effect-browser 0.2.0-beta.0 → 0.2.0-beta.1

package/dist/Testing.mjs

@@ -0,0 +1,1561 @@
+import { BrowserError, InitializationError, Reasons } from "./Errors.mjs";
+import { BrowserPolicy, ControlFacts, FrameInfo, Identifier, ObservedControl, PageExecutionState, PageInfo, PageSuspension, SafeFilename, TargetUrl, ViewportEvidence, ViewportRect } from "./BrowserData.mjs";
+import { a as cleanupStep, c as checked, l as fromNativeAttempt, n as make, s as reported, u as issueBinding } from "./BrowserRuntime-DViKNUdD.mjs";
+import { Crypto, Effect, Layer, Option, PlatformError, Redacted, Schema } from "effect";
+//#region src/internal/testing/Crypto.ts
+/**
+* A `Crypto` whose bytes count up from one, so every id and handoff token a scripted browser draws
+* is predictable. It is not random and computes no digest.
+*/
+const makeSequentialCrypto = () => {
+	let draws = 0;
+	return Crypto.make({
+		randomBytes: (size) => {
+			const bytes = new Uint8Array(size);
+			let rest = ++draws;
+			for (let index = size - 1; index >= 0 && rest > 0; index--) {
+				bytes[index] = rest % 256;
+				rest = Math.floor(rest / 256);
+			}
+			return bytes;
+		},
+		digest: () => Effect.fail(PlatformError.badArgument({
+			module: "Crypto",
+			method: "digest",
+			description: "A scripted browser's Crypto computes no digest"
+		}))
+	});
+};
+//#endregion
+//#region src/internal/testing/Frame.ts
+/** A valid 64×48 baseline JPEG, the bytes a scripted capture frame carries by default. */
+const jpegFrame = () => Uint8Array.from(atob("/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAoHBwgHBgoICAgLCgoLDhgQDg0NDh0VFhEYIx8lJCIfIiEmKzcvJik0KSEiMEExNDk7Pj4+JS5ESUM8SDc9Pjv/2wBDAQoLCw4NDhwQEBw7KCIoOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozv/wAARCAAwAEADASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwDyVLf2qdLf2q6lv7VOlv7UoyMadcpJb+1Tpb+1XUt/ap0t/atoyPSp1yklv7VYS39qupb+1Tpb+1bxkejTrlJLf2qdLf2q6lv7VOlv7VtGR6NOuYKW/tU6W/tV1Lf2qwlv7V4kZH5fTrlFLf2qwlv7VdS39qnS39q2jI9GnXKSW/tU6W/tV1Lf2qdLf2raMj0adcpJb+1Tpb+1Xkt/ap0t/at4yPRp1zBS39qnS39qupb+1Tpb+1eHGR+X065SS39qnS39qupb+1Tpb+1bxkejTrlJLf2qwlv7VdS39qnS39q2jI9GnXKSW/tU6W/tV1Lf2qdLf2raMj0adc//2Q=="), (character) => character.charCodeAt(0));
+//#endregion
+//#region src/internal/testing/Script.ts
+const uniqueBy = (key, title) => Schema.makeFilter((items) => new Set(items.map(key)).size === items.length, { title });
+/** Host-only facts a scripted control reports beyond what its observed fields imply. */
+const ControlFactsScript = Schema.Struct({
+	editable: Schema.optionalKey(Schema.Boolean),
+	formMethod: Schema.optionalKey(Schema.Literals([
+		"get",
+		"post",
+		"dialog"
+	])),
+	hitTest: Schema.optionalKey(Schema.Literals([
+		"self",
+		"covered",
+		"uncertain",
+		"unsampled"
+	])),
+	placement: Schema.optionalKey(Schema.Literals([
+		"inside",
+		"partial",
+		"outside"
+	])),
+	autocomplete: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(128))),
+	box: Schema.optionalKey(Schema.Struct({
+		x: Schema.Finite,
+		y: Schema.Finite,
+		width: Schema.Finite,
+		height: Schema.Finite
+	}))
+});
+/**
+* One control a scripted document offers. `id` becomes the issued `elementId`, so a scripted
+* model turn can name it statically. Nothing here is a live capability.
+*/
+const ControlScript = Schema.Struct({
+	id: Identifier,
+	kind: ObservedControl.fields.kind,
+	label: ObservedControl.fields.label,
+	disabled: Schema.optionalKey(Schema.Boolean),
+	/** A checkbox or radio `input` without it starts unchecked, as a real one does. */
+	checked: Schema.optionalKey(Schema.Boolean),
+	selected: Schema.optionalKey(Schema.Boolean),
+	inputType: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(32))),
+	required: Schema.optionalKey(Schema.Boolean),
+	multiple: Schema.optionalKey(Schema.Boolean),
+	/** The scripted select this option belongs to; it must be in the same document. */
+	selectElementId: Schema.optionalKey(Identifier),
+	/**
+	* The link target, or the form action a submit control sends to: reported as the control's
+	* destination fact, and where activating it leads. Only a `link`, or a `button`/`input` whose
+	* `inputType` is `submit` or `image`, has one, because that is all a real document reports.
+	*/
+	destination: Schema.optionalKey(TargetUrl),
+	/** Where activation leads with no destination fact: what an `onclick` handler does. */
+	activates: Schema.optionalKey(TargetUrl),
+	/** Outside the viewport: absent from viewport readings and refused by hover. */
+	offscreen: Schema.optionalKey(Schema.Boolean),
+	/** What `readText({ selector: "#id" })` returns; defaults to the label. */
+	text: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(65536))),
+	/** Clicking for a download completes one with this name. */
+	download: Schema.optionalKey(SafeFilename),
+	facts: Schema.optionalKey(ControlFactsScript)
+}).check(Schema.makeFilter((control) => control.destination === void 0 || control.kind === "link" || (control.kind === "button" || control.kind === "input") && (control.inputType === "submit" || control.inputType === "image"), { title: "a destination only on a link or a submit control" }));
+const DocumentScript = Schema.Struct({
+	url: TargetUrl,
+	title: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(512))),
+	text: Schema.String.check(Schema.isMaxLength(131072)),
+	controls: Schema.optionalKey(Schema.Array(ControlScript).check(Schema.isMaxLength(64), uniqueBy((control) => control.id, "unique control ids")))
+});
+/**
+* The documents a scripted browser can show. A navigation to a listed address reaches that
+* document; an unlisted address reaches an empty document with that address.
+*/
+const Script = Schema.Struct({
+	documents: Schema.Array(DocumentScript).check(Schema.isMinLength(1), Schema.isMaxLength(64), uniqueBy((document) => document.url, "unique document addresses")),
+	/** The first page's document at connect; defaults to the first listed document. */
+	start: Schema.optionalKey(TargetUrl),
+	/**
+	* What successive connection attempts to one browser do: `refuse` fails the attempt as an
+	* unreachable endpoint would, and `accept` connects. Attempts past the list connect.
+	*/
+	connections: Schema.optionalKey(Schema.Array(Schema.Literals(["accept", "refuse"])).check(Schema.isMaxLength(16)))
+});
+var ScriptedReference = class extends Schema.Class("ScriptedBrowserReference")({
+	provider: Schema.Literal("scripted"),
+	id: Identifier
+}) {};
+var ScriptedCleanupIssue = class extends Schema.Class("ScriptedCleanupIssue")({
+	step: Schema.Literals([
+		"fence",
+		"capture",
+		"initialization",
+		"disconnect"
+	]),
+	reason: Schema.Literals([
+		"timeout",
+		"failed",
+		"interrupted"
+	])
+}) {};
+/** Connection teardown facts for a scripted browser; there is no process or provider status. */
+var ScriptedCleanupResult = class extends Schema.Class("ScriptedCleanupResult")({
+	reference: ScriptedReference,
+	connection: Schema.Literals([
+		"closed",
+		"failed",
+		"not-connected",
+		"pending"
+	]),
+	issues: Schema.Array(ScriptedCleanupIssue).check(Schema.isMaxLength(16))
+}) {};
+/**
+* The operations whose next call a test may script. `disconnect` is the owner's native teardown
+* of a connection: a `Fail` makes it fail and a `Hold` parks it, however long cleanup waits.
+*/
+const ScriptableOperation = Schema.Literals([
+	"navigate",
+	"navigate-stop",
+	"observe",
+	"checkpoint",
+	"control-facts",
+	"revalidate",
+	"read-text",
+	"screenshot",
+	"wait",
+	"click",
+	"fill",
+	"fill-form",
+	"select-option",
+	"scroll",
+	"click-and-wait",
+	"download-action",
+	"select-files",
+	"file-chooser",
+	"pointer-move",
+	"hover",
+	"wheel",
+	"press",
+	"type",
+	"list-pages",
+	"list-frames",
+	"select-page",
+	"select-frame",
+	"new-page",
+	"close-page",
+	"resize",
+	"page-suspend",
+	"page-resume",
+	"capture-stop",
+	"disconnect"
+]);
+//#endregion
+//#region src/internal/testing/Engine.ts
+const gates = /* @__PURE__ */ new WeakMap();
+/** A gate that holds a scripted call until the test opens it. */
+const makeGate = Effect.sync(() => {
+	let reach = () => {};
+	let open = () => {};
+	const reached = new Promise((resolve) => {
+		reach = resolve;
+	});
+	const opened = new Promise((resolve) => {
+		open = resolve;
+	});
+	const gate = {
+		reached: Effect.promise(() => reached),
+		open: Effect.sync(() => {
+			open();
+		})
+	};
+	gates.set(gate, {
+		reach,
+		opened
+	});
+	return gate;
+});
+/** A 1×1 PNG: what a scripted screenshot or checkpoint picture contains. */
+const PNG = Uint8Array.from(atob("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="), (character) => character.charCodeAt(0));
+const fail = (operation, reason, outcome = "undispatched") => BrowserError.make({
+	operation,
+	reason,
+	outcome
+});
+const encoder = new TextEncoder();
+/** Cut at a character boundary so the bounded text is still valid UTF-16. */
+const bounded = (text, maximumBytes) => {
+	if (encoder.encode(text).length <= maximumBytes) return {
+		text,
+		truncated: false
+	};
+	let kept = "";
+	let bytes = 0;
+	for (const character of text) {
+		const size = encoder.encode(character).length;
+		if (bytes + size > maximumBytes) break;
+		kept += character;
+		bytes += size;
+	}
+	return {
+		text: kept,
+		truncated: true
+	};
+};
+const originOf = (url) => {
+	try {
+		return new URL(url).origin;
+	} catch {
+		return "null";
+	}
+};
+const isSelectable = (kind) => kind === "select";
+const isEditable = (control) => (control.kind === "input" || control.kind === "textarea") && control.disabled !== true;
+const isToggle = (control) => control.kind === "input" && (control.inputType === "checkbox" || control.inputType === "radio");
+/** Input types native fill types or assigns text into; every other input takes none. */
+const textInputs = /* @__PURE__ */ new Set([
+	"",
+	"email",
+	"number",
+	"password",
+	"search",
+	"tel",
+	"text",
+	"url",
+	"color",
+	"date",
+	"time",
+	"datetime-local",
+	"month",
+	"range",
+	"week"
+]);
+/**
+* What the real driver refuses before dispatching text into a control: a disabled one, one that
+* takes no text, and a number field given something that is not a number.
+*/
+const textRefusal = (control, text) => {
+	const editable = control.facts?.editable;
+	if (control.disabled === true) return Reasons.Disabled.make({});
+	if (editable === false) return Reasons.Unsupported.make({});
+	if (control.kind === "textarea") return void 0;
+	if (control.kind !== "input") return editable === true ? void 0 : Reasons.Unsupported.make({});
+	const type = (control.inputType ?? "").toLowerCase();
+	if (!textInputs.has(type)) return Reasons.Unsupported.make({});
+	return type === "number" && Number.isNaN(Number(text.trim())) ? Reasons.Unsupported.make({}) : void 0;
+};
+const controlState = (script) => ({
+	script,
+	checked: script.checked ?? (isToggle(script) ? false : void 0),
+	selected: script.selected
+});
+const makeScriptedBrowser = (script, timers) => {
+	const pages = /* @__PURE__ */ new Map();
+	const calls = [];
+	const armed = /* @__PURE__ */ new Map();
+	const connections = [];
+	const live = /* @__PURE__ */ new Set();
+	let latest;
+	/** The page last selected by any connection: where the control's document operations act. */
+	let lastSelected;
+	let attempts = 0;
+	let sequence = 0;
+	let pageSerial = 0;
+	let observationSerial = 0;
+	let suspensionSerial = 0;
+	let downloadSerial = 0;
+	let lastTimestamp = 17e11;
+	const state = (document) => ({
+		url: document.url,
+		title: document.title ?? "",
+		text: document.text,
+		controls: (document.controls ?? []).map(controlState)
+	});
+	const documentFor = (url) => {
+		const listed = script.documents.find((document) => document.url === url);
+		return state(listed ?? {
+			url,
+			text: ""
+		});
+	};
+	const createPage = (document, registered) => {
+		const serial = ++pageSerial;
+		const page = {
+			pageId: `page-${serial}`,
+			targetId: `target-${serial}`,
+			frameId: `frame-${serial}`,
+			document,
+			epoch: 0,
+			registeredEpoch: registered ? 0 : -1,
+			values: /* @__PURE__ */ new Map(),
+			files: /* @__PURE__ */ new Map(),
+			focused: void 0,
+			closed: false,
+			held: void 0,
+			navigation: void 0,
+			watchers: /* @__PURE__ */ new Set(),
+			capture: void 0
+		};
+		pages.set(page.pageId, page);
+		return page;
+	};
+	const openPages = () => [...pages.values()].filter((page) => !page.closed);
+	const notify = (page) => {
+		const watchers = Array.from(page.watchers);
+		for (const watcher of watchers) watcher();
+	};
+	/** The page shows a new document: nodes go stale, values reset, captures learn of it. */
+	const commit = (page, document) => {
+		page.document = document;
+		page.epoch++;
+		page.values.clear();
+		page.files.clear();
+		page.focused = void 0;
+		page.navigation = void 0;
+		for (const connection of live) connection.retire(page.pageId);
+		if (page.capture !== void 0) {
+			const { start } = page.capture;
+			if (start.document === void 0) start.invalidate("target-changed");
+			else start.document(document.url);
+		}
+		notify(page);
+		for (const connection of live) connection.announce(page.pageId);
+	};
+	/** In-document change: identity survives by control id, so retained nodes and waits carry on. */
+	const update = (page, document) => {
+		const previous = new Map(page.document.controls.map((control) => [control.script.id, control]));
+		const controls = (document.controls ?? []).map((script) => {
+			const existing = previous.get(script.id);
+			if (existing === void 0) return controlState(script);
+			existing.script = script;
+			if (script.checked !== void 0) existing.checked = script.checked;
+			if (script.selected !== void 0) existing.selected = script.selected;
+			return existing;
+		});
+		page.document = {
+			url: document.url,
+			title: document.title ?? "",
+			text: document.text,
+			controls
+		};
+		if (page.focused !== void 0 && !previous.has(page.focused)) page.focused = void 0;
+		notify(page);
+	};
+	const take = (operation) => {
+		const queue = armed.get(operation);
+		const next = queue?.shift();
+		if (queue !== void 0 && queue.length === 0) armed.delete(operation);
+		return next;
+	};
+	const internalGate = (gate) => {
+		const internal = gates.get(gate);
+		if (internal === void 0) throw new Error("A scripted gate must come from the browser it holds");
+		return internal;
+	};
+	/** Only a mutation's Ticket carries dispatch evidence; a read's ticket has none to give. */
+	const isTicket = (ticket) => "dispatch" in ticket;
+	const connect = (options, events) => {
+		const ordinal = attempts++;
+		if (script.connections?.[ordinal] === "refuse") {
+			connections.push("refused");
+			throw new Error("The scripted browser refused this connection");
+		}
+		const bindings = options.bindings ?? [];
+		let viewport = { ...options.viewport };
+		const positions = /* @__PURE__ */ new Map();
+		let pointer = null;
+		let selectedId;
+		let snapshot;
+		let disconnected = false;
+		let index = -1;
+		const place = (pageId, point) => {
+			positions.set(pageId, point);
+			pointer = point;
+		};
+		const receipt = (pageId) => ({ position: positions.get(pageId) ?? null });
+		const select = (pageId) => {
+			selectedId = pageId;
+			lastSelected = pageId;
+		};
+		const selectedPage = (operation = "target") => {
+			const page = selectedId === void 0 ? void 0 : pages.get(selectedId);
+			if (disconnected || page === void 0 || page.closed) throw fail(operation, Reasons.Closed.make({}));
+			return page;
+		};
+		const current = (target, operation) => {
+			if (target === void 0) return selectedPage(operation);
+			if (disconnected) throw fail(operation, Reasons.Closed.make({}));
+			const page = pages.get(target.pageId);
+			if (page === void 0 || page.closed || page.frameId !== target.frameId) throw fail(operation, Reasons.Stale.make({}));
+			return page;
+		};
+		const pageOf = (info, operation) => {
+			const page = pages.get(info.pageId);
+			if (page === void 0) throw fail(operation, Reasons.NotFound.make({}));
+			if (page.closed || page.targetId !== info.targetId) throw fail(operation, Reasons.Stale.make({}));
+			return page;
+		};
+		const info = (page) => PageInfo.make({
+			pageId: page.pageId,
+			targetId: page.targetId,
+			url: page.document.url,
+			title: page.document.title,
+			selected: page.pageId === selectedId
+		});
+		const frameInfo = (page) => FrameInfo.make({
+			frameId: page.frameId,
+			parentFrameId: null,
+			url: page.document.url,
+			name: ""
+		});
+		const invalidateSnapshot = (scope = "all") => {
+			if (snapshot !== void 0 && scope !== "none" && (scope === "all" || scope.pageId === snapshot.pageId)) snapshot.validity = "invalid";
+		};
+		/** This connection ends: what it held on the browser's pages ends with it. */
+		const dropConnection = (announce, ended = "dropped") => {
+			if (disconnected) return;
+			disconnected = true;
+			connections[index] = ended;
+			live.delete(connection);
+			for (const page of pages.values()) {
+				if (page.navigation?.by === connection) page.navigation.drop();
+				if (page.held?.by === connection) page.held = void 0;
+				if (page.capture?.by === connection) page.capture = void 0;
+				notify(page);
+			}
+			if (announce) events.disconnected();
+		};
+		const dispatch = (ticket, record) => {
+			if (isTicket(ticket)) ticket.dispatch();
+			record.dispatched = true;
+		};
+		/** Once the owner aborts the admitted call, its own check names the reason. */
+		const aborted = (ticket, operation) => {
+			try {
+				ticket.check();
+			} catch (error) {
+				if (Schema.is(BrowserError)(error)) return error;
+			}
+			return fail(operation, Reasons.Interrupted.make({}), "unknown");
+		};
+		const hold = (gate, ticket, operation, record) => {
+			const internal = internalGate(gate);
+			internal.reach();
+			return new Promise((resolve, reject) => {
+				const onAbort = () => {
+					cleanup();
+					record.settled = "failed";
+					reject(aborted(ticket, operation));
+				};
+				const cleanup = () => ticket.signal.removeEventListener("abort", onAbort);
+				if (ticket.signal.aborted) {
+					onAbort();
+					return;
+				}
+				ticket.signal.addEventListener("abort", onAbort, { once: true });
+				internal.opened.then(() => {
+					cleanup();
+					resolve();
+				});
+			});
+		};
+		const applyArmed = async (operation, ticket, record) => {
+			const outcome = take(operation);
+			if (outcome === void 0) return;
+			switch (outcome._tag) {
+				case "Fail":
+					if (outcome.outcome === "unknown") dispatch(ticket, record);
+					throw fail(operation, outcome.reason, outcome.outcome);
+				case "Hold":
+					if (outcome.dispatched) dispatch(ticket, record);
+					await hold(outcome.gate, ticket, operation, record);
+					ticket.check();
+					return;
+				case "Disconnect":
+					if (outcome.dispatched === true) dispatch(ticket, record);
+					dropConnection(true);
+					throw fail(operation, Reasons.Disconnected.make({}), record.dispatched ? "unknown" : "undispatched");
+			}
+		};
+		const attempt = async (operation, ticket, meta, body) => {
+			const record = {
+				sequence: ++sequence,
+				operation,
+				pageId: meta.pageId ?? selectedId ?? "",
+				...meta.elementId === void 0 ? {} : { elementId: meta.elementId },
+				...meta.selector === void 0 ? {} : { selector: meta.selector },
+				dispatched: false,
+				settled: "pending"
+			};
+			calls.push(record);
+			try {
+				ticket?.check();
+				if (ticket !== void 0) await applyArmed(operation, ticket, record);
+				const value = await body(record);
+				record.settled = "completed";
+				return value;
+			} catch (error) {
+				record.settled = "failed";
+				throw error;
+			}
+		};
+		const meta = (target) => target === void 0 ? {} : typeof target === "string" ? { selector: target } : { elementId: target.elementId };
+		const facts = (control) => {
+			const { script: value } = control;
+			const extra = value.facts ?? {};
+			return ControlFacts.make({
+				kind: value.kind,
+				label: value.label,
+				disabled: value.disabled ?? false,
+				...control.checked === void 0 ? {} : { checked: control.checked },
+				...control.selected === void 0 ? {} : { selected: control.selected },
+				...value.required === void 0 ? {} : { required: value.required },
+				...value.multiple === void 0 ? {} : { multiple: value.multiple },
+				editable: extra.editable ?? isEditable(value),
+				...value.inputType === void 0 ? {} : { inputType: value.inputType },
+				...extra.autocomplete === void 0 ? {} : { autocomplete: extra.autocomplete },
+				...value.destination === void 0 ? {} : { destination: value.destination },
+				...extra.formMethod === void 0 ? {} : { formMethod: extra.formMethod },
+				box: ViewportRect.make(extra.box ?? {
+					x: 0,
+					y: 0,
+					width: 120,
+					height: 24
+				}),
+				placement: extra.placement ?? (value.offscreen === true ? "outside" : "inside"),
+				hitTest: extra.hitTest ?? (value.offscreen === true ? "unsampled" : "self"),
+				mainFrame: true
+			});
+		};
+		const observed = (control) => {
+			const { script: value } = control;
+			return ObservedControl.make({
+				elementId: value.id,
+				kind: value.kind,
+				label: value.label,
+				disabled: value.disabled ?? false,
+				...control.checked === void 0 ? {} : { checked: control.checked },
+				...control.selected === void 0 ? {} : { selected: control.selected },
+				...value.inputType === void 0 ? {} : { inputType: value.inputType },
+				...value.required === void 0 ? {} : { required: value.required },
+				...value.multiple === void 0 ? {} : { multiple: value.multiple },
+				...value.selectElementId === void 0 ? {} : { selectElementId: value.selectElementId }
+			});
+		};
+		const bySelector = (page, selector, operation) => {
+			const id = selector.startsWith("#") ? selector.slice(1) : void 0;
+			const control = id === void 0 ? void 0 : page.document.controls.find((c) => c.script.id === id);
+			if (control === void 0) throw fail(operation, Reasons.NotFound.make({}));
+			return control;
+		};
+		/** A retained node is only as current as the observation that produced it. */
+		const retained = (target, ticket, operation, allowSuspended = false, attached = true) => {
+			ticket.check();
+			const stale = () => fail(operation, Reasons.Stale.make({}));
+			const current = snapshot;
+			if (current === void 0 || current.id !== target.observationId) throw stale();
+			const node = current.nodes.get(target.elementId);
+			if (node === void 0) throw stale();
+			if (current.validity === "invalid" || current.generation !== ticket.generation) throw stale();
+			const page = pages.get(current.pageId);
+			if (page === void 0 || page.closed || page.epoch !== current.epoch) throw stale();
+			if (selectedId !== current.pageId) throw stale();
+			if (current.validity === "suspended" && !allowSuspended && !current.revalidated.has(target.elementId)) throw stale();
+			if (attached && !page.document.controls.includes(node)) throw stale();
+			return {
+				node,
+				page,
+				snapshot: current
+			};
+		};
+		const resolve = (target, ticket, operation, policy, browserTarget, allowSuspended = false, enablement = false) => {
+			let node;
+			let page;
+			if (typeof target === "string") {
+				page = current(browserTarget, operation);
+				node = bySelector(page, target, operation);
+			} else ({node, page} = retained(target, ticket, operation, allowSuspended));
+			const fresh = facts(node);
+			if (enablement && node.script.disabled === true) throw fail(operation, Reasons.Disabled.make({}));
+			if (policy !== void 0) {
+				let admitted = false;
+				try {
+					admitted = policy(fresh) === true;
+				} catch {
+					admitted = false;
+				}
+				if (!admitted) throw fail(operation, Reasons.Denied.make({}));
+			}
+			ticket.check();
+			return {
+				node,
+				page,
+				facts: fresh
+			};
+		};
+		const requireRunning = (page, operation) => {
+			if (page.held !== void 0) throw fail(operation, Reasons.Busy.make({}));
+		};
+		const heldObservation = (pageId) => {
+			if (snapshot?.pageId === pageId && snapshot.validity === "valid") {
+				snapshot.validity = "suspended";
+				snapshot.revalidated.clear();
+			}
+		};
+		const activate = (page, node) => {
+			const { script: value } = node;
+			page.focused = value.id;
+			if (value.kind === "input" && value.inputType === "checkbox") node.checked = !node.checked;
+			if (value.kind === "input" && value.inputType === "radio") node.checked = true;
+			const target = value.destination ?? value.activates;
+			if (target !== void 0) commit(page, documentFor(target));
+			return page.document.url;
+		};
+		const focusedOrRefuse = (into, ticket, operation, policy, browserTarget) => {
+			if (into === void 0) return current(browserTarget, operation);
+			const { node, page } = resolve(into, ticket, operation, policy, browserTarget);
+			if (page.focused !== node.script.id) throw fail(operation, Reasons.NotFocused.make({}));
+			return page;
+		};
+		const typed = (page, text) => {
+			const focused = page.focused === void 0 ? void 0 : page.document.controls.find((control) => control.script.id === page.focused);
+			if (focused !== void 0 && isEditable(focused.script)) page.values.set(focused.script.id, (page.values.get(focused.script.id) ?? "") + text);
+		};
+		/** Issued options of one select, refused exactly where native selection refuses them. */
+		const chosen = (node, ids, operation) => {
+			const current = snapshot;
+			if (current === void 0) throw fail(operation, Reasons.Stale.make({}));
+			if (!isSelectable(node.script.kind)) throw fail(operation, Reasons.Unsupported.make({}));
+			const options = ids.map((id) => {
+				const option = current.nodes.get(id);
+				if (option === void 0 || option.script.selectElementId !== node.script.id) throw fail(operation, Reasons.Stale.make({}));
+				return option;
+			});
+			if (node.script.disabled === true || options.some((option) => option.script.disabled === true)) throw fail(operation, Reasons.Disabled.make({}));
+			if (node.script.multiple !== true && options.length > 1) throw fail(operation, Reasons.Unsupported.make({}));
+			return options;
+		};
+		const choose = (page, node, options) => {
+			if (node.script.multiple !== true) {
+				for (const candidate of page.document.controls) if (candidate.script.selectElementId === node.script.id) candidate.selected = false;
+			}
+			for (const option of options) option.selected = true;
+			page.focused = node.script.id;
+		};
+		/** A control's private state after a form step. It is compared here and never returned. */
+		const fieldState = (page, node) => {
+			const { script: value } = node;
+			if (node.checked !== void 0) return JSON.stringify(["checked", node.checked]);
+			if (value.kind === "select") return JSON.stringify(["options", page.document.controls.filter((option) => option.script.selectElementId === value.id && option.selected).map((option) => option.script.id)]);
+			if (value.kind === "input" || value.kind === "textarea" || value.facts?.editable === true) return JSON.stringify(["value", page.values.get(value.id) ?? ""]);
+			return JSON.stringify(["other"]);
+		};
+		/** One form step, as the real driver takes it; see `Driver["formStep"]`. */
+		const formStep = (page, node, field, ticket, record) => {
+			const epoch = page.epoch;
+			let act;
+			if (field.options !== void 0) {
+				const options = chosen(node, field.options, "fill-form");
+				act = () => choose(page, node, options);
+			} else if (field.checked !== void 0) {
+				if (node.checked === void 0) throw fail("fill-form", Reasons.Unsupported.make({}));
+				if (node.checked !== field.checked) {
+					if (!field.checked && node.script.inputType === "radio") throw fail("fill-form", Reasons.Unsupported.make({}));
+					act = () => {
+						activate(page, node);
+					};
+				}
+			} else {
+				const text = field.value ?? "";
+				const refusal = textRefusal(node.script, text);
+				if (refusal !== void 0) throw fail("fill-form", refusal);
+				act = () => {
+					page.values.set(node.script.id, text);
+					page.focused = void 0;
+				};
+			}
+			if (act !== void 0) {
+				dispatch(ticket, record);
+				act();
+			}
+			const state = page.epoch === epoch && !page.closed && page.document.controls.includes(node) ? fieldState(page, node) : void 0;
+			return {
+				status: act === void 0 ? "unchanged" : "set",
+				reached: field.checked === void 0 || state === void 0 || state === JSON.stringify(["checked", field.checked]),
+				state,
+				url: page.document.url
+			};
+		};
+		const inFlight = (page, url, outcome, timeoutMillis, record) => new Promise((resolve, reject) => {
+			let done = false;
+			const timer = timers.sleep(timeoutMillis);
+			const finish = (settle) => {
+				if (done) return;
+				done = true;
+				timer.cancel();
+				if (page.navigation === flight) page.navigation = void 0;
+				settle();
+			};
+			const failed = (reason) => finish(() => {
+				record.settled = "failed";
+				reject(fail("navigate", reason, "unknown"));
+			});
+			const flight = {
+				stop: () => failed(Reasons.Interrupted.make({})),
+				drop: () => failed(Reasons.Disconnected.make({})),
+				by: connection
+			};
+			page.navigation = flight;
+			timer.done.then(() => failed(Reasons.Timeout.make({})), () => {});
+			switch (outcome._tag) {
+				case "Fail":
+					failed(outcome.reason);
+					return;
+				case "Disconnect":
+					dropConnection(true);
+					return;
+				case "Hold": {
+					const gate = internalGate(outcome.gate);
+					gate.reach();
+					gate.opened.then(() => finish(() => {
+						commit(page, documentFor(url));
+						resolve(url);
+					}));
+				}
+			}
+		});
+		const waitUntil = (ticket, page, operation, record, satisfied, detached) => new Promise((resolve, reject) => {
+			const cleanup = () => {
+				page.watchers.delete(check);
+				ticket.signal.removeEventListener("abort", onAbort);
+				ticket.retire();
+			};
+			const onAbort = () => {
+				cleanup();
+				record.settled = "failed";
+				reject(aborted(ticket, operation));
+			};
+			const check = () => {
+				try {
+					ticket.check();
+					if (disconnected) throw fail(operation, Reasons.Disconnected.make({}));
+					if (detached()) throw fail(operation, Reasons.Stale.make({}));
+					if (!satisfied()) return;
+					cleanup();
+					resolve();
+				} catch (error) {
+					cleanup();
+					record.settled = "failed";
+					reject(error);
+				}
+			};
+			if (ticket.signal.aborted) {
+				onAbort();
+				return;
+			}
+			ticket.signal.addEventListener("abort", onAbort, { once: true });
+			page.watchers.add(check);
+			check();
+		});
+		const invokeBinding = async (name, input, origin) => {
+			const binding = bindings.find((candidate) => candidate.name === name);
+			if (binding === void 0) return { ok: false };
+			const page = selectedId === void 0 ? void 0 : pages.get(selectedId);
+			const epoch = page?.epoch;
+			const documentOrigin = origin ?? (page === void 0 ? "null" : originOf(page.document.url));
+			const text = JSON.stringify(input) ?? "null";
+			const error = (reason) => InitializationError.make({
+				operation: "callback",
+				step: name,
+				reason
+			});
+			const check = async (signal) => {
+				if (disconnected || signal.aborted) throw error("closed");
+				if (page === void 0 || page.closed || page.epoch !== epoch) throw error("stale");
+				if (!binding.origins.includes(documentOrigin)) throw error("origin");
+			};
+			try {
+				const reply = await binding.invoke({
+					read: async (signal) => {
+						await check(signal);
+						return text;
+					},
+					check,
+					dispose: async () => {}
+				});
+				return {
+					ok: true,
+					output: JSON.parse(reply)
+				};
+			} catch {
+				return { ok: false };
+			}
+		};
+		if (pages.size === 0) {
+			const startUrl = script.start ?? script.documents[0]?.url ?? "https://scripted.invalid/";
+			const first = createPage(documentFor(startUrl), true);
+			select(first.pageId);
+			if (options.initialTargetId !== void 0 && options.initialTargetId !== first.targetId) throw fail("connect", Reasons.NotFound.make({}));
+			if (options.newPage === true) select(createPage(state({
+				url: startUrl,
+				text: ""
+			}), false).pageId);
+		} else if (options.initialTargetId !== void 0) {
+			const target = openPages().find((page) => page.targetId === options.initialTargetId);
+			if (target === void 0) throw fail("connect", Reasons.NotFound.make({}));
+			select(target.pageId);
+		} else if (options.newPage === true) select(createPage(state({
+			url: "https://scripted.invalid/blank",
+			text: ""
+		}), false).pageId);
+		else {
+			const previous = lastSelected === void 0 ? void 0 : pages.get(lastSelected);
+			select(previous !== void 0 && !previous.closed ? previous.pageId : openPages()[0]?.pageId);
+		}
+		const driver = {
+			...options.pageControl === true ? { pageControl: {
+				state: async (page, ticket) => {
+					ticket.check();
+					const target = pageOf(page, "page-control");
+					return PageExecutionState.make({
+						pageId: target.pageId,
+						targetId: target.targetId,
+						state: target.held === void 0 ? "running" : "suspended",
+						...target.held === void 0 ? {} : { suspensionId: target.held.suspensionId }
+					});
+				},
+				suspend: (page, ticket) => attempt("page-suspend", ticket, { pageId: page.pageId }, async (record) => {
+					const target = pageOf(page, "page-suspend");
+					requireRunning(target, "page-suspend");
+					dispatch(ticket, record);
+					target.held = {
+						suspensionId: `suspension-${++suspensionSerial}`,
+						by: connection
+					};
+					heldObservation(target.pageId);
+					return PageSuspension.make({
+						pageId: target.pageId,
+						targetId: target.targetId,
+						suspensionId: target.held.suspensionId
+					});
+				}),
+				resume: (receipt, ticket) => attempt("page-resume", ticket, { pageId: receipt.pageId }, async (record) => {
+					const target = pages.get(receipt.pageId);
+					if (target === void 0 || target.closed || target.held === void 0 || target.targetId !== receipt.targetId || target.held.suspensionId !== receipt.suspensionId) throw fail("page-resume", Reasons.Stale.make({}));
+					dispatch(ticket, record);
+					target.held = void 0;
+					heldObservation(target.pageId);
+				}),
+				checkTarget: async (target, ticket) => {
+					ticket.check();
+					requireRunning(current(target, "page-control"), "page-control");
+				}
+			} } : {},
+			selected: () => {
+				const page = selectedPage();
+				return {
+					pageId: page.pageId,
+					frameId: page.frameId
+				};
+			},
+			selectedTargetId: async () => selectedPage().targetId,
+			listPages: (ticket) => attempt("list-pages", ticket, {}, async () => openPages().map(info)),
+			resolvePage: async (page, ticket) => {
+				ticket.check();
+				const target = pageOf(page, "target");
+				return {
+					pageId: target.pageId,
+					frameId: target.frameId
+				};
+			},
+			selectPage: (page, ticket) => attempt("select-page", ticket, { pageId: page.pageId }, async () => {
+				const target = pageOf(page, "select-page");
+				select(target.pageId);
+				events.invalidate("target-changed", "none");
+			}),
+			newPage: (ticket) => attempt("new-page", ticket, {}, async (record) => {
+				if (openPages().length >= options.maxPages) throw fail("new-page", Reasons.Limit.make({
+					dimension: "pages",
+					maximum: options.maxPages,
+					observed: openPages().length
+				}));
+				dispatch(ticket, record);
+				return info(createPage(state({
+					url: "https://scripted.invalid/blank",
+					text: ""
+				}), false));
+			}),
+			closePage: (page, ticket) => attempt("close-page", ticket, { pageId: page.pageId }, async (record) => {
+				const target = pageOf(page, "close-page");
+				dispatch(ticket, record);
+				target.closed = true;
+				target.navigation?.drop();
+				target.capture?.start.invalidate("target-changed");
+				target.capture = void 0;
+				notify(target);
+				if (selectedId === target.pageId) select(void 0);
+				invalidateSnapshot({ pageId: target.pageId });
+				events.invalidate("target-changed", { pageId: target.pageId });
+				for (const other of live) {
+					if (other === connection) continue;
+					other.retire(target.pageId);
+					other.announce(target.pageId);
+				}
+			}),
+			listFrames: (ticket, page) => attempt("list-frames", ticket, {}, async () => [frameInfo(page === void 0 ? selectedPage("list-frames") : pageOf(page, "list-frames"))]),
+			resolveFrame: async (page, frame, ticket) => {
+				ticket.check();
+				const target = pageOf(page, "target");
+				if (frame.frameId !== target.frameId) throw fail("target", Reasons.NotFound.make({}));
+				return {
+					pageId: target.pageId,
+					frameId: target.frameId
+				};
+			},
+			selectFrame: (id, ticket) => attempt("select-frame", ticket, {}, async () => {
+				if (id !== selectedPage("select-frame").frameId) throw fail("select-frame", Reasons.NotFound.make({}));
+				events.invalidate("target-changed", "none");
+			}),
+			beginNavigation: (url, timeoutMillis, ticket, target) => attempt("navigate", void 0, { pageId: target?.pageId }, async (record) => {
+				ticket.check();
+				const page = current(target, "navigate");
+				requireRunning(page, "navigate");
+				const outcome = take("navigate");
+				if (outcome?._tag === "Fail" && outcome.outcome !== "unknown") throw fail("navigate", outcome.reason, outcome.outcome);
+				if (outcome?._tag === "Hold" && !outcome.dispatched) {
+					await hold(outcome.gate, ticket, "navigate", record);
+					ticket.check();
+				}
+				if (outcome?._tag === "Disconnect" && outcome.dispatched !== true) {
+					dropConnection(true);
+					throw fail("navigate", Reasons.Disconnected.make({}));
+				}
+				dispatch(ticket, record);
+				page.navigation?.stop();
+				const inFlightOutcome = outcome === void 0 || outcome._tag === "Hold" && !outcome.dispatched ? void 0 : outcome;
+				let settled;
+				if (inFlightOutcome === void 0) {
+					commit(page, documentFor(url));
+					settled = Promise.resolve(url);
+				} else {
+					settled = inFlight(page, url, inFlightOutcome, timeoutMillis, record);
+					settled.catch(() => {});
+				}
+				return {
+					pageId: page.pageId,
+					mainFrame: true,
+					settled,
+					stop: (stopTicket, pending, onDispatch) => attempt("navigate-stop", void 0, { pageId: page.pageId }, async (stopRecord) => {
+						stopTicket.check();
+						const armedStop = take("navigate-stop");
+						if (armedStop?._tag === "Hold" && !armedStop.dispatched) {
+							await hold(armedStop.gate, stopTicket, "navigate-stop", stopRecord);
+							stopTicket.check();
+						}
+						if (!pending()) return "settled";
+						if (armedStop?._tag === "Fail" && armedStop.outcome !== "unknown") throw fail("navigate-stop", armedStop.reason, armedStop.outcome);
+						if (armedStop?._tag === "Disconnect" && armedStop.dispatched !== true) {
+							dropConnection(true);
+							throw fail("navigate-stop", Reasons.Disconnected.make({}));
+						}
+						dispatch(stopTicket, stopRecord);
+						onDispatch();
+						switch (armedStop?._tag) {
+							case "Fail": throw fail("navigate-stop", armedStop.reason, "unknown");
+							case "Disconnect":
+								dropConnection(true);
+								throw fail("navigate-stop", Reasons.Disconnected.make({}), "unknown");
+							case "Hold":
+								if (armedStop.dispatched) {
+									await hold(armedStop.gate, stopTicket, "navigate-stop", stopRecord);
+									stopTicket.check();
+								}
+								break;
+							case void 0:
+						}
+						page.navigation?.stop();
+						return "dispatched";
+					})
+				};
+			}),
+			readText: (selector, maximumBytes, ticket, target) => attempt("read-text", ticket, {
+				pageId: target?.pageId,
+				...meta(selector)
+			}, async () => {
+				const page = current(target, "read-text");
+				if (selector === void 0) return bounded(page.document.text, maximumBytes).text;
+				const control = bySelector(page, selector, "read-text");
+				return bounded(control.script.text ?? control.script.label, maximumBytes).text;
+			}),
+			observe: (scope, maximumBytes, controls, ticket, match) => attempt("observe", ticket, {}, async () => {
+				const page = selectedPage("observe");
+				const needle = match?.toLowerCase();
+				const matches = (value) => needle === void 0 || value.toLowerCase().includes(needle);
+				snapshot = void 0;
+				const selects = new Set(page.document.controls.filter((control) => isSelectable(control.script.kind) && (matches(control.script.label) || page.document.controls.some((option) => option.script.selectElementId === control.script.id && matches(option.script.label)))).map((control) => control.script.id));
+				const matching = page.document.controls.filter((control) => control.script.selectElementId !== void 0 ? selects.has(control.script.selectElementId) : isSelectable(control.script.kind) ? selects.has(control.script.id) : matches(control.script.label));
+				const reachable = matching.filter((control) => scope === "document" || control.script.offscreen !== true);
+				const kept = reachable.slice(0, controls);
+				const text = bounded(needle === void 0 ? page.document.text : page.document.text.split("\n").map((line) => line.trim()).filter((line) => line !== "" && matches(line)).join("\n"), maximumBytes);
+				const next = {
+					id: `observation-${++observationSerial}`,
+					pageId: page.pageId,
+					epoch: page.epoch,
+					generation: ticket.generation,
+					validity: "valid",
+					nodes: new Map(kept.map((control) => [control.script.id, control])),
+					revalidated: /* @__PURE__ */ new Set()
+				};
+				snapshot = next;
+				return {
+					observationId: next.id,
+					scope,
+					...match === void 0 ? {} : { match },
+					url: page.document.url,
+					text: text.text,
+					textTruncated: text.truncated,
+					controls: kept.map(observed),
+					controlsTruncated: kept.length < reachable.length,
+					viewport: ViewportEvidence.make({
+						width: viewport.width,
+						height: viewport.height,
+						clippedText: 0,
+						coveredText: 0,
+						uncertainText: 0,
+						unreachableControls: matching.length - reachable.length,
+						exhausted: false
+					})
+				};
+			}),
+			checkpoint: (maximumBytes, controls, pictureBytes, ticket) => attempt("checkpoint", ticket, {}, async () => {
+				const page = selectedPage("checkpoint");
+				const text = bounded(page.document.text, maximumBytes);
+				const reachable = page.document.controls.filter((control) => control.script.offscreen !== true);
+				return {
+					url: page.document.url,
+					text: text.text,
+					textTruncated: text.truncated,
+					controls: reachable.slice(0, controls).map(facts),
+					controlsTruncated: reachable.length > controls,
+					viewport: ViewportEvidence.make({
+						width: viewport.width,
+						height: viewport.height,
+						clippedText: 0,
+						coveredText: 0,
+						uncertainText: 0,
+						unreachableControls: page.document.controls.length - reachable.length,
+						exhausted: false
+					}),
+					documentChanged: false,
+					...pictureBytes === void 0 ? {} : { picture: new Uint8Array(PNG) }
+				};
+			}),
+			controlFacts: (target, ticket) => attempt("control-facts", ticket, meta(target), async () => {
+				selectedPage("control-facts");
+				return resolve(target, ticket, "control-facts").facts;
+			}),
+			revalidate: (target, ticket) => attempt("revalidate", ticket, meta(target), async () => {
+				const { snapshot: current } = retained(target, ticket, "revalidate", true);
+				current.revalidated.add(target.elementId);
+			}),
+			click: (target, ticket, policy, browserTarget) => attempt("click", ticket, {
+				pageId: browserTarget?.pageId,
+				...meta(target)
+			}, async (record) => {
+				const { node, page } = resolve(target, ticket, "click", policy, browserTarget);
+				requireRunning(page, "click");
+				dispatch(ticket, record);
+				return activate(page, node);
+			}),
+			fill: (target, value, ticket, policy, browserTarget) => attempt("fill", ticket, {
+				pageId: browserTarget?.pageId,
+				...meta(target)
+			}, async (record) => {
+				const { node, page } = resolve(target, ticket, "fill", policy, browserTarget);
+				requireRunning(page, "fill");
+				const refusal = textRefusal(node.script, value);
+				if (refusal !== void 0) throw fail("fill", refusal);
+				dispatch(ticket, record);
+				page.focused = node.script.id;
+				page.values.set(node.script.id, value);
+				return page.document.url;
+			}),
+			selectOption: (target, ids, ticket, policy) => attempt("select-option", ticket, meta(target), async (record) => {
+				const { node, page } = resolve(target, ticket, "select-option", policy);
+				requireRunning(page, "select-option");
+				const options = chosen(node, ids, "select-option");
+				dispatch(ticket, record);
+				choose(page, node, options);
+				return page.document.url;
+			}),
+			formStep: (target, field, ticket, policy) => attempt("fill-form", ticket, meta(target), async (record) => {
+				const { node, page } = resolve(target, ticket, "fill-form", policy, void 0, false, true);
+				requireRunning(page, "fill-form");
+				return formStep(page, node, field, ticket, record);
+			}),
+			formState: (targets, ticket) => attempt("fill-form", ticket, {}, async () => targets.map((target) => {
+				const { node, page } = retained(target, ticket, "fill-form", false, false);
+				return page.document.controls.includes(node) ? fieldState(page, node) : void 0;
+			})),
+			formSubmit: (target, ticket, policy) => attempt("fill-form", ticket, meta(target), async (record) => {
+				const { node, page } = resolve(target, ticket, "fill-form", policy, void 0, false, true);
+				requireRunning(page, "fill-form");
+				dispatch(ticket, record);
+				return activate(page, node);
+			}),
+			scroll: (_deltaX, _deltaY, ticket, target) => attempt("scroll", ticket, { pageId: target?.pageId }, async (record) => {
+				const page = current(target, "scroll");
+				requireRunning(page, "scroll");
+				dispatch(ticket, record);
+				return page.document.url;
+			}),
+			pointerMove: (to, ticket, target) => attempt("pointer-move", ticket, { pageId: target?.pageId }, async (record) => {
+				const page = current(target, "pointer-move");
+				requireRunning(page, "pointer-move");
+				dispatch(ticket, record);
+				place(page.pageId, {
+					x: to.x,
+					y: to.y
+				});
+				return receipt(page.pageId);
+			}),
+			hover: (target, ticket, policy, browserTarget) => attempt("hover", ticket, {
+				pageId: browserTarget?.pageId,
+				...meta(target)
+			}, async (record) => {
+				const { node, page, facts: fresh } = resolve(target, ticket, "hover", policy, browserTarget);
+				requireRunning(page, "hover");
+				if (node.script.offscreen === true) throw fail("hover", Reasons.NotVisible.make({}));
+				dispatch(ticket, record);
+				place(page.pageId, {
+					x: fresh.box.x + fresh.box.width / 2,
+					y: fresh.box.y + fresh.box.height / 2
+				});
+				return receipt(page.pageId);
+			}),
+			wheel: (_deltaX, _deltaY, at, ticket, target) => attempt("wheel", ticket, { pageId: target?.pageId }, async (record) => {
+				const page = current(target, "wheel");
+				requireRunning(page, "wheel");
+				dispatch(ticket, record);
+				if (at !== void 0) place(page.pageId, {
+					x: at.x,
+					y: at.y
+				});
+				return receipt(page.pageId);
+			}),
+			press: (key, _modifiers, into, ticket, policy, browserTarget) => attempt("press", ticket, {
+				pageId: browserTarget?.pageId,
+				...meta(into)
+			}, async (record) => {
+				const page = focusedOrRefuse(into, ticket, "press", policy, browserTarget);
+				requireRunning(page, "press");
+				dispatch(ticket, record);
+				if (key.length === 1) typed(page, key);
+				return receipt(page.pageId);
+			}),
+			type: (text, into, ticket, policy, browserTarget) => attempt("type", ticket, {
+				pageId: browserTarget?.pageId,
+				...meta(into)
+			}, async (record) => {
+				const page = focusedOrRefuse(into, ticket, "type", policy, browserTarget);
+				requireRunning(page, "type");
+				dispatch(ticket, record);
+				typed(page, text);
+				return receipt(page.pageId);
+			}),
+			screenshot: (_fullPage, _maximumBytes, ticket, target) => attempt("screenshot", ticket, { pageId: target?.pageId }, async () => {
+				current(target, "screenshot");
+				return new Uint8Array(PNG);
+			}),
+			resize: (next, ticket) => attempt("resize", ticket, {}, async (record) => {
+				const page = selectedPage("resize");
+				dispatch(ticket, record);
+				viewport = {
+					width: next.width,
+					height: next.height
+				};
+				page.capture?.start.invalidate("resized");
+				events.invalidate("resized");
+			}),
+			waitFor: (selector, state, ticket, target) => attempt("wait", ticket, {
+				pageId: target.pageId,
+				selector
+			}, async (record) => {
+				const page = current(target, "wait");
+				const epoch = page.epoch;
+				const find = () => {
+					const id = selector.startsWith("#") ? selector.slice(1) : void 0;
+					return id === void 0 ? void 0 : page.document.controls.find((control) => control.script.id === id);
+				};
+				await waitUntil(ticket, page, "wait", record, () => {
+					const control = find();
+					const present = control !== void 0;
+					const visible = present && control.script.offscreen !== true;
+					switch (state) {
+						case "visible": return visible;
+						case "hidden": return !visible;
+						case "attached": return present;
+						case "detached": return !present;
+					}
+				}, () => page.closed || page.epoch !== epoch);
+			}).finally(() => ticket.retire()),
+			waitForElement: (reference, state, ticket, target) => attempt("wait", ticket, {
+				pageId: target.pageId,
+				elementId: reference.elementId
+			}, async (record) => {
+				const page = current(target, "wait");
+				const { node } = retained(reference, ticket, "wait", true);
+				const epoch = page.epoch;
+				await waitUntil(ticket, page, "wait", record, () => {
+					const present = page.document.controls.includes(node);
+					const visible = present && node.script.offscreen !== true;
+					switch (state) {
+						case "visible": return visible;
+						case "hidden": return !visible;
+						case "enabled": return present && node.script.disabled !== true;
+						case "disabled": return present && node.script.disabled === true;
+					}
+				}, () => page.closed || page.epoch !== epoch);
+			}).finally(() => ticket.retire()),
+			clickAndWait: (target, ticket) => attempt("click-and-wait", ticket, meta(target), async (record) => {
+				const { node, page } = resolve(target, ticket, "click-and-wait");
+				requireRunning(page, "click-and-wait");
+				dispatch(ticket, record);
+				return activate(page, node);
+			}),
+			clickForDownload: (target, ticket) => attempt("download-action", ticket, meta(target), async (record) => {
+				const { node, page } = resolve(target, ticket, "download-action");
+				requireRunning(page, "download-action");
+				if (node.script.download === void 0) throw fail("download-action", Reasons.Unsupported.make({}));
+				dispatch(ticket, record);
+				page.focused = node.script.id;
+				return {
+					downloadId: `download-${++downloadSerial}`,
+					filename: node.script.download,
+					state: "completed"
+				};
+			}),
+			selectFiles: (target, files, ticket) => attempt("select-files", ticket, meta(target), async (record) => selectFilesOn(target, files, ticket, record, "select-files")),
+			clickForFileSelection: (target, files, ticket) => attempt("file-chooser", ticket, meta(target), async (record) => selectFilesOn(target, files, ticket, record, "file-chooser")),
+			documentReadiness: async (ticket, target) => {
+				ticket.check();
+				const page = current(target, "ready");
+				const bootstrap = options.bootstrap;
+				if (bootstrap === void 0 || bootstrap.readiness.length === 0) return { _tag: "Ready" };
+				if (page.epoch <= page.registeredEpoch && bootstrap.existingDocuments === "RequireFreshNavigation") return { _tag: "RequiresNavigation" };
+				const origin = originOf(page.document.url);
+				return bootstrap.readiness.some((requirement) => requirement.origins === void 0 || requirement.origins.includes(origin)) ? { _tag: "Ready" } : { _tag: "NotApplicable" };
+			},
+			dismissDialogs: async () => {},
+			capture: async (target) => {
+				const page = target === void 0 ? selectedPage("capture") : pageOf(PageInfo.make({
+					pageId: target.pageId,
+					targetId: target.targetId,
+					url: "",
+					title: "",
+					selected: false
+				}), "capture");
+				return {
+					pageId: page.pageId,
+					targetId: page.targetId,
+					frameId: page.frameId,
+					source: {
+						start: async (start) => {
+							if (disconnected || page.closed) throw fail("capture-start", Reasons.Closed.make({}));
+							page.capture = {
+								start,
+								by: connection
+							};
+							start.opened?.(page.document.url);
+						},
+						stop: async () => {
+							page.capture = void 0;
+							const outcome = take("capture-stop");
+							if (outcome?._tag === "Fail") throw fail("capture-stop", outcome.reason, outcome.outcome);
+						}
+					}
+				};
+			},
+			invalidateObservation: (scope) => {
+				invalidateSnapshot(scope);
+			},
+			disconnect: async () => {
+				if (disconnected) return;
+				const outcome = take("disconnect");
+				if (outcome?._tag === "Hold") {
+					const gate = internalGate(outcome.gate);
+					gate.reach();
+					await gate.opened;
+				}
+				if (outcome?._tag === "Fail") {
+					dropConnection(false, "close-failed");
+					throw fail("disconnect", outcome.reason, outcome.outcome);
+				}
+				dropConnection(false, "closed");
+			}
+		};
+		const selectFilesOn = (target, files, ticket, record, operation) => {
+			const { node, page } = resolve(target, ticket, operation);
+			requireRunning(page, operation);
+			if (node.script.kind !== "input" || node.script.inputType !== "file") throw fail(operation, Reasons.Unsupported.make({}));
+			dispatch(ticket, record);
+			page.files.set(node.script.id, files.map((file) => file._tag === "Inline" ? file.name : file.path));
+			return page.document.url;
+		};
+		const connection = {
+			retire: (pageId) => invalidateSnapshot({ pageId }),
+			announce: (pageId) => events.invalidate("target-changed", { pageId }),
+			drop: () => dropConnection(true),
+			invoke: invokeBinding,
+			pointer: () => pointer,
+			viewport: () => viewport
+		};
+		index = connections.push("open") - 1;
+		live.add(connection);
+		latest = connection;
+		return driver;
+	};
+	const toScript = (document) => ({
+		url: document.url,
+		title: document.title,
+		text: document.text,
+		controls: document.controls.map((control) => ({
+			...control.script,
+			...control.checked === void 0 ? {} : { checked: control.checked },
+			...control.selected === void 0 ? {} : { selected: control.selected }
+		}))
+	});
+	/** The page last selected by any connection; it stays reachable while no connection is open. */
+	const selectedOrClosed = Effect.suspend(() => {
+		const page = lastSelected === void 0 ? void 0 : pages.get(lastSelected);
+		return page === void 0 || page.closed ? Effect.fail(fail("target", Reasons.Closed.make({}))) : Effect.succeed(page);
+	});
+	return {
+		connect,
+		control: {
+			calls: Effect.sync(() => calls.map((call) => Object.freeze({ ...call }))),
+			next: (operation, outcome) => Effect.sync(() => {
+				const queue = armed.get(operation) ?? [];
+				queue.push(outcome);
+				armed.set(operation, queue);
+			}),
+			gate: makeGate,
+			document: {
+				current: selectedOrClosed.pipe(Effect.map((page) => toScript(page.document))),
+				replace: (next) => checked(DocumentScript, next, "configure").pipe(Effect.flatMap((document) => selectedOrClosed.pipe(Effect.map((page) => {
+					page.navigation?.stop();
+					commit(page, state(document));
+				})))),
+				update: (next) => checked(DocumentScript, next, "configure").pipe(Effect.flatMap((document) => selectedOrClosed.pipe(Effect.map((page) => {
+					update(page, document);
+				})))),
+				values: Effect.sync(() => lastSelected === void 0 ? /* @__PURE__ */ new Map() : new Map(pages.get(lastSelected)?.values ?? [])),
+				files: Effect.sync(() => lastSelected === void 0 ? /* @__PURE__ */ new Map() : new Map(pages.get(lastSelected)?.files ?? []))
+			},
+			pointer: Effect.sync(() => latest?.pointer() ?? null),
+			capture: { emit: (frame = {}) => selectedOrClosed.pipe(Effect.flatMap((page) => {
+				const running = page.capture?.start;
+				if (running === void 0) return Effect.fail(fail("capture-consume", Reasons.NotFound.make({})));
+				const timestamp = frame.timestamp ?? lastTimestamp + 40;
+				const viewport = page.capture?.by.viewport() ?? {
+					width: 0,
+					height: 0
+				};
+				lastTimestamp = Math.max(lastTimestamp, timestamp);
+				return Effect.sync(() => {
+					running.receive({
+						data: frame.bytes ?? jpegFrame(),
+						timestamp,
+						viewportWidth: frame.viewportWidth ?? viewport.width,
+						viewportHeight: frame.viewportHeight ?? viewport.height
+					});
+				});
+			})) },
+			invoke: (name, input, invokeOptions) => Effect.promise(() => {
+				const open = [...live].at(-1);
+				return open === void 0 ? Promise.resolve({ ok: false }) : open.invoke(name, input, invokeOptions?.origin);
+			}),
+			disconnect: Effect.sync(() => {
+				for (const connection of [...live]) connection.drop();
+			}),
+			connections: Effect.sync(() => [...connections])
+		}
+	};
+};
+//#endregion
+//#region src/internal/testing/Lifetime.ts
+/**
+* A lifetime with nothing outside the connection: no process to terminate and no provider to
+* release. Cleanup runs the same local steps an owned Chromium runs, each settling on its own,
+* and reports the same kind of receipt.
+*/
+const scriptedSource = (reference, onCleanup) => (local) => Effect.gen(function* () {
+	let latest;
+	let closing = false;
+	const close = yield* Effect.cached(Effect.uninterruptible(Effect.gen(function* () {
+		const issues = [];
+		const step = (name, action) => cleanupStep(action, 3e3).pipe(Effect.tap((result) => Effect.sync(() => {
+			if (result._tag === "Failure") issues.push(ScriptedCleanupIssue.make({
+				step: name,
+				reason: result.reason
+			}));
+		})));
+		yield* step("fence", local.fence);
+		yield* step("capture", local.capture);
+		yield* step("initialization", local.initialization);
+		const disconnected = yield* step("disconnect", local.disconnect);
+		const result = ScriptedCleanupResult.make({
+			reference,
+			connection: disconnected._tag === "Success" ? disconnected.value : "failed",
+			issues
+		});
+		Object.freeze(result.issues);
+		latest = Object.freeze(result);
+		return latest;
+	})));
+	const release = yield* Effect.cached(Effect.gen(function* () {
+		closing = true;
+		const result = yield* close;
+		if (onCleanup !== void 0) yield* reported(Effect.suspend(() => onCleanup(result)));
+		return result;
+	}).pipe(Effect.uninterruptible));
+	yield* Effect.addFinalizer(() => release.pipe(Effect.asVoid));
+	return {
+		reference,
+		connection: () => Effect.suspend(() => closing ? Effect.fail(BrowserError.make({
+			operation: "connect",
+			reason: Reasons.Closed.make({}),
+			outcome: "undispatched"
+		})) : Effect.succeed(Redacted.make(`scripted://${reference.id}`))),
+		release,
+		closeChecked: release.pipe(Effect.filterOrFail((result) => result.connection === "closed" && result.issues.length === 0, () => BrowserError.make({
+			operation: "close",
+			reason: Reasons.Failed.make({}),
+			outcome: "unknown"
+		}))),
+		cleanupResult: Effect.sync(() => Option.fromNullishOr(latest)),
+		controlRetired: Effect.sync(() => latest !== void 0 && latest.connection === "closed")
+	};
+});
+//#endregion
+//#region src/Testing.ts
+let references = 0;
+const makeEngine = Effect.fnUntraced(function* (script) {
+	const context = yield* Effect.context();
+	const browsers = /* @__PURE__ */ new Map();
+	const timers = { sleep: (millis) => {
+		const controller = new AbortController();
+		const done = Effect.runPromiseWith(context)(Effect.sleep(millis), { signal: controller.signal });
+		done.catch(() => {});
+		return {
+			done,
+			cancel: () => controller.abort()
+		};
+	} };
+	const attempt = async (request) => {
+		const address = Redacted.isRedacted(request.connection) ? String(Redacted.value(request.connection)) : String(request.connection);
+		let browser = browsers.get(address);
+		if (browser === void 0) {
+			browser = makeScriptedBrowser(script, timers);
+			browsers.set(address, browser);
+		}
+		return browser.connect(request.options, request.events);
+	};
+	return {
+		binding: issueBinding({ _tag: "BrowserBinding" }, fromNativeAttempt(attempt)),
+		controls: () => [...browsers.values()].map((browser) => browser.control)
+	};
+});
+/**
+* Open one scripted browser in the caller's Scope. The session is the real owner over a
+* scripted native engine: admission, budgets, staleness, dispatch evidence, capture, page holds
+* and typed callbacks are the production code paths. Only the page and its outcomes are scripted,
+* and the owner's ids and handoff tokens come from `sequentialCrypto`.
+*/
+const open = Effect.fnUntraced(function* (script, options = {}) {
+	const fixed = yield* checked(Script, script, "configure");
+	const policy = yield* checked(BrowserPolicy, options.policy ?? BrowserPolicy.unrestricted(), "configure");
+	const engine = yield* makeEngine(fixed);
+	const runtime = yield* make({
+		implementation: "scripted",
+		binding: engine.binding,
+		...options.automation === void 0 ? {} : { automation: options.automation },
+		...options.viewport === void 0 ? {} : { viewport: options.viewport }
+	}).pipe(Effect.provide(sequentialCrypto));
+	const reference = Object.freeze(ScriptedReference.make({
+		provider: "scripted",
+		id: `scripted-${++references}`
+	}));
+	const acquired = yield* runtime.acquire(policy, scriptedSource(reference, options.onCleanup), options.bootstrap === void 0 ? {} : { bootstrap: options.bootstrap });
+	const connection = yield* acquired.connect;
+	const control = engine.controls().at(-1);
+	if (control === void 0) return yield* BrowserError.make({
+		operation: "connect",
+		reason: Reasons.Provider.make({}),
+		outcome: "unknown"
+	});
+	return Object.assign(connection.session, {
+		reference,
+		control,
+		closeChecked: connection.session.closeChecked.pipe(Effect.andThen(acquired.lifetime.closeChecked)),
+		close: acquired.close,
+		cleanupResult: acquired.lifetime.cleanupResult
+	});
+});
+/**
+* The `Crypto` scripted browsers draw their ids and handoff tokens from. Its bytes count up from
+* one on each build, so every value is predictable; it is not random and computes no digest.
+* `open` uses it already. A provider Layer built over `binding` still requires a `Crypto`, and
+* this one keeps such a test free of a platform package.
+*/
+const sequentialCrypto = Layer.sync(Crypto.Crypto, makeSequentialCrypto);
+/**
+* The same engine for a provider Layer built on `browser-runtime`, such as
+* `BrowserbaseBrowser.layer` with `BrowserBinding.layer(binding)`. Each address the Layer
+* connects to is one browser with one control handle; reconnecting to it finds its pages.
+*/
+const binding = Effect.fnUntraced(function* (script) {
+	const fixed = yield* checked(Script, script, "configure");
+	const engine = yield* makeEngine(fixed);
+	return {
+		binding: engine.binding,
+		browsers: Effect.sync(engine.controls)
+	};
+});
+/** A valid 64×48 JPEG: the default bytes of a scripted capture frame, for a caller's own frames. */
+const jpeg = jpegFrame;
+//#endregion
+export { ControlFactsScript, ControlScript, DocumentScript, Script, ScriptableOperation, ScriptedCleanupIssue, ScriptedCleanupResult, ScriptedReference, binding, jpeg, open, sequentialCrypto };
+
+//# sourceMappingURL=Testing.mjs.map