@pascal-app/core 0.8.0 → 0.9.2

package/dist/registry/relations-resolver.js

@@ -0,0 +1,77 @@
+import { nodeRegistry } from './registry';
+const DEFAULT_MAX_DEPTH = 16;
+/**
+ * Walks the relations graph from one dirty node and returns the full set of
+ * IDs (including the starting one) that should be marked dirty. Pure — does
+ * NOT call `scene.markDirty`; callers iterate the result.
+ *
+ * Phase 1 implements:
+ * - `hosts`: marks children whose `type` matches the kind list
+ * - `affectsSpatial`: marks neighbors found via `spatialQuery`
+ *
+ * Phase 3 will add `linkedBy: 'endpoint-match'` for wall corner propagation.
+ */
+export function cascadeDirty(startId, ctx) {
+    const result = new Set();
+    const maxDepth = ctx.maxDepth ?? DEFAULT_MAX_DEPTH;
+    walk(startId, ctx, result, 0, maxDepth);
+    return result;
+}
+function walk(id, ctx, result, depth, maxDepth) {
+    if (result.has(id) || depth > maxDepth)
+        return;
+    result.add(id);
+    const node = ctx.scene.get(id);
+    if (!node)
+        return;
+    const def = nodeRegistry.get(node.type);
+    if (!def?.relations)
+        return;
+    const { hosts, affectsSpatial } = def.relations;
+    if (hosts && hosts.length > 0) {
+        const childIds = ctx.childQuery ? ctx.childQuery(node) : defaultChildIds(node, ctx.scene);
+        for (const childId of childIds) {
+            const child = ctx.scene.get(childId);
+            if (child && hosts.includes(child.type)) {
+                walk(childId, ctx, result, depth + 1, maxDepth);
+            }
+        }
+    }
+    if (affectsSpatial && affectsSpatial.length > 0 && ctx.spatialQuery) {
+        for (const neighborId of ctx.spatialQuery(node, affectsSpatial)) {
+            walk(neighborId, ctx, result, depth + 1, maxDepth);
+        }
+    }
+}
+/**
+ * Fallback children lookup that reads the node's `children: AnyNodeId[]`
+ * field if present. Most parametric nodes carry one; nodes that don't will
+ * need a `childQuery` override on the context.
+ */
+function defaultChildIds(node, _scene) {
+    const maybeChildren = node.children;
+    return Array.isArray(maybeChildren) ? maybeChildren : [];
+}
+/**
+ * Recursively collects every descendant of a node, plus the node itself.
+ * Used by `cascadeDelete: 'descendants'` and by tools that need to delete a
+ * subtree atomically. Independent of dirty-marking — pure traversal.
+ */
+export function collectDescendants(startId, ctx) {
+    const result = new Set();
+    const maxDepth = ctx.maxDepth ?? DEFAULT_MAX_DEPTH;
+    walkDescendants(startId, ctx, result, 0, maxDepth);
+    return result;
+}
+function walkDescendants(id, ctx, result, depth, maxDepth) {
+    if (result.has(id) || depth > maxDepth)
+        return;
+    result.add(id);
+    const node = ctx.scene.get(id);
+    if (!node)
+        return;
+    const childIds = ctx.childQuery ? ctx.childQuery(node) : defaultChildIds(node, ctx.scene);
+    for (const childId of childIds) {
+        walkDescendants(childId, ctx, result, depth + 1, maxDepth);
+    }
+}

package/dist/registry/relations-resolver.test.d.ts

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

package/dist/registry/relations-resolver.test.d.ts.map

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

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();
+    });
+});