@fastbrowse/linux-arm64 0.5.25 → 0.7.1

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

@@ -3,7 +3,7 @@
 // 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, allowedOrigins = null) => {
+((mode, allowedOrigins = null, limits = null) => {
   const granted = doc => {
     if (allowedOrigins === null) return true;
     const frame = doc.defaultView.frameElement;
@@ -94,7 +94,17 @@
     };
     registry.track(document);
   }
-  if (mode === 'fingerprint') {
+  const clock = () => ({
+    ready: document.readyState === 'interactive' || document.readyState === 'complete',
+    quietFor: performance.now() - registry.lastMutation,
+    hidden: document.hidden,
+  });
+  // The settle loop reads the clock alone until the page has gone quiet: the walk below reads every element and
+  // all the page's text, which on a large page costs more than the poll interval leaves room for.
+  if (mode === 'quiet') return clock();
+  // `loading` walks for indicators, and to watch new shadow roots and frames, but hashes nothing.
+  if (mode === 'fingerprint' || mode === 'loading') {
+    const hashing = mode === 'fingerprint';
     let hash = 2166136261;
     let loading = false;
     const hashText = text => {
@@ -103,8 +113,7 @@
     const include = root => {
       registry.track(root);
       loading ||= [...root.querySelectorAll(LOADING)].some(showing);
-      const text = root.body?.innerText ?? root.textContent ?? '';
-      hashText(text);
+      if (hashing) hashText(root.body?.innerText ?? root.textContent ?? '');
       // innerText omits shadow trees and child documents even when their content is visible.
       for (const e of root.querySelectorAll('*')) {
         // A filter can change only its checkmark, so text alone reported "Nonstop only" as a no-op.
@@ -112,6 +121,7 @@
         // Only rendered controls: a hidden carousel's aria-selected dots churn on their own and would read as
         // progress.
         if (
+          hashing &&
           ('checked' in e || 'selected' in e || e.hasAttribute('aria-checked') || e.hasAttribute('aria-selected')) &&
           e.checkVisibility({ checkOpacity: !nativeChoice(e), checkVisibilityCSS: true }) &&
           (!nativeChoice(e) || shownThrough(e))
@@ -138,10 +148,8 @@
     };
     include(document);
     return {
-      fingerprint: location.href + '|' + document.title + '|' + (hash >>> 0) + '|' + scrollY,
-      ready: document.readyState === 'interactive' || document.readyState === 'complete',
-      quietFor: performance.now() - registry.lastMutation,
-      hidden: document.hidden,
+      ...clock(),
+      fingerprint: hashing ? location.href + '|' + document.title + '|' + (hash >>> 0) + '|' + scrollY : null,
       loading,
     };
   }
@@ -153,12 +161,32 @@
     return id;
   };
   for (const [id, e] of registry.nodes) if (!e.isConnected) registry.nodes.delete(id);
+  // The DOM cannot change while this script runs, so a label, a text or a section title read once is reused for
+  // the rest of it. `registry.guard` reads them again in a later script, against a page that may have changed
+  // since, so the reuse ends as soon as this one does, whether it returns or throws.
+  const caches = [];
+  registry.nativeQueueMicrotask ||= window.queueMicrotask.bind(window);
+  registry.nativeQueueMicrotask(() => {
+    for (const cache of caches) cache.clear();
+    caches.length = 0;
+  });
+  const memo = read => {
+    const cache = new Map();
+    caches.push(cache);
+    return e => {
+      if (!caches.includes(cache)) return read(e);
+      if (!cache.has(e)) cache.set(e, read(e));
+      return cache.get(e);
+    };
+  };
+  const innerTextOf = memo(e => e.innerText);
 
   const safe = e => e.type !== 'hidden';
   // Password and agent-typed secret values never leave the page: only their length is observed.
   const secret = e => e.type === 'password' || e.dataset?.fastbrowseSecret === '1';
   const reveal = e => (typeof e.value !== 'string' ? null : secret(e) ? '•'.repeat(e.value.length) : e.value);
-  const visible = e => {
+  // Asked of each control by the walk and again by its guard, and of each text node's parent.
+  const visible = memo(e => {
     // Todo lists paint the checkmark beside a transparent native input without associating a label.
     // The input still receives clicks; opacity alone must not remove the only control for that row.
     // A transparent input with a visible label of its own keeps the label as its click target: TodoMVC's
@@ -176,7 +204,7 @@
     if (!choice) return true;
     const r = e.getBoundingClientRect();
     return r.width > 0 && r.height > 0 && !e.matches(':disabled') && !e.closest('[aria-disabled="true"]');
-  };
+  });
   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.
@@ -230,21 +258,21 @@
       .filter(Boolean)
       .join(' ');
   };
-  const labelOf = (e, seen = new Set()) => {
+  const labelFrom = (e, seen) => {
     if (!e || seen.has(e)) return '';
     seen.add(e);
     const root = typeof e.getRootNode === 'function' ? e.getRootNode() : document;
     const byId = id => (root.getElementById ? root.getElementById(id) : document.getElementById(id));
     const referenced = (e.getAttribute('aria-labelledby') || '')
       .split(/\s+/)
-      .map(id => labelOf(byId(id), seen))
+      .map(id => labelFrom(byId(id), seen))
       .filter(Boolean)
       .join(' ');
     return (
       referenced ||
       e.getAttribute('aria-label') ||
       [...(e.labels || [])]
-        .map(l => labelOf(l, seen))
+        .map(l => labelFrom(l, seen))
         .filter(Boolean)
         .join(' ') ||
       (['button', 'submit', 'reset'].includes(e.type) ? e.value : '') ||
@@ -256,7 +284,7 @@
               n.nodeType === 3
                 ? n.textContent
                 : n.nodeType === 1 && !CODE.has(n.tagName) && n.getAttribute('aria-hidden') !== 'true'
-                  ? labelOf(n, seen)
+                  ? labelFrom(n, seen)
                   : '',
             )
             .join(' ')
@@ -267,6 +295,8 @@
     );
   };
 
+  const labelOf = memo(e => labelFrom(e, new Set()));
+
   const ARIA_ROLES = [
     'button',
     'link',
@@ -318,7 +348,7 @@
     return null;
   };
 
-  const submitSemantics = e => {
+  const submitSemantics = memo(e => {
     const form = e.form;
     const explicit = ['BUTTON', 'INPUT'].includes(e.tagName) && ['submit', 'image'].includes(e.type);
     const implicit = [
@@ -346,9 +376,9 @@
       label: submit ? labelOf(submit) : labelOf(form),
       method: submit?.getAttribute('formmethod') || form.method,
       action: submit?.getAttribute('formaction') || form.action,
-      text: excerpt(form.innerText, FORM_TEXT_CHARS),
+      text: excerpt(innerTextOf(form), FORM_TEXT_CHARS),
     });
-  };
+  });
 
   const framePath = doc => {
     if (doc === document) return null;
@@ -379,6 +409,23 @@
     }
   }
 
+  // Guards and the page key go to Python as digests: each comparison is equality, and the full guards cost more to
+  // send than the snapshot takes to compute. Not cryptographic, and it needs not be: a page that wants a guard to
+  // hold can simply leave its DOM alone.
+  const digest = text => {
+    let h1 = 0xdeadbeef,
+      h2 = 0x41c6ce57;
+    for (let i = 0; i < text.length; i++) {
+      const c = text.charCodeAt(i);
+      h1 = Math.imul(h1 ^ c, 2654435761);
+      h2 = Math.imul(h2 ^ c, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return (h2 >>> 0).toString(16).padStart(8, '0') + (h1 >>> 0).toString(16).padStart(8, '0');
+  };
+  // Sibling controls share their card, so its text is hashed once per card rather than once per control.
+  const scopeDigest = memo(scope => digest(innerTextOf(scope)?.slice(0, GUARD_TEXT_CHARS) || ''));
   registry.guard = e => {
     if (!e?.isConnected || !visible(e)) return null;
     const source = sourceOf(e);
@@ -400,7 +447,7 @@
       e.getAttribute('aria-checked'),
       e.getAttribute('aria-selected'),
       e.getAttribute('href'),
-      scope?.innerText?.slice(0, GUARD_TEXT_CHARS) || '',
+      scope ? scopeDigest(scope) : '',
       e.ownerDocument.location.origin,
       e.ownerDocument.defaultView.performance.timeOrigin,
       submitSemantics(e),
@@ -409,6 +456,10 @@
       identity(source),
     ];
   };
+  registry.guardKey = e => {
+    const guard = registry.guard(e);
+    return guard && digest(JSON.stringify(guard));
+  };
 
   const controls = [];
   // Controls with no accessible name of their own, whose label is an icon's or only their role.
@@ -444,7 +495,8 @@
     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);
+      // Most links hold no button, and querying every link for every control was the walk's slowest step.
+      const nested = e.querySelector('button') ? 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;
@@ -531,11 +583,11 @@
   // A label tied to no control titles what follows it, as a heading would: a blog post's "Date Picker 3" is one,
   // and the post's first heading ("Data Entry Form") named that picker's Submit when only headings counted.
   // A hidden title names nothing on screen: innerText still returns a `hidden` label's text.
-  const titles = scope =>
+  const titles = memo(scope =>
     [...scope.querySelectorAll(`${HEADINGS},label`)].filter(
       e =>
         (e.localName !== 'label' || !e.control) && e.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }),
-    );
+    ));
   // A table's header cell names its own row, and a caption its own table, never what sits outside them: a jQuery UI
   // datepicker's Next button was named "Su", its weekday header, and every month's Next read the same.
   const reaches = (title, element) =>
