dsh-inner-browser-use 0.27.0 → 0.34.95

package/tools.js

@@ -5,26 +5,179 @@
  * Two costs decide whether this is usable: the tokens a read spends, and the
  * round trips a task spends. The tool surface here is shaped around both — a
  * read can be narrowed (`mode`, `max_chars`) and diffed (`changed_only`), and
- * `sidecar_do` runs a run of steps in one call with waits that know when a page
+ * `browser_do` runs a run of steps in one call with waits that know when a page
  * has settled.
  */
 
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { createHash } from 'node:crypto'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { mkdir, writeFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { mkdir, readdir, stat, unlink, writeFile } from 'node:fs/promises'
 import { VIEW } from './sidecar.js?v=1'
-import { readPage, renderPage, locate, covering, contextFor, identityOf, sameThing, labelSpot, selectSpot, bounds, pictures, REF_GONE } from './read.js?v=1'
+import { readPage, renderPage, readArticle, readRelevant, findOnPage, locate, covering, contextFor, identityOf, sameThing, differs, labelSpot, selectSpot, bounds, pictures, clickInDom, writeInDom, REF_GONE } from './read.js?v=1'
+import { brief as askBrief, recordRound, lastRoundNote, lastRound, markRound, MARK_STATUS } from './review.js?v=1'
 
-/** Where a screenshot from `sidecar_shot` lands, under the user's home. */
-export const SHOT_DIR = join('.dsh-inner-browser-use', 'screenshots')
+/** Which chat the running call belongs to, so each gets its own tab. */
+export const sessionScope = new AsyncLocalStorage()
+
+/** @returns {string} the chat id of the running call. */
+function currentSession() {
+  return String(sessionScope.getStore() ?? '')
+}
+
+/** How a call asked to act: real mouse and keys, or the page's own DOM. */
+const WAYS = new Set(['human', 'dom'])
+
+/** The way each chat said to act, until it says otherwise. */
+const chatWays = new Map()
+
+/**
+ * The way this call should act: what it asked for, else what its chat last set,
+ * else a real mouse and real keys, which no page can tell from a person.
+ * @param {any} args - the call's arguments.
+ * @returns {'human'|'dom'} which way.
+ */
+function wayOf(args) {
+  const said = String(args?.mode ?? '')
+  if (WAYS.has(said)) return /** @type {'human'|'dom'} */ (said)
+  const chat = currentSession()
+  return chatWays.get(chat) === 'dom' ? 'dom' : 'human'
+}
+
+/** Which project the running call belongs to, so its files stay together. */
+export const workScope = new AsyncLocalStorage()
+
+/** Where files a call produces land, under the user's home. */
+export const ARTIFACT_ROOT = String(process.env.DSH_INNER_BROWSER_ARTIFACTS ?? '') !== ''
+  ? String(process.env.DSH_INNER_BROWSER_ARTIFACTS)
+  : join(homedir(), '.dsh-inner-browser-use', 'artifacts')
+
+/** How many files one kind keeps per chat; older ones go. */
+export const ARTIFACT_KEEP = 40
+
+/** Project folder name: the folder's own name, plus a short hash of its path. */
+function projectKey() {
+  const cwd = String(workScope.getStore() ?? '')
+  if (cwd === '') return 'no-project'
+  const named = basename(cwd).toLowerCase().replace(/[^a-z0-9._-]/g, '-').replace(/^-+|-+$/g, '')
+  return `${named === '' ? 'project' : named}-${createHash('sha1').update(cwd).digest('hex').slice(0, 6)}`
+}
+
+/** Chat folder name: the short id a person can match to the chat. */
+function sessionKey() {
+  const id = currentSession().replace(/^session-/, '').replace(/[^a-z0-9-]/gi, '')
+  return id === '' ? 'no-chat' : id.slice(0, 8)
+}
+
+/**
+ * Where one kind of file for this project and this chat goes.
+ * `~/.dsh-inner-browser-use/artifacts/<project>/<chat>/<kind>/`
+ * @param {string} kind - shots, pictures, pdf.
+ * @returns {string} absolute directory; not created yet.
+ */
+export function artifactDir(kind) {
+  return join(ARTIFACT_ROOT, projectKey(), sessionKey(), kind)
+}
+
+/**
+ * Write one file where the project and the chat expect it, and keep the folder
+ * from growing without a limit.
+ * @param {string} kind - shots, pictures, pdf.
+ * @param {string} body - base64 body.
+ * @param {{name?: string, ext?: string, prefix?: string}} [options] - file name.
+ * @returns {Promise<string>} absolute path.
+ */
+export async function saveArtifact(kind, body, options = {}) {
+  const dir = artifactDir(kind)
+  await mkdir(dir, { recursive: true })
+  const ext = String(options.ext ?? '.png')
+  /* A name is a name: no separators, no runs of dots that could read as a path
+     climb, and no leading dot to hide the file. */
+  const wanted = String(options.name ?? '').replace(/[^\w.-]/g, '').replace(/\.(png|jpe?g|webp|pdf)$/i, '').replace(/\.{2,}/g, '.').replace(/^\.+/, '')
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15)
+  const prefix = String(options.prefix ?? kind)
+  const file = join(dir, `${wanted === '' ? `${prefix}-${stamp}` : wanted}${ext}`)
+  await writeFile(file, Buffer.from(body, 'base64'))
+  await pruneArtifacts(dir, ARTIFACT_KEEP)
+  return file
+}
+
+/**
+ * Keep the newest `keep` files in one folder: a browser session that runs all
+ * day does not leave a folder nobody can look through.
+ * @param {string} dir - folder to trim.
+ * @param {number} keep - how many files survive.
+ * @returns {Promise<void>} done.
+ */
+export async function pruneArtifacts(dir, keep) {
+  let names
+  try {
+    names = await readdir(dir)
+  } catch {
+    return
+  }
+  const listed = []
+  for (const name of names) {
+    try {
+      listed.push({ name, at: (await stat(join(dir, name))).mtimeMs })
+    } catch {
+      /* a file that vanished between listing and reading is already gone */
+    }
+  }
+  if (listed.length <= keep) return
+  listed.sort((left, right) => right.at - left.at)
+  for (const spare of listed.slice(keep)) {
+    try {
+      await unlink(join(dir, spare.name))
+    } catch {
+      /* best effort: a file in use stays */
+    }
+  }
+}
 
 /** How many times a call found a control again after the page redrew it. */
 const follows = { count: 0 }
 
 /** Shown when the sidecar has never been started in this run. */
-export const SIDECAR_OFF = 'The sidecar browser is not running. Call sidecar_open with the address first.'
+export const SIDECAR_OFF = 'The sidecar browser is not running. Call browser_open with the address first.'
 
 /** Output schema every tool returns. */
