rpc-agent 0.5.0 → 0.6.0

package/dist/capture.js

@@ -3,8 +3,9 @@ import { basename, extname, resolve } from 'node:path';
 import { applyHeaders, AuthRequiredError, redact, redirectedToLogin, resolveAuth, } from './auth.js';
 import { launchBrowser } from './browser.js';
 import { renderFramed, renderSlices } from './composite.js';
-import { explainError } from './errors.js';
+import { explainError, plainText } from './errors.js';
 import { emulationFor, resolveDevices } from './devices.js';
+import { detectMotion, finishAnimations, settleMotion, shotWarnings, unpin, warmUpScrollJs, } from './motion.js';
 import { pngSize, stitchPngs } from './png.js';
 import { fitsOneCapture, planSegments, planSlices, sliceScale } from './slices.js';
 export { MAX_CAPTURE_PX } from './slices.js';
@@ -88,10 +89,10 @@ async function captureDevice(browser, device, opts, outDir, hooks, auth) {
     try {
         const page = await context.newPage();
         await applyHeaders(context, page, auth);
-        page.on('pageerror', e => errors.add(`pageerror: ${e.message}`));
+        page.on('pageerror', e => errors.add(plainText(`pageerror: ${e.message}`)));
         page.on('console', m => {
             if (m.type() === 'error')
-                errors.add(`console: ${m.text()}`);
+                errors.add(plainText(`console: ${m.text()}`));
         });
         const response = await page.goto(opts.url, { waitUntil: 'load', timeout: opts.timeoutMs });
         result.status = response?.status() ?? null;
@@ -111,16 +112,35 @@ async function captureDevice(browser, device, opts, outDir, hooks, auth) {
                 throw err;
             }
         }
+        let warmUp;
         if (opts.fullPage) {
-            await warmUpScroll(page, opts.maxHeight);
+            warmUp = await warmUpScroll(page, opts.maxHeight);
             await settle(page, opts.timeoutMs);
         }
+        const finished = opts.finishAnimations ? await finishAnimations(page) : undefined;
+        // Collapse pins before measuring, so the stitched height is the unpinned one.
+        const unpinned = opts.fullPage && opts.unpin ? await unpin(page) : [];
         if (opts.waitMs > 0)
             await page.waitForTimeout(opts.waitMs);
+        // The screenshot ends CSS and Web Animations itself (animations: 'disabled'), so only wait for JS-driven changes.
+        const motion = { settle: await settleMotion(page, undefined, undefined, { waapi: false }) };
+        if (warmUp)
+            motion.warmUp = warmUp;
+        if (finished)
+            motion.finished = finished;
+        if (unpinned.length)
+            motion.unpinned = unpinned;
+        result.motion = motion;
         checkLogin();
         result.finalUrl = page.url();
         result.title = await page.title();
         result.scrollHeight = await page.evaluate(SCROLL_HEIGHT_JS);
+        const warnings = shotWarnings(await detectMotion(page, opts.fullPage ? 'page' : 'viewport'), motion.settle, {
+            fullPage: opts.fullPage,
+            unpinned,
+        });
+        if (warnings.length)
+            result.warnings = warnings;
         const base = fileStem(opts.url, device.id);
         const shotOpts = { animations: 'disabled', caret: 'hide', type: 'png' };
         // Viewport shot: the raw output when !fullPage, and the bezel input either way.
@@ -221,26 +241,6 @@ const WAIT_FOR_ASSETS_JS = `(async () => {
     new Promise(r => setTimeout(r, 5000)),
   ]);
 })()`;
-/**
- * Walk the page one viewport at a time so loading="lazy" images and
- * IntersectionObserver-driven content render, then return to the top.
- * Replaces the 120 ms per-segment pause in RPC's scroll-and-stitch.
- * Bounded to 100 steps and the full-page height cap.
- */
-const warmUpScrollJs = (maxHeight) => `(async () => {
-  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));
-  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 sleep(100);
-  }
-  window.scrollTo({ top: Math.min(root.scrollHeight, ${maxHeight}), behavior: 'instant' });
-  await sleep(150);
-  window.scrollTo({ top: 0, behavior: 'instant' });
-  await sleep(150);
-})()`;
 const SCROLL_WIDTH_JS = `Math.max(document.documentElement.scrollWidth, document.body ? document.body.scrollWidth : 0)`;
 const SCROLL_HEIGHT_JS = `Math.max(document.documentElement.scrollHeight, document.body ? document.body.scrollHeight : 0)`;
 /**
@@ -254,7 +254,7 @@ export async function settle(page, timeoutMs) {
     await page.evaluate(WAIT_FOR_ASSETS_JS).catch(() => { });
 }
 async function warmUpScroll(page, maxHeight) {
-    await page.evaluate(warmUpScrollJs(Math.round(maxHeight)));
+    return (await page.evaluate(warmUpScrollJs(Math.round(maxHeight))));
 }
 /** `<host>[-<path>]-<device>`, e.g. `localhost-3000-about-iphone-15`. */
 export function fileStem(url, deviceId) {

package/dist/check-page.js

@@ -2,7 +2,7 @@
 // capture.ts: under tsx/vitest, esbuild wraps named functions in a
 // `__name()` helper that doesn't exist inside the page.
 /** Shared helpers: a short unique selector, rendering tests and accessible names. */
-const HELPERS = `
+export const HELPERS = `
   const esc = s => (window.CSS && CSS.escape ? CSS.escape(s) : String(s).replace(/[^\\w-]/g, '\\\\$&'));
   const uniq = s => { try { return document.querySelectorAll(s).length === 1; } catch (e) { return false; } };
   const sel = el => {
@@ -289,20 +289,35 @@ export const MOBILE_JS = `(() => {
     }
   }
 
-  // Tap targets under 44x44 CSS px. Links inside running text are exempt.
+  // Tap targets under 44x44 CSS px. Inline links in a sentence are exempt
+  // (WCAG 2.5.8): display inline, with letters or digits outside any control
+  // in the same block of text. Buttons and links laid out as boxes count.
   const interactive = 'a[href], button, input:not([type="hidden"]), select, textarea, summary, [role="button"], [role="link"], [role="checkbox"], [role="switch"], [role="tab"], [role="menuitem"]';
+  const blockOf = node => {
+    let p = node.parentElement;
+    while (p && p !== document.body && ['inline', 'contents'].includes(getComputedStyle(p).display)) p = p.parentElement;
+    return p;
+  };
+  const inSentence = el => {
+    const isLink = (el.localName === 'a' && !el.hasAttribute('role')) || el.getAttribute('role') === 'link';
+    if (!isLink || getComputedStyle(el).display !== 'inline') return false;
+    const block = blockOf(el);
+    if (!block) return false;
+    const walker = document.createTreeWalker(block, NodeFilter.SHOW_TEXT);
+    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+      if (!/[\\p{L}\\p{N}]/u.test(n.textContent)) continue;
+      if (n.parentElement.closest(interactive) || blockOf(n) !== block) continue;
+      return true;
+    }
+    return false;
+  };
   const small = [];
   let tapTargets = 0;
   for (const el of document.querySelectorAll(interactive)) {
     if (!painted(el) || el.closest('[aria-hidden="true"], [inert]')) continue;
     const outerTarget = el.parentElement && el.parentElement.closest(interactive);
     if (outerTarget) continue;
-    const cs = getComputedStyle(el);
-    if (cs.display === 'inline' && el.parentElement) {
-      const own = clean(el.textContent).length;
-      const around = clean(el.parentElement.textContent).length;
-      if (around > own + 10) continue;
-    }
+    if (inSentence(el)) continue;
     tapTargets++;
     let { width, height } = el.getBoundingClientRect();
     if (el.labels) for (const l of el.labels) {

package/dist/check.js

@@ -9,6 +9,8 @@ import { launchBrowser } from './browser.js';
 import { describeFailure, fileStem, newDeviceContext, settle } from './capture.js';
 import { FONTS_JS, LABELS_JS, LAYOUT_SHIFT_INIT_JS, LAYOUT_SHIFTS_JS, META_JS, MOBILE_JS, SCROLL_ONCE_JS, } from './check-page.js';
 import { resolveDevices } from './devices.js';
+import { plainText } from './errors.js';
+import { detectMotion, motionCheckFindings, settleMotion } from './motion.js';
 import { imageSize } from './png.js';
 /** Report order and headings. */
 export const CHECKS = [
@@ -18,6 +20,7 @@ export const CHECKS = [
     { id: 'labels', title: 'Unlabelled controls' },
     { id: 'fonts', title: 'Fonts' },
     { id: 'mobile', title: 'Mobile viewport' },
+    { id: 'motion', title: 'Motion' },
 ];
 /** Bumped when a field changes meaning or goes away; new fields don't bump it. */
 export const REPORT_SCHEMA = 1;
@@ -28,6 +31,8 @@ export const CLS_POOR = 0.25;
 export const CLS_TOLERANCE = 0.001;
 /** Fixed idle after load and settle, before the scroll. */
 export const IDLE_MS = 500;
+/** Motion: how long the settle probe waits for animations to stop before reporting what is still moving. */
+export const MOTION_PROBE_MS = 1000;
 export const MIN_TAP = 44;
 export async function runCheck(opts, hooks = {}) {
     const devices = resolveDevices(opts.devices);
@@ -103,7 +108,7 @@ async function checkDevice(browser, device, opts, auth, cache, result) {
         const page = await context.newPage();
         await applyHeaders(context, page, auth);
         await page.addInitScript(LAYOUT_SHIFT_INIT_JS);
-        page.on('pageerror', e => uncaught.add(e.message.split('\n')[0] ?? e.message));
+        page.on('pageerror', e => uncaught.add(plainText(e.message.split('\n')[0] ?? e.message)));
         page.on('console', m => {
             const text = m.text();
             if (/Mixed Content/i.test(text)) {
@@ -113,7 +118,7 @@ async function checkDevice(browser, device, opts, auth, cache, result) {
                 return;
             }
             if (m.type() === 'error')
-                consoleErrors.add(text);
+                consoleErrors.add(plainText(text));
         });
         page.on('response', r => {
             if (r.request().resourceType() === 'font')
@@ -173,6 +178,9 @@ async function checkDevice(browser, device, opts, auth, cache, result) {
                 await attachShots(page, mobile, opts, device, 'horizontal-overflow');
             findings.push(...mobile);
         }
+        const still = await settleMotion(page, undefined, MOTION_PROBE_MS);
+        for (const f of motionCheckFindings(await detectMotion(page, 'viewport'), still))
+            findings.push({ ...f, check: 'motion' });
         return { findings, ...(og ? { ogImage: og } : {}) };
     }
     finally {
@@ -603,7 +611,7 @@ export function mobileFindings(d) {
             check: 'mobile',
             severity: 'warn',
             message: `${d.smallTargets.length} of ${d.tapTargets} tap targets are smaller than ${MIN_TAP}×${MIN_TAP}px`,
-            fix: `Make each control at least ${MIN_TAP}×${MIN_TAP} CSS px: padding, min-height/min-width, or a larger hit area with a ::before inset.`,
+            fix: `Make each control at least ${MIN_TAP}×${MIN_TAP} CSS px: padding, min-height/min-width, or a larger hit area with a ::before inset. Inline links in a sentence are exempt (WCAG 2.5.8).`,
             selector: d.smallTargets[0].selector,
             items: d.smallTargets.slice(0, 15).map(({ selector, text, value }) => ({ selector, text, value })),
         });

package/dist/cli.js

@@ -8,6 +8,8 @@ import { capture } from './capture.js';
 import { checkExitCode, runCheck, summaryLine } from './check.js';
 import { deviceLine, plainReport } from './check-format.js';
 import { CATEGORY_LABELS, CATEGORY_ORDER, DEVICE_ALIASES, DEVICES } from './devices.js';
+import { unpinnedLines, warningWhere } from './motion.js';
+import { record } from './record.js';
 import { currentMode, openPath, waitForEnter } from './term.js';
 const NO_PAINT = { ok: s => s, bad: s => s, warn: s => s };
 let paint = NO_PAINT;
@@ -124,6 +126,25 @@ async function main(argv) {
                 printCheck(report);
             return checkExitCode(report, cmd.options.failOn);
         }
+        case 'record': {
+            if (mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runRecord(cmd.options, { open: cmd.open }, c);
+            }
+            const result = await record(cmd.options, cmd.json
+                ? {}
+                : {
+                    onAuth: a => console.log(`auth: ${describeAuth(a)}`),
+                    onRecording: s => console.log(`recording ${s}s of ${cmd.options.selector ?? 'the viewport'} on ${cmd.options.device}`),
+                });
+            if (cmd.json)
+                console.log(JSON.stringify(result, null, 2));
+            else
+                printRecord(result);
+            if (cmd.open && !result.error)
+                openPath(result.outDir);
+            return result.error ? 1 : 0;
+        }
         case 'login': {
             if (cmd.passwordFromFlag) {
                 console.error(`rpc: ${paint.warn('warning:')} --password is visible in shell history and the process list; set RPC_LOGIN_PASSWORD instead`);
@@ -222,8 +243,13 @@ function printDoctor(r) {
     console.log(`node        ${r.node}`);
     console.log(`playwright  ${r.playwright}`);
     console.log(`browsers    ${r.browsersPath}`);
+    const ff = r.ffmpeg;
+    console.log(`ffmpeg      ${ff.source === 'missing' ? `${paint.warn('missing')} (only rpc record needs it)` : `${paint.ok('ok')} (${ff.source}, ${ff.path})`}`);
+    console.log(`mp4         ${r.mp4.ok ? `${paint.ok('ok')} (${r.mp4.encoder})` : 'no (optional: ffmpeg with H.264 on PATH, for rpc record --mp4)'}`);
     if (r.ok) {
         console.log(`chromium    ${paint.ok('ok')} (${r.version})`);
+        if (ff.fix)
+            console.error(`rpc: ${ff.fix}`);
         return;
     }
     console.log(`chromium    ${paint.bad(r.chromium)}`);
@@ -255,6 +281,36 @@ function printShot(s) {
     }
     if (s.consoleErrors?.length)
         lines.push(`   ${s.consoleErrors.length} console error(s), first: ${s.consoleErrors[0]}`);
+    for (const u of unpinnedLines(s.motion?.unpinned))
+        lines.push(`   unpinned ${u}`);
+    for (const w of s.warnings ?? []) {
+        const where = warningWhere(w);
+        lines.push(`   ${paint.warn('warn:')} ${w.message}${where ? `: ${where}` : ''}`);
+    }
+    console.log(lines.join('\n'));
+}
+function printRecord(r) {
+    const label = `${r.device} (${r.viewport.width}x${r.viewport.height} @${r.dpr}x)`;
+    if (r.error) {
+        console.error(`${paint.bad('x')} ${label}: ${r.error}`);
+        if (r.hint)
+            console.error(`   ${paint.warn('hint:')} ${r.hint}`);
+        return;
+    }
+    const lines = [`${paint.ok('ok')} ${label}${r.selector ? ` ${r.selector}` : ''}${r.status && r.status >= 400 ? ` HTTP ${r.status}` : ''}`];
+    const v = r.video;
+    if (v)
+        lines.push(`   ${rel(v.path)}  ${v.width}x${v.height}, ${v.duration}s at ${v.fps} fps (${v.captured} frames captured, ${r.ffmpeg} ffmpeg)`);
+    if (r.poster)
+        lines.push(`   ${rel(r.poster.path)}  ${r.poster.width}x${r.poster.height} poster`);
+    if (r.gif)
+        lines.push(`   ${rel(r.gif.path)}  ${r.gif.width}x${r.gif.height}, ${r.gif.frames} frames`);
+    if (r.mp4)
+        lines.push(`   ${rel(r.mp4.path)}  ${r.mp4.encoder}`);
+    for (const w of r.warnings ?? [])
+        lines.push(`   ${paint.warn('warn:')} ${w}`);
+    if (r.consoleErrors?.length)
+        lines.push(`   ${r.consoleErrors.length} console error(s), first: ${r.consoleErrors[0]}`);
     console.log(lines.join('\n'));
 }
 export function formatDeviceTable() {

package/dist/errors.js

@@ -113,3 +113,11 @@ export function explainError(err, ctx) {
     }
     return { code: 'UNKNOWN', error: first };
 }
+/**
+ * Page-supplied text (console errors, uncaught exceptions) with control
+ * characters removed, so a page can't send terminal escape sequences through
+ * rpc's output. Newlines and tabs stay.
+ */
+export function plainText(text) {
+    return text.replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '');
+}

package/dist/gif.js

@@ -0,0 +1,212 @@
+/** Palette entries for colours; the last index is transparent. */
+const COLOURS = 255;
+const TRANSPARENT = 255;
+/** Pixels sampled for the palette, across all frames. */
+const SAMPLES = 250_000;
+const bucket = (r, g, b) => ((r >> 3) << 10) | ((g >> 3) << 5) | (b >> 3);
+/** Median cut over a 15-bit colour histogram: up to COLOURS RGB triples. */
+export function buildPalette(frames) {
+    const counts = new Uint32Array(32768);
+    const sums = new Float64Array(32768 * 3);
+    const total = frames.reduce((n, f) => n + f.width * f.height, 0);
+    const step = Math.max(1, Math.floor(total / SAMPLES));
+    for (const f of frames) {
+        for (let i = 0; i < f.width * f.height; i += step) {
+            const o = i * f.channels;
+            const r = f.data[o], g = f.data[o + 1], b = f.data[o + 2];
+            const k = bucket(r, g, b);
+            counts[k]++;
+            sums[k * 3] = sums[k * 3] + r;
+            sums[k * 3 + 1] = sums[k * 3 + 1] + g;
+            sums[k * 3 + 2] = sums[k * 3 + 2] + b;
+        }
+    }
+    const used = [];
+    for (let k = 0; k < 32768; k++)
+        if (counts[k])
+            used.push(k);
+    const chan = (k, c) => (k >> (10 - 5 * c)) & 31;
+    const measure = (keys) => {
+        let best = 0;
+        let channel = 0;
+        for (let c = 0; c < 3; c++) {
+            let lo = 31, hi = 0;
+            for (const k of keys) {
+                const v = chan(k, c);
+                if (v < lo)
+                    lo = v;
+                if (v > hi)
+                    hi = v;
+            }
+            if (hi - lo > best) {
+                best = hi - lo;
+                channel = c;
+            }
+        }
+        return { keys, range: best, channel };
+    };
+    const boxes = [measure(used)];
+    while (boxes.length < COLOURS) {
+        let pick = -1;
+        for (let i = 0; i < boxes.length; i++)
+            if (boxes[i].range > 0 && (pick < 0 || boxes[i].range > boxes[pick].range))
+                pick = i;
+        if (pick < 0)
+            break;
+        const box = boxes[pick];
+        box.keys.sort((a, b) => chan(a, box.channel) - chan(b, box.channel));
+        const half = box.keys.reduce((n, k) => n + counts[k], 0) / 2;
+        let acc = 0;
+        let cut = 1;
+        for (; cut < box.keys.length - 1; cut++) {
+            acc += counts[box.keys[cut - 1]];
+            if (acc >= half)
+                break;
+        }
+        boxes.splice(pick, 1, measure(box.keys.slice(0, cut)), measure(box.keys.slice(cut)));
+    }
+    const palette = new Uint8Array(256 * 3);
+    boxes.forEach((box, i) => {
+        let n = 0, r = 0, g = 0, b = 0;
+        for (const k of box.keys) {
+            n += counts[k];
+            r += sums[k * 3];
+            g += sums[k * 3 + 1];
+            b += sums[k * 3 + 2];
+        }
+        palette[i * 3] = Math.round(r / n);
+        palette[i * 3 + 1] = Math.round(g / n);
+        palette[i * 3 + 2] = Math.round(b / n);
+    });
+    return palette.subarray(0, Math.max(1, boxes.length) * 3);
+}
+/** Nearest palette entry per 15-bit bucket, filled on first use. */
+function mapper(palette) {
+    const cache = new Int16Array(32768).fill(-1);
+    const n = palette.length / 3;
+    return (r, g, b) => {
+        const k = bucket(r, g, b);
+        let hit = cache[k];
+        if (hit >= 0)
+            return hit;
+        const cr = ((k >> 10) << 3) | 4, cg = (((k >> 5) & 31) << 3) | 4, cb = ((k & 31) << 3) | 4;
+        let best = Infinity;
+        for (let i = 0; i < n; i++) {
+            const dr = palette[i * 3] - cr, dg = palette[i * 3 + 1] - cg, db = palette[i * 3 + 2] - cb;
+            const d = dr * dr * 2 + dg * dg * 4 + db * db * 3;
+            if (d < best) {
+                best = d;
+                hit = i;
+            }
+        }
+        cache[k] = hit;
+        return hit;
+    };
+}
+/** GIF LZW with 8-bit minimum code size, split into data sub-blocks. */
+export function lzw(indices) {
+    const min = 8;
+    const clear = 1 << min;
+    const eoi = clear + 1;
+    const out = [];
+    let acc = 0;
+    let bits = 0;
+    let size = min + 1;
+    const emit = (code) => {
+        acc |= code << bits;
+        bits += size;
+        while (bits >= 8) {
+            out.push(acc & 0xff);
+            acc >>>= 8;
+            bits -= 8;
+        }
+    };
+    let table = new Map();
+    let next = eoi + 1;
+    emit(clear);
+    let prefix = indices[0] ?? 0;
+    for (let i = 1; i < indices.length; i++) {
+        const k = indices[i];
+        const key = prefix * 256 + k;
+        const code = table.get(key);
+        if (code !== undefined) {
+            prefix = code;
+            continue;
+        }
+        emit(prefix);
+        if (next === 4096) {
+            emit(clear);
+            table = new Map();
+            next = eoi + 1;
+            size = min + 1;
+        }
+        else {
+            if (next >= 1 << size)
+                size++;
+            table.set(key, next++);
+        }
+        prefix = k;
+    }
+    emit(prefix);
+    emit(eoi);
+    if (bits > 0)
+        out.push(acc & 0xff);
+    const blocks = [min];
+    for (let i = 0; i < out.length; i += 255) {
+        const chunk = out.slice(i, i + 255);
+        blocks.push(chunk.length, ...chunk);
+    }
+    blocks.push(0);
+    return Buffer.from(blocks);
+}
+/**
+ * A looping GIF built one frame at a time, `delayCs` hundredths of a second
+ * each, with a palette made beforehand (buildPalette on all or some frames).
+ * Only the previous frame's indices are kept, not the frames themselves.
+ */
+export function gifWriter(width, height, palette, delayCs) {
+    const nearest = mapper(palette);
+    const table = Buffer.alloc(256 * 3);
+    table.set(palette);
+    const u16 = (n) => [n & 0xff, (n >> 8) & 0xff];
+    const parts = [
+        Buffer.from('GIF89a', 'latin1'),
+        Buffer.from([...u16(width), ...u16(height), 0xf7, 0, 0]), // global table, 256 entries
+        table,
+        Buffer.from([0x21, 0xff, 11, ...Buffer.from('NETSCAPE2.0', 'latin1'), 3, 1, 0, 0, 0]), // loop forever
+    ];
+    let shown;
+    return {
+        add(f) {
+            if (f.width !== width || f.height !== height)
+                throw new Error('GIF frames must all be the same size');
+            const idx = new Uint8Array(width * height);
+            const now = new Uint8Array(width * height);
+            for (let i = 0; i < width * height; i++) {
+                const o = i * f.channels;
+                now[i] = nearest(f.data[o], f.data[o + 1], f.data[o + 2]);
+                idx[i] = shown && shown[i] === now[i] ? TRANSPARENT : now[i];
+            }
+            // Graphic control: keep the previous frame under this one, transparent index after the first frame.
+            parts.push(Buffer.from([0x21, 0xf9, 4, shown ? 0x05 : 0x04, ...u16(delayCs), TRANSPARENT, 0]));
+            parts.push(Buffer.from([0x2c, 0, 0, 0, 0, ...u16(width), ...u16(height), 0]));
+            parts.push(lzw(idx));
+            shown = now;
+        },
+        end() {
+            if (!shown)
+                throw new Error('No frames to encode');
+            return Buffer.concat([...parts, Buffer.from([0x3b])]);
+        },
+    };
+}
+/** Encode same-sized frames as a looping GIF, `delayCs` hundredths of a second each. */
+export function encodeGif(frames, delayCs) {
+    if (!frames.length)
+        throw new Error('No frames to encode');
+    const { width, height } = frames[0];
+    const gif = gifWriter(width, height, buildPalette(frames), delayCs);
+    for (const f of frames)
+        gif.add(f);
+    return gif.end();
+}

package/dist/help.js

@@ -6,6 +6,8 @@ const SHOT_OPTIONS = [
     ['    --slice-width <px>', 'max slice width (default: 768)'],
     ['    --max-height <px>', 'full-page cap in CSS px (default: 60000)'],
     ['    --reduced-motion', 'emulate prefers-reduced-motion: reduce'],
+    ['    --finish-animations', 'jump GSAP tweens on window (and Web Animations) to their end first'],
+    ['    --no-unpin', 'with --full-page: keep pinned sections (default: collapse each once)'],
     ['-o, --out <dir>', 'output directory (default: ./.rpc-shots)'],
     ['    --wait-for <selector>', 'wait for a CSS selector before capturing'],
     ['    --wait <ms>', 'extra settle delay after load (default: 0)'],
@@ -33,6 +35,22 @@ const CHECK_OPTIONS = [
     ['    --timeout <ms>', 'navigation timeout (default: 30000)'],
     ['    --json', 'print the report as JSON (schema in the README)'],
 ];
+const RECORD_OPTIONS = [
+    ['-d, --device <id>', 'one device id or alias (default: desktop-1440)'],
+    ['    --selector <css>', 'crop to this element; it is scrolled into view first'],
+    ['    --duration <s>', 'seconds of video, 0.5 to 30 (default: 5)'],
+    ['    --gif', 'also write a GIF (10 fps, at most 640px wide)'],
+    ['    --mp4', 'also write an mp4; needs ffmpeg with H.264 on PATH, skipped otherwise'],
+    ['-o, --out <dir>', 'output directory (default: ./.rpc-shots)'],
+    ['    --wait-for <selector>', 'wait for a CSS selector before recording'],
+    ['    --wait <ms>', 'extra delay before recording (default: 0)'],
+    ['    --color-scheme <s>', 'light | dark | no-preference'],
+    ['    --reduced-motion', 'emulate prefers-reduced-motion: reduce'],
+    ['    --timeout <ms>', 'navigation timeout (default: 30000)'],
+    ['    --no-emulate', 'viewport + DPR only (no mobile UA / touch)'],
+    ['    --open', 'open the output folder when done'],
+    ['    --json', 'print the result as JSON'],
+];
 const LOGIN_OPTIONS = [
     ['    --save <file>', 'write the storage state here instead of the per-origin session'],
     ['    --form', 'headless: fill an email + password form (CI, agents)'],
@@ -70,6 +88,17 @@ export const COMMANDS = {
             ['rpc check localhost:3000/billing', 'uses the session saved by rpc login'],
         ],
     },
+    record: {
+        usage: 'rpc record <url> [options]',
+        summary: 'Record a short video of a page, or of one element, for what a still cannot show: carousels, marquees, ' +
+            'pinned scroll sections, hover loops. Writes a VP9 webm and a poster PNG, plus a GIF or mp4 on request.',
+        options: [...RECORD_OPTIONS, ...AUTH_OPTIONS],
+        examples: [
+            ["rpc record localhost:3000 --selector '.hero-carousel'", '5 s of one element'],
+            ['rpc record localhost:3000 -d iphone --duration 10 --gif', 'whole phone viewport, plus a GIF'],
+            ["rpc record example.com --selector '#logos' --mp4", 'mp4 too, when ffmpeg is on PATH'],
+        ],
+    },
     login: {
         usage: 'rpc login <url> [--form] [--save <file>]',
         summary: 'Open a browser window at the URL, sign in, then press Enter (or close the window). The session is saved for that ' +
@@ -102,7 +131,7 @@ export const COMMANDS = {
     },
     doctor: {
         usage: 'rpc doctor [--json]',
-        summary: "Check that Playwright's Chromium is installed and launches.",
+        summary: "Check that Playwright's Chromium is installed and launches, and which ffmpeg `rpc record` would use.",
         options: [['    --json', 'print the report as JSON']],
         examples: [['rpc doctor', 'exits 1 when Chromium is missing']],
     },
@@ -117,13 +146,14 @@ export const COMMANDS = {
     },
     mcp: {
         usage: 'rpc mcp',
-        summary: 'Run the MCP server on stdio (tools: screenshot, check, list_devices, list_sessions).',
+        summary: 'Run the MCP server on stdio (tools: screenshot, check, record, list_devices, list_sessions).',
         examples: [['claude mcp add --scope user rpc -- node /abs/path/dist/cli.js mcp', 'add to Claude Code']],
     },
 };
 const TOP = [
     ['shot <url>', 'capture screenshots'],
-    ['check <url>', 'pre-launch audit: meta, layout shift, labels, fonts, mobile'],
+    ['check <url>', 'pre-launch audit: meta, layout shift, labels, fonts, mobile, motion'],
+    ['record <url>', 'record a short video of the page or one element'],
     ['login <url>', 'sign in once; later shots of that origin use the session'],
     ['sessions', 'list or clear saved sessions'],
     ['devices', 'list device ids and aliases'],