@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/core/world.ts

@@ -0,0 +1,80 @@
+// Part-space → world-space. Parts chain translation + yaw through their parents; QA, the
+// rasteriser and any back end that flattens a scene read world positions from here.
+
+import type { Part } from './asset.ts';
+import type { Mesh } from './mesh.ts';
+import type { Vec3 } from './vec.ts';
+
+export interface WorldTransform {
+  readonly origin: Vec3;
+  readonly yaw: number;
+}
+
+const rotZ = (p: Vec3, yaw: number): Vec3 => {
+  const c = Math.cos(yaw);
+  const s = Math.sin(yaw);
+  return [p[0] * c - p[1] * s, p[0] * s + p[1] * c, p[2]];
+};
+
+export function worldTransforms(parts: readonly Part[]): Map<string, WorldTransform> {
+  const out = new Map<string, WorldTransform>();
+  for (const p of parts) {
+    const parent = (p.parent ? out.get(p.parent) : undefined) ?? {
+      origin: [0, 0, 0] as Vec3,
+      yaw: 0,
+    };
+    const at = rotZ(p.at, parent.yaw);
+    out.set(p.name, {
+      origin: [parent.origin[0] + at[0], parent.origin[1] + at[1], parent.origin[2] + at[2]],
+      yaw: parent.yaw + p.yaw,
+    });
+  }
+  return out;
+}
+
+export function toWorld(t: WorldTransform, p: Vec3): Vec3 {
+  const r = rotZ(p, t.yaw);
+  return [r[0] + t.origin[0], r[1] + t.origin[1], r[2] + t.origin[2]];
+}
+
+export const rotateZ = rotZ;
+
+/** A part's mesh baked into world space (positions and normals), ready for QA or rasterising. */
+export function worldMesh(mesh: Mesh, t: 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) {
+    positions.set(
+      toWorld(t, [mesh.positions[i] ?? 0, mesh.positions[i + 1] ?? 0, mesh.positions[i + 2] ?? 0]),
+      i,
+    );
+    normals.set(
+      rotZ([mesh.normals[i] ?? 0, mesh.normals[i + 1] ?? 0, mesh.normals[i + 2] ?? 0], t.yaw),
+      i,
+    );
+  }
+  return { ...mesh, positions, normals };
+}
+
+// QA gates, checks, renderers and measures all ask for the same world meshes: compute once per
+// parts array (a CompiledAsset's parts are immutable).
+const worldCache = new WeakMap<readonly Part[], Map<string, Mesh>>();
+
+/** Every part with geometry, in world space, keyed by part name. Cached per parts array. */
+export function worldMeshes(parts: readonly Part[]): Map<string, Mesh> {
+  const hit = worldCache.get(parts);
+  if (hit) return hit;
+  const out = computeWorldMeshes(parts);
+  worldCache.set(parts, out);
+  return out;
+}
+
+function computeWorldMeshes(parts: readonly Part[]): Map<string, Mesh> {
+  const xf = worldTransforms(parts);
+  const out = new Map<string, Mesh>();
+  for (const p of parts) {
+    const t = xf.get(p.name);
+    if (p.mesh && t && p.mesh.indices.length > 0) out.set(p.name, worldMesh(p.mesh, t));
+  }
+  return out;
+}

package/src/export/bin-writer.ts

