dsh-inner-browser-use 0.18.0 → 0.34.28

package/read.js

@@ -43,6 +43,9 @@ const SELECTOR = [
   '[role="option"]',
   '[role="textbox"]',
   '[role="searchbox"]',
+  /* A drawing surface has no words in the tree, but it is the whole page in
+     some products: number it, and let a picture be taken of it. */
+  'canvas',
 ].join(',')
 
 /** How a role is written in the compact read: short enough to cost little. */
@@ -133,6 +136,10 @@ function snapshot(mode, budget, max) {
     const own = named || el.getAttribute?.('aria-label') || el.getAttribute?.('title') || el.getAttribute?.('placeholder') || ''
     const text = String(el.innerText ?? '').replace(/\\s+/g, ' ').trim()
     const value = el.tagName === 'INPUT' && el.type !== 'password' ? String(el.value ?? '') : ''
+    if (el.tagName === 'CANVAS' && label === '' && own === '' && text === '' && value === '') {
+      const b = el.getBoundingClientRect()
+      return 'drawing ' + Math.round(b.width) + 'x' + Math.round(b.height)
+    }
     return String(label || own || text || value || el.getAttribute?.('alt') || el.getAttribute?.('name') || '').replace(/\\s+/g, ' ').trim().slice(0, 140)
   }
   const box = (el) => el.getBoundingClientRect()
@@ -240,6 +247,98 @@ function snapshot(mode, budget, max) {
       }
     }
   }
