vexy-stax-js 3.0.1 → 3.1.1

package/CHANGELOG.md

@@ -4,6 +4,119 @@
 
 All notable changes to this project are documented here.
 
+## [3.0.11] — issues 335, 336, 337
+
+### Added
+
+- **`video` scene section** (335 / 336): `scene.js` `parseVideo()` + the JSON schema now accept and
+  validate the `video` section (`width`/`height`/`fps`/`frames`/`first_hold`/`last_hold`), mirroring
+  `vexy_stax.scene.Video`. Previously the strict parser rejected the key with "Unknown key 'video' in
+  scene", which broke the Python `playwright` engine (it mounts the scene in `<vexy-stax>`) — issue
+  336. The element now accepts a scene carrying `video`.
+- **Held first/last still frames in `toVideo()`** (335 §2): the video export now bookends the clip
+  with held stills — it renders the start endpoint and captures it `video.first_hold` times (default
+  10), plays the transition, then captures the end endpoint `video.last_hold` times (still →
+  transition → still). Mirrors `geometry.py`'s `frame_plan` holds. Verified: the exported
+  `airbl-transition.mp4` first/last frames are static.
+
+### Fixed
+
+- **Compact view reserved empty caption space** (337): `compactCamera` now fits ONLY the frontmost
+  slide plate (height `H`, aimed at the slide center `Y = lift`) instead of the slide+caption
+  composite, so the compact view fills the frame with no caption padding. Mirrors `geometry.py`
+  (issue 337). Verified: the playwright-rendered compact still fills the frame; geometry test updated.
+
+## [3.0.10] — issues 331
+
+### Fixed
+
+- **Seekable mp4 video export** (331): `src/export.js` `recordVideo()` now uses a
+  deterministic WebCodecs + `mp4-muxer` primary path instead of the broken
+  `captureStream`/MediaRecorder approach. The new `recordViaMuxer()` function:
+  - Checks H.264 (`avc1.640028`) support via `VideoEncoder.isConfigSupported()`; falls
+    back to VP9 (`vp09.00.10.08`) if H.264 is unavailable.
+  - Feeds each `VideoFrame(canvas, {timestamp, duration})` into a `VideoEncoder` whose
+    output chunks are piped directly to a `mp4-muxer` `Muxer` with
+    `fastStart: "in-memory"` and an `ArrayBufferTarget`.
+  - Calls `muxer.finalize()` after `encoder.flush()`, producing a `Blob([target.buffer],
+    {type:"video/mp4"})` with correct per-stream `duration` and `nb_frames` metadata —
+    verified seekable by ffprobe.
+  - `MediaRecorder` (live `captureStream`) is retained as a last-resort fallback for
+    environments entirely without `VideoEncoder`.
+- **`verify/example.mjs` extension logic** (331): the `ext` variable already derived the
+  extension from `blob.type` (`mp4` vs `webm`), so the primary path now writes
+  `airbl-transition.mp4` automatically.
+
+### Added
+
+- **Deployable `docs/` site for GitHub Pages** (331 part 2):
+  - `scripts/build-docs.mjs` copies the built `dist/` bundles (element + global + source
+    maps), the `airbl-lores` scene JSON + slide PNGs, writes a self-contained
+    `docs/index.html` landing page with a playable `<vexy-stax>` demo and usage snippets
+    for all three entry points (Web Component, ESM import, global script), and a short
+    `docs/README.md`.
+  - `package.json` gains a `build:docs` script (`node scripts/build-docs.mjs`).
+  - `build.sh` calls `npm run build:docs` after `npm run build`, so the docs site is
+    regenerated on every full build.
+  - Base path is `/vexy-stax-js/` (GitHub Pages subdirectory), set via a `<base>` tag
+    in `index.html`.
+
+## [3.0.9] — issue 332
+
+### Added
+
+- **Global `captions` on/off toggle** (332): a new top-level boolean scene field (default `true`,
+  preserving prior behavior) parsed + validated in `src/scene.js` and
+  `schema/vexy-stax-scene.schema.json` (strict — a non-bool throws). When `false`, no caption plates
+  are built (`stage.js`) and `captionOpacities` returns all-zero, and the slide plates drop directly
+  onto the floor.
+
+### Changed
+
+- **New stacked caption layout** (332): when captions are ON, each caption plate sits RIGHT ON the
+  floor (bottom edge on the floor line) and its slide plate sits directly ON TOP of it, LEFT-aligned
+  with the slide (caption left edge == slide left edge at `X = -width/2`). This replaces the previous
+  "caption to the LEFT of the plate" layout. Mirrors `vexy-stax-py` exactly.
+  - `geometry.js`: added `slideLift(scene)` (one caption-plate height when captions on, else 0); every
+    slide plate is lifted by it in `stage.js`. `captionAnchorX` now means the caption plate's LEFT edge
+    (numerically unchanged since `CAPTION_GAP_EM == 0`). `captionOpacities` returns all-zero when
+    `captions` is off.
+  - **Crop-free camera framing for the full composite**: `compactCamera` fits the frontmost COMPOSITE
+    (width `W`, height `H + lift`) and aims at its center (`Y = lift/2`); `expandedCamera` includes the
+    lifted slide corners AND the on-floor caption-plate bottom row in its bounding fit, so the
+    caption+slide stack is framed with no crop.
+  - `stage.js`: lifts plates/borders/reflections by `slideLift`, anchors each caption plate by its LEFT
+    edge on the floor, and skips caption plates entirely when the toggle is off.
+
+## [3.0.8] — issues 328, 329, 330
+
+### Changed
+
+- **Static Zalando Sans `<link>` in the generated demos** (328): `verify/example.mjs` now emits the
+  Google Fonts preconnect + `Zalando+Sans:wdth,wght@125,500` stylesheet directly in the `<head>` of
+  both `playable.html` and `scrollable.html`, so the caption face is available before first paint.
+  (The element's runtime `_ensureCaptionFonts` injection from 3.0.7 still awaits `document.fonts`,
+  so this just removes the first-frame fallback flash.)
+
+### Verified (no code change needed)
+
+- **`scrollable.html` reflects current src** (329): the demo HTML is regenerated from the live
+  `src/` on every `example.sh` / `example.mjs` run (and now also when the Python `example.py`
+  rebuilds the JS demos — issue 330), so there is no stale checked-in copy to "port" changes into.
+- **`outputs/` cleanup** (330): `example.sh` already `rm -rf outputs` before regenerating, so stale
+  artifacts are removed on every rebuild.
+
+## [3.0.7] — issue 328
+
+### Changed
+
+- **Default caption font → "Zalando Sans"** (328): the default caption font is now "Zalando Sans"
+  pulled from Google Fonts at wdth 125 / wght 500 (matching the bundled Python `vexy-stax.ttf` =
+  Zalando Sans Expanded). `makeCaptionSprite` renders the default at `500 expanded` with 0.02em
+  tracking (an explicit family is still used plainly, with a `system-ui, sans-serif` fallback).
+  `_ensureCaptionFonts` injects the Google Fonts preconnect links + the Zalando Sans stylesheet
+  and preloads the face by default whenever a caption uses the default font.
+
 ## [3.0.6] — issue 327
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vexy-stax-js",
-  "version": "3.0.1",
+  "version": "3.1.1",
   "description": "Browser renderer for the vexy-stax shared scene format: 3D glass plates in two views, with morphable opacity. Ships as ESM, Web Component, and a classic-script global.",
   "type": "module",
   "exports": {
@@ -19,7 +19,8 @@
     "build": "VEXY_BUILD=element vite build && VEXY_BUILD=global vite build",
     "preview": "vite preview",
     "test:unit": "node --test",
-    "test": "npm run test:unit && playwright test"
+    "test": "npm run test:unit && playwright test",
+    "build:docs": "node scripts/build-docs.mjs"
   },
   "keywords": [
     "threejs",
@@ -48,6 +49,7 @@
   },
   "dependencies": {
     "gsap": "^3.13.0",
+    "mp4-muxer": "^5.2.2",
     "three": "^0.181.0"
   },
   "devDependencies": {

package/schema/vexy-stax-scene.schema.json

@@ -69,6 +69,20 @@
     },
     "background": { "type": "string", "default": "#ffffff" },
     "juicy": { "type": "boolean", "default": false, "description": "Python-only per-channel color match." },
