@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/core/errors.ts

@@ -0,0 +1,50 @@
+// The one error type. Every failure carries a stable code, the cause, and the exact fix — the
+// reader is usually an agent, and an error it can act on is worth ten it has to interpret.
+
+export type ErrorCode =
+  | 'T3D_NOT_IMPLEMENTED'
+  | 'T3D_GRAMMAR_SYNTAX'
+  | 'T3D_GRAMMAR_OVERFLOW'
+  | 'T3D_PART_DUPLICATE'
+  | 'T3D_PART_UNKNOWN'
+  | 'T3D_RECIPE_INVALID'
+  | 'T3D_NO_ASSET_EXPORT'
+  | 'T3D_QA_FAILED'
+  | 'T3D_RENDER_OPTIONS'
+  | 'T3D_AMBIENT_RANDOM'
+  | 'T3D_RELEASE'
+  | 'T3D_BENCH'
+  | 'T3D_MATERIAL_INVALID'
+  | 'T3D_MATERIAL_UNKNOWN'
+  | 'T3D_MATERIAL_CONFLICT'
+  | 'T3D_SHEET_FULL'
+  | 'T3D_TEXTURE_MISSING';
+
+export interface ErrorDetails {
+  readonly cause: string;
+  readonly fix: string;
+}
+
+export class Ts23dError extends Error {
+  readonly code: ErrorCode;
+  readonly fix: string;
+
+  constructor(code: ErrorCode, details: ErrorDetails) {
+    super(`${code}: ${details.cause}`);
+    this.name = 'Ts23dError';
+    this.code = code;
+    this.fix = details.fix;
+  }
+
+  toJSON(): { code: ErrorCode; message: string; fix: string } {
+    return { code: this.code, message: this.message, fix: this.fix };
+  }
+}
+
+/** Placeholder for a planned seam. Names the plan so the agent knows where the work is tracked. */
+export function notImplemented(what: string, plan = 'docs/plans/roadmap.md'): never {
+  throw new Ts23dError('T3D_NOT_IMPLEMENTED', {
+    cause: `${what} is declared but not built yet`,
+    fix: `implement it — the spec and its slice are in ${plan}`,
+  });
+}

package/src/core/family.ts