+  /* A page with almost no words and one big picture is answering with the
+     picture. Say so here, in the same round trip, so a model that cannot open
+     files still learns that something came back: and sample it small to tell a
+     blank chart from a chart. */
+  const picture = (() => {
+    if (full >= 40) return null
+    let best = null
+    const missing = []
+    for (const el of document.querySelectorAll('img,canvas')) {
+      const b = box(el)
+      /* A picture that failed to arrive shrinks to an error icon, so its own
+         declared size is what the page meant to show. */
+      const askW = Number(el.getAttribute?.('width')) || 0
+      const askH = Number(el.getAttribute?.('height')) || 0
+      const wide = Math.max(b.width, askW)
+      const high = Math.max(b.height, askH)
+      if (wide < 64 || high < 64 || wide * high < 8000) continue
+      const s = getComputedStyle(el)
+      if (s.visibility === 'hidden' || s.display === 'none') continue
+      /* A picture slot that never got its picture is the commonest way a
+         generated image goes missing, and it is silent by default. */
+      if (el.tagName === 'IMG' && el.complete && el.naturalWidth === 0) {
+        missing.push({ width: Math.round(wide), height: Math.round(high) })
+        missing[missing.length - 1].name = String(el.getAttribute('alt') ?? '').replace(/\s+/g, ' ').trim().slice(0, 60)
+        continue
+      }
+      const w = el.tagName === 'CANVAS' ? el.width : el.naturalWidth || Math.round(b.width)
+      const h = el.tagName === 'CANVAS' ? el.height : el.naturalHeight || Math.round(b.height)
+      if (best === null || w * h > best.w * best.h) best = { el, w, h, kind: String(el.tagName).toLowerCase() }
+    }
+    if (best === null) return missing.length === 0 ? null : { missing }
+    /* What the read hands back about one picture: not a screen of fields. */
+    const said = { name: String(best.el.getAttribute?.('alt') ?? best.el.getAttribute?.('aria-label') ?? '').replace(/\s+/g, ' ').trim().slice(0, 60) }
+    said.kind = best.kind
+    said.width = best.w
+    said.height = best.h
+    said.colors = 0
+    said.flat = 0
+    try {
+      const board = document.createElement('canvas')
+      board.width = 32
+      board.height = 32
+      const pen = board.getContext('2d', { willReadFrequently: true })
+      if (pen === null) return said
+      pen.drawImage(best.el, 0, 0, 32, 32)
+      const dots = pen.getImageData(0, 0, 32, 32).data
+      const tally = new Map()
+      for (let at = 0; at < dots.length; at += 4) {
+        const key = (dots[at] >> 5) * 64 + (dots[at + 1] >> 5) * 8 + (dots[at + 2] >> 5)
+        tally.set(key, (tally.get(key) || 0) + 1)
+      }
+      let most = 0
+      for (const count of tally.values()) most = Math.max(most, count)
+      said.colors = tally.size
+      said.flat = Math.round((most / 1024) * 100) / 100
+    } catch {
+      /* A picture from elsewhere cannot be sampled: report its size only. */
+    }
+    return said
+  })()
+  /* What no amount of text will tell the reader: the screen shows something
+     that has no words in the tree. Counted here so every read can say it. */
+  const blind = (() => {
+    const out = { pictures: 0, canvases: 0, videos: 0, frames: 0 }
+    const speaks = (el) => {
+      const said = String(el.getAttribute?.('alt') ?? '').trim() || String(el.getAttribute?.('aria-label') ?? '').trim() || String(el.getAttribute?.('title') ?? '').trim()
+      if (said.length > 1) return true
+      let near = el.closest?.('figure, picture')
+      if (near) {
+        const words = String(near.querySelector?.('figcaption')?.textContent ?? '').trim()
+        if (words.length > 1) return true
+      }
+      return false
+    }
+    const shows = (el) => {
+      const b = box(el)
+      if (b.width < 48 || b.height < 48) return false
+      if (!inView(b)) return false
+      const st = getComputedStyle(el)
+      return st.visibility !== 'hidden' && st.display !== 'none' && Number(st.opacity) > 0.05
+    }
+    for (const el of document.querySelectorAll('img')) {
+      if (!shows(el) || speaks(el)) continue
+      out.pictures += 1
+    }
+    for (const el of document.querySelectorAll('canvas')) if (shows(el)) out.canvases += 1
+    for (const el of document.querySelectorAll('video')) if (shows(el)) out.videos += 1
+    /* A tracking pixel of a frame is not something the reader is missing: only
+       frames that occupy the screen are worth a sentence. */
+    for (const el of document.querySelectorAll('iframe')) if (shows(el)) out.frames += 1
+    return out
+  })()
   return JSON.stringify({
     url: location.href, // ui-copy-ignore
     title: document.title, // ui-copy-ignore
@@ -252,6 +351,8 @@ function snapshot(mode, budget, max) {
       return { ref: reg.id(el), kind: role(el), name: name(el) }
     })(),
     controls: picked,
+    picture,
+    blind,
   })
 })()`
 }
@@ -278,6 +379,130 @@ export function resolve(ref) {
 })()`
 }
 
