storyshot 0.7.0 → 0.7.2

package/src/hyperframes.mjs

@@ -19,7 +19,6 @@ import { fileURLToPath } from 'node:url';
 
 export const HF_VERSION = '0.8.217';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
-const GSAP_CDN = 'https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js';
 // families HyperFrames resolves by name; any other needs an @font-face
 const BUNDLED = ['Inter', 'Montserrat', 'Outfit', 'Nunito', 'Oswald', 'League Gothic', 'Archivo Black', 'Space Mono', 'IBM Plex Mono', 'JetBrains Mono',
   'EB Garamond', 'Playfair Display', 'Source Code Pro', 'Noto Sans JP', 'Roboto', 'Open Sans', 'Lato', 'Poppins'];
@@ -112,13 +111,24 @@ export function cueTimes(items, say, start, len) {
 
 // --- shared bits -----------------------------------------------------------------------------------
 const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-// "**word** rest" -> one span per word (per character in CJK), highlighted words inside a .hl span
-const words = (text, { cls = 'w', underline = '' } = {}) => String(text ?? '').split(/(\*\*.+?\*\*)/).filter(Boolean).map((seg) => {
-  const hl = /^\*\*.+\*\*$/.test(seg);
-  const inner = seg.replace(/^\*\*|\*\*$/g, '').split(/(\s+)/).filter(Boolean).map((w) => (/^\s+$/.test(w) ? ' '
-    : CJK.test(w) ? [...w].map((ch) => `<span class="${cls}">${esc(ch)}</span>`).join('') : `<span class="${cls}">${esc(w)}</span>`)).join('');
-  return hl ? `<span class="hl">${inner}${underline}</span>` : inner;
-}).join('');
+// "**word** rest" -> one span per word (per character in CJK), highlighted words inside a .hl span.
+// Punctuation stays with its neighbour, so a wrapped line never starts with "，" or ends with "（".
+const CLOSE = '，。、；：！？）」』》〉】”’,.;:!?)…', OPEN = '（「『《〈【“‘(';
+const words = (text, { cls = 'w', underline = '' } = {}) => {
+  const span = (t) => `<span class="${cls}">${esc(t)}</span>`;
+  const chars = (w) => [...w].reduce((out, ch) => (out.length && (CLOSE.includes(ch) || OPEN.includes(out.at(-1).at(-1))) ? [...out.slice(0, -1), out.at(-1) + ch] : [...out, ch]), []);
+  const parts = [];
+  for (const seg of String(text ?? '').split(/(\*\*.+?\*\*)/).filter(Boolean)) {
+    const hl = /^\*\*.+\*\*$/.test(seg);
+    let body = seg.replace(/^\*\*|\*\*$/g, ''), lead = '';
+    while (!hl && parts.at(-1)?.hl && CLOSE.includes(body[lead.length] ?? '\0')) lead += body[lead.length];
+    body = body.slice(lead.length);
+    if (lead) parts.at(-1).html = `<span style="white-space:nowrap">${parts.at(-1).html}${span(lead)}</span>`; // "**实时预览**，"
+    const inner = body.split(/(\s+)/).filter(Boolean).map((w) => (/^\s+$/.test(w) ? ' ' : CJK.test(w) ? chars(w).map(span).join('') : span(w))).join('');
+    parts.push({ hl, html: hl ? `<span class="hl">${inner}${underline}</span>` : inner });
+  }
+  return parts.map((x) => x.html).join('');
+};
 const md = (s) => esc(s).replace(/\*\*(.+?)\*\*/g, '<b>$1</b>').replace(/`(.+?)`/g, '<code>$1</code>');
 const isCmd = (cta) => /^\$?\s*(npx|npm|pnpm|yarn|bun|pip|pipx|uv|brew|curl|git|docker|cargo|go)\b/.test(String(cta ?? ''));
 const lum = (hex) => { const m = /^#?([0-9a-f]{6})$/i.exec(hex ?? ''); if (!m) return 0.5; const n = parseInt(m[1], 16); return (0.299 * (n >> 16) + 0.587 * ((n >> 8) & 255) + 0.114 * (n & 255)) / 255; };
@@ -148,8 +158,82 @@ const fontFaces = (font, { hand = false } = {}) => [
   hand ? `@font-face{font-family:'Virgil';src:url('assets/Virgil.woff2') format('woff2')}` : '',
 ].join('\n');
 
-const doc = ({ W, H, D, css, body, js, bg = 'transparent', gsap }) => `<!doctype html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=${W}, height=${H}">
-<script src="${gsap}"></script>
+// The cards animate with the browser's own Web Animations API, which HyperFrames seeks frame by frame.
+// The templates describe their motion with GSAP-style calls (tl.fromTo / tl.to with duration, ease,
+// stagger); this small timeline collects them, then gives each element one animation per property that
+// spans the whole card, with keyframes at each tween's start and end, so tweens on the same element play
+// in time order however they were written. It runs in the card's page.
+function pageTimeline(D) {
+  const EASES = { none: 'linear', 'power1.out': 'cubic-bezier(0.5,1,0.89,1)', 'power1.inOut': 'cubic-bezier(0.45,0,0.55,1)',
+    'power2.in': 'cubic-bezier(0.32,0,0.67,0)', 'power2.out': 'cubic-bezier(0.33,1,0.68,1)', 'power2.inOut': 'cubic-bezier(0.65,0,0.35,1)',
+    'power3.inOut': 'cubic-bezier(0.76,0,0.24,1)', 'power4.out': 'cubic-bezier(0.22,1,0.36,1)', 'expo.out': 'cubic-bezier(0.16,1,0.3,1)' };
+  const easing = (e = 'power1.out') => {
+    if (EASES[e]) return EASES[e];
+    if (/^back\.out/.test(e)) return 'cubic-bezier(0.34,1.56,0.64,1)';
+    const steps = /^steps\((\d+)\)$/.exec(e);
+    return steps ? `steps(${steps[1]}, end)` : 'linear';
+  };
+  const TF = ['x', 'y', 'scale', 'scaleX', 'scaleY'];
+  const setTf = (s, p) => {
+    for (const [k, v] of Object.entries(p ?? {})) {
+      if (k === 'x' || k === 'y') s[k] = v;
+      else if (k === 'scale') s.sx = s.sy = v;
+      else if (k === 'scaleX') s.sx = v;
+      else if (k === 'scaleY') s.sy = v;
+    }
+    return s;
+  };
+  const tfText = (s) => `translate(${s.x}px, ${s.y}px) scale(${s.sx}, ${s.sy})`;
+  const tweens = [];
+  const add = (sel, from, to, at) => {
+    const { duration = 0.5, ease, stagger = 0, immediateRender, ...props } = to;
+    [...document.querySelectorAll(sel)].forEach((el, i) => tweens.push({ el, from, to: props, t0: at + i * stagger, d: duration, ease: easing(ease), n: tweens.length }));
+  };
+  const build = () => {
+    const byEl = new Map();
+    for (const t of tweens) byEl.set(t.el, [...(byEl.get(t.el) ?? []), t]);
+    for (const [el, list] of byEl) {
+      list.sort((a, b) => a.t0 - b.t0 || a.n - b.n);
+      const cs = getComputedStyle(el);
+      const state = { tf: { x: 0, y: 0, sx: 1, sy: 1 }, opacity: Number(cs.opacity), filter: cs.filter === 'none' ? 'blur(0px)' : cs.filter,
+        strokeDashoffset: parseFloat(cs.strokeDashoffset) || 0, backgroundSize: cs.backgroundSize, clipPath: cs.clipPath };
+      const tracks = {};
+      const push = (ch, t, v0, v1) => (tracks[ch] ??= []).push({ t0: t.t0, t1: t.t0 + t.d, v0, v1, e: t.ease });
+      for (const t of list) {
+        const keys = [...new Set([...Object.keys(t.from ?? {}), ...Object.keys(t.to)])];
+        if (keys.some((k) => TF.includes(k))) {
+          const a = setTf({ ...state.tf }, Object.fromEntries(Object.entries(t.from ?? {}).filter(([k]) => TF.includes(k))));
+          const b = setTf({ ...a }, Object.fromEntries(Object.entries(t.to).filter(([k]) => TF.includes(k))));
+          push('transform', t, tfText(a), tfText(b));
+          state.tf = b;
+        }
+        for (const k of keys.filter((k) => !TF.includes(k))) {
+          const v0 = t.from && k in t.from ? t.from[k] : state[k], v1 = k in t.to ? t.to[k] : v0;
+          push(k, t, v0, v1);
+          state[k] = v1;
+        }
+      }
+      const at = (t) => Math.min(1, Math.max(0, t / D));
+      for (const [ch, segs] of Object.entries(tracks)) {
+        const val = (v) => (ch === 'strokeDashoffset' ? `${v}px` : String(v));
+        const kf = [{ offset: 0, [ch]: val(segs[0].v0), easing: 'linear' }];
+        let last = segs[0].v0;
+        segs.forEach((s, i) => {
+          const end = i + 1 < segs.length ? Math.min(s.t1, Math.max(s.t0, segs[i + 1].t0)) : s.t1; // a later tween cuts it short
+          kf.push({ offset: at(s.t0), [ch]: val(last), easing: 'linear' }, { offset: at(s.t0), [ch]: val(s.v0), easing: s.e }, { offset: at(end), [ch]: val(s.v1), easing: 'linear' });
+          last = s.v1;
+        });
+        kf.push({ offset: 1, [ch]: val(last) });
+        const a = el.animate(kf, { duration: D * 1000, fill: 'both' });
+        a.pause();
+        a.currentTime = 0;
+      }
+    }
+  };
+  return { fromTo: (sel, from, to, at = 0) => add(sel, from, to, at), to: (sel, to, at = 0) => add(sel, null, to, at), build };
+}
+
+const doc = ({ W, H, D, css, body, js, bg = 'transparent' }) => `<!doctype html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=${W}, height=${H}">
 <style>
 *{margin:0;padding:0;box-sizing:border-box}
 html,body{width:${W}px;height:${H}px;overflow:hidden;background:${bg}}
@@ -163,11 +247,34 @@ ${css}
 ${body}
 </div></div>
 <script>
-const tl = gsap.timeline({ paused: true });
+const tl = (${pageTimeline})(${D.toFixed(3)});
 const blurIn = (sel, at, o = {}) => { if (document.querySelector(sel)) tl.fromTo(sel, { opacity: 0, filter: 'blur(8px)', ...o.from }, { opacity: 1, filter: 'blur(0px)', duration: o.d ?? 0.18, ease: 'power4.out', stagger: o.stagger ?? 0, ...o.to }, at); };
 const draw = (sel, at, d = 0.35, stagger = 0.12) => { if (document.querySelector(sel)) tl.fromTo(sel, { strokeDashoffset: 1 }, { strokeDashoffset: 0, duration: d, ease: 'power1.inOut', stagger }, at); };
+// text that would run out of the frame shrinks until it fits: w px wide and at most that many lines (0: a
+// row that doesn't wrap, only its width counts); then what's in [data-fit-box] shrinks together until it
+// fits top to bottom. Layout sizes only (offset*, scroll*): the animations' transforms don't count.
+const fits = [];
+const fit = (sel, w, lines = 2) => document.querySelectorAll(sel).forEach((el) => fits.push({ el, w, lines, size: parseFloat(getComputedStyle(el).fontSize) }));
+const over = ({ el, w, lines }) => {
+  const cs = getComputedStyle(el), lh = parseFloat(cs.lineHeight) || parseFloat(cs.fontSize) * 1.25;
+  // (a row that doesn't wrap overflows its own box: its scrollWidth, not its parent's, says so)
+  return Math.max(el.scrollWidth, el.offsetWidth, ...[...el.children].map((c) => c.scrollWidth)) > w + 1 || (lines > 0 && el.offsetHeight > lh * lines + parseFloat(cs.paddingTop) + parseFloat(cs.paddingBottom) + 4);
+};
+const shrink = (f) => { f.el.style.fontSize = parseFloat(f.el.style.fontSize) * 0.95 + 'px'; };
+const refit = () => {
+  for (const f of fits) { f.el.style.fontSize = f.size + 'px'; f.el.style.maxWidth = f.w + 'px'; }
+  for (const f of fits) for (let k = 0; k < 40 && over(f); k++) shrink(f);
+  const box = document.querySelector('[data-fit-box]');
+  for (let k = 0; box && fits.length && k < 30; k++) {
+    const kids = [...box.querySelectorAll(':scope > *, :scope > .right > *')].filter((c) => c.offsetHeight && !c.classList.contains('right'));
+    if (!kids.length || (Math.min(...kids.map((c) => c.offsetTop)) >= ${H * 0.03} && Math.max(...kids.map((c) => c.offsetTop + c.offsetHeight)) <= ${H * 0.97})) break;
+    fits.forEach(shrink);
+  }
+};
 ${js}
-window.__timelines["main"] = tl;
+refit();
+document.fonts?.ready.then(refit);
+tl.build();
 </script></body></html>`;
 
 // --- lesson: tutorials, courses, docs ---------------------------------------------------------------
@@ -228,7 +335,7 @@ function lesson(job, ctx) {
 .kick{font:600 ${30 * u}px 'IBM Plex Mono','StoryshotCJK',monospace;letter-spacing:.24em;text-transform:uppercase;color:${P.muted};margin-bottom:${22 * u}px}
 h1{font-weight:600;letter-spacing:-.03em;line-height:1.08;max-width:${W * 0.82}px;text-wrap:balance;font-size:${titleSize}px}
 .hl{position:relative;${dark ? `color:${accent}` : `background-image:linear-gradient(${accent},${accent});background-repeat:no-repeat;background-position:0 88%;background-size:0% 36%;padding:0 .06em`}}
-.sub{font-size:${44 * u}px;color:${P.muted};margin-top:${22 * u}px;letter-spacing:-.01em;max-width:${W * 0.8}px}
+.sub{font-size:${44 * u}px;line-height:1.3;text-wrap:balance;color:${P.muted};margin-top:${22 * u}px;letter-spacing:-.01em;max-width:${W * 0.8}px}
 .logo{height:${H * 0.09}px;margin-bottom:${36 * u}px;${dark ? `background:#fff;padding:${10 * u}px ${16 * u}px;border-radius:${14 * u}px` : ''}}
 .cimg{max-width:${W * 0.6}px;max-height:${H * 0.4}px;margin-top:${34 * u}px;border-radius:${12 * u}px;box-shadow:0 ${12 * u}px ${36 * u}px ${P.shadow}}
 .split{flex-direction:row;gap:${72 * u}px;text-align:left}
@@ -253,7 +360,7 @@ h1{font-weight:600;letter-spacing:-.03em;line-height:1.08;max-width:${W * 0.82}p
 .tx{font-size:${31 * u}px;line-height:1.24;font-weight:500}
 .tx b{color:${dark ? accent : P.text}}
 .tx code,.li code{font:500 .9em 'IBM Plex Mono',monospace}
-.cta{margin-top:${50 * u}px;font-size:${38 * u}px;font-weight:600;padding:${20 * u}px ${44 * u}px;border-radius:${16 * u}px;background:${dark ? accent : ink};color:${dark ? ink : '#fff'}}
+.cta{margin-top:${50 * u}px;font-size:${38 * u}px;line-height:1.3;font-weight:600;padding:${20 * u}px ${44 * u}px;border-radius:${16 * u}px;background:${dark ? accent : ink};color:${dark ? ink : '#fff'}}
 .cta.cmd{font:500 ${36 * u}px 'IBM Plex Mono',monospace;background:${dark ? '#1a2238' : ink};color:#e2e8f0;text-align:left}
 .cta.cmd b{color:${accent}}
 #type{display:inline-block;white-space:nowrap}
@@ -265,7 +372,7 @@ h1{font-weight:600;letter-spacing:-.03em;line-height:1.08;max-width:${W * 0.82}p
   const body = `<div class="full bg"></div>
 ${job.backdrop ? `<img id="backdrop" class="full backdrop" src="assets/backdrop.jpg">` : ''}
 ${bandText ? band('bandA', 96 * u, bandText) + band('bandB', H - 176 * u, [...bandText].reverse().join('')) : ''}
-<div class="col${split ? ' split' : ''}">
+<div class="col${split ? ' split' : ''}" data-fit-box>
   ${split ? `<div class="left">${image}</div><div class="right">` : ''}
   ${logo}${emblem}
   ${kicker ? `<div id="kick" class="kick">${esc(kicker)}</div>` : ''}
@@ -284,6 +391,11 @@ ${think}`;
 
   const n = (x) => x.toFixed(2);
   const js = `
+fit('#title', ${split ? W * 0.44 : W * 0.82}, 3);
+fit('#sub', ${split ? W * 0.44 : W * 0.8}, 3);
+fit('#aln', ${split ? W * 0.44 : W * 0.88}, 0);
+fit('.steps', ${W * 0.88}, 0);
+fit('#cta', ${split ? W * 0.44 : W * 0.8}, ${isCmd(c.cta) ? 0 : 2});
 ${bandText ? `tl.fromTo('#bandA', { x: 0 }, { x: ${-92 * D * u}, duration: ${D}, ease: 'none' }, 0);
 tl.fromTo('#bandB', { x: ${-900 * u} }, { x: ${-900 * u + 92 * D * u}, duration: ${D}, ease: 'none' }, 0);` : ''}
 ${job.backdrop ? `tl.fromTo('#backdrop', { x: 0 }, { x: ${-14 * D * u}, duration: ${D}, ease: 'none' }, 0);` : ''}
@@ -315,7 +427,7 @@ ${isCmd(c.cta) ? `tl.fromTo('#type', { clipPath: 'inset(0 100% 0 0)' }, { clipPa
 ${think ? `blurIn('#think', ${n(job.thinkAt)});
 tl.fromTo('#drain', { scaleX: 1 }, { scaleX: 0, duration: ${c.think}, ease: 'none' }, ${n(job.thinkAt)});` : ''}
 `;
-  return doc({ W, H, D, css, body, js, bg: P.ground, gsap: ctx.gsap });
+  return doc({ W, H, D, css, body, js, bg: P.ground });
 }
 
 // --- launch: promos ----------------------------------------------------------------------------------
@@ -334,7 +446,7 @@ async function launch(job, ctx) {
 #stage{font-family:'${font}','StoryshotCJK',sans-serif;color:${INK}}
 .paper{background:#fff}
 .grid{background-image:radial-gradient(#d4d4dc ${1.6 * u}px,transparent ${1.8 * u}px);background-size:${36 * u}px ${36 * u}px;background-position:${18 * u}px ${18 * u}px}
-.line{position:absolute;left:0;right:0;text-align:center;white-space:nowrap}
+.line{position:absolute;left:0;right:0;margin:0 auto;text-align:center;line-height:1.3;text-wrap:balance}
 .hl{position:relative;display:inline-block;color:${STROKE}}
 .ul{position:absolute;left:-4%;width:108%;bottom:-0.42em;height:0.5em;overflow:visible}
 .ulp{stroke-width:${6 * u}px}
@@ -346,8 +458,10 @@ async function launch(job, ctx) {
     const T = job.logoTarget; // where the app shows the same logo in its first frame, if it does
     const L = job.logoSize; // the logo picture's size in output px
     const hasLogo = !!(job.logo && L);
-    const big = hasLogo ? Math.min((W * 0.42) / L.w, (H * 0.17) / L.h, 3.2) : 1;
-    const cy = H * (c.subtitle ? 0.41 : 0.47);
+    // a logo and a title: the boxed logo, the title under it (leave out title when the logo spells the name)
+    const named = hasLogo && !!c.title, nameSize = (String(c.title ?? '').length > 24 ? 64 : 84) * u;
+    const big = hasLogo ? Math.min((W * 0.42) / L.w, (H * (named ? 0.15 : 0.17)) / L.h, 3.2) : 1;
+    const cy = H * (named ? (c.subtitle ? 0.355 : 0.4) : c.subtitle ? 0.41 : 0.47);
     const bw = hasLogo ? L.w * big : 0, bh = hasLogo ? L.h * big : 0, bx = (W - bw) / 2, by = cy - bh / 2;
     const exitAt = Math.max(1.4, D - 1.0), shrink = 0.68;
     const box = hasLogo ? strokes(g.rectangle(bx - 70 * u, by - 56 * u, bw + 140 * u, bh + 112 * u, R({ seed: 7, strokeWidth: 3.5 * u })), 'bx') : '';
@@ -357,8 +471,9 @@ async function launch(job, ctx) {
 #logo{position:absolute;left:${logoBox.x}px;top:${logoBox.y}px;width:${T ? T.w : bw}px;height:${T ? T.h : bh}px;transform-origin:0 0}
 #pageimg{object-fit:fill;opacity:0}
 .tbox{position:absolute;left:0;right:0;top:${cy - 80 * u}px;display:flex;justify-content:center}
-.tbox span.t{position:relative;display:inline-block;padding:${24 * u}px ${60 * u}px;font-size:${(String(c.title ?? '').length > 18 ? 96 : 128) * u}px}
-.tbox svg{position:absolute;inset:0;width:100%;height:100%;overflow:visible}`;
+.tbox span.t{position:relative;display:inline-block;line-height:1.2;white-space:nowrap;padding:${24 * u}px ${60 * u}px;font-size:${(String(c.title ?? '').length > 18 ? 96 : 128) * u}px}
+.tbox svg{position:absolute;inset:0;width:100%;height:100%;overflow:visible}
+#name{font-size:${nameSize}px}`;
     const tbox = !hasLogo && c.title ? `<div class="tbox" id="tbox"><span class="t title">${words(c.title)}<svg viewBox="0 0 1000 300" preserveAspectRatio="none">${strokes(g.rectangle(6, 8, 988, 284, R({ seed: 7 })), 'bx', 'vector-effect="non-scaling-stroke"')}</svg></span></div>` : '';
     const body = `
 ${F.frameBg ? `<img class="full" src="assets/frame-bg.png">` : `<div class="full" style="background:#0b1020"></div>`}
@@ -366,25 +481,30 @@ ${F.chrome ? `<img id="chrome" class="full" src="assets/frame-chrome.png" style=
 ${F.url ? `<img id="url" class="full" src="assets/frame-url.png" style="opacity:0">` : ''}
 <div id="paper" class="full paper"><div id="grid" class="full grid"></div>${job.page ? `<img id="pageimg" class="full" src="assets/page.jpg">` : ''}</div>
 ${hasLogo ? `<svg id="box" class="full" viewBox="0 0 ${W} ${H}">${box}</svg><img id="logo" src="assets/logo${path.extname(job.logo)}">` : tbox}
-${c.subtitle ? `<div id="sub" class="line" style="top:${(hasLogo ? by + bh + 120 * u : cy + 190 * u)}px;font-family:${handFont};font-size:${(opts.hand ? 78 : 64) * u}px">${words(c.subtitle, { underline: underline(11) })}</div>` : ''}`;
+${named ? `<div id="name" class="line title" style="top:${by + bh + 92 * u}px">${words(c.title)}</div>` : ''}
+${c.subtitle ? `<div id="sub" class="line" style="top:${(named ? by + bh + 92 * u + nameSize * 1.45 : hasLogo ? by + bh + 120 * u : cy + 190 * u)}px;font-family:${handFont};font-size:${(opts.hand ? 78 : 64) * u}px">${words(c.subtitle, { underline: underline(11) })}</div>` : ''}`;
     const sx = F.FW / W, sy = F.FH / H, framed = F.FX > 0 || F.FY > 0;
     const js = `
+fit('#tbox .t', ${W * 0.86}, 0);
+fit('#name', ${W * 0.86}, 1);
+fit('#sub', ${W * 0.84}, 2);
 ${hasLogo ? `draw('.bx', 0.0, 0.5, 0.18);
 tl.fromTo('#logo', { x: ${n(bx - logoBox.x)}, y: ${n(by - logoBox.y)}, scale: ${n(T ? (bw / T.w) * 0.92 : 0.92)}, opacity: 0, filter: 'blur(8px)' },
-  { x: ${n(bx - logoBox.x)}, y: ${n(by - logoBox.y)}, scale: ${n(T ? bw / T.w : 1)}, opacity: 1, filter: 'blur(0px)', duration: 0.45, ease: 'back.out(1.5)' }, 0.12);`
+  { x: ${n(bx - logoBox.x)}, y: ${n(by - logoBox.y)}, scale: ${n(T ? bw / T.w : 1)}, opacity: 1, filter: 'blur(0px)', duration: 0.45, ease: 'back.out(1.5)' }, 0.12);
+${named ? "blurIn('#name .w', 0.35, { d: 0.16, stagger: 0.07 });" : ''}`
     : `draw('.bx', 0.0, 0.5, 0.18);
 blurIn('#tbox .w', 0.12, { d: 0.16, stagger: 0.07 });`}
 blurIn('#sub .w', 0.5, { d: 0.16, stagger: 0.07 });
 draw('#sub .ulp', 1.0, 0.4, 0);
 // the paper turns into the app window; the logo lands where the app shows its own
-tl.to('#box, #sub, #grid, #tbox', { opacity: 0, filter: 'blur(6px)', duration: 0.22, ease: 'power2.in' }, ${n(exitAt)});
+tl.to('#box, #sub, #grid, #tbox${named ? ', #name' : ''}', { opacity: 0, filter: 'blur(6px)', duration: 0.22, ease: 'power2.in' }, ${n(exitAt)});
 ${framed ? `tl.to('#paper', { x: ${F.FX}, y: ${F.FY}, scaleX: ${sx.toFixed(5)}, scaleY: ${sy.toFixed(5)}, duration: ${shrink}, ease: 'power3.inOut' }, ${n(exitAt + 0.08)});` : ''}
 ${job.page ? `tl.fromTo('#pageimg', { opacity: 0 }, { opacity: 1, duration: 0.4, ease: 'power2.inOut' }, ${n(exitAt + 0.25)});` : ''}
 ${hasLogo ? (T ? `tl.to('#logo', { x: 0, y: 0, scale: 1, duration: ${shrink}, ease: 'power3.inOut' }, ${n(exitAt + 0.08)});`
       : `tl.to('#logo', { opacity: 0, filter: 'blur(6px)', duration: 0.22, ease: 'power2.in' }, ${n(exitAt)});`) : ''}
 ${F.chrome ? `tl.to('#chrome, #url', { opacity: 1, duration: 0.3, ease: 'power2.out' }, ${n(exitAt + 0.35)});` : ''}
 `;
-    return doc({ W, H, D, css, body, js, bg: '#fff', gsap: ctx.gsap });
+    return doc({ W, H, D, css, body, js, bg: '#fff' });
   }
 
   // the end card is drawn over the last frame, which storyshot zooms into the page underneath: the
@@ -401,12 +521,12 @@ ${F.chrome ? `tl.to('#chrome, #url', { opacity: 1, duration: 0.3, ease: 'power2.
   const css = `${css0}
 .stack{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center;text-align:center;gap:${30 * u}px}
 #logo{height:${lh}px;width:${lw}px}
-.etitle{font-size:${(String(c.title ?? '').length > 24 ? 80 : 104) * u}px}
-.esub{font-family:${handFont};font-size:${(opts.hand ? 66 : 54) * u}px}
+.etitle{font-size:${(String(c.title ?? '').length > 24 ? 80 : 104) * u}px;line-height:1.2;text-wrap:balance}
+.esub{font-family:${handFont};font-size:${(opts.hand ? 66 : 54) * u}px;line-height:1.3;text-wrap:balance}
 .blist{display:flex;flex-direction:column;gap:${12 * u}px;font-size:${36 * u}px;text-align:left}
 .blist .bi{display:flex;align-items:center;gap:${16 * u}px}
 .blist svg{width:${40 * u}px;height:${40 * u}px;overflow:visible}
-.cta{position:relative;margin-top:${26 * u}px;padding:${22 * u}px ${54 * u}px;font-family:${cmd ? "'IBM Plex Mono',monospace" : handFont};font-size:${(cmd ? 46 : opts.hand ? 84 : 64) * u}px;color:${STROKE};font-weight:${cmd ? 500 : 600}}
+.cta{position:relative;line-height:1.2;margin-top:${26 * u}px;padding:${22 * u}px ${54 * u}px;font-family:${cmd ? "'IBM Plex Mono',monospace" : handFont};font-size:${(cmd ? 46 : opts.hand ? 84 : 64) * u}px;color:${STROKE};font-weight:${cmd ? 500 : 600}}
 .cta .box{position:absolute;inset:0;width:100%;height:100%;overflow:visible}
 .cta .arrow{position:absolute;left:${-arrowW - 16 * u}px;top:calc(50% - ${24 * u}px);width:${arrowW}px;height:${arrowH}px;overflow:visible}
 .cta .try{position:absolute;right:calc(100% + ${arrowW - 10 * u}px);top:calc(50% + ${arrowH - 30 * u}px);font-family:'Virgil','StoryshotCJK',sans-serif;font-size:${46 * u}px;color:${INK};white-space:nowrap;transform:rotate(-7deg)}
@@ -414,7 +534,7 @@ ${F.chrome ? `tl.to('#chrome, #url', { opacity: 1, duration: 0.3, ease: 'power2.
   const check = (i) => strokes(g.linearPath([[4, 22], [15, 34], [36, 6]], R({ seed: 30 + i, stroke: STROKE, strokeWidth: 4 * u })), `ck${i}`);
   const body = `
 <div id="paper" class="full paper" style="opacity:0"></div>
-<div class="stack">
+<div class="stack" data-fit-box>
   ${hasLogo ? `<img id="logo" src="assets/logo${path.extname(job.logo)}">` : ''}
   ${c.title ? `<div id="etitle" class="etitle title">${words(c.title)}</div>` : ''}
   ${c.subtitle ? `<div id="esub" class="esub">${words(c.subtitle, { underline: underline(13) })}</div>` : ''}
@@ -424,7 +544,11 @@ ${F.chrome ? `tl.to('#chrome, #url', { opacity: 1, duration: 0.3, ease: 'power2.
     <svg class="arrow" viewBox="0 0 280 160" preserveAspectRatio="none">${strokes(g.curve([[18, 150], [60, 72], [150, 30], [270, 24]], R({ seed: 5, strokeWidth: 3.5 })), 'ar', 'vector-effect="non-scaling-stroke"')}${strokes(g.linearPath([[238, 0], [272, 24], [240, 50]], R({ seed: 6, strokeWidth: 3.5 })), 'ah', 'vector-effect="non-scaling-stroke"')}</svg>
     <div id="try" class="try">${esc(tryLabel)}</div></div>` : ''}
 </div>`;
+  // the call to action keeps room on its left for the hand-drawn arrow and its "try it"
   const js = `
+fit('#etitle', ${W * 0.84}, 2);
+fit('#esub', ${W * 0.8}, 2);
+fit('#cta', ${W - 2 * (arrowW + 240 * u)}, ${cmd ? 0 : 2});
 tl.fromTo('#paper', { opacity: 0 }, { opacity: 0.88, duration: 0.45, ease: 'power2.out' }, 0.3);
 ${hasLogo ? `tl.fromTo('#logo', { opacity: 0, y: ${14 * u}, filter: 'blur(8px)' }, { opacity: 1, y: 0, filter: 'blur(0px)', duration: 0.4, ease: 'expo.out' }, 0.5);` : ''}
 blurIn('#etitle .w', 0.5, { d: 0.16, stagger: 0.07 });
@@ -439,7 +563,7 @@ draw('.ar', ${n(ctaAt + 0.55)}, 0.4, 0.1);
 draw('.ah', ${n(ctaAt + 0.9)}, 0.2, 0.05);
 blurIn('#try', ${n(ctaAt + 0.85)}, { d: 0.25 });` : ''}
 `;
-  return doc({ W, H, D, css, body, js, bg: 'transparent', gsap: ctx.gsap });
+  return doc({ W, H, D, css, body, js, bg: 'transparent' });
 }
 
 // --- rendering ---------------------------------------------------------------------------------------
@@ -457,8 +581,6 @@ export async function renderHyperframesCards(jobs, ctx, { log = console.log, war
   if (!jobs.length) return {};
   let cli = hyperframesCli();
   if (cli.error) { warn(`hyperframes: ${cli.error} — using the built-in cards`); return {}; }
-  let gsapFile = null;
-  try { gsapFile = createRequire(import.meta.url).resolve('gsap/dist/gsap.min.js'); } catch { /* the CDN copy */ }
   const template = ctx.opts.template;
   const root = path.join(ctx.work, 'hf');
   fs.mkdirSync(root, { recursive: true });
@@ -470,10 +592,8 @@ export async function renderHyperframesCards(jobs, ctx, { log = console.log, war
       try { await import('roughjs'); } catch { warn('hyperframes: the launch template needs the roughjs package (npm i roughjs) — using the built-in cards'); return {}; }
     }
     const alpha = launchCard && job.kind === 'end';
-    const html = launchCard ? await launch(job, { ...ctx, gsap: gsapFile ? 'assets/gsap.min.js' : GSAP_CDN })
-      : lesson(job, { ...ctx, gsap: gsapFile ? 'assets/gsap.min.js' : GSAP_CDN });
+    const html = launchCard ? await launch(job, ctx) : lesson(job, ctx);
     const assets = {
-      ...(gsapFile ? { 'gsap.min.js': gsapFile } : {}),
       ...(launchCard ? { 'Virgil.woff2': path.join(HERE, 'fonts', 'Virgil.woff2') } : {}),
       ...(job.backdrop ? { 'backdrop.jpg': job.backdrop } : {}),
       ...(job.page ? { 'page.jpg': job.page } : {}),

package/src/init.mjs

@@ -7,11 +7,12 @@ import { PURPOSES, defaultStoryboard } from './config.mjs';
 import { loginAdvice } from './auth.mjs';
 
 const q = (s) => JSON.stringify(String(s));
-// The product's name from the page title: its first part ("Squoosh | Image compressor" → "Squoosh"),
+// The product's name from the page title: its first part ("Squoosh | Image compressor" → "Squoosh",
+// "Hoppscotch • Open source API development ecosystem • Hoppscotch" → "Hoppscotch"),
 // or the repo on a code host ("GitHub - boheling/storyshot: Ask…" → "storyshot"). Only spaced
 // separators split, so a hyphenated name (Tic-Tac-Toe) stays whole.
 export function productName(title, host) {
-  const segs = String(title ?? '').split(/\s+[|—–·-]\s+|:\s+/).map((s) => s.trim()).filter(Boolean);
+  const segs = String(title ?? '').split(/\s+[|｜—–·•∙‧-]\s+|:\s+/).map((s) => s.trim()).filter(Boolean);
   const repo = segs.find((s) => /^[\w.-]+ ?\/ ?[\w.-]+$/.test(s));
   return repo ? repo.split('/')[1].trim() : segs[0] ?? host;
 }

package/src/inspect.mjs

@@ -39,7 +39,19 @@ function collect() {
   const pos = (el) => {
     const r = el.getBoundingClientRect();
     return { x: Math.round(r.x + scrollX), y: Math.round(r.y + scrollTop), w: Math.round(r.width), h: Math.round(r.height),
-      cx: Math.round(r.x + r.width / 2), cy: Math.round(r.y + r.height / 2), css: cssOf(el) };
+      vx: Math.round(r.x), vy: Math.round(r.y), cx: Math.round(r.x + r.width / 2), cy: Math.round(r.y + r.height / 2), css: cssOf(el) };
+  };
+  // what to list first when there are more than inspect shows: an open dialog, menu or popover (0), what
+  // is on screen and not covered by something else (1), below the fold (2), covered (3)
+  const LAYER = 'dialog[open], [role=dialog], [role=alertdialog], [aria-modal=true], [role=menu], [role=listbox], [popover], [role=tooltip]';
+  const rank = (el) => {
+    if (el.closest(LAYER)) return 0;
+    const r = el.getBoundingClientRect(), x = r.x + r.width / 2, y = r.y + r.height / 2;
+    if (y < 0 || y > innerHeight || x < 0 || x > innerWidth) return 2;
+    const hit = document.elementFromPoint(x, y), label = el.closest('label');
+    // (inside a shadow root the hit is its host; storyshot's own cursor and highlights don't count)
+    const clear = !hit || el.contains(hit) || hit.contains(el) || (label && hit.closest('label') === label) || el.getRootNode() !== document || hit.closest('[id^=__demo]');
+    return clear ? 1 : 3;
   };
   const clean = (s) => (s || '').replace(/\s+/g, ' ').trim();
   // a short CSS selector (tag + classes, or #id) — the last-resort target when names don't resolve
@@ -80,15 +92,15 @@ function collect() {
     .filter((el) => (vis(el) || shownBy(el)) && el.tagName !== 'LABEL' && !isAd(el) && !(el.isContentEditable && el.parentElement?.isContentEditable))
     .map((el) => ({ kind: 'role', role: roleOf(el), name: (el.isContentEditable || el.tagName === 'TEXTAREA' ? editorName(el) : nameOf(el)).slice(0, 80), shows: clean(el.innerText).slice(0, 60), alt: clean(el.querySelector('img[alt]')?.alt) || null, href: el.getAttribute('href'), label: labelText(el.labels?.[0]),
       range: roleOf(el) === 'slider' ? sliderRange(el) : null,
-      options: el.tagName === 'SELECT' ? [...el.options].map((o) => ({ text: clean(o.text), on: o.selected })).filter((o) => o.text).slice(0, 12) : null, ...pos(shownBy(el) ?? el) }));
+      options: el.tagName === 'SELECT' ? [...el.options].map((o) => ({ text: clean(o.text), on: o.selected })).filter((o) => o.text).slice(0, 12) : null, rank: rank(shownBy(el) ?? el), ...pos(shownBy(el) ?? el) }));
   // custom clickables: outermost cursor:pointer elements that aren't native controls
   const pointer = [];
   for (const el of document.querySelectorAll('body *')) {
-    if (pointer.length >= 40) break;
+    if (pointer.length >= 60) break;
     if (el.closest(NATIVE) || el.querySelector(NATIVE) || !vis(el) || isAd(el)) continue;
     if (getComputedStyle(el).cursor !== 'pointer' || (el.parentElement && getComputedStyle(el.parentElement).cursor === 'pointer')) continue;
     const img = el.tagName === 'IMG' ? el : el.querySelector('img[alt]');
-    pointer.push({ kind: 'pointer', alt: img?.alt ? clean(img.alt).slice(0, 80) : null, name: clean(el.innerText).slice(0, 80), ...pos(el) });
+    pointer.push({ kind: 'pointer', alt: img?.alt ? clean(img.alt).slice(0, 80) : null, name: clean(el.innerText).slice(0, 80), rank: rank(el), ...pos(el) });
   }
   return {
     title: document.title,
@@ -105,24 +117,38 @@ function collect() {
 
 const yaml = (t) => (typeof t === 'string' ? JSON.stringify(t) : `{ ${Object.entries(t).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(', ')} }`);
 
+// What can be clicked right now, without verifying targets: `inspect --after N` compares the page before and
+// after step N, to list what the step opened first.
+const keyOf = (el) => `${el.kind}|${el.role ?? ''}|${el.name}|${el.css ?? ''}`;
+export async function clickableKeys(page) {
+  const info = await page.evaluate(collect).catch(() => null);
+  return info && new Set(info.interactive.map(keyOf));
+}
+
 // Describe the page as it is right now. Shared by `inspect` and failure diagnostics.
-export async function describePage(page, viewport, { maxElements = 80 } = {}) {
+// before: clickableKeys() of an earlier state; what is new since then is listed first and marked.
+export async function describePage(page, viewport, { maxElements = 150, before = null } = {}) {
   const info = await page.evaluate(collect);
-  const seen = new Set(), elements = [];
+  const seen = new Set(), targets = new Set(), elements = [];
   const verify = async (locator, spec, el) => {
     const visible = locator.filter({ visible: true });
     const n = await visible.count().catch(() => 0);
     if (n === 1) return spec;
     if (n > 1) {
-      // pick the match whose box is where we saw the element
-      const xs = await visible.evaluateAll((els) => els.map((e) => { const r = e.getBoundingClientRect(); return [Math.round(r.x), Math.round(r.y), Math.round(r.width)]; })).catch(() => []);
-      const k = xs.findIndex(([x, , w]) => Math.abs(x - el.x) <= 2 && Math.abs(w - el.w) <= 2);
-      if (k >= 0) return { ...spec, nth: k };
+      // pick the match whose box is where we saw the element (all four sides: a column of same-named
+      // buttons shares x and width)
+      const xs = await visible.evaluateAll((els) => els.map((e) => { const r = e.getBoundingClientRect(); return [r.x, r.y, r.width, r.height].map(Math.round); })).catch(() => []);
+      const at = xs.map(([x, y, w, h], k) => [k, Math.abs(x - el.vx) + Math.abs(y - el.vy) + Math.abs(w - el.w) + Math.abs(h - el.h)]).filter(([, d]) => d <= 4);
+      if (at.length === 1) return { ...spec, nth: at[0][0] };
     }
     return null;
   };
-  for (const el of info.interactive) {
-    if (elements.length >= maxElements) break;
+  const fresh = (el) => !!before && !before.has(keyOf(el));
+  // the most useful first (new since `before`, open dialogs and menus, on screen), then the page's order
+  const order = info.interactive.map((el, k) => ({ el, k })).sort((a, b) => (fresh(b.el) - fresh(a.el)) || (a.el.rank - b.el.rank) || (a.k - b.k));
+  let left = 0;
+  for (const { el, k } of order) {
+    if (elements.length >= maxElements) { left++; continue; }
     const key = `${el.role ?? el.alt}|${el.name}|${el.x}|${el.y}`;
     if (seen.has(key)) continue;
     seen.add(key);
@@ -143,8 +169,15 @@ export async function describePage(page, viewport, { maxElements = 80 } = {}) {
       if (!target && el.name) target = await verify(page.getByText(el.name, { exact: true }), { text: el.name, exact: true }, el);
     }
     if (!target && el.css) target = await verify(page.locator(el.css), { css: el.css }, el);
-    if (target) elements.push({ ...el, target });
+    // two elements given the same target would both click the first: list neither as verified
+    if (target && targets.has(JSON.stringify(target))) {
+      const dup = elements.findIndex((e) => JSON.stringify(e.target) === JSON.stringify(target));
+      if (dup >= 0) elements.splice(dup, 1);
+      continue;
+    }
+    if (target) { targets.add(JSON.stringify(target)); elements.push({ ...el, k, fresh: fresh(el), target }); }
   }
+  elements.sort((a, b) => a.k - b.k);
 
   const url = page.url(), origin = new URL(url).origin;
   const internal = [...new Set(info.interactive.filter((e) => e.href && !e.href.startsWith('#'))
@@ -168,7 +201,10 @@ export async function describePage(page, viewport, { maxElements = 80 } = {}) {
     '',
     '## Clickable elements — verified targets (each matches exactly one visible element) for click/move/zoom',
     '   Copy targets exactly; `name` is the accessible name, which may differ from the on-screen label.',
-    ...elements.map((e) => `${fold(e.y)} y=${e.y}\tat (${e.cx}, ${e.cy})\t${yaml(e.target)}${e.role === 'textbox' ? `  (text input ${e.w}×${e.h} — click it, then \`type: …\`)` : e.role === 'slider' ? (e.range ? `  (slider ${e.range.lo}…${e.range.hi}, now ${e.range.now} — \`slide: { target: …, value: ${e.range.now} }\`)` : '  (slider — `slide: { target: …, to: 0..1 }`)') : e.options ? `  (dropdown — \`select: { target: …, option: "…" }\`; options: ${e.options.map((o) => `"${o.text}"${o.on ? ' (selected)' : ''}`).join(', ')})` : shows(e)}${e.href ? `  → ${e.href}` : ''}${e.kind === 'pointer' ? '  (custom clickable)' : ''}`),
+    ...(before && elements.some((e) => e.fresh) ? ['   ★ = new since the step before (what this step opened)'] : []),
+    ...elements.map((e) => `${e.fresh ? '★' : fold(e.y)} y=${e.y}\tat (${e.cx}, ${e.cy})\t${yaml(e.target)}${e.role === 'textbox' ? `  (text input ${e.w}×${e.h} — click it, then \`type: …\`)` : e.role === 'slider' ? (e.range ? `  (slider ${e.range.lo}…${e.range.hi}, now ${e.range.now} — \`slide: { target: …, value: ${e.range.now} }\`)` : '  (slider — `slide: { target: …, to: 0..1 }`)') : e.options ? `  (dropdown — \`select: { target: …, option: "…" }\`; options: ${e.options.map((o) => `"${o.text}"${o.on ? ' (selected)' : ''}`).join(', ')})` : shows(e)}${e.href ? `  → ${e.href}` : ''}${e.kind === 'pointer' ? '  (custom clickable)' : ''}${e.rank === 3 ? '  (covered by something on top right now)' : ''}`),
+    ...(left ? [`… and ${left} more not listed (the first ${maxElements} are: ${before ? 'new ones, ' : ''}open dialogs and menus, then what's on screen). ` +
+      'For a panel or menu, open it with a step and run `inspect <storyboard> --after <that step>`; its elements are listed first.'] : []),
     '',
     '## Images with alt text (target: { alt: "..." })',
     ...(info.images.length ? info.images.map((i) => `${fold(i.y)} y=${i.y}\t"${i.alt}"`) : ['(none)']),
@@ -179,7 +215,7 @@ export async function describePage(page, viewport, { maxElements = 80 } = {}) {
   return { text: lines.join('\n'), height: info.height, title: info.title, url, headings: info.headings, anchors: info.anchors, elements };
 }
 
-export async function inspect(url, { viewport = { width: 1600, height: 900 }, storageState, ignoreHTTPSErrors = false, outDir = '.storyshot/inspect', maxElements = 80 } = {}) {
+export async function inspect(url, { viewport = { width: 1600, height: 900 }, storageState, ignoreHTTPSErrors = false, outDir = '.storyshot/inspect', maxElements = 150 } = {}) {
   const browser = await chromium.launch();
   const context = await sessionContext(browser, { viewport, storageState, ignoreHTTPSErrors });
   const page = await context.newPage();

package/src/qwen-tts.mjs

@@ -49,13 +49,16 @@ export function qwenSpeakText(text, lang = qwenLang(text)) {
   return t;
 }
 
-// The language the model is told: the script decides; Latin text is left to the model.
-export function qwenLang(text) {
+// The language the model is told: the script decides; a line in Latin letters gets the storyboard's
+// `lang` (es → spanish) when the model knows it, else it's left to the model.
+const LATIN_LANGS = { en: 'english', es: 'spanish', fr: 'french', de: 'german', it: 'italian', pt: 'portuguese' };
+export function qwenLang(text, lang) {
   const s = String(text).replace(/\d+(?:\.\d+)?(?:[eE][-−+]?\d+)?/g, ' '); // the e in 2e-105 is no English word
   if (/[぀-ヿ]/.test(s)) return 'japanese';
   if (/[가-힯]/.test(s)) return 'korean';
-  const han = (s.match(/[㐀-鿿]/g) ?? []).length, latin = (s.match(/[A-Za-z]+/g) ?? []).length;
-  return han > latin ? 'chinese' : 'auto';
+  if (/[А-яЁё]/.test(s)) return 'russian';
+  const han = (s.match(/[㐀-鿿]/g) ?? []).length, latin = (s.match(/[A-Za-zÀ-ÿ]+/g) ?? []).length;
+  return han > latin ? 'chinese' : LATIN_LANGS[String(lang ?? '').toLowerCase().split(/[-_]/)[0]] ?? 'auto';
 }
 
 // --- the venv ---------------------------------------------------------------------------------------
@@ -104,7 +107,8 @@ function ensureVenv(log) {
 }
 
 // --- synthesis --------------------------------------------------------------------------------------
-// entries: [{ text, file }] (text already through qwenSpeakText) → a WAV at each `file`.
+// entries: [{ text, written?, file }] (text already through qwenSpeakText; written: the line before
+// `pronounce`, which the take check also accepts) → a WAV at each `file`.
 export async function synthQwen(v, entries, { log = console.log } = {}) {
   if (!entries.length) return;
   if (!qwenSupported()) throw new Error('the Qwen3-TTS voice runs on Apple Silicon Macs only (it uses MLX)');
@@ -112,7 +116,7 @@ export async function synthQwen(v, entries, { log = console.log } = {}) {
   if (!fs.existsSync(MODEL_FILE)) log(`downloading the Qwen3-TTS model (one time, ~2.3 GB) into ${HUB}…`);
   if (!fs.existsSync(ASR_FILE)) log(`downloading the Qwen3-ASR model that listens to each take (one time, ~1 GB) into ${HUB}…`);
   const lines = entries.map((e) => ({
-    text: e.text, file: `${e.file}.raw.wav`, voice: v.voice, lang: qwenLang(e.text),
+    text: e.text, written: e.written ?? e.text, file: `${e.file}.raw.wav`, voice: v.voice, lang: qwenLang(e.text, v.lang),
     // the same line gets the same take: a seed from the text
     seed: parseInt(crypto.createHash('sha1').update(e.text).digest('hex').slice(0, 7), 16),
   }));