@threenative/assets 0.3.2 → 0.3.3

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { Document, Material } from '@gltf-transform/core';
+
 /**
  * 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).
@@ -46,6 +48,11 @@ interface IAssetBudget {
     readonly uncooked: number | "none";
     readonly total: number | "none";
 }
+/** Runtime decoder capabilities that decide which emitted bytes can be compressed on-device. */
+interface IAssetRuntimeDecoderCapabilities {
+    readonly ktx2: boolean;
+    readonly meshopt: boolean;
+}
 
 type AssetFindingGrade = "fail" | "ok" | "warn";
 interface IAssetFinding {
@@ -99,6 +106,82 @@ 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[];
 
+/**
+ * What the `minTriangles` pre-filter is measured against.
+ *
+ * `"primitive"` compares each primitive on its own; `"asset"` compares the whole source asset's
+ * total. The asset total is the evidence-backed default: a carrier can be 347,497 triangles split
+ * over 300 primitives of ~1,200, where an absolute per-primitive floor measures how the artist
+ * happened to split the mesh rather than whether simplification would pay. Whichever is chosen, the
+ * floor is only a cheap pre-filter — the measured saving rule below is the gate.
+ */
+type LodMinTrianglesScope = "primitive" | "asset";
+
+/** Generation knobs, shared by every preset (PRD-377 §3.2); both are ceilings, not promises. */
+interface IModelLodGenerationOptions {
+    /**
+     * Versioned increasing geometric-error targets, in normalized mesh-extent units. Each target is
+     * simplified from LOD0 independently; a target that cannot reduce is dropped. Default
+     * {@link LOD_ERROR_TARGETS}.
+     */
+    readonly errorTargets?: readonly number[];
+    /** Levels in the chain including LOD0; integer 1–8. Default {@link DEFAULT_LOD_MAX_LEVELS}. */
+    readonly maxLevels?: number;
+    /**
+     * Fraction of its predecessor's triangles a derived level must save to be kept. Default
+     * {@link LOD_MIN_SAVING}. This is the benefit gate: an inability to reach it is a normal skip.
+     */
+    readonly minSaving?: number;
+    /**
+     * Cheap pre-filter floor in triangles. It is not the benefit gate — {@link minSaving} is — and
+     * only skips work where the simplifier's fixed per-call cost would dominate. Default
+     * {@link DEFAULT_LOD_MIN_TRIANGLES}.
+     */
+    readonly minTriangles?: number;
+    /**
+     * What {@link minTriangles} is measured against. Default
+     * {@link DEFAULT_LOD_MIN_TRIANGLES_SCOPE}, which floors the whole asset rather than each
+     * primitive, so a model split into many small primitives is still measured by its total.
+     */
+    readonly minTrianglesScope?: LodMinTrianglesScope;
+    /**
+     * Opt-in far rung that joins a mesh's same-material primitives into one draw per material group
+     * (PRD-377 §4.4 extension). **Default `false`: with no option the cook is byte-identical to
+     * today.** A join never crosses a material, never touches a skinned, morph-target or animated
+     * node, and never leaves the mesh's own node, so authored LOD0, node identity and picking are
+     * untouched; the joined geometry is an additional far rung beside LOD0.
+     */
+    readonly join?: boolean;
+}
+/** Quality policy for automatic LOD; it selects the projected pixel-error budget (PRD-377 §3.2). */
+type LodPreset = "aggressive" | "balanced" | "quality";
+/** Screen-space selection knobs; they change what the runtime picks, never what is baked. */
+interface IModelLodRuntimeOptions {
+    /** Projected geometric-error budget in raster pixels; positive finite. */
+    readonly maxPixelError?: number;
+    /** Fraction in `[0, 0.5)`, default 0.15, that stabilizes coarsening at a boundary. */
+    readonly hysteresis?: number;
+}
+/** A partial override for one asset; nested objects overlay, they never replace. */
+interface IModelLodOverride {
+    readonly enabled?: boolean;
+    readonly generation?: IModelLodGenerationOptions;
+    readonly preset?: LodPreset;
+    readonly runtime?: IModelLodRuntimeOptions;
+}
+/**
+ * `assets.lod`, as the compile step reads it. Absent or `{}` resolves to enabled/balanced; `false`
+ * and `{ enabled: false }` are equivalent absolute kill switches that no per-asset override can
+ * re-enable. Resolution is per asset and happens where the asset is known (PRD-377 §3.2, §5).
+ */
+interface IModelLodOptions {
+    readonly enabled?: boolean;
+    readonly generation?: IModelLodGenerationOptions;
+    readonly overrides?: Readonly<Record<string, boolean | IModelLodOverride>>;
+    readonly preset?: LodPreset;
+    readonly runtime?: IModelLodRuntimeOptions;
+}
+
 /**
  * The five bands a clip's content is judged in, contiguous and gapless up to Nyquist.
  *
@@ -414,6 +497,13 @@ interface IModelPassOptions {
      * would hide that.
      */
     readonly virtual?: IModelVirtualOptions | "none";
+    /**
+     * Automatic discrete LOD (`assets.lod`). Absent means no automatic generation in this phase;
+     * `false` / `"none"` is the kill switch, and an object carries the resolved policy. Per-asset
+     * overrides key off the canonical source asset path, which is why the pass resolves them here
+     * rather than at registry construction.
+     */
+    readonly lod?: boolean | IModelLodOptions | "none";
 }
 
 /**
@@ -475,6 +565,52 @@ interface ISimplifyRow {
     readonly trianglesAfter: number;
     readonly trianglesBefore: number;
 }
+/** What automatic discrete generation produced for one model (PRD-377 §4.3). */
+/** One material group inside an opt-in joined far rung: what it collapsed and how much it draws. */
+interface ILodJoinedGroupRow {
+    readonly material: string;
+    readonly primitives: number;
+    readonly triangles: number;
+}
+/** The opt-in joined far rung as the manifest carries it: draws and the primitives collapsed. */
+interface ILodJoinedRow {
+    readonly draws: number;
+    readonly groups: readonly ILodJoinedGroupRow[];
+    readonly primitives: number;
+    readonly triangles: number;
+    readonly trianglesBefore: number;
+}
+interface ILodRow {
+    /** Bytes the derived index buffers add, before compression. */
+    readonly byteOverhead: number;
+    /** Migration/legacy notes the resolver raised, by code. */
+    readonly diagnostics: readonly string[];
+    /** The resolved increasing geometric-error targets, as the bake consumed them. */
+    readonly errorTargets: readonly number[];
+    readonly fingerprint: string;
+    readonly generated: number;
+    /** Whether the opt-in join was requested; {@link joined} is present only when it did something. */
+    readonly join: boolean;
+    /** The opt-in joined far rung's honesty record, when one was produced. */
+    readonly joined?: ILodJoinedRow;
+    readonly levels: number;
+    readonly maxLevels: number;
+    /** Fraction of its predecessor's triangles a derived level had to save. */
+    readonly minSaving: number;
+    readonly minTriangles: number;
+    /** What `minTriangles` measured against: `"primitive"` or `"asset"`. */
+    readonly minTrianglesScope: string;
+    readonly preset: string;
+    readonly reasons: readonly string[];
+    /** The runtime selection budget this asset ships with; the loader reads it from the manifest. */
+    readonly runtime: {
+        readonly hysteresis: number;
+        readonly maxPixelError: number;
+    };
+    readonly skipped: 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. */
@@ -601,6 +737,8 @@ interface IModelSizeRow {
     };
     /** LOD simplification, when it was configured for this model. */
     readonly simplify?: ISimplifyRow;
+    /** Automatic discrete LOD generation (PRD-377), when the effective policy ran. */
+    readonly lod?: ILodRow;
     /** The cluster-DAG bake, when it was configured for this model. */
     readonly virtual?: IVirtualRow;
     /** Triangle count of the compiled output, recorded in the manifest. */
@@ -696,6 +834,12 @@ interface IAssetSourceConfig {
      * exactly as committed. Absent means optimization runs with defaults.
      */
     readonly models?: IModelsConfig | "none";
+    /**
+     * Automatic discrete LOD (`assets.lod`): a boolean kill switch/enable, an object carrying the
+     * resolved generation policy, or `"none"`. Absent means this phase generates nothing; the
+     * default-on decision is a later phase (PRD-377 §8).
+     */
+    readonly lod?: boolean | IModelLodOptions | "none";
     readonly output?: string;
     readonly source?: string;
     readonly targets?: IAssetTargets;
@@ -780,6 +924,16 @@ interface IAssetCompileOptions {
      * build uncompressed too. The build knows its target; it decides.
      */
     readonly platform?: "android" | "desktop" | "ios" | "web";
+    /**
+     * What the runtime that will execute this bake can decode, when the caller has probed it.
+     *
+     * `platform` is a proxy: it answers "android and iOS have no WebAssembly" for the targets this
+     * repository ships. A desktop host can also lack WebAssembly — the Linux arm64 lane builds
+     * QuickJS over wgpu-native — and then the same meshopt/KTX2 passes it would keep produce an
+     * asset nothing can decode. `threenative build` reads the engine from the runtime binary it will
+     * package and passes the real capability here; absent, the platform-derived default stands.
+     */
+    readonly runtimeDecoders?: IAssetRuntimeDecoderCapabilities;
     readonly source?: string;
     /** Overrides resolution of three's Basis transcoder for the copy into the output root. */
     readonly transcoder?: IBasisTranscoder;
@@ -928,4 +1082,239 @@ interface IAssetWatchHandle {
 }
 declare function watchAssets(options?: IAssetWatchOptions): IAssetWatchHandle;
 
-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 };
+/**
+ * A deterministic texture atlas packer.
+ *
+ * The reference game's carrier is 95 meshes over 76 materials and **73 distinct texture sources** —
+ * one texture per material, because an imported model carries a material per part. A per-material
+ * merge over content shaped like that has nothing to collapse: it found 274 buckets holding 213
+ * singletons and moved no frame time. That null result is the evidence for this file. Materials
+ * cannot be deduplicated while each one owns a private texture, so the atlas is the prerequisite
+ * and everything downstream — dedupe, merge, instancing — is priced against it.
+ *
+ * Two properties, both load-bearing:
+ *
+ *  - **Deterministic.** Two runs over the same inputs place every source at the same pixel. The
+ *    order is derived from the sources themselves (taller first, then wider, then the key), never
+ *    from map iteration or filesystem order, because a build that packs differently on a rebuild
+ *    invalidates every downstream cache and makes a screenshot-parity gate meaningless.
+ *  - **It refuses what it cannot do.** A source that tiles is excluded and reported, never packed
+ *    and silently clamped: a repeating surface whose UVs leave `[0, 1]` reads neighbouring pages
+ *    once it shares one, which is a visible bug that looks like corruption rather than like a
+ *    packing decision.
+ *
+ * Shelf packing, not a perfect bin: sorted by height it wastes a few percent of a page against an
+ * optimal solver nobody can read, and the cost of a wasted page is bytes, while the cost of a
+ * wrong one is a visual bug. `ponytail: shelf packer, revisit only if page count is measured to
+ * matter.`
+ */
+/** One image offered to the packer. */
+interface IAtlasSource {
+    /** Stable identity — the content hash or the texture's URI. Ties in the sort break on this. */
+    readonly key: string;
+    readonly width: number;
+    readonly height: number;
+    /**
+     * Whether the material samples this source outside `[0, 1]`. A tiling source cannot share a
+     * page, and saying so is the source's job, not a guess the packer makes from pixels.
+     */
+    readonly tiles?: boolean;
+}
+/** Where one source landed. */
+interface IAtlasPlacement {
+    readonly key: string;
+    readonly page: number;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** The UV transform for one source: `uv' = uv * scale + offset`. */
+interface IAtlasTransform {
+    readonly page: number;
+    readonly offsetX: number;
+    readonly offsetY: number;
+    readonly scaleX: number;
+    readonly scaleY: number;
+}
+/** Why a source was left out. Every exclusion is reported; none is silent. */
+type AtlasExclusionReason = "tiles" | "too-large";
+interface IAtlasExclusion {
+    readonly key: string;
+    readonly reason: AtlasExclusionReason;
+}
+interface IAtlasPage {
+    readonly index: number;
+    readonly width: number;
+    readonly height: number;
+    readonly placements: readonly IAtlasPlacement[];
+}
+interface IAtlasResult {
+    readonly pages: readonly IAtlasPage[];
+    /** Keyed by source key, in the packer's own deterministic order. */
+    readonly transforms: ReadonlyMap<string, IAtlasTransform>;
+    readonly excluded: readonly IAtlasExclusion[];
+}
+interface IAtlasOptions {
+    /** Page edge in pixels. Default 4096. */
+    readonly pageSize?: number;
+    /**
+     * Transparent pixels kept between neighbours, so a mip level or a bilinear tap cannot reach the
+     * next source. Default 4 — two levels of mip bleed at the sizes this packs.
+     */
+    readonly padding?: number;
+}
+/**
+ * Packs sources into pages and answers the UV transform for each.
+ *
+ * Fails closed on a malformed source: a zero or non-integer dimension is a decoder that did not
+ * decode, and packing it would put a divide-by-zero in every UV it rewrites.
+ */
+declare function packAtlas(sources: readonly IAtlasSource[], options?: IAtlasOptions): IAtlasResult;
+/**
+ * The manifest a build writes beside the pages.
+ *
+ * Sorted by key so two runs produce byte-identical JSON — the same reason the packing order is
+ * derived rather than inherited.
+ */
+declare function atlasManifest(result: IAtlasResult): string;
+
+/**
+ * Moving a mesh's UVs onto its atlas page, and deciding which meshes may not go.
+ *
+ * The rewrite itself is two multiplies and two adds per vertex. The decision in front of it is the
+ * part that matters: a surface that samples outside `[0, 1]` tiles, and a tiling surface on a
+ * shared page reads its neighbours. That is a visible bug that looks like corruption, so the
+ * policy here is to detect it from the geometry's own UVs and from the sampler's wrap mode, refuse
+ * to pack the source, and report it — never to clamp, and never to guess from the image.
+ */
+
+/** glTF sampler wrap modes; `10497` is REPEAT and `33648` is MIRRORED_REPEAT. */
+declare const WRAP_REPEAT = 10497;
+declare const WRAP_MIRRORED_REPEAT = 33648;
+declare const WRAP_CLAMP_TO_EDGE = 33071;
+/** Whether this UV set samples outside the unit square, and therefore tiles. */
+declare function uvsTile(uv: ArrayLike<number>): boolean;
+/** Whether the sampler asks to repeat. A wrap mode the packer does not know is treated as tiling. */
+declare function wrapTiles(wrapS: number | undefined, wrapT: number | undefined): boolean;
+/**
+ * Rewrites a UV buffer in place onto its atlas page.
+ *
+ * In place because the caller owns a freshly-decoded accessor and a second buffer per mesh is a
+ * copy of the whole scene's UVs for nothing. Throws on an odd-length buffer rather than rewriting
+ * half a coordinate.
+ */
+declare function rewriteUvs(uv: Float32Array, transform: IAtlasTransform): Float32Array;
+/**
+ * The texel a rewritten UV resolves to, in the source image's own pixel space.
+ *
+ * This is the inverse of `rewriteUvs` composed with the page geometry, and it exists so a test can
+ * assert the round trip rather than assert the arithmetic against itself: sample a texel, rewrite,
+ * resolve, and land within a texel of where you started.
+ */
+declare function resolveSourceTexel(atlasUv: readonly [number, number], transform: IAtlasTransform, source: {
+    readonly width: number;
+    readonly height: number;
+}): {
+    x: number;
+    y: number;
+};
+
+/**
+ * Collapsing materials that became identical once their textures shared a page.
+ *
+ * This is the step the atlas exists to enable, and it is also the step that falsifies the atlas.
+ * The reference game's merge found 274 buckets holding 213 singletons because every material owned
+ * a private texture; if the singleton count does not fall once those textures share pages, the
+ * atlas hypothesis is wrong and everything priced on it has to be repriced. So the signature here
+ * is deliberately conservative: two materials collapse only when every field that can change a
+ * pixel agrees, and anything the signature does not know about keeps them apart.
+ */
+/** The material state a signature is taken over. Structural, so a glTF or a three material fits. */
+interface IMaterialState {
+    readonly name?: string;
+    /** Texture identity per slot *after* atlasing — the page, not the original image. */
+    readonly textures: Readonly<Record<string, string | undefined>>;
+    /** Scalar and vector uniforms: base colour, metallic, roughness, emissive, alpha cutoff, … */
+    readonly uniforms: Readonly<Record<string, number | readonly number[] | string | boolean | undefined>>;
+    /** Anything that changes how the surface is drawn rather than what it samples. */
+    readonly flags: Readonly<Record<string, number | string | boolean | undefined>>;
+}
+/**
+ * A stable signature over everything that decides how this material looks.
+ *
+ * The name is deliberately **not** in it: an imported pack names a material per part, and letting
+ * the name separate them is exactly the property that made 213 singletons. Every other field is,
+ * including ones this pipeline does not understand, because an unknown field that differs is a
+ * reason not to collapse.
+ */
+declare function materialSignature(material: IMaterialState): string;
+/** One group of materials that became the same material. */
+interface IMaterialBucket {
+    readonly signature: string;
+    /** Names in input order, so a report can say which materials collapsed into which. */
+    readonly members: readonly string[];
+}
+interface IDedupeCensus {
+    /** Distinct signatures — the material count after deduplication. */
+    readonly buckets: number;
+    /** Buckets holding exactly one material: the count the atlas has to move. */
+    readonly singletons: number;
+    /** Materials in. */
+    readonly materials: number;
+}
+/** Groups materials by signature, in first-seen order so two runs report the same thing. */
+declare function dedupeMaterials(materials: readonly IMaterialState[]): {
+    buckets: readonly IMaterialBucket[];
+    census: IDedupeCensus;
+};
+/**
+ * The same materials with every texture slot repointed at its atlas page.
+ *
+ * A slot whose source was excluded from the atlas keeps its original texture, which is what makes
+ * the census honest: those materials stay singletons, and the report says how many.
+ */
+declare function withAtlasTextures(materials: readonly IMaterialState[], pageOf: (texture: string) => string | undefined): IMaterialState[];
+
+/**
+ * The bucket census: what a merge could collapse, before and after an atlas.
+ *
+ * "Fewer objects" was the obvious lever on the reference game and it recovered nothing — a runtime
+ * per-material merge replaced 246 of 1,561 meshes and moved no frame time, because 274 buckets
+ * held 213 singletons. The census is the number to read before promising a merge, and this is the
+ * thing that reads it: it walks a glTF document's materials, takes the same signature the dedupe
+ * takes, and reports the buckets twice — once as authored, once with every atlasable texture
+ * repointed at a page.
+ *
+ * The second number is the falsification point for the whole atlas argument. If singletons do not
+ * fall, the atlas is not the lever and nothing downstream of it should be built.
+ */
+
+/** One model's census. */
+interface IContentCensus {
+    readonly model: string;
+    readonly meshes: number;
+    readonly primitives: number;
+    readonly materials: number;
+    /** Distinct texture images the materials reference. */
+    readonly textureSources: number;
+    /** Sources the packer refused, with the reason — tiling surfaces, mostly. */
+    readonly excluded: number;
+    readonly atlasPages: number;
+    readonly before: IDedupeCensus;
+    readonly after: IDedupeCensus;
+}
+/** Reads a material into the state the signature is taken over. */
+declare function materialStateOf(material: Material): IMaterialState;
+/**
+ * Censuses one document: what its materials are now, and what they would be once their textures
+ * shared atlas pages.
+ *
+ * A texture whose size the document does not state cannot be packed, so it is reported as excluded
+ * rather than assumed square — an assumed size is an assumed page layout.
+ */
+declare function censusDocument(model: string, document: Document, pageSize?: number): IContentCensus;
+/** Totals across a set of models, so a scene's census is one line rather than twenty-nine. */
+declare function totalCensus(entries: readonly IContentCensus[]): Omit<IContentCensus, "model">;
+
+export { type AssetFindingGrade, type AssetKind, type AtlasExclusionReason, 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 IAtlasExclusion, type IAtlasOptions, type IAtlasPage, type IAtlasPlacement, type IAtlasResult, type IAtlasSource, type IAudioConfig, type IAudioLoopOptions, type IAudioOverride, type IAudioPassOptions, type IAudioRow, type IAudioSpectrumExpectation, type IBakeReceipt, type IBakeReceiptOutput, type IBasisTranscoder, type IContentCensus, type IDedupeCensus, type IEmbeddedTextureRow, type IEmbeddedTextureSummary, type ILightmapPassOptions, type IMaterialBucket, type IMaterialState, 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, WRAP_CLAMP_TO_EDGE, WRAP_MIRRORED_REPEAT, WRAP_REPEAT, atlasManifest, audioPass, censusDocument, compileAssets, dedupeMaterials, formatAudioSizes, formatHealthReport, formatModelSizes, formatPassCosts, formatTextureSizes, lightmapPass, materialSignature, materialStateOf, modelPass, packAtlas, parseAudioConfig, parsePng, resolveBasisTranscoder, resolveSourceTexel, rewriteUvs, runHealthReport, texturePass, totalCensus, uvsTile, watchAssets, withAtlasTextures, wrapTiles };