@nakednous/tree 0.0.8 → 0.0.9

package/README.md

@@ -58,11 +58,14 @@ track.eval(out)   // writes interpolated TRS into out
 Interpolation modes:
 
 ```js
-track.posInterp = 'catmullrom'  // default — centripetal Catmull-Rom
+track.posInterp = 'hermite'  // default — cubic Hermite; auto-computes centripetal
+                             //           Catmull-Rom tangents when none are stored
 track.posInterp = 'linear'
+track.posInterp = 'step'     // snap to k0; useful for discrete state changes
 
-track.rotInterp = 'slerp'       // default — constant angular velocity
-track.rotInterp = 'nlerp'       // normalised lerp; cheaper, slightly non-constant
+track.rotInterp = 'slerp'    // default — constant angular velocity
+track.rotInterp = 'nlerp'    // normalised lerp; cheaper, slightly non-constant speed
+track.rotInterp = 'step'     // snap to k0 quaternion
 ```
 
 Playback features: signed `rate` (negative reverses), `loop`, `pingPong`, `seek(t)` scrubbing, and lifecycle hooks (`onPlay`, `onEnd`, `onStop`). `_onActivate` / `_onDeactivate` are lib-space hooks for the host layer's draw-loop registry — not for user code.
@@ -70,9 +73,19 @@ Playback features: signed `rate` (negative reverses), `loop`, `pingPong`, `seek(
 `add()` accepts flexible specs. Top-level forms:
 
 ```js
-track.add({ pos, rot, scl })      // explicit TRS — rot accepts any form below
-track.add({ mMatrix: mat4 })      // decompose a column-major model matrix into TRS
-track.add([ spec, spec, ... ])    // bulk
+track.add({ pos, rot, scl })                      // explicit TRS — rot accepts any form below
+track.add({ pos, rot, scl, tanIn, tanOut })        // with Hermite tangents (vec3, optional)
+track.add({ mMatrix: mat4 })                       // decompose a column-major model matrix into TRS
+track.add([ spec, spec, ... ])                     // bulk
+```
+
+`tanIn` is the incoming position tangent at this keyframe; `tanOut` is the outgoing tangent. When only one is given, the other mirrors it. When neither is given, centripetal Catmull-Rom tangents are auto-computed from neighboring keyframes — identical to prior default behavior.
+
+```js
+track.add({ pos:[0,0,0] })                                      // auto tangents
+track.add({ pos:[100,0,0], tanOut:[0,50,0] })                   // leave heading +Y
+track.add({ pos:[200,0,0], tanIn:[0,50,0], tanOut:[-30,0,0] })  // arrive from +Y, leave heading -X
+track.add({ pos:[300,0,0] })                                    // auto tangents
 ```
 
 `rot` sub-forms — all normalised internally:
@@ -116,20 +129,25 @@ track.eval(out)
 Interpolation modes:
 
 ```js
-track.eyeInterp    = 'catmullrom'  // default
+track.eyeInterp    = 'hermite'  // default — auto-CR tangents when none stored
 track.eyeInterp    = 'linear'
+track.eyeInterp    = 'step'
 
-track.centerInterp = 'linear'      // default — suits fixed lookat targets
-track.centerInterp = 'catmullrom'  // smoother when center is also moving freely
+track.centerInterp = 'linear'   // default — suits fixed lookat targets
+track.centerInterp = 'hermite'  // smoother when center is also moving freely
+track.centerInterp = 'step'
 ```
 
 `add()` accepts:
 
 ```js
-track.add({ eye, center?, up?, fov?, halfHeight? })
+track.add({ eye, center?, up?, fov?, halfHeight?,
+            eyeTanIn?, eyeTanOut?, centerTanIn?, centerTanOut? })
                                    // fov — vertical fov (radians) for perspective
                                    // halfHeight — world-unit half-height for ortho
                                    // both nullable; omit to leave projection unchanged
+                                   // eyeTanIn/Out — Hermite tangents for eye path
+                                   // centerTanIn/Out — Hermite tangents for center path
 track.add({ vMatrix: mat4 })       // view matrix (world→eye); eye reconstructed
 track.add({ eMatrix: mat4 })       // eye matrix (eye→world); eye read from col3
 track.add([ spec, spec, ... ])     // bulk
@@ -137,9 +155,7 @@ track.add([ spec, spec, ... ])     // bulk
 
 Note: both matrix forms default `up` to `[0,1,0]`. The matrix col1 (up_ortho) is intentionally not used — it differs from the hint for upright cameras and would shift orbitControl's orbit reference. Use `capturePose()` (p5.tree bridge) when the real up hint is needed.
 
