@vgai/engine 0.5.0 → 0.5.2

package/dist/animation/xstate-animation-meta.js

@@ -1,252 +0,0 @@
-import { z } from 'zod';
-/**
- * E1 — Zod/TypeScript metadata attached to XState state `meta.animation`
- * (spec §11 E1, §5.6, §3.3).
- *
- * This module defines ONLY animation data: which clip(s) a state plays, how
- * they loop/blend/crossfade, and (for locomotion-style states) how a 1D/2D/
- * direct blend tree distributes weight across several clips from a live
- * parameter. It intentionally contains **no transition vocabulary** — no
- * `on`/`target`/`guard`/`always`/`after`/`entry`/`exit`. XState alone owns
- * states, transitions, events, and guards (§3.3); this metadata is read-only
- * data a binding (`xstate-animation-binding.ts`, E2) consumes to drive a
- * `THREE.AnimationMixer` when XState enters/exits a state. Every schema below
- * is `.strict()` specifically so that smuggling a transition-shaped key into
- * `meta.animation` is a loud Zod "unrecognized key" error, not a silently
- * ignored field (E1 AC: "Metadata contains no transition language").
- *
- * ## Native layered composition
- *
- * Parallel XState regions may drive independent named layers. Each layer can
- * filter a clip to selected bone subtrees, scale its weight, and use normal
- * override or Three's native additive blend mode. XState still owns all
- * state/transition semantics; these fields only describe how the active
- * state's native `AnimationAction`s are composed by the binding.
- *
- * ## Blend tree shape
- *
- * Deliberately structurally IDENTICAL to `anim-graph-types.ts`'s
- * `BlendTreeDef` (same `type`/`parameter`/`parameterY`/`children[].clip`/
- * `.threshold`/`.thresholdY`/`.weight` fields) so the binding can hand a
- * parsed `AnimationBlendTree` straight to the existing, already-tested
- * `evaluateBlendTree` (`blend-node.ts`) with zero conversion — E2 reuses that
- * function verbatim rather than re-implementing 1D/2D/direct blend math.
- */
-// ---------------------------------------------------------------------------
-// Blend tree children
-// ---------------------------------------------------------------------------
-const AnimationBlendChildSchema = z
-    .object({
-    clip: z.string().min(1).describe('Animation clip name this child plays'),
-    threshold: z.number().describe('1D/2D blend position on the primary parameter axis'),
-    thresholdY: z
-        .number()
-        .optional()
-        .describe('2D blend position on the secondary parameter axis (2D blend trees only)'),
-    weight: z
-        .number()
-        .min(0)
-        .optional()
-        .describe('Explicit weight for "direct" blend trees (ignored by 1D/2D)'),
-})
-    .strict();
-const AnimationBlendTree1DSchema = z
-    .object({
-    type: z.literal('1D').describe('Interpolates linearly between sorted children by threshold'),
-    parameter: z.string().min(1).describe('Context/selector value driving the blend'),
-    children: z
-        .array(AnimationBlendChildSchema)
-        .min(2, '1D blend tree needs at least 2 children to interpolate between'),
-})
-    .strict();
-const AnimationBlendTree2DSchema = z
-    .object({
-    type: z
-        .literal('2D')
-        .describe('Inverse-distance-weights children by (parameter, parameterY) position'),
-    parameter: z.string().min(1).describe('Primary axis context/selector value'),
-    parameterY: z.string().min(1).describe('Secondary axis context/selector value'),
-    children: z
-        .array(AnimationBlendChildSchema.extend({ thresholdY: z.number() }))
-        .min(1, '2D blend tree needs at least 1 child'),
-})
-    .strict();
-const AnimationBlendTreeDirectSchema = z
-    .object({
-    type: z.literal('direct').describe('Each child has an explicit weight, normalized to sum to 1'),
-    // `parameter` is unused by direct blending (evaluateBlendTree never reads
-    // it for `type: 'direct'`) but kept required+defaulted so the parsed
-    // value stays structurally assignable to `BlendTreeDef`
-    // (`anim-graph-types.ts`), which declares `parameter: string` for every
-    // blend mode — the same convention that type already uses.
-    parameter: z.string().default(''),
-    children: z
-        .array(AnimationBlendChildSchema.extend({ weight: z.number().min(0) }))
-        .min(1, 'direct blend tree needs at least 1 child'),
-})
-    .strict();
-export const AnimationBlendTreeSchema = z.discriminatedUnion('type', [
-    AnimationBlendTree1DSchema,
-    AnimationBlendTree2DSchema,
-    AnimationBlendTreeDirectSchema,
-]);
-// ---------------------------------------------------------------------------
-// Crossfade / blend-in-out metadata (shared by clip and blend-tree states)
-// ---------------------------------------------------------------------------
-const AnimationCrossfadeMetaSchema = z
-    .object({
-    duration: z
-        .number()
-        .min(0)
-        .default(0)
-        .describe('Seconds to blend from the previously active clip into this state on entry, applied via ' +
-        'native `AnimationAction.crossFadeTo`/`fadeIn` (E2). 0 = instant activation, no fade.'),
-    warp: z
-        .boolean()
-        .default(false)
-        .describe("Passed through to AnimationAction.crossFadeTo's `warp` param — linearly warps timeScale " +
-        'across the two clips during the blend so differing clip lengths line up. Default false.'),
-})
-    .strict()
-    .describe('Blend-in/out/crossfade timing for entering this state');
-const AnimationBoneMaskSchema = z
-    .object({
-    include: z
-        .array(z.string().min(1))
-        .min(1)
-        .optional()
-        .describe('Bone/object names whose complete descendant subtrees are retained'),
-    exclude: z
-        .array(z.string().min(1))
-        .min(1)
-        .optional()
-        .describe('Bone/object names whose complete descendant subtrees are removed'),
-})
-    .strict()
-    .refine((mask) => Boolean(mask.include?.length || mask.exclude?.length), {
-    message: 'boneMask needs at least one include or exclude bone name',
-})
-    .describe('Filters animation tracks by named Object3D/Bone subtrees');
-const AnimationLayerFields = {
-    layer: z
-        .string()
-        .min(1)
-        .optional()
-        .describe('Composition layer name; omitted means the single base layer'),
-    weight: z
-        .number()
-        .min(0)
-        .max(1)
-        .optional()
-        .describe('Layer weight multiplier from 0 to 1; defaults to 1'),
-    blendMode: z
-        .enum(['override', 'additive'])
-        .optional()
-        .describe('Native Three normal/override or additive action blending; defaults to override'),
-    boneMask: AnimationBoneMaskSchema.optional().describe('Optional include/exclude filter applied to every clip track in this state'),
-};
-// ---------------------------------------------------------------------------
-// Per-state animation metadata: single clip OR blend tree, plus crossfade
-// ---------------------------------------------------------------------------
-const ClipAnimationMetaSchema = z
-    .object({
-    clip: z.string().min(1).describe('Single clip to play while this XState state is active'),
-    loop: z
-        .boolean()
-        .default(true)
-        .describe('Loop the clip (THREE.LoopRepeat) vs play once (THREE.LoopOnce, clamped on last frame)'),
-    speed: z
-        .number()
-        .positive()
-        .default(1)
-        .describe('Playback speed multiplier (AnimationAction.timeScale)'),
-    crossfade: AnimationCrossfadeMetaSchema.optional(),
-    ...AnimationLayerFields,
-})
-    .strict();
-const BlendTreeAnimationMetaSchema = z
-    .object({
-    blendTree: AnimationBlendTreeSchema.describe('Multiple clips blended by a live context/selector-driven parameter'),
-    crossfade: AnimationCrossfadeMetaSchema.optional(),
-    ...AnimationLayerFields,
-})
-    .strict();
-/**
- * The full shape of `state.meta.animation` for one XState state (spec §5.6):
- * exactly one of a single clip or a blend tree, plus optional crossfade
- * timing. `.strict()` on both branches is what makes authoring a transition
- * keyword (`on`, `target`, `guard`, …) inside `meta.animation` a validation
- * error instead of a silently-accepted second transition dialect.
- */
-export const StateAnimationMetaSchema = z.union([
-    ClipAnimationMetaSchema,
-    BlendTreeAnimationMetaSchema,
-]);
-/** True iff a validated meta declares a single clip rather than a blend tree. */
-export function isClipAnimationMeta(meta) {
-    return 'clip' in meta;
-}
-/** True iff a validated meta declares a blend tree rather than a single clip. */
-export function isBlendTreeAnimationMeta(meta) {
-    return 'blendTree' in meta;
-}
-// ---------------------------------------------------------------------------
-// Validation entry point
-// ---------------------------------------------------------------------------
-/** Thrown by `parseStateAnimationMeta` — always names the offending state id. */
-export class AnimationMetaValidationError extends Error {
-    stateId;
-    issues;
-    constructor(message, stateId, issues) {
-        super(message);
-        this.stateId = stateId;
-        this.issues = issues;
-        this.name = 'AnimationMetaValidationError';
-    }
-}
-/**
- * Validate one state's `meta.animation` value. Called by the E2 binding for
- * every state a machine declares (both at bind time, up front, and — for
- * belt-and-suspenders — again whenever a state is entered).
- *
- * @throws {AnimationMetaValidationError} naming the state id and every Zod
- *   issue (path + message) — e.g. an unrecognized `on`/`target` key, a
- *   missing `clip`, or a 1D blend tree with only one child.
- */
-export function parseStateAnimationMeta(stateId, raw) {
-    const result = StateAnimationMetaSchema.safeParse(raw);
-    if (!result.success) {
-        const detail = result.error.issues
-            .map((issue) => `${issue.path.length ? issue.path.join('.') : '(root)'}: ${issue.message}`)
-            .join('; ');
-        throw new AnimationMetaValidationError(`[xstate-animation] invalid meta.animation for state "${stateId}": ${detail}`, stateId, result.error.issues);
-    }
-    return result.data;
-}
-/**
- * Walk every state node in a machine (from its root `StateNode`, e.g.
- * `actor.logic.root`) and validate every `meta.animation` value found.
- * States with no `meta.animation` are skipped (not every XState state needs
- * to drive animation). Returns one entry per animated state, in document
- * order.
- *
- * @throws {AnimationMetaValidationError} on the FIRST invalid meta found —
- *   naming the specific state id, so an agent authoring a machine gets an
- *   actionable pointer straight to the bad state instead of a generic error.
- */
-export function collectMachineAnimationMeta(root) {
-    const out = [];
-    const visit = (node) => {
-        if (node.meta && 'animation' in node.meta && node.meta.animation !== undefined) {
-            out.push({ stateId: node.id, meta: parseStateAnimationMeta(node.id, node.meta.animation) });
-        }
-        for (const child of Object.values(node.states ?? {}))
-            visit(child);
-    };
-    visit(root);
-    return out;
-}
-/** Every clip name referenced anywhere in a validated meta (1 for clip states, N for blend trees). */
-export function clipNamesOf(meta) {
-    return isClipAnimationMeta(meta) ? [meta.clip] : meta.blendTree.children.map((c) => c.clip);
-}

