@sadhaka/loom-engine 0.10.0

package/dist/asset/sprite-sheet-loader.js

@@ -0,0 +1,313 @@
+// Loom Engine - sprite-sheet loader.
+//
+// Loads a PNG + JSON manifest pair from a URL and returns the
+// {image, frames} shape that IGraphicsDevice.registerAtlas accepts
+// directly. The engine never decides where assets come from; the
+// caller passes a manifest URL and the loader fetches both halves.
+//
+// Manifest schema (see assets/knight/walk.json for an example):
+//   {
+//     "name": "knight-walk",
+//     "image": "walk.png",         // sibling-relative URL of the PNG
+//     "frames": [
+//       { "x":0, "y":0, "w":16, "h":32, "name":"walk_pass_a", "duration_ms":140 },
+//       ...
+//     ],
+//     "anchor": { "x": 8, "y": 32 },
+//     "fps": 8
+//   }
+//
+// PRIOR-ART.md cites the Aseprite "JSON-Array" export and the
+// TexturePacker "JSON-array" format as inspiration for the shape.
+// We do not parse either format directly; we use a small superset
+// (per-frame name + duration_ms + sheet anchor + fps) tailored to
+// the engine's animation needs.
+// Errors thrown by the loader. All carry a `kind` so callers can
+// branch on the failure mode without parsing message strings.
+export class SpriteSheetLoadError extends Error {
+    kind;
+    url;
+    constructor(kind, url, message, options) {
+        super(`SpriteSheetLoadError[${kind}] ${url}: ${message}`, options);
+        this.name = 'SpriteSheetLoadError';
+        this.kind = kind;
+        this.url = url;
+    }
+}
+// Default browser-side image decoder. Creates an <img>, sets src to
+// a blob: URL, and resolves on load. Throws SpriteSheetLoadError
+// with kind='decode-image' on failure.
+function defaultDecodeImage(bytes, url) {
+    return new Promise((resolve, reject) => {
+        const blob = new Blob([bytes], { type: 'image/png' });
+        const objectUrl = URL.createObjectURL(blob);
+        const img = new Image();
+        img.onload = () => {
+            URL.revokeObjectURL(objectUrl);
+            resolve(img);
+        };
+        img.onerror = (err) => {
+            URL.revokeObjectURL(objectUrl);
+            reject(new SpriteSheetLoadError('decode-image', url, 'Image element failed to decode the PNG bytes', { cause: err }));
+        };
+        img.src = objectUrl;
+    });
+}
+// Resolve a sibling-relative image path against the manifest URL.
+// "walk.png" alongside ".../knight/walk.json" -> ".../knight/walk.png".
+// Absolute URLs and "/abs/path" pass through unchanged.
+function resolveImageUrl(manifestUrl, imagePath) {
+    // URL constructor handles both absolute and relative inputs as long
+    // as we have a base. In Node (no DOM, no document) the manifestUrl
+    // must be absolute (file://, http(s)://); in the browser the
+    // Document base does the work.
+    try {
+        return new URL(imagePath, manifestUrl).toString();
+    }
+    catch {
+        // Fallback: simple sibling-replace. Strip the manifest filename
+        // and append the image filename. This handles bare relative paths
+        // when no URL constructor base is reachable.
+        const slash = manifestUrl.lastIndexOf('/');
+        if (slash < 0)
+            return imagePath;
+        return manifestUrl.slice(0, slash + 1) + imagePath;
+    }
+}
+// Validate a parsed JSON object against the manifest schema. Returns
+// the typed manifest or throws SpriteSheetLoadError. We do not pull
+// in a schema library; the engine ships zero runtime deps.
+function validateManifest(raw, url) {
+    if (!raw || typeof raw !== 'object') {
+        throw new SpriteSheetLoadError('invalid-manifest', url, 'manifest is not an object');
+    }
+    const m = raw;
+    if (typeof m['name'] !== 'string' || m['name'].length === 0) {
+        throw new SpriteSheetLoadError('invalid-manifest', url, 'name must be a non-empty string');
+    }
+    if (typeof m['image'] !== 'string' || m['image'].length === 0) {
+        throw new SpriteSheetLoadError('invalid-manifest', url, 'image must be a non-empty string');
+    }
+    if (!Array.isArray(m['frames']) || m['frames'].length === 0) {
+        throw new SpriteSheetLoadError('invalid-manifest', url, 'frames must be a non-empty array');
+    }
+    const frames = [];
+    for (let i = 0; i < m['frames'].length; i++) {
+        const fRaw = m['frames'][i];
+        if (!fRaw || typeof fRaw !== 'object') {
+            throw new SpriteSheetLoadError('invalid-manifest', url, `frame[${i}] is not an object`);
+        }
+        const f = fRaw;
+        const x = f['x'];
+        const y = f['y'];
+        const w = f['w'];
+        const h = f['h'];
+        if (typeof x !== 'number' ||
+            typeof y !== 'number' ||
+            typeof w !== 'number' ||
+            typeof h !== 'number') {
+            throw new SpriteSheetLoadError('invalid-manifest', url, `frame[${i}] must have numeric x, y, w, h`);
+        }
+        if (w <= 0 || h <= 0) {
+            throw new SpriteSheetLoadError('invalid-manifest', url, `frame[${i}] w and h must be positive`);
+        }
+        const frame = { x, y, w, h };
+        if (typeof f['name'] === 'string')
+            frame.name = f['name'];
+        if (typeof f['duration_ms'] === 'number')
+            frame.duration_ms = f['duration_ms'];
+        frames.push(frame);
+    }
+    // Anchor defaults to bottom-center of the first frame if not given.
+    let anchor;
+    const aRaw = m['anchor'];
+    if (aRaw && typeof aRaw === 'object') {
+        const a = aRaw;
+        if (typeof a['x'] !== 'number' || typeof a['y'] !== 'number') {
+            throw new SpriteSheetLoadError('invalid-manifest', url, 'anchor.x and anchor.y must be numeric when anchor is present');
+        }
+        anchor = { x: a['x'], y: a['y'] };
+    }
+    else {
+        const f0 = frames[0];
+        anchor = { x: f0.w / 2, y: f0.h };
+    }
+    // fps optional, defaults to 8 (matches the v1 walk-cycle cadence).
+    let fps = 8;
+    if (m['fps'] !== undefined) {
+        if (typeof m['fps'] !== 'number' || m['fps'] <= 0) {
+            throw new SpriteSheetLoadError('invalid-manifest', url, 'fps must be a positive number');
+        }
+        fps = m['fps'];
+    }
+    // Clips optional. When absent, synthesize a 'default' clip that
+    // walks all frames in order, looping. When present, validate that
+    // each clip has a non-empty frames[] of integer indices in range
+    // and a boolean loop flag.
+    let clips;
+    if (m['clips'] === undefined) {
+        const defaultFrames = [];
+        for (let i = 0; i < frames.length; i++)
+            defaultFrames.push(i);
+        clips = [{ name: 'default', frames: defaultFrames, loop: true }];
+    }
+    else {
+        if (!Array.isArray(m['clips'])) {
+            throw new SpriteSheetLoadError('invalid-manifest', url, 'clips must be an array when present');
+        }
+        clips = [];
+        for (let ci = 0; ci < m['clips'].length; ci++) {
+            const cRaw = m['clips'][ci];
+            if (!cRaw || typeof cRaw !== 'object') {
+                throw new SpriteSheetLoadError('invalid-manifest', url, `clips[${ci}] is not an object`);
+            }
+            const c = cRaw;
+            if (typeof c['name'] !== 'string' || c['name'].length === 0) {
+                throw new SpriteSheetLoadError('invalid-manifest', url, `clips[${ci}].name must be a non-empty string`);
+            }
+            if (!Array.isArray(c['frames']) || c['frames'].length === 0) {
+                throw new SpriteSheetLoadError('invalid-manifest', url, `clips[${ci}].frames must be a non-empty array`);
+            }
+            const clipFrames = [];
+            for (let fi = 0; fi < c['frames'].length; fi++) {
+                const v = c['frames'][fi];
+                if (typeof v !== 'number' || !Number.isInteger(v) || v < 0 || v >= frames.length) {
+                    throw new SpriteSheetLoadError('invalid-manifest', url, `clips[${ci}].frames[${fi}] must be an integer in [0, ${frames.length})`);
+                }
+                clipFrames.push(v);
+            }
+            if (typeof c['loop'] !== 'boolean') {
+                throw new SpriteSheetLoadError('invalid-manifest', url, `clips[${ci}].loop must be boolean`);
+            }
+            const clip = { name: c['name'], frames: clipFrames, loop: c['loop'] };
+            if (c['fps'] !== undefined) {
+                if (typeof c['fps'] !== 'number' || c['fps'] <= 0) {
+                    throw new SpriteSheetLoadError('invalid-manifest', url, `clips[${ci}].fps must be a positive number when present`);
+                }
+                clip.fps = c['fps'];
+            }
+            if (c['durations_ms'] !== undefined) {
+                if (!Array.isArray(c['durations_ms']) || c['durations_ms'].length !== clipFrames.length) {
+                    throw new SpriteSheetLoadError('invalid-manifest', url, `clips[${ci}].durations_ms must be an array of length ${clipFrames.length} when present`);
+                }
+                const durs = [];
+                for (let di = 0; di < c['durations_ms'].length; di++) {
+                    const d = c['durations_ms'][di];
+                    if (typeof d !== 'number' || d <= 0) {
+                        throw new SpriteSheetLoadError('invalid-manifest', url, `clips[${ci}].durations_ms[${di}] must be a positive number`);
+                    }
+                    durs.push(d);
+                }
+                clip.durations_ms = durs;
+            }
+            clips.push(clip);
+        }
+        if (clips.length === 0) {
+            throw new SpriteSheetLoadError('invalid-manifest', url, 'clips must be non-empty when present');
+        }
+    }
+    return {
+        name: m['name'],
+        image: m['image'],
+        frames,
+        anchor,
+        fps,
+        clips,
+    };
+}
+// Load a sprite sheet from a manifest URL. Fetches the JSON, then
+// the PNG referenced by the manifest's "image" field (resolved
+// sibling-relative to the manifest URL), then decodes the image and
+// returns a LoadedSpriteSheet.
+//
+// The returned `atlas` is shaped exactly for IGraphicsDevice.registerAtlas:
+//   const sheet = await loadSpriteSheet('/assets/knight/walk.json');
+//   const handle = device.registerAtlas(sheet.atlas);
+export async function loadSpriteSheet(manifestUrl, options = {}) {
+    const fetchImpl = options.fetchImpl ?? (typeof fetch !== 'undefined' ? fetch : undefined);
+    if (!fetchImpl) {
+        throw new SpriteSheetLoadError('fetch-manifest', manifestUrl, 'no fetch implementation available; pass options.fetchImpl');
+    }
+    const decodeImage = options.decodeImage ?? defaultDecodeImage;
+    // 1. Fetch + parse manifest.
+    let manifestResp;
+    try {
+        manifestResp = await fetchImpl(manifestUrl);
+    }
+    catch (err) {
+        throw new SpriteSheetLoadError('fetch-manifest', manifestUrl, 'network error', { cause: err });
+    }
+    if (!manifestResp.ok) {
+        throw new SpriteSheetLoadError('fetch-manifest', manifestUrl, `HTTP ${manifestResp.status} ${manifestResp.statusText}`);
+    }
+    let raw;
+    try {
+        raw = await manifestResp.json();
+    }
+    catch (err) {
+        throw new SpriteSheetLoadError('parse-manifest', manifestUrl, 'response is not valid JSON', { cause: err });
+    }
+    const manifest = validateManifest(raw, manifestUrl);
+    // 2. Fetch + decode image.
+    const imageUrl = resolveImageUrl(manifestUrl, manifest.image);
+    let imageResp;
+    try {
+        imageResp = await fetchImpl(imageUrl);
+    }
+    catch (err) {
+        throw new SpriteSheetLoadError('fetch-image', imageUrl, 'network error', { cause: err });
+    }
+    if (!imageResp.ok) {
+        throw new SpriteSheetLoadError('fetch-image', imageUrl, `HTTP ${imageResp.status} ${imageResp.statusText}`);
+    }
+    const bytes = await imageResp.arrayBuffer();
+    const image = await decodeImage(bytes, imageUrl);
+    // 3. Compose AtlasDescriptor (only fields the device reads).
+    const atlas = {
+        image,
+        frames: manifest.frames.map((f) => ({ x: f.x, y: f.y, w: f.w, h: f.h })),
+        name: manifest.name,
+    };
+    return { manifest, image, atlas };
+}
+// Compute the active frame index for a time-driven walk cycle. Use
+// per-frame duration_ms if every frame has it, otherwise fall back
+// to manifest.fps. Returns an integer in [0, frames.length).
+//
+// `now` is a monotonic millisecond clock (typically performance.now()
+// in the browser or process.hrtime() bigint -> ms in Node). `start`
+// is the t0 the caller stored when the animation began.
+export function computeFrameIndex(manifest, now, start) {
+    const n = manifest.frames.length;
+    if (n <= 1)
+        return 0;
+    // Sum per-frame durations if available. Mixed manifests (some
+    // frames with duration_ms, some without) fall back to fps.
+    let totalDuration = 0;
+    let allHaveDuration = true;
+    for (let i = 0; i < n; i++) {
+        const d = manifest.frames[i]?.duration_ms;
+        if (typeof d === 'number' && d > 0) {
+            totalDuration += d;
+        }
+        else {
+            allHaveDuration = false;
+            break;
+        }
+    }
+    const elapsed = Math.max(0, now - start);
+    if (allHaveDuration) {
+        const t = elapsed % totalDuration;
+        let acc = 0;
+        for (let i = 0; i < n; i++) {
+            acc += manifest.frames[i].duration_ms;
+            if (t < acc)
+                return i;
+        }
+        return n - 1; // safety
+    }
+    // Uniform-fps fallback.
+    const frameMs = 1000 / manifest.fps;
+    return Math.floor(elapsed / frameMs) % n;
+}
+//# sourceMappingURL=sprite-sheet-loader.js.map

