acrylblends 1.0.3 → 1.0.5

package/lib/utils/stream.js

@@ -1,88 +1,2 @@
-//#region ../../plugins/acryl-router/src/core/utils/stream.ts
-/**
-* @module
-* Stream utility.
-*/
-var StreamingApi = class {
-	writer;
-	encoder;
-	writable;
-	abortSubscribers = [];
-	responseReadable;
-	/**
-	* Whether the stream has been aborted.
-	*/
-	aborted = false;
-	/**
-	* Whether the stream has been closed normally.
-	*/
-	closed = false;
-	constructor(writable, _readable) {
-		this.writable = writable;
-		this.writer = writable.getWriter();
-		this.encoder = new TextEncoder();
-		const reader = _readable.getReader();
-		this.abortSubscribers.push(async () => {
-			await reader.cancel();
-		});
-		this.responseReadable = new ReadableStream({
-			async pull(controller) {
-				const { done, value } = await reader.read();
-				done ? controller.close() : controller.enqueue(value);
-			},
-			cancel: () => {
-				if (!this.closed) this.abort();
-			}
-		});
-	}
-	async write(input) {
-		try {
-			if (typeof input === "string") input = this.encoder.encode(input);
-			await this.writer.write(input);
-		} catch {}
-		return this;
-	}
-	async writeln(input) {
-		await this.write(input + "\n");
-		return this;
-	}
-	sleep(ms) {
-		return new Promise((res) => setTimeout(res, ms));
-	}
-	async close() {
-		this.closed = true;
-		try {
-			await this.writer.close();
-		} catch {}
-	}
-	async pipe(body) {
-		this.writer.releaseLock();
-		try {
-			await body.pipeTo(this.writable, {
-				preventClose: true,
-				preventAbort: true
-			});
-		} finally {
-			this.writer = this.writable.getWriter();
-		}
-	}
-	onAbort(listener) {
-		this.abortSubscribers.push(listener);
-	}
-	/**
-	* Abort the stream.
-	* You can call this method when stream is aborted by external event.
-	*/
-	abort() {
-		if (!this.aborted) {
-			this.aborted = true;
-			this.abortSubscribers.forEach((subscriber) => {
-				try {
-					Promise.resolve(subscriber()).catch(() => {});
-				} catch {}
-			});
-		}
-	}
-};
-//#endregion
+import { t as StreamingApi } from "../stream-CzM_SHkq.js";
 export { StreamingApi };

package/lib/utils/url.js

