acrylblends 0.7.7 → 0.8.0

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

@@ -0,0 +1,132 @@
+/** Builds a bounded, redacted accessibility snapshot of the page, with refs. */
+
+import { DEFAULT_SNAPSHOT_NODES, MAX_SNAPSHOT_NODES, UiControlError, type UiNode, type UiSnapshot } from '../protocol.ts'
+import { isHidden, levelOf, NAMED_BY_CONTENT, nameOf, roleOf, SHOWN_AS_VALUE, statesOf, TEXT_ROLE, textRun, valueOf } from './accessibility.ts'
+import type { RefTable } from './ref-table.ts'
+import { isProtected, isSensitive } from './sensitivity.ts'
+
+/** Marks the driver's own UI (the indicator), which a snapshot never lists. */
+export const DRIVER_UI_ATTRIBUTE = 'data-acryl-agent-control'
+
+/** The most elements one snapshot considers, however large the page. */
+const MAX_CANDIDATES = 5000
+
+
+interface Candidate {
+  readonly element: Element
+  readonly role: string
+  readonly name: string
+  readonly depth: number
+}
+
+/** True when the element (with layout) is at least partly inside the window; unknown layout counts as inside. */
+function inViewport(element: Element, view: Window | null): boolean {
+  if (view === null) return true
+  const rect = element.getBoundingClientRect()
+  if (rect.width === 0 && rect.height === 0) return true
+  return rect.bottom > 0 && rect.right > 0 && rect.top < view.innerHeight && rect.left < view.innerWidth
+}
+
+/**
+ * Every element with a role, and every run of visible text, in reading order. Text that is already a name (inside a button, a link, a
+ * heading, a label) is not listed again; a run is the text between two child elements, so `<p>Left: <b>24:59</b></p>` reads as
+ * `Left:` and `24:59`.
+ */
+function collect(root: Element): Candidate[] {
+  const found: Candidate[] = []
+  const walk = (element: Element, depth: number, named: boolean): void => {
+    if (found.length >= MAX_CANDIDATES) return
+    if (element.hasAttribute(DRIVER_UI_ATTRIBUTE)) return
+    const tag = element.tagName.toLowerCase()
+    if (tag === 'script' || tag === 'style' || tag === 'template' || tag === 'noscript') return
+    if (isHidden(element)) return
+    // A secret or payment field is not listed, and neither is anything inside a marked area.
+    if (isSensitive(element)) return
+    const role = roleOf(element)
+    let childDepth = depth
+    if (role !== null) {
+      found.push({ element, role, name: nameOf(element, role), depth })
+      childDepth = depth + 1
+    }
+    const inName = named || tag === 'label' || (role !== null && (NAMED_BY_CONTENT.has(role) || SHOWN_AS_VALUE.has(role)))
+    let run = ''
+    const flush = (): void => {
+      const text = textRun(run)
+      run = ''
+      if (text !== '' && !inName && found.length < MAX_CANDIDATES) found.push({ element, role: TEXT_ROLE, name: text, depth: childDepth })
+    }
+    for (const child of Array.from(element.childNodes)) {
+      if (child.nodeType === Node.TEXT_NODE) run += child.textContent ?? ''
+      else if (child instanceof Element) {
+        flush()
+        walk(child, childDepth, inName)
+      }
+    }
+    flush()
+  }
+  walk(root, 0, false)
+  return found
+}
+
+export interface SnapshotOptions {
+  readonly cursor?: number
+  readonly maxNodes?: number
+}
+
+/** Snapshots the page and remembers the full candidate list of the current generation, for paging. */
+export class SnapshotBuilder {
+  private candidates: Candidate[] = []
+
+  private readonly refs: RefTable
+  private readonly root: () => Element
+
+  constructor(refs: RefTable, root: () => Element) {
+    this.refs = refs
+    this.root = root
+  }
+
+  snapshot(options: SnapshotOptions = {}): UiSnapshot {
+    const max = Math.min(options.maxNodes ?? DEFAULT_SNAPSHOT_NODES, MAX_SNAPSHOT_NODES)
+    const root = this.root()
+    const view = root.ownerDocument.defaultView
+    let offset = options.cursor ?? 0
+    if (options.cursor === undefined) {
+      this.refs.begin()
+      const all = collect(root)
+      // What the user can see comes first, so a long page is cut from the bottom, not the middle of the window.
+      this.candidates = [...all.filter(c => inViewport(c.element, view)), ...all.filter(c => !inViewport(c.element, view))]
+      offset = 0
+    } else if (this.candidates.length === 0 || offset > this.candidates.length) {
+      throw new UiControlError('stale-ref', 'that page of the snapshot is gone; take a new snapshot')
+    }
+    const page = this.candidates.slice(offset, offset + max)
+    const nodes: UiNode[] = page.map((candidate) => {
+      const states = statesOf(candidate.element, candidate.role)
+      if (isProtected(candidate.element)) states.push('protected')
+      const value = valueOf(candidate.element, candidate.role)
+      const level = candidate.role === 'heading' ? levelOf(candidate.element) : undefined
+      return {
+        ref: this.refs.issue(candidate.element, candidate.role, candidate.name),
+        role: candidate.role,
+        name: candidate.name,
+        depth: candidate.depth,
+        states,
+        ...(value === undefined ? {} : { value }),
+        ...(level === undefined ? {} : { level }),
+      }
+    })
+    const end = offset + page.length
+    return {
+      generation: this.refs.generation,
+      title: root.ownerDocument.title,
+      nodes,
+      total: this.candidates.length,
+      ...(end < this.candidates.length ? { nextCursor: end } : {}),
+    }
+  }
+
+  /** Drop the remembered page list (with the refs). */
+  clear(): void {
+    this.candidates = []
+  }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * The door's page module (`main.ts` starts it; `<script type="module" src="/api/acryl-door/page.js"></script>` loads that). It drives this
+ * page's document for the agent (snapshots with refs, clicks, typing), answers the Host over the channel, and shows the indicator with
+ * the kill switch. It touches only this document, never another window and never the OS.
+ */
+
+import { PageChannel } from './channel.ts'
+import { UiDriver } from './driver/driver.ts'
+import { mountIndicator } from './indicator.ts'
+import { UserInputClock } from './user-input.ts'
+
+export const DOOR_BASE = '/api/acryl-door'
+
+/** Start the door on `document`. @returns the disposer. */
+export function startDoor(document: Document, base: string = DOOR_BASE): () => void {
+  const view = document.defaultView
+  if (view === null) throw new Error('acryl-door: the document has no window')
+  const clock = new UserInputClock()
+  const driver = new UiDriver({ document: () => document, msSinceUserInput: clock.msSince })
+  const windowId = typeof view.crypto?.randomUUID === 'function' ? view.crypto.randomUUID() : `w-${String(Date.now())}-${String(Math.random()).slice(2, 8)}`
+  const focused = (): boolean => document.visibilityState === 'visible' && document.hasFocus()
+  const detachInput = clock.attach(document)
+  const removeIndicator = mountIndicator(driver, document)
+  const channel = new PageChannel(driver, { windowId, focused, base })
+  const reportFocus = (): void => { channel.reportFocus(focused()) }
+  view.addEventListener('focus', reportFocus)
+  view.addEventListener('blur', reportFocus)
+  document.addEventListener('visibilitychange', reportFocus)
+  channel.connect()
+  return () => {
+    view.removeEventListener('focus', reportFocus)
+    view.removeEventListener('blur', reportFocus)
+    document.removeEventListener('visibilitychange', reportFocus)
+    channel.dispose()
+    removeIndicator()
+    detachInput()
+    // Pending calls settle as `unloaded` and every ref goes stale.
+    driver.dispose()
+  }
+}

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

@@ -0,0 +1,72 @@
+/**
+ * "The agent is driving" bar with its kill switch, in plain DOM (the React one in `acryl-agent-control` shows the same states). Shown while
+ * a call runs and after the person stopped the agent. It is marked as driver UI (so snapshots skip it) and as off limits to the agent (so
+ * it can never press its own Stop or Allow buttons). Escape stops the agent too, while it is working.
+ */
+
+import type { DriverActivity, UiDriver } from './driver/driver.ts'
+
+const LABELS: Record<string, string> = { snapshot: 'looking at the page', click: 'clicking', type: 'typing', select: 'choosing an option', press: 'pressing a key', scroll: 'scrolling', wait: 'waiting' }
+
+const STYLE_ID = 'acryl-door-indicator-style'
+const STYLES = `
+.acrylDoorBar { position: fixed; z-index: 2147483647; left: 50%; bottom: 16px; transform: translateX(-50%); display: flex; align-items: center; gap: 10px;
+  padding: 8px 12px; border-radius: 8px; font: 13px/1.4 system-ui, sans-serif; color: #fff; background: #1f2937; box-shadow: 0 4px 16px rgba(0,0,0,.25); }
+.acrylDoorBar[data-killed] { background: #7f1d1d; }
+.acrylDoorBar button { font: inherit; color: inherit; background: rgba(255,255,255,.15); border: 1px solid rgba(255,255,255,.35); border-radius: 6px; padding: 2px 10px; cursor: pointer; }
+.acrylDoorDot { width: 8px; height: 8px; border-radius: 50%; background: #34d399; }
+`
+
+/** Show the bar for `driver` in `document`. @returns the disposer, which removes the bar, its style and its listeners. */
+export function mountIndicator(driver: UiDriver, document: Document): () => void {
+  if (document.getElementById(STYLE_ID) === null) {
+    const style = document.createElement('style')
+    style.id = STYLE_ID
+    style.textContent = STYLES
+    document.head.append(style)
+  }
+  const bar = document.createElement('div')
+  bar.className = 'acrylDoorBar'
+  bar.setAttribute('data-acryl-agent-control', '')
+  bar.setAttribute('data-acryl-no-agent', '')
+  bar.setAttribute('role', 'status')
+  bar.setAttribute('aria-live', 'polite')
+
+  const onKey = (event: KeyboardEvent): void => {
+    if (event.key === 'Escape' && event.isTrusted && driver.activity.busy) driver.kill()
+  }
+  document.addEventListener('keydown', onKey, true)
+
+  const render = (activity: DriverActivity): void => {
+    if (!activity.busy && !activity.killed) { bar.remove(); return }
+    const button = document.createElement('button')
+    button.type = 'button'
+    const text = document.createElement('span')
+    if (activity.killed) {
+      bar.setAttribute('data-killed', '')
+      text.textContent = 'Agent stopped. It cannot use the page until you allow it.'
+      button.textContent = 'Allow again'
+      button.addEventListener('click', () => { driver.resume() })
+      bar.replaceChildren(text, button)
+    } else {
+      bar.removeAttribute('data-killed')
+      const dot = document.createElement('span')
+      dot.className = 'acrylDoorDot'
+      dot.setAttribute('aria-hidden', 'true')
+      text.textContent = `Agent is driving: ${LABELS[activity.doing] ?? activity.doing}`
+      button.textContent = 'Stop'
+      button.addEventListener('click', () => { driver.kill() })
+      bar.replaceChildren(dot, text, button)
+    }
+    if (!bar.isConnected) document.body.append(bar)
+  }
+  const unsubscribe = driver.subscribe(render)
+  render(driver.activity)
+
+  return () => {
+    unsubscribe()
+    document.removeEventListener('keydown', onKey, true)
+    bar.remove()
+    document.getElementById(STYLE_ID)?.remove()
+  }
+}

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

@@ -0,0 +1,7 @@
+/** The page's script: starts the door once on this document, even if the script tag appears twice. */
+
+import { startDoor } from './index.ts'
+
+const flag = '__acrylDoor'
+const host = globalThis as { [flag]?: () => void }
+if (host[flag] === undefined) host[flag] = startDoor(document)

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

@@ -0,0 +1,213 @@
+/**
+ * The one shape of a door call, shared by the Host and the in-page driver (moved from `acryl-agent-control`, spec 041).
+ *
+ * The Host turns a verb's arguments into a {@link UiRequest}, sends it to the page over the channel, and gets a {@link UiResult} back.
+ * Everything crossing the channel is validated here once, so neither side trusts the other's JSON. The page imports this file too, so it
+ * lives with the page code and has no Node imports.
+ */
+
+/** The operations the driver performs on the page. */
+export const UI_OPS = ['snapshot', 'click', 'type', 'select', 'press', 'scroll', 'wait'] as const
+export type UiOp = (typeof UI_OPS)[number]
+
+/** Operations that change the page, so each call needs approval. `snapshot`, `scroll` and `wait` only look. */
+export const MUTATING_OPS: readonly UiOp[] = ['click', 'type', 'select', 'press']
+
+export const MAX_TEXT_LENGTH = 10_000
+export const MAX_WAIT_MS = 10_000
+export const MAX_SNAPSHOT_NODES = 1000
+export const DEFAULT_SNAPSHOT_NODES = 300
+
+/** Why a call did not do what was asked. Every failure is one of these, never a silent wrong action. */
+export type UiErrorCode =
+  | 'no-window'        // no page of the app is connected
+  | 'stale-ref'        // the element changed or was replaced since the snapshot
+  | 'unknown-ref'      // the ref was never issued
+  | 'sensitive'        // a password, token, API key or payment field
+  | 'protected'        // a control the agent may never operate (policy, approval, this plugin)
+  | 'not-actionable'   // hidden, disabled, or the wrong kind of element for the action
+  | 'not-found'        // a wait ended without the thing appearing
+  | 'killed'           // the user pressed the kill switch
+  | 'timeout'          // the page did not answer in time
+  | 'aborted'          // the call was cancelled
+  | 'unloaded'         // the driver went away mid-call
+  | 'disconnected'     // the page's channel dropped while the call was in flight
+  | 'invalid'          // malformed request
+
+export class UiControlError extends Error {
+  readonly code: UiErrorCode
+
+  constructor(code: UiErrorCode, message: string) {
+    super(message)
+    this.code = code
+    this.name = 'UiControlError'
+  }
+}
+
+/** One element in a snapshot. */
+export interface UiNode {
+  /** `<generation>.<n>`; valid only until the next snapshot. */
+  readonly ref: string
+  readonly role: string
+  readonly name: string
+  readonly depth: number
+  /** Short state words: `disabled`, `checked`, `expanded`, `selected`, `focused`, `protected`, ... */
+  readonly states: readonly string[]
+  /** The text of an editable field, when it is not sensitive. */
+  readonly value?: string
+  /** Heading level, when it is a heading. */
+  readonly level?: number
+}
+
+export interface UiSnapshot {
+  readonly generation: number
+  readonly title: string
+  readonly nodes: readonly UiNode[]
+  /** How many elements matched in all; more than `nodes.length` when the page was cut. */
+  readonly total: number
+  /** Pass to the next snapshot call to continue, or absent when this is everything. */
+  readonly nextCursor?: number
+}
+
+export type UiRequest =
+  | { readonly op: 'snapshot'; readonly cursor?: number; readonly maxNodes?: number }
+  | { readonly op: 'click'; readonly ref: string }
+  | { readonly op: 'type'; readonly ref: string; readonly text: string; readonly submit?: boolean; readonly clear?: boolean }
+  | { readonly op: 'select'; readonly ref: string; readonly option: string }
+  | { readonly op: 'press'; readonly key: string; readonly ref?: string }
+  | { readonly op: 'scroll'; readonly direction: 'up' | 'down' | 'left' | 'right'; readonly ref?: string; readonly amount?: number }
+  | { readonly op: 'wait'; readonly text?: string; readonly role?: string; readonly name?: string; readonly gone?: boolean; readonly timeoutMs?: number }
+
+/** What the page did, and to which control (for the audit log and the approval prompt). */
+export interface UiActionResult {
+  readonly ok: true
+  readonly target?: { readonly role: string; readonly name: string }
+  readonly detail?: string
+}
+
+export type UiResult = UiSnapshot | UiActionResult
+
+/**
+ * Messages the page and the Host exchange over the channel. The Host sends calls down the page's event stream (`event: call`); the page
+ * opens that stream with its window id and focus, and sends everything else up by POST, naming its window id.
+ */
+export type ChannelToPage =
+  | { readonly t: 'call'; readonly id: number; readonly request: UiRequest }
+export type ChannelToHost =
+  | { readonly t: 'focus'; readonly focused: boolean }
+  | { readonly t: 'result'; readonly id: number; readonly value: UiResult }
+  | { readonly t: 'error'; readonly id: number; readonly code: UiErrorCode; readonly message: string }
+
+const KEYS = /^(?:[A-Za-z0-9]|Enter|Escape|Tab|Backspace|Delete|Space|Arrow(?:Up|Down|Left|Right)|Home|End|PageUp|PageDown)$/
+const REF = /^\d{1,9}\.\d{1,6}$/
+
+const isRecord = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value)
+const invalid = (message: string): never => { throw new UiControlError('invalid', message) }
+
+function ref(value: unknown): string {
+  if (typeof value !== 'string' || !REF.test(value)) return invalid('ref must look like 3.17, from the latest snapshot')
+  return value
+}
+
+function text(value: unknown, max = MAX_TEXT_LENGTH): string {
+  if (typeof value !== 'string' || value.length > max || value.includes('\0')) return invalid(`text must be a string of at most ${String(max)} characters`)
+  return value
+}
+
+/** @param value - untrusted JSON. @throws UiControlError `invalid`. */
+export function parseUiRequest(value: unknown): UiRequest {
+  if (!isRecord(value) || typeof value.op !== 'string') return invalid('a call needs an op')
+  const op = value.op as UiOp
+  const only = (allowed: readonly string[]): void => {
+    const extra = Object.keys(value).find(key => key !== 'op' && !allowed.includes(key))
+    if (extra !== undefined) invalid(`unknown field ${extra}`)
+  }
+  switch (op) {
+    case 'snapshot': {
+      only(['cursor', 'maxNodes'])
+      const cursor = value.cursor === undefined ? undefined : Number(value.cursor)
+      const maxNodes = value.maxNodes === undefined ? undefined : Number(value.maxNodes)
+      if ((cursor !== undefined && (!Number.isInteger(cursor) || cursor < 0)) || (maxNodes !== undefined && (!Number.isInteger(maxNodes) || maxNodes < 1 || maxNodes > MAX_SNAPSHOT_NODES))) return invalid('cursor and maxNodes must be small positive integers')
+      return { op, ...(cursor === undefined ? {} : { cursor }), ...(maxNodes === undefined ? {} : { maxNodes }) }
+    }
+    case 'click': only(['ref']); return { op, ref: ref(value.ref) }
+    case 'type': {
+      only(['ref', 'text', 'submit', 'clear'])
+      if ((value.submit !== undefined && typeof value.submit !== 'boolean') || (value.clear !== undefined && typeof value.clear !== 'boolean')) return invalid('submit and clear must be true or false')
+      return { op, ref: ref(value.ref), text: text(value.text), ...(value.submit === undefined ? {} : { submit: value.submit }), ...(value.clear === undefined ? {} : { clear: value.clear }) }
+    }
+    case 'select': only(['ref', 'option']); return { op, ref: ref(value.ref), option: text(value.option, 500) }
+    case 'press': {
+      only(['key', 'ref'])
+      if (typeof value.key !== 'string' || !KEYS.test(value.key)) return invalid('key must be a single character or a name such as Enter, Escape, Tab or ArrowDown')
+      return { op, key: value.key, ...(value.ref === undefined ? {} : { ref: ref(value.ref) }) }
+    }
+    case 'scroll': {
+      only(['direction', 'ref', 'amount'])
+      if (value.direction !== 'up' && value.direction !== 'down' && value.direction !== 'left' && value.direction !== 'right') return invalid('direction must be up, down, left or right')
+      const amount = value.amount === undefined ? undefined : Number(value.amount)
+      if (amount !== undefined && (!Number.isFinite(amount) || amount <= 0 || amount > 10_000)) return invalid('amount must be between 1 and 10000 pixels')
+      return { op, direction: value.direction, ...(value.ref === undefined ? {} : { ref: ref(value.ref) }), ...(amount === undefined ? {} : { amount }) }
+    }
+    case 'wait': {
+      only(['text', 'role', 'name', 'gone', 'timeoutMs'])
+      const timeoutMs = value.timeoutMs === undefined ? undefined : Number(value.timeoutMs)
+      if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > MAX_WAIT_MS)) return invalid(`timeoutMs must be between 0 and ${String(MAX_WAIT_MS)}`)
+      if (value.gone !== undefined && typeof value.gone !== 'boolean') return invalid('gone must be true or false')
+      if (value.text === undefined && value.role === undefined && value.name === undefined) return invalid('wait needs text, or a role and name')
+      return {
+        op,
+        ...(value.text === undefined ? {} : { text: text(value.text, 500) }),
+        ...(value.role === undefined ? {} : { role: text(value.role, 60) }),
+        ...(value.name === undefined ? {} : { name: text(value.name, 500) }),
+        ...(value.gone === undefined ? {} : { gone: value.gone }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+      }
+    }
+    default: return invalid(`unknown op ${String(op)}`)
+  }
+}
+
+/** @param text - one `call` event's data from the Host. @throws when it is not a well-formed call. */
+export function parseChannelToPage(text: string): ChannelToPage {
+  const value: unknown = JSON.parse(text)
+  if (isRecord(value) && value.t === 'call' && typeof value.id === 'number' && Number.isSafeInteger(value.id)) {
+    return { t: 'call', id: value.id, request: parseUiRequest(value.request) }
+  }
+  throw new UiControlError('invalid', 'not a channel call')
+}
+
+/** Every code a {@link UiControlError} can carry, so a code read off the wire is validated, not cast. */
+export const UI_ERROR_CODES: readonly UiErrorCode[] = ['no-window', 'stale-ref', 'unknown-ref', 'sensitive', 'protected', 'not-actionable', 'not-found', 'killed', 'timeout', 'aborted', 'unloaded', 'disconnected', 'invalid']
+
+/** A window id the page chose: short, printable, so it can travel in a query string and a log line. */
+export const WINDOW_ID = /^[A-Za-z0-9-]{1,80}$/u
+
+/** @param value - one parsed message from the page; null when it is not a well-formed message. */
+export function parseChannelToHost(value: unknown): ChannelToHost | null {
+  if (!isRecord(value)) return null
+  if (value.t === 'focus' && typeof value.focused === 'boolean') return { t: 'focus', focused: value.focused }
+  if (value.t === 'result' && typeof value.id === 'number' && isRecord(value.value)) return { t: 'result', id: value.id, value: value.value as unknown as UiResult }
+  if (value.t === 'error' && typeof value.id === 'number' && typeof value.message === 'string' && UI_ERROR_CODES.includes(value.code as UiErrorCode)) {
+    return { t: 'error', id: value.id, code: value.code as UiErrorCode, message: value.message.slice(0, 500) }
+  }
+  return null
+}
+
+/** One line of the audit log: what the agent did, never what it typed. */
+export interface AuditEntry {
+  /** ISO time of the call. */
+  readonly at: string
+  readonly tool: string
+  /** The control touched, when the call had one. */
+  readonly target?: { readonly role: string; readonly name: string }
+  readonly outcome: 'ok' | 'refused' | 'failed'
+  /** The error code for a refusal or failure, or a short note for a success. */
+  readonly detail?: string
+  /**
+   * Whether the user was asked first (`asked`), approval was switched off (`none`), the call needed no
+   * approval (`not-needed`), or it came from an operator holding this run's secret (`token`, spec 041 TB30): authorized by the secret,
+   * which only the OS user who started the app can read, and watched by the person at the page through the indicator and its kill switch.
+   */
+  readonly approval: 'asked' | 'none' | 'not-needed' | 'token'
+}

