@orkestrel/browser 0.0.18 → 0.0.19

package/dist/src/browser/index.js

@@ -0,0 +1,1640 @@
+import { attempt, isInteger, isObject, isString } from "@orkestrel/contract";
+import { BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_INTERACTIVE_ROLES, BROWSER_OUTLINE_LIMIT, BROWSER_REFERENCE_PREFIX, BROWSER_RESULT_LIMIT, BrowserConnectionError, BrowserElementError, BrowserError, BrowserResultLimitError, BrowserToolset, BrowserTransition, createBrowserReading, filterBrowserOutline, normalizeBrowserName, parseBrowserReference, renderBrowserOutline, validateBrowserTimeout } from "../core/index.js";
+import { Emitter } from "@orkestrel/emitter";
+//#region src/browser/constants.ts
+/**
+* Sets the default `wait` deadline for DOM waits in a browser document toolset, `5_000`
+* milliseconds.
+*/
+var BROWSER_DOCUMENT_TIMEOUT_MS = 5e3;
+/**
+* Maps an HTML element to the ARIA role the HTML Accessibility API Mappings specification gives
+* it when it carries no `role` attribute.
+*
+* @remarks
+* A key is a lowercase element name, or `input:` followed by the input's `type` state. An element
+* whose mapping depends on more than its name — `a` and `area` without `href`, `select` with
+* `multiple` or a `size` above 1, an `img` with an empty `alt`, a scoped `header` or `footer`, a
+* `section` or `form` without an accessible name, and a text input with a `list` — is resolved
+* by `computeBrowserRole` before this table is read. An element or input state the mapping gives
+* no role has no entry.
+*/
+var BROWSER_IMPLICIT_ROLES = Object.freeze(/* @__PURE__ */ new Map([
+	["a", "link"],
+	["area", "link"],
+	["article", "article"],
+	["aside", "complementary"],
+	["blockquote", "blockquote"],
+	["button", "button"],
+	["caption", "caption"],
+	["code", "code"],
+	["datalist", "listbox"],
+	["dd", "definition"],
+	["del", "deletion"],
+	["details", "group"],
+	["dfn", "term"],
+	["dialog", "dialog"],
+	["dt", "term"],
+	["em", "emphasis"],
+	["fieldset", "group"],
+	["figure", "figure"],
+	["footer", "contentinfo"],
+	["form", "form"],
+	["h1", "heading"],
+	["h2", "heading"],
+	["h3", "heading"],
+	["h4", "heading"],
+	["h5", "heading"],
+	["h6", "heading"],
+	["header", "banner"],
+	["hr", "separator"],
+	["html", "document"],
+	["img", "img"],
+	["ins", "insertion"],
+	["li", "listitem"],
+	["main", "main"],
+	["math", "math"],
+	["menu", "list"],
+	["meter", "meter"],
+	["nav", "navigation"],
+	["ol", "list"],
+	["optgroup", "group"],
+	["option", "option"],
+	["output", "status"],
+	["p", "paragraph"],
+	["progress", "progressbar"],
+	["search", "search"],
+	["section", "region"],
+	["select", "combobox"],
+	["strong", "strong"],
+	["sub", "subscript"],
+	["sup", "superscript"],
+	["table", "table"],
+	["tbody", "rowgroup"],
+	["td", "cell"],
+	["textarea", "textbox"],
+	["tfoot", "rowgroup"],
+	["th", "columnheader"],
+	["thead", "rowgroup"],
+	["time", "time"],
+	["tr", "row"],
+	["ul", "list"],
+	["input:button", "button"],
+	["input:checkbox", "checkbox"],
+	["input:email", "textbox"],
+	["input:image", "button"],
+	["input:number", "spinbutton"],
+	["input:password", "textbox"],
+	["input:radio", "radio"],
+	["input:range", "slider"],
+	["input:reset", "button"],
+	["input:search", "searchbox"],
+	["input:submit", "button"],
+	["input:tel", "textbox"],
+	["input:text", "textbox"],
+	["input:url", "textbox"]
+]));
+/**
+* Names the ARIA roles whose accessible name the accessible-name computation takes from the
+* element's content when no attribute or label names it.
+*/
+var BROWSER_CONTENT_NAMED_ROLES = Object.freeze(/* @__PURE__ */ new Set([
+	"button",
+	"cell",
+	"checkbox",
+	"columnheader",
+	"gridcell",
+	"heading",
+	"link",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"option",
+	"radio",
+	"row",
+	"rowheader",
+	"switch",
+	"tab",
+	"tooltip",
+	"treeitem"
+]));
+/**
+* Names the link and form targets that navigate the current browsing context or one of its
+* ancestors. `_blank` opens another browsing context, and any other name targets the browsing
+* context carrying that name, which `matchesBrowserPopup` resolves.
+*/
+var BROWSER_CONTEXT_TARGETS = Object.freeze(/* @__PURE__ */ new Set([
+	"",
+	"_self",
+	"_parent",
+	"_top"
+]));
+/** Names the `input` type states whose value an untrusted `fill` sets as typed text. */
+var BROWSER_TYPED_INPUTS = Object.freeze(/* @__PURE__ */ new Set([
+	"date",
+	"datetime-local",
+	"email",
+	"month",
+	"number",
+	"password",
+	"search",
+	"tel",
+	"text",
+	"time",
+	"url",
+	"week"
+]));
+/**
+* Selects the HTML interactive content a click inside a `label` can land on without activating
+* the label, as the HTML interactive-content category lists it: `a` with `href`, `audio` and
+* `video` with `controls`, `button`, `details`, `embed`, `iframe`, `img` with `usemap` or
+* `controls`, `input` other than `hidden`, `label`, `select`, and `textarea`.
+*/
+var BROWSER_INTERACTIVE_CONTENT = "a[href], audio[controls], button, details, embed, iframe, img[usemap], img[controls], input:not([type=\"hidden\" i]), label, select, textarea, video[controls]";
+//#endregion
+//#region src/browser/helpers.ts
+/**
+* Narrows a value to a `Document` attached to a window.
+*
+* @param value - The value to test
+* @returns `true` for an object that is a `Document` with a `defaultView`, otherwise `false`
+*/
+function isBrowserDocument(value) {
+	return isObject(value) && Reflect.get(value, "nodeType") === 9 && isObject(Reflect.get(value, "defaultView"));
+}
+/**
+* Reads the URL, title, and serialized markup a DOM reading is built from, refusing a capture
+* over the result limit before any parse.
+*
+* @remarks
+* The measure is the length of `JSON.stringify({ url, title, html })`, the form the CDP capture
+* guard compares with `BROWSER_RESULT_LIMIT`, so a character JSON escapes counts as its escape
+* sequence. A reading a caller builds with `createBrowserReading` passes through no limit.
+*
+* @param node - The element whose `outerHTML` is captured; its owner document supplies `URL`
+* and `title`
+* @returns The capture's `url`, `title`, and `html`
+* @throws Thrown as a `BrowserResultLimitError` when the serialized capture is longer than
+* `BROWSER_RESULT_LIMIT` characters, with `length` and `limit` in its context.
+*/
+function readBrowserCapture(node) {
+	const document = node.ownerDocument;
+	const capture = {
+		url: document.URL,
+		title: document.title,
+		html: node.outerHTML
+	};
+	const length = JSON.stringify(capture).length;
+	if (length > BROWSER_RESULT_LIMIT) throw new BrowserResultLimitError("Document capture exceeds BROWSER_RESULT_LIMIT", {
+		length,
+		limit: BROWSER_RESULT_LIMIT
+	});
+	return capture;
+}
+/**
+* Computes the ARIA role of an element from its `role` attribute or its implicit mapping.
+*
+* @remarks
+* The explicit role is the first token of the `role` attribute, with `presentation` folded into
+* its synonym `none`. Without one, the role follows the HTML Accessibility API Mappings
+* specification through `BROWSER_IMPLICIT_ROLES`, after the element-specific conditions that
+* table cannot express: a link needs `href`, a `select` with `multiple` or a `size` above 1 is a
+* `listbox`, an `img` with an empty `alt` is `none`, a `header` or `footer` inside sectioning
+* content has no landmark role, a `section` or `form` needs an accessible name, a text input with
+* a `list` is a `combobox`, and a `th` with `scope="row"` is a `rowheader`.
+*
+* @param element - The element to classify
+* @returns The role, or `undefined` when the element maps to no role
+*
+* @example
+* ```ts
+* const input = document.createElement('input')
+* input.type = 'checkbox'
+* computeBrowserRole(input) // 'checkbox'
+* ```
+*/
+function computeBrowserRole(element) {
+	const explicit = (element.getAttribute("role") ?? "").trim().toLowerCase().split(/\s+/)[0] ?? "";
+	if (explicit !== "") return explicit === "presentation" ? "none" : explicit;
+	const tag = element.localName;
+	if (tag === "a" || tag === "area") return element.hasAttribute("href") ? "link" : void 0;
+	if (tag === "input") {
+		const type = Reflect.get(element, "type");
+		const role = BROWSER_IMPLICIT_ROLES.get(`input:${isString(type) ? type : "text"}`);
+		return element.hasAttribute("list") && (role === "textbox" || role === "searchbox") ? "combobox" : role;
+	}
+	if (tag === "select") return element.hasAttribute("multiple") || Number(element.getAttribute("size")) > 1 ? "listbox" : "combobox";
+	if (tag === "img" && element.getAttribute("alt") === "") return "none";
+	if ((tag === "header" || tag === "footer") && (element.parentElement?.closest("article, aside, main, nav, section") ?? null) !== null) return void 0;
+	if ((tag === "section" || tag === "form") && !element.hasAttribute("aria-label") && !element.hasAttribute("aria-labelledby") && !element.hasAttribute("title")) return void 0;
+	if (tag === "th" && element.getAttribute("scope")?.toLowerCase() === "row") return "rowheader";
+	return BROWSER_IMPLICIT_ROLES.get(tag);
+}
+/**
+* Computes the accessible name of an element, trimmed and whitespace-collapsed.
+*
+* @remarks
+* The steps follow the accessible-name computation, first match wins: the elements
+* that `aria-labelledby` references in the element's own tree, each through
+* `computeBrowserAlternative` with hidden content admitted when the referenced element is itself
+* hidden (`matchesBrowserOmitted` or `matchesBrowserInvisible`), `aria-label`, the `label` of an
+* `option`, the value of an `input` button, the `alt` of an
+* image, the text of every associated `label`, the element's own content for a role in
+* `BROWSER_CONTENT_NAMED_ROLES`, then the `title` attribute, then the `placeholder` of a text
+* control. Every traversal carries the element as its `target`, so an embedded control
+* contributes its value unless it is the element being named. The `title` step follows content because a tooltip names an element only when nothing
+* else does.
+*
+* @param element - The element to name
+* @param role - The element's role. Default: `computeBrowserRole(element)`
+* @returns The name, or the empty string when no step names the element
+*
+* @example
+* ```ts
+* const button = document.createElement('button')
+* button.textContent = ' Save  draft '
+* computeBrowserName(button) // 'Save draft'
+* ```
+*/
+function computeBrowserName(element, role = computeBrowserRole(element)) {
+	const view = element.ownerDocument.defaultView;
+	const tree = element.getRootNode();
+	const scope = view !== null && tree instanceof view.ShadowRoot ? tree : element.ownerDocument;
+	const referenced = normalizeBrowserName((element.getAttribute("aria-labelledby") ?? "").split(/\s+/).flatMap((id) => {
+		const target = id === "" ? null : scope.getElementById(id);
+		return target === null ? [] : [computeBrowserAlternative(target, {
+			hidden: matchesBrowserOmitted(target) || matchesBrowserInvisible(target),
+			target: element
+		})];
+	}).join(" "));
+	if (referenced !== "") return referenced;
+	const label = normalizeBrowserName(element.getAttribute("aria-label") ?? "");
+	if (label !== "") return label;
+	if (view !== null && element instanceof view.HTMLOptionElement) {
+		const option = normalizeBrowserName(element.label);
+		if (option !== "") return option;
+	}
+	const tag = element.localName;
+	const type = tag === "input" ? Reflect.get(element, "type") : void 0;
+	if (type === "button" || type === "submit" || type === "reset") {
+		const value = normalizeBrowserName(element.getAttribute("value") ?? (type === "submit" ? "Submit" : type === "reset" ? "Reset" : ""));
+		if (value !== "") return value;
+	}
+	if (type === "image" || tag === "img" || tag === "area") {
+		const alt = normalizeBrowserName(element.getAttribute("alt") ?? "");
+		if (alt !== "") return alt;
+	}
+	const labelled = normalizeBrowserName(Array.from(scope.querySelectorAll("label")).filter((candidate) => candidate.control === element).map((candidate) => computeBrowserText(candidate, { target: element })).join(" "));
+	if (labelled !== "") return labelled;
+	if (role !== void 0 && BROWSER_CONTENT_NAMED_ROLES.has(role)) {
+		const content = computeBrowserText(element, { target: element });
+		if (content !== "") return content;
+	}
+	const title = normalizeBrowserName(element.getAttribute("title") ?? "");
+	if (title !== "") return title;
+	return tag === "input" || tag === "textarea" ? normalizeBrowserName(element.getAttribute("placeholder") ?? "") : "";
+}
+/**
+* Computes the text an element's content contributes to an accessible name, in the flat tree,
+* trimmed and whitespace-collapsed.
+*
+* @remarks
+* The text is what `readBrowserContent` reads, normalized.
+*
+* @param root - The element or shadow root whose content is read
+* @param context - The traversal context. Default: no hidden content and no target
+* @returns The trimmed, whitespace-collapsed text
+*
+* @example
+* ```ts
+* const link = document.createElement('a')
+* link.innerHTML = '<div>Cars</div><div>Search the fleet</div>'
+* document.body.append(link)
+* computeBrowserText(link) // 'Cars Search the fleet'
+* ```
+*/
+function computeBrowserText(root, context) {
+	return normalizeBrowserName(readBrowserContent(root, context));
+}
+/**
+* Reads the untrimmed text an element's content contributes to an accessible name, in the flat
+* tree.
+*
+* @remarks
+* The content is the open shadow root's children for a shadow host, the flattened assigned nodes
+* for a `slot`, and the child nodes otherwise. Each child contributes what
+* `computeBrowserAlternative` returns for it, and a child that `matchesBrowserBlock` reports is
+* set apart from its neighbours by a space. Whitespace at the edges of an inline child is kept,
+* so `<b>Go </b>home` reads `Go home`.
+*
+* @param root - The element or shadow root whose content is read
+* @param context - The traversal context. Default: no hidden content and no target
+* @returns The untrimmed text
+*
+* @example
+* ```ts
+* const label = document.createElement('span')
+* label.innerHTML = '<b>Go </b>home'
+* document.body.append(label)
+* readBrowserContent(label) // 'Go home'
+* ```
+*/
+function readBrowserContent(root, context) {
+	const view = root.ownerDocument?.defaultView ?? null;
+	const shadow = view !== null && root instanceof view.Element ? root.shadowRoot : null;
+	const children = shadow !== null ? Array.from(shadow.childNodes) : view !== null && root instanceof view.HTMLSlotElement ? root.assignedNodes({ flatten: true }) : Array.from(root.childNodes);
+	let text = "";
+	let previous = false;
+	for (const child of children) {
+		const piece = computeBrowserAlternative(child, context);
+		const block = view !== null && child instanceof view.Element && matchesBrowserBlock(child);
+		if (piece !== "") text += text !== "" && (block || previous) ? ` ${piece}` : piece;
+		previous = block;
+	}
+	return text;
+}
+/**
+* Computes the text one node contributes to an accessible name: its own text alternative, or its
+* content.
+*
+* @remarks
+* A text node contributes its data unless its parent is invisible; a parent without a box of its
+* own, such as a `slot` or a `display: contents` element, is not invisible. An element
+* contributes nothing when it is hidden or is a `script` or `style`, and an element that
+* `matchesBrowserInvisible` reports contributes only what its content contributes, never its
+* value, `aria-label`, `alt`, or `title`. The context's `hidden` admits both. An embedded control
+* that is not the context's `target` contributes its value: a text field or a range its `value`,
+* a `select` its selected options' labels; a password field and the target itself contribute
+* nothing. Any other element contributes its `aria-label`, the `alt` of an image, or its content
+* through `readBrowserContent`, and its `title` when those are empty.
+*
+* @param node - The node whose contribution is computed
+* @param context - The traversal context. Default: no hidden content and no target
+* @returns The untrimmed contribution
+*
+* @example
+* ```ts
+* const image = document.createElement('img')
+* image.alt = 'Save'
+* computeBrowserAlternative(image) // 'Save'
+* ```
+*/
+function computeBrowserAlternative(node, context) {
+	const view = node.ownerDocument?.defaultView ?? null;
+	const hidden = context?.hidden === true;
+	if (view === null) return node.textContent ?? "";
+	if (!(node instanceof view.Element)) {
+		const parent = node.parentElement;
+		if (node.nodeType !== view.Node.TEXT_NODE) return "";
+		return !hidden && parent !== null && matchesBrowserInvisible(parent) ? "" : node.textContent ?? "";
+	}
+	const tag = node.localName;
+	if (!hidden && matchesBrowserHidden(node)) return "";
+	if (tag === "script" || tag === "style") return "";
+	if (!hidden && matchesBrowserInvisible(node)) return readBrowserContent(node, context);
+	const embedded = node !== context?.target;
+	if (node instanceof view.HTMLTextAreaElement) return embedded ? node.value : "";
+	if (node instanceof view.HTMLSelectElement) return embedded ? Array.from(node.selectedOptions, (option) => option.label).join(" ") : "";
+	if (node instanceof view.HTMLInputElement && node.type !== "password" && (BROWSER_TYPED_INPUTS.has(node.type) || node.type === "range")) return embedded ? node.value : "";
+	const label = normalizeBrowserName(node.getAttribute("aria-label") ?? "");
+	if (label !== "") return label;
+	const content = tag === "img" || tag === "area" || tag === "input" && Reflect.get(node, "type") === "image" ? node.getAttribute("alt") ?? "" : readBrowserContent(node, context);
+	return content.trim() !== "" ? content : node.getAttribute("title") ?? "";
+}
+/**
+* Checks whether an element and its subtree are hidden from the rendered page.
+*
+* @param element - The element to test
+* @returns True if the element carries `hidden` or `aria-hidden="true"`, or its computed
+* `display` is `none`; false otherwise
+*
+* @example
+* ```ts
+* const note = document.createElement('p')
+* note.hidden = true
+* matchesBrowserHidden(note) // true
+* ```
+*/
+function matchesBrowserHidden(element) {
+	return element.hasAttribute("hidden") || element.getAttribute("aria-hidden") === "true" || element.ownerDocument.defaultView?.getComputedStyle(element).display === "none";
+}
+/**
+* Checks whether an element renders nothing visible of its own.
+*
+* @remarks
+* An element whose computed `visibility` is `hidden` or `collapse` is invisible. An element with
+* `display: contents` has no box of its own but renders its descendants, so it is not invisible.
+* Any other element is invisible when `checkVisibility` with `visibilityProperty` and
+* `contentVisibilityAuto` reports it, which covers an element without a box and one skipped by
+* `content-visibility: auto`. A descendant can still be visible, so the rule omits the element's
+* own row and text and keeps its subtree. An `option` or `optgroup` inside a `select` is
+* invisible where the `select` is, because a drop-down renders its options outside the page's
+* boxes. Zero-size and off-screen elements stay visible. An
+* element in a document without a window is never invisible, because nothing renders it.
+*
+* @param element - The element to test
+* @returns True if the element renders nothing visible of its own; false otherwise
+*
+* @example
+* ```ts
+* const button = document.createElement('button')
+* button.style.visibility = 'hidden'
+* document.body.append(button)
+* matchesBrowserInvisible(button) // true
+* ```
+*/
+function matchesBrowserInvisible(element) {
+	const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+	if (style === void 0) return false;
+	if (style.visibility === "hidden" || style.visibility === "collapse") return true;
+	const select = element.localName === "option" || element.localName === "optgroup" ? element.closest("select") : null;
+	if (select !== null) return matchesBrowserInvisible(select);
+	return style.display !== "contents" && !element.checkVisibility({
+		visibilityProperty: true,
+		contentVisibilityAuto: true
+	});
+}
+/**
+* Checks whether an element sits in an omitted subtree: the element or a flat-tree ancestor that
+* `readBrowserParent` reaches matches `matchesBrowserHidden`, through assigned slots, shadow
+* hosts, and the frame elements of same-origin documents.
+*
+* @param element - The element to test
+* @returns True if the element or an ancestor is hidden; false otherwise
+*
+* @example
+* ```ts
+* const section = document.createElement('section')
+* section.hidden = true
+* const button = section.appendChild(document.createElement('button'))
+* matchesBrowserOmitted(button) // true
+* ```
+*/
+function matchesBrowserOmitted(element) {
+	for (let current = element; current !== null; current = readBrowserParent(current)) if (matchesBrowserHidden(current)) return true;
+	return false;
+}
+/**
+* Reads an element's parent in the flat tree: the slot it is assigned to in an open shadow root,
+* its parent element, the host of the open shadow root it sits at the top of, or the frame
+* element of its same-origin document.
+*
+* @param element - The element whose parent is read
+* @returns The parent, or `null` at the top of a top-level or cross-origin-framed document
+*
+* @example
+* ```ts
+* readBrowserParent(document.body) // document.documentElement
+* readBrowserParent(document.documentElement) // null in a top-level document
+* ```
+*/
+function readBrowserParent(element) {
+	if (element.assignedSlot !== null) return element.assignedSlot;
+	if (element.parentElement !== null) return element.parentElement;
+	const view = element.ownerDocument.defaultView;
+	if (view === null) return null;
+	const tree = element.getRootNode();
+	return tree instanceof view.ShadowRoot ? tree.host : view.frameElement;
+}
+/**
+* Checks whether an element starts a block of its own, the unit that separates runs of text.
+*
+* @param element - The element to test
+* @returns True if the element is a `br`, or its computed `display` is neither inline-level,
+* `contents`, nor `none`; false otherwise
+*
+* @example
+* ```ts
+* const paragraph = document.createElement('p')
+* document.body.append(paragraph)
+* matchesBrowserBlock(paragraph) // true
+* ```
+*/
+function matchesBrowserBlock(element) {
+	if (element.localName === "br") return true;
+	const display = element.ownerDocument.defaultView?.getComputedStyle(element).display ?? "";
+	return !display.startsWith("inline") && display !== "contents" && display !== "none";
+}
+/**
+* Collects the tree roots a wait observes under a node: the node's own root, then every open
+* shadow root and every same-origin frame document at or beneath it, recursively.
+*
+* @param root - The document, shadow root, or element to collect under
+* @returns The roots, the node's own root first; a cross-origin frame contributes none
+*
+* @example
+* ```ts
+* collectBrowserRoots(document) // [document, ...each open shadow root and frame document]
+* ```
+*/
+function collectBrowserRoots(root) {
+	const roots = [root.getRootNode()];
+	const queue = [root];
+	for (let current = queue.shift(); current !== void 0; current = queue.shift()) {
+		const view = (isBrowserDocument(current) ? current : current.ownerDocument)?.defaultView ?? null;
+		const own = view !== null && current instanceof view.Element ? [current] : [];
+		for (const element of [...own, ...current.querySelectorAll("*")]) {
+			const shadow = element.shadowRoot;
+			if (shadow !== null) {
+				roots.push(shadow);
+				queue.push(shadow);
+			}
+			const child = view !== null && element instanceof view.HTMLIFrameElement ? element.contentDocument : null;
+			if (child !== null) {
+				roots.push(child);
+				queue.push(child);
+			}
+		}
+	}
+	return roots;
+}
+/**
+* Checks whether activating an element opens another browsing context.
+*
+* @remarks
+* A link with `href` navigates its `target`, and a form, or a submit button inside one, navigates
+* the submitter's `formtarget` or the form's `target`; either falls back to the target of the
+* document's `base` element. `_blank` opens another context, and a target in
+* `BROWSER_CONTEXT_TARGETS` does not. A name reuses the browsing context carrying it when the
+* element's window, an ancestor window, or a frame element in one of their documents carries it,
+* and opens another context otherwise; an ancestor this realm cannot read is skipped.
+*
+* @param element - The element an untrusted activation would target
+* @returns True if the activation opens another browsing context; false otherwise, including
+* for an element whose activation navigates nothing
+*
+* @example
+* ```ts
+* const link = document.createElement('a')
+* link.href = '/cars'
+* link.target = '_blank'
+* matchesBrowserPopup(link) // true
+* ```
+*/
+function matchesBrowserPopup(element) {
+	const document = element.ownerDocument;
+	const view = document.defaultView;
+	const base = document.querySelector("base[target]")?.getAttribute("target") ?? "";
+	const tag = element.localName;
+	const type = Reflect.get(element, "type");
+	const submitter = tag === "button" && type === "submit" || tag === "input" && (type === "submit" || type === "image");
+	const form = tag === "form" ? element : Reflect.get(element, "form");
+	let target;
+	if ((tag === "a" || tag === "area") && element.hasAttribute("href")) target = element.getAttribute("target") ?? base;
+	else if (view !== null && form instanceof view.HTMLFormElement && (tag === "form" || submitter)) target = (submitter ? element.getAttribute("formtarget") : null) ?? form.getAttribute("target") ?? base;
+	if (target === void 0) return false;
+	const keyword = target.trim().toLowerCase();
+	if (BROWSER_CONTEXT_TARGETS.has(keyword)) return false;
+	if (keyword === "_blank") return true;
+	const selector = `iframe[name="${CSS.escape(target)}"], frame[name="${CSS.escape(target)}"]`;
+	let current = view;
+	while (current !== null) {
+		const frame = current;
+		const found = attempt(() => frame.name === target || frame.document.querySelector(selector) !== null);
+		if (found.success && found.value) return false;
+		current = frame.parent === frame ? null : frame.parent;
+	}
+	return true;
+}
+/**
+* Checks whether a click on an element activates the `label` that contains it, following the
+* HTML label activation rule.
+*
+* @remarks
+* The click activates the label when the target is the label itself, or when no element on the
+* path from the target up to the label, the target included, matches
+* `BROWSER_INTERACTIVE_CONTENT`.
+*
+* @param target - The element the click lands on
+* @param label - The label that contains the target, or the target itself
+* @returns True if the click activates the label; false otherwise
+*
+* @example
+* ```ts
+* const label = document.createElement('label')
+* label.innerHTML = '<a href="#help">Help</a> <span>Photo</span>'
+* matchesBrowserActivation(label.querySelector('a'), label) // false
+* matchesBrowserActivation(label.querySelector('span'), label) // true
+* ```
+*/
+function matchesBrowserActivation(target, label) {
+	for (let current = target; current !== null && current !== label; current = current.parentElement) if (current.matches("a[href], audio[controls], button, details, embed, iframe, img[usemap], img[controls], input:not([type=\"hidden\" i]), label, select, textarea, video[controls]")) return false;
+	return true;
+}
+/**
+* Moves a tree walker past the subtree of its current node.
+*
+* @param walker - The walker to move; its root bounds the move
+* @returns The first node after the subtree in document order, or `null` when the walk is done
+*
+* @example
+* ```ts
+* const walker = document.createTreeWalker(document.body)
+* walker.nextNode()
+* skipBrowserSubtree(walker) // the first node after the body's first child and its descendants
+* ```
+*/
+function skipBrowserSubtree(walker) {
+	let node = walker.nextSibling();
+	while (node === null) {
+		if (walker.parentNode() === null) return null;
+		node = walker.nextSibling();
+	}
+	return node;
+}
+/**
+* Reads the nearest block container of an element, the unit that separates runs of text.
+*
+* @param element - The element to start from, or `null` for a node without a parent element
+* @param root - The node that bounds the search
+* @returns The nearest inclusive ancestor, below `root`, that `matchesBrowserBlock` reports;
+* `root` when none is
+*
+* @example
+* ```ts
+* const strong = document.createElement('strong')
+* const paragraph = document.createElement('p')
+* paragraph.append(strong)
+* document.body.append(paragraph)
+* readBrowserBlock(strong, document.body) // paragraph
+* ```
+*/
+function readBrowserBlock(element, root) {
+	let current = element;
+	while (current !== null && current !== root) {
+		if (matchesBrowserBlock(current)) return current;
+		current = current.parentElement;
+	}
+	return root;
+}
+/**
+* Subscribes one listener to a window's navigation events until a signal aborts.
+*
+* @remarks
+* The listener receives the Navigation API's `navigatesuccess` where the window has that API, and
+* `popstate` and `hashchange` where it does not, plus `pagehide` in both cases. A `pushState` in a
+* window without the Navigation API fires none of those events.
+*
+* @param window - The window whose navigation events are observed
+* @param listener - Receives each event; `event.type` tells an unload from a same-document
+* navigation
+* @param signal - Removes every subscription when it aborts
+*
+* @example
+* ```ts
+* const release = new AbortController()
+* listenBrowserNavigation(frame.contentWindow, (event) => console.log(event.type), release.signal)
+* ```
+*/
+function listenBrowserNavigation(window, listener, signal) {
+	const options = { signal };
+	if (Reflect.has(window, "navigation")) window.navigation.addEventListener("navigatesuccess", listener, options);
+	else {
+		window.addEventListener("popstate", listener, options);
+		window.addEventListener("hashchange", listener, options);
+	}
+	window.addEventListener("pagehide", listener, options);
+}
+//#endregion
+//#region src/browser/elements/BrowserDOMElement.ts
+/**
+* Drives a referenced element of a DOM document without trusted input.
+*
+* @remarks
+* `click` runs `HTMLElement.click()`; `fill` and `select` set the control through its native
+* prototype setter and dispatch `input` and `change`, and `fill` refuses `UNKNOWN` an element
+* that is not a text control and a read-only one; `submit` runs `form.requestSubmit()` and
+* observes the outcome through a `submit` listener registered across the call. Each action
+* refuses with a `BrowserElementError` naming the reason: `DISABLED` for a disabled control,
+* `HIDDEN` for an element that does not render, and `UNTRUSTED` for what an untrusted event
+* cannot do, which is a click or submission that opens another browsing context, a click that
+* opens a file chooser, and typing into a contenteditable element. A click that activates a
+* `label`, on the label itself or on a descendant that `matchesBrowserActivation` admits, is
+* judged by the label's control as well: a disabled control refuses `DISABLED`, and a file input
+* refuses `UNTRUSTED` as a direct click on it does. A click on an interactive descendant of a
+* label keeps only its own checks. `role` and `name` read the description the latest outline or
+* query that encountered the element captured, so a change to the element shows after the next
+* capture, and a dropped reference keeps its last capture. Every action on an element removed
+* from its document, collected, or held across a navigation reports `GONE`.
+*
+* @example
+* ```ts
+* const view = createBrowserDOMView({ document: frame.contentDocument })
+* await view.elements.outline()
+* await view.elements.element('e1')?.click()
+* ```
+*/
+var BrowserDOMElement = class {
+	#input;
+	constructor(input) {
+		this.#input = input;
+	}
+	get reference() {
+		return this.#input.reference;
+	}
+	get role() {
+		return this.#input.description().role;
+	}
+	get name() {
+		return this.#input.description().name;
+	}
+	async click(options) {
+		const [node, view] = this.#actionable(options);
+		const label = node instanceof view.HTMLLabelElement ? node : node.closest("label");
+		const control = label !== null && matchesBrowserActivation(node, label) ? label.control : null;
+		if (control !== null && control !== node) {
+			if (control.matches(":disabled")) throw new BrowserElementError(this.reference, "DISABLED", "labels a disabled control");
+			this.#refuse(control);
+		}
+		this.#refuse(node);
+		if (node instanceof view.HTMLElement) {
+			node.click();
+			return;
+		}
+		node.dispatchEvent(new view.MouseEvent("click", {
+			bubbles: true,
+			cancelable: true,
+			composed: true
+		}));
+	}
+	async fill(value, options) {
+		const [node, view] = this.#actionable(options);
+		if (node instanceof view.HTMLElement && node.isContentEditable) throw new BrowserElementError(this.reference, "UNTRUSTED", "is contenteditable, which an untrusted event cannot type into");
+		const input = node instanceof view.HTMLInputElement ? node : void 0;
+		const control = input ?? (node instanceof view.HTMLTextAreaElement ? node : void 0);
+		const setter = Reflect.getOwnPropertyDescriptor(input === void 0 ? view.HTMLTextAreaElement.prototype : view.HTMLInputElement.prototype, "value")?.set;
+		if (control === void 0 || input !== void 0 && !BROWSER_TYPED_INPUTS.has(input.type)) throw new BrowserElementError(this.reference, "UNKNOWN", "is not a text control");
+		if (control.readOnly || setter === void 0) throw new BrowserElementError(this.reference, "UNKNOWN", "is not editable");
+		control.focus();
+		Reflect.apply(setter, control, [value]);
+		control.dispatchEvent(new view.InputEvent("input", {
+			bubbles: true,
+			composed: true,
+			inputType: "insertReplacementText",
+			data: value
+		}));
+		control.dispatchEvent(new view.Event("change", { bubbles: true }));
+	}
+	async select(values, options) {
+		const [node, view] = this.#actionable(options);
+		if (!(node instanceof view.HTMLSelectElement)) throw new BrowserElementError(this.reference, "UNKNOWN", "is not a select control");
+		const choices = Array.from(node.options);
+		const selected = values.map((value) => choices.find((option) => option.value === value) ?? choices.find((option) => option.label === value));
+		if (values.find((_value, index) => selected[index] === void 0) !== void 0) throw new BrowserElementError(this.reference, "UNKNOWN", "has no such option");
+		for (const option of choices) option.selected = selected.includes(option);
+		node.dispatchEvent(new view.Event("input", {
+			bubbles: true,
+			composed: true
+		}));
+		node.dispatchEvent(new view.Event("change", { bubbles: true }));
+	}
+	async focus(options) {
+		const [node, view] = this.#current(options);
+		if (node instanceof view.HTMLElement || node instanceof view.SVGElement) node.focus();
+	}
+	async read(options) {
+		const [node] = this.#current(options);
+		return createBrowserReading({
+			...readBrowserCapture(node),
+			navigation: this.#input.navigation
+		});
+	}
+	async submit(options) {
+		const [node, view] = this.#current(options);
+		const owner = node instanceof view.HTMLFormElement ? node : Reflect.get(node, "form");
+		if (!(owner instanceof view.HTMLFormElement)) throw new BrowserElementError(this.reference, "UNKNOWN", "is not in a form");
+		const type = Reflect.get(node, "type");
+		const submitter = node instanceof view.HTMLButtonElement && type === "submit" || node instanceof view.HTMLInputElement && (type === "submit" || type === "image") ? node : void 0;
+		if (submitter?.matches(":disabled") === true) throw new BrowserElementError(this.reference, "DISABLED");
+		if (matchesBrowserPopup(submitter ?? owner)) throw new BrowserElementError(this.reference, "UNTRUSTED", "submits into another browsing context, which an untrusted submission cannot open");
+		let submitted = false;
+		const release = new AbortController();
+		owner.addEventListener("submit", () => {
+			submitted = true;
+		}, { signal: release.signal });
+		try {
+			owner.requestSubmit(submitter ?? null);
+		} finally {
+			release.abort();
+		}
+		if (submitted) return;
+		const invalid = Array.from(owner.elements).find((control) => control.localName !== "fieldset" && control.matches(":invalid"));
+		if (invalid === void 0) throw new BrowserError("did not submit", "BROWSER_DOCUMENT_SUBMIT", { reference: this.reference });
+		const field = computeBrowserName(invalid) || (invalid.getAttribute("name") ?? invalid.localName);
+		const reason = Reflect.get(invalid, "validationMessage");
+		const message = isString(reason) ? reason : "";
+		throw new BrowserError(`did not submit: ${field} — ${message}`, "BROWSER_DOCUMENT_SUBMIT", {
+			reference: this.reference,
+			field,
+			message
+		});
+	}
+	#current(options) {
+		options?.signal?.throwIfAborted();
+		const node = this.#input.node.deref();
+		const view = node?.ownerDocument.defaultView ?? null;
+		if (!this.#input.current() || node === void 0 || !node.isConnected || view === null) throw new BrowserElementError(this.reference, "GONE");
+		return [node, view];
+	}
+	#actionable(options) {
+		const current = this.#current(options);
+		const [node] = current;
+		if (!node.checkVisibility()) throw new BrowserElementError(this.reference, "HIDDEN");
+		if (node.matches(":disabled")) throw new BrowserElementError(this.reference, "DISABLED");
+		return current;
+	}
+	#refuse(target) {
+		if (matchesBrowserPopup(target)) throw new BrowserElementError(this.reference, "UNTRUSTED", "opens another browsing context, which an untrusted click cannot do");
+		if (target.localName === "input" && Reflect.get(target, "type") === "file") throw new BrowserElementError(this.reference, "UNTRUSTED", "opens a file chooser, which an untrusted click cannot do");
+	}
+};
+//#endregion
+//#region src/browser/BrowserDOMWait.ts
+/**
+* Parks one condition on DOM mutations until it holds, with one deadline and no other timer.
+*
+* @remarks
+* The wait observes every root `roots` returns, each through a `MutationObserver` of that root's
+* realm, and re-reads the roots after every mutation batch and every capture-phase `load` in an
+* observed root: a same-origin frame or an open shadow root that appears joins the observation,
+* and a root that departed (a replaced frame document, a removed shadow root) leaves it, with its
+* observer disconnected and its `load` listener removed. The check runs before the wait parks and
+* again after every subscription, and no check runs once the deadline, counted from `start`, has
+* passed, which the wait reads again after `roots` returns. The wait settles one time: on the
+* check's first value, on the signal's abort with its reason, at the deadline with
+* `BROWSER_WAIT_TIMEOUT`, on a `pagehide` in the first root's window with `GONE`, or with whatever
+* the check or the roots function throws. A signal that aborts while `check` or `roots` runs
+* settles the wait with its reason, and wins over a value that same check returns. Settlement
+* disconnects every observer and removes every listener synchronously, so a mutation queued
+* before it runs no check, and a `roots` or `check` that settles the wait from inside leaves no
+* observer, listener, or further check behind.
+*
+* A shadow root attached after the wait began is a declared limit: attaching one fires no
+* mutation record and no event, so the wait discovers it at the next mutation or `load` it
+* observes, and a match inserted into it with no other observed change is not seen before the
+* deadline. The wait never polls to close that gap.
+*
+* @example
+* ```ts
+* const ready = await new BrowserDOMWait({
+* 	roots: () => [document],
+* 	check: () => document.querySelector('#ready') ?? undefined,
+* 	timeout: 1_000,
+* 	start: performance.now(),
+* 	subject: 'Ready wait',
+* }).execute()
+* ```
+*/
+var BrowserDOMWait = class {
+	#wait;
+	#settled = Promise.withResolvers();
+	#release = new AbortController();
+	#observers = /* @__PURE__ */ new Map();
+	#main;
+	#timer;
+	#recheckHandler = this.#recheck.bind(this);
+	#unloadHandler = this.#unload.bind(this);
+	constructor(wait) {
+		this.#wait = wait;
+	}
+	get roots() {
+		return [...this.#observers.keys()];
+	}
+	async execute() {
+		const signal = this.#wait.signal;
+		signal?.throwIfAborted();
+		const first = this.#wait.check();
+		signal?.throwIfAborted();
+		if (first !== void 0) return first;
+		this.#timer = setTimeout(this.#expire.bind(this), Math.max(0, this.#remaining()));
+		signal?.addEventListener("abort", () => this.#fail(signal.reason), { signal: this.#release.signal });
+		this.#recheck();
+		return await this.#settled.promise;
+	}
+	#recheck() {
+		if (this.#release.signal.aborted) return;
+		if (this.#remaining() <= 0) {
+			this.#expire();
+			return;
+		}
+		const result = attempt(() => {
+			this.#reconcile();
+			if (this.#release.signal.aborted) return void 0;
+			if (this.#remaining() <= 0) {
+				this.#expire();
+				return;
+			}
+			return this.#wait.check();
+		});
+		if (!result.success) this.#fail(result.error);
+		else if (result.value !== void 0) this.#succeed(result.value);
+	}
+	#reconcile() {
+		const live = new Set(this.#wait.roots());
+		if (this.#release.signal.aborted) return;
+		for (const [root, entry] of this.#observers) {
+			if (live.has(root)) continue;
+			entry.observer.disconnect();
+			entry.release.abort();
+			this.#observers.delete(root);
+		}
+		for (const root of live) {
+			if (this.#observers.has(root)) continue;
+			const view = (isBrowserDocument(root) ? root : root.ownerDocument)?.defaultView ?? null;
+			if (view === null) continue;
+			const observer = new view.MutationObserver(this.#recheckHandler);
+			observer.observe(root, {
+				subtree: true,
+				childList: true,
+				attributes: true,
+				characterData: true
+			});
+			const release = new AbortController();
+			root.addEventListener("load", this.#recheckHandler, {
+				capture: true,
+				signal: release.signal
+			});
+			this.#observers.set(root, {
+				observer,
+				release
+			});
+			if (this.#main !== void 0) continue;
+			this.#main = view;
+			view.addEventListener("pagehide", this.#unloadHandler, { signal: this.#release.signal });
+		}
+	}
+	#remaining() {
+		const now = this.#wait.now;
+		return this.#wait.start + this.#wait.timeout - (now === void 0 ? performance.now() : now());
+	}
+	#expire() {
+		this.#fail(new BrowserError(`${this.#wait.subject} timed out`, "BROWSER_WAIT_TIMEOUT", { timeout: this.#wait.timeout }));
+	}
+	#unload() {
+		this.#fail(new BrowserElementError({ subject: "document" }, "GONE"));
+	}
+	#succeed(value) {
+		this.#stop();
+		this.#settled.resolve(value);
+	}
+	#fail(error) {
+		this.#stop();
+		this.#settled.reject(error);
+	}
+	#stop() {
+		clearTimeout(this.#timer);
+		this.#release.abort();
+		for (const entry of this.#observers.values()) {
+			entry.observer.disconnect();
+			entry.release.abort();
+		}
+		this.#observers.clear();
+	}
+};
+//#endregion
+//#region src/browser/elements/BrowserDOMElementManager.ts
+/**
+* Outlines a DOM document from its elements and binds stable references to the interactive ones.
+*
+* @remarks
+* Rows come in document order from a `TreeWalker` over the flat tree: an open shadow root
+* contributes its rows in place of its host's children, a `slot` its assigned nodes, and a
+* same-origin `iframe` its document's rows, while a cross-origin one renders
+* `iframe "NAME" (cross-origin, not readable)`. An element that `matchesBrowserHidden` reports is
+* omitted with its subtree, a scope root in such a subtree yields no row, and an element that
+* `matchesBrowserInvisible` reports yields no row of its own. An element whose role
+* `BROWSER_INTERACTIVE_ROLES` names receives a reference bound through a `WeakRef`, which never
+* changes while the manager holds it, and a reference number is never reused. Every outline or
+* query that encounters a bound element records its role and name afresh, and the element's
+* wrapper reports that latest capture, also after the manager drops the reference. A reference
+* and a reading from any walked document record that document's epoch, which advances on its own
+* navigation events and on the view's; that document's `pagehide` drops its references. A form
+* carrying a `toolname` attribute renders `[tool=NAME]` after its role and name. A `select` row
+* is followed by one `option` row per option, named by its label. Whitespace between two texts of
+* one block renders as one space, as a rendered `br` between them does, and texts with neither
+* between them stay joined. A CSS query
+* searches the document the view drives, not its child documents or shadow trees. After the
+* input's `signal` aborts, `outline`, `find`, and `wait` reject with its reason.
+*
+* `wait` parks a `BrowserDOMWait` bound to the view's lifetime over every root that
+* `collectBrowserRoots` reaches from its scope, reconciled at every observed mutation and frame
+* `load`. A shadow root attached after the wait began is a declared limit: the wait discovers it
+* at the next observed mutation or `load`, so a match inserted there with no other observed
+* change is not seen before the deadline.
+*
+* @example
+* ```ts
+* const view = createBrowserDOMView({ document: frame.contentDocument })
+* const outline = await view.elements.outline()
+* const [save] = await view.elements.find({ role: 'button', name: 'save' })
+* ```
+*/
+var BrowserDOMElementManager = class {
+	#input;
+	#records = /* @__PURE__ */ new Map();
+	#identities = /* @__PURE__ */ new WeakMap();
+	#descriptions = /* @__PURE__ */ new WeakMap();
+	#epochs = /* @__PURE__ */ new WeakMap();
+	#watched = /* @__PURE__ */ new WeakSet();
+	#count = 0;
+	constructor(input) {
+		this.#input = input;
+	}
+	async outline(options) {
+		this.#input.signal.throwIfAborted();
+		const limit = options?.limit ?? BROWSER_OUTLINE_LIMIT;
+		if (!isInteger(limit) || limit < 0) throw new BrowserError("Outline limit must be a nonnegative integer", void 0, { limit });
+		options?.signal?.throwIfAborted();
+		const document = this.#input.document();
+		const rows = this.#capture(this.#root(document, options?.within), options?.within);
+		return renderBrowserOutline(document.URL, document.title, rows, limit);
+	}
+	async find(query, options) {
+		this.#input.signal.throwIfAborted();
+		options?.signal?.throwIfAborted();
+		return this.#find(query);
+	}
+	async wait(query, options) {
+		this.#input.signal.throwIfAborted();
+		const start = performance.now();
+		const timeout = options?.timeout ?? 5e3;
+		validateBrowserTimeout(timeout);
+		const signal = options?.signal === void 0 ? this.#input.signal : AbortSignal.any([options.signal, this.#input.signal]);
+		return await new BrowserDOMWait({
+			roots: this.#roots.bind(this, query.within),
+			check: this.#match.bind(this, query, options?.absent === true),
+			timeout,
+			start,
+			signal,
+			subject: "Element wait"
+		}).execute();
+	}
+	element(reference) {
+		return this.#records.get(parseBrowserReference(reference) ?? "")?.element;
+	}
+	elements() {
+		for (const [reference, record] of this.#records) if (record.node.deref() === void 0) this.#records.delete(reference);
+		return [...this.#records.values()].map((record) => record.element);
+	}
+	clear() {
+		this.#records.clear();
+	}
+	#match(query, absent) {
+		const found = this.#find(query);
+		return (absent ? found.length === 0 : found.length > 0) ? found : void 0;
+	}
+	#find(query) {
+		const root = this.#root(this.#input.document(), query.within);
+		const matches = filterBrowserOutline(this.#capture(root, query.within), query).flatMap((row) => {
+			const record = this.#records.get(row.reference ?? "");
+			return record === void 0 ? [] : [record.element];
+		});
+		const css = query.css;
+		if (css === void 0) return matches;
+		const selected = attempt(() => Array.from(root.querySelectorAll(css)));
+		if (!selected.success) throw new BrowserError(`CSS query is invalid: ${css}`, "BROWSER_ELEMENT_QUERY", { css });
+		const bound = selected.value.map((element) => {
+			const role = computeBrowserRole(element) ?? "generic";
+			return this.#bind(element, role, computeBrowserName(element, role));
+		});
+		if (query.role === void 0 && query.name === void 0) return bound;
+		return matches.filter((element) => bound.includes(element));
+	}
+	#capture(root, within) {
+		const rows = [];
+		if (within === void 0 || !matchesBrowserOmitted(root)) this.#walk(root, rows, false);
+		return rows;
+	}
+	#root(document, within) {
+		if (within === void 0) return document.documentElement;
+		const node = this.#records.get(parseBrowserReference(within) ?? "")?.node.deref();
+		if (node === void 0 || !node.isConnected || node.ownerDocument.defaultView === null) throw new BrowserElementError(within, "GONE");
+		return node;
+	}
+	#roots(within) {
+		return collectBrowserRoots(this.#root(this.#input.document(), within));
+	}
+	#walk(root, rows, muted) {
+		const document = root.ownerDocument;
+		const view = document.defaultView;
+		if (view === null) return;
+		if (root instanceof view.Element && matchesBrowserHidden(root)) return;
+		this.#watch(document);
+		const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT, (node) => node instanceof view.Element && matchesBrowserHidden(node) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT);
+		let text = "";
+		let block;
+		let silenced;
+		let node = root instanceof view.Element ? root : walker.nextNode();
+		while (node !== null) {
+			if (silenced !== void 0 && !silenced.contains(node)) silenced = void 0;
+			const quiet = muted || silenced !== void 0;
+			if (!(node instanceof view.Element)) {
+				const parent = node.parentElement;
+				const data = node.textContent ?? "";
+				const blank = data.trim() === "";
+				if (!quiet && (!blank || text !== "") && (parent === null || !matchesBrowserInvisible(parent))) {
+					const container = readBrowserBlock(parent, root);
+					if (!blank) {
+						if (block !== void 0 && block !== container) text = this.#flush(rows, text);
+						text += data;
+						block = container;
+					} else if (container === block) text += data;
+				}
+				node = walker.nextNode();
+				continue;
+			}
+			const invisible = matchesBrowserInvisible(node);
+			if (node.localName === "br") {
+				if (!quiet && text !== "") text += "\n";
+				node = walker.nextNode();
+				continue;
+			}
+			if (node instanceof view.HTMLIFrameElement) {
+				text = this.#flush(rows, text);
+				const child = node.contentDocument;
+				if (invisible) {
+					node = skipBrowserSubtree(walker);
+					continue;
+				}
+				if (child === null) this.#text(rows, `iframe ${JSON.stringify(computeBrowserName(node))} (cross-origin, not readable)`);
+				else this.#walk(child.documentElement, rows, quiet);
+				node = skipBrowserSubtree(walker);
+				continue;
+			}
+			if (node instanceof view.HTMLSlotElement) {
+				text = this.#flush(rows, text);
+				for (const assigned of node.assignedNodes({ flatten: true })) if (assigned instanceof view.Element) this.#walk(assigned, rows, quiet);
+				else if (!quiet) this.#flush(rows, assigned.textContent ?? "");
+				node = skipBrowserSubtree(walker);
+				continue;
+			}
+			const tool = node.localName === "form" ? node.getAttribute("toolname") ?? "" : "";
+			const role = tool === "" ? computeBrowserRole(node) : "form";
+			if (!invisible && role !== void 0 && (BROWSER_INTERACTIVE_ROLES.has(role) || role === "heading" || tool !== "")) {
+				text = this.#flush(rows, text);
+				rows.push(this.#row(node, role, view, String(rows.length)));
+				if (silenced === void 0 && BROWSER_CONTENT_NAMED_ROLES.has(role)) silenced = node;
+				if (node.localName === "textarea") {
+					node = skipBrowserSubtree(walker);
+					continue;
+				}
+			}
+			const shadow = node.shadowRoot;
+			if (shadow !== null) {
+				text = this.#flush(rows, text);
+				this.#walk(shadow, rows, muted || silenced !== void 0);
+				node = skipBrowserSubtree(walker);
+				continue;
+			}
+			node = walker.nextNode();
+		}
+		this.#flush(rows, text);
+	}
+	#watch(document) {
+		const view = document.defaultView;
+		if (this.#watched.has(document) || view === null) return;
+		this.#watched.add(document);
+		listenBrowserNavigation(view, this.#advance.bind(this, new WeakRef(document)), this.#input.signal);
+	}
+	#advance(document, event) {
+		const target = document.deref();
+		if (target === void 0) return;
+		this.#epochs.set(target, (this.#epochs.get(target) ?? 0) + 1);
+		if (event.type !== "pagehide") return;
+		for (const [reference, record] of this.#records) {
+			const node = record.node.deref();
+			if (node === void 0 || node.ownerDocument === target) this.#records.delete(reference);
+		}
+	}
+	#epoch(document) {
+		const target = document.deref();
+		return target === void 0 ? -1 : this.#input.navigation() + (this.#epochs.get(target) ?? 0);
+	}
+	#flush(rows, text) {
+		if (normalizeBrowserName(text) !== "") this.#text(rows, text);
+		return "";
+	}
+	#text(rows, text) {
+		rows.push({
+			id: String(rows.length),
+			parent: void 0,
+			children: [],
+			backend: void 0,
+			frame: void 0,
+			ignored: false,
+			role: "StaticText",
+			name: normalizeBrowserName(text),
+			description: void 0,
+			value: void 0,
+			properties: {},
+			session: "",
+			reference: void 0
+		});
+	}
+	#row(element, role, view, id) {
+		const name = computeBrowserName(element, role);
+		const tool = element.localName === "form" ? element.getAttribute("toolname") : null;
+		const reference = role === "heading" ? void 0 : this.#bind(element, role, name).reference;
+		const input = element instanceof view.HTMLInputElement ? element : void 0;
+		const checked = input !== void 0 && (input.type === "checkbox" || input.type === "radio") ? input.checked : element.getAttribute("aria-checked") === "true";
+		let value;
+		if (element instanceof view.HTMLSelectElement) value = Array.from(element.selectedOptions, (option) => option.label).join(", ");
+		else if (element instanceof view.HTMLTextAreaElement) value = element.value;
+		else if (input !== void 0 && input.type !== "password" && (BROWSER_TYPED_INPUTS.has(input.type) || input.type === "range")) value = input.value;
+		return {
+			id: reference ?? id,
+			parent: void 0,
+			children: [],
+			backend: void 0,
+			frame: void 0,
+			ignored: false,
+			role,
+			name,
+			description: void 0,
+			value,
+			properties: {
+				checked,
+				disabled: element.matches(":disabled")
+			},
+			...tool === null || tool === "" ? {} : { tool },
+			session: "",
+			reference
+		};
+	}
+	#bind(element, role, name) {
+		const known = this.#identities.get(element);
+		const existing = known === void 0 ? void 0 : this.#records.get(known);
+		if (existing !== void 0) {
+			this.#descriptions.set(existing.node, {
+				role,
+				name
+			});
+			return existing.element;
+		}
+		this.#count += 1;
+		const reference = `${BROWSER_REFERENCE_PREFIX}${this.#count}`;
+		const node = new WeakRef(element);
+		const description = {
+			role,
+			name
+		};
+		this.#descriptions.set(node, description);
+		const created = new BrowserDOMElement({
+			reference,
+			description: this.#description.bind(this, node, description),
+			node,
+			current: this.#holds.bind(this, reference),
+			navigation: this.#epoch.bind(this, new WeakRef(element.ownerDocument))
+		});
+		this.#records.set(reference, {
+			node,
+			element: created
+		});
+		this.#identities.set(element, reference);
+		return created;
+	}
+	#holds(reference) {
+		return this.#records.has(reference);
+	}
+	#description(node, captured) {
+		return this.#descriptions.get(node) ?? captured;
+	}
+};
+//#endregion
+//#region src/browser/BrowserDOMView.ts
+/**
+* Reads and drives a DOM document from a realm that can reach it, without trusted input.
+*
+* @remarks
+* The view follows the window of the document it was given, so after that window navigates it
+* drives the window's next document. A reading records the view's navigation epoch, and reports
+* stale after the epoch advances. The epoch advances on the Navigation API's `navigatesuccess`
+* where the window has that API, on `popstate` and `hashchange` where it does not, on `pagehide`,
+* and when the window's document changes. A `pushState` in a window without the Navigation API
+* fires none of those events, so a reading there stays current across it. A cross-document
+* navigation also clears every element reference. `destroy()` releases the listeners and every
+* reference, and fails every pending wait with a `BrowserError` coded
+* `BROWSER_DOCUMENT_DESTROYED`; after it, `title()`, `read()`, `wait()`, and the element manager's
+* `outline()`, `find()`, and `wait()` reject with that error, and a second `destroy()` does
+* nothing more. `trusted` is `false`: no action grants user activation, and
+* every event the view's actions dispatch themselves carries `isTrusted` `false`. The `submit`
+* event that `requestSubmit()` fires during a `submit` is generated by the browser and carries
+* `isTrusted` `true`.
+*
+* @example
+* ```ts
+* const view = createBrowserDOMView({ document: frame.contentDocument })
+* const reading = await view.read()
+* reading.text().text
+* ```
+*/
+var BrowserDOMView = class {
+	#window;
+	#elements;
+	#release = new AbortController();
+	#navigateHandler = this.#navigate.bind(this);
+	#document;
+	#epoch = 0;
+	#listeners = new AbortController();
+	constructor(options) {
+		const document = options.document;
+		if (!isBrowserDocument(document) || document.defaultView === null) throw new BrowserError("Browser DOM view requires a document attached to a window", "BROWSER_DOCUMENT");
+		if (document === globalThis.document && options.own !== true) throw new BrowserError("Browser DOM view drives globalThis.document only with own: true, because an action that navigates the realm it runs in cannot return", "BROWSER_DOCUMENT_OWN");
+		this.#window = document.defaultView;
+		this.#document = document;
+		this.#elements = new BrowserDOMElementManager({
+			document: this.#current.bind(this),
+			navigation: this.#navigation.bind(this),
+			signal: this.#release.signal
+		});
+		this.#listen();
+	}
+	get url() {
+		return this.#current().URL;
+	}
+	get trusted() {
+		return false;
+	}
+	get elements() {
+		return this.#elements;
+	}
+	async title(options) {
+		this.#release.signal.throwIfAborted();
+		options?.signal?.throwIfAborted();
+		return this.#current().title;
+	}
+	async read(options) {
+		this.#release.signal.throwIfAborted();
+		options?.signal?.throwIfAborted();
+		return createBrowserReading({
+			...readBrowserCapture(this.#current().documentElement),
+			navigation: this.#navigation.bind(this)
+		});
+	}
+	async wait(text, options) {
+		this.#release.signal.throwIfAborted();
+		const start = performance.now();
+		const timeout = options?.timeout ?? 5e3;
+		validateBrowserTimeout(timeout);
+		const document = this.#current();
+		await new BrowserDOMWait({
+			roots: collectBrowserRoots.bind(void 0, document),
+			check: this.#contains.bind(this, document, text),
+			timeout,
+			start,
+			signal: options?.signal === void 0 ? this.#release.signal : AbortSignal.any([options.signal, this.#release.signal]),
+			subject: "Browser text wait"
+		}).execute();
+	}
+	destroy() {
+		this.#release.abort(new BrowserError("Browser DOM view was destroyed", "BROWSER_DOCUMENT_DESTROYED"));
+		this.#listeners.abort();
+		this.#elements.clear();
+	}
+	#current() {
+		const document = this.#window.document;
+		if (document !== this.#document && !this.#release.signal.aborted) {
+			this.#document = document;
+			this.#navigate();
+			this.#listen();
+		}
+		return this.#document;
+	}
+	#navigation() {
+		this.#current();
+		return this.#epoch;
+	}
+	#navigate(event) {
+		this.#epoch += 1;
+		if (event === void 0 || event.type === "pagehide") this.#elements.clear();
+	}
+	#contains(document, text) {
+		return (document.body?.innerText ?? "").includes(text) ? true : void 0;
+	}
+	#listen() {
+		this.#listeners.abort();
+		this.#listeners = new AbortController();
+		listenBrowserNavigation(this.#window, this.#navigateHandler, this.#listeners.signal);
+	}
+};
+//#endregion
+//#region src/browser/transports/SocketCDPTransport.ts
+/**
+* Provides a raw CDP text transport over the browser's native `WebSocket`.
+*
+* @remarks
+* `start()` resolves on the socket's `open` event and rejects with a `BrowserConnectionError`
+* carrying `url` for a URL whose scheme is not `ws:` or `wss:`, for a URL the `WebSocket`
+* constructor refuses (one with a fragment), for a socket that fails or closes before it opens,
+* and at the `timeout` deadline. Concurrent and repeated `start()` and `close()`
+* calls share their active transition, and a later `start()` opens a fresh socket after the
+* prior one closes. A close the remote end initiates emits `close`. The driven Chromium must
+* allow the caller's origin through `--remote-allow-origins`.
+*
+* @example
+* ```ts
+* const transport = new SocketCDPTransport({ url: 'ws://127.0.0.1:9222/devtools/browser/abc' })
+* await transport.start()
+* await transport.close()
+* ```
+*/
+var SocketCDPTransport = class {
+	#emitter;
+	#url;
+	#timeout;
+	#starting = new BrowserTransition();
+	#closing = new BrowserTransition();
+	#socket;
+	#opening;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			...options.on !== void 0 ? { on: options.on } : {},
+			...options.error !== void 0 ? { error: options.error } : {}
+		});
+		this.#url = options.url;
+		this.#timeout = options.timeout ?? BROWSER_DEFAULT_TIMEOUT_MS;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	async start() {
+		const closing = this.#closing.pending;
+		if (closing !== void 0) await closing;
+		if (this.#socket?.readyState === WebSocket.OPEN) return;
+		const active = this.#starting.pending;
+		if (active !== void 0) {
+			await active;
+			return;
+		}
+		await this.#starting.execute(this.#start.bind(this));
+	}
+	async send(data) {
+		const socket = this.#socket;
+		if (socket === void 0 || socket.readyState !== WebSocket.OPEN) throw new BrowserConnectionError("Socket CDP transport is not open", { url: this.#url });
+		socket.send(data);
+	}
+	async close() {
+		await this.#closing.execute(this.#close.bind(this));
+	}
+	async #start() {
+		const parsed = attempt(() => new URL(this.#url));
+		if (!parsed.success) throw new BrowserConnectionError(`Socket CDP URL is invalid: ${this.#url}`, {
+			url: this.#url,
+			error: parsed.error
+		});
+		if (parsed.value.protocol !== "ws:" && parsed.value.protocol !== "wss:") throw new BrowserConnectionError(`Socket CDP connection requires a ws: or wss: URL: ${this.#url}`, { url: this.#url });
+		const created = attempt(() => new WebSocket(this.#url));
+		if (!created.success) throw new BrowserConnectionError(`Socket CDP connection to ${this.#url} could not open`, {
+			url: this.#url,
+			error: created.error
+		});
+		const socket = created.value;
+		this.#socket = socket;
+		const opened = Promise.withResolvers();
+		this.#opening = opened;
+		const release = new AbortController();
+		const options = { signal: release.signal };
+		socket.addEventListener("open", () => opened.resolve(), options);
+		socket.addEventListener("error", () => opened.reject(this.#refuse("failed")), options);
+		socket.addEventListener("close", () => opened.reject(this.#refuse("closed before it opened")), options);
+		const timer = setTimeout(() => {
+			opened.reject(this.#refuse(`timed out after ${this.#timeout}ms`));
+		}, this.#timeout);
+		try {
+			await opened.promise;
+		} catch (error) {
+			if (this.#socket === socket) this.#socket = void 0;
+			socket.close();
+			throw error;
+		} finally {
+			if (this.#opening === opened) this.#opening = void 0;
+			clearTimeout(timer);
+			release.abort();
+		}
+		this.#bind(socket);
+	}
+	async #close() {
+		this.#opening?.reject(this.#refuse("was closed before it finished connecting"));
+		const socket = this.#socket;
+		this.#socket = void 0;
+		if (socket === void 0 || socket.readyState === WebSocket.CLOSED) {
+			await this.#starting.pending?.catch(() => void 0);
+			return;
+		}
+		const closed = Promise.withResolvers();
+		socket.addEventListener("close", () => closed.resolve(), { once: true });
+		socket.close();
+		await this.#starting.pending?.catch(() => void 0);
+		await closed.promise;
+	}
+	#bind(socket) {
+		socket.binaryType = "arraybuffer";
+		socket.addEventListener("message", (event) => {
+			const data = event.data;
+			if (isString(data)) this.#emitter.emit("message", data);
+			else if (data instanceof ArrayBuffer) this.#emitter.emit("message", new TextDecoder().decode(data));
+		});
+		socket.addEventListener("close", () => {
+			if (this.#socket === socket) this.#socket = void 0;
+			this.#emitter.emit("close");
+		});
+		socket.addEventListener("error", () => {
+			this.#emitter.emit("error", this.#refuse("failed"));
+		});
+	}
+	#refuse(reason) {
+		return new BrowserConnectionError(`Socket CDP connection to ${this.#url} ${reason}`, { url: this.#url });
+	}
+};
+//#endregion
+//#region src/browser/factories.ts
+/**
+* Creates a view that reads and drives a DOM document without trusted input.
+*
+* @param options - The driven document, and `own` to admit the realm's own document
+* @returns A {@link BrowserDOMViewInterface} over the document's window
+* @throws Thrown when `document` is not a document attached to a window, with the code
+* `BROWSER_DOCUMENT`, and when it is `globalThis.document` without `own: true`, with the code
+* `BROWSER_DOCUMENT_OWN`.
+*
+* @example
+* ```ts
+* const frame = document.createElement('iframe')
+* document.body.append(frame)
+* const view = createBrowserDOMView({ document: frame.contentDocument })
+* await view.elements.outline() // { text: 'page "" about:blank\n(0 of 0 elements)', … }
+* ```
+*/
+function createBrowserDOMView(options) {
+	return new BrowserDOMView(options);
+}
+/**
+* Creates a `BrowserToolsetInterface` that publishes the five view tools over a DOM document and
+* adopts a source's page tools beside them.
+*
+* @remarks
+* The toolset runs over a view {@link createBrowserDOMView} creates for `document`, so it
+* advertises `look`, `read`, `click`, `type`, and `wait`, and a click or type receipt ends with
+* ` (untrusted event)`. `source` supplies page tools, which the toolset adopts during `start()`
+* and again on every `change`; `toolset.native` never includes them, so publishing it to a
+* registry leaves that registry's own tools alone. The view belongs to the toolset: `destroy()`
+* removes the toolset's tools, then destroys the view, which releases its listeners and fails
+* its pending waits, and a construction that throws destroys the view before it rethrows.
+* `journeys` adds `record`, `save`, `journeys`, `edit`, and `replay` at construction; a replay
+* runs the steps the document placement executes.
+*
+* @param options - The driven document, `own`, the page-tool source, the manager, the bound, the
+* journey stores, and the emitter hooks
+* @returns A {@link BrowserToolsetInterface} whose `view` drives the document
+* @throws Thrown when `document` is not a document attached to a window, with the code
+* `BROWSER_DOCUMENT`, when it is `globalThis.document` without `own: true`, with the code
+* `BROWSER_DOCUMENT_OWN`, and when `limit` is not a positive integer.
+*
+* @example
+* ```ts
+* const toolset = createDocumentToolset({ document: frame.contentDocument, source: bridge })
+* await toolset.start()
+* await toolset.tools.execute({ id: '1', name: 'look', arguments: { what: 'form' } })
+* ```
+*/
+function createDocumentToolset(options) {
+	const view = createBrowserDOMView({
+		document: options.document,
+		...options.own === void 0 ? {} : { own: options.own }
+	});
+	try {
+		return new BrowserToolset(view, {
+			...options.on === void 0 ? {} : { on: options.on },
+			...options.error === void 0 ? {} : { error: options.error },
+			...options.tools === void 0 ? {} : { tools: options.tools },
+			...options.source === void 0 ? {} : { source: options.source },
+			...options.limit === void 0 ? {} : { limit: options.limit },
+			...options.journeys === void 0 ? {} : { journeys: options.journeys },
+			release: view.destroy.bind(view)
+		});
+	} catch (error) {
+		view.destroy();
+		throw error;
+	}
+}
+/**
+* Creates a CDP transport over the browser's native `WebSocket`.
+*
+* @param options - The CDP WebSocket debugger URL, the opening deadline, and emitter hooks
+* @returns A {@link CDPTransportInterface} a `CDPClient` sends and receives frames over
+*
+* @example
+* ```ts
+* const client = createCDPClient({
+* 	transport: createSocketCDPTransport({ url: 'ws://127.0.0.1:9222/devtools/browser/abc' }),
+* })
+* await client.connect()
+* ```
+*/
+function createSocketCDPTransport(options) {
+	return new SocketCDPTransport(options);
+}
+//#endregion
+export { BROWSER_CONTENT_NAMED_ROLES, BROWSER_CONTEXT_TARGETS, BROWSER_DOCUMENT_TIMEOUT_MS, BROWSER_IMPLICIT_ROLES, BROWSER_INTERACTIVE_CONTENT, BROWSER_TYPED_INPUTS, BrowserDOMElement, BrowserDOMElementManager, BrowserDOMView, BrowserDOMWait, SocketCDPTransport, collectBrowserRoots, computeBrowserAlternative, computeBrowserName, computeBrowserRole, computeBrowserText, createBrowserDOMView, createDocumentToolset, createSocketCDPTransport, isBrowserDocument, listenBrowserNavigation, matchesBrowserActivation, matchesBrowserBlock, matchesBrowserHidden, matchesBrowserInvisible, matchesBrowserOmitted, matchesBrowserPopup, readBrowserBlock, readBrowserCapture, readBrowserContent, readBrowserParent, skipBrowserSubtree };
+
+//# sourceMappingURL=index.js.map