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.

16.1 KB
Raw Blame
// Order 07: the authored floorplan.
//
// Three tiers, matching tests/home-store.test.js: the validator is pure and
// always runs, the store tier needs a real database, and the top tier needs a
// real Home Assistant because the whole point of the area write-back is that it
// changes the user's own registry rather than our picture of it.
//
//   HOME_LIVE=1 DATABASE_URL=... npx vitest run tests/home-layout.test.js
//
// HOME_LIVE=1 builds the house through the lane's one harness
// (scripts/home-test-instance.mjs). Set HOME_ASSISTANT_URL and
// HOME_ASSISTANT_TOKEN instead to point it at a house you already have.

import { afterAll, beforeAll, describe, expect, it } from 'vitest';

import { acquireHomeInstance, liveHomeAvailable } from './_helpers/home-instance.js';

import {
	LayoutInvalid,
	LIMITS,
	reconcileLayout,
	validateLayout,
} from '../api/_lib/home/layout.js';

// ---------------------------------------------------------------------------
// The pure tier.
// ---------------------------------------------------------------------------

describe('the layout validator', () => {
	it('accepts the shape the scene reads', () => {
		const doc = validateLayout({ rooms: { kitchen: { x: 3.2, z: -1.5, w: 5, d: 4 } } });
		expect(doc).toEqual({ format: 1, units: 'm', rooms: { kitchen: { x: 3.2, z: -1.5, w: 5, d: 4 } } });
	});

	it('rebuilds the document rather than deleting unknown keys off the caller\'s object', () => {
		// The difference matters: a delete list can be forgotten when a field is
		// added, a rebuild cannot let anything through it does not name.
		const hostile = { rooms: { kitchen: { x: 0, z: 0, __proto__: { polluted: true }, script: '<img onerror=1>' } } };
		expect(() => validateLayout(hostile)).toThrow(LayoutInvalid);
	});

	it('refuses an unknown top-level field', () => {
		expect(() => validateLayout({ rooms: {}, camera: { x: 1 } })).toThrow(/Unknown field "camera"/);
	});

	it('refuses a coordinate past the world bound instead of clamping it', () => {
		// Silently moving a room the user placed is worse than refusing the number.
		expect(() => validateLayout({ rooms: { a: { x: LIMITS.maxCoord + 1, z: 0 } } })).toThrow(/limit is 500 m/);
		expect(() => validateLayout({ rooms: { a: { x: 0, z: Number.NaN } } })).toThrow(/finite number/);
		expect(() => validateLayout({ rooms: { a: { x: 0, z: Infinity } } })).toThrow(/finite number/);
	});

	it('refuses a room smaller than its own label or larger than a field', () => {
		expect(() => validateLayout({ rooms: { a: { x: 0, z: 0, w: 0.2 } } })).toThrow(/between 1.5 and 60/);
		expect(() => validateLayout({ rooms: { a: { x: 0, z: 0, d: 900 } } })).toThrow(/between 1.5 and 60/);
	});

	it('leaves w and d absent when the author never set them, so the scene keeps its default', () => {
		const doc = validateLayout({ rooms: { a: { x: 1, z: 2 } } });
		expect(doc.rooms.a.w).toBeUndefined();
		expect(doc.rooms.a.d).toBeUndefined();
	});

	it('caps the room count and the document size', () => {
		const many = {};
		for (let i = 0; i < LIMITS.maxRooms + 1; i += 1) many[`room_${i}`] = { x: 0, z: 0 };
		expect(() => validateLayout({ rooms: many })).toThrow(/at most 200 rooms/);
	});

	it('accepts the synthetic room the scene invents for unfiled devices', () => {
		expect(validateLayout({ rooms: { __unassigned__: { x: 0, z: 0 } } }).rooms.__unassigned__).toBeDefined();
	});

	it('refuses a room id that is not one', () => {
		expect(() => validateLayout({ rooms: { 'kitchen lights!': { x: 0, z: 0 } } })).toThrow(/not a usable room id/);
		expect(() => validateLayout({ rooms: { ['a'.repeat(LIMITS.maxIdLength + 1)]: { x: 0, z: 0 } } })).toThrow(/not a usable room id/);
	});

	it('refuses a format it did not write', () => {
		expect(() => validateLayout({ format: 99, rooms: {} })).toThrow(/Unsupported layout format/);
		expect(() => validateLayout({ units: 'ft', rooms: {} })).toThrow(/metres/);
	});

	it('rounds to the centimetre, because nobody places a wall to a micrometre', () => {
		expect(validateLayout({ rooms: { a: { x: 1.23456789, z: 0 } } }).rooms.a.x).toBe(1.23);
	});

	it('refuses a non-object, an array, and a missing rooms map', () => {
		for (const bad of [null, 'x', 42, [], { rooms: [] }, { rooms: 'kitchen' }, {}]) {
			expect(() => validateLayout(bad), JSON.stringify(bad)).toThrow(LayoutInvalid);
		}
	});
});

