@vgai/engine 0.5.5 → 0.5.6

package/dist/animation/animation-clock.js

@@ -0,0 +1,301 @@
+import { PHASE_ORDER } from '../core/types';
+const EPSILON = 1e-9;
+// Bails a pathological single `advance(dt)` call out of lap-by-lap interval
+// enumeration (e.g. an absurd `dt` at max time scale over a tiny loop range)
+// so a single call can never spin unboundedly. Real fixed-step `dt`s never
+// approach this.
+const MAX_LAPS_PER_ADVANCE = 100_000;
+/** Advance `p0` forward by `distance` (>= 0) within `range`, honoring loop/clamp. */
+function sweepForward(p0, distance, range) {
+    const length = range.end - range.start;
+    const canLoop = range.loop && length > EPSILON;
+    const intervals = [];
+    let pos = p0;
+    let remaining = distance;
+    let looped = false;
+    let laps = 0;
+    for (;;) {
+        const distToEnd = range.end - pos;
+        if (!canLoop || remaining <= distToEnd + EPSILON) {
+            // Always clamp to range.end here, even when canLoop is true: this
+            // terminal branch is reached whenever `remaining` is within EPSILON of
+            // `distToEnd` (not just when it's exactly equal), so `pos + remaining`
+            // can overshoot `range.end` by up to EPSILON on a loop range. Clamping
+            // unconditionally (D1 follow-up, spec §10 D5) keeps `clock.time` from
+            // ever exceeding `range.end`, which in turn keeps the NEXT advance()'s
+            // `distToEnd` non-negative and prevents a degenerate `from > to`
+            // interval on the following call.
+            const to = Math.min(pos + remaining, range.end);
+            intervals.push({ from: pos, to, direction: 'forward' });
+            pos = to;
+            break;
+        }
+        intervals.push({ from: pos, to: range.end, direction: 'forward' });
+        remaining -= distToEnd;
+        pos = range.start;
+        looped = true;
+        laps++;
+        if (laps > MAX_LAPS_PER_ADVANCE) {
+            const wrapped = range.start + (remaining % length);
+            intervals.push({ from: pos, to: wrapped, direction: 'forward' });
+            pos = wrapped;
+            break;
+        }
+    }
+    return { pos, intervals, looped };
+}
+/** Advance `p0` backward by `distance` (>= 0) within `range`, honoring loop/clamp. */
+function sweepReverse(p0, distance, range) {
+    const length = range.end - range.start;
+    const canLoop = range.loop && length > EPSILON;
+    const intervals = [];
+    let pos = p0;
+    let remaining = distance;
+    let looped = false;
+    let laps = 0;
+    for (;;) {
+        const distToStart = pos - range.start;
+        if (!canLoop || remaining <= distToStart + EPSILON) {
+            // Mirror of the forward-sweep clamp above: always clamp to
+            // range.start here so a reverse advance() cannot undershoot it by up
+            // to EPSILON on a loop range (D1 follow-up, spec §10 D5).
+            const to = Math.max(pos - remaining, range.start);
+            intervals.push({ from: pos, to, direction: 'reverse' });
+            pos = to;
+            break;
+        }
+        intervals.push({ from: pos, to: range.start, direction: 'reverse' });
+        remaining -= distToStart;
+        pos = range.end;
+        looped = true;
+        laps++;
+        if (laps > MAX_LAPS_PER_ADVANCE) {
+            const wrapped = range.end - (remaining % length);
+            intervals.push({ from: pos, to: wrapped, direction: 'reverse' });
+            pos = wrapped;
+            break;
+        }
+    }
+    return { pos, intervals, looped };
+}
+function clampToRange(t, range) {
+    if (t < range.start)
+        return range.start;
+    if (t > range.end)
+        return range.end;
+    return t;
+}
+/**
+ * The engine-owned canonical clock. See the module doc comment above for
+ * the design constraints this implementation is bound by.
+ */
+export class AnimationClock {
+    _previousTime;
+    _currentTime;
+    _range;
+    _timeScale;
+    _playDirection = 'forward';
+    _lastCrossingDirection = 'forward';
+    _playbackState = 'stopped';
+    _evaluators = [];
+    _registrationCounter = 0;
+    constructor(options = {}) {
+        const start = options.start ?? 0;
+        const end = options.end ?? Math.max(start, 1);
+        if (end < start) {
+            throw new Error(`[AnimationClock] range end (${end}) must be >= start (${start})`);
+        }
+        const timeScale = options.timeScale ?? 1;
+        if (!Number.isFinite(timeScale) || timeScale < 0) {
+            throw new Error(`[AnimationClock] timeScale must be a finite number >= 0, got ${timeScale}`);
+        }
+        this._range = { start, end, loop: options.loop ?? false };
+        this._timeScale = timeScale;
+        this._previousTime = start;
+        this._currentTime = start;
+    }
+    /** Current playhead time, in seconds. */
+    get time() {
+        return this._currentTime;
+    }
+    /** Playhead time immediately before the most recent seek/advance. */
+    get previousTime() {
+        return this._previousTime;
+    }
+    /**
+     * Playback direction. `'paused'` whenever `playbackState !== 'playing'`
+     * (covers both `pause()` and `stop()`) — matches the spec's literal
+     * `direction: forward | reverse | paused` acceptance criterion. The
+     * underlying intended direction is preserved across pause/resume; see
+     * `play()`.
+     */
+    get direction() {
+        return this._playbackState === 'playing' ? this._playDirection : 'paused';
+    }
+    get playbackState() {
+        return this._playbackState;
+    }
+    get timeScale() {
+        return this._timeScale;
+    }
+    set timeScale(value) {
+        if (!Number.isFinite(value) || value < 0) {
+            throw new Error(`[AnimationClock] timeScale must be a finite number >= 0, got ${value}`);
+        }
+        this._timeScale = value;
+    }
+    get range() {
+        return this._range;
+    }
+    /**
+     * Update loop/range metadata. The current playhead is clamped into the
+     * new range if necessary (reported as an ordinary crossing — same
+     * evaluator path as `seek`/`advance` — so subscribers observe it).
+     */
+    setRange(next) {
+        const start = next.start ?? this._range.start;
+        const end = next.end ?? this._range.end;
+        const loop = next.loop ?? this._range.loop;
+        if (end < start) {
+            throw new Error(`[AnimationClock] range end (${end}) must be >= start (${start})`);
+        }
+        this._range = { start, end, loop };
+        const clamped = clampToRange(this._currentTime, this._range);
+        if (clamped !== this._currentTime) {
+            this.seek(clamped);
+        }
+    }
+    /**
+     * Begin/resume playback. `direction` sets (or re-asserts) the intended
+     * playback direction for subsequent `advance()` calls; omit it to resume
+     * in whatever direction was last set (default `'forward'` the first time).
+     */
+    play(direction) {
+        if (direction)
+            this._playDirection = direction;
+        this._playbackState = 'playing';
+    }
+    /** Halt playback at the current position. `advance()` becomes a no-op. */
+    pause() {
+        this._playbackState = 'paused';
+    }
+    /**
+     * Halt playback at the current position (distinct from `pause()` only in
+     * reported `playbackState`; this unit does not prescribe a reset-to-start
+     * policy — that is a cinematic-controller/render-seam decision, D5/I2).
+     * `advance()` is a no-op in this state, same as `paused`.
+     */
+    stop() {
+        this._playbackState = 'stopped';
+    }
+    /**
+     * Jump directly to `t` (clamped into `range`). Idempotent: calling
+     * `seek(t)` twice in a row leaves `time`/`previousTime` identical to
+     * calling it once — the second call is a true no-op (no state mutation,
+     * though evaluators still fire so a subscriber can rely on `seek` always
+     * producing a crossing for e.g. re-asserting visual state).
+     */
+    seek(t) {
+        const target = clampToRange(t, this._range);
+        if (target === this._currentTime) {
+            return this.emit(this._currentTime, this._currentTime, [{ from: target, to: target, direction: this._lastCrossingDirection }], false, this._lastCrossingDirection);
+        }
+        const direction = target > this._currentTime ? 'forward' : 'reverse';
+        const prev = this._currentTime;
+        this._previousTime = prev;
+        this._currentTime = target;
+        this._lastCrossingDirection = direction;
+        return this.emit(prev, target, [{ from: prev, to: target, direction }], false, direction);
+    }
+    /**
+     * Frame-index seek for export (D1 AC): seeks to EXACTLY `range.start +
+     * n / fps`, computed fresh from `n`/`fps` on every call. This is what
+     * keeps a rendered frame sequence drift-free — unlike repeatedly calling
+     * `advance(1 / fps)` `n` times (which accumulates float error), this
+     * always derives the same exact double for a given `(n, fps)` pair no
+     * matter what the clock's prior state was.
+     */
+    seekFrame(n, fps) {
+        if (!Number.isFinite(fps) || fps <= 0) {
+            throw new Error(`[AnimationClock] seekFrame fps must be a finite number > 0, got ${fps}`);
+        }
+        return this.seek(this._range.start + n / fps);
+    }
+    /**
+     * Fixed-step advance by `dt` seconds (magnitude; sign of movement comes
+     * from `direction`/`play()`, not from `dt`'s sign). A no-op whenever
+     * `playbackState !== 'playing'` — this is what makes `advance()` do
+     * nothing while paused (D1 AC). Returns `null` for that no-op case;
+     * otherwise returns the resulting crossing (which may span multiple loop
+     * laps if `dt * timeScale` exceeds the range length).
+     */
+    advance(dt) {
+        if (this._playbackState !== 'playing')
+            return null;
+        if (!Number.isFinite(dt)) {
+            throw new Error(`[AnimationClock] advance(dt) requires a finite dt, got ${dt}`);
+        }
+        const magnitude = Math.abs(dt) * this._timeScale;
+        const p0 = this._currentTime;
+        if (magnitude === 0) {
+            return this.emit(p0, p0, [], false, this._playDirection);
+        }
+        const result = this._playDirection === 'forward'
+            ? sweepForward(p0, magnitude, this._range)
+            : sweepReverse(p0, magnitude, this._range);
+        this._previousTime = p0;
+        this._currentTime = result.pos;
+        this._lastCrossingDirection = this._playDirection;
+        return this.emit(p0, result.pos, result.intervals, result.looped, this._playDirection);
+    }
+    /**
+     * Register an evaluator against a phase from the engine's own
+     * `SystemPhaseName` vocabulary (`core/types.ts`). Evaluators fire on
+     * every `seek()`/`advance()` (including idempotent no-op seeks and
+     * `setRange` clamps) in `PHASE_ORDER` order, then registration order
+     * within a phase — the same "deterministic phase order" every other
+     * engine system is invoked in, so a Theatre binding, a registered-GSAP
+     * seek, and a cue evaluator can each declare their phase and compose
+     * without inventing a second ordering rule.
+     */
+    subscribe(phase, evaluator) {
+        if (!PHASE_ORDER.includes(phase)) {
+            throw new Error(`[AnimationClock] unknown phase "${phase}". Valid: ${PHASE_ORDER.join(', ')}`);
+        }
+        const entry = { phase, order: this._registrationCounter++, fn: evaluator };
+        this._evaluators.push(entry);
+        return {
+            dispose: () => {
+                const idx = this._evaluators.indexOf(entry);
+                if (idx !== -1)
+                    this._evaluators.splice(idx, 1);
+            },
+        };
+    }
+    emit(previousTime, currentTime, intervals, looped, direction) {
+        const crossing = {
+            previousTime,
+            currentTime,
+            direction,
+            timeScale: this._timeScale,
+            looped,
+            intervals,
+        };
+        if (this._evaluators.length > 0) {
+            const ordered = [...this._evaluators].sort((a, b) => {
+                const pa = PHASE_ORDER.indexOf(a.phase);
+                const pb = PHASE_ORDER.indexOf(b.phase);
+                return pa !== pb ? pa - pb : a.order - b.order;
+            });
+            for (const entry of ordered) {
+                try {
+                    entry.fn(crossing);
+                }
+                catch (err) {
+                    console.error(`[AnimationClock] evaluator in phase "${entry.phase}" threw:`, err);
+                }
+            }
+        }
+        return crossing;
+    }
+}

