@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/src/export/metadata.ts

@@ -0,0 +1,59 @@
+// Provenance inside the file: `asset.generator` with the version, `asset.copyright`, and an XMP
+// packet (KHR_xmp_json_ld, Ratified) with title, description, creators, rights, licence and the
+// recipe's sources — what Sketchfab, Blender and asset stores read. No dates: bytes stay
+// deterministic.
+
+import type { Json } from './bin-writer.ts';
+import { GENERATOR } from './version.ts';
+
+export interface GlbMeta {
+  /** Default: the asset name. */
+  readonly title?: string;
+  readonly description?: string;
+  readonly creators?: readonly string[];
+  /** Goes to `asset.copyright` and `dc:rights`, e.g. "© 2026 Jane Doe". */
+  readonly copyright?: string;
+  /** SPDX id or licence URL → `xmpRights:UsageTerms`, e.g. "CC-BY-4.0". */
+  readonly license?: string;
+  /** Where the numbers came from (the recipe's `sources`) → `dc:relation`. */
+  readonly sources?: readonly string[];
+}
+
+const XMP = 'KHR_xmp_json_ld';
+const alt = (value: string): Json => ({
+  '@type': 'rdf:Alt',
+  'rdf:_1': { '@language': 'x-default', '@value': value },
+});
+
+/** `asset` block, plus root `extensions` and the extension name when an XMP packet is written. */
+export function metadata(
+  name: string,
+  meta: GlbMeta | undefined,
+): { asset: Json; extensions?: Json; used: string[] } {
+  const asset: Json = {
+    version: '2.0',
+    generator: GENERATOR,
+    ...(meta?.copyright ? { copyright: meta.copyright } : {}),
+  };
+  if (!meta) return { asset, used: [] };
+  const packet: Json = {
+    '@context': {
+      dc: 'http://purl.org/dc/elements/1.1/',
+      rdf: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#',
+      xmp: 'http://ns.adobe.com/xap/1.0/',
+      xmpRights: 'http://ns.adobe.com/xap/1.0/rights/',
+    },
+    'dc:title': alt(meta.title ?? name),
+    ...(meta.description ? { 'dc:description': alt(meta.description) } : {}),
+    ...(meta.creators?.length ? { 'dc:creator': { '@list': [...meta.creators] } } : {}),
+    ...(meta.copyright ? { 'dc:rights': alt(meta.copyright) } : {}),
+    ...(meta.license ? { 'xmpRights:UsageTerms': alt(meta.license) } : {}),
+    ...(meta.sources?.length ? { 'dc:relation': { '@set': [...meta.sources] } } : {}),
+    'xmp:CreatorTool': GENERATOR,
+  };
+  return {
+    asset: { ...asset, extensions: { [XMP]: { packet: 0 } } },
+    extensions: { [XMP]: { packets: [packet] } },
+    used: [XMP],
+  };
+}

package/src/export/motion.ts