package/dist/asset/sprite-sheet-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite-sheet-loader.js","sourceRoot":"","sources":["../../src/asset/sprite-sheet-loader.ts"],"names":[],"mappings":"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"}

package/dist/audio/audio-bus.d.ts

@@ -0,0 +1,43 @@
+export type BusPriority = 'essential' | 'ambient';
+export interface BusOptions {
+    initialGain?: number;
+    priority?: BusPriority;
+}
+export declare const AUDIO_BUDGET_AMBIENT_FLOOR = 0.25;
+export declare const AUDIO_BUDGET_ESSENTIAL_FLOOR = 0.05;
+export declare class AudioBus {
+    readonly ctx: AudioContext;
+    private master;
+    private buses;
+    private masterGain;
+    private currentBudget;
+    private suspended;
+    private constructor();
+    static create(ctx?: AudioContext): AudioBus;
+    unlock(): Promise<void>;
+    isUnlocked(): boolean;
+    input(name: string): AudioNode;
+    hasBus(name: string): boolean;
+    addBus(name: string, opts?: BusOptions): void;
+    removeBus(name: string): void;
+    setMasterGain(gain: number): void;
+    getMasterGain(): number;
+    setBusGain(name: string, gain: number): void;
+    getBusGain(name: string): number;
+    setBusMuted(name: string, muted: boolean): void;
+    isBusMuted(name: string): boolean;
+    setAudioBudget(budget: number): void;
+    getAudioBudget(): number;
+    private applyBudgetToBus;
+    playOneShot(busName: string, buffer: AudioBuffer, options?: {
+        rate?: number;
+        gain?: number;
+    }): AudioBufferSourceNode | null;
+    playTone(busName: string, freq: number, durationMs: number, options?: {
+        gain?: number;
+        type?: OscillatorType;
+    }): void;
+    dispose(): void;
+}
+export declare const RESOURCE_AUDIO_BUS = "audio_bus";
+//# sourceMappingURL=audio-bus.d.ts.map

