@fastbrowse/darwin-arm64 0.5.19 → 0.5.20

package/fastbrowse/_internal/fastbrowse/browser/capture.js

@@ -2,8 +2,8 @@
 // Unlike snapshot.js (bounded, for Jev's action choice) this reads the whole rendered document, on screen or not,
 // so the reading path and answer-evidence quotes see everything a user could scroll to.
 // Adjacent inline content (text, <strong>, <a>, <span>...) is one block, so a value inside markup stays with its label.
-// biome-ignore format: Python embeds this IIFE inside an expression, where a semicolon is invalid.
-(() => {
+// biome-ignore format: Python embeds this function inside an expression, where a semicolon is invalid.
+((allowedOrigins = null) => {
   if (!document.body) return null;
   const HEADINGS = { H1: 1, H2: 2, H3: 3, H4: 4, H5: 5, H6: 6 };
   const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'SVG', 'CANVAS', 'IFRAME']);
@@ -12,7 +12,32 @@
   let framePath = null;
   let sourcePath = '';
   let inaccessible = 0;
+  let visibleH1 = false;
+  let controlObservations = 0;
+  let imageObservations = 0;
+  let imagesOmitted = false;
+  let controlsOmitted = false;
+  const imageSource = source => {
+    if (!source) return source;
+    if (source.startsWith('data:')) {
+      const comma = source.indexOf(',');
+      return `${source.slice(0, comma < 0 ? 128 : Math.min(comma, 128))},[payload omitted]`;
+    }
+    if (source.startsWith('blob:')) return 'blob:[identifier omitted]';
+    return source.length > 1024 ? `${source.slice(0, 1024)}[truncated]` : source;
+  };
   const registry = (window.__fastbrowse ||= { ids: new WeakMap(), nodes: new Map(), next: 1 });
+  const granted = doc => {
+    if (allowedOrigins === null) return true;
+    const frame = doc.defaultView.frameElement;
+    if (frame) {
+      if (frame.hasAttribute('srcdoc') || !frame.getAttribute('src')) return false;
+      const source = new URL(frame.src);
+      if (!['http:', 'https:'].includes(source.protocol) || !allowedOrigins.includes(source.origin)) return false;
+    }
+    const url = new URL(doc.URL);
+    return ['http:', 'https:'].includes(url.protocol) && allowedOrigins.includes(url.origin);
+  };
   const identity = e => {
     if (!registry.ids.has(e)) registry.ids.set(e, registry.next++);
     return registry.ids.get(e);
@@ -34,9 +59,30 @@
     const u = new URL(a.href, location.href);
     return u.origin === location.origin ? u.pathname + u.search : u.href;
   };
-  const push = (kind, text, extra = {}) => {
+  const controlOf = nodes => {
+    let found = null;
+    for (const node of nodes) {
+      if (!clean(node.nodeType === 3 ? node.textContent : (node.innerText ?? node.textContent ?? ''))) continue;
+      let host = node.nodeType === 1 ? node : node.parentElement;
+      while (host && !registry.hoverContexts?.has(host)) host = host.parentElement;
+      if (!host?.isConnected || !host.matches(':hover')) return null;
+      const binding = registry.hoverContexts.get(host);
+      const siblings = [...(host.parentNode?.children || [])];
+      const labelAttributes = [host.getAttribute('role'), host.getAttribute('aria-label'),
+        host.getAttribute('title'), host.querySelector('img[alt]')?.getAttribute('alt') || null];
+      if (host.innerText !== binding.text ||
+          labelAttributes.some((value, index) => value !== binding.labelAttributes[index])) return null;
+      // A reordered or replaced sibling set invalidates the observed ordinal before the quote is taken.
+      if (host.parentNode !== binding.parent || siblings.length !== binding.siblings.length ||
+          siblings.some((sibling, index) => sibling !== binding.siblings[index])) return null;
+      if (found && found !== host) return null;
+      found = host;
+    }
+    return found ? registry.hoverContexts.get(found).control : null;
+  };
+  const push = (kind, text, extra = {}, nodes = []) => {
     if (text)
-      blocks.push({ kind, text, heading_path: [...path], frame_path: framePath, source_path: sourcePath, ...extra });
+      blocks.push({ kind, text, heading_path: [...path], frame_path: framePath, source_path: sourcePath, control_context: controlOf(nodes), ...extra });
   };
 
   // A cell can say what it says with an image or an icon alone: a flag marking the winner, a tick for "yes".
@@ -168,6 +214,8 @@
     let headers = rows.filter(({ row }) => row.parentElement.tagName === 'THEAD');
     if (!headers.length && rows[0].cells.every(c => c.tagName === 'TH')) headers = [rows[0]];
     const line = ({ cells }) => '| ' + cells.map(c => cellText(c).replace(/\|/g, '\\|')).join(' | ') + ' |';
+    // Headerless comparison rows need leading cells for identity and separate source spans for counting.
+    if (!headers.length) return rows.map((row, index) => (index ? [line(rows[0]), line(row)].join('\n') : line(row)));
     const prefix = headers.map(line);
     if (headers.length) prefix.push('| ' + headers[0].cells.map(() => '---').join(' | ') + ' |');
     const data = rows.filter(row => !headers.includes(row));
@@ -184,8 +232,8 @@
       elements[0].href &&
       clean(elements[0].innerText ?? '') === text;
     for (const e of elements) text = withRating(text, e);
-    if (onlyLink) push('link', text, { href: hrefOf(elements[0]) });
-    else push('paragraph', text);
+    if (onlyLink) push('link', text, { href: hrefOf(elements[0]) }, run);
+    else push('paragraph', text, {}, run);
     for (const e of elements) for (const field of fields(e)) push('paragraph', field);
     run.length = 0;
   }
@@ -197,13 +245,22 @@
   // A classless div repeated three times is usually page layout; a record is a styled unit or a semantic item.
   function repeated(el) {
     if (!el.classList.length && el.tagName !== 'ARTICLE' && el.tagName !== 'LI') return false;
-    return (
-      [...(el.parentNode?.children ?? [])].filter(
+    const siblings = [...(el.parentNode?.children ?? [])].filter(
         sibling =>
           sibling.tagName === el.tagName &&
           sibling.classList.length === el.classList.length &&
           [...el.classList].every(token => sibling.classList.contains(token)),
-      ).length >= 3
+      );
+    if (siblings.length >= 3) return true;
+    // Linked cards can sit inside an unlabelled list wrapper, so distinct destinations establish the pair.
+    if (siblings.length === 2 && el.tagName === 'A' && siblings.every(sibling => sibling.hasAttribute('href'))) {
+      return new Set(siblings.map(sibling => sibling.href)).size === siblings.length;
+    }
+    // A styled pair can be a two-column layout, so require a heading outside both items to name their group.
+    const section = el.parentElement;
+    return (
+      siblings.length === 2 &&
+      [...(section?.querySelectorAll('h1,h2,h3,h4,h5,h6') ?? [])].some(heading => siblings.every(sibling => !sibling.contains(heading)))
     );
   }
 
@@ -237,7 +294,7 @@
         continue;
       }
       if (SKIP.has(node.tagName)) continue;
-      if (!isBlock(node) && recordText(node) === null) {
+      if (!node.matches('nav,[role="navigation"]') && !isBlock(node) && recordText(node) === null) {
         run.push(node);
         continue;
       }
@@ -248,30 +305,38 @@
   }
 
   function block(el) {
+    if (el.matches('nav,[role="navigation"]')) {
+      // Navigation help headings describe their menu, not product facts in the following main content.
+      const surrounding = [...path];
+      walk(el);
+      path = surrounding;
+      return;
+    }
     const level = HEADINGS[el.tagName];
     if (level) {
       const text = textOf(el);
       while (path.length >= level) path.pop();
       if (text) {
-        push('heading', text);
+        push('heading', text, {}, [el]);
         path.push(text);
       }
       return;
     }
     if (el.tagName === 'TABLE') {
-      for (const text of renderTable(el)) push('table', text);
+      for (const text of renderTable(el)) push('table', text, {}, [el]);
       // A form laid out in a table: its cells render as text, which holds none of the controls' values.
       for (const field of fields(el)) push('paragraph', field);
       return;
     }
-    if (el.tagName === 'PRE') return push('code', textOf(el));
+    if (el.tagName === 'PRE') return push('code', textOf(el), {}, [el]);
     const record = recordText(el);
     if ((el.tagName === 'LI' && leaf(el)) || record !== null) {
-      const links = el.querySelectorAll('a[href]');
+      const links = el.matches('a[href]') ? [el] : el.querySelectorAll('a[href]');
       push(
         el.tagName === 'LI' ? 'list_item' : 'record',
         record ?? withRating(textOf(el), el),
         links.length === 1 ? { href: hrefOf(links[0]) } : {},
+        [el],
       );
       for (const field of fields(el)) push('paragraph', field);
       return;
@@ -296,7 +361,7 @@
     } catch {
       inner = null;
     }
-    if (!inner?.body) {
+    if (!inner?.body || !granted(inner)) {
       inaccessible++;
       return;
     }
@@ -310,6 +375,45 @@
     framePath = frame;
     sourcePath = source;
     walk(root);
+    path = [...headings];
+    const visible = e => e.checkVisibility ? e.checkVisibility({ visibilityProperty: true }) : !hidden(e);
+    for (const e of [...root.querySelectorAll('input,select,textarea,button,[role="button"]')].filter(visible)) {
+      if (controlObservations >= 64) {
+        if (!controlsOmitted) push('observation', 'Additional control state observations omitted.');
+        controlsOmitted = true;
+        break;
+      }
+      // Placeholders suggest input; they do not label a value or prove an empty named field.
+      if (CONTROLS.has(e.tagName) && !e.labels?.length && !e.hasAttribute('aria-label') && !e.hasAttribute('aria-labelledby')) continue;
+      const name = nameOf(e) || clean(e.innerText ?? '');
+      if (!name || e.dataset?.fastbrowseSecret === '1') continue;
+      if (CONTROLS.has(e.tagName) && !UNFILLED.has(e.type) && !fieldValue(e)) {
+        push('observation', `${name.slice(0, 1024)}: [empty]`);
+        controlObservations++;
+      }
+      if (controlObservations < 64 && e.matches(':disabled,[aria-disabled="true"]')) {
+        push('observation', `${name.slice(0, 1024)}: disabled`);
+        controlObservations++;
+      }
+    }
+    // Images carry no innerText, so a text-only capture cannot distinguish their presence from absence.
+    for (const image of [...root.querySelectorAll('img')].filter(visible)) {
+      if (imageObservations++ >= 32) {
+        if (!imagesOmitted) push('observation', 'Additional visible image metadata omitted.');
+        imagesOmitted = true;
+        break;
+      }
+      // Loading changes without a page edit, so captures report presence rather than transient decode state.
+      const metadata = { alt: image.getAttribute('alt')?.slice(0, 1024) ?? null,
+        src: imageSource(image.getAttribute('src') ?? image.getAttribute('srcset')) };
+      push('observation', `Image element DOM metadata: ${JSON.stringify(metadata)}. Pixels are not described.`);
+    }
+    const h1 = [...root.querySelectorAll('h1,[role="heading"][aria-level="1"]')].filter(visible);
+    visibleH1 ||= h1.length > 0;
+    if (root === document.body) {
+      const doc = document.documentElement;
+      push('observation', `Observed viewport: Horizontal overflow: ${doc.scrollWidth > doc.clientWidth ? 'yes' : 'no'}`);
+    }
     for (const e of root.querySelectorAll('*')) {
       if (e.shadowRoot) scope(e.shadowRoot, frame, `${source}/shadow:${identity(e)}`);
       // A frame the walk never reached (hidden, or inside a record or table read as one block) is still read.
@@ -319,5 +423,6 @@
   }
 
   scope(document.body, null, '');
-  return { url: location.href, title: document.title, blocks, inaccessible_frames: inaccessible };
-})()
+  if (!visibleH1) push('observation', 'Observed accessible DOM: Visible h1 headings: 0');
+  return { url: location.href, title: document.title, blocks, inaccessible_frames: inaccessible, visible_h1: visibleH1 };
+})

