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): let an invited member join a household from the link itself

nirholas842ec690e0b9
diff --git a/api/_lib/home-url-guard.js b/api/_lib/home-url-guard.js
index b59cdb43e..708a50223 100644
--- a/api/_lib/home-url-guard.js
+++ b/api/_lib/home-url-guard.js
@@ -28,6 +28,8 @@
import { ERR_CANNOT_CONNECT, ERR_INVALID_AUTH } from 'home-assistant-js-websocket';
import { normalizeBaseUrl } from '../../packages/home-bridge/src/url.js';
+import { Agent } from 'undici';
+
import { isPrivateAddress, pinnedAgent, resolvePublicHost, SsrfError } from './ssrf.js';
/**
@@ -150,9 +152,36 @@ async function resolveAnyHost(host) {
* @param {{host: string, addresses: Array<{address: string, family: number}>}} pin
*/
export function homeDispatcher(pin) {
+ // `pinnedAgent` re-checks every address against isPrivateAddress, which is
+ // right for every real deployment and wrong for the local-instance seam: the
+ // guard has already resolved and approved 127.0.0.1, and a second filter here
+ // would drop it and report "no public address to connect to". Under the seam
+ // the pin still applies (the lookup only ever yields the approved addresses
+ // for the approved host); it simply skips the public-address requirement it
+ // was already exempted from upstream.
+ if (ALLOW_LOCAL_INSTANCE) return localPinnedAgent(pin.host, pin.addresses);
return pinnedAgent(pin.host, pin.addresses);
}
+/**
+ * The seam's dispatcher: identical to `pinnedAgent` minus the public-address
+ * filter. Development only, and unreachable unless ALLOW_LOCAL_INSTANCE is on,
+ * which requires a non-production NODE_ENV.
+ */
+function localPinnedAgent(expectedHost, addresses) {
+ return new Agent({
+ connect: {
+ lookup(hostname, _opts, cb) {
+ if (hostname !== expectedHost) {
+ cb(new HomeUrlError('host_pin_mismatch', `unexpected connect host: ${hostname}`));
+ return;
+ }
+ cb(null, addresses.map((a) => ({ address: a.address, family: a.family })));
+ },
+ },
+ });
+}
+
/**
* A pinned WebSocket to the home's state channel.
*
diff --git a/api/_lib/home/tools.js b/api/_lib/home/tools.js
index 5b85a56a7..50b8545a3 100644
--- a/api/_lib/home/tools.js
+++ b/api/_lib/home/tools.js
@@ -582,7 +582,16 @@ async function performCall({ domain, service, data }, run, { toolName, extra = {
// Ungated: one call, no prompt. A product that nags on the safe direction is
// a product people turn off, so locking up and arming the alarm run here.
try {
- await withHome(run.homeId, run.ownerId, (bridge) => bridge.call(domain, service, data, { confirmed: false }));
+ await withHome(run.homeId, run.ownerId, (bridge) => {
+ // The pooled bridge carries its own copy of the gate, and it built its
+ // allow list when the socket opened. Grants change while a socket is
+ // open, in both directions, so the live set is pushed in before every
+ // write: a standing allowance granted a minute ago must work now, and
+ // one revoked a minute ago must stop working now rather than when the
+ // connection happens to recycle.
+ syncAllowList(bridge, grants);
+ return bridge.call(domain, service, data, { confirmed: false });
+ });
} catch (error) {
// Logged and answered HERE rather than rethrown. A rethrow would reach
// `bridgeFailure` in the dispatcher, which logs a second row under the tool
@@ -716,6 +725,20 @@ function toList(value) {
.filter(Boolean);
}
+/**
+ * Make the bridge's own allow list equal the home's live grants.
+ *
+ * `bridge.call` runs the gate a second time, independently of this module, which
+ * is deliberate: two gates on a front door is the right number. But the bridge's
+ * copy is only as fresh as the moment its socket opened, and a pooled socket
+ * lives for as long as somebody is watching the house.
+ */
+function syncAllowList(bridge, granted) {
+ const current = new Set(bridge.allowList.list());
+ for (const entityId of granted) if (!current.has(entityId)) bridge.allowList.add(entityId);
+ for (const entityId of current) if (!granted.has(entityId)) bridge.allowList.remove(entityId);
+}
+
// ── Composition and shaping ──────────────────────────────────────────────────
/**
diff --git a/api/_lib/home/usage.js b/api/_lib/home/usage.js
index f16cc4690..56813ed55 100644
--- a/api/_lib/home/usage.js
+++ b/api/_lib/home/usage.js
@@ -229,7 +229,11 @@ async function readGauges(userId) {
select
count(*) filter (where c.revoked_at is null and c.deactivated_at is null)::int as homes,
count(*) filter (where c.revoked_at is null and c.deactivated_at is null and c.transport = 'relay')::int as relay_connections,
- coalesce(max(m.members), 0)::int as members
+ coalesce(max(m.members), 0)::int as members,
+ -- The longest retention any of this account's homes is set to. That is
+ -- the number the plan's ceiling is a ceiling on, and the one that would
+ -- be refused if the user raised it further.
+ coalesce(max(c.action_log_retention_days) filter (where c.revoked_at is null), 0)::int as log_retention_days
from home_connections c
left join lateral (
select count(*)::int as members from home_members hm where hm.home_id = c.id
@@ -244,7 +248,7 @@ async function readGauges(userId) {
// surface shows is the fullest household: that is the one that would be
// refused an invite, and therefore the one worth showing.
members: row.members ?? 0,
- logRetentionDays: 0,
+ logRetentionDays: row.log_retention_days ?? 0,
};
}
diff --git a/data/pages.json b/data/pages.json
index bba4992bd..387deb436 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -1001,6 +1001,14 @@
"changefreq": "weekly",
"added": "2026-09-02"
},
+ {
+ "path": "/smart-home/join",
+ "title": "Join a home",
+ "description": "Accept an invitation to somebody's connected home. The link says which home it is, exactly what your role would let you do there and what it would never let you do, before you sign in. It works once and it expires.",
+ "priority": 0.4,
+ "changefreq": "yearly",
+ "added": "2026-09-03"
+ },
{
"path": "/smart-home/plan",
"title": "Home plan",
diff --git a/packages/home-bridge/README.md b/packages/home-bridge/README.md
index 40bf2fc7e..4ca55b169 100644
--- a/packages/home-bridge/README.md
+++ b/packages/home-bridge/README.md
@@ -13,6 +13,11 @@ than anything we would write. This package is the 200 lines in the middle that w
Why this exists, what else was evaluated, and where it goes next:
[docs/smart-home.md](../../docs/smart-home.md).
+**Pre-1.0.** An agent reaching a real building is new enough that the shape is not settled, and
+the export surface will move before 1.0. Pin an exact version if you are building on it. The one
+thing that will not move is the gate: reads free, safety moves unprompted, and anything that opens
+the house stops and asks.
+
## Install
```bash
diff --git a/packages/home-bridge/tests/fixtures/home.json b/packages/home-bridge/tests/fixtures/home.json
index 3c5ee58a9..c12fbbb40 100644
--- a/packages/home-bridge/tests/fixtures/home.json
+++ b/packages/home-bridge/tests/fixtures/home.json
@@ -3,7 +3,7 @@
"floors": [
{
"floor_id": "ground_floor",
- "name": "Ground floor",
+ "name": "Ground Floor",
"level": 0,
"icon": null
}
@@ -20,7 +20,7 @@
"area_id": "kitchen",
"name": "Kitchen",
"icon": "mdi:stove",
- "floor_id": "ground_floor",
+ "floor_id": null,
"aliases": []
},
{
@@ -29,313 +29,325 @@
"icon": "mdi:bed",
"floor_id": "ground_floor",
"aliases": []
+ },
+ {
+ "area_id": "front_door",
+ "name": "Front Door",
+ "icon": null,
+ "floor_id": "ground_floor",
+ "aliases": []
}
],
"devices": [
{
- "id": "e690362aad494c5b2eb79131d6e22e1a",
+ "id": "5484402f49ec4c5a5cc3057f0042aaf3",
"area_id": null,
"name": "Sun"
},
{
- "id": "bb8f0556ef84eed54f178dde192a9bfb",
- "area_id": null,
- "name": "Backup"
- },
- {
- "id": "a4d24210a270ed3217aab4f26f46a2bd",
- "area_id": null,
- "name": "Google Translate en com"
- },
- {
- "id": "2ec833737b627d775722879de4fcfba1",
+ "id": "e29b44b4f0268dd69b5c576e5b0d8604",
"area_id": null,
"name": "Basement Floor Wet"
},
{
- "id": "9d46f32a54020b501a53851f9f3327f1",
+ "id": "715267e1932503f69a7cf98760381723",
"area_id": null,
"name": "Movement Backyard"
},
{
- "id": "9fc4cbfbf5305340d7fd87034dc17f9e",
+ "id": "12992da36230b887d704adef59daecf7",
"area_id": null,
"name": "Outside Temperature"
},
{
- "id": "318164cfc0a4983822733c80240f1e7b",
+ "id": "f6945939e4c8fdf23ef322128a03cb20",
"area_id": null,
"name": "Push"
},
{
- "id": "8a84afd34a4001c67bdab5c455e79077",
+ "id": "b39ea500b282b16f384c208e39235f41",
"area_id": null,
"name": "HeatPump"
},
{
- "id": "e70d2d25aba01c0b18687fa4029d4434",
+ "id": "c90c8f080bcea0227f67ffa0c7bcbdf8",
"area_id": null,
"name": "Hvac"
},
{
- "id": "49de48e2e716ee64a39aa650a4e77385",
+ "id": "e9f4028288367ff1173fab481d8016fd",
"area_id": null,
"name": "Ecobee"
},
{
- "id": "c1211266a8d4123303b89953992dd589",
+ "id": "b8d215b824f80d9cc24ceb0e262b8d11",
"area_id": null,
"name": "Kitchen Window"
},
{
- "id": "30bacd9554f761a26c17e8831a29ebd4",
+ "id": "6a690f56c69b29c98f59712e5f096d20",
"area_id": null,
"name": "Hall Window"
},
{
- "id": "8d3d0ba2ad95dccaff8fd291a97efc93",
+ "id": "83a4887330f7eecc3d8ba0d5784f48f7",
"area_id": null,
"name": "Living Room Window"
},
{
- "id": "27fb91b71765f7572821547aca0cb7c4",
+ "id": "4f5cf01ee3ad1ceffe4bdcc124ee478b",
"area_id": null,
"name": "Garage Door"
},
{
- "id": "74c07d6fb548627014cefdb4fd5d9da4",
+ "id": "94bf640e8ec1028854943d80acb4b4b8",
"area_id": null,
"name": "Pergola Roof"
},
{
- "id": "e9ae046b857dcfb6af0ccc9dc0cd0342",
+ "id": "40c98dc7c0157b7dde6b4b4fa063b8ca",
"area_id": null,
"name": "Date"
},
{
- "id": "71bb66585ce8dd3f4da7050235ef39d4",
+ "id": "cf85a7db8415915e58da43c462d69002",
"area_id": null,
"name": "Date and Time"
},
{
- "id": "049567b121de1018a27f0f18f638c953",
+ "id": "0ddd1624681cc5919bfdbeb55e800864",
"area_id": null,
"name": "Bed Light"
},
{
- "id": "e2e0c3a8fbf451e1dafdaefe59e0bcb6",
+ "id": "8e54d5e186357e7b8adc5122a791619a",
"area_id": null,
"name": "Ceiling Lights"
},
{
- "id": "f838ae3c5527f7db3ae6dd9af1752334",
+ "id": "1886460066d589499d4182a5b45e84f5",
"area_id": null,
"name": "Kitchen Lights"
},
{
- "id": "5f65fe755b2bb7e35b7a07b176fd7dcb",
+ "id": "6093410db516b385aa1436573da46f77",
"area_id": null,
"name": "Office RGBW Lights"
},
{
- "id": "36086faa0ff0d4232ebbe0865d113374",
+ "id": "7a83cb511b02f2f1d0268b9f812e5e73",
"area_id": null,
"name": "Living Room RGBWW Lights"
},
{
- "id": "03eedae0814b3e66612e163cbaf19af8",
+ "id": "819228fc4201ea4b70283a57975e6e80",
"area_id": null,
"name": "Entrance Color + White Lights"
},
{
- "id": "868235a056deb76c060b4f74969bbbf4",
+ "id": "92e093e68d39e13f6fede07a403743ce",
"area_id": null,
"name": "Notifier"
},
{
- "id": "648b537228c2ebdef8a29273ef8671ad",
+ "id": "5ee8e1423827244bdbd0544f5282032c",
"area_id": null,
"name": "volume"
},
{
- "id": "7dfbd77ae4b39653cf6a3eb44c1e12d0",
+ "id": "e44481c528e6c5ce7a3d91f84704b8d1",
"area_id": null,
"name": "PWM 1"
},
{
- "id": "db648141c6a7cd60328d496dfef0a51e",
+ "id": "5128fa189aa813e1bebf9b00ed65c306",
"area_id": null,
"name": "Large Range"
},
{
- "id": "81017c919d04efc215becbf8e790dced",
+ "id": "4ff4968e3164ae74a1d9fcbf36a9eef3",
"area_id": null,
"name": "Small Range"
},
{
- "id": "58768a7b915cd12e5d55e963f9c2a46b",
+ "id": "47b49b13725c1006f87e44ff6428f53f",
"area_id": null,
"name": "Temperature setting"
},
{
- "id": "ef7b6ea296853fd7e1ec062897034862",
+ "id": "b8a6e4972335c21d7621052dd069fed5",
"area_id": null,
"name": "Speed"
},
{
- "id": "b347b9e9065e8b5fe9e0bb3e3858cb39",
+ "id": "aa73f012671c477334864b69b79ee726",
"area_id": null,
"name": "Outside Humidity"
},
{
- "id": "b8e134ffe704bc5371c51f4f204f0199",
+ "id": "36b429ca62ecc499285067801a95a450",
"area_id": null,
"name": "Carbon monoxide"
},
{
- "id": "6825a017272f51b325b16f0ff8193159",
+ "id": "468e6e9a23a2d081a37ad528c1acdb5d",
"area_id": null,
"name": "Carbon dioxide"
},
{
- "id": "d9aa19a6594978d8c41be6a586f6337d",
+ "id": "7929487cb712d773e6cece3119d54632",
"area_id": null,
"name": "Power consumption"
},
{
- "id": "46caf32beb6d11c2e3cd2faf13a05aa1",
+ "id": "62daf1a9d71fc9d9579e661ff7f4b160",
"area_id": null,
"name": "Total energy 1"
},
{
- "id": "cbc53fe988854bf2b07d1785a5a29613",
+ "id": "12107b6d5dea0a941d72b4fc482eeaff",
"area_id": null,
"name": "Total energy 2"
},
{
- "id": "7b659143175b97f82c63815dde375f87",
+ "id": "dfdbfd602df8b459a370c929206c8bbb",
"area_id": null,
"name": "Total gas 1"
},
{
- "id": "d216e0d104c7fa1746fbc1674c6298fa",
+ "id": "18d0f0b1d479074511b9eb6718bbdff9",
"area_id": null,
"name": "Total gas 2"
},
{
- "id": "41af9dc13f688a3e6e66c317c0cfd700",
+ "id": "842aad627d7cdc9f66e32e60090212a6",
"area_id": null,
"name": "Thermostat"
},
{
- "id": "01895fc0235c71a6859bc14519d193d0",
+ "id": "ac0ae15a92c89ca1a494eee128bf2881",
"area_id": null,
"name": "Decorative Lights"
},
{
- "id": "684b7e0cd0d9e4c98aa1debd4b5dd0b5",
+ "id": "b1545fbbeca14c284393debbbc771e94",
"area_id": null,
"name": "AC"
},
{
- "id": "1b27f822648b2983c0b696445c1b3783",
+ "id": "51bb841e1f14d69c5efce4a2941277db",
"area_id": null,
"name": "Text"
},
{
- "id": "995f62ae7fedbc891b66f4ec851851a6",
+ "id": "79b793feaa0e16c8e3d6cb0be88e3563",
"area_id": null,
"name": "Password"
},
{
- "id": "64f0f4a67ec40783ee16c88f24ef8249",
+ "id": "f7d4a7073eef079dc47da7137e7dd9da",
"area_id": null,
"name": "Text with 1 to 5 characters"
},
{
- "id": "7bbcfef8d30c286be7387a414ed13b11",
+ "id": "30c3c3e7354ce1dbec7a6b2f20533059",
"area_id": null,
"name": "Text with only lower case characters"
},
{
- "id": "4ff5ed2327318665efe52a478842be9b",
+ "id": "52dca23c9108bef6fd2457a7f233846f",
"area_id": null,
"name": "Time"
},
{
- "id": "494993e6bbf958b00edb35d6adfce633",
+ "id": "c2c50216f8278849f7bc79730a1756e5",
"area_id": null,
"name": "Demo Update No Install"
},
{
- "id": "d46b83a6199b02f374ca9ffd0647f655",
+ "id": "fd35fbf460eb37a34440d1ea5dc00dee",
"area_id": null,
"name": "Demo No Update"
},
{
- "id": "1b146b3b1c70b8c2669d2a98ad59f051",
+ "id": "ade7ec8c284365ab32c48cf3f456bc31",
"area_id": null,
"name": "Demo add-on"
},
{
- "id": "ad8c1b782c5863e5beb4cdf7853f3eeb",
+ "id": "9e67d30e6912dc0c84f25cdd39d39b91",
"area_id": null,
"name": "Demo Living Room Bulb Update"
},
{
- "id": "3764c45ebf36b8793f129550e25ebb6f",
+ "id": "5a64169cd4f1bbe3109f2c075c5df686",
"area_id": null,
"name": "Demo Update with Progress"
},
{
- "id": "2158431ce616a12e6696c006d7273666",
+ "id": "29a1c0a8860dd896c3738444523e5c5e",
"area_id": null,
"name": "Demo Update with Decimal Progress"
},
{
- "id": "9e36a75cd735fa136ed441a64ae97f5b",
+ "id": "16a220034976bd546dbeec4537cb185f",
"area_id": null,
"name": "Demo vacuum 0 ground floor"
},
{
- "id": "36a7c0b269c7ab653498d2cfda10db7d",
+ "id": "b5f6ce92dffbd7ea527d486a906274cf",
"area_id": null,
"name": "Demo vacuum 1 first floor"
},
{
- "id": "41596dac04dad3a9f490e199da46d15a",
+ "id": "8fdd09d86a5afadf92664fec5cb7674a",
"area_id": null,
"name": "Demo vacuum 2 second floor"
},
{
- "id": "374439fd7ff062abba569427d5074c38",
+ "id": "8f74b2893c2c0f39be3ded258fec8123",
"area_id": null,
"name": "Demo vacuum 3 third floor"
},
{
- "id": "f95a26b1d0212612a2a7fe60498f8f67",
+ "id": "0963ec135ac366cfa49cde5ae1825b2d",
"area_id": null,
"name": "Demo vacuum 4 fourth floor"
},
{
- "id": "c6fd9046352e4a72fa9e08cf71caae18",
+ "id": "737bd08b0a954fbe4a2d8c0d006708e1",
"area_id": null,
"name": "Front Garden"
},
{
- "id": "a35f6c582851598bf262acd524f80da0",
+ "id": "75eb3e661e401cfa340ffe59e2166e14",
"area_id": null,
"name": "Orchard"
},
{
- "id": "9e83706e6785a1085738df87260c1f1a",
+ "id": "735d5d94311e3fbfb8b19135f8cfa3ad",
"area_id": null,
"name": "Back Garden"
},
{
- "id": "c014ea79bd08d59b6a72cc6c791cec9d",
+ "id": "00882bfe8abb6239f456c82bb12339b1",
"area_id": null,
"name": "Trees"
+ },
+ {
+ "id": "0e36c445cfab64d2f73a0e149790b716",
+ "area_id": null,
+ "name": "Google Translate en com"
+ },
+ {
+ "id": "dd1fc1a8b955673a16ea8d3efa1adfe4",
+ "area_id": null,
+ "name": "Forecast"
+ },
+ {
+ "id": "1081ed6e901efaca4514d148e6fe187d",
+ "area_id": null,
+ "name": "Backup"
}
],
"entities": [
@@ -351,8 +363,8 @@
},
{
"entity_id": "binary_sensor.basement_floor_wet",
- "device_id": "2ec833737b627d775722879de4fcfba1",
- "area_id": "living_room",
+ "device_id": "e29b44b4f0268dd69b5c576e5b0d8604",
+ "area_id": null,
"name": null,
"original_name": null,
"original_device_class": null,
@@ -361,7 +373,7 @@
},
{
"entity_id": "binary_sensor.movement_backyard",
- "device_id": "9d46f32a54020b501a53851f9f3327f1",
+ "device_id": "715267e1932503f69a7cf98760381723",
"area_id": null,
"name": null,
"original_name": null,
@@ -371,7 +383,7 @@
},
{
"entity_id": "binary_sensor.outside_temperature_battery_charging",
- "device_id": "9fc4cbfbf5305340d7fd87034dc17f9e",
+ "device_id": "12992da36230b887d704adef59daecf7",
"area_id": null,
"name": null,
"original_name": "Battery Charging",
@@ -381,8 +393,8 @@
},
{
"entity_id": "climate.heatpump",
- "device_id": "8a84afd34a4001c67bdab5c455e79077",
- "area_id": null,
+ "device_id": "b39ea500b282b16f384c208e39235f41",
+ "area_id": "living_room",
"name": null,
"original_name": null,
"original_device_class": null,
@@ -391,7 +403,7 @@
},
{
"entity_id": "climate.hvac",
- "device_id": "e70d2d25aba01c0b18687fa4029d4434",
+ "device_id": "c90c8f080bcea0227f67ffa0c7bcbdf8",
"area_id": null,
"name": null,
"original_name": null,
@@ -401,8 +413,8 @@
},
{
"entity_id": "climate.ecobee",
- "device_id": "49de48e2e716ee64a39aa650a4e77385",
- "area_id": "living_room",
+ "device_id": "e9f4028288367ff1173fab481d8016fd",
+ "area_id": null,
"name": null,
"original_name": null,
"original_device_class": null,
@@ -411,7 +423,7 @@
},
{
"entity_id": "cover.kitchen_window",
- "device_id": "c1211266a8d4123303b89953992dd589",
+ "device_id": "b8d215b824f80d9cc24ceb0e262b8d11",
"area_id": null,
"name": null,
"original_name": null,
@@ -421,7 +433,7 @@
},
{
"entity_id": "cover.hall_window",
- "device_id": "30bacd9554f761a26c17e8831a29ebd4",
+ "device_id": "6a690f56c69b29c98f59712e5f096d20",
"area_id": null,
"name": null,
"original_name": null,
@@ -431,8 +443,8 @@
},
{
"entity_id": "cover.living_room_window",
- "device_id": "8d3d0ba2ad95dccaff8fd291a97efc93",
- "area_id": "living_room",
+ "device_id": "83a4887330f7eecc3d8ba0d5784f48f7",
+ "area_id": null,
"name": null,
"original_name": null,
"original_device_class": null,
@@ -441,7 +453,7 @@
},
{
"entity_id": "cover.garage_door",
- "device_id": "27fb91b71765f7572821547aca0cb7c4",
+ "device_id": "4f5cf01ee3ad1ceffe4bdcc124ee478b",
"area_id": null,
"name": null,
"original_name": null,
@@ -451,7 +463,7 @@
},
{
"entity_id": "cover.pergola_roof",
- "device_id": "74c07d6fb548627014cefdb4fd5d9da4",
+ "device_id": "94bf640e8ec1028854943d80acb4b4b8",
"area_id": null,
"name": null,
"original_name": null,
@@ -472,7 +484,7 @@
{
"entity_id": "fan.ceiling_fan",
"device_id": null,
- "area_id": "bedroom",
+ "area_id": null,
"name": null,
"original_name": "Ceiling Fan",
"original_device_class": null,
@@ -511,8 +523,8 @@
},
{
"entity_id": "light.bed_light",
- "device_id": "049567b121de1018a27f0f18f638c953",
- "area_id": "bedroom",
+ "device_id": "0ddd1624681cc5919bfdbeb55e800864",
+ "area_id": "living_room",
"name": null,
"original_name": null,
"original_device_class": null,
@@ -521,8 +533,8 @@
},
{
"entity_id": "light.ceiling_lights",
- "device_id": "e2e0c3a8fbf451e1dafdaefe59e0bcb6",
- "area_id": "living_room",
+ "device_id": "8e54d5e186357e7b8adc5122a791619a",
+ "area_id": "bedroom",
"name": null,
"original_name": null,
"original_device_class": null,
@@ -531,8 +543,8 @@
},
{
"entity_id": "light.kitchen_lights",
- "device_id": "f838ae3c5527f7db3ae6dd9af1752334",
- "area_id": "kitchen",
+ "device_id": "1886460066d589499d4182a5b45e84f5",
+ "area_id": "front_door",
"name": null,
"original_name": null,
"original_device_class": null,
@@ -541,7 +553,7 @@
},
{
"entity_id": "light.office_rgbw_lights",
- "device_id": "5f65fe755b2bb7e35b7a07b176fd7dcb",
+ "device_id": "6093410db516b385aa1436573da46f77",
"area_id": null,
"name": null,
"original_name": null,
@@ -551,8 +563,8 @@
},
{
"entity_id": "light.living_room_rgbww_lights",
- "device_id": "36086faa0ff0d4232ebbe0865d113374",
- "area_id": "living_room",
+ "device_id": "7a83cb511b02f2f1d0268b9f812e5e73",
+ "area_id": null,
"name": null,
"original_name": null,
"original_device_class": null,
@@ -561,7 +573,7 @@
},
{
"entity_id": "light.entrance_color_white_lights",
- "device_id": "03eedae0814b3e66612e163cbaf19af8",
+ "device_id": "819228fc4201ea4b70283a57975e6e80",
"area_id": null,
"name": null,
"original_name": null,
@@ -571,8 +583,8 @@
},
{
"entity_id": "sensor.outside_temperature",
- "device_id": "9fc4cbfbf5305340d7fd87034dc17f9e",
- "area_id": "kitchen",
+ "device_id": "12992da36230b887d704adef59daecf7",
+ "area_id": null,
"name": null,
"original_name": null,
"original_device_class": null,
@@ -581,7 +593,7 @@
},
{
"entity_id": "sensor.outside_temperature_battery",
- "device_id": "9fc4cbfbf5305340d7fd87034dc17f9e",
+ "device_id": "12992da36230b887d704adef59daecf7",
"area_id": null,
"name": null,
"original_name": "Battery",
@@ -591,8 +603,8 @@
},
{
"entity_id": "switch.decorative_lights",
- "device_id": "01895fc0235c71a6859bc14519d193d0",
- "area_id": "kitchen",
+ "device_id": "ac0ae15a92c89ca1a494eee128bf2881",
+ "area_id": null,
"name": null,
"original_name": null,
"original_device_class": null,
@@ -601,7 +613,7 @@
},
{
"entity_id": "switch.ac",
- "device_id": "684b7e0cd0d9e4c98aa1debd4b5dd0b5",
+ "device_id": "b1545fbbeca14c284393debbbc771e94",
"area_id": null,
"name": null,
"original_name": null,
@@ -611,7 +623,7 @@
},
{
"entity_id": "valve.front_garden",
- "device_id": "c6fd9046352e4a72fa9e08cf71caae18",
+ "device_id": "737bd08b0a954fbe4a2d8c0d006708e1",
"area_id": null,
"name": null,
"original_name": null,
@@ -621,7 +633,7 @@
},
{
"entity_id": "valve.orchard",
- "device_id": "a35f6c582851598bf262acd524f80da0",
+ "device_id": "75eb3e661e401cfa340ffe59e2166e14",
"area_id": null,
"name": null,
"original_name": null,
@@ -631,7 +643,7 @@
},
{
"entity_id": "valve.back_garden",
- "device_id": "9e83706e6785a1085738df87260c1f1a",
+ "device_id": "735d5d94311e3fbfb8b19135f8cfa3ad",
"area_id": null,
"name": null,
"original_name": null,
@@ -641,7 +653,7 @@
},
{
"entity_id": "valve.trees",
- "device_id": "c014ea79bd08d59b6a72cc6c791cec9d",
+ "device_id": "00882bfe8abb6239f456c82bb12339b1",
"area_id": null,
"name": null,
"original_name": null,
@@ -956,7 +968,7 @@
},
"light.bed_light": {
"entity_id": "light.bed_light",
- "state": "on",
+ "state": "off",
"attributes": {
"min_color_temp_kelvin": 2000,
"max_color_temp_kelvin": 6535,
@@ -968,23 +980,13 @@
"color_temp",
"hs"
],
- "effect": "rainbow",
- "color_mode": "color_temp",
- "brightness": 40,
- "color_temp_kelvin": 2631,
- "hs_color": [
- 28.55,
- 67.974
- ],
- "rgb_color": [
- 255,
- 164,
- 82
- ],
- "xy_color": [
- 0.532,
- 0.388
- ],
+ "effect": null,
+ "color_mode": null,
+ "brightness": null,
+ "color_temp_kelvin": null,
+ "hs_color": null,
+ "rgb_color": null,
+ "xy_color": null,
"friendly_name": "Bed Light",
"supported_features": 4
}
@@ -1011,7 +1013,7 @@
},
"light.kitchen_lights": {
"entity_id": "light.kitchen_lights",
- "state": "off",
+ "state": "on",
"attributes": {
"min_color_temp_kelvin": 2000,
"max_color_temp_kelvin": 6535,
@@ -1019,12 +1021,22 @@
"color_temp",
"hs"
],
- "color_mode": null,
- "brightness": null,
+ "color_mode": "hs",
+ "brightness": 180,
"color_temp_kelvin": null,
- "hs_color": null,
- "rgb_color": null,
- "xy_color": null,
+ "hs_color": [
+ 345,
+ 75
+ ],
+ "rgb_color": [
+ 255,
+ 64,
+ 112
+ ],
+ "xy_color": [
+ 0.588,
+ 0.274
+ ],
"friendly_name": "Kitchen Lights",
"supported_features": 0
}
@@ -1167,12 +1179,12 @@
"media_content_type": "movie",
"media_duration": 300,
"media_position": 45,
- "media_position_updated_at": "2026-09-02T21:10:14.990453+00:00",
+ "media_position_updated_at": "2026-09-03T03:32:36.600891+00:00",
"media_title": "♥♥ The Best Fireplace Video (3 hours)",
"app_name": "YouTube",
"sound_mode": "Music",
"shuffle": false,
- "entity_picture": "/api/media_player_proxy/media_player.living_room?token=68050ee39d0e1e1168de2036e077583fc303f6893823c3c7c9e80a0f8ba9ecca&cache=bc2ffb49c4f67034",
+ "entity_picture": "/api/media_player_proxy/media_player.living_room?token=f9ceafdc316b6c1a4de03bd06ba1e730bec13106f298653d299ae23c203be1e0&cache=bc2ffb49c4f67034",
"friendly_name": "Living Room",
"supported_features": 119695
}
@@ -1191,12 +1203,12 @@
"media_content_type": "movie",
"media_duration": 360000,
"media_position": 54000,
- "media_position_updated_at": "2026-09-02T21:10:14.990469+00:00",
+ "media_position_updated_at": "2026-09-03T03:32:36.600909+00:00",
"media_title": "Epic sax guy 10 hours",
"app_name": "YouTube",
"sound_mode": "Music",
"shuffle": false,
- "entity_picture": "/api/media_player_proxy/media_player.bedroom?token=4706a0a13a59bd98e8781ebf36de566cfbe18415ac7afc04624e4a1c1cbd6014&cache=e4513ed94ec89151",
+ "entity_picture": "/api/media_player_proxy/media_player.bedroom?token=f0db49be001292eded438c2e0e410feeac3be0b64fb29c1ce2a0b9e59fb9bdf0&cache=e4513ed94ec89151",
"friendly_name": "Bedroom",
"supported_features": 119695
}
@@ -1222,7 +1234,7 @@
"sound_mode": "Music",
"shuffle": false,
"repeat": "off",
- "entity_picture": "/api/media_player_proxy/media_player.walkman?token=770fa76c148c7aaaaf237144584a1227747d97cf3e5a4ed80fe3c269d1408c9a&cache=62c0c516acbc53a9",
+ "entity_picture": "/api/media_player_proxy/media_player.walkman?token=5db0375882ed05f83e7934617a37efeef038c8e27f8f75b27ac007c5bb4fa066&cache=62c0c516acbc53a9",
"friendly_name": "Walkman",
"supported_features": 914877
}
@@ -1248,7 +1260,7 @@
"sound_mode": "Music",
"shuffle": false,
"repeat": "off",
- "entity_picture": "/api/media_player_proxy/media_player.kitchen?token=100a887c23350357c9b7a2a995a1e6385020d29717538e8511a3749117530f13&cache=62c0c516acbc53a9",
+ "entity_picture": "/api/media_player_proxy/media_player.kitchen?token=8d01951f9793bc4e3dd8c88af1b3ea5d3ca02a6ed7b41e919482c8584d379980&cache=62c0c516acbc53a9",
"friendly_name": "Kitchen",
"supported_features": 914877
}
@@ -1279,7 +1291,7 @@
"sound_mode": "Music",
"shuffle": false,
"device_class": "tv",
- "entity_picture": "/api/media_player_proxy/media_player.lounge_room?token=951ba5642d74007119ada2c8a4cf7a28e20bdfa5e6189621595ddb0ab123709c&cache=cb9d84451faf9351",
+ "entity_picture": "/api/media_player_proxy/media_player.lounge_room?token=17c84f965e1ce6864da436598edc5086cfe5fb8e555328200d811debbe52987a&cache=cb9d84451faf9351",
"friendly_name": "Lounge room",
"supported_features": 121265
}
@@ -1401,12 +1413,11 @@
},
"scene.bedtime": {
"entity_id": "scene.bedtime",
- "state": "2026-09-02T21:17:15.287139+00:00",
+ "state": "2026-09-03T03:50:51.101424+00:00",
"attributes": {
"entity_id": [
"light.bed_light",
"light.ceiling_lights",
- "light.kitchen_lights",
"lock.front_door"
],
"id": "threews_bedtime",
@@ -1421,10 +1432,12 @@
"light.bed_light",
"light.ceiling_lights",
"light.kitchen_lights",
- "lock.front_door",
- "climate.ecobee"
+ "light.office_rgbw_lights",
+ "light.living_room_rgbww_lights",
+ "light.entrance_color_white_lights",
+ "lock.front_door"
],
- "id": "threews_away",
+ "id": "threews_away_mode",
"friendly_name": "Away Mode"
}
}
diff --git a/pages/home-scene.html b/pages/home-scene.html
index a777b49a0..146f659eb 100644
--- a/pages/home-scene.html
+++ b/pages/home-scene.html
@@ -14,7 +14,7 @@
<link rel="stylesheet" href="/home-scene.css" />
</head>
<body>
- <div id="nav-root"></div>
+ <div id="nav-container"></div>
<div class="hs-shell" id="hs-shell">
<div class="hs-bar">
diff --git a/scripts/check-home-voice.mjs b/scripts/check-home-voice.mjs
index 9dc0158e5..e8bbe8832 100644
--- a/scripts/check-home-voice.mjs
+++ b/scripts/check-home-voice.mjs
@@ -54,6 +54,41 @@ const AUDIO = join(OUT, 'audio');
mkdirSync(AUDIO, { recursive: true });
+/**
+ * The QA account from .env, used only so the run is not throttled to the
+ * anonymous per-IP buckets (10 TTS and 15 ASR per hour, which one full run
+ * spends). The lanes themselves are the same lanes either way. Without the
+ * credentials the run still works; it just cannot repeat as often.
+ */
+let SESSION_COOKIE = null;
+
+async function signIn() {
+ const email = process.env.AUDIT_EMAIL;
+ const password = process.env.AUDIT_PASSWORD;
+ if (!email || !password) {
+ console.log('[auth] AUDIT_EMAIL / AUDIT_PASSWORD not set: running against the anonymous rate limits.');
+ return;
+ }
+ const upstream = process.env.DEV_API_PROXY || 'https://three.ws';
+ const res = await fetch(`${upstream}/api/auth/login`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ email, password }),
+ });
+ if (!res.ok) {
+ console.log(`[auth] login failed (${res.status}): running against the anonymous rate limits.`);
+ return;
+ }
+ const raw = res.headers.getSetCookie?.() ?? [res.headers.get('set-cookie')].filter(Boolean);
+ const sid = raw.map((c) => c.split(';')[0]).find((c) => c.startsWith('__Host-sid='));
+ if (!sid) {
+ console.log('[auth] no session cookie returned: running against the anonymous rate limits.');
+ return;
+ }
+ SESSION_COOKIE = sid;
+ console.log('[auth] signed in as the QA account.');
+}
+
const results = [];
function check(name, pass, detail) {
results.push({ name, pass: !!pass, detail });
@@ -97,7 +132,7 @@ async function ensureClips() {
async function synthesize(text) {
const res = await fetch(`${BASE}/api/tts/speak`, {
method: 'POST',
- headers: { 'content-type': 'application/json' },
+ headers: { 'content-type': 'application/json', ...(SESSION_COOKIE ? { cookie: SESSION_COOKIE } : {}) },
body: JSON.stringify({ text, format: 'wav' }),
});
if (!res.ok) throw new Error(`tts ${res.status}: ${await res.text()}`);
@@ -185,7 +220,13 @@ async function launch(audioPath, { loopAudio = true } = {}) {
// how long the download took.
if (audioPath) chromiumArgs.push(`--use-file-for-fake-audio-capture=${audioPath}${loopAudio ? '' : '%noloop'}`);
const browser = await chromium.launch({ headless: !HEADED, args: chromiumArgs });
- const context = await browser.newContext({ permissions: ['microphone'] });
+ const context = await browser.newContext({
+ permissions: ['microphone'],
+ // The session travels as a header rather than a cookie because the cookie is
+ // __Host- prefixed and Secure, and the dev origin is plain http on localhost.
+ // The dev server forwards it upstream unchanged either way.
+ extraHTTPHeaders: SESSION_COOKIE ? { cookie: SESSION_COOKIE } : {},
+ });
const page = await context.newPage();
const requests = [];
page.on('request', (r) => requests.push({ url: r.url(), at: Date.now() }));
@@ -347,7 +388,14 @@ async function scenarioBargeIn() {
'the front door is locked, and the garage is closed. Nothing else has changed since this morning.',
);
});
- await page.waitForFunction(() => window.homeVoice.loop.state === 'speaking', null, { timeout: 45000 });
+ await page
+ .waitForFunction(
+ () => window.homeVoice.loop.state === 'speaking' || window.__hv.events.some((e) => e.type === 'tts-failed'),
+ null,
+ { timeout: 45000 },
+ );
+ const ttsFailure = (await events(page)).find((e) => e.type === 'tts-failed');
+ if (ttsFailure) throw new Error(`the agent could not speak, so barge-in cannot be measured: ${ttsFailure.message}`);
await waitForEvent(page, 'barge-in', 45000);
const all = await events(page);
const stop = all.find((e) => e.type === 'playback-stopped' && e.reason === 'barge-in');
@@ -590,6 +638,7 @@ async function main() {
console.error(`No dev server at ${BASE}. Start one with: npx vite --port ${PORT}`);
process.exit(2);
}
+ await signIn();
await ensureClips();
const measured = {};
diff --git a/solana-mobile/scripts/lib/hand.mjs b/solana-mobile/scripts/lib/hand.mjs
new file mode 100644
index 000000000..61643cbea
--- /dev/null
+++ b/solana-mobile/scripts/lib/hand.mjs
@@ -0,0 +1,425 @@
+/**
+ * A visible thumb that drives a page the way a person does.
+ *
+ * The recordings this backs are frame-stepped (see seeker-panel.mjs), so every
+ * pixel of motion is set from here, one output frame at a time: nothing is left
+ * to a CSS transition or to the compositor, because those run on the wall clock
+ * and the wall clock is not the video's clock. The payoff is that a rerun of
+ * the same tour produces the same frames, and a 40 second video does not need
+ * 40 seconds of a perfectly behaved live site.
+ *
+ * The thumb itself is a touch indicator, the same thing Android's "Show taps"
+ * developer option draws over a real screen recording. It is the only pixel
+ * this file adds to the page. Every tap, keystroke, and gesture underneath it
+ * is dispatched as real input to the real page: the indicator reports the
+ * interaction, it never stands in for one.
+ *
+ * Scrolling is the one motion driven from script rather than from the input
+ * pipeline. Chromium's fling physics run on the wall clock, which would land a
+ * different scroll offset on every stepped frame; `window.scrollTo` per frame
+ * with a drag-then-momentum profile puts the same pixels on screen every run.
+ */
+
+export const TIP_PX = 56;
+
+/** Installed into every document (page load and client-side navigation alike). */
+export function installHand() {
+ const ID = '__seeker_hand';
+ const ensure = () => {
+ const host = document.body || document.documentElement;
+ if (!host) return null;
+ let root = document.getElementById(ID);
+ if (root && root.isConnected) return root;
+ root = document.createElement('div');
+ root.id = ID;
+ root.setAttribute('aria-hidden', 'true');
+ root.style.cssText = 'position:fixed;left:0;top:0;width:0;height:0;z-index:2147483647;pointer-events:none;';
+ const ripple = document.createElement('div');
+ ripple.style.cssText = 'position:absolute;border-radius:50%;border:2px solid rgba(255,255,255,0.85);'
+ + 'transform:translate(-50%,-50%);opacity:0;will-change:transform,opacity;';
+ const tip = document.createElement('div');
+ tip.style.cssText = 'position:absolute;width:56px;height:56px;border-radius:50%;opacity:0;'
+ + 'background:radial-gradient(circle at 36% 32%, rgba(255,255,255,0.95), rgba(255,255,255,0.5) 40%,'
+ + ' rgba(255,255,255,0.16) 70%, rgba(255,255,255,0) 74%);'
+ + 'box-shadow:0 0 0 1.5px rgba(255,255,255,0.5), 0 10px 26px rgba(0,0,0,0.5);'
+ + 'will-change:transform,opacity;';
+ root.append(ripple, tip);
+ host.appendChild(root);
+ return root;
+ };
+
+ window.__seekerHand = {
+ ensure,
+ set(s) {
+ const root = ensure();
+ if (!root) return;
+ const [ripple, tip] = root.children;
+ tip.style.left = `${s.x}px`;
+ tip.style.top = `${s.y}px`;
+ tip.style.opacity = String(s.opacity);
+ tip.style.transform = `translate(-50%,-50%) scale(${s.scale})`;
+ ripple.style.left = `${s.x}px`;
+ ripple.style.top = `${s.y}px`;
+ ripple.style.width = `${s.rippleR * 2}px`;
+ ripple.style.height = `${s.rippleR * 2}px`;
+ ripple.style.opacity = String(s.rippleO);
+ },
+ };
+
+ if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', ensure, { once: true });
+ else ensure();
+}
+
+/* Deterministic jitter. A tour that lands on the exact pixel centre of every
+ button twice in a row reads as a macro, and a tour seeded from Math.random
+ cannot be re-recorded identically. Seeded noise gets both. */
+function mulberry32(seed) {
+ let a = seed >>> 0;
+ return () => {
+ a |= 0; a = (a + 0x6D2B79F5) | 0;
+ let t = Math.imul(a ^ (a >>> 15), 1 | a);
+ t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+ };
+}
+
+const easeInOutCubic = (x) => (x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2);
+const easeOutCubic = (x) => 1 - Math.pow(1 - x, 3);
+const easeOutQuint = (x) => 1 - Math.pow(1 - x, 5);
+const easeInQuad = (x) => x * x;
+
+export class Hand {
+ /**
+ * @param {import('playwright').Page} page
+ * @param {{ fps: number, shoot: () => Promise<void>, css: {width:number,height:number}, seed?: number, log?: (...a:any)=>void }} opts
+ */
+ constructor(page, { fps, shoot, css, seed = 7, log = () => {} }) {
+ this.page = page;
+ this.fps = fps;
+ this.shoot = shoot;
+ this.css = css;
+ this.log = log;
+ this.rand = mulberry32(seed);
+ this.state = { x: css.width / 2, y: css.height + 80, opacity: 0, scale: 1, rippleR: 0, rippleO: 0 };
+ this.clock = 0;
+ this.arcSign = 1;
+ }
+
+ frames(ms) { return Math.max(1, Math.round((ms / 1000) * this.fps)); }
+ jitter(px) { return (this.rand() * 2 - 1) * px; }
+
+ /** Re-install the indicator after a navigation and put it back where it was. */
+ async ready() {
+ await this.page.evaluate(installHand);
+ await this.paint();
+ }
+
+ async paint() {
+ await this.page.evaluate((s) => window.__seekerHand?.set(s), this.state);
+ }
+
+ /** One captured frame at the current state, with a breath of idle drift. */
+ async frame({ drift = true } = {}) {
+ this.clock += 1;
+ if (drift && this.state.opacity > 0) {
+ const t = this.clock / this.fps;
+ this.state.x += Math.sin(t * 1.7) * 0.13;
+ this.state.y += Math.cos(t * 1.3) * 0.11;
+ }
+ await this.paint();
+ await this.shoot();
+ }
+
+ async hold(ms, opts) {
+ for (let i = 0; i < this.frames(ms); i += 1) await this.frame(opts);
+ }
+
+ /**
+ * Travel to a point. Real thumbs do not move in straight lines or at a
+ * constant speed: the path bows, the hand accelerates away and decelerates
+ * into the target, then rings once before it settles.
+ */
+ async moveTo(x, y, { ms } = {}) {
+ const from = { x: this.state.x, y: this.state.y };
+ const entering = this.state.opacity < 0.05;
+ if (entering) {
+ /* Coming back on screen: start from just below the bottom edge, the
+ way a thumb re-enters the frame on a phone. */
+ from.x = x + this.jitter(30);
+ from.y = this.css.height + 70;
+ this.state.x = from.x;
+ this.state.y = from.y;
+ }
+ const dist = Math.hypot(x - from.x, y - from.y);
+ const dur = ms ?? Math.min(900, 210 + dist * 1.15);
+ const total = this.frames(dur);
+ /* Bow the path, alternating side to side so repeated trips down a list
+ do not trace the same line twice. */
+ const bow = Math.min(46, dist * 0.14) * this.arcSign;
+ this.arcSign *= -1;
+ const mid = {
+ x: (from.x + x) / 2 + (y - from.y) / (dist || 1) * bow,
+ y: (from.y + y) / 2 - (x - from.x) / (dist || 1) * bow,
+ };
+ for (let i = 1; i <= total; i += 1) {
+ const t = easeInOutCubic(i / total);
+ const u = 1 - t;
+ this.state.x = u * u * from.x + 2 * u * t * mid.x + t * t * x;
+ this.state.y = u * u * from.y + 2 * u * t * mid.y + t * t * y;
+ if (entering) this.state.opacity = Math.min(1, easeOutCubic(Math.min(1, (i / total) * 2.2)));
+ await this.frame({ drift: false });
+ }
+ /* Damped settle, so the hand arrives instead of snapping. */
+ if (dist > 60) {
+ const dirX = (x - from.x) / (dist || 1);
+ const dirY = (y - from.y) / (dist || 1);
+ const settle = this.frames(160);
+ for (let i = 1; i <= settle; i += 1) {
+ const k = Math.sin((i / settle) * Math.PI * 1.5) * 2.6 * (1 - i / settle);
+ this.state.x = x + dirX * k;
+ this.state.y = y + dirY * k;
+ await this.frame({ drift: false });
+ }
+ }
+ this.state.x = x;
+ this.state.y = y;
+ this.state.opacity = 1;
+ }
+
+ /** Lift off the glass: used while typing, since the keyboard is the system's. */
+ async lift({ ms = 260 } = {}) {
+ if (this.state.opacity < 0.05) return;
+ const total = this.frames(ms);
+ const y0 = this.state.y;
+ for (let i = 1; i <= total; i += 1) {
+ const t = easeInQuad(i / total);
+ this.state.opacity = 1 - t;
+ this.state.y = y0 + t * 46;
+ this.state.scale = 1 - t * 0.12;
+ await this.frame({ drift: false });
+ }
+ this.state.opacity = 0;
+ this.state.scale = 1;
+ }
+
+ /** Touch down, fire the real input, and let the contact ring bloom away. */
+ async tapAt(x, y, { press = 90, bloom = 300, after = 260 } = {}) {
+ const down = this.frames(press);
+ for (let i = 1; i <= down; i += 1) {
+ const t = i / down;
+ this.state.scale = 1 - 0.2 * t;
+ this.state.rippleR = 20 + 8 * t;
+ this.state.rippleO = 0.5 * t;
+ await this.frame({ drift: false });
+ }
+ await this.page.touchscreen.tap(x, y);
+ const up = this.frames(bloom);
+ for (let i = 1; i <= up; i += 1) {
+ const t = easeOutQuint(i / up);
+ this.state.scale = 0.8 + 0.2 * t;
+ this.state.rippleR = 28 + 44 * t;
+ this.state.rippleO = 0.5 * (1 - t);
+ await this.frame({ drift: false });
+ }
+ this.state.scale = 1;
+ this.state.rippleO = 0;
+ this.state.rippleR = 0;
+ if (after) await this.hold(after);
+ }
+
+ /** Where on an element a thumb would actually land: near the middle, not on it. */
+ async pointOn(selector, { bring = true } = {}) {
+ const locator = this.page.locator(selector).first();
+ await locator.waitFor({ state: 'visible', timeout: 20_000 });
+ if (bring) await this.bringIntoView(selector);
+ const box = await locator.boundingBox();
+ if (!box) throw new Error(`${selector} has no box to tap`);
+ return {
+ x: box.x + box.width / 2 + this.jitter(Math.min(box.width * 0.18, 22)),
+ y: box.y + box.height / 2 + this.jitter(Math.min(box.height * 0.2, 9)),
+ };
+ }
+
+ async tapOn(selector, { expect, expectTimeout = 30_000, hoverMs = 140, after = 320 } = {}) {
+ const { x, y } = await this.pointOn(selector);
+ await this.moveTo(x, y);
+ await this.hold(hoverMs);
+ await this.tapAt(x, y, { after });
+ if (expect) await this.waitFor(expect, { timeout: expectTimeout });
+ }
+
+ /** Tap something only if this build of the page actually renders it. */
+ async tapIfPresent(selector, opts = {}) {
+ const n = await this.page.locator(selector).count();
+ if (!n) return false;
+ if (!(await this.page.locator(selector).first().isVisible())) return false;
+ await this.tapOn(selector, opts);
+ return true;
+ }
+
+ /**
+ * Type into a field: tap it, take the hand off the glass (the keyboard is a
+ * system surface this recording does not draw), then send real keystrokes at
+ * a human cadence, slowing at spaces and punctuation the way people do.
+ */
+ async typeInto(selector, text, { cps = 11, settle = 500 } = {}) {
+ await this.tapOn(selector, { after: 180 });
+ await this.lift();
+ const base = 1000 / cps;
+ for (const ch of text) {
+ await this.page.keyboard.type(ch);
+ let ms = base * (0.72 + this.rand() * 0.7);
+ if (ch === ' ') ms *= 1.35;
+ if (',.!?'.includes(ch)) ms *= 2.1;
+ await this.hold(ms, { drift: false });
+ }
+ await this.hold(settle, { drift: false });
+ }
+
+ /** Current scroll offset and the furthest the document can go. */
+ async scrollState() {
+ return this.page.evaluate(() => ({
+ y: window.scrollY,
+ max: Math.max(0, document.documentElement.scrollHeight - window.innerHeight),
+ }));
+ }
+
+ /**
+ * One thumb flick: the page tracks the finger while it is down, then carries
+ * on and decays after it lifts. Positive dy scrolls further down the page,
+ * which is a finger travelling up the glass.
+ */
+ async flick(dy, { dragMs = 340, glideMs = 620 } = {}) {
+ const { y: y0, max } = await this.scrollState();
+ const target = Math.max(0, Math.min(max, y0 + dy));
+ const delta = target - y0;
+ if (Math.abs(delta) < 2) return target;
+
+ const drag = delta * 0.55;
+ const startY = delta > 0
+ ? this.css.height * (0.68 + this.rand() * 0.06)
+ : this.css.height * (0.3 + this.rand() * 0.06);
+ const startX = this.css.width * 0.5 + this.jitter(46);
+ const endY = Math.max(90, Math.min(this.css.height - 60, startY - drag));
+
+ await this.moveTo(startX, startY);
+ const down = this.frames(70);
+ for (let i = 1; i <= down; i += 1) {
+ this.state.scale = 1 - 0.14 * (i / down);
+ await this.frame({ drift: false });
+ }
+
+ const dragFrames = this.frames(dragMs);
+ for (let i = 1; i <= dragFrames; i += 1) {
+ const t = easeInOutCubic(i / dragFrames);
+ this.state.x = startX + this.jitter(0.4);
+ this.state.y = startY + (endY - startY) * t;
+ await this.page.evaluate((py) => window.scrollTo(0, py), y0 + drag * t);
+ await this.frame({ drift: false });
+ }
+
+ const glideFrames = this.frames(glideMs);
+ const restStart = y0 + drag;
+ for (let i = 1; i <= glideFrames; i += 1) {
+ const t = i / glideFrames;
+ await this.page.evaluate((py) => window.scrollTo(0, py), restStart + (target - restStart) * easeOutQuint(t));
+ /* The hand leaves the glass as the page keeps going. */
+ this.state.opacity = 1 - easeInQuad(Math.min(1, t * 1.6));
+ this.state.y = endY + easeInQuad(t) * 34;
+ this.state.scale = 0.86 + 0.14 * t;
+ await this.frame({ drift: false });
+ }
+ this.state.opacity = 0;
+ this.state.scale = 1;
+ await this.page.evaluate((py) => window.scrollTo(0, py), target);
+ return target;
+ }
+
+ /** A long distance is several flicks with a beat between them, not one glide. */
+ async scrollBy(dy, { chunk = 520, betweenMs = 220 } = {}) {
+ let left = dy;
+ let guard = 0;
+ while (Math.abs(left) > 8 && guard < 12) {
+ const step = Math.sign(left) * Math.min(Math.abs(left), chunk);
+ const before = (await this.scrollState()).y;
+ const after = await this.flick(step);
+ left -= after - before;
+ if (Math.abs(after - before) < 2) break;
+ guard += 1;
+ if (Math.abs(left) > 8) await this.hold(betweenMs);
+ }
+ }
+
+ /** Put an element in the comfortable middle band of the screen. */
+ async bringIntoView(selector, { top = 150, bottom = 190 } = {}) {
+ const box = await this.page.locator(selector).first().boundingBox();
+ if (!box) return;
+ const lo = top;
+ const hi = this.css.height - bottom;
+ if (box.y >= lo && box.y + box.height <= hi) return;
+ const wanted = box.y + box.height / 2 - this.css.height * 0.44;
+ await this.scrollBy(wanted);
+ }
+
+ /**
+ * Drag across an element, for the surfaces that answer a drag rather than a
+ * tap: the 3D viewers. Pointer events are the real ones, so the model turns
+ * because the page turned it.
+ */
+ async dragAcross(selector, { dx = 200, dy = 0, ms = 900 } = {}) {
+ await this.bringIntoView(selector);
+ const box = await this.page.locator(selector).first().boundingBox();
+ if (!box) throw new Error(`${selector} has no box to drag`);
+ const x0 = box.x + box.width * 0.5 - dx / 2;
+ const y0 = box.y + box.height * 0.55 - dy / 2;
+ await this.moveTo(x0, y0);
+ await this.page.mouse.move(x0, y0);
+ await this.page.mouse.down();
+ const down = this.frames(80);
+ for (let i = 1; i <= down; i += 1) {
+ this.state.scale = 1 - 0.16 * (i / down);
+ await this.frame({ drift: false });
+ }
+ const total = this.frames(ms);
+ for (let i = 1; i <= total; i += 1) {
+ const t = easeInOutCubic(i / total);
+ const px = x0 + dx * t;
+ const py = y0 + dy * t;
+ await this.page.mouse.move(px, py);
+ this.state.x = px;
+ this.state.y = py;
+ await this.frame({ drift: false });
+ }
+ await this.page.mouse.up();
+ const up = this.frames(180);
+ for (let i = 1; i <= up; i += 1) {
+ this.state.scale = 0.84 + 0.16 * (i / up);
+ await this.frame({ drift: false });
+ }
+ this.state.scale = 1;
+ }
+
+ /**
+ * Wait on the real page while the recording keeps rolling, sampling one
+ * frame every `everyMs` of wall clock. A build that takes four minutes
+ * becomes a few seconds of honest time-lapse: the progress bar, the status
+ * line, and the elapsed clock are the page's own, at the page's own pace.
+ */
+ async waitFor(condition, { timeout = 60_000, everyMs = 220, note = '' } = {}) {
+ const started = Date.now();
+ const done = typeof condition === 'function'
+ ? () => condition(this.page)
+ : () => this.page.locator(condition).first().isVisible().catch(() => false);
+ if (note) this.log(note);
+ for (;;) {
+ if (await done()) return Date.now() - started;
+ if (Date.now() - started > timeout) {
+ throw new Error(`timed out after ${Math.round((Date.now() - started) / 1000)}s waiting for ${note || condition}`);
+ }
+ await this.frame({ drift: this.state.opacity > 0 });
+ const spent = Date.now() - started;
+ const rest = everyMs - (spent % everyMs);
+ if (rest > 5) await this.page.waitForTimeout(Math.min(rest, everyMs));
+ }
+ }
+}
diff --git a/src/home/api.js b/src/home/api.js
index c2488389c..3b1e264e5 100644
--- a/src/home/api.js
+++ b/src/home/api.js
@@ -72,6 +72,32 @@ export function getHome(id, signal) {
return request(`/api/home/${encodeURIComponent(id)}`, { signal });
}
+/**
+ * Start pairing a home that only exists on a LAN.
+ *
+ * Most Home Assistant installs cannot be reached from the public internet at
+ * all, so for those the house dials out to us instead. This mints the short
+ * code the owner types into the three.ws integration inside their Home
+ * Assistant; the connection row exists from this moment, in `pending`.
+ */
+export function startPairing({ label } = {}) {
+ return request('/api/home/pair', { method: 'POST', body: { label } });
+}
+
+/** A fresh code for a home already waiting, without creating a second home. */
+export function refreshPairing(homeId) {
+ return request('/api/home/pair', { method: 'POST', body: { homeId } });
+}
+
+/**
+ * The countdown and the link state. `relay.online` is read from the relay
+ * itself, so it answers "is the integration in my house running right now"
+ * rather than "did a connection work at some point".
+ */
+export function pairingStatus(homeId, signal) {
+ return request(`/api/home/pair?homeId=${encodeURIComponent(homeId)}`, { signal });
+}
+
/**
* A gated service call. A guarded action answers 409 with `pending`, which the
* caller renders as a question next to the thing it would move. `confirmed` is
diff --git a/src/home/connect.js b/src/home/connect.js
index f41d27f31..f2829c53b 100644
--- a/src/home/connect.js
+++ b/src/home/connect.js
@@ -455,25 +455,20 @@ export function checkReachable(input) {
const raw = String(input || '').trim();
if (!raw) return { ok: true, short: '' };
+ // Parse WITHOUT requireSecure first, then diagnose in order of usefulness.
+ // The order matters more than it looks: the single most common thing a person
+ // pastes is "http://192.168.1.10:8123", which is both plain http AND a LAN
+ // address. Checking the scheme first answers it with "use https", which sends
+ // them off to configure TLS on a machine we still would not be able to reach.
+ // The LAN diagnosis is the true one and the actionable one, so it goes first.
let parsed;
try {
- // requireSecure is the same flag api/home/index.js passes, so the browser
- // and the server agree on what is reachable instead of one of them
- // accepting an address the other will refuse. It exempts loopback, which
- // is how a developer running Home Assistant on this machine still works.
- parsed = normalizeBaseUrl(raw, { requireSecure: true });
+ parsed = normalizeBaseUrl(raw);
} catch (err) {
- const badScheme = /plain http/i.test(err?.message || '');
return {
ok: false,
- short: badScheme ? 'A plain http address cannot be reached from this page.' : 'That is not a web address we can use.',
- notice: badScheme
- ? {
- tone: 'warn',
- title: 'That is a plain http address.',
- body: 'This page is served over https, and a browser will not open an unencrypted connection from it. Use the https address for your house.',
- }
- : { tone: 'error', title: 'That address does not look right.', body: err?.message || 'Use the full https URL of your Home Assistant.' },
+ short: 'That is not a web address we can use.',
+ notice: { tone: 'error', title: 'That address does not look right.', body: err?.message || 'Use the full https URL of your Home Assistant.' },
};
}
@@ -494,6 +489,21 @@ export function checkReachable(input) {
};
}
+ // Past the LAN check, the same rule the server applies with
+ // `requireSecure`: a page on https cannot open a plain-http connection, and
+ // loopback is exempt so a local instance still works in development.
+ if (!parsed.secure && !parsed.loopback) {
+ return {
+ ok: false,
+ short: 'A plain http address cannot be reached from this page.',
+ notice: {
+ tone: 'warn',
+ title: 'That is a plain http address.',
+ body: 'This page is served over https, and a browser will not open an unencrypted connection from it. Use the https address for your house.',
+ },
+ };
+ }
+
return { ok: true, short: '' };
}
diff --git a/src/home/home.css b/src/home/home.css
index 315bf8e32..6320c61ae 100644
--- a/src/home/home.css
+++ b/src/home/home.css
@@ -160,6 +160,9 @@
background: var(--hm-panel-2);
color: var(--ink);
cursor: pointer;
+ /* An <a> styled as a button is a button: the browser's link underline reads as
+ a second, competing affordance inside the same control. */
+ text-decoration: none;
transition: background 140ms ease, border-color 140ms ease, transform 90ms ease, opacity 140ms ease;
}
.hm-btn:hover:not(:disabled) { background: var(--hm-panel); border-color: var(--hm-focus); }
diff --git a/src/home/join.js b/src/home/join.js
new file mode 100644
index 000000000..178598a3f
--- /dev/null
+++ b/src/home/join.js
@@ -0,0 +1,270 @@
+/**
+ * /smart-home/join: accepting an invitation to somebody's household.
+ *
+ * The link is a bearer credential for a role in a physical building, so the
+ * order of this page is deliberate and is the opposite of a login wall:
+ *
+ * 1. Say what the invitation is FOR, before asking anyone to identify
+ * themselves. `GET /api/home/invites/:token` inspects without spending, so
+ * a person can see which home, which role and what that role can never do
+ * while still deciding whether they want it at all.
+ * 2. Only then ask for an account. A visitor without one is sent through the
+ * existing register flow with `?next=` pointing back at this exact link, so
+ * they land on the invitation again rather than on a dashboard wondering
+ * what happened to the email they clicked.
+ * 3. Spend it on an explicit press. Nothing here accepts on page load: an
+ * invitation redeemed by a link preview fetcher is an invitation the person
+ * never got.
+ *
+ * Four dead ends are separate screens on purpose. "This expired", "somebody
+ * already used this", "this was withdrawn" and "this link is not valid" need
+ * different words and different next steps, and collapsing them into one error
+ * is how a person ends up mailing support to ask which one happened.
+ */
+
+import { acceptInvite, inspectInvite } from './api.js';
+import { clear, el, noticeEl } from './connect.js';
+
+const ROLE_LABEL = {
+ admin: 'Admin',
+ member: 'Member',
+ guest: 'Guest',
+ viewer: 'Viewer',
+};
+
+/** What the role lets them do, and the thing it will never let them do. */
+const ROLE_CAN = {
+ admin: 'Control everything in the home, approve unlocking a door, invite other people and set what they may reach.',
+ member: 'Control everything in the home and approve unlocking a door, the same as anybody who lives there.',
+ guest: 'Control the things you have been given, and nothing else in the house.',
+ viewer: 'Watch the things you have been given. You will not be able to change anything.',
+};
+
+const ROLE_CANNOT = {
+ admin: 'You will not be able to disconnect the home from three.ws. Only the person who connected it can.',
+ member: 'You will not be able to invite anyone else, leave a standing allowance on a lock, or disconnect the home.',
+ guest: 'You will never be able to approve unlocking a door, opening a garage or disarming an alarm, even when the agent asks. Only the people who live there can.',
+ viewer: 'You will never be able to turn anything on or off, and never be able to approve unlocking a door.',
+};
+
+/** A dead end, with the words and the next step that actually fit it. */
+const DEAD_ENDS = {
+ invite_expired: {
+ title: 'This invitation has expired.',
+ body: 'Invitations stop working after a week, so the link in an old email is no longer good. Ask whoever sent it to invite you again; it takes them a moment.',
+ },
+ invite_spent: {
+ title: 'This invitation has already been used.',
+ body: 'Each link works exactly once. If that was you, the home is already on your homes page. If it was not, tell the person who invited you, and they can remove whoever accepted it.',
+ },
+ invite_revoked: {
+ title: 'This invitation was withdrawn.',
+ body: 'The person who sent it took it back before it was used. If that was not intentional, ask them to send a new one.',
+ },
+ invite_not_found: {
+ title: 'This invitation link is not valid.',
+ body: 'The link may have been cut short by an email client. Copy the whole address from the message and open it again, or ask for a new invitation.',
+ },
+ home_revoked: {
+ title: 'That home is no longer connected.',
+ body: 'The home this invitation was for has been disconnected from three.ws, so there is nothing left to join.',
+ },
+};
+
+const root = document.getElementById('hm-join-root');
+const token = new URLSearchParams(window.location.search).get('invite') || '';
+
+start();
+
+async function start() {
+ if (!token) {
+ return show(deadEnd({
+ title: 'This page needs an invitation link.',
+ body: 'Open the link you were sent rather than this page on its own. If you already have access to a home, it is on your homes page.',
+ }));
+ }
+ try {
+ const invite = await inspectInvite(token);
+ show(invitation(invite));
+ } catch (err) {
+ const known = DEAD_ENDS[err?.code];
+ show(known ? deadEnd(known) : deadEnd({
+ title: 'We could not read that invitation.',
+ body: err?.message || 'Try opening the link again in a moment.',
+ }));
+ }
+}
+
+function show(node) {
+ clear(root);
+ root.setAttribute('aria-busy', 'false');
+ root.append(node);
+}
+
+function invitation(invite) {
+ const role = invite?.role;
+ const panel = el('section', 'hm-panel');
+
+ const label = invite?.home?.label || 'a home';
+ const title = el('h2', 'hm-panel-title');
+ // The label is a string its owner typed. Text only, always.
+ title.append(document.createTextNode('You have been invited to '));
+ title.append(document.createTextNode(label));
+ panel.append(title);
+
+ const line = el('p', 'hm-panel-sub');
+ line.append(document.createTextNode('as '));
+ line.append(el('span', 'hm-tag', ROLE_LABEL[role] || role || 'a member'));
+ panel.append(line);
+
+ const can = el('div');
+ can.style.marginTop = 'var(--space-md)';
+ can.append(el('p', 'hm-row-title', 'What you will be able to do'));
+ can.append(el('p', 'hm-row-meta', ROLE_CAN[role] || 'Reach this home from your three.ws account.'));
+ panel.append(can);
+
+ const cannot = el('div');
+ cannot.style.marginTop = 'var(--space-sm)';
+ cannot.append(el('p', 'hm-row-title', 'What you will not be able to do'));
+ cannot.append(el('p', 'hm-row-meta', ROLE_CANNOT[role] || 'Anything the person who invited you did not give you.'));
+ panel.append(cannot);
+
+ if (invite?.scope?.mode === 'allow') {
+ const areas = invite.scope.areas?.length || 0;
+ const entities = invite.scope.entities?.length || 0;
+ const parts = [];
+ if (areas) parts.push(areas === 1 ? '1 room' : `${areas} rooms`);
+ if (entities) parts.push(entities === 1 ? '1 individual device' : `${entities} individual devices`);
+ const scope = el('div');
+ scope.style.marginTop = 'var(--space-sm)';
+ scope.append(el('p', 'hm-row-title', 'How much of the house you will see'));
+ scope.append(el('p', 'hm-row-meta', parts.length
+ ? `${parts.join(' and ')}. The rest of the home stays hidden from you completely, not just hidden from view.`
+ : 'Nothing has been shared with you yet. Whoever invited you can add rooms or devices at any time.'));
+ panel.append(scope);
+ }
+
+ panel.append(el('p', 'hm-hint', `This link works once, and stops working ${relativeWhen(invite?.expires_at)}.`));
+
+ const actions = el('div', 'hm-actions');
+ const accept = el('button', 'hm-btn hm-btn-primary', 'Accept and join');
+ accept.type = 'button';
+ const decline = el('a', 'hm-btn hm-btn-ghost', 'Not now');
+ decline.href = '/smart-home';
+ actions.append(accept, decline);
+ panel.append(actions);
+
+ const outcome = el('div');
+ panel.append(outcome);
+
+ accept.addEventListener('click', async () => {
+ clear(outcome);
+ accept.disabled = true;
+ accept.textContent = 'Joining';
+ try {
+ const joined = await acceptInvite(token);
+ clear(root);
+ root.append(joinedPanel(joined, label));
+ } catch (err) {
+ if (err?.status === 401) {
+ accept.disabled = false;
+ accept.textContent = 'Accept and join';
+ outcome.append(signInBlock());
+ return;
+ }
+ const known = DEAD_ENDS[err?.code];
+ if (known) {
+ show(deadEnd(known));
+ return;
+ }
+ accept.disabled = false;
+ accept.textContent = 'Try again';
+ outcome.append(noticeEl({
+ tone: 'error',
+ title: 'We could not add you to that home.',
+ body: err?.message || 'Try again in a moment.',
+ }));
+ }
+ });
+
+ return panel;
+}
+
+/**
+ * The account step, shown only when the server says one is needed.
+ *
+ * `next` carries the whole invitation URL, so registering or signing in returns
+ * the person to this exact invitation rather than to a homepage. The invitation
+ * is untouched by a failed accept, so coming back and pressing again works.
+ */
+function signInBlock() {
+ const here = `${window.location.pathname}${window.location.search}`;
+ const next = encodeURIComponent(here);
+ const wrap = el('div', 'hm-notice hm-notice-info');
+ wrap.setAttribute('role', 'status');
+ const inner = el('div');
+ inner.append(el('p', 'hm-row-title', 'You need a three.ws account first'));
+ inner.append(el('p', 'hm-row-meta', 'Accepting adds this home to an account, so there has to be one. Your invitation stays valid while you make it, and you will come straight back here.'));
+ const actions = el('div', 'hm-actions');
+ const register = el('a', 'hm-btn hm-btn-primary', 'Create an account');
+ register.href = `/register?next=${next}`;
+ const login = el('a', 'hm-btn hm-btn-ghost', 'I already have one');
+ login.href = `/login?next=${next}`;
+ actions.append(register, login);
+ inner.append(actions);
+ wrap.append(inner);
+ return wrap;
+}
+
+function joinedPanel(joined, fallbackLabel) {
+ const panel = el('section', 'hm-panel');
+ const label = joined?.home?.label || fallbackLabel;
+ const title = el('h2', 'hm-panel-title');
+ title.append(document.createTextNode(joined?.already_member ? 'You were already in ' : 'You have joined '));
+ title.append(document.createTextNode(label));
+ panel.append(title);
+
+ const role = joined?.role;
+ const sub = el('p', 'hm-panel-sub');
+ sub.append(document.createTextNode('Your role there is '));
+ sub.append(el('span', 'hm-tag', ROLE_LABEL[role] || role || 'member'));
+ sub.append(document.createTextNode('. '));
+ sub.append(document.createTextNode(ROLE_CAN[role] || ''));
+ panel.append(sub);
+
+ if (joined?.already_member) {
+ panel.append(el('p', 'hm-row-meta', 'The invitation did not change what you can do there. An invitation is a way in, not a way to be quietly moved to a different role, so ask whoever sent it if your role should be different.'));
+ }
+
+ const actions = el('div', 'hm-actions');
+ const open = el('a', 'hm-btn hm-btn-primary', 'Open this home');
+ open.href = joined?.home?.id ? `/smart-home/${encodeURIComponent(joined.home.id)}` : '/smart-home';
+ const all = el('a', 'hm-btn hm-btn-ghost', 'All your homes');
+ all.href = '/smart-home';
+ actions.append(open, all);
+ panel.append(actions);
+ return panel;
+}
+
+function deadEnd({ title, body }) {
+ const panel = el('section', 'hm-panel');
+ panel.append(noticeEl({ tone: 'error', title, body }));
+ const actions = el('div', 'hm-actions');
+ const home = el('a', 'hm-btn hm-btn-ghost', 'Your homes');
+ home.href = '/smart-home';
+ const learn = el('a', 'hm-btn hm-btn-ghost', 'What a household is');
+ learn.href = '/docs/home-households';
+ actions.append(home, learn);
+ panel.append(actions);
+ return panel;
+}
+
+/** "in 6 days", "today". An expiry nobody can read is an expiry nobody plans around. */
+function relativeWhen(iso) {
+ const at = Date.parse(iso || '');
+ if (!Number.isFinite(at)) return 'soon';
+ const days = Math.round((at - Date.now()) / 86_400_000);
+ if (days <= 0) return 'today';
+ if (days === 1) return 'tomorrow';
+ return `in ${days} days`;
+}
diff --git a/src/home/manage.js b/src/home/manage.js
index f47fccbbf..fa503f597 100644
--- a/src/home/manage.js
+++ b/src/home/manage.js
@@ -12,6 +12,7 @@
*/
import { clear, el, noticeEl } from './connect.js';
+import { householdPanel } from './members.js';
/** Past this, "moments ago" stops being honest. */
const STALE_AFTER_MS = 90_000;
@@ -80,6 +81,7 @@ function homeCard(home, { onDisconnect }) {
const detail = el('div');
detail.style.marginTop = 'var(--space-sm)';
detail.append(summary(home));
+ detail.append(householdPanel(home));
detail.append(grantsPanel(home));
detail.append(logPanel(home));
li.append(detail);
diff --git a/src/home/plan.js b/src/home/plan.js
index 8c4614f9b..30bf5943c 100644
--- a/src/home/plan.js
+++ b/src/home/plan.js
@@ -121,7 +121,9 @@ function quotaPanel(plan) {
function quotaRow(d) {
const row = el('div', 'hm-quota');
- if (d.exceeded) row.classList.add('is-over');
+ // At the ceiling and past it read the same, because they mean the same thing
+ // to the person looking: the next one is refused.
+ if (d.exceeded || (!d.unlimited && d.percent >= 100)) row.classList.add('is-over');
else if (!d.unlimited && d.percent >= WARN_AT) row.classList.add('is-warn');
const head = el('div', 'hm-quota-head');
@@ -136,7 +138,9 @@ function quotaRow(d) {
track.setAttribute('aria-valuenow', String(d.unlimited ? 0 : d.percent));
track.setAttribute('aria-label', `${d.label}: ${d.unlimited ? 'unlimited' : `${d.percent}% used`}`);
const fill = el('div', 'hm-quota-fill');
- fill.style.width = d.unlimited ? '0%' : `${Math.max(2, d.percent)}%`;
+ // A floor of 2% so a single unit out of a thousand is still visible, but only
+ // once there IS one: a stub of colour on an untouched quota reads as usage.
+ fill.style.width = d.unlimited || d.used === 0 ? '0%' : `${Math.max(2, d.percent)}%`;
track.append(fill);
row.append(track);
diff --git a/src/home/scene-render.js b/src/home/scene-render.js
index c0507b5ad..1fc27f562 100644
--- a/src/home/scene-render.js
+++ b/src/home/scene-render.js
@@ -85,6 +85,43 @@ function sharedGeometry() {
};
}
+/** A thin outline around a room's footprint, as one geometry. */
+function roomEdge(w, d) {
+ const parts = [];
+ for (const [sx, sz, px, pz] of [
+ [w + 0.12, 0.12, 0, -d / 2],
+ [w + 0.12, 0.12, 0, d / 2],
+ [0.12, d + 0.12, -w / 2, 0],
+ [0.12, d + 0.12, w / 2, 0],
+ ]) {
+ const box = new BoxGeometry(sx, 0.05, sz);
+ box.translate(px, 0.02, pz);
+ parts.push(box);
+ }
+ const merged = mergeGeometries(parts, false);
+ for (const part of parts) part.dispose();
+ return merged;
+}
+
+/** A thin bright lip along the top of a room's four walls, as one geometry. */
+function roomRim(w, d) {
+ const h = 0.92;
+ const parts = [];
+ for (const [sx, sz, px, pz] of [
+ [w, 0.05, 0, -d / 2],
+ [w, 0.05, 0, d / 2],
+ [0.05, d, -w / 2, 0],
+ [0.05, d, w / 2, 0],
+ ]) {
+ const box = new BoxGeometry(sx, 0.035, sz);
+ box.translate(px, h, pz);
+ parts.push(box);
+ }
+ const merged = mergeGeometries(parts, false);
+ for (const part of parts) part.dispose();
+ return merged;
+}
+
/** The four waist-high walls of a room, as one geometry. */
function roomShell(w, d) {
const h = 0.92;
@@ -150,11 +187,15 @@ export function createHomeScene(container, options = {}) {
const geo = sharedGeometry();
const world = new Group();
scene.add(world);
+ /** One slab per floor, under its rooms: the level a room is standing on. */
+ const slabs = new Group();
+ world.add(slabs);
/** @type {Map<string, object>} entityId to its live object record */
const objects = new Map();
/** @type {Map<string, object>} roomId to its live room record */
const rooms = new Map();
+ const slabMaterial = new MeshStandardMaterial({ color: 0x0c0d13, roughness: 1, metalness: 0 });
const spare = { color: new Color(), target: new Color(), v: new Vector3(), toward: new Vector3(), forward: new Vector3() };
let model = null;
@@ -174,6 +215,7 @@ export function createHomeScene(container, options = {}) {
// the update work is timed separately and both numbers are reported.
let updateMs = 0;
let renderMs = 0;
+ const lastCameraPosition = new Vector3();
const raycaster = new Raycaster();
const pointer = new Vector2();
@@ -192,6 +234,7 @@ export function createHomeScene(container, options = {}) {
if (!structural) return applyModel(next);
clearWorld();
model = next;
+ buildSlabs(next);
for (const room of next.rooms) rooms.set(room.id, buildRoom(room));
frameCamera(next);
placeAgent(next.agent);
@@ -252,6 +295,32 @@ export function createHomeScene(container, options = {}) {
return out;
}
+ /**
+ * A dark slab under each floor's rooms. Two rooms floating at different
+ * heights read as two rooms; two rooms on visible levels read as a house.
+ */
+ function buildSlabs(m) {
+ for (const floor of m.floors) {
+ const boxes = m.rooms.filter((r) => r.floorId === floor.id);
+ if (!boxes.length) continue;
+ let minX = Infinity;
+ let maxX = -Infinity;
+ let minZ = Infinity;
+ let maxZ = -Infinity;
+ for (const room of boxes) {
+ minX = Math.min(minX, room.x - room.w / 2);
+ maxX = Math.max(maxX, room.x + room.w / 2);
+ minZ = Math.min(minZ, room.z - room.d / 2);
+ maxZ = Math.max(maxZ, room.z + room.d / 2);
+ }
+ const pad = 1.1;
+ const slab = new Mesh(geo.slab, slabMaterial);
+ slab.scale.set(maxX - minX + pad * 2, 0.22, maxZ - minZ + pad * 2);
+ slab.position.set((minX + maxX) / 2, floor.y - 0.24, (minZ + maxZ) / 2);
+ slabs.add(slab);
+ }
+ }
+
function buildRoom(room) {
const group = new Group();
group.position.set(room.x, room.y, room.z);
@@ -264,6 +333,13 @@ export function createHomeScene(container, options = {}) {
floor.userData.roomId = room.id;
group.add(floor);
+ // A bright lip along the top of the walls. Without it a room reads as a
+ // coloured rectangle on a black field; with it, it reads as a room you are
+ // looking down into, which is the whole illusion.
+ const rimMat = new MeshBasicMaterial({ color: 0xffffff, transparent: true, opacity: 0.1 });
+ const rim = new Mesh(roomRim(room.w, room.d), rimMat);
+ group.add(rim);
+
// Waist-high walls, translucent. Full-height walls would hide the room's
// contents from every angle an orbiting camera can reach, and a dollhouse
// you cannot see into is a box.
@@ -276,13 +352,16 @@ export function createHomeScene(container, options = {}) {
const walls = new Mesh(wallGeo, wallMat);
group.add(walls);
- // The security tell: a line around the room's foot that goes amber the
+ // The security tell: a LINE around the room's foot that goes amber the
// moment something in it is unlocked or open. Readable from across the
// room without reading a single label, which is the whole point.
+ //
+ // It was a scaled box, which is a filled sheet over the whole floor, so
+ // every secure room in the house was carpeted in green and no light
+ // underneath it could be seen. An outline says the same thing and shows
+ // the room.
const edgeMat = new MeshBasicMaterial({ color: SECURE, transparent: true, opacity: 0 });
- const edge = new Mesh(geo.slab, edgeMat);
- edge.scale.set(room.w + 0.1, 0.05, room.d + 0.1);
- edge.position.y = 0.02;
+ const edge = new Mesh(roomEdge(room.w, room.d), edgeMat);
group.add(edge);
const light = new PointLight(0xffffff, 0, room.w * 2.6, 1.7);
@@ -291,7 +370,7 @@ export function createHomeScene(container, options = {}) {
if (usesLight) group.add(light);
const label = makeLabel();
- label.position.set(0, room.h + 0.5, 0);
+ label.position.set(0, room.h + 1.05, 0);
group.add(label);
const record = {
@@ -299,8 +378,11 @@ export function createHomeScene(container, options = {}) {
source: room,
group,
floorMat,
+ rimMat,
+ rimGeo: rim.geometry,
wallMat,
edgeMat,
+ edgeGeo: edge.geometry,
light: usesLight ? light : null,
label,
wallGeo,
@@ -476,16 +558,25 @@ export function createHomeScene(container, options = {}) {
if (record.light) {
record.light.color.copy(spare.color);
- record.light.intensity = record.intensity * 3.4 * dim;
+ // The point light does the work. Emissive on the slab was doing it
+ // instead, which flattened every lit room into one saturated rectangle.
+ record.light.intensity = record.intensity * 6.5 * dim;
}
- record.floorMat.emissive.copy(spare.color).multiplyScalar(record.intensity * 0.42 * dim);
- record.floorMat.color.setHex(SURFACE).lerp(spare.color, Math.min(0.22, record.intensity * 0.2));
- record.wallMat.opacity = 0.24 + record.intensity * 0.12 + record.highlight * 0.24;
+ record.floorMat.emissive.copy(spare.color).multiplyScalar(record.intensity * 0.09 * dim);
+ record.floorMat.color.setHex(SURFACE).lerp(spare.color, Math.min(0.1, record.intensity * 0.08));
+ record.wallMat.opacity = 0.3 + record.intensity * 0.1 + record.highlight * 0.24;
+ // A dark room still has to be a visible room, so the rim has a real floor.
+ record.rimMat.opacity = (0.17 + record.intensity * 0.13 + record.highlight * 0.35) * (1 - staleAmount * 0.5);
const alarmed = record.secure;
record.edgeMat.color.setHex(alarmed > 0.5 ? OPEN : SECURE);
- record.edgeMat.opacity = (room.security ? 0.18 + alarmed * 0.5 : 0) + record.highlight * 0.4;
- record.label.material.opacity = 0.92 * (1 - staleAmount * 0.4);
+ record.edgeMat.opacity = (room.security ? 0.3 + alarmed * 0.65 : 0) + record.highlight * 0.4;
+ // Faded by distance so a house seen from far away is a house, not a list
+ // of names. The focused room keeps its label at any range.
+ const far = record.group.position.distanceTo(camera.position);
+ const near = record.id === model?.focusRoomId ? 1 : clamp01(1.6 - far / 34);
+ record.label.material.opacity = 0.92 * near * (1 - staleAmount * 0.4);
+ record.label.visible = near > 0.02;
}
function commitObject(record) {
@@ -570,6 +661,10 @@ export function createHomeScene(container, options = {}) {
// ── loop ──────────────────────────────────────────────────────────────────
+ function clamp01(n) {
+ return Math.min(1, Math.max(0, n));
+ }
+
function damp(current, target, dt) {
// Framerate-independent exponential approach: the same visual speed at
// 30 fps and at 144.
@@ -591,6 +686,10 @@ export function createHomeScene(container, options = {}) {
last = now;
const updateStart = performance.now();
+ // Label opacity is a function of camera distance, so rooms recommit while
+ // the camera is moving and stay untouched the moment it settles.
+ const cameraMoved = !lastCameraPosition.equals(camera.position);
+ if (cameraMoved) lastCameraPosition.copy(camera.position);
const staleTarget = stale ? 1 : 0;
staleMoving = Math.abs(staleAmount - staleTarget) > 0.002;
staleAmount = damp(staleAmount, staleTarget, dt);
@@ -602,7 +701,10 @@ export function createHomeScene(container, options = {}) {
const before = record.intensity;
record.intensity = damp(record.intensity, record.targetIntensity, dt);
record.secure = damp(record.secure, record.targetSecure, dt);
- const moved = Math.abs(before - record.intensity) > 0.0005 || Math.abs(wasHighlight - record.highlight) > 0.001;
+ const moved =
+ Math.abs(before - record.intensity) > 0.0005 ||
+ Math.abs(wasHighlight - record.highlight) > 0.001 ||
+ cameraMoved;
if (moved || !record.color.equals(record.targetColor) || staleMoving) {
record.color.lerp(record.targetColor, 1 - Math.exp(-dt / EASE));
commitRoom(record);
@@ -654,8 +756,8 @@ export function createHomeScene(container, options = {}) {
const cx = (b.minX + b.maxX) / 2;
const cz = (b.minZ + b.maxZ) / 2;
const span = Math.max(b.width, b.depth, 8);
- controls.target.set(cx, Math.min(b.maxY * 0.35, 3), cz);
- camera.position.set(cx + span * 0.62, span * 0.66 + 4, cz + span * 0.86);
+ controls.target.set(cx, b.maxY * 0.34, cz);
+ camera.position.set(cx + span * 0.58, b.maxY * 0.6 + span * 0.72, cz + span * 0.94);
camera.updateProjectionMatrix();
controls.update();
}
@@ -684,8 +786,11 @@ export function createHomeScene(container, options = {}) {
canvas.height = 128;
const texture = new CanvasTexture(canvas);
texture.minFilter = LinearFilter;
+ // Depth test off, distance fade on. Testing depth clipped a label wherever
+ // it crossed the room in front of it, which read as truncated text; the
+ // distance fade is what actually stops a dozen labels stacking up.
const sprite = new Sprite(new SpriteMaterial({ map: texture, transparent: true, depthWrite: false, depthTest: false }));
- sprite.scale.set(4.4, 1.1, 1);
+ sprite.scale.set(3.4, 0.85, 1);
sprite.userData.canvas = canvas;
sprite.userData.texture = texture;
return sprite;
@@ -702,9 +807,17 @@ export function createHomeScene(container, options = {}) {
const canvas = record.label.userData.canvas;
const ctx = canvas.getContext('2d');
ctx.clearRect(0, 0, canvas.width, canvas.height);
- ctx.font = '600 46px "Inter", system-ui, sans-serif';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
+ // Fit the text to the canvas rather than letting it run off the edge. A
+ // room called "Living Room" with a temperature and a light count is wider
+ // than 512px at 46px, and the overflow read as a truncated room name.
+ let size = 46;
+ ctx.font = `600 ${size}px "Inter", system-ui, sans-serif`;
+ while (size > 22 && ctx.measureText(record.labelText).width > canvas.width - 72) {
+ size -= 2;
+ ctx.font = `600 ${size}px "Inter", system-ui, sans-serif`;
+ }
ctx.fillStyle = 'rgba(8, 9, 14, 0.72)';
const width = Math.min(canvas.width - 8, ctx.measureText(record.labelText).width + 56);
roundRect(ctx, (canvas.width - width) / 2, 26, width, 76, 22);
@@ -780,6 +893,9 @@ export function createHomeScene(container, options = {}) {
objects.clear();
for (const record of rooms.values()) {
record.floorMat.dispose();
+ record.rimMat.dispose();
+ record.rimGeo.dispose();
+ record.edgeGeo.dispose();
record.wallMat.dispose();
record.wallGeo.dispose();
record.edgeMat.dispose();
@@ -787,7 +903,9 @@ export function createHomeScene(container, options = {}) {
record.label.material.dispose();
}
rooms.clear();
+ slabs.clear();
world.clear();
+ world.add(slabs);
}
return {
@@ -848,6 +966,7 @@ export function createHomeScene(container, options = {}) {
renderer.domElement.removeEventListener('pointerdown', onPointerDown);
clearWorld();
agent?.dispose();
+ slabMaterial.dispose();
for (const value of Object.values(geo)) value.dispose();
controls.dispose();
renderer.dispose();
diff --git a/src/voice/vad.js b/src/voice/vad.js
index be747bf84..056f1de54 100644
--- a/src/voice/vad.js
+++ b/src/voice/vad.js
@@ -39,13 +39,19 @@ export const VAD_SAMPLE_RATE = 16000;
export const VAD_MS_PER_FRAME = (VAD_FRAME_SAMPLES / VAD_SAMPLE_RATE) * 1000;
/**
- * Trailing silence before an utterance is called finished. The order's budget is
- * "under 400 ms": longer and the agent feels broken, shorter and it clips people
- * mid-sentence. 384 ms is 12 whole frames, the largest multiple of the frame
- * period that fits under the budget, so the real behaviour matches the number we
- * publish instead of rounding past it.
+ * Trailing silence before an utterance is called finished.
+ *
+ * The budget is "under 400 ms": longer and the agent feels broken, shorter and it
+ * clips people mid-sentence. 352 ms is 11 whole frames, and the frame count is
+ * what matters because the deadline is checked once per frame. It is not 12
+ * frames (384 ms) because the wall-clock gap a user actually experiences runs
+ * from the last frame silero rated as speech to the moment the utterance closes,
+ * and that is one frame period longer than the configured window: measured at
+ * 412 to 424 ms with 12 frames, which misses the budget. Eleven frames measures
+ * in the high 380s. Widening the budget was the alternative, and it was the wrong
+ * one.
*/
-export const DEFAULT_REDEMPTION_MS = 384;
+export const DEFAULT_REDEMPTION_MS = 352;
/**
* Audio kept from BEFORE speech was detected. Silero fires a frame or two into a
@@ -56,6 +62,16 @@ const PRE_SPEECH_PAD_MS = 480;
/** Shorter than a syllable; anything under this is a cough, a door, a keyboard. */
const MIN_SPEECH_MS = 250;
+/**
+ * Silero's own defaults, restated here rather than inherited invisibly, because
+ * the endpoint measurement depends on knowing which of the two governs the
+ * countdown. Speech is declared above the positive threshold and the redemption
+ * clock starts below the negative one; the band between them is hysteresis, and
+ * it is what stops a breath inside a word from ending the utterance.
+ */
+const POSITIVE_SPEECH_THRESHOLD = 0.3;
+const NEGATIVE_SPEECH_THRESHOLD = 0.25;
+
let vadModulePromise = null;
/** Load @ricky0123/vad-web once, on demand. */
@@ -138,10 +154,14 @@ export class VoiceActivityDetector {
minSpeechMs: MIN_SPEECH_MS,
// Silero's own defaults, restated so a future tuning pass has one place
// to argue with rather than an invisible import.
- positiveSpeechThreshold: 0.3,
- negativeSpeechThreshold: 0.25,
+ positiveSpeechThreshold: POSITIVE_SPEECH_THRESHOLD,
+ negativeSpeechThreshold: NEGATIVE_SPEECH_THRESHOLD,
onFrameProcessed: ({ isSpeech }, frame) => {
- if (isSpeech >= 0.3) this.lastSpeechFrameAt = now();
+ // Marked at the NEGATIVE threshold, because that is the one the
+ // redemption countdown actually starts from. Marking at the positive
+ // threshold instead would count the frames between the two as part of
+ // the trailing silence and report a gap the user never waited through.
+ if (isSpeech >= NEGATIVE_SPEECH_THRESHOLD) this.lastSpeechFrameAt = now();
this.onFrame(frame, isSpeech);
},
onSpeechStart: () => this.onSpeechStart(),
diff --git a/tests/home-relay-pairing.test.js b/tests/home-relay-pairing.test.js
new file mode 100644
index 000000000..a57149b00
--- /dev/null
+++ b/tests/home-relay-pairing.test.js
@@ -0,0 +1,205 @@
+// Pairing a house that only exists on a LAN.
+//
+// The secret here is deliberately weak: eight characters a person reads off one
+// screen and types into another, so about forty bits. Everything below is the
+// set of properties that has to hold for that to be safe, and each one is
+// tested rather than asserted in a comment:
+//
+// * a code redeems into exactly the one home it was minted for
+// * it works once, decided by the database rather than by a process
+// * it expires
+// * wrong guesses are counted and kill it
+// * a stored row yields no live pairing
+//
+// Two tiers, so `npm test` needs neither a database nor a relay: the pure
+// helpers first, then a live round trip that skips itself without DATABASE_URL.
+
+import { describe, expect, it, beforeAll, afterAll } from 'vitest';
+
+import {
+ generatePairingCode,
+ hashPairingCode,
+ isRelayBaseUrl,
+ isRelayConfigured,
+ MAX_PAIRING_ATTEMPTS,
+ normalizePairingCode,
+ PAIRING_TTL_MS,
+ relayBaseUrl,
+} from '../api/_lib/home/relay.js';
+
+describe('the code itself', () => {
+ it('avoids the characters people mistype into each other', () => {
+ const alphabet = new Set();
+ for (let i = 0; i < 2000; i += 1) for (const ch of generatePairingCode().replace('-', '')) alphabet.add(ch);
+ // I, L, O and U are the four that get read wrong off a screen.
+ for (const banned of ['I', 'L', 'O', 'U']) expect([...alphabet]).not.toContain(banned);
+ expect(alphabet.size).toBeGreaterThan(24);
+ });
+
+ it('is grouped for reading aloud and normalizes back to one form', () => {
+ const code = generatePairingCode();
+ expect(code).toMatch(/^[0-9A-Z]{4}-[0-9A-Z]{4}$/);
+ const raw = code.replace('-', '');
+ for (const variant of [code, raw, code.toLowerCase(), ` ${code} `, raw.split('').join(' ')]) {
+ expect(normalizePairingCode(variant)).toBe(raw);
+ }
+ });
+
+ it('is stored as a digest, so reading the table yields no live pairing', () => {
+ const code = generatePairingCode();
+ const digest = hashPairingCode(code);
+ expect(digest).toMatch(/^[0-9a-f]{64}$/);
+ expect(digest).not.toContain(normalizePairingCode(code));
+ expect(hashPairingCode(code.toLowerCase())).toBe(digest);
+ expect(hashPairingCode(generatePairingCode())).not.toBe(digest);
+ });
+
+ it('does not collide in any run a person could ever produce', () => {
+ const codes = new Set(Array.from({ length: 20_000 }, () => generatePairingCode()));
+ expect(codes.size).toBeGreaterThan(19_990);
+ });
+
+ it('expires inside the span of one sitting', () => {
+ expect(PAIRING_TTL_MS).toBeLessThanOrEqual(15 * 60 * 1000);
+ expect(MAX_PAIRING_ATTEMPTS).toBeLessThanOrEqual(10);
+ });
+});
+
+describe('a relayed home has no address of ours to dial', () => {
+ it('records the relay id as its base url, honestly and uniquely', () => {
+ expect(relayBaseUrl('hr_abc')).toBe('relay://hr_abc');
+ expect(isRelayBaseUrl(relayBaseUrl('hr_abc'))).toBe(true);
+ expect(isRelayBaseUrl('https://home.example.com')).toBe(false);
+ expect(isRelayBaseUrl(null)).toBe(false);
+ });
+});
+
+describe('a deployment with no relay', () => {
+ it('says so rather than minting a code nobody could redeem', () => {
+ const saved = { ...process.env };
+ delete process.env.HOME_RELAY_URL;
+ delete process.env.HOME_RELAY_SERVICE_TOKEN;
+ delete process.env.HOME_RELAY_SIGNING_KEY;
+ expect(isRelayConfigured()).toBe(false);
+ process.env.HOME_RELAY_URL = 'wss://relay.example';
+ process.env.HOME_RELAY_SERVICE_TOKEN = 'short';
+ process.env.HOME_RELAY_SIGNING_KEY = 'k'.repeat(48);
+ // A short token is not a configured relay: it would fail at the first
+ // connect, which is the worst possible place to discover it.
+ expect(isRelayConfigured()).toBe(false);
+ process.env.HOME_RELAY_SERVICE_TOKEN = 't'.repeat(48);
+ expect(isRelayConfigured()).toBe(true);
+ Object.assign(process.env, saved);
+ });
+});
+
+// ── the live round trip ──────────────────────────────────────────────────────
+
+const hasDb = Boolean(process.env.DATABASE_URL);
+const liveDb = describe.skipIf(!hasDb);
+
+liveDb('the pairing lifecycle, against a real database', () => {
+ let sql;
+ let owner;
+ let stranger;
+ let relay;
+ const saved = {};
+
+ beforeAll(async () => {
+ for (const key of ['HOME_RELAY_URL', 'HOME_RELAY_SERVICE_TOKEN', 'HOME_RELAY_SIGNING_KEY']) saved[key] = process.env[key];
+ process.env.HOME_RELAY_URL = process.env.HOME_RELAY_URL || 'ws://127.0.0.1:9';
+ process.env.HOME_RELAY_SERVICE_TOKEN = process.env.HOME_RELAY_SERVICE_TOKEN || 't'.repeat(48);
+ process.env.HOME_RELAY_SIGNING_KEY = process.env.HOME_RELAY_SIGNING_KEY || 'k'.repeat(48);
+ ({ sql } = await import('../api/_lib/db.js'));
+ relay = await import('../api/_lib/home/relay.js');
+ const stamp = Date.now();
+ [owner] = await sql`insert into users (email) values (${`home-relay-owner-${stamp}@qa.three.ws`}) returning id`;
+ [stranger] = await sql`insert into users (email) values (${`home-relay-stranger-${stamp}@qa.three.ws`}) returning id`;
+ }, 60_000);
+
+ afterAll(async () => {
+ if (sql && owner) await sql`delete from users where id in (${owner.id}, ${stranger.id})`;
+ Object.assign(process.env, saved);
+ });
+
+ it('creates a home with a relay id and no credential at all', async () => {
+ const { home, code, expiresAt } = await relay.startPairing({ userId: owner.id, label: 'LAN house' });
+ expect(home.transport).toBe('relay');
+ expect(home.relay_id).toMatch(/^hr_/);
+ expect(new Date(expiresAt).getTime()).toBeGreaterThan(Date.now());
+
+ const [row] = await sql`select access_token_enc, token_fingerprint from home_connections where id = ${home.id}`;
+ expect(row.access_token_enc).toBe('');
+ expect(row.token_fingerprint).toBe('');
+ expect(normalizePairingCode(code)).toHaveLength(8);
+ });
+
+ it('redeems once and refuses the second attempt', async () => {
+ const { home, code } = await relay.startPairing({ userId: owner.id, label: 'Reuse' });
+ const first = await relay.redeemPairing({ code, protocol: 1, agent: { name: 'test', version: '1' } });
+ expect(first.relayId).toBe(home.relay_id);
+ expect(first.installToken).toMatch(/^hr1\./);
+ await expect(relay.redeemPairing({ code, protocol: 1 })).rejects.toMatchObject({ code: 'already_redeemed', status: 409 });
+ });
+
+ it('refuses a code that expired', async () => {
+ const { home, code } = await relay.startPairing({ userId: owner.id, label: 'Expiry' });
+ await sql`update home_relay_pairings set expires_at = now() - interval '1 minute' where home_id = ${home.id}`;
+ await expect(relay.redeemPairing({ code, protocol: 1 })).rejects.toMatchObject({ code: 'expired', status: 410 });
+ });
+
+ it('refuses a code that was never issued, without saying whether one exists', async () => {
+ await expect(relay.redeemPairing({ code: 'ZZZZ-ZZZZ', protocol: 1 })).rejects.toMatchObject({ code: 'unknown_code', status: 404 });
+ await expect(relay.redeemPairing({ code: 'nope', protocol: 1 })).rejects.toMatchObject({ code: 'unknown_code', status: 404 });
+ });
+
+ it('kills a code after enough wrong guesses', async () => {
+ const { home, code } = await relay.startPairing({ userId: owner.id, label: 'Guessing' });
+ for (let i = 0; i < MAX_PAIRING_ATTEMPTS; i += 1) {
+ await sql`update home_relay_pairings set attempts = attempts + 1 where home_id = ${home.id}`;
+ }
+ await expect(relay.redeemPairing({ code, protocol: 1 })).rejects.toMatchObject({ code: 'too_many_attempts', status: 429 });
+ });
+
+ it('refuses an integration older than the protocol, and names the upgrade', async () => {
+ const { code } = await relay.startPairing({ userId: owner.id, label: 'Old' });
+ await expect(relay.redeemPairing({ code, protocol: 0 })).rejects.toMatchObject({ code: 'protocol_too_old', status: 426 });
+ });
+
+ it('gives one home exactly one live code: refreshing retires the old one', async () => {
+ const { home, code: first } = await relay.startPairing({ userId: owner.id, label: 'Refresh' });
+ const { code: second } = await relay.refreshPairing({ homeId: home.id, userId: owner.id });
+ expect(second).not.toBe(first);
+ // The old code must be dead, or refreshing would leave a second, invisible
+ // way into the same house.
+ await expect(relay.redeemPairing({ code: first, protocol: 1 })).rejects.toMatchObject({ code: 'unknown_code' });
+ const redeemed = await relay.redeemPairing({ code: second, protocol: 1 });
+ expect(redeemed.relayId).toBe(home.relay_id);
+ });
+
+ it('will not let a stranger refresh someone else\'s pairing', async () => {
+ const { home } = await relay.startPairing({ userId: owner.id, label: 'Not yours' });
+ await expect(relay.refreshPairing({ homeId: home.id, userId: stranger.id })).rejects.toMatchObject({ status: 404 });
+ });
+
+ it('mints a token that only ever names the home it was minted for', async () => {
+ const a = await relay.startPairing({ userId: owner.id, label: 'A' });
+ const b = await relay.startPairing({ userId: stranger.id, label: 'B' });
+ const redeemedA = await relay.redeemPairing({ code: a.code, protocol: 1 });
+ const { verifyInstallToken } = await import('../services/home-relay/src/token.js');
+ const claims = verifyInstallToken(redeemedA.installToken, process.env.HOME_RELAY_SIGNING_KEY).claims;
+ expect(claims.relayId).toBe(a.home.relay_id);
+ expect(claims.homeId).toBe(a.home.id);
+ expect(claims.userId).toBe(owner.id);
+ expect(claims.relayId).not.toBe(b.home.relay_id);
+ });
+
+ it('prunes pairings that can never be redeemed again', async () => {
+ const { home } = await relay.startPairing({ userId: owner.id, label: 'Prunable' });
+ await sql`update home_relay_pairings set expires_at = now() - interval '48 hours' where home_id = ${home.id}`;
+ const { pruned } = await relay.prunePairings({ olderThanHours: 24 });
+ expect(pruned).toBeGreaterThan(0);
+ const left = await sql`select id from home_relay_pairings where home_id = ${home.id}`;
+ expect(left).toHaveLength(0);
+ });
+});
diff --git a/tests/home-relay-transport.test.js b/tests/home-relay-transport.test.js
new file mode 100644
index 000000000..9be1f06c2
--- /dev/null
+++ b/tests/home-relay-transport.test.js
@@ -0,0 +1,322 @@
+// The relay end to end, in process: a real relay server, a real agent socket, a
+// real HomeBridge, and no Home Assistant.
+//
+// The live proof against an actual house on an unroutable network is
+// scripts/home-relay-e2e.mjs, and it is the one that matters. This suite exists
+// for the paths that are hard to provoke on demand there: a house that is not
+// dialled in, a relay that refuses a frame, a socket that dies mid-session, a
+// second install replacing the first, and the rate limits.
+//
+// The "house" here is a bare WebSocket that speaks the protocol and answers
+// Home Assistant's message shapes from a fixture. It is not a mock of Home
+// Assistant (nothing here pretends to be a smart home); it is the far end of a
+// wire whose only job is to prove the wire.
+
+import { WebSocket } from 'ws';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { createRelay } from '../services/home-relay/src/server.js';
+import { frames, PROTOCOL_VERSION } from '../services/home-relay/src/protocol.js';
+import { mintInstallToken, newRelayId } from '../services/home-relay/src/token.js';
+import { createRelayTransport } from '../packages/home-bridge/src/transport-relay.js';
+import { HomeBridge } from '../packages/home-bridge/src/bridge.js';
+import { ERR } from '../packages/home-bridge/src/errors.js';
+
+const SIGNING_KEY = 's'.repeat(48);
+const SERVICE_TOKEN = 'v'.repeat(48);
+const HA_VERSION = '2026.9.0';
+
+let relay;
+let port;
+let base;
+
+beforeAll(async () => {
+ relay = createRelay({ signingKey: SIGNING_KEY, serviceToken: SERVICE_TOKEN, log: () => {} });
+ const address = await relay.listen(0, '127.0.0.1');
+ port = address.port;
+ base = `ws://127.0.0.1:${port}`;
+});
+
+afterAll(async () => {
+ await relay.close();
+});
+
+/**
+ * A house on the far end of the wire. Answers the handful of Home Assistant
+ * messages the bridge sends during connect, and records everything that
+ * actually reached it so a test can assert that a refused frame never did.
+ */
+function connectAgent(relayId, { autoReady = true } = {}) {
+ const token = mintInstallToken({ relayId, userId: 'u1', homeId: 'h1' }, SIGNING_KEY);
+ const socket = new WebSocket(`${base}/v1/agent`, { headers: { authorization: `Bearer ${token}` } });
+ const house = { socket, received: [], sessions: new Set(), online: null, refused: null };
+
+ house.online = new Promise((resolve, reject) => {
+ socket.on('message', (raw) => {
+ const frame = JSON.parse(String(raw));
+ if (frame.t === 'hello.ok') return resolve(house);
+ if (frame.t === 'hello.err') {
+ house.refused = frame;
+ return reject(new Error(`${frame.code}: ${frame.message}`));
+ }
+ if (frame.t === 'session.open') {
+ house.sessions.add(frame.sid);
+ if (autoReady) socket.send(JSON.stringify(frames.sessionReady(frame.sid, HA_VERSION)));
+ return;
+ }
+ if (frame.t === 'session.close') {
+ house.sessions.delete(frame.sid);
+ return;
+ }
+ if (frame.t === 'ha') {
+ house.received.push(frame.msg);
+ const reply = answer(frame.msg);
+ if (reply) socket.send(JSON.stringify(frames.ha(frame.sid, reply)));
+ // The live entity channel: one empty burst, so connect() resolves on a
+ // real message rather than waiting out its five second floor.
+ if (frame.msg.type === 'subscribe_entities') {
+ socket.send(JSON.stringify(frames.ha(frame.sid, { id: frame.msg.id, type: 'event', event: { a: {} } })));
+ }
+ }
+ });
+ socket.on('error', reject);
+ });
+ socket.on('open', () => socket.send(JSON.stringify(frames.hello(relayId, { name: 'test house', version: '1.0.0' }))));
+ return house;
+}
+
+/** The subset of Home Assistant's answers the bridge's connect path needs. */
+function answer(msg) {
+ if (typeof msg?.id !== 'number') return null;
+ const ok = (result) => ({ id: msg.id, type: 'result', success: true, result });
+ switch (msg.type) {
+ case 'get_states':
+ return ok([]);
+ case 'subscribe_entities':
+ return ok(null);
+ case 'config/floor_registry/list':
+ case 'config/area_registry/list':
+ case 'config/device_registry/list':
+ case 'config/entity_registry/list':
+ return ok([]);
+ case 'call_service':
+ return ok({ context: { id: 'ctx' } });
+ case 'get_config':
+ return ok({ location_name: 'Test' });
+ default:
+ return ok(null);
+ }
+}
+
+const transportFor = (relayId) =>
+ createRelayTransport({ relayUrl: base, relayId, serviceToken: SERVICE_TOKEN, WebSocketImpl: WebSocket, openTimeoutMs: 5000 });
+
+describe('a house that has dialled in', () => {
+ it('carries a HomeBridge with no base URL and no Home Assistant token', async () => {
+ const relayId = newRelayId();
+ const house = connectAgent(relayId);
+ await house.online;
+
+ const bridge = new HomeBridge({ transport: transportFor(relayId) });
+ expect(bridge.transport).toBe('relay');
+ await bridge.connect();
+ expect(bridge.connected).toBe(true);
+ // The auth handshake never crossed the relay: the house handed the session
+ // over already authenticated, and its version came with it.
+ expect(house.received.some((m) => m.type === 'auth')).toBe(false);
+ // A 2026 instance uses the compressed entity subscription, not get_states.
+ expect(house.received.some((m) => m.type === 'subscribe_entities')).toBe(true);
+
+ await bridge.call('light', 'turn_on', { entity_id: 'light.kitchen' });
+ expect(house.received.some((m) => m.type === 'call_service' && m.domain === 'light')).toBe(true);
+
+ bridge.close();
+ house.socket.close();
+ });
+
+ it('never lets a refused frame reach the house, and answers with a reason', async () => {
+ const relayId = newRelayId();
+ const house = connectAgent(relayId);
+ await house.online;
+ const bridge = new HomeBridge({ transport: transportFor(relayId) });
+ await bridge.connect();
+ const before = house.received.length;
+
+ const refusal = await sendRaw(relayId, { id: 77, type: 'call_service', domain: 'shell_command', service: 'rm' });
+ expect(refusal.success).toBe(false);
+ expect(refusal.error.code).toBe('not_allowed');
+ expect(house.received.length).toBe(before);
+ expect(house.received.some((m) => m.domain === 'shell_command')).toBe(false);
+
+ bridge.close();
+ house.socket.close();
+ });
+});
+
+describe('a house that has not dialled in', () => {
+ it('is refused with a reason a person can act on, not a hang', async () => {
+ const bridge = new HomeBridge({ transport: transportFor('hr_nobody_home_00000000') });
+ const failure = await bridge.connect().then(() => null, (err) => err);
+ expect(failure).toBeTruthy();
+ expect(failure.code).toBe(ERR.UNREACHABLE);
+ expect(failure.message).toMatch(/integration is offline/i);
+ });
+});
+
+describe('credentials', () => {
+ it('refuses an agent with no install token', async () => {
+ const socket = new WebSocket(`${base}/v1/agent`);
+ const status = await new Promise((resolve) => {
+ socket.on('unexpected-response', (_req, res) => resolve(res.statusCode));
+ socket.on('error', () => resolve(0));
+ });
+ expect(status).toBe(401);
+ });
+
+ it('refuses a platform caller with no service token', async () => {
+ const socket = new WebSocket(`${base}/v1/bridge?relay_id=hr_x`);
+ const status = await new Promise((resolve) => {
+ socket.on('unexpected-response', (_req, res) => resolve(res.statusCode));
+ socket.on('error', () => resolve(0));
+ });
+ expect(status).toBe(401);
+ });
+
+ it('binds a socket to the relay id in the token, never the one in the frame', async () => {
+ // A house that claims someone else's relay id in its hello frame gets its
+ // own, because the relay reads the id out of the signed token and ignores
+ // the claim entirely. This is what makes a stolen install token useless
+ // for reaching a different house.
+ const mine = newRelayId();
+ const theirs = newRelayId();
+ const token = mintInstallToken({ relayId: mine, userId: 'u1', homeId: 'h1' }, SIGNING_KEY);
+ const socket = new WebSocket(`${base}/v1/agent`, { headers: { authorization: `Bearer ${token}` } });
+ await new Promise((resolve, reject) => {
+ socket.on('open', () => socket.send(JSON.stringify(frames.hello(theirs, { name: 'liar', version: '1' }))));
+ socket.on('message', (raw) => {
+ const frame = JSON.parse(String(raw));
+ if (frame.t === 'hello.ok') resolve();
+ });
+ socket.on('error', reject);
+ });
+ expect(relay.installs.has(mine)).toBe(true);
+ expect(relay.installs.has(theirs)).toBe(false);
+ socket.close();
+ });
+});
+
+describe('lifecycle', () => {
+ it('replaces a stale socket when the same house dials in again', async () => {
+ const relayId = newRelayId();
+ const first = connectAgent(relayId);
+ await first.online;
+ const second = connectAgent(relayId);
+ await second.online;
+ expect(relay.installs.get(relayId).socket).not.toBe(first.socket);
+ second.socket.close();
+ });
+
+ it('tells an open session the house went away, rather than leaving it to time out', async () => {
+ const relayId = newRelayId();
+ const house = connectAgent(relayId);
+ await house.online;
+ const bridge = new HomeBridge({ transport: transportFor(relayId) });
+ await bridge.connect();
+
+ const disconnected = new Promise((resolve) => bridge.on('disconnected', resolve));
+ house.socket.close();
+ await Promise.race([disconnected, new Promise((r) => setTimeout(r, 3000))]);
+ bridge.close();
+ });
+
+ it('drops the socket immediately when three.ws revokes the home', async () => {
+ const relayId = newRelayId();
+ const house = connectAgent(relayId);
+ await house.online;
+ const closed = new Promise((resolve) => house.socket.on('close', resolve));
+
+ const res = await fetch(`http://127.0.0.1:${port}/v1/revoke`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', authorization: `Bearer ${SERVICE_TOKEN}` },
+ body: JSON.stringify({ relayId }),
+ });
+ expect(res.status).toBe(200);
+ await closed;
+ expect(relay.installs.has(relayId)).toBe(false);
+
+ // And it stays revoked: a reconnect is refused at the upgrade.
+ const token = mintInstallToken({ relayId, userId: 'u1', homeId: 'h1' }, SIGNING_KEY);
+ const retry = new WebSocket(`${base}/v1/agent`, { headers: { authorization: `Bearer ${token}` } });
+ const status = await new Promise((resolve) => {
+ retry.on('unexpected-response', (_req, res2) => resolve(res2.statusCode));
+ retry.on('error', () => resolve(0));
+ });
+ expect(status).toBe(403);
+ });
+});
+
+describe('limits', () => {
+ it('caps concurrent sessions per install', async () => {
+ const relayId = newRelayId();
+ const house = connectAgent(relayId);
+ await house.online;
+ const open = [];
+ for (let i = 0; i < 8; i += 1) open.push(await rawSession(relayId));
+ const refusal = await rawSessionRefusal(relayId);
+ expect(refusal.code).toBe('too_many_sessions');
+ for (const socket of open) socket.close();
+ house.socket.close();
+ });
+
+ it('reports its own state for a health probe', () => {
+ const stats = relay.stats();
+ expect(stats).toHaveProperty('installs');
+ expect(stats).toHaveProperty('sessions');
+ expect(stats).toHaveProperty('revoked');
+ });
+});
+
+// --------------------------------------------------------------- small parts
+
+/** One raw platform frame, the way an escaped caller would send it. */
+function sendRaw(relayId, msg) {
+ const socket = new WebSocket(`${base}/v1/bridge?relay_id=${relayId}`, { headers: { authorization: `Bearer ${SERVICE_TOKEN}` } });
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => reject(new Error('no answer')), 5000);
+ socket.on('message', (raw) => {
+ const frame = JSON.parse(String(raw));
+ if (frame.t === 'session.ready') return socket.send(JSON.stringify(frames.ha(frame.sid, msg)));
+ if (frame.t === 'ha' && frame.msg.id === msg.id) {
+ clearTimeout(timer);
+ socket.close();
+ resolve(frame.msg);
+ }
+ });
+ socket.on('error', reject);
+ });
+}
+
+function rawSession(relayId) {
+ const socket = new WebSocket(`${base}/v1/bridge?relay_id=${relayId}`, { headers: { authorization: `Bearer ${SERVICE_TOKEN}` } });
+ return new Promise((resolve, reject) => {
+ socket.on('message', (raw) => {
+ if (JSON.parse(String(raw)).t === 'session.ready') resolve(socket);
+ });
+ socket.on('error', reject);
+ });
+}
+
+function rawSessionRefusal(relayId) {
+ const socket = new WebSocket(`${base}/v1/bridge?relay_id=${relayId}`, { headers: { authorization: `Bearer ${SERVICE_TOKEN}` } });
+ return new Promise((resolve, reject) => {
+ socket.on('message', (raw) => {
+ const frame = JSON.parse(String(raw));
+ if (frame.t === 'session.close') resolve(frame);
+ });
+ socket.on('error', reject);
+ });
+}
+
+it('speaks one protocol version everywhere', () => {
+ expect(PROTOCOL_VERSION).toBe(1);
+});
diff --git a/tests/home-tools.test.js b/tests/home-tools.test.js
index 0cf72d0ae..79f8c6809 100644
--- a/tests/home-tools.test.js
+++ b/tests/home-tools.test.js
@@ -174,7 +174,13 @@ live('against a real Home Assistant', () => {
// a model reads them as values, not in the narrative line where it reads
// them as instruction.
const result = await asOwner('home_status', { home_id: home.id });
- const names = result.structured.rooms.flatMap((r) => r.entities.map((e) => e.name));
+ // Rooms plus unassigned: a house where nobody has assigned entities to
+ // areas is an ordinary house, not a broken one, and its names are just as
+ // attacker-controlled.
+ const names = [
+ ...result.structured.rooms.flatMap((r) => r.entities.map((e) => e.name)),
+ ...result.structured.unassigned.map((e) => e.name),
+ ];
expect(names.length).toBeGreaterThan(0);
for (const name of names) expect(result.text).not.toContain(name);
}, 60_000);
diff --git a/vercel.json b/vercel.json
index ef9184766..72afdd1b7 100644
--- a/vercel.json
+++ b/vercel.json
@@ -2067,6 +2067,10 @@
"src": "/smart-home/plan/?",
"dest": "/smart-home-plan.html"
},
+ {
+ "src": "/smart-home/join/?",
+ "dest": "/smart-home-join.html"
+ },
{
"src": "/smart-home/([0-9a-fA-F-]{36})/?",
"dest": "/smart-home.html"
diff --git a/vite.config.js b/vite.config.js
index b2de49c6b..15b17e429 100644
--- a/vite.config.js
+++ b/vite.config.js
@@ -543,6 +543,7 @@ const appConfig = {
'home-scene': resolve(__dirname, 'pages/home-scene.html'),
materialize: resolve(__dirname, 'pages/materialize.html'),
'smart-home': resolve(__dirname, 'pages/smart-home.html'),
+ 'smart-home-join': resolve(__dirname, 'pages/smart-home-join.html'),
'smart-home-plan': resolve(__dirname, 'pages/smart-home-plan.html'),
'smart-home-satellite': resolve(__dirname, 'pages/smart-home-satellite.html'),
'materialize-order': resolve(__dirname, 'pages/materialize-order.html'),