@pascal-app/core 1.0.1 → 1.0.4

package/dist/agent-operations/material-preset.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Why a write (an update's data, a created node, a tool's arguments) may not
+ * store a `materialPreset` / `*MaterialPreset` value or a `slots` entry, or
+ * null. A preset or slot value that names no catalog material renders as the
+ * default finish, and a slot the node does not have never renders, so the
+ * caller would believe a finish landed that never shows. A slot also takes a
+ * plain `#rrggbb` colour. Restating a node's current value passes, so an older
+ * node's bad value never blocks an unrelated edit.
+ */
+export declare function unknownMaterialPresetRefusal(data: Record<string, unknown>, current?: Record<string, unknown>): string | null;
+//# sourceMappingURL=material-preset.d.ts.map

package/dist/agent-operations/material-preset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material-preset.d.ts","sourceRoot":"","sources":["../../src/agent-operations/material-preset.ts"],"names":[],"mappings":"AA6CA;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,GAAG,IAAI,CAkCf"}

package/dist/agent-operations/material-preset.js

@@ -0,0 +1,74 @@
+import { getCatalogMaterialById, LIBRARY_MATERIAL_REF_PREFIX, MATERIAL_CATALOG, parseMaterialColor, parseMaterialRef, } from '../material-library.js';
+import { nodeSlotDeclarations } from '../node-slots/index.js';
+import { AnyNode } from '../schema/index.js';
+const isPresetField = (key) => key === 'materialPreset' || key.endsWith('MaterialPreset');
+// Community-library ids (`library:mtl_…`): the host checks them against its
+// material catalog; without one they pass.
+const COMMUNITY_MATERIAL_ID_PREFIX = 'mtl_';
+function isKnownMaterialRef(value) {
+    const ref = parseMaterialRef(value);
+    if (!ref)
+        return false;
+    if (ref.kind === 'scene' || ref.id.startsWith(COMMUNITY_MATERIAL_ID_PREFIX))
+        return true;
+    return !!getCatalogMaterialById(ref.id);
+}
+function presetCatalogLine() {
+    const byCategory = new Map();
+    for (const item of MATERIAL_CATALOG) {
+        const ids = byCategory.get(item.category) ?? [];
+        ids.push(item.id);
+        byCategory.set(item.category, ids);
+    }
+    return [...byCategory].map(([category, ids]) => `${category}: ${ids.join(', ')}`).join('; ');
+}
+// The slot ids the node exposes as it stands before this write's own slot
+// keys (a block's slot list includes the keys of its `slots`); null when its
+// kind declares none or the node does not parse.
+function declaredSlotIds(data, current) {
+    const parsed = AnyNode.safeParse({ ...current, ...data, slots: current?.slots ?? {} });
+    if (!parsed.success)
+        return null;
+    return nodeSlotDeclarations(parsed.data)?.map((slot) => slot.slotId) ?? null;
+}
+/**
+ * Why a write (an update's data, a created node, a tool's arguments) may not
+ * store a `materialPreset` / `*MaterialPreset` value or a `slots` entry, or
+ * null. A preset or slot value that names no catalog material renders as the
+ * default finish, and a slot the node does not have never renders, so the
+ * caller would believe a finish landed that never shows. A slot also takes a
+ * plain `#rrggbb` colour. Restating a node's current value passes, so an older
+ * node's bad value never blocks an unrelated edit.
+ */
+export function unknownMaterialPresetRefusal(data, current) {
+    const unknown = [];
+    for (const [key, value] of Object.entries(data)) {
+        if (!isPresetField(key) || typeof value !== 'string')
+            continue;
+        if (current && current[key] === value)
+            continue;
+        if (!isKnownMaterialRef(value))
+            unknown.push(`${key} ${JSON.stringify(value)}`);
+    }
+    const parts = [];
+    if (data.slots && typeof data.slots === 'object') {
+        const currentSlots = current?.slots;
+        const changed = Object.entries(data.slots).filter((entry) => typeof entry[1] === 'string' && currentSlots?.[entry[0]] !== entry[1]);
+        for (const [slot, value] of changed) {
+            if (!(parseMaterialColor(value) || isKnownMaterialRef(value))) {
+                unknown.push(`slots.${slot} ${JSON.stringify(value)}`);
+            }
+        }
+        const slotIds = changed.length > 0 ? declaredSlotIds(data, current) : null;
+        const missing = slotIds ? changed.filter(([slot]) => !slotIds.includes(slot)) : [];
+        if (missing.length > 0) {
+            parts.push(`A ${String(data.type ?? current?.type)} has no slot ${missing.map(([slot]) => JSON.stringify(slot)).join(', ')}; its slots are ${slotIds?.join(', ')}.`);
+        }
+    }
+    if (unknown.length > 0) {
+        parts.push(`Unknown material (${unknown.join(', ')}). A material is "${LIBRARY_MATERIAL_REF_PREFIX}<id>" with an id from ${presetCatalogLine()}. A slot also takes a plain colour such as "#2f5585"; to colour a whole node, paint it with material: { properties: { color: "#rrggbb" } }.`);
+    }
+    if (parts.length === 0)
+        return null;
+    return `${parts.join(' ')} Nothing was changed.`;
+}

