acrylblends 1.1.0 → 1.2.0

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

@@ -6,6 +6,7 @@
 
 import { existsSync } from 'node:fs'
 import { isAbsolute, relative, resolve } from 'node:path'
+import { underAppBase } from '../page/base.ts'
 import { parseUiRequest, UiControlError, type AuditEntry, type UiActionResult, type UiRequest, type UiResult, type UiSnapshot } from '../page/protocol.ts'
 import { renderSnapshot } from '../page/snapshot-text.ts'
 import type { AuditLog } from './audit.ts'
@@ -37,7 +38,7 @@ export interface ExtensionsPort {
 /** The slice of acrylblends' `tools` registry (the `agent` plugin's) the tool verbs use, and where the built-in chat finds the verbs. */
 export interface ToolsPort {
   /** @returns the function that removes the tool. @throws when the name is taken. */
-  register(name: string, tool: { readonly description: string; readonly parameters?: Readonly<Record<string, unknown>>; run(input: unknown): unknown }): () => void
+  register(name: string, tool: { readonly description: string; readonly parameters?: Readonly<Record<string, unknown>>; run(input: unknown, options?: { signal?: AbortSignal; page?: string }): unknown }): () => void
   list(): ReadonlyArray<{ readonly name: string; readonly description: string }>
   call(name: string, input: unknown): Promise<unknown>
 }
@@ -49,6 +50,8 @@ export interface DoorDeps {
   readonly audit: AuditLog
   /** The app's name, folder and, when it listens, its address (what `brief` prints so an agent can curl the running app). */
   readonly app: { readonly name: string; readonly root: string; readonly url?: string | undefined }
+  /** The prefix the app's pages answer under (the frame's canvas, `/app`); absent on the app's own server, at the root. */
+  readonly appBase?: string | undefined
   /** Read at each call: the services may come and go while the door runs. */
   readonly extensions: () => ExtensionsPort | undefined
   readonly tools: () => ToolsPort | undefined
@@ -60,6 +63,11 @@ export interface DoorDeps {
   readonly pageBackMs?: number
 }
 
+/** Who a verb runs for: `page`, the door's id of the page a run was asked from; its look and act go to that page alone (followed into its tab), never to another one. */
+export interface VerbScope {
+  readonly page?: string
+}
+
 /** What one verb answered: the value for `--json` and programs, the text for an agent reading a terminal. */
 export interface VerbAnswer {
   readonly value: unknown
@@ -96,16 +104,16 @@ export class Door {
   }
 
   /** Run one verb. @throws DoorError or UiControlError. */
-  async run(verb: string, args: unknown, signal: AbortSignal): Promise<VerbAnswer> {
+  async run(verb: string, args: unknown, signal: AbortSignal, scope: VerbScope = {}): Promise<VerbAnswer> {
     const input = (typeof args === 'object' && args !== null && !Array.isArray(args) ? args : {}) as Record<string, unknown>
     switch (verb) {
       case 'brief': return this.brief()
       case 'look': {
-        const snapshot = await this.look(input, signal)
+        const snapshot = await this.look(input, signal, scope)
         return { value: snapshot, text: renderSnapshot(snapshot, cursor => `run look --cursor ${String(cursor)}`) }
       }
       case 'act': {
-        const result = await this.act(input, signal)
+        const result = await this.act(input, signal, scope)
         return { value: result, text: `done${result.target === undefined ? '' : `: ${result.target.role} "${result.target.name}"`}${result.detail === undefined ? '' : ` (${result.detail})`}; look again before the next act` }
       }
       case 'plugin-list': return this.plugin(extensions => extensions.list(), false)
@@ -151,30 +159,47 @@ export class Door {
     return { value, text }
   }
 
-  look(input: Record<string, unknown>, signal: AbortSignal): Promise<UiSnapshot> {
-    const { window, rest } = this.windowOf(input)
+  look(input: Record<string, unknown>, signal: AbortSignal, scope: VerbScope = {}): Promise<UiSnapshot> {
+    const { window, rest } = this.windowOf(input, scope)
     const request = this.parse({ ...rest, op: 'snapshot' })
-    return this.callPage('look', request, signal, window) as Promise<UiSnapshot>
+    return this.callPage('look', request, signal, window, scope.page) as Promise<UiSnapshot>
   }
 
-  async act(input: Record<string, unknown>, signal: AbortSignal): Promise<UiActionResult> {
+  async act(input: Record<string, unknown>, signal: AbortSignal, scope: VerbScope = {}): Promise<UiActionResult> {
     if (input.op === 'snapshot') throw new DoorError('invalid', 'use look to see the page')
-    const { window, rest } = this.windowOf(input)
+    const { window, rest } = this.windowOf(input, scope)
     const request = this.parse(rest)
-    if (request.op !== 'reload' && request.op !== 'navigate') return await this.callPage(`act ${String(input.op)}`, request, signal, window) as UiActionResult
-    // The page is replaced: wait for the new one to connect, so the next look sees it. The page may drop before it has answered; that is the reload working.
-    const back = this.deps.channel.expectNewPage(this.deps.pageBackMs ?? PAGE_BACK_MS)
+    const page = scope.page
+    // A reload or a navigate replaces the page; a click, a key or typing may (a link, a form that submits), and the page says so when it does.
+    const moves = request.op === 'reload' || request.op === 'navigate'
+    if (!moves && request.op !== 'click' && request.op !== 'press' && request.op !== 'type')
+      return await this.callPage(`act ${String(input.op)}`, request, signal, window, page) as UiActionResult
+    // Wait for the new page to connect, so the next look sees it; the wait starts before the act, or a fast page is missed. The page may drop before it has answered;
+    // that is the move working. A run's own page comes back in its own tab; no other page that happens to connect meanwhile is taken for it.
+    const backMs = this.deps.pageBackMs ?? PAGE_BACK_MS
+    const stay = new AbortController()
+    const back = page === undefined ? this.deps.channel.expectNewPage(backMs, stay.signal) : this.deps.channel.expectPageBack(page, backMs, stay.signal)
     let answer: UiActionResult
+    let left = moves
     try {
-      answer = await this.callPage(`act ${request.op}`, request, signal, window) as UiActionResult
+      answer = await this.callPage(`act ${request.op}`, request, signal, window, page) as UiActionResult
+      left ||= answer.leaving === true
     } catch (cause) {
-      if (!(cause instanceof UiControlError && cause.code === 'disconnected')) { void back; throw cause }
-      answer = { ok: true, detail: request.op === 'reload' ? 'reloading' : `going to ${request.path}` }
+      if (!(cause instanceof UiControlError && cause.code === 'disconnected')) { stay.abort(); throw cause }
+      answer = { ok: true, detail: request.op === 'reload' ? 'reloading' : request.op === 'navigate' ? `going to ${request.path}` : 'the page is going to another address' }
+      left = true
+    }
+    if (!left) {
+      stay.abort()
+      return answer
     }
     const came = await back
-    // The page that came back is the one this agent was driving: it stays the target until the person focuses another page.
-    if (came !== undefined) this.deps.channel.prefer(came)
-    if (came === undefined) throw new UiControlError('timeout', request.op === 'reload' ? 'the page did not come back after the reload' : `the page did not come back after going to ${request.path}: is there a page at that path, and does it load the door's script?`)
+    // The page that came back is the one this agent was driving: it stays the target until the person focuses another page. A run that names its page follows that page's tab instead.
+    if (came !== undefined && page === undefined) this.deps.channel.prefer(came)
+    if (came === undefined)
+      throw new UiControlError('timeout', request.op === 'reload' ? 'the page did not come back after the reload'
+        : request.op === 'navigate' ? `the page did not come back after going to ${request.path}: is there a page at that path, and does it load the door's script?`
+        : `the ${request.op} took the page to another address, and no page came back: does the page there load the door's script?`)
     const landed = request.op === 'navigate' ? await this.statusAt(request.path) : undefined
     return { ...answer, detail: `${answer.detail ?? 'done'}${landed === undefined ? '' : `; ${landed}`}; the page is back: look again` }
   }
@@ -187,7 +212,10 @@ export class Door {
     const base = this.deps.app.url
     if (base === undefined) return undefined
     try {
-      const response = await fetch(new URL(path, base), { headers: { accept: 'text/html' }, signal: AbortSignal.timeout(3000) })
+      // The app's own path, under the host prefix when the pages answer there (the frame's canvas): /board is /app/board in the canvas and /board at the
+      // root, and the app's root is the prefix itself (`/app`, where its rows mount `/`), as the page's navigation join does it.
+      const target = underAppBase(this.deps.appBase ?? '', path)
+      const response = await fetch(new URL(target, base), { headers: { accept: 'text/html' }, signal: AbortSignal.timeout(3000) })
       await response.body?.cancel()
       return response.ok ? `${response.status} at ${path}` : `${response.status} at ${path}: the app serves no page there, look at what is shown and navigate to a path it does`
     } catch {
@@ -237,9 +265,11 @@ export class Door {
   }
 
   /** `window` on look and act: the desktop window (the number `window list` prints) whose page the call is for; without it, the page used last. */
-  private windowOf(input: Record<string, unknown>): { window: number | undefined; rest: Record<string, unknown> } {
+  private windowOf(input: Record<string, unknown>, scope: VerbScope = {}): { window: number | undefined; rest: Record<string, unknown> } {
     const { window, ...rest } = input
     if (window === undefined) return { window: undefined, rest }
+    // A run that is for one page cannot be pointed at a desktop window instead.
+    if (scope.page !== undefined) throw new DoorError('invalid', 'this run drives only the page it was asked from; window does not apply')
     if (typeof window !== 'number' || !Number.isSafeInteger(window) || window < 1) throw new DoorError('invalid', 'window must be the number `window list` prints for the window')
     return { window, rest }
   }
@@ -253,10 +283,10 @@ export class Door {
   }
 
   /** Run one call on the page and record it. The audit holds which control was touched and how it ended, never what was typed. */
-  private async callPage(verb: string, request: UiRequest, signal: AbortSignal, window?: number): Promise<UiResult> {
+  private async callPage(verb: string, request: UiRequest, signal: AbortSignal, window?: number, page?: string): Promise<UiResult> {
     const approval: AuditEntry['approval'] = 'token'
     try {
-      const value = await this.deps.channel.call(request, { signal, ...(window === undefined ? {} : { window }), ...(request.op === 'wait' ? { timeoutMs: (request.timeoutMs ?? 3000) + 5000 } : {}) })
+      const value = await this.deps.channel.call(request, { signal, ...(window === undefined ? {} : { window }), ...(page === undefined ? {} : { page }), ...(request.op === 'wait' ? { timeoutMs: (request.timeoutMs ?? 3000) + 5000 } : {}) })
       const target = 'target' in value ? value.target : undefined
       this.deps.audit.record({ at: new Date().toISOString(), tool: verb, ...(target === undefined ? {} : { target }), ...(window === undefined ? {} : { window }), outcome: 'ok', approval })
       return value
@@ -270,7 +300,7 @@ export class Door {
 
   private async plugin(run: (extensions: ExtensionsPort) => unknown, mutates = true): Promise<VerbAnswer> {
     const extensions = this.deps.extensions()
-    if (extensions === undefined) throw new DoorError('unavailable', 'this app has no extensions plugin, so plugins cannot be installed while it runs')
+    if (extensions === undefined) throw new DoorError('unavailable', 'this door has no extensions plugin to drive. In ACRYL\'s frame none is needed: a saved change in src/ or plugins/ reloads the app by itself, so do not restart it. Elsewhere, the app has no way to install plugins while it runs')
     const value = await run(extensions)
     // The app changed under the open pages: reload them (not when the plugin was already as it should be), and answer once they are back.
     const unchanged = typeof value === 'object' && value !== null && (value as { action?: unknown }).action === 'unchanged'

package/plugins/acryl-door/src/host/page-routes.ts

@@ -34,6 +34,8 @@ export function pageChannelRoutes(channel: UiChannel, options: PageRoutesOptions
       const focused = c.req.query('focused') === '1'
       const shellQuery = Number(c.req.query('shell'))
       const shellWindow = Number.isSafeInteger(shellQuery) && shellQuery > 0 ? shellQuery : undefined
+      const tabQuery = c.req.query('tab')
+      const tab = tabQuery !== undefined && WINDOW_ID.test(tabQuery) ? tabQuery : undefined
       const signal = c.req.raw.signal
       return streamSSE(c, async (stream) => {
         let end = (): void => {}
@@ -43,7 +45,7 @@ export function pageChannelRoutes(channel: UiChannel, options: PageRoutesOptions
         const write = (event: string, data: string): void => {
           stream.writeSSE({ event, data }).catch(end)
         }
-        const detach = channel.attach(windowId, focused, { send: (data) => { write('call', data) }, notify: write, close: end }, shellWindow)
+        const detach = channel.attach(windowId, focused, { send: (data) => { write('call', data) }, notify: write, close: end }, shellWindow, tab)
         const beat = setInterval(() => { write('ping', '') }, heartbeatMs)
         try {
           write('ready', '')

package/plugins/acryl-door/src/host/page-socket.ts

@@ -9,7 +9,7 @@
  */
 
 import { Acryl, type MiddlewareHandler } from 'acryl-router'
-import type { UpgradeWebSocket } from 'acryl-router/helpers'
+import type { UpgradeWebSocket, WSEvents } from 'acryl-router/helpers'
 import { loopbackAuthority } from 'acryl-router/middleware'
 import { parseChannelToHost, WINDOW_ID } from '../page/protocol.ts'
 import type { UiChannel } from './channel.ts'
@@ -20,7 +20,8 @@ export const SOCKET_HEARTBEAT_MS = 15_000
 
 export interface PageSocketOptions {
   readonly prefix: string
-  readonly upgrade: UpgradeWebSocket
+  /** The live upgrade helper: the route is mounted once, so the helper is read per request (a restarting host has a new one). */
+  readonly upgrade: () => UpgradeWebSocket | undefined
   readonly heartbeatMs?: number
 }
 
@@ -39,14 +40,13 @@ export const ownOrigin: MiddlewareHandler = async (c, next) => {
 
 export function pageSocketRoutes(channel: UiChannel, options: PageSocketOptions): Acryl {
   const heartbeatMs = options.heartbeatMs ?? SOCKET_HEARTBEAT_MS
-  return new Acryl().get(
-    `${options.prefix}/channel/ws`,
-    ownOrigin,
-    options.upgrade((c) => {
+  const events = (c: Parameters<MiddlewareHandler>[0]): WSEvents => {
       const windowId = c.req.query('window') as string
       const focused = c.req.query('focused') === '1'
       const shellQuery = Number(c.req.query('shell'))
       const shellWindow = Number.isSafeInteger(shellQuery) && shellQuery > 0 ? shellQuery : undefined
+      const tabQuery = c.req.query('tab')
+      const tab = tabQuery !== undefined && WINDOW_ID.test(tabQuery) ? tabQuery : undefined
       let detach: (() => void) | undefined
       let beat: NodeJS.Timeout | undefined
       return {
@@ -55,7 +55,7 @@ export function pageSocketRoutes(channel: UiChannel, options: PageSocketOptions)
             ws.send(JSON.stringify(frame))
           }
           // A call that cannot be written fails at once (`disconnected`), and a socket that is gone is dropped by its close: the door never holds a call for it.
-          detach = channel.attach(windowId, focused, { send: data => { write({ e: 'call', d: data }) }, notify: (event, data) => { write({ e: event, d: data }) }, close: () => { ws.close(1000, 'replaced') } }, shellWindow)
+          detach = channel.attach(windowId, focused, { send: data => { write({ e: 'call', d: data }) }, notify: (event, data) => { write({ e: event, d: data }) }, close: () => { ws.close(1000, 'replaced') } }, shellWindow, tab)
           write({ e: 'ready' })
           beat = setInterval(() => {
             try { write({ e: 'ping' }) } catch { /* the close event follows */ }
@@ -73,6 +73,16 @@ export function pageSocketRoutes(channel: UiChannel, options: PageSocketOptions)
           detach?.()
         },
       }
-    }, { textOnly: true }),
+  }
+  // Mounted once, ahead of the private routes: the route must keep its precedence across a host restart, so the middleware asks for the live helper
+  // at request time and refuses cleanly while none is ready.
+  return new Acryl().get(
+    `${options.prefix}/channel/ws`,
+    ownOrigin,
+    async (c, next) => {
+      const allow = options.upgrade()
+      if (allow === undefined) return c.json(error('the page channel is not ready yet'), 503)
+      return allow(events, { textOnly: true })(c, next)
+    },
   )
 }

package/plugins/acryl-door/src/host/verbs.ts

@@ -6,6 +6,9 @@
 import { MAX_SNAPSHOT_NODES, MAX_WAIT_MS } from '../page/protocol.ts'
 
 /** Every verb, in the order `brief` lists them. */
+/** The verbs that only use the page: what a page-only door (a production assistant) offers. */
+export const PAGE_VERBS = ['look', 'act'] as const satisfies readonly Verb[]
+
 export const VERBS = ['brief', 'look', 'act', 'plugin-list', 'plugin-add', 'plugin-remove', 'plugin-reload', 'tool-list', 'tool-call', 'window-list', 'window-open', 'window-focus', 'window-close', 'window-resize', 'menu-list', 'menu-click'] as const
 export type Verb = (typeof VERBS)[number]
 

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 { PAGE_VERBS, VERBS } from './host/verbs.ts'
 import { Door, type ExtensionsPort, type ToolsPort } from './host/door.ts'
-import { newSecret, removeDoorFile, stateDir, writeDoorFile } from './host/door-file.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,23 +140,47 @@ 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,
     tools: () => ctx.get('tools') as unknown as ToolsPort | undefined,
     expose: config.tools?.expose ?? [],
@@ -134,10 +191,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 +205,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'))