@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/kinds/vegetation.ts

@@ -0,0 +1,199 @@
+// Vegetation kind: `tree(ctx, …)` grows a Weber–Penn skeleton from species params and emits a
+// game tree — `trunk`, `roots` (buttress flare), and a swaying group `crown` holding `branches`
+// (merged) and `leaves` (merged cards) — then fits it onto its real height and crown spread.
+// LOD policy: LOD0 every level and every leaf card; LOD1 one level fewer (trees with ≥ 3 levels),
+// halved path resolution, twigs replaced by cluster cards; LOD2 an impostor under 300 triangles.
+
+import {
+  BUDGETS,
+  type BuildContext,
+  defineFamily,
+  type Mesh,
+  merge,
+  type RealDimensions,
+  Ts23dError,
+  translate,
+  triangleCount,
+  type Vec3,
+} from '../core/index.ts';
+import { frondLeaflets, fruit } from './vegetation-fronds.ts';
+import { blob, frondCards } from './vegetation-impostor.ts';
+import { clusterCards, crownShade, leafCards } from './vegetation-leaves.ts';
+import {
+  barkTint,
+  fitFactors,
+  radialSegments,
+  rootsMesh,
+  scaleMesh,
+  stemsMesh,
+  trunkMesh,
+} from './vegetation-mesh.ts';
+import type { TreeParams } from './vegetation-params.ts';
+import { SPECIES } from './vegetation-presets.ts';
+import { grow } from './vegetation-skeleton.ts';
+
+export interface TreeOptions {
+  /** A preset name (`oak`, `pine`, `palm`, `birch`, `willow`) or a full parameter set. */
+  readonly species?: string | TreeParams;
+  /** Overrides on top of the species. */
+  readonly params?: Partial<TreeParams>;
+  /** Total height, metres (ground to crown top). */
+  readonly height: number;
+  /** Crown spread (X and Y), metres. Default: the species' typical ratio to height. */
+  readonly spread?: number;
+  /** Trunk diameter at breast height (1.3 m), metres. Default: the species' typical ratio. */
+  readonly dbh?: number;
+  readonly seed?: number;
+  /** Part-name prefix: `oak_3` → `oak_3_trunk`, `oak_3_crown`, … */
+  readonly prefix?: string;
+}
+
+export interface TreeInfo {
+  readonly parts: { trunk: string; crown: string; branches: string; leaves: string; roots: string };
+  readonly height: number;
+  readonly spread: number;
+  readonly dbh: number;
+}
+
+export function treeParams(o: Pick<TreeOptions, 'species' | 'params'>): TreeParams {
+  const s = o.species ?? 'oak';
+  const base = typeof s === 'string' ? SPECIES[s as keyof typeof SPECIES] : s;
+  if (!base) {
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `unknown tree species '${String(s)}'`,
+      fix: `use one of ${Object.keys(SPECIES).join(', ')} or pass a TreeParams object (spread a preset and override)`,
+    });
+  }
+  return { ...base, ...o.params };
+}
+
+export function tree(ctx: BuildContext, o: TreeOptions): TreeInfo {
+  const p = treeParams(o);
+  if (!(o.height > 0) || p.levels.length < 2 || p.levels.length > 4) {
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `tree height ${o.height} m with ${p.levels.length} branch levels`,
+      fix: 'height must be > 0 and levels must hold the trunk plus 1–3 branch levels',
+    });
+  }
+  const k = o.height / p.typical.height;
+  const spread = o.spread ?? p.typical.spread * k;
+  const dbh = o.dbh ?? p.typical.dbh * k;
+  const pre = o.prefix ? `${o.prefix}_` : '';
+  const parts = {
+    trunk: `${pre}trunk`,
+    crown: `${pre}crown`,
+    branches: `${pre}branches`,
+    leaves: `${pre}leaves`,
+    roots: `${pre}roots`,
+  };
+  const rng = ctx.rng.fork(`tree:${o.prefix ?? ''}:${o.seed ?? 0}`);
+  const stems = grow(p, { height: o.height, dbh }, rng.fork('skeleton'));
+  const trunkStem = stems[0];
+  if (!trunkStem) return { parts, height: o.height, spread, dbh };
+  const deepest = p.levels.length - 1;
+  const lod = ctx.lod;
+  const top = trunkStem.pts[trunkStem.pts.length - 1]?.[2] ?? o.height;
+  const shade = crownShade(stems, 1);
+  let trunk: (r: number) => Mesh;
+  let roots: ((r: number) => Mesh) | null = null;
+  let branches: Mesh | null = null;
+  let leaves: Mesh;
+  if (lod === 2) {
+    const imp =
+      p.impostor === 'cards' ? frondCards(stems, p, 1) : blob(stems, p, rng.fork('impostor'));
+    trunk = () => barkTint(imp.trunk, p, top, rng.fork('bark'));
+    leaves = imp.leaves;
+  } else {
+    const hi = lod === 0 || deepest < 2 ? deepest : deepest - 1;
+    trunk = (r) => trunkMesh(trunkStem, p, lod, r, rng.fork('bark'));
+    if (p.roots) roots = (r) => rootsMesh(trunkStem, p, lod, r, rng.fork('roots'));
+    const wood = [
+      barkTint(stemsMesh(stems, 1, hi, lod, p.bark), p, top, rng.fork('bark:branches')),
+    ];
+    if (p.fruit && lod === 0)
+      wood.push(fruit(trunkStem, p.baseSize - 0.01, p.fruit, rng.fork('fruit')));
+    branches = merge(wood);
+    const lr = rng.fork('leaves');
+    leaves =
+      p.leaves.shape === 'frond'
+        ? frondLeaflets(
+            stems,
+            deepest,
+            p.leaves,
+            lod === 0 ? p.leaves.perStem : Math.ceil(p.leaves.perStem / 2),
+            shade,
+            lr,
+          )
+        : hi === deepest
+          ? leafCards(stems, deepest, radialSegments(deepest, lod), p.leaves, shade, lr)
+          : clusterCards(stems, deepest, p.leaves, shade, lr);
+  }
+  // Fit onto the real envelope; the trunk is rebuilt thinner by 1/sy so DBH (across Y) is exact.
+  const s = fitFactors(
+    [trunk(1), branches, leaves, roots?.(1) ?? null].filter((m): m is Mesh => m !== null),
+    [spread, spread, o.height],
+  );
+  const fit = (m: Mesh): Mesh => scaleMesh(m, s);
+  const base = trunkStem.pts[Math.round(p.baseSize * (trunkStem.pts.length - 1))] ?? [0, 0, 0];
+  const pivot: Vec3 = [base[0] * s[0], base[1] * s[1], base[2] * s[2]];
+  const back: Vec3 = [-pivot[0], -pivot[1], -pivot[2]];
+  ctx.part(parts.trunk, fit(trunk(1 / s[1])));
+  if (roots) ctx.part(parts.roots, fit(roots(1 / s[1])));
+  ctx.group(parts.crown, {
+    at: pivot,
+    motion: { kind: 'sway', axis: [1, 0, 0], degrees: 2, hz: 0.4 },
+    // The crown grows out of the trunk: they meet by design, and the clash gate's conservative
+    // full-turn sway volume would otherwise flag the wood that holds it.
+    clearOf: roots ? [parts.trunk, parts.roots] : [parts.trunk],
+  });
+  if (branches && triangleCount(branches) > 0)
+    ctx.part(parts.branches, translate(fit(branches), back), { parent: parts.crown });
+  ctx.part(parts.leaves, translate(fit(leaves), back), { parent: parts.crown });
+  return { parts, height: o.height, spread, dbh };
+}
+
+/** `real` for a tree recipe: overall envelope plus DBH (trunk across Y) and total height. */
+export function treeReal(o: {
+  height: number;
+  spread: number;
+  dbh: number;
+  prefix?: string;
+  source?: string;
+}): RealDimensions {
+  const pre = o.prefix ? `${o.prefix}_` : '';
+  const src = o.source ? { source: o.source } : {};
+  return {
+    length: o.spread,
+    width: o.spread,
+    height: o.height,
+    measures: [
+      {
+        label: 'trunk diameter at breast height',
+        value: o.dbh,
+        axis: 'y',
+        parts: [`${pre}trunk`],
+        ...src,
+      },
+      {
+        label: 'total height',
+        value: o.height,
+        axis: 'z',
+        parts: [`${pre}trunk`, `${pre}crown`, `${pre}branches`, `${pre}leaves`, `${pre}roots`],
+        ...src,
+      },
+    ],
+  };
+}
+
+export type TreeFamilyParams = Omit<TreeOptions, 'prefix'>;
+
+/** One family, many species: `trees.variant({ name: 'oak', params: { species: 'oak', height: 22 } })`. */
+export const trees = defineFamily<TreeFamilyParams>({
+  kind: 'vegetation',
+  tags: ['vegetation', 'tree'],
+  budget: BUDGETS.tree,
+  defaults: { species: 'oak', height: 22 },
+  build: (ctx, p) => {
+    tree(ctx, p);
+  },
+});

