@zakkster/lite-camera-pro 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+
+All notable changes to `@zakkster/lite-camera-pro` are documented here. The
+format follows Keep a Changelog, and this project adheres to Semantic
+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.1.0] -- 2026-08-26
+
+Subpath exports. A consumer who needs only screen shake now imports
+`@zakkster/lite-camera-pro/shake` and pays for the shake engine plus its
+tree-shaken noise sampler -- nothing else. No runtime behavior changed: the hot
+bodies (`computeShake`, `updateShake`, `apply`, `updateParallax`, `applyBounds`,
+`updateMultiTarget`) are byte-identical, and the camera class imports the same
+module files the subpaths expose (one engine, no fork -- proven by the T8
+Object.is identity check).
+
+Measured: the Las Vegas scratch-card consumer (BRIEF.md) reported a 73.5 KB gz
+whole-package pull for a three-tier win-shake ramp that touches only the shake
+API. Through `@zakkster/lite-camera-pro/shake` the same integration measures
+**2.82 KB gz** (2,883 B; 8.79 KB raw, esbuild esm, minify=false, gzip -9) --
+about **26x smaller**. Of that bundle, lite-noise's `Noise.js` contributes
+2,009 B (5.1% of its 39,613 B source), so tree-shaking through the noise
+dependency works as intended.
+
+### Added
+
+- **Subpath exports map.** Seven entries beside `.`: `./shake`, `./parallax`,
+  `./bounds`, `./multi`, `./follow`, `./sequence`, and `./package.json`. Each
+  runtime entry carries a sibling `types` condition (declared first, per the
+  TypeScript exports-map requirement). Per-subpath gz weights (esm, unminified,
+  gzip -9): `./shake` 2.82 KB, `./parallax` 0.89 KB, `./bounds` 1.13 KB,
+  `./multi` 0.89 KB, `./follow` 0.71 KB, `./sequence` 5.94 KB, `.` 21.70 KB.
+  `./sequence` drags `@zakkster/lite-timeline` + `@zakkster/lite-ease` by design
+  -- it is the only subpath that does.
+- **`src/Shake.js` barrel.** A two-line re-export over `ShakeEngine.js` +
+  `ShakePresets.js` (never a copy), so a shake-only consumer gets the engine,
+  the presets, and `getPreset`/`registerPreset`/`listPresets` from one import.
+- **Typed functional layer (CP-16a).** `src/index.d.ts` now re-exports six
+  per-subsystem sibling declarations (`Shake.d.ts`, `ParallaxManager.d.ts`,
+  `BoundsSystem.d.ts`, `MultiTarget.d.ts`, `FollowMode.d.ts`,
+  `CameraSequence.d.ts`), each declaring its module's complete runtime surface
+  -- state interfaces, enums, defaults, no `any`. The standalone functions are
+  now visible and typed at the main entry, not just the class.
+- **Size gate.** `test/size.mjs` bundles every subpath with the esbuild JS API
+  and asserts `./shake` gz stays at or under the fixed 16,384 B charter budget.
+  Wired into `npm run verify`.
+- **Dependency decision record (CP-17).** `decisions/0001-layout-and-deps.md`
+  documents the multi-file layout and the five first-party runtime deps, with
+  per-dep floor evidence. Repo-only; not shipped in the tarball.
+- **TypeScript smoke.** `test/types-smoke/smoke.ts` exercises every subpath plus
+  the main entry under `strict` + `noImplicitAny` + node16 resolution;
+  `npm run typecheck` runs it and joins `prepublishOnly`.
+
+## [1.0.1] -- 2026-08-25
+
+Foundation release: make the suite run, gate it, and land the fixes that cost
+nothing at the public surface. No behavior change to any valid, finite,
+in-bounds call -- CP-13 and CP-14 change only what defective input does.
+
+### Fixed
+
+- **CP-1 -- the standalone functional API is now reachable from the package
+  entry.** `src/index.js` re-exports `createShakeState` (Shake Engine) and
+  `createMultiTargetState` (Multi-Target); before, every state-taking function
+  in the documented tree-shakeable layer took a state no consumer could
+  construct. Reported in `BRIEF.md` by the Las Vegas scratch-card consumer.
+- **CP-8 -- use-after-destroy fails closed.** After
+  `CinematicCameraPro.destroy()`, EVERY public method throws an error with code
+  `ERR_CAMERA_DESTROYED` (fail closed) instead of a raw null deref. destroy()
+  calls `super.destroy()` for base parity, then rebinds the whole public surface
+  to the named-error sentinel, so the guarantee cannot drift as methods are
+  added. A double `destroy()` throws the same named error.
+- **CP-13 -- uniform floor snap.** `apply()` and `applyParallaxLayer()` now
+  snap the world/layer scroll with `Math.floor` instead of `| 0`, matching the
+  base camera. `| 0` truncated toward zero, disagreeing with the base by a full
+  pixel at negative fractional positions and taking a double-length integer step
+  about the origin.
+- **CP-14 + H-F -- trauma default fail-closed.** `addShake`/`addTraumaSimple`
+  replaced the falsy `profile.trauma || 0.5` default: `undefined` still means
+  0.5, but a non-finite trauma/intensity now activates NO slot (fail closed) and
+  an explicit `0` fires nothing. The old `||` laundered `NaN` into 0.5 -- the
+  only reason a NaN could not poison the shake sum from the trauma side (H-F).
+  The laundering is removed and the poison door closed in one change. Guards live
+  in the cold entry functions only; the per-frame `updateShake`/`computeShake`
+  loops are unchanged.
+
+### Added
+
+- **node:test suite.** Ported both vitest suites to `node:test` +
+  `node:assert/strict` (facade + standalone subsystems), added
+  `test/consumer.test.js` (the feel-freeze pinning the consumer's three-tier
+  shake ramp), `test/regressions.test.js` (one named test per finding above),
+  and `test/metadata.test.js` (three-place version law, packaging, CP-1 export
+  guard). Removed vitest and its config.
+- **Torture gate.** `test/torture.mjs` plus a tiered harness
+  (`@zakkster/lite-gc-profiler` + `@zakkster/lite-leak` + `@zakkster/lite-signal`
+  dev-only): metamorphic laws (T0), degenerate known-bad pins (T1), lifecycle
+  abuse (T4), the zero-alloc budget gate (T6: 200k `update`+`apply` under active
+  shake, `maxMajor:0`/`maxPauseMs:4`, pool-not-reallocated), retention soak (T7),
+  and the BREAK control (T9). `CAMPRO_TORTURE_BREAK=1` exits non-zero.
+- **Version law.** `export const VERSION = "1.0.1"` from `src/index.js`, this
+  `CHANGELOG.md`, and a `Version:` header in `llms.txt`.
+
+### Changed
+
+- Corrected three stale dependency header comments: `src/index.js` no longer
+  credits `lite-random` (not a dependency); `src/BoundsSystem.js` and
+  `src/MultiTarget.js` no longer claim a `@zakkster/lite-lerp` dependency they
+  do not import (their clamps are inline).
+
+## [1.0.0] -- 2025-06-28
+
+Initial release. Cinematic Canvas2D camera system extending
+`@zakkster/lite-camera`'s `CinematicCamera`: smooth/eased zoom, five follow
+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.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

