vexy-stax-js 3.1.1 → 3.1.7

package/CHANGELOG.md

@@ -4,6 +4,166 @@
 
 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
+
+- **`makeScene(slides, opts)`** (341): the "extremely easy to use" entry point — build a valid scene
+  from a bare list of slide image URLs (or `{src, caption, opacity, gap}` objects) plus a flat
+  options bag (`size`, `camera`, `gap`, `transition`, `view`, `background`, `captions`, `floor`,
+  `edge`, …). Defaults are filled so `makeScene(["a.png", "b.png"])` renders. Goes through the same
+  strict `parseScene` (illegal scenes still throw) and resolves slide srcs against `opts.baseUrl`.
+  Exported from `vexy-stax-js`, the element bundle, and the global build.
+- **`createStax(elOrSelector, opts)`** (341): an ESM factory mirroring lines-nano's `createNano`.
+  Resolves the element, builds the scene (from `slides` via `makeScene`, or `scene` via `loadScene`
+  — a URL **or** an inline object), mounts a `VexyStax`, waits for `ready`, optionally starts a mode
+  (`playable`/`scrollspy`), and returns the ready instance. Re-exported from the element bundle so a
+  single CDN `<script>` import gives `createStax`/`makeScene`/`loadScene`/`VexyStax`.
+- **`slides` + `captions` attributes on `<vexy-stax>`** (341): `<vexy-stax slides="a.png b.png c.png"
+  view="compact" mode="playable">` builds a scene from a space/newline-separated URL list (no scene
+  JSON needed). `captions` toggles caption plates. The existing `scene`/`config` paths are unchanged.
+- **Remote slide images** (341): the three.js `TextureLoader` now sets `crossOrigin="anonymous"`, so
+  slide `src` may be a remote `http(s)` URL — the image loads cross-origin **and** the canvas stays
+  exportable (`toImage`/`toVideo`) when the server sends CORS headers. `resolveSrc` already preserved
+  absolute URLs; this is the last piece. Verified headless (a slide referenced by an absolute http
+  URL loads and exports a non-trivial PNG).
+- **Click-to-toggle** (342): clicking anywhere inside an interactive container fluently transitions
+  between views — not-compact → collapse to compact, compact → expand. It reuses the morph driver (a
+  smooth `expand`/`collapse` leg — never a snap) and is **ON by default** for the `<vexy-stax>`
+  element and every `createStax` instance, layered **on top of** scrollspy (scroll drives the morph;
+  a click still toggles). New methods: `VexyStax.toggleView()` / `.enableClickToggle()` /
+  `.disableClickToggle()` and `el.toggleView()`. Opt out via `click-toggle="false"` (attribute) or
+  `createStax(el, { clickToggle: false })`.
+- **Scene-in-init** (342): pass a full inline scene **object** at initialization — `createStax(el,
+  { scene: {…} })` and the `<vexy-stax>` `el.scene = {…}` property (alongside the existing `config`
+  property). No URL / fetch required.
+- **Step-by-step how-to demos in `docs/`** (341): `scripts/build-docs.mjs` now also emits
+  `demo-component.html` (declarative `<vexy-stax>`), `demo-module.html` (ESM `createStax`/inline scene
+  /click-to-toggle), and `demo-library.html` (global `window.VexyStax.create`) — each a side-by-side
+  "minimal code + live element" page modeled on i.vexy.art/dev/lines-nano. The landing page gains a
+  "Use it — three ways" section linking to them, and every page documents **both** the co-located
+  local bundle and the **jsDelivr CDN** URL (`https://cdn.jsdelivr.net/npm/vexy-stax-js@<version>/…`,
+  version read from `package.json`). The existing `playable.html` / `scrollable.html` are unchanged
+  except the scrollspy demo now lets a click toggle on top of the scroll.
+
+### Changed
+
+- **Default floor → invisible white pane with faint reflections** (`#ffffff` / opacity `0.0` /
+  reflectivity `0.1`): `scene.js` `parseFloor`, the JSON schema, and the docs demos now default to a
+  floor with **no visible grey rectangle** (opacity 0) and only a whisper of mirror (reflectivity
+  0.1). Kept in exact lockstep with `vexy_stax.scene.Floor` (PY↔JS parity). The previous default was
+  a smoked-glass dark tint (`#1a1a1a` / `0.04` / `0.5`).
+
+### Notes
+
+- The package version is `3.1.2` (the next patch after the published `3.1.1`); this CHANGELOG entry
+  follows the repo's `3.0.x` issue-tracking heading convention for issues 341/342. CDN URLs in the
+  docs/README pin to `3.1.2`.
+
+## [3.0.12] — issue 341
+
+### Changed
+
+- **`docs/` is now a proper landing page** (341): https://vexy.dev/vexy-stax-js/ used to embed the
+  playable animation directly (with the dated grey-reflection floor) and linked to nothing.
+  `scripts/build-docs.mjs` now emits `index.html` as a LANDING PAGE — a hero + three cards linking
+  to the **Animated demo** (`playable.html`), the **Scrollspy demo** (`scrollable.html`), and the
+  **Documentation** at https://vexy.dev/vexy-stax-py/ — plus install/usage snippets, and no embedded
+  animation. The two demos are emitted as their own pages using clean-floor scene variants
+  (`airbl-demo.scene.json` / `airbl-scrollable.scene.json`, reflectivity 0) so neither shows the grey
+  reflection "shadows". All paths are relative so the site works both locally and under
+  `/vexy-stax-js/`. Verified headless: both demos mount without errors and the landing cards resolve.
+
 ## [3.0.11] — issues 335, 336, 337
 
 ### Added

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 Adam Twardoch / VexyArt
+   Copyright 2025 Fontlab Ltd.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -28,30 +28,109 @@ node verify/run.mjs && python3 verify/gate.py
 
 ## Usage
 
