Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(home): retire the floorplan order and record what its browser tier caught

nirholasfa0b4482e7d8
diff --git a/prompts/finish/304-home-07-floorplan-editor.md b/prompts/finish/304-home-07-floorplan-editor.md
deleted file mode 100644
index 9c707cdbe..000000000
--- a/prompts/finish/304-home-07-floorplan-editor.md
+++ /dev/null
@@ -1,158 +0,0 @@
-# 07. Floorplan authoring and layout persistence
-
-**How to run this:** paste this whole file into a fresh Claude Code chat opened in
-`/workspaces/three.ws`. Read [00-CONTEXT.md](_context/home-00-CONTEXT.md) first. Order
-[06](303-home-06-3d-home-scene.md) must have landed.
-
-## Binding operating clause
-
-Finish 100%. Never end with a question or an unexecuted plan. All CLAUDE.md hard rules apply: no
-mocks, no fake data, no TODOs, no stubs, no em-dash or en-dash, explicit-path commits, pushes and
-production deploys owner-gated.
-
-**Nothing in this file is a status claim to trust.** Step 0 re-measures.
-
----
-
-## Step 0: re-derive the current state
-
-```bash
-npm run dev &
-curl -s localhost:3000/api/home/<id> -H "cookie: <dev session>" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const g=JSON.parse(s).graph;console.log(g.floors.length,'floors',g.rooms.length,'rooms',g.unassigned.length,'unassigned')})"
-ls src/home/ # scene.js, scene-model.js from order 06
-```
-
-## Why this order exists
-
-Home Assistant knows which room a device is in. It does not know where that room is. Order 06
-ships a default arrangement so the scene is useful immediately; this order lets a person make it
-their actual house, which is the difference between a diagram and a place.
-
-It is also the fix for the most common real-world state: **a house where nothing is assigned to
-an area at all.** That user needs a five-minute path from a pile of entities to a floorplan.
-
-## The model
-
-A layout is per home, authored by a member, versioned, and **never** required. The scene must
-work with no layout, a partial layout, and a stale layout (a room that no longer exists).
-
-Schema, one migration:
-
-### `home_layouts`
-
-| Column | Type | Notes |
-|---|---|---|
-| `home_id` | `uuid primary key references home_connections(id) on delete cascade` | one live layout per home |
-| `version` | `integer not null default 1` | bumped on every save, for optimistic concurrency between household members |
-| `layout` | `jsonb not null` | the document below |
-| `updated_by` | `uuid not null references users(id)` | |
-| `updated_at` | `timestamptz not null default now()` | |
-
-The layout document, validated by a schema on write (reuse the repo's existing validation
-approach; do not accept arbitrary JSON into a rendering path):
-
-```json
-{
- "version": 1,
- "units": "m",
- "floors": [{ "id": "ground_floor", "level": 0 }],
- "rooms": [{
- "areaId": "kitchen",
- "floorId": "ground_floor",
- "x": 0, "y": 0, "w": 4.2, "h": 3.0, "rotation": 0,
- "entities": { "light.kitchen_lights": { "x": 2.1, "y": 1.5 } }
- }]
-}
-```
-
-Rules the validator enforces: bounded coordinates, a room count cap, a document byte cap, no
-unknown top-level keys, and `areaId` values that are strings only. A layout is user-authored
-JSON that drives a renderer, so treat it as untrusted input, not as trusted state.
-
-## The editor
-
-A 2D top-down plan, because nobody arranges a floorplan in perspective. The 3D scene updates
-live beside it or behind it.
-
-- Drag to move a room, handles to resize, snapping to a grid and to adjacent walls.
-- Rooms cannot overlap; the editor prevents it rather than validating it after the fact.
-- Undo and redo, keyboard shortcuts included.
-- Unassigned entities are a tray. Dragging one into a room **writes the area assignment back to
- Home Assistant** through `config/entity_registry/update`, so the work improves the user's own
- house and not just our picture of it. This is the single most valuable thing in this order.
-- Multi-floor: add, name, reorder, set level.
-- A "start from my house" path: if the house has areas, seed the plan from them; if it has none,
- the tray is the whole house and the flow is "make a room, drag things in".
-
-## Concurrency
-
-Two household members can edit. Optimistic concurrency on `version`: a save with a stale version
-returns 409 with the current document, and the editor offers a real merge choice (keep mine,
-take theirs, side by side), never a silent overwrite and never a lost edit.
-
-## Every state
-
-1. No layout: the seeded default, with an obvious way in.
-2. No areas at all: the tray-first flow.
-3. Editing: live, with the 3D following.
-4. Saving: optimistic, with a real failure path.
-5. Conflict: the 409 merge choice.
-6. Stale layout: a room in the layout no longer exists in Home Assistant. Show it as orphaned and
- offer to drop it; never crash, never silently discard the user's work.
-7. New room appeared in Home Assistant since the last save: surfaced in the tray, not hidden.
-8. Read-only: a household member without the layout role (order 12) sees the plan and cannot edit.
-9. Writing back to Home Assistant failed: the local layout still saves, and the failure is named.
-
-## Tasks
-
-| # | Task | Files |
-|---|---|---|
-| 1 | Migration and store functions. | `api/_lib/migrations/<ts>_home_layouts.sql`, `api/_lib/home/layout.js` |
-| 2 | The layout schema validator, with the caps. | `api/_lib/home/layout-schema.js`, `tests/home-layout-schema.test.js` |
-| 3 | `GET`/`PUT /api/home/:id/layout` with optimistic concurrency. | `api/home/[id]/layout.js` |
-| 4 | The area write-back to Home Assistant, gated as a normal (ungated) action and logged. | `api/_lib/home/tools.js` or a sibling |
-| 5 | The editor. | `src/home/floorplan.js`, styles |
-| 6 | Wiring the saved layout into order 06's scene builder. | `src/home/scene-model.js` |
-| 7 | e2e: author a plan, reload, and see it persist and render. | `tests/e2e/home-floorplan.spec.js` |
-
-## Definition of done
-
-- [ ] A real house arranged into a real floorplan, screenshotted in the editor and in the 3D scene.
-- [ ] Dragging an unassigned entity into a room really changed its area in Home Assistant. Prove it from the Home Assistant side, not from our UI.
-- [ ] A malformed layout document (over the cap, unknown keys, non-numeric coordinates) is rejected by the API with a designed error. Four transcripts.
-- [ ] Two browser sessions editing the same home produce the 409 merge choice, and no edit is lost. Record the sequence.
-- [ ] Deleting an area in Home Assistant puts the layout into state 6 without a crash and without discarding the rest.
-- [ ] A house with zero areas can reach a complete floorplan through the tray-first flow in under five minutes. Time it and report the number.
-- [ ] Undo and redo work, including across a drag and a resize.
-- [ ] Zero console errors or warnings from your code.
-- [ ] `npx playwright test tests/e2e/home-floorplan.spec.js` passes.
-- [ ] `npm run check:rules -- --paths <your files>` clean.
-
-## Never blocked
-
-| Blocker | Do this |
-|---|---|
-| Tempted to auto-generate a floorplan from device positions | There are no device positions. Home Assistant has no geometry. Seed from areas, let the human place. |
-| Tempted to make the layout required | Never. Order 06 works without one, and a required setup step before any value is how a feature dies. |
-| Overlap prevention is fiddly | Axis-aligned rectangles on a grid. Keep it rectangles in v1; free-form polygons are a later slice and not worth the complexity now. |
-| Writing back to Home Assistant feels risky | It is an area assignment, fully reversible in their own UI, and it is the thing that makes this worth doing. Log it, show it, and fail loudly rather than silently. |
-| A room in Home Assistant has no entities | Draw it. An empty room is still a room. |
-
-## Report format
-
-1. Editor and scene screenshots of a real arranged house.
-2. The Home Assistant-side proof of the area write-back.
-3. The four validator rejections.
-4. The concurrency sequence.
-5. The timed zero-areas walkthrough.
-6. Test output.
-7. Anything in this file you found to be wrong, and what you changed it to.
-
-## Retire this prompt when it is done (required)
-
-Verify every line against real output, append to `prompts/finish/_context/home-PROGRESS.md`, commit with
-explicit paths, and delete this file in that commit:
-
- git rm prompts/finish/304-home-07-floorplan-editor.md
-
-Never delete it on a partial.
diff --git a/prompts/finish/_context/home-PROGRESS.md b/prompts/finish/_context/home-PROGRESS.md
index c2986f889..d24059959 100644
--- a/prompts/finish/_context/home-PROGRESS.md
+++ b/prompts/finish/_context/home-PROGRESS.md
@@ -36,7 +36,7 @@ One section per finished order, newest at the bottom:
| 04 agent tools | done | 2026-09-09 |
| 05 connect flow | done | 2026-09-09 |
| 06 3D home scene | open | |
-| 07 floorplan editor | built, browser verification blocked, see entry | |
+| 07 floorplan editor | done | 2026-09-09 |
| 08 voice loop | done | 2026-09-09 |
| 09 Wyoming satellite | done | 2026-09-09 |
| 10 add-on relay | done, publish + deploy owner-gated | 2026-09-09 |
@@ -2388,3 +2388,90 @@ and the fixture getters, and `af50eb075` carries the `onConnect` await. The cont
verified at HEAD; only the attribution is wrong, and the shared-worktree rule against amending
means it stays that way. This entry and the order-file retirement are the only commit from this
session.
+
+
+---
+
+## 07 (browser tier closed). Floorplan authoring and layout persistence (2026-09-09)
+
+The 2026-09-03 entry above left exactly one thing open: the six browser journeys in
+`tests/e2e/home-floorplan.spec.js` were written and had never executed. They execute now.
+
+**Measured:** `HOME_LIVE=1 HOME_LIVE_NAME=layout07 HOME_E2E_API_PORT=8141 HOME_E2E_WEB_PORT=3071
+npm run test:home:e2e -- tests/e2e/home-floorplan.spec.js`: **6 passed**, twice in a row, against
+a real Home Assistant 2026.9.0 (4 areas, 1 floor, 92 entities) and the real API and database.
+`tests/e2e/home-scene.spec.js`: **6 passed**, so order 06 did not regress. The live unit tier,
+`WALLET_ENCRYPTION_KEY=$(openssl rand -hex 32) node --env-file=.env.local
+./node_modules/vitest/vitest.mjs run tests/home-layout.test.js`: **31 passed, 0 skipped**.
+Journey 9e reports its own number: **zero areas to a saved two-room floorplan with a device filed
+into one, 3 to 5 seconds**, against the order's five-minute bar. Its two screenshots land in
+`test-results/` (gitignored).
+
+**Running the lane at all.** `npm run test:home:e2e`, not a bare `npx playwright test --config
+playwright.home.config.js`: only the npm script loaded `.env.local`, so the documented re-run
+command died in global setup on `Missing required env var: DATABASE_URL`. The config now loads
+the file itself, so both spellings work; that fix is a peer's, landed mid-session.
+
+**Six defects, found because the journeys finally ran.** Four were real and two were the lane
+lying about itself:
+
+1. **The editor had no stylesheet.** `pages/home-scene.html` linked `/home-scene.css` and nothing
+ else, but every class the floorplan renders is `hm-plan-*`, which lives in `src/home/home.css`,
+ which only the `/smart-home` pages loaded. So the Plan view shipped with no rules at all:
+ absolutely positioned rooms fell back to static blocks and stacked down the page. The
+ before/after screenshots are unambiguous. Found here by reading the deliverable screenshot the
+ order asks for, and independently by a peer measuring touch targets in `home-a11y.spec.js`;
+ their fix is the one in the tree.
+2. **The conflict panel could not take theirs.** `HomeApiError`'s constructor destructured
+ `{ status, pending }` and silently dropped the `current` and `field` every caller passed. So
+ `err.current` was always undefined, the panel read "They saved version ?", and **"Take theirs"
+ returned early and did nothing**: the only way out of a 409 was to overwrite the other person,
+ which is the exact outcome the panel exists to prevent. This is the order's headline promise
+ ("never a silent overwrite and never a lost edit") and it was broken in the shipped code.
+3. **Switching to 3D threw every time.** `setView` calls `mount3d()` without awaiting it (it
+ lazy-imports Three.js), then reached for `state.renderer`, which it had just set to null and
+ which mount3d only reassigns after the import resolves: `Cannot read properties of null
+ (reading 'setModel')` on every switch to the 3D house with a house already loaded. mount3d
+ applies the model itself, so the 2D branch keeps that block and the 3D branch does not.
+4. **A room card could not hold its own contents.** A card is drawn to scale, so an ordinary 5.7 m
+ room is an 80px box, and a name plus a measurement plus a Remove button do not fit one. The
+ size line and the orphan tag now drop out by container query rather than wrapping mid-word.
+
+The two test defects mattered as much, because both made the suite report success it had not
+earned. `openPlan` waited only for `#hs-plan`, which exists immediately, so 9b and 9c counted a
+loading skeleton, concluded the house had nothing to place, and **skipped every run against a
+house with four areas and 78 unfiled devices**. And the tray's File button carries an aria-label
+("File <device> into a room"), which is its accessible name and beats the visible text, so
+`name: /^File$/` had matched nothing since the i18n pass; 9c and 9e hunted it until they timed
+out. A skip-if-empty guard that can also fire for the wrong reason is worse than no guard.
+
+**Two more flakes, fixed at the cause.** Filtering `.hm-plan-room` on `hasText` is a substring
+match over the whole card, devices included, so the Bedroom card (which lists "Kitchen Lights")
+answered to a filter for "Kitchen"; rooms are matched on their own `.hm-plan-room-name` now.
+And 9c filed `loose.first()`, which is as likely to be a YAML-defined entity that can never hold
+an area: the product refuses that correctly and by name (the order's state 9), so the journey now
+asks Home Assistant which entities are registry-backed first.
+
+**Vite HMR is off for this lane** (`VITE_NO_HMR`). Concurrent agents edit `src/` while a journey
+runs, and a connected HMR client reloaded the page under the browser on each of their saves: five
+reloads in one run, and 9e died on a navigation that arrived between naming a room and clicking
+File. The Codespaces HMR host also 404s here, which was three console errors a page the product
+did not cause.
+
+**Deviations from the order file, beyond the 2026-09-03 entry's:** the order says four browser
+journeys; there are six (9, 9b, 9c, 9d, 9e, 9f). It asks for four validator rejections; the
+validator produces eight designed ones, each naming the field it refused (room cap, unknown
+top-level key, unknown room key, non-finite coordinate, coordinate past the origin cap, room
+below the minimum size, `rooms` as an array, unusable room id).
+
+**Left open:** nothing in this order. Two things worth someone's time and out of scope here:
+`scripts/home-test-instance.mjs --seed --json` reports `floors: 0, areas: 0` for a house it just
+gave one floor and four areas (the counter counts only records it created, but the JSON key reads
+as a census), and the local API logs `agent_init_failed Missing required env var:
+S3_PUBLIC_DOMAIN` on every `/api/agents/me`, which is noise in every home e2e log.
+
+**Commits:** the fixes landed under a concurrent agent's messages while this session was running
+(`093990158`, `9d5c14a21`, `dad31271e`, `38eea8d9f`, plus the config's DATABASE_URL loader). The
+content is verified at HEAD by the runs above; the shared-worktree rules against amending and
+against sweeping other agents' work mean the attribution stays as it is. This entry and the order
+file's retirement are this session's only commit.