vexy-stax-js 3.0.10 → 3.1.1

package/CHANGELOG.md

@@ -4,6 +4,28 @@
 
 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

package/package.json

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

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

@@ -70,6 +70,19 @@
     "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/geometry.js

@@ -330,13 +330,14 @@ export function expandedCamera(scene, viewportAspect) {
 export function compactCamera(scene, viewportAspect) {
   const cam = scene.camera;
   const depth = stackDepth(scene, "compact");
-  // 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.
+  // 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 compositeH = scene.size.height + lift;
-  const target = [0.0, lift / 2.0, -depth / 2.0];
+  const target = [0.0, lift, -depth / 2.0];
 
   let isPercent = false;
   let pctVal = 90.0;
@@ -351,15 +352,16 @@ export function compactCamera(scene, viewportAspect) {
 
   let distance;
   if (isPercent) {
-    // 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.
+    // 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);
     const frac = pctVal / 100.0;
     const dW = scene.size.width / (2.0 * Math.tan(hfov / 2.0) * frac);
-    const dH = compositeH / (2.0 * Math.tan(vfov / 2.0) * frac);
+    const dH = scene.size.height / (2.0 * Math.tan(vfov / 2.0) * frac);
     const distToZ0 = Math.max(dW, dH);
     distance = distToZ0 + depth / 2.0;
   } else {

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);
       },
     });
   }