@@ -0,0 +1,79 @@
+// Packs typed arrays into one 4-byte-aligned glTF buffer and records bufferViews + accessors.
+
+export const ARRAY_BUFFER = 34962;
+export const ELEMENT_ARRAY_BUFFER = 34963;
+const FLOAT = 5126;
+const UINT32 = 5125;
+const UINT16 = 5123;
+
+export interface Json {
+  [key: string]: unknown;
+}
+
+export class BinWriter {
+  private readonly chunks: Uint8Array[] = [];
+  length = 0;
+  readonly views: Json[] = [];
+  readonly accessors: Json[] = [];
+
+  private push(bytes: Uint8Array, target?: number): number {
+    const pad = (4 - (this.length % 4)) % 4;
+    if (pad) {
+      this.chunks.push(new Uint8Array(pad));
+      this.length += pad;
+    }
+    this.views.push({
+      buffer: 0,
+      byteOffset: this.length,
+      byteLength: bytes.byteLength,
+      ...(target ? { target } : {}),
+    });
+    this.chunks.push(bytes);
+    this.length += bytes.byteLength;
+    return this.views.length - 1;
+  }
+
+  accessor(
+    data: Float32Array | Uint32Array | Uint16Array,
+    type: 'SCALAR' | 'VEC2' | 'VEC3' | 'VEC4',
+    target?: number,
+    bounds = false,
+    /** Integer data read as 0..1 (vertex colour as normalised unsigned short). */
+    normalized = false,
+  ): number {
+    const view = this.push(new Uint8Array(data.buffer, data.byteOffset, data.byteLength), target);
+    const width = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4 }[type];
+    const acc: Json = {
+      bufferView: view,
+      componentType:
+        data instanceof Uint32Array ? UINT32 : data instanceof Uint16Array ? UINT16 : FLOAT,
+      count: data.length / width,
+      type,
+      ...(normalized ? { normalized: true } : {}),
+    };
+    if (bounds) {
+      const min = Array<number>(width).fill(Infinity);
+      const max = Array<number>(width).fill(-Infinity);
+      for (let i = 0; i < data.length; i++) {
+        const k = i % width;
+        const v = data[i] ?? 0;
+        if (v < (min[k] ?? 0)) min[k] = v;
+        if (v > (max[k] ?? 0)) max[k] = v;
+      }
+      acc['min'] = min;
+      acc['max'] = max;
+    }
+    this.accessors.push(acc);
+    return this.accessors.length - 1;
+  }
+
+  bytes(): Uint8Array {
+    const out = new Uint8Array(Math.ceil(this.length / 4) * 4);
+    let o = 0;
+    for (const c of this.chunks) {
+      out.set(c, o);
+      o += c.byteLength;
+    }
+    return out;
+  }
+}

package/src/export/container.ts

@@ -0,0 +1,35 @@
+// The GLB container: 12-byte header, JSON chunk (space-padded), BIN chunk (zero-padded), every
+// length a multiple of 4 [glTF 2.0 §glb-file-format-specification].
+
+import type { Json } from './bin-writer.ts';
+
+export function packGlb(gltf: Json, body: Uint8Array): Uint8Array {
+  let json = new TextEncoder().encode(JSON.stringify(gltf));
+  const jsonPad = (4 - (json.byteLength % 4)) % 4;
+  if (jsonPad) {
+    const padded = new Uint8Array(json.byteLength + jsonPad).fill(0x20);
+    padded.set(json);
+    json = padded;
+  }
+  const total = 12 + 8 + json.byteLength + 8 + body.byteLength;
+  const out = new Uint8Array(total);
+  const dv = new DataView(out.buffer);
+  dv.setUint32(0, 0x46546c67, true);
+  dv.setUint32(4, 2, true);
+  dv.setUint32(8, total, true);
+  dv.setUint32(12, json.byteLength, true);
+  dv.setUint32(16, 0x4e4f534a, true);
+  out.set(json, 20);
+  const binAt = 20 + json.byteLength;
+  dv.setUint32(binAt, body.byteLength, true);
+  dv.setUint32(binAt + 4, 0x004e4942, true);
+  out.set(body, binAt + 8);
+  return out;
+}
+
+export function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.byteLength + b.byteLength);
+  out.set(a);
+  out.set(b, a.byteLength);
+  return out;
+}

package/src/export/credits.ts

@@ -0,0 +1,25 @@
+// Texture credits into the GLB: when an asset samples an image strip (a CC0 texture set registered
+// with defineMaterial), its credit line joins the XMP packet's `dc:contributor`. Assets that use
+// only procedural strips get no change, so their bytes stay identical.
+
+import type { CompiledAsset } from '../core/index.ts';
+import { stripCredits } from '../material/index.ts';
+import type { GlbMeta } from './metadata.ts';
+
+export function creditsOf(asset: CompiledAsset): string[] {
+  const out = new Set<string>();
+  for (const p of asset.parts) {
+    const uv = p.mesh?.uvs;
+    if (!uv) continue;
+    const v = new Float32Array(uv.length >> 1);
+    for (let i = 0; i < v.length; i++) v[i] = uv[i * 2 + 1] ?? 0;
+    for (const c of stripCredits(v)) out.add(c);
+  }
+  return [...out].sort();
+}
+
+export function withCredits(asset: CompiledAsset, meta: GlbMeta | undefined): GlbMeta | undefined {
+  const credits = creditsOf(asset);
+  if (!credits.length) return meta;
+  return { ...meta, credits: [...(meta?.credits ?? []), ...credits] };
+}

