@pascal-app/core 0.8.0 → 0.9.2

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":"AAEA,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,CAiEtB"}

package/dist/registry/subtree.js

@@ -0,0 +1,123 @@
+import { remapMeasurementReferences } from '../lib/measurement-geometry';
+import { generateId } from '../schema/base';
+function extractIdPrefix(id) {
+    const i = id.indexOf('_');
+    return i === -1 ? 'node' : id.slice(0, i);
+}
+function getChildIds(node) {
+    if ('children' in node && Array.isArray(node.children)) {
+        return node.children;
+    }
+    return [];
+}
+/**
+ * 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 function collectSubtree(nodes, rootId) {
+    const root = nodes[rootId];
+    if (!root)
+        return null;
+    const descendants = [];
+    const seen = new Set([rootId]);
+    const queue = [...getChildIds(root)];
+    let head = 0;
+    while (head < queue.length) {
+        const id = queue[head++];
+        if (seen.has(id))
+            continue;
+        const node = nodes[id];
+        if (!node)
+            continue;
+        seen.add(id);
+        descendants.push(node);
+        for (const childId of getChildIds(node))
+            queue.push(childId);
+    }
+    return { root, descendants };
+}
+/**
+ * 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 function cloneNodesInto(nodes, opts) {
+    // Phase 1 — mint fresh ids for every node, preserving the prefix.
+    const idMap = new Map();
+    for (const node of nodes) {
+        const prefix = extractIdPrefix(node.id);
+        idMap.set(node.id, generateId(prefix));
+    }
+    const rootFreshId = idMap.get(opts.rootId);
+    if (!rootFreshId) {
+        throw new Error(`cloneNodesInto: rootId "${opts.rootId}" not found in supplied nodes array`);
+    }
+    // Phase 2 — clone each node + rewire references.
+    const out = [];
+    let root = null;
+    for (const original of nodes) {
+        const cloned = JSON.parse(JSON.stringify(original));
+        const freshId = idMap.get(original.id);
+        cloned.id = freshId;
+        // parentId: root's parentId becomes opts.parentId (or preserved
+        // value if not supplied). Descendants point at the remapped parent.
+        if (original.id === opts.rootId) {
+            ;
+            cloned.parentId =
+                opts.parentId !== undefined
+                    ? opts.parentId
+                    : (cloned.parentId ?? null);
+        }
+        else if (cloned.parentId) {
+            const parentFresh = idMap.get(cloned.parentId);
+            cloned.parentId = parentFresh ?? null;
+        }
+        // children[]: remap any internal references, drop external ones
+        // (a descendant pointing at a sibling that didn't make it into
+        // `nodes` would dangle — `filter` drops those gracefully).
+        if ('children' in cloned && Array.isArray(cloned.children)) {
+            ;
+            cloned.children = cloned.children
+                .map((cid) => idMap.get(cid))
+                .filter((cid) => cid !== undefined);
+        }
+        if (cloned.type === 'measurement') {
+            cloned.measurement = remapMeasurementReferences(cloned.measurement, idMap);
+        }
+        if (original.id === opts.rootId) {
+            if (opts.position) {
+                ;
+                cloned.position = [
+                    opts.position[0],
+                    opts.position[1],
+                    opts.position[2],
+                ];
+            }
+            root = cloned;
+        }
+        else {
+            out.push(cloned);
+        }
+    }
+    if (!root) {
+        throw new Error('cloneNodesInto: root node missing after clone');
+    }
+    return { rootId: rootFreshId, nodes: [root, ...out], idMap };
+}

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

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

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

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

package/dist/registry/subtree.test.js

@@ -0,0 +1,163 @@
+import { describe, expect, test } from 'bun:test';
+import { cloneNodesInto, collectSubtree } from './subtree';
+function makeNode(id, type, extra = {}) {
+    return {
+        object: 'node',
+        id,
+        type,
+        parentId: null,
+        visible: true,
+        metadata: {},
+        ...extra,
+    };
+}
+describe('collectSubtree', () => {
+    test('returns null for missing root', () => {
+        expect(collectSubtree({}, 'missing')).toBeNull();
+    });
+    test('returns just the root for a leaf node', () => {
+        const root = makeNode('shelf_1', 'shelf', { width: 1 });
+        const sub = collectSubtree({ ['shelf_1']: root }, 'shelf_1');
+        expect(sub?.root).toBe(root);
+        expect(sub?.descendants).toEqual([]);
+    });
+    test('walks descendants in BFS / declaration order', () => {
+        const nodes = {
+            ['shelf_1']: makeNode('shelf_1', 'shelf', {
+                position: [0, 0, 0],
+                children: ['item_a', 'item_b'],
+                width: 1,
+            }),
+            ['item_a']: makeNode('item_a', 'item', {
+                parentId: 'shelf_1',
+                position: [0, 0, 0],
+            }),
+            ['item_b']: makeNode('item_b', 'item', {
+                parentId: 'shelf_1',
+                position: [0.3, 0, 0],
+            }),
+        };
+        const sub = collectSubtree(nodes, 'shelf_1');
+        expect(sub?.descendants.map((n) => n.id)).toEqual(['item_a', 'item_b']);
+    });
+    test('returned nodes are live references — no cloning', () => {
+        const item = makeNode('item_a', 'item', { parentId: 'shelf_1', position: [0, 0, 0] });
+        const nodes = {
+            ['shelf_1']: makeNode('shelf_1', 'shelf', { children: ['item_a'] }),
+            ['item_a']: item,
+        };
+        const sub = collectSubtree(nodes, 'shelf_1');
+        expect(sub?.descendants[0]).toBe(item);
+    });
+});
+describe('cloneNodesInto', () => {
+    test('clones a single root with fresh id and supplied position', () => {
+        const original = makeNode('door_orig', 'door', {
+            position: [1, 2, 3],
+            wallId: 'wall_x',
+            width: 0.9,
+        });
+        const { rootId, nodes } = cloneNodesInto([original], {
+            rootId: 'door_orig',
+            position: [10, 0, -4],
+        });
+        expect(nodes).toHaveLength(1);
+        const cloned = nodes[0];
+        expect(cloned.id).toBe(rootId);
+        expect(cloned.id).not.toBe('door_orig');
+        expect(cloned.id.startsWith('door_')).toBe(true);
+        expect(cloned.position).toEqual([10, 0, -4]);
+        expect(cloned.width).toBe(0.9);
+        // cloneNodesInto is host-ref-agnostic — wallId is preserved
+        // verbatim. Stripping is the caller's job (see getHostRefFields).
+        expect(cloned.wallId).toBe('wall_x');
+    });
+    test('preserves root position when none is supplied', () => {
+        const original = makeNode('shelf_orig', 'shelf', { position: [5, 0, 5] });
+        const { nodes } = cloneNodesInto([original], { rootId: 'shelf_orig' });
+        expect(nodes[0].position).toEqual([5, 0, 5]);
+    });
+    test('preserves parent/child subtree with remapped ids and relative positions', () => {
+        const shelf = makeNode('shelf_1', 'shelf', {
+            position: [5, 0, 5],
+            children: ['item_a', 'item_b'],
+        });
+        const itemA = makeNode('item_a', 'item', { parentId: 'shelf_1', position: [0, 0, 0] });
+        const itemB = makeNode('item_b', 'item', { parentId: 'shelf_1', position: [0.3, 0, 0] });
+        const { rootId, nodes: out } = cloneNodesInto([shelf, itemA, itemB], {
+            rootId: 'shelf_1',
+            position: [99, 0, -99],
+        });
+        expect(out).toHaveLength(3);
+        const root = out[0];
+        expect(root.id).toBe(rootId);
+        expect(root.id).not.toBe('shelf_1');
+        expect(root.position).toEqual([99, 0, -99]);
+        // Root's children rewritten to fresh ids; descendants' parentIds
+        // point at the new root id.
+        const ids = new Set(out.map((n) => n.id));
+        expect(root.children).toHaveLength(2);
+        for (const cid of root.children)
+            expect(ids.has(cid)).toBe(true);
+        for (let i = 1; i < out.length; i += 1) {
+            const desc = out[i];
+            expect(desc.parentId).toBe(rootId);
+            expect(Array.isArray(desc.position)).toBe(true);
+        }
+    });
+    test('remaps associative measurement references inside the cloned subtree', () => {
+        const wall = makeNode('wall_1', 'wall', { parentId: 'level_1' });
+        const measurement = makeNode('measurement_1', 'measurement', {
+            parentId: 'level_1',
+            measurement: {
+                kind: 'distance',
+                points: [
+                    {
+                        kind: 'feature',
+                        reference: { nodeId: 'wall_1', featureId: 'wall:start' },
+                        fallback: [0, 0, 0],
+                    },
+                    [1, 0, 0],
+                ],
+            },
+        });
+        const result = cloneNodesInto([wall, measurement], {
+            rootId: 'wall_1',
+        });
+        const clonedMeasurement = result.nodes.find((node) => node.type === 'measurement');
+        expect(clonedMeasurement?.type).toBe('measurement');
+        if (clonedMeasurement?.type === 'measurement' &&
+            clonedMeasurement.measurement.kind === 'distance') {
+            const anchor = clonedMeasurement.measurement.points[0];
+            expect(Array.isArray(anchor)).toBe(false);
+            if (!Array.isArray(anchor)) {
+                expect(anchor.reference.nodeId).toBe(result.idMap.get('wall_1'));
+            }
+        }
+    });
+    test('parents the cloned root under opts.parentId when supplied', () => {
+        const orig = makeNode('shelf_1', 'shelf', { parentId: 'level_old' });
+        const { nodes } = cloneNodesInto([orig], {
+            rootId: 'shelf_1',
+            parentId: 'level_new',
+        });
+        expect(nodes[0].parentId).toBe('level_new');
+    });
+    test('two clones produce disjoint id sets', () => {
+        const orig = makeNode('shelf_1', 'shelf', {
+            position: [0, 0, 0],
+            children: ['item_a'],
+        });
+        const child = makeNode('item_a', 'item', { parentId: 'shelf_1', position: [0, 0, 0] });
+        const first = cloneNodesInto([orig, child], { rootId: 'shelf_1' });
+        const second = cloneNodesInto([orig, child], { rootId: 'shelf_1' });
+        const idsA = new Set(first.nodes.map((n) => n.id));
+        const idsB = new Set(second.nodes.map((n) => n.id));
+        for (const id of idsA)
+            expect(idsB.has(id)).toBe(false);
+    });
+    test('throws if rootId is missing from the input array', () => {
+        const orig = makeNode('shelf_1', 'shelf', {});
+        expect(() => cloneNodesInto([orig], { rootId: 'shelf_other' })).toThrow(/rootId/);
+    });
+});