@solidrt/3d 0.0.46 → 0.0.48

package/src/glsl.ts

@@ -0,0 +1,112 @@
+// The exported lighting GLSL: string constants an app composes into its
+// own shaderMaterial sources with plain template literals - the same
+// pieces the package's future lit materials will be built from, so a
+// custom material never becomes second-class (no preprocessor, no include
+// resolver; the policy is argued in okf/research/3d-differentiators.md).
+//
+// The light-model functions are PURE: normals, view vectors, light
+// directions, colors and exponents all arrive as arguments, so these
+// constants pin nothing but function names. The LIT_VERTEX pair are the
+// deliberate exception - they pin the standard varying interface
+// (vWorldPos, vNormal, vUv, plus vColor on the colored variant) and
+// consume the standard uniform set (uModel, uViewProj, uNormal);
+// fragments written against those names compose with them directly. All directions are expected normalized;
+// every function returns its raw term, weighting and color belong to the
+// caller.
+
+import { glsl } from "@solidrt/core/gpu"
+
+/**
+ * The standard lit vertex stage: clip position via uViewProj * uModel,
+ * with world position, world normal (via `mat3(uNormal)`, correct under
+ * non-uniform scale) and UV as varyings:
+ *
+ *   in vec3 vWorldPos; in vec3 vNormal; in vec2 vUv;
+ *
+ * Pair it with your own fragment; the view vector there is
+ * `normalize(uCamPos - vWorldPos)`.
+ */
+export const LIT_VERTEX = glsl`
+  in vec3 aPos;
+  in vec3 aNormal;
+  in vec2 aUV;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+  uniform mat4 uNormal;
+  out vec3 vWorldPos;
+  out vec3 vNormal;
+  out vec2 vUv;
+
+  void main() {
+    vec4 world = uModel * vec4(aPos, 1.0);
+    gl_Position = uViewProj * world;
+    vWorldPos = world.xyz;
+    vNormal = mat3(uNormal) * aNormal;
+    vUv = aUV;
+  }
+`
+
+/**
+ * LIT_VERTEX for "colored"-layout geometry: the same interface plus the
+ * per-vertex aColor vec4 forwarded raw as `in vec4 vColor` - what it means
+ * (a tint, baked AO in one channel, anything) is the fragment's business.
+ * Using this constant opts the material into the colored layout (its
+ * meshes need withColors() geometry), because shaderMaterial detects
+ * aColor in the vertex source.
+ */
+export const LIT_VERTEX_COLORED = glsl`
+  in vec3 aPos;
+  in vec3 aNormal;
+  in vec2 aUV;
+  in vec4 aColor;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+  uniform mat4 uNormal;
+  out vec3 vWorldPos;
+  out vec3 vNormal;
+  out vec2 vUv;
+  out vec4 vColor;
+
+  void main() {
+    vec4 world = uModel * vec4(aPos, 1.0);
+    gl_Position = uViewProj * world;
+    vWorldPos = world.xyz;
+    vNormal = mat3(uNormal) * aNormal;
+    vUv = aUV;
+    vColor = aColor;
+  }
+`
+
+/** `vec3 hemisphere(vec3 n, vec3 sky, vec3 ground)` - ambient from a
+ * sky/ground gradient by the normal's vertical tilt: sky straight up,
+ * ground bounce straight down. */
+export const HEMISPHERE = glsl`
+  vec3 hemisphere(vec3 n, vec3 sky, vec3 ground) {
+    return mix(ground, sky, n.y * 0.5 + 0.5);
+  }
+`
+
+/** `float lambert(vec3 n, vec3 l)` - the diffuse term for a directional
+ * light pointing TOWARD the light (multiply by your light color). */
+export const LAMBERT = glsl`
+  float lambert(vec3 n, vec3 l) {
+    return max(dot(n, l), 0.0);
+  }
+`
+
+/** `float blinnSpecular(vec3 n, vec3 v, vec3 l, float shininess)` - the
+ * Blinn-Phong highlight from the half vector between view and light;
+ * shininess runs from wide matte sheen (~8) to tight mirror dot (~150). */
+export const BLINN_SPECULAR = glsl`
+  float blinnSpecular(vec3 n, vec3 v, vec3 l, float shininess) {
+    return pow(max(dot(n, normalize(l + v)), 0.0), shininess);
+  }
+`
+
+/** `float fresnel(vec3 n, vec3 v, float power)` - the grazing-angle rim
+ * weight (1 at silhouettes, 0 face-on); typical power 3 to 5. */
+export const FRESNEL = glsl`
+  float fresnel(vec3 n, vec3 v, float power) {
+    return pow(1.0 - max(dot(n, v), 0.0), power);
+  }
+`

