@threenative/assets 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -1,3 +1,52 @@
+/**
+ * Encodes compiled textures to KTX2/Basis so the GPU stores them compressed instead of as
+ * decoded RGBA (a 2048x2048 PNG is 16 MB in VRAM; BC7/ASTC hold it in a quarter of that).
+ *
+ * Codec choice is a declared property of the asset, never a guess: a config override wins,
+ * then the `*_normal.*` / `_nrm.*` filename convention, then alpha presence (UASTC keeps
+ * exact alpha and survives normal-map data; ETC1S does not). Mip chains are generated at
+ * encode time — always — because an uploaded compressed texture without mips looks worse
+ * than the PNG it replaced.
+ *
+ * The encoder is Basis Universal through `ktx2-encoder`'s in-process WASM build; users
+ * install nothing extra. Sources it cannot decode (anything but PNG/JPEG today) fail the
+ * build naming the file rather than shipping uncompressed behind the user's back.
+ */
+type TextureCodec = "etc1s" | "none" | "uastc";
+/**
+ * Why a source shipped uncompressed although its pass ran. `not-smaller` means encoding would
+ * have grown the download; `block-size` means no block codec can address the source's
+ * dimensions. Both keep the authored bytes; neither is a silent decision — the manifest carries
+ * the reason and the report prints it.
+ */
+type TextureSkipReason = "block-size" | "not-smaller";
+interface ITextureOverride {
+    readonly codec: TextureCodec;
+    /** First matching override wins; matched against the logical path, e.g. "ui/x.png". */
+    readonly glob: string;
+    /** ETC1S encoder quality 1–255. Ignored for UASTC, which uses its own fixed defaults. */
+    readonly quality?: number;
+}
+interface ITexturePassOptions {
+    /** Longest edge to retain; larger sources are downsampled without upscaling. */
+    readonly maxSize?: number;
+    readonly overrides?: readonly ITextureOverride[];
+    /** ETC1S encoder quality 1–255, default 150. Ignored for UASTC. */
+    readonly quality?: number;
+}
+/**
+ * Encodes source textures as mipmapped KTX2/Basis data and declares their runtime transcode targets.
+ * @constraint every compressed source width and height must be divisible by 4 because BC7, BC1, ETC2, and ASTC 4x4 use 4x4 blocks; WebGPU rejects an unaligned texture at draw time
+ * @constraint automatic cooking retains an unaligned source unchanged and reports block-size; an explicit compression codec override fails, while codec "none" remains available
+ * @example const pass = texturePass({ overrides: [{ glob: "ui/*", codec: "none" }] });
+ */
+declare function texturePass(options?: ITexturePassOptions): IAssetPass;
+
+interface IAssetBudget {
+    readonly uncooked: number | "none";
+    readonly total: number | "none";
+}
+
 type AssetFindingGrade = "fail" | "ok" | "warn";
 interface IAssetFinding {
     readonly asset: string;
@@ -38,6 +87,8 @@ interface IAssetHealthReport {
 interface IAssetHealthInput {
     readonly data: Buffer;
     readonly logicalPath: string;
+    /** Compiler-owned model output, when an imported source's GLB references shared images. */
+    readonly modelPath?: string;
 }
 /**
  * Measures every compiled asset and grades findings against the declared targets.
@@ -48,6 +99,99 @@ declare function runHealthReport(inputs: readonly IAssetHealthInput[], targets?:
 /** The person-readable form printed by the compile step, one line per finding plus a summary. */
 declare function formatHealthReport(report: IAssetHealthReport): readonly string[];
 
+/**
+ * The five bands a clip's content is judged in, contiguous and gapless up to Nyquist.
+ *
+ * Borrowed verbatim from `packages/playtest/src/runner/audio.ts`, names and edges both, so a game
+ * declares one band in one vocabulary and means the same thing to the build gate and to the audio
+ * inspector. Chosen for what they separate in practice: below 100 Hz a wood has nothing, 100-500 Hz
+ * is where a "warm" generation collapses into a hum, 500 Hz-2 kHz is body, 2-8 kHz is leaf rustle
+ * and birdsong and the brightness of a struck bell, and above 8 kHz is air.
+ */
+declare const AUDIO_BANDS: {
+    readonly sub: readonly [0, 100];
+    readonly low: readonly [100, 500];
+    readonly mid: readonly [500, 2000];
+    readonly high: readonly [2000, 8000];
+    readonly air: readonly [8000, number];
+};
+type AudioBand = keyof typeof AUDIO_BANDS;
+
+/**
+ * The audio declarations a game writes in `threenative.config.ts`, validated here.
+ *
+ * **Declared, never guessed.** Which clips loop, which are positional, and what a clip is *for*
+ * are facts only the game knows, and a pass that inferred them from a filename would be
+ * confidently wrong on the first asset named against its convention. `texture.ts` takes codec
+ * choice from an override, then a filename convention, then measured alpha — for audio there is no
+ * honest middle rung, so there is only the override. A clip nobody declared is still measured and
+ * still reported; what it does not get is an assertion about an intent nobody stated.
+ *
+ * Every key is checked here rather than deeper in the pass, because a silently-dropped `loop`
+ * is a build that shipped a clicking bed while reporting success — which is the defect this pass
+ * exists to stop.
+ */
+
+type AudioConditioning = "none";
+/** `"ceiling"` only ever attenuates; `"peak"` also lifts a quiet clip to the ceiling. */
+type AudioNormalisation = "ceiling" | "peak";
+/**
+ * What a clip is *for*, stated as a bound on where its energy sits.
+ *
+ * Both directions matter, and the two real defects this pass was built for are one of each. A chime
+ * that came back a hum needed a floor — it had 83% of its energy in `low` and nothing in `high`,
+ * where a struck bell lives. Fifteen footsteps needed a ceiling — they carried up to 45% of their
+ * energy in `sub`, below 100 Hz, which a wood has nothing in and which costs a phone's speaker its
+ * whole headroom for a sound nobody can hear.
+ *
+ * Percentages on the same 0-100 scale as the audio inspector's, and named bands from its
+ * vocabulary, so a game declares one number in one language for both tools.
+ */
+interface IAudioSpectrumExpectation {
+    readonly band: AudioBand;
+    /** Most of the clip's energy that may sit in the band. */
+    readonly maxPercent?: number;
+    /** Least of the clip's energy that must sit in the band. */
+    readonly minPercent?: number;
+}
+interface IAudioLoopOptions {
+    /**
+     * Equal-power cross-fade length in milliseconds. `0` keeps the clip's own length — a
+     * bar-accurate musical loop cannot be shortened by a fade — and still has its seam asserted.
+     */
+    readonly crossFadeMs?: number;
+    /** How far the splice may move to find a quiet seam, in milliseconds. */
+    readonly spliceToleranceMs?: number;
+}
+interface IAudioOverride {
+    /** Ships these bytes as committed. Measurement, and a declared loop's assertion, still run. */
+    readonly conditioning?: AudioConditioning;
+    /** First matching override wins; matched against the logical path, e.g. `"audio/bed.ogg"`. */
+    readonly glob: string;
+    /** The clip repeats forever, so its seam is cross-faded and then asserted. */
+    readonly loop?: boolean | IAudioLoopOptions;
+    readonly normalise?: AudioNormalisation;
+    /** Peak ceiling in dBFS; must be at or below 0. */
+    readonly peakDb?: number;
+    /** The clip plays from a place in the world, so it is downmixed to mono. */
+    readonly positional?: boolean;
+    /** Vorbis VBR quality, -1 to 10. */
+    readonly quality?: number;
+    /** The largest wrap-to-neighbourhood step ratio this loop may ship with. */
+    readonly seamMaxRatio?: number;
+    /** What the clip is for, stated as a band its energy must occupy. */
+    readonly spectrum?: IAudioSpectrumExpectation;
+}
+interface IAudioPassOptions {
+    readonly normalise?: AudioNormalisation;
+    readonly overrides?: readonly IAudioOverride[];
+    readonly peakDb?: number;
+    readonly quality?: number;
+    readonly seamMaxRatio?: number;
+}
+/** `"none"` drops the pass; an object configures it; absent means the defaults run. */
+declare function parseAudioConfig(raw: unknown): IAudioPassOptions | undefined;
+
 /**
  * Atlas integration follows the mesh → xatlas → remapped-attribute split documented by
  * xatlas-three 0.2.1 (MIT, copyright 2022 Palash Bansal). This implementation uses xatlasjs's
@@ -98,35 +242,6 @@ interface IModelVirtualOptions {
     readonly simplifyRatio?: number;
 }
 
-/**
- * Encodes compiled textures to KTX2/Basis so the GPU stores them compressed instead of as
- * decoded RGBA (a 2048x2048 PNG is 16 MB in VRAM; BC7/ASTC hold it in a quarter of that).
- *
- * Codec choice is a declared property of the asset, never a guess: a config override wins,
- * then the `*_normal.*` / `_nrm.*` filename convention, then alpha presence (UASTC keeps
- * exact alpha and survives normal-map data; ETC1S does not). Mip chains are generated at
- * encode time — always — because an uploaded compressed texture without mips looks worse
- * than the PNG it replaced.
- *
- * The encoder is Basis Universal through `ktx2-encoder`'s in-process WASM build; users
- * install nothing extra. Sources it cannot decode (anything but PNG/JPEG today) fail the
- * build naming the file rather than shipping uncompressed behind the user's back.
- */
-type TextureCodec = "etc1s" | "none" | "uastc";
-interface ITextureOverride {
-    readonly codec: TextureCodec;
-    /** First matching override wins; matched against the logical path, e.g. "ui/x.png". */
-    readonly glob: string;
-    /** ETC1S encoder quality 1–255. Ignored for UASTC, which uses its own fixed defaults. */
-    readonly quality?: number;
-}
-interface ITexturePassOptions {
-    readonly overrides?: readonly ITextureOverride[];
-    /** ETC1S encoder quality 1–255, default 150. Ignored for UASTC. */
-    readonly quality?: number;
-}
-declare function texturePass(options?: ITexturePassOptions): IAssetPass;
-
 /**
  * Compresses the images embedded *inside* a `.glb` — the half of a model the geometry passes
  * never touched. A prop carrying three 2048x2048 JPEGs is a small file and 67 MB of VRAM once
@@ -172,6 +287,8 @@ interface IEmbeddedTextureSummary {
     readonly gpuBytesBefore: number;
     /** How many images the resolution cap actually downsampled. */
     readonly resized: number;
+    /** Images retained at their authored bytes, by name, with the reason each one was not cooked. */
+    readonly skippedCompression: Readonly<Record<string, TextureSkipReason>>;
 }
 /** One embedded image as the verification compares it, source against re-read output. */
 interface IModelTextureBinding {
@@ -190,6 +307,33 @@ interface IModelTextureBindings {
     readonly textures: readonly IModelTextureBinding[];
 }
 
+/**
+ * Images that models share, written once and referenced from every model that carries them.
+ *
+ * A marketplace pack embeds its textures in every model that uses them: eight pines each carry
+ * the same 9 MB of bark and needle maps, so a valley of 58 models moves 280 MB for 63 MB of
+ * distinct images — and re-encodes every one of them on every build. The store keys an image on
+ * its **source** bytes plus the settings that decide its output, so the second model that
+ * carries the same bark map finds the encoded result instead of paying for it again, and a
+ * second build finds it on disk.
+ *
+ * The output is content-addressed under `shared/images/`, so two models that embed the same
+ * bytes resolve to one URL and the browser cache, the bundle and the delete-test all see one file.
+ */
+interface ISharedImage {
+    readonly buffer: Buffer;
+    /** `uastc`, `etc1s` or `none`, spelled into the filename so a cache hit knows what it found. */
+    readonly codec: string;
+    readonly mimeType: string;
+}
+interface ISharedImageStore {
+    /** The image encoded from this key, from memory or from a previous build's output. */
+    get(key: string): Promise<ISharedImage | undefined>;
+    put(key: string, image: ISharedImage): Promise<void>;
+    /** Output path, relative to the output root, of a stored image. */
+    outputPath(key: string, image: Pick<ISharedImage, "codec" | "mimeType">): string;
+}
+
 /**
  * Optimizes compiled models: dedup → prune → simplify → reorder → quantize → textures →
  * meshopt, in that fixed order, each individually switchable in config. Output declares
@@ -243,11 +387,21 @@ interface IModelSimplifyOptions {
 }
 interface IModelPassOptions {
     readonly passes?: IModelPassesOptions;
+    /** Native WebGPU rejects interleaved vertex attributes; mobile output uses separate buffers. */
+    readonly vertexLayout?: "interleaved" | "separate";
     /** Preserve generated TEXCOORD_1 data that is consumed by a runtime-attached lightmap. */
     readonly preserveLightmapUv?: boolean;
     readonly quantize?: IModelQuantizeOptions;
     /** LOD simplification; absent means no simplification at all. */
     readonly simplify?: IModelSimplifyOptions;
+    /**
+     * Share embedded images across models: each distinct image is written once, content-addressed
+     * under `shared/images/`, and every model that carries it references that one file. The store
+     * remembers encoded results within a build and, when it was given the output root, across
+     * builds — so a pack whose eight pines embed the same bark map encodes it once, not eight
+     * times per build. Absent means every model keeps its images embedded.
+     */
+    readonly sharedImages?: ISharedImageStore;
     /** Embedded-texture compression: options, or `"none"` to ship every image as authored. */
     readonly textures?: IModelTexturesOptions | "none";
     /**
@@ -277,6 +431,200 @@ interface IModelSimplifySummary {
 }
 declare function modelPass(options?: IModelPassOptions): IAssetPass;
 
+/**
+ * The person-readable size report the compile step prints after encoding: one line per
+ * compressed texture and optimized model plus a total, before against after. Pure formatting
+ * so tests can pin the exact lines a build prints.
+ */
+interface ITextureSizeRow {
+    readonly after: number;
+    readonly before: number;
+    /** Set when the bytes shipped as authored; printed so a flat row is never left unexplained. */
+    readonly compressionSkipped?: TextureSkipReason;
+    readonly format: string | undefined;
+    readonly logicalPath: string;
+}
+declare function formatTextureSizes(rows: readonly ITextureSizeRow[]): readonly string[];
+/** What the model pass did to the images inside one `.glb`. */
+interface IEmbeddedTextureRow {
+    readonly skippedCompression?: Readonly<Record<string, TextureSkipReason>>;
+    readonly bytesAfter: number;
+    readonly bytesBefore: number;
+    readonly count: number;
+    /** Chosen codec per embedded image, keyed by texture name. */
+    readonly formats?: Readonly<Record<string, string>>;
+    readonly gpuBytesAfter: number;
+    readonly gpuBytesBefore: number;
+    readonly resized: number;
+}
+/** What the cluster-DAG bake produced for one model. */
+interface IVirtualRow {
+    readonly bakeSeconds: number;
+    readonly clusters: number;
+    readonly levels: number;
+    readonly payloadBytes: number;
+    readonly primitives: number;
+    readonly skipped: number;
+    readonly stopReason: string;
+}
+/** What simplification delivered against what the config asked for. */
+interface ISimplifyRow {
+    readonly achievedRatio: number;
+    readonly error: number;
+    readonly requestedRatio: number;
+    readonly trianglesAfter: number;
+    readonly trianglesBefore: number;
+}
+/** Whether the pass executed this bake or every input that reached it was compile-cache-served. */
+type PassCostStatus = "cached" | "ran";
+/** What one input cost the pass that processed it, as the pass driver measured it. */
+interface IPassCostAssetRow {
+    readonly durationMs: number;
+    readonly logicalPath: string;
+}
+/**
+ * What one pass cost the whole bake: totals across inputs plus the per-asset attribution a
+ * 274-file pack needs to name its expensive members. Durations are measured by the pass driver,
+ * never reported by the pass itself, so a pass cannot opt out of measurement.
+ */
+interface IPassCostRow {
+    /** Per-input wall clock for the ran inputs, sorted by logical path; empty when cached. */
+    readonly assets: readonly IPassCostAssetRow[];
+    readonly cachedInputs: number;
+    readonly durationMs: number;
+    readonly pass: string;
+    readonly ranInputs: number;
+    readonly status: PassCostStatus;
+}
+/**
+ * Formats the per-pass cost lines the compile prints after the size report: one line per pass,
+ * then one line per input it ran on. A cached pass names its input count instead of a duration —
+ * the cache decision is the source, never a threshold inferred from a fast run.
+ */
+declare function formatPassCosts(rows: readonly IPassCostRow[]): readonly string[];
+/**
+ * What the audio pass measured and did to one clip.
+ *
+ * Every field is reported whether or not it was asserted on: an undeclared clip carries no
+ * `seamMaxRatio` and still carries its measured seam, because turning a convention off must not
+ * turn its measurement off. Every one of these numbers was measurable all along on the clips a
+ * hand-written script conditioned; nothing measured them.
+ */
+interface IAudioRow {
+    /**
+     * Where the clip's energy sits, as percentages across the five named bands summing to 100.
+     *
+     * Measured on every clip whether or not the game declared a bound, because this is the thing the
+     * hand-written script that preceded this pass never looked at, and it is where both of the real
+     * defects were.
+     */
+    readonly bandAir: number;
+    readonly bandHigh: number;
+    readonly bandLow: number;
+    readonly bandMid: number;
+    readonly bandSub: number;
+    readonly bytesAfter: number;
+    readonly bytesBefore: number;
+    readonly channelsAfter: number;
+    readonly channelsBefore: number;
+    /** False when the game declared these bytes shipped as committed. */
+    readonly conditioned: boolean;
+    readonly container: string;
+    /**
+     * Whether the audio was re-encoded, or the source bytes shipped untouched because nothing here
+     * moved the PCM. A needless re-encode costs a generation of lossy Vorbis to deliver the same
+     * audio, so a pass that does nothing says so instead of quietly charging for it.
+     */
+    readonly reencoded: boolean;
+    /** The fade applied, against the length the game asked for; absent unless the clip loops. */
+    readonly crossFadeMs?: number;
+    readonly crossFadeMsRequested?: number;
+    readonly dcOffsetAfter: number;
+    readonly dcOffsetBefore: number;
+    /** What the clip costs a device's memory once decoded — the larger of the two costs. */
+    readonly decodedBytesAfter: number;
+    readonly decodedBytesBefore: number;
+    readonly durationSeconds: number;
+    readonly frames: number;
+    readonly logicalPath: string;
+    readonly loop: boolean;
+    readonly peakAfter: number;
+    readonly peakBefore: number;
+    readonly sampleRate: number;
+    /** The largest ordinary adjacent step within 50 ms of the join. */
+    readonly seamNearP99: number;
+    /**
+     * `seamWrap / seamNearP99`, measured on the decoded output bytes — the ones that ship.
+     *
+     * The ratio rather than the magnitude, because a click is a step that is anomalous *where it
+     * happens*: an absolute bound condemns dense clips and excuses quiet ones.
+     */
+    readonly seamRatio: number;
+    readonly seamRatioBefore: number;
+    /** The bare step across the join. Reported because it is informative, not because it is judged. */
+    readonly seamWrap: number;
+    readonly seamWrapBefore: number;
+    /** Present only for a declared loop, which is the only clip whose seam is asserted. */
+    readonly seamMaxRatio?: number;
+    /** The band the game declared a bound on, and the bound; absent when it declared none. */
+    readonly spectrumBand?: string;
+    readonly spectrumMaxPercent?: number;
+    readonly spectrumMinPercent?: number;
+    readonly spectrumPercent?: number;
+}
+/**
+ * One line per conditioned clip plus a total, on the wire and decoded.
+ *
+ * The decoded total is the one worth printing loudest: a 21-second stereo ambience bed is 220 KB
+ * to download and 7.5 MB of resident memory, and it is the second number that decides whether a
+ * phone keeps the app alive.
+ */
+declare function formatAudioSizes(rows: readonly IAudioRow[]): readonly string[];
+/** One compiled model plus a total, before against after the optimization pass. */
+interface IModelSizeRow {
+    readonly after: number;
+    readonly before: number;
+    /** Embedded-image compression, when the model carried any. */
+    readonly embeddedTextures?: IEmbeddedTextureRow;
+    /** glTF extensions declared by the compiled output, e.g. EXT_meshopt_compression. */
+    readonly extensions?: readonly string[];
+    readonly logicalPath: string;
+    readonly lightmap?: {
+        readonly atlasHeight: number;
+        readonly atlasWidth: number;
+        readonly bakeMs: number;
+        readonly bytesAfter: number;
+        readonly bytesBefore: number;
+        readonly dilatedTexels: number;
+        readonly occludedTexels: number;
+        readonly validTexels: number;
+    };
+    /** LOD simplification, when it was configured for this model. */
+    readonly simplify?: ISimplifyRow;
+    /** The cluster-DAG bake, when it was configured for this model. */
+    readonly virtual?: IVirtualRow;
+    /** Triangle count of the compiled output, recorded in the manifest. */
+    readonly triangles?: number;
+}
+declare function formatModelSizes(rows: readonly IModelSizeRow[]): readonly string[];
+/** What an uncompressed pass cost this build, per kind, and which decision caused it. */
+interface ISkippedCompressionRow {
+    readonly bytes: number;
+    readonly files: number;
+    readonly kind: "model" | "texture";
+    /** Decoder-backed sub-passes that this row actually omitted. */
+    readonly decoders?: readonly ("meshopt" | "KTX2")[];
+    /** `"config"` — the game set `"none"`. `"platform"` — this target cannot decode compression. */
+    readonly reason: "config" | "platform";
+}
+/** A caller-supplied pass omitted because this target cannot provide its runtime decoder. */
+interface ISkippedPassRow {
+    readonly kind: "pass";
+    readonly pass: string;
+    readonly reason: "platform";
+}
+type ISkippedReportRow = ISkippedCompressionRow | ISkippedPassRow;
+
 type AssetKind = "audio" | "model" | "other" | "texture";
 /** Budgets a project declares for its assets; exceeding one fails the build. */
 interface IAssetTargets {
@@ -303,12 +651,20 @@ interface IAssetAuxiliaryOutput {
     /** Manifest array receiving this output, for example `lightmaps`. */
     readonly manifestField: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /**
+     * An output the pass already content-addressed itself, relative to the output root — the
+     * shared image several models reference by the same relative URL. Absent means the compile
+     * names it `<stem>.<role>.<digest><extension>` beside the input's own output.
+     */
+    readonly outputPath?: string;
     /** Stable filename segment, for example `lightmap`. */
     readonly role: string;
 }
 interface IAssetPass {
     /** Deterministic settings that change output bytes; omitted for identity/default passes. */
     readonly cacheKey?: string;
+    /** True when this pass's emitted output requires a runtime decoder unavailable on mobile. */
+    readonly needsRuntimeDecoder?: boolean;
     readonly name: string;
     /**
      * JSON-serializable snapshot of every option that changes this pass's output. Part of the
@@ -320,6 +676,21 @@ interface IAssetPass {
     apply(input: Buffer, logicalPath: string): Buffer | IAssetPassOutput | Promise<Buffer | IAssetPassOutput>;
 }
 interface IAssetSourceConfig {
+    readonly budget?: Partial<IAssetBudget> | number | "none";
+    /** Source-relative globs omitted from the build; excluded bytes are always reported. */
+    readonly exclude?: readonly string[];
+    /**
+     * Audio conditioning: an object of options, or the string `"none"` to ship every clip exactly
+     * as committed. Absent means conditioning runs with defaults. See `passes/audio-config.ts` for
+     * how a game declares which clips loop, which are positional, and what a clip is for.
+     */
+    readonly audio?: IAudioConfig | "none";
+    /**
+     * The bound on how many workers a bake may use. A direct `concurrency` option overrides it;
+     * absent means the driver's default (`min(4, cores - 1)`). CI boxes and laptops differ, and
+     * a 6.8 GB pack does not get to decide the machine's fate.
+     */
+    readonly concurrency?: number;
     /**
      * Model optimization: an object of options, or the string `"none"` to ship every model
      * exactly as committed. Absent means optimization runs with defaults.
@@ -339,6 +710,14 @@ interface IModelsConfig {
     readonly lightmap?: ILightmapPassOptions;
     readonly passes?: IModelPassesOptions;
     readonly quantize?: IModelQuantizeOptions;
+    /**
+     * Write each distinct embedded image once under `shared/images/` and reference it from every
+     * model that carries it, instead of embedding a copy in each. A marketplace pack's eight pines
+     * stop shipping eight copies of the same bark map, and a rebuild reuses last build's encodes.
+     * Default true: the served GLB references files beside it, which a host must serve. False
+     * keeps each model self-contained and reports the duplicated embedded-image byte cost.
+     */
+    readonly sharedImages?: boolean;
     /** LOD simplification. Absent means none: it is the one lossy stage, and it is opt-in. */
     readonly simplify?: IModelSimplifyOptions;
     /**
@@ -353,11 +732,20 @@ interface IModelsConfig {
      */
     readonly virtual?: IModelVirtualOptions | "none";
 }
+interface IAudioConfig {
+    readonly normalise?: "ceiling" | "peak";
+    readonly overrides?: readonly IAudioOverride[];
+    readonly peakDb?: number;
+    readonly quality?: number;
+    readonly seamMaxRatio?: number;
+}
 interface ITexturesConfig {
+    readonly maxSize?: number;
     readonly overrides?: readonly ITextureOverride[];
     readonly quality?: number;
 }
 interface IAssetCompileOptions {
+    readonly concurrency?: number;
     readonly config?: IAssetSourceConfig;
     readonly cwd?: string;
     /** Includes the machine-readable health report on the result. */
@@ -368,6 +756,30 @@ interface IAssetCompileOptions {
      * registry (the KTX2 texture pass) runs unless `config.textures` is `"none"`.
      */
     readonly passes?: readonly IAssetPass[];
+    /**
+     * The order inputs are processed in, which under a scheduler is the order their work
+     * completes. `"sorted"` (the default) is the documented behaviour; `"reversed"` exists for
+     * the determinism gate, which must be able to run the same inputs through the driver in a
+     * different completion order and compare every emitted byte. It is a test seam, not a
+     * project setting, and a game config never carries it.
+     */
+    readonly processingOrder?: "reversed" | "sorted";
+    /**
+     * The platform this bake is for, which decides whether compression can ship at all.
+     *
+     * Android and iOS run the native host without WebAssembly, so they carry no Basis transcoder
+     * and no Meshopt decoder: a `.ktx2` texture or a meshopt-compressed mesh in a mobile bundle is
+     * a black screen, and `threenative build` refuses one with `TN_NATIVE_KTX2_UNSUPPORTED`. Web
+     * and desktop decode both.
+     *
+     * Absent means web — a direct `compileAssets` call, or a project that compiles once and serves
+     * the result. `threenative build` always names its `--target`, so the passes that a platform
+     * cannot decode drop for that build and stay on for every other one. This is the whole reason
+     * `assets.textures: "none"` used to be pinned in the scaffolded config: the author was asked to
+     * choose one constant for four targets, and every game that wanted Android shipped its web
+     * build uncompressed too. The build knows its target; it decides.
+     */
+    readonly platform?: "android" | "desktop" | "ios" | "web";
     readonly source?: string;
     /** Overrides resolution of three's Basis transcoder for the copy into the output root. */
     readonly transcoder?: IBasisTranscoder;
@@ -377,10 +789,41 @@ interface IBasisTranscoder {
     readonly wasmPath: string;
 }
 interface IAssetCompileResult {
+    /** How many workers the driver actually used: 1 for a sequential bake (custom passes, or a bound of 1). */
+    readonly concurrencyUsed: number;
+    /** One cost row per pass, driver-measured; empty when no bake ran. */
+    readonly passCosts: readonly IPassCostRow[];
+    /**
+     * What built-in compression shipped uncompressed, plus caller-supplied decoder-dependent passes
+     * omitted for this target as `kind: "pass"` rows. Turning a convention off does not turn its
+     * measurement off.
+     */
+    readonly skippedCompression: readonly ISkippedReportRow[];
+    readonly receipt?: IBakeReceipt;
     readonly report?: IAssetHealthReport;
     readonly skipped: number;
     readonly written: number;
 }
+/** One file this bake owns, and where it came from. */
+interface IBakeReceiptOutput {
+    readonly bytes: number;
+    /** Path relative to the output root, with `/` separators on every platform. */
+    readonly path: string;
+    /** The producer: the pass chain for a compiled input, or the auxiliary output's own role. */
+    readonly producer: string;
+    /** The source asset this came from, or `null` for a file the bake ships on its own behalf. */
+    readonly source: string | null;
+}
+/**
+ * Everything the bake wrote, so the delete-test can remove exactly that and nothing else.
+ *
+ * Deterministic given the same inputs — no wall-clock field — because this repository proves a
+ * change is neutral by diffing emitted output, and a timestamp makes every such diff dirty.
+ */
+interface IBakeReceipt {
+    readonly outputs: readonly IBakeReceiptOutput[];
+    readonly pipelineVersion: number;
+}
 /**
  * Resolves three's Basis transcoder through the project's own `three` install so a path that
  * moved between three versions fails the build here, as a named error, instead of 404ing at
@@ -390,73 +833,36 @@ declare function resolveBasisTranscoder(cwd: string): IBasisTranscoder;
 declare function compileAssets(options?: IAssetCompileOptions): Promise<IAssetCompileResult>;
 
 /**
- * The person-readable size report the compile step prints after encoding: one line per
- * compressed texture and optimized model plus a total, before against after. Pure formatting
- * so tests can pin the exact lines a build prints.
+ * Conditions a game's audio at build time and proves it did not destroy it.
+ *
+ * `AssetKind` has classified `.ogg`, `.wav` and `.mp3` as audio since the pipeline was written and
+ * nothing acted on it: audio was classified and then shipped through untouched. A lane generated
+ * nineteen clips for a game and conditioned them in a one-off script instead — downmix, cross-fade,
+ * DC removal, peak, encode — and the script reported success on every one while having measured
+ * nothing at all.
+ *
+ * What it actually got wrong was **content**, not joins: a chime that came back 92% low-mid with
+ * nothing above 1 kHz, and footsteps carrying heavy sub-bass. The joins were fine — an early
+ * reading that one bed was clicking came from comparing bare wrap steps between clips, and by the
+ * measurement that reflects audibility that bed has the *cleaner* join of the two. That correction
+ * is why the seam gate here judges a ratio and not a magnitude, and why the declared-band check
+ * exists at all: the defect that shipped was the one nobody thought to measure.
+ *
+ * So this is `model.ts`'s shape rather than a filter chain: it transforms bytes and then measures
+ * the result, and every measurement it takes is reported whether or not it was asked to assert on
+ * it. Turning a convention off must not turn its measurement off — an undeclared clip's seam is
+ * measured and lands in the receipt, it just does not fail the build.
+ *
+ * What it deliberately does not do:
+ *
+ * - **Own the mix.** Peak handling defaults to a *ceiling*, which only ever attenuates. Normalising
+ *   every clip up to the same peak would make a footstep as loud as a chime and force the game to
+ *   undo the pipeline in its volume settings; that is deciding how the game sounds, and it belongs
+ *   to the game. `normalise: "peak"` asks for the lift by name.
+ * - **Guess intent.** See `audio-config.ts`.
+ * - **Process at runtime.** Every measurement and every transform here happens once, at build time.
  */
-interface ITextureSizeRow {
-    readonly after: number;
-    readonly before: number;
-    readonly format: string | undefined;
-    readonly logicalPath: string;
-}
-declare function formatTextureSizes(rows: readonly ITextureSizeRow[]): readonly string[];
-/** What the model pass did to the images inside one `.glb`. */
-interface IEmbeddedTextureRow {
-    readonly bytesAfter: number;
-    readonly bytesBefore: number;
-    readonly count: number;
-    /** Chosen codec per embedded image, keyed by texture name. */
-    readonly formats?: Readonly<Record<string, string>>;
-    readonly gpuBytesAfter: number;
-    readonly gpuBytesBefore: number;
-    readonly resized: number;
-}
-/** What the cluster-DAG bake produced for one model. */
-interface IVirtualRow {
-    readonly bakeSeconds: number;
-    readonly clusters: number;
-    readonly levels: number;
-    readonly payloadBytes: number;
-    readonly primitives: number;
-    readonly skipped: number;
-    readonly stopReason: string;
-}
-/** What simplification delivered against what the config asked for. */
-interface ISimplifyRow {
-    readonly achievedRatio: number;
-    readonly error: number;
-    readonly requestedRatio: number;
-    readonly trianglesAfter: number;
-    readonly trianglesBefore: number;
-}
-/** One compiled model plus a total, before against after the optimization pass. */
-interface IModelSizeRow {
-    readonly after: number;
-    readonly before: number;
-    /** Embedded-image compression, when the model carried any. */
-    readonly embeddedTextures?: IEmbeddedTextureRow;
-    /** glTF extensions declared by the compiled output, e.g. EXT_meshopt_compression. */
-    readonly extensions?: readonly string[];
-    readonly logicalPath: string;
-    readonly lightmap?: {
-        readonly atlasHeight: number;
-        readonly atlasWidth: number;
-        readonly bakeMs: number;
-        readonly bytesAfter: number;
-        readonly bytesBefore: number;
-        readonly dilatedTexels: number;
-        readonly occludedTexels: number;
-        readonly validTexels: number;
-    };
-    /** LOD simplification, when it was configured for this model. */
-    readonly simplify?: ISimplifyRow;
-    /** The cluster-DAG bake, when it was configured for this model. */
-    readonly virtual?: IVirtualRow;
-    /** Triangle count of the compiled output, recorded in the manifest. */
-    readonly triangles?: number;
-}
-declare function formatModelSizes(rows: readonly IModelSizeRow[]): readonly string[];
+declare function audioPass(options?: IAudioPassOptions): IAssetPass;
 
 interface IPngInfo {
     readonly width: number;
@@ -467,8 +873,25 @@ interface IPngInfo {
 declare function parsePng(value: Buffer): IPngInfo | undefined;
 
 /**
- * Dev-mode compilation: watches the asset source directory and recompiles changed inputs into
- * the output directory, so the dev loop is not "rebuild to see a texture".
+ * Dev-mode compilation: watches the asset source directory and recompiles into the output
+ * directory, so the dev loop is not "rebuild to see a texture".
+ *
+ * A settled burst runs `compileAssets` over the whole project — the same call the build lane
+ * makes, once per burst rather than once per changed file. The compiler's cache is what makes
+ * that affordable: an input whose bytes and pass configuration are unchanged is a hit and is
+ * never re-encoded, so a save pays for the file that changed. It is also the only way the output
+ * root stays honest, because nothing that matters here is per-file. One cook writes the manifest,
+ * the receipt naming every file it owns, the shared images several models point at and the Basis
+ * runtime the KTX2 loader fetches for them; it deletes the outputs the previous receipt owned and
+ * this one does not; and it measures the byte budget across the project, which is the only scale
+ * a ceiling means anything at. Cooking one file in isolation can produce a file but never a
+ * project: it publishes an entry without the images underneath it, orphans yesterday's output in
+ * `public/` the moment a save renames it, and clears a whole-game budget by weighing one asset.
+ *
+ * The price is that a burst fails closed. One compile means a broken file fails the burst, so a
+ * good file saved beside it is not published either. That is the compiler's own contract — a pass
+ * failure stops the build with the asset path — and the safe direction here: the last good cook
+ * keeps serving, the named failure goes to stderr, and the next good save heals it.
  *
  * Watcher mechanism: `node:fs.watch({ recursive: true })` — deliberately neither chokidar nor
  * Vite's own server watcher. This package is Node-only with zero runtime dependencies; Vite's
@@ -480,6 +903,12 @@ declare function parsePng(value: Buffer): IPngInfo | undefined;
 interface IAssetWatchSummary {
     readonly compiled: readonly string[];
     readonly failed: readonly string[];
+    /**
+     * One cost row per pass for this burst's compile, the same records a build emits. Present only
+     * when the burst compiled something; a burst compiles the whole project, so an input the cache
+     * skipped is counted in `cachedInputs` rather than left out.
+     */
+    readonly passCosts?: readonly IPassCostRow[];
 }
 interface IAssetWatchOptions extends IAssetCompileOptions {
     /** Quiet window that coalesces a burst of saves into one recompile. Default 100 ms. */
@@ -499,4 +928,4 @@ interface IAssetWatchHandle {
 }
 declare function watchAssets(options?: IAssetWatchOptions): IAssetWatchHandle;
 
-export { type AssetFindingGrade, type AssetKind, type IAssetCompileOptions, type IAssetCompileResult, type IAssetFinding, type IAssetHealthEntry, type IAssetHealthInput, type IAssetHealthReport, type IAssetPass, type IAssetPassOutput, type IAssetSourceConfig, type IAssetTargets, type IAssetWatchHandle, type IAssetWatchOptions, type IAssetWatchSummary, type IBasisTranscoder, type IEmbeddedTextureRow, type IEmbeddedTextureSummary, type ILightmapPassOptions, type IModelPassOptions, type IModelPassesOptions, type IModelQuantizeOptions, type IModelSimplifyOptions, type IModelSimplifySummary, type IModelSizeRow, type IModelStats, type IModelTextureBinding, type IModelTextureBindings, type IModelTextureOverride, type IModelTexturesOptions, type IModelsConfig, type IPngInfo, type ISimplifyRow, type ITextureOverride, type ITexturePassOptions, type ITextureSizeRow, type ITextureStats, type ITexturesConfig, type TextureCodec, compileAssets, formatHealthReport, formatModelSizes, formatTextureSizes, lightmapPass, modelPass, parsePng, resolveBasisTranscoder, runHealthReport, texturePass, watchAssets };
+export { type AssetFindingGrade, type AssetKind, type AudioBand, type AudioConditioning, type AudioNormalisation, type IAssetCompileOptions, type IAssetCompileResult, type IAssetFinding, type IAssetHealthEntry, type IAssetHealthInput, type IAssetHealthReport, type IAssetPass, type IAssetPassOutput, type IAssetSourceConfig, type IAssetTargets, type IAssetWatchHandle, type IAssetWatchOptions, type IAssetWatchSummary, type IAudioConfig, type IAudioLoopOptions, type IAudioOverride, type IAudioPassOptions, type IAudioRow, type IAudioSpectrumExpectation, type IBakeReceipt, type IBakeReceiptOutput, type IBasisTranscoder, type IEmbeddedTextureRow, type IEmbeddedTextureSummary, type ILightmapPassOptions, type IModelPassOptions, type IModelPassesOptions, type IModelQuantizeOptions, type IModelSimplifyOptions, type IModelSimplifySummary, type IModelSizeRow, type IModelStats, type IModelTextureBinding, type IModelTextureBindings, type IModelTextureOverride, type IModelTexturesOptions, type IModelsConfig, type IPassCostAssetRow, type IPassCostRow, type IPngInfo, type ISimplifyRow, type ITextureOverride, type ITexturePassOptions, type ITextureSizeRow, type ITextureStats, type ITexturesConfig, type PassCostStatus, type TextureCodec, audioPass, compileAssets, formatAudioSizes, formatHealthReport, formatModelSizes, formatPassCosts, formatTextureSizes, lightmapPass, modelPass, parseAudioConfig, parsePng, resolveBasisTranscoder, runHealthReport, texturePass, watchAssets };