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
// /api/home/:id/layout: the authored floorplan for one house.
//
// GET the current layout, its version, and what has drifted from the house
// PUT write a layout, refusing a stale write with 409 and the current one
// DELETE drop it, so the scene returns to the default arrangement
//
// Home Assistant has no geometry, so the arrangement of rooms in the 3D scene is
// either the default grid or something a person drew. This route owns the second
// one. It is never required: no row here is an ordinary state, and the scene
// renders the default grid without it.
//
// Two members can edit the same house. `version` is the whole concurrency story:
// a PUT names the version it loaded, a mismatch is refused with the current
// document attached, and the editor asks the user rather than silently
// discarding somebody's afternoon. Last-write-wins on a timestamp was rejected
// because clock skew between two browsers is real and the loser of a millisecond
// should not lose their work.
import { logAudit } from '../../_lib/audit.js';
import { requireCsrf } from '../../_lib/csrf.js';
import { resolveHomeAccess } from '../../_lib/home/access.js';
import { deleteLayout, getLayout, LayoutInvalid, putLayout, reconcileLayout } from '../../_lib/home/layout.js';
import { snapshot } from '../../_lib/home/runtime.js';
import { cors, error, json, method, rateLimited, readJson, wrap } from '../../_lib/http.js';
import { limits } from '../../_lib/rate-limit.js';
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,PUT,DELETE,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'PUT', 'DELETE'])) return;
// Reading the plan is a read; drawing it is the `layout` capability, which a
// guest and a viewer do not hold. A house sitter should see where the rooms
// are and should not be able to redraw somebody's home.
const access = await resolveHomeAccess(req, res, req.query?.id, req.method === 'GET' ? 'read' : 'layout');
if (!access.ok) return error(res, access.status, access.code, access.message);
const { caller, home } = access;
if (req.method === 'GET') {
const rl = await limits.homeRead(caller.userId);
if (!rl.success) return rateLimited(res, rl, 'too many home reads, slow down');
return json(res, 200, await describe(home.id, caller.userId));
}
if (!(await requireCsrf(req, res, caller.userId))) return;
if (req.method === 'DELETE') {
const removed = await deleteLayout(home.id);
if (removed) {
logAudit({ userId: caller.userId, action: 'delete_home_layout', resourceId: home.id, req });
}
return json(res, 200, { removed, ...(await describe(home.id, caller.userId)) });
}
const rl = await limits.homeAct(caller.userId);
if (!rl.success) return rateLimited(res, rl, 'too many layout writes, slow down');
const body = await readJson(req, res);
if (body === undefined) return;
// A caller that omits the version is not "starting fresh", it is a caller
// that has not read the concurrency contract. Saying so beats letting it
// overwrite whatever is there.
if (body?.version == null) {
return error(res, 400, 'version_required', 'Send the version you loaded, or 0 to create the first layout.');
}
const expected = Number(body.version);
if (!Number.isInteger(expected) || expected < 0) {
return error(res, 400, 'version_required', 'version must be a whole number, 0 or greater.');
}
let result;
try {
result = await putLayout({
homeId: home.id,
layout: body.layout,
updatedBy: caller.userId,
expectedVersion: expected,
});
} catch (err) {
if (err instanceof LayoutInvalid) {
return error(res, 400, 'layout_invalid', err.message, { field: err.field });
}
throw err;
}
if (!result.ok) {
// 409 with the current document, so the client can offer keep-mine,
// take-theirs or a side-by-side rather than a bare failure.
return json(res, 409, {
error: 'Someone else changed this floorplan while you were drawing.',
code: 'layout_conflict',
current: result.current,
...(await drift(home.id, caller.userId, result.current?.layout)),
});
}
logAudit({ userId: caller.userId, action: 'write_home_layout', resourceId: home.id, meta: { version: result.version, rooms: Object.keys(result.layout.rooms).length }, req });
return json(res, 200, { version: result.version, layout: result.layout, ...(await drift(home.id, caller.userId, result.layout)) });
});
/** The stored layout plus what has drifted from the live house. */
async function describe(homeId, userId) {
const stored = await getLayout(homeId);
return {
version: stored?.version ?? 0,
layout: stored?.layout ?? null,
updatedAt: stored?.updatedAt ?? null,
// A document this server would now refuse to store is reported rather
// than thrown: one bad row degrades to the default arrangement instead of
// taking the page down.
unreadable: stored?.unreadable ?? null,
...(await drift(homeId, userId, stored?.layout)),
};
}
/**
* Which placed rooms the house no longer has, and which house rooms nobody has
* placed. Both are ordinary, and the editor shows each of them.
*
* The graph read is best effort: a floorplan must stay editable while the house
* itself is unreachable, so a failure here reports no drift rather than failing
* the request.
*/
async function drift(homeId, userId, layoutDoc) {
if (!layoutDoc) return { orphaned: [], unplaced: [], driftKnown: false };
try {
const graph = await snapshot(homeId, userId);
const { orphaned, unplaced } = reconcileLayout(layoutDoc, graph);
return { orphaned, unplaced, driftKnown: true };
} catch {
return { orphaned: [], unplaced: [], driftKnown: false };
}
}