@vgai/engine 0.2.0 → 0.3.0

package/dist/animation/gsap-registration.d.ts

@@ -0,0 +1,119 @@
+import type { SystemPhaseName } from '../core/types';
+import type { AnimationClock } from './animation-clock';
+/**
+ * D7 — register a native, paused GSAP timeline on the canonical
+ * `AnimationClock` (spec §10 D7, §5.5 GSAP Contract, §3.2).
+ *
+ * Mirrors `theatre-clock-binding.ts` (D2)'s shape: VGAI's entire GSAP
+ * integration is "who drives time". Games build GSAP timelines with GSAP's
+ * own native, un-renamed API (`gsap.timeline()`, `.to()`, `.from()`, …,
+ * spec §5.5) — this module never wraps or renames the tween-building API. It
+ * only stores the native `gsap.core.Timeline` and seeks it every time the
+ * clock moves, exactly like the Theatre sequence binding seeks
+ * `sequence.position`.
+ *
+ * ## Unregistered GSAP is unaffected (§5.5 contract)
+ *
+ * `gsap.to(enemy.position, { … })` called anywhere in game code — without
+ * ever touching this module — keeps running on GSAP's own real-time,
+ * `requestAnimationFrame`-driven global ticker exactly as GSAP ships it. This
+ * module does not touch `gsap.ticker`, `gsap.globalTimeline`, or any other
+ * global GSAP state, precisely so it cannot perturb that ordinary real-time
+ * code path. Only a timeline explicitly passed to `registerGsap` — and
+ * created paused — participates in deterministic scrub/export.
+ *
+ * ## Why a PAUSED timeline seeked with `.time()` is deterministic
+ *
+ * GSAP's global ticker only auto-advances animations that are actually
+ * playing; a timeline created with `{ paused: true }` (and never resumed) is
+ * never touched by the ticker's rAF-driven `dt` accumulation, so wall-clock
+ * elapsed time, dropped frames, and GSAP's lag-smoothing heuristics (which
+ * exist purely to compensate a *playing* animation for an irregular ticker
+ * `dt`) cannot affect it. The only thing that ever moves a registered
+ * timeline's playhead is this module's own `timeline.time(clock.time)` call,
+ * driven synchronously off the clock — same story as `theatre-clock-binding`
+ * driving `sequence.position` off the clock instead of Theatre's own raf
+ * loop. This is proven directly against the real `gsap` runtime in
+ * `packages/engine/test/gsap-registration.test.ts` (including a real
+ * wall-clock `setTimeout` wait between two `clock.seek()` calls to the same
+ * time, asserting the sampled value is bit-for-bit identical — nothing
+ * "polished" the value while real time passed). `timeline.time(value)` (not
+ * `.seek(value)`) is used because it takes only a numeric offset in the
+ * clock's own second-denominated domain — `.seek()`'s label-string overload
+ * is irrelevant here and would only widen the accepted input past what a
+ * clock time actually is. Neither call resumes playback; both simply
+ * position an already-paused timeline, which is why this module never calls
+ * `.play()`/`.resume()`.
+ *
+ * ## Phase choice
+ *
+ * Registered by default at the `'animation'` phase — the same phase
+ * `bindClockToTheatreSequence` (D2) uses, and the same phase
+ * XState-bound `AnimationMixer` playback ticks in (see `ARCHITECTURE.md`'s
+ * phase table). A registered GSAP timeline commonly targets the same
+ * Object3D/material properties a Theatre-driven object binding also writes,
+ * so keeping both in the `'animation'` phase (ahead of `'preRender'`, where
+ * camera/material reads happen) avoids ordering surprises.
+ */
+export interface GsapRegistrationOptions {
+    /** Which `AnimationClock` phase to seek the timeline in. Defaults to `'animation'`. */
+    phase?: SystemPhaseName;
+}
+export interface GsapRegistration {
+    /**
+     * Removes the clock evaluator and stops driving the timeline (no further
+     * `timeline.time(...)` calls occur after this). Also frees this
+     * clock+timeline pair for re-registration (see `GsapRegistrationError`'s
+     * `'duplicate'` case below).
+     */
+    dispose(): void;
+}
+/**
+ * Thrown by `registerGsap` when the input does not satisfy the D7 contract.
+ * `code` distinguishes the three rejection reasons so a caller can branch on
+ * it programmatically instead of string-matching `message`:
+ *
+ *  - `'not-a-timeline'` — the second argument is not a real
+ *    `gsap.core.Timeline` instance (e.g. a plain object, a single GSAP
+ *    `Tween`, or `undefined`). Checked with `instanceof gsap.core.Timeline`
+ *    against the actual installed GSAP runtime, not duck-typing, so a
+ *    same-shaped fake cannot slip through.
+ *  - `'not-paused'` — the timeline exists but was not created with
+ *    `{ paused: true }` (or was later resumed) at registration time. This
+ *    module deliberately REJECTS rather than silently force-pausing: a
+ *    caller who already relies on the timeline advancing in real time (e.g.
+ *    a UI polish tween that happens to also get registered by mistake) would
+ *    otherwise have its behavior silently changed. Rejecting makes the fix
+ *    (`gsap.timeline({ paused: true })`) obvious at the call site instead of
+ *    producing a hard-to-notice runtime pause.
+ *  - `'duplicate'` — this exact timeline is already registered against this
+ *    exact clock. Detected per `(clock, timeline)` pair (not globally), so
+ *    the same timeline may legitimately be registered against two
+ *    independent clocks/cinematic contexts — mirroring D2's "multiple
+ *    projects/sheets coexist" allowance — while registering it twice on the
+ *    SAME clock (almost always a bug: a duplicate `useEffect` run, a missed
+ *    disposer, …) is caught immediately instead of silently doubling the
+ *    number of `.time()` writes per crossing.
+ */
+export declare class GsapRegistrationError extends Error {
+    readonly code: 'not-a-timeline' | 'not-paused' | 'duplicate';
+    constructor(message: string, code: 'not-a-timeline' | 'not-paused' | 'duplicate');
+}
+/**
+ * Register a native, paused `gsap.core.Timeline` on `clock`: from now on,
+ * every clock crossing (`seek`, `advance`, idempotent re-seeks, `setRange`
+ * clamps — anything that fires a `ClockEvaluator`, per `animation-clock.ts`)
+ * positions the timeline at `clock.time` via `timeline.time(clock.time)`.
+ * The timeline is never played/resumed — it stays paused and is driven
+ * exclusively by the clock, both in live preview and in offline
+ * frame-by-frame export (whatever calls `clock.seek`/`clock.seekFrame`).
+ *
+ * Throws `GsapRegistrationError` if `timeline` is not a real
+ * `gsap.core.Timeline`, is not paused, or is already registered against this
+ * `clock` — see that class's doc comment for the exact policy on each case.
+ *
+ * Returns a `GsapRegistration` whose `dispose()` removes the clock evaluator
+ * (mirrors `bindClockToTheatreSequence`'s `TheatreClockBinding`).
+ */
+export declare function registerGsap(clock: AnimationClock, timeline: gsap.core.Timeline, options?: GsapRegistrationOptions): GsapRegistration;
+//# sourceMappingURL=gsap-registration.d.ts.map

