@zakkster/lite-camera-pro 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -6,6 +6,82 @@ Versioning. Version lives in three places at once -- `package.json`, the
 `VERSION` const in `src/index.js`, and the `Version:` header in `llms.txt` --
 bumped together or not at all.
 
+## [1.2.0] -- 2026-08-30
+
+Fail-closed doors. Three reproduced ways ordinary runtime garbage permanently
+broke the render are closed at the entry, not patched in the body: a NaN dt that
+poisoned shake and camera forever (CP-3), a frame-time spike that diverged the
+position lerp (CP-4), and garbage into seven facade entries that crashed or froze
+at frame N+1 (CP-12, CP-19). The hot bodies are untouched: the only additions to
+an update path are two 2-line entry doors (`update()`, `updateShake()`), so the
+T6 alloc gate still holds at maxMajor 0 / maxPauseMs 4 with the shake and parallax
+pools pinned by identity. No new exports; the T8 main-entry surface is unchanged
+but for the VERSION value. Full policy in `decisions/0002-dt-policy.md` (repo-only).
+
+Credit: the ROADMAP audit catalogued CP-3/CP-4/CP-12; the PRO1 qa pass surfaced
+the CP-19 facade over-reads.
+
+### Added
+
+- **`cam.maxDt` tunable (default 0.1s).** `update()` clamps a finite dt above this
+  ceiling before integrating so a frame-time spike cannot diverge the position
+  lerp; a dt exactly == maxDt passes untouched. A plain field beside `lerpSpeed`,
+  not a per-frame-validated input (H-C).
+- **Fail-closed doors** on `setMode`, `setState`, `setZoom`, `zoomAt`,
+  `trackMultiple`, `setTargetCount` (facade) and `registerPreset` (shake
+  registry). Setters validate at the call so a defect fails loud there instead of
+  as a raw crash on the next frame. Shake profiles now finiteness-check every
+  numeric (decay/freq/maxOffset/maxAngle/dirX/dirY, not just trauma/intensity) in
+  the cold entry; the `profile.dirX || 0` NaN-laundering is removed.
+- **Five error codes** (house style, `.code` on a named Error): `ERR_CAMERA_MODE`,
+  `ERR_CAMERA_STATE`, `ERR_CAMERA_ZOOM`, `ERR_CAMERA_TARGETS`, `ERR_SHAKE_PRESET`.
+  Documented in `llms.txt`; a metadata drift guard asserts every code greppable in
+  `src/` is documented and vice versa (both directions, fail closed).
+- **dt policy decision record.** `decisions/0002-dt-policy.md` adopts reject
+  (Policy A) + clamp (Policy B) and records the rejection of an exponential-damping
+  rewrite (Policy C) by measurement. Repo-only; not shipped in the tarball.
+
+### Changed
+
+- **Measured door cost in the subpath weights** (esm, unminified, gzip -9):
+  `./shake` 2.82 -> 3.01 KB gz (the addShake full-profile guard + the preset
+  registry doors), `./sequence` 5.94 -> 6.01 KB gz (drags the preset registry),
+  `.` 21.70 -> 23.19 KB gz (all doors + their JSDoc). `./parallax`, `./bounds`,
+  `./multi`, `./follow` unchanged. The `./shake` budget gate (16384 B) holds at
+  3082 B.
+
+### Fixed
+
+- **CP-3 -- a NaN dt no longer poisons the shake engine forever.** Before:
+  `updateShake(state, NaN)` drove `time`/`trauma` to NaN, the `trauma <= 0` test
+  never fired, and `computeShake` emitted NaN every later frame; after one poison
+  frame plus 10k good frames the slot was still active with a NaN offset. Now the
+  reject door makes that frame a no-op and the slot decays to `active === false`,
+  `offsetX === 0`. The same poison via a profile (a NaN `decay`) is closed by the
+  addShake full-profile finiteness check.
+- **CP-4 -- a dt spike no longer diverges the position lerp.** Before: 40 frames
+  of `dt = 0.5` with `BoundsType.NONE` blew `pos` past 1e6 (the explicit
+  integrator is unstable for `lerpSpeed * dt > 2`). Now `update()` clamps dt to
+  `maxDt`, bounding `lerpSpeed * dt <= 0.5` at defaults; pos stays in the world
+  envelope. The exponential-damping alternative was rejected: measured against the
+  linear lerp at `lerpSpeed = 5` over 600 frames it drifts 15.884 px at dt = 1/60
+  and 32.981 px at dt = 1/30 -- four to five orders of magnitude above the f32
+  position-storage noise (~1.19e-4 px at a 1000 px offset), a visible change to how
+  valid frames feel (`decisions/0002-dt-policy.md`).
+- **CP-12 -- garbage into the facade fails loud, not at frame N+1.** Before:
+  `setMode(99)` left the strategy lookup undefined and the next `update()` threw a
+  raw un-coded TypeError; `setState({ zoom: 0 })` skipped the setZoom clamp and set
+  `visibleW` to Infinity; `setState({ zoom: NaN })` emitted `scale(NaN)` (a black
+  screen, no error); `shakePreset(undefined)` threw a raw TypeError from
+  `name.toLowerCase()`; `setZoom(NaN)` set zoom to NaN. Now each rejects at its door
+  (`ERR_CAMERA_MODE` / `ERR_CAMERA_STATE` / `ERR_CAMERA_ZOOM`) or is a documented
+  no-op (`shakePreset` unknown name), and `setState({ zoom: 0 })` clamps to 0.25.
+- **CP-19 -- multi-target over-reads are unreachable.** Before: `setTargetCount(64)`
+  on 2 targets, or `trackMultiple` with a garbage entry, crashed `updateMultiTarget`
+  at frame N+1 reading `.x` on undefined. Now `trackMultiple` validates the array and
+  every entry at call time and `setTargetCount` bounds the count to the array length,
+  both throwing `ERR_CAMERA_TARGETS`; the facade over-read is unreachable.
+
 ## [1.1.0] -- 2026-08-26
 
 Subpath exports. A consumer who needs only screen shake now imports