@@ -0,0 +1,70 @@
+// Bakes a part's Motion into one glTF sampler + channel of the looping `run` clip.
+// Seamless by construction: every motion is rounded to a WHOLE number of cycles over the clip,
+// so the last key equals the first (a 0.8 rps wheel over 4 s = 3 turns, not 3.2 — no jump at
+// the loop point). Spins get ≥ 12 keys per turn so LINEAR quaternion interpolation never takes
+// the short way round. Time arrays are shared between channels of equal key count.
+
+import type { Motion } from '../core/index.ts';
+import { quatFromAxisAngle } from '../core/index.ts';
+import type { BinWriter, Json } from './bin-writer.ts';
+
+export const LOOP_SECONDS = 4;
+
+/** Whole cycles of `rate` (Hz or rev/s) over the clip, at least one. */
+export const cyclesOf = (rate: number): number =>
+  Math.max(1, Math.round(Math.abs(rate) * LOOP_SECONDS)) * Math.sign(rate || 1);
+
+const timeAccessors = new WeakMap<BinWriter, Map<number, number>>();
+function times(bin: BinWriter, keys: number): { input: number; t: Float32Array } {
+  const t = new Float32Array(keys + 1).map((_, i) => (i / keys) * LOOP_SECONDS);
+  const byBin = timeAccessors.get(bin) ?? new Map<number, number>();
+  timeAccessors.set(bin, byBin);
+  let input = byBin.get(keys);
+  if (input === undefined) {
+    input = bin.accessor(t, 'SCALAR', undefined, true);
+    byBin.set(keys, input);
+  }
+  return { input, t };
+}
+
+export function motionChannel(
+  bin: BinWriter,
+  motion: Motion,
+  node: number,
+  rest: readonly number[],
+): { sampler: Json; channel: Json } {
+  const rate = motion.kind === 'spin' ? motion.rps : motion.hz;
+  const cycles = cyclesOf(rate);
+  const keys = Math.max(24, Math.abs(cycles) * (motion.kind === 'spin' ? 12 : 16));
+  const { input, t } = times(bin, keys);
+  const phase = (time: number): number => (time / LOOP_SECONDS) * cycles * Math.PI * 2;
+  // Two-sided: −1..1 around rest. One-way: 0..1, starting and ending at rest (seamless loop).
+  const wave = (time: number): number =>
+    motion.kind !== 'spin' && motion.oneWay
+      ? (1 - Math.cos(phase(time))) / 2
+      : Math.sin(phase(time));
+  if (motion.kind === 'slide') {
+    const values = new Float32Array((keys + 1) * 3);
+    t.forEach((time, i) => {
+      const s = wave(time);
+      values.set(
+        [0, 1, 2].map((k) => (rest[k] ?? 0) + (motion.offset[k] ?? 0) * s),
+        i * 3,
+      );
+    });
+    return {
+      sampler: { input, output: bin.accessor(values, 'VEC3'), interpolation: 'LINEAR' },
+      channel: { target: { node, path: 'translation' } },
+    };
+  }
+  const values = new Float32Array((keys + 1) * 4);
+  const peak = motion.kind === 'sway' ? (motion.degrees * Math.PI) / 180 : 0;
+  t.forEach((time, i) => {
+    const angle = motion.kind === 'spin' ? phase(time) : peak * wave(time);
+    values.set(quatFromAxisAngle(motion.axis, angle), i * 4);
+  });
+  return {
+    sampler: { input, output: bin.accessor(values, 'VEC4'), interpolation: 'LINEAR' },
+    channel: { target: { node, path: 'rotation' } },
+  };
+}

package/src/export/optimize-parts.ts

