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

package/dist/systems/geometry/geometry-system.js

@@ -1,5 +1,5 @@
 'use client';
-import { getEffectiveNode, nodeRegistry, sceneRegistry, useScene, } from '@pascal-app/core';
+import { getEffectiveNode, nodeRegistry, sceneRegistry, useLiveNodeOverrides, useScene, } from '@pascal-app/core';
 import { useFrame } from '@react-three/fiber';
 import { useEffect, useRef } from 'react';
 import { FrontSide } from 'three';
@@ -43,11 +43,24 @@ export const GeometrySystem = () => {
     const textures = useViewer((s) => s.textures);
     const colorPreset = useViewer((s) => s.colorPreset);
     const sceneTheme = useViewer((s) => s.sceneTheme);
+    const bumpGeometryRevision = useViewer((s) => s.bumpGeometryRevision);
+    // The shared scene-material library, threaded into each builder's ctx so
+    // pure geometry builders can resolve `scene:<id>` slot refs without
+    // importing `useScene`.
+    const sceneMaterials = useScene((s) => s.materials);
     // Per-node cache of the last-built geometry key (for kinds that declare
     // `def.geometryKey`). Lets us skip a dispose+rebuild when a node is dirty
     // but its geometry inputs are unchanged — e.g. an item reparenting onto a
     // shelf dirties the shelf without altering its boards.
     const builtGeometryKeyRef = useRef(new Map());
+    // Re-mark every geometry-backed node dirty whenever a viewer appearance
+    // value changes, so `def.geometry` builders re-run and pick up the new
+    // shading / texture / preset / theme. These four are deliberate re-run
+    // TRIGGERS, not values read in the body — the effect re-fires on any
+    // change. They're primitives (stable by value), so listing them is safe;
+    // biome flags them as "unnecessary" because the body doesn't reference
+    // them, but dropping them silently breaks appearance-mode switching.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: shading/textures/colorPreset/sceneTheme are intentional re-run triggers; removing them stops geometry from rebuilding on appearance change.
     useEffect(() => {
         const nodes = useScene.getState().nodes;
         for (const node of Object.values(nodes)) {
@@ -57,10 +70,30 @@ export const GeometrySystem = () => {
             }
         }
     }, [shading, textures, colorPreset, sceneTheme]);
+    // Editing a scene material must re-colour every geometry node that
+    // references it through a `scene:<id>` slot ref. Such a node's
+    // `geometryKey` is unchanged (only the referenced material's contents
+    // moved), so clear its cached key to defeat the skip in the rebuild loop,
+    // then mark it dirty. Scoped to nodes carrying a `scene:` ref so an
+    // unrelated material edit doesn't churn the whole scene.
+    useEffect(() => {
+        void sceneMaterials;
+        const nodes = useScene.getState().nodes;
+        for (const node of Object.values(nodes)) {
+            const def = nodeRegistry.get(node.type);
+            if (!def?.geometry)
+                continue;
+            if (!nodeReferencesSceneMaterial(node))
+                continue;
+            builtGeometryKeyRef.current.delete(node.id);
+            useScene.getState().markDirty(node.id);
+        }
+    }, [sceneMaterials]);
     useFrame(() => {
         if (dirtyNodes.size === 0)
             return;
         const nodes = useScene.getState().nodes;
+        let rebuiltGeometry = false;
         const batches = new Map();
         const dirtyIds = [];
         dirtyNodes.forEach((id) => {
@@ -132,17 +165,17 @@ export const GeometrySystem = () => {
             // never skipped. This kills the board remount + pointer enter/leave
             // churn when an item reparents onto a shelf.
             if (def.geometryKey) {
-                const builtKey = `${shading}|${textures}|${colorPreset}|${sceneTheme}|${def.geometryKey(effectiveNode)}`;
-                if (builtGeometryKeyRef.current.get(id) === builtKey) {
+                const childLiveOverrideKey = liveChildOverrideKey(node);
+                const builtKey = `${shading}|${textures}|${colorPreset}|${sceneTheme}|${def.geometryKey(effectiveNode)}|${childLiveOverrideKey}`;
+                if (shouldReuseGeometryBuild(builtGeometryKeyRef.current, id, group, builtKey)) {
                     clearDirty(id);
                     continue;
                 }
-                builtGeometryKeyRef.current.set(id, builtKey);
             }
             const parentId = (node.parentId ?? null);
             const key = `${node.type}::${parentId ?? ''}`;
             const levelData = levelDataByBatch.get(key);
-            const ctx = buildGeometryContext(effectiveNode, nodes, levelData);
+            const ctx = buildGeometryContext(effectiveNode, nodes, levelData, sceneMaterials);
             // The builder is typed against the kind's specific node — at the
             // generic system level we lose that refinement, so the cast lands
             // here. Builders are responsible for trusting their schema.
@@ -152,22 +185,10 @@ export const GeometrySystem = () => {
             }
             disposeChildren(group);
             for (const child of [...built.children]) {
-                // Tag every child the builder produced so a subsequent rebuild
-                // can dispose only THIS rebuild's outputs and leave React-
-                // mounted siblings (hosted items inside a shelf / slab / etc.)
-                // alone. Without this, a parent rebuild triggered by a child
-                // event (e.g. an item reparenting onto a shelf calls
-                // `dirtyNodes.add(parent)` in `ItemRenderer`'s effect) would
-                // wipe ALL of the parent group's children — including the
-                // freshly-mounted item — leaving the item in scene state but
-                // invisible.
-                ;
-                child.userData = {
-                    ...child.userData,
-                    __fromGeometry: true,
-                };
+                markGeometryBuildOutput(child);
                 group.add(child);
             }
+            rebuiltGeometry = true;
             // NOTE: we intentionally do NOT reset `group.position` / `group.rotation`
             // here. The `ParametricNodeRenderer` binds them via JSX (`position={...}`
             // / `rotation={...}`) driven by `useLiveTransforms` during drag and
@@ -178,17 +199,45 @@ export const GeometrySystem = () => {
             // origin. Geometry builders are expected to emit local-space children.
             clearDirty(id);
         }
+        if (rebuiltGeometry)
+            bumpGeometryRevision();
     }, 2);
     return null;
 };
-function buildGeometryContext(node, nodes, levelData) {
-    const resolve = (id) => nodes[id];
+function liveChildOverrideKey(node) {
+    const childIds = node.children;
+    if (!Array.isArray(childIds) || childIds.length === 0)
+        return '';
+    const overrides = useLiveNodeOverrides.getState().overrides;
+    const entries = [];
+    for (const childId of childIds) {
+        const override = overrides.get(childId);
+        if (override)
+            entries.push([childId, override]);
+    }
+    return entries.length === 0 ? '' : JSON.stringify(entries);
+}
+function nodeReferencesSceneMaterial(node) {
+    const slots = node.slots;
+    if (!slots)
+        return false;
+    for (const ref of Object.values(slots)) {
+        if (typeof ref === 'string' && ref.startsWith('scene:'))
+            return true;
+    }
+    return false;
+}
+function buildGeometryContext(node, nodes, levelData, materials) {
+    const resolve = (id) => {
+        const resolved = nodes[id];
+        return resolved ? getEffectiveNode(resolved) : undefined;
+    };
     const childIds = node.children;
     const children = Array.isArray(childIds)
-        ? childIds.map((cid) => nodes[cid]).filter((n) => n !== undefined)
+        ? childIds.map((cid) => resolve(cid)).filter((n) => n !== undefined)
         : [];
     const parentId = node.parentId;
-    const parent = parentId ? (nodes[parentId] ?? null) : null;
+    const parent = parentId ? (resolve(parentId) ?? null) : null;
     // Siblings = same kind, same parent, excluding self. Walks the parent's
     // children array; falls back to scanning the whole scene if the parent
     // doesn't carry a `children` list (rare — most parents do).
@@ -199,16 +248,18 @@ function buildGeometryContext(node, nodes, levelData) {
             for (const sid of parentChildIds) {
                 if (sid === node.id)
                     continue;
-                const s = nodes[sid];
+                const s = resolve(sid);
                 if (s && s.type === node.type)
                     siblings.push(s);
             }
         }
         else {
-            siblings = Object.values(nodes).filter((n) => n !== node && n.type === node.type && n.parentId === parentId);
+            siblings = Object.values(nodes)
+                .filter((n) => n !== node && n.type === node.type && n.parentId === parentId)
+                .map((n) => getEffectiveNode(n));
         }
     }
-    return { resolve, children, siblings, parent, levelData };
+    return { resolve, children, siblings, parent, levelData, materials };
 }
 function disposeChildren(group) {
     // Only dispose meshes the geometry builder produced on the previous
@@ -277,3 +328,21 @@ function isCachedMaterial(value) {
         ?.__pascalCachedMaterial);
 }
 export default GeometrySystem;
+export function markGeometryBuildOutput(child) {
+    // Tag the builder subtree so paint previews can reach nested meshes (for
+    // example a cabinet sink faucet handle), while disposal still removes only
+    // top-level builder children from the registered group.
+    child.traverse((object) => {
+        object.userData = {
+            ...object.userData,
+            __fromGeometry: true,
+        };
+    });
+}
+export function shouldReuseGeometryBuild(cache, id, group, key) {
+    const cached = cache.get(id);
+    if (cached?.group === group && cached.key === key)
+        return true;
+    cache.set(id, { group, key });
+    return false;
+}

package/dist/systems/geometry/geometry-system.test.d.ts

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

package/dist/systems/geometry/geometry-system.test.d.ts.map

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

package/dist/systems/geometry/geometry-system.test.js

@@ -0,0 +1,30 @@
+// @ts-expect-error — bun:test is provided by the Bun runtime; viewer does not
+// depend on @types/bun so the import type is unresolved at compile time.
+import { describe, expect, test } from 'bun:test';
+import { BoxGeometry, Group, Mesh, MeshBasicMaterial } from 'three';
+import { markGeometryBuildOutput, shouldReuseGeometryBuild, } from './geometry-system';
+describe('markGeometryBuildOutput', () => {
+    test('marks nested builder meshes for slot paint preview', () => {
+        const root = new Group();
+        const nested = new Group();
+        const mesh = new Mesh(new BoxGeometry(1, 1, 1), new MeshBasicMaterial());
+        mesh.userData.slotId = 'appliance';
+        nested.add(mesh);
+        root.add(nested);
+        markGeometryBuildOutput(root);
+        expect(root.userData.__fromGeometry).toBe(true);
+        expect(nested.userData.__fromGeometry).toBe(true);
+        expect(mesh.userData.__fromGeometry).toBe(true);
+        expect(mesh.userData.slotId).toBe('appliance');
+    });
+});
+describe('shouldReuseGeometryBuild', () => {
+    test('rebuilds when the same node id remounts into a new group with the same key', () => {
+        const cache = new Map();
+        const firstGroup = new Group();
+        const remountedGroup = new Group();
+        expect(shouldReuseGeometryBuild(cache, 'duct_1', firstGroup, 'same-key')).toBe(false);
+        expect(shouldReuseGeometryBuild(cache, 'duct_1', firstGroup, 'same-key')).toBe(true);
+        expect(shouldReuseGeometryBuild(cache, 'duct_1', remountedGroup, 'same-key')).toBe(false);
+    });
+});

package/dist/systems/interactive/control-widget.d.ts

@@ -0,0 +1,10 @@
+import type { Control, ControlValue } from '@pascal-app/core';
+/** One interactive control (toggle / slider / temperature) rendered inside the
+ *  item controls overlay. Shared by the parametric `InteractiveSystem` and the
+ *  baked-GLB `GlbInteractive` overlay so both look and behave identically. */
+export declare const ControlWidget: ({ control, value, onChange, }: {
+    control: Control;
+    value: ControlValue;
+    onChange: (v: ControlValue) => void;
+}) => import("react").JSX.Element | null;
+//# sourceMappingURL=control-widget.d.ts.map

package/dist/systems/interactive/control-widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-widget.d.ts","sourceRoot":"","sources":["../../../src/systems/interactive/control-widget.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAE7D;;8EAE8E;AAC9E,eAAO,MAAM,aAAa,GAAI,+BAI3B;IACD,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,YAAY,CAAA;IACnB,QAAQ,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAA;CACpC,uCAuEA,CAAA"}

package/dist/systems/interactive/control-widget.js

@@ -0,0 +1,35 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** One interactive control (toggle / slider / temperature) rendered inside the
+ *  item controls overlay. Shared by the parametric `InteractiveSystem` and the
+ *  baked-GLB `GlbInteractive` overlay so both look and behave identically. */
+export const ControlWidget = ({ control, value, onChange, }) => {
+    const labelStyle = {
+        color: 'white',
+        fontSize: 11,
+        fontFamily: 'monospace',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 2,
+    };
+    if (control.kind === 'toggle') {
+        return (_jsx("button", { onClick: () => onChange(!value), style: {
+                background: value ? '#4ade80' : '#374151',
+                color: 'white',
+                border: 'none',
+                borderRadius: 4,
+                padding: '4px 8px',
+                cursor: 'pointer',
+                fontSize: 12,
+                fontFamily: 'monospace',
+                transition: 'background 0.2s',
+            }, children: control.label ?? (value ? 'On' : 'Off') }));
+    }
+    if (control.kind === 'slider') {
+        return (_jsxs("label", { style: labelStyle, children: [_jsxs("span", { children: [control.label, ": ", value, control.unit ? ` ${control.unit}` : ''] }), _jsx("input", { max: control.max, min: control.min, onChange: (e) => onChange(Number(e.target.value)), onPointerDown: (e) => e.stopPropagation(), step: control.step, type: "range", value: value })] }));
+    }
+    if (control.kind === 'temperature') {
+        return (_jsxs("label", { style: labelStyle, children: [_jsxs("span", { children: [control.label, ": ", value, "\u00B0", control.unit] }), _jsx("input", { max: control.max, min: control.min, onChange: (e) => onChange(Number(e.target.value)), onPointerDown: (e) => e.stopPropagation(), step: 1, type: "range", value: value })] }));
+    }
+    return null;
+};

package/dist/systems/interactive/interactive-system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interactive-system.d.ts","sourceRoot":"","sources":["../../../src/systems/interactive/interactive-system.tsx"],"names":[],"mappings":"AAwBA,eAAO,MAAM,iBAAiB,mCAgB7B,CAAA"}
+{"version":3,"file":"interactive-system.d.ts","sourceRoot":"","sources":["../../../src/systems/interactive/interactive-system.tsx"],"names":[],"mappings":"AAiCA,eAAO,MAAM,iBAAiB,mCAsB7B,CAAA"}

package/dist/systems/interactive/interactive-system.js

@@ -1,22 +1,41 @@
 'use client';
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { pointInPolygon, sceneRegistry, useInteractive, useScene, } from '@pascal-app/core';
 import { Html } from '@react-three/drei';
 import { createPortal, useFrame } from '@react-three/fiber';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { Vector3 } from 'three';
 import { useShallow } from 'zustand/react/shallow';
 import useViewer from '../../store/use-viewer';
+import { ControlWidget } from './control-widget';
 const _tempVec = new Vector3();
-// ---- Parent: one overlay per interactive item ----
+// ---- Parent: one overlay per interactive item inside the selected zone ----
+//
+// The <Html> overlays only exist while a zone is selected and the item sits
+// inside it. Mounting them unconditionally is not an option: each drei <Html>
+// repositions and re-sorts its DOM element on every camera-move frame, and
+// with `occlude` it also raycasts the entire scene per overlay per frame. On
+// large scenes (hundreds of interactive items) that starves the frame budget
+// and the display/z-index churn makes the whole DOM UI flicker.
+//
+// The child components stay rendered (returning null) so an overlay can fade
+// out before its <Html> unmounts.
 export const InteractiveSystem = () => {
+    const zoneId = useViewer((s) => s.selection.zoneId);
+    const zonePolygon = useScene((s) => {
+        if (!zoneId)
+            return null;
+        const z = s.nodes[zoneId];
+        return z?.polygon ?? null;
+    });
     const interactiveNodeIds = useScene(useShallow((state) => Object.values(state.nodes)
         .filter((n) => n.type === 'item' && n.asset.interactive != null)
         .map((n) => n.id)));
-    return (_jsx(_Fragment, { children: interactiveNodeIds.map((id) => (_jsx(ItemControlsOverlay, { nodeId: id }, id))) }));
+    return (_jsx(_Fragment, { children: interactiveNodeIds.map((id) => (_jsx(ItemControlsOverlay, { nodeId: id, zonePolygon: zonePolygon }, id))) }));
 };
 // ---- Child: polls sceneRegistry then portals controls into the item group ----
-const ItemControlsOverlay = ({ nodeId }) => {
+const FADE_MS = 300;
+const ItemControlsOverlay = ({ nodeId, zonePolygon, }) => {
     const node = useScene((state) => state.nodes[nodeId]);
     const [itemObj, setItemObj] = useState(null);
     useFrame(() => {
@@ -28,26 +47,37 @@ const ItemControlsOverlay = ({ nodeId }) => {
     });
     const controlValues = useInteractive(useShallow((state) => state.items[nodeId]?.controlValues));
     const setControlValue = useInteractive((state) => state.setControlValue);
-    const zoneId = useViewer((s) => s.selection.zoneId);
-    const zonePolygon = useScene((s) => {
-        if (!zoneId)
-            return null;
-        const z = s.nodes[zoneId];
-        return z?.polygon ?? null;
-    });
-    if (!(itemObj && controlValues && node?.asset.interactive))
+    let visible = false;
+    if (itemObj && zonePolygon?.length) {
+        itemObj.getWorldPosition(_tempVec);
+        visible = pointInPolygon(_tempVec.x, _tempVec.z, zonePolygon);
+    }
+    // Fade in on mount and fade out before unmounting the <Html>.
+    const [mounted, setMounted] = useState(false);
+    const [shown, setShown] = useState(false);
+    useEffect(() => {
+        if (visible) {
+            setMounted(true);
+            // Double rAF: the overlay has to paint once at opacity 0 before the
+            // opacity-1 style lands, otherwise the fade-in transition is skipped.
+            let raf2 = 0;
+            const raf1 = requestAnimationFrame(() => {
+                raf2 = requestAnimationFrame(() => setShown(true));
+            });
+            return () => {
+                cancelAnimationFrame(raf1);
+                cancelAnimationFrame(raf2);
+            };
+        }
+        setShown(false);
+        const timeout = setTimeout(() => setMounted(false), FADE_MS);
+        return () => clearTimeout(timeout);
+    }, [visible]);
+    if (!(mounted && itemObj && controlValues && node?.asset.interactive))
         return null;
     const { controls } = node.asset.interactive;
     const [, height] = node.asset.dimensions;
-    let opacity = 0;
-    let pointerEvents = 'none';
-    if (zoneId && zonePolygon?.length) {
-        itemObj.getWorldPosition(_tempVec);
-        const inside = pointInPolygon(_tempVec.x, _tempVec.z, zonePolygon);
-        opacity = inside ? 1 : 0.1;
-        pointerEvents = inside ? 'auto' : 'none';
-    }
-    return createPortal(_jsx(Html, { center: true, distanceFactor: 8, occlude: true, position: [0, height + 0.3, 0], zIndexRange: [20, 0], children: _jsx("div", { style: {
+    return createPortal(_jsx(Html, { center: true, distanceFactor: 8, eps: -1, position: [0, height + 0.3, 0], zIndexRange: [20, 0], children: _jsx("div", { style: {
                 display: 'flex',
                 flexDirection: 'column',
                 gap: 6,
@@ -56,40 +86,9 @@ const ItemControlsOverlay = ({ nodeId }) => {
                 borderRadius: 8,
                 padding: '8px 12px',
                 minWidth: 120,
-                pointerEvents,
+                pointerEvents: visible ? 'auto' : 'none',
                 userSelect: 'none',
-                opacity,
-                transition: 'opacity 0.3s ease',
+                opacity: shown ? 1 : 0,
+                transition: `opacity ${FADE_MS}ms ease`,
             }, children: controls.map((control, i) => (_jsx(ControlWidget, { control: control, onChange: (v) => setControlValue(nodeId, i, v), value: controlValues[i] ?? false }, i))) }) }), itemObj);
 };
-// ---- Control widgets ----
-const ControlWidget = ({ control, value, onChange, }) => {
-    const labelStyle = {
-        color: 'white',
-        fontSize: 11,
-        fontFamily: 'monospace',
-        display: 'flex',
-        flexDirection: 'column',
-        gap: 2,
-    };
-    if (control.kind === 'toggle') {
-        return (_jsx("button", { onClick: () => onChange(!value), style: {
-                background: value ? '#4ade80' : '#374151',
-                color: 'white',
-                border: 'none',
-                borderRadius: 4,
-                padding: '4px 8px',
-                cursor: 'pointer',
-                fontSize: 12,
-                fontFamily: 'monospace',
-                transition: 'background 0.2s',
-            }, children: control.label ?? (value ? 'On' : 'Off') }));
-    }
-    if (control.kind === 'slider') {
-        return (_jsxs("label", { style: labelStyle, children: [_jsxs("span", { children: [control.label, ": ", value, control.unit ? ` ${control.unit}` : ''] }), _jsx("input", { max: control.max, min: control.min, onChange: (e) => onChange(Number(e.target.value)), onPointerDown: (e) => e.stopPropagation(), step: control.step, type: "range", value: value })] }));
-    }
-    if (control.kind === 'temperature') {
-        return (_jsxs("label", { style: labelStyle, children: [_jsxs("span", { children: [control.label, ": ", value, "\u00B0", control.unit] }), _jsx("input", { max: control.max, min: control.min, onChange: (e) => onChange(Number(e.target.value)), onPointerDown: (e) => e.stopPropagation(), step: 1, type: "range", value: value })] }));
-    }
-    return null;
-};

package/dist/systems/item/item-system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"item-system.d.ts","sourceRoot":"","sources":["../../../src/systems/item/item-system.tsx"],"names":[],"mappings":"AAcA;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,YA+BtB,CAAA"}
+{"version":3,"file":"item-system.d.ts","sourceRoot":"","sources":["../../../src/systems/item/item-system.tsx"],"names":[],"mappings":"AAcA;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,YA8CtB,CAAA"}

package/dist/systems/item/item-system.js

@@ -19,21 +19,35 @@ export const ItemSystem = () => {
         const nodes = useScene.getState().nodes;
         dirtyNodes.forEach((id) => {
             const node = nodes[id];
-            if (!node || node.type !== 'item')
+            if (node?.type !== 'item')
                 return;
             const item = node;
             const mesh = sceneRegistry.nodes.get(id);
             if (!mesh)
                 return;
             if (item.asset.attachTo === 'wall-side') {
-                // Wall-attached item: offset Z by half the parent wall's thickness
-                const parentWall = item.parentId ? nodes[item.parentId] : undefined;
-                if (parentWall && parentWall.type === 'wall') {
-                    const wallThickness = parentWall.thickness ?? 0.1;
+                // Wall-attached item: offset Z by half the host wall's thickness.
+                // Roof-segment wall faces share the convention — the face frame's
+                // z = 0 is the wall mid-plane, so the same push lands the item on
+                // the outer surface.
+                const parent = item.parentId ? nodes[item.parentId] : undefined;
+                const thickness = parent?.type === 'wall'
+                    ? (parent.thickness ?? 0.1)
+                    : parent?.type === 'roof-segment'
+                        ? (parent.wallThickness ?? 0.1)
+                        : undefined;
+                if (thickness !== undefined) {
                     const side = item.side === 'front' ? 1 : -1;
-                    mesh.position.z = (wallThickness / 2) * side;
+                    mesh.position.z = (thickness / 2) * side;
                 }
             }
+            // Hold the mark until the model settles (loaded, terminally failed, or
+            // never expected — see ItemRenderer.markSettled). Registration alone
+            // isn't "built": clearing then would let scene-ready fire while GLBs are
+            // still downloading and a bake would export loading placeholders.
+            const settled = mesh.userData.itemModelSettled;
+            if (!settled)
+                return;
             clearDirty(id);
         });
     }, 2);

package/dist/systems/level/level-system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"level-system.d.ts","sourceRoot":"","sources":["../../../src/systems/level/level-system.tsx"],"names":[],"mappings":"AAQA,eAAO,MAAM,WAAW,YAsCvB,CAAA"}
+{"version":3,"file":"level-system.d.ts","sourceRoot":"","sources":["../../../src/systems/level/level-system.tsx"],"names":[],"mappings":"AAeA,eAAO,MAAM,WAAW,YAuDvB,CAAA"}

package/dist/systems/level/level-system.js

@@ -1,33 +1,58 @@
-import { sceneRegistry, useScene } from '@pascal-app/core';
+import { getLevelElevations, sceneRegistry, useScene } from '@pascal-app/core';
 import { useFrame } from '@react-three/fiber';
 import { lerp } from 'three/src/math/MathUtils.js';
+import { applyShadowOnly, clearShadowOnly } from '../../lib/shadow-only';
 import useViewer from '../../store/use-viewer';
-import { getLevelHeight } from './level-utils';
 const EXPLODED_GAP = 5;
+// Levels currently in shadow-caster-only mode (solo hides them from the color
+// passes but keeps their sun shadows). Tracked so we can restore layer masks
+// exactly once on transition; apply re-runs every frame so meshes rebuilt
+// while hidden (theme/texture changes) get re-hidden.
+const shadowOnlyLevels = new WeakSet();
 export const LevelSystem = () => {
     useFrame((_, delta) => {
         const nodes = useScene.getState().nodes;
         const levelMode = useViewer.getState().levelMode;
         const selectedLevel = useViewer.getState().selection.levelId;
+        const levelElevations = getLevelElevations(nodes);
         const entries = [];
         sceneRegistry.byType.level.forEach((levelId) => {
             const obj = sceneRegistry.nodes.get(levelId);
             const level = nodes[levelId];
             if (obj && level) {
-                entries.push({ levelId, index: level.level ?? 0, obj });
+                entries.push({
+                    levelId,
+                    index: level.level,
+                    obj,
+                });
             }
         });
-        entries.sort((a, b) => a.index - b.index);
-        // Walk sorted levels, accumulating base Y offsets
-        let cumulativeY = 0;
+        const selectedIndex = selectedLevel
+            ? entries.find((e) => e.levelId === selectedLevel)?.index
+            : undefined;
         for (const { levelId, index, obj } of entries) {
             const level = nodes[levelId];
-            const baseY = cumulativeY;
+            const baseY = levelElevations.get(levelId)?.baseY ?? 0;
             const explodedExtra = levelMode === 'exploded' ? index * EXPLODED_GAP : 0;
             const targetY = baseY + explodedExtra;
             obj.position.y = lerp(obj.position.y, targetY, delta * 12); // Smoothly animate to new Y position
-            obj.visible = levelMode !== 'solo' || level?.id === selectedLevel || !selectedLevel;
-            cumulativeY += getLevelHeight(levelId, nodes);
+            // Solo: hidden levels ABOVE the soloed one stay in the shadow map
+            // (shadow-caster-only) so the sun still shadows the soloed floor through
+            // them; levels below can't block the sun, so they plain-hide.
+            const hidden = levelMode === 'solo' && Boolean(selectedLevel) && level?.id !== selectedLevel;
+            const castsWhileHidden = hidden && selectedIndex !== undefined && index > selectedIndex;
+            if (castsWhileHidden) {
+                applyShadowOnly(obj);
+                shadowOnlyLevels.add(obj);
+                obj.visible = true;
+            }
+            else {
+                if (shadowOnlyLevels.has(obj)) {
+                    clearShadowOnly(obj);
+                    shadowOnlyLevels.delete(obj);
+                }
+                obj.visible = !hidden;
+            }
         }
     }, 5); // Using a lower priority so it runs after transforms from other systems have settled
     return null;

package/dist/systems/level/level-utils.d.ts

@@ -1,6 +1,3 @@
-import { useScene } from '@pascal-app/core';
-export declare const DEFAULT_LEVEL_HEIGHT = 2.5;
-export declare function getLevelHeight(levelId: string, nodes: ReturnType<typeof useScene.getState>['nodes']): number;
 /**
  * Instantly snaps all level Objects3D to their true stacked Y positions
  * (ignores levelMode — always uses stacked, no exploded gap).

package/dist/systems/level/level-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"level-utils.d.ts","sourceRoot":"","sources":["../../../src/systems/level/level-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,QAAQ,EAET,MAAM,kBAAkB,CAAA;AAEzB,eAAO,MAAM,oBAAoB,MAAM,CAAA;AAQvC,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GACnD,MAAM,CA8BR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,IAAI,CAyCtD"}
+{"version":3,"file":"level-utils.d.ts","sourceRoot":"","sources":["../../../src/systems/level/level-utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,IAAI,CAyCtD"}

package/dist/systems/level/level-utils.js

@@ -1,43 +1,4 @@
-import { sceneRegistry, useScene, } from '@pascal-app/core';
-export const DEFAULT_LEVEL_HEIGHT = 2.5;
-// Cache: levelId → computed height. Invalidated when the nodes reference changes.
-// Zustand produces a new `nodes` object on every mutation, so reference equality
-// is a zero-cost way to detect stale data without any subscription overhead.
-const heightCache = new Map();
-let lastNodesRef = null;
-export function getLevelHeight(levelId, nodes) {
-    if (nodes !== lastNodesRef) {
-        heightCache.clear();
-        lastNodesRef = nodes;
-    }
-    if (heightCache.has(levelId))
-        return heightCache.get(levelId);
-    const level = nodes[levelId];
-    if (!level)
-        return DEFAULT_LEVEL_HEIGHT;
-    let maxTop = 0;
-    for (const childId of level.children) {
-        const child = nodes[childId];
-        if (!child)
-            continue;
-        if (child.type === 'ceiling') {
-            const ch = child.height ?? DEFAULT_LEVEL_HEIGHT;
-            if (ch > maxTop)
-                maxTop = ch;
-        }
-        else if (child.type === 'wall') {
-            let meshY = sceneRegistry.nodes.get(childId)?.position.y ?? 0;
-            if (meshY < 0)
-                meshY = 0;
-            const top = meshY + (child.height ?? DEFAULT_LEVEL_HEIGHT);
-            if (top > maxTop)
-                maxTop = top;
-        }
-    }
-    const height = maxTop > 0 ? maxTop : DEFAULT_LEVEL_HEIGHT;
-    heightCache.set(levelId, height);
-    return height;
-}
+import { getLevelElevations, sceneRegistry, useScene } from '@pascal-app/core';
 /**
  * Instantly snaps all level Objects3D to their true stacked Y positions
  * (ignores levelMode — always uses stacked, no exploded gap).
@@ -57,18 +18,19 @@ export function snapLevelsToTruePositions() {
         const obj = sceneRegistry.nodes.get(levelId);
         const level = nodes[levelId];
         if (obj && level) {
-            entries.push({ levelId, index: level.level ?? 0, obj });
+            entries.push({
+                levelId,
+                obj,
+            });
         }
     });
-    entries.sort((a, b) => a.index - b.index);
+    const levelElevations = getLevelElevations(nodes);
     // Snapshot current Y and visibility so we can restore them after the render
     const snapshot = new Map(entries.map(({ levelId, obj }) => [levelId, { y: obj.position.y, visible: obj.visible }]));
     // Snap to true stacked positions and make all levels visible
-    let cumulativeY = 0;
     for (const { levelId, obj } of entries) {
-        obj.position.y = cumulativeY;
+        obj.position.y = levelElevations.get(levelId)?.baseY ?? 0;
         obj.visible = true;
-        cumulativeY += getLevelHeight(levelId, nodes);
     }
     return () => {
         for (const { levelId, obj } of entries) {