@vgai/engine 0.2.0 → 0.3.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"camera-ownership.d.ts","sourceRoot":"","sources":["../../src/animation/camera-ownership.ts"],"names":[],"mappings":"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"}

package/dist/animation/camera-ownership.js

@@ -0,0 +1,169 @@
+import * as THREE from 'three';
+/** Thrown on an ownership-stack rule violation (not-current-owner, unknown camera key, duplicate take). */
+export class CameraOwnershipError extends Error {
+    ownerId;
+    constructor(message, ownerId) {
+        super(message);
+        this.ownerId = ownerId;
+        this.name = 'CameraOwnershipError';
+    }
+}
+/** Snapshot a camera's full pose (position/quaternion cloned — never aliases the live object). */
+export function capturePose(camera) {
+    return {
+        position: camera.position.clone(),
+        quaternion: camera.quaternion.clone(),
+        fov: camera.fov,
+        near: camera.near,
+        far: camera.far,
+    };
+}
+/** Write a captured pose onto a camera, updating its projection matrix. */
+export function applyPose(camera, pose) {
+    camera.position.copy(pose.position);
+    camera.quaternion.copy(pose.quaternion);
+    camera.fov = pose.fov;
+    camera.near = pose.near;
+    camera.far = pose.far;
+    camera.updateProjectionMatrix();
+}
+/** Position LERP + quaternion SLERP + fov/near/far LERP, `t` in `[0, 1]`. */
+export function lerpPose(from, to, t) {
+    return {
+        position: from.position.clone().lerp(to.position, t),
+        quaternion: from.quaternion.clone().slerp(to.quaternion, t),
+        fov: THREE.MathUtils.lerp(from.fov, to.fov, t),
+        near: THREE.MathUtils.lerp(from.near, to.near, t),
+        far: THREE.MathUtils.lerp(from.far, to.far, t),
+    };
+}
+/**
+ * Build a camera-ownership system bound to `clock`. See the module doc
+ * comment for the full ownership-stack, cut/blend, and restore-policy
+ * contract.
+ */
+export function createCameraOwnershipSystem(options) {
+    const { liveCamera, cameras, clock } = options;
+    const defaultPolicy = options.defaultPolicy ?? 'restore';
+    const phase = options.phase ?? 'render';
+    const stack = [];
+    let disposed = false;
+    function requireNotDisposed(action) {
+        if (disposed) {
+            throw new CameraOwnershipError(`[camera-ownership] ${action}: system has been disposed`, '');
+        }
+    }
+    function requireSourceCamera(cameraKey, action) {
+        const camera = cameras[cameraKey];
+        if (!camera) {
+            throw new CameraOwnershipError(`[camera-ownership] ${action}: no registered camera for key "${cameraKey}"`, cameraKey);
+        }
+        return camera;
+    }
+    function requireTopOwner(ownerId, action) {
+        const top = stack[stack.length - 1];
+        if (!top) {
+            throw new CameraOwnershipError(`[camera-ownership] ${action}: "${ownerId}" is not the current owner (ownership stack is empty)`, ownerId);
+        }
+        if (top.ownerId !== ownerId) {
+            throw new CameraOwnershipError(`[camera-ownership] ${action}: "${ownerId}" is not the current owner (current owner is "${top.ownerId}")`, ownerId);
+        }
+        return top;
+    }
+    /**
+     * Apply a frame's CURRENT state to `liveCamera` — a pure function of
+     * `clock.time` and the fixed `FrameState` record (see the module doc's
+     * "one unified transition model"). Never mutates `frame.state`.
+     */
+    function evaluateFrame(frame) {
+        const state = frame.state;
+        if (!state)
+            return;
+        const targetPose = capturePose(requireSourceCamera(state.targetKey, 'evaluate'));
+        const t = state.durationSeconds <= 0
+            ? 1
+            : Math.min(Math.max((clock.time - state.startTime) / state.durationSeconds, 0), 1);
+        applyPose(liveCamera, t >= 1 ? targetPose : lerpPose(state.fromPose, targetPose, t));
+    }
+    function beginTransition(ownerId, cameraKey, durationSeconds) {
+        const frame = requireTopOwner(ownerId, 'cut/blend');
+        requireSourceCamera(cameraKey, 'cut/blend'); // validate before mutating frame state
+        frame.state = {
+            targetKey: cameraKey,
+            fromPose: capturePose(liveCamera),
+            startTime: clock.time,
+            durationSeconds,
+        };
+        // Apply immediately so direct (non-clock-crossing-sourced) calls are
+        // visible right away; the per-crossing evaluator below re-applies the
+        // same result on every subsequent crossing (idempotent when called
+        // twice within the same crossing — e.g. once here, once from the D4
+        // hook's own 'preRender'-phase call site, once more from this module's
+        // later 'render'-phase evaluator).
+        evaluateFrame(frame);
+    }
+    function releaseFrame(frame, completed) {
+        const shouldRetain = frame.policy === 'retain' || (frame.policy === 'retain-if-completed' && completed);
+        if (!shouldRetain) {
+            applyPose(liveCamera, frame.restorePose);
+        }
+    }
+    const handle = clock.subscribe(phase, () => {
+        const top = stack[stack.length - 1];
+        if (top)
+            evaluateFrame(top);
+    });
+    return {
+        take(ownerId, takeOptions = {}) {
+            requireNotDisposed('take');
+            if (stack.some((frame) => frame.ownerId === ownerId)) {
+                throw new CameraOwnershipError(`[camera-ownership] take: "${ownerId}" is already on the ownership stack`, ownerId);
+            }
+            stack.push({
+                ownerId,
+                policy: takeOptions.policy ?? defaultPolicy,
+                restorePose: capturePose(liveCamera),
+                state: undefined,
+            });
+        },
+        cut(ownerId, cameraKey) {
+            requireNotDisposed('cut');
+            beginTransition(ownerId, cameraKey, 0);
+        },
+        blend(ownerId, cameraKey, blendSeconds) {
+            requireNotDisposed('blend');
+            if (!Number.isFinite(blendSeconds) || blendSeconds < 0) {
+                throw new CameraOwnershipError(`[camera-ownership] blend: blendSeconds must be a finite number >= 0, got ${blendSeconds}`, ownerId);
+            }
+            beginTransition(ownerId, cameraKey, blendSeconds);
+        },
+        applyDirectorEvent(ownerId, event) {
+            requireNotDisposed('applyDirectorEvent');
+            beginTransition(ownerId, event.cameraKey, event.blendSeconds);
+        },
+        release(ownerId, releaseOptions = {}) {
+            requireNotDisposed('release');
+            const top = requireTopOwner(ownerId, 'release');
+            stack.pop();
+            releaseFrame(top, releaseOptions.completed ?? false);
+        },
+        isOwner(ownerId) {
+            const top = stack[stack.length - 1];
+            return !!top && top.ownerId === ownerId;
+        },
+        get depth() {
+            return stack.length;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            while (stack.length > 0) {
+                const top = stack.pop();
+                if (top)
+                    releaseFrame(top, false);
+            }
+            handle.dispose();
+        },
+    };
+}