+    "captions": { "type": "boolean", "default": true, "description": "Global captions toggle (issue 332). ON: each slide plate sits on top of its on-floor caption plate (stacked layout). OFF: no caption plates; slide plates sit directly on the floor." },
+    "video": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Video render params (issue 335 §3): dimensions/fps/frame counts/held stills. transition still owns the animation (kind/easing/wait/duration); video owns the output framing. Defaults preserve prior behavior.",
+      "properties": {
+        "width": { "type": "integer", "minimum": 1, "description": "Video width; omitted ⇒ size.width." },
+        "height": { "type": "integer", "minimum": 1, "description": "Video height; omitted ⇒ size.height." },
+        "fps": { "type": "integer", "minimum": 1, "description": "Video frames per second; omitted ⇒ transition.fps (else 30). Overrides transition.fps when set." },
+        "frames": { "type": "integer", "minimum": 1, "description": "Transition frames PER LEG; omitted ⇒ round(transition.duration × fps)." },
+        "first_hold": { "type": "integer", "minimum": 0, "default": 10, "description": "Held copies of the FIRST frame (still intro)." },
+        "last_hold": { "type": "integer", "minimum": 0, "default": 10, "description": "Held copies of the LAST frame (still outro)." }
+      }
+    },
     "caption_defaults": { "$ref": "#/$defs/captionStyle" },
     "caption_fade": {
       "type": "object",

package/src/export.js

@@ -2,10 +2,15 @@
 // 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.
+// to a PNG Blob. Video: capture the deck transition to an encoded, seekable clip.
+//
+// PRIMARY path (issue 331): WebCodecs (VideoEncoder) + mp4-muxer → H.264/mp4.
+// Produces a fully seekable mp4 with correct duration + per-stream frame metadata.
+// Falls back to webm-muxer+VP9 if H.264 is unsupported, then finally to
+// MediaRecorder (live captureStream) as the last-resort path for environments
+// that lack VideoEncoder entirely.
+
+import { Muxer, ArrayBufferTarget } from "mp4-muxer";
 
 /**
  * Read a canvas to a PNG Blob.
@@ -43,36 +48,66 @@ function pickMimeType() {
   return candidates.find((t) => MediaRecorder.isTypeSupported(t));
 }
 
+/**
+ * Check whether a given VideoEncoder codec string is supported.
+ * @param {string} codec
+ * @param {number} width
+ * @param {number} height
+ * @param {number} fps
+ * @returns {Promise<boolean>}
+ */
+async function isCodecSupported(codec, width, height, fps) {
+  if (typeof VideoEncoder === "undefined") return false;
+  try {
+    const { supported } = await VideoEncoder.isConfigSupported({
+      codec,
+      width,
+      height,
+      framerate: fps,
+    });
+    return !!supported;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 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.
+ * Drives `run(onFrame)`: the caller renders each frame onto the canvas
+ * synchronously inside the per-frame callback. The PRIMARY path uses WebCodecs
+ * (VideoEncoder) + mp4-muxer to produce a seekable mp4 with correct duration
+ * and per-stream frame count metadata. Falls back to MediaRecorder only when
+ * VideoEncoder is unavailable.
  *
  * @param {object} opts
- * @param {HTMLCanvasElement} opts.canvas the renderer canvas to capture
- * @param {(onFrame:(state:object)=>void)=>Promise<void>} opts.run plays the
+ * @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
+ * @param {number} [opts.fps]  frame rate for the encoded clip (default 30)
  * @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 });
+  // PRIMARY: WebCodecs + mp4-muxer (issue 331) — prefer H.264/mp4; fall back to
+  // VP9/webm inside the same muxed path if H.264 is unsupported.
+  if (typeof VideoEncoder !== "undefined") {
+    const w = canvas.width;
+    const h = canvas.height;
+    const avcCodec = "avc1.640028"; // H.264 High Profile Level 4.0
+    const vp9Codec = "vp09.00.10.08";
+
+    const useAvc = await isCodecSupported(avcCodec, w, h, fps);
+    const useVp9 = !useAvc && (await isCodecSupported(vp9Codec, w, h, fps));
+
+    if (useAvc || useVp9) {
+      return recordViaMuxer({ canvas, run, fps, useAvc });
     }
-    return recordViaWebCodecs({ canvas, run, fps });
   }
 
+  // FALLBACK: MediaRecorder (captureStream) — no mux metadata, non-seekable.
   if (hasMediaRecorder()) {
     return recordViaMediaRecorder({ canvas, run, fps });
   }
@@ -82,6 +117,72 @@ export async function recordVideo({ canvas, run, fps = 30 }) {
   );
 }
 
