@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/material/texture-source.ts

@@ -0,0 +1,86 @@
+// Image-backed strips: a CC0 PBR texture set (Poly Haven, ambientCG or a local file) declared as
+// data — URL + sha256 per map, licence, author page, real-world size. Compile and paint stay
+// offline: bytes come only from a content-addressed cache the caller provides (`provideTextures`,
+// filled by `bun run textures`); a missing map throws T3D_TEXTURE_MISSING with that command.
+
+import { Ts23dError } from '../core/index.ts';
+
+export interface TextureFile {
+  /** Download URL (https) or, for `source: 'file'`, a path relative to the working directory. */
+  readonly url: string;
+  /** Lower-case hex sha256 of the file's bytes: the cache key and the integrity check. */
+  readonly sha256: string;
+}
+
+export interface TextureSource {
+  readonly source: 'polyhaven' | 'ambientcg' | 'file';
+  /** The set's id at the source, e.g. 'wood_planks_grey'. */
+  readonly id: string;
+  /** Only public-domain sets are accepted, so a generated asset never inherits a licence duty. */
+  readonly license: 'CC0-1.0';
+  /** Human page crediting the set (goes into the GLB's XMP credits). */
+  readonly page: string;
+  readonly author?: string;
+  /** Real-world size the image covers, metres (U × V). Poly Haven lists it as `dimensions`. */
+  readonly metres: readonly [number, number];
+  readonly maps: {
+    /** sRGB base colour. */
+    readonly albedo: TextureFile;
+    /** Tangent-space normal, OpenGL convention (+Y up in the image; Poly Haven `nor_gl`). */
+    readonly normal?: TextureFile;
+    /** Packed AO / roughness / metalness (Poly Haven `arm`, glTF ORM order). */
+    readonly arm?: TextureFile;
+  };
+}
+
+/** PNG bytes by sha256. */
+export type TextureCache = ReadonlyMap<string, Uint8Array>;
+
+const SHA = /^[0-9a-f]{64}$/;
+const provided = new Map<string, Uint8Array>();
+
+/** Hand verified texture bytes to the painter (e.g. from `loadTextureCache()` in scripts). */
+export function provideTextures(cache: TextureCache): void {
+  for (const [k, v] of cache) provided.set(k, v);
+}
+
+export function textureBytes(file: TextureFile, where: string): Uint8Array {
+  const hit = provided.get(file.sha256);
+  if (hit) return hit;
+  throw new Ts23dError('T3D_TEXTURE_MISSING', {
+    cause: `${where}: texture ${file.url} (sha256 ${file.sha256.slice(0, 12)}…) is not in the cache`,
+    fix: 'run `bun run textures <module defining the material>` once (downloads + verifies into node_modules/.cache/ts23d/textures), then provideTextures(await loadTextureCache()) before painting',
+  });
+}
+
+export function validateTexture(id: string, t: TextureSource): void {
+  const fail = (cause: string, fix: string): never => {
+    throw new Ts23dError('T3D_MATERIAL_INVALID', { cause: `material '${id}': ${cause}`, fix });
+  };
+  if (!['polyhaven', 'ambientcg', 'file'].includes(t.source))
+    fail(`texture.source '${t.source}'`, "use 'polyhaven', 'ambientcg' or 'file'");
+  if (t.license !== 'CC0-1.0')
+    fail(
+      `texture.license '${t.license}'`,
+      'only CC0-1.0 sets are accepted (Poly Haven and ambientCG are CC0)',
+    );
+  if (!(t.metres.length === 2 && t.metres.every((m) => Number.isFinite(m) && m > 0)))
+    fail(`texture.metres [${t.metres}]`, 'give the real size the image covers, e.g. [1.5, 1.5]');
+  for (const [map, f] of Object.entries(t.maps)) {
+    if (!f) continue;
+    if (!SHA.test(f.sha256))
+      fail(
+        `texture.maps.${map}.sha256 '${f.sha256}'`,
+        'lower-case hex sha256 of the file (sha256sum)',
+      );
+    if (!/\.png$/i.test(f.url))
+      fail(
+        `texture.maps.${map}.url '${f.url}'`,
+        'use the PNG download (8- or 16-bit); JPEG is not decoded',
+      );
+  }
+}
+
+/** One credit line for the GLB's XMP and the docs. */
+export const creditOf = (t: TextureSource): string =>
+  `${t.id}${t.author ? ` by ${t.author}` : ''} (${t.source}, ${t.license}) ${t.page}`;

