@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/cli/bin.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+// `t3d` — compile TypeScript recipes to GLB, gate them, and shoot contact sheets. `t3d help`
+// prints the commands; src/cli/args.ts holds the flags, src/cli/run.ts the output layout.
+
+import { run } from './run.ts';
+
+process.exitCode = await run(process.argv.slice(2));

package/src/cli/load.ts

@@ -0,0 +1,17 @@
+// Load a recipe module and collect every exported Asset. Recipes are plain TS modules: the CLI,
+// the site and tests all import them the same way.
+
+import { resolve } from 'node:path';
+import { type Asset, isAsset, Ts23dError } from '../core/index.ts';
+
+export async function loadAssets(file: string): Promise<Asset[]> {
+  const mod: Record<string, unknown> = await import(resolve(file));
+  const assets = Object.values(mod).filter(isAsset);
+  if (assets.length === 0) {
+    throw new Ts23dError('T3D_NO_ASSET_EXPORT', {
+      cause: `${file} exports no asset`,
+      fix: 'export const my_thing = defineAsset({ … }) — named export, no default',
+    });
+  }
+  return assets;
+}

package/src/cli/manifest.ts

@@ -0,0 +1,95 @@
+// manifest.json per asset: what an engine pipeline or an agent needs without opening a GLB —
+// files, triangles per LOD, pivots (the names game code binds to), emitters, surfaces, QA,
+// measures with their measured values, sources.
+
+import type { Asset, CompiledAsset } from '../core/index.ts';
+import { mergeToPivots } from '../export/index.ts';
+import { type Finding, measure } from '../qa/index.ts';
+
+export interface AssetManifest {
+  readonly name: string;
+  readonly kind: string;
+  readonly description?: string;
+  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 }[];
+  readonly sockets: readonly { name: string; kind: string; parent: string | null }[];
+  readonly surfaces: readonly string[];
+  readonly real?: { length: number; width: number; height: number };
+  readonly measures: readonly {
+    label: string;
+    spec: number;
+    measured: number | null;
+    source?: string;
+  }[];
+  readonly sources: readonly string[];
+  readonly qa: { readonly pass: boolean; readonly findings: readonly Finding[] };
+}
+
+const tris = (a: CompiledAsset): number =>
+  a.parts.reduce((s, p) => s + (p.mesh ? p.mesh.indices.length / 3 : 0), 0);
+
+export function manifestOf(
+  asset: Asset,
+  lods: readonly CompiledAsset[],
+  files: AssetManifest['files'],
+  findings: readonly Finding[],
+  lodCoverage?: readonly number[],
+): AssetManifest {
+  const top = lods[0];
+  const merged = top ? mergeToPivots(top) : null;
+  return {
+    name: asset.name,
+    kind: asset.kind,
+    ...(asset.description ? { description: asset.description } : {}),
+    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) =>
+        mergeToPivots(
+          l,
+          (l.glow ?? []).map((g) => g.parts),
+        ).parts.filter((p) => p.mesh).length,
+    ),
+    pivots: (merged?.parts ?? [])
+      .filter((p) => !p.emitter && !p.socket)
+      .map((p) => ({
+        name: p.name,
+        parent: p.parent,
+        ...(p.motion ? { motion: p.motion.kind } : {}),
+      })),
+    emitters: (top?.parts ?? []).flatMap((p) =>
+      p.emitter ? [{ name: p.name, kind: p.emitter.kind, when: p.emitter.when ?? 'always' }] : [],
+    ),
+    sockets: (top?.parts ?? []).flatMap((p) =>
+      p.socket ? [{ name: p.name, kind: p.socket.kind, parent: p.parent }] : [],
+    ),
+    surfaces: [...new Set((top?.parts ?? []).map((p) => p.surface ?? 'opaque'))].sort(),
+    ...(asset.real
+      ? { real: { length: asset.real.length, width: asset.real.width, height: asset.real.height } }
+      : {}),
+    measures: (asset.real?.measures ?? []).map((m) => ({
+      label: m.label,
+      spec: m.value,
+      measured: top ? measure(top, m) : null,
+      ...(m.source ? { source: m.source } : {}),
+    })),
+    sources: asset.sources ?? [],
+    qa: { pass: findings.length === 0, findings },
+  };
+}

