@ifc-lite/renderer 1.41.1 → 1.44.0

package/dist/camera-guards.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Finiteness predicates shared by every camera sub-system.
+ *
+ * They live in one module rather than next to their first caller because the
+ * same three mistakes keep being made independently in `camera.ts`,
+ * `camera-controls.ts`, `camera-animation.ts` and `camera-projection.ts`:
+ *
+ *  - **A magnitude comparison is not a finiteness check.** Every comparison
+ *    involving NaN is false, so `dist < eps` does not reject NaN — it waves it
+ *    through the guard that looks like it is rejecting it (#2441).
+ *  - **A lower-bound floor rejects NaN but admits Infinity.** `len > 1e-10` is
+ *    false for NaN and *true* for Infinity, and scaling infinite components by
+ *    `1 / Infinity` is `Infinity * 0` — NaN. A guard written as
+ *    `!Number.isNaN(...)` would pass every existing test and still be wrong.
+ *  - **`Math.max`/`Math.min` are NaN-transparent.** `Math.max(0.01, NaN)` is
+ *    `NaN`, not the floor, so a clamp forwards a malformed value rather than
+ *    absorbing it.
+ *
+ * Every predicate here therefore keys on `Number.isFinite`, which is the only
+ * test that rejects NaN and both infinities together.
+ */
+import type { Vec3 } from './types.js';
+/**
+ * Smallest orthographic half-height the projection matrix is ever built from.
+ * Matches the floor the orthographic zoom clamps to in `CameraControls`.
+ */
+export declare const MIN_ORTHO_SIZE = 0.01;
+/** Default orthographic half-height, in world units, and the neutral fallback. */
+export declare const DEFAULT_ORTHO_SIZE = 50;
+/**
+ * Is `dist` a usable camera-to-target radius — finite, and at least `min` away
+ * from zero so dividing by it means something?
+ *
+ * The navigation gestures all opened with a bare `dist < eps` early return.
+ * That is a magnitude test, not a finiteness test, so a malformed pose walked
+ * straight past it (#2441). Past the guard, the gesture writes its result into
+ * `camera.position` *and* `camera.target`, so a single non-finite coordinate
+ * (a BCF viewpoint restored from a file reaches the public setters
+ * unvalidated) spreads across all six on the first drag.
+ *
+ * Callers keep their own fallback: there is no single substitute distance that
+ * is right for all of them, which is also why `Camera.getDistance()` reports
+ * the pose verbatim rather than sanitizing it centrally.
+ */
+export declare function isUsableDistance(dist: number, min: number): boolean;
+/**
+ * Is `up` a usable screen-up reference — every component finite?
+ *
+ * `up` is the third vector of the pose, and it reaches the camera exactly the
+ * way `position` and `target` do: BCF stores `CameraUpVector`, `bcfToViewerCoords`
+ * only swaps axes, and `applyViewpoint` writes the result straight through
+ * (`animateToWithUp` on the animated path — which bypasses `setUp` entirely —
+ * or `setUp` on the instant one).
+ *
+ * Finiteness only, deliberately no magnitude floor. `normalize` already absorbs
+ * a zero-length or degenerate `up` by returning `{0,0,0}`, and a *short* `up` is
+ * a valid input whose direction is perfectly well defined — `MathUtils.lookAt`
+ * documents the same thing and keys its own degeneracy test on the angle rather
+ * than a length for exactly this reason. A floor here would silently drop the
+ * cursor anchor for poses that navigate correctly today.
+ *
+ * The floor `normalize` used to have was a *lower* bound, which is what left
+ * the gap: `len > 1e-10` is false for NaN (so a NaN `up` degraded safely to
+ * the zero vector) but **true for Infinity**, and scaling infinite components
+ * by `1 / Infinity` is `Infinity * 0` — NaN. Measured, not reasoned: `up`
+ * `(Infinity, 1, 0)` on a finite pose came back from one cursor-anchored zoom
+ * with position AND target `(NaN, NaN, NaN)`, in both projection modes (#2441).
+ * Both copies of `normalize` now key that floor on `Number.isFinite` too
+ * (#2479), so an unusable `up` reaches the same zero vector by either route —
+ * this predicate says so at the top of the gesture rather than relying on a
+ * helper's degradation three lines in, and it is what stops the *pose* being
+ * rewritten from a basis that carries no orientation.
+ *
+ * As with {@link isUsableDistance}, the caller keeps its own fallback and the
+ * pose is left exactly as it was found — `getUp()` still reports the malformed
+ * vector, so a restored viewpoint is not silently rewritten on its way back out.
+ */
+export declare function isUsableUp(up: Vec3): boolean;
+/**
+ * Clamp an orthographic half-height, rejecting a non-finite one.
+ *
+ * `Math.max`/`Math.min` are NaN-transparent, so a clamp alone does not stop a
+ * malformed value reaching the projection matrix (#2441). Returns `null` when
+ * there is no usable size, so the caller can keep the value it already had
+ * rather than substitute an arbitrary one.
+ *
+ * The `Infinity` rejection is not theoretical: `orthoSize` is scaled in place
+ * by the orthographic zoom, so a legitimately huge but finite half-height
+ * overflows to `Infinity` after enough zoom-out notches, and
+ * `Math.max(MIN_ORTHO_SIZE, Infinity)` is `Infinity`.
+ */
+export declare function usableOrthoSize(size: number): number | null;
+/**
+ * Are all of `values` finite?
+ *
+ * The gesture *arguments* — wheel deltas, pointer deltas, walk axes — are a
+ * different input class from the pose the gestures already guard (#2473), and
+ * they reach the same arithmetic. Measured on the pre-guard code: `orbit(NaN,
+ * 0)`, `pan(NaN, 0)`, `zoom(NaN)` and `moveFirstPerson(NaN, 0, 0)` each turned
+ * a perfectly finite pose into a non-finite one in a single call, and
+ * `orbit(Infinity, 0)` / `pan(Infinity, 0)` / `moveFirstPerson(Infinity, 0, 0)`
+ * did the same — the two do **not** behave alike everywhere, so both must be
+ * tested. (`zoom` is the exception: its delta is clamped by
+ * `Math.min(|delta| * s, MAX_ZOOM_DELTA)`, which absorbs `Infinity` but not
+ * `NaN`.)
+ */
+export declare function areFiniteNumbers(...values: number[]): boolean;
+/**
+ * Is this a usable cursor anchor — a finite cursor position inside a viewport
+ * with a real extent?
+ *
+ * The cursor-anchored zoom divides by the canvas dimensions, so they need
+ * `> 0` and not merely "truthy". Truthiness already rejects `0` and `NaN`
+ * (both falsy) which is why a collapsed canvas never reached the division, but
+ * it accepts `Infinity` and a negative width — the latter mirrors the anchor
+ * and drifts the target the wrong way. `Number.isFinite(w) && w > 0` is the
+ * check that means what the division needs.
+ */
+export declare function isUsableCursorAnchor(cursorX: number, cursorY: number, viewportWidth: number, viewportHeight: number): boolean;
+/**
+ * Is this AABB something the camera can be fitted to?
+ *
+ * Two rejections, and they are different failures:
+ *
+ *  - **Non-finite corners.** Fitting computes `center = (min + max) / 2` and
+ *    `size = max - min`, and writes both into the pose. `Math.max` picking the
+ *    largest extent is NaN-transparent, so one bad coordinate reaches
+ *    `camera.position`, `camera.target` *and* (in orthographic mode)
+ *    `orthoSize`, which `getOrthoSize()` then hands to a saved viewpoint —
+ *    persisting the damage past the session (#2461).
+ *  - **An inverted box** (`max < min` on any axis). That is the empty-AABB
+ *    sentinel every accumulator in this package starts from (`min = +Infinity,
+ *    max = -Infinity`) leaking out as if it were a real box, which is what a
+ *    mesh with no finite vertices produces. Its centre is `NaN` and its size
+ *    is negative; there is nothing to frame.
+ *
+ * A *degenerate* box (`max === min` on some or all axes — a flat wall, a
+ * single point) is explicitly **not** rejected: it is a legitimate thing to
+ * frame and `frameBounds` already centres on it.
+ *
+ * The answer to an unusable box is to reject the fit and leave the pose alone,
+ * not to clamp: there is no meaningful substitute for an infinite or inverted
+ * extent, and no previous bounds to fall back to at these entry points, which
+ * are stateless. Keeping the pose the user already had is the same policy
+ * `setAspect`, `setFOV` and `setOrthoSize` settled on (#2441/#2450).
+ */
+export declare function isUsableBounds(min: Vec3, max: Vec3): boolean;
+//# sourceMappingURL=camera-guards.d.ts.map

package/dist/camera-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-guards.d.ts","sourceRoot":"","sources":["../src/camera-guards.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,IAAI,GAAG,OAAO,CAE5C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAK7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,GACrB,OAAO,CAMT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAO5D"}

package/dist/camera-guards.js

@@ -0,0 +1,150 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * Smallest orthographic half-height the projection matrix is ever built from.
+ * Matches the floor the orthographic zoom clamps to in `CameraControls`.
+ */
+export const MIN_ORTHO_SIZE = 0.01;
+/** Default orthographic half-height, in world units, and the neutral fallback. */
+export const DEFAULT_ORTHO_SIZE = 50;
+/**
+ * Is `dist` a usable camera-to-target radius — finite, and at least `min` away
+ * from zero so dividing by it means something?
+ *
+ * The navigation gestures all opened with a bare `dist < eps` early return.
+ * That is a magnitude test, not a finiteness test, so a malformed pose walked
+ * straight past it (#2441). Past the guard, the gesture writes its result into
+ * `camera.position` *and* `camera.target`, so a single non-finite coordinate
+ * (a BCF viewpoint restored from a file reaches the public setters
+ * unvalidated) spreads across all six on the first drag.
+ *
+ * Callers keep their own fallback: there is no single substitute distance that
+ * is right for all of them, which is also why `Camera.getDistance()` reports
+ * the pose verbatim rather than sanitizing it centrally.
+ */
+export function isUsableDistance(dist, min) {
+    return Number.isFinite(dist) && dist >= min;
+}
+/**
+ * Is `up` a usable screen-up reference — every component finite?
+ *
+ * `up` is the third vector of the pose, and it reaches the camera exactly the
+ * way `position` and `target` do: BCF stores `CameraUpVector`, `bcfToViewerCoords`
+ * only swaps axes, and `applyViewpoint` writes the result straight through
+ * (`animateToWithUp` on the animated path — which bypasses `setUp` entirely —
+ * or `setUp` on the instant one).
+ *
+ * Finiteness only, deliberately no magnitude floor. `normalize` already absorbs
+ * a zero-length or degenerate `up` by returning `{0,0,0}`, and a *short* `up` is
+ * a valid input whose direction is perfectly well defined — `MathUtils.lookAt`
+ * documents the same thing and keys its own degeneracy test on the angle rather
+ * than a length for exactly this reason. A floor here would silently drop the
+ * cursor anchor for poses that navigate correctly today.
+ *
+ * The floor `normalize` used to have was a *lower* bound, which is what left
+ * the gap: `len > 1e-10` is false for NaN (so a NaN `up` degraded safely to
+ * the zero vector) but **true for Infinity**, and scaling infinite components
+ * by `1 / Infinity` is `Infinity * 0` — NaN. Measured, not reasoned: `up`
+ * `(Infinity, 1, 0)` on a finite pose came back from one cursor-anchored zoom
+ * with position AND target `(NaN, NaN, NaN)`, in both projection modes (#2441).
+ * Both copies of `normalize` now key that floor on `Number.isFinite` too
+ * (#2479), so an unusable `up` reaches the same zero vector by either route —
+ * this predicate says so at the top of the gesture rather than relying on a
+ * helper's degradation three lines in, and it is what stops the *pose* being
+ * rewritten from a basis that carries no orientation.
+ *
+ * As with {@link isUsableDistance}, the caller keeps its own fallback and the
+ * pose is left exactly as it was found — `getUp()` still reports the malformed
+ * vector, so a restored viewpoint is not silently rewritten on its way back out.
+ */
+export function isUsableUp(up) {
+    return Number.isFinite(up.x) && Number.isFinite(up.y) && Number.isFinite(up.z);
+}
+/**
+ * Clamp an orthographic half-height, rejecting a non-finite one.
+ *
+ * `Math.max`/`Math.min` are NaN-transparent, so a clamp alone does not stop a
+ * malformed value reaching the projection matrix (#2441). Returns `null` when
+ * there is no usable size, so the caller can keep the value it already had
+ * rather than substitute an arbitrary one.
+ *
+ * The `Infinity` rejection is not theoretical: `orthoSize` is scaled in place
+ * by the orthographic zoom, so a legitimately huge but finite half-height
+ * overflows to `Infinity` after enough zoom-out notches, and
+ * `Math.max(MIN_ORTHO_SIZE, Infinity)` is `Infinity`.
+ */
+export function usableOrthoSize(size) {
+    return Number.isFinite(size) ? Math.max(MIN_ORTHO_SIZE, size) : null;
+}
+/**
+ * Are all of `values` finite?
+ *
+ * The gesture *arguments* — wheel deltas, pointer deltas, walk axes — are a
+ * different input class from the pose the gestures already guard (#2473), and
+ * they reach the same arithmetic. Measured on the pre-guard code: `orbit(NaN,
+ * 0)`, `pan(NaN, 0)`, `zoom(NaN)` and `moveFirstPerson(NaN, 0, 0)` each turned
+ * a perfectly finite pose into a non-finite one in a single call, and
+ * `orbit(Infinity, 0)` / `pan(Infinity, 0)` / `moveFirstPerson(Infinity, 0, 0)`
+ * did the same — the two do **not** behave alike everywhere, so both must be
+ * tested. (`zoom` is the exception: its delta is clamped by
+ * `Math.min(|delta| * s, MAX_ZOOM_DELTA)`, which absorbs `Infinity` but not
+ * `NaN`.)
+ */
+export function areFiniteNumbers(...values) {
+    for (const v of values) {
+        if (!Number.isFinite(v))
+            return false;
+    }
+    return true;
+}
+/**
+ * Is this a usable cursor anchor — a finite cursor position inside a viewport
+ * with a real extent?
+ *
+ * The cursor-anchored zoom divides by the canvas dimensions, so they need
+ * `> 0` and not merely "truthy". Truthiness already rejects `0` and `NaN`
+ * (both falsy) which is why a collapsed canvas never reached the division, but
+ * it accepts `Infinity` and a negative width — the latter mirrors the anchor
+ * and drifts the target the wrong way. `Number.isFinite(w) && w > 0` is the
+ * check that means what the division needs.
+ */
+export function isUsableCursorAnchor(cursorX, cursorY, viewportWidth, viewportHeight) {
+    return (areFiniteNumbers(cursorX, cursorY, viewportWidth, viewportHeight) &&
+        viewportWidth > 0 &&
+        viewportHeight > 0);
+}
+/**
+ * Is this AABB something the camera can be fitted to?
+ *
+ * Two rejections, and they are different failures:
+ *
+ *  - **Non-finite corners.** Fitting computes `center = (min + max) / 2` and
+ *    `size = max - min`, and writes both into the pose. `Math.max` picking the
+ *    largest extent is NaN-transparent, so one bad coordinate reaches
+ *    `camera.position`, `camera.target` *and* (in orthographic mode)
+ *    `orthoSize`, which `getOrthoSize()` then hands to a saved viewpoint —
+ *    persisting the damage past the session (#2461).
+ *  - **An inverted box** (`max < min` on any axis). That is the empty-AABB
+ *    sentinel every accumulator in this package starts from (`min = +Infinity,
+ *    max = -Infinity`) leaking out as if it were a real box, which is what a
+ *    mesh with no finite vertices produces. Its centre is `NaN` and its size
+ *    is negative; there is nothing to frame.
+ *
+ * A *degenerate* box (`max === min` on some or all axes — a flat wall, a
+ * single point) is explicitly **not** rejected: it is a legitimate thing to
+ * frame and `frameBounds` already centres on it.
+ *
+ * The answer to an unusable box is to reject the fit and leave the pose alone,
+ * not to clamp: there is no meaningful substitute for an infinite or inverted
+ * extent, and no previous bounds to fall back to at these entry points, which
+ * are stateless. Keeping the pose the user already had is the same policy
+ * `setAspect`, `setFOV` and `setOrthoSize` settled on (#2441/#2450).
+ */
+export function isUsableBounds(min, max) {
+    return (areFiniteNumbers(min.x, min.y, min.z, max.x, max.y, max.z) &&
+        max.x >= min.x &&
+        max.y >= min.y &&
+        max.z >= min.z);
+}
+//# sourceMappingURL=camera-guards.js.map

package/dist/camera-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-guards.js","sourceRoot":"","sources":["../src/camera-guards.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AA0B/D;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAEnC,kFAAkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,GAAW;IACxD,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,GAAG,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,UAAU,CAAC,EAAQ;IACjC,OAAO,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAG,MAAgB;IAClD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,OAAe,EACf,aAAqB,EACrB,cAAsB;IAEtB,OAAO,CACL,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,cAAc,CAAC;QACjE,aAAa,GAAG,CAAC;QACjB,cAAc,GAAG,CAAC,CACnB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,cAAc,CAAC,GAAS,EAAE,GAAS;IACjD,OAAO,CACL,gBAAgB,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC1D,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CACf,CAAC;AACJ,CAAC"}

package/dist/camera-matrices.d.ts

@@ -0,0 +1,14 @@
+import type { CameraInternalState } from './camera-state.js';
+export declare function updateCameraMatrices(state: CameraInternalState): void;
+/**
+ * Compute tight near/far for orthographic mode by projecting the scene
+ * bounding sphere onto the camera view direction.
+ *
+ * This gives optimal depth precision (minimizing z-fighting) while ensuring
+ * no geometry is clipped regardless of camera position or view angle.
+ */
+export declare function computeOrthoNearFar(state: CameraInternalState, distance: number): {
+    near: number;
+    far: number;
+};
+//# sourceMappingURL=camera-matrices.d.ts.map

package/dist/camera-matrices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-matrices.d.ts","sourceRoot":"","sources":["../src/camera-matrices.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CA4DrE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,mBAAmB,EAC1B,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAyE/B"}

package/dist/camera-matrices.js

@@ -0,0 +1,146 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * View / projection / view-projection matrix derivation.
+ *
+ * One subject: camera state in, three finite matrices out. Its failure story
+ * is the #2441 near/far backstops — a non-finite pose or `orthoSize` must not
+ * reach the projection matrix, because `MathUtils.lookAt` scrubs the *view*
+ * matrix but nothing scrubs the projection one, and a NaN there leaves the
+ * viewport dead while every other reading looks healthy.
+ *
+ * **Hot path.** `updateCameraMatrices` runs on every frame the camera moves.
+ * It takes the shared state object **by reference** and nothing else: do not
+ * destructure it into parameters (that allocates an arguments object per
+ * frame) and do not widen the parameter to a structural supertype (that
+ * invites megamorphic dispatch). The allocation profile is deliberately
+ * unchanged from the method this replaced — `lookAt`, `perspectiveReverseZ` /
+ * `orthographicReverseZ` and `multiply` each already return a fresh `Mat4`,
+ * and the ortho branch already returned a fresh `{near, far}` per frame.
+ */
+import { MathUtils } from './math.js';
+import { DEFAULT_ORTHO_SIZE, usableOrthoSize } from './camera-guards.js';
+export function updateCameraMatrices(state) {
+    const dx = state.camera.position.x - state.camera.target.x;
+    const dy = state.camera.position.y - state.camera.target.y;
+    const dz = state.camera.position.z - state.camera.target.z;
+    const rawDistance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    // A non-finite position or target — a malformed BCF viewpoint reaches the
+    // public setters unvalidated — would put NaN into near/far and from there
+    // into the projection matrix, leaving the viewport dead even though
+    // `MathUtils.lookAt` scrubs the view matrix (#2441). Fall back to a
+    // neutral distance so the projection stays finite; the camera state itself
+    // is left as the caller set it.
+    const distance = Number.isFinite(rawDistance) ? rawDistance : 1;
+    state.viewMatrix = MathUtils.lookAt(state.camera.position, state.camera.target, state.camera.up);
+    if (state.projectionMode === 'orthographic') {
+        // Orthographic: project scene bounding sphere onto view direction for tight near/far.
+        // Tight range maximizes depth precision (less z-fighting) and prevents clipping.
+        const nf = computeOrthoNearFar(state, distance);
+        state.camera.near = nf.near;
+        state.camera.far = nf.far;
+        // Backstop for the writers that never see `setOrthoSize`'s clamp: the
+        // orthographic zoom scales `orthoSize` in place and the animator
+        // interpolates it, so a NaN reaching either (from a malformed pose, or
+        // from bounds that were themselves non-finite) would land straight in
+        // the projection matrix. Same fallback shape as the distance above.
+        //
+        // Finiteness alone is not the whole backstop: `Number.isFinite(0)` is
+        // true, and a zero — or negative — half-height makes `right - left` and
+        // `top - bottom` zero, so `orthographicReverseZ` divides by zero and the
+        // matrix comes back with `Infinity` scale terms. That is the same dead
+        // viewport as a NaN, reached through a *valid-but-falsy* value rather
+        // than an exotic one. `usableOrthoSize` is the single predicate that says
+        // both things at once, and it is the same one every writer already goes
+        // through — so this backstop now enforces exactly the invariant the
+        // writers promise rather than half of it (#2441).
+        const h = usableOrthoSize(state.orthoSize) ?? DEFAULT_ORTHO_SIZE;
+        const w = h * state.camera.aspect;
+        state.projMatrix = MathUtils.orthographicReverseZ(-w, w, -h, h, state.camera.near, state.camera.far);
+    }
+    else {
+        // Perspective: adapt near/far based on camera-to-target distance
+        state.camera.near = Math.max(0.01, distance * 0.001);
+        state.camera.far = Math.max(distance * 10, 1000);
+        state.projMatrix = MathUtils.perspectiveReverseZ(state.camera.fov, state.camera.aspect, state.camera.near, state.camera.far);
+    }
+    state.viewProjMatrix = MathUtils.multiply(state.projMatrix, state.viewMatrix);
+}
+/**
+ * Compute tight near/far for orthographic mode by projecting the scene
+ * bounding sphere onto the camera view direction.
+ *
+ * This gives optimal depth precision (minimizing z-fighting) while ensuring
+ * no geometry is clipped regardless of camera position or view angle.
+ */
+export function computeOrthoNearFar(state, distance) {
+    const bounds = state.sceneBounds;
+    if (!bounds) {
+        // Fallback: generous range centered on camera
+        return { near: -Math.max(distance, 500), far: Math.max(distance, 500) };
+    }
+    // Scene bounding sphere center and radius
+    const cx = (bounds.min.x + bounds.max.x) / 2;
+    const cy = (bounds.min.y + bounds.max.y) / 2;
+    const cz = (bounds.min.z + bounds.max.z) / 2;
+    const ex = bounds.max.x - bounds.min.x;
+    const ey = bounds.max.y - bounds.min.y;
+    const ez = bounds.max.z - bounds.min.z;
+    const radius = Math.sqrt(ex * ex + ey * ey + ez * ez) / 2;
+    // View direction (camera looks from position toward target)
+    const pos = state.camera.position;
+    let vx = state.camera.target.x - pos.x;
+    let vy = state.camera.target.y - pos.y;
+    let vz = state.camera.target.z - pos.z;
+    const vLen = Math.sqrt(vx * vx + vy * vy + vz * vz);
+    // Add 10% padding for safety.
+    const pad = radius * 0.1 + 1;
+    let near;
+    let far;
+    if (Number.isFinite(vLen) && vLen > 1e-8) {
+        vx /= vLen;
+        vy /= vLen;
+        vz /= vLen;
+        // Signed distance from camera to scene center along view direction
+        const toCenter = (cx - pos.x) * vx + (cy - pos.y) * vy + (cz - pos.z) * vz;
+        // Near/far as distances from camera along view direction.
+        // The sphere spans [toCenter - radius, toCenter + radius] along view dir.
+        near = toCenter - radius - pad;
+        far = toCenter + radius + pad;
+    }
+    else {
+        // No view direction to project onto — position and target coincide, or
+        // the pose is non-finite. Skipping the normalization (which is what the
+        // bare `vLen > 1e-8` did) left `v` at its raw near-zero value, so
+        // `toCenter` collapsed to ~0 and the range came out centred on the
+        // *camera* rather than on the scene: a camera parked 1000 units away got
+        // `[-(r + pad), +(r + pad)]` and clipped the entire model away, which is
+        // a blank viewport reached through a range that is perfectly finite and
+        // therefore sails past the non-finite backstop below.
+        //
+        // There is no honest direction to substitute either: `MathUtils.lookAt`
+        // picks its own fallback basis for a degenerate pose, and any axis chosen
+        // here could disagree with the one the frame is actually drawn from.
+        // Bracket the whole bounding sphere symmetrically instead — that contains
+        // the scene whichever way `lookAt` ended up looking.
+        const span = Math.sqrt((cx - pos.x) * (cx - pos.x) +
+            (cy - pos.y) * (cy - pos.y) +
+            (cz - pos.z) * (cz - pos.z)) + radius + pad;
+        near = -span;
+        far = span;
+    }
+    // Ensure minimum range for depth precision
+    if (far - near < 1) {
+        near -= 0.5;
+        far += 0.5;
+    }
+    // Same contract as the perspective branch: a non-finite camera position or
+    // scene bound must not reach the projection matrix (#2441).
+    if (!Number.isFinite(near) || !Number.isFinite(far)) {
+        const fallback = Math.max(Number.isFinite(distance) ? distance : 0, 500);
+        return { near: -fallback, far: fallback };
+    }
+    return { near, far };
+}
+//# sourceMappingURL=camera-matrices.js.map

package/dist/camera-matrices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-matrices.js","sourceRoot":"","sources":["../src/camera-matrices.ts"],"names":[],"mappings":"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"}

package/dist/camera-preset-view.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Preset views: the ViewCube's six named directions, plus the admission check
+ * that decides whether a preset may be applied at all.
+ *
+ * Split out of `camera-framing.ts`, which owns the *free* framing pickers
+ * (point / bounds / extents — "put the camera on this thing, keeping the
+ * current direction"). Presets are the opposite subject: the direction is
+ * dictated by the named face and the caller's rotation cycle, and the box is
+ * whatever the caller supplied or whatever the current pose implies. The two
+ * share only box arithmetic, which is why this module imports `centerOf` /
+ * `maxExtentOf` rather than owning a second copy.
+ *
+ * Pure by construction, exactly as `camera-framing.ts` is: everything here
+ * reads `CameraInternalState` and returns a target, nothing writes to it or
+ * touches the tween. That is what keeps both modules free of a cycle back into
+ * `camera-animation.ts`, which is the one that applies the results.
+ *
+ * **Guard placement.** `resolvePresetBounds` validates the box exactly once,
+ * here, and a rejection is `null`. Callers null-check and do nothing else: a
+ * second, defensive copy of the same guard in the caller would mean neither
+ * copy is load-bearing on its own, and the mutation test that pins this guard
+ * would go quiet while still looking green.
+ */
+import type { Vec3 } from './types.js';
+import type { CameraInternalState } from './camera-state.js';
+import { type FramingBounds } from './camera-framing.js';
+/**
+ * Get current bounds estimate (simplified - in production would use scene bounds).
+ */
+export declare function estimateBoundsFromPose(state: CameraInternalState): FramingBounds;
+/**
+ * Resolve the box a preset view should fit, from the caller's bounds or the
+ * current pose, and reject it if it is not usable.
+ *
+ * This is the whole admission decision for `setPresetView`, deliberately kept
+ * ahead of the rotation-cycling counter: a rejected preset must not advance
+ * the cycle, and the caller can only honour that if the verdict arrives before
+ * it mutates anything.
+ */
+export declare function resolvePresetBounds(state: CameraInternalState, bounds?: FramingBounds): FramingBounds | null;
+/**
+ * Pose for a preset view (Y-up coordinate system).
+ *
+ * `bounds` must already have passed {@link resolvePresetBounds}; `rotation` is
+ * the caller's 0-3 cycle position, which is why this takes it rather than
+ * owning it — the counter belongs to the animator, which is what remembers
+ * that the same face was clicked twice.
+ *
+ * @param buildingRotation Optional building rotation in radians (from IfcSite placement)
+ */
+export declare function presetViewTarget(state: CameraInternalState, view: 'top' | 'bottom' | 'front' | 'back' | 'left' | 'right', bounds: FramingBounds, rotation: number, buildingRotation?: number): {
+    position: Vec3;
+    target: Vec3;
+    up: Vec3;
+};
+//# sourceMappingURL=camera-preset-view.d.ts.map

package/dist/camera-preset-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-preset-view.d.ts","sourceRoot":"","sources":["../src/camera-preset-view.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,OAAO,EAAyC,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEhG;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,mBAAmB,GAAG,aAAa,CAsBhF;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,mBAAmB,EAC1B,MAAM,CAAC,EAAE,aAAa,GACrB,aAAa,GAAG,IAAI,CAYtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,mBAAmB,EAC1B,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAC5D,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,MAAM,GACxB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,CA0H5C"}