browxai 0.7.0

package/dist/page/element-export.js

@@ -0,0 +1,251 @@
+/// <reference lib="dom" />
+// `element_export` — save a specific element subtree as a self-contained
+// HTML snippet plus its rendered CSS + linked resources.
+//
+// Sibling to `page_archive` (src/page/archive.ts), scoped to one element
+// subtree instead of the whole document. The use case is "extract this
+// component / card / table — I want the markup, the styles that make it
+// look like it does, and the images / fonts it pulls — to a directory I
+// can grep / diff / re-open offline".
+//
+// Two formats, same shape as page_archive:
+//
+//   - `directory` (default) — `<intoDir>/element.html` + `<intoDir>/assets/`
+//     with every fetched resource. Internal `[src]` / `[href]` /
+//     `background-image: url(...)` references in the element subtree are
+//     rewritten to relative `assets/<kind>/<file>` paths.
+//
+//   - `single-file` — one HTML file at `<intoDir>` (a `.html` path) with
+//     every linked resource inlined as `data:` URIs and computed styles
+//     inlined per element. Same browser-engine soft-cap caveat as
+//     `page_archive` (~150 MB).
+//
+// Resource discovery walks **only the element subtree** (not the whole
+// document) for `[src]`, `[href]`, and computed `background-image: url(...)`
+// — same heuristics as `archive.ts`'s DISCOVERY_SCRIPT but scoped to a
+// `Node` instead of `document`. Stylesheets are captured page-wide (a
+// stylesheet matters even if its rules only target the subtree); inline
+// `<style>` blocks from the page are likewise carried over. The pragmatic
+// trade-off: more CSS than strictly needed, but the snippet renders
+// faithfully without the agent having to compose style extraction.
+//
+// Secrets-masking interplay: same deliberate gap as `page_archive`. The
+// exported file is a faithful capture of the rendered subtree; running the
+// per-session egress masking layer over it would corrupt inline JSON / CSS
+// / binary bytes. The `warnings[]` array always carries the caveat as its
+// first entry.
+import { resolve as resolvePath, dirname, join } from "node:path";
+import { mkdirSync, writeFileSync, statSync } from "node:fs";
+import { resolveWorkspacePath } from "../session/storage.js";
+import { locatorFor } from "./locator.js";
+import { SUBTREE_DISCOVERY_FN, buildFetchScript, assetFilename, subdirForKind, mimeFromKind, rewriteHtml, directorySize, wrapStandalone, } from "./element-export-discovery.js";
+const DEFAULT_MAX_SIZE_MB = 50;
+const SINGLE_FILE_SOFT_WARN_MB = 150;
+const PER_RESOURCE_HARD_MB = 50;
+/** Default output target when `intoDir` is omitted. Workspace-relative,
+ *  namespaced under `elements/<sessionId>-<ISO>-<ref>` to match the
+ *  archive subdir-per-artefact convention. */
+export function defaultElementExportPath(sessionId, ref, format) {
+    const safeSession = sessionId.replace(/[^A-Za-z0-9._-]/g, "_") || "default";
+    const safeRef = ref.replace(/[^A-Za-z0-9._-]/g, "_") || "el";
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const stem = `elements/${safeSession}-${ts}-${safeRef}`;
+    return format === "single-file" ? `${stem}.html` : stem;
+}
+const CSP_HINTS = ["connect-src", "refused to connect", "content security policy"];
+/** Classify one fetched resource against the per-resource + total budget,
+ *  mutating the running totals. Returns the (possibly budget-rejected) entry. */
+function classifyFetched(f, maxBytes, phase) {
+    if (!f.r.ok) {
+        const err = (f.r.error ?? "").toLowerCase();
+        if (CSP_HINTS.some((h) => err.includes(h)))
+            phase.cspBlocked++;
+        return f;
+    }
+    const bytes = f.r.bytes ?? 0;
+    if (bytes > PER_RESOURCE_HARD_MB * 1024 * 1024) {
+        phase.perResourceOversize++;
+        return {
+            res: f.res,
+            r: { ok: false, error: `resource exceeded per-resource cap (${PER_RESOURCE_HARD_MB} MB)` },
+        };
+    }
+    if (phase.runningBytes + bytes > maxBytes) {
+        phase.budgetExhausted = true;
+        return { res: f.res, r: { ok: false, error: "size budget exhausted" } };
+    }
+    phase.runningBytes += bytes;
+    return f;
+}
+/** Fetch the discovered resources in bounded concurrency batches, applying the
+ *  per-resource + total size budgets. Stops early once the budget is exhausted
+ *  (the remaining resources are recorded as dropped). */
+async function fetchElementResources(page, resources, maxBytes) {
+    const CONCURRENCY = 6;
+    const phase = {
+        fetched: [],
+        cspBlocked: 0,
+        perResourceOversize: 0,
+        runningBytes: 0,
+        budgetExhausted: false,
+    };
+    for (let i = 0; i < resources.length; i += CONCURRENCY) {
+        const settled = await Promise.all(resources.slice(i, i + CONCURRENCY).map(async (res) => {
+            try {
+                return { res, r: (await page.evaluate(buildFetchScript(res.url))) };
+            }
+            catch (e) {
+                return { res, r: { ok: false, error: e instanceof Error ? e.message : String(e) } };
+            }
+        }));
+        for (const f of settled)
+            phase.fetched.push(classifyFetched(f, maxBytes, phase));
+        if (phase.budgetExhausted) {
+            for (let j = i + CONCURRENCY; j < resources.length; j++) {
+                phase.fetched.push({
+                    res: resources[j],
+                    r: { ok: false, error: "size budget exhausted" },
+                });
+            }
+            break;
+        }
+    }
+    return phase;
+}
+/** Push the post-fetch budget/CSP warnings onto the result warnings. */
+function appendFetchWarnings(phase, maxSizeMb, warnings) {
+    if (phase.cspBlocked > 0) {
+        warnings.push(`${phase.cspBlocked} resource(s) blocked by the page's Content-Security-Policy ` +
+            "(typically `connect-src`). Counted in droppedCount.");
+    }
+    if (phase.perResourceOversize > 0) {
+        warnings.push(`${phase.perResourceOversize} resource(s) exceeded the per-resource ${PER_RESOURCE_HARD_MB} MB cap and were dropped.`);
+    }
+    if (phase.budgetExhausted) {
+        warnings.push(`Export size cap (maxSizeMb=${maxSizeMb}) reached — remaining resources were dropped. ` +
+            "Raise `maxSizeMb` to capture more.");
+    }
+}
+/** Emit the multi-file directory export — each fetched asset written under
+ *  `assets/<kind>/`, the HTML rewritten to point at the relative paths. */
+function emitDirectory(resolved, discovered, fetched, runningBytes) {
+    // workspace-rooted (resolveWorkspacePath rejects any escape from BROWX_WORKSPACE).
+    mkdirSync(resolved, { recursive: true });
+    const assetsRoot = join(resolved, "assets");
+    mkdirSync(assetsRoot, { recursive: true });
+    let resourceCount = 0;
+    let droppedCount = 0;
+    const replacements = [];
+    for (const f of fetched) {
+        if (!f.r.ok || !f.r.base64) {
+            droppedCount++;
+            continue;
+        }
+        const subdir = subdirForKind(f.res.kind);
+        const dir = join(assetsRoot, subdir);
+        mkdirSync(dir, { recursive: true });
+        const filename = assetFilename(f.res.url, f.res.kind, f.r.contentType ?? "");
+        writeFileSync(join(dir, filename), Buffer.from(f.r.base64, "base64"));
+        replacements.push({ rawRef: f.res.rawRef, replacement: `assets/${subdir}/${filename}` });
+        resourceCount++;
+    }
+    const standalone = wrapStandalone(rewriteHtml(discovered.html, replacements), discovered.css, "");
+    writeFileSync(join(resolved, "element.html"), standalone, "utf8");
+    let sizeBytes;
+    try {
+        sizeBytes = directorySize(resolved);
+    }
+    catch {
+        sizeBytes = Buffer.byteLength(standalone, "utf8") + runningBytes;
+    }
+    return { resourceCount, droppedCount, sizeBytes };
+}
+/** Emit the single-file export — assets inlined as data: URIs in the HTML. */
+function emitSingleFile(resolved, discovered, fetched, warnings) {
+    // workspace-rooted: dirname(resolved) is the parent of a BROWX_WORKSPACE-anchored path.
+    mkdirSync(dirname(resolved), { recursive: true });
+    let resourceCount = 0;
+    let droppedCount = 0;
+    const replacements = [];
+    for (const f of fetched) {
+        if (!f.r.ok || !f.r.base64) {
+            droppedCount++;
+            continue;
+        }
+        const mime = (f.r.contentType ?? "").split(";")[0].trim() || mimeFromKind(f.res.kind);
+        replacements.push({ rawRef: f.res.rawRef, replacement: `data:${mime};base64,${f.r.base64}` });
+        resourceCount++;
+    }
+    const standalone = wrapStandalone(rewriteHtml(discovered.html, replacements), discovered.css, "");
+    writeFileSync(resolved, standalone, "utf8");
+    const sizeBytes = statSync(resolved).size;
+    if (sizeBytes > SINGLE_FILE_SOFT_WARN_MB * 1024 * 1024) {
+        warnings.push(`single-file export is ${(sizeBytes / 1024 / 1024).toFixed(1)} MB. ` +
+            `Browsers commonly struggle past ~${SINGLE_FILE_SOFT_WARN_MB} MB — use \`format:"directory"\` for large subtrees.`);
+    }
+    return { resourceCount, droppedCount, sizeBytes };
+}
+/** Ensure the locator resolves to a real element; throws a clean message
+ *  otherwise (count() is fast and avoids a confusing `evaluate` failure). */
+async function assertResolves(locator, ref) {
+    let matchCount;
+    try {
+        matchCount = await locator.count();
+    }
+    catch (e) {
+        throw new Error(`element_export: ref "${ref}" did not resolve — ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (matchCount === 0) {
+        throw new Error(`element_export: ref "${ref}" did not match any element (re-snapshot the page or pass a fresh ref).`);
+    }
+}
+export async function elementExport(page, locator, workspaceRoot, sessionId, args) {
+    const format = args.format ?? "directory";
+    const maxSizeMb = args.maxSizeMb ?? DEFAULT_MAX_SIZE_MB;
+    if (!(maxSizeMb > 0) || maxSizeMb > 10_000) {
+        throw new Error(`element_export: maxSizeMb must be in (0, 10000] — got ${maxSizeMb}.`);
+    }
+    const maxBytes = Math.floor(maxSizeMb * 1024 * 1024);
+    const relPath = args.intoDir ?? defaultElementExportPath(sessionId, args.ref, format);
+    const resolved = resolveWorkspacePath(workspaceRoot, relPath, "element_export");
+    await assertResolves(locator, args.ref);
+    // 1. Subtree discovery — outerHTML + page-wide CSS + linked resources.
+    const discovered = await locator.evaluate(SUBTREE_DISCOVERY_FN);
+    const warnings = [
+        "element_export output is UNMASKED — secrets-masking would corrupt the export (literal-substring substitution breaks inline JSON / CSS / binary bytes). Treat the export as sensitive material, same posture as page_archive / dump_storage_state.",
+    ];
+    if (discovered.unreadableStylesheets > 0) {
+        warnings.push(`${discovered.unreadableStylesheets} stylesheet(s) were cross-origin without CORS and could not be read into the export. ` +
+            "Rules from those sheets that targeted the subtree won't appear in the captured CSS — the snippet may render differently than the source page.");
+    }
+    // 2. Fetch resources in bounded batches.
+    const phase = await fetchElementResources(page, discovered.resources, maxBytes);
+    appendFetchWarnings(phase, maxSizeMb, warnings);
+    // 3. Emit the export.
+    const emit = format === "directory"
+        ? emitDirectory(resolved, discovered, phase.fetched, phase.runningBytes)
+        : emitSingleFile(resolved, discovered, phase.fetched, warnings);
+    return {
+        ok: true,
+        format,
+        ref: args.ref,
+        path: resolvePath(resolved),
+        sizeBytes: emit.sizeBytes,
+        resourceCount: emit.resourceCount,
+        droppedCount: emit.droppedCount,
+        warnings,
+    };
+}
+/**
+ * Server-facing helper: resolve a ref through the registry, then call
+ * `elementExport`. Lives here so the server.ts call site is a one-liner.
+ */
+export async function elementExportFromRef(page, refs, workspaceRoot, sessionId, args) {
+    const locator = locatorFor(page, refs, { ref: args.ref });
+    const adapter = {
+        count: () => locator.count(),
+        evaluate: (fn) => locator.evaluate(fn),
+    };
+    const pageAdapter = { evaluate: (expr) => page.evaluate(expr) };
+    return elementExport(pageAdapter, adapter, workspaceRoot, sessionId, args);
+}

package/dist/page/emulation-substrate.d.ts

@@ -0,0 +1,53 @@
+import type { BrowserContext, Page } from "playwright-core";
+import type { SafariSessionHandle } from "../engine/index.js";
+import type { ColorScheme, GeolocationCoords, ReducedMotion } from "../session/emulation.js";
+/** The live mutation succeeded; the handler folds the engine state into its
+ *  `deviceEmulation` bag and renders the standard `applied` envelope. */
+export interface EmulationApplied {
+    kind: "applied";
+}
+/** An engine that has no live surface for this knob (Safari). The handler renders
+ *  `error`/`hint` as the same failure envelope its `catch` produced pre-seam, with
+ *  no `deviceEmulation` mutation — the override was never applied. */
+export interface EmulationRefusal {
+    kind: "refusal";
+    error: string;
+    hint?: string;
+}
+export type EmulationResult = EmulationApplied | EmulationRefusal;
+/** The live-emulation capability port. One instance wraps one session's engine
+ *  handle; the methods carry no engine type, so the handlers above this seam are
+ *  engine-blind. Mirrors the ActionSubstrate / CaptureSubstrate shape. `null`
+ *  coords clears the geolocation override. */
+export interface EmulationSubstrate {
+    readonly engine: string;
+    setGeolocation(coords: GeolocationCoords | null): Promise<EmulationResult>;
+    setColorScheme(scheme: ColorScheme): Promise<EmulationResult>;
+    setReducedMotion(motion: ReducedMotion): Promise<EmulationResult>;
+}
+/** Playwright engines — delegates each live mutation to the existing emulation
+ *  appliers over the session's context/page (the `context`/`page` thunks capture
+ *  the session entry, the same per-call access the handlers did before this seam).
+ *  No behaviour change. */
+export declare class PlaywrightEmulationSubstrate implements EmulationSubstrate {
+    private readonly context;
+    private readonly page;
+    readonly engine: string;
+    constructor(context: () => BrowserContext, page: () => Page, engine?: string);
+    setGeolocation(coords: GeolocationCoords | null): Promise<EmulationResult>;
+    setColorScheme(scheme: ColorScheme): Promise<EmulationResult>;
+    setReducedMotion(motion: ReducedMotion): Promise<EmulationResult>;
+}
+/** Safari — no live-emulation surface beyond viewport. safaridriver (WebDriver
+ *  Classic) has no geolocation / `prefers-color-scheme` / `prefers-reduced-motion`
+ *  mutator, so all three refuse cleanly here — the gating is in the adapter, not
+ *  the handler. These handlers had NO Safari branch pre-seam (they threw at
+ *  `page()` / `context()`); the structured refusal replaces that crash. */
+export declare class SafariEmulationSubstrate implements EmulationSubstrate {
+    readonly engine = "safari";
+    constructor(_handle: SafariSessionHandle);
+    setGeolocation(): Promise<EmulationResult>;
+    setColorScheme(): Promise<EmulationResult>;
+    setReducedMotion(): Promise<EmulationResult>;
+    private refuse;
+}

package/dist/page/emulation-substrate.js

@@ -0,0 +1,87 @@
+// The EmulationSubstrate interface — the engine-agnostic seam beneath the live
+// device-emulation tools (`set_geolocation` / `set_color_scheme` /
+// `set_reduced_motion`). It is the engine-agnostic emulation seam: a tool handler
+// asks a substrate to mutate ONE live-emulation knob and gets back a universal
+// result; an engine-specific implementation does the work. The handler never
+// names Playwright, safaridriver, or an engine — it calls
+// `emulationFor(e).setColorScheme(scheme)`, the same shape as
+// `actionsFor(e).click(args)` / `captureFor(e).screenshot(req)`.
+//
+// Scope: ONLY the three cross-browser, live-mutator emulation primitives — the
+// ones backed by a Playwright context/page mutator (`context.setGeolocation`,
+// `page.emulateMedia`) that takes effect mid-session. The CDP-only primitives
+// (`set_locale` / `set_timezone` / `set_user_agent`) stay engine-gated through
+// `assertEngineSupports` (they need the raw-CDP escape hatch and have no live
+// off-Chromium setter), and `set_viewport` lives in the ActionSubstrate — none
+// of those are this port's concern.
+//
+// Dependency direction (architecture doctrine §1): tool handler →
+// EmulationSubstrate (this interface) → implementation → Playwright | safaridriver.
+// Two impls today:
+//   - PlaywrightEmulationSubstrate (chromium / firefox / webkit / android): wraps
+//     the existing `applyGeolocation` / `clearGeolocation` / `applyColorScheme` /
+//     `applyReducedMotion` over a Playwright context/page — byte-identical to the
+//     pre-seam handler, so the four engines' keystones stay green unchanged. The
+//     handler keeps the `deviceEmulation` state mutation + the geolocation-
+//     permission warning + the result envelope; the substrate only performs the
+//     live mutation.
+//   - SafariEmulationSubstrate (safari): safaridriver exposes no live-emulation
+//     surface beyond viewport, so all three refuse cleanly IN THE ADAPTER (the
+//     gating lives here, not as an `if (e.session.safari?.())` branch in the
+//     handlers — these handlers had no Safari branch and threw at `page()` /
+//     `context()` before this seam).
+import { applyColorScheme, applyGeolocation, applyReducedMotion, clearGeolocation, } from "../session/emulation.js";
+/** Playwright engines — delegates each live mutation to the existing emulation
+ *  appliers over the session's context/page (the `context`/`page` thunks capture
+ *  the session entry, the same per-call access the handlers did before this seam).
+ *  No behaviour change. */
+export class PlaywrightEmulationSubstrate {
+    context;
+    page;
+    engine;
+    constructor(context, page, engine = "chromium") {
+        this.context = context;
+        this.page = page;
+        this.engine = engine;
+    }
+    async setGeolocation(coords) {
+        if (coords === null)
+            await clearGeolocation(this.context());
+        else
+            await applyGeolocation(this.context(), coords);
+        return { kind: "applied" };
+    }
+    async setColorScheme(scheme) {
+        await applyColorScheme(this.page(), scheme);
+        return { kind: "applied" };
+    }
+    async setReducedMotion(motion) {
+        await applyReducedMotion(this.page(), motion);
+        return { kind: "applied" };
+    }
+}
+/** Safari — no live-emulation surface beyond viewport. safaridriver (WebDriver
+ *  Classic) has no geolocation / `prefers-color-scheme` / `prefers-reduced-motion`
+ *  mutator, so all three refuse cleanly here — the gating is in the adapter, not
+ *  the handler. These handlers had NO Safari branch pre-seam (they threw at
+ *  `page()` / `context()`); the structured refusal replaces that crash. */
+export class SafariEmulationSubstrate {
+    engine = "safari";
+    constructor(_handle) { }
+    setGeolocation() {
+        return Promise.resolve(this.refuse("set_geolocation"));
+    }
+    setColorScheme() {
+        return Promise.resolve(this.refuse("set_color_scheme"));
+    }
+    setReducedMotion() {
+        return Promise.resolve(this.refuse("set_reduced_motion"));
+    }
+    refuse(tool) {
+        return {
+            kind: "refusal",
+            error: `\`${tool}\` is not supported on the Safari engine — safaridriver exposes no live-emulation surface beyond viewport.`,
+            hint: "Use a chromium, firefox, or webkit session for live geolocation / colour-scheme / reduced-motion overrides.",
+        };
+    }
+}

