@developerz.ai/ts23d 0.1.0 → 0.2.0

package/recipes/orc_head/README.md

@@ -1,34 +1,41 @@
 # Orc warrior bust — original stylised design
 
 ## Identity
-A brutish orc warlord, read from the 3/4 view by: **massive underbitten jaw with lower tusks**
-curving out past the upper lip, **heavy scowling brow** over small deep-set ember eyes, **flat
-broad nose**, **pointed ears** swept back, a **top-knot** on a low skull, and **spiked layered
-pauldrons + fur mantle** on huge trapezius.
+A brutish orc warlord, read from the 3/4 view by: a **hunched brute silhouette** (trapezius sloping
+from behind the ears to the shoulders, the neck nearly as wide as the head), a **massive
+underbitten jaw** with **lower tusks rising outside the upper lip**, a **heavy brow shelf** (a
+flattened bar with a glabella knot, scowling down at the centre) shadowing **small deep-set ember
+eyes**, a **flat broad nose**, **cheekbone ridges** running back to swept **pointed ears**, a **bound
+warrior's knot** falling to the nape, war paint, **pectorals and deltoids** on the bare chest, and
+**spiked plate pauldrons** (a domed cap and a shingled lame, hollow shells with worn bright rims)
+over a **fur mantle** — cut as a collectible bust on a turned plinth.
 
 ## Design spec (head units: 1 = chin to crown = 0.30 m, ≈ 1.3 × human)
 | Feature | Value (units) | Metres | Note |
 |---|---|---|---|
 | chin → crown | 1.00 | 0.300 | the `height` param |
-| overall bust L × W × H | — | 0.338 × 0.742 × 0.583 | `real`, ±5 % |
-| cranium width / depth / above eye line | 0.70 / 0.80 / 0.34 | 0.21 / 0.24 / 0.10 | low, sloped dome |
+| overall bust L × W × H | — | 0.405 × 0.660 × 0.587 | `real`, ±5 %; length includes the knot's tail |
+| cranium width / depth / above eye line | 0.70 / 0.74 / 0.31 | 0.21 / 0.22 / 0.09 | low, sloped dome: the face is the mass |
 | eye line | 0.56 | — | higher than human: the jaw is the mass |
-| eyeball radius / spacing | 0.050 / 0.155 | 0.015 / pupils 0.093 apart | `measures` gate, ±2 % |
-| jaw half-width at angle | 0.37 | 0.111 | human 0.22 |
-| muzzle (prognathism) / underbite / chin drop | 0.10 / 0.07 / 0.10 | | |
-| tusks length / base radius | 0.27 / 0.05 | 0.081 / 0.015 | 3 cone segments, flared |
-| neck radius | 0.32 | 0.096 | |
-| shoulders (half-span) | 1.05 | 0.315 | arms cut flat (classic bust) |
+| eyeball radius / spacing | 0.054 / 0.155 | 0.016 / pupils 0.093 apart | `measures` gate, ±2 % |
+| brow ridge / overhang / scowl | 0.075 / 0.06 / 0.04 | | a shelf, not two bumps |
+| jaw half-width at angle / chin | 0.40 / 1.3 | 0.120 | human 0.22; square rounded-box chin |
+| muzzle (prognathism) / underbite / chin drop | 0.10 / 0.10 / 0.10 | | lower lip thickens with the underbite |
+| tusks length / base radius | 0.22 / 0.055 | 0.066 / 0.017 | 3 cone segments from the lower lip, flared |
+| neck radius | 0.38 | 0.114 | |
+| shoulders (half-span) / mass | 1.00 / 1 | 0.300 | `bust.mass` 1 = brute: torso lifted (hunch), thick traps |
+| plinth | 0.17 + hunch | ≈ 0.08 | disc + socle; cut faces painted plinth stone |
 
 ## Palette (sRGB)
 | Role | Hex |
 |---|---|
