@pascal-app/core 0.8.0 → 0.9.1

package/dist/registry/relations-resolver.test.js

@@ -0,0 +1,183 @@
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { z } from 'zod';
+import { nodeRegistry, registerNode } from './registry';
+import { cascadeDirty, collectDescendants } from './relations-resolver';
+const id = (s) => s;
+function makeDef(kind, relations, overrides = {}) {
+    return {
+        kind,
+        schemaVersion: 1,
+        schema: z.object({ type: z.literal(kind) }),
+        category: 'utility',
+        defaults: () => ({}),
+        capabilities: {},
+        relations,
+        renderer: { kind: 'parametric', module: async () => ({ default: () => null }) },
+        ...overrides,
+    };
+}
+function makeNode(kind, idStr, extra = {}) {
+    return {
+        id: id(idStr),
+        type: kind,
+        parentId: null,
+        visible: true,
+        ...extra,
+    };
+}
+function makeFakeScene(nodes) {
+    return {
+        get: ((nid) => nodes[nid]),
+        nodes: () => nodes,
+        update: () => { },
+        upsert: () => id(''),
+        delete: () => { },
+        restore: () => { },
+        restoreAll: () => { },
+        markDirty: () => { },
+        pauseHistory: () => { },
+        resumeHistory: () => { },
+        getSubtree: () => null,
+        cloneNodesInto: () => null,
+    };
+}
+describe('cascadeDirty', () => {
+    beforeEach(() => {
+        nodeRegistry._reset();
+    });
+    test('starting node alone when registry is empty', () => {
+        const scene = makeFakeScene({ a: makeNode('unknown', 'a') });
+        const dirty = cascadeDirty(id('a'), { scene });
+        expect(Array.from(dirty)).toEqual([id('a')]);
+    });
+    test('starting node alone when no relations declared', () => {
+        registerNode(makeDef('thing'));
+        const scene = makeFakeScene({ a: makeNode('thing', 'a') });
+        const dirty = cascadeDirty(id('a'), { scene });
+        expect(Array.from(dirty)).toEqual([id('a')]);
+    });
+    test('hosts cascade marks matching children dirty', () => {
+        registerNode(makeDef('wall', { hosts: ['door', 'window'] }));
+        registerNode(makeDef('door'));
+        registerNode(makeDef('window'));
+        registerNode(makeDef('lamp'));
+        const wall = makeNode('wall', 'w1', {
+            children: [id('d1'), id('w2'), id('l1')],
+        });
+        const scene = makeFakeScene({
+            w1: wall,
+            d1: makeNode('door', 'd1', { parentId: id('w1') }),
+            w2: makeNode('window', 'w2', { parentId: id('w1') }),
+            l1: makeNode('lamp', 'l1', { parentId: id('w1') }), // not in hosts list
+        });
+        const dirty = cascadeDirty(id('w1'), { scene });
+        const ids = Array.from(dirty).sort();
+        expect(ids).toEqual([id('d1'), id('w1'), id('w2')]); // l1 excluded
+    });
+    test('hosts cascade is recursive but bounded by maxDepth', () => {
+        registerNode(makeDef('a', { hosts: ['a'] })); // a hosts more a
+        const nodes = {};
+        for (let i = 0; i < 25; i++) {
+            const childId = i < 24 ? id(`a${i + 1}`) : undefined;
+            nodes[`a${i}`] = makeNode('a', `a${i}`, {
+                children: childId ? [childId] : [],
+            });
+        }
+        const scene = makeFakeScene(nodes);
+        const dirty = cascadeDirty(id('a0'), { scene, maxDepth: 5 });
+        expect(dirty.size).toBe(6); // a0 + 5 descendants
+    });
+    test('affectsSpatial cascade uses spatialQuery to find neighbors', () => {
+        registerNode(makeDef('wall', { affectsSpatial: ['slab', 'zone'] }));
+        registerNode(makeDef('slab'));
+        registerNode(makeDef('zone'));
+        const scene = makeFakeScene({
+            w1: makeNode('wall', 'w1'),
+            s1: makeNode('slab', 's1'),
+            z1: makeNode('zone', 'z1'),
+            unrelated: makeNode('door', 'unrelated'),
+        });
+        const spatialQuery = (node, kinds) => {
+            if (node.id !== id('w1'))
+                return [];
+            const matches = [];
+            if (kinds.includes('slab'))
+                matches.push(id('s1'));
+            if (kinds.includes('zone'))
+                matches.push(id('z1'));
+            return matches;
+        };
+        const dirty = cascadeDirty(id('w1'), { scene, spatialQuery });
+        expect(Array.from(dirty).sort()).toEqual([id('s1'), id('w1'), id('z1')]);
+    });
+    test('affectsSpatial is a no-op when no spatialQuery is provided', () => {
+        registerNode(makeDef('wall', { affectsSpatial: ['slab'] }));
+        const scene = makeFakeScene({ w1: makeNode('wall', 'w1') });
+        const dirty = cascadeDirty(id('w1'), { scene });
+        expect(Array.from(dirty)).toEqual([id('w1')]); // spatial branch silently skipped
+    });
+    test('cycle in hosts cascade does not loop forever', () => {
+        registerNode(makeDef('a', { hosts: ['a'] }));
+        const nodes = {
+            a1: makeNode('a', 'a1', { children: [id('a2')] }),
+            a2: makeNode('a', 'a2', { children: [id('a1')] }), // cycle
+        };
+        const scene = makeFakeScene(nodes);
+        const dirty = cascadeDirty(id('a1'), { scene });
+        expect(dirty.size).toBe(2);
+        expect(dirty.has(id('a1'))).toBe(true);
+        expect(dirty.has(id('a2'))).toBe(true);
+    });
+    test('custom childQuery overrides the default node.children lookup', () => {
+        registerNode(makeDef('wall', { hosts: ['door'] }));
+        registerNode(makeDef('door'));
+        const scene = makeFakeScene({
+            w1: makeNode('wall', 'w1'), // no children field
+            d1: makeNode('door', 'd1', { parentId: id('w1') }),
+        });
+        // childQuery iterates the scene to find parentId matches — what you would
+        // do for kinds that don't carry an explicit children array.
+        const childQuery = (node) => {
+            const result = [];
+            for (const candidate of [id('d1')]) {
+                const c = scene.get(candidate);
+                if (c && c.parentId === node.id)
+                    result.push(c.id);
+            }
+            return result;
+        };
+        const dirty = cascadeDirty(id('w1'), { scene, childQuery });
+        expect(Array.from(dirty).sort()).toEqual([id('d1'), id('w1')]);
+    });
+});
+describe('collectDescendants', () => {
+    beforeEach(() => {
+        nodeRegistry._reset();
+    });
+    test('returns just the start when no children', () => {
+        const scene = makeFakeScene({ a: makeNode('thing', 'a') });
+        const result = collectDescendants(id('a'), { scene });
+        expect(Array.from(result)).toEqual([id('a')]);
+    });
+    test('returns full subtree regardless of relations declarations', () => {
+        // No def registered — descendants still found via the children array.
+        const scene = makeFakeScene({
+            root: makeNode('thing', 'root', { children: [id('c1'), id('c2')] }),
+            c1: makeNode('thing', 'c1', { children: [id('g1')] }),
+            c2: makeNode('thing', 'c2'),
+            g1: makeNode('thing', 'g1'),
+        });
+        const result = collectDescendants(id('root'), { scene });
+        expect(Array.from(result).sort()).toEqual([id('c1'), id('c2'), id('g1'), id('root')]);
+    });
+    test('respects maxDepth', () => {
+        const scene = makeFakeScene({
+            a: makeNode('thing', 'a', { children: [id('b')] }),
+            b: makeNode('thing', 'b', { children: [id('c')] }),
+            c: makeNode('thing', 'c', { children: [id('d')] }),
+            d: makeNode('thing', 'd'),
+        });
+        const result = collectDescendants(id('a'), { scene, maxDepth: 2 });
+        expect(Array.from(result).sort()).toEqual([id('a'), id('b'), id('c')]); // d truncated
+    });
+});

