browxai 0.7.0

package/dist/page/actions.js

@@ -0,0 +1,453 @@
+// Action primitives. Each wraps a Playwright `Locator` action in the
+// action-window machinery from actionresult.ts so callers always get a
+// structured `ActionResult` instead of a bare "ok".
+import { runInActionWindow, } from "./actionresult.js";
+import { locatorFor, resolveTargetChecked } from "./locator.js";
+import { preProbe, probe, captureHit, captureFocusedRef } from "./actions-probe.js";
+import { windowScrollGeometry, elementScrollGeometry, } from "./actions-scroll.js";
+// aligned with the anti-wedge default (5s). Inner Playwright ops use
+// the per-call `deadlineMs` when provided so a raised `timeoutMs` is honoured
+// by the inner op too (not just the outer race in runInActionWindow).
+const DEFAULT_TIMEOUT_MS = 5_000;
+export async function click(ctx, args) {
+    const descriptor = { type: "click", ...targetDescriptor(args.target) };
+    const { resolved, warning } = await resolveTargetChecked(ctx.page, ctx.refs, args.target);
+    const opts = warning
+        ? { ...args, extraWarnings: [...(args.extraWarnings ?? []), warning] }
+        : args;
+    return runInActionWindow(ctx, descriptor, opts, async () => {
+        if (resolved.kind === "coords") {
+            const hitBefore = await captureHit(ctx.page, resolved.x, resolved.y);
+            const focusBefore = await captureFocusedRef(ctx.page);
+            await ctx.page.mouse.click(resolved.x, resolved.y, args.button ? { button: args.button } : undefined);
+            const hitAfter = await captureHit(ctx.page, resolved.x, resolved.y);
+            const focusAfter = await captureFocusedRef(ctx.page);
+            return {
+                stillAttached: true,
+                hit: {
+                    before: hitBefore,
+                    after: hitAfter,
+                    focusChanged: focusBefore !== focusAfter,
+                },
+            };
+        }
+        const pre = await preProbe(resolved.loc);
+        // Click strategy: try the standard actionability path first with a
+        // SHORTER budget than the outer action deadline, so the auto-recovery
+        // pass with `force: true` has headroom. The recovery surfaces a
+        // warning so the caller knows the click-only pre-dispatch path was
+        // bypassed. Explicit `force:true` from the caller skips the strategy
+        // entirely.
+        //
+        // RCA (adopter, 2026-06-08): the busy-SPA cost is Playwright's
+        // mousedown hit-target interceptor — the one pre-dispatch check
+        // `click` does that `hover` does not (~500ms hover vs ~4s click on
+        // the same provably-actionable static element). Visibility /
+        // stability / receives-events / bbox aren't the culprit. `force: true`
+        // skips the interceptor.
+        const fullTimeout = args.deadlineMs ?? DEFAULT_TIMEOUT_MS;
+        if (args.force) {
+            await resolved.loc.click({ timeout: fullTimeout, button: args.button, force: true });
+            return probe(resolved.loc, args.target, undefined, pre);
+        }
+        // Reserve ~30% of the deadline for the recovery click; the rest is
+        // the actionability budget. Floor at 500ms each so neither path is
+        // unreasonably short on tiny custom deadlines.
+        const recoveryMs = Math.max(500, Math.floor(fullTimeout * 0.3));
+        const actionabilityMs = Math.max(500, fullTimeout - recoveryMs);
+        try {
+            await resolved.loc.click({ timeout: actionabilityMs, button: args.button });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            const isActionabilityTimeout = /Timeout|exceeded|element is not stable|element is not visible|element is outside of the viewport|element is not enabled|intercepts pointer events|did not receive/i.test(msg);
+            if (!isActionabilityTimeout)
+                throw e;
+            // Auto-recovery: the actionability check timed out. Try once with
+            // `force: true` — common on busy SPAs (perpetual rAF / WS keepalives /
+            // re-renders) where the stability check thrashes forever but the
+            // element IS clickable. Surface the recovery via an extra warning so
+            // the caller doesn't silently get a force-click they didn't opt into.
+            await resolved.loc.click({ timeout: recoveryMs, button: args.button, force: true });
+            const probed = await probe(resolved.loc, args.target, undefined, pre);
+            // Stamp the recovery warning on the probe — `runInActionWindow`
+            // splices probe.warnings[] onto the result's top-level warnings.
+            probed.warnings = [
+                `click: actionability path exceeded ${actionabilityMs}ms — recovered via \`force: true\` (bypasses Playwright's mousedown hit-target interceptor, the click-specific pre-dispatch check that loops/retries on busy SPAs). The page-side click event DID fire (trusted). Pass \`force: true\` explicitly on known-clickable targets to skip the auto-recovery and dispatch immediately. RCA reference: \`hover\` on the same element takes ~500ms vs \`click\` ~4s — the cost is entirely the click-only interceptor, not stability/visibility/receives-events.`,
+            ];
+            return probed;
+        }
+        return probe(resolved.loc, args.target, undefined, pre);
+    });
+}
+export async function fill(ctx, args) {
+    // Secrets materialisation: a `<NAME>`-shaped `value` is swapped for the
+    // registered real string AT dispatch. The descriptor records the alias
+    // (`<NAME>`), NEVER the real value — so `ActionResult.action.value`, any
+    // recorder appendage, and the post-probe's `valueRequested` echo the
+    // alias. Plain strings pass through unchanged.
+    const mat = materialiseValue(ctx, args.value);
+    if (!mat.ok)
+        return failedFill(args, mat.error);
+    const descriptorValue = mat.alias ? `<${mat.alias}>` : args.value;
+    const descriptor = {
+        type: "fill",
+        value: descriptorValue,
+        ...refOrSelector(args.target),
+    };
+    return runInActionWindow(ctx, descriptor, args, async () => {
+        const loc = locatorFor(ctx.page, ctx.refs, args.target);
+        const pre = await preProbe(loc);
+        await loc.fill(mat.value, { timeout: args.deadlineMs ?? DEFAULT_TIMEOUT_MS });
+        // pass the alias as `valueRequested` so `value === valueRequested`
+        // comparison still works without the real secret reaching the probe.
+        const probed = await probe(loc, args.target, descriptorValue, pre);
+        // Defence-in-depth: the field's DOM value reflects what we typed, so
+        // `probed.value` carries the secret. Mask before returning — the
+        // action-window will surface it on the ActionResult otherwise.
+        return maskProbe(probed, ctx);
+    });
+}
+export async function navigate(ctx, args) {
+    const descriptor = { type: "navigate", url: args.url };
+    return runInActionWindow(ctx, descriptor, args, async () => {
+        await ctx.page.goto(args.url, {
+            waitUntil: "domcontentloaded",
+            timeout: args.deadlineMs ?? DEFAULT_TIMEOUT_MS,
+        });
+    });
+}
+export async function press(ctx, args) {
+    // Secrets materialisation on `key` — mirrors `fill`. The realistic case is
+    // a one-shot OTP/passphrase that the agent needs to "press" into a focused
+    // field. Playwright's `press` accepts modifier+key strings ("Shift+A") and
+    // single chars; the `<NAME>` shape doesn't collide with either, so the
+    // alias detection in the registry is unambiguous.
+    const mat = materialiseValue(ctx, args.key);
+    if (!mat.ok)
+        return failedPress(args, mat.error);
+    const descriptorValue = mat.alias ? `<${mat.alias}>` : args.key;
+    const descriptor = {
+        type: "press",
+        value: descriptorValue,
+        ...(args.target ? refOrSelector(args.target) : {}),
+    };
+    return runInActionWindow(ctx, descriptor, args, async () => {
+        if (args.target) {
+            const loc = locatorFor(ctx.page, ctx.refs, args.target);
+            const pre = await preProbe(loc);
+            await loc.press(mat.value, { timeout: args.deadlineMs ?? DEFAULT_TIMEOUT_MS });
+            const probed = await probe(loc, args.target, undefined, pre);
+            return maskProbe(probed, ctx);
+        }
+        else {
+            await ctx.page.keyboard.press(mat.value);
+        }
+    });
+}
+export async function hover(ctx, args) {
+    const descriptor = { type: "hover", ...targetDescriptor(args.target) };
+    const { resolved, warning } = await resolveTargetChecked(ctx.page, ctx.refs, args.target);
+    const opts = warning
+        ? { ...args, extraWarnings: [...(args.extraWarnings ?? []), warning] }
+        : args;
+    return runInActionWindow(ctx, descriptor, opts, async () => {
+        if (resolved.kind === "coords") {
+            const hitBefore = await captureHit(ctx.page, resolved.x, resolved.y);
+            await ctx.page.mouse.move(resolved.x, resolved.y);
+            const hitAfter = await captureHit(ctx.page, resolved.x, resolved.y);
+            return { stillAttached: true, hit: { before: hitBefore, after: hitAfter } };
+        }
+        const pre = await preProbe(resolved.loc);
+        await resolved.loc.hover({ timeout: args.deadlineMs ?? DEFAULT_TIMEOUT_MS });
+        return probe(resolved.loc, args.target, undefined, pre);
+    });
+}
+export async function select(ctx, args) {
+    const descriptor = {
+        type: "select",
+        value: args.values.join(", "),
+        ...refOrSelector(args.target),
+    };
+    return runInActionWindow(ctx, descriptor, args, async () => {
+        const loc = locatorFor(ctx.page, ctx.refs, args.target);
+        const pre = await preProbe(loc);
+        await loc.selectOption(args.values, { timeout: args.deadlineMs ?? DEFAULT_TIMEOUT_MS });
+        return probe(loc, args.target, undefined, pre);
+    });
+}
+export async function waitFor(ctx, args) {
+    const timeout = args.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (args.text !== undefined) {
+        const descriptor = { type: "waitFor", value: `text:${args.text}` };
+        const wanted = args.text;
+        return runInActionWindow(ctx, descriptor, args, async () => {
+            // true substring match (case-insensitive, whitespace-trimmed)
+            // — `getByText(string)` is substring by default. The earlier
+            // `locator('text="…"')` form lowered to Playwright's quoted/exact-ish
+            // engine, contradicting the documented "substring" contract (a short
+            // token inside a longer string timed out). Visible-only; throws on
+            // timeout (caught by the action window → ok:false).
+            await ctx.page.getByText(wanted).first().waitFor({ state: "visible", timeout });
+            return { stillAttached: true };
+        });
+    }
+    if (!args.target) {
+        throw new Error("wait_for: pass a `target` (ref/selector/named/coords) or `text`");
+    }
+    const target = args.target;
+    const descriptor = { type: "waitFor", ...refOrSelector(target) };
+    return runInActionWindow(ctx, descriptor, args, async () => {
+        const loc = locatorFor(ctx.page, ctx.refs, target);
+        await loc.waitFor({ state: "visible", timeout });
+        return probe(loc, target);
+    });
+}
+/**
+ * Resolve which of the four scroll behaviours a `ScrollArgs` selects, or throw
+ * a clear error for a no-op call. Pure — exported for unit tests.
+ *
+ *   - target + (no to/by) | intoView:true  → scroll the element into view
+ *   - target + (to|by) + intoView:false    → scroll *within* the container
+ *   - coords target                        → wheel scroll at the point
+ *   - no target + (to|by)                  → window scroll
+ */
+export function scrollMode(args) {
+    if (args.target?.coords)
+        return { kind: "wheel-at" };
+    if (args.target) {
+        const wantsInto = args.intoView ?? (args.to === undefined && args.by === undefined);
+        return wantsInto ? { kind: "into-view" } : { kind: "container" };
+    }
+    if (args.to === undefined && args.by === undefined) {
+        throw new Error("scroll: no-op — pass `to` (top|bottom|left|right) or `by` {x,y}, or a `target` to scroll into view");
+    }
+    return { kind: "window" };
+}
+export async function scroll(ctx, args) {
+    const descriptor = {
+        type: "scroll",
+        value: args.to ?? (args.by ? `by ${args.by.x ?? 0},${args.by.y ?? 0}` : "into-view"),
+        ...(args.target ? refOrSelector(args.target) : {}),
+    };
+    return runInActionWindow(ctx, descriptor, args, async () => {
+        const mode = scrollMode(args);
+        if (mode.kind === "wheel-at") {
+            const c = args.target.coords;
+            await ctx.page.mouse.move(c.x, c.y);
+            await ctx.page.mouse.wheel(args.by?.x ?? 0, args.by?.y ?? 0);
+            return { stillAttached: true, scroll: await windowScrollGeometry(ctx.page) };
+        }
+        if (mode.kind === "into-view") {
+            const loc = locatorFor(ctx.page, ctx.refs, args.target);
+            await loc.scrollIntoViewIfNeeded({ timeout: args.deadlineMs ?? DEFAULT_TIMEOUT_MS });
+            const p = await probe(loc, args.target);
+            p.scroll = await windowScrollGeometry(ctx.page);
+            return p;
+        }
+        if (mode.kind === "container") {
+            const loc = locatorFor(ctx.page, ctx.refs, args.target);
+            await loc.evaluate((el, a) => {
+                if (a.to === "top")
+                    el.scrollTop = 0;
+                else if (a.to === "bottom")
+                    el.scrollTop = el.scrollHeight;
+                else if (a.to === "left")
+                    el.scrollLeft = 0;
+                else if (a.to === "right")
+                    el.scrollLeft = el.scrollWidth;
+                if (a.by)
+                    el.scrollBy(a.by.x ?? 0, a.by.y ?? 0);
+            }, { to: args.to, by: args.by });
+            const p = await probe(loc, args.target);
+            p.scroll = await elementScrollGeometry(loc);
+            return p;
+        }
+        // window
+        await ctx.page.evaluate((a) => {
+            const g = globalThis;
+            const w = g;
+            const doc = w.document?.documentElement;
+            if (a.to === "top")
+                w.scrollTo(w.scrollX, 0);
+            else if (a.to === "bottom")
+                w.scrollTo(w.scrollX, doc ? doc.scrollHeight : 1e9);
+            else if (a.to === "left")
+                w.scrollTo(0, w.scrollY);
+            else if (a.to === "right")
+                w.scrollTo(doc ? doc.scrollWidth : 1e9, w.scrollY);
+            if (a.by)
+                w.scrollBy(a.by.x ?? 0, a.by.y ?? 0);
+        }, { to: args.to, by: args.by });
+        return { stillAttached: true, scroll: await windowScrollGeometry(ctx.page) };
+    });
+}
+/** mid-session viewport resize. `page.setViewportSize` re-lays-out and
+ *  often triggers responsive re-render / lazy-load — wrapped in the action
+ *  window so `structure` / `network` / `snapshotDelta` show what changed.
+ *  Device emulation (isMobile/touch/UA/DPR) is creation-time only; this only
+ *  changes the size. */
+export async function setViewport(ctx, args) {
+    const descriptor = {
+        type: "setViewport",
+        value: `${args.width}x${args.height}`,
+    };
+    return runInActionWindow(ctx, descriptor, args, async () => {
+        await ctx.page.setViewportSize({ width: args.width, height: args.height });
+        return { stillAttached: true };
+    });
+}
+/**
+ * `choose_option` primitive. Generic combobox/listbox/menu selection
+ * for custom controls that aren't native `<select>` (so the existing `select`
+ * tool can't drive them). The pattern: open the target control, wait for a
+ * visible listbox/menu/portal, find the option element by exact text, click
+ * it, return the probe on the *trigger* so `ownerControl.displayText`
+ * shows the committed selection.
+ *
+ * Falls back across `role=option` → `role=menuitem` → `getByText` so works
+ * on any reasonable combobox shape. Does **not** simulate keyboard navigation
+ * (type-and-press-Enter) — that's a different primitive and prone to picking
+ * the wrong option in dense lists.
+ */
+export async function chooseOption(ctx, args) {
+    const descriptor = {
+        type: "chooseOption",
+        value: args.option,
+        ...targetDescriptor(args.target),
+    };
+    return runInActionWindow(ctx, descriptor, args, async () => {
+        if (args.target.coords) {
+            throw new Error("choose_option requires a ref/selector/named target (the combobox/menu trigger), not coords");
+        }
+        const trigger = locatorFor(ctx.page, ctx.refs, args.target);
+        const pre = await preProbe(trigger);
+        // Open the control if not already expanded. `aria-expanded` is the strongest
+        // signal; absence isn't proof it's closed, so we still click if false-or-missing.
+        const isExpanded = await trigger
+            .evaluate((el) => !!el.getAttribute && el.getAttribute("aria-expanded") === "true")
+            .catch(() => false);
+        if (!isExpanded) {
+            await trigger.click({ timeout: args.deadlineMs ?? DEFAULT_TIMEOUT_MS });
+        }
+        const optionLoc = await resolveOption(ctx.page, args.option, args.exact ?? true);
+        await optionLoc.click({ timeout: args.deadlineMs ?? DEFAULT_TIMEOUT_MS });
+        return probe(trigger, args.target, undefined, pre);
+    });
+}
+/** Resolve the option element by exact text across the three common shapes a
+ *  custom combobox/listbox emits. Tries each in order, returning the first
+ *  attempt that has a non-zero count. Last attempt is returned even if empty
+ *  so the subsequent `click()` produces a clean timeout error instead of
+ *  silently doing nothing. */
+async function resolveOption(page, text, exact) {
+    const attempts = [
+        () => page.getByRole("option", { name: text, exact }).first(),
+        () => page.getByRole("menuitem", { name: text, exact }).first(),
+        () => page.getByText(text, { exact }).first(),
+    ];
+    for (const make of attempts) {
+        const loc = make();
+        const count = await loc.count().catch(() => 0);
+        if (count > 0)
+            return loc;
+    }
+    return attempts[0]();
+}
+export async function goBack(ctx, args = {}) {
+    return runInActionWindow(ctx, { type: "goBack" }, args, async () => {
+        await ctx.page.goBack({
+            waitUntil: "domcontentloaded",
+            timeout: args.deadlineMs ?? DEFAULT_TIMEOUT_MS,
+        });
+    });
+}
+export async function goForward(ctx, args = {}) {
+    return runInActionWindow(ctx, { type: "goForward" }, args, async () => {
+        await ctx.page.goForward({
+            waitUntil: "domcontentloaded",
+            timeout: args.deadlineMs ?? DEFAULT_TIMEOUT_MS,
+        });
+    });
+}
+// ---------- helpers ----------
+/** Dispatch-side secret materialisation. Wraps `SecretRegistry.materialize`
+ *  with a no-registry fallback so non-secrets callers don't need to feature-
+ *  detect. Exported for composing primitives (e.g. multi-field fill). */
+export function materialiseValue(ctx, raw) {
+    if (!ctx.secrets)
+        return { ok: true, value: raw };
+    const m = ctx.secrets.materialize(raw, ctx.page.url());
+    if (!m.ok)
+        return { ok: false, error: m.error };
+    return m.alias ? { ok: true, value: m.value, alias: m.alias } : { ok: true, value: m.value };
+}
+/** Build a clean ActionResult-shaped failure for a secrets-materialisation
+ *  rejection (no Playwright op ever runs). Mirrors the action-window error
+ *  envelope so the agent sees a consistent shape. */
+function failedFill(args, message) {
+    return secretsFailure({ type: "fill", value: args.value, ...refOrSelector(args.target) }, message);
+}
+function failedPress(args, message) {
+    return secretsFailure({ type: "press", value: args.key, ...(args.target ? refOrSelector(args.target) : {}) }, message);
+}
+function secretsFailure(action, message) {
+    return {
+        ok: false,
+        action,
+        navigation: { changed: false, from: "", to: "", kind: null },
+        structure: { appeared: [], removed: [], newTabs: [] },
+        console: { errors: [], warnings: 0 },
+        pageErrors: [],
+        network: { summary: { total: 0, byType: {}, failed: 0 } },
+        tokensEstimate: 0,
+        warnings: [],
+        error: message,
+    };
+}
+/** Post-probe defence-in-depth: mask any registered real-value that leaked
+ *  into the probe's `value` / `displayText` / `ownerControl` / `container`
+ *  string fields. The fill / press path is the canonical source of these
+ *  leaks — the field's DOM value reflects what we just typed.
+ *  Exported for composing primitives (e.g. multi-field fill). */
+export function maskProbe(probed, ctx) {
+    if (!probed || !ctx.secrets)
+        return probed;
+    const out = { ...probed };
+    if (typeof out.value === "string")
+        out.value = ctx.secrets.applyMaskInText(out.value);
+    if (typeof out.displayText === "string")
+        out.displayText = ctx.secrets.applyMaskInText(out.displayText);
+    if (out.ownerControl) {
+        const oc = { ...out.ownerControl };
+        if (oc.displayTextBefore)
+            oc.displayTextBefore = ctx.secrets.applyMaskInText(oc.displayTextBefore);
+        if (oc.displayTextAfter)
+            oc.displayTextAfter = ctx.secrets.applyMaskInText(oc.displayTextAfter);
+        if (oc.label)
+            oc.label = ctx.secrets.applyMaskInText(oc.label);
+        out.ownerControl = oc;
+    }
+    if (out.container) {
+        const c = { ...out.container };
+        if (c.rowKey)
+            c.rowKey = ctx.secrets.applyMaskInText(c.rowKey);
+        if (c.rowText)
+            c.rowText = ctx.secrets.applyMaskInText(c.rowText);
+        out.container = c;
+    }
+    return out;
+}
+function refOrSelector(t) {
+    if (t.ref)
+        return { ref: t.ref };
+    if (t.selector)
+        return { selector: t.selector };
+    return {};
+}
+function targetDescriptor(t) {
+    // DispatchedAction's `ref`/`selector` fields are advisory metadata for the
+    // recording layer; coords targets simply omit them.
+    return refOrSelector(t);
+}
+export { preProbe, probe, captureHit, captureFocusedRef } from "./actions-probe.js";