describe('reconciling a layout against a live house', () => {
	const doc = { format: 1, units: 'm', rooms: { kitchen: { x: 0, z: 0 }, gone: { x: 7, z: 0 } } };

	it('names the rooms the house no longer has and the ones nobody placed', () => {
		const graph = { rooms: [{ id: 'kitchen' }, { id: 'bedroom' }], unassigned: [] };
		expect(reconcileLayout(doc, graph)).toEqual({ orphaned: ['gone'], unplaced: ['bedroom'] });
	});

	it('counts the synthetic bucket as a real room once anything is unfiled', () => {
		const graph = { rooms: [{ id: 'kitchen' }], unassigned: [{ entityId: 'light.x' }] };
		expect(reconcileLayout(doc, graph).unplaced).toEqual(['__unassigned__']);
	});

	it('says nothing drifted for an empty layout', () => {
		expect(reconcileLayout({ rooms: {} }, { rooms: [{ id: 'kitchen' }], unassigned: [] })).toEqual({
			orphaned: [],
			unplaced: ['kitchen'],
		});
	});
});

// ---------------------------------------------------------------------------
// The live tiers.
// ---------------------------------------------------------------------------

const hasDb = Boolean(process.env.DATABASE_URL);
const hasKey = Boolean(process.env.WALLET_ENCRYPTION_KEY || process.env.JWT_SECRET);

const liveDb = describe.skipIf(!hasDb || !hasKey);
const liveHome = describe.skipIf(!hasDb || !hasKey || !liveHomeAvailable());

// The house, when there is one. The file-level hook runs before any suite's own
// beforeAll, so the DB-only tier below files its row against the real instance
// when the lane has one and against an unroutable placeholder when it does not.
let haUrl;
let haToken;

beforeAll(async () => {
	if (!liveHomeAvailable()) return;
	const instance = await acquireHomeInstance();
	haUrl = instance.baseUrl;
	haToken = instance.token;
}, 600_000);

const SYNTHETIC_TOKEN = `synthetic.home.assistant.token.${'a'.repeat(64)}`;