package/src/material/trim-sheet.ts

@@ -0,0 +1,166 @@
+// The shared trim sheet: ONE 2048² atlas (albedo + normal + ORM) every asset maps into, so every
+// asset is one material and one draw call. Strips tile along U; cells are fixed decals.
+// Layout is data here; `paintTrimSheet` (generator.ts) paints it. V grows with world up on
+// box/planar faces. V 0–0.875 holds 28 strip rows (64 px each at 2048²): the 8 original strips,
+// 16 physically distinct materials (woods, metals, rubber, canvas, leather, plastic) and 4 slots
+// for project materials (`defineMaterial`). V 0.875–1 holds 128 px cells: decals, then foliage.
+
+import { Ts23dError } from '../core/index.ts';
+import { customIndex } from './slots.ts';
+
+/** The original eight strips: greyscale, tinted by vertex colour. */
+export type ClassicStripId =
+  | 'plain'
+  | 'brick'
+  | 'stone'
+  | 'slate'
+  | 'iron'
+  | 'wood'
+  | 'glass'
+  | 'concrete';
+/** Material strips with measured colour: use a near-white vertex colour (`NATURAL`) for truth. */
+export type MaterialStripId =
+  | 'oak'
+  | 'pine'
+  | 'wood_weathered'
+  | 'wood_painted'
+  | 'iron_rust'
+  | 'iron_cast'
+  | 'steel_painted'
+  | 'steel_galvanised'
+  | 'brass'
+  | 'copper'
+  | 'aluminium'
+  | 'chrome'
+  | 'rubber'
+  | 'canvas'
+  | 'leather'
+  | 'plastic';
+export type BuiltinStripId = ClassicStripId | MaterialStripId;
+/** A project material's id, as returned by `defineMaterial` (a branded string). */
+export type CustomStripId = string & { readonly __ts23dMaterial: true };
+export type StripId = BuiltinStripId | CustomStripId;
+export type DecalCellId = 'window_sash' | 'door_panel' | 'clock' | 'smokebox' | 'sign' | 'porthole';
+/** Cutout leaf cards: the anchor (twig base) is the cell's bottom-centre, growth toward +V. */
+export type FoliageCellId =
+  | 'foliage_broadleaf'
+  | 'foliage_maple'
+  | 'foliage_maple_autumn'
+  | 'foliage_birch'
+  | 'foliage_acacia'
+  | 'foliage_palm'
+  | 'foliage_spruce'
+  | 'foliage_spruce_snow'
+  | 'foliage_willow'
+  | 'foliage_reeds'
+  | 'foliage_needles';
+export type CellId = DecalCellId | FoliageCellId;
+
+export interface UvRect {
+  readonly u0: number;
+  readonly v0: number;
+  readonly u1: number;
+  readonly v1: number;
+  /** Metres of world surface one full rect covers, so texel density is equal across assets. */
+  readonly metres: number;
+}
+
+/** Strip rows in the atlas: built-ins first, then `CUSTOM_STRIP_SLOTS` project materials. */
+export const STRIP_ROWS = 28;
+const STRIP_H = 1 / 32;
+const classic: readonly ClassicStripId[] = [
+  'plain',
+  'brick',
+  'stone',
+  'slate',
+  'iron',
+  'wood',
+  'glass',
+  'concrete',
+];
+const material: readonly MaterialStripId[] = [
+  'oak',
+  'pine',
+  'wood_weathered',
+  'wood_painted',
+  'iron_rust',
+  'iron_cast',
+  'steel_painted',
+  'steel_galvanised',
+  'brass',
+  'copper',
+  'aluminium',
+  'chrome',
+  'rubber',
+  'canvas',
+  'leather',
+  'plastic',
+];
+const strips: readonly BuiltinStripId[] = [...classic, ...material];
+export const CUSTOM_STRIP_SLOTS = STRIP_ROWS - strips.length;
+const decals: readonly DecalCellId[] = [
+  'window_sash',
+  'door_panel',
+  'clock',
+  'smokebox',
+  'sign',
+  'porthole',
+];
+const foliage: readonly FoliageCellId[] = [
+  'foliage_broadleaf',
+  'foliage_maple',
+  'foliage_maple_autumn',
+  'foliage_birch',
+  'foliage_acacia',
+  'foliage_palm',
+  'foliage_spruce',
+  'foliage_spruce_snow',
+  'foliage_willow',
+  'foliage_reeds',
+  'foliage_needles',
+];
+const cells: readonly CellId[] = [...decals, ...foliage];
+/** Cells are 1/16 of the sheet, 16 per row from V 0.875: decals at 0–5, foliage from slot 8. */
+const CELL = 1 / 16;
+const CELL_V0 = STRIP_ROWS * STRIP_H;
+const FOLIAGE_SLOT = 8;
+const slotOf = (id: CellId): number => {
+  const d = decals.indexOf(id as DecalCellId);
+  return d >= 0 ? d : FOLIAGE_SLOT + foliage.indexOf(id as FoliageCellId);
+};
+
+export const TRIM_SHEET_SIZE = 2048;
+
+/** Atlas row of a strip id, or −1 when it is neither built in nor defined. */
+export function stripRow(id: string): number {
+  const b = strips.indexOf(id as BuiltinStripId);
+  if (b >= 0) return b;
+  const c = customIndex(id);
+  return c >= 0 ? strips.length + c : -1;
+}
+
+export function stripRect(id: StripId): UvRect {
+  const i = stripRow(id);
+  if (i < 0)
+    throw new Ts23dError('T3D_MATERIAL_UNKNOWN', {
+      cause: `strip '${id}' is neither built in nor defined`,
+      fix: `use a built-in strip (${strips.join(', ')}) or register it first with defineMaterial({ id: '${id}', ... })`,
+    });
+  return { u0: 0, v0: i * STRIP_H, u1: 1, v1: (i + 1) * STRIP_H, metres: 2 };
+}
+
+export function cellRect(id: CellId): UvRect {
+  const i = slotOf(id);
+  const u0 = (i % 16) * CELL;
+  const v0 = CELL_V0 + Math.floor(i / 16) * CELL;
+  return { u0, v0, u1: u0 + CELL, v1: v0 + CELL, metres: 1 };
+}
+
+/** Every built-in strip, classic first. */
+export const STRIPS = strips;
+export const CLASSIC_STRIPS = classic;
+export const MATERIAL_STRIPS = material;
+export const CELLS = cells;
+export const DECAL_CELLS = decals;
+export const FOLIAGE_CELLS = foliage;
+export const isFoliage = (id: CellId): id is FoliageCellId => id.startsWith('foliage_');

