vexy-stax-js 3.1.2 → 3.1.7

package/CHANGELOG.md

@@ -4,6 +4,96 @@
 
 All notable changes to this project are documented here.
 
+## [3.1.4] — issue 701: inline scene + aspect
+
+### Added
+
+- **Inline scene via a `<script type="application/json">` child** (701): drop the entire scene JSON
+  *inside* the `<vexy-stax>` element — no external `scene` URL and no giant `config` attribute to
+  escape. Precedence: `config` object → inline `<script>` scene → `scene` URL → `slides`. Inline
+  slide `src` paths resolve against the host page, so use absolute URLs for off-page images. This is
+  the clean way to "specify the full scene right where you load the component" (also keeps working
+  with the existing `el.scene = {…}` / `config` object/JSON-string paths).
+- **`aspect` attribute / `createStax({ aspect })` option** (701): shapes the embed box via CSS
+  `aspect-ratio` so a deck is easy to make short and wide. `aspect="3"` (or `"3/1"`, `"3:1"`,
+  `"16:9"`) → a 3:1 box; `:` and `x` are normalized to `/`. The camera reframes the deck to the
+  resolved box (the existing ResizeObserver path). `width`/`height` still set explicit CSS sizes;
+  the scene's own `size` controls the internal plate aspect.
+
+## [3.0.17] — control-button + docs-scene follow-ups
+
+### Fixed
+
+- **Control-button label was stale during scrollspy** (343/344): the single toggle button only
+  refreshed on a click-toggle's `transitionend`, so while the deck morphed by SCROLL (`seek`) the
+  label lagged (said "Explain" while already expanded). `VexyStax` now emits a **`viewchange`**
+  CustomEvent whenever `_currentView` flips — from `seek` (scroll), `setView`, or a transition — and
+  the buttons listen to it, so the label always reflects the current view (and thus the action a
+  click will perform). Verified: `seek(0.7)` → "Preview", `seek(0.2)` → "Explain".
+- **Demo scene edits were silently overwritten** (build): `docs/airbl-demo.scene.json` and
+  `docs/airbl-scrollable.scene.json` were REGENERATED from the shared py testdata on every
+  `build:docs`, clobbering hand edits. The demos now have **editable source files** under
+  `vexy-stax-js/demo-scenes/` that the build merely COPIES into `docs/` (seeding them once from the
+  testdata + default floor if absent). Edit `demo-scenes/airbl-scrollable.scene.json` to customize
+  the scrollable demo — it persists. (The slide PNGs are still copied from the py testdata.)
+
+## [3.0.16] — issue 344
+
+### Fixed
+
+- **Back slides' caption plates painted over front slides** (344): in the expanded view a caption
+  attached to a slide behind the front (e.g. "Halftone fill: Dots") drew ON TOP OF the frontmost
+  slide. The three.js plates use `depthWrite:false` and the captions `depthTest:false`, so DRAW
+  ORDER — not depth — decides compositing, but every plate shared `renderOrder 0` and every caption
+  `renderOrder 2`, so all captions painted over all plates. Each slide now owns a **per-slide
+  render-order block** `i*4` (index 0 = backmost): plate `i*4`, border `i*4+1`, caption `i*4+2`. A
+  front slide's plate (`(i+1)*4`) therefore paints AFTER — and its opaque pixels cover — a back
+  slide's caption (`i*4+2`), while transparent areas still let it show through. Mirrors the pygfx
+  engine's issue-327 ordering. (The pygfx + Blender engines occlude correctly via the depth buffer /
+  real 3D depth and were unaffected.) Verified: the frontmost slide is no longer overdrawn by the
+  caption of the slide behind it.
+
+## [3.0.15] — issue 343
+
+### Added
+
+- **Built-in control buttons** (343): an opt-in overlay over the deck that switches views via the
+  smooth click-toggle. Two layouts: `buttons="toggle"` — ONE relabeling button ("Explain" while
+  compact → expand, then "Preview" while expanded → collapse); `buttons="pair"` — two side-by-side
+  buttons ("Explain" / "Preview"). Default placement is just above the bottom, horizontally
+  centered; default styling is black text on a barely-there (5 %) blurred black pill. Fully
+  customizable: labels via `explain-label`/`preview-label`, placement via `buttons-position`
+  (`bottom`|`top`|`bottom-left`|…|`center`), and every visual via `--vexy-btn-*` CSS custom
+  properties (`--vexy-btn-color`/`-bg`/`-blur`/`-radius`/`-pad`/…). Exposed three ways:
+  the `<vexy-stax buttons="…">` attributes, `createStax(el, { buttons, explainLabel, previewLabel,
+  buttonsPosition, buttonStyle })`, and the `VexyStax.controls(opts)` method. New `src/controls.js`
+  (`attachControls`). Showcased on the scrollable demo + demo-component. Verified headless: the
+  toggle relabels Explain⇄Preview across clicks, the pair renders with custom labels, no errors.
+
+## [3.0.14] — issue 342 (scrollspy polish)
+
+### Fixed
+
+- **Click-toggle on the scrollspy demo snapped back to expanded** (342): after a click collapsed
+  the deck, the next scroll event re-seeked it to the scroll-position-derived value (expanded). The
+  `scrollable.html` scroll handler now uses a **manual-hold** model — a click-toggled state is held
+  until the scroll position naturally reaches the matching endpoint, then control hands back to
+  scroll seamlessly. The deck no longer snaps back.
+- **Post-toggle compact view was framed "too close" (plates cropped)** (342): `playTransition` ran
+  `frameStateAt(scene, t)` **without** the live container aspect, so animated transition frames fell
+  back to the scene aspect and the compact endpoint was framed closer than `setView`/`seek` (which
+  pass the live aspect). `transition()` now threads `this.stage.camera.aspect` through to
+  `playTransition` → `frameStateAt`. Verified: the post-toggle compact camera matches the initial
+  compact camera exactly on a wide container.
+- **Click-toggle transition was too slow** (342): a toggle reused the scene's `transition.duration`
+  (up to 3 s for scroll-story scenes). `toggleView()` now plays a snappy fixed **0.7 s** leg via a
+  new `opts.duration` override on `transition()`/`playTransition()`, independent of the scene timing.
+
+### Changed
+
+- **Scrollable demo stage is `100vw × 60vh`** (user request): shorter and wider than the previous
+  2:1 box. The camera fits the deck to this live aspect (see the aspect fix above).
+
 ## [3.0.13] — issues 341, 342
 
 ### Added

