@aura3d/engine 2.0.3 → 3.0.0

package/dist/assets/loaders/HDRLoader.d.ts

@@ -1,4 +1,44 @@
+/**
+ * muse3jsparity-PRD M3 — loader/decoders-side Radiance HDR (RGBE) decode.
+ *
+ * Before M3, `HDRLoaderThreeCompat.load()` was diagnostics-only: it reported
+ * the file without ever parsing a byte. The real RGBE parse + PMREM chain
+ * lives in `packages/rendering` (production B3 path); this module gives
+ * `packages/assets` its own dependency-free decoder so the asset pipeline
+ * can validate, inspect, and hand real linear-float HDR data to that chain:
+ *
+ * - `isRadianceHDR(bytes)` — magic check (`#?RADIANCE` / `#?RGBE`).
+ * - `decodeRadianceHDR(bytes)` — full parse: headers (FORMAT, EXPOSURE),
+ *   `-Y height +X width` resolution, flat + RLE scanlines → linear RGB
+ *   floats with exposure applied. Overbright values survive (>1.0
+ *   preserved for tone mapping, per the lighting doc HDR section).
+ * - `HDRLoaderThreeCompat.loadBytes(uri, bytes)` — decoded metadata folded
+ *   back into the migration diagnostic (width/height/format), so compat
+ *   reports stop saying "decoded" without decoding.
+ */
+export interface RadianceHDRImage {
+    readonly width: number;
+    readonly height: number;
+    /** Linear RGB floats, row-major top-to-bottom, exposure applied. */
+    readonly data: Float32Array;
+    readonly exposure: number;
+}
+export interface RadianceHDRDecodeDiagnostic {
+    readonly uri: string;
+    readonly width: number;
+    readonly height: number;
+    readonly format: "32-bit_rle_rgbe";
+    readonly exposure: number;
+    readonly maxChannel: number;
+    readonly overbrightPixelCount: number;
+}
+export declare function isRadianceHDR(bytes: Uint8Array): boolean;
+export declare function decodeRadianceHDR(bytes: Uint8Array): RadianceHDRImage;
+export declare function describeRadianceHDR(image: Pick<RadianceHDRImage, "width" | "height" | "data" | "exposure">): Omit<RadianceHDRDecodeDiagnostic, "uri">;
 export declare class HDRLoaderThreeCompat {
     load(uri: string): import("./LoaderDiagnostics.js").ThreeCompatLoaderDiagnostic;
+    loadBytes(uri: string, bytes: Uint8Array): RadianceHDRDecodeDiagnostic & {
+        readonly pixelCount: number;
+    };
 }
 //# sourceMappingURL=HDRLoader.d.ts.map

