rpc-agent 0.4.0 → 0.6.0

package/dist/args.js

@@ -1,8 +1,8 @@
 import { parseArgs } from 'node:util';
 import { parseCookie, parseHeader, resolveAuth, toOrigin } from './auth.js';
 import { resolveDevices } from './devices.js';
-import { COLOR_SCHEMES, DEFAULT_TIMEOUT_MS, defaultShotOptions, normalizeUrl, } from './options.js';
-export const HELP_TOPICS = ['shot', 'login', 'sessions', 'devices', 'doctor', 'install', 'mcp'];
+import { COLOR_SCHEMES, DEFAULT_TIMEOUT_MS, defaultCheckOptions, defaultRecordOptions, defaultShotOptions, FAIL_ON, MAX_RECORD_SECONDS, normalizeUrl, } from './options.js';
+export const HELP_TOPICS = ['shot', 'check', 'record', 'login', 'sessions', 'devices', 'doctor', 'install', 'mcp'];
 function isTopic(s) {
     return HELP_TOPICS.includes(s ?? '');
 }
@@ -16,6 +16,9 @@ export const USAGE = `rpc - screenshot a URL at device viewports, optionally in
 
 Usage:
   rpc shot <url> [options]   capture screenshots
+  rpc check <url> [options]  pre-launch audit: meta, layout shift, labels, fonts, mobile,
+                             motion
+  rpc record <url> [options] record a short video of the page or one element
   rpc login <url> [--form]   sign in once and save the session for that origin
   rpc sessions [list|clear [origin]]
                              list or delete saved sessions
@@ -34,6 +37,10 @@ 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 before capturing
+      --no-unpin             with --full-page: keep pinned sections as they
+                             are (default: collapse each to its section)
   -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)
@@ -43,7 +50,20 @@ Shot options:
       --json                 print the result as JSON
       --open                 open the output folder when done
 
-Auth options (values are never printed):
+Check options (plus -d, --wait-for, --wait, --timeout, --color-scheme, -o, --json):
+      --fail-on <level>      error (default) | warn: exit 1 on warnings too
+      --shots                screenshot the elements behind layout-shift and
+                             overflow findings (into --out)
+
+Record options (plus --wait-for, --wait, --timeout, --color-scheme,
+--reduced-motion, --no-emulate, -o, --json, --open):
+  -d, --device <id>          one device id or alias (default: desktop-1440)
+      --selector <css>       crop to this element (scrolled into view first)
+      --duration <s>         seconds of video, up to 30 (default: 5)
+      --gif                  also write a GIF
+      --mp4                  also write an mp4 (needs ffmpeg with H.264 on PATH)
+
+Auth options (values are never printed; shot, check and record):
       --cookie <c>           "name=value[; Domain=…; Path=…]", repeatable;
                              sent to the target origin only
       --header <h>           "Name: value", repeatable; target origin only
@@ -58,6 +78,8 @@ Examples:
   rpc shot localhost:3000 -d iphone-15,ipad,desktop-1440 --bezels
   rpc shot https://example.com --full-page --color-scheme dark
   rpc login localhost:3000/sign-in && rpc shot localhost:3000/dashboard
+  rpc check localhost:3000 --fail-on warn
+  rpc record localhost:3000 --selector '.carousel' --duration 6 --gif
 `;
 export function parseCli(argv, env = process.env) {
     const [cmd, ...rest] = argv;
@@ -104,6 +126,10 @@ export function parseCli(argv, env = process.env) {
         }
         case 'shot':
             return parseShot(rest);
+        case 'check':
+            return parseCheck(rest);
+        case 'record':
+            return parseRecord(rest);
         default:
             throw new ArgError(`Unknown command "${cmd}". Run \`rpc --help\`.`);
     }
@@ -125,13 +151,11 @@ function parseShot(args) {
         'slice-width': { type: 'string' },
         'max-height': { type: 'string' },
         'reduced-motion': { type: 'boolean' },
+        'finish-animations': { type: 'boolean' },
+        'no-unpin': { type: 'boolean' },
         json: { type: 'boolean' },
         open: { type: 'boolean' },
-        cookie: { type: 'string', multiple: true },
-        header: { type: 'string', multiple: true },
-        'storage-state': { type: 'string' },
-        'no-session': { type: 'boolean' },
-        'allow-origin': { type: 'string', multiple: true },
+        ...AUTH_FLAGS,
     }, true);
     if (positionals.length === 0)
         throw new ArgError('Missing <url>. Usage: rpc shot <url> [options]');