@@ -0,0 +1,80 @@
+// Runs the mesh optimiser (passes/optimize: weld → vertex cache → vertex fetch) over every part
+// headed for the GLB, and sums what it did into one report the CLI and manifest can print.
+
+import type { CompiledAsset } from '../core/index.ts';
+import { type OptimizeOptions, type OptimizeReport, optimize } from '../passes/index.ts';
+
+export interface PartOptimizeReport extends OptimizeReport {
+  readonly part: string;
+}
+
+/** Totals over all parts; ACMR/ATVR are triangle-weighted means. */
+export interface ExportReport {
+  readonly optimized: boolean;
+  readonly verticesBefore: number;
+  readonly verticesAfter: number;
+  readonly trianglesBefore: number;
+  readonly trianglesAfter: number;
+  readonly degenerate: number;
+  readonly duplicate: number;
+  readonly acmrBefore: number;
+  readonly acmr: number;
+  readonly atvrBefore: number;
+  readonly atvr: number;
+  readonly parts: readonly PartOptimizeReport[];
+}
+
+export function summarize(parts: readonly PartOptimizeReport[], optimized: boolean): ExportReport {
+  const sum = (f: (r: PartOptimizeReport) => number): number => parts.reduce((s, r) => s + f(r), 0);
+  const tb = sum((r) => r.trianglesBefore);
+  const ta = sum((r) => r.trianglesAfter);
+  const mean = (f: (r: PartOptimizeReport) => number, by: number, w: 'b' | 'a'): number =>
+    by ? sum((r) => f(r) * (w === 'b' ? r.trianglesBefore : r.trianglesAfter)) / by : 0;
+  return {
+    optimized,
+    verticesBefore: sum((r) => r.verticesBefore),
+    verticesAfter: sum((r) => r.verticesAfter),
+    trianglesBefore: tb,
+    trianglesAfter: ta,
+    degenerate: sum((r) => r.degenerate),
+    duplicate: sum((r) => r.duplicate),
+    acmrBefore: mean((r) => r.acmrBefore, tb, 'b'),
+    acmr: mean((r) => r.acmr, ta, 'a'),
+    atvrBefore: mean((r) => r.atvrBefore, tb, 'b'),
+    atvr: mean((r) => r.atvr, ta, 'a'),
+    parts,
+  };
+}
+
+/** Optimise every part mesh. `false` passes meshes through and reports them as-is. */
+export function optimizeParts(
+  asset: CompiledAsset,
+  o: OptimizeOptions | false,
+): { asset: CompiledAsset; report: ExportReport } {
+  const reports: PartOptimizeReport[] = [];
+  const parts = asset.parts.map((p) => {
+    if (!p.mesh || p.mesh.indices.length === 0) return p;
+    if (o === false) {
+      const v = p.mesh.positions.length / 3;
+      const t = p.mesh.indices.length / 3;
+      reports.push({
+        part: p.name,
+        verticesBefore: v,
+        verticesAfter: v,
+        trianglesBefore: t,
+        trianglesAfter: t,
+        degenerate: 0,
+        duplicate: 0,
+        acmrBefore: 0,
+        acmr: 0,
+        atvrBefore: 0,
+        atvr: 0,
+      });
+      return p;
+    }
+    const { mesh, report } = optimize(p.mesh, o);
+    reports.push({ part: p.name, ...report });
+    return { ...p, mesh };
+  });
+  return { asset: { ...asset, parts }, report: summarize(reports, o !== false) };
+}

package/src/export/primitive.ts

@@ -0,0 +1,35 @@
+// One mesh → one glTF primitive: POSITION (with bounds), NORMAL, TEXCOORD_0, COLOR_0 as unorm16
+// RGBA, TANGENT only when a normal map is bound, and the smallest index type that fits.
+
+import type { Mesh } from '../core/index.ts';
+import { ARRAY_BUFFER, type BinWriter, ELEMENT_ARRAY_BUFFER, type Json } from './bin-writer.ts';
+import { tangentsOf } from './tangents.ts';
+
+export function writePrimitive(bin: BinWriter, m: Mesh, material: number, tangents: boolean): Json {
+  // COLOR_0 as normalised unsigned short RGBA: 8 bytes/vertex instead of 16, no banding in
+  // darks (8-bit would). VEC4 because vertex attributes must be 4-byte aligned.
+  const colors = new Uint16Array((m.colors.length / 3) * 4);
+  const q = (v: number): number => Math.round(Math.min(1, Math.max(0, v)) * 65535);
+  for (let i = 0; i < m.colors.length / 3; i++)
+    colors.set(
+      [q(m.colors[i * 3] ?? 1), q(m.colors[i * 3 + 1] ?? 1), q(m.colors[i * 3 + 2] ?? 1), 65535],
+      i * 4,
+    );
+  return {
+    attributes: {
+      POSITION: bin.accessor(m.positions, 'VEC3', ARRAY_BUFFER, true),
+      NORMAL: bin.accessor(m.normals, 'VEC3', ARRAY_BUFFER),
+      TEXCOORD_0: bin.accessor(m.uvs, 'VEC2', ARRAY_BUFFER),
+      COLOR_0: bin.accessor(colors, 'VEC4', ARRAY_BUFFER, false, true),
+      // A bound normal map needs a tangent space (validator S10 / G15).
+      ...(tangents ? { TANGENT: bin.accessor(tangentsOf(m), 'VEC4', ARRAY_BUFFER) } : {}),
+    },
+    // 16-bit indices whenever the primitive allows: half the bytes, every engine reads them.
+    indices: bin.accessor(
+      m.positions.length / 3 <= 65535 ? Uint16Array.from(m.indices) : m.indices,
+      'SCALAR',
+      ELEMENT_ARRAY_BUFFER,
+    ),
+    material,
+  };
+}