liveDb('the layout store, against a real database', () => {
	let sql;
	let store;
	let layout;
	let owner;
	let second;
	let home;

	beforeAll(async () => {
		({ sql } = await import('../api/_lib/db.js'));
		store = await import('../api/_lib/home/store.js');
		layout = await import('../api/_lib/home/layout.js');
		const stamp = Date.now();
		[owner] = await sql`insert into users (email) values (${`home-layout-a-${stamp}@qa.three.ws`}) returning id`;
		[second] = await sql`insert into users (email) values (${`home-layout-b-${stamp}@qa.three.ws`}) returning id`;
		home = await store.createConnection({
			userId: owner.id,
			label: 'Layout test',
			baseUrl: haUrl || 'https://layout.invalid.three.ws',
			token: haToken || SYNTHETIC_TOKEN,
		});
	}, 60_000);

	afterAll(async () => {
		if (!sql) return;
		if (home) await sql`delete from home_connections where id = ${home.id}`;
		for (const u of [owner, second]) if (u) await sql`delete from users where id = ${u.id}`;
	});

	it('reports no layout before anyone draws one', async () => {
		expect(await layout.getLayout(home.id)).toBeNull();
	});

	it('creates the first layout at version 1', async () => {
		const res = await layout.putLayout({
			homeId: home.id,
			layout: { rooms: { kitchen: { x: 0, z: 0 } } },
			updatedBy: owner.id,
			expectedVersion: 0,
		});
		expect(res.ok).toBe(true);
		expect(res.version).toBe(1);
	});

	it('refuses a second create rather than overwriting the first', async () => {
		// A caller sending expectedVersion 0 believes there is nothing here. If a
		// row appeared since they loaded, that belief is stale and they must be
		// told, not silently overwritten.
		const res = await layout.putLayout({
			homeId: home.id,
			layout: { rooms: { bedroom: { x: 9, z: 0 } } },
			updatedBy: second.id,
			expectedVersion: 0,
		});
		expect(res.ok).toBe(false);
		expect(res.conflict).toBe(true);
		expect(res.current.layout.rooms).toHaveProperty('kitchen');
		expect(res.current.layout.rooms).not.toHaveProperty('bedroom');
	});

	it('advances the version on a good write', async () => {
		const res = await layout.putLayout({
			homeId: home.id,
			layout: { rooms: { kitchen: { x: 1, z: 1 } } },
			updatedBy: owner.id,
			expectedVersion: 1,
		});
		expect(res.ok).toBe(true);
		expect(res.version).toBe(2);
		expect((await layout.getLayout(home.id)).layout.rooms.kitchen).toEqual({ x: 1, z: 1, w: undefined, d: undefined });
	});

	it('refuses a stale write and hands back the current document, so no edit is lost', async () => {
		// Two members drawing at once. The second must be asked, not overruled.
		const stale = await layout.putLayout({
			homeId: home.id,
			layout: { rooms: { kitchen: { x: 99, z: 99 } } },
			updatedBy: second.id,
			expectedVersion: 1,
		});
		expect(stale.ok).toBe(false);
		expect(stale.conflict).toBe(true);
		expect(stale.current.version).toBe(2);
		expect(stale.current.layout.rooms.kitchen.x).toBe(1);
	});

	it('rejects an invalid document before it reaches the database', async () => {
		await expect(
			layout.putLayout({ homeId: home.id, layout: { rooms: { a: { x: 9e9, z: 0 } } }, updatedBy: owner.id, expectedVersion: 2 }),
		).rejects.toThrow(LayoutInvalid);
		expect((await layout.getLayout(home.id)).version).toBe(2);
	});

	it('reports a stored document this version would now refuse, rather than throwing', async () => {
		// A row can predate a cap. One bad document must degrade to the default
		// arrangement, not take the page down.
		await sql`update home_layouts set layout = ${JSON.stringify({ format: 1, units: 'm', rooms: { a: { x: 99999, z: 0 } } })}::jsonb where home_id = ${home.id}`;
		const read = await layout.getLayout(home.id);
		expect(read.unreadable).toMatch(/limit is 500 m/);
		expect(read.layout.rooms).toEqual({});
	});

	it('deletes, and is honest about deleting nothing twice', async () => {
		expect(await layout.deleteLayout(home.id)).toBe(true);
		expect(await layout.deleteLayout(home.id)).toBe(false);
		expect(await layout.getLayout(home.id)).toBeNull();
	});

	it('cascades with the home', async () => {
		await layout.putLayout({ homeId: home.id, layout: { rooms: { kitchen: { x: 0, z: 0 } } }, updatedBy: owner.id, expectedVersion: 0 });
		await sql`delete from home_connections where id = ${home.id}`;
		const [row] = await sql`select 1 as hit from home_layouts where home_id = ${home.id}`;
		expect(row).toBeUndefined();
		home = null;
	});
});

