vexy-stax-js 3.0.0

package/src/export.js

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: Apache-2.0
+// this_file: src/export.js
+//
+// Image + video export (SPEC.md §6.1). Image: read the renderer's WebGL canvas
+// to a PNG Blob. Video: capture the deck transition to an encoded clip — WebCodecs
+// (VideoEncoder + muxed via captureStream/MediaRecorder when available) with a
+// MediaRecorder fallback for browsers without WebCodecs. Both paths produce a
+// Blob the caller can download.
+
+/**
+ * Read a canvas to a PNG Blob.
+ * @param {HTMLCanvasElement} canvas
+ * @returns {Promise<Blob>}
+ */
+export function canvasToPngBlob(canvas) {
+  return new Promise((resolve, reject) => {
+    if (!canvas || typeof canvas.toBlob !== "function") {
+      reject(new Error("canvasToPngBlob: canvas.toBlob unavailable in this environment"));
+      return;
+    }
+    canvas.toBlob((blob) => {
+      if (blob) resolve(blob);
+      else reject(new Error("canvasToPngBlob: toBlob produced no blob"));
+    }, "image/png");
+  });
+}
+
+/** True when MediaRecorder + canvas.captureStream are usable. */
+function hasMediaRecorder() {
+  return (
+    typeof MediaRecorder !== "undefined" &&
+    typeof HTMLCanvasElement !== "undefined" &&
+    typeof HTMLCanvasElement.prototype.captureStream === "function"
+  );
+}
+
+/** Pick the first supported MediaRecorder mime type, or undefined for the default. */
+function pickMimeType() {
+  if (typeof MediaRecorder === "undefined" || typeof MediaRecorder.isTypeSupported !== "function") {
+    return undefined;
+  }
+  const candidates = ["video/webm;codecs=vp9", "video/webm;codecs=vp8", "video/webm", "video/mp4"];
+  return candidates.find((t) => MediaRecorder.isTypeSupported(t));
+}
+
+/**
+ * Record a transition to a video Blob.
+ *
+ * Drives `playFrames(applyOneFrame)`: the caller renders each frame onto the
+ * canvas synchronously inside the per-frame callback, and we capture the canvas
+ * stream while it plays. WebCodecs is preferred when present (lower latency, mp4
+ * where supported); otherwise MediaRecorder captures the live canvas stream.
+ *
+ * @param {object} opts
+ * @param {HTMLCanvasElement} opts.canvas the renderer canvas to capture
+ * @param {(onFrame:(state:object)=>void)=>Promise<void>} opts.run plays the
+ *   transition, calling onFrame for each frame (which must render to the canvas)
+ * @param {number} [opts.fps] frame rate for the captured stream
+ * @returns {Promise<Blob>}
+ */
+export async function recordVideo({ canvas, run, fps = 30 }) {
+  if (!canvas) throw new Error("recordVideo: canvas is required");
+  if (typeof run !== "function") throw new Error("recordVideo: run() callback is required");
+
+  if (typeof VideoEncoder !== "undefined" && typeof canvas.captureStream === "function") {
+    // WebCodecs path: still capture via MediaRecorder on the encoded stream when
+    // available, since muxing raw VideoEncoder chunks into a container is heavy.
+    // We treat presence of MediaRecorder as the muxer; if it's missing we fall
+    // through to the explicit WebCodecs-only encoder below.
+    if (hasMediaRecorder()) {
+      return recordViaMediaRecorder({ canvas, run, fps });
+    }
+    return recordViaWebCodecs({ canvas, run, fps });
+  }
+
+  if (hasMediaRecorder()) {
+    return recordViaMediaRecorder({ canvas, run, fps });
+  }
+
+  throw new Error(
+    "recordVideo: neither WebCodecs (VideoEncoder) nor MediaRecorder/captureStream is available in this environment"
+  );
+}
+
+async function recordViaMediaRecorder({ canvas, run, fps }) {
+  const stream = canvas.captureStream(fps);
+  const mimeType = pickMimeType();
+  const recorder = new MediaRecorder(stream, mimeType ? { mimeType } : undefined);
+  const chunks = [];
+  recorder.ondataavailable = (e) => {
+    if (e.data && e.data.size > 0) chunks.push(e.data);
+  };
+  const stopped = new Promise((resolve) => {
+    recorder.onstop = () => resolve();
+  });
+  recorder.start();
+  try {
+    await run((/* state */) => {
+      // The frame is already rendered by the stage; captureStream samples the
+      // canvas. requestFrame() (when available) forces a sample for this frame.
+      const track = stream.getVideoTracks?.()[0];
+      track?.requestFrame?.();
+    });
+  } finally {
+    if (recorder.state !== "inactive") recorder.stop();
+  }
+  await stopped;
+  stream.getTracks?.().forEach((t) => t.stop());
+  return new Blob(chunks, { type: recorder.mimeType || mimeType || "video/webm" });
+}
+
+async function recordViaWebCodecs({ canvas, run, fps }) {
+  // Minimal WebCodecs path: encode each frame; emit raw chunks wrapped as a Blob.
+  // (Full container muxing is out of scope; MediaRecorder is the primary path and
+  // this branch only runs where MediaRecorder is unavailable but VideoEncoder is.)
+  const chunks = [];
+  const encoder = new VideoEncoder({
+    output: (chunk) => {
+      const buf = new ArrayBuffer(chunk.byteLength);
+      chunk.copyTo(buf);
+      chunks.push(new Uint8Array(buf));
+    },
+    error: (e) => {
+      throw e;
+    },
+  });
+  encoder.configure({
+    codec: "vp09.00.10.08",
+    width: canvas.width,
+    height: canvas.height,
+    framerate: fps,
+  });
+  let frameIndex = 0;
+  await run(() => {
+    const frame = new VideoFrame(canvas, { timestamp: (frameIndex * 1e6) / fps });
+    encoder.encode(frame, { keyFrame: frameIndex % fps === 0 });
+    frame.close();
+    frameIndex += 1;
+  });
+  await encoder.flush();
+  encoder.close();
+  return new Blob(chunks, { type: "video/webm" });
+}

