storyshot 0.7.0 → 0.7.2

package/src/qwen_tts.py

@@ -2,7 +2,8 @@
 # storyshot's own venv (qwen-tts.mjs), one process per render: the model loads once for all lines.
 #
 # stdin:  {"repo", "revision", "temperature", "asr": {"repo", "revision"} | null,
-#          "lines": [{"text", "file", "voice", "lang", "seed"}]}
+#          "lines": [{"text", "written", "file", "voice", "lang", "seed"}]}
+#         (text: what the model reads; written: the line as the storyboard has it, before `pronounce`)
 # stderr: "line i/n <seconds>s [<tries> tries]" per line, plus whatever the libraries log
 # stdout: {"results": [{"seconds", "tries", "suspect", "heard", "mismatch"}], "asr": null | "why it didn't load"}
 #
@@ -15,6 +16,7 @@ import json
 import os
 import re
 import sys
+import unicodedata
 
 os.environ.setdefault('HF_HUB_DISABLE_TELEMETRY', '1')
 os.environ.setdefault('TRANSFORMERS_VERBOSITY', 'error')
@@ -72,12 +74,13 @@ def cn_number(m):
 
 
 def units(text, chinese, pinyin):
-    """The line as a list of sounds: pinyin syllables, digits, and Latin words as '#word' (m x and mx as '#m', '#x')."""
-    t = text.lower().replace('−', '-')
+    """The line as a list of sounds: pinyin syllables, digits, and Latin words as '#word' without accents
+    (m x and mx as '#m', '#x')."""
+    t = ''.join(c for c in unicodedata.normalize('NFD', text.lower().replace('−', '-')) if unicodedata.category(c) != 'Mn')
     if chinese:
         t = re.sub(r'\d+(?:\.\d+)?', cn_number, t)
     out = []
-    for tok in re.findall(r'[㐀-鿿]|[a-z]+|\d+', t):
+    for tok in re.findall(r'[㐀-鿿]|[^\W\d_㐀-鿿]+|\d+', t):  # Han one by one, words (with accents), numbers
         if chinese and re.match(r'[㐀-鿿]', tok):
             out += [{'liang': 'er'}.get(p, p) for p in pinyin(tok)]
         elif tok.isdigit():
@@ -92,6 +95,7 @@ def mismatch(text, heard, chinese, pinyin):
     text. A garbled take has a run of several; a homophone or a misheard letter is one on its own."""
     a, b = units(text, chinese, pinyin), units(heard, chinese, pinyin)
     letter = lambda u: len(u) == 2 and u[0] == '#'
+    glue = lambda us: ''.join(u.lstrip('#') for u in us)
     d = {(0, 0): (0, None)}
     for i in range(len(a) + 1):
         for j in range(len(b) + 1):
@@ -104,12 +108,18 @@ def mismatch(text, heard, chinese, pinyin):
                 ways.append((d[i, j - 1][0] + 1, (i, j - 1, 1)))
             if i and j:
                 x, y = a[i - 1], b[j - 1]
-                # a variable (m, b, x) the recognizer wrote as a character is half a mistake
-                cost = 0 if x == y else 0.5 if letter(x) or letter(y) else 1
+                # a variable (m, b, x) the recognizer wrote as a character, or a number word it wrote in digits
+                # (tres → 3), is half a mistake
+                cost = 0 if x == y else 0.5 if letter(x) or letter(y) or x.isdigit() != y.isdigit() else 1
                 ways.append((d[i - 1, j - 1][0] + cost, (i - 1, j - 1, cost)))
                 # a name in Latin letters in a Chinese line (Desmos) can come back as a few syllables: one mistake
                 if chinese and len(x) > 3 and x[0] == '#':
                     ways += [(d[i - 1, j - k][0] + 1, (i - 1, j - k, 1)) for k in range(2, min(5, j) + 1)]
+                # one word written as two or three (escribámosla / escribamos la): no mistake
+                if len(x) > 3 and x[0] == '#':
+                    ways += [(d[i - 1, j - k][0], (i - 1, j - k, 0)) for k in range(2, min(4, j) + 1) if glue(b[j - k:j]) == x[1:]]
+                if len(y) > 3 and y[0] == '#':
+                    ways += [(d[i - k, j - 1][0], (i - k, j - 1, 0)) for k in range(2, min(4, i) + 1) if glue(a[i - k:i]) == y[1:]]
             d[i, j] = min(ways, key=lambda w: w[0])
     i, j, run, worst = len(a), len(b), 0, 0
     while (i, j) != (0, 0):
@@ -144,15 +154,20 @@ def main():
         def hear(audio, line):
             """(what the recognizer heard, mismatch), or (None, None) for a line it can't check."""
             chinese = line['lang'] == 'chinese'