package/dist/animation/gsap-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gsap-registration.d.ts","sourceRoot":"","sources":["../../src/animation/gsap-registration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,mBAAmB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,MAAM,WAAW,uBAAuB;IACtC,uFAAuF;IACvF,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAG5C,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,GAAG,WAAW;gBAD5D,OAAO,EAAE,MAAM,EACN,IAAI,EAAE,gBAAgB,GAAG,YAAY,GAAG,WAAW;CAK/D;AAQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAC5B,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CA6ClB"}

package/dist/animation/gsap-registration.js

@@ -0,0 +1,92 @@
+import gsap from 'gsap';
+/**
+ * Thrown by `registerGsap` when the input does not satisfy the D7 contract.
+ * `code` distinguishes the three rejection reasons so a caller can branch on
+ * it programmatically instead of string-matching `message`:
+ *
+ *  - `'not-a-timeline'` — the second argument is not a real
+ *    `gsap.core.Timeline` instance (e.g. a plain object, a single GSAP
+ *    `Tween`, or `undefined`). Checked with `instanceof gsap.core.Timeline`
+ *    against the actual installed GSAP runtime, not duck-typing, so a
+ *    same-shaped fake cannot slip through.
+ *  - `'not-paused'` — the timeline exists but was not created with
+ *    `{ paused: true }` (or was later resumed) at registration time. This
+ *    module deliberately REJECTS rather than silently force-pausing: a
+ *    caller who already relies on the timeline advancing in real time (e.g.
+ *    a UI polish tween that happens to also get registered by mistake) would
+ *    otherwise have its behavior silently changed. Rejecting makes the fix
+ *    (`gsap.timeline({ paused: true })`) obvious at the call site instead of
+ *    producing a hard-to-notice runtime pause.
+ *  - `'duplicate'` — this exact timeline is already registered against this
+ *    exact clock. Detected per `(clock, timeline)` pair (not globally), so
+ *    the same timeline may legitimately be registered against two
+ *    independent clocks/cinematic contexts — mirroring D2's "multiple
+ *    projects/sheets coexist" allowance — while registering it twice on the
+ *    SAME clock (almost always a bug: a duplicate `useEffect` run, a missed
+ *    disposer, …) is caught immediately instead of silently doubling the
+ *    number of `.time()` writes per crossing.
+ */
+export class GsapRegistrationError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'GsapRegistrationError';
+    }
+}
+// Per-clock membership of already-registered timelines. A WeakMap keyed by
+// clock (not a field on AnimationClock itself — D1 owns no knowledge of
+// GSAP) holding a WeakSet keyed by timeline, so neither the clock nor a
+// disposed/dropped timeline is kept alive by this module.
+const registeredByClock = new WeakMap();
+/**
+ * Register a native, paused `gsap.core.Timeline` on `clock`: from now on,
+ * every clock crossing (`seek`, `advance`, idempotent re-seeks, `setRange`
+ * clamps — anything that fires a `ClockEvaluator`, per `animation-clock.ts`)
+ * positions the timeline at `clock.time` via `timeline.time(clock.time)`.
+ * The timeline is never played/resumed — it stays paused and is driven
+ * exclusively by the clock, both in live preview and in offline
+ * frame-by-frame export (whatever calls `clock.seek`/`clock.seekFrame`).
+ *
+ * Throws `GsapRegistrationError` if `timeline` is not a real
+ * `gsap.core.Timeline`, is not paused, or is already registered against this
+ * `clock` — see that class's doc comment for the exact policy on each case.
+ *
+ * Returns a `GsapRegistration` whose `dispose()` removes the clock evaluator
+ * (mirrors `bindClockToTheatreSequence`'s `TheatreClockBinding`).
+ */
+export function registerGsap(clock, timeline, options = {}) {
+    if (!(timeline instanceof gsap.core.Timeline)) {
+        throw new GsapRegistrationError('[registerGsap] expected a native gsap.core.Timeline (e.g. gsap.timeline({ paused: true })), ' +
+            `got ${timeline === null ? 'null' : typeof timeline}`, 'not-a-timeline');
+    }
+    if (!timeline.paused()) {
+        throw new GsapRegistrationError('[registerGsap] timeline must be created paused — gsap.timeline({ paused: true }) — before ' +
+            'registration; a registered timeline is driven exclusively by the clock and must never also ' +
+            'be advancing under its own real-time playback', 'not-paused');
+    }
+    let seenForClock = registeredByClock.get(clock);
+    if (!seenForClock) {
+        seenForClock = new WeakSet();
+        registeredByClock.set(clock, seenForClock);
+    }
+    if (seenForClock.has(timeline)) {
+        throw new GsapRegistrationError('[registerGsap] this timeline is already registered against this clock — dispose() the prior ' +
+            'registration before registering it again', 'duplicate');
+    }
+    seenForClock.add(timeline);
+    const phase = options.phase ?? 'animation';
+    const handle = clock.subscribe(phase, () => {
+        timeline.time(clock.time);
+    });
+    let disposed = false;
+    return {
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            handle.dispose();
+            seenForClock.delete(timeline);
+        },
+    };
+}