package/src/geometry.js

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: Apache-2.0
+// this_file: src/geometry.js
+//
+// Engine-agnostic view geometry per SPEC.md §3, mirroring
+// vexy-stax-py/src/vexy_stax/geometry.py EXACTLY (same formulas, same easings,
+// same camera math). Pure functions only. The numeric outputs must match the
+// Python for the same scene.
+//
+// Coordinate convention (three.js Y-up — SPEC.md §1, §3):
+// - X = plate width (centered at 0); Y = vertical/up (plates centered at Y=0);
+//   Z = depth/stacking, front plate at Z=0, index 0 (farthest) at Z=-stackDepth,
+//   +Z toward the viewer. Deck center is at Z = -stackDepth/2.
+// - Compact camera sits head-on on +Z; expanded orbits to azimuth/elevation.
+// - Camera framing uses scene.size as the plate size so Python and JS agree.
+// - Plate width/height in points == pixel dimensions of the source image.
+
+import { resolvedOpacity } from "./scene.js";
+
+export const MIN_GAP = 3.0;
+export const FILL = 0.85;
+
+/** Per-slide gap (points), falling back to camera.gap when unset (null). */
+export function plateGaps(scene) {
+  return scene.slides.map((s) => (s.gap === null || s.gap === undefined ? scene.camera.gap : s.gap));
+}
+
+/**
+ * Total deck depth along Z. Compact collapses every gap to MIN_GAP; expanded
+ * sums the (N-1) inter-plate gaps (gaps[0] is before slide 0 and unused).
+ */
+export function stackDepth(scene, view) {
+  const n = scene.slides.length;
+  if (n <= 1) return 0.0;
+  if (view === "compact") return (n - 1) * MIN_GAP;
+  const gaps = plateGaps(scene);
+  let sum = 0;
+  for (let i = 1; i < gaps.length; i++) sum += gaps[i];
+  return sum;
+}
+
+/** Per-plate Z (front plate at 0, index 0 at -stackDepth). Mirrors _stack_positions. */
+function stackPositions(gaps) {
+  const n = gaps.length;
+  if (n === 0) return [];
+  let depth = 0;
+  for (let i = 1; i < n; i++) depth += gaps[i];
+  const cum = [0.0];
+  for (let i = 1; i < n; i++) cum.push(cum[cum.length - 1] + gaps[i]);
+  return cum.map((c) => c - depth);
+}
+
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const cross = (a, b) => [
+  a[1] * b[2] - a[2] * b[1],
+  a[2] * b[0] - a[0] * b[2],
+  a[0] * b[1] - a[1] * b[0],
+];
+function normalize(a) {
+  const n = Math.sqrt(a[0] * a[0] + a[1] * a[1] + a[2] * a[2]) || 1.0;
+  return [a[0] / n, a[1] / n, a[2] / n];
+}
+
+/** Resolve a distance spec to absolute points (number, numeric string, or "P%"). */
+function parseDistance(distance, viewportWidth) {
+  if (typeof distance === "number") return distance;
+  const text = String(distance).trim();
+  if (text.endsWith("%")) return (parseFloat(text.slice(0, -1)) / 100.0) * viewportWidth;
+  return parseFloat(text);
+}
+
+/**
+ * Angled hero camera framing the expanded *deck* (SPEC.md §3). Fits the plate
+ * bounding box (not the floor diagonal) so the deck fills FILL of the frame on
+ * its tighter axis. Plate size = scene.size so JS and Python agree exactly.
+ * Returns { position:[x,y,z], target:[x,y,z], fov, near }.
+ */
+export function expandedCamera(scene) {
+  const cam = scene.camera;
+  const depth = stackDepth(scene, "expanded");
+  const target = [0.0, 0.0, -depth / 2.0];
+
+  // Direction target -> camera (azimuth swings toward -X, elevation lifts +Y).
+  const az = (cam.angle * Math.PI) / 180.0;
+  const el = (cam.elevation * Math.PI) / 180.0;
+  const toCam = normalize([
+    -Math.sin(az) * Math.cos(el),
+    Math.sin(el),
+    Math.cos(az) * Math.cos(el),
+  ]);
+  const look = [-toCam[0], -toCam[1], -toCam[2]]; // camera -> target
+
+  const upWorld = [0.0, 1.0, 0.0];
+  let right = cross(look, upWorld);
+  right = Math.abs(dot(look, upWorld)) < 0.999 ? normalize(right) : [1.0, 0.0, 0.0];
+  const up = normalize(cross(right, look));
+
+  const halfWPlate = scene.size.width / 2.0;
+  const halfHPlate = scene.size.height / 2.0;
+  const zPositions = stackPositions(plateGaps(scene));
+  let halfW = 0.0;
+  let halfH = 0.0;
+  for (const z of zPositions) {
+    for (const sx of [-halfWPlate, halfWPlate]) {
+      for (const sy of [-halfHPlate, halfHPlate]) {
+        const rel = sub([sx, sy, z], target);
+        halfW = Math.max(halfW, Math.abs(dot(rel, right)));
+        halfH = Math.max(halfH, Math.abs(dot(rel, up)));
+      }
+    }
+  }
+
+  const hfov = (cam.fov * Math.PI) / 180.0;
+  const aspect = scene.size.width / scene.size.height;
+  const vfov = 2.0 * Math.atan(Math.tan(hfov / 2.0) / aspect);
+  const dW = halfW / (FILL * Math.tan(hfov / 2.0));
+  const dH = halfH / (FILL * Math.tan(vfov / 2.0));
+  const distance = Math.max(dW, dH);
+  const near = Math.max(1.0, distance * 0.005);
+  const position = [
+    target[0] + toCam[0] * distance,
+    target[1] + toCam[1] * distance,
+    target[2] + toCam[2] * distance,
+  ];
+  return { position, target, fov: cam.fov, near };
+}
+
+/**
+ * Head-on camera on +Z aimed at the deck center. `distance` is "P%" of viewport
+ * width or absolute points; near plane scales with distance.
+ * Returns { position:[x,y,z], target:[x,y,z], fov, near }.
+ */
+export function compactCamera(scene) {
+  const cam = scene.camera;
+  const depth = stackDepth(scene, "compact");
+  const target = [0.0, 0.0, -depth / 2.0];
+  const distance = parseDistance(cam.distance, scene.size.width);
+  const near = Math.max(1.0, distance * 0.005);
+  const position = [target[0], target[1], target[2] + distance];
+  return { position, target, fov: cam.fov, near };
+}
+
+/** Evaluate a shared easing curve at t (clamped to [0, 1]). */
+export function ease(name, t) {
+  t = Math.max(0.0, Math.min(1.0, t));
+  if (name === "linear") return t;
+  if (name === "easeInCubic") return t * t * t;
+  if (name === "easeOutCubic") {
+    const u = 1.0 - t;
+    return 1.0 - u * u * u;
+  }
+  if (name === "easeInOutCubic") {
+    if (t < 0.5) return 4.0 * t * t * t;
+    const u = -2.0 * t + 2.0;
+    return 1.0 - (u * u * u) / 2.0;
+  }
+  throw new Error(`Unknown easing: ${JSON.stringify(name)}`);
+}
+
+/**
+ * Opacity at morph progress tExpanded in [0, 1] (0=compact, 1=expanded). Lerps
+ * the compact and expanded per-view values. Mirrors interpolate_opacity.
+ */
+export function interpolateOpacity(slide, tExpanded) {
+  const t = Math.max(0.0, Math.min(1.0, tExpanded));
+  const lo = resolvedOpacity(slide, "compact");
+  const hi = resolvedOpacity(slide, "expanded");
+  const value = lo + (hi - lo) * t;
+  return Math.max(0.0, Math.min(1.0, value));
+}
+
+function lerp3(a, b, t) {
+  return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+}
+
+function poseAt(compact, expanded, t) {
+  return {
+    position: lerp3(compact.position, expanded.position, t),
+    target: lerp3(compact.target, expanded.target, t),
+    fov: compact.fov + (expanded.fov - compact.fov) * t,
+    near: compact.near + (expanded.near - compact.near) * t,
+  };
+}
+
+/** Build a frame state at morph factor t (already eased) from precomputed poses. */
+function frameState(scene, compact, expanded, t) {
+  const expandedGaps = plateGaps(scene);
+  const gaps = expandedGaps.map((g) => MIN_GAP + (g - MIN_GAP) * t);
+  const opacities = scene.slides.map((s) => interpolateOpacity(s, t));
+  return { camera: poseAt(compact, expanded, t), gaps, opacities };
+}
+
+/**
+ * Build a FrameState at an already-eased morph factor t (0=compact, 1=expanded).
+ * Computes the compact/expanded endpoint poses on demand; used by the playable
+ * transition driver and scrollspy so a single t produces the full morph state
+ * (camera pose + per-plate gaps + per-slide opacities).
+ * @param {object} scene parsed scene
+ * @param {number} t eased morph factor
+ */
+export function frameStateAt(scene, t) {
+  const compact = compactCamera(scene);
+  const expanded = expandedCamera(scene);
+  return frameState(scene, compact, expanded, Math.max(0, Math.min(1, t)));
+}
+
+// Each transition is a sequence of legs expressed as morph endpoints
+// (0=compact, 1=expanded). Mirrors _LEGS in geometry.py.
+const LEGS = {
+  expand: [[0.0, 1.0]],
+  collapse: [[1.0, 0.0]],
+  expand_collapse: [
+    [0.0, 1.0],
+    [1.0, 0.0],
+  ],
+  collapse_expand: [
+    [1.0, 0.0],
+    [0.0, 1.0],
+  ],
+};
+
+/**
+ * Per-frame states for scene.transition (empty when no transition). Each leg
+ * renders round(duration*fps) frames; a hold of round(wait*fps) frames is
+ * inserted at the far end of each leg. Mirrors frame_plan in geometry.py.
+ */
+export function framePlan(scene) {
+  const tr = scene.transition;
+  if (!tr) return [];
+  const compact = compactCamera(scene);
+  const expanded = expandedCamera(scene);
+  const legFrames = Math.round(tr.duration * tr.fps);
+  const waitFrames = Math.round(tr.wait * tr.fps);
+  const legs = LEGS[tr.kind];
+
+  const states = [];
+  for (const [start, end] of legs) {
+    for (let i = 0; i < legFrames; i++) {
+      const p = legFrames ? i / legFrames : 0.0;
+      const eased = ease(tr.easing, p);
+      const t = start + (end - start) * eased;
+      states.push(frameState(scene, compact, expanded, t));
+    }
+    const hold = frameState(scene, compact, expanded, end);
+    for (let i = 0; i < waitFrames; i++) states.push(hold);
+  }
+  return states;
+}