+/** The picture half of a screenshot result: shown only when the route can see it. */
+const SHOT_IMAGE = {
+  type: 'object', // ui-copy-ignore
+  properties: {
+    attachmentId: { type: 'string' },
+    mediaType: { type: 'string' },
+    bytes: { type: 'integer' }, // ui-copy-ignore
+    width: { type: 'integer' }, // ui-copy-ignore
+    height: { type: 'integer' }, // ui-copy-ignore
+    name: { type: 'string' }, // ui-copy-ignore
+  },
+  required: ['attachmentId', 'mediaType', 'bytes', 'width', 'height'],
+  additionalProperties: false,
+}
+
+/** A screenshot's path, plus the picture when this model can look at it. */
+export const SHOT_OUTPUT = {
+  schema: { // ui-copy-ignore
+    type: 'object', // ui-copy-ignore
+    properties: { text: { type: 'string' }, image: SHOT_IMAGE },
+    required: ['text'],
+    additionalProperties: false,
+  },
+  /**
+   * @param {unknown} _args - call arguments, unused.
+   * @param {any} value - tool value.
+   * @returns {any[]} the text, and the picture when there is one.
+   */
+  render(_args, value) {
+    const blocks = [{ type: 'text', text: String(value?.text ?? '') }]
+    if (value?.image !== undefined) blocks.push({ type: 'image', attachment: value.image })
+    return blocks
+  },
+}
+
 const TEXT_OUTPUT = {
   schema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'], additionalProperties: false },
   /**
@@ -45,18 +198,38 @@ const TEXT_OUTPUT = {
  * @param {any} page - sidecar page.
  * @returns {Promise<string>} address, title, focus and any open dialog.
  */
+export const BRIEF_JS = `(() => {
+    const a = document.activeElement
+    const secret = a !== null && typeof a === 'object' && (String(a.type ?? '') === 'password' || String(a.getAttribute === undefined ? '' : a.getAttribute('type') ?? '') === 'password')
+    const focus = a !== null && a !== document.body && a !== document.documentElement
+      ? { name: String(a.getAttribute('aria-label') || a.getAttribute('placeholder') || (a.labels && a.labels[0] && a.labels[0].innerText) || a.innerText || a.name || a.tagName).trim().slice(0, 60), value: secret ? '' : String(a.value === undefined ? '' : a.value).slice(0, 60) }
+      : null
+    return { url: location.href, title: document.title.slice(0, 80), focus }
+  })()`
+
 async function brief(page) {
   const dialog = page.dialog
   if (dialog !== null && dialog !== undefined) {
     return `${String(page.url ?? '')} · dialog ${String(dialog.type ?? '')}: ${String(dialog.message ?? '')}`
   }
-  const info = await evaluate(page, `(() => {
-    const a = document.activeElement
-    const focus = a !== null && a !== document.body && a !== document.documentElement
-      ? { name: String(a.getAttribute('aria-label') || a.getAttribute('placeholder') || (a.labels && a.labels[0] && a.labels[0].innerText) || a.innerText || a.name || a.tagName).trim().slice(0, 60), value: String(a.value === undefined ? '' : a.value).slice(0, 60) }
-      : null
-    return { url: location.href, title: document.title.slice(0, 80), focus }
-  })()`)
+  /* On a Flash page the DOM around the plugin says nothing about what is on
+     screen, and reading it right after a click waits for the main thread the
+     plugin is holding. The bridge answers with the address and title instead. */
+  if (page.flashBridge !== null && page.flashBridge !== undefined) {
+    try {
+      const reply = await fetch(`http://127.0.0.1:${page.flashBridge}/info`, { signal: AbortSignal.timeout(600) })
+      if (reply.ok === true) {
+        const info = await reply.json()
+        const bits = [String(info?.url ?? page.url ?? '')]
+        if (String(info?.title ?? '') !== '') bits.push(String(info.title))
+        return bits.join(' · ')
+      }
+    } catch {
+      /* the cached address below is still a true answer */
+    }
+    return String(page.url ?? '')
+  }
+  const info = await evaluate(page, BRIEF_JS)
   const bits = [String(info?.url ?? '')]
   if (String(info?.title ?? '') !== '') bits.push(String(info.title))
   if (info?.focus) bits.push(`focus ${info.focus.name}${info.focus.value === '' ? '' : ` = ${info.focus.value}`}`)
@@ -71,9 +244,117 @@ async function brief(page) {
  * @param {string} label - what was done.
  * @returns {Promise<string>} reply text.
  */
+/** The address each page last reported to the model, so it is said once. */
+const saidUrls = new WeakMap()
+
+/**
+ * The address is worth one line the first time and every time it changes; the
+ * same address on every step is a cost with nothing to teach — the model read
+ * it a step ago and still has it. Titles and focus still come through.
+ * @param {any} page - sidecar page.
+ * @param {string} briefText - address, title and focus as `brief` built them.
+ * @returns {string} the line to send.
+ */
+/**
+ * A PDF is a document, not a blank page: say so, and put its bytes somewhere a
+ * reader can open them. The mirror cannot draw a PDF, and a model looking at an
+ * empty screen would otherwise think the address had nothing on it.
+ * @param {any} page - the tab.
+ * @returns {Promise<string>} a line to append to the read, or ''.
+ */
+async function pdfNote(page) {
+  const found = page?.pdf
+  if (found === null || found === undefined) return ''
+  let file = { path: '', bytes: 0 }
+  try {
+    file = await page.documentFile()
+  } catch (error) {
+    file = { path: '', bytes: 0 }
+  }
+  const size = file.bytes > 0 ? ` (${String(Math.max(1, Math.round(file.bytes / 1024)))} KB)` : ''
+  return file.path === ''
+    ? `\nthis address is a PDF${size}: the mirror cannot draw it, and its bytes could not be saved. browser_downloads lists what the browser has downloaded.`
+    : `\nthis address is a PDF${size}: the mirror cannot draw it. Saved to ${file.path} — envoy_read can read that file, or another document reader.`
+}
+
+/**
+ * The numbered controls that were not on the page at the read before this one.
+ * A model that just acted cares about what its action brought in, and saying so
+ * costs a few numbers instead of a whole second read.
+ * @param {any} before - the read before this one, or undefined.
+ * @param {any} after - the read now.
+ * @returns {number[]} refs in `after` that `before` did not have.
+ */
+export function freshRefs(before, after) {
+  if (before === undefined || before === null) return []
+  if (after === undefined || after === null) return []
+  const had = new Set((Array.isArray(before.controls) ? before.controls : []).map((control) => Number(control?.ref ?? -1)))
+  const fresh = []
+  for (const control of Array.isArray(after.controls) ? after.controls : []) {
+    const ref = Number(control?.ref ?? -1)
+    if (ref < 0 || had.has(ref)) continue
+    if (!fresh.includes(ref)) fresh.push(ref)
+  }
+  return fresh
+}
+
+/** What an action did, in one line: where it went, whether the page moved at all. */
+export async function outcome(page, before) {
+  if (typeof before !== 'string' || before === '') return ''
+  const after = await pageMark(page)
+  if (after === '') return ''
+  /* A movie has no DOM to compare: its frame counter is the whole answer. */
+  if (before.startsWith('flash:') && after.startsWith('flash:')) {
+    return before === after ? ' · no frame change' : ' · screen updated'
+  }
+  const [wasTitle, wasUrl, wasText, wasNodes] = before.split('|')
+  const [nowTitle, nowUrl, nowText, nowNodes] = after.split('|')
+  if (after === before) return ' · no visible change'
+  if (nowUrl !== wasUrl) return ` · navigated to ${String(nowUrl).slice(0, 300)}`
+  const words = Math.abs(Number(nowText ?? 0) - Number(wasText ?? 0))
+  const nodes = Math.abs(Number(nowNodes ?? 0) - Number(wasNodes ?? 0))
+  if (nowTitle !== wasTitle) return ' · page moved on'
+  if (words >= 20 || nodes >= 3) return ' · content changed'
+  return ' · no visible change'
+}
+
+/** Read results this chat already paid for, keyed by what the page looks like. */
+const readSeen = new WeakMap()
+
+export function oncePerPage(page, briefText) {
+  const parts = String(briefText).split(' · ')
+  const url = String(parts[0] ?? '')
+  const known = page === null || page === undefined ? undefined : saidUrls.get(page)
+  if (url !== '' && known !== undefined) {
+    saidUrls.set(page, url)
+    if (url === known && parts.length > 1) return parts.slice(1).join(' · ')
+    return briefText
+  }
+  if (url !== '' && page !== null && page !== undefined) saidUrls.set(page, url)
+  return briefText
+}
+
+/**
+ * A read that starts with an address the model was already given opens with the
+ * page itself. The address is how a page says which page it is, not something
+ * to repeat every read; a page that moved says the new address in full.
+ * @param {any} page - sidecar page.
+ * @param {string} url - the address this read is from.
+ * @param {string} text - the rendered read.
+ * @returns {string} the read, without a leading address already said.
+ */
+export function withoutSeenAddress(page, url, text) {
+  const body = String(text ?? '')
+  const address = String(url ?? '')
+  if (address === '' || page === null || page === undefined) return body
+  const first = body.split('\n')[0]
+  if (first !== address || saidUrls.get(page) !== address) return body
+  return body.slice(first.length + 1)
+}
+
 async function acted(page, args, look, label) {
   if (args?.read === true) return await look()
-  return `ok ${label} · ${await brief(page)}`
+  return `ok ${label} · ${oncePerPage(page, await brief(page))}`
 }
 
 /**
@@ -94,7 +375,7 @@ async function acted(page, args, look, label) {
 /** Titles a site shows while it asks the browser to prove a person is there. */
 const CHECK_TITLES = ['请稍候', 'just a moment', 'checking your browser', 'verifying you are human', 'attention required']
 
-const CHECK_NOTE = 'That is the site asking a browser to prove a person is there, and a windowless one never gets past it. sidecar_open with headless false opens a window on the same profile, with the same logins.'
+const CHECK_NOTE = 'That is the site asking a browser to prove a person is there, and a windowless one never gets past it. browser_open with headless false opens a window on the same profile, with the same logins.'
 
 /**
  * A check page: the site has not refused, it is asking for proof. Reading it
@@ -156,27 +437,36 @@ export async function unreachable(page) {
   if (!isErrorPage(page)) return ''
   /* The code is the part a model can act on: ERR_NAME_NOT_RESOLVED is a typo,
      ERR_PROXY_CONNECTION_FAILED is this machine's proxy, ERR_TIMED_OUT is slow. */
-  let detail = String(page.title ?? '')
+  let detail = ''
   try {
     const said = await evaluate(page, `(() => {
       const text = String(document.body ? document.body.innerText : '')
       const code = (String(text).match(/ERR_[A-Z0-9_]+/) || [''])[0]
-      return code === '' ? String(document.title || '') : code
+      return code
     })()`)
-    if (typeof said === 'string' && said.trim() !== '') detail = said.trim()
+    if (typeof said === 'string') detail = said.trim()
   } catch {
     /* The error page itself refused to be read; the address still says enough. */
   }
-  return `the network could not reach that address — the browser stopped on its own error page (${detail === '' ? 'no details' : detail}), which is not the site. Nothing on it is page content. Use sidecar_nav with another address, or fix the connection this machine needs.`
+  /* Chrome often writes the address it could not reach where the code would
+     be: that is still the one thing the person can check. */
+  if (detail === '') {
+    const title = String(page.title ?? '').trim()
+    if (title !== '' && !/\s/.test(title)) detail = title
+  }
+  if (detail === '') detail = String(page.wantUrl ?? page.lastUrl ?? '').replace(/^https?:\/\//, '').replace(/\/.*$/, '')
+  return `the network could not reach that address — the browser stopped on its own error page (${detail === '' ? 'no details' : detail}), which is not the site. Nothing on it is page content. Use browser_nav with another address, or fix the connection this machine needs.`
 }
 
-/** Key names this driver can press, spelled as a model would. */
+/** Key names this driver can press: DOM `key` names for the named keys, and
+    the character itself for a printable one (Space also answers to `Space`). */
 export const KEYS = {
   Enter: { key: 'Enter', code: 'Enter', keyCode: 13, text: '\r' },
   Tab: { key: 'Tab', code: 'Tab', keyCode: 9 },
   Escape: { key: 'Escape', code: 'Escape', keyCode: 27 },
   Backspace: { key: 'Backspace', code: 'Backspace', keyCode: 8 },
   Delete: { key: 'Delete', code: 'Delete', keyCode: 46 },
+  Insert: { key: 'Insert', code: 'Insert', keyCode: 45 },
   ArrowUp: { key: 'ArrowUp', code: 'ArrowUp', keyCode: 38 },
   ArrowDown: { key: 'ArrowDown', code: 'ArrowDown', keyCode: 40 },
   ArrowLeft: { key: 'ArrowLeft', code: 'ArrowLeft', keyCode: 37 },
@@ -186,6 +476,208 @@ export const KEYS = {
   PageUp: { key: 'PageUp', code: 'PageUp', keyCode: 33 },
   PageDown: { key: 'PageDown', code: 'PageDown', keyCode: 34 },
   Space: { key: ' ', code: 'Space', keyCode: 32, text: ' ' },
+  ContextMenu: { key: 'ContextMenu', code: 'ContextMenu', keyCode: 93 },
+  CapsLock: { key: 'CapsLock', code: 'CapsLock', keyCode: 20 },
+  NumLock: { key: 'NumLock', code: 'NumLock', keyCode: 144 },
+  ScrollLock: { key: 'ScrollLock', code: 'ScrollLock', keyCode: 145 },
+  PrintScreen: { key: 'PrintScreen', code: 'PrintScreen', keyCode: 44 },
+  Pause: { key: 'Pause', code: 'Pause', keyCode: 19 },
+  NumpadEnter: { key: 'Enter', code: 'NumpadEnter', keyCode: 13, text: '\r' },
+  AudioVolumeMute: { key: 'AudioVolumeMute', code: 'AudioVolumeMute', keyCode: 173 },
+  AudioVolumeDown: { key: 'AudioVolumeDown', code: 'AudioVolumeDown', keyCode: 174 },
+  AudioVolumeUp: { key: 'AudioVolumeUp', code: 'AudioVolumeUp', keyCode: 175 },
+  MediaPlayPause: { key: 'MediaPlayPause', code: 'MediaPlayPause', keyCode: 179 },
+  MediaTrackNext: { key: 'MediaTrackNext', code: 'MediaTrackNext', keyCode: 176 },
+  MediaTrackPrevious: { key: 'MediaTrackPrevious', code: 'MediaTrackPrevious', keyCode: 177 },
+  MediaStop: { key: 'MediaStop', code: 'MediaStop', keyCode: 178 },
+}
+
+/* A game moves while a key is held, and the keys a game listens for are letters
+   and digits, not the ones a form needs. Each entry carries what a browser
+   reports: the `key` value, the physical `code`, and the legacy number old
+   engines still look at. */
+for (const letter of 'abcdefghijklmnopqrstuvwxyz') {
+  KEYS[letter] = { key: letter, code: `Key${letter.toUpperCase()}`, keyCode: letter.toUpperCase().charCodeAt(0), text: letter }
+  /* A capital is its own key event: the page reads `A` with shift held, and a
+     form inserts `A`, not `a`. */
+  KEYS[letter.toUpperCase()] = {
+    key: letter.toUpperCase(),
+    code: `Key${letter.toUpperCase()}`,
+    keyCode: letter.toUpperCase().charCodeAt(0),
+    text: letter.toUpperCase(),
+    shift: true,
+  }
+}
+for (const digit of '0123456789') {
+  KEYS[digit] = { key: digit, code: `Digit${digit}`, keyCode: digit.charCodeAt(0), text: digit }
+}
+
+/* The symbols above the digits and around the alphabet, both halves of every
+   key: a page reads `?` as Slash with shift down, and a field inserts `?`.
+   `keyCode` is the legacy VK number Windows and old pages compare against. */
+const PUNCTUATION = [
+  ['Backquote', '`', 192], ['Minus', '-', 189], ['Equal', '=', 187],
+  ['BracketLeft', '[', 219], ['BracketRight', ']', 221], ['Backslash', '\\', 220],
+  ['Semicolon', ';', 186], ['Quote', "'", 222], ['Comma', ',', 188],
+  ['Period', '.', 190], ['Slash', '/', 191],
+]
+const SHIFTED_SYMBOLS = [
+  ['~', 'Backquote', 192], ['!', 'Digit1', 49], ['@', 'Digit2', 50], ['#', 'Digit3', 51],
+  ['$', 'Digit4', 52], ['%', 'Digit5', 53], ['^', 'Digit6', 54], ['&', 'Digit7', 55],
+  ['*', 'Digit8', 56], ['(', 'Digit9', 57], [')', 'Digit0', 48], ['_', 'Minus', 189],
+  ['+', 'Equal', 187], ['{', 'BracketLeft', 219], ['}', 'BracketRight', 221], ['|', 'Backslash', 220],
+  [':', 'Semicolon', 186], ['"', 'Quote', 222], ['<', 'Comma', 188], ['>', 'Period', 190],
+  ['?', 'Slash', 191],
+]
+for (const [code, char, keyCode] of PUNCTUATION) {
+  KEYS[char] = { key: char, code, keyCode, text: char }
+}
+for (const [char, code, keyCode] of SHIFTED_SYMBOLS) {
+  KEYS[char] = { key: char, code, keyCode, text: char, shift: true }
+}
+
+/* Function keys, the numeric keypad a page can listen to, and the keys that do
+   nothing in a text field but everything in an app: a canvas game, a document
+   editor, a video player. */
+for (let n = 1; n <= 12; n += 1) {
+  KEYS[`F${n}`] = { key: `F${n}`, code: `F${n}`, keyCode: 111 + n }
+}
+for (const digit of '0123456789') {
+  KEYS[`Numpad${digit}`] = { key: digit, code: `Numpad${digit}`, keyCode: 96 + Number(digit), text: digit }
+}
+KEYS.NumpadAdd = { key: '+', code: 'NumpadAdd', keyCode: 107, text: '+' }
+KEYS.NumpadSubtract = { key: '-', code: 'NumpadSubtract', keyCode: 109, text: '-' }
+KEYS.NumpadMultiply = { key: '*', code: 'NumpadMultiply', keyCode: 106, text: '*' }
+KEYS.NumpadDivide = { key: '/', code: 'NumpadDivide', keyCode: 111, text: '/' }
+KEYS.NumpadDecimal = { key: '.', code: 'NumpadDecimal', keyCode: 110, text: '.' }
+
+/* The names people actually type, and the spelling a model guesses. */
+const KEY_ALIASES = {
+  esc: 'Escape', return: 'Enter', del: 'Delete', ins: 'Insert',
+  up: 'ArrowUp', down: 'ArrowDown', left: 'ArrowLeft', right: 'ArrowRight',
+  pageup: 'PageUp', pagedown: 'PageDown', spacebar: 'Space', space: 'Space',
+  menu: 'ContextMenu', prtsc: 'PrintScreen', printscreen: 'PrintScreen',
+}
+
+/**
+ * The event a browser would report for a named key.
+ * @param {string} name - a key in {@link KEYS}, or something close to one.
+ * @returns {{key: string, code: string, keyCode: number, text?: string, shift?: boolean}} the event fields.
+ * @throws {Error} when the key does not exist.
+ */
+export function keySpec(name) {
+  const raw = String(name ?? '')
+  const exact = KEYS[raw]
+  if (exact !== undefined) return exact
+  if (raw === ' ') return KEYS.Space
+  const alias = KEY_ALIASES[raw.toLowerCase()]
+  if (alias !== undefined) return KEYS[alias]
+  const capital = raw.charAt(0).toUpperCase() + raw.slice(1)
+  if (KEYS[capital] !== undefined) return KEYS[capital]
+  const fn = /^f([1-9]|1[0-2])$/i.exec(raw)
+  if (fn !== null) return KEYS[`F${fn[1]}`]
+  throw new Error(`sidecar: no such key ${raw}`) // ui-copy-ignore
+}
+
+/**
+ * Turn `Ctrl+Shift` into the CDP modifier bits. `Mod` is the platform's own
+ * command key: Command on macOS, Control on Windows and Linux — one spelling
+ * for the shortcut a page treats as copy, undo, select-all.
+ * @param {string} held - modifiers joined by +, any of Alt/Option, Ctrl/Control,
+ *   Meta/Cmd/Command/Super/Win, Shift, Mod.
+ * @param {string} [platform] - defaults to this process's platform.
+ * @returns {number} CDP modifier bits: Alt 1, Ctrl 2, Meta 4, Shift 8.
+ */
+export function modifierBits(held, platform = process.platform) {
+  let bits = 0
+  for (const raw of String(held ?? '').split('+')) {
+    const one = raw.trim().toLowerCase()
+    if (one === 'alt' || one === 'option' || one === 'opt' || one === '⌥') bits |= 1
+    else if (one === 'ctrl' || one === 'control' || one === '^') bits |= 2
+    else if (one === 'meta' || one === 'cmd' || one === 'command' || one === 'super' || one === 'win' || one === '⌘') bits |= 4
+    else if (one === 'shift' || one === '⇧') bits |= 8
+    else if (one === 'mod') bits |= platform === 'darwin' ? 4 : 2
+  }
+  return bits
+}
+
+/**
+ * Turn what the mirror's client posted into the event the page should see. A
+ * capital letter carries its shift, a shortcut becomes the browser command it
+ * names, and a release carries no text so the field does not type twice.
+ * @param {any} body - `{ key, code?, keyCode?, modifiers?, text?, down?, repeat? }`.
+ * @returns {{name: string, down: boolean, repeat: boolean, spec: any, command: string|null}} the event.
+ */
+export function keyEvent(body) {
+  const name = String(body?.key ?? '')
+  let known
+  try {
+    known = keySpec(name)
+  } catch {
+    known = null
+  }
+  const held = Number(body?.modifiers ?? 0)
+  const down = body?.down !== false
+  const repeat = body?.repeat === true
+  const capital = name.length === 1 && name !== name.toLowerCase()
+  const modifiers = capital ? held | 8 : held
+  const command = down === true && repeat === false ? commandOf(name, modifiers) : null
+  const text = command !== null ? undefined : body?.text === undefined ? known?.text : String(body.text)
+  return {
+    name,
+    down,
+    repeat,
+    spec: {
+      key: name,
+      code: String(body?.code ?? known?.code ?? name),
+      keyCode: Number(body?.keyCode ?? 0) || known?.keyCode || 0,
+      text,
+      modifiers,
+    },
+    command,
+  }
+}
+
+/**
+ * Read a chord the way a shortcut is written: `Ctrl+Shift+Tab` is the held
+ * modifiers Ctrl and Shift around one Tab, and `Mod+a` is Command+a on macOS.
+ * @param {string} chord - keys joined by +, modifiers may be in it.
+ * @param {number} [modifiers] - bits already held.
+ * @returns {{names: string[], modifiers: number}} the keys to press and the bits.
+ */
+export function splitChord(chord, modifiers = 0) {
+  const bits = { alt: 1, ctrl: 2, control: 2, meta: 4, cmd: 4, command: 4, super: 4, win: 4, shift: 8, option: 1, opt: 1, mod: process.platform === 'darwin' ? 4 : 2 }
+  const names = []
+  let held = modifiers
+  for (const raw of String(chord ?? '').split('+')) {
+    const one = raw.trim()
+    if (one === '') continue
+    const bit = bits[one.toLowerCase()]
+    if (bit === undefined) names.push(one)
+    else held |= bit
+  }
+  return { names, modifiers: held }
+}
+
+/**
+ * The editing command a browser runs for a shortcut, if any: copy and paste are
+ * commands, not key events, and a key event alone leaves the clipboard alone.
+ * @param {string} name - the key name.
+ * @param {number} modifiers - CDP modifier bits.
+ * @returns {string|null} a CDP command name, or null.
+ */
+export function commandOf(name, modifiers) {
+  /* Either command key counts: a page listens for the one its platform uses,
+     and the mirror can be driven from a machine with the other one. */
+  if ((modifiers & 6) === 0) return null
+  const one = String(name ?? '').toLowerCase()
+  if (one === 'v') return 'paste'
+  if (one === 'c') return 'copy'
+  if (one === 'x') return 'cut'
+  if (one === 'a') return 'selectAll'
+  if (one === 'z') return (modifiers & 8) !== 0 ? 'redo' : 'undo'
+  if (one === 'y') return 'redo'
+  return null
 }
 
 /**
@@ -195,14 +687,41 @@ export const KEYS = {
  * @param {number} [modifiers] - CDP modifier bits: Alt 1, Ctrl 2, Meta 4, Shift 8.
  * @returns {Promise<void>} done.
  */
-export async function pressKey(page, name, modifiers = 0) {
-  const key = KEYS[name] ?? KEYS[name.charAt(0).toUpperCase() + name.slice(1)]
-  if (key === undefined) throw new Error(`sidecar: no such key ${name}`) // ui-copy-ignore
-  const base = { key: key.key, code: key.code, windowsVirtualKeyCode: key.keyCode, nativeVirtualKeyCode: key.keyCode, modifiers }
-  await page.key('keyDown', key.text === undefined ? base : { ...base, text: key.text })
+export async function pressKey(page, name, modifiers = 0, holdMs = 0) {
+  const key = keySpec(name)
+  const withShift = (key.shift === true ? modifiers | 8 : modifiers)
+  const base = { key: key.key, code: key.code, windowsVirtualKeyCode: key.keyCode, nativeVirtualKeyCode: key.keyCode, modifiers: withShift }
+  /* Copy, paste, undo and select-all are editor commands: a key event alone
+     leaves the clipboard and the field where they were. */
+  const command = commandOf(key.text ?? key.key, withShift)
+  await page.key('keyDown', command === null
+    ? (key.text === undefined ? base : { ...base, text: key.text })
+    : { ...base, text: undefined, commands: [command] })
+  /* A key held down is how a game moves: down, wait, up — not a tap. */
+  if (holdMs > 0) await new Promise((settle) => setTimeout(settle, holdMs))
   await page.key('keyUp', base)
 }
 
+/**
+ * Press several keys at once and hold them: the diagonal a game expects, and a
+ * chord such as Shift+ArrowLeft. Releasing in reverse order is what a pair of
+ * hands does, and some engines only notice the last key that went up.
+ * @param {any} page - sidecar page.
+ * @param {string[]} names - key names, for example ['ArrowLeft', 'ArrowUp'].
+ * @param {number} [modifiers] - CDP modifier bits.
+ * @param {number} [holdMs] - how long every key stays down.
+ * @returns {Promise<void>} done.
+ */
+export async function pressChord(page, names, modifiers = 0, holdMs = 0) {
+  const keys = names.map((name) => {
+    const key = keySpec(name)
+    return { key, base: { key: key.key, code: key.code, windowsVirtualKeyCode: key.keyCode, nativeVirtualKeyCode: key.keyCode, modifiers: key.shift === true ? modifiers | 8 : modifiers } }
+  })
+  for (const one of keys) await page.key('keyDown', one.key.text === undefined ? one.base : { ...one.base, text: one.key.text })
+  if (holdMs > 0) await new Promise((settle) => setTimeout(settle, holdMs))
+  for (const one of [...keys].reverse()) await page.key('keyUp', one.base)
+}
+
 /**
  * Empty the field that has focus, whatever this machine calls select-all:
  * Command on macOS, Control elsewhere. A page can swallow the shortcut, so any
@@ -262,7 +781,7 @@ export function personNote(sidecar) {
 export function holdText(sidecar) {
   const left = Number(sidecar?.holding?.() ?? 0)
   if (left <= 0) return ''
-  return `the person is using the mirror (${String(Math.ceil(left / 1000))} s more) — nothing was sent. Let them finish, then repeat this call; sidecar_resume takes the page back now.`
+  return `the person is using the mirror (${String(Math.ceil(left / 1000))} s more) — nothing was sent. Let them finish, then repeat this call; browser_resume takes the page back now.`
 }
 
 /**
@@ -296,11 +815,15 @@ async function coverProbe(page, ref) {
  * @param {ReturnType<typeof coverProbe>} probe - what the page said is on top.
  * @returns {string} a sentence, or an empty string.
  */
-function coverNote(probe) {
+function coverNote(probe, moved) {
   if (probe === null || probe === undefined) return ''
   const what = probe.tag === 'div' || probe.tag === 'section' ? 'an overlay' : `a ${probe.tag}`
-  return `
-${what} covers it${probe.name === '' ? '' : `: ${probe.name}`} — the click landed beneath it`
+  const head = `
+${what} covers it${probe.name === '' ? '' : `: ${probe.name}`}`
+  /* A banner that is about to be cleared is not a warning: the line below it
+     already says what was clicked on the way, so do not claim the click will
+     land under something that is leaving. */
+  return moved ? head : `${head} — the click would land beneath it`
 }
 
 /**
@@ -315,14 +838,19 @@ ${what} covers it${probe.name === '' ? '' : `: ${probe.name}`} — the click lan
 async function clearCover(page, ref) {
   const probe = await coverProbe(page, ref)
   if (probe === null) return { note: '', cleared: true, name: '' }
-  const note = coverNote(probe)
+  const note = coverNote(probe, probe.dismiss !== null)
   const away = probe.dismiss
   if (away === null) return { note, cleared: false, name: '' }
   await page.mouse('mouseMoved', { x: away.x, y: away.y })
   await page.mouse('mousePressed', { x: away.x, y: away.y, clickCount: 1 })
   await page.mouse('mouseReleased', { x: away.x, y: away.y, clickCount: 1 })
-  await wait(150)
-  const again = await coverProbe(page, ref)
+  /* Prove the banner left instead of guessing a paint delay: poll the same
+     question the refusal would ask, and stop the moment it answers clear. */
+  let again = await coverProbe(page, ref)
+  for (let look = 0; look < 8 && again !== null; look += 1) {
+    await wait(20)
+    again = await coverProbe(page, ref)
+  }
   if (again !== null) return { note: `${note}
 - clicking ${away.name} on it did not clear it`, cleared: false, name: away.name } // ui-copy-ignore
   return { note: `${note}
@@ -352,12 +880,19 @@ function wait(ms) {
  * @param {{contextId?: number, sessionId?: string}|null} [route] - frame to run in.
  * @returns {Promise<any>} the value.
  */
-async function evaluate(page, expression, route) {
+async function evaluate(page, expression, route, raceMs = 2000) {
   const params = { expression, returnByValue: true, awaitPromise: true }
   if (route?.contextId !== undefined) params.contextId = route.contextId
+  /* A page that navigates mid-call destroys the context this ran in; the
+     rejection arrives after the race is already lost. Handled, so it cannot
+     take the whole process down with it. */
   const call = page.cdp.send('Runtime.evaluate', params, route?.sessionId)
-  const raced = await Promise.race([call, wait(2000).then(() => 'timeout')])
+    .catch((error) => ({ threw: String(error?.message ?? error) }))
+  let timer = null
+  const raced = await Promise.race([call, new Promise((done) => { timer = setTimeout(() => done('timeout'), raceMs) })])
+  clearTimeout(timer)
   if (raced === 'timeout') return undefined
+  if (raced?.threw !== undefined) return undefined
   const { result, exceptionDetails } = raced
   if (exceptionDetails !== undefined) {
     return { error: String(exceptionDetails.exception?.description ?? exceptionDetails.text ?? 'evaluate failed') }
@@ -365,6 +900,36 @@ async function evaluate(page, expression, route) {
   return result?.value
 }
 
+/**
+ * What the page looks like in one cheap string: address, title, how many
+ * elements and how much text. Two of these equal says the click did nothing
+ * visible — worth saying, so the model does not click a dead control twice.
+ * A Flash page has no DOM to ask, so its frame counter answers instead.
+ * @param {any} page - sidecar page.
+ * @returns {Promise<string>} a fingerprint, or '' when the page would not say.
+ */
+export async function pageMark(page) {
+  if (page?.flashBridge !== null && page?.flashBridge !== undefined) {
+    return `flash:${Number(page.seq ?? 0)}:${Number(page.lastFrameAt ?? 0)}`
+  }
+  const said = await evaluate(page, `(() => { const body = document.body; return String(document.title || '').slice(0, 80) + '|' + String(location.href).slice(0, 200) + '|' + (body ? body.innerText.length : 0) + '|' + document.querySelectorAll('*').length })()`).catch(() => undefined)
+  return typeof said === 'string' ? said : ''
+}
+
+/**
+ * The page's answer, as an object.
+ * @param {any} said - what evaluate returned.
+ * @returns {any} the answer, or null when the page did not answer.
+ */
+function asSpot(said) {
+  if (typeof said !== 'string') return null
+  try {
+    return JSON.parse(said)
+  } catch {
+    return null
+  }
+}
+
 /**
  * Wait until the page has settled: loading finished and the address stopped
  * changing. Acting on a page mid-navigation is how a driver clicks the old page.
@@ -372,21 +937,62 @@ async function evaluate(page, expression, route) {
  * @param {number} [timeout] - ceiling in milliseconds.
  * @returns {Promise<string>} the address it settled on.
  */
-export async function settle(page, timeout = 5000) {
+export async function settle(page, timeout = 5000, since = 0) {
+  /* A Flash page has no load events and no DOM of its own to poll: the next
+     picture is the only sign the click changed anything, and the bridge paints
+     every pump, so this ends at the frame instead of at the timeout. */
+  if (page.flashBridge !== null && page.flashBridge !== undefined) {
+    const until = Date.now() + Math.min(timeout, 700)
+    const before = Number(page.seq ?? 0)
+    while (Date.now() < until) {
+      if (Number(page.seq ?? 0) > before || Number(page.lastFrameAt ?? 0) > since) break
+      await new Promise((resolve) => setTimeout(resolve, 20))
+    }
+    return String(page.url ?? '')
+  }
   /* A click may have opened a tab. The mirror follows it, so every tool that
      waited on a page ends up on the page the person would be looking at. */
   const opened = typeof page.adoptOpened === 'function' ? await page.adoptOpened().catch(() => '') : ''
   const deadline = Date.now() + timeout
+  const started = Date.now()
   let last = ''
   let steady = 0
   while (Date.now() < deadline) {
     if (page.dialog !== null && page.dialog !== undefined) return String(page.url ?? '')
-    const state = await evaluate(page, '({ ready: document.readyState, href: location.href })')
-    const key = `${String(state?.ready)}|${String(state?.href)}`
+    /* The browser already said the load it began has finished. That is the same
+       answer a readyState poll gives, and it stays true while a page's own
+       scripts hold the main thread, which is exactly when the poll stalls. */
+    const began = Number(page.navStarted ?? 0)
+    const fired = Number(page.loadFired ?? 0)
+    /* Two event-only answers: nothing began loading since the action, or the
+       navigation this action started has already finished. Neither needs the
+       renderer, whose answer can take seconds on a page that is busy. */
+    if (since > 0 && began <= since) return String(page.url ?? '')
+    if (fired > 0 && fired >= began && (since === 0 || fired >= since)) return String(page.url ?? '')
+    /* A click opened a page whose own requests hang: the browser began loading
+       and nothing has finished since. A person presses Esc and uses what
+       arrived, and waiting the whole timeout only to give up helps no one. */
+    if (since > 0 && began > since && Date.now() - began > 900) {
+      await page.cdp.send('Page.stopLoading', {}).catch(() => {})
+      return String(page.url ?? '')
+    }
+    const state = await evaluate(page, '({ ready: document.readyState, href: location.href, n: document.getElementsByTagName("*").length, c: (document.body?.textContent ?? "").length })', null, 400)
+    /* Nothing began loading since the action, and the page is complete: the
+       click changed state without navigating, so there is nothing to wait for. */
+    if (since > 0 && state?.ready === 'complete' && Number(page.navStarted ?? 0) <= since) return String(state?.href ?? '')
+    const key = `${String(state?.ready)}|${String(state?.href)}|${String(state?.n)}|${String(state?.c)}`
     steady = key === last ? steady + 1 : 0
     last = key
+    /* A page that already says complete needs one steady poll, not two: the
+       second look is what a redirect needs, and a click usually has none. */
+    if (state?.ready === 'complete' && steady >= 1) return String(state?.href ?? '')
     if (state?.ready !== 'loading' && steady >= 2) return String(state?.href ?? '')
-    await wait(60)
+    /* A loaded page can change on the next paint; a loading one is either
+       navigating or about to be. Right after an action that is usually the
+       page the action opened, which lands in tens of milliseconds, so the
+       first quarter second is watched closely and only then slows down. */
+    const fresh = Date.now() - started < 250
+    await wait(state?.ready === 'complete' ? (fresh ? 12 : 25) : (fresh ? 12 : 60))
   }
   return ''
 }
@@ -416,7 +1022,29 @@ async function until(page, expression, timeout) {
  * @returns {Promise<string>} a compact report.
  */
 /** The first control whose words match, scrolled into view. Text can beat a number: it costs no read. */
-async function findWords(page, words) {
+export async function findWords(page, words, known) {
+  /* The words a caller used usually came from a read that already happened, so
+     look among those numbers first: one position check is a single evaluate,
+     while a fresh read walks the whole page. A number the page no longer has
+     falls through to the read, so a redraw is not a missed click. */
+  const squeezeOf = (text) => String(text).toLowerCase().replace(/\s+/g, '')
+  const wantedFirst = squeezeOf(words)
+  const remembered = Array.isArray(known) ? known.filter((control) => control.view !== false && squeezeOf(control.name ?? '').includes(wantedFirst)) : []
+  remembered.sort((a, b) => Number(squeezeOf(a.name ?? '') === wantedFirst) - Number(squeezeOf(b.name ?? '') === wantedFirst))
+  /* A page that repeats one word down a list ("Add to cart" on every card) has
+     one obvious answer: the first one a person would reach. The last-first
+     order that keeps a scrolled page fast also picked whichever duplicate sat
+     lowest, so visible matches are tried in reading order first and the near
+     end is only the fallback. */
+  const firstInOrder = remembered.filter((control) => control.view !== false).sort((a, b) => Number(a.ref) - Number(b.ref))
+  const nearEnd = remembered.slice(-8).reverse()
+  for (const control of [...firstInOrder.slice(0, 4), ...nearEnd]) {
+    const spot = await locate(page, Number(control.ref))
+    if (spot.gone === true) continue
+    const name = String(spot.name ?? control.name ?? '')
+    if (!squeezeOf(name).includes(wantedFirst)) continue
+    return { ...control, ref: Number(control.ref), name, x: Number(spot.x), y: Number(spot.y) }
+  }
   const read = await readPage(page, { mode: 'text', maxChars: 1200, max: 200 })
   const shown = read.controls.filter((control) => control.view !== false)
   /* The words may sit in separate inline nodes: <span>Sign</span><span>in</span>
@@ -454,21 +1082,90 @@ async function fieldSpot(page, words) {
  * Where the field called these words is, clearing a banner over it first.
  * @param {any} page - sidecar page.
  * @param {string} words - what the field is called on screen.
- * @returns {Promise<{x: number, y: number, name: string, lead: string}|null>} the click.
+ * @returns {Promise<{x: number, y: number, name: string, lead: string, ref?: number}|null>} the click.
  */
-async function fieldByName(page, words) {
-  const hit = await findWords(page, words)
+async function fieldByName(page, words, known) {
+  const hit = await findWords(page, words, known)
   const lead = hit === null ? '' : await coverLead(page, hit.ref)
   if (hit !== null && EDITABLE_KINDS.includes(String(hit.kind))) {
     const spot = await locate(page, hit.ref)
-    if (spot.gone !== true) return { x: Number(spot.x), y: Number(spot.y), name: String(hit.name), lead }
+    if (spot.gone !== true) return { x: Number(spot.x), y: Number(spot.y), name: String(hit.name), lead, ref: Number(hit.ref) }
   }
   const field = await fieldSpot(page, words)
   if (field !== null) return { ...field, lead }
   if (hit === null) return null
   const spot = await locate(page, hit.ref)
   if (spot.gone === true) return null
-  return { x: Number(spot.x), y: Number(spot.y), name: String(hit.name), lead }
+  return { x: Number(spot.x), y: Number(spot.y), name: String(hit.name), lead, ref: Number(hit.ref) }
+}
+
+/**
+ * A date-like field ignores human typing: Chrome's date input wants its own
+ * segments, so keystrokes leave the value empty while the call reports success.
+ * Set it the way a form would, and say the value the page now holds.
+ * @param {any} page - sidecar page.
+ * @param {string} text - what the caller wanted in it.
+ * @returns {Promise<string>} a clause about the field, or '' when it is not one.
+ */
+/* The input kinds a person cannot type into: Chrome gives each of them its own
+   segment editor, and keys typed at it leave the value empty. */
+const DATE_KINDS = ['date', 'time', 'month', 'week', 'datetime-local']
+
+/**
+ * The date-like kind the focus is on, if it is on one.
+ * @param {any} page - sidecar page.
+ * @returns {Promise<string>} date, time… or '' when it is an ordinary field.
+ */
+async function dateLikeFocus(page) {
+  const said = await evaluate(page, `(() => {
+    const el = document.activeElement
+    if (!el || String(el.tagName).toUpperCase() !== 'INPUT') return ''
+    const kind = String(el.type)
+    if (!${JSON.stringify(DATE_KINDS)}.includes(kind)) return ''
+    if (String(el.value) !== '') return ''
+    return JSON.stringify({ kind })
+  })()`).catch(() => undefined)
+  return String(asSpot(said)?.kind ?? '')
+}
+
+async function fillDateLike(page, text) {
+  const kind = await dateLikeFocus(page)
+  if (kind === '') return ''
+  const empty = { kind }
+  const want = String(text).trim()
+  const after = await evaluate(page, `(() => {
+    const el = document.activeElement
+    const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set
+    setter.call(el, ${JSON.stringify(want)})
+    el.dispatchEvent(new Event('input', { bubbles: true }))
+    el.dispatchEvent(new Event('change', { bubbles: true }))
+    return String(el.value)
+  })()`).catch(() => undefined)
+  if (typeof after !== 'string' || after === '') {
+    return `that ${empty.kind} field would not take "${want}" — it wants ${empty.kind === 'time' ? '09:30' : '2026-03-04'}`
+  }
+  return `set ${after} in the ${empty.kind} field`
+}
+
+/**
+ * Put text in the focused box the cheapest way that still works there.
+ * A box that reacts while you type (suggestion lists, live search) needs the
+ * keys in order; anything else takes one paste event, and the box itself is
+ * the judge of whether it took it.
+ * @param {any} page - sidecar page.
+ * @param {string} text - what to type.
+ * @param {string} [hint] - the field's name, to spot a live-search box.
+ * @returns {Promise<void>} resolves when the box holds the text.
+ */
+export async function typeInto(page, text, hint = '') {
+  const words = String(text)
+  if (words === '') return
+  const live = /search|query|lookup|filter|搜索|筛选|查询/i.test(hint)
+  if (!live && (await page.quickType(words)) === true) {
+    await wait(30)
+    return
+  }
+  await page.humanType(words)
 }
 
 /**
@@ -479,13 +1176,31 @@ async function fieldByName(page, words) {
  * @param {{clear?: boolean, submit?: boolean}} options - how.
  */
 async function writeAt(page, point, text, options = {}) {
+  /* Approach the control the way a hand does: a couple of small moves that
+     land in different places, not a teleport followed by a click. */
+  const drift = (by) => ({ x: point.x + by, y: point.y + Math.round(by / 2) })
+  /* The shape of the approach is what a page can see; the gaps between its
+     points only buy latency. Three moves stay, the pauses are frames. */
+  await page.mouse('mouseMoved', drift(-14 - Math.round(Math.random() * 10)))
+  await wait(5 + Math.round(Math.random() * 8))
+  await page.mouse('mouseMoved', drift(-4 - Math.round(Math.random() * 4)))
+  await wait(4 + Math.round(Math.random() * 6))
   await page.mouse('mouseMoved', point)
+  await wait(5 + Math.round(Math.random() * 8))
   await page.mouse('mousePressed', { ...point, clickCount: 1 })
+  await wait(5 + Math.round(Math.random() * 9))
   await page.mouse('mouseReleased', { ...point, clickCount: 1 })
-  await wait(80)
+  await wait(14 + Math.round(Math.random() * 18))
   if (options.clear === true) await clearFocus(page)
-  await page.insertText(text)
+  /* A date or time input never takes keystrokes: noticing that before typing
+     spends one round trip instead of fourteen keys and a failed readback. */
+  if (await dateLikeFocus(page) !== '') return await fillDateLike(page, text)
+  if (options.human === false) await page.insertText(text)
+  else await typeInto(page, text, String(options.hint ?? ''))
+  const fixed = await fillDateLike(page, text)
+  if (fixed !== '') return fixed
   if (options.submit === true) await pressKey(page, 'Enter')
+  return ''
 }
 
 /**
@@ -498,8 +1213,11 @@ async function writeAt(page, point, text, options = {}) {
  */
 async function followRef(page, ref, known) {
   const spot = await locate(page, ref)
-  if (spot.gone !== true) return spot
   const was = Array.isArray(known) ? known.find((control) => Number(control.ref) === Number(ref)) : undefined
+  if (spot.gone !== true) {
+    const drift = differs(was, spot)
+    return drift === '' ? spot : { gone: true, why: drift }
+  }
   if (was === undefined) return spot
   const want = identityOf(was)
   if (want.name === '') return spot
@@ -512,12 +1230,40 @@ async function followRef(page, ref, known) {
   return { ...next, followed: true, was: want.name }
 }
 
+/**
+ * One read state per chat, created the first time that chat reads.
+ * @param {Map<string, any>} store - per-chat states.
+ * @param {string} id - chat id.
+ * @param {any} fallback - state for calls that name no chat.
+ * @returns {any} the state of that chat.
+ */
+export function readStateFor(store, id, fallback) {
+  const key = String(id ?? '')
+  const known = store.get(key)
+  if (known !== undefined) return known
+  /* The one object the plugin was started with belongs to calls that name no
+     chat, so a chat that does name itself gets an empty one of its own. */
+  const fresh = key === '' ? fallback : { refs: [], at: 0 }
+  store.set(key, fresh)
+  return fresh
+}
+
+/**
+ * A step that could not be carried out. The batch stops here: the next step was
+ * written against a page that never arrived.
+ * @param {string} text - what happened.
+ * @returns {{text: string, blocked: boolean}} the step result.
+ */
+function stuck(text) {
+  return { text, blocked: true }
+}
+
 async function runStep(page, step, known) {
   if (step.ref !== undefined) {
     if (step.tap !== undefined || step.text !== undefined) {
       const lead = await coverLead(page, Number(step.ref))
       const spot = await followRef(page, Number(step.ref), known)
-      if (spot.gone === true) return `ref ${String(step.ref)}: ${REF_GONE}`
+      if (spot.gone === true) return stuck(`ref ${String(step.ref)}: ${REF_GONE}`)
       const after = spot.followed === true ? ` (it was redrawn under a new number, used where it is now)` : ''
       const point = { x: Number(spot.x), y: Number(spot.y) }
       await page.mouse('mouseMoved', point)
@@ -526,17 +1272,17 @@ async function runStep(page, step, known) {
       if (step.tap !== undefined) return `${lead}clicked ${String(step.ref)} ${String(spot.name ?? '')}`.trim() + after
       await wait(80)
       if (step.clear === true) await clearFocus(page)
-      await page.insertText(String(step.text))
+      await page.humanType(String(step.text))
       if (step.submit === true) await pressKey(page, 'Enter')
       return `${lead}typed into ${String(step.ref)} ${String(spot.name ?? '')}`.trim() + after
     }
   }
   if (step.tap !== undefined && !/^\s*-?\d+(?:\.\d+)?\s*,\s*-?\d+(?:\.\d+)?\s*$/.test(String(step.tap))) {
-    const hit = await findWords(page, String(step.tap))
-    if (hit === null) return `no control says ${JSON.stringify(String(step.tap))}`
+    const hit = await findWords(page, String(step.tap), known)
+    if (hit === null) return stuck(`no control says ${JSON.stringify(String(step.tap))}`)
     const lead = await coverLead(page, hit.ref)
     const spot = await locate(page, hit.ref)
-    if (spot.gone === true) return `ref ${String(hit.ref)}: ${REF_GONE}`
+    if (spot.gone === true) return stuck(`ref ${String(hit.ref)}: ${REF_GONE}`)
     const point = { x: Number(spot.x), y: Number(spot.y) }
     await page.mouse('mouseMoved', point)
     await page.mouse('mousePressed', { ...point, clickCount: 1 })
@@ -546,9 +1292,10 @@ async function runStep(page, step, known) {
   if (step.field !== undefined) {
     /* The words may sit on the field or in a div above a bare input. Only a
        click that lands on the field itself can be trusted with the typing. */
-    const target = await fieldByName(page, String(step.field))
-    if (target === null) return `${String(step.field)}: ${REF_GONE}`
-    await writeAt(page, { x: target.x, y: target.y }, String(step.text ?? ''), { clear: step.clear, submit: step.submit })
+    const target = await fieldByName(page, String(step.field), known)
+    if (target === null) return stuck(`${String(step.field)}: ${REF_GONE}`)
+    const dated = await writeAt(page, { x: target.x, y: target.y }, String(step.text ?? ''), { clear: step.clear, submit: step.submit })
+    if (dated !== '') return dated
     return `${target.lead}typed into "${target.name.slice(0, 60)}"`
   }
   if (step.tap !== undefined) {
@@ -561,7 +1308,7 @@ async function runStep(page, step, known) {
   }
   if (step.text !== undefined) {
     if (step.clear === true) await clearFocus(page)
-    await page.insertText(String(step.text))
+    await page.humanType(String(step.text))
     if (step.submit === true) await pressKey(page, 'Enter')
     return `typed ${String(step.text).slice(0, 60)}`
   }
@@ -577,17 +1324,17 @@ async function runStep(page, step, known) {
   if (step.wait_text !== undefined) {
     const needle = JSON.stringify(String(step.wait_text))
     const ok = await until(page, `document.body ? document.body.innerText.includes(${needle}) : false`, Number(step.timeout ?? 8000))
-    return ok ? `saw ${String(step.wait_text)}` : `did not see ${String(step.wait_text)}`
+    return ok ? `saw ${String(step.wait_text)}` : stuck(`did not see ${String(step.wait_text)}`)
   }
   if (step.wait_gone !== undefined) {
     const needle = JSON.stringify(String(step.wait_gone))
     const ok = await until(page, `document.body ? !document.body.innerText.includes(${needle}) : true`, Number(step.timeout ?? 8000))
-    return ok ? `${String(step.wait_gone)} went away` : `${String(step.wait_gone)} stayed`
+    return ok ? `${String(step.wait_gone)} went away` : stuck(`${String(step.wait_gone)} stayed`)
   }
   if (step.wait_url !== undefined) {
     const needle = JSON.stringify(String(step.wait_url))
     const ok = await until(page, `location.href.includes(${needle})`, Number(step.timeout ?? 8000))
-    return ok ? `at ${String(step.wait_url)}` : `still at a different address`
+    return ok ? `at ${String(step.wait_url)}` : stuck(`still at a different address`)
   }
   if (step.open !== undefined) {
     const landed = await page.navigate(String(step.open))
@@ -617,13 +1364,85 @@ async function runStep(page, step, known) {
  * @param {{mode?: string, maxChars?: number}} options - narrowing.
  * @returns {Promise<any>} the read.
  */
+/** A read with nothing in it often means the document is still being built:
+ * samples of real pages showed zero controls when the read landed before
+ * hydration, and the model then calls the page broken. */
+function looksEmpty(read) {
+  return (read?.controls?.length ?? 0) === 0 && String(read?.text ?? '').trim().length < 40
+}
+
+/** @param {string} url - what the page claims to be. @returns {boolean} true when waiting can still help. */
+function canFill(url) {
+  const said = String(url ?? '')
+  return said.startsWith('http://') || said.startsWith('https://')
+}
+
 async function remember(page, refs, options) {
-  const read = await readPage(page, options)
+  let read = await readPage(page, options)
+  if (looksEmpty(read) && canFill(read.url)) {
+    /* Hydration and client-side rendering finish a few hundred milliseconds
+       after the address does. Read again until the page has something, but
+       never longer than a person would wait for a page that stays empty. */
+    const deadline = Date.now() + 1500
+    while (looksEmpty(read) && canFill(read.url) && Date.now() < deadline) {
+      await wait(120)
+      const again = await readPage(page, options)
+      if (!looksEmpty(again)) {
+        read = again
+        break
+      }
+      read = again
+    }
+  }
   refs.refs = read.controls
   refs.at = Date.now()
   return read
 }
 
+/**
+ * Two reads of the same page in the same shape say the same thing. Saying it
+ * again costs tokens and teaches nothing, so the second read can be one line.
+ * @param {any} before - the earlier read.
+ * @param {any} after - the read now.
+ * @returns {boolean} true when nothing a read would show has changed.
+ */
+export function sameRead(before, after) {
+  if (before === undefined || before === null || after === undefined || after === null) return false
+  if (before.url !== after.url || before.title !== after.title) return false
+  if (before.text !== after.text) return false
+  if (JSON.stringify(before.controls) !== JSON.stringify(after.controls)) return false
+  if ((before.focused?.ref ?? null) !== (after.focused?.ref ?? null)) return false
+  return true
+}
+
+/**
+ * Where two readings of a page differ, said in one line. A counter moving, one
+ * row appearing, a word edited: the page is mostly the same, and sending all of
+ * it again is what makes a long session expensive.
+ * @param {string} before - the text earlier.
+ * @param {string} after - the text now.
+ * @returns {string} a short line, or '' when the two have nothing in common.
+ */
+export function textChange(before, after) {
+  const was = String(before ?? '')
+  const now = String(after ?? '')
+  let head = 0
+  const shortest = Math.min(was.length, now.length)
+  while (head < shortest && was[head] === now[head]) head += 1
+  let tail = 0
+  while (tail < shortest - head && was[was.length - 1 - tail] === now[now.length - 1 - tail]) tail += 1
+  const gone = was.slice(head, was.length - tail)
+  const came = now.slice(head, now.length - tail)
+  /* A page that changed in one place is worth a line; one that shares almost no
+     text is a different page, and a diff of it would be as long as the page. */
+  if (head + tail < 12) return ''
+  const clip = (text) => (text.length > 160 ? `${text.slice(0, 157)}…` : text)
+  const near = clip(was.slice(Math.max(0, head - 24), head))
+  const far = clip(now.slice(now.length - tail, now.length - tail + 24))
+  const line = `${near === '' ? '' : `…${near} `}${gone === '' ? '' : `[${clip(gone)}] `}→ ${came === '' ? '' : `[${clip(came)}] `}${far === '' ? '' : `${far}…`}`
+  return line.trim()
+}
+
 /**
  * Say only what changed since the previous read.
  * @param {any} previous - the read before.
@@ -635,8 +1454,7 @@ export function diffRead(previous, next, options = {}) {
   const maxChars = Number(options.maxChars ?? 2000)
   const before = new Map(previous.controls.map((control) => [control.ref, control]))
   const after = new Map(next.controls.map((control) => [control.ref, control]))
-  const lines = [next.url]
-  if (previous.url !== next.url) lines.push(`address changed to ${next.url}`)
+  const lines = [previous.url === next.url ? next.url : `address ${next.url}`]
   const added = next.controls.filter((control) => !before.has(control.ref))
   const removed = previous.controls.filter((control) => !after.has(control.ref))
   const changed = next.controls.filter((control) => {
@@ -652,9 +1470,14 @@ export function diffRead(previous, next, options = {}) {
   }
   if (added.length + removed.length + changed.length === 0) lines.push('no control changed')
   if (previous.text !== next.text) {
-    const head = next.text.slice(0, Math.max(200, Math.min(1200, maxChars - 800)))
-    lines.push('', 'text now:', head)
-    if (next.text.length > head.length) lines.push(`… ${next.text.length - head.length} more characters`)
+    const said = textChange(previous.text, next.text)
+    const room = Math.max(200, Math.min(1200, maxChars - 200))
+    if (said !== '') lines.push(`text: ${said}`)
+    else {
+      const head = next.text.slice(0, room)
+      lines.push('', 'text now:', head)
+      if (next.text.length > head.length) lines.push(`… ${next.text.length - head.length} more characters`)
+    }
   }
   if (next.focused !== null && previous.focused?.ref !== next.focused.ref) lines.push(`focus ${next.focused.ref} ${next.focused.name}`)
   return lines.join('\n')
@@ -709,7 +1532,7 @@ export async function extractRows(page, args) {
   const out = await page.cdp.send('Runtime.evaluate', { expression, returnByValue: true }).catch((error) => ({ error: String(error?.message ?? error) }))
   if (out?.error !== undefined && out.error !== null && typeof out.error === 'string') return `the page did not answer: ${out.error}`
   const value = out?.result?.value
-  if (value === undefined || value === null || value === '') return 'the page did not answer; try again, or read the page with sidecar_view.'
+  if (value === undefined || value === null || value === '') return 'the page did not answer; try again, or read the page with browser_view.'
   if (value.gone === true) return `ref ${ref} is gone. Read the page again and use a new number.`
   if (value.bad === true) return `${select} is not a selector this browser understands.`
   const rows = Array.isArray(value.rows) ? value.rows : []
@@ -719,7 +1542,140 @@ export async function extractRows(page, args) {
   return `${rows.length} of ${Number(value.total)} rows matching ${select}:\n${said.join('\n')}${more}`
 }
 
+/**
+ * Say one thing to a box in the page and take the answer back. The wait ends
+ * when the answer has stopped changing, so a streaming reply is not cut off and
+ * a page that never answers does not hold the call open forever.
+ * @param {any} page - sidecar page.
+ * @param {{text?: string, ref?: number, submit?: boolean, timeout_ms?: number}} args - what to say.
+ * @returns {Promise<string>} the answer, or why there is none.
+ */
+/**
+ * Whether a box on the page still holds the words that were typed.
+ * A box that keeps them never sent them, which is what a signed-out page does.
+ * @param {any} page - sidecar page.
+ * @param {string} words - what was typed.
+ * @returns {Promise<boolean>} true when the words are still in a box.
+ */
+async function boxHolds(page, words) {
+  const wanted = String(words).slice(0, 24)
+  if (wanted === '') return false
+  const held = await evaluate(page, `(() => {
+  const wanted = ${JSON.stringify(wanted)}
+  for (const el of document.querySelectorAll('textarea, [contenteditable=""], [contenteditable="true"], input[type="text"], input[type="search"], input:not([type])')) {
+    if (String(el.value ?? el.innerText ?? '').trim().includes(wanted)) return true
+  }
+  return false
+})()`)
+  return held === true
+}
+
+/**
+ * Sends a line to whatever chat the page holds and waits for the answer to stop
+ * growing. The ref is followed the same way a click follows it, so a reply box
+ * that was redrawn since the read still gets the text.
+ * @param {any} page - sidecar page.
+ * @param {any} args - text, optional ref, optional timeout.
+ * @returns {Promise<string>} the answer.
+ */
+export async function askInPage(page, args) {
+const said = String(args?.text ?? '').trim()
+if (said === '') return 'Give me something to say.'
+const budget = Math.max(3000, Math.min(180_000, Math.trunc(Number(args?.timeout_ms ?? 60_000)) || 60_000))
+const before = await readPage(page, { mode: 'text', maxChars: 4000 })
+let point = null
+if (args?.ref !== undefined) {
+  const spot = await followRef(page, Number(args.ref))
+  if (spot.gone === true) return spot.why ?? REF_GONE
+  point = { x: Number(spot.x), y: Number(spot.y) }
+} else {
+  const at = await evaluate(page, `(() => {
+    let best = null
+    for (const el of document.querySelectorAll('textarea, [contenteditable=""], [contenteditable="true"], input[type="text"], input[type="search"], input:not([type])')) {
+      const b = el.getBoundingClientRect()
+      const s = getComputedStyle(el)
+      if (s.visibility === 'hidden' || s.display === 'none' || b.width < 80 || b.height < 18) continue
+      if (b.bottom < 0 || b.top > innerHeight) continue
+      if (best === null || b.width * b.height > best.area) best = { area: b.width * b.height, x: b.x + Math.min(24, b.width / 2), y: b.y + b.height / 2, name: String(el.getAttribute('placeholder') ?? el.getAttribute('aria-label') ?? '').slice(0, 40) }
+    }
+    return best === null ? null : { x: Math.round(best.x), y: Math.round(best.y), name: best.name }
+  })()`)
+  if (at === null || at === undefined) return 'No box to type in on this page. Call browser_view to see what is there.'
+  point = { x: Number(at.x), y: Number(at.y) }
+}
+await page.mouse('mouseMoved', point)
+await page.mouse('mousePressed', { ...point, clickCount: 1 })
+await page.mouse('mouseReleased', { ...point, clickCount: 1 })
+await wait(60)
+await page.humanType(said)
+if (args?.submit !== false) await pressKey(page, 'Enter')
+await wait(500)
+if (args?.submit !== false && (await boxHolds(page, said))) {
+  return `the words are still in the box 0.5s after pressing Enter: the page did not take the message. If it is waiting for a sign-in, sign in in the column, then ask again.`
+}
+const started = Date.now()
+const deadline = started + budget
+let last = before.text
+let fresh = ''
+let steady = 0
+let quiet = 0
+while (Date.now() < deadline) {
+  await wait(500)
+  const now = await readPage(page, { mode: 'text', maxChars: 4000 })
+  if (now.text !== last) {
+    last = now.text
+    fresh = now.text
+    steady = 0
+    quiet = 0
+    continue
+  }
+  if (fresh !== '') {
+    steady += 1
+    if (steady >= 3) break
+  } else {
+    quiet += 1
+    if (quiet >= 4 && Date.now() - started > 4000) break
+  }
+}
+const took = Date.now() - started
+/* A page that shows neither the words in a box nor the message itself never
+   took it: the chips moved, the menu redrew, and none of that is an answer. */
+const echo = String(said.slice(0, 24))
+if (fresh !== '' && echo.length >= 8 && !fresh.includes(echo)) {
+  const asking = /(sign in|log in|登录|注册)/i.test(fresh)
+  return `the page changed but does not show the message: it did not take what was sent.${asking ? ' It is asking for a sign-in — sign in in the column, then ask again.' : ' Try browser_view to see what is in the way.'}`
+}
+/* A box that still holds the words is the page saying it did not take them:
+   a signed-out page leaves them there, and the old wording sent the reader
+   looking for an answer that was never asked for. */
+const stuck = fresh === '' && (await boxHolds(page, said))
+if (fresh === '') {
+  if (stuck) return `sent it — no answer after ${Math.round(took / 100) / 10}s, and the words are still in the box: the page did not take the message. If it is waiting for a sign-in, sign in in the column, then ask again.`
+  return `sent it — no answer after ${Math.round(took / 100) / 10}s; the page still says: ${before.text.slice(0, 400)}`
+}
+/* The answer may replace the words that were there, so cut at the last
+   character the two reads share, not at the old length. */
+let shared = 0
+while (shared < fresh.length && shared < before.text.length && fresh[shared] === before.text[shared]) shared += 1
+const added = fresh.slice(shared)
+/* Lines are kept: a reviewer's list is one point per line, and flattening it
+   would leave the next round with a paragraph instead of items. */
+const words = added.replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim().slice(0, 2500)
+return `the answer came back in ${Math.round(took / 100) / 10}s:\n${words}`
+}
+
 export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
+  /* A ref belongs to the page it was read from, and two chats read two pages.
+     One shared read state meant chat B's read replaced chat A's baseline, so A's
+     next "what changed" was a diff against a page it never saw and a number from
+     A could be matched against B's control. Each chat now keeps its own. */
+  const byChat = new Map()
+  /**
+   * The read state of the chat this call speaks for.
+   * @param {string} [id] - chat id; the current one by default.
+   * @returns {{refs: any[], at: number, last?: any, lastShape?: string}} its state.
+   */
+  const refsFor = (id = currentSession()) => readStateFor(byChat, id, refs)
   /* Reading, clicking and typing on Chrome's own error page is not driving the
      site: the text there is Chrome talking, the buttons reload. Those calls are
      refused with the error code instead. The tools that report the browser
@@ -727,18 +1683,46 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
      run, because they are how a stuck person finds out what happened. */
   const withRawPage = async (work) => {
     if (!sidecar.alive) return { text: SIDECAR_OFF }
-    const page = await sidecar.ensure()
+    const page = await sidecar.ensure({ session: currentSession() })
     const text = await work(page)
     return { text: text + personNote(sidecar) }
   }
   /** Looking is still useful while the person has the page. */
   const withRead = async (work) => {
-    if (!sidecar.alive) return { text: SIDECAR_OFF }
-    const page = await sidecar.ensure()
+    /* A call starting means the last click is over: a tab that opens now is not
+       going to be followed under this call's feet. */
+    try {
+      sidecar.page?.disarmFollow?.()
+    } catch {
+      /* the page is already gone */
+    }
+    /* A plugin reload makes a new driver while the browser it started keeps
+       running. Refusing every read until someone opens a page again would throw
+       away a browser that is still there: attach to it instead. */
+    if (!sidecar.alive) {
+      /* A renderer crash can take the whole browser with it, and the first
+         relaunch sometimes loses the race with the old process exiting. One
+         more try turns that into a fresh tab instead of a refusal. */
+      try {
+        await sidecar.ensure({ session: currentSession() })
+      } catch {
+        await wait(300)
+        try {
+          await sidecar.ensure({ session: currentSession() })
+        } catch {
+          return { text: SIDECAR_OFF }
+        }
+      }
+    }
+    const page = await sidecar.ensure({ session: currentSession() })
     const dead = await unreachable(page)
     if (dead !== '') return { text: dead + personNote(sidecar) }
     const text = await work(page)
-    return { text: text + personNote(sidecar) }
+    /* Why a page stopped working is usually in its own log, and looking it up
+       costs another call. This is the one place every read passes through, so
+       say what went wrong since the previous one, once. */
+    const trouble = typeof page.troubleOf === 'function' ? page.troubleOf() : ''
+    return { text: text + (trouble === '' ? '' : `\n${trouble}`) + personNote(sidecar) }
   }
   const withPage = async (work) => {
     if (!sidecar.alive) return { text: SIDECAR_OFF }
@@ -747,7 +1731,9 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
     return withRead(work)
   }
   const look = async (page, options) => {
-    const read = await remember(page, refs, options)
+    const read = await remember(page, refsFor(), options)
+    /* A read already showed the address: the next action does not repeat it. */
+    if (String(read.url ?? '') !== '') saidUrls.set(page, String(read.url))
     const said = renderPage(read, options)
     return isCheckPage(read) ? `${said}\n${CHECK_NOTE}` : said
   }
@@ -768,8 +1754,11 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
    */
   const findAgain = async (page, ref) => {
     const spot = await locate(page, ref)
-    if (spot.gone !== true) return spot
-    const known = (refs?.refs ?? []).find((control) => Number(control.ref) === Number(ref))
+    const known = (refsFor().refs ?? []).find((control) => Number(control.ref) === Number(ref))
+    if (spot.gone !== true) {
+      const drift = differs(known, spot)
+      return drift === '' ? spot : { gone: true, why: drift }
+    }
     if (known === undefined) return spot
     const want = identityOf(known)
     if (want.name === '') return spot
@@ -786,13 +1775,17 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
 
   return [
     {
-      name: 'sidecar_open', // ui-copy-ignore
-      description: 'Start (or reuse) the sidecar browser — a real Chrome with its own persistent profile — and open a URL in it. It runs in the background and its screen appears in this chat\'s sidebar tab, so it keeps working while the person looks elsewhere. Logins survive restarts.',
+      name: 'browser_open', // ui-copy-ignore
+      description: 'Start (or reuse) the background browser — a real Chrome with its own persistent profile — and open a URL in it. It is not the host\'s own browser tab: this Chrome runs on its own and only its picture is mirrored into this chat\'s right column, so it keeps working while the person looks elsewhere. Logins survive restarts.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
           url: { type: 'string', description: 'Address to open. Omit to reuse the current page.' },
           headless: { type: 'boolean', description: 'Run without a window. Default true; turn off only if a site refuses a windowless browser.' },
+          flash: {
+            type: 'boolean',
+            description: 'Play the page in the Flash-era browser instead of Chrome — for a site whose game is a Flash movie that never got an HTML5 version. Default off; switching either way restarts the browser.',
+          },
         },
         additionalProperties: false,
       },
@@ -801,33 +1794,270 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       isConcurrencySafe: () => false,
       /** @param {any} args - arguments. @param {any} exec - tool run. @returns {Promise<{text: string}>} what the page is. */
       execute: async (args, exec) => {
-        const page = await sidecar.ensure({ url: args?.url, headless: args?.headless })
+        const who = String(exec?.agent?.id ?? '')
+        const page = await sidecar.ensure({ url: args?.url, headless: args?.headless, flash: args?.flash, session: who })
         if (args?.url === undefined) await page.readTitle()
         /* A window on the person's screen is their business, not a surprise: say
            it, so nobody wonders what popped up. A site that refuses a windowless
            browser is the only reason this happens. */
-        const windowed = sidecar.headless === false ? 'The browser is showing a window this time — a site only opens for a windowed one. Same profile, same logins.\n' : ''
+        /* The Flash runtime is windowless even when headless is false: its window
+           is never shown, so nothing popped up to explain. */
+        const windowed = sidecar.headless === false && sidecar.flash !== true ? 'The browser is showing a window this time — a site only opens for a windowed one. Same profile, same logins.\n' : ''
         /* The tab appears in the calling chat and nowhere else: the person may
            be reading a different chat, and a browser there would be a surprise. */
-        const who = String(exec?.agent?.id ?? '')
         if (who !== '') host.want?.(who) // ui-copy-ignore
         await settle(page, 8000)
         const dead = await unreachable(page)
         if (dead !== '') return { text: dead }
         /* The column may still be drawing nothing: say so here, where the
-           person is looking for a picture, rather than only in sidecar_state. */
+           person is looking for a picture, rather than only in browser_state. */
         const unseen = who === '' ? '' : viewerNote(await watchForViewer(sidecar, page, 1200))
-        return { text: windowed + (unseen === '' ? '' : `${unseen}\n`) + await look(page, { mode: 'text' }) }
+        return { text: windowed + (unseen === '' ? '' : `${unseen}\n`) + await look(page, { mode: 'text' }) + (await pdfNote(page)) }
+      },
+    },
+    {
+      name: 'browser_mode', // ui-copy-ignore
+      description: 'Choose how this chat acts from now on. "human" moves the real mouse and presses real keys, which no page can tell from a person — games and pages that watch pointer movement need this. "dom" clicks and fills the controls the page registered, which reaches one that an overlay covers and leaves key handlers alone. A call can also pass its own mode, which wins for that call only.',
+      parameters: {
+        type: 'object', // ui-copy-ignore
+        properties: {
+          mode: { type: 'string', enum: ['human', 'dom'], description: 'Which way to act.' },
+        },
+        required: ['mode'], // ui-copy-ignore
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 10_000,
+      isConcurrencySafe: () => true,
+      /** @param {any} args - arguments. @returns {Promise<{text: string}>} which way is set. */
+      execute: async (args) => {
+        const said = String(args?.mode ?? '')
+        if (!WAYS.has(said)) return 'Pass "human" or "dom".'
+        const chat = currentSession()
+        if (said === 'human') chatWays.delete(chat)
+        else chatWays.set(chat, said)
+        return said === 'human'
+          ? 'Real mouse and real keys from now on: pages cannot tell it from a person.'
+          : "The page's own controls from now on: clicks and typing go through its DOM, so an overlay cannot swallow them."
+      },
+    },
+    {
+      name: 'browser_prepare', // ui-copy-ignore
+      description: 'Get a game or a heavy app page ready to play, in one call: read what is on it, find the surface that takes input, say whether it needs a Flash player this browser does not have, measure its real frame rate, and test whether keys reach it. Ends with what to do next instead of a blank page and no explanation.',
+      parameters: {
+        type: 'object', // ui-copy-ignore
+        properties: {
+          seconds: { type: 'number', description: 'How long to count frames for. Default 1.2, at most 5.' },
+          focus: { type: 'boolean', description: 'Click the surface to put keyboard focus in it. Default true.' },
+        },
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 45_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - arguments. @param {any} exec - tool run. @returns {Promise<{text: string}>} what the page is ready for. */
+      execute: async (args, exec) => {
+        const who = String(exec?.agent?.id ?? '')
+        const page = await sidecar.ensure({ session: who })
+        await settle(page, 8000)
+        const seconds = Math.min(5, Math.max(0.5, Number(args?.seconds) || 1.2))
+        const ms = Math.round(seconds * 1000)
+        /* A page that never arrived is not a game that is not ready: say which. */
+        const dead = await unreachable(page)
+        if (dead !== '') return { text: dead }
+        const read = await readPage(page, { mode: 'text', maxChars: 1500 })
+        const said = asSpot(await evaluate(page, `(() => {
+          const box = (el) => { const r = el.getBoundingClientRect(); return { w: Math.round(r.width), h: Math.round(r.height), x: Math.round(r.x + r.width / 2), y: Math.round(r.y + r.height / 2) } }
+          const shown = (el) => {
+            const r = el.getBoundingClientRect()
+            const st = getComputedStyle(el)
+            return r.width >= 120 && r.height >= 80 && st.visibility !== 'hidden' && st.display !== 'none' && Number(st.opacity) > 0.05
+          }
+          const spot = (el, tag) => {
+            const first = box(el)
+            const seen = first.y > 0 && first.y < innerHeight && first.x > 0 && first.x < innerWidth
+            if (!seen) {
+              /* A surface below the fold is not where the person is looking, and
+                 a click at its coordinate would land somewhere else. */
+              el.scrollIntoView({ block: 'center', inline: 'center' })
+              return { tag, src: String(el.getAttribute('src') ?? ''), ...box(el), scrolled: true }
+            }
+            return { tag, src: String(el.getAttribute('src') ?? ''), ...first }
+          }
+          const canvases = Array.from(document.querySelectorAll('canvas')).filter(shown).map((el) => spot(el, 'canvas'))
+          const frames = Array.from(document.querySelectorAll('iframe')).filter(shown).map((el) => spot(el, 'frame'))
+          const movies = document.querySelectorAll('embed, object').length
+          return JSON.stringify({ canvases, frames, movies })
+        })()`))
+        const surface = said?.canvases?.[0] ?? said?.frames?.[0] ?? null
+        /* Give a game the click a person gives it: some of them only start
+           listening for keys once the surface has been touched. */
+        let clicked = ''
+        if (args?.focus !== false && surface !== null) {
+          await page.mouse('mouseMoved', { x: surface.x - 6, y: surface.y - 4 }).catch(() => {})
+          await wait(40)
+          await page.mouse('mousePressed', { x: surface.x, y: surface.y, clickCount: 1 }).catch(() => {})
+          await wait(30)
+          await page.mouse('mouseReleased', { x: surface.x, y: surface.y, clickCount: 1 }).catch(() => {})
+          clicked = `clicked the ${surface.tag} at ${surface.x},${surface.y}`
+        }
+        /* Count the page's own frames and listen for a key, in the page and in
+           the biggest frame, because a game is usually not in the page itself. */
+        const frames = await page.frameList().catch(() => [])
+        const routeOfFrame = (frame) => {
+          if (frame === undefined) return null
+          const sessionId = frame.contextId === undefined && typeof page.childSession === 'function' ? page.childSession(frame.frameId) : undefined
+          if (frame.contextId === undefined && sessionId === undefined) return null
+          return { contextId: frame.contextId, sessionId }
+        }
+        const countFrames = `new Promise((done) => {
+          window.__dshKeys = 0
+          if (window.__dshKeyUp === undefined) {
+            window.__dshKeyUp = true
+            addEventListener('keydown', () => { window.__dshKeys += 1 }, true)
+          }
+          let n = 0
+          const t0 = performance.now()
+          const tick = () => { n += 1; if (performance.now() - t0 < ${ms}) requestAnimationFrame(tick) }
+          requestAnimationFrame(tick)
+          setTimeout(() => done(JSON.stringify({ fps: Math.round((n * 1000) / Math.max(1, performance.now() - t0)), keys: window.__dshKeys })), ${ms + 60})
+        })`
+        const mainRate = asSpot(await evaluate(page, countFrames))
+        let frameRate = null
+        const childFrames = frames.slice(1).filter((frame) => String(frame.url ?? '') !== 'chrome-error://chromewebdata/')
+        const biggest = childFrames[0]
+        const route = routeOfFrame(biggest)
+        if (route !== null) frameRate = asSpot(await evaluate(page, countFrames, route))
+        let keys = route === null ? 'none arrived — there is no frame to test' : 'none arrived in the frame'
+        const keyDown = { type: 'keyDown', key: 'Shift', code: 'ShiftLeft', windowsVirtualKeyCode: 16, nativeVirtualKeyCode: 16 }
+        await page.cdp.send('Input.dispatchKeyEvent', keyDown, route?.sessionId).catch(() => {})
+        await page.cdp.send('Input.dispatchKeyEvent', { ...keyDown, key: 'Shift', type: 'keyUp' }, route?.sessionId).catch(() => {})
+        await wait(80)
+        const after = asSpot(await evaluate(page, 'JSON.stringify({ keys: window.__dshKeys ?? 0 })', route))
+        const mainAfter = asSpot(await evaluate(page, 'JSON.stringify({ keys: window.__dshKeys ?? 0 })'))
+        const arrived = Number(after?.keys ?? 0) + Number(mainAfter?.keys ?? 0) - Number(frameRate?.keys ?? 0) - Number(mainRate?.keys ?? 0)
+        if (arrived > 0) keys = `arrived in the frame (${arrived} keydown event${arrived === 1 ? '' : 's'} from a real key)`
+        else if (route !== null) keys = 'not in the frame — click inside it once, or the game only listens after it starts'
+        const lines = []
+        lines.push(`page: ${read.title === '' ? read.url : read.title} — ${read.controls.length} control(s), ${read.textChars} character(s)`)
+        lines.push(surface === null ? 'surface: no canvas or frame takes the screen — the page itself takes input' : `surface: ${surface.tag} ${surface.w}x${surface.h} at ${surface.x},${surface.y}${surface.scrolled === true ? ' (scrolled it into view)' : ''}${clicked === '' ? '' : ` (${clicked})`}`)
+        if (read.blind?.flash > 0 && sidecar.flash !== true) lines.push(`flash: ${read.blind.flash} movie(s) — open the same page with flash:true and it runs in this plugin's own player, in the column, with no window on the desktop`) // ui-copy-ignore
+        else if (read.blind?.flash > 0) lines.push(`flash: ${read.blind.flash} movie(s) running on this plugin's own player`)
+        else lines.push('flash: none found')
+        lines.push(`frames: ${Math.max(0, frames.length - 1)} (${childFrames.filter((frame) => String(frame.url ?? '') === 'about:blank').length} of them about:blank)`)
+        const rates = []
+        if (mainRate !== null) rates.push(`page ${mainRate.fps} fps`)
+        if (frameRate !== null) rates.push(`frame ${frameRate.fps} fps`)
+        lines.push(`frame rate: ${rates.length === 0 ? 'the page could not count' : rates.join(', ')} over ${ms} ms`)
+        lines.push(`keys: ${keys}`)
+        lines.push(`mode: human${surface === null ? '' : ' — a game watches the mouse and the keys, and only real ones arrive trusted'}`)
+        const trouble = read.blind?.flash > 0 && sidecar.flash !== true
+          ? 'call open with flash:true to run it here'
+          : read.blind?.flash > 0
+            ? 'the movie needs a click inside it before it starts'
+          : surface === null && Number(mainRate?.fps ?? 0) === 0
+            ? 'nothing on this page is animating — it may be waiting for a click, or the game is behind a login'
+            : surface === null
+              ? 'ready to read and act on, though there is no canvas or frame to watch'
+              : `ready: ${surface.tag} is live at ${mainRate?.fps ?? frameRate?.fps ?? 0} fps`
+        lines.push(trouble)
+        return { text: lines.join('\n') }
       },
     },
     {
-      name: 'sidecar_view', // ui-copy-ignore
-      description: 'Read the sidecar browser: numbered controls and the words on screen. Numbers stay valid across reads and actions until the page navigates. Narrow it with mode (text, links, forms, full) and max_chars; ask for changed_only after an action to spend fewer tokens.',
+      name: 'browser_find', // ui-copy-ignore
+      description: 'Find words on the page without reading it all: returns matching numbered controls (click the ref) and matching text (click x/y), each with whether it is on screen. A phone-sized page has hundreds of lines; this answers "where does it say X" in one compact result.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
-          mode: { type: 'string', enum: ['text', 'links', 'forms', 'full'], description: 'What to include. Default text: controls plus the visible words.' },
-          max_chars: { type: 'integer', description: 'Character budget for the page text. Default 6000.' },
+          query: { type: 'string', description: 'Words to look for; case does not matter.' },
+          regex: { type: 'boolean', description: 'Treat query as a regular expression.' },
+          limit: { type: 'integer', description: 'Matches to return. Default 12, at most 40.' },
+        },
+        required: ['query'],
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 30_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - arguments. @returns {Promise<{text: string}>} the matches. */
+      execute: async (args) => withRead(async (page) => {
+        const query = String(args?.query ?? '').trim()
+        if (query === '') return 'Give the words to look for.'
+        const found = await findOnPage(page, query, { regex: args?.regex === true, limit: Number(args?.limit ?? 12) })
+        if (found.fault !== undefined) return `the page did not answer when searched — ${String(found.fault).split('\n')[0].slice(0, 200)}`
+        const matches = Array.isArray(found.matches) ? found.matches : []
+        if (matches.length === 0) return `nothing on this page says ${JSON.stringify(query)} — try other words, or call browser_view for the whole page.`
+        const lines = matches.map((one) => `${one.ref === 0 ? `at ${one.x},${one.y}` : one.ref} [${one.tag}] ${one.name}${one.view === true ? '' : ' (off screen)'}`)
+        return `${matches.length} match(es) for ${JSON.stringify(query)}:\n${lines.join('\n')}`
+      }),
+    },
+    {
+      name: 'browser_read', // ui-copy-ignore
+      description: 'Read the page as a person does: one Markdown block of headings, paragraphs, lists and links, no controls and no markup. Far fewer tokens than browser_view on long pages (articles, docs, threads, issue trackers), and it keeps links so a follow-up can be opened by address. Use browser_view when you need numbers to click or type; use browser_read when you only need the words.',
+      parameters: {
+        type: 'object', // ui-copy-ignore
+        properties: {
+          max_chars: { type: 'integer', description: 'Character ceiling. Default 6000; the result says when it was cut.' },
+          query: { type: 'string', description: 'What you want to know. With a query, only the passages that answer it come back, ranked — the cheapest way to read a long page. Without one, the whole page comes back.' },
+          force: { type: 'boolean', description: 'Read again even if the page has not changed since this chat last read it.' },
+        },
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 30_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - arguments. @returns {Promise<{text: string}>} the words, as Markdown. */
+      execute: async (args) => withRead(async (page) => {
+        const asked = String(args?.query ?? '').trim()
+        const ceiling = Number(args?.max_chars ?? (asked === '' ? 6000 : 4000))
+        const mark = await pageMark(page)
+        const key = mark === '' ? '' : `${mark}|${asked}|${ceiling}`
+        const seen = page === null || page === undefined ? undefined : readSeen.get(page)
+        /* The text this chat already has is not worth sending twice: a page that
+           looks the same answers with where it is, not the same four thousand
+           characters. force is for a caller that lost the earlier answer. */
+        if (args?.force !== true && key !== '' && seen !== undefined && seen.key === key) {
+          return `${mark.split('|')[1] ?? ''} · unchanged since this chat last read it (${String(seen.text.length)} chars) — the text is the one above. Call browser_view with changed_only to see what moved, or pass force for it again.`
+        }
+        const keep = (text) => {
+          if (key !== '' && page !== null && page !== undefined) readSeen.set(page, { key, text })
+          return text
+        }
+        if (asked !== '') {
+          const found = await readRelevant(page, asked, { maxChars: ceiling })
+          if (found.fault !== undefined) return `the page did not answer when read — ${String(found.fault).split('\n')[0].slice(0, 200)}`
+          if (found.text === '') {
+            /* The question missed every block: the page is still the answer, so
+               hand it over whole rather than make the caller guess again. */
+            const whole = await readArticle(page, { maxChars: ceiling })
+            if (whole.fault === undefined && whole.text !== '') {
+              return keep(`${whole.url}\n# ${whole.title === '' ? '(untitled)' : whole.title}\n\nnothing here answers ${JSON.stringify(asked)} (${String(found.total)} blocks read), so the whole page follows:\n\n${whole.text}${whole.truncated ? `\n\n(cut at ${String(whole.chars)} characters; raise max_chars for more)` : ''}`)
+            }
+            return `${found.url}\n# ${found.title === '' ? '(untitled)' : found.title}\n\nnothing here answers ${JSON.stringify(asked)} (${String(found.total)} blocks read). Call browser_view for the whole page, or try other words.`
+          }
+          return keep(`${found.url}\n# ${found.title === '' ? '(untitled)' : found.title}\n\n${found.text}\n\n(${String(found.matched)} of ${String(found.total)} blocks, ranked for ${JSON.stringify(asked)})`)
+        }
+        const read = await readArticle(page, { maxChars: ceiling })
+        if (read.fault !== undefined) return `the page did not answer when read — ${read.fault.split('\n')[0].slice(0, 200)}`
+        if (read.text === '') {
+          const pdf = await pdfNote(page)
+          if (pdf !== '') return `${read.url}\n# ${read.title === '' ? '(untitled)' : read.title}${pdf}`
+          return `${read.url}\n# ${read.title === '' ? '(untitled)' : read.title}\n\nnothing to read here: the page draws its content, or it is still loading. Call browser_view to see what is on screen.`
+        }
+        const head = `${read.url}\n# ${read.title === '' ? '(untitled)' : read.title}`
+        const tail = read.truncated ? `\n\n(cut at ${String(read.chars)} characters; raise max_chars for more)` : ''
+        return keep(`${head}\n\n${read.text}${tail}`)
+      }),
+    },
+    {
+      name: 'browser_view', // ui-copy-ignore
+      description: 'Read the sidecar browser: numbered controls and the words on screen. Numbers stay valid across reads and actions until the page navigates. Narrow it with mode (text, links, forms, full, map) and max_chars; ask for changed_only after an action to spend fewer tokens. Use map first on a page too big to read.',
+      parameters: {
+        type: 'object', // ui-copy-ignore
+        properties: {
+          mode: { type: 'string', enum: ['text', 'links', 'forms', 'full', 'map'], description: 'What to include. Default text: controls plus the visible words. map: a landmark summary of a big page — how many controls of each kind, the distinct ones with their numbers, and how many words there are, without the words.' },
+          max_chars: { type: 'integer', description: 'Character budget for the page text. Default 4600.' },
           changed_only: { type: 'boolean', description: 'Only what changed since the last read.' },
         },
         additionalProperties: false,
@@ -838,25 +2068,56 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       /** @param {any} args - arguments. @returns {Promise<{text: string}>} the read. */
       execute: async (args) => withRead(async (page) => {
         const options = { mode: String(args?.mode ?? 'text'), maxChars: Number(args?.max_chars ?? 4600) }
-        const read = await remember(page, refs, options)
+        /* Each chat keeps its own read state: a shared one let another chat's
+           read replace this chat's baseline, so its numbers and its "what
+           changed" answered about a page it never saw. */
+        const state = refsFor()
+        const read = await remember(page, state, options)
         const note = isCheckPage(read) ? `\n${CHECK_NOTE}` : ''
-        if (args?.changed_only === true && refs.last !== undefined) return diffRead(refs.last, read, options) + note
-        refs.last = read
-        return renderPage(read, options) + note
+        if (args?.changed_only === true && state.last !== undefined) {
+          /* The diff becomes the new baseline: a page that moved zero -> one
+             should not report that move again on the next read. */
+          const text = diffRead(state.last, read, options) + note
+          state.last = read
+          state.lastShape = JSON.stringify(options)
+          return text
+        }
+        /* The read before this one answers two questions: what is new on this
+           one, and whether the page moved at all. Keep it before either answer
+           is overwritten. */
+        const before = state.last
+        state.last = read
+        const fresh = freshRefs(before, read)
+        const freshLine = fresh.length === 0 || fresh.length > 12 ? '' : `\nnew since the read before: ${fresh.map(String).join(', ')}`
+        /* Same page, same shape, same words: the numbers above still work, and
+           repeating the page would only spend tokens. */
+        if (sameRead(before, read) && state.lastShape === JSON.stringify(options)) {
+          const moved = Number(before.scroll?.y ?? 0) !== Number(read.scroll?.y ?? 0) ? `, scrolled to ${Math.round(Number(read.scroll?.y ?? 0))}` : ''
+          /* The address was said with the read above; "here" is the whole of it. */
+          const where = saidUrls.get(page) === String(read.url ?? '') ? 'here' : read.url
+          saidUrls.set(page, String(read.url ?? ''))
+          return `still ${where}${moved} — nothing changed since the last read; the numbers above still work${note}`
+        }
+        state.lastShape = JSON.stringify(options)
+        const said = withoutSeenAddress(page, read.url, renderPage(read, options))
+        saidUrls.set(page, String(read.url ?? ''))
+        return said + freshLine + note + (await pdfNote(page))
       }),
     },
     {
-      name: 'sidecar_click', // ui-copy-ignore
+      name: 'browser_click', // ui-copy-ignore
       description: 'Click a numbered control, a point, or the first control whose words contain `text` — the last needs no read first. The click is real mouse input and the mirror shows where it landed.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
-          ref: { type: 'integer', description: 'Number from sidecar_view.' },
+          ref: { type: 'integer', description: 'Number from browser_view.' },
           text: { type: 'string', description: 'Words on the control, when its number is not known.' },
           x: { type: 'integer', description: 'Viewport x, when clicking a point.' },
           y: { type: 'integer', description: 'Viewport y, when clicking a point.' },
           double: { type: 'boolean', description: 'Double-click.' },
           right: { type: 'boolean', description: 'Right-click, opening a context menu.' },
+          hold_ms: { type: 'integer', description: 'Keep the button down this long before releasing: a press-and-hold a game or a drag handle needs.' },
+          mode: { type: 'string', enum: ['human', 'dom'], description: '"human" moves the real mouse and is what a page cannot tell from a person; "dom" fires the page\'s own click on the numbered control, which reaches one an overlay covers. Omit to use what this chat set with browser_mode.' },
           read: { type: 'boolean', description: 'Read the page after the action, instead of a one-line confirmation.' },
         },
         additionalProperties: false,
@@ -871,36 +2132,55 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         let followed = ''
         if (args?.ref !== undefined) {
           const spot = await findAgain(page, Number(args.ref))
-          if (spot.gone === true) return REF_GONE
+          if (spot.gone === true) return spot.why ?? REF_GONE
           if (spot.followed === true) followed = `the page redrew, so "${String(spot.was).slice(0, 50)}" has a new number — used where it is now`
           point = { x: Number(spot.x), y: Number(spot.y) }
         } else if (String(args?.text ?? '') !== '') {
-          const hit = await findWords(page, String(args.text))
-          if (hit === null) return `No control says ${JSON.stringify(String(args.text))}. Call sidecar_view to see what is there.`
+          const hit = await findWords(page, String(args.text), refsFor().refs)
+          if (hit === null) return `No control says ${JSON.stringify(String(args.text))}. Call browser_view to see what is there.`
           point = { x: hit.x, y: hit.y }
           label = `"${hit.name.slice(0, 60)}"`
         }
-        if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) return 'Give a ref from sidecar_view, or both x and y.'
+        if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) return 'Give a ref from browser_view, or both x and y.'
+        if (wayOf(args) === 'dom') {
+          if (args?.ref === undefined) return 'Acting on the page itself needs a number from browser_view: pass ref, or leave mode out to click like a person.'
+          const pressedAt = Date.now()
+          const said = await evaluate(page, clickInDom(Number(args.ref), { double: args?.double === true, right: args?.right === true })).catch(() => undefined)
+          const hit = asSpot(said)
+          if (hit?.ok !== true) return REF_GONE
+          await settle(page, 5000, pressedAt)
+          const called = await acted(page, args, () => look(page, { mode: 'text', maxChars: 3000 }), `click ${label} on the page itself`)
+          return called + (followed === '' ? '' : ` (${followed})`)
+        }
         const button = args?.right === true ? 'right' : 'left'
         let cover = ''
         if (args?.ref !== undefined && button === 'left') {
           const gate = await clearCover(page, Number(args.ref))
           cover = gate.note
+          /* An overlay that would not go away leaves the control underneath:
+             the click would land on the overlay, so it is not sent. */
+          if (gate.cleared !== true) {
+            return `${cover.trim()}\nNot clicked: the control is still covered. Call browser_view and handle the overlay first.`
+          }
           if (gate.cleared && cover !== '') {
             const again = await locate(page, Number(args.ref))
             if (again.gone !== true) point = { x: Number(again.x), y: Number(again.y) }
           }
         }
+        const before = args?.read === true ? '' : await pageMark(page)
+        const pressedAt = Date.now()
         await page.mouse('mouseMoved', point)
         await page.mouse('mousePressed', { ...point, clickCount: args?.double === true ? 2 : 1, button })
+        const hold = Math.max(0, Math.min(60_000, Number(args?.hold_ms ?? 0)))
+        if (hold > 0) await new Promise((settle) => setTimeout(settle, hold))
         await page.mouse('mouseReleased', { ...point, clickCount: args?.double === true ? 2 : 1, button })
-        await settle(page)
+        await settle(page, 5000, pressedAt)
         const said = await acted(page, args, () => look(page, { mode: 'text', maxChars: 3000 }), `click ${label}`)
-        return said + cover + (followed === '' ? '' : ` (${followed})`)
+        return said + cover + (followed === '' ? '' : ` (${followed})`) + (await outcome(page, before))
       }),
     },
     {
-      name: 'sidecar_type', // ui-copy-ignore
+      name: 'browser_type', // ui-copy-ignore
       description: 'Type text into the sidecar browser — Chinese included — optionally pressing Enter. Pass a ref to focus that control first. With clear, the field is emptied first.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -910,6 +2190,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
           field: { type: 'string', description: 'The field is called this on screen, when you have no number for it.' },
           submit: { type: 'boolean', description: 'Press Enter after typing.' },
           clear: { type: 'boolean', description: 'Select all and delete before typing.' },
+          mode: { type: 'string', enum: ['human', 'dom'], description: '"human" presses real keys and is what a page cannot tell from a person; "dom" sets the field and fires its input events, which leaves key handlers untouched. Omit to use what this chat set with browser_mode.' },
           read: { type: 'boolean', description: 'Read the page after the action, instead of a one-line confirmation.' },
         },
         required: ['text'], // ui-copy-ignore
@@ -922,11 +2203,29 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       execute: async (args) => withPage(async (page) => {
         let cover = ''
         let followed = ''
+        if (wayOf(args) === 'dom') {
+          let target = Number.isInteger(args?.ref) ? Number(args.ref) : undefined
+          if (target === undefined && args?.field !== undefined) {
+            const found = await fieldByName(page, String(args.field), refsFor().refs)
+            if (found === null) return `${String(args.field)}: ${REF_GONE}`
+            if (!Number.isInteger(found.ref)) return `${String(args.field)}: read the page and pass its number, since a field found by its label has none.`
+            target = Number(found.ref)
+            cover = found.lead
+          }
+          if (target === undefined) return 'Acting on the page itself needs a number from browser_view: pass ref, or leave mode out to type like a person.'
+          const said = await evaluate(page, writeInDom(target, String(args?.text ?? ''), { clear: args?.clear === true, submit: args?.submit === true })).catch(() => undefined)
+          const wrote = asSpot(said)
+          if (wrote?.ok !== true) return REF_GONE
+          await settle(page)
+          const called = await acted(page, args, () => look(page, { mode: 'text', maxChars: 2000 }), 'type on the page itself')
+          return `${called} (field now "${String(wrote.value).slice(0, 40)}")` + cover
+        }
         if (args?.field !== undefined && args?.ref === undefined) {
-          const target = await fieldByName(page, String(args.field))
+          const target = await fieldByName(page, String(args.field), refsFor().refs)
           if (target === null) return `${String(args.field)}: ${REF_GONE}`
           cover = target.lead
-          await writeAt(page, { x: target.x, y: target.y }, String(args?.text ?? ''), { clear: args?.clear, submit: args?.submit === true })
+          const dated = await writeAt(page, { x: target.x, y: target.y }, String(args?.text ?? ''), { clear: args?.clear, submit: args?.submit === true, hint: target.name })
+          if (dated !== '') return dated + cover
           await settle(page)
           const called = await acted(page, args, () => look(page, { mode: 'text', maxChars: 2000 }), 'type')
           return called + cover + ` (typed into "${target.name.slice(0, 50)}")` // ui-copy-ignore
@@ -934,8 +2233,11 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         if (args?.ref !== undefined) {
           const gate = await clearCover(page, Number(args.ref))
           cover = gate.note
+          if (gate.cleared !== true) {
+            return `${cover.trim()}\nNot typed into: the field is still covered. Call browser_view and handle the overlay first.`
+          }
           const spot = await findAgain(page, Number(args.ref))
-          if (spot.gone === true) return REF_GONE + cover
+          if (spot.gone === true) return spot.why ?? REF_GONE + cover
           if (spot.followed === true) followed = `the page redrew, so "${String(spot.was).slice(0, 50)}" has a new number — typed where it is now`
           const point = { x: Number(spot.x), y: Number(spot.y) }
           await page.mouse('mouseMoved', point)
@@ -944,21 +2246,136 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
           await wait(80)
         }
         if (args?.clear === true) await clearFocus(page)
-        await page.insertText(String(args?.text ?? ''))
+        if (await dateLikeFocus(page) !== '') return (await fillDateLike(page, String(args?.text ?? ''))) + cover
+        const words = String(args?.text ?? '')
+        const before = args?.read === true ? '' : await pageMark(page)
+        await typeInto(page, words, String(args?.field ?? ''))
+        const dated = await fillDateLike(page, words)
+        if (dated !== '') return dated + cover
         if (args?.submit === true) await pressKey(page, 'Enter')
         await settle(page)
         const said = await acted(page, args, () => look(page, { mode: 'text', maxChars: 2000 }), 'type')
-        return said + cover + (followed === '' ? '' : ` (${followed})`) // ui-copy-ignore
+        return said + cover + (followed === '' ? '' : ` (${followed})`) + (await outcome(page, before)) // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_key', // ui-copy-ignore
-      description: 'Press one key in the sidecar browser: Enter, Tab, Escape, Backspace, Delete, ArrowUp/ArrowDown/ArrowLeft/ArrowRight, Home, End, PageUp, PageDown, Space.',
+      name: 'browser_ask', // ui-copy-ignore
+      description: 'Say something to a chat that is open in the page — a model, a support window, a search box — and read its answer back in the same call. Types into the box, presses Enter, then waits until the answer stops growing. Use it to get a review or a picture prompt answered without a read between every step.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
-          key: { type: 'string', description: 'Key name.' },
-          modifiers: { type: 'string', description: 'Held while pressing: Ctrl, Alt, Shift or Meta, joined by +.' },
+          text: { type: 'string', description: 'What to say.' },
+          ref: { type: 'integer', description: 'The box to type in, from browser_view. Omit to use the page\u2019s own chat box.' },
+          submit: { type: 'boolean', description: 'Press Enter to send. Default true.' },
+          timeout_ms: { type: 'integer', description: 'How long to wait for the answer. Default 60000.' },
+        },
+        required: ['text'], // ui-copy-ignore
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 180_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - arguments. @returns {Promise<{text: string}>} the answer. */
+      execute: async (args) => withPage((page) => askInPage(page, args)),
+    },
+    {
+      name: 'browser_review', // ui-copy-ignore
+      description: 'Ask the chat in the page to review a repository and take its review back as a list: builds the message, sends it, waits for the answer, and writes the round down so the next round knows what was already said. Use it for a review round, not for a one-off question (that is browser_ask).',
+      parameters: {
+        type: 'object', // ui-copy-ignore
+        properties: {
+          repo: { type: 'string', description: 'Address of the repository to review.' },
+          commit: { type: 'string', description: 'The commit the review is about. Omit for the newest one.' },
+          focus: { type: 'string', description: 'One thing to look at especially.' },
+          diff: { type: 'string', description: 'The change to review, as a diff. Include it when the reviewer cannot open the repository itself.' },
+          ref: { type: 'integer', description: 'The box to type in, from browser_view. Omit to use the page\u2019s own chat box.' },
+          timeout_ms: { type: 'integer', description: 'How long to wait for the review. Default 120000.' },
+        },
+        required: ['repo'], // ui-copy-ignore
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 240_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - arguments. @returns {Promise<{text: string}>} the review. */
+      execute: async (args) => withPage(async (page) => {
+        const repo = String(args?.repo ?? '').trim()
+        if (repo === '') return 'Which repository should the reviewer look at?'
+        const commit = String(args?.commit ?? '').trim()
+        /* What was settled last time travels with the question. */
+        const before = lastRound()
+        const already = Array.isArray(before?.marks) ? before.marks : []
+        const asked = askBrief({ repo, commit, focus: String(args?.focus ?? ''), diff: String(args?.diff ?? ''), already })
+        const started = Date.now()
+        const told = await askInPage(page, { text: asked, ref: args?.ref, timeout_ms: args?.timeout_ms ?? 120_000 })
+        const tookMs = Date.now() - started
+        if (!String(told).startsWith('the answer came back in')) return told
+        const answer = String(told).split('\n').slice(1).join('\n').trim()
+        const { round } = recordRound({ commit, question: asked, answer, tookMs })
+        /* A wall answers too, and its words are not advice: name it rather than
+           call the login screen prose. */
+        const wall = /(sign in|log in|登录|注册|verif|checking your browser)/i.test(answer)
+        /* The question sitting there unanswered is not prose: say that instead. */
+        const busy = asked.slice(0, 24)
+        const waiting = round.points.length === 0 && busy.length >= 8 && answer.includes(busy)
+        const list = round.points.length > 0
+          ? round.points.map((point, at) => `${at + 1}. ${point}`).join('\n')
+          : waiting
+            ? `the page has the message but has not answered yet; it shows: ${answer.replace(/\s+/g, ' ').slice(0, 200)}`
+            : wall
+            ? `the page is asking to sign in first, so there is no review yet: ${answer.replace(/\s+/g, ' ').slice(0, 200)}`
+            : `It answered in prose; no list to work from. It said: ${answer.replace(/\s+/g, ' ').slice(0, 200)}`
+        const settled = already.filter((mark) => mark.status !== 'open').length
+        const carried = settled === 0 ? '' : `\n(${settled} earlier point${settled === 1 ? '' : 's'} left out as already handled)`
+        return `review round: ${commit === '' ? 'newest commit' : commit.slice(0, 12)} in ${Math.round(tookMs / 100) / 10}s\n${list}${carried}`
+      }),
+    },
+    {
+      name: 'browser_review_verdict', // ui-copy-ignore
+      description: 'Record what happened to each point of the last review round, so the next round leaves settled points out: point numbers are the ones browser_review printed, and each mark is fixed, verified (checked in the code and the point does not apply), invalid, or open.',
+      parameters: {
+        type: 'object', // ui-copy-ignore
+        properties: {
+          mark: { // ui-copy-ignore
+            type: 'array',
+            description: 'One entry per point: which point, its status, and the evidence that backs it.',
+            items: { // ui-copy-ignore
+              type: 'object', // ui-copy-ignore
+              properties: { // ui-copy-ignore
+                point: { type: 'integer', description: 'The point number browser_review printed, starting at 1.' },
+                status: { type: 'string', enum: MARK_STATUS, description: 'fixed, verified, invalid, or open.' },
+                evidence: { type: 'string', description: 'Where the code shows it: file, test, or commit.' },
+              },
+              required: ['point', 'status'], // ui-copy-ignore
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ['mark'], // ui-copy-ignore
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 10_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - arguments. @returns {Promise<{text: string}>} what was recorded. */
+      execute: async (args) => {
+        const written = markRound({ marks: Array.isArray(args?.mark) ? args.mark : [] })
+        if (written === null) return 'No review round to mark: play one with browser_review first.'
+        const counts = new Map()
+        for (const mark of written.marks) counts.set(mark.status, (counts.get(mark.status) ?? 0) + 1)
+        const said = [...counts].map(([status, n]) => `${n} ${status}`).join(', ')
+        return `review round ${String(written.round.commit || 'newest').slice(0, 12)}: recorded ${written.marks.length} of ${written.round.points.length} points (${said}).`
+      },
+    },
+    {
+      name: 'browser_key', // ui-copy-ignore
+      description: 'Press one key in the background browser: Enter, Tab, Escape, Backspace, Delete, Insert, arrows, Home, End, PageUp, PageDown, Space, F1-F12, the numeric keypad (Numpad0-Numpad9, NumpadEnter, NumpadAdd, ...), printable characters and every symbol on a US keyboard (including shifted ones such as ? : @), plus the keys with a name (ContextMenu, CapsLock, PrintScreen, media keys). Join keys with + to hold them together (ArrowLeft+ArrowUp, Shift+Tab), and hold_ms to keep them down. Modifiers accept Ctrl, Alt, Shift, Meta/Cmd, or Mod for the platform command key; Ctrl+C/X/V/A/Z/Y run the real copy, cut, paste, select-all, undo and redo.',
+      parameters: {
+        type: 'object', // ui-copy-ignore
+        properties: {
+          key: { type: 'string', description: 'Key name, or several joined by + to hold them together (ArrowLeft+ArrowUp, Shift+ArrowLeft). Letters, digits, punctuation and shifted symbols work too.' },
+          modifiers: { type: 'string', description: 'Held while pressing: Ctrl, Alt, Shift, Meta/Cmd, or Mod (Command on macOS, Control on Windows and Linux), joined by +.' },
+          hold_ms: { type: 'integer', description: 'Keep the key down this long before releasing. Games move while a key is held.' },
           read: { type: 'boolean', description: 'Read the page after the action, instead of a one-line confirmation.' },
         },
         required: ['key'], // ui-copy-ignore
@@ -970,15 +2387,22 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       /** @param {any} args - arguments. @returns {Promise<{text: string}>} the page after. */
       execute: async (args) => withPage(async (page) => {
         const name = String(args?.key ?? 'Enter')
-        const held = String(args?.modifiers ?? '')
-        const mods = (held.includes('Alt') ? 1 : 0) + (held.includes('Ctrl') ? 2 : 0) + (held.includes('Meta') ? 4 : 0) + (held.includes('Shift') ? 8 : 0)
-        await pressKey(page, name, mods)
-        await settle(page, 3000)
+        const chord = splitChord(name, modifierBits(args?.modifiers))
+        const mods = chord.modifiers
+        const hold = Math.max(0, Math.min(60_000, Number(args?.hold_ms ?? 0)))
+        if (chord.names.length === 0) throw new Error(`sidecar: ${name} holds no key, only modifiers`) // ui-copy-ignore
+        /* One key goes through the plain path so an editing shortcut is sent as
+           the browser command it is; a chord holds every key down together. */
+        if (chord.names.length > 1) await pressChord(page, chord.names, mods, hold)
+        else await pressKey(page, chord.names[0], mods, hold)
+        /* A held key is game input: waiting for the page to fall quiet after one
+           costs more than the frame it was meant to drive. */
+        if (hold === 0) await settle(page, 3000)
         return acted(page, args, () => look(page, { mode: 'text', maxChars: 2000 }), `key ${name}`)
       }),
     },
     {
-      name: 'sidecar_scroll', // ui-copy-ignore
+      name: 'browser_scroll', // ui-copy-ignore
       description: 'Scroll the sidecar browser by wheel at its centre (negative goes up), then return what it shows.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -996,18 +2420,21 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       /** @param {any} args - arguments. @returns {Promise<{text: string}>} the page after. */
       execute: async (args) => withPage(async (page) => {
         await page.wheel({ x: Number(args?.x ?? VIEW.width / 2), y: Number(args?.y ?? VIEW.height / 2), dy: Number(args?.dy ?? 600) })
+        /* A wheel is a request, not a result: a list that loads more rows on
+           scroll has not answered yet when the wheel returns. Give the scroll
+           handler its turn, then let the page fall quiet. */
         await wait(200)
         const delta = Number(args?.dy ?? 600)
         return acted(page, args, () => look(page, { mode: 'text', maxChars: 4000 }), `scroll ${delta > 0 ? '+' : ''}${delta}`)
       }),
     },
     {
-      name: 'sidecar_hover', // ui-copy-ignore
+      name: 'browser_hover', // ui-copy-ignore
       description: 'Move the pointer onto a numbered control, so hover-only menus and tooltips open, then return what the page shows.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
-          ref: { type: 'integer', description: 'Number from sidecar_view.' },
+          ref: { type: 'integer', description: 'Number from browser_view.' },
           read: { type: 'boolean', description: 'Read the page after the action, instead of a one-line confirmation.' },
         },
         required: ['ref'], // ui-copy-ignore
@@ -1019,7 +2446,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       /** @param {any} args - arguments. @returns {Promise<{text: string}>} the page after. */
       execute: async (args) => withPage(async (page) => {
         const spot = await findAgain(page, Number(args?.ref))
-        if (spot.gone === true) return REF_GONE
+        if (spot.gone === true) return spot.why ?? REF_GONE
         const cursor = await page.hover({ x: Number(spot.x), y: Number(spot.y) })
         await wait(400)
         const said = await acted(page, args, () => look(page, { mode: 'text', maxChars: 2500 }), `hover ${String(args?.ref)} · ${cursor}`)
@@ -1027,7 +2454,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_nav', // ui-copy-ignore
+      name: 'browser_nav', // ui-copy-ignore
       description: 'Change the sidecar browser\'s address: open a url, go back, go forward, or reload. Use this instead of clicking the browser chrome.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1057,7 +2484,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_do', // ui-copy-ignore
+      name: 'browser_do', // ui-copy-ignore
       description: 'Run several steps in one call and report one compact result: the whole of "click search, type a query, press Enter, wait for results" is one call instead of five. Steps run in order and stop at the first that cannot proceed. Each step: {ref, tap | text, submit}, {tap: "x,y"}, {tap: "Sign in"}, {field: "Email", text}, {text}, {key}, {scroll}, {wait_text}, {wait_gone}, {wait_url}, {wait_idle}, {eval}, {open}, {sleep_ms}. Waits know when the page has settled. A step that names a control clears a cookie banner in its way first.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1103,39 +2530,46 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         if (steps.length === 0) return 'Give at least one step.'
         const report = []
         for (const [index, step] of steps.entries()) {
-          const said = await runStep(page, step ?? {}, refs?.refs)
-          report.push(`${index + 1}. ${said}`)
-          if (/^ref \d+: That control is gone/.test(said)) return `${report.join('\n')}\nStopped: the page changed. Call sidecar_view and use the new numbers.`
+          const stepAt = Date.now()
+          const said = await runStep(page, step ?? {}, refsFor().refs)
+          const text = typeof said === 'string' ? said : said.text
+          report.push(`${index + 1}. ${text}`)
+          /* A step that never landed makes every later step a guess, so the
+             batch ends here instead of typing into a page that is not there. */
+          if (typeof said !== 'string' && said.blocked === true) {
+            return `${report.join('\n')}\nStopped after step ${index + 1}. Call browser_view and plan again from what the page shows now.`
+          }
           /* A step can navigate straight onto Chrome's error page — a mistyped
              address, or a site that does not answer. The rest of the batch
              would then type into "This site can't be reached", so it stops
              here and says what really happened. */
           if (isErrorPage(page)) return `${report.join('\n')}\nStopped after step ${index + 1}: ${await unreachable(page)}`
           if (step?.sleep_ms === undefined && step?.wait_text === undefined && step?.wait_gone === undefined && step?.wait_url === undefined && step?.wait_idle === undefined) {
-            await settle(page, Number(step?.timeout ?? 5000))
+            await settle(page, Number(step?.timeout ?? 5000), stepAt)
           }
         }
         const mode = String(args?.read ?? 'text')
         if (mode === 'none') return report.join('\n')
         const options = { mode: mode === 'changed' ? 'text' : mode, maxChars: Number(args?.max_chars ?? 3000) }
-        const read = await remember(page, refs, options)
-        if (mode === 'changed' && refs.last !== undefined) {
-          const diff = diffRead(refs.last, read, options)
-          refs.last = read
+        const state = refsFor()
+        const read = await remember(page, state, options)
+        if (mode === 'changed' && state.last !== undefined) {
+          const diff = diffRead(state.last, read, options)
+          state.last = read
           return `${report.join('\n')}\n${diff}`
         }
-        refs.last = read
+        state.last = read
         return `${report.join('\n')}\n\n${renderPage(read, options)}`
       }),
     },
     {
-      name: 'sidecar_extract', // ui-copy-ignore
+      name: 'browser_extract', // ui-copy-ignore
       description: 'Read the items a selector matches as one compact line each — lists, search results, tables, menus — instead of the whole page. Each row keeps its link when it has one. Use it when a page has more rows than the read budget allows; it costs a fraction of a full read.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
           select: { type: 'string', description: 'CSS selector for the items, for example "ul.results > li".' },
-          ref: { type: 'integer', description: 'Only look inside this control, as numbered by the last sidecar_view.' },
+          ref: { type: 'integer', description: 'Only look inside this control, as numbered by the last browser_view.' },
           limit: { type: 'integer', description: 'Most rows to return. Default 40, at most 200.' },
         },
         required: ['select'], // ui-copy-ignore
@@ -1148,7 +2582,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       execute: async (args) => withRead((page) => extractRows(page, args)),
     },
     {
-      name: 'sidecar_eval', // ui-copy-ignore
+      name: 'browser_eval', // ui-copy-ignore
       description: 'Run JavaScript in the sidecar page and return its value. For what the numbered controls cannot express: reading a table, setting storage, filling a widget. The page must be opened first.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1181,12 +2615,12 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_select', // ui-copy-ignore
+      name: 'browser_select', // ui-copy-ignore
       description: 'Choose an option in a dropdown, by visible label or value, then return the page.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
-          ref: { type: 'integer', description: 'Number of the select control from sidecar_view.' },
+          ref: { type: 'integer', description: 'Number of the select control from browser_view.' },
           field: { type: 'string', description: 'The dropdown is called this on screen, when you have no number for it.' },
           value: { type: 'string', description: 'Option label or value to choose.' },
         },
@@ -1198,20 +2632,30 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       isConcurrencySafe: () => false,
       /** @param {any} args - arguments. @returns {Promise<{text: string}>} the page after. */
       execute: async (args) => withPage(async (page) => {
-        if (args?.ref === undefined) {
-          if (args?.field === undefined) return 'name the dropdown: pass its number from sidecar_view, or the words on screen that name it.' // ui-copy-ignore
-          const chosen = await evaluate(page, selectSpot(String(args.field), String(args?.value ?? '')))
+        let use = args
+        /* One dropdown on the page needs no naming: the value alone says which
+           one, and asking costs the caller a whole read. */
+        if (use?.ref === undefined && use?.field === undefined) {
+          const read = await readPage(page, { mode: 'text', maxChars: 1200, max: 200 })
+          const drops = read.controls.filter((control) => control.view !== false && ['select', 'combobox', 'listbox'].includes(String(control.kind)))
+          if (drops.length === 1) use = { ...use, ref: Number(drops[0].ref) }
+          else if (drops.length > 1) return `which dropdown: ${drops.slice(0, 5).map((one) => `${String(one.name).slice(0, 30)} (${String(one.ref)})`).join(' · ')}`
+          else return 'the page has no dropdown to choose in.' // ui-copy-ignore
+        }
+        if (use?.ref === undefined) {
+          const field = String(use.field)
+          const chosen = await evaluate(page, selectSpot(field, String(use?.value ?? '')))
           const said = typeof chosen === 'string' ? chosen : chosen?.error === undefined ? '' : String(chosen.error)
           if (said === '' || said.startsWith('no dropdown')) return said === '' ? 'the page did not answer; read it and try again.' : said // ui-copy-ignore
           await settle(page, 3000)
-          if (args?.read === true) return `${said}\n${await look(page, { mode: 'text', maxChars: 2000 })}`
+          if (use?.read === true) return `${said}\n${await look(page, { mode: 'text', maxChars: 2000 })}`
           return `${said} · ${await brief(page)}`
         }
-        const spot = await findAgain(page, Number(args?.ref))
-        if (spot.gone === true) return REF_GONE
-        const wanted = JSON.stringify(String(args?.value ?? ''))
-        const route = await contextFor(page, Number(args?.ref))
-        const local = route?.local ?? Number(args?.ref)
+        const spot = await findAgain(page, Number(use?.ref))
+        if (spot.gone === true) return spot.why ?? REF_GONE
+        const wanted = JSON.stringify(String(use?.value ?? ''))
+        const route = await contextFor(page, Number(use?.ref))
+        const local = route?.local ?? Number(use?.ref)
         const said = await evaluate(page, `(() => {
   const reg = window.__dshRead
   const hit = reg && reg.find(${local})
@@ -1226,17 +2670,17 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
   return 'chose ' + option.text.trim()
 })()`, route)
         await settle(page, 3000)
-        if (args?.read === true) return `${String(said)}\n${await look(page, { mode: 'text', maxChars: 2000 })}`
+        if (use?.read === true) return `${String(said)}\n${await look(page, { mode: 'text', maxChars: 2000 })}`
         return `${String(said)} · ${await brief(page)}`
       }),
     },
     {
-      name: 'sidecar_upload', // ui-copy-ignore
+      name: 'browser_upload', // ui-copy-ignore
       description: 'Put files into a file input on the page, by absolute path, then return the page. The file chooser never opens.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
-          ref: { type: 'integer', description: 'Number of the file input from sidecar_view.' },
+          ref: { type: 'integer', description: 'Number of the file input from browser_view.' },
           files: { type: 'array', items: { type: 'string' }, description: 'Absolute paths on this machine.' },
         },
         required: ['ref', 'files'], // ui-copy-ignore
@@ -1255,7 +2699,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         if (route?.contextId !== undefined) uploadParams.contextId = route.contextId
         const handle = await page.cdp.send('Runtime.evaluate', uploadParams, route?.sessionId)
         const objectId = handle.result?.objectId
-        if (objectId === undefined) return REF_GONE
+        if (objectId === undefined) return spot.why ?? REF_GONE
         const node = await page.cdp.send('DOM.describeNode', { objectId }, route?.sessionId)
         const backendNodeId = node?.node?.backendNodeId
         if (backendNodeId === undefined) return 'That control cannot take a file.'
@@ -1265,33 +2709,43 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_shot', // ui-copy-ignore
-      description: 'Save a PNG of the sidecar browser into the session folder and return its absolute path. Default is the visible screen; full takes the whole page, ref takes one control.',
+      name: 'browser_shot', // ui-copy-ignore
+      description: 'Save a PNG of the sidecar browser into the session folder and return its absolute path; when the current model accepts images the picture comes back in the same call, so a captcha, a chart or a broken layout can be looked at instead of guessed. Default is the visible screen; full takes the whole page, ref takes one control.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
           name: { type: 'string', description: 'File name without extension.' },
           full: { type: 'boolean', description: 'The whole page, not just the screen.' },
-          ref: { type: 'integer', description: 'One control from sidecar_view.' },
+          ref: { type: 'integer', description: 'One control from browser_view.' },
           scale: { type: 'integer', description: 'Pixel ratio. Default 1; 2 is sharper and heavier.' },
         },
         additionalProperties: false,
       },
-      output: TEXT_OUTPUT, // ui-copy-ignore
+      output: SHOT_OUTPUT, // ui-copy-ignore
       timeoutMs: 40_000,
       isConcurrencySafe: () => false,
-      /** @param {any} args - arguments. @returns {Promise<{text: string}>} the saved path. */
-      execute: async (args) => withRead(async (page) => {
+      /**
+       * A picture nobody can look at is only a file path: when the route declares
+       * image input, the same call carries the PNG as an attachment so the next
+       * step can be planned from what is actually on screen instead of guessing.
+       * @param {any} args - arguments.
+       * @param {any} [exec] - call context, for the route and its attachments.
+       * @returns {Promise<any>} the saved path, and the picture when available.
+       */
+      execute: async (args, exec) => {
+        /** @type {{data: string, file: string}|undefined} */
+        let taken
+        const said = await withRead(async (page) => {
         const scale = Math.max(1, Math.min(3, Number(args?.scale ?? 1)))
         let clip = undefined
         if (args?.ref !== undefined) {
           const spot = await findAgain(page, Number(args.ref))
-          if (spot.gone === true) return REF_GONE
+          if (spot.gone === true) return spot.why ?? REF_GONE
           /* The picture is of the control, not of a guess around its middle:
              a canvas can be most of the page, a checkbox a few pixels. */
           const box = await evaluate(page, bounds(Number(args.ref)))
           const rect = typeof box === 'string' ? JSON.parse(box) : box
-          if (rect?.gone === true) return REF_GONE
+          if (rect?.gone === true) return spot.why ?? REF_GONE
           const pad = 8
           clip = {
             x: Math.max(0, Math.round(Number(rect.x) - pad)),
@@ -1301,16 +2755,26 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
           }
         }
         const data = await page.shot({ full: args?.full === true, rect: clip, scale })
-        const dir = join(homedir(), SHOT_DIR)
-        await mkdir(dir, { recursive: true })
-        const name = String(args?.name ?? '').replace(/[^\w.-]/g, '') || `sidecar-${Date.now()}`
-        const file = join(dir, name.endsWith('.png') ? name : `${name}.png`)
-        await writeFile(file, Buffer.from(data, 'base64'))
+        const file = await saveArtifact('shots', data, { name: args?.name, prefix: 'shot' })
+        taken = { data, file }
         return file
-      }),
+        })
+        if (taken === undefined) return said
+        let image
+        try {
+          image = await host.showShot?.(taken.data, taken.file.split('/').pop() ?? 'shot.png', exec) // ui-copy-ignore
+        } catch {
+          image = undefined
+        }
+        /* The route may not carry pictures at all: then the file path is all
+           this call can give, and saying so is better than a silent path the
+           next step assumes was looked at. */
+        if (image === undefined) return { text: `${said.text}\nno picture reached this result — browser_view reads the words here, browser_grab returns a picture as a file` }
+        return { text: said.text, image }
+      },
     },
     {
-      name: 'sidecar_grab', // ui-copy-ignore
+      name: 'browser_grab', // ui-copy-ignore
       description: 'Save the picture on the page as a file: an image, a chart, a drawing surface. Picks the largest one, or the one inside a given control.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1334,9 +2798,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
           found = { pictures: [] }
         }
         const rows = []
-        const dir = join(homedir(), SHOT_DIR)
-        await mkdir(dir, { recursive: true })
-        const base = String(args?.name ?? '').replace(/[^\w.-]/g, '') || `sidecar-picture-${Date.now()}`
+        const base = String(args?.name ?? '').replace(/[^\w.-]/g, '')
         const list = Array.isArray(found?.pictures) ? found.pictures : []
         for (let index = 0; index < list.length; index += 1) {
           const item = list[index]
@@ -1345,8 +2807,11 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
           if (mark < 0) continue
           const type = String(item?.type ?? 'image/png')
           const ext = type.includes('jpeg') ? 'jpg' : type.includes('webp') ? 'webp' : type.includes('svg') ? 'svg' : 'png'
-          const file = join(dir, `${base}${list.length > 1 ? `-${index + 1}` : ''}.${ext}`)
-          await writeFile(file, Buffer.from(body.slice(mark + 1), 'base64'))
+          const file = await saveArtifact('pictures', body.slice(mark + 1), {
+            name: base === '' ? '' : `${base}${list.length > 1 ? `-${index + 1}` : ''}`,
+            ext: `.${ext}`,
+            prefix: 'picture',
+          })
           const size = `${Math.round(Number(item.width) || 0)}x${Math.round(Number(item.height) || 0)}`
           /* Say what the picture looks like in words: a model that cannot open
              a file still needs to know a chart came back blank. */
@@ -1362,7 +2827,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_state', // ui-copy-ignore
+      name: 'browser_state', // ui-copy-ignore
       description: 'Report the sidecar browser: whether it runs, its profile, address, title, how many people are watching its mirror, and how many times a call had to find a control again after the page redrew it.',
       parameters: { type: 'object', properties: {}, additionalProperties: false },
       output: TEXT_OUTPUT, // ui-copy-ignore
@@ -1372,13 +2837,24 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       execute: async () => {
         const state = await sidecar.state()
         const owner = String(host.owner?.() ?? '') // ui-copy-ignore
+        const session = currentSession()
+        const seats = String(host.seats?.() ?? '?') // ui-copy-ignore
+        const mine = sidecar.pageFor(session)
         const rows = [
           state.alive ? 'running' : 'stopped',
+          `chat ${session === '' ? '(no chat id)' : session}`,
+          `this chat's tab ${mine === null ? 'none' : String(mine.url)}`, // ui-copy-ignore
+          `tabs in the browser ${String(sidecar.pages.size)}`,
+          `tab list ${[...sidecar.pages.entries()].map(([key, each]) => `${key.slice(-8)}=${String(each.url)}=${each.cdp?.closed === true ? 'closed' : 'open'}`).join(' | ')}`, // ui-copy-ignore
+          `default tab ${String(sidecar.page?.url)}`, // ui-copy-ignore
           state.headless === false ? 'showing a window' : 'no window',
+          sidecar.flash ? 'Flash-era runtime' : 'Chrome runtime',
           `profile ${String(state.profile)}`,
           `url ${String(state.url)}`,
           `title ${String(state.title)}`,
           `viewers ${String(state.viewers)}`,
+          `listening chats ${seats}`, // ui-copy-ignore
+          `mirror owner ${owner === '' ? 'none' : owner}`, // ui-copy-ignore
           owner === '' ? 'no owner' : `owner ${owner}`,
           `refs followed ${String(follows.count)}`,
           holdText(sidecar) === '' ? 'person free' : `person using it (${String(Math.ceil(Number(sidecar.holding()) / 1000))} s left)`,
@@ -1389,7 +2865,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
     },
 
     {
-      name: 'sidecar_resume', // ui-copy-ignore
+      name: 'browser_resume', // ui-copy-ignore
       description: 'Take the page back from the person at the mirror: clears the hold so the next action is sent at once, instead of waiting the few seconds out.',
       parameters: { type: 'object', properties: {}, additionalProperties: false },
       output: TEXT_OUTPUT, // ui-copy-ignore
@@ -1402,7 +2878,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       },
     },
     {
-      name: 'sidecar_downloads', // ui-copy-ignore
+      name: 'browser_downloads', // ui-copy-ignore
       description: 'List what this browser has downloaded, newest first, with the file name, its size and when it arrived.',
       parameters: { type: 'object', properties: {}, additionalProperties: false },
       output: TEXT_OUTPUT, // ui-copy-ignore
@@ -1417,7 +2893,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
     },
 
     {
-      name: 'sidecar_drag', // ui-copy-ignore
+      name: 'browser_drag', // ui-copy-ignore
       description: 'Drag from one place to another with real mouse steps: from a ref or a point, to a point or offset. Use it for sliders, dashboards and drag-and-drop lists.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1440,7 +2916,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         let start = { x: Number(args?.x ?? NaN), y: Number(args?.y ?? NaN) }
         if (args?.from !== undefined) {
           const spot = await findAgain(page, Number(args.from))
-          if (spot.gone === true) return REF_GONE
+          if (spot.gone === true) return spot.why ?? REF_GONE
           start = { x: Number(spot.x), y: Number(spot.y) }
         }
         const end = { x: Number(args?.to_x ?? NaN), y: Number(args?.to_y ?? NaN) }
@@ -1460,12 +2936,12 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_check', // ui-copy-ignore
+      name: 'browser_check', // ui-copy-ignore
       description: 'Set a checkbox, radio or switch to a known state, and say whether it took. Clicking blindly flips a control that is already right; this one looks first.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
-          ref: { type: 'integer', description: 'Control number from sidecar_view.' },
+          ref: { type: 'integer', description: 'Control number from browser_view.' },
           checked: { type: 'boolean', description: 'Wanted state. Omit to flip it.' },
           read: { type: 'boolean', description: 'Read the page after.' },
         },
@@ -1485,11 +2961,11 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         if (checkRoute?.contextId !== undefined) checkParams.contextId = checkRoute.contextId
         const probe = await page.cdp.send('Runtime.evaluate', checkParams, checkRoute?.sessionId)
         const now = probe.result?.value
-        if (now === null || now === undefined) return REF_GONE
+        if (now === null || now === undefined) return spot.why ?? REF_GONE
         const want = args?.checked === undefined ? !Boolean(now.checked) : args.checked === true
         if (Boolean(now.checked) !== want) {
           const spot = await findAgain(page, Number(args.ref))
-          if (spot.gone === true) return REF_GONE
+          if (spot.gone === true) return spot.why ?? REF_GONE
           await page.mouse('mouseMoved', { x: Number(spot.x), y: Number(spot.y) })
           await page.mouse('mousePressed', { x: Number(spot.x), y: Number(spot.y) })
           await page.mouse('mouseReleased', { x: Number(spot.x), y: Number(spot.y) })
@@ -1501,7 +2977,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_wait', // ui-copy-ignore
+      name: 'browser_wait', // ui-copy-ignore
       description: 'Wait until the page shows a piece of text, stops showing it, reaches an address, or goes quiet. Cheaper than reading in a loop.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1537,7 +3013,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_dialog', // ui-copy-ignore
+      name: 'browser_dialog', // ui-copy-ignore
       description: 'Answer the alert, confirm or prompt the page is showing, or read what it asks. A dialog blocks the page until it is answered, so nothing else works while one is open.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1565,7 +3041,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_console', // ui-copy-ignore
+      name: 'browser_console', // ui-copy-ignore
       description: 'The console lines and errors this page has produced, newest last. Use it when a click seemed to do nothing.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1583,7 +3059,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_failed', // ui-copy-ignore
+      name: 'browser_failed', // ui-copy-ignore
       description: 'Requests this page tried and that failed, newest last. A blank area is often one of these.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1601,7 +3077,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_cookie',
+      name: 'browser_cookie',
       description: 'Read or change the cookies this browser keeps. Login state is a cookie, so this is how you check a sign-in and how you keep one.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1645,7 +3121,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_clipboard', // ui-copy-ignore
+      name: 'browser_clipboard', // ui-copy-ignore
       description: 'Read the sidecar browser\'s clipboard, or put text on it and paste it with a key press. For a page that only copies through a button, click it then read here.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1668,7 +3144,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       }),
     },
     {
-      name: 'sidecar_network', // ui-copy-ignore
+      name: 'browser_network', // ui-copy-ignore
       description: 'List the responses the page has received, newest first: method, status, type and address. Use it when a page fills itself from the network and the screen does not say why.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1694,7 +3170,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
     },
 
     {
-      name: 'sidecar_tabs', // ui-copy-ignore
+      name: 'browser_tabs', // ui-copy-ignore
       description: 'List the pages open in the browser, switch the mirror to another one, or close one. Use it when a site opens a link in a tab of its own.',
       parameters: {
         type: 'object', // ui-copy-ignore
@@ -1711,25 +3187,29 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       execute: async (args) => withRawPage(async (page) => {
         const action = String(args?.action ?? 'list')
         if (action === 'list') {
-          const rows = await sidecar.tabs()
+          const rows = await sidecar.tabs(currentSession())
           if (rows.length === 0) return 'no tabs'
           return rows.map((row, i) => `${i}${row.current ? ' *' : ''} ${row.title || row.url} · ${row.url}`).join('\n')
         }
         const index = Number(args?.index ?? 0)
         if (action === 'switch') {
-          const next = await sidecar.useTab(index)
+          const next = await sidecar.useTab(index, currentSession())
           return `tab ${index} · ${String(next?.url ?? '')}`
         }
         if (action === 'close') {
-          await sidecar.closeTab(index)
-          return `closed tab ${index} · ${String(sidecar.page?.url ?? '')}`
+          /* Say what was closed, not what is left: after the close the page
+             that was at that row is gone and reads back as about:blank. */
+          const before = await sidecar.tabs(currentSession())
+          const gone = String(before[index]?.url ?? '')
+          await sidecar.closeTab(index, currentSession())
+          return `closed tab ${index} · ${gone}`
         }
         throw new Error(`sidecar: unknown action ${action}`)
       }),
     },
 
     {
-      name: 'sidecar_pdf', // ui-copy-ignore
+      name: 'browser_pdf', // ui-copy-ignore
       description: 'Print the page to a PDF and return its path. Useful when the person wants the document rather than a picture of it.',
       parameters: { type: 'object', properties: {}, additionalProperties: false },
       output: TEXT_OUTPUT, // ui-copy-ignore
@@ -1738,11 +3218,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       /** @returns {Promise<{text: string}>} where the PDF is. */
       execute: async () => withRawPage(async (page) => {
         const data = await page.pdf()
-        const dir = join(homedir(), SHOT_DIR)
-        await mkdir(dir, { recursive: true })
-        const file = join(dir, `sidecar-${Date.now()}.pdf`)
-        await writeFile(file, Buffer.from(data, 'base64'))
-        return file
+        return saveArtifact('pdf', data, { ext: '.pdf', prefix: 'page' })
       }),
     },
   ]