acrylblends 1.0.7 → 1.0.8

package/lib/cordis/door.js

@@ -1,10 +1,12 @@
 import { t as Acryl } from "../app-CQcGWjrk.js";
 import { r as streamSSE } from "../streaming-BlDaph8U.js";
+import { r as loopbackAuthority } from "../loopback-only-BbasoF7R.js";
 import "../helpers-BEjcdbgw.js";
 import { n as clientModules } from "../client-modules-drj4mjhj.js";
-import { a as MAX_WAIT_MS, l as UiControlError, p as parseUiRequest, r as MAX_SNAPSHOT_NODES } from "../protocol-CQ_if7Dg.js";
+import { a as MAX_WAIT_MS, d as parseChannelToHost, l as UiControlError, p as parseUiRequest, r as MAX_SNAPSHOT_NODES, u as WINDOW_ID } from "../protocol-CQ_if7Dg.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-m13Pk-AI.js";
 import "../src-BTBm4OPD.js";
+import "../middleware-BfG_fp8P.js";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import z from "@deepseek-ai/schemastery";
@@ -1153,6 +1155,66 @@ function operatorRoutes(prefix, secret, door, reportError) {
 		}
 	});
 }
+/** The upgrade request comes from this app's own page: a loopback peer on this port, and an `Origin` that is exactly this app's origin. Nothing else is read as proof. */
+const ownOrigin = async (c, next) => {
+	const authority = loopbackAuthority(c);
+	const origin = c.req.header("origin");
+	const site = c.req.header("sec-fetch-site");
+	if (authority === void 0 || origin === void 0 || origin !== authority.origin || site !== void 0 && site !== "same-origin") return c.json(error("only this app's own page may open the channel"), 403);
+	const windowId = c.req.query("window");
+	if (windowId === void 0 || !WINDOW_ID.test(windowId)) return c.json(error("a window id is required"), 400);
+	await next();
+};
+function pageSocketRoutes(channel, options) {
+	const heartbeatMs = options.heartbeatMs ?? 15e3;
+	return new Acryl().get(`${options.prefix}/channel/ws`, ownOrigin, options.upgrade((c) => {
+		const windowId = c.req.query("window");
+		const focused = c.req.query("focused") === "1";
+		const shellQuery = Number(c.req.query("shell"));
+		const shellWindow = Number.isSafeInteger(shellQuery) && shellQuery > 0 ? shellQuery : void 0;
+		let detach;
+		let beat;
+		return {
+			onOpen(_event, ws) {
+				const write = (frame) => {
+					ws.send(JSON.stringify(frame));
+				};
+				detach = channel.attach(windowId, focused, {
+					send: (data) => {
+						write({
+							e: "call",
+							d: data
+						});
+					},
+					close: () => {
+						ws.close(1e3, "replaced");
+					}
+				}, shellWindow);
+				write({ e: "ready" });
+				beat = setInterval(() => {
+					try {
+						write({ e: "ping" });
+					} catch {}
+				}, heartbeatMs);
+			},
+			onMessage(event) {
+				if (typeof event.data !== "string") return;
+				let message;
+				try {
+					message = JSON.parse(event.data);
+				} catch {
+					return;
+				}
+				const parsed = parseChannelToHost(message);
+				if (parsed !== null) channel.receive(windowId, parsed);
+			},
+			onClose() {
+				if (beat !== void 0) clearInterval(beat);
+				detach?.();
+			}
+		};
+	}, { textOnly: true }));
+}
 /** The oldest Node the client runs on (the framework's own floor). */
 const MIN_NODE = [22, 19];
 /**
@@ -1363,7 +1425,16 @@ function apply(ctx, rawConfig = {}) {
 	const router = ctx.router;
 	if (typeof router.wrap === "function") router.wrap(addScript);
 	else ctx.router.route("/", new Acryl().use("*", addScript));
-	ctx.router.route("/", privateApi(DOOR_PREFIX, pageModule, pageChannelRoutes(channel, { prefix: DOOR_PREFIX }), shellRoutes(DOOR_PREFIX, secret, shell), operatorRoutes(DOOR_PREFIX, secret, door, reportError), mcpRoutes(DOOR_PREFIX, secret, door, reportError)));
+	let upgrade;
+	try {
+		upgrade = ctx.nodeServer?.upgrades?.();
+	} catch (cause) {
+		reportError("open the page channel over a WebSocket (the pages use the event stream)", cause);
+	}
+	ctx.router.route("/", privateApi(DOOR_PREFIX, pageModule, pageChannelRoutes(channel, { prefix: DOOR_PREFIX }), ...upgrade === void 0 ? [] : [pageSocketRoutes(channel, {
+		prefix: DOOR_PREFIX,
+		upgrade
+	})], shellRoutes(DOOR_PREFIX, secret, shell), operatorRoutes(DOOR_PREFIX, secret, door, reportError), mcpRoutes(DOOR_PREFIX, secret, door, reportError)));
 	ctx.inject(["tools"], (inner) => {
 		inner.effect(() => registerChatTools(inner.get("tools"), door), "acryl-door: the verbs in the tools registry");
 	});

package/lib/door/page.d.ts

@@ -55,6 +55,12 @@ declare class UiDriver {
   private emit;
 }
 //#endregion
+//#region ../../plugins/acryl-door/src/page/socket-source.d.ts
+interface SocketSource extends ChannelSource {
+  /** Send one message up; false when the socket is not open (the caller posts it instead). */
+  send(text: string): boolean;
+}
+//#endregion
 //#region ../../plugins/acryl-door/src/page/channel.d.ts
 /** The slice of an `EventSource` the channel uses, so tests can supply their own. */
 interface ChannelSource {
@@ -73,6 +79,11 @@ interface PageChannelOptions {
   /** Where the door's routes are, e.g. `/api/acryl-door`. */
   readonly base: string;
   readonly createSource?: (url: string) => ChannelSource;
+  /** Opens the WebSocket form of the channel (`<base>/channel/ws`); the browser's own by default. Pass `transport: 'stream'` to keep to the event stream. */
+  readonly createSocket?: (url: string) => SocketSource;
+  readonly transport?: 'auto' | 'stream';
+  /** Where the page says it fell back to the event stream (the console by default). */
+  readonly warn?: (message: string) => void;
   readonly post?: (url: string, body: string) => Promise<unknown>;
   readonly silenceMs?: number;
   readonly now?: () => number;
@@ -82,6 +93,9 @@ declare class PageChannel {
   private reconnectTimer;
   private watchdog;
   private backoff;
+  /** The WebSocket form is tried first; once it fails to open (a proxy that cannot upgrade, no `ws` on the server) the page keeps to the event stream. */
+  private socketAllowed;
+  private socketReady;
   private lastHeard;
   private disposed;
   private readonly now;
@@ -89,6 +103,8 @@ declare class PageChannel {
   private readonly options;
   constructor(driver: UiDriver, options: PageChannelOptions);
   connect(): void;
+  /** The WebSocket did not open: use the event stream from now on, and say why once. */
+  private fallBack;
   /** Tell the Host whether this window is the one in front. */
   reportFocus(focused: boolean): void;
   /**

package/lib/door/page.js

@@ -1,4 +1,54 @@
 import { a as MAX_WAIT_MS, f as parseChannelToPage, l as UiControlError, o as MUTATING_OPS, r as MAX_SNAPSHOT_NODES } from "../protocol-CQ_if7Dg.js";
+//#region ../../plugins/acryl-door/src/page/socket-source.ts
+function socketSource(socket) {
+	const listeners = /* @__PURE__ */ new Map();
+	let closed = false;
+	const source = {
+		onerror: null,
+		get readyState() {
+			return closed || socket.readyState >= 2 ? 2 : socket.readyState;
+		},
+		addEventListener(type, listener) {
+			listeners.set(type, [...listeners.get(type) ?? [], listener]);
+		},
+		send(text) {
+			if (socket.readyState !== 1) return false;
+			try {
+				socket.send(text);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		close() {
+			closed = true;
+			socket.onmessage = null;
+			socket.onerror = null;
+			socket.onclose = null;
+			try {
+				socket.close(1e3, "page left");
+			} catch {}
+		}
+	};
+	socket.onmessage = (event) => {
+		if (typeof event.data !== "string") return;
+		let frame;
+		try {
+			frame = JSON.parse(event.data);
+		} catch {
+			return;
+		}
+		if (typeof frame.e !== "string") return;
+		for (const listener of listeners.get(frame.e) ?? []) listener({ data: typeof frame.d === "string" ? frame.d : "" });
+	};
+	const lost = (event) => {
+		if (!closed) source.onerror?.(event);
+	};
+	socket.onerror = lost;
+	socket.onclose = lost;
+	return source;
+}
+//#endregion
 //#region ../../plugins/acryl-door/src/page/channel.ts
 /**
 * The page's end of the door's channel.
@@ -18,6 +68,9 @@ var PageChannel = class {
 	reconnectTimer;
 	watchdog;
 	backoff = BACKOFF_START_MS;
+	/** The WebSocket form is tried first; once it fails to open (a proxy that cannot upgrade, no `ws` on the server) the page keeps to the event stream. */
+	socketAllowed;
+	socketReady = false;
 	lastHeard = 0;
 	disposed = false;
 	now;
@@ -27,32 +80,49 @@ var PageChannel = class {
 		this.driver = driver;
 		this.options = options;
 		this.now = options.now ?? (() => Date.now());
+		this.socketAllowed = options.transport !== "stream" && (options.createSocket !== void 0 || options.createSource === void 0 && typeof WebSocket !== "undefined");
 	}
 	connect() {
 		if (this.disposed || this.source !== void 0) return;
-		const create = this.options.createSource ?? ((url) => new EventSource(url));
 		const query = `window=${encodeURIComponent(this.options.windowId)}&focused=${this.options.focused() ? "1" : "0"}${this.options.shellWindow === void 0 ? "" : `&shell=${String(this.options.shellWindow)}`}`;
-		const source = create(`${this.options.base}/channel?${query}`);
+		const viaSocket = this.socketAllowed;
+		this.socketReady = false;
+		const source = viaSocket ? (this.options.createSocket ?? ((url) => socketSource(new WebSocket(url))))(`${socketBase(this.options.base)}/channel/ws?${query}`) : (this.options.createSource ?? ((url) => new EventSource(url)))(`${this.options.base}/channel?${query}`);
 		this.source = source;
 		this.lastHeard = this.now();
 		const heard = () => {
 			this.lastHeard = this.now();
 			this.backoff = BACKOFF_START_MS;
 		};
-		source.addEventListener("ready", heard);
+		source.addEventListener("ready", () => {
+			this.socketReady = true;
+			heard();
+		});
 		source.addEventListener("ping", heard);
 		source.addEventListener("call", (event) => {
 			heard();
 			if (typeof event.data === "string") this.answer(event.data);
 		});
 		source.onerror = () => {
-			if (source.readyState === CLOSED) this.restart(source);
+			if (source.readyState !== CLOSED) return;
+			if (viaSocket && !this.socketReady) this.fallBack(source);
+			else this.restart(source);
 		};
 		const silence = this.options.silenceMs ?? 45e3;
 		this.watchdog = setInterval(() => {
 			if (this.now() - this.lastHeard > silence) this.restart(source);
 		}, Math.max(50, Math.floor(silence / 3)));
 	}
+	/** The WebSocket did not open: use the event stream from now on, and say why once. */
+	fallBack(source) {
+		if (this.source !== source) return;
+		this.socketAllowed = false;
+		(this.options.warn ?? ((message) => {
+			console.warn(message);
+		}))("acryl-door: the page channel could not open a WebSocket (the server has no upgrade route, or a proxy refused it); using server-sent events, which count against the browser's six connections per host");
+		this.stop();
+		this.connect();
+	}
 	/** Tell the Host whether this window is the one in front. */
 	reportFocus(focused) {
 		this.send({
@@ -130,6 +200,7 @@ var PageChannel = class {
 		});
 	}
 	send(message) {
+		if (this.source?.send?.(JSON.stringify(message)) === true) return;
 		(this.options.post ?? ((url, body) => fetch(url, {
 			method: "POST",
 			headers: { "content-type": "application/json" },
@@ -140,6 +211,12 @@ var PageChannel = class {
 		})).catch(() => {});
 	}
 };
+/** The WebSocket address of the door's routes: this page's own origin, `ws:` or `wss:`, then the base path. */
+function socketBase(base) {
+	const here = globalThis.location;
+	if (here === void 0) return base;
+	return `${here.protocol === "https:" ? "wss" : "ws"}://${here.host}${base}`;
+}
 //#endregion
 //#region ../../plugins/acryl-door/src/page/driver/sensitivity.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",

package/plugins/acryl-door/plugin.json

@@ -8,6 +8,9 @@
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/schemastery": "3.18.4"
   },
+  "devDependencies": {
+    "ws": "8.21.3"
+  },
   "mount": "mount it after acryl-node-server and extensions in development builds: root.plugin(door); add <script type=\"module\" src=\"/api/acryl-door/page.js\"></script> to the pages; the command is .acryl/bin/acryl",
   "gitignore": [".acryl/"],
   "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"],

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

@@ -0,0 +1,78 @@
+/**
+ * The page channel over a WebSocket. An event stream (`page-routes.ts`) holds one of the browser's six connections per host for as long as the page lives; two windows of an app that
+ * also stream their own state, with the panel following a run, use them all, and then no request of either window is sent (the door's answers, Stop). A WebSocket is not one of
+ * those six: it opens at once however many streams are open, and the page's answers travel on it too, so nothing is queued behind a stream.
+ *
+ * `GET <prefix>/channel/ws?window=<id>&focused=0|1[&shell=<n>]` upgrades. The messages are the same JSON as the stream's: down, `{ "e": "call", "d": "<the call>" }` and
+ * `{ "e": "ready" }` / `{ "e": "ping" }`; up, one {@link ChannelToHost} message per frame. A WebSocket has no CORS, so the `Origin` header is the boundary: it must be present and be
+ * exactly this app's own origin, or the upgrade is refused (403) before any handshake. A page on another port, a web site, and a program that sends no `Origin` are all refused.
+ */
+
+import { Acryl, type MiddlewareHandler } from 'acryl-router'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
+import { loopbackAuthority } from 'acryl-router/middleware'
+import { parseChannelToHost, WINDOW_ID } from '../page/protocol.ts'
+import type { UiChannel } from './channel.ts'
+import { error } from './http.ts'
+
+/** How often the Host writes a `ping`; the page gives up on a socket that is silent for three of these. */
+export const SOCKET_HEARTBEAT_MS = 15_000
+
+export interface PageSocketOptions {
+  readonly prefix: string
+  readonly upgrade: UpgradeWebSocket
+  readonly heartbeatMs?: number
+}
+
+/** The upgrade request comes from this app's own page: a loopback peer on this port, and an `Origin` that is exactly this app's origin. Nothing else is read as proof. */
+export const ownOrigin: MiddlewareHandler = async (c, next) => {
+  const authority = loopbackAuthority(c)
+  const origin = c.req.header('origin')
+  const site = c.req.header('sec-fetch-site')
+  if (authority === undefined || origin === undefined || origin !== authority.origin || (site !== undefined && site !== 'same-origin')) {
+    return c.json(error('only this app\'s own page may open the channel'), 403)
+  }
+  const windowId = c.req.query('window')
+  if (windowId === undefined || !WINDOW_ID.test(windowId)) return c.json(error('a window id is required'), 400)
+  await next()
+}
+
+export function pageSocketRoutes(channel: UiChannel, options: PageSocketOptions): Acryl {
+  const heartbeatMs = options.heartbeatMs ?? SOCKET_HEARTBEAT_MS
+  return new Acryl().get(
+    `${options.prefix}/channel/ws`,
+    ownOrigin,
+    options.upgrade((c) => {
+      const windowId = c.req.query('window') as string
+      const focused = c.req.query('focused') === '1'
+      const shellQuery = Number(c.req.query('shell'))
+      const shellWindow = Number.isSafeInteger(shellQuery) && shellQuery > 0 ? shellQuery : undefined
+      let detach: (() => void) | undefined
+      let beat: NodeJS.Timeout | undefined
+      return {
+        onOpen(_event, ws) {
+          const write = (frame: { e: string; d?: string }): void => {
+            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)
+          write({ e: 'ready' })
+          beat = setInterval(() => {
+            try { write({ e: 'ping' }) } catch { /* the close event follows */ }
+          }, heartbeatMs)
+        },
+        onMessage(event) {
+          if (typeof event.data !== 'string') return
+          let message: unknown
+          try { message = JSON.parse(event.data) } catch { return }
+          const parsed = parseChannelToHost(message)
+          if (parsed !== null) channel.receive(windowId, parsed)
+        },
+        onClose() {
+          if (beat !== undefined) clearInterval(beat)
+          detach?.()
+        },
+      }
+    }, { textOnly: true }),
+  )
+}

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

@@ -13,6 +13,7 @@ import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { Acryl } from 'acryl-router'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
 import { clientModules } from 'acryl-node-server/client-modules'
 import { auditPath, AuditLog } from './host/audit.ts'
 import { UiChannel } from './host/channel.ts'
@@ -23,6 +24,7 @@ import { DOOR_PREFIX, privateApi } from './host/http.ts'
 import { mcpRoutes } from './host/mcp-routes.ts'
 import { operatorRoutes } from './host/operator-routes.ts'
 import { pageChannelRoutes } from './host/page-routes.ts'
+import { pageSocketRoutes } from './host/page-socket.ts'
 import { ShellChannel, shellRoutes } from './host/shell.ts'
 import { realNode, writeShims, type ShimTarget } from './host/shim.ts'
 
@@ -154,10 +156,18 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
   // An app whose router copy is older than this plugin has no `wrap`: the middleware then covers the routes mounted after the door, as the agent panel's does.
   if (typeof router.wrap === 'function') router.wrap(addScript)
   else ctx.router.route('/', new Acryl().use('*', addScript as never))
+  // The page channel also runs over a WebSocket, which is not one of the browser's six connections per host. Without the `ws` package or an adapter that upgrades, the pages use the stream.
+  let upgrade: UpgradeWebSocket | undefined
+  try {
+    upgrade = (ctx as unknown as { nodeServer?: { upgrades?: () => UpgradeWebSocket } }).nodeServer?.upgrades?.()
+  } catch (cause) {
+    reportError('open the page channel over a WebSocket (the pages use the event stream)', cause)
+  }
   ctx.router.route('/', privateApi(
     DOOR_PREFIX,
     pageModule,
     pageChannelRoutes(channel, { prefix: DOOR_PREFIX }),
+    ...(upgrade === undefined ? [] : [pageSocketRoutes(channel, { prefix: DOOR_PREFIX, upgrade })]),
     shellRoutes(DOOR_PREFIX, secret, shell),
     operatorRoutes(DOOR_PREFIX, secret, door, reportError),
     mcpRoutes(DOOR_PREFIX, secret, door, reportError),

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

@@ -9,6 +9,7 @@
 
 import { UiControlError, parseChannelToPage, type ChannelToHost } from './protocol.ts'
 import type { UiDriver } from './driver/driver.ts'
+import { type SocketLike, type SocketSource, socketSource } from './socket-source.ts'
 
 /** The slice of an `EventSource` the channel uses, so tests can supply their own. */
 export interface ChannelSource {
@@ -32,6 +33,11 @@ export interface PageChannelOptions {
   /** Where the door's routes are, e.g. `/api/acryl-door`. */
   readonly base: string
   readonly createSource?: (url: string) => ChannelSource
+  /** Opens the WebSocket form of the channel (`<base>/channel/ws`); the browser's own by default. Pass `transport: 'stream'` to keep to the event stream. */
+  readonly createSocket?: (url: string) => SocketSource
+  readonly transport?: 'auto' | 'stream'
+  /** Where the page says it fell back to the event stream (the console by default). */
+  readonly warn?: (message: string) => void
   readonly post?: (url: string, body: string) => Promise<unknown>
   readonly silenceMs?: number
   readonly now?: () => number
@@ -42,6 +48,9 @@ export class PageChannel {
   private reconnectTimer: ReturnType<typeof setTimeout> | undefined
   private watchdog: ReturnType<typeof setInterval> | undefined
   private backoff = BACKOFF_START_MS
+  /** The WebSocket form is tried first; once it fails to open (a proxy that cannot upgrade, no `ws` on the server) the page keeps to the event stream. */
+  private socketAllowed: boolean
+  private socketReady = false
   private lastHeard = 0
   private disposed = false
   private readonly now: () => number
@@ -53,33 +62,56 @@ export class PageChannel {
     this.driver = driver
     this.options = options
     this.now = options.now ?? (() => Date.now())
+    // A test that supplies only a stream keeps to it; the browser's own WebSocket is tried when the page supplies neither.
+    this.socketAllowed = options.transport !== 'stream' && (options.createSocket !== undefined || (options.createSource === undefined && typeof WebSocket !== 'undefined'))
   }
 
   connect(): void {
     if (this.disposed || this.source !== undefined) return
-    const create = this.options.createSource ?? ((url: string): ChannelSource => new EventSource(url))
     const query = `window=${encodeURIComponent(this.options.windowId)}&focused=${this.options.focused() ? '1' : '0'}${this.options.shellWindow === undefined ? '' : `&shell=${String(this.options.shellWindow)}`}`
-    const source = create(`${this.options.base}/channel?${query}`)
+    const viaSocket = this.socketAllowed
+    this.socketReady = false
+    const source: ChannelSource = viaSocket
+      ? (this.options.createSocket ?? ((url: string): SocketSource => socketSource(new WebSocket(url) as unknown as SocketLike)))(`${socketBase(this.options.base)}/channel/ws?${query}`)
+      : (this.options.createSource ?? ((url: string): ChannelSource => new EventSource(url) as unknown as ChannelSource))(`${this.options.base}/channel?${query}`)
     this.source = source
     this.lastHeard = this.now()
     const heard = (): void => {
       this.lastHeard = this.now()
       this.backoff = BACKOFF_START_MS
     }
-    source.addEventListener('ready', heard)
+    source.addEventListener('ready', () => {
+      this.socketReady = true
+      heard()
+    })
     source.addEventListener('ping', heard)
     source.addEventListener('call', (event) => {
       heard()
       if (typeof event.data === 'string') this.answer(event.data)
     })
-    // An EventSource retries by itself after a network error; once it gives up (CLOSED), the channel starts over.
-    source.onerror = () => { if (source.readyState === CLOSED) this.restart(source) }
+    // An EventSource retries by itself after a network error; once it gives up (CLOSED), the channel starts over. A WebSocket that never became ready is not retried: the page
+    // falls back to the event stream, and says so once.
+    source.onerror = () => {
+      if (source.readyState !== CLOSED) return
+      if (viaSocket && !this.socketReady) this.fallBack(source)
+      else this.restart(source)
+    }
     const silence = this.options.silenceMs ?? SILENCE_MS
     this.watchdog = setInterval(() => {
       if (this.now() - this.lastHeard > silence) this.restart(source)
     }, Math.max(50, Math.floor(silence / 3)))
   }
 
+  /** The WebSocket did not open: use the event stream from now on, and say why once. */
+  private fallBack(source: ChannelSource): void {
+    if (this.source !== source) return
+    this.socketAllowed = false
+    const warn = this.options.warn ?? ((message: string) => { console.warn(message) })
+    warn('acryl-door: the page channel could not open a WebSocket (the server has no upgrade route, or a proxy refused it); using server-sent events, which count against the browser\'s six connections per host')
+    this.stop()
+    this.connect()
+  }
+
   /** Tell the Host whether this window is the one in front. */
   reportFocus(focused: boolean): void {
     this.send({ t: 'focus', focused })
@@ -149,9 +181,19 @@ export class PageChannel {
   }
 
   private send(message: ChannelToHost): void {
+    // On a WebSocket the answer goes up the socket: a request would queue behind the browser's six connections per host.
+    const source = this.source as Partial<SocketSource> | undefined
+    if (source?.send?.(JSON.stringify(message)) === true) return
     const post = this.options.post ?? ((url: string, body: string) => fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body }))
     post(`${this.options.base}/channel/answer`, JSON.stringify({ window: this.options.windowId, message })).catch(() => {
       // The Host is gone or restarting; the call it made settles on its side.
     })
   }
 }
+
+/** The WebSocket address of the door's routes: this page's own origin, `ws:` or `wss:`, then the base path. */
+function socketBase(base: string): string {
+  const here = (globalThis as { location?: { protocol: string; host: string } }).location
+  if (here === undefined) return base
+  return `${here.protocol === 'https:' ? 'wss' : 'ws'}://${here.host}${base}`
+}

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

@@ -22,7 +22,15 @@ export function startDoor(document: Document, base: string = DOOR_BASE): () => v
   const detachInput = clock.attach(document)
   const removeIndicator = mountIndicator(driver, document)
   const shellWindow = Number(/\bAcrylWindow\/(\d{1,9})\b/u.exec(view.navigator?.userAgent ?? '')?.[1])
-  const channel = new PageChannel(driver, { windowId, focused, base, ...(Number.isSafeInteger(shellWindow) && shellWindow > 0 ? { shellWindow } : {}) })
+  // `localStorage.setItem('acryl-door-transport', 'stream')` keeps this browser to the event stream (to compare, or behind a proxy that cannot upgrade).
+  const transport = ((): 'auto' | 'stream' => {
+    try {
+      return view.localStorage.getItem('acryl-door-transport') === 'stream' ? 'stream' : 'auto'
+    } catch {
+      return 'auto'
+    }
+  })()
+  const channel = new PageChannel(driver, { windowId, focused, base, transport, ...(Number.isSafeInteger(shellWindow) && shellWindow > 0 ? { shellWindow } : {}) })
   const reportFocus = (): void => { channel.reportFocus(focused()) }
   view.addEventListener('focus', reportFocus)
   view.addEventListener('blur', reportFocus)

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

@@ -0,0 +1,75 @@
+/**
+ * A WebSocket that looks like the event stream the channel already runs on: `addEventListener('call' | 'ready' | 'ping')`, `onerror`, `close()` and `readyState` (0 connecting, 1 open,
+ * 2 closed). Each frame from the Host is `{ "e": <event>, "d": <data> }`. It can also send, so the page's answers go up the same socket and need no request of their own: a request
+ * would wait behind the browser's six connections per host, which is what the socket is for.
+ */
+
+import type { ChannelSource } from './channel.ts'
+
+/** The slice of the browser's `WebSocket` used here, so a test can supply its own. */
+export interface SocketLike {
+  readyState: number
+  onopen: ((event: Event) => void) | null
+  onmessage: ((event: MessageEvent) => void) | null
+  onerror: ((event: Event) => void) | null
+  onclose: ((event: CloseEvent) => void) | null
+  send(data: string): void
+  close(code?: number, reason?: string): void
+}
+
+export interface SocketSource extends ChannelSource {
+  /** Send one message up; false when the socket is not open (the caller posts it instead). */
+  send(text: string): boolean
+}
+
+export function socketSource(socket: SocketLike): SocketSource {
+  const listeners = new Map<string, Array<(event: MessageEvent) => void>>()
+  let closed = false
+  const source: SocketSource = {
+    onerror: null,
+    get readyState(): number {
+      return closed || socket.readyState >= 2 ? 2 : socket.readyState
+    },
+    addEventListener(type, listener) {
+      listeners.set(type, [...(listeners.get(type) ?? []), listener])
+    },
+    send(text) {
+      if (socket.readyState !== 1) return false
+      try {
+        socket.send(text)
+        return true
+      } catch {
+        return false
+      }
+    },
+    close() {
+      closed = true
+      socket.onmessage = null
+      socket.onerror = null
+      socket.onclose = null
+      try {
+        socket.close(1000, 'page left')
+      } catch {
+        // Already closed.
+      }
+    },
+  }
+  socket.onmessage = (event) => {
+    if (typeof event.data !== 'string') return
+    let frame: { e?: unknown; d?: unknown }
+    try {
+      frame = JSON.parse(event.data) as { e?: unknown; d?: unknown }
+    } catch {
+      return
+    }
+    if (typeof frame.e !== 'string') return
+    for (const listener of listeners.get(frame.e) ?? []) listener({ data: typeof frame.d === 'string' ? frame.d : '' } as MessageEvent)
+  }
+  // An error or a close that this side did not ask for is the channel's cue to start over, or to fall back to the event stream.
+  const lost = (event: Event): void => {
+    if (!closed) source.onerror?.(event)
+  }
+  socket.onerror = lost
+  socket.onclose = lost
+  return source
+}