package/dist/assets.d.ts

@@ -1,26 +0,0 @@
-/**
- * Shared asset cache — URL-keyed, deduplicating loader for GLTF and JSON.
- *
- * Inspired by Unity's Resources.Load / Godot's load():
- *   assets.load<T>(url)  — async, returns Promise<T>, deduplicates concurrent loads
- *   assets.get<T>(url)   — sync, returns T, throws if not yet loaded
- *
- * GLTF files (.glb/.gltf) resolve to GLTFResult.
- * JSON files resolve to the parsed object (caller provides type via generic).
- *
- * Cache lives for the app lifetime — no dispose needed.
- */
-import type * as THREE from 'three';
-/** Result of loading a .glb/.gltf file. */
-export interface GLTFResult {
-    scene: THREE.Group;
-    animations: THREE.AnimationClip[];
-}
-export interface AssetCache {
-    /** Load an asset by URL. Returns a cached promise if already loading/loaded. */
-    load<T = unknown>(url: string): Promise<T>;
-    /** Get a previously-loaded asset synchronously. Throws if not yet loaded. */
-    get<T = unknown>(url: string): T;
-}
-export declare function createAssetCache(): AssetCache;
-//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,UAAU,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,gFAAgF;IAChF,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE3C,6EAA6E;IAC7E,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC;CAClC;AAED,wBAAgB,gBAAgB,IAAI,UAAU,CAiD7C"}