liveHome('the area write-back, against a real Home Assistant', () => {
	let bridge;
	let unfiled;
	let areaId;
	let originalArea;

	beforeAll(async () => {
		const { HomeBridge } = await import('../packages/home-bridge/src/index.js');
		bridge = new HomeBridge({ baseUrl: haUrl, token: haToken });
		await bridge.connect();
		areaId = bridge.areas()[0]?.id;
		// A registry entity that the seeder did not already file, so the test
		// moves something real and can put it back.
		const registry = bridge.registries.entities || [];
		const candidate = registry.find((e) => e.entity_id.startsWith('light.') && !e.disabled_by);
		unfiled = candidate?.entity_id;
		originalArea = candidate?.area_id ?? null;
	}, 60_000);

	afterAll(async () => {
		if (bridge && unfiled) {
			try {
				await bridge.assignEntityArea(unfiled, originalArea);
			} catch {
				// Best effort: the assertion below already proved the write works.
			}
		}
		bridge?.close();
	});

	it('has an area and a registry entity to work with', () => {
		expect(areaId).toBeTruthy();
		expect(unfiled).toBeTruthy();
	});

	it('moves a real entity into a real area, and Home Assistant agrees', async () => {
		await bridge.assignEntityArea(unfiled, areaId);
		// Read it back from Home Assistant's own registry, not from our cache of it.
		const fresh = await bridge.refreshRegistries();
		const entry = (bridge.registries.entities || []).find((e) => e.entity_id === unfiled);
		expect(entry.area_id).toBe(areaId);
		// And the room graph the scene renders reflects it without a reconnect.
		const room = fresh.rooms.find((r) => r.id === areaId);
		expect(room.entities.some((e) => e.entityId === unfiled)).toBe(true);
	}, 30_000);

	it('unfiles an entity when given a null area', async () => {
		await bridge.assignEntityArea(unfiled, null);
		const entry = (bridge.registries.entities || []).find((e) => e.entity_id === unfiled);
		expect(entry.area_id ?? null).toBeNull();
	}, 30_000);

	it('explains a YAML entity instead of throwing a raw protocol error', async () => {
		// Most demo and template entities never reach the entity registry, so this
		// is the common case rather than an edge one, and it needs a sentence a
		// person can act on.
		const registered = new Set((bridge.registries.entities || []).map((e) => e.entity_id));
		const yamlOnly = Object.keys(bridge.states).find((id) => !registered.has(id) && id.includes('.'));
		if (!yamlOnly) return;
		await expect(bridge.assignEntityArea(yamlOnly, areaId)).rejects.toThrow(/entity registry/i);
	}, 30_000);

	it('refuses something that is not an entity id at all', async () => {
		await expect(bridge.assignEntityArea('not-an-entity', areaId)).rejects.toThrow(/not an entity id/);
	});

	// Making a room is the way out of the house that has no areas at all, which
	// is the most common real house we see. Without it the tray has nowhere to
	// file anything to and the only advice we can give is "go and use Home
	// Assistant's settings first", which loses the person.
	it('makes a new room, and Home Assistant has it', async () => {
		const name = `Plan test ${Date.now().toString(36)}`;
		const area = await bridge.createArea(name);
		expect(area.created).toBe(true);
		expect(area.id).toBeTruthy();

		// Home Assistant's own area registry, not our cache of it.
		const fresh = await bridge.refreshRegistries();
		expect((bridge.registries.areas || []).some((a) => a.area_id === area.id)).toBe(true);
		// And the graph the scene renders carries it, so it is a placeable room
		// the moment it exists rather than after a reconnect.
		expect(fresh.rooms.some((r) => r.id === area.id)).toBe(true);

		// A second call with the same name is not an error: the room they asked
		// for is there, which is what they wanted.
		const again = await bridge.createArea(name);
		expect(again.created).toBe(false);
		expect(again.id).toBe(area.id);

		// A device can be filed into a room that did not exist a moment ago.
		await bridge.assignEntityArea(unfiled, area.id);
		const entry = (bridge.registries.entities || []).find((e) => e.entity_id === unfiled);
		expect(entry.area_id).toBe(area.id);

		// Take the room away again. The lane's house is shared by every live test
		// and reused across runs, so a test that leaves rooms behind quietly
		// changes the house every later assertion is made against.
		await bridge.assignEntityArea(unfiled, originalArea);
		await removeArea(bridge, area.id);
	}, 60_000);

	it('refuses a nameless room rather than making an unnamed one', async () => {
		await expect(bridge.createArea('   ')).rejects.toThrow(/needs a name/i);
	});
});

/**
 * Delete an area straight through Home Assistant's own websocket.
 *
 * The bridge deliberately has no delete: making a room is the flow the product
 * needs, and removing one is a decision that belongs in the user's own Home
 * Assistant rather than in a library we ship. A test that creates rooms still
 * has to clean up after itself, so it opens its own socket for the one message.
 */
async function removeArea(bridge, areaId) {
	const socket = new WebSocket(`${haUrl.replace(/^http/, 'ws')}/api/websocket`);
	try {
		await new Promise((resolve, reject) => {
			const timer = setTimeout(() => reject(new Error('area delete timed out')), 20_000);
			socket.onerror = () => { clearTimeout(timer); reject(new Error('websocket failed')); };
			socket.onmessage = (event) => {
				const msg = JSON.parse(event.data);
				if (msg.type === 'auth_required') return socket.send(JSON.stringify({ type: 'auth', access_token: haToken }));
				if (msg.type === 'auth_ok') return socket.send(JSON.stringify({ id: 1, type: 'config/area_registry/delete', area_id: areaId }));
				if (msg.type === 'result') { clearTimeout(timer); resolve(); }
			};
		});
	} finally {
		socket.close();
	}
	await bridge.refreshRegistries();
}