package/dist/agent-operations/material-refs.d.ts

@@ -0,0 +1,24 @@
+import { type MaterialSurface } from '../material-library.js';
+import type { SceneMaterial, SceneMaterialId } from '../schema/scene-material.js';
+/** The surface a node's finish goes on, by its kind and the role or field painted. */
+export declare function finishSurface(type: string, role?: string): MaterialSurface | undefined;
+/**
+ * Library ids nearest a name asked for: those that suit the surface first (a roof's roofing, a
+ * wall's wall materials, as the library tags them), then by the words they share with it.
+ */
+export declare function nearestLibraryMaterials(asked: string, surface?: MaterialSurface, count?: number): string[];
+/**
+ * A material ref that renders: a library id the catalog holds (`library:<id>`, or the bare id), or
+ * a scene material (`scene:<id>`, checked against the scene's materials when the host lends them).
+ * Anything else would fall back to a default with no word (an unknown preset came out grey), so it
+ * is refused, naming the nearest library ids for the surface; when the library has nothing of the
+ * kind like it, the refusal says so, and that a colour is the nearest (a corrugated roof was once
+ * offered bricks).
+ */
+export declare function requireMaterialRef(asked: string, field?: string, surface?: MaterialSurface, { paint, materials, }?: {
+    /** Whether to point to `paint` for a colour (paint passes it); else a flat library colour. */
+    paint?: boolean;
+    /** The scene's materials, when the host has them. */
+    materials?: Readonly<Record<SceneMaterialId, SceneMaterial>>;
+}): string;
+//# sourceMappingURL=material-refs.d.ts.map

package/dist/agent-operations/material-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material-refs.d.ts","sourceRoot":"","sources":["../../src/agent-operations/material-refs.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AA+B9E,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAGtF;AAYD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,eAAe,EACzB,KAAK,SAAI,GACR,MAAM,EAAE,CAWV;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,eAAe,EACzB,EACE,KAAa,EACb,SAAS,GACV,GAAE;IACD,8FAA8F;IAC9F,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,qDAAqD;IACrD,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC,CAAA;CACxD,GACL,MAAM,CAmCR"}

package/dist/agent-operations/material-refs.js