package/src/neural/generator.ts

@@ -0,0 +1,37 @@
+// Optional seam for organic shapes the recipe approach handles poorly: people, animals, sculpted
+// rocks. Runs an open-weight image/text-to-3D model on the USER's GPU (TRELLIS, Hunyuan3D, SF3D…)
+// behind a local HTTP endpoint, then wraps the result as an ordinary part. Never a core dependency.
+//
+// Determinism: a generated mesh is cached by (model, prompt/image hash, seed) under
+// .ts23d/neural/ and committed or published like any asset, so CI rebuilds without a GPU.
+
+import { type Mesh, notImplemented, type Vec3 } from '../core/index.ts';
+
+export interface GenerateRequest {
+  readonly prompt?: string;
+  /** PNG/JPEG bytes of a reference or concept image. */
+  readonly image?: Uint8Array;
+  readonly seed: number;
+  /** Fit the result into this box (metres), Z up, base on the ground. */
+  readonly fit: Vec3;
+  readonly targetTriangles: number;
+}
+
+export interface MeshGenerator {
+  /** e.g. 'trellis-2', 'hunyuan3d-2.1', 'sf3d'. Part of the cache key. */
+  readonly model: string;
+  generate(request: GenerateRequest): Promise<Mesh>;
+}
+
+/** Talks to a local server (e.g. a ComfyUI / gradio wrapper) at `endpoint`. Planned: M5. */
+export function localGenerator(_o: { model: string; endpoint: string }): MeshGenerator {
+  return notImplemented(
+    'localGenerator (local GPU model adapter)',
+    'docs/idea/08-neural-adapters.md',
+  );
+}
+
+/** Import an existing GLB (a CC0 base mesh, a sculpt, a generator's output) as a part. Planned: M5. */
+export function importGlb(_bytes: Uint8Array, _o: { fit: Vec3; recolor?: Vec3 }): Mesh {
+  return notImplemented('importGlb', 'docs/idea/08-neural-adapters.md');
+}

