browxai 0.7.0

package/dist/page/overflow-detect.js

@@ -0,0 +1,449 @@
+/// <reference lib="dom" />
+// `overflow_detect` — diagnose page-layout overflow.
+//
+// The silent UI-breakage primitive: clipped buttons, ellipsis-truncated
+// labels, horizontal-scrollbar-on-mobile bugs. Agents repeatedly miss
+// these because a screenshot looks "fine" (the clipped pixel doesn't
+// shout) and `find()` doesn't surface "the element rendered but its
+// content was lost". This tool walks the DOM, applies four overflow
+// shape detectors, and returns one finding per offending element.
+//
+// Detector taxonomy (all four enabled by default; opt out via `types`):
+//
+//   - `layout`              — `scrollWidth/Height > clientWidth/Height` on
+//                             an element whose computed `overflow` is
+//                             `auto`/`scroll`. The platform IS providing a
+//                             scrollbar but content overflows the visible
+//                             padding box. Subtler than `clipped` (content
+//                             is recoverable) but still worth surfacing.
+//   - `clipped`             — same dimensional check, but `overflow-x|y` is
+//                             `hidden`/`clip`. Content extending past the
+//                             box is invisible with no scrollbar to
+//                             recover. The high-value "the button got cut
+//                             off" finding.
+//   - `text-ellipsis`       — `text-overflow: ellipsis` AND
+//                             `scrollWidth > clientWidth` on the text node
+//                             itself. Carries `visibleText` (best-effort
+//                             heuristic — the offsetWidth-bounded prefix)
+//                             plus `fullText` (the truth the agent reads).
+//   - `viewport-horizontal` — singleton check: `documentElement.scrollWidth
+//                             > documentElement.clientWidth`. The "horizontal
+//                             scrollbar on body" mobile-layout bug. One
+//                             finding at most; selector `"html"`; evidence
+//                             surfaces the overrun amount + the widest
+//                             overrunning descendant when cheaply identifiable.
+//
+// EPSILON = 1 CSS px tolerates sub-pixel rounding noise — without it,
+// pages that scale fonts or run on a fractional devicePixelRatio routinely
+// trip false positives by ≤0.5 px.
+//
+// Bounded walk: `MAX_ELEMENTS_SCANNED = 10000`. When the cap is hit, the
+// result carries `warnings:["scan stopped at MAX_ELEMENTS_SCANNED…"]` so
+// the agent can re-run with `scope:"viewport"` for a narrower pass.
+//
+// Page-side function is passed as a REAL function literal (not a
+// stringified arrow) so Playwright's `Page.evaluate(fn, arg)` path
+// serializes the source and invokes in-page with the arg. The same trap
+// burned `dom_export`'s `PAGE_WALK_FN` and `element_export`'s discovery
+// function — a stringified `(args) => {...}` evaluates to the function
+// value uncalled, which CDP can't serialize → undefined.
+const ALL_TYPES = ["layout", "clipped", "text-ellipsis", "viewport-horizontal"];
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+const MAX_ELEMENTS_SCANNED = 10000;
+/** Selector synthesis tiers (page-side mirror in `PAGE_DETECT_FN`):
+ *
+ *   1. `[data-testid="..."]`
+ *   2. `[role="..."][aria-label="..."]`           (both stable)
+ *   3. nth-of-type CSS path bounded at 5 levels
+ *   4. `tag.classes` (up to 3 classes)
+ *
+ *  Capped at 200 chars; longer falls through to `tag` only with an
+ *  `evidence.selectorTruncated` flag.
+ *
+ *  Exported for unit tests against fixture mock elements.
+ */
+const SELECTOR_MAX_LEN = 200;
+export function synthesiseSelector(el) {
+    const tag = (el.tagName || "").toLowerCase();
+    let raw;
+    // Tier 1 — data-testid.
+    if (el.testId) {
+        raw = `[data-testid="${escapeAttrValue(el.testId)}"]`;
+    }
+    else if (el.role && el.ariaLabel) {
+        // Tier 2 — role + accessible name (both stable).
+        raw = `[role="${escapeAttrValue(el.role)}"][aria-label="${escapeAttrValue(el.ariaLabel)}"]`;
+    }
+    else if (el.parentChain && el.parentChain.length > 0 && typeof el.nthOfType === "number") {
+        // Tier 3 — nth-of-type CSS path, bounded at 5 levels.
+        const levels = [];
+        const chain = el.parentChain.slice(0, 5);
+        for (let i = chain.length - 1; i >= 0; i--) {
+            const a = chain[i];
+            levels.push(`${a.tagName.toLowerCase()}:nth-of-type(${a.nthOfType})`);
+        }
+        levels.push(`${tag}:nth-of-type(${el.nthOfType})`);
+        raw = levels.join(" > ");
+    }
+    else if (el.classList.length > 0) {
+        // Tier 4 — tag.classes (up to 3).
+        const classes = el.classList.slice(0, 3).map(escapeClassName);
+        raw = `${tag}.${classes.join(".")}`;
+    }
+    else {
+        raw = tag || "*";
+    }
+    if (raw.length <= SELECTOR_MAX_LEN) {
+        return { selector: raw, truncated: false, originalLength: raw.length };
+    }
+    return { selector: tag || "*", truncated: true, originalLength: raw.length };
+}
+function escapeAttrValue(v) {
+    return v.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function escapeClassName(c) {
+    // CSS identifier escape — limited to characters classlist actually surfaces;
+    // we don't try to encode arbitrary text-of-the-rainbow class names, just
+    // the ones a synthesised selector needs to round-trip.
+    return c.replace(/([^A-Za-z0-9_-])/g, "\\$1");
+}
+/** Pure helper: cap findings at `limit`, set `truncated` when exceeded.
+ *  Exported for unit tests. */
+export function applyLimit(findings, limit) {
+    if (findings.length <= limit) {
+        return { kept: findings, truncated: false };
+    }
+    return { kept: findings.slice(0, limit), truncated: true };
+}
+/** Pure helper: which detector mask should be active. Empty array →
+ *  all four (an empty filter is treated as "default", not "exclude
+ *  everything" — the latter would be a usage error with no signal). */
+export function resolveTypes(requested) {
+    if (!requested || requested.length === 0)
+        return new Set(ALL_TYPES);
+    // Filter to the known set so a typo doesn't silently turn into a
+    // useless filter; unknowns are dropped.
+    const out = new Set();
+    for (const t of requested) {
+        if (ALL_TYPES.includes(t))
+            out.add(t);
+    }
+    if (out.size === 0)
+        return new Set(ALL_TYPES);
+    return out;
+}
+/** Pure helper for the EPSILON math — returns true when content actually
+ *  overruns its container past the sub-pixel-noise tolerance. Centralised
+ *  so the unit tests can pin the threshold + so changes flow through one
+ *  site instead of four detector branches. */
+export const OVERFLOW_EPSILON = 1;
+export function overflows(scrollDim, clientDim, epsilon = OVERFLOW_EPSILON) {
+    return scrollDim > clientDim + epsilon;
+}
+/** Page-side detector. Receives the resolved type mask + scope + scan
+ *  budget; returns raw findings + a `scanCapped` flag. Walk is bounded
+ *  by `MAX_ELEMENTS_SCANNED`. Passed as a real function literal — see
+ *  the file-header note on the stringified-arrow trap. */
+const PAGE_DETECT_FN = (args) => {
+    const wantLayout = args.types.indexOf("layout") !== -1;
+    const wantClipped = args.types.indexOf("clipped") !== -1;
+    const wantEllipsis = args.types.indexOf("text-ellipsis") !== -1;
+    const wantVpHorizontal = args.types.indexOf("viewport-horizontal") !== -1;
+    const epsilon = args.epsilon;
+    const selectorMaxLen = args.selectorMaxLen;
+    const findings = [];
+    function escapeAttr(v) {
+        return v.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    }
+    function escapeCls(c) {
+        return c.replace(/([^A-Za-z0-9_-])/g, "\\$1");
+    }
+    function nthOfType(node) {
+        let n = 1;
+        let prev = node.previousElementSibling;
+        while (prev) {
+            if (prev.tagName === node.tagName)
+                n++;
+            prev = prev.previousElementSibling;
+        }
+        return n;
+    }
+    /** Tier 3 — nth-of-type CSS path (≤5 levels), else a class selector, else the
+     *  bare tag. */
+    function synthTier3(el, tag) {
+        const path = [];
+        let cur = el;
+        for (let i = 0; i < 5 && cur && cur.nodeType === 1 && cur !== document.documentElement; i++) {
+            const ctag = (cur.tagName || "").toLowerCase();
+            path.unshift(ctag + ":nth-of-type(" + nthOfType(cur) + ")");
+            cur = cur.parentElement;
+        }
+        if (path.length > 0)
+            return path.join(" > ");
+        if (el.classList && el.classList.length > 0) {
+            const cls = [];
+            for (let i = 0; i < el.classList.length && i < 3; i++)
+                cls.push(escapeCls(el.classList[i]));
+            return tag + "." + cls.join(".");
+        }
+        return tag || "*";
+    }
+    /** Compute the raw (un-truncated) selector via the tiered preference:
+     *  data-testid → role+aria-label → tier-3 path. */
+    function synthRaw(el, tag) {
+        const testId = el.getAttribute("data-testid");
+        if (testId)
+            return '[data-testid="' + escapeAttr(testId) + '"]';
+        const role = el.getAttribute("role");
+        const ariaLabel = el.getAttribute("aria-label");
+        if (role && ariaLabel) {
+            return '[role="' + escapeAttr(role) + '"][aria-label="' + escapeAttr(ariaLabel) + '"]';
+        }
+        return synthTier3(el, tag);
+    }
+    function synth(el) {
+        const tag = (el.tagName || "").toLowerCase();
+        const raw = synthRaw(el, tag);
+        if (raw.length <= selectorMaxLen) {
+            return { selector: raw, truncated: false, originalLength: raw.length };
+        }
+        return { selector: tag || "*", truncated: true, originalLength: raw.length };
+    }
+    function bboxOf(el) {
+        try {
+            const r = el.getBoundingClientRect();
+            if (!r)
+                return null;
+            return { x: r.x, y: r.y, w: r.width, h: r.height };
+        }
+        catch (_) {
+            return null;
+        }
+    }
+    function inViewport(el) {
+        try {
+            const r = el.getBoundingClientRect();
+            const vw = window.innerWidth || document.documentElement.clientWidth || 0;
+            const vh = window.innerHeight || document.documentElement.clientHeight || 0;
+            // Fully off-screen if right<=0 OR bottom<=0 OR left>=vw OR top>=vh.
+            if (r.right <= 0 || r.bottom <= 0 || r.left >= vw || r.top >= vh)
+                return false;
+            return true;
+        }
+        catch (_) {
+            return true;
+        }
+    }
+    // 1. viewport-horizontal — singleton finding before the element walk.
+    let scanCapped = false;
+    if (wantVpHorizontal)
+        detectViewportHorizontal();
+    // 2. Element walk for layout / clipped / text-ellipsis.
+    if (wantLayout || wantClipped || wantEllipsis) {
+        let all;
+        try {
+            all = document.querySelectorAll("*");
+        }
+        catch (_) {
+            return { findings, scanCapped: false };
+        }
+        const totalCount = all.length;
+        const scanLimit = totalCount < args.maxElements ? totalCount : args.maxElements;
+        if (totalCount > args.maxElements)
+            scanCapped = true;
+        for (let i = 0; i < scanLimit; i++) {
+            const el = all[i];
+            if (el.nodeType !== 1)
+                continue;
+            if (args.scope === "viewport" && !inViewport(el))
+                continue;
+            let cs = null;
+            try {
+                cs = getComputedStyle(el);
+            }
+            catch (_) {
+                continue;
+            }
+            if (!cs)
+                continue;
+            classifyElement(el, cs);
+        }
+    }
+    return { findings, scanCapped };
+    // --- nested classifiers (must stay nested for page serialization) ---
+    /** Find the widest descendant whose bbox overruns the viewport (bounded scan
+     *  of the first 500 candidates so the singleton stays cheap). */
+    function widestOverrunDescendant(cw) {
+        let widestSel;
+        let widestW = 0;
+        try {
+            const candidates = document.body
+                ? document.body.querySelectorAll("*")
+                : [];
+            const max = candidates.length < 500 ? candidates.length : 500;
+            for (let i = 0; i < max; i++) {
+                const c = candidates[i];
+                const r = c.getBoundingClientRect();
+                if (r.right > cw + epsilon && r.width > widestW) {
+                    widestW = r.width;
+                    widestSel = synth(c).selector;
+                }
+            }
+        }
+        catch {
+            // best-effort widest-descendant scan; leave widestSel undefined on failure
+        }
+        return { sel: widestSel, w: widestW };
+    }
+    /** viewport-horizontal singleton — the document scrolls horizontally past the
+     *  viewport. Best-effort; skips on hostile docs. */
+    function detectViewportHorizontal() {
+        try {
+            const docEl = document.documentElement;
+            if (!docEl)
+                return;
+            const sw = docEl.scrollWidth;
+            const cw = docEl.clientWidth;
+            if (sw <= cw + epsilon)
+                return;
+            const widest = widestOverrunDescendant(cw);
+            findings.push({
+                selector: "html",
+                selectorTruncated: false,
+                selectorOriginalLength: 4,
+                bbox: { x: 0, y: 0, w: cw, h: docEl.clientHeight },
+                type: "viewport-horizontal",
+                evidence: {
+                    documentScrollWidth: sw,
+                    viewportWidth: cw,
+                    overrunPx: sw - cw,
+                    ...(widest.sel
+                        ? { widestDescendantSelector: widest.sel, widestDescendantWidth: widest.w }
+                        : {}),
+                },
+            });
+        }
+        catch {
+            // best-effort viewport-overflow probe; skip section on hostile docs
+        }
+    }
+    function classifyElement(el, cs) {
+        const geom = {
+            sw: el.scrollWidth,
+            sh: el.scrollHeight,
+            cw: el.clientWidth,
+            ch: el.clientHeight,
+        };
+        const overX = geom.sw > geom.cw + epsilon;
+        const overY = geom.sh > geom.ch + epsilon;
+        if (!overX && !overY && !wantEllipsis)
+            return;
+        const ox = cs.overflowX || "";
+        const oy = cs.overflowY || "";
+        detectLayoutClip(el, geom, { overX, overY, ox, oy });
+        detectEllipsis(el, cs, geom, overX);
+    }
+    /** Layout (overflow on a scrollable axis) + clipped (overflow on a hidden/clip
+     *  axis) findings share the same evidence shape; emit whichever matches. */
+    function detectLayoutClip(el, geom, o) {
+        const isScroll = (v) => v === "auto" || v === "scroll";
+        const isClip = (v) => v === "hidden" || v === "clip";
+        const evidence = {
+            scrollWidth: geom.sw,
+            clientWidth: geom.cw,
+            scrollHeight: geom.sh,
+            clientHeight: geom.ch,
+            overflowX: o.ox,
+            overflowY: o.oy,
+        };
+        if (wantLayout && ((o.overX && isScroll(o.ox)) || (o.overY && isScroll(o.oy)))) {
+            pushFinding(el, "layout", evidence);
+        }
+        if (wantClipped && ((o.overX && isClip(o.ox)) || (o.overY && isClip(o.oy)))) {
+            pushFinding(el, "clipped", evidence);
+        }
+    }
+    function detectEllipsis(el, cs, geom, overX) {
+        if (!wantEllipsis || (cs.textOverflow || "") !== "ellipsis" || !overX)
+            return;
+        // full text (DOM truth) + a heuristic visible prefix proportional to
+        // clientWidth/scrollWidth; the agent reads `fullText` for the truth.
+        const fullText = (el.textContent || "").replace(/\s+/g, " ").trim();
+        let visibleText = fullText;
+        if (geom.sw > 0 && geom.cw > 0 && fullText.length > 0) {
+            const cutoff = Math.max(0, Math.floor(fullText.length * (geom.cw / geom.sw)));
+            visibleText = fullText.slice(0, cutoff);
+        }
+        pushFinding(el, "text-ellipsis", {
+            scrollWidth: geom.sw,
+            clientWidth: geom.cw,
+            visibleText,
+            fullText,
+        });
+    }
+    function pushFinding(el, type, evidence) {
+        const s = synth(el);
+        findings.push({
+            selector: s.selector,
+            selectorTruncated: s.truncated,
+            selectorOriginalLength: s.originalLength,
+            bbox: bboxOf(el),
+            type,
+            evidence,
+        });
+    }
+};
+export async function detectOverflow(page, args = {}) {
+    const scope = args.scope ?? "document";
+    const typeSet = resolveTypes(args.types);
+    const rawLimit = args.limit ?? DEFAULT_LIMIT;
+    if (!(rawLimit > 0)) {
+        throw new Error(`overflow_detect: limit must be > 0 — got ${rawLimit}.`);
+    }
+    const limit = Math.min(rawLimit, MAX_LIMIT);
+    const raw = await page.evaluate(PAGE_DETECT_FN, {
+        types: Array.from(typeSet),
+        scope,
+        maxElements: MAX_ELEMENTS_SCANNED,
+        epsilon: OVERFLOW_EPSILON,
+        selectorMaxLen: SELECTOR_MAX_LEN,
+    });
+    const findings = [];
+    for (const rf of raw.findings) {
+        // If selector was truncated, fold the original-length note into
+        // evidence — the agent shouldn't have to guess why the selector is
+        // a bare tag.
+        if (rf.selectorTruncated) {
+            findings.push({
+                selector: rf.selector,
+                bbox: rf.bbox,
+                type: rf.type,
+                evidence: {
+                    selectorTruncated: true,
+                    originalLength: rf.selectorOriginalLength,
+                },
+            });
+        }
+        else {
+            findings.push({
+                selector: rf.selector,
+                bbox: rf.bbox,
+                type: rf.type,
+                evidence: rf.evidence,
+            });
+        }
+    }
+    const { kept, truncated } = applyLimit(findings, limit);
+    const warnings = [];
+    if (raw.scanCapped) {
+        warnings.push(`scan stopped at MAX_ELEMENTS_SCANNED (${MAX_ELEMENTS_SCANNED}) — re-run with scope:viewport for a narrower pass`);
+    }
+    return {
+        ok: true,
+        scope,
+        findings: kept,
+        truncated,
+        warnings,
+    };
+}

package/dist/page/pdf.d.ts

@@ -0,0 +1,69 @@
+import type { Page } from "playwright-core";
+/** Paper format presets Playwright's `page.pdf()` accepts. The full Playwright
+ *  set; surface every one rather than re-curating — adopters that need
+ *  jurisdiction-specific paper get it without a roundtrip back to us. */
+export type PdfFormat = "Letter" | "Legal" | "Tabloid" | "Ledger" | "A0" | "A1" | "A2" | "A3" | "A4" | "A5" | "A6";
+export interface PdfSaveArgs {
+    /** Workspace-rooted file path. Default `pdfs/<sessionId>-<ts>.pdf`. Caller
+     *  supplies a path → it's resolved inside `$BROWX_WORKSPACE` (escape
+     *  rejected); caller omits it → see `defaultPdfPath`. */
+    path?: string;
+    /** Paper format. Default "A4". */
+    format?: PdfFormat;
+    /** Render scale. Default 1. Playwright clamps to `[0.1, 2.0]`; values
+     *  outside that range are rejected up-front for a clearer error. */
+    scale?: number;
+    /** Include CSS `background-color` / `background-image` in the rendered
+     *  output. Default `false` (matches browser-print's default; caller opts
+     *  in when the artefact needs styled backgrounds). */
+    printBackground?: boolean;
+}
+export interface PdfSaveResult {
+    ok: true;
+    /** Absolute, workspace-rooted path the bytes were written to. */
+    path: string;
+    /** Final on-disk size, in bytes. */
+    bytes: number;
+    /** Paper format actually used. */
+    format: PdfFormat;
+    /** Scale actually used. */
+    scale: number;
+    /** Whether CSS backgrounds were printed. */
+    printBackground: boolean;
+}
+/** Refusal context — what the tool layer hands `assertPdfSupported`. */
+export interface PdfSupportContext {
+    /** Session mode (`registry.ts` vocabulary: `persistent` / `incognito` /
+     *  `attached`). `attached` is BYOB. */
+    mode: "persistent" | "incognito" | "attached";
+}
+/** Structured refusal — matches the shape `extensionRefusal` returns so the
+ *  tool layer can wrap it uniformly. */
+export interface PdfRefusal {
+    error: string;
+    hint: string;
+}
+/** Refuse PDF generation on session modes Playwright `page.pdf()` doesn't
+ *  support. BYOB (`attached`) is the only refusal today: printing on a
+ *  human's own Chrome would surface a print dialog / mutate window state, and
+ *  `page.pdf()` itself only works against a Chromium we own. Managed
+ *  `persistent` and `incognito` sessions are both supported (headed and
+ *  headless — the Playwright headless-only constraint applies to legacy
+ *  bundles; the bundle browxai ships against handles headed managed Chromium
+ *  fine).
+ *
+ *  Returns `null` when supported; a `{error, hint}` envelope when refused. */
+export declare function assertPdfSupported(ctx: PdfSupportContext): PdfRefusal | null;
+/** Default output path when the caller doesn't supply one. Workspace-rooted
+ *  under `pdfs/<sessionId>-<ts>.pdf` — matches the `perf_stop` /
+ *  `start_har` "subdir per artefact kind" convention. */
+export declare function defaultPdfPath(sessionId: string): string;
+/** Write `page.pdf()` to a workspace-rooted path. The caller has already
+ *  verified the session mode supports PDF (`assertPdfSupported`); this layer
+ *  resolves the path, validates inputs, and dispatches to Playwright.
+ *
+ *  Throws on:
+ *  - `path` escaping `$BROWX_WORKSPACE` (via `resolveWorkspacePath`).
+ *  - `scale` outside `[0.1, 2.0]`.
+ *  - Underlying `page.pdf()` failure (re-thrown with original message). */
+export declare function pdfSave(page: Page, workspaceRoot: string, sessionId: string, args?: PdfSaveArgs): Promise<PdfSaveResult>;

package/dist/page/pdf.js

@@ -0,0 +1,109 @@
+// `pdf_save` — print the current page to a workspace-rooted PDF.
+//
+// The mirror of `upload_file`: `upload_file` reads workspace-rooted bytes INTO
+// the page, `pdf_save` writes the page's print output OUT to workspace-rooted
+// bytes. Wraps Playwright's `page.pdf()` (CDP `Page.printToPDF` under the hood)
+// — the first-class alternative to "screenshot the page and OCR it back" or to
+// driving the browser's print-to-file dialog with `shortcut`.
+//
+// Workspace-rooted by construction: every path runs through
+// `resolveWorkspacePath` (same helper `start_har` / `dump_storage_state` /
+// `export_playwright_script` use). A path escaping `$BROWX_WORKSPACE` is
+// rejected — no on-disk trace ever lands outside the workspace.
+//
+// Defaults match what an agent reaching for "save the page as a PDF" expects
+// without reading the docs: A4 paper, scale 1, `printBackground:false` (matches
+// browser-print's default — caller opts in when background colour/imagery
+// matters for the artefact).
+//
+// **Chromium constraint:** `page.pdf()` is Chromium-only and refuses on
+// browser-side `attached` (BYOB) sessions — printing on a human's own Chrome
+// would surface a print dialog / mutate the human's window state. The tool
+// layer refuses cleanly with a structured error before we ever call into
+// Playwright (see `assertPdfSupported`).
+import { resolve as resolvePath } from "node:path";
+import { statSync } from "node:fs";
+import { resolveWorkspacePath } from "../session/storage.js";
+/** Refuse PDF generation on session modes Playwright `page.pdf()` doesn't
+ *  support. BYOB (`attached`) is the only refusal today: printing on a
+ *  human's own Chrome would surface a print dialog / mutate window state, and
+ *  `page.pdf()` itself only works against a Chromium we own. Managed
+ *  `persistent` and `incognito` sessions are both supported (headed and
+ *  headless — the Playwright headless-only constraint applies to legacy
+ *  bundles; the bundle browxai ships against handles headed managed Chromium
+ *  fine).
+ *
+ *  Returns `null` when supported; a `{error, hint}` envelope when refused. */
+export function assertPdfSupported(ctx) {
+    if (ctx.mode === "attached") {
+        return {
+            error: "pdf_save: not supported on attached / BYOB sessions — page.pdf() " +
+                "drives Chromium's PrintToPDF and would surface a print dialog / " +
+                "mutate the human's Chrome window state",
+            hint: 'open a managed session (open_session({mode:"persistent"}) or ' +
+                '{mode:"incognito"}) and re-run pdf_save against that.',
+        };
+    }
+    return null;
+}
+/** Default output path when the caller doesn't supply one. Workspace-rooted
+ *  under `pdfs/<sessionId>-<ts>.pdf` — matches the `perf_stop` /
+ *  `start_har` "subdir per artefact kind" convention. */
+export function defaultPdfPath(sessionId) {
+    // Sanitise sessionId for filesystem use (the registry already constrains
+    // ids to a safe character set; this is belt-and-braces against future
+    // changes there). Same posture as `defaultTracePath`.
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, "_") || "default";
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    return `pdfs/${safe}-${ts}.pdf`;
+}
+/** Write `page.pdf()` to a workspace-rooted path. The caller has already
+ *  verified the session mode supports PDF (`assertPdfSupported`); this layer
+ *  resolves the path, validates inputs, and dispatches to Playwright.
+ *
+ *  Throws on:
+ *  - `path` escaping `$BROWX_WORKSPACE` (via `resolveWorkspacePath`).
+ *  - `scale` outside `[0.1, 2.0]`.
+ *  - Underlying `page.pdf()` failure (re-thrown with original message). */
+export async function pdfSave(page, workspaceRoot, sessionId, args = {}) {
+    const format = args.format ?? "A4";
+    const scale = args.scale ?? 1;
+    const printBackground = args.printBackground ?? false;
+    if (scale < 0.1 || scale > 2.0) {
+        throw new Error(`pdf_save: scale must be in [0.1, 2.0] — got ${scale}. ` +
+            `Playwright's page.pdf() clamps the value at the underlying CDP layer; ` +
+            `we reject up-front for a clearer error.`);
+    }
+    const relPath = args.path ?? defaultPdfPath(sessionId);
+    const resolved = resolveWorkspacePath(workspaceRoot, relPath, "pdf_save");
+    const fsMod = await import("node:fs");
+    const pathMod = await import("node:path");
+    // Ensure parent dir exists — `resolved` is rooted in BROWX_WORKSPACE by
+    // construction (resolveWorkspacePath rejects escapes); Playwright's
+    // `page.pdf({path})` writes synchronously and fails if the dir is missing.
+    fsMod.mkdirSync(pathMod.dirname(resolved), { recursive: true });
+    await page.pdf({
+        path: resolved,
+        format,
+        scale,
+        printBackground,
+    });
+    let bytes = 0;
+    try {
+        bytes = statSync(resolved).size;
+    }
+    catch {
+        /* best-effort */
+    }
+    // Belt-and-braces: re-run resolve to surface the absolute path in the
+    // result (the input may have been relative).
+    const absolute = resolvePath(resolved);
+    return {
+        ok: true,
+        path: absolute,
+        bytes,
+        format,
+        scale,
+        printBackground,
+    };
+}

