@flighthq/camera 0.3.0 → 0.3.1-next.1041.35b950c

package/dist/contract.d.ts

@@ -3,6 +3,7 @@ export * from './camera';
 export * from './camera2d';
 export * from './culling';
 export * from './depth';
+export * from './enableCameraGuards';
 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,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,7 @@ export * from './camera';
 export * from './camera2d';
 export * from './culling';
 export * from './depth';
+export * from './enableCameraGuards';
 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,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":"AAMA,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C;AAKD,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC"}

package/dist/enableCameraGuards.js

@@ -0,0 +1,28 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setCamera2DVisibleBoundsGuard } from './visibleBounds';
+export function areCameraGuardsEnabled() {
+    return cameraGuardsEnabled;
+}
+export function disableCameraGuards() {
+    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() {
+    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,
+    });
+}
+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,6BAA6B,EAAE,MAAM,iBAAiB,CAAC;AAEhE,MAAM,UAAU,sBAAsB;IACpC,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,6BAA6B,CAAC,IAAI,CAAC,CAAC;IACpC,mBAAmB,GAAG,KAAK,CAAC;AAC9B,CAAC;AAED,kGAAkG;AAClG,2FAA2F;AAC3F,iBAAiB;AACjB,MAAM,UAAU,kBAAkB;IAChC,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,IAAI,mBAAmB,GAAG,KAAK,CAAC"}

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.1041.35b950c",
   "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.1041.35b950c",
+    "@flighthq/geometry": "0.3.1-next.1041.35b950c",
+    "@flighthq/log": "0.3.1-next.1041.35b950c",
+    "@flighthq/types": "0.3.1-next.1041.35b950c"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/enableCameraGuards.test.ts

@@ -0,0 +1,63 @@
+import { 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 { createCamera2D } from './camera2d';
+import { areCameraGuardsEnabled, disableCameraGuards, enableCameraGuards } from './enableCameraGuards';
+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('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/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);
+  });
+});