-`fov` and `halfHeight` are lerped between keyframes only when both adjacent
-keyframes carry a non-null value for that field. Mixed or null entries pass
-`null` through — the bridge leaves the projection unchanged.
+`fov` and `halfHeight` are lerped between keyframes only when both adjacent keyframes carry a non-null value for that field. Mixed or null entries pass `null` through — the bridge leaves the projection unchanged.
 
 ---
 
@@ -241,7 +257,7 @@ qFromAxisAngle  qFromLookDir  qFromRotMat3x3  qFromMat4  qToMat4
 quatToAxisAngle
 ```
 
-**Spline / vector:** `catmullRomVec3`, `lerpVec3`
+**Spline / vector:** `hermiteVec3`, `lerpVec3`
 
 **Mat4:**
 ```

package/dist/index.js

@@ -822,7 +822,7 @@ function applyPickMatrix(proj, px, py, W, H) {
  *    qFromAxisAngle qFromLookDir qFromRotMat3x3 qFromMat4 qToMat4
  *    quatToAxisAngle
  *  Spline / vector helpers
- *    catmullRomVec3  lerpVec3
+ *    hermiteVec3  lerpVec3
  *  Transform / mat4 helpers
  *    transformToMat4  mat4ToTransform
  *  Tracks
@@ -839,20 +839,22 @@ function applyPickMatrix(proj, px, py, W, H) {
  *  add() / eval() for their respective data shape.
  *
  * ── Hook architecture ─────────────────────────────────────────────────────────
- *  _onActivate / _onDeactivate  — lib-space (underscore, set by host layer)
- *    Fire on playing transitions: false→true / true→false.
+ *  Lib-space hooks (underscore prefix — reserved for host layer / UI layer):
+ *    _onActivate / _onDeactivate  — fire on playing transitions false→true / true→false.
+ *    _onPlay / _onEnd / _onStop   — mirror the user-space hooks; used by the UI layer
+ *                                   so it can sync without chaining the public slots.
  *
- *  onPlay / onEnd / onStop      — user-space (public)
+ *  User-space hooks (public):
  *    onPlay : fires in play()  on false→true transition.
  *    onEnd  : fires in tick()  at natural boundary (once mode only).
  *    onStop : fires in stop() / reset() — explicit deactivation.
  *    onEnd and onStop are mutually exclusive per event.
  *
  *  Firing order:
- *    play()  → onPlay → _onActivate
- *    tick()  → onEnd  → _onDeactivate
- *    stop()  → onStop → _onDeactivate
- *    reset() → onStop → _onDeactivate
+ *    play()  → onPlay → _onPlay → _onActivate
+ *    tick()  → onEnd  → _onEnd  → _onDeactivate
+ *    stop()  → onStop → _onStop → _onDeactivate
+ *    reset() → onStop → _onStop → _onDeactivate
  *
  * ── Playback semantics (rate) ─────────────────────────────────────────────────
  *  rate > 0   forward
@@ -1048,33 +1050,42 @@ function _dist3(a, b) {
 }
 
 /**
- * Centripetal Catmull-Rom interpolation (alpha=0.5, Barry-Goldman).
- * out = interp(p0, p1, p2, p3, t) where t∈[0,1] maps p1→p2.
- * Boundary: p0===p1 or p2===p3 clamps the end tangent.
+ * Cubic Hermite interpolation between p0 and p1 with explicit tangents.
+ * Catmull-Rom is a special case where m0/m1 are auto-computed from neighbors.
  * @param {number[]} out  3-element result.
- * @param {number[]} p0  Control point before p1.
- * @param {number[]} p1  Segment start.
- * @param {number[]} p2  Segment end.
- * @param {number[]} p3  Control point after p2.
- * @param {number}   t   Blend [0, 1].
+ * @param {number[]} p0   Segment start.
+ * @param {number[]} m0   Outgoing tangent at p0 (world-space, dp/dt scaled to segment).
+ * @param {number[]} p1   Segment end.
+ * @param {number[]} m1   Incoming tangent at p1 (world-space, dp/dt scaled to segment).
+ * @param {number}   t    Blend [0, 1].
  * @returns {number[]} out
  */
-const catmullRomVec3 = (out, p0, p1, p2, p3, t) => {
-  const alpha = 0.5;
-  const dt0 = Math.pow(_dist3(p0,p1), alpha) || 1;
-  const dt1 = Math.pow(_dist3(p1,p2), alpha) || 1;
-  const dt2 = Math.pow(_dist3(p2,p3), alpha) || 1;
-  for (let i = 0; i < 3; i++) {
-    const t1_0 = (p1[i]-p0[i])/dt0 - (p2[i]-p0[i])/(dt0+dt1) + (p2[i]-p1[i])/dt1;
-    const t2_0 = (p2[i]-p1[i])/dt1 - (p3[i]-p1[i])/(dt1+dt2) + (p3[i]-p2[i])/dt2;
-    const m1=t1_0*dt1, m2=t2_0*dt1;
-    const a= 2*p1[i]-2*p2[i]+m1+m2;
-    const b=-3*p1[i]+3*p2[i]-2*m1-m2;
-    out[i] = a*t*t*t + b*t*t + m1*t + p1[i];
-  }
+const hermiteVec3 = (out, p0, m0, p1, m1, t) => {
+  const t2=t*t, t3=t2*t;
+  const h00=2*t3-3*t2+1, h10=t3-2*t2+t, h01=-2*t3+3*t2, h11=t3-t2;
+  out[0]=h00*p0[0]+h10*m0[0]+h01*p1[0]+h11*m1[0];
+  out[1]=h00*p0[1]+h10*m0[1]+h01*p1[1]+h11*m1[1];
+  out[2]=h00*p0[2]+h10*m0[2]+h01*p1[2]+h11*m1[2];
+  return out;
+};
+
+// Centripetal CR outgoing tangent at p1 for segment p1→p2, scaled by dt1.
+const _crTanOut = (out, p0, p1, p2, p3) => {
+  const dt0=Math.pow(_dist3(p0,p1),0.5)||1, dt1=Math.pow(_dist3(p1,p2),0.5)||1; Math.pow(_dist3(p2,p3),0.5)||1;
+  for (let i=0;i<3;i++) out[i]=((p1[i]-p0[i])/dt0-(p2[i]-p0[i])/(dt0+dt1)+(p2[i]-p1[i])/dt1)*dt1;
+  return out;
+};
+
+// Centripetal CR incoming tangent at p2 for segment p1→p2, scaled by dt1.
+const _crTanIn = (out, p0, p1, p2, p3) => {
+  Math.pow(_dist3(p0,p1),0.5)||1; const dt1=Math.pow(_dist3(p1,p2),0.5)||1, dt2=Math.pow(_dist3(p2,p3),0.5)||1;
+  for (let i=0;i<3;i++) out[i]=((p2[i]-p1[i])/dt1-(p3[i]-p1[i])/(dt1+dt2)+(p3[i]-p2[i])/dt2)*dt1;
   return out;
 };
 
+// Module-level scratch — shared by eval() across all track instances (non-reentrant hot path).
+const _m0=[0,0,0], _m1=[0,0,0];
+
 /**
  * Linear interpolation between two vec3s.
  * @param {number[]} out
@@ -1188,7 +1199,7 @@ const _EULER_ORDERS = new Set(['XYZ','XZY','YXZ','YZX','ZXY','ZYX']);
  */
 function _parseQuat(v) {
   if (!v) return null;
-  
+
   // raw [x,y,z,w] — plain array or typed array
   if ((Array.isArray(v) || ArrayBuffer.isView(v)) && v.length === 4) return [v[0], v[1], v[2], v[3]];
 
@@ -1280,13 +1291,15 @@ function _parseQuat(v) {
  *     Float32Array(16), plain Array, or { mat4 } wrapper.
  *     pos from col3, scl from column lengths, rot from normalised rotation block.
  *
- *   { pos, rot, scl }
+ *   { pos?, rot?, scl?, tanIn?, tanOut? }
  *     Explicit TRS.  pos and scl are vec3, rot accepts any form from _parseQuat.
  *     All fields are optional — missing pos/scl default to [0,0,0] / [1,1,1],
  *     missing rot defaults to identity.
+ *     tanIn/tanOut are optional vec3 tangents for Hermite interpolation.
+ *     When absent, centripetal Catmull-Rom tangents are auto-computed at eval time.
  *
  * @param {Object} spec
- * @returns {{ pos:number[], rot:number[], scl:number[] }|null}
+ * @returns {{ pos:number[], rot:number[], scl:number[], tanIn:number[]|null, tanOut:number[]|null }|null}
  */
 function _parseSpec(spec) {
   if (!spec || typeof spec !== 'object') return null;
@@ -1296,13 +1309,17 @@ function _parseSpec(spec) {
     const m = (ArrayBuffer.isView(spec.mMatrix) || Array.isArray(spec.mMatrix))
       ? spec.mMatrix : (spec.mMatrix.mat4 ?? null);
     if (!m || m.length < 16) return null;
-    return mat4ToTransform({ pos:[0,0,0], rot:[0,0,0,1], scl:[1,1,1] }, m);
+    const kf = mat4ToTransform({ pos:[0,0,0], rot:[0,0,0,1], scl:[1,1,1] }, m);
+    kf.tanIn = null; kf.tanOut = null;
+    return kf;
   }
 
-  const pos = _parseVec3(spec.pos) || [0,0,0];
-  const rot = _parseQuat(spec.rot) || [0,0,0,1];
-  const scl = _parseVec3(spec.scl) || [1,1,1];
-  return { pos, rot, scl };
+  const pos    = _parseVec3(spec.pos)    || [0,0,0];
+  const rot    = _parseQuat(spec.rot)    || [0,0,0,1];
+  const scl    = _parseVec3(spec.scl)    || [1,1,1];
+  const tanIn  = _parseVec3(spec.tanIn)  || null;
+  const tanOut = _parseVec3(spec.tanOut) || null;
+  return { pos, rot, scl, tanIn, tanOut };
 }
 
 function _sameTransform(a, b) {
@@ -1320,9 +1337,12 @@ function _sameTransform(a, b) {
  *
  * Accepted forms:
  *
- *   { eye, center?, up? }
+ *   { eye, center?, up?, fov?, halfHeight?,
+ *     eyeTanIn?, eyeTanOut?, centerTanIn?, centerTanOut? }
  *     Explicit lookat.  center defaults to [0,0,0], up defaults to [0,1,0].
  *     Both are normalised/stored as-is.  eye must be a vec3.
+ *     eyeTanIn/Out and centerTanIn/Out are optional vec3 tangents for Hermite.
+ *     When absent, centripetal Catmull-Rom tangents are auto-computed at eval time.
  *
  *   { vMatrix: mat4 }
  *     Column-major view matrix (world→eye).
@@ -1338,7 +1358,10 @@ function _sameTransform(a, b) {
  *     Float32Array(16), plain Array, or { mat4 } wrapper.
  *
  * @param {Object} spec
- * @returns {{ eye:number[], center:number[], up:number[] }|null}
+ * @returns {{ eye:number[], center:number[], up:number[],
+ *             fov:number|null, halfHeight:number|null,
+ *             eyeTanIn:number[]|null, eyeTanOut:number[]|null,
+ *             centerTanIn:number[]|null, centerTanOut:number[]|null }|null}
  */
 function _parseCameraSpec(spec) {
   if (!spec || typeof spec !== 'object') return null;
@@ -1354,7 +1377,8 @@ function _parseCameraSpec(spec) {
     const fx=-m[8], fy=-m[9], fz=-m[10];
     const fl=Math.sqrt(fx*fx+fy*fy+fz*fz)||1;
     return { eye:[ex,ey,ez], center:[ex+fx/fl,ey+fy/fl,ez+fz/fl], up:[0,1,0],
-             fov:null, halfHeight:null };
+             fov:null, halfHeight:null,
+             eyeTanIn:null, eyeTanOut:null, centerTanIn:null, centerTanOut:null };
   }
 
   // { eMatrix } — eye matrix (eye→world); eye = col3, forward = -col2
@@ -1366,21 +1390,26 @@ function _parseCameraSpec(spec) {
     const fx=-m[8], fy=-m[9], fz=-m[10];
     const fl=Math.sqrt(fx*fx+fy*fy+fz*fz)||1;
     return { eye:[ex,ey,ez], center:[ex+fx/fl,ey+fy/fl,ez+fz/fl], up:[0,1,0],
-             fov:null, halfHeight:null };
+             fov:null, halfHeight:null,
+             eyeTanIn:null, eyeTanOut:null, centerTanIn:null, centerTanOut:null };
   }
 
   // { eye, center?, up? } — explicit lookat (eye is a vec3, not a mat4)
   const eye    = _parseVec3(spec.eye);
   if (!eye) return null;
   const center = _parseVec3(spec.center) || [0,0,0];
-  const upRaw = spec.up ? _parseVec3(spec.up) : null;
-  const up    = upRaw || [0,1,0];
-  const ul    = Math.sqrt(up[0]*up[0]+up[1]*up[1]+up[2]*up[2]) || 1;
+  const upRaw  = spec.up ? _parseVec3(spec.up) : null;
+  const up     = upRaw || [0,1,0];
+  const ul     = Math.sqrt(up[0]*up[0]+up[1]*up[1]+up[2]*up[2]) || 1;
   return {
     eye, center,
     up: [up[0]/ul, up[1]/ul, up[2]/ul],
-    fov:        typeof spec.fov        === 'number' ? spec.fov        : null,
-    halfHeight: typeof spec.halfHeight === 'number' ? spec.halfHeight : null,
+    fov:         typeof spec.fov        === 'number' ? spec.fov        : null,
+    halfHeight:  typeof spec.halfHeight === 'number' ? spec.halfHeight : null,
+    eyeTanIn:    _parseVec3(spec.eyeTanIn)    || null,
+    eyeTanOut:   _parseVec3(spec.eyeTanOut)   || null,
+    centerTanIn: _parseVec3(spec.centerTanIn) || null,
+    centerTanOut:_parseVec3(spec.centerTanOut)|| null,
   };
 }
 
@@ -1427,6 +1456,10 @@ class Track {
     // Lib-space hooks (set by host layer, e.g. p5 bridge)
     /** @type {Function|null} */ this._onActivate   = null;
     /** @type {Function|null} */ this._onDeactivate = null;
+    // Lib-space event mirrors — set by UI layer (trackUI), never touched by user code
+    /** @type {Function|null} */ this._onPlay = null;
+    /** @type {Function|null} */ this._onEnd  = null;
+    /** @type {Function|null} */ this._onStop = null;
   }
 
   /** Playback rate. Assigning never starts/stops playback. @type {number} */
@@ -1474,6 +1507,7 @@ class Track {
     this.playing = true;
     if (!wasPlaying) {
       if (typeof this.onPlay === 'function') { try { this.onPlay(this); } catch (_) {} }
+      this._onPlay?.();
       this._onActivate?.();
     }
     return this;
@@ -1489,6 +1523,7 @@ class Track {
     this.playing = false;
     if (wasPlaying) {
       if (typeof this.onStop === 'function') { try { this.onStop(this); } catch (_) {} }
+      this._onStop?.();
       this._onDeactivate?.();
       if (rewind && this.keyframes.length > 1) this.seek(this._rate < 0 ? 1 : 0);
     }
@@ -1504,6 +1539,7 @@ class Track {
     this.playing = false;
     if (wasPlaying) {
       if (typeof this.onStop === 'function') { try { this.onStop(this); } catch (_) {} }
+      this._onStop?.();
       this._onDeactivate?.();
     }
     this.keyframes.length = 0;
@@ -1614,6 +1650,7 @@ class Track {
       this._setCursorFromScalar(0);
       this.playing = false;
       if (typeof this.onEnd === 'function') { try { this.onEnd(this); } catch (_) {} }
+      this._onEnd?.();
       this._onDeactivate?.();
       return false;
     }
@@ -1621,6 +1658,7 @@ class Track {
       this._setCursorFromScalar(total);
       this.playing = false;
       if (typeof this.onEnd === 'function') { try { this.onEnd(this); } catch (_) {} }
+      this._onEnd?.();
       this._onDeactivate?.();
       return false;
     }
@@ -1647,12 +1685,18 @@ class Track {
 /**
  * Renderer-agnostic TRS keyframe track.
  *
- * Keyframe shape: { pos:[x,y,z], rot:[x,y,z,w], scl:[x,y,z] }
+ * Keyframe shape: { pos:[x,y,z], rot:[x,y,z,w], scl:[x,y,z],
+ *                   tanIn?:[x,y,z], tanOut?:[x,y,z] }
+ *
+ * tanIn  — incoming position tangent at this keyframe (Hermite mode).
+ * tanOut — outgoing position tangent at this keyframe (Hermite mode).
+ * When only one is supplied, the other mirrors it.
+ * When neither is supplied, centripetal Catmull-Rom tangents are auto-computed.
  *
  * add() accepts individual specs or a bulk array of specs:
  *
  *   { mMatrix }                           — full TRS from model matrix
- *   { pos?, rot?, scl? }                  — direct TRS; all fields optional
+ *   { pos?, rot?, scl?, tanIn?, tanOut? } — direct TRS; all fields optional
  *   { pos?, rot: [x,y,z,w] }             — explicit quaternion
  *   { pos?, rot: { axis, angle } }        — axis-angle
  *   { pos?, rot: { dir, up? } }           — look direction
@@ -1665,16 +1709,15 @@ class Track {
  * Missing fields default to: pos → [0,0,0], rot → [0,0,0,1], scl → [1,1,1].
  *
  * eval() writes { pos, rot, scl }:
- *   pos — Catmull-Rom (posInterp='catmullrom') or lerp
- *   rot — slerp (rotInterp='slerp') or nlerp
+ *   pos — Hermite (tanIn/tanOut per keyframe; auto-CR when absent) or linear or step
+ *   rot — slerp (rotInterp='slerp') or nlerp or step
  *   scl — lerp
  *
  * @example
  * const track = new PoseTrack()
- * track.add({ pos:[0,0,0] })                           // identity rot, uniform scl
- * track.add({ pos:[100,0,0], rot: { euler:[0, Math.PI/2, 0] } })
- * track.add({ rot: { axis:[0,1,0], angle: Math.PI } }) // pos defaults to [0,0,0]
- * track.add({ mMatrix: someModelMatrix })
+ * track.add({ pos:[0,0,0] })
+ * track.add({ pos:[100,0,0], tanOut:[0,50,0] })   // leave heading +Y
+ * track.add({ pos:[200,0,0] })
  * track.play({ loop: true })
  * // per frame:
  * track.tick()
@@ -1686,14 +1729,19 @@ class PoseTrack extends Track {
     super();
     /**
      * Position interpolation mode.
-     * @type {'catmullrom'|'linear'}
+     * - 'hermite' — cubic Hermite; uses tanIn/tanOut per keyframe when present,
+     *               auto-computes centripetal Catmull-Rom tangents when absent (default)
+     * - 'linear'  — lerp
+     * - 'step'    — snap to k0 value; useful for discrete state changes
+     * @type {'hermite'|'linear'|'step'}
      */
-    this.posInterp = 'catmullrom';
+    this.posInterp = 'hermite';
     /**
      * Rotation interpolation mode.
      * - 'slerp'  — constant angular velocity (default)
      * - 'nlerp'  — normalised lerp; cheaper, slightly non-constant speed
-     * @type {'slerp'|'nlerp'}
+     * - 'step'   — snap to k0 quaternion; useful for discrete state changes
+     * @type {'slerp'|'nlerp'|'step'}
      */
     this.rotInterp = 'slerp';
     // Scratch for toMatrix() — avoids hot-path allocations
@@ -1761,17 +1809,29 @@ class PoseTrack extends Track {
     const k0   = this.keyframes[seg];
     const k1   = this.keyframes[seg + 1];
 
-    // pos — Catmull-Rom or lerp
-    if (this.posInterp === 'catmullrom') {
-      const p0 = seg > 0      ? this.keyframes[seg - 1].pos : k0.pos;
-      const p3 = seg + 2 < n ? this.keyframes[seg + 2].pos : k1.pos;
-      catmullRomVec3(out.pos, p0, k0.pos, k1.pos, p3, t);
-    } else {
+    // pos — Hermite (auto-CR tangents when none stored), linear, or step
+    if (this.posInterp === 'step') {
+      out.pos[0]=k0.pos[0]; out.pos[1]=k0.pos[1]; out.pos[2]=k0.pos[2];
+    } else if (this.posInterp === 'linear') {
       lerpVec3(out.pos, k0.pos, k1.pos, t);
+    } else {
+      const p0 = seg > 0      ? this.keyframes[seg - 1].pos : k0.pos;
+      const p3 = seg + 2 < n ? this.keyframes[seg + 2].pos  : k1.pos;
+      // tanOut on k0: use stored, else symmetric from tanIn, else auto-CR
+      const m0 = k0.tanOut != null ? k0.tanOut
+               : k0.tanIn  != null ? k0.tanIn
+               : _crTanOut(_m0, p0, k0.pos, k1.pos, p3);
+      // tanIn on k1: use stored, else symmetric from tanOut, else auto-CR
+      const m1 = k1.tanIn  != null ? k1.tanIn
+               : k1.tanOut != null ? k1.tanOut
+               : _crTanIn(_m1, p0, k0.pos, k1.pos, p3);
+      hermiteVec3(out.pos, k0.pos, m0, k1.pos, m1, t);
     }
 
-    // rot — slerp or nlerp
-    if (this.rotInterp === 'nlerp') {
+    // rot — step, slerp, or nlerp
+    if (this.rotInterp === 'step') {
+      out.rot[0]=k0.rot[0]; out.rot[1]=k0.rot[1]; out.rot[2]=k0.rot[2]; out.rot[3]=k0.rot[3];
+    } else if (this.rotInterp === 'nlerp') {
       qNlerp(out.rot, k0.rot, k1.rot, t);
     } else {
       qSlerp(out.rot, k0.rot, k1.rot, t);
@@ -1801,23 +1861,31 @@ class PoseTrack extends Track {
 /**
  * Lookat camera keyframe track.
  *
- * Keyframe shape: { eye:[x,y,z], center:[x,y,z], up:[x,y,z], fov?:number, halfHeight?:number }
+ * Keyframe shape: { eye:[x,y,z], center:[x,y,z], up:[x,y,z],
+ *                   fov?:number, halfHeight?:number,
+ *                   eyeTanIn?:[x,y,z], eyeTanOut?:[x,y,z],
+ *                   centerTanIn?:[x,y,z], centerTanOut?:[x,y,z] }
  *
  * fov        — vertical fov (radians) for perspective cameras; null for ortho.
  * halfHeight — world-unit half-height of ortho frustum; null for perspective.
  * Both are optional and nullable. eval() lerps each only when both adjacent
  * keyframes carry a non-null value for that field.
  *
+ * eyeTanIn/Out and centerTanIn/Out are optional vec3 tangents for Hermite
+ * interpolation of the eye and center paths respectively.
+ * When absent, centripetal Catmull-Rom tangents are auto-computed at eval time.
+ *
  * Each field is independently interpolated — eye and center along their
  * own paths, up nlerped on the unit sphere. This correctly handles cameras
  * that always look at a fixed target (center stays at origin throughout)
  * as well as free-fly paths where center moves independently.
- * 
+ *
  * Missing fields default to: center → [0,0,0], up → [0,1,0].
  *
  * add() accepts individual specs or a bulk array of specs:
  *
- *   { eye, center?, up?, fov?, halfHeight? }
+ *   { eye, center?, up?, fov?, halfHeight?,
+ *     eyeTanIn?, eyeTanOut?, centerTanIn?, centerTanOut? }
  *                         explicit lookat; center defaults to [0,0,0], up to [0,1,0].
  *                         fov and halfHeight are mutually exclusive nullable scalars.
  *   { vMatrix: mat4 }      view matrix (world→eye); eye reconstructed via -R^T·t
@@ -1831,8 +1899,8 @@ class PoseTrack extends Track {
  *   Use capturePose() (p5.tree bridge) when the real up hint is needed.
  *
  * eval() writes { eye, center, up, fov, halfHeight }:
- *   eye        — Catmull-Rom (eyeInterp='catmullrom') or lerp
- *   center     — Catmull-Rom (centerInterp='catmullrom') or lerp
+ *   eye        — Hermite (auto-CR when no tangents stored) or linear or step
+ *   center     — Hermite (auto-CR when no tangents stored) or linear or step
  *   up         — nlerp (normalize-after-lerp on unit sphere)
  *   fov        — lerp when both keyframes carry non-null fov; else null
  *   halfHeight — lerp when both keyframes carry non-null halfHeight; else null
@@ -1857,14 +1925,20 @@ class CameraTrack extends Track {
     super();
     /**
      * Eye position interpolation mode.
-     * @type {'catmullrom'|'linear'}
+     * - 'hermite' — cubic Hermite; auto-CR tangents when none stored (default)
+     * - 'linear'  — lerp
+     * - 'step'    — snap to k0 eye
+     * @type {'hermite'|'linear'|'step'}
      */
-    this.eyeInterp = 'catmullrom';
+    this.eyeInterp = 'hermite';
     /**
      * Center (lookat target) interpolation mode.
-     * 'linear' suits fixed or predictably moving targets.
-     * 'catmullrom' gives smoother paths when center is also flying freely.
-     * @type {'catmullrom'|'linear'}
+     * 'linear' suits fixed or predictably moving targets (default).
+     * 'hermite' gives smoother paths when center is also flying freely.
+     * - 'hermite' — cubic Hermite; auto-CR tangents when none stored
+     * - 'linear'  — lerp
+     * - 'step'    — snap to k0 center
+     * @type {'hermite'|'linear'|'step'}
      */
     this.centerInterp = 'linear';
     // Scratch for toCamera() — avoids hot-path allocations
@@ -1937,22 +2011,38 @@ class CameraTrack extends Track {
     const k0   = this.keyframes[seg];
     const k1   = this.keyframes[seg + 1];
 
-    // eye — Catmull-Rom or lerp
-    if (this.eyeInterp === 'catmullrom') {
-      const p0 = seg > 0      ? this.keyframes[seg - 1].eye : k0.eye;
-      const p3 = seg + 2 < n ? this.keyframes[seg + 2].eye : k1.eye;
-      catmullRomVec3(out.eye, p0, k0.eye, k1.eye, p3, t);
-    } else {
+    // eye — Hermite (auto-CR tangents when none stored), linear, or step
+    if (this.eyeInterp === 'step') {
+      out.eye[0]=k0.eye[0]; out.eye[1]=k0.eye[1]; out.eye[2]=k0.eye[2];
+    } else if (this.eyeInterp === 'linear') {
       lerpVec3(out.eye, k0.eye, k1.eye, t);
+    } else {
+      const p0 = seg > 0      ? this.keyframes[seg - 1].eye : k0.eye;
+      const p3 = seg + 2 < n ? this.keyframes[seg + 2].eye  : k1.eye;
+      const m0 = k0.eyeTanOut != null ? k0.eyeTanOut
+               : k0.eyeTanIn  != null ? k0.eyeTanIn
+               : _crTanOut(_m0, p0, k0.eye, k1.eye, p3);
+      const m1 = k1.eyeTanIn  != null ? k1.eyeTanIn
+               : k1.eyeTanOut != null ? k1.eyeTanOut
+               : _crTanIn(_m1, p0, k0.eye, k1.eye, p3);
+      hermiteVec3(out.eye, k0.eye, m0, k1.eye, m1, t);
     }
 
-    // center — Catmull-Rom or lerp (independent lookat target)
-    if (this.centerInterp === 'catmullrom') {
-      const c0 = seg > 0      ? this.keyframes[seg - 1].center : k0.center;
-      const c3 = seg + 2 < n ? this.keyframes[seg + 2].center : k1.center;
-      catmullRomVec3(out.center, c0, k0.center, k1.center, c3, t);
-    } else {
+    // center — Hermite, linear, or step (independent lookat target)
+    if (this.centerInterp === 'step') {
+      out.center[0]=k0.center[0]; out.center[1]=k0.center[1]; out.center[2]=k0.center[2];
+    } else if (this.centerInterp === 'linear') {
       lerpVec3(out.center, k0.center, k1.center, t);
+    } else {
+      const c0 = seg > 0      ? this.keyframes[seg - 1].center : k0.center;
+      const c3 = seg + 2 < n ? this.keyframes[seg + 2].center  : k1.center;
+      const m0 = k0.centerTanOut != null ? k0.centerTanOut
+               : k0.centerTanIn  != null ? k0.centerTanIn
+               : _crTanOut(_m0, c0, k0.center, k1.center, c3);
+      const m1 = k1.centerTanIn  != null ? k1.centerTanIn
+               : k1.centerTanOut != null ? k1.centerTanOut
+               : _crTanIn(_m1, c0, k0.center, k1.center, c3);
+      hermiteVec3(out.center, k0.center, m0, k1.center, m1, t);
     }
 
     // up — nlerp (normalize after lerp; correct for typical near-upright cameras)
@@ -2130,5 +2220,5 @@ function boxVisibility(planes, x0, y0, z0, x1, y1, z1) {
   return allIn ? VISIBLE : SEMIVISIBLE;
 }
 
-export { CameraTrack, EYE, INVISIBLE, MATRIX, MODEL, NDC, ORIGIN, PLANE_BOTTOM, PLANE_FAR, PLANE_LEFT, PLANE_NEAR, PLANE_RIGHT, PLANE_TOP, PoseTrack, SCREEN, SEMIVISIBLE, VISIBLE, WEBGL, WEBGPU, WORLD, _i, _j, _k, applyPickMatrix, boxVisibility, catmullRomVec3, distanceToPlane, frustumPlanes, i, j, k, lerpVec3, mapDirection, mapLocation, mat3Direction, mat3NormalFromMat4, mat4Invert, mat4Location, mat4MV, mat4Mul, mat4MulPoint, mat4PV, mat4ToTransform, mat4Transpose, pixelRatio, pointVisibility, projBottom, projFar, projFov, projHfov, projIsOrtho, projLeft, projNear, projRight, projTop, qCopy, qDot, qFromAxisAngle, qFromLookDir, qFromMat4, qFromRotMat3x3, qMul, qNegate, qNlerp, qNormalize, qSet, qSlerp, qToMat4, quatToAxisAngle, sphereVisibility, transformToMat4 };
+export { CameraTrack, EYE, INVISIBLE, MATRIX, MODEL, NDC, ORIGIN, PLANE_BOTTOM, PLANE_FAR, PLANE_LEFT, PLANE_NEAR, PLANE_RIGHT, PLANE_TOP, PoseTrack, SCREEN, SEMIVISIBLE, VISIBLE, WEBGL, WEBGPU, WORLD, _i, _j, _k, applyPickMatrix, boxVisibility, distanceToPlane, frustumPlanes, hermiteVec3, i, j, k, lerpVec3, mapDirection, mapLocation, mat3Direction, mat3NormalFromMat4, mat4Invert, mat4Location, mat4MV, mat4Mul, mat4MulPoint, mat4PV, mat4ToTransform, mat4Transpose, pixelRatio, pointVisibility, projBottom, projFar, projFov, projHfov, projIsOrtho, projLeft, projNear, projRight, projTop, qCopy, qDot, qFromAxisAngle, qFromLookDir, qFromMat4, qFromRotMat3x3, qMul, qNegate, qNlerp, qNormalize, qSet, qSlerp, qToMat4, quatToAxisAngle, sphereVisibility, transformToMat4 };
 //# sourceMappingURL=index.js.map