@pascal-app/core 0.9.1 → 1.0.0-beta.1

package/dist/store/use-scene.js

@@ -1,18 +1,32 @@
 'use client';
 import { temporal } from 'zundo';
 import { create } from 'zustand';
+import { parseMaterialRef, toSceneMaterialRef } from '../material-library';
+import { getNodePluginId, isNodeKindEnabled, nodeRegistry } from '../registry/registry';
 import { BuildingNode } from '../schema';
 import { generateCollectionId } from '../schema/collections';
 import { DoorNode as DoorNodeSchema } from '../schema/nodes/door';
 import { ElevatorNode as ElevatorNodeSchema } from '../schema/nodes/elevator';
 import { LevelNode } from '../schema/nodes/level';
 import { getPitchFromActiveRoofHeight, } from '../schema/nodes/roof-segment';
+import { segmentPointToRoofWallFace } from '../schema/nodes/roof-segment-walls';
 import { ShelfNode as ShelfNodeSchema } from '../schema/nodes/shelf';
 import { SiteNode } from '../schema/nodes/site';
-import { StairNode as StairNodeSchema } from '../schema/nodes/stair';
+import { getEffectiveStairSurfaceMaterial, StairNode as StairNodeSchema, } from '../schema/nodes/stair';
 import { StairSegmentNode as StairSegmentNodeSchema } from '../schema/nodes/stair-segment';
+import { getEffectiveWallSurfaceMaterial } from '../schema/nodes/wall';
+import { WindowNode as WindowNodeSchema } from '../schema/nodes/window';
+import { generateSceneMaterialId, SceneMaterial, } from '../schema/scene-material';
+import { AnyNode as AnyNodeSchema } from '../schema/types';
+import { deriveLegacyLevelHeight } from '../services/level-height';
+import { getCeilingClampBound } from '../services/storey';
+import { computeWallSlabSupport } from '../systems/slab/slab-support';
+import { DEFAULT_WALL_HEIGHT } from '../systems/wall/wall-footprint';
+import { healSceneNodes } from '../utils/heal-scene-graph';
 import * as nodeActions from './actions/node-actions';
-import { resetSceneHistoryPauseDepth } from './history-control';
+import { areSceneSnapshotsEqual, getSceneHistoryPauseDepth, notifySceneCommit, pauseSceneHistory, resetSceneHistoryPauseDepth, resumeSceneHistory, } from './history-control';
+import useLiveNodeOverrides from './use-live-node-overrides';
+import useLiveTransforms from './use-live-transforms';
 function getFiniteNumber(value, fallback) {
     return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
 }
