storyshot 0.6.0 → 0.7.2

package/src/config.mjs

@@ -31,10 +31,10 @@ export function loadEnv(dir) {
 
 // What the video is for sets sensible defaults; anything in the YAML overrides them.
 export const PURPOSES = {
-  pitch:    { duration: null,   music: { bpm: 120, volume: 1 },    sfx: true,  highlight: false, stepNumbers: false, subtitles: false, chapters: false, clips: null, frame: 'aurora', pace: 'fast', follow: false },
-  tutorial: { duration: 'auto', music: { bpm: 96, volume: 0.35 },  sfx: 'clicks', highlight: true,  stepNumbers: true,  subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true },
-  course:   { duration: 'auto', music: false,                     sfx: 'clicks', highlight: true,  stepNumbers: false, subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true },
-  docs:     { duration: 'auto', music: false,                     sfx: false, highlight: true,  stepNumbers: true,  subtitles: false, chapters: false, clips: ['gif', 'png'], frame: false, pace: 'normal', follow: false },
+  pitch:    { duration: null,   music: { bpm: 120, volume: 1 },    sfx: true,  highlight: false, stepNumbers: false, subtitles: false, chapters: false, clips: null, frame: 'aurora', pace: 'fast', follow: false, hyperframes: false },
+  tutorial: { duration: 'auto', music: { bpm: 96, volume: 0.35 },  sfx: 'clicks', highlight: true,  stepNumbers: true,  subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true, hyperframes: true },
+  course:   { duration: 'auto', music: false,                     sfx: 'clicks', highlight: true,  stepNumbers: false, subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true, hyperframes: true },
+  docs:     { duration: 'auto', music: false,                     sfx: false, highlight: true,  stepNumbers: true,  subtitles: false, chapters: false, clips: ['gif', 'png'], frame: false, pace: 'normal', follow: false, hyperframes: false },
 };
 
 // Where storyboards and their videos go, and how they're named: <site>-<kind>[-<topic>].yaml →
@@ -43,9 +43,10 @@ export const PURPOSES = {
 // follow each action and to read its result before the next one starts.
 export const PACES = {
   //        cursor ms  typing ms/char  beat after a click (ms)  hold after narration (s)  waits shown up to (s)  voice speed
-  fast:   { cursor: 700,  type: 55,  beat: 0,   tail: 0.4, maxWait: 1.0, voiceSpeed: 1 },
-  normal: { cursor: 900,  type: 70,  beat: 350, tail: 0.8, maxWait: 1.5, voiceSpeed: 1 },
-  slow:   { cursor: 1200, type: 95,  beat: 800, tail: 1.6, maxWait: 3.0, voiceSpeed: 0.92 },
+  //        shortest pause between the sentences of one line (s)
+  fast:   { cursor: 700,  type: 55,  beat: 0,   tail: 0.4, maxWait: 1.0, voiceSpeed: 1,    sentencePause: 0.3 },
+  normal: { cursor: 900,  type: 70,  beat: 350, tail: 0.8, maxWait: 1.5, voiceSpeed: 1,    sentencePause: 0.45 },
+  slow:   { cursor: 1200, type: 95,  beat: 800, tail: 1.6, maxWait: 3.0, voiceSpeed: 0.92, sentencePause: 0.6 },
 };
 
 export const FRAME_STYLES = ['aurora', 'studio', 'dark', 'pastel', 'blur'];
@@ -138,8 +139,9 @@ export function loadConfig(file, { draft = false } = {}) {
   if (frame?.icon) frame.iconFile = path.resolve(dir, frame.icon);
 
   // hyperframes: true | { template: lesson | launch, band, bandColors, emblem, hand, backdrop } — cards
-  // rendered by HyperFrames (see hyperframes.mjs); promos get the launch template, the rest the lesson one
-  const hf0 = raw.hyperframes;
+  // rendered by HyperFrames (see hyperframes.mjs); promos get the launch template, the rest the lesson one.
+  // On by default for tutorials and lessons, where Node can run it (22+); else the built-in cards
+  const hf0 = raw.hyperframes !== undefined ? raw.hyperframes : P.hyperframes && Number(process.versions.node.split('.')[0]) >= 22;
   const hyperframes = hf0 ? { template: purpose === 'pitch' ? 'launch' : 'lesson', backdrop: true, ...(typeof hf0 === 'object' ? hf0 : {}) } : null;
   if (hyperframes && !['lesson', 'launch'].includes(hyperframes.template)) throw new Error('hyperframes.template must be lesson or launch');
   if (hyperframes?.bandColors && !['aminoacid', 'nucleotide', 'accent'].includes(hyperframes.bandColors)) throw new Error('hyperframes.bandColors must be aminoacid, nucleotide or accent');
@@ -152,7 +154,8 @@ export function loadConfig(file, { draft = false } = {}) {
     // kokoro's and qwen's default voices follow the narration's language (zf_001 / serena for Chinese)
     const kokoroVoice = kokoroVoiceFor(raw);
     const byLang = { kokoro: kokoroVoice, qwen: qwenVoiceFor(raw) }[provider];
-    voice = { speed: pace0.voiceSpeed, volume: 1, ...VOICE_DEFAULTS[provider], ...(byLang ? { voice: byLang } : {}), ...raw.voice, provider };
+    voice = { speed: pace0.voiceSpeed, volume: 1, pause: pace0.sentencePause, ...VOICE_DEFAULTS[provider], ...(byLang ? { voice: byLang } : {}), ...(raw.lang ? { lang: raw.lang } : {}), ...raw.voice, provider };
+    if (!(typeof voice.pause === 'number' && voice.pause >= 0 && voice.pause <= 3)) throw new Error('voice.pause is the shortest pause between the sentences of a line, in seconds, 0–3 (0 leaves the voice as it is)');
     if (provider === 'qwen') {
       const v = qwenVoice(voice.voice);
       if (!v) throw new Error(`voice: qwen has no voice "${voice.voice}" (one of ${QWEN_VOICES.join(', ')})`);
@@ -214,8 +217,8 @@ export function loadConfig(file, { draft = false } = {}) {
     follow,
     music,
     voice,
-    // sfx: true (clicks and transition whooshes), 'clicks' (no whooshes: tutorials and lessons, where a
-    // sound at every card soon grates), or false
+    // sfx: true (clicks, transition whooshes and risers), 'clicks' (no whooshes or risers: tutorials and
+    // lessons, where a sound at every card soon grates), or false
     sfx: pick('sfx') === false ? false : { clicks: true, transitions: pick('sfx') !== 'clicks' },
     draft,
     out: path.resolve(dir, raw.out ?? `${name}.mp4`).replace(/(\.[^./]+)?$/, (ext) => (draft ? `.draft${ext || '.mp4'}` : ext)),

package/src/doctor.mjs

@@ -81,8 +81,8 @@ export async function doctor({ log = console.log } = {}) {
       : '· Chinese voice (kokoro zf_001) needs Python 3.10–3.12 — optional: brew install python@3.12, or uv python install 3.12 (or set STORYSHOT_PYTHON)');
   const q = qwenStatus();
   lines.push(!q.supported ? '· Qwen3-TTS voice (provider: qwen) needs an Apple Silicon Mac; storyboards that use it fall back to kokoro here'
-    : q.ready ? `✔ Qwen3-TTS voice (provider: qwen): venv in ${q.venv}${q.model ? ', model downloaded' : '; the model (~2.3 GB) downloads on first use'}`
-      : q.python ? `· Qwen3-TTS voice (provider: qwen): Python ${q.python.version} found; storyshot sets up its venv in ${q.venv} and downloads the model (~2.3 GB) on first use`
+    : q.ready ? `✔ Qwen3-TTS voice (provider: qwen): venv in ${q.venv}${q.model ? ', models downloaded' : '; the models (~3.3 GB: the voice, and a speech recognizer that checks each take) download on first use'}`
+      : q.python ? `· Qwen3-TTS voice (provider: qwen): Python ${q.python.version} found; storyshot sets up its venv in ${q.venv} and downloads the models (~3.3 GB) on first use`
         : '· Qwen3-TTS voice (provider: qwen) needs Python 3.10–3.12 — optional: brew install python@3.12, or uv python install 3.12 (or set STORYSHOT_PYTHON)');
   const hf = hyperframesCli();
   lines.push(hf.error ? `· HyperFrames cards (hyperframes: true) unavailable — optional: ${hf.error}`

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,6 +7,15 @@ 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",
+// "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 repo = segs.find((s) => /^[\w.-]+ ?\/ ?[\w.-]+$/.test(s));
+  return repo ? repo.split('/')[1].trim() : segs[0] ?? host;
+}
 const tgt = (t) => (typeof t === 'string' ? q(t) : `{ ${Object.entries(t).map(([k, v]) => `${k}: ${typeof v === 'string' ? q(v) : v}`).join(', ')} }`);
 
 export async function initStoryboard(url, { purpose = 'pitch', topic, file, storageState, ignoreHTTPSErrors = false, viewport = { width: 1600, height: 900 } } = {}) {
@@ -41,7 +50,7 @@ out: ${name}.mp4
 ${storageState ? `storageState: ${path.relative(path.dirname(path.resolve(file)), path.resolve(storageState)).split(path.sep).join('/')}   # saved login (never commit it)\n` : ''}${ignoreHTTPSErrors ? 'ignoreHTTPSErrors: true   # internal site with a self-signed certificate\n' : ''}${narrated ? 'voice: { provider: kokoro }        # free, local, English. For the final: { provider: elevenlabs, voice: <voice id> } + ELEVENLABS_API_KEY' : '# voice: { provider: kokoro }      # optional voiceover; add `say:` lines to steps'}
 
 ${purpose === 'pitch' ? `intro:                             # title card before the recording (promos; optional for tutorials/lessons)
-  title: ${q(page.title.split(/[|—–-]/)[0].trim() || host)}
+  title: ${q(productName(page.title, host))}
   subtitle: TODO the one-line promise, with the **key words** in bold
 ${PURPOSES[purpose]?.frame ? '# frame: false                     # the recording sits in a browser window on a backdrop; false = full frame\n' : ''}
 ` : purpose === 'tutorial' || purpose === 'course' ? `# intro: { title: TODO, subtitle: TODO }   # optional title card (e.g. "How to export a report")
@@ -65,7 +74,7 @@ steps:
   # run \`storyshot inspect ${file} --after <step>\` to list verified targets at that point.
 
 end_card:
-  title: ${q(page.title.split(/[|—–-]/)[0].trim() || host)}
+  title: ${q(productName(page.title, host))}
   cta: ${q(`Try it at ${host}`)}${narrated ? `\n  say: ${q(`Try it at ${host}.`)}` : ''}
 
 # ── Verified targets on ${page.url} (each matches exactly one visible element) ──