@vgai/engine 0.5.5 → 0.5.7

package/dist/animation/cubic-spline-interpolant.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The glTF CUBICSPLINE interpolant, and the factory that installs it on a
+ * `KeyframeTrack`.
+ *
+ * `GLTFLoader` has both of these and exports NEITHER — `GLTFCubicSplineInterpolant`
+ * and `_createCubicSplineTrackInterpolant` are module-private. Anything that
+ * builds a CUBICSPLINE track without going through a GLB parse therefore has
+ * to supply them, and the D25 migration does exactly that: it bakes Theatre's
+ * bezier easing into tangent triples, and a track carrying triples without the
+ * interpolant reads as three times as many components and plays garbage.
+ *
+ * The flag is also load-bearing on the way OUT. `GLTFExporter` decides a track
+ * is CUBICSPLINE by testing `isInterpolantFactoryMethodGLTFCubicSpline` and
+ * nothing else (`GLTFExporter.js:2252`), so a baked track without it exports
+ * as LINEAR over tangent triples — silently wrong. Installing it is what makes
+ * a converted clip round-trip through the industry format instead of needing
+ * one of ours.
+ *
+ * This is a port of Three's own algorithm, not an abstraction over it — the
+ * math below is theirs, kept deliberately line-comparable to
+ * `GLTFLoader.js`'s `GLTFCubicSplineInterpolant.interpolate_` so a future
+ * upstream fix is a readable diff. It exists because of a missing export, and
+ * should be deleted the day Three publishes one.
+ *
+ * Layout, which is the whole reason this is subtle:
+ *
+ *   [ inTangent_1, splineVertex_1, outTangent_1, inTangent_2, splineVertex_2, … ]
+ *
+ * so `track.getValueSize()` reports 3x the component count and
+ * `track.getInterpolation()` returns undefined (Three's enum cannot name a
+ * custom interpolant). The `isInterpolantFactoryMethodGLTFCubicSpline` flag on
+ * the factory is the only marker, and it is what the editor's authoring
+ * projection keys off — see `three-animation-authoring.ts`'s `trackLayout`.
+ */
+import * as THREE from 'three';
+/** Hermite evaluation over glTF's `[inTangent, vertex, outTangent]` triples. */
+export declare class CubicSplineInterpolant extends THREE.Interpolant {
+    copySampleValue_(index: number): Float32Array | number[];
+    interpolate_(i1: number, t0: number, t: number, t1: number): Float32Array | number[];
+}
+/** Quaternion tracks renormalize after the Hermite blend, as glTF requires. */
+export declare class CubicSplineQuaternionInterpolant extends CubicSplineInterpolant {
+    interpolate_(i1: number, t0: number, t: number, t1: number): Float32Array | number[];
+}
+/**
+ * Install the CUBICSPLINE interpolant on a track whose values are tangent
+ * triples — byte-identical in effect to what `GLTFLoader` does to a track it
+ * parses from a GLB, so a track from an authored file and a track from a GLB
+ * are indistinguishable downstream.
+ */
+export declare function installCubicSplineInterpolant(track: THREE.KeyframeTrack): THREE.KeyframeTrack;
+/** True when `track` carries glTF tangent triples rather than plain values. */
+export declare function isCubicSplineTrack(track: THREE.KeyframeTrack): boolean;
+//# sourceMappingURL=cubic-spline-interpolant.d.ts.map

package/dist/animation/cubic-spline-interpolant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cubic-spline-interpolant.d.ts","sourceRoot":"","sources":["../../src/animation/cubic-spline-interpolant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,gFAAgF;AAChF,qBAAa,sBAAuB,SAAQ,KAAK,CAAC,WAAW;IAC3D,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,MAAM,EAAE;IAYxD,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,MAAM,EAAE;CA8BrF;AAID,+EAA+E;AAC/E,qBAAa,gCAAiC,SAAQ,sBAAsB;IACjE,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,MAAM,EAAE;CAQ9F;AAQD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAe7F;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,aAAa,GAAG,OAAO,CAItE"}

package/dist/animation/cubic-spline-interpolant.js

