@zakkster/lite-camera-pro 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# 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.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/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.0.1
+
 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-camera-pro",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Cinematic camera system for Canvas2D games. Zero-GC, multi-target framing, noise-based shake, and timeline sequences.",
   "type": "module",
   "sideEffects": false,
@@ -18,6 +18,7 @@
   "files": [
     "src/",
     "README.md",
+    "CHANGELOG.md",
     "llms.txt",
     "LICENSE"
   ],
@@ -46,14 +47,18 @@
     "@zakkster/lite-timeline": "^1.0.0"
   },
   "devDependencies": {
-    "esbuild": "^0.25.0",
-    "vitest": "^4.1.4"
+    "@zakkster/lite-gc-profiler": "^1.16.0",
+    "@zakkster/lite-leak": "^1.10.0",
+    "@zakkster/lite-signal": "^1.5.0",
+    "esbuild": "^0.25.0"
   },
   "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",
     "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 bundle-check"
   },
   "keywords": [
     "camera",

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/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/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.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/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.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.0.1";
+
+// -- 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';