-ESM:
+Three ways to drop a deck on a page, easiest first (issues 341 / 342).
 
-```js
-import { VexyStax, loadScene } from "vexy-stax-js";
-const scene = await loadScene("scene.json");
-const stax = new VexyStax(container, scene);
-await stax.setView("compact");
-const blob = await stax.toImage({ scale: 2 });
-```
-
-Web Component:
+### Web Component — just a list of slides
 
 ```html
 <script type="module" src="./dist/vexy-stax.element.js"></script>
+
+<!-- The `slides` attribute: a space/newline-separated list of image URLs (local, data:, or
+     remote http(s)). Captions off by default; mode="playable" plays the transition once. -->
+<vexy-stax
+  slides="layer-0.png layer-1.png https://example.com/layer-2.png"
+  view="compact" mode="playable">
+</vexy-stax>
+
+<!-- …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>
 ```
 
-Global:
+**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/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`
+
+```js
+import { createStax, makeScene, VexyStax, loadScene } from "vexy-stax-js";
+
+// One call: build a scene from a URL list, mount, wait for ready.
+const stax = await createStax("#stage", {
+  slides: ["layer-0.png", "https://example.com/layer-1.png"],
+  gap: 480, transition: "expand_collapse", mode: "playable",
+});
+
+await stax.toggleView();          // fluent compact↔expanded (the default click behavior)
+const mp4 = await stax.toVideo(); // seekable mp4
+
+// createStax also accepts an inline scene object (scene-in-init):
+await createStax("#hero", { scene: { version: 1, slides: [{ src: "a.png" }] }, view: "expanded" });
+
+// makeScene builds a valid scene from a bare URL list, filling sensible defaults:
+const scene = makeScene(["a.png", "b.png", "c.png"], { gap: 480, transition: "expand_collapse" });
+const low  = new VexyStax(container, scene); // the low-level path is still available
+```
+
+`createStax(elOrSelector, opts)` — `opts` accepts `{ slides | scene, view, mode, trigger, width,
+height, aspect, clickToggle, baseUrl, …sceneOverrides }`. Any remaining key (`size`, `camera`, `gap`,
+`transition`, `background`, `captions`, `floor`, `edge`, …) is forwarded to `makeScene`.
+
+### Global script — `window.VexyStax`
 
 ```html
 <script src="./dist/vexy-stax.global.js"></script>