package/src/index.ts

@@ -5,15 +5,21 @@
 // without Solid components) and the component face (Scene/Mesh/Group/
 // PerspectiveCamera) on top. See AGENTS.md for the model and the traps.
 
-export { add, createGroup, createMesh, createScene, remove, setGeometry, setMaterial, setMeshParams, setTransform, setVisible } from "./scene.ts"
+export { add, createGroup, createMesh, createScene, getRotation, lookAt, remove, setGeometry, setMaterial, setMeshParams, setTransform, setVisible, worldPosition } from "./scene.ts"
 export type { CameraUpdate, Mesh as MeshNode, Scene as SceneHandle, SceneNode, SceneOptions, TransformUpdate } from "./scene.ts"
-export { box, disposeGeometry, plane, sphere, torusKnot, FLOATS_PER_VERTEX, VERTEX_LAYOUT } from "./geometry.ts"
-export type { Geometry } from "./geometry.ts"
+export { box, circle, cone, cylinder, disposeGeometry, fillColors, plane, ring, sphere, torus, torusKnot, withColors, FLOATS_PER_VERTEX, VERTEX_LAYOUTS } from "./geometry.ts"
+export type { ColorFill, Geometry, VertexLayout } from "./geometry.ts"
+export { fillet, roundRect, shape, triangulate } from "./profile.ts"
+export type { Profile, ProfilePoint } from "./profile.ts"
+export { extrude, lathe, pathFrames, sweep, tube } from "./sweep.ts"
+export type { PathFrames, PathPoint, SweepPath } from "./sweep.ts"
 export { shaderMaterial, unlit } from "./material.ts"
 export type { Material, ShaderMaterialOptions, UnlitOptions } from "./material.ts"
 export { Group, Mesh, PerspectiveCamera, Scene, useScene } from "./components.tsx"
 export type { MeshProps, PerspectiveCameraProps, SceneProps, TransformProps } from "./components.tsx"
 export { createOrbitCamera } from "./orbit.ts"
 export type { OrbitCamera, OrbitCameraOptions, OrbitPose } from "./orbit.ts"
-export { compose, copy, identity, lookAt, mat4, multiply, perspective } from "./math.ts"
-export type { Mat4, Vec3 } from "./math.ts"
+// math's lookAt (the camera view matrix) stays on the /math subpath: the
+// root's lookAt is the scene verb, the same split as `add`.
+export { compose, copy, eulerFromQuat, identity, mat4, multiply, normalMatrix, perspective, quat, quatFromAxisAngle, quatFromEuler, quatFromFrame, quatFromTo, quatMultiply, quatNormalize, quatSlerp } from "./math.ts"
+export type { Mat4, Quat, Vec2, Vec3 } from "./math.ts"

package/src/material.ts

@@ -36,7 +36,8 @@ import type {
   TextureId,
   Topology,
 } from "@solidrt/core/gpu"