+/**
+ * How big the control is and where it sits, so a picture can be of it alone.
+ * @param {number} ref - ref from a read.
+ * @returns {string} an expression that answers with the rectangle.
+ */
+export function bounds(ref) {
+  return `(() => {
+  const reg = window.${REGISTRY}
+  if (!reg) return JSON.stringify({ gone: true })
+  const hit = reg.find(${Number(ref)})
+  if (!hit) return JSON.stringify({ gone: true })
+  const el = hit.el
+  if (el.scrollIntoView) el.scrollIntoView({ block: 'center', inline: 'center' })
+  const b = el.getBoundingClientRect()
+  if (b.width < 2 || b.height < 2) return JSON.stringify({ gone: true, off: true })
+  return JSON.stringify({ gone: false, x: b.left, y: b.top, width: b.width, height: b.height })
+})()`
+}
+
+/**
+ * The pictures on the page, as files a person can open.
+ * A generated image or a chart is often the whole answer, and there is no
+ * wording in the tree that stands for it: take the picture itself.
+ * @param {number} [ref] - only pictures at or inside this control.
+ * @param {number} [count] - how many, largest first. Default 1.
+ * @returns {string} an expression that answers with `{pictures: [...]}`.
+ */
+export function pictures(ref, count) {
+  const scope = Number(ref)
+  const limit = Math.max(1, Math.min(4, Number(count) || 1))
+  return `(async () => {
+  const reg = window.${REGISTRY}
+  const where = ${Number.isFinite(scope) ? `(reg ? (reg.find(${scope}) || {}).el : null)` : 'null'}
+  const picked = []
+  const seen = new Set()
+  const add = (el, kind) => {
+    if (el === null || el === undefined || seen.has(el)) return
+    seen.add(el)
+    const b = el.getBoundingClientRect()
+    const w = kind === 'canvas' ? el.width : kind === 'video' ? el.videoWidth || b.width : el.naturalWidth || b.width
+    const h = kind === 'canvas' ? el.height : kind === 'video' ? el.videoHeight || b.height : el.naturalHeight || b.height
+    if (w < 48 || h < 48) return
+    if (b.width < 8 || b.height < 8) return
+    const s = getComputedStyle(el)
+    if (s.visibility === 'hidden' || s.display === 'none' || Number(s.opacity) < 0.05) return
+    picked.push({ el, kind, w, h, area: w * h })
+  }
+  const roots = where ? [where, ...where.querySelectorAll('*')] : [document, ...document.querySelectorAll('*')]
+  for (const node of roots) {
+    if (node === document || node === where) continue
+    const tag = node.tagName
+    if (tag === 'IMG') add(node, 'img')
+    else if (tag === 'CANVAS') add(node, 'canvas')
+    /* A paused video is the frame the person is looking at; it never arrives as
+       an image file, so it has to be drawn out of the element. */
+    else if (tag === 'VIDEO' && (node.videoWidth || 0) > 0) add(node, 'video')
+  }
+  if (where && where.tagName === 'IMG') add(where, 'img')
+  if (where && where.tagName === 'CANVAS') add(where, 'canvas')
+  if (where && where.tagName === 'VIDEO' && (where.videoWidth || 0) > 0) add(where, 'video')
+  picked.sort((a, b) => b.area - a.area)
+  /* A picture nobody can look at still has to be describable: how much of it is
+     one colour tells a blank chart from a chart. Sampled at 32x32, which is
+     enough for that and costs nothing. */
+  const look = async (data) => {
+    try {
+      const img = new Image()
+      img.src = data
+      await img.decode()
+      const board = document.createElement('canvas')
+      board.width = 32
+      board.height = 32
+      const pen = board.getContext('2d', { willReadFrequently: true })
+      if (pen === null) return null
+      pen.drawImage(img, 0, 0, 32, 32)
+      const dots = pen.getImageData(0, 0, 32, 32).data
+      const tally = new Map()
+      for (let at = 0; at < dots.length; at += 4) {
+        const key = (dots[at] >> 5) * 64 + (dots[at + 1] >> 5) * 8 + (dots[at + 2] >> 5)
+        tally.set(key, (tally.get(key) || 0) + 1)
+      }
+      let most = 0
+      for (const count of tally.values()) most = Math.max(most, count)
+      return { colors: tally.size, flat: Math.round((most / 1024) * 100) / 100 }
+    } catch {
+      return null
+    }
+  }
+  const out = []
+  for (const item of picked.slice(0, ${limit})) {
+    let data = ''
+    let type = 'image/png'
+    try {
+      if (item.kind === 'canvas' || item.kind === 'video') {
+        /* Same path for both: a video frame is copied onto a board and read as
+           a picture. Nothing here needs the video to be playing. */
+        const board = document.createElement('canvas')
+        board.width = Math.max(1, Math.round(item.w))
+        board.height = Math.max(1, Math.round(item.h))
+        const pen = board.getContext('2d')
+        pen.drawImage(item.el, 0, 0, board.width, board.height)
+        data = board.toDataURL('image/png')
+      } else {
+        const url = item.el.currentSrc || item.el.src || ''
+        const answer = await fetch(url, { credentials: 'include' })
+        const blob = await answer.blob()
+        type = blob.type || type
+        data = await new Promise((done, fail) => {
+          const reader = new FileReader()
+          reader.onload = () => done(String(reader.result))
+          reader.onerror = () => fail(new Error('unreadable'))
+          reader.readAsDataURL(blob)
+        })
+      }
+    } catch {
+      data = ''
+    }
+    const feel = data ? await look(data) : null
+    out.push({ kind: item.kind, width: item.w, height: item.h, type, data, colors: feel?.colors ?? 0, flat: feel?.flat ?? 0 })
+  }
+  return JSON.stringify({ pictures: out })
+})()`
+}
+
 /**
  * What sits on top of a control at click time, when it is not the control.
  * A cookie banner or a modal over the thing the agent meant to click is the
@@ -438,15 +663,15 @@ function routeOf(page, frame, slot) {
  * @param {any} page - sidecar page.
  * @param {string} mode - read mode.
  * @param {number} budget - characters of text to keep.
- * @returns {Promise<{text: string, controls: any[]}>} what the frames add.
+ * @returns {Promise<{text: string, controls: any[], frames: number}>} what the frames add.
  */
 async function readFrames(page, mode, budget) {
-  if (typeof page.frameList !== 'function') return { text: '', controls: [] }
+  if (typeof page.frameList !== 'function') return { text: '', controls: [], frames: 0 }
   let frames = []
   try {
     frames = await page.frameList()
   } catch (error) {
-    return { text: '', controls: [] }
+    return { text: '', controls: [], frames: 0 }
   }
   const children = frames.slice(1)
   const controls = []
@@ -468,7 +693,7 @@ async function readFrames(page, mode, budget) {
       continue
     }
   }
