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
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.mdindex 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 sorather than showing a black canvas.3. **Automatically**, when this device measurably cannot hold 18 frames a seconddiff --git a/docs/smart-home.md b/docs/smart-home.mdindex 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 thIt works; it is not yet worth shipping. The evidence and the conditions that would change thatanswer are in [section 8](#8-matter-direct-control-measured-and-not-yet-built). Nothing of itis 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 verifieddiff --git a/src/home/scene-fallback.js b/src/home/scene-fallback.jsindex 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.jsindex 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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);+ });+});