-<script>const stax = new VexyStax.VexyStax(el, scene);</script>
+<script>
+  VexyStax.create("#stage", { slides: ["a.png", "b.png", "c.png"] });
+</script>
 ```
 
+### CDN (no build step)
+
+Every snippet above also works verbatim from the jsDelivr CDN — swap the local bundle path for:
+
+```html
+<!-- Web Component / ESM -->
+<script type="module" src="https://cdn.jsdelivr.net/npm/vexy-stax-js@3.1.2/dist/vexy-stax.element.js"></script>
+<!-- Global script -->
+<script src="https://cdn.jsdelivr.net/npm/vexy-stax-js@3.1.2/dist/vexy-stax.global.js"></script>
+```
+
+### Remote slide images
+
+Slide `src` may be a local path, a `data:` URI, **or a remote `http(s)` URL**. The texture loader
+requests cross-origin images with `crossOrigin="anonymous"`, so a server that sends CORS headers
+lets the image load **and** keeps the canvas exportable (`toImage` / `toVideo`).
+
+### Live demos & how-to pages
+
+`npm run build:docs` emits a [docs site](https://vexy.dev/vexy-stax-js/): a landing page, the
+**Animated** (`playable.html`) and **Scrollspy** (`scrollable.html`) demos, plus three side-by-side
+"how to use" pages — `demo-component.html`, `demo-module.html`, `demo-library.html` — each showing
+the minimal code beside the live result (modeled on i.vexy.art/dev/lines-nano).
+
 ## Layout
 
 ```
@@ -74,4 +153,4 @@ for the same scene; both are tested against the same fixture vectors.
 
 ## License
 
-Apache-2.0 — Copyright 2026 Adam Twardoch / VexyArt
+Apache-2.0 — Copyright 2026 Fontlab Ltd.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vexy-stax-js",
-  "version": "3.1.1",
+  "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/schema/vexy-stax-scene.schema.json

