@pascal-app/viewer 1.1.0 → 1.1.2

package/README.md

@@ -86,6 +86,59 @@ rendering.
 See [`fixtures/viewer-live`](../../fixtures/viewer-live) for a complete small graph and the
 isolated packed-package dev/production smoke test.
 
+## Walkthrough for live scenes
+
+`LiveWalkthroughController` is a 3D controller from the main `@pascal-app/viewer` entry.
+Mount it inside `Viewer` alongside your live graph rendered with `renderPlugin`. It is dormant
+until `useViewer.walkthroughMode` is true. `walkthroughMovement` chooses `walk` (gravity,
+BVH collision, crouch, jump and door/window/item/elevator interaction) or `drone` (free flight).
+No editor state, editing plugin or baked asset is required.
+
+```tsx
+import { LiveWalkthroughController, useFirstPersonHud, useViewer, Viewer } from '@pascal-app/viewer'
+import { WalkthroughHud } from '@pascal-app/viewer/ui'
+import { OrbitControls } from '@react-three/drei'
+
+function LiveViewer() {
+  const walking = useViewer(s => s.walkthroughMode)
+  const suspended = useViewer(s => s.walkthroughSuspended)
+  const floorLabel = useFirstPersonHud(s => s.floorLabel)
+  const zoneLabel = useFirstPersonHud(s => s.zoneLabel)
+  const interact = useFirstPersonHud(s => s.interact)
+  const exit = () => useViewer.getState().setWalkthroughMode(false)
+  return (
+    <div style={{ position: 'relative', width: '100vw', height: '100vh' }}>
+      <Viewer>
+        <OrbitControls enabled={!walking} makeDefault />
+        <LiveWalkthroughController />
+      </Viewer>
+      <button onClick={() => useViewer.getState().setWalkthroughMode(!walking)}>Walkthrough</button>
+      {walking && <WalkthroughHud floorLabel={floorLabel} zoneLabel={zoneLabel}
+        interact={interact} suspended={suspended} onExit={exit} />}
+    </div>
+  )
+}
+```
+
+Use the UI styling setup below for the HUD. Click the canvas to lock the pointer; WASD/arrows move,
+Space jumps, Shift runs, Ctrl crouches, E/R or a locked-pointer click operates the targeted object,
+and T closes it. P frees the cursor and click/P resumes. Escape or losing pointer lock exits.
+A placed spawn controls entry position and heading; otherwise the controller derives a grounded
+spawn from the camera and live collider world. Disable other camera controls while walking.
+
+The controller publishes floor, room and interaction prompts to `useFirstPersonHud`. Its main and
+`viewer/ui` exports reference the same store. Mount the HUD outside the canvas and pass those
+values explicitly. Door and drawer cues emit core `interaction:sound`; opt into playback with
+`initInteractionSounds` from `viewer/sfx`. Movement and interaction do not persist document edits.
+
+Optional `LiveWalkthroughControllerProps` let a host own framing: `paused` freezes movement/look,
+`externalFov` (a function, read when walkthrough starts and ends) leaves FOV application/restoration to the host while it returns true, `pointerInteraction={false}` reserves
+locked-pointer clicks for the host, and `suspendOnUnlock` keeps walkthrough active when pointer lock
+is lost (Escape with a free cursor exits). `onExit` runs after the controller clears
+`walkthroughMode`. Props remain current during a session without releasing pointer lock.
+For baked scenes, continue using `GlbWalkthroughController`; `DroneController` also works with
+either scene source when only free flight is needed.
+
 ## Custom Camera Controls
 
 ```typescript
@@ -242,6 +295,110 @@ function ViewerControls() {
 }
 ```
 
