browxai 0.7.0

package/dist/page/downloads.js

@@ -0,0 +1,244 @@
+// Per-session download-capture pipeline. The reverse of `upload_file`:
+// intercept Playwright `download` events, persist the artifact to a
+// workspace-rooted slot, and surface it on `ActionResult.downloads[]` plus
+// `download_get` for byte-level retrieval.
+//
+// Design notes:
+//   - **Off by default.** A session's listener is always attached at creation,
+//     but it only persists files when `DownloadsRegistry.captureOn` is true
+//     (toggled by the `downloads_capture` MCP tool). When off the listener
+//     deletes Playwright's temp artifact and records nothing — keeps the
+//     no-trace posture for sessions that never opted in.
+//   - **Workspace-rooted paths only.** Captured files land in
+//     `$BROWX_WORKSPACE/.downloads/<sessionId>/<id>-<sanitised-name>`. The
+//     suggested filename from the page is *sanitised* (no path separators, no
+//     traversal, no NULs, no control bytes, length-capped) before composing the
+//     on-disk name. Same posture as `upload.ts`'s workspace-escape rejection.
+//   - **Per-session.** Each `SessionEntry` owns a registry; entries don't
+//     cross sessions. Ids are session-local and monotonic.
+//   - Gated by the existing `file-io` capability (no new capability), same as
+//     `upload_file`.
+import { mkdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { log } from "../util/logging.js";
+/** Per-session download registry. One instance per SessionEntry. */
+export class DownloadsRegistry {
+    storageDir;
+    /** Toggled by the `downloads_capture` MCP tool. */
+    captureOn = false;
+    /** Active captures, keyed by id. Bounded to MAX_ENTRIES — oldest evicted. */
+    entries = new Map();
+    nextId = 1;
+    /** Captures that have fired and are not yet sliced into an ActionResult. */
+    pendingSince = [];
+    /** Max captures kept in memory + on disk per session before LRU-evicting
+     *  the oldest. Prevents an unbounded download loop from filling the disk. */
+    static MAX_ENTRIES = 100;
+    constructor(
+    /** Per-session storage dir: `$BROWX_WORKSPACE/.downloads/<sessionId>/`. */
+    storageDir) {
+        this.storageDir = storageDir;
+    }
+    /** List all captured downloads for this session (most-recent first). */
+    list() {
+        return [...this.entries.values()].reverse();
+    }
+    /** Look up a capture by id; undefined if not present. */
+    get(id) {
+        return this.entries.get(id);
+    }
+    /** Slice captures that fired after `tsMs` (action-window slice). Returns a
+     *  snapshot of the captures so the action-window can include them on the
+     *  ActionResult without exposing the live registry. */
+    since(tsMs) {
+        return [...this.entries.values()].filter((d) => d.capturedAt >= tsMs);
+    }
+    /** Record a capture. Caller has already persisted the file at `path`. */
+    record(record) {
+        const id = `d${this.nextId++}`;
+        const entry = { id, ...record };
+        this.entries.set(id, entry);
+        this.pendingSince.push(entry);
+        // LRU evict oldest if over the cap.
+        while (this.entries.size > DownloadsRegistry.MAX_ENTRIES) {
+            const oldestKey = this.entries.keys().next().value;
+            if (oldestKey === undefined)
+                break;
+            const victim = this.entries.get(oldestKey);
+            this.entries.delete(oldestKey);
+            if (victim) {
+                // unlink under the workspace-rooted storageDir (BROWX_WORKSPACE).
+                try {
+                    unlinkSync(victim.path);
+                }
+                catch {
+                    /* best-effort cleanup */
+                }
+            }
+        }
+        return entry;
+    }
+}
+/** Sanitise a page-supplied filename for safe on-disk use. Rules (mirrors the
+ *  workspace-escape posture in `upload.ts`):
+ *    - strip path separators (`/`, `\`) and NUL/control bytes — collapses any
+ *      traversal attempt to a flat filename.
+ *    - reject leading dots so we never write to a hidden `.foo` file.
+ *    - cap at 200 chars (leaves room for the `<id>-` prefix on filesystems
+ *      with 255-byte name limits).
+ *    - empty / all-stripped → fall back to `"download"`.
+ *  Exported for unit tests. */
+export function sanitiseFilename(raw) {
+    if (typeof raw !== "string")
+        return "download";
+    // strip NUL + control bytes (0x00-0x1f, 0x7f) and path separators.
+    // eslint-disable-next-line no-control-regex
+    let name = raw.replace(/[\x00-\x1f\x7f/\\]/g, "_");
+    // collapse runs of dots ("../.." → ".") so the literal substring `..`
+    // never survives — eliminates "looks-like-traversal" appearance even though
+    // the lack of separators already makes traversal impossible.
+    name = name.replace(/\.{2,}/g, ".");
+    // collapse repeated underscores from the strip pass.
+    name = name.replace(/_+/g, "_");
+    // strip leading dots so we don't write a hidden file.
+    name = name.replace(/^\.+/, "");
+    // strip leading/trailing whitespace, dots, underscores — these only exist
+    // because of the strip passes above; without them the filename "/" would
+    // remain as "_" which is unhelpful + tests as if it carried information.
+    name = name.replace(/^[._\s]+|[._\s]+$/g, "");
+    // cap length.
+    if (name.length > 200)
+        name = name.slice(0, 200);
+    if (!name)
+        return "download";
+    return name;
+}
+/** Best-effort MIME type from a filename extension. Tiny built-in table; this
+ *  is metadata only (we never reject on it), so an unknown extension just
+ *  yields `undefined`. */
+export function mimeTypeFromName(name) {
+    const m = /\.([a-zA-Z0-9]+)$/.exec(name);
+    if (!m)
+        return undefined;
+    const ext = m[1].toLowerCase();
+    const map = {
+        pdf: "application/pdf",
+        csv: "text/csv",
+        tsv: "text/tab-separated-values",
+        txt: "text/plain",
+        json: "application/json",
+        xml: "application/xml",
+        html: "text/html",
+        htm: "text/html",
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        webp: "image/webp",
+        svg: "image/svg+xml",
+        zip: "application/zip",
+        tar: "application/x-tar",
+        gz: "application/gzip",
+        mp3: "audio/mpeg",
+        mp4: "video/mp4",
+        webm: "video/webm",
+        xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        xls: "application/vnd.ms-excel",
+        docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        doc: "application/msword",
+        pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        ppt: "application/vnd.ms-powerpoint",
+    };
+    return map[ext];
+}
+/** Attach the Playwright `download` listener to a context. The listener fires
+ *  for every download on every page in the context (now or later). When
+ *  capture is OFF the artifact is silently deleted; when ON it's persisted and
+ *  the registry records it. Errors during capture never propagate — they
+ *  surface as warnings on the session's log only. */
+export function attachDownloadCapture(context, registry) {
+    context.on("download", (download) => {
+        void handleDownload(download, registry).catch((err) => {
+            log.warn("downloads: capture failed", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+    });
+}
+async function handleDownload(download, registry) {
+    if (!registry.captureOn) {
+        // Capture disabled for this session: discard the artifact and record
+        // nothing. Playwright still buffers downloads to a temp file when
+        // `acceptDownloads: true`; cancelling drops the temp file.
+        await download.cancel().catch(() => undefined);
+        return;
+    }
+    const raw = download.suggestedFilename() ?? "download";
+    const safe = sanitiseFilename(raw);
+    // Ensure storage dir exists (created lazily; sessions that never opt in
+    // never create it). The dir is workspace-rooted (BROWX_WORKSPACE/.downloads
+    // via the SessionEntry factory in server.ts — never cwd).
+    mkdirSync(registry.storageDir, { recursive: true });
+    // Compose final on-disk path. We can't know the id yet (registry assigns
+    // it on `record`); use a millisecond+random prefix to disambiguate
+    // simultaneous downloads, then we'll record once persisted.
+    const prefix = `${Date.now()}-${Math.floor(Math.random() * 1e6).toString(36)}`;
+    const target = join(registry.storageDir, `${prefix}-${safe}`);
+    // Reject any composed path that doesn't resolve INSIDE storageDir. Defence
+    // in depth — sanitiseFilename already strips separators, but if a future
+    // change loosens it the workspace-escape guard catches it.
+    const resolved = resolve(target);
+    const root = resolve(registry.storageDir);
+    if (resolved !== root && !resolved.startsWith(root + sep)) {
+        await download.cancel().catch(() => undefined);
+        log.warn("downloads: refusing to persist outside storage dir", { resolved, root });
+        return;
+    }
+    try {
+        await download.saveAs(resolved);
+    }
+    catch (err) {
+        log.warn("downloads: saveAs failed", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return;
+    }
+    let sizeBytes = 0;
+    try {
+        sizeBytes = statSync(resolved).size;
+    }
+    catch {
+        /* best-effort */
+    }
+    const rawDifferedFromSafe = raw !== safe;
+    registry.record({
+        suggestedFilename: safe,
+        ...(rawDifferedFromSafe ? { rawSuggestedFilename: raw } : {}),
+        mimeType: mimeTypeFromName(safe),
+        sizeBytes,
+        path: resolved,
+        capturedAt: Date.now(),
+    });
+}
+/** Read a captured download's bytes. Returns base64. Throws if the id is
+ *  unknown or the file vanished. */
+export function readCapturedBytes(reg, id) {
+    const entry = reg.get(id);
+    if (!entry) {
+        throw new Error(`download_get: unknown id "${id}". Call downloads_capture({on:true}) before the action that triggers the download, then read the id from ActionResult.downloads[]`);
+    }
+    let buf;
+    try {
+        buf = readFileSync(entry.path);
+    }
+    catch (err) {
+        throw new Error(`download_get: file vanished for id "${id}" at ${entry.path} (${err instanceof Error ? err.message : String(err)})`);
+    }
+    return {
+        base64: buf.toString("base64"),
+        bytes: buf.length,
+        path: entry.path,
+        mimeType: entry.mimeType,
+        suggestedFilename: entry.suggestedFilename,
+    };
+}

package/dist/page/drop-files.d.ts

@@ -0,0 +1,78 @@
+import type { Page } from "playwright-core";
+import type { RefRegistry } from "./refs.js";
+import { type ActionTarget } from "./locator.js";
+export interface DropFileInputPath {
+    /** Workspace-rooted file path. Mutually exclusive with `contents`. */
+    path: string;
+    /** Filename presented to the page. Defaults to the basename of `path`. */
+    name?: string;
+    /** MIME type. Defaults to "application/octet-stream". */
+    mimeType?: string;
+}
+export interface DropFileInputContents {
+    /** base64 file content. Mutually exclusive with `path`. */
+    contents: string;
+    /** Filename presented to the page. Required in `contents`-mode. */
+    name: string;
+    /** MIME type. Defaults to "application/octet-stream". */
+    mimeType?: string;
+}
+export type DropFileInput = DropFileInputPath | DropFileInputContents;
+export interface DropFilesArgs {
+    target: ActionTarget;
+    files: DropFileInput[];
+}
+export interface DropFilesResult {
+    ok: boolean;
+    /** Resolved target description for debugging. */
+    target: string;
+    /** One entry per file with the resolved mode + bytes that were dropped. */
+    files: Array<{
+        name: string;
+        mode: "path" | "contents";
+        bytes: number;
+        mimeType: string;
+    }>;
+    /** Total bytes dispatched. */
+    totalBytes: number;
+    /** Number of files dropped. */
+    fileCount: number;
+    /** Which DOM events the page-side script actually fired. */
+    eventsFired: string[];
+    /** True when the `drop` event was dispatched (regardless of whether the
+     *  page handler called preventDefault — we report the dispatch, not the
+     *  app-side acceptance, since drop-zone apps vary wildly in how they
+     *  signal "I took it"). */
+    dropDispatched: boolean;
+}
+export interface DropPayload {
+    files: Array<{
+        base64: string;
+        name: string;
+        mimeType: string;
+    }>;
+    /** Viewport-relative coords for the dispatched events. We compute these
+     *  on the Node side (bounding-box centre for ref/selector; literal for
+     *  coords). The page-side script writes them onto every event so apps
+     *  that read `event.clientX`/`clientY` see consistent values. */
+    clientX: number;
+    clientY: number;
+    /** When the target was a coords target we have no Locator handle, so the
+     *  page-side script does `document.elementFromPoint(clientX, clientY)`
+     *  to find the drop target. For ref/selector targets we pass the
+     *  pre-resolved element via the Locator's evaluate-handle. */
+    byCoords: boolean;
+}
+export interface DropEvalResult {
+    eventsFired: string[];
+    dropDispatched: boolean;
+    /** Tag of the element we landed on — surfaced for debugging. */
+    hitTag?: string;
+    /** Any error from the in-page side. */
+    error?: string;
+}
+export declare const dropFilesPageScript: (args: {
+    el: unknown;
+    payload: DropPayload;
+}) => DropEvalResult;
+export declare function dropFiles(page: Page, refs: RefRegistry, workspaceRoot: string, args: DropFilesArgs): Promise<DropFilesResult>;

package/dist/page/drop-files.js

@@ -0,0 +1,310 @@
+/// <reference lib="dom" />
+// `drop_files` — synthesize an HTML5 drag-drop of one or more files onto a
+// page element.
+//
+// Modern uploaders are no longer `<input type=file>` — they're drop zones
+// listening for `dragenter` / `dragover` / `drop` with a populated
+// `DataTransfer.files`. Playwright's `setInputFiles` only drives the
+// `<input>` shape, so today's only path to drive a drop-zone uploader is
+// `eval_js` with hand-rolled DataTransfer plumbing. This tool is the
+// first-class alternative.
+//
+// Two file sources, same posture as `upload_file`:
+//   - `contents`  — base64 inline; no filesystem read at all.
+//   - `path`      — resolved **inside `$BROWX_WORKSPACE` only**; a path
+//                   escaping the workspace is rejected.
+//
+// In-page construction approach: we route bytes to the page through a
+// single `page.evaluate(fn, payload)` call at drop time. The page-side
+// function (defined inline so it closes-over nothing) builds `File`
+// objects from base64 payloads, populates a `DataTransfer`, then
+// dispatches `dragenter` → `dragover` → `drop` on the target element. We
+// deliberately do NOT use `addInitScript` to install a helper: each drop
+// is one-shot, the data shape varies per call, and a boot-time injection
+// would leak page-side identifiers.
+//
+// Why base64 over the Node→page boundary and not `Uint8Array`: Playwright's
+// `evaluate` round-trips a `Uint8Array` arg as a per-byte object array
+// (~10× the wire footprint of base64), and we'd still need to materialise
+// it as a Uint8Array in-page anyway — `atob` once on the page side is
+// cheaper than the structured-clone explosion.
+import { readFileSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { resolveTarget } from "./locator.js";
+function targetSummary(t) {
+    if (t.ref)
+        return `ref ${t.ref}`;
+    if (t.selector)
+        return `selector ${t.selector}`;
+    if (t.coords)
+        return `coords ${t.coords.x},${t.coords.y}`;
+    return "(unknown)";
+}
+function basename(p) {
+    const i = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+    return i >= 0 ? p.slice(i + 1) : p;
+}
+/** Prepare a path-mode file: workspace-escape guarded, read off disk, base64'd. */
+function preparePathFile(workspaceRoot, f, i) {
+    const fp = f.path;
+    const resolved = resolve(workspaceRoot, fp);
+    if (resolved !== workspaceRoot && !resolved.startsWith(workspaceRoot + sep)) {
+        throw new Error(`drop_files: files[${i}].path must resolve inside $BROWX_WORKSPACE — stage the file there, or use \`contents\` (base64)`);
+    }
+    let buf;
+    try {
+        buf = readFileSync(resolved);
+    }
+    catch (err) {
+        throw new Error(`drop_files: files[${i}].path: ${err.message}`);
+    }
+    return {
+        base64: buf.toString("base64"),
+        name: f.name ?? basename(fp),
+        mimeType: f.mimeType ?? "application/octet-stream",
+        bytes: buf.length,
+        mode: "path",
+    };
+}
+/** Prepare a contents-mode file (base64 inline; `name` required). */
+function prepareContentsFile(f, i) {
+    if (!f.name || f.name.length === 0) {
+        throw new Error(`drop_files: files[${i}]: \`name\` is required in contents-mode`);
+    }
+    return {
+        base64: f.contents,
+        name: f.name,
+        mimeType: f.mimeType ?? "application/octet-stream",
+        bytes: Buffer.from(f.contents, "base64").length,
+        mode: "contents",
+    };
+}
+function prepareFiles(workspaceRoot, files) {
+    if (!Array.isArray(files) || files.length === 0) {
+        throw new Error("drop_files: `files` must be a non-empty array");
+    }
+    return files.map((f, i) => {
+        const hasPath = typeof f.path === "string" && f.path.length > 0;
+        const hasContents = typeof f.contents === "string";
+        if (hasPath && hasContents) {
+            throw new Error(`drop_files: files[${i}]: pass exactly one of \`path\` or \`contents\``);
+        }
+        if (!hasPath && !hasContents) {
+            throw new Error(`drop_files: files[${i}]: requires \`path\` or \`contents\``);
+        }
+        return hasPath
+            ? preparePathFile(workspaceRoot, f, i)
+            : prepareContentsFile(f, i);
+    });
+}
+export const dropFilesPageScript = function PAGE_DROP_FILES_FN(args) {
+    const g = globalThis;
+    const W = g.window ?? g;
+    const D = g.document ?? W.document;
+    if (!W || !D)
+        return { eventsFired: [], dropDispatched: false, error: "no window/document" };
+    // 1. Resolve the target element. For ref/selector mode the caller passed
+    //    `el` directly via Locator.evaluate; for coords mode `el` is null
+    //    and we look it up via elementFromPoint. The narrowing is inlined (NOT a
+    //    module-level helper): this function is serialized to the page by
+    //    Locator.evaluate, so any sibling-scope reference is a ReferenceError in
+    //    the page realm.
+    const elCandidate = args.el;
+    let target = typeof elCandidate === "object" &&
+        elCandidate !== null &&
+        typeof elCandidate.dispatchEvent === "function"
+        ? elCandidate
+        : null;
+    if (args.payload.byCoords || !target) {
+        target = D.elementFromPoint(args.payload.clientX, args.payload.clientY);
+    }
+    if (!target)
+        return {
+            eventsFired: [],
+            dropDispatched: false,
+            error: "no target element at the requested point",
+        };
+    // Bind a non-null alias so the closure below sees a narrowed element type.
+    const targetEl = target;
+    // 2. Materialise File objects from base64 payloads. `atob` is universal,
+    //    Uint8Array → File is the canonical drop-zone construction.
+    const fileObjs = [];
+    const rawAtob = W.atob ?? g.atob;
+    // `atob` is a universal global (browser + Node); the captured lookups above
+    // only matter for unusual page contexts. Bind to `W` when present, else fall
+    // back to the ambient global — the same function the original `g.atob` path
+    // resolved to (never a silent identity map).
+    const atobFn = rawAtob ? rawAtob.bind(W) : atob;
+    const U8 = W.Uint8Array ?? g.Uint8Array ?? Uint8Array;
+    const FileCtor = W.File ?? g.File;
+    for (let i = 0; i < args.payload.files.length; i++) {
+        const f = args.payload.files[i];
+        const bin = atobFn(f.base64);
+        const len = bin.length;
+        const u8 = new U8(len);
+        for (let j = 0; j < len; j++)
+            u8[j] = bin.charCodeAt(j) & 0xff;
+        if (FileCtor)
+            fileObjs.push(new FileCtor([u8], f.name, { type: f.mimeType }));
+    }
+    // 3. Build the DataTransfer. `new DataTransfer()` is the public API
+    //    listeners read `event.dataTransfer.files` from. `items.add(file)`
+    //    implicitly registers the "Files" type, which apps gate on (React-
+    //    DnD's NativeTypes.FILE, e.g.).
+    const DTCtor = W.DataTransfer ?? g.DataTransfer;
+    const dt = DTCtor ? new DTCtor() : undefined;
+    if (dt) {
+        for (const file of fileObjs) {
+            if (dt.items && typeof dt.items.add === "function") {
+                dt.items.add(file);
+            }
+            else {
+                // Older shims expose `files` as a settable FileList-like. Fall back
+                // by reassigning via Object.defineProperty so the value is enumerable
+                // and `length`/index access both work — best-effort for ancient
+                // browsers; modern Chromium hits the `items.add` path above.
+                try {
+                    const arr = Array.from(dt.files);
+                    arr.push(file);
+                    const fakeList = arr;
+                    fakeList.item = (idx) => arr[idx] ?? null;
+                    Object.defineProperty(dt, "files", { value: fakeList, configurable: true });
+                }
+                catch {
+                    /* swallow — items.add path covers Chromium */
+                }
+            }
+        }
+    }
+    const eventsFired = [];
+    const DragEv = W.DragEvent ?? g.DragEvent;
+    const Ev = W.Event ?? g.Event ?? Event;
+    const fireOne = (kind) => {
+        // DragEvent is preferred (carries `dataTransfer` natively); some
+        // older browsers (jsdom in tests) don't expose it as a constructor.
+        // Fall back to a regular Event with dataTransfer assigned through a
+        // property descriptor — every real Chromium hits the DragEvent path.
+        let ev;
+        try {
+            if (!DragEv)
+                throw new Error("no DragEvent");
+            ev = new DragEv(kind, {
+                bubbles: true,
+                cancelable: true,
+                composed: true,
+                clientX: args.payload.clientX,
+                clientY: args.payload.clientY,
+                dataTransfer: dt,
+            });
+        }
+        catch {
+            const base = new Ev(kind, { bubbles: true, cancelable: true, composed: true });
+            ev = base;
+            try {
+                Object.defineProperty(base, "dataTransfer", { value: dt, configurable: true });
+            }
+            catch {
+                /* best-effort */
+            }
+            base.clientX = args.payload.clientX;
+            base.clientY = args.payload.clientY;
+        }
+        // Modern Chromium DragEvent may have a read-only dataTransfer that
+        // ignores the constructor option. Defensive: if it didn't take, force
+        // it via descriptor.
+        try {
+            if (ev.dataTransfer !== dt) {
+                Object.defineProperty(ev, "dataTransfer", { value: dt, configurable: true });
+            }
+        }
+        catch {
+            /* best-effort */
+        }
+        targetEl.dispatchEvent(ev);
+        eventsFired.push(kind);
+    };
+    // 4. Dispatch the standard HTML5 drop sequence. `dragenter` → `dragover`
+    //    → `drop`. We send `dragover` once; a real human drag would emit it
+    //    continuously, but most drop-zone listeners only need one to set
+    //    `event.dataTransfer.dropEffect` / call `preventDefault` so the
+    //    subsequent `drop` is accepted.
+    fireOne("dragenter");
+    fireOne("dragover");
+    fireOne("drop");
+    const tag = target.tagName ? String(target.tagName).toLowerCase() : "?";
+    return {
+        eventsFired,
+        dropDispatched: eventsFired.indexOf("drop") >= 0,
+        hitTag: tag,
+    };
+};
+/** Resolve the viewport-relative drop point: coords mode uses the literal point;
+ *  element mode uses the target's bounding-box centre (throwing when unrendered). */
+async function computeDropPoint(resolved) {
+    if (resolved.kind === "coords") {
+        return { clientX: resolved.x, clientY: resolved.y, byCoords: true };
+    }
+    const box = await resolved.loc.boundingBox().catch(() => null);
+    if (!box || box.width <= 0 || box.height <= 0) {
+        throw new Error("drop_files: target element has no rendered box — scroll into view or wait for it to mount");
+    }
+    return { clientX: box.x + box.width / 2, clientY: box.y + box.height / 2, byCoords: false };
+}
+export async function dropFiles(page, refs, workspaceRoot, args) {
+    if (!args || !args.target) {
+        throw new Error("drop_files: requires `target` (ref/selector/named/coords)");
+    }
+    const prepared = prepareFiles(workspaceRoot, args.files);
+    // Compute the viewport-relative click point on the Node side so apps reading
+    // `event.clientX`/`clientY` see realistic values.
+    const resolved = resolveTarget(page, refs, args.target);
+    const { clientX, clientY, byCoords } = await computeDropPoint(resolved);
+    const payload = {
+        clientX,
+        clientY,
+        byCoords,
+        files: prepared.map((p) => ({ base64: p.base64, name: p.name, mimeType: p.mimeType })),
+    };
+    // Inline the page-side script as a string so the closure-over-
+    // `dropFilesPageScript` survives the CDP boundary. Playwright's
+    // `evaluate(fn, arg)` accepts the function source as a string, parses
+    // it in the page, and invokes it with the cloned argument bag — exactly
+    // what we want, no addInitScript indirection required.
+    const scriptSource = dropFilesPageScript.toString();
+    // Dispatch. For ref/selector targets we route through the Locator so
+    // the page-side script receives the element directly as `el`. For coords
+    // we run on `page` and the script re-resolves via `elementFromPoint`.
+    const result = resolved.kind === "coords"
+        ? await page.evaluate((a) => {
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval
+            const factory = new Function("return (" + a.src + ");");
+            const fn = factory();
+            return fn({ el: null, payload: a.payload });
+        }, { payload, src: scriptSource })
+        : await resolved.loc.evaluate(
+        // Locator.evaluate signature: (element, arg).
+        (el, a) => {
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval
+            const factory = new Function("return (" + a.src + ");");
+            const fn = factory();
+            return fn({ el, payload: a.payload });
+        }, { payload, src: scriptSource });
+    if (result.error) {
+        throw new Error(`drop_files: in-page dispatch failed — ${result.error}`);
+    }
+    const totalBytes = prepared.reduce((acc, p) => acc + p.bytes, 0);
+    return {
+        ok: true,
+        target: targetSummary(args.target),
+        files: prepared.map((p) => ({
+            name: p.name,
+            mode: p.mode,
+            bytes: p.bytes,
+            mimeType: p.mimeType,
+        })),
+        totalBytes,
+        fileCount: prepared.length,
+        eventsFired: result.eventsFired,
+        dropDispatched: result.dropDispatched,
+    };
+}