@zakkster/lite-camera-pro 1.0.1 → 1.2.0

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;
-}
+// -- Package version (bumped in lockstep with package.json + llms.txt) --
+export declare const VERSION: string;
 
-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;
-}
-
-// ── 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;
@@ -168,60 +75,87 @@ export declare class CinematicCameraPro {
     predictTime: number;
     hybridVerticalSnap: boolean;
 
+    /**
+     * update() clamps a finite dt above this ceiling before integrating so a
+     * frame-time spike cannot diverge the position lerp (default 0.1s). Plain
+     * tunable; not validated per frame. See update() for the full dt policy.
+     */
+    maxDt: number;
+
     debugConfig: DebugHUDConfig;
 
-    // ── Follow Mode ──
+    // Follow mode
+    /** @throws Error `code = "ERR_CAMERA_MODE"` if mode is not an integer FollowMode in range. */
     setMode(mode: number): this;
 
-    // ── Multi-Target ──
+    // Multi-target
+    /** @throws Error `code = "ERR_CAMERA_TARGETS"` if targets is not an array or any entry lacks finite x/y (validated at call time). */
     trackMultiple(targets: Vec2[], options?: MultiTargetOptions): this;
     trackSingle(): this;
+    /** @throws Error `code = "ERR_CAMERA_TARGETS"` if count is not an integer in [0, targets.length]. */
     setTargetCount(count: number): this;
 
-    // ── Shake ──
+    // 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
+    /** @throws Error `code = "ERR_CAMERA_ZOOM"` if level is non-finite or duration is non-finite/negative. */
     setZoom(level: number, duration?: number, ease?: (t: number) => number): this;
+    /** @throws Error `code = "ERR_CAMERA_ZOOM"` if anchor x/y, level, or duration is non-finite (or duration negative). A non-function ease normalizes to null. */
     zoomAt(targetOrX: number | Vec2, yOrLevel: number, levelOrDur?: number, duration?: number, ease?: (t: number) => number): this;
 
-    // ── Coordinate Conversion ──
+    // 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
+    /**
+     * Advance the camera one frame. dt policy (fail closed): a non-finite or
+     * negative dt is a no-op (nothing mutated); dt 0/-0 is a legal no-advance
+     * frame; a finite dt above maxDt is clamped to maxDt (a dt exactly == maxDt
+     * passes untouched).
+     */
     update(dt: number, px: number, py: number, pvx?: number, pvy?: number): void;
     apply(ctx: CanvasRenderingContext2D): void;
 
-    // ── 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 };
+    /**
+     * Restore a pose-only snapshot (pos/target/zoom/mode). Validated in full
+     * before any field is written -- a rejected snapshot mutates nothing.
+     * posX/posY and targetX/targetY are both-or-neither; every present numeric
+     * must be finite; zoom is clamped to minZoom..maxZoom (zoom 0 -> minZoom);
+     * mode must be an integer FollowMode in range. Shake, sequences, and zoom
+     * animations are deliberately not serialized.
+     * @throws Error `code = "ERR_CAMERA_STATE"` on any violation.
+     */
     setState(snapshot: { posX?: number; posY?: number; targetX?: number; targetY?: number; zoom?: number; mode?: number }): this;
 
-    // ── Lifecycle ──
+    // Lifecycle
     destroy(): void;
 }
 

package/src/index.js

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