package/plugins/acryl-door/src/page/snapshot-text.ts

@@ -0,0 +1,18 @@
+/** How a snapshot reads to an agent. Pure text, shared by the Host and the tests (no DOM). */
+
+import type { UiSnapshot } from './protocol.ts'
+
+/**
+ * The snapshot as compact text for an agent: one line per element, indented by depth.
+ * @param more - how to ask for the rest when the page was cut, given the cursor to continue from.
+ */
+export function renderSnapshot(snapshot: UiSnapshot, more: (cursor: number) => string = cursor => `call ui_snapshot with cursor ${String(cursor)}`): string {
+  const lines = snapshot.nodes.map((node) => {
+    const level = node.level === undefined ? '' : ` level=${String(node.level)}`
+    const states = node.states.length === 0 ? '' : ` [${node.states.join(', ')}]`
+    const value = node.value === undefined ? '' : ` value=${JSON.stringify(node.value)}`
+    return `${'  '.repeat(Math.min(node.depth, 8))}- ${node.role}${node.name === '' ? '' : ` ${JSON.stringify(node.name)}`}${level}${states}${value} [ref=${node.ref}]`
+  })
+  const rest = snapshot.nextCursor === undefined ? '' : `\n(${String(snapshot.total - snapshot.nextCursor)} more elements; ${more(snapshot.nextCursor)})`
+  return `Page: ${snapshot.title || '(untitled)'}\nSnapshot ${String(snapshot.generation)}, ${String(snapshot.nodes.length)} of ${String(snapshot.total)} elements:\n${lines.join('\n')}${rest}`
+}

