@jitsusama/agentic-harness.core 0.1.0

package/dist/web/snapshot/deep.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Walking a page the way it is actually built.
+ *
+ * `document.querySelectorAll` stops at a shadow boundary and at
+ * a frame boundary, which means a probe using it sees a design
+ * system's markup as a row of empty custom elements. Measured on
+ * a two-component page: the flattened snapshot reports eighteen
+ * elements and this reported five, so the visual, design, target
+ * and keyboard captures each answered questions about a page
+ * that was mostly not there. The DOM snapshot pierces both, so
+ * the same library was answering the same question two ways.
+ *
+ * These are source strings rather than functions because they
+ * are injected into the page, and the bundler renames named
+ * inner bindings through a wrapper the page has never heard of.
+ *
+ * Same-origin only, for frames. A cross-origin iframe runs in
+ * another process and its document is unreachable from page
+ * script; nothing here can change that, so the count of frames
+ * that could not be entered is reported rather than hidden.
+ */
+/**
+ * Declares `deepElements(root)` and `deepSelectorFor(el)`.
+ *
+ * `deepElements` returns every element under a root, descending
+ * through open shadow roots and same-origin frames. Closed
+ * shadow roots are not reachable by anyone, including us.
+ *
+ * `deepSelectorFor` names an element so a reader can find it
+ * again, crossing boundaries with the `>>` that Playwright and
+ * devtools both use: `my-card >> button` says the button lives
+ * inside that component's shadow root.
+ */
+export declare const DEEP_DOM = "\n\tconst __shadowOf = (el) => {\n\t\ttry { return el.shadowRoot; } catch { return null; }\n\t};\n\tconst __docOf = (el) => {\n\t\t// Reaching into a cross-origin frame throws by design.\n\t\ttry { return el.contentDocument; } catch { return null; }\n\t};\n\tlet __unreachableFrames = 0;\n\tconst deepElements = (root) => {\n\t\tconst out = [];\n\t\tconst visit = (node) => {\n\t\t\tfor (const el of node.querySelectorAll(\"*\")) {\n\t\t\t\tout.push(el);\n\t\t\t\tconst shadow = __shadowOf(el);\n\t\t\t\tif (shadow) visit(shadow);\n\t\t\t\tif (el.tagName === \"IFRAME\" || el.tagName === \"FRAME\") {\n\t\t\t\t\tconst doc = __docOf(el);\n\t\t\t\t\tif (doc && doc.documentElement) visit(doc);\n\t\t\t\t\telse __unreachableFrames++;\n\t\t\t\t}\n\t\t\t}\n\t\t};\n\t\tvisit(root || document);\n\t\treturn out;\n\t};\n\tconst __oneSelector = (el) => {\n\t\tconst tag = el.tagName.toLowerCase();\n\t\tif (el.id) return \"#\" + el.id;\n\t\tconst hook = el.getAttribute(\"data-testid\");\n\t\tif (hook) return tag + '[data-testid=\"' + hook + '\"]';\n\t\tconst first = el.classList && el.classList[0];\n\t\tif (first) return tag + \".\" + first;\n\t\tconst parent = el.parentElement;\n\t\tif (!parent) return tag;\n\t\tconst kin = [...parent.children].filter((c) => c.tagName === el.tagName);\n\t\tif (kin.length === 1) return tag;\n\t\treturn tag + \":nth-of-type(\" + (kin.indexOf(el) + 1) + \")\";\n\t};\n\t// Cross a boundary by naming the host, so the path can be\n\t// followed by hand: \"my-card >> button\".\n\tconst deepSelectorFor = (el) => {\n\t\tconst parts = [__oneSelector(el)];\n\t\tlet node = el;\n\t\tfor (let hops = 0; hops < 10; hops++) {\n\t\t\tconst root = node.getRootNode ? node.getRootNode() : null;\n\t\t\tconst host = root && root.host;\n\t\t\tconst frame = root && root.defaultView && root.defaultView.frameElement;\n\t\t\tconst crossing = host || frame;\n\t\t\tif (!crossing) break;\n\t\t\tparts.unshift(__oneSelector(crossing));\n\t\t\tnode = crossing;\n\t\t}\n\t\treturn parts.join(\" >> \");\n\t};\n";
+/** How many frames the page would not let a probe enter. */
+export declare const DEEP_UNREACHABLE = "__unreachableFrames";

