@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/events/mascot-notify.js

@@ -0,0 +1,156 @@
+// The one-line bubbles the desktop / Android pets show.
+//
+// WHY HERE, NOT IN EACH CLIENT. Desktop Electron and the Android overlay both
+// subscribe to the same /api/events/ws feed. When each one invented its own
+// filter they drifted: both treated the owner's own send (`direction: "in"`)
+// as news, and skipped the thing the pet is for — an agent actually launching
+// its closing message on Telegram, a group, or A2A. One function, attached to
+// the frame as `notifications: string[]`, is what both surfaces render.
+//
+// SIGNAL, NOT DATA. A line names who spoke and where — on A2A, who spoke to
+// whom. It never carries the body. Delivery rows may also bring a bounded
+// `notify` headline the writer already chose (≤100 chars) — still a notice,
+// not the message.
+//
+// EACH LINE CARRIES ITS CHANNEL. The text alone leaves a client with nothing to
+// filter on: the phone has Telegram installed ON it, so an APX bubble about a
+// Telegram reply is the same news twice, while the trip notice on the same
+// phone is the only way that news arrives at all. So a notice is `{ text,
+// channel }` and the surface decides which channels may ring it — the web has
+// done that per device since lib/channels.ts; the APK could not, because what
+// reached it was a bare string.
+
+import { SUPERAGENT_ACTOR_ID } from "../constants/actors.js";
+import { resolveAgentName } from "../identity/self.js";
+
+const AGENT_FINAL_CHANNELS = new Set(["telegram", "group", "a2a"]);
+const DELIVERY_VIA = new Set(["routine_delivery", "mobility_delivery"]);
+
+/**
+ * The channels a BUBBLE can be about — not the channels APX speaks on.
+ *
+ * Five, and the list is closed by construction: three are agent finals
+ * (telegram / group / a2a) and two are deliveries that arrive with their own
+ * headline. A routine delivery is filed on `web` and a mobility one on
+ * telegram, but neither is news *about that channel* — "an errand on the way
+ * home" is not a Telegram message, and muting Telegram must not silence the
+ * car. So a delivery is tagged by what it IS, the same rule the `log` channel
+ * settled on core-side.
+ *
+ * A client shows this list as the choice; nothing else can ever ring.
+ */
+export const NOTICE_CHANNELS = ["telegram", "group", "a2a", "routine", "mobility"];
+
+function channelLabel(channel) {
+  if (channel === "telegram") return "Telegram";
+  if (channel === "group") return "Grupo";
+  if (channel === "a2a") return "A2A";
+  if (!channel) return "un canal";
+  return channel.charAt(0).toUpperCase() + channel.slice(1);
+}
+
+function speakerName(event) {
+  const author = String(event?.author || "").trim();
+  if (author && author !== "user" && author !== "owner" && !author.startsWith("@")) return author;
+  return String(event?.agent_slug || "").trim() || "agente";
+}
+
+/** A participant's name as a sentence should carry it.
+ *
+ *  The super-agent is filed on the ledger under its ACTOR ID, so a bubble that
+ *  printed the stored name said "a Super_agent" about the agent the owner calls
+ *  Roby. An id is what the ledger needs to keep one thread per correspondent;
+ *  it is not what a sentence about that correspondent says. Everyone else keeps
+ *  the name they were addressed by — an a2a address is a slug written lowercase
+ *  (`magui`), and "de magui a roby" reads as a log line rather than as news, so
+ *  it gets a capital. A name that already carries its own casing (`Roby`,
+ *  `iOS-bot`) is left exactly as its author wrote it. */
+function peerLabel(name) {
+  const n = String(name || "").trim();
+  if (n === SUPERAGENT_ACTOR_ID) return resolveAgentName();
+  if (!n || n !== n.toLowerCase()) return n;
+  return n.charAt(0).toUpperCase() + n.slice(1);
+}
+
+/** An agent's closing message on Telegram / group / A2A — not a stream chunk,
+ *  not a tool row, not the owner's own send, not a delivery that already has
+ *  its own headline. */
+export function isAgentFinalEvent(event) {
+  if (!event || event.direction !== "out") return false;
+  if (event.type && event.type !== "agent") return false;
+  if (!AGENT_FINAL_CHANNELS.has(event.channel)) return false;
+  if (event.streamed === true) return false;
+  if (DELIVERY_VIA.has(event.via)) return false;
+  return true;
+}
+
+/**
+ * @param {object[]} events  the public events already on a "messages" frame
+ * @returns {{text: string, channel: string}[]}
+ *          one notice per distinct agent×channel (plus any delivery
+ *          headlines), in a stable order, each tagged with the channel a
+ *          client filters on. See NOTICE_CHANNELS.
+ */
+export function mascotNoticesFromEvents(events) {
+  const notices = [];
+  const list = Array.isArray(events) ? events : [];
+
+  for (const event of list) {
+    if (event?.via === "mobility_delivery") {
+      const notice = String(event.notify || "").trim();
+      if (notice) notices.push({ text: notice, channel: "mobility" });
+    }
+  }
+
+  const routineByAgent = new Map();
+  for (const event of list) {
+    if (!event || event.via !== "routine_delivery" || event.channel !== "web") continue;
+    if (!event.agent_slug || event.agent_slug === "super_agent") continue;
+    routineByAgent.set(event.agent_slug, event.notify || routineByAgent.get(event.agent_slug) || "");
+  }
+  for (const [agent, notify] of routineByAgent) {
+    const notice = String(notify || "").trim();
+    notices.push({
+      text: notice ? `${agent}: ${notice}` : `${agent} te dejó un mensaje`,
+      channel: "routine",
+    });
+  }
+
+  const finals = new Map();
+  for (const event of list) {
+    if (!isAgentFinalEvent(event)) continue;
+    const agent = speakerName(event);
+    // On A2A the pair IS the news. "martin respondió en A2A" names a channel the
+    // owner never opened and leaves out the only thing he wants to know — who
+    // reached who. The counterpart rides the event for exactly this line; when
+    // it is missing (an older row, a writer that set no `to`) the bubble falls
+    // back to naming the channel rather than inventing a recipient.
+    const to = event.channel === "a2a" ? String(event.to || "").trim() : "";
+    finals.set(`${event.channel}|${agent}|${to}`, { channel: event.channel, agent, to });
+  }
+  for (const { channel, agent, to } of finals.values()) {
+    notices.push({
+      text: to
+        ? `Nuevo mensaje de ${peerLabel(agent)} a ${peerLabel(to)}`
+        : `${agent} respondió en ${channelLabel(channel)}`,
+      channel,
+    });
+  }
+
+  return notices;
+}
+
+/**
+ * The same notices as bare lines.
+ *
+ * Still the frame's `notifications`, because an APK is installed software that
+ * updates when its owner gets around to it: a phone carrying last month's build
+ * reads this field and must keep working. Desktop reads it too — the pet there
+ * has no per-channel question to answer, one screen showing everything is the
+ * whole point of it.
+ *
+ * @returns {string[]}
+ */
+export function mascotNotificationsFromEvents(events) {
+  return mascotNoticesFromEvents(events).map((notice) => notice.text);
+}

