@pascal-app/viewer 1.0.3 → 1.0.4

package/dist/components/viewer/glb-walkthrough-controller.d.ts

@@ -14,7 +14,7 @@ export declare const EYE_LERP_SPEED = 12;
  * mesh collision) fed a collider built from the artifact's own geometry — so the
  * baked viewer walks the building with the same physics as the editor, without
  * the parametric scene. Pointer-lock drives look; WASD moves; Space jumps; Shift
- * sprints. Door/window interaction stays in `GlbScene` (its centre-ray HUD).
+ * sprints. Interaction stays in `GlbScene` (its centre-ray HUD).
  */
 export declare function GlbWalkthroughController({ url }: {
     url: string;

package/dist/components/viewer/glb-walkthrough-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glb-walkthrough-controller.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/glb-walkthrough-controller.tsx"],"names":[],"mappings":"AAiCA,eAAO,MAAM,eAAe,KAAK,CAAA;AAkBjC,eAAO,MAAM,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAqB,CAAA;AAChF,eAAO,MAAM,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAqB,CAAA;AACjF,eAAO,MAAM,kBAAkB,MAAM,CAAA;AACrC,eAAO,MAAM,mBAAmB,OAAO,CAAA;AACvC,eAAO,MAAM,iBAAiB,MAAM,CAAA;AACpC,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAClC,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAInC,eAAO,MAAM,eAAe,OAAO,CAAA;AACnC,eAAO,MAAM,cAAc,KAAK,CAAA;AA8LhC;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,GAAG,EAAE,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,sCAqPhE"}
+{"version":3,"file":"glb-walkthrough-controller.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/glb-walkthrough-controller.tsx"],"names":[],"mappings":"AAkCA,eAAO,MAAM,eAAe,KAAK,CAAA;AAkBjC,eAAO,MAAM,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAqB,CAAA;AAChF,eAAO,MAAM,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAqB,CAAA;AACjF,eAAO,MAAM,kBAAkB,MAAM,CAAA;AACrC,eAAO,MAAM,mBAAmB,OAAO,CAAA;AACvC,eAAO,MAAM,iBAAiB,MAAM,CAAA;AACpC,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAClC,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAInC,eAAO,MAAM,eAAe,OAAO,CAAA;AACnC,eAAO,MAAM,cAAc,KAAK,CAAA;AAiMhC;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,GAAG,EAAE,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,sCA0PhE"}

package/dist/components/viewer/glb-walkthrough-controller.js

@@ -10,6 +10,7 @@ import { useGLTFKTX2 } from '../../hooks/use-gltf-ktx2';
 import { SCENE_LAYER } from '../../lib/layers';
 import useViewer from '../../store/use-viewer';
 import BVHEcctrl, {} from './bvh-ecctrl';
+import { applyWalkthroughCameraClipping } from './viewer-camera';
 // First-person FOV. The orbit camera is 50° (set on the Canvas), which feels
 // cramped on foot; ~60° vertical (~90° horizontal at 16:9) restores peripheral
 // awareness without wide-angle distortion. Applied only while walking — both
@@ -145,6 +146,11 @@ function buildGlbColliderWorld(scene) {
             return;
         if (!isEffectivelyVisible(mesh))
             return;
+        let ancestor = mesh;
+        while (ancestor && !ancestor.userData.proceduralMotion)
+            ancestor = ancestor.parent;
+        if (ancestor)
+            return;
         const kind = kindOf(mesh);
         if (kind && COLLIDER_EXCLUDED_KINDS.has(kind))
             return;
@@ -220,7 +226,7 @@ function resolveGlbSpawn(scene) {
  * mesh collision) fed a collider built from the artifact's own geometry — so the
  * baked viewer walks the building with the same physics as the editor, without
  * the parametric scene. Pointer-lock drives look; WASD moves; Space jumps; Shift
- * sprints. Door/window interaction stays in `GlbScene` (its centre-ray HUD).
+ * sprints. Interaction stays in `GlbScene` (its centre-ray HUD).
  */
 export function GlbWalkthroughController({ url }) {
     const { camera, gl } = useThree();
@@ -273,6 +279,11 @@ export function GlbWalkthroughController({ url }) {
             cam.updateProjectionMatrix();
         };
     }, [camera]);
+    useEffect(() => {
+        if (!camera.isPerspectiveCamera)
+            return;
+        return applyWalkthroughCameraClipping(camera);
+    }, [camera]);
     useEffect(() => {
         worldRef.current = world;
         if (world) {

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

@@ -10,6 +10,13 @@ declare module '@react-three/fiber' {
         lineBasicNodeMaterial: ThreeElement<typeof THREE.LineBasicNodeMaterial>;
     }
 }
+/**
+ * The scene-ready gate's own test as a count — nodes still to build or load
+ * (an item holds its mark until its model settles), 1 while the graph has
+ * not mounted. A capture waits on it, and reads a count that stops moving
+ * as a node no system will ever settle.
+ */
+export declare function pendingSceneBuildCount(): number;
 export interface ViewerImmersiveSession {
     Session: ComponentType<{
         children: React.ReactNode;
@@ -49,6 +56,13 @@ interface ViewerProps {
      */
     sceneReadyKey?: string | number | null;
     onSceneReadyChange?: (ready: boolean) => void;
+    /**
+     * Called when something in the scene throws while rendering (a node
+     * renderer or system, such as a plugin's lazy chunk that failed to load).
+     * The scene boundary still renders nothing in its place; this lets a host
+     * that must not carry on silently (a bake) fail with its own error.
+     */
+    onRenderError?: (cause: unknown) => void;
     /**
      * Wall-clock give-up cap for scene readiness, replacing the default
      * frame-count cap. Set it on hosts whose frame cadence is decoupled from

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":"AAEA,OAAO,EACL,KAAK,SAAS,EAMf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAkB,KAAK,YAAY,EAAsB,MAAM,oBAAoB,CAAA;AAC1F,OAAO,EACL,KAAK,aAAa,EAOnB,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAKrC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAKrE,OAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAA;AActE,OAAuB,EAAwB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAY1F,OAAO,QAAQ,oBAAoB,CAAC;IAOlC,UAAU,aAAa;QACrB,qBAAqB,EAAE,YAAY,CAAC,OAAO,KAAK,CAAC,qBAAqB,CAAC,CAAA;KACxE;CACF;AAoRD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,CAAC,CAAA;IACrD,KAAK,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,CAAC,CAAA;IACnD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CACnC;AAED,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,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,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;IAC7C;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,sEAAsE;IACtE,SAAS,CAAC,EAAE,sBAAsB,CAAA;CACnC;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,sGAuPV,CAAA;AAyEF,eAAe,MAAM,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/index.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,SAAS,EAOf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAkB,KAAK,YAAY,EAAsB,MAAM,oBAAoB,CAAA;AAC1F,OAAO,EACL,KAAK,aAAa,EAOnB,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAKrC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAKrE,OAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAA;AActE,OAAuB,EAAwB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAa1F,OAAO,QAAQ,oBAAoB,CAAC;IAOlC,UAAU,aAAa;QACrB,qBAAqB,EAAE,YAAY,CAAC,OAAO,KAAK,CAAC,qBAAqB,CAAC,CAAA;KACxE;CACF;AAsPD;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAS/C;AAsED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,CAAC,CAAA;IACrD,KAAK,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,CAAC,CAAA;IACnD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CACnC;AAED,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,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,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;IAC7C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IACxC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,sEAAsE;IACtE,SAAS,CAAC,EAAE,sBAAsB,CAAA;CACnC;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,sGAwQV,CAAA;AAyEF,eAAe,MAAM,CAAA"}

package/dist/components/viewer/index.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { nodeRegistry, RoofElevationSystem, StairOpeningSystem, sceneRegistry, useScene, } from '@pascal-app/core';
+import { nodeRegistry, RoofElevationSystem, StairOpeningSystem, sceneRegistry, useInteractive, useScene, } from '@pascal-app/core';
 import { Canvas, extend, useFrame, useThree } from '@react-three/fiber';
 import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useRef, useState, } from 'react';
 import * as THREE from 'three/webgpu';
@@ -16,9 +16,9 @@ import useViewer, {} from '../../store/use-viewer';
 import { FloorElevationSystem } from '../../systems/floor-elevation/floor-elevation-system';
 import { GeometrySystem } from '../../systems/geometry/geometry-system';
 import { PerfActionSettleSystem } from '../../systems/perf-action-settle/perf-action-settle-system';
+import { getPendingRoofMergeCount } from '../../systems/roof/roof-system';
 import { subscribeWallBuildInteractions } from '../../systems/wall/wall-build-lifecycle';
 import { ImmersiveXRPresentationProvider } from '../../xr/presentation-context';
-import { ErrorBoundary } from '../error-boundary';
 import { SceneRenderer } from '../renderers/scene-renderer';
 import { BATCH_SPIKE_ENABLED, BatchedMeshSpike } from './batched-mesh-spike';
 import FrameLimiter from './frame-limiter';
@@ -28,6 +28,7 @@ import { PerfPanel } from './perf-panel';
 import { PointerRaycastLayers } from './pointer-raycast-layers';
 import PostProcessing, { DEFAULT_HOVER_STYLES } from './post-processing';
 import { RegisteredSystems } from './registered-systems';
+import { composeRenderErrorHandlers, SceneErrorBoundary } from './render-error';
 import { useSceneAtmosphere } from './scene-atmosphere';
 import { SceneBvh } from './scene-bvh';
 import { SelectionManager } from './selection-manager';
@@ -83,6 +84,35 @@ const warnedEmptyDraw = process.env.NODE_ENV === 'production' ? null : new WeakS
  * carry the same check inline).
  */
 function installEmptyDrawGuard(renderer) {
+    // The render-object hook is one funnel; the post-processing passes and the
+    // outline node reach the backend by other paths, and a geometry whose
+    // draw range is empty still slips past a position count. The backend's
+    // own `draw` is the last gate before the command encoder — a zero-vertex
+    // draw leaves a vertex-buffer slot unbound ("Vertex buffer slot 1 required
+    // by [RenderPipeline "…MeshLambertNodeMaterial…"] was not set … Draw(0, …)",
+    // 2026-09-10) and poisons the whole encoder, so it is dropped here.
+    const backend = renderer.backend;
+    if (backend && typeof backend.draw === 'function' && !backend.__pascalDrawGuard) {
+        const draw = backend.draw.bind(backend);
+        backend.draw = (renderObject, ...rest) => {
+            const geometry = renderObject?.geometry;
+            const range = geometry?.drawRange;
+            if (!hasDrawableGeometry(geometry) || (range && range.count === 0)) {
+                if (warnedEmptyDraw && geometry && !warnedEmptyDraw.has(geometry)) {
+                    warnedEmptyDraw.add(geometry);
+                    console.warn('[viewer] dropped a zero-vertex draw at the backend', {
+                        name: renderObject?.object
+                            ?.name,
+                        type: renderObject?.object
+                            ?.type,
+                    });
+                }
+                return;
+            }
+            return draw(renderObject, ...rest);
+        };
+        backend.__pascalDrawGuard = true;
+    }
     renderer.setRenderObjectFunction((object, scene, camera, geometry, material, group, lightsNode, clippingContext, passId) => {
         if (!hasDrawableGeometry(geometry)) {
             if (warnedEmptyDraw && !warnedEmptyDraw.has(geometry ?? object)) {
@@ -155,31 +185,51 @@ function ImmersiveXRBackground() {
     const background = useViewer((state) => getSceneTheme(state.sceneTheme).background);
     return _jsx("color", { args: [background], attach: "background" });
 }
+function isPendingSceneBuild(id, { nodes, rootNodeIds }) {
+    const node = nodes[id];
+    if (!node)
+        return false;
+    // Unreachable nodes (orphaned by a broken detach: the parent doesn't list
+    // them in `children`, or no parent and not a root) never render — every
+    // renderer enumerates the parent's `children` array — so no system will
+    // ever build them or clear their mark. They must not hold scene-ready
+    // hostage (observed in prod scene data: two dangling windows kept every
+    // bake of that scene waiting out the full readiness cap).
+    const parent = node.parentId ? nodes[node.parentId] : undefined;
+    const reachable = parent
+        ? parent.children?.includes(id) === true
+        : rootNodeIds.includes(id);
+    if (!reachable)
+        return false;
+    const def = nodeRegistry.get(node.type);
+    return Boolean(def?.geometry || def?.capabilities?.floorPlaced || DIRTY_BUILD_KINDS.has(node.type));
+}
 function hasPendingSceneBuildWork() {
-    const { dirtyNodes, nodes, rootNodeIds } = useScene.getState();
-    for (const id of dirtyNodes) {
-        const node = nodes[id];
-        if (!node)
-            continue;
-        // Unreachable nodes (orphaned by a broken detach: the parent doesn't list
-        // them in `children`, or no parent and not a root) never render — every
-        // renderer enumerates the parent's `children` array — so no system will
-        // ever build them or clear their mark. They must not hold scene-ready
-        // hostage (observed in prod scene data: two dangling windows kept every
-        // bake of that scene waiting out the full readiness cap).
-        const parent = node.parentId ? nodes[node.parentId] : undefined;
-        const reachable = parent
-            ? parent.children?.includes(id) === true
-            : rootNodeIds.includes(id);
-        if (!reachable)
-            continue;
-        const def = nodeRegistry.get(node.type);
-        if (def?.geometry || def?.capabilities?.floorPlaced || DIRTY_BUILD_KINDS.has(node.type)) {
+    const state = useScene.getState();
+    for (const id of state.dirtyNodes) {
+        if (isPendingSceneBuild(id, state))
             return true;
-        }
     }
     return false;
 }
+/**
+ * The scene-ready gate's own test as a count — nodes still to build or load
+ * (an item holds its mark until its model settles), 1 while the graph has
+ * not mounted. A capture waits on it, and reads a count that stops moving
+ * as a node no system will ever settle.
+ */
+export function pendingSceneBuildCount() {
+    if (!hasCommittedSceneRoot())
+        return 1;
+    const state = useScene.getState();
+    // A roof's dirty mark clears when its merged shell is queued, frames before it is built.
+    let count = getPendingRoofMergeCount();
+    for (const id of state.dirtyNodes) {
+        if (isPendingSceneBuild(id, state))
+            count++;
+    }
+    return count;
+}
 function hasCommittedSceneRoot() {
     const { nodes, rootNodeIds } = useScene.getState();
     if (rootNodeIds.length === 0)
@@ -233,7 +283,7 @@ function SceneReadyTracker({ onSceneReadyChange, sceneReadyKey, sceneReadyMaxWai
     }, 10);
     return null;
 }
-const Viewer = forwardRef(function Viewer({ children, hoverStyles = DEFAULT_HOVER_STYLES, selectionManager = 'default', perf = false, useBvh = true, renderContext = 'editor', transparent, defaultRender, isolate, sceneReadyKey, onSceneReadyChange, sceneReadyMaxWaitMs, maxFps = 50, disablePostFx = false, renderPaused = false, immersive, }, ref) {
+const Viewer = forwardRef(function Viewer({ children, hoverStyles = DEFAULT_HOVER_STYLES, selectionManager = 'default', perf = false, useBvh = true, renderContext = 'editor', transparent, defaultRender, isolate, sceneReadyKey, onSceneReadyChange, onRenderError, sceneReadyMaxWaitMs, maxFps = 50, disablePostFx = false, renderPaused = false, immersive, }, ref) {
     useEffect(() => {
         if (nodeRegistry.size === 0) {
             console.warn('[viewer] Node registry is empty. Install @pascal-app/nodes and call await loadPlugin(builtinPlugin) before mounting <Viewer>.');
@@ -259,6 +309,14 @@ const Viewer = forwardRef(function Viewer({ children, hoverStyles = DEFAULT_HOVE
     const [pointerEvents] = useState(() => choosePointerEvents());
     const [rendererInitFailed, setRendererInitFailed] = useState(false);
     const isDark = useViewer((state) => getSceneTheme(state.sceneTheme).appearance === 'dark');
+    const sceneTheme = useViewer((state) => state.sceneTheme);
+    const previousLampTheme = useRef(sceneTheme);
+    useEffect(() => {
+        useInteractive
+            .getState()
+            .setLampDefault(getSceneTheme(sceneTheme).appearance === 'dark', previousLampTheme.current !== sceneTheme);
+        previousLampTheme.current = sceneTheme;
+    }, [sceneTheme]);
     const transparentBackground = useViewer((state) => state.transparentBackground);
     // The shadows toggle drives `renderer.shadowMap.enabled` (via the Canvas
     // `shadows` prop) rather than the lights' `castShadow`: toggling castShadow
@@ -382,11 +440,11 @@ const Viewer = forwardRef(function Viewer({ children, hoverStyles = DEFAULT_HOVE
                 }, shadows: {
                     type: THREE.PCFShadowMap,
                     enabled: shadowsEnabled,
-                }, children: _jsx(ImmersiveXRPresentationProvider, { enabled: immersiveActive, children: ImmersiveSession ? (_jsx(ImmersiveSession, { children: _jsx(ViewerScene, { disablePostFx: true, hoverStyles: hoverStyles, immersiveXR: true, onRenderError: immersive.onError, onSceneReadyChange: onSceneReadyChange, perf: perf, sceneReadyKey: sceneReadyKey, sceneReadyMaxWaitMs: sceneReadyMaxWaitMs, selectionManager: selectionManager, useBvh: useBvh, SceneWrapper: immersive.Scene, children: children }) })) : (_jsxs(_Fragment, { children: [_jsx(FrameLimiter, { fps: maxFps, paused: renderPaused }), _jsx(ViewerScene, { disablePostFx: disablePostFx, hoverStyles: hoverStyles, onSceneReadyChange: onSceneReadyChange, perf: perf, sceneReadyKey: sceneReadyKey, sceneReadyMaxWaitMs: sceneReadyMaxWaitMs, selectionManager: selectionManager, useBvh: useBvh, children: children })] })) }) }, immersiveActive ? 'webgl-xr' : 'webgpu')] }));
+                }, children: _jsx(ImmersiveXRPresentationProvider, { enabled: immersiveActive, children: ImmersiveSession ? (_jsx(ImmersiveSession, { children: _jsx(ViewerScene, { disablePostFx: true, hoverStyles: hoverStyles, immersiveXR: true, renderErrorHandlers: [immersive.onError, onRenderError], onSceneReadyChange: onSceneReadyChange, perf: perf, sceneReadyKey: sceneReadyKey, sceneReadyMaxWaitMs: sceneReadyMaxWaitMs, selectionManager: selectionManager, useBvh: useBvh, SceneWrapper: immersive.Scene, children: children }) })) : (_jsxs(_Fragment, { children: [_jsx(FrameLimiter, { fps: maxFps, onFrameError: composeRenderErrorHandlers(onRenderError), paused: renderPaused }), _jsx(ViewerScene, { disablePostFx: disablePostFx, hoverStyles: hoverStyles, renderErrorHandlers: [onRenderError], onSceneReadyChange: onSceneReadyChange, perf: perf, sceneReadyKey: sceneReadyKey, sceneReadyMaxWaitMs: sceneReadyMaxWaitMs, selectionManager: selectionManager, useBvh: useBvh, children: children })] })) }) }, immersiveActive ? 'webgl-xr' : 'webgpu')] }));
 });
-function ViewerScene({ children, disablePostFx, hoverStyles, immersiveXR = false, onRenderError, onSceneReadyChange, perf, sceneReadyKey, sceneReadyMaxWaitMs, selectionManager, useBvh, SceneWrapper, }) {
+function ViewerScene({ children, disablePostFx, hoverStyles, immersiveXR = false, renderErrorHandlers, onSceneReadyChange, perf, sceneReadyKey, sceneReadyMaxWaitMs, selectionManager, useBvh, SceneWrapper, }) {
     const renderedScene = useBvh ? (_jsx(SceneBvh, { children: _jsx(SceneRenderer, {}) })) : (_jsx(SceneRenderer, {}));
     const spatialScene = (_jsxs(_Fragment, { children: [renderedScene, _jsx(FloorElevationSystem, {}), _jsx(GeometrySystem, {}), _jsx(StairOpeningSystem, {}), _jsx(RoofElevationSystem, {}), _jsx(RegisteredSystems, {}), BATCH_SPIKE_ENABLED && _jsx(BatchedMeshSpike, {}), children] }));
-    return (_jsxs(_Fragment, { children: [_jsx(ViewerCamera, { immersiveXR: immersiveXR }), immersiveXR && _jsx(ImmersiveXRBackground, {}), _jsx(PointerRaycastLayers, {}), _jsx(GPUDeviceWatcher, { intentionalWebGL: immersiveXR }), _jsx(ToneMappingExposure, {}), _jsx(SceneReadyTracker, { onSceneReadyChange: onSceneReadyChange, sceneReadyKey: sceneReadyKey, sceneReadyMaxWaitMs: sceneReadyMaxWaitMs }), _jsxs(ErrorBoundary, { fallback: null, onError: onRenderError, scope: "viewer-scene", children: [_jsx(Lights, {}), SceneWrapper ? _jsx(SceneWrapper, { children: spatialScene }) : spatialScene, !immersiveXR && _jsx(PostProcessing, { disablePostFx: disablePostFx, hoverStyles: hoverStyles }), selectionManager === 'default' && _jsx(SelectionManager, {}), (perf || PERF_OVERLAY_ENABLED) && _jsx(PerfMonitor, {}), (perf || PERF_OVERLAY_ENABLED) && _jsx(PerfActionSettleSystem, {})] })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(ViewerCamera, { immersiveXR: immersiveXR }), immersiveXR && _jsx(ImmersiveXRBackground, {}), _jsx(PointerRaycastLayers, {}), _jsx(GPUDeviceWatcher, { intentionalWebGL: immersiveXR }), _jsx(ToneMappingExposure, {}), _jsx(SceneReadyTracker, { onSceneReadyChange: onSceneReadyChange, sceneReadyKey: sceneReadyKey, sceneReadyMaxWaitMs: sceneReadyMaxWaitMs }), _jsxs(SceneErrorBoundary, { handlers: renderErrorHandlers, children: [_jsx(Lights, {}), SceneWrapper ? _jsx(SceneWrapper, { children: spatialScene }) : spatialScene, !immersiveXR && _jsx(PostProcessing, { disablePostFx: disablePostFx, hoverStyles: hoverStyles }), selectionManager === 'default' && _jsx(SelectionManager, {}), (perf || PERF_OVERLAY_ENABLED) && _jsx(PerfMonitor, {}), (perf || PERF_OVERLAY_ENABLED) && _jsx(PerfActionSettleSystem, {})] })] }));
 }
 export default Viewer;

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":"AA6EA,wBAAgB,MAAM,gCAqQrB"}
+{"version":3,"file":"lights.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/lights.tsx"],"names":[],"mappings":"AA8EA,wBAAgB,MAAM,gCAwQrB"}

package/dist/components/viewer/lights.js

@@ -3,6 +3,7 @@ import { sceneRegistry } from '@pascal-app/core';
 import { useFrame } from '@react-three/fiber';
 import { useMemo, useRef } from 'react';
 import * as THREE from 'three/webgpu';
+import { getKeyLightDirectionOverride } from '../../lib/key-light-override';
 import { SHADOW_ONLY_LAYER } from '../../lib/layers';
 import { getSceneTheme } from '../../lib/scene-themes';
 import useViewer from '../../store/use-viewer';
@@ -141,7 +142,11 @@ export function Lights() {
                 const distance = size + SHADOW_BACKOFF;
                 const near = SHADOW_BACKOFF;
                 const far = distance + size;
-                if (atmosphere) {
+                const directionOverride = getKeyLightDirectionOverride();
+                if (directionOverride) {
+                    shadowDir.current.set(...directionOverride);
+                }
+                else if (atmosphere) {
                     shadowDir.current.copy(atmosphere.sunDirection);
                 }
                 else if (themeKey) {

package/dist/components/viewer/perf-monitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"perf-monitor.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/perf-monitor.tsx"],"names":[],"mappings":"AA2CA;;;;GAIG;AACH,eAAO,MAAM,WAAW,YAuTvB,CAAA"}
+{"version":3,"file":"perf-monitor.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/perf-monitor.tsx"],"names":[],"mappings":"AA6CA;;;;GAIG;AACH,eAAO,MAAM,WAAW,YA2TvB,CAAA"}

package/dist/components/viewer/perf-monitor.js

@@ -4,7 +4,9 @@ import { useEffect, useRef } from 'react';
 import { Vector3 } from 'three';
 import { initPerfObservers } from '../../lib/perf-observers';
 import { publishPerfStats, readPerfBatchStats } from '../../lib/perf-panel-store';
+import { readPerfHistory, readPerfSelection } from '../../lib/perf-probe-state';
 import { clearPerfMeasures, drainPerfCounters } from '../../lib/perf-tracks';
+import useViewer from '../../store/use-viewer';
 const SAMPLE_INTERVAL = 0.5; // seconds between display updates
 // Walking the scene graph is the overlay's own biggest cost on large projects,
 // and the counts barely move between ticks — sample it at 2s instead of 0.5s.
@@ -73,6 +75,10 @@ export const PerfMonitor = () => {
     useEffect(() => {
         const probe = {
             batchStats: readPerfBatchStats,
+            // Undo/redo entry counts and history pause state, and the selection path: what a
+            // gesture receipt needs on a production build, where the stores have no handle.
+            history: () => readPerfHistory(useScene),
+            selection: () => readPerfSelection(useViewer),
             listNodes(type) {
                 return Object.values(useScene.getState().nodes)
                     .filter((n) => n.type === type)

package/dist/components/viewer/post-processing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"post-processing.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/post-processing.tsx"],"names":[],"mappings":"AA8CA,eAAO,MAAM,YAAY;;;CAGxB,CAAA;AAGD,eAAO,MAAM,WAAW;;;;;;;;;;;;;CAavB,CAAA;AAgED,MAAM,MAAM,UAAU,GAAG;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,UAAU,CAAA;CACpB,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;AAS9B,eAAO,MAAM,oBAAoB,EAAE,WAElC,CAAA;AA+CD,QAAA,MAAM,oBAAoB,GAAI,iCAG3B;IACD,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,SAmnBA,CAAA;AAED,eAAe,oBAAoB,CAAA"}
+{"version":3,"file":"post-processing.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/post-processing.tsx"],"names":[],"mappings":"AA+CA,eAAO,MAAM,YAAY;;;CAGxB,CAAA;AAGD,eAAO,MAAM,WAAW;;;;;;;;;;;;;CAavB,CAAA;AAgED,MAAM,MAAM,UAAU,GAAG;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,UAAU,CAAA;CACpB,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;AAS9B,eAAO,MAAM,oBAAoB,EAAE,WAElC,CAAA;AA+CD,QAAA,MAAM,oBAAoB,GAAI,iCAG3B;IACD,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,SAmnBA,CAAA;AAED,eAAe,oBAAoB,CAAA"}

package/dist/components/viewer/post-processing.js

@@ -8,10 +8,11 @@ import { RenderPipeline, TimestampQuery } from 'three/webgpu';
 import { backdropGradient, deepSkyColor, horizonHazeColor } from '../../lib/backdrop';
 import { edgeColorFor, edgeOpacityScaleFor } from '../../lib/edge-style';
 import { PERF_OVERLAY_ENABLED } from '../../lib/gpu-perf';
-import { inkedEdges } from '../../lib/ink-edges';
+import { createEdgeDepthSampler, inkedEdges } from '../../lib/ink-edges';
 import { refreshIsolation } from '../../lib/isolation';
 import { LayerPassIndex, LayerPassNode } from '../../lib/layer-pass';
 import { GRID_LAYER, OVERLAY_LAYER, SCENE_LAYER, ZONE_LAYER } from '../../lib/layers';
+import { isLiveFrameHeld } from '../../lib/live-frame-hold';
 import { mergedOutline } from '../../lib/merged-outline-node';
 import { recordPerfSample, timeSpan } from '../../lib/perf-tracks';
 import { PostProcessingResources } from '../../lib/post-processing-resources';
@@ -371,6 +372,7 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, disablePostF
             // Scene depth is shared by SSGI, ink, and outlines.
             // The normal MRT is only built when SSGI or ink needs it.
             const scenePassDepth = scenePass.getTextureNode('depth');
+            const sampleEdgeDepth = createEdgeDepthSampler(scenePassDepth, camera);
             let scenePassNormal = null;
             if (needsNormalMRT) {
                 scenePass.setMRT(mrt({
@@ -428,7 +430,7 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, disablePostF
                 // (same ≈150→350 m window as ink-edges' distanceFade) so the horizon
                 // disc and the geometry↔sky depth cliff never grow an AO band — that
                 // band read as a visible line along the horizon.
-                const aoFarFade = smoothstep(tslFloat(0.9994), tslFloat(0.9998), scenePassDepth.sample(screenUV).r);
+                const aoFarFade = smoothstep(tslFloat(0.9994), tslFloat(0.9998), sampleEdgeDepth(screenUV));
                 ao = mix(ao, tslFloat(1), aoFarFade);
                 // Composite: scene * AO + diffuse * GI
                 sceneColor = vec4(add(scenePassColor.rgb.mul(ao), add(zonePass.rgb, scenePassDiffuse.rgb.mul(gi))), contentAlpha);
@@ -439,7 +441,7 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, disablePostF
             if (inkEnabled && scenePassDepth && scenePassNormal) {
                 sceneColor = vec4(inkedEdges({
                     sceneRgb: sceneColor.rgb,
-                    depthTex: scenePassDepth,
+                    sampleDepth: sampleEdgeDepth,
                     normalTex: scenePassNormal,
                     inkColor: inkColorUniform.current,
                     radius: inkRadius,
@@ -574,6 +576,9 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, disablePostF
         if (size.width < 1 || size.height < 1) {
             return;
         }
+        // A capture is working on the shared scene: the canvas keeps its last frame.
+        if (isLiveFrameHeld())
+            return;
         // `?disable=draw`: nothing downstream wants pixels — render an EMPTY scene
         // instead of the real one. This is the only render call (positive-priority
         // useFrame subscribers already disable R3F's automatic render), so the real

package/dist/components/viewer/registered-systems.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registered-systems.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/registered-systems.tsx"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,uCAgChC"}
+{"version":3,"file":"registered-systems.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/registered-systems.tsx"],"names":[],"mappings":"AAoDA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,uCAkChC"}

package/dist/components/viewer/registered-systems.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { createSceneApi, isNodeKindEnabled, nodeRegistry, useRegistryVersion, useScene, } from '@pascal-app/core';
-import { lazy, Suspense, useMemo } from 'react';
+import { Component, lazy, Suspense, useMemo } from 'react';
 const DEFAULT_PRIORITY = 5;
 const lazyCache = new WeakMap();
 function loadSystem(def) {
@@ -14,6 +14,20 @@ function loadSystem(def) {
     lazyCache.set(def.system.module, Comp);
     return Comp;
 }
+class SystemErrorBoundary extends Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error) {
+        if (process.env.NODE_ENV !== 'production') {
+            console.error(`[viewer] Disabled system ${this.props.systemId}`, error);
+        }
+    }
+    render() {
+        return this.state.failed ? null : this.props.children;
+    }
+}
 /**
  * Mounts every registered node kind's system component, ordered by
  * `system.priority` (default {@link DEFAULT_PRIORITY}).
@@ -56,6 +70,6 @@ export function RegisteredSystems() {
             const Comp = loadSystem(def);
             if (!Comp)
                 return null;
-            return (_jsx(Suspense, { fallback: null, children: _jsx(Comp, { sceneApi: sceneApi }) }, `registered-system:${kind}`));
+            return (_jsx(SystemErrorBoundary, { systemId: kind, children: _jsx(Suspense, { fallback: null, children: _jsx(Comp, { sceneApi: sceneApi }) }) }, `registered-system:${kind}`));
         }) }));
 }

package/dist/components/viewer/render-error.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+type RenderErrorHandler = ((cause: unknown) => void) | undefined;
+/**
+ * One handler that notifies every given handler (the immersive session's and
+ * the host's), or undefined when there is none. A handler that throws is
+ * logged and does not stop the others.
+ */
+export declare function composeRenderErrorHandlers(...handlers: RenderErrorHandler[]): RenderErrorHandler;
+/**
+ * The viewer-scene error boundary: a node renderer or system that throws while
+ * rendering renders nothing in its place, and every handler hears about it.
+ */
+export declare function SceneErrorBoundary({ handlers, children, }: {
+    handlers: RenderErrorHandler[];
+    children: ReactNode;
+}): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=render-error.d.ts.map

package/dist/components/viewer/render-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-error.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/render-error.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;AAEhE;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,QAAQ,EAAE,kBAAkB,EAAE,GAAG,kBAAkB,CAYhG;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,kBAAkB,EAAE,CAAA;IAC9B,QAAQ,EAAE,SAAS,CAAA;CACpB,+BAUA"}

package/dist/components/viewer/render-error.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ErrorBoundary } from '../error-boundary';
+/**
+ * One handler that notifies every given handler (the immersive session's and
+ * the host's), or undefined when there is none. A handler that throws is
+ * logged and does not stop the others.
+ */
+export function composeRenderErrorHandlers(...handlers) {
+    const present = handlers.filter((handler) => handler !== undefined);
+    if (present.length === 0)
+        return;
+    return (cause) => {
+        for (const handler of present) {
+            try {
+                handler(cause);
+            }
+            catch (error) {
+                console.error('[viewer] a render-error handler threw', error);
+            }
+        }
+    };
+}
+/**
+ * The viewer-scene error boundary: a node renderer or system that throws while
+ * rendering renders nothing in its place, and every handler hears about it.
+ */
+export function SceneErrorBoundary({ handlers, children, }) {
+    return (_jsx(ErrorBoundary, { fallback: null, onError: composeRenderErrorHandlers(...handlers), scope: "viewer-scene", children: children }));
+}

package/dist/components/viewer/scene-ground-replacement.d.ts

@@ -1,5 +1,11 @@
+import type { Scene } from 'three';
 /** Whether modeled exterior ground replaces this scene's fallback horizon disc. */
 export declare function useSceneGroundReplacement(): boolean;
+/**
+ * The same claim from outside React (a map layer that hangs its own meshes on
+ * the scene): returns the release. The last release restores the fallback.
+ */
+export declare function claimSceneGround(scene: Scene): () => void;
 /** Mount alongside replacement ground. The last release restores the fallback. */
 export declare function SceneGroundReplacement(): null;
 //# sourceMappingURL=scene-ground-replacement.d.ts.map

package/dist/components/viewer/scene-ground-replacement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-ground-replacement.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/scene-ground-replacement.tsx"],"names":[],"mappings":"AAoBA,mFAAmF;AACnF,wBAAgB,yBAAyB,IAAI,OAAO,CAInD;AAED,kFAAkF;AAClF,wBAAgB,sBAAsB,SAarC"}
+{"version":3,"file":"scene-ground-replacement.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/scene-ground-replacement.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAA;AAgBlC,mFAAmF;AACnF,wBAAgB,yBAAyB,IAAI,OAAO,CAInD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,IAAI,CASzD;AAED,kFAAkF;AAClF,wBAAgB,sBAAsB,SAarC"}

package/dist/components/viewer/scene-ground-replacement.js

@@ -18,6 +18,21 @@ export function useSceneGroundReplacement() {
     const store = useMemo(() => groundStore(scene), [scene]);
     return useStore(store, (state) => state.owners > 0);
 }
+/**
+ * The same claim from outside React (a map layer that hangs its own meshes on
+ * the scene): returns the release. The last release restores the fallback.
+ */
+export function claimSceneGround(scene) {
+    const store = groundStore(scene);
+    store.setState((state) => ({ owners: state.owners + 1 }));
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        store.setState((state) => ({ owners: Math.max(0, state.owners - 1) }));
+    };
+}
 /** Mount alongside replacement ground. The last release restores the fallback. */
 export function SceneGroundReplacement() {
     const scene = useThree((state) => state.scene);

package/dist/components/viewer/selection-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selection-manager.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/selection-manager.tsx"],"names":[],"mappings":"AAqSA,eAAO,MAAM,gBAAgB,mCA0G5B,CAAA"}
+{"version":3,"file":"selection-manager.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/selection-manager.tsx"],"names":[],"mappings":"AAqSA,eAAO,MAAM,gBAAgB,mCA+G5B,CAAA"}

package/dist/components/viewer/selection-manager.js

@@ -233,6 +233,10 @@ export const SelectionManager = () => {
         // re-subscribe when plugin kinds register after mount (async plugin load)
         void registryVersion;
         const onEnter = (event) => {
+            // Walkthrough is camera-only: first-person controls own hover for the
+            // interactable target, and pointer lock keeps raycasting from a frozen cursor.
+            if (useViewer.getState().walkthroughMode)
+                return;
             const strategy = getStrategy();
             if (!strategy)
                 return;
@@ -254,6 +258,8 @@ export const SelectionManager = () => {
             }
         };
         const onLeave = (event) => {
+            if (useViewer.getState().walkthroughMode)
+                return;
             const strategy = getStrategy();
             if (!strategy)
                 return;
@@ -268,6 +274,8 @@ export const SelectionManager = () => {
             }
         };
         const onClick = (event) => {
+            if (useViewer.getState().walkthroughMode)
+                return;
             const strategy = getStrategy();
             if (!strategy)
                 return;
@@ -324,6 +332,8 @@ const PointerMissedHandler = ({ clickHandledRef, }) => {
             const viewerState = useViewer.getState();
             if (viewerState.cameraDragging || viewerState.inputDragging)
                 return;
+            if (viewerState.walkthroughMode)
+                return;
             if (event.button !== 0)
                 return;
             // Use requestAnimationFrame to check after R3F event handlers

package/dist/components/viewer/viewer-camera.d.ts

@@ -9,6 +9,10 @@ export declare function applyViewerCameraClipping(camera: {
     near: number;
     updateProjectionMatrix(): void;
 }, immersiveXR: boolean): void;
+export declare function applyWalkthroughCameraClipping(camera: {
+    near: number;
+    updateProjectionMatrix(): void;
+}): () => void;
 export declare function viewerUsesPerspectiveCamera(cameraMode: string, immersiveXR: boolean): boolean;
 export declare const ViewerCamera: ({ immersiveXR }: {
     immersiveXR?: boolean;

package/dist/components/viewer/viewer-camera.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"viewer-camera.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/viewer-camera.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,OAAO,CAAA;AAOnC,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,cAWxF;AAcD,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,OAAO;;;EAExD;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,sBAAsB,IAAI,IAAI,CAAA;CAAE,EACrE,WAAW,EAAE,OAAO,QAMrB;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,WAEnF;AAED,eAAO,MAAM,YAAY,GAAI,iBAAyB;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,gCAqB9E,CAAA"}
+{"version":3,"file":"viewer-camera.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/viewer-camera.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,OAAO,CAAA;AAOnC,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,cAWxF;AAcD,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,OAAO;;;EAExD;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,sBAAsB,IAAI,IAAI,CAAA;CAAE,EACrE,WAAW,EAAE,OAAO,QAMrB;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACrD,IAAI,EAAE,MAAM,CAAA;IACZ,sBAAsB,IAAI,IAAI,CAAA;CAC/B,cASA;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,WAEnF;AAED,eAAO,MAAM,YAAY,GAAI,iBAAyB;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,gCAqB9E,CAAA"}

package/dist/components/viewer/viewer-camera.js

@@ -29,7 +29,7 @@ function ImmersiveXRViewLayers({ enabled }) {
     return null;
 }
 export function viewerCameraClipping(immersiveXR) {
-    return immersiveXR ? { far: 10_000, near: 0.001 } : { far: 1000, near: 0.1 };
+    return immersiveXR ? { far: 10_000, near: 0.001 } : { far: 1000, near: 0.3 };
 }
 export function applyViewerCameraClipping(camera, immersiveXR) {
     const clipping = viewerCameraClipping(immersiveXR);
@@ -37,6 +37,16 @@ export function applyViewerCameraClipping(camera, immersiveXR) {
     camera.near = clipping.near;
     camera.updateProjectionMatrix();
 }
+export function applyWalkthroughCameraClipping(camera) {
+    const previousNear = camera.near;
+    // The eye can approach a wall to the capsule's 0.25 m radius.
+    camera.near = Math.min(previousNear, 0.1);
+    camera.updateProjectionMatrix();
+    return () => {
+        camera.near = previousNear;
+        camera.updateProjectionMatrix();
+    };
+}
 export function viewerUsesPerspectiveCamera(cameraMode, immersiveXR) {
     return immersiveXR || cameraMode === 'perspective';
 }