acrylblends 1.1.0 → 1.3.0

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

@@ -18,8 +18,9 @@ import { clientModules } from 'acryl-node-server/client-modules'
 import { auditPath, AuditLog } from './host/audit.ts'
 import { UiChannel } from './host/channel.ts'
 import { registerChatTools } from './host/chat-tools.ts'
-import { Door, type ExtensionsPort, type ToolsPort } from './host/door.ts'
-import { newSecret, removeDoorFile, stateDir, writeDoorFile } from './host/door-file.ts'
+import { PAGE_VERBS, VERBS } from './host/verbs.ts'
+import { Door, type ExtensionsPort, type PluginSharePort, type ToolsPort } from './host/door.ts'
+import { assertDoorIsFree, newSecret, removeDoorFile, stateDir, writeDoorFile } from './host/door-file.ts'
 import { DOOR_PREFIX, privateApi } from './host/http.ts'
 import { mcpRoutes } from './host/mcp-routes.ts'
 import { operatorRoutes } from './host/operator-routes.ts'
@@ -37,9 +38,10 @@ interface AppFolder {
   readonly name: string
 }
 
-/** The part of `acryl-node-server` the door reads: where the app listens. */
+/** The address the carrier listens on, as the `acrylWeb` service gives it (host and port; DSH's webServer serves it today). */
 interface Listening {
-  readonly url: string
+  readonly host: string
+  readonly port: number
 }
 
 declare module '@deepseek-ai/cordis' {
@@ -48,7 +50,17 @@ declare module '@deepseek-ai/cordis' {
   }
 }
 
