acrylblends 0.7.7 → 0.8.0

package/plugins/acryl-door/src/page/driver/accessibility.ts

@@ -0,0 +1,163 @@
+/** Roles, accessible names and states of DOM elements, in the small subset a snapshot needs. */
+
+import { isSensitive } from './sensitivity.ts'
+
+const INPUT_ROLES: Record<string, string> = {
+  checkbox: 'checkbox', radio: 'radio', button: 'button', submit: 'button', reset: 'button', image: 'button',
+  range: 'slider', number: 'spinbutton', search: 'searchbox', text: 'textbox', email: 'textbox', url: 'textbox', tel: 'textbox', password: 'textbox',
+}
+
+const LANDMARKS: Record<string, string> = { nav: 'navigation', main: 'main', aside: 'complementary', dialog: 'dialog', form: 'form' }
+
+/** ARIA roles an element may declare that the driver treats as interactive or structural. */
+const EXPLICIT_ROLES = new Set([
+  'button', 'link', 'tab', 'tabpanel', 'menu', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'checkbox', 'radio', 'switch', 'textbox',
+  'searchbox', 'combobox', 'listbox', 'option', 'slider', 'spinbutton', 'dialog', 'alertdialog', 'alert', 'status', 'navigation', 'main',
+  'heading', 'tree', 'treeitem', 'row', 'gridcell', 'tablist', 'toolbar', 'region', 'form', 'img',
+])
+
+/** @returns the element's role, or null when it is not something a snapshot lists. */
+export function roleOf(el: Element): string | null {
+  const explicit = el.getAttribute('role')?.trim().toLowerCase().split(/\s+/)[0]
+  if (explicit !== undefined && explicit !== '' && EXPLICIT_ROLES.has(explicit)) return explicit
+  const tag = el.tagName.toLowerCase()
+  if (tag === 'a') return el.hasAttribute('href') ? 'link' : null
+  if (tag === 'button' || tag === 'summary') return 'button'
+  if (tag === 'select') return (el as HTMLSelectElement).multiple ? 'listbox' : 'combobox'
+  if (tag === 'textarea') return 'textbox'
+  if (/^h[1-6]$/.test(tag)) return 'heading'
+  if (tag === 'img') return el.getAttribute('alt')?.trim() ? 'img' : null
+  if (tag === 'input') {
+    const type = (el.getAttribute('type') ?? 'text').toLowerCase()
+    if (type === 'hidden') return null
+    return INPUT_ROLES[type] ?? 'textbox'
+  }
+  if (el.hasAttribute('contenteditable') && el.getAttribute('contenteditable') !== 'false') return 'textbox'
+  // A form is only a landmark when it has a name; an unnamed one is noise in a snapshot.
+  if (tag === 'form') return el.hasAttribute('aria-label') || el.hasAttribute('aria-labelledby') ? 'form' : null
+  return LANDMARKS[tag] ?? null
+}
+
+/** Roles whose accessible name is the text they contain, so that text is not listed again on its own. */
+export const NAMED_BY_CONTENT: ReadonlySet<string> = new Set(['button', 'link', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'heading', 'switch', 'treeitem', 'checkbox', 'radio', 'alert', 'status'])
+
+/** Roles that show their content as a value (a field, a native select), so the text inside them is not listed on its own either. */
+export const SHOWN_AS_VALUE: ReadonlySet<string> = new Set(['textbox', 'searchbox', 'combobox', 'spinbutton'])
+
+export const collapse = (value: string): string => value.replace(/\s+/g, ' ').trim()
+export const clip = (value: string, max: number): string => (value.length > max ? `${value.slice(0, max - 1)}…` : value)
+
+/** The text a reader would hear: like `textContent`, but leaving out what is `aria-hidden` or `hidden` (a check mark, an icon glyph). */
+function readableText(root: Node): string {
+  const parts: string[] = []
+  const walk = (node: Node): void => {
+    if (node.nodeType === Node.TEXT_NODE) parts.push(node.textContent ?? '')
+    else if (!(node instanceof Element && (node.getAttribute('aria-hidden') === 'true' || node.hasAttribute('hidden')))) node.childNodes.forEach(walk)
+  }
+  // The element being named is never skipped itself; only what it contains.
+  root.childNodes.forEach(walk)
+  return parts.join('')
+}
+
+const textOf = (el: Element, max: number): string => clip(collapse(readableText(el)), max)
+
+/** The role of a run of visible text that is not already a control's name or a field's value: what an agent reads a value from. */
+export const TEXT_ROLE = 'text'
+
+/** The longest text run a snapshot carries. */
+export const MAX_TEXT = 200
+
+/** One run of text as a snapshot lists it: collapsed and clipped, empty when there is nothing to read. */
+export const textRun = (raw: string): string => clip(collapse(raw), MAX_TEXT)
+
+/** The runs of text directly inside an element (between its child elements), as a snapshot lists them. */
+export function textRunsOf(el: Element): string[] {
+  const runs: string[] = []
+  let run = ''
+  for (const child of Array.from(el.childNodes)) {
+    if (child.nodeType === Node.TEXT_NODE) run += child.textContent ?? ''
+    else if (child instanceof Element) { runs.push(textRun(run)); run = '' }
+  }
+  runs.push(textRun(run))
+  return runs.filter(text => text !== '')
+}
+
+/** ARIA-style accessible name, kept short. */
+export function nameOf(el: Element, role: string): string {
+  const aria = el.getAttribute('aria-label')?.trim()
+  if (aria !== undefined && aria !== '') return clip(collapse(aria), 120)
+  const by = el.getAttribute('aria-labelledby')
+  if (by !== null && by.trim() !== '') {
+    const joined = collapse(by.split(/\s+/).map(id => el.ownerDocument.getElementById(id)?.textContent ?? '').join(' '))
+    if (joined !== '') return clip(joined, 120)
+  }
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
+    const id = el.id
+    const explicit = id === '' ? null : el.ownerDocument.querySelector(`label[for="${CSS.escape(id)}"]`)
+    const wrapping = el.closest('label')
+    const label = explicit ?? wrapping
+    const labelText = label === null ? '' : collapse(readableText(label))
+    if (labelText !== '') return clip(labelText, 120)
+    if (el instanceof HTMLInputElement && (el.type === 'button' || el.type === 'submit' || el.type === 'reset') && el.value !== '') return clip(el.value, 120)
+    const placeholder = el.getAttribute('placeholder')?.trim()
+    if (placeholder !== undefined && placeholder !== '') return clip(placeholder, 120)
+  }
+  if (role === 'img') return clip(collapse(el.getAttribute('alt') ?? ''), 120)
+  if (NAMED_BY_CONTENT.has(role)) {
+    const text = textOf(el, 120)
+    if (text !== '') return text
+  }
+  if (role === 'alert' || role === 'status' || role === 'dialog' || role === 'alertdialog') {
+    const text = textOf(el, 160)
+    if (text !== '') return text
+  }
+  return clip(collapse(el.getAttribute('title') ?? ''), 120)
+}
+
+/** The state words a snapshot shows for an element. */
+export function statesOf(el: Element, role: string): string[] {
+  const states: string[] = []
+  const aria = (name: string): string | null => el.getAttribute(name)
+  if ((el as HTMLButtonElement).disabled === true || aria('aria-disabled') === 'true') states.push('disabled')
+  if (el instanceof HTMLInputElement && (el.type === 'checkbox' || el.type === 'radio')) { if (el.checked) states.push('checked') } else if (aria('aria-checked') === 'true') states.push('checked')
+  if (aria('aria-expanded') === 'true') states.push('expanded')
+  if (aria('aria-expanded') === 'false') states.push('collapsed')
+  if (aria('aria-selected') === 'true') states.push('selected')
+  if (aria('aria-pressed') === 'true') states.push('pressed')
+  if (aria('aria-current') !== null && aria('aria-current') !== 'false') states.push('current')
+  if (aria('aria-invalid') === 'true') states.push('invalid')
+  if ((el as HTMLInputElement).required === true || aria('aria-required') === 'true') states.push('required')
+  if ((el as HTMLInputElement).readOnly === true || aria('aria-readonly') === 'true') states.push('readonly')
+  if (el.ownerDocument.activeElement === el) states.push('focused')
+  void role
+  return states
+}
+
+/** The visible value of an editable field, or undefined when it is empty, not editable, or sensitive. */
+export function valueOf(el: Element, role: string): string | undefined {
+  if (role !== 'textbox' && role !== 'searchbox' && role !== 'combobox' && role !== 'spinbutton') return undefined
+  if (isSensitive(el)) return undefined
+  let value: string | undefined
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) value = el.value
+  else if (el instanceof HTMLSelectElement) value = el.selectedOptions[0]?.textContent ?? undefined
+  else if (el.hasAttribute('contenteditable')) value = el.textContent ?? undefined
+  return value === undefined || value === '' ? undefined : clip(value, 100)
+}
+
+/** Heading level, when the element is a heading. */
+export function levelOf(el: Element): number | undefined {
+  const explicit = Number(el.getAttribute('aria-level'))
+  if (Number.isInteger(explicit) && explicit >= 1 && explicit <= 6) return explicit
+  const match = /^h([1-6])$/.exec(el.tagName.toLowerCase())
+  return match === null ? undefined : Number(match[1])
+}
+
+/** Hidden from everyone: the driver skips it and everything inside it. */
+export function isHidden(el: Element): boolean {
+  if (el.hasAttribute('hidden') || el.getAttribute('aria-hidden') === 'true') return true
+  if (el instanceof HTMLInputElement && el.type === 'hidden') return true
+  const view = el.ownerDocument.defaultView
+  if (view === null) return false
+  const style = view.getComputedStyle(el)
+  return style.display === 'none' || style.visibility === 'hidden'
+}