@@ -0,0 +1,111 @@
+/**
+ * The glTF CUBICSPLINE interpolant, and the factory that installs it on a
+ * `KeyframeTrack`.
+ *
+ * `GLTFLoader` has both of these and exports NEITHER — `GLTFCubicSplineInterpolant`
+ * and `_createCubicSplineTrackInterpolant` are module-private. Anything that
+ * builds a CUBICSPLINE track without going through a GLB parse therefore has
+ * to supply them, and the D25 migration does exactly that: it bakes Theatre's
+ * bezier easing into tangent triples, and a track carrying triples without the
+ * interpolant reads as three times as many components and plays garbage.
+ *
+ * The flag is also load-bearing on the way OUT. `GLTFExporter` decides a track
+ * is CUBICSPLINE by testing `isInterpolantFactoryMethodGLTFCubicSpline` and
+ * nothing else (`GLTFExporter.js:2252`), so a baked track without it exports
+ * as LINEAR over tangent triples — silently wrong. Installing it is what makes
+ * a converted clip round-trip through the industry format instead of needing
+ * one of ours.
+ *
+ * This is a port of Three's own algorithm, not an abstraction over it — the
+ * math below is theirs, kept deliberately line-comparable to
+ * `GLTFLoader.js`'s `GLTFCubicSplineInterpolant.interpolate_` so a future
+ * upstream fix is a readable diff. It exists because of a missing export, and
+ * should be deleted the day Three publishes one.
+ *
+ * Layout, which is the whole reason this is subtle:
+ *
+ *   [ inTangent_1, splineVertex_1, outTangent_1, inTangent_2, splineVertex_2, … ]
+ *
+ * so `track.getValueSize()` reports 3x the component count and
+ * `track.getInterpolation()` returns undefined (Three's enum cannot name a
+ * custom interpolant). The `isInterpolantFactoryMethodGLTFCubicSpline` flag on
+ * the factory is the only marker, and it is what the editor's authoring
+ * projection keys off — see `three-animation-authoring.ts`'s `trackLayout`.
+ */
+import * as THREE from 'three';
+/** Hermite evaluation over glTF's `[inTangent, vertex, outTangent]` triples. */
+export class CubicSplineInterpolant extends THREE.Interpolant {
+    copySampleValue_(index) {
+        const result = this.resultBuffer;
+        const values = this.sampleValues;
+        const valueSize = this.valueSize;
+        // The VERTEX sits one component-stride into its triple.
+        const offset = index * valueSize * 3 + valueSize;
+        for (let i = 0; i !== valueSize; i++)
+            result[i] = values[offset + i];
+        return result;
+    }
+    // Not `override`: Three's published typings do not declare `interpolate_`,
+    // though every built-in interpolant implements it.
+    interpolate_(i1, t0, t, t1) {
+        const result = this.resultBuffer;
+        const values = this.sampleValues;
+        const stride = this.valueSize;
+        const stride2 = stride * 2;
+        const stride3 = stride * 3;
+        const td = t1 - t0;
+        const p = (t - t0) / td;
+        const pp = p * p;
+        const ppp = pp * p;
+        const offset1 = i1 * stride3;
+        const offset0 = offset1 - stride3;
+        const s2 = -2 * ppp + 3 * pp;
+        const s3 = ppp - pp;
+        const s0 = 1 - s2;
+        const s1 = s3 - pp + p;
+        for (let i = 0; i !== stride; i++) {
+            const p0 = values[offset0 + i + stride]; // splineVertex_k
+            const m0 = values[offset0 + i + stride2] * td; // outTangent_k · Δt
+            const p1 = values[offset1 + i + stride]; // splineVertex_k+1
+            const m1 = values[offset1 + i] * td; // inTangent_k+1 · Δt
+            result[i] = s0 * p0 + s1 * m0 + s2 * p1 + s3 * m1;
+        }
+        return result;
+    }
+}
+const _quaternion = new THREE.Quaternion();
+/** Quaternion tracks renormalize after the Hermite blend, as glTF requires. */
+export class CubicSplineQuaternionInterpolant extends CubicSplineInterpolant {
+    interpolate_(i1, t0, t, t1) {
+        const result = super.interpolate_(i1, t0, t, t1);
+        _quaternion
+            .fromArray(result)
+            .normalize()
+            .toArray(result);
+        return result;
+    }
+}
+/**
+ * Install the CUBICSPLINE interpolant on a track whose values are tangent
+ * triples — byte-identical in effect to what `GLTFLoader` does to a track it
+ * parses from a GLB, so a track from an authored file and a track from a GLB
+ * are indistinguishable downstream.
+ */
+export function installCubicSplineInterpolant(track) {
+    const factory = function InterpolantFactoryMethodGLTFCubicSpline(result) {
+        const Interpolant = this instanceof THREE.QuaternionKeyframeTrack
+            ? CubicSplineQuaternionInterpolant
+            : CubicSplineInterpolant;
+        // getValueSize() counts the whole triple; the interpolant wants components.
+        return new Interpolant(this.times, this.values, this.getValueSize() / 3, result);
+    };
+    factory.isInterpolantFactoryMethodGLTFCubicSpline = true;
+    track.createInterpolant = factory;
+    return track;
+}
+/** True when `track` carries glTF tangent triples rather than plain values. */
+export function isCubicSplineTrack(track) {
+    const factory = track
+        .createInterpolant;
+    return factory?.isInterpolantFactoryMethodGLTFCubicSpline === true;
+}

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 (the 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,277 @@
+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;
+/**
+ * WF — one detected event-marker transition on the Director's `event` extra
+ * track (authored by the editor's Sequencer as HOLD string keyframes on the
+ * SAME Director object; see the sequencer's `EVENT_MARKER_PROP`).
+ */
+export interface EventMarkerEvent {
+    /** The marker name now active (the hold keyframe's string value). */
+    readonly name: string;
+    /** The previously active marker name, or `null` before the first marker. */
+    readonly previousName: string | null;
+}
+/**
+ * WF seam — fired once per DETECTED change of the Director's event-marker
+ * value, exactly the `activeCamera` detection semantics: markers are
+ * *directorial* state, so the hook reflects whatever value the clock's
+ * current time holds, however the clock got there (a seek across several
+ * markers fires only the one now active; a seek BACK re-fires the older
+ * marker as a change). Gameplay consequences that must distinguish seek from
+ * advance belong in a D5 `CueRunner` (`cinematic-cues.ts`), not here.
+ */
+export type EventMarkerHook = (event: EventMarkerEvent) => 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;
+    /**
+     * WF seam — event-marker hook (see {@link EventMarkerHook}). Fired when
+     * the string value of the Director's `eventMarkerKey` extra prop changes
+     * between evaluations (markers are authored as HOLD keyframes, so each
+     * marker's name holds until the next one). Optional; omit to ignore
+     * markers entirely.
+     */
+    onEventMarker?: EventMarkerHook;
+    /**
+     * Name of the extra Director prop carrying event-marker names. Defaults to
+     * `'event'` — the track the editor's Sequencer writes. An empty string or
+     * a non-string value means "no marker active".
+     */
+    eventMarkerKey?: 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;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAEhE,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;IACzB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,eAAe,CAAC;IAChC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;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,CA2DxB"}