package/dist/animation/theatre-clock-binding.d.ts

@@ -0,0 +1,89 @@
+import type { ISequence } from '@theatre/core';
+import type { SystemPhaseName } from '../core/types';
+import type { AnimationClock } from './animation-clock';
+/**
+ * D2 — bind the canonical `AnimationClock` to a Theatre sequence's playhead
+ * (spec §10 D2, §5.3, §3.2).
+ *
+ * This is VGAI's ENTIRE glue for Theatre integration on the clock side:
+ * games import and configure `@theatre/core` with its own native vocabulary
+ * (`getProject`/`types`/`sheet`/`object`, spec §5.3) — there is no renamed
+ * Theatre API here. The only thing VGAI owns is *who drives time*: the
+ * canonical clock is the single source of truth, and this binding seeks
+ * Theatre's sequence position to match it every time the clock moves. Theatre
+ * must never be left to drive its own `requestAnimationFrame` loop — see the
+ * module doc on `animation-clock.ts` for why (deterministic export, offline
+ * scrubbing, no wall-clock dependency).
+ *
+ * ## Why setting `sequence.position` is enough (no `sequence.play()`)
+ *
+ * Theatre's `ISequence.position` setter synchronously updates every bound
+ * `SheetObject`'s pull-based `.value` (proven against the real `@theatre/core`
+ * runtime in `packages/engine/test/theatre-binding.test.ts` — setting
+ * `position` and immediately reading `.value` reflects the new keyframe
+ * interpolation with no `requestAnimationFrame`/ticker wait, which is exactly
+ * what makes this safe to drive from a synchronous, wall-clock-free
+ * `AnimationClock.seek()`/`advance()` call, including headlessly in Node for
+ * the render/export seam, I2). Theatre's *push* notification channel
+ * (`onValuesChange`/`onChange`) is batched on its own internal raf-driven
+ * ticker — it is not delivered 1:1 with each programmatic `position` write,
+ * so a subscriber can observe several coalesced position writes as a single
+ * notification, or (in a headless/no-raf context) none at all — so object
+ * bindings (`theatre-object-binding.ts`) deliberately read `sheetObject.value`
+ * (pull) after this binding has run, rather than subscribing to Theatre's
+ * push channel, to stay exactly in lockstep with the clock.
+ *
+ * ## Phase choice
+ *
+ * Note on phase semantics: `phase` here orders evaluators WITHIN a single
+ * clock `emit()` — i.e. within one `seek()`/`advance()` call — using the
+ * engine's `SystemPhaseName` vocabulary purely as a shared, familiar naming
+ * convention (`animation-clock.ts`'s module doc). It does NOT mean an
+ * evaluator registered at, say, `'preRender'` executes during the live
+ * engine's own `system-runner` `preRender` phase call within a running RAF
+ * frame — the `AnimationClock` is independent of the live game loop's phase
+ * execution, and during offline export/scrub there is no RAF frame at all.
+ * `phase` only orders same-emit evaluators relative to each other (e.g.
+ * guaranteeing this clock-to-sequence binding runs before an object binding
+ * reads the sequence on the same crossing), never relative to unrelated
+ * engine systems that happen to run in a same-named phase during a live
+ * frame.
+ *
+ * Registered by default at the `'animation'` phase — the same phase
+ * XState-bound `AnimationMixer` playback ticks in (see `ARCHITECTURE.md`'s
+ * phase table: `... gameLogic → animation → preRender → render`). Object
+ * bindings (`bindObject3DTransform`/`bindCameraLens`) default to `'preRender'`
+ * (the documented home for camera placement/material tick) specifically so
+ * `PHASE_ORDER` — not registration order — guarantees they observe the
+ * position this binding just set, regardless of which binding a caller sets
+ * up first.
+ */
+export interface TheatreClockBindingOptions {
+    /**
+     * Which `AnimationClock` phase to seek the sequence in. Defaults to
+     * `'animation'`. Any object binding reading this sheet's objects should use
+     * a phase that runs no earlier (see module doc above) — `'preRender'`, the
+     * default for `bindObject3DTransform`/`bindCameraLens`, always qualifies.
+     */
+    phase?: SystemPhaseName;
+}
+export interface TheatreClockBinding {
+    /** Removes the clock evaluator. No further `sequence.position` writes occur after this. */
+    dispose(): void;
+}
+/**
+ * Subscribe `sequence.position = clock.time` to every crossing of `clock` in
+ * the given phase (default `'animation'`). Returns a disposer; call it to
+ * stop driving the sequence (e.g. on `GameCleanup.dispose()` or before
+ * rebinding on hot reload — this is what keeps HMR from accumulating
+ * duplicate listeners, since re-running `setup()` disposes the old binding
+ * before creating a new one).
+ *
+ * Multiple sheets/sequences can each get their own binding with no shared
+ * mutable state on VGAI's side — collision avoidance for the underlying
+ * Theatre project/sheet identity is Theatre's own `getProject(id)`/
+ * `project.sheet(id)` namespacing (spec §5.3), which this function does not
+ * touch or wrap.
+ */
+export declare function bindClockToTheatreSequence(clock: AnimationClock, sequence: ISequence, options?: TheatreClockBindingOptions): TheatreClockBinding;
+//# sourceMappingURL=theatre-clock-binding.d.ts.map

