vexy-stax-js 3.0.10 → 3.1.2

package/CHANGELOG.md

@@ -4,6 +4,98 @@
 
 All notable changes to this project are documented here.
 
+## [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
+
+- **`video` scene section** (335 / 336): `scene.js` `parseVideo()` + the JSON schema now accept and
+  validate the `video` section (`width`/`height`/`fps`/`frames`/`first_hold`/`last_hold`), mirroring
+  `vexy_stax.scene.Video`. Previously the strict parser rejected the key with "Unknown key 'video' in
+  scene", which broke the Python `playwright` engine (it mounts the scene in `<vexy-stax>`) — issue
+  336. The element now accepts a scene carrying `video`.
+- **Held first/last still frames in `toVideo()`** (335 §2): the video export now bookends the clip
+  with held stills — it renders the start endpoint and captures it `video.first_hold` times (default
+  10), plays the transition, then captures the end endpoint `video.last_hold` times (still →
+  transition → still). Mirrors `geometry.py`'s `frame_plan` holds. Verified: the exported
+  `airbl-transition.mp4` first/last frames are static.
+
+### Fixed
+
+- **Compact view reserved empty caption space** (337): `compactCamera` now fits ONLY the frontmost
+  slide plate (height `H`, aimed at the slide center `Y = lift`) instead of the slide+caption
+  composite, so the compact view fills the frame with no caption padding. Mirrors `geometry.py`
+  (issue 337). Verified: the playwright-rendered compact still fills the frame; geometry test updated.
+
 ## [3.0.10] — issues 331
 
 ### Fixed

package/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,89 @@ 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>
 ```
 
-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): assign an inline scene **object** without a URL —
+`el.scene = { version: 1, slides: [{ src: "a.png" }, …] }` (or the `config` property).
+
+### 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, 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 +133,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.0.10",
+  "version": "3.1.2",
   "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": {
@@ -70,6 +70,19 @@
     "background": { "type": "string", "default": "#ffffff" },
     "juicy": { "type": "boolean", "default": false, "description": "Python-only per-channel color match." },
     "captions": { "type": "boolean", "default": true, "description": "Global captions toggle (issue 332). ON: each slide plate sits on top of its on-floor caption plate (stacked layout). OFF: no caption plates; slide plates sit directly on the floor." },
+    "video": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Video render params (issue 335 §3): dimensions/fps/frame counts/held stills. transition still owns the animation (kind/easing/wait/duration); video owns the output framing. Defaults preserve prior behavior.",
+      "properties": {
+        "width": { "type": "integer", "minimum": 1, "description": "Video width; omitted ⇒ size.width." },
+        "height": { "type": "integer", "minimum": 1, "description": "Video height; omitted ⇒ size.height." },
+        "fps": { "type": "integer", "minimum": 1, "description": "Video frames per second; omitted ⇒ transition.fps (else 30). Overrides transition.fps when set." },
+        "frames": { "type": "integer", "minimum": 1, "description": "Transition frames PER LEG; omitted ⇒ round(transition.duration × fps)." },
+        "first_hold": { "type": "integer", "minimum": 0, "default": 10, "description": "Held copies of the FIRST frame (still intro)." },
+        "last_hold": { "type": "integer", "minimum": 0, "default": 10, "description": "Held copies of the LAST frame (still outro)." }
+      }
+    },
     "caption_defaults": { "$ref": "#/$defs/captionStyle" },
     "caption_fade": {
       "type": "object",

package/src/element.js

@@ -1,16 +1,25 @@
 // SPDX-License-Identifier: Apache-2.0
 // this_file: src/element.js
 //
-// <vexy-stax> custom element (SPEC.md §6.2). Attributes: scene (URL), view,
+// <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`). Events: ready, transitionstart,
+// inline scene object (overrides `scene`/`slides`). Events: ready, transitionstart,
 // transitionend. Mounts a VexyStax in light DOM. Auto-registers on import.
 
-import { VexyStax, loadScene } from "./index.js";
+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.
+    return ["scene", "slides", "captions", "view", "mode", "trigger", "width", "height", "click-toggle"];
   }
 
   constructor() {
@@ -20,7 +29,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 +38,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;
@@ -60,6 +89,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();
   }