package/dist/animation/cinematic-cues.d.ts

@@ -0,0 +1,200 @@
+import type { SystemPhaseName } from '../core/types';
+import type { AnimationClock, ClockCrossing } 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;`.
+ */
+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;
+}
+/**
+ * Build a cue runner bound to `clock`, evaluating `cues` on every crossing.
+ * See the module doc comment for the full policy contract.
+ */
+export declare function createCueRunner<TContext>(clock: AnimationClock, cues: readonly CinematicCue<TContext>[], options: CueRunnerOptions<TContext>): CueRunner;
+//# sourceMappingURL=cinematic-cues.d.ts.map

package/dist/animation/cinematic-cues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cinematic-cues.d.ts","sourceRoot":"","sources":["../../src/animation/cinematic-cues.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAGd,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuGG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC;AAEpC;;;;;;;;GAQG;AAEH,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,UAAU,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,GAAG,OAAO;IAC9C,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,gBAAgB,CAAC;IACrC,iFAAiF;IACjF,OAAO,CAAC,CAAC,GAAG,EAAE,QAAQ,GAAG,gBAAgB,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1D,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,MAAM,CAAC;AAEnD,MAAM,WAAW,gBAAgB,CAAC,QAAQ;IACxC,6DAA6D;IAC7D,OAAO,EAAE,QAAQ,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAAC;IAC1C,8EAA8E;IAC9E,KAAK,IAAI,IAAI,CAAC;IACd,qEAAqE;IACrE,SAAS,IAAI,SAAS,QAAQ,EAAE,CAAC;IACjC,uEAAuE;IACvE,WAAW,IAAI,IAAI,CAAC;IACpB,iEAAiE;IACjE,OAAO,IAAI,IAAI,CAAC;CACjB;AAsBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EACtC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,SAAS,YAAY,CAAC,QAAQ,CAAC,EAAE,EACvC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GAClC,SAAS,CAoNX"}

package/dist/animation/cinematic-cues.js

@@ -0,0 +1,213 @@
+function crossesForward(interval, cueTime) {
+    return interval.direction === 'forward' && cueTime > interval.from && cueTime <= interval.to;
+}
+function crossesReverse(interval, cueTime) {
+    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(clock, cues, options) {
+    const seen = new Set();
+    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 = 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 = [];
+    const states = new Map();
+    for (const { cue } of ordered) {
+        states.set(cue.id, {
+            firedForward: false,
+            firedReverse: false,
+            forwardCleanup: undefined,
+            reverseCleanup: undefined,
+        });
+    }
+    function stateOf(id) {
+        const state = states.get(id);
+        if (!state)
+            throw new Error(`[CueRunner] unknown cue id "${id}"`); // unreachable — defensive
+        return state;
+    }
+    function reportError(cueId, time, errPhase, error) {
+        const cueError = { cueId, time, phase: errPhase, error };
+        errors.push(cueError);
+        options.onError?.(cueError);
+    }
+    function invokeHandler(cue, errPhase, handler) {
+        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, cleanup) {
+        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, source) {
+        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, state) {
+        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, source) {
+        for (const { cue } of ordered) {
+            if (!crossesReverse(interval, cue.time))
+                continue;
+            if (source === 'seek' && !cue.firesDuringSeek)
+                continue;
+            reactToReverseCrossing(cue, stateOf(cue.id));
+        }
+    }
+    function rearmLoopCues() {
+        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, source) {
+        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 = 'advance';
+    const handle = clock.subscribe(phase, (crossing) => {
+        handleCrossing(crossing, pendingSource);
+    });
+    let disposed = false;
+    return {
+        seek(t) {
+            pendingSource = 'seek';
+            try {
+                return clock.seek(t);
+            }
+            finally {
+                pendingSource = 'advance';
+            }
+        },
+        advance(dt) {
+            pendingSource = 'advance';
+            return clock.advance(dt);
+        },
+        reset() {
+            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() {
+            return errors;
+        },
+        clearErrors() {
+            errors.length = 0;
+        },
+        dispose() {
+            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/dist/animation/clip-map.d.ts

@@ -0,0 +1,12 @@
+import type * as THREE from 'three';
+/**
+ * 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 declare function buildClipMap(animations: THREE.AnimationClip[], aliases?: Record<string, string>): Map<string, THREE.AnimationClip>;
+//# sourceMappingURL=clip-map.d.ts.map

package/dist/animation/clip-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clip-map.d.ts","sourceRoot":"","sources":["../../src/animation/clip-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAQpC;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,KAAK,CAAC,aAAa,EAAE,EACjC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,aAAa,CAAC,CAoBlC"}

package/dist/animation/clip-map.js

@@ -0,0 +1,37 @@
+/** Common aliases used by many free humanoid packs. Scene-authored aliases override these. */
+const DEFAULT_CLIP_ALIASES = {
+    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, aliases = {}) {
+    const clips = new Map();
+    const canonical = new Map();
+    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;
+}