package/dist/assets.js

@@ -1,55 +0,0 @@
-/**
- * Shared asset cache — URL-keyed, deduplicating loader for GLTF and JSON.
- *
- * Inspired by Unity's Resources.Load / Godot's load():
- *   assets.load<T>(url)  — async, returns Promise<T>, deduplicates concurrent loads
- *   assets.get<T>(url)   — sync, returns T, throws if not yet loaded
- *
- * GLTF files (.glb/.gltf) resolve to GLTFResult.
- * JSON files resolve to the parsed object (caller provides type via generic).
- *
- * Cache lives for the app lifetime — no dispose needed.
- */
-import { gltfLoader, resolveUrl } from './loader';
-export function createAssetCache() {
-    const cache = new Map();
-    const resolved = new Map();
-    // Use the shared, DRACO-wired GLTFLoader (A2 / CB2) — no second loader instance.
-    // This cache keeps the parsed source GLTFResult (load/get semantics for gameplay
-    // code); it does NOT clone. Callers that need disposal-safe clones use
-    // scene/asset-loaders `loadGLTF`, which clones + tags `__sharedGeometry`.
-    function load(url) {
-        const existing = cache.get(url);
-        if (existing)
-            return existing;
-        let promise;
-        if (url.endsWith('.glb') || url.endsWith('.gltf')) {
-            promise = new Promise((resolve, reject) => {
-                gltfLoader.load(url, (gltf) => resolve({ scene: gltf.scene, animations: gltf.animations }), undefined, reject);
-            });
-        }
-        else if (url.endsWith('.json')) {
-            promise = fetch(resolveUrl(url)).then((r) => {
-                if (!r.ok)
-                    throw new Error(`Failed to fetch ${url}: ${r.status}`);
-                return r.json();
-            });
-        }
-        else {
-            throw new Error(`AssetCache: unsupported file type for "${url}"`);
-        }
-        const tracked = promise.then((value) => {
-            resolved.set(url, value);
-            return value;
-        });
-        cache.set(url, tracked);
-        return tracked;
-    }
-    function get(url) {
-        if (!resolved.has(url)) {
-            throw new Error(`AssetCache: "${url}" not loaded. Call load() first and await it.`);
-        }
-        return resolved.get(url);
-    }
-    return { load, get };
-}

