agentbrowse 0.0.3 → 0.1.0

package/AGENTS.md

@@ -21,7 +21,8 @@ agentbrowse read --page 2                    # next chunk if it was truncated
 ## Rules that make this reliable
 
 - **Read with `--json`** when you need to parse: `read --json` gives `{ title, markdown, page, totalPages, state }`. Every command's text output ends with a `url | title | links` footer so you always know where you are.
-- **Targeting `click`/`type`**, in priority order: (1) visible text — `click "Sign in"`; (2) a number from the last `links`/`find` — `click 2`; (3) a CSS selector — `click "button.primary"`. Bare words are treated as visible text; use explicit CSS for elements without text.
+- **Prefer `snapshot` for acting.** `snapshot` returns every actionable element as `[ref] role "name" (state)` — e.g. `[3] button "Search"`. Then act by ref: `click 3`, `type 2 "shoes"`. Refs resolve by role+name, so they survive CSS/DOM changes — far more reliable than selectors. If the page changed and a ref is stale, the tool returns a **fresh snapshot** in the error (`stale_ref`); just re-pick from it.
+- **Other `click`/`type` targeting**, in priority order: (1) a `snapshot` ref — `click 3`; (2) visible text — `click "Sign in"`; (3) a number from the last `links`/`find`; (4) a CSS selector — `click "button.primary"`. Bare words are visible text; use explicit CSS for elements without text.
 - **Forms:** `fill -f email=me@x.com -f password=...` then `submit`. Or `type <field> <text>` for one field. Fields match by `name`, or pass a CSS selector.
 - **Truncation:** `read` is capped (`--max-chars`, default 8000). If `truncated`, request `--page 2`, etc. Don't assume you've seen the whole page from page 1.
 - **Errors:** non-zero exit codes mean failure; the reason is on **stderr** as `{ "error": { code, message } }`. `4` = target not found (re-run `links`/`find` to get fresh numbers), `3` = navigation problem, `2` = bad usage, `5` = daemon problem.

package/README.md

@@ -41,8 +41,9 @@ Sessions are isolated by `--session <id>` (default `default`), each with its own
 | `open <url>` | Navigate the session to a URL |
 | `read [url]` | Current page (or open `<url>` first) as token-bounded markdown (`--max-chars`, `--page`) |
 | `links [url]` | Numbered, followable links (`--filter`) |
+| `snapshot [url]` | **Accessibility-tree view**: every actionable element with a stable `[ref]`, role, name, state (`--filter`, `--max`, `--json`). The robust way to act |
 | `find <text>` | Locate elements by visible text; numbers reusable by `click` |
-| `click <target>` | Click by visible text, a number from `links`/`find`, or a CSS selector |
+| `click <target>` | Click by a `snapshot` ref (robust), visible text, a `links`/`find` number, or a CSS selector |
 | `type <field> <text>` | Type into a field (CSS selector or bare `name`) |
 | `fill -f name=value …` | Fill form fields |
 | `submit [form]` | Submit the current form |

package/dist/cli.js

