rpc-agent 0.0.0-stage → 0.4.0

package/dist/devices.js

@@ -0,0 +1,407 @@
+// Ported from responsive-point-check lib/devices.ts (MIT). Device data is
+// unchanged; user agents, aliases and lookup helpers are added at the end.
+export const DEVICES = [
+    // ----------------------------------------------------------- Apple Phones
+    {
+        id: 'iphone-se',
+        name: 'iPhone SE',
+        category: 'apple-phone',
+        width: 375,
+        height: 667,
+        dpr: 2,
+        bezel: 'phone-home',
+        bezelSrc: 'bezels/iphone-se.svg',
+        bezelLayout: {
+            outerWidth: 427,
+            outerHeight: 858,
+            screen: { x: 26, y: 95, width: 375, height: 667, radius: 4 },
+        },
+    },
+    {
+        id: 'iphone-11-pro',
+        name: 'iPhone 11 Pro',
+        category: 'apple-phone',
+        width: 375,
+        height: 812,
+        dpr: 3,
+        bezel: 'phone-notch',
+        // Same outer artwork dimensions as iPhone SE in this pack; thinner top
+        // and bottom bezels because it's a notched edge-to-edge display.
+        bezelSrc: 'bezels/iphone-11-pro.svg',
+        bezelLayout: {
+            outerWidth: 427,
+            outerHeight: 858,
+            screen: { x: 26, y: 23, width: 375, height: 812, radius: 40 },
+        },
+    },
+    // iPhone 12 mini — uses iphone-12-mini.svg (artwork 423×858, screen
+    // at (24, 23, 375, 812)). Scale viewport 360/375 = 0.96.
+    {
+        id: 'iphone-12-mini',
+        name: 'iPhone 12 mini',
+        category: 'apple-phone',
+        width: 360,
+        height: 780,
+        dpr: 3,
+        bezel: 'phone-notch',
+        bezelSrc: 'bezels/iphone-12-mini.svg',
+        bezelLayout: {
+            outerWidth: 410,
+            outerHeight: 824,
+            screen: { x: 25, y: 22, width: 360, height: 780, radius: 40 },
+        },
+    },
+    { id: 'iphone-13', name: 'iPhone 13', category: 'apple-phone', width: 390, height: 844, dpr: 3, bezel: 'phone-notch' },
+    { id: 'iphone-14', name: 'iPhone 14', category: 'apple-phone', width: 390, height: 844, dpr: 3, bezel: 'phone-notch' },
+    // iPhone 14 Plus — large notch design. Uses iphone-12-pro-max.svg
+    // (artwork 423×858, screen ~(24, 23, 375, 812)). Scale 428/375 = 1.14.
+    {
+        id: 'iphone-14-plus',
+        name: 'iPhone 14 Plus',
+        category: 'apple-phone',
+        width: 428,
+        height: 926,
+        dpr: 3,
+        bezel: 'phone-notch',
+        bezelSrc: 'bezels/iphone-12-pro-max.svg',
+        bezelLayout: {
+            outerWidth: 482,
+            outerHeight: 978,
+            screen: { x: 30, y: 26, width: 428, height: 926, radius: 46 },
+        },
+    },
+    { id: 'iphone-14-pro', name: 'iPhone 14 Pro', category: 'apple-phone', width: 393, height: 852, dpr: 3, bezel: 'phone-island' },
+    { id: 'iphone-14-pro-max', name: 'iPhone 14 Pro Max', category: 'apple-phone', width: 430, height: 932, dpr: 3, bezel: 'phone-island' },
+    { id: 'iphone-15', name: 'iPhone 15', category: 'apple-phone', width: 393, height: 852, dpr: 3, bezel: 'phone-island' },
+    { id: 'iphone-15-plus', name: 'iPhone 15 Plus', category: 'apple-phone', width: 430, height: 932, dpr: 3, bezel: 'phone-island' },
+    { id: 'iphone-15-pro', name: 'iPhone 15 Pro', category: 'apple-phone', width: 393, height: 852, dpr: 3, bezel: 'phone-island' },
+    { id: 'iphone-15-pro-max', name: 'iPhone 15 Pro Max', category: 'apple-phone', width: 430, height: 932, dpr: 3, bezel: 'phone-island' },
+    { id: 'iphone-16', name: 'iPhone 16', category: 'apple-phone', width: 393, height: 852, dpr: 3, bezel: 'phone-island' },
+    { id: 'iphone-16-pro', name: 'iPhone 16 Pro', category: 'apple-phone', width: 402, height: 874, dpr: 3, bezel: 'phone-island' },
+    { id: 'iphone-16-pro-max', name: 'iPhone 16 Pro Max', category: 'apple-phone', width: 440, height: 956, dpr: 3, bezel: 'phone-island' },
+    // iPhone 17 Pro — uses dedicated iphone-17-pro.svg artwork (1280×2642
+    // body with rx=210, twin-lens orange/coral accent on the back). Iframe
+    // sits within the inner screen rect at (55, 55, 1170, 2532) per the
+    // artwork's white "screen" rectangle. Scale: 402 / 1170 = 0.3436.
+    {
+        id: 'iphone-17-pro',
+        name: 'iPhone 17 Pro',
+        category: 'apple-phone',
+        width: 402,
+        height: 874,
+        dpr: 3,
+        bezel: 'phone-island',
+        bezelSrc: 'bezels/iphone-17-pro.svg',
+        bezelLayout: {
+            outerWidth: 440,
+            outerHeight: 908,
+            screen: { x: 19, y: 19, width: 402, height: 874, radius: 56 },
+        },
+    },
+    {
+        id: 'iphone-17-pro-max',
+        name: 'iPhone 17 Pro Max',
+        category: 'apple-phone',
+        width: 440,
+        height: 956,
+        dpr: 3,
+        bezel: 'phone-island',
+        bezelSrc: 'bezels/iphone-17-pro.svg',
+        bezelLayout: {
+            outerWidth: 482,
+            outerHeight: 994,
+            screen: { x: 21, y: 21, width: 440, height: 956, radius: 60 },
+        },
+    },
+    // --------------------------------------------------------- Android Phones
+    { id: 'pixel-6', name: 'Pixel 6', category: 'android-phone', width: 412, height: 915, dpr: 2.625, bezel: 'phone-classic' },
+    { id: 'pixel-7', name: 'Pixel 7', category: 'android-phone', width: 412, height: 915, dpr: 2.625, bezel: 'phone-classic' },
+    { id: 'pixel-7-pro', name: 'Pixel 7 Pro', category: 'android-phone', width: 412, height: 892, dpr: 3.5, bezel: 'phone-classic' },
+    { id: 'pixel-8', name: 'Pixel 8', category: 'android-phone', width: 412, height: 915, dpr: 2.625, bezel: 'phone-classic' },
+    { id: 'pixel-8-pro', name: 'Pixel 8 Pro', category: 'android-phone', width: 448, height: 998, dpr: 3, bezel: 'phone-classic' },
+    { id: 'pixel-9', name: 'Pixel 9', category: 'android-phone', width: 412, height: 915, dpr: 2.625, bezel: 'phone-classic' },
+    { id: 'pixel-9-pro', name: 'Pixel 9 Pro', category: 'android-phone', width: 412, height: 915, dpr: 3, bezel: 'phone-classic' },
+    { id: 'galaxy-s22', name: 'Galaxy S22', category: 'android-phone', width: 360, height: 780, dpr: 3, bezel: 'phone-classic' },
+    { id: 'galaxy-s23', name: 'Galaxy S23', category: 'android-phone', width: 360, height: 780, dpr: 3, bezel: 'phone-classic' },
+    { id: 'galaxy-s24', name: 'Galaxy S24', category: 'android-phone', width: 384, height: 854, dpr: 3, bezel: 'phone-classic' },
+    { id: 'galaxy-s24-ultra', name: 'Galaxy S24 Ultra', category: 'android-phone', width: 412, height: 915, dpr: 3.5, bezel: 'phone-classic' },
+    { id: 'oneplus-11', name: 'OnePlus 11', category: 'android-phone', width: 412, height: 919, dpr: 3, bezel: 'phone-classic' },
+    // ------------------------------------------------------------------ Tablets
+    // iPads use the dedicated ipad.svg (633×908). The kind-default tablet
+    // padding (50/56px absolute) handles the visible bezel.
+    { id: 'ipad-mini-6', name: 'iPad mini', category: 'tablet', width: 744, height: 1133, dpr: 2, bezel: 'tablet', bezelSrc: 'bezels/ipad.svg' },
+    { id: 'ipad-air-11', name: 'iPad Air 11"', category: 'tablet', width: 820, height: 1180, dpr: 2, bezel: 'tablet', bezelSrc: 'bezels/ipad.svg' },
+    { id: 'ipad-pro-11', name: 'iPad Pro 11"', category: 'tablet', width: 834, height: 1194, dpr: 2, bezel: 'tablet', bezelSrc: 'bezels/ipad.svg' },
+    { id: 'ipad-pro-13', name: 'iPad Pro 13"', category: 'tablet', width: 1024, height: 1366, dpr: 2, bezel: 'tablet', bezelSrc: 'bezels/ipad.svg' },
+    { id: 'galaxy-tab-s9', name: 'Galaxy Tab S9', category: 'tablet', width: 800, height: 1280, dpr: 2, bezel: 'tablet' },
+    // ------------------------------------------------------------------ Laptops
+    {
+        id: 'macbook',
+        name: 'MacBook',
+        category: 'laptop',
+        width: 1440,
+        height: 940,
+        dpr: 2,
+        bezel: 'laptop', // bezels/laptop.svg is the macbook artwork (kind default)
+    },
+    // Surface Laptop 13.5" — viewport 1504×1003 matches the artwork's screen
+    // aspect (1.499) almost exactly. Lid: (180, 21)→1128×754, scale 1.333.
+    {
+        id: 'surface-laptop',
+        name: 'Surface Laptop 13.5"',
+        category: 'laptop',
+        width: 1504,
+        height: 1003,
+        dpr: 1.5,
+        bezel: 'laptop',
+        bezelSrc: 'bezels/surface-laptop.svg',
+        bezelLayout: {
+            outerWidth: 1984,
+            outerHeight: 1108,
+            screen: { x: 240, y: 28, width: 1504, height: 1003, radius: 5 },
+        },
+    },
+    // MacBook Air — uses the new high-fidelity Sky Blue M4 artwork
+    // (2048×1241 viewBox; lid path with rx=61 from x=167.97 to 1881.82,
+    // y=0 to ~1145.26; inner screen rect (178.75, 10.78)→(1871.04, 1147.06),
+    // i.e. 1692×1136 inside the lid; keyboard hump and feet below).
+    // Scale 13": 1280 / 1692.3 = 0.7563. Scale 15": 1456 / 1692.3 = 0.8604.
+    {
+        id: 'macbook-air-13',
+        name: 'MacBook Air 13"',
+        category: 'laptop',
+        width: 1280,
+        height: 832,
+        dpr: 2,
+        bezel: 'laptop',
+        bezelSrc: 'bezels/macbook-air.svg',
+        bezelLayout: {
+            outerWidth: 1549,
+            outerHeight: 938,
+            screen: { x: 135, y: 8, width: 1280, height: 832, radius: 6 },
+        },
+    },
+    {
+        id: 'macbook-air-15',
+        name: 'MacBook Air 15"',
+        category: 'laptop',
+        width: 1456,
+        height: 945,
+        dpr: 2,
+        bezel: 'laptop',
+        bezelSrc: 'bezels/macbook-air.svg',
+        bezelLayout: {
+            outerWidth: 1762,
+            outerHeight: 1068,
+            screen: { x: 154, y: 9, width: 1456, height: 945, radius: 7 },
+        },
+    },
+    // MBP 14/16 use the high-fidelity macbook-pro-14.svg artwork.
+    // Lid: x=110, y=2, w=997, h=681. Screen above chin: ~y=2 to y=657 (h=655),
+    // aspect 1.521 — matches MBP 14/16's 1.539 closely.
+    {
+        id: 'macbook-pro-14',
+        name: 'MacBook Pro 14"',
+        category: 'laptop',
+        width: 1512,
+        height: 982,
+        dpr: 2,
+        bezel: 'laptop',
+        bezelSrc: 'bezels/macbook-pro-14.svg',
+        // Scale: 1512 / 997 = 1.516.
+        bezelLayout: {
+            outerWidth: 1843,
+            outerHeight: 1114,
+            screen: { x: 167, y: 3, width: 1512, height: 982, radius: 8 },
+        },
+    },
+    {
+        id: 'macbook-pro-16',
+        name: 'MacBook Pro 16"',
+        category: 'laptop',
+        width: 1728,
+        height: 1117,
+        dpr: 2,
+        bezel: 'laptop',
+        bezelSrc: 'bezels/macbook-pro-14.svg',
+        // Same artwork, scaled by 1728 / 997 = 1.733.
+        bezelLayout: {
+            outerWidth: 2108,
+            outerHeight: 1273,
+            screen: { x: 191, y: 3, width: 1728, height: 1117, radius: 8 },
+        },
+    },
+    // MacBook Pro 13" (M1 / M2 era, 1280×800). Uses the dedicated
+    // macbook-pro-13.svg with chin/keyboard detail. Lid above chin:
+    // (105, 2)→871×565, scale 1280/871 = 1.470.
+    {
+        id: 'macbook-pro-13',
+        name: 'MacBook Pro 13"',
+        category: 'laptop',
+        width: 1280,
+        height: 800,
+        dpr: 2,
+        bezel: 'laptop',
+        bezelSrc: 'bezels/macbook-pro-13.svg',
+        bezelLayout: {
+            outerWidth: 1588,
+            outerHeight: 917,
+            screen: { x: 154, y: 3, width: 1280, height: 800, radius: 8 },
+        },
+    },
+    { id: 'laptop-1280', name: 'Laptop 1280', category: 'laptop', width: 1280, height: 800, dpr: 1, bezel: 'laptop' },
+    { id: 'desktop-1366', name: 'Desktop 1366', category: 'laptop', width: 1366, height: 768, dpr: 1, bezel: 'monitor' },
+    { id: 'desktop-1440', name: 'Desktop 1440', category: 'laptop', width: 1440, height: 900, dpr: 1, bezel: 'monitor' },
+    { id: 'desktop-1536', name: 'Desktop 1536', category: 'laptop', width: 1536, height: 864, dpr: 1, bezel: 'monitor' },
+    { id: 'desktop-1920', name: 'Desktop 1920', category: 'laptop', width: 1920, height: 1080, dpr: 1, bezel: 'monitor' },
+    {
+        id: 'imac-24',
+        name: 'iMac 24"',
+        category: 'laptop',
+        width: 1440,
+        height: 997,
+        dpr: 2,
+        bezel: 'monitor',
+        bezelSrc: 'bezels/imac.svg',
+        bezelLayout: {
+            outerWidth: 1442,
+            outerHeight: 1230,
+            screen: { x: 1, y: 1, width: 1440, height: 997, radius: 24 },
+        },
+    },
+    {
+        id: 'studio-display',
+        name: 'Studio Display 27"',
+        category: 'laptop',
+        width: 2560,
+        height: 1440,
+        dpr: 2,
+        bezel: 'monitor',
+        // Pro Display XDR artwork at scale 0.831 (= 2560 / 3082).
+        bezelLayout: {
+            outerWidth: 2560,
+            outerHeight: 1899,
+            screen: { x: 0, y: 0, width: 2560, height: 1440, radius: 17 },
+        },
+    },
+    {
+        id: 'pro-display-xdr',
+        name: 'Pro Display XDR',
+        category: 'laptop',
+        width: 3008,
+        height: 1692,
+        dpr: 2,
+        bezel: 'monitor',
+        // 1:1 with the artwork (scale 0.976 ≈ identity for our purposes).
+        bezelLayout: {
+            outerWidth: 3008,
+            outerHeight: 2232,
+            screen: { x: 0, y: 0, width: 3008, height: 1692, radius: 20 },
+        },
+    },
+];
+export const DEVICES_BY_ID = Object.fromEntries(DEVICES.map(d => [d.id, d]));
+export const CATEGORY_LABELS = {
+    'apple-phone': 'Apple Phones',
+    'android-phone': 'Android Phones',
+    tablet: 'Tablets',
+    laptop: 'Laptops',
+};
+export const CATEGORY_ORDER = [
+    'apple-phone',
+    'android-phone',
+    'tablet',
+    'laptop',
+];
+export const DEFAULT_DEVICE_ID = 'iphone-15-pro';
+// ------------------------------------------------------------------ Additions
+const UA_IOS = 'Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1';
+const UA_IPAD = 'Mozilla/5.0 (iPad; CPU OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1';
+const UA_ANDROID_PHONE = 'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Mobile Safari/537.36';
+const UA_ANDROID_TABLET = 'Mozilla/5.0 (Linux; Android 14; SM-X710) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36';
+/** Category-level emulation. RPC itself sets no UA (it renders in an iframe
+ *  inside desktop Chrome); agents usually want the mobile UA + touch. */
+export function emulationFor(device) {
+    switch (device.category) {
+        case 'apple-phone':
+            return { userAgent: UA_IOS, isMobile: true, hasTouch: true };
+        case 'android-phone':
+            return { userAgent: UA_ANDROID_PHONE, isMobile: true, hasTouch: true };
+        case 'tablet':
+            return device.id.startsWith('ipad')
+                ? { userAgent: UA_IPAD, isMobile: true, hasTouch: true }
+                : { userAgent: UA_ANDROID_TABLET, isMobile: true, hasTouch: true };
+        case 'laptop':
+            return { userAgent: undefined, isMobile: false, hasTouch: false };
+    }
+}
+/** Short names agents are likely to guess. */
+export const DEVICE_ALIASES = {
+    iphone: 'iphone-15-pro',
+    mobile: 'iphone-15-pro',
+    phone: 'iphone-15-pro',
+    android: 'pixel-8',
+    pixel: 'pixel-8',
+    galaxy: 'galaxy-s24',
+    ipad: 'ipad-air-11',
+    tablet: 'ipad-air-11',
+    macbook: 'macbook-air-13',
+    laptop: 'laptop-1280',
+    desktop: 'desktop-1440',
+    imac: 'imac-24',
+};
+export const DEFAULT_DEVICES = ['iphone-15-pro', 'desktop-1440'];
+export class UnknownDeviceError extends Error {
+    input;
+    suggestions;
+    constructor(input, suggestions) {
+        super(`Unknown device "${input}".` +
+            (suggestions.length ? ` Did you mean: ${suggestions.join(', ')}?` : '') +
+            ' Run `rpc devices` to list all ids.');
+        this.input = input;
+        this.suggestions = suggestions;
+        this.name = 'UnknownDeviceError';
+    }
+}
+export function resolveDevice(input) {
+    const key = input.trim().toLowerCase();
+    const id = DEVICE_ALIASES[key] ?? key;
+    const device = DEVICES_BY_ID[id];
+    if (device)
+        return device;
+    throw new UnknownDeviceError(input, suggestDevices(key));
+}
+/** Resolve a list of ids/aliases, de-duplicating while keeping order. */
+export function resolveDevices(inputs) {
+    const seen = new Set();
+    const out = [];
+    for (const input of inputs) {
+        const d = resolveDevice(input);
+        if (seen.has(d.id))
+            continue;
+        seen.add(d.id);
+        out.push(d);
+    }
+    return out;
+}
+function suggestDevices(key) {
+    const ids = [...DEVICES.map(d => d.id), ...Object.keys(DEVICE_ALIASES)];
+    const scored = ids
+        .map(id => ({ id, score: id.includes(key) || key.includes(id) ? 0 : levenshtein(key, id) }))
+        .filter(s => s.score <= Math.max(2, Math.floor(key.length / 3)))
+        .sort((a, b) => a.score - b.score || a.id.localeCompare(b.id));
+    return scored.slice(0, 5).map(s => s.id);
+}
+function levenshtein(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = tmp;
+        }
+    }
+    return row[b.length];
+}

