@flighthq/camera 0.3.0 → 0.3.1-next.1050.9114695

package/dist/camera.d.ts

@@ -4,6 +4,7 @@ export declare function getCamera3DInverseViewProjectionMatrix4(out: Matrix4Like
 export declare function getCamera3DViewProjectionMatrix4(out: Matrix4Like, camera: Readonly<Camera3D>, aspect: number): void;
 export declare function setCamera3DAspect(camera: Camera3D, aspect: number): void;
 export declare function setCamera3DJitter(camera: Camera3D, x: number, y: number): void;
+export declare function setCamera3DViewGuard(guard: ((camera: Readonly<Camera3D>) => void) | null): void;
 export declare function setCamera3DViewMatrix4FromLookAt(camera: Camera3D, eye: Readonly<Vector3Like>, target: Readonly<Vector3Like>, up: Readonly<Vector3Like>): void;
 export declare function setCamera3DViewMatrix4FromMatrix4(camera: Camera3D, view: Readonly<Matrix4Like>): void;
 export declare function updateCamera3DInverseViewProjection(camera: Readonly<Camera3D>, aspect: number): boolean;

package/dist/camera.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../src/camera.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAUpG,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,QAAQ,CASxE;AASD,wBAAgB,uCAAuC,CACrD,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAC1B,MAAM,EAAE,MAAM,GACb,OAAO,CAGT;AAQD,wBAAgB,gCAAgC,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAInH;AAQD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAOxE;AAID,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAG9E;AAOD,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,QAAQ,EAChB,GAAG,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC1B,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC7B,EAAE,EAAE,QAAQ,CAAC,WAAW,CAAC,GACxB,IAAI,CAEN;AAID,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,IAAI,CAErG;AAMD,wBAAgB,mCAAmC,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAIvG"}
+{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../src/camera.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAUpG,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,QAAQ,CASxE;AASD,wBAAgB,uCAAuC,CACrD,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAC1B,MAAM,EAAE,MAAM,GACb,OAAO,CAGT;AAQD,wBAAgB,gCAAgC,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAInH;AAQD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAOxE;AAID,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAG9E;AAMD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAE/F;AAOD,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,QAAQ,EAChB,GAAG,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC1B,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC7B,EAAE,EAAE,QAAQ,CAAC,WAAW,CAAC,GACxB,IAAI,CAEN;AAeD,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,IAAI,CAGrG;AAMD,wBAAgB,mCAAmC,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAIvG"}

package/dist/camera.js

@@ -59,6 +59,13 @@ export function setCamera3DJitter(camera, x, y) {
     camera.jitter.x = x;
     camera.jitter.y = y;
 }
+// The seam the guard layer installs into; `null` keeps this module free of message text and of any
+// dependency on @flighthq/log. Installed here rather than at each consumer because the precondition is a
+// fact about the CAMERA — reporting it once where the matrix enters beats one warning per consumer that
+// happens to rely on it.
+export function setCamera3DViewGuard(guard) {
+    camera3DViewGuard = guard;
+}
 // Builds the camera's world->view matrix in place from an eye position, a look-at target, and an
 // up vector (right-handed look-at). This is the common path for positioning a camera without an
 // explicit world transform.
@@ -69,8 +76,20 @@ export function setCamera3DViewMatrix4FromLookAt(camera, eye, target, up) {
 }
 // Copies a precomputed world->view matrix into the camera in place. Use this when the view matrix
 // is derived elsewhere (for example, the inverse of a scene node's world transform).
+//
+// ★ PRECONDITION: `view` must be ORTHONORMAL — a rigid placement, position and orientation only. A view
+// matrix is the inverse of a camera's world placement, and a placement does not scale; this is what the
+// term means everywhere (Unity `worldToCameraMatrix`, Unreal's view matrix), not a Flight restriction.
+// Reflections are FINE: an improper orthogonal matrix (det = -1, as a water or mirror camera produces)
+// is still orthogonal, so Rᵀ is still R⁻¹ and every consumer that relies on the transpose stays exact.
+// What is excluded is a SCALED view, which has no coherent meaning as a placement inverse.
+//
+// The precondition is not enforced here — checking it on every assignment would cost every correct
+// caller for the benefit of an incorrect one. `explainCamera3DView` reports it on demand, and
+// `enableCameraGuards` warns on it; consumers such as `getCamera3DPosition` simply rely on it.
 export function setCamera3DViewMatrix4FromMatrix4(camera, view) {
     camera.view.m.set(view.m);
+    camera3DViewGuard?.(camera);
 }
 // Refreshes the camera's required inverse-view-projection cache for the supplied viewport aspect.
 // Returns true on success or false when projection×view is non-invertible, leaving the prior valid
@@ -100,4 +119,5 @@ function applyCamera3DProjectionJitter(out, x, y) {
 const __scratchInverse = createMatrix4();
 const __scratchProjection = createMatrix4();
 const __scratchViewProjection = createMatrix4();
+let camera3DViewGuard = null;
 //# sourceMappingURL=camera.js.map

package/dist/camera.js.map

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

package/dist/contract.d.ts

@@ -3,6 +3,8 @@ export * from './camera';
 export * from './camera2d';
 export * from './culling';
 export * from './depth';
+export * from './enableCameraGuards';
+export * from './explainCamera3DView';
 export * from './frustumCorners';
 export * from './intersection';
 export * from './parallax';

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,QAAQ,CAAC"}

package/dist/contract.js

@@ -3,6 +3,8 @@ export * from './camera';
 export * from './camera2d';
 export * from './culling';
 export * from './depth';
+export * from './enableCameraGuards';
+export * from './explainCamera3DView';
 export * from './frustumCorners';
 export * from './intersection';
 export * from './parallax';

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,QAAQ,CAAC"}

package/dist/enableCameraGuards.d.ts

@@ -0,0 +1,4 @@
+export declare function areCameraGuardsEnabled(): boolean;
+export declare function disableCameraGuards(): void;
+export declare function enableCameraGuards(): void;
+//# sourceMappingURL=enableCameraGuards.d.ts.map

package/dist/enableCameraGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableCameraGuards.d.ts","sourceRoot":"","sources":["../src/enableCameraGuards.ts"],"names":[],"mappings":"AAQA,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAI1C;AAKD,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC"}

package/dist/enableCameraGuards.js

@@ -0,0 +1,45 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setCamera3DViewGuard } from './camera';
+import { explainCamera3DView } from './explainCamera3DView';
+import { setCamera2DVisibleBoundsGuard } from './visibleBounds';
+export function areCameraGuardsEnabled() {
+    return cameraGuardsEnabled;
+}
+export function disableCameraGuards() {
+    setCamera3DViewGuard(null);
+    setCamera2DVisibleBoundsGuard(null);
+    cameraGuardsEnabled = false;
+}
+// Installs opt-in diagnostics for camera inputs that leave a computation with no answer. The core
+// modules stay message-free, so an application that omits this one sheds both the text and
+// @flighthq/log.
+export function enableCameraGuards() {
+    setCamera3DViewGuard(warnOnNonOrthonormalCamera3DView);
+    setCamera2DVisibleBoundsGuard(warnOnDegenerateCamera2DVisibleBounds);
+    cameraGuardsEnabled = true;
+}
+// The unbounded rectangle is a deliberate fail-toward-drawing, not a silent success: nothing is culled,
+// so the frame is correct but pays for every object. That is a performance cliff with no visible
+// symptom, which is exactly the case a guard exists to name.
+function warnOnDegenerateCamera2DVisibleBounds(camera) {
+    logOnce(`camera:degenerate-visible-bounds:${camera.zoom}`, LogLevel.Warn, {
+        message: 'getCamera2DVisibleBounds: the view matrix has no inverse, so the visible rectangle is unbounded and nothing is culled — a zoom of 0 is the usual cause; set a non-zero zoom.',
+        zoom: camera.zoom,
+    });
+}
+// Names the CAUSE, not any one consequence: several consumers rely on the orthonormality precondition
+// and warning once per consumer would be noise. A caller that wants to connect this to a specific wrong
+// answer has `explainCamera3DView` for the numbers.
+function warnOnNonOrthonormalCamera3DView(camera) {
+    const explanation = explainCamera3DView(camera);
+    if (explanation.isOrthonormal)
+        return;
+    logOnce('camera:non-orthonormal-view', LogLevel.Warn, {
+        message: 'setCamera3DViewMatrix4FromMatrix4: the view matrix is not orthonormal, which its consumers rely on — a scaled matrix is the usual cause. Reflections are fine; scale is not. Call explainCamera3DView(camera) for the measured deviations.',
+        scaleDeviation: explanation.scaleDeviation,
+        shearDeviation: explanation.shearDeviation,
+    });
+}
+let cameraGuardsEnabled = false;
+//# sourceMappingURL=enableCameraGuards.js.map

package/dist/enableCameraGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableCameraGuards.js","sourceRoot":"","sources":["../src/enableCameraGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC;AAEhE,MAAM,UAAU,sBAAsB;IACpC,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,oBAAoB,CAAC,IAAI,CAAC,CAAC;IAC3B,6BAA6B,CAAC,IAAI,CAAC,CAAC;IACpC,mBAAmB,GAAG,KAAK,CAAC;AAC9B,CAAC;AAED,kGAAkG;AAClG,2FAA2F;AAC3F,iBAAiB;AACjB,MAAM,UAAU,kBAAkB;IAChC,oBAAoB,CAAC,gCAAgC,CAAC,CAAC;IACvD,6BAA6B,CAAC,qCAAqC,CAAC,CAAC;IACrE,mBAAmB,GAAG,IAAI,CAAC;AAC7B,CAAC;AAED,wGAAwG;AACxG,iGAAiG;AACjG,6DAA6D;AAC7D,SAAS,qCAAqC,CAAC,MAA0B;IACvE,OAAO,CAAC,oCAAoC,MAAM,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC,IAAI,EAAE;QACxE,OAAO,EACL,8KAA8K;QAChL,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAC,CAAC;AACL,CAAC;AAED,sGAAsG;AACtG,wGAAwG;AACxG,oDAAoD;AACpD,SAAS,gCAAgC,CAAC,MAA0B;IAClE,MAAM,WAAW,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,WAAW,CAAC,aAAa;QAAE,OAAO;IACtC,OAAO,CAAC,6BAA6B,EAAE,QAAQ,CAAC,IAAI,EAAE;QACpD,OAAO,EACL,4OAA4O;QAC9O,cAAc,EAAE,WAAW,CAAC,cAAc;QAC1C,cAAc,EAAE,WAAW,CAAC,cAAc;KAC3C,CAAC,CAAC;AACL,CAAC;AAED,IAAI,mBAAmB,GAAG,KAAK,CAAC"}

package/dist/explainCamera3DView.d.ts

@@ -0,0 +1,3 @@
+import type { Camera3D, Camera3DViewExplanation } from '@flighthq/types/contract';
+export declare function explainCamera3DView(camera: Readonly<Camera3D>): Camera3DViewExplanation;
+//# sourceMappingURL=explainCamera3DView.d.ts.map

package/dist/explainCamera3DView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainCamera3DView.d.ts","sourceRoot":"","sources":["../src/explainCamera3DView.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAYlF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,uBAAuB,CA6BvF"}

package/dist/explainCamera3DView.js

@@ -0,0 +1,35 @@
+// Reports whether a camera's view matrix satisfies the orthonormality precondition its consumers rely
+// on, as PLAIN DATA rather than a verdict. Callers get the measured deviations and decide for
+// themselves what that means for the answer they got — `getCamera3DPosition`, for instance, is exact
+// for any orthogonal basis and merely wrong for a scaled one, which is a judgement about their use, not
+// about the matrix.
+//
+// Reflections pass: `determinant` is reported so a caller can tell a mirror camera (-1) from a rigid one
+// (+1), but neither is a violation — an improper orthogonal matrix still satisfies Rᵀ = R⁻¹.
+//
+// Shakeable: nothing in the render path calls this, so an application that never asks sheds it entirely.
+export function explainCamera3DView(camera) {
+    const m = camera.view.m;
+    const x = { x: m[0], y: m[1], z: m[2] };
+    const y = { x: m[4], y: m[5], z: m[6] };
+    const z = { x: m[8], y: m[9], z: m[10] };
+    const lengthX = Math.hypot(x.x, x.y, x.z);
+    const lengthY = Math.hypot(y.x, y.y, y.z);
+    const lengthZ = Math.hypot(z.x, z.y, z.z);
+    const determinant = m[0] * (m[5] * m[10] - m[6] * m[9]) - m[4] * (m[1] * m[10] - m[2] * m[9]) + m[8] * (m[1] * m[6] - m[2] * m[5]);
+    // Largest absolute deviation from unit length across the three basis vectors, and from zero across
+    // the three pairwise dots. One number each, so a caller can threshold without redoing the algebra.
+    const scaleDeviation = Math.max(Math.abs(lengthX - 1), Math.abs(lengthY - 1), Math.abs(lengthZ - 1));
+    const shearDeviation = Math.max(Math.abs(x.x * y.x + x.y * y.y + x.z * y.z), Math.abs(x.x * z.x + x.y * z.y + x.z * z.z), Math.abs(y.x * z.x + y.y * z.y + y.z * z.z));
+    return {
+        determinant,
+        isOrthonormal: scaleDeviation <= ORTHONORMAL_TOLERANCE && shearDeviation <= ORTHONORMAL_TOLERANCE,
+        isReflection: determinant < 0,
+        scaleDeviation,
+        shearDeviation,
+    };
+}
+// Loose enough to pass a matrix that has been through a decompose/recompose round trip in float32,
+// tight enough that a deliberate scale of even 1% is reported.
+const ORTHONORMAL_TOLERANCE = 1e-3;
+//# sourceMappingURL=explainCamera3DView.js.map

package/dist/explainCamera3DView.js.map

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

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { configureDirectionalShadowCamera3D, configureDirectionalShadowCamera3DTightFit, createCamera2D, createCamera3D, createOrthographicProjection, createPerspectiveProjection, getCamera2DParallaxPoint, getCamera2DViewMatrix, getCamera2DVisibleBounds, getCamera3DForward, getCamera3DFrustum, getCamera3DFrustumCorners, getCamera3DInverseViewProjectionMatrix4, getCamera3DLinearDepth, getCamera3DPosition, getCamera3DRayThroughBoundingSphere, getCamera3DRight, getCamera3DScreenToWorldRay, getCamera3DUp, getCamera3DViewProjectionMatrix4, getCamera3DViewSpaceZ, getCamera3DWorldToScreen, getOrthographicProjectionTexelSize, intersectCamera3DRayWithPlane, isBoxInCamera3DFrustum, isOrthographicProjection, isPerspectiveProjection, isPointInCamera3DFrustum, isSphereInCamera3DFrustum, projectCamera2DPoint, setCamera3DAspect, setCamera3DJitter, setCamera3DViewMatrix4FromLookAt, setCamera3DViewMatrix4FromMatrix4, setProjectionMatrix4, unprojectCamera2DPoint, updateCamera3DInverseViewProjection, zoomCamera2DAtScreenPoint, } from './contract';
+export { areCameraGuardsEnabled, configureDirectionalShadowCamera3D, configureDirectionalShadowCamera3DTightFit, createCamera2D, createCamera3D, createOrthographicProjection, createPerspectiveProjection, disableCameraGuards, enableCameraGuards, getCamera2DParallaxPoint, getCamera2DViewMatrix, getCamera2DVisibleBounds, getCamera3DForward, getCamera3DFrustum, getCamera3DFrustumCorners, getCamera3DInverseViewProjectionMatrix4, getCamera3DLinearDepth, getCamera3DPosition, getCamera3DRayThroughBoundingSphere, getCamera3DRight, getCamera3DScreenToWorldRay, getCamera3DUp, getCamera3DViewProjectionMatrix4, getCamera3DViewSpaceZ, getCamera3DWorldToScreen, getOrthographicProjectionTexelSize, intersectCamera3DRayWithPlane, isBoxInCamera3DFrustum, isOrthographicProjection, isPerspectiveProjection, isPointInCamera3DFrustum, isSphereInCamera3DFrustum, projectCamera2DPoint, setCamera3DAspect, setCamera3DJitter, setCamera3DViewMatrix4FromLookAt, setCamera3DViewMatrix4FromMatrix4, setProjectionMatrix4, unprojectCamera2DPoint, updateCamera3DInverseViewProjection, zoomCamera2DAtScreenPoint, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,0CAA0C,EAC1C,cAAc,EACd,cAAc,EACd,4BAA4B,EAC5B,2BAA2B,EAC3B,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,uCAAuC,EACvC,sBAAsB,EACtB,mBAAmB,EACnB,mCAAmC,EACnC,gBAAgB,EAChB,2BAA2B,EAC3B,aAAa,EACb,gCAAgC,EAChC,qBAAqB,EACrB,wBAAwB,EACxB,kCAAkC,EAClC,6BAA6B,EAC7B,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,gCAAgC,EAChC,iCAAiC,EACjC,oBAAoB,EACpB,sBAAsB,EACtB,mCAAmC,EACnC,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,kCAAkC,EAClC,0CAA0C,EAC1C,cAAc,EACd,cAAc,EACd,4BAA4B,EAC5B,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,uCAAuC,EACvC,sBAAsB,EACtB,mBAAmB,EACnB,mCAAmC,EACnC,gBAAgB,EAChB,2BAA2B,EAC3B,aAAa,EACb,gCAAgC,EAChC,qBAAqB,EACrB,wBAAwB,EACxB,kCAAkC,EAClC,6BAA6B,EAC7B,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,gCAAgC,EAChC,iCAAiC,EACjC,oBAAoB,EACpB,sBAAsB,EACtB,mCAAmC,EACnC,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { configureDirectionalShadowCamera3D, configureDirectionalShadowCamera3DTightFit, createCamera2D, createCamera3D, createOrthographicProjection, createPerspectiveProjection, getCamera2DParallaxPoint, getCamera2DViewMatrix, getCamera2DVisibleBounds, getCamera3DForward, getCamera3DFrustum, getCamera3DFrustumCorners, getCamera3DInverseViewProjectionMatrix4, getCamera3DLinearDepth, getCamera3DPosition, getCamera3DRayThroughBoundingSphere, getCamera3DRight, getCamera3DScreenToWorldRay, getCamera3DUp, getCamera3DViewProjectionMatrix4, getCamera3DViewSpaceZ, getCamera3DWorldToScreen, getOrthographicProjectionTexelSize, intersectCamera3DRayWithPlane, isBoxInCamera3DFrustum, isOrthographicProjection, isPerspectiveProjection, isPointInCamera3DFrustum, isSphereInCamera3DFrustum, projectCamera2DPoint, setCamera3DAspect, setCamera3DJitter, setCamera3DViewMatrix4FromLookAt, setCamera3DViewMatrix4FromMatrix4, setProjectionMatrix4, unprojectCamera2DPoint, updateCamera3DInverseViewProjection, zoomCamera2DAtScreenPoint, } from './contract';
+export { areCameraGuardsEnabled, configureDirectionalShadowCamera3D, configureDirectionalShadowCamera3DTightFit, createCamera2D, createCamera3D, createOrthographicProjection, createPerspectiveProjection, disableCameraGuards, enableCameraGuards, getCamera2DParallaxPoint, getCamera2DViewMatrix, getCamera2DVisibleBounds, getCamera3DForward, getCamera3DFrustum, getCamera3DFrustumCorners, getCamera3DInverseViewProjectionMatrix4, getCamera3DLinearDepth, getCamera3DPosition, getCamera3DRayThroughBoundingSphere, getCamera3DRight, getCamera3DScreenToWorldRay, getCamera3DUp, getCamera3DViewProjectionMatrix4, getCamera3DViewSpaceZ, getCamera3DWorldToScreen, getOrthographicProjectionTexelSize, intersectCamera3DRayWithPlane, isBoxInCamera3DFrustum, isOrthographicProjection, isPerspectiveProjection, isPointInCamera3DFrustum, isSphereInCamera3DFrustum, projectCamera2DPoint, setCamera3DAspect, setCamera3DJitter, setCamera3DViewMatrix4FromLookAt, setCamera3DViewMatrix4FromMatrix4, setProjectionMatrix4, unprojectCamera2DPoint, updateCamera3DInverseViewProjection, zoomCamera2DAtScreenPoint, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,0CAA0C,EAC1C,cAAc,EACd,cAAc,EACd,4BAA4B,EAC5B,2BAA2B,EAC3B,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,uCAAuC,EACvC,sBAAsB,EACtB,mBAAmB,EACnB,mCAAmC,EACnC,gBAAgB,EAChB,2BAA2B,EAC3B,aAAa,EACb,gCAAgC,EAChC,qBAAqB,EACrB,wBAAwB,EACxB,kCAAkC,EAClC,6BAA6B,EAC7B,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,gCAAgC,EAChC,iCAAiC,EACjC,oBAAoB,EACpB,sBAAsB,EACtB,mCAAmC,EACnC,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,kCAAkC,EAClC,0CAA0C,EAC1C,cAAc,EACd,cAAc,EACd,4BAA4B,EAC5B,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,uCAAuC,EACvC,sBAAsB,EACtB,mBAAmB,EACnB,mCAAmC,EACnC,gBAAgB,EAChB,2BAA2B,EAC3B,aAAa,EACb,gCAAgC,EAChC,qBAAqB,EACrB,wBAAwB,EACxB,kCAAkC,EAClC,6BAA6B,EAC7B,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,gCAAgC,EAChC,iCAAiC,EACjC,oBAAoB,EACpB,sBAAsB,EACtB,mCAAmC,EACnC,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/visibleBounds.d.ts

@@ -1,3 +1,4 @@
 import type { Camera2D, RectangleLike } from '@flighthq/types/contract';
 export declare function getCamera2DVisibleBounds(camera: Readonly<Camera2D>, out: RectangleLike): void;
+export declare function setCamera2DVisibleBoundsGuard(guard: ((camera: Readonly<Camera2D>) => void) | null): void;
 //# sourceMappingURL=visibleBounds.d.ts.map

package/dist/visibleBounds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"visibleBounds.d.ts","sourceRoot":"","sources":["../src/visibleBounds.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAUxE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI,CAI7F"}
+{"version":3,"file":"visibleBounds.d.ts","sourceRoot":"","sources":["../src/visibleBounds.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAkBxE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI,CAW7F;AAID,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAExG"}

package/dist/visibleBounds.js

@@ -6,11 +6,40 @@ import { getCamera2DViewMatrix } from './viewMatrix';
 // higher zoom it shrinks (a smaller world region fills the viewport); under rotation it is the
 // enclosing AABB of the rotated view, so it over-covers rather than clipping visible content. The
 // rectangle is always centered on the camera position `(x, y)`.
+//
+// A zero `zoom` makes the view matrix singular and it has no inverse, so there is no world rectangle
+// to report. `zoom` is deliberately NOT clamped to rescue this: it is a caller-set value, and quietly
+// substituting a different one is the kind of hidden correction the SDK does not do. The failure is
+// handled HERE instead, and it fails toward drawing — an unbounded rectangle, so the cull excludes
+// nothing. The asymmetry is the whole reason: over-drawing is slow and visible, under-drawing is
+// silent and wrong, and a cull bound that silently collapses removes content with nothing to point at
+// the cause.
 export function getCamera2DVisibleBounds(camera, out) {
     getCamera2DViewMatrix(camera, scratchMatrix);
-    inverseMatrix(scratchInverse, scratchMatrix);
+    if (!inverseMatrix(scratchInverse, scratchMatrix)) {
+        out.x = UNBOUNDED_ORIGIN;
+        out.y = UNBOUNDED_ORIGIN;
+        out.width = UNBOUNDED_EXTENT;
+        out.height = UNBOUNDED_EXTENT;
+        degenerateVisibleBoundsGuard?.(camera);
+        return;
+    }
     matrixTransformBounds(out, scratchInverse, 0, 0, camera.viewportWidth, camera.viewportHeight);
 }
+// The seam the guard layer installs into; `null` keeps this module free of message text and of any
+// dependency on @flighthq/log, so an application that never imports the guards sheds both.
+export function setCamera2DVisibleBoundsGuard(guard) {
+    degenerateVisibleBoundsGuard = guard;
+}
+// Finite extremes rather than ±Infinity. With `-Infinity` origin and `Infinity` extent, a max edge is
+// `-Infinity + Infinity` = NaN, and every NaN comparison is false — which `intersectsRectangle` happens
+// to read as "overlaps", because it is written as the negation of four disjoint tests. That is the
+// right answer reached by accident, and only for that one predicate: any cull that compares centers,
+// areas, or sorts by extent gets NaN instead. Half of MAX_VALUE keeps `x + width` finite, so ordinary
+// arithmetic holds everywhere and the rectangle still encloses any real content.
+const UNBOUNDED_EXTENT = Number.MAX_VALUE;
+const UNBOUNDED_ORIGIN = -Number.MAX_VALUE / 2;
+let degenerateVisibleBoundsGuard = null;
 const scratchInverse = createMatrix();
 const scratchMatrix = createMatrix();
 //# sourceMappingURL=visibleBounds.js.map

package/dist/visibleBounds.js.map

@@ -1 +1 @@
-{"version":3,"file":"visibleBounds.js","sourceRoot":"","sources":["../src/visibleBounds.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAGjG,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAErD,sGAAsG;AACtG,qGAAqG;AACrG,oGAAoG;AACpG,+FAA+F;AAC/F,kGAAkG;AAClG,gEAAgE;AAChE,MAAM,UAAU,wBAAwB,CAAC,MAA0B,EAAE,GAAkB;IACrF,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC7C,aAAa,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC;IAC7C,qBAAqB,CAAC,GAAG,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;AAChG,CAAC;AAED,MAAM,cAAc,GAAG,YAAY,EAAE,CAAC;AACtC,MAAM,aAAa,GAAG,YAAY,EAAE,CAAC"}
+{"version":3,"file":"visibleBounds.js","sourceRoot":"","sources":["../src/visibleBounds.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAGjG,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAErD,sGAAsG;AACtG,qGAAqG;AACrG,oGAAoG;AACpG,+FAA+F;AAC/F,kGAAkG;AAClG,gEAAgE;AAChE,EAAE;AACF,qGAAqG;AACrG,sGAAsG;AACtG,oGAAoG;AACpG,mGAAmG;AACnG,iGAAiG;AACjG,sGAAsG;AACtG,aAAa;AACb,MAAM,UAAU,wBAAwB,CAAC,MAA0B,EAAE,GAAkB;IACrF,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC7C,IAAI,CAAC,aAAa,CAAC,cAAc,EAAE,aAAa,CAAC,EAAE,CAAC;QAClD,GAAG,CAAC,CAAC,GAAG,gBAAgB,CAAC;QACzB,GAAG,CAAC,CAAC,GAAG,gBAAgB,CAAC;QACzB,GAAG,CAAC,KAAK,GAAG,gBAAgB,CAAC;QAC7B,GAAG,CAAC,MAAM,GAAG,gBAAgB,CAAC;QAC9B,4BAA4B,EAAE,CAAC,MAAM,CAAC,CAAC;QACvC,OAAO;IACT,CAAC;IACD,qBAAqB,CAAC,GAAG,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;AAChG,CAAC;AAED,mGAAmG;AACnG,2FAA2F;AAC3F,MAAM,UAAU,6BAA6B,CAAC,KAAoD;IAChG,4BAA4B,GAAG,KAAK,CAAC;AACvC,CAAC;AAED,sGAAsG;AACtG,wGAAwG;AACxG,mGAAmG;AACnG,qGAAqG;AACrG,sGAAsG;AACtG,iFAAiF;AACjF,MAAM,gBAAgB,GAAG,MAAM,CAAC,SAAS,CAAC;AAC1C,MAAM,gBAAgB,GAAG,CAAC,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC;AAE/C,IAAI,4BAA4B,GAAkD,IAAI,CAAC;AACvF,MAAM,cAAc,GAAG,YAAY,EAAE,CAAC;AACtC,MAAM,aAAa,GAAG,YAAY,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/camera",
-  "version": "0.3.0",
+  "version": "0.3.1-next.1050.9114695",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,9 +38,10 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/entity": "0.3.0",
-    "@flighthq/geometry": "0.3.0",
-    "@flighthq/types": "0.3.0"
+    "@flighthq/entity": "0.3.1-next.1050.9114695",
+    "@flighthq/geometry": "0.3.1-next.1050.9114695",
+    "@flighthq/log": "0.3.1-next.1050.9114695",
+    "@flighthq/types": "0.3.1-next.1050.9114695"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/camera.test.ts

@@ -12,6 +12,7 @@ import {
   getCamera3DViewProjectionMatrix4,
   setCamera3DAspect,
   setCamera3DJitter,
+  setCamera3DViewGuard,
   setCamera3DViewMatrix4FromLookAt,
   setCamera3DViewMatrix4FromMatrix4,
   updateCamera3DInverseViewProjection,
@@ -157,6 +158,25 @@ describe('setCamera3DJitter', () => {
   });
 });
 
+describe('setCamera3DViewGuard', () => {
+  it('is notified whenever a view matrix is assigned, and not otherwise', () => {
+    const seen: number[] = [];
+    setCamera3DViewGuard((camera) => seen.push(camera.view.m[0]));
+    try {
+      const camera = createCamera3D({
+        far: 100,
+        near: 0.1,
+        projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }),
+      });
+      expect(seen).toEqual([]);
+      setCamera3DViewMatrix4FromMatrix4(camera, createMatrix4(4, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1));
+      expect(seen).toEqual([4]);
+    } finally {
+      setCamera3DViewGuard(null);
+    }
+  });
+});
+
 describe('setCamera3DViewMatrix4FromLookAt', () => {
   it('builds the view matrix from eye-target-up', () => {
     const camera = createCamera3D({

package/src/enableCameraGuards.test.ts

@@ -0,0 +1,94 @@
+import { createMatrix4, createRectangle } from '@flighthq/geometry/contract';
+import { setLogSink } from '@flighthq/log/contract';
+import type { Camera2D, LogEntry } from '@flighthq/types/contract';
+import { afterEach, describe, expect, test } from 'vitest';
+
+import { createCamera3D, setCamera3DViewMatrix4FromMatrix4 } from './camera';
+import { createCamera2D } from './camera2d';
+import { areCameraGuardsEnabled, disableCameraGuards, enableCameraGuards } from './enableCameraGuards';
+import { createPerspectiveProjection } from './projection';
+import { getCamera2DVisibleBounds } from './visibleBounds';
+
+describe('areCameraGuardsEnabled', () => {
+  test('reports whether the guards are installed', () => {
+    expect(areCameraGuardsEnabled()).toBe(false);
+    enableCameraGuards();
+    expect(areCameraGuardsEnabled()).toBe(true);
+    disableCameraGuards();
+    expect(areCameraGuardsEnabled()).toBe(false);
+  });
+});
+
+describe('disableCameraGuards', () => {
+  test('leaves the core silent again once removed', () => {
+    enableCameraGuards();
+    disableCameraGuards();
+    expect(captureLog(() => getCamera2DVisibleBounds(degenerateCamera(), createRectangle()))).toHaveLength(0);
+  });
+});
+
+describe('enableCameraGuards', () => {
+  // `logOnce` keys on the zoom and has no reset, so this is the ONE test allowed to trigger the
+  // degenerate key — a second would be deduplicated away and assert nothing. The seam itself is tested
+  // directly, and deterministically, in visibleBounds.test.ts.
+  test('warns, naming the zoom and the consequence, when the visible bounds cannot be computed', () => {
+    enableCameraGuards();
+    const entries = captureLog(() => getCamera2DVisibleBounds(degenerateCamera(), createRectangle()));
+    expect(entries).toHaveLength(1);
+    expect(entries[0].data).toMatchObject({ zoom: 0 });
+    expect(String((entries[0].data as { message: string }).message)).toContain('nothing is culled');
+  });
+
+  test('warns on a non-orthonormal 3D view, naming the cause rather than a consumer', () => {
+    enableCameraGuards();
+    const entries = captureLog(() => {
+      const camera = createCamera3D({
+        far: 100,
+        near: 0.1,
+        projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }),
+      });
+      setCamera3DViewMatrix4FromMatrix4(camera, createMatrix4(3, 0, 0, 0, 0, 3, 0, 0, 0, 0, 3, 0, 0, 0, 0, 1));
+    });
+    expect(entries).toHaveLength(1);
+    expect(String((entries[0].data as { message: string }).message)).toContain('not orthonormal');
+  });
+
+  // Reflections satisfy the precondition, so warning on them would be a false positive on a legitimate
+  // water/mirror camera.
+  test('stays silent for a reflection view', () => {
+    enableCameraGuards();
+    const entries = captureLog(() => {
+      const camera = createCamera3D({
+        far: 100,
+        near: 0.1,
+        projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }),
+      });
+      setCamera3DViewMatrix4FromMatrix4(camera, createMatrix4(-1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 2, 3, 4, 1));
+    });
+    expect(entries).toHaveLength(0);
+  });
+
+  test('stays silent for a camera whose view matrix inverts', () => {
+    enableCameraGuards();
+    expect(captureLog(() => getCamera2DVisibleBounds(createCamera2D(64, 64), createRectangle()))).toHaveLength(0);
+  });
+});
+
+afterEach(() => {
+  disableCameraGuards();
+});
+
+function captureLog(run: () => void): LogEntry[] {
+  const entries: LogEntry[] = [];
+  setLogSink((entry) => entries.push(entry));
+  try {
+    run();
+  } finally {
+    setLogSink(null);
+  }
+  return entries;
+}
+
+function degenerateCamera(): Camera2D {
+  return createCamera2D(64, 64, { zoom: 0 });
+}

package/src/explainCamera3DView.test.ts

@@ -0,0 +1,49 @@
+import { createMatrix4 } from '@flighthq/geometry/contract';
+import { describe, expect, test } from 'vitest';
+
+import { createCamera3D, setCamera3DViewMatrix4FromLookAt, setCamera3DViewMatrix4FromMatrix4 } from './camera';
+import { explainCamera3DView } from './explainCamera3DView';
+import { createPerspectiveProjection } from './projection';
+
+describe('explainCamera3DView', () => {
+  test('accepts a rigid lookAt view', () => {
+    const camera = perspectiveCamera();
+    setCamera3DViewMatrix4FromLookAt(camera, { x: 0, y: 0, z: 10 }, { x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });
+    const explanation = explainCamera3DView(camera);
+    expect(explanation.isOrthonormal).toBe(true);
+    expect(explanation.isReflection).toBe(false);
+    expect(explanation.determinant).toBeCloseTo(1, 6);
+  });
+
+  // The case manager asked to be costed before the contract was accepted: a mirror camera is improper
+  // orthogonal (det = -1) but STILL orthogonal, so Rᵀ = R⁻¹ holds and nothing that relies on the
+  // transpose is lost. It must not be reported as a violation.
+  test('accepts a reflection view and reports it as one', () => {
+    const camera = perspectiveCamera();
+    setCamera3DViewMatrix4FromMatrix4(camera, createMatrix4(-1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 5, 7, 9, 1));
+    const explanation = explainCamera3DView(camera);
+    expect(explanation.isOrthonormal).toBe(true);
+    expect(explanation.isReflection).toBe(true);
+    expect(explanation.determinant).toBeCloseTo(-1, 6);
+  });
+
+  test('reports a scaled view as non-orthonormal, with the deviation', () => {
+    const camera = perspectiveCamera();
+    setCamera3DViewMatrix4FromMatrix4(camera, createMatrix4(2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 1));
+    const explanation = explainCamera3DView(camera);
+    expect(explanation.isOrthonormal).toBe(false);
+    expect(explanation.scaleDeviation).toBeCloseTo(1, 6);
+  });
+
+  test('reports a sheared view as non-orthonormal', () => {
+    const camera = perspectiveCamera();
+    setCamera3DViewMatrix4FromMatrix4(camera, createMatrix4(1, 0, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1));
+    const explanation = explainCamera3DView(camera);
+    expect(explanation.isOrthonormal).toBe(false);
+    expect(explanation.shearDeviation).toBeGreaterThan(0.1);
+  });
+});
+
+function perspectiveCamera(): ReturnType<typeof createCamera3D> {
+  return createCamera3D({ far: 100, near: 0.1, projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }) });
+}

package/src/visibleBounds.test.ts

@@ -1,9 +1,9 @@
-import { createRectangle, createVector2 } from '@flighthq/geometry/contract';
-import { describe, expect, it } from 'vitest';
+import { createRectangle, createVector2, intersectsRectangle } from '@flighthq/geometry/contract';
+import { describe, expect, it, test } from 'vitest';
 
 import { createCamera2D } from './camera2d';
 import { unprojectCamera2DPoint } from './projection2d';
-import { getCamera2DVisibleBounds } from './visibleBounds';
+import { getCamera2DVisibleBounds, setCamera2DVisibleBoundsGuard } from './visibleBounds';
 
 describe('getCamera2DVisibleBounds', () => {
   it('covers the full viewport in world units at zoom 1', () => {
@@ -52,3 +52,35 @@ describe('getCamera2DVisibleBounds', () => {
     }
   });
 });
+
+describe('setCamera2DVisibleBoundsGuard', () => {
+  test('fails toward drawing: an unbounded rectangle that still intersects distant content', () => {
+    const out = createRectangle();
+    getCamera2DVisibleBounds(createCamera2D(64, 64, { zoom: 0 }), out);
+    // Finite on purpose — the max edge must survive ordinary arithmetic, not rely on NaN comparisons.
+    expect(Number.isFinite(out.x + out.width)).toBe(true);
+    expect(Number.isFinite(out.y + out.height)).toBe(true);
+    // The property that matters is behavioural, not the constant: nothing gets culled.
+    expect(intersectsRectangle(out, createRectangle(1e12, -4e11, 10, 10))).toBe(true);
+    expect(intersectsRectangle(out, createRectangle(-9e15, 8e14, 1, 1))).toBe(true);
+  });
+
+  test('notifies the installed guard exactly once per degenerate call, and never for an invertible camera', () => {
+    const seen: number[] = [];
+    setCamera2DVisibleBoundsGuard((camera) => seen.push(camera.zoom));
+    try {
+      getCamera2DVisibleBounds(createCamera2D(64, 64, { zoom: 0 }), createRectangle());
+      getCamera2DVisibleBounds(createCamera2D(64, 64), createRectangle());
+      expect(seen).toEqual([0]);
+    } finally {
+      setCamera2DVisibleBoundsGuard(null);
+    }
+  });
+
+  test('leaves an invertible camera computing the same bounds as before', () => {
+    const out = createRectangle();
+    getCamera2DVisibleBounds(createCamera2D(64, 32), out);
+    expect(out.width).toBeCloseTo(64, 6);
+    expect(out.height).toBeCloseTo(32, 6);
+  });
+});