browxai 0.7.0

package/dist/page/archive.d.ts

@@ -0,0 +1,47 @@
+export type { DiscoveredResource } from "./archive-assets.js";
+/** Archive format. `directory` writes index.html + assets/ sidecar; `single-file`
+ *  inlines every linked resource as a `data:` URI in one HTML file. */
+export type ArchiveFormat = "directory" | "single-file";
+export interface ArchiveArgs {
+    /** Workspace-rooted output path. For `directory` it's a directory; for
+     *  `single-file` it's a `.html` file. When omitted, defaults to
+     *  `archives/<sessionId>-<ISO>` (directory) or
+     *  `archives/<sessionId>-<ISO>.html` (single-file). */
+    path?: string;
+    /** Archive format. Default `"directory"`. */
+    format?: ArchiveFormat;
+    /** Total archive size cap (MB). Default 200. Hard cap — fetches that
+     *  would push past the budget are dropped and counted. */
+    maxSizeMb?: number;
+}
+export interface ArchiveResult {
+    ok: true;
+    format: ArchiveFormat;
+    /** Absolute, workspace-rooted output path (directory or file). */
+    path: string;
+    /** Total archive size on disk, in bytes. */
+    sizeBytes: number;
+    /** Resources successfully fetched + included. */
+    resourceCount: number;
+    /** Resources skipped — unsupported scheme, fetch failure, oversize, or
+     *  size budget exhausted. The total `discovered = resourceCount + droppedCount`. */
+    droppedCount: number;
+    /** Non-fatal advisories — secrets-masking caveat (always), CSP `connect-src`
+     *  blocks (when seen), oversized single-file output, per-resource oversize
+     *  hits. The set is small + deterministic; never noise. */
+    warnings: string[];
+}
+/** Default output path when the caller omits one. Workspace-rooted under
+ *  `archives/<sessionId>-<ISO>[.html]` — matches the `pdf_save` /
+ *  `start_har` / `perf_stop` subdir-per-artefact convention. */
+export declare function defaultArchivePath(sessionId: string, format: ArchiveFormat): string;
+/** Page handle adapter — `page_archive` only needs `evaluate`. Exposing a
+ *  thin interface keeps the unit test mock trivial. */
+export interface ArchivePage {
+    evaluate(expression: string): Promise<unknown>;
+}
+/**
+ * Write the page archive. Workspace-rooted by construction; the caller
+ * (server.ts) has already gated on the `file-io` capability.
+ */
+export declare function pageArchive(page: ArchivePage, workspaceRoot: string, sessionId: string, args?: ArchiveArgs): Promise<ArchiveResult>;

package/dist/page/archive.js