@@ -20,6 +20,13 @@
 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):
+
+```js
+import { createShakeState, addShake, updateShake, computeShake, getPreset } from '@zakkster/lite-camera-pro/shake';
+```
+
 ---
 
 ## Why Pro?

package/llms.txt

@@ -6,6 +6,8 @@
 > 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
+
 ESM only. `import` from `@zakkster/lite-camera-pro`. Default export is the
 CinematicCameraPro class. All hot-path APIs avoid allocation; setup-time calls
 (constructor, createSequence, trackMultiple) may allocate.
@@ -107,6 +109,19 @@ Multi:    createMultiTargetState, updateMultiTarget
 Sequence: createCameraSequence, panTo, dramaticZoom, bossReveal, timedShake
 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
+  ./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
+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.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-camera-pro",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Cinematic camera system for Canvas2D games. Zero-GC, multi-target framing, noise-based shake, and timeline sequences.",
   "type": "module",
   "sideEffects": false,
@@ -13,11 +13,49 @@
       "node": "./src/index.js",
       "import": "./src/index.js",
       "default": "./src/index.js"
-    }
+    },
+    "./shake": {
+      "types": "./src/Shake.d.ts",
+      "node": "./src/Shake.js",
+      "import": "./src/Shake.js",
+      "default": "./src/Shake.js"
+    },
+    "./parallax": {
+      "types": "./src/ParallaxManager.d.ts",
+      "node": "./src/ParallaxManager.js",
+      "import": "./src/ParallaxManager.js",
+      "default": "./src/ParallaxManager.js"
+    },
+    "./bounds": {
+      "types": "./src/BoundsSystem.d.ts",
+      "node": "./src/BoundsSystem.js",
+      "import": "./src/BoundsSystem.js",
+      "default": "./src/BoundsSystem.js"
+    },
+    "./multi": {
+      "types": "./src/MultiTarget.d.ts",
+      "node": "./src/MultiTarget.js",
+      "import": "./src/MultiTarget.js",
+      "default": "./src/MultiTarget.js"
+    },
+    "./follow": {
+      "types": "./src/FollowMode.d.ts",
+      "node": "./src/FollowMode.js",
+      "import": "./src/FollowMode.js",
+      "default": "./src/FollowMode.js"
+    },
+    "./sequence": {
+      "types": "./src/CameraSequence.d.ts",
+      "node": "./src/CameraSequence.js",
+      "import": "./src/CameraSequence.js",
+      "default": "./src/CameraSequence.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "src/",
     "README.md",
+    "CHANGELOG.md",
     "llms.txt",
     "LICENSE"
   ],