@@ -1,197 +1,2 @@
-//#region ../../plugins/acryl-router/src/core/utils/url.ts
-const splitPath = (path) => {
-	const paths = path.split("/");
-	if (paths[0] === "") paths.shift();
-	return paths;
-};
-const splitRoutingPath = (routePath) => {
-	const { groups, path } = extractGroupsFromPath(routePath);
-	const paths = splitPath(path);
-	return replaceGroupMarks(paths, groups);
-};
-const extractGroupsFromPath = (path) => {
-	const groups = [];
-	path = path.replace(/\{[^}]+\}/g, (match, index) => {
-		const mark = `@${index}`;
-		groups.push([mark, match]);
-		return mark;
-	});
-	return {
-		groups,
-		path
-	};
-};
-const replaceGroupMarks = (paths, groups) => {
-	for (let i = groups.length - 1; i >= 0; i--) {
-		const [mark] = groups[i];
-		for (let j = paths.length - 1; j >= 0; j--) if (paths[j].includes(mark)) {
-			paths[j] = paths[j].replace(mark, groups[i][1]);
-			break;
-		}
-	}
-	return paths;
-};
-const patternCache = {};
-const getPattern = (label, next) => {
-	if (label === "*") return "*";
-	const match = label.match(/^\:([^\{\}]+)(?:\{(.+)\})?$/);
-	if (match) {
-		const cacheKey = `${label}#${next}`;
-		if (!patternCache[cacheKey]) if (match[2]) patternCache[cacheKey] = next && next[0] !== ":" && next[0] !== "*" ? [
-			cacheKey,
-			match[1],
-			new RegExp(`^${match[2]}(?=/${next})`)
-		] : [
-			label,
-			match[1],
-			new RegExp(`^${match[2]}$`)
-		];
-		else patternCache[cacheKey] = [
-			label,
-			match[1],
-			true
-		];
-		return patternCache[cacheKey];
-	}
-	return null;
-};
-const tryDecode = (str, decoder) => {
-	try {
-		return decoder(str);
-	} catch {
-		return str.replace(/(?:%[0-9A-Fa-f]{2})+/g, (match) => {
-			try {
-				return decoder(match);
-			} catch {
-				return match;
-			}
-		});
-	}
-};
-/**
-* Try to apply decodeURI() to given string.
-* If it fails, skip invalid percent encoding or invalid UTF-8 sequences, and apply decodeURI() to the rest as much as possible.
-* @param str The string to decode.
-* @returns The decoded string that sometimes contains undecodable percent encoding.
-* @example
-* tryDecodeURI('Hello%20World') // 'Hello World'
-* tryDecodeURI('Hello%20World/%A4%A2') // 'Hello World/%A4%A2'
-*/
-const tryDecodeURI = (str) => tryDecode(str, decodeURI);
-const getPath = (request) => {
-	const url = request.url;
-	const start = url.indexOf("/", url.indexOf(":") + 4);
-	let i = start;
-	for (; i < url.length; i++) {
-		const charCode = url.charCodeAt(i);
-		if (charCode === 37) {
-			const queryIndex = url.indexOf("?", i);
-			const hashIndex = url.indexOf("#", i);
-			const end = queryIndex === -1 ? hashIndex === -1 ? void 0 : hashIndex : hashIndex === -1 ? queryIndex : Math.min(queryIndex, hashIndex);
-			const path = url.slice(start, end);
-			return tryDecodeURI(path.includes("%25") ? path.replace(/%25/g, "%2525") : path);
-		} else if (charCode === 63 || charCode === 35) break;
-	}
-	return url.slice(start, i);
-};
-/**
-* @deprecated
-* Use the `URL` API instead.
-*/
-const getQueryStrings = (url) => {
-	const queryIndex = url.indexOf("?", 8);
-	if (queryIndex === -1) return "";
-	const hashIndex = url.indexOf("#", 8);
-	return hashIndex === -1 ? url.slice(queryIndex) : queryIndex < hashIndex ? url.slice(queryIndex, hashIndex) : "";
-};
-const getPathNoStrict = (request) => {
-	const result = getPath(request);
-	return result.length > 1 && result.at(-1) === "/" ? result.slice(0, -1) : result;
-};
-/**
-* Merge paths.
-* @param {string[]} ...paths - The paths to merge.
-* @returns {string} The merged path.
-* @example
-* mergePath('/api', '/users') // '/api/users'
-* mergePath('/api/', '/users') // '/api/users'
-* mergePath('/api', '/') // '/api'
-* mergePath('/api/', '/') // '/api/'
-*/
-const mergePath = (base, sub, ...rest) => {
-	if (rest.length) sub = mergePath(sub, ...rest);
-	return `${base?.[0] === "/" ? "" : "/"}${base}${sub === "/" ? "" : `${base?.at(-1) === "/" ? "" : "/"}${sub?.[0] === "/" ? sub.slice(1) : sub}`}`;
-};
-const checkOptionalParameter = (path) => {
-	if (path.charCodeAt(path.length - 1) !== 63 || !path.includes(":")) return null;
-	const segments = path.split("/");
-	const results = [];
-	let basePath = "";
-	segments.forEach((segment) => {
-		if (segment !== "" && !/\:/.test(segment)) basePath += "/" + segment;
-		else if (/\:/.test(segment)) if (segment.charCodeAt(segment.length - 1) === 63) {
-			if (results.length === 0 && basePath === "") results.push("/");
-			else results.push(basePath);
-			const optionalSegment = segment.slice(0, -1);
-			basePath += "/" + optionalSegment;
-			results.push(basePath);
-		} else basePath += "/" + segment;
-	});
-	return results.filter((v, i, a) => a.indexOf(v) === i);
-};
-const tryDecodeURIComponent = (str) => str.indexOf("%") !== -1 ? tryDecode(str, decodeURIComponent_) : str;
-const _decodeURI = (value) => {
-	if (value.indexOf("+") !== -1) value = value.replace(/\+/g, " ");
-	return tryDecodeURIComponent(value);
-};
-const _getQueryParam = (url, key, multiple) => {
-	const hashIndex = url.indexOf("#", 8);
-	if (hashIndex !== -1) url = url.slice(0, hashIndex);
-	let encoded;
-	if (!multiple && key && key.indexOf("%") === -1 && key.indexOf("+") === -1) {
-		let keyIndex = url.indexOf("?", 8);
-		if (keyIndex === -1) return;
-		if (!url.startsWith(key, keyIndex + 1)) keyIndex = url.indexOf(`&${key}`, keyIndex + 1);
-		while (keyIndex !== -1) {
-			const trailingKeyCode = url.charCodeAt(keyIndex + key.length + 1);
-			if (trailingKeyCode === 61) {
-				const valueIndex = keyIndex + key.length + 2;
-				const endIndex = url.indexOf("&", valueIndex);
-				return _decodeURI(url.slice(valueIndex, endIndex === -1 ? void 0 : endIndex));
-			} else if (trailingKeyCode == 38 || isNaN(trailingKeyCode)) return "";
-			keyIndex = url.indexOf(`&${key}`, keyIndex + 1);
-		}
-		encoded = /[%+]/.test(url);
-		if (!encoded) return;
-	}
-	const results = Object.create(null);
-	encoded ??= /[%+]/.test(url);
-	let keyIndex = url.indexOf("?", 8);
-	while (keyIndex !== -1) {
-		const nextKeyIndex = url.indexOf("&", keyIndex + 1);
-		let valueIndex = url.indexOf("=", keyIndex);
-		if (valueIndex > nextKeyIndex && nextKeyIndex !== -1) valueIndex = -1;
-		let name = url.slice(keyIndex + 1, valueIndex === -1 ? nextKeyIndex === -1 ? void 0 : nextKeyIndex : valueIndex);
-		if (encoded) name = _decodeURI(name);
-		keyIndex = nextKeyIndex;
-		if (name === "") continue;
-		let value;
-		if (valueIndex === -1) value = "";
-		else {
-			value = url.slice(valueIndex + 1, nextKeyIndex === -1 ? void 0 : nextKeyIndex);
-			if (encoded) value = _decodeURI(value);
-		}
-		if (multiple) {
-			if (!(results[name] && Array.isArray(results[name]))) results[name] = [];
-			results[name].push(value);
-		} else results[name] ??= value;
-	}
-	return key ? results[key] : results;
-};
-const getQueryParam = _getQueryParam;
-const getQueryParams = (url, key) => {
-	return _getQueryParam(url, key, true);
-};
-const decodeURIComponent_ = decodeURIComponent;
-//#endregion
+import { a as getPattern, c as getQueryStrings, d as splitRoutingPath, f as tryDecode, i as getPathNoStrict, l as mergePath, m as tryDecodeURIComponent, n as decodeURIComponent_, o as getQueryParam, p as tryDecodeURI, r as getPath, s as getQueryParams, t as checkOptionalParameter, u as splitPath } from "../url-BPh4d6j-.js";
 export { checkOptionalParameter, decodeURIComponent_, getPath, getPathNoStrict, getPattern, getQueryParam, getQueryParams, getQueryStrings, mergePath, splitPath, splitRoutingPath, tryDecode, tryDecodeURI, tryDecodeURIComponent };