package/src/cli/render-cmds.ts

@@ -0,0 +1,66 @@
+// `t3d hero` and `t3d review`: beauty renders and the AI review pack, one folder per asset.
+//   <out>/<asset>/hero.png
+//   <out>/<asset>/review/{hero,sheet,detail_1,detail_2,lods}.png review.md review.json
+
+import { mkdir } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { type Asset, compile } from '../core/index.ts';
+import type { PaintedSheet } from '../material/index.ts';
+import { beauty, type ReviewWarning, reviewPack } from '../render/index.ts';
+import type { Args } from './args.ts';
+
+export interface RenderResult {
+  readonly name: string;
+  readonly files: readonly string[];
+  readonly warnings: readonly ReviewWarning[];
+}
+
+export async function heroOne(
+  asset: Asset,
+  args: Args,
+  sheet: PaintedSheet,
+): Promise<RenderResult> {
+  const dir = join(args.out, asset.name);
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, 'hero.png');
+  await Bun.write(path, beauty(compile(asset, { lod: 0 }), { ...args.render, sheet }));
+  return { name: asset.name, files: [path], warnings: [] };
+}
+
+/** The dossier: README.md next to the recipe (recipes/<name>/), else a legacy refs/<name>.md. */
+async function refsFor(name: string, recipe: string): Promise<string | undefined> {
+  for (const p of [
+    join(dirname(resolve(recipe)), 'README.md'),
+    join(dirname(resolve(recipe)), '..', 'refs', `${name}.md`),
+    resolve('refs', `${name}.md`),
+  ])
+    if (await Bun.file(p).exists()) return relative(process.cwd(), p) || p;
+  return undefined;
+}
+
+export async function reviewOne(
+  asset: Asset,
+  recipe: string,
+  args: Args,
+  sheet: PaintedSheet,
+): Promise<RenderResult> {
+  const dir = join(args.out, asset.name, 'review');
+  await mkdir(dir, { recursive: true });
+  const refs = await refsFor(asset.name, recipe);
+  const pack = reviewPack(asset, { ...args.render, sheet, ...(refs ? { refs } : {}) });
+  const files: string[] = [];
+  for (const [name, bytes] of pack.files) {
+    const path = join(dir, name);
+    await Bun.write(path, bytes);
+    files.push(path);
+  }
+  return { name: asset.name, files, warnings: pack.metrics.warnings };
+}
+
+export function printRendered(r: RenderResult): void {
+  console.log(
+    `${r.name}  ${r.warnings.length ? `${r.warnings.length} warning(s)` : 'no warnings'}`,
+  );
+  for (const f of r.files) console.log(`  → ${f}`);
+  for (const w of r.warnings) console.log(`  ! ${w.code}: ${w.message}\n    fix: ${w.fix}`);
+}

package/src/cli/run.ts

