@zakkster/lite-camera-pro 1.0.0

package/src/DebugHUD.js

@@ -0,0 +1,290 @@
+/**
+ * @zakkster/lite-camera-pro — Debug HUD
+ *
+ * Full screen-space debug overlay with toggleable panels.
+ * Renders directly to canvas — no DOM, no HTML.
+ *
+ * Panels: position, zoom, follow mode, shake, sequence, parallax, bounds.
+ * Each panel can be toggled on/off individually.
+ *
+ * Zero dependencies beyond the camera instance.
+ */
+import {BoundsType} from './BoundsSystem.js';
+
+const LINE_H = 13;
+const PAD = 8;
+const FONT = '10px monospace';
+const FONT_BOLD = 'bold 10px monospace';
+const BG = 'rgba(0,0,0,0.6)';
+const COL_YELLOW = '#fbbf24';
+const COL_RED = '#ef4444';
+const COL_PURPLE = '#a78bfa';
+const COL_CYAN = '#22d3ee';
+const COL_GREEN = '#34d399';
+const COL_DIM = '#6b7280';
+const COL_WHITE = '#e5e5e5';
+
+const MODE_NAMES = ['SMOOTH', 'LOCK', 'PREDICTIVE', 'CUT', 'HYBRID'];
+const BOUNDS_NAMES = ['HARD', 'SOFT', 'ELASTIC', 'NONE'];
+
+/**
+ * Create debug HUD configuration.
+ * @returns {Object} HUD config — mutate .show to toggle panels
+ */
+export function createDebugHUDConfig() {
+    return {
+        show: {
+            position: true,
+            zoom: true,
+            mode: true,
+            shake: true,
+            sequence: true,
+            parallax: true,
+            bounds: true,
+            deadzone: true,   // world-space deadzone rect
+            lookahead: true,   // world-space lookahead vector
+        },
+        x: 4,
+        y: 4,
+    };
+}
+
+/**
+ * Draw the full debug HUD. Screen-space (call AFTER ctx.restore()).
+ *
+ * @param {CinematicCameraPro} cam
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {Object} [config]  HUD config from createDebugHUDConfig()
+ */
+export function drawDebugHUD(cam, ctx, config) {
+    const show = config ? config.show : {
+        position: true,
+        zoom: true,
+        mode: true,
+        shake: true,
+        sequence: true,
+        parallax: true,
+        bounds: true
+    };
+    const ox = config ? config.x : 4;
+    const oy = config ? config.y : 4;
+    const panelW = 260;
+
+    ctx.save();
+    ctx.font = FONT;
+
+    // ── Pass 1: count lines to size the background ──
+    let lineCount = 0;
+
+    if (show.position) lineCount += 2;
+    if (show.zoom) lineCount += 1;
+    if (show.mode) lineCount += 1;
+
+    if (show.shake) {
+        const sh = cam._shake;
+        if (sh.active) {
+            lineCount += 1; // header
+            for (let i = 0; i < sh.slotCount; i++) {
+                if (sh.slots[i].active) lineCount++;
+            }
+        }
+    }
+
+    if (show.sequence && cam._seq && cam._seq.playing) lineCount += 1;
+
+    if (show.parallax && cam._parallax.activeCount > 0) {
+        lineCount += 1;
+        for (let i = 0; i < cam._parallax.layerCount; i++) {
+            if (cam._parallax.layers[i].active) lineCount++;
+        }
+    }
+
+    if (show.bounds) {
+        const b = cam._bounds;
+
+        if (b.left !== BoundsType.HARD ||
+            b.right !== BoundsType.HARD ||
+            b.top !== BoundsType.HARD ||
+            b.bottom !== BoundsType.HARD) {
+            lineCount += 1;
+        }
+    }
+
+    if (lineCount === 0) {
+        ctx.restore();
+        return;
+    }
+
+    // ── Background ──
+    ctx.fillStyle = BG;
+    ctx.fillRect(ox, oy, panelW, lineCount * LINE_H + PAD * 2);
+
+    // ── Pass 2: draw directly, no intermediate objects ──
+    let row = 0;
+    const textX = ox + PAD;
+    const baseY = oy + PAD;
+
+    if (show.position) {
+        ctx.fillStyle = COL_DIM;
+        ctx.fillText(`pos  ${cam.pos[0].toFixed(1)}, ${cam.pos[1].toFixed(1)}`, textX, baseY + row * LINE_H);
+        row++;
+        ctx.fillText(`tgt  ${cam.target[0].toFixed(1)}, ${cam.target[1].toFixed(1)}`, textX, baseY + row * LINE_H);
+        row++;
+    }
+
+    if (show.zoom) {
+        ctx.fillStyle = COL_YELLOW;
+        ctx.fillText(`zoom ${cam.zoom.toFixed(3)}  vis ${cam.visibleW.toFixed(0)}×${cam.visibleH.toFixed(0)}`, textX, baseY + row * LINE_H);
+        row++;
+    }
+
+    if (show.mode) {
+        ctx.fillStyle = COL_CYAN;
+        ctx.fillText(`mode ${MODE_NAMES[cam.mode] || '?'}`, textX, baseY + row * LINE_H);
+        row++;
+    }
+
+    if (show.shake) {
+        const sh = cam._shake;
+        if (sh.active) {
+            let actSlots = 0, mxT = 0;
+            for (let i = 0; i < sh.slotCount; i++) {
+                if (sh.slots[i].active) {
+                    actSlots++;
+                    if (sh.slots[i].trauma > mxT) mxT = sh.slots[i].trauma;
+                }
+            }
+            ctx.fillStyle = COL_RED;
+            ctx.fillText(`shake ${actSlots} slot${actSlots > 1 ? 's' : ''} trauma=${mxT.toFixed(2)}`, textX, baseY + row * LINE_H);
+            row++;
+
+            for (let i = 0; i < sh.slotCount; i++) {
+                const s = sh.slots[i];
+                if (!s.active) continue;
+                const col = s.isDirectional ? COL_PURPLE : COL_RED;
+                ctx.fillStyle = col;
+                ctx.fillText(`  \u251C t=${s.trauma.toFixed(2)} f=${s.freq} d=${s.decay.toFixed(1)}${s.isDirectional ? ' dir' : ''}`, textX, baseY + row * LINE_H);
+                // Trauma bar
+                const barX = ox + panelW - 70;
+                const barY = baseY + row * LINE_H - 8;
+                ctx.fillStyle = 'rgba(255,255,255,0.08)';
+                ctx.fillRect(barX, barY, 60, 7);
+                ctx.fillStyle = col;
+                ctx.fillRect(barX, barY, 60 * s.trauma, 7);
+                row++;
+            }
+        }
+    }
+
+    if (show.sequence && cam._seq && cam._seq.playing) {
+        const progress = cam._seq.progress;
+        ctx.fillStyle = COL_PURPLE;
+        ctx.fillText(`seq  ${(progress * 100).toFixed(0)}%`, textX, baseY + row * LINE_H);
+        const barX = ox + panelW - 70;
+        const barY = baseY + row * LINE_H - 8;
+        ctx.fillStyle = 'rgba(255,255,255,0.08)';
+        ctx.fillRect(barX, barY, 60, 7);
+        ctx.fillStyle = COL_PURPLE;
+        ctx.fillRect(barX, barY, 60 * progress, 7);
+        row++;
+    }
+
+    if (show.parallax && cam._parallax.activeCount > 0) {
+        ctx.fillStyle = COL_GREEN;
+        ctx.fillText(`parallax ${cam._parallax.activeCount} layers`, textX, baseY + row * LINE_H);
+        row++;
+        for (let i = 0; i < cam._parallax.layerCount; i++) {
+            const l = cam._parallax.layers[i];
+            if (!l.active) continue;
+            ctx.fillStyle = COL_DIM;
+            ctx.fillText(`  \u251C ${l.id} speed=${l.speedX.toFixed(1)}`, textX, baseY + row * LINE_H);
+            row++;
+        }
+    }
+
+    if (show.bounds) {
+        const b = cam._bounds;
+
+        if (b.left !== BoundsType.HARD ||
+            b.right !== BoundsType.HARD ||
+            b.top !== BoundsType.HARD ||
+            b.bottom !== BoundsType.HARD) {
+            ctx.fillStyle = COL_CYAN;
+            ctx.fillText(`bounds L:${BOUNDS_NAMES[b.left]} R:${BOUNDS_NAMES[b.right]} T:${BOUNDS_NAMES[b.top]} B:${BOUNDS_NAMES[b.bottom]}`, textX, baseY + row * LINE_H);
+            row++;
+        }
+    }
+
+    ctx.restore();
+}
+
+/**
+ * Draw world-space debug overlay (deadzone rect, lookahead vector, world bounds).
+ * Call INSIDE ctx.save()/apply()/restore(), in camera-transformed space.
+ *
+ * @param {CinematicCameraPro} cam
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {Object} [config]  HUD config
+ */
+export function drawDebugWorld(cam, ctx, config) {
+    const show = config ? config.show : {deadzone: true, lookahead: true};
+
+    ctx.save();
+
+    const cx = cam.target[0] - cam.pos[0] + cam.visibleW * 0.5;
+    const cy = cam.target[1] - cam.pos[1] + cam.visibleH * 0.5;
+
+    // ── Deadzone rectangle ──
+    if (show.deadzone !== false) {
+        ctx.strokeStyle = 'rgba(251,191,36,0.4)';
+        ctx.lineWidth = 1;
+        ctx.strokeRect(
+            cx - cam.deadzoneX,
+            cy - cam.deadzoneY,
+            cam.deadzoneX * 2,
+            cam.deadzoneY * 2
+        );
+
+        // Center crosshair
+        ctx.beginPath();
+        ctx.moveTo(cx - 6, cy);
+        ctx.lineTo(cx + 6, cy);
+        ctx.moveTo(cx, cy - 6);
+        ctx.lineTo(cx, cy + 6);
+        ctx.stroke();
+    }
+
+    // ── Lookahead vector ──
+    if (show.lookahead !== false) {
+        const lx = cam.look[0];
+        const ly = cam.look[1];
+        const len = Math.sqrt(lx * lx + ly * ly);
+        if (len > 1) {
+            ctx.strokeStyle = COL_CYAN;
+            ctx.lineWidth = 2;
+            ctx.beginPath();
+            ctx.moveTo(cx, cy);
+            ctx.lineTo(cx + lx, cy + ly);
+            ctx.stroke();
+
+            // Arrowhead
+            const angle = Math.atan2(ly, lx);
+            const aLen = 6;
+            ctx.beginPath();
+            ctx.moveTo(cx + lx, cy + ly);
+            ctx.lineTo(cx + lx - aLen * Math.cos(angle - 0.4), cy + ly - aLen * Math.sin(angle - 0.4));
+            ctx.moveTo(cx + lx, cy + ly);
+            ctx.lineTo(cx + lx - aLen * Math.cos(angle + 0.4), cy + ly - aLen * Math.sin(angle + 0.4));
+            ctx.stroke();
+        }
+    }
+
+    // ── World bounds outline ──
+    ctx.strokeStyle = 'rgba(239,68,68,0.2)';
+    ctx.lineWidth = 2;
+    ctx.strokeRect(0, 0, cam.worldW, cam.worldH);
+
+    ctx.restore();
+}
+
+export default drawDebugHUD;

