@runablehq/mini-browser 0.1.0

package/README.md

@@ -0,0 +1,165 @@
+```
+               ┌─────────────────────────────────────────┐
+               │  ███╗   ███╗██████╗                     │
+               │  ████╗ ████║██╔══██╗                    │
+               │  ██╔████╔██║██████╔╝                    │
+               │  ██║╚██╔╝██║██╔══██╗                    │
+               │  ██║ ╚═╝ ██║██████╔╝                    │
+               │  ╚═╝     ╚═╝╚═════╝                     │
+               │                                         │
+               │     mini-browser for agents             │
+               └─────────────────────────────────────────┘
+```
+
+A lightweight browser CLI for AI agents. Navigate, observe, interact — all from the command line.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install dependencies
+bun install
+
+# 2. Build the CLI
+bun run build
+
+# 3. Start Chrome with remote debugging
+./start-chrome.sh
+
+# 4. You're ready!
+node dist/mb.js --help
+```
+
+---
+
+## Demo
+
+```bash
+# Navigate to a page
+$ mb go "https://example.com"
+https://example.com/
+
+# Get page text
+$ mb text
+Example Domain
+
+This domain is for use in documentation examples without needing permission.
+
+Learn more
+
+# Find interactive elements with coordinates
+$ mb snap
+[0] link "Learn more" (246, 223)
+
+# Click by coordinates
+$ mb click 246 223
+
+# Check where we ended up
+$ mb url
+https://www.iana.org/help/example-domains
+
+# Go back
+$ mb back
+
+# Take a screenshot
+$ mb shot page.png
+page.png
+```
+
+---
+
+## Commands
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  NAVIGATION                                                         │
+├─────────────────────────────────────────────────────────────────────┤
+│  go <url>              Navigate to URL                              │
+│  url                   Print current URL                            │
+│  back                  Go back                                      │
+│  forward               Go forward                                   │
+├─────────────────────────────────────────────────────────────────────┤
+│  OBSERVE                                                            │
+├─────────────────────────────────────────────────────────────────────┤
+│  shot [file]           Screenshot (default: ./shot.png)             │
+│  snap                  Interactive elements with (x, y) coords      │
+│  text [selector]       Visible text content                         │
+├─────────────────────────────────────────────────────────────────────┤
+│  INTERACT                                                           │
+├─────────────────────────────────────────────────────────────────────┤
+│  click <x> <y>         Click at coordinates                         │
+│  type [x y] <text>     Type text (triple-clicks to select first)    │
+│  fill <k=v...>         Fill form: Email=a@b.com "Name=Jo Do"        │
+│  key <key...>          Press keys (Enter, Tab, Meta+a)              │
+│  move <x> <y>          Move mouse / hover                           │
+│  drag <x1> <y1> <x2> <y2>  Drag from point to point                 │
+│  scroll <dir> [px]     Scroll up/down/left/right                    │
+├─────────────────────────────────────────────────────────────────────┤
+│  TABS                                                               │
+├─────────────────────────────────────────────────────────────────────┤
+│  tab list              List open tabs                               │
+│  tab new [url]         Open new tab, print index                    │
+│  tab close [n]         Close tab (default: last)                    │
+├─────────────────────────────────────────────────────────────────────┤
+│  OTHER                                                              │
+├─────────────────────────────────────────────────────────────────────┤
+│  js <code>             Run JavaScript in page context               │
+│  wait <target>         Wait for ms/selector/networkidle/url:...     │
+│  audit                 Design audit (colors, fonts, contrast)       │
+│  logs                  Stream console logs (Ctrl+C to stop)         │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--timeout <ms>` | Command timeout (default: 30000) |
+| `--tab <n>` | Target tab index (default: 0) |
+| `--json` | JSON output |
+| `--right` | Right-click |
+| `--double` | Double-click |
+
+---
+
+## How It Works
+
+```
+┌──────────┐     CDP      ┌─────────────────┐
+│    mb    │ ◄──────────► │  Chrome/Chromium │
+│   CLI    │   (9222)     │  (debug mode)    │
+└──────────┘              └─────────────────┘
+```
+
+1. **Start Chrome** with `--remote-debugging-port=9222`
+2. **Run commands** — `mb` connects via Chrome DevTools Protocol
+3. **Observe + Interact** — screenshots, text, clicks, forms, etc.
+
+---
+
+## For Agents
+
+The `snap` command is your best friend:
+
+```bash
+$ mb snap
+[0] button "Sign In" (845, 32)
+[1] input[type=email] (512, 245)
+[2] input[type=password] (512, 312)
+[3] button "Submit" (512, 380)
+[4] link "Forgot password?" (512, 420)
+```
+
+Each element has **coordinates** — use them with `click`, `type`, or `fill`.
+
+```bash
+# Click the Sign In button
+mb click 845 32
+
+# Or fill a form by label
+mb fill Email=user@example.com Password=secret123
+mb click 512 380
+```
+
+---

package/dist/mb.js

