@pascal-app/viewer 1.0.7 → 1.1.1

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

@@ -0,0 +1,32 @@
+/**
+ * The sculpted ground as walkthrough collision geometry.
+ *
+ * The first-person collider world is a single merged BVH mesh, and before terrain
+ * the ground contributed one flat 2 km box to it. That box is wrong in both
+ * directions on a sculpted site: it holds the player up at the datum inside an
+ * excavation, and buries them inside a hill. This module replaces it.
+ *
+ * Two properties it has to hold, because the whole point is that walking agrees
+ * with every other consumer of the field:
+ *
+ * - **The surface is the field**, sampled at every vertex — the same
+ *   `heightAtSample`/`normalAt` the rendered mesh uses (`terrain-geometry.ts`),
+ *   so what you see is what you stand on. It is deliberately not a decimated
+ *   proxy at realistic field sizes.
+ * - **It extends past the field**, because `heightAt` clamps to the border
+ *   outside it. A collider that stopped at the field edge would drop the player
+ *   into the void one step past the site, which is exactly the bug the flat box
+ *   existed to prevent. The skirt extrudes each border sample outward at its own
+ *   height, so the collider and `heightAt` agree everywhere, not just inside.
+ *
+ * Non-indexed triangles with position + normal, matching what the other collider
+ * contributors emit — `mergeGeometries` requires every input to agree on both.
+ */
+import { type TerrainField } from '@pascal-app/core';
+import * as THREE from 'three';
+/**
+ * Terrain collision geometry in the site's own frame — the caller applies the
+ * site's world matrix, exactly as it did for the flat box it replaces.
+ */
+export declare function createTerrainColliderGeometry(field: TerrainField): THREE.BufferGeometry | null;
+//# sourceMappingURL=terrain-collider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-collider.d.ts","sourceRoot":"","sources":["../../../../src/components/viewer/first-person/terrain-collider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAA4B,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC9E,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AA2E9B;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,CAAC,cAAc,GAAG,IAAI,CA0G9F"}

package/dist/components/viewer/first-person/terrain-collider.js

