@vgai/engine 0.2.0 → 0.3.0

package/src/animation/cinematic-cues.ts

@@ -0,0 +1,451 @@
+import type { SystemPhaseName } from '../core/types';
+import type {
+  AnimationClock,
+  ClockCrossing,
+  ClockEvaluatorHandle,
+  ClockInterval,
+} from './animation-clock';
+
+/**
+ * D5 — Cinematic Cues (spec §10 D5, §5.4, §3.2).
+ *
+ * `CinematicCue` is the deliberately small VGAI semantic for "gameplay
+ * consequences of cinematic time" (spec §3.2: "Theatre carries
+ * visual/directorial values; ordinary TypeScript cues carry gameplay
+ * consequences"). Cues live ALONGSIDE Theatre (`theatre-clock-binding.ts`,
+ * D2) — both are driven by the same canonical `AnimationClock`, but a cue
+ * is ordinary TypeScript with a `run`/`reverse` function, never a second
+ * property-animation format and never serialized executable code into
+ * Theatre state (spec §5.4).
+ *
+ * ## Fire-once, built on the clock's half-open interval convention
+ *
+ * The clock documents (see `ClockInterval` in `animation-clock.ts`) that a
+ * time `t` is CROSSED by a forward interval iff `t > from && t <= to`, and
+ * by a reverse interval iff `t < from && t >= to`. This module uses exactly
+ * that test (`crossesForward`/`crossesReverse` below) and nothing else to
+ * decide "did this crossing sweep past cue.time" — never a naive comparison
+ * of `previousTime`/`currentTime`, which is ambiguous across a loop wrap
+ * (one `ClockCrossing` can carry 2+ intervals, one per lap segment; see the
+ * clock's loop-wrap tests). Because a repeated `seek()` to the same time
+ * re-asserts a ZERO-LENGTH interval (`from === to`), and the half-open test
+ * never matches a zero-length interval, a cue naturally does not re-fire on
+ * a repeated seek to the same `t` with no extra bookkeeping required.
+ *
+ * ## Sticky fire-once state + explicit re-arm ("resetsOnLoop"/"restart")
+ *
+ * Beyond that per-crossing test, each cue additionally tracks whether it
+ * has EVER fired forward/reverse ("sticky" state, `CueState` below). Once
+ * fired, a cue does not fire again from ordinary play/seek traffic — this
+ * is what makes a one-shot story beat like `spawn-enemy` safe to scrub
+ * across repeatedly in an editor without re-triggering. Two things
+ * explicitly re-arm (clear) that sticky state:
+ *
+ *  - a loop-wrapping crossing (`crossing.looped === true`, which — per the
+ *    clock's own contract — only `advance()` can ever produce; `seek()`
+ *    always reports `looped: false`) re-arms only cues with
+ *    `resetsOnLoop: true`, once per lap boundary actually swept (so a
+ *    single giant multi-lap `advance()` correctly re-fires a per-lap cue
+ *    once per lap, not just once for the whole call);
+ *  - `CueRunner.reset()` unconditionally re-arms EVERY cue — this is the
+ *    "restart" policy: the intended call when a cinematic explicitly
+ *    restarts from the top and cues should be able to replay.
+ *
+ * ## Seek vs. play ("firesDuringSeek")
+ *
+ * `AnimationClock.seek()` and `AnimationClock.advance()` both funnel
+ * through the same `ClockCrossing` shape — the clock does not itself tag a
+ * crossing with which method produced it (that distinction is deliberately
+ * NOT added to the D1 clock; see the D1 follow-up note in
+ * `animation-clock.ts`, which stays scoped to the epsilon-clamp fix only).
+ * This module makes the distinction its own responsibility: drive the clock
+ * through `CueRunner.seek(t)` / `CueRunner.advance(dt)` (not
+ * `clock.seek`/`clock.advance` directly) and the runner tags the resulting
+ * crossing with its true source before evaluating cues. A cue with
+ * `firesDuringSeek` unset/false is skipped entirely (both directions, and
+ * the auto-cleanup/compensation described below) on a seek-sourced
+ * crossing — this is what keeps authoring-time scrubbing from spamming
+ * `player.lockInput()`/`enemies.spawn()` side effects, matching the spirit
+ * of the D4 director AC ("seeking ... without spuriously firing gameplay
+ * cues"). Driving the clock directly (bypassing the runner's wrapper
+ * methods) is still safe — the crossing is simply treated as `'advance'`
+ * sourced by default — but loses seek-vs-play discrimination; this is a
+ * documented, deliberate limitation, not a bug.
+ *
+ * ## Equal-timestamp tiebreak
+ *
+ * Cues are evaluated in ascending `time` order; cues with an EQUAL `time`
+ * are evaluated in REGISTRATION order (the order they appear in the array
+ * passed to `createCueRunner`) — the same tiebreak convention
+ * `AnimationClock.subscribe` itself uses for same-phase evaluators
+ * (`animation-clock.ts`'s `EvaluatorEntry.order`).
+ *
+ * ## Cleanup / compensation
+ *
+ * `run`/`reverse` may return a `CueCleanup` function. It is invoked (and
+ * then discarded) at whichever of these happens first:
+ *
+ *  - a reverse-direction crossing of the SAME cue (even if the cue has no
+ *    explicit `reverse` handler — this is the "compensation" half of the
+ *    contract: undo whatever `run` set up, symmetrically, when time moves
+ *    back past it), subject to the same `firesDuringSeek` gating as any
+ *    other reverse-direction reaction;
+ *  - the cue being re-armed by a loop wrap (`resetsOnLoop`) or by
+ *    `reset()` — any not-yet-compensated effect is cleaned up before the
+ *    cue is made eligible to fire again;
+ *  - `CueRunner.dispose()` — final teardown.
+ *
+ * `run`'s cleanup and `reverse`'s cleanup are tracked independently, so an
+ * explicit `reverse` handler that ALSO returns a cleanup gets its own
+ * compensation slot (invoked on re-arm/dispose, since there is no
+ * "un-reverse" direction to compensate it from).
+ *
+ * ## Error isolation
+ *
+ * Every `run`/`reverse`/cleanup invocation is individually try/caught. A
+ * throw is recorded as a `CueError` (`cueId` + `time` + which `phase`
+ * threw) via `getErrors()`/the optional `onError` callback, and NEVER
+ * re-thrown — one failing cue can neither block a sibling cue in the same
+ * crossing nor corrupt the clock (the clock has already committed its new
+ * position before any cue runs; a cue is a pure reaction to a completed
+ * crossing, never a participant in producing one).
+ */
+
+/** Optional compensation/cleanup a cue handler may return. */
+export type CueCleanup = () => void;
+
+/**
+ * `void` (not `undefined`) is required here so an ordinary handler written
+ * as `run: (ctx) => { ctx.player.lockInput(); }` (no explicit `return`,
+ * which TS types as `void`) stays assignable — TS's special-cased "a
+ * `void`-typed callback return position accepts any return value"
+ * assignability rule does NOT apply to `undefined`; swapping this to
+ * `undefined | CueCleanup` breaks every cue author whose handler doesn't
+ * end in a bare `return;`.
+ */
+// biome-ignore lint/suspicious/noConfusingVoidType: see doc comment above — void is required for callback assignability, not a mistake.
+export type CueHandlerResult = void | CueCleanup;
+
+/**
+ * A single cinematic cue: a stable id, a time in seconds, and the gameplay
+ * reaction(s) to crossing that time. See the module doc above and spec
+ * §5.4 for the full contract.
+ */
+export interface CinematicCue<TContext = unknown> {
+  /** Stable identifier, unique within one `CueRunner`. */
+  readonly id: string;
+  /** Time in seconds, in the same domain as the driving `AnimationClock`. */
+  readonly time: number;
+  /** Forward-crossing behavior. May return a cleanup/compensation function. */
+  run(ctx: TContext): CueHandlerResult;
+  /** Optional reverse (backward-crossing) behavior. May return its own cleanup. */
+  reverse?(ctx: TContext): CueHandlerResult;
+  /**
+   * Whether this cue reacts to a `CueRunner.seek()`-sourced crossing (in
+   * either direction). Default `false` — explicit seeks (authoring-time
+   * scrubbing, skip/jump) do not fire gameplay-consequential cues unless a
+   * cue opts in.
+   */
+  readonly firesDuringSeek?: boolean;
+  /**
+   * Whether a loop-wrapping crossing re-arms this cue so it can fire again
+   * next lap. Default `false` — the cue fires (at most) once for the
+   * lifetime of the runner, until an explicit `reset()`.
+   */
+  readonly resetsOnLoop?: boolean;
+}
+
+export type CueErrorPhase = 'run' | 'reverse' | 'cleanup';
+
+/** A failed cue's identity + which phase threw, never a live Error re-throw. */
+export interface CueError {
+  readonly cueId: string;
+  readonly time: number;
+  readonly phase: CueErrorPhase;
+  readonly error: unknown;
+}
+
+/** Which `AnimationClock` method produced the crossing being evaluated. */
+export type CueCrossingSource = 'advance' | 'seek';
+
+export interface CueRunnerOptions<TContext> {
+  /** The game context passed to every `run`/`reverse` call. */
+  context: TContext;
+  /**
+   * Which `AnimationClock` phase to evaluate cues in. Default `'gameLogic'`
+   * — gameplay consequences run before the `'animation'` phase Theatre
+   * bindings use (`theatre-clock-binding.ts`), matching `PHASE_ORDER`.
+   */
+  phase?: SystemPhaseName;
+  /** Called synchronously whenever a cue's run/reverse/cleanup throws. */
+  onError?: (err: CueError) => void;
+}
+
+/**
+ * The runner's public surface is intentionally context-agnostic (`TContext`
+ * only shapes construction — the cue handlers it drives — not this object's
+ * own methods), so it takes no type parameter.
+ */
+export interface CueRunner {
+  /**
+   * Explicit seek, tagged as `'seek'`-sourced for `firesDuringSeek` gating.
+   * Prefer this over calling the underlying clock's `seek()` directly.
+   */
+  seek(t: number): ClockCrossing;
+  /**
+   * Playback tick, tagged as `'advance'`-sourced. Prefer this over calling
+   * the underlying clock's `advance()` directly. No-op (returns `null`)
+   * under the same conditions `AnimationClock.advance` is a no-op.
+   */
+  advance(dt: number): ClockCrossing | null;
+  /** Re-arms every cue (the "restart" policy) and runs any pending cleanups. */
+  reset(): void;
+  /** Every cue failure recorded so far, in the order they occurred. */
+  getErrors(): readonly CueError[];
+  /** Clears the recorded error log (does not affect cue armed state). */
+  clearErrors(): void;
+  /** Unsubscribes from the clock and runs any pending cleanups. */
+  dispose(): void;
+}
+
+interface CueState {
+  firedForward: boolean;
+  firedReverse: boolean;
+  forwardCleanup: CueCleanup | undefined;
+  reverseCleanup: CueCleanup | undefined;
+}
+
+interface OrderedCue<TContext> {
+  cue: CinematicCue<TContext>;
+  registrationOrder: number;
+}
+
+function crossesForward(interval: ClockInterval, cueTime: number): boolean {
+  return interval.direction === 'forward' && cueTime > interval.from && cueTime <= interval.to;
+}
+
+function crossesReverse(interval: ClockInterval, cueTime: number): boolean {
+  return interval.direction === 'reverse' && cueTime < interval.from && cueTime >= interval.to;
+}
+
+/**
+ * Build a cue runner bound to `clock`, evaluating `cues` on every crossing.
+ * See the module doc comment for the full policy contract.
+ */
+export function createCueRunner<TContext>(
+  clock: AnimationClock,
+  cues: readonly CinematicCue<TContext>[],
+  options: CueRunnerOptions<TContext>,
+): CueRunner {
+  const seen = new Set<string>();
+  for (const cue of cues) {
+    if (seen.has(cue.id)) {
+      throw new Error(`[CueRunner] duplicate cue id "${cue.id}" — ids must be unique`);
+    }
+    seen.add(cue.id);
+  }
+
+  const ordered: OrderedCue<TContext>[] = cues.map((cue, registrationOrder) => ({
+    cue,
+    registrationOrder,
+  }));
+  ordered.sort((a, b) => {
+    if (a.cue.time !== b.cue.time) return a.cue.time - b.cue.time;
+    return a.registrationOrder - b.registrationOrder;
+  });
+
+  const context = options.context;
+  const phase = options.phase ?? 'gameLogic';
+  const errors: CueError[] = [];
+  const states = new Map<string, CueState>();
+  for (const { cue } of ordered) {
+    states.set(cue.id, {
+      firedForward: false,
+      firedReverse: false,
+      forwardCleanup: undefined,
+      reverseCleanup: undefined,
+    });
+  }
+
+  function stateOf(id: string): CueState {
+    const state = states.get(id);
+    if (!state) throw new Error(`[CueRunner] unknown cue id "${id}"`); // unreachable — defensive
+    return state;
+  }
+
+  function reportError(cueId: string, time: number, errPhase: CueErrorPhase, error: unknown): void {
+    const cueError: CueError = { cueId, time, phase: errPhase, error };
+    errors.push(cueError);
+    options.onError?.(cueError);
+  }
+
+  function invokeHandler(
+    cue: CinematicCue<TContext>,
+    errPhase: 'run' | 'reverse',
+    handler: (ctx: TContext) => CueHandlerResult,
+  ): CueCleanup | undefined {
+    try {
+      const result = handler(context);
+      return typeof result === 'function' ? result : undefined;
+    } catch (error) {
+      reportError(cue.id, cue.time, errPhase, error);
+      return undefined;
+    }
+  }
+
+  function invokeCleanup(cue: CinematicCue<TContext>, cleanup: CueCleanup): void {
+    try {
+      cleanup();
+    } catch (error) {
+      reportError(cue.id, cue.time, 'cleanup', error);
+    }
+  }
+
+  // NOTE: no crossing-scoped "already fired this crossing" guard beyond the
+  // per-cue `state.firedForward`/`state.firedReverse` flags below — those
+  // flags are sufficient (each cue is visited at most once per interval,
+  // and a fire sets the flag before the next interval is scanned) AND, in
+  // the resetsOnLoop case, `rearmLoopCues` deliberately clears them mid
+  // crossing so a cue CAN legitimately fire again in a later interval of
+  // the same multi-lap crossing (once per lap boundary actually crossed).
+  // A crossing-wide "fired once ever" set would silently defeat that.
+  function processForwardInterval(interval: ClockInterval, source: CueCrossingSource): void {
+    for (const { cue } of ordered) {
+      const state = stateOf(cue.id);
+      if (state.firedForward) continue;
+      if (!crossesForward(interval, cue.time)) continue;
+      if (source === 'seek' && !cue.firesDuringSeek) continue;
+
+      state.firedForward = true;
+      const cleanup = invokeHandler(cue, 'run', cue.run);
+      if (cleanup) state.forwardCleanup = cleanup;
+    }
+  }
+
+  // Split out of processReverseInterval to keep both functions under the
+  // project's cognitive-complexity budget: this is the "what happens to ONE
+  // cue on a reverse crossing" reaction — the explicit reverse() handler
+  // (if any, fire-once) plus the automatic forward-cleanup compensation
+  // (independent of whether reverse() exists) — see the module doc's
+  // "Cleanup / compensation" section.
+  function reactToReverseCrossing(cue: CinematicCue<TContext>, state: CueState): void {
+    if (cue.reverse && !state.firedReverse) {
+      state.firedReverse = true;
+      const cleanup = invokeHandler(cue, 'reverse', cue.reverse);
+      if (cleanup) state.reverseCleanup = cleanup;
+    }
+
+    if (state.forwardCleanup) {
+      const cleanup = state.forwardCleanup;
+      state.forwardCleanup = undefined;
+      invokeCleanup(cue, cleanup);
+    }
+  }
+
+  function processReverseInterval(interval: ClockInterval, source: CueCrossingSource): void {
+    for (const { cue } of ordered) {
+      if (!crossesReverse(interval, cue.time)) continue;
+      if (source === 'seek' && !cue.firesDuringSeek) continue;
+      reactToReverseCrossing(cue, stateOf(cue.id));
+    }
+  }
+
+  function rearmLoopCues(): void {
+    for (const { cue } of ordered) {
+      if (!cue.resetsOnLoop) continue;
+      const state = stateOf(cue.id);
+      if (!state.firedForward && !state.firedReverse) continue; // nothing to rearm
+      if (state.forwardCleanup) {
+        invokeCleanup(cue, state.forwardCleanup);
+        state.forwardCleanup = undefined;
+      }
+      if (state.reverseCleanup) {
+        invokeCleanup(cue, state.reverseCleanup);
+        state.reverseCleanup = undefined;
+      }
+      state.firedForward = false;
+      state.firedReverse = false;
+    }
+  }
+
+  function handleCrossing(crossing: ClockCrossing, source: CueCrossingSource): void {
+    for (const interval of crossing.intervals) {
+      if (interval.direction === 'forward') {
+        processForwardInterval(interval, source);
+      } else {
+        processReverseInterval(interval, source);
+      }
+
+      if (crossing.looped) {
+        const completesLap =
+          (interval.direction === 'forward' && interval.to === clock.range.end) ||
+          (interval.direction === 'reverse' && interval.to === clock.range.start);
+        if (completesLap) rearmLoopCues();
+      }
+    }
+  }
+
+  let pendingSource: CueCrossingSource = 'advance';
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, (crossing) => {
+    handleCrossing(crossing, pendingSource);
+  });
+
+  let disposed = false;
+
+  return {
+    seek(t: number): ClockCrossing {
+      pendingSource = 'seek';
+      try {
+        return clock.seek(t);
+      } finally {
+        pendingSource = 'advance';
+      }
+    },
+
+    advance(dt: number): ClockCrossing | null {
+      pendingSource = 'advance';
+      return clock.advance(dt);
+    },
+
+    reset(): void {
+      for (const { cue } of ordered) {
+        const state = stateOf(cue.id);
+        if (state.forwardCleanup) {
+          invokeCleanup(cue, state.forwardCleanup);
+          state.forwardCleanup = undefined;
+        }
+        if (state.reverseCleanup) {
+          invokeCleanup(cue, state.reverseCleanup);
+          state.reverseCleanup = undefined;
+        }
+        state.firedForward = false;
+        state.firedReverse = false;
+      }
+    },
+
+    getErrors(): readonly CueError[] {
+      return errors;
+    },
+
+    clearErrors(): void {
+      errors.length = 0;
+    },
+
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      handle.dispose();
+      for (const { cue } of ordered) {
+        const state = stateOf(cue.id);
+        if (state.forwardCleanup) {
+          invokeCleanup(cue, state.forwardCleanup);
+          state.forwardCleanup = undefined;
+        }
+        if (state.reverseCleanup) {
+          invokeCleanup(cue, state.reverseCleanup);
+          state.reverseCleanup = undefined;
+        }
+      }
+    },
+  };
+}

