@pascal-app/viewer 0.8.0 → 0.9.2

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

@@ -0,0 +1,348 @@
+'use client';
+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';
+import { createSurfaceRoleMaterial, } from '../../lib/materials';
+import useViewer from '../../store/use-viewer';
+/**
+ * Generic geometry system.
+ *
+ * For every node in `dirtyNodes` whose definition exposes `def.geometry`,
+ * this system:
+ *  1. Looks up the registered `Group` from `sceneRegistry` (mounted by the
+ *     framework's `<ParametricNodeRenderer>`, or a custom renderer that
+ *     opts into the same mount contract).
+ *  2. Builds a `GeometryContext` from the current scene snapshot.
+ *  3. Calls `def.geometry(node, ctx)` to get the new `Object3D`.
+ *  4. Disposes the registered group's existing children + their geometries
+ *     and materials.
+ *  5. Reparents the returned object's children onto the registered group.
+ *  6. Clears the dirty flag.
+ *
+ * This is the "no per-kind system needed" path documented in
+ * `wiki/architecture/node-definitions.md`. A kind that only rebuilds on
+ * dirty (shelf, item, fence segment, etc.) ships nothing more than a pure
+ * `geometry` function — no `renderer.tsx`, no `system.tsx`.
+ *
+ * Kinds with `def.system` declared run their own systems *in addition* to
+ * this one — animation + cascade + named-mesh material poking stay
+ * kind-specific.
+ *
+ * Frame priority 2 mirrors the per-kind shelf system it replaces. Door
+ * animation systems run at priority 2 today too, marking dirty so the
+ * geometry rebuild lands at priority 3-4 next frame. Door/window/wall
+ * still have their own systems (they need cross-cutting work this system
+ * doesn't cover) — they coexist; this system only acts on kinds that
+ * declare `def.geometry`.
+ */
+export const GeometrySystem = () => {
+    const dirtyNodes = useScene((s) => s.dirtyNodes);
+    const clearDirty = useScene((s) => s.clearDirty);
+    const shading = useViewer((s) => s.shading);
+    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)) {
+            const def = nodeRegistry.get(node.type);
+            if (def?.geometry) {
+                useScene.getState().markDirty(node.id);
+            }
+        }
+    }, [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) => {
+            const node = nodes[id];
+            if (!node)
+                return;
+            const def = nodeRegistry.get(node.type);
+            if (!def?.geometry)
+                return;
+            dirtyIds.push(id);
+            const parentId = (node.parentId ?? null);
+            const key = `${node.type}::${parentId ?? ''}`;
+            const existing = batches.get(key);
+            if (existing)
+                existing.ids.push(id);
+            else
+                batches.set(key, { kind: node.type, parentId, ids: [id] });
+        });
+        // Phase 2 — for each batch whose kind declares `computeLevelData`,
+        // collect every sibling in the level + run the precompute once.
+        const levelDataByBatch = new Map();
+        for (const [key, batch] of batches) {
+            const def = nodeRegistry.get(batch.kind);
+            if (!def?.computeLevelData)
+                continue;
+            const siblings = [];
+            if (batch.parentId) {
+                const parent = nodes[batch.parentId];
+                const childIds = parent?.children;
+                if (Array.isArray(childIds)) {
+                    for (const cid of childIds) {
+                        const child = nodes[cid];
+                        if (child?.type === batch.kind)
+                            siblings.push(child);
+                    }
+                }
+            }
+            else {
+                for (const node of Object.values(nodes)) {
+                    if (node?.type === batch.kind && !node.parentId)
+                        siblings.push(node);
+                }
+            }
+            levelDataByBatch.set(key, def.computeLevelData(siblings));
+        }
+        // Phase 3 — per-node rebuild. Each node receives its batch's
+        // precomputed `levelData` in ctx.
+        for (const id of dirtyIds) {
+            const node = nodes[id];
+            if (!node)
+                continue;
+            const def = nodeRegistry.get(node.type);
+            const builder = def?.geometry;
+            if (!builder)
+                continue;
+            const group = sceneRegistry.nodes.get(id);
+            if (!group)
+                continue; // mount hasn't run — keep dirty for next frame
+            // Merge any live drag override into the node so resize arrows /
+            // 2D affordances see their in-flight patch on every pointer move
+            // — zustand only learns about the final value on commit. Mirrors
+            // the WallSystem / DoorSystem / WindowSystem hook-up; any kind
+            // that drives its mesh through `def.geometry` (fence, shelf, item)
+            // now smooths drags through this single line.
+            const effectiveNode = getEffectiveNode(node);
+            // Skip the rebuild when the geometry inputs are unchanged (kinds that
+            // opt in via `def.geometryKey`). Fold in the global rendering inputs so
+            // a theme / shading change — which re-dirties every geometry node — is
+            // never skipped. This kills the board remount + pointer enter/leave
+            // churn when an item reparents onto a shelf.
+            if (def.geometryKey) {
+                const childLiveOverrideKey = liveChildOverrideKey(node);
+                const builtKey = `${shading}|${textures}|${colorPreset}|${sceneTheme}|${def.geometryKey(effectiveNode)}|${childLiveOverrideKey}`;
+                if (shouldReuseGeometryBuild(builtGeometryKeyRef.current, id, group, builtKey)) {
+                    clearDirty(id);
+                    continue;
+                }
+            }
+            const parentId = (node.parentId ?? null);
+            const key = `${node.type}::${parentId ?? ''}`;
+            const levelData = levelDataByBatch.get(key);
+            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.
+            const built = builder(effectiveNode, ctx, shading, textures, colorPreset, sceneTheme);
+            if (!textures && def.surfaceRole) {
+                applyDefaultSurfaceRole(built, def.surfaceRole, colorPreset, sceneTheme);
+            }
+            disposeChildren(group);
+            for (const child of [...built.children]) {
+                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
+            // `node.position` / `node.rotation` after commit. Zeroing them out
+            // during a rebuild would clobber the React-applied transform — and
+            // because the renderer doesn't necessarily re-render on the rebuild
+            // tick, R3F wouldn't re-apply the props, leaving the group stuck at
+            // origin. Geometry builders are expected to emit local-space children.
+            clearDirty(id);
+        }
+        if (rebuiltGeometry)
+            bumpGeometryRevision();
+    }, 2);
+    return null;
+};
+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) => resolve(cid)).filter((n) => n !== undefined)
+        : [];
+    const parentId = node.parentId;
+    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).
+    let siblings = [];
+    if (parent) {
+        const parentChildIds = parent.children;
+        if (Array.isArray(parentChildIds)) {
+            for (const sid of parentChildIds) {
+                if (sid === node.id)
+                    continue;
+                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)
+                .map((n) => getEffectiveNode(n));
+        }
+    }
+    return { resolve, children, siblings, parent, levelData, materials };
+}
+function disposeChildren(group) {
+    // Only dispose meshes the geometry builder produced on the previous
+    // rebuild (marked via `userData.__fromGeometry`). React-managed
+    // children (hosted node renderers) get left in place — they have
+    // their own React-driven lifecycle and would lose their meshes /
+    // materials if we disposed them here.
+    for (const child of [...group.children]) {
+        const fromGeometry = child.userData
+            ?.__fromGeometry;
+        if (!fromGeometry)
+            continue;
+        group.remove(child);
+        const mesh = child;
+        if (mesh.geometry?.dispose)
+            mesh.geometry.dispose();
+        if ('material' in mesh) {
+            const m = mesh.material;
+            if (Array.isArray(m)) {
+                for (const mat of m) {
+                    if (isCachedMaterial(mat))
+                        continue;
+                    if (mat && typeof mat.dispose === 'function') {
+                        ;
+                        mat.dispose();
+                    }
+                }
+            }
+            else if (isCachedMaterial(m)) {
+            }
+            else if (m && typeof m.dispose === 'function') {
+                ;
+                m.dispose();
+            }
+        }
+    }
+}
+function applyDefaultSurfaceRole(root, defaultRole, colorPreset, sceneTheme) {
+    root.traverse((child) => {
+        const mesh = child;
+        if (!('material' in mesh) || !mesh.material)
+            return;
+        const role = getMeshSurfaceRole(mesh.userData.surfaceRole, defaultRole);
+        mesh.userData.surfaceRole = role;
+        mesh.material = createSurfaceRoleMaterial(role, colorPreset, getMaterialSide(mesh.material), sceneTheme);
+    });
+}
+function getMeshSurfaceRole(value, fallback) {
+    return typeof value === 'string' && isSurfaceRole(value) ? value : fallback;
+}
+function isSurfaceRole(value) {
+    return (value === 'wall' ||
+        value === 'floor' ||
+        value === 'ceiling' ||
+        value === 'roof' ||
+        value === 'joinery' ||
+        value === 'glazing' ||
+        value === 'furnishing');
+}
+function getMaterialSide(material) {
+    const source = Array.isArray(material) ? material[0] : material;
+    return source?.side ?? FrontSide;
+}
+function isCachedMaterial(value) {
+    return Boolean(value?.userData
+        ?.__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

@@ -1,2 +1,2 @@
-export declare const InteractiveSystem: () => import("react/jsx-runtime").JSX.Element;
+export declare const InteractiveSystem: () => import("react").JSX.Element;
 //# sourceMappingURL=interactive-system.d.ts.map

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,+CAgB7B,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

@@ -1,2 +1,9 @@
+/**
+ * Per-frame wall-side offset for items mounted to wall faces. The slab-
+ * elevation lift for floor items lives in the generic
+ * `<FloorElevationSystem>` and runs at priority 1 — it has already
+ * landed `mesh.position.y` by the time this system clears the dirty
+ * mark at priority 2.
+ */
 export declare const ItemSystem: () => null;
 //# sourceMappingURL=item-system.d.ts.map

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":"AAiBA,eAAO,MAAM,UAAU,YA6CtB,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"}