package/src/export/glb-options.ts

@@ -0,0 +1,53 @@
+// Options and results of the GLB writer (glb.ts): what goes into the file and what comes back.
+
+import type { OptimizeOptions } from '../passes/index.ts';
+import type { LodCoverage } from './lod-coverage.ts';
+import type { GlowRule } from './materials.ts';
+import type { GlbMeta } from './metadata.ts';
+import type { ExportReport } from './optimize-parts.ts';
+import type { SheetBinding } from './textures.ts';
+
+export interface GlbOptions {
+  /** Keep every part as its own node (debugging, per-part picking). Default merges to pivots. */
+  readonly keepParts?: boolean;
+  /**
+   * Bake each part's `motion` into a looping `run` clip. Off by default: glTF has no autoplay
+   * flag and most viewers play the first clip, while engines usually drive the named pivots
+   * from game code. Turn it on for previews, cutscenes and ambient props.
+   */
+  readonly animations?: boolean;
+  /**
+   * Bind the painted trim sheet to every material: a `PaintedSheet` embeds the three PNGs (one
+   * self-contained file); `{ external: true, prefix? }` references shared `trim_sheet_*.png` by
+   * URI. Omitted: no textures, byte-identical to the untextured output.
+   */
+  readonly sheet?: SheetBinding;
+  /**
+   * Weld + vertex-cache + vertex-fetch optimisation per primitive (passes/optimize). On by
+   * default; `false` writes the meshes exactly as compiled (debugging the IR).
+   */
+  readonly optimize?: boolean | OptimizeOptions;
+  /** Parts that emit light (lamp lenses, lit windows): one emissive material per rule. */
+  readonly glow?: readonly GlowRule[];
+  /** Provenance: asset.copyright + an XMP packet (title, creators, licence, sources). */
+  readonly meta?: GlbMeta;
+  /**
+   * Single-file LODs only: [LOD0→LOD1, LOD1→LOD2, cull] screen-height fractions written as
+   * `MSFT_screencoverage`. Default: the asset's `lodCoverage`, else derived (lod-coverage.ts).
+   */
+  readonly lodCoverage?: LodCoverage;
+}
+
+/** The GLB bytes plus what the optimiser did (vertex counts, ACMR before/after, per part). */
+export interface GlbResult {
+  readonly glb: Uint8Array;
+  readonly report: ExportReport;
+}
+
+/** One GLB holding several LODs, plus one optimiser report per LOD (same order as the input). */
+export interface LodGlbResult {
+  readonly glb: Uint8Array;
+  readonly reports: readonly ExportReport[];
+  /** The `MSFT_screencoverage` written (empty for a single LOD). */
+  readonly coverage: readonly number[];
+}

package/src/export/glb.ts