@@ -546,7 +598,7 @@
     let first = '',
       before = '';
     for (const title of titles(scope)) {
-      const text = firstLine(title.innerText);
+      const text = firstLine(innerTextOf(title));
       if (!text || text === label || title.contains(element) || !reaches(title, element)) continue;
       first ||= text;
       if (title.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING) before = text;
@@ -563,18 +615,18 @@
     // A line that is itself a repeated control's label ("Prev") reads the same in every repeat, so it names none:
     // past it, a datepicker's first line is the month it shows. The label is cut out as whole words, since a day
     // labelled "2" cut out of "October 2026" left "October 0 6".
-    const lines = (scope.innerText || '')
+    const lines = (innerTextOf(scope) || '')
       .split('\n')
       .map(line => line.replace(/\s+/g, ' ').trim())
       .filter(line => line && !repeated.has(line));
     return firstLine(lines.map(line => (label ? ` ${line} `.split(` ${label} `).join(' ') : line)).join('\n'));
   };
-  const contextOf = (element, twins, label, nearest = true) => {
+  const contextOf = (element, holding, label, nearest = true) => {
     // The widest twin-free ancestor is the card, row or section the twins repeat over. A narrower one names
     // the button's own wrapper, which on a shop is its price rather than the product it belongs to.
     let scope = null;
     for (let e = element.parentElement; e && e !== e.ownerDocument.body; e = e.parentElement) {
-      if (twins.some(twin => twin !== element && e.contains(twin))) break;
+      if (holding.get(e) > 1) 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"]') ||
@@ -709,12 +761,18 @@
   for (const group of byLabel.values()) {
     if (group.length < 2) continue;
     const twins = group.map(c => registry.nodes.get(c.id));
-    const nearest = group.map(c => contextOf(registry.nodes.get(c.id), twins, c.label));
+    // How many twins each ancestor holds. One that holds two is past the card, and counting once beats asking
+    // every ancestor of every twin whether it contains each of the others.
+    const holding = new Map();
+    for (const twin of twins) {
+      for (let e = twin.parentElement; e; e = e.parentElement) holding.set(e, (holding.get(e) || 0) + 1);
+    }
+    const nearest = group.map(c => contextOf(registry.nodes.get(c.id), holding, c.label));
     group.forEach((c, i) => {
       // Cards that each end in an "Options" heading share their nearest title, which would name every twin
       // alike; a twin whose nearest title another twin shares is named by its card's first title instead.
       const shared = nearest.indexOf(nearest[i]) !== nearest.lastIndexOf(nearest[i]);
-      const context = shared ? contextOf(registry.nodes.get(c.id), twins, c.label, false) : nearest[i];
+      const context = shared ? contextOf(registry.nodes.get(c.id), holding, c.label, false) : nearest[i];
       if (context) c.context = context;
     });
     // Options that are direct children of one list share every ancestor, and their aria-label hides the text
@@ -770,7 +828,7 @@
       const aria = (e.getAttribute('aria-label') || '').trim();
       const outside = [...e.children]
         .filter(child => child !== path)
-        .map(child => firstLine(child.innerText))
+        .map(child => firstLine(innerTextOf(child)))
         .find(line => line && line !== label && !repeated.has(line));
       return excerpt((aria !== label && aria) || outside || first, CONTROL_CONTEXT_CHARS);
     }
@@ -883,6 +941,7 @@
   // Text in a same-process child document is on screen as much as the parent's: a frameset page has no text of
   // its own at all. Each child is read in its own coordinates, shifted by where its frame sits.
   const words = [];
+  // Geometry, the cheaper test, goes first.
   const readText = (doc, dx, dy) => {
     if (!doc.body) return;
     const walker = doc.createTreeWalker(doc.body, NodeFilter.SHOW_TEXT);
@@ -891,7 +950,7 @@
     while ((node = walker.nextNode())) {
       const value = node.textContent.trim(),
         parent = node.parentElement;
-      if (!value || !parent || parent.closest('script,style,noscript,template') || !visible(parent)) continue;
+      if (!value || !parent) continue;
       range.selectNodeContents(node);
       const r = range.getBoundingClientRect();
       const top = r.top + dy,
@@ -902,7 +961,9 @@
         top + r.height > 0 &&
         top < innerHeight &&
         left + r.width > 0 &&
-        left < innerWidth
+        left < innerWidth &&
+        !parent.closest('script,style,noscript,template') &&
+        visible(parent)
       ) {
         words.push(value);
       }
@@ -922,8 +983,50 @@
   readText(document, 0, 0);
   const viewport_text = words.join('\n');
 
-  const guards = {};
-  for (const c of controls) guards[c.id] = registry.guard(registry.nodes.get(c.id));
+  // Page state carried by pixels: a chart, a picture, a drawing or a video is evidence the page text and the
+  // control list cannot hold, and the verifier needs the screenshot for it. Only what the viewport shows counts,
+  // because that is what a screenshot captures: an image below the fold cannot appear in it, and counting every
+  // image on a long page would ask for a screenshot on almost every page and undo the gate it exists to serve.
+  // Geometry is read in the parent's coordinates the way readText reads text, so a frame's image counts where the
+  // frame itself sits on screen. Elements small enough to be an icon or a rule are not page state.
+  const VISUAL = 'img,canvas,video,svg,picture,figure,[role="img"]';
+  const VISUAL_MIN_PX = 48;
+  let visual_content = 0;
+  const readVisual = (doc, dx, dy) => {
+    if (visual_content) return;
+    for (const e of doc.querySelectorAll(VISUAL)) {
+      if (e.closest('[aria-hidden="true"],[inert]') || !visible(e)) continue;
+      const r = e.getBoundingClientRect();
+      const top = r.top + dy,
+        left = r.left + dx;
+      if (r.width < VISUAL_MIN_PX || r.height < VISUAL_MIN_PX) continue;
+      if (top + r.height <= 0 || top >= innerHeight || left + r.width <= 0 || left >= innerWidth) continue;
+      visual_content = 1;
+      return;
+    }
+    for (const frame of doc.querySelectorAll('iframe,frame')) {
+      let inner = null;
+      try {
+        inner = frame.contentDocument;
+      } catch {
+        inner = null;
+      }
+      if (!inner || !granted(inner)) continue;
+      const f = frame.getBoundingClientRect();
+      readVisual(inner, dx + f.left + frame.clientLeft, dy + f.top + frame.clientTop);
+    }
+  };
+  readVisual(document, 0, 0);
+
+  const guards = {},
+    retarget_keys = {};
+  for (const c of controls) {
+    const guard = registry.guard(registry.nodes.get(c.id));
+    guards[c.id] = guard && digest(JSON.stringify(guard));
+    // A redraw changes the node ids at either end of the guard. Everything between them, including the receiving
+    // document's timeOrigin and form semantics, must survive before an action can follow it.
+    retarget_keys[c.id] = guard && digest(JSON.stringify(guard.slice(1, -1)));
+  }
   // A dependent field can appear without changing page text. Compare all controls,
   // excusing only the value and required marker of the field just filled.
   const formState = controls.map(({ distance, offscreen, ...c }) => {
@@ -945,13 +1048,13 @@
   }
   registry.formObserved = { page: formPage, controls: formState };
   // Kept so a later check can ask whether any of these controls changed without sending the guards back.
-  registry.observed = new Map(controls.map(c => [c.id, JSON.stringify(guards[c.id])]));
+  registry.observed = new Map(controls.map(c => [c.id, guards[c.id]]));
   const field_state = [...document.querySelectorAll('input,textarea,select')]
     .filter(safe)
     .map(e => [identity(e), reveal(e), e.checked, e.selectedIndex, e.disabled, e.readOnly]);
   // Compare meaning and identity for the page_key fingerprint; geometry is re-resolved just before input.
   const semantics = controls.map(({ distance, ...c }) => c);
-  const page_key = JSON.stringify([
+  const page_key = digest(JSON.stringify([
     location.href,
     scrollX,
     scrollY,
@@ -961,16 +1064,35 @@
     viewport_text,
     semantics,
     field_state,
-  ]);
+  ]));
 
-  return {
+  const result = {
     url: location.href,
     title: document.title,
     viewport_text,
+    visual_content,
     document_key: String(performance.timeOrigin),
     controls: semantics,
     page_key,
     guards,
+    retarget_keys,
     inaccessible_frames: inaccessible,
   };
+  if (!limits) return result;
+  // Python keeps at most `limits.onscreen` of the controls on screen and `limits.offscreen` of those off it, each
+  // the first in this order, and any pager past either cap. A control past the caps is sent with only what decides
+  // whether it is a pager; Python asks for the rest of one it keeps, by this snapshot's token, from what is kept here.
+  const token = (registry.snapshots = (registry.snapshots || 0) + 1);
+  registry.sent = { token, rows: new Map(semantics.map(c => [c.id, [c, guards[c.id], retarget_keys[c.id]]])) };
+  let onscreen = 0,
+    offscreen = 0;
+  result.controls = semantics.map(c => {
+    if (c.offscreen ? offscreen++ < limits.offscreen : onscreen++ < limits.onscreen) return c;
+    delete result.guards[c.id];
+    delete result.retarget_keys[c.id];
+    const { id, role, label, operations, href, next_page } = c;
+    return { id, role, label, operations, href, next_page, offscreen: c.offscreen, partial: true };
+  });
+  result.token = token;
+  return result;
 })

package/fastbrowse/_internal/{fastbrowse-0.5.25.dist-info → fastbrowse-0.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastbrowse
-Version: 0.5.25
+Version: 0.7.1
 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
@@ -17,7 +17,7 @@ Requires-Dist: pydantic-settings<3,>=2.10
 Requires-Dist: pydantic<3,>=2.11
 Requires-Dist: websockets<18,>=14
 Provides-Extra: browser-use
-Requires-Dist: browser-use-sdk==3.11.3; extra == 'browser-use'
+Requires-Dist: browser-use-sdk==3.12.1; extra == 'browser-use'
 Provides-Extra: eval-data
 Requires-Dist: pyyaml<7,>=6; extra == 'eval-data'
 Provides-Extra: mcp
@@ -60,16 +60,19 @@ Benchmarking compares exactly three things:
 
 | | Comparison | Arms | Recorded |
 |:--|:--|:--|:--|
-| C1 | agent against agent | fastbrowse against the hosted Browser Use agent | 40 of 42 passed against 14 of 42, median 17.0s against 27.5s, $0.011 against $0.400 a task |
-| C2 | backend against backend | fastbrowse on its own browser pool against fastbrowse on a Browser Use Cloud browser | not yet measured |
+| C1 | agent against agent | fastbrowse against the hosted Browser Use agent | 46 tasks, three repeats: 99.2% against 97.8%, median 16.3s against 16.1s, $0.0256 against $0.2840 a result |
+| C2 | backend against backend | fastbrowse on its own browser pool against fastbrowse on a Browser Use Cloud browser | 53 tasks, three repeats: 96.2% against 98.1%, median 15.9s against 15.0s, $0.0192 against $0.0200 a result |
 | C3 | fastbrowse and its backend against [Browser Use Ultrafast](https://github.com/browser-use/jev-ultrafast) | fastbrowse on its own browser pool against `jev-ultrafast`, 6 tasks | not yet measured |
 
-C1's figures are the recorded head-to-head on 14 answer tasks, three passes each, on identical cloud browsers
-under identical limits. [Benchmark results](docs/benchmarks.md) gives each comparison's sources, the internal
-matched-task campaigns behind C1, the browser cost basis and the limitations. The
-[benchmark page](https://fastbrowse.ai/benchmarks) renders only figures the maintainer approved. Rows are
-comparable only at matching task versions; the upstream suites and the Codex with Cua Driver arm are diagnostics,
-described in [eval results and workflow](docs/evals.md).
+C1's figures are the recorded head-to-head on 46 tasks, three repeats each, on Browser Use cloud browsers under
+identical limits, with the hosted agent at its defaults. C2 compares browsers, not agents: both arms run the same
+fastbrowse build, tasks and repeats, and only the browser differs. On that backend fastbrowse passes fewer tasks
+on its own pool than on the Browser Use Cloud browser, 96.2% against 98.1%. [Benchmark results](docs/benchmarks.md)
+gives each comparison's sources, the campaigns behind C1, the browser cost basis and the limitations. The
+[benchmark page](https://fastbrowse.ai/benchmarks) renders only figures the maintainer approved; the C1 and C2
+figures come from the 0.5.25 campaign staged in `docs/results/benchmark-candidate.json`, which awaits approval.
+Rows are comparable only at matching task versions; the upstream suites and the Codex with Cua Driver arm are
+diagnostics, described in [eval results and workflow](docs/evals.md).
 
 ### Why fastbrowse, against each kind of agent
 
@@ -94,13 +97,14 @@ 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=... # Vercel AI Gateway: Jev backup, and the LLM when OPENROUTER_API_KEY is unset
+# export AI_GATEWAY_API_KEY=... # Vercel AI Gateway: Jev backup, and Jev 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
+Jev uses direct TypeSafe when `TYPESAFE_API_KEY` is supplied, otherwise OpenRouter when `OPENROUTER_API_KEY` is
+set, and the Vercel AI Gateway when neither is. With `AI_GATEWAY_API_KEY` beside another key, the gateway is the
+backup. `FASTBROWSE_JEV_SOURCE` overrides
 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.
 
@@ -121,8 +125,8 @@ cp .env.example .env   # then fill in the keys, BROWSER_USE_API_KEY included, or
 uv run fastbrowse "What is the title of the top story right now?" --start https://news.ycombinator.com/
 ```
 
-Steps go to stderr; the status, cost, step count and answer go to stdout. `--json` prints every step,
-the quotes behind the answer, and cost by component.
+Steps go to stderr; the status, cost, step count, the reason a run stopped short and the answer go to stdout.
+`--json` prints every step, the quotes behind the answer, and cost by component.
 
 | Flag | Effect |
 |:--|:--|
@@ -259,7 +263,7 @@ Only `complete` exits 0, so a program can also check zero versus nonzero.
 
 | Status | Exit | Meaning |
 |:--|--:|:--|
-| `complete` | 0 | every information requirement is backed by a quote, and every action is confirmed on the page |
+| `complete` | 0 | every information requirement is backed by a quote, and every action that changes the site is confirmed on the page |
 | `unverified` | 10 | it believes it finished but could not back every claim |
 | `needs_confirmation` | 3 | stopped before an irreversible action; re-run with `--authorize` |
 | `needs_login` | 4 | a sign-in wall that no `--secret` covers |
@@ -275,12 +279,18 @@ A `budget_exceeded` JSON result includes `budget.resource` (`steps`, `seconds`,
 `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 affected limit without parsing an error message.
 
+A run that stops `stuck` or `unverified` before writing its answer, with evidence read for a task that asks for
+one, returns a cited answer that starts `Answer (unverified)`, written by one more composer call. If that call
+fails, the answer is the list of quotes the run collected, as it is for the other statuses that stop with evidence.
+
 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.
 The `blocked` result's `evidence` quotes the opening text of the challenge page, with its address.
 
 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`;
+receipt. If that receipt is still unavailable, an OpenRouter call is charged at an upper bound from the model's
+listed prices: its whole context window at the highest price. A call that cannot be bounded, through the Vercel AI
+Gateway or a custom endpoint, leaves the cost unknown, and 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.
 
@@ -312,7 +322,7 @@ More in [docs/design.md](docs/design.md).
 | Signing in | yes | password fields excluded | `--secret` or a Bitwarden vault item; models see names only |
 | Irreversible actions | explicit task instructions in our fixture tests | no authorization parameter in Agent | classifier plus a code-enforced authorization gate |
 | Browser | cloud | Chrome through Browser Harness; cloud in these evals | cloud by default, or local Chrome with `--local` |
-| Benchmarked in | C1 | C3 | C1 on a cloud browser; C2 and C3 on its own browser pool |
+| Benchmarked in | C1 | C3 | C1 on a cloud browser; C2 on its own pool and on a Browser Use Cloud browser; C3 on its own pool |
 
 Browser Use Ultrafast (`jev-ultrafast`) is Browser Use's navigation agent, separate from its hosted
 LLM agent; fastbrowse shares its core techniques. Its column describes
@@ -410,7 +420,9 @@ it can be `None` for an ordinary successful action.
 
 For continuous live images, pass an async `on_frame` handler accepting JPEG bytes. Frames follow the active
 tab and are acknowledged after delivery, with no fixed frame rate. Only the latest pending frame is kept.
-Handler failures are logged without stopping the run. Live frames and recordings are held back while a
+Handler failures are logged without stopping the run. A handler must honour cancellation: it runs on the
+caller's event loop, so one that catches `CancelledError` without re-raising keeps that loop alive, and
+`asyncio.run` then waits for it at shutdown. Live frames and recordings are held back while a
 resolved secret may show on the page, as PNG step frames are. No handler means no live capture.
 
 Jev uses direct TypeSafe when keyed, otherwise OpenRouter, with Vercel AI Gateway also supported.

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

@@ -0,0 +1,14 @@
+../../../bin/fastbrowse,sha256=kaVbuMx-AlSCiesFjTFd09Km4R8Lunnqm06vuR0Q4ow,336
+../../../bin/fastbrowse-mcp,sha256=ZXqxb9qRtFFkC1H9e4YqAdOBsFqTUwa9EZeg_4K3Ybo,343
+_editable_impl_fastbrowse.pth,sha256=i4F7SPHtRO2rWCDD5u0Gnwv0cyF2GMJMQGgsS1QKCTI,43
+fastbrowse-0.7.1.dist-info/INSTALLER,sha256=5hhM4Q4mYTT9z6QB6PGpUAW81PGNFrYrdXMj4oM_6ak,2
+fastbrowse-0.7.1.dist-info/METADATA,sha256=mKePR_0mnmqEJpiPFAYyCl0v5kF_qBF8IUFFBKaENFg,38738
+fastbrowse-0.7.1.dist-info/RECORD,,
+fastbrowse-0.7.1.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastbrowse-0.7.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fastbrowse-0.7.1.dist-info/direct_url.json,sha256=p4VhBh51_mJBO89EvLp28QXawaajq5zi5eItI6PDXTg,85
+fastbrowse-0.7.1.dist-info/entry_points.txt,sha256=SlQAK1_4_oywTAMckx8BYuCQJva0F-QuShQPcxtUm-g,95
+fastbrowse-0.7.1.dist-info/licenses/LICENSE,sha256=gcUazG_j5a2blKPmfKqRKE98KOqX2kPbWY-EOtQZiNU,1067
+fastbrowse-0.7.1.dist-info/licenses/NOTICE,sha256=qEO0Az_Tk98vRVL0xjnGYgMvexlMCA92lWl4JBwYRzg,1854
+fastbrowse-0.7.1.dist-info/uv_build.json,sha256=RBNvo1WzZ4oRRq0W9-hknpT7T8If536DEMBg9hyq_4o,2
+fastbrowse-0.7.1.dist-info/uv_cache.json,sha256=DerUJgub597QeSdF8qxY4E-JmhxfSbHJSrORY_KaUxY,194

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

@@ -0,0 +1 @@
+{"timestamp":{"secs_since_epoch":1792907015,"nanos_since_epoch":434232915},"commit":null,"tags":null,"env":{},"directories":{"src":{"secs_since_epoch":1792907015,"nanos_since_epoch":434232915}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastbrowse/linux-arm64",
-  "version": "0.5.25",
+  "version": "0.7.1",
   "description": "The fastbrowse binary for Linux on arm64.",
   "license": "MIT",
   "repository": {

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

@@ -1,14 +0,0 @@
-../../../bin/fastbrowse,sha256=kaVbuMx-AlSCiesFjTFd09Km4R8Lunnqm06vuR0Q4ow,336
-../../../bin/fastbrowse-mcp,sha256=ZXqxb9qRtFFkC1H9e4YqAdOBsFqTUwa9EZeg_4K3Ybo,343
-_editable_impl_fastbrowse.pth,sha256=i4F7SPHtRO2rWCDD5u0Gnwv0cyF2GMJMQGgsS1QKCTI,43
-fastbrowse-0.5.25.dist-info/INSTALLER,sha256=5hhM4Q4mYTT9z6QB6PGpUAW81PGNFrYrdXMj4oM_6ak,2
-fastbrowse-0.5.25.dist-info/METADATA,sha256=PviO3CI9ERI53eHfNlnFhSL0Sn9CNuF-Oe-vEJqhBHg,37292
-fastbrowse-0.5.25.dist-info/RECORD,,
-fastbrowse-0.5.25.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-fastbrowse-0.5.25.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-fastbrowse-0.5.25.dist-info/direct_url.json,sha256=p4VhBh51_mJBO89EvLp28QXawaajq5zi5eItI6PDXTg,85
-fastbrowse-0.5.25.dist-info/entry_points.txt,sha256=SlQAK1_4_oywTAMckx8BYuCQJva0F-QuShQPcxtUm-g,95
-fastbrowse-0.5.25.dist-info/licenses/LICENSE,sha256=gcUazG_j5a2blKPmfKqRKE98KOqX2kPbWY-EOtQZiNU,1067
-fastbrowse-0.5.25.dist-info/licenses/NOTICE,sha256=qEO0Az_Tk98vRVL0xjnGYgMvexlMCA92lWl4JBwYRzg,1854
-fastbrowse-0.5.25.dist-info/uv_build.json,sha256=RBNvo1WzZ4oRRq0W9-hknpT7T8If536DEMBg9hyq_4o,2
-fastbrowse-0.5.25.dist-info/uv_cache.json,sha256=nuMm0LpaxGmXjICGUHug7x3u7cj1OiLULzJUGM_sVa4,194

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

@@ -1 +0,0 @@
-{"timestamp":{"secs_since_epoch":1792479825,"nanos_since_epoch":590769738},"commit":null,"tags":null,"env":{},"directories":{"src":{"secs_since_epoch":1792479825,"nanos_since_epoch":591769768}}}