@@ -0,0 +1,50 @@
+// Parametric families: one build function, many assets. A variant is a name plus the parameters
+// that differ — "T-34 1941 vs 1943 turret", "4-4-0 vs 2-6-0", "oak vs birch" — so a new model is a
+// one-key change, not a copied file. Families extend families: `base.extend({...})` layers new
+// defaults and can wrap the parent's build to add or replace detail.
+
+import { type Asset, type AssetDefinition, type BuildContext, defineAsset } from './asset.ts';
+
+type Shared = Omit<AssetDefinition, 'name' | 'build'>;
+
+export interface FamilyDefinition<P extends object> extends Shared {
+  /** Defaults for every parameter; variants override a subset. */
+  readonly defaults: P;
+  build(ctx: BuildContext, params: Readonly<P>): void;
+}
+
+export interface Variant<P> extends Partial<Shared> {
+  readonly name: string;
+  readonly params?: Partial<P>;
+}
+
+export interface Family<P extends object> {
+  readonly defaults: Readonly<P>;
+  /** Make one asset of this family. */
+  variant(v: Variant<P>): Asset;
+  /** Derive a family: new defaults (may add parameters) and optionally a build that wraps ours. */
+  extend<Q extends object>(
+    o: {
+      readonly defaults: Q;
+      readonly build?: (ctx: BuildContext, params: Readonly<P & Q>, base: () => void) => void;
+    } & Partial<Shared>,
+  ): Family<P & Q>;
+}
+
+export function defineFamily<P extends object>(def: FamilyDefinition<P>): Family<P> {
+  const { defaults, build, ...shared } = def;
+  return {
+    defaults,
+    variant: ({ name, params, ...over }) => {
+      const p = { ...defaults, ...params } as P;
+      return defineAsset({ ...shared, ...over, name, build: (ctx) => build(ctx, p) });
+    },
+    extend: ({ defaults: more, build: wrap, ...over }) =>
+      defineFamily<P & typeof more>({
+        ...shared,
+        ...over,
+        defaults: { ...defaults, ...more },
+        build: (ctx, p) => (wrap ? wrap(ctx, p, () => build(ctx, p)) : build(ctx, p)),
+      }),
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,66 @@
+// Public API of @ts23d/core: errors, RNG, vector math, the mesh IR and the asset DSL root.
+
+export {
+  type Asset,
+  type AssetDefinition,
+  BUDGETS,
+  type Budget,
+  type BuildContext,
+  type Check,
+  type CheckFinding,
+  type CompiledAsset,
+  compile,
+  defineAsset,
+  type Emitter,
+  type EmitterOptions,
+  isAsset,
+  type Lod,
+  type Measure,
+  type Motion,
+  type Part,
+  type PartOptions,
+  type RealDimensions,
+  type Slide,
+  type Socket,
+  type SocketOptions,
+  type Spin,
+  type Surface,
+  type Sway,
+  type UseOptions,
+} from './asset.ts';
+export { type ErrorCode, type ErrorDetails, notImplemented, Ts23dError } from './errors.ts';
+export { defineFamily, type Family, type FamilyDefinition, type Variant } from './family.ts';
+export {
+  type Bounds,
+  boundsOf,
+  type Mesh,
+  MeshBuilder,
+  merge,
+  translate,
+  triangleCount,
+  type Vertex,
+} from './mesh.ts';
+export { encodePng } from './png.ts';
+export { createRng, type Rng } from './rng.ts';
+export { type Affine, affine, applyAffine, frame, type Placement, place } from './transform.ts';
+export {
+  add,
+  cross,
+  dot,
+  length,
+  normalize,
+  type Quat,
+  quatFromAxisAngle,
+  scale,
+  sub,
+  type Vec2,
+  type Vec3,
+} from './vec.ts';
+export {
+  rotateZ,
+  toWorld,
+  type WorldTransform,
+  worldMesh,
+  worldMeshes,
+  worldTransforms,
+} from './world.ts';

package/src/core/mesh.ts

@@ -0,0 +1,114 @@
+// The IR: a triangle mesh with per-vertex normal, UV (into the shared trim sheet) and colour.
+// Every primitive emits one; passes and back ends consume one. Nothing else crosses stages.
+
+import type { Vec2, Vec3 } from './vec.ts';
+
+export interface Bounds {
+  readonly min: Vec3;
+  readonly max: Vec3;
+}
+
+export interface Mesh {
+  readonly positions: Float32Array;
+  readonly normals: Float32Array;
+  readonly uvs: Float32Array;
+  readonly colors: Float32Array;
+  readonly indices: Uint32Array;
+}
+
+export interface Vertex {
+  readonly p: Vec3;
+  readonly n: Vec3;
+  readonly uv: Vec2;
+  readonly color: Vec3;
+}
+
+export class MeshBuilder {
+  private readonly p: number[] = [];
+  private readonly n: number[] = [];
+  private readonly uv: number[] = [];
+  private readonly c: number[] = [];
+  private readonly idx: number[] = [];
+
+  vertex(v: Vertex): number {
+    this.p.push(...v.p);
+    this.n.push(...v.n);
+    this.uv.push(...v.uv);
+    this.c.push(...v.color);
+    return this.p.length / 3 - 1;
+  }
+
+  tri(a: number, b: number, c: number): this {
+    this.idx.push(a, b, c);
+    return this;
+  }
+
+  /** Counter-clockwise quad a-b-c-d as seen from the side its normal faces. */
+  quad(a: number, b: number, c: number, d: number): this {
+    return this.tri(a, b, c).tri(a, c, d);
+  }
+
+  build(): Mesh {
+    return {
+      positions: new Float32Array(this.p),
+      normals: new Float32Array(this.n),
+      uvs: new Float32Array(this.uv),
+      colors: new Float32Array(this.c),
+      indices: new Uint32Array(this.idx),
+    };
+  }
+}
+
+export const triangleCount = (m: Mesh): number => m.indices.length / 3;
+
+export function boundsOf(m: Mesh): Bounds {
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (let i = 0; i < m.positions.length; i += 3) {
+    for (let k = 0; k < 3; k++) {
+      const v = m.positions[i + k] ?? 0;
+      if (v < (min[k] ?? 0)) min[k] = v;
+      if (v > (max[k] ?? 0)) max[k] = v;
+    }
+  }
+  return {
+    min: [min[0] ?? 0, min[1] ?? 0, min[2] ?? 0],
+    max: [max[0] ?? 0, max[1] ?? 0, max[2] ?? 0],
+  };
+}
+
+/** Bake a translation into a mesh (parts are authored in parent space, then offset). */
+export function translate(m: Mesh, by: Vec3): Mesh {
+  const positions = new Float32Array(m.positions);
+  for (let i = 0; i < positions.length; i += 3) {
+    positions[i] = (positions[i] ?? 0) + by[0];
+    positions[i + 1] = (positions[i + 1] ?? 0) + by[1];
+    positions[i + 2] = (positions[i + 2] ?? 0) + by[2];
+  }
+  return { ...m, positions };
+}
+
+export function merge(meshes: readonly Mesh[]): Mesh {
+  // Preallocated from summed lengths: no intermediate arrays, no spread (which overflows the
+  // call stack on very large inputs).
+  const sum = (f: (m: Mesh) => number): number => meshes.reduce((t, m) => t + f(m), 0);
+  const positions = new Float32Array(sum((m) => m.positions.length));
+  const normals = new Float32Array(sum((m) => m.normals.length));
+  const uvs = new Float32Array(sum((m) => m.uvs.length));
+  const colors = new Float32Array(sum((m) => m.colors.length));
+  const indices = new Uint32Array(sum((m) => m.indices.length));
+  let v = 0;
+  let uv = 0;
+  let ix = 0;
+  for (const m of meshes) {
+    positions.set(m.positions, v * 3);
+    normals.set(m.normals, v * 3);
+    colors.set(m.colors, v * 3);
+    uvs.set(m.uvs, uv);
+    for (let i = 0; i < m.indices.length; i++) indices[ix + i] = (m.indices[i] ?? 0) + v;
+    v += m.positions.length / 3;
+    uv += m.uvs.length;
+    ix += m.indices.length;
+  }
+  return { positions, normals, uvs, colors, indices };
+}

package/src/core/part.ts

@@ -0,0 +1,130 @@
+// The part vocabulary: LOD, motion, emitters, sockets, surfaces and the Part record itself —
+// what a recipe can say about one named node.
+
+import type { Mesh } from './mesh.ts';
+import type { Vec3 } from './vec.ts';
+
+/** 0 = hero detail, 1 = mid, 2 = far. A recipe reads it and drops detail; it never decimates. */
+export type Lod = 0 | 1 | 2;
+
+export interface Spin {
+  readonly kind: 'spin';
+  /** Rotation axis in the part's local space. */
+  readonly axis: Vec3;
+  /** Revolutions per second of the baked loop. */
+  readonly rps: number;
+}
+
+export interface Slide {
+  readonly kind: 'slide';
+  /** Peak offset of a sinusoidal back-and-forth (piston rods, sliders). */
+  readonly offset: Vec3;
+  readonly hz: number;
+  /** Move only from rest to rest + offset and back (a sliding door), not to both sides. */
+  readonly oneWay?: boolean;
+}
+
+export interface Sway {
+  readonly kind: 'sway';
+  /** Rotation axis in the part's local space. */
+  readonly axis: Vec3;
+  /** Peak angle either side of rest: turret scan, gun elevation, wind in a crown, a door ajar. */
+  readonly degrees: number;
+  readonly hz: number;
+  /** Swing only from rest to +degrees and back (a signal arm dropping, a hatch opening). */
+  readonly oneWay?: boolean;
+}
+
+export type Motion = Spin | Slide | Sway;
+
+/**
+ * A particle source the engine spawns at runtime: exhaust smoke, loco steam, track dust, muzzle
+ * flash, chimney smoke, fire. Exported as an empty named node carrying `extras.ts23d.emitter`,
+ * so it moves with its parent (a turret, a stack) and any engine can bind its own system to it.
+ */
+export interface Emitter {
+  readonly kind: 'smoke' | 'steam' | 'dust' | 'muzzle' | 'fire' | 'sparks';
+  /** Emission direction in the parent's space; default up (+Z). */
+  readonly dir?: Vec3;
+  /** Particles per second at full intensity. */
+  readonly rate: number;
+  /** Seconds a particle lives. */
+  readonly life: number;
+  /** Start and end size in metres. */
+  readonly size: readonly [number, number];
+  /** Linear sRGB start colour; engines fade to transparent. */
+  readonly color?: Vec3;
+  /** Initial speed m/s along `dir`, with cone spread in degrees. */
+  readonly speed?: number;
+  readonly spreadDeg?: number;
+  /** 'always' (chimney), 'moving' (track dust), 'event' (muzzle — fired by game code). */
+  readonly when?: 'always' | 'moving' | 'event';
+}
+
+/**
+ * A named attachment point game code binds to: a seat, a weapon mount, a camera, a sound source,
+ * a hardpoint, a spawn or interaction point. An empty node with `extras.ts23d.socket`.
+ */
+export interface Socket {
+  readonly kind: 'seat' | 'mount' | 'camera' | 'audio' | 'attach' | 'spawn' | 'interact' | 'light';
+  /** Facing direction in the parent's space; default +X (forward). */
+  readonly dir?: Vec3;
+  /** Free-form, engine-facing: `{ clip: 'engine_idle' }`, `{ caliber: 88 }`, `{ fov: 60 }`. */
+  readonly data?: Readonly<Record<string, string | number | boolean>>;
+}
+
+export interface SocketOptions extends Socket {
+  readonly at?: Vec3;
+  readonly parent?: string;
+}
+
+export interface EmitterOptions extends Emitter {
+  readonly at?: Vec3;
+  readonly parent?: string;
+}
+
+/**
+ * How a part's surface renders. Everything stays on ONE shared texture set; the GLB carries at
+ * most four materials (one per surface in use), so batching still holds:
+ *   opaque — the default trim-sheet material
+ *   cutout — alpha-tested, double-sided: leaves, fences, grilles, ash
+ *   glass — clear: transmission + IOR 1.5 + thin volume (windows, bottles, lamp lenses)
+ *   translucent — tinted, partly see-through: plastic bottles, liquids, paper, smoke-stained glass
+ * Tint comes from vertex colour, as everywhere else.
+ */
+export type Surface = 'opaque' | 'cutout' | 'glass' | 'translucent';
+
+export interface PartOptions {
+  /** Pivot in the parent's space; the mesh is authored relative to it. */
+  readonly at?: Vec3;
+  readonly parent?: string;
+  /** Rotation about local Z, radians. A part that also moves goes inside a yawed group. */
+  readonly yaw?: number;
+  readonly motion?: Motion;
+  /** Parts this moving part may legitimately pass through (an axle in its bearing). QA `clashes`. */
+  readonly clearOf?: readonly string[];
+  readonly surface?: Surface;
+}
+
+export interface UseOptions {
+  /** Prefix for every instanced part: `house_3` → `house_3_roof`, `house_3_door_0`. */
+  readonly prefix: string;
+  readonly at?: Vec3;
+  readonly yaw?: number;
+  readonly parent?: string;
+  /** Per-instance seed, so ten copies of one recipe are ten variants. */
+  readonly seed?: number;
+}
+
+export interface Part {
+  readonly name: string;
+  readonly mesh: Mesh | null;
+  readonly at: Vec3;
+  readonly parent: string | null;
+  readonly yaw: number;
+  readonly motion: Motion | null;
+  readonly clearOf?: readonly string[];
+  readonly emitter?: Emitter;
+  readonly socket?: Socket;
+  readonly surface?: Surface;
+}

package/src/core/png.ts

@@ -0,0 +1,49 @@
+// RGBA → PNG bytes: contact sheets, painted trim sheets, embedded GLB textures. Zero dependencies beyond node:zlib (present in Bun and Node).
+
+import { deflateSync } from 'node:zlib';
+
+const CRC = new Uint32Array(256).map((_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+
+function crc32(bytes: Uint8Array): number {
+  let c = 0xffffffff;
+  for (const b of bytes) c = (CRC[(c ^ b) & 0xff] ?? 0) ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type: string, data: Uint8Array): Uint8Array {
+  const out = new Uint8Array(12 + data.length);
+  const dv = new DataView(out.buffer);
+  dv.setUint32(0, data.length);
+  out.set(new TextEncoder().encode(type), 4);
+  out.set(data, 8);
+  dv.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
+  return out;
+}
+
+export function encodePng(width: number, height: number, rgba: Uint8Array): Uint8Array {
+  const raw = new Uint8Array(height * (width * 4 + 1));
+  for (let y = 0; y < height; y++)
+    raw.set(rgba.subarray(y * width * 4, (y + 1) * width * 4), y * (width * 4 + 1) + 1);
+  const ihdr = new Uint8Array(13);
+  const dv = new DataView(ihdr.buffer);
+  dv.setUint32(0, width);
+  dv.setUint32(4, height);
+  ihdr.set([8, 6, 0, 0, 0], 8);
+  const parts = [
+    new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', new Uint8Array(deflateSync(raw))),
+    chunk('IEND', new Uint8Array()),
+  ];
+  const out = new Uint8Array(parts.reduce((s, p) => s + p.length, 0));
+  let o = 0;
+  for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+  }
+  return out;
+}

package/src/core/rng.ts

@@ -0,0 +1,49 @@
+// Seeded, forkable PRNG (mulberry32). The only entropy a recipe may read: same seed, same bytes.
+
+export interface Rng {
+  /** Uniform in [0, 1). */
+  next(): number;
+  range(min: number, max: number): number;
+  int(min: number, maxInclusive: number): number;
+  pick<T>(items: readonly T[]): T;
+  /** An independent stream keyed by name, so adding a draw in one part never shifts another. */
+  fork(name: string): Rng;
+  /** A colour varied by ±amount per channel (relative): ten bales, ten slightly different straws. */
+  jitter(color: readonly [number, number, number], amount: number): [number, number, number];
+}
+
+function hash(seed: number, name: string): number {
+  let h = seed ^ 0x9e3779b9;
+  for (let i = 0; i < name.length; i++) h = Math.imul(h ^ name.charCodeAt(i), 0x85ebca6b);
+  return (h ^ (h >>> 13)) >>> 0;
+}
+
+export function createRng(seed: number): Rng {
+  let state = seed >>> 0;
+  const next = (): number => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  return {
+    next,
+    range: (min, max) => min + (max - min) * next(),
+    int: (min, max) => min + Math.floor(next() * (max - min + 1)),
+    pick: <T>(items: readonly T[]): T => {
+      const item = items[Math.floor(next() * items.length)];
+      if (item === undefined) throw new RangeError('pick() from an empty list');
+      return item;
+    },
+    fork: (name) => createRng(hash(seed, name)),
+    jitter: (c, amount) => {
+      const k = 1 + (next() * 2 - 1) * amount;
+      return [
+        c[0] * k * (1 + (next() - 0.5) * amount * 0.4),
+        c[1] * k,
+        c[2] * k * (1 + (next() - 0.5) * amount * 0.4),
+      ];
+    },
+  };
+}

package/src/core/transform.ts

@@ -0,0 +1,90 @@
+// Rigid transforms on meshes: place a sub-mesh anywhere at any orientation, then merge. This is
+// how detail is authored — build a rivet/hatch/bracket once in local space, place it N times.
+
+import type { Mesh } from './mesh.ts';
+import type { Vec3 } from './vec.ts';
+
+/** Row-major 3×3 rotation(·scale) + translation. */
+export interface Affine {
+  readonly m: readonly [number, number, number, number, number, number, number, number, number];
+  readonly t: Vec3;
+}
+
+export interface Placement {
+  readonly at?: Vec3;
+  /** Radians about Z (heading), then Y (pitch), then X (roll). */
+  readonly yaw?: number;
+  readonly pitch?: number;
+  readonly roll?: number;
+  readonly scale?: number | Vec3;
+}
+
+export function affine(p: Placement): Affine {
+  const [cy, sy] = [Math.cos(p.yaw ?? 0), Math.sin(p.yaw ?? 0)];
+  const [cp, sp] = [Math.cos(p.pitch ?? 0), Math.sin(p.pitch ?? 0)];
+  const [cr, sr] = [Math.cos(p.roll ?? 0), Math.sin(p.roll ?? 0)];
+  const [kx, ky, kz]: Vec3 =
+    typeof p.scale === 'number' ? [p.scale, p.scale, p.scale] : (p.scale ?? [1, 1, 1]);
+  // R = Rz(yaw) · Ry(pitch) · Rx(roll), columns scaled by (kx, ky, kz).
+  return {
+    m: [
+      cy * cp * kx,
+      (cy * sp * sr - sy * cr) * ky,
+      (cy * sp * cr + sy * sr) * kz,
+      sy * cp * kx,
+      (sy * sp * sr + cy * cr) * ky,
+      (sy * sp * cr - cy * sr) * kz,
+      -sp * kx,
+      cp * sr * ky,
+      cp * cr * kz,
+    ],
+    t: p.at ?? [0, 0, 0],
+  };
+}
+
+/** A basis from an explicit frame: local X→u, Y→v, Z→w (all world vectors). */
+export const frame = (u: Vec3, v: Vec3, w: Vec3, at: Vec3 = [0, 0, 0]): Affine => ({
+  m: [u[0], v[0], w[0], u[1], v[1], w[1], u[2], v[2], w[2]],
+  t: at,
+});
+
+export function applyAffine(mesh: Mesh, a: Affine): Mesh {
+  const { m, t } = a;
+  const positions = new Float32Array(mesh.positions.length);
+  const normals = new Float32Array(mesh.normals.length);
+  for (let i = 0; i < positions.length; i += 3) {
+    const x = mesh.positions[i] ?? 0;
+    const y = mesh.positions[i + 1] ?? 0;
+    const z = mesh.positions[i + 2] ?? 0;
+    positions[i] = m[0] * x + m[1] * y + m[2] * z + t[0];
+    positions[i + 1] = m[3] * x + m[4] * y + m[5] * z + t[1];
+    positions[i + 2] = m[6] * x + m[7] * y + m[8] * z + t[2];
+    const nx = mesh.normals[i] ?? 0;
+    const ny = mesh.normals[i + 1] ?? 0;
+    const nz = mesh.normals[i + 2] ?? 0;
+    // Rigid + uniform scale: rotating the normal and renormalising is exact.
+    const rx = m[0] * nx + m[1] * ny + m[2] * nz;
+    const ry = m[3] * nx + m[4] * ny + m[5] * nz;
+    const rz = m[6] * nx + m[7] * ny + m[8] * nz;
+    const l = Math.hypot(rx, ry, rz) || 1;
+    normals[i] = rx / l;
+    normals[i + 1] = ry / l;
+    normals[i + 2] = rz / l;
+  }
+  // A mirror (det < 0) turns counter-clockwise triangles clockwise: flip each one back, or
+  // engines cull the outside and draw the inside.
+  const det =
+    m[0] * (m[4] * m[8] - m[5] * m[7]) -
+    m[1] * (m[3] * m[8] - m[5] * m[6]) +
+    m[2] * (m[3] * m[7] - m[4] * m[6]);
+  if (det >= 0) return { ...mesh, positions, normals };
+  const indices = mesh.indices.slice();
+  for (let t = 0; t + 2 < indices.length; t += 3) {
+    const b = indices[t + 1] ?? 0;
+    indices[t + 1] = indices[t + 2] ?? 0;
+    indices[t + 2] = b;
+  }
+  return { ...mesh, positions, normals, indices };
+}
+
+export const place = (mesh: Mesh, p: Placement): Mesh => applyAffine(mesh, affine(p));

package/src/core/vec.ts

@@ -0,0 +1,26 @@
+// Minimal vector math. Units are metres, Z is up, +X is an asset's "front" (docs/idea/03-ir.md).
+
+export type Vec2 = readonly [number, number];
+export type Vec3 = readonly [number, number, number];
+export type Quat = readonly [number, number, number, number];
+
+export const add = (a: Vec3, b: Vec3): Vec3 => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const sub = (a: Vec3, b: Vec3): Vec3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+export const scale = (a: Vec3, s: number): Vec3 => [a[0] * s, a[1] * s, a[2] * s];
+export const dot = (a: Vec3, b: Vec3): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+export const cross = (a: Vec3, b: Vec3): 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],
+];
+export const length = (a: Vec3): number => Math.hypot(a[0], a[1], a[2]);
+export const normalize = (a: Vec3): Vec3 => {
+  const l = length(a);
+  return l === 0 ? [0, 0, 0] : scale(a, 1 / l);
+};
+
+export function quatFromAxisAngle(axis: Vec3, radians: number): Quat {
+  const [x, y, z] = normalize(axis);
+  const s = Math.sin(radians / 2);
+  return [x * s, y * s, z * s, Math.cos(radians / 2)];
+}