package/src/kinds/vehicle.ts

@@ -0,0 +1,144 @@
+// Vehicle helpers: wheels that spin, tracks, propellers. Named parts follow the engine contract:
+// `axle_*` and `wheel_*` spin about local Y, `prop_*`/`rotor_*` spin about their own axis.
+
+import { type BuildContext, place, type Vec3 } from '../core/index.ts';
+import { parseWhyte } from '../grammar/index.ts';
+import { box, cylinder } from '../primitives/index.ts';
+
+const segs = (ctx: BuildContext, hi: number): number => [hi, Math.max(8, hi / 2), 6][ctx.lod] ?? 6;
+
+/** A pair of wheels on one spinning axle. */
+export function axle(
+  ctx: BuildContext,
+  o: {
+    name: string;
+    at: Vec3;
+    radius: number;
+    gauge: number;
+    width: number;
+    color: Vec3;
+    rps: number;
+  },
+): void {
+  ctx.group(o.name, { at: o.at, motion: { kind: 'spin', axis: [0, 1, 0], rps: o.rps } });
+  for (const [s, y] of [
+    ['l', o.gauge / 2],
+    ['r', -o.gauge / 2],
+  ] as const) {
+    ctx.part(
+      `${o.name}_wheel_${s}`,
+      cylinder({
+        radius: o.radius,
+        length: o.width,
+        segments: segs(ctx, 24),
+        axis: 'y',
+        at: [0, y, 0],
+        color: o.color,
+        strip: 'iron',
+      }),
+      { parent: o.name },
+    );
+  }
+}
+
+/** Lays out wheel groups from a Whyte arrangement along X; returns axle x-positions per role. */
+export function whyteAxles(
+  arrangement: string,
+  o: { leading: number; driving: number; trailing: number; spacing: number },
+): { role: string; x: number; radius: number }[] {
+  const groups = parseWhyte(arrangement);
+  const out: { role: string; x: number; radius: number }[] = [];
+  let x = 0;
+  for (const g of groups) {
+    const r = g.role === 'driving' ? o.driving : g.role === 'leading' ? o.leading : o.trailing;
+    for (let i = 0; i < g.count / 2; i++) {
+      out.push({ role: g.role, x: x + r, radius: r });
+      x += r * 2 + o.spacing;
+    }
+  }
+  const mid = x / 2;
+  // Front (+X) is the leading end.
+  return out.map((a) => ({ ...a, x: mid - a.x }));
+}
+
+/** One side of a tracked running gear: road wheels (spinning) + a flat track loop. */
+export function trackRun(
+  ctx: BuildContext,
+  o: {
+    side: 'l' | 'r';
+    y: number;
+    length: number;
+    wheels: number;
+    radius: number;
+    width: number;
+    color: Vec3;
+    track: Vec3;
+  },
+): void {
+  const pitch = o.length / o.wheels;
+  for (let i = 0; i < o.wheels; i++) {
+    const x = -o.length / 2 + pitch * (i + 0.5);
+    ctx.part(
+      `road_wheel_${o.side}_${i}`,
+      cylinder({
+        radius: o.radius,
+        length: o.width * 0.8,
+        segments: segs(ctx, 20),
+        axis: 'y',
+        at: [0, 0, 0],
+        color: o.color,
+        strip: 'iron',
+      }),
+      { at: [x, o.y, o.radius + 0.06], motion: { kind: 'spin', axis: [0, 1, 0], rps: -0.6 } },
+    );
+  }
+  const t = 0.06;
+  ctx.part(
+    `track_${o.side}_bottom`,
+    box({
+      size: [o.length + o.radius, o.width, t],
+      at: [0, o.y, 0],
+      color: o.track,
+      strip: 'iron',
+    }),
+  );
+  ctx.part(
+    `track_${o.side}_top`,
+    box({
+      size: [o.length, o.width, t],
+      at: [0, o.y, o.radius * 2 + 0.06],
+      color: o.track,
+      strip: 'iron',
+    }),
+  );
+}
+
+/** A propeller hub + blades that spin about X (nose direction). */
+export function propeller(
+  ctx: BuildContext,
+  o: { name: string; at: Vec3; radius: number; blades: number; color: Vec3; parent?: string },
+): void {
+  ctx.group(o.name, {
+    at: o.at,
+    ...(o.parent ? { parent: o.parent } : {}),
+    motion: { kind: 'spin', axis: [1, 0, 0], rps: 6 },
+  });
+  ctx.part(
+    `${o.name}_hub`,
+    cylinder({
+      radius: o.radius * 0.12,
+      length: o.radius * 0.3,
+      segments: segs(ctx, 12),
+      axis: 'x',
+      color: o.color,
+    }),
+    { parent: o.name },
+  );
+  // One blade built pointing up (+Z) from the hub, then rolled about the spin axis per blade.
+  const blade = box({ size: [0.03, o.radius * 0.12, o.radius], color: o.color });
+  for (let i = 0; i < o.blades; i++) {
+    ctx.part(`${o.name}_blade_${i}`, place(blade, { roll: (i / o.blades) * Math.PI * 2 }), {
+      parent: o.name,
+    });
+  }
+}

