@threenative/assets 0.3.2 → 0.3.5

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,20 @@ 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;
+}
+
+interface IModelDedupeSummary {
+    /** Distinct cooked outputs among the model sources that took part. */
+    readonly cooked: number;
+    /** Cooked bytes the duplicates would have written on their own. */
+    readonly savedBytes: number;
+    /** Model sources that took part, canonicals and duplicates alike. */
+    readonly sources: number;
+}
 
 type AssetFindingGrade = "fail" | "ok" | "warn";
 interface IAssetFinding {
@@ -99,6 +115,89 @@ 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 cutout?: boolean;
+    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 {
+    /**
+     * Convert eligible `BLEND` foliage to alpha-tested in the cook (PRD-458 §4). Default `true`,
+     * because a needle card exported as `BLEND` is refused a chain by rule and the tree then draws
+     * LOD0 forever. `false` keeps the authored blending; per asset, `cutout` in an override entry.
+     */
+    readonly cutout?: boolean;
+    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.
  *
@@ -192,6 +291,74 @@ interface IAudioPassOptions {
 /** `"none"` drops the pass; an object configures it; absent means the defaults run. */
 declare function parseAudioConfig(raw: unknown): IAudioPassOptions | undefined;
 
+interface IModelCompactInstanceOptions {
+    /**
+     * Minimum number of nodes that must share one mesh before it is instanced, default 2.
+     * gltf-transform's own default is 5; the lower floor is what lets a paired prop instance.
+     */
+    readonly min?: number;
+}
+interface IModelCompactOptions {
+    readonly flatten?: boolean;
+    readonly instance?: boolean | IModelCompactInstanceOptions;
+    readonly join?: boolean;
+    /** Extra exact node names to protect, on top of the regex and the structural rules. */
+    readonly protectedNames?: readonly string[];
+    /**
+     * Case-insensitive node-name regex source for nodes the game looks up or moves. Defaults to
+     * {@link DEFAULT_PROTECTED_PATTERN}; an invalid source throws rather than silently protecting nothing.
+     */
+    readonly protectedPattern?: string;
+}
+/** Why a node was kept out of join/instance. */
+type TModelProtectedRule = "allow-list" | "animation-ancestor" | "animation-target" | "regex" | "skin-joint";
+interface IModelProtectedNode {
+    readonly name: string;
+    readonly rule: TModelProtectedRule;
+}
+interface IModelCompactSummary {
+    /** Whether each pass ran and how many primitives/nodes it removed. */
+    readonly flatten: {
+        readonly enabled: boolean;
+        /** Nodes reparented toward the scene root; a node left in place is not counted. */
+        readonly reparented: number;
+    };
+    readonly instance: {
+        readonly batches: number;
+        readonly enabled: boolean;
+        readonly instances: number;
+        /** Why no batch was created, when none was. */
+        readonly reason?: string;
+    };
+    readonly join: {
+        readonly enabled: boolean;
+        readonly primitivesAfter: number;
+        readonly primitivesBefore: number;
+    };
+    readonly nodesAfter: number;
+    readonly nodesBefore: number;
+    readonly primitivesAfter: number;
+    readonly primitivesBefore: number;
+    /**
+     * Named scene nodes that existed before compaction and are gone after it. Empty is the
+     * expected result of a run whose protected set covered every name the game addresses; a
+     * non-empty list is the report's warning that a `getObjectByName` can now return undefined.
+     */
+    readonly removed: readonly string[];
+    /** Every node kept out of compaction, with the rule that protected it, sorted by name. */
+    readonly protected: readonly IModelProtectedNode[];
+}
+/** The compaction policy with every default resolved, so it is a stable cache key. */
+interface IResolvedCompactOptions {
+    readonly flatten: boolean;
+    readonly instance: false | IModelCompactInstanceOptions;
+    readonly join: boolean;
+    readonly protectedNames: readonly string[];
+    readonly protectedPattern: string;
+    /** Algorithm identity, so an upgraded pass never re-serves a cache from an older build. */
+    readonly version: number;
+}
+
 /**
  * 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
@@ -267,6 +434,13 @@ interface IModelTextureOverride {
     readonly slot: string;
 }
 interface IModelTexturesOptions {
+    /**
+     * Resolved by the compiler from the target's runtime capabilities, never by a project: the
+     * target has no KTX2 decoder, so an over-cap embedded image is box-resampled and re-emitted as
+     * a PNG instead of being encoded. Everything else — authored-byte retention under the cap,
+     * per-image deduplication, colour space — is unchanged.
+     */
+    readonly decoderFree?: boolean;
     /**
      * Longest edge an embedded image may keep, default 2048. Larger images are box-resampled
      * down preserving aspect ratio; smaller ones are never upscaled.
@@ -387,6 +561,12 @@ interface IModelSimplifyOptions {
 }
 interface IModelPassOptions {
     readonly passes?: IModelPassesOptions;
+    /**
+     * Lossless scene-graph compaction (flatten → instance → join) against one protected-node set.
+     * Absent means on with defaults; `false` is the kill switch; an object configures the
+     * sub-passes, the protected-name allow-list and the name regex. It never decimates geometry.
+     */
+    readonly compact?: boolean | IModelCompactOptions;
     /** 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. */
@@ -414,6 +594,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 +662,63 @@ 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;
+    /**
+     * The foliage cutout conversion the cook ran before generating (PRD-458 §4): the `BLEND`
+     * materials that became alpha-tested, and the ones that kept blending and why.
+     */
+    readonly cutout?: {
+        readonly converted: readonly string[];
+        readonly kept: readonly {
+            readonly name: string;
+            readonly reason: string;
+        }[];
+    };
+    /** 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. */
@@ -581,6 +825,19 @@ interface IAudioRow {
  */
 declare function formatAudioSizes(rows: readonly IAudioRow[]): readonly string[];
 /** One compiled model plus a total, before against after the optimization pass. */
+/** The cook's material merge (PRD-458 §5): what collapsed, and the counts either side of it. */
+interface IMaterialsRow {
+    /** Distinct signatures — the count a draw call is bound by. */
+    readonly distinct: {
+        readonly after: number;
+        readonly before: number;
+    };
+    readonly materials: {
+        readonly after: number;
+        readonly before: number;
+    };
+    readonly merged: readonly string[];
+}
 interface IModelSizeRow {
     readonly after: number;
     readonly before: number;
@@ -601,8 +858,14 @@ 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;
+    /** Lossless scene-graph compaction (PRD-443), when it ran. */
+    readonly compact?: IModelCompactSummary;
     /** The cluster-DAG bake, when it was configured for this model. */
     readonly virtual?: IVirtualRow;
+    /** The material merge the cook ran unconditionally, before any other geometry stage. */
+    readonly materials?: IMaterialsRow;
     /** Triangle count of the compiled output, recorded in the manifest. */
     readonly triangles?: number;
 }
@@ -666,6 +929,13 @@ interface IAssetPass {
     /** True when this pass's emitted output requires a runtime decoder unavailable on mobile. */
     readonly needsRuntimeDecoder?: boolean;
     readonly name: string;
+    /**
+     * Input kinds whose bytes this pass can change. The compile hashes only the passes that can
+     * change an asset into that asset's digest, so a model-only option edit does not rename every
+     * texture. `undefined` (the default for a caller-supplied pass) means any kind, which stays
+     * conservative: an unknown pass can change every asset.
+     */
+    readonly appliesTo?: readonly AssetKind[];
     /**
      * JSON-serializable snapshot of every option that changes this pass's output. Part of the
      * compile cache key: without it, editing a config value (texture quality, quantize bits, an
@@ -687,7 +957,7 @@ interface IAssetSourceConfig {
     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
+     * absent means the driver's default (cores - 1, bounded by ~2 GB of memory a worker, at most 12). CI boxes and laptops differ, and
      * a 6.8 GB pack does not get to decide the machine's fate.
      */
     readonly concurrency?: number;
@@ -696,6 +966,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;
@@ -706,6 +982,11 @@ interface IAssetSourceConfig {
     readonly textures?: ITexturesConfig | "none";
 }
 interface IModelsConfig {
+    /**
+     * Lossless scene-graph compaction (flatten → instance → join) against one protected-node set.
+     * Default true ({@link IModelCompactOptions}); `false` ships the scene graph as authored.
+     */
+    readonly compact?: boolean | IModelCompactOptions;
     /** Generate standard TEXCOORD_1 lightmap UVs. Absent means no lightmap pass. */
     readonly lightmap?: ILightmapPassOptions;
     readonly passes?: IModelPassesOptions;
@@ -780,6 +1061,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;
@@ -801,6 +1092,11 @@ interface IAssetCompileResult {
     readonly skippedCompression: readonly ISkippedReportRow[];
     readonly receipt?: IBakeReceipt;
     readonly report?: IAssetHealthReport;
+    /**
+     * What the model cook saved by cooking content-identical sources once, when this project has
+     * any model source. `cooked` is the number of distinct outputs those sources produced.
+     */
+    readonly dedupe?: IModelDedupeSummary;
     readonly skipped: number;
     readonly written: number;
 }
@@ -928,4 +1224,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 IModelCompactInstanceOptions, type IModelCompactOptions, type IModelCompactSummary, type IModelPassOptions, type IModelPassesOptions, type IModelProtectedNode, 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 IResolvedCompactOptions, type ISimplifyRow, type ITextureOverride, type ITexturePassOptions, type ITextureSizeRow, type ITextureStats, type ITexturesConfig, type PassCostStatus, type TModelProtectedRule, 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 };