package/src/export/tangents.ts

@@ -0,0 +1,75 @@
+// Per-vertex tangents (glTF TANGENT, VEC4) for normal-mapped meshes: Lengyel's UV-derivative
+// method, Gram-Schmidt against the vertex normal, w = handedness. The bitangent cross(N, T) · w
+// points toward DECREASING glTF v (the "green up" convention the painter writes). Identical to
+// MikkTSpace on flat-shaded quads; close, not bit-equal, on smooth curved surfaces.
+
+import type { Mesh } from '../core/index.ts';
+
+export function tangentsOf(m: Mesh): Float32Array {
+  const n = m.positions.length / 3;
+  const tan = new Float32Array(n * 3);
+  const bit = new Float32Array(n * 3);
+  const P = m.positions;
+  const U = m.uvs;
+  for (let t = 0; t < m.indices.length; t += 3) {
+    const a = m.indices[t] ?? 0;
+    const b = m.indices[t + 1] ?? 0;
+    const c = m.indices[t + 2] ?? 0;
+    const e1x = (P[b * 3] ?? 0) - (P[a * 3] ?? 0);
+    const e1y = (P[b * 3 + 1] ?? 0) - (P[a * 3 + 1] ?? 0);
+    const e1z = (P[b * 3 + 2] ?? 0) - (P[a * 3 + 2] ?? 0);
+    const e2x = (P[c * 3] ?? 0) - (P[a * 3] ?? 0);
+    const e2y = (P[c * 3 + 1] ?? 0) - (P[a * 3 + 1] ?? 0);
+    const e2z = (P[c * 3 + 2] ?? 0) - (P[a * 3 + 2] ?? 0);
+    const du1 = (U[b * 2] ?? 0) - (U[a * 2] ?? 0);
+    const dv1 = -((U[b * 2 + 1] ?? 0) - (U[a * 2 + 1] ?? 0));
+    const du2 = (U[c * 2] ?? 0) - (U[a * 2] ?? 0);
+    const dv2 = -((U[c * 2 + 1] ?? 0) - (U[a * 2 + 1] ?? 0));
+    const det = du1 * dv2 - du2 * dv1;
+    if (Math.abs(det) < 1e-12) continue;
+    const r = 1 / det;
+    const tx = (e1x * dv2 - e2x * dv1) * r;
+    const ty = (e1y * dv2 - e2y * dv1) * r;
+    const tz = (e1z * dv2 - e2z * dv1) * r;
+    const bx = (e2x * du1 - e1x * du2) * r;
+    const by = (e2y * du1 - e1y * du2) * r;
+    const bz = (e2z * du1 - e1z * du2) * r;
+    for (const v of [a, b, c]) {
+      tan[v * 3] = (tan[v * 3] ?? 0) + tx;
+      tan[v * 3 + 1] = (tan[v * 3 + 1] ?? 0) + ty;
+      tan[v * 3 + 2] = (tan[v * 3 + 2] ?? 0) + tz;
+      bit[v * 3] = (bit[v * 3] ?? 0) + bx;
+      bit[v * 3 + 1] = (bit[v * 3 + 1] ?? 0) + by;
+      bit[v * 3 + 2] = (bit[v * 3 + 2] ?? 0) + bz;
+    }
+  }
+  const out = new Float32Array(n * 4);
+  for (let v = 0; v < n; v++) {
+    const nx = m.normals[v * 3] ?? 0;
+    const ny = m.normals[v * 3 + 1] ?? 0;
+    const nz = m.normals[v * 3 + 2] ?? 1;
+    let tx = tan[v * 3] ?? 0;
+    let ty = tan[v * 3 + 1] ?? 0;
+    let tz = tan[v * 3 + 2] ?? 0;
+    const d = nx * tx + ny * ty + nz * tz;
+    tx -= nx * d;
+    ty -= ny * d;
+    tz -= nz * d;
+    let len = Math.hypot(tx, ty, tz);
+    if (len < 1e-8) {
+      // No usable UV gradient: any unit vector perpendicular to the normal.
+      [tx, ty, tz] = Math.abs(nx) < 0.9 ? [0, -nz, ny] : [nz, 0, -nx];
+      len = Math.hypot(tx, ty, tz) || 1;
+    }
+    tx /= len;
+    ty /= len;
+    tz /= len;
+    // Handedness: does cross(N, T) agree with the accumulated bitangent?
+    const cx = ny * tz - nz * ty;
+    const cy = nz * tx - nx * tz;
+    const cz = nx * ty - ny * tx;
+    const w = cx * (bit[v * 3] ?? 0) + cy * (bit[v * 3 + 1] ?? 0) + cz * (bit[v * 3 + 2] ?? 0);
+    out.set([tx, ty, tz, w < 0 ? -1 : 1], v * 4);
+  }
+  return out;
+}

