acrylblends 1.0.10 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.10",
+  "version": "1.2.0",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",
@@ -405,6 +405,7 @@
     "dist",
     "lib",
     "templates",
+    "legacy",
     "shared",
     "plugins",
     "docs"

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

@@ -17,6 +17,8 @@ import {
 /** The slice of a page's stream the channel needs, so tests can supply their own. */
 export interface PageStream {
   send(data: string): void
+  /** Tell the page something that is not a call (`run`: `1` while a run asked for from its panel goes, `0` when it ends). A stream that cannot (a test's) leaves it out. */
+  notify?(event: string, data: string): void
   close(): void
 }
 
@@ -42,6 +44,8 @@ interface Connection {
   readonly windowId: string
   /** The desktop window the page is in, when the Electron shell tagged it. */
   readonly shellWindow: number | undefined
+  /** The browser tab the page is in (the page keeps it for the tab's lifetime): a page that reloads or moves to another path comes back with a new window id and the same tab. */
+  readonly tab: string | undefined
   focused: boolean
   /** Order of last focus (or connection), so the most recent wins. */
   lastActive: number
@@ -62,21 +66,39 @@ export interface ChannelOptions {
    * address registers again a moment later). 0 (the default) fails at once.
    */
   readonly attachWaitMs?: number
+  /**
+   * Every call must name the page it is for (`page`), and goes to that page alone: never to the page in front or the one used last, which may be another visitor's. A page-only door
+   * (a production assistant, one channel for every visitor of the app) sets it.
+   */
+  readonly requirePage?: boolean
+}
+
+/** A page whose panel asked for a run: the id the run knows it by, and where that page is now (the same tab after a reload or a move). */
+interface Asker {
+  /** The window id the run was asked from: what its calls name as `page`. */
+  readonly origin: string
+  windowId: string
+  tab: string | undefined
 }
 
 /**
- * The pages and who drives which. One page answers a call, chosen the same way every time: the page the Host just sent somewhere (it comes back as a new page, `prefer`), else the
- * one in front (it reports `focused`), else the most recently active; a page that did not acknowledge a call in time goes to the end of the line. An explicit desktop `window` picks its page.
+ * The pages and who drives which. One page answers a call, chosen the same way every time: the page whose panel asked for the run that is making the call (`driveFor`), else the page the
+ * Host just sent somewhere (it comes back as a new page, `prefer`), else the one in front (it reports `focused`), else the most recently active; a page that did not acknowledge a call in time goes to the end of the line. An explicit desktop `window` picks its page.
+ * A call that names its `page` (the page a run was asked from) goes to that page alone, followed into its tab when it reloads or moves, and to no other.
  */
 export class UiChannel {
   private readonly ackMs: number
   private readonly attachWaitMs: number
+  private readonly requirePage: boolean
   /** The page the Host sent to a new place and that came back: it keeps being driven until the person focuses another page. */
   private preferred: string | undefined
+  /** The pages whose panels have a run going, the latest last: a call with no `window` goes to the latest of them that is still connected. */
+  private readonly askers: Asker[] = []
 
   constructor(options: ChannelOptions = {}) {
     this.ackMs = options.ackMs ?? DEFAULT_ACK_MS
     this.attachWaitMs = options.attachWaitMs ?? 0
+    this.requirePage = options.requirePage === true
   }
 
   private readonly connections = new Map<string, Connection>()
@@ -91,12 +113,19 @@ export class UiChannel {
    * Register a page's stream. A stream already open for the same window is closed first, and its calls settle as `disconnected`.
    * @returns the function to call when this stream ends.
    */
-  attach(windowId: string, focused: boolean, stream: PageStream, shellWindow?: number): () => void {
+  attach(windowId: string, focused: boolean, stream: PageStream, shellWindow?: number, tab?: string): () => void {
     const previous = this.connections.get(windowId)
     if (previous !== undefined) this.drop(previous, true)
     // A page that did not answer stays last in line when its stream reconnects: a tab that cannot answer reconnects just as readily, and would otherwise be first again.
-    const connection: Connection = { stream, windowId, shellWindow, focused, lastActive: ++this.clock, suspect: previous?.suspect === true }
+    const connection: Connection = { stream, windowId, shellWindow, tab, focused, lastActive: ++this.clock, suspect: previous?.suspect === true }
     this.connections.set(windowId, connection)
+    // A run's page that reloaded or moved comes back as a new page in the same tab: the run goes on with it.
+    for (const asker of this.askers) {
+      if (asker.windowId === windowId) asker.tab ??= tab
+      else if (tab !== undefined && asker.tab === tab) asker.windowId = windowId
+    }
+    // A page that reloaded or came back during its own run is told the run is still going.
+    if (this.askers.some(asker => asker.windowId === windowId)) this.tell(connection, '1')
     for (const waiter of [...this.attachWaiters]) waiter(windowId)
     return () => { if (this.connections.get(windowId) === connection) this.drop(connection, false) }
   }
@@ -137,12 +166,71 @@ export class UiChannel {
     return this.ordered().map(({ windowId, focused, shellWindow }) => ({ windowId, focused, ...(shellWindow === undefined ? {} : { shellWindow }) }))
   }
 
+  /**
+   * A run asked for from this page's panel is going: its calls (which name no window) are for this page, whatever else is open and whichever was driven last, until the run ends.
+   * An explicit desktop `window` still picks its own page.
+   * @returns the function to call when the run ends.
+   */
+  driveFor(windowId: string): () => void {
+    const asker: Asker = { origin: windowId, windowId, tab: this.connections.get(windowId)?.tab }
+    this.askers.push(asker)
+    this.tellPage(windowId, '1')
+    return () => {
+      const at = this.askers.indexOf(asker)
+      if (at === -1) return
+      this.askers.splice(at, 1)
+      // The page keeps the bar if another run of its own is still going.
+      if (!this.askers.some(other => other.windowId === asker.windowId)) this.tellPage(asker.windowId, '0')
+    }
+  }
+
+  /** Where the page a run was asked from is now: the same window, or the page that replaced it in the same tab. */
+  private whereIs(page: string): { windowId: string; tab: string | undefined } {
+    const asker = [...this.askers].reverse().find(entry => entry.origin === page)
+    return asker === undefined ? { windowId: page, tab: this.connections.get(page)?.tab } : { windowId: asker.windowId, tab: asker.tab }
+  }
+
+  /**
+   * A promise for the run's page coming back after a reload or a move: the next page that connects in its tab (or with its window id). Ask for it BEFORE the call that makes the page
+   * leave. Pages of other tabs, another visitor's among them, are never taken for it.
+   * @param signal - stop waiting (the act did not move the page after all); the promise then answers `undefined`.
+   * @returns the window id of the page that came back, or `undefined` when it did not within `timeoutMs`.
+   */
+  expectPageBack(page: string, timeoutMs: number, signal?: AbortSignal): Promise<string | undefined> {
+    const { windowId, tab } = this.whereIs(page)
+    return new Promise((resolve) => {
+      const done = (value: string | undefined): void => { clearTimeout(timer); this.attachWaiters.delete(waiter); signal?.removeEventListener('abort', stop); resolve(value) }
+      const stop = (): void => { done(undefined) }
+      signal?.addEventListener('abort', stop, { once: true })
+      const waiter = (attached: string): void => {
+        const connection = this.connections.get(attached)
+        if (attached === windowId || (tab !== undefined && connection?.tab === tab)) done(attached)
+      }
+      const timer = setTimeout(() => { done(undefined) }, timeoutMs)
+      this.attachWaiters.add(waiter)
+    })
+  }
+
+  private tellPage(windowId: string, running: '0' | '1'): void {
+    const connection = this.connections.get(windowId)
+    if (connection !== undefined) this.tell(connection, running)
+  }
+
+  private tell(connection: Connection, running: '0' | '1'): void {
+    try { connection.stream.notify?.('run', running) } catch { /* a stream that is going away says so by closing */ }
+  }
+
   /** Drive this page from now on (it is the one the Host just sent to a new place), until the person focuses another. */
   prefer(windowId: string): void {
     const connection = this.connections.get(windowId)
     if (connection === undefined) return
     this.preferred = windowId
     connection.lastActive = ++this.clock
+    // A run's own page that reloaded or navigated comes back as a new page: the run goes on with that one. A run whose page has a tab follows only that tab, so
+    // another visitor's page is never taken for it.
+    for (const asker of this.askers)
+      if (!this.connections.has(asker.windowId) && (asker.tab === undefined || asker.tab === connection.tab)) asker.windowId = windowId
+    if (this.askers.some(asker => asker.windowId === windowId)) this.tellPage(windowId, '1')
   }
 
   /**
@@ -150,9 +238,11 @@ export class UiChannel {
    * until it speaks; a call that changes the page is never sent to a second page, because the first might still run it.
    * @throws UiControlError `no-window`, `timeout`, `aborted`, `unloaded`, `disconnected`, or whatever the page refused with.
    */
-  async call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number; window?: number } = {}, retried = false): Promise<UiResult> {
+  async call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number; window?: number; page?: string } = {}, retried = false): Promise<UiResult> {
     if (this.closed) throw new UiControlError('unloaded', 'the door was unloaded')
     const readOnlyCall = request.op === 'snapshot' || request.op === 'wait'
+    if (options.page !== undefined) return await this.callPage(request, options.page, options, readOnlyCall)
+    if (this.requirePage) throw new UiControlError('no-window', 'this door drives only the page whose visitor asked, and the call names no page')
     // A page that is moving to another address registers again a moment later: a read-only call right after a navigate or reload waits for it, rather than failing.
     if (readOnlyCall && this.attachWaitMs > 0 && this.connections.size === 0) await this.expectNewPage(this.attachWaitMs)
     const ordered = this.ordered()
@@ -182,6 +272,26 @@ export class UiChannel {
     throw new UiControlError('timeout', `no page of the app answered within ${String(Math.round(this.ackMs / 1000))} s: the app's pages are open but none responded. Likely causes: a tab in the background, a page that is still loading after a navigation (look again), a page busy running a long script, or a page that holds the browser's six connections with event streams of its own (a page should keep to two). Bring the app's tab to the front, or navigate it, then look again`)
   }
 
+  /**
+   * A call for one page (the page a run was asked from, followed into its tab): it goes to that page alone and never fails over to another one. A page that is between two
+   * documents (it reloads, or moves to another path) is waited for, up to the attach wait.
+   */
+  private async callPage(request: UiRequest, page: string, options: { signal?: AbortSignal; timeoutMs?: number }, readOnly: boolean): Promise<UiResult> {
+    let target = this.connections.get(this.whereIs(page).windowId)
+    if (target === undefined && this.attachWaitMs > 0) {
+      const back = await this.expectPageBack(page, this.attachWaitMs)
+      if (back !== undefined) target = this.connections.get(back)
+    }
+    if (target === undefined) throw new UiControlError('no-window', 'the page this run is for is not open any more')
+    if (options.signal?.aborted === true) throw new UiControlError('aborted', 'the call was cancelled')
+    try {
+      return await this.callOne(target, request, options, readOnly)
+    } catch (cause) {
+      if (cause instanceof Silent) throw new UiControlError('timeout', 'the page this run is for did not answer: is its tab in the background or still loading? Look again')
+      throw cause
+    }
+  }
+
   private callOne(target: Connection, request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number }, failOver: boolean): Promise<UiResult> {
     const signal = options.signal
     const id = this.nextId
@@ -224,12 +334,15 @@ export class UiChannel {
 
   /**
    * A promise for the window id of the next page that connects and was not connected when this was asked (the page that came back after a reload or a move).
+   * @param signal - stop waiting; the promise then answers `undefined`.
    * @returns that id, or `undefined` when no new page connected within `timeoutMs`.
    */
-  expectNewPage(timeoutMs: number): Promise<string | undefined> {
+  expectNewPage(timeoutMs: number, signal?: AbortSignal): Promise<string | undefined> {
     const known = new Set(this.connections.keys())
     return new Promise((resolve) => {
-      const done = (value: string | undefined): void => { clearTimeout(timer); this.attachWaiters.delete(waiter); resolve(value) }
+      const done = (value: string | undefined): void => { clearTimeout(timer); this.attachWaiters.delete(waiter); signal?.removeEventListener('abort', stop); resolve(value) }
+      const stop = (): void => { done(undefined) }
+      signal?.addEventListener('abort', stop, { once: true })
       const waiter = (windowId: string): void => { if (!known.has(windowId)) done(windowId) }
       const timer = setTimeout(() => { done(undefined) }, timeoutMs)
       this.attachWaiters.add(waiter)
@@ -263,9 +376,11 @@ export class UiChannel {
     this.connections.clear()
   }
 
-  /** The order pages are driven in: the one the Host sent somewhere, suspect ones last, the one in front, then the most recently active. */
+  /** The order pages are driven in: the one whose panel asked, the one the Host sent somewhere, suspect ones last, the one in front, then the most recently active. */
   private ordered(): Connection[] {
-    const rank = (connection: Connection): number => (connection.suspect ? 0 : 4) + (connection.windowId === this.preferred ? 2 : 0) + (connection.focused ? 1 : 0)
+    // The latest asker that is still connected; a page that went away is skipped, and the run goes on with whatever is open.
+    const asker = [...this.askers].reverse().find(entry => this.connections.has(entry.windowId))?.windowId
+    const rank = (connection: Connection): number => (connection.suspect ? 0 : 4) + (connection.windowId === this.preferred ? 2 : 0) + (connection.focused ? 1 : 0) + (connection.windowId === asker && !connection.suspect ? 8 : 0)
     return [...this.connections.values()].sort((a, b) => rank(b) - rank(a) || b.lastActive - a.lastActive)
   }
 

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

@@ -6,10 +6,10 @@
 
 import { UiControlError } from '../page/protocol.ts'
 import { DoorError, type Door, type ToolsPort } from './door.ts'
-import { chatToolName, VERB_SPECS, VERBS } from './verbs.ts'
+import { chatToolName, VERB_SPECS, VERBS, type Verb } from './verbs.ts'
 
-/** Register every verb. @returns the function that removes them all; it also aborts the calls still running. */
-export function registerChatTools(tools: ToolsPort, door: Door): () => void {
+/** Register the verbs (default: every one). @returns the function that removes them all; it also aborts the calls still running. */
+export function registerChatTools(tools: ToolsPort, door: Door, verbs: readonly Verb[] = VERBS): () => void {
   const running = new AbortController()
   const removers: Array<() => void> = []
   const removeAll = (): void => {
@@ -17,14 +17,16 @@ export function registerChatTools(tools: ToolsPort, door: Door): () => void {
     for (const remove of removers.splice(0).reverse()) remove()
   }
   try {
-    for (const verb of VERBS) {
+    for (const verb of verbs) {
       removers.push(tools.register(chatToolName(verb), {
         description: VERB_SPECS[verb].description,
         // The model is told which fields the verb takes (an `act` needs its `op`), the same schema MCP lists.
         parameters: VERB_SPECS[verb].arguments as unknown as Readonly<Record<string, unknown>>,
-        run: async (input: unknown) => {
+        // The run's own signal and page come with the call: its look and act go to the page the run was asked from.
+        run: async (input: unknown, options?: { signal?: AbortSignal; page?: string }) => {
+          const signal = options?.signal === undefined ? running.signal : AbortSignal.any([running.signal, options.signal])
           try {
-            return (await door.run(verb, input ?? {}, running.signal)).text
+            return (await door.run(verb, input ?? {}, signal, options?.page === undefined ? {} : { page: options.page })).text
           } catch (cause) {
             if (cause instanceof DoorError || cause instanceof UiControlError) throw new Error(`${cause.code}: ${cause.message}`, { cause })
             throw cause

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

@@ -73,12 +73,17 @@ function alive(pid: number): boolean {
  * Write this run's connection file, replacing a stale one.
  * @throws when another live process already serves this folder's door: two apps from one folder would race for one file.
  */
-export function writeDoorFile(appRoot: string, url: string, secret: string): string {
-  const dir = ensureStateDir(appRoot)
+/** @throws when another live process already serves this folder's door: two apps from one folder would race for one file. */
+export function assertDoorIsFree(appRoot: string): void {
   const existing = readDoorFile(appRoot)
   if (existing !== undefined && existing.pid !== process.pid && alive(existing.pid)) {
     throw new Error(`acryl-door: another process (pid ${String(existing.pid)}) serves the door of ${appRoot}; stop it first`)
   }
+}
+
+export function writeDoorFile(appRoot: string, url: string, secret: string): string {
+  const dir = ensureStateDir(appRoot)
+  assertDoorIsFree(appRoot)
   const file = doorFilePath(appRoot)
   const temporary = join(dir, `${DOOR_FILE}.${String(process.pid)}.tmp`)
   const content: DoorFile = { version: 1, url, secret, pid: process.pid }

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
@@ -90,17 +98,22 @@ export class Door {
     this.deps = deps
   }
 
+  /** A run asked for from the panel of this page is going: its verbs that name no window are for that page. @returns the function to call when the run ends. */
+  driveFor(windowId: string): () => void {
+    return this.deps.channel.driveFor(windowId)
+  }
+
   /** 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)
@@ -146,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` }
   }
@@ -182,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 {
@@ -232,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 }
   }
@@ -248,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
@@ -265,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) }, 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 }) }, 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]