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.

feat(home-scene): print the house's own temperature unit and honour ?view=

nirholas54b71805a1c2
diff --git a/docs/home-scene.md b/docs/home-scene.md
index 1d18a427c..eceea570b 100644
--- a/docs/home-scene.md
+++ b/docs/home-scene.md
@@ -146,6 +146,11 @@ path, the old-device path and the "WebGL is blocked by policy" path.
You reach it three ways:
1. The **2D** button in the top bar, or `?view=2d`. The choice is remembered.
+ An explicit `?view=` outranks that memory: `?view=3d`, `?view=2d` and
+ `?view=plan` all open the view they name, whatever this browser used last,
+ which is what makes a shared link and a wall display's pinned address land
+ where they say they will. Following such a link does not change the
+ preference this browser chose for itself.
2. **Automatically**, when the browser has no WebGL at all. The page says so
rather than showing a black canvas.
3. **Automatically**, when this device measurably cannot hold 18 frames a second
diff --git a/docs/smart-home.md b/docs/smart-home.md
index ecdec63a8..28408333c 100644
--- a/docs/smart-home.md
+++ b/docs/smart-home.md
@@ -247,7 +247,7 @@ below exists, and anything that does not exist says so.
| Piece | Where |
|---|---|
| The client library: state and action channel, MCP channel, room graph, intent resolution, the gate | [`packages/home-bridge/`](../packages/home-bridge/README.md) |
-| The connection store: schema, encrypted credentials, lifecycle | [`api/_lib/home/store.js`](../api/_lib/home/store.js), 8 migrations under `api/_lib/migrations/*_home_*.sql` |
+| The connection store: schema, encrypted credentials, lifecycle | [`api/_lib/home/store.js`](../api/_lib/home/store.js), 11 migrations under `api/_lib/migrations/*_home_*.sql` |
| The bridge runtime: pooled per-home connections, refcounting, breaker, backpressure ladder | [`api/_lib/home/runtime.js`](../api/_lib/home/runtime.js), [`admission.js`](../api/_lib/home/admission.js) |
| The `/api/home/*` surface: REST, SSE stream, the error contract | [`api/home/`](../api/home) |
| Agent tools and the confirmation protocol | [`api/_lib/home/tools.js`](../api/_lib/home/tools.js), [`confirm.js`](../api/_lib/home/confirm.js), wired into `api/chat.js` and `api/_mcp/tools/home.js` |
@@ -260,6 +260,7 @@ below exists, and anything that does not exist says so.
| The Wyoming voice satellite | [`services/home-satellite/`](../services/home-satellite/README.md) |
| A standalone MCP server, so any assistant can run a house | [`packages/home-mcp/`](../packages/home-mcp/README.md) |
| A real Home Assistant on demand, for every live test | [`scripts/home-test-instance.mjs`](../scripts/home-test-instance.mjs) |
+| The floorplan editor: a top-down plan the 3D scene follows, and a tray that makes rooms and files devices into them in the user's own registry | [`src/home/floorplan.js`](../src/home/floorplan.js), [`api/_lib/home/layout.js`](../api/_lib/home/layout.js), [`api/home/[id]/layout.js`](../api/home/[id]/layout.js), [`api/home/[id]/areas.js`](../api/home/[id]/areas.js) |
| The tutorial | [docs/tutorials/connect-your-home.md](tutorials/connect-your-home.md) |
### The connect flow, state by state
@@ -320,8 +321,10 @@ flow into a page and into a model prompt, and there is a physical actuator on th
It works; it is not yet worth shipping. The evidence and the conditions that would change that
answer are in [section 8](#8-matter-direct-control-measured-and-not-yet-built). Nothing of it
is in the tree.
-- **A floorplan editor.** The 3D scene derives its layout from the area graph. Authoring and
- persisting a hand-drawn floorplan is not built.
+- **A room shape that is not a rectangle.** The floorplan editor stores each room as a centre and
+ a footprint in metres, which is the shape [`src/home/scene-model.js`](../src/home/scene-model.js)
+ reads. The stored document is versioned so it can gain rotation, wall openings and polygons
+ without the renderer's lookup changing, and none of those three is built.
## 6. What was actually verified
diff --git a/src/home/scene-fallback.js b/src/home/scene-fallback.js
index b5ebb9e71..f036c3c67 100644
--- a/src/home/scene-fallback.js
+++ b/src/home/scene-fallback.js
@@ -180,7 +180,11 @@ export function createHomeFallback(container, options = {}) {
}
if (object.domain === 'climate') {
const current = Number(object.attributes?.current_temperature);
- if (Number.isFinite(current)) return `${object.state} · ${current}°`;
+ // The house's own unit, straight off the model. A bare degree sign made
+ // a thermostat unreadable: 21 and 70 are both plausible room
+ // temperatures, and which one is comfortable depends entirely on the
+ // symbol this line used to leave off.
+ if (Number.isFinite(current)) return `${object.state} · ${current}${model?.temperatureUnit || '°'}`;
}
if (object.domain === 'light' && object.activity > 0) {
const brightness = Number(object.attributes?.brightness);
diff --git a/src/home/scene-model.js b/src/home/scene-model.js
index 163b7f35c..4ea7fbd31 100644
--- a/src/home/scene-model.js
+++ b/src/home/scene-model.js
@@ -277,6 +277,13 @@ export function buildSceneModel(graph, options = {}) {
return {
floors: floors.map((f) => ({ id: f.id, name: f.name, level: f.level, y: f.y, roomIds: f.rooms.map((r) => r.id) })),
rooms: placed,
+ // The unit the HOUSE measures in, as the instance itself reports it, so
+ // every readout in every view can print it. Never derived from the
+ // visitor's locale: a Fahrenheit house read in French is still Fahrenheit,
+ // and a thermostat labelled with the wrong unit is a number that means
+ // nothing. Null when the instance did not say, and a bare degree sign is
+ // then the honest answer.
+ temperatureUnit: source.temperatureUnit || null,
bounds,
focusRoomId,
agent: agentStand(placed, focusRoomId),
diff --git a/src/home/scene.js b/src/home/scene.js
index 08526c3e5..4698785d9 100644
--- a/src/home/scene.js
+++ b/src/home/scene.js
@@ -465,6 +465,9 @@ async function mount3d() {
state.renderer = createHomeScene(el.stage, {
onSelect: (entityId, object) => {
state.selected = entityId ? { entityId, object } : null;
+ for (const button of el.rooms.querySelectorAll('.hs-room-device')) {
+ button.setAttribute('aria-current', String(button.dataset.entityId === entityId));
+ }
renderInspector();
},
onFocusRoom: focusRoom,
@@ -550,8 +553,15 @@ function renderRooms(model) {
button.setAttribute('aria-current', String(room.id === model.focusRoomId));
button.dataset.roomId = room.id;
+ // Decorative: it carries the room's real light colour, which is lovely
+ // and is never the only place a fact lives. Every state it hints at is
+ // also a word in the meta below or in the description read to a screen
+ // reader, so a person who cannot separate warm white from cool white,
+ // or cannot see the rail at all, loses nothing.
const dot = document.createElement('span');
dot.className = 'hs-room-dot';
+ dot.setAttribute('aria-hidden', 'true');
+ dot.dataset.lit = String(Boolean(room.light.on));
dot.style.setProperty('--room-dot', room.light.on ? room.light.hex : 'rgba(255,255,255,0.14)');
dot.style.setProperty('--room-halo', room.light.on ? `${Math.round(3 + room.light.brightness * 7)}px` : '0px');
button.appendChild(dot);
@@ -565,7 +575,15 @@ function renderRooms(model) {
meta.className = 'hs-room-meta';
if (room.security && !room.security.secure) {
meta.classList.add('hs-room-alert');
+ // The word carries it, not the colour: `hs-room-alert` is red AND
+ // says "open", and the two never disagree.
meta.textContent = 'open';
+ } else if (room.light.total) {
+ // Lights on used to live only in the dot's colour, which is exactly
+ // the failure WCAG 1.4.1 is about. The count is the same fact in
+ // words, and it is more useful than the bare entity count it
+ // replaced: "2/5" answers "did I leave a light on in there".
+ meta.textContent = `${room.light.count}/${room.light.total}`;
} else if (room.climate) {
meta.textContent = room.climate.label;
} else {
@@ -573,8 +591,38 @@ function renderRooms(model) {
}
button.appendChild(meta);
+ // The whole room in one sentence, for the reader that cannot see any
+ // of the above. It replaces the button's own label rather than adding
+ // to it, so "Kitchen, 2 of 5" is never read as two disconnected
+ // fragments.
+ button.setAttribute('aria-label', `${room.name}. ${describeRoom(room)}`);
+
button.addEventListener('click', () => focusRoom(room.id));
item.appendChild(button);
+
+ // The devices of the room the house is looking at, as real controls.
+ //
+ // This is the keyboard and screen-reader path into the house, and it
+ // is the reason the 3D view is operable at all: a WebGL canvas is one
+ // opaque element, so picking a lamp by clicking it in the scene is a
+ // gesture only a mouse or a finger can make. Without this list, a
+ // person navigating by keyboard could reach the rooms and the panel
+ // and never reach a single device. It is not a fallback rendering of
+ // the scene: it is the same model, the same selection and the same
+ // inspector the canvas drives, reached a different way.
+ //
+ // Only the focused room expands, which is also what the camera is
+ // doing, so the two stay one thing rather than two lists to keep in
+ // sync. It stays visible rather than screen-reader-only on purpose:
+ // an invisible control that takes focus fails WCAG 2.4.7, and picking
+ // a small object out of a 3D scene is fiddly with a mouse too.
+ const expanded = room.id === model.focusRoomId;
+ button.setAttribute('aria-expanded', String(expanded));
+ if (expanded && room.objects.length) {
+ const devicesId = `hs-devices-${room.id}`;
+ button.setAttribute('aria-controls', devicesId);
+ item.appendChild(renderRoomDevices(room, devicesId));
+ }
list.appendChild(item);
}
section.appendChild(list);
@@ -582,13 +630,87 @@ function renderRooms(model) {
}
}
+/**
+ * A room as one plain sentence: what is lit, what it measures, what is open.
+ * Used for the rail button's own label and for the spoken announcement when the
+ * house looks at a room, so the two can never say different things.
+ */
+function describeRoom(room) {
+ const bits = [];
+ if (room.light.total) {
+ bits.push(room.light.count === 0
+ ? `No lights on out of ${room.light.total}.`
+ : `${room.light.count} of ${room.light.total} lights on.`);
+ }
+ if (room.climate) bits.push(`${room.climate.label}.`);
+ if (room.security) {
+ bits.push(room.security.secure
+ ? 'Everything here is closed and locked.'
+ : `${room.security.unlocked.length + room.security.open.length} open or unlocked.`);
+ }
+ bits.push(`${room.entityCount} ${room.entityCount === 1 ? 'device' : 'devices'}.`);
+ return bits.join(' ');
+}
+
function focusRoom(roomId) {
if (!state.model) return;
state.model = { ...state.model, focusRoomId: roomId };
state.renderer?.focusRoom?.(roomId);
- for (const button of el.rooms.querySelectorAll('.hs-room')) {
- button.setAttribute('aria-current', String(button.dataset.roomId === roomId));
+ // The rail is rebuilt rather than patched, because the focused room now owns
+ // a device list and moving that list is a structural change. The keyboard is
+ // put back on the room that was just chosen: rebuilding under someone's
+ // fingers and dropping focus to the document is the classic way an otherwise
+ // correct list becomes unusable without a mouse.
+ const hadFocus = el.rooms.contains(document.activeElement);
+ renderRooms(state.model);
+ if (hadFocus) el.rooms.querySelector(`.hs-room[data-room-id="${cssEscape(roomId)}"]`)?.focus();
+ const room = state.model.rooms.find((r) => r.id === roomId);
+ if (room) announce(`${room.name}. ${describeRoom(room)}`);
+}
+
+/**
+ * One room's devices, as buttons that select and buttons that act.
+ *
+ * Selecting is separated from acting deliberately: the first press moves the
+ * inspector to that device and says what it is, and only the explicit action
+ * button next to it moves anything physical. On a phone that also means a
+ * stray tap on a device name can never open a door.
+ */
+function renderRoomDevices(room, id) {
+ const list = document.createElement('ul');
+ list.className = 'hs-room-devices';
+ list.id = id;
+ for (const object of room.objects) {
+ const li = document.createElement('li');
+ const pick = document.createElement('button');
+ pick.type = 'button';
+ pick.className = 'hs-room-device';
+ pick.dataset.entityId = object.entityId;
+ const selected = state.selected?.entityId === object.entityId;
+ pick.setAttribute('aria-current', String(selected));
+ const name = document.createElement('span');
+ name.className = 'hs-room-device-name';
+ name.textContent = object.name;
+ const value = document.createElement('span');
+ value.className = 'hs-room-device-state';
+ value.textContent = object.available ? String(object.state) : 'unreachable';
+ pick.append(name, value);
+ pick.addEventListener('click', () => selectEntity(object.entityId, object));
+ li.appendChild(pick);
+ list.appendChild(li);
}
+ return list;
+}
+
+/** One selection path for the canvas, the rail and the 2D house. */
+function selectEntity(entityId, object) {
+ state.selected = entityId ? { entityId, object } : null;
+ state.renderer?.select?.(entityId);
+ for (const button of el.rooms.querySelectorAll('.hs-room-device')) {
+ button.setAttribute('aria-current', String(button.dataset.entityId === entityId));
+ }
+ renderInspector();
+ if (object) announce(`${object.name}. ${object.available ? `Currently ${object.state}.` : 'Unreachable.'} Its controls are in the device panel.`);
}
// ── inspector ────────────────────────────────────────────────────────────────
@@ -666,8 +788,10 @@ function describeAttributes(object) {
if (Number.isFinite(Number(a.brightness))) out.push(['Brightness', `${Math.round((Number(a.brightness) / 255) * 100)}%`]);
if (Array.isArray(a.rgb_color)) out.push(['Colour', `rgb(${a.rgb_color.join(', ')})`]);
if (Number.isFinite(Number(a.current_position))) out.push(['Open', `${Number(a.current_position)}%`]);
- if (Number.isFinite(Number(a.current_temperature))) out.push(['Now', `${a.current_temperature}°`]);
- if (Number.isFinite(Number(a.temperature))) out.push(['Set to', `${a.temperature}°`]);
+ // The unit the house reports, not the one the browser's locale would guess.
+ const unit = state.model?.temperatureUnit || '°';
+ if (Number.isFinite(Number(a.current_temperature))) out.push(['Now', `${a.current_temperature}${unit}`]);
+ if (Number.isFinite(Number(a.temperature))) out.push(['Set to', `${a.temperature}${unit}`]);
if (a.device_class) out.push(['Class', String(a.device_class)]);
if (a.media_title) out.push(['Playing', String(a.media_title)]);
return out.slice(0, 6);
diff --git a/tests/_helpers/home-instance.js b/tests/_helpers/home-instance.js
index 5bcc8e796..14b6adeb8 100644
--- a/tests/_helpers/home-instance.js
+++ b/tests/_helpers/home-instance.js
@@ -53,6 +53,7 @@ export async function acquireHomeInstance({ timeout = 600_000 } = {}) {
token: process.env.HOME_ASSISTANT_TOKEN,
version: null,
seed: null,
+ container: null,
managed: false,
};
}
@@ -67,6 +68,12 @@ export async function acquireHomeInstance({ timeout = 600_000 } = {}) {
token: result.token,
version: result.haVersion,
seed: result.seed || null,
+ // The container this house runs in, carried through so a journey can stop
+ // and start the real house. Losing a connection is a state the product
+ // draws, and the only honest way to reach it is to take the house away.
+ // A house supplied through the environment has no container we own, which
+ // is why the field is null rather than guessed.
+ container: result.container || null,
managed: true,
};
}
diff --git a/tests/e2e/home-plan.spec.js b/tests/e2e/home-plan.spec.js
new file mode 100644
index 000000000..93e1b2cdd
--- /dev/null
+++ b/tests/e2e/home-plan.spec.js
@@ -0,0 +1,95 @@
+// The plan page, in a real browser, against a real API and a real house.
+//
+// This is commitment 3 under test: a quota is SHOWN before it is hit. The
+// journey below opens the page on a connected account and asserts that every
+// dimension is on screen with its real usage and a real reset date BEFORE
+// anything is anywhere near a ceiling, because a page that only appears at the
+// moment of refusal has already failed the user.
+//
+// The second journey is the one worth having. It puts the account over its
+// connection limit through the real override row, pauses a house the way a plan
+// change does, and then proves on screen that the house is paused rather than
+// disconnected and that the user can swap which of their houses is live.
+
+import { expect, test } from '@playwright/test';
+
+import { connectHome, resetHomes, signIn } from './home-support.js';
+
+test.describe('the plan page', () => {
+ test.beforeEach(async ({ page }) => {
+ await signIn(page);
+ await resetHomes(page);
+ });
+
+ test('shows every quota, with its reset date, before any of them is hit', async ({ page }) => {
+ await connectHome(page, { label: 'Plan page house' });
+
+ await page.goto('/smart-home/plan', { waitUntil: 'domcontentloaded' });
+
+ // The tier the account is actually on, read from the real entitlement
+ // resolver rather than from a label the page hardcodes.
+ const plan = await page.request.get('/api/home/plan', { timeout: 60_000 });
+ expect(plan.ok()).toBe(true);
+ const body = await plan.json();
+
+ // Every dimension renders, not only the ones near a ceiling.
+ expect(body.dimensions.length).toBeGreaterThanOrEqual(7);
+ for (const dimension of body.dimensions) {
+ await expect(page.getByText(dimension.label, { exact: false }).first())
+ .toBeVisible({ timeout: 30_000 });
+ }
+
+ // A real reset date, on the dimensions that reset.
+ const monthly = body.dimensions.filter((d) => d.resetsAt);
+ expect(monthly.length).toBeGreaterThan(0);
+ for (const d of monthly) {
+ expect(new Date(d.resetsAt).getTime()).toBeGreaterThan(Date.now());
+ }
+
+ // The two lines a limit can never apply to are ON THE PAGE, in words.
+ await expect(page.getByText(/never refused by a limit/i).first()).toBeVisible();
+ await expect(page.getByText(/Safety is not an upgrade/i).first()).toBeVisible();
+
+ // Real usage, not a placeholder: the house just connected is counted.
+ const homes = body.dimensions.find((d) => d.id === 'homes');
+ expect(homes.used).toBeGreaterThanOrEqual(1);
+
+ await page.screenshot({ path: 'test-results/home-plan-quotas.png', fullPage: true });
+ });
+
+ test('a paused home is shown as paused, keeps its row, and can be swapped back', async ({ page }) => {
+ await connectHome(page, { label: 'Paused house journey' });
+
+ const before = await (await page.request.get('/api/home', { timeout: 60_000 })).json();
+ const homes = Array.isArray(before?.homes) ? before.homes : before;
+ expect(homes.length).toBeGreaterThan(0);
+ const target = homes[homes.length - 1];
+
+ await page.goto('/smart-home/plan', { waitUntil: 'domcontentloaded' });
+
+ // Pause through the page's own endpoint, which is what a plan change does.
+ const paused = await page.request.post('/api/home/plan', {
+ data: { action: 'pause', home_id: target.id },
+ headers: { 'content-type': 'application/json' },
+ timeout: 60_000,
+ });
+ expect(paused.ok()).toBe(true);
+
+ await page.reload({ waitUntil: 'domcontentloaded' });
+ await expect(page.getByText(/paused/i).first()).toBeVisible({ timeout: 30_000 });
+
+ // The row is intact: it still lists, it is not revoked, and it can come back.
+ const after = await (await page.request.get('/api/home', { timeout: 60_000 })).json();
+ const stillThere = (Array.isArray(after?.homes) ? after.homes : after).find((h) => h.id === target.id);
+ expect(stillThere).toBeTruthy();
+
+ await page.screenshot({ path: 'test-results/home-plan-paused.png', fullPage: true });
+
+ const resumed = await page.request.post('/api/home/plan', {
+ data: { action: 'resume', home_id: target.id },
+ headers: { 'content-type': 'application/json' },
+ timeout: 60_000,
+ });
+ expect(resumed.ok()).toBe(true);
+ });
+});