@es3d/es3d 0.0.0-stage → 1.0.1

package/src/scene/picking.js

@@ -0,0 +1,161 @@
+// CPU ray picking against the instance table.
+//
+// Each instance is tested with a world-space bounding-sphere check, then the
+// ray is transformed into the instance's canonical mesh space (inverse world
+// matrix) and tested against the canonical bounds and finally the triangles
+// (Möller–Trumbore). Because instancing keeps one canonical mesh per
+// geometry, picking cost scales with visible instances, not with triangles.
+
+import * as mat4 from '../math/mat4.js';
+
+function raySphere(ox, oy, oz, dx, dy, dz, cx, cy, cz, r) {
+  const lx = cx - ox, ly = cy - oy, lz = cz - oz;
+  const tca = lx * dx + ly * dy + lz * dz;
+  const d2 = lx * lx + ly * ly + lz * lz - tca * tca;
+  if (d2 > r * r) return Infinity;
+  const thc = Math.sqrt(r * r - d2);
+  const t0 = tca - thc;
+  const t1 = tca + thc;
+  if (t1 < 0) return Infinity;
+  return t0 < 0 ? 0 : t0;
+}
+
+function rayBox(o, d, b) {
+  let tmin = -Infinity, tmax = Infinity;
+  for (let k = 0; k < 3; k++) {
+    const pad = 1e-6 + (b.max[k] - b.min[k]) * 1e-4;
+    const lo = b.min[k] - pad, hi = b.max[k] + pad;
+    if (Math.abs(d[k]) < 1e-20) {
+      if (o[k] < lo || o[k] > hi) return false;
+    } else {
+      let t1 = (lo - o[k]) / d[k];
+      let t2 = (hi - o[k]) / d[k];
+      if (t1 > t2) [t1, t2] = [t2, t1];
+      tmin = Math.max(tmin, t1);
+      tmax = Math.min(tmax, t2);
+      if (tmin > tmax) return false;
+    }
+  }
+  return tmax >= 0;
+}
+
+let hitTriangle = -1; // first index of the triangle found by the last rayTriangles call
+
+/**
+ * Nearest triangle hit closer than `best`. With `facing` (+1 or -1) only
+ * triangles whose front side faces the ray origin count: det > 0 means the
+ * ray meets the counter-clockwise side, and `facing` is -1 for mirrored instances.
+ */
+function rayTriangles(o, d, mesh, best, facing = 0) {
+  const p = mesh.positions;
+  const idx = mesh.indices;
+  let tBest = best;
+  hitTriangle = -1;
+  for (let i = 0; i < idx.length; i += 3) {
+    const a = idx[i] * 3, b = idx[i + 1] * 3, c = idx[i + 2] * 3;
+    const e1x = p[b] - p[a], e1y = p[b + 1] - p[a + 1], e1z = p[b + 2] - p[a + 2];
+    const e2x = p[c] - p[a], e2y = p[c + 1] - p[a + 1], e2z = p[c + 2] - p[a + 2];
+    const px = d[1] * e2z - d[2] * e2y, py = d[2] * e2x - d[0] * e2z, pz = d[0] * e2y - d[1] * e2x;
+    const det = e1x * px + e1y * py + e1z * pz;
+    if (Math.abs(det) < 1e-18) continue;
+    if (facing && det * facing < 0) continue;
+    const inv = 1 / det;
+    const tx = o[0] - p[a], ty = o[1] - p[a + 1], tz = o[2] - p[a + 2];
+    const u = (tx * px + ty * py + tz * pz) * inv;
+    if (u < 0 || u > 1) continue;
+    const qx = ty * e1z - tz * e1y, qy = tz * e1x - tx * e1z, qz = tx * e1y - ty * e1x;
+    const v = (d[0] * qx + d[1] * qy + d[2] * qz) * inv;
+    if (v < 0 || u + v > 1) continue;
+    const t = (e2x * qx + e2y * qy + e2z * qz) * inv;
+    if (t > 1e-9 && t < tBest) {
+      tBest = t;
+      hitTriangle = i;
+    }
+  }
+  return tBest;
+}
+
+/**
+ * Nearest surface along a ray.
+ * @param {import('./flatten.js').RenderScene} scene
+ * @param {(entry:object, lod:number)=>import('../geometry/mesh.js').Mesh} meshOf
+ * @param {number[]} origin world ray origin
+ * @param {number[]} dir world ray direction (normalized)
+ * @param {{isVisible?: (i:number)=>boolean, maxDistance?: number, skipFlags?: number, facing?: boolean}} [opts]
+ *   skipFlags: instances with any of these flag bits are ignored. facing: only
+ *   surfaces whose front side faces the origin (double-sided geometry always counts).
+ * @returns {{index:number, uid:number, distance:number, point:number[], normal:number[]}|null}
+ *   normal is the world-space surface normal turned against the ray.
+ */
+export function raycast(scene, meshOf, origin, dir, opts = {}) {
+  const { isVisible = null, maxDistance = Infinity, skipFlags = 0, facing = false } = opts;
+  const cands = [];
+  const S = scene.spheres;
+  for (let i = 0; i < scene.count; i++) {
+    if (skipFlags && scene.flags[i] & skipFlags) continue;
+    if (isVisible && !isVisible(i)) continue;
+    const entry = scene.geometries[scene.geom[i]];
+    if (entry.kind !== 'triangles') continue;
+    const t = raySphere(origin[0], origin[1], origin[2], dir[0], dir[1], dir[2], S[i * 4], S[i * 4 + 1], S[i * 4 + 2], S[i * 4 + 3]);
+    if (t < maxDistance) cands.push([t, i]);
+  }
+  cands.sort((a, b) => a[0] - b[0]);
+  let best = maxDistance;
+  let bestIndex = -1;
+  let bestTriangle = -1;
+  const normal = [0, 0, 0];
+  const m = new Float64Array(16);
+  const inv = new Float64Array(16);
+  const lo = [0, 0, 0];
+  const ld = [0, 0, 0];
+  for (const [tSphere, i] of cands) {
+    if (tSphere > best) break;
+    for (let k = 0; k < 16; k++) m[k] = scene.matrices[i * 16 + k];
+    if (!mat4.invert(inv, m)) continue;
+    mat4.transformPoint(lo, inv, origin[0], origin[1], origin[2]);
+    mat4.transformDir(ld, inv, dir[0], dir[1], dir[2]);
+    const entry = scene.geometries[scene.geom[i]];
+    if (entry.bounds && !rayBox(lo, ld, entry.bounds)) continue;
+    const mesh = meshOf(entry, 0);
+    const material = scene.materials[scene.mat[i]];
+    const twoSided = entry.doubleSided || (material && material.doubleSided);
+    const front = facing && !twoSided ? (scene.flags[i] & 1 ? -1 : 1) : 0;
+    // t is in world units because the direction was transformed linearly (not renormalized)
+    const t = rayTriangles(lo, ld, mesh, best, front);
+    if (t < best) {
+      best = t;
+      bestIndex = i;
+      bestTriangle = hitTriangle;
+      // triangle normal to world space with the inverse transpose
+      const p = mesh.positions, idx = mesh.indices;
+      const a = idx[bestTriangle] * 3, b = idx[bestTriangle + 1] * 3, c = idx[bestTriangle + 2] * 3;
+      const e1 = [p[b] - p[a], p[b + 1] - p[a + 1], p[b + 2] - p[a + 2]];
+      const e2 = [p[c] - p[a], p[c + 1] - p[a + 1], p[c + 2] - p[a + 2]];
+      const n = [e1[1] * e2[2] - e1[2] * e2[1], e1[2] * e2[0] - e1[0] * e2[2], e1[0] * e2[1] - e1[1] * e2[0]];
+      for (let k = 0; k < 3; k++) normal[k] = inv[k * 4] * n[0] + inv[k * 4 + 1] * n[1] + inv[k * 4 + 2] * n[2];
+    }
+  }
+  if (bestIndex < 0) return null;
+  const nl = Math.hypot(normal[0], normal[1], normal[2]) || 1;
+  const sign = normal[0] * dir[0] + normal[1] * dir[1] + normal[2] * dir[2] > 0 ? -1 : 1;
+  return {
+    index: bestIndex,
+    uid: scene.uid[bestIndex],
+    distance: best,
+    point: [origin[0] + dir[0] * best, origin[1] + dir[1] * best, origin[2] + dir[2] * best],
+    normal: [(normal[0] / nl) * sign, (normal[1] / nl) * sign, (normal[2] / nl) * sign],
+  };
+}
+
+/**
+ * Element under a ray (for selection).
+ * @param {import('./flatten.js').RenderScene} scene
+ * @param {(entry:object, lod:number)=>import('../geometry/mesh.js').Mesh} meshOf
+ * @param {number[]} origin world ray origin
+ * @param {number[]} dir world ray direction (normalized)
+ * @param {(i:number)=>boolean} [isVisible]
+ * @returns {{index:number, uid:number, distance:number, point:number[], normal:number[]}|null}
+ */
+export function pick(scene, meshOf, origin, dir, isVisible = null) {
+  return raycast(scene, meshOf, origin, dir, { isVisible });
+}