package/src/export/textures.ts

@@ -0,0 +1,88 @@
+// The trim sheet in glTF: three images (albedo sRGB, normal + ORM linear), three textures and one
+// sampler (REPEAT along U so strips tile, CLAMP along V so the atlas never wraps rows, trilinear
+// mips). Embedded: PNGs ride in the BIN chunk after the geometry (self-contained single files).
+// External: images reference `<prefix>_{albedo,normal,orm}.png` by URI, so fifty assets share one
+// texture set on disk and in GPU memory — the point of the trim sheet. Write the PNGs once with
+// `sheetPngs`. Texture indices are fixed: 0 albedo, 1 normal, 2 ORM (materials.ts binds them).
+
+import { encodePng } from '../core/index.ts';
+import type { PaintedSheet } from '../material/index.ts';
+import type { Json } from './bin-writer.ts';
+
+export type SheetMap = 'albedo' | 'normal' | 'orm';
+export const SHEET_MAPS: readonly SheetMap[] = ['albedo', 'normal', 'orm'];
+
+/** Reference a shared sheet by URI instead of embedding it. */
+export interface ExternalSheet {
+  readonly external: true;
+  /** URI prefix relative to the .glb, e.g. `../textures/trim_sheet`. Default `trim_sheet`. */
+  readonly prefix?: string;
+}
+
+export type SheetBinding = PaintedSheet | ExternalSheet;
+
+export const sheetFileName = (map: SheetMap, prefix = 'trim_sheet'): string =>
+  `${prefix}_${map}.png`;
+
+const LINEAR = 9729;
+const LINEAR_MIPMAP_LINEAR = 9987;
+const REPEAT = 10497;
+const CLAMP_TO_EDGE = 33071;
+
+const pngCache = new WeakMap<PaintedSheet, Readonly<Record<SheetMap, Uint8Array>>>();
+
+/** PNG bytes of each map, encoded once per sheet (every LOD's GLB reuses them). */
+export function sheetPngs(sheet: PaintedSheet): Readonly<Record<SheetMap, Uint8Array>> {
+  const hit = pngCache.get(sheet);
+  if (hit) return hit;
+  const pngs = {
+    albedo: encodePng(sheet.size, sheet.size, sheet.albedo),
+    normal: encodePng(sheet.size, sheet.size, sheet.normal),
+    orm: encodePng(sheet.size, sheet.size, sheet.orm),
+  };
+  pngCache.set(sheet, pngs);
+  return pngs;
+}
+
+const isExternal = (s: SheetBinding): s is ExternalSheet => 'external' in s;
+
+/**
+ * glTF `images` / `textures` / `samplers` for the sheet. Embedded image bytes are returned as
+ * `tail`, to append to the BIN chunk at `offset` (4-aligned); their bufferViews go into `views`.
+ */
+export function sheetGltf(
+  sheet: SheetBinding,
+  views: Json[],
+  offset: number,
+): { json: Json; tail: Uint8Array } {
+  const textures = SHEET_MAPS.map((_, i) => ({ sampler: 0, source: i }));
+  const samplers = [
+    { magFilter: LINEAR, minFilter: LINEAR_MIPMAP_LINEAR, wrapS: REPEAT, wrapT: CLAMP_TO_EDGE },
+  ];
+  if (isExternal(sheet)) {
+    const images = SHEET_MAPS.map((m) => ({
+      name: `trim_sheet_${m}`,
+      uri: sheetFileName(m, sheet.prefix),
+    }));
+    return { json: { images, textures, samplers }, tail: new Uint8Array() };
+  }
+  const pngs = sheetPngs(sheet);
+  const parts: Uint8Array[] = [];
+  const images: Json[] = [];
+  let at = offset;
+  for (const m of SHEET_MAPS) {
+    const png = pngs[m];
+    views.push({ buffer: 0, byteOffset: at, byteLength: png.byteLength });
+    images.push({ name: `trim_sheet_${m}`, bufferView: views.length - 1, mimeType: 'image/png' });
+    const pad = (4 - (png.byteLength % 4)) % 4;
+    parts.push(png, new Uint8Array(pad));
+    at += png.byteLength + pad;
+  }
+  const tail = new Uint8Array(at - offset);
+  let o = 0;
+  for (const p of parts) {
+    tail.set(p, o);
+    o += p.byteLength;
+  }
+  return { json: { images, textures, samplers }, tail };
+}