package/dist/audio/index.d.ts

@@ -1,4 +0,0 @@
-export { bindClockToTone, type ToneClockBinding, type ToneClockBindingOptions, type ToneTransportLike, } from './tone-clock-binding';
-export { bridgeToneToThreeAudio, connectToneBusToMasterGain, resumeSharedAudio, type ToneAudioBridge, } from './tone-context';
-export { renderToneOffline, type ToneOfflineComposeFn, type ToneOfflineRenderRequest, type ToneOfflineRenderResult, } from './tone-offline-render';
-//# sourceMappingURL=index.d.ts.map

package/dist/audio/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audio/index.ts"],"names":[],"mappings":"AAqBA,OAAO,EACL,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,iBAAiB,EACjB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,iBAAiB,EACjB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC"}

package/dist/audio/index.js

@@ -1,24 +0,0 @@
-// Engine-core audio surface (spec §13 workstream G).
-//
-// G3 ("Replace or Relocate Procedural Audio Helpers") removed the former
-// `musical.ts`/`weapons.ts`/`impacts.ts`/`vehicle.ts`/`ambient.ts`/
-// `movement.ts`/`ui-sounds.ts` — raw-`AudioContext`/`Math.random`-driven
-// oscillator and noise-buffer SFX generators that were engine-owned but
-// non-spatial (they never touched `THREE.PositionalAudio`, so the "spatial
-// one-shot helper" exception in the G3 acceptance criteria does not apply to
-// them). Each was either relocated verbatim into the example project that
-// used it (`examples/{third-person,fps,third-person-arena,rts,vehicle}/src/
-// procedural-audio.ts`) or deleted as dead code with no shipped consumer
-// (`bassPulse`/`arpeggio`/`gunshot`/`laser`/`bounce`/`crash`/`explosion`/
-// `tireSkid`/`wind`/`rain`/`hum`/`nature`/`uiHover`/`uiError`). The canonical
-// replacements — a procedural-music example built directly on Tone's own API
-// and a spatial-audio example built directly on `THREE.PositionalAudio` — are
-// `examples/audio-showcase`.
-//
-// What remains here is the genuine engine-core audio capability: the G1/G2
-// Tone↔Three context bridge and offline render (`wav-encode.ts`, the G4
-// PCM->WAV encoder, is consumed by its own module path, not this barrel — see
-// `packages/engine/src/runtime/render-audio-control.ts`).
-export { bindClockToTone, } from './tone-clock-binding';
-export { bridgeToneToThreeAudio, connectToneBusToMasterGain, resumeSharedAudio, } from './tone-context';
-export { renderToneOffline, } from './tone-offline-render';