package/dist/page/emulation.d.ts

@@ -0,0 +1,60 @@
+import type { CDPSession, Page } from "playwright-core";
+/** All fields optional. Empty object == reset. */
+export interface NetworkEmulationInput {
+    offline?: boolean;
+    /** One-way latency in ms (CDP doubles it for round-trip). */
+    latencyMs?: number;
+    /** Max download throughput in bytes/sec. 0 / unset → unthrottled. */
+    downloadBps?: number;
+    /** Max upload throughput in bytes/sec. 0 / unset → unthrottled. */
+    uploadBps?: number;
+    /** 0..1 — passed straight through (CDP supports it; most chromium builds
+     *  ignore it but it's documented as a hint). */
+    packetLoss?: number;
+}
+export interface CpuEmulationInput {
+    /** 1 = no throttle. 2 = 2× slowdown. 4–6 simulates a low-end device. */
+    throttleRate?: number;
+}
+export interface NetworkEmulationState {
+    offline: boolean;
+    latencyMs: number;
+    downloadBps: number;
+    uploadBps: number;
+    packetLoss?: number;
+}
+export interface CpuEmulationState {
+    throttleRate: number;
+}
+/** The "no override" defaults — both tools' "reset" calls collapse to this. */
+export declare const DEFAULT_NETWORK: NetworkEmulationState;
+export declare const DEFAULT_CPU: CpuEmulationState;
+/** Per-session emulation cache + re-applier. One per SessionEntry. */
+export declare class EmulationRegistry {
+    private network;
+    private cpu;
+    /** Re-apply hook installed once per page on first use. */
+    private reattachInstalled;
+    /** Apply network conditions and remember them. Returns the normalized state
+     *  that's now active. */
+    applyNetwork(cdp: CDPSession, page: Page, input: NetworkEmulationInput): Promise<{
+        state: NetworkEmulationState;
+        reset: boolean;
+    }>;
+    /** Apply CPU throttling and remember it. */
+    applyCpu(cdp: CDPSession, page: Page, input: CpuEmulationInput): Promise<{
+        state: CpuEmulationState;
+        reset: boolean;
+    }>;
+    /** Reset both overrides — used by close/teardown paths if needed. */
+    resetAll(cdp: CDPSession): Promise<void>;
+    /** Test introspection: the currently-cached state, or undefined if not set. */
+    currentNetwork(): NetworkEmulationState | undefined;
+    currentCpu(): CpuEmulationState | undefined;
+    /** Defensive re-apply: CDP overrides are *usually* per-target and survive
+     *  navigation, but cross-process renderer swaps + incognito teardowns can
+     *  drop them. Re-push the cached state on every main-frame navigation. */
+    private installReattach;
+    private sendNetwork;
+    private sendCpu;
+}