package/dist/animation/blend-node.d.ts

@@ -0,0 +1,22 @@
+import type { BlendTreeDef } from './anim-graph-types';
+/**
+ * Evaluates a blend tree and returns weights for each child clip.
+ *
+ * 1D blend: interpolates between sorted blend points based on a single parameter.
+ *   Example: speed=3 with children at [walk:1, run:5] → weights [0.5, 0.5]
+ *
+ * 2D blend: uses two parameters (e.g., strafe locomotion). Weights are computed by
+ *   inverse-distance weighting (IDW): each child's weight is proportional to
+ *   1/distance from the (parameter, parameterY) sample point to that child's
+ *   (threshold, thresholdY) position, then normalized so all weights sum to 1.
+ *   A sample landing exactly on a child gives that child ~full weight. This is a
+ *   smooth approximation, not a Delaunay/barycentric blend (so non-adjacent
+ *   children still receive a small share); it is intentionally kept simple.
+ *
+ * Direct: each child has an explicit weight.
+ */
+export declare function evaluateBlendTree(def: BlendTreeDef, parameters: Map<string, number | boolean>): {
+    clip: string;
+    weight: number;
+}[];
+//# sourceMappingURL=blend-node.d.ts.map

package/dist/animation/blend-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blend-node.d.ts","sourceRoot":"","sources":["../../src/animation/blend-node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GACxC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,CAWpC"}

