acrylblends 1.0.10 → 1.2.0

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

@@ -7,6 +7,8 @@
  * response body still streaming and waits for all of it to settle.
  */
 
+import { appendFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { Context, Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import type { ConnectionInfo, RouterBindings } from './connection.ts'
@@ -21,6 +23,27 @@ import type { ErrorHandler, H, NotFoundHandler } from './core/types.ts'
 
 const DEFAULT_DISPOSE_GRACE_MS = 2000
 
+/** How long disposal waits for the flights it had to abort after the drain, before it continues without them. */
+const ABORT_SETTLE_MS = 300
+
+/** Set by ACRYL_ROUTER_TRACE=1: append request-signal lifecycle lines to ACRYL_ROUTER_TRACE_FILE (the CI artifact) - diagnostics for the abort-reaches-handler defect. */
+const traceFile = (): string => process.env.ACRYL_ROUTER_TRACE_FILE ?? `${tmpdir()}/acryl-router-trace.log`
+const trace = (line: string): void => {
+  if (process.env.ACRYL_ROUTER_TRACE !== '1') return
+  try { appendFileSync(traceFile(), `${String(Date.now())} [${String(process.pid)}] ${line}\n`) } catch { /* tracing never affects a request */ }
+}
+let flightSeq = 0
+const SIGNAL_TAG = Symbol.for('acryl.router.signalTag')
+const tagOf = (signal: AbortSignal | undefined): string => {
+  if (signal === undefined) return 'none'
+  const tag = (signal as unknown as Record<symbol, unknown>)[SIGNAL_TAG]
+  return typeof tag === 'string' ? tag : 'untagged'
+}
+const tagSignal = (signal: AbortSignal, tag: string): void => {
+  try { (signal as unknown as Record<symbol, unknown>)[SIGNAL_TAG] = tag } catch { /* a frozen signal keeps no tag */ }
+}
+
+
 /** How a trailing slash is read: `strict` keeps `/a` and `/a/` distinct, `ignore` treats them as one path. */
 export type TrailingSlash = 'strict' | 'ignore'
 
@@ -105,6 +128,10 @@ interface RouterState {
 
 interface Flight {
   readonly controller: AbortController
+  /** The request the handlers run on (the caller's request with the flight's signal): held strongly for the flight's lifetime, so its signal cannot be collected under a listener. */
+  readonly inner: Request
+  /** Names the flight in the ACRYL_ROUTER_TRACE diagnostics. */
+  readonly tag: string
   /** How many of each mount's handlers are running for this request right now (a middleware counts until its `next()` returns). */
   readonly running: Map<Mount, number>
   /** The mount whose handler produced the response; its body is that mount's code still running. */
@@ -150,8 +177,8 @@ export class Router extends Service {
     }
     ctx.effect(() => async () => {
       this.state.closing = true
-      await this.end([...this.flights], 'disposal')
-    }, 'acryl-router: abort and settle in-flight requests')
+      await this.drain()
+    }, 'acryl-router: drain in-flight requests, then abort what is left')
   }
 
   /** Registrations currently held (mounts, and the router-wide error and not-found handlers); a leak check for reload tests. */
@@ -168,12 +195,16 @@ export class Router extends Service {
     const mount = this.snapshot(path, app)
     this.state.mounts.add(mount)
     this.state.composed = undefined
-    // Removing a mount ends the requests its code is still serving: their signals abort, a body it produced is cancelled, and the
-    // plugin's unload waits for them (bounded by `disposeGraceMs`), so nothing a plugin started outlives it.
+    // Removing a mount ends the requests its code is still serving: they get the grace to finish first (a save being written when its plugin unloads,
+    // or when the whole app stops and every plugin unloads together, must not be cut), and only then are their signals aborted, their bodies cancelled
+    // and their settle awaited, so nothing a plugin started outlives it by more than that bounded grace.
     const remove = (): Promise<void> => {
       if (!this.state.mounts.delete(mount)) return Promise.resolve()
       this.state.composed = undefined
-      return this.end([...this.flights].filter(flight => (flight.running.get(mount) ?? 0) > 0 || flight.producer === mount), `removing ${path}`)
+      return this.drainFlights(
+        [...this.flights].filter(flight => (flight.running.get(mount) ?? 0) > 0 || flight.producer === mount),
+        `removing ${path}`,
+      )
     }
     // Each route the mount serves is a child effect of it, labeled on its own, so the inspector can report routes without asking the
     // router and no label grows with the size of the app (`ALL` is middleware or `all`). The children hold nothing: the mount does.
@@ -215,6 +246,7 @@ export class Router extends Service {
       const handler: H = async (c, next) => {
         const flight = this.flightOf.get(c.req.raw)
         if (flight === undefined) return inner(c, next)
+        trace(`handler ${flight.tag} requestTag=${tagOf(c.req.raw.signal)} innerTag=${tagOf(flight.inner.signal)} sameSignal=${String(c.req.raw.signal === flight.inner.signal)} aborted=${String(c.req.raw.signal.aborted)}`)
         let calledNext = false
         flight.running.set(mount, (flight.running.get(mount) ?? 0) + 1)
         try {
@@ -234,18 +266,46 @@ export class Router extends Service {
     return mount
   }
 
-  /** Abort `flights`, cut their bodies short and wait for them to settle, at most `disposeGraceMs`. */
-  private async end(flights: readonly Flight[], why: string): Promise<void> {
+  /**
+   * The router's own disposal: let the flights already in flight finish within `disposeGraceMs` - a save being written when the app stops must not be cut
+   * by the router beneath it - then abort what is left and settle it for a moment, so disposal does not wait a second full grace on code that ignores
+   * its abort signal.
+   */
+  private async drain(): Promise<void> {
+    await this.drainFlights([...this.flights], 'disposal')
+  }
+
+  /** The one draining rule: let `flights` finish inside the grace, then abort and settle what is left. */
+  private async drainFlights(flights: readonly Flight[], why: string): Promise<void> {
+    trace(`drain ${why} chosen=[${flights.map(flight => flight.tag).join(', ')}]`)
+    if (flights.length === 0) return
+    if (await this.settledWithin(flights, this.graceMs)) { trace(`drain ${why} settled inside the grace`); return }
+    const left = flights.filter(flight => this.flights.has(flight))
+    trace(`drain ${why} grace over left=[${left.map(flight => flight.tag).join(', ')}]`)
+    if (left.length > 0) await this.end(left, why, ABORT_SETTLE_MS)
+  }
+
+  /** Resolve true when every flight settled inside `ms`, false at the deadline. */
+  private async settledWithin(flights: readonly Flight[], ms: number): Promise<boolean> {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const gaveUp = new Promise<false>(resolve => { timer = setTimeout(() => { resolve(false) }, ms) })
+    const outcome = await Promise.race([Promise.allSettled(flights.map(flight => flight.settled)).then(() => true as const), gaveUp])
+    clearTimeout(timer)
+    return outcome
+  }
+
+  /** Abort `flights`, cut their bodies short and wait for them to settle, at most `settleMs`. */
+  private async end(flights: readonly Flight[], why: string, settleMs: number = this.graceMs): Promise<void> {
     if (flights.length === 0) return
     for (const flight of flights) {
+      trace(`abort ${flight.tag} before=${String(flight.controller.signal.aborted)}`)
       flight.controller.abort()
+      trace(`abort ${flight.tag} after=${String(flight.controller.signal.aborted)} innerAborted=${String(flight.inner.signal.aborted)}`)
+      queueMicrotask(() => { trace(`post-abort ${flight.tag} innerAborted=${String(flight.inner.signal.aborted)}`) })
       flight.endBody()
     }
-    let timer: ReturnType<typeof setTimeout> | undefined
-    const gaveUp = new Promise<'gave-up'>(resolve => { timer = setTimeout(() => { resolve('gave-up') }, this.graceMs) })
-    const outcome = await Promise.race([Promise.allSettled(flights.map(flight => flight.settled)).then(() => 'settled' as const), gaveUp])
-    clearTimeout(timer)
-    if (outcome === 'gave-up') this.ctx.logger.warn(`acryl-router: ${String(flights.length)} request(s) did not finish ${String(this.graceMs)} ms after abort (${why}); continued without them`)
+    if (await this.settledWithin(flights, settleMs)) return
+    this.ctx.logger.warn(`acryl-router: ${String(flights.length)} request(s) did not finish ${String(settleMs)} ms after abort (${why}); continued without them`)
   }
 
   /** Turn errors no mounted app handled into responses. One handler per router; the calling plugin owns it. */
@@ -292,7 +352,7 @@ export class Router extends Service {
    * `bindings` is an object an adapter hands to the handler as `c.env` (an upgrade request's socket hooks, for `upgradeWebSocket`); `connection` is added to it.
    */
   fetch(request: Request, connection: ConnectionInfo = {}, bindings?: object): Promise<Response> {
-    if (this.state.closing) return Promise.resolve(new Response('Service Unavailable', { status: 503 }))
+    if (this.state.closing) return Promise.resolve(new Response('Service Unavailable', { status: 503, headers: { connection: 'close' } }))
     const controller = new AbortController()
     const forward = (): void => controller.abort()
     if (request.signal.aborted) controller.abort()
@@ -308,8 +368,11 @@ export class Router extends Service {
     let bodyDone: Promise<void> = Promise.resolve()
     let endBody = (): void => {}
     let resolveSettled!: (value: Promise<unknown>) => void
-    const flight: Flight = { controller, running: new Map(), producer: undefined, endBody: () => { endBody() }, settled: new Promise(resolve => { resolveSettled = resolve }) }
+    const tag = `f${String(++flightSeq)}`
     const inner = new Request(request, { signal: controller.signal })
+    tagSignal(inner.signal, tag)
+    const flight: Flight = { controller, inner, tag, running: new Map(), producer: undefined, endBody: () => { endBody() }, settled: new Promise(resolve => { resolveSettled = resolve }) }
+    trace(`create ${tag} ${request.method} ${new URL(request.url).pathname}`)
     this.flightOf.set(inner, flight)
     // The caller gets the Response the moment the handler returns it; the flight lasts until its body ends and every waitUntil task settles.
     const response = this.dispatch(inner, env, executionCtx).then(raw => {

package/plugins/acryl-router-http/src/index.ts

@@ -41,6 +41,10 @@ export class RouterHttp extends Service implements RouterHttpService {
   private readonly router: Context['router']
   private readonly web: WebServerPort
   private hub: UpgradeHub | undefined
+  /** One upgrade helper per calling context: a fresh wrapper per call made every service event look like an owner change. */
+  private readonly upgradeHelpers = new WeakMap<object, UpgradeWebSocket>()
+  /** A stable identity for this service instance's hub: a caller that must recognize the same owner across calls keys on this, not on a helper. */
+  private readonly hubIdentity: object = {}
   /** The adapter's own context: the hub lives as long as the adapter, whichever plugin asked for it first (`this.ctx` is the caller's). */
   private readonly home: Context
   private readonly upgradesIn = new UpgradeEmitter()
@@ -99,8 +103,18 @@ export class RouterHttp extends Service implements RouterHttpService {
    * `upgradeWebSocket` for the calling plugin: the sockets its routes accept are closed with 1001 when it unloads. Needs the `ws` package.
    * The route must be on a path the plugin mounted with `upgrade: [path]`.
    */
+  /** Stable for this service's lifetime; a re-provided adapter has a new one, which is how a caller sees a new owner. */
+  hubToken(): object {
+    return this.hubIdentity
+  }
+
   upgrades(): UpgradeWebSocket {
-    return this.ensureHub().upgradeWebSocketFor(this.ctx) as unknown as UpgradeWebSocket
+    const owner = this.ctx
+    const cached = this.upgradeHelpers.get(owner)
+    if (cached !== undefined) return cached
+    const created = this.ensureHub().upgradeWebSocketFor(owner) as unknown as UpgradeWebSocket
+    this.upgradeHelpers.set(owner, created)
+    return created
   }
 
   /** How many WebSocket connections are open now. */

package/plugins/acryl-router-http/src/serve.ts

@@ -6,6 +6,35 @@ export interface FetchRouter {
   fetch(request: Request, connection?: { readonly remoteAddress?: string | undefined, readonly localPort?: number | undefined }): Promise<Response>
 }
 
+/** How long a refusal waits for a request body the handler never read. */
+export const REQUEST_BODY_SETTLE_MS = 1_000
+
+/**
+ * Read and discard a request body the handler left unread (a guard's 403, a 415, a body over its limit), so the client can finish sending and
+ * read the answer. Ending a response while request data is still arriving makes Node close the socket with that data pending, and the peer sees a
+ * reset instead of the answer: reliably on Windows (the workspace git worktree test's read ECONNRESET) and on other systems under load. Bounded:
+ * a client that stops sending waits at most `ms`, then loses the socket as before.
+ */
+export function settleRequestBody(req: IncomingMessage, ms: number = REQUEST_BODY_SETTLE_MS): Promise<void> {
+  if (req.readableEnded || req.destroyed) return Promise.resolve()
+  return new Promise<void>((resolve) => {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const done = (): void => {
+      if (timer !== undefined) clearTimeout(timer)
+      req.off('end', done)
+      req.off('close', done)
+      req.off('error', done)
+      resolve()
+    }
+    timer = setTimeout(done, ms)
+    timer.unref?.()
+    req.once('end', done)
+    req.once('close', done)
+    req.once('error', done)
+    req.resume()
+  })
+}
+
 /**
  * Serve one node request through the router and write the result. The request's abort signal fires when the client
  * disconnects before the response finished; the socket's peer address and local port travel as connection info, never in the request.
@@ -20,5 +49,7 @@ export async function serve(router: FetchRouter, req: IncomingMessage, res: Serv
   } catch {
     response = new Response('Internal Server Error', { status: 500 })
   }
+  // The handler may have answered without reading the body; let the client finish sending before the answer ends the connection.
+  if (method !== 'GET' && method !== 'HEAD') await settleRequestBody(req)
   await sendResponse(res, response, method)
 }

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