samey-cli 0.0.0-stage → 0.1.0

package/dist/render/extract.js

@@ -0,0 +1,441 @@
+/**
+ * Runs `fn` inside the page. The function is shipped as source text so that bundler
+ * helpers (esbuild's `__name`, used by tsx and vitest) never leak into the browser.
+ */
+export async function runInPage(page, fn, arg) {
+    const src = `(() => { var __name = (f) => f; return (${fn.toString()})(${JSON.stringify(arg)}); })()`;
+    return page.evaluate(src);
+}
+export async function extractViewportFacts(page, viewport) {
+    return runInPage(page, extractInPage, { viewport });
+}
+// Everything below executes in the browser. It must not reference anything outside its own body.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractInPage(opts) {
+    // Mobile emulation zooms out to fit overflowing content, which inflates innerWidth; clientWidth stays at the device width.
+    const W = document.documentElement.clientWidth || window.innerWidth;
+    const H = window.innerHeight;
+    const sx = window.scrollX;
+    const sy = window.scrollY;
+    const MAX_ELEMENTS = 8000;
+    const rectOf = (el) => {
+        const r = el.getBoundingClientRect();
+        return { x: Math.round(r.left + sx), y: Math.round(r.top + sy), width: Math.round(r.width), height: Math.round(r.height) };
+    };
+    const styleCache = new Map();
+    const css = (el) => {
+        let s = styleCache.get(el);
+        if (!s) {
+            s = getComputedStyle(el);
+            styleCache.set(el, s);
+        }
+        return s;
+    };
+    const visible = (el) => {
+        const r = el.getBoundingClientRect();
+        if (r.width < 1 || r.height < 1)
+            return false;
+        const s = css(el);
+        if (s.visibility === 'hidden' || s.display === 'none' || parseFloat(s.opacity) < 0.05)
+            return false;
+        return true;
+    };
+    const cssPath = (el) => {
+        if (el.id && /^[A-Za-z][\w-]*$/.test(el.id))
+            return `#${el.id}`;
+        const parts = [];
+        let cur = el;
+        while (cur && cur !== document.body && parts.length < 5) {
+            let part = cur.tagName.toLowerCase();
+            if (cur.id && /^[A-Za-z][\w-]*$/.test(cur.id)) {
+                parts.unshift(`#${cur.id}`);
+                break;
+            }
+            const parent = cur.parentElement;
+            if (parent) {
+                const same = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);
+                if (same.length > 1)
+                    part += `:nth-of-type(${same.indexOf(cur) + 1})`;
+            }
+            parts.unshift(part);
+            cur = parent;
+        }
+        return parts.join(' > ');
+    };
+    const textOf = (el) => (el.innerText || el.textContent || '').replace(/\s+/g, ' ').trim();
+    const ownText = (el) => Array.from(el.childNodes)
+        .filter((n) => n.nodeType === Node.TEXT_NODE)
+        .map((n) => n.textContent || '')
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const bump = (rec, key) => {
+        rec[key] = (rec[key] || 0) + 1;
+    };
+    const accessibleName = (el) => {
+        const aria = el.getAttribute('aria-label');
+        if (aria && aria.trim())
+            return aria.trim();
+        const by = el.getAttribute('aria-labelledby');
+        if (by) {
+            const t = by
+                .split(/\s+/)
+                .map((id) => document.getElementById(id)?.textContent || '')
+                .join(' ')
+                .trim();
+            if (t)
+                return t;
+        }
+        const t = textOf(el);
+        if (t)
+            return t;
+        const title = el.getAttribute('title');
+        if (title && title.trim())
+            return title.trim();
+        const img = el.querySelector('img[alt]');
+        if (img && img.getAttribute('alt').trim())
+            return img.getAttribute('alt').trim();
+        const svgTitle = el.querySelector('svg title');
+        if (svgTitle && svgTitle.textContent.trim())
+            return svgTitle.textContent.trim();
+        if (el instanceof HTMLInputElement && el.value)
+            return el.value;
+        return '';
+    };
+    const styles = {
+        colors: {},
+        backgrounds: {},
+        fontSizes: {},
+        fontFamilies: {},
+        radii: {},
+        shadows: {},
+        spacing: {},
+    };
+    const gradients = [];
+    const glows = [];
+    const tinyText = [];
+    const all = Array.from(document.body.querySelectorAll('*')).slice(0, MAX_ELEMENTS);
+    for (const el of all) {
+        const tag = el.tagName.toLowerCase();
+        if (tag === 'script' || tag === 'style' || tag === 'noscript' || tag === 'template')
+            continue;
+        if (el.closest('svg') && tag !== 'svg')
+            continue;
+        if (!visible(el))
+            continue;
+        const s = css(el);
+        const own = ownText(el);
+        if (own.length > 0) {
+            bump(styles.colors, s.color);
+            bump(styles.fontSizes, s.fontSize);
+            bump(styles.fontFamilies, s.fontFamily.split(',')[0].replace(/["']/g, '').trim());
+            const fs = parseFloat(s.fontSize);
+            if (fs < 12 && own.length > 3 && tinyText.length < 20) {
+                tinyText.push({ selector: cssPath(el), rect: rectOf(el), text: own.slice(0, 80), size: fs });
+            }
+        }
+        if (s.backgroundColor && s.backgroundColor !== 'rgba(0, 0, 0, 0)' && s.backgroundColor !== 'transparent') {
+            bump(styles.backgrounds, s.backgroundColor);
+        }
+        if (s.borderTopLeftRadius && s.borderTopLeftRadius !== '0px')
+            bump(styles.radii, s.borderTopLeftRadius);
+        if (s.boxShadow && s.boxShadow !== 'none') {
+            bump(styles.shadows, s.boxShadow);
+            // Large-blur shadows are glow candidates; saturation is judged on the Node side.
+            const blurs = Array.from(s.boxShadow.matchAll(/(-?\d+(?:\.\d+)?)px\s+(-?\d+(?:\.\d+)?)px\s+(\d+(?:\.\d+)?)px/g)).map((m) => parseFloat(m[3]));
+            if (blurs.some((b) => b >= 24) && glows.length < 60) {
+                glows.push({ selector: cssPath(el), rect: rectOf(el), value: s.boxShadow, kind: 'shadow' });
+            }
+        }
+        for (const prop of ['paddingTop', 'paddingLeft', 'marginTop', 'rowGap']) {
+            const v = s[prop];
+            if (v && v !== '0px' && v !== 'normal' && v.endsWith('px'))
+                bump(styles.spacing, v);
+        }
+        const bgImage = s.backgroundImage;
+        if (bgImage && bgImage.includes('gradient(') && gradients.length < 80) {
+            const r = rectOf(el);
+            const clip = s.backgroundClip || s.webkitBackgroundClip || '';
+            gradients.push({ selector: cssPath(el), rect: r, value: bgImage, area: r.width * r.height, isText: clip === 'text' });
+        }
+        const filter = s.filter || '';
+        const blurMatch = filter.match(/blur\((\d+(?:\.\d+)?)px\)/);
+        if (blurMatch && parseFloat(blurMatch[1]) >= 30 && glows.length < 60) {
+            glows.push({ selector: cssPath(el), rect: rectOf(el), value: `filter: ${filter}; background: ${s.backgroundImage !== 'none' ? s.backgroundImage : s.backgroundColor}`, kind: 'blur-blob' });
+        }
+        const backdrop = s.backdropFilter || s.webkitBackdropFilter || '';
+        if (backdrop.includes('blur(') && glows.length < 60) {
+            glows.push({ selector: cssPath(el), rect: rectOf(el), value: `backdrop-filter: ${backdrop}`, kind: 'backdrop' });
+        }
+    }
+    // Headings
+    const headings = Array.from(document.querySelectorAll('h1,h2,h3,h4,h5,h6'))
+        .filter(visible)
+        .map((el) => ({ selector: cssPath(el), rect: rectOf(el), level: parseInt(el.tagName[1], 10), text: textOf(el).slice(0, 200) }));
+    // Controls
+    const controlEls = Array.from(document.querySelectorAll('button, [role="button"], input[type="submit"], input[type="button"], a[href]')).filter(visible);
+    const controls = controlEls
+        .filter((el) => el.tagName !== 'A' || /btn|button/i.test(el.className.toString()) || el.getAttribute('role') === 'button')
+        .slice(0, 200)
+        .map((el) => ({
+        selector: cssPath(el),
+        rect: rectOf(el),
+        tag: el.tagName.toLowerCase(),
+        text: textOf(el).slice(0, 120),
+        name: accessibleName(el).slice(0, 120),
+        href: el.getAttribute('href') ?? undefined,
+        type: el.getAttribute('type') ?? undefined,
+        inForm: !!el.closest('form'),
+    }));
+    // Links
+    const links = Array.from(document.querySelectorAll('a'))
+        .filter(visible)
+        .slice(0, 400)
+        .map((a) => {
+        const raw = a.getAttribute('href');
+        let internal = false;
+        try {
+            internal = raw != null && new URL(a.href, location.href).origin === location.origin;
+        }
+        catch {
+            internal = false;
+        }
+        return { selector: cssPath(a), rect: rectOf(a), href: raw ?? '', text: accessibleName(a).slice(0, 120), internal };
+    });
+    // Images
+    const images = Array.from(document.images)
+        .filter((img) => visible(img) || (img.complete && img.naturalWidth === 0 && img.getAttribute('src')))
+        .slice(0, 200)
+        .map((img) => ({
+        selector: cssPath(img),
+        rect: rectOf(img),
+        src: img.currentSrc || img.getAttribute('src') || '',
+        alt: img.getAttribute('alt'),
+        broken: img.complete && img.naturalWidth === 0 && !!img.getAttribute('src'),
+        decorative: img.getAttribute('alt') === '' || img.getAttribute('role') === 'presentation' || img.getAttribute('aria-hidden') === 'true',
+    }));
+    // Text blocks for copy analysis
+    const textBlocks = Array.from(document.querySelectorAll('h1,h2,h3,h4,h5,h6,p,li,blockquote,figcaption,dd,dt,td,button,a,label,span,div'))
+        .filter((el) => {
+        const own = ownText(el);
+        if (own.length < 2)
+            return false;
+        const tag = el.tagName.toLowerCase();
+        if ((tag === 'span' || tag === 'div') && own.length < 12)
+            return false;
+        return visible(el);
+    })
+        .slice(0, 600)
+        .map((el) => ({ selector: cssPath(el), rect: rectOf(el), tag: el.tagName.toLowerCase(), text: textOf(el).slice(0, 600) }));
+    // Small touch targets (WCAG 2.5.8 minimum is 24x24 CSS px); inline links inside running text are exempt.
+    const smallTargets = [];
+    for (const el of controlEls.concat(Array.from(document.querySelectorAll('input:not([type=hidden]), select, textarea')).filter(visible))) {
+        const r = el.getBoundingClientRect();
+        if (r.width >= 24 && r.height >= 24)
+            continue;
+        if (el.tagName === 'A') {
+            const parent = el.parentElement;
+            if (parent && textOf(parent).length > textOf(el).length + 20)
+                continue;
+        }
+        if (smallTargets.length < 30) {
+            smallTargets.push({ selector: cssPath(el), rect: rectOf(el), text: accessibleName(el).slice(0, 60), w: Math.round(r.width), h: Math.round(r.height) });
+        }
+    }
+    // Horizontal overflow
+    const scrollWidth = document.documentElement.scrollWidth;
+    const overflowing = [];
+    if (scrollWidth > W + 1) {
+        const clipped = (el) => {
+            let p = el.parentElement;
+            while (p && p !== document.documentElement) {
+                const ox = css(p).overflowX;
+                if ((ox === 'hidden' || ox === 'auto' || ox === 'scroll' || ox === 'clip') && p.getBoundingClientRect().right <= W + 1)
+                    return true;
+                p = p.parentElement;
+            }
+            return false;
+        };
+        const offenders = all.filter((el) => {
+            const r = el.getBoundingClientRect();
+            return r.width > 0 && r.right > W + 1 && visible(el) && !clipped(el);
+        });
+        // Keep the outermost offenders: the element whose parent does not itself overflow.
+        const outer = offenders.filter((el) => !offenders.includes(el.parentElement));
+        for (const el of outer.slice(0, 10)) {
+            overflowing.push({ selector: cssPath(el), rect: rectOf(el), right: Math.round(el.getBoundingClientRect().right) });
+        }
+    }
+    // Unlabeled form fields
+    const unlabeledInputs = Array.from(document.querySelectorAll('input, select, textarea'))
+        .filter((el) => {
+        const type = (el.getAttribute('type') || '').toLowerCase();
+        if (['hidden', 'submit', 'button', 'reset', 'image'].includes(type))
+            return false;
+        if (!visible(el))
+            return false;
+        const labelled = (el.labels?.length ?? 0) > 0 || el.getAttribute('aria-label') || el.getAttribute('aria-labelledby') || el.getAttribute('title');
+        return !labelled;
+    })
+        .slice(0, 20)
+        .map((el) => ({ selector: cssPath(el), rect: rectOf(el), type: el.getAttribute('type') || el.tagName.toLowerCase() }));
+    // Sections
+    const shapeSig = (el, depth) => {
+        const tag = el.tagName.toLowerCase();
+        if (depth === 0)
+            return tag;
+        const kids = Array.from(el.children).filter((c) => !['script', 'style'].includes(c.tagName.toLowerCase())).slice(0, 6);
+        return tag + (kids.length ? '[' + kids.map((k) => shapeSig(k, depth - 1)).join(',') + ']' : '');
+    };
+    const isStyled = (el, parent) => {
+        const s = css(el);
+        const ps = css(parent);
+        return (parseFloat(s.borderTopWidth) > 0 ||
+            (s.boxShadow && s.boxShadow !== 'none') ||
+            (s.backgroundColor !== 'rgba(0, 0, 0, 0)' && s.backgroundColor !== ps.backgroundColor) ||
+            (s.backgroundImage && s.backgroundImage !== 'none') ||
+            parseFloat(s.borderTopLeftRadius) >= 6);
+    };
+    const findRepeatGroup = (root) => {
+        let best = null;
+        const queue = [[root, 0]];
+        while (queue.length) {
+            const [node, depth] = queue.shift();
+            const kids = Array.from(node.children).filter(visible);
+            if (kids.length >= 3) {
+                const counts = new Map();
+                for (const k of kids) {
+                    const sig = shapeSig(k, 2);
+                    if (!counts.has(sig))
+                        counts.set(sig, []);
+                    counts.get(sig).push(k);
+                }
+                for (const [sig, items] of counts) {
+                    if (items.length >= 3 && items.length / kids.length >= 0.6 && sig.includes('[')) {
+                        const styled = items.filter((i) => isStyled(i, node)).length >= items.length * 0.6;
+                        if (!best || items.length > best.items.length || (styled && !best.styled))
+                            best = { container: node, items, sig, styled };
+                    }
+                }
+            }
+            if (depth < 6)
+                for (const k of kids)
+                    queue.push([k, depth + 1]);
+        }
+        return best;
+    };
+    const sectionInfo = (el, index) => {
+        const tag = el.tagName.toLowerCase();
+        const r = rectOf(el);
+        const role = el.getAttribute('role') || '';
+        // A <header> that holds the h1 and takes real height is a hero, not site chrome.
+        const heroLike = !!el.querySelector('h1') && r.height >= 240;
+        const isChrome = ((tag === 'header' || role === 'banner') && !heroLike) || tag === 'footer' || tag === 'nav' || role === 'contentinfo' || role === 'navigation';
+        const h = el.querySelector('h1,h2,h3');
+        const heading = h ? textOf(h).slice(0, 160) : undefined;
+        let centered = false;
+        if (h) {
+            const hs = css(h);
+            const hr = h.getBoundingClientRect();
+            const er = el.getBoundingClientRect();
+            centered = hs.textAlign === 'center' || (hr.width < er.width * 0.8 && Math.abs(hr.left + hr.width / 2 - (er.left + er.width / 2)) < er.width * 0.03);
+        }
+        const group = findRepeatGroup(el);
+        let columns = 1;
+        if (group) {
+            const firstTop = group.items[0].getBoundingClientRect().top;
+            columns = group.items.filter((i) => Math.abs(i.getBoundingClientRect().top - firstTop) < 8).length;
+        }
+        const btns = Array.from(el.querySelectorAll('button, a, input[type=submit]')).filter((b) => {
+            if (!visible(b))
+                return false;
+            if (b.tagName !== 'A')
+                return true;
+            const s = css(b);
+            return (s.backgroundColor !== 'rgba(0, 0, 0, 0)' || parseFloat(s.borderTopWidth) > 0) && parseFloat(s.paddingLeft) >= 8;
+        });
+        const imgs = Array.from(el.querySelectorAll('img, svg, video, picture')).filter((m) => visible(m) && m.getBoundingClientRect().width > 16);
+        const text = textOf(el);
+        const cardCount = group ? group.items.length : 0;
+        const flags = {
+            hasBlockquote: !!el.querySelector('blockquote, q, figure > blockquote'),
+            hasDetails: !!el.querySelector('details, [aria-expanded]'),
+            hasPrice: /[$€£]\s?\d/.test(text) && /\/\s?(?:mo|month|yr|year)|per (?:month|year|user)|monthly|annually/i.test(text),
+        };
+        const sig = [
+            isChrome ? tag : 'sec',
+            `h${heading ? 1 : 0}`,
+            `c${centered ? 1 : 0}`,
+            `cols${Math.min(columns, 6)}`,
+            `cards${Math.min(cardCount, 8)}`,
+            group ? (group.styled ? 'styled' : 'plain') + ':' + group.sig.length.toString(36) : '-',
+            `b${Math.min(btns.length, 3)}`,
+            `i${imgs.length > 0 ? 1 : 0}`,
+            flags.hasBlockquote ? 'q' : '',
+            flags.hasDetails ? 'd' : '',
+            flags.hasPrice ? 'p' : '',
+        ].join('|');
+        return {
+            index,
+            selector: cssPath(el),
+            rect: r,
+            tag,
+            signature: sig,
+            heading,
+            text: text.slice(0, 500),
+            centered,
+            columns,
+            cardCount,
+            cardSignature: group ? group.sig : undefined,
+            buttonCount: btns.length,
+            imageCount: imgs.length,
+            ...flags,
+            isChrome,
+        };
+    };
+    const blockKids = (el) => Array.from(el.children).filter((c) => visible(c) && c.getBoundingClientRect().height >= 40);
+    let root = document.body;
+    for (let i = 0; i < 6; i++) {
+        const kids = blockKids(root);
+        if (kids.length === 1 && kids[0].getBoundingClientRect().height >= root.getBoundingClientRect().height * 0.8)
+            root = kids[0];
+        else
+            break;
+    }
+    const sectionEls = [];
+    for (const k of blockKids(root)) {
+        const kids = blockKids(k);
+        const tall = k.getBoundingClientRect().height > H * 2;
+        if ((k.tagName === 'MAIN' || tall) && kids.length >= 3 && !['HEADER', 'FOOTER', 'NAV'].includes(k.tagName))
+            sectionEls.push(...kids);
+        else
+            sectionEls.push(k);
+    }
+    const sections = sectionEls.slice(0, 40).map(sectionInfo);
+    const body = document.body;
+    const wordCount = textOf(body).split(/\s+/).filter(Boolean).length;
+    return {
+        viewport: opts.viewport,
+        width: W,
+        height: H,
+        docHeight: Math.max(body.scrollHeight, document.documentElement.scrollHeight),
+        scrollWidth,
+        lang: document.documentElement.getAttribute('lang'),
+        title: document.title,
+        metaDescription: document.querySelector('meta[name="description"]')?.getAttribute('content') ?? null,
+        sections,
+        headings,
+        controls,
+        links,
+        images,
+        textBlocks,
+        gradients,
+        glows,
+        styles,
+        smallTargets,
+        tinyText,
+        overflowing,
+        unlabeledInputs,
+        wordCount,
+    };
+}

package/dist/render/interact.d.ts

@@ -0,0 +1,8 @@
+import type { Page } from 'playwright';
+import type { ControlFact, InteractionResult } from '../types.js';
+export declare function isSafeControl(c: ControlFact): boolean;
+/**
+ * Clicks a handful of safe, visible buttons and records whether anything observable
+ * happened (navigation, DOM change). Restores the page after navigations.
+ */
+export declare function testInteractions(page: Page, controls: ControlFact[], limit: number, timeoutMs: number): Promise<InteractionResult[]>;

package/dist/render/interact.js

@@ -0,0 +1,76 @@
+import { runInPage } from './extract.js';
+/** Labels that suggest a click could change data, spend money, or end a session. Never clicked. */
+const UNSAFE = /\b(?:delete|remove|destroy|erase|buy|pay|purchase|checkout|order|subscribe|unsubscribe|log ?out|sign ?out|submit|send|confirm|cancel (?:plan|subscription)|reset|deploy|publish|charge|transfer|donate)\b/i;
+export function isSafeControl(c) {
+    if (c.inForm)
+        return false;
+    if (c.type === 'submit' || c.type === 'reset')
+        return false;
+    if (c.tag === 'a')
+        return false; // links are covered by the crawler and link checks
+    if (c.href)
+        return false;
+    if (!c.name && !c.text)
+        return false; // empty buttons are reported separately
+    if (UNSAFE.test(c.name) || UNSAFE.test(c.text))
+        return false;
+    if (c.rect.width < 4 || c.rect.height < 4)
+        return false;
+    return true;
+}
+function installObserver() {
+    const w = window;
+    w.__sameyMutations = 0;
+    w.__sameyObs?.disconnect();
+    w.__sameyObs = new MutationObserver((list) => {
+        w.__sameyMutations = (w.__sameyMutations ?? 0) + list.length;
+    });
+    w.__sameyObs.observe(document.documentElement, { subtree: true, childList: true, attributes: true, characterData: true });
+}
+function readMutations() {
+    return window.__sameyMutations ?? 0;
+}
+/**
+ * Clicks a handful of safe, visible buttons and records whether anything observable
+ * happened (navigation, DOM change). Restores the page after navigations.
+ */
+export async function testInteractions(page, controls, limit, timeoutMs) {
+    const results = [];
+    const startUrl = page.url();
+    const candidates = controls.filter(isSafeControl).slice(0, limit);
+    for (const c of candidates) {
+        const base = { selector: c.selector, rect: c.rect, text: c.name || c.text };
+        try {
+            if (page.url() !== startUrl)
+                await page.goto(startUrl, { waitUntil: 'load', timeout: timeoutMs });
+            const loc = page.locator(c.selector).first();
+            if (!(await loc.isVisible({ timeout: 500 }).catch(() => false))) {
+                results.push({ ...base, outcome: 'skipped', detail: 'not visible at click time' });
+                continue;
+            }
+            await runInPage(page, installObserver, undefined);
+            const errors = [];
+            const onError = (e) => errors.push(e.message);
+            page.on('pageerror', onError);
+            await loc.click({ timeout: Math.min(timeoutMs, 3000) });
+            await page.waitForTimeout(600);
+            page.off('pageerror', onError);
+            if (page.url() !== startUrl) {
+                results.push({ ...base, outcome: 'navigated', detail: page.url() });
+                continue;
+            }
+            if (errors.length) {
+                results.push({ ...base, outcome: 'error', detail: errors[0].slice(0, 200) });
+                continue;
+            }
+            const mutations = await runInPage(page, readMutations, undefined);
+            results.push({ ...base, outcome: mutations > 0 ? 'changed' : 'no-effect', detail: mutations > 0 ? `${mutations} DOM mutations` : undefined });
+            // Close anything the click opened so the next control starts from a similar state.
+            await page.keyboard.press('Escape').catch(() => undefined);
+        }
+        catch (err) {
+            results.push({ ...base, outcome: 'skipped', detail: err.message.split('\n')[0].slice(0, 160) });
+        }
+    }
+    return results;
+}

package/dist/render/network.d.ts

@@ -0,0 +1,33 @@
+import type { BrowserContext } from 'playwright';
+import { type NetworkPolicy } from '../security/net-policy.js';
+export interface NetworkLimits {
+    maxResponseBytes: number;
+    maxTotalBytes: number;
+    maxRequests: number;
+    requestTimeoutMs: number;
+}
+export declare const DEFAULT_LIMITS: NetworkLimits;
+export interface NetworkLog {
+    blocked: {
+        url: string;
+        reason: string;
+    }[];
+    /**
+     * Navigation redirects the guard stopped, keyed by the requesting URL. Chromium follows a
+     * redirect from a fulfilled route without routing the next hop, so navigations are aborted
+     * here and the crawler re-navigates to the validated target itself.
+     */
+    navRedirects: Map<string, string>;
+    /** Full URLs the guard refused. Their failures are samey's doing, not the site's. */
+    blockedUrls: Set<string>;
+    requests: number;
+    bytes: number;
+    budgetExceeded: boolean;
+}
+export declare function newNetworkLog(): NetworkLog;
+/**
+ * Serves every browser request from Node through the guarded client, so the browser never
+ * resolves DNS or opens a connection on its own. Blocked requests are aborted and logged.
+ * Shared state (budget, log) spans all contexts of one crawl.
+ */
+export declare function guardContext(context: BrowserContext, policy: NetworkPolicy, limits: NetworkLimits, log: NetworkLog): Promise<void>;

package/dist/render/network.js

@@ -0,0 +1,92 @@
+import { guardedRequest, TooLargeError } from '../security/fetch.js';
+import { BlockedError, checkUrlSyntax, displayUrl } from '../security/net-policy.js';
+export const DEFAULT_LIMITS = {
+    maxResponseBytes: 20 * 1024 * 1024,
+    maxTotalBytes: 250 * 1024 * 1024,
+    maxRequests: 3000,
+    requestTimeoutMs: 20_000,
+};
+export function newNetworkLog() {
+    return { blocked: [], navRedirects: new Map(), blockedUrls: new Set(), requests: 0, bytes: 0, budgetExceeded: false };
+}
+/**
+ * Serves every browser request from Node through the guarded client, so the browser never
+ * resolves DNS or opens a connection on its own. Blocked requests are aborted and logged.
+ * Shared state (budget, log) spans all contexts of one crawl.
+ */
+export async function guardContext(context, policy, limits, log) {
+    const block = async (route, url, reason, code = 'blockedbyclient') => {
+        log.blockedUrls.add(url);
+        if (log.blocked.length < 200)
+            log.blocked.push({ url: displayUrl(url), reason });
+        await route.abort(code).catch(() => undefined);
+    };
+    await context.route('**/*', async (route) => {
+        const req = route.request();
+        const url = req.url();
+        if (!/^https?:/i.test(url))
+            return block(route, url, 'unsupported protocol');
+        if (log.requests >= limits.maxRequests || log.bytes >= limits.maxTotalBytes) {
+            log.budgetExceeded = true;
+            return block(route, url, 'crawl network budget exhausted', 'failed');
+        }
+        log.requests++;
+        try {
+            const headersIn = await req.allHeaders();
+            const send = (u, method, body) => guardedRequest(u, { policy, method, headers: headersIn, body, maxBytes: limits.maxResponseBytes, timeoutMs: limits.requestTimeoutMs });
+            let res = await send(url, req.method(), req.postDataBuffer());
+            const isRedirect = () => res.status >= 300 && res.status < 400 && !!res.headers['location'];
+            if (isRedirect() && req.isNavigationRequest()) {
+                log.navRedirects.set(url, new URL(String(res.headers['location']), url).href);
+                await route.abort('aborted').catch(() => undefined);
+                return;
+            }
+            // Subresources: follow redirects here, re-validating every hop, and hand back the final response.
+            let current = url;
+            for (let hop = 0; isRedirect(); hop++) {
+                if (hop >= 5)
+                    throw new BlockedError('more than 5 redirects', url);
+                current = new URL(String(res.headers['location']), current).href;
+                const keep = res.status === 307 || res.status === 308;
+                res = await send(current, keep ? req.method() : 'GET', keep ? req.postDataBuffer() : null);
+            }
+            log.bytes += res.body.length;
+            const headers = {};
+            for (const [k, v] of Object.entries(res.headers)) {
+                if (['transfer-encoding', 'connection', 'keep-alive'].includes(k))
+                    continue;
+                headers[k] = Array.isArray(v) ? v.join('\n') : v;
+            }
+            await route.fulfill({ status: res.status, headers, body: res.body });
+        }
+        catch (err) {
+            if (err instanceof BlockedError)
+                return block(route, url, err.message);
+            if (err instanceof TooLargeError)
+                return block(route, url, err.message, 'failed');
+            await route.abort('failed').catch(() => undefined);
+        }
+    });
+    // WebSockets bypass request routing. Remote audits never need them; dev servers use them for hot reload.
+    await context.routeWebSocket(/.*/, (ws) => {
+        try {
+            checkUrlSyntax(ws.url().replace(/^ws/, 'http'), policy);
+            if (policy.allowLoopback) {
+                ws.connectToServer();
+                return;
+            }
+        }
+        catch {
+            /* fall through */
+        }
+        if (log.blocked.length < 200)
+            log.blocked.push({ url: displayUrl(ws.url().replace(/^ws/, 'http')), reason: 'websocket' });
+        ws.close();
+    });
+    context.on('page', (p) => {
+        // Pages opened by the site (window.open, target=_blank clicks) are closed immediately.
+        p.opener()
+            .then((opener) => (opener ? p.close() : undefined))
+            .catch(() => undefined);
+    });
+}

package/dist/render/robots.d.ts

@@ -0,0 +1,8 @@
+/** Minimal robots.txt support: Disallow/Allow rules for `User-agent: *` (or our own agent). */
+export interface RobotsRules {
+    allow: string[];
+    disallow: string[];
+}
+export declare function parseRobots(txt: string, agent?: string): RobotsRules;
+/** Longest matching rule wins; Allow wins ties, per RFC 9309. */
+export declare function isAllowed(rules: RobotsRules, path: string): boolean;