acrylblends 0.10.0 → 0.11.0

package/docs/framework/cordis/node-server.md

@@ -72,7 +72,29 @@ plugin that only mounted routes is different: its mount and the requests it is s
 Let the process configuration choose the address. Do not hard-code a development port in a reusable plugin: a plugin mounts routes and
 leaves the socket to whichever adapter the app runs with.
 
-## Not yet supported
+## WebSocket upgrades
 
-WebSocket upgrades under the router are a later task. The adapter's own WebSocket support exists in `src/adapter/` with its tests but is
-not wired to the router yet.
+A plugin takes WebSocket upgrades with `ctx.nodeServer.upgrades()` (or `ctx.routerHttp.upgrades()` on the Host's web server, with `ctx.routerHttp.mount(prefix, { upgrade: [paths] })` naming the exact paths). It returns the ported `upgradeWebSocket`; the route is an ordinary route with ordinary middleware in front of it:
+
+```ts
+export function apply(ctx: Context) {
+  const upgrade = ctx.nodeServer.upgrades()
+  ctx.router.route('/', new Acryl()
+    // Checks run before the upgrade: own page, loopback peer, exact Origin and Host. A refusal is a plain HTTP status with Connection: close, sent before any handshake.
+    .use('/terminal', ownPage)
+    .get('/terminal', upgrade(() => ({
+      onMessage(event, socket) {
+        if (socket.bufferedAmount < 1_000_000) socket.send(`echo ${String(event.data)}`)
+      },
+      onClose(event) {
+        // Called exactly once, whoever closed the socket.
+      },
+    }), { textOnly: true })))
+}
+```
+
+- **Limits.** Text frames only with `{ textOnly: true }` (binary frames never reach `onMessage`); `websocket.maxPayload` (default 1 MiB, a bigger frame closes the socket with 1009); no per-message compression; `socket.bufferedAmount` for back-pressure; `socket.close(code, reason)` with application codes such as 1013 or 4404 (a code the protocol forbids on the wire becomes 1011). No raw socket is exposed.
+- **Dead peers.** The server pings every `websocket.heartbeat` ms (default 30 000) and terminates a peer that did not answer the last ping. `websocket.grace` (default 2000) is how long a closing socket gets.
+- **Ownership.** The sockets a plugin's routes accepted belong to that plugin. When it unloads they are closed with 1001 within the grace (what is left is terminated), its handler sees `close` once, other plugins' sockets are untouched, and `ctx.nodeServer.sockets` counts what is still open. Stopping the server closes every socket.
+- **Needs `ws`.** `npm install ws`; an app that never upgrades does not need it.
+- **Tests.** `testWebSocket((request, env) => app.fetch(request, env), '/terminal', { headers })` from `acrylblends/node-server` runs the route and its middleware in process: a refusal answers `{ status }`, an accepted connection gives a `socket` that sends text frames, collects what the handler sent (`received`) and closes.

package/lib/bun.d.ts

@@ -1,7 +1,7 @@
 import { L as MiddlewareHandler, t as Context, v as Env } from "./context-DS3fYyG-.js";
 import { r as GetConnInfo } from "./types-Dv_nV2cv.js";
 import { f as FileSystemModule, m as ToSSGAdaptorInterface } from "./index-DaJtL7ci.js";
-import { a as WSEvents, n as UpgradeWebSocket } from "./index-BvFh1Gfx.js";
+import { a as WSEvents, n as UpgradeWebSocket } from "./index-C-SklY6u.js";
 import { t as ServeStaticOptions } from "./index-CseujaYI.js";
 
 //#region ../../plugins/acryl-router/src/core/adapter/bun/serve-static.d.ts

package/lib/cloudflare-workers.d.ts

@@ -1,6 +1,6 @@
 import { L as MiddlewareHandler, v as Env } from "./context-DS3fYyG-.js";
 import { r as GetConnInfo } from "./types-Dv_nV2cv.js";
-import { a as WSEvents, n as UpgradeWebSocket } from "./index-BvFh1Gfx.js";
+import { a as WSEvents, n as UpgradeWebSocket } from "./index-C-SklY6u.js";
 import { t as ServeStaticOptions$1 } from "./index-CseujaYI.js";
 
 //#region ../../plugins/acryl-router/src/core/adapter/cloudflare-workers/serve-static.d.ts

package/lib/cordis/door.d.ts

@@ -32,10 +32,11 @@ interface ToolsPort {
 interface DoorDeps {
   readonly channel: UiChannel;
   readonly audit: AuditLog;
-  /** The app's name and folder. */
+  /** The app's name, folder and, when it listens, its address (what `brief` prints so an agent can curl the running app). */
   readonly app: {
     readonly name: string;
     readonly root: string;
+    readonly url?: string | undefined;
   };
   /** Read at each call: the services may come and go while the door runs. */
   readonly extensions: () => ExtensionsPort | undefined;

package/lib/cordis/door.js

@@ -1,8 +1,8 @@
 import { t as Acryl } from "../app-BM0rTCp7.js";
 import { n as clientModules } from "../client-modules-CLvWOjbd.js";
 import { MAX_SNAPSHOT_NODES, MAX_WAIT_MS, UiControlError, parseUiRequest } from "../door/protocol.js";
-import { a as INVALID_JSON, c as operatorOnly, d as AuditLog, f as auditPath, i as DOOR_PREFIX, l as privateApi, o as error, p as UiChannel, r as pageChannelRoutes, s as jsonBody, t as renderSnapshot, u as readJson } from "../snapshot-text-D3NspDyT.js";
-import "../src-CwABFr6r.js";
+import { a as INVALID_JSON, c as operatorOnly, d as AuditLog, f as auditPath, i as DOOR_PREFIX, l as privateApi, o as error, p as UiChannel, r as pageChannelRoutes, s as jsonBody, t as renderSnapshot, u as readJson } from "../snapshot-text-yaWlezbd.js";
+import "../src-DNzw0Qsb.js";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { randomBytes } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
@@ -255,11 +255,12 @@ var Door = class {
 		}
 	}
 	brief() {
-		const { name, root } = this.deps.app;
+		const { name, root, url } = this.deps.app;
 		const read = SELF_KNOWLEDGE.filter((path) => existsSync(resolve(root, path)));
 		const value = {
 			app: name,
 			root,
+			...url === void 0 ? {} : { url },
 			read,
 			page: this.deps.channel.connected ? "open" : "not open",
 			plugins: this.deps.extensions() === void 0 ? "unavailable" : "available",
@@ -269,6 +270,7 @@ var Door = class {
 			value,
 			text: [
 				`App ${name} in ${root}.`,
+				...url === void 0 ? [] : [`Address: ${url} (the running app; curl it to check a route).`],
 				read.length === 0 ? "No AGENTS.md or skill in the folder." : `Read first: ${read.join(", ")}.`,
 				`Page: ${value.page}${value.page === "not open" ? " (open the app in a browser to look and act)" : ""}.`,
 				`Live plugins: ${value.plugins}.`,
@@ -730,7 +732,8 @@ function apply(ctx, rawConfig = {}) {
 		audit: new AuditLog(auditPath(stateDir(app.root))),
 		app: {
 			name: app.name,
-			root: app.root
+			root: app.root,
+			url: loopbackUrl(server.url)
 		},
 		extensions: () => ctx.get("extensions"),
 		tools: () => ctx.get("tools"),

package/lib/cordis/inspect.js

@@ -1,6 +1,6 @@
 import { t as Acryl } from "../app-BM0rTCp7.js";
 import { loopbackOnly } from "../loopback-only.js";
-import "../src-CwABFr6r.js";
+import "../src-DNzw0Qsb.js";
 import "../middleware-CPQ8himN.js";
 import { Service } from "@deepseek-ai/cordis";
 //#region ../../plugins/acryl-inspect/src/report.ts

package/lib/cordis/node-server.d.ts

@@ -1,4 +1,5 @@
-import { t as RequestError } from "../error-t4N2js2I.js";
+import { c as UpgradeHubOptions, i as testWebSocket, l as UpgradeRouter, n as TestWebSocketOptions, o as UpgradeEmitter, p as WebSocketLike, r as TestWebSocketResult, s as UpgradeHub, t as TestSocket, u as RequestError } from "../test-websocket-DyeS50Tr.js";
+import { n as UpgradeWebSocket } from "../index-C-SklY6u.js";
 import { ServeStaticOptions, serveStatic } from "../node-server/serve-static.js";
 import { Context, Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
@@ -11,6 +12,8 @@ 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. */
 declare const Config: z<Partial<Config>, Config>;
@@ -23,8 +26,17 @@ declare class NodeServer extends Service {
   readonly hostname: string;
   readonly config: Config;
   private readonly server;
+  private hub;
   private bound;
   constructor(ctx: Context, config: Config);
+  /**
+   * `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>;
+  /** How many WebSocket connections are open now. */
+  get sockets(): number;
   /** The port in use, 0 before the server listens. */
   get port(): number;
   /** The address clients use. */
@@ -42,4 +54,4 @@ declare function isPortUnavailable(error: unknown, platform?: NodeJS.Platform):
 /** Loads once the server listens, so a plugin that injects `nodeServer` can rely on `url`. A failure to bind fails the plugin. */
 declare function apply(ctx: Context, config?: Partial<Config>): Promise<void>;
 //#endregion
-export { Config, NodeServer, RequestError, type ServeStaticOptions, apply, inject, isPortUnavailable, name, serveStatic };
+export { Config, NodeServer, RequestError, type ServeStaticOptions, type TestSocket, type TestWebSocketOptions, type TestWebSocketResult, UpgradeEmitter, UpgradeHub, type UpgradeHubOptions, type UpgradeRouter, apply, inject, isPortUnavailable, name, serveStatic, testWebSocket };

package/lib/cordis/node-server.js

@@ -1,4 +1,4 @@
-import { a as Request, o as RequestError, t as createAdaptorServer } from "../server-DvgMGtzo.js";
+import { c as Request, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, r as UpgradeHub, t as testWebSocket } from "../test-websocket-ZXHNHQSU.js";
 import { t as serveStatic } from "../serve-static-3uo_9rjF.js";
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
@@ -10,12 +10,18 @@ const inject = ["router"];
 const 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.")
+	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(3e4).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(2e3).description("Milliseconds a closing socket gets before it is terminated when its plugin unloads.")
+	}).default({})
 });
 var NodeServer = class extends Service {
 	hostname;
 	config;
 	server;
+	hub;
 	bound = 0;
 	constructor(ctx, config) {
 		super(ctx, "nodeServer");
@@ -31,6 +37,7 @@ var NodeServer = class extends Service {
 			overrideGlobalObjects: false
 		});
 		ctx.effect(() => async () => {
+			await this.hub?.close();
 			this.server.closeAllConnections();
 			if (this.server.listening) await new Promise((resolve) => {
 				this.server.close(() => {
@@ -39,6 +46,22 @@ var NodeServer = class extends Service {
 			});
 		}, "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() {
+		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() {
+		return this.hub?.size ?? 0;
+	}
 	/** The port in use, 0 before the server listens. */
 	get port() {
 		return this.bound;
@@ -86,8 +109,9 @@ async function apply(ctx, config = {}) {
 		hostname: "127.0.0.1",
 		port: 0,
 		scan: 20,
+		websocket: {},
 		...config
 	}).listen();
 }
 //#endregion
-export { Config, NodeServer, RequestError, apply, inject, isPortUnavailable, name, serveStatic };
+export { Config, NodeServer, RequestError, UpgradeEmitter, UpgradeHub, apply, inject, isPortUnavailable, name, serveStatic, testWebSocket };

package/lib/cordis/router-http.d.ts

@@ -1,5 +1,7 @@
-import { i as RouterHttpService } from "../index-BqVQkTnu.js";
+import { n as UpgradeWebSocket } from "../index-C-SklY6u.js";
+import { i as RouterHttpService } from "../index-D4nVR3wu.js";
 import { IncomingMessage, ServerResponse } from "node:http";
+import { Duplex } from "node:stream";
 import { Context, Service } from "@deepseek-ai/cordis";
 
 //#region ../../plugins/acryl-router-http/src/serve.d.ts
@@ -40,16 +42,37 @@ 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;
 }
 declare class RouterHttp extends Service implements RouterHttpService {
   private readonly router;
   private readonly web;
+  private hub;
+  /** 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;
+  private readonly upgradesIn;
   constructor(ctx: Context);
   /**
    * 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, options?: {
+    readonly upgrade?: readonly string[];
+  }): () => void;
+  /**
+   * `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]`.
    */
-  mount(prefix: string): () => void;
+  upgrades(): UpgradeWebSocket;
+  /** How many WebSocket connections are open now. */
+  get sockets(): number;
+  private ensureHub;
 }
 declare function apply(ctx: Context): void;
 //#endregion

package/lib/cordis/router-http.js

@@ -1,3 +1,5 @@
+import { n as UpgradeEmitter, r as UpgradeHub } from "../test-websocket-ZXHNHQSU.js";
+import "./node-server.js";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 import { Service } from "@deepseek-ai/cordis";
@@ -88,27 +90,73 @@ const PREFIX_PATTERN = /^\/[A-Za-z0-9._~\-/]*[A-Za-z0-9._~-]$/;
 var RouterHttp = class extends Service {
 	router;
 	web;
+	hub;
+	/** 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). */
+	home;
+	upgradesIn = new UpgradeEmitter();
 	constructor(ctx) {
 		super(ctx, "routerHttp");
+		this.home = ctx;
 		this.router = ctx.router;
 		this.web = ctx.get("webServer");
 	}
 	/**
 	* 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) {
+	mount(prefix, options = {}) {
 		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 === void 0) throw new TypeError("acryl-router-http: this web server cannot take WebSocket upgrades (it has no registerUpgrade)");
+		const removers = [];
+		try {
+			if (upgrade.length > 0) this.ensureHub();
+			for (const path of upgrade) removers.push(this.web.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 = () => {
+			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() {
+		return this.ensureHub().upgradeWebSocketFor(this.ctx);
+	}
+	/** How many WebSocket connections are open now. */
+	get sockets() {
+		return this.hub?.size ?? 0;
+	}
+	ensureHub() {
+		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;
+	}
 };
 function apply(ctx) {
 	new RouterHttp(ctx);

package/lib/cordis/router.d.ts

@@ -3,6 +3,6 @@ import { c as StatusCode, n as ContentfulStatusCode } from "../http-status-DaAwG
 import { a as getConnInfo, i as connectionOf, n as RouterBindings, r as RouterEnv, t as ConnectionInfo } from "../connection-ZLEso7XL.js";
 import { t as Acryl } from "../app-D8riatvv.js";
 import { n as AppRequest, t as App } from "../deprecated-CTy4N7ng.js";
-import { a as TrailingSlash, i as RouterHttpService, n as MountableApp, o as apply, r as Router, s as name, t as Config } from "../index-BqVQkTnu.js";
+import { a as TrailingSlash, i as RouterHttpService, n as MountableApp, o as apply, r as Router, s as name, t as Config } from "../index-D4nVR3wu.js";
 import { t as HTTPException } from "../http-exception-kpGJkmpi.js";
 export { Acryl, type AcrylRequest, App, type AppRequest, Config, type ConnectionInfo, type ContentfulStatusCode, Context, type ContextRenderer, type ContextVariableMap, type Env, type ErrorHandler, type ExecutionContext, HTTPException, type Handler, type Input, type MiddlewareHandler, type MountableApp, type Next, type NotFoundHandler, type NotFoundResponse, Router, type RouterBindings, type RouterEnv, type RouterHttpService, type Schema, type StatusCode, type ToSchema, type TrailingSlash, type TypedResponse, type ValidationTargets, apply, connectionOf, getConnInfo, name };

package/lib/cordis/router.js

@@ -3,5 +3,5 @@ import { t as Context } from "../context-DDO0cfuP.js";
 import { t as Acryl } from "../app-BM0rTCp7.js";
 import { t as App } from "../deprecated-BP4fPt38.js";
 import { n as getConnInfo, t as connectionOf } from "../connection-C7xgP1hP.js";
-import { i as name, n as Router, r as apply, t as Config } from "../src-CwABFr6r.js";
+import { i as name, n as Router, r as apply, t as Config } from "../src-DNzw0Qsb.js";
 export { Acryl, App, Config, Context, HTTPException, Router, apply, connectionOf, getConnInfo, name };

package/lib/cordis/state.js

@@ -3,7 +3,7 @@ import { methodNotAllowed } from "../method-not-allowed.js";
 import { r as streamSSE } from "../streaming-DHST3Scg.js";
 import { loopbackOnly } from "../loopback-only.js";
 import "../helpers-CvTauQT5.js";
-import "../src-CwABFr6r.js";
+import "../src-DNzw0Qsb.js";
 import "../middleware-CPQ8himN.js";
 import { Service } from "@deepseek-ai/cordis";
 //#region ../../plugins/acryl-state/src/cell.ts

package/lib/door/host.js

@@ -1,2 +1,2 @@
-import { d as AuditLog, f as auditPath, n as HEARTBEAT_MS, p as UiChannel, r as pageChannelRoutes, t as renderSnapshot } from "../snapshot-text-D3NspDyT.js";
+import { d as AuditLog, f as auditPath, n as HEARTBEAT_MS, p as UiChannel, r as pageChannelRoutes, t as renderSnapshot } from "../snapshot-text-yaWlezbd.js";
 export { AuditLog, HEARTBEAT_MS, UiChannel, auditPath, pageChannelRoutes, renderSnapshot };

package/lib/{index-BvFh1Gfx.d.ts → index-C-SklY6u.d.ts}

@@ -33,6 +33,8 @@ interface WSContextInit<T = unknown> {
   close(code?: number, reason?: string): void;
   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;
 }
@@ -52,6 +54,7 @@ declare class WSContext<T = unknown> {
   raw?: T;
   binaryType: BinaryType;
   get readyState(): WSReadyState;
+  get bufferedAmount(): number;
   url: URL | null;
   protocol: string | null;
   close(code?: number, reason?: string): void;

package/lib/{index-BqVQkTnu.d.ts → index-D4nVR3wu.d.ts}

@@ -1,5 +1,6 @@
 import { B as NotFoundHandler, y as ErrorHandler } from "./context-DS3fYyG-.js";
 import { t as ConnectionInfo } from "./connection-ZLEso7XL.js";
+import { n as UpgradeWebSocket } from "./index-C-SklY6u.js";
 import { Context, Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 
@@ -18,8 +19,21 @@ declare const Config: z<Partial<Config>, Config>;
  * served over HTTP without depending on the adapter package.
  */
 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' {
   interface Context {
@@ -83,8 +97,9 @@ declare 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>;
   private dispatch;
   private app;
   /**

package/lib/node-server.d.ts

@@ -1,42 +1,12 @@
 import { t as Acryl } from "./app-D8riatvv.js";
-import { n as UpgradeWebSocket } from "./index-BvFh1Gfx.js";
-import { t as RequestError } from "./error-t4N2js2I.js";
+import { a as Owner, c as UpgradeHubOptions, d as upgradeWebSocket, f as WebSocketData, i as testWebSocket, l as UpgradeRouter, m as WebSocketServerLike, n as TestWebSocketOptions, o as UpgradeEmitter, p as WebSocketLike, r as TestWebSocketResult, s as UpgradeHub, t as TestSocket, u as RequestError } from "./test-websocket-DyeS50Tr.js";
 import { ServeStaticOptions, serveStatic } from "./node-server/serve-static.js";
 import { getConnInfo } from "./node-server/conninfo.js";
 import { AddressInfo } from "node:net";
 import { IncomingMessage, Server, ServerOptions, ServerResponse, createServer } from "node:http";
 import { Http2SecureServer, Http2Server, Http2ServerRequest, Http2ServerResponse, SecureServerOptions, ServerOptions as ServerOptions$1, createSecureServer, createServer as createServer$1 } from "node:http2";
-import { Duplex } from "node:stream";
 import { Server as Server$1, ServerOptions as ServerOptions$2, createServer as createServer$2 } from "node:https";
 
-//#region ../../plugins/acryl-node-server/src/adapter/websocket-types.d.ts
-type WSReadyState = 0 | 1 | 2 | 3;
-type WebSocketData = string | ArrayBuffer | Uint8Array | readonly Uint8Array[];
-type WebSocketSendOptions = {
-  compress?: boolean;
-};
-interface WebSocketLike {
-  protocol: string;
-  readyState: WSReadyState;
-  close(code?: number, reason?: string): void;
-  send(data: string | ArrayBuffer | ArrayBufferView, options?: WebSocketSendOptions): void;
-  on(event: 'message', listener: (data: WebSocketData, isBinary: boolean) => void): this;
-  on(event: 'close', listener: (code: number, reason: Uint8Array) => void): this;
-  on(event: 'error', listener: (error: unknown) => void): this;
-  off(event: 'message', listener: (data: WebSocketData, isBinary: boolean) => void): this;
-}
-interface WebSocketServerLike {
-  options: {
-    noServer?: boolean;
-  };
-  on(event: 'connection', listener: (ws: WebSocketLike, request: IncomingMessage) => void): this;
-  on(event: 'headers', listener: (headers: string[]) => void): this;
-  off(event: 'headers', listener: (headers: string[]) => void): this;
-  emit(event: 'connection', ws: WebSocketLike, request: IncomingMessage): boolean;
-  handleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, callback: (ws: WebSocketLike) => void): void;
-  close(): void;
-}
-//#endregion
 //#region ../../plugins/acryl-node-server/src/adapter/types.d.ts
 type HttpBindings = {
   incoming: IncomingMessage;
@@ -107,12 +77,6 @@ declare function serve(options: HttpsOptions, listeningListener?: (info: Address
 declare function serve(options: HttpOptions, listeningListener?: (info: AddressInfo) => void): Server;
 declare function serve(options: Options, listeningListener?: (info: AddressInfo) => void): ServerType;
 //#endregion
-//#region ../../plugins/acryl-node-server/src/adapter/websocket.d.ts
-type UpgradeWebSocketOptions = {
-  onError: (err: unknown) => void;
-};
-declare const upgradeWebSocket: UpgradeWebSocket<WebSocketLike, UpgradeWebSocketOptions>;
-//#endregion
 //#region ../../plugins/acryl-node-server/src/adapter/listener.d.ts
 declare const getRequestListener: (fetchCallback: FetchCallback, options?: {
   hostname?: string;
@@ -161,4 +125,4 @@ declare function clientModules(options: ClientModulesOptions): Acryl;
  */
 declare function buildClientModules(options: BuildClientModulesOptions): string[];
 //#endregion
-export { type BuildClientModulesOptions, type ClientModulesOptions, type Http2Bindings, type HttpBindings, RequestError, type ServeStaticOptions, type ServerType, type WebSocketData, type WebSocketLike, type WebSocketServerLike, buildClientModules, clientModules, createAdaptorServer, getConnInfo, getRequestListener, serve, serveStatic, upgradeWebSocket };
+export { type BuildClientModulesOptions, type ClientModulesOptions, type Http2Bindings, type HttpBindings, type Owner, RequestError, type ServeStaticOptions, type ServerType, type TestSocket, type TestWebSocketOptions, type TestWebSocketResult, UpgradeEmitter, UpgradeHub, type UpgradeHubOptions, type UpgradeRouter, type WebSocketData, type WebSocketLike, type WebSocketServerLike, buildClientModules, clientModules, createAdaptorServer, getConnInfo, getRequestListener, serve, serveStatic, testWebSocket, upgradeWebSocket };

package/lib/node-server.js

@@ -1,5 +1,5 @@
-import { i as getRequestListener, n as serve, o as RequestError, r as upgradeWebSocket, t as createAdaptorServer } from "./server-DvgMGtzo.js";
+import { a as serve, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, o as upgradeWebSocket, r as UpgradeHub, s as getRequestListener, t as testWebSocket } from "./test-websocket-ZXHNHQSU.js";
 import { t as serveStatic } from "./serve-static-3uo_9rjF.js";
 import { getConnInfo } from "./node-server/conninfo.js";
 import { n as clientModules, t as buildClientModules } from "./client-modules-CLvWOjbd.js";
-export { RequestError, buildClientModules, clientModules, createAdaptorServer, getConnInfo, getRequestListener, serve, serveStatic, upgradeWebSocket };
+export { RequestError, UpgradeEmitter, UpgradeHub, buildClientModules, clientModules, createAdaptorServer, getConnInfo, getRequestListener, serve, serveStatic, testWebSocket, upgradeWebSocket };

package/lib/{snapshot-text-D3NspDyT.js → snapshot-text-yaWlezbd.js}

@@ -5,7 +5,7 @@ import { r as streamSSE } from "./streaming-DHST3Scg.js";
 import { loopbackAuthority, loopbackOnly } from "./loopback-only.js";
 import "./helpers-CvTauQT5.js";
 import { UiControlError, WINDOW_ID, parseChannelToHost } from "./door/protocol.js";
-import "./src-CwABFr6r.js";
+import "./src-DNzw0Qsb.js";
 import "./middleware-CPQ8himN.js";
 import { dirname, join } from "node:path";
 import { timingSafeEqual } from "node:crypto";

package/lib/{src-CwABFr6r.js → src-DNzw0Qsb.js}

@@ -186,8 +186,9 @@ var Router = class 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, connection = {}) {
+	fetch(request, connection = {}, bindings) {
 		if (this.state.closing) return Promise.resolve(new Response("Service Unavailable", { status: 503 }));
 		const controller = new AbortController();
 		const forward = () => controller.abort();
@@ -201,7 +202,7 @@ var Router = class extends Service {
 			passThroughOnException: () => {},
 			props: {}
 		};
-		const env = { connection };
+		const env = bindings === void 0 ? { connection } : Object.assign(bindings, { connection });
 		let bodyDone = Promise.resolve();
 		let endBody = () => {};
 		let resolveSettled;