@pascal-app/core 1.0.3 → 1.0.5

package/dist/agent-operations/find-by-type.js

@@ -0,0 +1,317 @@
+import { FIND_BY_TYPE_LIMIT } from '../agent-tools/find-by-type.js';
+import { refuse } from '../agent-tools/refusal.js';
+import { isScriptedNode } from '../lib/geometry-script-node.js';
+import { measurementCentroid } from '../lib/measurement-geometry.js';
+import { nodeLevelFrame } from '../procedural-items/query.js';
+import { transformPoint } from '../procedural-items/spatial.js';
+import { nodeRegistry } from '../registry/index.js';
+import { AnyNode as AnyNodeSchema, nodeKindOf, } from '../schema/index.js';
+import { pointInPolygon } from '../systems/slab/slab-support.js';
+import { requireLevel } from './level-target.js';
+import { levelIdOf } from './scene-queries.js';
+const round = (v) => Math.round(v * 1000) / 1000;
+/** A point in an item's frame, in its level's frame (items on a level: position + yaw). */
+function toLevel(item, [x, y, z]) {
+    const yaw = item.rotation[1] ?? 0;
+    const [sx, sy, sz] = item.scale;
+    const lx = x * sx;
+    const lz = z * sz;
+    return [
+        round(item.position[0] + Math.cos(yaw) * lx + Math.sin(yaw) * lz),
+        round(item.position[1] + y * sy),
+        round(item.position[2] - Math.sin(yaw) * lx + Math.cos(yaw) * lz),
+    ];
+}
+function boundsInLevel(item, bounds) {
+    const corners = [];
+    for (const x of [bounds.min[0], bounds.max[0]])
+        for (const y of [bounds.min[1], bounds.max[1]])
+            for (const z of [bounds.min[2], bounds.max[2]])
+                corners.push(toLevel(item, [x, y, z]));
+    return {
+        min: [0, 1, 2].map((k) => Math.min(...corners.map((c) => c[k]))),
+        max: [0, 1, 2].map((k) => Math.max(...corners.map((c) => c[k]))),
+    };
+}
+const CORE_KINDS = new Set(AnyNodeSchema.options.map(nodeKindOf));
+/** A node's kind, lower case; a malformed node stored without one has none. */
+const kindOf = (node) => String(node.type).toLowerCase();
+const emitsLight = (node) => node.type === 'item' &&
+    Boolean(node.asset?.interactive?.effects?.some((effect) => effect.kind === 'light'));
+const matchesWord = (text, word) => Boolean(text) &&
+    text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .includes(word);
+/**
+ * A source id as importers write it into typed provenance: printable ASCII kept, every other
+ * character percent-encoded as UTF-8 bytes.
+ */
+function encodeSourceId(id) {
+    let out = '';
+    for (const char of id) {
+        if (/^[\x20-\x7E]$/.test(char)) {
+            out += char;
+            continue;
+        }
+        for (const byte of new TextEncoder().encode(char))
+            out += `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+    }
+    return out;
+}
+/** A node's import source ids: typed `provenance.refs[].id`, then legacy `metadata.sourceIds`. */
+function sourceIdsOf(node) {
+    const typed = (node.provenance?.refs ?? []).map((ref) => ref.id);
+    const legacy = node.metadata?.sourceIds;
+    return Array.isArray(legacy)
+        ? [...typed, ...legacy.filter((id) => typeof id === 'string')]
+        : typed;
+}
+/** The source filters as one test; a legacy id may be stored raw, a typed one percent-encoded. */
+function sourceFilter({ sourceId, sourceIdPrefix }) {
+    if (sourceId === undefined && sourceIdPrefix === undefined)
+        return undefined;
+    const exact = sourceId === undefined ? [] : [sourceId, encodeSourceId(sourceId)];
+    const prefixes = sourceIdPrefix === undefined ? [] : [sourceIdPrefix, encodeSourceId(sourceIdPrefix)];
+    return (node) => {
+        const ids = sourceIdsOf(node);
+        return ((sourceId === undefined || ids.some((id) => exact.includes(id))) &&
+            (sourceIdPrefix === undefined ||
+                ids.some((id) => prefixes.some((prefix) => id.startsWith(prefix)))));
+    };
+}
+function centre2(points) {
+    if (points.length === 0)
+        return null;
+    const area = measurementCentroid(points.map(([x, z]) => [x, 0, z]));
+    if (area)
+        return [area[0], area[2]];
+    const sum = points.reduce(([sx, sz], [x, z]) => [sx + x, sz + z], [0, 0]);
+    return [sum[0] / points.length, sum[1] / points.length];
+}
+function boundsCentre3(points) {
+    if (points.length === 0)
+        return null;
+    return [0, 1, 2].map((axis) => {
+        const values = points.map((p) => p[axis]);
+        return (Math.min(...values) + Math.max(...values)) / 2;
+    });
+}
+/**
+ * Where a node stands in its level's plan: a polygon's area centroid, a segment's midpoint, a
+ * path's centre, or the origin of a positioned node through its hosts (a window in its wall, a
+ * module in its cabinet); a block or an imported mesh by the centre of its vertex bounds, turned in
+ * 3D before it is projected. Plan-only frames, one cache per query, so each host resolves once.
+ */
+function planPointOf(node, nodes, frames) {
+    const n = node;
+    if (Array.isArray(n.polygon))
+        return centre2(n.polygon);
+    if (Array.isArray(n.start) && Array.isArray(n.end)) {
+        const [x1, z1] = n.start;
+        const [x2, z2] = n.end;
+        return [(x1 + x2) / 2, (z1 + z2) / 2];
+    }
+    if (Array.isArray(n.path)) {
+        const centre = boundsCentre3(n.path);
+        return centre ? [centre[0], centre[2]] : null;
+    }
+    if (!Array.isArray(n.position))
+        return null;
+    const local = node.type === 'block'
+        ? boundsCentre3((node.topology?.vertices ?? []).map((vertex) => vertex.position))
+        : node.type === 'imported-mesh'
+            ? boundsCentre3((node.primitives ?? []).flatMap(({ positions }) => {
+                const out = [];
+                for (let i = 0; i + 2 < positions.length; i += 3)
+                    out.push([positions[i], positions[i + 1], positions[i + 2]]);
+                return out;
+            }))
+            : null;
+    return framePoint(node, nodes, frames, local ?? [0, 0, 0]);
+}
+/** A point of a node's own frame in its level's plan, through its hosts, turned in 3D first. */
+function framePoint(node, nodes, frames, local) {
+    let frame;
+    try {
+        frame = nodeLevelFrame(node.id, nodes, undefined, { cache: frames, planOnly: true });
+    }
+    catch {
+        return null;
+    }
+    const [x, , z] = transformPoint(frame, local);
+    return [x, z];
+}
+function requireZone(nodes, zoneId) {
+    const zone = nodes[zoneId];
+    if (!zone)
+        refuse('zone_not_found', `Zone not found: ${zoneId}. Use a zoneId get_zones returned.`, {
+            zoneId,
+        });
+    if (zone.type !== 'zone')
+        refuse('not_a_zone', `Node ${zoneId} is a ${zone.type}, not a zone.`, {
+            zoneId,
+            type: zone.type,
+        });
+    return zone;
+}
+/**
+ * What of a node's results stands in this zone: on the zone's level, a plan point inside its outline
+ * and outside its holes, by the ray cast the editor's spatial grid uses (a closing vertex repeated,
+ * or a zero-length edge, puts nothing inside). A part with bounds stands at their middle, through
+ * its node's frame and hosts; anything else at its node's plan point. Geometry is read only once the
+ * node is on the zone's level.
+ */
+function zoneFilter(nodes, zone) {
+    const zoneLevel = levelIdOf(nodes, zone.id);
+    const outline = zone.polygon;
+    const holes = (zone.holes ?? []);
+    const frames = new Map();
+    const inside = (point) => point !== null &&
+        pointInPolygon(point[0], point[1], outline) &&
+        !holes.some((hole) => pointInPolygon(point[0], point[1], hole));
+    return (node, level, matches) => {
+        if (level !== zoneLevel)
+            return [];
+        let planPoint;
+        const nodePoint = () => {
+            if (planPoint === undefined)
+                planPoint = planPointOf(node, nodes, frames);
+            return planPoint;
+        };
+        return matches.filter(({ at }) => inside(at ? framePoint(node, nodes, frames, at) : nodePoint()));
+    };
+}
+/** Past this much JSON, a result leaves a record out and names it in `omitted`: get_node reads it. */
+const RECORD_BYTES = 1024;
+/** What a whole node records about itself (an importer's ids, Architect's marks), when it is small. */
+function recordsOf(node) {
+    const out = {};
+    const omitted = [];
+    const records = { metadata: node.metadata, provenance: node.provenance };
+    for (const [field, value] of Object.entries(records)) {
+        if (!value || Object.keys(value).length === 0)
+            continue;
+        if (JSON.stringify(value).length > RECORD_BYTES)
+            omitted.push(field);
+        else
+            out[field] = value;
+    }
+    return omitted.length ? { ...out, omitted } : out;
+}
+/**
+ * Whether a type word, or its singular, names anything find_by_type reads: a core kind, a plugin
+ * kind this runtime registered or the host checks (the hosted MCP knows its plugins' kinds without
+ * registering them), light, or a kind, an item category or a typed part in this scene.
+ */
+function namesAnything(nodes, names, { nodeSchema }) {
+    if (names.has('light'))
+        return true;
+    const registered = [...nodeRegistry.entries()].map(([kind]) => kind.toLowerCase());
+    const known = (name) => CORE_KINDS.has(name) || registered.includes(name) || Boolean(nodeSchema?.(name));
+    if ([...names].some(known))
+        return true;
+    return Object.values(nodes).some((node) => names.has(kindOf(node)) ||
+        (node.type === 'item' &&
+            [...names].some((name) => matchesWord(node.asset?.category, name))) ||
+        (isScriptedNode(node) &&
+            (node.source?.manifest?.parts ?? []).some((part) => part.type && names.has(part.type))));
+}
+/**
+ * `find_by_type`: everything of one type, nodes and the typed parts of authored objects alike,
+ * narrowed by level, parent, zone or source id. Parts are read from each object's manifest; the
+ * object stays the thing that is selected, moved and edited. Each result is the node's summary;
+ * `get_node` reads it whole. Past `limit` results are counted, not listed.
+ */
+export const findByType = (nodes, input, context) => {
+    const { levelId, parentId, zoneId } = input;
+    // A level, parent or zone that is not there is said, as get_zones says it, not answered with
+    // nothing found: the agent could not tell a typo from an empty floor.
+    if (levelId)
+        requireLevel(nodes, levelId);
+    if (parentId && !nodes[parentId])
+        refuse('node_not_found', `Node not found: ${parentId}.`, { id: parentId });
+    const inZone = zoneId ? zoneFilter(nodes, requireZone(nodes, zoneId)) : undefined;
+    const fromSource = sourceFilter(input);
+    // What was asked, as written; a word also in the singular ("walls"), a plugin's kind
+    // (`bones:studs`) never.
+    const kind = input.type?.trim().toLowerCase();
+    const names = kind === undefined
+        ? undefined
+        : new Set([kind, kind.includes(':') ? kind : kind.replace(/s$/, '')]);
+    const results = [];
+    for (const node of Object.values(nodes)) {
+        if (parentId && node.parentId !== parentId)
+            continue;
+        if (fromSource && !fromSource(node))
+            continue;
+        const level = levelIdOf(nodes, node.id);
+        if (levelId && level !== levelId)
+            continue;
+        const item = node.type === 'item' ? node : null;
+        const found = {
+            id: node.id,
+            name: node.name ?? item?.asset?.name,
+            nodeType: node.type,
+            levelId: level,
+            parentId: node.parentId ?? null,
+        };
+        const whole = { found: { ...found, ...recordsOf(node) } };
+        let matched;
+        if (names === undefined)
+            matched = [whole];
+        else {
+            const typed = (isScriptedNode(node) ? (node.source?.manifest?.parts ?? []) : []).filter((part) => part.type);
+            const typedParts = typed.filter((part) => names.has(part.type));
+            // An authored item whose typed parts are all of this type is one (a lantern); a mixed one (a
+            // porch), or a window, door or column, answers with its parts.
+            const wholeAuthored = item !== null && typedParts.length > 0 && typedParts.length === typed.length;
+            const wholeMatch = names.has(kindOf(node)) ||
+                wholeAuthored ||
+                (item &&
+                    ([...names].some((name) => matchesWord(item.asset?.category, name)) ||
+                        (names.has('light') && emitsLight(node) && typedParts.length === 0)));
+            // A part's bounds are in its node's model frame, which the node's scale stretches.
+            const scale = node.scale ?? [1, 1, 1];
+            matched = wholeMatch
+                ? [whole]
+                : typedParts.map((part) => ({
+                    found: {
+                        ...found,
+                        part: part.id,
+                        partType: part.type,
+                        ...(part.bounds && item && item.parentId === level
+                            ? { bounds: boundsInLevel(item, part.bounds) }
+                            : {}),
+                    },
+                    ...(part.bounds && {
+                        at: [0, 1, 2].map((axis) => ((part.bounds.min[axis] + part.bounds.max[axis]) / 2) * scale[axis]),
+                    }),
+                }));
+        }
+        // Where a node stands is read only for what matched: the zone test reads geometry.
+        if (matched.length > 0)
+            results.push(...(inZone ? inZone(node, level, matched) : matched).map(({ found }) => found));
+    }
+    if (names && results.length === 0 && !namesAnything(nodes, names, context)) {
+        const kinds = [...new Set(Object.values(nodes).map(kindOf))].sort();
+        refuse('unknown_type', `"${kind}" names nothing find_by_type reads: no node kind (core's or a plugin's this host knows), and no item category or part type in this scene. Kinds in this scene: ${kinds.join(', ')}.`, { type: kind, kinds });
+    }
+    const limit = input.limit ?? FIND_BY_TYPE_LIMIT;
+    const parts = results.filter((entry) => entry.part).length;
+    return {
+        result: {
+            ...(kind === undefined ? {} : { type: kind }),
+            count: results.length,
+            nodes: results.length - parts,
+            parts,
+            results: results.slice(0, limit),
+            ...(results.length > limit
+                ? {
+                    truncated: true,
+                    hint: `${limit} of ${results.length} listed. Narrow by type, levelId, zoneId or parentId, or ask for more with limit.`,
+                }
+                : {}),
+        },
+    };
+};

package/dist/agent-operations/furnish-room.d.ts

@@ -0,0 +1,39 @@
+import type { FURNISHED_ROOM_TYPES } from '../agent-tools/furnish-room.js';
+import { type LevelTargetInput } from './level-target.js';
+import { type Vec2 } from './plan-geometry.js';
+import type { AgentContext, AgentOperation, SceneNodes } from './types.js';
+type RoomType = (typeof FURNISHED_ROOM_TYPES)[number];
+type FurnishRoomInput = LevelTargetInput & {
+    zoneId?: string;
+    polygon?: number[][];
+    roomType: RoomType;
+    doorWallIndex?: number;
+};
+export declare const WALL_GAP = 0.1;
+/** The room asked for: a zone's level and outline, or a polygon on the level named. */
+export declare function roomToFurnish(nodes: SceneNodes, input: LevelTargetInput & Pick<FurnishRoomInput, 'zoneId' | 'polygon'>, context: AgentContext): {
+    levelId: string;
+    polygon: Vec2[];
+};
+/** A polygon edge seen from inside the room: its middle, its direction, and the way into the room. */
+export declare function edgeFrame(polygon: Vec2[], index: number, center: Vec2): {
+    mid: Vec2;
+    along: {
+        x: number;
+        z: number;
+    };
+    inward: {
+        x: number;
+        z: number;
+    };
+    length: number;
+    facing: number;
+};
+/**
+ * `furnish_room`: a room type's pieces from the host's catalog, against the walls the door decides,
+ * each moved off door clear zones and other items or skipped with the reason. The door wall is the
+ * edge a door of the room stands on (found by position), else doorWallIndex, else edge 0.
+ */
+export declare const furnishRoom: AgentOperation<FurnishRoomInput>;
+export {};
+//# sourceMappingURL=furnish-room.d.ts.map

package/dist/agent-operations/furnish-room.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"furnish-room.d.ts","sourceRoot":"","sources":["../../src/agent-operations/furnish-room.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAsBvE,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAA8B,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEvE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEvE,KAAK,QAAQ,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAA;AAErD,KAAK,gBAAgB,GAAG,gBAAgB,GAAG;IACzC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAKD,eAAO,MAAM,QAAQ,MAAM,CAAA;AAQ3B,uFAAuF;AACvF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,SAAS,CAAC,EACtE,OAAO,EAAE,YAAY;;aAkBwB,IAAI,EAAE;EAKpD;AA2BD,sGAAsG;AACtG,wBAAgB,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI;;;;;;;;;;;;EAWrE;AA0KD;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,cAAc,CAAC,gBAAgB,CAsGxD,CAAA"}

package/dist/agent-operations/furnish-room.js

@@ -0,0 +1,306 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { OTHER_SOURCES } from '../agent-tools/sources.js';
+import { ItemNode } from '../schema/index.js';
+import { edgeProjection } from './create-room.js';
+import { collectDoorKeepouts, itemBlocksDoorKeepout, itemPlanAabb, keepoutCoversPlanned, keepoutForPolygonEdge, } from './door-clearance.js';
+import { furnitureKind } from './furniture-kind.js';
+import { collectOccupiedFootprints, findValidPlacement, lateralSteps, MID_ROOM_DISTANCE_M, PLACEMENT_INSETS_M, wallFacesOn, } from './layout-clearance.js';
+import { targetLevel } from './level-target.js';
+import { polygonArea, polygonBounds } from './plan-geometry.js';
+import { levelIdOf, levelRole } from './scene-queries.js';
+// A door belongs to a room edge when it stands this close to the edge's line, within its span.
+const DOOR_EDGE_TOLERANCE = 0.25;
+// Clearance between a piece's back and the wall's centreline: half a wall and a hand's width.
+export const WALL_GAP = 0.1;
+// A wall-bound piece (a sofa, a bed, a TV stand) slides along its wall, within the wall's ends, to
+// clear a door or another piece, and steps off it only as far as verify_scene still reads it
+// against the wall (item_mid_room); where no wall stands, it is skipped.
+const AGAINST_WALL_INSETS_M = PLACEMENT_INSETS_M.filter((inset) => WALL_GAP + inset <= MID_ROOM_DISTANCE_M);
+/** The room asked for: a zone's level and outline, or a polygon on the level named. */
+export function roomToFurnish(nodes, input, context) {
+    if (input.zoneId) {
+        const zone = nodes[input.zoneId];
+        if (!zone)
+            refuse('zone_not_found', `Room not found: ${input.zoneId}. Use a zoneId create_room or get_zones returned.`, { zoneId: input.zoneId });
+        if (zone.type !== 'zone')
+            refuse('not_a_zone', `Node ${input.zoneId} is a ${zone.type}, not a room: pass the room's zoneId (create_room, get_zones).`, { zoneId: input.zoneId, type: zone.type });
+        const levelId = levelIdOf(nodes, zone.id);
+        if (!levelId)
+            refuse('level_not_found', `Room ${zone.id} is not on a level.`);
+        return { levelId, polygon: zone.polygon };
+    }
+    if (!input.polygon)
+        refuse('room_required', 'Say which room: its zoneId, or its polygon (and its level).');
+    return { levelId: targetLevel(nodes, input, context).id, polygon: input.polygon };
+}
+/** The doors of the level that stand on an edge of the room, by where they stand. */
+function doorsOfRoom(nodes, levelId, polygon) {
+    const found = [];
+    for (const wall of Object.values(nodes)) {
+        if (wall.type !== 'wall' || wall.parentId !== levelId)
+            continue;
+        const length = Math.hypot(wall.end[0] - wall.start[0], wall.end[1] - wall.start[1]);
+        if (length < 1e-9)
+            continue;
+        for (const childId of wall.children) {
+            const door = nodes[childId];
+            if (door?.type !== 'door')
+                continue;
+            const t = door.position[0] / length;
+            const point = [
+                wall.start[0] + t * (wall.end[0] - wall.start[0]),
+                wall.start[1] + t * (wall.end[1] - wall.start[1]),
+            ];
+            const edge = polygon.findIndex((a, i) => {
+                const along = edgeProjection(a, polygon[(i + 1) % polygon.length], point);
+                return along.distance < DOOR_EDGE_TOLERANCE && along.t >= 0 && along.t <= 1;
+            });
+            if (edge >= 0)
+                found.push({ doorId: door.id, edge });
+        }
+    }
+    return found;
+}
+/** A polygon edge seen from inside the room: its middle, its direction, and the way into the room. */
+export function edgeFrame(polygon, index, center) {
+    const a = polygon[index % polygon.length];
+    const b = polygon[(index + 1) % polygon.length];
+    const length = Math.hypot(b[0] - a[0], b[1] - a[1]) || 1;
+    const along = { x: (b[0] - a[0]) / length, z: (b[1] - a[1]) / length };
+    const mid = [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
+    const towardCenter = (center[0] - mid[0]) * -along.z + (center[1] - mid[1]) * along.x;
+    const inward = towardCenter >= 0 ? { x: -along.z, z: along.x } : { x: along.z, z: -along.x };
+    // An item's front is its +Z: turned to face into the room.
+    const facing = (Math.atan2(inward.x, inward.z) * 180) / Math.PI;
+    return { mid, along, inward, length, facing };
+}
+/** Where each piece of a room type goes, sized from the catalog's own dimensions. */
+function layout(roomType, polygon, doorWall, catalog) {
+    const bounds = polygonBounds(polygon);
+    const center = [bounds.centerX, bounds.centerZ];
+    const n = polygon.length;
+    const door = edgeFrame(polygon, doorWall, center);
+    const back = edgeFrame(polygon, doorWall + Math.floor(n / 2), center);
+    const side = edgeFrame(polygon, doorWall + 1, center);
+    const area = polygonArea(polygon);
+    const size = (assetId) => catalog.find((asset) => asset.id === assetId)?.dimensions;
+    const width = (assetId) => size(assetId)?.[0] ?? 1;
+    const depth = (assetId) => size(assetId)?.[2] ?? 1;
+    const poses = [];
+    /**
+     * Back against `edge`, `lateral` along it from its middle, `out` further into the room; moved
+     * along `edge` as far as the piece it `follows` was moved.
+     */
+    const against = (edge, assetId, lateral = 0, out = 0, follows) => {
+        const inset = depth(assetId) / 2 + WALL_GAP + out;
+        poses.push({
+            follows,
+            assetId,
+            x: edge.mid[0] + edge.inward.x * inset + edge.along.x * lateral,
+            z: edge.mid[1] + edge.inward.z * inset + edge.along.z * lateral,
+            rotationDeg: edge.facing,
+            along: edge.along,
+            inward: edge.inward,
+            wall: { length: edge.length, lateral },
+        });
+    };
+    const free = (assetId, x, z, rotationDeg = 0) => poses.push({ assetId, x, z, rotationDeg });
+    switch (roomType) {
+        case 'bedroom': {
+            const bed = Math.max(bounds.width, bounds.depth) >= 3.2 ? 'double-bed' : 'single-bed';
+            against(back, bed);
+            const table = width('bedside-table');
+            if (back.length >= width(bed) + 2 * table + 0.2) {
+                const lateral = width(bed) / 2 + table / 2 + 0.05;
+                against(back, 'bedside-table', -lateral, 0, bed);
+                against(back, 'bedside-table', lateral, 0, bed);
+            }
+            if (area >= 10)
+                against(side, 'dresser', side.length * 0.22);
+            if (area >= 13)
+                against(side, 'closet', -side.length * 0.22);
+            break;
+        }
+        case 'kitchen':
+            against(back, back.length >= 2.6 ? 'kitchen' : 'kitchen-counter');
+            if (back.length >= 3.5)
+                against(back, 'stove', back.length / 2 - width('stove') / 2 - 0.1);
+            against(side, 'fridge', side.length * 0.25);
+            break;
+        case 'bathroom':
+            against(back, 'toilet', back.length * 0.25);
+            against(back, 'bathroom-sink', -back.length * 0.2);
+            against(side, area >= 6.5 ? 'bathtub' : 'shower-square');
+            break;
+        case 'living':
+            against(back, 'sofa');
+            against(back, 'coffee-table', 0, depth('sofa') + 0.4, 'sofa');
+            against(side, 'livingroom-chair', -side.length * 0.18);
+            // The TV faces the sofa from the door wall; the placement slides it off the door's clear zone.
+            against(door, 'tv-stand', 0, 0, 'sofa');
+            break;
+        case 'dining': {
+            free('dining-table', bounds.centerX, bounds.centerZ);
+            const ahead = depth('dining-table') / 2 + depth('dining-chair') / 2;
+            const beside = width('dining-table') / 2 + depth('dining-chair') / 2;
+            free('dining-chair', bounds.centerX, bounds.centerZ - ahead);
+            free('dining-chair', bounds.centerX, bounds.centerZ + ahead, 180);
+            if (Math.min(bounds.width, bounds.depth) >= 3) {
+                free('dining-chair', bounds.centerX - beside, bounds.centerZ, 90);
+                free('dining-chair', bounds.centerX + beside, bounds.centerZ, 270);
+            }
+            break;
+        }
+        case 'laundry':
+            against(back, 'washing-machine', -0.55);
+            against(back, 'drying-rack', 0.65);
+            break;
+        case 'entry':
+        case 'hallway':
+            if (Math.min(bounds.width, bounds.depth) >= 1.4)
+                against(side, 'coat-rack');
+            break;
+        case 'storage':
+            against(back, 'closet');
+            break;
+    }
+    return poses;
+}
+const SKIP_REASONS = {
+    outside_bounds: 'outside the room',
+    overlaps_item: 'overlaps another item',
+    off_wall: 'no wall to stand against there',
+};
+const round = (value) => Math.round(value * 100) / 100;
+/**
+ * Why a piece was skipped, with its size: told only "bathtub: blocks door clearance", an agent
+ * set the same tub there with place_items. An item the room cannot hold in any turn says so and
+ * what instead; one in a door's way names the door.
+ */
+function skipReason(asset, pose, reason, room, doors) {
+    const [width = 1, , depth = 1] = asset.dimensions ?? [1, 1, 1];
+    const named = `${asset.id} (${round(width)} × ${round(depth)} m)`;
+    const [roomWidth, roomDepth] = [room.maxX - room.minX, room.maxZ - room.minZ];
+    const fits = (a, b) => a <= roomWidth && b <= roomDepth;
+    if (!fits(width, depth) && !fits(depth, width))
+        return `${named}: too large for the room (${round(roomWidth)} × ${round(roomDepth)} m); a smaller one, or add_object at the room's size`;
+    if (reason === 'blocks_door_clearance') {
+        const footprint = itemPlanAabb([pose.x, 0, pose.z], asset.dimensions, (pose.rotationDeg * Math.PI) / 180);
+        const door = doors.find((keepout) => itemBlocksDoorKeepout(footprint, keepout));
+        return `${named}: in the way of ${door ? `door ${door.doorId}` : 'the door wall kept clear for a door'}`;
+    }
+    return `${named}: ${SKIP_REASONS[reason]}`;
+}
+/**
+ * How a wall-bound piece looks for a spot: along its wall, its whole width within the wall's ends
+ * (`at` is where it starts, off the wall's middle), barely off it, against a wall that stands.
+ */
+function againstItsWall(wall, at, width, walls) {
+    // A piece wider than its wall stands at the wall's middle.
+    const reach = (wall.length - width) / 2;
+    return {
+        lateralsM: reach >= 0 ? lateralSteps(-reach - at, reach - at) : [-at],
+        insetsM: AGAINST_WALL_INSETS_M,
+        // A level with no walls yet is furnished by its outline alone; verify_scene judges no piece there.
+        ...(walls.length > 0 ? { againstWalls: walls } : {}),
+    };
+}
+/**
+ * `furnish_room`: a room type's pieces from the host's catalog, against the walls the door decides,
+ * each moved off door clear zones and other items or skipped with the reason. The door wall is the
+ * edge a door of the room stands on (found by position), else doorWallIndex, else edge 0.
+ */
+export const furnishRoom = (nodes, input, context) => {
+    const catalog = context.catalog;
+    if (!catalog)
+        refuse('no_catalog', 'This host has no item catalog to furnish from.');
+    const { levelId, polygon } = roomToFurnish(nodes, input, context);
+    const level = nodes[levelId];
+    if (level && levelRole(nodes, level).role === 'roof')
+        refuse('roof_level', `${level.name || level.id} is a roof level, not a storey.`, { levelId });
+    if (input.doorWallIndex !== undefined && input.doorWallIndex >= polygon.length)
+        refuse('edge_out_of_range', `The room has ${polygon.length} edges (0–${polygon.length - 1}); there is no edge ${input.doorWallIndex}.`);
+    const doors = doorsOfRoom(nodes, levelId, polygon);
+    const doorWall = input.doorWallIndex ?? doors[0]?.edge ?? 0;
+    const all = Object.values(nodes);
+    const doorKeepouts = collectDoorKeepouts(all, { levelId });
+    const keepouts = doorKeepouts.map((door) => door.aabb);
+    // A door wall without a door yet keeps the middle of it clear for the one to come.
+    if (!doors.some((door) => door.edge === doorWall)) {
+        const planned = keepoutForPolygonEdge(polygon, doorWall, { t: 0.5, width: 0.9 });
+        if (planned && !keepouts.some((keepout) => keepoutCoversPlanned(keepout, planned)))
+            keepouts.push(planned);
+    }
+    const occupied = collectOccupiedFootprints(all, { levelId, floorOnly: true }).map((footprint) => footprint.aabb);
+    const { minX, maxX, minZ, maxZ } = polygonBounds(polygon);
+    const walls = wallFacesOn(all, levelId);
+    const items = [];
+    const skipped = [];
+    // How far each piece was moved off the spot the layout gave it, for the pieces that follow it.
+    const moved = new Map();
+    for (const pose of layout(input.roomType, polygon, doorWall, catalog)) {
+        const asset = catalog.find((entry) => entry.id === pose.assetId);
+        if (!asset) {
+            skipped.push(`${pose.assetId}: not in the catalog`);
+            continue;
+        }
+        // Along its own wall only: a TV across the room slides as its sofa did and stays on its wall.
+        const lead = pose.follows ? moved.get(pose.follows) : undefined;
+        const slide = lead && pose.along ? lead[0] * pose.along.x + lead[1] * pose.along.z : 0;
+        const spot = {
+            x: pose.x + (pose.along?.x ?? 0) * slide,
+            z: pose.z + (pose.along?.z ?? 0) * slide,
+            rotationDeg: pose.rotationDeg,
+        };
+        const found = findValidPlacement({
+            primary: spot,
+            dimensions: asset.dimensions,
+            doorKeepouts: keepouts,
+            occupied,
+            roomBounds: { minX, maxX, minZ, maxZ },
+            roomOutline: polygon,
+            along: pose.along,
+            inward: pose.inward,
+            ...(pose.wall && furnitureKind(asset) === 'wall'
+                ? againstItsWall(pose.wall, pose.wall.lateral + slide, asset.dimensions?.[0] ?? 1, walls)
+                : {}),
+        });
+        if (!found.candidate) {
+            const at = found.refused ?? spot;
+            skipped.push(skipReason(asset, at, found.reason, { minX, maxX, minZ, maxZ }, doorKeepouts));
+            continue;
+        }
+        const { candidate } = found;
+        moved.set(pose.assetId, [candidate.x - pose.x, candidate.z - pose.z]);
+        const rotation = (candidate.rotationDeg * Math.PI) / 180;
+        occupied.push(itemPlanAabb([candidate.x, 0, candidate.z], asset.dimensions, rotation));
+        items.push(ItemNode.parse({
+            name: asset.name,
+            parentId: levelId,
+            position: [candidate.x, 0, candidate.z],
+            rotation: [0, rotation, 0],
+            asset,
+        }));
+    }
+    const itemIds = items.map((item) => item.id);
+    // Each piece with its size and id, as the skips are told: the set is not read back from the scene.
+    const pieces = items.map((item) => {
+        const [width = 1, , depth = 1] = item.asset.dimensions ?? [1, 1, 1];
+        return `${item.name ?? item.asset.name} (${round(width)} × ${round(depth)} m): ${item.id}`;
+    });
+    return {
+        result: {
+            ok: true,
+            placed: items.length,
+            itemIds,
+            pieces,
+            skipped,
+            doorWallIndex: doorWall,
+            doorsDetected: doors.length,
+            message: `Furnished the ${input.roomType} with ${items.length} item${items.length === 1 ? '' : 's'}${skipped.length ? `, skipped ${skipped.length}` : ''}.${skipped.length ? ` For what was skipped: ${OTHER_SOURCES}` : ''}${input.zoneId && items.length ? ` view_scene with interior { zoneId: "${input.zoneId}" } shows the room from inside, at a person's height.` : ''}`,
+        },
+        ...(items.length
+            ? { changes: { create: items.map((node) => ({ node, parentId: levelId })) } }
+            : {}),
+    };
+};