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): publish the release matrix and say how to run the lane's suites

nirholas4bf9a2a97185
diff --git a/docs/smart-home.md b/docs/smart-home.md
index f84fcd8ad..ecdec63a8 100644
--- a/docs/smart-home.md
+++ b/docs/smart-home.md
@@ -174,11 +174,26 @@ honest answers, in order of preference:
Works today with a long-lived token, zero new code on their side. This is v1.
2. **Browser-local direct connect.** For users who open three.ws from inside their own
network, over a local HTTPS origin. Narrow, but zero-latency and fully private.
-3. **A three.ws HA add-on that dials out.** A small custom component that opens an outbound
- WebSocket to three.ws and relays the two channels. This is the only option that works for
- an untouched LAN-only install, it is the one that ships through HACS, and it is phase 2.
-
-We will not pretend option 1 covers everyone, and we will not ship option 3 as a stub.
+3. **A three.ws integration that dials out.** A Home Assistant custom integration that opens
+ one outbound WebSocket to three.ws and carries the state and action channels over it. The
+ only option that works for an untouched LAN-only install, and the one that ships through
+ HACS.
+
+**Option 3 is built and verified, not planned.** It is
+[`services/home-relay/`](../services/home-relay/README.md) plus
+[`home-assistant-integration/`](../home-assistant-integration), it is proven end to end against
+a real Home Assistant on a network the caller cannot route to, and a home connected that way
+stores no Home Assistant token at all: the integration authenticates locally and nothing
+crosses. See [home-relay.md](home-relay.md) and
+[home-relay-threat-model.md](home-relay-threat-model.md).
+
+A **custom integration rather than an add-on**, and the distinction is load-bearing: an add-on
+only runs on Home Assistant OS and Supervised, while an integration runs on all four install
+types including Container and Core, and HACS distributes integrations rather than add-ons.
+Since the whole point is reaching the installs a remote URL misses, the option with the wider
+reach wins.
+
+We will not pretend option 1 covers everyone, and we did not ship option 3 as a stub.
### Permission model
@@ -247,6 +262,58 @@ below exists, and anything that does not exist says so.
| A real Home Assistant on demand, for every live test | [`scripts/home-test-instance.mjs`](../scripts/home-test-instance.mjs) |
| The tutorial | [docs/tutorials/connect-your-home.md](tutorials/connect-your-home.md) |
+### The connect flow, state by state
+
+`/smart-home` ([`pages/smart-home.html`](../pages/smart-home.html) + [`src/home/connect.js`](../src/home/connect.js)
++ [`src/home/manage.js`](../src/home/manage.js)) is the front door. It is written as an explicit
+state machine rather than a happy path with error handling bolted on, because the interesting
+half of connecting a house is everything that is not the happy path. `STATE` in `connect.js` is
+the list; `render()` is the only place a state is entered, so "which state am I in" is always
+answerable from `#hm-root[data-state]`, which is also how the e2e suite drives it.
+
+| State | When | What it must do |
+|---|---|---|
+| `signed_out` | no session | Explain the feature and offer sign-in. Never a disabled form. |
+| `empty` | signed in, no homes | The connect card, with the token instructions one disclosure away. |
+| `private_host` | the address is LAN-only | Name the address class and give the two real routes out. |
+| `verifying` | the handshake is running | Named steps, cancellable. Never a bare spinner or a fake progress bar. |
+| `connected` / `many` | one or more homes | The measured summary per home, plus grants, log, health and household. |
+| `one_home` | `/smart-home/:id` | That home alone, with a way back up to the list. |
+| `not_found` | an id that is not this account's | Reveals nothing about whether the id exists. |
+| `auth_failed` | Home Assistant rejected the token | Say so, refocus the token field, keep the URL. |
+| `unreachable` | no answer | Separate "wrong address" from "house offline". |
+| `quota_reached` | the plan ceiling | Offer the upgrade and nothing that would fail again. |
+| `revoked` | the last home was disconnected | Say what happened to the stored credential. |
+| `pairing` | the relay is waiting for the house to dial out | Poll, and stop the animation when the poll stops. |
+
+Two invariants hold the surface together, and both are asserted in
+[`tests/e2e/home-connect.spec.js`](../tests/e2e/home-connect.spec.js) rather than left as prose.
+
+**The token goes to the server once and never comes back.** The field is `type="password"` with
+a reveal toggle and `autocomplete="off"`; the value is never written to `localStorage` or
+`sessionStorage`, never placed in a URL, never logged, and never echoed by any endpoint. It is
+gone from the DOM the moment a connect succeeds. Reconnecting a house that is already on the
+account prefills the label and the address, and deliberately does not prefill the token: there
+is nowhere it could be read back from.
+
+**Reachability is decided in the browser, before the network.** `checkReachable()` uses
+`normalizeBaseUrl` and `isPrivateHost` from `@three-ws/home-bridge/url`, the same functions the
+server validates with, so the two cannot disagree about what is reachable. The order of the
+checks is load-bearing: a private host is diagnosed **before** the scheme, because
+`http://192.168.1.10:8123` is the single most common thing a person pastes and it is both plain
+http and unroutable. Answering it with "use https" sends someone off to configure TLS on a
+machine three.ws still could not reach; "that address only exists on your home network" is the
+true answer and the actionable one. The refusal costs zero network requests, which the e2e suite
+asserts by counting requests across the submit.
+
+The subpath import matters for a third reason: `@three-ws/home-bridge/url` pulls in nothing but
+`errors.js`, while the package root pulls the Home Assistant WebSocket client and the MCP SDK.
+Importing the root here would have shipped both to every visitor for two pure string functions.
+
+Everything a house supplies (a label, an entity id, an area name) is rendered with
+`textContent`. These are strings a stranger or a compromised integration can influence, they
+flow into a page and into a model prompt, and there is a physical actuator on the other end.
+
### Not shipped
- **Matter direct control.** Built as a throwaway kernel, measured, and deliberately not kept.
@@ -294,15 +361,53 @@ floor, four areas, 122 entities, two user scenes (Bedtime, Away Mode), four lock
| A standing allowance stays per entity | Same call with `HOME_ALLOWED_ENTITIES=lock.kitchen_door` | Refused; door still `locked` |
| The operator's own allowance does work | Same call with `HOME_ALLOWED_ENTITIES=lock.front_door` | Ran; door `unlocked`, then re-locked |
| Locking up never prompts | `lock.lock` through the server with no allowance at all | Ran |
-| The relay allowlist has not drifted from the protocol | `npx vitest run tests/home-relay-protocol.test.js` | 11 passed |
+| The relay allowlist has not drifted from the protocol | `npx vitest run tests/home-relay-protocol.test.js` | 30 passed |
+| A house on a network the caller cannot route to is driven through the relay | `scripts/home-relay-e2e.mjs` from a container on a second Docker bridge, with no route to the house | 10/10, including a real light toggled, a real door unlocked through the gate, and four allowlist refusals |
| The platform really will not dial a private address | Posted a loopback URL to `POST /api/home` on a local server against the live database | `unreachable`, with the LAN explanation, and nothing stored |
The registry snapshot from that instance is checked in as the package's test fixture
(`packages/home-bridge/tests/fixtures/home.json`, regenerated by
`scripts/capture-home-fixture.mjs`), so a Home Assistant registry change shows up as a failing
test rather than as a surprise in someone's house. The live checks above are also a test file
-(`packages/home-bridge/tests/live-home.test.js`), which skips itself unless
-`HOME_ASSISTANT_URL` and `HOME_ASSISTANT_TOKEN` are set.
+(`packages/home-bridge/tests/live-home.test.js`), which skips itself unless it is given a house:
+`HOME_LIVE=1` lets the harness build one, and `HOME_ASSISTANT_URL` plus `HOME_ASSISTANT_TOKEN`
+point it at one you already have.
+
+### The supported version range, measured
+
+Home Assistant ships a release every month, so the lane's correctness depends on a third party's
+release cadence. `npm run home:matrix` (`scripts/home-version-matrix.mjs`) runs the real client
+library against every release we claim to support and fills in this table from the runs. The
+release set is derived, never hardcoded: Home Assistant's own analytics
+(<https://analytics.home-assistant.io/data.json>, roughly 676,000 opted-in installs) carry the live install share
+per release, and the set is the current stable, the two releases before it, and the oldest
+release still in contiguous wide use at or above one percent of installs. The floor moves on its
+own as the world upgrades.
+
+Measured 2026-09-03:
+
+| Version | Share | Connect | Registries | State stream | Service call | Scenes | `mcp_server` | Notes |
+|---|---|---|---|---|---|---|---|---|
+| `2026.9` (current stable) | 4.17% | pass (2026.9.0) | pass (1f/4a/62d/92e) | pass (push) | pass (gated) | pass (scene) | pass (29 tools) | exposes via `homeassistant/expose_entity` |
+| `2026.8` (previous release) | 50.41% | pass (2026.8.3) | pass (1f/4a/62d/92e) | pass (push) | pass (gated) | pass (scene) | pass (29 tools) | exposes via `homeassistant/expose_entity` |
+| `2026.7` (previous release) | 13.21% | pass (2026.7.4) | pass (1f/4a/61d/87e) | pass (push) | pass (gated) | pass (scene) | pass (29 tools) | exposes via `homeassistant/expose_entity` |
+| `2025.10` (oldest in wide use) | 1.05% | pass (2025.10.4) | pass (1f/4a/52d/79e) | pass (push) | pass (gated) | pass (scene) | pass (22 tools) | exposes via `homeassistant/expose_entity` |
+
+**Supported range: 2025.10 and newer.** Every capability the platform depends on works across it.
+The floor is where install share falls below one percent, not where the code stops working;
+nothing was found that a 2025.10 house cannot do.
+
+One version difference was found, and it is handled by asking the house rather than by reading
+its version number:
+
+| Difference | Releases | How it is handled |
+|---|---|---|
+| The MCP endpoint moved. Through 2025.10 `mcp_server` served only the SSE transport at `/mcp_server/sse`; the Streamable HTTP endpoint at `/api/mcp` arrived later. | 2025.10 and older vs 2026.7 and newer | `connectHomeMcp` tries Streamable HTTP, and on a 404 falls back to SSE. It reports which transport answered (`transport`, `endpoint`). Before this, a 2025.10 house with a loaded `mcp_server` entry and 22 real tools was reported as having no MCP at all. |
+| The exposure command was renamed from `homeassistant/expose_entity/set` to `homeassistant/expose_entity`. | older releases vs the whole supported range | The test harness sends the current name and falls back on `unknown_command`. Every release in the supported range answers to the current name, so the fallback covers only houses below the floor. |
+| The `mcp_server` config flow's `llm_hass_api` field is a multi-select. | whole supported range | The harness reads the flow's own `data_schema` and sends the shape it asks for, rather than assuming a string. |
+
+Feature detection, never version sniffing: nothing in the client library branches on a version
+string. `HomeBridge.haVersion` exists to be reported to a person, not to be compared against.
---
diff --git a/playwright.home.config.js b/playwright.home.config.js
index 59476352e..280d9d947 100644
--- a/playwright.home.config.js
+++ b/playwright.home.config.js
@@ -33,6 +33,11 @@ const localSecrets = {
MCP_RESOURCE: `${APP_ORIGIN}/api/mcp`,
JWT_KID: 'home-e2e',
NODE_ENV: 'development',
+ // The house this lane drives is a container on loopback, and the URL guard
+ // refuses private addresses unless a non-production process opts in. Without
+ // this every journey fails at connect with "127.0.0.1 is a private address",
+ // which reads as a product bug and is a missing flag.
+ HOME_ALLOW_LOCAL_INSTANCE: '1',
};
export default defineConfig({
@@ -60,10 +65,11 @@ export default defineConfig({
{
// The same handlers Cloud Run runs, against the same database.
command: `node --env-file=.env.local server/index.mjs`,
- url: `http://127.0.0.1:${API_PORT}/api/home`,
- // /api/home answers 401 to an anonymous GET, which is a perfectly good
- // "the handler is mounted and the database is reachable" signal.
- ignoreHTTPSErrors: true,
+ // /api/version, not /api/home: the home endpoint answers an anonymous GET
+ // with 401, and Playwright waits out the whole timeout rather than
+ // treating that as ready. /api/version returns 200 and proves the same
+ // thing, that the route table is loaded and handlers are mounted.
+ url: `http://127.0.0.1:${API_PORT}/api/version`,
timeout: 180_000,
reuseExistingServer: false,
stdout: 'pipe',
diff --git a/tests/e2e/README.md b/tests/e2e/README.md
index e2d836d8c..748582b17 100644
--- a/tests/e2e/README.md
+++ b/tests/e2e/README.md
@@ -33,6 +33,74 @@ npx playwright test # reuses the running server
Do not wait on `networkidle` in specs — the app holds long-lived connections
(HMR socket, live feeds). Wait on concrete DOM/state instead.
+## The home lane
+
+The smart-home journeys live behind their own config,
+[`playwright.home.config.js`](../../playwright.home.config.js), and their own ports. They are not
+part of `npm run test:e2e`, because a spec about `/club` has no business booting a house.
+
+```bash
+npm run test:home:e2e # the ten journeys, against a real Home Assistant
+npm run home:instance # just the house: prints its URL and token
+npm run home:instance:down # remove it and its config directory
+npm run home:matrix # the release matrix (pulls one HA image at a time)
+```
+
+The lane's three suites, from cheapest to most expensive:
+
+| Suite | Command | Needs |
+|---|---|---|
+| Pure, over a recording of a real instance | `npx vitest run packages/home-bridge` | nothing |
+| Live, against a real house | `npm run test:home:live` | Docker, or a house you already have |
+| The ten browser journeys | `npm run test:home:e2e` | Docker, `.env.local` with `DATABASE_URL` |
+
+### What `npm run test:home:e2e` actually starts
+
+Three processes and no stubs anywhere between the click and the assertion:
+
+1. **Home Assistant**, from [`scripts/home-test-instance.mjs`](../../scripts/home-test-instance.mjs):
+ a container on a free port, onboarded through the real API, seeded with a floor, four rooms,
+ scenes, `mcp_server`, and a lock exposed to Assist.
+2. **The API**, `node server/index.mjs` on `:8099`: the same handlers Cloud Run runs, against the
+ database in `.env.local`.
+3. **The frontend**, `vite` on `:3020`, with `DEV_API_PROXY` pointed at that API.
+
+Dedicated ports and `reuseExistingServer: false` are deliberate. Other agents run their own
+`npm run dev` on `:3000` in this worktree, and reusing one is not a smaller version of this
+stack: its `/api` proxy points at **production**, so the run silently tests the wrong API and
+reports `No API route matches /api/home` as though the handler were missing.
+
+The house lives on `127.0.0.1`, which both the browser and the server accept because
+`normalizeBaseUrl` exempts loopback from the private-host refusal, so a developer running Home
+Assistant on this machine still works. Journey 10 proves the refusal still fires for every other
+private host.
+
+### Rules this lane holds
+
+- **Assert on the house, never on our own text.** Every journey that touches a lock reads that
+ lock's state back out of Home Assistant. A confirmation card that renders perfectly while the
+ deadbolt moves anyway is the exact failure this lane exists to catch.
+- **No `waitForTimeout`.** Wait for a condition: the state in Home Assistant, the element, the
+ event. `waitForState` in [`tests/_helpers/home-instance.js`](../_helpers/home-instance.js) is
+ the tool for the first one.
+- **No retries.** `retries: 0`, on purpose. A journey that only passes on the second attempt has
+ told us something, and hiding it is how the finding gets lost. A flaky test on a door is worse
+ than an absent one: fix it or delete it, in the session it is found.
+- **Two accounts, provisioned once.** Account creation is limited to five per hour per IP, so the
+ owner and guest accounts are created through the real signup page once and reused from
+ `.ha-config-e2e-accounts.json` (gitignored: real credentials).
+
+### Cleaning up
+
+The house outlives the run on purpose, so ten consecutive runs pay for one boot:
+
+```bash
+npm run home:instance:down # or: node scripts/home-test-instance.mjs --down --name lane
+```
+
+The harness only ever touches containers it labelled itself, so it can never remove another
+agent's Home Assistant on this machine.
+
## The conversion-path specs
`launch-token-flow.spec.js` and `coin-buy-trade.spec.js` cover the platform's
diff --git a/tests/e2e/home-global-setup.js b/tests/e2e/home-global-setup.js
index 3eae68b4a..79ea5ee6b 100644
--- a/tests/e2e/home-global-setup.js
+++ b/tests/e2e/home-global-setup.js
@@ -116,8 +116,17 @@ async function register(browser, origin, role) {
.first()
.textContent()
.catch(() => null);
+ // Say which of the two it was. Blaming the rate limit for what is really a
+ // dead API process sends the next person looking in the wrong place: this
+ // worktree is shared, and the API server has been killed out from under a
+ // run by another agent's `pkill`.
+ const reachable = await fetch(`${origin}/api/home`, { signal: AbortSignal.timeout(10_000) })
+ .then(() => true)
+ .catch(() => false);
throw new Error(
- `could not register the ${role} account${message ? `: ${message.trim()}` : ''}. Account creation is limited to five per hour per IP; the previous accounts in ${path.basename(ACCOUNTS_FILE)} are reused when they still log in.`,
+ reachable
+ ? `could not register the ${role} account${message ? `: ${message.trim()}` : ''}. Account creation is limited to five per hour per IP; the accounts in ${path.basename(ACCOUNTS_FILE)} are reused whenever they still log in.`
+ : `could not register the ${role} account because ${origin}/api is not answering. The API server died during this run; check the [WebServer] output for a SIGTERM.`,
{ cause },
);
} finally {