package/src/export/version.ts

@@ -0,0 +1,6 @@
+// The package version written into every GLB (`asset.generator`, XMP CreatorTool). Kept as a
+// constant because the library may not import package.json (rootDir is src); version.test.ts
+// fails the gate when the two disagree, and `bun run release` stamps both.
+
+export const VERSION = '0.1.0';
+export const GENERATOR = `@developerz.ai/ts23d ${VERSION}`;

package/src/grammar/index.ts

@@ -0,0 +1,4 @@
+// Public API of @ts23d/grammar: string mini-languages that a recipe calls from TypeScript.
+
+export { layoutSplit, parseSplit, type Slot, type SplitTerm, split } from './split.ts';
+export { parseWhyte, type WheelGroup } from './whyte.ts';

package/src/grammar/split.ts

@@ -0,0 +1,87 @@
+// Split grammar (after CGA shape, Müller et al. 2006): one line lays out a facade strip.
+//   "pier:0.9 | {arch:2.5}* | door:3 | pier:~"
+//   x:n fixed width · {a:n | b:m}* repeat to fill · x:~ stretch (shares leftover equally)
+
+import { Ts23dError } from '../core/index.ts';
+
+export type SplitTerm =
+  | { readonly kind: 'fixed'; readonly symbol: string; readonly size: number }
+  | { readonly kind: 'stretch'; readonly symbol: string; readonly weight: number }
+  | { readonly kind: 'repeat'; readonly body: readonly SplitTerm[] };
+
+export interface Slot {
+  readonly symbol: string;
+  readonly start: number;
+  readonly size: number;
+}
+
+const syntax = (src: string, why: string): Ts23dError =>
+  new Ts23dError('T3D_GRAMMAR_SYNTAX', {
+    cause: `cannot parse split "${src}": ${why}`,
+    fix: 'use `sym:<metres>`, `sym:~`, `sym:~<weight>` or `{a:1 | b:2}*`, separated by `|`',
+  });
+
+function parseTerm(raw: string, src: string): SplitTerm {
+  const t = raw.trim();
+  const m = /^([a-z_][a-z0-9_]*):(~(\d*\.?\d+)?|\d*\.?\d+)$/.exec(t);
+  if (!m) throw syntax(src, `bad term '${t}'`);
+  const [, symbol = '', size = ''] = m;
+  if (size.startsWith('~')) return { kind: 'stretch', symbol, weight: m[3] ? Number(m[3]) : 1 };
+  return { kind: 'fixed', symbol, size: Number(size) };
+}
+
+export function parseSplit(src: string): SplitTerm[] {
+  const out: SplitTerm[] = [];
+  const re = /\{([^}]*)\}\*|([^|{}]+)/g;
+  for (const m of src.matchAll(re)) {
+    if (m[1] !== undefined) {
+      const body = m[1].split('|').map((s) => parseTerm(s, src));
+      if (body.some((b) => b.kind !== 'fixed'))
+        throw syntax(src, 'a repeat body takes fixed sizes');
+      out.push({ kind: 'repeat', body });
+    } else if (m[2] !== undefined && m[2].trim() !== '') {
+      out.push(parseTerm(m[2], src));
+    }
+  }
+  if (out.length === 0) throw syntax(src, 'empty');
+  if (out.filter((t) => t.kind === 'repeat').length > 1) throw syntax(src, 'at most one repeat');
+  return out;
+}
+
+const sizeOf = (terms: readonly SplitTerm[]): number =>
+  terms.reduce((s, t) => s + (t.kind === 'fixed' ? t.size : 0), 0);
+
+/** Lay a parsed split across `length` metres. Repeats take whole copies; stretches share the rest. */
+export function layoutSplit(terms: readonly SplitTerm[], length: number): Slot[] {
+  const fixed = sizeOf(terms);
+  const repeat = terms.find((t) => t.kind === 'repeat');
+  const unit = repeat?.kind === 'repeat' ? sizeOf(repeat.body) : 0;
+  if (fixed > length + 1e-9) {
+    throw new Ts23dError('T3D_GRAMMAR_OVERFLOW', {
+      cause: `fixed terms need ${fixed} m but the strip is ${length} m`,
+      fix: 'shrink a fixed term, or turn one into a stretch (`sym:~`)',
+    });
+  }
+  const copies = unit > 0 ? Math.floor((length - fixed) / unit) : 0;
+  const weights = terms.reduce((s, t) => s + (t.kind === 'stretch' ? t.weight : 0), 0);
+  const leftover = length - fixed - copies * unit;
+  // No stretch term: the repeat absorbs the leftover by widening each copy evenly.
+  const grow = weights === 0 && copies > 0 ? (copies * unit + leftover) / (copies * unit) : 1;
+  const slots: Slot[] = [];
+  let x = 0;
+  const push = (symbol: string, size: number): void => {
+    slots.push({ symbol, start: x, size });
+    x += size;
+  };
+  for (const t of terms) {
+    if (t.kind === 'fixed') push(t.symbol, t.size);
+    else if (t.kind === 'stretch')
+      push(t.symbol, weights > 0 ? (leftover * t.weight) / weights : 0);
+    else
+      for (let i = 0; i < copies; i++)
+        for (const b of t.body) if (b.kind === 'fixed') push(b.symbol, b.size * grow);
+  }
+  return slots;
+}
+
+export const split = (src: string, length: number): Slot[] => layoutSplit(parseSplit(src), length);

