@developerz.ai/ts23d 0.0.0-stage → 0.2.0

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.2.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';

package/src/kinds/building.ts

@@ -0,0 +1,153 @@
+// Building helpers: masses, then details. A facade is a split-grammar line per floor and side;
+// `win`/`door`/`arch`/`shop` slots become openings, everything else stays wall. Plain mode: inset
+// glass/door panels. With `kit`: real openings (reveal, sill, lintel, sash, panelled door).
+
+import type { BuildContext, Vec3 } from '../core/index.ts';
+import { split } from '../grammar/index.ts';
+import type { StripId } from '../material/index.ts';
+import { box } from '../primitives/index.ts';
+import { opening } from './openings.ts';
+
+export type Side = 'front' | 'back' | 'left' | 'right';
+
+export interface FacadeOptions {
+  readonly prefix: string;
+  /** Centre of the mass's base. */
+  readonly at: Vec3;
+  /** Footprint width (X) and depth (Y) of the mass this facade wraps. */
+  readonly footprint: readonly [number, number];
+  readonly floors: number;
+  readonly floorHeight: number;
+  /** Grammar per floor; the same line for every floor unless `ground` overrides floor 0. */
+  readonly grammar: string;
+  readonly ground?: string;
+  readonly sides: readonly Side[];
+  readonly glass: Vec3;
+  readonly frame?: Vec3;
+  /** Window height as a fraction of the floor. */
+  readonly windowRatio?: number;
+  /** Detailed openings (see `opening`): reveal in the wall colour, stone sill/lintel, sash bars. */
+  readonly kit?: {
+    readonly wall: Vec3;
+    readonly trim?: Vec3;
+    readonly depth?: number;
+    readonly panes?: readonly [number, number];
+    /** The wall's strip, so reveals continue its courses. Default 'plain'. */
+    readonly strip?: StripId;
+  };
+}
+
+const OPENINGS = new Set(['win', 'door', 'arch', 'shop']);
+
+export function facade(ctx: BuildContext, o: FacadeOptions): void {
+  const [w, d] = o.footprint;
+  const ratio = o.windowRatio ?? 0.6;
+  const depth = 0.08;
+  for (const side of o.sides) {
+    const along = side === 'front' || side === 'back' ? d : w;
+    for (let f = 0; f < o.floors; f++) {
+      const line = f === 0 && o.ground ? o.ground : o.grammar;
+      const z = o.at[2] + f * o.floorHeight;
+      split(line, along).forEach((slot, i) => {
+        if (!OPENINGS.has(slot.symbol) || slot.size < 0.2) return;
+        const isDoor = slot.symbol === 'door' || slot.symbol === 'shop';
+        const h = isDoor ? o.floorHeight * 0.85 : o.floorHeight * ratio;
+        const sill = isDoor ? 0 : (o.floorHeight - h) / 2;
+        const c = slot.start + slot.size / 2 - along / 2;
+        const inset = slot.size * 0.85;
+        const pos: Vec3 =
+          side === 'front'
+            ? [o.at[0] + w / 2, o.at[1] + c, z + sill]
+            : side === 'back'
+              ? [o.at[0] - w / 2, o.at[1] - c, z + sill]
+              : side === 'left'
+                ? [o.at[0] - c, o.at[1] + d / 2, z + sill]
+                : [o.at[0] + c, o.at[1] - d / 2, z + sill];
+        const name = `${o.prefix}_${side}_${f}_${i}`;
+        if (o.kit) {
+          const k = o.kit;
+          ctx.part(
+            name,
+            opening(
+              {
+                kind: isDoor ? 'door' : 'window',
+                width: Math.max(0.3, inset - 0.2),
+                height: h - (isDoor ? 0.25 : 0.2),
+                at: pos,
+                facing: side,
+                glass: o.glass,
+                frame: o.frame ?? [0.92, 0.9, 0.85],
+                wall: k.wall,
+                ...(k.trim ? { trim: k.trim } : {}),
+                ...(k.depth !== undefined ? { depth: k.depth } : {}),
+                ...(k.panes ? { panes: k.panes } : {}),
+                ...(k.strip ? { wallStrip: k.strip } : {}),
+              },
+              ctx.lod,
+            ),
+          );
+          return;
+        }
+        const size: Vec3 =
+          side === 'front' || side === 'back' ? [depth, inset, h] : [inset, depth, h];
+        ctx.part(
+          name,
+          box({
+            size,
+            at: pos,
+            color: isDoor ? (o.frame ?? o.glass) : o.glass,
+            strip: 'glass',
+            omit: ['bottom'],
+          }),
+        );
+      });
+    }
+  }
+}
+
+export interface SetbackTier {
+  readonly footprint: readonly [number, number];
+  readonly floors: number;
+}
+
+/** Stack of shrinking masses (Empire State, Chrysler-style towers). Returns the top z. */
+export function setbacks(
+  ctx: BuildContext,
+  o: {
+    prefix: string;
+    tiers: readonly SetbackTier[];
+    floorHeight: number;
+    color: Vec3;
+    grammar: string;
+    glass: Vec3;
+    detail: boolean;
+  },
+): number {
+  let z = 0;
+  o.tiers.forEach((t, i) => {
+    const h = t.floors * o.floorHeight;
+    ctx.part(
+      `${o.prefix}_${i}`,
+      box({
+        size: [t.footprint[0], t.footprint[1], h],
+        at: [0, 0, z],
+        color: o.color,
+        strip: 'stone',
+        omit: i === 0 ? ['bottom'] : [],
+      }),
+    );
+    if (o.detail)
+      facade(ctx, {
+        prefix: `${o.prefix}_${i}_win`,
+        at: [0, 0, z],
+        footprint: t.footprint,
+        floors: t.floors,
+        floorHeight: o.floorHeight,
+        grammar: o.grammar,
+        sides: ['front', 'back', 'left', 'right'],
+        glass: o.glass,
+      });
+    z += h;
+  });
+  return z;
+}

