@threenative/assets 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 João Paulo Furtado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @threenative/assets
+
+The asset compile step for ThreeNative games. Walks a game's `assets/` source
+directory, applies ordered passes over each input, and writes content-addressed
+outputs into `public/` alongside an `assets.manifest.json` describing every
+managed file.
+
+Node-only. Carries the encoder dependencies the runtime must never inherit.
+
+## Embedded model textures
+
+The images inside a `.glb` go through the pipeline too, on by default. A prop carrying three
+2048x2048 JPEGs is a small file and about 64 MiB of VRAM once the driver decodes it, so each
+embedded image is transcoded to KTX2/Basis (UASTC for normal maps, ETC1S for colour and
+metallic-roughness) and capped to a maximum resolution. The compiled model declares
+`KHR_texture_basisu`; `ctx.assets.model()` wires three's shared, support-detected `KTX2Loader`
+for exactly those files, and the Basis transcoder is copied next to the compiled assets even in
+a project that has no standalone texture at all.
+
+```ts
+assets: {
+  models: {
+    // Defaults: every image compressed, longest edge capped at 2048.
+    textures: { maxSize: 1024, quality: 150, overrides: [{ slot: "normalTexture", codec: "uastc" }] },
+    // Off unless declared: the one stage that removes triangles on purpose.
+    simplify: { ratio: 0.5, error: 0.001 },
+  },
+}
+```
+
+`models: { textures: "none" }` ships every image exactly as authored. Measured on an 11.2 MB
+sandbox prop with three 2048x2048 JPEGs:
+
+| Setting | File | Embedded images | Estimated GPU bytes |
+| --- | --- | --- | --- |
+| geometry only (`textures: "none"`) | 10.74 -> 7.74 MiB | untouched | 64.00 MiB |
+| default (`maxSize: 2048`) | 10.74 -> 6.13 MiB | 6.93 -> 5.33 MiB | 10.67 MiB |
+| `maxSize: 1024` | 10.74 -> 2.30 MiB | 6.93 -> 1.49 MiB | 2.67 MiB |
+
+The pass verifies its own output: every embedded image is re-read from the written `.glb` and
+compared against what went in for the material slot and UV set it is bound to, so a texture the
+encoder or the writer dropped fails the build instead of shipping.
+
+## LOD simplification
+
+Off unless `models.simplify` is declared: it is the one stage that removes triangles on purpose,
+so it trades the pass's exact triangle guarantee for a bounded one — joints and clips still
+compared exactly, triangles required to fall but stay above a floor derived from the ratio, and
+the bounding box held to 1% instead of 0.1%.
+
+**How far can a ratio go before the silhouette changes?** Measured, not guessed: a 99,482-triangle
+candelabrum rendered at the condition it is played at — scaled to 3 m tall, camera 3 m from its
+centre, the framework's default 60° vertical fov, 1920x1080, twelve azimuths — with the coverage
+mask compared against the unsimplified baseline by exact Euclidean distance transform.
+
+| ratio | triangles | worst IoU | mean outline shift | p99 | max |
+| --- | --- | --- | --- | --- | --- |
+| 0.75 | 74,608 | 0.998 | 0.03 px | 1.0 px | 1.0 px |
+| 0.50 | 49,738 | 0.997 | 0.05 px | 1.0 px | 1.0 px |
+| 0.35 | 34,818 | 0.995 | 0.11 px | 1.0 px | 1.4 px |
+| **0.25** | **24,870** | **0.992** | **0.17 px** | **1.0 px** | **3.2 px** |
+| 0.15 | 15,126 | 0.985 | 0.35 px | 3.2 px | 16.0 px |
+| 0.10 | 15,152 | 0.984 | 0.36 px | 5.1 px | 21.0 px |
+
+**0.25 is the floor for a hero prop at that distance.** Down to it the outline moves at most one
+pixel over 99% of its length — a quarter of the triangles for a silhouette that cannot be told
+apart. Below it the simplifier starts removing whole features (the 16–21 px maxima are candle
+wicks and tracery openings disappearing), and that is visible without an A/B. A seven-branch bar
+of 42,904 triangles behaves the same way: 0.25 costs 1.0 px, 0.15 costs 4.0 px.
+
+`error` is the quality guard, not the target — it is the largest a vertex may move as a fraction
+of mesh extent (default 0.001, so 3 mm on a 3 m prop). It is what holds candela at 15.2% when the
+config asks for 5%; reaching a true 10% needs `error: 0.005`, and no value looser than that
+reduces further. Because that gap is silent by nature, the compile step prints both numbers:
+
+```
+simplified candela.glb: 99482 -> 15104 triangles (15.2% kept, requested 5.0%) — the error tolerance 0.001 stopped it short
+```
+
+Mobile native targets still refuse compressed assets — Android QuickJS and iOS JSC have no
+WebAssembly and therefore no Basis transcoder — so an Android or iOS build needs
+`assets.models: "none"`, exactly as it already did for compressed geometry.
+
+## Static lightmaps
+
+Opt a project's existing model pipeline into deterministic UV2 generation and offline static-light
+baking through `threenative.config.ts`:
+
+```ts
+assets: {
+  models: { lightmap: { atlasSize: 1024, padding: 4 } },
+}
+```
+
+Games still load the logical `.glb` with `ctx.assets.model()`. The compiler writes standard
+`TEXCOORD_1` data and a content-addressed KTX2; the runtime attaches it through Three.js
+`material.lightMap`. Removing the `lightmap` config removes the pass. Android and iOS builds still
+fail closed on KTX2 because those native hosts do not yet carry a decoder.
+
+| Proof | Result |
+| --- | --- |
+| Deterministic compile | Independent fresh directories produced byte-identical GLB, KTX2, and manifest hashes. |
+| Ordinary consumer | Stock `GLTFLoader` + `KTX2Loader` loaded the compiled binary paths without `@threenative/core`. |
+| Web gameplay | Packed-tarball sandbox required `material.lightMap` before reaching the goal could win. |
+| Negative control | Setting `material.lightMap = null` made `staticLightReady` and the win assertion fail. |
+| Native status | Linux desktop rendered the packed GLB/KTX2 with a clean playtest; Android/iOS still fail closed because their hosts have no KTX2 decoder. |