@@ -53,9 +53,9 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "color": { "type": "string", "default": "#1a1a1a" },
-        "opacity": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.04, "description": "Smoked glass — ~4% (issue 303)." },
-        "reflectivity": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 }
+        "color": { "type": "string", "default": "#ffffff" },
+        "opacity": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.0, "description": "Invisible floor pane by default (no grey rectangle); faint reflections only." },
+        "reflectivity": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.1 }
       }
     },
     "edge": {

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

@@ -1,16 +1,32 @@
 // SPDX-License-Identifier: Apache-2.0
 // this_file: src/element.js
 //
-// <vexy-stax> custom element (SPEC.md §6.2). Attributes: scene (URL), view,
-// mode (static|playable|scrollspy), width, height. Property `config` accepts an
-// inline scene object (overrides `scene`). Events: ready, transitionstart,
-// transitionend. Mounts a VexyStax in light DOM. Auto-registers on import.
-
-import { VexyStax, loadScene } from "./index.js";
+// <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, 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";
+
+// Re-export the public ESM API from the element bundle (issue 341): the built
+// dist/vexy-stax.element.js has src/element.js as its entry, so a user who loads that single
+// file can also `import { createStax, makeScene, loadScene, VexyStax }` from it (the how-to
+// ESM demo + the documented CDN URL both rely on this).
+export { VexyStax, loadScene, parseScene, makeScene, createStax } from "./index.js";
 
 export class VexyStaxElement extends HTMLElement {
   static get observedAttributes() {
-    return ["scene", "view", "mode", "trigger", "width", "height"];
+    // `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.
+    // `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() {
@@ -20,7 +36,7 @@ export class VexyStaxElement extends HTMLElement {
     this._mounting = false;
   }
 
-  /** Inline scene object (or JSON string); overrides the `scene` attribute. */
+  /** Inline scene object (or JSON string); overrides the `scene`/`slides` attributes. */
   set config(value) {
     this._config = typeof value === "string" ? JSON.parse(value) : value;
     if (this.isConnected) this._mount();
@@ -29,6 +45,26 @@ export class VexyStaxElement extends HTMLElement {
     return this._config;
   }
 
+  /**
+   * Scene-in-init (issue 342): assigning an OBJECT (or JSON string) sets the inline scene
+   * (same as `config`), so `el.scene = {version:1, slides:[…]}` works at init. Assigning a
+   * STRING URL is treated as the `scene` attribute (a URL to fetch). This makes the property
+   * mirror the lines-nano-style "pass the data right in" ergonomics for the Web Component.
+   */
+  set scene(value) {
+    if (value && typeof value === "object") {
+      this.config = value; // inline scene object
+    } else if (typeof value === "string") {
+      // Looks like JSON? treat as an inline scene; otherwise it's a URL attribute.
+      const trimmed = value.trim();
+      if (trimmed.startsWith("{")) this.config = JSON.parse(trimmed);
+      else this.setAttribute("scene", value);
+    }
+  }
+  get scene() {
+    return this._config ?? this.getAttribute("scene");
+  }
+
   /** The underlying VexyStax instance (null until mounted). */
   get instance() {
     return this._stax;
@@ -51,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;
@@ -60,6 +96,12 @@ export class VexyStaxElement extends HTMLElement {
       this._stax?.setView(this.getAttribute("view") || "expanded");
       return;
     }
+    if (name === "click-toggle") {
+      // Toggle the issue-342 behavior in place (no costly remount).
+      if (this.getAttribute("click-toggle") === "false") this._stax?.disableClickToggle();
+      else this._stax?.enableClickToggle();
+      return;
+    }
     // scene/mode changes re-mount.
     this._mount();
   }
@@ -69,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() {
@@ -78,10 +150,26 @@ export class VexyStaxElement extends HTMLElement {
       this._stax?.destroy();
       this._stax = null;
 
-      const sceneSrc = this._config ?? this.getAttribute("scene");
-      if (!sceneSrc) return; // nothing to render yet
       const baseUrl = typeof document !== "undefined" ? document.baseURI : undefined;
-      const scene = await loadScene(sceneSrc, { baseUrl });
+      // 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) {
+        scene = await loadScene(sceneSrc, { baseUrl });
+      } else if (slidesAttr && slidesAttr.trim()) {
+        const urls = slidesAttr.split(/\s+/).filter(Boolean);
+        const captionsAttr = this.getAttribute("captions");
+        const opts = { baseUrl };
+        if (captionsAttr !== null) opts.captions = captionsAttr !== "false";
+        scene = makeScene(urls, opts);
+      } else {
+        return; // nothing to render yet
+      }
 
       const view = this.getAttribute("view") || scene.view || "expanded";
       scene.view = view;
@@ -99,6 +187,28 @@ export class VexyStaxElement extends HTMLElement {
       // mode="playable" leaves the deck at its initial view; the host calls
       // el.transition(...) (e.g. on a button) to play it.
 
+      // Issue 342: click-to-toggle is ON by default for the interactive container — a click
+      // anywhere inside fluently toggles compact↔expanded, layered on top of scrollspy. Opt
+      // out with the `click-toggle="false"` attribute (or mode="static" pages that don't want it
+      // can still opt out explicitly). Default ON for every mode so a generic <vexy-stax> just
+      // works.
+      if (this.getAttribute("click-toggle") !== "false") {
+        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 } }));
@@ -127,6 +237,10 @@ export class VexyStaxElement extends HTMLElement {
   seek(t) {
     return this._stax?.seek(t);
   }
+  /** Issue 342: fluently toggle compact↔expanded (the default click behavior, exposed). */
+  toggleView() {
+    return this._stax?.toggleView();
+  }
 }
 
 if (typeof customElements !== "undefined" && !customElements.get("vexy-stax")) {

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/global.js

@@ -4,13 +4,19 @@
 // Classic-script global entry (SPEC.md §6.3). Importing this auto-registers the
 // <vexy-stax> element (via element.js) and exposes window.VexyStax.
 
-import { VexyStax, loadScene } from "./index.js";
+import { VexyStax, loadScene, makeScene, createStax } from "./index.js";
 import "./element.js";
 
-const api = { VexyStax, loadScene };
+// Issue 341: expose the easy entry points on the global too. `window.VexyStax.create(el, opts)`
+// mirrors lines-nano's `VexyLinesNano.create`, and makeScene builds a scene from a URL list.
+const api = { VexyStax, loadScene, makeScene, createStax, create: createStax };
 
 if (typeof window !== "undefined") {
   window.VexyStax = api;
 }
 
-export { VexyStax, loadScene };
+// Also export `create` as a NAMED binding (alias of createStax): Vite's IIFE lib mode assigns
+// `window.VexyStax = <module exports namespace>` AFTER this file runs, overwriting the `api`
+// object above — so `create` must be a real export to survive on `window.VexyStax.create`
+// (the lines-nano-style entry point used by the global demo).
+export { VexyStax, loadScene, makeScene, createStax, createStax as create };

package/src/index.js

@@ -7,15 +7,17 @@
 // mapping, and exporters are in transition.js / scrollspy.js / export.js.
 
 import { Stage } from "./stage.js";
-import { loadScene, parseScene, resolvedOpacity } from "./scene.js";
+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 {
   loadScene,
   parseScene,
+  makeScene,
   resolvedOpacity,
 };
 
@@ -50,6 +52,14 @@ export class VexyStax {
     this.scene = scene;
     this.stage = new Stage(container, scene);
     this._ro = null; // ResizeObserver for post-layout resize
+    // Issue 342: track the CURRENT view so click-to-toggle knows which way to go. Starts at the
+    // scene's initial view; updated by setView/seek/transition/toggleView. `_morphT` is the last
+    // applied morph factor (0=compact, 1=expanded) used to disambiguate mid-morph clicks.
+    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();
       // After mount, observe the container for its first actual layout dimensions.
@@ -87,6 +97,8 @@ export class VexyStax {
     await this._ready;
     this.stage.setView(view);
     this.stage.render();
+    this._morphT = view === "compact" ? 0 : 1;
+    this._setView_(view === "compact" ? "compact" : "expanded");
     return this;
   }
 
@@ -99,9 +111,22 @@ export class VexyStax {
     const tt = Math.max(0, Math.min(1, Number(t) || 0));
     this.stage.applyFrameState(frameStateAt(this.scene, tt, this.stage.camera.aspect), tt);
     this.stage.render();
+    // 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;
+    // 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;
@@ -172,12 +197,19 @@ 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 } }));
     try {
       await controller.promise;
+      // Settle the tracked view to the transition's end endpoint (issue 342).
+      const { endMorph } = transitionEndpoints(resolvedKind);
+      this._morphT = endMorph;
+      this._setView_(endMorph >= 0.5 ? "expanded" : "compact");
       this.container.dispatchEvent?.(new CustomEvent("transitionend", { detail: { kind: resolvedKind } }));
     } finally {
       this._cancelTransition = null;
@@ -185,6 +217,76 @@ export class VexyStax {
     return this;
   }
 
+  /**
+   * Click-to-toggle (issue 342): fluently transition between the two views. If the deck is
+   * currently expanded (or mid-morph past halfway), collapse to compact; otherwise expand.
+   * Reuses the existing morph driver (a smooth `collapse`/`expand` leg) — never a snap. Safe to
+   * call repeatedly: an in-flight toggle is ignored until it settles. Returns the played kind.
+   */
+  async toggleView() {
+    await this._ready;
+    if (this._toggling) return null;
+    const goCompact = this._currentView !== "compact"; // not compact ⇒ collapse to compact
+    const kind = goCompact ? "collapse" : "expand";
+    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 the easing; ensure one exists.
+      if (!this.scene.transition) {
+        this.scene.transition = { kind, duration: 0.7, wait: 0, fps: 30, easing: "easeInOutCubic" };
+      }
+      // 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;
+    }
+    return kind;
+  }
+
+  /**
+   * Enable click-to-toggle on the container (issue 342): a pointer click anywhere inside the
+   * element fluently toggles compact↔expanded. ON by default for interactive containers (the
+   * <vexy-stax> element + createStax) and layered ON TOP of scrollspy (scroll drives the morph;
+   * a click still toggles). Idempotent. Pass to disableClickToggle() to opt out.
+   */
+  enableClickToggle() {
+    if (this._clickToggle || !this.container?.addEventListener) return this;
+    const handler = (ev) => {
+      // Ignore clicks on interactive controls a host may overlay (buttons/links/inputs).
+      const tag = ev.target?.tagName;
+      if (tag && /^(BUTTON|A|INPUT|SELECT|TEXTAREA|LABEL)$/.test(tag)) return;
+      this.toggleView();
+    };
+    this.container.addEventListener("click", handler);
+    // Pointer affordance so it reads as clickable.
+    if (this.container.style && !this.container.style.cursor) this.container.style.cursor = "pointer";
+    this._clickToggle = { handler };
+    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) {
+      this.container.removeEventListener?.("click", this._clickToggle.handler);
+      this._clickToggle = null;
+    }
+    return this;
+  }
+
   /** Re-derive the morph factor t from a frame's gap[1] (for caption fade). */
   _morphFromGaps(gaps) {
     if (gaps.length < 2) return 0;
@@ -195,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;
@@ -301,8 +418,111 @@ export class VexyStax {
   destroy() {
     this._cancelTransition?.();
     this._scrollspy?.disconnect?.();
+    this.disableClickToggle();
+    this._controls?.destroy();
+    this._controls = null;
     this._ro?.disconnect?.();
     this._ro = null;
     this.stage?.dispose();
   }
 }
+
+// Scene-construction options consumed by createStax/makeScene rather than describing how to
+// 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", "aspect", "baseUrl", "clickToggle",
+]);
+
+/**
+ * The "extremely easy to use" ESM factory (issue 341), mirroring lines-nano's `createNano`.
+ * Resolve the mount element, build the scene (from a bare `slides` list via makeScene, or
+ * from a `scene` URL/object via loadScene), mount a VexyStax, wait until it's ready, optionally
+ * start a mode (playable/scrollspy), and return the ready instance.
+ *
+ * @param {HTMLElement|string} elOrSelector mount element or a CSS selector for it
+ * @param {object} [opts]
+ *   @param {string[]|object[]} [opts.slides]  slide image URLs (local/data:/remote) or slide
+ *       objects — the easy path; built via makeScene with the remaining opts as overrides.
+ *   @param {string|object} [opts.scene]  a scene URL or inline scene object (via loadScene);
+ *       used when `slides` is not given.
+ *   @param {"expanded"|"compact"} [opts.view]  initial view.
+ *   @param {"static"|"playable"|"scrollspy"} [opts.mode]  mount mode (default "static").
+ *       "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, …).
+ * @returns {Promise<VexyStax>} the ready instance.
+ */
+export async function createStax(elOrSelector, opts = {}) {
+  const el =
+    typeof elOrSelector === "string" ? document.querySelector(elOrSelector) : elOrSelector;
+  if (!el) throw new Error(`createStax: element not found (${String(elOrSelector)})`);
+  if (opts === null || typeof opts !== "object") throw new Error("createStax: opts must be an object");
+
+  // 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";
+  }
+
+  const baseUrl = opts.baseUrl ?? (typeof document !== "undefined" ? document.baseURI : undefined);
+
+  let scene;
+  if (opts.slides) {
+    // Flat scene overrides = every opt that isn't a mount/source key.
+    const sceneOpts = { baseUrl };
+    for (const [k, v] of Object.entries(opts)) {
+      if (!MOUNT_KEYS.has(k)) sceneOpts[k] = v;
+    }
+    scene = makeScene(opts.slides, sceneOpts);
+  } else if (opts.scene !== undefined) {
+    scene = await loadScene(opts.scene, { baseUrl });
+  } else {
+    throw new Error("createStax: provide `slides` (URLs) or `scene` (URL/object)");
+  }
+
+  // The view override wins over the scene's own initial view.
+  if (opts.view) scene.view = opts.view;
+
+  const stax = new VexyStax(el, scene);
+  await stax.ready;
+
+  const mode = opts.mode ?? "static";
+  if (mode === "scrollspy") {
+    const trigger =
+      typeof opts.trigger === "string" ? document.querySelector(opts.trigger) : opts.trigger ?? el;
+    stax.scrollspy({ trigger });
+  } else if (mode === "playable" && scene.transition) {
+    // Kick off the scene's transition once (best-effort; ignore if it's cancelled by teardown).
+    stax.transition().catch(() => {});
+  }
+
+  // Issue 342: click-to-toggle is ON by default for the interactive container (every mode),
+  // 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/scene.js

