@bytesbrains/pi-textbrowser 1.1.0

package/AGENTS.md

@@ -0,0 +1,151 @@
+# TextBrowser — Agent Usage Guide
+
+> You are an AI agent. This document helps you use the TextBrowser extension effectively.
+
+## Available Tools
+
+| Tool | Purpose | When to use |
+|---|---|---|
+| `browser_navigate` | Open a URL, return page context | First visit to a site or explicit navigation |
+| `browser_click` | Click an element by CSS, XPath, or text | Interact with links, buttons, form elements |
+| `browser_type` | Type text into an input field | Fill forms, search boxes, login fields |
+| `browser_scroll` | Scroll the page or an element into view | Explore long pages, find off-screen content |
+| `browser_screenshot` | Capture current page + OCR text | Re-read page without changing anything |
+| `browser_read` | Get current page context (no action) | Check if page state changed after an action |
+| `browser_evaluate` | Execute arbitrary JavaScript | **Escape hatch** for shadow DOM, complex interactions |
+
+## Dual-Mode Design: When to Use Visual vs Text-Only
+
+> ⚠️ **DEFAULT: Always use text-only mode first.** Only switch to visual mode when the task explicitly requires seeing pixels.
+
+### Decision Framework
+
+Ask yourself: *"Does this task require seeing colors, positions, or images?"*
+
+#### ✅ Text-Only Mode (`visual: false` or omit) — Use for:
+
+| Category | Examples | Why text works |
+|---|---|---|
+| **Navigation** | Open a URL, find a link, click a button | DOM elements + OCR reveal all interactive items |
+| **Form filling** | Login, search, type into inputs | CSS selectors + text labels identify fields |
+| **Data extraction** | Scrape a table, read article text | OCR + DOM textContent capture all visible text |
+| **Workflow automation** | Multi-step process (login → search → click) | Text elements + OCR track state changes |
+| **API/Admin panels** | Gitea, Firebase Console, GitHub | Structured UI labels are fully readable via text |
+| **Code review** | Read docs, explore repos | Content is textual by nature |
+
+#### 🖼️ Visual Mode (`visual: true`) — Use ONLY for:
+
+| Category | Examples | Why images are needed |
+|---|---|---|
+| **Layout verification** | "Does the button align with the header?" "Is the sidebar overlapping?" | Pixel positions matter |
+| **Color/theme checks** | "Is the dark mode working?" "Does this component match the brand color?" | Colors are invisible in text |
+| **Visual regression** | "Compare before/after screenshots of this component" | Diffing pixels |
+| **Image content** | "What does this dashboard chart show?" "Read the text in this logo" | Images are non-text |
+| **UI design review** | "Does the spacing look right?" "Is the font readable?" | Visual aesthetics |
+| **Debugging rendering** | "Why is this element invisible?" "Check if CSS is loading" | CSS bugs invisible to OCR |
+
+#### 🎯 Quick Reference
+
+```
+User says: "Open Gitea and explore repos"        → text-only ✅
+User says: "Login to LinkedIn and post"           → text-only ✅
+User says: "Check if the dark mode looks correct" → visual 🖼️
+User says: "Is the button centered on the page?"  → visual 🖼️
+User says: "Read the article content"             → text-only ✅
+User says: "Compare this page to the mockup"      → visual 🖼️
+```
+
+### Cost Comparison
+
+| Mode | Avg Tokens | Relative Cost | When |
+|---|---|---|---|
+| Text-only | ~200-400 | **1x** | Default — 90% of tasks |
+| Visual | ~1,500-3,000 | **5-15x** | Only when pixels matter |
+
+### Escalation Path
+
+If text-only mode provides insufficient information for the task, **state why** and escalate:
+
+> *"I can see the login form (elements [22]-[33]) but need to verify the button color matches the brand palette. Let me switch to visual mode."*
+
+Don't silently switch to visual — explain the rationale. This helps users understand token costs and keeps you accountable.
+
+## Session Persistence
+
+The browser maintains one Playwright Chromium instance per Pi session. All tools share the same page, cookies, and state. This means:
+
+- ✅ After `browser_navigate`, `browser_click` and `browser_type` work on the same page
+- ✅ Login sessions persist across tool calls
+- ⚠️ `browser_navigate` reloads the page — LinkedIn/GitHub may kill sessions
+
+## Best Practices
+
+> **⚠️ CRITICAL: Prefer `browser_read` + `browser_click` over `browser_navigate`.**
+> Every `browser_navigate` triggers a full page load, destroying login sessions and current state.
+> Once you're on a site, stay there. Use read/click/type/scroll to move around.
+> Only use `browser_navigate` when you genuinely need a completely different URL domain.
+>
+> **⚠️ COST: Default to text-only mode.** Visual mode burns 5-15× more tokens.
+> Use `visual: true` ONLY for layout, colors, design review, or image-content tasks.
+> If text-only is insufficient, explain why before switching.
+
+### Rule 1: Navigate once, then read & click
+```
+browser_navigate(url="https://example.com")   ← open the page
+browser_read()                                  ← check what's there
+browser_click(text="Sign In")                   ← interact
+browser_type(selector="#email", text="user")    ← fill form
+```
+
+Avoid `browser_navigate` after logging in — it destroys the session.
+
+### Rule 2: Use `headless: false` for visible browsing
+The user can see and interact with a visible browser window. After opening with `headless: false`, all subsequent tools inherit this setting — the window stays open.
+
+### Rule 3: Use element indices for precision
+The page context returns elements with `[index]` markers. Refer to: `"click element [15] (the Sign In button)"`
+
+### Rule 4: `browser_evaluate` is your shadow DOM escape hatch
+When elements live inside shadow DOM (LinkedIn, some React apps), standard clicks fail. Use `browser_evaluate` to query and interact through `el.shadowRoot`:
+
+```js
+// Find and click a button inside shadow DOM
+const el = document.querySelector('#host').shadowRoot.querySelector('button');
+el.click();
+```
+
+### Rule 5: Wait after actions
+After clicking, the page may need time to load. Use `browser_read` to confirm the new state before the next action.
+
+## Common Patterns
+
+### Form login
+```
+browser_navigate(url="https://site.com/login", headless=false)
+browser_type(selector="#username", text="user")
+browser_type(selector="#password", text="pass")
+browser_click(selector="button[type='submit']")
+browser_read()  ← verify logged in
+```
+
+### Explore with filters
+```
+browser_navigate(url="https://site.com/search")
+browser_type(selector="input[placeholder='Search']", text="query")
+browser_click(text="Search")
+browser_scroll(direction="down", amount=500)
+browser_read()
+```
+
+### Extract data via JS
+```
+browser_evaluate(script="Array.from(document.querySelectorAll('.item')).map(el => el.textContent)")
+```
+
+## Known Limitations
+
+- **Shadow DOM**: LinkedIn, Salesforce, and some SPA frameworks use shadow DOM that blocks standard clicks. Use `browser_evaluate`.
+- **Login sessions**: Some sites (LinkedIn) aggressively expire sessions when navigating. Log in once, then use read/click only.
+- **Captchas / 2FA**: Cannot bypass security checks. Ask the user to complete them in the visible browser window.
+- **File downloads**: Not supported. Use `browser_evaluate` to extract data as text.
+- **OCR accuracy**: Tesseract OCR depends on screenshot quality. Complex layouts, small fonts, or low-contrast text may produce garbled results. When OCR is unreliable, rely on DOM elements instead.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nandal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# TextBrowser for Pi
+
+[![npm version](https://img.shields.io/npm/v/pi-textbrowser)](https://www.npmjs.com/package/pi-textbrowser)
+[![license](https://img.shields.io/npm/l/pi-textbrowser)](./LICENSE)
+
+> Headless browser extension for Pi — browse the web with **structured DOM + OCR text maps**. **10-50x cheaper** than screenshot-based browsing.
+
+```
+┌─────────────┐     browser_navigate(url)     ┌─────────────┐
+│   Pi Agent  │ ─────────────────────────────>│  Playwright │
+│  (you)      │                               │   Chromium  │
+│             │ <─ DOM + OCR text map ────────│             │
+└─────────────┘        (~200 tokens)          └─────────────┘
+```
+
+## Why TextBrowser?
+
+| Approach | ~Tokens | Relative Cost |
+|---|---|---|
+| PNG 1920×1080 (vision model) | ~1,500–3,000 | 100% |
+| **TextBrowser (text-only)** | **~150–400** | **5–15%** |
+
+Vision-model screenshots burn thousands of tokens per page. TextBrowser captures the **DOM structure** + runs **OCR** on a screenshot, then **discards the image**. Only clean, structured text reaches the AI. You get element lists, bounding boxes, visible text, and OCR content — all for a fraction of the cost.
+
+Need to see colors or layout? Flip to **visual mode** and get the PNG too.
+
+## Install
+
+```bash
+pi install npm:pi-textbrowser
+npx playwright install chromium
+```
+
+Or add to your `.pi/settings.json`:
+
+```json
+{
+  "packages": ["npm:pi-textbrowser"]
+}
+```
+
+> **Note:** The Playwright Chromium binary is a one-time install.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `browser_navigate` | Open a URL, return page context |
+| `browser_click` | Click by selector / text / XPath |
+| `browser_type` | Fill input fields |
+| `browser_scroll` | Scroll page or element into view |
+| `browser_screenshot` | Capture current page context |
+| `browser_read` | Read current page without changing it |
+| `browser_evaluate` | Run JavaScript in the page |
+
+## Dual-Mode Design
+
+### Text-only mode (default) — use for 90% of tasks
+
+```
+browser_navigate(url="https://example.com")
+```
+
+- Screenshot captured **only for OCR** → image discarded
+- Returns: structured DOM elements + OCR text
+- **Zero image tokens** reach the AI
+- **5-15× cheaper** than visual mode
+
+**Use when**: navigating, form filling, data extraction, workflow automation, reading content
+
+### Visual mode — use ONLY for pixels, colors, layout
+
+```
+browser_navigate(url="https://example.com", visual=true)
+```
+
+- Screenshot captured for OCR **and** returned as base64 PNG
+- Returns: text map + actual image
+- **5-15× more tokens** than text-only
+
+**Use ONLY when**: checking layout alignment, verifying color/theme, debugging CSS, reviewing design, reading image content
+
+### When to use which
+
+| Task | Mode |
+|---|---|
+| "Open Gitea and explore repos" | Text-only ✅ |
+| "Login to LinkedIn and post" | Text-only ✅ |
+| "Check if dark mode looks correct" | Visual 🖼️ |
+| "Is the button centered on the page?" | Visual 🖼️ |
+| "Read the article content" | Text-only ✅ |
+| "Compare this page to the mockup" | Visual 🖼️ |
+
+## Example Session
+
+```
+You: Open https://example.com and explore the page
+
+→ browser_navigate(url="https://example.com")
+
+Page: https://example.com/
+Title: Example Domain
+Viewport: 1920x1080
+
+Elements (14 interactive of 82 total):
+  [3] <a> href="https://iana.org/domains/example" text="More information..."
+  ...
+
+OCR (full page screenshot):
+Example Domain
+This domain is for use in illustrative examples in documents.
+...
+```
+
+## Requirements
+
+- Node.js 18+
+- Pi coding agent installed
+- Playwright Chromium: `npx playwright install chromium`
+
+## License
+
+MIT © [nandal](https://github.com/nandal)
+
+---
+
+*Built by Agent, for Agents 🤖*

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@bytesbrains/pi-textbrowser",
+  "version": "1.1.0",
+  "description": "Headless browser for Pi — browse the web with DOM + OCR text maps. No image tokens, 10-50x cheaper than screenshot-based browsing.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "browser",
+    "automation",
+    "playwright",
+    "ocr",
+    "tesseract",
+    "web-scraping"
+  ],
+  "author": "nandal <nandal@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nandal/pi-ext",
+    "directory": "textbrowser"
+  },
+  "homepage": "https://github.com/nandal/pi-ext/tree/main/textbrowser",
+  "bugs": {
+    "url": "https://github.com/nandal/pi-ext/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "playwright": "^1.50.0",
+    "tesseract.js": "^6.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/nandal/pi-ext/main/textbrowser/screenshot.png"
+  }
+}

package/src/index.ts

@@ -0,0 +1,394 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Page, Browser, BrowserContext } from "playwright";
+
+// ── Module-level browser state (one instance per Pi session) ──
+
+let browser: Browser | null = null;
+let context: BrowserContext | null = null;
+let page: Page | null = null;
+let ocrWorker: any = null;
+let currentHeadless = false;
+
+async function getPage(headless?: boolean): Promise<Page> {
+  headless = headless ?? currentHeadless;
+  if (!page || headless !== currentHeadless) {
+    if (browser) {
+      try { await browser.close(); } catch { /* ignore */ }
+    }
+    currentHeadless = headless;
+    const { chromium } = await import("playwright");
+    browser = await chromium.launch({ headless });
+    context = await browser.newContext({
+      viewport: { width: 1280, height: 800 },
+      userAgent:
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    });
+    page = await context.newPage();
+  }
+  return page;
+}
+
+async function closeBrowser(): Promise<void> {
+  if (ocrWorker) {
+    try { await ocrWorker.terminate(); } catch { /* ignore */ }
+    ocrWorker = null;
+  }
+  if (browser) {
+    try { await browser.close(); } catch { /* ignore */ }
+    browser = null;
+    context = null;
+    page = null;
+  }
+}
+
+// ── OCR helper ──
+
+async function getOcrWorker(): Promise<any | null> {
+  if (ocrWorker) return ocrWorker;
+  try {
+    const { createWorker } = await import("tesseract.js");
+    ocrWorker = await createWorker("eng");
+    return ocrWorker;
+  } catch {
+    return null;
+  }
+}
+
+async function runOcr(buffer: Buffer): Promise<string> {
+  const worker = await getOcrWorker();
+  if (!worker) return "(OCR unavailable — install tesseract.js)";
+  const { data: { text } } = await worker.recognize(buffer);
+  return text.trim() || "(no text detected)";
+}
+
+// ── Page map generator ──
+
+interface ElementInfo {
+  index: number;
+  tag: string;
+  text?: string;
+  attributes: Record<string, string>;
+  bbox: { x: number; y: number; width: number; height: number } | null;
+}
+
+/**
+ * Generate a structured text map of the page.
+ *
+ * Modes:
+ *   text-only (default): screenshot is captured → OCR runs → image is DISCARDED.
+ *                        Only DOM + OCR text is returned. Zero image tokens.
+ *   visual:              screenshot is captured → OCR text + base64 PNG image
+ *                        are both returned. Useful when layout/colors matter.
+ */
+async function generatePageMap(p: Page, visual = false): Promise<{ text: string; image?: string }> {
+  const url = p.url();
+  const title = await p.title().catch(() => "(no title)");
+  const viewport = p.viewportSize() ?? { width: 1920, height: 1080 };
+
+  // Extract interactive / visible elements with bounding boxes (traverses shadow DOM)
+  const elements: ElementInfo[] = await p.evaluate(() => {
+    const interactive = new Set([
+      "A", "BUTTON", "INPUT", "TEXTAREA", "SELECT", "OPTION", "LABEL", "DETAILS", "SUMMARY",
+    ]);
+    const results: ElementInfo[] = [];
+    let index = 0;
+    const keepAttrs = ["id", "name", "type", "placeholder", "href", "src", "alt", "role", "aria-label", "value"];
+
+    function processElement(el: Element) {
+      const rect = el.getBoundingClientRect();
+      const style = window.getComputedStyle(el);
+      if (style.display === "none" || style.visibility === "hidden") return;
+      if (rect.width < 2 || rect.height < 2) return;
+
+      const tag = el.tagName.toLowerCase();
+      const isInteractive =
+        interactive.has(el.tagName) ||
+        (el as HTMLElement).onclick != null ||
+        el.getAttribute("role") === "button" ||
+        el.getAttribute("role") === "link";
+
+      if (!isInteractive && rect.width * rect.height < 400) return;
+
+      const text = el.textContent?.trim().slice(0, 200) || undefined;
+      const attrs: Record<string, string> = {};
+      for (const a of keepAttrs) {
+        const v = el.getAttribute(a);
+        if (v) attrs[a] = v;
+      }
+
+      results.push({
+        index: ++index,
+        tag,
+        text,
+        attributes: attrs,
+        bbox: { x: Math.round(rect.x), y: Math.round(rect.y), width: Math.round(rect.width), height: Math.round(rect.height) },
+      });
+
+      // Recurse into shadow DOM
+      if ((el as any).shadowRoot) {
+        walkTree((el as any).shadowRoot);
+      }
+    }
+
+    function walkTree(root: Document | ShadowRoot) {
+      const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+      while (walker.nextNode()) {
+        processElement(walker.currentNode as Element);
+      }
+    }
+
+    walkTree(document);
+    return results;
+  });
+
+  // Capture screenshot for OCR (and optionally for visual mode)
+  let screenshotBuffer: Buffer | null = null;
+  let ocrText: string;
+  try {
+    screenshotBuffer = Buffer.from(await p.screenshot({ type: "png", fullPage: false }));
+    ocrText = await runOcr(screenshotBuffer);
+  } catch {
+    ocrText = "(screenshot/OCR failed)";
+  }
+
+  // Build structured text output
+  const lines: string[] = [];
+  lines.push(`Page: ${url}`);
+  lines.push(`Title: ${title}`);
+  lines.push(`Viewport: ${viewport.width}x${viewport.height}`);
+  lines.push("");
+
+  const interactiveEls = elements.filter(
+    (e) =>
+      ["a", "button", "input", "textarea", "select"].includes(e.tag) ||
+      e.attributes.role === "button" ||
+      e.attributes.role === "link"
+  );
+
+  lines.push(`Elements (${interactiveEls.length} interactive of ${elements.length} total):`);
+  for (const el of interactiveEls.slice(0, 60)) {
+    const attrStr = Object.entries(el.attributes)
+      .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+      .join(" ");
+    const bboxStr = el.bbox
+      ? `bbox=(${el.bbox.x},${el.bbox.y},${el.bbox.x + el.bbox.width},${el.bbox.y + el.bbox.height})`
+      : "";
+    lines.push(`  [${el.index}] <${el.tag}> ${attrStr}${attrStr ? " " : ""}${bboxStr}`);
+    if (el.text && el.text.length > 1) {
+      lines.push(`      text: "${el.text.replace(/\n/g, " ")}"`);
+    }
+  }
+  if (interactiveEls.length > 60) {
+    lines.push(`  ... (${interactiveEls.length - 60} more interactive elements hidden)`);
+  }
+
+  lines.push("");
+  lines.push("OCR (full page screenshot):");
+  lines.push(ocrText || "(no text detected)");
+
+  const text = lines.join("\n");
+
+  // ── Mode: text-only ──
+  // Screenshot was captured only for OCR processing. Image is discarded.
+  // Zero image tokens reach the AI.
+  if (!visual) {
+    return { text };
+  }
+
+  // ── Mode: visual ──
+  // Include the base64-encoded PNG so the AI can see colors, layout, etc.
+  const image = screenshotBuffer?.toString("base64");
+  return { text, image };
+}
+
+// ── Extension ──
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "browser_navigate",
+    label: "Browser Navigate",
+    description: "Open a URL in the browser and return the page context (DOM + OCR). Default text-only mode captures screenshots only for OCR — no image tokens. Set visual=true to receive the actual PNG.",
+    parameters: Type.Object({
+      url: Type.String({ description: "URL to open" }),
+      headless: Type.Optional(Type.Boolean({ description: "Run headless (default false = visible window)" })),
+      visual: Type.Optional(Type.Boolean({ description: "Return base64 PNG screenshot alongside text (default false = text-only, zero image tokens)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      const p = await getPage(params.headless === true);
+      await p.goto(params.url, { waitUntil: "load", timeout: 30000 });
+      const { text, image } = await generatePageMap(p, params.visual);
+      const content: any[] = [{ type: "text", text }];
+      if (image) {
+        content.push({ type: "image", source: { type: "base64", mediaType: "image/png", data: image } });
+      }
+      return { content, details: { url: p.url() } };
+    },
+  });
+
+  pi.registerTool({
+    name: "browser_click",
+    label: "Browser Click",
+    description: "Click an element by CSS selector, XPath, or visible text. Returns updated page context.",
+    parameters: Type.Object({
+      selector: Type.Optional(Type.String({ description: "CSS selector" })),
+      xpath: Type.Optional(Type.String({ description: "XPath expression" })),
+      text: Type.Optional(Type.String({ description: "Visible text content to match" })),
+      visual: Type.Optional(Type.Boolean({ description: "Return base64 PNG screenshot alongside text (default false = text-only, zero image tokens)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      const p = await getPage();
+      if (params.selector) {
+        await p.locator(params.selector).first().click({ timeout: 10000, force: true });
+      } else if (params.xpath) {
+        await p.locator(`xpath=${params.xpath}`).first().click({ timeout: 10000, force: true });
+      } else if (params.text) {
+        await p.getByText(params.text, { exact: false }).first().click({ timeout: 10000, force: true });
+      } else {
+        return { content: [{ type: "text", text: "Error: provide selector, xpath, or text" }], isError: true, details: {} };
+      }
+      await p.waitForTimeout(500);
+      const { text, image } = await generatePageMap(p, params.visual);
+      const content: any[] = [{ type: "text", text }];
+      if (image) {
+        content.push({ type: "image", source: { type: "base64", mediaType: "image/png", data: image } });
+      }
+      return { content, details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "browser_type",
+    label: "Browser Type",
+    description: "Type text into an input field. Returns updated page context.",
+    parameters: Type.Object({
+      selector: Type.String({ description: "CSS selector for the input" }),
+      text: Type.String({ description: "Text to type" }),
+      clear: Type.Optional(Type.Boolean({ description: "Clear existing content first (default true)" })),
+      visual: Type.Optional(Type.Boolean({ description: "Return base64 PNG screenshot alongside text (default false = text-only, zero image tokens)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      const p = await getPage();
+      const locator = p.locator(params.selector).first();
+      if (params.clear !== false) {
+        await locator.fill(params.text);
+      } else {
+        await locator.pressSequentially(params.text);
+      }
+      const { text, image } = await generatePageMap(p, params.visual);
+      const content: any[] = [{ type: "text", text }];
+      if (image) {
+        content.push({ type: "image", source: { type: "base64", mediaType: "image/png", data: image } });
+      }
+      return { content, details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "browser_scroll",
+    label: "Browser Scroll",
+    description: "Scroll the page or a specific element. Returns updated page context.",
+    parameters: Type.Object({
+      direction: Type.String({ description: "Direction: up, down, left, right, or 'to' (element)" }),
+      amount: Type.Optional(Type.Number({ description: "Pixels to scroll (default 800)" })),
+      selector: Type.Optional(Type.String({ description: "CSS selector to scroll into view" })),
+      visual: Type.Optional(Type.Boolean({ description: "Return base64 PNG screenshot alongside text (default false = text-only, zero image tokens)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      const p = await getPage();
+      if (params.selector) {
+        await p.locator(params.selector).first().scrollIntoViewIfNeeded({ timeout: 10000 });
+      } else {
+        const dir = params.direction ?? "down";
+        const amt = params.amount ?? 800;
+        const delta = dir === "up" || dir === "left" ? -amt : amt;
+        const isVertical = dir === "up" || dir === "down";
+        await p.evaluate(({ d, vertical }) => {
+          if (vertical) window.scrollBy(0, d);
+          else window.scrollBy(d, 0);
+        }, { d: delta, vertical: isVertical });
+      }
+      await p.waitForTimeout(300);
+      const { text, image } = await generatePageMap(p, params.visual);
+      const content: any[] = [{ type: "text", text }];
+      if (image) {
+        content.push({ type: "image", source: { type: "base64", mediaType: "image/png", data: image } });
+      }
+      return { content, details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "browser_screenshot",
+    label: "Browser Screenshot",
+    description: "Capture the current page and return an OCR-based text map. Set visual=true to also receive the PNG.",
+    parameters: Type.Object({
+      fullPage: Type.Optional(Type.Boolean({ description: "Capture full page height (default false)" })),
+      visual: Type.Optional(Type.Boolean({ description: "Return base64 PNG screenshot alongside text (default false = text-only, zero image tokens)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      const p = await getPage();
+      const { text, image } = await generatePageMap(p, params.visual);
+      const content: any[] = [{ type: "text", text }];
+      if (image) {
+        content.push({ type: "image", source: { type: "base64", mediaType: "image/png", data: image } });
+      }
+      return { content, details: { fullPage: params.fullPage ?? false } };
+    },
+  });
+
+  pi.registerTool({
+    name: "browser_read",
+    label: "Browser Read",
+    description: "Get the current page context (DOM + OCR text map) without changing anything.",
+    parameters: Type.Object({
+      visual: Type.Optional(Type.Boolean({ description: "Return base64 PNG screenshot alongside text (default false = text-only, zero image tokens)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      const p = await getPage();
+      const { text, image } = await generatePageMap(p, params.visual);
+      const content: any[] = [{ type: "text", text }];
+      if (image) {
+        content.push({ type: "image", source: { type: "base64", mediaType: "image/png", data: image } });
+      }
+      return { content, details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "browser_evaluate",
+    label: "Browser Evaluate",
+    description: "Execute JavaScript in the page context and return the result. Restricted to safe DOM operations; no eval() or new Function().",
+    parameters: Type.Object({
+      script: Type.String({ description: "JavaScript code to run (must not contain eval, Function, import, or WebSocket)" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      // Validate: reject banned patterns to prevent arbitrary code execution
+      const banned = /\beval\b|\bFunction\b|\bimport\b|\bWebSocket\b|\bfetch\b\(|\bXMLHttpRequest\b|\bdocument\.write\b/i;
+      if (banned.test(params.script)) {
+        return {
+          content: [{ type: "text", text: "⚠️ Script rejected: contains banned keywords (eval, Function, import, WebSocket, fetch, XMLHttpRequest, document.write)." }],
+          isError: true,
+          details: {},
+        };
+      }
+      const p = await getPage();
+      // Execute in a sandboxed way — pass script as a string to Function constructor
+      // but only after the content check above
+      const result = await p.evaluate((script: string) => {
+        try {
+          const fn = new Function(`"use strict"; return (${script})`);
+          return fn();
+        } catch (e: any) {
+          return `Error: ${e.message}`;
+        }
+      }, params.script);
+      const text = typeof result === "object" ? JSON.stringify(result, null, 2) : String(result);
+      return { content: [{ type: "text", text }], details: { result } };
+    },
+  });
+
+  pi.on("session_shutdown", async () => {
+    await closeBrowser();
+  });
+}