-import { VERTEX_LAYOUT } from "./geometry.ts"
+import { VERTEX_LAYOUTS } from "./geometry.ts"
+import type { VertexLayout } from "./geometry.ts"
 
 export type Material = {
   /** The pipeline this material draws with (lazily created). */
@@ -45,6 +46,15 @@ export type Material = {
   params: ShaderParams
   /** Per-entry sampler bindings, when the material samples textures. */
   textures?: Record<string, TextureId>
+  /** True when the vertex stage declares `uNormal`: the scene then writes
+   * the world matrix's inverse-transpose alongside uModel for meshes using
+   * this material (set automatically by shaderMaterial). */
+  normalMatrix?: boolean
+  /** The vertex layout the pipeline is built for; absent means "standard".
+   * shaderMaterial sets "colored" when the vertex stage reads `aColor`. A
+   * mesh whose geometry layout differs is rejected at add() - the strides
+   * disagree, so a mismatch would render garbage, not just miss a channel. */
+  layout?: VertexLayout
   /** Present on materials that own their pipeline (shaderMaterial). */
   dispose?(): void
 }
@@ -97,7 +107,7 @@ function pipelineFor(kind: "color" | "map"): RenderPipelineId {
   })
   let program = linkProgram(sharedVertex, fragment, { label: "scene-unlit-" + kind })
   let pipeline = createRenderPipeline(program, {
-    attributes: VERTEX_LAYOUT,
+    attributes: VERTEX_LAYOUTS.standard,
     depth: true,
     cull: "back",
     label: "scene-unlit-" + kind,
@@ -140,13 +150,24 @@ export type ShaderMaterialOptions = {
    * mesh's world matrix, written per entry whenever the mesh moves) and
    * `uniform mat4 uViewProj` (the camera's view-projection, shared by the
    * whole scene target and written once per camera move) - transform with
-   * `uViewProj * uModel * vec4(aPos, 1.0)`. Declare any of the shared
+   * `uViewProj * uModel * vec4(aPos, 1.0)`; a source mentioning neither
+   * throws right here. The rest of the standard uniform set is opt-in by
+   * declare-and-use: `uniform mat4 uNormal` (either stage) receives the
+   * world inverse-transpose beside uModel - take `mat3(uNormal)` for
+   * normals, correct under non-uniform scale - and `uniform vec3 uCamPos`
+   * the camera's world position, shared like uViewProj (the specular /
+   * fresnel view vector: `uCamPos - worldPos`). Declare any of the
    * layout's `in` attributes (aPos vec3, aNormal vec3, aUV vec2);
-   * undeclared ones are skipped.
+   * undeclared ones are skipped. Reading `in vec4 aColor` opts the
+   * material into the "colored" 12-float layout - the per-vertex data
+   * channel (tint, baked AO, any four scalars); its meshes then need
+   * withColors() geometry, and a layout mismatch throws at add().
+   * `@solidrt/3d/glsl` exports a standard
+   * vertex stage and lighting pieces built on exactly this contract.
    */
   vertex: string
   fragment: string
-  /** Uniform seeds beyond uModel/uViewProj; update per mesh later with
+  /** Uniform seeds beyond the standard set; update per mesh later with
    * setMeshParams. */
   params?: ShaderParams
   textures?: Record<string, TextureId>
@@ -171,9 +192,25 @@ export type ShaderMaterialOptions = {
  * and `dispose()` it if the app is done with the look for good.
  */
 export function shaderMaterial(opts: ShaderMaterialOptions): Material {
+  // The standard-set contract, checked where the mistake is made: a vertex
+  // stage that never mentions the matrices cannot place meshes, and with
+  // shared params skipping undeclared names the omission would otherwise
+  // surface as a silently untransformed render, not an error.
+  for (let name of ["uModel", "uViewProj"]) {
+    if (!new RegExp("\\b" + name + "\\b").test(opts.vertex)) {
+      throw new Error(
+        "shaderMaterial vertex stage must declare and use '" + name + "' (see the standard uniform set in AGENTS.md)",
+      )
+    }
+  }
   let program: ProgramId | undefined
   let pipeline: RenderPipelineId | undefined
+  // Attributes live in the vertex stage only, so unlike the uNormal scan
+  // there is nothing to look for in the fragment source.
+  let layout: VertexLayout = /\baColor\b/.test(opts.vertex) ? "colored" : "standard"
   return {
+    normalMatrix: /\buNormal\b/.test(opts.vertex) || /\buNormal\b/.test(opts.fragment),
+    layout,
     pipeline() {
       if (pipeline === undefined) {
         let vs = compileShader("vertex", opts.vertex, { header: needsHeader(opts.vertex) })
@@ -182,7 +219,7 @@ export function shaderMaterial(opts: ShaderMaterialOptions): Material {
         destroyShader(vs)
         destroyShader(fs)
         pipeline = createRenderPipeline(program, {
-          attributes: VERTEX_LAYOUT,
+          attributes: VERTEX_LAYOUTS[layout],
           depth: opts.depth ?? true,
           depthWrite: opts.depthWrite,
           blend: opts.blend,

package/src/math.ts

@@ -9,7 +9,11 @@
 // interpreter. Mat4 is a 16-tuple so constant-index access stays plain
 // `number` under noUncheckedIndexedAccess.
 
+export type Vec2 = [number, number]
 export type Vec3 = [number, number, number]
+export type Vec4 = [number, number, number, number]
+/** A rotation as [x, y, z, w] - glTF's and Three's component order. */
+export type Quat = [number, number, number, number]
 // prettier-ignore
 export type Mat4 = [
   number, number, number, number,
@@ -39,6 +43,20 @@ export function copy(out: Mat4, m: Mat4): Mat4 {
   return out
 }
 
+/**
+ * Transform a point by m with w = 1, keeping the homogeneous result: the
+ * clip-space building block (scene.project, picking). The caller owns the
+ * perspective divide and the w <= 0 behind-the-camera test.
+ */
+export function transformPoint(out: Vec4, m: Mat4, p: Vec3): Vec4 {
+  let x = p[0], y = p[1], z = p[2]
+  out[0] = m[0] * x + m[4] * y + m[8] * z + m[12]
+  out[1] = m[1] * x + m[5] * y + m[9] * z + m[13]
+  out[2] = m[2] * x + m[6] * y + m[10] * z + m[14]
+  out[3] = m[3] * x + m[7] * y + m[11] * z + m[15]
+  return out
+}
+
 /** out = a * b (column vectors: b applies first). out may alias a or b. */
 export function multiply(out: Mat4, a: Mat4, b: Mat4): Mat4 {
   let a00 = a[0], a01 = a[1], a02 = a[2], a03 = a[3]
@@ -69,30 +87,51 @@ export function multiply(out: Mat4, a: Mat4, b: Mat4): Mat4 {
 }
 
 /**
- * Compose translation + rotation + scale into a local matrix. Rotation is
- * Euler angles in radians applied x, then y, then z (R = Rz * Ry * Rx on
- * column vectors) - the common "XYZ" order.
+ * Compose translation + rotation + scale into a local matrix - Three's
+ * `Matrix4.compose` signature, rotation as a quaternion.
+ *
+ * `rotation` must be a UNIT quaternion: a non-unit one scales the geometry
+ * by |q|^2, silently. The scene closes that trap by normalizing on write
+ * (setTransform) rather than paying for a check on every compose.
  */
-export function compose(out: Mat4, position: Vec3, rotation: Vec3, scale: Vec3): Mat4 {
-  let cx = Math.cos(rotation[0]), sx = Math.sin(rotation[0])
-  let cy = Math.cos(rotation[1]), sy = Math.sin(rotation[1])
-  let cz = Math.cos(rotation[2]), sz = Math.sin(rotation[2])
-  let r00 = cz * cy
-  let r01 = cz * sy * sx - sz * cx
-  let r02 = cz * sy * cx + sz * sx
-  let r10 = sz * cy
-  let r11 = sz * sy * sx + cz * cx
-  let r12 = sz * sy * cx - cz * sx
-  let r20 = -sy
-  let r21 = cy * sx
-  let r22 = cy * cx
-  out[0] = r00 * scale[0]; out[1] = r10 * scale[0]; out[2] = r20 * scale[0]; out[3] = 0
-  out[4] = r01 * scale[1]; out[5] = r11 * scale[1]; out[6] = r21 * scale[1]; out[7] = 0
-  out[8] = r02 * scale[2]; out[9] = r12 * scale[2]; out[10] = r22 * scale[2]; out[11] = 0
+export function compose(out: Mat4, position: Vec3, rotation: Quat, scale: Vec3): Mat4 {
+  let x = rotation[0], y = rotation[1], z = rotation[2], w = rotation[3]
+  let x2 = x + x, y2 = y + y, z2 = z + z
+  let xx = x * x2, xy = x * y2, xz = x * z2
+  let yy = y * y2, yz = y * z2, zz = z * z2
+  let wx = w * x2, wy = w * y2, wz = w * z2
+  let sx = scale[0], sy = scale[1], sz = scale[2]
+  out[0] = (1 - (yy + zz)) * sx; out[1] = (xy + wz) * sx; out[2] = (xz - wy) * sx; out[3] = 0
+  out[4] = (xy - wz) * sy; out[5] = (1 - (xx + zz)) * sy; out[6] = (yz + wx) * sy; out[7] = 0
+  out[8] = (xz + wy) * sz; out[9] = (yz - wx) * sz; out[10] = (1 - (xx + yy)) * sz; out[11] = 0
   out[12] = position[0]; out[13] = position[1]; out[14] = position[2]; out[15] = 1
   return out
 }
 
+/**
+ * The normal matrix for a world matrix: the inverse-transpose of its upper
+ * 3x3 (the cofactor matrix over the determinant), packed into a mat4 - the
+ * engine's settable uniform set has no mat3, so shaders take `mat3(uNormal)`.
+ * Correct under any transform including non-uniform scale, where
+ * `mat3(uModel)` would bend normals off the surface. A degenerate
+ * (zero-scale) input yields the raw cofactors instead of NaNs.
+ */
+export function normalMatrix(out: Mat4, m: Mat4): Mat4 {
+  let a = m[0], b = m[4], c = m[8]
+  let d = m[1], e = m[5], f = m[9]
+  let g = m[2], h = m[6], i = m[10]
+  let c00 = e * i - f * h
+  let c01 = f * g - d * i
+  let c02 = d * h - e * g
+  let det = a * c00 + b * c01 + c * c02
+  let s = 1 / (det || 1)
+  out[0] = c00 * s; out[1] = (c * h - b * i) * s; out[2] = (b * f - c * e) * s; out[3] = 0
+  out[4] = c01 * s; out[5] = (a * i - c * g) * s; out[6] = (c * d - a * f) * s; out[7] = 0
+  out[8] = c02 * s; out[9] = (b * g - a * h) * s; out[10] = (a * e - b * d) * s; out[11] = 0
+  out[12] = 0; out[13] = 0; out[14] = 0; out[15] = 1
+  return out
+}
+
 /**
  * Right-handed perspective projection with the engine's y-down clip flip
  * BAKED IN (row two is negated): geometry authored y-up displays y-up, and
@@ -110,6 +149,278 @@ export function perspective(out: Mat4, fovy: number, aspect: number, near: numbe
   return out
 }
 
+// Quaternions, the rotation the scene actually stores. Euler triples are a
+// boundary format only - authoring (setTransform's `rotation`, the
+// components' `rotation` prop) and reading back (getRotation) - so the order
+// convention and gimbal lock live at that boundary and nowhere else.
+
+/** A fresh identity rotation. */
+export function quat(): Quat {
+  return [0, 0, 0, 1]
+}
+
+/** Unit quaternion; a zero-length input comes back as the identity. `out`
+ * may alias `q`. */
+export function quatNormalize(out: Quat, q: Quat): Quat {
+  let len = Math.hypot(q[0], q[1], q[2], q[3])
+  if (len === 0) {
+    out[0] = 0; out[1] = 0; out[2] = 0; out[3] = 1
+    return out
+  }
+  out[0] = q[0] / len; out[1] = q[1] / len; out[2] = q[2] / len; out[3] = q[3] / len
+  return out
+}
+
+/**
+ * Euler radians to a quaternion, in XYZ order: x applied first, then y,
+ * then z (R = Rx * Ry * Rz on column vectors), Three's `Euler` default - a
+ * triple copied from a Three scene means the same thing here.
+ *
+ * ONE order exists, deliberately: a per-call order argument is how the same
+ * triple ends up meaning two different things in two places, and the
+ * quaternion is right there for anything an order was going to express.
+ */
+export function quatFromEuler(out: Quat, euler: Vec3): Quat {
+  let c1 = Math.cos(euler[0] / 2), s1 = Math.sin(euler[0] / 2)
+  let c2 = Math.cos(euler[1] / 2), s2 = Math.sin(euler[1] / 2)
+  let c3 = Math.cos(euler[2] / 2), s3 = Math.sin(euler[2] / 2)
+  out[0] = s1 * c2 * c3 + c1 * s2 * s3
+  out[1] = c1 * s2 * c3 - s1 * c2 * s3
+  out[2] = c1 * c2 * s3 + s1 * s2 * c3
+  out[3] = c1 * c2 * c3 - s1 * s2 * s3
+  return out
+}
+
+/**
+ * A quaternion back to Euler radians in the same XYZ order - the inverse of
+ * quatFromEuler, a convenience for reading and debugging rather than a peer
+ * of the quaternion: the mapping is many-to-one (a triple and that triple
+ * plus a full turn agree), and at the poles (local +z straight up or down)
+ * only the sum of x and z is determined, so this pins z to 0 and folds the
+ * roll into x. Round-tripping the result reproduces the rotation exactly;
+ * it need not reproduce the triple you started from.
+ */
+export function eulerFromQuat(out: Vec3, q: Quat): Vec3 {
+  let x = q[0], y = q[1], z = q[2], w = q[3]
+  let x2 = x + x, y2 = y + y, z2 = z + z
+  let xx = x * x2, xy = x * y2, xz = x * z2
+  let yy = y * y2, yz = y * z2, zz = z * z2
+  let wx = w * x2, wy = w * y2, wz = w * z2
+  // The same matrix entries compose() writes: m02 = sin(y) alone, and the
+  // x/z pair reads off the rest unless cos(y) is 0 (the pole).
+  let m00 = 1 - (yy + zz)
+  let m01 = xy - wz
+  let m02 = xz + wy
+  // cos(y), which both remaining pairs scale with. atan2 against it beats
+  // asin(m02) - Three's form - near the poles, where asin's derivative
+  // blows up and a 1e-16 error in m02 becomes 1e-8 in the angle. It also
+  // lets the pole branch start three orders of magnitude later: the pairs
+  // stay well-conditioned until cos(y) approaches the noise floor.
+  let cy = Math.hypot(m00, m01)
+  out[1] = Math.atan2(m02, cy)
+  if (cy > 1e-7) {
+    out[0] = Math.atan2(wx - yz, 1 - (xx + yy))
+    out[2] = Math.atan2(-m01, m00)
+  } else {
+    // Only x + z (at +y) or x - z (at -y) is determined; pin z and fold
+    // the whole roll into x.
+    out[0] = Math.atan2(yz + wx, 1 - (xx + zz))
+    out[2] = 0
+  }
+  return out
+}
+
+/**
+ * The rotation of `angle` RADIANS about `axis` - Three's `setFromAxisAngle`,
+ * Unity's `AngleAxis` (which takes degrees; this takes radians like
+ * everything else here). The axis need not be normalized - the named
+ * engines all require a unit axis and silently corrupt the rotation
+ * otherwise, the same precondition trap `quatFromTo` closes. A zero axis
+ * yields the identity.
+ */
+export function quatFromAxisAngle(out: Quat, axis: Vec3, angle: number): Quat {
+  let x = axis[0], y = axis[1], z = axis[2]
+  let len = Math.hypot(x, y, z)
+  if (len === 0) {
+    out[0] = 0; out[1] = 0; out[2] = 0; out[3] = 1
+    return out
+  }
+  let s = Math.sin(angle / 2) / len
+  out[0] = x * s
+  out[1] = y * s
+  out[2] = z * s
+  out[3] = Math.cos(angle / 2)
+  return out
+}
+
+/**
+ * out = a * b - the same order contract as the mat4 `multiply` above: on
+ * column vectors b applies first, so `quatMultiply(q, spin, q)` composes a
+ * further world-frame spin onto q while `quatMultiply(q, q, spin)` spins
+ * about q's own local frame. `out` may alias `a` or `b`.
+ *
+ * The product of unit quaternions is unit up to float drift, so this does
+ * not renormalize; an accumulator composed every frame drifts slowly, and
+ * the scene's setTransform renormalizes on write anyway.
+ */
+export function quatMultiply(out: Quat, a: Quat, b: Quat): Quat {
+  let ax = a[0], ay = a[1], az = a[2], aw = a[3]
+  let bx = b[0], by = b[1], bz = b[2], bw = b[3]
+  out[0] = aw * bx + ax * bw + ay * bz - az * by
+  out[1] = aw * by - ax * bz + ay * bw + az * bx
+  out[2] = aw * bz + ax * by - ay * bx + az * bw
+  out[3] = aw * bw - ax * bx - ay * by - az * bz
+  return out
+}
+
+/**
+ * Spherical interpolation from `a` to `b`: constant angular velocity along
+ * the shortest path (the sign of `b` is flipped when the pair straddles the
+ * quaternion double cover, so it never takes the long way round). t = 0 is
+ * `a`, t = 1 is `b`'s rotation; inputs must be unit and the result is unit.
+ * `out` may alias `a` or `b`.
+ *
+ * The canonical damped follow is
+ * `quatSlerp(q, q, target, 1 - Math.exp(-k * dt))` - frame-rate
+ * independent, k is the tracking speed.
+ */
+export function quatSlerp(out: Quat, a: Quat, b: Quat, t: number): Quat {
+  let ax = a[0], ay = a[1], az = a[2], aw = a[3]
+  let bx = b[0], by = b[1], bz = b[2], bw = b[3]
+  let cos = ax * bx + ay * by + az * bz + aw * bw
+  if (cos < 0) {
+    cos = -cos
+    bx = -bx; by = -by; bz = -bz; bw = -bw
+  }
+  let wa: number
+  let wb: number
+  if (cos < 0.9995) {
+    let theta = Math.acos(cos > 1 ? 1 : cos)
+    let sin = Math.sin(theta)
+    wa = Math.sin((1 - t) * theta) / sin
+    wb = Math.sin(t * theta) / sin
+  } else {
+    // Nearly identical: sin(theta) is noise, and a straight lerp is within
+    // float precision of the arc - normalized below like any other result.
+    wa = 1 - t
+    wb = t
+  }
+  out[0] = wa * ax + wb * bx
+  out[1] = wa * ay + wb * by
+  out[2] = wa * az + wb * bz
+  out[3] = wa * aw + wb * bw
+  return quatNormalize(out, out)
+}
+
+/**
+ * The shortest-arc rotation taking `from` to `to`: Unity's
+ * `Quaternion.FromToRotation`, glam's `Quat::from_rotation_arc`. Three
+ * calls this `setFromUnitVectors`; renamed because that name states a
+ * precondition instead of the operation, and this one has no such
+ * precondition - neither input need be normalized.
+ *
+ * This is how a y-axis solid gets aimed - `quatFromTo(q, [0, 1, 0], dir)`
+ * for a cylinder or cone - where lookAt's +z convention would need a
+ * correction. Opposite vectors have no shortest arc (every half turn is
+ * equally short); a stable perpendicular axis is picked. A zero-length
+ * input yields the identity.
+ */
+export function quatFromTo(out: Quat, from: Vec3, to: Vec3): Quat {
+  let ax = from[0], ay = from[1], az = from[2]
+  let bx = to[0], by = to[1], bz = to[2]
+  let la = Math.hypot(ax, ay, az)
+  let lb = Math.hypot(bx, by, bz)
+  if (la === 0 || lb === 0) {
+    out[0] = 0; out[1] = 0; out[2] = 0; out[3] = 1
+    return out
+  }
+  ax /= la; ay /= la; az /= la
+  bx /= lb; by /= lb; bz /= lb
+  let r = ax * bx + ay * by + az * bz + 1
+  if (r < 1e-6) {
+    // Antiparallel: the cross product vanishes, so take any perpendicular
+    // axis - crossing with the smaller of from's x/z components cannot
+    // vanish too, and picking off from alone keeps the choice stable.
+    r = 0
+    if (Math.abs(ax) > Math.abs(az)) {
+      out[0] = -ay; out[1] = ax; out[2] = 0
+    } else {
+      out[0] = 0; out[1] = -az; out[2] = ay
+    }
+  } else {
+    out[0] = ay * bz - az * by
+    out[1] = az * bx - ax * bz
+    out[2] = ax * by - ay * bx
+  }
+  out[3] = r
+  return quatNormalize(out, out)
+}
+
+/**
+ * The rotation that points the local +z axis along `forward`, with `up`
+ * choosing the roll about it - the object-aiming counterpart of lookAt(),
+ * which builds the camera's inverse frame. Neither input need be
+ * normalized. Degenerate inputs (zero forward, up parallel to forward) fall
+ * back to a stable perpendicular instead of producing NaNs.
+ */
+export function quatFromFrame(out: Quat, forward: Vec3, up: Vec3): Quat {
+  let zx = forward[0], zy = forward[1], zz = forward[2]
+  let len = Math.hypot(zx, zy, zz)
+  if (len === 0) {
+    zx = 0; zy = 0; zz = 1
+  } else {
+    zx /= len; zy /= len; zz /= len
+  }
+  let xx = up[1] * zz - up[2] * zy
+  let xy = up[2] * zx - up[0] * zz
+  let xz = up[0] * zy - up[1] * zx
+  len = Math.hypot(xx, xy, xz)
+  if (len === 0) {
+    // up is parallel to forward: cross with a world axis that cannot be,
+    // picked off z's own components so the choice is stable per direction.
+    let ax = Math.abs(zx) < 0.9 ? 1 : 0
+    let ay = ax === 1 ? 0 : 1
+    xx = ay * zz
+    xy = -ax * zz
+    xz = ax * zy - ay * zx
+    len = Math.hypot(xx, xy, xz)
+  }
+  xx /= len; xy /= len; xz /= len
+  let yx = zy * xz - zz * xy
+  let yy = zz * xx - zx * xz
+  let yz = zx * xy - zy * xx
+  // X | Y | Z are the rotation's columns, so its diagonal is xx, yy, zz.
+  // Branching on the largest diagonal entry keeps the divisor away from
+  // zero; the basis is orthonormal, so the result is already unit.
+  let trace = xx + yy + zz
+  if (trace > 0) {
+    let s = 0.5 / Math.sqrt(trace + 1)
+    out[0] = (yz - zy) * s
+    out[1] = (zx - xz) * s
+    out[2] = (xy - yx) * s
+    out[3] = 0.25 / s
+  } else if (xx > yy && xx > zz) {
+    let s = 2 * Math.sqrt(1 + xx - yy - zz)
+    out[0] = 0.25 * s
+    out[1] = (yx + xy) / s
+    out[2] = (zx + xz) / s
+    out[3] = (yz - zy) / s
+  } else if (yy > zz) {
+    let s = 2 * Math.sqrt(1 + yy - xx - zz)
+    out[0] = (yx + xy) / s
+    out[1] = 0.25 * s
+    out[2] = (zy + yz) / s
+    out[3] = (zx - xz) / s
+  } else {
+    let s = 2 * Math.sqrt(1 + zz - xx - yy)
+    out[0] = (zx + xz) / s
+    out[1] = (zy + yz) / s
+    out[2] = 0.25 * s
+    out[3] = (xy - yx) / s
+  }
+  return out
+}
+
 // Vec3 helpers for geometry construction. These allocate (unlike the matrix
 // functions above): they serve generation-time code - curve frames, normals -
 // not the per-frame path. Exposed on the /math subpath only, so `add` does
@@ -145,6 +456,10 @@ export function normalize(v: Vec3): Vec3 {
  * View matrix (world -> camera) for a camera at `eye` looking at `target`
  * with the given `up`. Degenerate inputs (eye == target, up parallel to the
  * view direction) fall back to axis defaults instead of producing NaNs.
+ *
+ * On the /math subpath ONLY - the package root's `lookAt` is the scene verb
+ * that aims a node (the Matrix4/Object3D split Three makes under the same
+ * name), the same collision rule the Vec3 helpers follow.
  */
 export function lookAt(out: Mat4, eye: Vec3, target: Vec3, up: Vec3): Mat4 {
   let zx = eye[0] - target[0]