acrylblends 1.0.10 → 1.1.0

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
 }
 
@@ -65,14 +67,16 @@ export interface ChannelOptions {
 }
 
 /**
- * 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.
  */
 export class UiChannel {
   private readonly ackMs: number
   private readonly attachWaitMs: number
   /** 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: Array<{ windowId: string }> = []
 
   constructor(options: ChannelOptions = {}) {
     this.ackMs = options.ackMs ?? DEFAULT_ACK_MS
@@ -97,6 +101,8 @@ export class UiChannel {
     // 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 }
     this.connections.set(windowId, connection)
+    // 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 +143,42 @@ 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 = { windowId }
+    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')
+    }
+  }
+
+  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.
+    for (const asker of this.askers) if (!this.connections.has(asker.windowId)) asker.windowId = windowId
+    if (this.askers.some(asker => asker.windowId === windowId)) this.tellPage(windowId, '1')
   }
 
   /**
@@ -263,9 +299,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/door.ts

@@ -90,6 +90,11 @@ 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> {
     const input = (typeof args === 'object' && args !== null && !Array.isArray(args) ? args : {}) as Record<string, unknown>

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

@@ -43,7 +43,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)
         const beat = setInterval(() => { write('ping', '') }, heartbeatMs)
         try {
           write('ready', '')

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

@@ -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)
           write({ e: 'ready' })
           beat = setInterval(() => {
             try { write({ e: 'ping' }) } catch { /* the close event follows */ }

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

@@ -41,6 +41,8 @@ export interface PageChannelOptions {
   readonly post?: (url: string, body: string) => Promise<unknown>
   readonly silenceMs?: number
   readonly now?: () => number
+  /** The Host says a run asked for from this page's panel started (`true`) or ended (`false`); false too when the stream is lost, until the Host says again. */
+  readonly onRun?: (running: boolean) => void
 }
 
 export class PageChannel {
@@ -85,6 +87,10 @@ export class PageChannel {
       heard()
     })
     source.addEventListener('ping', heard)