package/src/neural/images.ts

@@ -0,0 +1,27 @@
+// Image sources for the material generator and the agent loop: reference/concept images, decals,
+// texture source photos. kubeez.com is the recommended hosted source; any function returning PNG
+// bytes fits. Results are cached by (source, prompt, seed) like generated meshes. Planned: M5.
+
+import { notImplemented } from '../core/index.ts';
+
+export interface ImageRequest {
+  readonly prompt: string;
+  readonly seed: number;
+  readonly width: number;
+  readonly height: number;
+  /** e.g. 'decal', 'tileable', 'reference', 'concept'. */
+  readonly purpose: 'decal' | 'tileable' | 'reference' | 'concept';
+}
+
+export interface ImageSource {
+  readonly name: string;
+  generate(request: ImageRequest): Promise<Uint8Array>;
+}
+
+/** kubeez.com image generation. Reads the key from the caller, never from ambient env. */
+export function kubeezImages(_o: { apiKey: string; model?: string }): ImageSource {
+  return notImplemented(
+    'kubeezImages (kubeez.com image source)',
+    'docs/idea/08-neural-adapters.md',
+  );
+}

package/src/neural/index.ts

@@ -0,0 +1,10 @@
+// Public API of /neural: optional AI adapters — local-GPU mesh generators for organic shapes,
+// mesh import, and image sources (kubeez.com) for references and materials. Never required.
+
+export {
+  type GenerateRequest,
+  importGlb,
+  localGenerator,
+  type MeshGenerator,
+} from './generator.ts';
+export { type ImageRequest, type ImageSource, kubeezImages } from './images.ts';

package/src/passes/bake-ao.ts