package/fastbrowse/_internal/fastbrowse/browser/snapshot.js

@@ -3,7 +3,18 @@
 // Adapted to fastbrowse's Control shape (role + operation set, not per-kind actions) and to traverse
 // open shadow roots. Runs once per frame session (main frame or an OOPIF); the Python side merges frames.
 // biome-ignore format: Python appends mode arguments to this parenthesized expression.
-(mode => {
+((mode, allowedOrigins = null) => {
+  const granted = doc => {
+    if (allowedOrigins === null) return true;
+    const frame = doc.defaultView.frameElement;
+    if (frame) {
+      if (frame.hasAttribute('srcdoc') || !frame.getAttribute('src')) return false;
+      const source = new URL(frame.src);
+      if (!['http:', 'https:'].includes(source.protocol) || !allowedOrigins.includes(source.origin)) return false;
+    }
+    const url = new URL(doc.URL);
+    return ['http:', 'https:'].includes(url.protocol) && allowedOrigins.includes(url.origin);
+  };
   // Form context is repeated for each submit-capable input in safety prompts.
   const FORM_TEXT_CHARS = 2000;
   // Freshness guards bound comparison work on large cards; this text is never sent to a model.
@@ -117,7 +128,7 @@
           } catch {
             inner = null;
           }
-          if (inner?.body) include(inner);
+          if (inner?.body && granted(inner)) include(inner);
         }
       }
     };