package/dist/index.d.ts

@@ -0,0 +1,502 @@
+type AssetFindingGrade = "fail" | "ok" | "warn";
+interface IAssetFinding {
+    readonly asset: string;
+    readonly grade: AssetFindingGrade;
+    readonly id: string;
+    readonly message: string;
+    readonly subject?: string;
+    readonly target?: number;
+    readonly value: boolean | number | string;
+}
+interface ITextureStats {
+    readonly alpha: boolean;
+    readonly height: number;
+    readonly powerOfTwo: boolean;
+    readonly width: number;
+}
+interface IModelStats {
+    readonly animationClips: number;
+    readonly colliderPresent: boolean;
+    readonly materials: number;
+    readonly rootMotion: boolean;
+    readonly textures: readonly ITextureStats[];
+    readonly triangles: number;
+}
+interface IAssetHealthEntry {
+    readonly asset: string;
+    readonly kind: AssetKind;
+    readonly license: string;
+    readonly model?: IModelStats;
+    readonly texture?: ITextureStats;
+}
+interface IAssetHealthReport {
+    readonly entries: readonly IAssetHealthEntry[];
+    readonly failed: boolean;
+    readonly findings: readonly IAssetFinding[];
+    readonly summary: Readonly<Record<AssetFindingGrade, number>>;
+}
+interface IAssetHealthInput {
+    readonly data: Buffer;
+    readonly logicalPath: string;
+}
+/**
+ * Measures every compiled asset and grades findings against the declared targets.
+ * A finding only reaches `fail` where a target was declared, so the report stays
+ * informational until a project opts into enforcement.
+ */
+declare function runHealthReport(inputs: readonly IAssetHealthInput[], targets?: IAssetTargets): Promise<IAssetHealthReport>;
+/** The person-readable form printed by the compile step, one line per finding plus a summary. */
+declare function formatHealthReport(report: IAssetHealthReport): readonly string[];
+
+/**
+ * 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
+ * local Node/WASM API directly; it performs no CDN fetch and owns no runtime dependency.
+ */
+interface ILightmapPassOptions {
+    readonly atlasSize: number;
+    readonly padding: number;
+}
+declare function lightmapPass(options: ILightmapPassOptions): IAssetPass;
+
+/**
+ * Cluster-DAG bake options, as they appear under `assets.models.virtual` in `threenative.config.ts`.
+ *
+ * **Absent means the bake runs with defaults**, exactly as `textures` does: a game that imports a
+ * body too dense for the screen should not have to know this key exists to avoid drawing all of it.
+ * `"none"` ships every primitive as authored. There is no runtime flag either way — a minutes-long
+ * bake cannot happen at run time, and a second way to say the same thing is a second thing to get
+ * wrong.
+ */
+interface IModelVirtualOptions {
+    /** Clusters folded together per group, default 4. */
+    readonly groupSize?: number;
+    /** Upper bound on a cluster's triangles, default 128. */
+    readonly maxTriangles?: number;
+    /** Lower bound on a cluster's triangles, default 96. */
+    readonly minTriangles?: number;
+    /**
+     * Primitives below this many triangles are left alone. Default {@link DEFAULT_MIN_SOURCE_TRIANGLES}.
+     *
+     * The payload costs about 3–4x the primitive's compiled bytes whatever its density, so the
+     * default is the density where the cut starts earning them back. Measured on one body at seven
+     * densities, drawing at a distance that frames it across a third of the screen:
+     *
+     * | source triangles | desktop 1080p draws | Pixel 8 (0.44 scale) draws |
+     * | --- | --- | --- |
+     * | 32,768 | 92% | 57% |
+     * | 65,536 | 69% | 27% |
+     * | 131,072 | 35% | 16% |
+     * | 524,288 | 13% | 8% |
+     *
+     * Below 32k the cut is the whole mesh on desktop — payload for nothing. 65,536 is where a phone
+     * already draws a quarter of the triangles and a desktop a bit over two thirds, and it is the
+     * density at which a mesh needs 32-bit indices anyway.
+     */
+    readonly minSourceTriangles?: number;
+    /** Fraction of a group's triangles kept per level, default 0.5. */
+    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
+ * the driver decodes it; meshopt shrinks the other, cheaper half. This stage transcodes each
+ * embedded image to KTX2/Basis and declares `KHR_texture_basisu`, so the GPU stores blocks
+ * instead of RGBA, and caps the resolution so a 4K texture an image model produced cannot
+ * silently eat a phone's whole budget.
+ *
+ * Codec choice follows the declared use of the image, never a guess: a config override on the
+ * glTF slot wins, then normal-map slots (UASTC survives normal data; ETC1S does not), then
+ * alpha in the decoded pixels. Colour space comes from the slot too — `getTextureColorSpace`
+ * knows base colour and emissive are sRGB and that metallic-roughness and normals are data —
+ * so a linear map is never encoded through a perceptual metric.
+ *
+ * The encoder is the same in-process Basis WASM the standalone texture pass uses, so no new
+ * dependency and nothing extra to install. Everything fails closed: an image no decoder reads,
+ * an image whose dimensions are not a whole number of 4x4 blocks, and a texture whose binding
+ * did not survive the round trip all throw naming the model and the image.
+ */
+interface IModelTextureOverride {
+    readonly codec: TextureCodec;
+    /** glTF slot the override applies to, e.g. `normalTexture` or `baseColorTexture`. */
+    readonly slot: string;
+}
+interface IModelTexturesOptions {
+    /**
+     * Longest edge an embedded image may keep, default 2048. Larger images are box-resampled
+     * down preserving aspect ratio; smaller ones are never upscaled.
+     */
+    readonly maxSize?: number;
+    readonly overrides?: readonly IModelTextureOverride[];
+    /** ETC1S encoder quality 1–255, default 150. Ignored for UASTC. */
+    readonly quality?: number;
+}
+/** What the stage did, recorded in the manifest and printed by the size report. */
+interface IEmbeddedTextureSummary {
+    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;
+    /** How many images the resolution cap actually downsampled. */
+    readonly resized: number;
+}
+/** One embedded image as the verification compares it, source against re-read output. */
+interface IModelTextureBinding {
+    readonly height: number;
+    readonly key: string;
+    /** KTX2 mip levels; 1 for a still-uncompressed source image. */
+    readonly levels: number;
+    readonly mimeType: string;
+    readonly slots: readonly string[];
+    readonly texCoords: readonly number[];
+    readonly width: number;
+}
+interface IModelTextureBindings {
+    /** `material -> slot=textureIndex@uvN` for the five core glTF slots, in document order. */
+    readonly materials: readonly string[];
+    readonly textures: readonly IModelTextureBinding[];
+}
+
+/**
+ * Optimizes compiled models: dedup → prune → simplify → reorder → quantize → textures →
+ * meshopt, in that fixed order, each individually switchable in config. Output declares
+ * `KHR_mesh_quantization` and `EXT_meshopt_compression`, plus `KHR_texture_basisu` when it
+ * carried images; the runtime lazily wires three's own MeshoptDecoder and the shared,
+ * support-detected KTX2Loader for exactly those files (see `core/src/assets.ts`).
+ *
+ * Geometry was only ever half of a model. The textures embedded inside a `.glb` are the
+ * expensive half — three 2048x2048 JPEGs are a small file and ~67 MB of VRAM decoded — so
+ * they go through the same Basis encoder the standalone texture pass uses, capped to a
+ * declared maximum resolution (`packages/assets/src/passes/model-textures.ts`).
+ *
+ * The pass verifies its own output before shipping it: the result is re-read and its
+ * triangle, vertex, joint and clip counts and bounding box are compared against the source,
+ * throwing and naming the drift beyond tolerance, and every embedded image is compared for
+ * the material slot and UV set it is bound to. A pipeline that silently loses a mesh — or a
+ * texture — is worse than no pipeline. Counts are taken over scene-reachable content only, so
+ * `prune` dropping DCC leftovers is not drift — losing *referenced* geometry is. Joint indices
+ * and weights are never quantized below what the source declared.
+ *
+ * Draco stays an input, never an output: a Draco `.glb` is decoded here (the codec loads
+ * only when one is seen, so no project pays for it) and re-emitted as Meshopt. Animation
+ * channels are compressed but never resampled — resampling changes timing, which is gameplay.
+ */
+interface IModelPassesOptions {
+    readonly dedup?: boolean;
+    readonly meshopt?: boolean;
+    readonly prune?: boolean;
+    readonly quantize?: boolean;
+    readonly reorder?: boolean;
+}
+interface IModelQuantizeOptions {
+    /** Normal precision in bits, default 8. */
+    readonly normalBits?: number;
+    /** Position precision in bits, default 16. */
+    readonly positionBits?: number;
+    /** UV precision in bits, default 12. */
+    readonly uvBits?: number;
+}
+/**
+ * Mesh simplification for LOD. Off unless declared, because it is the one stage that
+ * deliberately destroys the triangle count the pass otherwise guarantees: with it on, the
+ * self-verify swaps exact triangle equality for a bounded reduction and a wider bounding-box
+ * tolerance, and joints and animation clips are still compared exactly.
+ */
+interface IModelSimplifyOptions {
+    /** Maximum positional error as a fraction of mesh extent, default 0.001. */
+    readonly error?: number;
+    /** Target fraction of the source triangle count, 0–1. */
+    readonly ratio: number;
+}
+interface IModelPassOptions {
+    readonly passes?: IModelPassesOptions;
+    /** 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;
+    /** Embedded-texture compression: options, or `"none"` to ship every image as authored. */
+    readonly textures?: IModelTexturesOptions | "none";
+    /**
+     * Cluster-DAG bake for virtual geometry: options, or `"none"` to ship every primitive as
+     * authored. **Absent means the bake runs with defaults**, on the same terms as `textures` — a
+     * game that imports a body too dense for the screen should not have to know this key exists.
+     * Only primitives at or above `minSourceTriangles` are touched, so an ordinary prop is
+     * byte-identical either way. Minutes on a dense body, so the compile cache keys on it — and on
+     * {@link VIRTUAL_BAKE_VERSION}, because a better partition changes the output and a stale entry
+     * would hide that.
+     */
+    readonly virtual?: IModelVirtualOptions | "none";
+}
+
+/**
+ * What simplification actually delivered. The error tolerance can stop the simplifier well
+ * short of the requested ratio — measured on a 99,482-triangle prop, `ratio: 0.05` with the
+ * default error lands at 15.2% — so both numbers are reported rather than only the one the
+ * config asked for.
+ */
+interface IModelSimplifySummary {
+    readonly achievedRatio: number;
+    readonly error: number;
+    readonly requestedRatio: number;
+    readonly trianglesAfter: number;
+    readonly trianglesBefore: number;
+}
+declare function modelPass(options?: IModelPassOptions): IAssetPass;
+
+type AssetKind = "audio" | "model" | "other" | "texture";
+/** Budgets a project declares for its assets; exceeding one fails the build. */
+interface IAssetTargets {
+    readonly maxMaterials?: number;
+    readonly maxTriangles?: number;
+    readonly maxTextureDimension?: number;
+}
+/**
+ * What a pass produced for one input. A plain `Buffer` return keeps the identity semantics;
+ * the richer shape lets a pass rename the output extension and declare manifest fields for
+ * the input it transformed (the KTX2 pass records `format` and `transcodeTargets`).
+ */
+interface IAssetPassOutput {
+    readonly auxiliaryOutputs?: readonly IAssetAuxiliaryOutput[];
+    readonly buffer: Buffer;
+    /** Extra manifest fields merged into the entry for the input this output came from. */
+    readonly entry?: Readonly<Record<string, unknown>>;
+    /** Replaces the source extension in the content-addressed output name when set. */
+    readonly outputExtension?: string;
+}
+interface IAssetAuxiliaryOutput {
+    readonly buffer: Buffer;
+    readonly extension: string;
+    /** Manifest array receiving this output, for example `lightmaps`. */
+    readonly manifestField: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /** 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;
+    readonly name: string;
+    /**
+     * 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
+     * override's codec) leaves the pass name and input hash untouched and the stale output is
+     * re-served forever. `undefined` for passes without options.
+     */
+    readonly configuration?: Readonly<Record<string, unknown>>;
+    apply(input: Buffer, logicalPath: string): Buffer | IAssetPassOutput | Promise<Buffer | IAssetPassOutput>;
+}
+interface IAssetSourceConfig {
+    /**
+     * Model optimization: an object of options, or the string `"none"` to ship every model
+     * exactly as committed. Absent means optimization runs with defaults.
+     */
+    readonly models?: IModelsConfig | "none";
+    readonly output?: string;
+    readonly source?: string;
+    readonly targets?: IAssetTargets;
+    /**
+     * Texture compression: an object of options, or the string `"none"` to ship every texture
+     * exactly as committed. Absent means compression runs with defaults.
+     */
+    readonly textures?: ITexturesConfig | "none";
+}
+interface IModelsConfig {
+    /** Generate standard TEXCOORD_1 lightmap UVs. Absent means no lightmap pass. */
+    readonly lightmap?: ILightmapPassOptions;
+    readonly passes?: IModelPassesOptions;
+    readonly quantize?: IModelQuantizeOptions;
+    /** LOD simplification. Absent means none: it is the one lossy stage, and it is opt-in. */
+    readonly simplify?: IModelSimplifyOptions;
+    /**
+     * Compression of the images embedded in a model, or the string `"none"` to ship them
+     * exactly as authored. Absent means compression runs with defaults.
+     */
+    readonly textures?: IModelTexturesOptions | "none";
+    /**
+     * Cluster-DAG bake for virtual geometry, or `"none"` to ship every primitive as authored.
+     * Absent means the bake runs with defaults, which clusters any primitive of 65,536 triangles
+     * or more and leaves everything below it byte-identical.
+     */
+    readonly virtual?: IModelVirtualOptions | "none";
+}
+interface ITexturesConfig {
+    readonly overrides?: readonly ITextureOverride[];
+    readonly quality?: number;
+}
+interface IAssetCompileOptions {
+    readonly config?: IAssetSourceConfig;
+    readonly cwd?: string;
+    /** Includes the machine-readable health report on the result. */
+    readonly health?: boolean;
+    readonly output?: string;
+    /**
+     * Replaces the built-in pass registry when provided; left undefined, the built-in
+     * registry (the KTX2 texture pass) runs unless `config.textures` is `"none"`.
+     */
+    readonly passes?: readonly IAssetPass[];
+    readonly source?: string;
+    /** Overrides resolution of three's Basis transcoder for the copy into the output root. */
+    readonly transcoder?: IBasisTranscoder;
+}
+interface IBasisTranscoder {
+    readonly javascriptPath: string;
+    readonly wasmPath: string;
+}
+interface IAssetCompileResult {
+    readonly report?: IAssetHealthReport;
+    readonly skipped: number;
+    readonly written: 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
+ * runtime inside the KTX2 loader.
+ */
+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.
+ */
+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[];
+
+interface IPngInfo {
+    readonly width: number;
+    readonly height: number;
+    readonly hasAlpha: boolean;
+}
+/** Parses the PNG structure needed by config validation and asset health reporting. */
+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".
+ *
+ * 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
+ * watcher exists only inside a Vite process and would drag in a peer dependency, and chokidar
+ * adds a package outright. Recursive `fs.watch` covers Windows, macOS and Linux on the Node
+ * versions Vite already requires, keeps `watchAssets` usable outside a dev server, and leaves
+ * the template plugin a handful of lines that only start and stop this watcher.
+ */
+interface IAssetWatchSummary {
+    readonly compiled: readonly string[];
+    readonly failed: readonly string[];
+}
+interface IAssetWatchOptions extends IAssetCompileOptions {
+    /** Quiet window that coalesces a burst of saves into one recompile. Default 100 ms. */
+    readonly debounceMs?: number;
+    /** Called once per settled burst with the logical paths that compiled and that failed. */
+    readonly onChange?: (summary: IAssetWatchSummary) => void;
+}
+interface IAssetWatchHandle {
+    /**
+     * Settles once the initial full compile finished. An initial failure is logged to stderr
+     * instead of thrown — a broken asset must not keep a dev server from booting, fixing the file
+     * triggers a healing burst, and the build lane still fails closed through `compileAssets`.
+     */
+    readonly ready: Promise<void>;
+    /** Stops watching and cancels any pending debounced burst. Idempotent. */
+    close(): void;
+}
+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 };