@pascal-app/core 1.0.1 → 1.0.4

package/dist/store/use-scene.js

@@ -1,7 +1,7 @@
 'use client';
 import { temporal } from 'zundo';
 import { create } from 'zustand';
-import { parseMaterialRef, toSceneMaterialRef } from '../material-library.js';
+import { toSceneMaterialRef } from '../material-library.js';
 import { getNodePluginId, isNodeKindEnabled, nodeRegistry } from '../registry/registry.js';
 import { BuildingNode } from '../schema/index.js';
 import { generateCollectionId } from '../schema/collections.js';
@@ -16,19 +16,28 @@ import { ShelfNode as ShelfNodeSchema } from '../schema/nodes/shelf.js';
 import { SiteNode } from '../schema/nodes/site.js';
 import { getEffectiveStairSurfaceMaterial, StairNode as StairNodeSchema, } from '../schema/nodes/stair.js';
 import { StairSegmentNode as StairSegmentNodeSchema } from '../schema/nodes/stair-segment.js';
-import { getEffectiveWallSurfaceMaterial } from '../schema/nodes/wall.js';
 import { WindowNode as WindowNodeSchema } from '../schema/nodes/window.js';
-import { generateSceneMaterialId, SceneMaterial, } from '../schema/scene-material.js';
+import { SceneMaterial } from '../schema/scene-material.js';
 import { AnyNode as AnyNodeSchema } from '../schema/types.js';
-import { syncAutoElevatorOpenings } from '../systems/elevator/elevator-opening-sync.js';
-import { syncAutoStairOpenings } from '../systems/stair/stair-opening-sync.js';
-import { syncStairRises } from '../systems/stair/stair-rise.js';
+import { DEFAULT_LEVEL_HEIGHT } from '../services/level-height.js';
+import { ensureSceneOpenings } from '../utils/ensure-scene-openings.js';
+import { migrateFloorPlates, migrateSlabSlots } from '../utils/floor-plate-migration.js';
 import { healSceneNodes } from '../utils/heal-scene-graph.js';
+import { legacySpecToMaterialRef, migrateSingleMaterialSlots, migrateWallSurfaceMaterials, } from '../utils/legacy-material-slots.js';
+import { materializeNodeDefaults } from '../utils/node-defaults.js';
+import { normalizeLegacyStructure } from '../utils/normalize-legacy-structure.js';
+import { materializeLegacyAutoOpenings } from '../utils/owned-floor-opening-migration.js';
+import { reconcileStructureOnLoad } from '../utils/reconcile-structure-on-load.js';
 import { removeRetiredDrawingSheetNodes } from '../utils/retired-scene-nodes.js';
+import { migrateCeilingRoomLinks, migrateRoomZones } from '../utils/room-zone-migration.js';
 import { migrateVerticalSceneNodes } from '../utils/vertical-scene-migration.js';
+import { migrateLegacyWallAssemblies } from '../utils/wall-assembly-migration.js';
+import { migrateWallFaceBands, migrateWallFaceKeys } from '../utils/wall-face-migration.js';
 import * as nodeActions from './actions/node-actions.js';
-import { areSceneSnapshotsEqual, getSceneHistoryPauseDepth, notifySceneCommit, pauseSceneHistory, resetSceneHistoryPauseDepth, resumeSceneHistory, runWithSceneCommitNodeIds, } from './history-control.js';
+import { areSceneSnapshotsEqual, beginSceneHistoryPauseSession, getSceneHistoryPauseDepth, isRestoringSceneHistory, notifySceneCommit, pauseSceneHistory, resetSceneHistoryPauseDepth, resumeSceneHistory, runAsRemoteSceneChange, runAsSceneHistoryRestore, runWithSceneCommitNodeIds, } from './history-control.js';
+import { beginSceneHistoryDraft as beginSceneHistoryDraftIn, clearSceneHistoryDrafts, createdSceneHistoryDraftIds, hasSceneHistoryDrafts, noteSceneHistoryDraftWrite, sceneHistoryDraftRevertUpdates as sceneHistoryDraftRevertUpdatesIn, settleSceneHistoryDrafts, withAdoptedDraftsAsOriginal, withDraftsRestored, } from './history-drafts.js';
 import { getHistoryDirtyNodeIds } from './history-invalidation.js';
+import { retainSceneAnnotations, withoutSceneAnnotations, withoutSceneNodeAnnotations, writeSceneNodeField, } from './scene-annotations.js';
 import { invalidatePendingHydration, isHydrationNormalization, queueSceneNormalization, runSceneHydration, } from './scene-hydration.js';
 import useLiveNodeOverrides from './use-live-node-overrides.js';
 import useLiveTransforms from './use-live-transforms.js';
@@ -217,91 +226,6 @@ function migrateElevatorParent(id, node, nodes) {
         parentId: buildingId,
     };
 }
