rpc-agent 0.4.0 → 0.6.0

package/dist/motion.js

@@ -0,0 +1,487 @@
+import { HELPERS } from './check-page.js';
+/** Final settle before a capture: quiet period and cap, in ms. */
+export const SETTLE_QUIET_MS = 150;
+export const SETTLE_CAP_MS = 2000;
+/** Per warm-up scroll step, and for all steps together. */
+export const STEP_QUIET_MS = 120;
+export const STEP_CAP_MS = 800;
+export const WARM_UP_BUDGET_MS = 8000;
+/**
+ * `__rpcSettle(quiet, cap, waapi)`: resolves when no `style`/`class`
+ * attribute on a visible element changed for `quiet` ms and (with `waapi`)
+ * no finite animation on the document timeline runs on a visible element,
+ * or at `cap` ms. Elements still changing or animating at the cap are
+ * remembered as loops (a JS marquee, a ticker, a long CSS animation) and
+ * don't hold up later calls on the same page.
+ *
+ * `waapi` false is for the last wait before a screenshot: Playwright's
+ * `animations: 'disabled'` already ends finite CSS and Web Animations in the
+ * image, so only JS-driven changes (GSAP-style tweens) can be caught mid-way.
+ */
+const SETTLE_FN = `
+  const __rpcSettle = async (quiet, cap, waapi = true) => {
+    const loops = (window.__rpcLoops = window.__rpcLoops || new WeakSet());
+    const start = performance.now();
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    const visible = el => {
+      if (!el || el.nodeType !== 1 || !el.isConnected) return false;
+      const r = el.getBoundingClientRect();
+      return r.width > 0 && r.height > 0 && r.bottom > 0 && r.right > 0 && r.top < vh && r.left < vw;
+    };
+    const changed = new Map();
+    let last = start;
+    const mo = new MutationObserver(list => {
+      const now = performance.now();
+      for (const m of list) {
+        if (!visible(m.target)) continue;
+        changed.set(m.target, now);
+        if (!loops.has(m.target)) last = now;
+      }
+    });
+    mo.observe(document.documentElement, { subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
+    const running = () => (waapi && document.getAnimations ? document.getAnimations() : []).filter(a => {
+      if (a.playState !== 'running' || loops.has(a.effect && a.effect.target) || (a.timeline && a.timeline !== document.timeline)) return false;
+      const t = a.effect && a.effect.getComputedTiming ? a.effect.getComputedTiming() : null;
+      return Boolean(t) && t.endTime !== Infinity && visible(a.effect.target);
+    });
+    let settled = false;
+    try {
+      for (;;) {
+        await new Promise(r => setTimeout(r, 30));
+        const now = performance.now();
+        if (now - last >= quiet && running().length === 0) { settled = true; break; }
+        if (now - start >= cap) break;
+      }
+    } finally {
+      mo.disconnect();
+    }
+    const now = performance.now();
+    const active = new Set(running().map(a => a.effect.target));
+    for (const [el, t] of changed) if (now - t < quiet && el.isConnected) active.add(el);
+    if (!settled) for (const el of active) loops.add(el);
+    return { settled, ms: Math.round(now - start), active: Array.from(active) };
+  };
+`;
+/** Settle at the current scroll position (see SETTLE_FN). */
+export const settleJs = (quiet = SETTLE_QUIET_MS, cap = SETTLE_CAP_MS, waapi = true) => `(async () => {
+  ${HELPERS}
+  ${SETTLE_FN}
+  const r = await __rpcSettle(${quiet}, ${cap}, ${waapi});
+  return { settled: r.settled, ms: r.ms, active: r.active.slice(0, 20).map(sel), count: r.active.length };
+})()`;
+/**
+ * Walk the page one viewport at a time so loading="lazy" images and
+ * IntersectionObserver-driven content render, settling at each step, then
+ * return to the top. Bounded to 100 steps and the full-page height cap; once
+ * the settle budget is spent, steps fall back to a fixed 100 ms pause.
+ */
+export const warmUpScrollJs = (maxHeight) => `(async () => {
+  ${SETTLE_FN}
+  const sleep = ms => new Promise(r => setTimeout(r, ms));
+  const root = document.scrollingElement || document.documentElement;
+  const step = Math.max(200, Math.floor(window.innerHeight * 0.9));
+  let spent = 0;
+  let steps = 0;
+  let settled = 0;
+  const pause = async () => {
+    steps++;
+    const left = ${WARM_UP_BUDGET_MS} - spent;
+    if (left < ${STEP_QUIET_MS}) return sleep(100);
+    const r = await __rpcSettle(${STEP_QUIET_MS}, Math.min(${STEP_CAP_MS}, left));
+    spent += r.ms;
+    if (r.settled) settled++;
+  };
+  for (let i = 0, y = 0; i < 100 && y < ${maxHeight}; i++, y += step) {
+    if (y > root.scrollHeight - window.innerHeight) break;
+    window.scrollTo({ top: y, behavior: 'instant' });
+    await pause();
+  }
+  window.scrollTo({ top: Math.min(root.scrollHeight, ${maxHeight}), behavior: 'instant' });
+  await pause();
+  window.scrollTo({ top: 0, behavior: 'instant' });
+  await sleep(150);
+  return { steps, settled, ms: Math.round(spent) };
+})()`;
+/**
+ * Pinned sections: `.pin-spacer` wrappers (GSAP ScrollTrigger), pins
+ * ScrollTrigger reports (when the pin is its parent's only child), and
+ * sticky or fixed sections (half a viewport or more) that are the only child of a parent at least half a viewport
+ * taller. Sets `pins` to `{ el, spacer, kind }`.
+ */
+const PINS_FN = `
+  const pins = [];
+  {
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    const taken = new Set();
+    const h = el => el.getBoundingClientRect().height;
+    const add = (el, spacer, kind) => {
+      if (taken.has(el) || !spacer || spacer === document.body || spacer === document.documentElement) return;
+      taken.add(el);
+      pins.push({ el, spacer, kind });
+    };
+    for (const sp of document.querySelectorAll('.pin-spacer')) {
+      const el = sp.firstElementChild;
+      if (el && h(sp) - h(el) >= vh / 4) add(el, sp, 'pin-spacer');
+    }
+    try {
+      const ST = window.ScrollTrigger;
+      if (ST && typeof ST.getAll === 'function') {
+        for (const st of ST.getAll()) {
+          const el = st && st.pin;
+          const parent = el && el.nodeType === 1 ? el.parentElement : null;
+          // Only a wrapper that holds just the pin: collapsing a shared parent (<main>) would move everything in it.
+          if (parent && parent.children.length === 1 && h(parent) - h(el) >= vh / 4) add(el, parent, 'scrolltrigger');
+        }
+      }
+    } catch (e) {}
+    for (const el of document.body ? document.body.querySelectorAll('*') : []) {
+      const cs = getComputedStyle(el);
+      if (cs.position !== 'sticky' && cs.position !== 'fixed') continue;
+      const r = el.getBoundingClientRect();
+      if (r.height < vh / 2 || r.width < vw / 2 || cs.visibility === 'hidden' || parseFloat(cs.opacity) < 0.1) continue;
+      const parent = el.parentElement;
+      if (!parent || parent.children.length !== 1) continue;
+      if (h(parent) - r.height >= vh / 2) add(el, parent, cs.position);
+    }
+  }
+`;
+/** Detect running animations, pins, hidden reveals and carousels. `scope` 'page' looks past the viewport. */
+export const motionJs = (scope) => `(async () => {
+  ${HELPERS}
+  ${PINS_FN}
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+  const wholePage = ${scope === 'page'};
+  const inScope = r => r.width > 0 && r.height > 0 && (wholePage || (r.bottom > -vh / 2 && r.top < vh * 1.5));
+  const rounded = (n, p) => Math.round(n * 10 ** p) / 10 ** p;
+
+  const finite = new Map();
+  const loops = new Map();
+  for (const a of document.getAnimations ? document.getAnimations() : []) {
+    if (a.playState !== 'running' || (a.timeline && a.timeline !== document.timeline)) continue;
+    const el = a.effect && a.effect.target;
+    if (!el || el.nodeType !== 1 || !inScope(el.getBoundingClientRect())) continue;
+    const t = a.effect.getComputedTiming();
+    const kind = a.animationName !== undefined ? 'CSS animation ' + a.animationName
+      : a.transitionProperty !== undefined ? 'CSS transition ' + a.transitionProperty
+      : 'Web Animation' + (a.id ? ' ' + a.id : '');
+    (t.endTime === Infinity ? loops : finite).set(el, kind);
+  }
+  const items = m => Array.from(m).slice(0, 20).map(([el, text]) => ({ selector: sel(el), text }));
+
+  const pinInfo = pins.map(p => ({
+    selector: sel(p.el),
+    spacer: sel(p.spacer),
+    kind: p.kind,
+    spacerHeight: Math.round(p.spacer.getBoundingClientRect().height),
+    height: Math.round(p.el.getBoundingClientRect().height),
+  }));
+
+  // Reveals: hidden or offset, and marked as animated content by a class,
+  // a data attribute or inline styles a library wrote. Class tokens are the
+  // reveal libraries' own (AOS, WOW, sal, animate.css) and plain reveal or
+  // fade names; generic words such as scroll, visible, motion or animate
+  // would match utility classes (overflow-x-scroll, motion-safe:, animate-spin).
+  const REVEAL_CLASS = /(^|[\\s_-])(reveal|reveals|fade|fade-in|fadein|aos|aos-init|aos-animate|appear|animated|inview|in-view|wow|sal|slide-in)([\\s_-]|$)/i;
+  const REVEAL_ATTRS = ['data-aos', 'data-sal', 'data-scroll', 'data-animate', 'data-animation', 'data-reveal', 'data-motion', 'data-inview', 'data-in-view', 'data-framer-appear-id'];
+  const LIB_STYLE = /opacity|transform|translate|scale|visibility/i;
+  // Carousel and slider tracks are moved by transforms on purpose; their offset is the current slide, not a reveal.
+  const LIBS = [['.swiper', 'Swiper'], ['.swiper-container', 'Swiper'], ['.embla', 'Embla'], ['.splide', 'Splide'], ['.keen-slider', 'Keen'], ['.flickity-enabled', 'Flickity'], ['.slick-slider', 'Slick'], ['.glide', 'Glide'], ['[aria-roledescription="carousel"]', 'carousel']];
+  const LIB_ROOTS = LIBS.map(([s]) => s).join(', ');
+  const isTrack = el => {
+    const p = el.parentElement;
+    return Boolean(p && p !== document.body && el.offsetWidth > p.clientWidth + 1 && getComputedStyle(p).overflowX !== 'visible');
+  };
+  // One axis of a translate, in px: percentages are of the element's own size.
+  const lengthPx = (v, size) => (v && v.endsWith('%') ? (parseFloat(v) / 100) * size : parseFloat(v) || 0);
+  // A translate of minus half the element's own size is centring (left: 50%; translate(-50%)), not an offset.
+  const offsetOf = (v, size) => (Math.abs(v + size / 2) <= 1 ? 0 : Math.abs(v));
+  const hidden = [];
+  const hiddenEls = [];
+  for (const el of document.body ? document.body.querySelectorAll('*') : []) {
+    if (hidden.length >= 20) break;
+    if (hiddenEls.some(h => h.contains(el))) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 8 || r.height < 8 || !inScope(r)) continue;
+    if (el.closest('[aria-hidden="true"], [inert], [hidden], dialog:not([open])')) continue;
+    const cs = getComputedStyle(el);
+    if (cs.position === 'fixed') continue;
+    if (el.closest(LIB_ROOTS)) continue;
+    const opacity = parseFloat(cs.opacity);
+    const m = cs.transform && cs.transform !== 'none' ? new DOMMatrixReadOnly(cs.transform) : null;
+    const w = el.offsetWidth || r.width;
+    const ht = el.offsetHeight || r.height;
+    const [tx, ty] = cs.translate && cs.translate !== 'none' ? cs.translate.split(/\\s+/) : [];
+    const dx = (m ? m.m41 : 0) + lengthPx(tx, w);
+    const dy = (m ? m.m42 : 0) + lengthPx(ty, ht);
+    const offset = isTrack(el) ? 0 : Math.max(offsetOf(dx, w), offsetOf(dy, ht));
+    let scale = m ? Math.hypot(m.a, m.b) : 1;
+    if (cs.scale && cs.scale !== 'none') scale = Math.min(scale, parseFloat(cs.scale) || 1);
+    const faded = opacity < 0.1 || cs.visibility === 'hidden';
+    const moved = offset >= 24 || scale < 0.85;
+    if (!faded && !moved) continue;
+    const media = /^(img|svg|video|canvas|picture)$/.test(el.localName) || el.querySelector('img, svg, video, canvas, picture');
+    if (!(el.textContent || '').trim() && !media) continue;
+    const cls = el.getAttribute('class') || '';
+    const why = REVEAL_CLASS.test(cls) ? 'reveal class' : REVEAL_ATTRS.some(a => el.hasAttribute(a)) ? 'reveal attribute' : LIB_STYLE.test(el.getAttribute('style') || '') ? 'inline style' : '';
+    if (!why) continue;
+    hiddenEls.push(el);
+    const state = faded ? (cs.visibility === 'hidden' ? 'visibility hidden' : 'opacity ' + rounded(opacity, 2)) : scale < 0.85 ? 'scale ' + rounded(scale, 2) : 'offset ' + Math.round(offset) + 'px';
+    hidden.push({ selector: sel(el), text: state + ' (' + why + ')', value: rounded(opacity, 2) });
+  }
+
+  // Carousels: library roots, horizontal scroll-snap, and tracks seen moving.
+  const found = new Map();
+  const note = (el, key, value) => found.set(el, Object.assign(found.get(el) || {}, { [key]: value }));
+  for (const [s, name] of LIBS) {
+    for (const el of document.querySelectorAll(s)) if (inScope(el.getBoundingClientRect())) note(el, 'lib', name);
+  }
+  const watch = [];
+  for (const el of document.body ? document.body.querySelectorAll('*') : []) {
+    if (watch.length >= 200) break;
+    const r = el.getBoundingClientRect();
+    if (r.width < 40 || r.height < 40 || !inScope(r)) continue;
+    const cs = getComputedStyle(el);
+    if (el.scrollWidth > el.clientWidth + 1 && cs.overflowX !== 'visible') {
+      watch.push({ el, root: el, scroller: true });
+      if (/x|inline|both/.test(cs.scrollSnapType || '')) note(el, 'snap', true);
+    }
+    const p = el.parentElement;
+    if (p && p !== document.body && r.width > p.clientWidth + 1 && getComputedStyle(p).overflowX !== 'visible') {
+      watch.push({ el, root: p, scroller: false });
+    }
+  }
+  const pos = w => (w.scroller ? String(w.el.scrollLeft) : getComputedStyle(w.el).transform + '|' + getComputedStyle(w.el).translate);
+  const before = watch.map(pos);
+  await new Promise(r => setTimeout(r, 300));
+  watch.forEach((w, i) => { if (pos(w) !== before[i]) note(w.root, 'moving', true); });
+  const roots = Array.from(found.keys());
+  const carousels = roots
+    .filter(el => !roots.some(o => o !== el && o.contains(el)))
+    .slice(0, 10)
+    .map(el => {
+      const f = found.get(el);
+      return { selector: sel(el), text: [f.lib, f.snap ? 'scroll-snap' : '', f.moving ? 'moving' : ''].filter(Boolean).join(', ') };
+    });
+
+  const libraries = [];
+  if (window.gsap) libraries.push('gsap');
+  if (window.ScrollTrigger) libraries.push('ScrollTrigger');
+  return { animations: { finite: items(finite), loops: items(loops) }, pins: pinInfo, hidden, carousels, libraries };
+})()`;
+/**
+ * --finish-animations: every finite Web Animation to its end, then GSAP
+ * when its globals are there. Scrubbed and pinned ScrollTriggers follow the
+ * scroll position, so they are left alone. Each library step is guarded.
+ */
+export const FINISH_JS = `(() => {
+  const out = { animations: 0, gsap: 0, scrollTriggers: 0 };
+  for (const a of document.getAnimations ? document.getAnimations() : []) {
+    try {
+      if (a.playState === 'finished' || (a.timeline && a.timeline !== document.timeline)) continue;
+      const t = a.effect && a.effect.getComputedTiming();
+      if (!t || t.endTime === Infinity) continue;
+      a.finish();
+      out.animations++;
+    } catch (e) {}
+  }
+  try {
+    const ST = window.ScrollTrigger;
+    if (ST && typeof ST.getAll === 'function') {
+      for (const st of ST.getAll()) {
+        try {
+          const v = (st && st.vars) || {};
+          if (v.scrub || v.pin || st.pin) continue;
+          const anim = st.animation;
+          if (anim && typeof anim.progress === 'function' && anim.progress() < 1) { anim.progress(1); out.scrollTriggers++; }
+        } catch (e) {}
+      }
+    }
+  } catch (e) {}
+  try {
+    const tl = window.gsap && window.gsap.globalTimeline;
+    if (tl && typeof tl.getChildren === 'function') {
+      for (const child of tl.getChildren(false, true, true)) {
+        try {
+          if (!child || child.scrollTrigger || typeof child.progress !== 'function') continue;
+          if ((typeof child.repeat === 'function' ? child.repeat() : 0) === -1) continue;
+          if (child.progress() < 1) { child.progress(1); out.gsap++; }
+        } catch (e) {}
+      }
+    }
+  } catch (e) {}
+  return out;
+})()`;
+/**
+ * Collapse each pin so the section shows once in a stitched shot. The rules
+ * are `!important` in a stylesheet, which beats the inline styles a library
+ * writes later (a ScrollTrigger refresh on the capture's resize).
+ */
+export const UNPIN_JS = `(() => {
+  ${HELPERS}
+  ${PINS_FN}
+  if (!pins.length) return [];
+  const height = el => el.getBoundingClientRect().height;
+  const before = pins.map(p => height(p.spacer));
+  if (!document.getElementById('rpc-unpin')) {
+    const style = document.createElement('style');
+    style.id = 'rpc-unpin';
+    style.textContent =
+      '[data-rpc-unpin="spacer"]{padding:0!important;height:auto!important;min-height:0!important;max-height:none!important}' +
+      '[data-rpc-unpin="pin"]{position:relative!important;top:auto!important;left:auto!important;right:auto!important;bottom:auto!important;transform:none!important;translate:none!important}' +
+      '[data-rpc-unpin="track"]{height:auto!important;min-height:0!important;padding-bottom:0!important}';
+    (document.head || document.documentElement).appendChild(style);
+  }
+  const out = pins.map(p => ({ selector: sel(p.el), spacer: sel(p.spacer), kind: p.kind }));
+  for (const p of pins) {
+    if (p.kind === 'sticky') {
+      p.spacer.setAttribute('data-rpc-unpin', 'track');
+    } else {
+      p.spacer.setAttribute('data-rpc-unpin', 'spacer');
+      p.el.setAttribute('data-rpc-unpin', 'pin');
+    }
+  }
+  return out.map((o, i) => ({ ...o, removed: Math.max(0, Math.round(before[i] - height(pins[i].spacer))) }));
+})()`;
+/**
+ * Wait for the page to stop moving. `waapi: false` ignores CSS and Web
+ * Animations (for the wait before a screenshot, which ends them itself).
+ */
+export async function settleMotion(page, quiet = SETTLE_QUIET_MS, cap = SETTLE_CAP_MS, { waapi = true } = {}) {
+    return (await page.evaluate(settleJs(quiet, cap, waapi)));
+}
+export async function detectMotion(page, scope) {
+    return (await page.evaluate(motionJs(scope)));
+}
+export async function finishAnimations(page) {
+    return (await page.evaluate(FINISH_JS));
+}
+export async function unpin(page) {
+    return (await page.evaluate(UNPIN_JS));
+}
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const STILL_FIX = 'Captures catch these mid-way. Use rpc shot --finish-animations to jump them to their end state, --wait <ms> to give ' +
+    'them time, or --reduced-motion if the page skips animations under prefers-reduced-motion.';
+const REVEAL_FIX = 'Reveal-on-scroll content waits at opacity 0 or offset until it animates in. Try rpc shot --finish-animations or ' +
+    '--reduced-motion, and make sure the content still shows when JavaScript or animations are off.';
+function carouselFix(items) {
+    return `A still shows one slide. Record it: rpc record <url> --selector '${items[0]?.selector ?? '<css>'}' --duration 5.`;
+}
+/** `rpc shot` warnings: what the image shows differently from a person scrolling. */
+export function shotWarnings(d, settle, ctx) {
+    const out = [];
+    if (settle.count > 0) {
+        out.push({
+            id: 'motion-running',
+            severity: 'warn',
+            message: `${plural(settle.count, 'element was', 'elements were')} still animating when captured`,
+            fix: STILL_FIX,
+            value: settle.count,
+            items: settle.active.map(selector => ({ selector })),
+        });
+    }
+    if (ctx.fullPage) {
+        const collapsed = new Set((ctx.unpinned ?? []).filter(u => u.removed > 0).map(u => u.selector));
+        const left = d.pins.filter(p => !collapsed.has(p.selector));
+        if (left.length) {
+            out.push({
+                id: 'motion-pinned',
+                severity: 'warn',
+                message: 'pinned section: the stitched shot may show blank space',
+                fix: 'Leave unpinning on (the default with --full-page; --no-unpin turns it off) so each pin is collapsed to its ' +
+                    'section, or record the section with rpc record --selector.',
+                items: left.map(pinItem),
+            });
+        }
+    }
+    if (d.hidden.length) {
+        out.push({
+            id: 'motion-reveal-hidden',
+            severity: 'warn',
+            message: `${plural(d.hidden.length, 'element')} still hidden by a reveal animation`,
+            fix: REVEAL_FIX,
+            items: d.hidden,
+        });
+    }
+    if (d.carousels.length) {
+        out.push({ id: 'motion-carousel', severity: 'warn', message: 'carousel: use `rpc record` for motion', fix: carouselFix(d.carousels), items: d.carousels });
+    }
+    return out;
+}
+/** `rpc check` Motion findings. Warn or info only: motion is a capture concern, not a launch blocker. */
+export function motionCheckFindings(d, settle) {
+    const out = [];
+    const running = new Map();
+    for (const s of settle.active)
+        running.set(s, { selector: s });
+    for (const a of d.animations.finite)
+        running.set(a.selector, a);
+    const loops = d.animations.loops.filter(a => !running.has(a.selector));
+    if (running.size) {
+        out.push({
+            id: 'motion-running',
+            severity: 'warn',
+            message: `${plural(running.size, 'element')} still animating after load`,
+            fix: STILL_FIX,
+            selector: [...running.keys()][0],
+            items: [...running.values()].slice(0, 20),
+        });
+    }
+    if (d.hidden.length) {
+        out.push({
+            id: 'motion-reveal-hidden',
+            severity: 'warn',
+            message: `${plural(d.hidden.length, 'element')} in or near the viewport still hidden by a reveal animation`,
+            fix: REVEAL_FIX,
+            selector: d.hidden[0].selector,
+            items: d.hidden,
+        });
+    }
+    if (loops.length) {
+        out.push({
+            id: 'motion-loop',
+            severity: 'info',
+            message: `${plural(loops.length, 'infinite animation')} (loops never settle, so a shot shows one frame)`,
+            fix: 'Stop decorative loops under prefers-reduced-motion: reduce; rpc shot --reduced-motion shows what that looks like.',
+            selector: loops[0].selector,
+            items: loops,
+        });
+    }
+    if (d.pins.length) {
+        out.push({
+            id: 'motion-pinned',
+            severity: 'info',
+            message: `${plural(d.pins.length, 'pinned section')}: a stitched full-page shot would show the spacer as blank space`,
+            fix: 'rpc shot --full-page collapses pins by default (listed under motion.unpinned in the result); rpc record --selector shows the pinned animation.',
+            selector: d.pins[0].selector,
+            items: d.pins.map(pinItem),
+        });
+    }
+    if (d.carousels.length) {
+        out.push({
+            id: 'motion-carousel',
+            severity: 'info',
+            message: `${plural(d.carousels.length, 'carousel or marquee', 'carousels or marquees')}: a still shows one frame`,
+            fix: carouselFix(d.carousels),
+            selector: d.carousels[0].selector,
+            items: d.carousels,
+        });
+    }
+    return out;
+}
+/** `#a, .b +2 more`: where a warning applies, for one-line output. */
+export function warningWhere(w, max = 3) {
+    const sels = (w.items ?? []).map(i => i.selector).filter(Boolean);
+    if (!sels.length)
+        return '';
+    return sels.slice(0, max).join(', ') + (sels.length > max ? ` +${sels.length - max} more` : '');
+}
+/** One line per collapsed pin: `#pinned (2100 css px of spacer removed)`. */
+export function unpinnedLines(unpinned) {
+    return (unpinned ?? []).filter(u => u.removed > 0).map(u => `${u.selector} (${u.removed} css px of spacer removed)`);
+}
+function pinItem(p) {
+    return { selector: p.selector, text: `${p.spacerHeight}px ${p.kind === 'sticky' ? 'track' : 'spacer'} for a ${p.height}px section`, value: p.spacerHeight - p.height };
+}

