@solidrt/3d 0.0.47 → 0.0.48

package/src/profile.ts

@@ -1,20 +1,14 @@
-// Profile kit: 3D geometry from 2D outlines. A Profile is a closed simple
-// polygon in the XY plane - bare [x, y] tuples are sharp (creased) corners,
-// tagged { p, smooth } points shade round - and winding is normalized to
-// CCW on use, so either authoring direction works. extrude() sweeps a
-// profile along z with an optional quarter-round bevel, lathe() revolves
-// one about the y axis, shape() fills one as a flat face; fillet() and
-// roundRect() produce smooth-tagged arc corners, and triangulate() (the
-// ear-clipping core behind every cap) is exported for custom flat work.
-//
-// Output is the shared vertex layout of geometry.ts with real texture UVs.
-// Winding is CCW seen from outside like every generator, so cull: "back"
-// works: sharp profile points emit one vertex per adjacent edge, smooth
-// points one vertex with the averaged normal. Indices pick Uint16Array or
-// Uint32Array by vertex count - filleted profiles times bevel slices make
-// dense outputs routine here.
+// Profile kit: the 2D outline vocabulary the solid generators build on. A
+// Profile is a closed simple polygon in the XY plane - bare [x, y] tuples
+// are sharp (creased) corners, tagged { p, smooth } points shade round -
+// and winding is normalized to CCW on use, so either authoring direction
+// works. fillet() and roundRect() produce smooth-tagged arc corners,
+// shape() fills a profile as a flat +z face in the shared vertex layout,
+// and triangulate() (the ear-clipping core behind every cap) is exported
+// for custom flat work. The swept-solid generators consuming this
+// vocabulary - extrude, lathe, sweep, tube - live in sweep.ts.
 
-import { FLOATS_PER_VERTEX } from "./geometry.ts"
+import { packIndices } from "./geometry.ts"
 import type { Geometry } from "./geometry.ts"
 import type { Vec2 } from "./math.ts"
 
@@ -27,13 +21,14 @@ export type ProfilePoint = { p: Vec2; smooth?: boolean }
  * go either way; consumers normalize to CCW. */
 export type Profile = (Vec2 | ProfilePoint)[]
 
-type Pt = { x: number; y: number; smooth: boolean }
+/** A normalized profile point (normalizeProfile's output). */
+export type Pt = { x: number; y: number; smooth: boolean }
 