-  return { text, controls }
+  return { text, controls, frames: children.length }
 }
 
 /** Decode a ref into the frame it lives in and the number that frame knows. */
@@ -521,18 +746,55 @@ export async function readPage(page, options = {}) {
     title: String(read?.title ?? page.title),
     text: String(read?.text ?? ''),
     textChars: Number(read?.textChars ?? 0),
+    picture: read?.picture ?? null,
     scroll: read?.scroll,
     focused: read?.focused ?? null,
     controls: Array.isArray(read?.controls) ? read.controls : [],
+    blind: blindSpots(read?.blind, framed.frames),
   }
 }
 
+/**
+ * Merge what the page counted with what the frame reader managed to see.
+ * @param {any} said - counts from the page.
+ * @param {number} [read] - frames that answered.
+ * @returns {{pictures: number, canvases: number, videos: number, frames: number}} what text cannot show.
+ */
+export function blindSpots(said, read) {
+  const n = (value) => (Number.isFinite(Number(value)) ? Math.max(0, Math.round(Number(value))) : 0)
+  /* The page knows which frames take up the screen; the frame reader knows how
+     many exist, tracking pixels included. The screen is what the reader is
+     missing, so its count wins whenever the page could count at all. */
+  const frames = said !== undefined && said !== null && said.frames !== undefined ? n(said.frames) : n(read)
+  return { pictures: n(said?.pictures), canvases: n(said?.canvases), videos: n(said?.videos), frames }
+}
+
 /**
  * Resolve a ref into a point, at the moment of the action.
  * @param {any} page - sidecar page.
  * @param {number} ref - ref from a read.
  * @returns {Promise<{gone: boolean, x?: number, y?: number, name?: string, kind?: string, off?: boolean, hidden?: boolean, disabled?: boolean}>} where it is now.
  */
