npm - vexy-stax-js - Versions diffs - 3.0.1 → 3.0.10 - Mend

vexy-stax-js 3.0.1 → 3.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/CHANGELOG.md +91 -0
package/package.json +4 -2
package/schema/vexy-stax-scene.schema.json +1 -0
package/src/export.js +120 -52
package/src/geometry.js +47 -15
package/src/scene.js +28 -0
package/src/stage.js +63 -37

package/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,97 @@
 All notable changes to this project are documented here.
+## [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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "vexy-stax-js",
-  "version": "3.0.1",
+  "version": "3.0.10",
   "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 CHANGED Viewed

@@ -69,6 +69,7 @@
     },
     "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." },
     "caption_defaults": { "$ref": "#/$defs/captionStyle" },
     "caption_fade": {
       "type": "object",

package/src/export.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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,14 @@ 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 332: the frontmost COMPOSITE the head-on camera frames is the slide plate plus
+  // (captions on) its on-floor caption plate stacked below it: full width W, height H + lift
+  // (lift == one caption-plate height), vertically centered at Y = lift/2. Aim at that
+  // composite center so neither the slide nor the caption row crops. Mirrors geometry.py.
+  const lift = slideLift(scene);
+  const compositeH = scene.size.height + lift;
+  const target = [0.0, lift / 2.0, -depth / 2.0];
   let isPercent = false;
   let pctVal = 90.0;
   if (typeof cam.distance === "string") {
@@ -318,24 +348,24 @@ 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): fit the frontmost COMPOSITE
+    // (width W, height H + lift) 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);
     const frac = pctVal / 100.0;
     const dW = scene.size.width / (2.0 * Math.tan(hfov / 2.0) * frac);
-    const dH = scene.size.height / (2.0 * Math.tan(vfov / 2.0) * frac);
+    const dH = compositeH / (2.0 * Math.tan(vfov / 2.0) * frac);
     const distToZ0 = Math.max(dW, dH);
     distance = distToZ0 + depth / 2.0;
   } 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 +410,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/scene.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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;