-| skin / shade / lips | `#5f8b3a` / `#3c5c24` / `#4f6f30` |
+| skin / shade / lips | `#5c8034` / `#33501e` / `#4f6f30` (painted tone: crevices darker, tops warmer) |
 | eyes: sclera / iris (+ emissive glow `#ff7a1a` × 2.5) | `#8a5a1a` / `#ffb030` |
 | tusks + bone spikes | `#e2d6b0` |
-| hair (top-knot) / fur mantle (strands alternate ×0.7) | `#1c1714` / `#5e4a34` |
+| hair (warrior's knot) / fur mantle (strands alternate ×0.72) | `#231a14` / `#5e4a34` |
 | war paint (cheek claw marks, crest stripe, chin stripes) | `#8a1c12` |
-| pauldron iron (lames ×1/0.88/0.76, rims ×0.55, rivets ×1.4) / leather baldric | `#6e6a62` / `#5a3a22` |
+| pauldron iron (cap ×1, lame ×0.85, worn rims ×1.3, rivets ×1.35, crest ×0.75) / leather baldric | `#55524d` / `#5a3a22` |
+| plinth / cut faces | `#6f6c6c` (linear 0.16, 0.15, 0.15) / ×1.3 |
 
 ## Parts the engine needs
 | Part | Pivot | Motion |
@@ -43,8 +50,10 @@ along the lips, the marionette lines and under the chin. Its cut faces are paint
 when it opens; it laps 0.75 cells over the head so no gap shows.
 
 ## LODs
-Sculpt cell = 2 % / 4.5 % / 14 % of head height. LOD0/1 bake vertex AO across all parts (16/10 rays); LOD2 drops
-warts, wiry tufts and the AO bake, and floors ear thickness at 0.7 cells so ears stay attached.
+Sculpt cell = 2 % / 4.5 % / 14 % of head height (bust 1.6 ×). LOD0/1 bake vertex AO across all
+parts (16/10 rays); every LOD carries the painted tone (cavity, warm top, cool under). LOD1/2 drop
+the teeth and tongue; LOD2 drops warts, wiry tufts and the AO bake, floors ear/tusk/nose radii at
+about a cell, makes the pauldron plates solid and the plinth one drum so nothing opens or floats.
 
 ## References (stylised anatomy, not likeness)
 | Topic | Link | Used for |
@@ -52,7 +61,8 @@ warts, wiry tufts and the AO bake, and floors ear thickness at 0.7 cells so ears
 | Loomis head: eye line at half height, brow/nose/chin thirds | https://finearttutorials.com/guide/loomis-method/ | human eye line 0.5, nose base 0.32, mouth 0.22 |
 | Proportions of the head (ears between brow and nose base, head ≈ 5 eyes wide) | https://artyfactory.com/portraits/pencil-portraits/proportions-of-a-head.html | ear placement, eye size vs head width |
 | Primary → secondary → tertiary forms (block brow/cheek/jaw first, then cut lids and folds) | https://www.creativebloq.com/how-to/how-to-sculpt-and-pose-a-cartoon-head-in-zbrush | the edit order in `head-face.ts` |
-| Orc: widen head and jawline to break human proportion | https://www.creativebloq.com/3d/how-create-orc-zbrush-61411834 | orc jaw width 0.37 vs human 0.22 |
+| Orc: widen head and jawline to break human proportion; sculpt bony forms (cheekbones) early | https://www.creativebloq.com/3d/how-create-orc-zbrush-61411834 | orc jaw width 0.40 vs human 0.22, zygomatic ridge |
+| Stylised bust method: primary → secondary → tertiary shapes | https://cgzen.gumroad.com/l/stylized-bust | torso masses before gear |
 | Stylised orc head study (silhouette, form language) | https://blenderartists.org/t/orc-head-study-stylized-characters/1655542 | massing check |
 | Stylised hair: large clumps first, hairline → crown, one primary flow direction | https://gamesartist.co.uk/curly-hair-ls/ · https://www.cgchannel.com/2023/03/tutorial-creating-stylized-hairstyles-using-zbrush | `swept` locks in head-hair.ts |
 | Dreams (Media Molecule, Evans, SIGGRAPH 2015): sculptures as ordered SDF edits + smooth-min | https://www.mediamolecule.com/blog/article/siggraph_2015 · slides https://advances.realtimerendering.com/s2015/AlexEvans_SIGGRAPH-2015-sml.pdf | the whole approach |
@@ -62,5 +72,7 @@ hand-painted stylised fantasy" is the idiom (exaggerated primary forms, generous
 vertex colour with baked AO), not a specific source.
 
 ## Known gaps
