rpc-agent 0.0.0-stage → 0.3.1

package/assets/bezels/windows-laptop.svg

@@ -0,0 +1,84 @@
+<svg width="1488" height="831" viewBox="0 0 1488 831" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g filter="url(#filter0_f_5_6085)">
+<rect x="12" y="817" width="1464" height="2" rx="1" fill="black"/>
+</g>
+<g filter="url(#filter1_f_5_6085)">
+<rect x="13" y="818" width="1462" height="1" rx="0.5" fill="black" fill-opacity="0.6"/>
+</g>
+<g filter="url(#filter2_ii_5_6085)">
+<rect x="12" y="791" width="1464" height="26" rx="1" fill="url(#paint0_linear_5_6085)"/>
+<rect x="12" y="791" width="1464" height="26" rx="1" fill="url(#paint1_linear_5_6085)" fill-opacity="0.2"/>
+</g>
+<path d="M181 0.5H1307C1318.87 0.5 1328.5 10.1259 1328.5 22V790.5H159.5V22C159.5 10.1259 169.126 0.5 181 0.5Z" fill="#D6D6D6" stroke="#CCCCCC"/>
+<g filter="url(#filter3_i_5_6085)">
+<rect x="180" y="21" width="1128" height="754" rx="4" fill="white" fill-opacity="0.01"/>
+</g>
+<g filter="url(#filter4_i_5_6085)">
+<path d="M162 23C162 11.9543 170.954 3 182 3H1306C1317.05 3 1326 11.9543 1326 23V791H162V23Z" fill="url(#paint2_radial_5_6085)"/>
+</g>
+<defs>
+<filter id="filter0_f_5_6085" x="0" y="805" width="1488" height="26" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape"/>
+<feGaussianBlur stdDeviation="6" result="effect1_foregroundBlur_5_6085"/>
+</filter>
+<filter id="filter1_f_5_6085" x="10" y="815" width="1468" height="7" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape"/>
+<feGaussianBlur stdDeviation="1.5" result="effect1_foregroundBlur_5_6085"/>
+</filter>
+<filter id="filter2_ii_5_6085" x="12" y="790" width="1464" height="27" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feOffset dy="-2"/>
+<feGaussianBlur stdDeviation="0.5"/>
+<feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/>
+<feColorMatrix type="matrix" values="0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0.7 0"/>
+<feBlend mode="normal" in2="shape" result="effect1_innerShadow_5_6085"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feOffset dy="-1"/>
+<feGaussianBlur stdDeviation="0.5"/>
+<feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/>
+<feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.3 0"/>
+<feBlend mode="normal" in2="effect1_innerShadow_5_6085" result="effect2_innerShadow_5_6085"/>
+</filter>
+<filter id="filter3_i_5_6085" x="180" y="21" width="1128" height="754" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feOffset/>
+<feGaussianBlur stdDeviation="1.5"/>
+<feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/>
+<feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.24 0"/>
+<feBlend mode="normal" in2="shape" result="effect1_innerShadow_5_6085"/>
+</filter>
+<filter id="filter4_i_5_6085" x="162" y="3" width="1164" height="788" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feMorphology radius="1" operator="erode" in="SourceAlpha" result="effect1_innerShadow_5_6085"/>
+<feOffset/>
+<feGaussianBlur stdDeviation="1"/>
+<feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/>
+<feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.4 0"/>
+<feBlend mode="normal" in2="shape" result="effect1_innerShadow_5_6085"/>
+</filter>
+<linearGradient id="paint0_linear_5_6085" x1="12" y1="804" x2="1476" y2="804" gradientUnits="userSpaceOnUse">
+<stop stop-color="#C6C5C5"/>
+<stop offset="0.00868664" stop-color="#FEFEFE"/>
+<stop offset="0.0311419" stop-color="#E3E3E3"/>
+<stop offset="0.962505" stop-color="#E7E6E6"/>
+<stop offset="0.992057" stop-color="white"/>
+<stop offset="1" stop-color="#C6C5C5"/>
+</linearGradient>
+<linearGradient id="paint1_linear_5_6085" x1="744" y1="791" x2="744" y2="817" gradientUnits="userSpaceOnUse">
+<stop stop-color="#EFEFEF"/>
+<stop offset="1" stop-color="#DBDBDB"/>
+</linearGradient>
+<radialGradient id="paint2_radial_5_6085" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(248 83.5) rotate(33.6577) scale(1470.51 2172.18)">
+<stop offset="0.155831" stop-color="white" stop-opacity="0.24"/>
+<stop offset="1" stop-color="white" stop-opacity="0"/>
+</radialGradient>
+</defs>
+</svg>