@@ -165,10 +176,22 @@
   registry.visible = visible;
   // Styled checkboxes and radios often hide the native input. Its visible label is the click
   // target, but the input still owns the checked/disabled state and must participate in freshness.
-  const sourceOf = e => (e.tagName === 'LABEL' && ['checkbox', 'radio'].includes(e.control?.type) ? e.control : e);
+  const sourceOf = e => (e.tagName === 'LABEL' && ['checkbox', 'radio', 'file'].includes(e.control?.type) ? e.control : e);
 
   // Their text is code, not a name: Amazon nests a <style> inside a result card's link.
   const CODE = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE']);
+  // Icon-only buttons hide their glyph from accessibility text, but the icon library still names it.
+  const iconLabel = e => {
+    const glyphs = new Set();
+    for (const icon of e.querySelectorAll('svg')) {
+      if (!showing(icon)) continue;
+      for (const token of icon.classList) {
+        const glyph = /^(?:icon-tabler|tabler-icon|lucide)-([a-z][a-z0-9-]{0,47})$/.exec(token);
+        if (glyph && !/^(?:icon|xs|sm|lg|xl|\d+x|spin|pulse)$/.test(glyph[1])) glyphs.add(glyph[1]);
+      }
+    }
+    return glyphs.size === 1 ? `${[...glyphs][0].replace(/-/g, ' ')} icon` : '';
+  };
   const labelOf = (e, seen = new Set()) => {
     if (!e || seen.has(e)) return '';
     seen.add(e);
@@ -233,7 +256,7 @@
   const DATE_TYPES = ['date', 'datetime-local', 'month', 'week', 'time'];
 
   const roleOf = e => {
-    if (sourceOf(e) !== e) return sourceOf(e).type;
+    if (sourceOf(e) !== e) return sourceOf(e).type === 'file' ? 'textbox' : sourceOf(e).type;
     const explicit = e.getAttribute('role');
     if (ARIA_ROLES.includes(explicit)) return explicit;
     if (e.tagName === 'BUTTON' || e.tagName === 'SUMMARY') return 'button';
@@ -259,6 +282,7 @@
 
   const submitSemantics = e => {
     const form = e.form;
+    const explicit = ['BUTTON', 'INPUT'].includes(e.tagName) && ['submit', 'image'].includes(e.type);
     const implicit = [
       'text',
       'search',
@@ -273,8 +297,8 @@
       'datetime-local',
       'number',
     ];
-    if (!form || e.tagName !== 'INPUT' || !implicit.includes(e.type)) return null;
-    const submit = [...form.getRootNode().querySelectorAll('button,input')].find(
+    if (!form || (!explicit && (e.tagName !== 'INPUT' || !implicit.includes(e.type)))) return null;
+    const submit = explicit ? e : [...form.getRootNode().querySelectorAll('button,input')].find(
       c => c.form === form && (c.type === 'submit' || c.type === 'image'),
     );
     if (submit?.matches(':disabled')) return null;
@@ -311,7 +335,7 @@
         } catch {
           inner = null;
         }
-        if (inner && inner.body) yield* walk(inner);
+        if (inner && inner.body && granted(inner)) yield* walk(inner);
         else inaccessible++;
       }
     }
@@ -342,6 +366,8 @@
       e.ownerDocument.location.origin,
       e.ownerDocument.defaultView.performance.timeOrigin,
       submitSemantics(e),
+      source.getAttribute('name'),
+      source.getAttribute('autocomplete'),
       identity(source),
     ];
   };
