@zakkster/lite-camera-pro 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -6,6 +6,129 @@ 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
+`@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
@@ -71,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

@@ -20,6 +20,13 @@
 npm install @zakkster/lite-camera-pro
 ```
 
+Need only screen shake? Import the `./shake` subpath and pull just the engine +
+presets (3.01 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,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.0.1
+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
@@ -109,9 +109,61 @@ 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     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  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.0.1",
+  "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,
@@ -13,7 +13,44 @@
       "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/",
@@ -50,15 +87,17 @@
     "@zakkster/lite-gc-profiler": "^1.16.0",
     "@zakkster/lite-leak": "^1.10.0",
     "@zakkster/lite-signal": "^1.5.0",
-    "esbuild": "^0.25.0"
+    "esbuild": "^0.25.0",
+    "typescript": "7.0.2"
   },
   "scripts": {
     "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",
+    "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 verify && 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/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;