package/dist/web/snapshot/deep.js

@@ -0,0 +1,91 @@
+/**
+ * Walking a page the way it is actually built.
+ *
+ * `document.querySelectorAll` stops at a shadow boundary and at
+ * a frame boundary, which means a probe using it sees a design
+ * system's markup as a row of empty custom elements. Measured on
+ * a two-component page: the flattened snapshot reports eighteen
+ * elements and this reported five, so the visual, design, target
+ * and keyboard captures each answered questions about a page
+ * that was mostly not there. The DOM snapshot pierces both, so
+ * the same library was answering the same question two ways.
+ *
+ * These are source strings rather than functions because they
+ * are injected into the page, and the bundler renames named
+ * inner bindings through a wrapper the page has never heard of.
+ *
+ * Same-origin only, for frames. A cross-origin iframe runs in
+ * another process and its document is unreachable from page
+ * script; nothing here can change that, so the count of frames
+ * that could not be entered is reported rather than hidden.
+ */
+/**
+ * Declares `deepElements(root)` and `deepSelectorFor(el)`.
+ *
+ * `deepElements` returns every element under a root, descending
+ * through open shadow roots and same-origin frames. Closed
+ * shadow roots are not reachable by anyone, including us.
+ *
+ * `deepSelectorFor` names an element so a reader can find it
+ * again, crossing boundaries with the `>>` that Playwright and
+ * devtools both use: `my-card >> button` says the button lives
+ * inside that component's shadow root.
+ */
+export const DEEP_DOM = `
+	const __shadowOf = (el) => {
+		try { return el.shadowRoot; } catch { return null; }
+	};
+	const __docOf = (el) => {
+		// Reaching into a cross-origin frame throws by design.
+		try { return el.contentDocument; } catch { return null; }
+	};
+	let __unreachableFrames = 0;
+	const deepElements = (root) => {
+		const out = [];
+		const visit = (node) => {
+			for (const el of node.querySelectorAll("*")) {
+				out.push(el);
+				const shadow = __shadowOf(el);
+				if (shadow) visit(shadow);
+				if (el.tagName === "IFRAME" || el.tagName === "FRAME") {
+					const doc = __docOf(el);
+					if (doc && doc.documentElement) visit(doc);
+					else __unreachableFrames++;
+				}
+			}
+		};
+		visit(root || document);
+		return out;
+	};
+	const __oneSelector = (el) => {
+		const tag = el.tagName.toLowerCase();
+		if (el.id) return "#" + el.id;
+		const hook = el.getAttribute("data-testid");
+		if (hook) return tag + '[data-testid="' + hook + '"]';
+		const first = el.classList && el.classList[0];
+		if (first) return tag + "." + first;
+		const parent = el.parentElement;
+		if (!parent) return tag;
+		const kin = [...parent.children].filter((c) => c.tagName === el.tagName);
+		if (kin.length === 1) return tag;
+		return tag + ":nth-of-type(" + (kin.indexOf(el) + 1) + ")";
+	};
+	// Cross a boundary by naming the host, so the path can be
+	// followed by hand: "my-card >> button".
+	const deepSelectorFor = (el) => {
+		const parts = [__oneSelector(el)];
+		let node = el;
+		for (let hops = 0; hops < 10; hops++) {
+			const root = node.getRootNode ? node.getRootNode() : null;
+			const host = root && root.host;
+			const frame = root && root.defaultView && root.defaultView.frameElement;
+			const crossing = host || frame;
+			if (!crossing) break;
+			parts.unshift(__oneSelector(crossing));
+			node = crossing;
+		}
+		return parts.join(" >> ");
+	};
+`;
+/** How many frames the page would not let a probe enter. */
+export const DEEP_UNREACHABLE = "__unreachableFrames";