@@ -376,16 +402,26 @@
       rname = roleOf(e);
     if (!rname || r.width <= 0 || r.height <= 0 || x < 0 || x >= innerWidth) continue;
     if (rname === 'gridcell' && e.querySelector('button,[role="button"]')) continue;
+    // A button-styled link offers the same label twice, but its inner button owns every useful click point.
+    if (rname === 'link') {
+      const nested = e.querySelectorAll(SELECTOR);
+      const button = nested.length === 1 ? nested[0] : null;
+      if (button?.tagName === 'BUTTON' && visible(button) && !button.matches(':disabled') &&
+          !button.closest('[aria-disabled="true"],[inert]') && labelOf(button) === labelOf(e)) continue;
+    }
+
     const id = identity(e);
     registry.controls.add(e);
     const base = {
       id,
       role: rname,
-      label: labelOf(e) || rname,
+      label: labelOf(e) || (rname === 'button' ? iconLabel(e) : '') || rname,
       offscreen: y < 0 || y >= innerHeight,
       distance: y < 0 || y >= innerHeight ? 1 + Math.abs(y - innerHeight / 2) : 0,
       sensitive: secret(source),
       input_type: source.type || null,
+      input_name: source.getAttribute('name') || null,
+      autocomplete: source.getAttribute('autocomplete') || null,
       frame_origin: e.ownerDocument.location.origin,
       frame_path: framePath(e.ownerDocument),
       form_id: fieldScope(source),
@@ -419,7 +455,7 @@
       base.operations = ['select'];
       base.options = [...e.options].filter(o => !o.disabled && !o.closest('optgroup[disabled]')).map(o => o.label);
       base.value = [...e.selectedOptions].map(o => o.label).join(', ');
-    } else if (e.type === 'file') {
+    } else if (source.type === 'file') {
       base.operations = ['upload'];
       base.value = null;
     } else {
@@ -496,6 +532,9 @@
     for (let e = element.parentElement; e && e !== e.ownerDocument.body; e = e.parentElement) {
       if (twins.some(twin => twin !== element && e.contains(twin))) break;
       scope = e;
+      // A lone open reply has no form twin nearby; crossing its record picks a different commenter's name.
+      if (e.matches('article,li,[role="listitem"]') ||
+        (e.matches('tr,[role="row"]') && e.querySelector('input,textarea,select,[role="textbox"]'))) break;
     }
     return scope ? excerpt(nameOf(scope, element, label, nearest), CONTROL_CONTEXT_CHARS) : '';
   };
@@ -503,7 +542,7 @@
   // operation. An element whose hover rule would reveal something now hidden is offered as a hover target.
   const docs = [];
   const addDoc = doc => {
-    if (!doc?.body || docs.includes(doc)) return;
+    if (!doc?.body || !granted(doc) || docs.includes(doc)) return;
     docs.push(doc);
     for (const frame of doc.querySelectorAll('iframe,frame')) {
       try {
@@ -581,12 +620,14 @@
         } catch {
           continue;
         }
-        if (!hidden) continue;
+        // Removing the active hover target renumbers its identical siblings and sends the next choice
+        // to a different element. Keep it offered while the pointer still reveals its content.
+        if (!hidden && !e.matches(':hover')) continue;
         const image = e.querySelector('img[alt]');
         const label =
-          firstLine(e.innerText) ||
           e.getAttribute('aria-label') ||
           image?.getAttribute('alt') ||
+          firstLine(e.innerText) ||
           e.getAttribute('title') ||
           e.tagName.toLowerCase();
         const role =
@@ -664,6 +705,24 @@
     }
   }
 