@@ -0,0 +1,914 @@
+#!/usr/bin/env node
+
+// src/lib/flags.ts
+import { parseArgs } from "node:util";
+
+// src/lib/config.ts
+var CDP_URL = "http://127.0.0.1:9222";
+var VIEWPORT = { width: 1024, height: 768 };
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_TAB = 0;
+
+// src/lib/flags.ts
+var parseNumericFlag = ({ name, value }) => {
+  if (typeof value !== "string") {
+    throw new Error(`Invalid value for --${name}: "${String(value)}". Expected a number.`);
+  }
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    throw new Error(`Invalid value for --${name}: "${value}". Expected a number.`);
+  }
+  return numeric;
+};
+var formatParseArgsError = ({ error }) => {
+  const message = error instanceof Error ? error.message : String(error);
+  const unknownFlag = message.match(/Unknown option '([^']+)'/);
+  if (unknownFlag?.[1]) {
+    return `Unknown flag ${unknownFlag[1]}. Run 'mb --help' for usage.`;
+  }
+  return `Invalid flags: ${message}`;
+};
+var parse = (argv) => {
+  const parsed = (() => {
+    try {
+      return parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+          timeout: { type: "string", default: String(DEFAULT_TIMEOUT) },
+          tab: { type: "string", default: String(DEFAULT_TAB) },
+          json: { type: "boolean", default: false },
+          right: { type: "boolean", default: false },
+          double: { type: "boolean", default: false },
+          help: { type: "boolean", short: "h", default: false }
+        }
+      });
+    } catch (error) {
+      throw new Error(formatParseArgsError({ error }));
+    }
+  })();
+  const { values, positionals } = parsed;
+  return {
+    args: positionals,
+    flags: {
+      timeout: parseNumericFlag({ name: "timeout", value: values.timeout }),
+      tab: parseNumericFlag({ name: "tab", value: values.tab }),
+      json: values.json,
+      right: values.right,
+      double: values.double,
+      help: values.help
+    }
+  };
+};
+
+// src/lib/browser.ts
+import puppeteer from "puppeteer-core";
+var connect = async (tab2 = 0) => {
+  const browser = await puppeteer.connect({
+    browserURL: CDP_URL,
+    defaultViewport: VIEWPORT
+  });
+  const pages = await browser.pages();
+  if (tab2 < 0 || tab2 >= pages.length) {
+    await browser.disconnect();
+    throw new Error(`Invalid tab index: ${tab2}. Open tabs: 0-${pages.length - 1}`);
+  }
+  const page = pages[tab2];
+  if (!page) throw new Error("No pages found");
+  return { browser, page, close: () => browser.disconnect() };
+};
+
+// src/commands/go.ts
+var go = async (args, flags) => {
+  const url2 = args[0];
+  if (!url2) {
+    console.error("Usage: mb go <url>");
+    process.exit(1);
+  }
+  const { page, close: close2 } = await connect(flags.tab);
+  await page.goto(url2, { waitUntil: "domcontentloaded", timeout: flags.timeout });
+  console.log(page.url());
+  await close2();
+};
+
+// src/commands/url.ts
+var url = async (args, flags) => {
+  const { page, close: close2 } = await connect(flags.tab);
+  console.log(page.url());
+  await close2();
+};
+
+// src/commands/back.ts
+var back = async (args, flags) => {
+  const { page, close: close2 } = await connect(flags.tab);
+  await page.goBack({ waitUntil: "domcontentloaded", timeout: flags.timeout });
+  console.log(page.url());
+  await close2();
+};
+
+// src/commands/forward.ts
+var forward = async (args, flags) => {
+  const { page, close: close2 } = await connect(flags.tab);
+  await page.goForward({ waitUntil: "domcontentloaded", timeout: flags.timeout });
+  console.log(page.url());
+  await close2();
+};
+
+// src/commands/shot.ts
+var shot = async (args, flags) => {
+  const path = args[0] || "./shot.png";
+  const { page, close: close2 } = await connect(flags.tab);
+  await page.screenshot({ path, type: "png" });
+  console.log(path);
+  await close2();
+};
+
+// src/commands/snap.ts
+var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
+  "link",
+  "button",
+  "textbox",
+  "combobox",
+  "searchbox",
+  "checkbox",
+  "radio",
+  "switch",
+  "slider",
+  "spinbutton",
+  "tab",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "treeitem",
+  "select"
+]);
+var STATE_PROPS = /* @__PURE__ */ new Set([
+  "haspopup",
+  "expanded",
+  "checked",
+  "selected",
+  "disabled",
+  "pressed"
+]);
+var VIEWPORT_MARGIN = 5;
+var getBox = async (client, backendNodeId) => {
+  const { model } = await client.send("DOM.getBoxModel", { backendNodeId });
+  if (model.width === 0 || model.height === 0) return null;
+  const [x1, y1, x2, , , y3] = model.border;
+  return {
+    x: Math.round((x1 + x2) / 2),
+    y: Math.round((y1 + y3) / 2)
+  };
+};
+var inViewport = ({ x, y }, viewport) => x >= 0 && x <= viewport.width && y >= 0 && y <= viewport.height + VIEWPORT_MARGIN;
+var extractState = (properties) => (properties ?? []).reduce((acc, p) => {
+  if (STATE_PROPS.has(p.name)) acc[p.name] = p.value.value;
+  return acc;
+}, {});
+var nameFallback = (name, role, properties) => {
+  if (name) return name;
+  const href = properties?.find((p) => p.name === "url")?.value?.value;
+  if (href && role === "link") {
+    try {
+      return new URL(href).pathname.replace(/\/$/, "") || href;
+    } catch {
+    }
+  }
+  return "";
+};
+var formatElement = (el, index) => {
+  const stateStr = Object.entries(el.state).map(([k, v]) => `[${k}=${v}]`).join(" ");
+  return `[${index}] ${el.role} "${el.name}" (${el.x}, ${el.y})${stateStr ? " " + stateStr : ""}`;
+};
+var snap = async (args, flags) => {
+  const { page, close: close2 } = await connect(flags.tab);
+  const client = await page.createCDPSession();
+  const viewport = await page.evaluate(() => ({
+    width: window.innerWidth,
+    height: window.innerHeight
+  }));
+  const { nodes } = await client.send("Accessibility.getFullAXTree");
+  const interesting = nodes.filter(
+    (n) => !n.ignored && n.backendDOMNodeId && INTERACTIVE_ROLES.has(n.role?.value)
+  );
+  const elements = (await Promise.all(
+    interesting.map(async (n) => {
+      try {
+        const box = await getBox(client, n.backendDOMNodeId);
+        if (!box || !inViewport(box, viewport)) return null;
+        return {
+          role: n.role.value,
+          name: nameFallback(n.name?.value || "", n.role.value, n.properties),
+          ...box,
+          state: extractState(n.properties)
+        };
+      } catch {
+        return null;
+      }
+    })
+  )).filter((el) => el !== null).sort((a, b) => a.y - b.y || a.x - b.x);
+  await client.detach();
+  await close2();
+  if (flags.json) {
+    console.log(JSON.stringify(elements, null, 2));
+    return;
+  }
+  elements.forEach((el, i) => console.log(formatElement(el, i)));
+};
+
+// src/commands/text.ts
+var text = async (args, flags) => {
+  const selector = args[0] || "body";
+  const { page, close: close2 } = await connect(flags.tab);
+  const content = await page.evaluate((sel) => {
+    const el = document.querySelector(sel);
+    return el?.innerText?.trim() ?? null;
+  }, selector);
+  await close2();
+  if (content === null) {
+    console.error(`Selector not found: ${selector}`);
+    process.exit(1);
+  }
+  console.log(content);
+};
+
+// src/commands/click.ts
+var click = async (args, flags) => {
+  const [xStr, yStr] = args;
+  if (!xStr || !yStr) {
+    console.error("Usage: mb click <x> <y>");
+    process.exit(1);
+  }
+  const x = +xStr;
+  const y = +yStr;
+  if (isNaN(x) || isNaN(y)) {
+    console.error("x and y must be numbers");
+    process.exit(1);
+  }
+  const { page, close: close2 } = await connect(flags.tab);
+  await page.mouse.click(x, y, {
+    button: flags.right ? "right" : "left",
+    clickCount: flags.double ? 2 : 1
+  });
+  await close2();
+};
+
+// src/commands/type.ts
+var type = async (args, flags) => {
+  if (args.length === 0) {
+    console.error("Usage: mb type <text> OR mb type <x> <y> <text>");
+    process.exit(1);
+  }
+  const maybeX = +args[0];
+  const maybeY = +args[1];
+  const hasCoords = args.length >= 3 && !isNaN(maybeX) && !isNaN(maybeY);
+  const coords = hasCoords ? { x: maybeX, y: maybeY } : null;
+  const text2 = hasCoords ? args.slice(2).join(" ") : args.join(" ");
+  if (!text2) {
+    console.error("Text is required");
+    process.exit(1);
+  }
+  const { page, close: close2 } = await connect(flags.tab);
+  if (coords) {
+    await page.mouse.click(coords.x, coords.y, { clickCount: 3 });
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  await page.keyboard.type(text2);
+  await close2();
+};
+
+// src/commands/fill.ts
+var parseKeyValuePairs = ({ args }) => {
+  const fields = {};
+  for (const arg of args) {
+    const eqIndex = arg.indexOf("=");
+    if (eqIndex === -1) {
+      throw new Error(`Invalid field "${arg}". Use key=value format, e.g.: mb fill Email=test@example.com`);
+    }
+    const key2 = arg.slice(0, eqIndex);
+    const value = arg.slice(eqIndex + 1);
+    if (!key2) {
+      throw new Error(`Empty field name in "${arg}"`);
+    }
+    fields[key2] = value;
+  }
+  return fields;
+};
+var parseFields = ({ args }) => {
+  return parseKeyValuePairs({ args });
+};
+var fill = async (args, flags) => {
+  if (args.length === 0) {
+    throw new Error('Usage: mb fill "Field Name=value" ...');
+  }
+  const fields = parseFields({ args });
+  const { page, close: close2 } = await connect(flags.tab);
+  const results = await page.evaluate((fields2) => {
+    const filled = [];
+    const failed = [];
+    const query = (selector, key2) => {
+      try {
+        return document.querySelector(selector);
+      } catch {
+        throw new Error(`Invalid selector for field "${key2}": ${selector}`);
+      }
+    };
+    const escapeSelectorValue = (value) => {
+      if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+        return CSS.escape(value);
+      }
+      return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    };
+    const findInput = (key2) => {
+      if (key2.startsWith("#") || key2.startsWith(".") || key2.startsWith("[")) {
+        return query(key2, key2);
+      }
+      const escapedKey = escapeSelectorValue(key2);
+      const byAria = query(`[aria-label="${escapedKey}"]`, key2);
+      if (byAria) return byAria;
+      const byPlaceholder = query(`[placeholder="${escapedKey}"]`, key2);
+      if (byPlaceholder) return byPlaceholder;
+      const byName = query(`[name="${escapedKey}"]`, key2);
+      if (byName) return byName;
+      const byId = document.getElementById(key2);
+      if (byId) return byId;
+      const labels = document.querySelectorAll("label");
+      for (const label of labels) {
+        if (label.textContent?.trim().toLowerCase().includes(key2.toLowerCase())) {
+          const forId = label.getAttribute("for");
+          if (forId) {
+            const input2 = document.getElementById(forId);
+            if (input2) return input2;
+          }
+          const input = label.querySelector("input, textarea, select");
+          if (input) return input;
+        }
+      }
+      return null;
+    };
+    for (const [key2, value] of Object.entries(fields2)) {
+      const el = findInput(key2);
+      if (!el) {
+        failed.push(key2);
+        continue;
+      }
+      if (el.tagName === "SELECT") {
+        el.value = value;
+      } else {
+        el.value = value;
+      }
+      el.dispatchEvent(new Event("input", { bubbles: true }));
+      el.dispatchEvent(new Event("change", { bubbles: true }));
+      filled.push(key2);
+    }
+    return { filled, failed };
+  }, fields);
+  await close2();
+  if (results.filled.length > 0) {
+    console.log(`Filled: ${results.filled.join(", ")}`);
+  }
+  if (results.failed.length > 0) {
+    throw new Error(`Not found: ${results.failed.join(", ")}`);
+  }
+};
+
+// src/commands/key.ts
+var key = async (args, flags) => {
+  if (args.length === 0) {
+    console.error("Usage: mb key <key...>");
+    process.exit(1);
+  }
+  const { page, close: close2 } = await connect(flags.tab);
+  for (const k of args) {
+    if (!k.includes("+")) {
+      await page.keyboard.press(k);
+      continue;
+    }
+    const parts = k.split("+");
+    const modifiers = parts.slice(0, -1);
+    const finalKey = parts.at(-1);
+    for (const m of modifiers) await page.keyboard.down(m);
+    await page.keyboard.press(finalKey);
+    for (const m of [...modifiers].reverse()) await page.keyboard.up(m);
+  }
+  await close2();
+};
+
+// src/commands/move.ts
+var move = async (args, flags) => {
+  if (args.length < 2) {
+    console.error("Usage: mb move <x> <y>");
+    process.exit(1);
+  }
+  const x = +args[0];
+  const y = +args[1];
+  if (isNaN(x) || isNaN(y)) {
+    console.error("x and y must be numbers");
+    process.exit(1);
+  }
+  const { page, close: close2 } = await connect(flags.tab);
+  await page.mouse.move(x, y);
+  await close2();
+};
+
+// src/commands/drag.ts
+var drag = async (args, flags) => {
+  if (args.length < 4) {
+    console.error("Usage: mb drag <x1> <y1> <x2> <y2>");
+    process.exit(1);
+  }
+  const coords = args.map(Number);
+  const [x1, y1, x2, y2] = coords;
+  if (coords.some(isNaN)) {
+    console.error("All coordinates must be numbers");
+    process.exit(1);
+  }
+  const { page, close: close2 } = await connect(flags.tab);
+  await page.mouse.move(x1, y1);
+  await page.mouse.down();
+  await page.mouse.move(x2, y2, { steps: 10 });
+  await page.mouse.up();
+  await close2();
+};
+
+// src/commands/scroll.ts
+var deltas = {
+  up: { x: 0, y: -1 },
+  down: { x: 0, y: 1 },
+  left: { x: -1, y: 0 },
+  right: { x: 1, y: 0 }
+};
+var scroll = async (args, flags) => {
+  const dir = args[0] || "down";
+  const px = Number(args[1] || 500);
+  const delta = deltas[dir];
+  if (!delta) {
+    console.error("Direction must be: up, down, left, right");
+    process.exit(1);
+  }
+  if (!Number.isFinite(px) || px <= 0) {
+    console.error("Pixels must be a positive number");
+    process.exit(1);
+  }
+  const { page, close: close2 } = await connect(flags.tab);
+  await page.evaluate(({ x, y }) => window.scrollBy(x, y), { x: delta.x * px, y: delta.y * px });
+  await close2();
+};
+
+// src/commands/js.ts
+import { text as readStdin } from "node:stream/consumers";
+var js = async (args, flags) => {
+  const code = args[0] === "-" ? await readStdin(process.stdin) : args.join(" ");
+  if (!code.trim()) {
+    console.error("Usage: mb js <code> OR echo 'code' | mb js -");
+    process.exit(1);
+  }
+  const { page, close: close2 } = await connect(flags.tab);
+  const result = await page.evaluate(code);
+  await close2();
+  if (result === void 0 || result === null) return;
+  console.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+};
+
+// src/commands/wait.ts
+var wait = async (args, flags) => {
+  const target = args[0];
+  if (!target) {
+    console.error("Usage: mb wait <ms | selector | networkidle | url:...>");
+    process.exit(1);
+  }
+  const { page, close: close2 } = await connect(flags.tab);
+  const ms = +target;
+  if (!isNaN(ms) && target === String(ms)) {
+    await new Promise((r) => setTimeout(r, ms));
+    await close2();
+    return;
+  }
+  if (target === "networkidle") {
+    await page.waitForNetworkIdle({ timeout: flags.timeout });
+    await close2();
+    return;
+  }
+  if (target.startsWith("url:")) {
+    await page.waitForFunction(
+      (p) => location.href.includes(p),
+      { timeout: flags.timeout },
+      target.slice(4)
+    );
+    await close2();
+    return;
+  }
+  await page.waitForSelector(target, { timeout: flags.timeout });
+  await close2();
+};
+
+// src/commands/audit.ts
+var findHeadingSkips = (headings) => headings.reduce((skips, level, i) => {
+  const prev = headings[i - 1];
+  if (i > 0 && prev !== void 0 && level > prev + 1)
+    return [...skips, `h${prev}\u2192h${level}`];
+  return skips;
+}, []);
+var findDesignIssues = ({ colors, families, sizes, radii }) => {
+  const checks = [
+    { count: families.length, max: 3, msg: "font families \u2014 limit to 2-3" },
+    { count: sizes.length, max: 8, msg: "font sizes \u2014 consolidate to 5-7 step type scale" },
+    { count: colors.length, max: 15, msg: "colors \u2014 tighten palette to 8-12" },
+    { count: radii.length, max: 4, msg: "border-radius values \u2014 standardize to 2-3" }
+  ];
+  return checks.filter(({ count, max }) => count > max).map(({ count, msg }) => `${count} ${msg}`);
+};
+var findA11yIssues = (a11y, headingSkips) => [
+  a11y.imagesNoAlt && `${a11y.imagesNoAlt} images missing alt`,
+  a11y.inputsNoLabel && `${a11y.inputsNoLabel} inputs missing label`,
+  a11y.linksNoText && `${a11y.linksNoText} links without text`,
+  a11y.buttonsNoText && `${a11y.buttonsNoText} buttons without text`,
+  headingSkips.length && `heading skip: ${headingSkips.join(", ")}`
+].filter(Boolean);
+var check = (ok, yes, no) => ok ? `  \u2713 ${yes}` : `  \u2717 ${no}`;
+var formatText = ({ data, contrast, browser, designIssues, a11yIssues, headingSkips }) => {
+  const { colors, families, sizes, weights, margins, paddings, radii, a11y, seo } = data;
+  const lines = [];
+  const out = (s) => lines.push(s);
+  out(`PALETTE  ${colors.length} colors`);
+  colors.slice(0, 12).forEach((c) => out(`  ${c.hex}  ${String(c.count).padStart(3)}x  ${c.uses.join(",")}`));
+  if (colors.length > 12) out(`  ... +${colors.length - 12} more`);
+  out(`
+TYPOGRAPHY  ${families.length} families, ${sizes.length} sizes`);
+  families.forEach((f) => out(`  ${f.name} (${f.count})`));
+  out(`  sizes: ${sizes.map((s) => `${s.value}(${s.count})`).join("  ")}`);
+  out(`  weights: ${weights.map((w) => `${w.value}(${w.count})`).join("  ")}`);
+  out(`
+SPACING`);
+  if (margins.length) out(`  margins:  ${margins.map((m) => `${m.value}(${m.count})`).join("  ")}`);
+  if (paddings.length) out(`  paddings: ${paddings.map((p) => `${p.value}(${p.count})`).join("  ")}`);
+  if (radii.length) out(`  radii:    ${radii.map((r) => `${r.value}(${r.count})`).join("  ")}`);
+  if (contrast.length) {
+    out(`
+CONTRAST  ${contrast.length} issues (Chrome DevTools)`);
+    contrast.slice(0, 10).forEach((c) => out(`  ${c.selector}  ${c.ratio}:1 (need ${c.threshold}:1)  ${c.fontSize} w${c.fontWeight}`));
+    if (contrast.length > 10) out(`  ... +${contrast.length - 10} more`);
+  }
+  out(`
+ACCESSIBILITY`);
+  out(check(!!a11y.lang, `lang="${a11y.lang}"`, "missing lang attribute"));
+  out(check(!!a11y.title, "page has title", "missing page title"));
+  a11yIssues.forEach((i) => out(`  \u2717 ${i}`));
+  if (!a11yIssues.length && a11y.lang && a11y.title) out("  \u2713 no issues");
+  out(`
+SEO`);
+  out(check(!!seo.title, `title: "${seo.title}"`, "missing title"));
+  out(check(!!seo.metaDescription, `meta description (${seo.metaDescription.length} chars)`, "missing meta description"));
+  out(check(!!seo.canonical, `canonical: ${seo.canonical}`, "no canonical link"));
+  out(check(seo.hasViewport, "viewport meta", "missing viewport meta"));
+  out(seo.h1Count === 1 ? `  \u2713 1 h1: "${seo.h1Text}"` : seo.h1Count === 0 ? "  \u2717 no h1" : `  \u26A0 ${seo.h1Count} h1 tags (should be 1)`);
+  out(`  ${seo.og.title ? "\u2713" : "\u2717"} og:title  ${seo.og.description ? "\u2713" : "\u2717"} og:description  ${seo.og.image ? "\u2713" : "\u2717"} og:image`);
+  if (browser.length) {
+    const grouped = {};
+    for (const i of browser) {
+      if (!grouped[i.code]) grouped[i.code] = [];
+      grouped[i.code].push(i);
+    }
+    out(`
+BROWSER  ${browser.length} issues`);
+    for (const [code, items] of Object.entries(grouped)) {
+      const details = items.map((i) => i.detail).filter(Boolean);
+      out(`  ${code} (${details.length})`);
+      details.slice(0, 3).forEach((d) => out(`    ${d}`));
+      if (details.length > 3) out(`    ... +${details.length - 3} more`);
+    }
+  }
+  if (designIssues.length) {
+    out(`
+DESIGN`);
+    designIssues.forEach((i) => out(`  \u2717 ${i}`));
+  }
+  const total = designIssues.length + contrast.length + a11yIssues.length;
+  out(`
+${total} issues total`);
+  return lines.join("\n");
+};
+var collectCdpIssues = async (page) => {
+  const contrast = [];
+  const browser = [];
+  try {
+    const client = await page.createCDPSession();
+    client.on("Audits.issueAdded", ({ issue }) => {
+      if (issue.code === "LowTextContrastIssue") {
+        const d = issue.details.lowTextContrastIssueDetails;
+        contrast.push({
+          selector: d.violatingNodeSelector,
+          ratio: Math.round(d.contrastRatio * 100) / 100,
+          threshold: d.thresholdAA,
+          fontSize: d.fontSize,
+          fontWeight: d.fontWeight
+        });
+      } else {
+        const detail = issue.details?.mixedContentIssueDetails?.insecureURL ?? issue.details?.deprecationIssueDetails?.type ?? issue.details?.contentSecurityPolicyIssueDetails?.violatedDirective ?? issue.details?.cookieIssueDetails?.cookie?.name ?? "";
+        browser.push({ code: issue.code, detail });
+      }
+    });
+    await client.send("Audits.enable");
+    await client.send("Audits.checkContrast", { reportAAA: false });
+    return { contrast, browser, cleanup: async () => {
+      try {
+        await client.send("Audits.disable");
+        await client.detach();
+      } catch {
+      }
+    } };
+  } catch {
+    return { contrast, browser, cleanup: async () => {
+    } };
+  }
+};
+var extractDesignData = (page) => page.evaluate(() => {
+  const parseRgb = (s) => {
+    const m = s.match(/rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)/);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+  };
+  const toHex = (rgb) => "#" + rgb.map((c) => c.toString(16).padStart(2, "0")).join("");
+  const transparent = (s) => s === "rgba(0, 0, 0, 0)" || s === "transparent";
+  const tally = (map, key2) => {
+    map[key2] = (map[key2] || 0) + 1;
+  };
+  const colors = {};
+  const families = {};
+  const sizes = {};
+  const weights = {};
+  const marginVals = {};
+  const paddingVals = {};
+  const radii = {};
+  for (const el of document.querySelectorAll("body *")) {
+    const rect = el.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) continue;
+    const cs = getComputedStyle(el);
+    if (cs.display === "none" || cs.visibility === "hidden" || cs.opacity === "0") continue;
+    for (const [val, use] of [[cs.color, "text"], [cs.backgroundColor, "bg"]]) {
+      if (transparent(val)) continue;
+      const rgb = parseRgb(val);
+      if (!rgb) continue;
+      const h = toHex(rgb);
+      const entry = colors[h] ?? (colors[h] = { count: 0, uses: /* @__PURE__ */ new Set() });
+      entry.count++;
+      entry.uses.add(use);
+    }
+    const fam = cs.fontFamily.split(",")[0]?.trim().replace(/['"]/g, "") ?? "";
+    tally(families, fam);
+    tally(sizes, cs.fontSize);
+    tally(weights, cs.fontWeight);
+    for (const dir of ["Top", "Right", "Bottom", "Left"]) {
+      const m = cs[`margin${dir}`], p = cs[`padding${dir}`];
+      if (m && m !== "0px") tally(marginVals, m);
+      if (p && p !== "0px") tally(paddingVals, p);
+    }
+    if (cs.borderRadius && cs.borderRadius !== "0px") tally(radii, cs.borderRadius);
+  }
+  const countMatching = (sel, predicate) => [...document.querySelectorAll(sel)].filter(predicate).length;
+  const hasAccessibleName = (el) => {
+    const text2 = el.innerText?.trim() || el.getAttribute("aria-label") || "";
+    return !!text2 || !!el.querySelector("img[alt]");
+  };
+  const headings = [...document.querySelectorAll("h1,h2,h3,h4,h5,h6")].map((h) => parseInt(h.tagName.charAt(1)));
+  const a11y = {
+    imagesNoAlt: countMatching("img", (el) => !el.hasAttribute("alt")),
+    inputsNoLabel: countMatching("input:not([type=hidden]), textarea, select", (el) => {
+      const inp = el;
+      const id = inp.id;
+      return !(inp.hasAttribute("aria-label") || inp.hasAttribute("aria-labelledby") || inp.hasAttribute("title") || inp.hasAttribute("placeholder") || id && document.querySelector(`label[for="${id}"]`) || inp.closest("label"));
+    }),
+    linksNoText: countMatching("a[href]", (el) => !hasAccessibleName(el)),
+    buttonsNoText: countMatching("button, [role=button]", (el) => !hasAccessibleName(el)),
+    headings,
+    lang: document.documentElement.getAttribute("lang") || "",
+    title: document.title?.trim().slice(0, 80) || ""
+  };
+  const meta = (sel, attr = "content") => document.querySelector(sel)?.getAttribute(attr) || "";
+  const h1 = document.querySelector("h1");
+  const seo = {
+    title: a11y.title,
+    metaDescription: meta('meta[name="description"]').slice(0, 120),
+    canonical: meta('link[rel="canonical"]', "href"),
+    h1Count: document.querySelectorAll("h1").length,
+    h1Text: h1?.innerText?.trim().slice(0, 80) || "",
+    hasViewport: !!document.querySelector('meta[name="viewport"]'),
+    og: {
+      title: !!document.querySelector('meta[property="og:title"]'),
+      description: !!document.querySelector('meta[property="og:description"]'),
+      image: !!document.querySelector('meta[property="og:image"]')
+    }
+  };
+  const descByCount = (obj) => Object.entries(obj).sort((a, b) => b[1] - a[1]);
+  const ascByPx = (obj) => Object.entries(obj).sort((a, b) => parseFloat(a[0]) - parseFloat(b[0]));
+  return {
+    colors: Object.entries(colors).sort((a, b) => b[1].count - a[1].count).map(([h, v]) => ({ hex: h, count: v.count, uses: [...v.uses] })),
+    families: descByCount(families).map(([name, count]) => ({ name, count })),
+    sizes: ascByPx(sizes).map(([value, count]) => ({ value, count })),
+    weights: ascByPx(weights).map(([value, count]) => ({ value, count })),
+    margins: ascByPx(marginVals).map(([value, count]) => ({ value, count })),
+    paddings: ascByPx(paddingVals).map(([value, count]) => ({ value, count })),
+    radii: ascByPx(radii).map(([value, count]) => ({ value, count })),
+    a11y,
+    seo
+  };
+});
+var audit = async (args, flags) => {
+  const { page, close: close2 } = await connect(flags.tab);
+  const cdp = await collectCdpIssues(page);
+  const data = await extractDesignData(page);
+  await new Promise((r) => setTimeout(r, 300));
+  await cdp.cleanup();
+  await close2();
+  const { contrast, browser } = cdp;
+  const headingSkips = findHeadingSkips(data.a11y.headings);
+  const designIssues = findDesignIssues(data);
+  const a11yIssues = findA11yIssues(data.a11y, headingSkips);
+  if (flags.json) {
+    console.log(JSON.stringify({ ...data, contrast, browser, designIssues, a11yIssues, headingSkips }, null, 2));
+    return;
+  }
+  console.log(formatText({ data, contrast, browser, designIssues, a11yIssues, headingSkips }));
+};
+
+// src/commands/tab.ts
+import puppeteer2 from "puppeteer-core";
+var subcommands = { list, new: newTab, close };
+var help = `Usage: mb tab <list|new|close> [args]
+
+  list              List open tabs
+  new [url]         Open new tab, print index
+  close [n]         Close tab (default: last)`;
+var tab = async (args, flags) => {
+  const [sub, ...rest] = args;
+  if (!sub || !(sub in subcommands)) {
+    console.error(help);
+    process.exit(1);
+  }
+  const handler = subcommands[sub];
+  await handler(rest, flags);
+};
+async function list(_args, flags) {
+  const browser = await puppeteer2.connect({ browserURL: CDP_URL, defaultViewport: VIEWPORT });
+  const pages = await browser.pages();
+  const entries = await Promise.all(
+    pages.map(async (page, i) => ({
+      index: i,
+      url: page.url(),
+      title: await page.title()
+    }))
+  );
+  await browser.disconnect();
+  if (flags.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return;
+  }
+  for (const { index, url: url2, title } of entries) {
+    console.log(`${index}	${url2}	${title}`);
+  }
+}
+async function newTab(args, flags) {
+  const url2 = args[0];
+  const browser = await puppeteer2.connect({ browserURL: CDP_URL, defaultViewport: VIEWPORT });
+  const page = await browser.newPage();
+  if (url2) {
+    try {
+      await page.goto(url2, { waitUntil: "domcontentloaded", timeout: flags.timeout });
+    } catch (e) {
+      await page.close();
+      await browser.disconnect();
+      throw e;
+    }
+  }
+  const pages = await browser.pages();
+  const index = pages.indexOf(page);
+  await browser.disconnect();
+  console.log(index);
+}
+async function close(args, _flags) {
+  const browser = await puppeteer2.connect({ browserURL: CDP_URL, defaultViewport: VIEWPORT });
+  const pages = await browser.pages();
+  if (pages.length <= 1) {
+    await browser.disconnect();
+    throw new Error("Cannot close the last tab");
+  }
+  const index = args[0] !== void 0 ? Number(args[0]) : pages.length - 1;
+  if (!Number.isInteger(index) || index < 0 || index >= pages.length) {
+    await browser.disconnect();
+    throw new Error(`Invalid tab index: ${args[0]}. Open tabs: 0-${pages.length - 1}`);
+  }
+  const target = pages[index];
+  const url2 = target.url();
+  await target.close();
+  await browser.disconnect();
+  console.log(`Closed tab ${index}	${url2}`);
+}
+
+// src/commands/logs.ts
+import puppeteer3 from "puppeteer-core";
+var logs = async (_args, flags) => {
+  const browser = await puppeteer3.connect({
+    browserURL: CDP_URL,
+    defaultViewport: VIEWPORT
+  });
+  const setupPage = async (page, index) => {
+    const client = await page.createCDPSession();
+    await client.send("Runtime.enable");
+    client.on("Runtime.consoleAPICalled", (event) => {
+      const args = event.args.map((a) => a.value !== void 0 ? String(a.value) : a.description ?? "").join(" ");
+      const time = (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
+      const type2 = event.type === "warning" ? "warn" : event.type;
+      if (flags.json) {
+        console.log(JSON.stringify({ tab: index, type: type2, time, message: args }));
+      } else {
+        const prefix = index > 0 ? `[${index}] ` : "";
+        console.log(`${prefix}[${time}] ${type2}: ${args}`);
+      }
+    });
+  };
+  const pages = await browser.pages();
+  for (let i = 0; i < pages.length; i++) {
+    await setupPage(pages[i], i);
+  }
+  browser.on("targetcreated", async (target) => {
+    if (target.type() === "page") {
+      const page = await target.page();
+      if (page) {
+        const allPages = await browser.pages();
+        const index = allPages.indexOf(page);
+        await setupPage(page, index);
+      }
+    }
+  });
+  console.error("Watching console logs... (Ctrl+C to stop)\n");
+  await new Promise((resolve) => {
+    process.on("SIGINT", () => {
+      console.error("\nStopped");
+      resolve();
+    });
+  });
+  await browser.disconnect();
+};
+
+// src/index.ts
+var commands = { go, url, back, forward, shot, snap, text, click, type, fill, key, move, drag, scroll, js, wait, audit, tab, logs };
+var help2 = `mb \u2014 Browser CLI for Agents
+
+Usage: mb <command> [args] [flags]
+
+Navigation:
+  go <url>              Navigate to URL
+  url                   Print current URL
+  back                  Go back
+  forward               Go forward
+
+Observe:
+  shot [file]           Screenshot (default: ./shot.png)
+  snap                  Interactive elements with (x, y)
+  text [selector]       Visible text content
+
+Interact:
+  click <x> <y>         Click at coordinates
+  type [x y] <text>     Type text (triple-clicks to select first)
+  fill <k=v...>         Fill form: Email=a@b.com "Name=Jo Do"
+  key <key...>          Press keys (Enter, Tab, Meta+a)
+  move <x> <y>          Move mouse / hover
+  drag <x1> <y1> <x2> <y2>  Drag
+  scroll <dir> [px]     Scroll up/down/left/right
+
+Other:
+  js <code>             Run JavaScript
+  wait <target>         Wait for ms/selector/networkidle/url:...
+  audit                 Design audit (colors, fonts, spacing, contrast)
+  logs                  Stream console logs (Ctrl+C to stop)
+
+Tabs:
+  tab list              List open tabs
+  tab new [url]         Open new tab, print index
+  tab close [n]         Close tab (default: last)
+
+Flags:
+  --timeout <ms>        Timeout (default: 30000)
+  --tab <n>             Tab index (default: 0)
+  --json                JSON output
+  --right/--double      Right/double click`;
+var main = async () => {
+  try {
+    const { args, flags } = parse(process.argv.slice(2));
+    const [cmd, ...rest] = args;
+    if (!cmd || flags.help) {
+      console.log(help2);
+      process.exit(0);
+    }
+    const handler = commands[cmd];
+    if (!handler) {
+      throw new Error(`Unknown command: ${cmd}
+Run 'mb --help' for usage`);
+    }
+    await handler(rest, flags);
+  } catch (e) {
+    console.error(`Error: ${e instanceof Error ? e.message : e}`);
+    process.exit(1);
+  }
+};
+main();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@runablehq/mini-browser",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A browser CLI for agents, built with Puppeteer",
+  "keywords": [
+    "browser",
+    "cli",
+    "puppeteer",
+    "automation",
+    "agent",
+    "screenshot",
+    "headless"
+  ],
+  "bin": {
+    "mb": "./dist/mb.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "build:binary": "bun build src/index.ts --compile --outfile dist/mb",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "puppeteer-core": "^24.37.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "esbuild": "^0.25.12",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}