@@ -0,0 +1,100 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { getCatalogMaterialById, MATERIAL_CATALOG, parseMaterialRef, } from '../material-library.js';
+const SURFACE_WORDS = {
+    roof: 'roofing',
+    wall: 'wall material',
+    floor: 'flooring',
+    ceiling: 'ceiling material',
+    furniture: 'joinery material',
+    outdoor: 'outdoor material',
+};
+/** The surface a kind's finish covers, as the library tags materials; a roof's `wall` role is a wall. */
+const KIND_SURFACES = {
+    roof: 'roof',
+    'roof-segment': 'roof',
+    dormer: 'roof',
+    wall: 'wall',
+    column: 'wall',
+    slab: 'floor',
+    stair: 'floor',
+    'stair-segment': 'floor',
+    ceiling: 'ceiling',
+    fence: 'outdoor',
+    chimney: 'outdoor',
+    door: 'furniture',
+    window: 'furniture',
+    item: 'furniture',
+    cabinet: 'furniture',
+    shelf: 'furniture',
+};
+/** The surface a node's finish goes on, by its kind and the role or field painted. */
+export function finishSurface(type, role) {
+    const surface = KIND_SURFACES[type];
+    return surface === 'roof' && role && /^wall(MaterialPreset)?$/.test(role) ? 'wall' : surface;
+}
+const wordsOf = (asked) => asked
+    .toLowerCase()
+    .replace(/^library:/, '')
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+const named = (entry) => `library:${entry.id} (${entry.label})`;
+const suits = (entry, surface) => entry.surfaces?.includes(surface) ?? false;
+/**
+ * Library ids nearest a name asked for: those that suit the surface first (a roof's roofing, a
+ * wall's wall materials, as the library tags them), then by the words they share with it.
+ */
+export function nearestLibraryMaterials(asked, surface, count = 3) {
+    const words = wordsOf(asked);
+    const score = (text) => words.filter((word) => text.includes(word)).length;
+    return MATERIAL_CATALOG.map((entry) => ({
+        entry,
+        fit: surface && suits(entry, surface) ? 1 : 0,
+        score: score(`${entry.id} ${entry.label}`.toLowerCase()),
+    }))
+        .sort((a, b) => b.fit - a.fit || b.score - a.score || a.entry.id.localeCompare(b.entry.id))
+        .slice(0, count)
+        .map(({ entry }) => named(entry));
+}
+/**
+ * A material ref that renders: a library id the catalog holds (`library:<id>`, or the bare id), or
+ * a scene material (`scene:<id>`, checked against the scene's materials when the host lends them).
+ * Anything else would fall back to a default with no word (an unknown preset came out grey), so it
+ * is refused, naming the nearest library ids for the surface; when the library has nothing of the
+ * kind like it, the refusal says so, and that a colour is the nearest (a corrugated roof was once
+ * offered bricks).
+ */
+export function requireMaterialRef(asked, field, surface, { paint = false, materials, } = {}) {
+    const parsed = parseMaterialRef(asked.includes(':') ? asked : `library:${asked}`);
+    if (parsed?.kind === 'scene') {
+        if (materials && !Object.hasOwn(materials, parsed.id))
+            refuse('unknown_material', `${asked} is not one of this scene's materials.`, {
+                material: asked,
+                ...(field ? { field } : {}),
+            });
+        return asked;
+    }
+    // A community material (`library:mtl_…`): the host checks it against its catalog.
+    if (parsed?.kind === 'library' && parsed.id.startsWith('mtl_'))
+        return asked;
+    if (parsed?.kind === 'library' && getCatalogMaterialById(parsed.id))
+        return `library:${parsed.id}`;
+    const words = wordsOf(asked);
+    const shares = (text) => words.some((word) => text.toLowerCase().includes(word));
+    const kind = surface ? MATERIAL_CATALOG.filter((entry) => suits(entry, surface)) : [];
+    const alike = kind.filter((entry) => shares(`${entry.id} ${entry.label}`));
+    const nearest = nearestLibraryMaterials(asked, surface);
+    // Only names sharing a word: with none, the ranking is alphabetical and names bricks for a roof.
+    const byName = nearestLibraryMaterials(asked).filter(shares);
+    const head = `${field ? `${field}: ` : ''}${asked} is not in the material library`;
+    const colour = paint
+        ? 'a colour with paint'
+        : 'a flat colour, library:preset-<colour> (library:preset-midgrey, library:preset-tan)';
+    const message = surface && !alike.length
+        ? `${head}, which has no ${SURFACE_WORDS[surface]} like it. Its ${SURFACE_WORDS[surface]}: ${kind.length ? kind.slice(0, 5).map(named).join(', ') : 'none'}.${byName.length ? ` Nearest by name: ${byName.join(', ')}.` : ''} Or ${colour} is the nearest.`
+        : `${head}. Nearest: ${nearest.join(', ')}; or give ${colour}.`;
+    return refuse('unknown_material', `${message} search_materials finds one by words.`, {
+        material: asked,
+        ...(field ? { field } : {}),
+        nearest,
+    });
+}