package/src/core/http-tools/browser.js

@@ -10,12 +10,13 @@
 // (no Chromium needed).
 //
 // Endpoints (mounted at /api/tools/browser by api.js):
-//   POST /navigate          { url, launch_options?, allow_dangerous? }
-//   POST /screenshot        { selector?, full_page?, width?, height?, encoded? }
-//   POST /click             { selector }
-//   POST /type              { selector, text, clear? }
-//   POST /select            { selector, value }
-//   POST /hover             { selector }
+//   POST /navigate          { url, launch_options?, allow_dangerous?, snapshot? }
+//   POST /snapshot          { selector?, interactive_only?, max_nodes? }
+//   POST /screenshot        { selector?, ref?, full_page?, width?, height?, encoded? }
+//   POST /click             { selector | ref, snapshot? }
+//   POST /type              { selector | ref, text, clear?, snapshot? }
+//   POST /select            { selector | ref, value, snapshot? }
+//   POST /hover             { selector | ref }
 //   POST /evaluate          { code }
 //   POST /get_text          { selector? }
 //   POST /get_content       { selector? }   // raw innerHTML
@@ -35,6 +36,8 @@ const _consoleLogs = [];
 
 const MAX_SCREENSHOT_BYTES = 2 * 1024 * 1024; // 2MB
 const MAX_CONTENT_CHARS    = 1 * 1024 * 1024; // 1MB