@@ -0,0 +1,192 @@
+// 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 <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 {
+  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,
+  args: Args,
+  texture: SheetBinding | undefined,
+  painted: PaintedSheet | undefined,
+): Promise<AssetManifest> {
+  const dir = join(args.out, asset.name);
+  await mkdir(dir, { recursive: true });
+  // Only the LODs the user asked for: QA, GLBs and the manifest cover exactly those.
+  const lods = args.lods.map((lod: Lod) => compile(asset, { lod }));
+  const findings: Finding[] = lods.flatMap((a) =>
+    runQa(a).map((f) => ({ ...f, message: `LOD${a.lod}: ${f.message}` })),
+  );
+  const glbs: string[] = [];
+  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, 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;
+  if (args.cmd === 'build' && args.shot) {
+    hero = join(dir, 'hero.png');
+    const top = lods[0] ?? compile(asset);
+    await Bun.write(hero, beauty(top, { ...args.render, ...(painted ? { sheet: painted } : {}) }));
+  }
+  if (args.cmd === 'shot' || args.shot) {
+    thumb = join(dir, 'thumb.png');
+    await Bun.write(thumb, thumbnail(lods[0] ?? compile(asset)));
+    sheet = join(dir, 'sheet.png');
+    await Bun.write(
+      sheet,
+      contactSheet(lods[0] ?? compile(asset), { far: lods.at(-1) ?? compile(asset, { lod: 2 }) }),
+    );
+  }
+  const manifest = manifestOf(
+    asset,
+    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;
+}
+
+function print(m: AssetManifest): void {
+  console.log(
+    `${m.name}  QA ${m.qa.pass ? 'PASS' : 'FAIL'}  tris ${m.triangles.join('/')}  draws ${m.drawCalls.join('/')}`,
+  );
+  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] : []),
+  ])
+    console.log(`  → ${f}`);
+  for (const f of m.qa.findings)
+    console.log(`  ✗ ${f.gate}${f.part ? ` [${f.part}]` : ''}: ${f.message}\n    fix: ${f.fix}`);
+}
+
+const COMMANDS = ['build', 'shot', 'list', 'hero', 'review'];
+
+function fail(e: unknown, json: boolean): number {
+  if (!(e instanceof Ts23dError)) throw e;
+  console.error(
+    json ? JSON.stringify({ ok: false, error: e.toJSON() }) : `${e.message}\n  fix: ${e.fix}`,
+  );
+  return 1;
+}
+
+export async function run(argv: readonly string[]): Promise<number> {
+  let args: Args;
+  try {
+    args = parseArgs(argv);
+  } catch (e) {
+    return fail(e, argv.includes('--json'));
+  }
+  if (!COMMANDS.includes(args.cmd) || args.files.length === 0) {
+    console.log(HELP);
+    return args.cmd === 'help' ? 0 : 2;
+  }
+  const built: AssetManifest[] = [];
+  const rendered: RenderResult[] = [];
+  // 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;
+  let texture: SheetBinding | undefined;
+  if (args.cmd === 'build' && args.sheet !== 'none' && painted) {
+    if (args.sheet === 'embed') texture = painted;
+    else {
+      const pngs = sheetPngs(painted);
+      await mkdir(args.out, { recursive: true });
+      for (const map of SHEET_MAPS) await Bun.write(join(args.out, sheetFileName(map)), pngs[map]);
+      texture = { external: true, prefix: '../trim_sheet' };
+    }
+  }
+  try {
+    for (const file of args.files) {
+      for (const asset of await loadAssets(file)) {
+        if (args.cmd === 'list')
+          console.log(
+            args.json ? JSON.stringify({ asset: asset.name, file }) : `${asset.name}  ${file}`,
+          );
+        else if (renders && painted)
+          rendered.push(
+            args.cmd === 'hero'
+              ? await heroOne(asset, args, painted)
+              : await reviewOne(asset, file, args, painted),
+          );
+        else built.push(await buildOne(asset, args, texture, painted));
+      }
+    }
+  } catch (e) {
+    return fail(e, args.json);
+  }
+  if (args.cmd === 'list') return 0;
+  if (renders) {
+    if (args.json) console.log(JSON.stringify({ ok: true, data: rendered }));
+    else rendered.forEach(printRendered);
+    return 0;
+  }
+  const ok = built.every((m) => m.qa.pass);
+  const index = built.map((m) => ({
+    name: m.name,
+    qa: m.qa.pass ? 'PASS' : 'FAIL',
+    triangles: m.triangles,
+    manifest: join(m.name, 'manifest.json'),
+  }));
+  await Bun.write(
+    join(args.out, 'index.json'),
+    `${JSON.stringify({ ok, assets: index }, null, 2)}\n`,
+  );
+  if (args.json) console.log(JSON.stringify({ ok, data: built }));
+  else built.forEach(print);
+  return ok ? 0 : 1;
+}

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