package/src/FollowMode.js

@@ -0,0 +1,179 @@
+/**
+ * @zakkster/lite-camera-pro — Follow Mode Strategies
+ *
+ * Each mode is a pure function:
+ *   (camera, dt, px, py, pvx, pvy) => void
+ *
+ * Mutates camera.target[] directly. No allocations.
+ * The camera's update() dispatches to the active strategy.
+ *
+ * Modes:
+ *   SMOOTH      — lerp + deadzone + lookahead (default, same as lite-camera)
+ *   LOCK        — snap to target, no interpolation
+ *   PREDICTIVE  — heavy velocity extrapolation, aggressive lookahead
+ *   CUT         — instant jump (for cutscene hard cuts)
+ *   HYBRID      — smooth horizontal, locked vertical (platformer standard)
+ */
+
+/** @enum {number} */
+export const FollowMode = {
+    SMOOTH:     0,
+    LOCK:       1,
+    PREDICTIVE: 2,
+    CUT:        3,
+    HYBRID:     4,
+};
+
+/**
+ * SMOOTH — Default. Deadzone + lookahead + lerp.
+ * This is the same behavior as lite-camera base.
+ */
+function smooth(cam, dt, px, py, pvx, pvy) {
+    const len = Math.sqrt(pvx * pvx + pvy * pvy);
+    const targetLx = len > 0 ? (pvx / len) * cam.lookaheadDist : 0;
+    const targetLy = len > 0 ? (pvy / len) * cam.lookaheadDist : 0;
+
+    cam.look[0] += (targetLx - cam.look[0]) * cam.lookaheadSpeed * dt;
+    cam.look[1] += (targetLy - cam.look[1]) * cam.lookaheadSpeed * dt;
+
+    const halfVisW = cam.visibleW * 0.5;
+    const halfVisH = cam.visibleH * 0.5;
+
+    const desiredX = px + cam.look[0] - halfVisW;
+    const desiredY = py + cam.look[1] - halfVisH;
+
+    if (desiredX < cam.target[0] - cam.deadzoneX)
+        cam.target[0] = desiredX + cam.deadzoneX;
+    else if (desiredX > cam.target[0] + cam.deadzoneX)
+        cam.target[0] = desiredX - cam.deadzoneX;
+
+    if (desiredY < cam.target[1] - cam.deadzoneY)
+        cam.target[1] = desiredY + cam.deadzoneY;
+    else if (desiredY > cam.target[1] + cam.deadzoneY)
+        cam.target[1] = desiredY - cam.deadzoneY;
+}
+
+/**
+ * LOCK — Camera snaps instantly to center on target.
+ * No deadzone, no lookahead, no lerp.
+ * Useful for: top-down shooters, fixed-camera moments.
+ */
+function lock(cam, dt, px, py, pvx, pvy) {
+    const halfVisW = cam.visibleW * 0.5;
+    const halfVisH = cam.visibleH * 0.5;
+
+    cam.target[0] = px - halfVisW;
+    cam.target[1] = py - halfVisH;
+
+    // Bypass lerp by also setting pos directly
+    cam.pos[0] = cam.target[0];
+    cam.pos[1] = cam.target[1];
+
+    // Zero out lookahead so switching modes doesn't jerk
+    cam.look[0] = 0;
+    cam.look[1] = 0;
+}
+
+/**
+ * PREDICTIVE — Aggressive lookahead using raw velocity extrapolation.
+ * Looks further ahead than SMOOTH, and scales with speed (not just direction).
+ * No deadzone — the camera actively chases the predicted position.
+ * Useful for: racing games, fast runners, bullet-hell dodge patterns.
+ *
+ * Uses cam.predictTime (seconds of extrapolation, default 0.3).
+ */
+function predictive(cam, dt, px, py, pvx, pvy) {
+    const predictTime = cam.predictTime || 0.3;
+
+    // Predicted position: where the player will be in `predictTime` seconds
+    const predX = px + pvx * predictTime;
+    const predY = py + pvy * predictTime;
+
+    const halfVisW = cam.visibleW * 0.5;
+    const halfVisH = cam.visibleH * 0.5;
+
+    // Lerp lookahead toward predicted offset (not normalized — scales with speed)
+    const targetLx = predX - px;
+    const targetLy = predY - py;
+    cam.look[0] += (targetLx - cam.look[0]) * cam.lookaheadSpeed * dt;
+    cam.look[1] += (targetLy - cam.look[1]) * cam.lookaheadSpeed * dt;
+
+    // No deadzone: camera directly tracks predicted center
+    cam.target[0] = px + cam.look[0] - halfVisW;
+    cam.target[1] = py + cam.look[1] - halfVisH;
+}
+
+/**
+ * CUT — Hard cut to center on target. Identical to LOCK but designed
+ * to be used as a one-frame mode switch for cutscene transitions.
+ * After the cut, you'd typically switch to SMOOTH or LOCK.
+ *
+ * Zero lerp, zero lookahead. Resets look vector.
+ */
+function cut(cam, dt, px, py, pvx, pvy) {
+    const halfVisW = cam.visibleW * 0.5;
+    const halfVisH = cam.visibleH * 0.5;
+
+    cam.target[0] = px - halfVisW;
+    cam.target[1] = py - halfVisH;
+    cam.pos[0]    = cam.target[0];
+    cam.pos[1]    = cam.target[1];
+
+    cam.look[0] = 0;
+    cam.look[1] = 0;
+}
+
+/**
+ * HYBRID — Smooth horizontal (with deadzone + lookahead), locked vertical.
+ * The platformer standard: horizontal feels cinematic, vertical is
+ * pixel-precise so platforms don't jitter.
+ *
+ * Uses cam.hybridVerticalSnap (default true) to control whether
+ * vertical uses instant snap or fast lerp.
+ */
+function hybrid(cam, dt, px, py, pvx, pvy) {
+    // ── Horizontal: full smooth behavior ──
+    const len = Math.sqrt(pvx * pvx + pvy * pvy);
+    const targetLx = len > 0 ? (pvx / len) * cam.lookaheadDist : 0;
+    cam.look[0] += (targetLx - cam.look[0]) * cam.lookaheadSpeed * dt;
+
+    const halfVisW = cam.visibleW * 0.5;
+    const halfVisH = cam.visibleH * 0.5;
+
+    const desiredX = px + cam.look[0] - halfVisW;
+
+    if (desiredX < cam.target[0] - cam.deadzoneX)
+        cam.target[0] = desiredX + cam.deadzoneX;
+    else if (desiredX > cam.target[0] + cam.deadzoneX)
+        cam.target[0] = desiredX - cam.deadzoneX;
+
+    // ── Vertical: locked (snap or fast lerp) ──
+    const desiredY = py - halfVisH;
+
+    if (cam.hybridVerticalSnap !== false) {
+        // Instant snap
+        cam.target[1] = desiredY;
+        cam.pos[1]    = desiredY;
+    } else {
+        // Fast lerp (3× normal speed)
+        cam.target[1] = desiredY;
+        cam.pos[1] += (cam.target[1] - cam.pos[1]) * cam.lerpSpeed * 3 * dt;
+    }
+
+    // Zero out vertical lookahead
+    cam.look[1] = 0;
+}
+
+/**
+ * Strategy lookup table. Indexed by FollowMode enum.
+ * @type {Function[]}
+ */
+export const FOLLOW_STRATEGIES = [
+    smooth,      // 0: SMOOTH
+    lock,        // 1: LOCK
+    predictive,  // 2: PREDICTIVE
+    cut,         // 3: CUT
+    hybrid,      // 4: HYBRID
+];
+
+export default FollowMode;

