@pascal-app/mcp 0.2.0

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

@@ -0,0 +1,158 @@
+import './node-shims';
+import type { SceneGraph } from '@pascal-app/core/clone-scene-graph';
+import type { AnyNode } from '@pascal-app/core/schema';
+import { type AnyNodeId, type AnyNodeType } from '@pascal-app/core/schema';
+import type { SceneMeta } from '../storage/types';
+export type ValidationError = {
+    nodeId: string;
+    path: string;
+    message: string;
+};
+export type ValidationResult = {
+    valid: boolean;
+    errors: ValidationError[];
+};
+export type CreatePatch = {
+    op: 'create';
+    node: AnyNode;
+    parentId?: AnyNodeId;
+};
+export type UpdatePatch = {
+    op: 'update';
+    id: AnyNodeId;
+    data: Partial<AnyNode>;
+};
+export type DeletePatch = {
+    op: 'delete';
+    id: AnyNodeId;
+    cascade?: boolean;
+};
+export type Patch = CreatePatch | UpdatePatch | DeletePatch;
+export type ActiveSceneMeta = Pick<SceneMeta, 'id' | 'name' | 'projectId' | 'ownerId' | 'thumbnailUrl' | 'version'>;
+/**
+ * Headless bridge to the `@pascal-app/core` Zustand store.
+ *
+ * All mutation flows through the real core store so undo/redo works via Zundo.
+ * No renderer is attached; `dirtyNodes` accumulates and can be drained via
+ * `flushDirty()` for observability.
+ */
+export declare class SceneBridge {
+    private activeScene;
+    /**
+     * Scene identity currently bound to this bridge. MCP tools use this to know
+     * which editor scene should receive live events after mutations.
+     */
+    setActiveScene(meta: ActiveSceneMeta): void;
+    getActiveScene(): ActiveSceneMeta | null;
+    clearActiveScene(): void;
+    /** Load initial state; if empty, creates default Site → Building → Level. */
+    loadDefault(): void;
+    /** Replace entire scene (undoable via Zundo). */
+    setScene(nodes: Record<AnyNodeId, AnyNode>, rootNodeIds: AnyNodeId[]): void;
+    /** Full snapshot for export, including collections. */
+    exportJSON(): SceneGraph & {
+        collections: Record<string, unknown>;
+    };
+    /**
+     * Import. Accepts either a JSON string or a parsed SceneGraph object.
+     * Throws on invalid JSON, unexpected shape, or prototype-polluting keys.
+     */
+    loadJSON(json: string | SceneGraph): void;
+    /** Read a single node, or `null` if not present. */
+    getNode(id: AnyNodeId): AnyNode | null;
+    /** All nodes (live reference into the store — do NOT mutate). */
+    getNodes(): Record<AnyNodeId, AnyNode>;
+    /** Root node IDs. */
+    getRootNodeIds(): AnyNodeId[];
+    /**
+     * Resolve children via the flat `nodes` dict. Uses THREE fallbacks because
+     * the codebase's parent-tracking is not uniform:
+     *
+     * 1. `node.parentId === parentId` (normal case post-store-mutation).
+     * 2. Parent has `children: string[]` of IDs (building, level, wall, ...).
+     * 3. Parent has `children: Array<node-object>` (the SiteNode quirk — see
+     *    PLAN §0.7). We resolve each object to its flat-dict entry by `id`.
+     *
+     * The `loadScene()` default assembler skips the store mutation paths so the
+     * default site/building/level tree has `parentId === null` on every node —
+     * only the `children` arrays reflect the hierarchy.
+     *
+     * Results are de-duplicated by id, in flat-dict iteration order.
+     */
+    getChildren(parentId: AnyNodeId): AnyNode[];
+    /**
+     * Walk up `parentId` chain; returns `[self, parent, grandparent, ...]`.
+     *
+     * Falls back to reverse-scanning `children` arrays when `parentId` is
+     * unset (see the default-scene quirk documented on `getChildren`).
+     */
+    getAncestry(id: AnyNodeId): AnyNode[];
+    /** Find all nodes matching the given filters (all filters ANDed). */
+    findNodes(filter: {
+        type?: AnyNodeType;
+        parentId?: AnyNodeId | null;
+        levelId?: AnyNodeId;
+    }): AnyNode[];
+    /** Resolve the level-ancestor of a node, or `null` if none in the chain. */
+    resolveLevelId(id: AnyNodeId): AnyNodeId | null;
+    /**
+     * Create a node. Caller must pass an already-parsed `AnyNode` (with a valid
+     * `id`, generated by the schema default if they did `XxxNode.parse({...})`).
+     * Returns the generated id.
+     */
+    createNode(node: AnyNode, parentId?: AnyNodeId): AnyNodeId;
+    /** Update node fields (shallow merge through the core store). */
+    updateNode(id: AnyNodeId, data: Partial<AnyNode>): void;
+    /**
+     * Delete a node. If the node has children and `cascade === false`, throws.
+     * If `cascade` is true (or undefined and no children), delegates to the core
+     * action which already recursively removes descendants.
+     *
+     * Returns the list of ids actually removed from the scene.
+     */
+    deleteNode(id: AnyNodeId, cascade?: boolean): string[];
+    /**
+     * 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.
+     */
+    applyPatch(patches: Patch[]): {
+        appliedOps: number;
+        deletedIds: AnyNodeId[];
+        createdIds: AnyNodeId[];
+    };
+    /** Undo. Returns the number of steps actually undone. */
+    undo(steps?: number): number;
+    /** Redo. Returns the number of steps actually redone. */
+    redo(steps?: number): number;
+    /**
+     * Zod-validate every node in the scene. Reports one error per failed node,
+     * concatenating Zod issue paths.
+     */
+    validateScene(): ValidationResult;
+    /**
+     * Drain the dirtyNodes set. Returns the ids that were present. No-op for
+     * renderer (there is no renderer in MCP mode); useful for observability.
+     */
+    flushDirty(): string[];
+    /** Current temporal history pointers. */
+    getHistory(): {
+        pastCount: number;
+        futureCount: number;
+    };
+    /** Clear the temporal undo/redo history. */
+    clearHistory(): void;
+    /**
+     * Return the node whose `children` array (string or object form) contains
+     * the given id, or null if none. Used as a fallback when `parentId` is
+     * missing on a node.
+     */
+    private _findParentByChildrenScan;
+    /**
+     * Collect ids of a node and all its descendants. Uses the same combined
+     * strategy as `getChildren` (parentId scan + children-array walk) so that
+     * the SiteNode quirk and the default-scene parentId-unset case both work.
+     */
+    private _collectDescendants;
+}
+//# sourceMappingURL=scene-bridge.d.ts.map

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

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

