docs: STATUS.md (session-context snapshot + documentation policy), new ROADMAP (quality-scale phases 7-10, universality), PRODUCT.md (market assessment, competitors verified 2026-07-06), DEVELOPMENT.md environment refresh

docs/DEVELOPMENT.md

@@ -2,10 +2,22 @@
 
 ## Environment (cowork sessions)
 
-- The source of truth for the code is the **git repository** (lives in `/tmp/hpc` during a session,
+- The source of truth is **GitHub `main`** (https://github.com/Matysh/houseplan-card).
-  restored from `houseplan-card.git.bundle`: `git clone houseplan-card.git.bundle hpc`).
+  In a sandbox session restore from it or from `houseplan-card.git.bundle`
-- The user's folder `houseplan/houseplan-card/` is a mirror of the repo (rsync after every commit)
+  (`git clone houseplan-card.git.bundle hpcN` into a **fresh** /tmp directory).
-  + an up-to-date `houseplan-card.git.bundle`.
+- The user's folder `houseplan/houseplan-card/` is a file mirror (synced after every commit)
+  + an up-to-date `houseplan-card.git.bundle`. The mount cannot delete files — stale
+  artifacts linger there; git is authoritative.
+- `/tmp` persists between sessions, **but files created in previous sessions belong to
+  `nobody` and are unreadable** (this hit `/tmp/hpc`, `/tmp/ha_jb`, `/tmp/shots/srv`).
+  Always clone into a new directory and re-run `npm ci`; ask the user to re-upload `ha_jb`.
+- Headless Chromium for smoke tests: `PLAYWRIGHT_BROWSERS_PATH=/tmp/pw npx playwright
+  install chromium-headless-shell`, then run with `LD_LIBRARY_PATH` pointing to the
+  extracted lib dirs (`libs/lib/x86_64-linux-gnu:libs/usr/lib/x86_64-linux-gnu:.../nss`).
+- Restart HA over SSH with `nohup ha core restart >/dev/null 2>&1 </dev/null &` —
+  a plain `ha core restart` holds the SSH session until the sandbox call times out.
+- GitHub pushes: classic PAT (repo+workflow scopes), created via the user's Chrome;
+  stored in `~/.git-credentials` for the session.
 
 ### ⚠️ File-sync pitfalls (critical)
 1. The network mount sometimes serves files **truncated/scrambled** — edits via the Edit tool

docs/PRODUCT.md

@@ -0,0 +1,74 @@
+# Product assessment & market position
+
+*Written 2026-07-05. Sources: GitHub API star counts and HA docs verified 2026-07-06;
+see links inline. Update this file when the landscape shifts.*
+
+## What the product is
+
+An interactive floor plan for Home Assistant delivered as one HACS package:
+a storage **integration** (server-side config, WS API, file uploads, auth) + a
+**Lovelace card** (rendering, room markup editor, drag layout, zoom, live states,
+temperature, Zigbee LQI, device metadata with PDF manuals, virtual markers,
+en/ru localization). GUI-first: no YAML, no hand-made SVG.
+
+## Competitive landscape (stars verified 2026-07-06)
+
+| Competitor | Stars | Approach | Weakness we exploit |
+|---|---|---|---|
+| [ha-floorplan](https://github.com/ExperienceLovelace/ha-floorplan) (incumbent) | 1 562 | hand-made SVG + YAML/CSS/JS rules | steep barrier: Inkscape + YAML; no GUI editor; config in card YAML |
+| native `picture-elements` | built-in | absolute % coordinates in YAML | trial-and-error positioning, no zones, no editor |
+| native Areas/Home dashboard (2025.4→2025.12) | built-in | auto card grid by area/floor | **not spatial** — leaves the visual-plan niche open |
+| [Dwains Dashboard](https://github.com/dwainscheeren/dwains-lovelace-dashboard) | 2 049 | auto-generated menus | not a floor plan |
+| [Bubble Card](https://github.com/Clooos/Bubble-Card) | 4 391 | GUI card collection | not a floor plan; sets the GUI-quality bar |
+| [zigbee-floorplan-card](https://github.com/TheLarsinator/zigbee-floorplan-card) | 71 | LQI over a plan image | single-purpose; validates our LQI feature |
+| [kishorviswanathan/ha-floorplan](https://github.com/kishorviswanathan/ha-floorplan) (2026-01) | 155 | external web editor → YAML export | editor outside HA, still YAML at runtime |
+| [Padraigggs-ha-interactive-floorplan](https://github.com/Padraiggg/Padraigggs-ha-interactive-floorplan) (2026-03) | 41 | editor+viewer cards, "no YAML" | weeks old, card-only, no server-side integration |
+| [easy-floorplan](https://github.com/nicosandller/easy-floorplan) (2026-05) | 11 | draw walls/furniture in the card | drawing-centric, immature |
+
+**Demand evidence:** a dedicated [Floorplan forum category](https://community.home-assistant.io/c/third-party/floorplan/28);
+the "100% Floorplan UI" mega-thread (500k+ views); a visible 2025–2026 wave of new
+floorplan projects (three launched in the last six months alone). The pain is constant:
+*people want a floor plan without Inkscape and YAML.*
+
+## Honest assessment
+
+**Usefulness — high.** A floor plan is the most natural "at a glance" home UI, and the
+GUI-first workflow (upload image → outline rooms → devices appear → drag) removes the
+exact barrier that keeps most users on lists of entity cards.
+
+**Demand — real but niche-shaped.** Floorplan is a perennial top request, but the
+audience is enthusiasts with wall tablets. Realistic trajectory given the field:
+hundreds of stars in the first year *if* discoverability is solved (HACS default +
+demo GIF + forum post). Bubble Card (4.4k★) proves polished GUI cards can go
+quasi-mainstream; ha-floorplan's 1.5k★ with a hostile workflow shows the demand floor.
+
+**Unique position — currently unoccupied.** Nobody else combines: server-side config
+(integration + `.storage`, survives dashboard edits, shared across users/devices,
+optimistic locking, live multi-client sync) + in-card room polygon editor bound to HA
+areas + curated auto-placement + drag layout + LQI/temperature overlays + config flow +
+en/ru localization + CI/quality-scale discipline. The newcomers are card-only toys so
+far; the incumbent is powerful but YAML/SVG-locked. Our moat grows if we integrate
+deeper with the areas/floors registry (Phase 9) — that is the direction HA core itself
+is signalling with the native Areas dashboard.
+
+**Risks.**
+1. *HA core ships a native spatial plan.* The Areas dashboard is grid-based today, but
+   core moving spatial would commoditize us. Mitigation: registry integration, speed.
+2. *Discoverability.* 0 stars until the HACS queue (~2 months) clears. Mitigation:
+   demo assets + forum/Reddit showcase now, custom-repo installs meanwhile.
+3. *Single maintainer bus factor* — mitigated by docs/ discipline and tests.
+4. *Frontend API churn* (undocumented hass internals custom cards rely on).
+   Mitigation: minimal surface, CI against beta HA (add to Phase 8).
+
+## Recommended next moves (priority order)
+
+1. **Demo GIF + English forum/Reddit posts** — cheapest adoption lever, do before the
+   HACS queue clears so the storefront lands with social proof.
+2. **Phase 7 quality items** (runtime_data, unloading, storage migrations, single_config_entry)
+   — cheap now, expensive later; also a credibility marker for reviewers.
+3. **Registry-driven onboarding** (import floors/areas as spaces/rooms suggestions) —
+   the feature that makes first-run magical and that no competitor has.
+4. **Editable icon rules** — removes the last dacha DNA and answers the #1 predictable
+   user complaint ("wrong icon for my device").
+5. **Click actions (toggle from the plan)** — most requested behavior in every
+   floorplan thread; we currently only open info dialogs.

docs/ROADMAP.md

@@ -1,73 +1,82 @@
-# Roadmap: from a "dacha map" to a publishable universal integration
+# Roadmap: a universal, flexible floor-plan component
 
-Goal: publish to HACS (first as a custom repository, then a PR into default) a universal
+Goal: a **proper Home Assistant component** built to HA developer-docs patterns —
-"interactive house plan" integration: custom plans per space, manual room markup,
+not a hardcoded feature. Universal (any house, any language, any plan format),
-semi-automatic device placement, hiding/renaming/changing icons, virtual
+flexible (options instead of assumptions), and measured against the official
-devices. No hardcoding of a specific house in the code.
+**Integration Quality Scale** even though custom integrations are not formally graded
+(see `docs/PRODUCT.md` for the market rationale).
 
-## Principles (locked in)
+Phases 0–6 of the original plan (server-side config, room markup editor, device
-- We write a proper full component following HA dev docs patterns, not a hardcoded feature.
+management, virtual devices, publication) are **done** — see CHANGELOG v1.3.0–v1.11.2.
-- All data of a specific house is **instance configuration** (server-side Store),
+This roadmap replaces them.
-  not code/bundle. The current dacha data will become the first migrated instance.
-- Document everything immediately in docs/ (session context gets lost).
-- Storage versioning (Store minor_version + async_migrate) from day one.
 
-## Phase 0 — Publication hygiene (quick, no new features)
+## Phase 7 — Quality Scale: Bronze-complete (structural correctness)
-- [x] hacs.json, manifest with the required keys, custom_components/* structure
-- [x] CI: hacs/action + hassfest (workflow validate.yml) — added, verify on GitHub
-- [x] brand/icon.png
-- [ ] Public GitHub repository: description, topics, issues on; first Release v1.2.x
-- [ ] README EN (primary) + README.ru.md; screenshots/GIF (mandatory for the HACS storefront)
-- [ ] Replace codeowners/documentation/issue_tracker with real URLs after the repo is created
 
-## Phase 1 — Server-side config (decoupling from the dacha) ← ✅ DONE in v1.3.0 (except removing the bundle data — kept as a fallback until phase 2)
+Track progress in `custom_components/houseplan/quality_scale.yaml` (done/exempt + comment).
-New store `houseplan.config` (Store v1):
-```json
-{ "spaces": [ { "id": "f1", "title": "1st floor", "plan": {"media_id": "...", "type": "svg"},
-    "view_box": [x,y,w,h], "rooms": [{"id","name","area_id","x","y","w","h"}] } ],
-  "device_overrides": { "<device_id>": {"hidden":bool,"icon":str,"name":str} },
-  "virtual_devices": [ {"id","space","name","icon","x","y","note"?, "entity_id"?} ],
-  "settings": {"exclude_integrations": [...], "group_lights": bool, ...} }
-```
-- WS API v2: `houseplan/config/get|set`, `houseplan/plan/upload` (plan file → 
-  `<config>/houseplan/` via the process executor, served through a static path), layout as today.
-- The card: when a server config exists it uses it; the dacha bundle data becomes a
-  **fallback example** and is then removed (a migration script will push it into the Store).
-- Coordinate units: normalized (0..1 of the plan) for new configs — independence from the
-  source resolution; the dacha migration will convert 1489×1053 → normalized.
 
-## Phase 2 — Markup editor in the card ← ✅ CORE DONE in v1.4.0 (remaining: plan upload from the UI, view_box editing, editing existing rooms)
+- [ ] `runtime-data`: move `hass.data[DOMAIN]` (stores, entry, write lock) to typed
-- A "Setup" mode (separate from drag layout): drawing/resizing room rectangles
+  `entry.runtime_data` (`type HouseplanConfigEntry = ConfigEntry[HouseplanData]`).
-  on top of the plan, binding to an area (ha-area-picker selector), viewBox (frame) editing.
+  Keep WS command registration in `async_setup` (commands must survive entry reloads).
-- Later: polygonal rooms (SVG path), plan rotations.
+- [ ] `config-entry-unloading` (Silver, do it now): real `async_unload_entry` — unregister
-- Plan upload from the UI (file upload → WS) + picking existing media.
+  update listeners via `entry.async_on_unload`; document what stays (static paths cannot
+  be unregistered — exempt comment).
+- [ ] `test-before-setup`: verify storage is loadable/writable in `async_setup_entry`,
+  raise `ConfigEntryNotReady` on failure.
+- [ ] `unique-config-entry`: replace the manual `_async_current_entries()` check with
+  `single_config_entry: true` in manifest.
+- [ ] `config-flow-test-coverage` + backend tests for websocket_api (pytest-homeassistant-custom-component:
+  conflict/rev, admin_only enforcement, layout point ops, upload limits).
+- [ ] Storage versioning: `Store(minor_version=...)` + `_async_migrate_func` skeleton **now**,
+  before the config schema evolves further (Bronze-adjacent, cheap while schema is stable).
+- [ ] `quality_scale.yaml` with honest exempt list (no entities ⇒ entity rules N/A, no polling, no deps).
 
-## Phase 3 — Device management ← ✅ DONE in v1.6.x (hiding, icon, name, model, link, description, PDF, rebinding, "+", virtual)
+## Phase 8 — Quality Scale: Silver + selected Gold
-- A device panel in setup mode: a list of unplaced devices (with filters), drag from the panel
-  onto the plan; auto-layout "grid over the room" by button.
-- Per-device overrides: hide, custom icon (ha-icon-picker), custom name. Stored in config.
-- Configurable curation: integration/domain exclusions in the options flow instead of hardcode.
 
-## Phase 4 — Virtual devices ← ✅ basics in v1.6.x (CRUD of virtual markers in the shared dialog; further note/icon polish as needed)
+- [ ] `test-coverage` ≥95% backend; frontend: extract remaining pure logic (view math,
-- CRUD of virtual markers (name, icon, coordinates, note; optionally a link to an
+  marker resolution) into `logic.ts`/`devices.ts` and cover with node:test.
-  entity/URL): septic tank, valve, a meter without a sensor, etc. Rendered like normal icons,
+- [ ] `diagnostics.py`: config + layout dump with `async_redact_data` (redact names/links/PDF paths).
-  click → a card with the note or more-info of the bound entity.
+- [ ] `reconfiguration-flow` + richer **options flow**: admin_only, curation defaults
+  (exclude domains — UI editable, replacing the hardcoded EXCLUDED_DOMAINS fallback),
+  LQI thresholds, group_lights default.
+- [ ] `repair-issues`: broken plan file references, orphaned layout entries, storage
+  migration failures → Repairs UI instead of silent logs.
+- [ ] `system_health.py`: config rev, spaces/markers count, storage sizes.
+- [ ] `exception-translations` + `icon-translations` where applicable.
+- [ ] Frontend resource registration: adopt the community-consensus embedded-card pattern
+  end-to-end (we already do StaticPathConfig + storage-mode resource + `?v=` busting;
+  add resource cleanup on removal and document YAML-mode fallback).
 
-## Phase 5 — UX/feature polish
+## Phase 9 — Universality & flexibility (product depth)
-- Configurable click actions: toggle for lights/outlets, long-press → more-info.
-- Live-indication tuning (theme-aware colors, badges), light theme.
-- Tooltips on touch devices (long-press), accessibility (keyboard, aria).
-- LQI option: "bad signal" threshold, hiding the labels on non-zigbee instances.
 
-## Phase 6 — Quality and publication
+- [ ] **Areas/floors registry integration**: import HA floors as spaces, suggest area
-- Tests: pytest (config_flow, websocket_api, Store migrations) + hassfest/hacs action in CI;
+  bindings from the registry, sync names (HA is moving this way — native Areas/Home
-  frontend: vitest for rules/geometry utilities.
+  dashboard; riding the registry is our moat).
-- Typing: strict TS interfaces for hass (custom-card-helpers or our own), mypy for python.
+- [ ] **Curation without hardcode**: icon rules (`iconFor`) become data — user-editable
-- Translations for integration+card: en + ru (translations/, card string localization).
+  mapping (regex/domain/device_class → mdi icon) stored in config, shipping EN+RU
-- Quality scale bronze → silver checklist; PR into hacs/default; optionally a PR into
+  defaults; drop dacha-specific patterns from code.
-  home-assistant/brands (the brand/ in the repo suffices for now).
+- [ ] **Click actions** per device/domain: toggle / more-info / navigate / custom service
+  call (configurable, like standard card `tap_action`).
+- [ ] **Theming**: respect light themes (currently dark-leaning), use HA theme variables
+  everywhere, optional per-space background color.
+- [ ] Multi-instance question: keep single-instance (one house) but support **multiple
+  cards** with different default spaces (already works) — document as a decision.
+- [ ] Plan formats: keep SVG/PNG/JPG/WebP; add max dimensions guidance; optional
+  auto-downscale on upload.
+- [ ] More locales: extract i18n dictionaries to JSON so contributors can add languages
+  without touching TS.
 
-## Open questions
+## Phase 10 — Community & distribution
-- Publication name: "House Plan Card"? the `houseplan` domain is not taken in HACS default — verify.
+
-- MIT license (package.json is already MIT) — add a LICENSE file.
+- [ ] hacs/default PR #8995 through moderation (expect drafting for fixes).
-- Plan formats: SVG preferred (vector, size), PNG support is mandatory.
+- [ ] Demo GIF/video for README (the single biggest driver of adoption for dashboard cards).
+- [ ] Forum post in the Floorplan category + Reddit r/homeassistant showcase once
+  the demo assets exist.
+- [ ] GitHub: issue templates, discussions on, CONTRIBUTING.md (build/test in 5 minutes).
+- [ ] Semantic versioning discipline; keep release notes user-facing (they show in HACS).
+
+## Explicit non-goals (for now)
+
+- 3D plans (.glb) — separate market (3Dash), heavy dependencies.
+- Editing the plan image itself (walls/furniture drawing à la easy-floorplan) — we
+  consume existing plan images; the markup editor stays about *rooms/zones*, not drawing.
+- Cloud anything. Config stays in `.storage`, local-first.

docs/STATUS.md

@@ -0,0 +1,66 @@
+# Project status & session context
+
+> **Purpose of this file.** Cowork/AI sessions lose context (overflow, new session).
+> This file is the **first thing to read** when resuming work. It captures the current
+> state, where everything lives, and how to continue safely.
+>
+> **Documentation policy (mandatory):** every change is documented *in the same
+> commit* — CHANGELOG entry for anything user-visible, STATUS.md for state changes
+> (versions, publication, infrastructure), DEVELOPMENT.md for new gotchas,
+> ARCHITECTURE.md for design changes, ROADMAP.md when plans move.
+
+## Snapshot (2026-07-05)
+
+| Item | State |
+|---|---|
+| Version | **v1.11.2** everywhere (manifest, const.py, package.json, CARD_VERSION) |
+| GitHub | https://github.com/Matysh/houseplan-card — branch `main`, releases v1.9.3…v1.11.2 |
+| CI | `.github/workflows/validate.yml` (hacs + hassfest + frontend + backend) — **fully green** since v1.11.1; `release.yml` auto-attaches the card bundle (needs `permissions: contents: write`, fixed) |
+| HACS | Works as custom repository (id 1290210112 on the home instance). **Inclusion PR: https://github.com/hacs/default/pull/8995** (queue ≈2 months as of 2026-07) |
+| Brands | Ships **inside the integration**: `custom_components/houseplan/brand/{icon,icon@2x,logo,logo@2x}.png` (HA ≥2026.3 local-brands mechanism). home-assistant/brands PR #10700 was auto-closed — that repo no longer accepts custom integrations |
+| Home instance | ha.jbstudio.pro (SSH port 323, key `ha_jb`), deployed v1.11.2, installed *via HACS* (custom repo) — updates flow through HACS now |
+| Localization | UI en/ru (`src/i18n.ts`), auto by `hass.locale` + `language` card option; codebase and docs are English-first (`README.ru.md` is the Russian copy) |
+| Tests | 15 frontend (node:test on logic/rules) + 10 backend (pytest on validation.py) |
+
+## Recent milestones (details in CHANGELOG.md)
+
+- **v1.10.0** — audit & refactor: asyncio.Lock around all store writes (race fix, atomic
+  `expected_rev`), point `layout/update` instead of full `layout/set` (anti last-writer-wins),
+  new `layout/delete`, `safeUrl()` XSS guard, `fetchWithAuth`, KEY_HASS, streaming upload cap,
+  card split into modules (`styles.ts` / `types.ts` / `devices.ts`), dynamic spaces in the GUI
+  editor, dead code removed.
+- **v1.11.0** — full English translation + en/ru UI localization.
+- **v1.11.1** — brand images inside the integration; CI fully green for the first time.
+- **v1.11.2** — Description textarea fix in the device dialog.
+
+## Where things live
+
+- **Source of truth:** the git repo (GitHub `main`). In a sandbox session: clone from GitHub or
+  from `houseplan-card.git.bundle` (kept fresh in the user folder root *and* in `houseplan-card/`).
+- **User folder** `houseplan/houseplan-card/` — a file mirror of the repo (synced after every
+  commit; the mount cannot delete files, so a few stale artifacts linger — git is authoritative).
+- **Production config:** server-side on the HA instance, `.storage/houseplan.config` +
+  `.storage/houseplan.layout` (backups `.bak-v1100` exist on the box).
+
+## Open items / watchlist
+
+1. **hacs/default PR #8995** — waiting for moderation (bot may draft the PR for minor fixes —
+   fix and re-ready; wrongly filled template ⇒ silent close).
+2. GitHub PAT `houseplan-card-publish` (repo+workflow) expires ~2026-07-12; in sandbox
+   `~/.git-credentials`. Revoke after the HACS queue clears, or re-issue when needed.
+3. Stale files on the mount that cannot be deleted from the sandbox: `src/data/` leftovers,
+   `brand_preview.png`, old nested bundle copies — ignore, git is authoritative.
+4. Roadmap next: see ROADMAP.md (quality-scale conformance is the next big theme).
+
+## How to resume work in a fresh session (checklist)
+
+1. Read this file, then CHANGELOG.md (top entries), DEVELOPMENT.md (environment gotchas).
+2. Restore the repo: `git clone <user-folder>/houseplan-card.git.bundle hpcN` in `/tmp`
+   (files from *previous* sandbox sessions in `/tmp` belong to `nobody` and are unreadable —
+   always clone into a fresh directory; `npm ci` again).
+3. Deployment needs the `ha_jb` SSH key — ask the user to upload it (uploads are readable
+   only in the session they were uploaded in).
+4. Build only in `/tmp` (never on the mount), `npm run build` (starts with `tsc --noEmit`),
+   md5-verify after every deploy, restart HA via
+   `nohup ha core restart >/dev/null 2>&1 </dev/null &` (otherwise the SSH session hangs).
+5. GitHub pushes need a PAT (create via the user's Chrome: settings/tokens, repo+workflow scope).