package/src/kinds/faces.ts

@@ -0,0 +1,138 @@
+// Convex-polygon toolkit for the building kinds: half-plane clipping in plan, and emitting a flat
+// convex 3D polygon onto a trim strip AT TRUE SCALE. A strip tiles along U only, so the polygon is
+// cut into bands `scaleMetres` tall along its V direction (courses start on `vOrigin`); each band
+// maps V 0→1 across the strip. That is how slates run down a slope and bricks up a gable.
+
+import {
+  cross,
+  dot,
+  type MeshBuilder,
+  normalize,
+  sub,
+  type Vec2,
+  type Vec3,
+} from '../core/index.ts';
+import { DEFAULT_SHEET, type StripId, stripRect } from '../material/index.ts';
+
+const EPS = 1e-9;
+
+/** Keep the part of a convex polygon where the linear function `f` is ≤ 0. */
+export function clipPoly<P extends Vec2 | Vec3>(poly: readonly P[], f: (p: P) => number): P[] {
+  const out: P[] = [];
+  const n = poly.length;
+  for (let i = 0; i < n; i++) {
+    const a = poly[i];
+    const b = poly[(i + 1) % n];
+    if (a === undefined || b === undefined) continue;
+    const fa = f(a);
+    const fb = f(b);
+    if (fa <= EPS) out.push(a);
+    if (fa <= EPS !== fb <= EPS) {
+      const t = fa / (fa - fb);
+      out.push(a.map((v, k) => v + ((b[k] ?? v) - v) * t) as unknown as P);
+    }
+  }
+  return dedupe(out);
+}
+
+/** Drop consecutive duplicate points (clipping through a vertex emits it twice). */
+export function dedupe<P extends Vec2 | Vec3>(poly: readonly P[]): P[] {
+  const out: P[] = [];
+  for (const p of poly) {
+    const q = out.at(-1);
+    if (!q || p.some((v, k) => Math.abs(v - (q[k] ?? 0)) > 1e-7)) out.push(p);
+  }
+  const first = out[0];
+  const last = out.at(-1);
+  if (out.length > 1 && first && last && first.every((v, k) => Math.abs(v - (last[k] ?? 0)) < 1e-7))
+    out.pop();
+  return out;
+}
+
+/** Signed area of a 2D polygon (CCW positive). */
+export const area2 = (poly: readonly Vec2[]): number =>
+  poly.reduce((s, a, i) => {
+    const b = poly[(i + 1) % poly.length] ?? a;
+    return s + a[0] * b[1] - b[0] * a[1];
+  }, 0) / 2;
+
+/** Vertical extent of one band (one full V of the strip) in metres, from the house sheet. */
+export const stripScale = (strip: StripId): number => DEFAULT_SHEET.strips[strip]?.scaleMetres ?? 1;
+
+export interface FaceOptions {
+  /** Convex and planar; either winding (it is turned to face `normal`). */
+  readonly points: readonly Vec3[];
+  readonly normal: Vec3;
+  /** Direction V grows along (up a slope, up a wall); projected into the face plane. */
+  readonly up: Vec3;
+  /** A point on the line where courses start (eave, wall foot). */
+  readonly vOrigin: Vec3;
+  readonly color: Vec3 | ((p: Vec3) => Vec3);
+  readonly strip: StripId;
+  /** false: one polygon, V squeezed over the whole face (far LODs). Default true. */
+  readonly banded?: boolean;
+}
+
+/** Emit a convex face into `b`, banded at the strip's true scale. Returns triangles added. */
+export function emitFace(b: MeshBuilder, o: FaceOptions): number {
+  if (o.points.length < 3) return 0;
+  const n = normalize(o.normal);
+  const points = dot(newell(o.points), n) < 0 ? [...o.points].reverse() : o.points;
+  const vDir = normalize(sub(o.up, scaleV(n, dot(o.up, n))));
+  const uDir = cross(vDir, n);
+  const rect = stripRect(o.strip);
+  const scale = stripScale(o.strip);
+  const vOf = (p: Vec3): number => dot(sub(p, o.vOrigin), vDir);
+  const vs = points.map(vOf);
+  const lo = Math.min(...vs);
+  const hi = Math.max(...vs);
+  if (hi - lo < 1e-6) return 0;
+  const colour = (p: Vec3): Vec3 => (typeof o.color === 'function' ? o.color(p) : o.color);
+  const bands: [number, number][] = [];
+  if (o.banded === false) bands.push([lo, hi]);
+  else {
+    for (let k = Math.floor(lo / scale + 1e-9); k * scale < hi - 1e-9; k++) {
+      bands.push([k * scale, (k + 1) * scale]);
+    }
+  }
+  let tris = 0;
+  for (const [v0, v1] of bands) {
+    const span = v1 - v0;
+    const poly = clipPoly(
+      clipPoly(points, (p) => v0 - vOf(p)),
+      (p) => vOf(p) - v1,
+    );
+    if (poly.length < 3) continue;
+    const ids = poly.map((p) => {
+      const f = Math.min(1, Math.max(0, (vOf(p) - v0) / span));
+      return b.vertex({
+        p,
+        n,
+        uv: [
+          rect.u0 + (dot(p, uDir) / rect.metres) * (rect.u1 - rect.u0),
+          rect.v0 + f * (rect.v1 - rect.v0),
+        ],
+        color: colour(p),
+      });
+    });
+    const first = ids[0] ?? 0;
+    for (let i = 1; i + 1 < ids.length; i++) b.tri(first, ids[i] ?? 0, ids[i + 1] ?? 0);
+    tris += ids.length - 2;
+  }
+  return tris;
+}
+
+/** Newell's polygon normal (unnormalised): robust for any planar polygon. */
+export function newell(poly: readonly Vec3[]): Vec3 {
+  const n: [number, number, number] = [0, 0, 0];
+  for (let i = 0; i < poly.length; i++) {
+    const a = poly[i] ?? [0, 0, 0];
+    const b = poly[(i + 1) % poly.length] ?? a;
+    n[0] += (a[1] - b[1]) * (a[2] + b[2]);
+    n[1] += (a[2] - b[2]) * (a[0] + b[0]);
+    n[2] += (a[0] - b[0]) * (a[1] + b[1]);
+  }
+  return n;
+}
+
+const scaleV = (v: Vec3, s: number): Vec3 => [v[0] * s, v[1] * s, v[2] * s];