package/dist/agent-operations/node-patch.d.ts

@@ -0,0 +1,3 @@
+import type { AnyNode } from '../schema/index.js';
+export declare function honestNodePatch(current: AnyNode, data: Readonly<Record<string, unknown>>): Record<string, unknown>;
+//# sourceMappingURL=node-patch.d.ts.map

package/dist/agent-operations/node-patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-patch.d.ts","sourceRoot":"","sources":["../../src/agent-operations/node-patch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AA8ExC,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwDzB"}

package/dist/agent-operations/node-patch.js

@@ -0,0 +1,114 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { parseMaterialColor } from '../material-library.js';
+import { parseNode } from '../schema/compiled-node-parsers.js';
+import { finishSurface, requireMaterialRef } from './material-refs.js';
+/**
+ * An agent's edit of a node checked so it does what it says, the same on the MCP's apply_patch
+ * and the chat's update_node. A pier once took five attempts: `material: {color}`
+ * reported "applied" and stored `{}` (the schema drops unknown keys), `materialPreset: null` was
+ * refused (no way to clear), an unknown preset rendered grey, and a `material` under a set preset
+ * never showed. Returns the data to write: `null` (or an empty material ref) as `undefined`, which
+ * the store reads as "remove the field". Free-form records (metadata, slots) keep every key, so they
+ * pass as sent.
+ */
+/** The pairs where the first, set, hides the second: the renderer reads a preset before a material. */
+const HIDES = [
+    ['materialPreset', 'material'],
+    ['topMaterialPreset', 'topMaterial'],
+    ['edgeMaterialPreset', 'edgeMaterial'],
+    ['wallMaterialPreset', 'wallMaterial'],
+];
+const isPreset = (key) => key === 'materialPreset' || key.endsWith('MaterialPreset');
+const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** The paths of `sent` the parsed node does not keep as sent: dropped, or changed (a value coerced). */
+function lostPaths(sent, kept, path) {
+    if (isRecord(sent)) {
+        if (!isRecord(kept))
+            return [path];
+        return Object.entries(sent).flatMap(([key, value]) => value === undefined
+            ? []
+            : key in kept
+                ? lostPaths(value, kept[key], `${path}.${key}`)
+                : [`${path}.${key}`]);
+    }
+    if (Array.isArray(sent))
+        return Array.isArray(kept) && kept.length === sent.length
+            ? sent.flatMap((value, i) => lostPaths(value, kept[i], `${path}[${i}]`))
+            : [path];
+    return typeof sent === 'string' && sent !== kept
+        ? [`${path} (stored as ${JSON.stringify(kept)})`]
+        : [];
+}
+/** Material refs the patch writes: a preset field, a slot, a region's or a room's finish. */
+function materialRefs(data) {
+    const refs = [];
+    for (const [key, value] of Object.entries(data)) {
+        if (isPreset(key) && typeof value === 'string')
+            refs.push([key, value]);
+        if (key === 'slots' && isRecord(value))
+            for (const [slot, ref] of Object.entries(value))
+                if (typeof ref === 'string')
+                    refs.push([`slots.${slot}`, ref]);
+        if (key === 'faceRegions' && Array.isArray(value))
+            value.forEach((region, i) => {
+                if (isRecord(region) && typeof region.finish === 'string')
+                    refs.push([`faceRegions[${i}].finish`, region.finish]);
+            });
+    }
+    return refs;
+}
+/** The node's current value at a field materialRefs names (a preset, `slots.<id>`, a region). */
+function valueAt(node, field) {
+    const record = node;
+    const slot = /^slots\.(.+)$/.exec(field);
+    if (slot)
+        return isRecord(record.slots) ? record.slots[slot[1]] : undefined;
+    const region = /^faceRegions\[(\d+)\]\.finish$/.exec(field);
+    if (region) {
+        const regions = record.faceRegions;
+        const entry = Array.isArray(regions) ? regions[Number(region[1])] : undefined;
+        return isRecord(entry) ? entry.finish : undefined;
+    }
+    return record[field];
+}
+export function honestNodePatch(current, data) {
+    const sent = {};
+    for (const [key, value] of Object.entries(data))
+        sent[key] = value === null || (isPreset(key) && value === '') ? undefined : value;
+    const merged = { ...current, ...sent };
+    for (const [key, value] of Object.entries(sent))
+        if (value === undefined)
+            delete merged[key];
+    const parsed = parseNode(merged);
+    if (!parsed.success) {
+        const required = parsed.error.issues
+            .map((issue) => String(issue.path[0] ?? ''))
+            .find((key) => key in sent && sent[key] === undefined);
+        if (required)
+            refuse('field_required', `${current.type} ${current.id} needs ${required}: it cannot be cleared.`, {
+                field: required,
+            });
+        // Any other schema failure is the caller's own refusal.
+        return sent;
+    }
+    const lost = Object.entries(sent).flatMap(([key, value]) => value === undefined ? [] : lostPaths(value, parsed.data[key], key));
+    if (lost.length)
+        refuse('unknown_field', `${current.type} ${current.id} would not keep ${lost.join(', ')}: the patch would report it applied and drop it.${lost.some((path) => /(^|\.)color\b/.test(path))
+            ? ' A colour goes in material.properties.color.'
+            : ''}`, { fields: lost });
+    for (const [field, ref] of materialRefs(sent)) {
+        // Restating the node's own value passes, so an older node's bad value never blocks an edit;
+        // a slot also takes a plain colour (as unknownMaterialPresetRefusal reads them).
+        if (valueAt(current, field) === ref)
+            continue;
+        if (field.startsWith('slots.') && parseMaterialColor(ref))
+            continue;
+        requireMaterialRef(ref, field, finishSurface(current.type, field));
+    }
+    for (const [preset, material] of HIDES) {
+        const hider = merged[preset];
+        if (sent[material] !== undefined && typeof hider === 'string' && hider)
+            refuse('shadowed_field', `${material} would not show: ${preset} (${hider}) is read first. Clear it in the same patch (${preset}: null).`, { field: material, hiddenBy: preset });
+    }
+    return sent;
+}

