rpc-agent 0.0.0-stage → 0.4.0

package/dist/capture.js

@@ -0,0 +1,274 @@
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
+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 { 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);
+    const auth = hooks.auth ?? resolveAuth(opts.url, opts.auth ?? {});
+    await mkdir(outDir, { recursive: true });
+    if (auth.summary)
+        hooks.onAuth?.(auth.summary);
+    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, 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);
+                }
+            }
+            if (shot.consoleErrors?.length && auth.secrets.length) {
+                shot.consoleErrors = shot.consoleErrors.map(l => redact(l, auth.secrets));
+            }
+            if (!hooks.keepBuffers)
+                delete shot.buffers;
+            hooks.onDevice?.(shot);
+            shots.push(shot);
+        }
+        return { url: opts.url, outDir, shots, ...(auth.summary ? { auth: auth.summary } : {}) };
+    }
+    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, auth) {
+    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
+        ...(auth.state ? { storageState: auth.state } : {}),
+    });
+    if (auth.cookies.length)
+        await context.addCookies(auth.cookies);
+    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('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);
+        // A login page instead of the requested one: say so rather than capture it.
+        const checkLogin = () => {
+            if (redirectedToLogin(opts.url, page.url()))
+                throw new AuthRequiredError(opts.url, page.url(), result.status ?? null);
+        };
+        checkLogin();
+        if (opts.waitFor) {
+            try {
+                await page.waitForSelector(opts.waitFor, { state: 'visible', timeout: opts.timeoutMs });
+            }
+            catch (err) {
+                checkLogin();
+                throw err;
+            }
+        }
+        if (opts.fullPage) {
+            await warmUpScroll(page, opts.maxHeight);
+            await settle(page, opts.timeoutMs);
+        }
+        if (opts.waitMs > 0)
+            await page.waitForTimeout(opts.waitMs);
+        checkLogin();
+        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}`;
+}

package/dist/cli.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { ArgError, parseCli, USAGE } from './args.js';
+import { clearSessions, describeAuth, listSessions, localTime, sessionsDir } from './auth.js';
+import { doctor, installChromium } from './browser.js';
+import { capture } from './capture.js';
+import { CATEGORY_LABELS, CATEGORY_ORDER, DEVICE_ALIASES, DEVICES } from './devices.js';
+import { currentMode, openPath, waitForEnter } from './term.js';
+const NO_PAINT = { ok: s => s, bad: s => s, warn: s => s };
+let paint = NO_PAINT;
+async function plainPaint() {
+    if (!currentMode().color)
+        return NO_PAINT;
+    const { default: pc } = await import('picocolors');
+    const c = pc.createColors(true);
+    return { ok: c.green, bad: c.red, warn: c.yellow };
+}
+// Loaded only for rich (interactive terminal) runs; `rpc mcp` and --json
+// never import clack.
+async function loadUi() {
+    const ui = await import('./ui.js');
+    return { ui, c: ui.colors(currentMode().color) };
+}
+async function main(argv) {
+    const cmd = parseCli(argv);
+    if (cmd.command === 'mcp') {
+        const { runMcpServer } = await import('./mcp.js');
+        await runMcpServer();
+        return -1; // keep running; stdio transport owns the process
+    }
+    const json = 'json' in cmd && cmd.json;
+    const mode = currentMode(json);
+    if (!mode.rich && !json)
+        paint = await plainPaint();
+    switch (cmd.command) {
+        case 'help': {
+            if (argv.length === 0 && mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runInteractive(c);
+            }
+            if (!cmd.topic && !mode.rich) {
+                process.stdout.write(USAGE);
+                return 0;
+            }
+            const { commandHelp, richHelp } = await import('./help.js');
+            const { default: pc } = await import('picocolors');
+            const c = pc.createColors(mode.color);
+            process.stdout.write(cmd.topic ? commandHelp(cmd.topic, c) : richHelp(c));
+            return 0;
+        }
+        case 'version': {
+            const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+            console.log(pkg.version);
+            return 0;
+        }
+        case 'devices':
+            if (cmd.json) {
+                console.log(JSON.stringify({ devices: DEVICES, aliases: DEVICE_ALIASES }, null, 2));
+            }
+            else if (mode.rich) {
+                const { ui, c } = await loadUi();
+                ui.printDevices(c);
+            }
+            else {
+                process.stdout.write(formatDeviceTable());
+            }
+            return 0;
+        case 'doctor': {
+            if (mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runDoctor(doctor, c);
+            }
+            const report = await doctor();
+            if (cmd.json)
+                console.log(JSON.stringify(report, null, 2));
+            else
+                printDoctor(report);
+            return report.ok ? 0 : 1;
+        }
+        case 'install': {
+            const code = await installChromium({ headed: Boolean(cmd.headed) });
+            if (code !== 0)
+                return code;
+            if (mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runDoctor(doctor, c);
+            }
+            const report = await doctor();
+            printDoctor(report);
+            return report.ok ? 0 : 1;
+        }
+        case 'shot': {
+            if (mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runShot(cmd.options, { open: cmd.open }, c);
+            }
+            const result = await capture(cmd.options, cmd.json ? {} : { onDevice: printShot, onAuth: a => console.log(`auth: ${describeAuth(a)}`) });
+            if (cmd.json)
+                console.log(JSON.stringify(result, null, 2));
+            if (cmd.open && result.shots.some(s => !s.error))
+                openPath(result.outDir);
+            return result.shots.some(s => s.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`);
+            }
+            if (mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runLogin(cmd, c);
+            }
+            return plainLogin(cmd);
+        }
+        case 'sessions': {
+            if (mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runSessions(cmd.action, cmd.origin, c);
+            }
+            if (cmd.action === 'clear') {
+                const gone = await clearSessions(cmd.origin);
+                if (cmd.json)
+                    console.log(JSON.stringify({ removed: gone }, null, 2));
+                else if (gone.length === 0)
+                    console.log(cmd.origin ? `No saved session for ${cmd.origin}` : 'No saved sessions');
+                else
+                    for (const o of gone)
+                        console.log(`removed ${o}`);
+                return 0;
+            }
+            const list = await listSessions();
+            if (cmd.json)
+                console.log(JSON.stringify({ dir: sessionsDir(), sessions: list }, null, 2));
+            else if (list.length === 0)
+                console.log(`No saved sessions in ${sessionsDir()}. Create one with: rpc login <url>`);
+            else
+                for (const s of list)
+                    console.log(sessionLine(s));
+            return 0;
+        }
+    }
+}
+async function plainLogin(cmd) {
+    const { formLogin, interactiveLogin } = await import('./login.js');
+    let result;
+    if (cmd.form) {
+        if (!cmd.json)
+            console.log(`signing in at ${cmd.url} (headless form)`);
+        result = await formLogin(cmd, cmd.form);
+    }
+    else {
+        const enter = waitForEnter();
+        try {
+            result = await interactiveLogin(cmd, enter.promise, () => {
+                if (!cmd.json)
+                    console.log(`Opened ${cmd.url}. Sign in in the browser window, then press Enter here (or close the window).`);
+            });
+        }
+        finally {
+            enter.stop();
+        }
+    }
+    if (cmd.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(`${paint.ok('saved')} session for ${result.origin}: ${result.path} (${result.cookies} cookie(s), ${result.localStorage} localStorage origin(s))`);
+        if (result.stillOnLogin) {
+            console.error(`${paint.warn('warning:')} the page was still on a login URL (${result.finalUrl}); the sign-in may not have finished`);
+        }
+    }
+    return 0;
+}
+function sessionLine(s) {
+    const when = localTime;
+    const parts = [s.origin, `${s.cookies} cookie(s)`];
+    if (s.savedAt)
+        parts.push(`saved ${when(s.savedAt)}`);
+    if (s.expired)
+        parts.push(paint.bad(`expired ${when(s.expires)}`));
+    else if (s.expires)
+        parts.push(`expires ${when(s.expires)}`);
+    parts.push(rel(s.path));
+    return parts.join('  ');
+}
+function rel(p) {
+    const r = relative(process.cwd(), p);
+    return r.startsWith('..') ? p : r;
+}
+function printDoctor(r) {
+    console.log(`node        ${r.node}`);
+    console.log(`playwright  ${r.playwright}`);
+    console.log(`browsers    ${r.browsersPath}`);
+    if (r.ok) {
+        console.log(`chromium    ${paint.ok('ok')} (${r.version})`);
+        return;
+    }
+    console.log(`chromium    ${paint.bad(r.chromium)}`);
+    console.error(`rpc: ${r.error}`);
+    if (r.chromium === 'missing')
+        console.error('Run `rpc install` to download it now.');
+}
+function printShot(s) {
+    const label = `${s.device} (${s.viewport.width}x${s.viewport.height} @${s.dpr}x)`;
+    if (s.error) {
+        console.error(`${paint.bad('x')} ${label}: ${s.error}`);
+        if (s.hint)
+            console.error(`   ${paint.warn('hint:')} ${s.hint}`);
+        return;
+    }
+    const lines = [`${paint.ok('ok')} ${label}${s.status && s.status >= 400 ? ` HTTP ${s.status}` : ''}`];
+    if (s.shot) {
+        const extra = [
+            s.segments && s.segments > 1 ? `${s.segments} segments stitched` : '',
+            s.clipped ? `clipped at ${s.capturedHeight} of ${s.scrollHeight} css px` : '',
+        ].filter(Boolean);
+        lines.push(`   ${rel(s.shot.path)}  ${s.shot.width}x${s.shot.height}${extra.length ? ` (${extra.join(', ')})` : ''}`);
+    }
+    if (s.framed)
+        lines.push(`   ${rel(s.framed.path)}  ${s.framed.width}x${s.framed.height}`);
+    if (s.slices?.saved && s.slices.items[0]?.path) {
+        const first = rel(s.slices.items[0].path);
+        lines.push(`   ${first.replace(/-slice-\d+\.jpg$/, '-slice-NN.jpg')}  ${s.slices.total} slice(s), ${s.slices.items[0].width}px wide`);
+    }
+    if (s.consoleErrors?.length)
+        lines.push(`   ${s.consoleErrors.length} console error(s), first: ${s.consoleErrors[0]}`);
+    console.log(lines.join('\n'));
+}
+export function formatDeviceTable() {
+    const out = [];
+    for (const cat of CATEGORY_ORDER) {
+        out.push(CATEGORY_LABELS[cat]);
+        for (const d of DEVICES.filter(x => x.category === cat)) {
+            out.push(`  ${d.id.padEnd(20)} ${`${d.width}x${d.height}`.padEnd(10)} @${String(d.dpr).padEnd(6)} ${d.name}`);
+        }
+        out.push('');
+    }
+    out.push('Aliases');
+    for (const [alias, id] of Object.entries(DEVICE_ALIASES))
+        out.push(`  ${alias.padEnd(20)} -> ${id}`);
+    return out.join('\n') + '\n';
+}
+main(process.argv.slice(2)).then(code => {
+    if (code >= 0)
+        process.exitCode = code;
+}, err => {
+    if (err instanceof ArgError) {
+        console.error(`rpc: ${err.message}`);
+        process.exitCode = 2;
+    }
+    else {
+        console.error(`rpc: ${err.message}`);
+        process.exitCode = 1;
+    }
+});

