dsh-inner-browser-use 0.34.28 → 0.34.95

package/read.js

@@ -22,7 +22,7 @@ const REGISTRY = '__dshRead'
 const VERSION = 2
 
 /** Interactive elements worth numbering, in the order a reader would meet them. */
-const SELECTOR = [
+export const SELECTOR = [
   'a[href]',
   'button',
   'input:not([type="hidden"])',
@@ -67,7 +67,7 @@ const SIGIL = { // ui-copy-ignore
  * @param {number} version - registry version.
  * @returns {string} an expression to evaluate.
  */
-function seed(selector, version) {
+export function seed(selector, version) {
   return `(() => {
   const w = window
   const current = w.${REGISTRY}
@@ -118,7 +118,7 @@ function seed(selector, version) {
  * @param {number} max - controls to number at most.
  * @returns {string} an expression to evaluate.
  */
-function snapshot(mode, budget, max) {
+export function snapshot(mode, budget, max) {
   const wanted = JSON.stringify(mode)
   return `(() => {
   const reg = window.${REGISTRY}
@@ -129,10 +129,10 @@ function snapshot(mode, budget, max) {
   const name = (el) => {
     const label = el.labels && el.labels[0] ? String(el.labels[0].innerText ?? '') : ''
     const pointing = String(el.getAttribute?.('aria-labelledby') ?? '')
-    const named = pointing.split(/\s+/).filter(Boolean).map((id) => {
+    const named = pointing.split(/\\s+/).filter(Boolean).map((id) => {
       const other = el.ownerDocument.getElementById(id)
       return other === null ? '' : String(other.innerText ?? other.textContent ?? '')
-    }).join(' ').replace(/\s+/g, ' ').trim()
+    }).join(' ').replace(/\\s+/g, ' ').trim()
     const own = named || el.getAttribute?.('aria-label') || el.getAttribute?.('title') || el.getAttribute?.('placeholder') || ''
     const text = String(el.innerText ?? '').replace(/\\s+/g, ' ').trim()
     const value = el.tagName === 'INPUT' && el.type !== 'password' ? String(el.value ?? '') : ''
@@ -270,7 +270,7 @@ function snapshot(mode, budget, max) {
          generated image goes missing, and it is silent by default. */
       if (el.tagName === 'IMG' && el.complete && el.naturalWidth === 0) {
         missing.push({ width: Math.round(wide), height: Math.round(high) })
-        missing[missing.length - 1].name = String(el.getAttribute('alt') ?? '').replace(/\s+/g, ' ').trim().slice(0, 60)
+        missing[missing.length - 1].name = String(el.getAttribute('alt') ?? '').replace(/\\s+/g, ' ').trim().slice(0, 60)
         continue
       }
       const w = el.tagName === 'CANVAS' ? el.width : el.naturalWidth || Math.round(b.width)
@@ -279,7 +279,7 @@ function snapshot(mode, budget, max) {
     }
     if (best === null) return missing.length === 0 ? null : { missing }
     /* What the read hands back about one picture: not a screen of fields. */
-    const said = { name: String(best.el.getAttribute?.('alt') ?? best.el.getAttribute?.('aria-label') ?? '').replace(/\s+/g, ' ').trim().slice(0, 60) }
+    const said = { name: String(best.el.getAttribute?.('alt') ?? best.el.getAttribute?.('aria-label') ?? '').replace(/\\s+/g, ' ').trim().slice(0, 60) }
     said.kind = best.kind
     said.width = best.w
     said.height = best.h
@@ -310,7 +310,7 @@ function snapshot(mode, budget, max) {
   /* What no amount of text will tell the reader: the screen shows something
      that has no words in the tree. Counted here so every read can say it. */
   const blind = (() => {
-    const out = { pictures: 0, canvases: 0, videos: 0, frames: 0 }
+    const out = { pictures: 0, canvases: 0, videos: 0, frames: 0, flash: 0 }
     const speaks = (el) => {
       const said = String(el.getAttribute?.('alt') ?? '').trim() || String(el.getAttribute?.('aria-label') ?? '').trim() || String(el.getAttribute?.('title') ?? '').trim()
       if (said.length > 1) return true
@@ -337,6 +337,44 @@ function snapshot(mode, budget, max) {
     /* A tracking pixel of a frame is not something the reader is missing: only
        frames that occupy the screen are worth a sentence. */
     for (const el of document.querySelectorAll('iframe')) if (shows(el)) out.frames += 1
+    /* A movie this browser refuses to play is the worst kind of blank: the page
+       looks loaded and nothing says why nothing happens. Count it so the read
+       can say it out loud. */
+    for (const el of document.querySelectorAll('embed, object')) {
+      const said = String(el.getAttribute?.('type') ?? el.getAttribute?.('src') ?? el.getAttribute?.('data') ?? el.getAttribute?.('classid') ?? '')
+      if (!/shockwave|flash|application\\/x-swf/i.test(said) && el.tagName !== 'EMBED') continue
+      if (el.tagName === 'EMBED' && !/shockwave|flash|swf/i.test(said)) continue
+      if (shows(el)) out.flash += 1
+    }
+    if (out.flash === 0) {
+      const asked = Array.from(document.querySelectorAll('a[href], iframe[src], script[src], link[href]'))
+        .map((el) => String(el.getAttribute?.('href') ?? el.getAttribute?.('src') ?? ''))
+        .filter((said) => /\\.swf(\\?|$)/i.test(said)).length
+      if (asked > 0) out.flash = asked
+    }
+    if (out.flash === 0) {
+      /* Many sites build the movie in a script or load it inside a frame, so
+         nothing in the tree names it. The scripts still do. */
+      const scripts = Array.from(document.scripts).map((el) => String(el.textContent ?? '')).join(' ')
+      const hits = scripts.match(/\\.swf(?=["'\\s?]|$)/gi)
+      if (hits !== null && hits.length > 0) out.flash = Math.min(9, hits.length)
+    }
+    if (out.flash === 0) {
+      /* The player may be written into a same-origin frame that nothing in the
+         outer tree mentions. Same origin means this page can look inside. */
+      try {
+        for (const frame of document.querySelectorAll('iframe')) {
+          const inside = frame.contentDocument
+          if (inside === null || inside === undefined) continue
+          const movies = inside.querySelectorAll('embed, object').length
+          const inner = Array.from(inside.scripts ?? []).map((el) => String(el.textContent ?? '')).join(' ')
+          const found = inner.match(/\\.swf(?=["'\\s?]|$)/gi)
+          out.flash = Math.min(9, out.flash + movies + (found === null ? 0 : found.length))
+        }
+      } catch {
+        /* a frame from elsewhere cannot be looked into, which is fine */
+      }
+    }
     return out
   })()
   return JSON.stringify({
@@ -372,13 +410,102 @@ export function resolve(ref) {
   const el = hit.el
   const b = el.getBoundingClientRect()
   if (b.width < 2 || b.height < 2) return JSON.stringify({ gone: true, off: true })
-  if (b.top < 0 || b.left < 0 || b.bottom > innerHeight || b.right > innerWidth) el.scrollIntoView({ block: 'center', inline: 'center' })
+  /* A control inside a scrolling panel can be outside the panel while still
+     inside the window: the point would land on the panel's other content, and
+     the click would be reported against the wrong thing. Ask every clipping
+     ancestor, not only the window. */
+  const clipped = () => {
+    const me = el.getBoundingClientRect()
+    for (let up = el.parentElement; up; up = up.parentElement) {
+      const css = getComputedStyle(up)
+      const flow = css.overflowX + ' ' + css.overflowY
+      if (!/auto|scroll|hidden|clip/.test(flow)) continue
+      const box = up.getBoundingClientRect()
+      if (me.top < box.top - 1 || me.bottom > box.bottom + 1 || me.left < box.left - 1 || me.right > box.right + 1) return true
+    }
+    return false
+  }
+  if (b.top < 0 || b.left < 0 || b.bottom > innerHeight || b.right > innerWidth || clipped()) el.scrollIntoView({ block: 'center', inline: 'center' })
   const after = el.getBoundingClientRect()
   const s = getComputedStyle(el)
   return JSON.stringify({ gone: false, x: Math.round(after.left + after.width / 2), y: Math.round(after.top + after.height / 2), name: String(el.innerText ?? el.value ?? el.getAttribute?.('aria-label') ?? '').trim().slice(0, 80), kind: String(el.tagName).toLowerCase(), hidden: s.visibility === 'hidden' || s.display === 'none', disabled: el.disabled === true })
 })()`
 }
 
+/**
+ * Click the control the page itself registered, instead of moving the mouse to
+ * it. A page whose own handlers want a click, or a control an overlay covers,
+ * is reachable this way; a page that watches real pointer movement is not.
+ * @param {number} ref - ref from a read.
+ * @param {{double?: boolean, right?: boolean}} [options] - how to click.
+ * @returns {string} an expression that answers with what it hit.
+ */
+export function clickInDom(ref, options = {}) {
+  const double = options.double === true
+  const right = options.right === true
+  return `(() => {
+  const reg = window.${REGISTRY}
+  const hit = reg && reg.find(${Number(ref)})
+  if (!hit) return JSON.stringify({ ok: false, gone: true })
+  const el = hit.el
+  const name = String(el.innerText ?? el.value ?? el.getAttribute?.('aria-label') ?? '').trim().slice(0, 60)
+  try { el.scrollIntoView({ block: 'center', inline: 'center' }) } catch { /* a detached node has no place */ }
+  try { el.focus({ preventScroll: true }) } catch { /* not every node takes focus */ }
+  const send = (type, button) => el.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true, view: window, button, buttons: type === 'mousedown' || type === 'pointerdown' ? (button === 2 ? 2 : 1) : 0 }))
+  if (${right}) {
+    el.dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, cancelable: true, view: window, button: 2 }))
+  } else {
+    send('pointerdown', 0)
+    send('mousedown', 0)
+    el.click ? el.click() : send('click', 0)
+    if (${double}) { el.click ? el.click() : send('click', 0) }
+    send('pointerup', 0)
+    send('mouseup', 0)
+  }
+  return JSON.stringify({ ok: true, name, tag: String(el.tagName).toLowerCase() })
+})()`
+}
+
+/**
+ * Put text into a control through the page's own value and input events, the
+ * way the page's own code would; no key is pressed and no pointer moves.
+ * @param {number} ref - ref from a read.
+ * @param {string} text - what to put in.
+ * @param {{clear?: boolean, submit?: boolean}} [options] - replace, and send it.
+ * @returns {string} an expression that answers with the field's new value.
+ */
+export function writeInDom(ref, text, options = {}) {
+  return `(() => {
+  const reg = window.${REGISTRY}
+  const hit = reg && reg.find(${Number(ref)})
+  if (!hit) return JSON.stringify({ ok: false, gone: true })
+  const el = hit.el
+  const whole = ${JSON.stringify(String(text))}
+  const clear = ${options.clear === true}
+  const submit = ${options.submit === true}
+  try { el.focus({ preventScroll: true }) } catch { /* a plain div takes no focus */ }
+  if (/^(input|textarea)$/i.test(el.tagName)) {
+    const proto = el.tagName === 'TEXTAREA' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype
+    const set = Object.getOwnPropertyDescriptor(proto, 'value')?.set
+    const next = clear ? whole : String(el.value ?? '') + whole
+    set === undefined ? (el.value = next) : set.call(el, next)
+    el.dispatchEvent(new Event('input', { bubbles: true }))
+    el.dispatchEvent(new Event('change', { bubbles: true }))
+  } else if (el.isContentEditable) {
+    el.textContent = clear ? whole : String(el.textContent ?? '') + whole
+    el.dispatchEvent(new InputEvent('input', { bubbles: true, data: whole, inputType: 'insertText' }))
+  } else {
+    return JSON.stringify({ ok: false, why: 'not a field' })
+  }
+  if (submit) {
+    const form = el.form ?? el.closest?.('form') ?? null
+    if (form && typeof form.requestSubmit === 'function') form.requestSubmit()
+    else el.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', keyCode: 13, bubbles: true }))
+  }
+  return JSON.stringify({ ok: true, value: String(el.value ?? el.textContent ?? '').slice(0, 60) })
+})()`
+}
+
 /**
  * How big the control is and where it sits, so a picture can be of it alone.
  * @param {number} ref - ref from a read.
@@ -578,12 +705,57 @@ function asRoute(route) {
  * @param {number|{contextId?: number, sessionId?: string}} [route] - where to run it.
  * @returns {Promise<any>} the JSON-safe value.
  */
-async function evaluateIn(page, expression, route) {
+/**
+ * Ask the page, but never forever. A navigation whose last request hangs can
+ * leave the renderer unable to answer: without a ceiling every read, click and
+ * type on such a page waits on the network, and the tool is killed instead of
+ * reporting. Timing out says so.
+ * @param {any} page - sidecar page.
+ * @param {any} params - Runtime.evaluate parameters.
+ * @param {string|undefined} sessionId - out-of-process frame, if any.
+ * @param {number} raceMs - ceiling in milliseconds.
+ * @returns {Promise<any>} the protocol answer.
+ */
+async function answer(page, params, sessionId, raceMs) {
+  let timer = null
+  const call = page.cdp.send('Runtime.evaluate', params, sessionId)
+  const raced = await Promise.race([call, new Promise((done) => { timer = setTimeout(() => done(null), raceMs) })])
+  clearTimeout(timer)
+  if (raced !== null) return raced
+  /* The page is probably stuck on a request of its own. A person presses Esc
+     and works with what arrived; stopping the load is the same move, and it is
+     what makes the next look answer at all. */
+  const began = Number(page.navStarted ?? 0)
+  const fired = Number(page.loadFired ?? 0)
+  if (began > 0 && began > fired) await page.cdp.send('Page.stopLoading', {}).catch(() => {})
+  let after = null
+  const retry = page.cdp.send('Runtime.evaluate', params, sessionId)
+  const again = await Promise.race([retry, new Promise((done) => { after = setTimeout(() => done(null), 600) })])
+  clearTimeout(after)
+  if (again !== null) return again
+  throw new Error(`the page did not answer within ${raceMs} ms (it is stuck loading)`)
+}
+
+async function evaluateIn(page, expression, route, raceMs = 3000) {
   const where = asRoute(route)
   const params = { expression, returnByValue: true }
   if (where.contextId !== undefined) params.contextId = where.contextId
-  const { result } = await page.cdp.send('Runtime.evaluate', params, where.sessionId)
-  return result?.value
+  let said
+  try {
+    said = await answer(page, params, where.sessionId, raceMs)
+  } catch (error) {
+    /* The world or the frame is gone: the caller needs to say so, not read an
+       empty page as a page that is empty. */
+    throw new Error(`the page did not answer (${String(error?.message ?? error).split('\n')[0]})`)
+  }
+  /* A page script that throws answers with no value and one line of why. Read
+     as an empty result, that is indistinguishable from a page with nothing on
+     it, and a broken page then looks empty instead of broken. */
+  if (said?.exceptionDetails !== undefined) {
+    const why = String(said.exceptionDetails.exception?.description ?? said.exceptionDetails.text ?? 'unknown error')
+    throw new Error(`the page's own script failed (${why.split('\n')[0].slice(0, 160)})`)
+  }
+  return said?.result?.value
 }
 
 /** @param {any} page - sidecar page. @param {any} [route] - world to seed. */
@@ -666,15 +838,17 @@ function routeOf(page, frame, slot) {
  * @returns {Promise<{text: string, controls: any[], frames: number}>} what the frames add.
  */
 async function readFrames(page, mode, budget) {
-  if (typeof page.frameList !== 'function') return { text: '', controls: [], frames: 0 }
+  const none = { text: '', controls: [], frames: 0, blind: { pictures: 0, canvases: 0, videos: 0, frames: 0, flash: 0 } }
+  if (typeof page.frameList !== 'function') return none
   let frames = []
   try {
     frames = await page.frameList()
   } catch (error) {
-    return { text: '', controls: [], frames: 0 }
+    return none
   }
   const children = frames.slice(1)
   const controls = []
+  const blind = { ...none.blind }
   let text = ''
   for (let slot = 0; slot < children.length && slot < 8; slot += 1) {
     const route = routeOf(page, children[slot], slot + 1)
@@ -689,11 +863,14 @@ async function readFrames(page, mode, budget) {
         controls.push({ ...item, ref: tag + Number(item.ref), frame: slot + 1, x: Number(item.x ?? 0) + offset.x, y: Number(item.y ?? 0) + offset.y })
       }
       if (text.length < 400 && typeof inside.text === 'string' && inside.text !== '') text += `${text === '' ? '' : '\n'}${inside.text.slice(0, 400)}`
+      /* What is out of reach inside a frame is out of reach here too: a canvas
+         or a movie in a frame is exactly the blank the reader cannot explain. */
+      for (const key of Object.keys(blind)) blind[key] += Math.max(0, Math.round(Number(inside.blind?.[key] ?? 0)))
     } catch (error) {
       continue
     }
   }
-  return { text, controls, frames: children.length }
+  return { text, controls, frames: children.length, blind }
 }
 
 /** Decode a ref into the frame it lives in and the number that frame knows. */
@@ -728,16 +905,359 @@ export async function contextFor(page, ref) {
  * @param {{mode?: string, maxChars?: number, max?: number}} [options] - how much to read.
  * @returns {Promise<{url: string, title: string, text: string, textChars: number, scroll?: any, focused?: any, controls: any[]}>} the read.
  */
+const EMPTY_BLIND = { pictures: 0, canvases: 0, videos: 0, frames: 0, flash: 0 }
+
+/**
+ * A read that failed: the address and the reason, with nothing invented.
+ * @param {any} page - sidecar page.
+ * @param {string} fault - why the page could not be read.
+ * @returns {any} the read.
+ */
+export function faultRead(page, fault) {
+  const empty = { text: '', textChars: 0, controls: [], picture: null, scroll: undefined, focused: null, blind: EMPTY_BLIND }
+  return Object.assign({ url: String(page.url ?? ''), title: String(page.title ?? ''), fault: String(fault) }, empty)
+}
+
+/**
+ * The page as a person reads it: headings, paragraphs, list items and links, as
+ * Markdown, with no markup and no controls to number. A long article costs a
+ * fraction of a snapshot, which is what makes reading a real page affordable.
+ * @param {number} budget - character ceiling for the returned text.
+ * @returns {string} a page script that returns JSON.
+ */
+export function article(budget) {
+  return `(() => {
+  const limit = ${budget}
+  const pick = document.querySelector('article, main, [role="main"]') || document.body
+  if (!pick) return JSON.stringify({ text: '', chars: 0, linkCount: 0, truncated: false })
+  const skip = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'SVG', 'IFRAME', 'CANVAS', 'VIDEO', 'HEADER', 'FOOTER', 'NAV', 'ASIDE'])
+  const lines = []
+  let length = 0
+  let truncated = false
+  let linkCount = 0
+  const walk = (node) => {
+    if (truncated || node === null || node === undefined) return
+    if (node.nodeType === 3) {
+      const text = String(node.textContent ?? '').replace(/\\s+/g, ' ').trim()
+      if (text !== '') { lines.push(text); length += text.length + 1 }
+      if (length >= limit) truncated = true
+      return
+    }
+    if (node.nodeType !== 1) return
+    const tag = node.tagName
+    if (skip.has(tag) || node.hidden === true || node.getAttribute?.('aria-hidden') === 'true') return
+    const style = getComputedStyle(node)
+    if (style.display === 'none' || style.visibility === 'hidden') return
+    if (/^H[1-6]$/.test(tag)) {
+      const text = String(node.innerText ?? '').replace(/\\s+/g, ' ').trim()
+      if (text !== '') { lines.push('#' .repeat(Number(tag.slice(1))) + ' ' + text); length += text.length + Number(tag.slice(1)) + 2 }
+      if (length >= limit) truncated = true
+      return
+    }
+    if (tag === 'A') {
+      linkCount += 1
+      const text = String(node.innerText ?? '').replace(/\\s+/g, ' ').trim()
+      const href = String(node.href ?? '')
+      if (text !== '' && /^https?:/.test(href)) {
+        const line = '[' + text.slice(0, 120) + '](' + href + ')'
+        lines.push(line); length += line.length + 1
+      } else if (text !== '') { lines.push(text); length += text.length + 1 }
+      if (length >= limit) truncated = true
+      return
+    }
+    if (tag === 'LI') {
+      const text = String(node.innerText ?? '').replace(/\\s+/g, ' ').trim()
+      if (text !== '') { lines.push('- ' + text); length += text.length + 3 }
+      if (length >= limit) truncated = true
+      return
+    }
+    if (tag === 'PRE' || tag === 'CODE') {
+      const text = String(node.innerText ?? '').slice(0, 1200)
+      if (text !== '') { lines.push('~~~'); lines.push(text); lines.push('~~~'); length += text.length + 8 }
+      if (length >= limit) truncated = true
+      return
+    }
+    for (const child of node.childNodes) walk(child)
+  }
+  walk(pick)
+  let text = lines.filter((one) => one !== '').join(String.fromCharCode(10)).trim()
+  if (text.length > limit) { text = text.slice(0, limit); truncated = true }
+  const allLinks = document.querySelectorAll('a[href]').length
+  return JSON.stringify({ text, chars: text.length, linkCount: allLinks, truncated })
+})()`
+}
+
+/**
+ * Find words on the page: numbered controls whose name matches, then plain text
+ * that is not a control. A phone-sized page has hundreds of lines; finding the
+ * three that mention what the caller wants costs a fraction of reading them.
+ * @param {string} query - words to look for.
+ * @param {boolean} asRegex - treat the words as a regular expression source.
+ * @param {number} limit - matches to return.
+ * @returns {string} an expression to evaluate.
+ */
+export function finder(query, asRegex, limit) {
+  return `(() => {
+  const reg = window.${REGISTRY}
+  if (!reg) return JSON.stringify({ broken: true })
+  const pattern = ${asRegex === true} ? new RegExp(${JSON.stringify(String(query))}, 'i') : null
+  const needle = ${JSON.stringify(String(query).toLowerCase())}
+  const test = (text) => pattern === null ? text.toLowerCase().includes(needle) : pattern.test(text)
+  const out = []
+  const seen = new Set()
+  /* A control inside a web component lives in a shadow root, where a document
+     query never looks; collect the open roots first, cheaply and bounded. */
+  const roots = [document]
+  for (let i = 0; i < roots.length && roots.length <= 200; i += 1) {
+    for (const host of roots[i].querySelectorAll('*')) {
+      if (host.shadowRoot) roots.push(host.shadowRoot)
+    }
+  }
+  const found = []
+  for (const root of roots) for (const el of root.querySelectorAll(reg.selector)) found.push(el)
+  for (const el of found) {
+    if (out.length >= ${limit}) break
+    if (!el || !el.isConnected) continue
+    const label = String(el.innerText ?? el.value ?? el.getAttribute?.('aria-label') ?? el.getAttribute?.('placeholder') ?? el.getAttribute?.('title') ?? '').replace(/\\s+/g, ' ').trim()
+    if (label === '' || label.length > 300 || !test(label)) continue
+    const b = el.getBoundingClientRect()
+    seen.add(el)
+    out.push({ ref: reg.id(el), name: label.slice(0, 120), tag: String(el.tagName).toLowerCase(), x: Math.round(b.x), y: Math.round(b.y), view: b.bottom > 0 && b.top < innerHeight })
+  }
+  if (out.length < ${limit} && document.body) {
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT)
+    let node = walker.nextNode()
+    while (node !== null && out.length < ${limit}) {
+      const parent = node.parentElement
+      if (parent !== null && !seen.has(parent) && !['SCRIPT', 'STYLE', 'NOSCRIPT'].includes(parent.tagName)) {
+        const text = String(node.nodeValue ?? '').replace(/\\s+/g, ' ').trim()
+        if (text !== '' && text.length < 400 && test(text)) {
+          const b = parent.getBoundingClientRect()
+          out.push({ ref: 0, name: text.slice(0, 120), tag: String(parent.tagName).toLowerCase(), x: Math.round(b.x), y: Math.round(b.y), view: b.bottom > 0 && b.top < innerHeight })
+        }
+      }
+      node = walker.nextNode()
+    }
+  }
+  return JSON.stringify({ matches: out })
+})()`
+}
+
+/**
+ * Run the finder against a page and give back its matches.
+ * @param {any} page - sidecar page.
+ * @param {string} query - words or pattern.
+ * @param {{regex?: boolean, limit?: number}} [options] - how to look.
+ * @returns {Promise<{matches: any[], fault?: string}>} what matched.
+ */
+export async function findOnPage(page, query, options = {}) {
+  const limit = Math.max(1, Math.min(40, Number(options.limit ?? 12)))
+  try {
+    await seedPage(page)
+    const raw = String((await evaluateIn(page, finder(query, options.regex === true, limit))) ?? '{}')
+    const said = JSON.parse(raw)
+    if (said?.broken === true) return { matches: [], fault: 'the page has not been read yet — call browser_view first' }
+    return said
+  } catch (error) {
+    return { matches: [], fault: String(error?.message ?? error) }
+  }
+}
+
+/**
+ * Collect the page as blocks of prose, each with the heading it sits under and
+ * how much of it is links. Navigation, sidebars and footers are mostly links;
+ * Readability's oldest signal is that such a block is not the content, and it
+ * costs one number to carry instead of a guess.
+ * @param {number} budget - characters of block text to collect.
+ * @returns {string} an expression to evaluate.
+ */
+export function blocks(budget) {
+  return `(() => {
+  const root = document.querySelector('article, main, [role="main"]') || document.body
+  if (!root) return JSON.stringify({ blocks: [] })
+  const limit = ${budget}
+  const BLOCK = new Set(['P', 'LI', 'TD', 'TH', 'BLOCKQUOTE', 'PRE', 'FIGCAPTION', 'DD', 'DT', 'SUMMARY'])
+  const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'SVG', 'IFRAME', 'CANVAS', 'VIDEO', 'HEADER', 'FOOTER', 'NAV', 'ASIDE', 'FORM', 'BUTTON', 'SELECT', 'TEXTAREA'])
+  const out = []
+  const seen = new Set()
+  let chars = 0
+  let heading = ''
+  const flatten = (text) => String(text ?? '').replace(/\\s+/g, ' ').trim()
+  const push = (el) => {
+    if (chars >= limit) return
+    const text = flatten(el.innerText ?? el.textContent ?? '')
+    if (text === '' || text.length > 4000) return
+    let linkChars = 0
+    for (const link of el.querySelectorAll('a')) linkChars += flatten(link.innerText ?? '').length
+    if (el.tagName === 'A') linkChars += text.length
+    const density = text.length === 0 ? 0 : Math.min(1, linkChars / text.length)
+    out.push({ h: heading, t: text, d: Math.round(density * 100) / 100 })
+    chars += text.length
+  }
+  const walk = (el) => {
+    if (chars >= limit || el === null) return
+    const tag = el.tagName
+    if (SKIP.has(tag) || el.hidden === true || el.getAttribute?.('aria-hidden') === 'true') return
+    const style = getComputedStyle(el)
+    if (style.display === 'none' || style.visibility === 'hidden') return
+    if (/^H[1-6]$/.test(tag)) {
+      heading = flatten(el.innerText ?? '')
+      return
+    }
+    if (BLOCK.has(tag)) {
+      if (!seen.has(el)) { seen.add(el); push(el) }
+      return
+    }
+    for (const child of el.children) walk(child)
+  }
+  walk(root)
+  const title = document.title
+  return JSON.stringify({ title, blocks: out })
+})()`
+}
+
+/** Words as the ranker sees them: ASCII runs, and every CJK character on its own. */
+const tokenPattern = /[a-z0-9]+|[\u3400-\u9fff]/g
+
+/**
+ * Cut text into comparable terms.
+ * @param {string} text - any text.
+ * @returns {string[]} lower-case terms.
+ */
+export function terms(text) {
+  return String(text ?? '').toLowerCase().match(tokenPattern) ?? []
+}
+
+/** How often a term may occur before it stops adding meaning. */
+const SATURATION = 1.5
+
+/**
+ * Rank blocks against a query the way a search engine ranks a passage: BM25,
+ * with the heading counted as a place a term can match. Then read only the
+ * blocks that carry the query, which is the token saving that matters.
+ * @param {{h?: string, t: string, d?: number}[]} blocks - page blocks.
+ * @param {string} query - what the caller wants to know.
+ * @returns {{block: any, score: number}[]} blocks, best first.
+ */
+export function rank(blocks, query) {
+  const asked = terms(query)
+  if (asked.length === 0) return []
+  const docs = blocks.map((block) => ({ block, terms: terms(`${block.h ?? ''} ${block.t}`) }))
+  const average = docs.reduce((sum, one) => sum + one.terms.length, 0) / Math.max(1, docs.length)
+  const seen = new Map()
+  for (const one of docs) for (const term of new Set(one.terms)) seen.set(term, (seen.get(term) ?? 0) + 1)
+  const total = Math.max(1, docs.length)
+  const scored = []
+  for (const one of docs) {
+    const counts = new Map()
+    for (const term of one.terms) counts.set(term, (counts.get(term) ?? 0) + 1)
+    let score = 0
+    for (const term of asked) {
+      const seenIn = seen.get(term) ?? 0
+      if (seenIn === 0) continue
+      const idf = Math.log(1 + (total - seenIn + 0.5) / (seenIn + 0.5))
+      const tf = counts.get(term) ?? 0
+      if (tf === 0) continue
+      const length = one.terms.length
+      score += idf * ((tf * (SATURATION + 1)) / (tf + SATURATION * (1 - 0.75 + (0.75 * length) / average)))
+    }
+    /* A block that is nearly all link is a menu: it matches words without
+       saying anything about them. */
+    score *= 1 - 0.8 * Number(one.block.d ?? 0)
+    if (score > 0) scored.push({ block: one.block, score })
+  }
+  scored.sort((a, b) => b.score - a.score)
+  return scored
+}
+
+/**
+ * Read only the passages of a page that answer a query, so a long page costs
+ * what the answer costs instead of what the page costs.
+ * @param {any} page - sidecar page.
+ * @param {string} query - what the caller wants to know.
+ * @param {{maxChars?: number, limit?: number}} [options] - ceilings.
+ * @returns {Promise<{title: string, url: string, text: string, chars: number, matched: number, total: number, fault?: string}>} the passages.
+ */
+export async function readRelevant(page, query, options = {}) {
+  const budget = Math.max(400, Math.min(24_000, Number(options.maxChars ?? 4000)))
+  try {
+    const raw = String((await evaluateIn(page, blocks(budget * 8))) ?? '{}')
+    const said = JSON.parse(raw)
+    const all = Array.isArray(said?.blocks) ? said.blocks : []
+    const ranked = rank(all, query)
+    if (ranked.length === 0) {
+      return { title: String(said?.title ?? page.title ?? ''), url: String(page.url ?? ''), text: '', chars: 0, matched: 0, total: all.length }
+    }
+    const limit = Math.max(1, Math.min(20, Number(options.limit ?? 8)))
+    const lines = []
+    let used = 0
+    let matched = 0
+    let lastHeading = ''
+    for (const row of ranked.slice(0, limit)) {
+      const body = String(row.block.t ?? '')
+      if (used + body.length > budget) continue
+      const heading = String(row.block.h ?? '')
+      if (heading !== '' && heading !== lastHeading) { lines.push(`## ${heading}`); lastHeading = heading }
+      lines.push(body)
+      used += body.length
+      matched += 1
+      if (used >= budget) break
+    }
+    return {
+      title: String(said?.title ?? page.title ?? ''),
+      url: String(page.url ?? ''),
+      text: lines.join('\n\n'),
+      chars: used,
+      matched,
+      total: all.length,
+    }
+  } catch (error) {
+    return { title: '', url: String(page.url ?? ''), text: '', chars: 0, matched: 0, total: 0, fault: String(error?.message ?? error) }
+  }
+}
+
+/**
+ * Read the page as Markdown, through the same deadline as a snapshot.
+ * @param {any} page - sidecar page.
+ * @param {{maxChars?: number}} [options] - character ceiling.
+ * @returns {Promise<{url: string, title: string, text: string, chars: number, linkCount: number, truncated: boolean, fault?: string}>} what it says.
+ */
+export async function readArticle(page, options = {}) {
+  const budget = Math.max(400, Math.min(24_000, Number(options.maxChars ?? 6000)))
+  try {
+    const raw = String((await evaluateIn(page, article(budget))) ?? '{}')
+    const said = JSON.parse(raw)
+    return {
+      url: String(page.url ?? ''),
+      title: String(await evaluateIn(page, 'document.title').catch(() => page.title ?? '') ?? ''),
+      text: String(said?.text ?? ''),
+      chars: Number(said?.chars ?? 0),
+      linkCount: Number(said?.linkCount ?? 0),
+      truncated: said?.truncated === true,
+    }
+  } catch (error) {
+    return { url: String(page.url ?? ''), title: String(page.title ?? ''), text: '', chars: 0, linkCount: 0, truncated: false, fault: String(error?.message ?? error) }
+  }
+}
+
 export async function readPage(page, options = {}) {
   const mode = String(options.mode ?? 'text')
   const maxChars = Number.isFinite(Number(options.maxChars)) ? Math.max(400, Math.min(24_000, Number(options.maxChars))) : 6000
   const max = Number.isFinite(Number(options.max)) ? Math.max(5, Math.min(200, Number(options.max))) : 90
-  await seedPage(page)
-  let read = await evaluateSnapshot(page, mode, maxChars, max)
-  if (read?.broken === true) {
-    await seedPage(page)
-    read = await evaluateSnapshot(page, mode, maxChars, max)
+  /* A page that refuses to run the reader gets two tries and then one line
+     saying why; an empty page must not be confused with a broken one. */
+  let fault = ''
+  let read = {}
+  for (let attempt = 0; attempt < 2 && fault === ''; attempt += 1) {
+    try {
+      await seedPage(page)
+      read = await evaluateSnapshot(page, mode, maxChars, max)
+      if (read?.broken === true) fault = attempt === 1 ? 'the page replied with something that was not a read' : ''
+    } catch (error) {
+      fault = String(error?.message ?? error)
+    }
   }
+  if (fault !== '') return faultRead(page, fault)
   const framed = await readFrames(page, mode, Math.min(maxChars, 1200))
   if (framed.controls.length > 0) read = { ...read, controls: [...(read.controls ?? []), ...framed.controls] }
   if (framed.text !== '') read = { ...read, text: `${String(read.text ?? '')}${String(read.text ?? '') === '' ? '' : '\n'}${framed.text}` }
@@ -750,7 +1270,11 @@ export async function readPage(page, options = {}) {
     scroll: read?.scroll,
     focused: read?.focused ?? null,
     controls: Array.isArray(read?.controls) ? read.controls : [],
-    blind: blindSpots(read?.blind, framed.frames),
+    blind: (() => {
+      const own = blindSpots(read?.blind, framed.frames)
+      for (const key of Object.keys(own)) own[key] += Number(framed.blind?.[key] ?? 0)
+      return own
+    })(),
   }
 }
 
@@ -758,7 +1282,7 @@ export async function readPage(page, options = {}) {
  * Merge what the page counted with what the frame reader managed to see.
  * @param {any} said - counts from the page.
  * @param {number} [read] - frames that answered.
- * @returns {{pictures: number, canvases: number, videos: number, frames: number}} what text cannot show.
+ * @returns {{pictures: number, canvases: number, videos: number, frames: number, flash: number}} what text cannot show.
  */
 export function blindSpots(said, read) {
   const n = (value) => (Number.isFinite(Number(value)) ? Math.max(0, Math.round(Number(value))) : 0)
@@ -766,7 +1290,7 @@ export function blindSpots(said, read) {
      many exist, tracking pixels included. The screen is what the reader is
      missing, so its count wins whenever the page could count at all. */
   const frames = said !== undefined && said !== null && said.frames !== undefined ? n(said.frames) : n(read)
-  return { pictures: n(said?.pictures), canvases: n(said?.canvases), videos: n(said?.videos), frames }
+  return { pictures: n(said?.pictures), canvases: n(said?.canvases), videos: n(said?.videos), frames, flash: n(said?.flash) }
 }
 
 /**
@@ -833,15 +1357,69 @@ function sigilOf(control) {
 export function renderPage(read, options = {}) {
   const mode = String(options.mode ?? 'text')
   const maxChars = Number(options.maxChars ?? 6000)
+  const maxControls = Number(options.maxControls ?? 140)
   const lines = [read.url]
   /* A browser error page is not a site with nothing on it: it is a site that
      never arrived. Saying so is the only way the reader stops looking for the
      content that would have been there. */
-  if (String(read.url).startsWith('chrome-error://')) lines.push('the page did not load — sidecar_nav to open the address again, or sidecar_open if the browser is gone')
+  if (String(read.url).startsWith('chrome-error://')) lines.push('the page did not load — browser_nav to open the address again, or browser_open if the browser is gone')
+  if (String(read.fault ?? '') !== '') lines.push(`the page did not answer when read — ${String(read.fault).slice(0, 200)}`)
   if (read.title !== '') lines.push(`# ${read.title}`)
+  /* A map is for a page too big to read: what it is made of and where the
+     things worth clicking are, without the words. One screen of landmarks
+     instead of forty thousand characters of page. */
+  if (mode === 'map') {
+    const kinds = new Map()
+    for (const control of read.controls) kinds.set(sigilOf(control), Number(kinds.get(sigilOf(control)) ?? 0) + 1)
+    const kindsText = [...kinds].map(([kind, count]) => `${kind}×${count}`).join(', ')
+    lines.push(`map: ${String(read.controls.length)} controls${kindsText === '' ? '' : ` — ${kindsText}`}`)
+    const seenNames = new Set()
+    let listedNames = 0
+    for (const control of read.controls) {
+      const key = `${sigilOf(control)}|${control.name}`
+      if (seenNames.has(key)) continue
+      seenNames.add(key)
+      lines.push(`${String(control.ref)} [${sigilOf(control)}] ${control.name === '' ? '(unnamed)' : control.name}`)
+      listedNames += 1
+      if (listedNames >= 24) break
+    }
+    const rest = read.controls.length - listedNames
+    if (rest > 0) lines.push(`… ${String(rest)} more, counted above — browser_view mode links or forms lists every one`)
+    const words = Number(read.textChars ?? String(read.text ?? '').length)
+    if (words > 0) lines.push(`words: ${String(words)} characters — browser_read for the text, or browser_read with query for one answer`)
+    if (read.focused) lines.push(`focus ${String(read.focused.ref)} [${String(read.focused.kind)}] ${String(read.focused.name)}`)
+    const out = lines.join('\n')
+    return out.length > maxChars ? `${out.slice(0, Math.max(0, maxChars - 40))}\n… (cut at ${String(maxChars)} characters)` : out
+  }
   const shown = read.controls.filter((control) => control.view !== false || mode === 'full')
   const hidden = read.controls.length - shown.length
-  for (const control of shown) {
+  /* A page with hundreds of rows would spend the whole budget on numbers and
+     leave no room for the words that say what the page is; the rest keep their
+     refs and come back with a narrower mode or after a scroll. */
+  const listed = shown.length > maxControls ? shown.slice(0, maxControls) : shown
+  /* A listing page repeats the same word down the page: thirty "Add to cart",
+     a header menu repeated in the footer. A person reading it sees one idea,
+     so it gets one line with a count; the first ref still clicks, and mode
+     links or forms lists every one when a caller needs a particular row. */
+  const tally = new Map()
+  if (mode === 'text') {
+    for (const control of listed) {
+      const key = `${sigilOf(control)}|${control.name}|${control.checked ? 1 : 0}`
+      const seen = tally.get(key)
+      if (seen === undefined) tally.set(key, { first: control, count: 1 })
+      else seen.count += 1
+    }
+  }
+  const repeated = (control) => tally.get(`${sigilOf(control)}|${control.name}|${control.checked ? 1 : 0}`)
+  const done = new Set()
+  for (const control of listed) {
+    const group = mode === 'text' ? repeated(control) : undefined
+    if (group !== undefined && group.count > 2) {
+      if (done.has(group)) continue
+      done.add(group)
+      lines.push(`${control.ref} [${sigilOf(control)}] ${control.name === '' ? '(unnamed)' : control.name} ×${group.count}`)
+      continue
+    }
     let line = `${control.ref} [${sigilOf(control)}] ${control.name === '' ? '(unnamed)' : control.name}`
     if (control.kind === 'checkbox' || control.kind === 'radio') line += control.checked ? ' (checked)' : ' (unchecked)'
     else if (control.value !== '' && control.value !== control.name) line += ` = ${control.value}`
@@ -850,12 +1428,32 @@ export function renderPage(read, options = {}) {
     lines.push(line)
   }
   if (hidden > 0 && mode !== 'links' && mode !== 'forms') lines.push(`… ${hidden} more controls off screen`)
+  if (shown.length > listed.length) lines.push(`… ${shown.length - listed.length} more controls on this screen — browser_scroll, or ask for mode links or forms`)
   if (read.focused) lines.push(`focus ${read.focused.ref} [${read.focused.kind}] ${read.focused.name}`)
-  const body = read.text
+  let body = read.text
+  /* A listing page's words are its button labels again: printing them twice
+     doubles the cost of the read. Only when most of the screen's words came
+     from controls — an article's prose stays. */
+  if (mode === 'text' && body.length > 200 && listed.length > 1) {
+    let covered = 0
+    for (const control of listed) {
+      const name = String(control.name ?? '')
+      if (name.length < 3) continue
+      let at = body.indexOf(name)
+      while (at !== -1 && covered < body.length) {
+        covered += name.length
+        at = body.indexOf(name, at + name.length)
+      }
+    }
+    if (covered / body.length > 0.55) body = ''
+  }
   if (body !== '') {
     lines.push('')
     lines.push(body)
     if (read.textChars > body.length) lines.push(`… ${read.textChars - body.length} more characters`)
+  } else if (read.text !== '') {
+    lines.push('')
+    lines.push(`the words here are the ${listed.length} controls above — browser_view {mode:'full'} for the page's own wording`)
   }
   if (read.blind !== undefined && read.blind !== null) {
     const bits = []
@@ -863,9 +1461,15 @@ export function renderPage(read, options = {}) {
     if (read.blind.canvases > 0) bits.push(`${read.blind.canvases} drawing surface(s)`)
     if (read.blind.videos > 0) bits.push(`${read.blind.videos} video(s)`)
     if (read.blind.frames > 0) bits.push(`${read.blind.frames} embedded frame(s)`)
+    if (read.blind.flash > 0) bits.push(`${read.blind.flash} Flash movie(s) this browser cannot play — look for the site's own H5 or micro-client version`)
     /* Only when something is actually out of reach: a line saying "nothing is
        hidden" on every read is a line the reader learns to skip. */
-    if (bits.length > 0) lines.push(`text cannot show: ${bits.join(', ')} — sidecar_grab takes the picture, sidecar_shot shows the screen`)
+    if (bits.length > 0) lines.push(`text cannot show: ${bits.join(', ')} — browser_grab takes the picture, browser_shot shows the screen`)
+    /* Almost no words but frames on screen is the shape of a plugin game. Saying
+       it here is the difference between "blank page" and "this needs Flash". */
+    if (read.blind.flash === 0 && read.blind.frames > 0 && Number(read.textChars ?? 0) < 400) {
+      lines.push(`${read.blind.frames} frame(s) and almost no text: the content is inside them — if it stays blank it may be a plugin game this browser cannot play; look for the site's H5 or micro-client version`)
+    }
   }
   if (read.picture && Array.isArray(read.picture.missing)) {
     /* Something was meant to be here and is not: say that instead of nothing. */
@@ -877,7 +1481,7 @@ export function renderPage(read, options = {}) {
     const pic = read.picture
     const look = Number(pic.flat) >= 0.9 ? 'mostly one colour' : Number(pic.colors) <= 3 ? 'a few colours' : 'a picture with detail'
     const size = `${Math.round(Number(pic.width) || 0)}x${Math.round(Number(pic.height) || 0)}`
-    lines.push(`picture ${size} ${look}${pic.name === '' ? '' : ` "${pic.name}"`} — sidecar_grab saves it as a file`)
+    lines.push(`picture ${size} ${look}${pic.name === '' ? '' : ` "${pic.name}"`} — browser_grab saves it as a file`)
   }
   if (read.scroll && read.scroll.height > read.scroll.viewport + 40) {
     lines.push(`scroll ${read.scroll.y}/${read.scroll.height - read.scroll.viewport}`)
@@ -886,7 +1490,7 @@ export function renderPage(read, options = {}) {
 }
 
 /** A ref that was valid on the previous read and is no longer here. */
-export const REF_GONE = 'That control is gone: the page changed since the read. Call sidecar_view and use the new number.'
+export const REF_GONE = 'That control is gone: the page changed since the read. Call browser_view and use the new number.'
 
 /**
  * The control itself, not its number: what it is, what it is called, and where