package/dist/animation/theatre-clock-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theatre-clock-binding.d.ts","sourceRoot":"","sources":["../../src/animation/theatre-clock-binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,mBAAmB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,2FAA2F;IAC3F,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,SAAS,EACnB,OAAO,GAAE,0BAA+B,GACvC,mBAAmB,CAerB"}

package/dist/animation/theatre-clock-binding.js

@@ -0,0 +1,29 @@
+/**
+ * Subscribe `sequence.position = clock.time` to every crossing of `clock` in
+ * the given phase (default `'animation'`). Returns a disposer; call it to
+ * stop driving the sequence (e.g. on `GameCleanup.dispose()` or before
+ * rebinding on hot reload — this is what keeps HMR from accumulating
+ * duplicate listeners, since re-running `setup()` disposes the old binding
+ * before creating a new one).
+ *
+ * Multiple sheets/sequences can each get their own binding with no shared
+ * mutable state on VGAI's side — collision avoidance for the underlying
+ * Theatre project/sheet identity is Theatre's own `getProject(id)`/
+ * `project.sheet(id)` namespacing (spec §5.3), which this function does not
+ * touch or wrap.
+ */
+export function bindClockToTheatreSequence(clock, sequence, options = {}) {
+    const phase = options.phase ?? 'animation';
+    const handle = clock.subscribe(phase, () => {
+        sequence.position = clock.time;
+    });
+    let disposed = false;
+    return {
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            handle.dispose();
+        },
+    };
+}