@@ -46,14 +84,20 @@
     "@zakkster/lite-timeline": "^1.0.0"
   },
   "devDependencies": {
+    "@zakkster/lite-gc-profiler": "^1.16.0",
+    "@zakkster/lite-leak": "^1.10.0",
+    "@zakkster/lite-signal": "^1.5.0",
     "esbuild": "^0.25.0",
-    "vitest": "^4.1.4"
+    "typescript": "7.0.2"
   },
   "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "node --test test/*.test.js",
+    "test:gc": "node --expose-gc --test test/*.test.js",
+    "torture": "node --expose-gc test/torture.mjs",
+    "verify": "npm run test:gc && npm run torture && node test/size.mjs",
+    "typecheck": "tsc -p test/types-smoke/tsconfig.json",
     "bundle-check": "esbuild ./src/index.js --bundle --format=esm --outfile=test-bundle.js",
-    "prepublishOnly": "npm run test && npm run bundle-check"
+    "prepublishOnly": "npm run verify && npm run typecheck && npm run bundle-check"
   },
   "keywords": [
     "camera",

package/src/BoundsSystem.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @zakkster/lite-camera-pro/bounds -- TypeScript declarations.
+ *
+ * Configurable per-edge boundary behavior. Pure math, no dependencies.
+ * Complete runtime surface, no `any`.
+ */
+
+// -- Boundary types --
+export declare const BoundsType: {
+    readonly HARD: 0;
+    readonly SOFT: 1;
+    readonly ELASTIC: 2;
+    readonly NONE: 3;
+};
+
+// -- Bounds system state (one per camera) --
+export interface BoundsState {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    softZone: number;
+    elasticMax: number;
+    elasticStrength: number;
+    boundsX: number;
+    boundsY: number;
+    boundsW: number;
+    boundsH: number;
+    customBounds: boolean;
+}
+
+// -- Per-edge config for setBoundsEdges --
+export interface BoundsEdgesConfig {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+}
+
+export declare function createBoundsState(): BoundsState;
+export declare function setBoundsAll(state: BoundsState, type: number): void;
+export declare function setBoundsEdges(state: BoundsState, config: BoundsEdgesConfig): void;
+export declare function setBoundsRect(state: BoundsState, x: number, y: number, w: number, h: number): void;
+export declare function clearBoundsRect(state: BoundsState): void;
+export declare function applyBounds(
+    state: BoundsState,
+    target: Float32Array,
+    pos: Float32Array,
+    maxX: number,
+    maxY: number,
+    visW: number,
+    visH: number,
+    dt: number,
+): void;

package/src/BoundsSystem.js

@@ -11,7 +11,7 @@
  *
  * Zero allocations. All state is pre-allocated on the camera.
  *