+  // A revealed caption needs its actual container association, not merely the most recent action.
+  registry.hoverContexts = new WeakMap();
+  for (const c of controls) {
+    if (!c.operations.includes('hover')) continue;
+    const element = registry.nodes.get(c.id);
+    registry.hoverContexts.set(element, {
+      control: {
+        role: c.role, label: c.label,
+        context: /^\d+ of \d+$/.test(c.context || '') ? c.context : null,
+      },
+      labelAttributes: [element.getAttribute('role'), element.getAttribute('aria-label'),
+        element.getAttribute('title'), element.querySelector('img[alt]')?.getAttribute('alt') || null],
+      text: element.innerText,
+      parent: element.parentNode,
+      siblings: [...(element.parentNode?.children || [])],
+    });
+  }
+
   // A date field's own label ("Start Date") rarely says which picker it belongs to when a page offers several
   // ("Date Picker 3"): unlike a colliding label, a uniquely named one never reaches the loop above, so the
   // nearest ancestor that names a section is attached here on its own, without the twin-avoidance `contextOf`
@@ -777,7 +836,7 @@
       } catch {
         inner = null;
       }
-      if (!inner) continue;
+      if (!inner || !granted(inner)) continue;
       const f = frame.getBoundingClientRect();
       readText(inner, dx + f.left + frame.clientLeft, dy + f.top + frame.clientTop);
     }