@@ -134,6 +134,7 @@ var DAEMON_CODE_EXIT = {
   bad_args: EXIT.usage,
   unknown_cmd: EXIT.usage,
   target_not_found: EXIT.targetNotFound,
+  stale_ref: EXIT.targetNotFound,
   exec_error: EXIT.navigation
 };
 function fromDaemon(res) {
@@ -228,6 +229,31 @@ async function runLinks(opts) {
   return data.links.map((l) => `${l.n}. ${l.text}  ->  ${l.href}`).join("\n");
 }
 
+// src/commands/snapshot.ts
+async function runSnapshot(opts) {
+  if (opts.url) {
+    const o = await sendRequest(opts.session, { id: nextId(), cmd: "open", args: { url: opts.url } });
+    if (!o.ok) throw fromDaemon(o);
+  }
+  const res = await sendRequest(opts.session, {
+    id: nextId(),
+    cmd: "snapshot",
+    args: { filter: opts.filter, max: opts.max }
+  });
+  if (!res.ok) throw fromDaemon(res);
+  const d = res.data;
+  if (opts.json) return JSON.stringify(d, null, 2);
+  const lines = d.elements.map((e) => {
+    const state = [e.disabled ? "disabled" : "", e.checked ? "checked" : ""].filter(Boolean).join(" ");
+    return `[${e.ref}] ${e.role.padEnd(9)} "${e.name}"${e.href ? `  -> ${e.href}` : ""}${state ? `  (${state})` : ""}`;
+  });
+  const more = d.total > d.elements.length ? `
+(+${d.total - d.elements.length} more \u2014 narrow with --filter)` : "";
+  return `${lines.join("\n") || "(no actionable elements)"}${more}
+---
+snapshot v${d.version} | url: ${d.url} | ${d.elements.length} actionable elements`;
+}
+
 // src/commands/stop.ts
 async function runStop(session) {
   try {
@@ -568,6 +594,60 @@ function extractLinks(html, baseUrl, filter) {
   return out;
 }
 
+// src/core/snapshot.ts
+var ACTIONABLE = /* @__PURE__ */ new Set([
+  "link",
+  "button",
+  "textbox",
+  "searchbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "listbox",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "tab",
+  "switch",
+  "slider",
+  "spinbutton",
+  "option"
+]);
+var LINE = /^\s*-\s+([a-z][\w-]*)(?:\s+"((?:[^"\\]|\\.)*)")?(?:\s+\[([^\]]*)\])?:?\s*$/;
+var URL2 = /^\s*-\s+\/url:\s*"?([^"\n]*?)"?\s*$/;
+function parseAriaSnapshot(yaml) {
+  const out = [];
+  const counts = /* @__PURE__ */ new Map();
+  for (const raw of yaml.split("\n")) {
+    const url = raw.match(URL2);
+    if (url) {
+      const last = out[out.length - 1];
+      if (last && last.role === "link") last.href = url[1];
+      continue;
+    }
+    const m = raw.match(LINE);
+    if (!m) continue;
+    const role = m[1];
+    const name = (m[2] ?? "").replace(/\\"/g, '"');
+    const states = (m[3] ?? "").split(/[\s,]+/).filter(Boolean);
+    const actionable = ACTIONABLE.has(role);
+    const el = { role, name, actionable, nth: 0 };
+    for (const s of states) {
+      if (s === "disabled") el.disabled = true;
+      else if (s === "checked") el.checked = true;
+      else if (s.startsWith("level=")) el.level = Number(s.slice(6));
+    }
+    if (actionable) {
+      const key = `${role} ${name}`;
+      const n = counts.get(key) ?? 0;
+      el.nth = n;
+      counts.set(key, n + 1);
+    }
+    out.push(el);
+  }
+  return out;
+}
+
 // src/core/target.ts
 function looksLikeSelector(s) {
   const t = s.trim();
@@ -599,6 +679,39 @@ async function startDaemon(sessionId, opts = {}) {
   const context = await browser.newContext(statePath ? { storageState: statePath } : {});
   const page = await context.newPage();
   let lastRefs = [];
+  let snapshotVersion = 0;
+  let snapshotRefs = /* @__PURE__ */ new Map();
+  page.on("framenavigated", (f) => {
+    if (f === page.mainFrame()) snapshotVersion++;
+  });
+  async function freshSnapshot(filter, max = 150) {
+    const yaml = await page.locator("body").ariaSnapshot();
+    const all = parseAriaSnapshot(yaml).filter((e) => e.actionable);
+    const f = filter?.toLowerCase();
+    const shown = all.filter((e) => !f || `${e.role} ${e.name}`.toLowerCase().includes(f)).slice(0, max);
+    snapshotRefs = /* @__PURE__ */ new Map();
+    const elements = shown.map((e, i) => {
+      const ref = i + 1;
+      snapshotRefs.set(ref, { role: e.role, name: e.name, nth: e.nth });
+      return { ref, role: e.role, name: e.name, href: e.href, disabled: e.disabled, checked: e.checked };
+    });
+    return { elements, total: all.length };
+  }
+  async function staleRef(req) {
+    const fresh = await freshSnapshot();
+    return {
+      id: req.id,
+      ok: false,
+      error: { code: "stale_ref", message: "snapshot is stale; use the fresh refs" },
+      data: { version: snapshotVersion, url: page.url(), elements: fresh.elements }
+    };
+  }
+  function refLocator(target) {
+    if (!/^\d+$/.test(target)) return null;
+    const entry = snapshotRefs.get(parseInt(target, 10));
+    if (!entry) return null;
+    return page.getByRole(entry.role, { name: entry.name, exact: true }).nth(entry.nth);
+  }
   const settle = () => page.waitForLoadState("domcontentloaded").catch(() => {
   });
   async function dispatch(req) {
@@ -645,6 +758,13 @@ async function startDaemon(sessionId, opts = {}) {
         case "click": {
           const target = String(req.args?.target ?? "");
           if (!target) return err(req, "bad_args", "click requires a target");
+          const snapLoc = refLocator(target);
+          if (snapLoc) {
+            if (await snapLoc.count() === 0) return staleRef(req);
+            await snapLoc.click();
+            await settle();
+            return ok(req, { url: page.url(), title: await page.title() });
+          }
           if (/^\d+$/.test(target)) {
             const ref = lastRefs[parseInt(target, 10) - 1];
             if (!ref) return err(req, "target_not_found", `no ref #${target}; run links or find first`);
@@ -666,6 +786,12 @@ async function startDaemon(sessionId, opts = {}) {
           const selector = String(req.args?.selector ?? "");
           const text = String(req.args?.text ?? "");
           if (!selector) return err(req, "bad_args", "type requires a selector");
+          const snapField = refLocator(selector);
+          if (snapField) {
+            if (await snapField.count() === 0) return staleRef(req);
+            await snapField.fill(text);
+            return ok(req, { typed: selector, url: page.url() });
+          }
           const loc = resolveField(page, selector);
           if (await loc.count() === 0) return err(req, "target_not_found", `no field matching: ${selector}`);
           await loc.fill(text);
@@ -695,6 +821,12 @@ async function startDaemon(sessionId, opts = {}) {
           await settle();
           return ok(req, { url: page.url(), title: await page.title() });
         }
+        case "snapshot": {
+          const filter = req.args?.filter ? String(req.args.filter) : void 0;
+          const max = Number(req.args?.max ?? 150);
+          const { elements, total } = await freshSnapshot(filter, max);
+          return ok(req, { version: snapshotVersion, url: page.url(), elements, total });
+        }
         case "savestate": {
           const p = ensureStatePath(sessionId);
           await context.storageState({ path: p });
@@ -790,6 +922,9 @@ function buildProgram() {
   program.command("links").description("List navigable links on the current page (or open <url> first).").argument("[url]", "optional URL to open before listing").option("--json", "structured JSON output", false).option("--filter <text>", "case-insensitive substring filter").action(
     (url, opts, cmd) => emit(() => runLinks({ session: session(cmd), json: !!opts.json, filter: opts.filter, url }))
   );
+  program.command("snapshot").description("List actionable elements (accessibility tree) with refs for click/type.").argument("[url]", "optional URL to open before snapshotting").option("--json", "structured JSON output", false).option("--filter <text>", "case-insensitive substring filter").option("--max <n>", "max elements", (v) => parseInt(v, 10), 150).action(
+    (url, opts, cmd) => emit(() => runSnapshot({ session: session(cmd), json: !!opts.json, filter: opts.filter, max: opts.max, url }))
+  );
   program.command("find").description("Find elements on the current page by visible text (numbers reusable by click).").argument("<text...>", "visible text to search for").option("--json", "structured JSON output", false).action(
     (text, opts, cmd) => emit(() => runFind({ session: session(cmd), json: !!opts.json, text: text.join(" ") }))
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentbrowse",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "Agent-browser CLI: drive any website from the terminal.",
   "type": "module",
   "bin": {