package/src/scene/scene-graph.js

@@ -0,0 +1,320 @@
+// Scene graph construction: validated AST -> SceneNode tree.
+//
+// Every renderable element becomes one SceneNode with its static local matrix
+// pre-computed. Nodes are memoised per element, so a definition referenced by
+// a thousand <use> elements exists once in memory: instancing is resolved by
+// traversal, not by copying subtrees. Materials are collected into a table,
+// geometry descriptors are interned in the geometry cache (lazy tessellation).
+
+import * as mat4 from '../math/mat4.js';
+import { valueOf, elementSpec } from '../format/schema.js';
+import { localMatrix } from '../transform/transform.js';
+import { describeShape, hasGeometry } from '../geometry/registry.js';
+import { MaterialTable, paramsFromElement } from '../material/materials.js';
+import { animationFromElement } from './animation.js';
+import { MAX_INSTANCES, MAX_DEPTH } from '../format/limits.js';
+
+export { MAX_INSTANCES, MAX_DEPTH };
+
+export class SceneNode {
+  constructor(el, kind) {
+    this.el = el;
+    this.uid = el.uid;
+    this.kind = kind;
+    this.local = null; // static local matrix (Float64Array) or null for identity
+    this.visible = true;
+    this.material = null;
+    this.color = null;
+    this.anims = [];
+    this.children = [];
+    // shape
+    this.geometry = null;
+    this.unit = null;
+    // use
+    this.target = null;
+    // repeat
+    this.count = 0;
+    this.step = null;
+    // scatter / lod / light / camera parameters
+    this.params = null;
+  }
+
+  get animated() {
+    return this.anims.length > 0;
+  }
+}
+
+const ENV_DEFAULTS = {
+  background: [0.09, 0.1, 0.12, 1],
+  sky: [0.8, 0.86, 0.95, 1],
+  ground: [0.25, 0.22, 0.2, 1],
+  intensity: 0.5,
+  exposure: 1,
+};
+
+function isIdentity(m) {
+  return mat4.isIdentity(m, 1e-15);
+}
+
+/**
+ * @param {import('../format/ast.js').Document} doc validated document
+ * @param {import('../geometry/geometry-cache.js').GeometryCache} cache
+ */
+export function buildSceneGraph(doc, cache, opts = {}) {
+  const maxInstances = opts.maxInstances || MAX_INSTANCES;
+  const diagnostics = [];
+  const materials = new MaterialTable();
+  const memo = new Map();
+  let environment = { ...ENV_DEFAULTS, explicit: false };
+  let envFound = false;
+  let controls = null;
+  // which clocks drive the document: viewers skip per-frame work for the ones it does not use
+  const animation = { time: false, scroll: false };
+  const stats = { nodes: 0, shapes: 0, uses: 0, defs: 0, lights: 0, cameras: 0, materials: 0 };
+
+  const report = (el, severity, code, message, phase = 'reference') => {
+    diagnostics.push({ severity, code, message, element: el, phase });
+  };
+
+  // materials and environment are document-wide
+  const collect = (el) => {
+    if (el.unknown) return;
+    if (el.name === 'material' && el.values && el.values.id !== undefined) {
+      materials.define(el.values.id, paramsFromElement(el));
+      stats.materials++;
+    }
+    if (el.name === 'environment' && !envFound) {
+      envFound = true;
+      environment = {
+        background: valueOf(el, 'background'),
+        sky: valueOf(el, 'sky'),
+        ground: valueOf(el, 'ground'),
+        intensity: valueOf(el, 'intensity'),
+        exposure: valueOf(el, 'exposure'),
+        explicit: true,
+        uid: el.uid,
+      };
+    }
+    if (el.name === 'controls' && !controls) controls = controlsFromElement(el);
+    if (el.name === 'defs') stats.defs += el.children.filter((c) => c.type === 'element').length;
+    for (const c of el.children) if (c.type === 'element') collect(c);
+  };
+  collect(doc.root);
+
+  cache.beginBuild();
+
+  const nodeFor = (el, depth = 0) => {
+    if (memo.has(el)) return memo.get(el);
+    if (depth > MAX_DEPTH) {
+      report(el, 'error', 'E_TOO_DEEP', `Nesting is deeper than ${MAX_DEPTH}. Flatten the tree or shorten the use chain.`);
+      memo.set(el, null);
+      return null;
+    }
+    if (el.unknown || !elementSpec(el.name)) {
+      memo.set(el, null);
+      return null;
+    }
+    const name = el.name;
+    let kind;
+    if (name === 'es3d' || name === 'v3d' || name === 'scene' || name === 'group') kind = 'group';
+    else if (name === 'use') kind = 'use';
+    else if (name === 'repeat') kind = 'repeat';
+    else if (name === 'scatter') kind = 'scatter';
+    else if (name === 'lod') kind = 'lod';
+    else if (name === 'light') kind = 'light';
+    else if (name === 'camera') kind = 'camera';
+    else if (hasGeometry(name)) kind = 'shape';
+    else {
+      memo.set(el, null);
+      return null;
+    }
+    const node = new SceneNode(el, kind);
+    memo.set(el, node);
+    stats.nodes++;
+    const v = el.values || {};
+    if (kind !== 'camera' && kind !== 'light') {
+      const m = localMatrix(v);
+      node.local = isIdentity(m) ? null : m;
+    }
+    node.visible = valueOf(el, 'visible') !== false;
+    node.collide = v.collide !== false;
+    node.material = v.material !== undefined ? v.material : null;
+    node.color = v.color !== undefined ? v.color : null;
+    const position = valueOf(el, 'position') || [0, 0, 0];
+    node.base = {
+      position,
+      rotation: valueOf(el, 'rotation') || [0, 0, 0],
+      scale: valueOf(el, 'scale') || [1, 1, 1],
+    };
+    if (kind === 'camera') {
+      // a camera without a target looks down -Z: start a target animation from there
+      node.base.target = v.target || [position[0], position[1], position[2] - 1];
+      node.base.fov = [valueOf(el, 'fov')];
+    }
+
+    for (const c of el.children) {
+      if (c.type !== 'element') continue;
+      if (c.name === 'animate') {
+        if (!c.unknown && c.values && c.values.attr) {
+          const a = animationFromElement(c, node.base);
+          node.anims.push(a);
+          animation[a.timeline === 'scroll' ? 'scroll' : 'time'] = true;
+        }
+        continue;
+      }
+      if (name === 'es3d' || name === 'v3d') {
+        if (c.name === 'defs' || c.name === 'title' || c.name === 'desc' || c.name === 'environment' || c.name === 'material') continue;
+      }
+      if (c.name === 'material' || c.name === 'environment' || c.name === 'controls') continue;
+      const child = nodeFor(c, depth + 1);
+      if (child) node.children.push(child);
+    }
+
+    switch (kind) {
+      case 'shape': {
+        stats.shapes++;
+        let desc = null;
+        try {
+          desc = describeShape(el, {});
+        } catch (err) {
+          report(el, 'error', 'E_GEOMETRY', `Cannot describe <${name}>: ${err.message}`, 'geometry');
+        }
+        if (desc) {
+          node.geometry = cache.acquire(desc, el);
+          node.unit = desc.unit && !isIdentity(desc.unit) ? desc.unit : null;
+        } else if (!diagnostics.some((d) => d.element === el)) {
+          report(el, 'error', 'E_GEOMETRY', `<${name}> has no usable geometry source.`, 'geometry');
+        }
+        break;
+      }
+      case 'use':
+        stats.uses++;
+        if (el.target && !el.circular) node.target = nodeFor(el.target, depth + 1);
+        break;
+      case 'repeat':
+        node.count = v.count || 0;
+        node.step = v.step ? v.step.matrix : mat4.createF64();
+        break;
+      case 'scatter':
+        node.params = {
+          grid: v.grid || null,
+          count: v.grid ? v.grid[0] * v.grid[1] : v.count || 0,
+          spacing: valueOf(el, 'spacing'),
+          area: v.area || null,
+          radius: v.radius || null,
+          seed: valueOf(el, 'seed'),
+          jitter: valueOf(el, 'jitter'),
+          randomScale: v.randomScale || null,
+          randomRotation: v.randomRotation || null,
+          randomMaterial: v.randomMaterial || null,
+        };
+        break;
+      case 'lod':
+        node.params = { distances: v.distances || [] };
+        break;
+      case 'light': {
+        stats.lights++;
+        const m = mat4.createF64();
+        if (v.transform) m.set(v.transform.matrix);
+        node.params = {
+          type: v.type,
+          color: valueOf(el, 'color'),
+          intensity: valueOf(el, 'intensity'),
+          position: valueOf(el, 'position'),
+          rotation: v.rotation || null,
+          direction: v.direction || null,
+          target: v.target || null,
+          range: valueOf(el, 'range'),
+          angle: valueOf(el, 'angle'),
+          penumbra: valueOf(el, 'penumbra'),
+          groundColor: valueOf(el, 'groundColor'),
+          transform: v.transform ? m : null,
+        };
+        break;
+      }
+      case 'camera': {
+        stats.cameras++;
+        node.params = {
+          type: valueOf(el, 'type'),
+          position: valueOf(el, 'position'),
+          target: v.target || null,
+          rotation: v.rotation || null,
+          up: valueOf(el, 'up'),
+          fov: valueOf(el, 'fov'),
+          height: valueOf(el, 'height'),
+          near: v.near || null,
+          far: v.far || null,
+          aspect: valueOf(el, 'aspect'),
+          fit: valueOf(el, 'fit'),
+          transform: v.transform ? v.transform.matrix : null,
+          name: v.name || v.id || `camera ${stats.cameras}`,
+        };
+        break;
+      }
+      default:
+        break;
+    }
+    return node;
+  };
+
+  const root = doc.root ? nodeFor(doc.root) : null;
+  cache.endBuild();
+
+  // expanded instance count (memoised per node) guards against accidental explosions
+  const counts = new Map();
+  const countOf = (node) => {
+    if (!node) return 0;
+    if (counts.has(node)) return counts.get(node);
+    counts.set(node, 0); // cycle guard
+    let n = 0;
+    const kids = () => node.children.reduce((s, c) => s + countOf(c), 0);
+    switch (node.kind) {
+      case 'shape':
+        n = node.geometry ? 1 : 0;
+        break;
+      case 'use':
+        n = countOf(node.target);
+        break;
+      case 'repeat':
+        n = node.count * kids();
+        break;
+      case 'scatter':
+        n = node.params.count * kids();
+        break;
+      case 'light':
+      case 'camera':
+        n = 0;
+        break;
+      default:
+        n = kids();
+    }
+    if (!node.visible) n = 0;
+    counts.set(node, n);
+    return n;
+  };
+  const expanded = countOf(root);
+  stats.expandedInstances = expanded;
+  if (expanded > maxInstances) {
+    report(doc.root, 'error', 'E_TOO_MANY_INSTANCES', `The scene expands to ${expanded.toLocaleString('en-US')} instances, more than the limit of ${maxInstances.toLocaleString('en-US')}. Reduce repeat or scatter counts.`, 'render');
+  }
+
+  return { doc, root, materials, environment, controls, animation, cache, diagnostics, stats, tooLarge: expanded > maxInstances, expanded };
+}
+
+/** Viewer settings from a <controls> element (angles in degrees, as written). */
+function controlsFromElement(el) {
+  const v = el.values || {};
+  return {
+    mode: valueOf(el, 'mode'),
+    zoom: valueOf(el, 'zoom'),
+    pan: valueOf(el, 'pan'),
+    minDistance: v.minDistance ?? null,
+    maxDistance: v.maxDistance ?? null,
+    minPolar: valueOf(el, 'minPolar'),
+    maxPolar: valueOf(el, 'maxPolar'),
+    targetMin: v.targetMin && v.targetMax ? v.targetMin : null,
+    targetMax: v.targetMin && v.targetMax ? v.targetMax : null,
+    collide: valueOf(el, 'collide'),
+    uid: el.uid,
+  };
+}

