@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/render/vis-buffer.ts

@@ -0,0 +1,119 @@
+// Visibility buffer: perspective-rasterise every triangle once, keeping only the nearest triangle
+// id and its perspective-correct barycentrics per pixel. Shading then runs exactly once per pixel
+// (deferred), so overdraw on an 88k-triangle tank costs a depth compare, not a lighting model.
+
+import type { PerspectiveCamera } from './camera.ts';
+import type { Scene } from './scene.ts';
+
+export interface VisBuffer {
+  readonly width: number;
+  readonly height: number;
+  /** Triangle id per pixel, −1 = background. */
+  readonly tri: Int32Array;
+  /** Perspective-correct barycentrics of vertices 1 and 2 (vertex 0 = 1 − b1 − b2). */
+  readonly b1: Float32Array;
+  readonly b2: Float32Array;
+  /** 1 / view depth (larger = nearer). */
+  readonly invw: Float32Array;
+  /** Per-triangle texture mip level from its texel : pixel footprint. */
+  readonly mip: Uint8Array;
+}
+
+/** Return false to discard a fragment (alpha-tested cutouts). */
+export type AlphaTest = (tri: number, b1: number, b2: number, mip: number) => boolean;
+
+export function rasteriseVis(
+  s: Scene,
+  cam: PerspectiveCamera,
+  texSize: number,
+  alpha?: AlphaTest,
+): VisBuffer {
+  const W = cam.width;
+  const H = cam.height;
+  const n = W * H;
+  const tri = new Int32Array(n).fill(-1);
+  const b1 = new Float32Array(n);
+  const b2 = new Float32Array(n);
+  const invw = new Float32Array(n);
+  const nv = s.positions.length / 3;
+  const sx = new Float32Array(nv);
+  const sy = new Float32Array(nv);
+  const iw = new Float32Array(nv);
+  const P = s.positions;
+  const [ex, ey, ez] = cam.eye;
+  for (let v = 0; v < nv; v++) {
+    const dx = (P[v * 3] ?? 0) - ex;
+    const dy = (P[v * 3 + 1] ?? 0) - ey;
+    const dz = (P[v * 3 + 2] ?? 0) - ez;
+    const w = dx * cam.f[0] + dy * cam.f[1] + dz * cam.f[2];
+    const q = w > 1e-4 ? 1 / w : -1;
+    iw[v] = q;
+    sx[v] = cam.cx + (dx * cam.r[0] + dy * cam.r[1] + dz * cam.r[2]) * q * cam.focal;
+    sy[v] = cam.cy - (dx * cam.u[0] + dy * cam.u[1] + dz * cam.u[2]) * q * cam.focal;
+  }
+  const mip = new Uint8Array(s.triangles);
+  const I = s.indices;
+  const UV = s.uvs;
+  for (let t = 0; t < s.triangles; t++) {
+    const a = I[t * 3] ?? 0;
+    const b = I[t * 3 + 1] ?? 0;
+    const c = I[t * 3 + 2] ?? 0;
+    const qa = iw[a] ?? -1;
+    const qb = iw[b] ?? -1;
+    const qc = iw[c] ?? -1;
+    if (qa < 0 || qb < 0 || qc < 0) continue;
+    const ax = sx[a] ?? 0;
+    const ay = sy[a] ?? 0;
+    const bx = sx[b] ?? 0;
+    const by = sy[b] ?? 0;
+    const cx = sx[c] ?? 0;
+    const cy = sy[c] ?? 0;
+    const area = (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+    if (Math.abs(area) < 1e-12) continue;
+    const uvArea = Math.abs(
+      ((UV[b * 2] ?? 0) - (UV[a * 2] ?? 0)) * ((UV[c * 2 + 1] ?? 0) - (UV[a * 2 + 1] ?? 0)) -
+        ((UV[b * 2 + 1] ?? 0) - (UV[a * 2 + 1] ?? 0)) * ((UV[c * 2] ?? 0) - (UV[a * 2] ?? 0)),
+    );
+    const lod = 0.5 * Math.log2((uvArea * texSize * texSize) / Math.abs(area) + 1e-12);
+    const m = Math.max(0, Math.min(10, Math.floor(lod + 0.25)));
+    mip[t] = m;
+    const lx = ax < bx ? Math.min(ax, cx) : Math.min(bx, cx);
+    const hx = ax > bx ? Math.max(ax, cx) : Math.max(bx, cx);
+    const ly = ay < by ? Math.min(ay, cy) : Math.min(by, cy);
+    const hy = ay > by ? Math.max(ay, cy) : Math.max(by, cy);
+    const minX = lx < 0 ? 0 : Math.floor(lx);
+    const maxX = hx > W - 1 ? W - 1 : Math.ceil(hx);
+    const minY = ly < 0 ? 0 : Math.floor(ly);
+    const maxY = hy > H - 1 ? H - 1 : Math.ceil(hy);
+    if (minX > maxX || minY > maxY) continue;
+    const inv = 1 / area;
+    const cut = alpha !== undefined && s.surface[t] === 1;
+    // Affine edge functions, stepped per pixel.
+    const A0 = (by - cy) * inv;
+    const B0 = (cx - bx) * inv;
+    const A1 = (cy - ay) * inv;
+    const B1 = (ax - cx) * inv;
+    const C0 = (bx * cy - by * cx) * inv;
+    const C1 = (cx * ay - cy * ax) * inv;
+    for (let y = minY; y <= maxY; y++) {
+      const py = y + 0.5;
+      let w0 = C0 + A0 * (minX + 0.5) + B0 * py;
+      let w1 = C1 + A1 * (minX + 0.5) + B1 * py;
+      for (let x = minX; x <= maxX; x++, w0 += A0, w1 += A1) {
+        const w2 = 1 - w0 - w1;
+        if (w0 < 0 || w1 < 0 || w2 < 0) continue;
+        const z = w0 * qa + w1 * qb + w2 * qc;
+        const i = y * W + x;
+        if (z <= (invw[i] ?? 0)) continue;
+        const pb = (w1 * qb) / z;
+        const pc = (w2 * qc) / z;
+        if (cut && alpha && !alpha(t, pb, pc, m)) continue;
+        invw[i] = z;
+        tri[i] = t;
+        b1[i] = pb;
+        b2[i] = pc;
+      }
+    }
+  }
+  return { width: W, height: H, tri, b1, b2, invw, mip };
+}

package/src/testing/assert.ts

@@ -0,0 +1,115 @@
+// Assertions for a recipe's own `bun test` (or any runner): each compiles the asset, checks one
+// property, and throws a Ts23dError with the findings and a fix — no test framework imported.
+//   it('passes QA', () => assertQaPass(tiger_1));
+//   it('has its pivots', () => assertParts(tiger_1, ['turret', 'gun', 'wheel_l_*']));
+
+import type { Asset, Lod, Measure } from '../core/index.ts';
+import {
+  clashes,
+  DEFAULT_GATES,
+  DEFAULT_LOD_GATES,
+  type Gate,
+  glob,
+  type LodGate,
+  measure,
+  runLodQa,
+  runQa,
+} from '../qa/index.ts';
+import { compileLods, failOn, type LodOptions } from './compiled.ts';
+
+export interface QaOptions extends LodOptions {
+  /** Per-LOD gates. Default the build's DEFAULT_GATES. */
+  readonly gates?: readonly Gate[];
+  /** Chain gates over all compiled LODs. Default DEFAULT_LOD_GATES. */
+  readonly lodGates?: readonly LodGate[];
+}
+
+/** The same gate `t3d build` runs: every LOD passes QA, plus the LOD-chain gates. */
+export function assertQaPass(asset: Asset, o: QaOptions = {}): void {
+  const lods = compileLods(asset, o);
+  const found = lods.flatMap((a) =>
+    runQa(a, o.gates ?? DEFAULT_GATES).map((finding) => ({ finding, lod: a.lod })),
+  );
+  const chain = lods.length > 1 ? runLodQa(lods, o.lodGates ?? DEFAULT_LOD_GATES) : [];
+  failOn(`${asset.name} QA`, [...found, ...chain.map((finding) => ({ finding }))]);
+}
+
+/** Triangles per LOD at or under `caps` (default: the asset's own budget). */
+export function assertBudget(
+  asset: Asset,
+  caps: readonly [number, number, number] = asset.budget.triangles,
+  o: LodOptions = {},
+): void {
+  failOn(
+    `${asset.name} budget`,
+    compileLods(asset, o).flatMap((a) => {
+      const tris = a.parts.reduce((s, p) => s + (p.mesh ? p.mesh.indices.length / 3 : 0), 0);
+      const cap = caps[a.lod];
+      return tris > cap
+        ? [
+            {
+              lod: a.lod,
+              finding: {
+                gate: 'budget',
+                message: `${tris} triangles > ${cap}`,
+                fix: 'drop detail at this LOD (ctx.lod / ctx.pick) — never raise a cap to make a test pass',
+              },
+            },
+          ]
+        : [];
+    }),
+  );
+}
+
+/** Each selector (name or glob) matches at least one part at every LOD checked. */
+export function assertParts(asset: Asset, selectors: readonly string[], o: LodOptions = {}): void {
+  failOn(
+    `${asset.name} parts`,
+    compileLods(asset, o).flatMap((a) =>
+      selectors
+        .filter((s) => !a.parts.some((p) => glob(s).test(p.name)))
+        .map((s) => ({
+          lod: a.lod,
+          finding: {
+            gate: 'parts',
+            message: `no part matches '${s}'`,
+            fix: 'engines bind to these names: add the part/group at this LOD (gate its geometry, not its pivot)',
+          },
+        })),
+    ),
+  );
+}
+
+/** One spec dimension at LOD0, the way the `measures` gate checks `real.measures`. */
+export function assertMeasure(asset: Asset, m: Measure, o: { lod?: Lod } = {}): number {
+  const [a] = compileLods(asset, { lods: [o.lod ?? 0] });
+  const got = a ? measure(a, m) : null;
+  const tol = m.tolerance ?? 0.02;
+  const bad = got === null || Math.abs(got - m.value) / m.value > tol;
+  failOn(
+    `${asset.name} measure`,
+    bad
+      ? [
+          {
+            finding: {
+              gate: 'measure',
+              message:
+                got === null
+                  ? `'${m.label}': no part matches ${JSON.stringify(m.parts ?? m.between)}`
+                  : `${m.label}: ${got.toFixed(3)} m on ${m.axis.toUpperCase()}, want ${m.value} m (±${tol * 100}%)`,
+              fix: 'rebuild the part from the spec number; never edit the spec to match the model',
+            },
+          },
+        ]
+      : [],
+  );
+  return got ?? Number.NaN;
+}
+
+/** Every moving part sweeps clear of everything else (the `clashes` gate), at every LOD. */
+export function assertMotionClear(asset: Asset, o: LodOptions = {}): void {
+  failOn(
+    `${asset.name} motion`,
+    compileLods(asset, o).flatMap((a) => clashes(a).map((finding) => ({ finding, lod: a.lod }))),
+  );
+}

package/src/testing/compiled.ts

@@ -0,0 +1,31 @@
+// Shared plumbing for the assertions: compile an asset at the LODs asked for, and turn QA
+// findings into one thrown Ts23dError an agent can act on (code, every finding, the first fix).
+
+import { type Asset, type CompiledAsset, compile, type Lod, Ts23dError } from '../core/index.ts';
+import type { Finding } from '../qa/index.ts';
+
+export interface LodOptions {
+  /** LODs to check. Default all three. */
+  readonly lods?: readonly Lod[];
+  readonly seed?: number;
+}
+
+export const ALL_LODS: readonly Lod[] = [0, 1, 2];
+
+export const compileLods = (asset: Asset, o: LodOptions = {}): CompiledAsset[] =>
+  (o.lods ?? ALL_LODS).map((lod) =>
+    compile(asset, { lod, ...(o.seed !== undefined ? { seed: o.seed } : {}) }),
+  );
+
+export const describeFinding = (f: Finding, lod?: Lod): string =>
+  `${lod !== undefined ? `LOD${lod} ` : ''}${f.gate}${f.part ? ` [${f.part}]` : ''}: ${f.message}`;
+
+/** Throw T3D_QA_FAILED listing every finding; no-op when there are none. */
+export function failOn(what: string, found: ReadonlyArray<{ finding: Finding; lod?: Lod }>): void {
+  if (found.length === 0) return;
+  const lines = found.map(({ finding, lod }) => `  - ${describeFinding(finding, lod)}`);
+  throw new Ts23dError('T3D_QA_FAILED', {
+    cause: `${what}: ${found.length} finding(s)\n${lines.join('\n')}`,
+    fix: found[0]?.finding.fix ?? 'read the findings above',
+  });
+}

package/src/testing/hash.ts

@@ -0,0 +1,14 @@
+// A stable content hash for snapshot tests: 64-bit FNV-1a (two 32-bit lanes), pure JS, so the
+// same bytes give the same hex string on Bun, Node and the browser — no runtime hash API needed.
+
+export function hashBytes(bytes: Uint8Array): string {
+  let h1 = 0x811c9dc5;
+  let h2 = 0xcbf29ce4;
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i] ?? 0;
+    h1 = Math.imul(h1 ^ b, 0x01000193);
+    h2 = Math.imul(h2 ^ b ^ (h1 >>> 24), 0x01000193);
+  }
+  const hex = (n: number): string => (n >>> 0).toString(16).padStart(8, '0');
+  return `${hex(h2)}${hex(h1)}`;
+}

