@orkestrel/browser 0.0.7 → 0.0.9

package/dist/src/core/index.js

@@ -1,5 +1,6 @@
-import { attempt, instanceOf, isArray, isBoolean, isFiniteNumber, isInstance, isInteger, isRecord, isString, parseArray, parseEnum, parseJSON } from "@orkestrel/contract";
+import { attempt, instanceOf, isArray, isBoolean, isFiniteNumber, isFunction, isInstance, isInteger, isRecord, isString, parseArray, parseEnum, parseJSON } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
+import { createHTML, renderText } from "@orkestrel/html";
 //#region src/core/constants.ts
 /** Base64 alphabet, index-ordered, used to build {@link BASE64_LOOKUP}. */
 var BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -74,7 +75,7 @@ var BROWSER_MOUSE_BUTTON_MASKS = Object.freeze({
 /** Tool identity embedded in HAR 1.2 documents. */
 var BROWSER_HAR_CREATOR = Object.freeze({
 	name: "@orkestrel/browser",
-	version: "0.0.5"
+	version: "0.0.8"
 });
 /** Attribute used to tag temporary screenshot styles and masks. */
 var BROWSER_SCREENSHOT_ATTRIBUTE = "data-orkestrel-screenshot";
@@ -2822,326 +2823,6 @@ function decodeBrowserSnapshot(value, styles = [], limit = BROWSER_SNAPSHOT_NODE
 	};
 }
 /**
-* Lazily walk every captured browser node in structural depth-first order.
-*
-* @remarks
-* Iframe content documents are entered at their owner element. Orphaned or
-* cyclic protocol nodes are still yielded once through an identity guard.
-*
-* @param snapshot - Captured browser snapshot
-* @returns A lazy node generator
-*/
-function* walkBrowserSnapshot(snapshot) {
-	const seeds = [];
-	for (const document of snapshot.documents) seeds.push(...document.nodes.filter((node) => node.parent === void 0));
-	for (const document of snapshot.documents) seeds.push(...document.nodes);
-	const visited = /* @__PURE__ */ new Set();
-	for (const seed of seeds) {
-		const stack = [seed];
-		while (stack.length > 0) {
-			const node = stack.pop();
-			if (node === void 0) break;
-			const identity = `${node.document}:${node.index}`;
-			if (visited.has(identity)) continue;
-			visited.add(identity);
-			yield node;
-			const children = childrenOfBrowserNode(snapshot, node);
-			for (let index = children.length - 1; index >= 0; index -= 1) {
-				const child = children[index];
-				if (child !== void 0) stack.push(child);
-			}
-		}
-	}
-}
-/**
-* Lazily walk every captured node in structural breadth-first order.
-*
-* @param snapshot - Captured browser snapshot
-* @returns A lazy breadth-first generator
-*/
-function* walkBrowserSnapshotBreadthFirst(snapshot) {
-	const seeds = [];
-	for (const document of snapshot.documents) seeds.push(...document.nodes.filter((node) => node.parent === void 0));
-	for (const document of snapshot.documents) seeds.push(...document.nodes);
-	const visited = /* @__PURE__ */ new Set();
-	for (const seed of seeds) {
-		const queue = [seed];
-		let cursor = 0;
-		while (cursor < queue.length) {
-			const node = queue[cursor];
-			cursor += 1;
-			if (node === void 0) continue;
-			const identity = `${node.document}:${node.index}`;
-			if (visited.has(identity)) continue;
-			visited.add(identity);
-			yield node;
-			queue.push(...childrenOfBrowserNode(snapshot, node));
-		}
-	}
-}
-/**
-* Lazily walk one captured browser-node subtree in depth-first order.
-*
-* @param snapshot - Captured browser snapshot
-* @param root - Root node, included as the first result
-* @returns A lazy subtree generator
-*/
-function* walkBrowserNode(snapshot, root) {
-	const stack = [root];
-	const visited = /* @__PURE__ */ new Set();
-	while (stack.length > 0) {
-		const node = stack.pop();
-		if (node === void 0) break;
-		const identity = `${node.document}:${node.index}`;
-		if (visited.has(identity)) continue;
-		visited.add(identity);
-		yield node;
-		const children = childrenOfBrowserNode(snapshot, node);
-		for (let index = children.length - 1; index >= 0; index -= 1) {
-			const child = children[index];
-			if (child !== void 0) stack.push(child);
-		}
-	}
-}
-/**
-* Lazily walk one captured browser-node subtree in breadth-first order.
-*
-* @param snapshot - Captured browser snapshot
-* @param root - Root node, included as the first result
-* @returns A lazy breadth-first subtree generator
-*/
-function* walkBrowserNodeBreadthFirst(snapshot, root) {
-	const queue = [root];
-	const visited = /* @__PURE__ */ new Set();
-	let cursor = 0;
-	while (cursor < queue.length) {
-		const node = queue[cursor];
-		cursor += 1;
-		if (node === void 0) continue;
-		const identity = `${node.document}:${node.index}`;
-		if (visited.has(identity)) continue;
-		visited.add(identity);
-		yield node;
-		queue.push(...childrenOfBrowserNode(snapshot, node));
-	}
-}
-/**
-* Lazily walk descendants of one captured node, excluding the node itself.
-*
-* @param snapshot - Captured browser snapshot
-* @param root - Root whose descendants are required
-* @returns A lazy descendant generator
-*/
-function* descendantsOfBrowserNode(snapshot, root) {
-	let first = true;
-	for (const node of walkBrowserNode(snapshot, root)) {
-		if (first) {
-			first = false;
-			continue;
-		}
-		yield node;
-	}
-}
-/**
-* Resolve the document containing a browser node.
-*
-* @param snapshot - Captured browser snapshot
-* @param node - Node whose document is required
-* @returns The containing document, or undefined
-*/
-function documentOfBrowserNode(snapshot, node) {
-	return snapshot.documents.find((document) => document.index === node.document);
-}
-/**
-* Return direct children of a captured browser node.
-*
-* @remarks
-* Includes the root nodes of an iframe's linked content document. Shadow DOM
-* and template content already carry flattened parent indexes from CDP.
-*
-* @param snapshot - Captured browser snapshot
-* @param node - Parent node
-* @returns Direct children in snapshot order
-*/
-function childrenOfBrowserNode(snapshot, node) {
-	const document = documentOfBrowserNode(snapshot, node);
-	if (document === void 0) return [];
-	const children = document.nodes.filter((candidate) => candidate.parent === node.index);
-	if (node.content === void 0) return children;
-	const content = snapshot.documents.find((candidate) => candidate.index === node.content);
-	if (content === void 0) return children;
-	return [...children, ...content.nodes.filter((candidate) => candidate.parent === void 0)];
-}
-/**
-* Resolve the structural parent of a captured browser node.
-*
-* @remarks
-* An iframe content-document root resolves to its owning iframe node.
-*
-* @param snapshot - Captured browser snapshot
-* @param node - Child node
-* @returns Parent node, or undefined for a top-level document root
-*/
-function parentOfBrowserNode(snapshot, node) {
-	const document = documentOfBrowserNode(snapshot, node);
-	if (document === void 0) return void 0;
-	return node.parent === void 0 ? findBrowserNode(snapshot, (candidate) => candidate.content === node.document) : document.nodes[node.parent];
-}
-/**
-* Return every structural sibling except the supplied browser node.
-*
-* @param snapshot - Captured browser snapshot
-* @param node - Node whose siblings are required
-* @returns Siblings in structural order
-*/
-function siblingsOfBrowserNode(snapshot, node) {
-	const parent = parentOfBrowserNode(snapshot, node);
-	return (parent === void 0 ? documentOfBrowserNode(snapshot, node)?.nodes.filter((candidate) => candidate.parent === void 0) ?? [] : childrenOfBrowserNode(snapshot, parent)).filter((candidate) => candidate.document !== node.document || candidate.index !== node.index);
-}
-/**
-* Return structural siblings before the supplied browser node.
-*
-* @param snapshot - Captured browser snapshot
-* @param node - Reference node
-* @returns Earlier siblings in structural order
-*/
-function precedingSiblingsOfBrowserNode(snapshot, node) {
-	const parent = parentOfBrowserNode(snapshot, node);
-	const candidates = parent === void 0 ? documentOfBrowserNode(snapshot, node)?.nodes.filter((candidate) => candidate.parent === void 0) ?? [] : childrenOfBrowserNode(snapshot, parent);
-	const index = candidates.findIndex((candidate) => candidate.document === node.document && candidate.index === node.index);
-	return index < 0 ? [] : candidates.slice(0, index);
-}
-/**
-* Return structural siblings after the supplied browser node.
-*
-* @param snapshot - Captured browser snapshot
-* @param node - Reference node
-* @returns Later siblings in structural order
-*/
-function followingSiblingsOfBrowserNode(snapshot, node) {
-	const parent = parentOfBrowserNode(snapshot, node);
-	const candidates = parent === void 0 ? documentOfBrowserNode(snapshot, node)?.nodes.filter((candidate) => candidate.parent === void 0) ?? [] : childrenOfBrowserNode(snapshot, parent);
-	const index = candidates.findIndex((candidate) => candidate.document === node.document && candidate.index === node.index);
-	return index < 0 ? [] : candidates.slice(index + 1);
-}
-/**
-* Return the nearest-first ancestor chain for a captured browser node.
-*
-* @param snapshot - Captured browser snapshot
-* @param node - Descendant node
-* @returns Nearest-first ancestor list
-*/
-function ancestorsOfBrowserNode(snapshot, node) {
-	const ancestors = [];
-	const visited = /* @__PURE__ */ new Set();
-	let current = node;
-	while (true) {
-		const parent = parentOfBrowserNode(snapshot, current);
-		if (parent === void 0) break;
-		const identity = `${parent.document}:${parent.index}`;
-		if (visited.has(identity)) break;
-		visited.add(identity);
-		ancestors.push(parent);
-		current = parent;
-	}
-	return ancestors;
-}
-/**
-* Test whether one captured node is below another across frame boundaries.
-*
-* @param snapshot - Captured browser snapshot
-* @param node - Candidate descendant
-* @param ancestor - Candidate ancestor
-* @returns Whether the relationship exists
-*/
-function isBrowserNodeDescendant(snapshot, node, ancestor) {
-	return ancestorsOfBrowserNode(snapshot, node).some((candidate) => candidate.document === ancestor.document && candidate.index === ancestor.index);
-}
-/**
-* Resolve the nearest common ancestor of two captured browser nodes.
-*
-* @param snapshot - Captured browser snapshot
-* @param first - First node
-* @param second - Second node
-* @returns Common ancestor, or undefined
-*/
-function commonAncestorOfBrowserNodes(snapshot, first, second) {
-	const firstAncestors = [first, ...ancestorsOfBrowserNode(snapshot, first)];
-	const secondAncestors = [second, ...ancestorsOfBrowserNode(snapshot, second)];
-	const identities = new Set(firstAncestors.map((node) => `${node.document}:${node.index}`));
-	return secondAncestors.find((node) => identities.has(`${node.document}:${node.index}`));
-}
-/**
-* Compute the edge count between two captured browser nodes.
-*
-* @param snapshot - Captured browser snapshot
-* @param first - First node
-* @param second - Second node
-* @returns Tree distance, or undefined when no common ancestor exists
-*/
-function computeBrowserNodeDistance(snapshot, first, second) {
-	const common = commonAncestorOfBrowserNodes(snapshot, first, second);
-	if (common === void 0) return void 0;
-	const firstPath = [first, ...ancestorsOfBrowserNode(snapshot, first)];
-	const secondPath = [second, ...ancestorsOfBrowserNode(snapshot, second)];
-	const firstDistance = firstPath.findIndex((node) => node.document === common.document && node.index === common.index);
-	const secondDistance = secondPath.findIndex((node) => node.document === common.document && node.index === common.index);
-	if (firstDistance < 0 || secondDistance < 0) return void 0;
-	return firstDistance + secondDistance;
-}
-/**
-* Find the first captured node satisfying a predicate.
-*
-* @param snapshot - Captured browser snapshot
-* @param predicate - Node predicate
-* @returns First matching node, or undefined
-*/
-function findBrowserNode(snapshot, predicate) {
-	for (const node of walkBrowserSnapshot(snapshot)) if (predicate(node)) return node;
-}
-/**
-* Find captured nodes satisfying a predicate.
-*
-* @param snapshot - Captured browser snapshot
-* @param predicate - Node predicate
-* @param limit - Optional maximum result count
-* @returns Matching nodes in snapshot order
-*/
-function findBrowserNodes(snapshot, predicate, limit) {
-	if (limit !== void 0 && (!isInteger(limit) || limit < 0)) throw new BrowserError("Browser node result limit must be a non-negative integer", void 0, { limit });
-	if (limit === 0) return [];
-	const found = [];
-	for (const node of walkBrowserSnapshot(snapshot)) {
-		if (!predicate(node)) continue;
-		found.push(node);
-		if (limit !== void 0 && found.length >= limit) break;
-	}
-	return found;
-}
-/**
-* Find the first matching descendant beneath one captured node.
-*
-* @param snapshot - Captured browser snapshot
-* @param root - Root whose descendants are searched
-* @param predicate - Node predicate
-* @returns First matching descendant, or undefined
-*/
-function findBrowserDescendant(snapshot, root, predicate) {
-	for (const node of descendantsOfBrowserNode(snapshot, root)) if (predicate(node)) return node;
-}
-/**
-* Find the nearest matching node from the candidate through its ancestors.
-*
-* @param snapshot - Captured browser snapshot
-* @param node - Starting node, included in the search
-* @param predicate - Node predicate
-* @returns Closest matching node, or undefined
-*/
-function closestBrowserNode(snapshot, node, predicate) {
-	if (predicate(node)) return node;
-	return ancestorsOfBrowserNode(snapshot, node).find(predicate);
-}
-/**
 * Read one captured node attribute.
 *
 * @param node - Captured browser node
@@ -3152,6 +2833,23 @@ function attributeOfBrowserNode(node, name) {
 	return node.attributes[name];
 }
 /**
+* Test whether a browser-node matcher is a declarative query.
+*
+* @param value - Browser-node query or predicate
+* @returns Whether the matcher is a declarative query
+*
+* @example
+* ```ts
+* import { isBrowserNodeQuery } from '@src/core'
+*
+* isBrowserNodeQuery({ name: 'main' }) // true
+* isBrowserNodeQuery(() => true) // false
+* ```
+*/
+function isBrowserNodeQuery(value) {
+	return !isFunction(value);
+}
+/**
 * Test a captured node against a declarative query.
 *
 * @param node - Captured browser node
@@ -3179,36 +2877,6 @@ function isBrowserNodeVisible(node) {
 	const bounds = node.layout?.bounds;
 	return bounds !== void 0 && bounds[2] > 0 && bounds[3] > 0;
 }
-/**
-* Build a deterministic, serializable path for a captured browser node.
-*
-* @param snapshot - Captured browser snapshot
-* @param node - Captured browser node
-* @returns Frame-qualified structural path
-*/
-function nodeToPath(snapshot, node) {
-	const document = documentOfBrowserNode(snapshot, node);
-	if (document === void 0) return `document:${node.document} > node:${node.index}`;
-	const chain = [...ancestorsOfBrowserNode(snapshot, node)].reverse();
-	chain.push(node);
-	const segments = [];
-	for (const current of chain) {
-		if (current.type !== 1) {
-			segments.push(`${current.name.toLowerCase()}:${current.index}`);
-			continue;
-		}
-		let ordinal = 1;
-		if (current.parent !== void 0) {
-			const owner = documentOfBrowserNode(snapshot, current);
-			for (const sibling of owner?.nodes ?? []) {
-				if (sibling.index >= current.index) break;
-				if (sibling.parent === current.parent && sibling.name === current.name) ordinal += 1;
-			}
-		}
-		segments.push(`${current.name.toLowerCase()}:${ordinal}`);
-	}
-	return `frame(${JSON.stringify(document.frame)}) > ${segments.join(" > ")}`;
-}
 //#endregion
 //#region src/core/CDPClient.ts
 /**
@@ -5011,9 +4679,7 @@ var BrowserLocator = class BrowserLocator {
 			case "enabled":
 				expression = `(() => { const element = ${compileLocatorExpression(this.#query)}; return Boolean(element && !element.matches(':disabled')) })()`;
 				break;
-			case "editable":
-				expression = `(() => { const element = ${compileLocatorExpression(this.#query)}; return Boolean(element && !element.matches(':disabled,[readonly]') && (element.isContentEditable || 'value' in element)) })()`;
-				break;
+			case "editable": expression = `(() => { const element = ${compileLocatorExpression(this.#query)}; return Boolean(element && !element.matches(':disabled,[readonly]') && (element.isContentEditable || 'value' in element)) })()`;
 		}
 		return await this.#frame.evaluate(expression) === true;
 	}
@@ -5174,7 +4840,7 @@ var BrowserFrame = class {
 		this.assert();
 		const [title, html, text, currentUrl] = await Promise.all([
 			this.#evaluate("document.title"),
-			this.#evaluate(guardEvaluateExpression("document.documentElement.outerHTML", BROWSER_RESULT_LIMIT)),
+			this.#captureHTML(),
 			this.#evaluate(guardEvaluateExpression("document.body ? document.body.innerText : \"\"", BROWSER_RESULT_LIMIT)),
 			this.#evaluate("location.href")
 		]);
@@ -5187,6 +4853,11 @@ var BrowserFrame = class {
 			text: requireBrowserString(text, "Document text")
 		};
 	}
+	async article() {
+		this.assert();
+		const html = requireBrowserString(await this.#captureHTML(), "Document HTML");
+		return renderText(createHTML(html).distill().document);
+	}
 	async click(selector, options) {
 		this.assert();
 		await this.#selectors.css(selector).click(options);
@@ -5247,6 +4918,9 @@ var BrowserFrame = class {
 	update(url) {
 		this.#url = url;
 	}
+	async #captureHTML() {
+		return await this.#evaluate(guardEvaluateExpression("document.documentElement.outerHTML", BROWSER_RESULT_LIMIT));
+	}
 	async #evaluate(expression, timeout) {
 		const session = await this.#sessionId();
 		const params = {
@@ -6074,6 +5748,189 @@ var BrowserScriptManager = class {
 	}
 };
 //#endregion
+//#region src/core/BrowserSnapshot.ts
+/** A navigable, serializable browser DOM snapshot. */
+var BrowserSnapshot = class {
+	#owners;
+	documents;
+	styles;
+	constructor(input) {
+		this.documents = Object.freeze([...input.documents]);
+		this.styles = Object.freeze([...input.styles]);
+	}
+	walk(options) {
+		return options?.order === "breadth" ? this.#breadth(options.root) : this.#depth(options?.root);
+	}
+	*descendants(node) {
+		let first = true;
+		for (const descendant of this.#depth(node)) {
+			if (first) {
+				first = false;
+				continue;
+			}
+			yield descendant;
+		}
+	}
+	document(node) {
+		return this.documents.find((document) => document.index === node.document);
+	}
+	children(node) {
+		const document = this.document(node);
+		if (document === void 0) return [];
+		const children = document.nodes.filter((candidate) => candidate.parent === node.index);
+		if (node.content === void 0) return children;
+		const content = this.documents.find((candidate) => candidate.index === node.content);
+		if (content === void 0) return children;
+		return [...children, ...content.nodes.filter((candidate) => candidate.parent === void 0)];
+	}
+	parent(node) {
+		const document = this.document(node);
+		if (document === void 0) return void 0;
+		return node.parent === void 0 ? this.#owner(node.document) : document.nodes[node.parent];
+	}
+	siblings(node, relation) {
+		const candidates = this.#candidates(node);
+		const index = candidates.findIndex((candidate) => candidate.document === node.document && candidate.index === node.index);
+		if (relation === "preceding") return index < 0 ? [] : candidates.slice(0, index);
+		if (relation === "following") return index < 0 ? [] : candidates.slice(index + 1);
+		return candidates.filter((candidate) => candidate.document !== node.document || candidate.index !== node.index);
+	}
+	ancestors(node) {
+		const ancestors = [];
+		const visited = /* @__PURE__ */ new Set();
+		let current = node;
+		while (true) {
+			const parent = this.parent(current);
+			if (parent === void 0) break;
+			const identity = this.#identity(parent);
+			if (visited.has(identity)) break;
+			visited.add(identity);
+			ancestors.push(parent);
+			current = parent;
+		}
+		return ancestors;
+	}
+	common(first, second) {
+		const firstAncestors = this.#chain(first);
+		const secondAncestors = this.#chain(second);
+		const identities = new Set(firstAncestors.map((node) => this.#identity(node)));
+		return secondAncestors.find((node) => identities.has(this.#identity(node)));
+	}
+	distance(first, second) {
+		const common = this.common(first, second);
+		if (common === void 0) return void 0;
+		const identity = this.#identity(common);
+		const firstDistance = this.#chain(first).findIndex((node) => this.#identity(node) === identity);
+		const secondDistance = this.#chain(second).findIndex((node) => this.#identity(node) === identity);
+		if (firstDistance < 0 || secondDistance < 0) return void 0;
+		return firstDistance + secondDistance;
+	}
+	find(query) {
+		for (const node of this.walk()) if (this.#match(node, query)) return node;
+	}
+	filter(query, limit) {
+		if (limit !== void 0 && (!isInteger(limit) || limit < 0)) throw new BrowserError("Browser node result limit must be a non-negative integer", void 0, { limit });
+		if (limit === 0) return [];
+		const found = [];
+		for (const node of this.walk()) {
+			if (!this.#match(node, query)) continue;
+			found.push(node);
+			if (limit !== void 0 && found.length >= limit) break;
+		}
+		return found;
+	}
+	closest(node, query) {
+		if (this.#match(node, query)) return node;
+		for (const ancestor of this.ancestors(node)) if (this.#match(ancestor, query)) return ancestor;
+	}
+	path(node) {
+		const document = this.document(node);
+		if (document === void 0) return `document:${node.document} > node:${node.index}`;
+		const chain = [...this.ancestors(node)].reverse();
+		chain.push(node);
+		const segments = [];
+		for (const current of chain) {
+			if (current.type !== 1) {
+				segments.push(`${current.name.toLowerCase()}:${current.index}`);
+				continue;
+			}
+			let ordinal = 1;
+			if (current.parent !== void 0) {
+				const owner = this.document(current);
+				for (const sibling of owner?.nodes ?? []) {
+					if (sibling.index >= current.index) break;
+					if (sibling.parent === current.parent && sibling.name === current.name) ordinal += 1;
+				}
+			}
+			segments.push(`${current.name.toLowerCase()}:${ordinal}`);
+		}
+		return `frame(${JSON.stringify(document.frame)}) > ${segments.join(" > ")}`;
+	}
+	#roots() {
+		const roots = [];
+		for (const document of this.documents) roots.push(...document.nodes.filter((node) => node.parent === void 0));
+		for (const document of this.documents) roots.push(...document.nodes);
+		return roots;
+	}
+	#owner(document) {
+		const owners = this.#owners;
+		if (owners !== void 0) return owners.get(document);
+		const index = /* @__PURE__ */ new Map();
+		for (const node of this.walk()) if (node.content !== void 0 && !index.has(node.content)) index.set(node.content, node);
+		this.#owners = index;
+		return index.get(document);
+	}
+	*#depth(root) {
+		const visited = /* @__PURE__ */ new Set();
+		for (const seed of root === void 0 ? this.#roots() : [root]) {
+			const stack = [seed];
+			while (stack.length > 0) {
+				const node = stack.pop();
+				if (node === void 0) break;
+				const identity = this.#identity(node);
+				if (visited.has(identity)) continue;
+				visited.add(identity);
+				yield node;
+				const children = this.children(node);
+				for (let index = children.length - 1; index >= 0; index -= 1) {
+					const child = children[index];
+					if (child !== void 0) stack.push(child);
+				}
+			}
+		}
+	}
+	*#breadth(root) {
+		const visited = /* @__PURE__ */ new Set();
+		for (const seed of root === void 0 ? this.#roots() : [root]) {
+			const queue = [seed];
+			let cursor = 0;
+			while (cursor < queue.length) {
+				const node = queue[cursor];
+				cursor += 1;
+				if (node === void 0) continue;
+				const identity = this.#identity(node);
+				if (visited.has(identity)) continue;
+				visited.add(identity);
+				yield node;
+				queue.push(...this.children(node));
+			}
+		}
+	}
+	#candidates(node) {
+		const parent = this.parent(node);
+		return parent === void 0 ? this.document(node)?.nodes.filter((candidate) => candidate.parent === void 0) ?? [] : this.children(parent);
+	}
+	#chain(node) {
+		return [node, ...this.ancestors(node)];
+	}
+	#match(node, query) {
+		return isBrowserNodeQuery(query) ? matchesBrowserNode(node, query) : query(node);
+	}
+	#identity(node) {
+		return `${node.document}:${node.index}`;
+	}
+};
+//#endregion
 //#region src/core/BrowserWorker.ts
 /**
 * Dedicated, shared, or service worker attached through a flattened target session.
@@ -6362,11 +6219,11 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 	async snapshot(options) {
 		this.assert();
 		const styles = options?.styles ?? [];
-		return decodeBrowserSnapshot(await this.request("DOMSnapshot.captureSnapshot", {
+		return new BrowserSnapshot(decodeBrowserSnapshot(await this.request("DOMSnapshot.captureSnapshot", {
 			computedStyles: [...styles],
 			includePaintOrder: options?.paint ?? false,
 			includeDOMRects: options?.rects ?? false
-		}), styles, options?.limit ?? 1e5);
+		}), styles, options?.limit ?? 1e5));
 	}
 	async codegen(options) {
 		this.assert();
@@ -7249,7 +7106,24 @@ var BrowserContext = class {
 function createCDPClient(options) {
 	return new CDPClient(options);
 }
+/**
+* Create a navigable browser snapshot from decoded serializable data.
+*
+* @param input - Captured documents and computed-style names
+* @returns A {@link BrowserSnapshotInterface}
+*
+* @example
+* ```ts
+* import { createBrowserSnapshot, decodeBrowserSnapshot } from '@src/core'
+*
+* const snapshot = createBrowserSnapshot(decodeBrowserSnapshot(captured, ['display']))
+* snapshot.find({ name: 'main' })
+* ```
+*/
+function createBrowserSnapshot(input) {
+	return new BrowserSnapshot(input);
+}
 //#endregion
-export { BASE64_CHARS, BASE64_LOOKUP, BROWSER_CODEGEN_BINDING_NAME, BROWSER_CODEGEN_SOURCE, BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_DEFAULT_VIEWPORT_HEIGHT, BROWSER_DEFAULT_VIEWPORT_WIDTH, BROWSER_FRAME_WORLD_NAME, BROWSER_HAR_CREATOR, BROWSER_KEY_MODIFIERS, BROWSER_MOUSE_BUTTON_MASKS, BROWSER_RESULT_LIMIT, BROWSER_RESULT_LIMIT_PATTERN, BROWSER_RESULT_LIMIT_SENTINEL_PREFIX, BROWSER_SCREENSHOT_ATTRIBUTE, BROWSER_SNAPSHOT_NODE_LIMIT, BROWSER_STABLE_FRAME_COUNT, BROWSER_STOP_LOADING_TIMEOUT_MS, BROWSER_TEST_ID_ATTRIBUTE, BROWSER_WAIT_POLL_INTERVAL_MS, BrowserAccessibility, BrowserClock, BrowserCodegen, BrowserContext, BrowserCookieManager, BrowserCoverage, BrowserDiagnostics, BrowserDialog, BrowserDownload, BrowserEmulationManager, BrowserError, BrowserFileChooser, BrowserFrame, BrowserHARManager, BrowserHandle, BrowserKeyboard, BrowserLocator, BrowserMouse, BrowserNavigationManager, BrowserNetworkManager, BrowserPage, BrowserPerformance, BrowserPermissionManager, BrowserResultLimitError, BrowserRoute, BrowserScriptManager, BrowserSelectorError, BrowserSelectorManager, BrowserStorageManager, BrowserTouch, BrowserTracing, BrowserWebSocket, BrowserWorker, CDPClient, CDPConnectionError, CDPError, CDPTimeoutError, ancestorsOfBrowserNode, attributeOfBrowserNode, browserHARHeadersToRecord, browserHeadersToProtocol, browserPDFToParams, browserScreenshotToParams, bytesToText, childrenOfBrowserNode, closestBrowserNode, commonAncestorOfBrowserNodes, compileActionabilityFunction, compileAttachedLocatorWaitExpression, compileAttachedWaitExpression, compileBrowserBindingCleanup, compileBrowserBindingResult, compileBrowserBindingSource, compileClickExpression, compileCodegenScript, compileDetachedLocatorWaitExpression, compileDetachedWaitExpression, compileFillExpression, compileFunctionWaitExpression, compileHiddenLocatorWaitExpression, compileHiddenWaitExpression, compileLocatorExpression, compileLocatorListExpression, compileScreenshotCleanupExpression, compileScreenshotPreparationExpression, compileSelectExpression, compileStorageClearExpression, compileStorageReadExpression, compileStorageRestoreExpression, compileVisibleLocatorWaitExpression, compileVisibleWaitExpression, computeBrowserButtons, computeBrowserModifiers, computeBrowserNodeDistance, concatBytes, cookieToProtocol, createBrowserHAREntry, createCDPClient, decodeBase64, decodeBrowserAttributes, decodeBrowserSnapshot, decodeRareBooleanData, decodeRareIntegerData, decodeRareStringData, descendantsOfBrowserNode, documentOfBrowserNode, encodeBase64, findBrowserDescendant, findBrowserNode, findBrowserNodes, followingSiblingsOfBrowserNode, guardEvaluateExpression, isBrowserError, isBrowserNodeDescendant, isBrowserNodeVisible, isBrowserResultLimitError, isBrowserSelectorError, isCDPConnectionError, isCDPError, isCDPTimeoutError, keyToBrowserInput, matchesBrowserCookieURL, matchesBrowserNode, matchesBrowserRoute, matchesBrowserURL, mediaToFeatures, nodeToPath, normalizeCodegenActions, parentOfBrowserNode, parseBrowserChord, parseCodegenActionPayload, precedingSiblingsOfBrowserNode, readBrowserAXString, readBrowserAXValue, readBrowserAccessibility, readBrowserBindingCall, readBrowserConsoleMessage, readBrowserCookie, readBrowserCookiePartition, readBrowserCookies, readBrowserCoverageRanges, readBrowserDownloadProgress, readBrowserDownloadStart, readBrowserFrames, readBrowserHeaders, readBrowserMetrics, readBrowserPageError, readBrowserProfile, readBrowserProfileFrame, readBrowserQuad, readBrowserRect, readBrowserRemoteValue, readBrowserRequest, readBrowserRequestFailure, readBrowserResponse, readBrowserResponseRecord, readBrowserScriptCoverage, readBrowserScriptIdentifier, readBrowserSecurity, readBrowserStack, readBrowserStorageEntries, readBrowserStorageOrigin, readBrowserStreamChunk, readBrowserStyleCoverage, readBrowserTiming, readBrowserTimingRange, readBrowserWebSocketFrame, readCodegenNavigateAction, readEvaluationResult, readNumberArray, readSnapshotString, requireBrowserString, siblingsOfBrowserNode, textToBytes, validateBrowserAccessibilityOptions, validateBrowserActionOptions, validateBrowserContextOptions, validateBrowserEmulationOptions, validateBrowserHAR, validateBrowserPoint, validateBrowserRange, validateBrowserTimeout, validateBrowserViewport, walkBrowserNode, walkBrowserNodeBreadthFirst, walkBrowserSnapshot, walkBrowserSnapshotBreadthFirst };
+export { BASE64_CHARS, BASE64_LOOKUP, BROWSER_CODEGEN_BINDING_NAME, BROWSER_CODEGEN_SOURCE, BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_DEFAULT_VIEWPORT_HEIGHT, BROWSER_DEFAULT_VIEWPORT_WIDTH, BROWSER_FRAME_WORLD_NAME, BROWSER_HAR_CREATOR, BROWSER_KEY_MODIFIERS, BROWSER_MOUSE_BUTTON_MASKS, BROWSER_RESULT_LIMIT, BROWSER_RESULT_LIMIT_PATTERN, BROWSER_RESULT_LIMIT_SENTINEL_PREFIX, BROWSER_SCREENSHOT_ATTRIBUTE, BROWSER_SNAPSHOT_NODE_LIMIT, BROWSER_STABLE_FRAME_COUNT, BROWSER_STOP_LOADING_TIMEOUT_MS, BROWSER_TEST_ID_ATTRIBUTE, BROWSER_WAIT_POLL_INTERVAL_MS, BrowserAccessibility, BrowserClock, BrowserCodegen, BrowserContext, BrowserCookieManager, BrowserCoverage, BrowserDiagnostics, BrowserDialog, BrowserDownload, BrowserEmulationManager, BrowserError, BrowserFileChooser, BrowserFrame, BrowserHARManager, BrowserHandle, BrowserKeyboard, BrowserLocator, BrowserMouse, BrowserNavigationManager, BrowserNetworkManager, BrowserPage, BrowserPerformance, BrowserPermissionManager, BrowserResultLimitError, BrowserRoute, BrowserScriptManager, BrowserSelectorError, BrowserSelectorManager, BrowserSnapshot, BrowserStorageManager, BrowserTouch, BrowserTracing, BrowserWebSocket, BrowserWorker, CDPClient, CDPConnectionError, CDPError, CDPTimeoutError, attributeOfBrowserNode, browserHARHeadersToRecord, browserHeadersToProtocol, browserPDFToParams, browserScreenshotToParams, bytesToText, compileActionabilityFunction, compileAttachedLocatorWaitExpression, compileAttachedWaitExpression, compileBrowserBindingCleanup, compileBrowserBindingResult, compileBrowserBindingSource, compileClickExpression, compileCodegenScript, compileDetachedLocatorWaitExpression, compileDetachedWaitExpression, compileFillExpression, compileFunctionWaitExpression, compileHiddenLocatorWaitExpression, compileHiddenWaitExpression, compileLocatorExpression, compileLocatorListExpression, compileScreenshotCleanupExpression, compileScreenshotPreparationExpression, compileSelectExpression, compileStorageClearExpression, compileStorageReadExpression, compileStorageRestoreExpression, compileVisibleLocatorWaitExpression, compileVisibleWaitExpression, computeBrowserButtons, computeBrowserModifiers, concatBytes, cookieToProtocol, createBrowserHAREntry, createBrowserSnapshot, createCDPClient, decodeBase64, decodeBrowserAttributes, decodeBrowserSnapshot, decodeRareBooleanData, decodeRareIntegerData, decodeRareStringData, encodeBase64, guardEvaluateExpression, isBrowserError, isBrowserNodeQuery, isBrowserNodeVisible, isBrowserResultLimitError, isBrowserSelectorError, isCDPConnectionError, isCDPError, isCDPTimeoutError, keyToBrowserInput, matchesBrowserCookieURL, matchesBrowserNode, matchesBrowserRoute, matchesBrowserURL, mediaToFeatures, normalizeCodegenActions, parseBrowserChord, parseCodegenActionPayload, readBrowserAXString, readBrowserAXValue, readBrowserAccessibility, readBrowserBindingCall, readBrowserConsoleMessage, readBrowserCookie, readBrowserCookiePartition, readBrowserCookies, readBrowserCoverageRanges, readBrowserDownloadProgress, readBrowserDownloadStart, readBrowserFrames, readBrowserHeaders, readBrowserMetrics, readBrowserPageError, readBrowserProfile, readBrowserProfileFrame, readBrowserQuad, readBrowserRect, readBrowserRemoteValue, readBrowserRequest, readBrowserRequestFailure, readBrowserResponse, readBrowserResponseRecord, readBrowserScriptCoverage, readBrowserScriptIdentifier, readBrowserSecurity, readBrowserStack, readBrowserStorageEntries, readBrowserStorageOrigin, readBrowserStreamChunk, readBrowserStyleCoverage, readBrowserTiming, readBrowserTimingRange, readBrowserWebSocketFrame, readCodegenNavigateAction, readEvaluationResult, readNumberArray, readSnapshotString, requireBrowserString, textToBytes, validateBrowserAccessibilityOptions, validateBrowserActionOptions, validateBrowserContextOptions, validateBrowserEmulationOptions, validateBrowserHAR, validateBrowserPoint, validateBrowserRange, validateBrowserTimeout, validateBrowserViewport };
 
 //# sourceMappingURL=index.js.map