+    source.addEventListener('run', (event) => {
+      heard()
+      this.options.onRun?.(event.data === '1')
+    })
     source.addEventListener('call', (event) => {
       heard()
       if (typeof event.data === 'string') this.answer(event.data)
@@ -158,6 +164,8 @@ export class PageChannel {
     if (source !== undefined) {
       source.onerror = null
       source.close()
+      // Without the stream the page cannot hear the run end: the Host says again if it is still going, once the stream is back.
+      this.options.onRun?.(false)
     }
   }
 

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

@@ -19,6 +19,8 @@ export const LEAVE_DELAY_MS = 150
 export interface DriverActivity {
   /** True from the moment a call starts until it ends. */
   readonly busy: boolean
+  /** True from the moment a run asked for from this page's panel starts until it ends, between the calls too. */
+  readonly running: boolean
   /** What the agent is doing, for the indicator ("click", "type", ...). */
   readonly doing: string
   /** True after the user pressed the kill switch. */
@@ -53,7 +55,8 @@ export class UiDriver {
   private disposed = false
   private busyCount = 0
   private doing = ''
-  private current: DriverActivity = { busy: false, doing: '', killed: false }
+  private current: DriverActivity = { busy: false, running: false, doing: '', killed: false }
+  private runningFlag = false
 
   private readonly options: UiDriverOptions
 
@@ -82,6 +85,17 @@ export class UiDriver {
     this.emit()
   }
 
+  /**
+   * A run asked for from this page's panel starts (`true`) or ends (`false`). The indicator stays up for the whole run, not only while a call is in flight. A new run is a new
+   * question from the person, so it also allows the agent to drive again after an earlier Stop.
+   */
+  setRunning(running: boolean): void {
+    if (running === this.runningFlag) return
+    this.runningFlag = running
+    if (running) this.killedFlag = false
+    this.emit()
+  }
+
   /** The user allowed the agent to drive again. */
   resume(): void {
     this.killedFlag = false
@@ -165,8 +179,8 @@ export class UiDriver {
   }
 
   private emit(): void {
-    const next: DriverActivity = { busy: this.busyCount > 0, doing: this.doing, killed: this.killedFlag }
-    if (next.busy === this.current.busy && next.doing === this.current.doing && next.killed === this.current.killed) return
+    const next: DriverActivity = { busy: this.busyCount > 0, running: this.runningFlag, doing: this.doing, killed: this.killedFlag }
+    if (next.busy === this.current.busy && next.running === this.current.running && next.doing === this.current.doing && next.killed === this.current.killed) return
     this.current = next
     const activity = next
     for (const listener of [...this.listeners]) listener(activity)

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

@@ -11,6 +11,9 @@ 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')
+
 /** Start the door on `document`. @returns the disposer. */
 export function startDoor(document: Document, base: string = DOOR_BASE): () => void {
   const view = document.defaultView
@@ -18,6 +21,7 @@ export function startDoor(document: Document, base: string = DOOR_BASE): () => v
   const clock = new UserInputClock()
   const driver = new UiDriver({ document: () => document, msSinceUserInput: clock.msSince })
   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 focused = (): boolean => document.visibilityState === 'visible' && document.hasFocus()
   const detachInput = clock.attach(document)
   const removeIndicator = mountIndicator(driver, document)
@@ -30,7 +34,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, 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,6 +51,7 @@ 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()
     detachInput()

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-state/plugin.json

@@ -1,13 +1,14 @@
 {
   "name": "acryl-state",
-  "description": "Observable cells and derived cells, shared state with JSON and server-sent event routes on the router. Vendored from ACRYL.",
+  "description": "Observable cells and derived cells, shared state with JSON, server-sent event and WebSocket routes on the router, and a browser module (watch) that follows keys over one socket. Vendored from ACRYL.",
   "requires": ["acryl-router"],
   "inject": ["router"],
   "provides": ["state"],
   "dependencies": {
-    "@deepseek-ai/cordis": "4.0.4"
+    "@deepseek-ai/cordis": "4.0.4",
+    "ws": "8.21.3"
   },
-  "mount": "root.plugin(state); ctx.state.cell('todos.count', 0), then count.update((n) => n + 1)",
+  "mount": "root.plugin(state); ctx.state.cell('todos.count', 0), then count.update((n) => n + 1); a page follows it with import { watch } from '/api/state/client.js'; watch('todos.count', (n) => { ... })",
   "omit": ["src/react.ts", "**/*.test.*", "**/*.case.ts"],
   "entries": {
     "": "src/index.ts",

package/plugins/acryl-state/src/client-source.ts

@@ -0,0 +1,244 @@
+/**
+ * The browser module served at `/api/state/client.js`, kept as text so it travels with the plugin wherever the plugin goes (copied into an app as source, or bundled): there is
+ * no file to find at run time and no compiler needed to serve it. `String.raw` keeps every backslash as written, so what is below is the module exactly as the browser gets it.
+ * The code has no imports and uses no backtick or dollar-brace of its own.
+ *
+ *   import { watch } from '/api/state/client.js'
+ *   const stop = watch('tasks.count', (value) => { badge.textContent = String(value) })
+ *
+ * One WebSocket for the whole page carries every key; a WebSocket is not one of the browser's six connections per host, so a page that watches ten keys, in as many windows,
+ * leaves every one of them free for requests. Where the WebSocket cannot open (no `ws` package on the server, a proxy that does not upgrade), each key is followed by its
+ * event stream instead, with one console warning.
+ */
+export const CLIENT_SOURCE = String.raw`// acryl-state: watch(key, onValue, onError?) follows a state key over one WebSocket for the page.
+const HEARTBEAT_SILENCE_MS = 45000
+const RETRY_MIN_MS = 250
+const RETRY_MAX_MS = 10000
+
+const here = import.meta.url
+const watchers = new Map()
+const latest = new Map()
+const streams = new Map()
+const complained = new Set()
+let socket
+let timer
+let watchdog
+let attempts = 0
+let opened = false
+let following = 'socket'
+let suspended = false
+let warnedStream = false
+
+const socketUrl = () => {
+  const url = new URL('ws', here)
+  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
+  return url.href
+}
+const streamUrl = (key) => new URL(encodeURIComponent(key) + '/events?json=1', here).href
+
+const deliver = (key, text) => {
+  if (latest.get(key) === text) return
+  latest.set(key, text)
+  let value
+  try {
+    value = JSON.parse(text)
+  } catch {
+    return
+  }
+  for (const watcher of [...(watchers.get(key) ?? [])]) {
+    try {
+      watcher.onValue(value)
+    } catch (cause) {
+      console.error('acryl-state: a watcher of ' + key + ' threw', cause)
+    }
+  }
+}
+
+const fail = (key, message) => {
+  const set = watchers.get(key)
+  if (set === undefined) return
+  let told = false
+  for (const watcher of [...set]) {
+    if (watcher.onError === undefined) continue
+    told = true
+    try {
+      watcher.onError(new Error(message))
+    } catch (cause) {
+      console.error('acryl-state: an error handler of ' + key + ' threw', cause)
+    }
+  }
+  if (!told && !complained.has(key)) {
+    complained.add(key)
+    console.warn('acryl-state: ' + key + ': ' + message)
+  }
+}
+
+const send = (frame) => {
+  if (socket !== undefined && socket.readyState === 1) socket.send(JSON.stringify(frame))
+}
+
+const arm = () => {
+  clearTimeout(watchdog)
+  watchdog = setTimeout(() => lost(socket), HEARTBEAT_SILENCE_MS)
+}
+
+const closeSocket = () => {
+  clearTimeout(watchdog)
+  const current = socket
+  socket = undefined
+  if (current === undefined) return
+  current.onopen = current.onmessage = current.onerror = current.onclose = null
+  try {
+    current.close(1000, 'page left')
+  } catch {
+    // Already closed.
+  }
+}
+
+const closeStreams = () => {
+  for (const source of streams.values()) source.close()
+  streams.clear()
+}
+
+const openStream = (key) => {
+  if (streams.has(key) || typeof EventSource === 'undefined') return
+  const source = new EventSource(streamUrl(key))
+  streams.set(key, source)
+  source.addEventListener('value', (event) => deliver(key, event.data))
+  source.onerror = () => {
+    // A network error is retried by the browser itself; a refusal (the key does not exist) ends the stream for good.
+    if (source.readyState === 2) {
+      streams.delete(key)
+      fail(key, 'the event stream was refused (no such state?)')
+    }
+  }
+}
+
+const fallBack = () => {
+  following = 'stream'
+  if (!warnedStream) {
+    warnedStream = true
+    console.warn('acryl-state: the WebSocket did not open, so each key is followed by its own event stream (each holds one of the browser\'s six connections to this host)')
+  }
+  for (const key of watchers.keys()) openStream(key)
+}
+
+// A socket that closes, errors or goes quiet: before it ever opened this is a server without WebSockets, so the streams take over; after, the server went away and the page tries again.
+const lost = (which) => {
+  if (which !== socket) return
+  closeSocket()
+  if (watchers.size === 0 || suspended) return
+  if (!opened) {
+    fallBack()
+    return
+  }
+  const delay = Math.min(RETRY_MIN_MS * 2 ** attempts, RETRY_MAX_MS)
+  attempts += 1
+  clearTimeout(timer)
+  timer = setTimeout(connect, delay)
+}
+
+const connect = () => {
+  clearTimeout(timer)
+  if (socket !== undefined || watchers.size === 0 || suspended || following !== 'socket') return
+  let made
+  try {
+    made = new WebSocket(socketUrl())
+  } catch {
+    fallBack()
+    return
+  }
+  socket = made
+  made.onopen = () => {
+    opened = true
+    attempts = 0
+    arm()
+    for (const key of watchers.keys()) send({ t: 'sub', key })
+  }
+  made.onmessage = (event) => {
+    if (made !== socket) return
+    arm()
+    let frame
+    try {
+      frame = JSON.parse(event.data)
+    } catch {
+      return
+    }
+    if (frame === null || typeof frame !== 'object' || typeof frame.key !== 'string') return
+    if (typeof frame.error === 'string') fail(frame.key, frame.error)
+    else deliver(frame.key, JSON.stringify(frame.value))
+  }
+  made.onerror = () => lost(made)
+  made.onclose = () => lost(made)
+}
+
+const start = () => {
+  if (watchers.size === 0) return
+  if (following === 'stream') for (const key of watchers.keys()) openStream(key)
+  else connect()
+}
+
+if (typeof addEventListener === 'function') {
+  // A page in the back/forward cache keeps its connections open for as long as it is kept; let them go when the page is hidden for good, and open them again when it comes back.
+  addEventListener('pagehide', () => {
+    suspended = true
+    clearTimeout(timer)
+    closeSocket()
+    closeStreams()
+  })
+  addEventListener('pageshow', () => {
+    if (!suspended) return
+    suspended = false
+    start()
+  })
+}
+
+// Follow the state key: onValue gets the value now and after every change, as the JSON value the server holds (a string stays a string). onError, when given, is told of a key that
+// does not exist; without it the page console gets one warning. Returns the function that stops watching.
+export function watch(key, onValue, onError) {
+  if (typeof key !== 'string' || key === '') throw new TypeError('watch(key, onValue): the key is a state key like "tasks.count"')
+  if (typeof onValue !== 'function') throw new TypeError('watch(key, onValue): onValue is a function')
+  const watcher = { onValue, onError }
+  let set = watchers.get(key)
+  const first = set === undefined
+  if (first) {
+    set = new Set()
+    watchers.set(key, set)
+  }
+  set.add(watcher)
+  complained.delete(key)
+  if (!first && latest.has(key)) {
+    const text = latest.get(key)
+    queueMicrotask(() => {
+      if (!set.has(watcher)) return
+      try {
+        onValue(JSON.parse(text))
+      } catch (cause) {
+        console.error('acryl-state: a watcher of ' + key + ' threw', cause)
+      }
+    })
+  }
+  if (first && !suspended) {
+    if (following === 'stream') openStream(key)
+    else if (socket === undefined) connect()
+    else send({ t: 'sub', key })
+  }
+  let stopped = false
+  return () => {
+    if (stopped) return
+    stopped = true
+    set.delete(watcher)
+    if (set.size > 0) return
+    watchers.delete(key)
+    latest.delete(key)
+    complained.delete(key)
+    streams.get(key)?.close()
+    streams.delete(key)
+    send({ t: 'unsub', key })
+    if (watchers.size === 0) {
+      clearTimeout(timer)
+      closeSocket()
+    }
+  }
+}
+`

package/plugins/acryl-state/src/service.ts

@@ -6,10 +6,12 @@
  */
 
 import { Context, Service } from '@deepseek-ai/cordis'
-import { Acryl, type Context as RequestContext } from 'acryl-router'
-import { streamSSE } from 'acryl-router/helpers'
+import { Acryl, type Context as RequestContext, type MiddlewareHandler } from 'acryl-router'
+import { streamSSE, type UpgradeWebSocket } from 'acryl-router/helpers'
 import { loopbackOnly, methodNotAllowed } from 'acryl-router/middleware'
 import { createCell, createDerived, type Cell, type ReadonlyCell } from './cell.ts'
+import { CLIENT_SOURCE } from './client-source.ts'
+import { refuseStranger, stateSocket } from './socket.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -24,6 +26,9 @@ export const name = 'acryl-state'
 
 const KEY_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/
 
+/** Names under `/api/state` that are routes, not keys: a cell cannot be called by one. */
+const RESERVED_KEYS = new Set(['ws', 'client.js'])
+
 export class State extends Service {
   private readonly cells = new Map<string, ReadonlyCell<unknown>>()
 
@@ -33,6 +38,7 @@ export class State extends Service {
 
   private claim(key: string): void {
     if (!KEY_PATTERN.test(key)) throw new TypeError(`acryl-state: key "${key}" must be dotted lowercase words, like "market.sources"`)
+    if (RESERVED_KEYS.has(key)) throw new TypeError(`acryl-state: "${key}" is the name of a route under /api/state, choose another key`)
     if (this.cells.has(key)) throw new Error(`acryl-state: key "${key}" is already in use`)
   }
 
@@ -73,9 +79,10 @@ export class State extends Service {
 
   /**
    * The current value of `key` as a server-sent event stream: the value now, then one event per change, until the client cancels or the router
-   * is disposed (both abort the stream). A comment line goes out every 15 seconds so proxies and browsers keep an idle stream open.
+   * is disposed (both abort the stream). A comment line goes out every 15 seconds so proxies and browsers keep an idle stream open. A string value travels as it is; with `json`
+   * (the `?json=1` of the browser client) every value is JSON, so `"12"` and `12` can be told apart.
    */
-  stream(key: string, c: RequestContext): Response | undefined {
+  stream(key: string, c: RequestContext, json = false): Response | undefined {
     const cell = this.find(key)
     if (cell === undefined) return undefined
     return streamSSE(c, async stream => {
@@ -83,7 +90,7 @@ export class State extends Service {
       // Writes are asynchronous; chaining them keeps events in the order the cell changed.
       let queue: Promise<unknown> = Promise.resolve()
       const send = (value: unknown): void => {
-        queue = queue.then(() => stream.writeSSE({ event: 'value', data: typeof value === 'string' ? value : JSON.stringify(value) })).catch(() => {})
+        queue = queue.then(() => stream.writeSSE({ event: 'value', data: typeof value === 'string' && !json ? value : JSON.stringify(value) })).catch(() => {})
       }
       send(cell.get())
       const unsubscribe = cell.subscribe(send)
@@ -105,14 +112,34 @@ export function apply(ctx: Context): void {
   // app; the terminal calls the router in process and is the host's own code.
   ctx.inject(['router'], inner => {
     const api = new Acryl()
+    // The WebSocket form is mounted when a server that upgrades appears (the server row comes after this one in a blend); until then, and without the `ws` package, `/ws` answers 404 and the
+    // browser client follows the event streams. The route is registered before `/:key`, which would otherwise take `ws` for a key.
+    let socket: MiddlewareHandler | undefined
     api.use(loopbackOnly({ inProcess: 'allow' }), methodNotAllowed({ app: api }))
       .get('/', c => c.json({ keys: state.keys() }))
+      .get('/client.js', c => c.body(CLIENT_SOURCE, 200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-cache' }))
+      .get('/ws', async (c, next) => {
+        const upgrade = socket
+        if (upgrade === undefined) return c.json({ error: 'this server does not upgrade to a WebSocket' }, 404)
+        const refusal = refuseStranger(c)
+        if (refusal !== undefined) return refusal
+        return await upgrade(c, next)
+      })
       .get('/:key', c => {
         const cell = state.find(c.req.param('key'))
         return cell === undefined ? c.json({ error: 'no such state' }, 404) : c.json({ key: cell.key, value: cell.get() })
       })
-      .get('/:key/events', c => state.stream(c.req.param('key'), c) ?? c.json({ error: 'no such state' }, 404))
+      .get('/:key/events', c => state.stream(c.req.param('key'), c, c.req.query('json') === '1') ?? c.json({ error: 'no such state' }, 404))
     inner.router.route('/api/state', api)
+    inner.inject(['nodeServer'], withServer => {
+      try {
+        const upgrade = (withServer as unknown as { nodeServer: { upgrades(): UpgradeWebSocket } }).nodeServer.upgrades()
+        socket = stateSocket(state, { upgrade })
+        withServer.effect(() => () => { socket = undefined }, 'acryl-state: the WebSocket route')
+      } catch (cause) {
+        ctx.logger.warn(`acryl-state: state is followed by event streams only (${cause instanceof Error ? cause.message : String(cause)})`)
+      }
+    })
     // Over HTTP only where an adapter exists (Web and Desktop); the terminal needs none.
     inner.inject(['routerHttp'], http => { http.routerHttp.mount('/api/state') })
   })