@@ -0,0 +1,183 @@
+// Ambient occlusion baked into vertex colour: the cheapest big look upgrade for a vertex-coloured
+// asset — creases, wheel wells and the gap under a turret darken, as a lit render would. Each
+// vertex fires a fixed cosine-weighted hemisphere of rays (Fibonacci spiral, no randomness) at the
+// asset's own triangles (and optionally the ground plane); the hit fraction darkens its colour.
+
+import { type CompiledAsset, type Mesh, merge, type Vec3, worldMeshes } from '../core/index.ts';
+import { RayGrid } from './ray-grid.ts';
+
+export interface AoOptions {
+  /** Rays per vertex. Default 24. */
+  readonly samples?: number;
+  /** Occluders farther than this (metres) don't count. Default 1. */
+  readonly radius?: number;
+  /** 0 = no change, 1 = fully occluded vertices go black. Default 0.6. */
+  readonly strength?: number;
+  /** Treat z = 0 as a ground plane (contact shadow under the asset). Default true. */
+  readonly ground?: boolean;
+}
+
+const GOLDEN = Math.PI * (3 - Math.sqrt(5));
+
+/** Fixed cosine-weighted directions around +Z. */
+function hemisphere(n: number): Vec3[] {
+  return Array.from({ length: n }, (_, i) => {
+    const r = Math.sqrt((i + 0.5) / n);
+    const phi = i * GOLDEN;
+    return [r * Math.cos(phi), r * Math.sin(phi), Math.sqrt(Math.max(0, 1 - r * r))] as Vec3;
+  });
+}
+
+/** Orthonormal frame with `n` as its Z (Frisvad / Duff et al. branchless basis). */
+function frame(n: Vec3): [Vec3, Vec3] {
+  const s = n[2] >= 0 ? 1 : -1;
+  const a = -1 / (s + n[2]);
+  const b = n[0] * n[1] * a;
+  return [
+    [1 + s * n[0] * n[0] * a, s * b, -s * n[0]],
+    [b, s + n[1] * n[1] * a, -n[1]],
+  ];
+}
+
+/**
+ * Vertices sharing a position (0.1 mm) and normal (0.001) share one result: welded seams and
+ * duplicated soup vertices cost one hemisphere, not many. Open addressing on the six integers.
+ */
+class Memo {
+  private readonly keys: Float64Array;
+  private readonly vals: Float64Array;
+  private readonly used: Uint8Array;
+  private readonly mask: number;
+
+  constructor(n: number) {
+    let cap = 16;
+    while (cap < n * 2) cap *= 2;
+    this.mask = cap - 1;
+    this.keys = new Float64Array(cap * 6);
+    this.vals = new Float64Array(cap);
+    this.used = new Uint8Array(cap);
+  }
+
+  /** Slot for the key; `found` tells whether it already holds a value. */
+  slot(k: Float64Array): { at: number; found: boolean } {
+    let h = 2166136261;
+    for (let i = 0; i < 6; i++) h = Math.imul(h ^ ((k[i] ?? 0) | 0), 16777619);
+    let at = (h >>> 0) & this.mask;
+    for (;;) {
+      if (!this.used[at]) return { at, found: false };
+      let same = true;
+      for (let i = 0; i < 6 && same; i++) same = this.keys[at * 6 + i] === k[i];
+      if (same) return { at, found: true };
+      at = (at + 1) & this.mask;
+    }
+  }
+
+  get(at: number): number {
+    return this.vals[at] ?? 0;
+  }
+
+  set(at: number, k: Float64Array, v: number): void {
+    this.used[at] = 1;
+    this.keys.set(k, at * 6);
+    this.vals[at] = v;
+  }
+}
+
+/** Per-vertex visibility (1 = open sky, 0 = buried) of `mesh` against `grid`. */
+function visibility(mesh: Mesh, grid: RayGrid, o: AoOptions): Float32Array {
+  const hemi = hemisphere(o.samples ?? 24);
+  const D = Float64Array.from(hemi.flat());
+  const count = hemi.length;
+  const radius = o.radius ?? 1;
+  const ground = o.ground ?? true;
+  const P = mesh.positions;
+  const N = mesh.normals;
+  const out = new Float32Array(P.length / 3);
+  const memo = new Memo(out.length);
+  const key = new Float64Array(6);
+  // Lift off the surface so a ray never hits the face it starts on.
+  const bias = 2e-3;
+  for (let v = 0; v < out.length; v++) {
+    const px = P[v * 3] ?? 0;
+    const py = P[v * 3 + 1] ?? 0;
+    const pz = P[v * 3 + 2] ?? 0;
+    const rx = N[v * 3] ?? 0;
+    const ry = N[v * 3 + 1] ?? 0;
+    const rz = N[v * 3 + 2] ?? 1;
+    const len = Math.hypot(rx, ry, rz) || 1;
+    const n: Vec3 = [rx / len, ry / len, rz / len];
+    key[0] = Math.round(px * 1e4);
+    key[1] = Math.round(py * 1e4);
+    key[2] = Math.round(pz * 1e4);
+    key[3] = Math.round(n[0] * 1e3);
+    key[4] = Math.round(n[1] * 1e3);
+    key[5] = Math.round(n[2] * 1e3);
+    const s = memo.slot(key);
+    if (s.found) {
+      out[v] = memo.get(s.at);
+      continue;
+    }
+    const [t, b] = frame(n);
+    const ox = px + n[0] * bias;
+    const oy = py + n[1] * bias;
+    const oz = pz + n[2] * bias;
+    let blocked = 0;
+    for (let i = 0; i < count; i++) {
+      const d0 = D[i * 3] ?? 0;
+      const d1 = D[i * 3 + 1] ?? 0;
+      const d2 = D[i * 3 + 2] ?? 0;
+      const wx = t[0] * d0 + b[0] * d1 + n[0] * d2;
+      const wy = t[1] * d0 + b[1] * d1 + n[1] * d2;
+      const wz = t[2] * d0 + b[2] * d1 + n[2] * d2;
+      if (ground && wz < -1e-6 && oz >= 0 && -oz / wz <= radius) blocked++;
+      else if (grid.hit(ox, oy, oz, wx, wy, wz, radius)) blocked++;
+    }
+    const vis = 1 - blocked / count;
+    memo.set(s.at, key, vis);
+    out[v] = vis;
+  }
+  return out;
+}
+
+const darken = (mesh: Mesh, vis: Float32Array, strength: number): Mesh => {
+  const colors = new Float32Array(mesh.colors);
+  for (let v = 0; v < vis.length; v++) {
+    const f = 1 - strength * (1 - (vis[v] ?? 1));
+    for (let k = 0; k < 3; k++) colors[v * 3 + k] = (colors[v * 3 + k] ?? 0) * f;
+  }
+  return { ...mesh, colors };
+};
+
+/** Bake AO of one mesh against itself (or `occluder`, in the same space). */
+// Callers bake several parts against one occluder (a head's skin, jaw and eyes against the
+// whole head): index each occluder once. Meshes are immutable, so the grid stays valid.
+const grids = new WeakMap<Mesh, RayGrid>();
+const gridOf = (m: Mesh): RayGrid => {
+  const hit = grids.get(m);
+  if (hit) return hit;
+  const g = new RayGrid(m);
+  grids.set(m, g);
+  return g;
+};
+
+export function bakeAo(mesh: Mesh, o: AoOptions = {}, occluder: Mesh = mesh): Mesh {
+  return darken(mesh, visibility(mesh, gridOf(occluder), o), o.strength ?? 0.6);
+}
+
+/**
+ * Bake AO across a whole compiled asset: every part is occluded by every other (a wheel darkens
+ * the hull behind it). Colours only change, so parts keep their local meshes and pivots.
+ */
+export function bakeAoAsset(asset: CompiledAsset, o: AoOptions = {}): CompiledAsset {
+  const world = worldMeshes(asset.parts);
+  if (world.size === 0) return asset;
+  const grid = new RayGrid(merge([...world.values()]));
+  const strength = o.strength ?? 0.6;
+  return {
+    ...asset,
+    parts: asset.parts.map((p) => {
+      const w = world.get(p.name);
+      return p.mesh && w ? { ...p, mesh: darken(p.mesh, visibility(w, grid, o), strength) } : p;
+    }),
+  };
+}