-// One side-strip vertex of the profile ring: position, outward 2D normal,
-// owning point index (for miter lookup) and normalized perimeter
-// parameter. Sharp points appear twice (once per edge normal); the list
-// ends with a copy of the first entry at t = 1, the UV seam.
-type RingEntry = { x: number; y: number; nx: number; ny: number; point: number; t: number }
+/** One side-strip vertex of the profile ring: position, outward 2D normal,
+ * owning point index (for miter lookup) and normalized perimeter
+ * parameter. Sharp points appear twice (once per edge normal); the list
+ * ends with a copy of the first entry at t = 1, the UV seam. */
+export type RingEntry = { x: number; y: number; nx: number; ny: number; point: number; t: number }
 
 function signedArea(px: number[], py: number[]): number {
   let a = 0
@@ -44,9 +39,10 @@ function signedArea(px: number[], py: number[]): number {
   return a / 2
 }
 
-// Tag/tuple points to one shape, consecutive duplicates (including a
-// closing repeat of the first point) dropped, winding forced CCW.
-function normalizeProfile(profile: Profile): Pt[] {
+/** Tag/tuple points to one shape, consecutive duplicates (including a
+ * closing repeat of the first point) dropped, winding forced CCW - the
+ * shared entry point of every profile consumer. */
+export function normalizeProfile(profile: Profile): Pt[] {
   let pts: Pt[] = []
   for (let point of profile) {
     let x: number, y: number, smooth: boolean
@@ -68,11 +64,11 @@ function normalizeProfile(profile: Profile): Pt[] {
   return pts
 }
 
-// Per-point miter offsets and the vertex entries a swept strip needs.
-// Offsetting a point by -miter * d insets the polygon by exactly d on both
-// adjacent edges; miter length is clamped so a spiky corner cannot fling
-// its inset point far into the interior.
-function profileRing(pts: Pt[]) {
+/** Per-point miter offsets and the vertex entries a swept strip needs.
+ * Offsetting a point by -miter * d insets the polygon by exactly d on both
+ * adjacent edges; miter length is clamped so a spiky corner cannot fling
+ * its inset point far into the interior. */
+export function profileRing(pts: Pt[]) {
   let n = pts.length
   let enx: number[] = []
   let eny: number[] = []
@@ -134,25 +130,17 @@ function profileRing(pts: Pt[]) {
   return { entries, miterX, miterY }
 }
 
-// Two CCW-outward triangles per cell of a swept (outer + 1) x entries
-// vertex grid, entries inner: for extrude, outer runs down the z slices;
-// for lathe, around the revolution. The split and winding reduce to box
-// and cylinder respectively (verified against those generators). The
-// zero-width cell between a sharp point's two entries is skipped.
-function sweepIndices(outer: number, entries: RingEntry[], out: number[]): void {
-  let stride = entries.length
-  for (let o = 0; o < outer; o++) {
-    for (let k = 0; k < stride - 1; k++) {
-      let e = entries[k]!
-      let f = entries[k + 1]!
-      if (e.x === f.x && e.y === f.y) continue
-      let a = o * stride + k
-      let b = a + 1
-      let c = a + stride + 1
-      let d = a + stride
-      out.push(c, b, d, b, a, d)
-    }
+export type ProfileBounds = { minX: number; maxX: number; minY: number; maxY: number; w: number; h: number }
+
+/** The profile's bounding box with degenerate spans widened to 1 - the
+ * denominator every cap UV map shares. */
+export function profileBounds(pts: { x: number; y: number }[]): ProfileBounds {
+  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity
+  for (let p of pts) {
+    minX = Math.min(minX, p.x); maxX = Math.max(maxX, p.x)
+    minY = Math.min(minY, p.y); maxY = Math.max(maxY, p.y)
   }
+  return { minX, maxX, minY, maxY, w: maxX - minX || 1, h: maxY - minY || 1 }
 }
 
 // Inside a CCW triangle, edges included: a vertex sitting exactly on an
@@ -170,10 +158,11 @@ function pointInTriangle(
   return s1 >= 0 && s2 >= 0 && s3 >= 0
 }
 
-// Ear clipping for a simple polygon, either winding; returns index triples
-// into the input, wound CCW for a +z viewer. Whatever remains un-clippable
-// becomes a fan, so a cap is never silently dropped.
-function earClip(px: number[], py: number[]): number[] {
+/** Ear clipping for a simple polygon, either winding; returns index
+ * triples into the input, wound CCW for a +z viewer. Whatever remains
+ * un-clippable becomes a fan, so a cap is never silently dropped.
+ * triangulate() is the public face; the generators call this directly. */
+export function earClip(px: number[], py: number[]): number[] {
   let idx: number[] = []
   for (let i = 0; i < px.length; i++) idx.push(i)
   if (signedArea(px, py) < 0) idx.reverse()
@@ -206,10 +195,6 @@ function earClip(px: number[], py: number[]): number[] {
   return out
 }
 
-function packIndices(indices: number[], vertexCount: number): Uint16Array | Uint32Array {
-  return vertexCount > 65535 ? new Uint32Array(indices) : new Uint16Array(indices)
-}
-
 /**
  * Ear-clip a simple polygon (either winding, no holes): flat index triples
  * into `points`, wound CCW for a +z viewer. Un-clippable leftovers fall
@@ -307,190 +292,6 @@ export function roundRect(
   return fillet(corners, radius, segments)
 }
 
-/**
- * The profile swept along z, centered on the origin: z runs from depth/2
- * down to -depth/2, caps at both ends. `bevel` rounds both rims with a
- * quarter-circle roll of that radius (clamped to just under half the
- * depth), inset from the outline by miter offset so the bevel stays
- * inside the silhouette. Side UVs: u = normalized distance around the
- * outline (seam at the first point), v = 0 at the +z rim to 1 at the -z
- * rim, bevel arcs included. Caps map the profile's bounding box to the
- * unit square like plane(); the -z cap mirrors u so its texture reads
- * unmirrored from outside.
- */
-export function extrude(
-  profile: Profile,
-  depth = 1,
-  bevel = 0,
-  bevelSegments = 4,
-  label?: string,
-): Geometry {
-  let pts = normalizeProfile(profile)
-  let { entries, miterX, miterY } = profileRing(pts)
-  let h = depth / 2
-  let b = Math.min(bevel, depth * 0.49)
-
-  // Slices from the +z rim down: inset from the outline, z, and the
-  // (radial, z) direction the entry normal tilts into. The rim slice's
-  // normal equals the cap's, so a bevel blends into its cap crease-free.
-  let slices: { inset: number; z: number; nr: number; nz: number }[] = []
-  if (b > 1e-9) {
-    let bsegs = Math.max(1, Math.round(bevelSegments))
-    for (let i = 0; i <= bsegs; i++) {
-      let a = (i / bsegs) * (Math.PI / 2)
-      slices.push({ inset: b * (1 - Math.sin(a)), z: h - b * (1 - Math.cos(a)), nr: Math.sin(a), nz: Math.cos(a) })
-    }
-    for (let i = bsegs; i >= 0; i--) {
-      let a = (i / bsegs) * (Math.PI / 2)
-      slices.push({ inset: b * (1 - Math.sin(a)), z: -h + b * (1 - Math.cos(a)), nr: Math.sin(a), nz: -Math.cos(a) })
-    }
-  } else {
-    slices.push({ inset: 0, z: h, nr: 1, nz: 0 }, { inset: 0, z: -h, nr: 1, nz: 0 })
-  }
-
-  // v follows the path length down the side, bevel arcs included.
-  let v: number[] = [0]
-  let path = 0
-  for (let i = 1; i < slices.length; i++) {
-    let p = slices[i - 1]!
-    let s = slices[i]!
-    path += Math.hypot(s.z - p.z, s.inset - p.inset)
-    v.push(path)
-  }
-  for (let i = 0; i < v.length; i++) v[i] = v[i]! / (path || 1)
-
-  let verts: number[] = []
-  for (let si = 0; si < slices.length; si++) {
-    let s = slices[si]!
-    for (let e of entries) {
-      // (e.n * nr, nz) is unit already: |e.n| = 1 and nr^2 + nz^2 = 1.
-      verts.push(
-        e.x - miterX[e.point]! * s.inset,
-        e.y - miterY[e.point]! * s.inset,
-        s.z,
-        e.nx * s.nr,
-        e.ny * s.nr,
-        s.nz,
-        e.t,
-        v[si]!,
-      )
-    }
-  }
-  let indices: number[] = []
-  sweepIndices(slices.length - 1, entries, indices)
-
-  // Caps, inset to meet the bevel rim; UVs span the base profile's box.
-  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity
-  for (let p of pts) {
-    minX = Math.min(minX, p.x); maxX = Math.max(maxX, p.x)
-    minY = Math.min(minY, p.y); maxY = Math.max(maxY, p.y)
-  }
-  let bw = maxX - minX || 1
-  let bh = maxY - minY || 1
-  let inset = slices[0]!.inset
-  let cx: number[] = []
-  let cy: number[] = []
-  for (let i = 0; i < pts.length; i++) {
-    cx.push(pts[i]!.x - miterX[i]! * inset)
-    cy.push(pts[i]!.y - miterY[i]! * inset)
-  }
-  let tris = earClip(cx, cy)
-  let base = verts.length / FLOATS_PER_VERTEX
-  for (let i = 0; i < cx.length; i++) {
-    verts.push(cx[i]!, cy[i]!, h, 0, 0, 1, (cx[i]! - minX) / bw, (maxY - cy[i]!) / bh)
-  }
-  for (let i = 0; i < tris.length; i += 3) {
-    indices.push(base + tris[i]!, base + tris[i + 1]!, base + tris[i + 2]!)
-  }
-  base = verts.length / FLOATS_PER_VERTEX
-  for (let i = 0; i < cx.length; i++) {
-    verts.push(cx[i]!, cy[i]!, -h, 0, 0, -1, (maxX - cx[i]!) / bw, (maxY - cy[i]!) / bh)
-  }
-  for (let i = 0; i < tris.length; i += 3) {
-    indices.push(base + tris[i]!, base + tris[i + 2]!, base + tris[i + 1]!)
-  }
-
-  return {
-    vertices: new Float32Array(verts),
-    indices: packIndices(indices, verts.length / FLOATS_PER_VERTEX),
-    label,
-  }
-}
-
-/**
- * A solid of revolution: the CLOSED profile - x is the radius (>= 0), y
- * the height - revolved about the y axis through `angle` radians starting
- * at `start`. The closed profile (a cross-section with thickness, or run
- * to the axis) keeps the output watertight and cull-correct where an open
- * polyline shell would show its missing back faces; partial sweeps get
- * flat triangulated end caps. UVs: u 0..1 around the sweep (seam column
- * duplicated like torus), v = normalized distance around the profile;
- * caps map the profile's bounding box, the end cap mirrored in u.
- */
-export function lathe(
-  profile: Profile,
-  segments = 32,
-  angle = Math.PI * 2,
-  start = 0,
-  label?: string,
-): Geometry {
-  if (!(angle > 0) || angle > Math.PI * 2 + 1e-9) throw new Error("Lathe angle must be in (0, 2*PI]")
-  let pts = normalizeProfile(profile)
-  let { entries } = profileRing(pts)
-  let full = angle > Math.PI * 2 - 1e-9
-
-  let verts: number[] = []
-  for (let c = 0; c <= segments; c++) {
-    let u = c / segments
-    let phi = start + angle * u
-    // The same radial direction as cylinder(), so winding transfers.
-    let dx = -Math.cos(phi)
-    let dz = Math.sin(phi)
-    for (let e of entries) {
-      verts.push(e.x * dx, e.y, e.x * dz, e.nx * dx, e.ny, e.nx * dz, u, e.t)
-    }
-  }
-  let indices: number[] = []
-  sweepIndices(segments, entries, indices)
-
-  if (!full) {
-    let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity
-    for (let p of pts) {
-      minX = Math.min(minX, p.x); maxX = Math.max(maxX, p.x)
-      minY = Math.min(minY, p.y); maxY = Math.max(maxY, p.y)
-    }
-    let bw = maxX - minX || 1
-    let bh = maxY - minY || 1
-    let px = pts.map((p) => p.x)
-    let py = pts.map((p) => p.y)
-    let tris = earClip(px, py)
-    for (let end = 0; end < 2; end++) {
-      let phi = end === 0 ? start : start + angle
-      let dx = -Math.cos(phi)
-      let dz = Math.sin(phi)
-      // Outward along minus/plus the sweep direction; the CCW profile
-      // triangulation faces the start normal as-is and flips for the end.
-      let nx = end === 0 ? -Math.sin(phi) : Math.sin(phi)
-      let nz = end === 0 ? -Math.cos(phi) : Math.cos(phi)
-      let base = verts.length / FLOATS_PER_VERTEX
-      for (let p of pts) {
-        let u = end === 0 ? (p.x - minX) / bw : (maxX - p.x) / bw
-        verts.push(p.x * dx, p.y, p.x * dz, nx, 0, nz, u, (maxY - p.y) / bh)
-      }
-      for (let i = 0; i < tris.length; i += 3) {
-        if (end === 0) indices.push(base + tris[i]!, base + tris[i + 1]!, base + tris[i + 2]!)
-        else indices.push(base + tris[i]!, base + tris[i + 2]!, base + tris[i + 1]!)
-      }
-    }
-  }
-
-  return {
-    vertices: new Float32Array(verts),
-    indices: packIndices(indices, verts.length / FLOATS_PER_VERTEX),
-    label,
-  }
-}
-
 /**
  * The profile filled as a flat face in the XY plane facing +z - the
  * general case of circle()/ring() for arbitrary outlines. UVs map the
@@ -499,18 +300,12 @@ export function lathe(
  */
 export function shape(profile: Profile, label?: string): Geometry {
   let pts = normalizeProfile(profile)
-  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity
-  for (let p of pts) {
-    minX = Math.min(minX, p.x); maxX = Math.max(maxX, p.x)
-    minY = Math.min(minY, p.y); maxY = Math.max(maxY, p.y)
-  }
-  let bw = maxX - minX || 1
-  let bh = maxY - minY || 1
+  let { minX, maxY, w, h } = profileBounds(pts)
   let px = pts.map((p) => p.x)
   let py = pts.map((p) => p.y)
   let verts: number[] = []
   for (let p of pts) {
-    verts.push(p.x, p.y, 0, 0, 0, 1, (p.x - minX) / bw, (maxY - p.y) / bh)
+    verts.push(p.x, p.y, 0, 0, 0, 1, (p.x - minX) / w, (maxY - p.y) / h)
   }
   return {
     vertices: new Float32Array(verts),

package/src/scene.ts

@@ -19,18 +19,30 @@
 
 import { addDraw, createDrawTarget, destroyTexture, removeDraw, setDrawParams, setDrawRange, setTargetParams, setTargetSize } from "@solidrt/core/gpu"
 import type { DrawId, FilterMode, ShaderParams, TextureId, WrapMode } from "@solidrt/core/gpu"
-import { getOwner, onCleanup } from "@solidjs/signals"
-import { compose, copy, lookAt, mat4, multiply, normalMatrix, perspective, transformPoint } from "./math.ts"
-import type { Mat4, Vec3, Vec4 } from "./math.ts"
+import { getOwner, onCleanup } from "@solidrt/core"
+// The scene's lookAt() aims a node; math's builds a camera's view matrix -
+// the same pairing (and the same name) as Three's Object3D/Matrix4.
+import { compose, copy, eulerFromQuat, identity, lookAt as lookAtMatrix, mat4, multiply, normalMatrix, perspective, quatFromEuler, quatFromFrame, quatNormalize, transformPoint } from "./math.ts"
+import type { Mat4, Quat, Vec3, Vec4 } from "./math.ts"
 import { geometryBuffers } from "./geometry.ts"
 import type { Geometry } from "./geometry.ts"
 import type { Material } from "./material.ts"
 
 const IDENTITY = mat4()
 const RESOLVED = Promise.resolve()
+// lookAt()'s default roll reference. Read-only: quatFromFrame never
+// writes its inputs, so one shared vector is safe.
+const WORLD_UP: Vec3 = [0, 1, 0]
 // Param values are snapshotted at the FFI boundary (addDraw shares
 // IDENTITY the same way), so one scratch serves every uNormal write.
 let normalScratch = mat4()
+// lookAt()/worldPosition() scratch: the ancestor walk recomputes worlds
+// without touching node state, so nothing here outlives a single call.
+let worldScratch = mat4()
+let localScratch = mat4()
+let pointScratch: Vec4 = [0, 0, 0, 0]
+let aimScratch: Vec3 = [0, 0, 0]
+let upScratch: Vec3 = [0, 0, 0]
 
 // The scene half a node needs to reach: attach/detach entries and schedule
 // a sync. Kept separate from the public Scene type so internals stay off
@@ -50,8 +62,10 @@ export type SceneNode = {
   children: SceneNode[]
   /** Read freely; write through setTransform/setVisible so changes sync. */
   position: Vec3
-  /** Euler radians, applied x then y then z. */
-  rotation: Vec3
+  /** The stored rotation, always a UNIT quaternion. Euler triples convert
+   * on the way in (setTransform's `rotation`) and out (getRotation) - there
+   * is no second rotation field to fall out of step with this one. */
+  quaternion: Quat
   scale: Vec3
   visible: boolean
   _localDirty: boolean
@@ -121,7 +135,7 @@ function makeNode(kind: "group" | "mesh"): SceneNode {
     parent: null,
     children: [],
     position: [0, 0, 0],
-    rotation: [0, 0, 0],
+    quaternion: [0, 0, 0, 1],
     scale: [1, 1, 1],
     visible: true,
     _localDirty: true,
@@ -183,7 +197,13 @@ function leaveScene(node: SceneNode): void {
 
 export type TransformUpdate = {
   position?: Vec3
+  /** Euler radians in XYZ order (x first), Three's `Euler` default -
+   * converted to the node's quaternion on write. */
   rotation?: Vec3
+  /** The rotation itself. Normalized on write, so a hand-built or
+   * drifted quaternion cannot silently scale the geometry. Passing this
+   * together with `rotation` is an error, not a precedence question. */
+  quaternion?: Quat
   /** A number is uniform scale. */
   scale?: Vec3 | number
 }
@@ -202,11 +222,12 @@ export function setTransform(node: SceneNode, update: TransformUpdate): void {
     node.position[2] = p[2]
   }
   let r = update.rotation
-  if (r) {
-    node.rotation[0] = r[0]
-    node.rotation[1] = r[1]
-    node.rotation[2] = r[2]
+  let q = update.quaternion
+  if (r !== undefined && q !== undefined) {
+    throw new Error("Pass rotation or quaternion to setTransform, not both")
   }
+  if (r !== undefined) quatFromEuler(node.quaternion, r)
+  else if (q !== undefined) quatNormalize(node.quaternion, q)
   let s = update.scale
   if (s !== undefined) {
     if (typeof s === "number") {
@@ -223,6 +244,109 @@ export function setTransform(node: SceneNode, update: TransformUpdate): void {
   node._scene?._schedule()
 }
 
+/**
+ * Aim a node at a WORLD-space point, Three's `Object3D.lookAt`: the node's
+ * local +z ends up pointing at `target`, with `up` (world space, default
+ * +y) choosing the roll about that axis. Ancestor transforms are undone,
+ * so the aim holds under a rotated group - the ancestor chain is brought
+ * up to date on the spot rather than waiting for the pending sync.
+ *
+ * +z because that is the library's own sweep axis (`extrude`, `sweep`,
+ * `tube` run along z), so aiming their output needs no correction. For a
+ * y-axis solid (`cylinder`, `cone`) reach for `quatFromTo` instead, which
+ * takes the axis to aim as an argument.
+ *
+ * Writes `node.quaternion` - an ordinary rotation afterwards, readable and
+ * overwritable by setTransform. To aim along a DIRECTION rather than at a
+ * point, add it to the node's world position (`worldPosition`), the same
+ * conversion Three asks for.
+ *
+ * Exact for rotation and uniform scale in the ancestor chain; a
+ * non-uniformly scaled ancestor shears the frame and the aim is
+ * approximate, exactly as in Three (both read the parent's upper 3x3 as
+ * if it were a rotation).
+ */
+export function lookAt(node: SceneNode, target: Vec3, up: Vec3 = WORLD_UP): void {
+  let parent = node.parent
+  if (parent === null) {
+    // No ancestors: parent space IS world space, aim straight from the
+    // node's own position.
+    aimScratch[0] = target[0] - node.position[0]
+    aimScratch[1] = target[1] - node.position[1]
+    aimScratch[2] = target[2] - node.position[2]
+    quatFromFrame(node.quaternion, aimScratch, up)
+  } else {
+    let world = worldInto(worldScratch, parent)
+    transformPoint(pointScratch, world, node.position)
+    aimScratch[0] = target[0] - pointScratch[0]
+    aimScratch[1] = target[1] - pointScratch[1]
+    aimScratch[2] = target[2] - pointScratch[2]
+    // World -> parent space for both vectors: rotating forward and up
+    // rotates the frame they build, so converting the inputs is the same
+    // as converting the resulting rotation, and needs no matrix inverse.
+    unrotate(aimScratch, world, aimScratch)
+    unrotate(upScratch, world, up)
+    quatFromFrame(node.quaternion, aimScratch, upScratch)
+  }
+  node._localDirty = true
+  node._scene?._schedule()
+}
+
+/**
+ * A node's rotation as Euler radians in XYZ order, copied into `out` (or a
+ * fresh Vec3). A convenience for reading and debugging, NOT a peer of
+ * `node.quaternion`: the conversion is lossy in the sense that it cannot
+ * recover the triple that was written (see eulerFromQuat), only a triple
+ * that means the same rotation. Anything composing or interpolating
+ * rotations should work with the quaternion.
+ */
+export function getRotation(node: SceneNode, out: Vec3 = [0, 0, 0]): Vec3 {
+  return eulerFromQuat(out, node.quaternion)
+}
+
+/**
+ * A node's position in world space, copied into `out` (or a fresh Vec3) -
+ * Three's `getWorldPosition`. Brings the ancestor chain up to date first,
+ * so it is exact before the pending sync has run.
+ */
+export function worldPosition(node: SceneNode, out: Vec3 = [0, 0, 0]): Vec3 {
+  let world = worldInto(worldScratch, node)
+  out[0] = world[12]
+  out[1] = world[13]
+  out[2] = world[14]
+  return out
+}
+
+/**
+ * `out` = node's world matrix, composing any dirty locals up the chain
+ * WITHOUT clearing their flags: the pending sync still has to see them to
+ * write uModel. One shared local scratch serves any depth - each frame
+ * uses it only after its recursive call has returned.
+ */
+function worldInto(out: Mat4, node: SceneNode): Mat4 {
+  if (node.parent === null) identity(out)
+  else worldInto(out, node.parent)
+  let local = node._localDirty
+    ? compose(localScratch, node.position, node.quaternion, node.scale)
+    : node._local
+  return multiply(out, out, local)
+}
+
+/**
+ * `out` = v with m's rotation undone: the transpose of m's upper 3x3 with
+ * its columns normalized, so uniform scale divides out. out may alias v.
+ */
+function unrotate(out: Vec3, m: Mat4, v: Vec3): Vec3 {
+  let x = v[0], y = v[1], z = v[2]
+  let l0 = Math.hypot(m[0], m[1], m[2]) || 1
+  let l1 = Math.hypot(m[4], m[5], m[6]) || 1
+  let l2 = Math.hypot(m[8], m[9], m[10]) || 1
+  out[0] = (m[0] * x + m[1] * y + m[2] * z) / l0
+  out[1] = (m[4] * x + m[5] * y + m[6] * z) / l1
+  out[2] = (m[8] * x + m[9] * y + m[10] * z) / l2
+  return out
+}
+
 /** Show or hide a node and its whole subtree (a hidden mesh costs one
  * `instanceCount: 0` draw range - the entry stays, drawing nothing). */
 export function setVisible(node: SceneNode, visible: boolean): void {
@@ -308,7 +432,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     cameraDirty = false
     cameraPending = true
     perspective(proj, (fov * Math.PI) / 180, width / height, near, far)
-    lookAt(view, eye, target, up)
+    lookAtMatrix(view, eye, target, up)
     multiply(viewProj, proj, view)
   }
 
@@ -326,7 +450,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     let walk = (node: SceneNode, parentChanged: boolean, parentVisible: boolean) => {
       let changed = parentChanged
       if (node._localDirty) {
-        compose(node._local, node.position, node.rotation, node.scale)
+        compose(node._local, node.position, node.quaternion, node.scale)
         node._localDirty = false
         changed = true
       }