acrylblends 0.10.0 → 0.11.0

package/plugins/acryl-node-server/src/index.ts

@@ -17,9 +17,14 @@ import z from '@deepseek-ai/schemastery'
 import type {} from 'acryl-router'
 import { Request as AdapterRequest } from './adapter/request.ts'
 import { createAdaptorServer } from './adapter/server.ts'
+import { UpgradeHub, type UpgradeHubOptions } from './upgrade-hub.ts'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
+import type { WebSocketLike } from './adapter/websocket-types.ts'
 
 export { serveStatic, type ServeStaticOptions } from './adapter/serve-static.ts'
 export { RequestError } from './adapter/request.ts'
+export { testWebSocket, type TestSocket, type TestWebSocketOptions, type TestWebSocketResult } from './test-websocket.ts'
+export { UpgradeEmitter, UpgradeHub, type UpgradeHubOptions, type UpgradeRouter } from './upgrade-hub.ts'
 
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
 export const name = 'acryl-node-server'
@@ -29,6 +34,8 @@ export interface Config {
   hostname: string
   port: number
   scan: number
+  /** Limits of WebSocket upgrades (`upgrades()`); the defaults suit most apps. */
+  websocket: UpgradeHubOptions
 }
 
 /** Every field has a default, so a caller passes only what it changes: `ctx.plugin(plugin, { ... })` takes the partial shape. */