package/README.md

@@ -44,13 +44,33 @@ Three ways to drop a deck on a page, easiest first (issues 341 / 342).
 
 <!-- …or point at a full scene JSON (with captions, camera, transition, …): -->
 <vexy-stax scene="scene.json" view="expanded"></vexy-stax>
+
+<!-- …or drop the WHOLE scene inline, right where you load the component (issue 701) —
+     a `<script type="application/json">` child, no external URL: -->
+<vexy-stax view="compact" mode="playable" aspect="3">
+  <script type="application/json">
+  { "version": 1, "transition": { "kind": "expand_collapse" },
+    "slides": [ { "src": "https://example.com/layer-0.png" },
+                { "src": "https://example.com/layer-1.png" } ] }
+  </script>
+</vexy-stax>
 ```
 
 **Click-to-toggle is on by default** (issue 342): clicking anywhere inside a `<vexy-stax>` fluently
 toggles compact↔expanded. Opt out with `click-toggle="false"`.
 
-**Scene-in-init** (issue 342): assign an inline scene **object** without a URL —
-`el.scene = { version: 1, slides: [{ src: "a.png" }, …] }` (or the `config` property).
+**Scene-in-init** (issue 342/701): supply an inline scene **without a URL** three ways — assign a
+JS object (`el.scene = { version: 1, slides: [{ src: "a.png" }, …] }` or the `config` property), a
+JSON-string `config` attribute, or a child **`<script type="application/json">`** holding the whole
+scene (shown above; the no-escaping way to "specify the full scene right where you load the
+component"). Inline slide `src` paths resolve against the host page, so use absolute URLs when the
+images live elsewhere.
+
+**Aspect / size** (issue 701): the `aspect` attribute shapes the box via CSS `aspect-ratio` so a
+deck is easy to make short and wide — `aspect="3"` (or `"3/1"`, `"3:1"`, `"16:9"`) gives a 3:1 box;
+the camera reframes the deck to fit. `width`/`height` still set an explicit CSS size, and the
+scene's own `size` controls the internal plate aspect. `createStax(el, { aspect: "3" })` is the ESM
+equivalent.
 
 ### ES Module — `createStax`
 
@@ -75,7 +95,7 @@ const low  = new VexyStax(container, scene); // the low-level path is still avai
 ```
 
 `createStax(elOrSelector, opts)` — `opts` accepts `{ slides | scene, view, mode, trigger, width,
-height, clickToggle, baseUrl, …sceneOverrides }`. Any remaining key (`size`, `camera`, `gap`,
+height, aspect, clickToggle, baseUrl, …sceneOverrides }`. Any remaining key (`size`, `camera`, `gap`,
 `transition`, `background`, `captions`, `floor`, `edge`, …) is forwarded to `makeScene`.
 
 ### Global script — `window.VexyStax`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vexy-stax-js",
-  "version": "3.1.2",
+  "version": "3.1.7",
   "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/src/controls.js

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: Apache-2.0
+// this_file: vexy-stax-js/src/controls.js
+//
+// Built-in control buttons (issue 343): a small overlay over the deck that switches between the
+// compact ("Preview") and expanded ("Explain") views via the smooth click-toggle morph. Two layouts:
+//   - "toggle" (default): ONE relabeling button — "Explain" while compact (click → expand), then
+//     "Preview" while expanded (click → collapse back to compact).
+//   - "pair": TWO buttons side-by-side — "Explain" (→ expand) and "Preview" (→ compact).
+// Default placement is just above the bottom, horizontally centered. Default styling is black text
+// on a barely-there (5%) blurred black pill. Everything is themeable via CSS custom properties
+// (`--vexy-btn-*` on the element) and the labels/position/type are options.
+
+// Simple position presets (the `position` option). All are relative to the component box.
+const POSITIONS = {
+  bottom: "left:50%;bottom:6%;transform:translateX(-50%);",
+  top: "left:50%;top:6%;transform:translateX(-50%);",
+  "bottom-left": "left:5%;bottom:6%;",
+  "bottom-right": "right:5%;bottom:6%;",
+  "top-left": "left:5%;top:6%;",
+  "top-right": "right:5%;top:6%;",
+  center: "left:50%;top:50%;transform:translate(-50%,-50%);",
+};
+
+let _styleInjected = false;
+
+/** Safari does not apply backdrop-filter over a WebGL canvas; use a solid pill there instead. */
+function isSafari(doc) {
+  const ua = doc.defaultView?.navigator?.userAgent ?? "";
+  return /Safari/i.test(ua) && !/Chrome|Chromium|CriOS|FxiOS|EdgiOS|Edg\//i.test(ua);
+}
+
+function injectStyle(doc) {
+  if (_styleInjected || !doc?.head) return;
+  _styleInjected = true;
+  const s = doc.createElement("style");
+  // All visual knobs are CSS custom properties so a host overrides them with one rule, e.g.
+  //   vexy-stax { --vexy-btn-color:#fff; --vexy-btn-bg:rgba(0,0,0,.4); --vexy-btn-blur:14px; }
+  // Safari: backdrop-filter is ignored over canvas — use --vexy-btn-bg-solid instead (issue 343).
+  const safariBtn = isSafari(doc)
+    ? `
+.vexy-stax-controls button{
+  -webkit-backdrop-filter:none;backdrop-filter:none;
+  background:var(--vexy-btn-bg-solid,rgba(255,255,255,0.92));
+}
+.vexy-stax-controls button:hover{background:var(--vexy-btn-bg-solid-hover,rgba(255,255,255,0.97))}`
+    : "";
+  s.textContent = `
+.vexy-stax-controls{position:absolute;z-index:5;display:flex;gap:8px;pointer-events:none}
+.vexy-stax-controls button{
+  pointer-events:auto;cursor:pointer;font:inherit;
+  font-size:var(--vexy-btn-font,14px);font-weight:var(--vexy-btn-weight,600);letter-spacing:.01em;line-height:1;
+  color:var(--vexy-btn-color,#000);
+  background:var(--vexy-btn-bg,rgba(0,0,0,0.05));
+  -webkit-backdrop-filter:blur(var(--vexy-btn-blur,10px));backdrop-filter:blur(var(--vexy-btn-blur,10px));
+  border:var(--vexy-btn-border,1px solid rgba(0,0,0,0.08));
+  border-radius:var(--vexy-btn-radius,999px);
+  padding:var(--vexy-btn-pad,9px 18px);
+  box-shadow:var(--vexy-btn-shadow,0 2px 10px rgba(0,0,0,0.06));
+  transition:background .15s,transform .12s;
+}
+.vexy-stax-controls button:hover{background:var(--vexy-btn-bg-hover,rgba(0,0,0,0.10))}
+.vexy-stax-controls button:active{transform:translateY(1px)}${safariBtn}
+`;
+  doc.head.appendChild(s);
+}
+
+/**
+ * Attach control buttons over the deck (issue 343).
+ * @param {object} stax the VexyStax instance (uses `_currentView` + `toggleView()`/`setView`)
+ * @param {HTMLElement} container the element the canvas lives in (the overlay is appended here)
+ * @param {object} [opts]
+ * @param {"toggle"|"pair"} [opts.type="toggle"] single relabeling button, or a side-by-side pair
+ * @param {string} [opts.explainLabel="Explain"] label for the compact→expand action
+ * @param {string} [opts.previewLabel="Preview"] label for the expand→compact action
+ * @param {string} [opts.position="bottom"] one of POSITIONS (bottom|top|bottom-left|…|center)
+ * @param {string} [opts.style] extra inline CSS appended to the overlay wrapper (full custom position)
+ * @returns {{el:HTMLElement, update:()=>void, destroy:()=>void}|null}
+ */
+export function attachControls(stax, container, opts = {}) {
+  if (!container?.ownerDocument || !container.appendChild) return null;
+  const doc = container.ownerDocument;
+  injectStyle(doc);
+
+  const type = opts.type === "pair" ? "pair" : "toggle";
+  const explainLabel = opts.explainLabel ?? "Explain"; // compact → expand
+  const previewLabel = opts.previewLabel ?? "Preview"; // expanded → compact
+  const posKey = opts.position && POSITIONS[opts.position] ? opts.position : "bottom";
+
+  // The overlay is absolutely positioned, so the container must establish a positioning context.
+  if (container.style && typeof getComputedStyle === "function" && getComputedStyle(container).position === "static") {
+    container.style.position = "relative";
+  }
+
+  const wrap = doc.createElement("div");
+  wrap.className = "vexy-stax-controls";
+  wrap.setAttribute("style", POSITIONS[posKey] + (opts.style ?? ""));
+
+  const isCompact = () => stax._currentView === "compact";
+  let update;
+
+  if (type === "pair") {
+    const bExplain = doc.createElement("button");
+    bExplain.type = "button";
+    bExplain.textContent = explainLabel;
+    bExplain.addEventListener("click", () => { if (isCompact()) stax.toggleView(); });
+    const bPreview = doc.createElement("button");
+    bPreview.type = "button";
+    bPreview.textContent = previewLabel;
+    bPreview.addEventListener("click", () => { if (!isCompact()) stax.toggleView(); });
+    wrap.append(bExplain, bPreview);
+    update = () => {}; // both labels are always shown
+  } else {
+    const b = doc.createElement("button");
+    b.type = "button";
+    b.addEventListener("click", () => stax.toggleView());
+    wrap.append(b);
+    update = () => { b.textContent = isCompact() ? explainLabel : previewLabel; };
+    update();
+  }
+
+  container.appendChild(wrap);
+
+  // Keep the single-button label in sync with the CURRENT view however it changes — a click-toggle,
+  // a setView, OR a scroll-driven seek (issue 344 follow-up). VexyStax emits a "viewchange"
+  // CustomEvent on the container whenever `_currentView` flips, including mid-scrollspy, so the
+  // label is never stale (a click during a scroll always shows the action it will perform).
+  const onChange = () => update();
+  container.addEventListener("viewchange", onChange);
+
+  return {
+    el: wrap,
+    update,
+    destroy() {
+      container.removeEventListener("viewchange", onChange);
+      wrap.remove();
+    },
+  };
+}

package/src/element.js

@@ -3,9 +3,12 @@
 //
 // <vexy-stax> custom element (SPEC.md §6.2). Attributes: scene (URL), slides
 // (space/newline-separated image URLs — issue 341), captions (bool), view,
-// mode (static|playable|scrollspy), width, height. Property `config` accepts an
-// inline scene object (overrides `scene`/`slides`). Events: ready, transitionstart,
-// transitionend. Mounts a VexyStax in light DOM. Auto-registers on import.
+// mode (static|playable|scrollspy), width, height, aspect (CSS aspect-ratio,
+// e.g. "3", "3/1", "3:1" — issue 701). Property `config` accepts an inline scene
+// object (overrides `scene`/`slides`); an inline `<script type="application/json">`
+// child also supplies the scene (issue 701 — "specify the full scene right where
+// you load the component"). Events: ready, transitionstart, transitionend. Mounts
+// a VexyStax in light DOM. Auto-registers on import.
 
 import { VexyStax, loadScene, makeScene } from "./index.js";
 
@@ -19,7 +22,11 @@ export class VexyStaxElement extends HTMLElement {
   static get observedAttributes() {
     // `slides` + `captions` are the issue-341 easy path (a scene from a bare URL list);
     // `click-toggle` is the issue-342 opt-out for the default click-to-toggle behavior.
-    return ["scene", "slides", "captions", "view", "mode", "trigger", "width", "height", "click-toggle"];
+    // `buttons` + `explain-label`/`preview-label`/`buttons-position` are the issue-343 control buttons.
+    return [
+      "scene", "slides", "captions", "view", "mode", "trigger", "width", "height", "aspect",
+      "click-toggle", "buttons", "explain-label", "preview-label", "buttons-position",
+    ];
   }
 
   constructor() {
@@ -80,7 +87,7 @@ export class VexyStaxElement extends HTMLElement {
 
   attributeChangedCallback(name) {
     if (!this.isConnected) return;
-    if (name === "width" || name === "height") {
+    if (name === "width" || name === "height" || name === "aspect") {
       this._applySize();
       this._stax?.resize();
       return;
@@ -104,6 +111,36 @@ export class VexyStaxElement extends HTMLElement {
     const h = this.getAttribute("height");
     if (w) this.style.width = /^\d+$/.test(w) ? `${w}px` : w;
     if (h) this.style.height = /^\d+$/.test(h) ? `${h}px` : h;
+    // Issue 701: `aspect` sets the CSS aspect-ratio so the embed box is easy to shape
+    // (e.g. aspect="3" / "3/1" / "3:1" → a short, wide 3:1 deck). Accepts the CSS
+    // `<width>/<height>` or bare-ratio forms; ":" and "x" are normalized to "/". With
+    // only `aspect` (no height) the element's height follows from its width, and the
+    // ResizeObserver reframes the camera to the resolved box.
+    const aspect = this.getAttribute("aspect");
+    if (aspect && aspect.trim()) {
+      this.style.aspectRatio = aspect.trim().replace(/[:x]/i, " / ");
+    }
+  }
+
+  /**
+   * Issue 701: an inline scene declared as a child `<script type="application/json">` (or
+   * `application/vexy-scene+json`). This is the no-escaping way to "specify the full scene
+   * right where you load the component" — drop the whole scene JSON inside the element instead
+   * of pointing `scene` at a URL. Returns the parsed object (later normalized by loadScene), or
+   * null when there is no such child. A `<script>` child is never rendered, so it is invisible.
+   */
+  _inlineScene() {
+    if (typeof this.querySelector !== "function") return null;
+    const tag = this.querySelector(
+      'script[type="application/json"], script[type="application/vexy-scene+json"]'
+    );
+    const text = tag?.textContent?.trim();
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch (err) {
+      throw new Error(`<vexy-stax>: inline <script> scene is not valid JSON (${err.message})`);
+    }
   }
 
   async _mount() {
@@ -114,11 +151,12 @@ export class VexyStaxElement extends HTMLElement {
       this._stax = null;
 
       const baseUrl = typeof document !== "undefined" ? document.baseURI : undefined;
-      // Source precedence (issue 341): inline `config` object → `scene` URL → `slides` list.
-      // `slides` is the easy path: a space/newline-separated list of image URLs (local, data:,
-      // or remote http(s)) built into a scene via makeScene. `captions` (bool attr) toggles
-      // caption plates (default on; here off unless slides carry their own — empty by default).
-      const sceneSrc = this._config ?? this.getAttribute("scene");
+      // Source precedence (issue 341 + 701): inline `config` object → inline <script> scene →
+      // `scene` URL → `slides` list. `slides` is the easy path: a space/newline-separated list
+      // of image URLs (local, data:, or remote http(s)) built into a scene via makeScene.
+      // `captions` (bool attr) toggles caption plates (default on; here off unless slides carry
+      // their own — empty by default).
+      const sceneSrc = this._config ?? this._inlineScene() ?? this.getAttribute("scene");
       const slidesAttr = this.getAttribute("slides");
       let scene;
       if (sceneSrc) {
@@ -158,6 +196,19 @@ export class VexyStaxElement extends HTMLElement {
         this._stax?.enableClickToggle();
       }
 
+      // Issue 343: built-in control buttons. `buttons` = "toggle" (single relabeling button) or
+      // "pair" (two buttons); a bare `buttons` attribute defaults to "toggle". `explain-label`,
+      // `preview-label` and `buttons-position` customize text + placement (style via --vexy-btn-*).
+      const buttonsAttr = this.getAttribute("buttons");
+      if (buttonsAttr !== null && buttonsAttr !== "false") {
+        this._stax?.controls({
+          type: buttonsAttr === "pair" ? "pair" : "toggle",
+          explainLabel: this.getAttribute("explain-label") ?? undefined,
+          previewLabel: this.getAttribute("preview-label") ?? undefined,
+          position: this.getAttribute("buttons-position") ?? undefined,
+        });
+      }
+
       this.dispatchEvent(new CustomEvent("ready", { detail: { instance: this._stax } }));
     } catch (err) {
       this.dispatchEvent(new CustomEvent("error", { detail: { error: err } }));

package/src/geometry.js

@@ -122,9 +122,18 @@ export function captionBaselineY(scene) {
   return -(scene.size.height / 2.0) + CAPTION_BASELINE_EM * captionSize(scene);
 }
 
-/** Per-slide gap (points), falling back to camera.gap when unset (null). */
+/**
+ * Per-slide gap (points), falling back to camera.gap when unset (null).
+ * Resolves a gap of 0 to MIN_GAP.
+ */
 export function plateGaps(scene) {
-  return scene.slides.map((s) => (s.gap === null || s.gap === undefined ? scene.camera.gap : s.gap));
+  return scene.slides.map((s) => {
+    let g = (s.gap === null || s.gap === undefined ? scene.camera.gap : s.gap);
+    if (g === 0) {
+      g = MIN_GAP;
+    }
+    return g;
+  });
 }
 
 /**

package/src/index.js

@@ -11,6 +11,7 @@ import { loadScene, parseScene, makeScene, resolvedOpacity } from "./scene.js";
 import { frameStateAt, ease } from "./geometry.js";
 import { playTransition, transitionEndpoints, buildTimeline, morphAtProgress } from "./transition.js";
 import { attachScrollspy } from "./scrollspy.js";
+import { attachControls } from "./controls.js";
 import { canvasToPngBlob, recordVideo } from "./export.js";
 
 export {
@@ -57,6 +58,7 @@ export class VexyStax {
     this._currentView = scene.view === "compact" ? "compact" : "expanded";
     this._morphT = this._currentView === "compact" ? 0 : 1;
     this._clickToggle = null; // { handler } when wired (enableClickToggle)
+    this._controls = null; // { destroy } when wired (controls(), issue 343)
     this._toggling = false; // guard against overlapping toggle transitions
     this._ready = this.stage.init().then(() => {
       this.stage.render();
@@ -95,8 +97,8 @@ export class VexyStax {
     await this._ready;
     this.stage.setView(view);
     this.stage.render();
-    this._currentView = view === "compact" ? "compact" : "expanded";
-    this._morphT = this._currentView === "compact" ? 0 : 1;
+    this._morphT = view === "compact" ? 0 : 1;
+    this._setView_(view === "compact" ? "compact" : "expanded");
     return this;
   }
 
@@ -112,10 +114,19 @@ export class VexyStax {
     // Issue 342: remember the morph position so a click-toggle on a scroll-driven deck knows
     // whether it is currently nearer compact (→ expand) or expanded (→ collapse).
     this._morphT = tt;
-    this._currentView = tt >= 0.5 ? "expanded" : "compact";
+    // Issue 344 follow-up: emit a viewchange when the scroll crosses the compact/expanded midpoint
+    // so the control-button label (and any host UI) stays in sync during a scroll-driven morph.
+    this._setView_(tt >= 0.5 ? "expanded" : "compact");
     return this;
   }
 
+  /** Set `_currentView` and emit a "viewchange" CustomEvent on the container when it changes (343/344). */
+  _setView_(view) {
+    if (view === this._currentView) return;
+    this._currentView = view;
+    this.container?.dispatchEvent?.(new CustomEvent("viewchange", { detail: { view } }));
+  }
+
   /** Resize the renderer/camera to the container (or explicit size). */
   resize(width, height) {
     const w = width ?? this.container.clientWidth;
@@ -186,7 +197,10 @@ export class VexyStax {
       const t = this._morphFromGaps(state.gaps);
       this.stage.applyFrameState(state, t);
       this.stage.render();
-    }, { kind: resolvedKind, onProgress: opts.onProgress });
+      // Pass the LIVE container aspect so the animated frames match setView()/seek() framing
+      // (issue 342: otherwise the compact endpoint is framed too close on a wide container).
+      // `opts.duration` lets a click-toggle play a snappy leg instead of the full scene timing.
+    }, { kind: resolvedKind, onProgress: opts.onProgress, aspect: this.stage.camera.aspect, duration: opts.duration });
 
     this._cancelTransition = controller.cancel;
     this.container.dispatchEvent?.(new CustomEvent("transitionstart", { detail: { kind: resolvedKind } }));
@@ -195,7 +209,7 @@ export class VexyStax {
       // Settle the tracked view to the transition's end endpoint (issue 342).
       const { endMorph } = transitionEndpoints(resolvedKind);
       this._morphT = endMorph;
-      this._currentView = endMorph >= 0.5 ? "expanded" : "compact";
+      this._setView_(endMorph >= 0.5 ? "expanded" : "compact");
       this.container.dispatchEvent?.(new CustomEvent("transitionend", { detail: { kind: resolvedKind } }));
     } finally {
       this._cancelTransition = null;
@@ -217,11 +231,13 @@ export class VexyStax {
     this._toggling = true;
     try {
       // The scene may have no `transition` section (e.g. a slides-only deck) — supply timing so
-      // toggle still animates. transition() reads scene.transition for timing; ensure one exists.
+      // toggle still animates. transition() reads scene.transition for the easing; ensure one exists.
       if (!this.scene.transition) {
-        this.scene.transition = { kind, duration: 0.9, wait: 0, fps: 30, easing: "easeInOutCubic" };
+        this.scene.transition = { kind, duration: 0.7, wait: 0, fps: 30, easing: "easeInOutCubic" };
       }
-      await this.transition(kind);
+      // Issue 342: a click-toggle plays a SNAPPY leg (0.7 s) regardless of the scene's
+      // transition.duration (which may be a long 3 s scroll-story ramp) — overriding it here.
+      await this.transition(kind, { duration: 0.7 });
     } finally {
       this._toggling = false;
     }
@@ -249,6 +265,19 @@ export class VexyStax {
     return this;
   }
 
+  /**
+   * Add built-in control buttons over the deck (issue 343): a single relabeling toggle
+   * ("Explain" → expand, "Preview" → compact) or a side-by-side pair. Frosted, bottom-centered by
+   * default; themeable via `--vexy-btn-*` CSS custom properties on the element. Replaces any prior
+   * controls. Pass `false` to remove them. Options: `{type:"toggle"|"pair", explainLabel,
+   * previewLabel, position, style}`.
+   */
+  controls(opts = {}) {
+    this._controls?.destroy();
+    this._controls = opts === false ? null : attachControls(this, this.container, opts);
+    return this;
+  }
+
   /** Remove the click-to-toggle handler (issue 342 opt-out). */
   disableClickToggle() {
     if (this._clickToggle) {
@@ -268,11 +297,26 @@ export class VexyStax {
   }
 
   /**
-   * Record the transition to a video Blob (WebCodecs preferred, MediaRecorder
-   * fallback). Plays the full transition while capturing the canvas.
+   * Record the transition to a video Blob.
+   *
+   * **Encoding path selection** (export.js `recordVideo`):
+   * 1. **PRIMARY — WebCodecs + mp4-muxer** (issue 331): uses `VideoEncoder` to
+   *    encode each rendered frame directly into H.264/mp4 (preferred) or VP9/webm.
+   *    Produces a fully seekable container with correct duration and per-stream
+   *    frame-count metadata. Available in Chrome 94+, Edge 94+, and recent Safari.
+   * 2. **FALLBACK — MediaRecorder** (`canvas.captureStream`): used when
+   *    `VideoEncoder` is unavailable (older browsers, some WebViews). Output is a
+   *    non-seekable webm stream; duration/frame metadata may be absent. The
+   *    recorded MIME type reflects the first supported codec from
+   *    `[vp9, vp8, webm, mp4]`.
+   *
+   * The clip is bookended by held stills: `scene.video.first_hold` copies of the
+   * start frame and `scene.video.last_hold` copies of the end frame (default 10
+   * each, matching the Python `frame_plan` holds).
+   *
    * @param {object} [opts]
    * @param {string} [opts.kind] override scene.transition.kind
-   * @returns {Promise<Blob>}
+   * @returns {Promise<Blob>} mp4 Blob (WebCodecs path) or webm Blob (MediaRecorder fallback)
    */
   async toVideo(opts = {}) {
     await this._ready;
@@ -375,6 +419,8 @@ export class VexyStax {
     this._cancelTransition?.();
     this._scrollspy?.disconnect?.();
     this.disableClickToggle();
+    this._controls?.destroy();
+    this._controls = null;
     this._ro?.disconnect?.();
     this._ro = null;
     this.stage?.dispose();
@@ -385,7 +431,7 @@ export class VexyStax {
 // MOUNT (view/mode/trigger/width/height) or WHICH source (slides/scene). Everything else in
 // `opts` is treated as a flat scene override and forwarded to makeScene (issue 341).
 const MOUNT_KEYS = new Set([
-  "slides", "scene", "view", "mode", "trigger", "width", "height", "baseUrl", "clickToggle",
+  "slides", "scene", "view", "mode", "trigger", "width", "height", "aspect", "baseUrl", "clickToggle",
 ]);
 
 /**
@@ -405,6 +451,7 @@ const MOUNT_KEYS = new Set([
  *       "playable" plays scene.transition once when ready; "scrollspy" attaches a scroll story.
  *   @param {Element|string} [opts.trigger]  scrollspy trigger (default: the element).
  *   @param {string} [opts.width] @param {string} [opts.height]  CSS size overrides on the element.
+ *   @param {string|number} [opts.aspect]  CSS aspect-ratio for the box (e.g. 3, "3/1", "3:1").
  *   @param {string} [opts.baseUrl]  base for resolving relative slide/scene URLs.
  *   ...any other key is a flat scene override forwarded to makeScene (size, camera, gap,
  *      transition, background, captions, floor, edge, caption_defaults, …).
@@ -419,6 +466,9 @@ export async function createStax(elOrSelector, opts = {}) {
   // Optional CSS size on the host element (parity with the <vexy-stax> width/height attrs).
   if (opts.width) el.style.width = /^\d+$/.test(String(opts.width)) ? `${opts.width}px` : opts.width;
   if (opts.height) el.style.height = /^\d+$/.test(String(opts.height)) ? `${opts.height}px` : opts.height;
+  // Issue 701: `aspect` shapes the box via CSS aspect-ratio (e.g. 3, "3/1", "3:1" → a 3:1 deck);
+  // ":"/"x" are normalized to "/". Parity with the <vexy-stax aspect="…"> attribute.
+  if (opts.aspect) el.style.aspectRatio = String(opts.aspect).trim().replace(/[:x]/i, " / ");
   if (typeof el.style === "object") {
     el.style.position = el.style.position || "relative";
     el.style.display = el.style.display || "block";
@@ -460,5 +510,19 @@ export async function createStax(elOrSelector, opts = {}) {
   // and layers on top of scrollspy (scroll drives the morph; a click still toggles). Opt out
   // with `clickToggle: false`.
   if (opts.clickToggle !== false) stax.enableClickToggle();
+
+  // Issue 343: built-in control buttons. `buttons: true` (or "toggle"/"pair") shows the overlay;
+  // `explainLabel`/`previewLabel`/`buttonsPosition`/`buttonStyle` customize it (or pass a full
+  // object as `buttons`).
+  if (opts.buttons) {
+    const c = typeof opts.buttons === "object" ? opts.buttons : { type: opts.buttons === "pair" ? "pair" : "toggle" };
+    stax.controls({
+      explainLabel: opts.explainLabel,
+      previewLabel: opts.previewLabel,
+      position: opts.buttonsPosition,
+      style: opts.buttonStyle,
+      ...c,
+    });
+  }
   return stax;
 }

package/src/stage.js

@@ -30,6 +30,11 @@ import {
 } from "./geometry.js";
 import { resolvedOpacity } from "./scene.js";
 
+// Per-slide render-order block size (issue 344): each slide owns [i*BLOCK, i*BLOCK+BLOCK) for its
+// plate (+0), border (+1) and caption (+2). Blocks grow with the slide index (front slides last),
+// so a front slide's plate occludes the captions of slides behind it. Reflections/floor sit below.
+const RENDER_BLOCK = 4;
+
 /**
  * Build a white OPAQUE bordered caption PLATE (issue 311). The whole caption is one
  * rectangle drawn on a single canvas texture: solid white fill, a stroked border of
@@ -277,11 +282,14 @@ export class Stage {
         opacity: 1,
       });
       const mesh = new THREE.Mesh(geometry, material);
-      // Explicit renderOrder so the transparent draw order is STABLE (reflection -2 <
-      // floor -1 < plate 0 < border 1 < caption 2). Equal renderOrders (plate==floor==0)
-      // let three.js distance-sort them, which flips frame-to-frame at the floor line and
-      // flickers at the bottom of each slide (issue 320 §9).
-      mesh.renderOrder = 0;
+      // PER-SLIDE render-order blocks (issue 344, mirrors pygfx issue 327): the plates and
+      // captions are alpha-blended with depthWrite/Test off, so DRAW ORDER — not depth — decides
+      // compositing. Give each slide a contiguous block `i*BLOCK` that grows with the slide index
+      // (index 0 = backmost, last = frontmost), so a FRONT slide's plate (i*BLOCK) paints AFTER —
+      // and its opaque pixels cover — a BACK slide's caption (`(i-1)*BLOCK + 2`). Within a block:
+      // plate(+0) < border(+1) < caption(+2). Reflections/floor stay below all of it (-2 / -1).
+      // Equal renderOrders would let three.js distance-sort and flip frame-to-frame (issue 320 §9).
+      mesh.renderOrder = i * RENDER_BLOCK;
       this.threeScene.add(mesh);
 
       // BLURRY mirror reflection (issue 303 §1): a mirror copy below the floor line
@@ -319,7 +327,7 @@ export class Stage {
       let border = null;
       if (this._edgeWidth > 0) {
         border = this._makeBorder(w, h, this._edgeWidth, this._edgeColor);
-        border.group.renderOrder = 1; // draw on top of the plate
+        border.group.renderOrder = i * RENDER_BLOCK + 1; // on top of this slide's plate (issue 344)
         this.threeScene.add(border.group);
       }
 
@@ -450,7 +458,10 @@ export class Stage {
         borderColor,
       };
       const { mesh, material, worldWidth } = makeCaptionSprite(caption.text, style);
-      mesh.renderOrder = 2; // draw the caption plate on top of the deck + borders
+      // Issue 344: this slide's caption draws on top of its OWN plate + border (i*BLOCK + 2), but
+      // BELOW the next (more frontward) slide's plate ((i+1)*BLOCK), so front slides occlude the
+      // captions of slides behind them.
+      mesh.renderOrder = i * RENDER_BLOCK + 2;
       this.threeScene.add(mesh);
       this.captions.push({ sprite: mesh, material, plateIndex: i, caption, worldWidth });
     });

package/src/transition.js

@@ -114,8 +114,12 @@ export function playTransition(scene, apply, opts = {}) {
   const tr = scene.transition;
   const kind = opts.kind ?? tr?.kind;
   if (!kind) throw new Error("playTransition: no transition kind (scene.transition is null and no kind given)");
-  const duration = tr?.duration ?? 3.0;
-  const wait = tr?.wait ?? 0.0;
+  // `opts.duration` overrides the scene timing (issue 342: a click-toggle plays a SNAPPY leg, not
+  // the scene's full transition.duration). `opts.aspect` is the LIVE container aspect — without it
+  // frameStateAt() falls back to the scene aspect and the compact endpoint is framed too close for
+  // a non-scene-aspect container (e.g. the wide scrollable demo).
+  const duration = opts.duration ?? tr?.duration ?? 3.0;
+  const wait = opts.duration != null ? 0.0 : tr?.wait ?? 0.0;
   const easing = tr?.easing ?? "easeInOutCubic";
   const timeline = buildTimeline(kind, { duration, wait });
 
@@ -147,7 +151,7 @@ export function playTransition(scene, apply, opts = {}) {
     const elapsed = now() - start;
     const p = totalMs > 0 ? Math.min(1, elapsed / totalMs) : 1;
     const t = morphAtProgress(timeline, p, (x) => ease(easing, x));
-    apply(frameStateAt(scene, t));
+    apply(frameStateAt(scene, t, opts.aspect));
     opts.onProgress?.(p);
     if (p >= 1) {
       resolveFn();