package/src/MultiTarget.js

@@ -0,0 +1,125 @@
+/**
+ * @zakkster/lite-camera-pro — Multi-Target Framing
+ *
+ * Calculates camera position and zoom to keep multiple targets visible.
+ * Zero allocations per frame — all state is pre-allocated on the camera.
+ *
+ * Used by boss fights, co-op, cutscenes tracking multiple actors.
+ *
+ * Depends on: @zakkster/lite-lerp (clamp)
+ */
+
+/**
+ * Compute the camera target position and zoom level that frames
+ * all targets with the specified padding.
+ *
+ * Mutates cam.target[], cam.zoom directly. Zero allocations.
+ *
+ * @param {CinematicCameraPro} cam       The camera instance
+ * @param {number}             dt        Delta time in seconds
+ * @param {{x:number,y:number}[]} targets  Array of target objects
+ * @param {number}             count     Number of active targets
+ */
+export function updateMultiTarget(cam, dt, targets, count) {
+    if (count === 0) return;
+
+    const mt = cam._mt;
+
+    // ── 1. Compute bounding box of all targets ──
+    let minX = targets[0].x;
+    let maxX = minX;
+    let minY = targets[0].y;
+    let maxY = minY;
+
+    for (let i = 1; i < count; i++) {
+        const tx = targets[i].x;
+        const ty = targets[i].y;
+        if (tx < minX) minX = tx;
+        if (tx > maxX) maxX = tx;
+        if (ty < minY) minY = ty;
+        if (ty > maxY) maxY = ty;
+    }
+
+    // ── 2. Center of the bounding box ──
+    const centerX = (minX + maxX) * 0.5;
+    const centerY = (minY + maxY) * 0.5;
+
+    // ── 3. Required world-space dimensions (with padding) ──
+    // Minimum bbox = viewport at maxZoom, prevents near-zero division
+    const minBBox = 100; // minimum world-space pixels to prevent extreme zoom
+    const bboxW = Math.max((maxX - minX) + mt.paddingX * 2, minBBox);
+    const bboxH = Math.max((maxY - minY) + mt.paddingY * 2, minBBox);
+
+    // ── 4. Compute zoom to fit bbox into viewport ──
+    const zoomX = cam.viewW / bboxW;
+    const zoomY = cam.viewH / bboxH;
+    let desiredZoom = Math.min(zoomX, zoomY);
+
+    // Clamp to camera limits
+    if (desiredZoom < cam.minZoom) desiredZoom = cam.minZoom;
+    if (desiredZoom > cam.maxZoom) desiredZoom = cam.maxZoom;
+    // Multi-target specific clamps (tighter range for framing)
+    if (desiredZoom < mt.minZoom) desiredZoom = mt.minZoom;
+    if (desiredZoom > mt.maxZoom) desiredZoom = mt.maxZoom;
+
+    // ── 5. Smooth zoom toward desired ──
+    // Exponential damping: cam.zoom approaches desiredZoom at mt.zoomSpeed rate
+    const zoomLerp = 1 - Math.exp(-mt.zoomSpeed * dt);
+    cam.zoom += (desiredZoom - cam.zoom) * zoomLerp;
+
+    // ── 6. Update visible dimensions after zoom change ──
+    cam.visibleW = cam.viewW / cam.zoom;
+    cam.visibleH = cam.viewH / cam.zoom;
+    cam._maxX = cam.worldW - cam.visibleW;
+    cam._maxY = cam.worldH - cam.visibleH;
+    if (cam._maxX < 0) cam._maxX = 0;
+    if (cam._maxY < 0) cam._maxY = 0;
+
+    // ── 7. Camera target = center of bbox, offset by half-visible ──
+    const desiredX = centerX - cam.visibleW * 0.5;
+    const desiredY = centerY - cam.visibleH * 0.5;
+
+    // Smooth position follow
+    const posLerp = 1 - Math.exp(-mt.followSpeed * dt);
+    cam.target[0] += (desiredX - cam.target[0]) * posLerp;
+    cam.target[1] += (desiredY - cam.target[1]) * posLerp;
+
+    // Zero out lookahead (multi-target doesn't use it)
+    cam.look[0] = 0;
+    cam.look[1] = 0;
+}
+
+/**
+ * Default multi-target configuration. Allocated once on the camera.
+ * All fields are mutable by the developer.
+ *
+ * @returns {Object} Config object stored as cam._mt
+ */
+export function createMultiTargetState() {
+    return {
+        /** Whether multi-target tracking is active */
+        active: false,
+
+        /** Array ref provided by developer (we never allocate a new one) */
+        targets: null,
+
+        /** Number of active targets (avoids .length access on sparse arrays) */
+        count: 0,
+
+        /** World-space padding around the bounding box (pixels) */
+        paddingX: 80,
+        paddingY: 80,
+
+        /** Zoom limits specific to multi-target framing */
+        minZoom: 0.3,
+        maxZoom: 2.0,
+
+        /** Zoom smoothing speed (higher = snappier). Uses exponential damping. */
+        zoomSpeed: 4.0,
+
+        /** Position follow speed. Uses exponential damping. */
+        followSpeed: 5.0,
+    };
+}
+
+export default updateMultiTarget;