@ricsam/r5d-browser 0.0.113 → 0.0.115

package/README.md

@@ -22,10 +22,16 @@ r5d-browser start --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/
 
 The profile is stored under `~/.r5d/browser/chrome-profile`. The previous Chrome for Testing profile at `~/.r5d/browser/profile` is preserved but is not migrated automatically, so sign in again the first time you use the new profile. Browser binaries previously installed under `~/.r5d/browser/browsers` are also left untouched, but new versions of `r5d-browser` do not use them. Completed downloads are retained under `~/.r5d/browser/downloads`; agents can list them and copy a selected file into the active session's artifacts. That artifact is then synchronized to every connected worker. Browser screenshots are session artifacts in r5d.dev and are not retained by the browser process.
 
+Password input values are replaced with `[redacted]` in `browser_read_page` snapshots, including values used in accessibility labels and iframe content. Reading a snapshot preserves the actual form values.
+
 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 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`.
+
+The viewport survives navigation, reloads, and r5d.dev control-connection reconnects until the agent calls `browser_set_viewport` with `{ tabId, reset: true }`, closes the tab, or exits the browser. Reset restores sizing from the current OS window; omit width/height when resetting. The tool returns the actual width and height. Re-read the page or capture a screenshot after resizing because old coordinates are stale, and reset when testing is finished. To apply a size before the first page load, open `about:blank`, set its viewport, then navigate. An outdated browser client returns an update-and-restart instruction for this tool.
+
 As an escape hatch, agents can create loopback-only TCP port forwards from this Mac to the worker bound to a chat when a local flow specifically needs this browser's authenticated state or human interaction, such as testing Google OAuth. Ordinary local application testing should use Playwright directly on the worker without a forward. For example, a forward can map Chrome's `localhost:4323` to `127.0.0.1:3232` on that worker. The relay preserves raw TCP traffic, including HTTP, HTTPS, WebSockets, HMR, and SSE; it never exposes a public listener or permits an arbitrary target host.
 
 Port forwards remain active across agent turns and r5d.dev control-connection reconnects. They are owned by the running `r5d-browser` process, so restarting that process ends them. Agents can list and stop forwards, and the user can inspect or stop them from Settings.

package/dist/cjs/browser-input.cjs

@@ -0,0 +1,82 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var browser_input_exports = {};
+__export(browser_input_exports, {
+  MAX_VIEWPORT_DIMENSION: () => MAX_VIEWPORT_DIMENSION,
+  normalizeBrowserInput: () => normalizeBrowserInput,
+  parseViewportInput: () => parseViewportInput
+});
+module.exports = __toCommonJS(browser_input_exports);
+const browserInputFields = {
+  list_tabs: { required: [], optional: [] },
+  list_downloads: { required: [], optional: [] },
+  get_download: { required: ["downloadId"], optional: ["offset", "maxBytes"] },
+  open_tab: { required: [], optional: ["url", "disposition"] },
+  close_tab: { required: ["tabId"], optional: [] },
+  navigate: { required: ["tabId", "url"], optional: [] },
+  set_viewport: { required: ["tabId"], optional: ["width", "height", "reset"] },
+  read_page: { required: ["tabId"], optional: ["depth", "maxChars"] },
+  screenshot: { required: ["tabId"], optional: ["fullPage"] },
+  move_mouse: { required: ["tabId", "x", "y"], optional: [] },
+  mouse_click: { required: ["tabId"], optional: ["ref", "x", "y", "button", "clickCount"] },
+  scroll: { required: ["tabId"], optional: ["ref", "direction", "amount", "x", "y"] },
+  wait_for: { required: ["tabId"], optional: ["selector", "text", "url", "loadState", "state", "timeoutMs"] },
+  form_input: { required: ["tabId", "ref"], optional: ["value", "values", "checked"] },
+  keyboard: { required: ["tabId", "keys"], optional: ["modifiers"] },
+  keyboard_type: { required: ["tabId", "text"], optional: ["mode", "delayMs"] },
+  run_js: { required: ["tabId", "code"], optional: [] },
+  port_forward: { required: ["workerPort"], optional: ["browserPort"] },
+  list_port_forwards: { required: [], optional: [] },
+  stop_port_forward: { required: ["forwardId"], optional: [] }
+};
+const MAX_VIEWPORT_DIMENSION = 4096;
+function parseViewportInput(input) {
+  if (input.reset !== void 0 && typeof input.reset !== "boolean") throw new Error("set_viewport reset must be a boolean.");
+  if (input.reset === true) {
+    if (input.width !== void 0 || input.height !== void 0)
+      throw new Error("set_viewport accepts width/height or reset: true, not both.");
+    return null;
+  }
+  const { width, height } = input;
+  for (const [name, value] of Object.entries({ width, height })) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > MAX_VIEWPORT_DIMENSION) {
+      throw new Error(
+        `set_viewport requires ${name} to be an integer from 1 to ${MAX_VIEWPORT_DIMENSION} CSS pixels, or reset: true without dimensions.`
+      );
+    }
+  }
+  return { width, height };
+}
+function normalizeBrowserInput(action, input) {
+  const fields = browserInputFields[action];
+  for (const key of fields.required) {
+    if (input[key] === null || input[key] === void 0) throw new Error(`${action} requires ${key}.`);
+  }
+  const normalized = { ...input };
+  for (const key of fields.optional) {
+    if (normalized[key] === null) delete normalized[key];
+  }
+  return normalized;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MAX_VIEWPORT_DIMENSION,
+  normalizeBrowserInput,
+  parseViewportInput
+});

package/dist/cjs/browser-runtime.cjs

@@ -33,6 +33,8 @@ __export(browser_runtime_exports, {
 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_password_safe_snapshot = require("./password-safe-snapshot.cjs");
 const MAX_DOWNLOAD_CHUNK_BYTES = 1024 * 1024;
 const MAX_RUN_JS_RESULT_BYTES = 1024 * 1024;
 const MAX_RUN_JS_ARTIFACT_BYTES = 4 * 1024 * 1024;
@@ -82,6 +84,7 @@ class BrowserRuntime {
   ids = /* @__PURE__ */ new WeakMap();
   pages = /* @__PURE__ */ new Map();
   cursor = /* @__PURE__ */ new Map();
+  viewportSessions = /* @__PURE__ */ new Map();
   downloadSaveQueue = Promise.resolve();
   track(page) {
     const existing = this.ids.get(page);
@@ -98,6 +101,7 @@ class BrowserRuntime {
     page.once("close", () => {
       this.pages.delete(id);
       this.cursor.delete(id);
+      this.viewportSessions.delete(id);
     });
     return id;
   }
@@ -233,7 +237,36 @@ class BrowserRuntime {
   async drainDownloads() {
     await this.downloadSaveQueue;
   }
+  async setViewport(page, tabId, viewport) {
+    const existing = this.viewportSessions.get(tabId);
+    if (viewport) {
+      const cdp = existing ?? await this.context.newCDPSession(page);
+      try {
+        await cdp.send("Emulation.setDeviceMetricsOverride", { ...viewport, deviceScaleFactor: 0, mobile: false });
+        this.viewportSessions.set(tabId, cdp);
+      } catch (error) {
+        if (!existing) await cdp.detach().catch(() => void 0);
+        throw error;
+      }
+    } else if (existing) {
+      await existing.send("Emulation.clearDeviceMetricsOverride");
+      this.viewportSessions.delete(tabId);
+      await existing.detach().catch(() => void 0);
+    }
+    this.cursor.delete(tabId);
+    if (viewport) {
+      const ready = await page.waitForFunction(
+        ({ width, height }) => window.innerWidth === width && window.innerHeight === height,
+        viewport,
+        { timeout: 5e3 }
+      );
+      await ready.dispose();
+    }
+    const actual = await page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }));
+    return { tabId, ...actual, reset: viewport === null };
+  }
   async execute(action, input) {
+    input = (0, import_browser_input.normalizeBrowserInput)(action, input);
     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);
@@ -272,18 +305,20 @@ class BrowserRuntime {
       case "navigate":
         await this.gotoSettled(page, String(input.url));
         return { tab: await this.tabInfo(page) };
+      case "set_viewport":
+        return await this.setViewport(page, tabId, (0, import_browser_input.parseViewportInput)(input));
       case "read_page": {
         const maxChars = clampInt(input.maxChars, 1e3, 2e5, 5e4);
         const depth = input.depth === void 0 ? void 0 : clampInt(input.depth, 1, 50, 50);
         const options = { mode: "ai", boxes: true, timeout: READ_PAGE_TIMEOUT_MS, ...depth === void 0 ? {} : { depth } };
         let snapshot;
         try {
-          snapshot = await page.ariaSnapshot(options);
+          snapshot = await (0, import_password_safe_snapshot.passwordSafeAriaSnapshot)(page, options);
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
           if (isDestroyedContext(message)) {
             await page.waitForLoadState("domcontentloaded", { timeout: 5e3 }).catch(() => void 0);
-            snapshot = await page.ariaSnapshot(options);
+            snapshot = await (0, import_password_safe_snapshot.passwordSafeAriaSnapshot)(page, options);
           } else if (/Timeout/i.test(message)) {
             throw new Error(
               `read_page timed out after ${READ_PAGE_TIMEOUT_MS}ms building the outline. The page is very large or busy; retry with a depth limit (e.g. depth: 10).`
@@ -311,13 +346,28 @@ class BrowserRuntime {
       case "screenshot": {
         if (input.fullPage === true) {
           const metrics = await page.evaluate(() => ({
-            docWidth: Math.max(document.documentElement.scrollWidth, window.innerWidth),
-            docHeight: Math.max(document.documentElement.scrollHeight, window.innerHeight)
+            // Match Playwright's full-page bounds, which exclude scrollbar gutters.
+            docWidth: Math.max(
+              document.documentElement.scrollWidth,
+              document.documentElement.offsetWidth,
+              document.documentElement.clientWidth,
+              document.body?.scrollWidth ?? 0,
+              document.body?.offsetWidth ?? 0,
+              document.body?.clientWidth ?? 0
+            ),
+            docHeight: Math.max(
+              document.documentElement.scrollHeight,
+              document.documentElement.offsetHeight,
+              document.documentElement.clientHeight,
+              document.body?.scrollHeight ?? 0,
+              document.body?.offsetHeight ?? 0,
+              document.body?.clientHeight ?? 0
+            )
           }));
           const width = Math.min(metrics.docWidth, MAX_FULL_PAGE_WIDTH);
           const height = Math.min(metrics.docHeight, MAX_FULL_PAGE_HEIGHT);
           const truncated = metrics.docHeight > MAX_FULL_PAGE_HEIGHT || metrics.docWidth > MAX_FULL_PAGE_WIDTH;
-          const bytes2 = truncated ? await page.screenshot({ type: "png", scale: "css", timeout: 15e3, clip: { x: 0, y: 0, width, height } }) : await page.screenshot({ type: "png", scale: "css", timeout: 15e3, fullPage: true });
+          const bytes2 = truncated ? await page.screenshot({ type: "png", scale: "css", timeout: 15e3, fullPage: true, clip: { x: 0, y: 0, width, height } }) : await page.screenshot({ type: "png", scale: "css", timeout: 15e3, fullPage: true });
           return { base64: bytes2.toString("base64"), width, height, fullPage: true, pageHeight: metrics.docHeight, truncated };
         }
         const bytes = await page.screenshot({ type: "png", scale: "css" });

package/dist/cjs/main.cjs

@@ -154,11 +154,13 @@ async function connectLoop(params) {
               portForwarding: true,
               runJsArtifacts: true,
               readPage: true,
+              passwordRedaction: true,
               refActions: true,
               waitFor: true,
               formInput: true,
               typedKeys: true,
-              screenshotFullPage: true
+              screenshotFullPage: true,
+              viewportSizing: true
             }
           },
           tabs: await params.runtime.listTabs(),

package/dist/cjs/package.json

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

package/dist/cjs/password-safe-snapshot.cjs

@@ -0,0 +1,150 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var password_safe_snapshot_exports = {};
+__export(password_safe_snapshot_exports, {
+  passwordSafeAriaSnapshot: () => passwordSafeAriaSnapshot
+});
+module.exports = __toCommonJS(password_safe_snapshot_exports);
+var import_node_module = require("node:module");
+const import_meta = {};
+const requirePlaywright = (0, import_node_module.createRequire)(typeof __filename === "string" ? __filename : import_meta.url);
+const SUPPORTED_PLAYWRIGHT_VERSION = "1.62.1";
+const DEFAULT_TIMEOUT_MS = 1e4;
+const UNAVAILABLE = "Password-safe browser snapshots are unavailable with this Playwright runtime. Update r5d-browser before retrying.";
+function isServerFrame(value) {
+  return !!value && typeof value.selectors?.callOnSelector === "function";
+}
+function captureInUtilityWorld({ elements, injected }, options) {
+  const root = elements[0];
+  const valueDescriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value");
+  const typeDescriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "type");
+  const attributeDescriptor = Object.getOwnPropertyDescriptor(Element.prototype, "getAttribute");
+  if (!root || typeof injected.ariaSnapshotWithRefs !== "function" || !valueDescriptor?.configurable || typeof valueDescriptor.get !== "function" || typeof typeDescriptor?.get !== "function" || !attributeDescriptor?.configurable || typeof attributeDescriptor.value !== "function") {
+    throw new Error("Password-safe snapshot utility APIs are unavailable.");
+  }
+  const readValue = valueDescriptor.get;
+  const readType = typeDescriptor.get;
+  const readAttribute = attributeDescriptor.value;
+  const isPassword = (element) => element instanceof HTMLInputElement && readType.call(element) === "password";
+  try {
+    Object.defineProperty(HTMLInputElement.prototype, "value", {
+      ...valueDescriptor,
+      get() {
+        const value = readValue.call(this);
+        return value && isPassword(this) ? "[redacted]" : value;
+      }
+    });
+    Object.defineProperty(Element.prototype, "getAttribute", {
+      ...attributeDescriptor,
+      value(name) {
+        const value = readAttribute.call(this, name);
+        return value && String(name).toLowerCase() === "value" && isPassword(this) ? "[redacted]" : value;
+      }
+    });
+    const snapshot = injected.ariaSnapshotWithRefs(root, options);
+    if (snapshot && typeof snapshot.then === "function") {
+      throw new Error("Password-safe snapshot generation must be synchronous.");
+    }
+    return snapshot;
+  } finally {
+    Object.defineProperty(Element.prototype, "getAttribute", attributeDescriptor);
+    Object.defineProperty(HTMLInputElement.prototype, "value", valueDescriptor);
+  }
+}
+function validateSnapshot(value) {
+  const snapshot = value;
+  if (!snapshot || typeof snapshot.text !== "string" || !Array.isArray(snapshot.iframeRefs) || !snapshot.iframeDepths || typeof snapshot.iframeDepths !== "object" || snapshot.iframeRefs.some((ref) => typeof ref !== "string" || !/^(f\d+)?e\d+$/.test(ref)) || Object.entries(snapshot.iframeDepths).some(([ref, depth]) => !/^(f\d+)?e\d+$/.test(ref) || !Number.isInteger(depth) || depth < 0)) {
+    throw new Error(UNAVAILABLE);
+  }
+}
+async function passwordSafeAriaSnapshot(page, options = {}) {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new Error("Password-safe snapshots require a finite positive timeout.");
+  let frame;
+  try {
+    if (requirePlaywright("playwright-core/package.json").version !== SUPPORTED_PLAYWRIGHT_VERSION) throw new Error(UNAVAILABLE);
+    const connection = page._connection;
+    if (typeof connection?.toImpl !== "function") throw new Error(UNAVAILABLE);
+    frame = connection.toImpl(page.mainFrame());
+  } catch {
+    throw new Error(UNAVAILABLE);
+  }
+  if (!isServerFrame(frame)) throw new Error(UNAVAILABLE);
+  const deadline = Date.now() + timeout;
+  const renderOptions = {
+    mode: "ai",
+    ...options.depth === void 0 ? {} : { depth: options.depth },
+    boxes: options.boxes
+  };
+  const timeoutError = () => new Error(`Timeout ${timeout}ms exceeded building a password-safe browser snapshot.`);
+  const bounded = async (operation) => {
+    let timer;
+    try {
+      return await Promise.race([
+        operation,
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(timeoutError()), Math.max(0, deadline - Date.now()));
+        })
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  const captureFrame = async (currentFrame, selector, frameOptions, isMainFrame = false) => {
+    if (!isServerFrame(currentFrame)) throw new Error(UNAVAILABLE);
+    if (Date.now() >= deadline) throw timeoutError();
+    const captured = await bounded(currentFrame.selectors.callOnSelector(selector, { strict: false }, captureInUtilityWorld, frameOptions));
+    if (!captured) {
+      if (!isMainFrame) return [];
+      await bounded(new Promise((resolve) => setTimeout(resolve, 50)));
+      return captureFrame(currentFrame, selector, frameOptions, true);
+    }
+    if (captured.info?.world !== "utility" || !isServerFrame(captured.frame)) throw new Error(UNAVAILABLE);
+    validateSnapshot(captured.result);
+    const snapshot = captured.result;
+    const renderedRefs = snapshot.iframeRefs.filter((ref) => Object.hasOwn(snapshot.iframeDepths, ref));
+    const children = /* @__PURE__ */ new Map();
+    await Promise.all(
+      renderedRefs.map(async (ref) => {
+        const childDepth = frameOptions.depth === void 0 ? void 0 : frameOptions.depth - snapshot.iframeDepths[ref] - 1;
+        if (childDepth !== void 0 && childDepth <= 0) return;
+        children.set(
+          ref,
+          await captureFrame(captured.frame, `aria-ref=${ref} >> internal:control=enter-frame >> body,frameset`, {
+            ...frameOptions,
+            ...childDepth === void 0 ? {} : { depth: childDepth }
+          })
+        );
+      })
+    );
+    const lines = [];
+    for (const line of snapshot.text.split("\n")) {
+      const match = line.match(/^(\s*)- iframe (?:\[active\] )?\[ref=([^\]]*)\]/);
+      const child = match ? children.get(match[2]) : void 0;
+      lines.push(child?.length ? `${line}:` : line);
+      if (match && child) lines.push(...child.map((childLine) => `${match[1]}  ${childLine}`));
+    }
+    return lines;
+  };
+  return (await captureFrame(frame, "body,frameset", renderOptions, true)).join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  passwordSafeAriaSnapshot
+});

package/dist/mjs/browser-input.mjs

@@ -0,0 +1,56 @@
+const browserInputFields = {
+  list_tabs: { required: [], optional: [] },
+  list_downloads: { required: [], optional: [] },
+  get_download: { required: ["downloadId"], optional: ["offset", "maxBytes"] },
+  open_tab: { required: [], optional: ["url", "disposition"] },
+  close_tab: { required: ["tabId"], optional: [] },
+  navigate: { required: ["tabId", "url"], optional: [] },
+  set_viewport: { required: ["tabId"], optional: ["width", "height", "reset"] },
+  read_page: { required: ["tabId"], optional: ["depth", "maxChars"] },
+  screenshot: { required: ["tabId"], optional: ["fullPage"] },
+  move_mouse: { required: ["tabId", "x", "y"], optional: [] },
+  mouse_click: { required: ["tabId"], optional: ["ref", "x", "y", "button", "clickCount"] },
+  scroll: { required: ["tabId"], optional: ["ref", "direction", "amount", "x", "y"] },
+  wait_for: { required: ["tabId"], optional: ["selector", "text", "url", "loadState", "state", "timeoutMs"] },
+  form_input: { required: ["tabId", "ref"], optional: ["value", "values", "checked"] },
+  keyboard: { required: ["tabId", "keys"], optional: ["modifiers"] },
+  keyboard_type: { required: ["tabId", "text"], optional: ["mode", "delayMs"] },
+  run_js: { required: ["tabId", "code"], optional: [] },
+  port_forward: { required: ["workerPort"], optional: ["browserPort"] },
+  list_port_forwards: { required: [], optional: [] },
+  stop_port_forward: { required: ["forwardId"], optional: [] }
+};
+const MAX_VIEWPORT_DIMENSION = 4096;
+function parseViewportInput(input) {
+  if (input.reset !== void 0 && typeof input.reset !== "boolean") throw new Error("set_viewport reset must be a boolean.");
+  if (input.reset === true) {
+    if (input.width !== void 0 || input.height !== void 0)
+      throw new Error("set_viewport accepts width/height or reset: true, not both.");
+    return null;
+  }
+  const { width, height } = input;
+  for (const [name, value] of Object.entries({ width, height })) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > MAX_VIEWPORT_DIMENSION) {
+      throw new Error(
+        `set_viewport requires ${name} to be an integer from 1 to ${MAX_VIEWPORT_DIMENSION} CSS pixels, or reset: true without dimensions.`
+      );
+    }
+  }
+  return { width, height };
+}
+function normalizeBrowserInput(action, input) {
+  const fields = browserInputFields[action];
+  for (const key of fields.required) {
+    if (input[key] === null || input[key] === void 0) throw new Error(`${action} requires ${key}.`);
+  }
+  const normalized = { ...input };
+  for (const key of fields.optional) {
+    if (normalized[key] === null) delete normalized[key];
+  }
+  return normalized;
+}
+export {
+  MAX_VIEWPORT_DIMENSION,
+  normalizeBrowserInput,
+  parseViewportInput
+};

package/dist/mjs/browser-runtime.mjs

@@ -1,5 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
+import { normalizeBrowserInput, parseViewportInput } from "./browser-input.mjs";
+import { passwordSafeAriaSnapshot } from "./password-safe-snapshot.mjs";
 const MAX_DOWNLOAD_CHUNK_BYTES = 1024 * 1024;
 const MAX_RUN_JS_RESULT_BYTES = 1024 * 1024;
 const MAX_RUN_JS_ARTIFACT_BYTES = 4 * 1024 * 1024;
@@ -49,6 +51,7 @@ class BrowserRuntime {
   ids = /* @__PURE__ */ new WeakMap();
   pages = /* @__PURE__ */ new Map();
   cursor = /* @__PURE__ */ new Map();
+  viewportSessions = /* @__PURE__ */ new Map();
   downloadSaveQueue = Promise.resolve();
   track(page) {
     const existing = this.ids.get(page);
@@ -65,6 +68,7 @@ class BrowserRuntime {
     page.once("close", () => {
       this.pages.delete(id);
       this.cursor.delete(id);
+      this.viewportSessions.delete(id);
     });
     return id;
   }
@@ -200,7 +204,36 @@ class BrowserRuntime {
   async drainDownloads() {
     await this.downloadSaveQueue;
   }
+  async setViewport(page, tabId, viewport) {
+    const existing = this.viewportSessions.get(tabId);
+    if (viewport) {
+      const cdp = existing ?? await this.context.newCDPSession(page);
+      try {
+        await cdp.send("Emulation.setDeviceMetricsOverride", { ...viewport, deviceScaleFactor: 0, mobile: false });
+        this.viewportSessions.set(tabId, cdp);
+      } catch (error) {
+        if (!existing) await cdp.detach().catch(() => void 0);
+        throw error;
+      }
+    } else if (existing) {
+      await existing.send("Emulation.clearDeviceMetricsOverride");
+      this.viewportSessions.delete(tabId);
+      await existing.detach().catch(() => void 0);
+    }
+    this.cursor.delete(tabId);
+    if (viewport) {
+      const ready = await page.waitForFunction(
+        ({ width, height }) => window.innerWidth === width && window.innerHeight === height,
+        viewport,
+        { timeout: 5e3 }
+      );
+      await ready.dispose();
+    }
+    const actual = await page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }));
+    return { tabId, ...actual, reset: viewport === null };
+  }
   async execute(action, input) {
+    input = normalizeBrowserInput(action, input);
     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);
@@ -239,18 +272,20 @@ class BrowserRuntime {
       case "navigate":
         await this.gotoSettled(page, String(input.url));
         return { tab: await this.tabInfo(page) };
+      case "set_viewport":
+        return await this.setViewport(page, tabId, parseViewportInput(input));
       case "read_page": {
         const maxChars = clampInt(input.maxChars, 1e3, 2e5, 5e4);
         const depth = input.depth === void 0 ? void 0 : clampInt(input.depth, 1, 50, 50);
         const options = { mode: "ai", boxes: true, timeout: READ_PAGE_TIMEOUT_MS, ...depth === void 0 ? {} : { depth } };
         let snapshot;
         try {
-          snapshot = await page.ariaSnapshot(options);
+          snapshot = await passwordSafeAriaSnapshot(page, options);
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
           if (isDestroyedContext(message)) {
             await page.waitForLoadState("domcontentloaded", { timeout: 5e3 }).catch(() => void 0);
-            snapshot = await page.ariaSnapshot(options);
+            snapshot = await passwordSafeAriaSnapshot(page, options);
           } else if (/Timeout/i.test(message)) {
             throw new Error(
               `read_page timed out after ${READ_PAGE_TIMEOUT_MS}ms building the outline. The page is very large or busy; retry with a depth limit (e.g. depth: 10).`
@@ -278,13 +313,28 @@ class BrowserRuntime {
       case "screenshot": {
         if (input.fullPage === true) {
           const metrics = await page.evaluate(() => ({
-            docWidth: Math.max(document.documentElement.scrollWidth, window.innerWidth),
-            docHeight: Math.max(document.documentElement.scrollHeight, window.innerHeight)
+            // Match Playwright's full-page bounds, which exclude scrollbar gutters.
+            docWidth: Math.max(
+              document.documentElement.scrollWidth,
+              document.documentElement.offsetWidth,
+              document.documentElement.clientWidth,
+              document.body?.scrollWidth ?? 0,
+              document.body?.offsetWidth ?? 0,
+              document.body?.clientWidth ?? 0
+            ),
+            docHeight: Math.max(
+              document.documentElement.scrollHeight,
+              document.documentElement.offsetHeight,
+              document.documentElement.clientHeight,
+              document.body?.scrollHeight ?? 0,
+              document.body?.offsetHeight ?? 0,
+              document.body?.clientHeight ?? 0
+            )
           }));
           const width = Math.min(metrics.docWidth, MAX_FULL_PAGE_WIDTH);
           const height = Math.min(metrics.docHeight, MAX_FULL_PAGE_HEIGHT);
           const truncated = metrics.docHeight > MAX_FULL_PAGE_HEIGHT || metrics.docWidth > MAX_FULL_PAGE_WIDTH;
-          const bytes2 = truncated ? await page.screenshot({ type: "png", scale: "css", timeout: 15e3, clip: { x: 0, y: 0, width, height } }) : await page.screenshot({ type: "png", scale: "css", timeout: 15e3, fullPage: true });
+          const bytes2 = truncated ? await page.screenshot({ type: "png", scale: "css", timeout: 15e3, fullPage: true, clip: { x: 0, y: 0, width, height } }) : await page.screenshot({ type: "png", scale: "css", timeout: 15e3, fullPage: true });
           return { base64: bytes2.toString("base64"), width, height, fullPage: true, pageHeight: metrics.docHeight, truncated };
         }
         const bytes = await page.screenshot({ type: "png", scale: "css" });

package/dist/mjs/main.mjs

@@ -131,11 +131,13 @@ async function connectLoop(params) {
               portForwarding: true,
               runJsArtifacts: true,
               readPage: true,
+              passwordRedaction: true,
               refActions: true,
               waitFor: true,
               formInput: true,
               typedKeys: true,
-              screenshotFullPage: true
+              screenshotFullPage: true,
+              viewportSizing: true
             }
           },
           tabs: await params.runtime.listTabs(),

package/dist/mjs/package.json

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

package/dist/mjs/password-safe-snapshot.mjs

@@ -0,0 +1,125 @@
+import { createRequire } from "node:module";
+const requirePlaywright = createRequire(typeof __filename === "string" ? __filename : import.meta.url);
+const SUPPORTED_PLAYWRIGHT_VERSION = "1.62.1";
+const DEFAULT_TIMEOUT_MS = 1e4;
+const UNAVAILABLE = "Password-safe browser snapshots are unavailable with this Playwright runtime. Update r5d-browser before retrying.";
+function isServerFrame(value) {
+  return !!value && typeof value.selectors?.callOnSelector === "function";
+}
+function captureInUtilityWorld({ elements, injected }, options) {
+  const root = elements[0];
+  const valueDescriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value");
+  const typeDescriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "type");
+  const attributeDescriptor = Object.getOwnPropertyDescriptor(Element.prototype, "getAttribute");
+  if (!root || typeof injected.ariaSnapshotWithRefs !== "function" || !valueDescriptor?.configurable || typeof valueDescriptor.get !== "function" || typeof typeDescriptor?.get !== "function" || !attributeDescriptor?.configurable || typeof attributeDescriptor.value !== "function") {
+    throw new Error("Password-safe snapshot utility APIs are unavailable.");
+  }
+  const readValue = valueDescriptor.get;
+  const readType = typeDescriptor.get;
+  const readAttribute = attributeDescriptor.value;
+  const isPassword = (element) => element instanceof HTMLInputElement && readType.call(element) === "password";
+  try {
+    Object.defineProperty(HTMLInputElement.prototype, "value", {
+      ...valueDescriptor,
+      get() {
+        const value = readValue.call(this);
+        return value && isPassword(this) ? "[redacted]" : value;
+      }
+    });
+    Object.defineProperty(Element.prototype, "getAttribute", {
+      ...attributeDescriptor,
+      value(name) {
+        const value = readAttribute.call(this, name);
+        return value && String(name).toLowerCase() === "value" && isPassword(this) ? "[redacted]" : value;
+      }
+    });
+    const snapshot = injected.ariaSnapshotWithRefs(root, options);
+    if (snapshot && typeof snapshot.then === "function") {
+      throw new Error("Password-safe snapshot generation must be synchronous.");
+    }
+    return snapshot;
+  } finally {
+    Object.defineProperty(Element.prototype, "getAttribute", attributeDescriptor);
+    Object.defineProperty(HTMLInputElement.prototype, "value", valueDescriptor);
+  }
+}
+function validateSnapshot(value) {
+  const snapshot = value;
+  if (!snapshot || typeof snapshot.text !== "string" || !Array.isArray(snapshot.iframeRefs) || !snapshot.iframeDepths || typeof snapshot.iframeDepths !== "object" || snapshot.iframeRefs.some((ref) => typeof ref !== "string" || !/^(f\d+)?e\d+$/.test(ref)) || Object.entries(snapshot.iframeDepths).some(([ref, depth]) => !/^(f\d+)?e\d+$/.test(ref) || !Number.isInteger(depth) || depth < 0)) {
+    throw new Error(UNAVAILABLE);
+  }
+}
+async function passwordSafeAriaSnapshot(page, options = {}) {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new Error("Password-safe snapshots require a finite positive timeout.");
+  let frame;
+  try {
+    if (requirePlaywright("playwright-core/package.json").version !== SUPPORTED_PLAYWRIGHT_VERSION) throw new Error(UNAVAILABLE);
+    const connection = page._connection;
+    if (typeof connection?.toImpl !== "function") throw new Error(UNAVAILABLE);
+    frame = connection.toImpl(page.mainFrame());
+  } catch {
+    throw new Error(UNAVAILABLE);
+  }
+  if (!isServerFrame(frame)) throw new Error(UNAVAILABLE);
+  const deadline = Date.now() + timeout;
+  const renderOptions = {
+    mode: "ai",
+    ...options.depth === void 0 ? {} : { depth: options.depth },
+    boxes: options.boxes
+  };
+  const timeoutError = () => new Error(`Timeout ${timeout}ms exceeded building a password-safe browser snapshot.`);
+  const bounded = async (operation) => {
+    let timer;
+    try {
+      return await Promise.race([
+        operation,
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(timeoutError()), Math.max(0, deadline - Date.now()));
+        })
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  const captureFrame = async (currentFrame, selector, frameOptions, isMainFrame = false) => {
+    if (!isServerFrame(currentFrame)) throw new Error(UNAVAILABLE);
+    if (Date.now() >= deadline) throw timeoutError();
+    const captured = await bounded(currentFrame.selectors.callOnSelector(selector, { strict: false }, captureInUtilityWorld, frameOptions));
+    if (!captured) {
+      if (!isMainFrame) return [];
+      await bounded(new Promise((resolve) => setTimeout(resolve, 50)));
+      return captureFrame(currentFrame, selector, frameOptions, true);
+    }
+    if (captured.info?.world !== "utility" || !isServerFrame(captured.frame)) throw new Error(UNAVAILABLE);
+    validateSnapshot(captured.result);
+    const snapshot = captured.result;
+    const renderedRefs = snapshot.iframeRefs.filter((ref) => Object.hasOwn(snapshot.iframeDepths, ref));
+    const children = /* @__PURE__ */ new Map();
+    await Promise.all(
+      renderedRefs.map(async (ref) => {
+        const childDepth = frameOptions.depth === void 0 ? void 0 : frameOptions.depth - snapshot.iframeDepths[ref] - 1;
+        if (childDepth !== void 0 && childDepth <= 0) return;
+        children.set(
+          ref,
+          await captureFrame(captured.frame, `aria-ref=${ref} >> internal:control=enter-frame >> body,frameset`, {
+            ...frameOptions,
+            ...childDepth === void 0 ? {} : { depth: childDepth }
+          })
+        );
+      })
+    );
+    const lines = [];
+    for (const line of snapshot.text.split("\n")) {
+      const match = line.match(/^(\s*)- iframe (?:\[active\] )?\[ref=([^\]]*)\]/);
+      const child = match ? children.get(match[2]) : void 0;
+      lines.push(child?.length ? `${line}:` : line);
+      if (match && child) lines.push(...child.map((childLine) => `${match[1]}  ${childLine}`));
+    }
+    return lines;
+  };
+  return (await captureFrame(frame, "body,frameset", renderOptions, true)).join("\n");
+}
+export {
+  passwordSafeAriaSnapshot
+};

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

@@ -0,0 +1,91 @@
+declare const browserInputFields: {
+    list_tabs: {
+        required: never[];
+        optional: never[];
+    };
+    list_downloads: {
+        required: never[];
+        optional: never[];
+    };
+    get_download: {
+        required: string[];
+        optional: string[];
+    };
+    open_tab: {
+        required: never[];
+        optional: string[];
+    };
+    close_tab: {
+        required: string[];
+        optional: never[];
+    };
+    navigate: {
+        required: string[];
+        optional: never[];
+    };
+    set_viewport: {
+        required: string[];
+        optional: string[];
+    };
+    read_page: {
+        required: string[];
+        optional: string[];
+    };
+    screenshot: {
+        required: string[];
+        optional: string[];
+    };
+    move_mouse: {
+        required: string[];
+        optional: never[];
+    };
+    mouse_click: {
+        required: string[];
+        optional: string[];
+    };
+    scroll: {
+        required: string[];
+        optional: string[];
+    };
+    wait_for: {
+        required: string[];
+        optional: string[];
+    };
+    form_input: {
+        required: string[];
+        optional: string[];
+    };
+    keyboard: {
+        required: string[];
+        optional: string[];
+    };
+    keyboard_type: {
+        required: string[];
+        optional: string[];
+    };
+    run_js: {
+        required: string[];
+        optional: never[];
+    };
+    port_forward: {
+        required: string[];
+        optional: string[];
+    };
+    list_port_forwards: {
+        required: never[];
+        optional: never[];
+    };
+    stop_port_forward: {
+        required: string[];
+        optional: never[];
+    };
+};
+export type BrowserInputAction = keyof typeof browserInputFields;
+export declare const MAX_VIEWPORT_DIMENSION = 4096;
+export type BrowserViewport = {
+    width: number;
+    height: number;
+};
+export declare function parseViewportInput(input: Readonly<Record<string, unknown>>): BrowserViewport | null;
+export declare function normalizeBrowserInput(action: BrowserInputAction, input: Readonly<Record<string, unknown>>): Record<string, unknown>;
+export {};

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" | "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";
 export type TabInfo = {
     tabId: string;
     windowId: string;
@@ -18,6 +18,7 @@ export declare class BrowserRuntime {
     private readonly ids;
     private readonly pages;
     private readonly cursor;
+    private readonly viewportSessions;
     private downloadSaveQueue;
     constructor(context: BrowserContext, downloadsPath: string);
     private track;
@@ -34,5 +35,6 @@ export declare class BrowserRuntime {
     private tabInfo;
     listTabs(): Promise<TabInfo[]>;
     drainDownloads(): Promise<void>;
+    private setViewport;
     execute(action: BrowserAction, input: Record<string, unknown>): Promise<unknown>;
 }

package/dist/types/password-safe-snapshot.d.ts

@@ -0,0 +1,15 @@
+import type { Page } from "playwright-core";
+export type PasswordSafeSnapshotOptions = {
+    mode?: "ai";
+    depth?: number;
+    boxes?: boolean;
+    timeout?: number;
+};
+/**
+ * Playwright 1.62.1 has no public snapshot redaction hook. This deliberately narrow
+ * adapter uses its in-process server Frame and the same utility-world selector,
+ * ref generation, and iframe stitching as ariaSnapshotForFrame in coreBundle.js.
+ * The exact version and private API shapes are checked; failure never falls back
+ * to page.ariaSnapshot(), which exposes password values in this pinned version.
+ */
+export declare function passwordSafeAriaSnapshot(page: Page, options?: PasswordSafeSnapshotOptions): Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-browser",
-  "version": "0.0.113",
+  "version": "0.0.115",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",