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
test(home-connect): verify every connect state against a real house and retire order 05
nirholasfa1cc81be788
diff --git a/prompts/finish/302-home-05-connect-flow.md b/prompts/finish/302-home-05-connect-flow.mddeleted file mode 100644index 4f016098b..000000000--- a/prompts/finish/302-home-05-connect-flow.md+++ /dev/null@@ -1,137 +0,0 @@-# 05. The connect flow: `/home` onboarding, every state--**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-[03](home-03-api-surface.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. Start the dev server and exercise this in a real browser; a UI-order that was never opened is not done.--**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 & # port 3000-curl -s localhost:3000/api/home -H "cookie: <dev session>" | head -c 300-grep -n "materialize" vercel.json | head -4 # the page-route pattern to copy-ls pages/ | grep -E "materialize|agent-detail" ; ls src/ | grep -E "materialize|agent-detail"-grep -n "^--" public/tokens.css | head -20 # the vocabulary you must use-```--## What this order owns--Getting a stranger from "I have a Home Assistant somewhere" to "my agent is connected", and-every way that goes wrong. It owns no 3D (order 06) and no voice (order 08).--Route `/home` via a `vercel.json` `routes` entry to `pages/home.html`, controller `src/home/connect.js`.-Follow the `/materialize` precedent exactly: a `routes` entry, a page file, a module in `src/`.--## The flow--1. **Signed out**: the value proposition and a sign-in, not a form that will fail.-2. **No home yet**: the connect card. Two fields, base URL and token, plus a link to the exact- Home Assistant path for minting one (Profile, Security, Long-lived access tokens, Create- token). Never make the user search for it.-3. **URL typed**: validate client-side with `normalizeBaseUrl` and `isPrivateHost` from- `@three-ws/home-bridge`, **before** any network call, and say the true thing immediately:- a `192.168.x.x` or `.local` address cannot be reached by three.ws. Offer the two real paths- (a remote https URL now, or the add-on from order 10 when it lands) rather than a dead end.-4. **Verifying**: a real progress state naming what is happening ("opening a connection",- "reading your rooms"), never a bare spinner and never a fake progress bar.-5. **Connected**: the house summarised. Rooms found, entities found, whether `mcp_server` is on- and how many tools it exposes, the Home Assistant version. All measured, never assumed.-6. **Managing**: the list of homes, per-home status, the standing allowances with a revoke on- each, the action log, and a disconnect that says plainly what it does to the stored token.--## Every state you must build--There are eleven, and a missing one is what makes a product feel unfinished. Each gets a-designed treatment using `public/tokens.css` primitives:--| # | State | Must |-|---|---|---|-| 1 | Signed out | explain the feature, offer sign-in, never a disabled form |-| 2 | Empty (no homes) | the connect card, with the token instructions inline |-| 3 | Validating input | inline, immediate, before the network |-| 4 | Private-host refusal | name the address class and give the two real options |-| 5 | Verifying | named steps, skeleton not spinner, cancellable |-| 6 | Connected | the measured summary, and a clear next action into `/home/:id` |-| 7 | `auth` failure | "create a new long-lived token", with the path, and the field refocused |-| 8 | `unreachable` failure | distinguishes "wrong address" from "house offline", offers a retry and the add-on path |-| 9 | Degraded (connected, breaker open, or stale) | the last known state visibly marked stale with its age, never an empty house |-| 10 | Revoked / disconnected | says the stored credential was scrubbed, offers reconnect |-| 11 | Many homes | the list scales past one without a redesign; long labels truncate without breaking layout |--## Quality bar (non-negotiable)--- Every interactive element has hover, active, focus-visible and disabled states.-- Keyboard: the whole flow is completable without a mouse. Focus moves to the error on failure.-- The token field is `type="password"` with a reveal toggle, `autocomplete="off"`, and is never- written to `localStorage`, never logged, never put in a URL, and never echoed back by the API.-- Nothing shifts layout when async data lands. Reserve the space.-- 320px, 768px and 1440px all work. Test all three.-- Every user-supplied string (the label, entity names, area names) is rendered as text, never as- HTML. This is the same untrusted-input rule as order 04, on the render side.-- Copy is plain language. "Your home is only on your local network" beats "ERR_PRIVATE_HOST".--## Tasks--| # | Task | Files |-|---|---|---|-| 1 | Route and page shell, wired into `data/pages.json` so it is discoverable. | `vercel.json`, `pages/home.html`, `data/pages.json` |-| 2 | The connect controller with all eleven states. | `src/home/connect.js`, `src/home/home.css` |-| 3 | Client-side reachability validation using the published package, so the same logic runs both sides. | same |-| 4 | The manage view: list, status, grants with revoke, action log, disconnect. | `src/home/manage.js` |-| 5 | i18n: every string through the existing extraction path (`npm run i18n:extract`). | as generated |-| 6 | Playwright e2e covering the happy path and at least four failure states. | `tests/e2e/home-connect.spec.js` |-| 7 | Docs and changelog. | `docs/smart-home.md`, `data/changelog.json`, `STRUCTURE.md` |--## Definition of done--- [ ] Screenshots of all eleven states at 1440px, and states 2, 5, 6 and 8 at 320px.-- [ ] A real connect against a real local Home Assistant, in a real browser, with the network tab showing the real `POST /api/home/connect` and its real response.-- [ ] A private-host address produces the designed refusal with no network call. Prove it with an empty network tab.-- [ ] A wrong token produces state 7 with the field refocused, not a generic error.-- [ ] Stopping the Home Assistant container puts a connected home into state 9 with a visible staleness age, and the room list stays on screen.-- [ ] Zero console errors and zero console warnings from your code, on every state.-- [ ] `npm run audit:web` passes for `/home` (see `docs/ops/page-audit.md`; use `audit:web:login` first for the authed sweep).-- [ ] Keyboard-only completion of the connect flow, recorded as a step list in your report.-- [ ] `npx playwright test tests/e2e/home-connect.spec.js` passes.-- [ ] The token never appears in `localStorage`, in a URL, in a console line, or in any API response. Prove each with the command you used.-- [ ] `npm run audit:docs` clean, `npm run check:rules -- --paths <your files>` clean.--## Never blocked--| Blocker | Do this |-|---|---|-| No Home Assistant to connect to | Run one; the docker command is in the context file. Never build a UI against a fixture and call it verified. |-| No QA login | `AUDIT_EMAIL` / `AUDIT_PASSWORD` in `.env`, or `npm run audit:web:provision` to create one through the real register page. |-| A state is hard to reproduce | Force it: stop the container for state 9, use a junk token for 7, use `192.168.1.10` for 4. Every state here is reachable in under a minute. |-| Tempted to store the token client-side "to make reconnect easier" | Refuse. It goes to the server once, encrypted at rest, and never comes back. |-| The design feels sparse | Read `DESIGN-TOKENS.md` and a shipped surface (`/materialize`) before inventing anything. Consistency beats novelty here. |--## Report format--1. The screenshot set (eleven states, plus the four mobile ones).-2. The real connect transcript from the browser network tab.-3. The no-network-call proof for the private-host refusal.-4. The keyboard-only walkthrough.-5. The four token-leak proofs.-6. `audit:web`, Playwright and `check:rules` 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/302-home-05-connect-flow.md--Never delete it on a partial.diff --git a/prompts/finish/_context/home-PROGRESS.md b/prompts/finish/_context/home-PROGRESS.mdindex 207af3d8f..d18210066 100644--- a/prompts/finish/_context/home-PROGRESS.md+++ b/prompts/finish/_context/home-PROGRESS.md@@ -34,7 +34,7 @@ One section per finished order, newest at the bottom:| 02 bridge runtime | done | 2026-09-03 || 03 API surface | done | 2026-09-03 || 04 agent tools | done | 2026-09-09 |-| 05 connect flow | mostly done, see entry | 2026-09-03 |+| 05 connect flow | done | 2026-09-09 || 06 3D home scene | open | || 07 floorplan editor | built, browser verification blocked, see entry | || 08 voice loop | done | 2026-09-09 |@@ -2230,3 +2230,131 @@ repeats. Neither is a product defect and neither reproduces on `https://three.ws**Commits:** `9e9a2f42f` (the two service fixes and their tests, committed from the shared worktreeby a concurrent agent mid-run), `6fc8dccff` (README), plus this entry.++---++## 05. The connect flow: `/smart-home` onboarding, every state, run 2 (2026-09-09)++**Verdict: done.** Run 1 (2026-09-03, above) built the surface and marked itself PARTIAL for one+reason: the order 11 SSRF guard had closed the only route to a real Home Assistant, so the live+half of the acceptance criteria could not be run at all. That is resolved. `api/_lib/home-url-guard.js`+now carries the two-condition seam run 1 asked for (`HOME_ALLOW_LOCAL_INSTANCE=1` AND no+`K_SERVICE`, tested positively so it is off on Cloud Run whatever else is configured), and+`playwright.home.config.js` sets it for the lane. Every item run 1 left open is closed below+against a real house, and no product code needed changing to close them.++**Shipped:** nothing new on the surface. This run is the verification run 1 could not do, plus+five defects fixed in the lane's own evidence harness, each of which was making a green result+mean less than it appeared to.++**Measured, all from run 7 of the tier this session (`npm run test:home:e2e`, connect specs):**+- `tests/e2e/home-connect.spec.js` + `home-connect-live.spec.js` + `home-connect-gallery.spec.js`:+ **39 passed, 0 failed** in 3.2 minutes, against Home Assistant `2026.9.0` in a real container.+- **The real connect:** `HTTP 201`, capabilities measured live as `entityCount 125, areaCount 4,+ floorCount 1, macroCount 2, haVersion 2026.9.0, mcp true, mcpToolCount 29`. `haVersion` is+ asserted equal to what `/api/config` on the house itself returns, not scraped off an entity.+ The whole browser console for the connect was two lines, both `debug: [vite] connecting/connected`.+ Transcript and screenshots: `reports/home-connect-live/`.+- **State 9, live, not rendered:** the container was really stopped mid-test. The card kept its+ entire measured summary (4 rooms, 125 devices, 2 scenes, 2026.9.0, MCP 29 tools), the status+ line read "Not answering right now. It last answered moments ago, and that is the state shown+ below", `data-state` was `degraded`, and the home polled back to `connected` on its own once the+ container returned, with no reconnect and no new token. This is the item run 1 could only assert+ against a two-hour-old timestamp.+- **State 7, live:** a junk token against the real house is classified `auth` on the wire (a 4xx,+ never a 5xx), lands on `data-state="auth_failed"`, refocuses `#hm-token`, names the Long-lived+ access tokens path, keeps the address the user typed, and stores no half-home. Added this run;+ the tier previously proved only that the page maps code `auth` onto state 7, never that a real+ Home Assistant 401 is classified as `auth` at all.+- **All fifteen states photographed at 1440px and 320px** into `reports/home-connect-states/`+ (30 PNGs), each asserted to add **zero horizontal overflow at 320px** and to write nothing to+ the console.+- **Private-host refusal: zero network requests** between submit and the rendered refusal,+ counted on the Playwright request event.+- **Keyboard:** the connect completes from the keyboard against the real house. Tab stops from+ the top of the document to the first field: `Skip to content`, then `What we store, in full`,+ then `hm-label`; then Tab to `hm-url`, Tab to `hm-token`, Enter submits.+- **Token leak, four proofs, all against a real long-lived token:** absent from `localStorage`,+ from `sessionStorage`, from `document.cookie` and from `window.location.href` (read out of the+ page after a real submit); absent from the response body (substring search over the whole body);+ absent from every request URL in the transcript; absent from every console line. Statically:+ `grep -rn "localStorage\|sessionStorage\|document.cookie" src/home/` finds nothing in+ `connect.js` or `manage.js` (the one hit is `scene.js` storing a 2D/3D view preference), and+ `grep -rn "console\." src/home/` finds nothing in either file.+- `npm run audit:web` for `/smart-home`, **authed against production**, desktop and mobile:+ **0 error, 0 warn**, 3 info. Run 1 could only report 6 errors that were all the Codespace's own+ HMR socket; auditing the live site removes that class entirely.+- `npm run audit:docs`: clean, 1590 files. `npm run check:rules`: clean on every file touched.+- Home unit tests, sharded to survive concurrent agents: **655 passed, 0 failed** across 26 files+ (`tests/home-*.test.js` plus `packages/home-bridge`); the live-tier cases skip without a house.++**Five defects fixed, all in the lane's evidence harness rather than the product.** Each one was+letting a run report something other than what it measured:++1. **`tests/e2e/home-global-setup.js`: the documented escape hatch from the registration rate+ limit was itself broken.** `raiseHomeCeiling` iterated a hardcoded `['owner', 'guest']` while+ `HOME_E2E_ROLES` exists precisely so a lane that needs only an owner does not spend one of five+ hourly registrations on a guest. Setting it crashed on `accounts.guest.email`, so the one way+ out of a rate limit was a dead end. Now iterates `ROLES` and skips a role it was not asked to+ provision.+2. **`tests/e2e/home-connect-gallery.spec.js`: the console assertion allowlisted one HTTP status.**+ It muted `Failed to load resource ... 401` by literal string. States 8 and 12 arrived later+ with a 502 and a 402, and both went red over a line Chromium's network stack writes about a+ response the spec itself fulfilled and the page handled correctly. Replaced with a filter that+ asks WHO emitted the line rather than which status it names: HMR, `GL Driver Message` from the+ GPU process, and `Failed to load resource` **scoped to `/api/` by URL**. The same line for a+ stylesheet, a script or a font still fails, which is the half worth keeping.+3. **`tests/e2e/home-connect-stubs.js`: the shared fixture had a ninety-second fuse.**+ `HOME.last_ok_at` was stamped once when the module was imported, and a connected home whose+ last handshake has aged past 90 seconds is state 9. The tier runs for eight minutes, so most of+ it was on the wrong side of that line: `connected` assertions passed or failed purely as a+ function of how long the run had been going and which order the files executed in. The three+ timestamps are now getters, so the fixture means what it says at the moment it is used, and a+ spec that wants a stale house still says so explicitly.+4. **`tests/e2e/home-connect-stubs.js`: state 5 was never actually held.** The gallery holds the+ verifying screen by returning a promise that never settles, and `stub` passed that promise+ straight to `route.fulfill`, which answered the request immediately with an empty 200. The page+ then read no home, asked for the list, got an empty one, and landed on the EMPTY screen. State+ 5 existed only for as long as one round trip against a local stub, so the spec passed on a+ quiet machine, failed on a loaded one, and on the runs where it passed it was photographing a+ frame rather than a state. `onConnect` is now awaited, which makes a never-settling promise a+ real hang. `05-verifying-1440.png` is the first honest picture of that screen.+5. **`scripts/home-test-instance.mjs`: one killed harness poisoned its lane for fifteen minutes.**+ `withLock` abandoned a lock only on age, with a 900-second threshold, while every caller of the+ harness kills it on a much shorter timeout (`stopHomeInstance` allows 120 seconds) and a killed+ process never reaches the `finally` that releases. So a timeout left a lock, the next call sat+ in the wait loop until that lock aged out, died on its own caller's timeout, and left a fresh+ one: one kill guaranteed the next several. It presented as `home-test-instance timed out after+ 120s` on a `--stop` that takes **7 seconds** when it runs at all, which reads as a hung+ container and is a dead process's leftovers. The lock now records its holder's pid and a waiter+ asks the operating system whether that process still exists. Proven both ways: a planted lock+ owned by a dead pid is reclaimed and the call completes in 11 seconds, and a planted lock owned+ by a live pid is still waited on, by name (`[lock] waiting for pid 418469 to finish with "c05"`).+ `EPERM` counts as held, so another user's process is never evicted. SIGTERM and SIGINT now+ release the lock too; SIGKILL cannot be caught, which is why the pid check is the real fix.++**Deviations from the order file, beyond the ones run 1 already recorded:**+- The order file asks for eleven states and a route at `/home`. Both were already superseded and+ are correct as they stand: the route is `/smart-home` (run 1's deviation 1, `/home` is the+ marketing landing page), and the flow has **fifteen** states, the four beyond the original+ twelve being the pairing host, one deep-linked home, and an id that is not this account's.+- The order's task list (page, controller, i18n, docs, changelog, `STRUCTURE.md`, `data/pages.json`)+ was all completed by run 1 and verified present this run, so nothing there was rebuilt.+ `data/changelog.json` gets no entry from this run: every change here is test-harness only, with+ no user-visible effect, which the CLAUDE.md changelog rule explicitly excludes.++**Operational note for the next lane, not a defect:** `playwright.home.config.js` defaults to+ports 8099 and 3020 and refuses to reuse a server, so two agents running the home lane at once+collide with `http://127.0.0.1:8099/api/version is already used`. That is the config behaving as+its own comment says it should (own the ports or fail loudly). Set `HOME_E2E_API_PORT` and+`HOME_E2E_WEB_PORT`, as this run did (8107 and 3027), rather than killing the peer's server.++**Left open: nothing for this order.**++**Commits:** all five fixes reached `main` inside concurrent agents' `git add -A` sweeps before+they could be staged from here, under commit messages about other work: `f663e9c9a` carries the+harness lock fix, the ROLES fix, the gallery filter, the live-spec filter, the new state 7 test+and the fixture getters, and `af50eb075` carries the `onConnect` await. The content is intact and+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.