@@ -0,0 +1,129 @@
+// The DSL's root: an asset is a TypeScript function that builds named parts into a scene.
+// Code, not JSON — loops, helpers and composition are the point (docs/decisions/002).
+
+import type { Asset, AssetDefinition, AssetMeta, CompiledAsset } from './definition.ts';
+import { Ts23dError } from './errors.ts';
+import type { Mesh } from './mesh.ts';
+import type { Lod, Part, PartOptions, UseOptions } from './part.ts';
+import { createRng } from './rng.ts';
+
+export * from './definition.ts';
+export * from './part.ts';
+
+export function defineAsset(def: AssetDefinition): Asset {
+  if (!/^[a-z][a-z0-9_]*$/.test(def.name)) {
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `asset name '${def.name}' is not snake_case`,
+      fix: 'rename it to [a-z][a-z0-9_]* — it becomes the GLB file name and the root node',
+    });
+  }
+  return { ...def, __ts23d: 'asset' };
+}
+
+export const isAsset = (value: unknown): value is Asset =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { __ts23d?: unknown }).__ts23d === 'asset';
+
+export function compile(asset: Asset, options: { lod?: Lod; seed?: number } = {}): CompiledAsset {
+  const lod = options.lod ?? 0;
+  const seed = options.seed ?? asset.seed ?? 1;
+  const parts = new Map<string, Part>();
+  const add = (name: string, mesh: Mesh | null, o: PartOptions = {}): void => {
+    if (parts.has(name)) {
+      throw new Ts23dError('T3D_PART_DUPLICATE', {
+        cause: `part '${name}' was added twice in '${asset.name}'`,
+        fix: 'give each part a unique name — suffix the loop index, e.g. wheel_0, wheel_1',
+      });
+    }
+    if (o.parent !== undefined && !parts.has(o.parent)) {
+      throw new Ts23dError('T3D_PART_UNKNOWN', {
+        cause: `part '${name}' parents to '${o.parent}', which does not exist yet`,
+        fix: 'add the parent (ctx.group or ctx.part) before its children',
+      });
+    }
+    if (o.motion && o.yaw) {
+      throw new Ts23dError('T3D_RECIPE_INVALID', {
+        cause: `part '${name}' sets both yaw and motion`,
+        fix: 'put the yaw on a parent ctx.group and the motion on the part inside it',
+      });
+    }
+    parts.set(name, {
+      name,
+      mesh,
+      at: o.at ?? [0, 0, 0],
+      parent: o.parent ?? null,
+      yaw: o.yaw ?? 0,
+      motion: o.motion ?? null,
+      ...(o.clearOf ? { clearOf: o.clearOf } : {}),
+      ...(o.surface && o.surface !== 'opaque' ? { surface: o.surface } : {}),
+    });
+  };
+  const use = (child: Asset, o: UseOptions): void => {
+    const sub = compile(child, { lod, seed: o.seed ?? seed });
+    add(o.prefix, null, {
+      at: o.at ?? [0, 0, 0],
+      yaw: o.yaw ?? 0,
+      ...(o.parent ? { parent: o.parent } : {}),
+    });
+    for (const p of sub.parts) {
+      add(`${o.prefix}_${p.name}`, p.mesh, {
+        at: p.at,
+        yaw: p.yaw,
+        parent: p.parent ? `${o.prefix}_${p.parent}` : o.prefix,
+        ...(p.motion ? { motion: p.motion } : {}),
+        ...(p.surface ? { surface: p.surface } : {}),
+      });
+      const named = parts.get(`${o.prefix}_${p.name}`);
+      if (named && (p.emitter || p.socket)) {
+        parts.set(named.name, {
+          ...named,
+          ...(p.emitter ? { emitter: p.emitter } : {}),
+          ...(p.socket ? { socket: p.socket } : {}),
+        });
+      }
+    }
+  };
+  asset.build({
+    lod,
+    seed,
+    rng: createRng(seed),
+    pick: (perLod) => perLod[lod],
+    part: add,
+    group: (name, o) => add(name, null, o),
+    emitter: (name, { at, parent, ...emitter }) => {
+      add(name, null, { ...(at ? { at } : {}), ...(parent ? { parent } : {}) });
+      const p = parts.get(name);
+      if (p) parts.set(name, { ...p, emitter });
+    },
+    socket: (name, { at, parent, ...socket }) => {
+      add(name, null, { ...(at ? { at } : {}), ...(parent ? { parent } : {}) });
+      const p = parts.get(name);
+      if (p) parts.set(name, { ...p, socket });
+    },
+    use,
+  });
+  return {
+    name: asset.name,
+    kind: asset.kind,
+    lod,
+    budget: asset.budget,
+    real: asset.real ?? null,
+    checks: asset.checks ?? [],
+    parts: [...parts.values()],
+    ...metaOf(asset),
+    ...(asset.glow?.length ? { glow: asset.glow } : {}),
+    ...(asset.lodCoverage ? { lodCoverage: asset.lodCoverage } : {}),
+  };
+}
+
+function metaOf(a: Asset): { meta?: AssetMeta } {
+  const meta: AssetMeta = {
+    ...(a.description ? { description: a.description } : {}),
+    ...(a.sources?.length ? { sources: a.sources } : {}),
+    ...(a.license ? { license: a.license } : {}),
+    ...(a.copyright ? { copyright: a.copyright } : {}),
+    ...(a.creators?.length ? { creators: a.creators } : {}),
+  };
+  return Object.keys(meta).length ? { meta } : {};
+}