+/**
+ * Whether a number still means what it meant when it was read.
+ *
+ * A page can keep the same element and change its words: "Send" becomes
+ * "Stop", a row is reused for another order. Pressing the old number then
+ * does something the person never asked for.
+ * @param {any} known - the control the read handed out.
+ * @param {any} spot - what the number resolves to now.
+ * @returns {string} what changed, or '' when it is the same control.
+ */
+export function differs(known, spot) {
+  if (known === undefined || known === null || spot === undefined || spot === null) return ''
+  const before = String(known.name ?? '').replace(/\s+/g, ' ').trim().slice(0, 40)
+  const now = String(spot.name ?? '').replace(/\s+/g, ' ').trim().slice(0, 40)
+  if (before === '' || now === '' || before === now) return ''
+  const head = Math.min(12, before.length, now.length)
+  if (head >= 4 && (before.slice(0, head) === now.slice(0, head) || before.includes(now.slice(0, head)) || now.includes(before.slice(0, head)))) return ''
+  return `that number now points at "${now}" instead of "${before}" — read the page again and use the new number.`
+}
+
 export async function locate(page, ref) {
   const split = splitFrameRef(ref)
   let route = null
@@ -572,6 +834,10 @@ export function renderPage(read, options = {}) {
   const mode = String(options.mode ?? 'text')
   const maxChars = Number(options.maxChars ?? 6000)
   const lines = [read.url]
+  /* A browser error page is not a site with nothing on it: it is a site that
+     never arrived. Saying so is the only way the reader stops looking for the
+     content that would have been there. */
+  if (String(read.url).startsWith('chrome-error://')) lines.push('the page did not load — sidecar_nav to open the address again, or sidecar_open if the browser is gone')
   if (read.title !== '') lines.push(`# ${read.title}`)
   const shown = read.controls.filter((control) => control.view !== false || mode === 'full')
   const hidden = read.controls.length - shown.length
@@ -591,6 +857,28 @@ export function renderPage(read, options = {}) {
     lines.push(body)
     if (read.textChars > body.length) lines.push(`… ${read.textChars - body.length} more characters`)
   }
+  if (read.blind !== undefined && read.blind !== null) {
+    const bits = []
+    if (read.blind.pictures > 0) bits.push(`${read.blind.pictures} picture(s) with no words`)
+    if (read.blind.canvases > 0) bits.push(`${read.blind.canvases} drawing surface(s)`)
+    if (read.blind.videos > 0) bits.push(`${read.blind.videos} video(s)`)
+    if (read.blind.frames > 0) bits.push(`${read.blind.frames} embedded frame(s)`)
+    /* Only when something is actually out of reach: a line saying "nothing is
+       hidden" on every read is a line the reader learns to skip. */
+    if (bits.length > 0) lines.push(`text cannot show: ${bits.join(', ')} — sidecar_grab takes the picture, sidecar_shot shows the screen`)
+  }
+  if (read.picture && Array.isArray(read.picture.missing)) {
+    /* Something was meant to be here and is not: say that instead of nothing. */
+    for (const gone of read.picture.missing.slice(0, 2)) {
+      const size = `${Math.round(Number(gone.width) || 0)}x${Math.round(Number(gone.height) || 0)}`
+      lines.push(`picture ${size}${gone.name === '' ? '' : ` "${gone.name}"`} did not load — the page may need a reload, or the picture is gone`)
+    }
+  } else if (read.picture) {
+    const pic = read.picture
+    const look = Number(pic.flat) >= 0.9 ? 'mostly one colour' : Number(pic.colors) <= 3 ? 'a few colours' : 'a picture with detail'
+    const size = `${Math.round(Number(pic.width) || 0)}x${Math.round(Number(pic.height) || 0)}`
+    lines.push(`picture ${size} ${look}${pic.name === '' ? '' : ` "${pic.name}"`} — sidecar_grab saves it as a file`)
+  }
   if (read.scroll && read.scroll.height > read.scroll.viewport + 40) {
     lines.push(`scroll ${read.scroll.y}/${read.scroll.height - read.scroll.viewport}`)
   }
@@ -634,23 +922,8 @@ export function sameThing(want, control) {
   return true
 }
 
-/**
- * The field a label belongs to, when nothing formally connects the two.
- *
- * `{field: "Email"}` used to mean "click the control that says Email". On a real
- * form the words live in a div above a bare input, so the click landed on the
- * text and the typing went wherever focus already was — the classic silent wrong
- * field. This finds the *editable* element the words point at: a real label, an
- * aria name, a placeholder, a name attribute, the text right before it, or the
- * text of the small wrapper it sits in.
- * @param {string} words - what the field is called.
- * @returns {string} an expression that evaluates to a spot, or {} when nothing fits.
- */
-export function labelSpot(words) {
-  const wanted = JSON.stringify(String(words ?? '').toLowerCase())
-  return `(() => {
-  const want = ${wanted}
-  if (want === '') return JSON.stringify({})
+/** The in-page half shared by `labelSpot` and `selectSpot`: shadow roots, what says what. */
+const NAME_PRELUDE = `
   const roots = [document]
   for (const el of document.querySelectorAll('*')) {
     if (roots.length > 400) break
@@ -685,34 +958,125 @@ export function labelSpot(words) {
     add(el.getAttribute('aria-label'))
     add(el.getAttribute('placeholder'))
     add(el.getAttribute('title'))
-    add(el.getAttribute('name'))
     if (el.id) for (const l of document.querySelectorAll('label[for]')) if (l.htmlFor === el.id) add(l.innerText ?? l.textContent)
     const prev = el.previousElementSibling
     if (prev && editable(prev) !== true) add(prev.innerText ?? prev.textContent)
     const parent = el.parentElement
     if (parent && parent.querySelectorAll('input,textarea,select,[contenteditable=true]').length <= 1) add(parent.innerText ?? parent.textContent)
+    /* Wrapped a couple of levels deep (a styled box hiding a real input), the
+       words sit before the wrapper, not before the input. */
+    let up = parent
+    for (let depth = 0; depth < 3 && up; depth += 1) {
+      const before = up.previousElementSibling
+      if (before && editable(before) !== true) add(before.innerText ?? before.textContent)
+      up = up.parentElement
+    }
+    /* The attribute is the last resort for a name on screen: it is often the
+       developer's word for the field, not the one the user reads. */
+    add(el.getAttribute('name'))
     return out
   }
-  let best = null
-  for (const root of roots) {
-    for (const el of root.querySelectorAll('input,textarea,select,[contenteditable=""],[contenteditable=true],[role=textbox],[role=searchbox],[role=combobox]')) {
-      if (editable(el) !== true || shown(el) !== true) continue
-      let score = 0
-      let name = ''
-      for (const nm of names(el)) {
-        const low = nm.toLowerCase()
-        if (low === want) score = Math.max(score, 3)
-        else if (want.length >= 2 && low.includes(want)) score = Math.max(score, 2)
-        else if (low.length >= 3 && want.includes(low)) score = Math.max(score, 1)
-        if (score > 0 && name === '') name = nm
+  const squeeze = (s) => String(s).toLowerCase().replace(/\s+/g, '')
+  const scored = (el, want) => {
+    let score = 0
+    let name = ''
+    const flat = squeeze(want)
+    for (const nm of names(el)) {
+      const low = nm.toLowerCase()
+      if (low === want || squeeze(low) === flat) score = Math.max(score, 3)
+      else if (want.length >= 2 && low.includes(want)) score = Math.max(score, 2)
+      else if (flat.length >= 2 && squeeze(low).includes(flat)) score = Math.max(score, 2)
+      else if (low.length >= 3 && want.includes(low)) score = Math.max(score, 1)
+      if (score > 0 && name === '') name = nm
+    }
+    return { score, name }
+  }
+  const boxOf = (el) => {
+    for (let node = el; node; node = node.parentElement) {
+      const b = node.getBoundingClientRect()
+      if (b.width < 8 || b.height < 8) continue
+      const s = getComputedStyle(node)
+      if (s.display !== 'none' && s.visibility !== 'hidden' && Number(s.opacity) > 0.05) return b
+    }
+    return null
+  }
+  const bestOf = (selector, want, hiddenOk) => {
+    let best = null
+    for (const root of roots) {
+      for (const el of root.querySelectorAll(selector)) {
+        if (hiddenOk !== true && shown(el) !== true) continue
+        const hit = scored(el, want)
+        if (hit.score === 0) continue
+        if (best === null || hit.score > best.score) best = { el, score: hit.score, name: hit.name }
       }
-      if (score === 0) continue
-      if (best === null || score > best.score) best = { el, score, name }
     }
+    return best
   }
-  if (best === null) return JSON.stringify({})
+`
+
+/**
+ * The field a label belongs to, when nothing formally connects the two.
+ * ...
+ */
+/**
+ * The field a label belongs to, when nothing formally connects the two.
+ *
+ * `{field: "Email"}` used to mean "click the control that says Email". On a real
+ * form the words live in a div above a bare input, so the click landed on the
+ * text and the typing went wherever focus already was — the classic silent wrong
+ * field. This finds the *editable* element the words point at: a real label, an
+ * aria name, a placeholder, a name attribute, the text right before it, or the
+ * text of the small wrapper it sits in.
+ * @param {string} words - what the field is called.
+ * @returns {string} an expression that evaluates to a spot, or {} when nothing fits.
+ */
+export function labelSpot(words) {
+  const wanted = JSON.stringify(String(words ?? '').toLowerCase())
+  return `(() => {
+  const want = ${wanted}
+  if (want === '') return JSON.stringify({})
+  ${NAME_PRELUDE}
+  const selector = 'input,textarea,select,[contenteditable=""],[contenteditable=true],[role=textbox],[role=searchbox],[role=combobox]'
+  let best = bestOf(selector, want)
+  let box = best === null ? null : boxOf(best.el)
+  let behind = false
+  if (best === null || box === null) {
+    /* The field a date picker shows is often a transparent box over a styled
+       div: the input stays out of sight, but the words still name it. */
+    const under = bestOf(selector, want, true)
+    const place = under === null ? null : boxOf(under.el)
+    if (under !== null && place !== null) { best = under; box = place; behind = true }
+  }
+  if (best === null || box === null) return JSON.stringify({})
+  if (editable(best.el) !== true) return JSON.stringify({})
   best.el.scrollIntoView({ block: 'center', inline: 'nearest' })
-  const b = best.el.getBoundingClientRect()
-  return JSON.stringify({ x: Math.round(b.left + b.width / 2), y: Math.round(b.top + b.height / 2), name: best.name, score: best.score })
+  const fresh = boxOf(best.el) ?? box
+  return JSON.stringify({ x: Math.round(fresh.left + fresh.width / 2), y: Math.round(fresh.top + fresh.height / 2), name: best.name, score: best.score, behind })
+})()`
+}
+
+/**
+ * The dropdown the words belong to, with the wanted option already chosen.
+ * @param {string} words - what the dropdown is called on screen.
+ * @param {string} value - option label or value.
+ * @returns {string} an expression that picks the option and says what it did.
+ */
+export function selectSpot(words, value) {
+  const wanted = JSON.stringify(String(words ?? '').toLowerCase())
+  const wanted2 = JSON.stringify(String(value ?? ''))
+  return `(() => {
+  const want = ${wanted}
+  const wanted = ${wanted2}
+  if (want === '') return 'no dropdown was named'
+  ${NAME_PRELUDE}
+  const best = bestOf('select', want)
+  if (best === null) return 'no dropdown says ' + JSON.stringify(want)
+  const select = best.el
+  const option = Array.from(select.options).find((item) => item.value === wanted || item.text.trim() === wanted || item.text.trim().toLowerCase() === wanted.toLowerCase())
+  if (!option) return 'no option ' + wanted + ' in ' + best.name + '; options are ' + Array.from(select.options).slice(0, 12).map((item) => item.text.trim()).join(' | ')
+  select.value = option.value
+  select.dispatchEvent(new Event('input', { bubbles: true }))
+  select.dispatchEvent(new Event('change', { bubbles: true }))
+  return 'chose ' + option.text.trim() + ' in ' + best.name
 })()`
 }