-            if asr is None or not (chinese or (line['lang'] == 'auto' and not re.search(r'[㐀-鿿]', line['text']))):
+            latin = {'english': 'English', 'spanish': 'Spanish', 'french': 'French', 'german': 'German', 'italian': 'Italian',
+                     'portuguese': 'Portuguese'}.get(line['lang'], 'English' if line['lang'] == 'auto' else None)
+            if asr is None or not (chinese or (latin and not re.search(r'[㐀-鿿]', line['text']))):
                 return None, None
             tmp = line['file'] + '.check.wav'
             write(tmp, audio, model.sample_rate)
             try:
-                heard = asr.generate(tmp, language='Chinese' if chinese else 'English').text.strip()
+                heard = asr.generate(tmp, language='Chinese' if chinese else latin).text.strip()
             finally:
                 os.remove(tmp)
-            return heard, mismatch(line['text'], heard, chinese, pinyin)
+            # against the line as written too: `pronounce` respells words for the voice (y → ye), and the
+            # recognizer writes what it hears the usual way
+            ms = [mismatch(t, heard, chinese, pinyin) for t in dict.fromkeys([line['text'], line.get('written') or line['text']])]
+            return heard, min(ms, key=lambda m: max(m[0] / RETRY_AT, m[1] / RETRY_RUN))
 
         results, n = [], len(job['lines'])
         for i, line in enumerate(job['lines']):

package/src/record.mjs

@@ -3,12 +3,12 @@
 import { chromium } from 'playwright';
 import fs from 'node:fs';
 import path from 'node:path';
-import { describePage } from './inspect.mjs';
+import { clickableKeys, describePage } from './inspect.mjs';
 import { detectLogin, loginAdvice, sessionContext } from './auth.mjs';
 import { certError } from './config.mjs';
 
 // Injected into every page: fake cursor, click ripple, smooth in-page anchor scrolling.