package/dist/web/snapshot/flatten.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The whole page, flattened into one addressable list.
+ *
+ * The protocol hands a snapshot over as a struct of parallel
+ * arrays with every string replaced by an index into one shared
+ * table, and rare properties held as sparse pairs. That shape is
+ * excellent to transmit and impossible to reason about, so this
+ * turns it into nodes you can look at.
+ *
+ * Two things it gets for free, which are otherwise painful.
+ * Shadow content is already inline under its host, with no
+ * separate root node, and the protocol marks every node of a
+ * shadow tree rather than only its root, so piercing needs no
+ * traversal at all. And every iframe arrives as another document
+ * linked from the node that hosts it, so the whole page, frames
+ * included, is one list once they are joined.
+ *
+ * Whether a node is rendered is not inferred from its styles: it
+ * is whether the browser gave it a layout entry, which is the
+ * browser's own answer, and the only one that accounts for an
+ * ancestor being hidden.
+ */
+/** Sparse properties: the nodes that have one, and the values. */
+export interface RareValues {
+    readonly index: readonly number[];
+    readonly value?: readonly number[];
+}
+/** Node arrays, as the protocol packs them. */
+export interface RawNodes {
+    readonly parentIndex: readonly number[];
+    readonly nodeType: readonly number[];
+    readonly nodeName: readonly number[];
+    readonly nodeValue: readonly number[];
+    readonly backendNodeId: readonly number[];
+    readonly attributes: readonly (readonly number[])[];
+    readonly shadowRootType?: RareValues;
+    readonly contentDocumentIndex?: RareValues;
+    readonly isClickable?: RareValues;
+    readonly pseudoType?: RareValues;
+}
+/** Layout arrays, covering only the nodes that were rendered. */
+export interface RawLayout {
+    readonly nodeIndex: readonly number[];
+    readonly styles: readonly (readonly number[])[];
+    readonly bounds: readonly (readonly number[])[];
+    readonly text?: readonly number[];
+}
+/** One document: the page, or a frame within it. */
+export interface RawDocument {
+    readonly documentURL: number;
+    readonly title?: number;
+    readonly nodes: RawNodes;
+    readonly layout: RawLayout;
+    readonly scrollOffsetX?: number;
+    readonly scrollOffsetY?: number;
+}
+/** DOMSnapshot.captureSnapshot, as it comes back. */
+export interface RawSnapshot {
+    readonly documents: readonly RawDocument[];
+    readonly strings: readonly string[];
+}
+/** Where something is on the page. */
+export interface Bounds {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** One node, with everything known about it in one place. */
+export interface IndexedNode {
+    /** Unique across every document in the snapshot. */
+    readonly id: string;
+    readonly documentIndex: number;
+    readonly documentUrl: string;
+    readonly nodeName: string;
+    readonly nodeType: number;
+    readonly backendNodeId: number;
+    readonly attributes: Readonly<Record<string, string>>;
+    /** The id of the parent, across frame boundaries. */
+    readonly parent?: string;
+    readonly styles: Readonly<Record<string, string>>;
+    readonly bounds?: Bounds;
+    readonly text?: string;
+    readonly clickable: boolean;
+    readonly inShadow: boolean;
+    /** Whether the browser laid it out at all. */
+    readonly rendered: boolean;
+}
+/** Whether this node is an element. */
+export declare function isElement(node: IndexedNode): boolean;
+/** Whether this node is a run of text. */
+export declare function isText(node: IndexedNode): boolean;
+/**
+ * Flatten a snapshot into addressable nodes.
+ *
+ * The style property names must be given in the same order they
+ * were requested in, because the protocol returns the values as
+ * a bare array positioned against that request and never names
+ * them again.
+ */
+export declare function flattenSnapshot(snapshot: RawSnapshot, styleProperties: readonly string[]): readonly IndexedNode[];

package/dist/web/snapshot/flatten.js

@@ -0,0 +1,131 @@
+/**
+ * The whole page, flattened into one addressable list.
+ *
+ * The protocol hands a snapshot over as a struct of parallel
+ * arrays with every string replaced by an index into one shared
+ * table, and rare properties held as sparse pairs. That shape is
+ * excellent to transmit and impossible to reason about, so this
+ * turns it into nodes you can look at.
+ *
+ * Two things it gets for free, which are otherwise painful.
+ * Shadow content is already inline under its host, with no
+ * separate root node, and the protocol marks every node of a
+ * shadow tree rather than only its root, so piercing needs no
+ * traversal at all. And every iframe arrives as another document
+ * linked from the node that hosts it, so the whole page, frames
+ * included, is one list once they are joined.
+ *
+ * Whether a node is rendered is not inferred from its styles: it
+ * is whether the browser gave it a layout entry, which is the
+ * browser's own answer, and the only one that accounts for an
+ * ancestor being hidden.
+ */
+/** Node types worth naming, rather than leaving as numbers. */
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+/** Whether this node is an element. */
+export function isElement(node) {
+    return node.nodeType === ELEMENT_NODE;
+}
+/** Whether this node is a run of text. */
+export function isText(node) {
+    return node.nodeType === TEXT_NODE;
+}
+/** Turn sparse pairs into something you can ask a question of. */
+function sparse(rare) {
+    const found = new Map();
+    if (!rare)
+        return found;
+    rare.index.forEach((nodeIndex, at) => {
+        // A rare boolean has indices and no values: being listed is
+        // the whole message.
+        found.set(nodeIndex, rare.value?.[at] ?? 1);
+    });
+    return found;
+}
+/**
+ * Flatten a snapshot into addressable nodes.
+ *
+ * The style property names must be given in the same order they
+ * were requested in, because the protocol returns the values as
+ * a bare array positioned against that request and never names
+ * them again.
+ */
+export function flattenSnapshot(snapshot, styleProperties) {
+    const text = (index) => index === undefined || index < 0 ? "" : (snapshot.strings[index] ?? "");
+    const nodes = [];
+    // Which document each iframe host node opens, so a child
+    // document can be attached to the node that owns it.
+    const hostOfDocument = new Map();
+    snapshot.documents.forEach((document, documentIndex) => {
+        const { nodes: raw, layout } = document;
+        const documentUrl = text(document.documentURL);
+        const id = (nodeIndex) => `${documentIndex}:${nodeIndex}`;
+        const shadowRoots = sparse(raw.shadowRootType);
+        const clickable = sparse(raw.isClickable);
+        const contentDocuments = sparse(raw.contentDocumentIndex);
+        // Layout is indexed by its own position, so the mapping from
+        // a node back to its layout entry has to be built once.
+        const layoutOf = new Map();
+        layout.nodeIndex.forEach((nodeIndex, at) => {
+            layoutOf.set(nodeIndex, at);
+        });
+        for (const [nodeIndex, nameIndex] of raw.nodeName.entries()) {
+            const at = layoutOf.get(nodeIndex);
+            const parentIndex = raw.parentIndex[nodeIndex] ?? -1;
+            const attributes = {};
+            const packed = raw.attributes[nodeIndex] ?? [];
+            for (let pair = 0; pair + 1 < packed.length; pair += 2) {
+                attributes[text(packed[pair])] = text(packed[pair + 1]);
+            }
+            const styles = {};
+            if (at !== undefined) {
+                const values = layout.styles[at] ?? [];
+                styleProperties.forEach((property, position) => {
+                    const value = text(values[position]);
+                    if (value !== "")
+                        styles[property] = value;
+                });
+            }
+            const box = at === undefined ? undefined : layout.bounds[at];
+            const own = text(layout.text?.[at ?? -1]);
+            nodes.push({
+                id: id(nodeIndex),
+                documentIndex,
+                documentUrl,
+                nodeName: text(nameIndex),
+                nodeType: raw.nodeType[nodeIndex] ?? 0,
+                backendNodeId: raw.backendNodeId[nodeIndex] ?? 0,
+                attributes,
+                ...(parentIndex >= 0 ? { parent: id(parentIndex) } : {}),
+                styles,
+                ...(box && box.length === 4
+                    ? {
+                        bounds: {
+                            x: box[0],
+                            y: box[1],
+                            width: box[2],
+                            height: box[3],
+                        },
+                    }
+                    : {}),
+                ...(own === "" ? {} : { text: own }),
+                clickable: clickable.has(nodeIndex),
+                inShadow: shadowRoots.has(nodeIndex),
+                rendered: at !== undefined,
+            });
+            const opens = contentDocuments.get(nodeIndex);
+            if (opens !== undefined)
+                hostOfDocument.set(opens, id(nodeIndex));
+        }
+    });
+    // Join the frames on: a frame's root has no parent of its own,
+    // so it takes the node that hosts it, and the page becomes one
+    // tree rather than several.
+    return nodes.map((node) => {
+        if (node.parent !== undefined)
+            return node;
+        const host = hostOfDocument.get(node.documentIndex);
+        return host === undefined ? node : { ...node, parent: host };
+    });
+}

package/dist/web/snapshot/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The page flattened into one addressable list, and the
+ * questions worth asking of it.
+ */
+export { DEEP_DOM, DEEP_UNREACHABLE } from "./deep.js";
+export { type Bounds, flattenSnapshot, type IndexedNode, isElement, isText, type RareValues, type RawDocument, type RawLayout, type RawNodes, type RawSnapshot, } from "./flatten.js";
+export { HIDDEN_BOX_PX, PRESENTED } from "./presented.js";
+export { describeNode, describeStyles, find, matches, type Query, type Tally, tally, } from "./query.js";

package/dist/web/snapshot/index.js

@@ -0,0 +1,10 @@
+/**
+ * The page flattened into one addressable list, and the
+ * questions worth asking of it.
+ */
+// The page-side traversal every capture shares, so a probe sees
+// the page the snapshot sees rather than only the top document.
+export { DEEP_DOM, DEEP_UNREACHABLE } from "./deep.js";
+export { flattenSnapshot, isElement, isText, } from "./flatten.js";
+export { HIDDEN_BOX_PX, PRESENTED } from "./presented.js";
+export { describeNode, describeStyles, find, matches, tally, } from "./query.js";

package/dist/web/snapshot/presented.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Page-side answers to "is this actually being offered to
+ * anybody", shared by every probe that has to decide.
+ *
+ * This ships as a source string, like the deep traversal it sits
+ * beside, because it declares helpers of its own and the bundler
+ * renames named inner bindings through a wrapper the page has
+ * never heard of.
+ *
+ * It exists because four probes asked this question three
+ * different ways. Two settled for a bare checkVisibility(), which
+ * answers about display and nothing else, and the disagreement
+ * showed up as false findings rather than as a disagreement: a
+ * real app's closed dialogs were reported as 48 critical
+ * accessibility failures and its screen-reader-only inputs as ten
+ * pointer targets one pixel across.
+ *
+ * The recognition of a visually-hidden idiom is presentational
+ * judgment rather than measurement, and is one of this library's
+ * declared exceptions to reporting only what the browser said.
+ * The browser has no notion of the idiom; without it, every
+ * correctly built skip link on every page is a finding.
+ */
+/** A box no larger than this is a hiding technique, not content. */
+export declare const HIDDEN_BOX_PX = 4;
+/**
+ * Declares `presented`, `visible`, `inertHere` and
+ * `visuallyHidden` for a page-side probe.
+ *
+ * Prepend it inside the probe's IIFE, as with DEEP_DOM.
+ */
+export declare const PRESENTED = "\n\t// The browser's own answer, but only when asked the whole\n\t// question. Bare checkVisibility() reports on display alone,\n\t// so it calls a visibility:hidden control visible, and real\n\t// apps hide closed menus and dialogs exactly that way.\n\t//\n\t// opacity is deliberately not asked about. An opacity:0\n\t// control is still in the focus order and still clickable, so\n\t// treating it as absent buries real defects rather than\n\t// avoiding false ones.\n\tconst visible = (el) =>\n\t\ttypeof el.checkVisibility === \"function\"\n\t\t\t? el.checkVisibility({\n\t\t\t\t\tvisibilityProperty: true,\n\t\t\t\t\tcontentVisibilityAuto: true,\n\t\t\t\t})\n\t\t\t: el.getClientRects().length > 0;\n\n\t// inert takes a subtree out of interaction without changing\n\t// anything about how it looks, so no style question finds it.\n\t// A closed dialog is the ordinary case.\n\tconst inertHere = (el) =>\n\t\ttypeof el.closest === \"function\" && el.closest(\"[inert]\") !== null;\n\n\t// The screen-reader-only family: clipped to nothing, or parked\n\t// off the left edge where no scrollable area is created. Such\n\t// an element is deliberately not shown to sighted users, so it\n\t// is not something they can look at or aim a pointer at.\n\tconst visuallyHidden = (el) => {\n\t\tconst rect = el.getBoundingClientRect();\n\t\tconst tiny =\n\t\t\trect.width <= 4 && rect.height <= 4;\n\t\tconst style = getComputedStyle(el);\n\t\tif (tiny && style.clipPath !== \"none\") return true;\n\t\tif (tiny && style.overflowX === \"hidden\") return true;\n\t\treturn rect.x + rect.width < 0;\n\t};\n\n\t// Offered to somebody: painted, not inert, and not hidden by\n\t// one of the idioms above.\n\tconst presented = (el) =>\n\t\tvisible(el) && !inertHere(el) && !visuallyHidden(el);\n";

package/dist/web/snapshot/presented.js

@@ -0,0 +1,74 @@
+/**
+ * Page-side answers to "is this actually being offered to
+ * anybody", shared by every probe that has to decide.
+ *
+ * This ships as a source string, like the deep traversal it sits
+ * beside, because it declares helpers of its own and the bundler
+ * renames named inner bindings through a wrapper the page has
+ * never heard of.
+ *
+ * It exists because four probes asked this question three
+ * different ways. Two settled for a bare checkVisibility(), which
+ * answers about display and nothing else, and the disagreement
+ * showed up as false findings rather than as a disagreement: a
+ * real app's closed dialogs were reported as 48 critical
+ * accessibility failures and its screen-reader-only inputs as ten
+ * pointer targets one pixel across.
+ *
+ * The recognition of a visually-hidden idiom is presentational
+ * judgment rather than measurement, and is one of this library's
+ * declared exceptions to reporting only what the browser said.
+ * The browser has no notion of the idiom; without it, every
+ * correctly built skip link on every page is a finding.
+ */
+/** A box no larger than this is a hiding technique, not content. */
+export const HIDDEN_BOX_PX = 4;
+/**
+ * Declares `presented`, `visible`, `inertHere` and
+ * `visuallyHidden` for a page-side probe.
+ *
+ * Prepend it inside the probe's IIFE, as with DEEP_DOM.
+ */
+export const PRESENTED = `
+	// The browser's own answer, but only when asked the whole
+	// question. Bare checkVisibility() reports on display alone,
+	// so it calls a visibility:hidden control visible, and real
+	// apps hide closed menus and dialogs exactly that way.
+	//
+	// opacity is deliberately not asked about. An opacity:0
+	// control is still in the focus order and still clickable, so
+	// treating it as absent buries real defects rather than
+	// avoiding false ones.
+	const visible = (el) =>
+		typeof el.checkVisibility === "function"
+			? el.checkVisibility({
+					visibilityProperty: true,
+					contentVisibilityAuto: true,
+				})
+			: el.getClientRects().length > 0;
+
+	// inert takes a subtree out of interaction without changing
+	// anything about how it looks, so no style question finds it.
+	// A closed dialog is the ordinary case.
+	const inertHere = (el) =>
+		typeof el.closest === "function" && el.closest("[inert]") !== null;
+
+	// The screen-reader-only family: clipped to nothing, or parked
+	// off the left edge where no scrollable area is created. Such
+	// an element is deliberately not shown to sighted users, so it
+	// is not something they can look at or aim a pointer at.
+	const visuallyHidden = (el) => {
+		const rect = el.getBoundingClientRect();
+		const tiny =
+			rect.width <= ${HIDDEN_BOX_PX} && rect.height <= ${HIDDEN_BOX_PX};
+		const style = getComputedStyle(el);
+		if (tiny && style.clipPath !== "none") return true;
+		if (tiny && style.overflowX === "hidden") return true;
+		return rect.x + rect.width < 0;
+	};
+
+	// Offered to somebody: painted, not inert, and not hidden by
+	// one of the idioms above.
+	const presented = (el) =>
+		visible(el) && !inertHere(el) && !visuallyHidden(el);
+`;

package/dist/web/snapshot/query.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Asking the flattened page questions.
+ *
+ * The queries here are the ones that cannot be asked any other
+ * way: how many of these are there, where are they, which ones
+ * are not rendered, what is inside that frame. A CSS selector
+ * run in the page answers some of this, but it answers it inside
+ * one document and it cannot see into a closed shadow root or
+ * across a frame boundary. The index can, because the browser
+ * already flattened all of it.
+ */
+import type { IndexedNode } from "./flatten.js";
+/** What to look for. */
+export interface Query {
+    /** Tag name, matched case-insensitively. */
+    readonly tag?: string;
+    /** An attribute that must be present, and optionally its value. */
+    readonly attribute?: string;
+    readonly value?: string;
+    /** Text the node must contain, matched case-insensitively. */
+    readonly text?: string;
+    /** Restrict to a class. */
+    readonly className?: string;
+    /** Only what the browser rendered, or only what it did not. */
+    readonly rendered?: boolean;
+    /** Only nodes inside a shadow root. */
+    readonly inShadow?: boolean;
+    /** Only nodes belonging to this document url. */
+    readonly documentUrl?: string;
+    /** Only nodes the browser considers clickable. */
+    readonly clickable?: boolean;
+}
+/** Whether one node answers the query. */
+export declare function matches(node: IndexedNode, query: Query): boolean;
+/** Everything that answers the query, in document order. */
+export declare function find(nodes: readonly IndexedNode[], query: Query): readonly IndexedNode[];
+/** A tally of something, largest first. */
+export interface Tally {
+    readonly key: string;
+    readonly count: number;
+}
+/**
+ * Count nodes by some property of them.
+ *
+ * A page with four hundred divs is not usefully listed, but it
+ * is usefully counted, and the counting is what tells you the
+ * listing would be a waste.
+ */
+export declare function tally(nodes: readonly IndexedNode[], by: (node: IndexedNode) => string | undefined): readonly Tally[];
+/**
+ * How a node reads in a listing.
+ *
+ * The position says which space it is measured in. A snapshot
+ * measures down the document, while an element inspection reports
+ * the box model, which measures from the viewport. The same element
+ * on a scrolled page reads differently in each, and saying so is
+ * what stops the two being compared as though they agreed.
+ */
+export declare function describeNode(node: IndexedNode): string;
+/**
+ * Say what a node's named properties compute to.
+ *
+ * A property the snapshot carries no value for is named rather than
+ * dropped. Leaving it out would read exactly like a property nobody
+ * asked about, and a caller would take the silence for a value.
+ */
+export declare function describeStyles(node: IndexedNode, wanted: readonly string[]): string;