package/dist/agent-operations/paint.d.ts

@@ -0,0 +1,21 @@
+import { type MaterialSchema } from '../schema/index.js';
+import type { AgentOperation } from './types.js';
+/**
+ * `paint`: a finish in one call, as the editor's Paint gives it. Through patches an agent once took
+ * five tries to paint a pier grey: `material: {color}` was stored as `{}`, `materialPreset: null`
+ * was refused and an unknown preset fell back to grey. A colour is the nearest of the library's
+ * flat colours, said with how near; a native material is kept as a scene material. Slots are
+ * written as the editor's slot paint writes them, a wall's faces through its paint plan, a roof's
+ * role through its role field.
+ */
+type PaintInput = {
+    targets: string[];
+    role?: string;
+    color?: string;
+    material?: string | MaterialSchema;
+    materialName?: string;
+    erase?: true;
+};
+export declare const paint: AgentOperation<PaintInput>;
+export {};
+//# sourceMappingURL=paint.d.ts.map

package/dist/agent-operations/paint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paint.d.ts","sourceRoot":"","sources":["../../src/agent-operations/paint.ts"],"names":[],"mappings":"AAaA,OAAO,EAKL,KAAK,cAAc,EAKpB,MAAM,WAAW,CAAA;AAMlB,OAAO,KAAK,EAAgB,cAAc,EAAc,MAAM,SAAS,CAAA;AAEvE;;;;;;;GAOG;AAEH,KAAK,UAAU,GAAG;IAChB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,CAAA;IAClC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,IAAI,CAAA;CACb,CAAA;AA6HD,eAAO,MAAM,KAAK,EAAE,cAAc,CAAC,UAAU,CAuI5C,CAAA"}