- * Depends on: @zakkster/lite-lerp (clamp, smoothstep)
+ * Depends on: nothing (pure math -- clamp/smoothstep are inline).
  */
 
 /** @enum {number} */

package/src/CameraSequence.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @zakkster/lite-camera-pro/sequence -- TypeScript declarations.
+ *
+ * Timeline-driven camera choreography. NOTE: this subpath drags
+ * @zakkster/lite-timeline and @zakkster/lite-ease by design -- it is the only
+ * subpath that does. Complete runtime surface, no `any`.
+ */
+
+import type { CinematicCameraPro } from './index.js';
+import type { ShakeProfile } from './Shake.js';
+
+// -- Sequence construction options --
+export interface CameraSequenceOptions {
+    loop?: boolean;
+    onComplete?: () => void;
+    blendOutTime?: number;
+}
+
+// -- Per-step options --
+export interface StepOptions {
+    ease?: (t: number) => number;
+    at?: string | number;
+}
+
+// -- A fluent camera sequence handle --
+export interface CameraSequence {
+    moveTo(x: number, y: number, duration: number, opts?: StepOptions): CameraSequence;
+    zoomTo(level: number, duration: number, opts?: StepOptions): CameraSequence;
+    moveAndZoom(x: number, y: number, level: number, duration: number, opts?: StepOptions): CameraSequence;
+    shake(profileOrName: string | ShakeProfile, intensity?: number, opts?: StepOptions): CameraSequence;
+    wait(duration: number, opts?: StepOptions): CameraSequence;
+    call(fn: () => void, opts?: StepOptions): CameraSequence;
+    play(): CameraSequence;
+    pause(): CameraSequence;
+    resume(): CameraSequence;
+    stop(): CameraSequence;
+    seek(timeMs: number): CameraSequence;
+    destroy(): void;
+    readonly duration: number;
+    readonly progress: number;
+    readonly playing: boolean;
+}
+
+export declare function createCameraSequence(cam: CinematicCameraPro, options?: CameraSequenceOptions): CameraSequence;
+export declare function panTo(
+    cam: CinematicCameraPro,
+    x: number,
+    y: number,
+    duration: number,
+    opts?: CameraSequenceOptions & StepOptions,
+): CameraSequence;
+export declare function dramaticZoom(
+    cam: CinematicCameraPro,
+    x: number,
+    y: number,
+    zoom: number,
+    duration: number,
+    opts?: CameraSequenceOptions & StepOptions,
+): CameraSequence;
+export declare function bossReveal(
+    cam: CinematicCameraPro,
+    x: number,
+    y: number,
+    totalMs?: number,
+    opts?: CameraSequenceOptions,
+): CameraSequence;
+export declare function timedShake(
+    cam: CinematicCameraPro,
+    presetOrProfile: string | ShakeProfile,
+    holdMs?: number,
+    opts?: CameraSequenceOptions,
+): CameraSequence;
+
+declare const _default: typeof createCameraSequence;
+export default _default;

package/src/CinematicCameraPro.js

@@ -46,6 +46,16 @@ import {
 } from './BoundsSystem.js';
 import {createDebugHUDConfig, drawDebugHUD, drawDebugWorld} from './DebugHUD.js';
 