-function pageScript({ scrollOffset }) {
+export function pageScript({ scrollOffset }) {
   const install = () => {
     if (document.getElementById('__demo_cursor')) return;
     const c = document.createElement('div');
@@ -132,20 +132,59 @@ function pageScript({ scrollOffset }) {
     if (el && instant) el.remove();
     else if (el) { el.style.opacity = '0'; setTimeout(() => el.remove(), 300); }
   };
-  window.__demoKeys = (label) => {
+  // the key badge sits just below the cursor (above it near the bottom), where the action is: a zoom on
+  // that spot keeps it in the frame. Returns its box, so captions keep off it.
+  window.__demoKeys = (label, x = innerWidth / 2, y = innerHeight * 0.7) => {
     const el = document.createElement('div');
     el.textContent = label;
     Object.assign(el.style, {
-      position: 'fixed', left: '50%', bottom: '22%', transform: 'translateX(-50%)', zIndex: '2147483646', pointerEvents: 'none',
+      position: 'fixed', left: '0', top: '0', zIndex: '2147483646', pointerEvents: 'none', whiteSpace: 'nowrap',
       font: '600 30px -apple-system, "Segoe UI", sans-serif', color: '#fff', background: 'rgba(15,23,42,.88)',
       padding: '14px 26px', borderRadius: '14px', boxShadow: '0 10px 30px rgba(0,0,0,.3)', letterSpacing: '.04em',
     });
     document.documentElement.appendChild(el);
-    el.animate([{ opacity: 0, transform: 'translateX(-50%) scale(.9)' }, { opacity: 1, transform: 'translateX(-50%) scale(1)', offset: 0.15 },
+    const { width: w, height: h } = el.getBoundingClientRect();
+    const left = Math.max(16, Math.min(innerWidth - w - 16, x - w / 2));
+    const top = y + 48 + h < innerHeight - 16 ? y + 48 : Math.max(16, y - 40 - h);
+    Object.assign(el.style, { left: `${left}px`, top: `${top}px` });
+    el.animate([{ opacity: 0, transform: 'scale(.9)' }, { opacity: 1, transform: 'scale(1)', offset: 0.15 },
       { opacity: 1, offset: 0.8 }, { opacity: 0 }], { duration: 1400, easing: 'ease-out' }).onfinish = () => el.remove();
+    return { x: left, y: top, width: w, height: h };
   };
   // `mark`: a highlighter sweeps over a phrase (a text Range, even across inline elements) or an
   // element, line by line. Marks follow scrolling (positions are re-read every frame).
+  // What of a rect is really on screen: cut to the viewport and to every ancestor of `from` that clips
+  // its overflow (a panel scrolled past it, a collapsed section). scrollable: false cuts only to the
+  // clippers that can't scroll (what scrolling could never bring into view). null when nothing is left.
+  window.__demoClip = (q, from, { scrollable = true } = {}) => {
+    let { left, top, right, bottom } = q;
+    for (let a = from; a && a !== document.documentElement && a !== document.body; a = a.parentElement) {
+      const s = getComputedStyle(a);
+      const clips = s.overflowX !== 'visible' || s.overflowY !== 'visible', scrolls = /auto|scroll/.test(s.overflowX + s.overflowY);
+      if (clips && (scrollable || !scrolls)) {
+        const b = a.getBoundingClientRect();
+        left = Math.max(left, b.left); top = Math.max(top, b.top); right = Math.min(right, b.right); bottom = Math.min(bottom, b.bottom);
+      }
+      if (s.position === 'fixed') break; // a fixed element isn't clipped by what's around it
+    }
+    if (scrollable) { left = Math.max(left, 0); top = Math.max(top, 0); right = Math.min(right, innerWidth); bottom = Math.min(bottom, innerHeight); }
+    return right - left > 1 && bottom - top > 1 ? { left, top, right, bottom } : null;
+  };
+  // how a text range or element shows: 'shown' (on screen, nothing over it), 'away' (scrolling brings it
+  // into view), 'covered' (on screen, under something else) or 'hidden' (invisible, clipped, collapsed)
+  window.__demoShows = (src) => {
+    const el = src instanceof Range ? (src.commonAncestorContainer.nodeType === 1 ? src.commonAncestorContainer : src.commonAncestorContainer.parentElement) : src;
+    if (!el || getComputedStyle(el).visibility !== 'visible') return 'hidden';
+    for (let a = el; a; a = a.parentElement) if (+getComputedStyle(a).opacity < 0.05) return 'hidden';
+    const rects = [...(src instanceof Range ? src.getClientRects() : [src.getBoundingClientRect()])].filter((q) => q.width > 1 && q.height > 1);
+    const from = src instanceof Range ? el : el.parentElement;
+    if (!rects.some((q) => window.__demoClip(q, from, { scrollable: false }))) return 'hidden';
+    const seen = rects.map((q) => window.__demoClip(q, from)).filter(Boolean);
+    if (!seen.length) return 'away';
+    const q = seen.sort((a, b) => (b.right - b.left) * (b.bottom - b.top) - (a.right - a.left) * (a.bottom - a.top))[0];
+    const hit = document.elementFromPoint((q.left + q.right) / 2, (q.top + q.bottom) / 2);
+    return !hit || el.contains(hit) || hit.contains(el) && getComputedStyle(el).pointerEvents === 'none' || (!(src instanceof Range) && hit.contains(el)) ? 'shown' : 'covered';
+  };
   window.__demoFind = (phrase) => {
     const norm = (s) => s.replace(/\s+/g, ' ');
     const want = norm(phrase).trim();
@@ -168,27 +207,29 @@ function pageScript({ scrollOffset }) {
         const r = document.createRange();
         const [sn, so] = map[at], [en, eo] = map[at + needle.length - 1];
         r.setStart(sn, so); r.setEnd(en, eo + 1);
-        const rects = [...r.getClientRects()].filter((q) => q.width > 1 && q.height > 1);
-        if (rects.length) ranges.push(r);
+        // text the viewer can't see (hidden, clipped, collapsed, or a page's old view kept in the DOM) doesn't count
+        const shows = window.__demoShows(r);
+        if (shows !== 'hidden') ranges.push({ r, shows });
       }
       if (ranges.length) break;
     }
-    const inView = (r) => { const q = r.getBoundingClientRect(); return q.top >= 0 && q.bottom <= innerHeight; };
-    const r = ranges.find(inView) ?? ranges[0];
-    if (!r) return null;
-    window.__demoFound = r;
-    return { inView: inView(r), count: ranges.length };
+    // on screen first, then what a scroll brings into view, then what something covers right now
+    const found = ['shown', 'away', 'covered'].map((s) => ranges.find((x) => x.shows === s)).find(Boolean);
+    if (!found) return null;
+    window.__demoFound = found.r;
+    return { inView: found.shows === 'shown', count: ranges.length };
   };
   window.__demoMark = (what, { ms = 700, color, box = false }) => {
     const layer = document.getElementById('__demo_marks') ?? document.documentElement.appendChild(Object.assign(document.createElement('div'), { id: '__demo_marks' }));
     // multiply on the layer itself (its children are isolated inside it), so text under a mark stays readable
     Object.assign(layer.style, { position: 'fixed', inset: '0', zIndex: '2147483644', pointerEvents: 'none', transition: 'opacity .3s ease', mixBlendMode: 'multiply' });
     const src = what === 'found' ? window.__demoFound : window.__demoMarkEl;
+    const clipFrom = what === 'found' ? (src.commonAncestorContainer.nodeType === 1 ? src.commonAncestorContainer : src.commonAncestorContainer.parentElement) : src.parentElement;
     const rectsOf = () => {
-      const all = what === 'found' ? [...src.getClientRects()] : [src.getBoundingClientRect()];
+      const all = (what === 'found' ? [...src.getClientRects()] : [src.getBoundingClientRect()]).filter((q) => q.width > 1 && q.height > 1);
       // one rect per line: merge the pieces of inline elements that sit on the same line
       const lines = [];
-      for (const q of all.filter((q) => q.width > 1 && q.height > 1)) {
+      for (const q of all) {
         const l = lines.find((l) => Math.abs(l.top - q.top) < q.height * 0.5);
         if (l) { l.left = Math.min(l.left, q.left); l.right = Math.max(l.right, q.right); l.top = Math.min(l.top, q.top); l.bottom = Math.max(l.bottom, q.bottom); }
         else lines.push({ left: q.left, right: q.right, top: q.top, bottom: q.bottom });
@@ -209,17 +250,21 @@ function pageScript({ scrollOffset }) {
       delay += d;
       return el;
     });
+    // each line drawn only where it's on screen: text scrolled out of its panel (or out from under a
+    // header) loses its mark there instead of leaving it floating over whatever is now in that place
     const place = () => {
       if (!els[0]?.isConnected) return;
-      rectsOf().forEach((q, i) => {
-        const el = els[i]; if (!el) return;
-        const pad = box ? 6 : 2;
-        Object.assign(el.style, { left: `${q.left - pad}px`, top: `${q.top - (box ? pad : 0)}px`, width: `${q.right - q.left + 2 * pad}px`, height: `${q.bottom - q.top + (box ? 2 * pad : 0)}px` });
+      const now = rectsOf();
+      els.forEach((el, i) => {
+        const q = now[i] && window.__demoClip(now[i], clipFrom), pad = box ? 6 : 2;
+        if (!q) { el.style.display = 'none'; return; }
+        Object.assign(el.style, { display: '', left: `${q.left - pad}px`, top: `${q.top - (box ? pad : 0)}px`, width: `${q.right - q.left + 2 * pad}px`, height: `${q.bottom - q.top + (box ? 2 * pad : 0)}px` });
       });
       requestAnimationFrame(place);
     };
     place();
-    const u = first.reduce((a, q) => ({ x: Math.min(a.x, q.left), y: Math.min(a.y, q.top), r: Math.max(a.r, q.right), b: Math.max(a.b, q.bottom) }), { x: 1e9, y: 1e9, r: -1e9, b: -1e9 });
+    const shown = first.map((q) => window.__demoClip(q, clipFrom)).filter(Boolean);
+    const u = (shown.length ? shown : first).reduce((a, q) => ({ x: Math.min(a.x, q.left), y: Math.min(a.y, q.top), r: Math.max(a.r, q.right), b: Math.max(a.b, q.bottom) }), { x: 1e9, y: 1e9, r: -1e9, b: -1e9 });
     return { x: u.x, y: u.y, width: u.r - u.x, height: u.b - u.y };
   };
   // `note`: a short label with an arrow pointing at an element, placed on the side with the most room.
@@ -390,6 +435,8 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
   });
   const sleep = (ms) => page.waitForTimeout(ms);
   const now = () => Date.now() / 1000;
+  const warned = []; // also printed by inspect --after, whose log is silent
+  const warn = (m) => { warned.push(m); log(`  ⚠ ${m}`); };
 
   // --- cursor ---------------------------------------------------------------------
   let cur = { x: VW * 0.62, y: VH * 0.55 };
@@ -445,7 +492,13 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     const l = locate(page, spec);
     await waiting(() => l.waitFor({ state: 'visible', timeout }));
     await l.scrollIntoViewIfNeeded();
-    const b = await l.boundingBox();
+    let b = await l.boundingBox();
+    if (b && (b.x + b.width <= 0 || b.y + b.height <= 0)) {
+      // parked off screen, the way styled radios and checkboxes hide the real input: go to its label
+      const label = (await l.evaluateHandle((el) => [...(el.labels ?? [])].find((x) => { const r = x.getBoundingClientRect(); return r.width > 2 && r.height > 2 && r.right > 0; }) ?? null).catch(() => null))?.asElement();
+      if (label) { await label.scrollIntoViewIfNeeded().catch(() => {}); b = (await label.boundingBox()) ?? b; }
+      else warn(`${acting}: the target is off screen (at x=${Math.round(b.x)}, y=${Math.round(b.y)}) — the page hides it there; target what it shows instead (inspect lists it)`);
+    }
     boxes.set(keyOf(spec), b);
     marks.push({ t: now(), box: b });
     const o = opt.offset ?? { x: 0.5, y: 0.5 };
@@ -467,6 +520,10 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     return true;
   }
   const spotOff = (instant) => page.evaluate((i) => window.__demoSpotOff(i), !!instant).catch(() => {});
+  const keys = async (label) => {
+    const box = await page.evaluate(([l, x, y]) => window.__demoKeys(l, x, y), [label, cur.x, cur.y]).catch(() => null);
+    if (box) marks.push({ t: now(), box });
+  };
   const keyLabel = (k) => k.split('+').map((p) => ({ Meta: '⌘', ControlOrMeta: '⌘', Control: 'Ctrl', Shift: '⇧', Alt: '⌥', Enter: '↵ Enter', Escape: 'Esc', Backspace: '⌫', Tab: '⇥ Tab' })[p] ?? (p.length === 1 ? p.toUpperCase() : p)).join(' ');
 
   async function runAction(action) {
@@ -485,6 +542,16 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         const p = await pointOf(spec, opt);
         const lit = await spot(p.box, hl);
         await moveTo(p.x, p.y, opt.ms ?? cfg.pace.cursor);
+        if (!isPoint(spec)) {
+          const over = await locate(page, spec).evaluate((el, [x, y]) => {
+            const hit = document.elementFromPoint(x, y);
+            const label = el.closest('label') ?? [...(el.labels ?? [])].find((l) => l.contains(hit));
+            if (!hit || el.contains(hit) || hit.contains(el) || (label && label.contains(hit)) || el.getRootNode() !== document || hit.closest('[id^=__demo]')) return null;
+            const text = (hit.innerText ?? '').replace(/\s+/g, ' ').trim().slice(0, 50);
+            return hit.tagName.toLowerCase() + [...hit.classList].slice(0, 2).map((c) => `.${c}`).join('') + (text ? ` "${text}"` : '');
+          }, [p.x, p.y]).catch(() => null);
+          if (over) warn(`${acting}: ${over} is on top of the click target, so the click lands on it — close or hide it first (in setup: click its close button, or hide: <its css>)`);
+        }
         await sleep(lit ? 350 + cfg.pace.beat / 3 : 120);
         if (kind === 'dblclick') { clicks.push(now()); await page.mouse.dblclick(p.x, p.y); } else await press();
         if (lit) { await sleep(150); await spotOff(); }
@@ -505,7 +572,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
       }
       case 'dismiss': {
         const l = locate(page, spec);
-        if (await l.isVisible().catch(() => false)) { await l.click(); await sleep(400); }
+        if (await l.isVisible().catch(() => false)) { await l.click({ timeout: 10000 }); await sleep(400); }
         break;
       }
       case 'waitFor': await waiting(() => locate(page, spec).waitFor({ state: 'visible', timeout: opt.timeout ?? 180000 })); await settle(); await nudge(); break;
@@ -603,7 +670,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
           document.addEventListener('paste', (e) => { window.__demoPasted = !!e.clipboardData?.getData('text'); }, { capture: true, once: true });
           return true;
         }, () => false), text).catch(() => false);
-        if (!fast) await page.evaluate((l) => window.__demoKeys(l), process.platform === 'darwin' ? '⌘ V' : 'Ctrl V').catch(() => {});
+        if (!fast) await keys(process.platform === 'darwin' ? '⌘ V' : 'Ctrl V');
         if (copied) await page.keyboard.press('ControlOrMeta+V');
         await sleep(200);
         const pasted = copied && await page.evaluate(() => window.__demoPasted === true).catch(() => false);
@@ -655,7 +722,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
             }
             return v?.now;
           }, value.value).catch(() => null);
