@zakkster/lite-camera-pro 1.0.1 → 1.2.0

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/FollowMode.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @zakkster/lite-camera-pro/follow -- TypeScript declarations.
+ *
+ * Follow-mode enum and the strategy dispatch table. Complete runtime surface,
+ * no `any`.
+ */
+
+import type { CinematicCameraPro } from './index.js';
+
+// -- Follow modes --
+export declare const FollowMode: {
+    readonly SMOOTH: 0;
+    readonly LOCK: 1;
+    readonly PREDICTIVE: 2;
+    readonly CUT: 3;
+    readonly HYBRID: 4;
+};
+
+// -- Strategy dispatch table, indexed by FollowMode value --
+export declare const FOLLOW_STRATEGIES: ReadonlyArray<
+    (cam: CinematicCameraPro, dt: number, px: number, py: number, pvx: number, pvy: number) => void
+>;
+
+declare const _default: typeof FollowMode;
+export default _default;

package/src/MultiTarget.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @zakkster/lite-camera-pro/multi -- TypeScript declarations.
+ *
+ * Multi-target framing: fit several targets in view. Pure math, no
+ * dependencies. Complete runtime surface, no `any`.
+ */
+
+import type { CinematicCameraPro } from './index.js';
+
+// -- A 2D point (target position) --
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+
+// -- Multi-target config/state (one per camera) --
+export interface MultiTargetState {
+    active: boolean;
+    targets: Vec2[] | null;
+    count: number;
+    paddingX: number;
+    paddingY: number;
+    minZoom: number;
+    maxZoom: number;
+    zoomSpeed: number;
+    followSpeed: number;
+}
+
+// -- Options accepted by CinematicCameraPro.trackMultiple --
+export interface MultiTargetOptions {
+    paddingX?: number;
+    paddingY?: number;
+    padding?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    zoomSpeed?: number;
+    followSpeed?: number;
+}
+
+export declare function updateMultiTarget(
+    cam: CinematicCameraPro,
+    dt: number,
+    targets: Vec2[],
+    count: number,
+): void;
+export declare function createMultiTargetState(): MultiTargetState;
+
+declare const _default: typeof updateMultiTarget;
+export default _default;

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/ParallaxManager.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @zakkster/lite-camera-pro/parallax -- TypeScript declarations.
+ *
+ * Multi-layer scroll manager. Pure math, no dependencies. Complete runtime
+ * surface, no `any`.
+ */
+
+// -- Wrap modes for layer tiling --
+export declare const WrapMode: {
+    readonly NONE: 0;
+    readonly REPEAT_X: 1;
+    readonly REPEAT_Y: 2;
+    readonly REPEAT_BOTH: 3;
+};
+
+// -- A single pre-allocated parallax layer --
+export interface ParallaxLayer {
+    active: boolean;
+    id: string;
+    speedX: number;
+    speedY: number;
+    offsetX: number;
+    offsetY: number;
+    wrap: number;
+    scrollX: number;
+    scrollY: number;
+}
+
+// -- Parallax manager state (one per camera) --
+export interface ParallaxState {
+    layers: ParallaxLayer[];
+    layerCount: number;
+    activeCount: number;
+}
+
+// -- Options accepted by addParallaxLayer --
+export interface ParallaxLayerOptions {
+    offsetX?: number;
+    offsetY?: number;
+    wrap?: number;
+}
+
+// -- Output shape for getLayerScroll --
+export interface ScrollOut {
+    x: number;
+    y: number;
+}
+
+export declare function createParallaxState(): ParallaxState;
+export declare function addParallaxLayer(
+    state: ParallaxState,
+    id: string,
+    speedX: number,
+    speedY?: number,
+    opts?: ParallaxLayerOptions,
+): ParallaxLayer | null;
+export declare function removeParallaxLayer(state: ParallaxState, id: string): void;
+export declare function updateParallax(state: ParallaxState, camX: number, camY: number, zoom: number): void;
+export declare function getLayerScroll(state: ParallaxState, id: string, out: ScrollOut): ScrollOut | null;
+export declare function applyParallaxLayer(state: ParallaxState, id: string, ctx: CanvasRenderingContext2D): boolean;

package/src/Shake.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @zakkster/lite-camera-pro/shake -- TypeScript declarations.
+ *
+ * The ./shake subpath barrel: the noise-based shake engine (ShakeEngine.js)
+ * plus the built-in presets and registry (ShakePresets.js). Complete runtime
+ * surface, no `any`.
+ */
+
+// -- Shake profile (input) --
+export interface ShakeProfile {
+    /** Initial trauma [0, 1]. Undefined defaults to 0.5 in addShake. */
+    trauma?: number;
+    /** Noise sample frequency (higher = more jittery). Default 15. */
+    freq?: number;
+    /** Trauma units lost per second. Default 1. */
+    decay?: number;
+    /** Maximum pixel offset at trauma=1. Default 15. */
+    maxOffset?: number;
+    /** Maximum rotation (radians) at trauma=1. Default 0.05. */
+    maxAngle?: number;
+    /** Directional X component; (0,0) = omnidirectional. Default 0. */
+    dirX?: number;
+    /** Directional Y component. Default 0. */
+    dirY?: number;
+    /** Per-profile intensity multiplier used by addShake. Default 1. */
+    intensity?: number;
+}
+
+// -- A single pre-allocated shake slot --
+export interface ShakeSlot {
+    active: boolean;
+    isDefault: boolean;
+    trauma: number;
+    decay: number;
+    freq: number;
+    time: number;
+    maxOffset: number;
+    maxAngle: number;
+    dirX: number;
+    dirY: number;
+    isDirectional: boolean;
+}
+
+// -- Shake engine state (one per camera) --
+export interface ShakeState {
+    slots: ShakeSlot[];
+    slotCount: number;
+    seedOffset: number;
+    /** Computed X offset in pixels (read by apply()). */
+    offsetX: number;
+    /** Computed Y offset in pixels. */
+    offsetY: number;
+    /** Computed rotation in radians. */
+    angle: number;
+    /** Global shake scale (0 = no shake, 1 = normal). */
+    globalScale: number;
+    /** True when any slot is active. */
+    active: boolean;
+}
+
+// -- Shake engine functions (ShakeEngine.js) --
+export declare function createShakeState(seedOffset?: number): ShakeState;
+export declare function addShake(state: ShakeState, profile: ShakeProfile, intensity?: number): void;
+export declare function addTraumaSimple(state: ShakeState, amount: number): void;
+export declare function updateShake(state: ShakeState, dt: number): void;
+export declare function computeShake(state: ShakeState): void;
+export declare function clearShakes(state: ShakeState): void;
+
+// -- Built-in presets (ShakePresets.js) --
+export declare const EXPLOSION: Readonly<ShakeProfile>;
+export declare const EARTHQUAKE: Readonly<ShakeProfile>;
+export declare const RECOIL: Readonly<ShakeProfile>;
+export declare const IMPACT: Readonly<ShakeProfile>;
+export declare const LANDING: Readonly<ShakeProfile>;
+export declare const DAMAGE: Readonly<ShakeProfile>;
+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/Shake.js

@@ -0,0 +1,7 @@
+// @zakkster/lite-camera-pro -- the ./shake subpath barrel.
+// Re-export only; never a copy. The camera class and this subpath import the
+// SAME module files, so createShakeState et al. have one runtime identity.
+// ShakePresets is folded in so a shake-only consumer gets presets + getPreset
+// from a single import.
+export * from './ShakeEngine.js';
+export * from './ShakePresets.js';

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 });
 }