package/dist/page/archive-assets.d.ts

@@ -0,0 +1,39 @@
+/** One linked resource the discovery script found. `kind` drives subdir
+ *  placement in directory mode + content-type inference in single-file mode. */
+export interface DiscoveredResource {
+    url: string;
+    kind: "image" | "font" | "script" | "stylesheet" | "media" | "other";
+    /** Original attribute text the discovery script saw — used to rewrite the
+     *  HTML to point at the asset sidecar in directory mode. */
+    rawRef: string;
+}
+/** Fetch one URL from inside the page, returning base64 + a content-type
+ *  guess. Used in single-file mode (data: URIs) and as the byte source for
+ *  directory mode. Failures are caught — the caller drops + counts. */
+export declare function buildFetchScript(url: string): string;
+export interface FetchedResource {
+    ok: boolean;
+    base64?: string;
+    contentType?: string;
+    bytes?: number;
+    status?: number;
+    error?: string;
+}
+/** Slugify a URL into a filesystem-safe asset filename. The hash prefix
+ *  disambiguates same-name resources from different origins. */
+export declare function assetFilename(url: string, kind: DiscoveredResource["kind"], contentType: string): string;
+export declare function subdirForKind(kind: DiscoveredResource["kind"]): string;
+/** Rewrite raw HTML — replace every recorded `rawRef` with the relative
+ *  asset path the file has been written to. We do a literal substring
+ *  replacement (anchored to quote boundaries where possible) rather than
+ *  parsing the HTML: parsing introduces fidelity risk, and the discovery
+ *  script captured exactly the raw attribute text we'll see in `outerHTML`.
+ *
+ *  The order matters — replace longer `rawRef`s before shorter ones so a
+ *  prefix-substring of a different URL isn't accidentally matched. */
+export declare function rewriteHtml(html: string, replacements: Array<{
+    rawRef: string;
+    replacement: string;
+}>): string;
+export declare function mimeFromKind(kind: DiscoveredResource["kind"]): string;
+export declare function directorySize(dir: string): number;

