acrylblends 1.1.0 → 1.2.0

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()
+    },
+  }
+}

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

@@ -60,6 +60,8 @@ export interface UiNode {
   readonly value?: string
   /** Heading level, when it is a heading. */
   readonly level?: number
+  /** The choices of a select, as `act select` takes them, when it is not sensitive. */
+  readonly options?: readonly string[]
 }
 
 export interface UiSnapshot {
@@ -88,6 +90,8 @@ export interface UiActionResult {
   readonly ok: true
   readonly target?: { readonly role: string; readonly name: string }
   readonly detail?: string
+  /** The act started a navigation (a link, a form that submits): this page is going away, and the Host waits for the next one. */
+  readonly leaving?: true
 }
 
 export type UiResult = UiSnapshot | UiActionResult

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

@@ -11,7 +11,8 @@ export function renderSnapshot(snapshot: UiSnapshot, more: (cursor: number) => s
     const level = node.level === undefined ? '' : ` level=${String(node.level)}`
     const states = node.states.length === 0 ? '' : ` [${node.states.join(', ')}]`
     const value = node.value === undefined ? '' : ` value=${JSON.stringify(node.value)}`
-    return `${'  '.repeat(Math.min(node.depth, 8))}- ${node.role}${node.name === '' ? '' : ` ${JSON.stringify(node.name)}`}${level}${states}${value} [ref=${node.ref}]`
+    const options = node.options === undefined ? '' : ` options=${JSON.stringify(node.options)}`
+    return `${'  '.repeat(Math.min(node.depth, 8))}- ${node.role}${node.name === '' ? '' : ` ${JSON.stringify(node.name)}`}${level}${states}${value}${options} [ref=${node.ref}]`
   })
   const rest = snapshot.nextCursor === undefined ? '' : `\n(${String(snapshot.total - snapshot.nextCursor)} more elements; ${more(snapshot.nextCursor)})`
   return `Page: ${snapshot.title || '(untitled)'}\nSnapshot ${String(snapshot.generation)}, ${String(snapshot.nodes.length)} of ${String(snapshot.total)} elements:\n${lines.join('\n')}${rest}`

package/plugins/acryl-node-server/src/adapter/listener.ts

@@ -14,6 +14,7 @@ import {
 } from './request.ts'
 import { defaultContentType, cacheKey, Response as LightweightResponse } from './response.ts'
 import type { InternalCache } from './response.ts'