package/src/animation/clip-map.ts

@@ -0,0 +1,41 @@
+import type * as THREE from 'three';
+
+/** Common aliases used by many free humanoid packs. Scene-authored aliases override these. */
+const DEFAULT_CLIP_ALIASES: Record<string, string> = {
+  walking: 'walk',
+  running: 'run',
+};
+
+/**
+ * Build the clip lookup shared by runtime and editor.
+ *
+ * GLTF exporters disagree about case and may prefix animation names with an
+ * armature (`Armature|Idle`). Keep the exact exported suffix while also
+ * exposing a lowercase lookup, then apply aliases case-insensitively. This
+ * lets authored graphs use either `Idle_Loop` or `idle_loop` without silently
+ * falling back to the bind pose.
+ */
+export function buildClipMap(
+  animations: THREE.AnimationClip[],
+  aliases: Record<string, string> = {},
+): Map<string, THREE.AnimationClip> {
+  const clips = new Map<string, THREE.AnimationClip>();
+  const canonical = new Map<string, THREE.AnimationClip>();
+
+  for (const clip of animations) {
+    const raw = clip.name.split('|').pop()?.trim() || clip.name;
+    canonical.set(raw.toLowerCase(), clip);
+    if (!clips.has(raw)) clips.set(raw, clip);
+    if (!clips.has(raw.toLowerCase())) clips.set(raw.toLowerCase(), clip);
+  }
+
+  const mergedAliases = { ...DEFAULT_CLIP_ALIASES, ...aliases };
+  for (const [source, alias] of Object.entries(mergedAliases)) {
+    const clip = canonical.get(source.toLowerCase());
+    if (!clip) continue;
+    if (!clips.has(alias)) clips.set(alias, clip);
+    if (!clips.has(alias.toLowerCase())) clips.set(alias.toLowerCase(), clip);
+  }
+
+  return clips;
+}

package/src/animation/gsap-registration.ts

@@ -0,0 +1,184 @@
+import gsap from 'gsap';
+import type { SystemPhaseName } from '../core/types';
+import type { AnimationClock, ClockEvaluatorHandle } 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 class GsapRegistrationError extends Error {
+  constructor(
+    message: string,
+    readonly code: 'not-a-timeline' | 'not-paused' | 'duplicate',
+  ) {
+    super(message);
+    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<AnimationClock, WeakSet<gsap.core.Timeline>>();
+
+/**
+ * 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: AnimationClock,
+  timeline: gsap.core.Timeline,
+  options: GsapRegistrationOptions = {},
+): GsapRegistration {
+  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: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    timeline.time(clock.time);
+  });
+
+  let disposed = false;
+  return {
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      handle.dispose();
+      seenForClock!.delete(timeline);
+    },
+  };
+}