package/dist/audio/tone-clock-binding.d.ts

@@ -1,75 +0,0 @@
-import type { AnimationClock } from '../animation/animation-clock';
-import type { SystemPhaseName } from '../core/types';
-/**
- * G2 — Integrate Tone with the Canonical Clock, preview/real-time half
- * (spec §13 G2, §10 D1). Mirrors `animation/theatre-clock-binding.ts`'s D2
- * pattern exactly, on purpose: the canonical `AnimationClock` is the single
- * source of truth for "what time is it", and every participating system
- * (Theatre's sequence position, a registered GSAP timeline, and — here — a
- * Tone transport) is seeked to match it on every clock crossing. Tone must
- * never be left to free-run its own real-time clock while participating in
- * a cinematic, for the exact same reason Theatre isn't: deterministic
- * export, offline scrubbing, and no wall-clock dependency
- * (`animation-clock.ts`'s module doc explains why in full).
- *
- * ## Why setting `transport.seconds` is enough
- *
- * Setting `Tone.getTransport().seconds` repositions the transport's
- * playhead synchronously; it does not itself start real-time ticking (that
- * still requires an explicit `transport.start()`, which this binding
- * deliberately never calls — see the module doc on `animation-clock.ts` for
- * why nothing in this codebase is allowed to drive its own
- * `requestAnimationFrame`/wall-clock loop). A clock-seeked Tone transport is
- * a pure function of `clock.time`, exactly like a Theatre sequence's
- * `position` setter.
- *
- * ## Structural (not nominal) transport typing
- *
- * `ToneTransportLike` intentionally types only the ONE property this
- * binding touches (`seconds`), the same narrowing discipline
- * `runtime/render-control.ts`'s `SeekableClock` uses for the canonical
- * clock. `Tone.getTransport()`'s real `TransportClass` satisfies this
- * structurally with no adapter — pass it directly at the real call site.
- * The narrow type is also what makes this binding's own unit tests real
- * (not mocked-away): `packages/engine/test/audio/tone-clock-binding.test.ts`
- * exercises the FULL seek/pause/loop/time-scale matrix against a real
- * `AnimationClock` and a plain `{ seconds: number }` object — no Tone
- * import, no `AudioContext`, and it still proves the exact behavior a real
- * `Tone.Transport` will see, because `TransportClass` IS a
- * `ToneTransportLike` at the type level.
- */
-export interface ToneTransportLike {
-    seconds: number;
-}
-export interface ToneClockBindingOptions {
-    /**
-     * Which `AnimationClock` phase to seek the transport in. Defaults to
-     * `'animation'` — the same phase `theatre-clock-binding.ts` uses by
-     * default, so a Theatre sequence and a Tone transport bound to the same
-     * clock stay in lockstep with each other (`PHASE_ORDER`-then-registration-
-     * order — see `animation-clock.ts`'s `subscribe` doc comment).
-     */
-    phase?: SystemPhaseName;
-}
-export interface ToneClockBinding {
-    /** Removes the clock evaluator. No further `transport.seconds` writes
-     *  occur after this — the transport is left at whatever position it was
-     *  last seeked to (matches `TheatreClockBinding.dispose`'s contract). */
-    dispose(): void;
-}
-/**
- * Subscribe `transport.seconds = clock.time` to every crossing of `clock`
- * in the given phase (default `'animation'`). Returns a disposer; call it
- * to stop driving the transport (e.g. on `GameCleanup.dispose()`, or before
- * rebinding on hot reload — this is what keeps HMR from accumulating
- * duplicate listeners).
- *
- * Only call this for a Tone composition that PARTICIPATES in a cinematic
- * (spec G2 AC). Ordinary, non-cinematic game music should drive Tone's own
- * real-time transport directly (`transport.start()`, `Tone.Transport.bpm`,
- * etc. — see `tone-context.ts`'s "escape hatch" section) and must NEVER be
- * bound here, since a bound transport's position is entirely clock-driven
- * and `start()`/`stop()` calls on it would fight this binding's writes.
- */
-export declare function bindClockToTone(clock: AnimationClock, transport: ToneTransportLike, options?: ToneClockBindingOptions): ToneClockBinding;
-//# sourceMappingURL=tone-clock-binding.d.ts.map