+import { RAW_RESPONSE_HANDLED } from './raw.ts'
 import type { CustomErrorHandler, FetchCallback, HttpBindings } from './types.ts'
 import {
   readWithoutBlocking,
@@ -500,6 +501,9 @@ export const getRequestListener = (
       res = fetchCallback(req, { incoming, outgoing } as HttpBindings) as
         | Response
         | Promise<Response>
+        | typeof RAW_RESPONSE_HANDLED
+      // A raw handler (not a `Response`) owns the node response: it has written (or is writing) it, so the adapter writes nothing.
+      if (res === RAW_RESPONSE_HANDLED) return
       if (!isPromise(res) && isImmediateCacheableResponse(res)) {
         // Synchronous cacheable response — no close listener needed.
         // No I/O events can fire between fetchCallback returning and responseViaCache

package/plugins/acryl-node-server/src/adapter/raw.ts

@@ -0,0 +1,18 @@
+/**
+ * Raw HTTP handlers, outside the router: a host that must serve another server's node `(req, res)` handlers (a DSH compatibility port, the
+ * desktop shell's own endpoints) registers by path instead of building an `Acryl`. The adapter hands a matched request to the handler with the
+ * real `IncomingMessage`/`ServerResponse` and writes nothing itself; `RAW_RESPONSE_HANDLED` is how the fetch callback tells it so.
+ *
+ * Upgrades work the same way at the socket level: a registered path is claimed before the router's WebSocket handling, and the adapter's
+ * WebSocket setup leaves a request marked with `RAW_UPGRADE_HANDLED` alone.
+ */
+import type { IncomingMessage } from 'node:http'
+
+/** Returned by a raw-aware fetch callback: the node response is already owned, do not write. */
+export const RAW_RESPONSE_HANDLED: unique symbol = Symbol.for('acryl-node-server.raw-response')
+
+/** Set on an upgrade request a raw handler took over; the adapter's WebSocket setup skips it. */
+export const RAW_UPGRADE_HANDLED: unique symbol = Symbol.for('acryl-node-server.raw-upgrade')
+
+/** An upgrade request a raw handler took over. */
+export type RawUpgradeRequest = IncomingMessage & { [RAW_UPGRADE_HANDLED]?: true }

package/plugins/acryl-node-server/src/adapter/websocket.ts

@@ -3,6 +3,7 @@ import { defineWebSocketHelper } from 'acryl-router/helpers'
 import type { IncomingMessage } from 'node:http'
 import { STATUS_CODES } from 'node:http'
 import type { Duplex } from 'node:stream'
+import { RAW_UPGRADE_HANDLED, type RawUpgradeRequest } from './raw.ts'
 import type { FetchCallback } from './types.ts'
 import type { WebSocketData, WebSocketLike, WebSocketServerLike } from './websocket-types.ts'
 
@@ -144,6 +145,8 @@ const appendResponseHeaders = (headers: string[], responseHeaders?: Headers) =>
 }
 
 const rejectUpgradeRequest = (socket: Duplex, status: number, responseHeaders?: Headers) => {
+  // The socket already has its answer (a provider transition can route one upgrade to two handlers for a moment): never write a second one.
+  if (socket.destroyed || socket.writableEnded) return
   const responseLines = ['Connection: close', 'Content-Length: 0']
   appendResponseHeaders(responseLines, responseHeaders)
 
@@ -181,8 +184,13 @@ export const setupWebSocket = (options: {
   server: UpgradeSource
   fetchCallback: FetchCallback
   wss: WebSocketServerLike
+  /**
+   * Leave a request alone when a raw upgrade handler claimed it. Set by a transport that shares its upgrade source with raw claims (the node
+   * server's HTTP server); a hub fed by its own emitter (the Web adapter) must still answer its own upgrades, which arrive through a raw claim.
+   */
+  skipWhenRawUpgrade?: boolean
 }): void => {
-  const { server, fetchCallback, wss } = options
+  const { server, fetchCallback, wss, skipWhenRawUpgrade = false } = options
 
   const waiterMap = new Map<
     IncomingMessage,
@@ -216,9 +224,11 @@ export const setupWebSocket = (options: {
   }
 
   server.on('upgrade', async (request, socket: Duplex, head) => {
+    // A raw upgrade handler claimed this path before the WebSocket setup ran: the socket is (or will be) its own.
+    if (skipWhenRawUpgrade && (request as RawUpgradeRequest)[RAW_UPGRADE_HANDLED] === true) return
     if (request.headers.upgrade?.toLowerCase() !== 'websocket') {
-      // Nobody else listens: an upgrade to another protocol is answered, not left hanging.
-      if (server.listenerCount('upgrade') === 1) rejectUpgradeRequest(socket, 400)
+      // An upgrade to another protocol is answered, not left hanging (the transport's raw listener flags the ones it already answered).
+      rejectUpgradeRequest(socket, 400)
       return
     }
 
@@ -241,9 +251,7 @@ export const setupWebSocket = (options: {
         responseHeaders = response.headers
       }
     } catch {
-      if (server.listenerCount('upgrade') === 1) {
-        rejectUpgradeRequest(socket, 500)
-      }
+      rejectUpgradeRequest(socket, 500)
       return
     }
 
@@ -251,9 +259,7 @@ export const setupWebSocket = (options: {
 
     if (!waiter || waiter.connectionSymbol !== env[CONNECTION_SYMBOL_KEY]) {
       rejectWaiter(request)
-      if (server.listenerCount('upgrade') === 1) {
-        rejectUpgradeRequest(socket, status, responseHeaders)
-      }
+      rejectUpgradeRequest(socket, status, responseHeaders)
       return
     }
 

package/plugins/acryl-node-server/src/client-modules.ts

@@ -38,6 +38,12 @@ const DEFAULT_CACHE_BYTES = 16 * 1024 * 1024
 export interface ClientModulesOptions {
   /** The folder of client modules, absolute or relative to the working directory. */
   readonly root: string
+  /**
+   * The URL prefix the app is mounted at, when the caller knows it. A host can compose app plugins under its own router, and under a
+   * Host whose router is a different copy of this package the request's match result is not visible here, so `basePath(c)` throws; the
+   * explicit prefix is then the only reliable way to know where the mount starts. Omitted, the router's `basePath(c)` is used.
+   */
+  readonly mount?: string | undefined
   /** The folder {@link buildClientModules} wrote; with `NODE_ENV=production` it is served instead of compiling, which needs no `typescript`. */
   readonly compiled?: string | undefined
   /** At most this many bytes of compiled modules are kept in memory (least recently served first out); 16 MiB when not given. */
@@ -204,7 +210,7 @@ export function clientModules(options: ClientModulesOptions): Acryl {
 
   const app = new Acryl()
   app.get('/*', (c) => {
-    const requestPath = c.req.path.slice(basePath(c).length)
+    const requestPath = c.req.path.slice(options.mount === undefined ? basePath(c).length : options.mount.length)
     const runtime = /^\/@acrylblends\/([a-z-]+\.js)$/u.exec(requestPath)?.[1]
     const send = (code: string, etag: string): Response => {
       if (c.req.header('if-none-match') === etag) return c.body(null, 304, { etag, 'cache-control': 'no-cache' })