package/src/testing/index.ts

@@ -0,0 +1,14 @@
+// Public API of /testing: assertions for users' own recipe tests (`bun test`, vitest, node:test —
+// framework-agnostic: each throws a Ts23dError with findings and a fix, or returns quietly).
+
+export {
+  assertBudget,
+  assertMeasure,
+  assertMotionClear,
+  assertParts,
+  assertQaPass,
+  type QaOptions,
+} from './assert.ts';
+export { ALL_LODS, compileLods, describeFinding, type LodOptions } from './compiled.ts';
+export { hashBytes } from './hash.ts';
+export { assertDeterministic, type SnapshotOptions, snapshotHash } from './snapshot.ts';

package/src/testing/snapshot.ts

@@ -0,0 +1,37 @@
+// Determinism and snapshot helpers: the GLB an asset compiles to, hashed. Pin a hash in a test to
+// catch any unintended geometry change; compile twice to prove the recipe has no ambient state.
+
+import { type Asset, compile, type Lod, Ts23dError } from '../core/index.ts';
+import { exportGlb, type GlbOptions } from '../export/index.ts';
+import type { LodOptions } from './compiled.ts';
+import { ALL_LODS } from './compiled.ts';
+import { hashBytes } from './hash.ts';
+
+export interface SnapshotOptions {
+  readonly lod?: Lod;
+  readonly seed?: number;
+  /** Exporter options; default the plain optimised GLB (no textures, no clips). */
+  readonly glb?: GlbOptions;
+}
+
+/** 16-hex-digit content hash of the asset's GLB at one LOD. */
+export function snapshotHash(asset: Asset, o: SnapshotOptions = {}): string {
+  const a = compile(asset, {
+    lod: o.lod ?? 0,
+    ...(o.seed !== undefined ? { seed: o.seed } : {}),
+  });
+  return hashBytes(exportGlb(a, o.glb ?? {}).glb);
+}
+
+/** Compile + export twice per LOD; the bytes must match. */
+export function assertDeterministic(asset: Asset, o: LodOptions = {}): void {
+  for (const lod of o.lods ?? ALL_LODS) {
+    const once = snapshotHash(asset, { lod, ...(o.seed !== undefined ? { seed: o.seed } : {}) });
+    const twice = snapshotHash(asset, { lod, ...(o.seed !== undefined ? { seed: o.seed } : {}) });
+    if (once !== twice)
+      throw new Ts23dError('T3D_QA_FAILED', {
+        cause: `${asset.name} LOD${lod} is not byte-deterministic (${once} vs ${twice})`,
+        fix: 'remove ambient state from build(): read ctx.rng/ctx.seed only — no Math.random, Date, or module-level counters',
+      });
+  }
+}

package/src/types/gltf-validator.d.ts

@@ -0,0 +1,13 @@
+// Minimal types for the dev-only Khronos validator (it ships none).
+declare module 'gltf-validator' {
+  export function validateBytes(
+    data: Uint8Array,
+    options?: Record<string, unknown>,
+  ): Promise<{
+    issues: {
+      numErrors: number;
+      numWarnings: number;
+      messages: { severity: number; code: string; pointer?: string; message: string }[];
+    };
+  }>;
+}