package/dist/args.js

@@ -0,0 +1,189 @@
+import { parseArgs } from 'node:util';
+import { resolveDevices } from './devices.js';
+import { COLOR_SCHEMES, defaultShotOptions, } from './options.js';
+export const HELP_TOPICS = ['shot', 'devices', 'doctor', 'install', 'mcp'];
+function isTopic(s) {
+    return HELP_TOPICS.includes(s ?? '');
+}
+function wantsHelp(args) {
+    return args.includes('--help') || args.includes('-h');
+}
+export class ArgError extends Error {
+    name = 'ArgError';
+}
+export const USAGE = `rpc - screenshot a URL at device viewports, optionally in device bezels
+
+Usage:
+  rpc shot <url> [options]   capture screenshots
+  rpc devices [--json]       list device ids and aliases
+  rpc mcp                    run the MCP server on stdio
+  rpc doctor [--json]        check that Playwright's Chromium is installed and launches
+  rpc install                download Playwright's Chromium (same version rpc uses)
+
+Shot options:
+  -d, --devices <ids>        comma-separated device ids or aliases
+                             (default: iphone-15-pro,desktop-1440)
+  -b, --bezels               frame each shot in its device bezel
+  -f, --full-page            capture the full scroll height (stitched, any height)
+      --slices               with --full-page: also write viewport-tall JPEG
+                             review slices (<stem>-slice-NN.jpg)
+      --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
+  -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)
+      --color-scheme <s>     light | dark | no-preference
+      --timeout <ms>         navigation timeout (default: 30000)
+      --no-emulate           viewport + DPR only (no mobile UA / touch)
+      --json                 print the result as JSON
+      --open                 open the output folder when done
+
+Run \`rpc help <command>\` for one command's options and examples.
+Run \`rpc\` with no arguments in a terminal for an interactive capture.
+
+Examples:
+  rpc shot localhost:3000 -d iphone-15,ipad,desktop-1440 --bezels
+  rpc shot https://example.com --full-page --color-scheme dark
+`;
+export function parseCli(argv) {
+    const [cmd, ...rest] = argv;
+    switch (cmd) {
+        case undefined:
+        case 'help':
+        case '-h':
+        case '--help': {
+            const topic = rest[0];
+            if (topic === undefined)
+                return { command: 'help' };
+            if (!isTopic(topic))
+                throw new ArgError(`No help for "${topic}". Topics: ${HELP_TOPICS.join(', ')}`);
+            return { command: 'help', topic };
+        }
+        case '-v':
+        case '--version':
+            return { command: 'version' };
+        case 'mcp':
+            if (wantsHelp(rest))
+                return { command: 'help', topic: 'mcp' };
+            return { command: 'mcp' };
+        case 'install':
+            if (wantsHelp(rest))
+                return { command: 'help', topic: 'install' };
+            return { command: 'install' };
+        case 'doctor': {
+            if (wantsHelp(rest))
+                return { command: 'help', topic: 'doctor' };
+            const { values } = parse(rest, { json: { type: 'boolean' } }, false);
+            return { command: 'doctor', json: Boolean(values.json) };
+        }
+        case 'devices': {
+            if (wantsHelp(rest))
+                return { command: 'help', topic: 'devices' };
+            const { values } = parse(rest, { json: { type: 'boolean' } }, false);
+            return { command: 'devices', json: Boolean(values.json) };
+        }
+        case 'shot':
+            return parseShot(rest);
+        default:
+            throw new ArgError(`Unknown command "${cmd}". Run \`rpc --help\`.`);
+    }
+}
+function parseShot(args) {
+    if (wantsHelp(args))
+        return { command: 'help', topic: 'shot' };
+    const { values, positionals } = parse(args, {
+        devices: { type: 'string', short: 'd' },
+        bezels: { type: 'boolean', short: 'b' },
+        'full-page': { type: 'boolean', short: 'f' },
+        out: { type: 'string', short: 'o' },
+        'wait-for': { type: 'string' },
+        wait: { type: 'string' },
+        'color-scheme': { type: 'string' },
+        timeout: { type: 'string' },
+        'no-emulate': { type: 'boolean' },
+        slices: { type: 'boolean' },
+        'slice-width': { type: 'string' },
+        'max-height': { type: 'string' },
+        'reduced-motion': { type: 'boolean' },
+        json: { type: 'boolean' },
+        open: { type: 'boolean' },
+    }, true);
+    if (positionals.length === 0)
+        throw new ArgError('Missing <url>. Usage: rpc shot <url> [options]');
+    if (positionals.length > 1)
+        throw new ArgError(`Expected one URL, got: ${positionals.join(' ')}`);
+    let options;
+    try {
+        options = defaultShotOptions(positionals[0]);
+    }
+    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 (values.bezels)
+        options.bezels = true;
+    if (values['full-page'])
+        options.fullPage = 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') {
+        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 (values['no-emulate'])
+        options.emulate = false;
+    if (values.slices)
+        options.saveSlices = true;
+    if (values['reduced-motion'])
+        options.reducedMotion = true;
+    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);
+    }
+    return { command: 'shot', options, json: Boolean(values.json), open: Boolean(values.open) };
+}
+function parse(args, options, allowPositionals) {
+    try {
+        return parseArgs({ args, options: options, allowPositionals, strict: true });
+    }
+    catch (err) {
+        throw new ArgError(err.message);
+    }
+}
+function splitList(s) {
+    return s.split(',').map(x => x.trim()).filter(Boolean);
+}
+function parseInt_(flag, raw, min, max) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < min || n > max)
+        throw new ArgError(`${flag} must be an integer from ${min} to ${max}`);
+    return n;
+}
+function parseMs(flag, raw) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        throw new ArgError(`${flag} must be a non-negative number of ms`);
+    return Math.round(n);
+}

