@vgai/engine 0.2.0 → 0.3.0

package/dist/adapter/world-kind.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `WorldKind` — the kinds of render surface a world can be (T7.1/T7.3/T6.2).
+ *
+ * Moved here (T7.5, `docs/BACKBONE-TASKS.md`'s D6 row) from `runtime/game.ts`
+ * so `adapter/game-adapter.ts`'s kind-tagged `MountedWorld` types can name it
+ * without a value-level import cycle (`runtime/game.ts` type-imports from
+ * `adapter/game-adapter.ts` already). This is a leaf module — it imports
+ * nothing — so anything may import it with zero risk of a cycle.
+ * `runtime/game.ts` re-exports this SAME type (`export type { WorldKind }`),
+ * so no existing `import type { WorldKind } from '../runtime/game'` call site
+ * needed to change.
+ */
+export type WorldKind = 'threejs' | 'pixijs' | 'react';
+/**
+ * Exhaustiveness guard for `WorldKind` dispatch (v4 architecture-review
+ * §7.4-2: a hypothetical 4th kind must fail to COMPILE at every kind-dispatch
+ * site, not silently contribute nothing or silently default to an existing
+ * kind). Lives here — colocated with the kind vocabulary itself, not in a
+ * generic util module — so the three call sites that need it
+ * (`runtime/create-runtime.ts`'s mount loop, `editor/adapter-resolver.ts`'s
+ * `resolveAllWorlds`, `editor/play-mode.ts`'s `installMultiWorldAuthoring`)
+ * import it from the same leaf module that defines `WorldKind`, keeping the
+ * type and its guard from drifting apart. The `never` parameter is the
+ * compile-time half of the guard (TS refuses to call this with anything the
+ * compiler hasn't already narrowed to zero remaining variants); the thrown
+ * Error is the runtime half, in case a value's static type lied (e.g. data
+ * crossing a JSON boundary).
+ */
+export declare function assertNever(value: never, context?: string): never;
+//# sourceMappingURL=world-kind.d.ts.map

package/dist/adapter/world-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-kind.d.ts","sourceRoot":"","sources":["../../src/adapter/world-kind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAIjE"}

package/dist/adapter/world-kind.js

@@ -0,0 +1,18 @@
+/**
+ * Exhaustiveness guard for `WorldKind` dispatch (v4 architecture-review
+ * §7.4-2: a hypothetical 4th kind must fail to COMPILE at every kind-dispatch
+ * site, not silently contribute nothing or silently default to an existing
+ * kind). Lives here — colocated with the kind vocabulary itself, not in a
+ * generic util module — so the three call sites that need it
+ * (`runtime/create-runtime.ts`'s mount loop, `editor/adapter-resolver.ts`'s
+ * `resolveAllWorlds`, `editor/play-mode.ts`'s `installMultiWorldAuthoring`)
+ * import it from the same leaf module that defines `WorldKind`, keeping the
+ * type and its guard from drifting apart. The `never` parameter is the
+ * compile-time half of the guard (TS refuses to call this with anything the
+ * compiler hasn't already narrowed to zero remaining variants); the thrown
+ * Error is the runtime half, in case a value's static type lied (e.g. data
+ * crossing a JSON boundary).
+ */
+export function assertNever(value, context) {
+    throw new Error(`Unreachable${context ? ` ${context}` : ''}: unexpected value ${JSON.stringify(value)}`);
+}

package/dist/ai/navigation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * NavMeshManager — wraps recast-navigation for navmesh generation + crowd pathfinding.
+ *
+ * Usage:
+ *   await init();  // WASM init (call once per app)
+ *   const nav = new NavMeshManager();
+ *   await nav.buildFromMeshes(meshes);
+ *   const path = nav.findPath(start, end);
+ *   const crowd = nav.createCrowd(10);
+ *   // In game loop: nav.updateCrowd(dt);
+ */
+import { NavMeshHelper } from '@recast-navigation/three';
+import type { CrowdAgent } from 'recast-navigation';
+import { Crowd } from 'recast-navigation';
+import type { Mesh, Scene } from 'three';
+export type { CrowdAgent };
+export interface Vector3Like {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface NavMeshBuildParams {
+    cellSize?: number | undefined;
+    cellHeight?: number | undefined;
+    walkableSlopeAngle?: number | undefined;
+    walkableHeight?: number | undefined;
+    walkableClimb?: number | undefined;
+    walkableRadius?: number | undefined;
+    maxEdgeLen?: number | undefined;
+    maxSimplificationError?: number | undefined;
+    minRegionArea?: number | undefined;
+    mergeRegionArea?: number | undefined;
+}
+export declare function initNavigation(): Promise<void>;
+export declare class NavMeshManager {
+    private navMesh;
+    private query;
+    private crowd;
+    private helper;
+    /** Build navmesh from Three.js Mesh objects (grounds, obstacles, etc.). */
+    buildFromMeshes(meshes: Mesh[], params?: NavMeshBuildParams): boolean;
+    /**
+     * Destroy all live recast handles (crowd, query, navmesh) and dispose the
+     * debug helper. Recast objects live on the WASM heap and are NOT GC'd —
+     * they must be explicitly `.destroy()`ed or they leak.
+     */
+    private destroyRecast;
+    /** True once a navmesh has been built (for the NavigationAdapter to gate on). */
+    hasNavMesh(): boolean;
+    /** Find a straight path between two world positions. Returns [] if no path. */
+    findPath(start: Vector3Like, end: Vector3Like): Vector3Like[];
+    /** Create a crowd with up to maxAgents agents. */
+    createCrowd(maxAgents: number): Crowd;
+    /** Step the crowd simulation. Call once per frame. */
+    updateCrowd(dt: number): void;
+    /** Get or create the wireframe debug mesh. Add to scene once, call update() after rebuilding. */
+    getDebugMesh(scene: Scene): NavMeshHelper | null;
+    /** Serialize the current navmesh to a binary blob. */
+    exportData(): Uint8Array;
+    /** Load a navmesh from a previously exported binary blob. */
+    loadFromData(data: Uint8Array): void;
+    dispose(scene: Scene): void;
+}
+//# sourceMappingURL=navigation.d.ts.map

package/dist/ai/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/ai/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAsB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAoD,MAAM,mBAAmB,CAAC;AAC5F,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAGzC,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAID,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,MAAM,CAA8B;IAE5C,2EAA2E;IAC3E,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO;IA4BrE;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAoBrB,iFAAiF;IACjF,UAAU,IAAI,OAAO;IAIrB,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,WAAW,EAAE;IAO7D,kDAAkD;IAClD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK;IAMrC,sDAAsD;IACtD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI7B,iGAAiG;IACjG,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,IAAI;IAShD,sDAAsD;IACtD,UAAU,IAAI,UAAU;IAKxB,6DAA6D;IAC7D,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAQpC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAM5B"}

package/dist/ai/navigation.js

@@ -0,0 +1,133 @@
+/**
+ * NavMeshManager — wraps recast-navigation for navmesh generation + crowd pathfinding.
+ *
+ * Usage:
+ *   await init();  // WASM init (call once per app)
+ *   const nav = new NavMeshManager();
+ *   await nav.buildFromMeshes(meshes);
+ *   const path = nav.findPath(start, end);
+ *   const crowd = nav.createCrowd(10);
+ *   // In game loop: nav.updateCrowd(dt);
+ */
+import { NavMeshHelper, threeToSoloNavMesh } from '@recast-navigation/three';
+import { Crowd, exportNavMesh, importNavMesh, init, NavMeshQuery } from 'recast-navigation';
+import { DEFAULTS } from '../scene/defaults';
+let wasmInitialized = false;
+export async function initNavigation() {
+    if (wasmInitialized)
+        return;
+    await init();
+    wasmInitialized = true;
+}
+export class NavMeshManager {
+    navMesh = null;
+    query = null;
+    crowd = null;
+    helper = null;
+    /** Build navmesh from Three.js Mesh objects (grounds, obstacles, etc.). */
+    buildFromMeshes(meshes, params) {
+        const d = DEFAULTS.navigation;
+        const result = threeToSoloNavMesh(meshes, {
+            cs: params?.cellSize ?? d.cellSize,
+            ch: params?.cellHeight ?? d.cellHeight,
+            walkableSlopeAngle: params?.walkableSlopeAngle ?? d.walkableSlopeAngle,
+            walkableHeight: params?.walkableHeight ?? d.walkableHeight,
+            walkableClimb: params?.walkableClimb ?? d.walkableClimb,
+            walkableRadius: params?.walkableRadius ?? d.walkableRadius,
+            maxEdgeLen: params?.maxEdgeLen ?? d.maxEdgeLen,
+            maxSimplificationError: params?.maxSimplificationError ?? d.maxSimplificationError,
+            minRegionArea: params?.minRegionArea ?? d.minRegionArea,
+            mergeRegionArea: params?.mergeRegionArea ?? d.mergeRegionArea,
+            // Recast tuning knobs with no DEFAULTS counterpart (not modeled there).
+            maxVertsPerPoly: 6,
+            detailSampleDist: 6,
+            detailSampleMaxError: 1,
+        });
+        if (!result.success || !result.navMesh)
+            return false;
+        // Free the previous recast objects before replacing them (WASM heap leak).
+        this.destroyRecast();
+        this.navMesh = result.navMesh;
+        this.query = new NavMeshQuery(this.navMesh);
+        return true;
+    }
+    /**
+     * Destroy all live recast handles (crowd, query, navmesh) and dispose the
+     * debug helper. Recast objects live on the WASM heap and are NOT GC'd —
+     * they must be explicitly `.destroy()`ed or they leak.
+     */
+    destroyRecast() {
+        if (this.helper) {
+            this.helper.parent?.remove(this.helper);
+            this.helper.dispose?.();
+            this.helper = null;
+        }
+        if (this.crowd) {
+            this.crowd.destroy();
+            this.crowd = null;
+        }
+        if (this.query) {
+            this.query.destroy();
+            this.query = null;
+        }
+        if (this.navMesh) {
+            this.navMesh.destroy();
+            this.navMesh = null;
+        }
+    }
+    /** True once a navmesh has been built (for the NavigationAdapter to gate on). */
+    hasNavMesh() {
+        return this.navMesh !== null;
+    }
+    /** Find a straight path between two world positions. Returns [] if no path. */
+    findPath(start, end) {
+        if (!this.query)
+            return [];
+        const result = this.query.computePath(start, end);
+        if (!result.success)
+            return [];
+        return result.path;
+    }
+    /** Create a crowd with up to maxAgents agents. */
+    createCrowd(maxAgents) {
+        if (!this.navMesh)
+            throw new Error('Build navmesh first');
+        this.crowd = new Crowd(this.navMesh, { maxAgents, maxAgentRadius: 0.6 });
+        return this.crowd;
+    }
+    /** Step the crowd simulation. Call once per frame. */
+    updateCrowd(dt) {
+        this.crowd?.update(dt);
+    }
+    /** Get or create the wireframe debug mesh. Add to scene once, call update() after rebuilding. */
+    getDebugMesh(scene) {
+        if (!this.navMesh)
+            return null;
+        if (!this.helper) {
+            this.helper = new NavMeshHelper(this.navMesh);
+            scene.add(this.helper);
+        }
+        return this.helper;
+    }
+    /** Serialize the current navmesh to a binary blob. */
+    exportData() {
+        if (!this.navMesh)
+            throw new Error('No navmesh to export');
+        return exportNavMesh(this.navMesh);
+    }
+    /** Load a navmesh from a previously exported binary blob. */
+    loadFromData(data) {
+        const { navMesh } = importNavMesh(data);
+        // Free the previous recast objects before replacing them.
+        this.destroyRecast();
+        this.navMesh = navMesh;
+        this.query = new NavMeshQuery(this.navMesh);
+    }
+    dispose(scene) {
+        // Ensure the helper is removed from the passed scene as well, then destroy
+        // every recast handle (crowd/query/navmesh) so nothing leaks on the WASM heap.
+        if (this.helper)
+            scene.remove(this.helper);
+        this.destroyRecast();
+    }
+}

package/dist/animation/anim-graph-types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Blend-tree shapes shared by the (removed, E5) legacy `AnimGraph` runtime and
+ * the current XState -> AnimationMixer binding (`xstate-animation-binding.ts`,
+ * E2). Retained deliberately — see `packages/engine/test/removal-inventory.ts`'s
+ * `animgraph` family note: `BlendTreeDef`/`BlendChild` are imported directly by
+ * `xstate-animation-binding.ts`, so this file survived E5's removal as a
+ * partial edit rather than being deleted whole. Every other type this file
+ * used to declare (`AnimGraphFile`, `AnimParameter`, `AnimLayer`, `AnimState`,
+ * `AnimTransition`, `TransitionCondition` — the state-machine-shaped half of
+ * the old `.animgraph.json` format) was deleted with the runtime that read
+ * them (`anim-graph.ts`).
+ */
+export interface BlendTreeDef {
+    type: '1D' | '2D' | 'direct';
+    parameter: string;
+    parameterY?: string;
+    children: BlendChild[];
+}
+export interface BlendChild {
+    clip: string;
+    threshold: number;
+    thresholdY?: number;
+    weight?: number;
+}
+//# sourceMappingURL=anim-graph-types.d.ts.map

package/dist/animation/anim-graph-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anim-graph-types.d.ts","sourceRoot":"","sources":["../../src/animation/anim-graph-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,QAAQ,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/animation/anim-graph-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,213 @@
+import { type SystemPhaseName } from '../core/types';
+/**
+ * D1 — the canonical `AnimationClock` (spec §10 D1, §3.2, §4).
+ *
+ * VGAI owns exactly one clock per cinematic/scene context. It is the single
+ * source of truth for "what time is it" that Theatre sequences, registered
+ * GSAP timelines, and cinematic cue evaluators are seeked against (D2/D5/D7
+ * — NOT implemented here, this unit is the clock only). The render seam
+ * (I2) drives this clock's `seek(t)`/frame-index API directly, without ever
+ * advancing gameplay substeps.
+ *
+ * Design constraints (from the spec and the D1 review notes):
+ *
+ *  - Time is in SECONDS with no hidden wall-clock read. This class never
+ *    reads the system clock or a monotonic timer directly — the caller (the
+ *    fixed-step game loop for live playback, or a render/export harness for
+ *    offline scrubbing) is the only source of `dt`/target time. That is
+ *    what makes `seek(t)` and frame-index seeking reproducible offline.
+ *  - No parallel scheduler. Evaluator registration reuses the engine's own
+ *    `SystemPhaseName`/`PHASE_ORDER` vocabulary (`core/types.ts`) — the same
+ *    phase names every `GameComponent`/system in the engine already uses —
+ *    so a Theatre binding (D2), a GSAP registration (D7), and a cue
+ *    evaluator (D5) can each declare which phase they conceptually belong
+ *    to and be invoked in one deterministic, engine-wide order instead of
+ *    each subsystem inventing its own ordering rule. IMPORTANT: this only
+ *    orders evaluators relative to each other WITHIN one `emit()` — i.e.
+ *    within a single `seek()`/`advance()` call. Registering at `'preRender'`
+ *    does NOT mean an evaluator runs during the live engine's own
+ *    `system-runner` `preRender` phase inside a running RAF frame — the
+ *    clock is independent of the live game loop's phase execution (and
+ *    during offline export/scrub there is no RAF frame at all). The shared
+ *    vocabulary buys a familiar, documented ordering convention between
+ *    clock-side evaluators, not a promise of interleaving with unrelated
+ *    engine systems that happen to run in a same-named phase during a live
+ *    frame.
+ *  - Frame-index seeking for export must be EXACT: frame `n` at fps `f`
+ *    always evaluates `start + n / f`, computed directly from `n` and `f`
+ *    on every call — never by accumulating `1/f` repeatedly, which would
+ *    drift. See `seekFrame` below.
+ */
+/** Sign of time evolution while the clock is actually playing. */
+export type ClockDirection = 'forward' | 'reverse';
+/** Coarse playback state. `advance()` is a no-op unless this is `'playing'`. */
+export type ClockPlaybackState = 'playing' | 'paused' | 'stopped';
+/** Loop/range metadata — the valid time domain `[start, end]`. */
+export interface ClockRange {
+    readonly start: number;
+    readonly end: number;
+    readonly loop: boolean;
+}
+/**
+ * One contiguous, monotonic sweep of time within a single `[start, end]`
+ * lap. A step that crosses a loop boundary produces MORE THAN ONE interval
+ * (one per lap segment) so a cue evaluator can test each segment
+ * independently and never conflate "crossed near the end of lap 1" with
+ * "crossed near the start of lap 2".
+ *
+ * ## Cue-crossing detection convention (half-open)
+ *
+ * A cue/marker at time `t` is considered CROSSED by an interval iff:
+ *
+ *  - forward interval: `t > interval.from && t <= interval.to`
+ *  - reverse interval: `t < interval.from && t >= interval.to`
+ *
+ * This is deliberately half-open on the "from" side and closed on the "to"
+ * side (i.e. the endpoint the sweep is *arriving at* counts, the endpoint it
+ * *departed from* does not). Consumers (D5 cinematic cues) MUST use exactly
+ * this convention, never an inclusive-both-ends test: `seek()` is
+ * idempotent and re-asserts a zero-length interval `{from: t, to: t}` on a
+ * repeated seek to the same `t` (see `AnimationClock.seek`), and an
+ * inclusive-both-ends detector would re-match that zero-length interval
+ * (`from === to === t`) and double-fire on every repeated seek. The
+ * half-open test above never matches a zero-length interval (`t > t` and
+ * `t < t` are both always false), so a fire-once cue evaluator built on it
+ * gets idempotent re-seeks "for free" with no extra bookkeeping.
+ */
+export interface ClockInterval {
+    readonly from: number;
+    readonly to: number;
+    readonly direction: ClockDirection;
+}
+/**
+ * What a subscribed evaluator receives on every `seek`/`advance` call that
+ * changes (or idempotently re-asserts) the clock's position.
+ */
+export interface ClockCrossing {
+    readonly previousTime: number;
+    readonly currentTime: number;
+    /** Direction of this specific crossing (not necessarily `clock.direction`,
+     *  which reflects live playback intent — a `seek()` while paused still
+     *  reports the direction it moved, or the last known direction if it was
+     *  a no-op re-seek to the same time). */
+    readonly direction: ClockDirection;
+    readonly timeScale: number;
+    /** True iff this crossing wrapped a loop boundary (produced 2+ intervals). */
+    readonly looped: boolean;
+    /**
+     * The monotonic sweep segment(s) covered by this crossing, in
+     * chronological evaluation order. Normally exactly one interval
+     * `[previousTime, currentTime]`; a loop-wrapping step yields one interval
+     * per lap segment traversed. A subscriber determines exactly which cue
+     * times were crossed (and in which direction) by testing each interval,
+     * never by comparing `previousTime`/`currentTime` directly — that alone
+     * is ambiguous across a wrap.
+     */
+    readonly intervals: readonly ClockInterval[];
+}
+export type ClockEvaluator = (crossing: ClockCrossing) => void;
+export interface ClockEvaluatorHandle {
+    dispose(): void;
+}
+export interface AnimationClockOptions {
+    /** Range start, in seconds. Default 0. */
+    start?: number;
+    /** Range end, in seconds. Default `Math.max(start, 1)`. */
+    end?: number;
+    /** Whether `advance()` wraps at the range boundary instead of clamping. Default false. */
+    loop?: boolean;
+    /** Playback rate multiplier, must be finite and >= 0. Default 1. */
+    timeScale?: number;
+}
+/**
+ * The engine-owned canonical clock. See the module doc comment above for
+ * the design constraints this implementation is bound by.
+ */
+export declare class AnimationClock {
+    private _previousTime;
+    private _currentTime;
+    private _range;
+    private _timeScale;
+    private _playDirection;
+    private _lastCrossingDirection;
+    private _playbackState;
+    private _evaluators;
+    private _registrationCounter;
+    constructor(options?: AnimationClockOptions);
+    /** Current playhead time, in seconds. */
+    get time(): number;
+    /** Playhead time immediately before the most recent seek/advance. */
+    get previousTime(): number;
+    /**
+     * Playback direction. `'paused'` whenever `playbackState !== 'playing'`
+     * (covers both `pause()` and `stop()`) — matches the spec's literal
+     * `direction: forward | reverse | paused` acceptance criterion. The
+     * underlying intended direction is preserved across pause/resume; see
+     * `play()`.
+     */
+    get direction(): ClockDirection | 'paused';
+    get playbackState(): ClockPlaybackState;
+    get timeScale(): number;
+    set timeScale(value: number);
+    get range(): ClockRange;
+    /**
+     * Update loop/range metadata. The current playhead is clamped into the
+     * new range if necessary (reported as an ordinary crossing — same
+     * evaluator path as `seek`/`advance` — so subscribers observe it).
+     */
+    setRange(next: Partial<Pick<ClockRange, 'start' | 'end' | 'loop'>>): void;
+    /**
+     * Begin/resume playback. `direction` sets (or re-asserts) the intended
+     * playback direction for subsequent `advance()` calls; omit it to resume
+     * in whatever direction was last set (default `'forward'` the first time).
+     */
+    play(direction?: ClockDirection): void;
+    /** Halt playback at the current position. `advance()` becomes a no-op. */
+    pause(): void;
+    /**
+     * Halt playback at the current position (distinct from `pause()` only in
+     * reported `playbackState`; this unit does not prescribe a reset-to-start
+     * policy — that is a cinematic-controller/render-seam decision, D5/I2).
+     * `advance()` is a no-op in this state, same as `paused`.
+     */
+    stop(): void;
+    /**
+     * Jump directly to `t` (clamped into `range`). Idempotent: calling
+     * `seek(t)` twice in a row leaves `time`/`previousTime` identical to
+     * calling it once — the second call is a true no-op (no state mutation,
+     * though evaluators still fire so a subscriber can rely on `seek` always
+     * producing a crossing for e.g. re-asserting visual state).
+     */
+    seek(t: number): ClockCrossing;
+    /**
+     * Frame-index seek for export (D1 AC): seeks to EXACTLY `range.start +
+     * n / fps`, computed fresh from `n`/`fps` on every call. This is what
+     * keeps a rendered frame sequence drift-free — unlike repeatedly calling
+     * `advance(1 / fps)` `n` times (which accumulates float error), this
+     * always derives the same exact double for a given `(n, fps)` pair no
+     * matter what the clock's prior state was.
+     */
+    seekFrame(n: number, fps: number): ClockCrossing;
+    /**
+     * Fixed-step advance by `dt` seconds (magnitude; sign of movement comes
+     * from `direction`/`play()`, not from `dt`'s sign). A no-op whenever
+     * `playbackState !== 'playing'` — this is what makes `advance()` do
+     * nothing while paused (D1 AC). Returns `null` for that no-op case;
+     * otherwise returns the resulting crossing (which may span multiple loop
+     * laps if `dt * timeScale` exceeds the range length).
+     */
+    advance(dt: number): ClockCrossing | null;
+    /**
+     * Register an evaluator against a phase from the engine's own
+     * `SystemPhaseName` vocabulary (`core/types.ts`). Evaluators fire on
+     * every `seek()`/`advance()` (including idempotent no-op seeks and
+     * `setRange` clamps) in `PHASE_ORDER` order, then registration order
+     * within a phase — the same "deterministic phase order" every other
+     * engine system is invoked in, so a Theatre binding, a registered-GSAP
+     * seek, and a cue evaluator can each declare their phase and compose
+     * without inventing a second ordering rule.
+     */
+    subscribe(phase: SystemPhaseName, evaluator: ClockEvaluator): ClockEvaluatorHandle;
+    private emit;
+}
+//# sourceMappingURL=animation-clock.d.ts.map

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

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