@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/export/lod-coverage.ts

@@ -0,0 +1,71 @@
+// View-distance hints for the single-file GLB: MSFT_lod (vendor extension, node level) on the
+// LOD0 root lists the LOD1/LOD2 roots, and `extras.MSFT_screencoverage` holds, per LOD, the
+// screen-height fraction below which the next LOD (or nothing) takes over — Unity LODGroup's
+// "screen relative transition height". Spec: KhronosGroup/glTF extensions/2.0/Vendor/MSFT_lod.
+//
+// Default thresholds match screen-space triangle density: a LOD with r × the triangles looks as
+// dense at √r × the size on screen (triangles per pixel ∝ tris / coverage²). Landmarks (≥ 10 m)
+// cull later than props, so a building stays on the skyline.
+
+import type { CompiledAsset } from '../core/index.ts';
+import { Ts23dError, worldMeshes } from '../core/index.ts';
+
+export const MSFT_LOD = 'MSFT_lod';
+export const SCREEN_COVERAGE = 'MSFT_screencoverage';
+
+export type LodCoverage = readonly [number, number, number];
+
+const tris = (a: CompiledAsset): number =>
+  a.parts.reduce((s, p) => s + (p.mesh ? p.mesh.indices.length / 3 : 0), 0);
+
+/** Largest extent in metres: `real` when declared, else the LOD0 world bounds. */
+function extent(a: CompiledAsset): number {
+  if (a.real) return Math.max(a.real.length, a.real.width, a.real.height);
+  const lo = [Infinity, Infinity, Infinity];
+  const hi = [-Infinity, -Infinity, -Infinity];
+  for (const mesh of worldMeshes(a.parts).values()) {
+    const p = mesh.positions;
+    for (let i = 0; i < p.length; i++) {
+      const k = i % 3;
+      const v = p[i] ?? 0;
+      lo[k] = Math.min(lo[k] ?? 0, v);
+      hi[k] = Math.max(hi[k] ?? 0, v);
+    }
+  }
+  return Math.max(0, ...hi.map((h, k) => h - (lo[k] ?? 0)));
+}
+
+const clamp = (v: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, v));
+const round = (v: number): number => Math.round(v * 1000) / 1000;
+
+/** Default [LOD0→1, LOD1→2, cull] for an asset from its compiled LODs (any subset, LOD0 first). */
+export function defaultCoverage(lods: readonly CompiledAsset[]): LodCoverage {
+  const byLod = new Map<number, number>(lods.map((a) => [a.lod, tris(a)]));
+  const top = lods[0];
+  const t0 = Math.max(1, top ? tris(top) : 1);
+  const ratio = (lod: number): number => (byLod.get(lod) ?? t0) / t0;
+  const c1 = round(clamp(Math.sqrt(ratio(1)), 0.1, 0.6));
+  const c2 = round(clamp(Math.sqrt(ratio(2)), 0.02, c1 / 2));
+  const cull = top && extent(top) >= 10 ? 0.002 : 0.01;
+  return [c1, c2, Math.min(cull, round(c2 / 2))];
+}
+
+export function checkCoverage(c: readonly number[], asset: string): void {
+  const [a = -1, b = -1, cull = -1] = c;
+  if (c.length !== 3 || !(a < 1 && a > b && b > cull && cull >= 0))
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `lodCoverage ${JSON.stringify(c)} on '${asset}' is not strictly descending in [0, 1)`,
+      fix: 'give [LOD0→LOD1, LOD1→LOD2, cull] screen-height fractions, e.g. [0.5, 0.2, 0.01]; 0 = never cull',
+    });
+}
+
+/**
+ * MSFT_screencoverage for the LODs actually written (e.g. [0, 2]): entry j is the coverage where
+ * LOD j hands over — to the next included LOD's switch point, or to nothing (cull) for the last.
+ */
+export function coverageFor(levels: readonly number[], c: LodCoverage): number[] {
+  return levels.map((_, j) => {
+    const next = levels[j + 1];
+    return next === undefined ? c[2] : (c[next - 1] ?? c[2]);
+  });
+}

