@pascal-app/core 1.0.6 → 1.0.7

package/dist/agent-operations/add-object.d.ts

@@ -1,6 +1,7 @@
+import { type ObjectPiece } from '../agent-tools/add-object.js';
 import { type ScriptedNode } from '../lib/geometry-script-node.js';
 import { type AnyNode, type CompiledGeometryScript, type GeometryScriptLanguage, type GeometryScriptParamValue, type WallFace } from '../schema/index.js';
-import type { AgentOperation, BatchedObject } from './types.js';
+import type { AgentContext, AgentOperation, BatchedObject } from './types.js';
 export type AddObjectInput = {
     /** Absent for a params-only edit: the host compiled the object's stored script. */
     code?: string;
@@ -11,12 +12,19 @@ export type AddObjectInput = {
     /** Degrees about Y, as the contract parses it. */
     rotation?: number;
     side?: 'front' | 'back';
+    /** The module's slot colours as written, not their library matches. */
+    exact?: boolean;
     name?: string;
     description?: string;
     tags?: string[];
     category?: string;
     /** What the object stands in for; kept in `metadata.reason`, listed by verify_scene. */
     reason?: string;
+    /**
+     * Roof geometry (`metadata.role: 'roof'`) for a roof level: not storey content, so the storey's
+     * wall and slab shape refusals do not apply. Set by author_scene, not by the tool's contract.
+     */
+    role?: 'roof';
     /** What the surface's compile produced from `code` (compiled before the operation runs). */
     compiled: CompiledGeometryScript;
 };
@@ -41,6 +49,20 @@ export declare function requireAddObjectReason(input: {
     nodeId?: string;
     reason?: string;
 }): void;
+/** A piece to make from words (`add_object`'s `piece`): what a maker reads, and where it lands. */
+export type PlannedPiece = {
+    id: string;
+    description: string;
+    size: [number, number, number];
+    mount: ObjectPiece['mount'];
+    /** The add_object call, without code, that places it once its module lands; null: made only. */
+    place: Omit<AddObjectInput, 'compiled' | 'code'> | null;
+};
+/** The piece path of add_object, before any host makes it: the same refusals on every surface. */
+export declare function planPiece(input: Omit<AddObjectInput, 'compiled'> & {
+    piece: ObjectPiece;
+    language?: unknown;
+}): PlannedPiece;
 export declare const addObject: AgentOperation<AddObjectInput>;
 /**
  * `add_object` inside run_batch: the batch's host built the module before the batch ran (a compile
@@ -57,7 +79,7 @@ export declare const addObjectInBatch: AgentOperation<Omit<AddObjectInput, 'comp
 export declare function buildBatchObjects(calls: readonly {
     tool?: unknown;
     input?: unknown;
-}[], build: (input: Omit<AddObjectInput, 'compiled'>) => Promise<CompiledGeometryScript>): Promise<Record<number, BatchedObject>>;
+}[], build: (input: Omit<AddObjectInput, 'compiled'>) => Promise<CompiledGeometryScript>, designBrief?: AgentContext['designBrief']): Promise<Record<number, BatchedObject>>;
 export type RescriptOpeningInput = {
     description?: string;
     category?: string;
@@ -107,22 +129,26 @@ export declare function refuseParamsWithoutScript(nodes: Record<string, AnyNode>
  * fields would no longer match the geometry. Restating the current value passes.
  */
 export declare function scriptedFieldRefusal(node: AnyNode, data: Record<string, unknown>): string | null;
-/** What `get_source` reads: a scripted node, a room's floor script, or a wall face's script. */
+/**
+ * What `get_source` reads: a scripted node, a room's floor script, a slab's surface script, or a
+ * wall face's script.
+ */
 export type ScriptReadable = Pick<ScriptedNode, 'name' | 'source'> & {
     id: string;
-    type: ScriptedNode['type'] | 'zone' | 'wall';
+    type: ScriptedNode['type'] | 'zone' | 'slab' | 'wall';
     /** The wall face whose script it is. */
     face?: WallFace;
 };
 /**
  * The script `get_source` reads at `nodeId`: an authored object's, a room's floor script by its
- * zone id, or a wall's face script (`face`, which a wall with one scripted face may leave out).
+ * zone id, a slab's surface script by its slab id, or a wall's face script (`face`, which a wall
+ * with one scripted face may leave out).
  */
 export declare function readableScript(nodes: Record<string, AnyNode>, nodeId: string, face?: WallFace): ScriptReadable;
 /** What `get_source` answers once the host has the module's text. */
 export declare function readSourceResult(node: ScriptReadable, code: string): {
     nodeId: string;
-    type: "column" | "door" | "item" | "wall" | "window" | "zone";
+    type: "column" | "door" | "item" | "slab" | "wall" | "window" | "zone";
     face?: WallFace | undefined;
     name: string | undefined;
     language: "bpy" | "three";

package/dist/agent-operations/add-object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-object.d.ts","sourceRoot":"","sources":["../../src/agent-operations/add-object.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"add-object.d.ts","sourceRoot":"","sources":["../../src/agent-operations/add-object.ts"],"names":[],"mappings":"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"}

package/dist/agent-operations/add-object.js

@@ -3,13 +3,16 @@ import { addObjectTool } from '../agent-tools/add-object.js';
 import { isAgentRefusal, refuse } from '../agent-tools/refusal.js';
 import { CATALOG_SOURCE } from '../agent-tools/sources.js';
 import { artifactUrl } from '../lib/artifact-store.js';
-import { isScriptedNode, matchScriptSlotsToLibrary, requireMeasured, scriptedSize, scriptInteractive, scriptSource, } from '../lib/geometry-script-node.js';
+import { isScriptedNode, matchScriptSlotsToLibrary, rebuiltInteractive, requireMeasured, scriptedSize, scriptInteractive, scriptSource, } from '../lib/geometry-script-node.js';
 import { geometryRestingHeight, resettledPosition } from '../lib/geometry-surfaces.js';
 import { area, intersection, union } from '../lib/polygon-boolean.js';
 import { generateId, ItemNode, } from '../schema/index.js';
 import { achievedChanges } from './achieved.js';
+import { requireFurnishing } from './design-brief.js';
 import { targetLevel } from './level-target.js';
 import { roofLevelRefusal } from './roof-writes.js';
+import { exactColorMaterial, exactScriptSlots } from './scene-materials.js';
+import { queryNodes } from './scene-queries.js';
 const ATTACH = {
     floor: undefined,
     wall: 'wall',
@@ -22,11 +25,14 @@ const HOSTS = {
     'wall-side': ['wall'],
     ceiling: ['ceiling'],
 };
-function scriptAsset(compiled, input, previous) {
+function scriptAsset(compiled, input, previousNode) {
+    const previous = previousNode?.asset;
     const { min, max } = compiled.manifest.bounds;
     const restingHeight = geometryRestingHeight(compiled.manifest);
     const attachTo = ATTACH[compiled.mount];
-    const interactive = scriptInteractive(compiled.manifest);
+    const interactive = previousNode
+        ? rebuiltInteractive(compiled.manifest, previousNode)
+        : scriptInteractive(compiled.manifest);
     return {
         id: `script_${compiled.sha256.slice(0, 16)}`,
         category: input.category ?? previous?.category ?? 'object',
@@ -97,7 +103,7 @@ const FLOOR_SHARE = 0.5;
  * the compile measured, turned and placed as the object will be.
  */
 function shareOverFloor(nodes, levelId, compiled, input) {
-    const slabs = Object.values(nodes).filter((node) => node.type === 'slab' && node.parentId === levelId);
+    const slabs = queryNodes(nodes, { type: 'slab', parentId: levelId });
     const { min, max } = compiled.manifest.bounds;
     const footprintArea = (max[0] - min[0]) * (max[2] - min[2]);
     if (slabs.length === 0 || !(footprintArea > 0))
@@ -183,10 +189,40 @@ export function requireAddObjectReason(input) {
     if (!input.nodeId && !input.reason?.trim())
         refuse('reason_required', 'Give its design intent (reason): why the authored shape, size or style suits the request. The scene check lists every authored object with its reason; no catalog-exhaustion proof is required.');
 }
+/** The piece path of add_object, before any host makes it: the same refusals on every surface. */
+export function planPiece(input) {
+    if (input.code)
+        refuse('piece_with_code', 'Pass code or piece, not both: piece has Pascal write the module.');
+    if (input.nodeId)
+        refuse('piece_on_edit', 'piece makes a new object; to change an object, pass its nodeId with code or params.');
+    requireAddObjectReason(input);
+    const { piece, params: _params, language: _language, code: _code, ...place } = input;
+    return {
+        id: piece.id ?? generateId('piece'),
+        description: piece.description,
+        size: [piece.size.width, piece.size.height, piece.size.depth],
+        mount: piece.mount ?? 'floor',
+        place: place.position || place.parentId ? place : null,
+    };
+}
 export const addObject = (nodes, input, context) => {
     const { compiled } = input;
     requireMeasured(compiled, { label: input.name, nodeId: input.nodeId, tool: 'add_object' });
     const rotation = input.rotation === undefined ? undefined : [0, (input.rotation * Math.PI) / 180, 0];
+    const createdMaterials = [];
+    const slotsOf = (matched) => {
+        if (!input.exact)
+            return matched;
+        const materials = { ...context.materials };
+        return exactScriptSlots(compiled.manifest, matched, (hex, surface) => {
+            const resolved = exactColorMaterial(context.materials && materials, hex, surface);
+            if (resolved.created) {
+                materials[resolved.sceneMaterial.id] = resolved.sceneMaterial;
+                createdMaterials.push(resolved.sceneMaterial);
+            }
+            return resolved.ref;
+        });
+    };
     if (input.nodeId) {
         if (nodes[input.nodeId]?.type === 'column')
             refuse('use_column_tool', `Rebuild ${input.nodeId} with add_column and nodeId.`, {
@@ -205,8 +241,8 @@ export const addObject = (nodes, input, context) => {
             rotation: rotation ?? previous.rotation,
             ...(input.side === undefined ? {} : { side: input.side }),
             source: scriptSource(compiled, itemSourceMeta(input), previous.source),
-            slots: matchScriptSlotsToLibrary(compiled.manifest, previous.slots, previous.source?.manifest),
-            asset: scriptAsset(compiled, input, previous.asset),
+            slots: slotsOf(matchScriptSlotsToLibrary(compiled.manifest, previous.slots, previous.source?.manifest)),
+            asset: scriptAsset(compiled, input, previous),
             ...(input.reason ? { metadata: { ...previous.metadata, reason: input.reason } } : {}),
         });
         // Children resting on or hanging from the object follow its new geometry.
@@ -230,6 +266,7 @@ export const addObject = (nodes, input, context) => {
                     { id: next.id, data: next },
                     ...resettled.map(({ id, position }) => ({ id, data: { position } })),
                 ],
+                ...(createdMaterials.length ? { materials: createdMaterials } : {}),
             },
         };
     }
@@ -240,7 +277,7 @@ export const addObject = (nodes, input, context) => {
     if (!hosts.includes(parent.type)) {
         refuse('wrong_host', `A ${compiled.mount} object goes on a ${hosts.join(' or ')}, not on a ${parent.type}. Pass parentId of a ${hosts[0]}, or change \`mount\`.`, { mount: compiled.mount, parentType: parent.type });
     }
-    if (compiled.mount === 'floor' && parent.type === 'level') {
+    if (compiled.mount === 'floor' && parent.type === 'level' && input.role !== 'roof') {
         // Given no host while the roof level is in view (a roof just placed selects it), the object
         // belongs on the storey it covers; one named onto the roof level goes up with the roof (a
         // chimney cap, a gable louvre).
@@ -267,9 +304,9 @@ export const addObject = (nodes, input, context) => {
             0,
         ],
         source: scriptSource(compiled, itemSourceMeta(input)),
-        slots: matchScriptSlotsToLibrary(compiled.manifest),
+        slots: slotsOf(matchScriptSlotsToLibrary(compiled.manifest)),
         asset,
-        metadata: { reason: input.reason },
+        metadata: { reason: input.reason, ...(input.role ? { role: input.role } : {}) },
     });
     const hint = [
         typeHint(input),
@@ -281,7 +318,10 @@ export const addObject = (nodes, input, context) => {
         .join(' ');
     return {
         result: { ...summary(node, compiled, []), ...(hint ? { hint } : {}) },
-        changes: { create: [{ node, parentId: parent.id }] },
+        changes: {
+            create: [{ node, parentId: parent.id }],
+            ...(createdMaterials.length ? { materials: createdMaterials } : {}),
+        },
     };
 };
 /**
@@ -309,7 +349,7 @@ const BATCH_COMPILES_AT_ONCE = 3;
  * that refuses) is kept with its own message, so the batch reports it and the others stand. A call
  * whose input does not parse is left out: the batch refuses it with the contract's message.
  */
-export async function buildBatchObjects(calls, build) {
+export async function buildBatchObjects(calls, build, designBrief) {
     const parse = z.object(addObjectTool.input);
     const built = {};
     const edited = new Set();
@@ -338,6 +378,7 @@ export async function buildBatchObjects(calls, build) {
     const worker = async () => {
         for (let job = jobs[next++]; job; job = jobs[next++]) {
             try {
+                requireFurnishing('add_object', job.input, designBrief);
                 requireAddObjectReason(job.input);
                 built[job.index] = { compiled: await build(job.input) };
             }
@@ -477,7 +518,8 @@ export function scriptedFieldRefusal(node, data) {
 }
 /**
  * The script `get_source` reads at `nodeId`: an authored object's, a room's floor script by its
- * zone id, or a wall's face script (`face`, which a wall with one scripted face may leave out).
+ * zone id, a slab's surface script by its slab id, or a wall's face script (`face`, which a wall
+ * with one scripted face may leave out).
  */
 export function readableScript(nodes, nodeId, face) {
     const node = nodes[nodeId];
@@ -499,6 +541,11 @@ export function readableScript(nodes, nodeId, face) {
             });
         return { id: node.id, type: 'wall', name: node.name, source, face: read };
     }
+    if (node?.type === 'slab') {
+        if (!node.surfaceScript)
+            refuse('not_authored', `${node.name || nodeId} has no surface script.`, { id: nodeId });
+        return { id: node.id, type: 'slab', name: node.name, source: node.surfaceScript };
+    }
     if (node?.type !== 'zone')
         return authoredObject(nodes, nodeId);
     if (!node.floor?.script)

package/dist/agent-operations/add-wall.d.ts

@@ -1,13 +1,8 @@
-import { type LevelTargetInput } from './level-target.js';
 import type { AgentOperation } from './types.js';
-type AddWallInput = LevelTargetInput & {
-    start: number[];
-    end: number[];
-    thickness?: number;
-    height?: number;
-    curveOffset?: number;
-};
+type AddWallInput = z.infer<z.ZodObject<typeof addWallTool.input>>;
 /** `add_wall`: one wall between two points, named as the editor names walls. */
 export declare const addWall: AgentOperation<AddWallInput>;
+import type { z } from 'zod';
+import type { addWallTool } from '../agent-tools/walls.js';
 export {};
 //# sourceMappingURL=add-wall.d.ts.map

package/dist/agent-operations/add-wall.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-wall.d.ts","sourceRoot":"","sources":["../../src/agent-operations/add-wall.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,gBAAgB,CAAA;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAG7C,KAAK,YAAY,GAAG,gBAAgB,GAAG;IACrC,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,GAAG,EAAE,MAAM,EAAE,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,gFAAgF;AAChF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,YAAY,CAiFhD,CAAA"}
+{"version":3,"file":"add-wall.d.ts","sourceRoot":"","sources":["../../src/agent-operations/add-wall.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAI7C,KAAK,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,CAAA;AAElE,gFAAgF;AAChF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,YAAY,CAoGhD,CAAA;AAED,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/agent-operations/add-wall.js

@@ -3,16 +3,25 @@ import { levelFootprintLoops } from '../lib/building-footprint.js';
 import { foundationReadingOfLevel } from '../lib/foundation-construction.js';
 import { foundationWallRule, levelHoldsFoundationWalls, withFoundationConstruction, } from '../lib/foundation-wall.js';
 import { lotOverhang } from '../lib/site-placement.js';
-import { WallNode } from '../schema/index.js';
+import { railingWallDefaults, WallNode } from '../schema/index.js';
 import { normalizeWallCurveOffset } from '../systems/wall/wall-curve.js';
 import { WALL_MIN_LENGTH } from '../systems/wall/wall-topology.js';
 import { applySceneChanges } from './apply-changes.js';
 import { targetLevel } from './level-target.js';
 import { refuseRoofLevel } from './roof-writes.js';
+import { queryNodes } from './scene-queries.js';
+import { wallTypePatch } from './wall-type.js';
 /** `add_wall`: one wall between two points, named as the editor names walls. */
 export const addWall = (nodes, input, context) => {
     const level = targetLevel(nodes, input, context);
     refuseRoofLevel(nodes, level.id, 'a wall');
+    const railing = input.wallType === 'railing';
+    if (input.railing && !railing)
+        refuse('not_a_railing', 'railing settings require wallType railing.');
+    if (railing && input.type !== undefined)
+        refuse('railing_wall', 'A railing has no assembly: omit type.');
+    const guardDefaults = railing ? railingWallDefaults(input.railing?.style) : undefined;
+    const guard = guardDefaults ? { ...guardDefaults.railing, ...input.railing } : undefined;
     const start = input.start;
     const end = input.end;
     const length = Math.hypot(end[0] - start[0], end[1] - start[1]);
@@ -21,7 +30,8 @@ export const addWall = (nodes, input, context) => {
     const curveOffset = input.curveOffset
         ? normalizeWallCurveOffset({ start, end }, input.curveOffset)
         : 0;
-    const walls = Object.values(nodes).filter((node) => node.type === 'wall').length;
+    const walls = queryNodes(nodes, { type: 'wall' }).length;
+    const assembly = input.type === undefined ? {} : wallTypePatch(nodes, input.type);
     const drawn = WallNode.parse({
         name: `Wall ${walls + 1}`,
         parentId: level.id,
@@ -30,14 +40,27 @@ export const addWall = (nodes, input, context) => {
         ...(input.thickness === undefined ? {} : { thickness: input.thickness }),
         ...(input.height === undefined ? {} : { height: input.height }),
         ...(curveOffset ? { curveOffset } : {}),
+        ...assembly,
+        ...(input.wallType === undefined ? {} : { wallType: input.wallType }),
+        ...(guardDefaults && guard
+            ? {
+                ...guardDefaults,
+                railing: guard,
+                height: input.height ?? guardDefaults.height,
+                thickness: guard.postSize,
+            }
+            : {}),
     });
-    const [wall] = withFoundationConstruction(nodes, level.id, [
-        ...Object.values(nodes).filter((node) => node.type === 'wall' && node.parentId === level.id),
-        drawn,
-    ], [drawn], { thickness: input.thickness });
+    const [wall] = railing
+        ? [drawn]
+        : withFoundationConstruction(nodes, level.id, [...queryNodes(nodes, { type: 'wall', parentId: level.id }), drawn], [drawn], { thickness: input.thickness, ...assembly });
     const reading = foundationReadingOfLevel(nodes, level.id);
-    const foundation = wall.assembly !== undefined;
-    const partition = !foundation && input.thickness === undefined && levelHoldsFoundationWalls(nodes, level.id);
+    const foundation = input.type === undefined && wall.assembly !== undefined;
+    const partition = !railing &&
+        !foundation &&
+        input.type === undefined &&
+        input.thickness === undefined &&
+        levelHoldsFoundationWalls(nodes, level.id);
     // the wall's mitred band, curve and all: what crosses the lot line, not only its centreline
     const after = applySceneChanges(nodes, { create: [{ node: wall, parentId: level.id }] });
     const site = lotOverhang(after, level.id, levelFootprintLoops(after, after[level.id], null, new Set([wall.id])));

package/dist/agent-operations/apply-changes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply-changes.d.ts","sourceRoot":"","sources":["../../src/agent-operations/apply-changes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA6B,MAAM,WAAW,CAAA;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAelE;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,SAAS,SAAS,EAAE,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoCzB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,YAAY,GAAG,SAAS,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,YAAY,EAAE,GAC5B,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,GAAG,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAyC7E"}
+{"version":3,"file":"apply-changes.d.ts","sourceRoot":"","sources":["../../src/agent-operations/apply-changes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAA6B,MAAM,WAAW,CAAA;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAelE;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,SAAS,SAAS,EAAE,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoCzB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,YAAY,GAAG,SAAS,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,YAAY,EAAE,GAC5B,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,GAAG,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAyC7E"}

package/dist/agent-operations/apply-changes.js

@@ -1,3 +1,4 @@
+import { draftOf } from '../runtime/reader.js';
 const childrenOf = (node) => node && 'children' in node && Array.isArray(node.children) ? node.children : null;
 /**
  * A node with a patch applied. A field the patch sets to `undefined` is removed, as the store's
@@ -16,7 +17,7 @@ function patched(node, data) {
  * it. A create is written as given; parse it first for its schema's defaults.
  */
 export function applySceneWrites(nodes, writes) {
-    const next = { ...nodes };
+    const next = draftOf(nodes);
     const setChildren = (parentId, edit) => {
         const parent = parentId ? next[parentId] : undefined;
         const children = childrenOf(parent);

package/dist/agent-operations/asset-catalog.d.ts

@@ -0,0 +1,63 @@
+import type { AssetInput } from '../schema/index.js';
+import type { AgentContext, SceneNodes } from './types.js';
+/** One search of an item library: its words (none lists the library), a category, at most `limit` hits. */
+export type AssetSearchQuery = {
+    text?: string;
+    category?: string;
+    limit: number;
+};
+export type AssetSearchResult = {
+    /** The best hits first, at most the query's limit. */
+    items: AssetInput[];
+    /** Every item the query matches. */
+    total: number;
+    /** The categories of every match, most first, where the host counts them: a cut search names them to narrow by. */
+    categories?: {
+        name: string;
+        count: number;
+    }[];
+};
+/**
+ * An item library a host searches where it is kept (a database) instead of handing every item
+ * over: ranked hits per query, and the items a call names, by id. A library of 100k items is
+ * never held whole by a session or a browser tab.
+ */
+export type AssetCatalogSource = {
+    search(query: AssetSearchQuery): Promise<AssetSearchResult>;
+    byId(ids: readonly string[]): Promise<AssetInput[]>;
+};
+/** What a host's agent tools place from: every item (a built-in list), or a source it searches. */
+export type AssetCatalog = readonly AssetInput[] | AssetCatalogSource;
+export declare const isAssetCatalogSource: (catalog: AssetCatalog) => catalog is AssetCatalogSource;
+/**
+ * Items in the order search_assets lists them for `text` (`rank`); items that rank alike keep the
+ * order they came in. A host that finds hits its own way (a database's fusion) orders them so too.
+ */
+export declare function rankAssets(items: readonly AssetInput[], text: string): AssetInput[];
+/**
+ * A search of a list held whole: the items whose name, id, category or tags hold every word of
+ * the query, best first (`rankAssets`, then by name), with the categories of all of them.
+ */
+export declare function searchAssetList(items: readonly AssetInput[], { text, category, limit }: AssetSearchQuery): AssetSearchResult;
+/** A list served as a source: searched as `searchAssetList` does, items by id. */
+export declare function assetCatalogSource(items: readonly AssetInput[]): AssetCatalogSource;
+/** The key of a search in `catalogSearches`: its words, category and limit. */
+export declare const assetSearchKey: ({ text, category, limit }: AssetSearchQuery) => string;
+/** The searches a `search_assets` input runs, one per query, as its operation reads them. */
+export declare function assetSearchesOf(input: unknown): AssetSearchQuery[];
+/**
+ * What a call reads of the library, alone or in a batch: the searches of `search_assets`, and the
+ * ids the others look up — the items placed or viewed, furnish_room's set for its room type, the
+ * catalog items a paint with no role finishes (their models list the surfaces).
+ */
+export declare function catalogReads(nodes: SceneNodes, tool: string, input: unknown): {
+    ids: string[];
+    searches: AssetSearchQuery[];
+};
+/**
+ * What a call reads of the host's library, read before it as the operations are sync. A list is
+ * handed over whole. A source answers the call's searches (`catalogSearches`) and gives the items
+ * the call names (`catalog`), so a call that names none reads nothing.
+ */
+export declare function readCatalog(nodes: SceneNodes, tool: string, input: unknown, catalog: AssetCatalog): Promise<Pick<AgentContext, 'catalog' | 'catalogSearches'>>;
+//# sourceMappingURL=asset-catalog.d.ts.map

package/dist/agent-operations/asset-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-catalog.d.ts","sourceRoot":"","sources":["../../src/agent-operations/asset-catalog.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAI3C,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEvD,2GAA2G;AAC3G,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAElF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,sDAAsD;IACtD,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,mHAAmH;IACnH,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAC/C,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAC3D,IAAI,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;CACpD,CAAA;AAED,mGAAmG;AACnG,MAAM,MAAM,YAAY,GAAG,SAAS,UAAU,EAAE,GAAG,kBAAkB,CAAA;AAErE,eAAO,MAAM,oBAAoB,YAAa,YAAY,KAAG,OAAO,IAAI,kBAC/C,CAAA;AA4DzB;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAKnF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,EAAE,IAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,gBAAgB,GAC/C,iBAAiB,CAiBnB;AAED,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,kBAAkB,CAMnF;AAED,+EAA+E;AAC/E,eAAO,MAAM,cAAc,8BAAoC,gBAAgB,KAAG,MACjC,CAAA;AAKjD,6FAA6F;AAC7F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAalE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb;IAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAqCjD;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,iBAAiB,CAAC,CAAC,CAe5D"}

package/dist/agent-operations/asset-catalog.js

@@ -0,0 +1,182 @@
+import { SEARCH_ASSETS_LIMIT } from '../agent-tools/assets.js';
+import { roleLessPaints } from './asset-views.js';
+import { placedAssets } from './design-brief.js';
+import { FURNISH_ROOM_ASSETS } from './furnish-room.js';
+export const isAssetCatalogSource = (catalog) => !Array.isArray(catalog);
+const wordsOf = (text) => text
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter(Boolean);
+function matches(item, text, category) {
+    if (category && item.category !== category)
+        return false;
+    const haystack = [
+        item.id,
+        item.name,
+        item.category,
+        ...(item.tags ?? []),
+        ...(item.functionTags ?? []),
+    ]
+        .join(' ')
+        .toLowerCase();
+    return text
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean)
+        .every((term) => haystack.includes(term));
+}
+/**
+ * How well an item answers a query, lower first: 0 is its name or id exactly, else the weakest of
+ * the query's words, 1 a word of the name ("bed" in "Platform Bed"), 2 starting one ("Bedside
+ * Table"), 3 starting a word of the category, 4 of a tag, 5 inside the name, 6 anywhere else. The
+ * sum orders items whose weakest word ties.
+ */
+function rank(item, query) {
+    const whole = query.trim().toLowerCase().replace(/\s+/g, ' ');
+    if (whole === item.name.trim().toLowerCase().replace(/\s+/g, ' ') ||
+        whole === item.id.toLowerCase())
+        return [0, 0];
+    const name = item.name.toLowerCase();
+    const nameWords = wordsOf(item.name);
+    const categoryWords = wordsOf(item.category);
+    const tagWords = [...(item.tags ?? []), ...(item.functionTags ?? [])].flatMap(wordsOf);
+    const startsOne = (words, word) => words.some((w) => w.startsWith(word));
+    const ranks = wordsOf(query).map((word) => nameWords.includes(word)
+        ? 1
+        : startsOne(nameWords, word)
+            ? 2
+            : startsOne(categoryWords, word)
+                ? 3
+                : startsOne(tagWords, word)
+                    ? 4
+                    : name.includes(word)
+                        ? 5
+                        : 6);
+    return [Math.max(0, ...ranks), ranks.reduce((sum, value) => sum + value, 0)];
+}
+/**
+ * Items in the order search_assets lists them for `text` (`rank`); items that rank alike keep the
+ * order they came in. A host that finds hits its own way (a database's fusion) orders them so too.
+ */
+export function rankAssets(items, text) {
+    return items
+        .map((item) => ({ item, rank: rank(item, text) }))
+        .sort((a, b) => a.rank[0] - b.rank[0] || a.rank[1] - b.rank[1])
+        .map(({ item }) => item);
+}
+/**
+ * A search of a list held whole: the items whose name, id, category or tags hold every word of
+ * the query, best first (`rankAssets`, then by name), with the categories of all of them.
+ */
+export function searchAssetList(items, { text = '', category, limit }) {
+    const found = rankAssets(
+    // Stable: items of one name keep the list's order.
+    items
+        .filter((item) => matches(item, text, category))
+        .sort((a, b) => a.name.localeCompare(b.name, 'en')), text);
+    const counts = new Map();
+    for (const item of found)
+        counts.set(item.category, (counts.get(item.category) ?? 0) + 1);
+    return {
+        items: found.slice(0, limit),
+        total: found.length,
+        categories: [...counts]
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0], 'en'))
+            .map(([name, count]) => ({ name, count })),
+    };
+}
+/** A list served as a source: searched as `searchAssetList` does, items by id. */
+export function assetCatalogSource(items) {
+    const byId = new Map(items.map((item) => [item.id, item]));
+    return {
+        search: async (query) => searchAssetList(items, query),
+        byId: async (ids) => ids.flatMap((id) => byId.get(id) ?? []),
+    };
+}
+/** The key of a search in `catalogSearches`: its words, category and limit. */
+export const assetSearchKey = ({ text = '', category, limit }) => JSON.stringify([text, category ?? null, limit]);
+const asRecord = (value) => typeof value === 'object' && value !== null ? value : {};
+/** The searches a `search_assets` input runs, one per query, as its operation reads them. */
+export function assetSearchesOf(input) {
+    const { queries, limit } = asRecord(input);
+    return (Array.isArray(queries) ? queries : []).flatMap((entry) => {
+        const { query, category } = asRecord(entry);
+        if (typeof query !== 'string')
+            return [];
+        return [
+            {
+                text: query,
+                ...(typeof category === 'string' && { category }),
+                limit: typeof limit === 'number' ? limit : SEARCH_ASSETS_LIMIT,
+            },
+        ];
+    });
+}
+/**
+ * What a call reads of the library, alone or in a batch: the searches of `search_assets`, and the
+ * ids the others look up — the items placed or viewed, furnish_room's set for its room type, the
+ * catalog items a paint with no role finishes (their models list the surfaces).
+ */
+export function catalogReads(nodes, tool, input) {
+    const ids = new Set();
+    const searches = [];
+    const visit = (name, args) => {
+        switch (name) {
+            case 'run_batch':
+                for (const call of Array.isArray(args.calls) ? args.calls : []) {
+                    const batched = asRecord(call);
+                    if (batched.tool !== 'run_batch')
+                        visit(batched.tool, asRecord(batched.input));
+                }
+                return;
+            case 'search_assets':
+                searches.push(...assetSearchesOf(args));
+                return;
+            case 'view_assets':
+                for (const id of Array.isArray(args.ids) ? args.ids : [])
+                    if (typeof id === 'string')
+                        ids.add(id);
+                return;
+            case 'furnish_room': {
+                const roomType = String(args.roomType);
+                for (const id of Object.hasOwn(FURNISH_ROOM_ASSETS, roomType)
+                    ? FURNISH_ROOM_ASSETS[roomType]
+                    : [])
+                    ids.add(id);
+                return;
+            }
+        }
+        if (typeof name !== 'string')
+            return;
+        for (const id of placedAssets(name, args))
+            ids.add(id);
+        for (const { targets } of roleLessPaints(name, args))
+            for (const target of targets) {
+                const node = typeof target === 'string' ? nodes[target] : undefined;
+                if (node?.type === 'item' && node.asset?.id)
+                    ids.add(node.asset.id);
+            }
+    };
+    visit(tool, asRecord(input));
+    return { ids: [...ids], searches };
+}
+/**
+ * What a call reads of the host's library, read before it as the operations are sync. A list is
+ * handed over whole. A source answers the call's searches (`catalogSearches`) and gives the items
+ * the call names (`catalog`), so a call that names none reads nothing.
+ */
+export async function readCatalog(nodes, tool, input, catalog) {
+    if (!isAssetCatalogSource(catalog))
+        return { catalog };
+    const { ids, searches } = catalogReads(nodes, tool, input);
+    const [items, answers] = await Promise.all([
+        ids.length ? catalog.byId(ids) : [],
+        Promise.all(searches.map((query) => catalog.search(query))),
+    ]);
+    return {
+        catalog: items,
+        ...(searches.length && {
+            catalogSearches: Object.fromEntries(searches.map((query, index) => [assetSearchKey(query), answers[index]])),
+        }),
+    };
+}