package/src/material/cc0.ts

@@ -0,0 +1,41 @@
+// Ready-made CC0 image materials (opt-in, never registered by default, so the repo paints offline).
+// Register with `defineMaterial(CC0_WOOD_PLANKS_GREY)`, fetch once with `bun run textures`, then
+// `provideTextures(await loadTextureCache())` before painting. Hashes pin the exact bytes.
+
+import type { MaterialDef } from './material-def.ts';
+
+const PH = 'https://dl.polyhaven.org/file/ph-assets/Textures/png/1k/wood_planks_grey';
+
+/** Poly Haven "Wood Planks Grey" by Rob Tuytel (CC0), 1.5 m square, 1k PNG maps. */
+export const CC0_WOOD_PLANKS_GREY: MaterialDef = {
+  id: 'ph_wood_planks_grey',
+  kind: 'flat',
+  scaleMetres: 0.6,
+  roughness: 0.85,
+  description: 'Photo-scanned weathered grey planks (Poly Haven, CC0).',
+  sources: ['https://polyhaven.com/a/wood_planks_grey'],
+  texture: {
+    source: 'polyhaven',
+    id: 'wood_planks_grey',
+    license: 'CC0-1.0',
+    page: 'https://polyhaven.com/a/wood_planks_grey',
+    author: 'Rob Tuytel',
+    metres: [1.5, 1.5],
+    maps: {
+      albedo: {
+        url: `${PH}/wood_planks_grey_diff_1k.png`,
+        sha256: '3e6aeb842edd813759fdc96a6ffe6b695c888280f42501de589442311749ac5d',
+      },
+      normal: {
+        url: `${PH}/wood_planks_grey_nor_gl_1k.png`,
+        sha256: 'a9f2ad602eca2d59e84f203b1087e819e62ae517532bb25f7eb02a13c826e08b',
+      },
+      arm: {
+        url: `${PH}/wood_planks_grey_arm_1k.png`,
+        sha256: '9b81e9a0b4f9db0a920c4c2ce8ff13e0411b3624d4de455acdabe41e3fafe20e',
+      },
+    },
+  },
+};
+
+export const CC0_MATERIALS: readonly MaterialDef[] = [CC0_WOOD_PLANKS_GREY];