package/dist/audio/tone-clock-binding.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tone-clock-binding.d.ts","sourceRoot":"","sources":["../../src/audio/tone-clock-binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,8BAA8B,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;6EAEyE;IACzE,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,iBAAiB,EAC5B,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CAelB"}

package/dist/audio/tone-clock-binding.js

@@ -1,29 +0,0 @@
-/**
- * Subscribe `transport.seconds = clock.time` to every crossing of `clock`
- * in the given phase (default `'animation'`). Returns a disposer; call it
- * to stop driving the transport (e.g. on `GameCleanup.dispose()`, or before
- * rebinding on hot reload — this is what keeps HMR from accumulating
- * duplicate listeners).
- *
- * Only call this for a Tone composition that PARTICIPATES in a cinematic
- * (spec G2 AC). Ordinary, non-cinematic game music should drive Tone's own
- * real-time transport directly (`transport.start()`, `Tone.Transport.bpm`,
- * etc. — see `tone-context.ts`'s "escape hatch" section) and must NEVER be
- * bound here, since a bound transport's position is entirely clock-driven
- * and `start()`/`stop()` calls on it would fight this binding's writes.
- */
-export function bindClockToTone(clock, transport, options = {}) {
-    const phase = options.phase ?? 'animation';
-    const handle = clock.subscribe(phase, (crossing) => {
-        transport.seconds = crossing.currentTime;
-    });
-    let disposed = false;
-    return {
-        dispose() {
-            if (disposed)
-                return;
-            disposed = true;
-            handle.dispose();
-        },
-    };
-}

package/dist/audio/tone-context.d.ts