@@ -136,15 +136,17 @@ function parseVideo(raw) {
 }
 
 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 };
+  // Default floor: an INVISIBLE white pane (opacity 0 → no grey floor rectangle) with faint
+  // reflections (reflectivity 0.1) so decks read as floating with just a whisper of mirror.
+  // Kept in exact lockstep with vexy_stax.scene.Floor (PY↔JS parity).
+  if (raw === undefined) return { color: "#ffffff", opacity: 0.0, reflectivity: 0.1 };
   const o = asObject(raw, "floor");
   rejectExtraKeys(o, new Set(["color", "opacity", "reflectivity"]), "floor");
   return {
-    color: o.color === undefined ? "#1a1a1a" : str(o.color, "floor.color"),
-    opacity: o.opacity === undefined ? 0.04 : num(o.opacity, "floor.opacity", { min: 0, max: 1 }),
+    color: o.color === undefined ? "#ffffff" : str(o.color, "floor.color"),
+    opacity: o.opacity === undefined ? 0.0 : num(o.opacity, "floor.opacity", { min: 0, max: 1 }),
     reflectivity:
-      o.reflectivity === undefined ? 0.5 : num(o.reflectivity, "floor.reflectivity", { min: 0, max: 1 }),
+      o.reflectivity === undefined ? 0.1 : num(o.reflectivity, "floor.reflectivity", { min: 0, max: 1 }),
   };
 }
 
