@pascal-app/viewer 1.1.0 → 1.1.1

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

@@ -0,0 +1,1449 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { closeDoorOpenState, closeWindowOpenState, DOOR_SWING_OPEN_ANGLE, emitter, getDisplayedDoorValue, getDisplayedWindowValue, getElevatorCabCenterZ, getElevatorCabDepth, getElevatorCabWidth, getElevatorDoorLeafSides, getElevatorDoorLeafWidth, getElevatorDoorLeafX, getElevatorShaftDepth, getElevatorShaftWallThickness, getElevatorShaftWidth, getLevelDisplayName, getLevelElevations, getResolvedElevatorDoorStyle, isOperableWindowType, isOperationDoorType, itemPrompt, nodeMechanism, openElevatorDoor, operateItem, pointInPolygon2D, requestElevatorLevel, resolveElevatorDispatchTarget, resolveElevatorLevels, sceneRegistry, toggleDoorOpenState, toggleNodeMechanism, toggleWindowOpenState, useInteractive, useScene, } from '@pascal-app/core';
+import { operablePartFor, operableParts, } from '@pascal-app/core/procedural-items';
+import { KeyboardControls } from '@react-three/drei';
+import { useFrame, useThree } from '@react-three/fiber';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Box3, BoxGeometry, Euler, Matrix4, Mesh, MeshBasicMaterial, Ray, Raycaster, Vector2, Vector3, } from 'three';
+import { acceleratedRaycast, computeBoundsTree, disposeBoundsTree } from 'three-mesh-bvh';
+import { createDroneInput, DRONE_SLOW_MULTIPLIER, seedDroneLook, stepDroneFlight, turnFirstPersonLook, } from '../../lib/drone-flight';
+import { setSurfaceRaycastLayers } from '../../lib/layers';
+import { isTypingTarget } from '../../lib/typing-target';
+import { useFirstPersonHud } from '../../store/use-first-person-hud';
+import useViewer from '../../store/use-viewer';
+import { openingSettled, proceduralSettled } from '../../systems/interactive/opening-settled';
+import BVHEcctrl, {} from './bvh-ecctrl';
+import { buildFirstPersonColliderWorldFromRegistry, deriveFirstPersonSpawn, FIRST_PERSON_SPAWN_EYE_HEIGHT, } from './first-person/build-collider-world';
+import { hasNativeLeaf, mechanismHudInteract, mechanismTargetIds, nativeOpeningIds, watchScriptedDoors, } from './first-person/mechanism-targets';
+import { CROUCH_CAPSULE, CROUCH_EYE_OFFSET, CROUCH_FLOAT_HEIGHT, CROUCH_RUN_SPEED, CROUCH_WALK_SPEED, EYE_LERP_SPEED, STAND_CAPSULE, STAND_CLEARANCE, STAND_FLOAT_HEIGHT, WALKTHROUGH_FOV, } from './glb-walkthrough-controller';
+import { applyWalkthroughCameraClipping } from './viewer-camera';
+const CAMERA_EYE_OFFSET = 0.45;
+const CONTROLLER_CENTER_FROM_EYE = 0.85;
+const DOOR_INTERACTION_DISTANCE = 2.5;
+const DOOR_LEAF_INTERACTION_DEPTH = 0.08;
+const ELEVATOR_RIDE_HORIZONTAL_PADDING = 0.18;
+const ELEVATOR_COLLIDER_HORIZONTAL_PADDING = 0.14;
+const ELEVATOR_COLLIDER_FLOOR_THICKNESS = 0.08;
+const ELEVATOR_COLLIDER_DOOR_DEPTH = 0.12;
+const ELEVATOR_ENTRY_DOOR_OPEN_THRESHOLD = 0.72;
+const VOID_FALL_RESPAWN_DEPTH = 12;
+const HUD_LABEL_SAMPLE_FRAMES = 10;
+const movementKeyboardBindings = [
+    { name: 'forward', keys: ['ArrowUp', 'KeyW'] },
+    { name: 'backward', keys: ['ArrowDown', 'KeyS'] },
+    { name: 'leftward', keys: ['ArrowLeft', 'KeyA'] },
+    { name: 'rightward', keys: ['ArrowRight', 'KeyD'] },
+    { name: 'jump', keys: ['Space'] },
+    { name: 'run', keys: ['ShiftLeft', 'ShiftRight'] },
+];
+const keyboardMap = movementKeyboardBindings;
+const movementKeyToName = new Map(movementKeyboardBindings.flatMap(({ name, keys }) => keys.map((key) => [key, name])));
+const inactiveMovementInput = {
+    backward: false,
+    forward: false,
+    jump: false,
+    leftward: false,
+    rightward: false,
+    run: false,
+};
+function getMovementInputForKey(code, active) {
+    const name = movementKeyToName.get(code);
+    return name ? { [name]: active } : null;
+}
+function focusFirstPersonCanvas(canvas) {
+    const activeElement = document.activeElement;
+    if (activeElement instanceof HTMLElement && !canvas.contains(activeElement)) {
+        activeElement.blur();
+    }
+    if (!canvas.hasAttribute('tabindex')) {
+        canvas.tabIndex = -1;
+    }
+    canvas.focus({ preventScroll: true });
+}
+const cameraOffset = new Vector3();
+const cameraEuler = new Euler(0, 0, 0, 'YXZ');
+const droneInput = createDroneInput();
+const standClearanceRaycaster = new Raycaster();
+const standClearanceUp = new Vector3(0, 1, 0);
+const centerScreenPoint = new Vector2(0, 0);
+const doorInteractionRaycaster = new Raycaster();
+setSurfaceRaycastLayers(doorInteractionRaycaster.layers);
+const proceduralInteractionRaycaster = new Raycaster();
+setSurfaceRaycastLayers(proceduralInteractionRaycaster.layers);
+const doorLeafBox = new Box3();
+const doorLeafInverseMatrix = new Matrix4();
+const doorLeafLocalHit = new Vector3();
+const doorLeafLocalRay = new Ray();
+const doorLeafMatrix = new Matrix4();
+const doorLeafWorldHit = new Vector3();
+const doorOpeningBox = new Box3();
+const doorOpeningInverseMatrix = new Matrix4();
+const doorOpeningLocalHit = new Vector3();
+const doorOpeningLocalRay = new Ray();
+const doorOpeningMatrix = new Matrix4();
+const doorOpeningWorldHit = new Vector3();
+const elevatorLocalControllerPosition = new Vector3();
+const elevatorInteractionRaycaster = new Raycaster();
+const elevatorColliderMatrix = new Matrix4();
+const elevatorColliderLocalMatrix = new Matrix4();
+const elevatorLocalEyePosition = new Vector3();
+const elevatorWorldControllerPosition = new Vector3();
+const elevatorColliderMaterial = new MeshBasicMaterial({ visible: false });
+const spawnWorldPosition = new Vector3();
+const spawnWorldEuler = new Euler(0, 0, 0, 'YXZ');
+const windowInteractionRaycaster = new Raycaster();
+setSurfaceRaycastLayers(windowInteractionRaycaster.layers);
+const hudBuildingLocalEyePosition = new Vector3();
+const hudWorldEyePosition = new Vector3();
+const hudLevelBounds = new Box3();
+function getLevelChildren(level, nodes) {
+    const childIds = new Set(level.children);
+    return Object.values(nodes).filter((node) => node.parentId === level.id || childIds.has(node.id));
+}
+function pointIsInLevelFootprint(point, worldPoint, level, nodes) {
+    const children = getLevelChildren(level, nodes);
+    const slabs = children.filter((node) => node.type === 'slab' && node.polygon.length >= 3);
+    const zones = children.filter((node) => node.type === 'zone' && node.polygon.length >= 3);
+    if (slabs.length > 0) {
+        return slabs.some((slab) => pointInPolygon2D(point, slab.polygon) &&
+            !slab.holes.some((hole) => pointInPolygon2D(point, hole)));
+    }
+    if (zones.length > 0) {
+        if (zones.some((zone) => pointInPolygon2D(point, zone.polygon)))
+            return true;
+    }
+    const levelObject = sceneRegistry.nodes.get(level.id);
+    if (!levelObject)
+        return false;
+    hudLevelBounds.setFromObject(levelObject);
+    return (!hudLevelBounds.isEmpty() &&
+        worldPoint.x >= hudLevelBounds.min.x &&
+        worldPoint.x <= hudLevelBounds.max.x &&
+        worldPoint.z >= hudLevelBounds.min.z &&
+        worldPoint.z <= hudLevelBounds.max.z);
+}
+function resolveFirstPersonHudLabels(worldPoint) {
+    const nodes = useScene.getState().nodes;
+    const levelElevations = getLevelElevations(nodes);
+    for (const building of Object.values(nodes)) {
+        if (building.type !== 'building')
+            continue;
+        const buildingObject = sceneRegistry.nodes.get(building.id);
+        if (!buildingObject)
+            continue;
+        buildingObject.updateWorldMatrix(true, true);
+        hudBuildingLocalEyePosition.copy(worldPoint);
+        buildingObject.worldToLocal(hudBuildingLocalEyePosition);
+        const levels = Object.values(nodes)
+            .filter((node) => node.type === 'level')
+            .filter((level) => levelElevations.get(level.id)?.buildingId === building.id)
+            .sort((left, right) => (levelElevations.get(left.id)?.baseY ?? 0) - (levelElevations.get(right.id)?.baseY ?? 0));
+        let activeLevel = null;
+        for (const level of levels) {
+            const elevation = levelElevations.get(level.id);
+            if (!elevation)
+                continue;
+            if (hudBuildingLocalEyePosition.y >= elevation.baseY - 0.5 &&
+                hudBuildingLocalEyePosition.y < elevation.baseY + elevation.height + 0.5) {
+                activeLevel = level;
+            }
+        }
+        if (!activeLevel)
+            continue;
+        const point = [hudBuildingLocalEyePosition.x, hudBuildingLocalEyePosition.z];
+        if (!pointIsInLevelFootprint(point, worldPoint, activeLevel, nodes))
+            continue;
+        const zone = getLevelChildren(activeLevel, nodes).find((node) => node.type === 'zone' && node.polygon.length >= 3 && pointInPolygon2D(point, node.polygon));
+        return {
+            floorLabel: getLevelDisplayName(activeLevel),
+            zoneLabel: zone?.type === 'zone' ? zone.name : null,
+        };
+    }
+    return { floorLabel: null, zoneLabel: null };
+}
+function resolveHudInteract(target) {
+    if (!target)
+        return null;
+    if (target.type === 'elevator') {
+        return {
+            label: target.action === 'open-door' ? 'door button' : 'elevator button',
+            verb: 'press',
+        };
+    }
+    const node = useScene.getState().nodes[target.id];
+    if (target.type === 'mechanism')
+        return node ? mechanismHudInteract(node) : null;
+    if (target.type === 'item') {
+        if (node?.type !== 'item' || !node.asset.interactive)
+            return null;
+        const { label, verb } = itemPrompt(target.id, node.name ?? node.asset.name, node.asset.interactive);
+        return { label, verb };
+    }
+    if (target.type === 'procedural') {
+        if (node?.type !== 'procedural-item')
+            return null;
+        const procedural = node;
+        const parts = operableParts(procedural.recipe);
+        if (parts.length === 0 && procedural.recipe.parts.some((part) => part.light)) {
+            const state = useInteractive.getState();
+            const isOn = state.procedural[target.id]?.lightsOn ?? state.lampDefault;
+            return { label: procedural.name ?? 'Lights', verb: isOn ? 'turn off' : 'turn on' };
+        }
+        const part = target.partId ? parts.find((entry) => entry.id === target.partId) : undefined;
+        const active = useInteractive.getState().procedural[target.id]?.parts;
+        const isOn = part ? Boolean(active?.[part.id]) : parts.some((entry) => active?.[entry.id]);
+        const kind = part?.kind ?? (parts.every((entry) => entry.kind === 'spin') ? 'spin' : 'hinge');
+        return {
+            label: part?.label ?? procedural.name ?? 'item',
+            verb: kind === 'spin' ? (isOn ? 'turn off' : 'turn on') : isOn ? 'close' : 'open',
+        };
+    }
+    if (target.type === 'window') {
+        if (node?.type !== 'window')
+            return null;
+        const isOpen = getDisplayedWindowValue(target.id, node.operationState) > 0;
+        return { label: node.name || 'window', verb: isOpen ? 'close' : 'open' };
+    }
+    if (node?.type !== 'door')
+        return null;
+    const isOpen = isOperationDoorType(node.doorType)
+        ? getDisplayedDoorValue(target.id, 'operationState', node.operationState) > 0
+        : getDisplayedDoorValue(target.id, 'swingAngle', node.swingAngle) > 0;
+    return { label: node.name || 'door', verb: isOpen ? 'close' : 'open' };
+}
+/** E plays what the viewer's callout plays for the same door, window or switch. */
+function playTargetSound(target) {
+    const verb = resolveHudInteract(target)?.verb;
+    if (!verb || verb === 'press')
+        return;
+    const node = useScene.getState().nodes[target.id];
+    // A recipe's door or lid swings and claps shut, its drawer slides; both land on the motion's end.
+    if (target.type === 'procedural' && (verb === 'open' || verb === 'close')) {
+        if (verb === 'open') {
+            emitter.emit('interaction:sound', 'panel-open');
+            return;
+        }
+        if (target.kind !== 'slide')
+            emitter.emit('interaction:sound', 'panel-swing');
+        void proceduralSettled(target.id).then(() => emitter.emit('interaction:sound', 'panel-close'));
+        return;
+    }
+    let sound;
+    if (verb !== 'open' && verb !== 'close')
+        sound = verb === 'turn on' || verb === 'play' ? 'switch-on' : 'switch-off';
+    else if (node?.type === 'door' && node.doorType?.startsWith('garage-'))
+        sound = 'garage';
+    else if (node?.type === 'window')
+        sound = verb === 'open' ? 'window-open' : 'window-close';
+    else
+        sound = verb === 'open' ? 'door-open' : 'door-close';
+    // A built-in leaf or sash swings shut, then latches on the frame it lands.
+    if ((sound === 'door-close' || sound === 'window-close') &&
+        (target.type === 'door' || target.type === 'window') &&
+        node) {
+        emitter.emit('interaction:sound', sound === 'door-close' ? 'door-swing' : 'window-swing');
+        void openingSettled(node).then(() => emitter.emit('interaction:sound', sound));
+        return;
+    }
+    emitter.emit('interaction:sound', sound);
+}
+function resolveElevatorButtonTarget(object) {
+    let current = object;
+    while (current) {
+        const candidate = current.userData.elevatorButton;
+        if (candidate?.disabled === true) {
+            return null;
+        }
+        if (typeof candidate?.elevatorId === 'string' && candidate.kind === 'cab') {
+            const action = candidate.action === 'open-door' ? 'open-door' : 'request-level';
+            if (action === 'open-door') {
+                return {
+                    action,
+                    buttonKind: candidate.kind,
+                    elevatorId: candidate.elevatorId,
+                };
+            }
+        }
+        if (typeof candidate?.elevatorId === 'string' &&
+            typeof candidate.levelId === 'string' &&
+            (candidate.kind === 'cab' || candidate.kind === 'landing')) {
+            return {
+                action: 'request-level',
+                buttonKind: candidate.kind,
+                elevatorId: candidate.elevatorId,
+                levelId: candidate.levelId,
+            };
+        }
+        current = current.parent;
+    }
+    return null;
+}
+function getInteractableTargetKey(target) {
+    if (!target)
+        return null;
+    return target.type === 'elevator'
+        ? `${target.type}:${target.id}:${target.levelId}`
+        : target.type === 'procedural'
+            ? `${target.type}:${target.id}:${target.partId ?? 'all'}`
+            : `${target.type}:${target.id}`;
+}
+function isDynamicElevatorCollider(kind) {
+    return kind.startsWith('cab-') || kind.startsWith('landing-door');
+}
+function isInsideElevatorCab(elevator, runtime, localEyePosition) {
+    const halfWidth = getElevatorCabWidth(elevator) / 2 - ELEVATOR_RIDE_HORIZONTAL_PADDING;
+    const halfDepth = getElevatorCabDepth(elevator) / 2 - ELEVATOR_RIDE_HORIZONTAL_PADDING;
+    const cabCenterZ = getElevatorCabCenterZ(elevator);
+    const cabHeight = Math.max(elevator.cabHeight, 1.4);
+    return (Math.abs(localEyePosition.x) <= Math.max(halfWidth, 0.24) &&
+        Math.abs(localEyePosition.z - cabCenterZ) <= Math.max(halfDepth, 0.24) &&
+        localEyePosition.y >= runtime.carY + 0.35 &&
+        localEyePosition.y <= runtime.carY + cabHeight + 0.7);
+}
+function createElevatorColliderMesh(elevatorId, kind, size, localPosition, userData = {}) {
+    const geometry = new BoxGeometry(size[0], size[1], size[2]);
+    const bvhGeometry = geometry;
+    bvhGeometry.computeBoundsTree = computeBoundsTree;
+    bvhGeometry.disposeBoundsTree = disposeBoundsTree;
+    bvhGeometry.computeBoundsTree?.({
+        targetLeafSize: 12,
+        strategy: 0,
+    });
+    bvhGeometry.computeBoundingBox();
+    const mesh = new Mesh(bvhGeometry, elevatorColliderMaterial);
+    mesh.raycast = acceleratedRaycast;
+    mesh.matrixAutoUpdate = false;
+    mesh.visible = true;
+    mesh.userData = {
+        ...userData,
+        dynamic: isDynamicElevatorCollider(kind),
+        elevatorId,
+        excludeCollisionCheck: false,
+        excludeFloatHit: false,
+        friction: 0.8,
+        kind,
+        localPosition,
+        matrixInitialized: false,
+        restitution: 0.03,
+        type: 'ELEVATOR_COLLIDER',
+    };
+    return mesh;
+}
+function buildElevatorColliderMeshes() {
+    const nodes = useScene.getState().nodes;
+    const meshes = [];
+    for (const elevatorId of sceneRegistry.byType.elevator) {
+        const typedElevatorId = elevatorId;
+        const node = nodes[typedElevatorId];
+        if (node?.type !== 'elevator' || node.visible === false)
+            continue;
+        const { entries, shaftBaseY, shaftTopY, totalHeight } = resolveElevatorLevels(node, nodes);
+        const cabWidth = getElevatorCabWidth(node);
+        const cabDepth = getElevatorCabDepth(node);
+        const shaftWidth = getElevatorShaftWidth(node, cabWidth);
+        const shaftDepth = getElevatorShaftDepth(node, cabDepth);
+        const cabHeight = Math.max(node.cabHeight, 1.4);
+        const doorWidth = Math.min(Math.max(node.doorWidth, 0.45), cabWidth - 0.18, shaftWidth - 0.18);
+        const doorHeight = Math.min(Math.max(node.doorHeight, 1.2), cabHeight - 0.1);
+        const doorStyle = getResolvedElevatorDoorStyle(node.doorStyle);
+        const shaftHeight = Math.max(totalHeight, cabHeight + 0.3);
+        const wallThickness = getElevatorShaftWallThickness(node);
+        const cabFloorWidth = Math.max(cabWidth - ELEVATOR_COLLIDER_HORIZONTAL_PADDING * 2, 0.48);
+        const cabFloorDepth = Math.max(cabDepth - ELEVATOR_COLLIDER_HORIZONTAL_PADDING * 2, 0.48);
+        const frontWallZ = -shaftDepth / 2 - wallThickness / 2;
+        const frontZ = frontWallZ - wallThickness / 2 - 0.018;
+        const cabCenterZ = -shaftDepth / 2 + cabDepth / 2;
+        const leafWidth = getElevatorDoorLeafWidth(doorWidth, doorStyle);
+        const doorLeafSides = getElevatorDoorLeafSides(doorStyle);
+        const resolvedShaftTopY = Math.max(shaftTopY, shaftBaseY + shaftHeight);
+        meshes.push(createElevatorColliderMesh(typedElevatorId, 'shaft-back', [shaftWidth + wallThickness * 2, shaftHeight, wallThickness], [0, shaftBaseY + shaftHeight / 2, shaftDepth / 2 + wallThickness / 2]), createElevatorColliderMesh(typedElevatorId, 'shaft-left', [wallThickness, shaftHeight, shaftDepth + wallThickness * 2], [-shaftWidth / 2 - wallThickness / 2, shaftBaseY + shaftHeight / 2, 0]), createElevatorColliderMesh(typedElevatorId, 'shaft-right', [wallThickness, shaftHeight, shaftDepth + wallThickness * 2], [shaftWidth / 2 + wallThickness / 2, shaftBaseY + shaftHeight / 2, 0]), createElevatorColliderMesh(typedElevatorId, 'shaft-top', [shaftWidth + wallThickness * 2, wallThickness, shaftDepth + wallThickness * 2], [0, shaftBaseY + shaftHeight - wallThickness / 2, 0]), createElevatorColliderMesh(typedElevatorId, 'cab-floor', [cabFloorWidth, ELEVATOR_COLLIDER_FLOOR_THICKNESS, cabFloorDepth], [0, ELEVATOR_COLLIDER_FLOOR_THICKNESS / 2, cabCenterZ]), createElevatorColliderMesh(typedElevatorId, 'cab-ceiling', [cabWidth, wallThickness, cabDepth], [0, cabHeight - wallThickness / 2, cabCenterZ]), createElevatorColliderMesh(typedElevatorId, 'cab-back', [cabWidth, cabHeight, wallThickness], [0, cabHeight / 2, cabCenterZ + cabDepth / 2 - wallThickness / 2]), createElevatorColliderMesh(typedElevatorId, 'cab-left', [wallThickness, cabHeight, cabDepth], [-cabWidth / 2 + wallThickness / 2, cabHeight / 2, cabCenterZ]), createElevatorColliderMesh(typedElevatorId, 'cab-right', [wallThickness, cabHeight, cabDepth], [cabWidth / 2 - wallThickness / 2, cabHeight / 2, cabCenterZ]), createElevatorColliderMesh(typedElevatorId, 'cab-door-gate', [doorWidth, doorHeight, ELEVATOR_COLLIDER_DOOR_DEPTH], [0, doorHeight / 2, frontZ], { doorWidth }), ...doorLeafSides.map((side) => createElevatorColliderMesh(typedElevatorId, side === 'left' ? 'cab-door-left' : 'cab-door-right', [leafWidth, doorHeight, ELEVATOR_COLLIDER_DOOR_DEPTH], [0, doorHeight / 2, frontZ], { doorWidth, side })));
+        const entrySpans = entries.map((entry, index) => {
+            const nextEntry = entries[index + 1];
+            return {
+                entry,
+                levelTopY: Math.max(nextEntry?.baseY ?? resolvedShaftTopY, entry.baseY + doorHeight + 0.24),
+            };
+        });
+        for (const { entry, levelTopY } of entrySpans) {
+            const wallDepth = wallThickness;
+            const levelHeight = Math.max(levelTopY - entry.baseY, doorHeight + 0.24);
+            const jambWidth = Math.max((shaftWidth - doorWidth) / 2, 0.08);
+            const jambCenterOffset = doorWidth / 2 + jambWidth / 2;
+            const headerHeight = Math.max(levelHeight - doorHeight, 0.14);
+            meshes.push(createElevatorColliderMesh(typedElevatorId, 'shaft-front-left', [jambWidth, levelHeight, wallDepth], [-jambCenterOffset, entry.baseY + levelHeight / 2, frontWallZ]), createElevatorColliderMesh(typedElevatorId, 'shaft-front-right', [jambWidth, levelHeight, wallDepth], [jambCenterOffset, entry.baseY + levelHeight / 2, frontWallZ]), createElevatorColliderMesh(typedElevatorId, 'shaft-front-header', [shaftWidth, headerHeight, wallDepth], [0, entry.baseY + doorHeight + headerHeight / 2, frontWallZ]), createElevatorColliderMesh(typedElevatorId, 'landing-door-gate', [doorWidth, doorHeight, ELEVATOR_COLLIDER_DOOR_DEPTH], [0, entry.baseY + doorHeight / 2, frontZ - 0.02], { doorWidth, levelId: entry.id }), ...doorLeafSides.map((side) => createElevatorColliderMesh(typedElevatorId, side === 'left' ? 'landing-door-left' : 'landing-door-right', [leafWidth, doorHeight, ELEVATOR_COLLIDER_DOOR_DEPTH], [0, entry.baseY + doorHeight / 2, frontZ - 0.02], { doorWidth, levelId: entry.id, side })));
+        }
+    }
+    return meshes;
+}
+function disposeElevatorColliderMeshes(meshes) {
+    for (const mesh of meshes) {
+        const geometry = mesh.geometry;
+        geometry.disposeBoundsTree?.();
+        geometry.dispose();
+    }
+}
+const resolvePlacedSpawnNode = (nodes) => {
+    const candidates = Object.values(nodes).filter((node) => node.type === 'spawn');
+    if (candidates.length === 0)
+        return null;
+    return [...candidates].sort((a, b) => a.id.localeCompare(b.id))[0] ?? null;
+};
+/** Live scene walking, collision and interaction. Mount inside Viewer; useViewer owns activation. */
+const noExternalFov = () => false;
+export function LiveWalkthroughController(props) {
+    const active = useViewer((state) => state.walkthroughMode);
+    return active ? _jsx(LiveWalkthroughSession, { ...props }) : null;
+}
+function LiveWalkthroughSession({ paused = false, externalFov = noExternalFov, pointerInteraction = true, suspendOnUnlock = false, onExit, }) {
+    const hostRef = useRef({ paused, externalFov, pointerInteraction, suspendOnUnlock, onExit });
+    hostRef.current = { paused, externalFov, pointerInteraction, suspendOnUnlock, onExit };
+    const exit = useCallback(() => {
+        if (!useViewer.getState().walkthroughMode)
+            return;
+        useViewer.getState().setWalkthroughMode(false);
+        hostRef.current.onExit?.();
+    }, []);
+    const { camera, gl } = useThree();
+    const placedSpawnNode = useScene((state) => resolvePlacedSpawnNode(state.nodes));
+    const isDroneMode = useViewer((state) => state.walkthroughMovement === 'drone');
+    const controllerRef = useRef(null);
+    const movementInputRef = useRef({ ...inactiveMovementInput });
+    const hadPointerLockRef = useRef(false);
+    const lookRef = useRef({ yaw: 0, pitch: 0 });
+    const interactableTargetRef = useRef(null);
+    const hudLabelFrameRef = useRef(HUD_LABEL_SAMPLE_FRAMES - 1);
+    const crouchKeyRef = useRef(false);
+    const droneAscendKeyRef = useRef(false);
+    const droneSlowKeyRef = useRef(false);
+    const droneDescendKeyRef = useRef(false);
+    const droneVelocityRef = useRef(new Vector3());
+    const suspendRef = useRef(false);
+    const eyeOffsetRef = useRef(CAMERA_EYE_OFFSET);
+    const [crouched, setCrouched] = useState(false);
+    const [isElevatorRideLocked, setIsElevatorRideLocked] = useState(false);
+    const ridingElevatorRef = useRef(null);
+    const rideLockedRef = useRef(false);
+    const worldRef = useRef(null);
+    const elevatorColliderMeshesRef = useRef([]);
+    const [world, setWorld] = useState(null);
+    const [elevatorColliderMeshes, setElevatorColliderMeshes] = useState([]);
+    const [controllerStart, setControllerStart] = useState(null);
+    useEffect(() => {
+        if (!camera.isPerspectiveCamera)
+            return;
+        return applyWalkthroughCameraClipping(camera);
+    }, [camera]);
+    useEffect(() => {
+        const previousCameraMode = useViewer.getState().cameraMode;
+        if (previousCameraMode === 'orthographic') {
+            useViewer.getState().setCameraMode('perspective');
+        }
+        return () => {
+            if (previousCameraMode === 'orthographic') {
+                useViewer.getState().setCameraMode('orthographic');
+            }
+        };
+    }, []);
+    // Read the host's current FOV ownership at entry and teardown: changing it
+    // mid-session must not restore the orbit FOV underneath a host's framing rig.
+    useEffect(() => {
+        const perspectiveCamera = camera;
+        if (!perspectiveCamera.isPerspectiveCamera)
+            return;
+        if (hostRef.current.externalFov())
+            return;
+        const previousFov = perspectiveCamera.fov;
+        perspectiveCamera.fov = WALKTHROUGH_FOV;
+        perspectiveCamera.updateProjectionMatrix();
+        return () => {
+            if (hostRef.current.externalFov())
+                return;
+            perspectiveCamera.fov = previousFov;
+            perspectiveCamera.updateProjectionMatrix();
+        };
+    }, [camera]);
+    useEffect(() => {
+        useFirstPersonHud.getState().reset();
+        return () => useFirstPersonHud.getState().reset();
+    }, []);
+    const replaceColliderWorld = useCallback((nextWorld) => {
+        worldRef.current?.dispose();
+        worldRef.current = nextWorld;
+        setWorld(nextWorld);
+    }, []);
+    const replaceElevatorColliderMeshes = useCallback((nextMeshes) => {
+        disposeElevatorColliderMeshes(elevatorColliderMeshesRef.current);
+        elevatorColliderMeshesRef.current = nextMeshes;
+        setElevatorColliderMeshes(nextMeshes);
+    }, []);
+    const rebuildColliderWorld = useCallback(() => {
+        replaceColliderWorld(buildFirstPersonColliderWorldFromRegistry());
+        replaceElevatorColliderMeshes(buildElevatorColliderMeshes());
+    }, [replaceColliderWorld, replaceElevatorColliderMeshes]);
+    const setElevatorRideLocked = useCallback((locked) => {
+        if (rideLockedRef.current === locked)
+            return;
+        rideLockedRef.current = locked;
+        setIsElevatorRideLocked(locked);
+    }, []);
+    const setControllerApi = useCallback((api) => {
+        controllerRef.current = api;
+        if (api) {
+            api.setMovement(movementInputRef.current);
+        }
+    }, []);
+    const resolveInteractableDoorId = useCallback(() => {
+        const nodes = useScene.getState().nodes;
+        camera.updateMatrixWorld(true);
+        doorInteractionRaycaster.setFromCamera(centerScreenPoint, camera);
+        let closestDoorId = null;
+        let closestDistance = DOOR_INTERACTION_DISTANCE;
+        for (const doorId of sceneRegistry.byType.door) {
+            const node = nodes[doorId];
+            if (node?.type !== 'door')
+                continue;
+            if (node.openingKind === 'opening')
+                continue;
+            if (!hasNativeLeaf(node))
+                continue;
+            if (node.segments.every((segment) => segment.type === 'empty'))
+                continue;
+            const object = sceneRegistry.nodes.get(doorId);
+            if (!object)
+                continue;
+            object.updateWorldMatrix(true, true);
+            const placementHit = doorInteractionRaycaster
+                .intersectObject(object, true)
+                .find((intersection) => intersection.distance <= DOOR_INTERACTION_DISTANCE);
+            if (placementHit && placementHit.distance < closestDistance) {
+                closestDoorId = doorId;
+                closestDistance = placementHit.distance;
+            }
+            const leafW = node.width - 2 * node.frameThickness;
+            const leafH = node.height - node.frameThickness;
+            if (leafW <= 0 || leafH <= 0)
+                continue;
+            const leafCenterY = -node.frameThickness / 2;
+            if (isOperationDoorType(node.doorType)) {
+                doorOpeningMatrix
+                    .copy(object.matrixWorld)
+                    .multiply(new Matrix4().makeTranslation(0, leafCenterY, 0));
+                doorOpeningInverseMatrix.copy(doorOpeningMatrix).invert();
+                doorOpeningBox.min.set(-leafW / 2, -leafH / 2, -DOOR_LEAF_INTERACTION_DEPTH / 2);
+                doorOpeningBox.max.set(leafW / 2, leafH / 2, DOOR_LEAF_INTERACTION_DEPTH / 2);
+                doorOpeningLocalRay
+                    .copy(doorInteractionRaycaster.ray)
+                    .applyMatrix4(doorOpeningInverseMatrix);
+                const localOpeningHit = doorOpeningLocalRay.intersectBox(doorOpeningBox, doorOpeningLocalHit);
+                if (!localOpeningHit)
+                    continue;
+                doorOpeningWorldHit.copy(localOpeningHit).applyMatrix4(doorOpeningMatrix);
+                const openingHitDistance = doorOpeningWorldHit.distanceTo(doorInteractionRaycaster.ray.origin);
+                if (openingHitDistance <= DOOR_INTERACTION_DISTANCE &&
+                    openingHitDistance < closestDistance) {
+                    closestDoorId = doorId;
+                    closestDistance = openingHitDistance;
+                }
+                continue;
+            }
+            const hingeX = node.hingesSide === 'right' ? leafW / 2 : -leafW / 2;
+            const swingDirectionSign = node.swingDirection === 'inward' ? 1 : -1;
+            const hingeDirectionSign = node.hingesSide === 'right' ? 1 : -1;
+            const currentSwingAngle = useInteractive.getState().doors[doorId]?.swingAngle ?? node.swingAngle ?? 0;
+            const clampedSwingAngle = Math.max(0, Math.min(DOOR_SWING_OPEN_ANGLE, currentSwingAngle));
+            const leafSwingRotation = clampedSwingAngle * swingDirectionSign * hingeDirectionSign;
+            doorLeafMatrix
+                .copy(object.matrixWorld)
+                .multiply(new Matrix4().makeTranslation(hingeX, 0, 0))
+                .multiply(new Matrix4().makeRotationY(leafSwingRotation))
+                .multiply(new Matrix4().makeTranslation(-hingeX, leafCenterY, 0));
+            doorLeafInverseMatrix.copy(doorLeafMatrix).invert();
+            doorLeafBox.min.set(-leafW / 2, -leafH / 2, -DOOR_LEAF_INTERACTION_DEPTH / 2);
+            doorLeafBox.max.set(leafW / 2, leafH / 2, DOOR_LEAF_INTERACTION_DEPTH / 2);
+            doorLeafLocalRay.copy(doorInteractionRaycaster.ray).applyMatrix4(doorLeafInverseMatrix);
+            const localHit = doorLeafLocalRay.intersectBox(doorLeafBox, doorLeafLocalHit);
+            if (!localHit)
+                continue;
+            doorLeafWorldHit.copy(localHit).applyMatrix4(doorLeafMatrix);
+            const hitDistance = doorLeafWorldHit.distanceTo(doorInteractionRaycaster.ray.origin);
+            if (hitDistance <= DOOR_INTERACTION_DISTANCE && hitDistance < closestDistance) {
+                closestDoorId = doorId;
+                closestDistance = hitDistance;
+            }
+        }
+        return closestDoorId;
+    }, [camera]);
+    const resolveInteractableWindowId = useCallback(() => {
+        const nodes = useScene.getState().nodes;
+        camera.updateMatrixWorld(true);
+        windowInteractionRaycaster.setFromCamera(centerScreenPoint, camera);
+        let closestWindowId = null;
+        let closestDistance = DOOR_INTERACTION_DISTANCE;
+        for (const windowId of sceneRegistry.byType.window) {
+            const node = nodes[windowId];
+            if (node?.type !== 'window')
+                continue;
+            if (node.openingKind === 'opening')
+                continue;
+            if (!hasNativeLeaf(node))
+                continue;
+            if (!isOperableWindowType(node.windowType))
+                continue;
+            const object = sceneRegistry.nodes.get(windowId);
+            if (!object)
+                continue;
+            const hit = windowInteractionRaycaster
+                .intersectObject(object, true)
+                .find((intersection) => intersection.distance <= DOOR_INTERACTION_DISTANCE);
+            if (!(hit && hit.distance < closestDistance))
+                continue;
+            closestWindowId = windowId;
+            closestDistance = hit.distance;
+        }
+        return closestWindowId;
+    }, [camera]);
+    const resolveInteractableElevatorTarget = useCallback(() => {
+        const nodes = useScene.getState().nodes;
+        camera.updateMatrixWorld(true);
+        elevatorInteractionRaycaster.setFromCamera(centerScreenPoint, camera);
+        let closestTarget = null;
+        let closestDistance = DOOR_INTERACTION_DISTANCE;
+        for (const elevatorId of sceneRegistry.byType.elevator) {
+            const typedElevatorId = elevatorId;
+            const node = nodes[typedElevatorId];
+            if (node?.type !== 'elevator')
+                continue;
+            const object = sceneRegistry.nodes.get(typedElevatorId);
+            if (!object)
+                continue;
+            const runtime = useInteractive.getState().elevators[typedElevatorId];
+            object.updateWorldMatrix(true, true);
+            if (runtime) {
+                elevatorLocalEyePosition.copy(camera.position);
+                object.worldToLocal(elevatorLocalEyePosition);
+            }
+            const canUseCabButtons = runtime && isInsideElevatorCab(node, runtime, elevatorLocalEyePosition);
+            const intersections = elevatorInteractionRaycaster.intersectObject(object, true);
+            for (const intersection of intersections) {
+                if (intersection.distance > closestDistance)
+                    continue;
+                const target = resolveElevatorButtonTarget(intersection.object);
+                if (!target || target.elevatorId !== elevatorId)
+                    continue;
+                if (target.action === 'request-level') {
+                    if (!target.levelId || nodes[target.levelId]?.type !== 'level')
+                        continue;
+                }
+                if (target.buttonKind === 'cab' && !canUseCabButtons)
+                    continue;
+                closestTarget = {
+                    action: target.action,
+                    buttonKind: target.buttonKind,
+                    id: target.elevatorId,
+                    levelId: target.levelId,
+                    type: 'elevator',
+                };
+                closestDistance = intersection.distance;
+            }
+        }
+        return closestTarget;
+    }, [camera]);
+    const resolveInteractableTarget = useCallback(() => {
+        const elevatorTarget = resolveInteractableElevatorTarget();
+        if (elevatorTarget)
+            return elevatorTarget;
+        const doorId = resolveInteractableDoorId();
+        if (doorId)
+            return { id: doorId, type: 'door' };
+        const windowId = resolveInteractableWindowId();
+        if (windowId)
+            return { id: windowId, type: 'window' };
+        camera.updateMatrixWorld(true);
+        proceduralInteractionRaycaster.setFromCamera(centerScreenPoint, camera);
+        proceduralInteractionRaycaster.far = DOOR_INTERACTION_DISTANCE;
+        let closest = null;
+        let closestDistance = DOOR_INTERACTION_DISTANCE;
+        const nodes = useScene.getState().nodes;
+        const covered = new Set();
+        for (const rawId of sceneRegistry.byType['procedural-item'] ?? []) {
+            covered.add(rawId);
+            const id = rawId;
+            const node = nodes[id];
+            if (node?.type !== 'procedural-item')
+                continue;
+            const procedural = node;
+            if (!operableParts(procedural.recipe).length &&
+                !procedural.recipe.parts.some((part) => part.light))
+                continue;
+            const object = sceneRegistry.nodes.get(id);
+            if (!object)
+                continue;
+            for (const hit of proceduralInteractionRaycaster.intersectObject(object, true)) {
+                if (hit.distance >= closestDistance)
+                    break;
+                // Skip what is not drawn: a joint tree's inactive rest or joint meshes.
+                let drawn = true;
+                for (let at = hit.object; at && at !== object; at = at.parent)
+                    if (!at.visible)
+                        drawn = false;
+                if (!drawn)
+                    continue;
+                let ancestor = hit.object;
+                while (ancestor && ancestor !== object && !ancestor.userData.proceduralMotion)
+                    ancestor = ancestor.parent;
+                let motion = ancestor?.userData.proceduralMotion;
+                // An idle joint tree draws one merged mesh per slot; its face ranges name the part.
+                const ranges = hit.object.userData.proceduralRanges;
+                if (!motion && ranges && hit.faceIndex != null) {
+                    const face = hit.faceIndex;
+                    const partId = ranges.find((range) => face < range.end)?.partId;
+                    const part = partId ? operablePartFor(procedural.recipe, partId) : undefined;
+                    if (part)
+                        motion = { nodeId: id, partId: part.id, kind: part.kind };
+                }
+                closest =
+                    motion?.nodeId === id && motion.partId
+                        ? { id, partId: motion.partId, kind: motion.kind, type: 'procedural' }
+                        : { id, type: 'procedural' };
+                closestDistance = hit.distance;
+                break;
+            }
+        }
+        for (const rawId of sceneRegistry.byType.item ?? []) {
+            covered.add(rawId);
+            const id = rawId;
+            const node = nodes[id];
+            if (node?.type !== 'item' ||
+                !node.asset.interactive?.controls.some((control) => control.kind === 'toggle'))
+                continue;
+            const object = sceneRegistry.nodes.get(id);
+            if (!object)
+                continue;
+            const hit = proceduralInteractionRaycaster.intersectObject(object, true)[0];
+            if (hit && hit.distance < closestDistance) {
+                closest = { id, type: 'item' };
+                closestDistance = hit.distance;
+            }
+        }
+        // Doors and windows have their own walkthrough targets (resolveInteractable*Id), except those
+        // built from a script: their clips run through the mechanism target below.
+        for (const id of nativeOpeningIds())
+            covered.add(id);
+        for (const id of mechanismTargetIds(covered)) {
+            const object = sceneRegistry.nodes.get(id);
+            const hit = object && proceduralInteractionRaycaster.intersectObject(object, true)[0];
+            if (hit && hit.distance < closestDistance) {
+                closest = { id, type: 'mechanism' };
+                closestDistance = hit.distance;
+            }
+        }
+        if (!closest) {
+            const selectedId = useViewer.getState().selection.selectedIds.at(-1);
+            const selected = selectedId ? nodes[selectedId] : undefined;
+            if (selected?.type === 'item' &&
+                selected.asset.interactive?.controls.some((control) => control.kind === 'toggle'))
+                return { id: selected.id, type: 'item' };
+        }
+        if (closest)
+            return closest;
+        return null;
+    }, [
+        camera,
+        resolveInteractableDoorId,
+        resolveInteractableElevatorTarget,
+        resolveInteractableWindowId,
+    ]);
+    const toggleInteractableTarget = useCallback(() => {
+        if (isDroneMode)
+            return;
+        const target = interactableTargetRef.current ?? resolveInteractableTarget();
+        if (!target)
+            return;
+        playTargetSound(target);
+        if (target.type === 'mechanism') {
+            const node = useScene.getState().nodes[target.id];
+            if (node)
+                toggleNodeMechanism(node);
+            return;
+        }
+        if (target.type === 'item') {
+            const node = useScene.getState().nodes[target.id];
+            if (node?.type === 'item' && node.asset.interactive)
+                operateItem(target.id, node.asset.interactive);
+            return;
+        }
+        if (target.type === 'procedural') {
+            const node = useScene.getState().nodes[target.id];
+            if (node?.type !== 'procedural-item')
+                return;
+            const parts = operableParts(node.recipe).map((part) => part.id);
+            const state = useInteractive.getState();
+            if (parts.length === 0) {
+                state.toggleProceduralLights(target.id);
+                return;
+            }
+            if (target.partId)
+                state.toggleProceduralPart(target.id, target.partId);
+            else
+                state.setProceduralParts(target.id, parts, !parts.some((id) => state.procedural[target.id]?.parts[id]));
+            return;
+        }
+        if (target.type === 'elevator') {
+            if (target.buttonKind === 'cab') {
+                const state = useInteractive.getState().elevators[target.id];
+                if (state) {
+                    ridingElevatorRef.current = {
+                        elevatorId: target.id,
+                        localControllerY: null,
+                        previousCarY: state.carY,
+                    };
+                }
+            }
+            if (target.action === 'open-door') {
+                openElevatorDoor(target.id);
+                return;
+            }
+            if (target.levelId) {
+                const targetElevatorId = target.buttonKind === 'landing'
+                    ? resolveElevatorDispatchTarget({
+                        elevators: useInteractive.getState().elevators,
+                        levelId: target.levelId,
+                        nodes: useScene.getState().nodes,
+                        requestedElevatorId: target.id,
+                    })
+                    : target.id;
+                requestElevatorLevel(targetElevatorId, target.levelId);
+            }
+            return;
+        }
+        if (target.type === 'window') {
+            const node = useScene.getState().nodes[target.id];
+            if (node?.type !== 'window' ||
+                node.openingKind === 'opening' ||
+                !isOperableWindowType(node.windowType)) {
+                return;
+            }
+            toggleWindowOpenState(target.id, { persist: false });
+            return;
+        }
+        const doorId = target.id;
+        const node = useScene.getState().nodes[doorId];
+        if (node?.type !== 'door' || node.openingKind === 'opening')
+            return;
+        toggleDoorOpenState(doorId, { persist: false });
+    }, [isDroneMode, resolveInteractableTarget]);
+    const closeInteractableTarget = useCallback(() => {
+        if (isDroneMode)
+            return;
+        const target = interactableTargetRef.current ?? resolveInteractableTarget();
+        if (!target)
+            return;
+        if (target.type === 'mechanism') {
+            const node = useScene.getState().nodes[target.id];
+            if (node)
+                nodeMechanism(node)?.set(node, false);
+            return;
+        }
+        if (target.type === 'procedural') {
+            const node = useScene.getState().nodes[target.id];
+            if (node?.type !== 'procedural-item')
+                return;
+            const parts = target.partId
+                ? [target.partId]
+                : operableParts(node.recipe).map((part) => part.id);
+            useInteractive.getState().setProceduralParts(target.id, parts, false);
+            return;
+        }
+        if (target.type === 'elevator')
+            return;
+        if (target.type === 'window') {
+            const node = useScene.getState().nodes[target.id];
+            if (node?.type !== 'window' ||
+                node.openingKind === 'opening' ||
+                !isOperableWindowType(node.windowType)) {
+                return;
+            }
+            closeWindowOpenState(target.id, { persist: false });
+            return;
+        }
+        const node = useScene.getState().nodes[target.id];
+        if (node?.type !== 'door' || node.openingKind === 'opening')
+            return;
+        closeDoorOpenState(target.id, { persist: false });
+    }, [isDroneMode, resolveInteractableTarget]);
+    const placedSpawn = useMemo(() => {
+        if (!(placedSpawnNode && placedSpawnNode.type === 'spawn'))
+            return null;
+        const spawnObject = sceneRegistry.nodes.get(placedSpawnNode.id);
+        if (spawnObject) {
+            spawnObject.updateWorldMatrix(true, false);
+            spawnObject.getWorldPosition(spawnWorldPosition);
+            spawnWorldEuler.setFromRotationMatrix(spawnObject.matrixWorld, 'YXZ');
+            return {
+                position: [
+                    spawnWorldPosition.x,
+                    spawnWorldPosition.y + FIRST_PERSON_SPAWN_EYE_HEIGHT,
+                    spawnWorldPosition.z,
+                ],
+                yaw: spawnWorldEuler.y,
+            };
+        }
+        return {
+            position: [
+                placedSpawnNode.position[0],
+                placedSpawnNode.position[1] + FIRST_PERSON_SPAWN_EYE_HEIGHT,
+                placedSpawnNode.position[2],
+            ],
+            yaw: placedSpawnNode.rotation,
+        };
+    }, [placedSpawnNode]);
+    useEffect(() => {
+        // Drone has no gravity, no floor and no collision, so the BVH collider world
+        // (a full-scene traversal, rebuilt on every door/window animation) is pure
+        // cost there. Switching modes disposes it and rebuilds on the way back.
+        if (!isDroneMode)
+            rebuildColliderWorld();
+        return () => {
+            worldRef.current?.dispose();
+            worldRef.current = null;
+            disposeElevatorColliderMeshes(elevatorColliderMeshesRef.current);
+            elevatorColliderMeshesRef.current = [];
+            setElevatorColliderMeshes([]);
+            setWorld(null);
+        };
+    }, [isDroneMode, rebuildColliderWorld]);
+    useEffect(() => {
+        if (isDroneMode)
+            return;
+        emitter.on('door:animation-completed', rebuildColliderWorld);
+        emitter.on('window:animation-completed', rebuildColliderWorld);
+        // A door built from a script opens by its model's clip, which reports no animation end.
+        const stopWatching = watchScriptedDoors(rebuildColliderWorld);
+        return () => {
+            emitter.off('door:animation-completed', rebuildColliderWorld);
+            emitter.off('window:animation-completed', rebuildColliderWorld);
+            stopWatching();
+        };
+    }, [isDroneMode, rebuildColliderWorld]);
+    // A walk session started before a drone detour would otherwise resume at its
+    // original spawn; drop it so the next walk re-derives one.
+    useEffect(() => {
+        if (isDroneMode)
+            setControllerStart(null);
+    }, [isDroneMode]);
+    // Drone picks up wherever the camera currently is — orbit pose or walk eye.
+    useEffect(() => {
+        if (!isDroneMode)
+            return;
+        seedDroneLook(lookRef.current, camera.quaternion);
+        droneVelocityRef.current.set(0, 0, 0);
+        // Interaction prompts belong to walk; drop whatever its frame left behind.
+        if (useViewer.getState().hoveredId === interactableTargetRef.current?.id) {
+            useViewer.getState().setHoveredId(null);
+        }
+        interactableTargetRef.current = null;
+        useFirstPersonHud.getState().reset();
+    }, [camera, isDroneMode]);
+    useEffect(() => {
+        if (!world)
+            return;
+        if (controllerStart)
+            return;
+        const spawn = placedSpawn ?? deriveFirstPersonSpawn(camera, world);
+        const [x, y, z] = spawn.position;
+        lookRef.current.yaw = spawn.yaw;
+        lookRef.current.pitch = 0;
+        setControllerStart({
+            position: [x, y - CONTROLLER_CENTER_FROM_EYE, z],
+            yaw: spawn.yaw,
+        });
+    }, [camera, controllerStart, placedSpawn, world]);
+    useEffect(() => {
+        const canvas = gl.domElement;
+        focusFirstPersonCanvas(canvas);
+        const frame = window.requestAnimationFrame(() => focusFirstPersonCanvas(canvas));
+        return () => window.cancelAnimationFrame(frame);
+    }, [gl]);
+    // The pointer-lock effect below must be mount-stable. Its cleanup exits
+    // pointer lock, and `toggleInteractableTarget` is recreated whenever the
+    // camera object changes — which happens right after entry when the
+    // persisted orthographic mode swaps to perspective. If the async lock
+    // grant lands before that re-run, the cleanup's exitPointerLock fires an
+    // unlock the handler reads as "user left walkthrough", instantly
+    // cancelling a fresh entry (and arming the browser's ~1.25s re-lock
+    // cooldown, so the next presses fail too). Route the callback through a
+    // ref so the effect deps stay `[gl]`.
+    const toggleInteractableTargetRef = useRef(toggleInteractableTarget);
+    useEffect(() => {
+        toggleInteractableTargetRef.current = toggleInteractableTarget;
+    }, [toggleInteractableTarget]);
+    useEffect(() => {
+        const canvas = gl.domElement;
+        const handleMouseMove = (e) => {
+            if (document.pointerLockElement !== canvas)
+                return;
+            // A still render must retain the exact framed pose.
+            if (hostRef.current.paused)
+                return;
+            turnFirstPersonLook(lookRef.current, e.movementX, e.movementY, useViewer.getState().walkthroughMovement === 'drone' && droneSlowKeyRef.current
+                ? DRONE_SLOW_MULTIPLIER
+                : 1);
+        };
+        const handleClick = (event) => {
+            const target = event.target;
+            if (!(target instanceof HTMLElement))
+                return;
+            if (!canvas.contains(target))
+                return;
+            if (document.pointerLockElement !== canvas) {
+                canvas.requestPointerLock?.();
+            }
+        };
+        const handleMouseDown = (event) => {
+            if (document.pointerLockElement !== canvas)
+                return;
+            if (event.button !== 0)
+                return;
+            if (!hostRef.current.pointerInteraction)
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            toggleInteractableTargetRef.current();
+        };
+        const handlePointerLockChange = () => {
+            const isLocked = document.pointerLockElement === canvas;
+            if (isLocked) {
+                hadPointerLockRef.current = true;
+                suspendRef.current = false;
+                useViewer.getState().setWalkthroughSuspended(false);
+                return;
+            }
+            // Deliberately released (screenshot pause) — stay in first person;
+            // clicking the canvas re-locks.
+            if (suspendRef.current)
+                return;
+            if (hadPointerLockRef.current &&
+                hostRef.current.suspendOnUnlock &&
+                useViewer.getState().walkthroughMode) {
+                suspendRef.current = true;
+                useViewer.getState().setWalkthroughSuspended(true);
+                return;
+            }
+            if (hadPointerLockRef.current && useViewer.getState().walkthroughMode) {
+                exit();
+            }
+        };
+        handlePointerLockChange();
+        document.addEventListener('mousemove', handleMouseMove);
+        document.addEventListener('click', handleClick);
+        document.addEventListener('mousedown', handleMouseDown, true);
+        document.addEventListener('pointerlockchange', handlePointerLockChange);
+        return () => {
+            document.removeEventListener('mousemove', handleMouseMove);
+            document.removeEventListener('click', handleClick);
+            document.removeEventListener('mousedown', handleMouseDown, true);
+            document.removeEventListener('pointerlockchange', handlePointerLockChange);
+            useViewer.getState().setWalkthroughSuspended(false);
+            if (document.pointerLockElement === canvas) {
+                document.exitPointerLock();
+            }
+        };
+    }, [exit, gl]);
+    useEffect(() => {
+        const canvas = gl.domElement;
+        const applyMovementKey = (event, active) => {
+            if (isTypingTarget(event.target))
+                return false;
+            const movement = getMovementInputForKey(event.code, active);
+            if (!movement)
+                return false;
+            event.preventDefault();
+            Object.assign(movementInputRef.current, movement);
+            controllerRef.current?.setMovement(movement);
+            return true;
+        };
+        const handleKeyDown = (event) => {
+            const handledMovement = applyMovementKey(event, true);
+            if (handledMovement)
+                return;
+            if (isTypingTarget(event.target))
+                return;
+            if (event.code === 'ControlLeft' || event.code === 'ControlRight') {
+                // While paused (P), crouch is frozen as-is — ⌃⇧⌘4 (clipboard
+                // screenshot) must not toggle it under the user.
+                if (!suspendRef.current)
+                    crouchKeyRef.current = true;
+            }
+            else if (event.code === 'KeyQ') {
+                // Drone descend. Space (already bound to jump) and E are the matching ascend.
+                event.preventDefault();
+                event.stopPropagation();
+                if (!suspendRef.current)
+                    droneDescendKeyRef.current = true;
+            }
+            else if (event.code === 'KeyE' && isDroneMode) {
+                event.preventDefault();
+                event.stopPropagation();
+                if (!suspendRef.current)
+                    droneAscendKeyRef.current = true;
+            }
+            else if ((event.code === 'AltLeft' || event.code === 'AltRight') && isDroneMode) {
+                event.preventDefault();
+                event.stopPropagation();
+                if (!suspendRef.current)
+                    droneSlowKeyRef.current = true;
+            }
+            else if (event.code === 'Escape') {
+                event.preventDefault();
+                event.stopPropagation();
+                if (hostRef.current.suspendOnUnlock) {
+                    if (document.pointerLockElement === canvas) {
+                        suspendRef.current = true;
+                        useViewer.getState().setWalkthroughSuspended(true);
+                        document.exitPointerLock();
+                    }
+                    else {
+                        exit();
+                    }
+                    return;
+                }
+                if (document.pointerLockElement === canvas) {
+                    document.exitPointerLock();
+                }
+                exit();
+            }
+            else if (event.code === 'KeyE' || event.code === 'KeyR') {
+                event.preventDefault();
+                event.stopPropagation();
+                toggleInteractableTarget();
+            }
+            else if (event.code === 'KeyT') {
+                event.preventDefault();
+                event.stopPropagation();
+                closeInteractableTarget();
+            }
+            else if (event.code === 'KeyP') {
+                // P toggles a cursor pause (advertised in the HUD): frees the pointer
+                // without leaving first person — e.g. for an OS screenshot, which
+                // needs a movable cursor — and click or P resumes.
+                event.preventDefault();
+                event.stopPropagation();
+                if (document.pointerLockElement === canvas) {
+                    suspendRef.current = true;
+                    useViewer.getState().setWalkthroughSuspended(true);
+                    document.exitPointerLock();
+                }
+                else if (suspendRef.current) {
+                    const result = canvas.requestPointerLock?.();
+                    if (result && typeof result.catch === 'function')
+                        result.catch(() => { });
+                }
+            }
+        };
+        const handleKeyUp = (event) => {
+            if ((event.code === 'ControlLeft' || event.code === 'ControlRight') && !suspendRef.current) {
+                crouchKeyRef.current = false;
+            }
+            if (event.code === 'KeyQ' && !suspendRef.current) {
+                droneDescendKeyRef.current = false;
+            }
+            if (event.code === 'KeyE' && !suspendRef.current) {
+                droneAscendKeyRef.current = false;
+            }
+            if ((event.code === 'AltLeft' || event.code === 'AltRight') && !suspendRef.current) {
+                droneSlowKeyRef.current = false;
+            }
+            applyMovementKey(event, false);
+        };
+        const handleBlur = () => {
+            if (!suspendRef.current) {
+                crouchKeyRef.current = false;
+                droneAscendKeyRef.current = false;
+                droneDescendKeyRef.current = false;
+                droneSlowKeyRef.current = false;
+            }
+        };
+        document.addEventListener('keydown', handleKeyDown, true);
+        document.addEventListener('keyup', handleKeyUp, true);
+        window.addEventListener('blur', handleBlur);
+        return () => {
+            document.removeEventListener('keydown', handleKeyDown, true);
+            document.removeEventListener('keyup', handleKeyUp, true);
+            window.removeEventListener('blur', handleBlur);
+        };
+    }, [closeInteractableTarget, exit, gl, isDroneMode, toggleInteractableTarget]);
+    const syncElevatorColliderMeshes = useCallback(() => {
+        const nodes = useScene.getState().nodes;
+        const interactive = useInteractive.getState();
+        for (const mesh of elevatorColliderMeshesRef.current) {
+            const { doorWidth, dynamic, elevatorId, kind, levelId, localPosition, side } = mesh.userData;
+            const node = nodes[elevatorId];
+            const runtime = interactive.elevators[elevatorId];
+            const object = sceneRegistry.nodes.get(elevatorId);
+            if (!(node?.type === 'elevator' && object && node.visible !== false)) {
+                mesh.visible = false;
+                continue;
+            }
+            if (!dynamic && mesh.userData.matrixInitialized && mesh.visible) {
+                continue;
+            }
+            let [localX, localY, localZ] = localPosition;
+            const isCabCollider = kind.startsWith('cab-');
+            const isDoorCollider = kind === 'landing-door-left' || kind === 'landing-door-right';
+            const isCabDoorGate = kind === 'cab-door-gate';
+            const isLandingDoorGate = kind === 'landing-door-gate';
+            if (isCabCollider) {
+                localY += runtime?.carY ?? 0;
+            }
+            if (kind === 'cab-door-left' || kind === 'cab-door-right') {
+                if (!runtime) {
+                    mesh.visible = false;
+                    continue;
+                }
+                localX = getElevatorDoorLeafX(side ?? 'left', doorWidth ?? node.doorWidth, runtime.doorOpen, node.doorStyle);
+                mesh.visible = true;
+            }
+            else if (isCabDoorGate) {
+                if (!runtime) {
+                    mesh.visible = false;
+                    continue;
+                }
+                mesh.visible = runtime.doorOpen < ELEVATOR_ENTRY_DOOR_OPEN_THRESHOLD;
+            }
+            else if (isDoorCollider) {
+                const doorOpen = runtime?.currentLevelId === levelId ? (runtime?.doorOpen ?? 0) : 0;
+                localX = getElevatorDoorLeafX(side ?? 'left', doorWidth ?? node.doorWidth, doorOpen, node.doorStyle);
+                mesh.visible = true;
+            }
+            else if (isLandingDoorGate) {
+                const doorOpen = runtime?.currentLevelId === levelId ? (runtime?.doorOpen ?? 0) : 0;
+                mesh.visible = doorOpen < ELEVATOR_ENTRY_DOOR_OPEN_THRESHOLD;
+            }
+            else {
+                mesh.visible = true;
+            }
+            object.updateWorldMatrix(true, false);
+            elevatorColliderMatrix.copy(object.matrixWorld);
+            elevatorColliderMatrix.multiply(elevatorColliderLocalMatrix.makeTranslation(localX, localY, localZ));
+            mesh.matrix.copy(elevatorColliderMatrix);
+            mesh.matrixWorld.copy(elevatorColliderMatrix);
+            mesh.userData.matrixInitialized = true;
+        }
+    }, []);
+    useFrame(() => {
+        if (isDroneMode)
+            return;
+        syncElevatorColliderMeshes();
+    }, -1);
+    const syncElevatorRide = useCallback((group) => {
+        const nodes = useScene.getState().nodes;
+        const interactive = useInteractive.getState();
+        const activeRide = ridingElevatorRef.current;
+        let nextRide = null;
+        const elevatorIds = activeRide
+            ? [
+                activeRide.elevatorId,
+                ...Array.from(sceneRegistry.byType.elevator).filter((elevatorId) => elevatorId !== activeRide.elevatorId),
+            ]
+            : Array.from(sceneRegistry.byType.elevator);
+        for (const elevatorId of elevatorIds) {
+            const typedElevatorId = elevatorId;
+            const node = nodes[typedElevatorId];
+            if (node?.type !== 'elevator')
+                continue;
+            const runtime = interactive.elevators[typedElevatorId];
+            const object = sceneRegistry.nodes.get(typedElevatorId);
+            if (!(runtime && object))
+                continue;
+            object.updateWorldMatrix(true, true);
+            elevatorLocalEyePosition.copy(camera.position);
+            object.worldToLocal(elevatorLocalEyePosition);
+            const halfWidth = getElevatorCabWidth(node) / 2 - ELEVATOR_RIDE_HORIZONTAL_PADDING;
+            const halfDepth = getElevatorCabDepth(node) / 2 - ELEVATOR_RIDE_HORIZONTAL_PADDING;
+            const cabCenterZ = getElevatorCabCenterZ(node);
+            const cabHeight = Math.max(node.cabHeight, 1.4);
+            const insideFootprint = Math.abs(elevatorLocalEyePosition.x) <= Math.max(halfWidth, 0.24) &&
+                Math.abs(elevatorLocalEyePosition.z - cabCenterZ) <= Math.max(halfDepth, 0.24);
+            const insideCabHeight = elevatorLocalEyePosition.y >= runtime.carY + 0.35 &&
+                elevatorLocalEyePosition.y <= runtime.carY + cabHeight + 0.7;
+            const continuingRide = activeRide?.elevatorId === typedElevatorId &&
+                insideFootprint &&
+                elevatorLocalEyePosition.y >= runtime.carY - 0.2 &&
+                elevatorLocalEyePosition.y <= runtime.carY + cabHeight + 1.25;
+            if ((insideFootprint && insideCabHeight) || continuingRide) {
+                nextRide = {
+                    cabHeight,
+                    cabCenterZ,
+                    carY: runtime.carY,
+                    doorOpen: runtime.doorOpen,
+                    elevatorId: typedElevatorId,
+                    halfDepth: Math.max(halfDepth, 0.24),
+                    halfWidth: Math.max(halfWidth, 0.24),
+                    object,
+                    phase: runtime.phase,
+                };
+                break;
+            }
+        }
+        if (!nextRide) {
+            ridingElevatorRef.current = null;
+            setElevatorRideLocked(false);
+            return;
+        }
+        const previousCarY = activeRide?.elevatorId === nextRide.elevatorId ? activeRide.previousCarY : nextRide.carY;
+        const deltaY = nextRide.carY - previousCarY;
+        nextRide.object.updateWorldMatrix(true, true);
+        elevatorLocalControllerPosition.copy(group.position);
+        nextRide.object.worldToLocal(elevatorLocalControllerPosition);
+        const localControllerY = activeRide?.elevatorId === nextRide.elevatorId && activeRide.localControllerY !== null
+            ? activeRide.localControllerY
+            : elevatorLocalControllerPosition.y - nextRide.carY;
+        if (Math.abs(deltaY) > 0.0001) {
+            group.position.y += deltaY;
+            controllerRef.current?.resetLinVel();
+        }
+        const shouldLockToCab = nextRide.phase === 'closing' ||
+            nextRide.phase === 'moving' ||
+            (nextRide.phase === 'opening' && nextRide.doorOpen < ELEVATOR_ENTRY_DOOR_OPEN_THRESHOLD);
+        if (shouldLockToCab) {
+            elevatorLocalControllerPosition.copy(group.position);
+            nextRide.object.worldToLocal(elevatorLocalControllerPosition);
+            const desiredLocalY = nextRide.carY + localControllerY;
+            if (Math.abs(elevatorLocalControllerPosition.y - desiredLocalY) > 0.002) {
+                elevatorLocalControllerPosition.y = desiredLocalY;
+                elevatorWorldControllerPosition.copy(elevatorLocalControllerPosition);
+                nextRide.object.localToWorld(elevatorWorldControllerPosition);
+                group.position.y = elevatorWorldControllerPosition.y;
+                controllerRef.current?.resetLinVel();
+                elevatorLocalControllerPosition.copy(group.position);
+                nextRide.object.worldToLocal(elevatorLocalControllerPosition);
+            }
+            const clampedX = Math.max(-nextRide.halfWidth, Math.min(nextRide.halfWidth, elevatorLocalControllerPosition.x));
+            const clampedZ = Math.max(nextRide.cabCenterZ - nextRide.halfDepth, Math.min(nextRide.cabCenterZ + nextRide.halfDepth, elevatorLocalControllerPosition.z));
+            if (Math.abs(clampedX - elevatorLocalControllerPosition.x) > 0.0001 ||
+                Math.abs(clampedZ - elevatorLocalControllerPosition.z) > 0.0001) {
+                elevatorLocalControllerPosition.x = clampedX;
+                elevatorLocalControllerPosition.z = clampedZ;
+                elevatorWorldControllerPosition.copy(elevatorLocalControllerPosition);
+                nextRide.object.localToWorld(elevatorWorldControllerPosition);
+                group.position.x = elevatorWorldControllerPosition.x;
+                group.position.z = elevatorWorldControllerPosition.z;
+                controllerRef.current?.resetLinVel();
+            }
+        }
+        setElevatorRideLocked(shouldLockToCab);
+        ridingElevatorRef.current = {
+            elevatorId: nextRide.elevatorId,
+            localControllerY,
+            previousCarY: nextRide.carY,
+        };
+    }, [camera, setElevatorRideLocked]);
+    const hasStandingClearance = useCallback((position) => {
+        standClearanceRaycaster.set(position, standClearanceUp);
+        standClearanceRaycaster.far = STAND_CLEARANCE;
+        const meshes = [];
+        if (worldRef.current)
+            meshes.push(worldRef.current.mesh);
+        for (const mesh of elevatorColliderMeshesRef.current) {
+            if (mesh.visible)
+                meshes.push(mesh);
+        }
+        return standClearanceRaycaster.intersectObjects(meshes, false).length === 0;
+    }, []);
+    // Drone: the viewer's free flight (`stepDroneFlight`, also behind the viewer's
+    // `DroneController`) fed from this controller's keys — WASD along the view
+    // axes, Space or E rises, Q (or Ctrl) sinks, Shift boosts, Alt slows.
+    useFrame((_, delta) => {
+        if (!isDroneMode)
+            return;
+        if (hostRef.current.paused)
+            return;
+        const movement = movementInputRef.current;
+        droneInput.forward = movement.forward === true;
+        droneInput.backward = movement.backward === true;
+        droneInput.leftward = movement.leftward === true;
+        droneInput.rightward = movement.rightward === true;
+        droneInput.up = movement.jump === true || droneAscendKeyRef.current;
+        droneInput.down = droneDescendKeyRef.current || crouchKeyRef.current;
+        droneInput.boost = movement.run === true;
+        droneInput.slow = droneSlowKeyRef.current;
+        stepDroneFlight(camera, lookRef.current, droneInput, droneVelocityRef.current, delta);
+    }, 2.5);
+    useFrame((_, delta) => {
+        if (isDroneMode)
+            return;
+        if (!controllerRef.current?.group)
+            return;
+        const group = controllerRef.current.group;
+        // Crouch follows the held key; standing back up waits for headroom.
+        // Frozen while the cursor pause is active.
+        if (!suspendRef.current && crouchKeyRef.current !== crouched) {
+            if (crouchKeyRef.current)
+                setCrouched(true);
+            else if (hasStandingClearance(group.position))
+                setCrouched(false);
+        }
+        const targetEyeOffset = crouched ? CROUCH_EYE_OFFSET : CAMERA_EYE_OFFSET;
+        eyeOffsetRef.current +=
+            (targetEyeOffset - eyeOffsetRef.current) * Math.min(1, delta * EYE_LERP_SPEED);
+        cameraOffset.set(0, eyeOffsetRef.current, 0);
+        // The site ground collider is effectively unbounded, but scenes without a
+        // site node only have finite fallback floors — if the controller still ends
+        // up below every collider it can never land, so put it back at the spawn.
+        // Prefer the live spawn node over the mount-time start position so a spawn
+        // moved mid-walkthrough doesn't respawn the player at stale coordinates.
+        const worldBounds = worldRef.current?.bounds;
+        if (worldBounds && group.position.y < worldBounds.min.y - VOID_FALL_RESPAWN_DEPTH) {
+            const respawnPosition = placedSpawn
+                ? [
+                    placedSpawn.position[0],
+                    placedSpawn.position[1] - CONTROLLER_CENTER_FROM_EYE,
+                    placedSpawn.position[2],
+                ]
+                : controllerStart?.position;
+            if (respawnPosition) {
+                group.position.set(respawnPosition[0], respawnPosition[1], respawnPosition[2]);
+                controllerRef.current.resetLinVel();
+                ridingElevatorRef.current = null;
+                setElevatorRideLocked(false);
+            }
+        }
+        group.rotation.y = 0;
+        camera.position.copy(group.position).add(cameraOffset);
+        cameraEuler.set(lookRef.current.pitch, lookRef.current.yaw, 0, 'YXZ');
+        camera.quaternion.setFromEuler(cameraEuler);
+        camera.updateMatrixWorld(true);
+        syncElevatorRide(group);
+        camera.position.copy(group.position).add(cameraOffset);
+        camera.updateMatrixWorld(true);
+        const nextInteractableTarget = resolveInteractableTarget();
+        const previousInteractableTarget = interactableTargetRef.current;
+        if (getInteractableTargetKey(previousInteractableTarget) !==
+            getInteractableTargetKey(nextInteractableTarget)) {
+            interactableTargetRef.current = nextInteractableTarget;
+            useViewer.getState().setHoveredId(nextInteractableTarget?.id ?? null);
+        }
+        useFirstPersonHud.getState().setHud({
+            interact: resolveHudInteract(nextInteractableTarget),
+        });
+        hudLabelFrameRef.current += 1;
+        if (hudLabelFrameRef.current >= HUD_LABEL_SAMPLE_FRAMES) {
+            hudLabelFrameRef.current = 0;
+            camera.getWorldPosition(hudWorldEyePosition);
+            useFirstPersonHud.getState().setHud(resolveFirstPersonHudLabels(hudWorldEyePosition));
+        }
+    }, 2.5);
+    useEffect(() => {
+        return () => {
+            if (useViewer.getState().hoveredId === interactableTargetRef.current?.id) {
+                useViewer.getState().setHoveredId(null);
+            }
+        };
+    }, []);
+    const firstPersonColliderMeshes = useMemo(() => (world ? [world.mesh, ...elevatorColliderMeshes] : elevatorColliderMeshes), [world, elevatorColliderMeshes]);
+    if (isDroneMode || !world) {
+        return null;
+    }
+    return (_jsx(_Fragment, { children: controllerStart && (_jsx(KeyboardControls, { map: keyboardMap, children: _jsx(BVHEcctrl, { acceleration: 26, airDragFactor: 0.3, colliderCapsuleArgs: crouched ? CROUCH_CAPSULE : STAND_CAPSULE, colliderMeshes: firstPersonColliderMeshes, collisionCheckIteration: 3, collisionPushBackDamping: 0.1, collisionPushBackThreshold: 0.001, debug: false, deceleration: 30, delay: 0, fallGravityFactor: 4, floatCheckType: "BOTH", floatDampingC: 36, floatHeight: crouched ? CROUCH_FLOAT_HEIGHT : STAND_FLOAT_HEIGHT, floatPullBackHeight: 0.35, floatSensorRadius: 0.15, floatSpringK: 1200, gravity: 9.81, jumpVel: 5, maxRunSpeed: crouched ? CROUCH_RUN_SPEED : 5, maxSlope: 1.2, maxWalkSpeed: crouched ? CROUCH_WALK_SPEED : 2, paused: isElevatorRideLocked || paused, position: controllerStart.position, ref: setControllerApi }, "first-person-controller") })) }));
+}