package/src/material/define.ts

@@ -0,0 +1,130 @@
+// Project materials: `defineMaterial` validates a MaterialDef, gives it one of the sheet's custom
+// strip rows (in registration order: define materials in one shared module so every recipe sees
+// the same order) and adds it to the house sheet, so `DEFAULT_SHEET` paints it and primitives map
+// onto it. Redefining an id with the same definition is a no-op; a different one is a conflict.
+// `materialOf` answers what any strip is (built-in or defined) for docs, review and tests;
+// `textureSources` / `stripCredits` serve the CC0 image strips (fetch list, GLB credits).
+
+import { Ts23dError } from '../core/index.ts';
+import { MATERIAL_LIBRARY } from './library.ts';
+import { type MaterialDef, toStripRecipe } from './material-def.ts';
+import { HOUSE_STRIPS } from './paint/default-sheet.ts';
+import type { StripRecipe } from './paint/types.ts';
+import { clearCustom, customIds, customIndex, pushCustom } from './slots.ts';
+import { creditOf, type TextureSource } from './texture-source.ts';
+import {
+  CLASSIC_STRIPS,
+  CUSTOM_STRIP_SLOTS,
+  type CustomStripId,
+  STRIPS,
+  type StripId,
+  stripRect,
+} from './trim-sheet.ts';
+
+const defined = new Map<string, MaterialDef>();
+
+/** The same definition, field by field (painters by identity, colours and params by value). */
+function same(a: MaterialDef, b: MaterialDef): boolean {
+  return (
+    JSON.stringify({ ...a, paint: 0 }) === JSON.stringify({ ...b, paint: 0 }) && a.paint === b.paint
+  );
+}
+
+/**
+ * Register a project material and return its strip id for `strip:` options.
+ * @example
+ * const teak = defineMaterial({ id: 'teak_deck', kind: 'planks', roughness: 0.6,
+ *   albedo: '#8a5a32', albedo2: '#5a3a1e', params: { width: 0.12, rings: 0.5 } });
+ * box({ size: [4, 2, 0.05], strip: teak, color: NATURAL });
+ */
+export function defineMaterial(def: MaterialDef): CustomStripId {
+  const recipe = toStripRecipe(def);
+  const id = def.id;
+  if ((STRIPS as readonly string[]).includes(id))
+    throw new Ts23dError('T3D_MATERIAL_CONFLICT', {
+      cause: `material '${id}' is a built-in strip`,
+      fix: `pick another id (e.g. '${id}_custom'), or restyle the built-in via paintTrimSheet({ ...DEFAULT_SHEET, strips: { ...DEFAULT_SHEET.strips, ${id}: … } })`,
+    });
+  const prior = defined.get(id);
+  if (prior) {
+    if (same(prior, def)) return id as CustomStripId;
+    throw new Ts23dError('T3D_MATERIAL_CONFLICT', {
+      cause: `material '${id}' is already defined differently`,
+      fix: 'define each material once in a shared module and import it, or give the variant its own id',
+    });
+  }
+  if (customIds().length >= CUSTOM_STRIP_SLOTS)
+    throw new Ts23dError('T3D_SHEET_FULL', {
+      cause: `the trim sheet has ${CUSTOM_STRIP_SLOTS} custom strip rows, all taken (${customIds().join(', ')})`,
+      fix: 'reuse a built-in strip with a vertex colour, or restyle an unused built-in strip in your SheetRecipe',
+    });
+  defined.set(id, def);
+  pushCustom(id);
+  (HOUSE_STRIPS as Record<string, StripRecipe>)[id] = recipe;
+  return id as CustomStripId;
+}
+
+/**
+ * Forget every defined material (tests; long-lived workers that reload recipes). Built-ins stay.
+ * Meshes compiled before the reset keep UVs into rows that may be reassigned.
+ */
+export function resetMaterials(): void {
+  for (const id of defined.keys()) delete (HOUSE_STRIPS as Record<string, StripRecipe>)[id];
+  defined.clear();
+  clearCustom();
+}
+
+export interface MaterialInfo {
+  readonly id: StripId;
+  /** classic = greyscale strip tinted by vertex colour; library/defined carry their own colour. */
+  readonly origin: 'classic' | 'library' | 'defined';
+  readonly recipe: StripRecipe;
+  readonly description: string;
+  readonly sources: readonly string[];
+}
+
+/** What a strip is: its recipe, origin, description and sources. Unknown ids throw. */
+export function materialOf(id: StripId): MaterialInfo {
+  const recipe = HOUSE_STRIPS[id];
+  const lib = (MATERIAL_LIBRARY as Readonly<Record<string, MaterialDef>>)[id];
+  const def = lib ?? defined.get(id);
+  if (!recipe || (customIndex(id) < 0 && !(STRIPS as readonly string[]).includes(id)))
+    throw new Ts23dError('T3D_MATERIAL_UNKNOWN', {
+      cause: `strip '${id}' is neither built in nor defined`,
+      fix: `use one of ${STRIPS.join(', ')}, or defineMaterial({ id: '${id}', ... }) first`,
+    });
+  const classic = (CLASSIC_STRIPS as readonly string[]).includes(id);
+  return {
+    id,
+    origin: classic ? 'classic' : lib ? 'library' : 'defined',
+    recipe,
+    description:
+      def?.description ?? `classic ${recipe.kind} strip (greyscale, vertex colour tints)`,
+    sources: def?.sources ?? [],
+  };
+}
+
+/** Every texture set a defined material references (what `bun run textures` fetches). */
+export function textureSources(): readonly TextureSource[] {
+  return [...defined.values()].flatMap((d) => (d.texture ? [d.texture] : []));
+}
+
+/**
+ * Credit lines for the image strips a mesh samples: any V coordinate inside such a strip's row
+ * counts. Empty when no image strip is used (the GLB stays byte-identical).
+ */
+export function stripCredits(vs: ArrayLike<number>): string[] {
+  const out: string[] = [];
+  for (const [id, d] of defined) {
+    if (!d.texture) continue;
+    const r = stripRect(id as StripId);
+    for (let i = 0; i < vs.length; i++) {
+      const v = vs[i] ?? -1;
+      if (v >= r.v0 && v <= r.v1) {
+        out.push(creditOf(d.texture));
+        break;
+      }
+    }
+  }
+  return out;
+}