package/src/export/materials.ts

@@ -0,0 +1,126 @@
+// The (at most) four shared materials, one per Surface in use. All sample the same trim sheet and
+// take tint from COLOR_0, so batching holds; only the shading model differs. Glass/translucent use
+// KHR_materials_transmission + _volume + _ior (three, Babylon, glTFast); engines without them fall
+// back to alpha BLEND via baseColorFactor.a. With a painted sheet bound (textures.ts), every
+// material samples it: baseColor (sRGB, alpha = cutout mask), normal, and ORM in both the
+// occlusion and metallicRoughness slots. Opaque/cutout factors go to 1 so the ORM texture rules;
+// glass/translucent keep theirs as multipliers (clear stays clear whatever strip it maps).
+
+import type { Surface } from '../core/index.ts';
+import type { Json } from './bin-writer.ts';
+
+const MATERIALS: Readonly<Record<Surface, Json>> = {
+  opaque: {
+    name: 'ts23d_trim',
+    pbrMetallicRoughness: {
+      baseColorFactor: [1, 1, 1, 1],
+      metallicFactor: 0,
+      roughnessFactor: 0.8,
+    },
+  },
+  cutout: {
+    name: 'ts23d_trim_cutout',
+    alphaMode: 'MASK',
+    alphaCutoff: 0.5,
+    doubleSided: true,
+    pbrMetallicRoughness: {
+      baseColorFactor: [1, 1, 1, 1],
+      metallicFactor: 0,
+      roughnessFactor: 0.9,
+    },
+  },
+  glass: {
+    name: 'ts23d_glass',
+    alphaMode: 'BLEND',
+    pbrMetallicRoughness: {
+      baseColorFactor: [1, 1, 1, 0.25],
+      metallicFactor: 0,
+      roughnessFactor: 0.05,
+    },
+    extensions: {
+      KHR_materials_transmission: { transmissionFactor: 1 },
+      KHR_materials_volume: { thicknessFactor: 0.01 },
+      KHR_materials_ior: { ior: 1.5 },
+    },
+  },
+  translucent: {
+    name: 'ts23d_translucent',
+    alphaMode: 'BLEND',
+    pbrMetallicRoughness: {
+      baseColorFactor: [1, 1, 1, 0.6],
+      metallicFactor: 0,
+      roughnessFactor: 0.35,
+    },
+    extensions: {
+      KHR_materials_transmission: { transmissionFactor: 0.6 },
+      KHR_materials_volume: { thicknessFactor: 0.02 },
+      KHR_materials_ior: { ior: 1.45 },
+    },
+  },
+};
+
+const ORDER: readonly Surface[] = ['opaque', 'cutout', 'glass', 'translucent'];
+
+/** The same material sampling the sheet (texture indices fixed by textures.ts). */
+function textured(m: Json, surface: Surface): Json {
+  const pbr = m['pbrMetallicRoughness'] as Json;
+  const own = surface === 'opaque' || surface === 'cutout';
+  return {
+    ...m,
+    pbrMetallicRoughness: {
+      ...pbr,
+      baseColorTexture: { index: 0 },
+      metallicRoughnessTexture: { index: 2 },
+      ...(own ? { metallicFactor: 1, roughnessFactor: 1 } : {}),
+    },
+    normalTexture: { index: 1 },
+    occlusionTexture: { index: 2 },
+  };
+}
+
+/** Materials for the surfaces present, plus each surface's index and the extensions used. */
+export function materialsFor(
+  used: ReadonlySet<Surface>,
+  withSheet = false,
+): {
+  materials: Json[];
+  index: Map<Surface, number>;
+  extensionsUsed: string[];
+} {
+  const present = ORDER.filter((s) => s === 'opaque' || used.has(s));
+  const index = new Map(present.map((s, i) => [s, i] as const));
+  const ext = new Set<string>();
+  for (const s of present)
+    for (const e of Object.keys((MATERIALS[s]['extensions'] as Json | undefined) ?? {})) ext.add(e);
+  const materials = present.map((s) => (withSheet ? textured(MATERIALS[s], s) : MATERIALS[s]));
+  return { materials, index, extensionsUsed: [...ext].sort() };
+}
+
+export const EMISSIVE_STRENGTH = 'KHR_materials_emissive_strength';
+
+/** A lit surface: lamp lenses, windows at night, panel glow. */
+export interface GlowRule {
+  /** Part names or globs: 'headlamp_*', 'window_*'. */
+  readonly parts: readonly string[];
+  /** Linear RGB 0..1 (use `hex('#ffd9a0')` from /material). Default warm white. */
+  readonly color?: readonly [number, number, number];
+  /** Brightness multiplier (KHR_materials_emissive_strength, Ratified); 1 = plain glTF. */
+  readonly strength?: number;
+}
+
+/**
+ * The opaque trim material plus emission. emissiveFactor caps at 1 in core glTF; anything
+ * brighter rides KHR_materials_emissive_strength (engines without it see the clamped glow).
+ */
+export function glowMaterial(rule: GlowRule, i: number, withSheet: boolean): Json {
+  const base = withSheet ? textured(MATERIALS.opaque, 'opaque') : MATERIALS.opaque;
+  const strength = rule.strength ?? 4;
+  return {
+    ...base,
+    name: `ts23d_glow_${i}`,
+    emissiveFactor: [...(rule.color ?? [1, 0.85, 0.6])],
+    ...(strength !== 1
+      ? { extensions: { [EMISSIVE_STRENGTH]: { emissiveStrength: strength } } }
+      : {}),
+  };
+}