@@ -290,6 +292,129 @@ export function parseScene(raw) {
   };
 }
 
+// Issue 341: the "extremely easy to use" entry point. Build a valid Scene object from a
+// bare list of slide image URLs (or {src, caption, opacity, gap} objects) + a flat options
+// bag, filling sensible defaults so even `makeScene(["a.png", "b.png"])` renders. The result
+// goes straight through parseScene (so the SAME strict invariants apply — illegal scenes
+// still throw) and is returned normalized, ready for `new VexyStax(el, scene)`. Slide `src`
+// may be a local path, a `data:` URI, OR a remote http(s) URL — resolveSrc/the TextureLoader
+// preserve absolute URLs (and stage.js sets crossOrigin so remote images load + stay
+// canvas-exportable). This keeps "easy scene customization" + "remote URL" in one helper.
+
+/** One slide entry → a raw scene-slide object. A bare string is treated as `src`. */
+function slideEntry(entry, index, defaults) {
+  if (typeof entry === "string") {
+    const slide = { src: entry };
+    if (defaults.caption) slide.caption = { text: "", show_in: "expanded" };
+    return slide;
+  }
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    throw new Error(`makeScene: slides[${index}] must be a string URL or an object`);
+  }
+  // Accept the friendly shape {src, caption, opacity, gap}. `caption` may be a plain
+  // string (→ {text, show_in:"expanded"}) for ergonomics, or the full caption object.
+  const slide = {};
+  if (entry.src === undefined) throw new Error(`makeScene: slides[${index}].src is required`);
+  slide.src = entry.src;
+  if (entry.gap !== undefined && entry.gap !== null) slide.gap = entry.gap;
+  if (entry.opacity !== undefined) slide.opacity = entry.opacity;
+  if (entry.caption !== undefined) {
+    slide.caption =
+      typeof entry.caption === "string"
+        ? { text: entry.caption, show_in: "expanded" }
+        : entry.caption;
+  }
+  return slide;
+}
+
+/**
+ * Build a normalized Scene from a list of slide image URLs (or slide objects) plus a flat
+ * options bag (issue 341). Returns a parsed scene (via parseScene), so it is ready to hand
+ * to `new VexyStax(container, scene)`. Sensible defaults are filled so a bare list of URLs
+ * renders. Slide `src` may be local, `data:`, or a remote http(s) URL.
+ *
+ * @param {Array<string|{src:string, caption?:string|object, opacity?:number|object, gap?:number}>} slides
+ *   slide image URLs or slide objects (at least one).
+ * @param {object} [opts] flat scene options:
+ *   @param {{width:number,height:number}|number[]} [opts.size]  scene size (default 1920×1080)
+ *   @param {object} [opts.camera]      camera overrides (gap/distance/angle/elevation/fov)
+ *   @param {string} [opts.gap]         shortcut for camera.gap (expanded plate spacing)
+ *   @param {string|object} [opts.transition]  a transition KIND string, or a full transition object
+ *   @param {string} [opts.view]        initial view ("expanded" | "compact")
+ *   @param {string} [opts.background]  background CSS color
+ *   @param {boolean} [opts.captions]   global captions toggle (default: true)
+ *   @param {object} [opts.floor]       floor overrides (color/opacity/reflectivity)
+ *   @param {object} [opts.edge]        plate edge overrides (width/color)
+ *   @param {object} [opts.caption_defaults] caption style defaults (size/color/font/…)
+ *   @param {object} [opts.caption_fade]     caption fade overrides
+ *   @param {object} [opts.video]       video render overrides
+ * @returns {object} a normalized scene (same shape as parseScene's output)
+ */
+export function makeScene(slides, opts = {}) {
+  if (!Array.isArray(slides) || slides.length < 1) {
+    throw new Error("makeScene: pass a non-empty array of slide URLs or slide objects");
+  }
+  if (opts === null || typeof opts !== "object" || Array.isArray(opts)) {
+    throw new Error("makeScene: opts must be an object");
+  }
+  // Fail loud on unknown options (parse, don't validate): a typo'd override (e.g. `juicey`)
+  // shouldn't be silently dropped. `baseUrl`/`gap` are makeScene conveniences; the rest map
+  // 1:1 onto scene keys validated by parseScene.
+  const ALLOWED_OPTS = new Set([
+    "baseUrl", "gap", "size", "camera", "transition", "view", "background",
+    "captions", "floor", "edge", "juicy", "caption_defaults", "caption_fade", "video",
+  ]);
+  for (const key of Object.keys(opts)) {
+    if (!ALLOWED_OPTS.has(key)) throw new Error(`makeScene: unknown option ${JSON.stringify(key)}`);
+  }
+
+  // A bare list of objects with no caption text shouldn't auto-add empty caption plates;
+  // `captions` only forces empty captions for STRING slides when explicitly requested.
+  const wantCaptions = opts.captions === true;
+  const raw = { version: 1, slides: slides.map((s, i) => slideEntry(s, i, { caption: wantCaptions })) };
+
+  // size: accept {width,height} or [w,h].
+  if (opts.size !== undefined) {
+    if (Array.isArray(opts.size)) raw.size = { width: opts.size[0], height: opts.size[1] };
+    else raw.size = opts.size;
+  }
+
+  // camera: start from explicit overrides, then fold in the `gap` shortcut.
+  if (opts.camera !== undefined || opts.gap !== undefined) {
+    raw.camera = { ...(opts.camera ?? {}) };
+    if (opts.gap !== undefined) raw.camera.gap = opts.gap;
+  }
+
+  // transition: a bare kind string is expanded to a minimal transition object; an object
+  // passes through (parseScene fills its own defaults + validates the kind).
+  if (opts.transition !== undefined) {
+    raw.transition =
+      typeof opts.transition === "string" ? { kind: opts.transition } : opts.transition;
+  }
+
+  if (opts.view !== undefined) raw.view = opts.view;
+  if (opts.background !== undefined) raw.background = opts.background;
+  // captions: only forward an explicit boolean (string-slide empty captions handled above).
+  if (typeof opts.captions === "boolean") raw.captions = opts.captions;
+  if (opts.floor !== undefined) raw.floor = opts.floor;
+  if (opts.edge !== undefined) raw.edge = opts.edge;
+  if (opts.juicy !== undefined) raw.juicy = opts.juicy;
+  if (opts.caption_defaults !== undefined) raw.caption_defaults = opts.caption_defaults;
+  if (opts.caption_fade !== undefined) raw.caption_fade = opts.caption_fade;
+  if (opts.video !== undefined) raw.video = opts.video;
+
+  const scene = parseScene(raw);
+  // Resolve slide srcs against an optional base (the host page / scene URL). Absolute
+  // http(s) URLs and `data:` URIs are preserved (resolveSrc uses `new URL(src, base)`), so
+  // remote slide images keep working; relative paths resolve against the base (issue 341).
+  const base =
+    opts.baseUrl ?? (typeof document !== "undefined" ? document.baseURI : undefined);
+  if (base) {
+    for (const slide of scene.slides) slide.src = resolveSrc(slide.src, base);
+  }
+  return scene;
+}
+
 /** Resolve a slide `src` against `base` (a URL string). `data:` URIs pass through. */
 function resolveSrc(src, base) {
   if (src.startsWith("data:")) return src;

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
@@ -239,6 +244,12 @@ export class Stage {
 
   async _buildPlates() {
     const loader = new THREE.TextureLoader();
+    // Issue 341: load slide images from REMOTE http(s) URLs, not just local paths/data: URIs.
+    // setCrossOrigin("anonymous") makes the underlying <img> a CORS request, so a server that
+    // sends `Access-Control-Allow-Origin` lets the image load AND keeps the WebGL canvas
+    // un-tainted (toImage/toVideo stay exportable). Local same-origin and data: URIs are
+    // unaffected. resolveSrc already preserves absolute URLs, so this is the last piece.
+    loader.setCrossOrigin("anonymous");
     const textures = await Promise.all(this.scene.slides.map((s) => loadTexture(loader, s.src)));
     const reflectivity = this.scene.floor.reflectivity;
 
@@ -271,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
@@ -313,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);
       }
 
@@ -444,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();