package/src/material/generator.ts

@@ -0,0 +1,63 @@
+// Procedural material generator: paints the shared trim sheet (albedo, normal, ORM) from code —
+// brick bonds, plank grain (oak, pine, weathered, painted), riveted plates, bare/cast/painted/
+// galvanised metal, canvas, leather, slate, concrete, glass, decal cells and cutout foliage cards
+// — at a fixed seed, so the texture is as deterministic as the meshes. Supplied PNGs (reference
+// photos, kubeez.com generations) can stamp cells; they are inputs, never the only path.
+//
+// Conventions: V (image row) grows with world up, as box/planar map faces; strips tile seamlessly
+// along U and span `stripRect().metres` there and `scaleMetres` along V; classic strips are
+// near-greyscale sRGB (vertex colour tints them); library/defined material strips, foliage and
+// stamped cells carry colour. Project strips (`defineMaterial`) paint after the built-ins.
+
+import { createRng } from '../core/index.ts';
+import { createCanvas } from './paint/canvas.ts';
+import { paintCell } from './paint/cell.ts';
+import { blankSheet, composeRegion } from './paint/compose.ts';
+import { DEFAULT_SHEET } from './paint/default-sheet.ts';
+import { paintStrip } from './paint/strip.ts';
+import type { PaintedSheet, SheetRecipe } from './paint/types.ts';
+import { validateSheet, validateStrip } from './paint/validate.ts';
+import { customIds } from './slots.ts';
+import { CELLS, cellRect, STRIPS, type StripId, stripRect } from './trim-sheet.ts';
+
+export { DEFAULT_SHEET } from './paint/default-sheet.ts';
+export type {
+  CellImage,
+  MaterialPainter,
+  MaterialSurface,
+  PaintedSheet,
+  PaintKit,
+  SheetRecipe,
+  StripKind,
+  StripRecipe,
+} from './paint/types.ts';
+
+const FALLBACK = { kind: 'noise', scaleMetres: 1, roughness: 0.6 } as const;
+
+export function paintTrimSheet(recipe: SheetRecipe = DEFAULT_SHEET): PaintedSheet {
+  validateSheet(recipe);
+  const size = recipe.size ?? 2048;
+  const sheet = blankSheet(size);
+  const rng = createRng(recipe.seed);
+  const seedOf = (name: string): number => rng.fork(name).int(0, 0x7fffffff);
+  const pad = Math.max(2, size / 256);
+  const all = [...STRIPS, ...(customIds() as readonly StripId[])];
+  for (const id of all) {
+    const r = recipe.strips[id] ?? DEFAULT_SHEET.strips[id] ?? FALLBACK;
+    validateStrip(`strips.${id}`, r);
+    const rect = stripRect(id);
+    const h = Math.round((rect.v1 - rect.v0) * size);
+    const c = createCanvas(size, h, rect.metres, r.scaleMetres, true);
+    paintStrip(c, r, seedOf(id), `strips.${id}`);
+    composeRegion(sheet, c, 0, Math.round(rect.v0 * size), pad);
+  }
+  for (const id of CELLS) {
+    const e = recipe.cells?.[id] ?? DEFAULT_SHEET.cells?.[id] ?? FALLBACK;
+    const rect = cellRect(id);
+    const w = Math.round((rect.u1 - rect.u0) * size);
+    const c = createCanvas(w, w, rect.metres, rect.metres, false);
+    paintCell(c, id, e, seedOf(id));
+    composeRegion(sheet, c, Math.round(rect.u0 * size), Math.round(rect.v0 * size), pad);
+  }
+  return sheet;
+}