@@ -1,114 +0,0 @@
-import type { ToneAudioNode } from 'tone';
-/**
- * G1 — Establish Audio Ownership (spec §13 G1, §3.6, §4).
- *
- * ## The boundary
- *
- * Two independent, native-vocabulary audio systems coexist in every VGAI
- * game, each with a genuinely different job. This module does not wrap
- * either one — it only decides who owns which native `AudioContext` and how
- * the two graphs meet:
- *
- *  - **Three/Web Audio** (`setup/setup-audio.ts`) remains authoritative for
- *    SPATIAL audio: `THREE.AudioListener` (attached to the active camera)
- *    and `THREE.Audio`/`THREE.PositionalAudio` sources. (G3, a later unit,
- *    has since removed the non-spatial engine-owned one-shot procedural
- *    helpers this comment used to name here — `audio/impacts.ts`,
- *    `audio/weapons.ts`, `audio/ambient.ts`, and their siblings — relocating
- *    each into the example project that used it, or deleting it as dead code;
- *    see `packages/engine/src/audio/index.ts`'s header comment and
- *    `examples/audio-showcase` for the canonical native-Tone/native-Three
- *    replacements. This module's own boundary/bridge is unchanged by that
- *    unit.)
- *  - **Tone.js** owns musical transport, tempo, scheduling, synthesis, and
- *    procedural composition — imported and used with its OWN native API
- *    (`new Tone.Synth()`, `Tone.getTransport()`, `Tone.Offline(...)`,
- *    `Tone.getContext()`), never through a VGAI-renamed wrapper (spec §1's
- *    native-library rule). See `packages/engine/test/audio/tone-context.test.ts`
- *    for a direct, unwrapped usage example.
- *
- * ## Why they must share one native `AudioContext`
- *
- * Both systems ultimately talk to exactly one hardware output. If Tone ran
- * its own independently-created `AudioContext` alongside
- * `THREE.AudioListener`'s, they would: fight over autoplay-policy resume
- * state (two contexts, two `state`s, two places a "click to start audio"
- * gesture would need to unlock); produce TWO separate graphs that a single
- * mute/volume control cannot coherently silence; and — fatally for G4/I6 —
- * make deterministic offline capture impossible to align with the video's
- * frame-addressed render range, since there would be no single graph whose
- * lifecycle (suspend/resume/close) the render/capture harness can reason
- * about.
- *
- * `bridgeToneToThreeAudio` fixes this: it points Tone's global context
- * (`Tone.setContext`) at the SAME native `AudioContext` instance
- * `THREE.AudioListener` already created (`setupAudio(camera).listener.context`,
- * `setup/setup-audio.ts`). After bridging,
- * `Tone.getContext().rawContext === threeListener.context` — there is
- * exactly one native context. One `.resume()`/`.suspend()` call (or
- * `Tone.start()`, which does both) affects both systems, and routing a Tone
- * bus into `setupAudio()`'s `masterGain` (see `connectToneBusToMasterGain`
- * below) puts Tone's output under the SAME mute/master-volume control as
- * every `THREE.Audio` source.
- *
- * ## What this module does NOT do
- *
- * It does not create an `AudioContext` (that remains `setupAudio`'s job —
- * call `bridgeToneToThreeAudio` AFTER `setupAudio(camera)`, before
- * constructing any Tone node: Tone nodes built against the PREVIOUS global
- * context are not retroactively migrated — Tone's own `setContext` contract,
- * not a VGAI limitation). It does not wrap any Tone class, and it does not
- * touch THREE's audio path at all. G3 (a later unit) is where engine-owned
- * procedural helpers get rewritten directly on Tone or relocated to game
- * code — this module only owns the context boundary + bridge.
- *
- * ## Escape hatch — ordinary (non-cinematic) game music
- *
- * None of the above requires participating in a cinematic. Once bridged,
- * ordinary game music can drive Tone's REAL real-time transport exactly as
- * Tone's own docs describe — `Tone.getTransport().bpm.value = 128`,
- * `Tone.getTransport().start()`, `new Tone.Sequence(...).start(0)`, etc. —
- * with no VGAI involvement at all. `tone-clock-binding.ts` (G2) is opt-in,
- * only for the case where a Tone composition must stay in lockstep with the
- * canonical `AnimationClock` because it participates in a cinematic.
- */
-/** Result of {@link bridgeToneToThreeAudio} — the shared native context plus
- *  a re-checkable assertion, so a caller/test doesn't need to re-derive the
- *  bridging logic to confirm it still holds later. */
-export interface ToneAudioBridge {
-    /** The native `AudioContext` Tone and `THREE.AudioListener` now share. */
-    readonly context: AudioContext;
-    /** True iff `Tone.getContext().rawContext` is still exactly `context`
-     *  (identity, not equality — proves ONE shared native context, not two
-     *  compatible-looking ones). */
-    isBridged(): boolean;
-}
-/**
- * Point Tone's global context at `context` (typically
- * `setupAudio(camera).listener.context` from `setup/setup-audio.ts`). Call
- * this once per game boot, after `setupAudio(camera)`, before constructing
- * any Tone node.
- */
-export declare function bridgeToneToThreeAudio(context: AudioContext): ToneAudioBridge;
-/**
- * Route a Tone output node (a bus, `Tone.getDestination()`, or any
- * `Tone.Gain` used as a submix) into the SAME `masterGain`
- * `setupAudio()` created, so Tone output is silenced/attenuated by the
- * identical mute/volume control as every `THREE.Audio`/`THREE.PositionalAudio`
- * source. `toneNode` is Tone's own `ToneAudioNode` type (no VGAI wrapper);
- * `masterGain` is the plain native `GainNode` `setupAudio()` already
- * returns — Tone's `.connect()` natively accepts a raw `AudioNode` as its
- * destination, so no adapter node is needed on either side.
- */
-export declare function connectToneBusToMasterGain(toneNode: ToneAudioNode, masterGain: GainNode): void;
-/**
- * Resume the shared context after a user gesture. Because
- * {@link bridgeToneToThreeAudio} guarantees Tone and THREE share the
- * identical native context, calling `Tone.start()` — which both resumes the
- * context AND runs Tone's own autoplay-unlock bookkeeping (a silent-buffer
- * trick required on some browsers) — is sufficient to unstick BOTH systems;
- * a separate `context.resume()` call on the THREE side is redundant once
- * bridged, not required.
- */
-export declare function resumeSharedAudio(): Promise<void>;
-//# sourceMappingURL=tone-context.d.ts.map

