Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
#!/usr/bin/env node
/**
* Measure the live 3D home against a real house.
*
* `/smart-home/:id` makes four performance claims: it paints quickly from cold,
* it holds a frame rate on a desktop and on a phone, it reflects a real device
* within a frame of hearing about it, and it does not leak while it runs for
* hours on a wall display. Those numbers are quoted in
* [docs/home-scene.md](../docs/home-scene.md), and a quoted number nobody can
* re-derive rots into folklore. This script re-derives all of them.
*
* Nothing here is simulated. The house is a real Home Assistant, every state
* change is a real service call against a real device, the page is the shipped
* page, and the heap is read out of V8 through the DevTools protocol after a
* forced collection, so a sample is the memory that survived rather than the
* memory that had not been swept yet.
*
* Bring a stack up first (a house, the API, the frontend). The home e2e config
* builds exactly that stack and leaves its details in `.ha-config-e2e-stack.json`,
* which is the default input here:
*
* node scripts/home-test-instance.mjs --name scene06 --up --onboard --seed --json
* node --env-file=.env.local server/index.mjs & # API on 8098
* DEV_API_PROXY=http://127.0.0.1:8098 npx vite --port 3021 &
* node scripts/measure-home-scene.mjs --origin http://localhost:3021 --minutes 10
*
* Output is a JSON report on stdout and, with `--out`, a PNG per state.
*/
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { chromium } from 'playwright';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const opts = parseArgs(process.argv.slice(2));
if (opts.help) {
usage();
process.exit(0);
}
const stack = readStack(opts.stack);
const ORIGIN = opts.origin || stack.origin || 'http://localhost:3021';
const HOUSE = stack.home;
const ACCOUNT = stack.accounts?.owner;
if (!HOUSE?.baseUrl || !HOUSE?.token) fail('the stack file has no house. Run the home e2e config once, or pass --stack.');
if (!ACCOUNT?.email) fail('the stack file has no owner account.');
/** How long the heap trace runs. Ten minutes is the documented claim. */
const MINUTES = Number(opts.minutes ?? 10);
/** Round trips measured for the end to end latency figure. */
const LATENCY_TRIALS = Number(opts.trials ?? 8);
const report = {
measuredAt: new Date().toISOString(),
origin: ORIGIN,
house: { version: HOUSE.version || null },
// What else this machine was doing. A frame rate read off a box with a load
// average of sixty is a measurement of the box, and a reader who cannot see
// that has been handed a number that looks like a product fact.
machine: { cpus: os.cpus().length, loadAverageAtStart: os.loadavg().map((n) => Math.round(n * 100) / 100) },
};
await main();
async function main() {
const browser = await chromium.launch({ args: ['--enable-precise-memory-info', '--use-gl=swiftshader'] });
try {
const context = await browser.newContext({ viewport: { width: 1440, height: 900 } });
await signIn(context);
const homeId = await connectHouse(context);
report.homeId = homeId;
// Every page this run opens, not just the 3D one: the flat view, the empty
// house and the error screen are part of the product and a warning on any
// of them counts.
const errors = [];
context.on('page', (opened) => {
opened.on('console', (msg) => {
if (msg.type() === 'error' || msg.type() === 'warning') errors.push(`${msg.type()}: ${msg.text()}`);
});
opened.on('pageerror', (err) => errors.push(`pageerror: ${err.message}`));
});
const page = await context.newPage();
report.routes = await checkRoutes(context, homeId);
report.coldPaint = await measureColdPaint(page, homeId);
// --states-only exists for the second pass over a differently configured
// house: the numbers do not change with the wallpaper, and re-running a
// ten minute heap trace to photograph one more empty state is waste.
if (!opts['states-only']) {
report.desktop = await measureFrameRate(page, 'desktop');
report.latency = await measureLatency(page);
report.heap = await measureHeap(page, MINUTES);
report.mobile = await measureMobile(context, homeId);
}
report.console = errors;
if (opts.out) report.screenshots = await captureStates(context, page, homeId);
await disconnectHouse(context, homeId);
} finally {
await browser.close();
}
process.stdout.write(`${JSON.stringify(report, null, '\t')}\n`);
}
// ---------------------------------------------------------------- the stack
async function signIn(context) {
const res = await context.request.post(`${ORIGIN}/api/auth/login`, {
data: { email: ACCOUNT.email, password: ACCOUNT.password },
headers: { 'content-type': 'application/json' },
timeout: 60_000,
});
if (!res.ok()) fail(`login returned ${res.status()}: ${(await res.text()).slice(0, 200)}`);
}
/**
* Connect the house through the real endpoint.
*
* A fresh row every run, and removed again at the end. The stored Home
* Assistant token is encrypted with the API process's key, which a local stack
* generates per run, so a row left behind by an earlier run is one this run
* cannot read: reuse would fail as a product error rather than as the stale
* credential it is.
*/
async function connectHouse(context) {
const label = opts.label || `Scene measurement ${new Date().toISOString().slice(11, 19)}`;
const token = await csrf(context);
const res = await context.request.post(`${ORIGIN}/api/home`, {
data: { label, baseUrl: HOUSE.baseUrl, token: HOUSE.token },
headers: { 'content-type': 'application/json', 'x-csrf-token': token },
timeout: 120_000,
});
if (!res.ok()) fail(`connecting the house returned ${res.status()}: ${(await res.text()).slice(0, 300)}`);
const body = await res.json();
const id = body?.home?.id || body?.data?.home?.id || body?.id;
if (!id) fail(`the connect response carried no home id: ${JSON.stringify(body).slice(0, 200)}`);
return id;
}
/** Take the measurement house back off the account, so runs leave nothing. */
async function disconnectHouse(context, homeId) {
const token = await csrf(context);
await context.request
.delete(`${ORIGIN}/api/home/${homeId}`, { headers: { 'x-csrf-token': token }, timeout: 60_000 })
.catch(() => {});
}
async function csrf(context) {
const res = await context.request.get(`${ORIGIN}/api/csrf-token`, { timeout: 30_000 });
if (!res.ok()) fail(`csrf token returned ${res.status()}`);
const body = await res.json();
return (body.data || body).token;
}
/**
* Both addresses really serve this page.
*
* `/smart-home/:id` is where the connect flow lands and `/home/:id` is the
* campaign's own address for the same house. They are two rows in the route
* table, so one of them can rot without the other noticing.
*/
async function checkRoutes(context, homeId) {
const out = {};
for (const route of [`/smart-home/${homeId}`, `/home/${homeId}`]) {
const res = await context.request.get(`${ORIGIN}${route}`, { timeout: 60_000 });
const body = res.ok() ? await res.text() : '';
out[route] = { status: res.status(), servesScene: body.includes('src/home/scene.js') };
}
return out;
}
/** Open the scene and wait until the renderer has drawn a frame of the house. */
async function openScene(page, homeId, { view = '3d' } = {}) {
await page.goto(`${ORIGIN}/smart-home/${homeId}?view=${view}`, { waitUntil: 'domcontentloaded' });
if (view === '3d') {
await page.waitForFunction(() => window.__homeScene?.stats()?.drawCalls > 0, null, { timeout: 240_000 });
} else {
await page.waitForSelector('.hs-card', { timeout: 240_000 });
}
}
// ---------------------------------------------------------------- the numbers
/**
* Cold paint: a context with no cache, no session storage and no warm module
* graph, timed from navigation start to the first frame that actually drew the
* house. Reloading a warm page would measure the cache, not the product.
*/
async function measureColdPaint(page, homeId) {
const started = Date.now();
await openScene(page, homeId);
const wall = Date.now() - started;
const marks = await page.evaluate(() => {
const nav = performance.getEntriesByType('navigation')[0];
const paint = performance.getEntriesByName('first-contentful-paint')[0];
return {
firstContentfulPaintMs: paint ? Math.round(paint.startTime) : null,
domContentLoadedMs: nav ? Math.round(nav.domContentLoadedEventEnd) : null,
};
});
const model = await page.evaluate(() => ({
rooms: window.__homeScene.model.rooms.length,
floors: window.__homeScene.model.floors.length,
entities: window.__homeScene.model.stats.entities,
drawn: window.__homeScene.model.stats.drawn,
}));
return { navigationToDrawnHouseMs: wall, ...marks, model, stats: await page.evaluate(() => window.__homeScene.stats()) };
}
/**
* Frame rate, sampled from the renderer's own counter over a real window of
* wall-clock time with the tab visible and the house live.
*/
async function measureFrameRate(page, label, seconds = 20) {
const samples = [];
for (let i = 0; i < seconds; i += 1) {
await page.waitForTimeout(1000);
const stats = await page.evaluate(() => window.__homeScene.stats());
samples.push(stats.fps);
}
const stats = await page.evaluate(() => window.__homeScene.stats());
return { label, samples, median: median(samples), min: Math.min(...samples), updateMs: stats.updateMs, renderMs: stats.renderMs, drawCalls: stats.drawCalls, objects: stats.objects };
}
/**
* End to end: from the instant the service call leaves this process to the
* animation frame in the page that first carries the new state.
*
* The page side is a requestAnimationFrame loop reading the same model the
* renderer draws, so the timestamp is the frame that shows the change and not
* the socket message that preceded it. Both clocks are `Date.now()` in the same
* machine, and the page's own `__homeScene.latency` (SSE frame to painted
* frame) is reported beside it so the network leg can be told from ours.
*/
async function measureLatency(page) {
const light = await anyLight();
const samples = [];
for (let i = 0; i < LATENCY_TRIALS; i += 1) {
const before = await readState(light.entityId);
const wanted = before === 'on' ? 'off' : 'on';
await page.evaluate(
({ id, want }) => {
window.__sceneWatch = { at: null };
const tick = () => {
for (const room of window.__homeScene.model.rooms) {
const found = room.objects.find((o) => o.entityId === id);
if (found && found.state === want) {
window.__sceneWatch.at = Date.now();
return;
}
}
requestAnimationFrame(tick);
};
requestAnimationFrame(tick);
},
{ id: light.entityId, want: wanted },
);
const sent = Date.now();
await callService(`light/turn_${wanted}`, light.entityId);
const seenAt = await page.waitForFunction(() => window.__sceneWatch?.at, null, { timeout: 60_000 }).then((h) => h.jsonValue());
samples.push(seenAt - sent);
await page.waitForTimeout(400);
}
const inPage = await page.evaluate(() => window.__homeScene.latency);
return {
entityId: light.entityId,
callToPaintedFrameMs: { samples, median: median(samples), worst: Math.max(...samples) },
sseFrameToPaintedFrameMs: { samples: inPage.samples.slice(-LATENCY_TRIALS), median: median(inPage.samples.slice(-LATENCY_TRIALS)) },
};
}
/**
* The heap, over a run of real device changes.
*
* Every sample is taken after `HeapProfiler.collectGarbage`, so what is
* reported is retained memory rather than garbage that had not been swept.
* That is the only reading that can distinguish a leak from a sawtooth, and a
* leak here is a wall display that dies overnight.
*/
async function measureHeap(page, minutes) {
const client = await page.context().newCDPSession(page);
await client.send('HeapProfiler.enable');
await client.send('Performance.enable');
const lights = await allLights();
const samples = [];
const sample = async (t) => {
await client.send('HeapProfiler.collectGarbage');
const metrics = await client.send('Performance.getMetrics');
const used = metrics.metrics.find((m) => m.name === 'JSHeapUsedSize')?.value ?? 0;
const stats = await page.evaluate(() => window.__homeScene.stats());
samples.push({ minute: t, heapMB: round2(used / 1024 / 1024), objects: stats.objects, geometries: stats.geometries, textures: stats.textures, fps: stats.fps });
};
await sample(0);
let changes = 0;
for (let minute = 1; minute <= minutes; minute += 1) {
const until = Date.now() + 60_000;
while (Date.now() < until) {
const light = lights[changes % lights.length];
await callService(`light/turn_${changes % 2 ? 'on' : 'off'}`, light);
changes += 1;
await page.waitForTimeout(4000);
}
await sample(minute);
}
const first = samples[0];
const last = samples[samples.length - 1];
return {
minutes,
realDeviceChanges: changes,
samples,
growthMB: round2(last.heapMB - first.heapMB),
objectsHeld: last.objects === first.objects && last.geometries === first.geometries && last.textures === first.textures,
};
}
/**
* A phone, as closely as a headless desktop can honestly be one: a phone
* viewport, a touch device, and the CPU throttled through the DevTools
* protocol. The GPU is still this machine's, which is why the number reported
* is labelled as CPU throttled rather than as a phone measurement.
*/
async function measureMobile(context, homeId) {
const page = await context.newPage();
await page.setViewportSize({ width: 390, height: 844 });
const client = await context.newCDPSession(page);
await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });
try {
await openScene(page, homeId);
const result = await measureFrameRate(page, 'cpu-throttled-4x-390px', 15);
result.routedToFallback = await page.evaluate(() => window.__homeScene.status.view === '2d');
return result;
} finally {
await client.send('Emulation.setCPUThrottlingRate', { rate: 1 });
await page.close();
}
}
// ---------------------------------------------------------------- the states
/** One PNG per state, into --out. */
async function captureStates(context, page, homeId) {
const dir = path.resolve(ROOT, opts.out);
fs.mkdirSync(dir, { recursive: true });
const shot = async (target, name) => {
const file = path.join(dir, `${name}.png`);
await target.screenshot({ path: file });
return path.relative(ROOT, file);
};
const shots = {};
// 1. loading: a context with nothing cached, caught before the graph lands.
const cold = await context.newPage();
await cold.setViewportSize({ width: 1440, height: 900 });
await cold.goto(`${ORIGIN}/smart-home/${homeId}`, { waitUntil: 'commit' });
await cold.waitForSelector('.hs-skeleton', { timeout: 30_000 });
shots.loading = await shot(cold, '01-loading');
await cold.close();
// 4. live, and 7. acting, and 8. confirmation pending: the running house.
await openScene(page, homeId);
await page.waitForTimeout(1500);
shots.live = await shot(page, '04-live');
shots.liveChange = await captureLiveChange(page, dir);
shots.acting = await captureActing(page);
shots.confirmation = await captureConfirmation(page);
// 9. the 2D house, which is also the no-WebGL path.
const flat = await context.newPage();
await flat.setViewportSize({ width: 1440, height: 900 });
await flat.addInitScript(() => {
const original = HTMLCanvasElement.prototype.getContext;
HTMLCanvasElement.prototype.getContext = function (type, ...rest) {
if (String(type).startsWith('webgl')) return null;
return original.call(this, type, ...rest);
};
});
await flat.goto(`${ORIGIN}/smart-home/${homeId}`, { waitUntil: 'domcontentloaded' });
await flat.waitForSelector('.hs-card', { timeout: 120_000 });
shots.noWebgl = await shot(flat, '09-no-webgl');
await flat.close();
// 10. error: a home id that is not this account's.
const missing = await context.newPage();
await missing.setViewportSize({ width: 1440, height: 900 });
await missing.goto(`${ORIGIN}/smart-home/00000000-0000-4000-8000-000000000000`, { waitUntil: 'domcontentloaded' });
await missing.waitForSelector('.hs-overlay', { timeout: 60_000 });
shots.error = await shot(missing, '10-error');
await missing.close();
// 2 and 3: a real house with nothing in it, and one where nothing is filed.
if (opts['bare-stack']) Object.assign(shots, await captureEmptyHouse(context, shot));
// 5: the house taken away underneath the page it is drawn in.
if (HOUSE.container) Object.assign(shots, await captureLostHouse(page, shot));
// 6, and it goes last because it ends this run's home: disconnected is the
// state where nobody is retrying any more, and the run's own cleanup is
// exactly the action that produces it.
Object.assign(shots, await captureDisconnected(context, page, homeId, shot));
shots.dir = path.relative(ROOT, dir);
return shots;
}
/**
* The two states a house reaches before anyone has organised it: connected and
* exposing nothing at all, and exposing devices that are in no area.
*
* Both are real houses, not a filtered view of the seeded one: a second Home
* Assistant with no integration enabled is exactly what someone sees minutes
* after installing it.
*/
async function captureEmptyHouse(context, shot) {
const bare = JSON.parse(fs.readFileSync(path.resolve(ROOT, opts['bare-stack']), 'utf8'));
const token = await csrf(context);
const res = await context.request.post(`${ORIGIN}/api/home`, {
data: { label: `Bare house ${Date.now()}`, baseUrl: bare.baseUrl, token: bare.token },
headers: { 'content-type': 'application/json', 'x-csrf-token': token },
timeout: 120_000,
});
if (!res.ok()) return { emptyHouse: `connect failed: ${res.status()}` };
const id = (await res.json())?.home?.id;
if (!id) return { emptyHouse: 'connect returned no id' };
const page = await context.newPage();
await page.setViewportSize({ width: 1440, height: 900 });
await page.goto(`${ORIGIN}/smart-home/${id}`, { waitUntil: 'domcontentloaded' });
await page.waitForSelector('.hs-overlay h2', { timeout: 120_000 });
const heading = (await page.locator('.hs-overlay h2').first().textContent())?.trim();
// Which of the two designed nothings this house lands in is the house's own
// answer, not something to assert: a bare instance exposes nothing, and one
// with an integration on and no areas exposes devices that are in no room.
const empty = /empty/i.test(heading || '');
const file = await shot(page, empty ? '02-empty-house' : '03-nothing-in-a-room');
await page.close();
await disconnectHouse(context, id);
return { [empty ? 'emptyHouse' : 'nothingInARoom']: file, bareHouseHeading: heading };
}
/**
* Stale, then live again, by really stopping the container the house runs in.
*
* A stopped house is STALE, not disconnected, and that distinction is the point:
* the platform is still retrying and the house on screen is the last one we saw.
* Disconnected is a different state with a different cause, and
* `captureDisconnected` below produces it. The rooms must survive both.
*/
async function captureLostHouse(page, shot) {
const out = {};
await docker(['stop', HOUSE.container]);
try {
await page.locator('#hs-status[data-status="stale"]').waitFor({ timeout: 180_000 });
out.stale = await shot(page, '05-stale');
out.staleRoomsHeld = await page.evaluate(() => window.__homeScene.model.rooms.length);
} catch (err) {
out.lostHouseError = err.message;
} finally {
await docker(['start', HOUSE.container]);
}
// Back on its own, with no reload: the page recovers or the run says so. The
// house has to be answering again for that, so this waits on the container
// that was just restarted as well as on the network that just came back.
await waitForHouse();
await page
.locator('#hs-status[data-status="live"]')
.waitFor({ timeout: 300_000 })
.then(() => {
out.recoveredWithoutReload = true;
})
.catch(() => {
out.recoveredWithoutReload = false;
});
return out;
}
/**
* Disconnected: the state where nobody is retrying any more.
*
* Not reachable by taking the house away (that is stale, correctly) and not by
* taking the browser offline either, because an EventSource that is already
* established keeps delivering, so the page is right to keep saying live. It is
* reached by revoking the connection, which is what the Disconnect button does
* and what this run does at the end anyway. The screen showing that house has to
* be told, and this is the check that it was.
*/
async function captureDisconnected(context, page, homeId, shot) {
const out = {};
const before = await page.evaluate(() => window.__homeScene.model.rooms.length).catch(() => 0);
await disconnectHouse(context, homeId);
try {
await page.locator('#hs-status[data-status="disconnected"]').waitFor({ timeout: 120_000 });
out.disconnected = await shot(page, '06-disconnected');
out.disconnectedRoomsHeld = await page.evaluate(() => window.__homeScene.model.rooms.length);
out.disconnectedHeldEveryRoom = out.disconnectedRoomsHeld === before;
out.disconnectedOffersReconnect = await page.locator('#hs-reconnect:not([hidden])').isVisible();
// The reason, not a generic drop: the frame that explains it arrives just
// ahead of the stream closing behind it, and the close must not erase it.
out.disconnectedSays = await page.locator('#hs-status').getAttribute('title');
} catch (err) {
out.disconnectedError = err.message;
}
return out;
}
/** Wait until the house itself answers again after a stop and start. */
async function waitForHouse() {
for (let i = 0; i < 90; i += 1) {
const ok = await haFetch('/api/')
.then((r) => r.ok)
.catch(() => false);
if (ok) return true;
await new Promise((resolve) => setTimeout(resolve, 2000));
}
return false;
}
async function docker(args) {
const { execFile } = await import('node:child_process');
await new Promise((resolve, reject) => execFile('docker', args, (err) => (err ? reject(err) : resolve())));
}
/**
* A frame sequence of a real light being switched in Home Assistant.
*
* One frame before the service call and a frame every 150 ms after it, of the
* canvas alone. The light is chosen in the room the camera is already looking
* at, so the change is inside the frame rather than behind it.
*/
async function captureLiveChange(page, dir) {
const target = await page.evaluate(() => {
const model = window.__homeScene.model;
const room = model.rooms.find((r) => r.id === model.focusRoomId) || model.rooms[0];
const light = room?.objects.find((o) => o.domain === 'light');
return light ? { entityId: light.entityId, state: light.state, room: room.name } : null;
});
if (!target) return null;
const stage = page.locator('#hs-stage canvas');
const frames = [];
const shoot = async (name) => {
const file = path.join(dir, `${name}.png`);
await stage.screenshot({ path: file });
frames.push(path.relative(ROOT, file));
};
await shoot('02-live-change-0-before');
const wanted = target.state === 'on' ? 'off' : 'on';
const sent = Date.now();
await callService(`light/turn_${wanted}`, target.entityId);
for (let i = 1; i <= 6; i += 1) {
await page.waitForTimeout(150);
await shoot(`02-live-change-${i}-t${i * 150}ms`);
}
const seen = await page.evaluate(
(id) => {
for (const room of window.__homeScene.model.rooms) {
const found = room.objects.find((o) => o.entityId === id);
if (found) return found.state;
}
return null;
},
target.entityId,
);
return { entityId: target.entityId, room: target.room, from: target.state, to: seen, wanted, elapsedMs: Date.now() - sent, frames };
}
/**
* Select a real object by clicking the canvas where that object actually is.
*
* The page raycasts from the pointer, so this is the user's own gesture rather
* than a synthetic selection. An object can be behind a wall from the current
* camera, which is why the caller passes candidates and the inspector is read
* back to confirm which one was actually hit.
*/
async function clickEntity(page, entityId) {
const selected = async () =>
(
await page
.locator('.hs-entity-id')
.textContent({ timeout: 5000 })
.catch(() => null)
)?.trim() === entityId;
const at = await page.evaluate((id) => window.__homeScene.project(id), entityId);
const box = await page.locator('#hs-stage canvas').boundingBox();
if (at?.visible && box) {
await page.mouse.click(box.x + at.x, box.y + at.y);
if (await selected()) return true;
}
// The raycast can legitimately miss: the object is behind the camera, another
// object is in front of it, or this box is loaded enough that the camera has
// moved between the projection and the click. None of that is a device a
// person cannot reach, because the room rail lists every one of them and is
// the keyboard route to the same selection. Falling back to it keeps the
// measurement about the product rather than about pointer luck.
//
// The rail lists devices for the room it is focused on, so the room comes
// first, exactly as a person using the keyboard would do it.
const roomId = await page.evaluate(
(id) => window.__homeScene.model.rooms.find((room) => room.objects.some((o) => o.entityId === id))?.id || null,
entityId,
);
if (!roomId) return false;
const room = page.locator(`.hs-room[data-room-id="${cssValue(roomId)}"]`).first();
if (!(await room.count())) return false;
await room.click();
const row = page.locator(`.hs-room-device[data-entity-id="${cssValue(entityId)}"]`).first();
await row.waitFor({ timeout: 10_000 }).catch(() => {});
if (!(await row.count())) return false;
await row.scrollIntoViewIfNeeded().catch(() => {});
await row.click();
return selected();
}
/** Quote a Home Assistant id for a CSS attribute selector. */
function cssValue(value) {
return String(value).replace(/["\\]/g, '\\$&');
}
/** Every drawn object of a domain, room by room. */
async function objectsOfDomain(page, domain) {
return page.evaluate(
(want) => window.__homeScene.model.rooms.flatMap((room) => room.objects.filter((o) => o.domain === want).map((o) => o.entityId)),
domain,
);
}
/** Act on a real unguarded device and catch the beat where its room lights up. */
async function captureActing(page) {
for (const entityId of await objectsOfDomain(page, 'light')) {
if (!(await clickEntity(page, entityId))) continue;
const button = page.locator('#hs-inspector').getByRole('button', { name: /^Turn (on|off)$/ }).first();
if (!(await button.count())) continue;
await button.click();
// Inside setActing's hold, so the highlighted room is on screen.
await page.waitForTimeout(600);
const file = path.join(path.resolve(ROOT, opts.out), '07-acting.png');
await page.screenshot({ path: file });
return path.relative(ROOT, file);
}
return null;
}
/** Ask a real lock to open, which the gate answers with a question. */
async function captureConfirmation(page) {
for (const entityId of await objectsOfDomain(page, 'lock')) {
if (!(await clickEntity(page, entityId))) continue;
const button = page.locator('#hs-inspector').getByRole('button', { name: /^(Unlock|Lock)$/ }).first();
if (!(await button.count())) continue;
const risky = (await button.textContent())?.trim() === 'Unlock';
if (!risky) continue;
await button.click();
await page.waitForSelector('.hs-confirm', { timeout: 30_000 });
const file = path.join(path.resolve(ROOT, opts.out), '08-confirmation.png');
await page.screenshot({ path: file });
return path.relative(ROOT, file);
}
return null;
}
// ---------------------------------------------------------------- the house
async function haFetch(pathname, init = {}) {
const res = await fetch(`${HOUSE.baseUrl}${pathname}`, {
...init,
headers: { authorization: `Bearer ${HOUSE.token}`, 'content-type': 'application/json', ...(init.headers || {}) },
});
if (!res.ok) throw new Error(`Home Assistant ${pathname} answered ${res.status}`);
return res.json();
}
async function callService(service, entityId) {
return haFetch(`/api/services/${service}`, { method: 'POST', body: JSON.stringify({ entity_id: entityId }) });
}
async function readState(entityId) {
const body = await haFetch(`/api/states/${entityId}`);
return body.state;
}
async function allLights() {
const states = await haFetch('/api/states');
const lights = states.filter((s) => s.entity_id.startsWith('light.')).map((s) => s.entity_id);
if (!lights.length) throw new Error('the house has no lights to drive');
return lights;
}
async function anyLight() {
const [entityId] = await allLights();
return { entityId };
}
// ---------------------------------------------------------------- plumbing
function readStack(file) {
const target = path.resolve(ROOT, file || '.ha-config-e2e-stack.json');
if (!fs.existsSync(target)) fail(`no stack at ${path.relative(ROOT, target)}. Bring one up first; see the header of this file.`);
return JSON.parse(fs.readFileSync(target, 'utf8'));
}
function parseArgs(argv) {
const out = {};
for (let i = 0; i < argv.length; i += 1) {
const arg = argv[i];
if (!arg.startsWith('--')) continue;
const key = arg.slice(2);
if (key === 'help') out.help = true;
else out[key] = argv[i + 1]?.startsWith('--') ? true : argv[++i];
}
return out;
}
function usage() {
process.stdout.write(
[
'Measure the live 3D home against a real house.',
'',
' --origin <url> where the frontend is served (default: the stack file)',
' --stack <file> the stack description (default: .ha-config-e2e-stack.json)',
' --minutes <n> length of the heap trace (default: 10)',
' --trials <n> latency round trips (default: 8)',
' --label <text> the home label to create',
' --out <dir> write one PNG per state into this directory',
' --bare-stack <f> a second house with nothing in it, as --json from',
' scripts/home-test-instance.mjs, for the empty states',
'',
].join('\n'),
);
}
function median(values) {
if (!values.length) return null;
const sorted = [...values].sort((a, b) => a - b);
const mid = Math.floor(sorted.length / 2);
return round2(sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2);
}
function round2(value) {
return Math.round(value * 100) / 100;
}
function fail(message) {
console.error(`measure-home-scene: ${message}`);
process.exit(1);
}