@@ -118,5 +194,6 @@ modes, multi-target auto-framing, an 8-slot simplex-noise shake engine with
 presets, fluent timeline sequences, a 16-layer parallax manager, per-edge
 bounds, a debug HUD, and zero-alloc coordinate conversion.
 
+[1.2.0]: https://github.com/PeshoVurtoleta/lite-camera-pro/releases/tag/v1.2.0
 [1.0.1]: https://github.com/PeshoVurtoleta/lite-camera-pro/releases/tag/v1.0.1
 [1.0.0]: https://github.com/PeshoVurtoleta/lite-camera-pro/releases/tag/v1.0.0

package/README.md

@@ -21,7 +21,7 @@ npm install @zakkster/lite-camera-pro
 ```
 
 Need only screen shake? Import the `./shake` subpath and pull just the engine +
-presets (2.82 KB gz -- esm, unminified, gzip -9):
+presets (3.01 KB gz -- esm, unminified, gzip -9):
 
 ```js
 import { createShakeState, addShake, updateShake, computeShake, getPreset } from '@zakkster/lite-camera-pro/shake';

package/llms.txt

@@ -6,7 +6,7 @@
 > with presets, fluent timeline sequences, a 16-layer parallax manager, per-edge
 > bounds, a debug HUD, and zero-alloc coordinate conversion.
 
-Version: 1.1.0
+Version: 1.2.0
 
 ESM only. `import` from `@zakkster/lite-camera-pro`. Default export is the
 CinematicCameraPro class. All hot-path APIs avoid allocation; setup-time calls
@@ -112,19 +112,58 @@ Enums:    FollowMode, FOLLOW_STRATEGIES, BoundsType, WrapMode
 ## Subpath exports (import only what you use; gz, esm, unminified, gzip -9)
 Beside the "." main entry, six subsystem subpaths + "./package.json". Same runtime
 identities as the main entry (one engine, no fork). Per-subpath gz weight:
-  ./shake     2.82 KB  createShakeState, addShake, addTraumaSimple, updateShake, computeShake, clearShakes + presets/getPreset/registerPreset/listPresets
+  ./shake     3.01 KB  createShakeState, addShake, addTraumaSimple, updateShake, computeShake, clearShakes + presets/getPreset/registerPreset/listPresets
   ./parallax  0.89 KB  createParallaxState, addParallaxLayer, removeParallaxLayer, updateParallax, getLayerScroll, applyParallaxLayer, WrapMode
   ./bounds    1.13 KB  createBoundsState, setBoundsAll, setBoundsEdges, setBoundsRect, clearBoundsRect, applyBounds, BoundsType
   ./multi     0.89 KB  createMultiTargetState, updateMultiTarget
   ./follow    0.71 KB  FollowMode, FOLLOW_STRATEGIES
-  ./sequence  5.94 KB  createCameraSequence, panTo, dramaticZoom, bossReveal, timedShake  (drags lite-timeline + lite-ease by design -- the only subpath that does)
-  .           21.70 KB full class + functional layer
+  ./sequence  6.01 KB  createCameraSequence, panTo, dramaticZoom, bossReveal, timedShake  (drags lite-timeline + lite-ease by design -- the only subpath that does)
+  .           23.19 KB full class + functional layer
 Self-reference example (shake only):
   import { createShakeState, addShake, updateShake, computeShake, getPreset } from '@zakkster/lite-camera-pro/shake';
 
 ## Dependencies (all @zakkster, first-party)
 @zakkster/lite-camera (base CinematicCamera), lite-ease, lite-lerp, lite-noise, lite-timeline.
 