package/dist/animation/blend-node.js

@@ -0,0 +1,97 @@
+/**
+ * Evaluates a blend tree and returns weights for each child clip.
+ *
+ * 1D blend: interpolates between sorted blend points based on a single parameter.
+ *   Example: speed=3 with children at [walk:1, run:5] → weights [0.5, 0.5]
+ *
+ * 2D blend: uses two parameters (e.g., strafe locomotion). Weights are computed by
+ *   inverse-distance weighting (IDW): each child's weight is proportional to
+ *   1/distance from the (parameter, parameterY) sample point to that child's
+ *   (threshold, thresholdY) position, then normalized so all weights sum to 1.
+ *   A sample landing exactly on a child gives that child ~full weight. This is a
+ *   smooth approximation, not a Delaunay/barycentric blend (so non-adjacent
+ *   children still receive a small share); it is intentionally kept simple.
+ *
+ * Direct: each child has an explicit weight.
+ */
+export function evaluateBlendTree(def, parameters) {
+    switch (def.type) {
+        case '1D':
+            return evaluate1D(def, parameters);
+        case '2D':
+            return evaluate2D(def, parameters);
+        case 'direct':
+            return evaluateDirect(def);
+        default:
+            return def.children.map((c) => ({ clip: c.clip, weight: 1 / def.children.length }));
+    }
+}
+function evaluate1D(def, parameters) {
+    const paramValue = Number(parameters.get(def.parameter) ?? 0);
+    const children = [...def.children].sort((a, b) => a.threshold - b.threshold);
+    const results = children.map((c) => ({ clip: c.clip, weight: 0 }));
+    if (children.length === 0)
+        return results;
+    if (children.length === 1) {
+        results[0].weight = 1;
+        return results;
+    }
+    // Below first threshold
+    if (paramValue <= children[0].threshold) {
+        results[0].weight = 1;
+        return results;
+    }
+    // Above last threshold
+    if (paramValue >= children[children.length - 1].threshold) {
+        results[results.length - 1].weight = 1;
+        return results;
+    }
+    // Between two thresholds — linear interpolation
+    for (let i = 0; i < children.length - 1; i++) {
+        const lo = children[i];
+        const hi = children[i + 1];
+        if (paramValue >= lo.threshold && paramValue <= hi.threshold) {
+            const range = hi.threshold - lo.threshold;
+            const t = range > 0 ? (paramValue - lo.threshold) / range : 0;
+            results[i].weight = 1 - t;
+            results[i + 1].weight = t;
+            return results;
+        }
+    }
+    return results;
+}
+function evaluate2D(def, parameters) {
+    const px = Number(parameters.get(def.parameter) ?? 0);
+    const py = Number(parameters.get(def.parameterY ?? '') ?? 0);
+    // Inverse-distance weighting: weight each child by 1/distance to its 2D point,
+    // then normalize below so the returned weights sum to 1.
+    const children = def.children;
+    const results = children.map((c) => ({ clip: c.clip, weight: 0 }));
+    let totalInvDist = 0;
+    const invDists = [];
+    for (const child of children) {
+        const dx = px - child.threshold;
+        const dy = py - (child.thresholdY ?? 0);
+        const dist = Math.sqrt(dx * dx + dy * dy);
+        const invDist = dist < 0.001 ? 1000 : 1 / dist;
+        invDists.push(invDist);
+        totalInvDist += invDist;
+    }
+    if (totalInvDist > 0) {
+        for (let i = 0; i < results.length; i++) {
+            results[i].weight = invDists[i] / totalInvDist;
+        }
+    }
+    return results;
+}
+function evaluateDirect(def) {
+    const results = def.children.map((c) => ({ clip: c.clip, weight: c.weight ?? 0 }));
+    // Normalize so weights sum to exactly 1.0 — otherwise the leftover weight
+    // bleeds in the bind pose / T-pose (the actions add up to <1 or >1).
+    const total = results.reduce((sum, r) => sum + r.weight, 0);
+    if (total > 0) {
+        for (const r of results)
+            r.weight /= total;
+    }
+    return results;
+}