package/dist/composite.js

@@ -0,0 +1,115 @@
+import { bezelLayoutFor, loadBezelSvg } from './bezel.js';
+/** Any origin works; requests to it never leave the process (page.route). */
+const ORIGIN = 'http://rpc-compositor.invalid';
+/** Long-side cap for framed output so 3x phones and 2x 27" displays stay sane. */
+export const MAX_FRAMED_PX = 4096;
+/**
+ * Serve `html` at ORIGIN/ and `images` at ORIGIN/shot.png (the first) and
+ * ORIGIN/img/<n>.png from a throwaway page, then run `fn`. Routing avoids
+ * stuffing multi-MB data: URLs into setContent.
+ */
+async function withStage(browser, viewport, deviceScaleFactor, html, images, fn) {
+    const list = Array.isArray(images) ? images : [images];
+    const context = await browser.newContext({ viewport, deviceScaleFactor });
+    try {
+        const page = await context.newPage();
+        await page.route(`${ORIGIN}/**`, route => {
+            const path = new URL(route.request().url()).pathname;
+            const m = /^\/img\/(\d+)\.png$/.exec(path);
+            const img = path === '/shot.png' ? list[0] : m ? list[Number(m[1])] : undefined;
+            if (img)
+                return route.fulfill({ status: 200, contentType: 'image/png', body: img });
+            if (path !== '/')
+                return route.fulfill({ status: 404 });
+            return route.fulfill({ status: 200, contentType: 'text/html', body: html });
+        });
+        await page.goto(`${ORIGIN}/`);
+        // String predicate: see the note on in-page scripts in capture.ts.
+        await page.waitForFunction(`Array.from(document.images).every(i => i.complete)`);
+        return await fn(page);
+    }
+    finally {
+        await context.close();
+    }
+}
+/** Strip the root <svg>'s fixed width/height so CSS can size it, as RPC does. */
+function prepareSvg(svg) {
+    return svg.replace(/<svg\b[^>]*>/, tag => tag.replace(/\s(width|height)="[^"]*"/g, '').replace('<svg', '<svg style="position:absolute;left:0;top:0;width:100%;height:100%"'));
+}
+/**
+ * Composite a viewport screenshot into the device bezel. Mirrors RPC's
+ * frame.ts: SVG fills the outer box underneath, the page sits on top at the
+ * screen rect with the screen's corner radius. Output has a transparent
+ * background and the device's DPR (capped by MAX_FRAMED_PX).
+ */
+export async function renderFramed(browser, device, viewportPng) {
+    const layout = bezelLayoutFor(device);
+    const { screen } = layout;
+    const scale = Math.min(device.dpr, MAX_FRAMED_PX / Math.max(layout.outerWidth, layout.outerHeight));
+    const html = `<!doctype html><html><head><style>
+  html,body{margin:0;background:transparent}
+  #frame{position:relative;width:${layout.outerWidth}px;height:${layout.outerHeight}px}
+  #bezel{position:absolute;inset:0;z-index:1}
+  #screen{position:absolute;z-index:2;display:block;left:${screen.x}px;top:${screen.y}px;
+    width:${screen.width}px;height:${screen.height}px;border-radius:${screen.radius}px;object-fit:fill}
+</style></head><body><div id="frame"><div id="bezel">${prepareSvg(loadBezelSvg(layout.src))}</div>
+<img id="screen" src="/shot.png" alt=""></div></body></html>`;
+    return withStage(browser, { width: layout.outerWidth, height: layout.outerHeight }, scale, html, viewportPng, page => page.locator('#frame').screenshot({ omitBackground: true, type: 'png' }));
+}
+/**
+ * Small JPEG for returning inline over MCP. Tall full-page shots are cropped
+ * to the top `maxAspect` region first so text is still legible after scaling.
+ */
+export async function renderPreview(browser, png, size, { maxDim = 1024, maxAspect = 3, quality = 70 } = {}) {
+    const srcH = Math.min(size.height, Math.round(size.width * maxAspect));
+    const cropped = srcH < size.height;
+    const scale = Math.min(1, maxDim / Math.max(size.width, srcH));
+    const width = Math.max(1, Math.round(size.width * scale));
+    const height = Math.max(1, Math.round(srcH * scale));
+    const html = `<!doctype html><html><head><style>
+  html,body{margin:0;background:#fff}
+  #c{width:${width}px;height:${height}px;overflow:hidden}
+  img{display:block;width:${width}px;height:auto}
+</style></head><body><div id="c"><img src="/shot.png" alt=""></div></body></html>`;
+    const data = await withStage(browser, { width, height }, 1, html, png, page => page.locator('#c').screenshot({ type: 'jpeg', quality }));
+    return { data, width, height, cropped };
+}
+/**
+ * Render review slices (JPEG) from full-page capture segments. The segments
+ * are stacked at preview scale in one compositor page and each slice is a
+ * clipped view of that stack, so neither the page nor any slice ever needs a
+ * bitmap taller than a single segment.
+ *
+ * `cssWidth` is the captured width in CSS px; `scale` is output px per CSS px.
+ */
+export async function renderSlices(browser, segments, slices, cssWidth, scale, quality = 70) {
+    if (slices.length === 0)
+        return [];
+    const width = Math.max(1, Math.round(cssWidth * scale));
+    const maxH = Math.max(...slices.map(s => Math.round(s.height * scale)));
+    const imgs = segments
+        .map((seg, i) => 
+    // Whole-pixel edges so adjacent segments meet without a blended seam row.
+    `<img src="/img/${i}.png" alt="" style="position:absolute;left:0;top:${Math.round(seg.y * scale)}px;` +
+        `width:${width}px;height:${Math.round((seg.y + seg.height) * scale) - Math.round(seg.y * scale)}px">`)
+        .join('');
+    const html = `<!doctype html><html><head><style>
+  html,body{margin:0;background:#fff}
+  #c{position:relative;width:${width}px;height:${maxH}px;overflow:hidden}
+  #s{position:absolute;left:0;top:0;width:${width}px}
+  img{display:block}
+</style></head><body><div id="c"><div id="s">${imgs}</div></div></body></html>`;
+    return withStage(browser, { width, height: maxH }, 1, html, segments.map(s => s.png), async (page) => {
+        const out = [];
+        for (const slice of slices) {
+            const pxHeight = Math.max(1, Math.round(slice.height * scale));
+            await page.evaluate(`(() => {
+            document.getElementById('c').style.height = '${pxHeight}px';
+            document.getElementById('s').style.transform = 'translateY(${-Math.round(slice.y * scale)}px)';
+          })()`);
+            const data = await page.locator('#c').screenshot({ type: 'jpeg', quality });
+            out.push({ ...slice, data, width, pxHeight });
+        }
+        return out;
+    });
+}