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
/**
* The 2D house.
*
* Not a consolation prize. This is the accessibility path, the old-device path
* and the "WebGL is blocked by policy" path, and it has to be able to do
* everything the 3D scene can do: read the whole house and act on it. It reads
* the SAME scene model, so a room that exists in one exists in the other and
* the two cannot drift.
*
* It is also the automatic destination for a device that measurably cannot hold
* a frame rate, which is why it is built to be genuinely good rather than
* merely present.
*/
import { formatNumber, locale, plural, t } from './i18n-home.js';
/**
* Domains a person can act on from here, and the two services each offers.
*
* The third slot is a catalog key, not a label: the label is resolved at render
* time so switching language re-renders into the new one rather than keeping
* whatever was current when this module was first evaluated.
*/
const CONTROLS = {
light: { on: ['light', 'turn_on', 'act_turn_on', 'Turn on'], off: ['light', 'turn_off', 'act_turn_off', 'Turn off'] },
switch: { on: ['switch', 'turn_on', 'act_turn_on', 'Turn on'], off: ['switch', 'turn_off', 'act_turn_off', 'Turn off'] },
fan: { on: ['fan', 'turn_on', 'act_turn_on', 'Turn on'], off: ['fan', 'turn_off', 'act_turn_off', 'Turn off'] },
lock: { on: ['lock', 'unlock', 'act_unlock', 'Unlock'], off: ['lock', 'lock', 'act_lock', 'Lock'] },
cover: { on: ['cover', 'open_cover', 'act_open', 'Open'], off: ['cover', 'close_cover', 'act_close', 'Close'] },
media_player: { on: ['media_player', 'media_play', 'act_play', 'Play'], off: ['media_player', 'media_pause', 'act_pause', 'Pause'] },
vacuum: { on: ['vacuum', 'start', 'act_start', 'Start'], off: ['vacuum', 'return_to_base', 'act_send_home', 'Send home'] },
};
/**
* @param {HTMLElement} container
* @param {object} options
* @param {(request: { entityId: string, domain: string, service: string, name: string, roomId: string }) => void} options.onAct
* @param {(roomId: string) => void} [options.onFocusRoom]
*/
export function createHomeFallback(container, options = {}) {
container.classList.add('hs-flat');
container.innerHTML = '';
const list = document.createElement('div');
list.className = 'hs-flat-floors';
container.appendChild(list);
let model = null;
let stale = false;
let busy = new Set();
/**
* Rebuild the flat house, and put the keyboard back where it was.
*
* This list is the accessible route into a live house: a canvas is one opaque
* element, so for a screen-reader or keyboard user these rows ARE the house.
* And a live house never stops talking. Every state event on the stream (a
* light dimming, a sensor ticking, the demo integration's thermostat drifting)
* lands here and rebuilds every node, which used to drop the focused control
* on the floor mid-press: the person tabs to Unlock, the kitchen sensor
* reports, the button they were on is destroyed and their Enter goes to the
* document. Measured against a real Home Assistant, where it also made the
* no-mouse journey in tests/e2e/home-a11y.spec.js fail at random.
*
* The fix is to restore by identity rather than by node: `data-act-for` plus
* `data-act-service` name an action control, `data-entity-id` a device row and
* `data-room-id` a room, and each one's replacement is the same control by
* every measure a person cares about. Selection state (`scrollTop`) is left
* alone by the rebuild, so only focus needs carrying.
*/
function render() {
if (!model) return;
const keep = focusKey(document.activeElement);
list.innerHTML = '';
for (const floor of model.floors) {
const section = document.createElement('section');
section.className = 'hs-flat-floor';
const heading = document.createElement('h2');
heading.className = 'hs-flat-floor-name';
heading.textContent = floor.name;
section.appendChild(heading);
const grid = document.createElement('div');
grid.className = 'hs-flat-grid';
for (const roomId of floor.roomIds) {
const room = model.rooms.find((r) => r.id === roomId);
if (room) grid.appendChild(roomCard(room));
}
section.appendChild(grid);
list.appendChild(section);
}
if (keep) restoreFocus(keep);
}
/**
* A selector that finds this element's replacement after a rebuild, or null
* when the element is not one of ours (the page's own chrome keeps its focus
* without help, because this only ever replaces what is inside `list`).
*/
function focusKey(node) {
if (!(node instanceof HTMLElement) || !list.contains(node)) return null;
if (node.dataset.actFor) {
return `[data-act-for="${cssEscape(node.dataset.actFor)}"]` +
(node.dataset.actService ? `[data-act-service="${cssEscape(node.dataset.actService)}"]` : '');
}
if (node.dataset.entityId) return `[data-entity-id="${cssEscape(node.dataset.entityId)}"]`;
if (node.dataset.roomId) return `[data-room-id="${cssEscape(node.dataset.roomId)}"]`;
return null;
}
function restoreFocus(selector) {
const again = list.querySelector(selector);
// Not an error when it is gone: a device really can leave the house
// between two frames, and the reader is better off where the browser puts
// them than focused on something that is no longer there.
if (again instanceof HTMLElement) again.focus({ preventScroll: true });
}
function roomCard(room) {
const card = document.createElement('article');
card.className = 'hs-card';
card.dataset.roomId = room.id;
if (stale) card.classList.add('is-stale');
// The room's real light, as a real gradient: a dark room is dark here too.
card.style.setProperty('--room-light', room.light.hex);
card.style.setProperty('--room-glow', String(room.light.on ? Math.min(0.55, 0.12 + room.light.brightness * 0.4) : 0));
const head = document.createElement('header');
head.className = 'hs-card-head';
const title = document.createElement('button');
title.type = 'button';
title.className = 'hs-card-title';
title.textContent = room.name;
title.addEventListener('click', () => options.onFocusRoom?.(room.id));
head.appendChild(title);
const meta = document.createElement('p');
meta.className = 'hs-card-meta';
const bits = [];
bits.push(room.light.total
? t('home_scene.flat_lights_on', '{{on}} of {{total}} lights on', { on: formatNumber(room.light.count), total: formatNumber(room.light.total) })
: t('home_scene.flat_no_lights', 'no lights'));
if (room.climate) {
bits.push(plural(
'home_scene.flat_from_sensors',
room.climate.sources,
'{{label}} from {{count}} sensor',
'{{label}} from {{count}} sensors',
{ label: room.climate.label },
));
}
if (room.security) {
bits.push(room.security.secure
? t('home_scene.flat_secure', 'secure')
: t('home_scene.flat_open_count', '{{count}} open', { count: formatNumber(room.security.unlocked.length + room.security.open.length) }));
}
meta.textContent = bits.join(' · ');
head.appendChild(meta);
card.appendChild(head);
if (room.security && !room.security.secure) {
const flag = document.createElement('p');
flag.className = 'hs-card-flag';
flag.textContent = describeOpen(room);
card.appendChild(flag);
}
const items = document.createElement('ul');
items.className = 'hs-card-items';
for (const object of room.objects) items.appendChild(entityRow(object, room));
card.appendChild(items);
if (room.readouts.length) {
const readouts = document.createElement('dl');
readouts.className = 'hs-card-readouts';
for (const readout of room.readouts) {
const dt = document.createElement('dt');
dt.textContent = readout.name;
const dd = document.createElement('dd');
dd.textContent = `${readout.value}${readout.unit ? ` ${readout.unit}` : ''}`;
readouts.append(dt, dd);
}
card.appendChild(readouts);
}
if (room.hiddenCount) {
const more = document.createElement('p');
more.className = 'hs-card-more';
more.textContent = plural('home_scene.flat_hidden', room.hiddenCount, '{{count}} more device in this room', '{{count}} more devices in this room');
card.appendChild(more);
}
return card;
}
function entityRow(object, room) {
const row = document.createElement('li');
row.className = 'hs-item';
row.dataset.entityId = object.entityId;
if (!object.available) row.classList.add('is-unavailable');
const dot = document.createElement('span');
dot.className = 'hs-item-dot';
dot.dataset.kind = object.kind;
dot.style.setProperty('--dot', dotColor(object, room));
dot.setAttribute('aria-hidden', 'true');
row.appendChild(dot);
const name = document.createElement('span');
name.className = 'hs-item-name';
name.textContent = object.name;
row.appendChild(name);
const state = document.createElement('span');
state.className = 'hs-item-state';
state.textContent = object.available ? readableState(object) : t('home_scene.unreachable', 'unreachable');
row.appendChild(state);
const control = CONTROLS[object.domain];
if (control && object.available) {
const active = object.activity > 0.02;
const [domain, service, key, source] = active ? control.off : control.on;
const label = t(`home_scene.${key}`, source);
const button = document.createElement('button');
button.type = 'button';
button.className = 'hs-item-act';
// Which control this is, in terms that survive the rebuild this list
// does on every busy change. scene.js's restoreConfirmFocus finds the
// replacement by these two attributes when the guarded confirmation
// is answered and the node it was opened from has gone.
button.dataset.actFor = object.entityId;
button.dataset.actService = `${domain}.${service}`;
const working = busy.has(object.entityId);
button.textContent = working ? t('home_scene.working', 'Working') : label;
// aria-disabled, not the disabled property. A disabled button cannot
// hold focus, so the browser blurs it the instant the request starts
// and a keyboard user is dropped at the top of the document for the
// length of a round trip. This reads as disabled to a screen reader,
// looks disabled, refuses the press below, and keeps the keyboard.
if (working) button.setAttribute('aria-disabled', 'true');
// The device's name and its room's name are the user's own words, so
// they are interpolated rather than concatenated into a translatable
// sentence: a catalog string with "Front Door" baked into it would be
// machine-translated on the next run.
button.setAttribute('aria-label', t('home_scene.act_aria', '{{action}} {{name}} in {{room}}', { action: label, name: object.name, room: room.name }));
button.addEventListener('click', () => {
if (button.getAttribute('aria-disabled') === 'true') return;
options.onAct?.({ entityId: object.entityId, domain, service, name: object.name, roomId: room.id });
});
row.appendChild(button);
}
return row;
}
function dotColor(object, room) {
if (!object.available) return 'rgba(224, 90, 74, 0.55)';
if (object.domain === 'light') return object.activity > 0 ? room.light.hex : 'rgba(255,255,255,0.16)';
if (object.domain === 'lock') return object.activity > 0.5 ? '#e05a4a' : '#2fbf71';
if (object.domain === 'cover' || object.domain === 'binary_sensor') return object.activity > 0.02 ? '#e0a33a' : 'rgba(255,255,255,0.16)';
return object.activity > 0.4 ? '#8fa6ff' : 'rgba(255,255,255,0.16)';
}
function readableState(object) {
if (object.domain === 'cover') {
const position = Number(object.attributes?.current_position);
if (Number.isFinite(position)) {
if (position === 0) return t('home_scene.state_closed', 'closed');
if (position === 100) return t('home_scene.state_open', 'open');
return t('home_scene.state_part_open', '{{percent}} open', { percent: percent(position) });
}
}
if (object.domain === 'climate') {
const current = Number(object.attributes?.current_temperature);
// The house's own unit, straight off the model. A bare degree sign made
// a thermostat unreadable: 21 and 70 are both plausible room
// temperatures, and which one is comfortable depends entirely on the
// symbol this line used to leave off.
if (Number.isFinite(current)) return `${object.state} · ${current}${model?.temperatureUnit || '°'}`;
}
if (object.domain === 'light' && object.activity > 0) {
const brightness = Number(object.attributes?.brightness);
if (Number.isFinite(brightness)) {
return t('home_scene.state_on_at', 'on · {{percent}}', { percent: percent(Math.round((brightness / 255) * 100)) });
}
}
return String(object.state);
}
function describeOpen(room) {
const names = [];
for (const entityId of [...room.security.unlocked, ...room.security.open]) {
const object = room.objects.find((o) => o.entityId === entityId);
names.push(object ? object.name : entityId);
}
if (!names.length) return t('home_scene.something_open', 'Something in this room is open.');
// The device names are the user's own and are joined with the reader's own
// list separator; only the sentence around them is copy. English "is/are"
// and the "and 2 more" tail are both catalog keys so a locale can put them
// where its own grammar needs them.
const shown = names.slice(0, 3);
if (names.length > 3) shown.push(t('home_scene.n_more', '{{count}} more', { count: formatNumber(names.length - 3) }));
const extra = listFormat(shown);
return room.security.unlocked.length
? plural('home_scene.is_unlocked', names.length, '{{names}} is unlocked.', '{{names}} are unlocked.', { names: extra })
: plural('home_scene.is_open', names.length, '{{names}} is open.', '{{names}} are open.', { names: extra });
}
return {
setModel(next) {
model = next;
render();
},
setStale(next) {
stale = Boolean(next);
container.classList.toggle('is-stale', stale);
for (const card of list.querySelectorAll('.hs-card')) card.classList.toggle('is-stale', stale);
},
setBusy(entityIds) {
busy = new Set(entityIds);
render();
},
focusRoom(roomId) {
const card = list.querySelector(`[data-room-id="${cssEscape(roomId)}"]`);
// Someone who asked for less motion gets the card placed, not flown to.
const reduce = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
card?.scrollIntoView({ behavior: reduce ? 'auto' : 'smooth', block: 'center' });
card?.classList.add('is-focused');
setTimeout(() => card?.classList.remove('is-focused'), 1800);
},
/** Same shape the WebGL scene exposes, so the page treats them alike. */
setActing(next) {
if (next?.roomId) this.focusRoom(next.roomId);
},
stats() {
return { fps: 0, objects: model ? model.stats.drawn : 0, rooms: model ? model.rooms.length : 0, mode: '2d' };
},
dispose() {
container.innerHTML = '';
container.classList.remove('hs-flat');
},
};
}
/** A percentage in the reader's own locale, never `${n}%`. */
function percent(value) {
try {
return new Intl.NumberFormat(locale(), { style: 'percent', maximumFractionDigits: 0 }).format(Number(value) / 100);
} catch {
return `${value}%`;
}
}
/** "a, b and c" in the reader's own language, never a hardcoded comma-and. */
function listFormat(items) {
try {
return new Intl.ListFormat(locale(), { style: 'long', type: 'conjunction' }).format(items);
} catch {
return items.join(', ');
}
}
function cssEscape(value) {
return typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(value) : String(value).replace(/["\\]/g, '\\$&');
}
/**
* Can this browser actually run the 3D scene? Asked once, answered honestly:
* a context that fails to create, a software rasterizer, or a device the caller
* already measured as too slow all route to the 2D house rather than to a black
* canvas with a spinner over it.
*/
export function webglAvailable() {
if (typeof document === 'undefined') return false;
try {
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
if (!gl) return false;
const lose = gl.getExtension('WEBGL_lose_context');
lose?.loseContext();
return true;
} catch {
return false;
}
}