-export const inject = ['router', 'appInstance', 'nodeServer']
+// Two hosts serve the same door. On DSH (slice 1 of the IDE port) the carrier's address comes from `acrylWeb`, upgrades from `routerHttp`, and the page script
+// goes into DSH's own index through the web server's index-inject hook (the framework's router.wrap never sees that page). On the plain node-server host the
+// address and upgrades come from `nodeServer`, and `router.wrap` adds the script. Only `router` and `appInstance` are required; a host without the optional
+// services simply takes the other path, so the door never stays PENDING beside a server that does not provide them.
+export const inject = ['router', 'appInstance']
+
+/** The services a host may provide in place of `acrylWeb`/`routerHttp` (the plain node-server host). */
+interface NodeServerLike {
+  readonly url?: string
+  upgrades?: () => UpgradeWebSocket
+}
 
 export interface Config {
   tools?: { expose?: string[] }
@@ -57,13 +69,34 @@ export interface Config {
    * run it in production (a packaged desktop app whose user drives it with an agent) says so here; `ACRYL_DOOR=off` still wins.
    */
   allowInProduction?: boolean
+  /**
+   * Page only, for a production assistant: the page channel and two chat tools, `door_look` and `door_act`, and nothing else - no operator routes, no MCP, no desktop
+   * shell channel, no `.acryl/` file, no plugin, tool or window verbs. The app's agent can then use the page for a visitor and cannot change the app. Runs in production
+   * without `allowInProduction`; `ACRYL_DOOR=off` still wins.
+   */
+  pageOnly?: boolean
   /** Reload the open pages after a live plugin change, so an agent that built a feature sees it on the page it has open. Default: true. */
   reloadOnChange?: boolean
+  /**
+   * Put the page script in the host's own index page (DSH's web UI) too, so an agent can drive that UI. Default: true. A host whose index is a frame
+   * around the app (the ACRYL Blends frame, whose centre shows the app's page) turns it off: the door then drives the app's page in the canvas, and an
+   * agent's `act navigate` or a reload after a plugin change never takes the person's tab out of the frame.
+   */
+  hostIndex?: boolean
+  /**
+   * The host prefix the app's pages are served under (the frame's canvas, `/app`); absent on the app's own server, where they are at the root. The
+   * door puts it on every page as `<meta name="acryl-app-base">`, and `act navigate` with an app path goes under it: a page the app serves at
+   * `/board` is reached at `/app/board` in the frame and at `/board` in production, and the same verb works in both.
+   */
+  appBase?: string
 }
 
 export const Config: z<Config> = z.object({
   allowInProduction: z.boolean().default(false).description('Run in production too (NODE_ENV=production); ACRYL_DOOR=off still turns it off.'),
+  pageOnly: z.boolean().default(false).description('Only the page and the look and act chat tools (a production assistant); runs in production.'),
   reloadOnChange: z.boolean().default(true).description('Reload the open pages after a plugin was added, removed or reloaded while the app runs.'),
+  hostIndex: z.boolean().default(true).description("Put the page script in the host's own index page too; off when that index is a frame around the app."),
+  appBase: z.string().default('').description('The prefix the app pages are served under (the frame canvas), without a trailing slash; empty at the root.'),
   tools: z.object({
     // Not a `door_` name: those are the door's own verbs in the registry, never offered back as app tools.
     expose: z.array(z.string().pattern(/^(?!door_)[A-Za-z][A-Za-z0-9_-]{0,63}$/u)).description('App tools (from the tools registry) the door offers; none by default.'),
@@ -107,24 +140,49 @@ export function notFoundPage(path: string, scriptTag: string): string {
 export function apply(ctx: Context, rawConfig: Config = {}): void {
   const config = Config(rawConfig)
   // Development only: nothing is started, mounted or written in production, or when switched off.
-  if (process.env.ACRYL_DOOR === 'off' || (process.env.NODE_ENV === 'production' && config.allowInProduction !== true)) return
+  const pageOnly = config.pageOnly === true
+  if (process.env.ACRYL_DOOR === 'off' || (process.env.NODE_ENV === 'production' && config.allowInProduction !== true && !pageOnly)) return
   const app = ctx.get('appInstance') as unknown as AppFolder
-  const server = ctx.get('nodeServer') as unknown as Listening
+  // The carrier, as the host provides it: DSH's `acrylWeb`, or the plain node server's own url. Read when used, never captured at apply time.
+  const carrier = (): Listening | undefined => {
+    const web = ctx.get('acrylWeb') as unknown as Listening | undefined
+    if (web !== undefined) return web
+    const node = ctx.get('nodeServer') as unknown as NodeServerLike | undefined
+    if (typeof node?.url !== 'string') return undefined
+    try {
+      const parsed = new URL(node.url)
+      return { host: parsed.hostname, port: Number(parsed.port) }
+    } catch {
+      return undefined
+    }
+  }
   if (typeof app?.root !== 'string') throw new Error('acryl-door: the appInstance service has no app folder (root)')
   const reportError = (operation: string, cause: unknown): void => {
     ctx.logger?.error?.(`acryl-door: failed to ${operation}: ${cause instanceof Error ? cause.message : String(cause)}`)
   }
+  const address: { url: string } = { url: '' }
+  // The rival check runs at activation, not in the deferred write: a folder another live process serves fails the row at once (the write waits for a bound port).
+  // A page-only door writes no file, so it has no rival to check.
+  if (!pageOnly) assertDoorIsFree(app.root)
   const secret = newSecret()
   // A look right after a navigate or reload waits up to two seconds for the page that is moving to register again, and a read-only call that no page acknowledged gives a page that just registered one more try.
-  const channel = new UiChannel({ attachWaitMs: 2000 })
+  // A page-only door serves every visitor of the app on one channel: each call goes to the page of the visitor whose run made it, never to another visitor's page.
+  const channel = new UiChannel({ attachWaitMs: 2000, requirePage: pageOnly })
   const shell = new ShellChannel()
   const audit = new AuditLog(auditPath(stateDir(app.root)))
+  // Where the app's pages answer under this host (`/app` in the frame): `act navigate` sends an app path there, and a page may read it from the
+  // head. The app's own server has no prefix and no meta.
+  const rawBase = typeof config.appBase === 'string' ? config.appBase.trim() : ''
+  const appBase = rawBase.startsWith('/') && rawBase !== '/' ? rawBase.replace(/\/+$/u, '') : ''
   const door = new Door({
     channel,
     shell,
     audit,
-    app: { name: app.name, root: app.root, url: loopbackUrl(server.url) },
+    // The address is read when it is used, not when the plugin applies: the carrier binds after the fiber starts (DSH's webServer reports its listening port only then).
+    app: { name: app.name, root: app.root, get url() { return address.url } },
+    ...(appBase === '' ? {} : { appBase }),
     extensions: () => ctx.get('extensions') as unknown as ExtensionsPort | undefined,
+    pluginShare: () => ctx.get('pluginShare') as unknown as PluginSharePort | undefined,
     tools: () => ctx.get('tools') as unknown as ToolsPort | undefined,
     expose: config.tools?.expose ?? [],
     reloadOnChange: config.reloadOnChange !== false,
@@ -134,10 +192,11 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
   // One script tag for the page (`page.js`): it imports the module tree served below it.
   const pageModule = new Acryl()
     .get(`${DOOR_PREFIX}/page.js`, c => c.body(`import '${DOOR_PREFIX}/page/main.ts'\n`, 200, { 'content-type': 'text/javascript; charset=utf-8' }))
-    .route(`${DOOR_PREFIX}/page`, clientModules({ root: PAGE_DIR }))
+    .route(`${DOOR_PREFIX}/page`, clientModules({ root: PAGE_DIR, mount: `${DOOR_PREFIX}/page` }))
   // The page script on every HTML page the app answers, whenever its plugin was mounted (the pages of a plugin that loaded at boot, before this one, included): a page an agent writes
-  // can be looked at and driven without anyone adding the tag. A page that already carries it (the templates' own pages) is left as it is. Development only, like the rest of the door.
+  // can be looked at and driven without anyone adding the tag. A page that already carries it keeps one copy. Development only, like the rest of the door.
   const tag = `<script type="module" src="${DOOR_PREFIX}/page.js"></script>`
+  const meta = appBase === '' ? '' : `<meta name="acryl-app-base" content="${appBase}">`
   const addScript = async (c: { res: Response; req: { path: string; header(name: string): string | undefined } }, next: () => Promise<void>): Promise<void> => {
     await next()
     if (!(c.res.headers.get('content-type') ?? '').includes('text/html')) {
@@ -147,48 +206,127 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
         c.res = new Response(notFoundPage(c.req.path, tag), { status: 404, headers: { 'content-type': 'text/html; charset=utf-8' } })
       return
     }
-    const html = await c.res.text()
+    let html = await c.res.text()
     const headers = new Headers(c.res.headers)
     headers.delete('content-length')
-    const carries = html.includes(`${DOOR_PREFIX}/page.js`)
-    c.res = new Response(carries ? html : html.includes('</body>') ? html.replace('</body>', `${tag}</body>`) : html + tag, { status: c.res.status, headers })
+    if (meta !== '' && !html.includes('name="acryl-app-base"'))
+      html = html.includes('</head>') ? html.replace('</head>', `${meta}</head>`) : meta + html
+    if (!html.includes(`${DOOR_PREFIX}/page.js`))
+      html = html.includes('</body>') ? html.replace('</body>', `${tag}</body>`) : html + tag
+    c.res = new Response(html, { status: c.res.status, headers })
   }
   const router = ctx.router as unknown as { wrap?: (middleware: typeof addScript) => unknown }
   // An app whose router copy is older than this plugin has no `wrap`: the middleware then covers the routes mounted after the door, as the agent panel's does.
   if (typeof router.wrap === 'function') router.wrap(addScript)
   else ctx.router.route('/', new Acryl().use('*', addScript as never))
-  // The page channel also runs over a WebSocket, which is not one of the browser's six connections per host. Without the `ws` package or an adapter that upgrades, the pages use the stream.
-  let upgrade: UpgradeWebSocket | undefined
-  try {
-    upgrade = (ctx as unknown as { nodeServer?: { upgrades?: () => UpgradeWebSocket } }).nodeServer?.upgrades?.()
-  } catch (cause) {
-    reportError('open the page channel over a WebSocket (the pages use the event stream)', cause)
+  // DSH's own index.html is not a framework route, so `router.wrap` never sees it: the tag goes in through the web server's index-inject hook instead. The
+  // tap is owned by this plugin's fiber, so unloading the door takes the tag with it, and the new activation's page routes answer under the new secret.
+  if (config.hostIndex !== false) ctx.inject(['webServer'], inner => {
+    inner.effect(() => {
+      const taps = inner.get('webServer') as unknown as { tapIndex?: (transform: (html: string) => string) => () => void } | undefined
+      if (typeof taps?.tapIndex !== 'function') return () => {}
+      return taps.tapIndex(html => {
+        if (html.includes(`${DOOR_PREFIX}/page.js`)) return html
+        return html.includes('</body>') ? html.replace('</body>', `${tag}</body>`) : html + tag
+      })
+    }, 'acryl-door: the page script in the host index')
+  })
+  // The page channel also runs over a WebSocket, which is not one of the browser's six connections per host. Without `ws` or an adapter that
+  // upgrades, the pages use the stream. The socket route is mounted ONCE here, ahead of the private routes, so it keeps its precedence when the host
+  // restarts; what moves is the upgrade helper it reads per request. While routerHttp exists its inject scope owns the prefix claim and sets the
+  // helper (Cordis disposes the claim exactly when the service goes away); the node server's hub is the helper only while routerHttp is absent.
+  // An upgrade while no helper is ready is refused 503 by the route, never answered twice.
+  let pageUpgrade: UpgradeWebSocket | undefined
+  let nodeUpgrade: UpgradeWebSocket | undefined
+  const endNodeOwner = (): void => {
+    if (pageUpgrade === nodeUpgrade) pageUpgrade = undefined
+    nodeUpgrade = undefined
+  }
+  const nodeFallback = (): void => {
+    if (ctx.get('routerHttp') !== undefined || nodeUpgrade !== undefined) return
+    try {
+      const allow = (ctx.get('nodeServer') as unknown as NodeServerLike | undefined)?.upgrades?.()
+      if (allow !== undefined) {
+        nodeUpgrade = allow
+        pageUpgrade = allow
+      }
+    } catch (cause) {
+      reportError('open the page channel over a WebSocket (the pages use the event stream)', cause)
+    }
   }
+  ctx.inject(['routerHttp'], (inner) => {
+    // The adapter is here: the node helper gives way, and this scope owns the prefix claim and the helper until Cordis disposes it with the service.
+    endNodeOwner()
+    const http = inner.get('routerHttp') as unknown as
+      | { upgrades?: () => UpgradeWebSocket; mount?: (prefix: string, options: { upgrade: string[] }) => () => void }
+      | undefined
+    try {
+      const allow = http?.upgrades?.()
+      if (allow === undefined || http === undefined || typeof http.mount !== 'function') return
+      pageUpgrade = allow
+      const remove = http.mount(DOOR_PREFIX, { upgrade: [`${DOOR_PREFIX}/channel/ws`] })
+      inner.effect(() => () => {
+        remove()
+        if (pageUpgrade === allow) pageUpgrade = undefined
+        nodeFallback()
+      }, 'acryl-door: the page socket via routerHttp')
+    } catch (cause) {
+      reportError('open the page channel over a WebSocket (the pages use the event stream)', cause)
+    }
+  })
+  ctx.inject(['nodeServer'], (inner) => {
+    inner.effect(() => {
+      nodeFallback()
+      const onService = inner.on as unknown as (name: string, listener: () => void) => () => void
+      const off = onService('internal/service', () => {
+        if (ctx.get('routerHttp') !== undefined) endNodeOwner()
+        else nodeFallback()
+      })
+      return () => {
+        off()
+        endNodeOwner()
+      }
+    }, 'acryl-door: the page socket on the node server')
+  })
+  ctx.router.route('/', pageSocketRoutes(channel, { prefix: DOOR_PREFIX, upgrade: () => pageUpgrade }))
   ctx.router.route('/', privateApi(
     DOOR_PREFIX,
     pageModule,
     pageChannelRoutes(channel, { prefix: DOOR_PREFIX }),
-    ...(upgrade === undefined ? [] : [pageSocketRoutes(channel, { prefix: DOOR_PREFIX, upgrade })]),
-    shellRoutes(DOOR_PREFIX, secret, shell),
-    operatorRoutes(DOOR_PREFIX, secret, door, reportError),
-    mcpRoutes(DOOR_PREFIX, secret, door, reportError),
+    ...(pageOnly ? [] : [
+      shellRoutes(DOOR_PREFIX, secret, shell),
+      operatorRoutes(DOOR_PREFIX, secret, door, reportError),
+      mcpRoutes(DOOR_PREFIX, secret, door, reportError),
+    ]),
   ))
   // The built-in chat's agent reads the `tools` registry: the verbs are in it while both are up.
   ctx.inject(['tools'], (inner) => {
-    inner.effect(() => registerChatTools(inner.get('tools') as unknown as ToolsPort, door), 'acryl-door: the verbs in the tools registry')
+    inner.effect(() => registerChatTools(inner.get('tools') as unknown as ToolsPort, door, pageOnly ? PAGE_VERBS : VERBS), 'acryl-door: the verbs in the tools registry')
   })
   ctx.effect(function* () {
     yield ctx.reflect.provide('door', door)
-    writeDoorFile(app.root, loopbackUrl(server.url), secret)
+  }, 'acryl-door: the door service')
+  // A page-only door leaves no file and no command for an operator.
+  if (pageOnly) return
+  // The carrier binds asynchronously (DSH's webServer, the node server before it): the address and the file are written once it reports a real port.
+  ctx.effect(async () => {
+    let bound = carrier()
+    for (let at = 0; at < 500 && (bound === undefined || !(bound.port > 0)); at += 1) {
+      await new Promise((done) => setTimeout(done, 10))
+      bound = carrier()
+    }
+    if (bound === undefined) throw new Error('acryl-door: no carrier bound the app (neither acrylWeb nor nodeServer answered)')
+    address.url = loopbackUrl(`http://${bound.host}:${String(bound.port)}`)
+    writeDoorFile(app.root, address.url, secret)
     // A shim that cannot be replaced (Windows, held open by a running `acryl`) leaves the old one in place; it must not stop the app from starting.
     try { writeShims(app.root, shimTarget()) } catch (cause) { reportError('write .acryl/bin', cause) }
-    yield () => { removeDoorFile(app.root, secret) }
-  }, 'acryl-door: the door service, .acryl/door.json and .acryl/bin/acryl')
+    return () => { removeDoorFile(app.root, secret) }
+  }, 'acryl-door: .acryl/door.json and .acryl/bin/acryl')
 }
 
 export { Door, DoorError, type VerbAnswer } from './host/door.ts'
-export { chatToolName, VERB_SPECS, VERBS, type Verb, type VerbSpec } from './host/verbs.ts'
+export { chatToolName, PAGE_VERBS, VERB_SPECS, VERBS, type Verb, type VerbSpec } from './host/verbs.ts'
 export { mcpTools } from './host/mcp-routes.ts'
 export { DOOR_PREFIX } from './host/http.ts'
-export { doorFilePath, readDoorFile, STATE_DIR, type DoorFile } from './host/door-file.ts'
+export { assertDoorIsFree, doorFilePath, readDoorFile, STATE_DIR, type DoorFile } from './host/door-file.ts'
 export type { CallResponse } from './host/operator-routes.ts'

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

@@ -0,0 +1,32 @@
+/**
+ * Where a host serves the app's pages under a prefix (the ACRYL frame's canvas, `/app`): the meta the door puts on each page, and where an app path
+ * lands under that prefix. Empty at the root, which is the app's own server.
+ */
+
+/**
+ * The one thing this file needs from a page's document. Spelled without DOM types so the Host imports `underAppBase` from here too, instead of keeping
+ * a second copy of the join; a real Document satisfies it.
+ */
+interface MetaHost {
+  querySelector(selectors: string): { getAttribute(name: string): string | null } | null
+}
+
+/** The app base a page carries (`<meta name="acryl-app-base">`, the host's prefix for the app); '' at the root. */
+export function appBaseOf(document: MetaHost): string {
+  const content = document.querySelector('meta[name="acryl-app-base"]')?.getAttribute('content')?.trim() ?? ''
+  return content.startsWith('/') && content !== '/' ? content.replace(/\/+$/u, '') : ''
+}
+
+/**
+ * `path` (an app path, optionally with a query) under `base`: '/board' under '/app' is '/app/board'; the app's root is the base itself, so '/' is
+ * '/app' (its mount) and not '/app/'; without a base, the path as written.
+ */
+export function underAppBase(base: string, path: string): string {
+  if (base === '') return path
+  const at = path.search(/[?#]/u)
+  const route = at === -1 ? path : path.slice(0, at)
+  const rest = at === -1 ? '' : path.slice(at)
+  if (route === base || route.startsWith(`${base}/`)) return path
+  if (route === '/' || route === '') return `${base}${rest}`
+  return `${base}${route.startsWith('/') ? '' : '/'}${route}${rest}`
+}

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

@@ -27,6 +27,8 @@ const BACKOFF_MAX_MS = 10_000
 
 export interface PageChannelOptions {
   readonly windowId: string
+  /** The browser tab the page is in (kept across the tab's reloads and moves), so the Host follows a run's page into the next document of its tab. */
+  readonly tab?: string
   /** The desktop window this page is in (`AcrylWindow/<n>` in the user agent, set by the Electron shell), so the Host can drive it by the number `window list` prints. */
   readonly shellWindow?: number
   readonly focused: () => boolean
@@ -70,7 +72,7 @@ export class PageChannel {
 
   connect(): void {
     if (this.disposed || this.source !== undefined) return
-    const query = `window=${encodeURIComponent(this.options.windowId)}&focused=${this.options.focused() ? '1' : '0'}${this.options.shellWindow === undefined ? '' : `&shell=${String(this.options.shellWindow)}`}`
+    const query = `window=${encodeURIComponent(this.options.windowId)}&focused=${this.options.focused() ? '1' : '0'}${this.options.shellWindow === undefined ? '' : `&shell=${String(this.options.shellWindow)}`}${this.options.tab === undefined ? '' : `&tab=${encodeURIComponent(this.options.tab)}`}`
     const viaSocket = this.socketAllowed
     this.socketReady = false
     const source: ChannelSource = viaSocket

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

@@ -147,6 +147,17 @@ export function valueOf(el: Element, role: string): string | undefined {
   return value === undefined || value === '' ? undefined : clip(value, 100)
 }
 
+/** Choices of a select listed at most; a longer list ends with how many more there are. */
+const MAX_OPTIONS = 20
+
+/** The choices of a native select (what `act select` takes), or undefined when it is not one or is sensitive. */
+export function optionsOf(el: Element): string[] | undefined {
+  if (!(el instanceof HTMLSelectElement) || isSensitive(el)) return undefined
+  const labels = [...el.options].filter(option => !option.hidden).map(option => clip((option.textContent ?? '').trim(), 60)).filter(label => label !== '')
+  if (labels.length <= MAX_OPTIONS) return labels
+  return [...labels.slice(0, MAX_OPTIONS), `(${String(labels.length - MAX_OPTIONS)} more)`]
+}
+
 /** Heading level, when the element is a heading. */
 export function levelOf(el: Element): number | undefined {
   const explicit = Number(el.getAttribute('aria-level'))

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

@@ -16,6 +16,8 @@ export interface ActionEnvironment {
   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>
+  /** Called with the element an act is about to use, so the page can show the person what the agent is touching. */
+  readonly touched?: (element: Element) => void
 }
 
 const target = (role: string, name: string): { role: string; name: string } => ({ role, name })
@@ -35,6 +37,7 @@ function prepare(env: ActionEnvironment, ref: string): { element: Element; role:
   if ((element as HTMLButtonElement).disabled === true || element.getAttribute('aria-disabled') === 'true') {
     throw new UiControlError('not-actionable', `"${resolved.name}" is disabled`)
   }
+  env.touched?.(element)
   return resolved
 }
 
@@ -149,6 +152,7 @@ export function scroll(env: ActionEnvironment, request: Request<'scroll'>): UiAc
   const dy = request.direction === 'up' ? -amount : request.direction === 'down' ? amount : 0
   if (request.ref !== undefined) {
     const { element, role, name } = env.refs.resolve(request.ref)
+    env.touched?.(element)
     ;(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}` }

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

@@ -27,11 +27,16 @@ export interface DriverActivity {
   readonly killed: boolean
 }
 
+/** How long after an act a navigation it started is still noticed (a link's navigation starts a task or two after the click). */
+const LEAVE_WATCH_MS = 50
+
 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>
+  /** Called with the element an act is about to use, for the page to show it (the door's outline on what the agent touches). */
+  readonly touched?: (element: Element) => void
   /** Leave the page: reload it, or go to a path of the app. Default: the document's own `location`, a moment after the answer is sent. */
   readonly leave?: (to: { readonly reload: true } | { readonly path: string }) => void
 }
@@ -63,7 +68,12 @@ export class UiDriver {
   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 }
+    this.env = {
+      refs: this.refs,
+      document: options.document,
+      sleep: options.sleep ?? realSleep,
+      ...(options.touched === undefined ? {} : { touched: options.touched }),
+    }
   }
 
   /** The current activity; the same object until something changes, as a store snapshot must be. */
@@ -142,10 +152,10 @@ export class UiDriver {
   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 'click': return await this.watchLeaving(() => click(this.env, request), signal)
+      case 'type': return await this.watchLeaving(() => typeText(this.env, request), signal)
       case 'select': return selectOption(this.env, request)
-      case 'press': return pressKey(this.env, request)
+      case 'press': return await this.watchLeaving(() => pressKey(this.env, request), signal)
       case 'scroll': return scroll(this.env, request)
       case 'wait': return wait(this.env, request, signal)
       case 'reload': return this.leave({ reload: true }, 'reloading')
@@ -153,6 +163,24 @@ export class UiDriver {
     }
   }
 
+  /**
+   * Run an act that may start a navigation (a click on a link, Enter in a form) and say so: the browser asks `beforeunload` when a navigation starts, during the act or a
+   * moment after it. The answer is sent before the page goes; the Host then waits for the next page instead of reading this one again.
+   */
+  private async watchLeaving(act: () => UiActionResult, signal: AbortSignal): Promise<UiActionResult> {
+    const view = this.options.document().defaultView
+    let leaving = false
+    const onLeave = (): void => { leaving = true }
+    view?.addEventListener('beforeunload', onLeave)
+    try {
+      const result = act()
+      if (!leaving) await this.env.sleep(LEAVE_WATCH_MS, signal)
+      return leaving ? { ...result, leaving: true, detail: `${result.detail === undefined ? '' : `${result.detail}; `}the page is going to another address` } : result
+    } finally {
+      view?.removeEventListener('beforeunload', onLeave)
+    }
+  }
+
   /**
    * The page is about to be replaced, so the answer is given first and the move happens a moment later (the answer is a POST that the page's own unload would cut off).
    * The Host does not wait for this answer to be the last word: it waits for the page to come back.

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

@@ -1,7 +1,7 @@
 /** 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 { isHidden, levelOf, NAMED_BY_CONTENT, nameOf, optionsOf, 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'
 
@@ -90,7 +90,8 @@ export class SnapshotBuilder {
     const root = this.root()
     const view = root.ownerDocument.defaultView
     let offset = options.cursor ?? 0
-    if (options.cursor === undefined) {
+    // Cursor 0 is the first page, which is a new snapshot: a model that passes it on its first look gets one instead of a stale-ref.
+    if (offset === 0) {
       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.
@@ -105,6 +106,7 @@ export class SnapshotBuilder {
       if (isProtected(candidate.element)) states.push('protected')
       const value = valueOf(candidate.element, candidate.role)
       const level = candidate.role === 'heading' ? levelOf(candidate.element) : undefined
+      const options = optionsOf(candidate.element)
       return {
         ref: this.refs.issue(candidate.element, candidate.role, candidate.name),
         role: candidate.role,
@@ -113,6 +115,7 @@ export class SnapshotBuilder {
         states,
         ...(value === undefined ? {} : { value }),
         ...(level === undefined ? {} : { level }),
+        ...(options === undefined ? {} : { options }),
       }
     })
     const end = offset + page.length

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

@@ -4,9 +4,11 @@
  * the kill switch. It touches only this document, never another window and never the OS.
  */
 
+import { appBaseOf, underAppBase } from './base.ts'
 import { PageChannel } from './channel.ts'
 import { UiDriver } from './driver/driver.ts'
 import { mountIndicator } from './indicator.ts'
+import { mountOutlines } from './outline.ts'
 import { UserInputClock } from './user-input.ts'
 
 export const DOOR_BASE = '/api/acryl-door'
@@ -14,14 +16,50 @@ export const DOOR_BASE = '/api/acryl-door'
 /** The key on the page's `window` under which the door publishes `{ windowId }`: the agent panel in the same page sends it with a question, and the door drives that page for the run. */
 export const PAGE_KEY = Symbol.for('acryl.door.page')
 
+/** Where the page keeps its tab's id: per tab, kept across reloads and moves within the app, never shared with another tab. */
+const TAB_KEY = 'acryl-door-tab'
+
+/**
+ * This tab's id: the page that replaces this one in the same tab (a reload, a move to another path) says the same, so the Host keeps driving that tab for a run asked from it.
+ * `undefined` when the browser keeps no session storage.
+ */
+function tabOf(view: Window): string | undefined {
+  try {
+    const kept = view.sessionStorage.getItem(TAB_KEY)
+    if (kept !== null && /^[A-Za-z0-9-]{8,80}$/u.test(kept)) return kept
+    const made = typeof view.crypto?.randomUUID === 'function' ? view.crypto.randomUUID() : undefined
+    if (made === undefined) return undefined
+    view.sessionStorage.setItem(TAB_KEY, made)
+    return made
+  } catch {
+    return undefined
+  }
+}
+
 /** 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 appBase = appBaseOf(document)
+  // The ring on whatever the agent touches, drawn in this page (the frame's canvas and production's assistant both get it).
+  const outlines = mountOutlines(document)
+  const driver = new UiDriver({
+    document: () => document,
+    msSinceUserInput: clock.msSince,
+    touched: (element) => { outlines.touched(element) },
+    // A host that serves the app under a prefix (the ACRYL frame's canvas) marks its pages: an app path navigates under that prefix, so the same
+    // `act navigate --path /board` reaches the app's /board in the frame and on the app's own server.
+    ...(appBase === '' ? {} : {
+      leave: (to: { readonly reload: true } | { readonly path: string }): void => {
+        if ('reload' in to) view.location.reload()
+        else view.location.assign(underAppBase(appBase, to.path))
+      },
+    }),
+  })
   const windowId = typeof view.crypto?.randomUUID === 'function' ? view.crypto.randomUUID() : `w-${String(Date.now())}-${String(Math.random()).slice(2, 8)}`
   Object.defineProperty(view, PAGE_KEY, { value: Object.freeze({ windowId }), configurable: true })
+  const tab = tabOf(view)
   const focused = (): boolean => document.visibilityState === 'visible' && document.hasFocus()
   const detachInput = clock.attach(document)
   const removeIndicator = mountIndicator(driver, document)
@@ -34,7 +72,7 @@ export function startDoor(document: Document, base: string = DOOR_BASE): () => v
       return 'auto'
     }
   })()
-  const channel = new PageChannel(driver, { windowId, focused, base, transport, onRun: running => { driver.setRunning(running) }, ...(Number.isSafeInteger(shellWindow) && shellWindow > 0 ? { shellWindow } : {}) })
+  const channel = new PageChannel(driver, { windowId, ...(tab === undefined ? {} : { tab }), focused, base, transport, onRun: running => { driver.setRunning(running) }, ...(Number.isSafeInteger(shellWindow) && shellWindow > 0 ? { shellWindow } : {}) })
   const reportFocus = (): void => { channel.reportFocus(focused()) }
   view.addEventListener('focus', reportFocus)
   view.addEventListener('blur', reportFocus)
@@ -54,6 +92,7 @@ export function startDoor(document: Document, base: string = DOOR_BASE): () => v
     Reflect.deleteProperty(view, PAGE_KEY)
     channel.dispose()
     removeIndicator()
+    outlines.dispose()
     detachInput()
     // Pending calls settle as `unloaded` and every ref goes stale.
     driver.dispose()

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

@@ -0,0 +1,56 @@
+/**
+ * A green ring on the element the agent just used, for a moment (docs/design/blends-frame-mockup.html outlines the "My tasks" the assistant opened). It is
+ * drawn here, in the page itself, so the person sees what the agent touched in the frame's canvas and in production's assistant alike, and so it goes on its
+ * own: nothing outside the page has to draw it, position it, or take it away.
+ */
+
+const STYLE_ID = 'acryl-door-outline-style'
+/** The class the ring is drawn with: the page's element keeps its own styles, and an outline follows the element's shape. */
+const CLASS = 'acrylDoorOutline'
+/** How long the ring stays after the agent's last act; each act replaces it, so one run leaves one ring, a moment after its last step. */
+export const OUTLINE_MS = 2000
+
+const STYLES = `.${CLASS} { outline: 2px solid #3fb67b !important; outline-offset: 1px; }`
+
+export interface Outlines {
+  /** Ring `element` as what the agent just used; the previous ring goes. */
+  touched(element: Element): void
+  /** Take the ring off and remove the style: nothing of this remains in the page. */
+  dispose(): void
+}
+
+/** Draw the ring in `document`. @returns the control the driver calls, and the disposer that leaves the page as it was. */
+export function mountOutlines(document: Document): Outlines {
+  if (document.getElementById(STYLE_ID) === null) {
+    const style = document.createElement('style')
+    style.id = STYLE_ID
+    style.textContent = STYLES
+    document.head.append(style)
+  }
+  let ringed: Element | undefined
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const clear = (): void => {
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      timer = undefined
+    }
+    ringed?.classList.remove(CLASS)
+    ringed = undefined
+  }
+  return {
+    touched(element: Element): void {
+      // The same control again in one run keeps its ring where it is; the person sees one ring, not a flicker.
+      if (element !== ringed) {
+        ringed?.classList.remove(CLASS)
+        ringed = element
+        element.classList.add(CLASS)
+      }
+      if (timer !== undefined) clearTimeout(timer)
+      timer = setTimeout(clear, OUTLINE_MS)
+    },
+    dispose(): void {
+      clear()
+      document.getElementById(STYLE_ID)?.remove()
+    },
+  }
+}