-// Reuse an already-minted scene material for an identical inline legacy
-// material so a whole building painted one custom colour collapses to one
-// shared datablock (mirrors `commitSlotPaint`'s dedupe-on-match).
-function findMintedSceneMaterialRef(material, mintedMaterials) {
-    const target = JSON.stringify(material);
-    for (const sceneMaterial of Object.values(mintedMaterials)) {
-        if (JSON.stringify(sceneMaterial.material) === target) {
-            return toSceneMaterialRef(sceneMaterial.id);
-        }
-    }
-    return undefined;
-}
-// Turn a legacy surface spec (`{ material, materialPreset }`) into a
-// `MaterialRef`: a preset that's already a `library:`/`scene:` ref is used
-// as-is; an inline material mints (or reuses) a scene material. Returns
-// undefined when the spec carries no material. Shared by every legacy→slots
-// migration below.
-function legacySpecToMaterialRef(spec, mintedMaterials) {
-    if (typeof spec.materialPreset === 'string' && parseMaterialRef(spec.materialPreset)) {
-        return spec.materialPreset;
-    }
-    if (spec.material !== undefined) {
-        const existing = findMintedSceneMaterialRef(spec.material, mintedMaterials);
-        if (existing)
-            return existing;
-        const id = generateSceneMaterialId();
-        mintedMaterials[id] = {
-            id,
-            name: `Material ${Object.keys(mintedMaterials).length + 1}`,
-            material: spec.material,
-        };
-        return toSceneMaterialRef(id);
-    }
-    return undefined;
-}
-// Move the retired inline `material*` / `interiorMaterial*` / `exteriorMaterial*`
-// fields onto the unified `node.slots` model (interior / exterior → a
-// `library:`/`scene:` ref), minting scene materials for inline customs into
-// `mintedMaterials` (merged into the scene material map by the caller). Already
-// slot-modelled walls and walls with no legacy material are left untouched.
-function migrateWallSurfaceMaterials(node, mintedMaterials) {
-    if (node.slots && (node.slots.interior !== undefined || node.slots.exterior !== undefined)) {
-        return node;
-    }
-    const slots = { ...(node.slots ?? {}) };
-    for (const side of ['interior', 'exterior']) {
-        const spec = getEffectiveWallSurfaceMaterial(node, side);
-        const ref = legacySpecToMaterialRef(spec, mintedMaterials);
-        if (ref)
-            slots[side] = ref;
-    }
-    if (Object.keys(slots).length === 0) {
-        return node;
-    }
-    return {
-        ...node,
-        slots,
-        material: undefined,
-        materialPreset: undefined,
-        interiorMaterial: undefined,
-        interiorMaterialPreset: undefined,
-        exteriorMaterial: undefined,
-        exteriorMaterialPreset: undefined,
-    };
-}
-// Move a kind's single legacy `material` / `materialPreset` onto its declared
-// slots. A pre-slot-model node painted one material rendered that material on
-// every part (each slot resolves `node.slots[slot]` → legacy → default), so the
-// migration writes the same ref to every slot id the kind can expose — unused
-// conditional slots are harmless. Already slot-modelled or unpainted nodes are
-// left untouched. Mirrors `migrateWallSurfaceMaterials` for single-surface and
-// whole-object kinds (slab, ceiling, fence, column, shelf).
-function migrateSingleMaterialSlots(node, slotIds, mintedMaterials) {
-    if (node.slots && Object.keys(node.slots).length > 0) {
-        return node;
-    }
-    const ref = legacySpecToMaterialRef({ material: node.material, materialPreset: node.materialPreset }, mintedMaterials);
-    if (!ref) {
-        return node;
-    }
-    const slots = {};
-    for (const slotId of slotIds)
-        slots[slotId] = ref;
-    return { ...node, slots, material: undefined, materialPreset: undefined };
-}
 function migrateRoleMaterialSlots(node, roles, mintedMaterials) {
     const slots = { ...(node.slots ?? {}) };
     const next = { ...node };
@@ -509,22 +433,6 @@ function migrateConstructionDimension(node) {
         }),
     };
 }