@@ -45,6 +59,7 @@ function getVector3(value, fallback) {
     ];
 }
 function normalizeStairNode(node) {
+    const hasTotalRise = 'totalRise' in node;
     const sanitized = {
         ...node,
         position: getVector3(node.position, [0, 0, 0]),
@@ -55,7 +70,7 @@ function normalizeStairNode(node) {
         slabOpeningMode: getEnumValue(node.slabOpeningMode, ['none', 'destination'], 'none'),
         openingOffset: getFiniteNumber(node.openingOffset, 0),
         width: getFiniteNumber(node.width, 1),
-        totalRise: getFiniteNumber(node.totalRise, 2.5),
+        totalRise: hasTotalRise ? getFiniteNumber(node.totalRise, 2.5) : undefined,
         stepCount: getFiniteNumber(node.stepCount, 10),
         thickness: getFiniteNumber(node.thickness, 0.25),
         fillToFloor: getBoolean(node.fillToFloor, true),
@@ -70,7 +85,15 @@ function normalizeStairNode(node) {
         children: getStringArray(node.children),
     };
     const parsed = StairNodeSchema.safeParse(sanitized);
-    return parsed.success ? parsed.data : null;
+    if (!parsed.success)
+        return null;
+    if (hasTotalRise)
+        return parsed.data;
+    // Absent `totalRise` means "rise derives from the storey height" and must
+    // survive the load: safeParse echoes the sanitized explicit-undefined key,
+    // which would flip `'totalRise' in node` checks — strip it back off.
+    const { totalRise: _totalRise, ...rest } = parsed.data;
+    return rest;
 }
 function normalizeStairSegmentNode(node) {
     const sanitized = {
@@ -93,6 +116,13 @@ function normalizeDoorNode(node) {
     const parsed = DoorNodeSchema.safeParse(node);
     return parsed.success ? { ...node, ...parsed.data } : null;
 }
+// Windows saved before a schema field existed (e.g. `columnRatios`/`rowRatios`/
+// `frameThickness`) load without it; the mesh builder then reads undefined and
+// throws every frame. Zod-parse on load so schema defaults land, like doors.
+function normalizeWindowNode(node) {
+    const parsed = WindowNodeSchema.safeParse(node);
+    return parsed.success ? { ...node, ...parsed.data } : null;
+}
 function normalizeShelfNode(node) {
     const sanitized = {
         ...node,
@@ -182,40 +212,127 @@ function migrateElevatorParent(id, node, nodes) {
         parentId: buildingId,
     };
 }
-function migrateWallSurfaceMaterials(node) {
-    const hasInterior = node.interiorMaterial !== undefined || typeof node.interiorMaterialPreset === 'string';
-    const hasExterior = node.exteriorMaterial !== undefined || typeof node.exteriorMaterialPreset === 'string';
-    const legacyFinish = {
-        material: node.material,
-        materialPreset: typeof node.materialPreset === 'string' ? node.materialPreset : undefined,
-    };
-    if (!(hasInterior || hasExterior)) {
-        if (legacyFinish.material === undefined && legacyFinish.materialPreset === undefined) {
-            return node;
+// 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 {
-            ...node,
-            interiorMaterial: legacyFinish.material,
-            interiorMaterialPreset: legacyFinish.materialPreset,
-            exteriorMaterial: legacyFinish.material,
-            exteriorMaterialPreset: legacyFinish.materialPreset,
-        };
     }
-    if (!hasInterior) {
-        return {
-            ...node,
-            interiorMaterial: node.exteriorMaterial,
-            interiorMaterialPreset: node.exteriorMaterialPreset,
-        };
+    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 (!hasExterior) {
-        return {
-            ...node,
-            exteriorMaterial: node.interiorMaterial,
-            exteriorMaterialPreset: node.interiorMaterialPreset,
+    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 };
+}
+// Stair carries per-role legacy fields (`treadMaterial*` / `sideMaterial*` /
+// `railingMaterial*`) plus a catch-all. Map each to its slot via the same
+// fallback chain the renderer uses (`getEffectiveStairSurfaceMaterial`):
+// tread→treads, side→body, railing→railing. Runs after
+// `migrateStairSurfaceMaterials` has normalised the legacy fields.
+function migrateStairSurfaceSlots(node, mintedMaterials) {
+    if (node.slots && Object.keys(node.slots).length > 0) {
+        return node;
+    }
+    const roleToSlot = [
+        ['tread', 'treads'],
+        ['side', 'body'],
+        ['railing', 'railing'],
+    ];
+    const slots = {};
+    for (const [role, slotId] of roleToSlot) {
+        const spec = getEffectiveStairSurfaceMaterial(node, role);
+        const ref = legacySpecToMaterialRef(spec, mintedMaterials);
+        if (ref)
+            slots[slotId] = ref;
+    }
+    if (Object.keys(slots).length === 0) {
+        return node;
     }
-    return node;
+    return {
+        ...node,
+        slots,
+        material: undefined,
+        materialPreset: undefined,
+        treadMaterial: undefined,
+        treadMaterialPreset: undefined,
+        sideMaterial: undefined,
+        sideMaterialPreset: undefined,
+        railingMaterial: undefined,
+        railingMaterialPreset: undefined,
+    };
 }
 function migrateStairSurfaceMaterials(node) {
     const hasRailing = node.railingMaterial !== undefined || typeof node.railingMaterialPreset === 'string';
@@ -333,8 +450,84 @@ function migrateRoofSurfaceMaterials(node) {
     }
     return next;
 }
+function migrateConstructionDimension(node) {
+    const drawingOverrides = Array.isArray(node.drawingOverrides) ? node.drawingOverrides : [];
+    const hasLegacyDrawingOverride = drawingOverrides.some((entry) => entry &&
+        typeof entry === 'object' &&
+        !Array.isArray(entry) &&
+        entry.presentation === 'reference');
+    if (!('reference' in node || 'referenceStyle' in node || hasLegacyDrawingOverride))
+        return node;
+    const { reference: _reference, referenceStyle: _referenceStyle, ...dimension } = node;
+    return {
+        ...dimension,
+        drawingOverrides: drawingOverrides.map((entry) => {
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+                return entry;
+            return entry.presentation === 'reference' ? { ...entry, presentation: 'shown' } : entry;
+        }),
+    };
+}
+function removeRetiredDrawingSheets(nodes) {
+    const retiredIds = new Set(Object.entries(nodes)
+        .filter(([, node]) => node?.type === 'drawing-sheet')
+        .map(([id]) => id));
+    if (retiredIds.size === 0)
+        return;
+    for (const id of retiredIds)
+        delete nodes[id];
+    for (const [id, node] of Object.entries(nodes)) {
+        if (!Array.isArray(node?.children))
+            continue;
+        const children = getStringArray(node.children);
+        if (!children.some((childId) => retiredIds.has(childId)))
+            continue;
+        nodes[id] = {
+            ...node,
+            children: children.filter((childId) => !retiredIds.has(childId)),
+        };
+    }
+}
+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;
+}
+// Walls whose top lands within this of the storey plane become plane-bound;
+// ceilings whose stored height lands within this of their clamp bound become
+// follows-mode (step 3f) — same census-backed threshold for both.
+// From a prod census: the 0.15-short "hole pattern" (default 2.5 walls next to
+// a taller wall) must snap to the plane, while intentional 0.20-short walls
+// (2.5 under a 2.7 plane, 2.3 under a 2.5 plane) must keep their explicit
+// height — hence 0.20 with a strictly-less-than comparison.
+const PLANE_BOUND_EPSILON = 0.2;
 function migrateNodes(nodes) {
-    const patchedNodes = { ...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 patchedNodes = { ...healed };
+    removeRetiredDrawingSheets(patchedNodes);
+    // Scene materials minted while moving legacy wall fields onto `node.slots`;
+    // merged into the scene material map by the caller (`setScene`).
+    const mintedMaterials = {};
+    // Pass 1: all node types except elevator.
+    // Elevator migration (migrateElevatorParent) mutates level.children to remove
+    // the elevator ID. If the elevator is processed before its parent level in
+    // Object.entries order, the level migration in this same pass would then see
+    // a children array that still contains the elevator ID and filter it out as
+    // "missing" — corrupting the level. Running elevators in a second pass after
+    // all levels are stable avoids the race entirely.
     for (const [id, node] of Object.entries(patchedNodes)) {
         // 1. Item scale migration
         if (node.type === 'item' && !('scale' in node)) {
@@ -410,11 +603,21 @@ function migrateNodes(nodes) {
                 patchedNodes[id] = normalized;
             }
         }
+        if (node.type === 'window') {
+            const normalized = normalizeWindowNode(node);
+            if (normalized) {
+                patchedNodes[id] = normalized;
+            }
+        }
+        if (node.type === 'construction-dimension') {
+            patchedNodes[id] = migrateConstructionDimension(node);
+        }
         if (node.type === 'stair') {
             const normalized = normalizeStairNode(migrateStairSurfaceMaterials(node));
             if (normalized) {
                 patchedNodes[id] = normalized;
             }
+            patchedNodes[id] = migrateStairSurfaceSlots(patchedNodes[id], mintedMaterials);
         }
         if (node.type === 'stair-segment') {
             const normalized = normalizeStairSegmentNode(node);
@@ -423,20 +626,52 @@ function migrateNodes(nodes) {
             }
         }
         if (node.type === 'wall') {
-            patchedNodes[id] = migrateWallSurfaceMaterials(patchedNodes[id]);
+            patchedNodes[id] = migrateWallSurfaceMaterials(migrateWallAssembly(patchedNodes[id]), mintedMaterials);
         }
-        if (node.type === 'shelf') {
-            const normalized = normalizeShelfNode(node);
-            if (normalized) {
-                patchedNodes[id] = normalized;
+        // Cabinet v2→v3: node-level `doorStyle` was dead (geometry reads only the
+        // per-compartment `doorType`) and was removed from both cabinet schemas;
+        // `handlePosition: 'edge'` behaved identically to 'auto' and was dropped
+        // from the enum; the compartment stack became a discriminated union that
+        // rejects a `cooktopLayout` mismatched to its gas/induction type (the old
+        // loose schema ignored it).
+        if (node.type === 'cabinet' || node.type === 'cabinet-module') {
+            const { doorStyle: _doorStyle, ...rest } = node;
+            const next = rest;
+            if (next.handlePosition === 'edge')
+                next.handlePosition = 'auto';
+            if (Array.isArray(next.stack)) {
+                next.stack = next.stack.map((compartment) => {
+                    if (!compartment || typeof compartment !== 'object')
+                        return compartment;
+                    const layout = compartment.cooktopLayout;
+                    if (typeof layout !== 'string')
+                        return compartment;
+                    if (compartment.type === 'cooktop-gas' && !layout.startsWith('gas-')) {
+                        return { ...compartment, cooktopLayout: 'gas-4burner' };
+                    }
+                    if (compartment.type === 'cooktop-induction' && !layout.startsWith('induction-')) {
+                        return { ...compartment, cooktopLayout: 'induction-4zone' };
+                    }
+                    return compartment;
+                });
             }
+            patchedNodes[id] = next;
+        }
+        if (node.type === 'slab' || node.type === 'ceiling') {
+            patchedNodes[id] = migrateSingleMaterialSlots(patchedNodes[id], ['surface'], mintedMaterials);
+        }
+        if (node.type === 'fence') {
+            patchedNodes[id] = migrateSingleMaterialSlots(patchedNodes[id], ['posts', 'infill', 'base', 'rail'], mintedMaterials);
+        }
+        if (node.type === 'column') {
+            patchedNodes[id] = migrateSingleMaterialSlots(patchedNodes[id], ['shaft', 'base', 'capital', 'frame'], mintedMaterials);
         }
-        if (node.type === 'elevator') {
-            const parentMigrated = migrateElevatorParent(id, node, patchedNodes);
-            const normalized = normalizeElevatorNode(parentMigrated);
+        if (node.type === 'shelf') {
+            const normalized = normalizeShelfNode(node);
             if (normalized) {
                 patchedNodes[id] = normalized;
             }
+            patchedNodes[id] = migrateSingleMaterialSlots(patchedNodes[id], ['shelves', 'frame', 'back'], mintedMaterials);
         }
         // Roof-segment hosting was added in this migration cycle (the same
         // pattern as shelf above). Older segments saved before the schema
@@ -449,6 +684,41 @@ function migrateNodes(nodes) {
         if (node.type === 'roof-segment' && !Array.isArray(node.children)) {
             patchedNodes[id] = { ...node, children: [] };
         }
+        // Roof-hosted wall children (door / window / item) originally stored
+        // SEGMENT-LOCAL positions with the face yaw in rotation[1]; the
+        // format moved to explicit `roofFace` + FACE-LOCAL coords so the
+        // renderer's face frame can track segment edits live. Convert in
+        // place: face from the old cardinal yaw, u/v from the outer-plane
+        // projection, z re-based from the outer plane to the wall mid-plane.
+        if ((node.type === 'door' || node.type === 'window' || node.type === 'item') &&
+            typeof node.roofSegmentId === 'string' &&
+            node.roofFace === undefined) {
+            const current = patchedNodes[id];
+            const segment = patchedNodes[current.roofSegmentId];
+            if (segment?.type === 'roof-segment') {
+                const tau = Math.PI * 2;
+                const yaw = (((current.rotation?.[1] ?? 0) % tau) + tau) % tau;
+                const eps = 1e-3;
+                const face = yaw < eps || tau - yaw < eps
+                    ? 'front'
+                    : Math.abs(yaw - Math.PI) < eps
+                        ? 'back'
+                        : Math.abs(yaw - Math.PI / 2) < eps
+                            ? 'right'
+                            : Math.abs(yaw - (3 * Math.PI) / 2) < eps
+                                ? 'left'
+                                : null;
+                if (face) {
+                    const { u, v, dist } = segmentPointToRoofWallFace(segment, face, current.position);
+                    patchedNodes[id] = {
+                        ...current,
+                        roofFace: face,
+                        position: [u, v, dist + (segment.wallThickness ?? 0.1) / 2],
+                        rotation: [0, 0, 0],
+                    };
+                }
+            }
+        }
         if (node.type === 'roof') {
             patchedNodes[id] = migrateRoofSurfaceMaterials(patchedNodes[id]);
         }
@@ -476,8 +746,200 @@ function migrateNodes(nodes) {
                 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
+        // parent migration moved them up to building). If those dangling IDs are
+        // left in place, collectReachableNodeIds marks the level as having
+        // reachable children that don't exist, which corrupts the scene graph
+        // traversal and leaves the LevelNode in a broken state — making floors
+        // impossible to drag or delete after import.
+        // We intentionally do NOT filter by type prefix here; being permissive
+        // about which types are allowed as children prevents data loss when new
+        // child types are added to the schema in the future.
+        if (node.type === 'level') {
+            const rawChildren = getStringArray(node.children);
+            const validChildren = rawChildren.filter((childId) => {
+                const exists = Boolean(patchedNodes[childId]);
+                if (!exists) {
+                    console.warn('[migrateNodes] level', id, 'references missing child', childId, '— dropping');
+                }
+                return exists;
+            });
+            const levelNumber = getFiniteNumber(node.level, 0);
+            patchedNodes[id] = {
+                ...node,
+                level: levelNumber,
+                children: validChildren,
+            };
+        }
+    }
+    // Pass 2: elevator migration.
+    // migrateElevatorParent mutates the parent level's children array (removes
+    // the elevator ID from it). Running this after Pass 1 guarantees that the
+    // level normalization above has already seen a clean children list — if we
+    // ran elevator migration inside Pass 1, the order of Object.entries
+    // iteration would be non-deterministic: processing an elevator before its
+    // parent level would mutate the level's children mid-iteration, potentially
+    // causing the level branch above to see a stale node reference.
+    for (const [id, node] of Object.entries(patchedNodes)) {
+        if (node.type !== 'elevator')
+            continue;
+        const parentMigrated = migrateElevatorParent(id, node, patchedNodes);
+        const normalized = normalizeElevatorNode(parentMigrated);
+        if (normalized) {
+            patchedNodes[id] = normalized;
+        }
+    }
+    // Pass 3: vertical building model.
+    // A level without `height` marks a scene saved before the vertical model
+    // landed. Computed before this pass mutates anything: the stair-rise
+    // cleanup below must never run on already-migrated scenes.
+    const isLegacyScene = Object.values(patchedNodes).some((node) => node?.type === 'level' && !('height' in node));
+    // 3a. Ordinal renumber — always runs, per building (idempotent
+    // self-healing; MCP's create-level historically wrote its elevation PARAM
+    // into the ordinal, so fractional/duplicate ordinals exist in the wild).
+    const buildingNodes = Object.values(patchedNodes).filter((node) => node?.type === 'building');
+    const levelsByBuilding = new Map();
+    for (const [id, node] of Object.entries(patchedNodes)) {
+        if (node?.type !== 'level')
+            continue;
+        // Mirrors the building resolution in services/storey.ts: an explicit
+        // parentId pointing at a building wins, membership in a building's
+        // children array is the legacy fallback, and unresolvable levels share
+        // one orphan bucket.
+        const buildingId = buildingNodes.find((building) => building.id === node.parentId)?.id ??
+            buildingNodes.find((building) => getStringArray(building.children).includes(id))?.id ??
+            null;
+        const bucket = levelsByBuilding.get(buildingId) ?? [];
+        bucket.push({ id, ordinal: getFiniteNumber(node.level, 0) });
+        levelsByBuilding.set(buildingId, bucket);
+    }
+    for (const bucket of levelsByBuilding.values()) {
+        // Anchored at zero on purpose: ordinals are semantic — `level < 0`
+        // renders "Basement N" and `level === 0` is the ground-floor default —
+        // so negatives compact upward toward −1 and non-negatives compact down
+        // to 0. A blind 0..n renumber would rename basements.
+        const sorted = [...bucket].sort((a, b) => a.ordinal - b.ordinal);
+        const negativeCount = sorted.filter((entry) => entry.ordinal < 0).length;
+        sorted.forEach((entry, index) => {
+            const nextOrdinal = index - negativeCount;
+            const current = patchedNodes[entry.id];
+            if (current.level !== nextOrdinal) {
+                patchedNodes[entry.id] = { ...current, level: nextOrdinal };
+            }
+        });
+    }
+    // 3b. Stored storey heights: materialize the legacy stacked height verbatim
+    // (never rounded or snapped — snapping would move existing buildings).
+    // All planes derive before any wall height below mutates.
+    const legacyLevelIds = Object.entries(patchedNodes)
+        .filter(([, node]) => node?.type === 'level' && !('height' in node))
+        .map(([id]) => id);
+    const derivedHeights = new Map();
+    for (const levelId of legacyLevelIds) {
+        derivedHeights.set(levelId, deriveLegacyLevelHeight(levelId, patchedNodes));
+    }
+    for (const levelId of legacyLevelIds) {
+        const plane = derivedHeights.get(levelId);
+        const level = patchedNodes[levelId];
+        patchedNodes[levelId] = { ...level, height: plane };
+        // 3c. Wall-top classification against the just-written plane, using the
+        // same slab-support election as deriveLegacyLevelHeight (call shape
+        // mirrored from services/level-height.ts). Walls whose top meets the
+        // plane drop their explicit height and follow the level from now on;
+        // walls ending short (or tall) keep an explicit height — materializing
+        // the 2.5 default onto absent-height walls that end short of the plane.
+        const children = getStringArray(level.children)
+            .map((childId) => patchedNodes[childId])
+            .filter((child) => child !== undefined);
+        const slabs = children.filter((child) => child.type === 'slab');
+        const walls = children.filter((child) => child.type === 'wall');
+        for (const wall of walls) {
+            const electedBase = computeWallSlabSupport({
+                start: wall.start,
+                end: wall.end,
+                curveOffset: wall.curveOffset,
+                thickness: wall.thickness,
+            }, slabs, walls).elevation;
+            const effectiveHeight = wall.height ?? DEFAULT_WALL_HEIGHT;
+            const top = Math.max(0, electedBase) + effectiveHeight;
+            if (Math.abs(plane - top) < PLANE_BOUND_EPSILON) {
+                if ('height' in wall) {
+                    const { height: _height, ...planeBound } = wall;
+                    patchedNodes[wall.id] = planeBound;
+                }
+            }
+            else {
+                patchedNodes[wall.id] = { ...wall, height: effectiveHeight };
+            }
+        }
+    }
+    // 3d. Stair rise: on legacy scenes a totalRise of exactly 2.5 is the old
+    // schema default, not a user choice — drop it so the rise derives from the
+    // storey height. Gated on isLegacyScene because on a post-migration scene
+    // a stored 2.5 IS a deliberately typed value and must survive reloads.
+    if (isLegacyScene) {
+        for (const [id, node] of Object.entries(patchedNodes)) {
+            if (node?.type !== 'stair')
+                continue;
+            if (node.totalRise !== 2.5)
+                continue;
+            const { totalRise: _totalRise, ...derivedRise } = node;
+            patchedNodes[id] = derivedRise;
+        }
+    }
+    // 3e. Slab placement/thickness split. `elevation` stays the walking surface;
+    // the new `thickness` grows downward so the solid occupies
+    // [elevation − thickness, elevation]. Legacy solids extruded [0, elevation],
+    // so thickness = elevation EXACTLY (including degenerate 0 — MIN_SLAB_THICKNESS
+    // applies to edits only, never here) keeps the occupied interval identical.
+    // Legacy pools (elevation < 0) become explicit `recessed` intent with
+    // elevation unchanged. Gated per slab on a missing `thickness` — the
+    // migration output is cast, so schema defaults never materialize on load.
+    for (const [id, node] of Object.entries(patchedNodes)) {
+        if (node?.type !== 'slab' || 'thickness' in node)
+            continue;
+        const elevation = getFiniteNumber(node.elevation, 0.05);
+        patchedNodes[id] =
+            elevation < 0
+                ? { ...node, thickness: 0.05, recessed: true }
+                : { ...node, thickness: elevation };
+    }
+    // 3f. Ceiling follows-mode classification (the ceiling mirror of 3c; runs
+    // after 3b/3e so the clamp bound sees stored level heights and split slab
+    // thicknesses). A stored ceiling height within PLANE_BOUND_EPSILON of its
+    // clamp bound (min(storey plane, covering-slab underside) − margin, via
+    // getCeilingClampBound) is the legacy default tracking the level top, not
+    // a choice — drop it so the ceiling follows the level from now on.
+    // autoFromWalls ceilings always convert: their height was derived by the
+    // space-detection sync, never user intent. Gated on isLegacyScene, which
+    // is exact — nothing shipped between the level-height migration and this
+    // one — and makes the step idempotent. Known accepted edge: a
+    // post-migration user typing a custom height exactly equal to the bound
+    // keeps it (the gate prevents re-classification on later loads).
+    if (isLegacyScene) {
+        for (const [id, node] of Object.entries(patchedNodes)) {
+            if (node?.type !== 'ceiling' || !('height' in node))
+                continue;
+            const dropHeight = () => {
+                const { height: _height, ...follows } = node;
+                patchedNodes[id] = follows;
+            };
+            if (node.autoFromWalls === true) {
+                dropHeight();
+                continue;
+            }
+            if (typeof node.parentId !== 'string')
+                continue;
+            const bound = getCeilingClampBound(node.parentId, patchedNodes, Array.isArray(node.polygon) ? node.polygon : []);
+            const stored = getFiniteNumber(node.height, Number.NaN);
+            if (Number.isFinite(bound) && Math.abs(stored - bound) < PLANE_BOUND_EPSILON) {
+                dropHeight();
+            }
+        }
     }
-    return patchedNodes;
+    return { nodes: patchedNodes, mintedMaterials };
 }
 function getNodeChildIds(node) {
     if (!('children' in node && Array.isArray(node.children))) {
@@ -527,6 +989,10 @@ function collectReachableNodeIds(nodes, rootNodeIds) {
     }
     return reachable;
 }
+function sceneHistorySnapshotFromState(state) {
+    const { nodes, rootNodeIds, collections, materials, installedPlugins } = state;
+    return { nodes, rootNodeIds, collections, materials, installedPlugins };
+}
 const useScene = create()(temporal((set, get) => ({
     // 1. Flat dictionary of all nodes
     nodes: {},
@@ -536,6 +1002,9 @@ const useScene = create()(temporal((set, get) => ({
     dirtyNodes: new Set(),
     // 4. Collections
     collections: {},
+    materials: {},
+    installedPlugins: [],
+    hasExplicitPluginInstallState: false,
     // 5. Read-only lock
     readOnly: false,
     setReadOnly: (readOnly) => set({ readOnly }),
@@ -545,15 +1014,25 @@ const useScene = create()(temporal((set, get) => ({
             rootNodeIds: [],
             dirtyNodes: new Set(),
             collections: {},
+            materials: {},
+            installedPlugins: [],
+            hasExplicitPluginInstallState: false,
         });
     },
     clearScene: () => {
+        const installedPlugins = get().installedPlugins;
+        const hasExplicitPluginInstallState = get().hasExplicitPluginInstallState;
         get().unloadScene();
         get().loadScene(); // Default scene
+        set({ installedPlugins, hasExplicitPluginInstallState });
     },
-    setScene: (nodes, rootNodeIds) => {
+    setScene: (nodes, rootNodeIds, extra) => {
         // Apply backward compatibility migrations
-        const patchedNodes = migrateNodes(nodes);
+        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).
+        const materials = { ...mintedMaterials, ...(extra?.materials ?? {}) };
         // Remove orphans: nodes whose parentId points to a non-existent node
         const cleanedNodes = { ...patchedNodes };
         for (const node of Object.values(cleanedNodes)) {
@@ -562,12 +1041,6 @@ const useScene = create()(temporal((set, get) => ({
                 delete cleanedNodes[node.id];
             }
         }
-        set({
-            nodes: cleanedNodes,
-            rootNodeIds,
-            dirtyNodes: new Set(),
-            collections: {},
-        });
         const normalizedRootNodeIds = normalizeRootNodeIds(cleanedNodes, rootNodeIds);
         const reachableNodeIds = collectReachableNodeIds(cleanedNodes, normalizedRootNodeIds);
         if (normalizedRootNodeIds.length > 0) {
@@ -578,17 +1051,47 @@ const useScene = create()(temporal((set, get) => ({
                 delete cleanedNodes[node.id];
             }
         }
+        // Single tracked `set`: with zundo, every tracked write pushes the
+        // pre-write state onto `pastStates`. Writing the scene in two steps
+        // (as this used to) exposed a half-normalized intermediate state —
+        // and the pre-load (possibly empty) state — as undo targets.
         set({
             nodes: cleanedNodes,
             rootNodeIds: normalizedRootNodeIds,
             dirtyNodes: new Set(),
-            collections: {},
+            collections: extra?.collections ?? {},
+            materials,
+            installedPlugins: Array.from(new Set(extra?.installedPlugins ?? [])),
+            hasExplicitPluginInstallState: extra?.hasExplicitPluginInstallState ?? false,
         });
         // Mark all nodes as dirty to trigger re-validation
         Object.values(cleanedNodes).forEach((node) => {
             get().markDirty(node.id);
         });
     },
+    setInstalledPlugins: (pluginIds, options) => {
+        if (get().readOnly)
+            return;
+        const nextInstalledPlugins = Array.from(new Set(pluginIds));
+        const previousInstalledPlugins = get().installedPlugins;
+        const dirtyNodes = new Set(get().dirtyNodes);
+        for (const node of Object.values(get().nodes)) {
+            if (!getNodePluginId(node.type))
+                continue;
+            if (!isNodeKindEnabled(node.type, nextInstalledPlugins)) {
+                dirtyNodes.delete(node.id);
+            }
+            else if (!isNodeKindEnabled(node.type, previousInstalledPlugins)) {
+                if (nodeRegistry.get(node.type)?.dirtyTracking !== false)
+                    dirtyNodes.add(node.id);
+            }
+        }
+        set({
+            installedPlugins: nextInstalledPlugins,
+            hasExplicitPluginInstallState: options?.explicit ?? get().hasExplicitPluginInstallState,
+            dirtyNodes,
+        });
+    },
     loadScene: () => {
         if (get().rootNodeIds.length > 0) {
             // Assign all nodes as dirty to force re-validation
@@ -601,6 +1104,7 @@ const useScene = create()(temporal((set, get) => ({
         const level0 = LevelNode.parse({
             level: 0,
             children: [],
+            height: 2.5,
         });
         const building = BuildingNode.parse({
             children: [level0.id],
@@ -619,6 +1123,11 @@ const useScene = create()(temporal((set, get) => ({
         set({ nodes, rootNodeIds });
     },
     markDirty: (id) => {
+        const node = get().nodes[id];
+        if (node && !isNodeKindEnabled(node.type, get().installedPlugins))
+            return;
+        if (node && nodeRegistry.get(node.type)?.dirtyTracking === false)
+            return;
         get().dirtyNodes.add(id);
     },
     clearDirty: (id) => {
@@ -730,20 +1239,448 @@ const useScene = create()(temporal((set, get) => ({
             return { collections: nextCollections, nodes: nextNodes };
         });
     },
+    // --- SCENE MATERIALS ---
+    addSceneMaterial: (material) => {
+        if (get().readOnly)
+            return;
+        set((state) => ({
+            materials: { ...state.materials, [material.id]: material },
+        }));
+    },
+    updateSceneMaterial: (id, data) => {
+        if (get().readOnly)
+            return;
+        set((state) => {
+            const material = state.materials[id];
+            if (!material)
+                return state;
+            return { materials: { ...state.materials, [id]: { ...material, ...data } } };
+        });
+    },
+    removeSceneMaterial: (id) => {
+        if (get().readOnly)
+            return;
+        set((state) => {
+            const materials = { ...state.materials };
+            delete materials[id];
+            return { materials };
+        });
+    },
 }), {
-    partialize: (state) => {
-        const { nodes, rootNodeIds, collections } = state;
-        return { nodes, rootNodeIds, collections };
+    partialize: (state) => sceneHistorySnapshotFromState(state),
+    equality: (pastState, currentState) => areSceneSnapshotsEqual(pastState, currentState),
+    onSave: (pastState, currentState) => {
+        notifySceneCommit({
+            origin: 'local',
+            before: sceneHistorySnapshotFromState(pastState),
+            current: sceneHistorySnapshotFromState(currentState),
+        });
     },
     limit: 50, // Limit to last 50 actions
 }));
 export default useScene;
+let sceneReadOnlyLeaseCount = 0;
+let sceneReadOnlyLeaseBaseline = false;
+export function acquireSceneReadOnlyLease() {
+    if (sceneReadOnlyLeaseCount === 0) {
+        sceneReadOnlyLeaseBaseline = useScene.getState().readOnly;
+    }
+    sceneReadOnlyLeaseCount += 1;
+    useScene.setState({ readOnly: true });
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        sceneReadOnlyLeaseCount = Math.max(0, sceneReadOnlyLeaseCount - 1);
+        if (sceneReadOnlyLeaseCount > 0)
+            return;
+        useScene.setState({ readOnly: sceneReadOnlyLeaseBaseline });
+        sceneReadOnlyLeaseBaseline = false;
+    };
+}
+function sceneOperationPatchLiveConflictIds(beforeState, changes) {
+    const ids = new Set();
+    const addNodeAndParent = (node) => {
+        if (!node)
+            return;
+        ids.add(node.id);
+        if (node.parentId)
+            ids.add(node.parentId);
+    };
+    for (const { id, data } of changes.nodeUpdates) {
+        ids.add(id);
+        if (Object.hasOwn(data, 'parentId')) {
+            const currentParentId = beforeState.nodes[id]?.parentId;
+            if (currentParentId)
+                ids.add(currentParentId);
+            if (typeof data.parentId === 'string')
+                ids.add(data.parentId);
+        }
+    }
+    for (const { node } of changes.nodeCreates)
+        addNodeAndParent(node);
+    for (const { node } of changes.nodeDeletes)
+        addNodeAndParent(node);
+    return ids;
+}
+function sceneOperationPatchHasLiveConflict(beforeState, changes) {
+    const overrides = useLiveNodeOverrides.getState();
+    const transforms = useLiveTransforms.getState();
+    for (const id of sceneOperationPatchLiveConflictIds(beforeState, changes)) {
+        if (overrides.get(id) || transforms.get(id))
+            return true;
+    }
+    return false;
+}
+function areScenePatchValuesEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (typeof left !== typeof right || left === null || right === null)
+        return false;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            left.length === right.length &&
+            left.every((value, index) => areScenePatchValuesEqual(value, right[index])));
+    }
+    if (typeof left !== 'object' || typeof right !== 'object')
+        return false;
+    const leftRecord = left;
+    const rightRecord = right;
+    const leftKeys = Object.keys(leftRecord);
+    if (leftKeys.length !== Object.keys(rightRecord).length)
+        return false;
+    return leftKeys.every((key) => Object.hasOwn(rightRecord, key) &&
+        areScenePatchValuesEqual(leftRecord[key], rightRecord[key]));
+}
+function parseSceneOperationPatchNode(value) {
+    const builtin = AnyNodeSchema.safeParse(value);
+    if (builtin.success)
+        return builtin.data;
+    if (!(value && typeof value === 'object' && !Array.isArray(value)))
+        return null;
+    const type = value.type;
+    if (typeof type !== 'string')
+        return null;
+    const registered = nodeRegistry.get(type)?.schema.safeParse(value);
+    return registered?.success ? registered.data : null;
+}
+function structuralSiblingIds(nodes, rootNodeIds, parentId) {
+    if (!parentId)
+        return rootNodeIds;
+    const parent = nodes[parentId];
+    if (!(parent && 'children' in parent && Array.isArray(parent.children)))
+        return null;
+    return parent.children.every((id) => typeof id === 'string')
+        ? parent.children
+        : null;
+}
+function insertSceneStructuralPlacements(base, placements) {
+    if (placements.length === 0)
+        return base;
+    const result = new Array(base.length + placements.length);
+    for (const change of placements) {
+        if (!Number.isSafeInteger(change.position) ||
+            change.position < 0 ||
+            change.position >= result.length ||
+            result[change.position] !== undefined) {
+            return null;
+        }
+        result[change.position] = change.node.id;
+    }
+    let baseIndex = 0;
+    for (let index = 0; index < result.length; index += 1) {
+        if (result[index] !== undefined)
+            continue;
+        result[index] = base[baseIndex];
+        baseIndex += 1;
+    }
+    return result;
+}
+function sceneOperationPatchNextState(beforeState, changes) {
+    const createIds = new Set();
+    const deleteIds = new Set();
+    const updateIds = new Set();
+    const materialIds = new Set();
+    const parsedCreates = [];
+    for (const change of changes.nodeCreates) {
+        const parsed = parseSceneOperationPatchNode(change.node);
+        if (!parsed ||
+            parsed.id !== change.node.id ||
+            createIds.has(parsed.id) ||
+            Object.hasOwn(beforeState.nodes, parsed.id) ||
+            !Number.isSafeInteger(change.position) ||
+            change.position < 0) {
+            return null;
+        }
+        createIds.add(parsed.id);
+        parsedCreates.push({ node: change.node, position: change.position });
+    }
+    for (const change of changes.nodeDeletes) {
+        const id = change.node.id;
+        const current = beforeState.nodes[id];
+        const parentId = change.node.parentId ?? null;
+        const siblings = structuralSiblingIds(beforeState.nodes, beforeState.rootNodeIds, parentId);
+        if (!current ||
+            createIds.has(id) ||
+            deleteIds.has(id) ||
+            !Number.isSafeInteger(change.position) ||
+            change.position < 0 ||
+            siblings?.[change.position] !== id ||
+            !areScenePatchValuesEqual(current, change.node)) {
+            return null;
+        }
+        deleteIds.add(id);
+    }
+    for (const id of createIds) {
+        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))
+        : beforeState.rootNodeIds;
+    const changedParentIds = new Set();
+    for (const change of changes.nodeDeletes) {
+        const parentId = change.node.parentId ?? null;
+        if (parentId && !deleteIds.has(parentId))
+            changedParentIds.add(parentId);
+        delete nextNodes[change.node.id];
+    }
+    for (const parentId of changedParentIds) {
+        const parent = nextNodes[parentId];
+        if (!(parent && 'children' in parent && Array.isArray(parent.children)))
+            return null;
+        nextNodes[parentId] = {
+            ...parent,
+            children: parent.children.filter((id) => !deleteIds.has(id)),
+        };
+    }
+    for (const change of parsedCreates)
+        nextNodes[change.node.id] = change.node;
+    const rootCreates = [];
+    const existingParentCreates = new Map();
+    for (const change of parsedCreates) {
+        const parentId = change.node.parentId ?? null;
+        if (!parentId) {
+            rootCreates.push(change);
+            continue;
+        }
+        const parent = nextNodes[parentId];
+        if (!parent)
+            return null;
+        if (createIds.has(parentId)) {
+            if (!('children' in parent) ||
+                !Array.isArray(parent.children) ||
+                parent.children[change.position] !== change.node.id) {
+                return null;
+            }
+            continue;
+        }
+        const placements = existingParentCreates.get(parentId) ?? [];
+        placements.push(change);
+        existingParentCreates.set(parentId, placements);
+    }
+    const insertedRoots = insertSceneStructuralPlacements(nextRootNodeIds, rootCreates);
+    if (!insertedRoots)
+        return null;
+    nextRootNodeIds = insertedRoots;
+    for (const [parentId, placements] of existingParentCreates) {
+        const parent = nextNodes[parentId];
+        if (!(parent && 'children' in parent && Array.isArray(parent.children)))
+            return null;
+        const children = insertSceneStructuralPlacements(parent.children, placements);
+        if (!children)
+            return null;
+        nextNodes[parentId] = { ...parent, children };
+    }
+    for (const change of parsedCreates) {
+        const parentId = change.node.parentId ?? null;
+        const siblings = structuralSiblingIds(nextNodes, nextRootNodeIds, parentId);
+        if (siblings?.[change.position] !== change.node.id)
+            return null;
+        if (!('children' in change.node && Array.isArray(change.node.children)))
+            continue;
+        for (const childId of change.node.children) {
+            if (nextNodes[childId]?.parentId !== change.node.id)
+                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) ||
+            (material !== null && (material.id !== id || !SceneMaterial.safeParse(material).success))) {
+            return null;
+        }
+        materialIds.add(id);
+        if (material === null)
+            delete materials[id];
+        else
+            materials[id] = material;
+    }
+    return { materials, nodes: nextNodes, rootNodeIds: nextRootNodeIds };
+}
+export function applySceneOperationPatch(changes) {
+    const beforeState = useScene.getState();
+    if (changes.nodeUpdates.length === 0 &&
+        changes.materialChanges.length === 0 &&
+        changes.nodeCreates.length === 0 &&
+        changes.nodeDeletes.length === 0) {
+        return false;
+    }
+    if (sceneOperationPatchHasLiveConflict(beforeState, changes))
+        return false;
+    const next = sceneOperationPatchNextState(beforeState, changes);
+    if (!next)
+        return false;
+    const before = sceneHistorySnapshotFromState(beforeState);
+    const shouldScopeHistoryPause = useScene.temporal.getState().isTracking || getSceneHistoryPauseDepth() > 0;
+    if (shouldScopeHistoryPause)
+        pauseSceneHistory(useScene);
+    try {
+        useScene.setState(next);
+    }
+    finally {
+        if (shouldScopeHistoryPause)
+            resumeSceneHistory(useScene);
+    }
+    const currentState = useScene.getState();
+    const current = sceneHistorySnapshotFromState(currentState);
+    const touchedNodeIds = new Set([
+        ...changes.nodeUpdates.map(({ id }) => id),
+        ...changes.nodeCreates.map(({ node }) => node.id),
+        ...changes.nodeDeletes.map(({ node }) => node.id),
+    ]);
+    for (const id of touchedNodeIds) {
+        useLiveNodeOverrides.getState().clear(id);
+        useLiveTransforms.getState().clear(id);
+    }
+    if (areSceneSnapshotsEqual(before, current))
+        return false;
+    for (const id of touchedNodeIds) {
+        if (current.nodes[id])
+            currentState.markDirty(id);
+        else
+            currentState.clearDirty(id);
+        const beforeParentId = before.nodes[id]?.parentId;
+        const currentParentId = current.nodes[id]?.parentId;
+        if (beforeParentId)
+            currentState.markDirty(beforeParentId);
+        if (currentParentId)
+            currentState.markDirty(currentParentId);
+    }
+    const structuralParentIds = new Set();
+    for (const { node } of changes.nodeCreates) {
+        if (node.parentId)
+            structuralParentIds.add(node.parentId);
+    }
+    for (const { node } of changes.nodeDeletes) {
+        if (node.parentId)
+            structuralParentIds.add(node.parentId);
+    }
+    for (const parentId of structuralParentIds) {
+        const parent = current.nodes[parentId];
+        if (!(parent && 'children' in parent && Array.isArray(parent.children)))
+            continue;
+        for (const childId of parent.children)
+            currentState.markDirty(childId);
+    }
+    if (changes.materialChanges.length > 0) {
+        const materialRefs = new Set(changes.materialChanges.map(({ id }) => toSceneMaterialRef(id)));
+        for (const node of Object.values(current.nodes)) {
+            const slots = 'slots' in node ? node.slots : undefined;
+            if (!(slots && Object.values(slots).some((ref) => materialRefs.has(ref))))
+                continue;
+            currentState.markDirty(node.id);
+            if (node.parentId)
+                currentState.markDirty(node.parentId);
+        }
+    }
+    for (const { node } of changes.nodeDeletes)
+        currentState.clearDirty(node.id);
+    notifySceneCommit({
+        origin: 'host',
+        before,
+        current,
+    });
+    return true;
+}
+export function applyScenePatch(changes) {
+    return applySceneOperationPatch({
+        ...changes,
+        nodeCreates: [],
+        nodeDeletes: [],
+    });
+}
+export function applySceneSnapshot(snapshot, options) {
+    const before = sceneHistorySnapshotFromState(useScene.getState());
+    const temporalState = useScene.temporal.getState();
+    if (!temporalState.isTracking || getSceneHistoryPauseDepth() > 0) {
+        throw new Error('Cannot replace the scene snapshot during an active interaction');
+    }
+    pauseSceneHistory(useScene);
+    try {
+        useScene.getState().setScene(snapshot.nodes, snapshot.rootNodeIds, {
+            collections: snapshot.collections,
+            installedPlugins: snapshot.installedPlugins,
+            materials: snapshot.materials,
+        });
+        useScene.temporal.getState().clear();
+    }
+    finally {
+        resumeSceneHistory(useScene);
+    }
+    useLiveNodeOverrides.getState().clearAll();
+    useLiveTransforms.getState().clearAll();
+    const current = sceneHistorySnapshotFromState(useScene.getState());
+    if (areSceneSnapshotsEqual(before, current))
+        return false;
+    notifySceneCommit({ origin: options.origin, before, current });
+    return true;
+}
 // Track previous temporal state lengths and node snapshot for diffing
 let prevPastLength = 0;
 let prevFutureLength = 0;
 let prevNodesSnapshot = null;
 export function clearSceneHistory() {
     resetSceneHistoryPauseDepth();
+    // 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
+    // invisible to undo. Resume unconditionally so the cleared history starts
+    // tracking from the loaded baseline.
+    useScene.temporal.getState().resume();
     useScene.temporal.getState().clear();
     prevPastLength = 0;
     prevFutureLength = 0;