@ifc-lite/renderer 1.43.0 → 1.44.0

package/dist/camera-first-person.js

@@ -0,0 +1,119 @@
+/* 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/. */
+import { areFiniteNumbers, isUsableDistance } from './camera-guards.js';
+export class FirstPersonNavigator {
+    state;
+    updateMatrices;
+    isFirstPersonMode = false;
+    walkVelocity = { x: 0, z: 0 };
+    constructor(state, updateMatrices) {
+        this.state = state;
+        this.updateMatrices = updateMatrices;
+    }
+    /**
+     * Set first-person mode.
+     *
+     * Load-bearing, not bookkeeping: {@link move} refuses to walk while this is
+     * off. The flag was write-only before the extraction — nothing ever read it,
+     * so `moveFirstPerson` moved the camera whether or not walk mode had been
+     * entered, and the only thing keeping that from being visible was the
+     * viewer's *second*, independent check on `activeTool === 'walk'`. Two
+     * unrelated gates for one decision means neither is load-bearing on its own,
+     * and the renderer is published: an embedder driving `moveFirstPerson` from
+     * its own key handler has only this one.
+     *
+     * Disabling also drops the accumulated walk velocity. It is smoothed in
+     * place (`+= (target - current) * 0.15`), so a leftover would be spent on
+     * the first frame after walk mode is re-entered — a visible lurch in
+     * whatever direction the user happened to be walking when they left.
+     */
+    setEnabled(enabled) {
+        this.isFirstPersonMode = enabled;
+        if (!enabled)
+            this.stop();
+    }
+    /**
+     * Drop the accumulated walk velocity, keeping the mode as it is.
+     *
+     * Called on model reset. The mode itself is deliberately *not* cleared:
+     * it mirrors the viewer's active tool, which a model load does not change,
+     * and clearing it here would leave walk mode silently dead until the user
+     * toggled the tool off and back on again.
+     */
+    stop() {
+        this.walkVelocity.x = 0;
+        this.walkVelocity.z = 0;
+    }
+    /**
+     * Walk on the horizontal XZ plane (Y-up coordinate system).
+     * Forward/backward moves in the camera's horizontal facing direction.
+     * Left/right strafes perpendicular. Y position stays fixed (walking on ground).
+     * Speed scales with scene size. Movement uses smooth acceleration to avoid
+     * abrupt jumps — velocity ramps up over successive frames.
+     */
+    move(forward, right, _up) {
+        // Mode gate, ahead of every other guard: walking is only a thing that
+        // exists while walk mode is on. See {@link setEnabled}.
+        if (!this.isFirstPersonMode)
+            return;
+        // Argument-side guard (#2473). `walkVelocity` is accumulated in place, so
+        // a non-finite axis latches first-person movement dead for the session
+        // exactly the way a non-finite pose did (#2441) — and it does not need an
+        // exotic value: both `moveFirstPerson(NaN, 0, 0)` and
+        // `moveFirstPerson(Infinity, 0, 0)` came back with a non-finite position
+        // on a finite pose. `_up` is unused, so it is deliberately not tested.
+        if (!areFiniteNumbers(forward, right))
+            return;
+        // Camera forward direction projected onto XZ plane
+        const dir = {
+            x: this.state.camera.target.x - this.state.camera.position.x,
+            z: this.state.camera.target.z - this.state.camera.position.z,
+        };
+        const horizLen = Math.sqrt(dir.x * dir.x + dir.z * dir.z);
+        // Finiteness, not just magnitude: `NaN < 1e-10` is false, so a malformed
+        // pose fell through here and `dir.x / horizLen` came back NaN. That does
+        // not merely produce one bad step — `walkVelocity` is accumulated in place
+        // (`+= (target - current) * 0.15`), so a single NaN frame latches it and
+        // first-person movement stays dead for the rest of the session even after
+        // the pose is corrected (#2441).
+        if (!isUsableDistance(horizLen, 1e-10))
+            return;
+        // Normalized horizontal forward and right vectors
+        const fwdX = dir.x / horizLen;
+        const fwdZ = dir.z / horizLen;
+        const rightX = -fwdZ;
+        const rightZ = fwdX;
+        // Target velocity from input (forward/right can be -2..2 with sprint)
+        const targetVelX = fwdX * forward + rightX * right;
+        const targetVelZ = fwdZ * forward + rightZ * right;
+        // Smooth acceleration: lerp current walk velocity toward target
+        this.walkVelocity.x += (targetVelX - this.walkVelocity.x) * 0.15;
+        this.walkVelocity.z += (targetVelZ - this.walkVelocity.z) * 0.15;
+        // Speed proportional to scene size (use camera-target distance as proxy)
+        const camDir = {
+            x: this.state.camera.position.x - this.state.camera.target.x,
+            y: this.state.camera.position.y - this.state.camera.target.y,
+            z: this.state.camera.position.z - this.state.camera.target.z,
+        };
+        const distance = Math.sqrt(camDir.x * camDir.x + camDir.y * camDir.y + camDir.z * camDir.z);
+        // The horizontal guard above does not cover this one: `camDir` includes Y,
+        // so a pose whose *only* bad coordinate is vertical reaches here with a
+        // finite `horizLen` and a NaN `distance`. `Math.max` is NaN-transparent —
+        // `Math.max(0.02, NaN)` is `NaN`, not the floor — so the clamp would
+        // forward it into the offsets written back to position and target.
+        if (!isUsableDistance(distance, 0))
+            return;
+        const speed = Math.max(0.02, distance * 0.004);
+        // Apply smoothed velocity
+        const offsetX = this.walkVelocity.x * speed;
+        const offsetZ = this.walkVelocity.z * speed;
+        // Move both position and target by the same offset (preserves view direction)
+        this.state.camera.position.x += offsetX;
+        this.state.camera.position.z += offsetZ;
+        this.state.camera.target.x += offsetX;
+        this.state.camera.target.z += offsetZ;
+        this.updateMatrices();
+    }
+}
+//# sourceMappingURL=camera-first-person.js.map

