@pascal-app/viewer 0.8.0 → 0.9.1

package/dist/components/renderers/node-renderer.d.ts

@@ -1,5 +1,5 @@
 import { type AnyNode } from '@pascal-app/core';
 export declare const NodeRenderer: ({ nodeId }: {
     nodeId: AnyNode["id"];
-}) => import("react/jsx-runtime").JSX.Element | null;
+}) => import("react").JSX.Element | null;
 //# sourceMappingURL=node-renderer.d.ts.map

package/dist/components/renderers/node-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-renderer.d.ts","sourceRoot":"","sources":["../../../src/components/renderers/node-renderer.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,OAAO,EAAY,MAAM,kBAAkB,CAAA;AAqBzD,eAAO,MAAM,YAAY,GAAI,YAAY;IAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,mDA4BjE,CAAA"}
+{"version":3,"file":"node-renderer.d.ts","sourceRoot":"","sources":["../../../src/components/renderers/node-renderer.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,OAAO,EAA+C,MAAM,kBAAkB,CAAA;AAqB5F,eAAO,MAAM,YAAY,GAAI,YAAY;IAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,uCAwBjE,CAAA"}

package/dist/components/renderers/node-renderer.js

@@ -1,28 +1,44 @@
 'use client';
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useScene } from '@pascal-app/core';
-import { BuildingRenderer } from './building/building-renderer';
-import { CeilingRenderer } from './ceiling/ceiling-renderer';
-import { ColumnRenderer } from './column/column-renderer';
-import { DoorRenderer } from './door/door-renderer';
-import { FenceRenderer } from './fence/fence-renderer';
-import { GuideRenderer } from './guide/guide-renderer';
-import { ItemRenderer } from './item/item-renderer';
-import { LevelRenderer } from './level/level-renderer';
-import { RoofRenderer } from './roof/roof-renderer';
-import { RoofSegmentRenderer } from './roof-segment/roof-segment-renderer';
-import { ScanRenderer } from './scan/scan-renderer';
-import { SiteRenderer } from './site/site-renderer';
-import { SlabRenderer } from './slab/slab-renderer';
-import { SpawnRenderer } from './spawn/spawn-renderer';
-import { StairRenderer } from './stair/stair-renderer';
-import { StairSegmentRenderer } from './stair-segment/stair-segment-renderer';
-import { WallRenderer } from './wall/wall-renderer';
-import { WindowRenderer } from './window/window-renderer';
-import { ZoneRenderer } from './zone/zone-renderer';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { nodeRegistry, useScene } from '@pascal-app/core';
+import { lazy, Suspense } from 'react';
+import { ParametricNodeRenderer } from './parametric-node-renderer';
+// Cache lazy components by their RendererSource so React.lazy isn't re-invoked
+// on every render — that would create a new Suspense boundary each time.
+const lazyCache = new WeakMap();
+function getRegistryRenderer(source) {
+    const cached = lazyCache.get(source);
+    if (cached)
+        return cached;
+    // GLB / instanced-GLB sources lower onto built-in renderers landed in
+    // Phase 5 — for now only parametric (lazy module) sources are honored.
+    if (source.kind !== 'parametric')
+        return null;
+    const Comp = lazy(source.module);
+    lazyCache.set(source, Comp);
+    return Comp;
+}
 export const NodeRenderer = ({ nodeId }) => {
     const node = useScene((state) => state.nodes[nodeId]);
     if (!node)
         return null;
-    return (_jsxs(_Fragment, { children: [node.type === 'site' && _jsx(SiteRenderer, { node: node }), node.type === 'building' && _jsx(BuildingRenderer, { node: node }), node.type === 'ceiling' && _jsx(CeilingRenderer, { node: node }), node.type === 'column' && _jsx(ColumnRenderer, { node: node }), node.type === 'level' && _jsx(LevelRenderer, { node: node }), node.type === 'item' && _jsx(ItemRenderer, { node: node }), node.type === 'slab' && _jsx(SlabRenderer, { node: node }), node.type === 'spawn' && _jsx(SpawnRenderer, { node: node }), node.type === 'wall' && _jsx(WallRenderer, { node: node }), node.type === 'fence' && _jsx(FenceRenderer, { node: node }), node.type === 'door' && _jsx(DoorRenderer, { node: node }), node.type === 'window' && _jsx(WindowRenderer, { node: node }), node.type === 'zone' && _jsx(ZoneRenderer, { node: node }), node.type === 'roof' && _jsx(RoofRenderer, { node: node }), node.type === 'roof-segment' && _jsx(RoofSegmentRenderer, { node: node }), node.type === 'stair' && _jsx(StairRenderer, { node: node }), node.type === 'stair-segment' && _jsx(StairSegmentRenderer, { node: node }), node.type === 'scan' && _jsx(ScanRenderer, { node: node }), node.type === 'guide' && _jsx(GuideRenderer, { node: node })] }));
+    const def = nodeRegistry.get(node.type);
+    if (!def)
+        return null;
+    // Two-checkbox dispatch (see wiki/architecture/node-definitions.md):
+    //  1. Custom renderer — JSX-side composition for kinds that need GLB,
+    //     drei, <Html>, instancing, shader materials.
+    //  2. Else, if the kind ships `def.geometry`, the generic empty-group
+    //     <ParametricNodeRenderer> is filled by <GeometrySystem> from the
+    //     pure builder.
+    if (def.renderer) {
+        const Renderer = getRegistryRenderer(def.renderer);
+        if (!Renderer)
+            return null;
+        return (_jsx(Suspense, { fallback: null, children: _jsx(Renderer, { node: node }) }));
+    }
+    if (def.geometry) {
+        return _jsx(ParametricNodeRenderer, { node: node });
+    }
+    return null;
 };