package/plugins/acryl-door/src/page/driver/actions.ts

@@ -0,0 +1,186 @@
+/** The actions the driver performs on the page, each guarded by the same rules. */
+
+import { MAX_WAIT_MS, UiControlError, type UiActionResult, type UiRequest } from '../protocol.ts'
+import { isHidden, nameOf, roleOf } from './accessibility.ts'
+import type { RefTable } from './ref-table.ts'
+import { isProtected, isSensitive } from './sensitivity.ts'
+import { DRIVER_UI_ATTRIBUTE } from './snapshot.ts'
+
+type Request<Op extends UiRequest['op']> = Extract<UiRequest, { op: Op }>
+
+const EDITABLE_ROLES = new Set(['textbox', 'searchbox', 'spinbutton', 'combobox'])
+const POLL_MS = 50
+
+export interface ActionEnvironment {
+  readonly refs: RefTable
+  readonly document: () => Document
+  /** Resolves after `ms`; rejects when `signal` aborts. Injectable so tests need no real time. */
+  readonly sleep: (ms: number, signal: AbortSignal) => Promise<void>
+}
+
+const target = (role: string, name: string): { role: string; name: string } => ({ role, name })
+
+function effectivelyHidden(element: Element): boolean {
+  for (let node: Element | null = element; node !== null; node = node.parentElement) if (isHidden(node)) return true
+  return false
+}
+
+/** Everything an action checks before touching an element. */
+function prepare(env: ActionEnvironment, ref: string): { element: Element; role: string; name: string } {
+  const resolved = env.refs.resolve(ref)
+  const { element } = resolved
+  if (isSensitive(element)) throw new UiControlError('sensitive', 'that is a password, token or payment field; the agent does not read or type into it')
+  if (isProtected(element)) throw new UiControlError('protected', `"${resolved.name}" belongs to approval, permissions or Agent Control itself; only the user operates it`)
+  if (effectivelyHidden(element)) throw new UiControlError('not-actionable', `"${resolved.name}" is not visible`)
+  if ((element as HTMLButtonElement).disabled === true || element.getAttribute('aria-disabled') === 'true') {
+    throw new UiControlError('not-actionable', `"${resolved.name}" is disabled`)
+  }
+  return resolved
+}
+
+function mouse(element: Element, type: string): void {
+  element.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true }))
+}
+
+/** xterm.js reads neither the value of its input textarea nor a bare synthetic key: text arrives as a paste, and key handling reads the legacy `keyCode`. */
+function isTerminalInput(element: Element): boolean {
+  return element.classList.contains('xterm-helper-textarea')
+}
+
+function pasteInto(element: Element, text: string): void {
+  const clipboardData = new DataTransfer()
+  clipboardData.setData('text/plain', text)
+  element.dispatchEvent(new ClipboardEvent('paste', { clipboardData, bubbles: true, cancelable: true }))
+}
+
+const LEGACY_KEY_CODES: Readonly<Record<string, number>> = {
+  Backspace: 8, Tab: 9, Enter: 13, Escape: 27, ' ': 32, PageUp: 33, PageDown: 34, End: 35, Home: 36,
+  ArrowLeft: 37, ArrowUp: 38, ArrowRight: 39, ArrowDown: 40, Delete: 46,
+}
+
+function setNativeValue(element: HTMLInputElement | HTMLTextAreaElement, value: string): void {
+  const proto = element instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype
+  const setter = Object.getOwnPropertyDescriptor(proto, 'value')?.set
+  if (setter === undefined) element.value = value
+  else setter.call(element, value)
+}
+
+export function click(env: ActionEnvironment, request: Request<'click'>): UiActionResult {
+  const { element, role, name } = prepare(env, request.ref)
+  ;(element as HTMLElement).scrollIntoView?.({ block: 'nearest' })
+  ;(element as HTMLElement).focus?.()
+  mouse(element, 'mousedown')
+  mouse(element, 'mouseup')
+  ;(element as HTMLElement).click()
+  return { ok: true, target: target(role, name) }
+}
+
+export function typeText(env: ActionEnvironment, request: Request<'type'>): UiActionResult {
+  const { element, role, name } = prepare(env, request.ref)
+  if (!EDITABLE_ROLES.has(role) || (role === 'combobox' && element instanceof HTMLSelectElement)) {
+    throw new UiControlError('not-actionable', `"${name}" is a ${role}, not a text field; use select or click`)
+  }
+  if ((element as HTMLInputElement).readOnly === true || element.getAttribute('aria-readonly') === 'true') {
+    throw new UiControlError('not-actionable', `"${name}" is read-only`)
+  }
+  const clear = request.clear ?? true
+  ;(element as HTMLElement).focus?.()
+  if (isTerminalInput(element)) {
+    // A terminal has no text to clear: what is typed goes to the process that is running in it.
+    pasteInto(element, request.text)
+  } else if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+    setNativeValue(element, clear ? request.text : element.value + request.text)
+    element.dispatchEvent(new Event('input', { bubbles: true }))
+    element.dispatchEvent(new Event('change', { bubbles: true }))
+  } else {
+    element.textContent = clear ? request.text : (element.textContent ?? '') + request.text
+    element.dispatchEvent(new Event('input', { bubbles: true }))
+  }
+  if (request.submit === true) pressKey(env, { op: 'press', key: 'Enter', ref: request.ref })
+  return { ok: true, target: target(role, name), detail: `typed ${String(request.text.length)} characters` }
+}
+
+export function selectOption(env: ActionEnvironment, request: Request<'select'>): UiActionResult {
+  const { element, role, name } = prepare(env, request.ref)
+  if (!(element instanceof HTMLSelectElement)) throw new UiControlError('not-actionable', `"${name}" is a ${role}, not a select; click it and pick the option`)
+  const wanted = request.option.trim().toLowerCase()
+  const options = Array.from(element.options)
+  const match = options.find(option => option.value.toLowerCase() === wanted) ?? options.find(option => (option.textContent ?? '').trim().toLowerCase() === wanted)
+  if (match === undefined) throw new UiControlError('not-found', `"${name}" has no option "${request.option}"`)
+  if (match.disabled) throw new UiControlError('not-actionable', `the option "${request.option}" is disabled`)
+  element.value = match.value
+  element.dispatchEvent(new Event('input', { bubbles: true }))
+  element.dispatchEvent(new Event('change', { bubbles: true }))
+  return { ok: true, target: target(role, name), detail: `selected ${match.textContent?.trim() ?? match.value}` }
+}
+
+export function pressKey(env: ActionEnvironment, request: Request<'press'>): UiActionResult {
+  const doc = env.document()
+  let element: Element
+  let role: string
+  let name: string
+  if (request.ref !== undefined) {
+    ({ element, role, name } = prepare(env, request.ref))
+  } else {
+    element = doc.activeElement ?? doc.body
+    if (isSensitive(element)) throw new UiControlError('sensitive', 'the focused field is a password, token or payment field')
+    if (isProtected(element)) throw new UiControlError('protected', 'the focused control belongs to approval, permissions or Agent Control itself')
+    role = roleOf(element) ?? 'page'
+    name = roleOf(element) === null ? '' : nameOf(element, role)
+  }
+  const key = request.key === 'Space' ? ' ' : request.key
+  const keyCode = LEGACY_KEY_CODES[key]
+  const init = { key, bubbles: true, cancelable: true, ...(keyCode === undefined ? {} : { keyCode, which: keyCode }) }
+  ;(element as HTMLElement).focus?.()
+  const proceed = element.dispatchEvent(new KeyboardEvent('keydown', init))
+  if (proceed) {
+    // A synthetic key event does not do what a real one does, so the two defaults that matter are done here.
+    if ((key === 'Enter' || key === ' ') && (role === 'button' || role === 'link')) (element as HTMLElement).click()
+    else if (key === 'Enter' && element instanceof HTMLInputElement && element.form !== null) element.form.requestSubmit?.()
+  }
+  element.dispatchEvent(new KeyboardEvent('keyup', init))
+  return { ok: true, target: target(role, name), detail: `pressed ${request.key}` }
+}
+
+export function scroll(env: ActionEnvironment, request: Request<'scroll'>): UiActionResult {
+  const doc = env.document()
+  const amount = request.amount ?? 400
+  const dx = request.direction === 'left' ? -amount : request.direction === 'right' ? amount : 0
+  const dy = request.direction === 'up' ? -amount : request.direction === 'down' ? amount : 0
+  if (request.ref !== undefined) {
+    const { element, role, name } = env.refs.resolve(request.ref)
+    ;(element as HTMLElement).scrollBy?.({ left: dx, top: dy })
+    if (typeof (element as HTMLElement).scrollBy !== 'function') { element.scrollTop += dy; element.scrollLeft += dx }
+    return { ok: true, target: target(role, name), detail: `scrolled ${request.direction}` }
+  }
+  const view = doc.defaultView
+  view?.scrollBy?.({ left: dx, top: dy })
+  return { ok: true, detail: `scrolled the page ${request.direction}` }
+}
+
+/** True when something visible on the page matches `request`. */
+function present(env: ActionEnvironment, request: Request<'wait'>): boolean {
+  const doc = env.document()
+  const walk = (element: Element): boolean => {
+    if (element.hasAttribute(DRIVER_UI_ATTRIBUTE) || isHidden(element) || isSensitive(element)) return false
+    const role = roleOf(element)
+    if (request.role !== undefined || request.name !== undefined) {
+      if (role !== null && (request.role === undefined || role === request.role.toLowerCase()) && (request.name === undefined || nameOf(element, role).toLowerCase().includes(request.name.toLowerCase()))) return true
+    }
+    if (request.text !== undefined && element.children.length === 0 && (element.textContent ?? '').toLowerCase().includes(request.text.toLowerCase())) return true
+    return Array.from(element.children).some(walk)
+  }
+  return walk(doc.body)
+}
+
+export async function wait(env: ActionEnvironment, request: Request<'wait'>, signal: AbortSignal): Promise<UiActionResult> {
+  const budget = Math.min(request.timeoutMs ?? 3000, MAX_WAIT_MS)
+  let waited = 0
+  const wantGone = request.gone === true
+  for (;;) {
+    if (present(env, request) !== wantGone) return { ok: true, detail: wantGone ? 'it is gone' : 'it is there' }
+    if (waited >= budget) throw new UiControlError('not-found', wantGone ? 'it did not go away in time' : 'it did not appear in time')
+    await env.sleep(POLL_MS, signal)
+    waited += POLL_MS
+  }
+}

