storyshot 0.6.0 → 0.7.2

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');
@@ -55,19 +55,60 @@ function pageScript({ scrollOffset }) {
     for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) if (scrollable(p)) return p;
     return docEl();
   };
+  // `behavior: 'instant'` on every frame: with `scroll-behavior: smooth` in the page's CSS (GitHub has it),
+  // plain scrollTop writes each start a smooth scroll of their own, so the page lags behind and is still
+  // moving after the step that scrolled it is over
   window.__demoScrollBy = (dy, ms = 1200, sc = mainScroller()) => new Promise((done) => {
     const start = sc.scrollTop, t0 = performance.now();
     const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
     const step = (now) => {
-      const k = Math.min(1, (now - t0) / ms);
-      sc.scrollTop = start + dy * ease(k);
+      const k = ms > 0 ? Math.min(1, Math.max(0, (now - t0) / ms)) : 1;
+      sc.scrollTo({ top: start + dy * ease(k), behavior: 'instant' });
       if (k < 1) requestAnimationFrame(step); else done();
     };
     requestAnimationFrame(step);
   });
+  // How far down a header will cover the window once `el` is scrolled to the top: bars fixed at the top,
+  // and sticky ones that stick inside a box holding `el` (GitHub's README bar sticks within the README).
+  const headerCover = (el) => {
+    let cover = 0;
+    for (const h of document.querySelectorAll('body *')) {
+      if (h.getAttribute('id')?.startsWith('__demo') || h.contains(el)) continue; // not h.id: a form with an <input name=id> has that input as its .id
+      const cs = getComputedStyle(h);
+      if (cs.position !== 'fixed' && cs.position !== 'sticky') continue;
+      const r = h.getBoundingClientRect();
+      if (!r.height || r.height > innerHeight * 0.3 || r.width < innerWidth * 0.3 || cs.visibility === 'hidden' || cs.opacity === '0') continue;
+      if (cs.position === 'fixed' && r.top <= 1) cover = Math.max(cover, r.bottom);
+      const stick = parseFloat(cs.top);
+      if (cs.position === 'sticky' && !Number.isNaN(stick) && stick < innerHeight * 0.3 && h.parentElement?.contains(el)) cover = Math.max(cover, stick + r.height);
+    }
+    return cover;
+  };
+  // the element's top lands `scrollOffset` px down, or just below a header that would cover it there
   window.__demoScrollTo = (el, ms) => {
-    const sc = scrollerFor(el), top = sc === docEl() ? 0 : sc.getBoundingClientRect().top;
-    return window.__demoScrollBy(el.getBoundingClientRect().top - top - scrollOffset, ms, sc);
+    const sc = scrollerFor(el), docs = sc === docEl(), top = docs ? 0 : sc.getBoundingClientRect().top;
+    const offset = docs ? Math.max(scrollOffset, headerCover(el) + 12) : scrollOffset;
+    return window.__demoScrollBy(el.getBoundingClientRect().top - top - offset, ms, sc);
+  };
+  // resolves once nothing has scrolled for a few frames (the page's own smooth scrolling included)
+  window.__demoScrollIdle = (max = 2000) => new Promise((done) => {
+    const sc = mainScroller(), pos = () => `${scrollX},${scrollY},${sc.scrollTop}`;
+    const end = performance.now() + max;
+    let last = pos(), still = 0;
+    const check = () => {
+      const now = pos();
+      still = now === last ? still + 1 : 0; last = now;
+      if (still >= 3 || performance.now() > end) done(); else requestAnimationFrame(check);
+    };
+    requestAnimationFrame(check);
+  });
+  // a slider's value and range: an <input type=range>, or an ARIA slider (Desmos: [role=slider] on its knob)
+  window.__demoSliderValue = (el) => {
+    const r = el.type === 'range' ? el : el.querySelector?.('input[type=range]');
+    if (r) return { now: Number(r.value), lo: Number(r.min || 0), hi: Number(r.max || 100), native: r };
+    const aria = el.hasAttribute('aria-valuenow') ? el : el.querySelector?.('[aria-valuenow]');
+    const now = Number(aria?.getAttribute('aria-valuenow'));
+    return aria && Number.isFinite(now) ? { now, lo: Number(aria.getAttribute('aria-valuemin') ?? 0), hi: Number(aria.getAttribute('aria-valuemax') ?? 100) } : null;
   };
   // Tutorial callouts: spotlight a target, show a pressed key combo.
   window.__demoSpot = (r) => {
@@ -86,24 +127,64 @@ function pageScript({ scrollOffset }) {
     Object.assign(el.style, { left: `${r.x - pad}px`, top: `${r.y - pad}px`, width: `${r.width + 2 * pad}px`, height: `${r.height + 2 * pad}px` });
     requestAnimationFrame(() => { el.style.opacity = '1'; });
   };
-  window.__demoSpotOff = () => {
+  window.__demoSpotOff = (instant) => {
     const el = document.getElementById('__demo_spot');
-    if (el) { el.style.opacity = '0'; setTimeout(() => el.remove(), 300); }
+    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();
@@ -126,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 });
@@ -167,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.
@@ -348,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 };
@@ -403,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 };
@@ -424,7 +519,11 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     await sleep(280);
     return true;
   }
