acrylblends 1.0.7 → 1.0.9

package/lib/{audit-BD8_2pkh.d.ts → audit-Dw-siYTp.d.ts}

@@ -9,6 +9,11 @@ interface PageStream {
 interface ChannelOptions {
   /** How long a page has to acknowledge a read-only call (`look`, `wait`) before the next page is tried. */
   readonly ackMs?: number;
+  /**
+   * How long a read-only call waits for a page to register when there is none, or when every page was silent and a new one may be on its way (a page that is moving to another
+   * address registers again a moment later). 0 (the default) fails at once.
+   */
+  readonly attachWaitMs?: number;
 }
 /**
  * The pages and who drives which. One page answers a call, chosen the same way every time: the page the Host just sent somewhere (it comes back as a new page, `prefer`), else the
@@ -16,6 +21,7 @@ interface ChannelOptions {
  */
 declare class UiChannel {
   private readonly ackMs;
+  private readonly attachWaitMs;
   /** The page the Host sent to a new place and that came back: it keeps being driven until the person focuses another page. */
   private preferred;
   constructor(options?: ChannelOptions);
@@ -52,7 +58,7 @@ declare class UiChannel {
     signal?: AbortSignal;
     timeoutMs?: number;
     window?: number;
-  }): Promise<UiResult>;
+  }, retried?: boolean): Promise<UiResult>;
   private callOne;
   /**
    * A promise for the next time a page connects (a page that reloaded or moved opens a new stream). Ask for it BEFORE the call that makes the page leave, or a fast page is missed.

package/lib/cordis/door.d.ts

@@ -1,5 +1,5 @@
 import { f as UiActionResult, y as UiSnapshot } from "../protocol-a2aqrp2X.js";
-import { i as UiChannel, r as PageStream, t as AuditLog } from "../audit-BD8_2pkh.js";
+import { i as UiChannel, r as PageStream, t as AuditLog } from "../audit-Dw-siYTp.js";
 import { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 
@@ -37,6 +37,9 @@ interface ShellWindow {
   readonly focused: boolean;
   readonly width: number;
   readonly height: number;
+  /** Where the window's top left corner is on the screen (so two windows on top of each other can be told). */
+  readonly x?: number;
+  readonly y?: number;
 }
 interface ShellMenuItem {
   /** Labels from the top of the menu, joined with `>`: `File>New Note`. */

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 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 { 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-CBi3EMnj.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";
@@ -598,7 +600,7 @@ var DoorError = class extends Error {
 };
 /** A shell answer as text an agent reads: windows and menu items one to a line. */
 function renderShell(result) {
-	if ("windows" in result) return result.windows.length === 0 ? "no windows are open" : result.windows.map((window) => `${String(window.id)}  ${JSON.stringify(window.title)}  ${window.path}  ${String(window.width)}x${String(window.height)}${window.focused ? "  focused" : ""}`).join("\n");
+	if ("windows" in result) return result.windows.length === 0 ? "no windows are open" : result.windows.map((window) => `${String(window.id)}  ${JSON.stringify(window.title)}  ${window.path}  ${String(window.width)}x${String(window.height)}${window.x === void 0 || window.y === void 0 ? "" : `@${String(window.x)},${String(window.y)}`}${window.focused ? "  focused" : ""}`).join("\n");
 	if ("items" in result) return result.items.length === 0 ? "the app has no menu" : result.items.map((item) => `${item.path}${item.enabled ? "" : "  (disabled)"}${item.ends === true ? "  (ends the app; needs force)" : ""}`).join("\n");
 	return result.detail;
 }
@@ -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];
 /**
@@ -1318,7 +1380,7 @@ function apply(ctx, rawConfig = {}) {
 		ctx.logger?.error?.(`acryl-door: failed to ${operation}: ${cause instanceof Error ? cause.message : String(cause)}`);
 	};
 	const secret = newSecret();
-	const channel = new UiChannel();
+	const channel = new UiChannel({ attachWaitMs: 2e3 });
 	const shell = new ShellChannel();
 	const door = new Door({
 		channel,
@@ -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/host.d.ts

@@ -1,6 +1,6 @@
 import { t as Acryl } from "../app-D8riatvv.js";
 import { n as AuditEntry, y as UiSnapshot } from "../protocol-a2aqrp2X.js";
-import { i as UiChannel, n as auditPath, r as PageStream, t as AuditLog } from "../audit-BD8_2pkh.js";
+import { i as UiChannel, n as auditPath, r as PageStream, t as AuditLog } from "../audit-Dw-siYTp.js";
 
 //#region ../../plugins/acryl-door/src/host/page-routes.d.ts
 /** How often the Host writes a `ping`; the page gives up on a stream that is silent for three of these. */

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-m13Pk-AI.js";
+import { d as AuditLog, f as auditPath, n as HEARTBEAT_MS, p as UiChannel, r as pageChannelRoutes, t as renderSnapshot } from "../snapshot-text-CBi3EMnj.js";
 export { AuditLog, HEARTBEAT_MS, UiChannel, auditPath, pageChannelRoutes, renderSnapshot };

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/lib/{snapshot-text-m13Pk-AI.js → snapshot-text-CBi3EMnj.js}

@@ -34,10 +34,12 @@ const DEFAULT_ACK_MS = 3e3;
 */
 var UiChannel = class {
 	ackMs;
+	attachWaitMs;
 	/** The page the Host sent to a new place and that came back: it keeps being driven until the person focuses another page. */
 	preferred;
 	constructor(options = {}) {
 		this.ackMs = options.ackMs ?? DEFAULT_ACK_MS;
+		this.attachWaitMs = options.attachWaitMs ?? 0;
 	}
 	connections = /* @__PURE__ */ new Map();
 	pending = /* @__PURE__ */ new Map();
@@ -114,8 +116,10 @@ var UiChannel = class {
 	* until it speaks; a call that changes the page is never sent to a second page, because the first might still run it.
 	* @throws UiControlError `no-window`, `timeout`, `aborted`, `unloaded`, `disconnected`, or whatever the page refused with.
 	*/
-	async call(request, options = {}) {
+	async call(request, options = {}, retried = false) {
 		if (this.closed) throw new UiControlError("unloaded", "the door was unloaded");
+		const readOnlyCall = request.op === "snapshot" || request.op === "wait";
+		if (readOnlyCall && this.attachWaitMs > 0 && this.connections.size === 0) await this.expectNewPage(this.attachWaitMs);
 		const ordered = this.ordered();
 		const candidates = options.window === void 0 ? ordered : ordered.filter((connection) => connection.shellWindow === options.window);
 		if (candidates.length === 0 && options.window !== void 0) {
@@ -124,13 +128,21 @@ var UiChannel = class {
 		}
 		if (candidates.length === 0) throw new UiControlError("no-window", "no page of the app is open to control");
 		if (options.signal?.aborted === true) throw new UiControlError("aborted", "the call was cancelled");
-		const readOnly = request.op === "snapshot" || request.op === "wait";
-		for (const target of candidates) try {
-			return await this.callOne(target, request, options, readOnly);
-		} catch (cause) {
-			if (!(cause instanceof Silent)) throw cause;
+		const readOnly = readOnlyCall;
+		const tried = /* @__PURE__ */ new Set();
+		for (const target of candidates) {
+			tried.add(target.windowId);
+			try {
+				return await this.callOne(target, request, options, readOnly);
+			} catch (cause) {
+				if (!(cause instanceof Silent)) throw cause;
+			}
+		}
+		if (readOnly && !retried && this.attachWaitMs > 0 && options.window === void 0) {
+			const fresh = await this.expectNewPage(this.attachWaitMs);
+			if (fresh !== void 0 && !tried.has(fresh)) return await this.call(request, options, true);
 		}
-		throw new UiControlError("timeout", `no page of the app answered within ${String(Math.round(this.ackMs / 1e3))} s: the app's pages are open but none responded (a tab in the background, or a page that is still loading). Bring the app's tab to the front, or navigate it, then look again`);
+		throw new UiControlError("timeout", `no page of the app answered within ${String(Math.round(this.ackMs / 1e3))} s: the app's pages are open but none responded. Likely causes: a tab in the background, a page that is still loading after a navigation (look again), or a page that holds the browser's six connections with event streams of its own (a page should keep to two). Bring the app's tab to the front, or navigate it, then look again`);
 	}
 	callOne(target, request, options, failOver) {
 		const signal = options.signal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "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/channel.ts

@@ -57,6 +57,11 @@ const DEFAULT_ACK_MS = 3000
 export interface ChannelOptions {
   /** How long a page has to acknowledge a read-only call (`look`, `wait`) before the next page is tried. */
   readonly ackMs?: number
+  /**
+   * How long a read-only call waits for a page to register when there is none, or when every page was silent and a new one may be on its way (a page that is moving to another
+   * address registers again a moment later). 0 (the default) fails at once.
+   */
+  readonly attachWaitMs?: number
 }
 
 /**
@@ -65,11 +70,13 @@ export interface ChannelOptions {
  */
 export class UiChannel {
   private readonly ackMs: number
+  private readonly attachWaitMs: number
   /** The page the Host sent to a new place and that came back: it keeps being driven until the person focuses another page. */
   private preferred: string | undefined
 
   constructor(options: ChannelOptions = {}) {
     this.ackMs = options.ackMs ?? DEFAULT_ACK_MS
+    this.attachWaitMs = options.attachWaitMs ?? 0
   }
 
   private readonly connections = new Map<string, Connection>()
@@ -143,8 +150,11 @@ export class UiChannel {
    * until it speaks; a call that changes the page is never sent to a second page, because the first might still run it.
    * @throws UiControlError `no-window`, `timeout`, `aborted`, `unloaded`, `disconnected`, or whatever the page refused with.
    */
-  async call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number; window?: number } = {}): Promise<UiResult> {
+  async call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number; window?: number } = {}, retried = false): Promise<UiResult> {
     if (this.closed) throw new UiControlError('unloaded', 'the door was unloaded')
+    const readOnlyCall = request.op === 'snapshot' || request.op === 'wait'
+    // A page that is moving to another address registers again a moment later: a read-only call right after a navigate or reload waits for it, rather than failing.
+    if (readOnlyCall && this.attachWaitMs > 0 && this.connections.size === 0) await this.expectNewPage(this.attachWaitMs)
     const ordered = this.ordered()
     // `window` is the number `window list` prints: that desktop window's page, not the one used last.
     const candidates = options.window === undefined ? ordered : ordered.filter(connection => connection.shellWindow === options.window)
@@ -154,15 +164,22 @@ export class UiChannel {
     }
     if (candidates.length === 0) throw new UiControlError('no-window', 'no page of the app is open to control')
     if (options.signal?.aborted === true) throw new UiControlError('aborted', 'the call was cancelled')
-    const readOnly = request.op === 'snapshot' || request.op === 'wait'
+    const readOnly = readOnlyCall
+    const tried = new Set<string>()
     for (const target of candidates) {
+      tried.add(target.windowId)
       try {
         return await this.callOne(target, request, options, readOnly)
       } catch (cause) {
         if (!(cause instanceof Silent)) throw cause
       }
     }
-    throw new UiControlError('timeout', `no page of the app answered within ${String(Math.round(this.ackMs / 1000))} s: the app's pages are open but none responded (a tab in the background, or a page that is still loading). Bring the app's tab to the front, or navigate it, then look again`)
+    // Every page was silent. A page that registered meanwhile (the one that was moving) gets the call once.
+    if (readOnly && !retried && this.attachWaitMs > 0 && options.window === undefined) {
+      const fresh = await this.expectNewPage(this.attachWaitMs)
+      if (fresh !== undefined && !tried.has(fresh)) return await this.call(request, options, true)
+    }
+    throw new UiControlError('timeout', `no page of the app answered within ${String(Math.round(this.ackMs / 1000))} s: the app's pages are open but none responded. Likely causes: a tab in the background, a page that is still loading after a navigation (look again), or a page that holds the browser's six connections with event streams of its own (a page should keep to two). Bring the app's tab to the front, or navigate it, then look again`)
   }
 
   private callOne(target: Connection, request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number }, failOver: boolean): Promise<UiResult> {

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

@@ -71,7 +71,7 @@ function renderShell(result: ShellResult): string {
   if ('windows' in result) {
     return result.windows.length === 0
       ? 'no windows are open'
-      : result.windows.map(window => `${String(window.id)}  ${JSON.stringify(window.title)}  ${window.path}  ${String(window.width)}x${String(window.height)}${window.focused ? '  focused' : ''}`).join('\n')
+      : result.windows.map(window => `${String(window.id)}  ${JSON.stringify(window.title)}  ${window.path}  ${String(window.width)}x${String(window.height)}${window.x === undefined || window.y === undefined ? '' : `@${String(window.x)},${String(window.y)}`}${window.focused ? '  focused' : ''}`).join('\n')
   }
   if ('items' in result) return result.items.length === 0 ? 'the app has no menu' : result.items.map(item => `${item.path}${item.enabled ? '' : '  (disabled)'}${item.ends === true ? '  (ends the app; needs force)' : ''}`).join('\n')
   return result.detail

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'
 
@@ -113,7 +115,8 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
     ctx.logger?.error?.(`acryl-door: failed to ${operation}: ${cause instanceof Error ? cause.message : String(cause)}`)
   }
   const secret = newSecret()
-  const channel = new UiChannel()
+  // A look right after a navigate or reload waits up to two seconds for the page that is moving to register again, and a read-only call that no page acknowledged gives a page that just registered one more try.
+  const channel = new UiChannel({ attachWaitMs: 2000 })
   const shell = new ShellChannel()
   const audit = new AuditLog(auditPath(stateDir(app.root)))
   const door = new Door({
@@ -154,10 +157,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),