@@ -78,10 +113,25 @@ 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): 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");
+      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 +149,15 @@ 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();
+      }
+
       this.dispatchEvent(new CustomEvent("ready", { detail: { instance: this._stax } }));
     } catch (err) {
       this.dispatchEvent(new CustomEvent("error", { detail: { error: err } }));
@@ -127,6 +186,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

@@ -330,13 +330,14 @@ export function expandedCamera(scene, viewportAspect) {
 export function compactCamera(scene, viewportAspect) {
   const cam = scene.camera;
   const depth = stackDepth(scene, "compact");
-  // Issue 332: the frontmost COMPOSITE the head-on camera frames is the slide plate plus
-  // (captions on) its on-floor caption plate stacked below it: full width W, height H + lift
-  // (lift == one caption-plate height), vertically centered at Y = lift/2. Aim at that
-  // composite center so neither the slide nor the caption row crops. Mirrors geometry.py.
+  // Issue 337: the compact view frames ONLY the frontmost SLIDE plate — not the composite with
+  // its caption row. Captions are invisible in compact (they fade in only as the deck expands),
+  // so reserving the caption-plate height just padded the frame. The slide is lifted by `lift`
+  // (issue 332: it sits on top of the on-floor caption plate), so its center is at Y = lift and
+  // it spans height H. Aim at the slide center and fit H so the slide fills the frame tight.
+  // Mirrors geometry.py.
   const lift = slideLift(scene);
-  const compositeH = scene.size.height + lift;
-  const target = [0.0, lift / 2.0, -depth / 2.0];
+  const target = [0.0, lift, -depth / 2.0];
 
   let isPercent = false;
   let pctVal = 90.0;
@@ -351,15 +352,16 @@ export function compactCamera(scene, viewportAspect) {
 
   let distance;
   if (isPercent) {
-    // Dual-axis crop-free fit (SPEC.md §3, issue 302 §1): fit the frontmost COMPOSITE
-    // (width W, height H + lift) so the limiting axis touches P% and the other axis only
-    // ever has extra padding (never a crop). distance = max(d_w, d_h). Mirrors geometry.py.
+    // Dual-axis crop-free fit (SPEC.md §3, issue 302 §1, issue 337): fit the frontmost SLIDE
+    // plate (width W, height H — NOT the caption composite) so the limiting axis touches P% and
+    // the other axis only ever has extra padding (never a crop). distance = max(d_w, d_h).
+    // Mirrors geometry.py.
     const hfov = (cam.fov * Math.PI) / 180.0;
     const aspect = viewportAspect || scene.size.width / scene.size.height;
     const vfov = 2.0 * Math.atan(Math.tan(hfov / 2.0) / aspect);
     const frac = pctVal / 100.0;
     const dW = scene.size.width / (2.0 * Math.tan(hfov / 2.0) * frac);
-    const dH = compositeH / (2.0 * Math.tan(vfov / 2.0) * frac);
+    const dH = scene.size.height / (2.0 * Math.tan(vfov / 2.0) * frac);
     const distToZ0 = Math.max(dW, dH);
     distance = distToZ0 + depth / 2.0;
   } else {

package/src/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,7 +7,7 @@
 // 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";
@@ -16,6 +16,7 @@ import { canvasToPngBlob, recordVideo } from "./export.js";
 export {
   loadScene,
   parseScene,
+  makeScene,
   resolvedOpacity,
 };
 
@@ -50,6 +51,13 @@ 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._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 +95,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;
     return this;
   }
 
@@ -99,6 +109,10 @@ 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;
+    this._currentView = tt >= 0.5 ? "expanded" : "compact";
     return this;
   }
 
@@ -178,6 +192,10 @@ export class VexyStax {
     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._currentView = endMorph >= 0.5 ? "expanded" : "compact";
       this.container.dispatchEvent?.(new CustomEvent("transitionend", { detail: { kind: resolvedKind } }));
     } finally {
       this._cancelTransition = null;
@@ -185,6 +203,61 @@ 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 timing; ensure one exists.
+      if (!this.scene.transition) {
+        this.scene.transition = { kind, duration: 0.9, wait: 0, fps: 30, easing: "easeInOutCubic" };
+      }
+      await this.transition(kind);
+    } 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;
+  }
+
+  /** 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;
@@ -205,13 +278,28 @@ export class VexyStax {
     await this._ready;
     const kind = opts.kind ?? this.scene.transition?.kind;
     if (!kind) throw new Error("VexyStax.toVideo: no kind given and scene.transition is null");
-    const fps = this.scene.transition?.fps ?? 30;
+    const fps = this.scene.video?.fps ?? this.scene.transition?.fps ?? 30;
     const canvas = this.stage.renderer.domElement;
+    // Issue 335 §2: bookend the clip with HELD STILLS — render the start frame and capture it
+    // `first_hold` times, then the transition, then capture the end frame `last_hold` times
+    // (still → transition → still). Defaults 10/10 from scene.video. Mirrors geometry.py's
+    // frame_plan holds (the Python engines get holds via frame_plan; here toVideo drives a
+    // real-time capture, so we hold by capturing the boundary frames repeatedly).
+    const firstHold = this.scene.video?.first_hold ?? 10;
+    const lastHold = this.scene.video?.last_hold ?? 10;
+    const { startMorph, endMorph } = transitionEndpoints(kind);
+    const aspect = this.stage.camera.aspect;
 
     return recordVideo({
       canvas,
       fps,
       run: async (onFrame) => {
+        // Held still intro: snap to the start endpoint and capture it `firstHold` times.
+        const startState = frameStateAt(this.scene, startMorph, aspect);
+        this.stage.applyFrameState(startState, startMorph);
+        this.stage.render();
+        for (let i = 0; i < firstHold; i++) onFrame(startState);
+
         const controller = playTransition(this.scene, (state) => {
           const t = this._morphFromGaps(state.gaps);
           this.stage.applyFrameState(state, t);
@@ -219,6 +307,12 @@ export class VexyStax {
           onFrame(state);
         }, { kind });
         await controller.promise;
+
+        // Held still outro: snap to the end endpoint and capture it `lastHold` times.
+        const endState = frameStateAt(this.scene, endMorph, aspect);
+        this.stage.applyFrameState(endState, endMorph);
+        this.stage.render();
+        for (let i = 0; i < lastHold; i++) onFrame(endState);
       },
     });
   }
@@ -280,8 +374,91 @@ export class VexyStax {
   destroy() {
     this._cancelTransition?.();
     this._scrollspy?.disconnect?.();
+    this.disableClickToggle();
     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", "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} [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;
+  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();
+  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

@@ -239,6 +239,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;