acrylblends 1.1.0 → 1.2.0

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

@@ -1,6 +1,9 @@
-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 { t as ConnectionInfo } from "../connection-ZLEso7XL.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-GUTAkFQT.js";
 import { n as UpgradeWebSocket } from "../index-C-SklY6u.js";
 import { n as serveStatic, t as ServeStaticOptions } from "../serve-static-B7sqnftW.js";
+import { IncomingMessage, ServerResponse } from "node:http";
+import { Duplex } from "node:stream";
 import { Context, Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 
@@ -8,6 +11,24 @@ import z from "@deepseek-ai/schemastery";
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
 declare const name = "acryl-node-server";
 declare const inject: string[];
+/** A raw node handler: the request and response are the platform's, and the adapter writes nothing for them. */
+interface RawRoute {
+  readonly kind: 'prefix' | 'exact';
+  readonly path: string;
+  readonly handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+}
+/** A raw upgrade handler: the socket is the handler's once the path matches; the router never sees the upgrade. */
+interface RawUpgradeRoute {
+  readonly path: string;
+  readonly handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>;
+}
+/**
+ * Answer a request before raw routes and the router, or pass it on with `undefined`. The callback runs synchronously, so a request no gate answers still
+ * reaches a raw route's sentinel synchronously; a gate that needs the router (a host keeping an app's URLs in scope under a prefix, the ACRYL frame's canvas)
+ * returns its promise, and the adapter handles that like the router's own answer. `connection` carries the socket facts, which a router mount needs to check
+ * the peer and the real port.
+ */
+type RequestGate = (request: Request, connection: ConnectionInfo) => Response | Promise<Response> | undefined;
 interface Config {
   hostname: string;
   port: number;
@@ -22,28 +43,105 @@ declare module '@deepseek-ai/cordis' {
     nodeServer: NodeServer;
   }
 }
+/**
+ * Milliseconds a request already in flight, or an upgraded socket's own owner, may finish once the server stops taking new work. A save during a
+ * restart must not be cut; a stream that never ends must not hold the stop open.
+ */
+declare const STOP_GRACE_MS = 2000;
 declare class NodeServer extends Service {
   readonly hostname: string;
   readonly config: Config;
   private readonly server;
+  private readonly router;
   private hub;
   private bound;
+  /** The one stop this server runs: a second call (the disposer after an explicit stop) waits on the same promise. */
+  private stopping;
+  /** Requests whose response has not finished yet: the stop waits for them before their sockets are cut. */
+  private active;
+  /** Upgraded sockets this server handed out (WebSockets): neither close() nor closeAllConnections() reaches them, so the stop tracks them itself. */
+  private readonly upgraded;
+  /** Raw routes registered by the host's compatibility layer (see {@link registerRaw}). */
+  private readonly rawExact;
+  private readonly rawPrefix;
+  private readonly rawUpgrades;
+  /** Gates registered by a host that maps an app's URLs (see {@link NodeServer.gate}); they run in the order they were added. */
+  private readonly gates;
+  /** One raw dispatch per upgrade request: a second listener (or a re-added one) must never emit the same request again. */
+  private readonly rawUpgradeSeen;
   constructor(ctx: Context, config: Config);
+  /**
+   * Stop serving, gracefully, and resolve once the port is free: no new connections; requests already in flight may finish (a stream that never ends is
+   * cut) within {@link STOP_GRACE_MS}; each upgraded socket's owner closes it with a close frame first, and what is left is destroyed. Idempotent - the
+   * disposer calls it.
+   *
+   * Calling this BEFORE the rest of the app is disposed is what makes the grace count: the router has its own disposal, and it aborts in-flight requests
+   * and ends their bodies by design, concurrently with every other disposer (Cordis runs them together). A launcher that disposes the context directly
+   * therefore cuts the request this drains; a launcher that stops the server first lets it answer, then disposes.
+   */
+  stop(): Promise<void>;
+  private closeGracefully;
+  /**
+   * Wait, bounded, until no request is in flight and no upgraded socket is left; true when both reached zero inside the bound. Every pass sweeps idle
+   * keep-alive sockets again: the single sweep `close()` does misses one that becomes idle after its request finished, and such a socket would otherwise
+   * hold the stop to its deadline.
+   */
+  private settleStop;
+  /**
+   * Serve a raw node handler at `path`, beside the router: `exact` matches the pathname only, `prefix` the path and everything below it. The
+   * handler gets the platform's `IncomingMessage`/`ServerResponse` and owns the response; the router is not run for it. A path already served
+   * throws. The returned remover restores the path (the server itself goes on serving the rest).
+   */
+  registerRaw(route: RawRoute): () => void;
+  /**
+   * Answer matching requests before raw routes and the router, so a host can keep an app's URLs in scope under a prefix (the frame's canvas). A gate runs
+   * synchronously and can answer with a promise (see {@link RequestGate}); gates run in the order they were added, and the returned remover takes this one back.
+   */
+  gate(handler: RequestGate): () => void;
+  /**
+   * A gate's asynchronous answer: run the request it was given through the router, in the adapter's request form (a gate never makes one itself), with the
+   * socket facts. The raw routes do not run for that request.
+   */
+  throughRouter(request: Request, connection?: ConnectionInfo): Promise<Response>;
+  /**
+   * Claim an upgrade path for a raw node handler: the handler receives `(req, socket, head)` and from then on owns the socket. The router's
+   * WebSocket handling never sees a claimed upgrade. A path already claimed throws; the remover releases the claim. The transport's one raw
+   * listener exists for the server's whole lifetime and consults this registry, so claims coming and going never add or remove a listener.
+   */
+  registerRawUpgrade(route: RawUpgradeRoute): () => void;
+  /** The raw handler for a request: an exact path first, then the longest matching prefix. */
+  private rawFor;
   /**
    * `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 `upgrade` listeners the transport holds (raw plus router setups); a test asserts it does not grow across claim changes. */
+  get upgradeListenerCount(): number;
   /** 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. */
   get url(): string;
-  /** Bind, scanning past taken ports. */
+  /** Bind, scanning past taken ports and past the ports a browser refuses. */
   listen(): Promise<void>;
 }
+/**
+ * The ports every Fetch client refuses to connect to: the Fetch standard's bad ports (https://fetch.spec.whatwg.org/#port-blocking). Chromium
+ * refuses a page on one (ERR_UNSAFE_PORT) and Node's fetch answers "bad port"; the list below is the one Node 24 reports, probed port by port
+ * on 2026-11-03 (82 ports, 1 to 10080). An app's stable port is hashed into 3100..3999, and 3659 is on the list: without this rule one app in
+ * 900 would come up on an address no browser may open, which the frame gate caught that day (verify-frame-token was refused at 3659).
+ */
+declare const RESTRICTED_PORTS: ReadonlySet<number>;
+/** Whether a browser refuses to open this port. */
+declare function isRestrictedPort(port: number): boolean;
+/**
+ * The ports `listen` may try, in order: `port` with at most `scan` further ones, without the ports a browser refuses. Port 0 stays alone: the
+ * system chooses it, and the ports it hands out are above the restricted range.
+ */
+declare function portCandidates(port: number, scan: number): number[];
 /**
  * Whether a failed bind means "this port, try the next one". A port another socket holds answers `EADDRINUSE` everywhere. On Windows a port
  * inside a range the system reserves (Hyper-V, WSL and Docker exclude ranges, `netsh interface ipv4 show excludedportrange`) answers
@@ -54,4 +152,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, type TestSocket, type TestWebSocketOptions, type TestWebSocketResult, UpgradeEmitter, UpgradeHub, type UpgradeHubOptions, type UpgradeRouter, apply, inject, isPortUnavailable, name, serveStatic, testWebSocket };
+export { Config, NodeServer, RESTRICTED_PORTS, RawRoute, RawUpgradeRoute, RequestError, RequestGate, STOP_GRACE_MS, type ServeStaticOptions, type TestSocket, type TestWebSocketOptions, type TestWebSocketResult, UpgradeEmitter, UpgradeHub, type UpgradeHubOptions, type UpgradeRouter, apply, inject, isPortUnavailable, isRestrictedPort, name, portCandidates, serveStatic, testWebSocket };

package/lib/cordis/node-server.js

@@ -1,4 +1,4 @@
-import { l as RequestError, n as UpgradeEmitter, r as UpgradeHub, t as testWebSocket } from "../test-websocket-BLeEvybj.js";
+import { d as RequestError, n as UpgradeEmitter, r as UpgradeHub, t as testWebSocket } from "../test-websocket-CQOSvBth.js";
 import { t as serveStatic } from "../serve-static-C1Nkj_xB.js";
-import { a as isPortUnavailable, i as inject, n as NodeServer, o as name, r as apply, t as Config } from "../src-LX0E4ec4.js";
-export { Config, NodeServer, RequestError, UpgradeEmitter, UpgradeHub, apply, inject, isPortUnavailable, name, serveStatic, testWebSocket };
+import { a as apply, c as isRestrictedPort, i as STOP_GRACE_MS, l as name, n as NodeServer, o as inject, r as RESTRICTED_PORTS, s as isPortUnavailable, t as Config, u as portCandidates } from "../src-CtkIX_Gg.js";
+export { Config, NodeServer, RESTRICTED_PORTS, RequestError, STOP_GRACE_MS, UpgradeEmitter, UpgradeHub, apply, inject, isPortUnavailable, isRestrictedPort, name, portCandidates, serveStatic, testWebSocket };

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

@@ -1,5 +1,5 @@
 import { n as UpgradeWebSocket } from "../index-C-SklY6u.js";
-import { i as RouterHttpService } from "../index-DMOtA-NJ.js";
+import { i as RouterHttpService } from "../index-DGq7H0lb.js";
 import { IncomingMessage, ServerResponse } from "node:http";
 import { Duplex } from "node:stream";
 import { Context, Service } from "@deepseek-ai/cordis";
@@ -52,6 +52,10 @@ declare class RouterHttp extends Service implements RouterHttpService {
   private readonly router;
   private readonly web;
   private hub;
+  /** One upgrade helper per calling context: a fresh wrapper per call made every service event look like an owner change. */
+  private readonly upgradeHelpers;
+  /** A stable identity for this service instance's hub: a caller that must recognize the same owner across calls keys on this, not on a helper. */
+  private readonly hubIdentity;
   /** 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;
@@ -69,6 +73,8 @@ declare class RouterHttp extends Service implements RouterHttpService {
    * `upgradeWebSocket` for the calling plugin: the sockets its routes accept are closed with 1001 when it unloads. Needs the `ws` package.
    * The route must be on a path the plugin mounted with `upgrade: [path]`.
    */
+  /** Stable for this service's lifetime; a re-provided adapter has a new one, which is how a caller sees a new owner. */
+  hubToken(): object;
   upgrades(): UpgradeWebSocket;
   /** How many WebSocket connections are open now. */
   get sockets(): number;

package/lib/cordis/router-http.js

@@ -1,5 +1,5 @@
-import { n as UpgradeEmitter, r as UpgradeHub } from "../test-websocket-BLeEvybj.js";
-import "../src-LX0E4ec4.js";
+import { n as UpgradeEmitter, r as UpgradeHub } from "../test-websocket-CQOSvBth.js";
+import "../src-CtkIX_Gg.js";
 import { Readable } from "node:stream";
 import { Service } from "@deepseek-ai/cordis";
 import { pipeline } from "node:stream/promises";
@@ -59,6 +59,33 @@ async function sendResponse(res, response, method) {
 }
 //#endregion
 //#region ../../plugins/acryl-router-http/src/serve.ts
+/** How long a refusal waits for a request body the handler never read. */
+const REQUEST_BODY_SETTLE_MS = 1e3;
+/**
+* Read and discard a request body the handler left unread (a guard's 403, a 415, a body over its limit), so the client can finish sending and
+* read the answer. Ending a response while request data is still arriving makes Node close the socket with that data pending, and the peer sees a
+* reset instead of the answer: reliably on Windows (the workspace git worktree test's read ECONNRESET) and on other systems under load. Bounded:
+* a client that stops sending waits at most `ms`, then loses the socket as before.
+*/
+function settleRequestBody(req, ms = REQUEST_BODY_SETTLE_MS) {
+	if (req.readableEnded || req.destroyed) return Promise.resolve();
+	return new Promise((resolve) => {
+		let timer;
+		const done = () => {
+			if (timer !== void 0) clearTimeout(timer);
+			req.off("end", done);
+			req.off("close", done);
+			req.off("error", done);
+			resolve();
+		};
+		timer = setTimeout(done, ms);
+		timer.unref?.();
+		req.once("end", done);
+		req.once("close", done);
+		req.once("error", done);
+		req.resume();
+	});
+}
 /**
 * Serve one node request through the router and write the result. The request's abort signal fires when the client
 * disconnects before the response finished; the socket's peer address and local port travel as connection info, never in the request.
@@ -78,6 +105,7 @@ async function serve(router, req, res) {
 	} catch {
 		response = new Response("Internal Server Error", { status: 500 });
 	}
+	if (method !== "GET" && method !== "HEAD") await settleRequestBody(req);
 	await sendResponse(res, response, method);
 }
 //#endregion
@@ -91,6 +119,10 @@ var RouterHttp = class extends Service {
 	router;
 	web;
 	hub;
+	/** One upgrade helper per calling context: a fresh wrapper per call made every service event look like an owner change. */
+	upgradeHelpers = /* @__PURE__ */ new WeakMap();
+	/** A stable identity for this service instance's hub: a caller that must recognize the same owner across calls keys on this, not on a helper. */
+	hubIdentity = {};
 	/** 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();
@@ -141,8 +173,17 @@ var RouterHttp = class extends Service {
 	* `upgradeWebSocket` for the calling plugin: the sockets its routes accept are closed with 1001 when it unloads. Needs the `ws` package.
 	* The route must be on a path the plugin mounted with `upgrade: [path]`.
 	*/
+	/** Stable for this service's lifetime; a re-provided adapter has a new one, which is how a caller sees a new owner. */
+	hubToken() {
+		return this.hubIdentity;
+	}
 	upgrades() {
-		return this.ensureHub().upgradeWebSocketFor(this.ctx);
+		const owner = this.ctx;
+		const cached = this.upgradeHelpers.get(owner);
+		if (cached !== void 0) return cached;
+		const created = this.ensureHub().upgradeWebSocketFor(owner);
+		this.upgradeHelpers.set(owner, created);
+		return created;
 	}
 	/** How many WebSocket connections are open now. */
 	get sockets() {

package/lib/cordis/router.d.ts

@@ -2,6 +2,6 @@ import { B as NotFoundHandler, L as MiddlewareHandler, O as Handler, Q as Valida
 import { c as StatusCode, n as ContentfulStatusCode } from "../http-status-DaAwGAFL.js";
 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 { a as TrailingSlash, i as RouterHttpService, n as MountableApp, o as apply, r as Router, s as name, t as Config } from "../index-DMOtA-NJ.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-DGq7H0lb.js";
 import { t as HTTPException } from "../http-exception-kpGJkmpi.js";
 export { Acryl, type AcrylRequest, 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

@@ -2,5 +2,5 @@ import { t as HTTPException } from "../http-exception-MjWkT89V.js";
 import { t as Context } from "../context-CkOh7Ygv.js";
 import { t as Acryl } from "../app-CQcGWjrk.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-BTBm4OPD.js";
+import { i as name, n as Router, r as apply, t as Config } from "../src-iBJ2ysV9.js";
 export { Acryl, Config, Context, HTTPException, Router, apply, connectionOf, getConnInfo, name };

package/lib/cordis/state.js

@@ -3,7 +3,7 @@ import { t as methodNotAllowed } from "../method-not-allowed-TO2_hnfl.js";
 import { r as streamSSE } from "../streaming-BlDaph8U.js";
 import { i as loopbackOnly, r as loopbackAuthority } from "../loopback-only-BbasoF7R.js";
 import "../helpers-BEjcdbgw.js";
-import "../src-BTBm4OPD.js";
+import "../src-iBJ2ysV9.js";
 import "../middleware-BfG_fp8P.js";
 import { Service } from "@deepseek-ai/cordis";
 //#region ../../plugins/acryl-state/src/cell.ts

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-BFpULBCj.js";
+import { n as AuditEntry, y as UiSnapshot } from "../protocol-BeIYCgTo.js";
+import { i as UiChannel, n as auditPath, r as PageStream, t as AuditLog } from "../audit-Bok_UNCn.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-BwM6T2nG.js";
+import { d as AuditLog, f as auditPath, n as HEARTBEAT_MS, p as UiChannel, r as pageChannelRoutes, t as renderSnapshot } from "../snapshot-text-CXTnjxGx.js";
 export { AuditLog, HEARTBEAT_MS, UiChannel, auditPath, pageChannelRoutes, renderSnapshot };

package/lib/door/page.d.ts

@@ -1,4 +1,4 @@
-import { _ as UiRequest, v as UiResult } from "../protocol-a2aqrp2X.js";
+import { _ as UiRequest, v as UiResult } from "../protocol-BeIYCgTo.js";
 
 //#region ../../plugins/acryl-door/src/page/driver/driver.d.ts
 interface DriverActivity {
@@ -16,6 +16,8 @@ interface UiDriverOptions {
   /** Milliseconds since the user last used the page (mouse, keyboard); Infinity when never. */
   readonly msSinceUserInput?: () => number;
   readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+  /** Called with the element an act is about to use, for the page to show it (the door's outline on what the agent touches). */
+  readonly touched?: (element: Element) => void;
   /** Leave the page: reload it, or go to a path of the app. Default: the document's own `location`, a moment after the answer is sent. */
   readonly leave?: (to: {
     readonly reload: true;
@@ -54,6 +56,11 @@ declare class UiDriver {
   /** @param signal - the Host cancelled the call. @throws UiControlError. */
   handle(request: UiRequest, signal?: AbortSignal): Promise<UiResult>;
   private run;
+  /**
+   * Run an act that may start a navigation (a click on a link, Enter in a form) and say so: the browser asks `beforeunload` when a navigation starts, during the act or a
+   * moment after it. The answer is sent before the page goes; the Host then waits for the next page instead of reading this one again.
+   */
+  private watchLeaving;
   /**
    * The page is about to be replaced, so the answer is given first and the move happens a moment later (the answer is a POST that the page's own unload would cut off).
    * The Host does not wait for this answer to be the last word: it waits for the page to come back.
@@ -81,6 +88,8 @@ interface ChannelSource {
 declare const SILENCE_MS = 45000;
 interface PageChannelOptions {
   readonly windowId: string;
+  /** The browser tab the page is in (kept across the tab's reloads and moves), so the Host follows a run's page into the next document of its tab. */
+  readonly tab?: string;
   /** The desktop window this page is in (`AcrylWindow/<n>` in the user agent, set by the Electron shell), so the Host can drive it by the number `window list` prints. */
   readonly shellWindow?: number;
   readonly focused: () => boolean;

package/lib/door/page.js

@@ -84,7 +84,7 @@ var PageChannel = class {
 	}
 	connect() {
 		if (this.disposed || this.source !== void 0) return;
-		const query = `window=${encodeURIComponent(this.options.windowId)}&focused=${this.options.focused() ? "1" : "0"}${this.options.shellWindow === void 0 ? "" : `&shell=${String(this.options.shellWindow)}`}`;
+		const query = `window=${encodeURIComponent(this.options.windowId)}&focused=${this.options.focused() ? "1" : "0"}${this.options.shellWindow === void 0 ? "" : `&shell=${String(this.options.shellWindow)}`}${this.options.tab === void 0 ? "" : `&tab=${encodeURIComponent(this.options.tab)}`}`;
 		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}`);
@@ -497,6 +497,15 @@ function valueOf(el, role) {
 	else if (el.hasAttribute("contenteditable")) value = el.textContent ?? void 0;
 	return value === void 0 || value === "" ? void 0 : clip(value, 100);
 }
+/** Choices of a select listed at most; a longer list ends with how many more there are. */
+const MAX_OPTIONS = 20;
+/** The choices of a native select (what `act select` takes), or undefined when it is not one or is sensitive. */
+function optionsOf(el) {
+	if (!(el instanceof HTMLSelectElement) || isSensitive(el)) return void 0;
+	const labels = [...el.options].filter((option) => !option.hidden).map((option) => clip((option.textContent ?? "").trim(), 60)).filter((label) => label !== "");
+	if (labels.length <= MAX_OPTIONS) return labels;
+	return [...labels.slice(0, MAX_OPTIONS), `(${String(labels.length - MAX_OPTIONS)} more)`];
+}
 /** Heading level, when the element is a heading. */
 function levelOf(el) {
 	const explicit = Number(el.getAttribute("aria-level"));
@@ -583,7 +592,7 @@ var SnapshotBuilder = class {
 		const root = this.root();
 		const view = root.ownerDocument.defaultView;
 		let offset = options.cursor ?? 0;
-		if (options.cursor === void 0) {
+		if (offset === 0) {
 			this.refs.begin();
 			const all = collect(root);
 			this.candidates = [...all.filter((c) => inViewport(c.element, view)), ...all.filter((c) => !inViewport(c.element, view))];
@@ -595,6 +604,7 @@ var SnapshotBuilder = class {
 			if (isProtected(candidate.element)) states.push("protected");
 			const value = valueOf(candidate.element, candidate.role);
 			const level = candidate.role === "heading" ? levelOf(candidate.element) : void 0;
+			const options = optionsOf(candidate.element);
 			return {
 				ref: this.refs.issue(candidate.element, candidate.role, candidate.name),
 				role: candidate.role,
@@ -602,7 +612,8 @@ var SnapshotBuilder = class {
 				depth: candidate.depth,
 				states,
 				...value === void 0 ? {} : { value },
-				...level === void 0 ? {} : { level }
+				...level === void 0 ? {} : { level },
+				...options === void 0 ? {} : { options }
 			};
 		});
 		const end = offset + page.length;
@@ -645,6 +656,7 @@ function prepare(env, ref) {
 	if (isProtected(element)) throw new UiControlError("protected", `"${resolved.name}" belongs to approval, permissions or Agent Control itself; only the user operates it`);
 	if (effectivelyHidden(element)) throw new UiControlError("not-actionable", `"${resolved.name}" is not visible`);
 	if (element.disabled === true || element.getAttribute("aria-disabled") === "true") throw new UiControlError("not-actionable", `"${resolved.name}" is disabled`);
+	env.touched?.(element);
 	return resolved;
 }
 function mouse(element, type) {
@@ -786,6 +798,7 @@ function scroll(env, request) {
 	const dy = request.direction === "up" ? -amount : request.direction === "down" ? amount : 0;
 	if (request.ref !== void 0) {
 		const { element, role, name } = env.refs.resolve(request.ref);
+		env.touched?.(element);
 		element.scrollBy?.({
 			left: dx,
 			top: dy
@@ -914,6 +927,8 @@ var RefTable = class {
 /** After the user touches the page, agent actions wait this long, so the user always wins. */
 const YIELD_MS = 400;
 const MAX_YIELD_MS = 2e3;
+/** How long after an act a navigation it started is still noticed (a link's navigation starts a task or two after the click). */
+const LEAVE_WATCH_MS = 50;
 function realSleep(ms, signal) {
 	return new Promise((resolve, reject) => {
 		if (signal.aborted) {
@@ -955,7 +970,8 @@ var UiDriver = class {
 		this.env = {
 			refs: this.refs,
 			document: options.document,
-			sleep: options.sleep ?? realSleep
+			sleep: options.sleep ?? realSleep,
+			...options.touched === void 0 ? {} : { touched: options.touched }
 		};
 	}
 	/** The current activity; the same object until something changes, as a store snapshot must be. */
@@ -1034,10 +1050,10 @@ var UiDriver = class {
 				...request.cursor === void 0 ? {} : { cursor: request.cursor },
 				...request.maxNodes === void 0 ? {} : { maxNodes: request.maxNodes }
 			});
-			case "click": return click(this.env, request);
-			case "type": return typeText(this.env, request);
+			case "click": return await this.watchLeaving(() => click(this.env, request), signal);
+			case "type": return await this.watchLeaving(() => typeText(this.env, request), signal);
 			case "select": return selectOption(this.env, request);
-			case "press": return pressKey(this.env, request);
+			case "press": return await this.watchLeaving(() => pressKey(this.env, request), signal);
 			case "scroll": return scroll(this.env, request);
 			case "wait": return wait(this.env, request, signal);
 			case "reload": return this.leave({ reload: true }, "reloading");
@@ -1045,6 +1061,29 @@ var UiDriver = class {
 		}
 	}
 	/**
+	* Run an act that may start a navigation (a click on a link, Enter in a form) and say so: the browser asks `beforeunload` when a navigation starts, during the act or a
+	* moment after it. The answer is sent before the page goes; the Host then waits for the next page instead of reading this one again.
+	*/
+	async watchLeaving(act, signal) {
+		const view = this.options.document().defaultView;
+		let leaving = false;
+		const onLeave = () => {
+			leaving = true;
+		};
+		view?.addEventListener("beforeunload", onLeave);
+		try {
+			const result = act();
+			if (!leaving) await this.env.sleep(LEAVE_WATCH_MS, signal);
+			return leaving ? {
+				...result,
+				leaving: true,
+				detail: `${result.detail === void 0 ? "" : `${result.detail}; `}the page is going to another address`
+			} : result;
+		} finally {
+			view?.removeEventListener("beforeunload", onLeave);
+		}
+	}
+	/**
 	* The page is about to be replaced, so the answer is given first and the move happens a moment later (the answer is a POST that the page's own unload would cut off).
 	* The Host does not wait for this answer to be the last word: it waits for the page to come back.
 	*/

package/lib/door/protocol.d.ts

@@ -1,2 +1,2 @@
-import { C as parseUiRequest, S as parseChannelToPage, _ as UiRequest, a as DEFAULT_SNAPSHOT_NODES, b as WINDOW_ID, c as MAX_WAIT_MS, d as UI_OPS, f as UiActionResult, g as UiOp, h as UiNode, i as ChannelToPage, l as MUTATING_OPS, m as UiErrorCode, n as AuditEntry, o as MAX_SNAPSHOT_NODES, p as UiControlError, r as ChannelToHost, s as MAX_TEXT_LENGTH, t as APP_PATH, u as UI_ERROR_CODES, v as UiResult, x as parseChannelToHost, y as UiSnapshot } from "../protocol-a2aqrp2X.js";
+import { C as parseUiRequest, S as parseChannelToPage, _ as UiRequest, a as DEFAULT_SNAPSHOT_NODES, b as WINDOW_ID, c as MAX_WAIT_MS, d as UI_OPS, f as UiActionResult, g as UiOp, h as UiNode, i as ChannelToPage, l as MUTATING_OPS, m as UiErrorCode, n as AuditEntry, o as MAX_SNAPSHOT_NODES, p as UiControlError, r as ChannelToHost, s as MAX_TEXT_LENGTH, t as APP_PATH, u as UI_ERROR_CODES, v as UiResult, x as parseChannelToHost, y as UiSnapshot } from "../protocol-BeIYCgTo.js";
 export { APP_PATH, AuditEntry, ChannelToHost, ChannelToPage, DEFAULT_SNAPSHOT_NODES, MAX_SNAPSHOT_NODES, MAX_TEXT_LENGTH, MAX_WAIT_MS, MUTATING_OPS, UI_ERROR_CODES, UI_OPS, UiActionResult, UiControlError, UiErrorCode, UiNode, UiOp, UiRequest, UiResult, UiSnapshot, WINDOW_ID, parseChannelToHost, parseChannelToPage, parseUiRequest };

package/lib/drivers.d.ts

@@ -26,10 +26,11 @@ type ChatEvent = {
 interface ChatDriver {
   readonly kind: 'chat';
   readonly name: string;
-  /** Runs one message. Aborting `signal` stops the run. */
+  /** Runs one message. Aborting `signal` stops the run. `page` is the door's id of the page whose panel asked, when it sent one: a driver that uses the page drives that one. */
   start(options: {
     message: string;
     signal: AbortSignal;
+    page?: string;
   }): AsyncIterable<ChatEvent>;
 }
 /** A live pseudo-terminal session. */
@@ -45,6 +46,14 @@ interface TerminalSession {
 interface TerminalDriver {
   readonly kind: 'terminal';
   readonly name: string;
+  /**
+   * Where the panel loads the terminal view from: the browser module that draws it, and the URL prefix the view's endpoints live under. The driver
+   * plugin serves both, so the view follows wherever the app is mounted (the root of its own server, or the prefix the ACRYL frame serves it at).
+   */
+  readonly view: {
+    readonly module: string;
+    readonly prefix: string;
+  };
   start(options: {
     cwd: string;
     env: NodeJS.ProcessEnv;

package/lib/{index-DMOtA-NJ.d.ts → index-DGq7H0lb.d.ts}

@@ -88,7 +88,17 @@ declare class Router extends Service {
    * mount's code a request is in. The core's `app.route` runs first so a sub-app's own `onError` still applies to its routes.
    */
   private snapshot;
-  /** Abort `flights`, cut their bodies short and wait for them to settle, at most `disposeGraceMs`. */
+  /**
+   * The router's own disposal: let the flights already in flight finish within `disposeGraceMs` - a save being written when the app stops must not be cut
+   * by the router beneath it - then abort what is left and settle it for a moment, so disposal does not wait a second full grace on code that ignores
+   * its abort signal.
+   */
+  private drain;
+  /** The one draining rule: let `flights` finish inside the grace, then abort and settle what is left. */
+  private drainFlights;
+  /** Resolve true when every flight settled inside `ms`, false at the deadline. */
+  private settledWithin;
+  /** Abort `flights`, cut their bodies short and wait for them to settle, at most `settleMs`. */
   private end;
   /** Turn errors no mounted app handled into responses. One handler per router; the calling plugin owns it. */
   onError(handler: ErrorHandler): () => void;

package/lib/node-server.d.ts

@@ -1,5 +1,5 @@
 import { t as Acryl } from "./app-D8riatvv.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 { 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-GUTAkFQT.js";
 import { n as serveStatic, t as ServeStaticOptions } from "./serve-static-B7sqnftW.js";
 import { t as getConnInfo } from "./conninfo-BCROmdnf.js";
 import { AddressInfo } from "node:net";
@@ -90,6 +90,12 @@ declare const getRequestListener: (fetchCallback: FetchCallback, options?: {
 interface ClientModulesOptions {
   /** The folder of client modules, absolute or relative to the working directory. */
   readonly root: string;
+  /**
+   * The URL prefix the app is mounted at, when the caller knows it. A host can compose app plugins under its own router, and under a
+   * Host whose router is a different copy of this package the request's match result is not visible here, so `basePath(c)` throws; the
+   * explicit prefix is then the only reliable way to know where the mount starts. Omitted, the router's `basePath(c)` is used.
+   */
+  readonly mount?: string | undefined;
   /** The folder {@link buildClientModules} wrote; with `NODE_ENV=production` it is served instead of compiling, which needs no `typescript`. */
   readonly compiled?: string | undefined;
   /** At most this many bytes of compiled modules are kept in memory (least recently served first out); 16 MiB when not given. */

package/lib/node-server.js

@@ -1,5 +1,5 @@
-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-BLeEvybj.js";
+import { a as serve, d as RequestError, i as createAdaptorServer, n as UpgradeEmitter, o as upgradeWebSocket, r as UpgradeHub, s as getRequestListener, t as testWebSocket } from "./test-websocket-CQOSvBth.js";
 import { t as serveStatic } from "./serve-static-C1Nkj_xB.js";
 import { t as getConnInfo } from "./conninfo-CWJwieh4.js";
-import { n as clientModules, t as buildClientModules } from "./client-modules-drj4mjhj.js";
+import { n as clientModules, t as buildClientModules } from "./client-modules-Bkdr83jO.js";
 export { RequestError, UpgradeEmitter, UpgradeHub, buildClientModules, clientModules, createAdaptorServer, getConnInfo, getRequestListener, serve, serveStatic, testWebSocket, upgradeWebSocket };

package/lib/{protocol-a2aqrp2X.d.ts → protocol-BeIYCgTo.d.ts}

@@ -36,6 +36,8 @@ interface UiNode {
   readonly value?: string;
   /** Heading level, when it is a heading. */
   readonly level?: number;
+  /** The choices of a select, as `act select` takes them, when it is not sensitive. */
+  readonly options?: readonly string[];
 }
 interface UiSnapshot {
   readonly generation: number;
@@ -93,6 +95,8 @@ interface UiActionResult {
     readonly name: string;
   };
   readonly detail?: string;
+  /** The act started a navigation (a link, a form that submits): this page is going away, and the Host waits for the next one. */
+  readonly leaving?: true;
 }
 type UiResult = UiSnapshot | UiActionResult;
 /**