package/dist/components/renderers/parametric-node-renderer.d.ts

@@ -0,0 +1,5 @@
+import { type AnyNode } from '@pascal-app/core';
+export declare const ParametricNodeRenderer: ({ node }: {
+    node: AnyNode;
+}) => import("react").JSX.Element;
+//# sourceMappingURL=parametric-node-renderer.d.ts.map

package/dist/components/renderers/parametric-node-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parametric-node-renderer.d.ts","sourceRoot":"","sources":["../../../src/components/renderers/parametric-node-renderer.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,OAAO,EAMb,MAAM,kBAAkB,CAAA;AAwCzB,eAAO,MAAM,sBAAsB,GAAI,UAAU;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,gCA4CjE,CAAA"}

package/dist/components/renderers/parametric-node-renderer.js

@@ -0,0 +1,34 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLiveNodeOverrides, useLiveTransforms, useRegistry, useScene, } from '@pascal-app/core';
+import { useLayoutEffect, useRef } from 'react';
+import { useNodeEvents } from '../../hooks/use-node-events';
+import { NodeRenderer } from './node-renderer';
+export const ParametricNodeRenderer = ({ node }) => {
+    const ref = useRef(null);
+    const n = node;
+    const handlers = useNodeEvents(node, node.type);
+    const liveTransform = useLiveTransforms((s) => s.get(node.id));
+    // Registry arrow handles (rotation gizmo, position-affecting patches)
+    // write to `useLiveNodeOverrides`. GeometrySystem already merges that
+    // for the mesh body; we also fold it into the outer group's
+    // position/rotation so the rotation arrow shows live motion instead
+    // of snapping only on commit. Per-node subscription so unrelated
+    // override writes don't re-render the whole tree.
+    const liveOverride = useLiveNodeOverrides((s) => s.overrides.get(node.id));
+    const overrideRotation = liveOverride?.rotation;
+    const overridePosition = liveOverride?.position;
+    useRegistry(node.id, node.type, ref);
+    useLayoutEffect(() => {
+        useScene.getState().markDirty(node.id);
+    }, [node.id]);
+    const position = liveTransform?.position ?? overridePosition ?? n.position ?? [0, 0, 0];
+    const rawRotation = overrideRotation ?? n.rotation;
+    const rotation = liveTransform?.rotation !== undefined
+        ? [0, liveTransform.rotation, 0]
+        : typeof rawRotation === 'number'
+            ? [0, rawRotation, 0]
+            : (rawRotation ?? [0, 0, 0]);
+    return (_jsx("group", { position: position, ref: ref, rotation: rotation, visible: n.visible !== false, ...handlers, children: Array.isArray(n.children) &&
+            n.children.map((childId) => (_jsx(NodeRenderer, { nodeId: childId }, `${node.id}:${childId}`))) }));
+};

package/dist/components/renderers/scene-renderer.d.ts

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