package/dist/page/emulation.js

@@ -0,0 +1,162 @@
+// Network + CPU emulation — capability `action`.
+//
+// Wraps two CDP primitives so flaky-mobile / offline / low-end-device repros
+// stop requiring a real lab device:
+//   - Network.emulateNetworkConditions  → `NetworkEmulation`
+//   - Emulation.setCPUThrottlingRate    → `CpuEmulation`
+//
+// Both are per-target overrides; CDP keeps them applied for the lifetime of
+// the *target*. But a renderer swap (cross-process navigation), a fresh page,
+// or some incognito teardown corners can drop them — so we cache the active
+// state per session and re-apply on `framenavigated` for the main frame.
+// Plays cleanly with `route` / `route_queue`: the route handler's `delayMs`
+// stacks ON TOP of the emulated latency, by design.
+//
+// Reset semantics:
+//   - `network_emulate({})` / `{offline:false}` (with no latency/bps/loss) →
+//     clears the override (offline=false, latency 0, bps -1, packetLoss 0).
+//   - `cpu_emulate({})` / `{throttleRate:1}` → clears the override (rate 1).
+//
+// BYOB note: overrides apply to the attached Chrome's page for as long as
+// CDP holds them. After our session detaches, the human's DevTools Network /
+// Performance panels may still show the throttled state until they reset it
+// or close the page — surfaced as a `warning` on the result.
+/** The "no override" defaults — both tools' "reset" calls collapse to this. */
+export const DEFAULT_NETWORK = {
+    offline: false,
+    latencyMs: 0,
+    downloadBps: 0,
+    uploadBps: 0,
+};
+export const DEFAULT_CPU = { throttleRate: 1 };
+const MAX_LATENCY_MS = 600_000;
+const MAX_BPS = 10_000_000_000; // 10 GB/s — generous; really a sanity ceiling
+const MAX_CPU_RATE = 100;
+function clampNonNeg(n, max) {
+    if (n === undefined || n === null || !Number.isFinite(n) || n < 0)
+        return 0;
+    return Math.min(n, max);
+}
+function normalizeNetwork(input) {
+    const state = {
+        offline: input.offline === true,
+        latencyMs: clampNonNeg(input.latencyMs, MAX_LATENCY_MS),
+        downloadBps: clampNonNeg(input.downloadBps, MAX_BPS),
+        uploadBps: clampNonNeg(input.uploadBps, MAX_BPS),
+    };
+    if (input.packetLoss !== undefined) {
+        if (!Number.isFinite(input.packetLoss) || input.packetLoss < 0 || input.packetLoss > 1) {
+            throw new Error(`network_emulate: packetLoss must be between 0 and 1 (got ${input.packetLoss})`);
+        }
+        state.packetLoss = input.packetLoss;
+    }
+    return state;
+}
+function normalizeCpu(input) {
+    const r = input.throttleRate;
+    if (r === undefined || r === null)
+        return { throttleRate: 1 };
+    if (!Number.isFinite(r) || r < 1 || r > MAX_CPU_RATE) {
+        throw new Error(`cpu_emulate: throttleRate must be between 1 and ${MAX_CPU_RATE} (got ${r})`);
+    }
+    return { throttleRate: r };
+}
+function isNetworkReset(s) {
+    return (!s.offline &&
+        s.latencyMs === 0 &&
+        s.downloadBps === 0 &&
+        s.uploadBps === 0 &&
+        (s.packetLoss === undefined || s.packetLoss === 0));
+}
+function isCpuReset(s) {
+    return s.throttleRate === 1;
+}
+/** Per-session emulation cache + re-applier. One per SessionEntry. */
+export class EmulationRegistry {
+    network;
+    cpu;
+    /** Re-apply hook installed once per page on first use. */
+    reattachInstalled = new WeakSet();
+    /** Apply network conditions and remember them. Returns the normalized state
+     *  that's now active. */
+    async applyNetwork(cdp, page, input) {
+        const state = normalizeNetwork(input);
+        await this.sendNetwork(cdp, state);
+        this.network = state;
+        this.installReattach(page);
+        return { state, reset: isNetworkReset(state) };
+    }
+    /** Apply CPU throttling and remember it. */
+    async applyCpu(cdp, page, input) {
+        const state = normalizeCpu(input);
+        await this.sendCpu(cdp, state);
+        this.cpu = state;
+        this.installReattach(page);
+        return { state, reset: isCpuReset(state) };
+    }
+    /** Reset both overrides — used by close/teardown paths if needed. */
+    async resetAll(cdp) {
+        if (this.network && !isNetworkReset(this.network)) {
+            await this.sendNetwork(cdp, DEFAULT_NETWORK).catch(() => undefined);
+        }
+        if (this.cpu && !isCpuReset(this.cpu)) {
+            await this.sendCpu(cdp, DEFAULT_CPU).catch(() => undefined);
+        }
+        this.network = undefined;
+        this.cpu = undefined;
+    }
+    /** Test introspection: the currently-cached state, or undefined if not set. */
+    currentNetwork() {
+        return this.network;
+    }
+    currentCpu() {
+        return this.cpu;
+    }
+    /** Defensive re-apply: CDP overrides are *usually* per-target and survive
+     *  navigation, but cross-process renderer swaps + incognito teardowns can
+     *  drop them. Re-push the cached state on every main-frame navigation. */
+    installReattach(page) {
+        if (this.reattachInstalled.has(page))
+            return;
+        this.reattachInstalled.add(page);
+        const onNav = async (frame) => {
+            // main frame only
+            if (frame.parentFrame())
+                return;
+            try {
+                // re-acquire the CDP session via the page's context — the original
+                // session ref may be stale after a renderer swap.
+                const cdp = await page
+                    .context()
+                    .newCDPSession(page)
+                    .catch(() => null);
+                if (!cdp)
+                    return;
+                if (this.network && !isNetworkReset(this.network)) {
+                    await this.sendNetwork(cdp, this.network).catch(() => undefined);
+                }
+                if (this.cpu && !isCpuReset(this.cpu)) {
+                    await this.sendCpu(cdp, this.cpu).catch(() => undefined);
+                }
+            }
+            catch {
+                // page may have closed mid-navigation; swallow
+            }
+        };
+        // playwright's framenavigated fires for every frame; we filter inside.
+        page.on("framenavigated", onNav);
+    }
+    async sendNetwork(cdp, s) {
+        // CDP wants -1 for "no throttle" on bps fields; map 0 → -1.
+        await cdp.send("Network.emulateNetworkConditions", {
+            offline: s.offline,
+            latency: s.latencyMs,
+            downloadThroughput: s.downloadBps > 0 ? s.downloadBps : -1,
+            uploadThroughput: s.uploadBps > 0 ? s.uploadBps : -1,
+            ...(s.packetLoss !== undefined ? { packetLoss: s.packetLoss } : {}),
+        });
+    }
+    async sendCpu(cdp, s) {
+        await cdp.send("Emulation.setCPUThrottlingRate", { rate: s.throttleRate });
+    }
+}