package/src/passes/grime.ts

@@ -0,0 +1,37 @@
+// Grime: darken vertex colour near the ground and in named zones (soot, mud, dust). A pass over a
+// finished mesh, so recipes stay about shape; wear is applied once, the same way everywhere.
+
+import type { Mesh, Vec3 } from '../core/index.ts';
+
+export interface GrimeZone {
+  readonly at: Vec3;
+  readonly radius: number;
+  /** 0..1 darkening at the centre. */
+  readonly strength: number;
+}
+
+export interface GrimeOptions {
+  /** Height (m) below which mud/dust builds up toward the ground. */
+  readonly ground?: number;
+  /** Darkening at z = 0. */
+  readonly groundStrength?: number;
+  readonly zones?: readonly GrimeZone[];
+}
+
+export function grime(mesh: Mesh, o: GrimeOptions): Mesh {
+  const colors = new Float32Array(mesh.colors);
+  const g = o.ground ?? 0;
+  const gs = o.groundStrength ?? 0.3;
+  for (let i = 0; i < mesh.positions.length / 3; i++) {
+    const x = mesh.positions[i * 3] ?? 0;
+    const y = mesh.positions[i * 3 + 1] ?? 0;
+    const z = mesh.positions[i * 3 + 2] ?? 0;
+    let f = g > 0 && z < g ? 1 - gs * (1 - Math.max(0, z) / g) : 1;
+    for (const zone of o.zones ?? []) {
+      const d = Math.hypot(x - zone.at[0], y - zone.at[1], z - zone.at[2]) / zone.radius;
+      if (d < 1) f *= 1 - zone.strength * (1 - d);
+    }
+    for (let k = 0; k < 3; k++) colors[i * 3 + k] = (colors[i * 3 + k] ?? 1) * f;
+  }
+  return { ...mesh, colors };
+}

