acrylblends 1.0.10 → 1.2.0

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

@@ -4,20 +4,62 @@
  * 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'
 
+/** 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)
@@ -30,7 +72,7 @@ export function startDoor(document: Document, base: string = DOOR_BASE): () => v
       return 'auto'
     }
   })()
-  const channel = new PageChannel(driver, { windowId, focused, base, transport, ...(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)
@@ -47,8 +89,10 @@ export function startDoor(document: Document, base: string = DOOR_BASE): () => v
     view.removeEventListener('pagehide', leave)
     view.removeEventListener('pageshow', back)
     document.removeEventListener('visibilitychange', reportFocus)
+    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/indicator.ts

@@ -1,6 +1,7 @@
 /**
- * "The agent is driving" bar with its kill switch, in plain DOM (the React one in `acryl-agent-control` shows the same states). Shown while
- * a call runs and after the person stopped the agent. It is marked as driver UI (so snapshots skip it) and as off limits to the agent (so
+ * "The agent is driving" bar with its kill switch, in plain DOM (the React one in `acryl-agent-control` shows the same states). Shown for the whole of a run asked for from
+ * this page's panel (between the calls too), while a call runs, and after the person stopped the agent. Stop kills the page's control and asks the panel to stop the run (the
+ * `acryl:stop-run` event on the window, which the panel listens for). It is marked as driver UI (so snapshots skip it) and as off limits to the agent (so
  * it can never press its own Stop or Allow buttons). Escape stops the agent too, while it is working.
  */
 
@@ -8,6 +9,9 @@ import type { DriverActivity, UiDriver } from './driver/driver.ts'
 
 const LABELS: Record<string, string> = { snapshot: 'looking at the page', click: 'clicking', type: 'typing', select: 'choosing an option', press: 'pressing a key', scroll: 'scrolling', wait: 'waiting' }
 
+/** Dispatched on the page's window by the Stop button: the agent panel in the same page cancels its run. */
+export const STOP_RUN_EVENT = 'acryl:stop-run'
+
 const STYLE_ID = 'acryl-door-indicator-style'
 const STYLES = `
 .acrylDoorBar { position: fixed; z-index: 2147483647; left: 50%; bottom: 16px; transform: translateX(-50%); display: flex; align-items: center; gap: 10px;
@@ -32,13 +36,17 @@ export function mountIndicator(driver: UiDriver, document: Document): () => void
   bar.setAttribute('role', 'status')
   bar.setAttribute('aria-live', 'polite')
 
+  const stopAgent = (): void => {
+    driver.kill()
+    document.defaultView?.dispatchEvent(new CustomEvent(STOP_RUN_EVENT))
+  }
   const onKey = (event: KeyboardEvent): void => {
-    if (event.key === 'Escape' && event.isTrusted && driver.activity.busy) driver.kill()
+    if (event.key === 'Escape' && event.isTrusted && (driver.activity.busy || driver.activity.running)) stopAgent()
   }
   document.addEventListener('keydown', onKey, true)
 
   const render = (activity: DriverActivity): void => {
-    if (!activity.busy && !activity.killed) { bar.remove(); return }
+    if (!activity.busy && !activity.running && !activity.killed) { bar.remove(); return }
     const button = document.createElement('button')
     button.type = 'button'
     const text = document.createElement('span')
@@ -53,9 +61,9 @@ export function mountIndicator(driver: UiDriver, document: Document): () => void
       const dot = document.createElement('span')
       dot.className = 'acrylDoorDot'
       dot.setAttribute('aria-hidden', 'true')
-      text.textContent = `Agent is driving: ${LABELS[activity.doing] ?? activity.doing}`
+      text.textContent = `Agent is driving: ${activity.busy ? (LABELS[activity.doing] ?? activity.doing) : 'working on your request'}`
       button.textContent = 'Stop'
-      button.addEventListener('click', () => { driver.kill() })
+      button.addEventListener('click', stopAgent)
       bar.replaceChildren(dot, text, button)
     }
     if (!bar.isConnected) document.body.append(bar)

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' })