-          if (got != null && Math.abs(got - value.value) > 1e-9) log(`  ⚠ ${acting}: slide stopped at ${got}, not ${value.value} — the slider snaps to its step`);
+          if (got != null && Math.abs(got - value.value) > 1e-9) warn(`${acting}: slide stopped at ${got}, not ${value.value} — the slider snaps to its step`);
         }
         await settle();
         await beat();
@@ -696,8 +763,10 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         await l.evaluate((el) => { window.__demoMarkEl = el; });
         const box = await page.evaluate(([t, o]) => window.__demoNote(t, o), [String(value.text), { side: value.side, ink: cfg.theme.ink, accent: cfg.theme.accent }]);
         marks.push({ t: now(), box });
-        // reading time: about 3 words per second, at least a second
-        const read = fast ? 0 : value.ms ?? Math.max(1000, String(value.text).split(/\s+/).length * 330);
+        // reading time: about 3 words a second, or 5 Chinese/Japanese/Korean characters; at least a second
+        const t = String(value.text), cjk = /[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g;
+        const words = t.replace(cjk, ' ').split(/\s+/).filter(Boolean).length, chars = (t.match(cjk) ?? []).length;
+        const read = fast ? 0 : value.ms ?? Math.max(1000, words * 330 + chars * 200);
         holds += read / 1000;
         await sleep(read);
         break;
@@ -706,7 +775,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         const key = typeof value === 'object' ? value.key : String(value);
         // on-screen key badge: shortcuts and special keys only (not plain characters), when highlighting
         const show = value?.show ?? (hl && (key.includes('+') || key.length > 1));
-        if (show && !fast) await page.evaluate((l) => window.__demoKeys(l), keyLabel(key)).catch(() => {});
+        if (show && !fast) await keys(keyLabel(key));
         await page.keyboard.press(key);
         await sleep(200);
         if (key === 'Enter') { await settle(); await beat(); }
@@ -751,10 +820,14 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         const lw = await detectLogin(page).catch(() => ({})), loginWall = lw.wall ? lw.reason : null;
         if (desc) fs.writeFileSync(pageFile, desc.text);
         await browser.close().catch(() => {});
+        // Playwright's call log says when another element takes the click (a modal, a banner, an overlay)
+        const blocker = e.message.replace(/\u001b\[\d+m/g, '').match(/\n\s*-\s*(?:<[^\n]*?> from )?(<[^\n]*?>)(?: subtree)? intercepts pointer events/)?.[1];
         const err = new Error(`${where}, action ${j + 1} (${kind}: ${JSON.stringify(value)}) failed: ` +
-          `${e.message.split('\n')[0]}${matches}\n  page: ${page.url()}\n  screenshot of the moment it failed: ${shot}` +
+          `${e.message.split('\n')[0]}${matches}` +
+          (blocker ? `\n  another element is on top of it and takes the click: ${blocker.slice(0, 200)} — close it first (click its button, or hide: it in setup)` : '') +
+          `\n  page: ${page.url()}\n  screenshot of the moment it failed: ${shot}` +
           (loginWall ? `\n  ⚠ the page is asking to log in (${loginWall}) — ${cfg.storageState ? 'the saved session has probably expired; run login again' : loginAdvice(cfg.url)}` : '') +
-          (desc ? `\n  targets on the page at that moment: ${pageFile}` : ''));
+          (desc ? (fast ? `\n\nThe page at that moment:\n${desc.text}` : `\n  targets on the page at that moment: ${pageFile}`) : ''));
         err.screenshot = shot;
         err.pageDescription = desc?.text;
         throw err;
@@ -777,8 +850,11 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
   await runAll(cfg.setup, 'setup');
   for (const [card, file] of [[cfg.endCard, 'logo.png'], [cfg.intro, 'intro-logo.png']]) {
     if (!card?.logo || card.logoFile) continue;
-    await locate(page, card.logo).screenshot({ path: path.join(cfg.work, file), omitBackground: true, timeout: 5000 })
-      .catch((e) => log(`warning: could not capture logo (${e.message.split('\n')[0]})`));
+    await locate(page, card.logo).screenshot({ path: path.join(cfg.work, file), omitBackground: true, timeout: 5000 }).catch(async (e) => {
+      const all = locateAll(page, card.logo), n = await all.count().catch(() => 0), v = await all.filter({ visible: true }).count().catch(() => 0);
+      const why = !n ? 'nothing on the first page matches it' : !v ? `it matches ${n} element(s), none of them visible` : e.message.split('\n')[0];
+      log(`warning: could not capture the ${card === cfg.intro ? 'intro' : 'end card'} logo ${JSON.stringify(card.logo)}: ${why} — an inline <svg> logo is { css: "header a svg" } or similar, not an img; or give a logo file`);
+    });
   }
   // where the intro's logo sits on the first page: a HyperFrames launch intro lands its logo there
   const introLogo = cfg.intro?.logo && !cfg.intro.logoFile
@@ -818,8 +894,10 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
 
   if (fast) {
     const n = Math.min(inspectAfter, cfg.steps.length);
+    let before = null;
     for (const [i, s] of cfg.steps.slice(0, n).entries()) {
       stepHighlight = false;
+      if (i === n - 1) before = await clickableKeys(page);
       // like the recording: marks, notes and spotlights end with their step (the last step's stay in the screenshot)
       if (i > 0) await page.evaluate(() => { window.__demoUnmark(true); window.__demoUnnote(true); window.__demoSpotOff(true); }).catch(() => {});
       await runAll(s.actions, `step ${i + 1}`);
@@ -828,9 +906,9 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     await sleep(800);
     const shot = path.join(cfg.work, `inspect-after-${n}.jpg`);
     await page.screenshot({ path: shot, quality: 80, scale: 'css' });
-    const desc = await describePage(page, cfg.viewport);
+    const desc = await describePage(page, cfg.viewport, { before });
     await browser.close();
-    return { text: `State after ${n ? `step ${n}` : 'setup'} of ${cfg.name}:\n${desc.text}\n\nScreenshot: ${shot}`, screenshot: shot };
+    return { text: `State after ${n ? `step ${n}` : 'setup'} of ${cfg.name}:\n${warned.map((w) => `⚠ ${w}\n`).join('')}${desc.text}\n\nScreenshot: ${shot}`, screenshot: shot };
   }
 
   // --- recording ----------------------------------------------------------------------

package/src/voice.mjs

@@ -7,7 +7,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { isZhVoice, synthZh, zhSpeakText, ZH_DEFAULT_VOICE, ZH_TTS_ID } from './kokoro-zh.mjs';
-import { qwenSpeakText, QWEN_TTS_ID, synthQwen } from './qwen-tts.mjs';
+import { qwenLang, qwenSpeakText, QWEN_TTS_ID, synthQwen } from './qwen-tts.mjs';
 
 const SR = 48000;
 export const VOICE_DEFAULTS = {
@@ -112,10 +112,10 @@ function cached(cfg, line) {
   const zh = v.provider === 'kokoro' && isZhVoice(v.voice), qwen = v.provider === 'qwen';
   const text = zh ? zhSpeakText(pronounce(v, line)) : qwen ? qwenSpeakText(pronounce(v, line)) : pronounce(v, line);
   const ext = { kokoro: 'wav', qwen: 'wav', say: 'aiff' }[v.provider] ?? 'mp3';
-  const key = zh ? [v.provider, v.voice, ZH_TTS_ID, v.speed, text] : qwen ? [v.provider, v.voice, QWEN_TTS_ID, v.speed, text]
+  const key = zh ? [v.provider, v.voice, ZH_TTS_ID, v.speed, text] : qwen ? [v.provider, v.voice, QWEN_TTS_ID, v.speed, text, ...(qwenLang(text, v.lang) !== qwenLang(text) ? [qwenLang(text, v.lang)] : [])]
     : [v.provider, v.voice, v.model, v.speed, v.instructions, text];
   const hash = crypto.createHash('sha1').update(JSON.stringify(key)).digest('hex').slice(0, 16);
-  return { text, file: path.join(dir, `${hash}.${ext}`), zh, qwen };
+  return { text, written: line, file: path.join(dir, `${hash}.${ext}`), zh, qwen };
 }
 
 // A line's sentences, so each is spoken on its own with a pause after it (TTS engines run the
@@ -142,10 +142,10 @@ export function sentences(text) {
 // One line as stereo Float32 PCM at 48 kHz, leading and trailing silence trimmed.
 async function speakLine(cfg, line, log) {
   const v = cfg.voice;
-  const { text, file, zh, qwen } = cached(cfg, line);
+  const { text, written, file, zh, qwen } = cached(cfg, line);
   if (!fs.existsSync(file)) {
     if (zh) await synthZh(v, [{ text, file }], { log });
-    else if (qwen) await synthQwen(v, [{ text, file }], { log });
+    else if (qwen) await synthQwen(v, [{ text, written, file }], { log });
     else {
       log(`  tts (${v.provider}): "${text}"`);
       await synth(v, text, file);