package/src/passes/index.ts

@@ -0,0 +1,8 @@
+// Public API of /passes: whole-mesh post-processing applied after geometry — wear, optimisation.
+
+export { type AoOptions, bakeAo, bakeAoAsset } from './bake-ao.ts';
+export { type GrimeOptions, type GrimeZone, grime } from './grime.ts';
+export { type Livery, type LiveryRule, livery } from './livery.ts';
+export { type OptimizeOptions, type OptimizeReport, optimize } from './optimize.ts';
+export { RayGrid } from './ray-grid.ts';
+export { type WeightedNormalsOptions, weightedNormals } from './weighted-normals.ts';

package/src/passes/livery.ts

@@ -0,0 +1,66 @@
+// Livery: paint a finished mesh by rules instead of by hand. Base colour, then ordered rules —
+// the last matching rule wins — keyed on height bands, an along-length range, a side-elevation
+// polygon (stripes, wings, numbers' backgrounds), and surface orientation (roof, front, back,
+// sides, underside). One call turns a grey loco into "Daylight", a tank into its camo scheme.
+
+import type { Mesh, Vec2, Vec3 } from '../core/index.ts';
+
+export interface LiveryRule {
+  readonly color: Vec3;
+  /** Height band [z0, z1] (metres). */
+  readonly z?: readonly [number, number];
+  /** Along-length band [x0, x1] (metres, +X forward). */
+  readonly x?: readonly [number, number];
+  /** Polygon in the side elevation (x, z): the region a stripe or panel covers. */
+  readonly poly?: readonly Vec2[];
+  /** Only faces whose normal points this way (n·axis > 0.5; roof: n.z > 0.55). */
+  readonly facing?: 'roof' | 'under' | 'front' | 'back' | 'side';
+  /** Multiply into the existing colour instead of replacing it (weathering, shading). */
+  readonly multiply?: boolean;
+}
+
+export interface Livery {
+  readonly base?: Vec3;
+  readonly rules: readonly LiveryRule[];
+}
+
+function inPoly(poly: readonly Vec2[], x: number, z: number): boolean {
+  let inside = false;
+  for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+    const [xi, zi] = poly[i] ?? [0, 0];
+    const [xj, zj] = poly[j] ?? [0, 0];
+    if (zi > z !== zj > z && x < ((xj - xi) * (z - zi)) / (zj - zi) + xi) inside = !inside;
+  }
+  return inside;
+}
+
+function faces(f: NonNullable<LiveryRule['facing']>, n: Vec3): boolean {
+  if (f === 'roof') return n[2] > 0.55;
+  if (f === 'under') return n[2] < -0.55;
+  if (f === 'front') return n[0] > 0.5;
+  if (f === 'back') return n[0] < -0.5;
+  return Math.abs(n[1]) > 0.5;
+}
+
+export function livery(mesh: Mesh, l: Livery): Mesh {
+  const colors = new Float32Array(mesh.colors);
+  for (let i = 0; i < mesh.positions.length / 3; i++) {
+    const x = mesh.positions[i * 3] ?? 0;
+    const z = mesh.positions[i * 3 + 2] ?? 0;
+    const n: Vec3 = [
+      mesh.normals[i * 3] ?? 0,
+      mesh.normals[i * 3 + 1] ?? 0,
+      mesh.normals[i * 3 + 2] ?? 0,
+    ];
+    let c: Vec3 = l.base ?? [colors[i * 3] ?? 1, colors[i * 3 + 1] ?? 1, colors[i * 3 + 2] ?? 1];
+    for (const r of l.rules) {
+      if (r.z && (z < r.z[0] || z > r.z[1])) continue;
+      if (r.x && (x < r.x[0] || x > r.x[1])) continue;
+      if (r.poly && !inPoly(r.poly, x, z)) continue;
+      if (r.facing && !faces(r.facing, n)) continue;
+      c = r.multiply ? [c[0] * r.color[0], c[1] * r.color[1], c[2] * r.color[2]] : r.color;
+    }
+    colors.set(c, i * 3);
+  }
+  return { ...mesh, colors };
+}