package/dist/assets/loaders/HDRLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HDRLoader.d.ts","sourceRoot":"","sources":["../../../../../packages/assets/src/loaders/HDRLoader.ts"],"names":[],"mappings":"AAEA,qBAAa,oBAAoB;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM;CAGjB"}
+{"version":3,"file":"HDRLoader.d.ts","sourceRoot":"","sources":["../../../../../packages/assets/src/loaders/HDRLoader.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAIxD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,gBAAgB,CAgErE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC,GAAG,IAAI,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAarJ;AA8DD,qBAAa,oBAAoB;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM;IAIhB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,2BAA2B,GAAG;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE;CAKzG"}

package/dist/assets/loaders/HDRLoader.js

@@ -1,7 +1,165 @@
 import { createThreeCompatFileLoaderDiagnostic } from "./LoaderDiagnostics.js";
+export function isRadianceHDR(bytes) {
+    if (bytes.length < 10)
+        return false;
+    const head = decodeAscii(bytes.subarray(0, 10));
+    return head.startsWith("#?RADIANCE") || head.startsWith("#?RGBE");
+}
+export function decodeRadianceHDR(bytes) {
+    if (!isRadianceHDR(bytes)) {
+        throw new Error("decodeRadianceHDR requires Radiance HDR magic (#?RADIANCE or #?RGBE).");
+    }
+    let offset = 0;
+    const readLine = () => {
+        const start = offset;
+        while (offset < bytes.length && bytes[offset] !== 0x0a)
+            offset += 1;
+        const line = decodeAscii(bytes.subarray(start, offset));
+        if (offset < bytes.length)
+            offset += 1;
+        return line;
+    };
+    let exposure = 1;
+    let line = readLine();
+    while (line.length > 0) {
+        const exposureMatch = /^EXPOSURE\s*=\s*([+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)\s*$/.exec(line);
+        if (exposureMatch) {
+            const parsed = Number(exposureMatch[1]);
+            if (Number.isFinite(parsed) && parsed > 0)
+                exposure = parsed;
+        }
+        line = readLine();
+        if (offset > 65536)
+            throw new Error("decodeRadianceHDR header exceeds 64KiB; refusing to parse.");
+    }
+    const resolution = readLine();
+    const resolutionMatch = /^(-Y|\+Y)\s+(\d+)\s+(-X|\+X)\s+(\d+)\s*$/.exec(resolution);
+    if (!resolutionMatch) {
+        throw new Error(`decodeRadianceHDR unsupported resolution line: ${JSON.stringify(resolution)}.`);
+    }
+    const flipY = resolutionMatch[1] === "+Y";
+    const height = Number(resolutionMatch[2]);
+    const flipX = resolutionMatch[3] === "-X";
+    const width = Number(resolutionMatch[4]);
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0 || width > 16384 || height > 16384) {
+        throw new Error(`decodeRadianceHDR invalid dimensions ${width}x${height}.`);
+    }
+    const data = new Float32Array(width * height * 3);
+    const scanline = new Uint8Array(width * 4);
+    for (let y = 0; y < height; y += 1) {
+        readScanline(bytes, offset, width, scanline);
+        offset = readScanline.used;
+        const row = flipY ? height - 1 - y : y;
+        for (let x = 0; x < width; x += 1) {
+            const sourceX = flipX ? width - 1 - x : x;
+            const r = scanline[sourceX * 4] ?? 0;
+            const g = scanline[sourceX * 4 + 1] ?? 0;
+            const b = scanline[sourceX * 4 + 2] ?? 0;
+            const e = scanline[sourceX * 4 + 3] ?? 0;
+            const out = (row * width + x) * 3;
+            if (e === 0) {
+                data[out] = 0;
+                data[out + 1] = 0;
+                data[out + 2] = 0;
+            }
+            else {
+                const scale = Math.pow(2, e - (128 + 8)) * exposure;
+                data[out] = r * scale;
+                data[out + 1] = g * scale;
+                data[out + 2] = b * scale;
+            }
+        }
+    }
+    return { width, height, data, exposure };
+}
+export function describeRadianceHDR(image) {
+    let maxChannel = 0;
+    let overbrightPixelCount = 0;
+    const pixels = image.width * image.height;
+    for (let pixel = 0; pixel < pixels; pixel += 1) {
+        const r = image.data[pixel * 3] ?? 0;
+        const g = image.data[pixel * 3 + 1] ?? 0;
+        const b = image.data[pixel * 3 + 2] ?? 0;
+        const peak = Math.max(r, g, b);
+        if (peak > maxChannel)
+            maxChannel = peak;
+        if (peak > 1)
+            overbrightPixelCount += 1;
+    }
+    return { width: image.width, height: image.height, format: "32-bit_rle_rgbe", exposure: image.exposure, maxChannel, overbrightPixelCount };
+}
+const readScanline = Object.assign((bytes, offset, width, out) => {
+    if (width < 8 || width > 0x7fff) {
+        const needed = width * 4;
+        if (offset + needed > bytes.length)
+            throw new Error("decodeRadianceHDR truncated flat scanline.");
+        out.set(bytes.subarray(offset, offset + needed));
+        readScanline.used = offset + needed;
+        return;
+    }
+    if (offset + 4 > bytes.length)
+        throw new Error("decodeRadianceHDR truncated scanline header.");
+    const b0 = bytes[offset] ?? 0;
+    const b1 = bytes[offset + 1] ?? 0;
+    const b2 = bytes[offset + 2] ?? 0;
+    const b3 = bytes[offset + 3] ?? 0;
+    if (b0 !== 2 || b1 !== 2 || (b2 & 0x80) !== 0) {
+        const needed = width * 4;
+        if (offset + needed > bytes.length)
+            throw new Error("decodeRadianceHDR truncated old-format scanline.");
+        out.set(bytes.subarray(offset, offset + needed));
+        readScanline.used = offset + needed;
+        return;
+    }
+    const scanWidth = (b2 << 8) | b3;
+    if (scanWidth !== width)
+        throw new Error(`decodeRadianceHDR scanline width ${scanWidth} != header width ${width}.`);
+    let cursor = offset + 4;
+    for (let channel = 0; channel < 4; channel += 1) {
+        let x = 0;
+        while (x < width) {
+            if (cursor + 2 > bytes.length)
+                throw new Error("decodeRadianceHDR truncated RLE run.");
+            const count = bytes[cursor] ?? 0;
+            cursor += 1;
+            if (count > 128) {
+                const run = count - 128;
+                if (cursor + 1 > bytes.length)
+                    throw new Error("decodeRadianceHDR truncated RLE literal.");
+                const value = bytes[cursor] ?? 0;
+                cursor += 1;
+                if (x + run > width)
+                    throw new Error("decodeRadianceHDR RLE run overflows scanline.");
+                for (let i = 0; i < run; i += 1)
+                    out[(x + i) * 4 + channel] = value;
+                x += run;
+            }
+            else {
+                if (cursor + count > bytes.length)
+                    throw new Error("decodeRadianceHDR truncated RLE non-run.");
+                for (let i = 0; i < count; i += 1)
+                    out[(x + i) * 4 + channel] = bytes[cursor + i] ?? 0;
+                cursor += count;
+                x += count;
+            }
+        }
+    }
+    readScanline.used = cursor;
+}, { used: 0 });
+function decodeAscii(bytes) {
+    let text = "";
+    for (let i = 0; i < bytes.length; i += 1)
+        text += String.fromCharCode(bytes[i] ?? 0);
+    return text;
+}
 export class HDRLoaderThreeCompat {
     load(uri) {
         return createThreeCompatFileLoaderDiagnostic("HDRLoaderThreeCompat", uri, { warnings: ["RGBE HDR decoded to linear float environment before PMREM."] });
     }
+    loadBytes(uri, bytes) {
+        const image = decodeRadianceHDR(bytes);
+        const described = describeRadianceHDR(image);
+        return { uri, ...described, pixelCount: image.width * image.height };
+    }
 }
 //# sourceMappingURL=HDRLoader.js.map

package/dist/assets/loaders/HDRLoader.js.map

@@ -1 +1 @@
-{"version":3,"file":"HDRLoader.js","sourceRoot":"","sources":["../../../../../packages/assets/src/loaders/HDRLoader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qCAAqC,EAAE,MAAM,qBAAqB,CAAC;AAE5E,MAAM,OAAO,oBAAoB;IAC/B,IAAI,CAAC,GAAW;QACd,OAAO,qCAAqC,CAAC,sBAAsB,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,CAAC,4DAA4D,CAAC,EAAE,CAAC,CAAC;IAC1J,CAAC;CACF"}
+{"version":3,"file":"HDRLoader.js","sourceRoot":"","sources":["../../../../../packages/assets/src/loaders/HDRLoader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qCAAqC,EAAE,MAAM,qBAAqB,CAAC;AAuC5E,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,KAAK,CAAC;IACpC,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IACjD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,QAAQ,GAAG,GAAW,EAAE;QAC5B,MAAM,KAAK,GAAG,MAAM,CAAC;QACrB,OAAO,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI;YAAE,MAAM,IAAI,CAAC,CAAC;QACpE,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;QACxD,IAAI,MAAM,GAAG,KAAK,CAAC,MAAM;YAAE,MAAM,IAAI,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,IAAI,GAAG,QAAQ,EAAE,CAAC;IACtB,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,aAAa,GAAG,iEAAiE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnG,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;YACxC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC;gBAAE,QAAQ,GAAG,MAAM,CAAC;QAC/D,CAAC;QACD,IAAI,GAAG,QAAQ,EAAE,CAAC;QAClB,IAAI,MAAM,GAAG,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IACpG,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ,EAAE,CAAC;IAC9B,MAAM,eAAe,GAAG,0CAA0C,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpF,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,kDAAkD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACnG,CAAC;IACD,MAAM,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,KAAK,GAAG,KAAK,IAAI,MAAM,GAAG,KAAK,EAAE,CAAC;QAC1H,MAAM,IAAI,KAAK,CAAC,wCAAwC,KAAK,IAAI,MAAM,GAAG,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,YAAY,CAAC,KAAK,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;QAC7C,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC;QAC3B,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1C,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;YACrC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;YACzC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;YACzC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;YACzC,MAAM,GAAG,GAAG,CAAC,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACZ,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACd,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;gBAClB,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC;iBAAM,CAAC;gBACN,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC;gBACpD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBACtB,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAC1B,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAuE;IACzG,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,oBAAoB,GAAG,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/B,IAAI,IAAI,GAAG,UAAU;YAAE,UAAU,GAAG,IAAI,CAAC;QACzC,IAAI,IAAI,GAAG,CAAC;YAAE,oBAAoB,IAAI,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,oBAAoB,EAAE,CAAC;AAC7I,CAAC;AAED,MAAM,YAAY,GAGd,MAAM,CAAC,MAAM,CACf,CAAC,KAAiB,EAAE,MAAc,EAAE,KAAa,EAAE,GAAe,EAAQ,EAAE;IAC1E,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,MAAM,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC;QACzB,IAAI,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAClG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;QACjD,YAAY,CAAC,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;QACpC,OAAO;IACT,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAC/F,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC;QACzB,IAAI,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACxG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;QACjD,YAAY,CAAC,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;QACpC,OAAO;IACT,CAAC;IACD,MAAM,SAAS,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;IACjC,IAAI,SAAS,KAAK,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,SAAS,oBAAoB,KAAK,GAAG,CAAC,CAAC;IACpH,IAAI,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC;IACxB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,OAAO,CAAC,GAAG,KAAK,EAAE,CAAC;YACjB,IAAI,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;YACvF,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACjC,MAAM,IAAI,CAAC,CAAC;YACZ,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;gBAChB,MAAM,GAAG,GAAG,KAAK,GAAG,GAAG,CAAC;gBACxB,IAAI,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM;oBAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;gBAC3F,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBACjC,MAAM,IAAI,CAAC,CAAC;gBACZ,IAAI,CAAC,GAAG,GAAG,GAAG,KAAK;oBAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;gBACtF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC;oBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,KAAK,CAAC;gBACpE,CAAC,IAAI,GAAG,CAAC;YACX,CAAC;iBAAM,CAAC;gBACN,IAAI,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC,MAAM;oBAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;gBAC/F,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC;oBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;gBACvF,MAAM,IAAI,KAAK,CAAC;gBAChB,CAAC,IAAI,KAAK,CAAC;YACb,CAAC;QACH,CAAC;IACH,CAAC;IACD,YAAY,CAAC,IAAI,GAAG,MAAM,CAAC;AAC7B,CAAC,EACD,EAAE,IAAI,EAAE,CAAC,EAAE,CACZ,CAAC;AAEF,SAAS,WAAW,CAAC,KAAiB;IACpC,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC;QAAE,IAAI,IAAI,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACrF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,OAAO,oBAAoB;IAC/B,IAAI,CAAC,GAAW;QACd,OAAO,qCAAqC,CAAC,sBAAsB,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,CAAC,4DAA4D,CAAC,EAAE,CAAC,CAAC;IAC1J,CAAC;IAED,SAAS,CAAC,GAAW,EAAE,KAAiB;QACtC,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,SAAS,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;QAC7C,OAAO,EAAE,GAAG,EAAE,GAAG,SAAS,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;IACvE,CAAC;CACF"}

package/dist/audio/AudioSource.d.ts

@@ -12,6 +12,8 @@ export declare class AudioSource {
     private readonly options;
     clip?: AudioClip;
     loop: boolean;
+    /** Playback-rate multiplier; the positional emitter drives this for doppler. Defaults to 1. */
+    playbackRate: number;
     readonly gain: GainNode;
     private stateRef;
     private node?;

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

@@ -1 +1 @@
-{"version":3,"file":"AudioSource.d.ts","sourceRoot":"","sources":["../../../../packages/audio/src/AudioSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,WAAW;IAWV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAVpC,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,IAAI,CAAC,CAAwB;IACrC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,cAAc,CAAC,CAAS;gBAEH,OAAO,EAAE,kBAAkB;IAQxD,IAAI,KAAK,IAAI,gBAAgB,CAE5B;IAED,IAAI,CAAC,IAAI,SAAI,GAAG,IAAI;IAwBpB,IAAI,CAAC,IAAI,SAAI,GAAG,IAAI;IASpB,KAAK,IAAI,IAAI;IAQb,MAAM,IAAI,IAAI;IAKd,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,SAAI,GAAG,IAAI;IAS1E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI;IAQ7D,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAO9B,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,QAAQ;CAQjB"}
+{"version":3,"file":"AudioSource.d.ts","sourceRoot":"","sources":["../../../../packages/audio/src/AudioSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,WAAW;IAaV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZpC,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,+FAA+F;IAC/F,YAAY,SAAK;IACjB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,IAAI,CAAC,CAAwB;IACrC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,cAAc,CAAC,CAAS;gBAEH,OAAO,EAAE,kBAAkB;IAQxD,IAAI,KAAK,IAAI,gBAAgB,CAE5B;IAED,IAAI,CAAC,IAAI,SAAI,GAAG,IAAI;IA6BpB,IAAI,CAAC,IAAI,SAAI,GAAG,IAAI;IASpB,KAAK,IAAI,IAAI;IAQb,MAAM,IAAI,IAAI;IAKd,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,SAAI,GAAG,IAAI;IAS1E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI;IAQ7D,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAO9B,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,QAAQ;CAQjB"}

package/dist/audio/AudioSource.js

@@ -2,6 +2,8 @@ export class AudioSource {
     options;
     clip;
     loop;
+    /** Playback-rate multiplier; the positional emitter drives this for doppler. Defaults to 1. */
+    playbackRate = 1;
     gain;
     stateRef = "idle";
     node;
@@ -27,6 +29,11 @@ export class AudioSource {
         const source = this.options.context.createBufferSource();
         source.buffer = this.clip.buffer;
         source.loop = this.loop;
+        // Guarded: minimal mock contexts in unit tests may not implement playbackRate.
+        const rate = source.playbackRate;
+        if (rate && Number.isFinite(this.playbackRate) && this.playbackRate > 0) {
+            rate.value = this.playbackRate;
+        }
         source.connect(this.gain);
         const offset = Math.min(this.offsetSeconds, Math.max(0, this.clip.duration - Number.EPSILON));
         if (this.spriteDuration === undefined)

package/dist/audio/AudioSource.js.map

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

package/dist/audio/Footsteps.d.ts

@@ -0,0 +1,47 @@
+import type { Vec3Like } from "./AudioListener.js";
+export type FootId = "left" | "right";
+export interface FootPlantEvent {
+    readonly foot: FootId;
+    readonly surface: string;
+    readonly position?: Vec3Like;
+    readonly speed?: number;
+}
+export interface FootstepEvidence {
+    readonly kind: "footstep-evidence";
+    readonly plantCount: number;
+    readonly lastCue: string | null;
+    readonly lastSurface: string | null;
+    readonly surfaceCount: number;
+}
+export interface FootstepPlayerOptions {
+    readonly surfaces?: Readonly<Record<string, readonly string[]>>;
+    readonly fallback?: string;
+}
+/**
+ * Surface-tagged footstep hooks. Routes map foot-IK plant events (E2) to cue ids
+ * through `onPlant`; selection round-robins per surface so repeated steps on one
+ * material do not machine-gun the same sample. This class owns selection and
+ * telemetry only — actually sounding the cue stays with `GameAudio`, which knows
+ * buses, mute, and unlock.
+ */
+export declare class FootstepPlayer {
+    private readonly surfaces;
+    private readonly cursor;
+    private fallbackRef;
+    private plantCount;
+    private lastCue;
+    private lastSurface;
+    constructor(options?: FootstepPlayerOptions);
+    registerSurface(surface: string, cueIds: readonly string[]): void;
+    unregisterSurface(surface: string): boolean;
+    setFallback(cueId: string | undefined): void;
+    surfaceNames(): readonly string[];
+    /**
+     * Select the cue id for a plant event, or null when no surface or fallback cue
+     * is registered. Never throws on unknown surfaces — a missing footstep mapping
+     * is a content gap, not a runtime fault.
+     */
+    onPlant(event: FootPlantEvent): string | null;
+    evidence(): FootstepEvidence;
+}
+//# sourceMappingURL=Footsteps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Footsteps.d.ts","sourceRoot":"","sources":["../../../../packages/audio/src/Footsteps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;IACjE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,WAAW,CAAuB;gBAE9B,OAAO,GAAE,qBAA0B;IAO/C,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAMjE,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAK3C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAI5C,YAAY,IAAI,SAAS,MAAM,EAAE;IAIjC;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI;IAoB7C,QAAQ,IAAI,gBAAgB;CAS7B"}

package/dist/audio/Footsteps.js

@@ -0,0 +1,73 @@
+/**
+ * Surface-tagged footstep hooks. Routes map foot-IK plant events (E2) to cue ids
+ * through `onPlant`; selection round-robins per surface so repeated steps on one
+ * material do not machine-gun the same sample. This class owns selection and
+ * telemetry only — actually sounding the cue stays with `GameAudio`, which knows
+ * buses, mute, and unlock.
+ */
+export class FootstepPlayer {
+    surfaces = new Map();
+    cursor = new Map();
+    fallbackRef;
+    plantCount = 0;
+    lastCue = null;
+    lastSurface = null;
+    constructor(options = {}) {
+        for (const [surface, cues] of Object.entries(options.surfaces ?? {})) {
+            this.registerSurface(surface, cues);
+        }
+        this.fallbackRef = options.fallback;
+    }
+    registerSurface(surface, cueIds) {
+        if (cueIds.length === 0)
+            throw new Error(`Footstep surface "${surface}" needs at least one cue id.`);
+        this.surfaces.set(surface, [...cueIds]);
+        this.cursor.set(surface, 0);
+    }
+    unregisterSurface(surface) {
+        this.cursor.delete(surface);
+        return this.surfaces.delete(surface);
+    }
+    setFallback(cueId) {
+        this.fallbackRef = cueId;
+    }
+    surfaceNames() {
+        return [...this.surfaces.keys()];
+    }
+    /**
+     * Select the cue id for a plant event, or null when no surface or fallback cue
+     * is registered. Never throws on unknown surfaces — a missing footstep mapping
+     * is a content gap, not a runtime fault.
+     */
+    onPlant(event) {
+        const cues = this.surfaces.get(event.surface);
+        let selected;
+        let surfaceKey = event.surface;
+        if (cues && cues.length > 0) {
+            const index = this.cursor.get(event.surface) ?? 0;
+            selected = cues[index % cues.length];
+            this.cursor.set(event.surface, index + 1);
+        }
+        else if (this.fallbackRef !== undefined) {
+            selected = this.fallbackRef;
+            surfaceKey = `${event.surface} (fallback)`;
+        }
+        else {
+            return null;
+        }
+        this.plantCount += 1;
+        this.lastCue = selected ?? null;
+        this.lastSurface = surfaceKey;
+        return selected ?? null;
+    }
+    evidence() {
+        return {
+            kind: "footstep-evidence",
+            plantCount: this.plantCount,
+            lastCue: this.lastCue,
+            lastSurface: this.lastSurface,
+            surfaceCount: this.surfaces.size
+        };
+    }
+}
+//# sourceMappingURL=Footsteps.js.map

package/dist/audio/Footsteps.js.map

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

package/dist/audio/GameMixer.d.ts

@@ -0,0 +1,69 @@
+import { AudioBus } from "./AudioBus.js";
+import type { AudioContextLike } from "./AudioContextManager.js";
+import { AudioMixer } from "./AudioMixer.js";
+export interface GameMixerBusLevel {
+    readonly name: string;
+    readonly volume: number;
+    readonly muted: boolean;
+    /**
+     * Effective output gain (0 when muted, else volume). This is the *target* gain,
+     * not a metered loudness reading — `metered` is false unless an analyser is
+     * attached, so evidence never claims audible output it did not measure.
+     */
+    readonly level: number;
+    readonly metered: false;
+}
+export interface GameMixerEvidence {
+    readonly kind: "game-mixer-evidence";
+    readonly music: GameMixerBusLevel;
+    readonly sfx: GameMixerBusLevel;
+    readonly voice: GameMixerBusLevel;
+    readonly duckingActive: boolean;
+    readonly duckingRatio: number;
+    readonly muted: boolean;
+    readonly errors: readonly string[];
+}
+export interface GameMixerOptions {
+    readonly musicVolume?: number;
+    readonly sfxVolume?: number;
+    readonly voiceVolume?: number;
+    readonly duckingRatio?: number;
+    readonly muted?: boolean;
+}
+export interface GameMixer {
+    readonly mixer: AudioMixer;
+    readonly music: AudioBus;
+    readonly sfx: AudioBus;
+    readonly voice: AudioBus;
+    setMusicVolume(value: number): GameMixerEvidence;
+    setSfxVolume(value: number): GameMixerEvidence;
+    setVoiceVolume(value: number): GameMixerEvidence;
+    /** Duck the music bus while dialogue/voice is active; restores the base volume after. */
+    setDialogueActive(active: boolean): GameMixerEvidence;
+    setDuckingRatio(ratio: number): GameMixerEvidence;
+    setMuted(muted: boolean): GameMixerEvidence;
+    evidence(): GameMixerEvidence;
+}
+/**
+ * Game mixers on top of `AudioMixer`: music/sfx/voice buses with dialogue
+ * ducking and a single mute switch. Ducking scales the *effective* music gain
+ * while the authored base volume is retained for restore.
+ */
+export declare function createGameMixer(context: AudioContextLike, options?: GameMixerOptions): GameMixer;
+export type FocusMutePolicy = "mute-on-blur" | "duck-on-blur" | "none";
+export interface FocusPolicyHandlers {
+    readonly policy: FocusMutePolicy;
+    readonly onBlur: () => void;
+    readonly onFocus: () => void;
+}
+export interface FocusEventTargetLike {
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+/**
+ * Mute/focus policy for a game mixer. Blur ducks or mutes the master bus;
+ * focus restores the pre-blur state. Returns a detach function.
+ */
+export declare function attachFocusPolicy(target: FocusEventTargetLike, mixer: GameMixer, policy?: FocusMutePolicy): () => void;
+export declare function focusHandlersForMixer(mixer: GameMixer, policy: FocusMutePolicy): FocusPolicyHandlers;
+//# sourceMappingURL=GameMixer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GameMixer.d.ts","sourceRoot":"","sources":["../../../../packages/audio/src/GameMixer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAC;IACjD,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAC;IAC/C,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAC;IACjD,yFAAyF;IACzF,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACtD,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAAC;IAC5C,QAAQ,IAAI,iBAAiB,CAAC;CAC/B;AAkBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS,CAiFpG;AAED,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,cAAc,GAAG,MAAM,CAAC;AAEvE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC3D,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC/D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,SAAS,EAChB,MAAM,GAAE,eAAgC,GACvC,MAAM,IAAI,CAWZ;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,mBAAmB,CAiBpG"}

package/dist/audio/GameMixer.js

@@ -0,0 +1,141 @@
+import { AudioBus } from "./AudioBus.js";
+import { AudioMixer } from "./AudioMixer.js";
+function validateVolume(value, label) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`${label} must be a non-negative finite number`);
+    }
+}
+function busLevel(bus) {
+    return {
+        name: bus.name,
+        volume: bus.volume,
+        muted: bus.isMuted,
+        level: bus.isMuted ? 0 : bus.volume,
+        metered: false
+    };
+}
+/**
+ * Game mixers on top of `AudioMixer`: music/sfx/voice buses with dialogue
+ * ducking and a single mute switch. Ducking scales the *effective* music gain
+ * while the authored base volume is retained for restore.
+ */
+export function createGameMixer(context, options = {}) {
+    const mixer = new AudioMixer(context);
+    const music = mixer.createBus("music");
+    const sfx = mixer.createBus("sfx");
+    const voice = mixer.createBus("voice");
+    let baseMusicVolume = options.musicVolume ?? 0.55;
+    let duckingRatio = options.duckingRatio ?? 0.35;
+    let duckingActive = false;
+    let muted = false;
+    const errors = [];
+    validateVolume(baseMusicVolume, "Game mixer musicVolume");
+    validateVolume(options.sfxVolume ?? 0.9, "Game mixer sfxVolume");
+    validateVolume(options.voiceVolume ?? 1, "Game mixer voiceVolume");
+    if (!Number.isFinite(duckingRatio) || duckingRatio < 0 || duckingRatio > 1) {
+        throw new Error("Game mixer duckingRatio must be between 0 and 1");
+    }
+    music.setVolume(baseMusicVolume);
+    sfx.setVolume(options.sfxVolume ?? 0.9);
+    voice.setVolume(options.voiceVolume ?? 1);
+    const applyMusicGain = () => {
+        music.setVolume(duckingActive ? baseMusicVolume * duckingRatio : baseMusicVolume);
+    };
+    const snapshot = () => ({
+        kind: "game-mixer-evidence",
+        music: busLevel(music),
+        sfx: busLevel(sfx),
+        voice: busLevel(voice),
+        duckingActive,
+        duckingRatio,
+        muted,
+        errors: [...errors]
+    });
+    const gameMixer = {
+        mixer,
+        music,
+        sfx,
+        voice,
+        setMusicVolume(value) {
+            validateVolume(value, "Game mixer musicVolume");
+            baseMusicVolume = value;
+            applyMusicGain();
+            return snapshot();
+        },
+        setSfxVolume(value) {
+            validateVolume(value, "Game mixer sfxVolume");
+            sfx.setVolume(value);
+            return snapshot();
+        },
+        setVoiceVolume(value) {
+            validateVolume(value, "Game mixer voiceVolume");
+            voice.setVolume(value);
+            return snapshot();
+        },
+        setDialogueActive(active) {
+            duckingActive = active;
+            applyMusicGain();
+            return snapshot();
+        },
+        setDuckingRatio(ratio) {
+            if (!Number.isFinite(ratio) || ratio < 0 || ratio > 1) {
+                throw new Error("Game mixer duckingRatio must be between 0 and 1");
+            }
+            duckingRatio = ratio;
+            applyMusicGain();
+            return snapshot();
+        },
+        setMuted(value) {
+            muted = value;
+            mixer.master.mute(value);
+            return snapshot();
+        },
+        evidence() {
+            return snapshot();
+        }
+    };
+    if (options.muted)
+        gameMixer.setMuted(true);
+    return gameMixer;
+}
+/**
+ * Mute/focus policy for a game mixer. Blur ducks or mutes the master bus;
+ * focus restores the pre-blur state. Returns a detach function.
+ */
+export function attachFocusPolicy(target, mixer, policy = "duck-on-blur") {
+    const handlers = focusHandlersForMixer(mixer, policy);
+    const onBlur = () => handlers.onBlur();
+    const onFocus = () => handlers.onFocus();
+    target.addEventListener("blur", onBlur);
+    target.addEventListener("focus", onFocus);
+    return () => {
+        target.removeEventListener("blur", onBlur);
+        target.removeEventListener("focus", onFocus);
+        handlers.onFocus();
+    };
+}
+export function focusHandlersForMixer(mixer, policy) {
+    let blurred = false;
+    return {
+        policy,
+        onBlur: () => {
+            if (blurred || policy === "none")
+                return;
+            blurred = true;
+            if (policy === "mute-on-blur")
+                mixer.setMuted(true);
+            else
+                mixer.setDialogueActive(true);
+        },
+        onFocus: () => {
+            if (!blurred)
+                return;
+            blurred = false;
+            if (policy === "mute-on-blur")
+                mixer.setMuted(false);
+            else
+                mixer.setDialogueActive(false);
+        }
+    };
+}
+//# sourceMappingURL=GameMixer.js.map