package/dist/audio/audio-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-bus.d.ts","sourceRoot":"","sources":["../../src/audio/audio-bus.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;AAElD,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAqBD,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAC/C,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,qBAAa,QAAQ;IACnB,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,SAAS,CAAiB;IAElC,OAAO;IAcP,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,YAAY,GAAG,QAAQ;IAarC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAe7B,UAAU,IAAI,OAAO;IAOrB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS;IAQ9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,IAAI;IAejD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAO7B,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKjC,aAAa,IAAI,MAAM;IAIvB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAO5C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIhC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAO/C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAOjC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAUpC,cAAc,IAAI,MAAM;IAIxB,OAAO,CAAC,gBAAgB;IAmBxB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,qBAAqB,GAAG,IAAI;IAoB/H,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,cAAc,CAAA;KAAO,GAAG,IAAI;IAuBzH,OAAO,IAAI,IAAI;CAOhB;AAID,eAAO,MAAM,kBAAkB,cAAc,CAAC"}

package/dist/audio/audio-bus.js

@@ -0,0 +1,258 @@
+// AudioBus - simple Web Audio mixer for the Loom Engine.
+//
+// Architecture:
+//   master (GainNode, output -> destination)
+//     |- 'sfx'   sub-bus
+//     |- 'music' sub-bus
+//     |- 'voice' sub-bus
+//     |- 'ui'    sub-bus
+//
+// Sub-buses are GainNodes that route into master. Sound-source code
+// connects an AudioNode to bus.input(name) and the bus handles routing
+// + per-bus gain + per-bus mute. New named buses can be created via
+// addBus(name, opts).
+//
+// Lazy unlock: browsers block AudioContext until the first user
+// gesture. AudioBus.create() does NOT auto-resume the context;
+// callers must call unlock() inside a click / touchstart / keydown
+// handler or use a UI prompt. Calling play* before unlock returns
+// silently with no error - production builds want a single warning
+// in the console; v1 keeps it quiet to avoid spam.
+//
+// VE-budget gating per LOOM-ENGINE-SPEC.md Section 3 / Phase 5: the
+// caller passes the VeilBudget audioBudget into setMasterAudioBudget
+// each tick (or on Director updates). When the budget drops below
+// the priority floor for a bus, that bus mutes. Default tier order:
+//   essential (always plays):    sfx, voice
+//   ambient (mutes under load):  music, ui
+//
+// Inspirations (per PRIOR-ART.md):
+//   Web Audio API W3C spec - public technique, no patent IP
+//   Gain bus pattern - canonical (FMOD, Wwise, Web Audio docs)
+//   Priority-tiered ducking - common in game audio engines, not
+//   patented as a pattern; Loom-specific is the VE-budget driver
+const DEFAULT_BUSES = [
+    { name: 'sfx', opts: { initialGain: 1.0, priority: 'essential' } },
+    { name: 'music', opts: { initialGain: 0.6, priority: 'ambient' } },
+    { name: 'voice', opts: { initialGain: 1.0, priority: 'essential' } },
+    { name: 'ui', opts: { initialGain: 0.8, priority: 'ambient' } },
+];
+// Budget thresholds. When VeilBudget.audioBudget drops below the
+// 'ambient' threshold, ambient buses mute. When it drops below
+// 'essential', everything mutes (engine still runs in silence).
+// These are arbitrary scalars; the Director's budget value should be
+// in [0, 1] where 1 is "all good".
+export const AUDIO_BUDGET_AMBIENT_FLOOR = 0.25;
+export const AUDIO_BUDGET_ESSENTIAL_FLOOR = 0.05;
+export class AudioBus {
+    ctx;
+    master;
+    buses = new Map();
+    masterGain = 1;
+    currentBudget = 1.0;
+    suspended = true;
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.master = ctx.createGain();
+        this.master.gain.value = this.masterGain;
+        this.master.connect(ctx.destination);
+        for (const def of DEFAULT_BUSES) {
+            this.addBus(def.name, def.opts);
+        }
+    }
+    // Construct from an existing AudioContext (tests pass mocks) or
+    // let the bus create one. Browser autoplay policy means the new
+    // context starts suspended.
+    static create(ctx) {
+        if (ctx) {
+            return new AudioBus(ctx);
+        }
+        if (typeof AudioContext === 'undefined') {
+            throw new Error('AudioBus.create: AudioContext is unavailable in this environment');
+        }
+        return new AudioBus(new AudioContext());
+    }
+    // Resume the AudioContext after a user gesture. Returns a promise
+    // that settles when the context is running. Calling more than once
+    // is safe.
+    async unlock() {
+        if (this.ctx.state === 'running') {
+            this.suspended = false;
+            return;
+        }
+        try {
+            await this.ctx.resume();
+            this.suspended = this.ctx.state !== 'running';
+        }
+        catch {
+            // Already-suspended contexts that fail resume are usually a
+            // policy issue; nothing the engine can do beyond surface it.
+            this.suspended = true;
+        }
+    }
+    isUnlocked() {
+        return !this.suspended && this.ctx.state === 'running';
+    }
+    // Public: a node a sound source connects to so the bus routes its
+    // output through master. Returns the bus's input GainNode; users
+    // call audioSource.connect(bus.input('sfx')).
+    input(name) {
+        const entry = this.buses.get(name);
+        if (!entry) {
+            throw new Error('AudioBus.input: unknown bus "' + name + '"');
+        }
+        return entry.node;
+    }
+    hasBus(name) {
+        return this.buses.has(name);
+    }
+    addBus(name, opts = {}) {
+        if (this.buses.has(name))
+            return; // idempotent
+        const node = this.ctx.createGain();
+        const initial = opts.initialGain ?? 1.0;
+        node.gain.value = initial;
+        node.connect(this.master);
+        this.buses.set(name, {
+            node,
+            baseGain: initial,
+            muted: false,
+            priority: opts.priority ?? 'ambient',
+        });
+        this.applyBudgetToBus(name);
+    }
+    removeBus(name) {
+        const entry = this.buses.get(name);
+        if (!entry)
+            return;
+        entry.node.disconnect();
+        this.buses.delete(name);
+    }
+    setMasterGain(gain) {
+        this.masterGain = Math.max(0, gain);
+        this.master.gain.value = this.masterGain;
+    }
+    getMasterGain() {
+        return this.masterGain;
+    }
+    setBusGain(name, gain) {
+        const entry = this.buses.get(name);
+        if (!entry)
+            return;
+        entry.baseGain = Math.max(0, gain);
+        this.applyBudgetToBus(name);
+    }
+    getBusGain(name) {
+        return this.buses.get(name)?.baseGain ?? 0;
+    }
+    setBusMuted(name, muted) {
+        const entry = this.buses.get(name);
+        if (!entry)
+            return;
+        entry.muted = muted;
+        this.applyBudgetToBus(name);
+    }
+    isBusMuted(name) {
+        return this.buses.get(name)?.muted ?? false;
+    }
+    // Apply the latest VeilBudget audioBudget. Caller pushes this from
+    // the resource each tick (or on Director updates). Idempotent;
+    // re-apply with the same value is cheap.
+    setAudioBudget(budget) {
+        if (Number.isNaN(budget) || budget < 0)
+            budget = 0;
+        if (budget > 1)
+            budget = 1;
+        if (budget === this.currentBudget)
+            return;
+        this.currentBudget = budget;
+        for (const name of this.buses.keys()) {
+            this.applyBudgetToBus(name);
+        }
+    }
+    getAudioBudget() {
+        return this.currentBudget;
+    }
+    applyBudgetToBus(name) {
+        const entry = this.buses.get(name);
+        if (!entry)
+            return;
+        let effective = entry.baseGain;
+        if (entry.muted)
+            effective = 0;
+        if (this.currentBudget < AUDIO_BUDGET_ESSENTIAL_FLOOR) {
+            effective = 0;
+        }
+        else if (entry.priority === 'ambient' &&
+            this.currentBudget < AUDIO_BUDGET_AMBIENT_FLOOR) {
+            effective = 0;
+        }
+        entry.node.gain.value = effective;
+    }
+    // Convenience: play a one-shot AudioBuffer through a named bus.
+    // Returns the AudioBufferSourceNode so callers can stop / track it.
+    // Returns null if the bus or context isn't ready.
+    playOneShot(busName, buffer, options = {}) {
+        const entry = this.buses.get(busName);
+        if (!entry)
+            return null;
+        if (!this.isUnlocked())
+            return null;
+        const src = this.ctx.createBufferSource();
+        src.buffer = buffer;
+        src.playbackRate.value = options.rate ?? 1;
+        if (options.gain !== undefined) {
+            const g = this.ctx.createGain();
+            g.gain.value = options.gain;
+            src.connect(g).connect(entry.node);
+        }
+        else {
+            src.connect(entry.node);
+        }
+        src.start();
+        return src;
+    }
+    // Convenience: short tone via OscillatorNode. Useful for code-only
+    // demos and UI feedback when no sound assets are loaded yet.
+    playTone(busName, freq, durationMs, options = {}) {
+        const entry = this.buses.get(busName);
+        if (!entry)
+            return;
+        if (!this.isUnlocked())
+            return;
+        const osc = this.ctx.createOscillator();
+        const gain = this.ctx.createGain();
+        osc.type = options.type ?? 'sine';
+        osc.frequency.value = freq;
+        const peakGain = options.gain ?? 0.2;
+        // Tiny attack / release envelope so the tone doesn't click.
+        const now = this.ctx.currentTime;
+        const dur = Math.max(0.01, durationMs / 1000);
+        gain.gain.setValueAtTime(0, now);
+        gain.gain.linearRampToValueAtTime(peakGain, now + 0.005);
+        gain.gain.linearRampToValueAtTime(peakGain, now + dur - 0.02);
+        gain.gain.linearRampToValueAtTime(0, now + dur);
+        osc.connect(gain).connect(entry.node);
+        osc.start(now);
+        osc.stop(now + dur + 0.05);
+    }
+    // Tear down. Useful in tests; production demo lives the lifetime of
+    // the page.
+    dispose() {
+        for (const entry of this.buses.values()) {
+            try {
+                entry.node.disconnect();
+            }
+            catch { /* ignore */ }
+        }
+        this.buses.clear();
+        try {
+            this.master.disconnect();
+        }
+        catch { /* ignore */ }
+    }
+}
+// Resource key for the world's resource registry. Engine.create
+// registers an AudioBus instance under this key.
+export const RESOURCE_AUDIO_BUS = 'audio_bus';
+//# sourceMappingURL=audio-bus.js.map

package/dist/audio/audio-bus.js.map

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