@@ -0,0 +1,187 @@
+// glTF 2.0 binary writer. One material (the trim sheet) for the whole asset, one node per part
+// with its pivot as translation, and each part's motion baked as a looping animation clip.
+// Extras a stock viewer understands: light sockets → KHR_lights_punctual, glowing parts →
+// emissive (+ KHR_materials_emissive_strength), provenance → asset.copyright + KHR_xmp_json_ld.
+// `exportLodGlb` packs several LODs into ONE file (MSFT_lod alternates sharing materials,
+// textures and motion samplers). Zero dependencies and byte-deterministic.
+
+import type { CompiledAsset, Part } from '../core/index.ts';
+import { Ts23dError } from '../core/index.ts';
+import { BinWriter, type Json } from './bin-writer.ts';
+import { concat, packGlb } from './container.ts';
+import { withCredits } from './credits.ts';
+import type { GlbOptions, GlbResult, LodGlbResult } from './glb-options.ts';
+import { newDoc, writeHierarchy } from './hierarchy.ts';
+import { LIGHTS } from './lights.ts';
+import {
+  checkCoverage,
+  coverageFor,
+  defaultCoverage,
+  MSFT_LOD,
+  SCREEN_COVERAGE,
+} from './lod-coverage.ts';
+import { EMISSIVE_STRENGTH, type GlowRule, glowMaterial, materialsFor } from './materials.ts';
+import { globRe, glowLayer, mergeToPivots } from './merge-pivots.ts';
+import { metadata } from './metadata.ts';
+import { optimizeParts, summarize } from './optimize-parts.ts';
+import { sheetGltf } from './textures.ts';
+
+// Viewers auto-play the FIRST clip and glTF has no "paused" flag, so the first clip is `rest`: two
+// keys holding the root's rest rotation. The file opens still; pick `run` to play it.
+// Authoring frame: Z up, +X front. glTF: Y up, +Z front, +X = the asset's left. This root
+// rotation maps +X→+Z, +Z→+Y, +Y→+X (verified numerically), so assets face forward in engines.
+const Z_UP_TO_Y_UP = [-0.5, -0.5, -0.5, 0.5];
+function restClip(bin: BinWriter, roots: readonly number[]): Json {
+  const input = bin.accessor(new Float32Array([0, 1]), 'SCALAR', undefined, true);
+  const output = bin.accessor(new Float32Array([...Z_UP_TO_Y_UP, ...Z_UP_TO_Y_UP]), 'VEC4');
+  return {
+    name: 'rest',
+    samplers: [{ input, output, interpolation: 'STEP' }],
+    channels: roots.map((node) => ({ sampler: 0, target: { node, path: 'rotation' } })),
+  };
+}
+
+export type { GlbOptions, GlbResult, LodGlbResult } from './glb-options.ts';
+
+export function toGlb(input: CompiledAsset, o: GlbOptions = {}): Uint8Array {
+  return exportGlb(input, o).glb;
+}
+
+export function exportGlb(input: CompiledAsset, o: GlbOptions = {}): GlbResult {
+  const { glb, reports } = exportLodGlb([input], o);
+  return { glb, report: reports[0] ?? summarize([], false) };
+}
+
+/** All LODs in one GLB: LOD0 in the scene, the rest as MSFT_lod alternates outside it. */
+export function toLodGlb(lods: readonly CompiledAsset[], o: GlbOptions = {}): Uint8Array {
+  return exportLodGlb(lods, o).glb;
+}
+
+function checkGlow(rules: readonly GlowRule[]): void {
+  for (const r of rules)
+    if ((r.strength ?? 4) < 0 || (r.color ?? [0, 0, 0]).some((c) => c < 0 || c > 1))
+      throw new Ts23dError('T3D_RECIPE_INVALID', {
+        cause: `glow rule for ${JSON.stringify(r.parts)} has a colour outside 0..1 or a negative strength`,
+        fix: 'colour is linear 0..1 (hex() converts sRGB); brightness goes in `strength`',
+      });
+}
+
+function checkLods(lods: readonly CompiledAsset[]): void {
+  const names = new Set(lods.map((l) => l.name));
+  const levels = lods.map((l) => l.lod);
+  if (
+    lods.length === 0 ||
+    names.size !== 1 ||
+    levels.some((l, i) => i > 0 && l <= (levels[i - 1] ?? 0))
+  )
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `exportLodGlb got LODs [${levels.join(', ')}] of [${[...names].join(', ')}]`,
+      fix: 'pass compile(asset, { lod }) results of ONE asset, highest detail first: LOD0, LOD1, LOD2',
+    });
+}
+
+/** One LOD prepared for writing: merged + optimised parts and its glow-layer lookup. */
+function prepare(input: CompiledAsset, o: GlbOptions, glow: readonly GlowRule[]) {
+  const opt = o.optimize === false ? false : o.optimize === true ? {} : (o.optimize ?? {});
+  const merged = o.keepParts
+    ? input
+    : mergeToPivots(
+        input,
+        glow.map((g) => g.parts),
+      );
+  const { asset, report } = optimizeParts(merged, opt);
+  // optimizeParts copies parts: carry the glow tag across by position.
+  const glowRes = glow.map((g) => g.parts.map(globRe));
+  const glowOf = (p: Part, i: number): number =>
+    glowLayer.get(merged.parts[i] ?? p) ??
+    (o.keepParts ? glowRes.findIndex((rs) => rs.some((r) => r.test(p.name))) : -1);
+  return { asset, report, glowOf };
+}
+
+export function exportLodGlb(lods: readonly CompiledAsset[], o: GlbOptions = {}): LodGlbResult {
+  checkLods(lods);
+  const top = lods[0] as CompiledAsset;
+  const glow = o.glow ?? top.glow ?? [];
+  checkGlow(glow);
+  const preps = lods.map((l) => prepare(l, o, glow));
+  const withSheet = o.sheet !== undefined;
+  const mats = materialsFor(
+    new Set(preps.flatMap((p) => p.asset.parts.flatMap((q) => (q.surface ? [q.surface] : [])))),
+    withSheet,
+  );
+  const glowAt = mats.materials.length;
+  const materials = [...mats.materials, ...glow.map((g, i) => glowMaterial(g, i, withSheet))];
+  const doc = newDoc(new BinWriter());
+  const roots = preps.map(({ asset, glowOf }, k) =>
+    writeHierarchy(doc, asset, k === 0 ? asset.name : `${asset.name}_LOD${asset.lod}`, {
+      withSheet,
+      animations: o.animations === true,
+      materialOf: (part, i) => {
+        const g = glowOf(part, i);
+        return g >= 0 ? glowAt + g : (mats.index.get(part.surface ?? 'opaque') ?? 0);
+      },
+    }),
+  );
+  for (const r of roots) {
+    const node = doc.nodes[r];
+    if (node) node['rotation'] = Z_UP_TO_Y_UP;
+  }
+  const coverage: number[] = [];
+  const rootNode = doc.nodes[0];
+  if (roots.length > 1 && rootNode) {
+    const c = o.lodCoverage ?? top.lodCoverage ?? defaultCoverage(lods);
+    checkCoverage(c, top.name);
+    coverage.push(
+      ...coverageFor(
+        lods.map((l) => l.lod),
+        c,
+      ),
+    );
+    // Alternates stay OUT of the scene's root list: a viewer without MSFT_lod shows LOD0 only.
+    rootNode['extensions'] = { [MSFT_LOD]: { ids: roots.slice(1) } };
+    rootNode['extras'] = { [SCREEN_COVERAGE]: coverage };
+  }
+
+  // Every accessor — the rest clip's included — must be written BEFORE the buffer is sealed.
+  const { bin, lights, samplers, channels } = doc;
+  const animations = channels.length
+    ? [restClip(bin, roots), { name: 'run', samplers, channels }]
+    : [];
+  const geometry = bin.bytes();
+  const tex = o.sheet ? sheetGltf(o.sheet, bin.views, geometry.byteLength) : null;
+  const body = tex?.tail.byteLength ? concat(geometry, tex.tail) : geometry;
+  const meta = metadata(top.name, withCredits(top, o.meta ?? top.meta));
+  const used = [
+    ...mats.extensionsUsed,
+    ...(glow.some((g) => (g.strength ?? 4) !== 1) ? [EMISSIVE_STRENGTH] : []),
+    ...(lights.length ? [LIGHTS] : []),
+    ...(coverage.length ? [MSFT_LOD] : []),
+    ...meta.used,
+  ].sort();
+  const extensions: Json = {
+    ...(lights.length ? { [LIGHTS]: { lights } } : {}),
+    ...(meta.extensions ?? {}),
+  };
+  const gltf: Json = {
+    asset: meta.asset,
+    extras: {
+      kind: top.kind,
+      lod: coverage.length ? lods.map((l) => l.lod) : top.lod,
+      units: 'metres',
+      up: 'Z (rotated to glTF Y-up at the root)',
+    },
+    ...(used.length ? { extensionsUsed: used } : {}),
+    ...(Object.keys(extensions).length ? { extensions } : {}),
+    scene: 0,
+    scenes: [{ name: top.name, nodes: [0] }],
+    nodes: doc.nodes,
+    meshes: doc.meshes,
+    materials,
+    ...(tex ? tex.json : {}),
+    buffers: [{ byteLength: body.byteLength }],
+    bufferViews: bin.views,
+    accessors: bin.accessors,
+    ...(animations.length ? { animations } : {}),
+  };
+  return { glb: packGlb(gltf, body), reports: preps.map((p) => p.report), coverage };
+}