-Pauldron lames still read soft (no hammered dents or edge wear); fur strands are cones, not
-noise-broken clumps; no skin pores/wrinkle noise; the top-knot is a plain bun.
+Pauldron plates are smooth shells (no hammered dents or scratches); fur strands are cones, not
+noise-broken clumps; no skin pores or wrinkle noise; the jaw part's seam still shows as a faint
+line round the chin up close; the bust's U-cut leaves the belly reading slightly pear-shaped from
+dead front.

package/recipes/orc_head/orc_head.ts

@@ -1,7 +1,9 @@
 // Stylised orc warrior bust — an original design in the chunky hand-painted fantasy idiom: massive
-// underbitten jaw with lower tusks, heavy scowling brow over small ember eyes, flat broad nose,
-// pointed swept ears, top-knot, war-paint stripes, layered spiked pauldrons and a fur mantle. The
-// `head` kind sculpts it (race preset `orc`, chin to crown 0.30 m); this file is the spec.
+// underbitten jaw with lower tusks rising outside the upper lip, a heavy brow shelf over small ember
+// eyes, flat broad nose, swept ears, a bound warrior's knot, war paint; a hunched brute torso
+// (trapezius from ear to shoulder, pectorals, deltoids) under spiked plate pauldrons and a fur
+// mantle, cut as a collectible bust on a turned plinth. The `head` kind sculpts it (race preset
+// `orc`, chin to crown 0.30 m); this file is the spec.
 // Design dossier: recipes/orc_head/README.md.
 
 import { defineAsset, head, hex } from '@developerz.ai/ts23d';