package/dist/errors.js

@@ -0,0 +1,115 @@
+const SANDBOX_HINT = 'If the host works in a normal browser, this process may be blocked by a sandbox or network allowlist ' +
+    '(e.g. the Claude Code sandbox: add the domain to the allowed hosts, or run outside the sandbox). ' +
+    'Note that nslookup can succeed while the sandboxed process still cannot connect.';
+function isLocalHost(host) {
+    return /^(localhost|127\.\d+\.\d+\.\d+|0\.0\.0\.0|\[::1\]|::1)$/i.test(host) || host.endsWith('.localhost');
+}
+function describeTarget(url) {
+    try {
+        const u = new URL(url);
+        const port = u.port || (u.protocol === 'https:' ? '443' : u.protocol === 'http:' ? '80' : '');
+        return { host: u.host || u.pathname, local: isLocalHost(u.hostname), file: u.protocol === 'file:', port };
+    }
+    catch {
+        return { host: url, local: false, file: false, port: '' };
+    }
+}
+/** Map a Playwright/Chromium error to `{ error, code, hint }`. */
+export function explainError(err, ctx) {
+    const raw = err instanceof Error ? err.message : String(err);
+    const first = (raw.split('\n')[0] ?? raw).trim();
+    const t = describeTarget(ctx.url);
+    const net = /net::(ERR_[A-Z0-9_]+)/.exec(raw)?.[1];
+    if (net) {
+        const tag = `(net::${net})`;
+        switch (net) {
+            case 'ERR_NAME_NOT_RESOLVED':
+            case 'ERR_NAME_RESOLUTION_FAILED':
+                return {
+                    code: net,
+                    error: `Could not resolve host ${t.host} ${tag}`,
+                    hint: t.local
+                        ? `Check the host name in the URL.`
+                        : `Check the URL for typos. ${SANDBOX_HINT}`,
+                };
+            case 'ERR_CONNECTION_REFUSED':
+                return {
+                    code: net,
+                    error: `Connection refused by ${t.host} ${tag}`,
+                    hint: t.local
+                        ? `Nothing is listening on port ${t.port}. Start the dev server (or check which port it printed) and retry.`
+                        : `The server refused the connection. ${SANDBOX_HINT}`,
+                };
+            case 'ERR_INTERNET_DISCONNECTED':
+                return {
+                    code: net,
+                    error: `No network connection ${tag}`,
+                    hint: `This process has no network access. ${SANDBOX_HINT}`,
+                };
+            case 'ERR_PROXY_CONNECTION_FAILED':
+            case 'ERR_TUNNEL_CONNECTION_FAILED':
+            case 'ERR_PROXY_AUTH_REQUESTED':
+            case 'ERR_PROXY_CERTIFICATE_INVALID':
+            case 'ERR_NO_SUPPORTED_PROXIES':
+                return {
+                    code: net,
+                    error: `Proxy refused the connection to ${t.host} ${tag}`,
+                    hint: `Traffic goes through a proxy that did not allow this host. ${SANDBOX_HINT}`,
+                };
+            case 'ERR_CONNECTION_TIMED_OUT':
+            case 'ERR_TIMED_OUT':
+            case 'ERR_ADDRESS_UNREACHABLE':
+            case 'ERR_NETWORK_ACCESS_DENIED':
+            case 'ERR_CONNECTION_RESET':
+            case 'ERR_CONNECTION_CLOSED':
+            case 'ERR_CONNECTION_FAILED':
+            case 'ERR_EMPTY_RESPONSE':
+            case 'ERR_BLOCKED_BY_ADMINISTRATOR':
+                return {
+                    code: net,
+                    error: `Could not connect to ${t.host} ${tag}`,
+                    hint: t.local
+                        ? `Check that the dev server on port ${t.port} is running and healthy.`
+                        : `The host is unreachable from here. ${SANDBOX_HINT}`,
+                };
+            case 'ERR_SSL_PROTOCOL_ERROR':
+            case 'ERR_SSL_VERSION_OR_CIPHER_MISMATCH':
+                return {
+                    code: net,
+                    error: `TLS handshake with ${t.host} failed ${tag}`,
+                    hint: t.local
+                        ? `The server probably speaks plain HTTP. Use http:// instead of https://.`
+                        : `The server's TLS setup is broken or something intercepts the connection.`,
+                };
+            case 'ERR_FILE_NOT_FOUND':
+                return { code: net, error: `File not found: ${t.host} ${tag}`, hint: `Check the path; relative paths resolve against the working directory.` };
+            case 'ERR_TOO_MANY_REDIRECTS':
+                return { code: net, error: `Redirect loop at ${t.host} ${tag}`, hint: `The page redirects to itself; check auth/locale redirects on the server.` };
+            case 'ERR_ABORTED':
+                return { code: net, error: `Navigation to ${ctx.url} was aborted ${tag}`, hint: `The URL may trigger a download or an immediate client-side redirect.` };
+            default:
+                return { code: net, error: first };
+        }
+    }
+    if (/TimeoutError|Timeout \d+ms exceeded/i.test(raw)) {
+        const secs = ctx.timeoutMs ? `${Math.round(ctx.timeoutMs / 1000)} s` : 'the timeout';
+        if (/waitForSelector|waiting for locator/i.test(raw) && ctx.waitFor) {
+            return {
+                code: 'WAIT_FOR_TIMEOUT',
+                error: `Selector "${ctx.waitFor}" did not become visible within ${secs}`,
+                hint: `Check the selector, or that the page reaches that state without interaction.`,
+            };
+        }
+        if (/goto|navigat/i.test(raw)) {
+            return {
+                code: 'TIMEOUT',
+                error: `Loading ${t.host} did not finish within ${secs}`,
+                hint: t.local
+                    ? `The dev server may still be compiling; retry or raise timeoutMs.`
+                    : `Raise timeoutMs if the site is slow. A silently dropped connection can also mean the host is blocked: ${SANDBOX_HINT}`,
+            };
+        }
+        return { code: 'TIMEOUT', error: first, hint: `Raise timeoutMs or waitMs and retry.` };
+    }
+    return { code: 'UNKNOWN', error: first };
+}