package/src/export/hierarchy.ts

@@ -0,0 +1,122 @@
+// Writes one LOD's node tree into a shared glTF document: a root node, one node per (merged) part
+// with its pivot as translation, light nodes under light sockets, meshes, and the part motions as
+// `run` channels. Called once per LOD; the bin, materials, lights and motion samplers are shared,
+// so a single-file GLB stores each identical motion and light only once.
+
+import type { CompiledAsset, Part } from '../core/index.ts';
+import { quatFromAxisAngle } from '../core/index.ts';
+import type { BinWriter, Json } from './bin-writer.ts';
+import { LIGHTS, lightOf } from './lights.ts';
+import { motionChannel } from './motion.ts';
+import { writePrimitive } from './primitive.ts';
+
+/** The growing glTF arrays every LOD appends to. */
+export interface GltfDoc {
+  readonly bin: BinWriter;
+  readonly nodes: Json[];
+  readonly meshes: Json[];
+  readonly lights: Json[];
+  readonly samplers: Json[];
+  readonly channels: Json[];
+  /** motion + rest pose → sampler index: the same wheel spin at LOD0 and LOD1 is one sampler. */
+  readonly motionSamplers: Map<string, number>;
+  readonly lightIndex: Map<string, number>;
+}
+
+export const newDoc = (bin: BinWriter): GltfDoc => ({
+  bin,
+  nodes: [],
+  meshes: [],
+  lights: [],
+  samplers: [],
+  channels: [],
+  motionSamplers: new Map(),
+  lightIndex: new Map(),
+});
+
+export interface HierarchyOptions {
+  /** Material index for a part (trim sheet by surface, or its glow layer). */
+  readonly materialOf: (part: Part, i: number) => number;
+  readonly withSheet: boolean;
+  readonly animations: boolean;
+}
+
+function attach(doc: GltfDoc, parentId: number, id: number): void {
+  const parent = doc.nodes[parentId];
+  if (!parent) return;
+  parent['children'] = [...((parent['children'] as number[] | undefined) ?? []), id];
+}
+
+function lightIndexOf(doc: GltfDoc, light: Json): number {
+  const key = JSON.stringify(light);
+  const known = doc.lightIndex.get(key);
+  if (known !== undefined) return known;
+  doc.lights.push(light);
+  doc.lightIndex.set(key, doc.lights.length - 1);
+  return doc.lights.length - 1;
+}
+
+function addMotion(doc: GltfDoc, part: Part, id: number): void {
+  if (!part.motion) return;
+  const key = JSON.stringify([part.motion, part.at]);
+  let sampler = doc.motionSamplers.get(key);
+  let channel: Json;
+  if (sampler === undefined) {
+    const written = motionChannel(doc.bin, part.motion, id, part.at);
+    doc.samplers.push(written.sampler);
+    sampler = doc.samplers.length - 1;
+    doc.motionSamplers.set(key, sampler);
+    channel = written.channel;
+  } else {
+    channel = {
+      target: { node: id, path: part.motion.kind === 'slide' ? 'translation' : 'rotation' },
+    };
+  }
+  doc.channels.push({ ...channel, sampler });
+}
+
+/** Appends `asset`'s tree under a new root named `rootName`; returns the root node index. */
+export function writeHierarchy(
+  doc: GltfDoc,
+  asset: CompiledAsset,
+  rootName: string,
+  o: HierarchyOptions,
+): number {
+  doc.nodes.push({ name: rootName, children: [] as number[] });
+  const root = doc.nodes.length - 1;
+  const index = new Map<string, number>();
+  asset.parts.forEach((part: Part, i) => {
+    const node: Json = { name: part.name, translation: [...part.at] };
+    if (part.yaw) node['rotation'] = [...quatFromAxisAngle([0, 0, 1], part.yaw)];
+    if (part.emitter || part.socket) {
+      node['extras'] = {
+        ts23d: {
+          ...(part.emitter ? { emitter: part.emitter } : {}),
+          ...(part.socket ? { socket: part.socket } : {}),
+        },
+      };
+    }
+    if (part.mesh && part.mesh.indices.length > 0) {
+      doc.meshes.push({
+        name: part.name,
+        primitives: [writePrimitive(doc.bin, part.mesh, o.materialOf(part, i), o.withSheet)],
+      });
+      node['mesh'] = doc.meshes.length - 1;
+    }
+    doc.nodes.push(node);
+    const id = doc.nodes.length - 1;
+    index.set(part.name, id);
+    attach(doc, part.parent === null ? root : (index.get(part.parent) ?? root), id);
+    const lit = lightOf(part);
+    if (lit) {
+      doc.nodes.push({
+        name: `${part.name}_light`,
+        rotation: [...lit.rotation],
+        extensions: { [LIGHTS]: { light: lightIndexOf(doc, lit.light) } },
+      });
+      attach(doc, id, doc.nodes.length - 1);
+    }
+    if (o.animations) addMotion(doc, part, id);
+  });
+  return root;
+}