package/plugins/acryl-door/src/page/driver/driver.ts

@@ -0,0 +1,153 @@
+/**
+ * The in-page driver: takes one {@link UiRequest} and does it, under the rules.
+ *
+ * It owns the ref table, the kill switch, the yield-to-the-user rule and the "driving" activity the indicator
+ * shows. It touches only the document it is given, never another window and never the OS.
+ */
+
+import { UiControlError, MUTATING_OPS, type UiRequest, type UiResult } from '../protocol.ts'
+import { click, pressKey, scroll, selectOption, typeText, wait, type ActionEnvironment } from './actions.ts'
+import { RefTable } from './ref-table.ts'
+import { SnapshotBuilder } from './snapshot.ts'
+
+/** After the user touches the page, agent actions wait this long, so the user always wins. */
+const YIELD_MS = 400
+const MAX_YIELD_MS = 2000
+
+export interface DriverActivity {
+  /** True from the moment a call starts until it ends. */
+  readonly busy: boolean
+  /** What the agent is doing, for the indicator ("click", "type", ...). */
+  readonly doing: string
+  /** True after the user pressed the kill switch. */
+  readonly killed: boolean
+}
+
+export interface UiDriverOptions {
+  readonly document: () => Document
+  /** Milliseconds since the user last used the page (mouse, keyboard); Infinity when never. */
+  readonly msSinceUserInput?: () => number
+  readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>
+}
+
+function realSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) { reject(signal.reason); return }
+    const timer = setTimeout(() => { signal.removeEventListener('abort', onAbort); resolve() }, ms)
+    const onAbort = (): void => { clearTimeout(timer); reject(signal.reason) }
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+export class UiDriver {
+  private readonly refs = new RefTable()
+  private readonly snapshots: SnapshotBuilder
+  private readonly listeners = new Set<(activity: DriverActivity) => void>()
+  private readonly env: ActionEnvironment
+  private readonly stopAll = new Set<AbortController>()
+  private killedFlag = false
+  private disposed = false
+  private busyCount = 0
+  private doing = ''
+  private current: DriverActivity = { busy: false, doing: '', killed: false }
+
+  private readonly options: UiDriverOptions
+
+  constructor(options: UiDriverOptions) {
+    this.options = options
+    this.snapshots = new SnapshotBuilder(this.refs, () => options.document().body)
+    this.env = { refs: this.refs, document: options.document, sleep: options.sleep ?? realSleep }
+  }
+
+  /** The current activity; the same object until something changes, as a store snapshot must be. */
+  get activity(): DriverActivity {
+    return this.current
+  }
+
+  subscribe(listener: (activity: DriverActivity) => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /** The user pressed the kill switch: pending calls settle as `killed` and new ones are refused. */
+  kill(): void {
+    this.killedFlag = true
+    for (const controller of [...this.stopAll]) controller.abort(new UiControlError('killed', 'the user stopped the agent'))
+    this.refs.clear()
+    this.snapshots.clear()
+    this.emit()
+  }
+
+  /** The user allowed the agent to drive again. */
+  resume(): void {
+    this.killedFlag = false
+    this.emit()
+  }
+
+  /** The driver goes away: pending calls settle as `unloaded`; refs are gone. */
+  dispose(): void {
+    this.disposed = true
+    for (const controller of [...this.stopAll]) controller.abort(new UiControlError('unloaded', 'the driver was unloaded'))
+    this.refs.clear()
+    this.snapshots.clear()
+    this.listeners.clear()
+  }
+
+  /** @param signal - the Host cancelled the call. @throws UiControlError. */
+  async handle(request: UiRequest, signal?: AbortSignal): Promise<UiResult> {
+    if (this.disposed) throw new UiControlError('unloaded', 'the driver was unloaded')
+    if (this.killedFlag) throw new UiControlError('killed', 'the user stopped the agent; it cannot drive until they allow it again')
+    const controller = new AbortController()
+    this.stopAll.add(controller)
+    const onCancel = (): void => { controller.abort(new UiControlError('aborted', 'the call was cancelled')) }
+    signal?.addEventListener('abort', onCancel, { once: true })
+    this.busyCount += 1
+    this.doing = request.op
+    this.emit()
+    try {
+      if (MUTATING_OPS.includes(request.op)) await this.yieldToUser(controller.signal)
+      if (controller.signal.aborted) throw controller.signal.reason
+      return await this.run(request, controller.signal)
+    } catch (cause) {
+      if (cause instanceof UiControlError) throw cause
+      if (controller.signal.aborted && controller.signal.reason instanceof UiControlError) throw controller.signal.reason
+      throw new UiControlError('not-actionable', cause instanceof Error ? cause.message : 'the action failed')
+    } finally {
+      signal?.removeEventListener('abort', onCancel)
+      this.stopAll.delete(controller)
+      this.busyCount -= 1
+      if (this.busyCount === 0) this.doing = ''
+      this.emit()
+    }
+  }
+
+  private async run(request: UiRequest, signal: AbortSignal): Promise<UiResult> {
+    switch (request.op) {
+      case 'snapshot': return this.snapshots.snapshot({ ...(request.cursor === undefined ? {} : { cursor: request.cursor }), ...(request.maxNodes === undefined ? {} : { maxNodes: request.maxNodes }) })
+      case 'click': return click(this.env, request)
+      case 'type': return typeText(this.env, request)
+      case 'select': return selectOption(this.env, request)
+      case 'press': return pressKey(this.env, request)
+      case 'scroll': return scroll(this.env, request)
+      case 'wait': return wait(this.env, request, signal)
+    }
+  }
+
+  private async yieldToUser(signal: AbortSignal): Promise<void> {
+    const since = this.options.msSinceUserInput
+    if (since === undefined) return
+    let waited = 0
+    while (since() < YIELD_MS && waited < MAX_YIELD_MS) {
+      await this.env.sleep(100, signal)
+      waited += 100
+    }
+  }
+
+  private emit(): void {
+    const next: DriverActivity = { busy: this.busyCount > 0, doing: this.doing, killed: this.killedFlag }
+    if (next.busy === this.current.busy && next.doing === this.current.doing && next.killed === this.current.killed) return
+    this.current = next
+    const activity = next
+    for (const listener of [...this.listeners]) listener(activity)
+  }
+}

package/plugins/acryl-door/src/page/driver/ref-table.ts

@@ -0,0 +1,78 @@
+/**
+ * Refs: short-lived handles an agent uses to name an element.
+ *
+ * A ref is `<generation>.<n>`. Each snapshot starts a new generation and every older ref becomes stale, so a
+ * ref can never quietly point at a different element after the page changed. Even within a generation, a
+ * ref is honoured only while its element is still in the document and still has the role and name it had when
+ * the ref was issued; a re-rendered or replaced control is a typed `stale-ref`, never a click somewhere else.
+ */
+
+import { UiControlError } from '../protocol.ts'
+import { nameOf, roleOf, TEXT_ROLE, textRunsOf } from './accessibility.ts'
+
+interface Entry {
+  readonly element: WeakRef<Element>
+  readonly role: string
+  readonly name: string
+}
+
+export interface ResolvedRef {
+  readonly element: Element
+  readonly role: string
+  readonly name: string
+}
+
+export class RefTable {
+  private generationNumber = 0
+  private entries = new Map<number, Entry>()
+  private nextIndex = 1
+
+  get generation(): number {
+    return this.generationNumber
+  }
+
+  /** Start a new generation: every earlier ref is now stale. */
+  begin(): number {
+    this.generationNumber += 1
+    this.entries = new Map()
+    this.nextIndex = 1
+    return this.generationNumber
+  }
+
+  /** Forget everything (the driver is going away or was stopped). */
+  clear(): void {
+    this.begin()
+  }
+
+  issue(element: Element, role: string, name: string): string {
+    const index = this.nextIndex
+    this.nextIndex += 1
+    this.entries.set(index, { element: new WeakRef(element), role, name })
+    return `${String(this.generationNumber)}.${String(index)}`
+  }
+
+  /** @throws UiControlError `unknown-ref` or `stale-ref`. */
+  resolve(ref: string): ResolvedRef {
+    const [generationText, indexText] = ref.split('.')
+    const generation = Number(generationText)
+    const index = Number(indexText)
+    if (!Number.isInteger(generation) || !Number.isInteger(index)) throw new UiControlError('unknown-ref', `${ref} is not a ref`)
+    if (generation !== this.generationNumber) {
+      throw new UiControlError('stale-ref', `${ref} is from an earlier snapshot (the latest is ${String(this.generationNumber)}); take a new snapshot`)
+    }
+    const entry = this.entries.get(index)
+    if (entry === undefined) throw new UiControlError('unknown-ref', `${ref} was not in the snapshot`)
+    const element = entry.element.deref()
+    if (element === undefined || !element.isConnected) throw new UiControlError('stale-ref', `${ref} is no longer on the page; take a new snapshot`)
+    // The same node can be reused for something else after a re-render: check it is still what was listed.
+    if (entry.role === TEXT_ROLE) {
+      if (!textRunsOf(element).includes(entry.name)) throw new UiControlError('stale-ref', `${ref} changed since the snapshot ("${entry.name}" is no longer there); take a new snapshot`)
+      return { element, role: entry.role, name: entry.name }
+    }
+    const role = roleOf(element)
+    if (role !== entry.role || nameOf(element, role) !== entry.name) {
+      throw new UiControlError('stale-ref', `${ref} changed since the snapshot ("${entry.name}" is now something else); take a new snapshot`)
+    }
+    return { element, role: entry.role, name: entry.name }
+  }
+}

package/plugins/acryl-door/src/page/driver/sensitivity.ts

@@ -0,0 +1,49 @@
+/**
+ * What the agent may never see or type into, decided by rule and not by trusting the agent:
+ * secrets and payment fields (sensitive), and controls that govern the agent itself (protected).
+ */
+
+/** Field names and labels that mean a secret or a payment detail. */
+const SENSITIVE_WORDS = /pass(?:word|code|phrase)|secret|token|api[-_ ]?key|credential|private[-_ ]?key|\bpin\b|card|cvv|cvc|iban|routing|account[-_ ]?number|ssn|social[-_ ]?security|one[-_ ]?time|otp/i
+/** `autocomplete` values that browsers treat as credentials or payment data. */
+const SENSITIVE_AUTOCOMPLETE = /^(?:cc-|current-password|new-password|one-time-code)/
+
+const label = (el: Element, attr: string): string => el.getAttribute(attr) ?? ''
+
+/** True for a form field (or anything marked) that holds a secret or payment detail. */
+export function isSensitive(el: Element): boolean {
+  if (el.closest('[data-acryl-sensitive]') !== null) return true
+  if (!(el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement)) return false
+  if (el instanceof HTMLInputElement && el.type === 'password') return true
+  const autocomplete = label(el, 'autocomplete').trim().toLowerCase()
+  if (autocomplete.split(/\s+/).some(token => SENSITIVE_AUTOCOMPLETE.test(token))) return true
+  return SENSITIVE_WORDS.test([el.name, el.id, label(el, 'placeholder'), label(el, 'aria-label')].join(' '))
+}
+
+/** Areas whose controls the agent may look at but never operate. */
+const PROTECTED_REGION = /approval|permission|policy|agent control|ui control|acryl-agent-control|acryl-door|kill switch/i
+
+/** The text an ancestor uses to name itself, for region rules. */
+function ancestorName(el: Element): string {
+  const own = label(el, 'aria-label') || label(el, 'data-region') || ''
+  if (own !== '') return own
+  const labelled = label(el, 'aria-labelledby')
+  if (labelled !== '') {
+    return labelled.split(/\s+/).map(id => el.ownerDocument.getElementById(id)?.textContent ?? '').join(' ')
+  }
+  return ''
+}
+
+/**
+ * True for a control the agent must not operate: inside `[data-acryl-no-agent]`, inside a region whose
+ * name says approval, permission, policy or Agent Control, or itself named after switching Agent Control off.
+ */
+export function isProtected(el: Element): boolean {
+  if (el.closest('[data-acryl-no-agent]') !== null) return true
+  let node: Element | null = el
+  for (let depth = 0; node !== null && depth < 12; depth += 1) {
+    if (PROTECTED_REGION.test(ancestorName(node))) return true
+    node = node.parentElement
+  }
+  return false
+}