@pascal-app/viewer 1.0.7 → 1.1.1

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"}

package/dist/components/viewer/first-person/ground-holes.js

@@ -0,0 +1,116 @@
+/**
+ * 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 { difference, union } from '@pascal-app/core';
+import { BufferAttribute, BufferGeometry, ShapeUtils, Vector2 } from 'three';
+/** Triangles flatter than this in plan (m²) are vertical faces: they hold nothing up. */
+const MIN_PLAN_AREA = 1e-9;
+/** Twice the signed plan area of `a b c` (x right, z down). */
+function orient(a, b, c) {
+    return (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+}
+/**
+ * `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 function cutGroundCollider(geometry, holes) {
+    if (holes.length === 0)
+        return geometry;
+    const cutouts = union(holes);
+    if (cutouts.length === 0)
+        return geometry;
+    const boxes = cutouts.map(({ outer }) => ({
+        minX: Math.min(...outer.map(([x]) => x)),
+        maxX: Math.max(...outer.map(([x]) => x)),
+        minZ: Math.min(...outer.map(([, z]) => z)),
+        maxZ: Math.max(...outer.map(([, z]) => z)),
+    }));
+    const position = geometry.getAttribute('position');
+    const normal = geometry.getAttribute('normal');
+    const positions = [];
+    const normals = [];
+    const push = (corner) => {
+        positions.push(corner.x, corner.y, corner.z);
+        normals.push(corner.nx, corner.ny, corner.nz);
+    };
+    for (let i = 0; i + 2 < position.count; i += 3) {
+        const corners = [0, 1, 2].map((k) => ({
+            x: position.getX(i + k),
+            y: position.getY(i + k),
+            z: position.getZ(i + k),
+            nx: normal.getX(i + k),
+            ny: normal.getY(i + k),
+            nz: normal.getZ(i + k),
+        }));
+        const [a, b, c] = corners;
+        const minX = Math.min(a.x, b.x, c.x);
+        const maxX = Math.max(a.x, b.x, c.x);
+        const minZ = Math.min(a.z, b.z, c.z);
+        const maxZ = Math.max(a.z, b.z, c.z);
+        const reached = boxes.some((box) => box.maxX > minX && box.minX < maxX && box.maxZ > minZ && box.minZ < maxZ);
+        const plan = [
+            [a.x, a.z],
+            [b.x, b.z],
+            [c.x, c.z],
+        ];
+        const determinant = orient(plan[0], plan[1], plan[2]);
+        if (!reached || Math.abs(determinant) < MIN_PLAN_AREA) {
+            corners.forEach(push);
+            continue;
+        }
+        let pieces;
+        try {
+            pieces = difference(plan, cutouts, { throwOnError: true });
+        }
+        catch {
+            corners.forEach(push);
+            continue;
+        }
+        const at = (x, z) => {
+            const wa = ((b.z - c.z) * (x - c.x) + (c.x - b.x) * (z - c.z)) / determinant;
+            const wb = ((c.z - a.z) * (x - c.x) + (a.x - c.x) * (z - c.z)) / determinant;
+            const wc = 1 - wa - wb;
+            const nx = a.nx * wa + b.nx * wb + c.nx * wc;
+            const ny = a.ny * wa + b.ny * wb + c.ny * wc;
+            const nz = a.nz * wa + b.nz * wb + c.nz * wc;
+            const length = Math.hypot(nx, ny, nz) || 1;
+            return {
+                x,
+                y: a.y * wa + b.y * wb + c.y * wc,
+                z,
+                nx: nx / length,
+                ny: ny / length,
+                nz: nz / length,
+            };
+        };
+        for (const piece of pieces) {
+            const rings = [piece.outer, ...piece.holes];
+            const points = rings.flat();
+            const contour = piece.outer.map(([x, z]) => new Vector2(x, z));
+            const voids = piece.holes.map((ring) => ring.map(([x, z]) => new Vector2(x, z)));
+            for (const [p, q, r] of ShapeUtils.triangulateShape(contour, voids)) {
+                const corner = [p, q, r].map((index) => points[index]);
+                const swap = Math.sign(orient(corner[0], corner[1], corner[2])) !== Math.sign(determinant);
+                const ordered = swap ? [corner[0], corner[2], corner[1]] : corner;
+                for (const [x, z] of ordered)
+                    push(at(x, z));
+            }
+        }
+    }
+    const cut = new BufferGeometry();
+    cut.setAttribute('position', new BufferAttribute(new Float32Array(positions), 3));
+    cut.setAttribute('normal', new BufferAttribute(new Float32Array(normals), 3));
+    geometry.dispose();
+    return cut;
+}

package/dist/components/viewer/first-person/mechanism-targets.d.ts

@@ -0,0 +1,27 @@
+import { type AnyNode, type AnyNodeId } from '@pascal-app/core';
+import type { WalkthroughInteract } from '../../../store/use-first-person-hud';
+/**
+ * Whether the walkthrough swings this door or window itself, through the native `operationState`
+ * its door and window systems draw. One built from a script has no native leaf or sash: a swing
+ * would draw nothing, so its clips run through its mechanism, as an authored object's do.
+ */
+export declare function hasNativeLeaf(node: AnyNode | undefined): boolean;
+/** Mounted doors and windows the walkthrough's own door and window targets cover. */
+export declare function nativeOpeningIds(): AnyNodeId[];
+/**
+ * Mounted nodes the walkthrough runs through `capabilities.mechanism`, any kind
+ * included. `covered` holds the nodes a finer target already tested (procedural
+ * parts, catalog item toggles), so no node is targeted twice.
+ */
+export declare function mechanismTargetIds(covered: ReadonlySet<string>): AnyNodeId[];
+/** The walkthrough prompt for a mechanism target: its name and what E does next. */
+export declare function mechanismHudInteract(node: AnyNode): WalkthroughInteract;
+/**
+ * Calls `onChange` when a mounted door built from a script opens or closes. The walkthrough's
+ * collider follows the door's mechanism, and its model's clip is moved by no tween system that
+ * would report the end, as a native door's does: without this the world keeps the leaf that was
+ * there when it was last built. It fires at the toggle: the doorway is passable as the leaves
+ * start to move, and solid again as they start to close.
+ */
+export declare function watchScriptedDoors(onChange: () => void): () => void;
+//# sourceMappingURL=mechanism-targets.d.ts.map

package/dist/components/viewer/first-person/mechanism-targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mechanism-targets.d.ts","sourceRoot":"","sources":["../../../../src/components/viewer/first-person/mechanism-targets.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,SAAS,EAOf,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAA;AAE9E;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAEhE;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,IAAI,SAAS,EAAE,CAS9C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,EAAE,CAU5E;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,CAMvE;AAcD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CASnE"}

package/dist/components/viewer/first-person/mechanism-targets.js

@@ -0,0 +1,79 @@
+import { isScriptedNode, nodeMechanism, nodeRegistry, sceneRegistry, useInteractive, useScene, } from '@pascal-app/core';
+/**
+ * Whether the walkthrough swings this door or window itself, through the native `operationState`
+ * its door and window systems draw. One built from a script has no native leaf or sash: a swing
+ * would draw nothing, so its clips run through its mechanism, as an authored object's do.
+ */
+export function hasNativeLeaf(node) {
+    return !isScriptedNode(node);
+}
+/** Mounted doors and windows the walkthrough's own door and window targets cover. */
+export function nativeOpeningIds() {
+    const nodes = useScene.getState().nodes;
+    const ids = [];
+    for (const kind of ['door', 'window']) {
+        for (const id of sceneRegistry.byType[kind] ?? []) {
+            if (hasNativeLeaf(nodes[id]))
+                ids.push(id);
+        }
+    }
+    return ids;
+}
+/**
+ * Mounted nodes the walkthrough runs through `capabilities.mechanism`, any kind
+ * included. `covered` holds the nodes a finer target already tested (procedural
+ * parts, catalog item toggles), so no node is targeted twice.
+ */
+export function mechanismTargetIds(covered) {
+    const nodes = useScene.getState().nodes;
+    const ids = [];
+    for (const [kind, kindIds] of Object.entries(sceneRegistry.byType)) {
+        if (!nodeRegistry.get(kind)?.capabilities.mechanism)
+            continue;
+        for (const id of kindIds) {
+            if (!covered.has(id) && nodeMechanism(nodes[id]))
+                ids.push(id);
+        }
+    }
+    return ids;
+}
+/** The walkthrough prompt for a mechanism target: its name and what E does next. */
+export function mechanismHudInteract(node) {
+    const mechanism = nodeMechanism(node);
+    if (!mechanism)
+        return null;
+    const on = mechanism.isOn(node, useInteractive.getState());
+    const verb = mechanism.verb === 'open' ? (on ? 'close' : 'open') : on ? 'turn off' : 'turn on';
+    return { label: node.name ?? 'item', verb };
+}
+/** Ids of the mounted doors built from a script that are open, by their mechanism. */
+function openScriptedDoors() {
+    const nodes = useScene.getState().nodes;
+    const state = useInteractive.getState();
+    const open = [];
+    for (const id of sceneRegistry.byType.door ?? []) {
+        const node = nodes[id];
+        if (isScriptedNode(node) && nodeMechanism(node)?.isOn(node, state))
+            open.push(id);
+    }
+    return open.sort().join(',');
+}
+/**
+ * Calls `onChange` when a mounted door built from a script opens or closes. The walkthrough's
+ * collider follows the door's mechanism, and its model's clip is moved by no tween system that
+ * would report the end, as a native door's does: without this the world keeps the leaf that was
+ * there when it was last built. It fires at the toggle: the doorway is passable as the leaves
+ * start to move, and solid again as they start to close.
+ */
+export function watchScriptedDoors(onChange) {
+    let known = openScriptedDoors();
+    return useInteractive.subscribe((state, previous) => {
+        if (state.items === previous.items)
+            return;
+        const next = openScriptedDoors();
+        if (next === known)
+            return;
+        known = next;
+        onChange();
+    });
+}