acrylblends 1.1.0 → 1.3.0

package/lib/{src-BTBm4OPD.js → src-iBJ2ysV9.js}

@@ -5,6 +5,8 @@ import { t as TrieRouter } from "./trie-router-JydLKUa2.js";
 import { t as Acryl } from "./app-CQcGWjrk.js";
 import "./core-BOu1jYua.js";
 import "./connection-C7xgP1hP.js";
+import { appendFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 //#region ../../plugins/acryl-router/src/service.ts
@@ -17,6 +19,28 @@ import z from "@deepseek-ai/schemastery";
 * response body still streaming and waits for all of it to settle.
 */
 const DEFAULT_DISPOSE_GRACE_MS = 2e3;
+/** How long disposal waits for the flights it had to abort after the drain, before it continues without them. */
+const ABORT_SETTLE_MS = 300;
+/** Set by ACRYL_ROUTER_TRACE=1: append request-signal lifecycle lines to ACRYL_ROUTER_TRACE_FILE (the CI artifact) - diagnostics for the abort-reaches-handler defect. */
+const traceFile = () => process.env.ACRYL_ROUTER_TRACE_FILE ?? `${tmpdir()}/acryl-router-trace.log`;
+const trace = (line) => {
+	if (process.env.ACRYL_ROUTER_TRACE !== "1") return;
+	try {
+		appendFileSync(traceFile(), `${String(Date.now())} [${String(process.pid)}] ${line}\n`);
+	} catch {}
+};
+let flightSeq = 0;
+const SIGNAL_TAG = Symbol.for("acryl.router.signalTag");
+const tagOf = (signal) => {
+	if (signal === void 0) return "none";
+	const tag = signal[SIGNAL_TAG];
+	return typeof tag === "string" ? tag : "untagged";
+};
+const tagSignal = (signal, tag) => {
+	try {
+		signal[SIGNAL_TAG] = tag;
+	} catch {}
+};
 /** Every field has a default, so a caller passes only what it changes: `ctx.plugin(plugin, { ... })` takes the partial shape. */
 const Config = z.object({
 	trailingSlash: z.union(["strict", "ignore"]).default("strict").description("Whether `/a` and `/a/` are different paths."),
@@ -64,8 +88,8 @@ var Router = class extends Service {
 		};
 		ctx.effect(() => async () => {
 			this.state.closing = true;
-			await this.end([...this.flights], "disposal");
-		}, "acryl-router: abort and settle in-flight requests");
+			await this.drain();
+		}, "acryl-router: drain in-flight requests, then abort what is left");
 	}
 	/** Registrations currently held (mounts, and the router-wide error and not-found handlers); a leak check for reload tests. */
 	get size() {
@@ -83,7 +107,7 @@ var Router = class extends Service {
 		const remove = () => {
 			if (!this.state.mounts.delete(mount)) return Promise.resolve();
 			this.state.composed = void 0;
-			return this.end([...this.flights].filter((flight) => (flight.running.get(mount) ?? 0) > 0 || flight.producer === mount), `removing ${path}`);
+			return this.drainFlights([...this.flights].filter((flight) => (flight.running.get(mount) ?? 0) > 0 || flight.producer === mount), `removing ${path}`);
 		};
 		const served = new Set(app.routes.map((route) => `${route.method} ${mergePath(path, route.path)}`));
 		const owner = this.ctx;
@@ -125,6 +149,7 @@ var Router = class extends Service {
 			const handler = async (c, next) => {
 				const flight = this.flightOf.get(c.req.raw);
 				if (flight === void 0) return inner(c, next);
+				trace(`handler ${flight.tag} requestTag=${tagOf(c.req.raw.signal)} innerTag=${tagOf(flight.inner.signal)} sameSignal=${String(c.req.raw.signal === flight.inner.signal)} aborted=${String(c.req.raw.signal.aborted)}`);
 				let calledNext = false;
 				flight.running.set(mount, (flight.running.get(mount) ?? 0) + 1);
 				try {
@@ -145,22 +170,52 @@ var Router = class extends Service {
 		}
 		return mount;
 	}
-	/** Abort `flights`, cut their bodies short and wait for them to settle, at most `disposeGraceMs`. */
-	async end(flights, why) {
+	/**
+	* 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.
+	*/
+	async drain() {
+		await this.drainFlights([...this.flights], "disposal");
+	}
+	/** The one draining rule: let `flights` finish inside the grace, then abort and settle what is left. */
+	async drainFlights(flights, why) {
+		trace(`drain ${why} chosen=[${flights.map((flight) => flight.tag).join(", ")}]`);
 		if (flights.length === 0) return;
-		for (const flight of flights) {
-			flight.controller.abort();
-			flight.endBody();
+		if (await this.settledWithin(flights, this.graceMs)) {
+			trace(`drain ${why} settled inside the grace`);
+			return;
 		}
+		const left = flights.filter((flight) => this.flights.has(flight));
+		trace(`drain ${why} grace over left=[${left.map((flight) => flight.tag).join(", ")}]`);
+		if (left.length > 0) await this.end(left, why, ABORT_SETTLE_MS);
+	}
+	/** Resolve true when every flight settled inside `ms`, false at the deadline. */
+	async settledWithin(flights, ms) {
 		let timer;
 		const gaveUp = new Promise((resolve) => {
 			timer = setTimeout(() => {
-				resolve("gave-up");
-			}, this.graceMs);
+				resolve(false);
+			}, ms);
 		});
-		const outcome = await Promise.race([Promise.allSettled(flights.map((flight) => flight.settled)).then(() => "settled"), gaveUp]);
+		const outcome = await Promise.race([Promise.allSettled(flights.map((flight) => flight.settled)).then(() => true), gaveUp]);
 		clearTimeout(timer);
-		if (outcome === "gave-up") this.ctx.logger.warn(`acryl-router: ${String(flights.length)} request(s) did not finish ${String(this.graceMs)} ms after abort (${why}); continued without them`);
+		return outcome;
+	}
+	/** Abort `flights`, cut their bodies short and wait for them to settle, at most `settleMs`. */
+	async end(flights, why, settleMs = this.graceMs) {
+		if (flights.length === 0) return;
+		for (const flight of flights) {
+			trace(`abort ${flight.tag} before=${String(flight.controller.signal.aborted)}`);
+			flight.controller.abort();
+			trace(`abort ${flight.tag} after=${String(flight.controller.signal.aborted)} innerAborted=${String(flight.inner.signal.aborted)}`);
+			queueMicrotask(() => {
+				trace(`post-abort ${flight.tag} innerAborted=${String(flight.inner.signal.aborted)}`);
+			});
+			flight.endBody();
+		}
+		if (await this.settledWithin(flights, settleMs)) return;
+		this.ctx.logger.warn(`acryl-router: ${String(flights.length)} request(s) did not finish ${String(settleMs)} ms after abort (${why}); continued without them`);
 	}
 	/** Turn errors no mounted app handled into responses. One handler per router; the calling plugin owns it. */
 	onError(handler) {
@@ -203,7 +258,10 @@ var Router = class extends Service {
 	* `bindings` is an object an adapter hands to the handler as `c.env` (an upgrade request's socket hooks, for `upgradeWebSocket`); `connection` is added to it.
 	*/
 	fetch(request, connection = {}, bindings) {
-		if (this.state.closing) return Promise.resolve(new Response("Service Unavailable", { status: 503 }));
+		if (this.state.closing) return Promise.resolve(new Response("Service Unavailable", {
+			status: 503,
+			headers: { connection: "close" }
+		}));
 		const controller = new AbortController();
 		const forward = () => controller.abort();
 		if (request.signal.aborted) controller.abort();
@@ -220,8 +278,13 @@ var Router = class extends Service {
 		let bodyDone = Promise.resolve();
 		let endBody = () => {};
 		let resolveSettled;
+		const tag = `f${String(++flightSeq)}`;
+		const inner = new Request(request, { signal: controller.signal });
+		tagSignal(inner.signal, tag);
 		const flight = {
 			controller,
+			inner,
+			tag,
 			running: /* @__PURE__ */ new Map(),
 			producer: void 0,
 			endBody: () => {
@@ -231,7 +294,7 @@ var Router = class extends Service {
 				resolveSettled = resolve;
 			})
 		};
-		const inner = new Request(request, { signal: controller.signal });
+		trace(`create ${tag} ${request.method} ${new URL(request.url).pathname}`);
 		this.flightOf.set(inner, flight);
 		const response = this.dispatch(inner, env, executionCtx).then((raw) => {
 			const tracked = this.track(raw);

package/lib/{test-websocket-BLeEvybj.js → test-websocket-CQOSvBth.js}

@@ -744,6 +744,12 @@ Object.defineProperty(Response$1, "json", {
 	configurable: true
 });
 //#endregion
+//#region ../../plugins/acryl-node-server/src/adapter/raw.ts
+/** Returned by a raw-aware fetch callback: the node response is already owned, do not write. */
+const RAW_RESPONSE_HANDLED = Symbol.for("acryl-node-server.raw-response");
+/** Set on an upgrade request a raw handler took over; the adapter's WebSocket setup skips it. */
+const RAW_UPGRADE_HANDLED = Symbol.for("acryl-node-server.raw-upgrade");
+//#endregion
 //#region ../../plugins/acryl-node-server/src/adapter/utils.ts
 async function readWithoutBlocking(readPromise) {
 	return Promise.race([readPromise, Promise.resolve().then(() => Promise.resolve(void 0))]);
@@ -1040,6 +1046,7 @@ const getRequestListener = (fetchCallback, options = {}) => {
 				incoming,
 				outgoing
 			});
+			if (res === RAW_RESPONSE_HANDLED) return;
 			if (!isPromise(res) && isImmediateCacheableResponse(res)) {
 				if (needsBodyCleanup && !incoming.readableEnded) outgoing.once("finish", () => {
 					if (!incoming.readableEnded) drainIncoming(incoming);
@@ -1137,6 +1144,7 @@ const appendResponseHeaders = (headers, responseHeaders) => {
 	});
 };
 const rejectUpgradeRequest = (socket, status, responseHeaders) => {
+	if (socket.destroyed || socket.writableEnded) return;
 	const responseLines = ["Connection: close", "Content-Length: 0"];
 	appendResponseHeaders(responseLines, responseHeaders);
 	socket.end(`HTTP/1.1 ${status.toString()} ${STATUS_CODES[status] ?? ""}\r\n${responseLines.join("\r\n")}\r\n\r
@@ -1154,7 +1162,7 @@ const createUpgradeRequest = (request) => {
 	return new Request(url, { headers });
 };
 const setupWebSocket = (options) => {
-	const { server, fetchCallback, wss } = options;
+	const { server, fetchCallback, wss, skipWhenRawUpgrade = false } = options;
 	const waiterMap = /* @__PURE__ */ new Map();
 	wss.on("connection", (ws, request) => {
 		const waiter = waiterMap.get(request);
@@ -1180,8 +1188,9 @@ const setupWebSocket = (options) => {
 		});
 	};
 	server.on("upgrade", async (request, socket, head) => {
+		if (skipWhenRawUpgrade && request[RAW_UPGRADE_HANDLED] === true) return;
 		if (request.headers.upgrade?.toLowerCase() !== "websocket") {
-			if (server.listenerCount("upgrade") === 1) rejectUpgradeRequest(socket, 400);
+			rejectUpgradeRequest(socket, 400);
 			return;
 		}
 		const env = {
@@ -1199,13 +1208,13 @@ const setupWebSocket = (options) => {
 				responseHeaders = response.headers;
 			}
 		} catch {
-			if (server.listenerCount("upgrade") === 1) rejectUpgradeRequest(socket, 500);
+			rejectUpgradeRequest(socket, 500);
 			return;
 		}
 		const waiter = waiterMap.get(request);
 		if (!waiter || waiter.connectionSymbol !== env[CONNECTION_SYMBOL_KEY]) {
 			rejectWaiter(request);
-			if (server.listenerCount("upgrade") === 1) rejectUpgradeRequest(socket, status, responseHeaders);
+			rejectUpgradeRequest(socket, status, responseHeaders);
 			return;
 		}
 		const addResponseHeaders = (headers) => {
@@ -1389,7 +1398,7 @@ var UpgradeHub = class {
 	* Accept upgrades from `source` and answer them with `router`: the request runs through the router's middleware with the socket's peer address and local port as connection
 	* facts (so the same loopback, origin and host checks work), and the upgrade bindings travel in `c.env` for `upgradeWebSocket`.
 	*/
-	attach(source, router) {
+	attach(source, router, options = {}) {
 		const fetchCallback = (request, env) => {
 			const { incoming } = env;
 			return router.fetch(request, {
@@ -1400,7 +1409,8 @@ var UpgradeHub = class {
 		setupWebSocket({
 			server: source,
 			fetchCallback,
-			wss: this.server
+			wss: this.server,
+			...options
 		});
 	}
 	/** How many sockets are open. */
@@ -1541,4 +1551,4 @@ async function testWebSocket(fetch, path, options = {}) {
 	};
 }
 //#endregion
-export { serve as a, Request$1 as c, createAdaptorServer as i, RequestError as l, UpgradeEmitter as n, upgradeWebSocket as o, UpgradeHub as r, getRequestListener as s, testWebSocket as t };
+export { serve as a, RAW_RESPONSE_HANDLED as c, RequestError as d, createAdaptorServer as i, RAW_UPGRADE_HANDLED as l, UpgradeEmitter as n, upgradeWebSocket as o, UpgradeHub as r, getRequestListener as s, testWebSocket as t, Request$1 as u };

package/lib/{test-websocket-DyeS50Tr.d.ts → test-websocket-GUTAkFQT.d.ts}

@@ -88,7 +88,9 @@ declare class UpgradeHub {
    * Accept upgrades from `source` and answer them with `router`: the request runs through the router's middleware with the socket's peer address and local port as connection
    * facts (so the same loopback, origin and host checks work), and the upgrade bindings travel in `c.env` for `upgradeWebSocket`.
    */
-  attach(source: UpgradeSource, router: UpgradeRouter): void;
+  attach(source: UpgradeSource, router: UpgradeRouter, options?: {
+    skipWhenRawUpgrade?: boolean;
+  }): void;
   /** How many sockets are open. */
   get size(): number;
   /** `upgradeWebSocket` for the plugin `owner`: the sockets it accepts are closed with 1001 when that plugin unloads. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",
@@ -405,6 +405,7 @@
     "dist",
     "lib",
     "templates",
+    "legacy",
     "shared",
     "plugins",
     "docs"

package/plugins/acryl-door/plugin.json

@@ -11,6 +11,9 @@
   "devDependencies": {
     "ws": "8.21.3"
   },
+  "scripts": {
+    "acryl": "node plugins/acryl-door/src/cli/acryl.ts"
+  },
   "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/cli/acryl.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * The door's operator client: what `<app>/.acryl/bin/acryl` runs. It finds the app from the folder it is started in (the nearest
+ * The door's operator client: what `npm run acryl -- <verb>` and `<app>/.acryl/bin/acryl` run. It finds the app from the folder it is started in (the nearest
  * `.acryl/door.json` upward, or `--dir`), never through PATH or a machine-wide registry, so it reaches only the app running from that
  * folder. The secret is read from that file and sent as a `Bearer` header; it is never printed.
  *
@@ -10,13 +10,14 @@
  * Exit codes: 0 done, 1 the verb failed (its code and message are printed), 2 a usage error, 3 no running app in this folder.
  */
 
+import { createInterface } from 'node:readline/promises'
 import { existsSync, realpathSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { readDoorFile, STATE_DIR, DOOR_FILE } from '../host/door-file.ts'
 
 const ACT_OPS = new Set(['click', 'type', 'select', 'press', 'scroll', 'wait', 'reload', 'navigate'])
-const VALUED = new Set(['--dir', '--ref', '--text', '--option', '--key', '--direction', '--amount', '--cursor', '--max-nodes', '--role', '--name', '--timeout-ms', '--id', '--width', '--height', '--window', '--tool', '--args', '--path'])
+const VALUED = new Set(['--dir', '--owner', '--license', '--ref', '--text', '--option', '--key', '--direction', '--amount', '--cursor', '--max-nodes', '--role', '--name', '--timeout-ms', '--id', '--width', '--height', '--window', '--tool', '--args', '--path'])
 const FLAGS = new Set(['--json', '--submit', '--no-clear', '--gone', '--force', '--help'])
 
 export class UsageError extends Error {}
@@ -42,7 +43,7 @@ const USAGE = `usage: acryl <verb> [options] [--json] [--dir <app folder>]
   act navigate --path <path of the app, e.g. /demo>
   act wait (--text <t> | --role <role> [--name <n>]) [--gone] [--timeout-ms <ms>]
   (look and every act take --window <n>: the desktop window whose page it is for; window list prints the numbers)
-  plugin list | plugin add <folder> | plugin remove <name> | plugin reload
+  plugin list | plugin add <folder> | plugin pull <source> | plugin publish <name> [--owner <account>] [--license <id>] | plugin remove <name> | plugin reload
   window list | window open [--path <p>] | window focus --id <n> | window close --id <n> [--force]
   window resize --id <n> --width <px> --height <px>
   menu list | menu click --path "File>New Note" [--force]
@@ -138,8 +139,15 @@ export function parseInvocation(argv: readonly string[], env: NodeJS.ProcessEnv
     case 'plugin': {
       if (second === 'list' || second === 'reload') return make(`plugin-${second}`)
       if (second === 'add') { if (third === undefined) throw new UsageError('plugin add needs a folder, e.g. plugin add plugins/pomodoro'); return make('plugin-add', { folder: third }) }
+      if (second === 'pull') { if (third === undefined) throw new UsageError('plugin pull needs a source, e.g. plugin pull github:someone/pomodoro@0.1.0'); return make('plugin-pull', { source: third }) }
+      if (second === 'publish') {
+        if (third === undefined) throw new UsageError('plugin publish needs a plugin name, e.g. plugin publish pomodoro')
+        const owner = values.get('--owner')
+        const license = values.get('--license')
+        return make('plugin-publish', { name: third, ...(owner === undefined ? {} : { owner }), ...(license === undefined ? {} : { license }) })
+      }
       if (second === 'remove') { if (third === undefined) throw new UsageError('plugin remove needs a plugin name'); return make('plugin-remove', { name: third }) }
-      throw new UsageError(`plugin needs list, add, remove or reload\n${USAGE}`)
+      throw new UsageError(`plugin needs list, add, pull, publish, remove or reload\n${USAGE}`)
     }
     case 'window': {
       const id = integer(values, '--id')
@@ -199,6 +207,11 @@ export interface Io {
   readonly out: (text: string) => void
   readonly err: (text: string) => void
   readonly fetch?: typeof fetch
+  /**
+   * Ask the person at this terminal; absent when nobody is there (a pipe, an agent's shell), and then nothing that needs a yes can happen.
+   * @returns whether they said yes.
+   */
+  readonly ask?: (question: string) => Promise<boolean>
 }
 
 /** Run one invocation. @returns the exit code. */
@@ -214,7 +227,7 @@ export async function main(argv: readonly string[], io: Io): Promise<number> {
   const app = findApp(io.cwd, invocation.dir)
   const file = app === undefined ? undefined : readDoorFile(app)
   if (app === undefined || file === undefined) {
-    io.err(`no running app${app === undefined ? ` in ${io.cwd} or above it` : ` in ${app}`}: start it (npm run dev) in its folder, then try again\n`)
+    io.err(`no running app${app === undefined ? ` in ${io.cwd} or above it` : ` in ${app}`}: these commands reach the running app, so start it (npm run dev) in its folder in another terminal, then run the same line again\n`)
     return 3
   }
   const request = io.fetch ?? fetch
@@ -225,7 +238,7 @@ export async function main(argv: readonly string[], io: Io): Promise<number> {
       ? await request(`${file.url}/api/acryl-door/verbs`, { headers })
       : await request(`${file.url}/api/acryl-door/call`, { method: 'POST', headers, body: JSON.stringify({ verb: invocation.verb, args: invocation.args }) })
   } catch {
-    io.err(`no running app in ${app}: ${file.url} does not answer (it stopped without removing .acryl/door.json?); start it again\n`)
+    io.err(`no running app in ${app}: ${file.url} does not answer (it stopped without removing .acryl/door.json?); start it (npm run dev), then run the same line again\n`)
     return 3
   }
   if (response.status === 403) {
@@ -243,9 +256,52 @@ export async function main(argv: readonly string[], io: Io): Promise<number> {
     return 1
   }
   io.out(invocation.json ? `${JSON.stringify(body.value)}\n` : `${body.text ?? ''}\n`)
+  if (invocation.verb === 'plugin-publish' && io.ask !== undefined && isPlan(body.value)) return confirmPublish(invocation, body.value, io, request, `${file.url}/api/acryl-door/publish-confirmed`, headers)
   return 0
 }
 
+const isPlan = (value: unknown): value is PlanAsked =>
+  typeof value === 'object' && value !== null && 'owner' in value
+
+/** What the prompt names. */
+interface PlanAsked {
+  readonly owner: string
+  readonly repo: string
+  readonly version: string
+  readonly license: string
+}
+
+/** The person's yes: only what they just read is published, and anything but a plain yes sends nothing. */
+async function confirmPublish(
+  invocation: Invocation,
+  plan: PlanAsked,
+  io: Io,
+  request: typeof fetch,
+  url: string,
+  headers: Record<string, string>,
+): Promise<number> {
+  const yes = await io.ask?.(`Publish ${plan.owner}/${plan.repo} v${plan.version} under ${plan.license}? Type yes to send it: `)
+  if (yes !== true) { io.out('Nothing was sent.\n'); return 0 }
+  const response = await request(url, { method: 'POST', headers, body: JSON.stringify({ name: invocation.args.name, owner: invocation.args.owner, license: invocation.args.license, confirm: plan }) })
+  const body = await response.json().catch(() => undefined) as { ok?: boolean; message?: string; value?: { ok?: boolean; releaseUrl?: string; pullLine?: string; reason?: string; next?: string } } | undefined
+  const result = body?.value
+  if (body?.ok !== true || result?.ok !== true) {
+    io.err(`Not published: ${result?.reason ?? body?.message ?? 'the app did not answer'}${result?.next === undefined ? '' : `. ${result.next}`}\n`)
+    return 1
+  }
+  io.out(`Published: ${result.releaseUrl ?? ''}\nA friend gets exactly these bytes with:\n  ${result.pullLine ?? ''}\n`)
+  return 0
+}
+
+async function askAtTerminal(question: string): Promise<boolean> {
+  const prompt = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    return (await prompt.question(question)).trim().toLowerCase() === 'yes'
+  } finally {
+    prompt.close()
+  }
+}
+
 /** True when this file is the program Node was started with (not imported by a test). */
 function isProgram(): boolean {
   const entry = process.argv[1]
@@ -262,6 +318,7 @@ if (isProgram()) {
     cwd: process.cwd(),
     out: (text) => { process.stdout.write(text) },
     err: (text) => { process.stderr.write(text) },
+    ...(process.stdin.isTTY && process.stdout.isTTY ? { ask: askAtTerminal } : {}),
   }).then((code) => { process.exitCode = code }, (cause: unknown) => {
     process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`)
     process.exitCode = 1

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

@@ -44,6 +44,8 @@ interface Connection {
   readonly windowId: string
   /** The desktop window the page is in, when the Electron shell tagged it. */
   readonly shellWindow: number | undefined
+  /** The browser tab the page is in (the page keeps it for the tab's lifetime): a page that reloads or moves to another path comes back with a new window id and the same tab. */
+  readonly tab: string | undefined
   focused: boolean
   /** Order of last focus (or connection), so the most recent wins. */
   lastActive: number
@@ -64,23 +66,39 @@ export interface ChannelOptions {
    * address registers again a moment later). 0 (the default) fails at once.
    */
   readonly attachWaitMs?: number
+  /**
+   * Every call must name the page it is for (`page`), and goes to that page alone: never to the page in front or the one used last, which may be another visitor's. A page-only door
+   * (a production assistant, one channel for every visitor of the app) sets it.
+   */
+  readonly requirePage?: boolean
+}
+
+/** A page whose panel asked for a run: the id the run knows it by, and where that page is now (the same tab after a reload or a move). */
+interface Asker {
+  /** The window id the run was asked from: what its calls name as `page`. */
+  readonly origin: string
+  windowId: string
+  tab: string | undefined
 }
 
 /**
  * The pages and who drives which. One page answers a call, chosen the same way every time: the page whose panel asked for the run that is making the call (`driveFor`), else the page the
  * Host just sent somewhere (it comes back as a new page, `prefer`), else the one in front (it reports `focused`), else the most recently active; a page that did not acknowledge a call in time goes to the end of the line. An explicit desktop `window` picks its page.
+ * A call that names its `page` (the page a run was asked from) goes to that page alone, followed into its tab when it reloads or moves, and to no other.
  */
 export class UiChannel {
   private readonly ackMs: number
   private readonly attachWaitMs: number
+  private readonly requirePage: boolean
   /** 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
   /** The pages whose panels have a run going, the latest last: a call with no `window` goes to the latest of them that is still connected. */
-  private readonly askers: Array<{ windowId: string }> = []
+  private readonly askers: Asker[] = []
 
   constructor(options: ChannelOptions = {}) {
     this.ackMs = options.ackMs ?? DEFAULT_ACK_MS
     this.attachWaitMs = options.attachWaitMs ?? 0
+    this.requirePage = options.requirePage === true
   }
 
   private readonly connections = new Map<string, Connection>()
@@ -95,12 +113,17 @@ export class UiChannel {
    * Register a page's stream. A stream already open for the same window is closed first, and its calls settle as `disconnected`.
    * @returns the function to call when this stream ends.
    */
-  attach(windowId: string, focused: boolean, stream: PageStream, shellWindow?: number): () => void {
+  attach(windowId: string, focused: boolean, stream: PageStream, shellWindow?: number, tab?: string): () => void {
     const previous = this.connections.get(windowId)
     if (previous !== undefined) this.drop(previous, true)
     // A page that did not answer stays last in line when its stream reconnects: a tab that cannot answer reconnects just as readily, and would otherwise be first again.
-    const connection: Connection = { stream, windowId, shellWindow, focused, lastActive: ++this.clock, suspect: previous?.suspect === true }
+    const connection: Connection = { stream, windowId, shellWindow, tab, focused, lastActive: ++this.clock, suspect: previous?.suspect === true }
     this.connections.set(windowId, connection)
+    // A run's page that reloaded or moved comes back as a new page in the same tab: the run goes on with it.
+    for (const asker of this.askers) {
+      if (asker.windowId === windowId) asker.tab ??= tab
+      else if (tab !== undefined && asker.tab === tab) asker.windowId = windowId
+    }
     // A page that reloaded or came back during its own run is told the run is still going.
     if (this.askers.some(asker => asker.windowId === windowId)) this.tell(connection, '1')
     for (const waiter of [...this.attachWaiters]) waiter(windowId)
@@ -149,7 +172,7 @@ export class UiChannel {
    * @returns the function to call when the run ends.
    */
   driveFor(windowId: string): () => void {
-    const asker = { windowId }
+    const asker: Asker = { origin: windowId, windowId, tab: this.connections.get(windowId)?.tab }
     this.askers.push(asker)
     this.tellPage(windowId, '1')
     return () => {
@@ -161,6 +184,33 @@ export class UiChannel {
     }
   }
 
+  /** Where the page a run was asked from is now: the same window, or the page that replaced it in the same tab. */
+  private whereIs(page: string): { windowId: string; tab: string | undefined } {
+    const asker = [...this.askers].reverse().find(entry => entry.origin === page)
+    return asker === undefined ? { windowId: page, tab: this.connections.get(page)?.tab } : { windowId: asker.windowId, tab: asker.tab }
+  }
+
+  /**
+   * A promise for the run's page coming back after a reload or a move: the next page that connects in its tab (or with its window id). Ask for it BEFORE the call that makes the page
+   * leave. Pages of other tabs, another visitor's among them, are never taken for it.
+   * @param signal - stop waiting (the act did not move the page after all); the promise then answers `undefined`.
+   * @returns the window id of the page that came back, or `undefined` when it did not within `timeoutMs`.
+   */
+  expectPageBack(page: string, timeoutMs: number, signal?: AbortSignal): Promise<string | undefined> {
+    const { windowId, tab } = this.whereIs(page)
+    return new Promise((resolve) => {
+      const done = (value: string | undefined): void => { clearTimeout(timer); this.attachWaiters.delete(waiter); signal?.removeEventListener('abort', stop); resolve(value) }
+      const stop = (): void => { done(undefined) }
+      signal?.addEventListener('abort', stop, { once: true })
+      const waiter = (attached: string): void => {
+        const connection = this.connections.get(attached)
+        if (attached === windowId || (tab !== undefined && connection?.tab === tab)) done(attached)
+      }
+      const timer = setTimeout(() => { done(undefined) }, timeoutMs)
+      this.attachWaiters.add(waiter)
+    })
+  }
+
   private tellPage(windowId: string, running: '0' | '1'): void {
     const connection = this.connections.get(windowId)
     if (connection !== undefined) this.tell(connection, running)
@@ -176,8 +226,10 @@ export class UiChannel {
     if (connection === undefined) return
     this.preferred = windowId
     connection.lastActive = ++this.clock
-    // A run's own page that reloaded or navigated comes back as a new page: the run goes on with that one.
-    for (const asker of this.askers) if (!this.connections.has(asker.windowId)) asker.windowId = windowId
+    // A run's own page that reloaded or navigated comes back as a new page: the run goes on with that one. A run whose page has a tab follows only that tab, so
+    // another visitor's page is never taken for it.
+    for (const asker of this.askers)
+      if (!this.connections.has(asker.windowId) && (asker.tab === undefined || asker.tab === connection.tab)) asker.windowId = windowId
     if (this.askers.some(asker => asker.windowId === windowId)) this.tellPage(windowId, '1')
   }
 
@@ -186,9 +238,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 } = {}, retried = false): Promise<UiResult> {
+  async call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number; window?: number; page?: string } = {}, retried = false): Promise<UiResult> {
     if (this.closed) throw new UiControlError('unloaded', 'the door was unloaded')
     const readOnlyCall = request.op === 'snapshot' || request.op === 'wait'
+    if (options.page !== undefined) return await this.callPage(request, options.page, options, readOnlyCall)
+    if (this.requirePage) throw new UiControlError('no-window', 'this door drives only the page whose visitor asked, and the call names no page')
     // 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()
@@ -218,6 +272,26 @@ export class UiChannel {
     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), a page busy running a long script, 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`)
   }
 
+  /**
+   * A call for one page (the page a run was asked from, followed into its tab): it goes to that page alone and never fails over to another one. A page that is between two
+   * documents (it reloads, or moves to another path) is waited for, up to the attach wait.
+   */
+  private async callPage(request: UiRequest, page: string, options: { signal?: AbortSignal; timeoutMs?: number }, readOnly: boolean): Promise<UiResult> {
+    let target = this.connections.get(this.whereIs(page).windowId)
+    if (target === undefined && this.attachWaitMs > 0) {
+      const back = await this.expectPageBack(page, this.attachWaitMs)
+      if (back !== undefined) target = this.connections.get(back)
+    }
+    if (target === undefined) throw new UiControlError('no-window', 'the page this run is for is not open any more')
+    if (options.signal?.aborted === true) throw new UiControlError('aborted', 'the call was cancelled')
+    try {
+      return await this.callOne(target, request, options, readOnly)
+    } catch (cause) {
+      if (cause instanceof Silent) throw new UiControlError('timeout', 'the page this run is for did not answer: is its tab in the background or still loading? Look again')
+      throw cause
+    }
+  }
+
   private callOne(target: Connection, request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number }, failOver: boolean): Promise<UiResult> {
     const signal = options.signal
     const id = this.nextId
@@ -260,12 +334,15 @@ export class UiChannel {
 
   /**
    * A promise for the window id of the next page that connects and was not connected when this was asked (the page that came back after a reload or a move).
+   * @param signal - stop waiting; the promise then answers `undefined`.
    * @returns that id, or `undefined` when no new page connected within `timeoutMs`.
    */
-  expectNewPage(timeoutMs: number): Promise<string | undefined> {
+  expectNewPage(timeoutMs: number, signal?: AbortSignal): Promise<string | undefined> {
     const known = new Set(this.connections.keys())
     return new Promise((resolve) => {
-      const done = (value: string | undefined): void => { clearTimeout(timer); this.attachWaiters.delete(waiter); resolve(value) }
+      const done = (value: string | undefined): void => { clearTimeout(timer); this.attachWaiters.delete(waiter); signal?.removeEventListener('abort', stop); resolve(value) }
+      const stop = (): void => { done(undefined) }
+      signal?.addEventListener('abort', stop, { once: true })
       const waiter = (windowId: string): void => { if (!known.has(windowId)) done(windowId) }
       const timer = setTimeout(() => { done(undefined) }, timeoutMs)
       this.attachWaiters.add(waiter)

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

@@ -6,10 +6,10 @@
 
 import { UiControlError } from '../page/protocol.ts'
 import { DoorError, type Door, type ToolsPort } from './door.ts'
-import { chatToolName, VERB_SPECS, VERBS } from './verbs.ts'
+import { chatToolName, VERB_SPECS, VERBS, type Verb } from './verbs.ts'
 
-/** Register every verb. @returns the function that removes them all; it also aborts the calls still running. */
-export function registerChatTools(tools: ToolsPort, door: Door): () => void {
+/** Register the verbs (default: every one). @returns the function that removes them all; it also aborts the calls still running. */
+export function registerChatTools(tools: ToolsPort, door: Door, verbs: readonly Verb[] = VERBS): () => void {
   const running = new AbortController()
   const removers: Array<() => void> = []
   const removeAll = (): void => {
@@ -17,14 +17,16 @@ export function registerChatTools(tools: ToolsPort, door: Door): () => void {
     for (const remove of removers.splice(0).reverse()) remove()
   }
   try {
-    for (const verb of VERBS) {
+    for (const verb of verbs) {
       removers.push(tools.register(chatToolName(verb), {
         description: VERB_SPECS[verb].description,
         // The model is told which fields the verb takes (an `act` needs its `op`), the same schema MCP lists.
         parameters: VERB_SPECS[verb].arguments as unknown as Readonly<Record<string, unknown>>,
-        run: async (input: unknown) => {
+        // The run's own signal and page come with the call: its look and act go to the page the run was asked from.
+        run: async (input: unknown, options?: { signal?: AbortSignal; page?: string }) => {
+          const signal = options?.signal === undefined ? running.signal : AbortSignal.any([running.signal, options.signal])
           try {
-            return (await door.run(verb, input ?? {}, running.signal)).text
+            return (await door.run(verb, input ?? {}, signal, options?.page === undefined ? {} : { page: options.page })).text
           } catch (cause) {
             if (cause instanceof DoorError || cause instanceof UiControlError) throw new Error(`${cause.code}: ${cause.message}`, { cause })
             throw cause