-  const spotOff = () => page.evaluate(() => window.__demoSpotOff()).catch(() => {});
+  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) {
@@ -443,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(); }
@@ -463,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;
@@ -473,6 +582,9 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
       case 'scrollTo': {
         const h = await locate(page, spec).elementHandle({ timeout: opt.timeout ?? 15000 });
         await page.evaluate(([el, ms]) => window.__demoScrollTo(el, ms), [h, opt.ms ?? 1200]);
+        // where it landed: a zoom on the same target frames it there, not where it was before the scroll
+        const b = await h.boundingBox().catch(() => null);
+        if (b) boxes.set(keyOf(spec), b);
         break;
       }
       case 'scroll': await page.evaluate(([dy, ms]) => window.__demoScrollBy(dy, ms), [value.y ?? value, value.ms ?? 1000]); break;
@@ -558,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);
@@ -570,25 +682,28 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
       }
       case 'slide': {
         // slide: { target: <slider>, to: 0.2 } — drag a slider to a position along its track (0 = start,
-        // 1 = end), found from the element instead of pixel positions that break when the layout moves
-        if (!value?.target || typeof value?.to !== 'number') throw new Error('slide needs { target: <slider>, to: 0..1 }');
+        // 1 = end), or { target, value: 3 } — to a value, for sliders that report their range; found from
+        // the element instead of pixel positions that break when the layout moves
+        if (!value?.target || (typeof value?.to !== 'number' && typeof value?.value !== 'number')) throw new Error('slide needs { target: <slider>, to: 0..1 } or { target: <slider>, value: <number> }');
         const p = await pointOf(value.target, value);
-        const b = p.box;
-        const from = await locate(page, value.target).evaluate((el) => {
-          const r = el.type === 'range' ? el : el.querySelector?.('input[type=range]');
-          if (r) return (Number(r.value) - Number(r.min || 0)) / ((Number(r.max || 100) - Number(r.min || 0)) || 1);
-          const aria = el.hasAttribute('aria-valuenow') ? el : el.querySelector?.('[aria-valuenow]');
-          if (aria) {
-            const now = Number(aria.getAttribute('aria-valuenow')), lo = Number(aria.getAttribute('aria-valuemin') ?? 0), hi = Number(aria.getAttribute('aria-valuemax') ?? 100);
-            if (Number.isFinite(now)) return (now - lo) / ((hi - lo) || 1);
+        const s = await locate(page, value.target).evaluate((el) => {
+          // a knob (Desmos's [role=slider] is its 38 px thumb): slide along its track, the nearest wide parent
+          let track = el;
+          const w = el.getBoundingClientRect().width;
+          for (let a = el.parentElement, i = 0; w < 60 && a && i < 4; a = a.parentElement, i++) if (a.getBoundingClientRect().width >= 3 * w) { track = a; break; }
+          const t = track.getBoundingClientRect(), v = window.__demoSliderValue(el);
+          let from = v ? (v.now - v.lo) / ((v.hi - v.lo) || 1) : null;
+          if (from == null) {
+            // custom sliders: start where the knob is drawn, so the value doesn't jump first
+            const knob = [...track.querySelectorAll('[role=slider], [class*=thumb], [class*=handle], [class*=knob]')]
+              .map((k) => k.getBoundingClientRect()).find((k) => k.width > 0 && k.width < t.width * 0.5);
+            from = knob ? (knob.x + knob.width / 2 - t.x) / (t.width || 1) : 0.5;
           }
-          // custom sliders (e.g. Desmos): start where the knob is drawn, so the value doesn't jump first
-          const t = el.getBoundingClientRect();
-          const knob = [...el.querySelectorAll('[role=slider], [class*=thumb], [class*=handle], [class*=knob]')]
-            .map((k) => k.getBoundingClientRect()).find((k) => k.width > 0 && k.width < t.width * 0.5);
-          return knob ? (knob.x + knob.width / 2 - t.x) / (t.width || 1) : 0.5;
-        }).catch(() => 0.5);
-        const x0 = b.x + b.width * from, x1 = b.x + b.width * Math.max(0, Math.min(1, value.to)), y = b.y + b.height / 2;
+          return { box: { x: t.x, y: t.y, width: t.width, height: t.height }, from, range: v && { lo: v.lo, hi: v.hi } };
+        }).catch(() => ({ box: p.box, from: 0.5, range: null }));
+        if (typeof value.value === 'number' && !s.range) throw new Error('slide value: this slider doesn\'t report its range (no aria-valuemin/max, not an <input type=range>) — use to: 0..1');
+        const to = typeof value.value === 'number' ? (value.value - s.range.lo) / ((s.range.hi - s.range.lo) || 1) : value.to;
+        const b = s.box, x0 = b.x + b.width * s.from, x1 = b.x + b.width * Math.max(0, Math.min(1, to)), y = b.y + b.height / 2;
         await moveTo(x0, y, value.ms ?? cfg.pace.cursor);
         await sleep(120);
         clicks.push(now());
@@ -596,6 +711,19 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         await moveTo(x1, y, value.dragMs ?? 900);
         await sleep(120);
         await page.mouse.up();
+        if (typeof value.value === 'number') {
+          // a native range's thumb doesn't reach the ends of its box, so the drag can land a step off: set it
+          const got = await locate(page, value.target).evaluate((el, want) => {
+            const v = window.__demoSliderValue(el), r = v?.native;
+            if (r && v.now !== want) {
+              Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set.call(r, String(want));
+              r.dispatchEvent(new Event('input', { bubbles: true })); r.dispatchEvent(new Event('change', { bubbles: true }));
+              return Number(r.value);
+            }
+            return v?.now;
+          }, value.value).catch(() => null);
+          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();
         break;
@@ -608,11 +736,9 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         let box = null;
         const phraseOnly = v.text && Object.keys(v).every((k) => ['text', 'exact'].includes(k));
         if (phraseOnly) {
+          await page.evaluate(() => window.__demoScrollIdle()).catch(() => {}); // judge "in view" where the page ends up
           const found = await page.evaluate((t) => window.__demoFind(t), v.text);
-          if (found && !found.inView) {
-            await page.evaluate((ms) => window.__demoScrollTo(window.__demoFound.startContainer.parentElement, ms), fast ? 0 : 900);
-            await sleep(fast ? 50 : 950);
-          }
+          if (found && !found.inView) await page.evaluate((ms) => window.__demoScrollTo(window.__demoFound.startContainer.parentElement, ms), fast ? 0 : 900);
           if (found) box = await page.evaluate(([ms, color, b]) => window.__demoMark('found', { ms, color, box: b }), [ms, color, opt.box ?? false]);
         }
         if (!box) {
@@ -637,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;
@@ -647,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(); }
@@ -659,7 +787,9 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
 
   // --- setup (not recorded) -----------------------------------------------------------
   // Run a list of actions; on failure, say exactly which one and save a screenshot.
+  let acting = '';
   async function runAll(actions, where) {
+    acting = where;
     for (const [j, a] of actions.entries()) {
       try {
         // watchdog: an action that hangs (a frozen page, a stalled browser) fails with a clear message
@@ -690,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;
@@ -716,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
@@ -757,18 +894,21 @@ 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;
-      // like the recording: marks and notes end with their step (the last step's stay in the screenshot)
-      if (i > 0) await page.evaluate(() => { window.__demoUnmark(); window.__demoUnnote(); }).catch(() => {});
+      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}`);
+      await page.evaluate(() => window.__demoScrollIdle()).catch(() => {});
     }
     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 ----------------------------------------------------------------------
@@ -804,10 +944,14 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     const zoomTarget = s.zoom?.target && !isPoint(s.zoom.target);
     const startBox = zoomTarget ? await boxNow() : null;
     await runAll(s.actions, `step ${i + 1}`);
+    // a scroll still running (the page's own smooth scrolling) ends in this step, not in the next one's first shot
+    await page.evaluate(() => window.__demoScrollIdle()).catch(() => {});
     const end = now(); // before clearing: a step that is held for its narration keeps its marks
-    await spotOff();
-    // docs clips start where the step starts: clear at once, so no fading callout leaks into the next clip
-    await page.evaluate((i) => { window.__demoUnmark(i); window.__demoUnnote(i); }, cfg.clips.length > 0).catch(() => {});
+    // docs clips start where the step starts, and a hidden step is cut: clear at once, so no fading
+    // callout leaks into the next shot
+    const instant = cfg.clips.length > 0 || !!s.hidden;
+    await spotOff(instant);
+    await page.evaluate((i) => { window.__demoUnmark(i); window.__demoUnnote(i); }, instant).catch(() => {});
     let zoomBox = null;
     if (s.zoom?.target) {
       if (isPoint(s.zoom.target)) {