package/src/material/index.ts

@@ -0,0 +1,60 @@
+// Public API of @developerz.ai/ts23d/material: the shared trim-sheet layout, the procedural sheet
+// painter, the material library + `defineMaterial` for project materials, palettes and engine
+// shader sources.
+
+export { CC0_MATERIALS, CC0_WOOD_PLANKS_GREY } from './cc0.ts';
+export {
+  defineMaterial,
+  type MaterialInfo,
+  materialOf,
+  resetMaterials,
+  stripCredits,
+  textureSources,
+} from './define.ts';
+export {
+  type CellImage,
+  DEFAULT_SHEET,
+  type MaterialPainter,
+  type MaterialSurface,
+  type PaintedSheet,
+  type PaintKit,
+  paintTrimSheet,
+  type SheetRecipe,
+  type StripKind,
+  type StripRecipe,
+} from './generator.ts';
+export { MATERIAL_LIBRARY } from './library.ts';
+export type { MaterialDef } from './material-def.ts';
+export { definePalette, hex, NATURAL, type Palette, palettes } from './palette.ts';
+export { godotShaderSource, type ShaderHints, threeMaterialSource } from './shader.ts';
+export {
+  creditOf,
+  provideTextures,
+  type TextureCache,
+  type TextureFile,
+  type TextureSource,
+} from './texture-source.ts';
+export {
+  type BuiltinStripId,
+  CELLS,
+  type CellId,
+  CLASSIC_STRIPS,
+  type ClassicStripId,
+  CUSTOM_STRIP_SLOTS,
+  type CustomStripId,
+  cellRect,
+  DECAL_CELLS,
+  type DecalCellId,
+  FOLIAGE_CELLS,
+  type FoliageCellId,
+  isFoliage,
+  MATERIAL_STRIPS,
+  type MaterialStripId,
+  STRIP_ROWS,
+  STRIPS,
+  type StripId,
+  stripRect,
+  stripRow,
+  TRIM_SHEET_SIZE,
+  type UvRect,
+} from './trim-sheet.ts';