@@ -36,6 +43,13 @@ export const Config: z<Partial<Config>, Config> = z.object({
   hostname: z.string().default('127.0.0.1').description('Address to bind. Loopback by default; binding elsewhere exposes the app to the network.'),
   port: z.number().min(0).max(65535).default(0).description('Port to listen on; 0 lets the system choose. A taken port is followed by the next free one.'),
   scan: z.number().min(0).default(20).description('How many further ports to try when the configured one is taken.'),
+  websocket: z
+    .object({
+      maxPayload: z.number().min(1).default(1024 * 1024).description('The largest WebSocket frame accepted, in bytes; a bigger one closes the socket with 1009.'),
+      heartbeat: z.number().min(0).default(30_000).description('Milliseconds between pings; a peer that did not answer the last one is terminated. 0 turns it off.'),
+      grace: z.number().min(0).default(2000).description('Milliseconds a closing socket gets before it is terminated when its plugin unloads.'),
+    })
+    .default({}),
 })
 
 declare module '@deepseek-ai/cordis' {
@@ -48,6 +62,7 @@ export class NodeServer extends Service {
   readonly hostname: string
   readonly config: Config
   private readonly server: Server
+  private hub: UpgradeHub | undefined
   private bound = 0
 
   constructor(ctx: Context, config: Config) {
@@ -64,11 +79,30 @@ export class NodeServer extends Service {
       overrideGlobalObjects: false,
     }) as Server
     ctx.effect(() => async () => {
+      await this.hub?.close()
       this.server.closeAllConnections()
       if (this.server.listening) await new Promise<void>(resolve => { this.server.close(() => { resolve() }) })
     }, 'acryl-node-server: close listener and open connections')
   }
 
+  /**
+   * `upgradeWebSocket` for the plugin that asks (call it once, in `apply`): `app.get('/ws', upgrade((c) => ({ onMessage(event, ws) { ... } })))`. Checks go in ordinary middleware on the
+   * route, and a handler that returns a `Response` refuses the upgrade with that status before any handshake. Every socket it accepts belongs to the calling plugin: when the plugin
+   * unloads they are closed with 1001 within `websocket.grace` and the handler sees `close` once. Pass `{ textOnly: true }` to drop binary frames. Needs the `ws` package.
+   */
+  upgrades(): UpgradeWebSocket<WebSocketLike> {
+    if (!this.hub) {
+      this.hub = new UpgradeHub(this.config.websocket)
+      this.hub.attach(this.server, this.ctx.router)
+    }
+    return this.hub.upgradeWebSocketFor(this.ctx)
+  }
+
+  /** How many WebSocket connections are open now. */
+  get sockets(): number {
+    return this.hub?.size ?? 0
+  }
+
   /** The port in use, 0 before the server listens. */
   get port(): number {
     return this.bound
@@ -113,6 +147,6 @@ export function isPortUnavailable(error: unknown, platform: NodeJS.Platform = pr
 
 /** Loads once the server listens, so a plugin that injects `nodeServer` can rely on `url`. A failure to bind fails the plugin. */
 export async function apply(ctx: Context, config: Partial<Config> = {}): Promise<void> {
-  const server = new NodeServer(ctx, { hostname: '127.0.0.1', port: 0, scan: 20, ...config })
+  const server = new NodeServer(ctx, { hostname: '127.0.0.1', port: 0, scan: 20, websocket: {}, ...config })
   await server.listen()
 }

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

@@ -0,0 +1,110 @@
+/**
+ * An in-process WebSocket pair for tests (spec 047 T009): runs an upgrade route the way the adapters do, with no socket and no network. `testWebSocket(fetch, '/path', { headers })`
+ * answers either a refusal (`status`, no `socket`) or an accepted connection whose client side sends text frames, receives what the handler sent, and closes.
+ *
+ *   const { socket } = await testWebSocket((request, env) => app.fetch(request, env), '/stream', { headers: { origin: 'http://127.0.0.1:3000' } })
+ *   socket.send('hello'); expect(socket.received).toEqual(['echo hello'])
+ */
+import type { IncomingMessage } from 'node:http'
+import { CONNECTION_SYMBOL_KEY, WAIT_FOR_WEBSOCKET_SYMBOL } from './adapter/websocket.ts'
+import type { WebSocketData, WebSocketLike } from './adapter/websocket-types.ts'
+
+type Listener = (...args: never[]) => void
+
+/** The client side of an accepted test connection. */
+export interface TestSocket {
+  /** Frames the handler sent, in order (text only). */
+  readonly received: string[]
+  /** The code and reason the handler closed with, when it did. */
+  readonly closed: { readonly code: number | undefined; readonly reason: string | undefined } | undefined
+  /** Send a text frame to the handler. */
+  send(text: string): void
+  /** Close from the client side. */
+  close(code?: number, reason?: string): void
+}
+
+export interface TestWebSocketOptions {
+  readonly headers?: Record<string, string>
+  /** The socket's peer address and local port, as an adapter would pass them. */
+  readonly connection?: { readonly remoteAddress?: string; readonly localPort?: number }
+  /** The URL origin the request is made against; default `http://127.0.0.1`. */
+  readonly base?: string
+}
+
+export interface TestWebSocketResult {
+  /** The refusal's status, or 101 when the upgrade was accepted. */
+  readonly status: number
+  readonly socket?: TestSocket
+}
+
+/** A fake `ws` socket: events go both ways without a network. */
+class FakeSocket implements WebSocketLike {
+  protocol = ''
+  readyState: 0 | 1 | 2 | 3 = 1
+  bufferedAmount = 0
+  readonly sent: string[] = []
+  closedWith: { code: number | undefined; reason: string | undefined } | undefined
+  private readonly listeners = new Map<string, Listener[]>()
+  on(event: string, listener: Listener): this {
+    this.listeners.set(event, [...(this.listeners.get(event) ?? []), listener])
+    return this
+  }
+  off(event: string, listener: Listener): this {
+    this.listeners.set(event, (this.listeners.get(event) ?? []).filter(l => l !== listener))
+    return this
+  }
+  emit(event: string, ...args: unknown[]): void {
+    for (const listener of this.listeners.get(event) ?? []) (listener as (...a: unknown[]) => void)(...args)
+  }
+  send(data: WebSocketData | ArrayBufferView): void {
+    this.sent.push(typeof data === 'string' ? data : Buffer.from(data as Uint8Array).toString('utf8'))
+  }
+  close(code?: number, reason?: string): void {
+    if (this.readyState === 3) return
+    this.closedWith = { code, reason }
+    this.readyState = 3
+    this.emit('close', code ?? 1005, Buffer.from(reason ?? ''))
+  }
+  ping(): void {}
+  terminate(): void {
+    this.close(1006)
+  }
+}
+
+export async function testWebSocket(
+  fetch: (request: Request, env: object) => Promise<Response>,
+  path: string,
+  options: TestWebSocketOptions = {},
+): Promise<TestWebSocketResult> {
+  const fake = new FakeSocket()
+  let waiter: { connectionSymbol: symbol; resolve: (ws: WebSocketLike) => void } | undefined
+  const incoming = { headers: options.headers ?? {}, socket: { remoteAddress: options.connection?.remoteAddress, localPort: options.connection?.localPort } } as unknown as IncomingMessage
+  const env: Record<symbol | string, unknown> = {
+    incoming,
+    outgoing: undefined,
+    wss: {},
+    [WAIT_FOR_WEBSOCKET_SYMBOL]: (_request: IncomingMessage, connectionSymbol: symbol) =>
+      new Promise<WebSocketLike>(resolve => {
+        waiter = { connectionSymbol, resolve }
+      }),
+  }
+  const headers = new Headers({ upgrade: 'websocket', connection: 'Upgrade', ...options.headers })
+  const response = await fetch(new Request(new URL(path, options.base ?? 'http://127.0.0.1'), { headers }), env)
+  if (!waiter || waiter.connectionSymbol !== env[CONNECTION_SYMBOL_KEY]) return { status: response.status }
+  waiter.resolve(fake)
+  // The handler's open event and buffered messages run on the next turns.
+  await new Promise(resolve => setTimeout(resolve, 0))
+  const socket: TestSocket = {
+    received: fake.sent,
+    get closed() {
+      return fake.closedWith
+    },
+    send: text => fake.emit('message', text, false),
+    close: (code, reason) => {
+      if (fake.readyState === 3) return
+      fake.readyState = 3
+      fake.emit('close', code ?? 1005, Buffer.from(reason ?? ''))
+    },
+  }
+  return { status: 101, socket }
+}

package/plugins/acryl-node-server/src/upgrade-hub.ts

@@ -0,0 +1,152 @@
+/**
+ * WebSocket upgrades for the Cordis adapters (spec 047 T009): one hub per HTTP transport. It owns the `ws` server (text and size limits, no compression), runs the ported
+ * `setupWebSocket` on whatever emits `upgrade` events (a `node:http` server, or the Host web server's exact-path upgrade routes), pings every socket and ends the ones that stop
+ * answering, and gives each mounting plugin an `upgradeWebSocket` whose accepted sockets belong to that plugin: when it unloads they are closed with 1001 within the grace, and
+ * what is left is terminated. The handler sees `close` exactly once.
+ */
+import { EventEmitter } from 'node:events'
+import { createRequire } from 'node:module'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
+import type { FetchCallback } from './adapter/types.ts'
+import { type UpgradeSource, setupWebSocket, upgradeWebSocket as portedUpgradeWebSocket } from './adapter/websocket.ts'
+import type { WebSocketLike, WebSocketServerLike } from './adapter/websocket-types.ts'
+
+export interface UpgradeHubOptions {
+  /** The largest frame accepted, in bytes; a bigger one closes the socket with 1009. Default 1 MiB. */
+  maxPayload?: number
+  /** Milliseconds between pings; a peer that did not answer the previous one is terminated. Default 30 000; 0 turns the heartbeat off. */
+  heartbeat?: number
+  /** Milliseconds a closing socket gets to finish its close handshake before it is terminated. Default 2000. */
+  grace?: number
+}
+
+type WebSocketServerConstructor = new (options: {
+  noServer: true
+  maxPayload: number
+  perMessageDeflate: false
+}) => WebSocketServerLike
+
+/** The `ws` package, loaded when the first hub is made: an app that never upgrades does not need it. */
+function loadWs(): WebSocketServerConstructor {
+  try {
+    return (createRequire(import.meta.url)('ws') as { WebSocketServer: WebSocketServerConstructor }).WebSocketServer
+  } catch (error) {
+    throw new Error(`WebSocket upgrades need the "ws" package (npm install ws): ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+/** The part of the router a hub calls: run a request with connection facts and the adapter's bindings. */
+export interface UpgradeRouter {
+  fetch(request: Request, connection: { remoteAddress?: string | undefined; localPort?: number | undefined }, bindings?: object): Promise<Response>
+}
+
+/** What a hub needs of a Cordis context: tying a disposer to the plugin that asked. */
+export interface Owner {
+  effect(execute: () => () => unknown, label?: string): unknown
+}
+
+export class UpgradeHub {
+  readonly server: WebSocketServerLike
+  private readonly all = new Set<WebSocketLike>()
+  private readonly alive = new WeakMap<WebSocketLike, boolean>()
+  private readonly grace: number
+  private timer: ReturnType<typeof setInterval> | undefined
+  private closed = false
+
+  constructor(options: UpgradeHubOptions = {}) {
+    const Server = loadWs()
+    this.server = new Server({ noServer: true, maxPayload: options.maxPayload ?? 1024 * 1024, perMessageDeflate: false })
+    this.grace = options.grace ?? 2000
+    this.server.on('connection', ws => {
+      this.all.add(ws)
+      this.alive.set(ws, true)
+      ws.on('pong', () => this.alive.set(ws, true))
+      ws.on('close', () => this.all.delete(ws))
+    })
+    const heartbeat = options.heartbeat ?? 30_000
+    if (heartbeat > 0) {
+      this.timer = setInterval(() => {
+        for (const ws of this.all) {
+          if (this.alive.get(ws) === false) {
+            ws.terminate()
+            continue
+          }
+          this.alive.set(ws, false)
+          ws.ping()
+        }
+      }, heartbeat)
+      this.timer.unref()
+    }
+  }
+
+  /**
+   * Accept upgrades from `source` and answer them with `router`: the request runs through the router's middleware with the socket's peer address and local port as connection
+   * facts (so the same loopback, origin and host checks work), and the upgrade bindings travel in `c.env` for `upgradeWebSocket`.
+   */
+  attach(source: UpgradeSource, router: UpgradeRouter): void {
+    const fetchCallback: FetchCallback = (request, env) => {
+      const { incoming } = env as { incoming: { socket: { remoteAddress?: string; localPort?: number } } }
+      return router.fetch(request, { remoteAddress: incoming.socket.remoteAddress, localPort: incoming.socket.localPort }, env)
+    }
+    setupWebSocket({ server: source, fetchCallback, wss: this.server })
+  }
+
+  /** How many sockets are open. */
+  get size(): number {
+    return this.all.size
+  }
+
+  /** `upgradeWebSocket` for the plugin `owner`: the sockets it accepts are closed with 1001 when that plugin unloads. */
+  upgradeWebSocketFor(owner: Owner): UpgradeWebSocket<WebSocketLike> {
+    const mine = new Set<WebSocketLike>()
+    owner.effect(() => () => this.closeAll(mine, 1001, 'going away'), 'upgrade sockets')
+    const track = (ws: WebSocketLike): void => {
+      mine.add(ws)
+      ws.on('close', () => mine.delete(ws))
+    }
+    const owned = (...args: unknown[]): unknown => {
+      const [first, second, third] = args as [unknown, Record<string, unknown> | undefined, Record<string, unknown> | undefined]
+      return typeof first === 'function'
+        ? (portedUpgradeWebSocket as (...a: unknown[]) => unknown)(first, { ...second, track })
+        : (portedUpgradeWebSocket as (...a: unknown[]) => unknown)(first, second, { ...third, track })
+    }
+    return owned as UpgradeWebSocket<WebSocketLike>
+  }
+
+  /** Close `sockets` with `code`, wait for their close handshakes up to the grace, terminate what is left. */
+  async closeAll(sockets: Iterable<WebSocketLike>, code: number, reason: string): Promise<void> {
+    const open = [...sockets].filter(ws => ws.readyState < 3)
+    await Promise.all(
+      open.map(
+        ws =>
+          new Promise<void>(resolve => {
+            const timer = setTimeout(() => {
+              ws.terminate()
+              resolve()
+            }, this.grace)
+            ws.on('close', () => {
+              clearTimeout(timer)
+              resolve()
+            })
+            if (ws.readyState === 1) ws.close(code, reason)
+            else if (ws.readyState === 3) {
+              clearTimeout(timer)
+              resolve()
+            }
+          }),
+      ),
+    )
+  }
+
+  /** End everything: every socket closes with 1001, the heartbeat stops, the `ws` server closes. */
+  async close(): Promise<void> {
+    if (this.closed) return
+    this.closed = true
+    if (this.timer !== undefined) clearInterval(this.timer)
+    await this.closeAll(this.all, 1001, 'going away')
+    this.server.close()
+  }
+}
+
+/** A stand-in for a server's `upgrade` events, for transports that dispatch upgrades themselves (the Host web server's exact-path routes). */
+export class UpgradeEmitter extends EventEmitter {}

package/plugins/acryl-router/src/core/helper/websocket/index.ts

@@ -54,6 +54,8 @@ export interface WSContextInit<T = unknown> {
 
   raw?: T
   readyState: WSReadyState
+  /** Bytes queued to send and not yet written to the socket; a sender that cares about back-pressure reads it. */
+  bufferedAmount?: number
   url?: string | URL | null
   protocol?: string | null
 }
@@ -84,6 +86,9 @@ export class WSContext<T = unknown> {
   get readyState(): WSReadyState {
     return this.#init.readyState
   }
+  get bufferedAmount(): number {
+    return this.#init.bufferedAmount ?? 0
+  }
   url: URL | null
   protocol: string | null
   close(code?: number, reason?: string) {

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

@@ -10,6 +10,7 @@
 import { Context, Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import type { ConnectionInfo, RouterBindings } from './connection.ts'
+import type { UpgradeWebSocket } from './core/helper/websocket/index.ts'
 import { Acryl } from './core/app.ts'
 import type { ExecutionContext } from './core/context.ts'
 import { HTTPException } from './core/http-exception.ts'
@@ -40,8 +41,19 @@ export const Config: z<Partial<Config>, Config> = z.object({
  * served over HTTP without depending on the adapter package.
  */
 export interface RouterHttpService {
-  /** Serve `prefix` and everything below it through the router; returns a remover. The mount also goes away when the calling plugin unloads. */
-  mount(prefix: string): () => void
+  /**
+   * Serve `prefix` and everything below it through the router; returns a remover. The mount also goes away when the calling plugin unloads.
+   * `options.upgrade` lists the exact paths below the prefix that may be upgraded to a WebSocket (each must be inside the prefix); no other path of the mount accepts an upgrade.
+   */
+  mount(prefix: string, options?: { readonly upgrade?: readonly string[] }): () => void
+  /**
+   * `upgradeWebSocket` for the calling plugin: `app.get('/terminal', upgrade((c) => ({ onMessage(event, ws) { ... } })))` on a route the plugin mounted with `upgrade: ['/terminal']`.
+   * Checks go in ordinary middleware on the route; a handler that returns a `Response` refuses with that status before any handshake. The sockets it accepts belong to the calling
+   * plugin: when it unloads they are closed with 1001 and the handler sees `close` once. Needs the `ws` package.
+   */
+  upgrades(): UpgradeWebSocket
+  /** How many WebSocket connections are open now. */
+  readonly sockets: number
 }
 
 declare module '@deepseek-ai/cordis' {
@@ -260,8 +272,9 @@ export class Router extends Service {
    * Run a request in process. Never throws: failures become a 500, a disposed router answers 503. `connection` describes the transport
    * (an HTTP adapter passes the socket's peer address and local port); an in-process caller omits it. Handlers read it with
    * `connectionOf(c)`, abort with `c.req.raw.signal` and keep the request in flight with `c.executionCtx.waitUntil(task)`.
+   * `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 = {}): Promise<Response> {
+  fetch(request: Request, connection: ConnectionInfo = {}, bindings?: object): Promise<Response> {
     if (this.state.closing) return Promise.resolve(new Response('Service Unavailable', { status: 503 }))
     const controller = new AbortController()
     const forward = (): void => controller.abort()
@@ -273,7 +286,8 @@ export class Router extends Service {
       passThroughOnException: () => {},
       props: {},
     }
-    const env: RouterBindings = { connection }
+    // `bindings` is used as `c.env` itself (not copied): the upgrade helper records its handshake state on it, and the adapter reads that state back after the handler answered.
+    const env: RouterBindings = bindings === undefined ? { connection } : Object.assign(bindings, { connection })
     let bodyDone: Promise<void> = Promise.resolve()
     let endBody = (): void => {}
     let resolveSettled!: (value: Promise<unknown>) => void

package/plugins/acryl-router-http/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "acryl-router-http",
-  "description": "The serve() and request bridge that acryl-node-server uses to put the router on node:http. Mounting it as a plugin needs the DSH web server, which a generated app does not have. Vendored from ACRYL.",
-  "requires": ["acryl-router"],
+  "description": "Mounts router prefixes on the ACRYL Host's web server, with exact-path WebSocket upgrades owned by the mounting plugin, and the serve() and request bridge. Mounting it as a plugin needs the Host web server, which a generated app does not have. Vendored from ACRYL.",
+  "requires": ["acryl-router", "acryl-node-server"],
   "inject": ["router"],
   "provides": [],
   "dependencies": {

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

@@ -5,8 +5,11 @@
  */
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Duplex } from 'node:stream'
 import type { RouterHttpService } from 'acryl-router'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
 import { Context, Service } from '@deepseek-ai/cordis'
+import { UpgradeEmitter, UpgradeHub } from 'acryl-node-server'
 import { serve } from './serve.ts'
 
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
@@ -25,6 +28,11 @@ export interface WebServerPort {
     readonly path: string
     readonly handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
   }): () => void
+  /** One exact-path upgrade claim (`WebUpgradeRoute` of the web server); optional because an older web server has none. */
+  registerUpgrade?(route: {
+    readonly path: string
+    readonly handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>
+  }): () => void
 }
 
 const PREFIX_PATTERN = /^\/[A-Za-z0-9._~\-/]*[A-Za-z0-9._~-]$/
@@ -32,9 +40,14 @@ const PREFIX_PATTERN = /^\/[A-Za-z0-9._~\-/]*[A-Za-z0-9._~-]$/
 export class RouterHttp extends Service implements RouterHttpService {
   private readonly router: Context['router']
   private readonly web: WebServerPort
+  private hub: UpgradeHub | undefined
+  /** 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()
 
   constructor(ctx: Context) {
     super(ctx, 'routerHttp')
+    this.home = ctx
     this.router = ctx.router
     this.web = ctx.get('webServer') as WebServerPort
   }
@@ -42,17 +55,68 @@ export class RouterHttp extends Service implements RouterHttpService {
   /**
    * Serve `prefix` and everything below it through the router. Returns a remover; the mount also goes away when the
    * calling plugin unloads. A prefix another route already claims throws, as the webServer treats it as misconfiguration.
+   * `options.upgrade` names the exact paths that may be upgraded to a WebSocket: each must be inside the prefix, and each is one
+   * exact-path upgrade route of the web server, removed with the mount. No other path of the mount accepts an upgrade.
    */
-  mount(prefix: string): () => void {
+  mount(prefix: string, options: { readonly upgrade?: readonly string[] } = {}): () => void {
     if (!PREFIX_PATTERN.test(prefix)) throw new TypeError(`acryl-router-http: "${prefix}" is not a mountable path prefix`)
-    const remove = this.web.register({
-      kind: 'prefix',
-      path: prefix,
-      handler: (req, res) => serve(this.router, req, res),
-    })
+    const upgrade = options.upgrade ?? []
+    for (const path of upgrade) {
+      if (!PREFIX_PATTERN.test(path) || !(path === prefix || path.startsWith(`${prefix}/`)))
+        throw new TypeError(`acryl-router-http: the upgrade path "${path}" is not inside the prefix "${prefix}"`)
+    }
+    if (upgrade.length > 0 && this.web.registerUpgrade === undefined)
+      throw new TypeError('acryl-router-http: this web server cannot take WebSocket upgrades (it has no registerUpgrade)')
+    const removers: Array<() => void> = []
+    // Claim the upgrade paths first: a duplicate throws before anything is mounted, so a refused mount leaves nothing behind.
+    try {
+      if (upgrade.length > 0) this.ensureHub()
+      for (const path of upgrade) {
+        removers.push(
+          (this.web.registerUpgrade as NonNullable<WebServerPort['registerUpgrade']>)({
+            path,
+            handler: (req, socket, head) => { this.upgradesIn.emit('upgrade', req, socket, head) },
+          }),
+        )
+      }
+      removers.push(
+        this.web.register({
+          kind: 'prefix',
+          path: prefix,
+          handler: (req, res) => serve(this.router, req, res),
+        }),
+      )
+    } catch (error) {
+      for (const remove of removers) remove()
+      throw error
+    }
+    const remove = (): void => { for (const undo of removers.splice(0)) undo() }
     this.ctx.effect(() => () => { remove() }, `acryl-router-http: mount ${prefix}`)
     return remove
   }
+
+  /**
+   * `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]`.
+   */
+  upgrades(): UpgradeWebSocket {
+    return this.ensureHub().upgradeWebSocketFor(this.ctx) as unknown as UpgradeWebSocket
+  }
+
+  /** How many WebSocket connections are open now. */
+  get sockets(): number {
+    return this.hub?.size ?? 0
+  }
+
+  private ensureHub(): UpgradeHub {
+    if (!this.hub) {
+      const hub = new UpgradeHub()
+      hub.attach(this.upgradesIn, this.router)
+      this.hub = hub
+      this.home.effect(() => () => hub.close(), 'acryl-router-http: WebSocket hub')
+    }
+    return this.hub
+  }
 }
 
 export function apply(ctx: Context): void {

package/shared/AGENTS.core.md

@@ -19,7 +19,7 @@ The docs write `import { Acryl } from 'acrylblends'` and `from 'acrylblends/<sub
 
 **JSX: write `.tsx`.** The scripts in `package.json` run Node.js with `--import ./plugins/acryl-node-server/src/register.ts`, which compiles `.tsx` files with this app's own `typescript`; `tsconfig.json` sets `jsx: react-jsx` and `jsxImportSource: #acryl-jsx`, which `package.json`'s `imports` maps to the vendored runtime in `plugins/acryl-router`. See `src/about.tsx` (blank template) for a page and `test/app.test.ts` for how it is tested. Render a component with `.toString()` and return it with `c.html(...)`; import `jsx`, `Fragment` and the types from `../plugins/acryl-router/src/core/jsx/index.ts` when you need them. A command that starts the app without those scripts (a bare `node src/main.ts`) cannot load a `.tsx` file. Without a build step you can write the call JSX compiles to instead: `jsx('h1', { class: 'title' }, 'Hello')`, children after the props.
 
-A plugin written into `plugins/` while the app runs may use the docs' own names instead: `acrylblends` and `acrylblends/<subpath>` resolve to the same files. `App` is the
+**A plugin you install into the running app** (`.acryl/bin/acryl plugin add plugins/<name>`) **imports the framework by its package name**: `import { Acryl } from 'acrylblends'` (and `acrylblends/<subpath>`, for example `acrylblends/helpers`). `acrylblends` and `acrylblends/<subpath>` resolve to the same files as the relative paths above, and the plugin is checked in a staging copy where a relative path like `../plugins/acryl-router/src/index.ts` may not resolve (a plugin that wrote it failed its first install). Plugins that `src/app.ts` imports at start-up keep using the relative paths. `App` is the
 deprecated name of `Acryl`.
 
 ## How a feature is built

package/shared/DEFAULTS.md

@@ -26,7 +26,7 @@ install a second time). Do not create `src/plugins/` or `extensions/`.
 The door is a command in this folder, `.acryl/bin/acryl`, that lets you look at and change the running app. The running app writes it, and it reaches only the app running from this folder. Its state (a secret and an audit log) lives under `.acryl/`, which git ignores: never commit it. It is on in development and off with `NODE_ENV=production` or `ACRYL_DOOR=off`; one process at a time serves a folder's door, so a second `npm start` in the same folder stops with a message that says so (the tests set `ACRYL_DOOR=off`). If `.acryl/bin/acryl` is not here, the app is not running: start it with `npm run dev` (in the background) and open its address in a browser.
 
 ```
-.acryl/bin/acryl brief                      what this app is: its plugins, where the docs are, the verbs, and whether a page is open
+.acryl/bin/acryl brief                      what this app is: its address (curl a new route there), where the docs are, the verbs, and whether a page is open
 .acryl/bin/acryl look                       the page as text, with refs (1.1, 1.2, ...): roles, names, values, visible text
 .acryl/bin/acryl act click --ref <r>
 .acryl/bin/acryl act type --ref <r> --text <t> [--submit] [--no-clear]

package/lib/error-t4N2js2I.d.ts

@@ -1,8 +0,0 @@
-//#region ../../plugins/acryl-node-server/src/adapter/error.d.ts
-declare class RequestError extends Error {
-  constructor(message: string, options?: {
-    cause?: unknown;
-  });
-}
-//#endregion
-export { RequestError as t };