@@ -0,0 +1,175 @@
+/**
+ * The sculpted ground as walkthrough collision geometry.
+ *
+ * The first-person collider world is a single merged BVH mesh, and before terrain
+ * the ground contributed one flat 2 km box to it. That box is wrong in both
+ * directions on a sculpted site: it holds the player up at the datum inside an
+ * excavation, and buries them inside a hill. This module replaces it.
+ *
+ * Two properties it has to hold, because the whole point is that walking agrees
+ * with every other consumer of the field:
+ *
+ * - **The surface is the field**, sampled at every vertex — the same
+ *   `heightAtSample`/`normalAt` the rendered mesh uses (`terrain-geometry.ts`),
+ *   so what you see is what you stand on. It is deliberately not a decimated
+ *   proxy at realistic field sizes.
+ * - **It extends past the field**, because `heightAt` clamps to the border
+ *   outside it. A collider that stopped at the field edge would drop the player
+ *   into the void one step past the site, which is exactly the bug the flat box
+ *   existed to prevent. The skirt extrudes each border sample outward at its own
+ *   height, so the collider and `heightAt` agree everywhere, not just inside.
+ *
+ * Non-indexed triangles with position + normal, matching what the other collider
+ * contributors emit — `mergeGeometries` requires every input to agree on both.
+ */
+import { heightAtSample, normalAt } from '@pascal-app/core';
+import * as THREE from 'three';
+/**
+ * How far past the field the ground keeps holding the player, in metres. Matches
+ * the flat box's half-extent so a site's collider bounds do not change size when
+ * it gains terrain.
+ */
+const SKIRT_REACH = 1000;
+/**
+ * Cell budget before the collider decimates.
+ *
+ * 66k cells is a 257² field — the largest anything realistic produces, and ~131k
+ * triangles, which the BVH builds in well under a frame's worth of budget. The
+ * schema allows up to 4097² (a decode-bomb guard, not a real terrain); at that
+ * size an exact collider would be 100M triangles, so past the budget this steps
+ * the sample grid and the collider becomes a faithful-but-coarser version of the
+ * same surface rather than an out-of-memory crash.
+ */
+const MAX_COLLIDER_CELLS = 66_000;
+function colliderStride(field) {
+    const cells = Math.max(1, (field.cols - 1) * (field.rows - 1));
+    if (cells <= MAX_COLLIDER_CELLS)
+        return 1;
+    return Math.ceil(Math.sqrt(cells / MAX_COLLIDER_CELLS));
+}
+/** The sample indices the collider walks: every `stride`-th, always including the border. */
+function sampleLine(count, stride) {
+    const line = [];
+    for (let i = 0; i < count - 1; i += stride)
+        line.push(i);
+    line.push(count - 1);
+    return line;
+}
+class TriangleSink {
+    field;
+    positions = [];
+    normals = [];
+    constructor(field) {
+        this.field = field;
+    }
+    push(v) {
+        this.positions.push(v.x, v.y, v.z);
+        const [nx, ny, nz] = normalAt(this.field, v.x, v.z);
+        this.normals.push(nx, ny, nz);
+    }
+    /**
+     * One cell, given its four corners named by axis order. Winding matches
+     * `buildTerrainMesh`: `(p00, p01, p10)` and `(p10, p01, p11)` faces +Y, which is
+     * what the spawn resolver's `normal.dot(UP) > 0.2` floor test needs.
+     */
+    quad(p00, p10, p01, p11) {
+        this.push(p00);
+        this.push(p01);
+        this.push(p10);
+        this.push(p10);
+        this.push(p01);
+        this.push(p11);
+    }
+    build() {
+        if (this.positions.length === 0)
+            return null;
+        const geometry = new THREE.BufferGeometry();
+        geometry.setAttribute('position', new THREE.BufferAttribute(new Float32Array(this.positions), 3));
+        geometry.setAttribute('normal', new THREE.BufferAttribute(new Float32Array(this.normals), 3));
+        return geometry;
+    }
+}
+/**
+ * Terrain collision geometry in the site's own frame — the caller applies the
+ * site's world matrix, exactly as it did for the flat box it replaces.
+ */
+export function createTerrainColliderGeometry(field) {
+    if (field.cols < 2 || field.rows < 2)
+        return null;
+    const stride = colliderStride(field);
+    const cols = sampleLine(field.cols, stride);
+    const rows = sampleLine(field.rows, stride);
+    const sink = new TriangleSink(field);
+    const xAt = (col) => field.origin[0] + col * field.spacing;
+    const zAt = (row) => field.origin[1] + row * field.spacing;
+    const at = (col, row) => ({
+        x: xAt(col),
+        y: heightAtSample(field, col, row),
+        z: zAt(row),
+    });
+    for (let ri = 0; ri < rows.length - 1; ri++) {
+        const r0 = rows[ri];
+        const r1 = rows[ri + 1];
+        for (let ci = 0; ci < cols.length - 1; ci++) {
+            const c0 = cols[ci];
+            const c1 = cols[ci + 1];
+            sink.quad(at(c0, r0), at(c1, r0), at(c0, r1), at(c1, r1));
+        }
+    }
+    // The skirt: each border sample extruded outward at its own height, so stepping
+    // off the field lands on the border height rather than on nothing. This is the
+    // collider spelling of `heightAt`'s edge clamp.
+    const firstCol = 0;
+    const lastCol = field.cols - 1;
+    const firstRow = 0;
+    const lastRow = field.rows - 1;
+    const westX = xAt(firstCol) - SKIRT_REACH;
+    const eastX = xAt(lastCol) + SKIRT_REACH;
+    const northZ = zAt(firstRow) - SKIRT_REACH;
+    const southZ = zAt(lastRow) + SKIRT_REACH;
+    for (let ci = 0; ci < cols.length - 1; ci++) {
+        const c0 = cols[ci];
+        const c1 = cols[ci + 1];
+        const north0 = at(c0, firstRow);
+        const north1 = at(c1, firstRow);
+        sink.quad({ x: north0.x, y: north0.y, z: northZ }, { x: north1.x, y: north1.y, z: northZ }, north0, north1);
+        const south0 = at(c0, lastRow);
+        const south1 = at(c1, lastRow);
+        sink.quad(south0, south1, { x: south0.x, y: south0.y, z: southZ }, {
+            x: south1.x,
+            y: south1.y,
+            z: southZ,
+        });
+    }
+    for (let ri = 0; ri < rows.length - 1; ri++) {
+        const r0 = rows[ri];
+        const r1 = rows[ri + 1];
+        const west0 = at(firstCol, r0);
+        const west1 = at(firstCol, r1);
+        sink.quad({ x: westX, y: west0.y, z: west0.z }, west0, { x: westX, y: west1.y, z: west1.z }, west1);
+        const east0 = at(lastCol, r0);
+        const east1 = at(lastCol, r1);
+        sink.quad(east0, { x: eastX, y: east0.y, z: east0.z }, east1, {
+            x: eastX,
+            y: east1.y,
+            z: east1.z,
+        });
+    }
+    // Corner quads, flat at the corner sample's height — the diagonal region no edge
+    // strip covers, and where `heightAt` also reports the corner value.
+    const corners = [
+        [at(firstCol, firstRow), westX, northZ],
+        [at(lastCol, firstRow), eastX, northZ],
+        [at(firstCol, lastRow), westX, southZ],
+        [at(lastCol, lastRow), eastX, southZ],
+    ];
+    for (const [corner, farX, farZ] of corners) {
+        const minX = Math.min(corner.x, farX);
+        const maxX = Math.max(corner.x, farX);
+        const minZ = Math.min(corner.z, farZ);
+        const maxZ = Math.max(corner.z, farZ);
+        const y = corner.y;
+        sink.quad({ x: minX, y, z: minZ }, { x: maxX, y, z: minZ }, { x: minX, y, z: maxZ }, { x: maxX, y, z: maxZ });
+    }
+    return sink.build();
+}

