From 2fe20a095b1c565134cb9983eb0ed27c9b3d351c Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 26 Sep 2026 18:19:52 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=81=D0=B2=D0=B5=D1=81=D1=82=D0=B8=20?= =?UTF-8?q?=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B0=D1=86?= =?UTF-8?q?=D0=B8=D1=8E=20=D1=81=20=D0=BA=D0=BE=D0=B4=D0=BE=D0=BC=20=D0=B8?= =?UTF-8?q?=20=D0=BA=D0=B0=D0=BD=D0=BE=D0=BD=D0=BE=D0=BC=20(#667)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Пятнадцать расхождений из #667. Бюджет initial View назван одним источником (scripts/bundle-budget.mjs). CONTRIBUTING описывает бандл после #657, HA-харнесс после #630 и релиз через release-contract и release.yml. Мутанты указывают на реестр scripts/mutation-registry.mjs. STATUS и ROADMAP больше не держат PR в HACS «в очереди» и инструкции прежней песочницы. SCOPE называет три редактора, форматы плана и радар #485. README выводят первую комнату через «Стены». Русское руководство сверено с v1.78.0-beta.5, таблица «Источник плана» склеена. UX-MODES и STYLING-HOOKS следуют коду: проёмы в просмотре инертны, space-card рисует проёмы и декор-изображения. Починены якорь в DEVICE-PRESENTATION и пол зума 1/3. ADR 089/122/160 и ISOMETRIC помечают активацию через hp_alpha исторической. Из раскладки ARCHITECTURE убран несуществующий src/data. legacy/README не называет docs/superpowers действующими спецификациями. Паритет английского руководства (п. 8) выделен в #668. Issue: #667 User-Visible: no Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018qZfe7YS4rqEMKoVeS3GKd --- AGENTS.md | 2 +- CONTRIBUTING.md | 23 ++++++---- README.md | 4 +- README.ru.md | 4 +- docs/ARCHITECTURE.md | 5 +- docs/DEVELOPMENT.md | 2 +- docs/DEVICE-PRESENTATION.md | 2 +- docs/ISOMETRIC.md | 6 +++ docs/README.ru.md | 6 +-- docs/ROADMAP.md | 4 +- docs/SCOPE.md | 15 +++--- docs/STATUS.md | 48 +++++++++----------- docs/STYLING-HOOKS.md | 8 ++-- docs/TESTING-DEMO.md | 2 +- docs/USER-GUIDE.ru.md | 8 ++-- docs/UX-MODES.md | 7 +-- docs/adr/089-isometric-stage1-renderer.md | 3 ++ docs/adr/122-isometric-stage2-composition.md | 3 ++ docs/adr/160-isometric-stage3-overlays.md | 3 ++ docs/testing-notes/core-checklist.md | 2 +- docs/testing-notes/geometry.md | 6 +-- docs/testing-notes/live-and-integrations.md | 4 +- legacy/README.md | 2 +- 23 files changed, 94 insertions(+), 75 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1fceffd9..930f7a66 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -406,7 +406,7 @@ committed copy (#657): npm run bundle:sync # build + dist → demo/srv/assets (#255) npm run bundle:clean # before an ordinary commit: dist back to the committed copy (#657) npm run bundle:release # candidate only: build + dist → custom_components + demo/srv/assets -npm run bundle:budget # initial View graph <= 256000 B gzip (#337) +npm run bundle:budget # initial View graph within INITIAL_VIEW_GZIP_BUDGET (scripts/bundle-budget.mjs, #337/#367) ``` CI (`bundle-policy --verify`) checks the fresh build's integrity on every push diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b46eb76..a6474e96 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -104,9 +104,12 @@ tree repeatedly. Do **not** replace it with `--depth=1`: a shallow clone is abou the same size but has no `merge-base`, so the process gate, `smoke-select` and every `origin/dev..HEAD` range stop working. -The HA-harness backend tests (`tests_backend/test_ha_*.py`) need Python ≥3.13 and -`pytest-homeassistant-custom-component home-assistant-frontend`; CI runs them on -every push — locally they are skipped when `homeassistant` is not importable. +The HA-harness backend tests (`tests_backend/test_ha_*.py`) need the +repository-pinned Python (`.python-version`) and +`pytest-homeassistant-custom-component home-assistant-frontend`; their canon is +Linux CI or WSL (`bash scripts/wsl-setup.sh --verify`). Without an importable +`homeassistant` they are not collected at all — not skipped — and pytest prints +`HA harness NOT collected: …` (#630). ## Ground rules @@ -114,8 +117,10 @@ every push — locally they are skipped when `homeassistant` is not importable. `docs/STATUS.md` for state changes; `docs/DEVELOPMENT.md` for new gotchas. - Every UI string goes through `src/i18n/.json`; follow the [Translations](#translations) flow for registry and backend parity. -- The built card must be committed in sync: `cp dist/houseplan-card.js - custom_components/houseplan/frontend/` (CI compares them byte-for-byte). +- The committed bundle changes only in a release candidate: `npm run + bundle:release` in a commit with a `Release:` trailer (#657). An ordinary task + restores it with `npm run bundle:clean` before committing — the `commit-msg` + hook refuses a bundle change otherwise. - Tap actions have a security model (locks/alarms never toggle from the plan) — see `resolveToggleIntent` in `src/device-toggle.ts`; don't weaken it. - Every commit follows the issue and trailer contract in `PROCESS.md`. @@ -125,6 +130,8 @@ every push — locally they are skipped when `homeassistant` is not importable. ## Architecture Start with `docs/ARCHITECTURE.md` (data model, WS API, coordinate system) and -`docs/STATUS.md` (current state). Release: bump the version in `package.json`, -`manifest.json`, `const.py`, `CARD_VERSION`, tag `vX.Y.Z`, publish a GitHub release — -the workflow attaches the card bundle. +`docs/STATUS.md` (current state). Release mechanics live in `docs/STATUS.md` › Workflow: the version sources are +the ones checked by `scripts/release-contract.mjs`, prereleases go through +`npm run release:prerelease -- --issues=… --yes` (or the manual +`Publish prerelease` workflow), and stable installable assets are published only +by `release.yml` (#540). diff --git a/README.md b/README.md index 787b2bea..45de9cda 100755 --- a/README.md +++ b/README.md @@ -61,8 +61,8 @@ sync across screens. 1. Install the integration and open **House Plan** in the Home Assistant sidebar. 2. Create the first **space**: upload SVG/PNG/JPG/WebP, reuse an uploaded image, or choose no image and draw the plan by hand. -3. In Plan, select **Room outline**, place vertices, and click the first point to - close the outline. +3. In Plan, select **Walls** and draw one continuous chain around the room: when + it closes an area, the room dialog opens. 4. Name the room and bind it to a Home Assistant area. Use “No area” for a room that has no devices. 5. Open Device: devices from the bound area are already placed; drag their diff --git a/README.ru.md b/README.ru.md index 282c91f4..cf93c30f 100644 --- a/README.ru.md +++ b/README.ru.md @@ -59,8 +59,8 @@ Assistant — и устройства появятся на плане авто 1. Установите интеграцию и откройте **House Plan** в боковом меню Home Assistant. 2. Создайте первое **пространство**: загрузите SVG/PNG/JPG/WebP либо выберите вариант без изображения, чтобы нарисовать план вручную. -3. В редакторе «План» выберите **Контур комнаты**, поставьте вершины и замкните - контур нажатием на первую точку. +3. В редакторе «План» выберите **Стены** и нарисуйте непрерывную цепочку по + периметру комнаты: когда она замкнёт область, откроется диалог комнаты. 4. Назовите комнату и свяжите её с зоной Home Assistant. Для помещения без устройств выберите «Без зоны». 5. Откройте «Устройства»: устройства связанной зоны уже размещены автоматически; diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4f7efa3a..fde57830 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -44,10 +44,7 @@ houseplan-card/ │ ├─ space-model-selection.ts # active-or-first and exact optional space selectors │ ├─ render/opening-tunnels.ts # immutable SVG projection of resolved tunnel geometry/fills │ ├─ editor.ts # GUI config editor (ha-form + selectors) -│ ├─ rules.ts # icon rules (iconFor), filtering, groups, fallback order -│ └─ data/ -│ ├─ house.ts # geometry: ROOMS (rooms→area), FLOOR_VB (viewBox), names -│ └─ backgrounds.ts # VECTOR plans (SVG base64) + FLOOR_BG_RECT (positioning) +│ └─ rules.ts # icon rules (iconFor), filtering, groups, fallback order ├─ dist/ # entry + manifest + content-hashed JS chunks ├─ demo/golden/ # deterministic HP-QA-01 matrix, capture/verify/accept ├─ demo/performance/ # large-house budgets and same-runner comparison diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 193249af..3a8b4bfa 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -341,7 +341,7 @@ commands and the explicit review workflow are documented in ```bash cd /tmp/hpc && npm ci # once npm run bundle:sync # build + entry/manifest/chunks → demo -npm run bundle:budget # initial View graph must stay <= 256000 B gzip +npm run bundle:budget # initial View graph within INITIAL_VIEW_GZIP_BUDGET (scripts/bundle-budget.mjs) npm run bundle:clean # before an ordinary commit (#657) npm run bundle:release # candidate only: also → custom_components/houseplan/frontend node scripts/bundle-tree.mjs dist custom_components/houseplan/frontend # candidate parity diff --git a/docs/DEVICE-PRESENTATION.md b/docs/DEVICE-PRESENTATION.md index 6dbaa289..ce9ec6ad 100644 --- a/docs/DEVICE-PRESENTATION.md +++ b/docs/DEVICE-PRESENTATION.md @@ -2,7 +2,7 @@ Этот документ — developer-facing канон для issue [#267](https://github.com/Matysh/houseplan-card/issues/267). Пользовательские -названия и обещания остаются в [USER-GUIDE.ru.md](USER-GUIDE.ru.md#12-отображение-устройств); +названия и обещания остаются в [USER-GUIDE.ru.md](USER-GUIDE.ru.md#12-визуальные-состояния-устройств); здесь зафиксировано, как уже разрешённые факты превращаются в одно «лицо» маркера. Любое изменение результата требует изменения строки, fixture и mutation evidence в одном pull request. diff --git a/docs/ISOMETRIC.md b/docs/ISOMETRIC.md index 33bd0e9f..e2c53cf3 100644 --- a/docs/ISOMETRIC.md +++ b/docs/ISOMETRIC.md @@ -119,6 +119,9 @@ the exact Linux CI SHA. ## Stage 2 composition (#122) +> Historical: written while 2.5D was a hidden `hp_alpha` experiment. Since #649 +> it is public; activation is described in [Activation](#activation). + Stage 2 evolves the same hidden `iso` experiment; it does not add a flag, setting or public activation path. The accepted implementation contract is `docs/specs/122-isometric-stage2.md` and the fixed composition decisions are in @@ -204,6 +207,9 @@ budget nor treats fallback as benchmark success. ## Stage 4 visual handoff (#570) +> Historical: written while 2.5D was a hidden `hp_alpha` experiment. Since #649 +> it is public; activation is described in [Activation](#activation). + Stage 4 refines the same hidden `iso` presentation behind `hp_alpha`; it adds no public switch, configuration field or experiment id. Stage 3 history remains in `docs/specs/160-isometric-stage3.md` and diff --git a/docs/README.ru.md b/docs/README.ru.md index 76051a81..9500c246 100644 --- a/docs/README.ru.md +++ b/docs/README.ru.md @@ -2,16 +2,14 @@ Этот каталог — точка входа в русскоязычную документацию House Plan. -> **Сверено с версией v1.60.0.** Продукт с тех пор ушёл вперёд (линия 1.64); -> при расхождении этого каталога с `docs/USER-GUIDE.ru.md` и changelog верить им. -> Пересверка каталога — отдельная документационная задача. +> При расхождении этого каталога с `docs/USER-GUIDE.ru.md` и changelog верить им. | Документ | Для кого | Что внутри | |---|---|---| | [Полное руководство пользователя](USER-GUIDE.ru.md) | Пользователи и администраторы Home Assistant | Установка, первая настройка, пространства, комнаты, стены, проёмы, устройства, визуальные состояния, заливки, подложка, солнце, пылесосы, киоск, обслуживание и диагностика | | [Радары присутствия](RADAR.md) | Пользователи, администраторы и интеграторы | Поддерживаемые профили, привязка источников, установка и калибровка, статусы данных, приватность и диагностика | | [Редактор подложки и декора](DECOR-EDITOR.md) | Пользователи, тестировщики и разработчики | Инструменты, единое выделение и трансформации, физические размеры, магнит, Undo/Redo, поведение картинки-подложки и совместимость старых полей | -| [GitHub Issues](https://github.com/Matysh/houseplan-card/issues) и [Project v2](https://github.com/users/Matysh/projects/1) | Владелец, разработчики и контрибьюторы | Единственный актуальный backlog: задачи, приоритеты, решения и статусы выполнения | +| [GitHub Issues](https://github.com/Matysh/houseplan-card/issues) | Владелец, разработчики и контрибьюторы | Единственный актуальный backlog: задачи, приоритеты и решения; статус — в метках issue (`PROCESS.md` §9) | Старые тематические документы в этом каталоге остаются инженерными спецификациями и историей решений. При расхождении пользовательского описания с интерфейсом текущей версии приоритет имеет новое руководство, а при расхождении с фактическим поведением — код текущей версии. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 6232830e..845a565e 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -77,8 +77,8 @@ Track progress in `custom_components/houseplan/quality_scale.yaml` (done/exempt ## Phase 10 — Community & distribution -- [ ] hacs/default PR **#9004** through moderation (#8995 was bot-closed for a - non-template body; #9004 is queued with the label since 2026-07-22). +- [x] hacs/default PR **#9004** merged on 2026-08-25: House Plan is in the HACS + default catalog (#8995 was bot-closed earlier for a non-template body). - [ ] 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. diff --git a/docs/SCOPE.md b/docs/SCOPE.md index 48a648c7..0e72e08e 100755 --- a/docs/SCOPE.md +++ b/docs/SCOPE.md @@ -48,9 +48,9 @@ deliberate degradation is allowed under `TOUCH-SUPPORT.md`. | J1 | "Show the whole home and what's happening right now" — live spatial overview: device states, room fills (light/temp/LQI), values, multi-floor tabs | **Closed** | | J2 | "Something is wrong — show me *where*" — leak/smoke/gas pulse, open doors/windows, unlocked locks, red dot on devices HA added silently | **Closed** | | J3 | "Let me act on the obvious right from the plan" — tap-to-toggle for safe domains, info cards, guarded lock action | **Closed** | -| J4 | "From zero to a working plan in one evening, no Inkscape/YAML" — image/PDF/draw, floors-import wizard, room polygons bound to areas, filtered auto-placement, editable icon rules | **Closed**; onboarding polish is *partial* (no registry-driven room suggestions) | +| J4 | "From zero to a working plan in one evening, no Inkscape/YAML" — image (SVG/PNG/JPG/WebP) or draw, floors-import wizard, room polygons bound to areas, filtered auto-placement, editable icon rules | **Closed**; onboarding polish is *partial* (no registry-driven room suggestions) | | J5 | "Room climate at a glance" — per-room temperature/humidity, comfort-range fills, room-card metrics | **Closed** | -| J6 | "Keep the plan true as the home evolves" — new-device flag, two editors, drag/resize, merge/split, multi-client live sync, optimistic locking | **Closed** | +| J6 | "Keep the plan true as the home evolves" — new-device flag, three editors (plan, devices, background), drag/resize, merge/split, multi-client live sync, optimistic locking | **Closed** | | J7 | "Is my Zigbee mesh healthy *here*?" — LQI badges, per-room average/fill and opt-in direct-neighbour links for one hovered device | **Closed** (spatial diagnostics; no persistent full-mesh graph) | ## Partially covered — improvement backlog stays inside these @@ -62,11 +62,14 @@ deliberate degradation is allowed under `TOUCH-SUPPORT.md`. formatting only. - **Accessibility**: `prefers-reduced-motion` only; no keyboard navigation in editors, no ARIA labelling of the plan. -- **Docs/screenshots**: README predates the two-editor redesign. +- **Docs**: the English user guide covers less than the Russian one + ([#668](https://github.com/Matysh/houseplan-card/issues/668)). ## Known gaps that fit the mission (build only on owner's request) -- Person/presence shown in rooms (classic floorplan ask; pure J1). +- Person/presence shown in rooms (classic floorplan ask; pure J1). Started on the + owner's request with mmWave radar presence, [#485](https://github.com/Matysh/houseplan-card/issues/485) + (`docs/RADAR.md`); anything beyond it stays here. ### The lock invariant, stated precisely (review CR-1) No lock or alarm panel is ever actuated **by a tap on the plan**: icons, lock @@ -158,8 +161,8 @@ the file — and if a future version wants to reclaim that space, it asks. > a plan image (or draw one), outline rooms and bind them to HA areas — your > devices appear in place, automatically, with live states. Glance at the wall > tablet: what's on, what's open, what's too cold, what's leaking, what's new. -> Tap to act — safely: locks never toggle by accident. Two built-in editors -> (plan and devices) mean no Inkscape, no YAML, no external tools — ever. +> Tap to act — safely: locks never toggle by accident. Three built-in editors +> (plan, devices and background) mean no Inkscape, no YAML, no external tools — ever. **Tasks it closes:** whole-home live overview · spatial alerts (leak/smoke/open/ unlocked/new device) · safe quick actions · per-room climate · Zigbee mesh diff --git a/docs/STATUS.md b/docs/STATUS.md index ec064f8b..c83b6ffe 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -63,10 +63,11 @@ same commit as the behaviour. ## 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). +- **Source of truth:** the git repo on GitHub — work lands on `dev`, stable releases on + `main`. In a sandbox session clone it from GitHub. +- **Owner's folder:** `houseplan-card-src/houseplan-card` is the author's tree and + `houseplan-card-src/hp-dev` the owner's worktree on `dev` (`AGENTS.md` › Working + trees). The former file mirror `houseplan/houseplan-card/` is no longer maintained. - **Production config:** server-side on the HA instance, `.storage/houseplan.config` + `.storage/houseplan.layout` (backups `.bak-v1100` exist on the box). @@ -78,39 +79,34 @@ same commit as the behaviour. The former local product plan is preserved only as a snapshot at [`legacy/docs/PRODUCT-IMPROVEMENT-PLAN.ru.md`](../legacy/docs/PRODUCT-IMPROVEMENT-PLAN.ru.md) and must not be updated or used as a backlog. -1. **hacs/default PR #9004** — accepted by the bot into the review queue ('New default - repository' label). Minor issues ⇒ the bot drafts the PR (fix and re-ready). -2. GitHub auth: fine-grained PAT (Contents R/W, issued 2026-07-23) in the sandbox - `~/.git-credentials`; pushes go over SSH with the `ha_jb` key. The old classic PAT - expired and is gone. -3. Privacy: legacy real-house plan sources (`assets/`) and screenshots were +1. Privacy: legacy real-house plan sources (`assets/`) and screenshots were removed from the current tree. Public documentation images are generated from synthetic fixtures by the `Docs screenshots` workflow, accepted with `npm run docs:accept -- --reviewed`, and indexed in `docs/images/screenshots.json`. Old images persist in git history and release archives; history rewrite is deliberately not done because it would break release tags and HACS installs. -4. 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. -5. Roadmap: phases 7–10 are DONE (v1.12.0 quality scale, v1.13.0 universality, +2. Roadmap: phases 7–10 are DONE (v1.12.0 quality scale, v1.13.0 universality, v1.13.1 distribution). Next candidates: measure backend coverage (>95% goal); mypy strict. -6. The public-doc screenshot harness is versioned in `demo/docs/capture.mjs` and +3. The public-doc screenshot harness is versioned in `demo/docs/capture.mjs` and reuses the production component plus deterministic golden fixtures. ## 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 /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 — it lives in the user folder at - `houseplan/.secrets/ha_jb` (outside git) and often survives in the sandbox home - `~/.ssh/ha_jb`; copy with chmod 600. Only ask the user if both are gone. -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