package/dist/options.js

@@ -19,11 +19,44 @@ export function defaultShotOptions(url) {
         timeoutMs: DEFAULT_TIMEOUT_MS,
         emulate: true,
         reducedMotion: false,
+        finishAnimations: false,
+        unpin: true,
         maxHeight: DEFAULT_MAX_HEIGHT,
         maxSlices: DEFAULT_MAX_SLICES,
         sliceWidth: DEFAULT_SLICE_WIDTH,
     };
 }
+export const FAIL_ON = ['error', 'warn'];
+export function defaultCheckOptions(url) {
+    return {
+        url: normalizeUrl(url),
+        devices: [...DEFAULT_DEVICES],
+        outDir: DEFAULT_OUT_DIR,
+        waitMs: 0,
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        emulate: true,
+        reducedMotion: false,
+        shots: false,
+        failOn: 'error',
+    };
+}
+export const DEFAULT_RECORD_DEVICE = 'desktop-1440';
+export const DEFAULT_RECORD_SECONDS = 5;
+export const MAX_RECORD_SECONDS = 30;
+export function defaultRecordOptions(url) {
+    return {
+        url: normalizeUrl(url),
+        device: DEFAULT_RECORD_DEVICE,
+        duration: DEFAULT_RECORD_SECONDS,
+        gif: false,
+        mp4: false,
+        outDir: DEFAULT_OUT_DIR,
+        waitMs: 0,
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        emulate: true,
+        reducedMotion: false,
+    };
+}
 /**
  * Accept what an agent is likely to type:
  *   http(s)://…, file://…  -> unchanged

package/dist/png.js

@@ -8,6 +8,53 @@ export function pngSize(buf) {
     const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
     return { width: view.getUint32(16), height: view.getUint32(20) };
 }
+/** Width/height of a PNG, JPEG, GIF or WebP from its header; undefined for anything else. */
+export function imageSize(buf) {
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    const ascii = (at, len) => String.fromCharCode(...buf.subarray(at, at + len));
+    try {
+        if (buf.length >= 24 && SIGNATURE.every((b, i) => buf[i] === b))
+            return pngSize(buf);
+        if (ascii(0, 4) === 'GIF8' && buf.length >= 10) {
+            return { width: view.getUint16(6, true), height: view.getUint16(8, true) };
+        }
+        if (ascii(0, 4) === 'RIFF' && ascii(8, 4) === 'WEBP') {
+            const kind = ascii(12, 4);
+            if (kind === 'VP8 ')
+                return { width: view.getUint16(26, true) & 0x3fff, height: view.getUint16(28, true) & 0x3fff };
+            if (kind === 'VP8L') {
+                const bits = view.getUint32(21, true);
+                return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+            }
+            if (kind === 'VP8X') {
+                const u24 = (at) => buf[at] | (buf[at + 1] << 8) | (buf[at + 2] << 16);
+                return { width: u24(24) + 1, height: u24(27) + 1 };
+            }
+            return undefined;
+        }
+        if (buf[0] === 0xff && buf[1] === 0xd8) {
+            // Walk the JPEG segments to the first start-of-frame marker.
+            for (let at = 2; at + 9 < buf.length;) {
+                if (buf[at] !== 0xff)
+                    return undefined;
+                const marker = buf[at + 1];
+                if (marker === 0xff) {
+                    at++;
+                    continue;
+                }
+                const len = view.getUint16(at + 2);
+                if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                    return { width: view.getUint16(at + 7), height: view.getUint16(at + 5) };
+                }
+                at += 2 + len;
+            }
+        }
+    }
+    catch {
+        // Truncated header.
+    }
+    return undefined;
+}
 /**
  * Decode an 8-bit RGB/RGBA non-interlaced PNG, which is what Chromium
  * screenshots are. Anything else throws: this is not a general decoder.