@pascal-app/mcp 1.0.1 → 1.0.4

package/dist/bridge/scene-bridge.js

@@ -1,6 +1,7 @@
 // Side-effect import MUST come first: installs RAF polyfill before core loads.
 import './node-shims.js';
-import { AnyNode as AnyNodeSchema, parseNode, } from '@pascal-app/core/schema';
+import { adjacentLevelId, applyStructureReconciliation, assertDerivedNodeWrites, changedStairOpeningOwners, floorOpeningTargets, HIDDEN_SITE_NOTE, pauseSceneHistory, pauseSpaceDetection, planNodeDeletion, planOwnedFloorOpenings, planWallDeletion, resumeSceneHistory, resumeSpaceDetection, runAsSingleSceneHistoryStep, stairDeckLevelId, structureChangeBatch, } from '@pascal-app/core';
+import { AnyNode as AnyNodeSchema, generateId, parseNode, SceneMaterial, } from '@pascal-app/core/schema';
 // Per PLAN §0.6: `useScene` is the DEFAULT export from `@pascal-app/core/store`.
 import useScene from '@pascal-app/core/store';
 /**
@@ -11,6 +12,8 @@ import useScene from '@pascal-app/core/store';
  * `flushDirty()` for observability.
  */
 export class SceneBridge {
+    /** `applyPatch` takes `upsert_material` patches, in the patch's one history step. */
+    supportsMaterialUpserts = true;
     activeScene = null;
     /**
      * Scene identity currently bound to this bridge. MCP tools use this to know
@@ -24,6 +27,7 @@ export class SceneBridge {
             ownerId: meta.ownerId,
             thumbnailUrl: meta.thumbnailUrl,
             version: meta.version,
+            ...(meta.graphHash === undefined ? {} : { graphHash: meta.graphHash }),
         };
     }
     getActiveScene() {
@@ -118,6 +122,17 @@ export class SceneBridge {
     getNodes() {
         return useScene.getState().nodes;
     }
+    getCollections() {
+        return useScene.getState().collections;
+    }
+    getMaterials() {
+        return useScene.getState().materials;
+    }
+    setCollections(collections) {
+        if (useScene.getState().readOnly)
+            return;
+        useScene.setState({ collections });
+    }
     /** Root node IDs. */
     getRootNodeIds() {
         return useScene.getState().rootNodeIds;
@@ -236,7 +251,12 @@ export class SceneBridge {
      * Returns the generated id.
      */
     createNode(node, parentId) {
-        useScene.getState().createNode(node, parentId);
+        const before = useScene.getState().nodes;
+        assertDerivedNodeWrites(before, { create: [{ node: parentId ? { ...node, parentId } : node }] });
+        runAsSingleSceneHistoryStep(useScene, () => {
+            useScene.getState().createNode(node, parentId);
+            this.reconcileDependentStructure(before);
+        });
         return node.id;
     }
     /** Update node fields (shallow merge through the core store). */
@@ -244,7 +264,12 @@ export class SceneBridge {
         if (!useScene.getState().nodes[id]) {
             throw new Error(`node not found: ${id}`);
         }
-        useScene.getState().updateNode(id, data);
+        const before = useScene.getState().nodes;
+        assertDerivedNodeWrites(before, { update: [{ id, data }] });
+        runAsSingleSceneHistoryStep(useScene, () => {
+            useScene.getState().updateNode(id, data);
+            this.reconcileDependentStructure(before);
+        });
     }
     /**
      * Delete a node. If the node has children and `cascade === false`, throws.
@@ -264,7 +289,18 @@ export class SceneBridge {
             throw new Error(`node has ${descendants.length - 1} descendant(s); pass cascade: true to delete recursively`);
         }
         const before = new Set(Object.keys(state.nodes));
-        useScene.getState().deleteNode(id);
+        const wallLevels = [
+            ...new Set(descendants.flatMap((nodeId) => {
+                const deleted = state.nodes[nodeId];
+                return deleted?.type === 'wall' && deleted.parentId ? [deleted.parentId] : [];
+            })),
+        ];
+        runAsSingleSceneHistoryStep(useScene, () => {
+            useScene.getState().deleteNode(id);
+            if (wallLevels.length)
+                this.deriveStructure(wallLevels);
+            this.reconcileDependentStructure(state.nodes);
+        });
         const afterNodes = useScene.getState().nodes;
         const removed = [];
         for (const prevId of before) {
@@ -275,8 +311,8 @@ export class SceneBridge {
     }
     /**
      * Atomic multi-op patch. Validates EVERY patch first (dry run); only if all
-     * pass does it apply in a single batch via `createNodes` / `updateNodes` /
-     * `deleteNodes`. Throws on any validation failure without mutating state.
+     * pass does it apply through the store actions in one history step. Throws on
+     * validation failure without mutating state.
      */
     applyPatch(patches) {
         const state = useScene.getState();
@@ -289,11 +325,18 @@ export class SceneBridge {
         // Zod-normalised copy (which has a generated id if the caller omitted one)
         // instead of the unparsed input.
         const parsedCreateNodes = new Map();
+        const materialUpserts = new Map();
         for (let i = 0; i < patches.length; i++) {
             const p = patches[i];
             if (!p)
                 throw new Error(`invalid patch: patches[${i}] is undefined`);
-            if (p.op === 'create') {
+            if (p.op === 'upsert_material') {
+                const parsed = SceneMaterial.safeParse(p.material);
+                if (!parsed.success)
+                    throw new Error(`invalid patch: patches[${i}] material failed schema: ${parsed.error.message}`);
+                materialUpserts.set(parsed.data.id, parsed.data);
+            }
+            else if (p.op === 'create') {
                 const res = parseNode(p.node);
                 if (!res.success) {
                     throw new Error(`invalid patch: patches[${i}] create node failed schema: ${res.error.message}`);
@@ -301,7 +344,7 @@ export class SceneBridge {
                 if (p.parentId !== undefined && !simAvailable.has(p.parentId)) {
                     throw new Error(`invalid patch: patches[${i}] create parentId "${p.parentId}" not found`);
                 }
-                parsedCreateNodes.set(i, res.data);
+                parsedCreateNodes.set(i, p.parentId ? { ...res.data, parentId: p.parentId } : res.data);
                 simAvailable.add(res.data.id);
             }
             else if (p.op === 'update') {
@@ -333,47 +376,75 @@ export class SceneBridge {
                 throw new Error(`invalid patch: patches[${i}] unknown op`);
             }
         }
-        // Dry-run succeeded — apply in order, batching adjacent ops of the same
-        // op type so Zundo groups them tightly.
-        const createOps = [];
-        const updateOps = [];
-        const deleteIds = [];
-        const createdIds = [];
-        // Simple approach: queue by type, flush in original order by walking
-        // patches and interleaving flushes when the op type changes, so ids
-        // created/updated/deleted stay temporally consistent.
-        const flush = (kind) => {
-            if (kind !== 'create' && createOps.length > 0) {
-                useScene.getState().createNodes(createOps);
-                createOps.length = 0;
-            }
-            if (kind !== 'update' && updateOps.length > 0) {
-                useScene.getState().updateNodes(updateOps);
-                updateOps.length = 0;
+        // Derived construction is refused BEFORE anything is applied, so a patch
+        // that tries to author a floor plate or an auto ceiling leaves the scene
+        // untouched like any other invalid patch.
+        assertDerivedNodeWrites(nodes, {
+            create: [...parsedCreateNodes.values()].map((node) => ({ node })),
+            update: patches.flatMap((patch) => patch.op === 'update' ? [{ id: patch.id, data: patch.data }] : []),
+        });
+        const createOps = new Map();
+        const updateOps = new Map();
+        const deleteIds = new Set();
+        const nextNodes = { ...nodes };
+        for (const [index, patch] of patches.entries()) {
+            if (patch.op === 'create') {
+                const parsed = parsedCreateNodes.get(index);
+                const node = { ...parsed, parentId: patch.parentId ?? parsed.parentId };
+                createOps.set(node.id, { node, parentId: patch.parentId });
+                deleteIds.delete(node.id);
+                nextNodes[node.id] = node;
             }
-            if (kind !== 'delete' && deleteIds.length > 0) {
-                useScene.getState().deleteNodes(deleteIds);
-                deleteIds.length = 0;
+            else if (patch.op === 'update') {
+                nextNodes[patch.id] = { ...nextNodes[patch.id], ...patch.data };
+                const created = createOps.get(patch.id);
+                if (created) {
+                    created.node = nextNodes[patch.id];
+                    if (patch.data.parentId !== undefined)
+                        created.parentId = patch.data.parentId;
+                }
+                else
+                    updateOps.set(patch.id, { ...updateOps.get(patch.id), ...patch.data });
             }
-        };
-        for (let i = 0; i < patches.length; i++) {
-            const p = patches[i];
-            if (p.op === 'create') {
-                flush('create');
-                const parsedNode = parsedCreateNodes.get(i);
-                createOps.push({ node: parsedNode, parentId: p.parentId });
-                createdIds.push(parsedNode.id);
+            else if (patch.op === 'delete') {
+                deleteIds.add(patch.id);
+                createOps.delete(patch.id);
+                updateOps.delete(patch.id);
+                delete nextNodes[patch.id];
             }
-            else if (p.op === 'update') {
-                flush('update');
-                updateOps.push({ id: p.id, data: p.data });
+        }
+        // Plan the entire deletion selection before applying anything. Interleaved
+        // update operations must not turn an all-boundaries deletion into balconies.
+        const planned = structureChangeBatch(planWallDeletion(nodes, {
+            nodeIds: [...deleteIds],
+            nextNodes,
+            mintId: generateId,
+        }).changes);
+        for (const { id, data } of planned.update)
+            updateOps.set(id, { ...updateOps.get(id), ...data });
+        const wallLevels = [
+            ...new Set(planned.delete.flatMap((id) => {
+                const node = nodes[id];
+                return node?.type === 'wall' && node.parentId ? [node.parentId] : [];
+            })),
+        ];
+        runAsSingleSceneHistoryStep(useScene, () => {
+            pauseSpaceDetection();
+            try {
+                for (const material of materialUpserts.values())
+                    useScene.getState().addSceneMaterial(material);
+                useScene.getState().createNodes([...createOps.values(), ...planned.create]);
+                useScene.getState().updateNodes([...updateOps].map(([id, data]) => ({ id, data })));
+                useScene.getState().deleteNodes(planned.delete);
             }
-            else {
-                flush('delete');
-                deleteIds.push(p.id);
+            finally {
+                resumeSpaceDetection();
             }
-        }
-        flush('none');
+            if (wallLevels.length)
+                this.deriveStructure(wallLevels);
+            this.reconcileDependentStructure(nodes);
+        });
+        const createdIds = Object.keys(useScene.getState().nodes).filter((id) => !nodes[id]);
         // Compute actual deleted ids by diffing pre/post snapshots.
         const postNodes = useScene.getState().nodes;
         const deletedIds = [];
@@ -387,6 +458,40 @@ export class SceneBridge {
             createdIds,
         };
     }
+    /**
+     * Preview what deleting `ids` does to `scene` with this bridge's semantics
+     * (core's store planner), without committing or minting default gutters.
+     * The apply_patch guard runs its dry run through this.
+     */
+    planDeletion(scene, ids) {
+        return planNodeDeletion(scene, ids, { mintDefaults: false });
+    }
+    /**
+     * Derive this scene's construction the way the browser's commit subscriber
+     * does: one pass of the shared kernel writes the room zones, the auto
+     * ceilings, the wall side classification and the floor plates.
+     *
+     * The headless bridge has no space-detection subscriber, so the semantic
+     * tools that state room intent call this to materialise the construction
+     * they report. Writes are history-paused, so undo returns to the state
+     * before the triggering tool call rather than stranding derived nodes.
+     */
+    deriveStructure(levelIds) {
+        pauseSceneHistory(useScene);
+        try {
+            const patches = applyStructureReconciliation(useScene, {
+                levelIds,
+                mintId: (kind) => generateId(kind),
+            });
+            return {
+                createdIds: patches.flatMap((patch) => patch.op === 'create' ? [patch.node.id] : []),
+                deletedIds: patches.flatMap((patch) => (patch.op === 'delete' ? [patch.id] : [])),
+            };
+        }
+        finally {
+            resumeSceneHistory(useScene);
+        }
+    }
     /** Undo. Returns the number of steps actually undone. */
     undo(steps = 1) {
         const before = useScene.temporal.getState().pastStates.length;
@@ -407,8 +512,12 @@ export class SceneBridge {
      */
     validateScene() {
         const errors = [];
+        const warnings = [];
         const nodes = useScene.getState().nodes;
         for (const [id, node] of Object.entries(nodes)) {
+            if (node.type === 'site' && node.visible === false) {
+                warnings.push({ nodeId: id, path: 'visible', message: HIDDEN_SITE_NOTE });
+            }
             const res = AnyNodeSchema.safeParse(node);
             if (res.success)
                 continue;
@@ -420,7 +529,7 @@ export class SceneBridge {
                 });
             }
         }
-        return { valid: errors.length === 0, errors };
+        return { valid: errors.length === 0, errors, warnings };
     }
     /**
      * Drain the dirtyNodes set. Returns the ids that were present. No-op for
@@ -446,6 +555,82 @@ export class SceneBridge {
     clearHistory() {
         useScene.temporal.getState().clear();
     }
+    runAsSingleHistoryStep(run) {
+        return runAsSingleSceneHistoryStep(useScene, run);
+    }
+    reconcileDependentStructure(before) {
+        const currentNodes = this.getNodes();
+        const authoredInputChanged = [
+            ...new Set([...Object.keys(before), ...Object.keys(currentNodes)]),
+        ].some((id) => {
+            if (before[id] === currentNodes[id])
+                return false;
+            const type = (currentNodes[id] ?? before[id])?.type;
+            return (type === 'stair' ||
+                type === 'stair-segment' ||
+                type === 'elevator' ||
+                type === 'level' ||
+                type === 'building' ||
+                type === 'slab' ||
+                type === 'ceiling');
+        });
+        if (authoredInputChanged) {
+            const ownerIds = changedStairOpeningOwners(before, currentNodes);
+            for (const node of [...Object.values(before), ...Object.values(currentNodes)]) {
+                if (node.type === 'elevator' &&
+                    (before[node.id] !== currentNodes[node.id] ||
+                        Object.values(currentNodes).some((level) => level.type === 'level' && before[level.id] !== level)))
+                    ownerIds.add(node.id);
+            }
+            const owned = planOwnedFloorOpenings(currentNodes, { ownerIds });
+            if (owned.length) {
+                pauseSpaceDetection();
+                try {
+                    useScene.getState().applyNodeChanges(structureChangeBatch(owned));
+                }
+                finally {
+                    resumeSpaceDetection();
+                }
+            }
+        }
+        const current = this.getNodes();
+        const levels = new Set();
+        for (const id of new Set([...Object.keys(before), ...Object.keys(current)])) {
+            if (before[id] === current[id])
+                continue;
+            for (const nodes of [before, current]) {
+                const level = stairDeckLevelId(nodes, nodes[id]);
+                if (level)
+                    levels.add(level);
+                const node = nodes[id];
+                if (node?.type === 'level') {
+                    levels.add(node.id);
+                    const lower = adjacentLevelId(nodes, node.id, -1);
+                    if (lower)
+                        levels.add(lower);
+                }
+                if (node?.type === 'stair')
+                    for (const opening of Object.values(nodes))
+                        if (opening.type === 'floor-opening' && opening.ownerId === node.id)
+                            for (const target of floorOpeningTargets(nodes, opening))
+                                levels.add(target.levelId);
+                if (node?.type === 'floor-opening')
+                    for (const target of floorOpeningTargets(nodes, node))
+                        levels.add(target.levelId);
+                if (node?.type === 'door' || node?.type === 'window') {
+                    const wall = nodes[node.parentId];
+                    if (wall?.type === 'wall' && wall.parentId)
+                        levels.add(wall.parentId);
+                }
+                else if ((node?.type === 'zone' || node?.type === 'slab' || node?.type === 'wall') &&
+                    node.parentId) {
+                    levels.add(node.parentId);
+                }
+            }
+        }
+        if (levels.size)
+            this.deriveStructure([...levels]);
+    }
     // ---- internal helpers ----
     /**
      * Return the node whose `children` array (string or object form) contains

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { SceneBridge } from './bridge/scene-bridge.js';
 export { createSceneOperations, type SceneOperations } from './operations/index.js';
 export { type CreatePascalMcpServerOptions, createPascalMcpServer } from './server.js';
+export type { GeometryScriptHost, ScriptedKind } from './tools/add-object.js';
+export { type AssetCatalog, builtInCatalog } from './tools/asset-catalog.js';
+export type { SceneViewCapture, SceneViewHost } from './tools/view-scene.js';
 export { version } from './version.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AAC1E,OAAO,EAAE,KAAK,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AACnF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AAC1E,OAAO,EAAE,KAAK,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AACnF,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAC1E,OAAO,EAAE,KAAK,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACzE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACzE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export { SceneBridge } from './bridge/scene-bridge.js';
 export { createSceneOperations } from './operations/index.js';
 export { createPascalMcpServer } from './server.js';
+export { builtInCatalog } from './tools/asset-catalog.js';
 export { version } from './version.js';

package/dist/operations/scene-operations.d.ts

@@ -1,7 +1,8 @@
+import type { NodeDeletionPlan, NodeDeletionScene } from '@pascal-app/core';
 import type { SceneGraph } from '@pascal-app/core/clone-scene-graph';
-import type { AnyNode, AnyNodeId, AnyNodeType } from '@pascal-app/core/schema';
+import type { AnyNode, AnyNodeId, AnyNodeType, Collection, CollectionId, SceneMaterial, SceneMaterialId } from '@pascal-app/core/schema';
 import type { ActiveSceneMeta, Patch, SceneBridge, ValidationResult } from '../bridge/scene-bridge.js';
-import type { ProjectCreateOptions, ProjectStatus, SceneEvent, SceneEventAppendOptions, SceneEventListOptions, SceneListOptions, SceneMeta, SceneMutateOptions, SceneSaveOptions, SceneStore, SceneWithGraph } from '../storage/types.js';
+import type { ProjectCreateOptions, ProjectStatus, SceneDeleteResult, SceneEvent, SceneEventAppendOptions, SceneEventListOptions, SceneListOptions, SceneMeta, SceneMutateOptions, SceneSaveOptions, SceneStore, SceneWithGraph } from '../storage/types.js';
 export type CreateSceneOperationsOptions = {
     bridge?: SceneBridge;
     store?: SceneStore;
@@ -15,6 +16,11 @@ export interface SceneOperations {
     readonly canCreateProject: boolean;
     readonly canGetProjectStatus: boolean;
     readonly storeBackend: SceneStore['backend'] | null;
+    /**
+     * Whether `applyPatch` takes `upsert_material` patches with the nodes that use them, in one
+     * history step. A host that does lends `getMaterials`, and paint keeps native materials there.
+     */
+    readonly supportsMaterialUpserts?: boolean;
     setActiveScene(meta: ActiveSceneMeta): void;
     getActiveScene(): ActiveSceneMeta | null;
     clearActiveScene(): void;
@@ -27,6 +33,10 @@ export interface SceneOperations {
     loadJSON(json: string | SceneGraph): void;
     getNode(id: AnyNodeId): AnyNode | null;
     getNodes(): Record<AnyNodeId, AnyNode>;
+    getCollections(): Record<CollectionId, Collection>;
+    getMaterials?(): Readonly<Record<SceneMaterialId, SceneMaterial>>;
+    /** Replace the scene's collections (one undo step, like any edit). */
+    setCollections(collections: Record<CollectionId, Collection>): void;
     getRootNodeIds(): AnyNodeId[];
     getChildren(parentId: AnyNodeId): AnyNode[];
     getAncestry(id: AnyNodeId): AnyNode[];
@@ -44,6 +54,15 @@ export interface SceneOperations {
         deletedIds: AnyNodeId[];
         createdIds: AnyNodeId[];
     };
+    /**
+     * The active bridge's deletion preview, when it has one. Absent for bridges
+     * that cannot preview their own deletes; the apply_patch guard is then stricter.
+     */
+    readonly planDeletion?: (scene: NodeDeletionScene, ids: AnyNodeId[]) => NodeDeletionPlan;
+    deriveStructure(levelIds?: AnyNodeId[]): {
+        createdIds: AnyNodeId[];
+        deletedIds: AnyNodeId[];
+    };
     undo(steps?: number): number;
     redo(steps?: number): number;
     validateScene(): ValidationResult;
@@ -53,12 +72,13 @@ export interface SceneOperations {
         futureCount: number;
     };
     clearHistory(): void;
+    runAsSingleHistoryStep<T>(run: () => T): T;
     createProject(options: ProjectCreateOptions): Promise<ProjectStatus>;
     getProjectStatus(id: string): Promise<ProjectStatus | null>;
     saveScene(options: SceneSaveOptions): Promise<SceneMeta>;
     loadStoredScene(id: string): Promise<SceneWithGraph | null>;
     listScenes(options?: SceneListOptions): Promise<SceneMeta[]>;
-    deleteStoredScene(id: string, options?: SceneMutateOptions): Promise<boolean>;
+    deleteStoredScene(id: string, options?: SceneMutateOptions): Promise<SceneDeleteResult>;
     renameStoredScene(id: string, newName: string, options?: SceneMutateOptions): Promise<SceneMeta>;
     appendSceneEvent(options: SceneEventAppendOptions): Promise<SceneEvent | null>;
     listSceneEvents(id: string, options?: SceneEventListOptions): Promise<SceneEvent[]>;

package/dist/operations/scene-operations.d.ts.map

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

package/dist/operations/scene-operations.js

@@ -4,13 +4,21 @@ export function createSceneOperations(options) {
 class SceneOperationsFacade {
     #bridge;
     #store;
+    planDeletion;
     constructor(options) {
         this.#bridge = options.bridge;
         this.#store = options.store;
+        const bridge = options.bridge;
+        if (typeof bridge?.planDeletion === 'function') {
+            this.planDeletion = (scene, ids) => bridge.planDeletion(scene, ids);
+        }
     }
     get hasBridge() {
         return this.#bridge !== undefined;
     }
+    get supportsMaterialUpserts() {
+        return this.#bridge?.supportsMaterialUpserts === true;
+    }
     get hasStore() {
         return this.#store !== undefined;
     }
@@ -61,7 +69,9 @@ class SceneOperationsFacade {
         };
     }
     loadJSON(json) {
-        this.requireBridge().loadJSON(json);
+        const bridge = this.requireBridge();
+        bridge.loadJSON(json);
+        bridge.clearHistory();
     }
     getNode(id) {
         return this.requireBridge().getNode(id);
@@ -69,6 +79,15 @@ class SceneOperationsFacade {
     getNodes() {
         return this.requireBridge().getNodes();
     }
+    getCollections() {
+        return this.requireBridge().getCollections();
+    }
+    getMaterials() {
+        return this.requireBridge().getMaterials();
+    }
+    setCollections(collections) {
+        this.requireBridge().setCollections(collections);
+    }
     getRootNodeIds() {
         return this.requireBridge().getRootNodeIds();
     }
@@ -96,6 +115,14 @@ class SceneOperationsFacade {
     applyPatch(patches) {
         return this.requireBridge().applyPatch(patches);
     }
+    /**
+     * Derive construction from the intent the tools just wrote. The hosted
+     * bridge reconciles inside every mutation and exposes no hook, so the call
+     * is optional: there it is already done by the time a tool builds its result.
+     */
+    deriveStructure(levelIds) {
+        return this.requireBridge().deriveStructure?.(levelIds) ?? { createdIds: [], deletedIds: [] };
+    }
     undo(steps) {
         return this.requireBridge().undo(steps);
     }
@@ -114,6 +141,9 @@ class SceneOperationsFacade {
     clearHistory() {
         this.requireBridge().clearHistory();
     }
+    runAsSingleHistoryStep(run) {
+        return this.requireBridge().runAsSingleHistoryStep(run);
+    }
     async createProject(options) {
         const store = this.requireStore();
         if (!store.createProject) {

package/dist/prompts/from-brief.js

@@ -25,7 +25,7 @@ export function buildFromBriefPrompt(args) {
     if (args.constraints && args.constraints.trim().length > 0) {
         parts.push('', '## Constraints', args.constraints.trim());
     }
-    parts.push('', '## Task', 'Produce tool calls that realise the brief within the stated constraints.', '1. Bind a scene — `create_project` (new), `list_scenes` then `load_scene` (existing), or `create_house_from_brief` (starter template).', '2. Build the design — `create_story_shell` for exterior shells, `create_room`/`add_door`/`add_window`/`create_stair_between_levels`/`furnish_room` for interior layout, `create_roof` for roofing, `apply_patch` for exact bulk graph work.', '3. Finish — call `validate_scene`, `verify_scene`, and `get_project_status`, then return the `editorUrl`.', 'Call `save_scene` with `saveMode: "checkpoint"` only when the design reaches a meaningful milestone.');
+    parts.push('', '## Task', 'Produce tool calls that realise the brief within the stated constraints.', '1. Bind a scene — `create_project` (new), `list_scenes` then `load_scene` (existing), or `create_house_from_brief` (starter template).', '2. Build the design — `create_story_shell` for exterior shells, `create_room`/`add_door`/`add_window`/`create_stair`/`furnish_room` for interior layout, `create_roof` for roofing, `apply_patch` for exact bulk graph work.', '3. Finish — call `validate_scene`, `verify_scene`, and `get_project_status`, then return the `editorUrl`.', 'Call `save_scene` with `saveMode: "checkpoint"` only when the design reaches a meaningful milestone.');
     return parts.join('\n');
 }
 export function registerFromBrief(server, _bridge) {

package/dist/prompts/iterate-on-feedback.js

@@ -7,7 +7,7 @@ const PREAMBLE = [
     '  - Prefer updates over create+delete pairs when a field change will do.',
     '  - Do not re-create nodes that already exist.',
     '  - Do not touch nodes that are unrelated to the feedback.',
-    '  - Prefer semantic tools such as create_room, add_door, add_window, furnish_room, and place_item when they match the request.',
+    '  - Prefer semantic tools such as create_room, add_door, add_window, furnish_room, and place_items when they match the request.',
     '  - Bundle related mutations into a single `apply_patch` call so they share one undo step.',
     '  - For multi-room changes, call verify_scene after the mutation and fix reported issues.',
     SCENE_DESIGN_GUIDANCE,

package/dist/prompts/scene-guidance.js

@@ -11,13 +11,13 @@ export const SCENE_DESIGN_GUIDANCE = [
     '',
     'Preferred phased tool workflow:',
     '  - Query first with list_levels, get_level_summary, get_walls, or get_zones when editing an existing scene.',
-    '  - Create visible massing early: create_level as needed, then create_story_shell once per story.',
+    '  - Create visible massing early: add_level as needed, then create_story_shell once per story.',
     '  - For rooms, prefer create_room, then add_door/add_window, then furnish_room.',
-    '  - For stairs between floors, prefer create_stair_between_levels so slab/ceiling openings stay rectangular and do not duplicate auto-generated holes.',
+    '  - For stairs between floors, use create_stair: the stair owns the floor openings it cuts, so moving or deleting it moves or closes them.',
     '  - For roofs, prefer create_roof and let it create/use a dedicated roof level above the top occupied story so solo/exploded level views can isolate the roof.',
     '  - verify_scene reports both levelCount and occupiedStoryCount. Use occupiedStoryCount when checking whether a one-story/two-story brief was satisfied.',
     '  - add_door/add_window use t = 0..1 along a wall: 0 is start, 0.5 is center, 1 is end.',
-    '  - Use search_assets before place_item when placing a specific catalog item.',
+    '  - Use search_assets before place_items when placing catalog items.',
     '  - Use apply_patch for precise bulk edits that the semantic tools cannot express.',
     '  - After each major phase, call get_level_summary or pascal://scene/current/summary so progress is visible and errors are easier to localize.',
     '  - After multi-room or full-floor work, call validate_scene and verify_scene, then fix reported issues before finishing.',

package/dist/resources/agent-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-guide.d.ts","sourceRoot":"","sources":["../../src/resources/agent-guide.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,eAAO,MAAM,WAAW,QA2DZ,CAAA;AAEZ,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAuCpF"}
+{"version":3,"file":"agent-guide.d.ts","sourceRoot":"","sources":["../../src/resources/agent-guide.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,eAAO,MAAM,WAAW,QAgFZ,CAAA;AAEZ,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAuCpF"}