package/dist/page/archive-assets.js

@@ -0,0 +1,187 @@
+// page_archive asset helpers — the per-URL page-side fetch script, the
+// filename/mime/ext/subdir naming, HTML rewriting, and directory-size walk.
+// Split out of archive.ts so the orchestrator stays under the size budget;
+// behavior-identical.
+import { extname, sep } from "node:path";
+import { statSync, readdirSync } from "node:fs";
+/** Fetch one URL from inside the page, returning base64 + a content-type
+ *  guess. Used in single-file mode (data: URIs) and as the byte source for
+ *  directory mode. Failures are caught — the caller drops + counts. */
+export function buildFetchScript(url) {
+    // page.evaluate(string) treats the string as an expression — `await` only
+    // works inside an async IIFE. Encode the URL once at compose time.
+    const literal = JSON.stringify(url);
+    return `(async () => {
+  try {
+    var r = await fetch(${literal}, { credentials: 'include', cache: 'no-store' });
+    if (!r.ok) return { ok: false, status: r.status, contentType: r.headers.get('content-type') || '' };
+    var ct = r.headers.get('content-type') || '';
+    var buf = await r.arrayBuffer();
+    var bytes = new Uint8Array(buf);
+    // chunked base64 — TextDecoder + btoa for portability inside the page
+    var CHUNK = 0x8000, parts = [];
+    for (var i = 0; i < bytes.length; i += CHUNK) {
+      parts.push(String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK)));
+    }
+    return { ok: true, base64: btoa(parts.join('')), contentType: ct, bytes: bytes.length };
+  } catch (e) {
+    return { ok: false, error: (e && e.message) ? String(e.message) : String(e) };
+  }
+})()`;
+}
+/** Slugify a URL into a filesystem-safe asset filename. The hash prefix
+ *  disambiguates same-name resources from different origins. */
+export function assetFilename(url, kind, contentType) {
+    let stem;
+    let urlExt = "";
+    try {
+        const u = new URL(url);
+        const last = u.pathname.split("/").filter(Boolean).pop() ?? "asset";
+        urlExt = extname(last);
+        stem = last.replace(/[^A-Za-z0-9._-]/g, "_") || "asset";
+        if (urlExt)
+            stem = stem.slice(0, -urlExt.length);
+    }
+    catch {
+        stem = "asset";
+    }
+    // 8-char hash from the URL to disambiguate collisions across origins.
+    const hash = simpleHash(url);
+    const ext = urlExt || guessExtFromContentType(contentType) || guessExtFromKind(kind);
+    return `${stem}-${hash}${ext}`;
+}
+function simpleHash(s) {
+    // tiny non-cryptographic hash — collision risk is negligible at archive
+    // resource counts (low hundreds) and we want zero deps.
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h = (h ^ s.charCodeAt(i)) >>> 0;
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h.toString(16).padStart(8, "0");
+}
+function guessExtFromContentType(ct) {
+    const c = ct.split(";")[0].trim().toLowerCase();
+    const map = {
+        "text/html": ".html",
+        "text/css": ".css",
+        "text/javascript": ".js",
+        "application/javascript": ".js",
+        "application/json": ".json",
+        "image/png": ".png",
+        "image/jpeg": ".jpg",
+        "image/gif": ".gif",
+        "image/svg+xml": ".svg",
+        "image/webp": ".webp",
+        "image/x-icon": ".ico",
+        "font/woff": ".woff",
+        "font/woff2": ".woff2",
+        "font/ttf": ".ttf",
+        "font/otf": ".otf",
+        "application/font-woff": ".woff",
+        "application/font-woff2": ".woff2",
+        "video/mp4": ".mp4",
+        "audio/mpeg": ".mp3",
+    };
+    return map[c] ?? "";
+}
+function guessExtFromKind(kind) {
+    switch (kind) {
+        case "image":
+            return ".bin";
+        case "font":
+            return ".font";
+        case "script":
+            return ".js";
+        case "stylesheet":
+            return ".css";
+        case "media":
+            return ".media";
+        default:
+            return ".bin";
+    }
+}
+export function subdirForKind(kind) {
+    switch (kind) {
+        case "image":
+            return "images";
+        case "font":
+            return "fonts";
+        case "script":
+            return "scripts";
+        case "stylesheet":
+            return "styles";
+        case "media":
+            return "media";
+        default:
+            return "other";
+    }
+}
+/** Rewrite raw HTML — replace every recorded `rawRef` with the relative
+ *  asset path the file has been written to. We do a literal substring
+ *  replacement (anchored to quote boundaries where possible) rather than
+ *  parsing the HTML: parsing introduces fidelity risk, and the discovery
+ *  script captured exactly the raw attribute text we'll see in `outerHTML`.
+ *
+ *  The order matters — replace longer `rawRef`s before shorter ones so a
+ *  prefix-substring of a different URL isn't accidentally matched. */
+export function rewriteHtml(html, replacements) {
+    const sorted = [...replacements].sort((a, b) => b.rawRef.length - a.rawRef.length);
+    let out = html;
+    for (const { rawRef, replacement } of sorted) {
+        if (!rawRef)
+            continue;
+        // Wrap in quote-anchored patterns first so `path="/foo"` doesn't catch
+        // a stray `/foo` substring in inline text.
+        const quoted = [`"${rawRef}"`, `'${rawRef}'`];
+        for (const q of quoted) {
+            const replWith = q[0] + replacement + q[0];
+            out = out.split(q).join(replWith);
+        }
+        // Fall through — some `srcset` / `style` references don't wear quotes.
+        // Bounded literal replace to avoid the regex-cost trap.
+        if (rawRef.length >= 4)
+            out = out.split(rawRef).join(replacement);
+    }
+    return out;
+}
+export function mimeFromKind(kind) {
+    // Fallback MIME when the response carried no Content-Type. Use a concrete
+    // type the browser can render rather than a wildcard (which is not valid
+    // in a `data:` URI). These are best-guesses, not authoritative — the
+    // upstream response should be carrying Content-Type in any sane setup.
+    switch (kind) {
+        case "image":
+            return "image/png";
+        case "font":
+            return "font/woff2";
+        case "script":
+            return "application/javascript";
+        case "stylesheet":
+            return "text/css";
+        case "media":
+            return "video/mp4";
+        default:
+            return "application/octet-stream";
+    }
+}
+export function directorySize(dir) {
+    let total = 0;
+    const walk = (d) => {
+        for (const entry of readdirSync(d, { withFileTypes: true })) {
+            const p = d + sep + entry.name;
+            if (entry.isDirectory())
+                walk(p);
+            else if (entry.isFile()) {
+                try {
+                    total += statSync(p).size;
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        }
+    };
+    walk(dir);
+    return total;
+}