@ricsam/r5d-browser 0.0.125 → 0.0.126

package/README.md

@@ -26,6 +26,12 @@ Password input values are replaced with `[redacted]` in `browser_read_page` snap
 
 Agents read pages through `browser_read_page`, an accessibility outline with stable element refs (`[ref=e12]`) on interactable elements and `[box=x,y,w,h]` viewport coordinates on everything visible. Refs feed the one-call interaction tools: `browser_mouse_click` clicks a ref (scrolled into view, with actionability checks) or an x/y point, `browser_form_input` sets values on text inputs, selects, checkboxes, and contenteditable elements with trusted events that controlled (React-style) components honor, and `browser_scroll` scrolls an element into view or dispatches trusted wheel input. Same-origin iframe content appears inline with frame-prefixed refs such as `f1e3`; cross-origin frame content may be omitted. Refs come from the most recent snapshot of a tab, so agents re-read the page after navigations or large re-renders. `browser_wait_for` waits for a selector, visible text, a URL glob, or a load state instead of sleeping, and `browser_keyboard_type` has a `keys` mode that presses each character as a real key event (up to 500 characters per call) for type-ahead widgets — characters without key codes, such as emoji, still fall back to text insertion. Screenshots capture the viewport by default; `fullPage: true` captures the scrollable page up to 4000 CSS px of height.
 
+Agents attach worker files with `browser_upload_files({ tabId, files, ref })`, or `selector` instead of `ref` for a hidden file input. `files` contains up to 100 regular-file paths on the session's bound worker: absolute paths, paths relative to the session working directory, `~/` paths, or paths using `$R5D_ROOT` and `$R5D_SESSION_ID`. The files may live outside the repository. Multiple files require an input with `multiple`; directory inputs and native file-picker dialogs are not supported.
+
+The operation reads the source files in 1 MiB chunks, relays them through r5d.dev without storing their bytes in artifacts or recovery journals, verifies size and SHA-256, and attaches them using Playwright. Browser copies live in private, generated folders under `~/.r5d/browser/uploads`, preserving filenames even when several files share a name. Completed copies remain until their tab closes or r5d-browser exits so later form submission can still read them. Failed transfers are removed; abandoned partial transfers expire after five minutes without activity, and the next browser start clears staging left after a crash. There is no per-file byte limit; one operation has a 30-minute deadline. Changed source files, disconnections, stale target elements, and session cancellation fail the operation without automatically retrying attachment. Both the worker and browser must advertise upload support.
+
+Setting a file input fires its normal input/change events, which may immediately start a site's upload. For forms that require a separate submit action, the agent submits afterwards. The result reports attached filenames and byte sizes; it does not claim the website finished processing them.
+
 Agents running JavaScript in a page can save captured text straight into the active session's artifacts by calling `r5dCreateArtifact(filename, content)`, which takes two strings and must be called before the agent's code returns. Each captured file is written to the session artifacts in r5d.dev, synchronized to every connected worker, and reported back under `$R5D_ROOT/artifacts/$R5D_SESSION_ID`; a single call may create at most 32 files totalling 4 MiB. The function is passed into the agent's code rather than assigned to `window`, so pages can neither call it nor use it to detect automation.
 
 For responsive testing that needs an existing login (for example, an app using Google login), agents can call `browser_set_viewport` with `{ tabId, width: 390, height: 844 }`. Both dimensions must be integers from 1 to 4096 CSS pixels. The override is scoped to that tab, even in a shared window: it does not resize the OS window or affect other tabs. It preserves the profile, user agent, touch support, and device pixel ratio; this is layout sizing, not mobile-device emulation. It adds no Chrome launch flags or webdriver spoofing; `navigator.webdriver` remains natively `false`.

package/dist/cjs/browser-input.cjs