@@ -0,0 +1,349 @@
+// `page_archive` — save the current page as a self-contained archive.
+//
+// Two formats:
+//
+//   - `directory` (default) — write `<path>/index.html` plus a sidecar
+//     `<path>/assets/` containing every linked resource the DOM-walk
+//     discovered (images, fonts, scripts, stylesheets, CSS background
+//     images surfaced via `getComputedStyle`). Internal references in the
+//     serialised HTML are rewritten to relative `assets/...` paths. Browser-
+//     openable straight off disk; the archive is a real directory the
+//     adopter can grep / diff / repackage.
+//
+//   - `single-file` — one self-contained HTML file at `path` with every
+//     resource inlined as a `data:` URI. The MHTML-equivalent without the
+//     MIME-multipart format (which Chromium has dropped good support for in
+//     the modern surface). One file to copy around; cap-bounded by `maxSizeMb`.
+//
+// Path safety mirrors `pdf_save` / `dump_storage_state`: every output path is
+// resolved via `resolveWorkspacePath`, so a path that escapes
+// `$BROWX_WORKSPACE` is rejected before any byte is written.
+//
+// Resource discovery walks the live DOM inside `page.evaluate` and pulls
+// every node carrying a fetchable URL (`<img src>`, `<link href>`, `<script
+// src>`, `<source>`, `<video poster>`, `<iframe src>` modulo cross-origin
+// access, plus CSS `background-image: url(...)` from computed styles). Each
+// URL is then fetched **from inside the page** via `await fetch(u)`, which
+// inherits the page's origin (and credentials) — the only way to reliably
+// pull resources that depend on session cookies or the page's CSP
+// `connect-src` posture. Cross-origin fetches that CSP refuses are caught
+// and surfaced in `droppedCount` + `warnings[]` rather than aborting the
+// archive.
+//
+// Document HTML is captured with `document.documentElement.outerHTML` after
+// the agent's own pre-archive wait. The tool does NOT inject its own wait;
+// the agent is expected to navigate + settle the page BEFORE calling
+// `page_archive`. Same posture as `pdf_save`.
+//
+// Secrets-masking interplay (DELIBERATE GAP):
+//   The output is a *faithful* capture of the rendered page. Running the
+//   per-session egress masking layer over the HTML / linked bytes would
+//   corrupt the archive — masking is literal-substring substitution, would
+//   break inline JSON state blobs, CSS, image bytes, and would produce a
+//   file that no longer opens correctly. So `page_archive` writes UNMASKED
+//   page state on purpose. The caller takes the same posture as
+//   `dump_storage_state` toward the result: it may carry credentials, treat
+//   the archive as sensitive material. Documented in tool-reference + flagged
+//   on every result through `warnings[]`.
+import { resolve as resolvePath, dirname, join } from "node:path";
+import { mkdirSync, writeFileSync, statSync } from "node:fs";
+import { resolveWorkspacePath } from "../session/storage.js";
+import { buildFetchScript, assetFilename, subdirForKind, rewriteHtml, mimeFromKind, directorySize, } from "./archive-assets.js";
+/** Default size cap. Large enough for a meaty SPA + media, small enough that
+ *  a runaway page (infinite-scroll, video stream) doesn't fill the
+ *  workspace. Override with `maxSizeMb`. */
+const DEFAULT_MAX_SIZE_MB = 200;
+/** Hard ceiling for single-file mode beyond the user's cap. Browsers
+ *  routinely struggle to load HTML > ~150 MB into a single document — the
+ *  in-memory `data:` URI cost compounds. We surface a warning when the
+ *  single-file output exceeds this, but never refuse: the cap is the cap. */
+const SINGLE_FILE_SOFT_WARN_MB = 150;
+/** Resource hard ceiling per fetch — refuse to inline a single 500 MB video
+ *  even if `maxSizeMb` would permit it. The point of an archive is fidelity,
+ *  not turning the agent into a CDN. Surfaces a warning. */
+const PER_RESOURCE_HARD_MB = 50;
+/** Default output path when the caller omits one. Workspace-rooted under
+ *  `archives/<sessionId>-<ISO>[.html]` — matches the `pdf_save` /
+ *  `start_har` / `perf_stop` subdir-per-artefact convention. */
+export function defaultArchivePath(sessionId, format) {
+    // Match the sanitisation posture of `defaultPdfPath` — the registry
+    // already constrains ids, this is belt-and-braces.
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, "_") || "default";
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const stem = `archives/${safe}-${ts}`;
+    return format === "single-file" ? `${stem}.html` : stem;
+}
+/** One linked resource the discovery script found. `kind` drives subdir
+ *  placement in directory mode + content-type inference in single-file mode.
+ *  Re-exported from `./archive-assets.js` (the type's home) at the top. */
+/** Page-side discovery script — runs inside the page and returns the
+ *  document HTML plus a list of every linked resource URL we can reach.
+ *  Same pattern as `dom-walk.ts`: ECMAScript-only, stringified IIFE. */
+const DISCOVERY_SCRIPT = `(() => {
+  function abs(u) {
+    try { return new URL(u, document.baseURI).href; } catch (_) { return null; }
+  }
+  function bgUrls(el) {
+    var out = [];
+    try {
+      var cs = getComputedStyle(el);
+      var bg = cs && cs.backgroundImage;
+      if (bg && bg !== 'none') {
+        var re = /url\\((['"]?)([^'")]+)\\1\\)/g, m;
+        while ((m = re.exec(bg)) !== null) out.push(m[2]);
+      }
+    } catch (_) {}
+    return out;
+  }
+  var resources = [];
+  var seen = Object.create(null);
+  function push(raw, kind) {
+    if (!raw) return;
+    var a = abs(raw);
+    if (!a) return;
+    // skip non-fetchable schemes — data:/blob:/about:/javascript: etc.
+    if (!/^https?:|^ftp:|^file:/i.test(a)) return;
+    var key = a + '|' + kind;
+    if (seen[key]) return;
+    seen[key] = 1;
+    resources.push({ url: a, kind: kind, rawRef: raw });
+  }
+  // <img src>, <img srcset> (first candidate only — keep the discovery cheap)
+  var imgs = document.querySelectorAll('img[src], img[srcset], source[src], source[srcset]');
+  for (var i = 0; i < imgs.length; i++) {
+    var el = imgs[i];
+    var s = el.getAttribute('src');
+    if (s) push(s, 'image');
+    var ss = el.getAttribute('srcset');
+    if (ss) {
+      var first = ss.split(',')[0].trim().split(/\\s+/)[0];
+      if (first) push(first, 'image');
+    }
+  }
+  // <link rel="stylesheet|icon|preload|prefetch">
+  var links = document.querySelectorAll('link[href]');
+  for (var i = 0; i < links.length; i++) {
+    var el = links[i];
+    var rel = (el.getAttribute('rel') || '').toLowerCase();
+    var href = el.getAttribute('href');
+    if (!href) continue;
+    var kind = 'other';
+    if (rel.indexOf('stylesheet') !== -1) kind = 'stylesheet';
+    else if (rel.indexOf('icon') !== -1) kind = 'image';
+    else if (rel.indexOf('preload') !== -1 || rel.indexOf('prefetch') !== -1) {
+      var as = (el.getAttribute('as') || '').toLowerCase();
+      if (as === 'font') kind = 'font';
+      else if (as === 'script') kind = 'script';
+      else if (as === 'image') kind = 'image';
+      else if (as === 'style') kind = 'stylesheet';
+    }
+    push(href, kind);
+  }
+  // <script src>
+  var scripts = document.querySelectorAll('script[src]');
+  for (var i = 0; i < scripts.length; i++) push(scripts[i].getAttribute('src'), 'script');
+  // <video|audio src|poster>, <track src>
+  var media = document.querySelectorAll('video[src], audio[src], video[poster], track[src]');
+  for (var i = 0; i < media.length; i++) {
+    var el = media[i];
+    var s = el.getAttribute('src'); if (s) push(s, 'media');
+    var p = el.getAttribute('poster'); if (p) push(p, 'image');
+  }
+  // <iframe src> — captured for fidelity even though cross-origin iframes
+  // won't be reachable from a fetch in this document. The agent gets a
+  // best-effort archive; cross-origin iframes are dropped at fetch time
+  // and counted in droppedCount.
+  var iframes = document.querySelectorAll('iframe[src]');
+  for (var i = 0; i < iframes.length; i++) push(iframes[i].getAttribute('src'), 'other');
+  // computed background-image — walk every visible element. Bounded — most
+  // pages have <100 background-images; a runaway page is bounded by the
+  // overall maxSizeMb cap downstream.
+  var all = document.querySelectorAll('*');
+  for (var i = 0; i < all.length && i < 5000; i++) {
+    var us = bgUrls(all[i]);
+    for (var j = 0; j < us.length; j++) push(us[j], 'image');
+  }
+  return {
+    html: document.documentElement ? document.documentElement.outerHTML : '',
+    baseUri: document.baseURI || '',
+    resources: resources,
+  };
+})()`;
+/**
+ * Write the page archive. Workspace-rooted by construction; the caller
+ * (server.ts) has already gated on the `file-io` capability.
+ */
+export async function pageArchive(page, 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(`page_archive: maxSizeMb must be in (0, 10000] — got ${maxSizeMb}.`);
+    }
+    const maxBytes = Math.floor(maxSizeMb * 1024 * 1024);
+    const relPath = args.path ?? defaultArchivePath(sessionId, format);
+    const resolved = resolveWorkspacePath(workspaceRoot, relPath, "page_archive");
+    // 1. Run discovery inside the page — one round-trip, returns
+    //    documentElement.outerHTML + the URL set.
+    const discovered = (await page.evaluate(DISCOVERY_SCRIPT));
+    const warnings = [
+        // ALWAYS present — the secrets-masking caveat is part of the result
+        // envelope, not buried in docs. An adopter automating archive collection
+        // sees it on every call.
+        "page_archive output is UNMASKED — secrets-masking would corrupt the archive (literal-substring substitution breaks inline JSON / CSS / binary bytes). Treat the archive as sensitive material, same posture as dump_storage_state.",
+    ];
+    // 2. Fetch each resource (bounded concurrency + size budgets), then 3. emit.
+    const phase = await fetchArchiveResources(page, discovered.resources, maxBytes);
+    appendArchiveWarnings(phase, maxSizeMb, warnings);
+    const emit = format === "directory"
+        ? emitArchiveDirectory(resolved, discovered.html, phase.fetched, phase.runningBytes)
+        : emitArchiveSingleFile(resolved, discovered.html, phase.fetched, warnings);
+    return {
+        ok: true,
+        format,
+        path: resolvePath(resolved),
+        sizeBytes: emit.sizeBytes,
+        resourceCount: emit.resourceCount,
+        droppedCount: emit.droppedCount,
+        warnings,
+    };
+}
+const ARCHIVE_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 classifyArchiveFetched(f, maxBytes, phase) {
+    if (!f.r.ok) {
+        const err = (f.r.error ?? "").toLowerCase();
+        if (ARCHIVE_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. */
+async function fetchArchiveResources(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(classifyArchiveFetched(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 appendArchiveWarnings(phase, maxSizeMb, warnings) {
+    if (phase.cspBlocked > 0) {
+        warnings.push(`${phase.cspBlocked} resource(s) blocked by the page's Content-Security-Policy ` +
+            "(typically `connect-src` — fetch() inside the page is subject to the same " +
+            "policy as the page itself). These are 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. ` +
+            "Raise the per-resource cap by forking — the cap is hard-coded by design (an archive is fidelity, not a CDN).");
+    }
+    if (phase.budgetExhausted) {
+        warnings.push(`Archive size cap (maxSizeMb=${maxSizeMb}) reached — remaining resources were dropped. ` +
+            "Raise `maxSizeMb` to capture more, but note browsers struggle with single-file archives > " +
+            SINGLE_FILE_SOFT_WARN_MB +
+            " MB.");
+    }
+}
+/** Emit the multi-file directory archive — each asset under `assets/<kind>/`,
+ *  the HTML rewritten to relative paths. Workspace-rooted by construction
+ *  (`resolved` ⊆ $BROWX_WORKSPACE). */
+function emitArchiveDirectory(resolved, html, fetched, runningBytes) {
+    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 rewritten = rewriteHtml(html, replacements);
+    // workspace-rooted: `resolved` ⊆ $BROWX_WORKSPACE (resolveWorkspacePath gated it).
+    writeFileSync(join(resolved, "index.html"), rewritten, "utf8");
+    let sizeBytes;
+    try {
+        sizeBytes = directorySize(resolved);
+    }
+    catch {
+        sizeBytes = Buffer.byteLength(rewritten, "utf8") + runningBytes;
+    }
+    return { resourceCount, droppedCount, sizeBytes };
+}
+/** Emit the single-file archive — assets inlined as data: URIs in the HTML.
+ *  Workspace-rooted by construction (`resolved` ⊆ $BROWX_WORKSPACE). */
+function emitArchiveSingleFile(resolved, html, fetched, warnings) {
+    // workspace-rooted: dirname(resolved) is the parent of a $BROWX_WORKSPACE 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 rewritten = rewriteHtml(html, replacements);
+    // workspace-rooted: `resolved` ⊆ $BROWX_WORKSPACE (resolveWorkspacePath gated it).
+    writeFileSync(resolved, rewritten, "utf8");
+    const sizeBytes = statSync(resolved).size;
+    if (sizeBytes > SINGLE_FILE_SOFT_WARN_MB * 1024 * 1024) {
+        warnings.push(`single-file archive is ${(sizeBytes / 1024 / 1024).toFixed(1)} MB. ` +
+            `Browsers commonly struggle to open inline-data HTML beyond ~${SINGLE_FILE_SOFT_WARN_MB} MB ` +
+            '(the data: URI cost compounds in-memory). Use `format:"directory"` for large pages.');
+    }
+    return { resourceCount, droppedCount, sizeBytes };
+}

package/dist/page/asset-export.d.ts

@@ -0,0 +1,122 @@
+import type { CDPSession, Page } from "playwright-core";
+import type { SessionNetworkRing, NetworkEntry } from "./network.js";
+/** Hard ceiling on the per-call file count cap — even a caller-supplied
+ *  `maxCount` is clamped to this. Bounds a runaway export on a long session. */
+export declare const ASSET_EXPORT_HARD_MAX_COUNT = 50000;
+/** Hard ceiling on the per-call byte cap. */
+export declare const ASSET_EXPORT_HARD_MAX_BYTES: number;
+/** Default per-call file count cap. Caller can override up to the hard max. */
+export declare const ASSET_EXPORT_DEFAULT_MAX_COUNT = 10000;
+/** Default per-call byte cap (500 MiB). */
+export declare const ASSET_EXPORT_DEFAULT_MAX_BYTES: number;
+export interface AssetFilter {
+    /** Substring match against response `Content-Type` (case-insensitive,
+     *  any one match wins). Example: `["image/", "video/"]`. Undefined → any. */
+    mime?: string[];
+    /** RegExp source; matched case-insensitive against the response URL.
+     *  Example: `"\\.(woff2?|ttf|otf)$"`. Invalid regex → throws at the tool
+     *  boundary so the agent sees the structured error. */
+    urlPattern?: string;
+    /** Inclusive lower bound on the response's encoded byte size. */
+    minBytes?: number;
+    /** Inclusive upper bound on the response's encoded byte size. */
+    maxBytes?: number;
+    /** Allow-list of HTTP status codes. Default: 2xx (200..299). */
+    status?: number[];
+}
+export interface ManifestEntry {
+    url: string;
+    mime?: string;
+    status?: number;
+    sizeBytes: number;
+    savedAs: string;
+}
+export interface AssetExportResult {
+    ok: boolean;
+    intoDir: string;
+    totalCount: number;
+    matchedCount: number;
+    persistedCount: number;
+    droppedCount: number;
+    manifest: ManifestEntry[];
+    warnings: string[];
+}
+export interface AssetExportArgs {
+    filter: AssetFilter;
+    /** Workspace-rooted subdir for the exported files. Default
+     *  `assets/<sessionId>-<ISO>/`. Escape rejected. */
+    intoDir?: string;
+    /** Override the per-call file count cap. Clamped to
+     *  `ASSET_EXPORT_HARD_MAX_COUNT`. */
+    maxCount?: number;
+    /** Override the per-call total byte cap. Clamped to
+     *  `ASSET_EXPORT_HARD_MAX_BYTES`. */
+    maxBytes?: number;
+}
+/** Build the regex once at the boundary. Throws `Error` on invalid source so
+ *  the tool layer surfaces a structured failure instead of a runtime crash
+ *  deep inside the loop. */
+export declare function compileUrlPattern(src: string | undefined): RegExp | null;
+/** Filter a single `NetworkEntry` against a normalised filter. Pure — uses
+ *  only the entry's captured metadata; no I/O. Exported so the test suite
+ *  can pin every branch without spinning a NetworkBuffer. */
+interface NormalisedAssetFilter {
+    mime?: string[];
+    urlPattern: RegExp | null;
+    minBytes?: number;
+    maxBytes?: number;
+    status: ReadonlySet<number> | null;
+}
+/** Filter a single `NetworkEntry` against a normalised filter. Pure — uses only
+ *  the entry's captured metadata; no I/O. Exported so the test suite can pin
+ *  every branch without spinning a NetworkBuffer. */
+export declare function matchesFilter(entry: NetworkEntry, filter: NormalisedAssetFilter): boolean;
+/** Sanitise a URL-derived asset filename. Same posture as
+ *  `downloads.sanitiseFilename`:
+ *    - strip path separators (`/`, `\`) and NUL/control bytes — collapses any
+ *      traversal attempt to a flat filename.
+ *    - collapse runs of dots so the literal `..` substring never survives.
+ *    - strip leading dots so we don't write a hidden file.
+ *    - cap length (leaves room for a `-N` collision suffix).
+ *    - empty / all-stripped → fall back to `"asset"`.
+ *  Exported for unit tests. */
+export declare function sanitiseAssetFilename(raw: string): string;
+/** Derive a base filename from a URL: take the last path segment, decode
+ *  percent-encoding, drop a query string. Falls back to `"asset"` when the
+ *  URL has no usable basename (e.g. `https://example.com/`). Exported for
+ *  unit tests. */
+export declare function filenameFromUrl(url: string): string;
+/** Resolve a collision by appending `-N` before the extension. Pure; uses
+ *  the supplied `Set` of already-used names. Exported for unit tests. */
+export declare function resolveCollision(name: string, used: Set<string>): string;
+/** ISO-8601 timestamp safe for use in a directory name (`:` replaced with `-`). */
+export declare function timestampForDir(d?: Date): string;
+/** Resolve the export dir. Default: `assets/<sessionId>-<ISO>/`. Caller-
+ *  supplied `intoDir` is resolved INSIDE `workspaceRoot`; any escape throws
+ *  the same structured error as `upload_file` / `pdf_save`. */
+export declare function resolveAssetExportDir(workspaceRoot: string, sessionId: string, intoDir?: string): string;
+/** Try CDP `Network.getResponseBody` first; on "not available" fall back to
+ *  an in-page `fetch()` against the original URL. Returns the bytes (decoded)
+ *  + the effective content-type, or an `{ error }` envelope when both attempts
+ *  fail. The CORS caveat: cross-origin URLs without permissive CORS headers
+ *  will reject the in-page fetch; that's surfaced as `droppedCount` by the
+ *  caller, not a crash. */
+export declare function fetchBodyBytes(cdp: CDPSession, page: Page, entry: NetworkEntry): Promise<{
+    ok: true;
+    bytes: Buffer;
+    mimeType?: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+/** The live-session handles + workspace anchors `asset_export` threads through,
+ *  bundled so the entry point stays within the parameter budget. */
+export interface AssetExportDeps {
+    cdp: CDPSession;
+    page: Page;
+    buffer: SessionNetworkRing;
+    workspaceRoot: string;
+    sessionId: string;
+}
+export declare function assetExport(deps: AssetExportDeps, args: AssetExportArgs): Promise<AssetExportResult>;
+export {};