package/dist/page/export-playwright-script.d.ts

@@ -0,0 +1,47 @@
+import type { RecordedStep } from "./recording.js";
+import type { DispatchedAction } from "./actionresult.js";
+export interface LoweredStep {
+    /** Source lines for this step — each entry is one line in the emitted file
+     *  (no trailing newlines). Always wrapped in the test body's indentation
+     *  by the caller; the lines themselves are flush-left. */
+    lines: string[];
+    /** True when the step's selector was tier-5 / role-only / otherwise low-
+     *  confidence at recording time. The caller surfaces this as a TODO
+     *  comment above the lines. */
+    fragile: boolean;
+    /** Diagnostic — was this step lowered to a real Playwright call, or to a
+     *  `// TODO:` placeholder because we don't know how to lower its action
+     *  type? Drives the result's `unhandled` counter so the agent can see
+     *  whether the export captured everything. */
+    handled: boolean;
+}
+export interface LowerResult {
+    /** Complete `.spec.ts` source. Always includes the `@playwright/test`
+     *  import + a single `test(...)` shell, even when the trace is empty
+     *  (the body is then just a `// No steps recorded.` placeholder). */
+    source: string;
+    /** Diagnostics for the caller. */
+    stats: {
+        steps: number;
+        handled: number;
+        unhandled: number;
+        fragile: number;
+    };
+}
+/** Lower a recorded trace to a Playwright spec source string. Pure; the
+ *  caller decides whether to write it to disk. */
+export declare function lowerTraceToSpec(flowName: string, steps: ReadonlyArray<RecordedStep>): LowerResult;
+export declare function lowerStep(step: RecordedStep): LoweredStep;
+/** Lower a recorded `selectorHint` into a Playwright locator expression
+ *  rooted at the `page` identifier. Mirrors `parseSelectorHint` in
+ *  `./locator.ts`. */
+export declare function locatorExprFor(step: RecordedStep): string;
+/** Pure; exported for unit tests. */
+export declare function locatorExprFromHint(hint: string): string;
+export declare function parseCheck(source: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type { RecordedStep, DispatchedAction };