package/dist/bridge/scene-bridge.js

@@ -0,0 +1,482 @@
+// Side-effect import MUST come first: installs RAF polyfill before core loads.
+import './node-shims';
+import { AnyNode as AnyNodeSchema } 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';
+/**
+ * Headless bridge to the `@pascal-app/core` Zustand store.
+ *
+ * All mutation flows through the real core store so undo/redo works via Zundo.
+ * No renderer is attached; `dirtyNodes` accumulates and can be drained via
+ * `flushDirty()` for observability.
+ */
+export class SceneBridge {
+    activeScene = null;
+    /**
+     * Scene identity currently bound to this bridge. MCP tools use this to know
+     * which editor scene should receive live events after mutations.
+     */
+    setActiveScene(meta) {
+        this.activeScene = {
+            id: meta.id,
+            name: meta.name,
+            projectId: meta.projectId,
+            ownerId: meta.ownerId,
+            thumbnailUrl: meta.thumbnailUrl,
+            version: meta.version,
+        };
+    }
+    getActiveScene() {
+        return this.activeScene;
+    }
+    clearActiveScene() {
+        this.activeScene = null;
+    }
+    /** Load initial state; if empty, creates default Site → Building → Level. */
+    loadDefault() {
+        useScene.getState().loadScene();
+    }
+    /** Replace entire scene (undoable via Zundo). */
+    setScene(nodes, rootNodeIds) {
+        useScene.getState().setScene(nodes, rootNodeIds);
+    }
+    /** Full snapshot for export, including collections. */
+    exportJSON() {
+        const state = useScene.getState();
+        // Deep-clone so callers can't mutate store state directly.
+        return JSON.parse(JSON.stringify({
+            nodes: state.nodes,
+            rootNodeIds: state.rootNodeIds,
+            collections: state.collections ?? {},
+        }));
+    }
+    /**
+     * Import. Accepts either a JSON string or a parsed SceneGraph object.
+     * Throws on invalid JSON, unexpected shape, or prototype-polluting keys.
+     */
+    loadJSON(json) {
+        let parsed;
+        if (typeof json === 'string') {
+            try {
+                parsed = JSON.parse(json);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`invalid JSON: ${msg}`);
+            }
+        }
+        else {
+            parsed = json;
+        }
+        if (!parsed || typeof parsed !== 'object') {
+            throw new Error('invalid scene: expected object with {nodes, rootNodeIds}');
+        }
+        const obj = parsed;
+        const nodes = obj.nodes;
+        const rootNodeIds = obj.rootNodeIds;
+        if (!nodes || typeof nodes !== 'object' || Array.isArray(nodes)) {
+            throw new Error('invalid scene: `nodes` must be an object');
+        }
+        if (!Array.isArray(rootNodeIds)) {
+            throw new Error('invalid scene: `rootNodeIds` must be an array');
+        }
+        // Reject prototype-polluting keys as top-level `nodes` keys.
+        const BANNED = new Set(['__proto__', 'constructor', 'prototype']);
+        for (const key of Object.keys(nodes)) {
+            if (BANNED.has(key)) {
+                throw new Error(`invalid scene: forbidden key "${key}" in nodes`);
+            }
+        }
+        this.setScene(nodes, rootNodeIds);
+    }
+    /** Read a single node, or `null` if not present. */
+    getNode(id) {
+        const node = useScene.getState().nodes[id];
+        return node ?? null;
+    }
+    /** All nodes (live reference into the store — do NOT mutate). */
+    getNodes() {
+        return useScene.getState().nodes;
+    }
+    /** Root node IDs. */
+    getRootNodeIds() {
+        return useScene.getState().rootNodeIds;
+    }
+    /**
+     * Resolve children via the flat `nodes` dict. Uses THREE fallbacks because
+     * the codebase's parent-tracking is not uniform:
+     *
+     * 1. `node.parentId === parentId` (normal case post-store-mutation).
+     * 2. Parent has `children: string[]` of IDs (building, level, wall, ...).
+     * 3. Parent has `children: Array<node-object>` (the SiteNode quirk — see
+     *    PLAN §0.7). We resolve each object to its flat-dict entry by `id`.
+     *
+     * The `loadScene()` default assembler skips the store mutation paths so the
+     * default site/building/level tree has `parentId === null` on every node —
+     * only the `children` arrays reflect the hierarchy.
+     *
+     * Results are de-duplicated by id, in flat-dict iteration order.
+     */
+    getChildren(parentId) {
+        const nodes = useScene.getState().nodes;
+        const out = [];
+        const seen = new Set();
+        // Strategy 1: parentId scan.
+        for (const node of Object.values(nodes)) {
+            if (node.parentId === parentId && !seen.has(node.id)) {
+                seen.add(node.id);
+                out.push(node);
+            }
+        }
+        // Strategies 2 & 3: parent's own `children` field.
+        const parent = nodes[parentId];
+        if (parent && 'children' in parent && Array.isArray(parent.children)) {
+            for (const child of parent.children) {
+                let childId = null;
+                if (typeof child === 'string')
+                    childId = child;
+                else if (child &&
+                    typeof child === 'object' &&
+                    'id' in child &&
+                    typeof child.id === 'string') {
+                    childId = child.id;
+                }
+                if (!childId)
+                    continue;
+                const childNode = nodes[childId];
+                if (!childNode)
+                    continue;
+                if (seen.has(childNode.id))
+                    continue;
+                seen.add(childNode.id);
+                out.push(childNode);
+            }
+        }
+        return out;
+    }
+    /**
+     * Walk up `parentId` chain; returns `[self, parent, grandparent, ...]`.
+     *
+     * Falls back to reverse-scanning `children` arrays when `parentId` is
+     * unset (see the default-scene quirk documented on `getChildren`).
+     */
+    getAncestry(id) {
+        const nodes = useScene.getState().nodes;
+        const out = [];
+        let current = nodes[id];
+        const seen = new Set();
+        while (current && !seen.has(current.id)) {
+            seen.add(current.id);
+            out.push(current);
+            const pid = current.parentId;
+            if (pid && nodes[pid]) {
+                current = nodes[pid];
+                continue;
+            }
+            // Fallback: scan for any node whose `children` includes this id.
+            const fallback = this._findParentByChildrenScan(current.id);
+            if (!fallback)
+                break;
+            current = fallback;
+        }
+        return out;
+    }
+    /** Find all nodes matching the given filters (all filters ANDed). */
+    findNodes(filter) {
+        const nodes = useScene.getState().nodes;
+        const out = [];
+        for (const node of Object.values(nodes)) {
+            if (filter.type !== undefined && node.type !== filter.type)
+                continue;
+            if (filter.parentId !== undefined) {
+                const np = (node.parentId ?? null);
+                if (np !== filter.parentId)
+                    continue;
+            }
+            if (filter.levelId !== undefined) {
+                if (this.resolveLevelId(node.id) !== filter.levelId)
+                    continue;
+            }
+            out.push(node);
+        }
+        return out;
+    }
+    /** Resolve the level-ancestor of a node, or `null` if none in the chain. */
+    resolveLevelId(id) {
+        const ancestry = this.getAncestry(id);
+        for (const node of ancestry) {
+            if (node.type === 'level')
+                return node.id;
+        }
+        return null;
+    }
+    /**
+     * Create a node. Caller must pass an already-parsed `AnyNode` (with a valid
+     * `id`, generated by the schema default if they did `XxxNode.parse({...})`).
+     * Returns the generated id.
+     */
+    createNode(node, parentId) {
+        useScene.getState().createNode(node, parentId);
+        return node.id;
+    }
+    /** Update node fields (shallow merge through the core store). */
+    updateNode(id, data) {
+        if (!useScene.getState().nodes[id]) {
+            throw new Error(`node not found: ${id}`);
+        }
+        useScene.getState().updateNode(id, data);
+    }
+    /**
+     * Delete a node. If the node has children and `cascade === false`, throws.
+     * If `cascade` is true (or undefined and no children), delegates to the core
+     * action which already recursively removes descendants.
+     *
+     * Returns the list of ids actually removed from the scene.
+     */
+    deleteNode(id, cascade = false) {
+        const state = useScene.getState();
+        const node = state.nodes[id];
+        if (!node) {
+            throw new Error(`node not found: ${id}`);
+        }
+        const descendants = this._collectDescendants(id);
+        if (!cascade && descendants.length > 1) {
+            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 afterNodes = useScene.getState().nodes;
+        const removed = [];
+        for (const prevId of before) {
+            if (!(prevId in afterNodes))
+                removed.push(prevId);
+        }
+        return removed;
+    }
+    /**
+     * 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.
+     */
+    applyPatch(patches) {
+        const state = useScene.getState();
+        const nodes = state.nodes;
+        // Track synthesized state as we dry-run so later ops can reference
+        // earlier-created ids and reflect earlier-deleted ids.
+        const simAvailable = new Set(Object.keys(nodes));
+        const simDeleted = new Set();
+        // Parsed create nodes keyed by patch index — so the apply phase can use the
+        // Zod-normalised copy (which has a generated id if the caller omitted one)
+        // instead of the unparsed input.
+        const parsedCreateNodes = 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') {
+                const res = AnyNodeSchema.safeParse(p.node);
+                if (!res.success) {
+                    throw new Error(`invalid patch: patches[${i}] create node failed schema: ${res.error.message}`);
+                }
+                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);
+                simAvailable.add(res.data.id);
+            }
+            else if (p.op === 'update') {
+                if (!simAvailable.has(p.id) || simDeleted.has(p.id)) {
+                    throw new Error(`invalid patch: patches[${i}] update id "${p.id}" not found`);
+                }
+                if (!p.data || typeof p.data !== 'object') {
+                    throw new Error(`invalid patch: patches[${i}] update data is not an object`);
+                }
+            }
+            else if (p.op === 'delete') {
+                if (!simAvailable.has(p.id) || simDeleted.has(p.id)) {
+                    throw new Error(`invalid patch: patches[${i}] delete id "${p.id}" not found`);
+                }
+                if (p.cascade === false) {
+                    // Only inspect the current store state — we don't simulate
+                    // descendant additions during dry-run, because that would require
+                    // building a full shadow tree. This matches the semantics of the
+                    // single-op deleteNode guard.
+                    const desc = this._collectDescendants(p.id);
+                    if (desc.length > 1) {
+                        throw new Error(`invalid patch: patches[${i}] delete "${p.id}" has descendants; pass cascade: true`);
+                    }
+                }
+                simAvailable.delete(p.id);
+                simDeleted.add(p.id);
+            }
+            else {
+                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;
+            }
+            if (kind !== 'delete' && deleteIds.length > 0) {
+                useScene.getState().deleteNodes(deleteIds);
+                deleteIds.length = 0;
+            }
+        };
+        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 (p.op === 'update') {
+                flush('update');
+                updateOps.push({ id: p.id, data: p.data });
+            }
+            else {
+                flush('delete');
+                deleteIds.push(p.id);
+            }
+        }
+        flush('none');
+        // Compute actual deleted ids by diffing pre/post snapshots.
+        const postNodes = useScene.getState().nodes;
+        const deletedIds = [];
+        for (const prevId of Object.keys(nodes)) {
+            if (!(prevId in postNodes))
+                deletedIds.push(prevId);
+        }
+        return {
+            appliedOps: patches.length,
+            deletedIds,
+            createdIds,
+        };
+    }
+    /** Undo. Returns the number of steps actually undone. */
+    undo(steps = 1) {
+        const before = useScene.temporal.getState().pastStates.length;
+        useScene.temporal.getState().undo(steps);
+        const after = useScene.temporal.getState().pastStates.length;
+        return Math.max(0, before - after);
+    }
+    /** Redo. Returns the number of steps actually redone. */
+    redo(steps = 1) {
+        const before = useScene.temporal.getState().futureStates.length;
+        useScene.temporal.getState().redo(steps);
+        const after = useScene.temporal.getState().futureStates.length;
+        return Math.max(0, before - after);
+    }
+    /**
+     * Zod-validate every node in the scene. Reports one error per failed node,
+     * concatenating Zod issue paths.
+     */
+    validateScene() {
+        const errors = [];
+        const nodes = useScene.getState().nodes;
+        for (const [id, node] of Object.entries(nodes)) {
+            const res = AnyNodeSchema.safeParse(node);
+            if (res.success)
+                continue;
+            for (const issue of res.error.issues) {
+                errors.push({
+                    nodeId: id,
+                    path: issue.path.join('.'),
+                    message: issue.message,
+                });
+            }
+        }
+        return { valid: errors.length === 0, errors };
+    }
+    /**
+     * Drain the dirtyNodes set. Returns the ids that were present. No-op for
+     * renderer (there is no renderer in MCP mode); useful for observability.
+     */
+    flushDirty() {
+        const state = useScene.getState();
+        const ids = Array.from(state.dirtyNodes);
+        for (const id of ids) {
+            state.clearDirty(id);
+        }
+        return ids;
+    }
+    /** Current temporal history pointers. */
+    getHistory() {
+        const t = useScene.temporal.getState();
+        return {
+            pastCount: t.pastStates.length,
+            futureCount: t.futureStates.length,
+        };
+    }
+    /** Clear the temporal undo/redo history. */
+    clearHistory() {
+        useScene.temporal.getState().clear();
+    }
+    // ---- internal helpers ----
+    /**
+     * Return the node whose `children` array (string or object form) contains
+     * the given id, or null if none. Used as a fallback when `parentId` is
+     * missing on a node.
+     */
+    _findParentByChildrenScan(id) {
+        const nodes = useScene.getState().nodes;
+        for (const candidate of Object.values(nodes)) {
+            if (!('children' in candidate && Array.isArray(candidate.children)))
+                continue;
+            for (const child of candidate.children) {
+                let childId = null;
+                if (typeof child === 'string')
+                    childId = child;
+                else if (child &&
+                    typeof child === 'object' &&
+                    'id' in child &&
+                    typeof child.id === 'string') {
+                    childId = child.id;
+                }
+                if (childId === id)
+                    return candidate;
+            }
+        }
+        return null;
+    }
+    /**
+     * Collect ids of a node and all its descendants. Uses the same combined
+     * strategy as `getChildren` (parentId scan + children-array walk) so that
+     * the SiteNode quirk and the default-scene parentId-unset case both work.
+     */
+    _collectDescendants(id) {
+        const nodes = useScene.getState().nodes;
+        if (!nodes[id])
+            return [];
+        const out = [];
+        const stack = [id];
+        const seen = new Set();
+        // Precompute parent → child[] index from parentId only. `children` arrays
+        // are consulted on-the-fly via getChildren.
+        while (stack.length > 0) {
+            const curr = stack.pop();
+            if (seen.has(curr))
+                continue;
+            seen.add(curr);
+            out.push(curr);
+            const children = this.getChildren(curr);
+            for (const c of children)
+                stack.push(c.id);
+        }
+        return out;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { SceneBridge } from './bridge/scene-bridge';
+export { createSceneOperations, type SceneOperations } from './operations';
+export { type CreatePascalMcpServerOptions, createPascalMcpServer } from './server';
+export declare const version = "0.1.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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;AAEnF,eAAO,MAAM,OAAO,UAAU,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { SceneBridge } from './bridge/scene-bridge';
+export { createSceneOperations } from './operations';
+export { createPascalMcpServer } from './server';
+export const version = '0.1.0';

package/dist/lib/rehydrate-site-children.d.ts

@@ -0,0 +1,12 @@
+import type { SceneGraph } from '@pascal-app/core/clone-scene-graph';
+/**
+ * `cloneSceneGraph` normalises `SiteNode.children` to an array of node IDs,
+ * but core's `SiteNode` schema expects an array of embedded `BuildingNode` /
+ * `ItemNode` objects (see `packages/mcp/CROSS_CUTTING.md` §2). To keep the
+ * cloned graph validating against `AnyNode`, re-embed the site children from
+ * the flat dict.
+ *
+ * Pure: returns a new graph without mutating the input.
+ */
+export declare function rehydrateSiteChildren(graph: SceneGraph): SceneGraph;
+//# sourceMappingURL=rehydrate-site-children.d.ts.map

package/dist/lib/rehydrate-site-children.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate-site-children.d.ts","sourceRoot":"","sources":["../../src/lib/rehydrate-site-children.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAGpE;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CA2BnE"}