package/src/core/definition.ts

@@ -0,0 +1,156 @@
+// The asset contract: what defineAsset takes (AssetDefinition), what build() receives
+// (BuildContext), budgets, real-world dimensions, measures, checks, and the compiled result.
+
+import type { Mesh } from './mesh.ts';
+import type { EmitterOptions, Lod, Part, PartOptions, SocketOptions, UseOptions } from './part.ts';
+import type { Rng } from './rng.ts';
+
+export interface BuildContext {
+  readonly lod: Lod;
+  readonly seed: number;
+  readonly rng: Rng;
+  /** The value for this LOD: `ctx.pick([24, 12, 6])` — segments, counts, sizes per detail level. */
+  pick<T>(perLod: readonly [T, T, T]): T;
+  /** Add a named part. Names are the contract with the engine: `axle_*`, `door_*`, `rotor_*`. */
+  part(name: string, mesh: Mesh | null, options?: PartOptions): void;
+  /** An empty pivot that other parts parent to. */
+  group(name: string, options?: PartOptions): void;
+  /** Declare a particle source (smoke, steam, dust, muzzle…) as a named node. */
+  emitter(name: string, options: EmitterOptions): void;
+  /** Declare an attachment point (seat, mount, camera, audio, light…) as a named node. */
+  socket(name: string, options: SocketOptions): void;
+  /** Instance another asset inside this one, compiled at this LOD — the composition primitive. */
+  use(asset: Asset, options: UseOptions): void;
+}
+
+export interface Budget {
+  /** Triangle ceiling per LOD; QA fails the build above it. */
+  readonly triangles: readonly [number, number, number];
+}
+
+/** Real-world overall dimensions (metres) the QA `proportions` gate holds the model to. */
+export interface RealDimensions {
+  /** Along X (front-back). */
+  readonly length: number;
+  /** Along Y. */
+  readonly width: number;
+  /** Along Z. */
+  readonly height: number;
+  /** Allowed relative error per axis; default 0.05. */
+  readonly tolerance?: number;
+  /** Named spec-sheet dimensions checked against the model (QA `measures`). */
+  readonly measures?: readonly Measure[];
+}
+
+/**
+ * One real-world dimension from a source, checked against the model at LOD0: the world-space
+ * extent of `parts` (union of their bounds) along `axis`, or the distance between two parts'
+ * centres. E.g. driver diameter = extent of `axle_driver_0` on Z; gauge = centre distance of the
+ * two rail parts on Y; turret width = extent of `turret_body` on Y.
+ */
+export interface Measure {
+  readonly label: string;
+  readonly value: number;
+  readonly axis: 'x' | 'y' | 'z';
+  /** Extent of these parts (prefix match: 'axle_driver_0' includes its wheels). */
+  readonly parts?: readonly string[];
+  /** Or: distance between the centres of exactly two parts along `axis`. */
+  readonly between?: readonly [string, string];
+  readonly tolerance?: number;
+  /** Where this number comes from (one of `sources`, or a page reference). */
+  readonly source?: string;
+}
+
+/** One problem a recipe's own check found. QA turns these into findings named `check`. */
+export interface CheckFinding {
+  readonly message: string;
+  readonly fix: string;
+  readonly part?: string;
+}
+
+/**
+ * A recipe-declared assertion about its own geometry, run by the QA gate at every LOD:
+ * "tracks clear the hull", "wheels never overlap", "left matches right". Plain functions —
+ * build them with the helpers in /qa (`clear`, `touches`, `noOverlap`, `symmetric`) or write one.
+ */
+export type Check = (asset: CompiledAsset) => readonly CheckFinding[];
+
+/**
+ * Triangle budgets per class (LOD0 / LOD1 / LOD2): a starting point, measured on real recipes.
+ * `budget: BUDGETS.vehicle` — raise one with a measured reason, never to hide a regression.
+ */
+export const BUDGETS = {
+  prop: { triangles: [800, 300, 80] },
+  detailedProp: { triangles: [5000, 1500, 300] },
+  building: { triangles: [20000, 6000, 800] },
+  vehicle: { triangles: [60000, 15000, 1000] },
+  hero: { triangles: [150000, 40000, 2000] },
+  tree: { triangles: [25000, 6000, 300] },
+  scene: { triangles: [500000, 120000, 15000] },
+} as const satisfies Record<string, Budget>;
+
+/** A part set that emits light (lamp lenses, lit windows): an emissive material in the GLB. */
+export interface Glow {
+  /** Part names or globs: 'headlamp_*', 'window_*'. */
+  readonly parts: readonly string[];
+  /** Linear RGB 0..1 (`hex('#ffd9a0')`). Default warm white. */
+  readonly color?: readonly [number, number, number];
+  /** Brightness multiplier (KHR_materials_emissive_strength); 1 = plain glTF. Default 4. */
+  readonly strength?: number;
+}
+
+/** Provenance written into every GLB: `asset.copyright` + an XMP packet. */
+export interface AssetMeta {
+  readonly description?: string;
+  readonly sources?: readonly string[];
+  /** SPDX id or licence URL, e.g. 'CC0-1.0', 'MIT'. */
+  readonly license?: string;
+  /** e.g. '© 2026 Jane Doe'. */
+  readonly copyright?: string;
+  readonly creators?: readonly string[];
+}
+
+export interface AssetDefinition {
+  readonly name: string;
+  readonly kind: string;
+  readonly description?: string;
+  /** Where the numbers came from: spec sheets, rosters, drawings, photos. Required for `real`. */
+  readonly sources?: readonly string[];
+  readonly real?: RealDimensions;
+  readonly tags?: readonly string[];
+  readonly budget: Budget;
+  readonly seed?: number;
+  /** The recipe's own physical intent, enforced by QA (see Check). */
+  readonly checks?: readonly Check[];
+  /** SPDX id or licence URL for the generated asset, e.g. 'CC0-1.0'. Written into the GLB. */
+  readonly license?: string;
+  readonly copyright?: string;
+  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;
+}
+
+export interface Asset extends AssetDefinition {
+  readonly __ts23d: 'asset';
+}
+
+export interface CompiledAsset {
+  readonly name: string;
+  readonly kind: string;
+  readonly lod: Lod;
+  readonly budget: Budget;
+  readonly real: RealDimensions | null;
+  readonly checks: readonly Check[];
+  readonly parts: readonly Part[];
+  /** Provenance carried from the definition (absent when the recipe declares none). */
+  readonly meta?: AssetMeta;
+  readonly glow?: readonly Glow[];
+  readonly lodCoverage?: readonly [number, number, number];
+}