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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.mddeleted file mode 100644index 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.mdindex 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 contverified at HEAD; only the attribution is wrong, and the shared-worktree rule against amendingmeans it stays that way. This entry and the order-file retirement are the only commit from thissession.+++---++## 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.