package/dist/animation/theatre-director.d.ts

@@ -0,0 +1,242 @@
+import type { ISheetObject, UnknownShorthandCompoundProps } from '@theatre/core';
+import type { SystemPhaseName } from '../core/types';
+import type { AnimationClock } from './animation-clock';
+/**
+ * D4 — the Theatre "Director" convention (spec §10 D4, §5.3, §3.2).
+ *
+ * A `Director` is an ordinary Theatre Sheet Object, authored with Theatre's
+ * NATIVE `types.stringLiteral`/`types.boolean` vocabulary exactly as shown in
+ * spec §5.3 — this module never wraps or renames that API. It is a
+ * *convention* (a documented, stable shape) plus a thin binding, not a new
+ * animation format:
+ *
+ * ```ts
+ * import { types } from '@theatre/core';
+ * const director = sheet.object('Director', {
+ *   activeCamera: types.stringLiteral('wide', { wide: 'wide', close: 'close', gameplay: 'gameplay' }),
+ *   shot: types.stringLiteral('opening', { opening: 'opening', reveal: 'reveal', ending: 'ending' }),
+ *   letterbox: types.boolean(false),
+ *   // extensible: any additional directorial prop is carried through verbatim
+ *   // as `DirectorState.extras`, e.g.:
+ *   blendSeconds: types.number(0, { range: [0, Infinity] }),
+ * });
+ * ```
+ *
+ * `activeCamera`/`shot`/`letterbox` are required by the convention (spec §10
+ * D4 AC: "covers active camera, shot ID, letterbox, and optional directorial
+ * properties"). Anything else declared on the same Theatre object (exposure,
+ * grade, a blend-duration prop, ...) is an "optional directorial property" —
+ * it is read and surfaced verbatim through `DirectorState.extras`, never
+ * hardcoded here, which is what keeps the convention extensible without
+ * VGAI inventing a schema for it.
+ *
+ * ## Binding: pull-based, same lockstep pattern as D2/D3
+ *
+ * `bindDirectorToClock` follows exactly the `theatre-clock-binding.ts` /
+ * `theatre-object-binding.ts` pattern: it reads the Director object's
+ * pull-based `sheetObject.value` on every canonical-clock crossing (never
+ * Theatre's own batched `onValuesChange` push channel — see those modules'
+ * doc comments for why that would desync from a synchronous `clock.seek()`).
+ * Default phase is `'preRender'`, the same default `bindObject3DTransform`/
+ * `bindCameraLens` use, so — via `PHASE_ORDER`, not registration order — the
+ * Director always reads a sequence position that `bindClockToTheatreSequence`
+ * (registered at `'animation'`, which runs earlier) has already set for this
+ * crossing, regardless of which binding a caller sets up first.
+ *
+ * ## Seeking updates Director without firing gameplay cues
+ *
+ * This binding has NO concept of "seek" vs "advance" — unlike
+ * `CueRunner` (D5, `cinematic-cues.ts`), which deliberately distinguishes the
+ * two (via its own `seek()`/`advance()` wrapper methods) so a
+ * `firesDuringSeek: false` cue can be skipped on scrub. A Director value is
+ * *visual/directorial state*, not a gameplay consequence (spec §3.2: "Theatre
+ * carries visual/directorial values; ordinary TypeScript cues carry gameplay
+ * consequences") — it should always reflect the clock's current time,
+ * however the clock got there. Composing the two on the SAME
+ * `AnimationClock` (Director bound directly to the clock; cues bound through
+ * a `CueRunner` wrapping the same clock) is exactly what makes "seek updates
+ * Director but does not spuriously fire gameplay cues" fall out for free: a
+ * `CueRunner.seek(t)` call moves the one shared clock, which both this
+ * binding (always reacts) and the cue runner (gates on `firesDuringSeek`)
+ * observe on the same crossing. See `theatre-director.test.ts`'s
+ * "composes with D5" suite for the proof.
+ *
+ * ## Camera-ownership hook — the D6 seam
+ *
+ * Discrete `activeCamera` changes are exactly the moments a *camera
+ * ownership* system (D6, not built in this unit) needs to know about, to cut
+ * or blend the live gameplay camera to the Director's declared shot. This
+ * module does not own or perform any camera mutation — it only DETECTS a
+ * change in the Director's `activeCamera` value across successive
+ * evaluations and reports it through `onActiveCameraChange`
+ * (`CameraOwnershipHook`), a minimal, one-directional seam:
+ *
+ *  - fired once per detected `activeCamera` transition (never for a
+ *    no-op/unchanged evaluation, including a re-seek to the same time or a
+ *    seek that stays within the same shot's camera);
+ *  - the FIRST evaluation after bind is treated as an "assignment", not a
+ *    "cut from something" — `previousCameraKey` is `null` and `mode` is
+ *    forced to `'cut'` (there is nothing to blend FROM yet; D6 is expected
+ *    to use this event to perform its initial camera capture/placement);
+ *  - `mode`/`blendSeconds` are derived from an optional extra numeric prop on
+ *    the SAME Director object (`blendSecondsKey`, default `'blendSeconds'`)
+ *    — a positive value at the moment of the transition means `'blend'`
+ *    (with that duration), anything else means `'cut'`. This is the "expose
+ *    enough for a consumer to cut or blend" seam named in the D4 AC; the
+ *    ACTUAL blend implementation (interpolating the live camera pose over
+ *    `blendSeconds`) is D6's job, not this module's.
+ *
+ * ### `blendSeconds` MUST be authored as HOLD keyframes
+ *
+ * `blendSeconds` is read at the EXACT moment `activeCamera` is detected to
+ * change, whatever clock time that happens to land on. If `blendSeconds` is
+ * authored as an ordinary interpolating (bezier) track, a transition
+ * detected at a time that isn't exactly a keyframe position reads whatever
+ * partially-interpolated value the bezier curve has reached AT THAT MOMENT —
+ * not the value actually authored FOR that transition. Concretely: a cut
+ * authored at `t=3` with `blendSeconds=0`, followed by a blend authored at
+ * `t=6` with `blendSeconds=1.5`, makes the track interpolate from `0` to
+ * `1.5` across `[3, 6)`. If the `activeCamera` transition at `t=3` is first
+ * *observed* at some later non-keyframe time inside that span (e.g. a coarse
+ * seek from `t=2` straight to `t=4.5`, skipping past `t=3` without an
+ * intermediate evaluation), `blendSeconds` at `t=4.5` reads a nonzero,
+ * partially-interpolated value — misreporting an authored CUT as a partial
+ * BLEND.
+ *
+ * The fix is to author `blendSeconds` keyframes as Theatre HOLD keyframes
+ * (`connectedRight: false`, optionally also `type: 'hold'`) rather than the
+ * default interpolating bezier keyframes. `connectedRight: false` makes
+ * Theatre's own sequence evaluator hold the LEFT keyframe's value constant
+ * across the entire span up to (not including) the next keyframe, then snap
+ * — never partially interpolate. With `blendSeconds` authored this way, its
+ * value at ANY time within `[3, 6)` reads exactly `0` (the cut authored at
+ * `t=3`), and only reads `1.5` once the clock reaches `t=6` (the blend
+ * authored there) — correct regardless of which non-keyframe time a
+ * transition happens to first be observed at. See
+ * `fixtures/theatre-director-proof.theatre-project.json` (its `blendSeconds`
+ * track uses `connectedRight: false` on every keyframe) and
+ * `theatre-director.test.ts`'s "playback grid" suite, which proves this by
+ * evaluating a fine-grained, non-keyframe-aligned time grid across the whole
+ * span and asserting the reported `mode` never drifts from what was
+ * authored at the keyframe that produced the transition.
+ *
+ * D6 will most likely implement `CameraOwnershipHook` as (roughly) "capture
+ * gameplay camera pose once on the first `mode: 'cut'` event; on each
+ * subsequent event, cut or blend the owned camera to the shot named by
+ * `cameraKey`". Nothing above depends on that implementation existing —
+ * `onActiveCameraChange` is optional and this module works with no hook
+ * attached at all (Director values are still readable via `getState()`).
+ *
+ * ## Read API (SDK/CLI seam, B5)
+ *
+ * `readDirectorState` is a pure, synchronous read of whatever a Director
+ * Theatre object's CURRENT value is — no clock/binding required. It is what
+ * a later `cinematic.*` SDK/CLI operation (B5) would call to inspect Director
+ * state (e.g. "what shot is authored at time t") without needing to spin up
+ * a full runtime binding. `TheatreDirectorBinding.getState()` is the
+ * clock-driven equivalent — it returns the value read at bind time until the
+ * FIRST clock crossing occurs (not "the most recent crossing" — before any
+ * crossing there IS no crossing yet), and the value as of the most recent
+ * crossing thereafter.
+ *
+ * Authoring `Director` keyframes in Theatre Studio is a dev-only workflow
+ * (spec §10 D2: "Theatre Studio is available only in authoring/development
+ * contexts"); the committed project-state JSON is the source of truth this
+ * module reads in production — nothing here imports the Theatre Studio
+ * package (see `theatre-binding.test.ts`'s repo-wide grep proof of that).
+ */
+/** Thrown when a Theatre object does not conform to the Director convention. */
+export declare class TheatreDirectorError extends Error {
+    readonly objectKey: string;
+    constructor(message: string, objectKey: string);
+}
+/** The Director convention's three required props, plus everything else verbatim. */
+export interface DirectorState {
+    readonly activeCamera: string;
+    readonly shot: string;
+    readonly letterbox: boolean;
+    /**
+     * Any additional directorial props declared on the same Theatre object
+     * (e.g. `exposure`, `grade`, `blendSeconds`), captured verbatim from
+     * `sheetObject.value`. The Director convention is deliberately extensible
+     * here — VGAI does not enumerate or validate extras beyond the three
+     * required props.
+     */
+    readonly extras: Readonly<Record<string, unknown>>;
+}
+/**
+ * Pure, synchronous read of a Director Theatre object's CURRENT value.
+ * No clock/binding involved — suitable for one-shot inspection (the later
+ * SDK/CLI read path, B5) as well as being the function
+ * `bindDirectorToClock` itself calls on every crossing.
+ *
+ * @throws {TheatreDirectorError} if the object's value does not conform to
+ *   the Director convention (missing/mistyped `activeCamera`/`shot`/`letterbox`).
+ */
+export declare function readDirectorState<Props extends UnknownShorthandCompoundProps>(sheetObject: ISheetObject<Props>): DirectorState;
+/** Whether a reported `activeCamera` transition should be a hard cut or a blend. */
+export type CameraCutMode = 'cut' | 'blend';
+/**
+ * One detected `activeCamera` transition. This is the entire payload the
+ * D6 camera-ownership system needs to decide what to do — it carries no
+ * camera object or mutation itself (that stays entirely on the consumer's
+ * side, matching "no arbitrary unsafe property-path evaluator" / "thin
+ * integration code" throughout D2-D5).
+ */
+export interface CameraOwnershipChangeEvent {
+    /** The Director's new `activeCamera` value. */
+    readonly cameraKey: string;
+    /** The Director's previous `activeCamera` value, or `null` on the first (assignment) event. */
+    readonly previousCameraKey: string | null;
+    /** `'cut'` unless a positive blend duration was authored for this transition. */
+    readonly mode: CameraCutMode;
+    /** Blend duration in seconds; `0` for a `'cut'`. */
+    readonly blendSeconds: number;
+    /** The Director's `shot` value at the moment of this transition, for convenience. */
+    readonly shot: string;
+}
+/**
+ * D6 seam: implemented fully by the camera-ownership/restoration system
+ * (spec §10 D6). This module only detects and reports discrete
+ * `activeCamera` transitions — it performs no camera capture, cut, blend, or
+ * restoration itself.
+ */
+export type CameraOwnershipHook = (event: CameraOwnershipChangeEvent) => void;
+export interface TheatreDirectorBindingOptions {
+    /**
+     * Which `AnimationClock` phase to evaluate the Director in. Defaults to
+     * `'preRender'` (see module doc — guaranteed by `PHASE_ORDER` to observe a
+     * sequence position `bindClockToTheatreSequence`'s `'animation'`-phase
+     * default has already set for this crossing).
+     */
+    phase?: SystemPhaseName;
+    /** Camera-ownership seam (D6) — see module doc. Optional; omit to just read state. */
+    onActiveCameraChange?: CameraOwnershipHook;
+    /**
+     * Name of an optional extra numeric Director prop that carries the blend
+     * duration (seconds) for the transition landing on the CURRENT
+     * evaluation. Defaults to `'blendSeconds'`. Absent, non-numeric, or
+     * non-positive at the moment of a transition reports `mode: 'cut'`.
+     */
+    blendSecondsKey?: string;
+}
+export interface TheatreDirectorBinding {
+    /**
+     * Current Director state (D4 AC: inspectable read API). Before the first
+     * clock crossing, this is the bind-time value (`readDirectorState` called
+     * once at bind); from the first crossing onward, it is the value as of the
+     * most recent crossing.
+     */
+    getState(): DirectorState;
+    /** Removes the clock evaluator. No further evaluation (or hook calls) occurs after this. */
+    dispose(): void;
+}
+/**
+ * Bind a Director Theatre Sheet Object to `clock`: on every crossing, read
+ * its current value (`readDirectorState`) and, if `activeCamera` changed
+ * since the last evaluation, report the transition through
+ * `onActiveCameraChange` (the D6 seam). Returns a disposer and a `getState()`
+ * read API. See the module doc comment for the full contract.
+ */
+export declare function bindDirectorToClock<Props extends UnknownShorthandCompoundProps>(clock: AnimationClock, sheetObject: ISheetObject<Props>, options?: TheatreDirectorBindingOptions): TheatreDirectorBinding;
+//# sourceMappingURL=theatre-director.d.ts.map

package/dist/animation/theatre-director.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theatre-director.d.ts","sourceRoot":"","sources":["../../src/animation/theatre-director.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,mBAAmB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+IG;AAEH,gFAAgF;AAChF,qBAAa,oBAAqB,SAAQ,KAAK;IAG3C,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAD1B,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,MAAM;CAK7B;AAED,qFAAqF;AACrF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AAID;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,6BAA6B,EAC3E,WAAW,EAAE,YAAY,CAAC,KAAK,CAAC,GAC/B,aAAa,CAqCf;AAED,oFAAoF;AACpF,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,OAAO,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+FAA+F;IAC/F,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;AAE9E,MAAM,WAAW,6BAA6B;IAC5C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,sFAAsF;IACtF,oBAAoB,CAAC,EAAE,mBAAmB,CAAC;IAC3C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,QAAQ,IAAI,aAAa,CAAC;IAC1B,4FAA4F;IAC5F,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,6BAA6B,EAC7E,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,YAAY,CAAC,KAAK,CAAC,EAChC,OAAO,GAAE,6BAAkC,GAC1C,sBAAsB,CA8CxB"}