package/dist/audio/tone-context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tone-context.d.ts","sourceRoot":"","sources":["../../src/audio/tone-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH;;sDAEsD;AACtD,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B;;oCAEgC;IAChC,SAAS,IAAI,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,YAAY,GAAG,eAAe,CAM7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,GAAG,IAAI,CAE9F;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEvD"}

package/dist/audio/tone-context.js

@@ -1,39 +0,0 @@
-import * as Tone from 'tone';
-/**
- * Point Tone's global context at `context` (typically
- * `setupAudio(camera).listener.context` from `setup/setup-audio.ts`). Call
- * this once per game boot, after `setupAudio(camera)`, before constructing
- * any Tone node.
- */
-export function bridgeToneToThreeAudio(context) {
-    Tone.setContext(context);
-    return {
-        context,
-        isBridged: () => Tone.getContext().rawContext === context,
-    };
-}
-/**
- * Route a Tone output node (a bus, `Tone.getDestination()`, or any
- * `Tone.Gain` used as a submix) into the SAME `masterGain`
- * `setupAudio()` created, so Tone output is silenced/attenuated by the
- * identical mute/volume control as every `THREE.Audio`/`THREE.PositionalAudio`
- * source. `toneNode` is Tone's own `ToneAudioNode` type (no VGAI wrapper);
- * `masterGain` is the plain native `GainNode` `setupAudio()` already
- * returns — Tone's `.connect()` natively accepts a raw `AudioNode` as its
- * destination, so no adapter node is needed on either side.
- */
-export function connectToneBusToMasterGain(toneNode, masterGain) {
-    toneNode.connect(masterGain);
-}
-/**
- * Resume the shared context after a user gesture. Because
- * {@link bridgeToneToThreeAudio} guarantees Tone and THREE share the
- * identical native context, calling `Tone.start()` — which both resumes the
- * context AND runs Tone's own autoplay-unlock bookkeeping (a silent-buffer
- * trick required on some browsers) — is sufficient to unstick BOTH systems;
- * a separate `context.resume()` call on the THREE side is redundant once
- * bridged, not required.
- */
-export async function resumeSharedAudio() {
-    await Tone.start();
-}