package/src/transform/transform.js

@@ -0,0 +1,211 @@
+// The ES3D transform system.
+//
+// transform="translate(0,2,0) rotate(0,45,0) scale(2)" is read exactly like
+// SVG: functions are applied left to right as nested coordinate systems, so the
+// resulting matrix is T1 * T2 * T3 (the rightmost function acts on the object
+// first). Supported functions:
+//
+//   translate(x[,y[,z]])      rotate(x,y,z)  Euler degrees (X, then Y, then Z)
+//   rotateX(a) rotateY(a) rotateZ(a)         rotate(a, ax,ay,az) axis-angle
+//   scale(s) | scale(x,y,z)                  quat(x,y,z,w)
+//   matrix(m0..m15)  16 numbers, column-major (like CSS matrix3d)
+//
+// Elements additionally accept position / rotation / scale attributes. The
+// local matrix of an element is   transform * T(position) * R(rotation) * S(scale)
+// mirroring SVG <use>, where x/y are applied after (inside) the transform.
+
+import * as mat4 from '../math/mat4.js';
+import { ValueError } from '../format/value-error.js';
+import { suggest } from '../format/errors.js';
+import { readNumber, numberValue } from '../path/path-parser.js';
+
+const FUNCS = {
+  translate: [1, 3],
+  rotate: [3, 4],
+  rotateX: [1, 1],
+  rotateY: [1, 1],
+  rotateZ: [1, 1],
+  scale: [1, 3],
+  matrix: [16, 16],
+  quat: [4, 4],
+};
+
+function isWs(c) {
+  return c === 32 || c === 9 || c === 10 || c === 13 || c === 44; // comma acts as separator between functions
+}
+
+/** Parse a transform list into operations (validated, with offsets). */
+export function parseTransformOps(str) {
+  const ops = [];
+  const n = str.length;
+  let i = 0;
+  while (true) {
+    while (i < n && isWs(str.charCodeAt(i))) i++;
+    if (i >= n) break;
+    const nameStart = i;
+    while (i < n && /[A-Za-z0-9]/.test(str[i])) i++;
+    const fn = str.slice(nameStart, i);
+    if (!fn) throw new ValueError(`Unexpected character '${str[i]}' in transform.`, i, 1);
+    if (!(fn in FUNCS)) {
+      throw new ValueError(`Unknown transform function '${fn}'.`, nameStart, fn.length, {
+        suggestion: suggest(fn, Object.keys(FUNCS)),
+        hint: 'Valid functions: translate, rotate, rotateX, rotateY, rotateZ, scale, matrix, quat.',
+      });
+    }
+    while (i < n && (str[i] === ' ' || str[i] === '\t')) i++;
+    if (str[i] !== '(') throw new ValueError(`Expected '(' after '${fn}'.`, i, 1);
+    i++;
+    const args = [];
+    for (;;) {
+      while (i < n && /[\s,]/.test(str[i])) i++;
+      if (str[i] === ')') {
+        i++;
+        break;
+      }
+      if (i >= n) throw new ValueError(`Missing ')' to close '${fn}('.`, nameStart, fn.length + 1);
+      const end = readNumber(str, i);
+      if (end < 0) throw new ValueError(`Expected a number in '${fn}()' but found '${str[i]}'.`, i, 1);
+      args.push(numberValue);
+      i = end;
+    }
+    const [min, max] = FUNCS[fn];
+    if (args.length < min || args.length > max) {
+      let hint;
+      if (fn === 'rotate' && args.length === 1) hint = 'rotate() takes Euler angles rotate(x,y,z) or an axis-angle rotate(a,ax,ay,az); use rotateY(a) for a single angle.';
+      if (fn === 'rotate' && args.length === 2) hint = 'rotate() takes 3 Euler angles in degrees, e.g. rotate(0,45,0).';
+      throw new ValueError(
+        `${fn}() takes ${min === max ? min : `${min} to ${max}`} numbers but ${args.length} ${args.length === 1 ? 'was' : 'were'} given.`,
+        nameStart,
+        i - nameStart,
+        { hint },
+      );
+    }
+    if (fn === 'rotate' && args.length === 4 && Math.hypot(args[1], args[2], args[3]) < 1e-12) {
+      throw new ValueError('rotate(angle, ax, ay, az): the rotation axis must not be zero.', nameStart, i - nameStart);
+    }
+    if (fn === 'scale' && args.length === 2) {
+      throw new ValueError('scale() takes 1 (uniform) or 3 numbers.', nameStart, i - nameStart);
+    }
+    ops.push({ fn, args, offset: nameStart });
+  }
+  return ops;
+}
+
+/** Matrix of a single transform operation. */
+export function opMatrix(op, out = mat4.createF64()) {
+  const a = op.args;
+  switch (op.fn) {
+    case 'translate':
+      return mat4.fromTranslation(out, a[0], a[1] || 0, a[2] || 0);
+    case 'rotate':
+      if (a.length === 4) return mat4.fromAxisAngle(out, a[1], a[2], a[3], a[0] * mat4.DEG);
+      return mat4.fromEulerDeg(out, a[0], a[1], a[2]);
+    case 'rotateX':
+      return mat4.fromRotationX(out, a[0] * mat4.DEG);
+    case 'rotateY':
+      return mat4.fromRotationY(out, a[0] * mat4.DEG);
+    case 'rotateZ':
+      return mat4.fromRotationZ(out, a[0] * mat4.DEG);
+    case 'scale':
+      return a.length === 1 ? mat4.fromScaling(out, a[0], a[0], a[0]) : mat4.fromScaling(out, a[0], a[1], a[2]);
+    case 'matrix':
+      for (let k = 0; k < 16; k++) out[k] = a[k];
+      return out;
+    case 'quat':
+      return mat4.fromQuat(out, a[0], a[1], a[2], a[3]);
+    default:
+      throw new Error(`unknown transform ${op.fn}`);
+  }
+}
+
+export function opsToMatrix(ops) {
+  const m = mat4.createF64();
+  const t = mat4.createF64();
+  for (const op of ops) {
+    opMatrix(op, t);
+    mat4.multiply(m, m, t);
+  }
+  return m;
+}
+
+/**
+ * {ops, matrix} for already separated operations (binary decoding), applying
+ * the same rules as the text parser; null when an operation is invalid.
+ */
+export function transformFromOps(ops) {
+  for (const op of ops) {
+    const range = FUNCS[op.fn];
+    if (!range) return null;
+    const n = op.args.length;
+    if (n < range[0] || n > range[1] || !op.args.every(Number.isFinite)) return null;
+    if (op.fn === 'rotate' && n === 4 && Math.hypot(op.args[1], op.args[2], op.args[3]) < 1e-12) return null;
+    if (op.fn === 'scale' && n === 2) return null;
+  }
+  return { ops, matrix: opsToMatrix(ops) };
+}
+
+/** Parse a transform attribute value into {ops, matrix}. */
+export function parseTransform(str) {
+  const ops = parseTransformOps(str);
+  return { ops, matrix: opsToMatrix(ops) };
+}
+
+const ZERO = [0, 0, 0];
+const ONE = [1, 1, 1];
+
+/**
+ * Local matrix of an element from its typed values:
+ *   transform * T(position) * R(rotation) * S(scale)
+ */
+export function localMatrix(values, out = mat4.createF64(), overrides = null) {
+  const position = (overrides && overrides.position) || values.position || ZERO;
+  const rotation = (overrides && overrides.rotation) || values.rotation || ZERO;
+  const scale = (overrides && overrides.scale) || values.scale || ONE;
+  mat4.compose(out, position, rotation, scale);
+  const tr = values.transform;
+  if (tr && tr.ops.length) mat4.multiply(out, tr.matrix, out);
+  return out;
+}
+
+/** Format a matrix as a transform string (used by serializers / expansion). */
+export function matrixToTransformString(m, fmt) {
+  const d = mat4.decompose(m);
+  if (d) {
+    const parts = [];
+    const [tx, ty, tz] = d.translation;
+    if (Math.abs(tx) > 1e-9 || Math.abs(ty) > 1e-9 || Math.abs(tz) > 1e-9) parts.push(`translate(${fmt(tx)},${fmt(ty)},${fmt(tz)})`);
+    const [qx, qy, qz, qw] = d.rotation;
+    if (Math.abs(qx) > 1e-9 || Math.abs(qy) > 1e-9 || Math.abs(qz) > 1e-9) parts.push(`quat(${fmt(qx)},${fmt(qy)},${fmt(qz)},${fmt(qw)})`);
+    const [sx, sy, sz] = d.scale;
+    if (Math.abs(sx - 1) > 1e-9 || Math.abs(sy - 1) > 1e-9 || Math.abs(sz - 1) > 1e-9) {
+      if (Math.abs(sx - sy) < 1e-9 && Math.abs(sy - sz) < 1e-9) parts.push(`scale(${fmt(sx)})`);
+      else parts.push(`scale(${fmt(sx)},${fmt(sy)},${fmt(sz)})`);
+    }
+    return parts.join(' ');
+  }
+  return `matrix(${Array.from(m, fmt).join(',')})`;
+}
+
+/**
+ * Decompose a shear-free affine matrix into translation, ES3D Euler angles
+ * (degrees, R = Rz * Ry * Rx) and scale. Returns null when shear is present.
+ */
+export function matrixToEuler(m) {
+  const d = mat4.decompose(m);
+  if (!d) return null;
+  const [sx, sy, sz] = d.scale;
+  const r = [m[0] / sx, m[1] / sx, m[2] / sx, m[4] / sy, m[5] / sy, m[6] / sy, m[8] / sz, m[9] / sz, m[10] / sz];
+  const R2 = Math.max(-1, Math.min(1, -r[2]));
+  const y = Math.asin(R2);
+  let x, z;
+  if (Math.abs(R2) < 0.9999999) {
+    x = Math.atan2(r[5], r[8]);
+    z = Math.atan2(r[1], r[0]);
+  } else {
+    // gimbal lock: rotation about X and Z are coupled; put everything into Z
+    x = 0;
+    z = Math.atan2(-r[3], r[4]);
+  }
+  const deg = (v) => (v * 180) / Math.PI;
+  return { translation: d.translation, rotation: [deg(x), deg(y), deg(z)], scale: d.scale };
+}