package/src/export/index.ts

@@ -0,0 +1,34 @@
+// Public API of /export: back ends that turn a CompiledAsset into a file.
+
+export {
+  exportGlb,
+  exportLodGlb,
+  type GlbOptions,
+  type GlbResult,
+  type LodGlbResult,
+  toGlb,
+  toLodGlb,
+} from './glb.ts';
+export {
+  checkCoverage,
+  coverageFor,
+  defaultCoverage,
+  type LodCoverage,
+  MSFT_LOD,
+  SCREEN_COVERAGE,
+} from './lod-coverage.ts';
+export { mergeToPivots } from './merge-pivots.ts';
+export {
+  type ExportReport,
+  optimizeParts,
+  type PartOptimizeReport,
+  summarize,
+} from './optimize-parts.ts';
+export {
+  type ExternalSheet,
+  SHEET_MAPS,
+  type SheetBinding,
+  type SheetMap,
+  sheetFileName,
+  sheetPngs,
+} from './textures.ts';

package/src/export/lights.ts

@@ -0,0 +1,49 @@
+// KHR_lights_punctual from light sockets: `ctx.socket('headlamp_l', { kind: 'light', dir,
+// data: { light: 'spot', color: '#ffe8c0', intensity: 200, range: 30, cone: 25 } })` becomes a
+// real light every engine and viewer can switch on. The socket node stays as authored; the light
+// rides a child node `<socket>_light` rotated so its −Z (the glTF light direction) is `dir`.
+
+import type { Part, Quat, Vec3 } from '../core/index.ts';
+import { hex } from '../material/index.ts';
+import type { Json } from './bin-writer.ts';
+
+export const LIGHTS = 'KHR_lights_punctual';
+
+/** Shortest rotation taking unit `a` onto unit `b`. */
+function between(a: Vec3, b: Vec3): Quat {
+  const d = a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+  if (d < -0.999999) return [1, 0, 0, 0]; // opposite: half turn about X (⊥ to −Z)
+  const c: Vec3 = [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+  const w = 1 + d;
+  const n = Math.hypot(c[0], c[1], c[2], w);
+  return [c[0] / n, c[1] / n, c[2] / n, w / n];
+}
+
+const num = (v: unknown, fallback: number): number =>
+  typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+
+/** The glTF light for a light socket, or null for any other part. */
+export function lightOf(part: Part): { light: Json; rotation: Quat } | null {
+  const s = part.socket;
+  if (s?.kind !== 'light') return null;
+  const d = s.data ?? {};
+  const type = d['light'] === 'point' || d['light'] === 'directional' ? d['light'] : 'spot';
+  const color = typeof d['color'] === 'string' ? hex(d['color']) : [1, 1, 1];
+  const dir = s.dir ?? [1, 0, 0];
+  const len = Math.hypot(...dir) || 1;
+  const outer = (Math.min(89, num(d['cone'], 30)) * Math.PI) / 180;
+  const inner = Math.min(outer * 0.999, (num(d['inner'], 0) * Math.PI) / 180);
+  const range = num(d['range'], 0);
+  return {
+    light: {
+      name: part.name,
+      type,
+      color,
+      // Spot/point: candela; directional: lux. Defaults suit a vehicle lamp / a sun.
+      intensity: num(d['intensity'], type === 'directional' ? 3 : type === 'point' ? 20 : 100),
+      ...(range > 0 && type !== 'directional' ? { range } : {}),
+      ...(type === 'spot' ? { spot: { innerConeAngle: inner, outerConeAngle: outer } } : {}),
+    },
+    rotation: between([0, 0, -1], [dir[0] / len, dir[1] / len, dir[2] / len]),
+  };
+}