package/dist/bezel.js

@@ -0,0 +1,74 @@
+// Ported from responsive-point-check lib/bezel-asset.ts (MIT). Portrait only;
+// the browser-extension fetch/cache is replaced by reading from assets/bezels.
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** assets/ sits one level above both src/ (tsx) and dist/ (built). */
+export const ASSETS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'assets');
+/** Per-kind padding around the viewport, verbatim from RPC. Ratios are
+ *  fractions of the viewport dimension so the artwork scales uniformly. */
+export const BEZEL_PADDING = {
+    'phone-island': {
+        topRatio: 32 / 874,
+        bottomRatio: 38 / 874,
+        leftRatio: 22 / 402,
+        rightRatio: 22 / 402,
+        radiusRatio: 50 / 402,
+    },
+    'phone-notch': {
+        topRatio: 28 / 848,
+        bottomRatio: 36 / 848,
+        leftRatio: 20 / 407,
+        rightRatio: 20 / 407,
+        radiusRatio: 50 / 407,
+    },
+    'phone-classic': {
+        topRatio: 28 / 850,
+        bottomRatio: 36 / 850,
+        leftRatio: 18 / 410,
+        rightRatio: 22 / 410,
+        radiusRatio: 50 / 410,
+    },
+    'phone-home': { top: 60, right: 14, bottom: 60, left: 14, radius: 4 },
+    tablet: { top: 56, right: 50, bottom: 56, left: 50, radius: 36 },
+    laptop: {
+        top: 10, right: 180, bottom: 60, left: 180,
+        radius: 22,
+        radiusRatio: 32 / 2032.8,
+    },
+    monitor: {
+        top: 0, right: 0, bottom: 320, left: 0,
+        radius: 20,
+        radiusRatio: 20 / 3082,
+    },
+};
+export function bezelLayoutFor(device) {
+    const src = device.bezelSrc ?? `bezels/${device.bezel}.svg`;
+    if (device.bezelLayout) {
+        const o = device.bezelLayout;
+        return { src, outerWidth: o.outerWidth, outerHeight: o.outerHeight, screen: { ...o.screen } };
+    }
+    const w = device.width;
+    const h = device.height;
+    const p = BEZEL_PADDING[device.bezel];
+    const top = p.topRatio !== undefined ? Math.round(h * p.topRatio) : p.top ?? 0;
+    const bottom = p.bottomRatio !== undefined ? Math.round(h * p.bottomRatio) : p.bottom ?? 0;
+    const left = p.leftRatio !== undefined ? Math.round(w * p.leftRatio) : p.left ?? 0;
+    const right = p.rightRatio !== undefined ? Math.round(w * p.rightRatio) : p.right ?? 0;
+    const radius = p.radiusRatio !== undefined ? Math.round(w * p.radiusRatio) : p.radius ?? 0;
+    return {
+        src,
+        outerWidth: w + left + right,
+        outerHeight: h + top + bottom,
+        screen: { x: left, y: top, width: w, height: h, radius },
+    };
+}
+const svgCache = new Map();
+export function loadBezelSvg(src) {
+    let svg = svgCache.get(src);
+    if (svg === undefined) {
+        svg = readFileSync(resolve(ASSETS_DIR, src), 'utf8');
+        svgCache.set(src, svg);
+    }
+    return svg;
+}