package/dist/agent-operations/paint.js

@@ -0,0 +1,219 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { ceilingSlots, columnSlots, doorSlots, fenceSlots, slabSlots, wallSlots, windowSlots, } from '../node-slots/index.js';
+import { nearestLibraryColorRef } from '../procedural-items/library-colors.js';
+import { getEffectiveSegmentSurfaceMaterial, } from '../schema/index.js';
+import { buildWallFinishLayout, getWallLevelZones } from '../systems/wall/wall-finish.js';
+import { planWallPaint } from '../systems/wall/wall-paint-plan.js';
+import { roomSideFaces } from '../systems/wall/wall-room-sides.js';
+import { finishSurface, requireMaterialRef } from './material-refs.js';
+import { resolveInlinePaintMaterial } from './scene-materials.js';
+const ROOF_ROLES = ['top', 'edge', 'wall'];
+/** The surfaces painted when no role is named: what "paint the column" means. */
+const DEFAULT_ROLES = {
+    wall: ['a', 'b', 'curtain-frame', 'curtain-solid'],
+    column: ['shaft'],
+    slab: ['surface'],
+    ceiling: ['surface'],
+    fence: ['posts', 'infill', 'base', 'rail'],
+    door: ['panel', 'frame'],
+    window: ['frame'],
+};
+function slotsOf(node) {
+    switch (node.type) {
+        case 'wall':
+            return wallSlots(node);
+        case 'column':
+            return columnSlots(node);
+        case 'slab':
+            return slabSlots();
+        case 'ceiling':
+            return ceilingSlots();
+        case 'fence':
+            return fenceSlots(node);
+        case 'door':
+            return doorSlots();
+        case 'window':
+            return windowSlots();
+        default:
+            return null;
+    }
+}
+/** The finish asked for, as the ref it writes; refused when it is unknown. */
+function finishOf(input, surface, context) {
+    const given = [input.color, input.material, input.erase].filter((value) => value !== undefined);
+    if (given.length !== 1)
+        refuse('finish_required', 'Give one finish: color (#rrggbb), material (a library or scene ref, or a native material), or erase: true.');
+    if (input.materialName !== undefined && typeof input.material !== 'object')
+        refuse('invalid_material_name', 'materialName names a native material only.');
+    if (input.erase)
+        return { ref: undefined };
+    if (input.color) {
+        const match = nearestLibraryColorRef(input.color);
+        if (!match)
+            refuse('invalid_color', `${input.color} is no colour: give #rrggbb.`);
+        return {
+            ref: match.ref,
+            note: `${input.color}: nearest library colour ${match.name} (${match.color}), ΔE ${Math.round(match.distance)}.`,
+        };
+    }
+    if (typeof input.material === 'object')
+        return resolveInlinePaintMaterial(context.materials, input.material, input.materialName);
+    const ref = requireMaterialRef(input.material, undefined, surface, {
+        paint: true,
+        materials: context.materials,
+    });
+    const sceneMaterial = context.materials
+        ? Object.values(context.materials).find((entry) => `scene:${entry.id}` === ref)
+        : undefined;
+    return { ref, ...(sceneMaterial ? { sceneMaterial } : {}) };
+}
+/** A node's data for an update: what changed, and `undefined` for the fields it lost. */
+function changedData(before, after) {
+    const data = {};
+    for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+        const [a, b] = [
+            before[key],
+            after[key],
+        ];
+        if (JSON.stringify(a) !== JSON.stringify(b))
+            data[key] = b;
+    }
+    return data;
+}
+/** A roof's or a segment's role written, its inline material for that role gone with it. */
+function paintRoofRole(node, role, ref) {
+    const next = { ...node };
+    delete next[`${role}Material`];
+    if (ref)
+        next[`${role}MaterialPreset`] = ref;
+    else
+        delete next[`${role}MaterialPreset`];
+    return next;
+}
+/**
+ * A wall face painted whole, as the editor's Paint paints each part of it: the face's own finish,
+ * and the finish of each room it is turned to, which shows over the face's own. Painted parts
+ * (regions) stay on top, as they do under a room's paint.
+ */
+function paintWallFace(nodes, wall, face, ref) {
+    const plan = planWallPaint(nodes, wall, { kind: 'slot', slotId: face }, ref);
+    const rooms = buildWallFinishLayout(wall, getWallLevelZones(wall, nodes)).spans[face];
+    for (const zoneId of new Set(rooms.map((span) => span.zoneId))) {
+        const scene = { ...nodes, ...plan };
+        Object.assign(plan, planWallPaint(scene, scene[wall.id], { kind: 'room-face', zoneId, face }, ref));
+    }
+    return plan;
+}
+export const paint = (nodes, input, context) => {
+    // A refused material's nearest are the first target's kind: a roof is offered roofing.
+    const first = input.targets[0] ? nodes[input.targets[0]] : undefined;
+    const finish = finishOf(input, first && finishSurface(first.type, input.role), context);
+    const { ref } = finish;
+    const written = {};
+    const current = (id) => (written[id] ?? nodes[id]);
+    const scene = () => ({ ...nodes, ...written });
+    const painted = [];
+    const keptParts = [];
+    for (const id of input.targets) {
+        const node = current(id);
+        if (!node)
+            refuse('target_not_found', `Nothing to paint: ${id} is not in the scene (a room edit may have replaced its walls: read the scene again). Nothing was painted.`, { target: id });
+        if (node.type === 'roof' || node.type === 'roof-segment') {
+            const role = (input.role ?? 'top');
+            if (!ROOF_ROLES.includes(role))
+                refuse('unknown_role', `A roof's roles are ${ROOF_ROLES.join(', ')}.`, {
+                    target: id,
+                    roles: [...ROOF_ROLES],
+                });
+            if (node.type === 'roof') {
+                // A segment's own finish for the role, or its catch-all, shows over its roof's.
+                const shadowing = node.children.filter((childId) => {
+                    const segment = current(childId);
+                    if (segment?.type !== 'roof-segment')
+                        return false;
+                    const own = getEffectiveSegmentSurfaceMaterial(segment, role);
+                    return own.material !== undefined || own.materialPreset !== undefined;
+                });
+                if (shadowing.length)
+                    refuse('shadowed_field', `The roof's ${role} would not show: segments ${shadowing.join(', ')} have their own. Paint the segments instead.`, { target: id, segments: shadowing });
+            }
+            written[id] = paintRoofRole(node, role, ref);
+            painted.push({ id, roles: [role] });
+            continue;
+        }
+        const slots = slotsOf(node);
+        if (!slots)
+            refuse('not_paintable', `A ${node.type} has no finish paint gives: paint walls, columns, slabs, ceilings, fences, doors, windows or roofs.`, { target: id, type: node.type });
+        const ids = slots.map((slot) => slot.slotId);
+        let roles;
+        if (input.role === 'exterior' || input.role === 'interior') {
+            // A curtain wall has frame, glass and panels where a wall has faces.
+            if (node.type !== 'wall' || !ids.includes('a'))
+                refuse('unknown_role', `A ${node.type === 'wall' ? 'curtain wall' : node.type} has no ${input.role} face: its roles are ${ids.join(', ')}.`, { target: id, roles: ids });
+            const sides = roomSideFaces(scene(), id);
+            const face = input.role === 'interior' ? sides.inside : sides.outside;
+            if (!face)
+                refuse('side_unknown', `Wall ${id} has rooms on both sides or none: name its face, a or b.`, { target: id });
+            roles = [face];
+        }
+        else if (input.role) {
+            if (!ids.includes(input.role))
+                refuse('unknown_role', `A ${node.type}'s roles are ${ids.join(', ')}.`, {
+                    target: id,
+                    roles: ids,
+                });
+            roles = [input.role];
+        }
+        else
+            roles = (DEFAULT_ROLES[node.type] ?? []).filter((role) => ids.includes(role));
+        if (!roles.length)
+            refuse('unknown_role', `Name the ${node.type}'s surface: its roles are ${ids.join(', ')}.`, {
+                target: id,
+                roles: ids,
+            });
+        for (const role of roles) {
+            const target = current(id);
+            if (target.type === 'wall') {
+                const face = role === 'a' || role === 'b' ? role : null;
+                Object.assign(written, face
+                    ? paintWallFace(scene(), target, face, ref)
+                    : planWallPaint(scene(), target, { kind: 'slot', slotId: role }, ref));
+                const parts = face && ref ? target.faceRegions?.filter((region) => region.face === face) : [];
+                if (parts?.length)
+                    keptParts.push(`${id} ${face}: ${parts.map((region) => region.id).join(', ')}`);
+                continue;
+            }
+            const next = { ...(target.slots ?? {}) };
+            if (ref)
+                next[role] = ref;
+            else
+                delete next[role];
+            written[id] = { ...target, slots: next };
+        }
+        painted.push({ id, roles });
+    }
+    const update = Object.entries(written).flatMap(([id, node]) => {
+        const data = changedData(nodes[id], node);
+        return Object.keys(data).length ? [{ id, data }] : [];
+    });
+    const createdMaterial = finish.created ? finish.sceneMaterial : undefined;
+    const note = [
+        finish.note,
+        keptParts.length && `Painted parts keep their own finish (${keptParts.join('; ')}).`,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return {
+        result: {
+            ok: true,
+            painted,
+            finish: ref ?? 'default',
+            ...(finish.sceneMaterial
+                ? { materialId: finish.sceneMaterial.id, material: finish.sceneMaterial.material }
+                : {}),
+            ...(createdMaterial ? { createdMaterial } : {}),
+            ...(note ? { note } : {}),
+        },
+        changes: { update, ...(createdMaterial ? { materials: [createdMaterial] } : {}) },
+    };
+};

package/dist/agent-operations/place-items.d.ts

@@ -0,0 +1,20 @@
+import { type LevelTargetInput } from './level-target.js';
+import type { AgentOperation } from './types.js';
+type Entry = {
+    assetId: string;
+    x: number;
+    z: number;
+    y?: number;
+    rotation?: number;
+    targetNodeId?: string;
+};
+type PlaceItemsInput = LevelTargetInput & {
+    items: Entry[];
+};
+/**
+ * `place_items`: catalog items on a level's floor, or on the host each names (a wall, a ceiling,
+ * an item standing on the floor), each placed or refused on its own.
+ */
+export declare const placeItems: AgentOperation<PlaceItemsInput>;
+export {};
+//# sourceMappingURL=place-items.d.ts.map

package/dist/agent-operations/place-items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place-items.d.ts","sourceRoot":"","sources":["../../src/agent-operations/place-items.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,gBAAgB,CAAA;AAOnE,OAAO,KAAK,EAAE,cAAc,EAA4B,MAAM,SAAS,CAAA;AAEvE,KAAK,KAAK,GAAG;IACX,OAAO,EAAE,MAAM,CAAA;IACf,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AACD,KAAK,eAAe,GAAG,gBAAgB,GAAG;IAAE,KAAK,EAAE,KAAK,EAAE,CAAA;CAAE,CAAA;AA6K5D;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,eAAe,CAuHtD,CAAA"}