paper-motion 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to the `paper-motion` npm package. Dates are release dates on npm.
 
+## 0.4.1 · 2026-11-12
+
+- **The studio's live previews are much lighter.** A scene opened with `?embed` draws its shaders at the size it is
+  shown, not the full frame times the screen's density (a Retina screen drew 8 million pixels a frame for a box
+  700 px wide), skips layers no one can see, and plays at 30 frames a second. In a test of a part with six shots,
+  shader draws went from 180 to about 10 a second. Renders are unchanged.
+- **A part always plays its whole scene: its length is its speed.** Shorter plays it faster, longer slower, never
+  cut short and never looped; sounds move with the picture and keep their pitch. Each part may run from 1.6× faster
+  to 0.6× slower than its scene (`SPEED`, `lengthRange` in inventory.mjs); a length outside that range is held at
+  the limit with a warning. The studio's Length slider runs over that range, says how much faster or slower the
+  part plays, and its live preview plays at that speed. The planner proposes lengths inside the range.
+- **Previews in the studio play once and hold their last frame** (a click plays one again); "Play the whole video"
+  moves on when each part ends, instead of after a timer that let a part loop.
+- **Beat cuts puts one word on each beat, never repeating, and ends on its last word**: its length is the words
+  at the tempo. The chain records each scene's real length, so the studio knows it.
+
 ## 0.4.0 · 2026-11-12
 
 A piece is built from what the user has to show, not from a mood.

package/bin/pamo.mjs