@@ -41,6 +41,11 @@ const browserInputFields = {
   keyboard: { required: ["tabId", "keys"], optional: ["modifiers"] },
   keyboard_type: { required: ["tabId", "text"], optional: ["mode", "delayMs"] },
   run_js: { required: ["tabId", "code"], optional: [] },
+  upload_files: { required: ["tabId", "files"], optional: ["ref", "selector"] },
+  upload_begin: { required: ["tabId", "uploadId", "files"], optional: ["ref", "selector"] },
+  upload_chunk: { required: ["tabId", "uploadId", "index", "offset", "base64"], optional: [] },
+  upload_attach: { required: ["tabId", "uploadId", "hashes"], optional: [] },
+  upload_abort: { required: ["tabId", "uploadId"], optional: [] },
   port_forward: { required: ["workerPort"], optional: ["browserPort"] },
   list_port_forwards: { required: [], optional: [] },
   stop_port_forward: { required: ["forwardId"], optional: [] }

package/dist/cjs/browser-runtime.cjs

@@ -34,6 +34,8 @@ module.exports = __toCommonJS(browser_runtime_exports);
 var import_node_fs = __toESM(require("node:fs"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
 var import_browser_input = require("./browser-input.cjs");
+var import_upload_store = require("./upload-store.cjs");
+var import_browser_upload = require("@ricsam/r5d-api/browser-upload");
 var import_password_safe_snapshot = require("./password-safe-snapshot.cjs");
 const MAX_DOWNLOAD_CHUNK_BYTES = 1024 * 1024;
 const MAX_RUN_JS_RESULT_BYTES = 1024 * 1024;
@@ -72,9 +74,12 @@ Ref ${ref} comes from the most recent browser_read_page snapshot of this tab. If
   );
 }
 class BrowserRuntime {
-  constructor(context, downloadsPath) {
+  constructor(context, downloadsPath, uploadsPath = `${downloadsPath}.uploads`) {
     this.context = context;
     this.downloadsPath = downloadsPath;
+    this.uploads = new import_upload_store.BrowserUploadStore(uploadsPath, (target) => {
+      void target.dispose().catch(() => void 0);
+    });
     import_node_fs.default.mkdirSync(downloadsPath, { recursive: true });
     for (const page of context.pages()) this.track(page);
     context.on("page", (page) => this.track(page));
@@ -85,6 +90,7 @@ class BrowserRuntime {
   pages = /* @__PURE__ */ new Map();
   cursor = /* @__PURE__ */ new Map();
   viewportSessions = /* @__PURE__ */ new Map();
+  uploads;
   downloadSaveQueue = Promise.resolve();
   track(page) {
     const existing = this.ids.get(page);
@@ -99,6 +105,7 @@ class BrowserRuntime {
       });
     });
     page.once("close", () => {
+      this.uploads.closeTab(id);
       this.pages.delete(id);
       this.cursor.delete(id);
       this.viewportSessions.delete(id);
@@ -265,8 +272,15 @@ class BrowserRuntime {
     const actual = await page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }));
     return { tabId, ...actual, reset: viewport === null };
   }
+  closeUploads() {
+    this.uploads.close();
+  }
   async execute(action, input) {
     input = (0, import_browser_input.normalizeBrowserInput)(action, input);
+    if (action === "upload_abort") {
+      this.uploads.abort(input.uploadId, input.tabId);
+      return { aborted: true };
+    }
     if (action === "list_tabs") return { tabs: await this.listTabs() };
     if (action === "list_downloads") return { downloads: await this.listDownloads() };
     if (action === "get_download") return await this.getDownloadChunk(input);
@@ -490,6 +504,38 @@ class BrowserRuntime {
         }
         return { tabId, matched: true, elapsedMs: Date.now() - started, url: page.url(), title: await page.title().catch(() => "") };
       }
+      case "upload_begin": {
+        const target = (0, import_browser_upload.parseUploadTarget)(input);
+        const locator = target.ref ? this.refLocator(page, target.ref) : page.locator(target.selector);
+        const element = await locator.elementHandle({ timeout: REF_ACTION_TIMEOUT_MS });
+        if (!element) throw new Error("File input was not found.");
+        try {
+          const info = await element.evaluate((el) => ({
+            fileInput: el instanceof HTMLInputElement && el.type === "file",
+            directory: el.hasAttribute("webkitdirectory"),
+            multiple: el.hasAttribute("multiple")
+          }));
+          if (!info.fileInput || info.directory) throw new Error("Target must be a file input (directory inputs are not supported).");
+          if (Array.isArray(input.files) && input.files.length > 1 && !info.multiple) throw new Error("This file input does not accept multiple files.");
+          this.uploads.begin(input.uploadId, tabId, input.files, element);
+          return { tabId, uploadId: input.uploadId };
+        } catch (error) {
+          await element.dispose().catch(() => void 0);
+          throw error;
+        }
+      }
+      case "upload_chunk":
+        this.uploads.append(input.uploadId, tabId, input.index, input.offset, input.base64);
+        return { tabId, uploadId: input.uploadId };
+      case "upload_attach": {
+        const upload = this.uploads.ready(input.uploadId, tabId, input.hashes);
+        if (!await upload.target.evaluate((el) => el.isConnected && el instanceof HTMLInputElement && el.type === "file")) {
+          throw new Error("The file input was removed or changed during the upload. Read the page again and retry.");
+        }
+        await upload.target.setInputFiles(upload.paths, { timeout: REF_ACTION_TIMEOUT_MS });
+        this.uploads.attached(input.uploadId, tabId);
+        return { tabId, files: upload.files };
+      }
       case "form_input": {
         const ref = requireRef(input.ref);
         const provided = ["value", "values", "checked"].filter((key) => input[key] !== void 0);

package/dist/cjs/main.cjs

@@ -160,7 +160,8 @@ async function connectLoop(params) {
               formInput: true,
               typedKeys: true,
               screenshotFullPage: true,
-              viewportSizing: true
+              viewportSizing: true,
+              fileUploads: true
             }
           },
           tabs: await params.runtime.listTabs(),
@@ -213,6 +214,11 @@ async function connectLoop(params) {
             }
             if (message.type !== "operation") return;
             try {
+              if (["upload_begin", "upload_chunk", "upload_abort"].includes(message.action)) {
+                const result2 = await params.runtime.execute(message.action, message.input);
+                socket?.send(JSON.stringify({ type: "operation_result", requestId: message.requestId, result: result2 }));
+                return;
+              }
               const beforeTabs = await params.runtime.listTabs();
               const operationResult = await params.runtime.execute(message.action, message.input);
               const tabs = await params.runtime.listTabs();
@@ -332,7 +338,9 @@ async function start(options) {
   }
   try {
     const profilePath = launch.profilePath;
-    const runtime = new import_browser_runtime.BrowserRuntime(launch.context, downloadsPath);
+    const uploadsPath = import_node_path.default.join(browserRoot(), "uploads");
+    import_node_fs.default.rmSync(uploadsPath, { recursive: true, force: true });
+    const runtime = new import_browser_runtime.BrowserRuntime(launch.context, downloadsPath, uploadsPath);
     const instanceId = loadInstanceId();
     const portForwards = new import_port_forward_manager.BrowserPortForwardManager(baseUrl, token, instanceId);
     process.stdout.write(`[r5d-browser] profile: ${profilePath}
@@ -391,6 +399,7 @@ async function start(options) {
     } catch (error) {
       cleanupError ??= error;
     }
+    runtime.closeUploads();
     await controlStopped;
     for (const [signal, handler] of signalHandlers) processEvents.off(signal, handler);
     if (outcome.exitCode !== 0) throw new Error(outcome.message ?? "Google Chrome stopped unexpectedly.");

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-browser",
-  "version": "0.0.125",
+  "version": "0.0.126",
   "type": "commonjs"
 }

package/dist/cjs/upload-store.cjs

@@ -0,0 +1,136 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var upload_store_exports = {};
+__export(upload_store_exports, {
+  BrowserUploadStore: () => BrowserUploadStore
+});
+module.exports = __toCommonJS(upload_store_exports);
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+var import_node_crypto = require("node:crypto");
+var import_browser_upload = require("@ricsam/r5d-api/browser-upload");
+class BrowserUploadStore {
+  constructor(root, releaseTarget = () => void 0) {
+    this.releaseTarget = releaseTarget;
+    import_node_fs.default.mkdirSync(root, { recursive: true, mode: 448 });
+    this.directory = import_node_fs.default.mkdtempSync(import_node_path.default.join(root, "run-"));
+  }
+  releaseTarget;
+  directory;
+  uploads = /* @__PURE__ */ new Map();
+  begin(id, tabId, files, target) {
+    if (typeof id !== "string" || !/^[a-f0-9-]{36}$/.test(id) || this.uploads.has(id)) throw new Error("Invalid or duplicate upload id.");
+    if (!Array.isArray(files) || files.length === 0 || files.length > 100) throw new Error("Upload requires between 1 and 100 files.");
+    const metadata = files.map(import_browser_upload.validateUploadFile);
+    const directory = import_node_fs.default.mkdtempSync(import_node_path.default.join(this.directory, "upload-"));
+    try {
+      const staged = metadata.map((file, index) => {
+        const parent = import_node_path.default.join(directory, String(index));
+        import_node_fs.default.mkdirSync(parent, { mode: 448 });
+        const filePath = import_node_path.default.join(parent, file.filename);
+        import_node_fs.default.closeSync(import_node_fs.default.openSync(filePath, "wx", 384));
+        return { ...file, path: filePath, offset: 0, hash: (0, import_node_crypto.createHash)("sha256") };
+      });
+      const timer = setTimeout(() => this.abort(id, tabId), 5 * 60 * 1e3);
+      timer.unref();
+      this.uploads.set(id, { tabId, directory, files: staged, target, attached: false, timer });
+    } catch (error) {
+      import_node_fs.default.rmSync(directory, { recursive: true, force: true });
+      throw error;
+    }
+  }
+  get(id, tabId) {
+    const upload = typeof id === "string" ? this.uploads.get(id) : void 0;
+    if (!upload || upload.tabId !== tabId) throw new Error("Upload is missing, expired, or belongs to another tab.");
+    if (upload.attached) throw new Error("Upload has already been attached.");
+    upload.timer.refresh();
+    return upload;
+  }
+  append(id, tabId, index, offset, base64) {
+    const upload = this.get(id, tabId);
+    const file = typeof index === "number" && Number.isInteger(index) ? upload.files[index] : void 0;
+    if (!file || offset !== file.offset) throw new Error("Invalid upload file index or chunk offset.");
+    const bytes = (0, import_browser_upload.decodeUploadChunk)(base64);
+    if (bytes.length === 0 || file.offset + bytes.length > file.size)
+      throw new Error("Upload chunk does not match the declared file size.");
+    const fd = import_node_fs.default.openSync(file.path, import_node_fs.default.constants.O_WRONLY | import_node_fs.default.constants.O_NOFOLLOW);
+    try {
+      let written = 0;
+      while (written < bytes.length) {
+        const count = import_node_fs.default.writeSync(fd, bytes, written, bytes.length - written, file.offset + written);
+        if (!count) throw new Error("Could not write upload chunk.");
+        written += count;
+      }
+    } finally {
+      import_node_fs.default.closeSync(fd);
+    }
+    file.hash.update(bytes);
+    file.offset += bytes.length;
+  }
+  ready(id, tabId, hashes) {
+    const upload = this.get(id, tabId);
+    if (!Array.isArray(hashes) || hashes.length !== upload.files.length) throw new Error("Upload requires a checksum for every file.");
+    for (const [index, file] of upload.files.entries()) {
+      if (file.offset !== file.size || file.hash.copy().digest("hex") !== hashes[index])
+        throw new Error("Upload is incomplete or its checksum does not match.");
+    }
+    return {
+      target: upload.target,
+      paths: upload.files.map((file) => file.path),
+      files: upload.files.map(({ filename, size }) => ({ filename, size }))
+    };
+  }
+  attached(id, tabId) {
+    const upload = this.get(id, tabId);
+    upload.attached = true;
+    clearTimeout(upload.timer);
+  }
+  abort(id, tabId) {
+    const upload = this.uploads.get(id);
+    if (!upload || upload.tabId !== tabId || upload.attached) return;
+    this.remove(id, upload);
+  }
+  remove(id, upload) {
+    clearTimeout(upload.timer);
+    this.uploads.delete(id);
+    this.releaseTarget(upload.target);
+    import_node_fs.default.rmSync(upload.directory, { recursive: true, force: true });
+  }
+  closeTab(tabId) {
+    for (const [id, upload] of this.uploads) if (upload.tabId === tabId) this.remove(id, upload);
+  }
+  close() {
+    for (const [id, upload] of this.uploads) this.remove(id, upload);
+    import_node_fs.default.rmSync(this.directory, { recursive: true, force: true });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BrowserUploadStore
+});

package/dist/mjs/browser-input.mjs

@@ -16,6 +16,11 @@ const browserInputFields = {
   keyboard: { required: ["tabId", "keys"], optional: ["modifiers"] },
   keyboard_type: { required: ["tabId", "text"], optional: ["mode", "delayMs"] },
   run_js: { required: ["tabId", "code"], optional: [] },
+  upload_files: { required: ["tabId", "files"], optional: ["ref", "selector"] },
+  upload_begin: { required: ["tabId", "uploadId", "files"], optional: ["ref", "selector"] },
+  upload_chunk: { required: ["tabId", "uploadId", "index", "offset", "base64"], optional: [] },
+  upload_attach: { required: ["tabId", "uploadId", "hashes"], optional: [] },
+  upload_abort: { required: ["tabId", "uploadId"], optional: [] },
   port_forward: { required: ["workerPort"], optional: ["browserPort"] },
   list_port_forwards: { required: [], optional: [] },
   stop_port_forward: { required: ["forwardId"], optional: [] }

package/dist/mjs/browser-runtime.mjs

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeBrowserInput, parseViewportInput } from "./browser-input.mjs";
+import { BrowserUploadStore } from "./upload-store.mjs";
+import { parseUploadTarget } from "@ricsam/r5d-api/browser-upload";
 import { passwordSafeAriaSnapshot } from "./password-safe-snapshot.mjs";
 const MAX_DOWNLOAD_CHUNK_BYTES = 1024 * 1024;
 const MAX_RUN_JS_RESULT_BYTES = 1024 * 1024;
@@ -39,9 +41,12 @@ Ref ${ref} comes from the most recent browser_read_page snapshot of this tab. If
   );
 }
 class BrowserRuntime {
-  constructor(context, downloadsPath) {
+  constructor(context, downloadsPath, uploadsPath = `${downloadsPath}.uploads`) {
     this.context = context;
     this.downloadsPath = downloadsPath;
+    this.uploads = new BrowserUploadStore(uploadsPath, (target) => {
+      void target.dispose().catch(() => void 0);
+    });
     fs.mkdirSync(downloadsPath, { recursive: true });
     for (const page of context.pages()) this.track(page);
     context.on("page", (page) => this.track(page));
@@ -52,6 +57,7 @@ class BrowserRuntime {
   pages = /* @__PURE__ */ new Map();
   cursor = /* @__PURE__ */ new Map();
   viewportSessions = /* @__PURE__ */ new Map();
+  uploads;
   downloadSaveQueue = Promise.resolve();
   track(page) {
     const existing = this.ids.get(page);
@@ -66,6 +72,7 @@ class BrowserRuntime {
       });
     });
     page.once("close", () => {
+      this.uploads.closeTab(id);
       this.pages.delete(id);
       this.cursor.delete(id);
       this.viewportSessions.delete(id);
@@ -232,8 +239,15 @@ class BrowserRuntime {
     const actual = await page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }));
     return { tabId, ...actual, reset: viewport === null };
   }
+  closeUploads() {
+    this.uploads.close();
+  }
   async execute(action, input) {
     input = normalizeBrowserInput(action, input);
+    if (action === "upload_abort") {
+      this.uploads.abort(input.uploadId, input.tabId);
+      return { aborted: true };
+    }
     if (action === "list_tabs") return { tabs: await this.listTabs() };
     if (action === "list_downloads") return { downloads: await this.listDownloads() };
     if (action === "get_download") return await this.getDownloadChunk(input);
@@ -457,6 +471,38 @@ class BrowserRuntime {
         }
         return { tabId, matched: true, elapsedMs: Date.now() - started, url: page.url(), title: await page.title().catch(() => "") };
       }
+      case "upload_begin": {
+        const target = parseUploadTarget(input);
+        const locator = target.ref ? this.refLocator(page, target.ref) : page.locator(target.selector);
+        const element = await locator.elementHandle({ timeout: REF_ACTION_TIMEOUT_MS });
+        if (!element) throw new Error("File input was not found.");
+        try {
+          const info = await element.evaluate((el) => ({
+            fileInput: el instanceof HTMLInputElement && el.type === "file",
+            directory: el.hasAttribute("webkitdirectory"),
+            multiple: el.hasAttribute("multiple")
+          }));
+          if (!info.fileInput || info.directory) throw new Error("Target must be a file input (directory inputs are not supported).");
+          if (Array.isArray(input.files) && input.files.length > 1 && !info.multiple) throw new Error("This file input does not accept multiple files.");
+          this.uploads.begin(input.uploadId, tabId, input.files, element);
+          return { tabId, uploadId: input.uploadId };
+        } catch (error) {
+          await element.dispose().catch(() => void 0);
+          throw error;
+        }
+      }
+      case "upload_chunk":
+        this.uploads.append(input.uploadId, tabId, input.index, input.offset, input.base64);
+        return { tabId, uploadId: input.uploadId };
+      case "upload_attach": {
+        const upload = this.uploads.ready(input.uploadId, tabId, input.hashes);
+        if (!await upload.target.evaluate((el) => el.isConnected && el instanceof HTMLInputElement && el.type === "file")) {
+          throw new Error("The file input was removed or changed during the upload. Read the page again and retry.");
+        }
+        await upload.target.setInputFiles(upload.paths, { timeout: REF_ACTION_TIMEOUT_MS });
+        this.uploads.attached(input.uploadId, tabId);
+        return { tabId, files: upload.files };
+      }
       case "form_input": {
         const ref = requireRef(input.ref);
         const provided = ["value", "values", "checked"].filter((key) => input[key] !== void 0);

package/dist/mjs/main.mjs

@@ -137,7 +137,8 @@ async function connectLoop(params) {
               formInput: true,
               typedKeys: true,
               screenshotFullPage: true,
-              viewportSizing: true
+              viewportSizing: true,
+              fileUploads: true
             }
           },
           tabs: await params.runtime.listTabs(),
@@ -190,6 +191,11 @@ async function connectLoop(params) {
             }
             if (message.type !== "operation") return;
             try {
+              if (["upload_begin", "upload_chunk", "upload_abort"].includes(message.action)) {
+                const result2 = await params.runtime.execute(message.action, message.input);
+                socket?.send(JSON.stringify({ type: "operation_result", requestId: message.requestId, result: result2 }));
+                return;
+              }
               const beforeTabs = await params.runtime.listTabs();
               const operationResult = await params.runtime.execute(message.action, message.input);
               const tabs = await params.runtime.listTabs();
@@ -309,7 +315,9 @@ async function start(options) {
   }
   try {
     const profilePath = launch.profilePath;
-    const runtime = new BrowserRuntime(launch.context, downloadsPath);
+    const uploadsPath = path.join(browserRoot(), "uploads");
+    fs.rmSync(uploadsPath, { recursive: true, force: true });
+    const runtime = new BrowserRuntime(launch.context, downloadsPath, uploadsPath);
     const instanceId = loadInstanceId();
     const portForwards = new BrowserPortForwardManager(baseUrl, token, instanceId);
     process.stdout.write(`[r5d-browser] profile: ${profilePath}
@@ -368,6 +376,7 @@ async function start(options) {
     } catch (error) {
       cleanupError ??= error;
     }
+    runtime.closeUploads();
     await controlStopped;
     for (const [signal, handler] of signalHandlers) processEvents.off(signal, handler);
     if (outcome.exitCode !== 0) throw new Error(outcome.message ?? "Google Chrome stopped unexpectedly.");

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-browser",
-  "version": "0.0.125",
+  "version": "0.0.126",
   "type": "module"
 }

package/dist/mjs/upload-store.mjs

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { decodeUploadChunk, validateUploadFile } from "@ricsam/r5d-api/browser-upload";
+class BrowserUploadStore {
+  constructor(root, releaseTarget = () => void 0) {
+    this.releaseTarget = releaseTarget;
+    fs.mkdirSync(root, { recursive: true, mode: 448 });
+    this.directory = fs.mkdtempSync(path.join(root, "run-"));
+  }
+  releaseTarget;
+  directory;
+  uploads = /* @__PURE__ */ new Map();
+  begin(id, tabId, files, target) {
+    if (typeof id !== "string" || !/^[a-f0-9-]{36}$/.test(id) || this.uploads.has(id)) throw new Error("Invalid or duplicate upload id.");
+    if (!Array.isArray(files) || files.length === 0 || files.length > 100) throw new Error("Upload requires between 1 and 100 files.");
+    const metadata = files.map(validateUploadFile);
+    const directory = fs.mkdtempSync(path.join(this.directory, "upload-"));
+    try {
+      const staged = metadata.map((file, index) => {
+        const parent = path.join(directory, String(index));
+        fs.mkdirSync(parent, { mode: 448 });
+        const filePath = path.join(parent, file.filename);
+        fs.closeSync(fs.openSync(filePath, "wx", 384));
+        return { ...file, path: filePath, offset: 0, hash: createHash("sha256") };
+      });
+      const timer = setTimeout(() => this.abort(id, tabId), 5 * 60 * 1e3);
+      timer.unref();
+      this.uploads.set(id, { tabId, directory, files: staged, target, attached: false, timer });
+    } catch (error) {
+      fs.rmSync(directory, { recursive: true, force: true });
+      throw error;
+    }
+  }
+  get(id, tabId) {
+    const upload = typeof id === "string" ? this.uploads.get(id) : void 0;
+    if (!upload || upload.tabId !== tabId) throw new Error("Upload is missing, expired, or belongs to another tab.");
+    if (upload.attached) throw new Error("Upload has already been attached.");
+    upload.timer.refresh();
+    return upload;
+  }
+  append(id, tabId, index, offset, base64) {
+    const upload = this.get(id, tabId);
+    const file = typeof index === "number" && Number.isInteger(index) ? upload.files[index] : void 0;
+    if (!file || offset !== file.offset) throw new Error("Invalid upload file index or chunk offset.");
+    const bytes = decodeUploadChunk(base64);
+    if (bytes.length === 0 || file.offset + bytes.length > file.size)
+      throw new Error("Upload chunk does not match the declared file size.");
+    const fd = fs.openSync(file.path, fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW);
+    try {
+      let written = 0;
+      while (written < bytes.length) {
+        const count = fs.writeSync(fd, bytes, written, bytes.length - written, file.offset + written);
+        if (!count) throw new Error("Could not write upload chunk.");
+        written += count;
+      }
+    } finally {
+      fs.closeSync(fd);
+    }
+    file.hash.update(bytes);
+    file.offset += bytes.length;
+  }
+  ready(id, tabId, hashes) {
+    const upload = this.get(id, tabId);
+    if (!Array.isArray(hashes) || hashes.length !== upload.files.length) throw new Error("Upload requires a checksum for every file.");
+    for (const [index, file] of upload.files.entries()) {
+      if (file.offset !== file.size || file.hash.copy().digest("hex") !== hashes[index])
+        throw new Error("Upload is incomplete or its checksum does not match.");
+    }
+    return {
+      target: upload.target,
+      paths: upload.files.map((file) => file.path),
+      files: upload.files.map(({ filename, size }) => ({ filename, size }))
+    };
+  }
+  attached(id, tabId) {
+    const upload = this.get(id, tabId);
+    upload.attached = true;
+    clearTimeout(upload.timer);
+  }
+  abort(id, tabId) {
+    const upload = this.uploads.get(id);
+    if (!upload || upload.tabId !== tabId || upload.attached) return;
+    this.remove(id, upload);
+  }
+  remove(id, upload) {
+    clearTimeout(upload.timer);
+    this.uploads.delete(id);
+    this.releaseTarget(upload.target);
+    fs.rmSync(upload.directory, { recursive: true, force: true });
+  }
+  closeTab(tabId) {
+    for (const [id, upload] of this.uploads) if (upload.tabId === tabId) this.remove(id, upload);
+  }
+  close() {
+    for (const [id, upload] of this.uploads) this.remove(id, upload);
+    fs.rmSync(this.directory, { recursive: true, force: true });
+  }
+}
+export {
+  BrowserUploadStore
+};

package/dist/types/browser-input.d.ts

@@ -67,6 +67,26 @@ declare const browserInputFields: {
         required: string[];
         optional: never[];
     };
+    upload_files: {
+        required: string[];
+        optional: string[];
+    };
+    upload_begin: {
+        required: string[];
+        optional: string[];
+    };
+    upload_chunk: {
+        required: string[];
+        optional: never[];
+    };
+    upload_attach: {
+        required: string[];
+        optional: never[];
+    };
+    upload_abort: {
+        required: string[];
+        optional: never[];
+    };
     port_forward: {
         required: string[];
         optional: string[];

package/dist/types/browser-runtime.d.ts

@@ -1,5 +1,5 @@
 import type { BrowserContext } from "playwright-core";
-export type BrowserAction = "list_tabs" | "list_downloads" | "get_download" | "open_tab" | "close_tab" | "navigate" | "set_viewport" | "read_page" | "screenshot" | "move_mouse" | "mouse_click" | "scroll" | "wait_for" | "form_input" | "keyboard" | "keyboard_type" | "run_js";
+export type BrowserAction = "list_tabs" | "list_downloads" | "get_download" | "open_tab" | "close_tab" | "navigate" | "set_viewport" | "read_page" | "screenshot" | "move_mouse" | "mouse_click" | "scroll" | "wait_for" | "form_input" | "keyboard" | "keyboard_type" | "run_js" | "upload_begin" | "upload_chunk" | "upload_attach" | "upload_abort";
 export type TabInfo = {
     tabId: string;
     windowId: string;
@@ -19,8 +19,9 @@ export declare class BrowserRuntime {
     private readonly pages;
     private readonly cursor;
     private readonly viewportSessions;
+    private readonly uploads;
     private downloadSaveQueue;
-    constructor(context: BrowserContext, downloadsPath: string);
+    constructor(context: BrowserContext, downloadsPath: string, uploadsPath?: string);
     private track;
     private safeDownloadFilename;
     private availableDownloadPath;
@@ -36,5 +37,6 @@ export declare class BrowserRuntime {
     listTabs(): Promise<TabInfo[]>;
     drainDownloads(): Promise<void>;
     private setViewport;
+    closeUploads(): void;
     execute(action: BrowserAction, input: Record<string, unknown>): Promise<unknown>;
 }

package/dist/types/upload-store.d.ts

@@ -0,0 +1,21 @@
+import { type BrowserUploadFile } from "@ricsam/r5d-api/browser-upload";
+/** Owns only private, generated directories. Source paths are never accepted on the browser host. */
+export declare class BrowserUploadStore<T> {
+    private readonly releaseTarget;
+    private readonly directory;
+    private readonly uploads;
+    constructor(root: string, releaseTarget?: (target: T) => void);
+    begin(id: string, tabId: string, files: unknown, target: T): void;
+    private get;
+    append(id: unknown, tabId: string, index: unknown, offset: unknown, base64: unknown): void;
+    ready(id: unknown, tabId: string, hashes: unknown): {
+        target: T;
+        paths: string[];
+        files: BrowserUploadFile[];
+    };
+    attached(id: string, tabId: string): void;
+    abort(id: string, tabId: string): void;
+    private remove;
+    closeTab(tabId: string): void;
+    close(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-browser",
-  "version": "0.0.125",
+  "version": "0.0.126",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",
@@ -21,6 +21,7 @@
     "r5d-browser": "dist/cjs/main.cjs"
   },
   "dependencies": {
+    "@ricsam/r5d-api": "^0.0.126",
     "playwright-core": "1.62.1",
     "ws": "^8.18.3"
   },