package/dist/camera-first-person.js.map

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

package/dist/camera-framing.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Framing: "put the camera on this thing, keeping the direction it already
+ * has". Given the current camera state and a point or an AABB, work out the
+ * pose to end up in.
+ *
+ * The ViewCube's *preset* directions are the neighbouring subject and live in
+ * `camera-preset-view.ts`: there the direction is dictated by a named face and
+ * a rotation cycle rather than inherited from the pose, and the box has to pass
+ * its own admission check first. They share only the box arithmetic below,
+ * which is why `centerOf` / `maxExtentOf` are exported.
+ *
+ * Pure by construction — every function here reads `CameraInternalState` and
+ * returns a target, and none of them writes to it or touches the tween. That
+ * is what keeps this module free of a cycle back into `camera-animation.ts`,
+ * which is the one that applies the results. Same shape as
+ * `camera-fit-policy.ts`, which is already pure-picker + facade-applier.
+ *
+ * Its failure story is not the tween's. The tween latches a non-finite
+ * *gesture delta* into a velocity that never decays (#2441/#2473); framing
+ * takes a non-finite *box* — geometry-derived, and every AABB accumulator in
+ * this package hands out an inverted `+Inf/-Inf` sentinel for a mesh with no
+ * finite vertices — and writes it into position, target AND `orthoSize`, which
+ * `getOrthoSize()` then persists into a saved viewpoint (#2461).
+ *
+ * **Guard placement.** Each input is validated 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 tests that pin these guards would
+ * go quiet while still looking green.
+ */
+import type { Vec3 } from './types.js';
+import type { CameraInternalState } from './camera-state.js';
+/** A pose to animate to. `orthoSize` is undefined when the fit should not touch zoom. */
+export interface FramingTarget {
+    position: Vec3;
+    target: Vec3;
+    orthoSize?: number;
+}
+/** As {@link FramingTarget}, plus the fit distance `zoomExtent` reports onward. */
+export interface ZoomExtentTarget extends FramingTarget {
+    fitDistance: number;
+}
+/** An axis-aligned box. */
+export interface FramingBounds {
+    min: Vec3;
+    max: Vec3;
+}
+/** Centre of a box. */
+export declare function centerOf(min: Vec3, max: Vec3): Vec3;
+/** Largest edge length of a box. */
+export declare function maxExtentOf(min: Vec3, max: Vec3): number;
+/**
+ * Distance at which a box of `maxSize` fits the perspective frustum, with
+ * `padding` slack. Shared with `camera-preset-view.ts`, which fits the same
+ * way from a dictated direction.
+ *
+ * Fits **both** screen axes. The vertical half-angle is `fov / 2`; the
+ * horizontal one is `atan(tan(fov / 2) * aspect)`, so on a portrait viewport
+ * (`aspect < 1`) the horizontal field is the *narrower* of the two and a
+ * distance derived from the vertical field alone leaves the box overflowing
+ * left and right — the fit silently clips the very thing it was asked to
+ * frame. Landscape is unaffected: for `aspect >= 1` the vertical field is
+ * already the binding one and this returns the vertical distance exactly,
+ * bit for bit.
+ *
+ * `orthoSizeFor` above has divided by `aspect` for the same reason since it
+ * was written; this is the perspective half of the same rule, which had been
+ * missing (the three fit-distance formulas in this package all predate it).
+ */
+export declare function fitDistanceFor(state: CameraInternalState, maxSize: number, padding: number): number;
+/**
+ * Frame/center view on a point (keeps current distance and direction).
+ * Standard CAD "Frame Selection" behavior.
+ */
+export declare function framePointTarget(state: CameraInternalState, point: Vec3): FramingTarget | null;
+/**
+ * Frame selection - zoom to fit bounds while keeping current view direction.
+ * This is what "Frame Selection" should do - zoom to fill screen.
+ */
+export declare function frameBoundsTarget(state: CameraInternalState, min: Vec3, max: Vec3): FramingTarget | null;
+/**
+ * Zoom to extents: same fit, wider padding, and the current view direction is
+ * taken from the pose rather than the view matrix.
+ */
+export declare function zoomExtentTarget(state: CameraInternalState, min: Vec3, max: Vec3): ZoomExtentTarget | null;
+//# sourceMappingURL=camera-framing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"camera-framing.d.ts","sourceRoot":"","sources":["../src/camera-framing.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,yFAAyF;AACzF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,IAAI,CAAC;IACf,MAAM,EAAE,IAAI,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,2BAA2B;AAC3B,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,IAAI,CAAC;IACV,GAAG,EAAE,IAAI,CAAC;CACX;AAED,uBAAuB;AACvB,wBAAgB,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,IAAI,CAMnD;AAED,oCAAoC;AACpC,wBAAgB,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAExD;AAYD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQnG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,IAAI,GAAG,aAAa,GAAG,IAAI,CAuB9F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,aAAa,GAAG,IAAI,CA4ExG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,gBAAgB,GAAG,IAAI,CAoE1G"}

package/dist/camera-framing.js

@@ -0,0 +1,230 @@
+/* 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/. */
+import { areFiniteNumbers, isUsableBounds, isUsableDistance } from './camera-guards.js';
+/** Centre of a box. */
+export function centerOf(min, max) {
+    return {
+        x: (min.x + max.x) / 2,
+        y: (min.y + max.y) / 2,
+        z: (min.z + max.z) / 2,
+    };
+}
+/** Largest edge length of a box. */
+export function maxExtentOf(min, max) {
+    return Math.max(max.x - min.x, max.y - min.y, max.z - min.z);
+}
+/**
+ * Orthographic half-height that shows a box of `maxSize` with `padding` slack,
+ * or `undefined` in perspective mode where `orthoSize` is not in play.
+ */
+function orthoSizeFor(state, maxSize, padding) {
+    if (state.projectionMode !== 'orthographic')
+        return undefined;
+    const aspect = state.camera.aspect || 1;
+    return Math.max(0.01, maxSize / 2, maxSize / 2 / aspect) * padding;
+}
+/**
+ * Distance at which a box of `maxSize` fits the perspective frustum, with
+ * `padding` slack. Shared with `camera-preset-view.ts`, which fits the same
+ * way from a dictated direction.
+ *
+ * Fits **both** screen axes. The vertical half-angle is `fov / 2`; the
+ * horizontal one is `atan(tan(fov / 2) * aspect)`, so on a portrait viewport
+ * (`aspect < 1`) the horizontal field is the *narrower* of the two and a
+ * distance derived from the vertical field alone leaves the box overflowing
+ * left and right — the fit silently clips the very thing it was asked to
+ * frame. Landscape is unaffected: for `aspect >= 1` the vertical field is
+ * already the binding one and this returns the vertical distance exactly,
+ * bit for bit.
+ *
+ * `orthoSizeFor` above has divided by `aspect` for the same reason since it
+ * was written; this is the perspective half of the same rule, which had been
+ * missing (the three fit-distance formulas in this package all predate it).
+ */
+export function fitDistanceFor(state, maxSize, padding) {
+    const fovFactor = Math.tan(state.camera.fov / 2);
+    const vertical = (maxSize / 2) / fovFactor * padding;
+    const aspect = state.camera.aspect;
+    // `setAspect` is the only writer and already rejects a non-positive or
+    // non-finite ratio, so this only ever narrows the *portrait* case.
+    if (!Number.isFinite(aspect) || aspect <= 0 || aspect >= 1)
+        return vertical;
+    return vertical / aspect;
+}
+/**
+ * Frame/center view on a point (keeps current distance and direction).
+ * Standard CAD "Frame Selection" behavior.
+ */
+export function framePointTarget(state, point) {
+    // The point is added to the current offset and animated into both
+    // `position` and `target`, so a non-finite one destroys the pose. It is
+    // externally derived: `zoomToTopic` frames a BCF marker position, which is
+    // computed from a file-supplied viewpoint direction (#2461/#2466).
+    if (!areFiniteNumbers(point.x, point.y, point.z))
+        return null;
+    // Keep current viewing direction and distance
+    const dir = {
+        x: state.camera.position.x - state.camera.target.x,
+        y: state.camera.position.y - state.camera.target.y,
+        z: state.camera.position.z - state.camera.target.z,
+    };
+    // New position: point + current offset
+    return {
+        position: {
+            x: point.x + dir.x,
+            y: point.y + dir.y,
+            z: point.z + dir.z,
+        },
+        target: point,
+    };
+}
+/**
+ * Frame selection - zoom to fit bounds while keeping current view direction.
+ * This is what "Frame Selection" should do - zoom to fill screen.
+ */
+export function frameBoundsTarget(state, min, max) {
+    // Bounds are the upstream input #2450 stopped short of (#2461). They are
+    // not caller-authored constants: they come from geometry, and every AABB
+    // accumulator in this package starts from `min = +Infinity, max =
+    // -Infinity` and only narrows on a comparison — which is false for a
+    // non-finite vertex — so a mesh with no finite vertices hands out that
+    // inverted sentinel as if it were a real box. `Math.max` picking the
+    // largest extent is NaN-transparent, so it reaches `position`, `target`
+    // AND `orthoSize`, and `getOrthoSize()` is what a saved viewpoint persists.
+    if (!isUsableBounds(min, max))
+        return null;
+    const center = centerOf(min, max);
+    const maxSize = maxExtentOf(min, max);
+    if (maxSize < 1e-6) {
+        // Very small or zero size - just center on it
+        return framePointTarget(state, center);
+    }
+    // Calculate required distance based on FOV to fit bounds
+    const distance = fitDistanceFor(state, maxSize, 1.2); // 1.2x padding for nice framing
+    // Get current viewing direction from view matrix (more reliable than position-target)
+    // View matrix forward is -Z axis in view space
+    const viewMatrix = state.viewMatrix.m;
+    // Extract forward direction from view matrix (negative Z column, normalized)
+    let dir = {
+        x: -viewMatrix[8], // -m[2][0] (forward X)
+        y: -viewMatrix[9], // -m[2][1] (forward Y)
+        z: -viewMatrix[10], // -m[2][2] (forward Z)
+    };
+    const dirLen = Math.sqrt(dir.x * dir.x + dir.y * dir.y + dir.z * dir.z);
+    // Normalize direction
+    if (dirLen > 1e-6) {
+        dir.x /= dirLen;
+        dir.y /= dirLen;
+        dir.z /= dirLen;
+    }
+    else {
+        // Fallback: use position-target if view matrix is invalid
+        dir = {
+            x: state.camera.position.x - state.camera.target.x,
+            y: state.camera.position.y - state.camera.target.y,
+            z: state.camera.position.z - state.camera.target.z,
+        };
+        const fallbackLen = Math.sqrt(dir.x * dir.x + dir.y * dir.y + dir.z * dir.z);
+        // Finiteness, not just magnitude — see `zoomExtentTarget`. `dirLen` above
+        // is safe (`MathUtils.lookAt` guarantees a finite view matrix), but this
+        // fallback reads the raw pose, where an overflowed coordinate is reachable.
+        if (isUsableDistance(fallbackLen, 1e-6)) {
+            dir.x /= fallbackLen;
+            dir.y /= fallbackLen;
+            dir.z /= fallbackLen;
+        }
+        else {
+            // Last resort: southeast isometric
+            dir.x = 0.6;
+            dir.y = 0.5;
+            dir.z = 0.6;
+            const len = Math.sqrt(dir.x * dir.x + dir.y * dir.y + dir.z * dir.z);
+            dir.x /= len;
+            dir.y /= len;
+            dir.z /= len;
+        }
+    }
+    return {
+        // New position: center + direction * distance
+        position: {
+            x: center.x + dir.x * distance,
+            y: center.y + dir.y * distance,
+            z: center.z + dir.z * distance,
+        },
+        target: center,
+        // Calculate orthoSize for orthographic mode so zoom level resets properly
+        orthoSize: orthoSizeFor(state, maxSize, 1.2),
+    };
+}
+/**
+ * Zoom to extents: same fit, wider padding, and the current view direction is
+ * taken from the pose rather than the view matrix.
+ */
+export function zoomExtentTarget(state, min, max) {
+    // Same input class and same reasoning as `frameBoundsTarget` (#2461).
+    if (!isUsableBounds(min, max))
+        return null;
+    const center = centerOf(min, max);
+    const maxSize = maxExtentOf(min, max);
+    // Keep current viewing direction
+    const dir = {
+        x: state.camera.position.x - state.camera.target.x,
+        y: state.camera.position.y - state.camera.target.y,
+        z: state.camera.position.z - state.camera.target.z,
+    };
+    const currentDistance = Math.sqrt(dir.x * dir.x + dir.y * dir.y + dir.z * dir.z);
+    // The degenerate box `frameBoundsTarget` has always special-cased and this
+    // one did not. `isUsableBounds` deliberately admits `max === min` (a flat
+    // wall, a single picked point, a one-element model), and for such a box the
+    // fit distance below is *zero* — so `position` is written equal to `target`,
+    // a pose that carries no view direction at all and that `MathUtils.lookAt`
+    // then has to substitute a whole basis for. Centre on the point at the
+    // distance the camera already has, exactly as `frameBounds` does, and report
+    // that distance rather than zero.
+    //
+    // Only when the current offset is usable. When it is not, the pose already
+    // has position === target (or is non-finite), so there is no offset to keep
+    // and nothing is gained by keeping it; fall through to the isometric
+    // fallback below, which is what this path did before.
+    if (maxSize < 1e-6 && isUsableDistance(currentDistance, 1e-10)) {
+        const framed = framePointTarget(state, center);
+        if (framed)
+            return { ...framed, fitDistance: currentDistance };
+    }
+    // Calculate required distance based on FOV
+    const distance = fitDistanceFor(state, maxSize, 1.5); // 1.5x for padding
+    // Normalize direction. Finiteness, not just magnitude: `len > 1e-10` is
+    // *true* for Infinity, and `Infinity / Infinity` is NaN, so a pose whose
+    // position has overflowed walks past a bare floor and writes a NaN position
+    // from a perfectly usable box (#2441).
+    if (isUsableDistance(currentDistance, 1e-10)) {
+        dir.x /= currentDistance;
+        dir.y /= currentDistance;
+        dir.z /= currentDistance;
+    }
+    else {
+        // Fallback direction
+        dir.x = 0.6;
+        dir.y = 0.5;
+        dir.z = 0.6;
+        const len = Math.sqrt(dir.x * dir.x + dir.y * dir.y + dir.z * dir.z);
+        dir.x /= len;
+        dir.y /= len;
+        dir.z /= len;
+    }
+    return {
+        // New position: center + direction * distance
+        position: {
+            x: center.x + dir.x * distance,
+            y: center.y + dir.y * distance,
+            z: center.z + dir.z * distance,
+        },
+        target: center,
+        // Calculate orthoSize for orthographic mode so zoom level resets properly
+        orthoSize: orthoSizeFor(state, maxSize, 1.5),
+        // The caller hands this to `CameraProjection.updateNearFarPlanes`.
+        fitDistance: distance,
+    };
+}
+//# sourceMappingURL=camera-framing.js.map

package/dist/camera-framing.js.map

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

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