+## Fail-closed doors (1.2.0)
+Ordinary runtime garbage (a NaN dt, a frame-time spike, a bad save file) can no longer
+break the render at frame N+1. Setters validate at the call; the update path validates at
+its entry; every unverified numeric fails loud or is a documented no-op. Hot bodies pay
+nothing (the doors are two comparisons on the update path; errors build only on cold throws).
+
+dt policy (cam.update(dt, ...) and standalone updateShake(state, dt)):
+- Non-finite (NaN/+-Infinity/null) or negative dt -> documented no-op, nothing mutated.
+- dt 0 and -0 -> legal no-advance frames (zero deltas everywhere).
+- cam.update clamps a finite dt above cam.maxDt (default 0.1s, a plain tunable) to cam.maxDt;
+  a dt exactly == maxDt passes untouched. updateShake is reject-only (no maxDt; a large finite
+  dt is self-limiting). Set cam.maxDt directly to retune; it is not validated per frame.
+
+Shake profiles (cam.shake / addShake): every numeric (trauma, decay, freq, maxOffset,
+maxAngle, dirX, dirY) is resolved to its default then finiteness-checked in the cold entry;
+a non-finite field activates NO slot (a NaN decay would otherwise leave a slot alive forever).
+
+Error codes (all throw a house-style Error with a .code):
+- ERR_CAMERA_MODE     setMode(mode): mode must be an integer FollowMode in [0, 4].
+- ERR_CAMERA_STATE    setState(snapshot): non-null object; posX/posY both-or-neither,
+                      targetX/targetY both-or-neither; every present numeric finite; zoom
+                      finite then clamped (zoom 0 -> minZoom 0.25, not an error); mode an
+                      integer FollowMode in range. Validated in full before any write
+                      (a rejected snapshot mutates nothing). Snapshot is pose-only
+                      (pos/target/zoom/mode) -- shake, sequences, zoom animations are not
+                      serialized.
+- ERR_CAMERA_ZOOM     setZoom(level, duration): level finite; duration finite and >= 0
+                      (0 = instant). zoomAt: anchor x/y, level, duration finite (>= 0);
+                      a non-function ease normalizes to null (both call forms).
+- ERR_CAMERA_TARGETS  trackMultiple(targets): array; every entry an object with finite x/y
+                      (validated at call time; empty array legal, count 0). setTargetCount(n):
+                      integer in [0, targets.length].
+- ERR_SHAKE_PRESET    registerPreset(name, profile): non-empty string name + object profile
+                      (setup path fails loud).
+- ERR_CAMERA_DESTROYED  every public method after destroy() (1.0.1).
+getPreset(name): a non-string or unknown name returns null (never throws) -- the event path.
+cam.shakePreset(name): an unknown or non-string name is a no-op returning this; use
+listPresets() to enumerate valid names.
+
 ## Notes
 - Migration: CinematicCameraPro is a drop-in superset of lite-camera's CinematicCamera.
 - Zero-GC: coordinate conversion uses caller-owned out objects; visible dims are cached properties (no getVisibleArea()); shake (8) and parallax (16) slots are pre-allocated and reused.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-camera-pro",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Cinematic camera system for Canvas2D games. Zero-GC, multi-target framing, noise-based shake, and timeline sequences.",
   "type": "module",
   "sideEffects": false,

package/src/CinematicCameraPro.js