package/lib/{validator-D84mq-dO.js → validator-Btiyt5VJ.js}

@@ -1,6 +1,6 @@
-import { HTTPException } from "./http-exception.js";
-import { bufferToFormData } from "./utils/buffer.js";
-import { getCookie } from "./cookie.js";
+import { t as HTTPException } from "./http-exception-MjWkT89V.js";
+import { t as bufferToFormData } from "./buffer-CkEOJCcY.js";
+import { i as getCookie } from "./cookie-BHIduy2T.js";
 //#region ../../plugins/acryl-router/src/core/validator/validator.ts
 const jsonRegex = /^application\/([a-z-\.]+\+)?json(;\s*[a-zA-Z0-9\-]+\=([^;]+))*$/i;
 const multipartRegex = /^multipart\/form-data(;\s?boundary=[a-zA-Z0-9'"()+_,\-./:=?]+)?$/i;

package/lib/validator.js

@@ -1,2 +1,2 @@
-import { t as validator } from "./validator-D84mq-dO.js";
+import { t as validator } from "./validator-Btiyt5VJ.js";
 export { validator };

package/lib/websocket-DsyBIKVA.js

@@ -0,0 +1,56 @@
+//#region ../../plugins/acryl-router/src/core/helper/websocket/index.ts
+/**
+* A context for controlling WebSockets
+*/
+var WSContext = class {
+	#init;
+	constructor(init) {
+		this.#init = init;
+		this.raw = init.raw;
+		this.url = init.url ? new URL(init.url) : null;
+		this.protocol = init.protocol ?? null;
+	}
+	send(source, options) {
+		this.#init.send(source, options ?? {});
+	}
+	raw;
+	binaryType = "arraybuffer";
+	get readyState() {
+		return this.#init.readyState;
+	}
+	get bufferedAmount() {
+		return this.#init.bufferedAmount ?? 0;
+	}
+	url;
+	protocol;
+	close(code, reason) {
+		this.#init.close(code, reason);
+	}
+};
+const createWSMessageEvent = (source) => {
+	return new MessageEvent("message", { data: source });
+};
+/**
+* Create a WebSocket adapter/helper
+*/
+const defineWebSocketHelper = (handler) => {
+	return ((...args) => {
+		if (typeof args[0] === "function") {
+			const [createEvents, options] = args;
+			return async function upgradeWebSocket(c, next) {
+				const result = await handler(c, await createEvents(c), options);
+				if (result) return result;
+				await next();
+			};
+		} else {
+			const [c, events, options] = args;
+			return (async () => {
+				const upgraded = await handler(c, events, options);
+				if (!upgraded) throw new Error("Failed to upgrade WebSocket");
+				return upgraded;
+			})();
+		}
+	});
+};
+//#endregion
+export { createWSMessageEvent as n, defineWebSocketHelper as r, WSContext as t };

package/lib/ws.js

@@ -1,56 +1,2 @@
-//#region ../../plugins/acryl-router/src/core/helper/websocket/index.ts
-/**
-* A context for controlling WebSockets
-*/
-var WSContext = class {
-	#init;
-	constructor(init) {
-		this.#init = init;
-		this.raw = init.raw;
-		this.url = init.url ? new URL(init.url) : null;
-		this.protocol = init.protocol ?? null;
-	}
-	send(source, options) {
-		this.#init.send(source, options ?? {});
-	}
-	raw;
-	binaryType = "arraybuffer";
-	get readyState() {
-		return this.#init.readyState;
-	}
-	get bufferedAmount() {
-		return this.#init.bufferedAmount ?? 0;
-	}
-	url;
-	protocol;
-	close(code, reason) {
-		this.#init.close(code, reason);
-	}
-};
-const createWSMessageEvent = (source) => {
-	return new MessageEvent("message", { data: source });
-};
-/**
-* Create a WebSocket adapter/helper
-*/
-const defineWebSocketHelper = (handler) => {
-	return ((...args) => {
-		if (typeof args[0] === "function") {
-			const [createEvents, options] = args;
-			return async function upgradeWebSocket(c, next) {
-				const result = await handler(c, await createEvents(c), options);
-				if (result) return result;
-				await next();
-			};
-		} else {
-			const [c, events, options] = args;
-			return (async () => {
-				const upgraded = await handler(c, events, options);
-				if (!upgraded) throw new Error("Failed to upgrade WebSocket");
-				return upgraded;
-			})();
-		}
-	});
-};
-//#endregion
+import { n as createWSMessageEvent, r as defineWebSocketHelper, t as WSContext } from "./websocket-DsyBIKVA.js";
 export { WSContext, createWSMessageEvent, defineWebSocketHelper };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "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/src/cli/acryl.ts

@@ -15,8 +15,8 @@ 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'])
-const VALUED = new Set(['--dir', '--ref', '--text', '--option', '--key', '--direction', '--amount', '--cursor', '--max-nodes', '--role', '--name', '--timeout-ms', '--tool', '--args'])
+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', '--tool', '--args', '--path'])
 const FLAGS = new Set(['--json', '--submit', '--no-clear', '--gone', '--help'])
 
 export class UsageError extends Error {}
@@ -36,6 +36,8 @@ const USAGE = `usage: acryl <verb> [options] [--json] [--dir <app folder>]
   act select --ref <r> --option <o>
   act press --key <key> [--ref <r>]
   act scroll --direction up|down|left|right [--ref <r>] [--amount <px>]
+  act reload
+  act navigate --path <path of the app, e.g. /demo>
   act wait (--text <t> | --role <role> [--name <n>]) [--gone] [--timeout-ms <ms>]
   plugin list | plugin add <folder> | plugin remove <name> | plugin reload
   tool list | tool call --tool <name> [--args '<json>']
@@ -90,7 +92,7 @@ export function parseInvocation(argv: readonly string[]): Invocation {
       return make('act', {
         op: second,
         ...pick('--ref', 'ref'), ...pick('--text', 'text'), ...pick('--option', 'option'), ...pick('--key', 'key'),
-        ...pick('--direction', 'direction'), ...pick('--role', 'role'), ...pick('--name', 'name'),
+        ...pick('--direction', 'direction'), ...pick('--role', 'role'), ...pick('--name', 'name'), ...pick('--path', 'path'),
         ...(amount === undefined ? {} : { amount }),
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
         ...(set.has('--submit') ? { submit: true } : {}),

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

@@ -45,6 +45,8 @@ export class UiChannel {
   private nextId = 1
   private clock = 0
   private closed = false
+  /** Callers waiting for a page to (re)connect: each is told once, by the next stream that attaches. */
+  private readonly attachWaiters = new Set<() => void>()
 
   /**
    * Register a page's stream. A stream already open for the same window is closed first, and its calls settle as `disconnected`.
@@ -55,6 +57,7 @@ export class UiChannel {
     if (previous !== undefined) this.drop(previous, true)
     const connection: Connection = { stream, windowId, focused, lastActive: ++this.clock }
     this.connections.set(windowId, connection)
+    for (const waiter of [...this.attachWaiters]) waiter()
     return () => { if (this.connections.get(windowId) === connection) this.drop(connection, false) }
   }
 
@@ -109,6 +112,39 @@ export class UiChannel {
     })
   }
 
+  /**
+   * 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.
+   * @returns whether a page connected within `timeoutMs`.
+   */
+  expectAttach(timeoutMs: number, count = 1): Promise<boolean> {
+    return new Promise((resolve) => {
+      let left = count
+      const done = (value: boolean): void => { clearTimeout(timer); this.attachWaiters.delete(waiter); resolve(value) }
+      const waiter = (): void => { left -= 1; if (left <= 0) done(true) }
+      const timer = setTimeout(() => { done(false) }, timeoutMs)
+      this.attachWaiters.add(waiter)
+    })
+  }
+
+  /**
+   * Ask every connected page to reload (the app just changed under them) and wait, up to `timeoutMs`, for them to come back. Best effort: a page that does not come back
+   * (it was closed, or it moved to a page without the door) is not an error here.
+   * @returns how many pages were asked.
+   */
+  async reloadAll(timeoutMs = 8000): Promise<number> {
+    const targets = this.byRecency()
+    if (this.closed || targets.length === 0) return 0
+    const back = this.expectAttach(timeoutMs, targets.length)
+    for (const target of targets) {
+      const id = this.nextId
+      this.nextId += 1
+      // No call is waiting for the answer: the page answers by POST and the Host ignores an id it does not know.
+      try { target.stream.send(JSON.stringify({ t: 'call', id, request: { op: 'reload' } } satisfies ChannelToPage)) } catch { /* that page is gone */ }
+    }
+    await back
+    return targets.length
+  }
+
   /** Close every page's stream and settle every pending call as `unloaded`. */
   close(): void {
     this.closed = true

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

@@ -20,6 +20,8 @@ export function registerChatTools(tools: ToolsPort, door: Door): () => void {
     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) => {
           try {
             return (await door.run(verb, input ?? {}, running.signal)).text

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

@@ -35,7 +35,7 @@ export interface ExtensionsPort {
 /** The slice of acrylblends' `tools` registry (the `agent` plugin's) the tool verbs use, and where the built-in chat finds the verbs. */
 export interface ToolsPort {
   /** @returns the function that removes the tool. @throws when the name is taken. */
-  register(name: string, tool: { readonly description: string; run(input: unknown): unknown }): () => void
+  register(name: string, tool: { readonly description: string; readonly parameters?: Readonly<Record<string, unknown>>; run(input: unknown): unknown }): () => void
   list(): ReadonlyArray<{ readonly name: string; readonly description: string }>
   call(name: string, input: unknown): Promise<unknown>
 }
@@ -50,6 +50,10 @@ export interface DoorDeps {
   readonly tools: () => ToolsPort | undefined
   /** The app tools the door offers; anything else is refused before it reaches the registry. */
   readonly expose: readonly string[]
+  /** Reload the open pages after a plugin was added, removed or reloaded, so the page an agent looks at next is the new one. Default: true. */
+  readonly reloadOnChange?: boolean
+  /** How long a reload or a move may take before the new page has connected again (tests shorten it). Default 15 s. */
+  readonly pageBackMs?: number
 }
 
 /** What one verb answered: the value for `--json` and programs, the text for an agent reading a terminal. */
@@ -61,6 +65,9 @@ export interface VerbAnswer {
 /** The files an agent should read first, when the app has them. */
 const SELF_KNOWLEDGE = ['AGENTS.md', 'CLAUDE.md', '.agents/skills', '.claude/skills', 'docs', 'plugins']
 
+/** How long a reload or a move may take before the new page has connected to the door again. */
+const PAGE_BACK_MS = 15_000
+
 export class Door {
   private readonly deps: DoorDeps
 
@@ -81,7 +88,7 @@ export class Door {
         const result = await this.act(input, signal)
         return { value: result, text: `done${result.target === undefined ? '' : `: ${result.target.role} "${result.target.name}"`}${result.detail === undefined ? '' : ` (${result.detail})`}; look again before the next act` }
       }
-      case 'plugin-list': return this.plugin(extensions => extensions.list())
+      case 'plugin-list': return this.plugin(extensions => extensions.list(), false)
       case 'plugin-add': return this.plugin(extensions => extensions.install(this.insideApp(input.folder)))
       case 'plugin-remove': {
         const name = input.name
@@ -127,9 +134,38 @@ export class Door {
     return this.callPage('look', request, signal) as Promise<UiSnapshot>
   }
 
-  act(input: Record<string, unknown>, signal: AbortSignal): Promise<UiActionResult> {
+  async act(input: Record<string, unknown>, signal: AbortSignal): Promise<UiActionResult> {
     if (input.op === 'snapshot') throw new DoorError('invalid', 'use look to see the page')
-    return this.callPage(`act ${String(input.op)}`, this.parse(input), signal) as Promise<UiActionResult>
+    const request = this.parse(input)
+    if (request.op !== 'reload' && request.op !== 'navigate') return await this.callPage(`act ${String(input.op)}`, request, signal) as UiActionResult
+    // The page is replaced: wait for the new one to connect, so the next look sees it. The page may drop before it has answered; that is the reload working.
+    const back = this.deps.channel.expectAttach(this.deps.pageBackMs ?? PAGE_BACK_MS)
+    let answer: UiActionResult
+    try {
+      answer = await this.callPage(`act ${request.op}`, request, signal) as UiActionResult
+    } catch (cause) {
+      if (!(cause instanceof UiControlError && cause.code === 'disconnected')) { void back; throw cause }
+      answer = { ok: true, detail: request.op === 'reload' ? 'reloading' : `going to ${request.path}` }
+    }
+    if (!await back) throw new UiControlError('timeout', request.op === 'reload' ? 'the page did not come back after the reload' : `the page did not come back after going to ${request.path}: is there a page at that path, and does it load the door's script?`)
+    const landed = request.op === 'navigate' ? await this.statusAt(request.path) : undefined
+    return { ...answer, detail: `${answer.detail ?? 'done'}${landed === undefined ? '' : `; ${landed}`}; the page is back: look again` }
+  }
+
+  /**
+   * What the app answers at a path the page was sent to, so an agent that mistyped one is told ("404 at /nope") and not left to find out from a page it did not expect.
+   * A second GET of the same path (a page is read-only); nothing when the app has no address or does not answer in time.
+   */
+  private async statusAt(path: string): Promise<string | undefined> {
+    const base = this.deps.app.url
+    if (base === undefined) return undefined
+    try {
+      const response = await fetch(new URL(path, base), { headers: { accept: 'text/html' }, signal: AbortSignal.timeout(3000) })
+      await response.body?.cancel()
+      return response.ok ? `${response.status} at ${path}` : `${response.status} at ${path}: the app serves no page there, look at what is shown and navigate to a path it does`
+    } catch {
+      return undefined
+    }
   }
 
   private parse(input: Record<string, unknown>): UiRequest {
@@ -156,10 +192,13 @@ export class Door {
     }
   }
 
-  private async plugin(run: (extensions: ExtensionsPort) => unknown): Promise<VerbAnswer> {
+  private async plugin(run: (extensions: ExtensionsPort) => unknown, mutates = true): Promise<VerbAnswer> {
     const extensions = this.deps.extensions()
     if (extensions === undefined) throw new DoorError('unavailable', 'this app has no extensions plugin, so plugins cannot be installed while it runs')
     const value = await run(extensions)
+    // The app changed under the open pages: reload them (not when the plugin was already as it should be), and answer once they are back.
+    const unchanged = typeof value === 'object' && value !== null && (value as { action?: unknown }).action === 'unchanged'
+    if (mutates && !unchanged && this.deps.reloadOnChange !== false) await this.deps.channel.reloadAll()
     return { value, text: JSON.stringify(value, null, 2) }
   }
 

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

@@ -7,6 +7,7 @@
  * app is running in the folder (exit 3). It carries no secret; the client reads `door.json` at each call.
  */
 
+import { spawnSync } from 'node:child_process'
 import { chmodSync, mkdirSync, renameSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { ensureStateDir } from './door-file.ts'
@@ -25,6 +26,28 @@ export interface ShimTarget {
   readonly electron: boolean
 }
 
+/** The oldest Node the client runs on (the framework's own floor). */
+const MIN_NODE = [22, 19]
+
+/**
+ * A real Node for the command, when the app runs inside Electron: Electron can run the client as Node, but on macOS every such call prints a code-signing complaint on stderr,
+ * which lands in an agent's transcript. A `node` on the PATH that is new enough is used instead; without one, Electron runs the client. `find` is replaceable for tests.
+ */
+export function realNode(find: () => { path: string; version: string } | undefined = findNodeOnPath): string | undefined {
+  const found = find()
+  if (found === undefined) return undefined
+  const [major = 0, minor = 0] = found.version.replace(/^v/u, '').split('.').map(Number)
+  return major > MIN_NODE[0]! || (major === MIN_NODE[0] && minor >= MIN_NODE[1]!) ? found.path : undefined
+}
+
+function findNodeOnPath(): { path: string; version: string } | undefined {
+  const located = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['node'], { encoding: 'utf8', env: { ...process.env, ELECTRON_RUN_AS_NODE: undefined } })
+  const path = located.status === 0 ? located.stdout.split(/\r?\n/u).find((line) => line.trim() !== '')?.trim() : undefined
+  if (path === undefined) return undefined
+  const asked = spawnSync(path, ['--version'], { encoding: 'utf8' })
+  return asked.status === 0 ? { path, version: asked.stdout.trim() } : undefined
+}
+
 /** A word for `sh`: single-quoted, with each `'` closed, escaped and reopened. */
 function shWord(value: string): string {
   return `'${value.replaceAll('\'', '\'\\\'\'')}'`

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

@@ -47,12 +47,13 @@ export const VERB_SPECS: Readonly<Record<Verb, VerbSpec>> = {
     },
   },
   'act': {
-    usage: 'act click|type|select|press|scroll|wait ...: do one thing on the page (refs from the latest look)',
-    description: 'Do one thing on the page: click, type, select, press a key, scroll, or wait for text or a control. Look again before the next act.',
+    usage: 'act click|type|select|press|scroll|wait|reload|navigate ...: do one thing on the page (refs from the latest look)',
+    description: 'Do one thing on the page: click, type, select, press a key, scroll, wait for text or a control, reload the page, or navigate to another path of the app. Look again before the next act.',
     arguments: {
       type: 'object',
       properties: {
-        op: { type: 'string', enum: ['click', 'type', 'select', 'press', 'scroll', 'wait'] },
+        op: { type: 'string', enum: ['click', 'type', 'select', 'press', 'scroll', 'wait', 'reload', 'navigate'] },
+        path: { type: 'string', description: 'navigate: a path of this app, e.g. /demo (the page must load the door script to be controlled afterwards)' },
         ref,
         text: { type: 'string', description: 'type: what to type; wait: the text to wait for' },
         submit: { type: 'boolean', description: 'type: press Enter after' },