package/dist/registry/scene-api.d.ts

@@ -0,0 +1,44 @@
+import type { AnyNode, AnyNodeId } from '../schema/types';
+import type { SceneApi } from './types';
+/**
+ * Minimal store shape this module depends on.
+ *
+ * Decoupled from `useScene` directly so the production singleton and tests can
+ * share one factory. The full store implements a superset.
+ */
+export type SceneStoreLike = {
+    getState: () => {
+        nodes: Record<AnyNodeId, AnyNode>;
+        rootNodeIds: AnyNodeId[];
+        dirtyNodes: Set<AnyNodeId>;
+        createNode: (node: AnyNode, parentId?: AnyNodeId) => void;
+        createNodes?: (ops: {
+            node: AnyNode;
+            parentId?: AnyNodeId;
+        }[]) => void;
+        updateNode: (id: AnyNodeId, data: Partial<AnyNode>) => void;
+        deleteNode: (id: AnyNodeId) => void;
+        markDirty: (id: AnyNodeId) => void;
+    };
+    temporal: {
+        getState: () => {
+            pause: () => void;
+            resume: () => void;
+        };
+    };
+};
+/**
+ * Creates a {@link SceneApi} backed by a store.
+ *
+ * Snapshot semantics:
+ * - `pauseHistory()` starts a copy-on-write window. The first time `update`,
+ *   `upsert`, or `delete` touches a node id, the pre-change value is captured.
+ * - `restore(id)` and `restoreAll()` apply the captured value back. Either is
+ *   safe to call only while a pause window is active.
+ * - `resumeHistory()` drops the snapshot.
+ *
+ * Snapshots are lazy and bounded by the number of nodes touched during the
+ * pause window — never an upfront clone of the entire scene.
+ */
+export declare function createSceneApi(store: SceneStoreLike): SceneApi;
+//# sourceMappingURL=scene-api.d.ts.map