package/src/grammar/whyte.ts

@@ -0,0 +1,20 @@
+// Whyte notation ("4-4-0", "2-6-2") → wheel groups. Domain-native params: the loco kind reads it.
+
+import { Ts23dError } from '../core/index.ts';
+
+export interface WheelGroup {
+  readonly role: 'leading' | 'driving' | 'trailing';
+  readonly count: number;
+}
+
+export function parseWhyte(arrangement: string): WheelGroup[] {
+  const parts = arrangement.split('-').map(Number);
+  if (parts.length !== 3 || parts.some((n) => !Number.isInteger(n) || n < 0 || n % 2 !== 0)) {
+    throw new Ts23dError('T3D_GRAMMAR_SYNTAX', {
+      cause: `'${arrangement}' is not a rigid-frame Whyte arrangement`,
+      fix: "use three even numbers: leading-driving-trailing, e.g. '4-4-0' or '2-8-2'",
+    });
+  }
+  const roles = ['leading', 'driving', 'trailing'] as const;
+  return roles.map((role, i) => ({ role, count: parts[i] ?? 0 }));
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// @developerz.ai/ts23d — the whole DSL from one import. Subpaths (`/core`, `/grammar`, …) exist for
+// tree-shaking and for reading one layer at a time.
+
+export { type AssetManifest, manifestOf } from './cli/manifest.ts';
+export * from './core/index.ts';
+export * from './export/index.ts';
+export * from './grammar/index.ts';
+export * from './kinds/index.ts';
+export * from './material/index.ts';
+export * from './neural/index.ts';
+export * from './passes/index.ts';
+export * from './primitives/index.ts';
+export * from './qa/index.ts';
+export * from './render/index.ts';