@pascal-app/core 1.0.4 → 1.0.5

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

@@ -1,4 +1,12 @@
+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;
@@ -25,70 +33,285 @@ function boundsInLevel(item, bounds) {
         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'));
+    Boolean(node.asset?.interactive?.effects?.some((effect) => effect.kind === 'light'));
 const matchesWord = (text, word) => Boolean(text) &&
     text
         .toLowerCase()
         .split(/[^a-z0-9]+/)
         .includes(word);
 /**
- * `find_by_type`: everything of one type, nodes and the typed parts of
- * authored objects alike. Parts are read from each object's manifest; the
- * object stays the thing that is selected, moved and edited.
+ * A source id as importers write it into typed provenance: printable ASCII kept, every other
+ * character percent-encoded as UTF-8 bytes.
  */
-export const findByType = (nodes, { type, levelId }) => {
-    // A level that is not there is said, as get_zones says it, not answered with nothing found.
+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);
-    const word = type.trim().toLowerCase().replace(/s$/, '');
+    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 typed = (isScriptedNode(node) ? node.source.manifest.parts : []).filter((part) => part.type);
-        const typedParts = typed.filter((part) => part.type === word);
-        // 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 = node.type === word ||
-            wholeAuthored ||
-            (item &&
-                (matchesWord(item.asset.category, word) ||
-                    (word === 'light' && emitsLight(node) && typedParts.length === 0)));
-        if (wholeMatch) {
-            results.push({
-                id: node.id,
-                name: node.name ?? item?.asset.name,
-                nodeType: node.type,
-                levelId: level,
-            });
-            continue;
-        }
-        for (const part of typedParts) {
-            results.push({
-                id: node.id,
-                name: node.name ?? item?.asset.name,
-                nodeType: node.type,
-                levelId: level,
-                part: part.id,
-                partType: part.type,
-                ...(part.bounds && item && item.parentId === level
-                    ? { bounds: boundsInLevel(item, part.bounds) }
-                    : {}),
-            });
+        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: {
-            type: word,
+            ...(kind === undefined ? {} : { type: kind }),
             count: results.length,
-            nodes: results.filter((entry) => !entry.part).length,
-            parts: results.filter((entry) => entry.part).length,
-            results,
+            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

@@ -1,6 +1,7 @@
 import type { FURNISHED_ROOM_TYPES } from '../agent-tools/furnish-room.js';
 import { type LevelTargetInput } from './level-target.js';
-import type { AgentOperation } from './types.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;
@@ -8,6 +9,26 @@ type FurnishRoomInput = LevelTargetInput & {
     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

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

@@ -1 +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;AAavE,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,gBAAgB,CAAA;AAGnE,OAAO,KAAK,EAAgB,cAAc,EAAc,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;AAkND;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,cAAc,CAAC,gBAAgB,CA8ExD,CAAA"}
+{"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

@@ -1,17 +1,23 @@
 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 { collectOccupiedFootprints, findValidPlacement } from './layout-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.
-const WALL_GAP = 0.1;
+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. */
-function roomToFurnish(nodes, input, context) {
+export function roomToFurnish(nodes, input, context) {
     if (input.zoneId) {
         const zone = nodes[input.zoneId];
         if (!zone)
@@ -56,7 +62,7 @@ function doorsOfRoom(nodes, levelId, polygon) {
     return found;
 }
 /** A polygon edge seen from inside the room: its middle, its direction, and the way into the room. */
-function edgeFrame(polygon, index, center) {
+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;
@@ -81,16 +87,21 @@ function layout(roomType, polygon, doorWall, catalog) {
     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. */
-    const against = (edge, assetId, lateral = 0, out = 0) => {
+    /**
+     * 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 });
@@ -101,8 +112,8 @@ function layout(roomType, polygon, doorWall, catalog) {
             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);
-                against(back, 'bedside-table', lateral);
+                against(back, 'bedside-table', -lateral, 0, bed);
+                against(back, 'bedside-table', lateral, 0, bed);
             }
             if (area >= 10)
                 against(side, 'dresser', side.length * 0.22);
@@ -119,17 +130,14 @@ function layout(roomType, polygon, doorWall, catalog) {
         case 'bathroom':
             against(back, 'toilet', back.length * 0.25);
             against(back, 'bathroom-sink', -back.length * 0.2);
-            if (area >= 6.5)
-                against(side, 'bathtub');
-            else
-                free('shower-square', bounds.centerX, bounds.centerZ);
+            against(side, area >= 6.5 ? 'bathtub' : 'shower-square');
             break;
         case 'living':
             against(back, 'sofa');
-            against(back, 'coffee-table', 0, depth('sofa') + 0.4);
+            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');
+            against(door, 'tv-stand', 0, 0, 'sofa');
             break;
         case 'dining': {
             free('dining-table', bounds.centerX, bounds.centerZ);
@@ -161,6 +169,7 @@ function layout(roomType, polygon, doorWall, catalog) {
 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;
 /**
@@ -182,6 +191,20 @@ function skipReason(asset, pose, reason, room, doors) {
     }
     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
@@ -210,27 +233,45 @@ export const furnishRoom = (nodes, input, context) => {
     }
     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;
         }
-        const { candidate, reason } = findValidPlacement({
-            primary: { x: pose.x, z: pose.z, rotationDeg: pose.rotationDeg },
+        // 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 (!candidate) {
-            skipped.push(skipReason(asset, pose, reason, { minX, maxX, minZ, maxZ }, doorKeepouts));
+        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({
@@ -242,15 +283,21 @@ export const furnishRoom = (nodes, input, context) => {
         }));
     }
     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}` : ''}.`,
+            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 })) } }

package/dist/agent-operations/furniture-kind.d.ts

@@ -0,0 +1,22 @@
+import { type ItemNode } from '../schema/index.js';
+/** How a piece of furniture stands in a room, read from what the catalog calls it. */
+export type FurnitureKind = 'chair' | 'free' | 'wall';
+type Named = {
+    id: string;
+    name?: string | undefined;
+};
+/** Only a named, flat floor covering is nonblocking, never an arbitrary short solid or low top surface. */
+export declare function isFloorUnderlay(item: ItemNode): boolean;
+/**
+ * Wall-bound pieces (a fridge, a counter, a bed, a sofa) stand against a wall and never in the
+ * middle of a room; free-standing ones (a dining table, a rug, a plant) may take the middle; a chair
+ * is placed around its table. A name the table does not know is free-standing.
+ */
+export declare function furnitureKind(asset: Named): FurnitureKind;
+/**
+ * What a piece faces when it does not stand against a wall, as a pattern for the name of the item
+ * it belongs with: the coffee table and the TV face the sofa, a chair faces its table.
+ */
+export declare function anchorOf(asset: Named): string | null;
+export {};
+//# sourceMappingURL=furniture-kind.d.ts.map

package/dist/agent-operations/furniture-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"furniture-kind.d.ts","sourceRoot":"","sources":["../../src/agent-operations/furniture-kind.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,QAAQ,EAAuC,MAAM,WAAW,CAAA;AAEnG,sFAAsF;AACtF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAA;AAErD,KAAK,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAA;AAetD,2GAA2G;AAC3G,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CA+BvD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,CAQzD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAMpD"}