package/dist/registry/scene-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-api.d.ts","sourceRoot":"","sources":["../../src/registry/scene-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAOzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,MAAM;QACd,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QACjC,WAAW,EAAE,SAAS,EAAE,CAAA;QACxB,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,CAAA;QAC1B,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,KAAK,IAAI,CAAA;QACzD,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;SAAE,EAAE,KAAK,IAAI,CAAA;QACtE,UAAU,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;QAC3D,UAAU,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,CAAA;QACnC,SAAS,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,CAAA;KACnC,CAAA;IACD,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM;YAAE,KAAK,EAAE,MAAM,IAAI,CAAC;YAAC,MAAM,EAAE,MAAM,IAAI,CAAA;SAAE,CAAA;KAC1D,CAAA;CACF,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,QAAQ,CAgG9D"}

package/dist/registry/scene-api.js

@@ -0,0 +1,111 @@
+import { pauseSceneHistory, resumeSceneHistory } from '../store/history-control';
+import { collectSubtree, cloneNodesInto as runCloneNodesInto, } from './subtree';
+/**
+ * Creates a {@link SceneApi} backed by a store.
+ *
+ * Snapshot semantics:
+ * - `pauseHistory()` starts a copy-on-write window. The first time `update`,
+ *   `upsert`, or `delete` touches a node id, the pre-change value is captured.
+ * - `restore(id)` and `restoreAll()` apply the captured value back. Either is
+ *   safe to call only while a pause window is active.
+ * - `resumeHistory()` drops the snapshot.
+ *
+ * Snapshots are lazy and bounded by the number of nodes touched during the
+ * pause window — never an upfront clone of the entire scene.
+ */
+export function createSceneApi(store) {
+    let snapshot = null;
+    function captureIfNeeded(id) {
+        if (!snapshot || snapshot.has(id))
+            return;
+        const existing = store.getState().nodes[id];
+        snapshot.set(id, existing ?? null);
+    }
+    return {
+        get(id) {
+            return store.getState().nodes[id];
+        },
+        nodes() {
+            return store.getState().nodes;
+        },
+        update(id, patch) {
+            captureIfNeeded(id);
+            store.getState().updateNode(id, patch);
+        },
+        upsert(node, parentId) {
+            captureIfNeeded(node.id);
+            store.getState().createNode(node, parentId);
+            return node.id;
+        },
+        delete(id) {
+            captureIfNeeded(id);
+            store.getState().deleteNode(id);
+        },
+        restore(id) {
+            if (!snapshot)
+                return;
+            const original = snapshot.get(id);
+            if (original === undefined)
+                return;
+            const current = store.getState().nodes[id];
+            if (original === null) {
+                if (current)
+                    store.getState().deleteNode(id);
+            }
+            else if (!current) {
+                store.getState().createNode(original);
+            }
+            else {
+                store.getState().updateNode(id, original);
+            }
+        },
+        restoreAll() {
+            if (!snapshot)
+                return;
+            for (const id of snapshot.keys()) {
+                this.restore(id);
+            }
+        },
+        markDirty(id) {
+            store.getState().markDirty(id);
+        },
+        pauseHistory() {
+            pauseSceneHistory(store);
+            if (!snapshot)
+                snapshot = new Map();
+        },
+        resumeHistory() {
+            resumeSceneHistory(store);
+            snapshot = null;
+        },
+        getSubtree(rootId) {
+            return collectSubtree(store.getState().nodes, rootId);
+        },
+        cloneNodesInto(nodes, opts) {
+            const { rootId, nodes: cloned } = runCloneNodesInto(nodes, opts);
+            const root = cloned[0];
+            if (!root)
+                return null;
+            const state = store.getState();
+            const ops = [];
+            for (let i = 0; i < cloned.length; i += 1) {
+                const node = cloned[i];
+                if (i === 0) {
+                    ops.push(opts.parentId ? { node, parentId: opts.parentId } : { node });
+                }
+                else {
+                    ops.push({ node });
+                }
+            }
+            const batch = state.createNodes;
+            if (batch) {
+                batch(ops);
+            }
+            else {
+                for (const op of ops)
+                    state.createNode(op.node, op.parentId);
+            }
+            return rootId;
+        },
+    };
+}

