rpc-agent 0.4.0 → 0.6.0

package/dist/cli.js

@@ -5,14 +5,21 @@ 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 { 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;
+/** The full palette for check output; identity functions unless FORCE_COLOR. */
+let colours;
 async function plainPaint() {
+    const { default: pc } = await import('picocolors');
+    colours = pc.createColors(currentMode().color);
     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 };
 }
@@ -102,6 +109,42 @@ async function main(argv) {
                 openPath(result.outDir);
             return result.shots.some(s => s.error) ? 1 : 0;
         }
+        case 'check': {
+            if (mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runCheck(cmd.options, c);
+            }
+            const report = await runCheck(cmd.options, cmd.json
+                ? {}
+                : {
+                    onAuth: a => console.log(`auth: ${describeAuth(a)}`),
+                    onDevice: d => console.log(deviceLine(d, colours)),
+                });
+            if (cmd.json)
+                console.log(JSON.stringify(report, null, 2));
+            else
+                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`);
@@ -187,12 +230,26 @@ function rel(p) {
     const r = relative(process.cwd(), p);
     return r.startsWith('..') ? p : r;
 }
+function printCheck(report) {
+    const body = plainReport(report, colours);
+    if (body)
+        console.log(body);
+    console.log('');
+    const s = report.summary;
+    const line = summaryLine(s);
+    console.log(s.errors ? paint.bad(line) : s.warnings ? paint.warn(line) : paint.ok(line));
+}
 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)}`);
@@ -224,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)'],
@@ -22,6 +24,33 @@ const AUTH_OPTIONS = [
     ['    --no-session', "don't use the session saved by `rpc login` for this origin"],
     ['    --allow-origin <o>', 'also send headers and loaded cookies to this origin, repeatable'],
 ];
+const CHECK_OPTIONS = [
+    ['-d, --devices <ids>', 'comma-separated device ids or aliases (default: iphone-15-pro,desktop-1440)'],
+    ['    --fail-on <level>', 'error (default) or warn: also exit 1 on warnings'],
+    ['    --shots', 'screenshot the elements behind layout-shift and overflow findings'],
+    ['-o, --out <dir>', 'where --shots writes (default: ./.rpc-shots)'],
+    ['    --wait-for <selector>', 'wait for a CSS selector before checking'],
+    ['    --wait <ms>', 'extra settle delay after the scroll (default: 0)'],
+    ['    --color-scheme <s>', 'light | dark | no-preference'],
+    ['    --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)'],
@@ -47,6 +76,29 @@ export const COMMANDS = {
             ["rpc shot api.example.com/admin --header 'Authorization: Bearer $TOKEN'", ''],
         ],
     },
+    check: {
+        usage: 'rpc check <url> [options]',
+        summary: 'Audit one page before launch: meta and social tags, layout shift (CLS), unlabelled controls, web fonts, ' +
+            'mobile viewport bugs and basics (status, mixed content, console errors). Exits 1 when there are errors.',
+        options: [...CHECK_OPTIONS, ...AUTH_OPTIONS],
+        examples: [
+            ['rpc check localhost:3000', 'phone + desktop'],
+            ['rpc check localhost:3000 --fail-on warn --json', 'CI: fail on warnings too'],
+            ['rpc check example.com -d pixel,iphone-se,desktop --shots', 'more devices, element screenshots'],
+            ['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 ' +
@@ -79,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']],
     },
@@ -94,12 +146,14 @@ export const COMMANDS = {
     },
     mcp: {
         usage: 'rpc mcp',
-        summary: 'Run the MCP server on stdio (tools: screenshot, 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, 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'],