-function migrateWallAssembly(node) {
-    if (!Object.hasOwn(node, 'assemblyLayers'))
-        return node;
-    const assemblyThickness = Array.isArray(node.assemblyLayers)
-        ? node.assemblyLayers.reduce((total, layer) => {
-            if (!(layer && typeof layer === 'object'))
-                return total;
-            const thickness = layer.thickness;
-            return typeof thickness === 'number' && Number.isFinite(thickness) && thickness > 0
-                ? total + thickness
-                : total;
-        }, 0)
-        : 0;
-    const { assemblyLayers: _assemblyLayers, ...wall } = node;
-    return assemblyThickness > 0 ? { ...wall, thickness: assemblyThickness } : wall;
-}
 function migrateBlockRename(id, node, nodes) {
     if (node.type !== 'custom-mesh')
         return [id, node];
@@ -561,7 +469,7 @@ function migrateBlockHostedItem(node) {
 function migrateNodes(nodes) {
     // Repair pre-existing corruption (null children, zero-length walls) before
     // any per-type migration runs, so already-saved scenes load cleanly.
-    const { nodes: healed } = healSceneNodes(nodes);
+    const { nodes: healed } = healSceneNodes(normalizeLegacyStructure(nodes));
     const { nodes: patchedNodes } = removeRetiredDrawingSheetNodes(healed);
     // Scene materials minted while moving legacy wall fields onto `node.slots`;
     // merged into the scene material map by the caller (`setScene`).
@@ -706,7 +614,7 @@ function migrateNodes(nodes) {
             }
         }
         if (node.type === 'wall') {
-            patchedNodes[id] = migrateWallSurfaceMaterials(migrateWallAssembly(patchedNodes[id]), mintedMaterials);
+            patchedNodes[id] = migrateWallSurfaceMaterials(patchedNodes[id], mintedMaterials);
         }
         // Cabinet v2→v3: node-level `doorStyle` was dead (geometry reads only the
         // per-compartment `doorType`) and was removed from both cabinet schemas;
@@ -822,30 +730,6 @@ function migrateNodes(nodes) {
         if (node.type === 'roof') {
             patchedNodes[id] = migrateRoofSurfaceMaterials(patchedNodes[id]);
         }
-        // Legacy: site.children used to hold nested BuildingNode / ItemNode
-        // objects (see the SiteNode schema before the children-as-ids fix).
-        // Flatten any leftover nested children into ids, and absorb the
-        // embedded nodes into the flat map so the rest of the loader can
-        // treat the site like every other parent.
-        if (node.type === 'site' && Array.isArray(node.children)) {
-            let needsFlatten = false;
-            const flattened = [];
-            for (const child of node.children) {
-                if (typeof child === 'string') {
-                    flattened.push(child);
-                }
-                else if (child && typeof child === 'object' && typeof child.id === 'string') {
-                    needsFlatten = true;
-                    flattened.push(child.id);
-                    if (!patchedNodes[child.id]) {
-                        patchedNodes[child.id] = { ...child, parentId: id };
-                    }
-                }
-            }
-            if (needsFlatten) {
-                patchedNodes[id] = { ...node, children: flattened };
-            }
-        }
         // Level children normalization.
         // Pre-0.9.1 JSONs may carry child IDs that no longer exist in the node
         // map (e.g. elevator IDs that lived under a level before the elevator
@@ -898,8 +782,28 @@ function migrateNodes(nodes) {
             patchedNodes[id] = normalized;
         }
     }
-    const vertical = migrateVerticalSceneNodes(patchedNodes);
-    return { nodes: vertical.nodes, mintedMaterials };
+    const walls = migrateLegacyWallAssemblies(patchedNodes);
+    const vertical = migrateVerticalSceneNodes(walls.nodes);
+    const rooms = migrateRoomZones(vertical.nodes);
+    const ceilings = migrateCeilingRoomLinks(rooms.nodes);
+    const legacyOpeningsPrepared = Object.values(ceilings.nodes).some((value) => {
+        const node = value;
+        return node.type === 'slab' && node.autoFromWalls && !node.plateRole;
+    }) &&
+        Object.values(ceilings.nodes).some((value) => {
+            const node = value;
+            return node.type === 'stair' || node.type === 'elevator';
+        });
+    const plates = migrateFloorPlates(materializeLegacyAutoOpenings(ceilings.nodes, true));
+    const slots = migrateSlabSlots(plates.nodes);
+    const openings = ensureSceneOpenings(slots.nodes).nodes;
+    // M1 before M2: bands move onto geometric faces, then become paint regions.
+    const wallFaces = migrateWallFaceKeys(openings);
+    const structure = reconcileStructureOnLoad(migrateWallFaceBands(wallFaces.nodes).nodes, vertical.nodes, { legacyOpeningsPrepared });
+    return {
+        nodes: materializeNodeDefaults(structure.nodes).nodes,
+        mintedMaterials,
+    };
 }
 function getNodeChildIds(node) {
     if (!('children' in node && Array.isArray(node.children))) {
@@ -949,23 +853,36 @@ function collectReachableNodeIds(nodes, rootNodeIds) {
     }
     return reachable;
 }
-function sceneHistorySnapshotFromState(state) {
-    const { nodes, rootNodeIds, collections, materials, installedPlugins } = state;
-    // Fresh placement nodes are renderable drafts, not document history. Excluding their
-    // entire subtree here protects both local undo and external commit subscribers.
-    const transientNodeIds = new Set();
-    for (const node of Object.values(nodes)) {
-        const metadata = node.metadata;
-        if (metadata &&
-            typeof metadata === 'object' &&
-            !Array.isArray(metadata) &&
-            metadata.isNew === true) {
-            transientNodeIds.add(node.id);
-        }
-    }
-    if (transientNodeIds.size === 0) {
-        return { nodes, rootNodeIds, collections, materials, installedPlugins };
+/** Collection membership lives in `collection.nodeIds`; items alone mirror it in `collectionIds`. */
+function mirrorItemMembership(nodes, collectionId, nodeIds, member) {
+    let next = nodes;
+    for (const nodeId of nodeIds) {
+        const node = next[nodeId];
+        if (node?.type !== 'item')
+            continue;
+        const current = node.collectionIds ?? [];
+        if (current.includes(collectionId) === member)
+            continue;
+        if (next === nodes)
+            next = { ...nodes };
+        next[nodeId] = {
+            ...node,
+            collectionIds: member
+                ? [...current, collectionId]
+                : current.filter((id) => id !== collectionId),
+        };
     }
+    return next;
+}
+/**
+ * `parts` without the subtrees of `draftIds`, and without the references to them (children,
+ * procedural attachments, collections, roots). Returns `parts` itself when there is nothing to drop.
+ */
+function withoutDraftSubtrees(parts, draftIds) {
+    const { nodes, rootNodeIds, collections } = parts;
+    const transientNodeIds = new Set([...draftIds].filter((id) => Boolean(nodes[id])));
+    if (transientNodeIds.size === 0)
+        return parts;
     const childIdsByParentId = new Map();
     const addChild = (parentId, childId) => {
         const childIds = childIdsByParentId.get(parentId) ?? new Set();
@@ -990,36 +907,93 @@ function sceneHistorySnapshotFromState(state) {
             pendingIds.push(childId);
         }
     }
-    const historyNodes = {};
-    for (const [id, node] of Object.entries(nodes)) {
+    const documentNodes = {};
+    for (const [id, sourceNode] of Object.entries(nodes)) {
         if (transientNodeIds.has(id))
             continue;
+        let node = sourceNode;
+        if (node.type === 'procedural-item') {
+            let attachments;
+            for (const childId of transientNodeIds) {
+                if (!Object.hasOwn(node.attachments, childId))
+                    continue;
+                attachments ??= { ...node.attachments };
+                delete attachments[childId];
+            }
+            if (attachments)
+                node = { ...node, attachments };
+        }
         if (!('children' in node && Array.isArray(node.children))) {
-            historyNodes[id] = node;
+            documentNodes[id] = node;
             continue;
         }
         const children = node.children.filter((childId) => !transientNodeIds.has(childId));
-        historyNodes[id] =
+        documentNodes[id] =
             children.length === node.children.length ? node : { ...node, children };
     }
-    const historyCollections = {};
+    const documentCollections = {};
     for (const [id, collection] of Object.entries(collections)) {
         const nodeIds = collection.nodeIds.filter((nodeId) => !transientNodeIds.has(nodeId));
         if (collection.controlNodeId && transientNodeIds.has(collection.controlNodeId)) {
             const { controlNodeId: _controlNodeId, ...rest } = collection;
-            historyCollections[id] = { ...rest, nodeIds };
+            documentCollections[id] = { ...rest, nodeIds };
         }
         else {
-            historyCollections[id] =
+            documentCollections[id] =
                 nodeIds.length === collection.nodeIds.length ? collection : { ...collection, nodeIds };
         }
     }
     return {
-        nodes: historyNodes,
+        nodes: documentNodes,
         rootNodeIds: rootNodeIds.filter((id) => !transientNodeIds.has(id)),
-        collections: historyCollections,
+        collections: documentCollections,
+    };
+}
+function isFreshPlacementNode(node) {
+    const metadata = node.metadata;
+    return (!!metadata &&
+        typeof metadata === 'object' &&
+        !Array.isArray(metadata) &&
+        metadata.isNew === true);
+}
+/**
+ * Fresh placement nodes are renderable drafts, not document history. Excluding their entire
+ * subtree here protects both local undo and external commit subscribers. Carried drafts
+ * (history-drafts.ts) are kept out the same way.
+ */
+function sceneHistorySnapshotFromState(state) {
+    const { nodes, materials, installedPlugins, hasExplicitPluginInstallState } = state;
+    const kept = withoutDraftSubtrees(state, [
+        ...createdSceneHistoryDraftIds(),
+        ...Object.values(nodes)
+            .filter(isFreshPlacementNode)
+            .map((node) => node.id),
+    ]);
+    return {
+        nodes: withAdoptedDraftsAsOriginal(nodes, kept.nodes),
+        rootNodeIds: kept.rootNodeIds,
+        collections: kept.collections,
         materials,
         installedPlugins,
+        hasExplicitPluginInstallState,
+    };
+}
+/**
+ * The current scene as every save writes it: without the drafts an interaction is carrying —
+ * created carry drafts (history-drafts.ts) and the `drafts` the caller owns — and with adopted
+ * carry drafts as they were before the carry. Never inferred from metadata: committed nodes can
+ * still carry `metadata.isNew`, so only explicitly owned drafts are left out.
+ */
+export function getSceneDocument(drafts = []) {
+    const state = useScene.getState();
+    const kept = withoutDraftSubtrees(state, [...createdSceneHistoryDraftIds(), ...drafts]);
+    return {
+        nodes: withAdoptedDraftsAsOriginal(state.nodes, kept.nodes),
+        rootNodeIds: kept.rootNodeIds,
+        collections: kept.collections,
+        materials: state.materials,
+        installedPlugins: state.installedPlugins,
+        hasExplicitPluginInstallState: state.hasExplicitPluginInstallState,
     };
 }
 /**
@@ -1079,7 +1053,26 @@ function createSceneStore(config) {
     };
     return create()(hydratedConfig);
 }
-function runTemporalJump(target, jump) {
+function runTemporalJump(target, restore) {
+    const draftsBefore = useScene.getState().nodes;
+    const restoreDrafts = () => {
+        const current = useScene.getState().nodes;
+        const nodes = retainSceneAnnotations(draftsBefore, withDraftsRestored(draftsBefore, current) ?? current);
+        if (nodes === current)
+            return;
+        // The carry's own state, not a new step: a tracked write here would clear redo.
+        const pause = beginSceneHistoryPauseSession(useScene);
+        try {
+            useScene.setState({ nodes });
+        }
+        finally {
+            pause.end();
+        }
+    };
+    runTemporalJumpOnly(target, () => runAsSceneHistoryRestore(restore));
+    restoreDrafts();
+}
+function runTemporalJumpOnly(target, jump) {
     if (!target?.nodes) {
         jump();
         return;
@@ -1092,7 +1085,6 @@ function runTemporalJump(target, jump) {
         const next = target.nodes[nodeId];
         if (previous === next)
             continue;
-        // Structural hierarchy changes keep the full-level reconciliation fallback.
         if ([previous, next].some((node) => node && ['site', 'building', 'level'].includes(node.type))) {
             jump();
             return;
@@ -1147,9 +1139,9 @@ const useScene = createSceneStore(temporal((set, get) => ({
     setScene: (nodes, rootNodeIds, extra) => {
         // Apply backward compatibility migrations
         const { nodes: patchedNodes, mintedMaterials } = migrateNodes(nodes);
-        // Scene materials minted by the wall legacy→slots migration join the
-        // loaded palette (existing refs win on id collision — there are none,
-        // ids are freshly generated).
+        // Scene materials minted by the legacy→slots migrations join the
+        // loaded palette. Their ids are content-derived, so an existing entry
+        // with the same id (the hosted authority minted it) is the same material.
         const materials = { ...mintedMaterials, ...(extra?.materials ?? {}) };
         // Remove orphans: nodes whose parentId points to a non-existent node
         const cleanedNodes = { ...patchedNodes };
@@ -1186,37 +1178,22 @@ const useScene = createSceneStore(temporal((set, get) => ({
                 installedPlugins: Array.from(new Set(extra?.installedPlugins ?? [])),
                 hasExplicitPluginInstallState: extra?.hasExplicitPluginInstallState ?? false,
             });
-            const applyNormalization = (updates) => {
-                if (updates.length > 0)
-                    get().updateNodes(updates);
-            };
-            const hydratedNodes = Object.values(get().nodes);
-            if (!get().readOnly) {
-                pauseSceneHistory(useScene);
-                try {
-                    if (hydratedNodes.some((node) => node.type === 'elevator')) {
-                        applyNormalization(syncAutoElevatorOpenings(get().nodes));
+            if (!get().readOnly &&
+                Object.values(get().nodes).some((node) => node.type === 'stair')) {
+                queueSceneNormalization(() => {
+                    if (get().hydrationId !== hydrationId)
+                        return;
+                    const { updates } = ensureSceneOpenings(get().nodes);
+                    if (!updates.length)
+                        return;
+                    pauseSceneHistory(useScene);
+                    try {
+                        get().updateNodes(updates);
                     }
-                }
-                finally {
-                    resumeSceneHistory(useScene);
-                }
-                if (hydratedNodes.some((node) => node.type === 'stair')) {
-                    // Spatial-grid subscribers must settle first. Owning this pass
-                    // here also covers opening systems that mount after the load.
-                    queueSceneNormalization(() => {
-                        if (get().hydrationId !== hydrationId)
-                            return;
-                        pauseSceneHistory(useScene);
-                        try {
-                            applyNormalization(syncStairRises(get().nodes));
-                            applyNormalization(syncAutoStairOpenings(get().nodes));
-                        }
-                        finally {
-                            resumeSceneHistory(useScene);
-                        }
-                    });
-                }
+                    finally {
+                        resumeSceneHistory(useScene);
+                    }
+                });
             }
             // Mark all nodes as dirty to trigger re-validation
             Object.values(get().nodes).forEach((node) => {
@@ -1269,7 +1246,7 @@ const useScene = createSceneStore(temporal((set, get) => ({
             parentId: building.id,
             level: 0,
             children: [],
-            height: 2.5,
+            height: DEFAULT_LEVEL_HEIGHT,
         });
         // Define all nodes flat
         const nodes = {
@@ -1291,33 +1268,24 @@ const useScene = createSceneStore(temporal((set, get) => ({
     clearDirty: (id) => {
         get().dirtyNodes.delete(id);
     },
-    createNodes: (ops) => nodeActions.createNodesAction(set, get, ops),
-    createNode: (node, parentId) => nodeActions.createNodesAction(set, get, [{ node, parentId }]),
-    applyNodeChanges: (changes) => nodeActions.applyNodeChangesAction(set, get, changes),
-    updateNodes: (updates) => nodeActions.updateNodesAction(set, get, updates),
-    updateNode: (id, data) => nodeActions.updateNodesAction(set, get, [{ id, data }]),
+    createNodes: (ops, options) => nodeActions.createNodesAction(set, get, ops, options),
+    createNode: (node, parentId, options) => nodeActions.createNodesAction(set, get, [{ node, parentId }], options),
+    applyNodeChanges: (changes, options) => nodeActions.applyNodeChangesAction(set, get, changes, options),
+    updateNodes: (updates, options) => nodeActions.updateNodesAction(set, get, updates, options),
+    updateNode: (id, data, options) => nodeActions.updateNodesAction(set, get, [{ id, data }], options),
+    detachDerivedNode: (id, data) => nodeActions.detachDerivedNodeAction(set, get, id, data),
     // --- DELETE ---
-    deleteNodes: (ids) => nodeActions.deleteNodesAction(set, get, ids),
-    deleteNode: (id) => nodeActions.deleteNodesAction(set, get, [id]),
+    deleteNodes: (ids, options) => nodeActions.deleteNodesAction(set, get, ids, options),
+    deleteNode: (id, options) => nodeActions.deleteNodesAction(set, get, [id], options),
     // --- COLLECTIONS ---
     createCollection: (name, nodeIds = []) => {
         if (get().readOnly)
             return '';
         const id = generateCollectionId();
-        const collection = { id, name, nodeIds };
-        set((state) => {
-            const nextCollections = { ...state.collections, [id]: collection };
-            // Denormalize: stamp collectionId onto each node
-            const nextNodes = { ...state.nodes };
-            for (const nodeId of nodeIds) {
-                const node = nextNodes[nodeId];
-                if (!node)
-                    continue;
-                const existing = ('collectionIds' in node ? node.collectionIds : undefined) ?? [];
-                nextNodes[nodeId] = { ...node, collectionIds: [...existing, id] };
-            }
-            return { collections: nextCollections, nodes: nextNodes };
-        });
+        set((state) => ({
+            collections: { ...state.collections, [id]: { id, name, nodeIds: [...nodeIds] } },
+            nodes: mirrorItemMembership(state.nodes, id, nodeIds, true),
+        }));
         return id;
     },
     deleteCollection: (id) => {
@@ -1327,18 +1295,10 @@ const useScene = createSceneStore(temporal((set, get) => ({
             const col = state.collections[id];
             const nextCollections = { ...state.collections };
             delete nextCollections[id];
-            // Remove collectionId from all member nodes
-            const nextNodes = { ...state.nodes };
-            for (const nodeId of col?.nodeIds ?? []) {
-                const node = nextNodes[nodeId];
-                if (!(node && 'collectionIds' in node))
-                    continue;
-                nextNodes[nodeId] = {
-                    ...node,
-                    collectionIds: node.collectionIds.filter((cid) => cid !== id),
-                };
-            }
-            return { collections: nextCollections, nodes: nextNodes };
+            return {
+                collections: nextCollections,
+                nodes: mirrorItemMembership(state.nodes, id, col?.nodeIds ?? [], false),
+            };
         });
     },
     updateCollection: (id, data) => {
@@ -1351,50 +1311,38 @@ const useScene = createSceneStore(temporal((set, get) => ({
             return { collections: { ...state.collections, [id]: { ...col, ...data } } };
         });
     },
-    addToCollection: (id, nodeId) => {
+    addToCollection: (id, nodeIds) => {
         if (get().readOnly)
             return;
         set((state) => {
             const col = state.collections[id];
-            if (!col || col.nodeIds.includes(nodeId))
+            const added = nodeIds.filter((nodeId) => !col?.nodeIds.includes(nodeId));
+            if (!col || added.length === 0)
                 return state;
-            const nextCollections = {
-                ...state.collections,
-                [id]: { ...col, nodeIds: [...col.nodeIds, nodeId] },
-            };
-            const node = state.nodes[nodeId];
-            if (!node)
-                return { collections: nextCollections };
-            const existing = ('collectionIds' in node ? node.collectionIds : undefined) ?? [];
-            const nextNodes = {
-                ...state.nodes,
-                [nodeId]: { ...node, collectionIds: [...existing, id] },
+            return {
+                collections: {
+                    ...state.collections,
+                    [id]: { ...col, nodeIds: [...col.nodeIds, ...added] },
+                },
+                nodes: mirrorItemMembership(state.nodes, id, added, true),
             };
-            return { collections: nextCollections, nodes: nextNodes };
         });
     },
-    removeFromCollection: (id, nodeId) => {
+    removeFromCollection: (id, nodeIds) => {
         if (get().readOnly)
             return;
         set((state) => {
             const col = state.collections[id];
-            if (!col)
+            const removed = nodeIds.filter((nodeId) => col?.nodeIds.includes(nodeId));
+            if (!col || removed.length === 0)
                 return state;
-            const nextCollections = {
-                ...state.collections,
-                [id]: { ...col, nodeIds: col.nodeIds.filter((n) => n !== nodeId) },
-            };
-            const node = state.nodes[nodeId];
-            if (!(node && 'collectionIds' in node))
-                return { collections: nextCollections };
-            const nextNodes = {
-                ...state.nodes,
-                [nodeId]: {
-                    ...node,
-                    collectionIds: node.collectionIds.filter((cid) => cid !== id),
+            return {
+                collections: {
+                    ...state.collections,
+                    [id]: { ...col, nodeIds: col.nodeIds.filter((nodeId) => !removed.includes(nodeId)) },
                 },
+                nodes: mirrorItemMembership(state.nodes, id, removed, false),
             };
-            return { collections: nextCollections, nodes: nextNodes };
         });
     },
     // --- SCENE MATERIALS ---
@@ -1426,7 +1374,7 @@ const useScene = createSceneStore(temporal((set, get) => ({
     },
 }), {
     partialize: (state) => sceneHistorySnapshotFromState(state),
-    equality: (pastState, currentState) => areSceneSnapshotsEqual(pastState, currentState),
+    equality: (pastState, currentState) => areSceneSnapshotsEqual({ ...pastState, nodes: withoutSceneAnnotations(pastState.nodes) }, { ...currentState, nodes: withoutSceneAnnotations(currentState.nodes) }),
     onSave: (pastState, currentState) => {
         notifySceneCommit({
             origin: 'local',
@@ -1455,6 +1403,23 @@ const invalidateForLiveState = () => {
 useLiveNodeOverrides.subscribe(invalidateForLiveState);
 useLiveTransforms.subscribe(invalidateForLiveState);
 useScene.subscribe(invalidateForLiveState);
+// Systems rebuild a node's geometry only when it is dirty, so a preview that
+// drops its override without marking the node left it drawn at the preview
+// (a cancelled wall move's floor still pushed out). Whoever clears an
+// override, or one of its fields, the node rebuilds from the scene.
+useLiveNodeOverrides.subscribe(function markClearedOverridesDirty(state, previous) {
+    if (state.overrides === previous.overrides)
+        return;
+    let scene = null;
+    for (const [id, before] of previous.overrides) {
+        const after = state.overrides.get(id);
+        if (after === before || (after && Object.keys(before).every((key) => key in after)))
+            continue;
+        scene ??= useScene.getState();
+        if (scene.nodes[id])
+            scene.markDirty(id);
+    }
+});
 export default useScene;
 let sceneReadOnlyLeaseCount = 0;
 let sceneReadOnlyLeaseBaseline = false;
@@ -1511,7 +1476,8 @@ function sceneOperationPatchHasLiveConflict(beforeState, changes) {
     return false;
 }
 function areScenePatchValuesEqual(left, right) {
-    if (Object.is(left, right))
+    // Compensation crosses JSON, which serializes both signed zeros as 0.
+    if (left === right)
         return true;
     if (typeof left !== typeof right || left === null || right === null)
         return false;
@@ -1525,8 +1491,10 @@ function areScenePatchValuesEqual(left, right) {
         return false;
     const leftRecord = left;
     const rightRecord = right;
-    const leftKeys = Object.keys(leftRecord);
-    if (leftKeys.length !== Object.keys(rightRecord).length)
+    // Recorded compensation nodes have crossed JSON, which omits undefined properties.
+    const leftKeys = Object.keys(leftRecord).filter((key) => leftRecord[key] !== undefined);
+    const rightKeys = Object.keys(rightRecord).filter((key) => rightRecord[key] !== undefined);
+    if (leftKeys.length !== rightKeys.length)
         return false;
     return leftKeys.every((key) => Object.hasOwn(rightRecord, key) &&
         areScenePatchValuesEqual(leftRecord[key], rightRecord[key]));
@@ -1605,7 +1573,7 @@ function sceneOperationPatchNextState(beforeState, changes) {
             !Number.isSafeInteger(change.position) ||
             change.position < 0 ||
             siblings?.[change.position] !== id ||
-            !areScenePatchValuesEqual(current, change.node)) {
+            !areScenePatchValuesEqual(withoutSceneNodeAnnotations(current), withoutSceneNodeAnnotations(change.node))) {
             return null;
         }
         deleteIds.add(id);
@@ -1614,11 +1582,6 @@ function sceneOperationPatchNextState(beforeState, changes) {
         if (deleteIds.has(id))
             return null;
     }
-    for (const node of Object.values(beforeState.nodes)) {
-        const parentId = node.parentId ?? null;
-        if (parentId && deleteIds.has(parentId) && !deleteIds.has(node.id))
-            return null;
-    }
     const nextNodes = { ...beforeState.nodes };
     let nextRootNodeIds = deleteIds.size > 0
         ? beforeState.rootNodeIds.filter((id) => !deleteIds.has(id))
@@ -1653,8 +1616,7 @@ function sceneOperationPatchNextState(beforeState, changes) {
         if (!parent)
             return null;
         if (createIds.has(parentId)) {
-            if (!('children' in parent) ||
-                !Array.isArray(parent.children) ||
+            if (!('children' in parent && Array.isArray(parent.children)) ||
                 parent.children[change.position] !== change.node.id) {
                 return null;
             }
@@ -1664,6 +1626,66 @@ function sceneOperationPatchNextState(beforeState, changes) {
         placements.push(change);
         existingParentCreates.set(parentId, placements);
     }
+    for (const { id, data, removeFields } of changes.nodeUpdates) {
+        const node = nextNodes[id];
+        if (!node ||
+            createIds.has(id) ||
+            deleteIds.has(id) ||
+            updateIds.has(id) ||
+            ('id' in data && data.id !== node.id) ||
+            ('type' in data && data.type !== node.type) ||
+            ('object' in data && data.object !== node.object) ||
+            removeFields.some((field) => field === 'id' || field === 'object' || field === 'type' || Object.hasOwn(data, field))) {
+            return null;
+        }
+        updateIds.add(id);
+        let candidate = { ...node };
+        for (const [field, value] of Object.entries(data)) {
+            const written = writeSceneNodeField(candidate, field, value, true);
+            if (!written)
+                return null;
+            candidate = written;
+        }
+        for (const field of removeFields) {
+            const written = writeSceneNodeField(candidate, field, undefined, false);
+            if (!written)
+                return null;
+            candidate = written;
+        }
+        const validated = parseSceneOperationPatchNode(candidate);
+        if (!validated ||
+            validated.id !== id ||
+            validated.type !== node.type ||
+            validated.object !== node.object) {
+            return null;
+        }
+        nextNodes[id] = candidate;
+    }
+    for (const id of updateIds) {
+        const previousParent = beforeState.nodes[id]?.parentId;
+        const parentId = nextNodes[id]?.parentId;
+        if (previousParent === parentId)
+            continue;
+        if (previousParent) {
+            const parent = nextNodes[previousParent];
+            if (parent && 'children' in parent && Array.isArray(parent.children))
+                nextNodes[previousParent] = {
+                    ...parent,
+                    children: parent.children.filter((child) => child !== id),
+                };
+        }
+        else
+            nextRootNodeIds = nextRootNodeIds.filter((child) => child !== id);
+        if (parentId) {
+            const parent = nextNodes[parentId];
+            if (!(parent && 'children' in parent && Array.isArray(parent.children)))
+                return null;
+            if (!parent.children.includes(id))
+                nextNodes[parentId] = { ...parent, children: [...parent.children, id] };
+        }
+        else if (!nextRootNodeIds.includes(id))
+            nextRootNodeIds = [...nextRootNodeIds, id];
+    }
     const insertedRoots = insertSceneStructuralPlacements(nextRootNodeIds, rootCreates);
     if (!insertedRoots)
         return null;
@@ -1677,6 +1699,10 @@ function sceneOperationPatchNextState(beforeState, changes) {
             return null;
         nextNodes[parentId] = { ...parent, children };
     }
+    for (const node of Object.values(nextNodes)) {
+        if (node.parentId && deleteIds.has(node.parentId))
+            return null;
+    }
     for (const change of parsedCreates) {
         const parentId = change.node.parentId ?? null;
         const siblings = structuralSiblingIds(nextNodes, nextRootNodeIds, parentId);
@@ -1689,31 +1715,6 @@ function sceneOperationPatchNextState(beforeState, changes) {
                 return null;
         }
     }
-    for (const { id, data, removeFields } of changes.nodeUpdates) {
-        const node = nextNodes[id];
-        if (!node ||
-            createIds.has(id) ||
-            deleteIds.has(id) ||
-            updateIds.has(id) ||
-            ('id' in data && data.id !== node.id) ||
-            ('type' in data && data.type !== node.type) ||
-            ('object' in data && data.object !== node.object) ||
-            removeFields.some((field) => field === 'id' || field === 'object' || field === 'type' || Object.hasOwn(data, field))) {
-            return null;
-        }
-        updateIds.add(id);
-        const candidate = { ...node, ...data };
-        for (const field of removeFields)
-            delete candidate[field];
-        const validated = parseSceneOperationPatchNode(candidate);
-        if (!validated ||
-            validated.id !== id ||
-            validated.type !== node.type ||
-            validated.object !== node.object) {
-            return null;
-        }
-        nextNodes[id] = candidate;
-    }
     const materials = changes.materialChanges.length > 0 ? { ...beforeState.materials } : beforeState.materials;
     for (const { id, material } of changes.materialChanges) {
         if (materialIds.has(id) ||
@@ -1726,16 +1727,87 @@ function sceneOperationPatchNextState(beforeState, changes) {
         else
             materials[id] = material;
     }
-    return { materials, nodes: nextNodes, rootNodeIds: nextRootNodeIds };
+    const collectionChanges = changes.collectionChanges ?? [];
+    const collections = collectionChanges.length > 0 ? { ...beforeState.collections } : beforeState.collections;
+    const collectionIds = new Set();
+    for (const { id, collection } of collectionChanges) {
+        if (collectionIds.has(id) || (collection !== null && collection.id !== id))
+            return null;
+        collectionIds.add(id);
+        if (collection === null)
+            delete collections[id];
+        else
+            collections[id] = collection;
+    }
+    const pluginChanges = changes.pluginChanges ?? [];
+    if (changes.pluginInstallState) {
+        return {
+            collections,
+            materials,
+            nodes: nextNodes,
+            rootNodeIds: nextRootNodeIds,
+            installedPlugins: [...changes.pluginInstallState.installedPlugins],
+            hasExplicitPluginInstallState: changes.pluginInstallState.explicit,
+        };
+    }
+    if (pluginChanges.length === 0) {
+        return { collections, materials, nodes: nextNodes, rootNodeIds: nextRootNodeIds };
+    }
+    const installedPlugins = new Set(beforeState.installedPlugins);
+    const pluginIds = new Set();
+    for (const { id, installed } of pluginChanges) {
+        if (!id || pluginIds.has(id))
+            return null;
+        pluginIds.add(id);
+        if (installed)
+            installedPlugins.add(id);
+        else
+            installedPlugins.delete(id);
+    }
+    return {
+        collections,
+        materials,
+        nodes: nextNodes,
+        rootNodeIds: nextRootNodeIds,
+        installedPlugins: Array.from(installedPlugins),
+        // A shared install list is a decision someone made, so hosts must not
+        // re-add their default plugins on top of it.
+        hasExplicitPluginInstallState: true,
+    };
 }
-export function applySceneOperationPatch(changes) {
+export function applySceneOperationPatch(changes, options = {}) {
     const beforeState = useScene.getState();
     if (changes.nodeUpdates.length === 0 &&
         changes.materialChanges.length === 0 &&
         changes.nodeCreates.length === 0 &&
-        changes.nodeDeletes.length === 0) {
+        changes.nodeDeletes.length === 0 &&
+        !changes.pluginChanges?.length &&
+        !changes.collectionChanges?.length &&
+        !changes.pluginInstallState) {
         return false;
     }
+    if (options.undoable &&
+        !(useScene.temporal.getState().isTracking &&
+            getSceneHistoryPauseDepth() === 0 &&
+            !hasSceneHistoryDrafts())) {
+        return false;
+    }
+    if (options.annotation &&
+        (options.undoable ||
+            beforeState.readOnly ||
+            !useScene.temporal.getState().isTracking ||
+            getSceneHistoryPauseDepth() > 0 ||
+            hasSceneHistoryDrafts()))
+        return false;
+    if (options.annotation &&
+        (changes.nodeCreates.length ||
+            changes.nodeDeletes.length ||
+            changes.materialChanges.length ||
+            changes.pluginChanges?.length ||
+            changes.collectionChanges?.length ||
+            changes.pluginInstallState ||
+            changes.nodeUpdates.some(({ data, removeFields }) => removeFields.length || Object.keys(data).some((field) => field !== 'source.images'))))
+        return false;
     if (sceneOperationPatchHasLiveConflict(beforeState, changes))
         return false;
     const next = sceneOperationPatchNextState(beforeState, changes);
@@ -1746,7 +1818,7 @@ export function applySceneOperationPatch(changes) {
     if (shouldScopeHistoryPause)
         pauseSceneHistory(useScene);
     try {
-        useScene.setState(next);
+        runAsRemoteSceneChange(() => useScene.setState(next));
     }
     finally {
         if (shouldScopeHistoryPause)
@@ -1765,6 +1837,12 @@ export function applySceneOperationPatch(changes) {
     }
     if (areSceneSnapshotsEqual(before, current))
         return false;
+    if (options.undoable) {
+        useScene.temporal.setState(({ pastStates }) => ({
+            pastStates: [...pastStates, before],
+            futureStates: [],
+        }));
+    }
     for (const id of touchedNodeIds) {
         if (current.nodes[id])
             currentState.markDirty(id);
@@ -1804,10 +1882,22 @@ export function applySceneOperationPatch(changes) {
                 currentState.markDirty(node.parentId);
         }
     }
+    if (changes.pluginChanges?.length || changes.pluginInstallState) {
+        for (const node of Object.values(current.nodes)) {
+            if (!getNodePluginId(node.type))
+                continue;
+            if (!isNodeKindEnabled(node.type, currentState.installedPlugins)) {
+                currentState.clearDirty(node.id);
+            }
+            else if (!isNodeKindEnabled(node.type, beforeState.installedPlugins)) {
+                currentState.markDirty(node.id);
+            }
+        }
+    }
     for (const { node } of changes.nodeDeletes)
         currentState.clearDirty(node.id);
     notifySceneCommit({
-        origin: 'host',
+        origin: options.annotation ? 'local' : 'host',
         before,
         current,
     });
@@ -1823,18 +1913,19 @@ export function applyScenePatch(changes) {
 export function applySceneSnapshot(snapshot, options) {
     const before = sceneHistorySnapshotFromState(useScene.getState());
     const temporalState = useScene.temporal.getState();
-    if (!temporalState.isTracking || getSceneHistoryPauseDepth() > 0) {
+    if (!temporalState.isTracking || getSceneHistoryPauseDepth() > 0 || hasSceneHistoryDrafts()) {
         throw new Error('Cannot replace the scene snapshot during an active interaction');
     }
     useLiveNodeOverrides.getState().clearAll();
     useLiveTransforms.getState().clearAll();
     pauseSceneHistory(useScene);
     try {
-        useScene.getState().setScene(snapshot.nodes, snapshot.rootNodeIds, {
+        runAsRemoteSceneChange(() => useScene.getState().setScene(snapshot.nodes, snapshot.rootNodeIds, {
             collections: snapshot.collections,
             installedPlugins: snapshot.installedPlugins,
+            hasExplicitPluginInstallState: options.explicitPluginInstallState,
             materials: snapshot.materials,
-        });
+        }));
         useScene.temporal.getState().clear();
     }
     finally {
@@ -1849,8 +1940,37 @@ export function applySceneSnapshot(snapshot, options) {
 // Track previous temporal state lengths for identifying history jumps
 let prevPastLength = 0;
 let prevFutureLength = 0;
+/**
+ * Runs one of a carry's own writes to its drafts (see history-drafts.ts) under a short pause,
+ * and marks the adopted drafts' fields it changed as carry-owned.
+ */
+export function runSceneHistoryDraftWrite(write) {
+    const before = useScene.getState().nodes;
+    const wasRawPaused = !useScene.temporal.getState().isTracking && getSceneHistoryPauseDepth() === 0;
+    const pause = beginSceneHistoryPauseSession(useScene);
+    try {
+        return write();
+    }
+    finally {
+        noteSceneHistoryDraftWrite(before, useScene.getState().nodes);
+        pause.end();
+        // Legacy movers can co-mount with the overlay without owning a counted pause.
+        if (wasRawPaused && getSceneHistoryPauseDepth() === 0)
+            useScene.temporal.getState().pause();
+    }
+}
+/** Updates that revert the fields a carry still holds on `ids` (see history-drafts.ts). */
+export function sceneHistoryDraftRevertUpdates(ids) {
+    return sceneHistoryDraftRevertUpdatesIn(useScene.getState().nodes, ids);
+}
+/** Registers a carried draft (see history-drafts.ts); returns the call that ends it. */
+export function beginSceneHistoryDraft(id, original) {
+    return beginSceneHistoryDraftIn(id, original, useScene.getState().nodes);
+}
+export { settleSceneHistoryDrafts };
 export function clearSceneHistory() {
     resetSceneHistoryPauseDepth();
+    clearSceneHistoryDrafts();
     // Resetting the pause-depth counter without resuming would strand the
     // temporal store in `isTracking: false` if a pause window was active when
     // the scene was (re)loaded — every edit after the load would then be
@@ -1870,10 +1990,13 @@ useScene.temporal.subscribe((state, previousState) => {
         return;
     const currentPastLength = state.pastStates.length;
     const currentFutureLength = state.futureStates.length;
+    // Only the store's own undo / redo jump history: a new edit after an undo also
+    // grows the past and drops the redo stack, and is not a redo.
     // Undo: futureStates increases (state moved from past to future)
     // Redo: pastStates increases while futureStates decreases (state moved from future to past)
-    const didUndo = currentFutureLength > prevFutureLength;
-    const didRedo = currentPastLength > prevPastLength && currentFutureLength < prevFutureLength;
+    const jumping = isRestoringSceneHistory();
+    const didUndo = jumping && currentFutureLength > prevFutureLength;
+    const didRedo = jumping && currentPastLength > prevPastLength && currentFutureLength < prevFutureLength;
     if (didUndo || didRedo) {
         // Capture both layouts before another synchronous jump can replace them.
         // The state pushed onto the opposite stack includes history-paused derived