@developerz.ai/ts23d 0.1.0 → 0.2.0

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

@@ -1,11 +1,13 @@
 // Procedural material generator: paints the shared trim sheet (albedo, normal, ORM) from code —
-// brick bonds, plank grain, riveted plates, 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
+// 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; albedo is near-greyscale
-// sRGB (vertex colour tints it) except foliage and stamped cells, which carry colour + alpha.
+// 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';
@@ -15,12 +17,16 @@ 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 { CELLS, cellRect, STRIPS, stripRect } from './trim-sheet.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,
@@ -30,18 +36,19 @@ 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 ?? 1024;
+  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);
-  for (const id of STRIPS) {
+  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));
+    paintStrip(c, r, seedOf(id), `strips.${id}`);
     composeRegion(sheet, c, 0, Math.round(rect.v0 * size), pad);
   }
   for (const id of CELLS) {

package/src/material/index.ts

@@ -1,29 +1,60 @@
-// Public API of @ts23d/material: the shared trim-sheet layout, the procedural sheet painter,
-// palettes and engine shader sources.
+// 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 { definePalette, hex, type Palette, palettes } from './palette.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';

package/src/material/library.ts

@@ -0,0 +1,196 @@
+// The house material library: sixteen physically distinct strips with measured or sourced PBR
+// numbers (docs/architecture/materials.md has the table and the reasoning). Metals use the
+// physicallybased.info reflectance (sRGB here), dielectrics stay inside the 30–240 sRGB albedo
+// range, roughness follows engine/asset references. Colour lives in the texture, so tint these
+// with a near-white vertex colour (`NATURAL`) — except where noted (paint films take the hue).
+
+import type { MaterialDef } from './material-def.ts';
+import type { MaterialStripId } from './trim-sheet.ts';
+
+const PB = 'https://physicallybased.info';
+const ROBLOX = 'https://create.roblox.com/docs/art/modeling/material-reference';
+const PBR_GUIDE = 'https://www.adobe.com/learn/substance-3d-designer/web/the-pbr-guide-part-2';
+
+type Library = Readonly<Record<MaterialStripId, MaterialDef & { readonly id: MaterialStripId }>>;
+
+export const MATERIAL_LIBRARY: Library = {
+  oak: {
+    id: 'oak',
+    kind: 'planks',
+    scaleMetres: 0.6,
+    roughness: 0.68,
+    albedo: '#a27b52',
+    albedo2: '#6a482b',
+    params: { width: 0.14, rings: 0.55, rays: 0.6, knots: 0.6 },
+    description: 'Oak boards: warm brown, dark latewood rings, pale ray flecks.',
+    sources: [PBR_GUIDE, ROBLOX],
+  },
+  pine: {
+    id: 'pine',
+    kind: 'planks',
+    scaleMetres: 0.6,
+    roughness: 0.72,
+    albedo: '#d2b183',
+    albedo2: '#9b6a3c',
+    params: { width: 0.16, rings: 0.75, knots: 2.5 },
+    description: 'Pine boards: pale yellow, strong orange latewood, frequent knots.',
+    sources: [PBR_GUIDE, ROBLOX],
+  },
+  wood_weathered: {
+    id: 'wood_weathered',
+    kind: 'planks',
+    scaleMetres: 0.6,
+    roughness: 0.86,
+    albedo: '#9b968c',
+    albedo2: '#4f463c',
+    params: { width: 0.2, rings: 0.35, checks: 1, knots: 1.5, grime: 0.15 },
+    description: 'Barn-grey weathered boards: silvered, eroded grain, open checks.',
+    sources: [ROBLOX],
+  },
+  wood_painted: {
+    id: 'wood_painted',
+    kind: 'planks',
+    scaleMetres: 0.6,
+    roughness: 0.84,
+    albedo: '#ededed',
+    albedo2: '#a08c74',
+    params: { width: 0.14, paint: 1, paintRough: 0.62, chips: 0.38, knots: 0.8, grime: 0.3 },
+    description: 'Painted boards (vertex colour = paint) worn through to grey wood at the edges.',
+    sources: [ROBLOX],
+  },
+  iron_rust: {
+    id: 'iron_rust',
+    kind: 'metal',
+    scaleMetres: 0.5,
+    roughness: 0.55,
+    metalness: 0.9,
+    albedo: '#8e8a85',
+    albedo2: '#764323',
+    params: { oxide: 0.62, cast: 0.25, streaks: 0.5 },
+    description: 'Weathered wrought/rolled iron, rust blooming in patches and runs.',
+    sources: [PB, ROBLOX],
+  },
+  iron_cast: {
+    id: 'iron_cast',
+    kind: 'metal',
+    scaleMetres: 0.5,
+    roughness: 0.68,
+    metalness: 0.75,
+    albedo: '#6c6966',
+    albedo2: '#55372a',
+    params: { cast: 1, oxide: 0.35 },
+    description: 'Sand-cast iron (wheels, frames): dark pitted skin, dull oxide.',
+    sources: [PB],
+  },
+  steel_painted: {
+    id: 'steel_painted',
+    kind: 'metal',
+    scaleMetres: 0.5,
+    roughness: 0.4,
+    metalness: 1,
+    albedo: '#eeeeee',
+    albedo2: '#5a3b2a',
+    params: { paint: 1, paintRough: 0.42, chips: 0.2, streaks: 0.2, grime: 0.2 },
+    description: 'Painted steel (vertex colour = paint): chips show rusty steel beneath.',
+    sources: [ROBLOX],
+  },
+  steel_galvanised: {
+    id: 'steel_galvanised',
+    kind: 'metal',
+    scaleMetres: 0.5,
+    roughness: 0.42,
+    metalness: 1,
+    albedo: '#d5dadc',
+    albedo2: '#9a9c98',
+    params: { spangle: 1, oxide: 0.12 },
+    description: 'Hot-dip galvanised steel: zinc spangle, white-rust bloom.',
+    sources: [PB],
+  },
+  brass: {
+    id: 'brass',
+    kind: 'metal',
+    scaleMetres: 0.5,
+    roughness: 0.28,
+    metalness: 1,
+    albedo: '#f5e5ae',
+    albedo2: '#6b5a3a',
+    params: { brush: 0.3, oxide: 0.1 },
+    description: 'Brass fittings: warm gold reflectance, dark tarnish in patches.',
+    sources: [PB, ROBLOX],
+  },
+  copper: {
+    id: 'copper',
+    kind: 'metal',
+    scaleMetres: 0.5,
+    roughness: 0.32,
+    metalness: 1,
+    albedo: '#f2b89c',
+    albedo2: '#6fa58f',
+    params: { oxide: 0.15 },
+    description: 'Copper: salmon reflectance with verdigris patches.',
+    sources: [PB],
+  },
+  aluminium: {
+    id: 'aluminium',
+    kind: 'metal',
+    scaleMetres: 0.5,
+    roughness: 0.34,
+    metalness: 1,
+    albedo: '#e6e8e9',
+    params: { brush: 1 },
+    description: 'Brushed aluminium: bright, cool, streaked along U.',
+    sources: [PB],
+  },
+  chrome: {
+    id: 'chrome',
+    kind: 'metal',
+    scaleMetres: 0.5,
+    roughness: 0.07,
+    metalness: 1,
+    albedo: '#d3d9dc',
+    description: 'Chrome plate: near-mirror.',
+    sources: [PB],
+  },
+  rubber: {
+    id: 'rubber',
+    kind: 'noise',
+    scaleMetres: 0.5,
+    roughness: 0.78,
+    albedo: '#2c2c2c',
+    params: { tone: 0.95, mottle: 0.06, relief: 0.0002, size: 0.05, grime: 0.2 },
+    description: 'Vulcanised rubber (tyres, hoses, seals).',
+    sources: [PB, ROBLOX],
+  },
+  canvas: {
+    id: 'canvas',
+    kind: 'weave',
+    scaleMetres: 1,
+    roughness: 0.88,
+    albedo: '#cbbea2',
+    albedo2: '#8a7c62',
+    params: { pitch: 0.004, folds: 0.6, stains: 0.35 },
+    description: 'Cotton duck canvas: natural, weave relief, folds and water stains.',
+    sources: [ROBLOX],
+  },
+  leather: {
+    id: 'leather',
+    kind: 'leather',
+    scaleMetres: 0.5,
+    roughness: 0.58,
+    albedo: '#7c5438',
+    albedo2: '#3e281a',
+    params: { creases: 0.5, wear: 0.4 },
+    description: 'Worn brown leather: pebble grain, dark creases, burnished wear.',
+    sources: [ROBLOX],
+  },
+  plastic: {
+    id: 'plastic',
+    kind: 'noise',
+    scaleMetres: 0.5,
+    roughness: 0.35,
+    albedo: '#ececec',
+    params: { tone: 0.97, mottle: 0.01, relief: 0.00004, size: 0.2 },
+    description: 'Moulded plastic (vertex colour = the plastic colour): satin, even.',
+    sources: [ROBLOX],
+  },
+};

package/src/material/material-def.ts

@@ -0,0 +1,84 @@
+// The material definition contract: what a project (or the house library) says about a strip —
+// PBR numbers, intrinsic colour, a base painter kind and an optional painter layer — and its
+// translation to the sheet's StripRecipe. Validation throws T3D_MATERIAL_INVALID with the fix.
+
+import { Ts23dError, type Vec3 } from '../core/index.ts';
+import type { MaterialPainter, StripKind, StripRecipe } from './paint/types.ts';
+import { hex } from './palette.ts';
+import { type TextureSource, validateTexture } from './texture-source.ts';
+
+export interface MaterialDef {
+  /** snake_case, unique; becomes the strip id recipes pass as `strip`. */
+  readonly id: string;
+  /** Base painter the strip starts from. Default 'noise' (a quiet surface). */
+  readonly kind?: StripKind;
+  /** World metres the strip's V span represents (typical face height). Default 1. */
+  readonly scaleMetres?: number;
+  /** Perceptual roughness 0..1 (glTF): 0 mirror, 1 chalk. */
+  readonly roughness: number;
+  /** 0 dielectric, 1 metal. Default 0. Avoid in-between values except for dirt/oxide blends. */
+  readonly metalness?: number;
+  /** Intrinsic base colour: sRGB '#rrggbb' or linear RGB. Default white (vertex colour = hue). */
+  readonly albedo?: string | Vec3;
+  /** Second colour the painter blends to (latewood, rust, verdigris, bare wood under paint). */
+  readonly albedo2?: string | Vec3;
+  /** Painter knobs for `kind` (see each painter's header in src/material/paint/). */
+  readonly params?: Readonly<Record<string, number>>;
+  /** Your own layer, painted after `kind`: write height/tone/rough/metal/mix per texel. */
+  readonly paint?: MaterialPainter;
+  /** Paint from a CC0 texture set (opt-in, needs `bun run textures`) instead of `kind`. */
+  readonly texture?: TextureSource;
+  readonly description?: string;
+  /** Where the numbers come from (URLs). */
+  readonly sources?: readonly string[];
+}
+
+const ID = /^[a-z][a-z0-9_]{1,31}$/;
+const unit = (v: number): boolean => Number.isFinite(v) && v >= 0 && v <= 1;
+
+function fail(id: string, cause: string, fix: string): never {
+  throw new Ts23dError('T3D_MATERIAL_INVALID', { cause: `material '${id}': ${cause}`, fix });
+}
+
+function colour(id: string, key: string, v: string | Vec3 | undefined): Vec3 | undefined {
+  if (v === undefined) return undefined;
+  if (typeof v === 'string') {
+    if (!/^#?[0-9a-fA-F]{6}$/.test(v))
+      fail(id, `${key} '${v}' is not a hex colour`, "use '#rrggbb'");
+    return hex(v);
+  }
+  if (!(v.length === 3 && v.every(unit)))
+    fail(id, `${key} [${v}] is not linear RGB 0..1`, "use '#rrggbb' or three numbers in 0..1");
+  return v;
+}
+
+/** Validate a definition and turn it into the strip recipe the sheet painter runs. */
+export function toStripRecipe(d: MaterialDef): StripRecipe {
+  const id = String(d.id);
+  if (!ID.test(id))
+    fail(id, 'id is not snake_case (2–32 chars, starts with a letter)', "e.g. 'teak_deck'");
+  if (!unit(d.roughness)) fail(id, `roughness ${d.roughness}`, 'roughness is 0..1');
+  if (d.metalness !== undefined && !unit(d.metalness))
+    fail(id, `metalness ${d.metalness}`, 'metalness is 0..1 (0 dielectric, 1 metal)');
+  const scale = d.scaleMetres ?? 1;
+  if (!(Number.isFinite(scale) && scale > 0))
+    fail(id, `scaleMetres ${scale}`, 'scaleMetres is the face height in metres, > 0');
+  if (d.paint !== undefined && typeof d.paint !== 'function')
+    fail(id, 'paint is not a function', 'paint is (surface, kit) => void');
+  for (const [k, v] of Object.entries(d.params ?? {}))
+    if (!Number.isFinite(v)) fail(id, `params.${k} is ${v}`, 'params are finite numbers');
+  if (d.texture) validateTexture(id, d.texture);
+  const albedo = colour(id, 'albedo', d.albedo);
+  const albedo2 = colour(id, 'albedo2', d.albedo2);
+  return {
+    kind: d.kind ?? 'noise',
+    scaleMetres: scale,
+    roughness: d.roughness,
+    ...(d.metalness !== undefined ? { metalness: d.metalness } : {}),
+    ...(d.params ? { params: d.params } : {}),
+    ...(albedo ? { albedo } : {}),
+    ...(albedo2 ? { albedo2 } : {}),
+    ...(d.paint ? { paint: d.paint } : {}),
+    ...(d.texture ? { texture: d.texture } : {}),
+  };
+}

package/src/material/paint/canvas.ts

@@ -1,7 +1,8 @@
 // The painting surface for one sheet region (a strip or a cell): float layers in real metres.
 // Painters write height (metres of relief, + is out of the surface), linear grey tone,
-// roughness and metalness; `finish` turns them into normal + ORM; `compose` copies into the sheet.
+// roughness, metalness and a two-colour `mix`; `compose` turns them into albedo + normal + ORM.
 
+import type { Vec3 } from '../../core/index.ts';
 import { fbm } from './noise.ts';
 
 export interface Canvas {
@@ -18,8 +19,14 @@ export interface Canvas {
   readonly metal: Float32Array;
   /** Extra occlusion multiplied into the cavity AO (foliage darkens toward the twig). */
   readonly occl: Float32Array;
+  /** 0 = `colours[0]`, 1 = `colours[1]` (latewood, rust, bare wood under chipped paint…). */
+  readonly mix: Float32Array;
+  /** Linear albedo pair for material strips; null = greyscale (vertex colour carries hue). */
+  colours: readonly [Vec3, Vec3] | null;
   /** sRGB RGBA override (stamped images, coloured foliage); null when painted greyscale. */
   rgba: Uint8Array | null;
+  /** Tangent-space normal override (image strips); null = derived from `height`. */
+  normalRgba: Uint8Array | null;
 }
 
 export function createCanvas(
@@ -41,7 +48,10 @@ export function createCanvas(
     rough: new Float32Array(n).fill(0.8),
     metal: new Float32Array(n),
     occl: new Float32Array(n).fill(1),
+    mix: new Float32Array(n),
+    colours: null,
     rgba: null,
+    normalRgba: null,
   };
 }
 

package/src/material/paint/compose.ts

@@ -32,7 +32,7 @@ export function composeRegion(
   const ao = cavityOcclusion(c);
   const maps = [
     [sheet.albedo, packAlbedo(c, ao)],
-    [sheet.normal, sobelNormals(c)],
+    [sheet.normal, c.normalRgba ?? sobelNormals(c)],
     [sheet.orm, packOrm(c, ao)],
   ] as const;
   const padX = c.wrapU ? 0 : pad;

package/src/material/paint/decode-png.ts

@@ -1,5 +1,5 @@
-// Minimal PNG decoder for stamping supplied images into cells: 8-bit grey, grey+alpha, RGB, RGBA
-// and palette (with tRNS), non-interlaced. Zero dependencies beyond node:zlib. Anything else
+// Minimal PNG decoder for stamping supplied images into cells and image strips: 8- or 16-bit grey,
+// grey+alpha, RGB, RGBA (16-bit keeps the high byte) and 8-bit palette (with tRNS), non-interlaced. Zero dependencies beyond node:zlib. Anything else
 // throws T3D_RECIPE_INVALID with the conversion to make.
 
 import { inflateSync } from 'node:zlib';
@@ -17,7 +17,7 @@ const CHANNELS: Readonly<Record<number, number>> = { 0: 1, 2: 3, 3: 1, 4: 2, 6:
 function bad(cause: string): never {
   throw new Ts23dError('T3D_RECIPE_INVALID', {
     cause: `cell image: ${cause}`,
-    fix: 'pass PNG bytes, 8 bits per channel, non-interlaced (e.g. re-save as RGBA8 PNG)',
+    fix: 'pass PNG bytes, 8 or 16 bits per channel, non-interlaced (e.g. re-save as RGBA8 PNG)',
   });
 }
 
@@ -35,6 +35,7 @@ export function decodePng(bytes: Uint8Array): Rgba {
   let width = 0;
   let height = 0;
   let type = -1;
+  let depth = 8;
   let palette: Uint8Array = new Uint8Array();
   let trns: Uint8Array = new Uint8Array();
   const idat: Uint8Array[] = [];
@@ -46,7 +47,9 @@ export function decodePng(bytes: Uint8Array): Rgba {
       width = dv.getUint32(o + 8);
       height = dv.getUint32(o + 12);
       type = body[9] ?? -1;
-      if (body[8] !== 8) bad(`bit depth ${body[8]} (only 8 is supported)`);
+      depth = body[8] ?? 0;
+      if (depth !== 8 && !(depth === 16 && type !== 3))
+        bad(`bit depth ${depth} (8, or 16 for non-palette images, is supported)`);
       if (body[12] !== 0) bad('interlaced');
     } else if (name === 'PLTE') palette = body;
     else if (name === 'tRNS') trns = body;
@@ -57,7 +60,9 @@ export function decodePng(bytes: Uint8Array): Rgba {
   const ch = CHANNELS[type];
   if (!ch || width === 0 || height === 0) bad(`colour type ${type} or empty image`);
   const raw = new Uint8Array(inflateSync(Buffer.concat(idat)));
-  const stride = width * ch;
+  const B = depth / 8;
+  const bpp = ch * B;
+  const stride = width * bpp;
   if (raw.length < height * (stride + 1)) bad('truncated image data');
   const px = new Uint8Array(height * stride);
   for (let y = 0; y < height; y++) {
@@ -65,9 +70,9 @@ export function decodePng(bytes: Uint8Array): Rgba {
     const src = y * (stride + 1) + 1;
     const row = y * stride;
     for (let x = 0; x < stride; x++) {
-      const a = x >= ch ? (px[row + x - ch] ?? 0) : 0;
+      const a = x >= bpp ? (px[row + x - bpp] ?? 0) : 0;
       const b = y > 0 ? (px[row - stride + x] ?? 0) : 0;
-      const c = x >= ch && y > 0 ? (px[row - stride + x - ch] ?? 0) : 0;
+      const c = x >= bpp && y > 0 ? (px[row - stride + x - bpp] ?? 0) : 0;
       const v = raw[src + x] ?? 0;
       const pred =
         f === 1 ? a : f === 2 ? b : f === 3 ? (a + b) >> 1 : f === 4 ? paeth(a, b, c) : 0;
@@ -76,8 +81,9 @@ export function decodePng(bytes: Uint8Array): Rgba {
   }
   const data = new Uint8Array(width * height * 4);
   for (let i = 0; i < width * height; i++) {
-    const s = i * ch;
-    const g = px[s] ?? 0;
+    const s = i * bpp;
+    const at = (k: number): number => px[s + k * B] ?? 0;
+    const g = at(0);
     const o = i * 4;
     if (type === 3) {
       data[o] = palette[g * 3] ?? 0;
@@ -86,14 +92,14 @@ export function decodePng(bytes: Uint8Array): Rgba {
       data[o + 3] = trns[g] ?? 255;
     } else if (ch >= 3) {
       data[o] = g;
-      data[o + 1] = px[s + 1] ?? 0;
-      data[o + 2] = px[s + 2] ?? 0;
-      data[o + 3] = ch === 4 ? (px[s + 3] ?? 255) : 255;
+      data[o + 1] = at(1);
+      data[o + 2] = at(2);
+      data[o + 3] = ch === 4 ? at(3) : 255;
     } else {
       data[o] = g;
       data[o + 1] = g;
       data[o + 2] = g;
-      data[o + 3] = ch === 2 ? (px[s + 1] ?? 255) : 255;
+      data[o + 3] = ch === 2 ? at(1) : 255;
     }
   }
   return { width, height, data };