package/dist/registry/scene-api.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scene-api.test.d.ts.map

package/dist/registry/scene-api.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-api.test.d.ts","sourceRoot":"","sources":["../../src/registry/scene-api.test.ts"],"names":[],"mappings":""}

package/dist/registry/scene-api.test.js

@@ -0,0 +1,183 @@
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { resetSceneHistoryPauseDepth } from '../store/history-control';
+import { createSceneApi } from './scene-api';
+function makeFakeStore(initial = {}) {
+    const state = {
+        nodes: { ...initial },
+        rootNodeIds: [],
+        dirtyNodes: new Set(),
+        createNode(node) {
+            state.nodes[node.id] = node;
+        },
+        updateNode(id, data) {
+            const existing = state.nodes[id];
+            if (existing)
+                state.nodes[id] = { ...existing, ...data };
+        },
+        deleteNode(id) {
+            delete state.nodes[id];
+        },
+        markDirty(id) {
+            state.dirtyNodes.add(id);
+        },
+    };
+    let paused = 0;
+    const temporal = {
+        getState: () => ({
+            pause: () => {
+                paused += 1;
+            },
+            resume: () => {
+                paused -= 1;
+            },
+        }),
+    };
+    const store = {
+        getState: () => state,
+        temporal,
+        _state: state,
+        _pausedCount: () => paused,
+    };
+    return store;
+}
+function makeNode(id, extra = {}) {
+    return { id, type: 'site', parentId: null, visible: true, ...extra };
+}
+// Tests use short string IDs ("a", "b") for readability. The store's
+// AnyNodeId is a branded template-literal type — cast at the boundary.
+const id = (s) => s;
+const nodes = (store) => store._state.nodes;
+describe('SceneApi', () => {
+    beforeEach(() => {
+        resetSceneHistoryPauseDepth();
+    });
+    test('get reads node from store', () => {
+        const store = makeFakeStore({ a: makeNode('a') });
+        const api = createSceneApi(store);
+        expect(api.get(id('a'))).toEqual(makeNode('a'));
+        expect(api.get(id('missing'))).toBeUndefined();
+    });
+    test('update applies patch via store.updateNode', () => {
+        const store = makeFakeStore({ a: makeNode('a', { visible: true }) });
+        const api = createSceneApi(store);
+        api.update(id('a'), { visible: false });
+        expect(nodes(store)['a']).toMatchObject({ visible: false });
+    });
+    test('upsert calls createNode and returns the id', () => {
+        const store = makeFakeStore();
+        const api = createSceneApi(store);
+        const returnedId = api.upsert(makeNode('a'));
+        expect(returnedId).toBe(id('a'));
+        expect(nodes(store)['a']).toBeDefined();
+    });
+    test('delete removes node from store', () => {
+        const store = makeFakeStore({ a: makeNode('a') });
+        const api = createSceneApi(store);
+        api.delete(id('a'));
+        expect(nodes(store)['a']).toBeUndefined();
+    });
+    test('markDirty forwards to store', () => {
+        const store = makeFakeStore({ a: makeNode('a') });
+        const api = createSceneApi(store);
+        api.markDirty(id('a'));
+        expect(store._state.dirtyNodes.has(id('a'))).toBe(true);
+    });
+    test('pauseHistory and resumeHistory bracket store.temporal pause/resume', () => {
+        const store = makeFakeStore();
+        const api = createSceneApi(store);
+        expect(store._pausedCount()).toBe(0);
+        api.pauseHistory();
+        expect(store._pausedCount()).toBe(1);
+        api.resumeHistory();
+        expect(store._pausedCount()).toBe(0);
+    });
+    test('nested pause/resume use a depth counter (single pause call to temporal)', () => {
+        const store = makeFakeStore();
+        const api = createSceneApi(store);
+        api.pauseHistory();
+        api.pauseHistory();
+        expect(store._pausedCount()).toBe(1); // only one actual pause
+        api.resumeHistory();
+        expect(store._pausedCount()).toBe(1); // still paused — inner resume
+        api.resumeHistory();
+        expect(store._pausedCount()).toBe(0);
+    });
+});
+describe('SceneApi snapshot / restore', () => {
+    beforeEach(() => {
+        resetSceneHistoryPauseDepth();
+    });
+    test('restore returns a touched node to its pre-pause state', () => {
+        const store = makeFakeStore({ a: makeNode('a', { visible: true }) });
+        const api = createSceneApi(store);
+        api.pauseHistory();
+        api.update(id('a'), { visible: false });
+        expect(nodes(store)['a']).toMatchObject({ visible: false });
+        api.restore(id('a'));
+        expect(nodes(store)['a']).toMatchObject({ visible: true });
+        api.resumeHistory();
+    });
+    test('restore on a node never touched is a no-op', () => {
+        const store = makeFakeStore({ a: makeNode('a', { visible: true }) });
+        const api = createSceneApi(store);
+        api.pauseHistory();
+        api.restore(id('a'));
+        expect(nodes(store)['a']).toMatchObject({ visible: true });
+        api.resumeHistory();
+    });
+    test('restoreAll reverts every touched node', () => {
+        const store = makeFakeStore({
+            a: makeNode('a', { visible: true }),
+            b: makeNode('b', { visible: true }),
+        });
+        const api = createSceneApi(store);
+        api.pauseHistory();
+        api.update(id('a'), { visible: false });
+        api.update(id('b'), { visible: false });
+        api.restoreAll();
+        expect(nodes(store)['a']).toMatchObject({ visible: true });
+        expect(nodes(store)['b']).toMatchObject({ visible: true });
+        api.resumeHistory();
+    });
+    test('restore re-creates a node that was deleted mid-pause', () => {
+        const original = makeNode('a', { visible: true });
+        const store = makeFakeStore({ a: original });
+        const api = createSceneApi(store);
+        api.pauseHistory();
+        api.delete(id('a'));
+        expect(nodes(store)['a']).toBeUndefined();
+        api.restore(id('a'));
+        expect(nodes(store)['a']).toEqual(original);
+        api.resumeHistory();
+    });
+    test('restore deletes a node that was upserted mid-pause', () => {
+        const store = makeFakeStore();
+        const api = createSceneApi(store);
+        api.pauseHistory();
+        api.upsert(makeNode('a'));
+        expect(nodes(store)['a']).toBeDefined();
+        api.restore(id('a'));
+        expect(nodes(store)['a']).toBeUndefined();
+        api.resumeHistory();
+    });
+    test('snapshot is dropped on resumeHistory; restore after resume is a no-op', () => {
+        const store = makeFakeStore({ a: makeNode('a', { visible: true }) });
+        const api = createSceneApi(store);
+        api.pauseHistory();
+        api.update(id('a'), { visible: false });
+        api.resumeHistory();
+        api.restore(id('a')); // snapshot gone — no effect
+        expect(nodes(store)['a']).toMatchObject({ visible: false });
+    });
+    test('only the first mutation in a pause window captures the original', () => {
+        const store = makeFakeStore({ a: makeNode('a', { visible: true }) });
+        const api = createSceneApi(store);
+        api.pauseHistory();
+        api.update(id('a'), { visible: false });
+        api.update(id('a'), { visible: true }); // second update — must not overwrite snapshot
+        api.update(id('a'), { visible: false });
+        api.restore(id('a'));
+        expect(nodes(store)['a']).toMatchObject({ visible: true }); // the *first* pre-pause value
+        api.resumeHistory();
+    });
+});