package/dist/browser.js

@@ -0,0 +1,80 @@
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, 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). */
+function playwrightCli() {
+    return resolve(dirname(require.resolve('playwright/package.json')), 'cli.js');
+}
+export function playwrightVersion() {
+    return JSON.parse(readFileSync(require.resolve('playwright/package.json'), 'utf8')).version;
+}
+/**
+ * The command that fixes a missing browser. `rpc install` runs this package's
+ * own Playwright CLI, so the downloaded Chromium matches the version rpc
+ * launches, whether rpc came from npx, a global install or a clone.
+ */
+export function installHint() {
+    return ('Fix: run `npx rpc-agent install` (or `rpc install` if rpc is on your PATH). ' +
+        `It downloads Chromium for Playwright ${playwrightVersion()}, the version rpc uses.`);
+}
+export class BrowserMissingError extends Error {
+    executablePath;
+    name = 'BrowserMissingError';
+    constructor(executablePath) {
+        super(`Playwright's Chromium is not installed${executablePath ? ` (expected ${executablePath})` : ''}. ` + installHint());
+        this.executablePath = executablePath;
+    }
+}
+/** Launch headless Chromium, turning "Executable doesn't exist" into BrowserMissingError. */
+export async function launchBrowser() {
+    try {
+        return await chromium.launch({ headless: true });
+    }
+    catch (err) {
+        const msg = err.message;
+        if (/Executable doesn't exist|playwright install/i.test(msg)) {
+            throw new BrowserMissingError(/Executable doesn't exist at (\S.*?)\s*$/m.exec(msg)?.[1]);
+        }
+        throw err;
+    }
+}
+/** 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)',
+    };
+    try {
+        const browser = await launchBrowser();
+        const version = browser.version();
+        await browser.close();
+        return { ok: true, ...base, chromium: 'ok', version };
+    }
+    catch (err) {
+        if (err instanceof BrowserMissingError) {
+            return { ok: false, ...base, chromium: 'missing', error: err.message, fix: installHint() };
+        }
+        return { ok: false, ...base, chromium: 'launch-failed', error: err.message.split('\n')[0] ?? String(err) };
+    }
+}
+/**
+ * Run `playwright install --only-shell chromium` with this package's
+ * Playwright, streaming its output. rpc always launches headless, which uses
+ * the headless shell, so the full Chrome for Testing build (about 370 MB on
+ * disk) would never run.
+ */
+export function installChromium() {
+    return new Promise((res, rej) => {
+        // Load the CLI through -e with a plain argv[1]. Under npx the real path is
+        // in the `_npx` cache, and Playwright then prints a box telling the user
+        // to install their project's dependencies, which doesn't apply here.
+        const loader = `process.argv.splice(1, 0, 'playwright'); require(${JSON.stringify(playwrightCli())});`;
+        const child = spawn(process.execPath, ['-e', loader, 'install', '--only-shell', 'chromium'], { stdio: 'inherit' });
+        child.on('error', rej);
+        child.on('exit', code => res(code ?? 1));
+    });
+}

package/dist/capture.js

@@ -0,0 +1,241 @@
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
+import { basename, extname, resolve } from 'node:path';
+import { launchBrowser } from './browser.js';
+import { renderFramed, renderSlices } from './composite.js';
+import { explainError } from './errors.js';
+import { emulationFor, resolveDevices } from './devices.js';
+import { pngSize, stitchPngs } from './png.js';
+import { fitsOneCapture, planSegments, planSlices, sliceScale } from './slices.js';
+export { MAX_CAPTURE_PX } from './slices.js';
+export { launchBrowser } from './browser.js';
+export async function capture(opts, hooks = {}) {
+    const devices = resolveDevices(opts.devices);
+    const outDir = resolve(opts.outDir);
+    await mkdir(outDir, { recursive: true });
+    const browser = hooks.browser ?? (await launchBrowser());
+    try {
+        const shots = [];
+        for (const device of devices) {
+            let shot;
+            hooks.onDeviceStart?.(device);
+            try {
+                shot = await captureDevice(browser, device, opts, outDir, hooks);
+            }
+            catch (err) {
+                shot = baseShot(device);
+                const e = explainError(err, { url: opts.url, timeoutMs: opts.timeoutMs, waitFor: opts.waitFor });
+                shot.error = e.error;
+                shot.code = e.code;
+                if (e.hint)
+                    shot.hint = e.hint;
+            }
+            if (!hooks.keepBuffers)
+                delete shot.buffers;
+            hooks.onDevice?.(shot);
+            shots.push(shot);
+        }
+        return { url: opts.url, outDir, shots };
+    }
+    finally {
+        if (!hooks.browser)
+            await browser.close();
+    }
+}
+function baseShot(device) {
+    return {
+        device: device.id,
+        name: device.name,
+        viewport: { width: device.width, height: device.height },
+        dpr: device.dpr,
+    };
+}
+async function captureDevice(browser, device, opts, outDir, hooks) {
+    const emu = opts.emulate ? emulationFor(device) : undefined;
+    const context = await browser.newContext({
+        viewport: { width: device.width, height: device.height },
+        deviceScaleFactor: device.dpr,
+        isMobile: emu?.isMobile ?? false,
+        hasTouch: emu?.hasTouch ?? false,
+        ...(emu?.userAgent ? { userAgent: emu.userAgent } : {}),
+        ...(opts.colorScheme ? { colorScheme: opts.colorScheme } : {}),
+        ...(opts.reducedMotion ? { reducedMotion: 'reduce' } : {}),
+        ignoreHTTPSErrors: true, // self-signed local dev certs
+    });
+    const result = baseShot(device);
+    const errors = new Set();
+    try {
+        const page = await context.newPage();
+        page.on('pageerror', e => errors.add(`pageerror: ${e.message}`));
+        page.on('console', m => {
+            if (m.type() === 'error')
+                errors.add(`console: ${m.text()}`);
+        });
+        const response = await page.goto(opts.url, { waitUntil: 'load', timeout: opts.timeoutMs });
+        result.status = response?.status() ?? null;
+        await settle(page, opts.timeoutMs);
+        if (opts.waitFor) {
+            await page.waitForSelector(opts.waitFor, { state: 'visible', timeout: opts.timeoutMs });
+        }
+        if (opts.fullPage) {
+            await warmUpScroll(page, opts.maxHeight);
+            await settle(page, opts.timeoutMs);
+        }
+        if (opts.waitMs > 0)
+            await page.waitForTimeout(opts.waitMs);
+        result.finalUrl = page.url();
+        result.title = await page.title();
+        result.scrollHeight = await page.evaluate(SCROLL_HEIGHT_JS);
+        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.
+        let viewportPng;
+        if (!opts.fullPage || opts.bezels) {
+            viewportPng = await page.screenshot(shotOpts);
+        }
+        let shotPng;
+        let segments;
+        if (opts.fullPage) {
+            const total = Math.min(result.scrollHeight, opts.maxHeight);
+            result.clipped = result.scrollHeight > opts.maxHeight;
+            result.capturedHeight = total;
+            if (fitsOneCapture(total, device.dpr) && !result.clipped) {
+                // One pass, as in v0.1: no seams, Playwright sizes it.
+                shotPng = await page.screenshot({ ...shotOpts, fullPage: true });
+                segments = [{ y: 0, height: total, png: shotPng }];
+            }
+            else {
+                // Clipped full-page captures render exactly what one tall capture
+                // would (sticky/fixed elements at their scroll-0 position, nothing
+                // scrolls), so the segments stitch without repeated headers.
+                const width = Math.max(device.width, await page.evaluate(SCROLL_WIDTH_JS));
+                segments = [];
+                for (const band of planSegments(total, device.dpr)) {
+                    const png = await page.screenshot({
+                        ...shotOpts,
+                        fullPage: true,
+                        clip: { x: 0, y: band.y, width, height: band.height },
+                    });
+                    segments.push({ ...band, png });
+                }
+                shotPng = await stitchPngs(segments.map(s => s.png));
+            }
+            result.segments = segments.length;
+        }
+        else {
+            shotPng = viewportPng;
+        }
+        result.shot = await save(resolve(outDir, `${base}.png`), shotPng);
+        result.buffers = { shot: shotPng };
+        if (segments && (opts.saveSlices || hooks.inlineSlices)) {
+            const cssWidth = result.shot.width / device.dpr;
+            const scale = sliceScale(cssWidth, device.dpr, opts.sliceWidth);
+            const all = planSlices(device.id, result.capturedHeight, device.height);
+            const save = opts.saveSlices === true ||
+                (opts.saveSlices === undefined && Boolean(hooks.inlineSlices) && all.length > opts.maxSlices);
+            const wanted = save ? all : all.slice(0, opts.maxSlices);
+            const rendered = await renderSlices(browser, segments, wanted, cssWidth, scale);
+            if (save)
+                await removeOldSlices(outDir, base);
+            const items = [];
+            for (const { data, ...info } of rendered) {
+                const item = { ...info };
+                if (save) {
+                    item.path = resolve(outDir, `${base}-slice-${String(info.index).padStart(2, '0')}.jpg`);
+                    await writeFile(item.path, data);
+                }
+                items.push(item);
+            }
+            result.slices = { total: all.length, sliceHeight: device.height, items, saved: save };
+            result.buffers.slices = rendered.map(r => r.data);
+        }
+        if (opts.bezels && viewportPng) {
+            const framedPng = await renderFramed(browser, device, viewportPng);
+            result.framed = await save(resolve(outDir, `${base}-framed.png`), framedPng);
+            result.buffers.framed = framedPng;
+        }
+    }
+    finally {
+        result.consoleErrors = [...errors].slice(0, 20);
+        await context.close();
+    }
+    return result;
+}
+/** Drop `<stem>-slice-NN.jpg` files from earlier runs so a shorter page doesn't leave stale slices. */
+async function removeOldSlices(outDir, base) {
+    const prefix = `${base}-slice-`; // base is a [a-z0-9-] slug
+    for (const f of await readdir(outDir)) {
+        if (f.startsWith(prefix) && /^\d+\.jpg$/.test(f.slice(prefix.length)))
+            await rm(resolve(outDir, f), { force: true });
+    }
+}
+async function save(path, png) {
+    await writeFile(path, png);
+    return { path, ...pngSize(png) };
+}
+// In-page scripts are plain strings: when this file runs through tsx/vitest,
+// esbuild wraps named arrow functions in a `__name()` helper that doesn't
+// exist inside the page, so a serialized function would throw there.
+const WAIT_FOR_ASSETS_JS = `(async () => {
+  const imgs = Array.from(document.images).filter(i => !i.complete);
+  await Promise.race([
+    Promise.all([
+      document.fonts ? document.fonts.ready : null,
+      ...imgs.map(i => new Promise(r => { i.addEventListener('load', r); i.addEventListener('error', r); })),
+    ]),
+    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) {
+    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)));
+}
+/** `<host>[-<path>]-<device>`, e.g. `localhost-3000-about-iphone-15`. */
+export function fileStem(url, deviceId) {
+    const u = new URL(url);
+    let parts;
+    if (u.protocol === 'file:') {
+        parts = `file-${basename(u.pathname, extname(u.pathname))}`;
+    }
+    else {
+        parts = `${u.hostname}${u.port ? `-${u.port}` : ''}${u.pathname}`;
+    }
+    const slug = parts
+        .toLowerCase()
+        .replace(/^www\./, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 80)
+        .replace(/-+$/, '');
+    return `${slug || 'page'}-${deviceId}`;
+}