package/dist/animation/camera-ownership.d.ts

@@ -0,0 +1,249 @@
+import * as THREE from 'three';
+import type { SystemPhaseName } from '../core/types';
+import type { AnimationClock } from './animation-clock';
+import type { CameraOwnershipChangeEvent } from './theatre-director';
+/**
+ * D6 — Camera Ownership and Restoration (spec §10 D6, §3.2, §4).
+ *
+ * VGAI owns exactly one thing here: WHO is allowed to move the live,
+ * actually-rendered camera at any given moment, and what happens to it when
+ * that control is released. The actual camera math (cuts, blends, lens
+ * changes, orbit/follow/look-at/dolly behavior) is expressed entirely with
+ * native `THREE.PerspectiveCamera` objects — Object3D-as-truth, no camera
+ * wrapper (spec §4, the "world node IS the entity" rule). This module reads and writes real Three.js camera properties
+ * (`position`, `quaternion`, `fov`, `near`, `far`) and nothing else.
+ *
+ * ## Two cooperating pieces
+ *
+ *  - `cameras`: a fixed registry of named SOURCE cameras (`cameraKey ->
+ *    THREE.PerspectiveCamera`), each an ordinary Object3D that ANY other
+ *    system may drive however it likes — a Theatre binding
+ *    (`bindObject3DTransform`/`bindCameraLens`, D3), a hand-written orbit/
+ *    follow/spline-dolly update, or a one-shot `camera.lookAt(target)` call.
+ *    This module never mutates a source camera; it only READS its current
+ *    pose at evaluation time.
+ *  - `liveCamera`: the ONE camera actually rendered. This module is the only
+ *    thing that writes to it while a cinematic owns it. Whatever ordinary
+ *    game code drives `liveCamera` the rest of the time (gameplay's own
+ *    orbit/follow controller, typically) is untouched and resumes writing to
+ *    it the moment ownership returns to "nobody" (the stack is empty).
+ *
+ * ## Ownership stack (LIFO) — the D6 nested/interrupted-cinematics rule
+ *
+ * `take(ownerId)` pushes a new ownership FRAME, capturing `liveCamera`'s
+ * CURRENT pose as that frame's `restorePose` — i.e. "whatever the camera
+ * looked like the instant this owner took over" (gameplay's pose for the
+ * first/outermost `take`, or the parent cinematic's current pose for a
+ * NESTED `take` while a parent is still on the stack). Only the TOP frame
+ * may drive the camera (`cut`/`blend`/`applyDirectorEvent`/`release` all
+ * throw `CameraOwnershipError` if `ownerId` is not the current top) — this
+ * is what makes nested ownership resolve deterministically: a second
+ * cinematic taking the camera while a first one owns it must explicitly
+ * `take()` (pushing on top) before it can drive anything, and must
+ * `release()` (popping) before the frame beneath it can drive anything
+ * again. There is no "steal without taking" path.
+ *
+ * `release(ownerId, { completed })` pops the top frame (throws if `ownerId`
+ * is not on top — the LIFO rule) and applies that frame's declared
+ * `CameraRestorePolicy` to `liveCamera` IMMEDIATELY:
+ *
+ *  - `'restore'` (default): `liveCamera` is set back to the frame's captured
+ *    `restorePose` — bit-exact, no interpolation.
+ *  - `'retain'`: `liveCamera` is left exactly as the cinematic last set it
+ *    (the cinematic's end pose).
+ *  - `'retain-if-completed'`: `'retain'` if `completed: true` was passed,
+ *    `'restore'` otherwise. This is the policy a cinematic controller (not
+ *    built in this unit — spec §3.2 names it as a future seam) would use to
+ *    express "keep the final shot if the cinematic played to its natural
+ *    end, but snap back to gameplay if it was skipped/cancelled".
+ *
+ * If a PARENT frame remains after the pop, it is NOT forcibly re-applied —
+ * the parent's own tracking/blending state (whatever it last was) simply
+ * resumes driving `liveCamera` on the next clock crossing, same as it always
+ * would. Concretely: "B stops → ownership returns to A's state" means
+ * `liveCamera` is snapped to A's captured pose the instant B releases, and
+ * then continues to be driven by A's own last `cut`/`blend` target (if any)
+ * on subsequent crossings — exactly as if B had never interrupted A. If A's
+ * target camera is static (not itself being animated), the snapped pose and
+ * the resumed-tracking pose are identical, which is what the test suite
+ * exercises for determinism.
+ *
+ * `dispose()` is the "render cleanup" path (D6 AC: "render cleanup restore
+ * or retain state according to the declared policy"): every still-open
+ * frame is released LIFO, per ITS OWN declared policy, with `completed:
+ * false` (a teardown is never a natural completion — `retain-if-completed`
+ * frames restore on cleanup, exactly like a cancel).
+ *
+ * ## Cut vs. blend — consuming the D4 `CameraOwnershipHook` seam
+ *
+ * `theatre-director.ts` (D4) detects discrete `activeCamera` transitions and
+ * reports them through `CameraOwnershipHook` — a `CameraOwnershipChangeEvent`
+ * carrying `cameraKey`/`mode`/`blendSeconds`, nothing else. This module's
+ * `applyDirectorEvent(ownerId, event)` is the entire consumption of that
+ * seam: it forwards `event.cameraKey`/`event.blendSeconds` into the same
+ * `cut`/`blend` logic a caller could invoke directly. The wiring is ordinary
+ * caller-side composition (same pattern D4/D5 already use to compose on one
+ * shared clock — see `theatre-director.test.ts`'s "composes with D5" suite):
+ *
+ * ```ts
+ * const ownership = createCameraOwnershipSystem({ liveCamera, cameras, clock });
+ * ownership.take('intro-cinematic');
+ * const directorBinding = bindDirectorToClock(clock, director, {
+ *   onActiveCameraChange: (event) => ownership.applyDirectorEvent('intro-cinematic', event),
+ * });
+ * // ...cinematic plays...
+ * ownership.release('intro-cinematic', { completed: true });
+ * directorBinding.dispose();
+ * ```
+ *
+ * The Director's FIRST event per bind is always `mode: 'cut'`
+ * (`previousCameraKey: null` — an "assignment", per the D4 module doc) —
+ * consumed exactly like any other cut, which is what performs the
+ * cinematic's INITIAL camera capture/placement onto its opening shot. A
+ * `take()` before binding the Director is required so the pre-cinematic
+ * gameplay pose is captured before that first cut lands.
+ *
+ * ## One unified transition model — cut is just a zero-duration blend
+ *
+ * Internally, `cut`/`blend`/`applyDirectorEvent` all record exactly one
+ * `FrameState` shape: `{ targetKey, fromPose, startTime, durationSeconds }`
+ * (`durationSeconds` is `0` for a cut). On EVERY clock crossing, the applied
+ * pose is a PURE function of `clock.time` and this fixed record — nothing is
+ * mutated as time passes:
+ *
+ * ```
+ * t = durationSeconds <= 0 ? 1 : clamp((clock.time - startTime) / durationSeconds, 0, 1)
+ * appliedPose = t >= 1 ? currentPoseOf(targetKey) : lerp(fromPose, currentPoseOf(targetKey), t)
+ * ```
+ *
+ * `currentPoseOf(targetKey)` is re-sampled LIVE every crossing (never a
+ * frozen snapshot), so blending onto — or having already cut to — a moving/
+ * Theatre-animated source camera tracks it correctly both mid-blend and
+ * after the blend window has fully elapsed. `fromPose` IS a fixed snapshot,
+ * taken once at the moment the transition begins (`capturePose(liveCamera)`
+ * — "wherever the camera currently is"); `t` clamps to `0` for any
+ * `clock.time` before `startTime` (holds `fromPose`) and to `1` at/after
+ * `startTime + durationSeconds` (holds the target's live current pose) —
+ * the same clamp-to-domain-boundary convention `AnimationClock` itself uses.
+ *
+ * Because nothing here depends on evaluation HISTORY (no state flips from
+ * "blending" to "tracking" as time passes — a cut IS just `durationSeconds:
+ * 0`, permanently, until the next `cut`/`blend` call replaces the record),
+ * a blend is fully deterministic under arbitrary re-seek: seeking forward
+ * past the blend end and then BACK into the blend window reproduces the
+ * exact same interpolated pose, not whatever the live target happened to be
+ * doing after the blend completed. See `camera-ownership.test.ts`'s
+ * "deterministic under re-seek" case.
+ *
+ * ## Phase choice: 'render', deliberately later than D3's 'preRender'
+ *
+ * `bindObject3DTransform`/`bindCameraLens` (D3) and `bindDirectorToClock`
+ * (D4) both default to the `'preRender'` phase. This module's own clock
+ * evaluator defaults to `'render'` — the LAST phase in `PHASE_ORDER` —
+ * specifically so `PHASE_ORDER` itself (not registration order) guarantees
+ * every registered source camera has already received its per-crossing
+ * pose update, and the Director has already fired any `applyDirectorEvent`
+ * for this crossing, before this module samples `cameras[key]` or resolves
+ * a pending transition. This is the same reasoning `theatre-director.ts`'s
+ * module doc gives for its own phase default relative to
+ * `bindClockToTheatreSequence`'s `'animation'` phase.
+ *
+ * ## Camera behaviors — what's tested vs. merely expressible
+ *
+ * Because a "source camera" is an ordinary `THREE.PerspectiveCamera` sampled
+ * fresh every crossing, ANY procedural code that mutates one earlier in
+ * `PHASE_ORDER` (or synchronously before a direct `cut`/`blend` call) is
+ * picked up automatically — this module does not special-case which
+ * mechanism produced the pose:
+ *
+ *  - **cuts, blends, FOV, near/far** — implemented and tested directly in
+ *    this module (`camera-ownership.test.ts`).
+ *  - **look-at** — tested: a source camera's orientation is set with
+ *    ordinary `camera.lookAt(target)` before a crossing; this module reads
+ *    the resulting `quaternion` like any other pose.
+ *  - **follow** — tested: a source camera's `position` is updated by
+ *    ordinary per-crossing application code (simulating a follow
+ *    controller); `currentPoseOf` re-samples it live every crossing, so the
+ *    live camera visibly follows.
+ *  - **orbit, spline-dolly** — EXPRESSIBLE via the identical mechanism
+ *    (ordinary code moves a registered source camera's `position`/
+ *    `quaternion` every crossing/frame — an orbit controller stepping an
+ *    angle, a spline sampler stepping arc-length) but not independently
+ *    tested in this unit; the follow test proves the general "procedurally
+ *    driven source camera, resampled live" path they would use.
+ */
+/** Restore-vs-retain policy applied when an ownership frame is released. */
+export type CameraRestorePolicy = 'restore' | 'retain' | 'retain-if-completed';
+/** A fully-captured camera pose: position, orientation, and lens. */
+export interface CameraPose {
+    readonly position: THREE.Vector3;
+    readonly quaternion: THREE.Quaternion;
+    readonly fov: number;
+    readonly near: number;
+    readonly far: number;
+}
+/** Thrown on an ownership-stack rule violation (not-current-owner, unknown camera key, duplicate take). */
+export declare class CameraOwnershipError extends Error {
+    readonly ownerId: string;
+    constructor(message: string, ownerId: string);
+}
+/** Snapshot a camera's full pose (position/quaternion cloned — never aliases the live object). */
+export declare function capturePose(camera: THREE.PerspectiveCamera): CameraPose;
+/** Write a captured pose onto a camera, updating its projection matrix. */
+export declare function applyPose(camera: THREE.PerspectiveCamera, pose: CameraPose): void;
+/** Position LERP + quaternion SLERP + fov/near/far LERP, `t` in `[0, 1]`. */
+export declare function lerpPose(from: CameraPose, to: CameraPose, t: number): CameraPose;
+export interface CameraOwnershipTakeOptions {
+    /** Restore policy for this frame. Defaults to the system's `defaultPolicy` (itself default `'restore'`). */
+    policy?: CameraRestorePolicy;
+}
+export interface CameraOwnershipReleaseOptions {
+    /**
+     * Whether the cinematic reached its natural end (vs. stop/skip/cancel).
+     * Only meaningful for a frame taken with `policy: 'retain-if-completed'`.
+     * Default `false`.
+     */
+    completed?: boolean;
+}
+export interface CameraOwnershipSystemOptions {
+    /** The camera actually rendered. Mutated in place by this system; untouched by it while the ownership stack is empty. */
+    liveCamera: THREE.PerspectiveCamera;
+    /**
+     * `cameraKey -> source camera` registry. Each value is an ordinary
+     * `THREE.PerspectiveCamera` that other code (Theatre bindings, orbit/
+     * follow/dolly controllers, `lookAt`) is free to drive; this module only
+     * reads its pose.
+     */
+    cameras: Readonly<Record<string, THREE.PerspectiveCamera>>;
+    /** The canonical clock driving deterministic, time-based blends. */
+    clock: AnimationClock;
+    /** Default `CameraRestorePolicy` for `take()` calls that don't specify one. Default `'restore'`. */
+    defaultPolicy?: CameraRestorePolicy;
+    /** `AnimationClock` phase to evaluate tracking/blending in. Default `'render'` — see module doc. */
+    phase?: SystemPhaseName;
+}
+export interface CameraOwnershipSystem {
+    /** Push a new ownership frame for `ownerId`, capturing `liveCamera`'s current pose as its restore point. Throws if `ownerId` is already on the stack. */
+    take(ownerId: string, options?: CameraOwnershipTakeOptions): void;
+    /** Hard-cut the live camera to `cameraKey`'s current pose. `ownerId` must be the current (top-of-stack) owner. */
+    cut(ownerId: string, cameraKey: string): void;
+    /** Begin a deterministic, clock-driven blend to `cameraKey` over `blendSeconds`. `ownerId` must be the current owner. */
+    blend(ownerId: string, cameraKey: string, blendSeconds: number): void;
+    /** Consume a D4 `CameraOwnershipChangeEvent` directly — cuts or blends per `event.mode`/`event.blendSeconds`. */
+    applyDirectorEvent(ownerId: string, event: CameraOwnershipChangeEvent): void;
+    /** Pop the top frame for `ownerId` (must be the current owner) and apply its declared restore policy. */
+    release(ownerId: string, options?: CameraOwnershipReleaseOptions): void;
+    /** Whether `ownerId` currently owns the camera (is top of stack). */
+    isOwner(ownerId: string): boolean;
+    /** Current ownership-stack depth. `0` means gameplay (nobody) owns the camera. */
+    readonly depth: number;
+    /** Render-cleanup path: releases every open frame LIFO per its own policy (`completed: false`), then unsubscribes. */
+    dispose(): void;
+}
+/**
+ * Build a camera-ownership system bound to `clock`. See the module doc
+ * comment for the full ownership-stack, cut/blend, and restore-policy
+ * contract.
+ */
+export declare function createCameraOwnershipSystem(options: CameraOwnershipSystemOptions): CameraOwnershipSystem;
+//# sourceMappingURL=camera-ownership.d.ts.map