@@ -144,17 +168,8 @@ function parseShot(args) {
     catch (err) {
         throw new ArgError(err.message);
     }
-    if (typeof values.devices === 'string') {
-        const list = splitList(values.devices);
-        if (list.length === 0)
-            throw new ArgError('--devices is empty');
-        try {
-            options.devices = resolveDevices(list).map(d => d.id);
-        }
-        catch (err) {
-            throw new ArgError(err.message);
-        }
-    }
+    if (typeof values.devices === 'string')
+        options.devices = parseDevices(values.devices);
     if (values.bezels)
         options.bezels = true;
     if (values['full-page'])
@@ -167,25 +182,38 @@ function parseShot(args) {
         options.waitMs = parseMs('--wait', values.wait);
     if (typeof values.timeout === 'string')
         options.timeoutMs = parseMs('--timeout', values.timeout);
-    if (typeof values['color-scheme'] === 'string') {
-        const s = values['color-scheme'];
-        if (!COLOR_SCHEMES.includes(s)) {
-            throw new ArgError(`--color-scheme must be one of ${COLOR_SCHEMES.join(', ')}`);
-        }
-        options.colorScheme = s;
-    }
+    if (typeof values['color-scheme'] === 'string')
+        options.colorScheme = parseColorScheme(values['color-scheme']);
     if (values['no-emulate'])
         options.emulate = false;
     if (values.slices)
         options.saveSlices = true;
     if (values['reduced-motion'])
         options.reducedMotion = true;
+    if (values['finish-animations'])
+        options.finishAnimations = true;
+    if (values['no-unpin'])
+        options.unpin = false;
     if (typeof values['slice-width'] === 'string') {
         options.sliceWidth = parseInt_('--slice-width', values['slice-width'], 256, 4096);
     }
     if (typeof values['max-height'] === 'string') {
         options.maxHeight = parseInt_('--max-height', values['max-height'], 500, 200_000);
     }
+    const auth = parseAuth(values, options.url);
+    if (auth)
+        options.auth = auth;
+    return { command: 'shot', options, json: Boolean(values.json), open: Boolean(values.open) };
+}
+const AUTH_FLAGS = {
+    cookie: { type: 'string', multiple: true },
+    header: { type: 'string', multiple: true },
+    'storage-state': { type: 'string' },
+    'no-session': { type: 'boolean' },
+    'allow-origin': { type: 'string', multiple: true },
+};
+/** Cookie/header/session flags, validated against the URL now: bad input is a usage error. */
+function parseAuth(values, url) {
     const auth = {};
     try {
         if (values.cookie?.length)
@@ -198,15 +226,153 @@ function parseShot(args) {
             auth.useSession = false;
         if (values['allow-origin']?.length)
             auth.allowOrigins = values['allow-origin'].flatMap(splitList).map(toOrigin);
-        if (Object.keys(auth).length) {
-            resolveAuth(options.url, auth); // validate now: bad input is a usage error
-            options.auth = auth;
-        }
+        if (!Object.keys(auth).length)
+            return undefined;
+        resolveAuth(url, auth);
+        return auth;
     }
     catch (err) {
         throw new ArgError(err.message);
     }
-    return { command: 'shot', options, json: Boolean(values.json), open: Boolean(values.open) };
+}
+function parseDevices(raw) {
+    const list = splitList(raw);
+    if (list.length === 0)
+        throw new ArgError('--devices is empty');
+    try {
+        return resolveDevices(list).map(d => d.id);
+    }
+    catch (err) {
+        throw new ArgError(err.message);
+    }
+}
+function parseCheck(args) {
+    if (wantsHelp(args))
+        return { command: 'help', topic: 'check' };
+    const { values, positionals } = parse(args, {
+        devices: { type: 'string', short: 'd' },
+        out: { type: 'string', short: 'o' },
+        'wait-for': { type: 'string' },
+        wait: { type: 'string' },
+        'color-scheme': { type: 'string' },
+        timeout: { type: 'string' },
+        'fail-on': { type: 'string' },
+        shots: { type: 'boolean' },
+        json: { type: 'boolean' },
+        ...AUTH_FLAGS,
+    }, true);
+    if (positionals.length === 0)
+        throw new ArgError('Missing <url>. Usage: rpc check <url> [options]');
+    if (positionals.length > 1)
+        throw new ArgError(`Expected one URL, got: ${positionals.join(' ')}`);
+    let options;
+    try {
+        options = defaultCheckOptions(positionals[0]);
+    }
+    catch (err) {
+        throw new ArgError(err.message);
+    }
+    if (typeof values.devices === 'string')
+        options.devices = parseDevices(values.devices);
+    if (typeof values.out === 'string')
+        options.outDir = values.out;
+    if (typeof values['wait-for'] === 'string')
+        options.waitFor = values['wait-for'];
+    if (typeof values.wait === 'string')
+        options.waitMs = parseMs('--wait', values.wait);
+    if (typeof values.timeout === 'string')
+        options.timeoutMs = parseMs('--timeout', values.timeout);
+    if (typeof values['color-scheme'] === 'string')
+        options.colorScheme = parseColorScheme(values['color-scheme']);
+    if (typeof values['fail-on'] === 'string') {
+        if (!FAIL_ON.includes(values['fail-on']))
+            throw new ArgError(`--fail-on must be one of ${FAIL_ON.join(', ')}`);
+        options.failOn = values['fail-on'];
+    }
+    if (values.shots)
+        options.shots = true;
+    const auth = parseAuth(values, options.url);
+    if (auth)
+        options.auth = auth;
+    return { command: 'check', options, json: Boolean(values.json) };
+}
+function parseRecord(args) {
+    if (wantsHelp(args))
+        return { command: 'help', topic: 'record' };
+    const { values, positionals } = parse(args, {
+        device: { type: 'string', short: 'd' },
+        devices: { type: 'string' },
+        selector: { type: 'string' },
+        duration: { type: 'string' },
+        gif: { type: 'boolean' },
+        mp4: { type: 'boolean' },
+        out: { type: 'string', short: 'o' },
+        'wait-for': { type: 'string' },
+        wait: { type: 'string' },
+        'color-scheme': { type: 'string' },
+        timeout: { type: 'string' },
+        'no-emulate': { type: 'boolean' },
+        'reduced-motion': { type: 'boolean' },
+        json: { type: 'boolean' },
+        open: { type: 'boolean' },
+        ...AUTH_FLAGS,
+    }, true);
+    if (positionals.length === 0)
+        throw new ArgError('Missing <url>. Usage: rpc record <url> [options]');
+    if (positionals.length > 1)
+        throw new ArgError(`Expected one URL, got: ${positionals.join(' ')}`);
+    let options;
+    try {
+        options = defaultRecordOptions(positionals[0]);
+    }
+    catch (err) {
+        throw new ArgError(err.message);
+    }
+    const device = values.device ?? values.devices;
+    if (typeof device === 'string') {
+        const list = parseDevices(device);
+        if (list.length !== 1)
+            throw new ArgError('rpc record takes one device (-d desktop-1440)');
+        options.device = list[0];
+    }
+    if (typeof values.selector === 'string') {
+        if (!values.selector.trim())
+            throw new ArgError('--selector is empty');
+        options.selector = values.selector;
+    }
+    if (typeof values.duration === 'string') {
+        const n = Number(values.duration);
+        if (!Number.isFinite(n) || n < 0.5 || n > MAX_RECORD_SECONDS)
+            throw new ArgError(`--duration must be a number of seconds from 0.5 to ${MAX_RECORD_SECONDS}`);
+        options.duration = n;
+    }
+    if (values.gif)
+        options.gif = true;
+    if (values.mp4)
+        options.mp4 = true;
+    if (typeof values.out === 'string')
+        options.outDir = values.out;
+    if (typeof values['wait-for'] === 'string')
+        options.waitFor = values['wait-for'];
+    if (typeof values.wait === 'string')
+        options.waitMs = parseMs('--wait', values.wait);
+    if (typeof values.timeout === 'string')
+        options.timeoutMs = parseMs('--timeout', values.timeout);
+    if (typeof values['color-scheme'] === 'string')
+        options.colorScheme = parseColorScheme(values['color-scheme']);
+    if (values['no-emulate'])
+        options.emulate = false;
+    if (values['reduced-motion'])
+        options.reducedMotion = true;
+    const auth = parseAuth(values, options.url);
+    if (auth)
+        options.auth = auth;
+    return { command: 'record', options, json: Boolean(values.json), open: Boolean(values.open) };
+}
+function parseColorScheme(s) {
+    if (!COLOR_SCHEMES.includes(s))
+        throw new ArgError(`--color-scheme must be one of ${COLOR_SCHEMES.join(', ')}`);
+    return s;
 }
 function parseLogin(args, env) {
     if (wantsHelp(args))

package/dist/browser.js

@@ -1,7 +1,7 @@
-import { spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, resolve } from 'node:path';
+import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
 import { chromium } from 'playwright';
 const require = createRequire(import.meta.url);
 /** Playwright's own CLI, from this package's dependency (so versions match). */
@@ -41,12 +41,66 @@ export async function launchBrowser() {
         throw err;
     }
 }
+/**
+ * Playwright's ffmpeg build, which `playwright install chromium` downloads
+ * next to the browser. It reads MJPEG, writes VP9 webm and PNG, and has the
+ * crop, scale and pad filters: enough for `rpc record` and its GIF frames.
+ * Found through Playwright's registry, so PLAYWRIGHT_BROWSERS_PATH applies.
+ */
+export function playwrightFfmpeg() {
+    try {
+        const fromPlaywright = createRequire(require.resolve('playwright/package.json'));
+        const core = fromPlaywright('playwright-core/lib/coreBundle');
+        const path = core.registry?.registry?.findExecutable('ffmpeg')?.executablePath();
+        return path && existsSync(path) ? path : undefined;
+    }
+    catch {
+        return undefined; // registry layout changed: fall back to PATH
+    }
+}
+/** `ffmpeg` on PATH, if any. Relative entries (`.`) are skipped: they would run whatever `ffmpeg` sits in the cwd. */
+export function systemFfmpeg(env = process.env) {
+    const names = process.platform === 'win32' ? ['ffmpeg.exe'] : ['ffmpeg'];
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        for (const n of names)
+            if (isAbsolute(dir) && existsSync(join(dir, n)))
+                return join(dir, n);
+    }
+    return undefined;
+}
+/** The ffmpeg `rpc record` uses: Playwright's build first, then PATH. */
+export function findFfmpeg() {
+    const pw = playwrightFfmpeg();
+    if (pw)
+        return { path: pw, source: 'playwright' };
+    const sys = systemFfmpeg();
+    return sys ? { path: sys, source: 'system' } : undefined;
+}
+/** An H.264 encoder in this ffmpeg build (Playwright's has none), for --mp4. */
+export function h264Encoder(ffmpeg) {
+    const r = spawnSync(ffmpeg, ['-hide_banner', '-encoders'], { encoding: 'utf8', timeout: 10_000 });
+    const list = `${r.stdout ?? ''}`;
+    return ['libx264', 'h264_videotoolbox', 'libopenh264'].find(e => new RegExp(`\\s${e}\\s`).test(list));
+}
+/** ffmpeg for `rpc record`, and H.264 for --mp4. */
+export function videoReport() {
+    const ff = findFfmpeg();
+    const sys = systemFfmpeg();
+    const encoder = sys ? h264Encoder(sys) : undefined;
+    return {
+        ffmpeg: ff
+            ? { source: ff.source, path: ff.path }
+            : { source: 'missing', fix: 'rpc record needs ffmpeg: run `npx rpc-agent install` (Playwright downloads its ffmpeg with Chromium), or put ffmpeg on PATH.' },
+        mp4: encoder ? { ok: true, encoder } : { ok: false },
+    };
+}
 /** Check that Chromium is installed and actually launches. */
 export async function doctor() {
     const base = {
         node: process.version,
         playwright: playwrightVersion(),
         browsersPath: process.env.PLAYWRIGHT_BROWSERS_PATH || '(Playwright default cache)',
+        ...videoReport(),
     };
     try {
         const browser = await launchBrowser();

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';
@@ -26,21 +27,7 @@ export async function capture(opts, hooks = {}) {
                 shot = await captureDevice(browser, device, opts, outDir, hooks, auth);
             }
             catch (err) {
-                shot = baseShot(device);
-                if (err instanceof AuthRequiredError) {
-                    shot.status = err.status;
-                    shot.finalUrl = err.finalUrl;
-                    shot.error = err.message;
-                    shot.code = err.code;
-                    shot.hint = err.hint;
-                }
-                else {
-                    const e = explainError(err, { url: opts.url, timeoutMs: opts.timeoutMs, waitFor: opts.waitFor });
-                    shot.error = redact(e.error, auth.secrets);
-                    shot.code = e.code;
-                    if (e.hint)
-                        shot.hint = redact(e.hint, auth.secrets);
-                }
+                shot = { ...baseShot(device), ...describeFailure(err, opts, auth) };
             }
             if (shot.consoleErrors?.length && auth.secrets.length) {
                 shot.consoleErrors = shot.consoleErrors.map(l => redact(l, auth.secrets));
@@ -57,6 +44,18 @@ export async function capture(opts, hooks = {}) {
             await browser.close();
     }
 }
+/** A device's navigation/capture failure as `{ error, code, hint }`, secrets scrubbed. */
+export function describeFailure(err, opts, auth) {
+    if (err instanceof AuthRequiredError) {
+        return { status: err.status, finalUrl: err.finalUrl, error: err.message, code: err.code, hint: err.hint };
+    }
+    const e = explainError(err, { url: opts.url, timeoutMs: opts.timeoutMs, waitFor: opts.waitFor });
+    return {
+        error: redact(e.error, auth.secrets),
+        code: e.code,
+        ...(e.hint ? { hint: redact(e.hint, auth.secrets) } : {}),
+    };
+}
 function baseShot(device) {
     return {
         device: device.id,
@@ -65,7 +64,8 @@ function baseShot(device) {
         dpr: device.dpr,
     };
 }
-async function captureDevice(browser, device, opts, outDir, hooks, auth) {
+/** A fresh context for one device: viewport, DPR, mobile emulation, media features and auth state. */
+export async function newDeviceContext(browser, device, opts, auth) {
     const emu = opts.emulate ? emulationFor(device) : undefined;
     const context = await browser.newContext({
         viewport: { width: device.width, height: device.height },
@@ -80,15 +80,19 @@ async function captureDevice(browser, device, opts, outDir, hooks, auth) {
     });
     if (auth.cookies.length)
         await context.addCookies(auth.cookies);
+    return context;
+}
+async function captureDevice(browser, device, opts, outDir, hooks, auth) {
+    const context = await newDeviceContext(browser, device, opts, auth);
     const result = baseShot(device);
     const errors = new Set();
     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;
@@ -108,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.
@@ -218,40 +241,20 @@ 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)`;
 /**
  * Network idle (bounded: dev servers with HMR or analytics beacons may never
  * go idle), web fonts, and pending <img> loads.
  */
-async function settle(page, timeoutMs) {
+export async function settle(page, timeoutMs) {
     await page
         .waitForLoadState('networkidle', { timeout: Math.min(timeoutMs, 10_000) })
         .catch(() => { });
     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-format.js

@@ -0,0 +1,120 @@
+// Text for `rpc check` results: plain lines (pipes, CI, agents), the rich
+// terminal boxes and the MCP summary. No clack here, so `rpc mcp` and the
+// plain paths can use it.
+import { relative } from 'node:path';
+import { CHECKS } from './check.js';
+/** Findings by check, in report order; checks with nothing to say are left out. */
+export function groupFindings(report) {
+    return CHECKS.map(c => ({ check: c.id, title: c.title, findings: report.findings.filter(f => f.check === c.id) })).filter(g => g.findings.length > 0);
+}
+/** `2 errors, 1 warning` with zero counts left out, or `no issues`. */
+export function countsPhrase(findings) {
+    const n = (s) => findings.filter(f => f.severity === s).length;
+    const parts = [
+        n('error') ? `${n('error')} error${n('error') === 1 ? '' : 's'}` : '',
+        n('warn') ? `${n('warn')} warning${n('warn') === 1 ? '' : 's'}` : '',
+        n('info') ? `${n('info')} info` : '',
+    ].filter(Boolean);
+    return parts.length ? parts.join(', ') : 'no issues';
+}
+export function severityMark(s, c, icons) {
+    if (icons)
+        return s === 'error' ? c.red('✗') : s === 'warn' ? c.yellow('▲') : c.cyan('●');
+    return s === 'error' ? c.red('error') : s === 'warn' ? c.yellow('warn ') : c.cyan('info ');
+}
+/** One finding: mark and message, devices when not all of them, items, then the fix. */
+export function findingLines(f, allDevices, c, o) {
+    const mark = severityMark(f.severity, c, o.icons);
+    const indent = ' '.repeat(o.icons ? 2 : 6);
+    const onSome = f.devices.length < allDevices.length ? c.dim(` (${f.devices.join(', ')})`) : '';
+    const [first = '', ...rest] = wrap(f.message, o.width - indent.length);
+    const out = [`${mark} ${first}${rest.length ? '' : onSome}`];
+    rest.forEach((l, i) => out.push(`${indent}${l}${i === rest.length - 1 ? onSome : ''}`));
+    const max = o.maxItems ?? 5;
+    const items = f.items ?? [];
+    if (!items.length && (f.selector || f.url))
+        out.push(`${indent}${c.cyan(f.selector ?? f.url)}`);
+    for (const item of items.slice(0, max)) {
+        const full = item.selector ?? item.url ?? '';
+        const extra = item.text && item.text !== full ? item.text : '';
+        // Long selectors lose their start: the end names the element.
+        const room = Math.max(20, o.width - indent.length - 2 - (extra ? extra.length + 2 : 0));
+        const where = full.length > room ? `…${full.slice(full.length - room + 1)}` : full;
+        const line = [where ? c.cyan(where) : '', extra ? c.dim(extra) : ''].filter(Boolean).join('  ');
+        out.push(`${indent}${c.dim('·')} ${line}`);
+        if (item.screenshot)
+            out.push(`${indent}  ${c.dim('shot:')} ${rel(item.screenshot)}`);
+    }
+    if (items.length > max)
+        out.push(`${indent}${c.dim(`+${items.length - max} more (see --json)`)}`);
+    const [fix = '', ...more] = wrap(f.fix, o.width - indent.length - 5);
+    out.push(`${indent}${c.dim(`fix: ${fix}`)}`);
+    for (const l of more)
+        out.push(`${indent}${c.dim(`     ${l}`)}`);
+    return out;
+}
+/** Lines for one check's findings. */
+export function groupLines(g, allDevices, c, o) {
+    return g.findings.flatMap(f => findingLines(f, allDevices, c, o));
+}
+/** `iphone-15-pro (393x852 @3x) HTTP 200, CLS 0.000, title "…"` or the failure. */
+export function deviceLine(d, c) {
+    const label = `${d.device} (${d.viewport.width}x${d.viewport.height} @${d.dpr}x)`;
+    if (d.error)
+        return `${c.red('x')} ${label}: ${d.error}`;
+    const status = d.status == null ? 'no status' : d.status >= 400 ? c.red(`HTTP ${d.status}`) : `HTTP ${d.status}`;
+    const cls = d.cls === undefined ? '' : `, CLS ${d.cls.toFixed(3)}`;
+    return `${c.green('ok')} ${label} ${status}${cls}${d.mobile ? '' : c.dim(' (no phone checks)')}`;
+}
+/** Plain output for pipes and CI: device lines, findings by check, the summary line. */
+export function plainReport(report, c, width = 100) {
+    const all = report.devices.map(d => d.device);
+    const out = [];
+    for (const g of groupFindings(report)) {
+        out.push('', `${g.title}: ${countsPhrase(g.findings)}`);
+        for (const l of groupLines(g, all, c, { icons: false, width }))
+            out.push(`  ${l}`);
+    }
+    return out.join('\n');
+}
+/** Short text for agents (MCP): the counts, then one line per error and warning. */
+export function textSummary(report) {
+    const s = report.summary;
+    const lines = [
+        `${report.url}: ${s.errors} error(s), ${s.warnings} warning(s), ${s.info} info on ${report.devices.map(d => d.device).join(', ')}.`,
+    ];
+    for (const d of report.devices) {
+        if (d.error)
+            lines.push(`FAILED ${d.device}: ${d.error}${d.hint ? `\n  hint: ${d.hint}` : ''}`);
+    }
+    const top = report.findings.filter(f => f.severity !== 'info');
+    for (const f of top.slice(0, 25)) {
+        const where = f.selector ?? f.url;
+        lines.push(`${f.severity === 'error' ? 'ERROR' : 'WARN'} [${f.id}] ${f.message}${where ? ` at ${where}` : ''}`);
+    }
+    if (top.length > 25)
+        lines.push(`… ${top.length - 25} more in the JSON report.`);
+    if (!top.length)
+        lines.push('No errors or warnings.');
+    return lines.join('\n');
+}
+function rel(p) {
+    const r = relative(process.cwd(), p);
+    return r.startsWith('..') ? p : r;
+}
+function wrap(text, width) {
+    const out = [];
+    let line = '';
+    for (const word of text.split(/\s+/)) {
+        if (line && line.length + 1 + word.length > width) {
+            out.push(line);
+            line = word;
+        }
+        else {
+            line = line ? `${line} ${word}` : word;
+        }
+    }
+    if (line)
+        out.push(line);
+    return out;
+}