@@ -550,7 +550,7 @@ async function main() {
       await ensureDeps();
       if (args.check) {
         const r = await chainLib.checkChain({ piece });
-        for (const p of r.parts) console.log(`  ${p.dir} · ${p.join} · ${p.from}–${+(p.from + p.seconds).toFixed(2)} s of ${p.D}`);
+        for (const p of r.parts) console.log(`  ${p.dir} · ${p.join} · ${p.seconds} s (its ${p.natural} s scene${Math.abs(p.rate - 1) > 0.005 ? `, ×${p.rate.toFixed(2)}` : ''})`);
         for (const w of r.warnings) console.log(`  ! ${w}`);
         console.log(`${r.total.toFixed(1)} s in all`);
         break;

package/lib/chain.mjs

@@ -22,6 +22,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
+import { lengthRange } from './inventory.mjs';
 
 export const JOINS = { cut: 0, whip: 0.35, dissolve: 0.5, dip: 0.5 };
 // the registry's transitions the user may have chosen, as joins between parts: [ffmpeg xfade transition, seconds].
@@ -35,7 +36,6 @@ export const MOVE_JOINS = {
 for (const [k, [, d]] of Object.entries(MOVE_JOINS)) JOINS[k] = d;
 JOINS.whip = 0.35;   // the engine's own whip (slide + smear) wins over the registry's whip move of the same name
 const OVERLAP = new Set(['whip', 'dissolve', ...Object.keys(MOVE_JOINS)]);   // joins that need the outgoing part to run on under the next
-const LAND_HOLD = 0.6;                           // seconds after a land for the hit to read
 
 const readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
 const pad = (i) => String(i + 1).padStart(2, '0');
@@ -156,17 +156,20 @@ export function plan(chain, infos) {
     const info = infos[i], D = info.config.duration, from = p.from ?? 0;
     const join = i === 0 ? 'cut' : (p.join ?? chain.join ?? 'whip');
     if (!JOINS.hasOwnProperty(join)) throw new Error(`part ${i + 1}: join "${join}" (use ${Object.keys(JOINS).join(', ')})`);
-    let seconds = p.seconds ?? D - from;
-    if (from + seconds > D + 1e-6) { warnings.push(`${p.dir}: ${seconds} s from ${from} runs past its end (${D} s); it plays ${+(D - from).toFixed(2)} s`); seconds = D - from; }
-    const lands = info.marks.filter((m) => m.gesture === 'land').map((m) => m.t).filter((t) => t >= from);
-    const land = lands.length ? Math.max(...lands) : null;
-    if (land !== null && from + seconds < land + LAND_HOLD) warnings.push(`${p.dir}: cut at ${seconds} s loses its land at ${+(land - from).toFixed(2)} s; give it at least ${+(land - from + LAND_HOLD).toFixed(1)} s`);
-    return { ...p, from, seconds, join, D };
+    // a part plays its whole scene: another length plays it faster or slower (never cut, never looped), within limits
+    const natural = +(D - from).toFixed(3), range = lengthRange(natural);
+    let seconds = p.seconds ?? natural;
+    if (seconds < range.min - 1e-6 || seconds > range.max + 1e-6) {
+      const held = Math.min(range.max, Math.max(range.min, seconds));
+      warnings.push(`${p.dir}: ${seconds} s would play its ${natural} s scene too ${seconds < range.min ? 'fast' : 'slow'} (it takes ${range.min}–${range.max} s); it plays ${held} s`);
+      seconds = held;
+    }
+    return { ...p, from, seconds, join, D, natural, rate: natural / seconds };
   });
-  // the outgoing part runs on under an overlapping join, as far as it can
+  // under an overlapping join the outgoing part holds its last frame while the next one comes in
   for (const [i, p] of parts.entries()) {
     const next = parts[i + 1], d = next && OVERLAP.has(next.join) ? JOINS[next.join] : 0;
-    p.to = Math.min(p.D, p.from + p.seconds + d);
+    p.out = +(p.seconds + d).toFixed(3);
   }
   return { parts, warnings, total: parts.reduce((a, p) => a + p.seconds, 0) };
 }
@@ -232,7 +235,7 @@ export async function renderChain({ cwd = process.cwd(), piece, out, motionBlur
         onStep({ part: i + 1, of: parts.length, dir: p.dir });
         if (kind) writeJob(home, { kind, part: i + 1, of: parts.length });
         const f = path.join(tmp, `${pad(i)}.mov`);
-        await renderVideo({ url: url(p), out: f, format: 'prores', from: p.from, to: p.to, sfx, motionBlur, dpr });
+        await renderVideo({ url: url(p), out: f, format: 'prores', from: p.from, to: p.D, rate: p.rate, seconds: p.out, sfx, motionBlur, dpr });
         files.push(f);
       }
       const tokens = readJson(path.join(cwd, 'brand/tokens.json'), {}), sound = readJson(path.join(cwd, 'brand/sound.json'), {});
@@ -268,7 +271,7 @@ export async function renderDrafts({ cwd = process.cwd(), piece, only, onStep =
       mark(p.dir, { status: 'rendering' });
       const out = path.join(dir, 'drafts', `${p.dir}.mp4`);
       try {
-        await renderVideo({ url: url(p), out, from: p.from, to: p.from + p.seconds, dpr: 0.5, motionBlur: 1, crf: 26 });
+        await renderVideo({ url: url(p), out, from: p.from, to: p.D, rate: p.rate, seconds: p.seconds, dpr: 0.5, motionBlur: 1, crf: 26 });
       } catch (e) { mark(p.dir, { status: 'review', error: String(e.message ?? e).slice(0, 300) }); throw e; }
       const v = (readPiece(dir)?.parts?.[p.dir]?.v ?? 0) + 1;
       mark(p.dir, { status: 'review', v, error: undefined, note: undefined });
@@ -296,6 +299,12 @@ async function withChain({ cwd, piece }, fn) {
   try {
     const browser = await launch(), infos = [];
     try { for (const p of chain.parts) infos.push(await sceneInfo(browser, url(p))); } finally { await browser.close(); }
+    // what each scene really lasts (some depend on their content: one beat per word), for the studio's length slider
+    try {
+      fs.writeFileSync(path.join(dir, '.lengths.json'), JSON.stringify(Object.fromEntries(chain.parts.map((p, i) => [p.dir, {
+        duration: infos[i].config.duration, mtime: Math.round(fs.statSync(path.join(dir, p.dir, 'scene.html')).mtimeMs),
+      }])), null, 2) + '\n');
+    } catch { /* the slider falls back to the block's usual length */ }
     const sizes = new Set(infos.map((x) => `${x.config.width}x${x.config.height}`));
     if (sizes.size > 1) throw new Error(`parts come in different sizes (${[...sizes].join(', ')}): set the same format in each CONFIG`);
     const planned = plan(chain, infos);

package/lib/edit.mjs

@@ -9,7 +9,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
-import { fillConfig, evalFill, normalize, loadRaw, propose, writePlan, describe } from './inventory.mjs';
+import { fillConfig, evalFill, normalize, loadRaw, propose, writePlan, describe, lengthRange } from './inventory.mjs';
 
 const readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
 const writeJson = (f, v) => fs.writeFileSync(f, JSON.stringify(v, null, 2) + '\n');
@@ -106,16 +106,29 @@ export const canUndo = (dir) => readJson(histFile(dir), []).at(-1)?.label ?? nul
 
 // ── reading the video ──────────────────────────────────────────────────────────────────────────────────────────
 
+/**
+ * A part's length within what its scene allows: it always plays the whole scene, so a length is a speed. Returns the
+ * length (held inside the range), the scene's own length, the range and the speed (above 1 is faster).
+ */
+export function timing(seconds, natural) {
+  const range = lengthRange(natural), s = Math.min(range.max, Math.max(range.min, seconds ?? natural));
+  return { seconds: s, duration: natural, range: { min: range.min, max: range.max }, rate: +(natural / s).toFixed(3) };
+}
+
 /** The parts as the editor shows them: each with its block, its words, motion, background, settings and join. */
 export function videoView(cwd, dir, scenes) {
   const chain = readJson(path.join(dir, 'chain.json'), null);
   if (!chain) return null;
   const byId = new Map(scenes.map((b) => [b.id, b]));
+  // what each scene really lasts, read by the last join (a scene's length can depend on its content); stale once edited
+  const lengths = readJson(path.join(dir, '.lengths.json'), {});
+  const real = (p) => { const l = lengths[p.dir]; try { return l && l.mtime === Math.round(fs.statSync(partFile(dir, p)).mtimeMs) ? l.duration : null; } catch { return null; } };
   const parts = (chain.parts ?? []).filter((p) => p.dir && fs.existsSync(partFile(dir, p))).map((p, i, all) => {
     const html = fs.readFileSync(partFile(dir, p), 'utf8'), cfg = readConfig(html), b = byId.get(p.id) ?? { id: p.id, params: [], needs: [] };
+    const D = real(p);
     const motion = b.repeat ? { param: b.repeat.param, value: cfg[b.repeat.param] ?? null, options: (b.params ?? []).find((x) => x.name === b.repeat.param)?.options ?? [], previews: b.repeat.previews ?? {} } : null;
     return {
-      dir: p.dir, id: p.id, title: b.title ?? p.id, kind: b.needs?.[0]?.kind ?? null, summary: b.summary ?? '', seconds: p.seconds ?? b.duration ?? 4, duration: b.duration ?? null,
+      dir: p.dir, id: p.id, title: b.title ?? p.id, kind: b.needs?.[0]?.kind ?? null, summary: b.summary ?? '', ...timing(p.seconds, D ?? b.duration ?? 4), exact: D !== null,
       join: i < all.length - 1 ? p.join ?? chain.join ?? 'whip' : null, shows: p.shows ?? [], what: p.what ?? '',
       words: wordFields(b, cfg), motion, background: cfg.background ?? null, takesBackground: (b.params ?? []).some((x) => x.name === 'background'), tune: tunables(b, cfg),
       mtime: Math.round(fs.statSync(partFile(dir, p)).mtimeMs),
@@ -193,8 +206,11 @@ export async function editVideo(cwd, dir, a, scenes, brief = {}) {
     }
     case 'seconds': {
       const p = find(), n = Number(a.value); if (!Number.isFinite(n)) throw new Error('give a length in seconds');
-      keep([chainFile], `the length of ${title(p)}`); p.seconds = Math.max(1, Math.min(30, +n.toFixed(1))); writeJson(chainFile, chain);
-      return { say: `${title(p)}: ${p.seconds} s`, part: p.dir };
+      const b = byId.get(p.id) ?? {}, natural = readJson(path.join(dir, '.lengths.json'), {})[p.dir]?.duration ?? b.duration ?? 4;
+      const t = timing(+n.toFixed(1), natural);
+      keep([chainFile], `the length of ${title(p)}`); p.seconds = t.seconds; writeJson(chainFile, chain);
+      const pace = t.rate > 1.005 ? `, ${Math.round((t.rate - 1) * 100)}% faster` : t.rate < 0.995 ? `, ${Math.round((1 - t.rate) * 100)}% slower` : '';
+      return { say: `${title(p)}: ${p.seconds} s${pace}`, part: p.dir };
     }
     case 'join': {
       const { JOINS } = await import('./chain.mjs'); if (!(a.value in JOINS)) throw new Error('bad transition');

package/lib/inventory.mjs

@@ -281,7 +281,14 @@ const lead = (b) => b.needs[0];
 // the shortest a scene can run in a chain: its land (where its last beat, the hold, begins) plus the time for the
 // hit to read; a scene that ends on something else keeps most of its length
 const LAND_HOLD = 0.6;
-const floorOf = (b) => { const d = b.duration ?? 5, last = b.beats?.at(-1); return +(last && /^hold$/i.test(last.name) ? Math.min(d, last.from + LAND_HOLD + 0.1) : d * 0.8).toFixed(1); };
+/**
+ * A part always plays its whole scene: a different length plays it faster or slower, never cut short and never
+ * looped. These are how far it may go, so motion still reads (too fast) and still moves (too slow).
+ */
+export const SPEED = { fast: 1.6, slow: 0.6 };
+/** The lengths a part may take, from its scene's own length: { natural, min, max } in seconds. */
+export const lengthRange = (natural) => ({ natural, min: Math.ceil((natural / SPEED.fast) * 10) / 10, max: Math.floor((natural / SPEED.slow) * 10) / 10 });
+const floorOf = (b) => lengthRange(b.duration ?? 5).min;   // as fast as it may play
 const fits = (need, it) => it.kind === need.kind && (need.has ?? []).every((f) => it[f] !== undefined && it[f] !== '') && Object.entries(need.where ?? {}).every(([k, v]) => it[k] === v);
 // an item that says otherwise ("device: phone" for a block that prefers desktop) goes to this block last
 const offKey = (need, it) => Object.entries(need.prefer ?? {}).some(([k, v]) => it[k] !== undefined && it[k] !== v);
@@ -411,9 +418,9 @@ export function propose(items, scenes, { seconds, brief = {} } = {}) {
   return options.map((o, i) => ({ letter: String.fromCharCode(65 + i), ...o }));
 }
 
-// Fits the beats to the length asked for. No beat runs shorter than its floor (its land must read), so a piece that
-// is too long loses its last beat that is not a must instead; what time is left over the floors is shared out. A
-// short piece stays short: a scene cannot run past its own length, and padding it would be a lie about the content.
+// Fits the beats to the length asked for. Every beat plays its whole scene, faster or slower: none faster than its
+// floor (SPEED.fast), so a piece that is too long loses its last beat that is not a must instead. A short piece plays
+// a little slower (up to a quarter), never more: padding it further would be a lie about the content.
 function timed(beats, target) {
   let list = beats.map((b) => ({ ...b })), notes = [];
   const sum = (k) => list.reduce((s, b) => s + b[k], 0);
@@ -425,8 +432,9 @@ function timed(beats, target) {
       notes.push(`dropped "${list[i].what}" to fit ${target} s`); list.splice(i, 1);
     }
     // share out what is left over the floors; a scene never runs past its own length, so a short piece stays short
-    const room = sum('duration') - sum('min'), k = target >= sum('duration') ? 1 : Math.max(0, (target - sum('min')) / (room || 1));
-    list.forEach((b) => { b.duration = +(b.min + (b.duration - b.min) * k).toFixed(1); });
+    const total = sum('duration'), room = total - sum('min');
+    if (target >= total) { const g = Math.min(1.25, target / (total || 1)); list.forEach((b) => { b.duration = +(b.duration * g).toFixed(1); }); }
+    else { const k = Math.max(0, (target - sum('min')) / (room || 1)); list.forEach((b) => { b.duration = +(b.min + (b.duration - b.min) * k).toFixed(1); }); }
     if (sum('duration') > target * 1.05) notes.push(`runs ${sum('duration').toFixed(1)} s, over the ${target} s asked: every beat left is a must and none can run shorter`);
     if (sum('duration') < target * 0.9) notes.push(`runs ${sum('duration').toFixed(1)} s of the ${target} s asked: there is no more material to show`);
   }

package/lib/render.mjs

@@ -94,12 +94,13 @@ export async function renderSfx({ url, out, from = 0, to }) {
   } finally { await browser.close(); }
 }
 
-async function sfxFromPage(s, { from = 0, to, out, normalize = true }) {
+async function sfxFromPage(s, { from = 0, to, rate = 1, length, out, normalize = true }) {
   const { cues, audio } = await s.page.evaluate(() => ({ cues: window.__pm.cues ?? [], audio: window.__pm.audio ?? {} }));
   if (!cues.length) return null;
   const end = to ?? s.config.duration;
-  const shifted = cues.filter((c) => c.t < end).map((c) => ({ ...c, t: c.t - from }));
-  writeWav(out, synthesize(shifted, { duration: end - from, ...audio, normalize }));
+  // a faster or slower part moves its hits with the picture; each sound keeps its own pitch and length
+  const shifted = cues.filter((c) => c.t < end).map((c) => ({ ...c, t: (c.t - from) / rate }));
+  writeWav(out, synthesize(shifted, { duration: length ?? (end - from) / rate, ...audio, normalize }));
   return { out, cues: cues.length };
 }
 
@@ -110,7 +111,7 @@ function subframes(f, fps, k, shutter, duration) {
   return Array.from({ length: k }, (_, j) => Math.min(duration - 1e-4, Math.max(0, (f + ((j + 0.5) / k - 0.5) * open) / fps)));
 }
 
-export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1, from, to, fps: fpsOverride, crf, audio, sfx = true, motionBlur = 1, shutter = 180, gifWidth = 720, gifFps = 24, onProgress }) {
+export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1, from, to, rate = 1, seconds, fps: fpsOverride, crf, audio, sfx = true, motionBlur = 1, shutter = 180, gifWidth = 720, gifFps = 24, onProgress }) {
   const fmt = FORMATS[format];
   if (!fmt) throw new Error(`Unknown format "${format}". Use one of: ${Object.keys(FORMATS).join(', ')}`);
   const browser = await launch();
@@ -120,9 +121,12 @@ export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1,
     const first = await openScene(browser, url, { dpr });
     const cfg = first.config;
     const fps = fpsOverride ?? cfg.fps;
+    // the scene's window [from, to], played at `rate` (scene seconds per second of video): 2 plays it twice as fast.
+    // `seconds` sets the video's length; past the window's end the last frame holds (under an overlapping join)
     const f0 = Math.round((from ?? 0) * fps);
     const f1 = Math.round((to ?? cfg.duration) * fps);
-    const total = f1 - f0;
+    const total = seconds !== undefined ? Math.round(seconds * fps) : Math.round((f1 - f0) / rate);
+    const sceneT = (st) => Math.min(f1 / fps - 1e-4, f0 / fps + st * rate);   // a time in the video → in the scene
     if (total <= 0) throw new Error('Nothing to render (check --from/--to).');
     const n = Math.max(1, Math.min(workers ?? Math.min(4, Math.max(1, Math.floor(os.cpus().length / 2))), Math.ceil(total / 15)));
     const chunk = Math.ceil(total / n);
@@ -131,7 +135,7 @@ export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1,
 
     let sfxWav = null;
     if (sfx && !fmt.gif && !fmt.seq) {
-      const r = await sfxFromPage(first, { from: f0 / fps, to: f1 / fps, out: path.join(tmp, 'sfx.wav'), normalize: !audio }); // with an external track, effects keep their own gains
+      const r = await sfxFromPage(first, { from: f0 / fps, to: f1 / fps, rate, length: total / fps, out: path.join(tmp, 'sfx.wav'), normalize: !audio }); // with an external track, effects keep their own gains
       sfxWav = r?.out ?? null;
     }
 
@@ -139,7 +143,7 @@ export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1,
     for (let i = 1; i < n; i++) sessions.push(await openScene(browser, url, { dpr }));
 
     const segments = await Promise.all(sessions.map(async (s, i) => {
-      const a = f0 + i * chunk, b = Math.min(f1, a + chunk);
+      const a = i * chunk, b = Math.min(total, a + chunk);
       if (a >= b) return null;
       const seg = path.join(tmp, `seg${String(i).padStart(3, '0')}.mkv`);
       // Lossless RGB intermediate; the final encode happens once, after concat.
@@ -148,8 +152,8 @@ export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1,
       const blur = k > 1 ? ['-vf', `tmix=frames=${k},select='eq(mod(n\\,${k})\\,${k - 1})',setpts=N/(${fps}*TB)`, '-r', String(fps)] : [];
       const p = ffmpeg(['-f', 'image2pipe', '-framerate', String(fps * k), '-c:v', 'png', '-i', '-', ...blur, '-c:v', 'libx264rgb', '-preset', 'ultrafast', '-crf', '0', seg], { stdin: true });
       for (let f = a; f < b; f++) {
-        for (const tt of subframes(f, fps, k, shutter, cfg.duration)) {
-          await s.seek(tt);
+        for (const st of subframes(f, fps, k, shutter, Infinity)) {
+          await s.seek(sceneT(st));
           await write(p, await s.capture());
         }
         done++; tick();

package/lib/studio.mjs

@@ -177,7 +177,7 @@ export function view(cwd, piece) {
     video: (() => {
       const v = videoView(cwd, dir, SCENES); if (!v) return null;
       const rel = path.relative(cwd, dir).split(path.sep).map(encodeURIComponent).join('/');
-      for (const x of v.parts) { x.live = LIVE ? `${LIVE}/${rel}/${encodeURIComponent(x.dir)}/scene.html?embed&v=${x.mtime}-${styleView(cwd).stamp}` : null; x.poster = preview(x.id, 'jpg'); x.clip = preview(x.id, 'webm');
+      for (const x of v.parts) { x.live = LIVE ? `${LIVE}/${rel}/${encodeURIComponent(x.dir)}/scene.html?embed&rate=${x.rate}&v=${x.mtime}-${styleView(cwd).stamp}` : null; x.poster = preview(x.id, 'jpg'); x.clip = preview(x.id, 'webm');
         if (x.motion) x.motion.demos = x.motion.options.map((o) => ({ value: o, title: TITLES.get(x.motion.previews[o]) ?? o, poster: x.motion.previews[o] ? preview(x.motion.previews[o], 'jpg') : null, clip: x.motion.previews[o] ? preview(x.motion.previews[o], 'webm') : null })); }
       return v;
     })(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paper-motion",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Frame-exact video renderer for HTML scenes built with Paper Shaders: the engine behind the paper-motion agent skills.",
   "keywords": [
     "video",

package/runtime/index.js

@@ -144,6 +144,13 @@ const imageCache = new Map();
 // A transparent pixel stands in for an image shader with no image (PaperTexture and Water also work standalone).
 const BLANK = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=';
 
+// A scene shown inside another page (?embed: the studio's live previews) draws its shaders at the size it is shown,
+// not at the frame's full size times the screen's density (8 million pixels a frame on a Retina screen for a box
+// 700 px wide). Renders never pass ?embed, so they keep every pixel.
+const EMBED_PIXELS = typeof location !== 'undefined' && /[?&]embed(?:[=&]|$)/.test(location.search)
+  ? Math.max(480 * 270, Math.round(innerWidth * innerHeight * Math.max(1, globalThis.devicePixelRatio ?? 1) ** 2))
+  : null;
+
 class ShaderLayer {
   /**
    * @param el       element the canvas fills (give it a size: e.g. position:absolute; inset:0)
@@ -177,7 +184,7 @@ class ShaderLayer {
       { preserveDrawingBuffer: true, ...(props.webGlContextAttributes ?? {}) },
       0, this.frame0,
       this.options.minPixelRatio ?? 2,
-      this.options.maxPixelCount ?? 3840 * 2160 * 2,
+      this.options.maxPixelCount ?? EMBED_PIXELS ?? 3840 * 2160 * 2,
       props.mipmaps,
     );
     if (this.options.loop) {
@@ -220,6 +227,8 @@ class ShaderLayer {
 
   seek(t) {
     if (!this.a) return;
+    // embedded, a layer no one can see (a later shot waiting at opacity 0, display none) is not drawn this frame
+    if (EMBED_PIXELS && this.el.checkVisibility && !this.el.checkVisibility({ opacityProperty: true, visibilityProperty: true })) return;
     const time = this.time ?? (t + (this.options.timeOffset ?? 0));
     const ms = (s) => this.frame0 + s * 1000 * this.speed;
     const L = this.options.loop;

package/runtime/player.js

@@ -5,8 +5,11 @@
 
 export function mountPlayer(scene, startT = 0) {
   const { stage, duration, fps } = scene;
-  const embed = new URLSearchParams(location.search).has('embed');
-  let t = startT, playing = true, loop = true, last = performance.now(), busy = false;
+  const q = new URLSearchParams(location.search), embed = q.has('embed');
+  // a part longer or shorter than its scene plays the whole scene slower or faster (the studio passes its rate)
+  const rate = Math.min(4, Math.max(0.25, Number(q.get('rate')) || 1));
+  // embedded, a scene plays once and holds its last frame (a click plays it again); on its own page it loops
+  let t = startT, playing = true, loop = !embed, last = performance.now(), busy = false;
 
   const bar = document.createElement('div');
   bar.innerHTML = `
@@ -45,10 +48,15 @@ export function mountPlayer(scene, startT = 0) {
   }
   function setPlaying(p) { playing = p; playBtn.textContent = p ? '❚❚' : '▶'; last = performance.now(); }
 
+  // embedded, it draws at most 30 frames a second: a preview beside an editor, not the render
+  const step = embed ? 1000 / 30 - 2 : 0;
+  let drawn = 0;
   function tick(now) {
+    if (embed && now - drawn < step) { requestAnimationFrame(tick); return; }
+    drawn = now;
     if (playing && !busy) {
-      let nt = t + (now - last) / 1000;
-      if (nt >= duration) { if (loop) nt %= duration; else { nt = duration; setPlaying(false); } }
+      let nt = t + ((now - last) / 1000) * rate;
+      if (nt >= duration) { if (loop) nt %= duration; else { nt = duration - 1 / fps; setPlaying(false); if (embed) { try { parent.postMessage({ pm: 'ended' }, '*'); } catch { /* no parent */ } } } }
       show(nt);
     }
     last = now;
@@ -57,6 +65,7 @@ export function mountPlayer(scene, startT = 0) {
   requestAnimationFrame(tick);
 
   playBtn.onclick = () => setPlaying(!playing);
+  if (embed) addEventListener('click', () => { if (!playing) show(0); setPlaying(true); });
   loopBtn.onclick = () => { loop = !loop; loopBtn.classList.toggle('on', loop); };
   range.oninput = () => { setPlaying(false); show(Number(range.value)); };
   addEventListener('keydown', (e) => {

package/studio/index.html

@@ -326,8 +326,8 @@ function inspHTML(p) {
     tune: `${p.tune.map((t) => t.kind === 'number'
         ? `<div class="slider"><div>${esc(t.label)}<em id="tv-${esc(t.name)}">${esc(t.value)}</em></div><input type="range" min="${t.min}" max="${t.max}" step="${t.step}" value="${esc(t.value)}" data-tune="${esc(t.name)}"></div>`
         : `<div class="fld">${esc(t.label)}<div class="seg">${t.options.map((o) => `<button class="btn sm${String(t.value) === String(o) ? ' on' : ''}" data-tunev="${esc(t.name)}" data-v="${esc(o)}">${esc(o)}</button>`).join('')}</div></div>`).join('')}
-      <div class="slider"><div>Length<em id="tv-seconds">${Number(p.seconds).toFixed(1)} s</em></div><input type="range" min="1.5" max="${Math.max(10, Math.ceil((p.duration ?? 6) * 1.6))}" step="0.1" value="${p.seconds}" data-seconds></div>
-      ${p.duration && p.seconds < p.duration * 0.7 ? '<p class="hint" style="color:var(--warn)">Shorter than this part needs to land: it may be cut.</p>' : ''}`,
+      <div class="slider"><div>Length<em id="tv-seconds">${Number(p.seconds).toFixed(1)} s</em></div><input type="range" min="${p.range.min}" max="${p.range.max}" step="0.1" value="${p.seconds}" data-seconds data-natural="${p.duration}"></div>
+      <p class="hint" id="tv-pace">${pace(p.seconds, p.duration)}</p>`,
   };
   return `<div class="lbl">Part ${n} of ${P.video.parts.length}</div><h2>${esc(p.title)}</h2><p class="hint sum">${esc(p.summary)}</p>
     <div class="tabs">${[['words', 'Words'], ['motion', 'Motion'], ['bg', 'Background'], ['tune', 'Tune']].map(([k, l]) => `<button class="${tab === k ? 'on' : ''}" data-tab="${k}">${l}</button>`).join('')}</div>
@@ -452,11 +452,18 @@ document.addEventListener('click', async (e) => {
 let sheetOpenAt = 0;
 const _open = openSheet; openSheet = (k, a) => { if (k === 'add') sheetOpenAt = a; _open(k, a); };
 function playAll() {
-  if (playing) { clearTimeout(playing); playing = null; render(); return; }
+  if (playing) { clearTimeout(playing); playing = null; onEnded = null; render(); return; }
   let i = 0; const parts = P.video.parts;
-  const next = () => { if (i >= parts.length || view !== 'video') { playing = null; render(); return; } sel = parts[i].dir; render(); playing = setTimeout(next, (parts[i++].seconds + 0.6) * 1000); };
+  // each part plays once in the player; the next one starts when it says it ended (or after its length, if it never does)
+  const next = () => {
+    clearTimeout(playing);
+    if (i >= parts.length || view !== 'video') { playing = null; onEnded = null; render(); return; }
+    sel = parts[i].dir; render(); onEnded = next; playing = setTimeout(next, (parts[i++].seconds + 3) * 1000);
+  };
   playing = 1; next();
 }
+let onEnded = null;
+addEventListener('message', (e) => { if (e.data?.pm === 'ended' && onEnded && e.source === $('player')?.querySelector('iframe')?.contentWindow) onEnded(); });
 document.addEventListener('change', (e) => {
   const d = e.target.dataset;
   if (d.word !== undefined) vact('word', { key: d.word, value: e.target.value });
@@ -464,7 +471,16 @@ document.addEventListener('change', (e) => {
   else if ('seconds' in d) vact('seconds', { value: e.target.value });
   else if (d.color) act({ type: 'style-color', key: d.color, value: e.target.value });
 });
-document.addEventListener('input', (e) => { const d = e.target.dataset; const k = d.tune ?? ('seconds' in d ? 'seconds' : null); if (k) { const o = $(`tv-${k}`); if (o) o.textContent = k === 'seconds' ? `${Number(e.target.value).toFixed(1)} s` : e.target.value; } });
+document.addEventListener('input', (e) => {
+  const d = e.target.dataset; const k = d.tune ?? ('seconds' in d ? 'seconds' : null); if (!k) return;
+  const o = $(`tv-${k}`); if (o) o.textContent = k === 'seconds' ? `${Number(e.target.value).toFixed(1)} s` : e.target.value;
+  if (k === 'seconds' && $('tv-pace')) $('tv-pace').textContent = pace(Number(e.target.value), Number(d.natural));
+});
+// a part always plays its whole scene: its length is a speed
+function pace(s, natural) {
+  const r = natural / s, pct = Math.round(Math.abs(r - 1) * 100);
+  return pct < 1 ? 'Plays its whole scene at its own speed.' : `Plays its whole scene ${pct}% ${r > 1 ? 'faster' : 'slower'}.`;
+}
 document.addEventListener('focusout', (e) => {
   const d = e.target.dataset ?? {}, v = e.target.isContentEditable ? e.target.innerText.trim() : null;
   if (d.brief && v !== P.brief[d.brief]) act({ type: 'brief', key: d.brief, value: v }, true);