+// Cold-path sentinel: after destroy() every method that reads nulled internal
+// state is rebound to this so a use-after-destroy fails closed with a named
+// error instead of a raw null deref. Rebinding (not an in-body guard) keeps
+// update()/apply() at zero per-frame cost. Matches base CinematicCamera (CP-8).
+const _dead = () => {
+    const e = new Error("CinematicCameraPro: use after destroy()");
+    e.code = "ERR_CAMERA_DESTROYED";
+    throw e;
+};
+
 export class CinematicCameraPro extends CinematicCamera {
 
     /**
@@ -798,8 +808,10 @@ export class CinematicCameraPro extends CinematicCamera {
         ctx.scale(this.zoom, this.zoom);
         ctx.translate(-this._halfW / this.zoom, -this._halfH / this.zoom);
 
-        // 6. Scroll to camera world position
-        ctx.translate(-(this.pos[0] | 0), -(this.pos[1] | 0));
+        // 6. Scroll to camera world position.
+        // int snap is deliberate: kills texture shimmer. floor (not | 0) so the
+        // snap is uniform about the origin -- | 0 truncates toward zero (CP-13).
+        ctx.translate(-Math.floor(this.pos[0]), -Math.floor(this.pos[1]));
     }
 
     // ─────────────────────────────────────────────────────
@@ -868,9 +880,10 @@ export class CinematicCameraPro extends CinematicCamera {
     }
 
     /**
-     * Destroy the camera. Releases sequences, clears shake state, and
-     * nulls all nested allocations so the GC can reclaim them. After
-     * destroy(), the camera is unusable — do not call any further methods.
+     * Destroy the camera. Releases sequences, clears shake state, and nulls all
+     * nested allocations so the GC can reclaim them. After destroy() the camera
+     * is unusable: EVERY public method throws an Error with code
+     * "ERR_CAMERA_DESTROYED" (fail closed) rather than a raw null deref.
      */
     destroy() {
         if (this._seq) {
@@ -878,16 +891,37 @@ export class CinematicCameraPro extends CinematicCamera {
             this._seq = null;
         }
 
+        // clearShakeState needs _shake still live -- run it before the null.
         clearShakeState(this._shake);
 
-        // Release nested state so the slot pools / layer arrays can be GC'd
+        // Release nested Pro state so the slot pools / layer arrays can be GC'd.
         this._shake = null;
         this._mt = null;
         this._parallax = null;
         this._bounds = null;
         this.debugConfig = null;
-        this.pos = this.target = this.look = null;
-        this.rng = null;
+
+        // Null the base typed arrays + rng and rebind the base methods
+        // (update/apply/debug/addTrauma/resize/destroy) to the base sentinel.
+        // Ordered after the Pro teardown so nothing above reads a nulled base
+        // field. T8 asserts parity with the base's destroy contract.
+        super.destroy();
+
+        // CP-8: a destroyed camera fails closed on EVERY public method. Any call
+        // throws ERR_CAMERA_DESTROYED (Pro's sentinel -- consistent message)
+        // instead of a raw null deref. Rebinding the WHOLE public surface, not a
+        // curated subset, means the guarantee cannot silently drift as methods
+        // are added -- and re-stamps the base rebinds from super.destroy() with
+        // Pro's message for parity. Getters (sequencePlaying) are already
+        // null-safe. A double destroy() throws the same named error.
+        this.update = this.apply = this.debug = this.debugHUD =
+            this.addTrauma = this.shake = this.shakePreset = this.clearShakes =
+            this.setMode = this.trackMultiple = this.trackSingle = this.setTargetCount =
+            this.createSequence = this.playSequence = this.stopSequence =
+            this.addParallaxLayer = this.removeParallaxLayer = this.applyParallax =
+            this.setBoundsType = this.setBoundsEdges = this.setBoundsRect = this.clearBoundsRect =
+            this.setZoom = this.zoomAt = this.screenToWorld = this.worldToScreen =
+            this.getState = this.setState = this.resize = this.destroy = _dead;
     }
 }
 

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

@@ -6,7 +6,7 @@
  *
  * Used by boss fights, co-op, cutscenes tracking multiple actors.
  *
- * Depends on: @zakkster/lite-lerp (clamp)
+ * Depends on: nothing (pure math -- zoom/position clamps are inline).
  */
 
 /**

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/ParallaxManager.js

@@ -191,7 +191,10 @@ export function applyParallaxLayer(state, id, ctx) {
     for (let i = 0; i < state.layerCount; i++) {
         const layer = state.layers[i];
         if (layer.active && layer.id === id) {
-            ctx.translate(-(layer.scrollX | 0), -(layer.scrollY | 0));
+            // int snap is deliberate: kills texture shimmer. floor (not | 0) so
+            // the snap is uniform about the origin -- | 0 truncates toward zero
+            // (CP-13), matching the base camera and CinematicCameraPro.apply().
+            ctx.translate(-Math.floor(layer.scrollX), -Math.floor(layer.scrollY));
             return true;
         }
     }

package/src/Shake.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @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) --
+export declare function getPreset(name: string): Readonly<ShakeProfile> | null;
+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,11 +129,24 @@ 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.
+    //   - resulting trauma <= 0 -> inert (a zero-trauma shake fires nothing).
+    const rawTrauma = profile.trauma === undefined ? 0.5 : profile.trauma;
+    if (!Number.isFinite(rawTrauma) || !Number.isFinite(intensity)) return;
+    const trauma = Math.min(1, rawTrauma * intensity);
+    if (trauma <= 0) return;
+
     const slot = acquireSlot(state);
 
     slot.active = true;
     slot.isDefault = false;
-    slot.trauma = Math.min(1, (profile.trauma || 0.5) * intensity);
+    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;
@@ -166,6 +179,11 @@ export function addShake(state, profile, intensity = 1) {
  * @param {number} amount Trauma to add [0, 1]
  */
 export function addTraumaSimple(state, amount) {
+    // CP-14 + H-F (fail closed): a non-finite amount activates NOTHING and an
+    // amount <= 0 is inert. Same policy as addShake, in this cold entry only so
+    // the hot per-frame loops stay branch-for-branch unchanged.
+    if (!Number.isFinite(amount) || amount <= 0) return;
+
     // Try to find an existing default omni slot to stack onto.
     // Preset/profile slots are NEVER stacked onto — they have parameters
     // (freq, decay, etc.) that addTrauma's generic shake wouldn't match.

package/src/index.d.ts

@@ -1,68 +1,27 @@
 /**
- * @zakkster/lite-camera-pro — TypeScript Declarations
+ * @zakkster/lite-camera-pro -- TypeScript declarations (main entry).
+ *
+ * The full functional layer is re-exported from the per-subsystem sibling
+ * declarations (one declaration per type -- no duplicates). This file adds the
+ * CinematicCameraPro class, the debug-HUD facade, and the VERSION const.
  */
 
-// ── Follow Modes ──
-export declare const FollowMode: {
-    readonly SMOOTH: 0;
-    readonly LOCK: 1;
-    readonly PREDICTIVE: 2;
-    readonly CUT: 3;
-    readonly HYBRID: 4;
-};
-
-export declare const FOLLOW_STRATEGIES: ReadonlyArray<
-    (cam: CinematicCameraPro, dt: number, px: number, py: number, pvx: number, pvy: number) => void
->;
-
-// ── Wrap Modes ──
-export declare const WrapMode: {
-    readonly NONE: 0;
-    readonly REPEAT_X: 1;
-    readonly REPEAT_Y: 2;
-    readonly REPEAT_BOTH: 3;
-};
-
-// ── Bounds Types ──
-export declare const BoundsType: {
-    readonly HARD: 0;
-    readonly SOFT: 1;
-    readonly ELASTIC: 2;
-    readonly NONE: 3;
-};
-
-// ── Shake Profile ──
-export interface ShakeProfile {
-    trauma?: number;
-    freq?: number;
-    decay?: number;
-    maxOffset?: number;
-    maxAngle?: number;
-    dirX?: number;
-    dirY?: number;
-}
-
-// ── Shake Presets ──
-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>;
-
-export declare function getPreset(name: string): ShakeProfile | null;
-export declare function registerPreset(name: string, profile: ShakeProfile): void;
-export declare function listPresets(): string[];
-
-// ── Vec2 ──
-export interface Vec2 {
-    x: number;
-    y: number;
-}
-
-// ── Debug HUD Config ──
+// -- Functional layer (mirrors the ./shake, ./parallax, ./bounds, ./multi,
+//    ./follow, ./sequence subpaths; same runtime identities) --
+export * from './Shake.js';
+export * from './ParallaxManager.js';
+export * from './BoundsSystem.js';
+export * from './MultiTarget.js';
+export * from './FollowMode.js';
+export * from './CameraSequence.js';
+
+// -- Types needed locally by the class declaration --
+import type { ShakeProfile } from './Shake.js';
+import type { Vec2, MultiTargetOptions } from './MultiTarget.js';
+import type { BoundsEdgesConfig } from './BoundsSystem.js';
+import type { CameraSequence, CameraSequenceOptions } from './CameraSequence.js';
+
+// -- Debug HUD (DebugHUD.js) -- facade only, no dedicated subpath --
 export interface DebugHUDConfig {
     show: {
         position: boolean;
@@ -83,66 +42,14 @@ export declare function createDebugHUDConfig(): DebugHUDConfig;
 export declare function drawDebugHUD(cam: CinematicCameraPro, ctx: CanvasRenderingContext2D, config?: DebugHUDConfig): void;
 export declare function drawDebugWorld(cam: CinematicCameraPro, ctx: CanvasRenderingContext2D, config?: DebugHUDConfig): void;
 
-// ── Camera Sequence ──
-export interface CameraSequenceOptions {
-    loop?: boolean;
-    onComplete?: () => void;
-    blendOutTime?: number;
-}
-
-export interface StepOptions {
-    ease?: (t: number) => number;
-    at?: string | number;
-}
-
-export interface CameraSequence {
-    moveTo(x: number, y: number, duration: number, opts?: StepOptions): CameraSequence;
-    zoomTo(level: number, duration: number, opts?: StepOptions): CameraSequence;
-    moveAndZoom(x: number, y: number, level: number, duration: number, opts?: StepOptions): CameraSequence;
-    shake(profileOrName: string | ShakeProfile, intensity?: number, opts?: StepOptions): CameraSequence;
-    wait(duration: number, opts?: StepOptions): CameraSequence;
-    call(fn: () => void, opts?: StepOptions): CameraSequence;
-    play(): CameraSequence;
-    pause(): CameraSequence;
-    resume(): CameraSequence;
-    stop(): CameraSequence;
-    seek(timeMs: number): CameraSequence;
-    destroy(): void;
-    readonly duration: number;
-    readonly progress: number;
-    readonly playing: boolean;
-}
-
-export declare function createCameraSequence(cam: CinematicCameraPro, options?: CameraSequenceOptions): CameraSequence;
-export declare function panTo(cam: CinematicCameraPro, x: number, y: number, duration: number, opts?: CameraSequenceOptions & StepOptions): CameraSequence;
-export declare function dramaticZoom(cam: CinematicCameraPro, x: number, y: number, zoom: number, duration: number, opts?: CameraSequenceOptions & StepOptions): CameraSequence;
-export declare function bossReveal(cam: CinematicCameraPro, x: number, y: number, totalMs?: number, opts?: CameraSequenceOptions): CameraSequence;
-export declare function timedShake(cam: CinematicCameraPro, presetOrProfile: string | ShakeProfile, holdMs?: number, opts?: CameraSequenceOptions): CameraSequence;
-
-// ── Multi-Target Options ──
-export interface MultiTargetOptions {
-    paddingX?: number;
-    paddingY?: number;
-    padding?: number;
-    minZoom?: number;
-    maxZoom?: number;
-    zoomSpeed?: number;
-    followSpeed?: number;
-}
-
-// ── Bounds Config ──
-export interface BoundsEdgesConfig {
-    left?: number;
-    right?: number;
-    top?: number;
-    bottom?: number;
-}
+// -- Package version (bumped in lockstep with package.json + llms.txt) --
+export declare const VERSION: string;
 
-// ── Main Camera Class ──
+// -- Main camera class --
 export declare class CinematicCameraPro {
     constructor(viewW: number, viewH: number, worldW: number, worldH: number, seed?: number);
 
-    // ── Public state ──
+    // Public state
     readonly pos: Float32Array;
     readonly target: Float32Array;
     readonly look: Float32Array;
@@ -170,58 +77,58 @@ export declare class CinematicCameraPro {
 
     debugConfig: DebugHUDConfig;
 
-    // ── Follow Mode ──
+    // Follow mode
     setMode(mode: number): this;
 
-    // ── Multi-Target ──
+    // Multi-target
     trackMultiple(targets: Vec2[], options?: MultiTargetOptions): this;
     trackSingle(): this;
     setTargetCount(count: number): this;
 
-    // ── Shake ──
+    // Shake
     addTrauma(amount: number): this;
     shake(profile: ShakeProfile, intensity?: number): this;
     shakePreset(name: string, intensity?: number): this;
     clearShakes(): this;
 
-    // ── Sequences ──
+    // Sequences
     createSequence(options?: CameraSequenceOptions): CameraSequence;
     playSequence(seq: CameraSequence): this;
     stopSequence(): this;
     readonly sequencePlaying: boolean;
 
-    // ── Zoom ──
+    // Zoom
     setZoom(level: number, duration?: number, ease?: (t: number) => number): this;
     zoomAt(targetOrX: number | Vec2, yOrLevel: number, levelOrDur?: number, duration?: number, ease?: (t: number) => number): this;
 
-    // ── Coordinate Conversion ──
+    // Coordinate conversion
     screenToWorld(sx: number, sy: number, out: Vec2): Vec2;
     worldToScreen(wx: number, wy: number, out: Vec2): Vec2;
 
-    // ── Parallax ──
+    // Parallax
     addParallaxLayer(id: string, speedX: number, speedY?: number, opts?: { offsetX?: number; offsetY?: number; wrap?: number }): this;
     removeParallaxLayer(id: string): this;
     applyParallax(id: string, ctx: CanvasRenderingContext2D): boolean;
 
-    // ── Bounds ──
+    // Bounds
     setBoundsType(type: number): this;
     setBoundsEdges(config: BoundsEdgesConfig): this;
     setBoundsRect(x: number, y: number, w: number, h: number): this;
     clearBoundsRect(): this;
 
-    // ── Core ──
+    // Core
     update(dt: number, px: number, py: number, pvx?: number, pvy?: number): void;
     apply(ctx: CanvasRenderingContext2D): void;
 
-    // ── Debug ──
+    // Debug
     debug(ctx: CanvasRenderingContext2D): void;
     debugHUD(ctx: CanvasRenderingContext2D): void;
 
-    // ── Save / Load ──
+    // Save / load
     getState(): { posX: number; posY: number; targetX: number; targetY: number; zoom: number; mode: number };
     setState(snapshot: { posX?: number; posY?: number; targetX?: number; targetY?: number; zoom?: number; mode?: number }): this;
 
-    // ── Lifecycle ──
+    // Lifecycle
     destroy(): void;
 }
 

package/src/index.js

@@ -2,32 +2,34 @@
  * @zakkster/lite-camera-pro
  * Commercial cinematic camera system for Canvas2D games.
  *
- * Built on: lite-camera, lite-lerp, lite-ease, lite-random, lite-noise, lite-timeline
+ * Built on: lite-camera, lite-lerp, lite-ease, lite-noise, lite-timeline
  * Zero external dependencies outside the @zakkster ecosystem.
  */
 
-// ── Core ──
+export const VERSION = "1.1.0";
+
+// -- Core --
 export { CinematicCameraPro } from './CinematicCameraPro.js';
 export { default } from './CinematicCameraPro.js';
 
-// ── Follow Modes ──
+// -- Follow Modes --
 export { FollowMode, FOLLOW_STRATEGIES } from './FollowMode.js';
 
-// ── Multi-Target ──
-export { updateMultiTarget } from './MultiTarget.js';
+// -- Multi-Target --
+export { createMultiTargetState, updateMultiTarget } from './MultiTarget.js';
 
-// ── Shake Engine ──
-export { addShake, addTraumaSimple, updateShake, computeShake, clearShakes } from './ShakeEngine.js';
+// -- Shake Engine --
+export { createShakeState, addShake, addTraumaSimple, updateShake, computeShake, clearShakes } from './ShakeEngine.js';
 export { EXPLOSION, EARTHQUAKE, RECOIL, IMPACT, LANDING, DAMAGE, RUMBLE, HEAVY_IMPACT, getPreset, registerPreset, listPresets } from './ShakePresets.js';
 
-// ── Sequences ──
+// -- Sequences --
 export { createCameraSequence, panTo, dramaticZoom, bossReveal, timedShake } from './CameraSequence.js';
 
-// ── Parallax ──
+// -- Parallax --
 export { WrapMode, createParallaxState, addParallaxLayer, removeParallaxLayer, updateParallax, getLayerScroll, applyParallaxLayer } from './ParallaxManager.js';
 
-// ── Bounds ──
+// -- Bounds --
 export { BoundsType, createBoundsState, setBoundsAll, setBoundsEdges, setBoundsRect, clearBoundsRect, applyBounds } from './BoundsSystem.js';
 
-// ── Debug HUD ──
+// -- Debug HUD --
 export { createDebugHUDConfig, drawDebugHUD, drawDebugWorld } from './DebugHUD.js';