package/dist/components/viewer/glb-replace-instances.d.ts

@@ -1,4 +1,4 @@
-import { type AnyNode } from '@pascal-app/core';
+import { type AnyNode, type GeometryContext } from '@pascal-app/core';
 import type { Object3D } from 'three';
 /**
  * Re-renders `bake: 'replace'` kinds (e.g. plugin trees) live over the baked GLB.
@@ -9,10 +9,13 @@ import type { Object3D } from 'three';
  * free, and a forest stays a few instanced draw calls.
  *
  * Memoized: `GlbScene` re-renders each frame on camera move; `nodes` and
- * `identity` are stable refs, so this whole subtree short-circuits.
+ * `identity` are stable refs, so this whole subtree short-circuits; `resolve`
+ * must be stable too.
  */
-export declare const GlbReplaceInstances: import("react").MemoExoticComponent<({ nodes, identity, }: {
+export declare const GlbReplaceInstances: import("react").MemoExoticComponent<({ nodes, identity, resolve, }: {
     nodes: AnyNode[];
     identity: Map<string, Object3D>;
+    /** Looks up nodes of the published scene graph; handed to every renderer. */
+    resolve?: GeometryContext['resolve'];
 }) => import("react").JSX.Element>;
 //# sourceMappingURL=glb-replace-instances.d.ts.map

package/dist/components/viewer/glb-replace-instances.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glb-replace-instances.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/glb-replace-instances.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,OAAO,EAA0C,MAAM,kBAAkB,CAAA;AAGvF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAerC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,6DAG7B;IACD,KAAK,EAAE,OAAO,EAAE,CAAA;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;CAChC,iCAyCC,CAAA"}
+{"version":3,"file":"glb-replace-instances.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/glb-replace-instances.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,eAAe,EAErB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAiBrC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,sEAI7B;IACD,KAAK,EAAE,OAAO,EAAE,CAAA;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC/B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAA;CACrC,iCAyCC,CAAA"}

package/dist/components/viewer/glb-replace-instances.js

@@ -1,6 +1,6 @@
 'use client';
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
-import { nodeRegistry } from '@pascal-app/core';
+import { nodeRegistry, } from '@pascal-app/core';
 import { createPortal } from '@react-three/fiber';
 import { Fragment, lazy, memo, Suspense, useMemo } from 'react';
 // Lazy components cached by their source so React.lazy isn't re-invoked per render.
@@ -22,9 +22,10 @@ function getReplaceRenderer(source) {
  * free, and a forest stays a few instanced draw calls.
  *
  * Memoized: `GlbScene` re-renders each frame on camera move; `nodes` and
- * `identity` are stable refs, so this whole subtree short-circuits.
+ * `identity` are stable refs, so this whole subtree short-circuits; `resolve`
+ * must be stable too.
  */
-export const GlbReplaceInstances = memo(function GlbReplaceInstances({ nodes, identity, }) {
+export const GlbReplaceInstances = memo(function GlbReplaceInstances({ nodes, identity, resolve, }) {
     const byLevel = useMemo(() => {
         const levels = new Map();
         for (const node of nodes) {
@@ -54,7 +55,7 @@ export const GlbReplaceInstances = memo(function GlbReplaceInstances({ nodes, id
             if (!source)
                 return;
             const Renderer = getReplaceRenderer(source);
-            portals.push(_jsx(Fragment, { children: createPortal(_jsx(Suspense, { fallback: null, children: _jsx(Renderer, { nodes: kindNodes }) }), anchor) }, `${parentId}:${kind}`));
+            portals.push(_jsx(Fragment, { children: createPortal(_jsx(Suspense, { fallback: null, children: _jsx(Renderer, { nodes: kindNodes, resolve: resolve }) }), anchor) }, `${parentId}:${kind}`));
         });
     });
     return _jsx(_Fragment, { children: portals });

package/dist/components/viewer/glb-scene.d.ts

@@ -67,7 +67,9 @@ export declare function GlbScene({ url, interactiveItems, referenceNodes, replac
     /** Clicks and hovers on the building; without it the scene is look-only. */
     onPick?: (event: GlbPickEvent) => void;
     onWalkthroughChange?: (state: GlbWalkthrough) => void;
-    /** The scene graph's nodes, so the selection callout can say what each element is. */
+    /** Every node of the scene graph the artifact was baked from: the selection
+     *  callout says what each element is, and `replace` renderers resolve their
+     *  parent and siblings. A stable reference. */
     sceneNodes?: Readonly<Record<string, AnyNode>>;
 }): import("react").JSX.Element;
 export {};

package/dist/components/viewer/glb-scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glb-scene.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/glb-scene.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,OAAO,EAab,MAAM,kBAAkB,CAAA;AASzB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAoB9B,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAuB3E;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAA;IAC/D,SAAS,EAAE;QAAE,GAAG,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAA;CAC1E,CAAA;AAKD;0EAC0E;AAC1E,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAC/D,GAAG,IAAI,CAAA;AAqDR,KAAK,YAAY,GAAG;IAAE,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAA;CAAE,CAAA;AA4CpE;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,GAC5C,CAAC,WAAW,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAA;CAAE,CAAC,GAAG,IAAI,CAkB5E;AASD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,MAAM,EACN,mBAAmB,EACnB,UAAU,GACX,EAAE;IACD,GAAG,EAAE,MAAM,CAAA;IACX;oFACgF;IAChF,gBAAgB,CAAC,EAAE,kBAAkB,EAAE,CAAA;IACvC;mFAC+E;IAC/E,cAAc,CAAC,EAAE,OAAO,EAAE,CAAA;IAC1B;kFAC8E;IAC9E,YAAY,CAAC,EAAE,OAAO,EAAE,CAAA;IACxB,iFAAiF;IACjF,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAA;IACxE,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IACtC,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IACrD,sFAAsF;IACtF,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAC/C,+BAu7BA"}
+{"version":3,"file":"glb-scene.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/glb-scene.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,OAAO,EAcb,MAAM,kBAAkB,CAAA;AASzB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAoB9B,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAuB3E;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAA;IAC/D,SAAS,EAAE;QAAE,GAAG,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAA;CAC1E,CAAA;AAKD;0EAC0E;AAC1E,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAC/D,GAAG,IAAI,CAAA;AAqDR,KAAK,YAAY,GAAG;IAAE,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAA;CAAE,CAAA;AA4CpE;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,GAC5C,CAAC,WAAW,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAA;CAAE,CAAC,GAAG,IAAI,CAkB5E;AASD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,MAAM,EACN,mBAAmB,EACnB,UAAU,GACX,EAAE;IACD,GAAG,EAAE,MAAM,CAAA;IACX;oFACgF;IAChF,gBAAgB,CAAC,EAAE,kBAAkB,EAAE,CAAA;IACvC;mFAC+E;IAC/E,cAAc,CAAC,EAAE,OAAO,EAAE,CAAA;IAC1B;kFAC8E;IAC9E,YAAY,CAAC,EAAE,OAAO,EAAE,CAAA;IACxB,iFAAiF;IACjF,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAA;IACxE,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IACtC,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IACrD;;mDAE+C;IAC/C,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAC/C,+BA47BA"}

package/dist/components/viewer/glb-scene.js

@@ -127,6 +127,7 @@ export function GlbScene({ url, interactiveItems, referenceNodes, replaceNodes,
     const gltf = useGLTFKTX2(url);
     const rootRef = useRef(null);
     const actions = useClipActions(gltf.animations, rootRef);
+    const resolveNode = useMemo(() => sceneNodes ? (id) => sceneNodes[id] : undefined, [sceneNodes]);
     const proceduralPlayback = useMemo(() => {
         const byNode = new Map();
         gltf.scene.traverse((object) => {
@@ -987,7 +988,7 @@ export function GlbScene({ url, interactiveItems, referenceNodes, replaceNodes,
         for (const mesh of occluderOwnMeshes)
             clearShadowOnly(mesh);
     }, [occluderOwnMeshes]);
-    return (_jsxs("group", { ref: rootRef, children: [walkingOnFoot && shuttersInView ? _jsx(GlbShuttersPrompt, {}) : null, _jsx("primitive", { object: gltf.scene, onClick: handleClick, onPointerMissed: handlePointerMissed, onPointerMove: handlePointerMove, onPointerOut: handlePointerOut }), _jsx(GlbSelectionCallout, { identity: identity, isOpen: isOpen, items: interactiveItems, loopMechanisms: loopMechanisms, sceneNodes: sceneNodes, toggleOpen: toggleOpenable }), interactiveItems?.length ? (_jsx(GlbInteractive, { actions: actions, identity: identity, items: interactiveItems })) : null, referenceNodes?.length ? (_jsx(GlbReferenceNodes, { identity: identity, nodes: referenceNodes })) : null, replaceNodes?.length ? (_jsx(GlbReplaceInstances, { identity: identity, nodes: replaceNodes })) : null, _jsx(GlbDaylightGround, { root: gltf.scene })] }));
+    return (_jsxs("group", { ref: rootRef, children: [walkingOnFoot && shuttersInView ? _jsx(GlbShuttersPrompt, {}) : null, _jsx("primitive", { object: gltf.scene, onClick: handleClick, onPointerMissed: handlePointerMissed, onPointerMove: handlePointerMove, onPointerOut: handlePointerOut }), _jsx(GlbSelectionCallout, { identity: identity, isOpen: isOpen, items: interactiveItems, loopMechanisms: loopMechanisms, sceneNodes: sceneNodes, toggleOpen: toggleOpenable }), interactiveItems?.length ? (_jsx(GlbInteractive, { actions: actions, identity: identity, items: interactiveItems })) : null, referenceNodes?.length ? (_jsx(GlbReferenceNodes, { identity: identity, nodes: referenceNodes })) : null, replaceNodes?.length ? (_jsx(GlbReplaceInstances, { identity: identity, nodes: replaceNodes, resolve: resolveNode })) : null, _jsx(GlbDaylightGround, { root: gltf.scene })] }));
 }
 function playShutterSound(node) {
     const id = node.userData.pascalId;

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

@@ -9,7 +9,7 @@ export declare const CROUCH_RUN_SPEED = 1.4;
 export declare const STAND_CLEARANCE = 1.25;
 export declare const EYE_LERP_SPEED = 12;
 /**
- * First-person walkthrough controller for the baked GLB. Reuses the editor's
+ * First-person walkthrough controller for the baked GLB. Uses the shared
  * `BVHEcctrl` capsule character controller (gravity, jump, sprint, ground-float,
  * mesh collision) fed a collider built from the artifact's own geometry — so the
  * baked viewer walks the building with the same physics as the editor, without

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

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

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

@@ -16,8 +16,7 @@ import { applyWalkthroughCameraClipping } from './viewer-camera';
 // awareness without wide-angle distortion. Applied only while walking — both
 // walkthrough controllers read this and restore the orbit FOV on exit.
 export const WALKTHROUGH_FOV = 60;
-// Eye/capsule geometry mirrors the editor's first-person controller so the
-// baked walkthrough feels identical. The capsule centre sits below the eye; the
+// Shared with the live walkthrough so baked and parametric scenes feel identical. The capsule centre sits below the eye; the
 // camera rides the capsule with a small offset and the controller floats it to
 // the ground.
 const CAMERA_EYE_OFFSET = 0.45;
@@ -109,7 +108,7 @@ function boxFloorGeometry(cx, topY, cz, width, depth) {
 // Fallback ground so the player never falls into the void: a single large
 // ground plane at the lowest level (level 0). Upper levels rely on their own
 // baked slabs — a slab-less upper floor lets you fall down to the ground, which
-// the ground plane catches. (Mirrors the editor walkthrough's site ground.)
+// the ground plane catches. (Mirrors the live walkthrough's site ground.)
 function addFallbackFloors(scene, geometries) {
     const sceneBounds = new Box3();
     for (const geometry of geometries) {
@@ -224,7 +223,7 @@ function resolveGlbSpawn(scene) {
     };
 }
 /**
- * First-person walkthrough controller for the baked GLB. Reuses the editor's
+ * First-person walkthrough controller for the baked GLB. Uses the shared
  * `BVHEcctrl` capsule character controller (gravity, jump, sprint, ground-float,
  * mesh collision) fed a collider built from the artifact's own geometry — so the
  * baked viewer walks the building with the same physics as the editor, without

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/index.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,SAAS,EAGd,KAAK,gBAAgB,EAKtB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAkB,KAAK,YAAY,EAAsB,MAAM,oBAAoB,CAAA;AAC1F,OAAO,EACL,KAAK,aAAa,EAOnB,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAMrC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACrE,OAAO,EAAuB,KAAK,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AAI5F,OAAkB,EAAE,KAAK,aAAa,EAAsB,MAAM,wBAAwB,CAAA;AAe1F,OAAuB,EAAwB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAa1F,OAAO,QAAQ,oBAAoB,CAAC;IAOlC,UAAU,aAAa;QACrB,qBAAqB,EAAE,YAAY,CAAC,OAAO,KAAK,CAAC,qBAAqB,CAAC,CAAA;KACxE;CACF;AAsPD;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAS/C;AAsED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,CAAC,CAAA;IACrD,KAAK,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,CAAC,CAAA;IACnD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CACnC;AASD,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,gBAAgB,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IACvC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,aAAa,CAAC,EAAE;QACd,OAAO,CAAC,EAAE,aAAa,CAAA;QACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;QAClB,WAAW,CAAC,EAAE,WAAW,CAAA;KAC1B,CAAA;IACD,6FAA6F;IAC7F,YAAY,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACtC,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAC7C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IACxC;;;;OAIG;IACH,YAAY,CAAC,EAAE,uBAAuB,CAAA;IACtC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,sEAAsE;IACtE,SAAS,CAAC,EAAE,sBAAsB,CAAA;CACnC;AAED,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;CAC3C,CAAA;AAED,QAAA,MAAM,MAAM,sGA6SV,CAAA;eA+Ea,MAAM"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/index.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,SAAS,EAId,KAAK,gBAAgB,EAKtB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAkB,KAAK,YAAY,EAAsB,MAAM,oBAAoB,CAAA;AAC1F,OAAO,EACL,KAAK,aAAa,EAOnB,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAMrC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACrE,OAAO,EAAuB,KAAK,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AAK5F,OAAkB,EAAE,KAAK,aAAa,EAAsB,MAAM,wBAAwB,CAAA;AAe1F,OAAuB,EAAwB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAa1F,OAAO,QAAQ,oBAAoB,CAAC;IAOlC,UAAU,aAAa;QACrB,qBAAqB,EAAE,YAAY,CAAC,OAAO,KAAK,CAAC,qBAAqB,CAAC,CAAA;KACxE;CACF;AAsPD;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAS/C;AAsED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,CAAC,CAAA;IACrD,KAAK,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,CAAC,CAAA;IACnD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CACnC;AASD,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,gBAAgB,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IACvC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,aAAa,CAAC,EAAE;QACd,OAAO,CAAC,EAAE,aAAa,CAAA;QACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;QAClB,WAAW,CAAC,EAAE,WAAW,CAAA;KAC1B,CAAA;IACD,6FAA6F;IAC7F,YAAY,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACtC,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAC7C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IACxC;;;;OAIG;IACH,YAAY,CAAC,EAAE,uBAAuB,CAAA;IACtC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,sEAAsE;IACtE,SAAS,CAAC,EAAE,sBAAsB,CAAA;CACnC;AAED,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;CAC3C,CAAA;AAED,QAAA,MAAM,MAAM,sGA+SV,CAAA;eA+Ea,MAAM"}

package/dist/components/viewer/index.js

@@ -1,6 +1,6 @@
 'use client';
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { nodeRegistry, RoofElevationSystem, StairOpeningSystem, sceneRegistry, useInteractive, useScene, } from '@pascal-app/core';
+import { isDevelopmentBuild, nodeRegistry, RoofElevationSystem, StairOpeningSystem, sceneRegistry, useInteractive, useScene, } from '@pascal-app/core';
 import { Canvas, extend, useFrame, useThree } from '@react-three/fiber';
 import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useRef, useState, } from 'react';
 import * as THREE from 'three/webgpu';
@@ -13,6 +13,7 @@ import { choosePointerEvents } from '../../lib/pointer-events';
 import { initializeGpuRenderer } from '../../lib/renderer-capability';
 import { getSceneTheme } from '../../lib/scene-themes';
 import { installTextureNodeNullGuard } from '../../lib/texture-node-guard';
+import { viewerPreferenceStorage } from '../../lib/viewer-preference-storage';
 import useViewer, {} from '../../store/use-viewer';
 import { FloorElevationSystem } from '../../systems/floor-elevation/floor-elevation-system';
 import { GeometrySystem } from '../../systems/geometry/geometry-system';
@@ -68,7 +69,7 @@ const DIRTY_BUILD_KINDS = new Set([
     'wall',
     'window',
 ]);
-const warnedEmptyDraw = process.env.NODE_ENV === 'production' ? null : new WeakSet();
+const warnedEmptyDraw = isDevelopmentBuild() ? new WeakSet() : null;
 /**
  * Renderer-level safety net against the empty-vertex-buffer crash.
  *
@@ -375,7 +376,7 @@ const Viewer = forwardRef(function Viewer({ children, hoverStyles = DEFAULT_HOVE
         if (!hasDefaultRender || typeof window === 'undefined')
             return;
         let persistedState = {};
-        const rawPreferences = window.localStorage.getItem('viewer-preferences');
+        const rawPreferences = viewerPreferenceStorage.getItem('viewer-preferences');
         if (rawPreferences) {
             try {
                 const parsed = JSON.parse(rawPreferences);
@@ -421,7 +422,10 @@ const Viewer = forwardRef(function Viewer({ children, hoverStyles = DEFAULT_HOVE
     if (showGpuFallback) {
         return _jsx(UnsupportedGpuViewerFallback, {});
     }
-    return (_jsxs(_Fragment, { children: [(perf || PERF_OVERLAY_ENABLED) && _jsx(PerfPanel, {}), _jsx(Canvas, { ref: subscribeWallBuildInteractions, camera: { position: [50, 50, 50], fov: 50 }, className: `transition-colors duration-700 ${transparentBackground ? 'bg-transparent' : isDark ? 'bg-[#1f2433]' : 'bg-[#fafafa]'}`, dpr: [1, maxDpr], events: pointerEvents, frameloop: "never", gl: ((props) => {
+    return (_jsxs(_Fragment, { children: [(perf || PERF_OVERLAY_ENABLED) && _jsx(PerfPanel, {}), _jsx(Canvas, { ref: subscribeWallBuildInteractions, camera: { position: [50, 50, 50], fov: 50 }, style: {
+                    backgroundColor: transparentBackground ? 'transparent' : isDark ? '#1f2433' : '#fafafa',
+                    transition: 'background-color 700ms cubic-bezier(0.4, 0, 0.2, 1), color 700ms cubic-bezier(0.4, 0, 0.2, 1)',
+                }, dpr: [1, maxDpr], events: pointerEvents, frameloop: "never", gl: ((props) => {
                     const canvas = props.canvas;
                     const cached = canvas ? WEBGPU_RENDERER_CACHE.get(canvas) : undefined;
                     if (cached)

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

@@ -0,0 +1,17 @@
+export type LiveWalkthroughControllerProps = {
+    /** Freeze movement and look while a host renders a still. */
+    paused?: boolean;
+    /**
+     * Whether the host owns camera FOV right now (e.g. a capture rig). Read when walkthrough
+     * starts and when it ends, so the answer at teardown decides whether the orbit FOV returns.
+     */
+    externalFov?: () => boolean;
+    /** Allow locked-pointer clicks to operate the targeted object (E/R still work). */
+    pointerInteraction?: boolean;
+    /** Keep walkthrough active when pointer lock is lost; Escape with a free cursor exits. */
+    suspendOnUnlock?: boolean;
+    /** Called after walkthroughMode is cleared, including on Escape or pointer unlock. */
+    onExit?: () => void;
+};
+export declare function LiveWalkthroughController(props: LiveWalkthroughControllerProps): import("react").JSX.Element | null;
+//# sourceMappingURL=live-walkthrough-controller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"live-walkthrough-controller.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/live-walkthrough-controller.tsx"],"names":[],"mappings":"AA8uBA,MAAM,MAAM,8BAA8B,GAAG;IAC3C,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAA;IAC3B,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,0FAA0F;IAC1F,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAKD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,8BAA8B,sCAG9E"}