package/src/global.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: Apache-2.0
+// this_file: src/global.js
+//
+// Classic-script global entry (SPEC.md §6.3). Importing this auto-registers the
+// <vexy-stax> element (via element.js) and exposes window.VexyStax.
+
+import { VexyStax, loadScene } from "./index.js";
+import "./element.js";
+
+const api = { VexyStax, loadScene };
+
+if (typeof window !== "undefined") {
+  window.VexyStax = api;
+}
+
+export { VexyStax, loadScene };

package/src/index.js

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: Apache-2.0
+// this_file: src/index.js
+//
+// Public ESM API (SPEC.md §6.1): a static view, image export, a playable
+// transition, video export, and a scroll-driven transition. The view math comes
+// from geometry.js (mirrors the Python exactly); the morph driver, scrollspy
+// mapping, and exporters are in transition.js / scrollspy.js / export.js.
+
+import { Stage } from "./stage.js";
+import { loadScene, parseScene, resolvedOpacity } from "./scene.js";
+import { frameStateAt, ease } from "./geometry.js";
+import { playTransition, transitionEndpoints, buildTimeline, morphAtProgress } from "./transition.js";
+import { attachScrollspy } from "./scrollspy.js";
+import { canvasToPngBlob, recordVideo } from "./export.js";
+
+export {
+  loadScene,
+  parseScene,
+  resolvedOpacity,
+};
+
+export {
+  MIN_GAP,
+  FILL,
+  plateGaps,
+  stackDepth,
+  compactCamera,
+  expandedCamera,
+  ease,
+  interpolateOpacity,
+  framePlan,
+  frameStateAt,
+} from "./geometry.js";
+
+export { buildTimeline, morphAtProgress, transitionEndpoints } from "./transition.js";
+export { computeScrollProgress, prefersReducedMotion } from "./scrollspy.js";
+export { canvasToPngBlob } from "./export.js";
+
+export class VexyStax {
+  /**
+   * @param {HTMLElement} container mount point for the three.js canvas
+   * @param {object} scene normalized scene object (from loadScene)
+   */
+  constructor(container, scene) {
+    if (!container) throw new Error("VexyStax: container is required");
+    if (!scene || !Array.isArray(scene.slides)) {
+      throw new Error("VexyStax: scene must be a parsed scene object (use loadScene first)");
+    }
+    this.container = container;
+    this.scene = scene;
+    this.stage = new Stage(container, scene);
+    this._ready = this.stage.init().then(() => {
+      this.stage.render();
+      return this;
+    });
+  }
+
+  /** Resolves once textures are loaded and the initial view is rendered. */
+  get ready() {
+    return this._ready;
+  }
+
+  /** Position the deck + camera for a view and render a frame. */
+  async setView(view) {
+    await this._ready;
+    this.stage.setView(view);
+    this.stage.render();
+    return this;
+  }
+
+  /** Resize the renderer/camera to the container (or explicit size). */
+  resize(width, height) {
+    const w = width ?? this.container.clientWidth;
+    const h = height ?? this.container.clientHeight;
+    this.stage.resize(w, h);
+    this.stage.render();
+  }
+
+  /**
+   * Render the current view to a PNG Blob. `scale` re-renders at a higher
+   * pixel size. (Animated transition export is a later story.)
+   */
+  async toImage({ scale = 1 } = {}) {
+    await this._ready;
+    const renderer = this.stage.renderer;
+    const canvas = renderer.domElement;
+    let restore = null;
+    if (scale !== 1) {
+      // getSize fills a Vector2; we read CSS size then re-render larger.
+      const w = canvas.width;
+      const h = canvas.height;
+      const cssW = this.container.clientWidth || this.scene.size.width;
+      const cssH = this.container.clientHeight || this.scene.size.height;
+      const prevPR = renderer.getPixelRatio();
+      renderer.setPixelRatio(prevPR * scale);
+      renderer.setSize(cssW, cssH, false);
+      restore = () => {
+        renderer.setPixelRatio(prevPR);
+        renderer.setSize(cssW, cssH, false);
+        this.stage.render();
+      };
+    }
+    this.stage.render();
+    try {
+      return await canvasToPngBlob(canvas);
+    } finally {
+      if (restore) restore();
+    }
+  }
+
+  // --- Render operations (SPEC.md §6.1) ------------------------------------
+
+  /**
+   * Play a transition (camera + spacing + opacity + caption fade morph) as an
+   * animation, rendering each frame. Resolves when the animation finishes.
+   *
+   * @param {string} [kind] override scene.transition.kind
+   * @param {object} [opts]
+   * @param {(p:number)=>void} [opts.onProgress] global progress [0,1] per frame
+   * @returns {Promise<this>}
+   */
+  async transition(kind, opts = {}) {
+    await this._ready;
+    const resolvedKind = kind ?? this.scene.transition?.kind;
+    if (!resolvedKind) {
+      throw new Error("VexyStax.transition: no kind given and scene.transition is null");
+    }
+    // Snap to the starting endpoint so the first frame is correct.
+    const { startMorph } = transitionEndpoints(resolvedKind);
+    this.stage.applyFrameState(frameStateAt(this.scene, startMorph), startMorph);
+    this.stage.render();
+
+    this._cancelTransition?.();
+    const controller = playTransition(this.scene, (state) => {
+      // Derive the (unclamped) morph factor for caption fade from the state's
+      // camera lerp between compact/expanded targets is unnecessary; the driver
+      // already passes opacities/gaps. We re-derive t from gaps[1] for captions.
+      const t = this._morphFromGaps(state.gaps);
+      this.stage.applyFrameState(state, t);
+      this.stage.render();
+    }, { kind: resolvedKind, onProgress: opts.onProgress });
+
+    this._cancelTransition = controller.cancel;
+    this.container.dispatchEvent?.(new CustomEvent("transitionstart", { detail: { kind: resolvedKind } }));
+    try {
+      await controller.promise;
+      this.container.dispatchEvent?.(new CustomEvent("transitionend", { detail: { kind: resolvedKind } }));
+    } finally {
+      this._cancelTransition = null;
+    }
+    return this;
+  }
+
+  /** Re-derive the morph factor t from a frame's gap[1] (for caption fade). */
+  _morphFromGaps(gaps) {
+    if (gaps.length < 2) return 0;
+    const fullGap = this.stage.scene.camera.gap;
+    const span = fullGap - 3.0; // MIN_GAP = 3
+    if (span <= 0) return gaps[1] >= fullGap ? 1 : 0;
+    return Math.max(0, Math.min(1, (gaps[1] - 3.0) / span));
+  }
+
+  /**
+   * Record the transition to a video Blob (WebCodecs preferred, MediaRecorder
+   * fallback). Plays the full transition while capturing the canvas.
+   * @param {object} [opts]
+   * @param {string} [opts.kind] override scene.transition.kind
+   * @returns {Promise<Blob>}
+   */
+  async toVideo(opts = {}) {
+    await this._ready;
+    const kind = opts.kind ?? this.scene.transition?.kind;
+    if (!kind) throw new Error("VexyStax.toVideo: no kind given and scene.transition is null");
+    const fps = this.scene.transition?.fps ?? 30;
+    const canvas = this.stage.renderer.domElement;
+
+    return recordVideo({
+      canvas,
+      fps,
+      run: async (onFrame) => {
+        const controller = playTransition(this.scene, (state) => {
+          const t = this._morphFromGaps(state.gaps);
+          this.stage.applyFrameState(state, t);
+          this.stage.render();
+          onFrame(state);
+        }, { kind });
+        await controller.promise;
+      },
+    });
+  }
+
+  /**
+   * Drive the transition from scroll position over a trigger region (SPEC.md
+   * §6.4). Maps scroll progress [0,1] to the morph; respects
+   * prefers-reduced-motion (snaps to endpoints).
+   *
+   * @param {object} opts
+   * @param {Element|string} opts.trigger element or selector for the scroll region
+   * @param {string} [opts.kind] override scene.transition.kind
+   * @param {boolean} [opts.reducedMotion] override prefers-reduced-motion
+   * @returns {{disconnect:()=>void}}
+   */
+  scrollspy(opts = {}) {
+    const kind = opts.kind ?? this.scene.transition?.kind ?? "expand";
+    const trigger =
+      typeof opts.trigger === "string" ? document.querySelector(opts.trigger) : opts.trigger;
+    if (!trigger) throw new Error("VexyStax.scrollspy: trigger element not found");
+
+    // Build a normalized timeline so scroll progress maps through the same legs
+    // (including holds) as the playable animation.
+    const easing = this.scene.transition?.easing ?? "easeInOutCubic";
+    const duration = this.scene.transition?.duration ?? 3.0;
+    const wait = this.scene.transition?.wait ?? 0.0;
+
+    const apply = (p) => {
+      // Map global scroll progress through the transition timeline → morph t.
+      const t = this._scrollMorph(kind, p, easing, duration, wait);
+      this.stage.applyFrameState(frameStateAt(this.scene, t), t);
+      this.stage.render();
+    };
+
+    // Prime to the starting endpoint.
+    apply(0);
+
+    this._scrollspy?.disconnect?.();
+    this._scrollspy = attachScrollspy({
+      trigger,
+      reducedMotion: opts.reducedMotion,
+      onProgress: apply,
+    });
+    return this._scrollspy;
+  }
+
+  /** Resolve scroll progress p to a morph factor via the transition timeline. */
+  _scrollMorph(kind, p, easing, duration, wait) {
+    const timeline = buildTimeline(kind, { duration, wait });
+    return morphAtProgress(timeline, p, (x) => ease(easing, x));
+  }
+
+  /** Tear down the three.js stage, stop animations/scrollspy, remove the canvas. */
+  destroy() {
+    this._cancelTransition?.();
+    this._scrollspy?.disconnect?.();
+    this.stage?.dispose();
+  }
+}