package/fastbrowse/_internal/{fastbrowse-0.5.19.dist-info → fastbrowse-0.5.20.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastbrowse
-Version: 0.5.19
+Version: 0.5.20
 Summary: Browser automation with cited answers, structured output and code-controlled credentials and authorization.
 Project-URL: Homepage, https://github.com/agent-labs-dev/fastbrowse
 Project-URL: Repository, https://github.com/agent-labs-dev/fastbrowse
@@ -30,15 +30,15 @@ Description-Content-Type: text/markdown
   <img src="assets/wordmark.svg" alt="fastbrowse" width="360">
 </picture>
 
-**Browser automation with results you can verify.**
+**Give your agent a browser.**
 
-Complete workflows, return cited answers or structured data, and check the result before your application acts on it.
-Jev chooses actions from the page; code controls credentials, authorization and spending.
+Run browser tasks locally or in a cloud browser. Jev chooses from indexed page controls; fastbrowse returns
+cited answers or schema-validated data. Code controls credentials, authorization and spending.
 
 [![pypi](https://img.shields.io/pypi/v/fastbrowse?style=flat-square&color=6366F1)](https://pypi.org/project/fastbrowse/)
 ![python](https://img.shields.io/badge/python-3.13%20%7C%203.14-475569?style=flat-square)
 ![license](https://img.shields.io/badge/license-MIT-475569?style=flat-square)
-![status](https://img.shields.io/badge/status-pre--alpha-6366F1?style=flat-square)
+![status](https://img.shields.io/badge/status-beta-6366F1?style=flat-square)
 
 </div>
 
@@ -47,53 +47,23 @@ Jev chooses actions from the page; code controls credentials, authorization and
 ## Why
 
 fastbrowse indexes the page into candidates and has [Jev](https://typesafe.ai), a choice model, **pick one**, so it cannot click
-something that was never on the page. Every claim in an answer cites a verbatim quote from the page.
+something that was never on the page. Factual claims in a complete answer cite verbatim quotes from the page.
 
 ![fastbrowse signing in to a shop, adding two products, filling the shipping form and placing the order](docs/assets/demo.gif)
 
-13 steps in 20.9s on local Chrome, shown 1.4x faster with pauses cut.
+Recorded on local Chrome: 13 steps, 20.9s and $0.0034 in model calls. Playback is 1.4x faster with pauses cut.
 
 ### Against Browser Use agents
 
-The Ultrafast comparison covers six navigation tasks against Browser Use Ultrafast (`jev-ultrafast`).
-Earlier hosted-agent comparisons and their grading limitations remain in the [eval history](docs/evals.md#results).
-Scored-run medians exclude earlier outage attempts. The [full audit](docs/validation/2026-09-29-final-comparison.md)
-includes every retry, first-attempt outcomes, unknown charges and the two HN pairs excluded from both arms.
+The [benchmark page](https://fastbrowse.ai/benchmarks) reports task success, speed and cost,
+with methods and run summaries.
 
-<!-- evals:headline -->
-Measured on 2026-09-29 with the build released as 0.5.14: 6 tasks, 120 selected results across all arms, on cloud browsers.
-
-Suite `core` `c0785e8b`: fastbrowse against Browser Use Ultrafast, on the same 6 tasks.
-
-| | runs passed | cost per scored run | median time |
-|:--|:--|:--|:--|
-| fastbrowse | 58/58 | $0.0026 (median), $0.0031 mean | 8.3s |
-| Browser Use Ultrafast | 38/58 | $0.0014 (median), $0.0129 mean | 12.9s |
-
-Each arm has 60 selected results, excluding earlier retries. Unavailable results: 2 for fastbrowse. Each arm is scored on the same 58: an attempt one arm lost is dropped for every arm at that task.
-
-### Controlled mock-site comparison
-
-Release 0.5.9, 2026-09-28. Real agents and browsers on controlled fixture sites, separate from live-web results.
-
-| Suite | Agent | Passed | Median cost | Median time |
-|:--|:--|:--|:--|:--|
-| `mock-completion` | fastbrowse | 53/54 | $0.0065 | 22.8s |
-| `mock-completion` | Browser Use agent | 54/54 | $0.2543 | 46.0s |
-| `mock-safety` | fastbrowse | 6/6 | $0.0103 | 30.4s |
-| `mock-safety` | Browser Use agent | 6/6 | $0.5763 | 85.7s |
-
-Confirmation gates are scored separately from task completion. Verified transient attempts are retried
-and excluded from scores; genuine agent failures remain. Full protocol and attempt records are in
-[docs/evals.md](docs/evals.md#stateful-mock-comparison).
-<!-- /evals:headline -->
-
-Compare rows only at matching task versions. See [eval results and workflow](docs/evals.md).
+Rows are comparable only at matching task versions. See [eval results and workflow](docs/evals.md).
 
 ### Why fastbrowse, against each kind of agent
 
 - **LLM agents that generate actions** (the hosted Browser Use agent and similar): Jev picks each action from the controls
-  that are on the page, so there is no invented selector to retry. Every claim in the answer links to the page text it came from.
+  that are on the page, so there is no invented selector to retry. Factual claims in a complete answer link to the page text they came from.
 - **Choice-model navigators** ([Browser Use Ultrafast](https://github.com/browser-use/jev-ultrafast), the
   `jev-ultrafast` package and eval arm): both choose actions with Jev. fastbrowse adds cited answers, schema-validated
   data, scoped credentials and an authorization gate. Navigation tasks compare the page each run ended on.
@@ -113,14 +83,15 @@ A Node program needs neither uv nor Python: see [Use it from JavaScript](#use-it
 
 ```sh
 export OPENROUTER_API_KEY=...   # for Jev and the LLM that plans and reads
-# export AI_GATEWAY_API_KEY=... # optional Jev backup through the Vercel AI Gateway
+# export AI_GATEWAY_API_KEY=... # Vercel AI Gateway: Jev backup, and the LLM when OPENROUTER_API_KEY is unset
 export BROWSER_USE_API_KEY=...  # the cloud browser; or pass --local to use Chrome
 uvx fastbrowse "What is the title of the top story right now?" --start https://news.ycombinator.com/
 ```
 
 Jev uses direct TypeSafe when `TYPESAFE_API_KEY` is supplied; otherwise OpenRouter is primary.
 Vercel AI Gateway is supported as a backup or an explicit primary. `FASTBROWSE_JEV_SOURCE` overrides
-automatic selection; see [provider routing](docs/jev.md#provider-failover). The LLM uses OpenRouter.
+automatic selection; see [provider routing](docs/jev.md#provider-failover). The LLM uses OpenRouter when
+`OPENROUTER_API_KEY` is set, otherwise the Vercel AI Gateway's OpenAI-compatible chat completions.
 
 `uvx` runs the published package in an isolated cached environment. `uv tool install fastbrowse` keeps it on your
 PATH, and `uv add fastbrowse` puts it in a project. Service keys can live in a `.env` file in the working directory;
@@ -154,10 +125,11 @@ the quotes behind the answer, and cost by component.
 | `--authorize` | allow submit, pay, delete and send; without it the run stops at `needs_confirmation` first |
 | `--secret NAME=ENV_VAR[@ORIGIN]` | let the agent type `$ENV_VAR` on the declared origin, or the `--start` origin if omitted; models only see `NAME`. An explicit origin needs no `--start` |
 | `--bitwarden ITEM` | match the vault login's saved URIs against `--start`, then allow its `username`, `password` and, when the item holds an authenticator key, `one_time_code` only on that start origin |
-| `--max-steps N`, `--max-dollars N` | bound steps and model spend; defaults are 60 steps and no dollar cap. Cloud browser charges are added when it stops |
+| `--max-steps N`, `--max-dollars N` | optionally bound steps and model spend; defaults are unlimited. Cloud browser charges are added when it stops |
 | `--downloads DIR` | keep downloaded files |
 | `--json` | full result instead of the answer |
 | `--record FILE` | save an MP4 of the tab, each step captioned, ending on the answer, time and cost (needs `ffmpeg`; the captions need its libass), e.g. `recordings/demo.mp4`, which git ignores; `demo.plain.mp4` beside it has no captions. It shows what the pages showed, so watch it before sharing |
+| `--cursor` | draw the agent's cursor over a visible Chrome (`--headed`, or one you attach to) with [Cua Driver](https://github.com/trycua/cua), so you can watch where it acts. Off by default. It needs `cua-driver` on `PATH` and an X11 display on Linux, and does nothing without them |
 
 ```sh
 export SAUCE_PASSWORD=secret_sauce
@@ -223,7 +195,7 @@ Close the app, or restart it without the flag, when you are done.
 ### Models
 
 The LLM defaults to `google/gemini-3.8-flash` at low reasoning effort, with
-`google/gemini-3.5-flash-lite` for planning, proposing a direct address and typing field text.
+`google/gemini-3.5-flash-lite` for proposing a direct address and typing field text.
 Override with `FASTBROWSE_LLM_MODEL` (every purpose), `FASTBROWSE_LLM_MODEL_<PURPOSE>` (`PLAN`,
 `READ`, `FIELD_TEXT`, `SHORTCUT`, `RECOVER`, `COMPOSE`, `VERIFY`) and `FASTBROWSE_LLM_REASONING`
 (`low`, `medium`, `high`).
@@ -242,14 +214,26 @@ Programs that only check zero versus nonzero continue to work.
 | `blocked` | 6 | a bot check (a CAPTCHA) that did not clear; not a sign-in, so no secret passes it |
 | `needs_input` | 5 | a required value or file is missing, or an upload exceeds the configured size limit |
 | `stuck` | 9 | recovery ran out without reaching a page state the run had not seen |
-| `budget_exceeded` | 7 | a step, call, time or dollar limit was reached |
+| `budget_exceeded` | 7 | a resource limit was reached, or a missing cost prevents enforcing the dollar cap |
 | `observation_limit` | 11 | the page or required evidence cannot fit the configured prompt budget |
 | `unavailable` | 8 | a model or browser provider stayed unavailable through every retry; the same run later may pass |
 | `error` | 1 | a model or browser failure |
 
 A `budget_exceeded` JSON result includes `budget.resource` (`steps`, `seconds`, `dollars`, `jev_calls` or
 `llm_calls`) and `budget.limit`. Other results have `budget: null`. The embedding and MCP APIs carry the same
-optional object, so callers can identify the exhausted limit without parsing an error message.
+optional object, so callers can identify the affected limit without parsing an error message.
+
+A bot check can block a cloud browser before any task steps execute. Retry with an attached local browser
+or choose another source for the research. Credentials do not resolve a CAPTCHA.
+
+If a model completion omits its cost, fastbrowse looks up the matching OpenRouter or Vercel generation
+receipt. If that receipt is still unavailable, a run with a dollar cap stops with `budget_exceeded`;
+this does not mean the known charges reached the cap. Supplied `inputs` can provide exact field text
+without a field-writing generation.
+
+A browser command that remains unanswered for 120 seconds returns `unavailable`, even if the browser
+still answers health checks. Step and dollar limits do not bound total elapsed time. Set `Limits(max_seconds=...)` for a run deadline.
+When investigating a stalled run, enable trace logging and retain the last event alongside the result.
 
 ## How it works
 
@@ -462,6 +446,18 @@ There is no binary for Alpine or another musl system, and none for a platform ou
 that allows programs only by the team that signed them refuses. The Windows binary is not signed. Bun and Deno are
 untested.
 
+## Use fastbrowse with your agent
+
+Install the [fastbrowse skill](docs/skill.md) to delegate website tasks from an agent that supports Agent Skills. It uses the MCP
+tool when connected, or the CLI, and preserves the task's citations, status, authorization, and budget.
+The guide covers agent selection, configuration, and example prompts for Codex and Claude Code.
+Agents without skill support can use the CLI or MCP server directly.
+
+## Run fastbrowse through Nebula
+
+[Nebula](https://www.nebula.gg/) embeds fastbrowse in its agent harness, with browser steps, results and
+permitted vault logins. Use Bitwarden or 1Password through Nebula with credentials scoped to authorized websites.
+
 ## Use it from an MCP client
 
 `fastbrowse-mcp` serves one `browse` tool over [MCP](https://modelcontextprotocol.io), so Claude Code, Claude
@@ -493,12 +489,12 @@ The server's flags decide what a calling model may do; a call can ask for less,
 
 | Flag | Effect |
 |:--|:--|
-| `--local`, `--headed`, `--profile DIR`, `--downloads DIR` | as for the CLI, fixed for every call |
+| `--local`, `--headed`, `--profile DIR`, `--downloads DIR`, `--cursor` | as for the CLI, fixed for every call |
 | `--cloud-profile ID` | every call runs signed in as that cloud profile; a calling model cannot choose it |
 | `--allow-authorize` | let a call pass `authorize` to go through irreversible actions; without it they always stop at `needs_confirmation` |
 | `--secret NAME=ENV_VAR@ORIGIN` | typed when a call's start page is on `ORIGIN` (`https://*.site.com` covers its hosts); the model sees `NAME` only |
 | `--bitwarden ITEM` | a vault login a call may name in `bitwarden` |
-| `--max-steps N`, `--max-dollars N`, `--max-seconds N` | ceilings per call (defaults 60, $1.00, 600s) |
+| `--max-steps N`, `--max-dollars N`, `--max-seconds N` | optional ceilings per call; defaults are unlimited |
 | `--max-concurrent N` | runs at once, default 1; more calls wait their turn |
 | `--transport http`, `--host`, `--port` | streamable HTTP at `/mcp` instead of stdio |
 
@@ -521,9 +517,9 @@ seconds to minutes, so raise the client's tool timeout if it has one (`MCP_TOOL_
 
 ## Evals and development
 
-The [eval workflow](docs/evals.md#workflow) has the run, publish and regeneration commands. Final page checks
+[Eval commands](docs/evals.md) cover running suites, publishing results and regenerating evidence. Final page checks
 require evidence read by the harness, and a pass also requires the task's expected ending. Published rows carry
-build and task versions; the [site feed](docs/results/summary.json) is generated from them.
+build and task versions; the [compact results feed](docs/results/summary.json) is generated from them.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and checks, [docs/design.md](docs/design.md) for the browser
 layer, and [docs/jev.md](docs/jev.md) for the Jev assumptions checked against Typesafe's documentation.

package/fastbrowse/_internal/fastbrowse-0.5.20.dist-info/RECORD

@@ -0,0 +1,14 @@
+../../../bin/fastbrowse,sha256=k_VHUJGUyyMLHeLCiSHLkBTLNP1m86q6e4YkyAHdlZM,337
+../../../bin/fastbrowse-mcp,sha256=1CAFjtHrbGFIoAzljudiwUZ-Qrz8WFq5CLTPaDEvGRE,344
+_editable_impl_fastbrowse.pth,sha256=Ft6bxdkTegROr5p9hZSxsnUSfEHrZYCfXWKjtpA4_DU,44
+fastbrowse-0.5.20.dist-info/INSTALLER,sha256=5hhM4Q4mYTT9z6QB6PGpUAW81PGNFrYrdXMj4oM_6ak,2
+fastbrowse-0.5.20.dist-info/METADATA,sha256=TRP1vQPXRmVjUohcVe1cPzAiSIAyyu5deui0sw5RpmA,31373
+fastbrowse-0.5.20.dist-info/RECORD,,
+fastbrowse-0.5.20.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastbrowse-0.5.20.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fastbrowse-0.5.20.dist-info/direct_url.json,sha256=cZGZY9ovdib3X-RhjHdlyO_0_EMUe0tW6AXsSyMbNE4,86
+fastbrowse-0.5.20.dist-info/entry_points.txt,sha256=SlQAK1_4_oywTAMckx8BYuCQJva0F-QuShQPcxtUm-g,95
+fastbrowse-0.5.20.dist-info/licenses/LICENSE,sha256=gcUazG_j5a2blKPmfKqRKE98KOqX2kPbWY-EOtQZiNU,1067
+fastbrowse-0.5.20.dist-info/licenses/NOTICE,sha256=qEO0Az_Tk98vRVL0xjnGYgMvexlMCA92lWl4JBwYRzg,1854
+fastbrowse-0.5.20.dist-info/uv_build.json,sha256=RBNvo1WzZ4oRRq0W9-hknpT7T8If536DEMBg9hyq_4o,2
+fastbrowse-0.5.20.dist-info/uv_cache.json,sha256=GWjVYY9Vp6-ng3PbDCtLXRAAV5WI5xeIq-BkZ9dZnZ0,194

package/fastbrowse/_internal/fastbrowse-0.5.20.dist-info/uv_cache.json

@@ -0,0 +1 @@
+{"timestamp":{"secs_since_epoch":1791608646,"nanos_since_epoch":209709708},"commit":null,"tags":null,"env":{},"directories":{"src":{"secs_since_epoch":1791608646,"nanos_since_epoch":211240749}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastbrowse/darwin-arm64",
-  "version": "0.5.19",
+  "version": "0.5.20",
   "description": "The fastbrowse binary for macOS on arm64.",
   "license": "MIT",
   "repository": {

package/fastbrowse/_internal/fastbrowse-0.5.19.dist-info/RECORD

@@ -1,14 +0,0 @@
-../../../bin/fastbrowse,sha256=k_VHUJGUyyMLHeLCiSHLkBTLNP1m86q6e4YkyAHdlZM,337
-../../../bin/fastbrowse-mcp,sha256=1CAFjtHrbGFIoAzljudiwUZ-Qrz8WFq5CLTPaDEvGRE,344
-_editable_impl_fastbrowse.pth,sha256=Ft6bxdkTegROr5p9hZSxsnUSfEHrZYCfXWKjtpA4_DU,44
-fastbrowse-0.5.19.dist-info/INSTALLER,sha256=5hhM4Q4mYTT9z6QB6PGpUAW81PGNFrYrdXMj4oM_6ak,2
-fastbrowse-0.5.19.dist-info/METADATA,sha256=l_hggNhjxHhCyunHbMTPUkdpyJ3tl79Y1AHPhtN7EKo,31033
-fastbrowse-0.5.19.dist-info/RECORD,,
-fastbrowse-0.5.19.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-fastbrowse-0.5.19.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-fastbrowse-0.5.19.dist-info/direct_url.json,sha256=cZGZY9ovdib3X-RhjHdlyO_0_EMUe0tW6AXsSyMbNE4,86
-fastbrowse-0.5.19.dist-info/entry_points.txt,sha256=SlQAK1_4_oywTAMckx8BYuCQJva0F-QuShQPcxtUm-g,95
-fastbrowse-0.5.19.dist-info/licenses/LICENSE,sha256=gcUazG_j5a2blKPmfKqRKE98KOqX2kPbWY-EOtQZiNU,1067
-fastbrowse-0.5.19.dist-info/licenses/NOTICE,sha256=qEO0Az_Tk98vRVL0xjnGYgMvexlMCA92lWl4JBwYRzg,1854
-fastbrowse-0.5.19.dist-info/uv_build.json,sha256=RBNvo1WzZ4oRRq0W9-hknpT7T8If536DEMBg9hyq_4o,2
-fastbrowse-0.5.19.dist-info/uv_cache.json,sha256=56hZcPp9TKFHS_cHNMZvd-M8ZP3zllN_UK0f4-ceyEc,194

package/fastbrowse/_internal/fastbrowse-0.5.19.dist-info/uv_cache.json

@@ -1 +0,0 @@
-{"timestamp":{"secs_since_epoch":1791321494,"nanos_since_epoch":878437009},"commit":null,"tags":null,"env":{},"directories":{"src":{"secs_since_epoch":1791321494,"nanos_since_epoch":879909245}}}