package/dist/components/renderers/scene-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-renderer.d.ts","sourceRoot":"","sources":["../../../src/components/renderers/scene-renderer.tsx"],"names":[],"mappings":"AAKA,eAAO,MAAM,aAAa,+CAUzB,CAAA"}
+{"version":3,"file":"scene-renderer.d.ts","sourceRoot":"","sources":["../../../src/components/renderers/scene-renderer.tsx"],"names":[],"mappings":"AAKA,eAAO,MAAM,aAAa,mCAUzB,CAAA"}

package/dist/components/viewer/ground-occluder.d.ts

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

package/dist/components/viewer/ground-occluder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ground-occluder.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/ground-occluder.tsx"],"names":[],"mappings":"AAMA,eAAO,MAAM,cAAc,+CAuG1B,CAAA"}
+{"version":3,"file":"ground-occluder.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/ground-occluder.tsx"],"names":[],"mappings":"AAOA,eAAO,MAAM,cAAc,mCAuF1B,CAAA"}

package/dist/components/viewer/ground-occluder.js

@@ -1,12 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useScene } from '@pascal-app/core';
-import polygonClipping from 'polygon-clipping';
 import { useMemo } from 'react';
 import * as THREE from 'three';
+import { unionPolygons } from '../../lib/polygon-union';
+import { getSceneTheme } from '../../lib/scene-themes';
 import useViewer from '../../store/use-viewer';
 export const GroundOccluder = () => {
-    const theme = useViewer((state) => state.theme);
-    const bgColor = theme === 'dark' ? '#1f2433' : '#fafafa';
+    const bgColor = useViewer((state) => getSceneTheme(state.sceneTheme).ground);
     const nodes = useScene((state) => state.nodes);
     const shape = useMemo(() => {
         const s = new THREE.Shape();
@@ -49,28 +49,16 @@ export const GroundOccluder = () => {
             polygons.push(node.polygon);
         });
         if (polygons.length > 0) {
-            // Format for polygon-clipping: [[[x, y], [x, y], ...]]
-            const multiPolygons = polygons.map((pts) => {
-                const ring = pts.map((p) => [p[0], -p[1]]); // Negate Y (which was Z)
-                return [ring];
-            });
-            // Union all polygons together to prevent artifacts from overlapping
-            const unionedPolygons = polygonClipping.union(multiPolygons[0], ...multiPolygons.slice(1));
-            // Add each resulting unioned polygon as a hole
-            for (const geom of unionedPolygons) {
-                // First ring in each geometry is the exterior ring
-                if (geom.length > 0) {
-                    const ring = geom[0];
-                    const hole = new THREE.Path();
-                    if (ring.length > 0) {
-                        hole.moveTo(ring[0][0], ring[0][1]);
-                        for (let i = 1; i < ring.length; i++) {
-                            hole.lineTo(ring[i][0], ring[i][1]);
-                        }
-                        hole.closePath();
-                        s.holes.push(hole);
-                    }
+            for (const ring of unionPolygons(polygons.map((pts) => pts.map((p) => [p[0], -p[1]])))) {
+                if (ring.length < 3)
+                    continue;
+                const hole = new THREE.Path();
+                hole.moveTo(ring[0][0], ring[0][1]);
+                for (let i = 1; i < ring.length; i++) {
+                    hole.lineTo(ring[i][0], ring[i][1]);
                 }
+                hole.closePath();
+                s.holes.push(hole);
             }
         }
         return s;

package/dist/components/viewer/index.d.ts

@@ -1,5 +1,8 @@
+import { type AnyNodeId } from '@pascal-app/core';
 import { type ThreeToJSXElements } from '@react-three/fiber';
 import * as THREE from 'three/webgpu';
+import type { ColorPreset, RenderShading } from '../../lib/materials';
+import { type RenderContext } from '../../store/use-viewer';
 import { type HoverStyles } from './post-processing';
 declare module '@react-three/fiber' {
     interface ThreeElements extends ThreeToJSXElements<typeof THREE> {
@@ -11,7 +14,40 @@ interface ViewerProps {
     selectionManager?: 'default' | 'custom';
     perf?: boolean;
     useBvh?: boolean;
+    renderContext?: RenderContext;
+    defaultRender?: {
+        shading?: RenderShading;
+        textures?: boolean;
+        colorPreset?: ColorPreset;
+    };
+    /**
+     * Visibility filter on the live canvas. When non-null, every registered
+     * node group whose id is not in `isolate` (or in the isolated set's
+     * ancestor / descendant closure) is hidden. Pass `null` (or omit) to
+     * clear. Powers the unified preset-capture flow (community modal sets
+     * this to the subtree it wants to thumbnail) and is the building block
+     * for a future focus-mode UX.
+     */
+    isolate?: AnyNodeId[] | null;
+    /**
+     * Host-controlled key for scene readiness. Change it whenever a new scene
+     * graph is being loaded; the viewer will report not-ready until the graph is
+     * mounted, build systems have had a frame to settle, and one rendered frame
+     * has presented the new content.
+     */
+    sceneReadyKey?: string | number | null;
+    onSceneReadyChange?: (ready: boolean) => void;
 }
-declare const Viewer: React.FC<ViewerProps>;
+/** Imperative handle exposed via `ref` on `<Viewer>`. */
+export type ViewerHandle = {
+    /**
+     * Apply / clear the same visibility filter as the `isolate` prop. Useful
+     * for transient cases (a temporary hover-to-isolate UX) where holding
+     * the value in React state would be over-engineering. Passing `null`
+     * clears.
+     */
+    setIsolated(ids: AnyNodeId[] | null): void;
+};
+declare const Viewer: import("react").ForwardRefExoticComponent<ViewerProps & import("react").RefAttributes<ViewerHandle>>;
 export default Viewer;
 //# sourceMappingURL=index.d.ts.map

package/dist/components/viewer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/index.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,kBAAkB,EAAsB,MAAM,oBAAoB,CAAA;AAEhG,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAwBrC,OAAuB,EAAwB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AA+B1F,OAAO,QAAQ,oBAAoB,CAAC;IAClC,UAAU,aAAc,SAAQ,kBAAkB,CAAC,OAAO,KAAK,CAAC;KAAG;CACpE;AAkFD,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,gBAAgB,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IACvC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,QAAA,MAAM,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,CAwGjC,CAAA;AASD,eAAe,MAAM,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/index.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,SAAS,EAKf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAkB,KAAK,kBAAkB,EAAsB,MAAM,oBAAoB,CAAA;AAEhG,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAIrC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAErE,OAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAQtE,OAAuB,EAAwB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAM1F,OAAO,QAAQ,oBAAoB,CAAC;IAClC,UAAU,aAAc,SAAQ,kBAAkB,CAAC,OAAO,KAAK,CAAC;KAAG;CACpE;AAuOD,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,gBAAgB,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IACvC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,aAAa,CAAC,EAAE;QACd,OAAO,CAAC,EAAE,aAAa,CAAA;QACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;QAClB,WAAW,CAAC,EAAE,WAAW,CAAA;KAC1B,CAAA;IACD;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACtC,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAC9C;AAED,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;CAC3C,CAAA;AAED,QAAA,MAAM,MAAM,sGAmKV,CAAA;AAkBF,eAAe,MAAM,CAAA"}

package/dist/components/viewer/index.js

@@ -1,56 +1,26 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Bvh } from '@react-three/drei';
+import { nodeRegistry, StairOpeningSystem, sceneRegistry, useScene, } from '@pascal-app/core';
 import { Canvas, extend, useFrame, useThree } from '@react-three/fiber';
-import { useEffect, useMemo, useRef } from 'react';
+import { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
 import * as THREE from 'three/webgpu';
-import useViewer from '../../store/use-viewer';
-import { CeilingSystem } from '../../systems/ceiling/ceiling-system';
-import { DoorAnimationSystem } from '../../systems/door/door-animation-system';
-import { DoorSystem } from '../../systems/door/door-system';
-import { FenceSystem } from '../../systems/fence/fence-system';
-import { GuideSystem } from '../../systems/guide/guide-system';
-import { ItemSystem } from '../../systems/item/item-system';
-import { ItemLightSystem } from '../../systems/item-light/item-light-system';
-import { LevelSystem } from '../../systems/level/level-system';
-import { RoofSystem } from '../../systems/roof/roof-system';
-import { ScanSystem } from '../../systems/scan/scan-system';
-import { SlabSystem } from '../../systems/slab/slab-system';
-import { StairSystem } from '../../systems/stair/stair-system';
-import { WallCutout } from '../../systems/wall/wall-cutout';
-import { WallSystem } from '../../systems/wall/wall-system';
-import { WindowAnimationSystem } from '../../systems/window/window-animation-system';
-import { WindowSystem } from '../../systems/window/window-system';
-import { ZoneSystem } from '../../systems/zone/zone-system';
+import { hasDrawableGeometry } from '../../lib/drawable-geometry';
+import { PERF_OVERLAY_ENABLED, pushGpuSample } from '../../lib/gpu-perf';
+import { applyIsolation, clearIsolation } from '../../lib/isolation';
+import { getSceneTheme } from '../../lib/scene-themes';
+import useViewer, {} from '../../store/use-viewer';
+import { FloorElevationSystem } from '../../systems/floor-elevation/floor-elevation-system';
+import { GeometrySystem } from '../../systems/geometry/geometry-system';
 import { ErrorBoundary } from '../error-boundary';
 import { SceneRenderer } from '../renderers/scene-renderer';
 import FrameLimiter from './frame-limiter';
 import { Lights } from './lights';
 import { PerfMonitor } from './perf-monitor';
 import PostProcessing, { DEFAULT_HOVER_STYLES } from './post-processing';
+import { RegisteredSystems } from './registered-systems';
+import { SceneBvh } from './scene-bvh';
 import { SelectionManager } from './selection-manager';
 import { ViewerCamera } from './viewer-camera';
-function AnimatedBackground({ isDark }) {
-    const targetColor = useMemo(() => new THREE.Color(), []);
-    const initialized = useRef(false);
-    useFrame(({ scene }, delta) => {
-        const dt = Math.min(delta, 0.1) * 4;
-        const targetHex = isDark ? '#1f2433' : '#ffffff';
-        if (!(scene.background && scene.background instanceof THREE.Color)) {
-            scene.background = new THREE.Color(targetHex);
-            initialized.current = true;
-            return;
-        }
-        if (!initialized.current) {
-            scene.background.set(targetHex);
-            initialized.current = true;
-            return;
-        }
-        targetColor.set(targetHex);
-        scene.background.lerp(targetColor, dt);
-    });
-    return null;
-}
 extend(THREE);
 // R3F's <Canvas> useLayoutEffect has no deps, so any re-render (theme switch,
 // parent re-render, StrictMode double-mount) re-invokes `configure()`. With a
@@ -67,6 +37,49 @@ extend(THREE);
 // concurrent configure() calls await the same init instead of creating two
 // renderers in parallel and only caching the second.
 const WEBGPU_RENDERER_CACHE = new WeakMap();
+const SCENE_READY_SETTLED_FRAMES = 2;
+const SCENE_READY_MAX_WAIT_FRAMES = 180;
+const DIRTY_BUILD_KINDS = new Set([
+    'ceiling',
+    'door',
+    'item',
+    'roof',
+    'roof-segment',
+    'stair',
+    'stair-segment',
+    'wall',
+    'window',
+]);
+const warnedEmptyDraw = process.env.NODE_ENV === 'production' ? null : new WeakSet();
+/**
+ * Renderer-level safety net against the empty-vertex-buffer crash.
+ *
+ * Wraps the per-object render function so any draw whose geometry has a count-0
+ * `position` attribute is skipped instead of submitted. One such draw leaves
+ * WebGPU vertex buffer slot 0 unbound, which the validator rejects and which
+ * poisons the *whole* command encoder — so a single stray empty mesh (e.g. a
+ * transient placeholder, or a derived edge/outline geometry) flickers the entire
+ * canvas, not just itself. See `hasDrawableGeometry`.
+ *
+ * The custom render-object function is the documented three.js hook for this
+ * (`Renderer.setRenderObjectFunction`); it must call `renderObject()` for
+ * everything it keeps. `MergedOutlineNode` captures and restores this function
+ * around its passes, so the guard survives outline rendering (its own passes
+ * carry the same check inline).
+ */
+function installEmptyDrawGuard(renderer) {
+    renderer.setRenderObjectFunction((object, scene, camera, geometry, material, group, lightsNode, clippingContext, passId) => {
+        if (!hasDrawableGeometry(geometry)) {
+            if (warnedEmptyDraw && !warnedEmptyDraw.has(geometry ?? object)) {
+                warnedEmptyDraw.add(geometry ?? object);
+                console.warn('[viewer] skipped a draw with an empty position buffer (would poison the WebGPU command encoder)', { name: object?.name, type: object?.type, material: material?.name });
+            }
+            return;
+        }
+        ;
+        renderer.renderObject(object, scene, camera, geometry, material, group, lightsNode, clippingContext, passId);
+    });
+}
 function GPUDeviceWatcher() {
     const gl = useThree((s) => s.gl);
     useEffect(() => {
@@ -84,46 +97,149 @@ function GPUDeviceWatcher() {
             features: Array.from(device.features ?? []),
         });
         device.lost.then((info) => {
-            console.error(`[viewer] WebGPU device lost: reason="${info.reason}", message="${info.message}". ` +
+            console.error(`[viewer] WebGPU device lost: reason="${info.reason ?? 'unknown'}", message="${info.message ?? ''}". ` +
                 'The page must be reloaded to recover the GPU context.');
         });
         // Uncaptured errors are normally silent (only console-warned by Chrome at
         // best). Pipe them to console.error so silent mobile crashes show up.
         const onUncapturedError = (event) => {
-            console.error('[viewer] WebGPU uncaptured error:', event.error.message, event.error);
+            console.error('[viewer] WebGPU uncaptured error:', event?.error?.message, event?.error);
         };
-        device.addEventListener('uncapturederror', onUncapturedError);
+        device.addEventListener?.('uncapturederror', onUncapturedError);
         return () => {
-            device.removeEventListener('uncapturederror', onUncapturedError);
+            device.removeEventListener?.('uncapturederror', onUncapturedError);
         };
     }, [gl]);
     return null;
 }
-const Viewer = ({ children, hoverStyles = DEFAULT_HOVER_STYLES, selectionManager = 'default', perf = false, useBvh = true, }) => {
-    const theme = useViewer((state) => state.theme);
-    return (_jsxs(Canvas, { camera: { position: [50, 50, 50], fov: 50 }, className: `transition-colors duration-700 ${theme === 'dark' ? 'bg-[#1f2433]' : 'bg-[#fafafa]'}`, dpr: [1, 1.5], frameloop: "never", gl: ((props) => {
+function ToneMappingExposure() {
+    const sceneTheme = useViewer((state) => state.sceneTheme);
+    const gl = useThree((state) => state.gl);
+    const invalidate = useThree((state) => state.invalidate);
+    useEffect(() => {
+        gl.toneMappingExposure = getSceneTheme(sceneTheme).toneMappingExposure;
+        invalidate();
+    }, [gl, invalidate, sceneTheme]);
+    return null;
+}
+function hasPendingSceneBuildWork() {
+    const { dirtyNodes, nodes } = useScene.getState();
+    for (const id of dirtyNodes) {
+        const node = nodes[id];
+        if (!node)
+            continue;
+        const def = nodeRegistry.get(node.type);
+        if (def?.geometry || def?.capabilities?.floorPlaced || DIRTY_BUILD_KINDS.has(node.type)) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasCommittedSceneRoot() {
+    const { nodes, rootNodeIds } = useScene.getState();
+    if (rootNodeIds.length === 0)
+        return Object.keys(nodes).length === 0;
+    return rootNodeIds.some((id) => sceneRegistry.nodes.has(id));
+}
+function SceneReadyTracker({ onSceneReadyChange, sceneReadyKey, }) {
+    const readyRef = useRef(false);
+    const settledFramesRef = useRef(0);
+    const waitedFramesRef = useRef(0);
+    const onSceneReadyChangeRef = useRef(onSceneReadyChange);
+    useEffect(() => {
+        onSceneReadyChangeRef.current = onSceneReadyChange;
+    }, [onSceneReadyChange]);
+    useEffect(() => {
+        void sceneReadyKey;
+        readyRef.current = false;
+        settledFramesRef.current = 0;
+        waitedFramesRef.current = 0;
+        onSceneReadyChangeRef.current?.(false);
+    }, [sceneReadyKey]);
+    useFrame(() => {
+        if (!(onSceneReadyChangeRef.current && !readyRef.current))
+            return;
+        waitedFramesRef.current += 1;
+        if (waitedFramesRef.current < SCENE_READY_MAX_WAIT_FRAMES &&
+            (!hasCommittedSceneRoot() || hasPendingSceneBuildWork())) {
+            settledFramesRef.current = 0;
+            return;
+        }
+        settledFramesRef.current += 1;
+        if (settledFramesRef.current < SCENE_READY_SETTLED_FRAMES)
+            return;
+        readyRef.current = true;
+        onSceneReadyChangeRef.current(true);
+    }, 10);
+    return null;
+}
+const Viewer = forwardRef(function Viewer({ children, hoverStyles = DEFAULT_HOVER_STYLES, selectionManager = 'default', perf = false, useBvh = true, renderContext = 'editor', defaultRender, isolate, sceneReadyKey, onSceneReadyChange, }, ref) {
+    useImperativeHandle(ref, () => ({
+        setIsolated: (ids) => applyIsolation(ids),
+    }), []);
+    // Track the most recently-applied isolation so the cleanup path can
+    // restore visibility even if the prop is removed while the component is
+    // still mounted. `clearIsolation()` is a no-op when nothing was applied.
+    const isolateRef = useRef(undefined);
+    useEffect(() => {
+        isolateRef.current = isolate ?? null;
+        applyIsolation(isolate ?? null);
+        return () => {
+            // Only clear if this effect was the one that applied — protects
+            // against a parent unmount racing with a setIsolated() consumer.
+            if (isolateRef.current === isolate)
+                clearIsolation();
+        };
+    }, [isolate]);
+    const isDark = useViewer((state) => getSceneTheme(state.sceneTheme).appearance === 'dark');
+    const defaultShading = defaultRender?.shading;
+    const defaultTextures = defaultRender?.textures;
+    const defaultColorPreset = defaultRender?.colorPreset;
+    const hasDefaultRender = defaultRender != null;
+    useEffect(() => {
+        const ctx = renderContext;
+        useViewer.getState().setRenderContext(ctx);
+        const { shading, shadingByContext, setShading } = useViewer.getState();
+        setShading(shadingByContext[ctx] ?? defaultShading ?? shading);
+        if (!hasDefaultRender || typeof window === 'undefined')
+            return;
+        let persistedState = {};
+        const rawPreferences = window.localStorage.getItem('viewer-preferences');
+        if (rawPreferences) {
+            try {
+                const parsed = JSON.parse(rawPreferences);
+                if (parsed &&
+                    typeof parsed === 'object' &&
+                    parsed.state &&
+                    typeof parsed.state === 'object') {
+                    persistedState = parsed.state;
+                }
+            }
+            catch { }
+        }
+        if (defaultTextures !== undefined && !('textures' in persistedState)) {
+            useViewer.getState().setTextures(defaultTextures);
+        }
+        if (defaultColorPreset && !('colorPreset' in persistedState)) {
+            useViewer.getState().setColorPreset(defaultColorPreset);
+        }
+    }, [defaultColorPreset, defaultShading, defaultTextures, hasDefaultRender, renderContext]);
+    // Coarse-pointer devices (phones/tablets) get a tighter DPR ceiling to keep
+    // fragment-shader cost down — saves another ~30% over 1.5x on high-DPI mobile.
+    // Desktops (fine pointer) keep the original 1.5 cap.
+    const maxDpr = typeof window !== 'undefined' && window.matchMedia('(pointer: coarse)').matches ? 1.25 : 1.5;
+    return (_jsxs(Canvas, { camera: { position: [50, 50, 50], fov: 50 }, className: `transition-colors duration-700 ${isDark ? 'bg-[#1f2433]' : 'bg-[#fafafa]'}`, dpr: [1, maxDpr], frameloop: "never", gl: ((props) => {
             const canvas = props.canvas;
             const cached = canvas ? WEBGPU_RENDERER_CACHE.get(canvas) : undefined;
             if (cached)
                 return cached;
-            // Surface the env we're about to ask WebGPU for — catches "no
-            // navigator.gpu" / "adapter request failed" silently failing in
-            // mobile WebViews where WebGPU is gated behind flags.
-            const hasGpu = typeof navigator !== 'undefined' && 'gpu' in navigator;
-            console.log('[viewer] Creating WebGPURenderer', {
-                hasNavigatorGPU: hasGpu,
-                ua: typeof navigator !== 'undefined' ? navigator.userAgent : 'n/a',
-            });
             const promise = (async () => {
                 try {
                     const renderer = new THREE.WebGPURenderer(props);
                     renderer.toneMapping = THREE.ACESFilmicToneMapping;
-                    renderer.toneMappingExposure = 0.9;
+                    renderer.toneMappingExposure = getSceneTheme(useViewer.getState().sceneTheme).toneMappingExposure;
                     await renderer.init();
-                    console.log('[viewer] WebGPURenderer ready', {
-                        backend: renderer.backend?.constructor?.name,
-                        isWebGPU: renderer.isWebGPURenderer === true,
-                    });
+                    installEmptyDrawGuard(renderer);
                     return renderer;
                 }
                 catch (err) {
@@ -144,11 +260,18 @@ const Viewer = ({ children, hoverStyles = DEFAULT_HOVER_STYLES, selectionManager
         }, shadows: {
             type: THREE.PCFShadowMap,
             enabled: true,
-        }, children: [_jsx(FrameLimiter, { fps: 50 }), _jsx(ViewerCamera, {}), _jsx(GPUDeviceWatcher, {}), _jsxs(ErrorBoundary, { fallback: null, scope: "viewer-scene", children: [_jsx(Lights, {}), useBvh ? (_jsx(Bvh, { children: _jsx(SceneRenderer, {}) })) : (_jsx(SceneRenderer, {})), _jsx(LevelSystem, {}), _jsx(GuideSystem, {}), _jsx(ScanSystem, {}), _jsx(WallCutout, {}), _jsx(CeilingSystem, {}), _jsx(DoorAnimationSystem, {}), _jsx(WindowAnimationSystem, {}), _jsx(DoorSystem, {}), _jsx(FenceSystem, {}), _jsx(ItemSystem, {}), _jsx(RoofSystem, {}), _jsx(SlabSystem, {}), _jsx(StairSystem, {}), _jsx(WallSystem, {}), _jsx(WindowSystem, {}), _jsx(ZoneSystem, {}), _jsx(PostProcessing, { hoverStyles: hoverStyles }), _jsx(ItemLightSystem, {}), selectionManager === 'default' && _jsx(SelectionManager, {}), perf && _jsx(PerfMonitor, {}), children] })] }));
-};
+        }, children: [_jsx(FrameLimiter, { fps: 50 }), _jsx(ViewerCamera, {}), _jsx(GPUDeviceWatcher, {}), _jsx(ToneMappingExposure, {}), _jsx(SceneReadyTracker, { onSceneReadyChange: onSceneReadyChange, sceneReadyKey: sceneReadyKey }), _jsxs(ErrorBoundary, { fallback: null, scope: "viewer-scene", children: [_jsx(Lights, {}), useBvh ? (_jsx(SceneBvh, { children: _jsx(SceneRenderer, {}) })) : (_jsx(SceneRenderer, {})), _jsx(FloorElevationSystem, {}), _jsx(GeometrySystem, {}), _jsx(StairOpeningSystem, {}), _jsx(RegisteredSystems, {}), _jsx(PostProcessing, { hoverStyles: hoverStyles }), selectionManager === 'default' && _jsx(SelectionManager, {}), (perf || PERF_OVERLAY_ENABLED) && _jsx(PerfMonitor, {}), children] })] }));
+});
 const DebugRenderer = () => {
     useFrame(({ gl, scene, camera }) => {
+        const submittedAt = PERF_OVERLAY_ENABLED ? performance.now() : 0;
         gl.render(scene, camera);
+        if (PERF_OVERLAY_ENABLED) {
+            const queue = gl.backend?.device?.queue;
+            queue?.onSubmittedWorkDone?.().then(() => {
+                pushGpuSample(performance.now() - submittedAt);
+            });
+        }
     });
     return null;
 };

package/dist/components/viewer/lights.d.ts

@@ -1,2 +1,2 @@
-export declare function Lights(): import("react/jsx-runtime").JSX.Element;
+export declare function Lights(): import("react").JSX.Element;
 //# sourceMappingURL=lights.d.ts.map

package/dist/components/viewer/lights.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lights.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/lights.tsx"],"names":[],"mappings":"AAMA,wBAAgB,MAAM,4CAoIrB"}
+{"version":3,"file":"lights.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/lights.tsx"],"names":[],"mappings":"AAqDA,wBAAgB,MAAM,gCA2NrB"}