+/**
+ * PRIMARY recording path: VideoEncoder frames piped into mp4-muxer (H.264) or
+ * webm-muxer (VP9). Produces a properly seekable container with real duration +
+ * per-stream nb_frames metadata.
+ *
+ * @param {object} opts
+ * @param {HTMLCanvasElement} opts.canvas
+ * @param {(onFrame:()=>void)=>Promise<void>} opts.run
+ * @param {number} opts.fps
+ * @param {boolean} opts.useAvc  true→H.264+mp4, false→VP9+webm via mp4-muxer
+ */
+async function recordViaMuxer({ canvas, run, fps, useAvc }) {
+  const w = canvas.width;
+  const h = canvas.height;
+  const codec = useAvc ? "avc1.640028" : "vp09.00.10.08";
+
+  const target = new ArrayBufferTarget();
+  const muxer = new Muxer({
+    target,
+    video: {
+      codec: useAvc ? "avc" : "vp9",
+      width: w,
+      height: h,
+    },
+    // fastStart embeds the moov atom at the front for immediate seeking in players.
+    fastStart: "in-memory",
+  });
+
+  const chunks = [];
+  const encoder = new VideoEncoder({
+    output: (chunk, meta) => {
+      muxer.addVideoChunk(chunk, meta);
+    },
+    error: (e) => {
+      throw e;
+    },
+  });
+
+  encoder.configure({
+    codec,
+    width: w,
+    height: h,
+    framerate: fps,
+    // H.264: signal avc1 bitstream (Annex-B not needed for mp4-muxer).
+    ...(useAvc ? { avc: { format: "avc" } } : {}),
+  });
+
+  let frameIndex = 0;
+  const frameDuration = Math.round(1e6 / fps); // microseconds per frame
+
+  await run(() => {
+    const timestamp = frameIndex * frameDuration;
+    const frame = new VideoFrame(canvas, { timestamp, duration: frameDuration });
+    encoder.encode(frame, { keyFrame: frameIndex % fps === 0 });
+    frame.close();
+    frameIndex += 1;
+  });
+
+  await encoder.flush();
+  encoder.close();
+  muxer.finalize();
+
+  const mimeType = useAvc ? "video/mp4" : "video/webm";
+  return new Blob([target.buffer], { type: mimeType });
+}
+
 async function recordViaMediaRecorder({ canvas, run, fps }) {
   const stream = canvas.captureStream(fps);
   const mimeType = pickMimeType();
@@ -108,36 +209,3 @@ async function recordViaMediaRecorder({ canvas, run, fps }) {
   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

@@ -84,17 +84,30 @@ export function captionPlateHeight(scene) {
 }
 
 /**
- * World Y of a caption plate's vertical center (issue 311): the plate sits on the virtual
- * ground (Y = -height/2), so its center is half its height above it. Mirrors geometry.py.
+ * World Y of a caption plate's vertical center (issue 311; relayout issue 332): the plate
+ * sits RIGHT ON the floor (its bottom edge on the floor line Y = -height/2), so its center
+ * is half its plate height above it. The slide plate then sits on TOP (see slideLift).
+ * Mirrors caption_plate_center_y in geometry.py.
  */
 export function captionPlateCenterY(scene) {
   return -(scene.size.height / 2.0) + captionPlateHeight(scene) / 2.0;
 }
 
 /**
- * World X where every caption's RIGHT edge aligns — CAPTION_GAP_EM em left of the plate
- * left edge (-width/2). All plates share scene.size width centered at X=0. Mirrors
- * caption_anchor_x in geometry.py.
+ * World Y offset added to EVERY slide plate's vertical center (issue 332). Captions ON: each
+ * slide sits on TOP of its on-floor caption plate, so it is lifted by exactly one
+ * caption-plate height relative to the centered (Y=0) convention. Captions OFF: no caption
+ * plates, slides sit directly on the floor → lift 0. Mirrors slide_lift in geometry.py.
+ */
+export function slideLift(scene) {
+  return scene.captions ? captionPlateHeight(scene) : 0.0;
+}
+
+/**
+ * World X where every caption plate's LEFT edge aligns (issue 332 relayout): the caption
+ * plate is LEFT-aligned with its slide plate, so its left edge sits at the slide left edge
+ * (-width/2). CAPTION_GAP_EM is 0, so the numeric value is unchanged from the prior
+ * right-edge anchor; only the meaning (now a LEFT edge) changed. Mirrors caption_anchor_x.
  */
 export function captionAnchorX(scene) {
   return -(scene.size.width / 2.0 + CAPTION_GAP_EM * captionSize(scene));
@@ -199,16 +212,27 @@ export function expandedCamera(scene, viewportAspect) {
   const halfHPlate = scene.size.height / 2.0;
   const zPositions = stackPositions(plateGaps(scene));
 
+  // Issue 332: slides are LIFTED by one caption-plate height (captions on) so they sit on
+  // top of their on-floor caption plates. The full composite the camera frames (NO crop)
+  // spans vertically from the floor line (caption-plate bottom == -H/2) up to the lifted
+  // slide top (lift + H/2). Include the lifted slide corners AND the caption-plate bottom
+  // corners so the bounding fit never crops the caption row. Mirrors geometry.py.
+  const lift = slideLift(scene);
+  const floorY = -halfHPlate; // caption plate bottom (and floor line)
+  const slideYLo = lift - halfHPlate;
+  const slideYHi = lift + halfHPlate;
+  const capYs = scene.captions ? [floorY] : []; // extra bottom row (caption plate bottom)
+
   // Precompute each corner's (right, up, look) offsets relative to baseTarget so
   // projecting at a candidate (distance D, horizontal pan) is cheap and exact.
   // ndc_x = (cr - pan)/((cl + D)*th). Mirrors geometry.py expanded_camera.
   const corners = []; // [cr, cu, cl]
   const centers = []; // [cr, cl] of each plate center
   for (const z of zPositions) {
-    const relC = sub([0.0, 0.0, z], baseTarget);
+    const relC = sub([0.0, lift, z], baseTarget);
     centers.push([dot(relC, right), dot(relC, look)]);
     for (const sx of [-halfWPlate, halfWPlate]) {
-      for (const sy of [-halfHPlate, halfHPlate]) {
+      for (const sy of [slideYLo, slideYHi, ...capYs]) {
         const rel = sub([sx, sy, z], baseTarget);
         corners.push([dot(rel, right), dot(rel, up), dot(rel, look)]);
       }
@@ -306,8 +330,15 @@ export function expandedCamera(scene, viewportAspect) {
 export function compactCamera(scene, viewportAspect) {
   const cam = scene.camera;
   const depth = stackDepth(scene, "compact");
-  const target = [0.0, 0.0, -depth / 2.0];
-  
+  // Issue 337: the compact view frames ONLY the frontmost SLIDE plate — not the composite with
+  // its caption row. Captions are invisible in compact (they fade in only as the deck expands),
+  // so reserving the caption-plate height just padded the frame. The slide is lifted by `lift`
+  // (issue 332: it sits on top of the on-floor caption plate), so its center is at Y = lift and
+  // it spans height H. Aim at the slide center and fit H so the slide fills the frame tight.
+  // Mirrors geometry.py.
+  const lift = slideLift(scene);
+  const target = [0.0, lift, -depth / 2.0];
+
   let isPercent = false;
   let pctVal = 90.0;
   if (typeof cam.distance === "string") {
@@ -318,12 +349,13 @@ export function compactCamera(scene, viewportAspect) {
       if (!isNaN(parsed)) pctVal = parsed;
     }
   }
-  
+
   let distance;
   if (isPercent) {
-    // Dual-axis crop-free fit (SPEC.md §3, issue 302 §1): fit the frontmost plate
-    // (scene.size) so the limiting axis touches P% and the other axis only ever has
-    // extra padding (never a crop). distance = max(d_w, d_h). Mirrors geometry.py.
+    // Dual-axis crop-free fit (SPEC.md §3, issue 302 §1, issue 337): fit the frontmost SLIDE
+    // plate (width W, height H — NOT the caption composite) so the limiting axis touches P% and
+    // the other axis only ever has extra padding (never a crop). distance = max(d_w, d_h).
+    // Mirrors geometry.py.
     const hfov = (cam.fov * Math.PI) / 180.0;
     const aspect = viewportAspect || scene.size.width / scene.size.height;
     const vfov = 2.0 * Math.atan(Math.tan(hfov / 2.0) / aspect);
@@ -335,7 +367,7 @@ export function compactCamera(scene, viewportAspect) {
   } else {
     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 };
@@ -380,6 +412,8 @@ export function interpolateOpacity(slide, tExpanded) {
  */
 export function captionOpacities(scene, tExpanded) {
   const t = Math.max(0.0, Math.min(1.0, tExpanded));
+  // Issue 332: a global captions=false toggle suppresses ALL caption plates everywhere.
+  if (!scene.captions) return scene.slides.map(() => 0.0);
   const cf = scene.caption_fade;
   const window = cf ? cf.window : CAPTION_FADE_WINDOW;
   const stagger = cf ? cf.stagger : CAPTION_STAGGER;

package/src/index.js

@@ -205,13 +205,28 @@ export class VexyStax {
     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 fps = this.scene.video?.fps ?? this.scene.transition?.fps ?? 30;
     const canvas = this.stage.renderer.domElement;
+    // Issue 335 §2: bookend the clip with HELD STILLS — render the start frame and capture it
+    // `first_hold` times, then the transition, then capture the end frame `last_hold` times
+    // (still → transition → still). Defaults 10/10 from scene.video. Mirrors geometry.py's
+    // frame_plan holds (the Python engines get holds via frame_plan; here toVideo drives a
+    // real-time capture, so we hold by capturing the boundary frames repeatedly).
+    const firstHold = this.scene.video?.first_hold ?? 10;
+    const lastHold = this.scene.video?.last_hold ?? 10;
+    const { startMorph, endMorph } = transitionEndpoints(kind);
+    const aspect = this.stage.camera.aspect;
 
     return recordVideo({
       canvas,
       fps,
       run: async (onFrame) => {
+        // Held still intro: snap to the start endpoint and capture it `firstHold` times.
+        const startState = frameStateAt(this.scene, startMorph, aspect);
+        this.stage.applyFrameState(startState, startMorph);
+        this.stage.render();
+        for (let i = 0; i < firstHold; i++) onFrame(startState);
+
         const controller = playTransition(this.scene, (state) => {
           const t = this._morphFromGaps(state.gaps);
           this.stage.applyFrameState(state, t);
@@ -219,6 +234,12 @@ export class VexyStax {
           onFrame(state);
         }, { kind });
         await controller.promise;
+
+        // Held still outro: snap to the end endpoint and capture it `lastHold` times.
+        const endState = frameStateAt(this.scene, endMorph, aspect);
+        this.stage.applyFrameState(endState, endMorph);
+        this.stage.render();
+        for (let i = 0; i < lastHold; i++) onFrame(endState);
       },
     });
   }

package/src/scene.js

@@ -113,6 +113,28 @@ function parseTransition(raw) {
   };
 }
 
+// Issue 335 §3 / 336: the `video` section centralizes the VIDEO render params. Mirrors
+// vexy_stax.scene.Video exactly so PY and JS agree. Always present (default below): width/
+// height fall back to scene.size when null; fps falls back to transition.fps (else 30);
+// frames (transition frames PER LEG) falls back to round(transition.duration * fps);
+// first_hold/last_hold (default 10) prepend/append held still frames in the video.
+function parseVideo(raw) {
+  if (raw === undefined) {
+    return { width: null, height: null, fps: null, frames: null, first_hold: 10, last_hold: 10 };
+  }
+  const o = asObject(raw, "video");
+  rejectExtraKeys(o, new Set(["width", "height", "fps", "frames", "first_hold", "last_hold"]), "video");
+  const orNull = (v, where, opts) => (v === undefined || v === null ? null : int(v, where, opts));
+  return {
+    width: orNull(o.width, "video.width", { min: 1 }),
+    height: orNull(o.height, "video.height", { min: 1 }),
+    fps: orNull(o.fps, "video.fps", { min: 1 }),
+    frames: orNull(o.frames, "video.frames", { min: 1 }),
+    first_hold: o.first_hold === undefined ? 10 : int(o.first_hold, "video.first_hold", { min: 0 }),
+    last_hold: o.last_hold === undefined ? 10 : int(o.last_hold, "video.last_hold", { min: 0 }),
+  };
+}
+
 function parseFloor(raw) {
   // Smoked glass: ~4% opacity, dark tint, reflective (issue 303 §1).
   if (raw === undefined) return { color: "#1a1a1a", opacity: 0.04, reflectivity: 0.5 };
@@ -232,6 +254,8 @@ export function parseScene(raw) {
     "edge",
     "background",
     "juicy",
+    "captions",
+    "video",
     "caption_defaults",
     "caption_fade",
     "slides",
@@ -256,6 +280,10 @@ export function parseScene(raw) {
     edge: parseEdge(o.edge),
     background: o.background === undefined ? "#ffffff" : str(o.background, "background"),
     juicy: o.juicy === undefined ? false : bool(o.juicy, "juicy"),
+    // Issue 332: global captions toggle (default true → preserves prior stacked-with-captions
+    // behavior). false skips all caption plates and drops slides onto the floor.
+    captions: o.captions === undefined ? true : bool(o.captions, "captions"),
+    video: parseVideo(o.video),
     caption_defaults: parseCaptionStyle(o.caption_defaults, "caption_defaults"),
     caption_fade: parseCaptionFade(o.caption_fade),
     slides: o.slides.map((s, i) => parseSlide(s, i)),

package/src/stage.js

@@ -23,6 +23,7 @@ import {
   captionFillColor,
   captionBorderColor,
   captionOpacities,
+  slideLift,
   plateEdgeWidth,
   CAPTION_PLATE_PAD_EM,
   REFLECTION_BLUR_FRAC,
@@ -56,19 +57,28 @@ export function makeCaptionSprite(text, style) {
   const fillColor = style?.fillColor ?? edgeColor;
   const borderColor = style?.borderColor ?? edgeColor;
 
-  // Caption font stack (issue 327): the requested family (e.g. REM from Google Fonts) with a
-  // `system-ui, sans-serif` fallback so an unloaded/unknown family never falls back to the
-  // canvas default serif (which renders as Times New Roman). Quote the family for safety.
-  const fontFamily = style?.font ? `"${style.font}", system-ui, sans-serif` : "system-ui, sans-serif";
-
+  // Caption font (issue 328): the default is "Zalando Sans" — the bundled vexy-stax face — an
+  // EXPANDED, medium-weight grotesque pulled from Google Fonts (wdth 125 / wght 500). We match
+  // that with `500 expanded` + 0.02em tracking. An explicit family is used as given, with a
+  // `system-ui, sans-serif` fallback so an unloaded family never resolves to the canvas default
+  // serif (Times New Roman — issue 327). Quote the family for safety.
   const dpr = 2; // render the canvas at 2x for crisper text
-  const pxFont = `${size * dpr}px ${fontFamily}`;
+  const usesDefaultFont = !style?.font;
+  const fontFamily = usesDefaultFont
+    ? `"Zalando Sans", system-ui, sans-serif`
+    : `"${style.font}", system-ui, sans-serif`;
+  const weightStretch = usesDefaultFont ? "500 expanded " : "";
+  const trackingPx = usesDefaultFont ? 0.02 * size * dpr : 0; // 0.02em → device px
+
+  const pxFont = `${weightStretch}${size * dpr}px ${fontFamily}`;
 
   // Measure the typeset text width (px at 1× = scene points), then the plate world width is
   // text width + 1.5em pad on EACH side (issue 311). Heights are exact: plate world height.
+  // letterSpacing must be set BEFORE measuring so the plate width accounts for the tracking.
   const measureCanvas = document.createElement("canvas");
   const mctx = measureCanvas.getContext("2d");
   mctx.font = pxFont;
+  if (trackingPx && "letterSpacing" in mctx) mctx.letterSpacing = `${trackingPx}px`;
   const textWWorld = mctx.measureText(text).width / dpr; // scene-point text width
   const worldWidth = textWWorld + 2.0 * CAPTION_PLATE_PAD_EM * size;
   const worldHeight = plateHeight;
@@ -96,8 +106,9 @@ export function makeCaptionSprite(text, style) {
     ctx.strokeRect(lwPx / 2, lwPx / 2, canvasW - lwPx, canvasH - lwPx);
   }
 
-  // Caption text, centered both ways, in the caption color.
+  // Caption text, centered both ways, in the caption color (same tracking as the measurement).
   ctx.font = pxFont;
+  if (trackingPx && "letterSpacing" in ctx) ctx.letterSpacing = `${trackingPx}px`;
   ctx.textAlign = "center";
   ctx.textBaseline = "middle";
   ctx.fillStyle = color;
@@ -351,30 +362,39 @@ export class Stage {
   }
 
   /**
-   * Ensure the caption fonts are loaded before the caption canvases are drawn (issue 320).
-   * Caption text is rasterized to a canvas at build time, so the font must be available
-   * first or it falls back to a system font. The default font "REM" is pulled from Google
-   * Fonts (injected once); any other family is left to the host page. Best-effort: in
-   * non-browser/offline contexts it resolves without blocking (captions fall back).
+   * Ensure the default caption font is loaded before the caption canvases are drawn (issue 328).
+   * Caption text is rasterized to a canvas at build time, so the font must be available first or
+   * it falls back to a system font. The default font is "Zalando Sans" (the bundled vexy-stax
+   * face) pulled from Google Fonts at wdth 125 / wght 500; explicit families are left to the host
+   * page. Best-effort: in non-browser/offline contexts it resolves without blocking.
    */
   async _ensureCaptionFonts() {
     if (typeof document === "undefined" || !document.fonts) return;
-    const fonts = new Set();
-    if (this.scene.caption_defaults?.font) fonts.add(this.scene.caption_defaults.font);
-    for (const s of this.scene.slides) {
-      if (s.caption?.style?.font) fonts.add(s.caption.style.font);
-    }
-    if (fonts.size === 0) return;
-    // Load REM (the documented default caption font) from Google Fonts when used. We must wait
-    // for the stylesheet to actually PARSE before calling document.fonts.load — otherwise the
-    // REM @font-face rules don't exist yet and load() resolves against the system fallback,
-    // leaving captions in a serif default (issue 327). So await the <link> onload first.
-    const usesRem = [...fonts].some((f) => String(f).trim().toLowerCase() === "rem");
-    if (usesRem && typeof document.getElementById === "function" && !document.getElementById("vexy-rem-font")) {
+    // Does any caption fall back to the DEFAULT font (no explicit family anywhere)?
+    const defFont = this.scene.caption_defaults?.font;
+    const needsDefault = !defFont && this.scene.slides.some((s) => s.caption && !s.caption.style?.font);
+    if (!needsDefault) return;
+    // Pull "Zalando Sans" (wdth 125 / wght 500) from Google Fonts. We must await the stylesheet
+    // PARSE before document.fonts.load — otherwise the @font-face rules don't exist yet and
+    // load() resolves against the system fallback, leaving captions in a serif default (327).
+    if (typeof document.getElementById === "function" && !document.getElementById("vexy-zalando-font")) {
+      for (const [id, href, cors] of [
+        ["vexy-gf-preconnect", "https://fonts.googleapis.com", false],
+        ["vexy-gf-preconnect-static", "https://fonts.gstatic.com", true],
+      ]) {
+        if (!document.getElementById(id)) {
+          const pre = document.createElement("link");
+          pre.id = id;
+          pre.rel = "preconnect";
+          pre.href = href;
+          if (cors) pre.crossOrigin = "anonymous";
+          document.head?.appendChild(pre);
+        }
+      }
       const link = document.createElement("link");
-      link.id = "vexy-rem-font";
+      link.id = "vexy-zalando-font";
       link.rel = "stylesheet";
-      link.href = "https://fonts.googleapis.com/css2?family=REM:wght@400;500;700&display=swap";
+      link.href = "https://fonts.googleapis.com/css2?family=Zalando+Sans:wdth,wght@125,500&display=swap";
       const linkLoaded = new Promise((resolve) => {
         link.onload = resolve;
         link.onerror = resolve; // offline → fall through to system fallback
@@ -383,7 +403,8 @@ export class Stage {
       await linkLoaded;
     }
     try {
-      await Promise.all([...fonts].map((f) => document.fonts.load(`32px "${f}"`)));
+      // Match the canvas font descriptor (500 / expanded == wdth 125) so the right face preloads.
+      await document.fonts.load('500 expanded 32px "Zalando Sans"');
       if (document.fonts.ready) await document.fonts.ready;
     } catch {
       /* offline / unsupported → captions fall back to a system font */
@@ -393,6 +414,7 @@ export class Stage {
   /** Build a caption sprite under each plate that declares one (best-effort). */
   _buildCaptions() {
     if (typeof document === "undefined") return; // no canvas → skip captions
+    if (!this.scene.captions) return; // issue 332: global captions toggle off
     const defaults = this.scene.caption_defaults ?? null;
     // Caption-plate layout (issue 311): the caption is a small white opaque bordered PLATE.
     // 1em == captionSize, plate height == captionPlateHeight, border == the slide-plate edge
@@ -501,6 +523,9 @@ export class Stage {
     const bottomY = -tallest / 2;
     const floorY = bottomY;
     const reflectivity = this.scene.floor.reflectivity;
+    // Issue 332: lift every slide plate (+ border/reflection) by one caption-plate height so
+    // it sits ON TOP of its on-floor caption plate (0 when captions are off → on the floor).
+    const lift = slideLift(this.scene);
 
     // Cumulative Z: index 0 farthest (most negative), last at 0.
     // stack_depth = sum(gaps[1:]); place slide i at z = -(stack_depth - cumGapTo(i)).
@@ -511,7 +536,7 @@ export class Stage {
     this.plates.forEach((plate, i) => {
       if (i > 0) cum += gaps[i];
       const z = -(totalDepth - cum);
-      const y = bottomY + plate.height / 2;
+      const y = bottomY + lift + plate.height / 2;
       const op = opacities[i];
       plate.mesh.position.set(0, y, z);
       plate.mesh.material.opacity = op;
@@ -535,12 +560,13 @@ export class Stage {
   }
 
   /**
-   * Position each caption PLATE (issue 311) so its RIGHT edge is at captionAnchorX (2em left
-   * of the plates) and its VERTICAL CENTER is at captionPlateCenterY (the plate sits on the
-   * virtual ground), at the slide plate's current Z (captions recede with their plate). The
-   * caption mesh is centered geometry of width `worldWidth`, so the mesh CENTER X is
-   * anchorX − worldWidth/2. The whole plate (fill + border + text) fades with the per-frame
-   * opacity. opacities[plateIndex] == 0 → fully invisible.
+   * Position each caption PLATE (issue 311; relayout issue 332) so its LEFT edge is at
+   * captionAnchorX (the slide LEFT edge) and its VERTICAL CENTER is at captionPlateCenterY
+   * (the plate sits on the floor, the slide stacked on top of it), at the slide plate's
+   * current Z (captions recede with their plate). The caption mesh is centered geometry of
+   * width `worldWidth`, so the mesh CENTER X is anchorX + worldWidth/2. The whole plate
+   * (fill + border + text) fades with the per-frame opacity. opacities[plateIndex] == 0 →
+   * fully invisible.
    * @param {number[]} opacities  per-slide opacity list (1:1 with this.plates)
    */
   _placeCaptions(opacities) {
@@ -549,10 +575,10 @@ export class Stage {
     const centerY = captionPlateCenterY(this.scene);
     this.captions.forEach(({ sprite, material, plateIndex, worldWidth }) => {
       const plate = this.plates[plateIndex];
-      // Right edge at anchorX → mesh center at anchorX − width/2; vertical center at centerY;
-      // plate Z (captions recede with their plate in expanded view).
+      // Issue 332: LEFT edge at anchorX (the slide left edge) → mesh center at anchorX + w/2;
+      // vertical center at centerY (on the floor); plate Z (captions recede with their plate).
       const w = worldWidth ?? sprite.scale?.x ?? 0;
-      sprite.position.set(anchorX - w / 2, centerY, plate.mesh.position.z);
+      sprite.position.set(anchorX + w / 2, centerY, plate.mesh.position.z);
       const op = opacities[plateIndex] ?? 0;
       material.opacity = op;
       sprite.visible = op > 0.001;