@ricsam/r5d-browser 0.0.114 → 0.0.115

package/README.md

@@ -28,6 +28,10 @@ Agents read pages through `browser_read_page`, an accessibility outline with sta
 
 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

@@ -18,7 +18,9 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var browser_input_exports = {};
 __export(browser_input_exports, {
-  normalizeBrowserInput: () => normalizeBrowserInput
+  MAX_VIEWPORT_DIMENSION: () => MAX_VIEWPORT_DIMENSION,
+  normalizeBrowserInput: () => normalizeBrowserInput,
+  parseViewportInput: () => parseViewportInput
 });
 module.exports = __toCommonJS(browser_input_exports);
 const browserInputFields = {
@@ -28,6 +30,7 @@ const browserInputFields = {
   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: [] },
@@ -42,6 +45,24 @@ const browserInputFields = {
   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) {
@@ -55,5 +76,7 @@ function normalizeBrowserInput(action, input) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  normalizeBrowserInput
+  MAX_VIEWPORT_DIMENSION,
+  normalizeBrowserInput,
+  parseViewportInput
 });

package/dist/cjs/browser-runtime.cjs

@@ -84,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);
@@ -100,6 +101,7 @@ class BrowserRuntime {
     page.once("close", () => {
       this.pages.delete(id);
       this.cursor.delete(id);
+      this.viewportSessions.delete(id);
     });
     return id;
   }
@@ -235,6 +237,34 @@ 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() };
@@ -275,6 +305,8 @@ 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);
@@ -314,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

@@ -159,7 +159,8 @@ async function connectLoop(params) {
               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.114",
+  "version": "0.0.115",
   "type": "commonjs"
 }

package/dist/mjs/browser-input.mjs

@@ -5,6 +5,7 @@ const browserInputFields = {
   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: [] },
@@ -19,6 +20,24 @@ const browserInputFields = {
   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) {
@@ -31,5 +50,7 @@ function normalizeBrowserInput(action, input) {
   return normalized;
 }
 export {
-  normalizeBrowserInput
+  MAX_VIEWPORT_DIMENSION,
+  normalizeBrowserInput,
+  parseViewportInput
 };

package/dist/mjs/browser-runtime.mjs

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { normalizeBrowserInput } from "./browser-input.mjs";
+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;
@@ -51,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);
@@ -67,6 +68,7 @@ class BrowserRuntime {
     page.once("close", () => {
       this.pages.delete(id);
       this.cursor.delete(id);
+      this.viewportSessions.delete(id);
     });
     return id;
   }
@@ -202,6 +204,34 @@ 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() };
@@ -242,6 +272,8 @@ 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);
@@ -281,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

@@ -136,7 +136,8 @@ async function connectLoop(params) {
               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.114",
+  "version": "0.0.115",
   "type": "module"
 }

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

@@ -23,6 +23,10 @@ declare const browserInputFields: {
         required: string[];
         optional: never[];
     };
+    set_viewport: {
+        required: string[];
+        optional: string[];
+    };
     read_page: {
         required: string[];
         optional: string[];
@@ -77,5 +81,11 @@ declare const browserInputFields: {
     };
 };
 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/package.json

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