@@ -101,6 +101,13 @@ export class CinematicCameraPro extends CinematicCamera {
         // ── Hybrid mode config ──
         this.hybridVerticalSnap = true; // true = instant, false = fast lerp
 
+        // -- dt policy tunable (see decisions/0002-dt-policy.md) --
+        // update() clamps a finite dt above this ceiling before integrating, so
+        // a frame-time spike cannot diverge the position lerp (CP-4). Plain knob,
+        // not a per-frame-validated input -- writing garbage here is out of
+        // contract (D-f). A dt exactly == maxDt passes unclamped (H-D).
+        this.maxDt = 0.1; // seconds
+
         // ── Multi-target framing ──
         this._mt = createMultiTargetState();
 
@@ -136,6 +143,14 @@ export class CinematicCameraPro extends CinematicCamera {
      * camera.setMode(FollowMode.PREDICTIVE);
      */
     setMode(mode) {
+        // Fail-closed door (CP-12): an out-of-range mode makes the update()
+        // strategy lookup undefined and crashes at frame N+1 with a raw
+        // TypeError. Reject at the setter with a named error instead.
+        if (!Number.isInteger(mode) || mode < 0 || mode >= FOLLOW_STRATEGIES.length) {
+            const e = new Error("CinematicCameraPro: setMode(mode) requires an integer FollowMode in [0, " + (FOLLOW_STRATEGIES.length - 1) + "]");
+            e.code = "ERR_CAMERA_MODE";
+            throw e;
+        }
         this.mode = mode;
         return this;
     }
@@ -167,6 +182,25 @@ export class CinematicCameraPro extends CinematicCamera {
      * camera.trackSingle();
      */
     trackMultiple(targets, options) {
+        // Fail-closed door (CP-19). Validate the array and every entry at CALL
+        // time -- a garbage target would otherwise crash updateMultiTarget at
+        // frame N+1 reading .x on undefined. Live mutation of the array/entries
+        // after this call is out of contract (no per-frame validation, H-C).
+        // An empty array is legal (count 0; update skips).
+        if (!Array.isArray(targets)) {
+            const e = new Error("CinematicCameraPro: trackMultiple(targets) requires an array");
+            e.code = "ERR_CAMERA_TARGETS";
+            throw e;
+        }
+        for (let i = 0; i < targets.length; i++) {
+            const t = targets[i];
+            if (t === null || typeof t !== 'object' || !Number.isFinite(t.x) || !Number.isFinite(t.y)) {
+                const e = new Error("CinematicCameraPro: trackMultiple targets[" + i + "] must be an object with finite x and y");
+                e.code = "ERR_CAMERA_TARGETS";
+                throw e;
+            }
+        }
+
         const mt = this._mt;
         mt.active = true;
         mt.targets = targets;
@@ -209,7 +243,17 @@ export class CinematicCameraPro extends CinematicCamera {
      * @returns {CinematicCameraPro} this
      */
     setTargetCount(count) {
-        this._mt.count = count;
+        // Fail-closed door (CP-19). count must be an integer in [0, targets
+        // length]; an over-count would make updateMultiTarget read past the
+        // array end and crash at frame N+1. n=0 with null targets is legal.
+        const mt = this._mt;
+        const max = mt.targets ? mt.targets.length : 0;
+        if (!Number.isInteger(count) || count < 0 || count > max) {
+            const e = new Error("CinematicCameraPro: setTargetCount(count) must be an integer in [0, " + max + "]");
+            e.code = "ERR_CAMERA_TARGETS";
+            throw e;
+        }
+        mt.count = count;
         return this;
     }
 
@@ -262,6 +306,10 @@ export class CinematicCameraPro extends CinematicCamera {
      * Built-in presets: explosion, earthquake, recoil, impact,
      * landing, damage, rumble, heavy_impact.
      *
+     * Fail-closed (CP-12/CP-19): an unknown name OR a non-string name is a
+     * documented no-op -- getPreset returns null, nothing is activated, and
+     * `this` is returned. Use listPresets() to enumerate valid names.
+     *
      * @param {string} name       Preset name (case-insensitive)
      * @param {number} [intensity=1] Scale multiplier
      * @returns {CinematicCameraPro} this
@@ -491,6 +539,20 @@ export class CinematicCameraPro extends CinematicCamera {
      * camera.setZoom(2.0, 0.5, easeOutExpo);
      */
     setZoom(level, duration = 0, ease = null) {
+        // Fail-closed door (CP-12). Finiteness precedes the clamp: clamp(NaN)
+        // returns NaN, so a NaN level would sail past the clamp and poison the
+        // zoom (F5). A non-finite or negative duration is defective input --
+        // duration 0 stays instant.
+        if (!Number.isFinite(level)) {
+            const e = new Error("CinematicCameraPro: setZoom(level) requires a finite number");
+            e.code = "ERR_CAMERA_ZOOM";
+            throw e;
+        }
+        if (!Number.isFinite(duration) || duration < 0) {
+            const e = new Error("CinematicCameraPro: setZoom duration must be a finite number >= 0");
+            e.code = "ERR_CAMERA_ZOOM";
+            throw e;
+        }
         level = clamp(level, this.minZoom, this.maxZoom);
 
         if (duration <= 0) {
@@ -533,27 +595,44 @@ export class CinematicCameraPro extends CinematicCamera {
      * camera.zoomAt(boss, 1.8, 0.8, easeOutExpo);
      */
     zoomAt(targetOrX, yOrLevel, levelOrDur, duration = 0, ease = null) {
-        let level, dur, easeFn;
+        // Fail-closed door (CP-12/CP-19). Resolve BOTH call forms into locals,
+        // validate them, and ONLY THEN write any this._ state -- a rejected call
+        // must mutate nothing. .x/.y are read and validated at CALL time only
+        // (live anchor mutation afterwards is out of contract). Finiteness
+        // precedes the clamp (F5). A non-function ease normalizes to null in
+        // both forms -- the static form gains it, closing a frame-N+1
+        // "this._zoomEase is not a function" crash.
+        let target, anchorX, anchorY, level, dur, easeFn;
 
         if (typeof targetOrX === 'object' && targetOrX !== null) {
             // zoomAt(target, level, duration, ease)
-            this._zoomTarget = targetOrX;
-            this._zoomAnchorX = targetOrX.x;
-            this._zoomAnchorY = targetOrX.y;
+            target = targetOrX;
+            anchorX = targetOrX.x;
+            anchorY = targetOrX.y;
             level = yOrLevel;
-            dur = levelOrDur || 0;
+            dur = levelOrDur !== undefined ? levelOrDur : 0;
             easeFn = duration; // shifted arg position — duration slot holds ease
-            if (typeof easeFn !== 'function') easeFn = null;
         } else {
             // zoomAt(x, y, level, duration, ease)
-            this._zoomTarget = null;
-            this._zoomAnchorX = targetOrX;
-            this._zoomAnchorY = yOrLevel;
+            target = null;
+            anchorX = targetOrX;
+            anchorY = yOrLevel;
             level = levelOrDur;
             dur = duration;
             easeFn = ease;
         }
+        if (typeof easeFn !== 'function') easeFn = null;
+
+        if (!Number.isFinite(anchorX) || !Number.isFinite(anchorY) ||
+            !Number.isFinite(level) || !Number.isFinite(dur) || dur < 0) {
+            const e = new Error("CinematicCameraPro: zoomAt requires finite anchor x/y, a finite level, and a finite duration >= 0");
+            e.code = "ERR_CAMERA_ZOOM";
+            throw e;
+        }
 
+        this._zoomTarget = target;
+        this._zoomAnchorX = anchorX;
+        this._zoomAnchorY = anchorY;
         this._hasAnchor = true;
         level = clamp(level, this.minZoom, this.maxZoom);
 
@@ -658,6 +737,15 @@ export class CinematicCameraPro extends CinematicCamera {
     /**
      * Advance the camera by one frame.
      *
+     * dt policy (fail closed -- see decisions/0002-dt-policy.md):
+     *   - Non-finite (NaN/+-Infinity/null) or negative dt is REJECTED: the call
+     *     is a documented no-op, nothing is mutated, and it returns. A poisoned
+     *     frame is invisible (CP-3/CP-4).
+     *   - dt === 0 and -0 are legal no-advance frames (zero deltas everywhere).
+     *   - A finite dt above this.maxDt (default 0.1) is clamped to this.maxDt so
+     *     a frame-time spike cannot diverge the position lerp; a dt exactly ==
+     *     maxDt passes untouched.
+     *
      * @param {number} dt   Delta time in seconds
      * @param {number} px   Player world X
      * @param {number} py   Player world Y
@@ -665,6 +753,11 @@ export class CinematicCameraPro extends CinematicCamera {
      * @param {number} [pvy=0] Player velocity Y (for lookahead)
      */
     update(dt, px, py, pvx = 0, pvy = 0) {
+        // Fail-closed dt door (CP-3/CP-4, D-k). Two comparisons at the very top;
+        // the whole body below is byte-identical to 1.1.0 (H-C: zero new
+        // branches on the hot path). A rejected frame mutates nothing.
+        if (!Number.isFinite(dt) || dt < 0) return;
+        if (dt > this.maxDt) dt = this.maxDt;
 
         const mt = this._mt;
         const seq = this._seq;
@@ -861,20 +954,82 @@ export class CinematicCameraPro extends CinematicCamera {
 
     /**
      * Restore camera state from a snapshot.
+     *
+     * Fail-closed contract (CP-12/CP-19 -- see decisions/0002-dt-policy.md
+     * siblings): the snapshot is validated in full BEFORE any field is written,
+     * so a rejected snapshot mutates nothing.
+     *   - snapshot must be a non-null object.
+     *   - posX/posY are both-or-neither; targetX/targetY are both-or-neither.
+     *   - every present numeric must be finite (the error names the field).
+     *   - zoom is finite-checked then clamped to minZoom..maxZoom exactly as
+     *     setZoom does -- zoom 0 clamps to minZoom (0.25), not an error.
+     *   - mode, if present, must be an integer FollowMode in range.
+     * The snapshot is pose-only (pos/target/zoom/mode); shake, sequences, and
+     * zoom animations are deliberately not serialized. Any violation throws
+     * ERR_CAMERA_STATE.
+     *
      * @param {Object} snapshot
      * @returns {CinematicCameraPro} this
      */
     setState(snapshot) {
-        if (snapshot.posX !== undefined) {
+        if (typeof snapshot !== 'object' || snapshot === null) {
+            const e = new Error("CinematicCameraPro: setState requires a snapshot object");
+            e.code = "ERR_CAMERA_STATE";
+            throw e;
+        }
+
+        const hasPosX = snapshot.posX !== undefined;
+        const hasPosY = snapshot.posY !== undefined;
+        const hasTargetX = snapshot.targetX !== undefined;
+        const hasTargetY = snapshot.targetY !== undefined;
+        const hasZoom = snapshot.zoom !== undefined;
+        const hasMode = snapshot.mode !== undefined;
+
+        // Pairing rule: a lone posX would write pos[1] = undefined -> NaN (F9).
+        if (hasPosX !== hasPosY) {
+            const e = new Error("CinematicCameraPro: setState posX and posY must be provided together");
+            e.code = "ERR_CAMERA_STATE";
+            throw e;
+        }
+        if (hasTargetX !== hasTargetY) {
+            const e = new Error("CinematicCameraPro: setState targetX and targetY must be provided together");
+            e.code = "ERR_CAMERA_STATE";
+            throw e;
+        }
+
+        // Finiteness of every present numeric (validate ALL before mutating ANY).
+        if (hasPosX && (!Number.isFinite(snapshot.posX) || !Number.isFinite(snapshot.posY))) {
+            const e = new Error("CinematicCameraPro: setState posX/posY must be finite numbers");
+            e.code = "ERR_CAMERA_STATE";
+            throw e;
+        }
+        if (hasTargetX && (!Number.isFinite(snapshot.targetX) || !Number.isFinite(snapshot.targetY))) {
+            const e = new Error("CinematicCameraPro: setState targetX/targetY must be finite numbers");
+            e.code = "ERR_CAMERA_STATE";
+            throw e;
+        }
+        if (hasZoom && !Number.isFinite(snapshot.zoom)) {
+            const e = new Error("CinematicCameraPro: setState zoom must be a finite number");
+            e.code = "ERR_CAMERA_STATE";
+            throw e;
+        }
+        if (hasMode && (!Number.isInteger(snapshot.mode) || snapshot.mode < 0 || snapshot.mode >= FOLLOW_STRATEGIES.length)) {
+            const e = new Error("CinematicCameraPro: setState mode must be an integer FollowMode in [0, " + (FOLLOW_STRATEGIES.length - 1) + "]");
+            e.code = "ERR_CAMERA_STATE";
+            throw e;
+        }
+
+        // All validated -> apply. zoom takes the same clamp as setZoom.
+        if (hasPosX) {
             this.pos[0] = snapshot.posX;
             this.pos[1] = snapshot.posY;
         }
-        if (snapshot.targetX !== undefined) {
+        if (hasTargetX) {
             this.target[0] = snapshot.targetX;
             this.target[1] = snapshot.targetY;
         }
-        if (snapshot.zoom !== undefined) this.zoom = snapshot.zoom;
-        if (snapshot.mode !== undefined) this.mode = snapshot.mode;
+        if (hasZoom) this.zoom = clamp(snapshot.zoom, this.minZoom, this.maxZoom);
+        if (hasMode) this.mode = snapshot.mode;
         this._updateBoundsForZoom();
         return this;
     }

package/src/MultiTarget.js

@@ -15,6 +15,14 @@
  *
  * Mutates cam.target[], cam.zoom directly. Zero allocations.
  *
+ * Count contract (caller-owned, standalone ./multi callers included): count
+ * must satisfy 0 <= count <= targets.length and every targets[0..count-1] must
+ * be an object with finite x/y. This loop reads targets[0..count-1] without
+ * per-frame validation (zero-GC hot path) -- an out-of-range count or a garbage
+ * entry is undefined behavior here. The CinematicCameraPro facade enforces the
+ * contract at its trackMultiple/setTargetCount doors (ERR_CAMERA_TARGETS);
+ * direct callers of this function own that guarantee themselves.
+ *
  * @param {CinematicCameraPro} cam       The camera instance
  * @param {number}             dt        Delta time in seconds
  * @param {{x:number,y:number}[]} targets  Array of target objects

package/src/Shake.d.ts

@@ -77,6 +77,12 @@ export declare const RUMBLE: Readonly<ShakeProfile>;
 export declare const HEAVY_IMPACT: Readonly<ShakeProfile>;
 
 // -- Preset registry (ShakePresets.js) --
+/** Case-insensitive lookup. Unknown or non-string name returns null (1.2.0). */
 export declare function getPreset(name: string): Readonly<ShakeProfile> | null;
+/**
+ * Register (or overwrite) a named preset. Setup path: fails loud.
+ * @throws Error with code "ERR_SHAKE_PRESET" if name is not a non-empty
+ *   string or profile is not a non-null object (1.2.0).
+ */
 export declare function registerPreset(name: string, profile: ShakeProfile): void;
 export declare function listPresets(): string[];

package/src/ShakeEngine.js

@@ -129,16 +129,34 @@ function acquireSlot(state) {
  * @param {number} [profile.intensity=1] Scale multiplier for the profile
  */
 export function addShake(state, profile, intensity = 1) {
-    // CP-14 + H-F (fail closed): validate trauma/intensity in this COLD entry so
-    // the per-frame updateShake/computeShake loops gain zero new branches.
-    //   - trauma undefined -> 0.5 (documented default)
-    //   - trauma or intensity non-finite (NaN/Inf) -> activate NOTHING, return
-    //     early. The old `profile.trauma || 0.5` laundered NaN to 0.5, opening a
-    //     poison door: a single NaN shake would drive every later frame to NaN.
-    //     null is not zero; an unverified number does not get a default.
+    // CP-14 + CP-3 + H-F (fail closed): validate the WHOLE profile in this COLD
+    // entry so the per-frame updateShake/computeShake loops gain zero new
+    // branches. Every numeric is resolved to its documented default FIRST (the
+    // `!== undefined ? : default` form -- including dirX/dirY, replacing the old
+    // `|| 0` that laundered a NaN direction to 0), then one combined finiteness
+    // check activates NOTHING and returns BEFORE acquireSlot on any failure:
+    //   - trauma undefined -> 0.5; a non-finite trauma/intensity fires nothing.
+    //     The old `profile.trauma || 0.5` laundered NaN to 0.5, a poison door.
+    //   - decay/freq/maxOffset/maxAngle/dirX/dirY non-finite -> reject too. A
+    //     NaN decay would leave the slot's trauma <= 0 test false forever, so
+    //     the slot never deactivates (CP-3 via a poisoned profile).
+    //   - null is not zero; an unverified number does not get a default.
     //   - resulting trauma <= 0 -> inert (a zero-trauma shake fires nothing).
+    // Valid, all-finite profiles resolve to the SAME slot values as before --
+    // only the ORDER of the default resolution moved (H-A).
     const rawTrauma = profile.trauma === undefined ? 0.5 : profile.trauma;
-    if (!Number.isFinite(rawTrauma) || !Number.isFinite(intensity)) return;
+    const decay = profile.decay !== undefined ? profile.decay : 1.0;
+    const freq = profile.freq !== undefined ? profile.freq : 15;
+    const maxOffset = profile.maxOffset !== undefined ? profile.maxOffset : 15;
+    const maxAngle = profile.maxAngle !== undefined ? profile.maxAngle : 0.05;
+    const dirX = profile.dirX !== undefined ? profile.dirX : 0;
+    const dirY = profile.dirY !== undefined ? profile.dirY : 0;
+
+    if (!Number.isFinite(rawTrauma) || !Number.isFinite(intensity) ||
+        !Number.isFinite(decay) || !Number.isFinite(freq) ||
+        !Number.isFinite(maxOffset) || !Number.isFinite(maxAngle) ||
+        !Number.isFinite(dirX) || !Number.isFinite(dirY)) return;
+
     const trauma = Math.min(1, rawTrauma * intensity);
     if (trauma <= 0) return;
 
@@ -147,22 +165,20 @@ export function addShake(state, profile, intensity = 1) {
     slot.active = true;
     slot.isDefault = false;
     slot.trauma = trauma;
-    slot.decay = profile.decay !== undefined ? profile.decay : 1.0;
-    slot.freq = profile.freq !== undefined ? profile.freq : 15;
-    slot.maxOffset = profile.maxOffset !== undefined ? profile.maxOffset : 15;
-    slot.maxAngle = profile.maxAngle !== undefined ? profile.maxAngle : 0.05;
+    slot.decay = decay;
+    slot.freq = freq;
+    slot.maxOffset = maxOffset;
+    slot.maxAngle = maxAngle;
     slot.time = 0; // reset time for fresh noise sampling
 
-    // Directional
-    const dx = profile.dirX || 0;
-    const dy = profile.dirY || 0;
-    slot.isDirectional = (dx !== 0 || dy !== 0);
+    // Directional. dirX/dirY are already resolved + finite-checked above.
+    slot.isDirectional = (dirX !== 0 || dirY !== 0);
 
     if (slot.isDirectional) {
         // Normalize direction
-        const len = Math.sqrt(dx * dx + dy * dy);
-        slot.dirX = dx / len;
-        slot.dirY = dy / len;
+        const len = Math.sqrt(dirX * dirX + dirY * dirY);
+        slot.dirX = dirX / len;
+        slot.dirY = dirY / len;
     } else {
         slot.dirX = 0;
         slot.dirY = 0;
@@ -220,6 +236,14 @@ export function addTraumaSimple(state, amount) {
  * @param {number} dt    Delta time in seconds
  */
 export function updateShake(state, dt) {
+    // CP-3 + H-C (fail closed): a non-finite or negative dt is rejected as a
+    // no-op in this entry so the per-slot loop below stays branch-for-branch
+    // unchanged. A NaN dt would drive s.time/s.trauma to NaN, the trauma <= 0
+    // test would never fire, and computeShake would emit NaN forever. No maxDt
+    // clamp here: a large finite dt is self-limiting (trauma decays past 0, the
+    // slot deactivates in one step). cam.update() hands an already-clamped dt.
+    if (!Number.isFinite(dt) || dt < 0) return;
+
     let anyActive = false;
 
     for (let i = 0; i < state.slotCount; i++) {

package/src/ShakePresets.js

@@ -144,10 +144,15 @@ const _registry = {
 /**
  * Get a preset by name.
  *
+ * Fail-closed (CP-12): a non-string name returns null (the event path -- e.g.
+ * cam.shakePreset(undefined) -- must not crash on name.toLowerCase()). An
+ * unknown string returns null too. Case-insensitive for valid strings.
+ *
  * @param {string} name  Preset name (case-insensitive)
  * @returns {Object|null} Shake profile or null
  */
 export function getPreset(name) {
+    if (typeof name !== 'string') return null;
     return _registry[name.toLowerCase()] || null;
 }
 
@@ -165,6 +170,16 @@ export function getPreset(name) {
  * });
  */
 export function registerPreset(name, profile) {
+    // Fail-closed (CP-12, setup path fails loud): a non-string/empty name or a
+    // non-object profile is a defective registration -- reject it rather than
+    // poison the registry with a key that getPreset can never resolve or a
+    // profile addShake would spread into garbage.
+    if (typeof name !== 'string' || name === '' ||
+        typeof profile !== 'object' || profile === null) {
+        const e = new Error("lite-camera-pro: registerPreset(name, profile) requires a non-empty string name and a profile object");
+        e.code = "ERR_SHAKE_PRESET";
+        throw e;
+    }
     _registry[name.toLowerCase()] = Object.freeze({ ...profile });
 }
 

package/src/index.d.ts

@@ -75,14 +75,24 @@ export declare class CinematicCameraPro {
     predictTime: number;
     hybridVerticalSnap: boolean;
 
+    /**
+     * update() clamps a finite dt above this ceiling before integrating so a
+     * frame-time spike cannot diverge the position lerp (default 0.1s). Plain
+     * tunable; not validated per frame. See update() for the full dt policy.
+     */
+    maxDt: number;
+
     debugConfig: DebugHUDConfig;
 
     // Follow mode
+    /** @throws Error `code = "ERR_CAMERA_MODE"` if mode is not an integer FollowMode in range. */
     setMode(mode: number): this;
 
     // Multi-target
+    /** @throws Error `code = "ERR_CAMERA_TARGETS"` if targets is not an array or any entry lacks finite x/y (validated at call time). */
     trackMultiple(targets: Vec2[], options?: MultiTargetOptions): this;
     trackSingle(): this;
+    /** @throws Error `code = "ERR_CAMERA_TARGETS"` if count is not an integer in [0, targets.length]. */
     setTargetCount(count: number): this;
 
     // Shake
@@ -98,7 +108,9 @@ export declare class CinematicCameraPro {
     readonly sequencePlaying: boolean;
 
     // Zoom
+    /** @throws Error `code = "ERR_CAMERA_ZOOM"` if level is non-finite or duration is non-finite/negative. */
     setZoom(level: number, duration?: number, ease?: (t: number) => number): this;
+    /** @throws Error `code = "ERR_CAMERA_ZOOM"` if anchor x/y, level, or duration is non-finite (or duration negative). A non-function ease normalizes to null. */
     zoomAt(targetOrX: number | Vec2, yOrLevel: number, levelOrDur?: number, duration?: number, ease?: (t: number) => number): this;
 
     // Coordinate conversion
@@ -117,6 +129,12 @@ export declare class CinematicCameraPro {
     clearBoundsRect(): this;
 
     // Core
+    /**
+     * Advance the camera one frame. dt policy (fail closed): a non-finite or
+     * negative dt is a no-op (nothing mutated); dt 0/-0 is a legal no-advance
+     * frame; a finite dt above maxDt is clamped to maxDt (a dt exactly == maxDt
+     * passes untouched).
+     */
     update(dt: number, px: number, py: number, pvx?: number, pvy?: number): void;
     apply(ctx: CanvasRenderingContext2D): void;
 
@@ -126,6 +144,15 @@ export declare class CinematicCameraPro {
 
     // Save / load
     getState(): { posX: number; posY: number; targetX: number; targetY: number; zoom: number; mode: number };
+    /**
+     * Restore a pose-only snapshot (pos/target/zoom/mode). Validated in full
+     * before any field is written -- a rejected snapshot mutates nothing.
+     * posX/posY and targetX/targetY are both-or-neither; every present numeric
+     * must be finite; zoom is clamped to minZoom..maxZoom (zoom 0 -> minZoom);
+     * mode must be an integer FollowMode in range. Shake, sequences, and zoom
+     * animations are deliberately not serialized.
+     * @throws Error `code = "ERR_CAMERA_STATE"` on any violation.
+     */
     setState(snapshot: { posX?: number; posY?: number; targetX?: number; targetY?: number; zoom?: number; mode?: number }): this;
 
     // Lifecycle

package/src/index.js

@@ -6,7 +6,7 @@
  * Zero external dependencies outside the @zakkster ecosystem.
  */
 
-export const VERSION = "1.1.0";
+export const VERSION = "1.2.0";
 
 // -- Core --
 export { CinematicCameraPro } from './CinematicCameraPro.js';