package/plugins/acryl-door/src/page/user-input.ts

@@ -0,0 +1,24 @@
+/** Tracks when the user last used the page, so the agent yields to them. */
+
+/** Events only a real person produces: a script's `dispatchEvent` is never `isTrusted`. */
+const USER_EVENTS = ['pointerdown', 'mousedown', 'keydown', 'wheel', 'touchstart'] as const
+
+export class UserInputClock {
+  private last = Number.NEGATIVE_INFINITY
+
+  private readonly now: () => number
+
+  constructor(now: () => number = () => Date.now()) {
+    this.now = now
+  }
+
+  /** Milliseconds since the user last touched the page; Infinity when they have not. */
+  msSince = (): number => (this.last === Number.NEGATIVE_INFINITY ? Number.POSITIVE_INFINITY : this.now() - this.last)
+
+  /** Start listening. @returns disposer. */
+  attach(target: Document): () => void {
+    const handler = (event: Event): void => { if (event.isTrusted) this.last = this.now() }
+    for (const type of USER_EVENTS) target.addEventListener(type, handler, { capture: true, passive: true })
+    return () => { for (const type of USER_EVENTS) target.removeEventListener(type, handler, { capture: true }) }
+  }
+}

package/plugins/acryl-door/upstream.json

@@ -0,0 +1,28 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-door",
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 13,
+  "digest": "sha256:90f0731ebb2e6d8a7c29e6f1e6f250cb2eb719b6622e5d9e5655281947584d6c",
+  "testsNotRun": {
+    "tests/page/accessible-name-hidden.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/page/channel.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/page/driver.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/page/indicator.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/page/visible-text.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/host/door.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/host/verbs.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/host/shim.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/host/loader.spec.ts": "loads the plugin through the real Loader (@deepseek-ai/cordis-plugin-loader), which generated apps do not install"
+  },
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-inspect/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-inspect",
-    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",

package/plugins/acryl-kv/plugin.json

@@ -7,6 +7,11 @@
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.4"
   },
-  "mount": "it is the port, not a service: a plugin declares inject: ['kv'] and imports the ctx.kv type from './plugins/acryl-kv/src/cordis.ts'; add acryl-kv-json (a file) or acryl-kv-db (your SQL database) to provide it",
-  "omit": ["src/conformance.ts", "**/*.test.*", "**/*.spec.*", "**/*.case.ts"]
+  "mount": "it is the port, not a service: a plugin declares inject: ['kv'] and imports the ctx.kv type from '../plugins/acryl-kv/src/cordis.ts'; add acryl-kv-json (a file) or acryl-kv-db (your SQL database) to provide it",
+  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"],
+  "imports": {
+    "#acryl-kv": "acryl-kv/src/index.ts",
+    "#acryl-kv/conformance": "acryl-kv/src/conformance.ts"
+  },
+  "suite": "src/conformance.ts"
 }