+## Sound effects (`@pascal-app/viewer/sfx`)
+
+Opt in to building interactions and selection/hover cues from any viewer or custom UI.
+The default files come from `https://editor.pascal.app/audios/sfx`; hosts serving the files
+locally should configure their own base URL before preloading. Importing the entry creates no
+Howl instances or interaction subscriptions. Playback starts after the browser allows audio;
+selection/hover cues stay silent until user activation and during walkthrough.
+
+```tsx
+import { useEffect } from 'react'
+import { configureViewer } from '@pascal-app/viewer'
+import { initInteractionSounds, playSound, useAudioSettings, useViewerUiSounds } from '@pascal-app/viewer/sfx'
+configureViewer({ sfxBaseUrl: '/audios/sfx' })
+function SoundControls() {
+  useEffect(() => initInteractionSounds(), [])
+  useViewerUiSounds()
+  const toggleMute = useAudioSettings(s => s.toggleMute)
+  return <button onPointerEnter={() => playSound('menuHover')} onClick={() => { playSound('menuClick'); toggleMute() }}>Toggle sound</button>
+}
+```
+
+`SOUNDS` lists the built-in cue definitions. `playSound(name, options?)` supports gain
+(`volumeMultiplier`) and stereo positioning. `preloadSounds()` warms files without playing;
+`disposeSounds()` releases the shared cache when the host runtime shuts down. Host cues can use
+`SoundDefinition` objects with the same player, including `startSoundLoop` / `stopSoundLoop`.
+`useAudioSettings` shares master/effects volumes across tabs and keeps mute per tab, preserving
+existing Pascal storage keys. Denied storage falls back to memory. Existing radio preferences
+remain in the same settings record so editor consumers continue to share one store.
+
+## Viewer UI (`@pascal-app/viewer/ui`)
+
+Pascal's read-only viewer chrome as React components: the 3D / 2D / Split stage (`ViewerStage`)
+with its read-only floor plan (`FloorplanPreview`, kept in step with the 3D camera, with its compass
+and floor picker), the controls bar (levels, walls, display, daylight, sky, walkthrough), the scene
+header (project card, breadcrumb, floor list), the hover label, the room pills, room highlight and
+selected-room callout (`ViewerRooms`), the walkthrough and drone HUDs, the loader, the selection
+model behind them
+(`applyViewerClick`, `ViewerSelectionManager`) and the primitives they are built from (`Button`,
+`DropdownMenu*`, `Popover*`, `Tooltip*`, `Switch`). The entry never imports the editor or Next.
+
+The components are styled with Tailwind v4 classes. Point Tailwind at the built entry and import
+the theme (tokens, `shadow-elevation-*`, `corner-smooth`, the loader animations):
+
+```css
+@import "tailwindcss";
+@import "@pascal-app/viewer/ui/theme.css";
+@source "../node_modules/@pascal-app/viewer/dist/ui";
+```
+
+Override any token after the import (`:root { --radius: 0.5rem }`). The docks and menus scope
+themselves with a `dark` class. Control icons load from `configureViewer({ iconsBaseUrl })` (default
+`https://editor.pascal.app/icons`); button sounds play through `@pascal-app/viewer/sfx`.
+
+```tsx
+import { LiveWalkthroughController, useViewer, Viewer } from '@pascal-app/viewer'
+import {
+  ParametricViewerRooms,
+  SceneLoader,
+  ViewerControlsBar,
+  ViewerSceneHeader,
+  ViewerSelectionManager,
+  ViewerStage,
+  WalkthroughHud,
+} from '@pascal-app/viewer/ui'
+
+function ProjectViewer({ ready, name }: { ready: boolean; name: string }) {
+  const walking = useViewer((s) => s.walkthroughMode)
+  const toggleWalk = () => useViewer.getState().setWalkthroughMode(!walking)
+  return (
+    <div className="relative h-full w-full">
+      <ViewerStage>
+        <Viewer selectionManager="custom">
+          <LiveWalkthroughController />
+          <ViewerSelectionManager />
+          <ParametricViewerRooms />
+        </Viewer>
+      </ViewerStage>
+      <ViewerSceneHeader backHref={null} linkComponent={MyLink} projectName={name} />
+      <ViewerControlsBar onWalkthroughToggle={toggleWalk} walkthroughActive={walking} />
+      {walking && <WalkthroughHud onExit={toggleWalk} />}
+      {!ready && <SceneLoader />}
+    </div>
+  )
+}
+```
+
+`ViewerStage` shows its children (the 3D canvas) in 3D, the floor plan in 2D, and both side by side
+in Split; the switcher picks among `modes` (all three by default) and Split falls back to 2D on
+narrow screens. Panning, zooming or turning the plan moves the 3D camera and the reverse, through the
+navigation pose store (`navigationSyncPoseStore`); on the 3D side, drive your drei `CameraControls`
+through `useViewerCameraNavigationSync(controlsRef)`, as Pascal's camera does
+(`synchronizeNavigation={false}` turns the link off). The plan draws each kind's `def.floorplan`,
+which `renderPlugin` carries; without a `scene` prop it reads the live scene store, and a host with
+another node source passes `scene={{ nodes, installedPlugins }}`. Picking a floor in 2D selects that
+level in the viewer. Room names show as the plan's drawn tags. Control the mode with `mode` /
+`onModeChange` or let the stage hold it (`defaultMode`).
+
+`linkComponent` renders the header's links (a plain `<a>` by default); pass your router's link,
+e.g. Next's `Link`. `ParametricViewerRooms` is `ViewerRooms` over the live scene store; a host with
+another node source (a baked scene) passes `<ViewerRooms source={{ nodes, objectFor }} />`. While
+mounted, zones draw no tinted volume: a room shows through its pill and highlight instead. The walkthrough toggle flips `walkthroughMode`; the mounted
+`LiveWalkthroughController` moves the camera. Read `useFirstPersonHud` for the HUD's room and
+interaction props, as in the live walkthrough example above.
+
 ## Asset CDN Helpers
 
 ```typescript

package/dist/components/viewer/drone-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drone-controller.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/drone-controller.tsx"],"names":[],"mappings":"AAsCA,MAAM,MAAM,oBAAoB,GAAG;IACjC,oEAAoE;IACpE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kGAAkG;IAClG,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,MAAc,EAAE,MAAM,EAAE,EAAE,oBAAoB,QAyK/E"}
+{"version":3,"file":"drone-controller.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/drone-controller.tsx"],"names":[],"mappings":"AA+BA,MAAM,MAAM,oBAAoB,GAAG;IACjC,oEAAoE;IACpE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kGAAkG;IAClG,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,MAAc,EAAE,MAAM,EAAE,EAAE,oBAAoB,QAyK/E"}

package/dist/components/viewer/drone-controller.js

@@ -3,14 +3,10 @@ import { useFrame, useThree } from '@react-three/fiber';
 import { useEffect, useRef } from 'react';
 import { Vector3 } from 'three';
 import { createDroneInput, DRONE_SLOW_MULTIPLIER, droneInputForKey, readDroneInput, seedDroneLook, stepDroneFlight, turnFirstPersonLook, } from '../../lib/drone-flight';
+import { isTypingTarget } from '../../lib/typing-target';
 import useViewer from '../../store/use-viewer';
 import { WALKTHROUGH_FOV } from './glb-walkthrough-controller';
 import { applyWalkthroughCameraClipping } from './viewer-camera';
-const TYPING_TARGET = 'input, textarea, select, [contenteditable]:not([contenteditable="false"]), [role="combobox"], [role="textbox"], [role="dialog"], [role="alertdialog"]';
-function isTypingTarget(target) {
-    const element = target;
-    return !!element && (element.isContentEditable === true || !!element.closest?.(TYPING_TARGET));
-}
 function requestLock(canvas) {
     // The request can reject asynchronously (the browser's re-lock cooldown);
     // clicking the canvas asks again.

package/dist/components/viewer/first-person/build-collider-world.d.ts

@@ -0,0 +1,14 @@
+import * as THREE from 'three';
+export declare const FIRST_PERSON_SPAWN_EYE_HEIGHT = 1.65;
+export type FirstPersonColliderWorld = {
+    mesh: THREE.Mesh;
+    bounds: THREE.Box3 | null;
+    dispose: () => void;
+};
+export type FirstPersonSpawn = {
+    position: [number, number, number];
+    yaw: number;
+};
+export declare function buildFirstPersonColliderWorldFromRegistry(): FirstPersonColliderWorld | null;
+export declare function deriveFirstPersonSpawn(camera: THREE.Camera, world: FirstPersonColliderWorld): FirstPersonSpawn;
+//# sourceMappingURL=build-collider-world.d.ts.map

package/dist/components/viewer/first-person/build-collider-world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-collider-world.d.ts","sourceRoot":"","sources":["../../../../src/components/viewer/first-person/build-collider-world.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAqB9B,eAAO,MAAM,6BAA6B,OAAmB,CAAA;AAE7D,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAA;IAChB,MAAM,EAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAwWD,wBAAgB,yCAAyC,IAAI,wBAAwB,GAAG,IAAI,CA6F3F;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,KAAK,EAAE,wBAAwB,GAC9B,gBAAgB,CA0ClB"}

package/dist/components/viewer/first-person/build-collider-world.js

@@ -0,0 +1,426 @@
+import { computeSceneBoundsXZ, coveredBelowGradeFootprints, getGarageVisibleOpeningRatio, getLevelElevations, isOperationDoorType, nodeMechanism, nodeRegistry, sceneRegistry, terrainFieldOf, useInteractive, useScene, } from '@pascal-app/core';
+import * as THREE from 'three';
+import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
+import { acceleratedRaycast, computeBoundsTree, disposeBoundsTree } from 'three-mesh-bvh';
+import { cutGroundCollider } from './ground-holes';
+import { createTerrainColliderGeometry } from './terrain-collider';
+const SKIPPED_MESH_NAMES = new Set(['cutout', 'collision-mesh']);
+const COLLIDER_NODE_CATEGORIES = new Set(['structure', 'furnish']);
+const DEDICATED_COLLIDER_NODE_TYPES = new Set(['elevator']);
+const COLLIDER_MATERIAL = new THREE.MeshBasicMaterial();
+const DOWN = new THREE.Vector3(0, -1, 0);
+const UP = new THREE.Vector3(0, 1, 0);
+const SPAWN_EYE_HEIGHT = 1.65;
+const RAYCAST_CLEARANCE = 25;
+const DOOR_LEAF_COLLIDER_DEPTH = 0.06;
+const OPERATION_DOOR_COLLIDER_OPEN_THRESHOLD = 0.85;
+const LEVEL_FALLBACK_FLOOR_THICKNESS = 0.08;
+const LEVEL_FALLBACK_FLOOR_PADDING = 2;
+const LEVEL_FALLBACK_FLOOR_MIN_SIZE = 30;
+const SITE_GROUND_COLLIDER_MIN_SIZE = 2000;
+export const FIRST_PERSON_SPAWN_EYE_HEIGHT = SPAWN_EYE_HEIGHT;
+function isMesh(object) {
+    return 'isMesh' in object && object.isMesh;
+}
+// Renderer-effective visibility: an invisible ancestor hides the whole
+// subtree at render time even when the object's own flag is true. The
+// collider world must match what's rendered — the roof keeps stale,
+// UNCUT per-segment CSG inside its hidden `segments-wrapper` (full-edit
+// exit hides the wrapper without stripping geometry), and cloning those
+// meshes would block the walkthrough player at openings the visible
+// merged shell has cut through.
+function isEffectivelyVisible(object) {
+    let current = object;
+    while (current) {
+        if (!current.visible)
+            return false;
+        current = current.parent;
+    }
+    return true;
+}
+function isColliderMaterialVisible(material) {
+    return Array.isArray(material) ? material.some((entry) => entry.visible) : material.visible;
+}
+function isGenericColliderNode(node) {
+    if (node.visible === false)
+        return false;
+    if (DEDICATED_COLLIDER_NODE_TYPES.has(node.type))
+        return false;
+    const def = nodeRegistry.get(node.type);
+    // Ceilings are a transparent mount surface for fixtures (lights, fans), not a
+    // walkable or blocking structure — the walkthrough player must pass through
+    // them rather than be held up as if standing on a floor slab.
+    if (def?.surfaceRole === 'ceiling')
+        return false;
+    return COLLIDER_NODE_CATEGORIES.has(def?.category ?? '');
+}
+function createBoxColliderGeometry(width, height, depth) {
+    const sourceGeometry = new THREE.BoxGeometry(width, height, depth).toNonIndexed();
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute('position', sourceGeometry.getAttribute('position').clone());
+    geometry.setAttribute('normal', sourceGeometry.getAttribute('normal').clone());
+    sourceGeometry.dispose();
+    return geometry;
+}
+function getVisibleLevelChildren(level, nodes) {
+    return level.children
+        .map((childId) => nodes[childId])
+        .filter((child) => Boolean(child && child.visible !== false));
+}
+function createLevelFallbackFloorGeometry(level, nodes) {
+    if (level.visible === false)
+        return null;
+    const children = getVisibleLevelChildren(level, nodes);
+    if (children.some((child) => child.type === 'slab'))
+        return null;
+    const levelObject = sceneRegistry.nodes.get(level.id);
+    if (!levelObject?.visible)
+        return null;
+    const bounds = computeSceneBoundsXZ(children);
+    const [centerX, centerZ] = bounds?.center ?? [0, 0];
+    const [boundsWidth, boundsDepth] = bounds?.size ?? [0, 0];
+    const width = Math.max(boundsWidth + LEVEL_FALLBACK_FLOOR_PADDING * 2, LEVEL_FALLBACK_FLOOR_MIN_SIZE);
+    const depth = Math.max(boundsDepth + LEVEL_FALLBACK_FLOOR_PADDING * 2, LEVEL_FALLBACK_FLOOR_MIN_SIZE);
+    const geometry = createBoxColliderGeometry(width, LEVEL_FALLBACK_FLOOR_THICKNESS, depth);
+    levelObject.updateWorldMatrix(true, false);
+    geometry.applyMatrix4(new THREE.Matrix4().makeTranslation(centerX, -LEVEL_FALLBACK_FLOOR_THICKNESS / 2, centerZ));
+    geometry.applyMatrix4(levelObject.matrixWorld);
+    return geometry;
+}
+function collectLevelFallbackFloorGeometries(nodes) {
+    const geometries = [];
+    const levelElevations = getLevelElevations(nodes);
+    for (const levelId of sceneRegistry.byType.level) {
+        const node = nodes[levelId];
+        if (node?.type !== 'level')
+            continue;
+        if (levelElevations.get(node.id)?.baseY !== 0)
+            continue;
+        const geometry = createLevelFallbackFloorGeometry(node, nodes);
+        if (geometry)
+            geometries.push(geometry);
+    }
+    return geometries;
+}
+// The visible ground is the site node's ground mesh, but `site` is a `site`
+// category node and therefore excluded from the generic collider sweep. Without
+// a dedicated collider, a spawn on the bare ground (no slab, or not parented to
+// a level that triggers the per-level fallback) has no floor to stand on and the
+// walkthrough player falls through. Derive a thin ground slab from node data (not
+// the rendered mesh) so it exists regardless of geometry-mount timing. The slab
+// is effectively unbounded (not sized to the site polygon): the ground plane must
+// keep holding the player up even after they step past the site boundary,
+// otherwise they fall below the ground plane into the void.
+//
+// A sculpted site takes the terrain path instead: the flat slab would hold the
+// player at the datum inside an excavation and bury them inside a hill. Derived
+// from the field rather than the rendered terrain mesh for the same
+// mount-timing reason as the flat slab.
+//
+// Either way the ground is cut open over what the house covers of its basement
+// (`coveredBelowGradeFootprints`, the rings the ground is drawn open over): a sheet
+// across the stairwell would hold the player at grade on the way down, with the
+// stair and the basement's floor below it. The house covers that part, so it is cut
+// whatever the view does with the ground; past it the ground is walked on as before.
+function createSiteGroundColliderGeometry(site, nodes) {
+    if (site.visible === false)
+        return null;
+    const siteObject = sceneRegistry.nodes.get(site.id);
+    if (!siteObject?.visible)
+        return null;
+    const covered = coveredBelowGradeFootprints(nodes);
+    const field = terrainFieldOf(site);
+    if (field) {
+        const terrainGeometry = createTerrainColliderGeometry(field);
+        if (terrainGeometry) {
+            const cut = cutGroundCollider(terrainGeometry, covered);
+            siteObject.updateWorldMatrix(true, false);
+            cut.applyMatrix4(siteObject.matrixWorld);
+            return cut;
+        }
+    }
+    const bounds = computeSceneBoundsXZ(nodes);
+    const [centerX, centerZ] = bounds?.center ?? [0, 0];
+    const [boundsWidth, boundsDepth] = bounds?.size ?? [0, 0];
+    const width = Math.max(boundsWidth + LEVEL_FALLBACK_FLOOR_PADDING * 2, SITE_GROUND_COLLIDER_MIN_SIZE);
+    const depth = Math.max(boundsDepth + LEVEL_FALLBACK_FLOOR_PADDING * 2, SITE_GROUND_COLLIDER_MIN_SIZE);
+    const geometry = createBoxColliderGeometry(width, LEVEL_FALLBACK_FLOOR_THICKNESS, depth);
+    siteObject.updateWorldMatrix(true, false);
+    geometry.applyMatrix4(new THREE.Matrix4().makeTranslation(centerX, -LEVEL_FALLBACK_FLOOR_THICKNESS / 2, centerZ));
+    const cut = cutGroundCollider(geometry, covered);
+    cut.applyMatrix4(siteObject.matrixWorld);
+    return cut;
+}
+function collectSiteGroundColliderGeometries(nodes) {
+    const geometries = [];
+    for (const siteId of sceneRegistry.byType.site ?? []) {
+        const node = nodes[siteId];
+        if (node?.type !== 'site')
+            continue;
+        const geometry = createSiteGroundColliderGeometry(node, nodes);
+        if (geometry)
+            geometries.push(geometry);
+    }
+    return geometries;
+}
+// Decode any attribute (interleaved, quantized/normalized integer, Float64…) into a
+// plain, non-normalized Float32Array BufferAttribute. mergeGeometries() requires every
+// merged geometry to share the same typed-array constructor for matching attributes, so
+// imported item GLBs using KHR_mesh_quantization or interleaved buffers must be coerced
+// to Float32 to match wall/slab geometry.
+function toFloat32Attribute(source) {
+    const itemSize = source.itemSize;
+    const array = new Float32Array(source.count * itemSize);
+    for (let i = 0; i < source.count; i++) {
+        const offset = i * itemSize;
+        array[offset] = source.getX(i);
+        if (itemSize > 1)
+            array[offset + 1] = source.getY(i);
+        if (itemSize > 2)
+            array[offset + 2] = source.getZ(i);
+        if (itemSize > 3)
+            array[offset + 3] = source.getW(i);
+    }
+    return new THREE.BufferAttribute(array, itemSize);
+}
+function cloneWorldGeometry(mesh) {
+    const sourceGeometry = mesh.geometry;
+    const position = sourceGeometry.getAttribute('position');
+    if (!position || position.count < 3)
+        return null;
+    const workingGeometry = sourceGeometry.index
+        ? sourceGeometry.toNonIndexed()
+        : sourceGeometry.clone();
+    const cleanGeometry = new THREE.BufferGeometry();
+    cleanGeometry.setAttribute('position', toFloat32Attribute(workingGeometry.getAttribute('position')));
+    const normal = workingGeometry.getAttribute('normal');
+    if (normal) {
+        cleanGeometry.setAttribute('normal', toFloat32Attribute(normal));
+    }
+    else {
+        cleanGeometry.computeVertexNormals();
+    }
+    cleanGeometry.applyMatrix4(mesh.matrixWorld);
+    workingGeometry.dispose();
+    const worldPosition = cleanGeometry.getAttribute('position');
+    if (!worldPosition || worldPosition.count < 3) {
+        cleanGeometry.dispose();
+        return null;
+    }
+    return cleanGeometry;
+}
+function shouldSkipColliderNode(node) {
+    if (node.type === 'window') {
+        return node.openingKind === 'opening';
+    }
+    if (node.type !== 'door')
+        return false;
+    if (!node.segments.length)
+        return true;
+    if (node.openingKind === 'opening')
+        return true;
+    return node.segments.every((segment) => segment.type === 'empty');
+}
+function createDoorLeafColliderGeometry(root, node) {
+    const hasLeafContent = node.segments.some((segment) => segment.type !== 'empty');
+    if (!hasLeafContent)
+        return null;
+    // A door built from a script opens by its model's `open` clip, which the mechanism runs through
+    // its own control: the native `operationState` below never moves for it, so open is read there.
+    if (node.source && nodeMechanism(node)?.isOn(node, useInteractive.getState()))
+        return null;
+    const leafW = node.width - 2 * node.frameThickness;
+    const leafH = node.height - node.frameThickness;
+    if (leafW <= 0 || leafH <= 0)
+        return null;
+    const leafCenterY = -node.frameThickness / 2;
+    const runtimeDoorState = useInteractive.getState().doors[node.id];
+    const operationState = runtimeDoorState?.operationState ?? node.operationState;
+    const swingAngle = runtimeDoorState?.swingAngle ?? node.swingAngle;
+    root.updateWorldMatrix(true, false);
+    if (node.doorType === 'garage-sectional' || node.doorType === 'garage-rollup') {
+        const openAmount = getGarageVisibleOpeningRatio(node.doorType, operationState);
+        const visibleHeight = leafH * (1 - openAmount);
+        if (visibleHeight <= 0.12)
+            return null;
+        const geometry = createBoxColliderGeometry(leafW, visibleHeight, DOOR_LEAF_COLLIDER_DEPTH);
+        const visibleCenterY = leafCenterY - leafH / 2 + visibleHeight / 2;
+        geometry.applyMatrix4(root.matrixWorld.clone().multiply(new THREE.Matrix4().makeTranslation(0, visibleCenterY, 0)));
+        return geometry;
+    }
+    if (isOperationDoorType(node.doorType) &&
+        (operationState ?? 0) >= OPERATION_DOOR_COLLIDER_OPEN_THRESHOLD) {
+        return null;
+    }
+    const hingeX = node.hingesSide === 'right' ? leafW / 2 : -leafW / 2;
+    const swingDirectionSign = node.swingDirection === 'inward' ? 1 : -1;
+    const hingeDirectionSign = node.hingesSide === 'right' ? 1 : -1;
+    const clampedSwingAngle = Math.max(0, Math.min(Math.PI / 2, swingAngle ?? 0));
+    const leafSwingRotation = clampedSwingAngle * swingDirectionSign * hingeDirectionSign;
+    const geometry = createBoxColliderGeometry(leafW, leafH, DOOR_LEAF_COLLIDER_DEPTH);
+    const matrix = root.matrixWorld
+        .clone()
+        .multiply(new THREE.Matrix4().makeTranslation(hingeX, 0, 0))
+        .multiply(new THREE.Matrix4().makeRotationY(leafSwingRotation))
+        .multiply(new THREE.Matrix4().makeTranslation(-hingeX, leafCenterY, 0));
+    geometry.applyMatrix4(matrix);
+    return geometry;
+}
+function buildRegisteredColliderNodeIds(nodes) {
+    const nodeIds = new Set();
+    for (const nodeId of sceneRegistry.nodes.keys()) {
+        const node = nodes[nodeId];
+        if (!node || !isGenericColliderNode(node))
+            continue;
+        if (shouldSkipColliderNode(node))
+            continue;
+        nodeIds.add(nodeId);
+    }
+    return nodeIds;
+}
+function collectColliderGeometriesFromNode(root, rootNodeId, visitedMeshes, registeredObjectIds, registeredColliderNodeIds) {
+    const geometries = [];
+    const visit = (object) => {
+        if (visitedMeshes.has(object))
+            return;
+        visitedMeshes.add(object);
+        // Prune hidden subtrees — children of an invisible group never render,
+        // so they must not collide either (see isEffectivelyVisible). An idle joint
+        // tree draws a merged rest pose that includes its moving parts; its hidden
+        // split group holds the same static parts apart from them.
+        if (object.userData.pascalProceduralRest)
+            return;
+        if (!object.visible && !object.userData.pascalProceduralSplit)
+            return;
+        if (object.userData.proceduralMotion)
+            return;
+        if (isMesh(object) &&
+            isColliderMaterialVisible(object.material) &&
+            !SKIPPED_MESH_NAMES.has(object.name)) {
+            const geometry = cloneWorldGeometry(object);
+            if (geometry) {
+                geometries.push(geometry);
+            }
+        }
+        for (const child of object.children) {
+            const childNodeId = registeredObjectIds.get(child);
+            if (childNodeId && childNodeId !== rootNodeId && registeredColliderNodeIds.has(childNodeId)) {
+                continue;
+            }
+            visit(child);
+        }
+    };
+    visit(root);
+    return geometries;
+}
+export function buildFirstPersonColliderWorldFromRegistry() {
+    const nodes = useScene.getState().nodes;
+    const geometries = [];
+    const visitedMeshes = new WeakSet();
+    const registeredColliderNodeIds = buildRegisteredColliderNodeIds(nodes);
+    const registeredObjectIds = new Map();
+    for (const [nodeId, object] of sceneRegistry.nodes) {
+        registeredObjectIds.set(object, nodeId);
+    }
+    for (const nodeId of registeredColliderNodeIds) {
+        const node = nodes[nodeId];
+        if (!node)
+            continue;
+        const root = sceneRegistry.nodes.get(nodeId);
+        if (!root)
+            continue;
+        // Registered objects can sit inside a hidden wrapper (roof segments
+        // under `segments-wrapper`) — the per-node traversal starts AT the
+        // object, so the ancestor chain must be checked here.
+        if (!isEffectivelyVisible(root))
+            continue;
+        if (node.type === 'door') {
+            const doorGeometry = createDoorLeafColliderGeometry(root, node);
+            if (doorGeometry) {
+                geometries.push(doorGeometry);
+            }
+            continue;
+        }
+        root.updateMatrixWorld(true);
+        geometries.push(...collectColliderGeometriesFromNode(root, nodeId, visitedMeshes, registeredObjectIds, registeredColliderNodeIds));
+    }
+    geometries.push(...collectLevelFallbackFloorGeometries(nodes));
+    geometries.push(...collectSiteGroundColliderGeometries(nodes));
+    if (geometries.length === 0) {
+        return null;
+    }
+    const mergedGeometry = mergeGeometries(geometries, false);
+    for (const geometry of geometries) {
+        geometry.dispose();
+    }
+    if (!mergedGeometry || mergedGeometry.getAttribute('position') == null) {
+        mergedGeometry?.dispose();
+        return null;
+    }
+    const bvhGeometry = mergedGeometry;
+    bvhGeometry.computeBoundsTree = computeBoundsTree;
+    bvhGeometry.disposeBoundsTree = disposeBoundsTree;
+    bvhGeometry.computeBoundsTree?.({
+        targetLeafSize: 12,
+        strategy: 0,
+    });
+    bvhGeometry.computeBoundingBox();
+    const mesh = new THREE.Mesh(bvhGeometry, COLLIDER_MATERIAL);
+    mesh.raycast = acceleratedRaycast;
+    mesh.visible = true;
+    mesh.userData = {
+        type: 'STATIC',
+        friction: 0.8,
+        restitution: 0.05,
+        excludeFloatHit: false,
+        excludeCollisionCheck: false,
+    };
+    mesh.updateMatrixWorld(true);
+    return {
+        mesh,
+        bounds: bvhGeometry.boundingBox?.clone() ?? null,
+        dispose: () => {
+            bvhGeometry.disposeBoundsTree?.();
+            bvhGeometry.dispose();
+        },
+    };
+}
+export function deriveFirstPersonSpawn(camera, world) {
+    const direction = new THREE.Vector3();
+    camera.getWorldDirection(direction);
+    direction.y = 0;
+    if (direction.lengthSq() < 1e-6) {
+        direction.set(0, 0, -1);
+    }
+    else {
+        direction.normalize();
+    }
+    const yaw = Math.atan2(-direction.x, -direction.z);
+    const raycaster = new THREE.Raycaster();
+    const candidates = [[camera.position.x, camera.position.z]];
+    const boundsCenter = world.bounds?.getCenter(new THREE.Vector3());
+    if (boundsCenter) {
+        candidates.push([boundsCenter.x, boundsCenter.z]);
+    }
+    for (const [x, z] of candidates) {
+        const topY = Math.max(world.bounds?.max.y ?? camera.position.y, camera.position.y) + RAYCAST_CLEARANCE;
+        raycaster.set(new THREE.Vector3(x, topY, z), DOWN);
+        const intersections = raycaster.intersectObject(world.mesh, false);
+        const hit = intersections.find((intersection) => {
+            if (!intersection.face)
+                return true;
+            const normal = intersection.face.normal.clone().transformDirection(world.mesh.matrixWorld);
+            return normal.dot(UP) > 0.2;
+        });
+        if (hit) {
+            return {
+                position: [hit.point.x, hit.point.y + SPAWN_EYE_HEIGHT, hit.point.z],
+                yaw,
+            };
+        }
+    }
+    return {
+        position: [camera.position.x, Math.max(camera.position.y, SPAWN_EYE_HEIGHT), camera.position.z],
+        yaw,
+    };
+}

package/dist/components/viewer/first-person/ground-holes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Holes in the site ground's collision geometry.
+ *
+ * The walkthrough stands on one merged BVH mesh, and the site's ground (a flat slab, or the terrain)
+ * is a sheet across the whole lot. Where the house stands over a basement the ground is drawn open
+ * (`coveredBelowGradeFootprints`), but the sheet under the stairwell stayed: the player descending
+ * the stair met it at grade and could go no deeper. Cutting the collider by the same rings the
+ * ground is drawn open over lets the player follow the building's floors and stairs there.
+ *
+ * Every triangle that reaches a hole is cut against it in plan; the pieces keep the source
+ * triangle's plane (height and normal interpolated from its corners) and its facing, so the cut
+ * surface is exactly the one the uncut triangle was.
+ */
+import { type Ring } from '@pascal-app/core';
+import { BufferGeometry } from 'three';
+/**
+ * `geometry` (non-indexed, `position` and `normal`, in the frame the rings are in) without the part
+ * of it that lies over `holes`. A triangle the clip fails on is kept whole: the ground closed is
+ * the safe side. The geometry is returned as it is when there are no holes.
+ */
+export declare function cutGroundCollider(geometry: BufferGeometry, holes: readonly Ring[]): BufferGeometry;
+//# sourceMappingURL=ground-holes.d.ts.map

package/dist/components/viewer/first-person/ground-holes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-holes.d.ts","sourceRoot":"","sources":["../../../../src/components/viewer/first-person/ground-holes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAc,KAAK,IAAI,EAAS,MAAM,kBAAkB,CAAA;AAC/D,OAAO,EAAmB,cAAc,EAAuB,MAAM,OAAO,CAAA;AAY5E;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,SAAS,IAAI,EAAE,GACrB,cAAc,CA8FhB"}