fix(2.5D): keep device overlays stable while zooming

Issue: #651
User-Visible: yes

docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+- Device and door-lock markers in the 2.5D plan no longer change their scene
+  positions while the plan is zoomed or panned. Nearby markers now move away
+  from a wall as one rigid group, so rows and the spacing between their
+  members stay the same as on the flat plan instead of fanning into a diagonal
+  or being rearranged at a different zoom
+  ([#651](https://github.com/Matysh/houseplan-card/issues/651)).
+
 ## v1.78.0-beta.3 — 2026-09-25
 
 - The 2.5D plan is now available to everyone: **General settings → Display →

docs/CHANGELOG.ru.md

@@ -8,6 +8,13 @@
 
 ## Не выпущено
 
+- Значки устройств и замков дверей на объёмном плане (2.5D) больше не меняют
+  положение в сцене при приближении, отдалении и перемещении плана. Близкие
+  значки теперь отодвигаются от стены одной жёсткой группой: ряды и интервалы
+  внутри них остаются такими же, как на обычном плане, вместо превращения в
+  диагональ или новой раскладки на другом масштабе
+  ([#651](https://github.com/Matysh/houseplan-card/issues/651)).
+
 ## v1.78.0-beta.3 — 2026-09-25
 
 - Объёмный план (2.5D) теперь доступен всем: **Общие настройки → Отображение →

docs/ISOMETRIC.md

@@ -207,21 +207,31 @@ inverse hit mapping, invisible collision footprints and fit bounds share that
 one affine authority.
 
 Device markers, room labels/cards and opening-lock badges keep their canonical
-floor anchors but render on a low plane four visual units above the floor. Each
-first clears wall silhouettes. A second deterministic group pass separates the
-complete screen-space footprints of devices and lock badges from one another
-within one absolute 48 CSS-pixel budget, using a bounded spatial index and
-stable kind/id tie-break; it never writes the correction back to configuration.
-The live pass enumerates one-pixel lattice candidates only at critical edges
-and intersections of the forbidden screen-space roots it actually encounters;
-it does not scan the area of the displacement disk or depend on a coarse grid.
-Room, wall-silhouette and radius checks remain exact final filters, so a legal
-slit narrower than four CSS pixels is still found without weakening masonry or
-ownership safety. The two full isometric profiles therefore use the ordinary
-150/60/75 ms resize/pan/state noise allowances again (#585).
-Room labels do not enter that mutual pass and stay below interactive roots. If
-the owning room truly has no legal placement, the least-overlapping result is
-kept as an explicit degraded diagnostic without hiding or shrinking an item.
+floor anchors but render on a low plane four visual units above the floor.
+Devices and lock badges in the same room whose canonical reference-fit bounds
+(expanded by 12 CSS px) connect form one rigid cluster. Every member receives
+the same scene-space displacement, so pairwise vectors, rows and intervals are
+the affine projection of the Flat layout rather than a per-marker fan toward a
+room safe point. Room labels never enter a cluster and stay below interactive
+roots.
+
+The reference-fit view, not the current live view, converts CSS safety values
+into scene units. Wheel/button zoom, pinch and pan therefore transform an
+already resolved scene and cannot invalidate placement. Structural changes —
+stage/camera, walls, rooms, marker membership or canonical anchors — rebuild it
+deterministically; viewport movement and HA-only state do not. One common
+vector clears the exact wall silhouettes and already placed clusters within an
+absolute 48 CSS-pixel reference-fit budget, using stable size/required-shift/
+kind-id order and boundary candidates instead of scanning the displacement
+disk. The correction is runtime-only and is never written to configuration.
+
+If no completely legal common vector exists, the nearest deterministic result
+keeps the cluster rigid and prioritises room ownership, then wall clearance,
+then overlap with an earlier cluster. It never splits or shrinks a cluster;
+residual overlap is an explicit degraded diagnostic. This supersedes the old
+single-marker fallback while retaining the 48 px cap. The two full isometric
+profiles keep the ordinary 150/60/75 ms resize/pan/state noise allowances
+(#585, #651).
 Fit probes reserve the maximum correction but do not execute live collision
 search. There is no painted plate, long tether, ground dot or per-marker
 shadow. The original screen-facing HTML root remains the only hit, focus,

docs/STATUS.md

@@ -40,7 +40,7 @@ same commit as the change it describes.
 | Item | State |
 |---|---|
 | Current local cycle | **Beta v1.78.0-beta.3 candidate** — prepared from the exact integrated `dev` tree. It makes 2.5D a public opt-in setting (#649), compacts the phone header and stabilises the main toolbar (#616, #647), adds native Sections height resize (#648), tightens Home Assistant read-only access (#626), and includes the associated repository, release-review and mutation-gate maintenance (#628, #638, #650). `main` remains on stable v1.77.0. |
-| 2.5D View | #89 Stage 1 ships in v1.63.0-beta.1, #122 Stage 2 in v1.64.0, #160 Stage 3 in v1.73.0-beta.1, #570/#583 Stage 4 on `dev`. #649 Stage 6 makes it public: the installation-wide General settings switch `settings.volumetric_view` (Display, third item) replaces the alpha entry, the header toggle and the phone-menu item; raised tiles with one floor-shadow layer, a soft sun wash instead of Flat wedges, user wall colours independent of the theme, furniture at the Flat line width. Flat remains default and byte-for-byte unchanged; editors and `houseplan-space-card` stay Flat. Acceptance frames: `docs/design/649-25d-stage6/ACCEPTANCE.md`. |
+| 2.5D View | #89 Stage 1 ships in v1.63.0-beta.1, #122 Stage 2 in v1.64.0, #160 Stage 3 in v1.73.0-beta.1, #570/#583 Stage 4 on `dev`. #649 Stage 6 makes it public: the installation-wide General settings switch `settings.volumetric_view` (Display, third item) replaces the alpha entry, the header toggle and the phone-menu item; raised tiles with one floor-shadow layer, a soft sun wash instead of Flat wedges, user wall colours independent of the theme, furniture at the Flat line width. #651 keeps device/lock clusters rigid and independent of live zoom/pan. Flat remains default and byte-for-byte unchanged; editors and `houseplan-space-card` stay Flat. Acceptance frames: `docs/design/649-25d-stage6/ACCEPTANCE.md`. |
 | Workflow | Superseded 2026-08-12: the pre-1.62 rule of "local edits without tests or commits" is **dead** — since release 1.62 every product change follows `PROCESS.md` (issue in `S5-ready`+, branch `issue/<NN>-slug`, trailers on every commit, review pipeline; `AGENTS.md` is the summary). Release mechanics below remain current. A requested pre-release gets a production build plus the smallest targeted unit/smoke set covering the changed surfaces, one tested `dev` commit/tag and a GitHub Release with `prerelease=true`; `main` stays untouched. The complete local frontend/backend/smoke gate runs only before a stable release, after which `main` is fast-forwarded to the exact tested `dev` SHA and the stable release is produced by `release.yml` (`workflow_dispatch` on `main` with the tag) — the only publisher of installable assets since #540: gates on the exact SHA (Validate, Full Performance, E2E on the candidate commit), one build, `houseplan.zip` archived from the committed tree, `SHA256SUMS`, draft → publish → read-back verification; a release published by hand in the GitHub form is turned back into a draft and walked through the same path, and a re-dispatch on a public tag is a repair that adds only missing assets. Release bodies are short and bilingual (Russian first); every bullet links its GitHub issue (#NN) so the #328 rules stay machine-checkable. A STABLE body aggregates the changelog since the PREVIOUS STABLE release (never since the last beta): features/fixes described across the line's beta changelogs must appear, while bugs that were introduced and fixed strictly inside the beta line (never shipped in any stable) are excluded — draft with `npm run release:notes -- <tag>`, curate by hand, then `npm run release:notes -- <tag> --verify` must pass. `Мелкие исправления и улучшения` / `Small fixes and improvements` is allowed only when the range really contains user-visible work not itemised in the body; a single-issue hotfix ships without it (the verifier enforces this). Every body ends with separate links to the Russian and English changelogs. Open or partially delivered issues are never presented as shipped. Telegram announcements are sent only for stable releases; beta and RC publication is silent. `docs/RELEASE-NOTES.md` is the current canonical body instance; `npm run release:prerelease -- <tag> --issues=… --yes` is the primary local publication path and the manual `Publish prerelease` workflow is its GitHub-only equivalent once present on `main`. Nothing is copied to the home instance by hand |
 | GitHub | https://github.com/Matysh/houseplan-card — [Issues](https://github.com/Matysh/houseplan-card/issues) are the canonical task records; their labels carry priority and workflow status (`PROCESS.md` §9). GitHub Projects is no longer used. `main` carries stable releases; pre-release tags may point directly at `dev`. Work lands on `dev` and is merged into `main` for a stable release, so `dev` is normally equal to or ahead of `main`, never behind. Push via SSH key `ha_jb` (remote git@github.com:…); API releases via the fine-grained PAT in `~/.git-credentials` (Contents R/W, issued 2026-07-23) |
 | CI | #541 replaces three incompatible meanings of “green” with one machine-verifiable Validate proof: candidate SHA/tree, run ID/attempt, requested checks, actually executed jobs and independently checked content-addressed reuse. Review, merge and release share the same closed state machine; a light green dispatch cannot hide a full red run, and a dispatch without six executed mutant jobs cannot authorize review or merge. #573 makes the proof composite — product-tree identity, accepted golden overlay (tree, index hash, either a `Baseline-Reviewed` run or a `Baseline-Reviewed-Local` attestation) and the content key of every reusable job — and release consumers on the candidate checkout recompute and compare all of it; the accepted overlay is an input of `golden` only, so a baseline-only commit after a golden-red candidate reuses smoke, performance smoke, parity and backend, skips caught witnesses and re-runs golden alone. #641 permits a complete attested WSL/ext4 capture from a clean published SHA to replace the first expected-red artifact-transport run, while a full independent GitHub Validate on the accepted exact SHA remains mandatory. Prerelease publication requires a green full exact-SHA proof covering frontend/backend, smoke (including the #73 rAF frame sampler), golden, HACS/Hassfest and the short absolute-ceiling performance smoke. Obsolete same-ref Validate runs are cancelled. Full seven-sample base/candidate performance remains in `performance.yml` (`main` push, weekly, manual); stable release assets fail closed unless Validate and Full Performance are green for the exact tagged SHA and the stable-only CDP compositor screencast finds no empty/black presented frame. |