package/dist/registry/subtree.d.ts

@@ -0,0 +1,67 @@
+import type { AnyNode, AnyNodeId } from '../schema/types';
+/** A flat live-scene subtree rooted at `root`. */
+export type Subtree = {
+    /** The root node, exactly as stored in `useScene.nodes[rootId]`. */
+    root: AnyNode;
+    /** Every descendant reachable from `root` via the data-model `children` array, in BFS order. */
+    descendants: AnyNode[];
+};
+/**
+ * Collect the subtree of nodes rooted at `rootId` from the live scene.
+ *
+ * - BFS walk via `node.children` arrays — order is stable and matches
+ *   declaration order on container kinds.
+ * - Returns the live node references (not clones). Cheap; the caller
+ *   chooses whether to deep-clone for persistence.
+ * - Returns `null` if `rootId` is missing.
+ */
+export declare function collectSubtree(nodes: Readonly<Record<AnyNodeId, AnyNode>>, rootId: AnyNodeId): Subtree | null;
+export type CloneNodesIntoOptions = {
+    /**
+     * The id of the root node within `nodes` (i.e. the node whose
+     * `parentId` becomes `parentId` in the destination instead of being
+     * remapped to a sibling's fresh id). Required because `nodes` is a
+     * flat array — there's no other way to mark which one is the root.
+     */
+    rootId: AnyNodeId;
+    /**
+     * Parent for the cloned root in the destination scene. When omitted,
+     * the root is inserted as a scene root (its `parentId` becomes the
+     * preserved value, often `null`).
+     */
+    parentId?: AnyNodeId;
+    /**
+     * Optional override for the cloned root's `position` (most placement
+     * flows stamp the cursor / target point here). When omitted, the
+     * root's own `position` field is preserved verbatim. Descendants
+     * always keep their original positions — those are local to the root.
+     */
+    position?: readonly [number, number, number];
+};
+export type CloneNodesIntoResult = {
+    /** Fresh id assigned to the root in the destination scene. */
+    rootId: AnyNodeId;
+    /** Every cloned node, root first, ready to feed into `createNodes`. */
+    nodes: AnyNode[];
+    /** Original id → fresh id map, mostly useful for tests and host-side bookkeeping. */
+    idMap: Map<AnyNodeId, AnyNodeId>;
+};
+/**
+ * Clone a flat array of nodes with fresh IDs and rewired references,
+ * ready to insert via `useScene.createNodes`.
+ *
+ * Transformations applied:
+ *   1. Deep-clone each node via JSON round-trip (strips three.js refs,
+ *      functions, circular links — same trick `cloneLevelSubtree` uses).
+ *   2. Mint a fresh id for every node, preserving the prefix
+ *      (`wall_…`, `door_…`, etc.) so logs and lookups stay readable.
+ *   3. Rewrite `parentId`, `children[]` to use the fresh ids.
+ *   4. Stamp `position` onto the root if provided.
+ *   5. Set the root's `parentId` to `opts.parentId` when supplied.
+ *
+ * Intentionally generic — no awareness of host refs (`wallId`/`wallT`
+ * etc.). The caller is responsible for stripping or re-deriving those
+ * before / after calling this function. See `getHostRefFields(def)`.
+ */
+export declare function cloneNodesInto(nodes: ReadonlyArray<AnyNode>, opts: CloneNodesIntoOptions): CloneNodesIntoResult;
+//# sourceMappingURL=subtree.d.ts.map

package/dist/registry/subtree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subtree.d.ts","sourceRoot":"","sources":["../../src/registry/subtree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAmBzD,kDAAkD;AAClD,MAAM,MAAM,OAAO,GAAG;IACpB,oEAAoE;IACpE,IAAI,EAAE,OAAO,CAAA;IACb,gGAAgG;IAChG,WAAW,EAAE,OAAO,EAAE,CAAA;CACvB,CAAA;AAcD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,EAC3C,MAAM,EAAE,SAAS,GAChB,OAAO,GAAG,IAAI,CAmBhB;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;;OAKG;IACH,MAAM,EAAE,SAAS,CAAA;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAC7C,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,8DAA8D;IAC9D,MAAM,EAAE,SAAS,CAAA;IACjB,uEAAuE;IACvE,KAAK,EAAE,OAAO,EAAE,CAAA;IAChB,qFAAqF;IACrF,KAAK,EAAE,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;CACjC,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,EAC7B,IAAI,EAAE,qBAAqB,GAC1B,oBAAoB,CA6DtB"}