package/dist/page/perf-audit-analysers.d.ts

@@ -0,0 +1,40 @@
+import type { AuditContext, CategoryResult } from "./perf-audit-types.js";
+/** The audit category registry — the ONE place a category is declared. Each
+ *  key is a category name; each value is its analyser. `as const satisfies`
+ *  pins the keys as string literals (so `AuditCategory` derives a closed union)
+ *  while still type-checking every value against the analyser signature.
+ *
+ *  Order is meaningful — issues are surfaced in this order when severity ties. */
+export declare const ANALYSERS: {
+    readonly "render-blocking": typeof analyseRenderBlocking;
+    readonly "unused-code": typeof analyseUnusedCode;
+    readonly "oversize-images": typeof analyseOversizeImages;
+    readonly "layout-thrashing": typeof analyseLayoutThrashing;
+    readonly "long-tasks": typeof analyseLongTasks;
+    readonly "leak-suspects": typeof analyseLeakSuspects;
+    readonly "cache-opportunities": typeof analyseCacheOpportunities;
+    readonly "font-loading": typeof analyseFontLoading;
+};
+/** The closed audit-category vocabulary — DERIVED from `ANALYSERS`'s keys, never
+ *  hand-listed. A category exists iff it has an analyser. */
+export type AuditCategory = keyof typeof ANALYSERS;
+/** Every audit category, in declaration order — DERIVED from `ANALYSERS`. The
+ *  `Object.keys` cast is sound because the keys ARE the `AuditCategory` union. */
+export declare const ALL_AUDIT_CATEGORIES: AuditCategory[];
+export declare function analyseRenderBlocking(ctx: AuditContext): CategoryResult;
+/** unused-code — scripts + CSS files with `usagePercent < 30`. Severity tied
+ *  to absolute waste (bytes), not percent, because a 90%-dead 2KB file
+ *  doesn't matter. */
+export declare function analyseUnusedCode(ctx: AuditContext): CategoryResult;
+/** oversize-images — images > 500KB. */
+export declare function analyseOversizeImages(ctx: AuditContext): CategoryResult;
+/** layout-thrashing — > 5 forced sync layouts. */
+export declare function analyseLayoutThrashing(ctx: AuditContext): CategoryResult;
+/** long-tasks — `RunTask` events > 50ms. */
+export declare function analyseLongTasks(ctx: AuditContext): CategoryResult;
+/** leak-suspects — retainer-growth rows with deltaPercent > 10. */
+export declare function analyseLeakSuspects(ctx: AuditContext): CategoryResult;
+/** cache-opportunities — static assets missing `Cache-Control` header. */
+export declare function analyseCacheOpportunities(ctx: AuditContext): CategoryResult;
+/** font-loading — fonts loaded > 200ms after document start. */
+export declare function analyseFontLoading(ctx: AuditContext): CategoryResult;