+const MAX_SNAPSHOT_NODES   = 400;
+const MAX_SNAPSHOT_CHARS   = 40 * 1024;
 
 // Args we always pass for stability + reduced attack surface.
 const SECURITY_ARGS = [
@@ -228,11 +231,328 @@ async function onPage(fn) {
   return withContextRetry(() => fn(page));
 }
 
+// ---------------------------------------------------------------------------
+// Accessibility snapshot + refs
+// ---------------------------------------------------------------------------
+//
+// Why this exists. A model driving Puppeteer by CSS selector has to invent the
+// selector out of browser_get_content's raw HTML — a megabyte of markup to find
+// one button, and a wrong guess most of the time. Snapshot walks the RENDERED
+// DOM instead and returns what a screen reader would announce: role, accessible
+// name, state, one line per element, with every control stamped `ref_N`. The
+// action tools take `{ ref }`, so the model clicks what it read rather than
+// what it inferred.
+//
+// Refs live in the page as `data-apx-ref` attributes and die with it. A
+// navigation or a re-render invalidates them; the action tools then say so by
+// name instead of failing on a mystery selector.
+
+// Runs INSIDE the page — must stay self-contained (page.evaluate stringifies
+// it, so it can close over nothing from this module).
+function collectA11yNodes({ rootSelector, interactiveOnly, maxNodes }) {
+  const SKIP_TAGS = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "HEAD", "SVG", "PATH", "IFRAME"]);
+  // Controls whose subtree the walk does not enter: their accessible name
+  // already carries the inner text, so descending only duplicates it.
+  const LEAF_TAGS = new Set(["A", "BUTTON", "INPUT", "SELECT", "TEXTAREA", "SUMMARY"]);
+  const INTERACTIVE_ROLES = new Set([
+    "button", "link", "checkbox", "radio", "tab", "menuitem", "menuitemcheckbox",
+    "menuitemradio", "option", "switch", "combobox", "textbox", "searchbox",
+    "slider", "spinbutton", "treeitem",
+  ]);
+  const TAG_ROLES = {
+    A: "link", BUTTON: "button", SELECT: "combobox", TEXTAREA: "textbox",
+    SUMMARY: "button", LABEL: "label", IMG: "img", FORM: "form", NAV: "navigation",
+    MAIN: "main", HEADER: "banner", FOOTER: "contentinfo", ASIDE: "complementary",
+    DIALOG: "dialog", TABLE: "table", TR: "row", ARTICLE: "article",
+    H1: "heading", H2: "heading", H3: "heading", H4: "heading", H5: "heading", H6: "heading",
+  };
+  // Emitted without a ref: they carry no action, they carry the grouping that
+  // tells one "Delete" apart from the next.
+  const LANDMARK_ROLES = new Set([
+    "navigation", "main", "banner", "contentinfo", "complementary", "dialog",
+    "form", "search", "region", "article", "table", "row", "tablist",
+  ]);
+
+  const nodes = [];
+  let refSeq = 0;
+  let truncated = false;
+
+  // A fresh snapshot retires the previous generation of refs, so a stale ref
+  // can never silently resolve to a different element after a re-render.
+  for (const el of document.querySelectorAll("[data-apx-ref]")) el.removeAttribute("data-apx-ref");
+
+  const root = rootSelector ? document.querySelector(rootSelector) : document.body;
+  if (!root) return { error: `Element not found: ${rootSelector}` };
+
+  const squash = (t, cap) => {
+    const v = String(t || "").replace(/\s+/g, " ").trim();
+    return v.length > cap ? v.slice(0, cap) + "…" : v;
+  };
+
+  function roleOf(el) {
+    const explicit = (el.getAttribute("role") || "").trim().toLowerCase();
+    if (explicit) return explicit.split(/\s+/)[0];
+    const tag = el.tagName;
+    if (tag === "INPUT") {
+      const t = (el.getAttribute("type") || "text").toLowerCase();
+      if (t === "checkbox") return "checkbox";
+      if (t === "radio") return "radio";
+      if (t === "submit" || t === "button" || t === "reset" || t === "image") return "button";
+      if (t === "range") return "slider";
+      if (t === "number") return "spinbutton";
+      if (t === "search") return "searchbox";
+      return "textbox";
+    }
+    if (tag === "A") return el.hasAttribute("href") ? "link" : "";
+    return TAG_ROLES[tag] || "";
+  }
+
+  function visible(el) {
+    if (el.hasAttribute("hidden")) return false;
+    if (el.getAttribute("aria-hidden") === "true") return false;
+    if (el.tagName === "INPUT" && (el.getAttribute("type") || "").toLowerCase() === "hidden") return false;
+    if (!el.getClientRects().length) return false;
+    const cs = getComputedStyle(el);
+    return !(cs.visibility === "hidden" || cs.display === "none" || cs.opacity === "0");
+  }
+
+  function nameOf(el) {
+    const aria = el.getAttribute("aria-label");
+    if (aria && aria.trim()) return squash(aria, 120);
+    const by = el.getAttribute("aria-labelledby");
+    if (by) {
+      const joined = by.split(/\s+/)
+        .map((id) => document.getElementById(id))
+        .filter(Boolean)
+        .map((n) => squash(n.innerText || n.textContent, 80))
+        .join(" ");
+      if (joined.trim()) return squash(joined, 120);
+    }
+    if (el.tagName === "IMG") return squash(el.getAttribute("alt"), 120);
+    if (el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.tagName === "SELECT") {
+      if (el.labels && el.labels.length) {
+        const l = squash(el.labels[0].innerText || el.labels[0].textContent, 80);
+        if (l) return l;
+      }
+      return squash(
+        el.getAttribute("placeholder") || el.getAttribute("title") || el.getAttribute("name"),
+        120
+      );
+    }
+    return squash(el.innerText || el.textContent, 120) || squash(el.getAttribute("title"), 120);
+  }
+
+  function isInteractive(el, role) {
+    const tag = el.tagName;
+    if (tag === "A") return el.hasAttribute("href");
+    if (LEAF_TAGS.has(tag)) return true;
+    if (el.isContentEditable) return true;
+    if (INTERACTIVE_ROLES.has(role)) return true;
+    const ti = el.getAttribute("tabindex");
+    if (ti !== null && ti !== "-1") return true;
+    return el.hasAttribute("onclick");
+  }
+
+  // Text owned by THIS element (its direct text-node children), so each run of
+  // page copy is attributed to exactly one node and never repeated up the tree.
+  function directText(el) {
+    let out = "";
+    for (const n of el.childNodes) if (n.nodeType === 3) out += n.nodeValue;
+    return squash(out, 300);
+  }
+
+  function walk(el, depth, parentName) {
+    if (nodes.length >= maxNodes) { truncated = true; return; }
+    if (SKIP_TAGS.has(el.tagName)) return;
+    if (!visible(el)) return;
+
+    const role = roleOf(el);
+    const interactive = isInteractive(el, role);
+    let emitted = false;
+    let ownName = parentName;
+
+    if (interactive) {
+      const ref = `ref_${++refSeq}`;
+      el.setAttribute("data-apx-ref", ref);
+      const name = nameOf(el);
+      const node = { depth, ref, role: role || "generic", name };
+      const type = el.tagName === "INPUT" ? (el.getAttribute("type") || "text").toLowerCase() : null;
+      if (type && type !== "text") node.type = type;
+      if (el.tagName === "A") {
+        const href = el.getAttribute("href");
+        if (href) node.href = squash(href, 120);
+      }
+      // A password field's value is never worth echoing back into a transcript.
+      const stateOnly = type === "checkbox" || type === "radio";
+      if (!stateOnly && type !== "password" && (el.tagName === "INPUT" || el.tagName === "TEXTAREA") && el.value) {
+        node.value = squash(el.value, 60);
+      }
+      if (el.tagName === "SELECT" && el.value) node.value = squash(el.value, 60);
+      if (el.checked) node.checked = true;
+      if (el.disabled || el.getAttribute("aria-disabled") === "true") node.disabled = true;
+      if (el.required) node.required = true;
+      const expanded = el.getAttribute("aria-expanded");
+      if (expanded !== null) node.expanded = expanded === "true";
+      if (el.getAttribute("aria-selected") === "true") node.selected = true;
+      nodes.push(node);
+      emitted = true;
+      ownName = name;
+    } else if (!interactiveOnly && LANDMARK_ROLES.has(role)) {
+      const label = squash(el.getAttribute("aria-label"), 80);
+      nodes.push(label ? { depth, role, name: label } : { depth, role });
+      emitted = true;
+    } else if (!interactiveOnly && role === "heading") {
+      const level = /^H[1-6]$/.test(el.tagName)
+        ? Number(el.tagName[1])
+        : Number(el.getAttribute("aria-level")) || null;
+      const name = squash(el.innerText || el.textContent, 160);
+      const node = { depth, role: "heading", name };
+      if (level) node.level = level;
+      nodes.push(node);
+      emitted = true;
+      ownName = name;
+    }
+
+    if (!interactiveOnly && !(el.tagName === "LABEL" && el.control)) {
+      const own = directText(el);
+      // Skip copy already spoken by the control that encloses it.
+      if (own && own.length > 1 && own !== ownName && own !== parentName) {
+        if (nodes.length >= maxNodes) truncated = true;
+        else nodes.push({ depth: emitted ? depth + 1 : depth, role: "text", name: own });
+      }
+    }
+
+    if (LEAF_TAGS.has(el.tagName)) return;
+    const childDepth = emitted ? depth + 1 : depth;
+    for (const child of el.children) walk(child, childDepth, ownName);
+  }
+
+  walk(root, 0, "");
+  return { url: location.href, title: document.title, nodes, truncated };
+}
+
+/**
+ * A structural node with no name and no children says nothing — layout tables
+ * alone can emit dozens of them. Drop it: a node is empty when the next node is
+ * not deeper than it is.
+ */
+export function pruneEmptyContainers(nodes) {
+  const list = nodes || [];
+  return list.filter((n, i) => {
+    if (n.ref || n.name) return true;
+    const next = list[i + 1];
+    return !!next && (Number(next.depth) || 0) > (Number(n.depth) || 0);
+  });
+}
+
+/** Render collected nodes as the indented, screen-reader-shaped text the model reads. */
+export function renderSnapshot(nodes, { maxChars = MAX_SNAPSHOT_CHARS } = {}) {
+  const lines = [];
+  let chars = 0;
+  let clipped = 0;
+  for (const n of pruneEmptyContainers(nodes)) {
+    const pad = "  ".repeat(Math.max(0, Math.min(Number(n.depth) || 0, 12)));
+    let line = `${pad}- ${n.role || "generic"}`;
+    if (n.name) line += ` ${JSON.stringify(n.name)}`;
+    if (n.ref) line += ` [${n.ref}]`;
+    const meta = [];
+    if (n.level) meta.push(`level=${n.level}`);
+    if (n.type) meta.push(`type=${n.type}`);
+    if (n.href) meta.push(`href=${n.href}`);
+    if (n.value) meta.push(`value=${JSON.stringify(n.value)}`);
+    if (n.checked) meta.push("checked");
+    if (n.selected) meta.push("selected");
+    if (n.expanded !== undefined) meta.push(`expanded=${n.expanded}`);
+    if (n.disabled) meta.push("disabled");
+    if (n.required) meta.push("required");
+    if (meta.length) line += ` {${meta.join(" ")}}`;
+    if (chars + line.length + 1 > maxChars) { clipped++; continue; }
+    chars += line.length + 1;
+    lines.push(line);
+  }
+  if (clipped) lines.push(`…(${clipped} more nodes omitted — narrow with selector or interactive_only)`);
+  return lines.join("\n");
+}
+
+/**
+ * The CSS selector an action tool should act on, from either addressing mode.
+ * `ref` wins when both are given; neither is an error the model can fix.
+ */
+export function resolveTarget({ ref, selector } = {}) {
+  if (ref !== undefined && ref !== null && String(ref).trim() !== "") {
+    const id = String(ref).trim();
+    if (!/^ref_\d+$/.test(id)) {
+      throw new Error(`invalid ref "${ref}" — refs look like "ref_12" and come from browser_snapshot`);
+    }
+    return `[data-apx-ref="${id}"]`;
+  }
+  if (selector !== undefined && selector !== null && String(selector).trim() !== "") {
+    return String(selector);
+  }
+  return null;
+}
+
+function requireTarget({ ref, selector }) {
+  const target = resolveTarget({ ref, selector });
+  if (!target) throw new Error("ref or selector required — call browser_snapshot first and act on a ref");
+  return target;
+}
+
+// Wait for the element, translating a missing ref into the one instruction
+// that actually unblocks the model: take a new snapshot.
+async function waitForTarget(page, target, ref, timeout = 10000) {
+  try {
+    await page.waitForSelector(target, { timeout });
+  } catch (e) {
+    if (ref) {
+      throw new Error(
+        `${ref} is no longer on the page — the DOM changed since the last browser_snapshot. ` +
+        `Call browser_snapshot again and use a fresh ref.`
+      );
+    }
+    throw e;
+  }
+}
+
+// Actions accept `snapshot: true` to return the post-action page state in the
+// same round trip, which is what keeps a multi-step flow from costing one extra
+// tool call per click.
+async function maybeSnapshot(want) {
+  if (!want) return undefined;
+  try {
+    const s = await browser_snapshot();
+    return s.snapshot;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function browser_snapshot({ selector, interactive_only = false, max_nodes } = {}) {
+  return onPage(async (page) => {
+    const cap = Math.min(Number(max_nodes) || MAX_SNAPSHOT_NODES, 1500);
+    const res = await page.evaluate(collectA11yNodes, {
+      rootSelector: selector ?? null,
+      interactiveOnly: !!interactive_only,
+      maxNodes: cap,
+    });
+    if (res?.error) throw new Error(res.error);
+    const snapshot = renderSnapshot(res.nodes);
+    return {
+      ok: true,
+      url: res.url,
+      title: res.title,
+      nodes: res.nodes.length,
+      truncated: !!res.truncated,
+      snapshot,
+    };
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Tool implementations
 // ---------------------------------------------------------------------------
 
-export async function browser_navigate({ url, launch_options, allow_dangerous, wait_until } = {}) {
+export async function browser_navigate({ url, launch_options, allow_dangerous, wait_until, snapshot } = {}) {
   if (!url) throw new Error("url required");
   const page = await ensureBrowser({ launch_options, allow_dangerous });
 
@@ -272,16 +592,19 @@ export async function browser_navigate({ url, launch_options, allow_dangerous, w
     title = "";
   }
 
+  const snap = await maybeSnapshot(snapshot);
   return {
     ok: true,
     url: page.url(),
     status: response?.status() ?? null,
     title,
     wait_until: response ? (preferred) : null,
+    ...(snap === undefined ? {} : { snapshot: snap }),
   };
 }
 
-export async function browser_screenshot({ selector, full_page = false, width, height, encoded = false, save_path, save_to_tmp = false } = {}) {
+export async function browser_screenshot({ selector, ref, full_page = false, width, height, encoded = false, save_path, save_to_tmp = false } = {}) {
+  const target = resolveTarget({ ref, selector });
   const page = await ensureBrowser();
   if (width || height) {
     await page.setViewport({
@@ -291,10 +614,10 @@ export async function browser_screenshot({ selector, full_page = false, width, h
   }
 
   const buf = await withContextRetry(async () => {
-    const target = selector ? await page.$(selector) : null;
-    if (selector && !target) throw new Error(`Element not found: ${selector}`);
-    return target
-      ? await target.screenshot({ type: "png", encoding: "base64" })
+    const handle = target ? await page.$(target) : null;
+    if (target && !handle) throw new Error(`Element not found: ${ref || selector}`);
+    return handle
+      ? await handle.screenshot({ type: "png", encoding: "base64" })
       : await page.screenshot({ type: "png", encoding: "base64", fullPage: !!full_page });
   });
 
@@ -331,49 +654,55 @@ export async function browser_screenshot({ selector, full_page = false, width, h
   };
 }
 
-export async function browser_click({ selector } = {}) {
-  if (!selector) throw new Error("selector required");
-  return onPage(async (page) => {
-    await page.waitForSelector(selector, { timeout: 10000 });
-    await page.click(selector);
+export async function browser_click({ selector, ref, snapshot } = {}) {
+  const target = requireTarget({ ref, selector });
+  const res = await onPage(async (page) => {
+    await waitForTarget(page, target, ref);
+    await page.click(target);
     await page.waitForNetworkIdle({ timeout: 5000 }).catch(() => {});
-    return { ok: true, selector, url: page.url() };
+    return { ok: true, ref: ref ?? null, selector: selector ?? null, url: page.url() };
   });
+  const snap = await maybeSnapshot(snapshot);
+  return snap === undefined ? res : { ...res, snapshot: snap };
 }
 
-export async function browser_type({ selector, text, clear = true } = {}) {
-  if (!selector) throw new Error("selector required");
+export async function browser_type({ selector, ref, text, clear = true, snapshot } = {}) {
+  const target = requireTarget({ ref, selector });
   if (text === undefined) throw new Error("text required");
-  return onPage(async (page) => {
-    await page.waitForSelector(selector, { timeout: 10000 });
-    await page.focus(selector);
+  const res = await onPage(async (page) => {
+    await waitForTarget(page, target, ref);
+    await page.focus(target);
     if (clear) {
       await page.keyboard.down("Control");
       await page.keyboard.press("KeyA");
       await page.keyboard.up("Control");
       await page.keyboard.press("Backspace");
     }
-    await page.type(selector, String(text), { delay: 20 });
-    return { ok: true, selector, typed: String(text).length };
+    await page.type(target, String(text), { delay: 20 });
+    return { ok: true, ref: ref ?? null, selector: selector ?? null, typed: String(text).length };
   });
+  const snap = await maybeSnapshot(snapshot);
+  return snap === undefined ? res : { ...res, snapshot: snap };
 }
 
-export async function browser_select({ selector, value } = {}) {
-  if (!selector) throw new Error("selector required");
+export async function browser_select({ selector, ref, value, snapshot } = {}) {
+  const target = requireTarget({ ref, selector });
   if (value === undefined) throw new Error("value required");
-  return onPage(async (page) => {
-    await page.waitForSelector(selector, { timeout: 10000 });
-    await page.select(selector, String(value));
-    return { ok: true, selector, value };
+  const res = await onPage(async (page) => {
+    await waitForTarget(page, target, ref);
+    await page.select(target, String(value));
+    return { ok: true, ref: ref ?? null, selector: selector ?? null, value };
   });
+  const snap = await maybeSnapshot(snapshot);
+  return snap === undefined ? res : { ...res, snapshot: snap };
 }
 
-export async function browser_hover({ selector } = {}) {
-  if (!selector) throw new Error("selector required");
+export async function browser_hover({ selector, ref } = {}) {
+  const target = requireTarget({ ref, selector });
   return onPage(async (page) => {
-    await page.waitForSelector(selector, { timeout: 10000 });
-    await page.hover(selector);
-    return { ok: true, selector };
+    await waitForTarget(page, target, ref);
+    await page.hover(target);
+    return { ok: true, ref: ref ?? null, selector: selector ?? null };
   });
 }
 
@@ -511,6 +840,7 @@ export function buildBrowserRouter(express) {
   };
 
   router.post("/navigate",          wrap(browser_navigate));
+  router.post("/snapshot",          wrap(browser_snapshot));
   router.post("/screenshot",        wrap(browser_screenshot));
   router.post("/click",             wrap(browser_click));
   router.post("/type",              wrap(browser_type));