acrylblends 0.8.1 → 0.9.0

package/lib/door/page.js

@@ -0,0 +1,1030 @@
+import { MAX_SNAPSHOT_NODES, MAX_WAIT_MS, MUTATING_OPS, UiControlError, parseChannelToPage } from "./protocol.js";
+//#region ../../plugins/acryl-door/src/page/channel.ts
+/**
+* The page's end of the door's channel.
+*
+* It keeps an event stream open to the Host (`GET <base>/channel`), runs each call on the driver, and posts the answer back. The Host
+* writes a `ping` every few seconds; a stream silent for {@link SILENCE_MS} is dropped and opened again, so a page whose connection died
+* without an error (a sleeping laptop, a proxy) resumes on its own. A page that reconnects keeps its window id, and the Host settles a
+* call in flight on the old stream as `disconnected`.
+*/
+/** The Host's heartbeat is 15 s; three missed beats and the stream counts as dead. */
+const SILENCE_MS = 45e3;
+const CLOSED = 2;
+const BACKOFF_START_MS = 500;
+const BACKOFF_MAX_MS = 1e4;
+var PageChannel = class {
+	source;
+	reconnectTimer;
+	watchdog;
+	backoff = BACKOFF_START_MS;
+	lastHeard = 0;
+	disposed = false;
+	now;
+	driver;
+	options;
+	constructor(driver, options) {
+		this.driver = driver;
+		this.options = options;
+		this.now = options.now ?? (() => Date.now());
+	}
+	connect() {
+		if (this.disposed || this.source !== void 0) return;
+		const create = this.options.createSource ?? ((url) => new EventSource(url));
+		const query = `window=${encodeURIComponent(this.options.windowId)}&focused=${this.options.focused() ? "1" : "0"}`;
+		const source = create(`${this.options.base}/channel?${query}`);
+		this.source = source;
+		this.lastHeard = this.now();
+		const heard = () => {
+			this.lastHeard = this.now();
+			this.backoff = BACKOFF_START_MS;
+		};
+		source.addEventListener("ready", heard);
+		source.addEventListener("ping", heard);
+		source.addEventListener("call", (event) => {
+			heard();
+			if (typeof event.data === "string") this.answer(event.data);
+		});
+		source.onerror = () => {
+			if (source.readyState === CLOSED) this.restart(source);
+		};
+		const silence = this.options.silenceMs ?? 45e3;
+		this.watchdog = setInterval(() => {
+			if (this.now() - this.lastHeard > silence) this.restart(source);
+		}, Math.max(50, Math.floor(silence / 3)));
+	}
+	/** Tell the Host whether this window is the one in front. */
+	reportFocus(focused) {
+		this.send({
+			t: "focus",
+			focused
+		});
+	}
+	dispose() {
+		this.disposed = true;
+		if (this.reconnectTimer !== void 0) clearTimeout(this.reconnectTimer);
+		this.stop();
+	}
+	/** Drop the stream and open a new one after the backoff. */
+	restart(source) {
+		if (this.source !== source) return;
+		this.stop();
+		if (this.disposed) return;
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = void 0;
+			this.connect();
+		}, this.backoff);
+		this.backoff = Math.min(this.backoff * 2, BACKOFF_MAX_MS);
+	}
+	stop() {
+		if (this.watchdog !== void 0) clearInterval(this.watchdog);
+		this.watchdog = void 0;
+		const source = this.source;
+		this.source = void 0;
+		if (source !== void 0) {
+			source.onerror = null;
+			source.close();
+		}
+	}
+	answer(text) {
+		let call;
+		try {
+			call = parseChannelToPage(text);
+		} catch {
+			return;
+		}
+		this.driver.handle(call.request).then((value) => {
+			this.send({
+				t: "result",
+				id: call.id,
+				value
+			});
+		}, (cause) => {
+			const failure = cause instanceof UiControlError ? cause : new UiControlError("not-actionable", cause instanceof Error ? cause.message : "the action failed");
+			this.send({
+				t: "error",
+				id: call.id,
+				code: failure.code,
+				message: failure.message
+			});
+		});
+	}
+	send(message) {
+		(this.options.post ?? ((url, body) => fetch(url, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body
+		})))(`${this.options.base}/channel/answer`, JSON.stringify({
+			window: this.options.windowId,
+			message
+		})).catch(() => {});
+	}
+};
+//#endregion
+//#region ../../plugins/acryl-door/src/page/driver/sensitivity.ts
+/**
+* What the agent may never see or type into, decided by rule and not by trusting the agent:
+* secrets and payment fields (sensitive), and controls that govern the agent itself (protected).
+*/
+/** Field names and labels that mean a secret or a payment detail. */
+const SENSITIVE_WORDS = /pass(?:word|code|phrase)|secret|token|api[-_ ]?key|credential|private[-_ ]?key|\bpin\b|card|cvv|cvc|iban|routing|account[-_ ]?number|ssn|social[-_ ]?security|one[-_ ]?time|otp/i;
+/** `autocomplete` values that browsers treat as credentials or payment data. */
+const SENSITIVE_AUTOCOMPLETE = /^(?:cc-|current-password|new-password|one-time-code)/;
+const label = (el, attr) => el.getAttribute(attr) ?? "";
+/** True for a form field (or anything marked) that holds a secret or payment detail. */
+function isSensitive(el) {
+	if (el.closest("[data-acryl-sensitive]") !== null) return true;
+	if (!(el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement)) return false;
+	if (el instanceof HTMLInputElement && el.type === "password") return true;
+	if (label(el, "autocomplete").trim().toLowerCase().split(/\s+/).some((token) => SENSITIVE_AUTOCOMPLETE.test(token))) return true;
+	return SENSITIVE_WORDS.test([
+		el.name,
+		el.id,
+		label(el, "placeholder"),
+		label(el, "aria-label")
+	].join(" "));
+}
+/** Areas whose controls the agent may look at but never operate. */
+const PROTECTED_REGION = /approval|permission|policy|agent control|ui control|acryl-agent-control|acryl-door|kill switch/i;
+/** The text an ancestor uses to name itself, for region rules. */
+function ancestorName(el) {
+	const own = label(el, "aria-label") || label(el, "data-region") || "";
+	if (own !== "") return own;
+	const labelled = label(el, "aria-labelledby");
+	if (labelled !== "") return labelled.split(/\s+/).map((id) => el.ownerDocument.getElementById(id)?.textContent ?? "").join(" ");
+	return "";
+}
+/**
+* True for a control the agent must not operate: inside `[data-acryl-no-agent]`, inside a region whose
+* name says approval, permission, policy or Agent Control, or itself named after switching Agent Control off.
+*/
+function isProtected(el) {
+	if (el.closest("[data-acryl-no-agent]") !== null) return true;
+	let node = el;
+	for (let depth = 0; node !== null && depth < 12; depth += 1) {
+		if (PROTECTED_REGION.test(ancestorName(node))) return true;
+		node = node.parentElement;
+	}
+	return false;
+}
+//#endregion
+//#region ../../plugins/acryl-door/src/page/driver/accessibility.ts
+/** Roles, accessible names and states of DOM elements, in the small subset a snapshot needs. */
+const INPUT_ROLES = {
+	checkbox: "checkbox",
+	radio: "radio",
+	button: "button",
+	submit: "button",
+	reset: "button",
+	image: "button",
+	range: "slider",
+	number: "spinbutton",
+	search: "searchbox",
+	text: "textbox",
+	email: "textbox",
+	url: "textbox",
+	tel: "textbox",
+	password: "textbox"
+};
+const LANDMARKS = {
+	nav: "navigation",
+	main: "main",
+	aside: "complementary",
+	dialog: "dialog",
+	form: "form"
+};
+/** ARIA roles an element may declare that the driver treats as interactive or structural. */
+const EXPLICIT_ROLES = /* @__PURE__ */ new Set([
+	"button",
+	"link",
+	"tab",
+	"tabpanel",
+	"menu",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"checkbox",
+	"radio",
+	"switch",
+	"textbox",
+	"searchbox",
+	"combobox",
+	"listbox",
+	"option",
+	"slider",
+	"spinbutton",
+	"dialog",
+	"alertdialog",
+	"alert",
+	"status",
+	"navigation",
+	"main",
+	"heading",
+	"tree",
+	"treeitem",
+	"row",
+	"gridcell",
+	"tablist",
+	"toolbar",
+	"region",
+	"form",
+	"img"
+]);
+/** @returns the element's role, or null when it is not something a snapshot lists. */
+function roleOf(el) {
+	const explicit = el.getAttribute("role")?.trim().toLowerCase().split(/\s+/)[0];
+	if (explicit !== void 0 && explicit !== "" && EXPLICIT_ROLES.has(explicit)) return explicit;
+	const tag = el.tagName.toLowerCase();
+	if (tag === "a") return el.hasAttribute("href") ? "link" : null;
+	if (tag === "button" || tag === "summary") return "button";
+	if (tag === "select") return el.multiple ? "listbox" : "combobox";
+	if (tag === "textarea") return "textbox";
+	if (/^h[1-6]$/.test(tag)) return "heading";
+	if (tag === "img") return el.getAttribute("alt")?.trim() ? "img" : null;
+	if (tag === "input") {
+		const type = (el.getAttribute("type") ?? "text").toLowerCase();
+		if (type === "hidden") return null;
+		return INPUT_ROLES[type] ?? "textbox";
+	}
+	if (el.hasAttribute("contenteditable") && el.getAttribute("contenteditable") !== "false") return "textbox";
+	if (tag === "form") return el.hasAttribute("aria-label") || el.hasAttribute("aria-labelledby") ? "form" : null;
+	return LANDMARKS[tag] ?? null;
+}
+/** Roles whose accessible name is the text they contain, so that text is not listed again on its own. */
+const NAMED_BY_CONTENT = /* @__PURE__ */ new Set([
+	"button",
+	"link",
+	"tab",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"option",
+	"heading",
+	"switch",
+	"treeitem",
+	"checkbox",
+	"radio",
+	"alert",
+	"status"
+]);
+/** Roles that show their content as a value (a field, a native select), so the text inside them is not listed on its own either. */
+const SHOWN_AS_VALUE = /* @__PURE__ */ new Set([
+	"textbox",
+	"searchbox",
+	"combobox",
+	"spinbutton"
+]);
+const collapse = (value) => value.replace(/\s+/g, " ").trim();
+const clip = (value, max) => value.length > max ? `${value.slice(0, max - 1)}…` : value;
+/** The text a reader would hear: like `textContent`, but leaving out what is `aria-hidden` or `hidden` (a check mark, an icon glyph). */
+function readableText(root) {
+	const parts = [];
+	const walk = (node) => {
+		if (node.nodeType === Node.TEXT_NODE) parts.push(node.textContent ?? "");
+		else if (!(node instanceof Element && (node.getAttribute("aria-hidden") === "true" || node.hasAttribute("hidden")))) node.childNodes.forEach(walk);
+	};
+	root.childNodes.forEach(walk);
+	return parts.join("");
+}
+const textOf = (el, max) => clip(collapse(readableText(el)), max);
+/** The role of a run of visible text that is not already a control's name or a field's value: what an agent reads a value from. */
+const TEXT_ROLE = "text";
+/** One run of text as a snapshot lists it: collapsed and clipped, empty when there is nothing to read. */
+const textRun = (raw) => clip(collapse(raw), 200);
+/** The runs of text directly inside an element (between its child elements), as a snapshot lists them. */
+function textRunsOf(el) {
+	const runs = [];
+	let run = "";
+	for (const child of Array.from(el.childNodes)) if (child.nodeType === Node.TEXT_NODE) run += child.textContent ?? "";
+	else if (child instanceof Element) {
+		runs.push(textRun(run));
+		run = "";
+	}
+	runs.push(textRun(run));
+	return runs.filter((text) => text !== "");
+}
+/** ARIA-style accessible name, kept short. */
+function nameOf(el, role) {
+	const aria = el.getAttribute("aria-label")?.trim();
+	if (aria !== void 0 && aria !== "") return clip(collapse(aria), 120);
+	const by = el.getAttribute("aria-labelledby");
+	if (by !== null && by.trim() !== "") {
+		const joined = collapse(by.split(/\s+/).map((id) => el.ownerDocument.getElementById(id)?.textContent ?? "").join(" "));
+		if (joined !== "") return clip(joined, 120);
+	}
+	if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
+		const id = el.id;
+		const explicit = id === "" ? null : el.ownerDocument.querySelector(`label[for="${CSS.escape(id)}"]`);
+		const wrapping = el.closest("label");
+		const label = explicit ?? wrapping;
+		const labelText = label === null ? "" : collapse(readableText(label));
+		if (labelText !== "") return clip(labelText, 120);
+		if (el instanceof HTMLInputElement && (el.type === "button" || el.type === "submit" || el.type === "reset") && el.value !== "") return clip(el.value, 120);
+		const placeholder = el.getAttribute("placeholder")?.trim();
+		if (placeholder !== void 0 && placeholder !== "") return clip(placeholder, 120);
+	}
+	if (role === "img") return clip(collapse(el.getAttribute("alt") ?? ""), 120);
+	if (NAMED_BY_CONTENT.has(role)) {
+		const text = textOf(el, 120);
+		if (text !== "") return text;
+	}
+	if (role === "alert" || role === "status" || role === "dialog" || role === "alertdialog") {
+		const text = textOf(el, 160);
+		if (text !== "") return text;
+	}
+	return clip(collapse(el.getAttribute("title") ?? ""), 120);
+}
+/** The state words a snapshot shows for an element. */
+function statesOf(el, role) {
+	const states = [];
+	const aria = (name) => el.getAttribute(name);
+	if (el.disabled === true || aria("aria-disabled") === "true") states.push("disabled");
+	if (el instanceof HTMLInputElement && (el.type === "checkbox" || el.type === "radio")) {
+		if (el.checked) states.push("checked");
+	} else if (aria("aria-checked") === "true") states.push("checked");
+	if (aria("aria-expanded") === "true") states.push("expanded");
+	if (aria("aria-expanded") === "false") states.push("collapsed");
+	if (aria("aria-selected") === "true") states.push("selected");
+	if (aria("aria-pressed") === "true") states.push("pressed");
+	if (aria("aria-current") !== null && aria("aria-current") !== "false") states.push("current");
+	if (aria("aria-invalid") === "true") states.push("invalid");
+	if (el.required === true || aria("aria-required") === "true") states.push("required");
+	if (el.readOnly === true || aria("aria-readonly") === "true") states.push("readonly");
+	if (el.ownerDocument.activeElement === el) states.push("focused");
+	return states;
+}
+/** The visible value of an editable field, or undefined when it is empty, not editable, or sensitive. */
+function valueOf(el, role) {
+	if (role !== "textbox" && role !== "searchbox" && role !== "combobox" && role !== "spinbutton") return void 0;
+	if (isSensitive(el)) return void 0;
+	let value;
+	if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) value = el.value;
+	else if (el instanceof HTMLSelectElement) value = el.selectedOptions[0]?.textContent ?? void 0;
+	else if (el.hasAttribute("contenteditable")) value = el.textContent ?? void 0;
+	return value === void 0 || value === "" ? void 0 : clip(value, 100);
+}
+/** Heading level, when the element is a heading. */
+function levelOf(el) {
+	const explicit = Number(el.getAttribute("aria-level"));
+	if (Number.isInteger(explicit) && explicit >= 1 && explicit <= 6) return explicit;
+	const match = /^h([1-6])$/.exec(el.tagName.toLowerCase());
+	return match === null ? void 0 : Number(match[1]);
+}
+/** Hidden from everyone: the driver skips it and everything inside it. */
+function isHidden(el) {
+	if (el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true") return true;
+	if (el instanceof HTMLInputElement && el.type === "hidden") return true;
+	const view = el.ownerDocument.defaultView;
+	if (view === null) return false;
+	const style = view.getComputedStyle(el);
+	return style.display === "none" || style.visibility === "hidden";
+}
+/** The most elements one snapshot considers, however large the page. */
+const MAX_CANDIDATES = 5e3;
+/** True when the element (with layout) is at least partly inside the window; unknown layout counts as inside. */
+function inViewport(element, view) {
+	if (view === null) return true;
+	const rect = element.getBoundingClientRect();
+	if (rect.width === 0 && rect.height === 0) return true;
+	return rect.bottom > 0 && rect.right > 0 && rect.top < view.innerHeight && rect.left < view.innerWidth;
+}
+/**
+* Every element with a role, and every run of visible text, in reading order. Text that is already a name (inside a button, a link, a
+* heading, a label) is not listed again; a run is the text between two child elements, so `<p>Left: <b>24:59</b></p>` reads as
+* `Left:` and `24:59`.
+*/
+function collect(root) {
+	const found = [];
+	const walk = (element, depth, named) => {
+		if (found.length >= MAX_CANDIDATES) return;
+		if (element.hasAttribute("data-acryl-agent-control")) return;
+		const tag = element.tagName.toLowerCase();
+		if (tag === "script" || tag === "style" || tag === "template" || tag === "noscript") return;
+		if (isHidden(element)) return;
+		if (isSensitive(element)) return;
+		const role = roleOf(element);
+		let childDepth = depth;
+		if (role !== null) {
+			found.push({
+				element,
+				role,
+				name: nameOf(element, role),
+				depth
+			});
+			childDepth = depth + 1;
+		}
+		const inName = named || tag === "label" || role !== null && (NAMED_BY_CONTENT.has(role) || SHOWN_AS_VALUE.has(role));
+		let run = "";
+		const flush = () => {
+			const text = textRun(run);
+			run = "";
+			if (text !== "" && !inName && found.length < MAX_CANDIDATES) found.push({
+				element,
+				role: TEXT_ROLE,
+				name: text,
+				depth: childDepth
+			});
+		};
+		for (const child of Array.from(element.childNodes)) if (child.nodeType === Node.TEXT_NODE) run += child.textContent ?? "";
+		else if (child instanceof Element) {
+			flush();
+			walk(child, childDepth, inName);
+		}
+		flush();
+	};
+	walk(root, 0, false);
+	return found;
+}
+/** Snapshots the page and remembers the full candidate list of the current generation, for paging. */
+var SnapshotBuilder = class {
+	candidates = [];
+	refs;
+	root;
+	constructor(refs, root) {
+		this.refs = refs;
+		this.root = root;
+	}
+	snapshot(options = {}) {
+		const max = Math.min(options.maxNodes ?? 300, MAX_SNAPSHOT_NODES);
+		const root = this.root();
+		const view = root.ownerDocument.defaultView;
+		let offset = options.cursor ?? 0;
+		if (options.cursor === void 0) {
+			this.refs.begin();
+			const all = collect(root);
+			this.candidates = [...all.filter((c) => inViewport(c.element, view)), ...all.filter((c) => !inViewport(c.element, view))];
+			offset = 0;
+		} else if (this.candidates.length === 0 || offset > this.candidates.length) throw new UiControlError("stale-ref", "that page of the snapshot is gone; take a new snapshot");
+		const page = this.candidates.slice(offset, offset + max);
+		const nodes = page.map((candidate) => {
+			const states = statesOf(candidate.element, candidate.role);
+			if (isProtected(candidate.element)) states.push("protected");
+			const value = valueOf(candidate.element, candidate.role);
+			const level = candidate.role === "heading" ? levelOf(candidate.element) : void 0;
+			return {
+				ref: this.refs.issue(candidate.element, candidate.role, candidate.name),
+				role: candidate.role,
+				name: candidate.name,
+				depth: candidate.depth,
+				states,
+				...value === void 0 ? {} : { value },
+				...level === void 0 ? {} : { level }
+			};
+		});
+		const end = offset + page.length;
+		return {
+			generation: this.refs.generation,
+			title: root.ownerDocument.title,
+			nodes,
+			total: this.candidates.length,
+			...end < this.candidates.length ? { nextCursor: end } : {}
+		};
+	}
+	/** Drop the remembered page list (with the refs). */
+	clear() {
+		this.candidates = [];
+	}
+};
+//#endregion
+//#region ../../plugins/acryl-door/src/page/driver/actions.ts
+/** The actions the driver performs on the page, each guarded by the same rules. */
+const EDITABLE_ROLES = /* @__PURE__ */ new Set([
+	"textbox",
+	"searchbox",
+	"spinbutton",
+	"combobox"
+]);
+const POLL_MS = 50;
+const target = (role, name) => ({
+	role,
+	name
+});
+function effectivelyHidden(element) {
+	for (let node = element; node !== null; node = node.parentElement) if (isHidden(node)) return true;
+	return false;
+}
+/** Everything an action checks before touching an element. */
+function prepare(env, ref) {
+	const resolved = env.refs.resolve(ref);
+	const { element } = resolved;
+	if (isSensitive(element)) throw new UiControlError("sensitive", "that is a password, token or payment field; the agent does not read or type into it");
+	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`);
+	return resolved;
+}
+function mouse(element, type) {
+	element.dispatchEvent(new MouseEvent(type, {
+		bubbles: true,
+		cancelable: true
+	}));
+}
+/** xterm.js reads neither the value of its input textarea nor a bare synthetic key: text arrives as a paste, and key handling reads the legacy `keyCode`. */
+function isTerminalInput(element) {
+	return element.classList.contains("xterm-helper-textarea");
+}
+function pasteInto(element, text) {
+	const clipboardData = new DataTransfer();
+	clipboardData.setData("text/plain", text);
+	element.dispatchEvent(new ClipboardEvent("paste", {
+		clipboardData,
+		bubbles: true,
+		cancelable: true
+	}));
+}
+const LEGACY_KEY_CODES = {
+	Backspace: 8,
+	Tab: 9,
+	Enter: 13,
+	Escape: 27,
+	" ": 32,
+	PageUp: 33,
+	PageDown: 34,
+	End: 35,
+	Home: 36,
+	ArrowLeft: 37,
+	ArrowUp: 38,
+	ArrowRight: 39,
+	ArrowDown: 40,
+	Delete: 46
+};
+function setNativeValue(element, value) {
+	const proto = element instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+	const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+	if (setter === void 0) element.value = value;
+	else setter.call(element, value);
+}
+function click(env, request) {
+	const { element, role, name } = prepare(env, request.ref);
+	element.scrollIntoView?.({ block: "nearest" });
+	element.focus?.();
+	mouse(element, "mousedown");
+	mouse(element, "mouseup");
+	element.click();
+	return {
+		ok: true,
+		target: target(role, name)
+	};
+}
+function typeText(env, request) {
+	const { element, role, name } = prepare(env, request.ref);
+	if (!EDITABLE_ROLES.has(role) || role === "combobox" && element instanceof HTMLSelectElement) throw new UiControlError("not-actionable", `"${name}" is a ${role}, not a text field; use select or click`);
+	if (element.readOnly === true || element.getAttribute("aria-readonly") === "true") throw new UiControlError("not-actionable", `"${name}" is read-only`);
+	const clear = request.clear ?? true;
+	element.focus?.();
+	if (isTerminalInput(element)) pasteInto(element, request.text);
+	else if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+		setNativeValue(element, clear ? request.text : element.value + request.text);
+		element.dispatchEvent(new Event("input", { bubbles: true }));
+		element.dispatchEvent(new Event("change", { bubbles: true }));
+	} else {
+		element.textContent = clear ? request.text : (element.textContent ?? "") + request.text;
+		element.dispatchEvent(new Event("input", { bubbles: true }));
+	}
+	if (request.submit === true) pressKey(env, {
+		op: "press",
+		key: "Enter",
+		ref: request.ref
+	});
+	return {
+		ok: true,
+		target: target(role, name),
+		detail: `typed ${String(request.text.length)} characters`
+	};
+}
+function selectOption(env, request) {
+	const { element, role, name } = prepare(env, request.ref);
+	if (!(element instanceof HTMLSelectElement)) throw new UiControlError("not-actionable", `"${name}" is a ${role}, not a select; click it and pick the option`);
+	const wanted = request.option.trim().toLowerCase();
+	const options = Array.from(element.options);
+	const match = options.find((option) => option.value.toLowerCase() === wanted) ?? options.find((option) => (option.textContent ?? "").trim().toLowerCase() === wanted);
+	if (match === void 0) throw new UiControlError("not-found", `"${name}" has no option "${request.option}"`);
+	if (match.disabled) throw new UiControlError("not-actionable", `the option "${request.option}" is disabled`);
+	element.value = match.value;
+	element.dispatchEvent(new Event("input", { bubbles: true }));
+	element.dispatchEvent(new Event("change", { bubbles: true }));
+	return {
+		ok: true,
+		target: target(role, name),
+		detail: `selected ${match.textContent?.trim() ?? match.value}`
+	};
+}
+function pressKey(env, request) {
+	const doc = env.document();
+	let element;
+	let role;
+	let name;
+	if (request.ref !== void 0) ({element, role, name} = prepare(env, request.ref));
+	else {
+		element = doc.activeElement ?? doc.body;
+		if (isSensitive(element)) throw new UiControlError("sensitive", "the focused field is a password, token or payment field");
+		if (isProtected(element)) throw new UiControlError("protected", "the focused control belongs to approval, permissions or Agent Control itself");
+		role = roleOf(element) ?? "page";
+		name = roleOf(element) === null ? "" : nameOf(element, role);
+	}
+	const key = request.key === "Space" ? " " : request.key;
+	const keyCode = LEGACY_KEY_CODES[key];
+	const init = {
+		key,
+		bubbles: true,
+		cancelable: true,
+		...keyCode === void 0 ? {} : {
+			keyCode,
+			which: keyCode
+		}
+	};
+	element.focus?.();
+	if (element.dispatchEvent(new KeyboardEvent("keydown", init))) {
+		if ((key === "Enter" || key === " ") && (role === "button" || role === "link")) element.click();
+		else if (key === "Enter" && element instanceof HTMLInputElement && element.form !== null) element.form.requestSubmit?.();
+	}
+	element.dispatchEvent(new KeyboardEvent("keyup", init));
+	return {
+		ok: true,
+		target: target(role, name),
+		detail: `pressed ${request.key}`
+	};
+}
+function scroll(env, request) {
+	const doc = env.document();
+	const amount = request.amount ?? 400;
+	const dx = request.direction === "left" ? -amount : request.direction === "right" ? amount : 0;
+	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);
+		element.scrollBy?.({
+			left: dx,
+			top: dy
+		});
+		if (typeof element.scrollBy !== "function") {
+			element.scrollTop += dy;
+			element.scrollLeft += dx;
+		}
+		return {
+			ok: true,
+			target: target(role, name),
+			detail: `scrolled ${request.direction}`
+		};
+	}
+	doc.defaultView?.scrollBy?.({
+		left: dx,
+		top: dy
+	});
+	return {
+		ok: true,
+		detail: `scrolled the page ${request.direction}`
+	};
+}
+/** True when something visible on the page matches `request`. */
+function present(env, request) {
+	const doc = env.document();
+	const walk = (element) => {
+		if (element.hasAttribute("data-acryl-agent-control") || isHidden(element) || isSensitive(element)) return false;
+		const role = roleOf(element);
+		if (request.role !== void 0 || request.name !== void 0) {
+			if (role !== null && (request.role === void 0 || role === request.role.toLowerCase()) && (request.name === void 0 || nameOf(element, role).toLowerCase().includes(request.name.toLowerCase()))) return true;
+		}
+		if (request.text !== void 0 && element.children.length === 0 && (element.textContent ?? "").toLowerCase().includes(request.text.toLowerCase())) return true;
+		return Array.from(element.children).some(walk);
+	};
+	return walk(doc.body);
+}
+async function wait(env, request, signal) {
+	const budget = Math.min(request.timeoutMs ?? 3e3, MAX_WAIT_MS);
+	let waited = 0;
+	const wantGone = request.gone === true;
+	for (;;) {
+		if (present(env, request) !== wantGone) return {
+			ok: true,
+			detail: wantGone ? "it is gone" : "it is there"
+		};
+		if (waited >= budget) throw new UiControlError("not-found", wantGone ? "it did not go away in time" : "it did not appear in time");
+		await env.sleep(POLL_MS, signal);
+		waited += POLL_MS;
+	}
+}
+//#endregion
+//#region ../../plugins/acryl-door/src/page/driver/ref-table.ts
+/**
+* Refs: short-lived handles an agent uses to name an element.
+*
+* A ref is `<generation>.<n>`. Each snapshot starts a new generation and every older ref becomes stale, so a
+* ref can never quietly point at a different element after the page changed. Even within a generation, a
+* ref is honoured only while its element is still in the document and still has the role and name it had when
+* the ref was issued; a re-rendered or replaced control is a typed `stale-ref`, never a click somewhere else.
+*/
+var RefTable = class {
+	generationNumber = 0;
+	entries = /* @__PURE__ */ new Map();
+	nextIndex = 1;
+	get generation() {
+		return this.generationNumber;
+	}
+	/** Start a new generation: every earlier ref is now stale. */
+	begin() {
+		this.generationNumber += 1;
+		this.entries = /* @__PURE__ */ new Map();
+		this.nextIndex = 1;
+		return this.generationNumber;
+	}
+	/** Forget everything (the driver is going away or was stopped). */
+	clear() {
+		this.begin();
+	}
+	issue(element, role, name) {
+		const index = this.nextIndex;
+		this.nextIndex += 1;
+		this.entries.set(index, {
+			element: new WeakRef(element),
+			role,
+			name
+		});
+		return `${String(this.generationNumber)}.${String(index)}`;
+	}
+	/** @throws UiControlError `unknown-ref` or `stale-ref`. */
+	resolve(ref) {
+		const [generationText, indexText] = ref.split(".");
+		const generation = Number(generationText);
+		const index = Number(indexText);
+		if (!Number.isInteger(generation) || !Number.isInteger(index)) throw new UiControlError("unknown-ref", `${ref} is not a ref`);
+		if (generation !== this.generationNumber) throw new UiControlError("stale-ref", `${ref} is from an earlier snapshot (the latest is ${String(this.generationNumber)}); take a new snapshot`);
+		const entry = this.entries.get(index);
+		if (entry === void 0) throw new UiControlError("unknown-ref", `${ref} was not in the snapshot`);
+		const element = entry.element.deref();
+		if (element === void 0 || !element.isConnected) throw new UiControlError("stale-ref", `${ref} is no longer on the page; take a new snapshot`);
+		if (entry.role === "text") {
+			if (!textRunsOf(element).includes(entry.name)) throw new UiControlError("stale-ref", `${ref} changed since the snapshot ("${entry.name}" is no longer there); take a new snapshot`);
+			return {
+				element,
+				role: entry.role,
+				name: entry.name
+			};
+		}
+		const role = roleOf(element);
+		if (role !== entry.role || nameOf(element, role) !== entry.name) throw new UiControlError("stale-ref", `${ref} changed since the snapshot ("${entry.name}" is now something else); take a new snapshot`);
+		return {
+			element,
+			role: entry.role,
+			name: entry.name
+		};
+	}
+};
+//#endregion
+//#region ../../plugins/acryl-door/src/page/driver/driver.ts
+/**
+* The in-page driver: takes one {@link UiRequest} and does it, under the rules.
+*
+* It owns the ref table, the kill switch, the yield-to-the-user rule and the "driving" activity the indicator
+* shows. It touches only the document it is given, never another window and never the OS.
+*/
+/** 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;
+function realSleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal.reason);
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+var UiDriver = class {
+	refs = new RefTable();
+	snapshots;
+	listeners = /* @__PURE__ */ new Set();
+	env;
+	stopAll = /* @__PURE__ */ new Set();
+	killedFlag = false;
+	disposed = false;
+	busyCount = 0;
+	doing = "";
+	current = {
+		busy: false,
+		doing: "",
+		killed: false
+	};
+	options;
+	constructor(options) {
+		this.options = options;
+		this.snapshots = new SnapshotBuilder(this.refs, () => options.document().body);
+		this.env = {
+			refs: this.refs,
+			document: options.document,
+			sleep: options.sleep ?? realSleep
+		};
+	}
+	/** The current activity; the same object until something changes, as a store snapshot must be. */
+	get activity() {
+		return this.current;
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	/** The user pressed the kill switch: pending calls settle as `killed` and new ones are refused. */
+	kill() {
+		this.killedFlag = true;
+		for (const controller of [...this.stopAll]) controller.abort(new UiControlError("killed", "the user stopped the agent"));
+		this.refs.clear();
+		this.snapshots.clear();
+		this.emit();
+	}
+	/** The user allowed the agent to drive again. */
+	resume() {
+		this.killedFlag = false;
+		this.emit();
+	}
+	/** The driver goes away: pending calls settle as `unloaded`; refs are gone. */
+	dispose() {
+		this.disposed = true;
+		for (const controller of [...this.stopAll]) controller.abort(new UiControlError("unloaded", "the driver was unloaded"));
+		this.refs.clear();
+		this.snapshots.clear();
+		this.listeners.clear();
+	}
+	/** @param signal - the Host cancelled the call. @throws UiControlError. */
+	async handle(request, signal) {
+		if (this.disposed) throw new UiControlError("unloaded", "the driver was unloaded");
+		if (this.killedFlag) throw new UiControlError("killed", "the user stopped the agent; it cannot drive until they allow it again");
+		const controller = new AbortController();
+		this.stopAll.add(controller);
+		const onCancel = () => {
+			controller.abort(new UiControlError("aborted", "the call was cancelled"));
+		};
+		signal?.addEventListener("abort", onCancel, { once: true });
+		this.busyCount += 1;
+		this.doing = request.op;
+		this.emit();
+		try {
+			if (MUTATING_OPS.includes(request.op)) await this.yieldToUser(controller.signal);
+			if (controller.signal.aborted) throw controller.signal.reason;
+			return await this.run(request, controller.signal);
+		} catch (cause) {
+			if (cause instanceof UiControlError) throw cause;
+			if (controller.signal.aborted && controller.signal.reason instanceof UiControlError) throw controller.signal.reason;
+			throw new UiControlError("not-actionable", cause instanceof Error ? cause.message : "the action failed");
+		} finally {
+			signal?.removeEventListener("abort", onCancel);
+			this.stopAll.delete(controller);
+			this.busyCount -= 1;
+			if (this.busyCount === 0) this.doing = "";
+			this.emit();
+		}
+	}
+	async run(request, signal) {
+		switch (request.op) {
+			case "snapshot": return this.snapshots.snapshot({
+				...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 "select": return selectOption(this.env, request);
+			case "press": return pressKey(this.env, request);
+			case "scroll": return scroll(this.env, request);
+			case "wait": return wait(this.env, request, signal);
+		}
+	}
+	async yieldToUser(signal) {
+		const since = this.options.msSinceUserInput;
+		if (since === void 0) return;
+		let waited = 0;
+		while (since() < YIELD_MS && waited < MAX_YIELD_MS) {
+			await this.env.sleep(100, signal);
+			waited += 100;
+		}
+	}
+	emit() {
+		const next = {
+			busy: this.busyCount > 0,
+			doing: this.doing,
+			killed: this.killedFlag
+		};
+		if (next.busy === this.current.busy && next.doing === this.current.doing && next.killed === this.current.killed) return;
+		this.current = next;
+		const activity = next;
+		for (const listener of [...this.listeners]) listener(activity);
+	}
+};
+//#endregion
+//#region ../../plugins/acryl-door/src/page/user-input.ts
+/** Tracks when the user last used the page, so the agent yields to them. */
+/** Events only a real person produces: a script's `dispatchEvent` is never `isTrusted`. */
+const USER_EVENTS = [
+	"pointerdown",
+	"mousedown",
+	"keydown",
+	"wheel",
+	"touchstart"
+];
+var UserInputClock = class {
+	last = Number.NEGATIVE_INFINITY;
+	now;
+	constructor(now = () => Date.now()) {
+		this.now = now;
+	}
+	/** Milliseconds since the user last touched the page; Infinity when they have not. */
+	msSince = () => this.last === Number.NEGATIVE_INFINITY ? Number.POSITIVE_INFINITY : this.now() - this.last;
+	/** Start listening. @returns disposer. */
+	attach(target) {
+		const handler = (event) => {
+			if (event.isTrusted) this.last = this.now();
+		};
+		for (const type of USER_EVENTS) target.addEventListener(type, handler, {
+			capture: true,
+			passive: true
+		});
+		return () => {
+			for (const type of USER_EVENTS) target.removeEventListener(type, handler, { capture: true });
+		};
+	}
+};
+//#endregion
+//#region ../../plugins/acryl-door/src/page/indicator.ts
+const LABELS = {
+	snapshot: "looking at the page",
+	click: "clicking",
+	type: "typing",
+	select: "choosing an option",
+	press: "pressing a key",
+	scroll: "scrolling",
+	wait: "waiting"
+};
+const STYLE_ID = "acryl-door-indicator-style";
+const STYLES = `
+.acrylDoorBar { position: fixed; z-index: 2147483647; left: 50%; bottom: 16px; transform: translateX(-50%); display: flex; align-items: center; gap: 10px;
+  padding: 8px 12px; border-radius: 8px; font: 13px/1.4 system-ui, sans-serif; color: #fff; background: #1f2937; box-shadow: 0 4px 16px rgba(0,0,0,.25); }
+.acrylDoorBar[data-killed] { background: #7f1d1d; }
+.acrylDoorBar button { font: inherit; color: inherit; background: rgba(255,255,255,.15); border: 1px solid rgba(255,255,255,.35); border-radius: 6px; padding: 2px 10px; cursor: pointer; }
+.acrylDoorDot { width: 8px; height: 8px; border-radius: 50%; background: #34d399; }
+`;
+/** Show the bar for `driver` in `document`. @returns the disposer, which removes the bar, its style and its listeners. */
+function mountIndicator(driver, document) {
+	if (document.getElementById(STYLE_ID) === null) {
+		const style = document.createElement("style");
+		style.id = STYLE_ID;
+		style.textContent = STYLES;
+		document.head.append(style);
+	}
+	const bar = document.createElement("div");
+	bar.className = "acrylDoorBar";
+	bar.setAttribute("data-acryl-agent-control", "");
+	bar.setAttribute("data-acryl-no-agent", "");
+	bar.setAttribute("role", "status");
+	bar.setAttribute("aria-live", "polite");
+	const onKey = (event) => {
+		if (event.key === "Escape" && event.isTrusted && driver.activity.busy) driver.kill();
+	};
+	document.addEventListener("keydown", onKey, true);
+	const render = (activity) => {
+		if (!activity.busy && !activity.killed) {
+			bar.remove();
+			return;
+		}
+		const button = document.createElement("button");
+		button.type = "button";
+		const text = document.createElement("span");
+		if (activity.killed) {
+			bar.setAttribute("data-killed", "");
+			text.textContent = "Agent stopped. It cannot use the page until you allow it.";
+			button.textContent = "Allow again";
+			button.addEventListener("click", () => {
+				driver.resume();
+			});
+			bar.replaceChildren(text, button);
+		} else {
+			bar.removeAttribute("data-killed");
+			const dot = document.createElement("span");
+			dot.className = "acrylDoorDot";
+			dot.setAttribute("aria-hidden", "true");
+			text.textContent = `Agent is driving: ${LABELS[activity.doing] ?? activity.doing}`;
+			button.textContent = "Stop";
+			button.addEventListener("click", () => {
+				driver.kill();
+			});
+			bar.replaceChildren(dot, text, button);
+		}
+		if (!bar.isConnected) document.body.append(bar);
+	};
+	const unsubscribe = driver.subscribe(render);
+	render(driver.activity);
+	return () => {
+		unsubscribe();
+		document.removeEventListener("keydown", onKey, true);
+		bar.remove();
+		document.getElementById(STYLE_ID)?.remove();
+	};
+}
+//#endregion
+export { PageChannel, SILENCE_MS, UiDriver, UserInputClock, mountIndicator };