package/src/export/merge-pivots.ts

@@ -0,0 +1,146 @@
+// Batching for engines: every part that is NOT a pivot is merged into its nearest pivot ancestor,
+// so draw calls = pivots with geometry, not parts. A pivot is anything the engine may move: a
+// group (`ctx.group`, a named handle like `turret`, `gun`, `door_l`) or a part with `motion`.
+// Static top-level geometry merges into one `body` part. Names the engine binds to survive.
+// Non-opaque surfaces split into `<pivot>_<surface>` children (one draw call per surface), and
+// glowing parts (GlbOptions.glow) into `<pivot>_glow_<i>` children with their emissive material.
+
+import {
+  type CompiledAsset,
+  type Mesh,
+  merge,
+  type Part,
+  rotateZ,
+  type Surface,
+  toWorld,
+  type WorldTransform,
+  worldTransforms,
+} from '../core/index.ts';
+
+const isPivot = (p: Part): boolean => p.mesh === null || p.motion !== null;
+
+/** Merged layer parts that glow → index of the glow rule (read by the GLB writer). */
+export const glowLayer = new WeakMap<Part, number>();
+
+/** `*`/`?` glob → anchored RegExp (export cannot import /qa: same tier). */
+export const globRe = (pattern: string): RegExp =>
+  new RegExp(
+    `^${pattern
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replaceAll('*', '.*')
+      .replaceAll('?', '.')}$`,
+  );
+const SURFACES: readonly Surface[] = ['cutout', 'glass', 'translucent'];
+
+/** Re-express a part's mesh in its pivot's local space. */
+function intoPivot(mesh: Mesh, part: WorldTransform, pivot: WorldTransform): Mesh {
+  const positions = new Float32Array(mesh.positions.length);
+  const normals = new Float32Array(mesh.normals.length);
+  for (let i = 0; i < positions.length; i += 3) {
+    const w = toWorld(part, [
+      mesh.positions[i] ?? 0,
+      mesh.positions[i + 1] ?? 0,
+      mesh.positions[i + 2] ?? 0,
+    ]);
+    positions.set(
+      rotateZ([w[0] - pivot.origin[0], w[1] - pivot.origin[1], w[2] - pivot.origin[2]], -pivot.yaw),
+      i,
+    );
+    normals.set(
+      rotateZ(
+        rotateZ(
+          [mesh.normals[i] ?? 0, mesh.normals[i + 1] ?? 0, mesh.normals[i + 2] ?? 0],
+          part.yaw,
+        ),
+        -pivot.yaw,
+      ),
+      i,
+    );
+  }
+  return { ...mesh, positions, normals };
+}
+
+export function mergeToPivots(
+  asset: CompiledAsset,
+  glow: readonly (readonly string[])[] = [],
+): CompiledAsset {
+  const glowRes = glow.map((globs) => globs.map(globRe));
+  const glowOf = (name: string): number => glowRes.findIndex((rs) => rs.some((r) => r.test(name)));
+  const byName = new Map(asset.parts.map((p) => [p.name, p]));
+  const xf = worldTransforms(asset.parts);
+  const ROOT = 'body';
+  const identity: WorldTransform = { origin: [0, 0, 0], yaw: 0 };
+  const pivotOf = (p: Part): string => {
+    let cur = p.parent ? byName.get(p.parent) : undefined;
+    while (cur && !isPivot(cur)) cur = cur.parent ? byName.get(cur.parent) : undefined;
+    return cur?.name ?? ROOT;
+  };
+  // Buckets keyed by pivot + surface: opaque merges into the pivot's own mesh; each other
+  // surface in use becomes one child `<pivot>_<surface>` so materials never mix in a primitive.
+  const extra = new Map<string, Mesh[]>();
+  const bucket = (pivot: string, surface: Surface | undefined, mesh: Mesh, g = -1): void => {
+    const k = `${pivot}|${g >= 0 ? `glow_${g}` : (surface ?? 'opaque')}`;
+    extra.set(k, [...(extra.get(k) ?? []), mesh]);
+  };
+  for (const p of asset.parts) {
+    if (!p.mesh) continue;
+    const g = glowOf(p.name);
+    if (isPivot(p)) {
+      bucket(p.name, p.surface, p.mesh, g);
+      continue;
+    }
+    const pivot = pivotOf(p);
+    const t = xf.get(p.name) ?? identity;
+    const pt = pivot === ROOT ? identity : (xf.get(pivot) ?? identity);
+    bucket(pivot, p.surface, intoPivot(p.mesh, t, pt), g);
+  }
+  const parts: Part[] = [];
+  const layers = (pivot: string, parent: string | null): void => {
+    for (const surface of SURFACES) {
+      const meshes = extra.get(`${pivot}|${surface}`);
+      if (!meshes) continue;
+      parts.push({
+        name: `${pivot}_${surface}`,
+        mesh: merge(meshes),
+        at: [0, 0, 0],
+        parent,
+        yaw: 0,
+        motion: null,
+        surface,
+      });
+    }
+    glow.forEach((_, g) => {
+      const meshes = extra.get(`${pivot}|glow_${g}`);
+      if (!meshes) return;
+      const part: Part = {
+        name: `${pivot}_glow_${g}`,
+        mesh: merge(meshes),
+        at: [0, 0, 0],
+        parent,
+        yaw: 0,
+        motion: null,
+      };
+      glowLayer.set(part, g);
+      parts.push(part);
+    });
+  };
+  const body = extra.get(`${ROOT}|opaque`);
+  if (body)
+    parts.push({
+      name: ROOT,
+      mesh: merge(body),
+      at: [0, 0, 0],
+      parent: null,
+      yaw: 0,
+      motion: null,
+    });
+  layers(ROOT, null);
+  for (const p of asset.parts) {
+    if (!isPivot(p)) continue;
+    const own = extra.get(`${p.name}|opaque`);
+    const { surface: _drop, ...rest } = p;
+    parts.push({ ...rest, mesh: own ? merge(own) : null });
+    layers(p.name, p.name);
+  }
+  return { ...asset, parts };
+}

package/src/export/metadata.ts

@@ -0,0 +1,62 @@
+// 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[];
+  /** Third-party inputs (e.g. CC0 texture sets) → `dc:contributor`. Filled by export. */
+  readonly credits?: 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] } } : {}),
+    ...(meta.credits?.length ? { 'dc:contributor': { '@set': [...meta.credits] } } : {}),
+    '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;
+}