@@ -10,15 +12,15 @@ export const orc_head = defineAsset({
   name: 'orc_head',
   kind: 'character',
   description:
-    'Stylised orc warrior bust: underbite and lower tusks, heavy brow, ember eyes, top-knot, spiked pauldrons, fur mantle',
+    'Stylised orc warrior bust on a plinth: underbite and lower tusks, heavy brow, ember eyes, warrior knot, hunched trapezius, spiked plate pauldrons, fur mantle',
   tags: ['character', 'fantasy', 'orc', 'bust', 'sculpt'],
   license: 'CC0-1.0',
   sources: ['recipes/orc_head/README.md (design dossier: proportions, palette, references)'],
   // Design spec, not a real-world one: overall bust size and eye spacing from the dossier.
   real: {
-    length: 0.338,
-    width: 0.742,
-    height: 0.583,
+    length: 0.405,
+    width: 0.66,
+    height: 0.587,
     measures: [
       {
         label: 'eye spacing (pupil to pupil)',

package/src/cli/args.ts

@@ -17,6 +17,12 @@ export interface Args {
   readonly sheetSize: 512 | 1024 | 2048;
   /** Which detail levels to build: all three by default, or e.g. only the hero mesh. */
   readonly lods: readonly (0 | 1 | 2)[];
+  /**
+   * How LODs land on disk: `split` lodN.glb per level · `single` one <asset>.glb with MSFT_lod
+   * alternates · `both` (default): split files import everywhere, the single file is for
+   * MSFT_lod-aware loaders and one-file pipelines.
+   */
+  readonly lodFiles: 'split' | 'single' | 'both';
   /** Beauty-render camera and size (hero, review, and build's hero.png); unset = defaults. */
   readonly render: {
     readonly width?: number;
@@ -42,8 +48,11 @@ flags:
                   front, default -35 (front-left 3/4) · --el <deg> elevation, default 18 · --fov <deg> 30
   --sheet <mode>  external (default): one shared trim_sheet_{albedo,normal,orm}.png in <out>/,
                   referenced by every GLB · embed: self-contained GLBs · none: vertex colour only
-  --sheet-size n  512 | 1024 (default) | 2048
+  --sheet-size n  512 | 1024 | 2048 (default)
   --lods <list>   which detail levels to build: 0,1,2 (default) · 0 = hero only · 0,2 = near + far
+  --lods <mode>   how they are written: both (default) = lod0/1/2.glb + <asset>.glb · split = lodN.glb
+                  only · single = <asset>.glb only (LOD0 in the scene, LOD1/2 as MSFT_lod alternates
+                  with screen-coverage switch hints; viewers without MSFT_lod show LOD0 only)
   --json          machine-readable output`;
 
 export function parseArgs(argv: readonly string[]): Args {
@@ -53,8 +62,9 @@ export function parseArgs(argv: readonly string[]): Args {
   let animations = true;
   let shot = true;
   let sheet: Args['sheet'] = 'external';
-  let sheetSize: Args['sheetSize'] = 1024;
+  let sheetSize: Args['sheetSize'] = 2048;
   let lods: Args['lods'] = [0, 1, 2];
+  let lodFiles: Args['lodFiles'] = 'both';
   const render: {
     width?: number;
     height?: number;
@@ -81,6 +91,8 @@ export function parseArgs(argv: readonly string[]): Args {
     else if (a === '--sheet') {
       const m = argv[++i];
       sheet = m === 'embed' || m === 'none' ? m : 'external';
+    } else if (a === '--lods' && /^(split|single|both)$/.test(argv[i + 1] ?? '')) {
+      lodFiles = argv[++i] as Args['lodFiles'];
     } else if (a === '--lods') {
       const picked = (argv[++i] ?? '')
         .split(',')
@@ -89,7 +101,7 @@ export function parseArgs(argv: readonly string[]): Args {
       lods = picked.length ? [...new Set(picked)].sort() : lods;
     } else if (a === '--sheet-size') {
       const n = Number(argv[++i]);
-      sheetSize = n === 512 || n === 2048 ? n : 1024;
+      sheetSize = n === 512 || n === 1024 ? n : 2048;
     } else if (a === '--size') Object.assign(render, parseSize(argv[++i] ?? ''));
     else if (a === '--az') render.azDeg = num(a, argv[++i]);
     else if (a === '--el') render.elDeg = num(a, argv[++i]);
@@ -107,6 +119,7 @@ export function parseArgs(argv: readonly string[]): Args {
     sheet,
     sheetSize,
     lods,
+    lodFiles,
     render,
   };
 }

package/src/cli/manifest.ts

@@ -13,11 +13,15 @@ export interface AssetManifest {
   readonly tags: readonly string[];
   readonly files: {
     readonly lods: readonly string[];
+    /** All built LODs in one GLB (MSFT_lod), when `--lods single|both`. */
+    readonly single?: string;
     readonly hero?: string;
     readonly sheet?: string;
     readonly thumb?: string;
   };
   readonly triangles: readonly number[];
+  /** MSFT_screencoverage written into `files.single`: where each LOD hands over (last = cull). */
+  readonly lodCoverage?: readonly number[];
   readonly drawCalls: readonly number[];
   readonly pivots: readonly { name: string; parent: string | null; motion?: string }[];
   readonly emitters: readonly { name: string; kind: string; when: string }[];
@@ -42,6 +46,7 @@ export function manifestOf(
   lods: readonly CompiledAsset[],
   files: AssetManifest['files'],
   findings: readonly Finding[],
+  lodCoverage?: readonly number[],
 ): AssetManifest {
   const top = lods[0];
   const merged = top ? mergeToPivots(top) : null;
@@ -52,6 +57,7 @@ export function manifestOf(
     tags: asset.tags ?? [],
     files,
     triangles: lods.map(tris),
+    ...(lodCoverage?.length ? { lodCoverage } : {}),
     // One draw per merged mesh, glowing parts in their own emissive layer (as the GLB writes them).
     drawCalls: lods.map(
       (l) =>

package/src/cli/run.ts

@@ -1,19 +1,33 @@
 // Command dispatch for `t3d`. Pure function of argv → exit code, so it is testable in-process.
 // Output layout, one folder per asset (stable paths agents and pipelines can rely on):
-//   <out>/<asset>/lod0.glb lod1.glb lod2.glb hero.png thumb.png sheet.png manifest.json
+//   <out>/<asset>/lod0.glb lod1.glb lod2.glb <asset>.glb (all LODs, MSFT_lod) hero.png thumb.png
+//   sheet.png manifest.json
 //   <out>/<asset>/review/… (t3d review) · <out>/index.json — every asset built, with its QA verdict
 
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { type Asset, compile, type Lod, Ts23dError } from '../core/index.ts';
-import { SHEET_MAPS, type SheetBinding, sheetFileName, sheetPngs, toGlb } from '../export/index.ts';
-import { DEFAULT_SHEET, type PaintedSheet, paintTrimSheet } from '../material/index.ts';
+import {
+  exportLodGlb,
+  SHEET_MAPS,
+  type SheetBinding,
+  sheetFileName,
+  sheetPngs,
+  toGlb,
+} from '../export/index.ts';
+import {
+  DEFAULT_SHEET,
+  type PaintedSheet,
+  paintTrimSheet,
+  provideTextures,
+} from '../material/index.ts';
 import { type Finding, runQa } from '../qa/index.ts';
 import { beauty, contactSheet, thumbnail } from '../render/index.ts';
 import { type Args, HELP, parseArgs } from './args.ts';
 import { loadAssets } from './load.ts';
 import { type AssetManifest, manifestOf } from './manifest.ts';
 import { heroOne, printRendered, type RenderResult, reviewOne } from './render-cmds.ts';
+import { loadTextureCache } from './texture-cache.ts';
 
 async function buildOne(
   asset: Asset,
@@ -29,16 +43,22 @@ async function buildOne(
     runQa(a).map((f) => ({ ...f, message: `LOD${a.lod}: ${f.message}` })),
   );
   const glbs: string[] = [];
-  if (args.cmd === 'build') {
+  const glbOptions = { animations: args.animations, ...(texture ? { sheet: texture } : {}) };
+  let single: string | undefined;
+  let coverage: readonly number[] = [];
+  if (args.cmd === 'build' && args.lodFiles !== 'single') {
     for (const a of lods) {
       const path = join(dir, `lod${a.lod}.glb`);
-      await Bun.write(
-        path,
-        toGlb(a, { animations: args.animations, ...(texture ? { sheet: texture } : {}) }),
-      );
+      await Bun.write(path, toGlb(a, glbOptions));
       glbs.push(path);
     }
   }
+  if (args.cmd === 'build' && args.lodFiles !== 'split') {
+    single = join(dir, `${asset.name}.glb`);
+    const packed = exportLodGlb(lods, glbOptions);
+    coverage = packed.coverage;
+    await Bun.write(single, packed.glb);
+  }
   let sheet: string | undefined;
   let thumb: string | undefined;
   let hero: string | undefined;
@@ -61,11 +81,13 @@ async function buildOne(
     lods,
     {
       lods: glbs,
+      ...(single ? { single } : {}),
       ...(hero ? { hero } : {}),
       ...(sheet ? { sheet } : {}),
       ...(thumb ? { thumb } : {}),
     },
     findings,
+    coverage,
   );
   await Bun.write(join(dir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
   return manifest;
@@ -77,6 +99,7 @@ function print(m: AssetManifest): void {
   );
   for (const f of [
     ...m.files.lods,
+    ...(m.files.single ? [m.files.single] : []),
     ...(m.files.hero ? [m.files.hero] : []),
     ...(m.files.sheet ? [m.files.sheet] : []),
   ])
@@ -108,11 +131,12 @@ export async function run(argv: readonly string[]): Promise<number> {
   }
   const built: AssetManifest[] = [];
   const rendered: RenderResult[] = [];
-  // Paint the trim sheet once per run (~1 s at 1024²). External mode writes it once into <out>/
+  // Paint the trim sheet once per run (~4 s at 2048²). External mode writes it once into <out>/
   // and every GLB in <out>/<asset>/ references ../trim_sheet_*.png — one texture set for all.
   // The beauty renders sample the same painted sheet.
   const renders = args.cmd === 'hero' || args.cmd === 'review';
   const wantsSheet = (args.cmd === 'build' && args.sheet !== 'none') || renders;
+  if (wantsSheet) provideTextures(await loadTextureCache());
   const painted = wantsSheet
     ? paintTrimSheet({ ...DEFAULT_SHEET, size: args.sheetSize })
     : undefined;

package/src/cli/texture-cache.ts

@@ -0,0 +1,24 @@
+// The local CC0 texture cache (`bun run textures` fills it): every file re-verified by its sha256
+// name, handed to `provideTextures` before painting. Missing files are fine here; painting a
+// material that needs one throws T3D_TEXTURE_MISSING with the fetch command.
+
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { TextureCache } from '../material/index.ts';
+
+export const TEXTURE_CACHE = join('node_modules', '.cache', 'ts23d', 'textures');
+
+const sha256 = (b: Uint8Array): string => new Bun.CryptoHasher('sha256').update(b).digest('hex');
+
+/** Every cached map whose bytes still match its sha256 name. */
+export async function loadTextureCache(dir = TEXTURE_CACHE): Promise<TextureCache> {
+  const out = new Map<string, Uint8Array>();
+  const names = await readdir(dir).catch(() => [] as string[]);
+  for (const name of names.sort()) {
+    const m = /^([0-9a-f]{64})\.png$/.exec(name);
+    if (!m?.[1]) continue;
+    const bytes = new Uint8Array(await Bun.file(join(dir, name)).arrayBuffer());
+    if (sha256(bytes) === m[1]) out.set(m[1], bytes);
+  }
+  return out;
+}

package/src/core/asset.ts

@@ -113,6 +113,7 @@ export function compile(asset: Asset, options: { lod?: Lod; seed?: number } = {}
     parts: [...parts.values()],
     ...metaOf(asset),
     ...(asset.glow?.length ? { glow: asset.glow } : {}),
+    ...(asset.lodCoverage ? { lodCoverage: asset.lodCoverage } : {}),
   };
 }
 

package/src/core/definition.ts

@@ -128,6 +128,12 @@ export interface AssetDefinition {
   readonly creators?: readonly string[];
   /** Emissive part sets; `t3d build` writes them as glowing materials. */
   readonly glow?: readonly Glow[];
+  /**
+   * View-distance hints for the single-file GLB (MSFT_lod `MSFT_screencoverage`): the screen-height
+   * fraction below which LOD0 → LOD1, LOD1 → LOD2, and LOD2 is culled (0 = never). Strictly
+   * descending, 1 > a > b > c >= 0. Omitted: derived from the triangle counts and size.
+   */
+  readonly lodCoverage?: readonly [number, number, number];
   build(ctx: BuildContext): void;
 }
 
@@ -146,4 +152,5 @@ export interface CompiledAsset {
   /** Provenance carried from the definition (absent when the recipe declares none). */
   readonly meta?: AssetMeta;
   readonly glow?: readonly Glow[];
+  readonly lodCoverage?: readonly [number, number, number];
 }

package/src/core/errors.ts

@@ -13,7 +13,12 @@ export type ErrorCode =
   | 'T3D_RENDER_OPTIONS'
   | 'T3D_AMBIENT_RANDOM'
   | 'T3D_RELEASE'
-  | 'T3D_BENCH';
+  | 'T3D_BENCH'
+  | 'T3D_MATERIAL_INVALID'
+  | 'T3D_MATERIAL_UNKNOWN'
+  | 'T3D_MATERIAL_CONFLICT'
+  | 'T3D_SHEET_FULL'
+  | 'T3D_TEXTURE_MISSING';
 
 export interface ErrorDetails {
   readonly cause: string;

package/src/export/credits.ts

@@ -0,0 +1,25 @@
+// Texture credits into the GLB: when an asset samples an image strip (a CC0 texture set registered
+// with defineMaterial), its credit line joins the XMP packet's `dc:contributor`. Assets that use
+// only procedural strips get no change, so their bytes stay identical.
+
+import type { CompiledAsset } from '../core/index.ts';
+import { stripCredits } from '../material/index.ts';
+import type { GlbMeta } from './metadata.ts';
+
+export function creditsOf(asset: CompiledAsset): string[] {
+  const out = new Set<string>();
+  for (const p of asset.parts) {
+    const uv = p.mesh?.uvs;
+    if (!uv) continue;
+    const v = new Float32Array(uv.length >> 1);
+    for (let i = 0; i < v.length; i++) v[i] = uv[i * 2 + 1] ?? 0;
+    for (const c of stripCredits(v)) out.add(c);
+  }
+  return [...out].sort();
+}
+
+export function withCredits(asset: CompiledAsset, meta: GlbMeta | undefined): GlbMeta | undefined {
+  const credits = creditsOf(asset);
+  if (!credits.length) return meta;
+  return { ...meta, credits: [...(meta?.credits ?? []), ...credits] };
+}

package/src/export/glb-options.ts

@@ -0,0 +1,53 @@
+// Options and results of the GLB writer (glb.ts): what goes into the file and what comes back.
+
+import type { OptimizeOptions } from '../passes/index.ts';
+import type { LodCoverage } from './lod-coverage.ts';
+import type { GlowRule } from './materials.ts';
+import type { GlbMeta } from './metadata.ts';
+import type { ExportReport } from './optimize-parts.ts';
+import type { SheetBinding } from './textures.ts';
+
+export interface GlbOptions {
+  /** Keep every part as its own node (debugging, per-part picking). Default merges to pivots. */
+  readonly keepParts?: boolean;
+  /**
+   * Bake each part's `motion` into a looping `run` clip. Off by default: glTF has no autoplay
+   * flag and most viewers play the first clip, while engines usually drive the named pivots
+   * from game code. Turn it on for previews, cutscenes and ambient props.
+   */
+  readonly animations?: boolean;
+  /**
+   * Bind the painted trim sheet to every material: a `PaintedSheet` embeds the three PNGs (one
+   * self-contained file); `{ external: true, prefix? }` references shared `trim_sheet_*.png` by
+   * URI. Omitted: no textures, byte-identical to the untextured output.
+   */
+  readonly sheet?: SheetBinding;
+  /**
+   * Weld + vertex-cache + vertex-fetch optimisation per primitive (passes/optimize). On by
+   * default; `false` writes the meshes exactly as compiled (debugging the IR).
+   */
+  readonly optimize?: boolean | OptimizeOptions;
+  /** Parts that emit light (lamp lenses, lit windows): one emissive material per rule. */
+  readonly glow?: readonly GlowRule[];
+  /** Provenance: asset.copyright + an XMP packet (title, creators, licence, sources). */
+  readonly meta?: GlbMeta;
+  /**
+   * Single-file LODs only: [LOD0→LOD1, LOD1→LOD2, cull] screen-height fractions written as
+   * `MSFT_screencoverage`. Default: the asset's `lodCoverage`, else derived (lod-coverage.ts).
+   */
+  readonly lodCoverage?: LodCoverage;
+}
+
+/** The GLB bytes plus what the optimiser did (vertex counts, ACMR before/after, per part). */
+export interface GlbResult {
+  readonly glb: Uint8Array;
+  readonly report: ExportReport;
+}
+
+/** One GLB holding several LODs, plus one optimiser report per LOD (same order as the input). */
+export interface LodGlbResult {
+  readonly glb: Uint8Array;
+  readonly reports: readonly ExportReport[];
+  /** The `MSFT_screencoverage` written (empty for a single LOD). */
+  readonly coverage: readonly number[];
+}