Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(browser): share DOM snapshot admission

morluto70de702109fd
diff --git a/docs/electron-observation.md b/docs/electron-observation.md
index b869e4b76..353af9787 100644
--- a/docs/electron-observation.md
+++ b/docs/electron-observation.md
@@ -58,8 +58,13 @@ The normalized result contains canonical local paths, frame and DOM
structure, resource metadata, stable script/resource identities, explicit
completeness, and content-addressed script artifacts. Resource sizes are unknown
when omitted or invalid; supplied invalid sizes also produce an explicit
-completeness diagnostic. Script metadata
-retains its execution-context frame ID when CDP supplies one. The capture also
+completeness diagnostic.
+
+DOM node indices retain their snapshot positions. Invalid rows are omitted with
+completeness diagnostics, so `total_nodes` can exceed the retained node count
+and a parent index can refer to an omitted source node.
+
+Script metadata retains its execution-context frame ID when CDP supplies one. The capture also
inventories worker, service-worker, and shared-worker targets with
validated opener-target and parent-frame IDs. Worker discovery uses passive
target metadata; REA does not attach to or execute code in those targets.
diff --git a/src/browser/CdpCaptureDocuments.ts b/src/browser/CdpCaptureDocuments.ts
index bff87bb79..40fbb3227 100644
--- a/src/browser/CdpCaptureDocuments.ts
+++ b/src/browser/CdpCaptureDocuments.ts
@@ -12,10 +12,14 @@ import {
type UnknownRecord,
} from "./CdpCaptureValues.js";
import {
- cdpSnapshotAttributesResolve,
cdpSnapshotString,
cdpSnapshotValueString,
} from "./CdpSnapshotStrings.js";
+import {
+ snapshotDocumentNodes,
+ snapshotNodeAt,
+ type SnapshotAttributes,
+} from "./CdpSnapshotNodes.js";
import type { BrowserExclusionReason } from "../domain/browserCompleteness.js";
import { exclusionReasonForUrl } from "./CdpCaptureEventHelpers.js";
import type { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
@@ -247,19 +251,12 @@ export function* captureDom(
continue;
}
const baseUrl = baseUrlValue || documentUrl;
- const documentNodes = snapshotDocumentNodes(document.nodes);
+ const documentNodes = snapshotDocumentNodes(document.nodes, strings);
if (documentNodes === undefined) {
excludeDocumentEvidence(completeness, "invalid_protocol_value");
continue;
}
- const {
- nodeTypes: rawNodeTypes,
- nodeNames: rawNodeNames,
- nodeValues: rawNodeValues,
- parents: rawParents,
- attributes: rawAttributes,
- backendNodeIds,
- } = documentNodes;
+ const { nodeTypes, backendNodeIds } = documentNodes;
if (documentNodes.excessAttributes > 0)
excludeDocumentEvidence(
completeness,
@@ -267,40 +264,19 @@ export function* captureDom(
documentNodes.excessAttributes,
);
const baseIndex = total;
- total += rawNodeTypes.length;
- const ancestry = createDocumentSvgAncestry({
- nodeTypes: rawNodeTypes,
- nodeNames: rawNodeNames,
- parents: rawParents,
- strings,
- attributes: rawAttributes,
- });
+ total += nodeTypes.length;
+ const ancestry = createDocumentSvgAncestry(documentNodes);
const pendingMetadata: PendingDomMetadata[] = [];
- for (let index = 0; index < rawNodeTypes.length; index += 1) {
- const nodeType = rawNodeTypes[index];
- const nodeNameIndex = rawNodeNames[index];
- const nodeValueIndex = rawNodeValues[index];
- const parent = rawParents[index];
- const attributeIndexes = numberArray(rawAttributes[index]);
- const nodeName = cdpSnapshotString(strings, nodeNameIndex);
- const nodeValue = cdpSnapshotValueString(strings, nodeValueIndex);
- if (
- nodeType === undefined ||
- nodeName === undefined ||
- nodeValue === undefined ||
- parent === undefined ||
- parent < -1 ||
- parent === index ||
- parent >= rawNodeTypes.length ||
- attributeIndexes === undefined ||
- !cdpSnapshotAttributesResolve(strings, attributeIndexes)
- ) {
+ for (let index = 0; index < nodeTypes.length; index += 1) {
+ const admitted = snapshotNodeAt(documentNodes, index);
+ if (!admitted.ok) {
excludeDocumentEvidence(completeness, "invalid_protocol_value");
continue;
}
- const attributes = attributeIndexes as readonly number[];
+ const { nodeType, nodeName, nodeValue, parent, attributes } =
+ admitted.value;
const nodeIndex = baseIndex + index;
- const attributeNames = uniqueAttributeNames(attributes, strings);
+ const attributeNames = [...new Set(attributes.map(([name]) => name))];
const svgLink = domSvgLink(ancestry, index);
if (svgLink.xmlDocument === undefined)
completeness?.exclude("metadata", "invalid_protocol_value");
@@ -311,13 +287,9 @@ export function* captureDom(
attributeNames.includes("xlink:href") &&
!attributeNames.includes("href")
) {
- const backendNodeId = numberValue(backendNodeIds[index]);
+ const backendNodeId = backendNodeIds[index];
svgQuery =
- backendNodeId !== undefined &&
- Number.isSafeInteger(backendNodeId) &&
- backendNodeId > 0
- ? { backendNodeId, nodeName }
- : null;
+ backendNodeId !== undefined ? { backendNodeId, nodeName } : null;
}
nodes.push({
index: nodeIndex,
@@ -330,7 +302,6 @@ export function* captureDom(
pendingMetadata.push({
svgQuery,
options: {
- strings,
attributes,
// The BASE element itself resolves against the document fallback URL.
baseUrl: nodeName.toLowerCase() === "base" ? documentUrl : baseUrl,
@@ -343,7 +314,7 @@ export function* captureDom(
});
if (
pendingMetadata.length === DOM_METADATA_BATCH_SIZE ||
- index === rawNodeTypes.length - 1
+ index === nodeTypes.length - 1
) {
const metadata = yield* captureDomMetadata(
pendingMetadata,
@@ -404,55 +375,6 @@ export const snapshotDocuments = (
});
};
-/** One snapshot document's parallel node arrays, validated for every consumer. */
-export interface SnapshotDocumentNodes {
- readonly nodeTypes: readonly (number | undefined)[];
- readonly nodeNames: readonly (number | undefined)[];
- readonly nodeValues: readonly (number | undefined)[];
- readonly parents: readonly (number | undefined)[];
- readonly attributes: readonly unknown[];
- readonly backendNodeIds: readonly unknown[];
- /** Attribute rows beyond the node count describe no node. */
- readonly excessAttributes: number;
-}
-
-/** Missing or misaligned node arrays make the document's nodes unknown. */
-export const snapshotDocumentNodes = (
- value: unknown,
-): SnapshotDocumentNodes | undefined => {
- const nodes = recordValue(value);
- if (nodes === undefined) return undefined;
- const nodeTypes = numberArray(nodes.nodeType);
- const nodeNames = numberArray(nodes.nodeName);
- const nodeValues = numberArray(nodes.nodeValue);
- const parents = numberArray(nodes.parentIndex);
- const attributes = Array.isArray(nodes.attributes)
- ? nodes.attributes
- : undefined;
- if (
- nodeTypes === undefined ||
- nodeNames === undefined ||
- nodeValues === undefined ||
- parents === undefined ||
- attributes === undefined ||
- nodeNames.length !== nodeTypes.length ||
- nodeValues.length !== nodeTypes.length ||
- parents.length !== nodeTypes.length
- )
- return undefined;
- return {
- nodeTypes,
- nodeNames,
- nodeValues,
- parents,
- attributes,
- backendNodeIds: Array.isArray(nodes.backendNodeId)
- ? nodes.backendNodeId
- : [],
- excessAttributes: Math.max(0, attributes.length - nodeTypes.length),
- };
-};
-
function* captureDomMetadata(
pending: readonly PendingDomMetadata[],
completeness: CdpCaptureCompleteness | undefined,
@@ -669,37 +591,8 @@ const accessibilityStates = (
const axText = (value: unknown): string | null =>
cdpStringValue(recordValue(value)?.value) ?? null;
-const uniqueAttributeNames = (
- attributeIndexes: readonly number[],
- strings: readonly (string | undefined)[],
-): string[] => {
- const names: string[] = [];
- const seen = new Set<string>();
- for (let index = 0; index < attributeIndexes.length; index += 2) {
- const name = cdpSnapshotString(strings, attributeIndexes[index]);
- if (name === undefined) continue;
- if (seen.has(name)) continue;
- seen.add(name);
- names.push(name);
- }
- return names;
-};
-
-const numberArray = (
- value: unknown,
-): readonly (number | undefined)[] | undefined => {
- if (!Array.isArray(value)) return undefined;
- return value.map((item) => {
- const number = numberValue(item);
- return number !== undefined && Number.isSafeInteger(number)
- ? number
- : undefined;
- });
-};
-
interface DomMetadataOptions {
- readonly strings: readonly (string | undefined)[];
- readonly attributes: readonly number[];
+ readonly attributes: SnapshotAttributes;
readonly baseUrl: string;
readonly documentUrl: string;
readonly nodeIndex: number;
@@ -731,7 +624,6 @@ const domMetadata = (
readonly agentHints: WebPageInspection["metadata"]["agent_hints"];
} => {
const {
- strings,
attributes,
baseUrl,
documentUrl,
@@ -740,12 +632,8 @@ const domMetadata = (
allowedOrigins,
} = options;
const pairs = new Map<string, string>();
- for (let index = 0; index + 1 < attributes.length; index += 2) {
- // Chrome already folds HTML names; SVG/XML names remain case-sensitive.
- const name = cdpSnapshotString(strings, attributes[index]);
- const value = cdpSnapshotValueString(strings, attributes[index + 1]);
- if (name === undefined || value === undefined) continue;
- // HTML keeps the first declaration. A later repeat must not move dom_urls.
+ for (const [name, value] of attributes) {
+ // HTML keeps the first declaration; SVG/XML spelling stays case-sensitive.
if (!pairs.has(name)) pairs.set(name, value);
}
const urls: WebPageInspection["metadata"]["dom_urls"] = [];
diff --git a/src/browser/CdpCaptureDomSvg.ts b/src/browser/CdpCaptureDomSvg.ts
index 877bab06d..f196a36eb 100644
--- a/src/browser/CdpCaptureDomSvg.ts
+++ b/src/browser/CdpCaptureDomSvg.ts
@@ -1,20 +1,16 @@
-import { numberValue, recordValue } from "./CdpCaptureValues.js";
-import {
- cdpSnapshotAttributesResolve,
- cdpSnapshotString,
- cdpSnapshotValueString,
-} from "./CdpSnapshotStrings.js";
+import { recordValue } from "./CdpCaptureValues.js";
+import type {
+ SnapshotDocumentNodes,
+ SnapshotAttributes,
+} from "./CdpSnapshotNodes.js";
const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
const XLINK_NAMESPACE = "http://www.w3.org/1999/xlink";
-interface DomSnapshotNodes {
- readonly nodeTypes: readonly (number | undefined)[];
- readonly nodeNames: readonly (number | undefined)[];
- readonly parents: readonly (number | undefined)[];
- readonly strings: readonly (string | undefined)[];
- readonly attributes: readonly unknown[];
-}
+type DomSnapshotNodes = Pick<
+ SnapshotDocumentNodes,
+ "nodeTypes" | "nodeNames" | "parents" | "attributes"
+>;
interface XmlSvgLink {
readonly svgElement: boolean;
@@ -57,16 +53,6 @@ interface DomSvgLink {
readonly xlinkHref: string | undefined;
}
-const numberArray = (value: unknown): readonly (number | undefined)[] =>
- Array.isArray(value)
- ? value.map((item) => {
- const number = numberValue(item);
- return number !== undefined && Number.isSafeInteger(number)
- ? number
- : undefined;
- })
- : [];
-
// DOMSnapshot has no namespace URI. HTML documents use uppercase `HTML` and
// the parser's local names. XML documents preserve prefixed names and xmlns
// declarations, including those on standalone SVG roots.
@@ -74,27 +60,23 @@ const xmlDocument = (nodes: DomSnapshotNodes): boolean | undefined => {
const documentIndex = nodes.nodeTypes.findIndex((nodeType) => nodeType === 9);
if (documentIndex < 0) return false;
if (
- !validSvgSourceNode(nodes, documentIndex) ||
+ svgSourceNode(nodes, documentIndex) === undefined ||
nodes.parents[documentIndex] !== -1
)
return undefined;
for (let index = 0; index < nodes.nodeTypes.length; index += 1) {
if (nodes.nodeTypes[index] !== 1) continue;
if (nodes.parents[index] !== documentIndex) continue;
- const name = cdpSnapshotString(nodes.strings, nodes.nodeNames[index]);
- if (name === undefined || !validSvgSourceNode(nodes, index))
- return undefined;
+ const source = svgSourceNode(nodes, index);
+ if (source === undefined) return undefined;
+ const name = source.nodeName;
if (name === "HTML") return false;
if (name === "html" || name.includes(":")) return true;
// Explicit namespaces also identify standalone SVG and other XML roots.
// Namespace-free synthetic snapshots retain the legacy HTML behavior.
- const attributes = numberArray(nodes.attributes[index]);
- for (let offset = 0; offset + 1 < attributes.length; offset += 2) {
- const value = attributes[offset];
- const attributeName = cdpSnapshotString(nodes.strings, value);
- if (attributeName === undefined) return undefined;
+ const attributes = source.attributes;
+ for (const [attributeName] of attributes)
if (xmlnsPrefix(attributeName) !== undefined) return true;
- }
return false;
}
return false;
@@ -162,10 +144,9 @@ const resolveXmlElements = (
const pending: XmlWalkStep[] = [];
for (let node = 0; node < nodes.nodeNames.length; node += 1) {
const parent = nodes.parents[node];
- if (parent === undefined || parent < -1 || parent >= nodes.nodeNames.length)
- continue;
+ if (parent === undefined) continue;
if (parent < 0) pending.push({ node });
- else if (parent < nodes.nodeNames.length && parent !== node) {
+ else {
const siblings = children.get(parent);
if (siblings === undefined) children.set(parent, [node]);
else siblings.push(node);
@@ -184,20 +165,16 @@ const resolveXmlElements = (
continue;
}
const { node } = step;
- if (!validSvgSourceNode(nodes, node)) continue;
- const attributes = numberArray(nodes.attributes[node]);
- const restore = applyDeclarations(bindings, attributes, nodes.strings);
+ const source = svgSourceNode(nodes, node);
+ if (source === undefined) continue;
+ const attributes = source.attributes;
+ const restore = applyDeclarations(bindings, attributes);
const svgElement =
- nodes.nodeTypes[node] === 1 &&
- elementNamespace(
- cdpSnapshotString(nodes.strings, nodes.nodeNames[node]),
- bindings,
- ) === SVG_NAMESPACE;
+ source.nodeType === 1 &&
+ elementNamespace(source.nodeName, bindings) === SVG_NAMESPACE;
resolved.set(node, {
svgElement,
- xlinkHref: svgElement
- ? xlinkHrefValue(attributes, nodes.strings, bindings)
- : undefined,
+ xlinkHref: svgElement ? xlinkHrefValue(attributes, bindings) : undefined,
});
pending.push({ restore });
for (const child of children.get(node) ?? []) pending.push({ node: child });
@@ -209,18 +186,11 @@ const resolveXmlElements = (
const applyDeclarations = (
bindings: Map<string, string>,
- attributes: readonly (number | undefined)[],
- strings: readonly (string | undefined)[],
+ attributes: SnapshotAttributes,
): readonly NamespaceRestore[] => {
const restore: NamespaceRestore[] = [];
const seen = new Set<string>();
- for (let index = 0; index + 1 < attributes.length; index += 2) {
- const nameIndex = attributes[index];
- const valueIndex = attributes[index + 1];
- if (nameIndex === undefined || valueIndex === undefined) continue;
- const name = cdpSnapshotString(strings, nameIndex);
- const value = cdpSnapshotValueString(strings, valueIndex);
- if (name === undefined || value === undefined) continue;
+ for (const [name, value] of attributes) {
const prefix = xmlnsPrefix(name);
if (prefix === undefined || seen.has(prefix)) continue;
seen.add(prefix);
@@ -263,17 +233,11 @@ const elementNamespace = (
// First prefixed href bound to the XLink namespace. Duplicate names keep the
// earlier value. Plain href is applied by the caller and wins even when empty.
const xlinkHrefValue = (
- attributes: readonly (number | undefined)[],
- strings: readonly (string | undefined)[],
+ attributes: SnapshotAttributes,
bindings: ReadonlyMap<string, string>,
): string | undefined => {
const seen = new Set<string>();
- for (let index = 0; index + 1 < attributes.length; index += 2) {
- const nameIndex = attributes[index];
- const valueIndex = attributes[index + 1];
- if (nameIndex === undefined || valueIndex === undefined) continue;
- const name = cdpSnapshotString(strings, nameIndex);
- if (name === undefined) continue;
+ for (const [name, value] of attributes) {
if (seen.has(name)) continue;
seen.add(name);
const colon = name.indexOf(":");
@@ -281,25 +245,19 @@ const xlinkHrefValue = (
const prefix = name.slice(0, colon);
const local = name.slice(colon + 1);
if (local !== "href" || bindings.get(prefix) !== XLINK_NAMESPACE) continue;
- return cdpSnapshotValueString(strings, valueIndex);
+ return value;
}
return undefined;
};
-const validSvgSourceNode = (
- nodes: DomSnapshotNodes,
- index: number,
-): boolean => {
- if (
- nodes.nodeTypes[index] === undefined ||
- cdpSnapshotString(nodes.strings, nodes.nodeNames[index]) === undefined
- )
- return false;
- const rawAttributes = nodes.attributes[index];
- if (!Array.isArray(rawAttributes)) return false;
- const attributes = numberArray(rawAttributes);
- return (
- attributes.length === rawAttributes.length &&
- cdpSnapshotAttributesResolve(nodes.strings, attributes)
- );
+// Namespace interpretation needs these parsed facts even when a node value is unknown.
+const svgSourceNode = (nodes: DomSnapshotNodes, index: number) => {
+ const nodeType = nodes.nodeTypes[index];
+ const nodeName = nodes.nodeNames[index];
+ const attributes = nodes.attributes[index];
+ return nodeType === undefined ||
+ nodeName === undefined ||
+ attributes === undefined
+ ? undefined
+ : { nodeType, nodeName, attributes };
};
diff --git a/src/browser/CdpElectronInspection.ts b/src/browser/CdpElectronInspection.ts
index 54d5106fd..bb8c2d1f8 100644
--- a/src/browser/CdpElectronInspection.ts
+++ b/src/browser/CdpElectronInspection.ts
@@ -10,7 +10,6 @@ import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js";
import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
import {
delayWithCancellation,
- numberValue,
resourceContentSize,
recordValue,
requiredRecord,
@@ -18,10 +17,11 @@ import {
} from "./CdpCaptureValues.js";
import {
frameTreeResources,
- snapshotDocumentNodes,
snapshotDocuments,
walkFrameTrees,
} from "./CdpCaptureDocuments.js";
+import { snapshotDocumentNodes, snapshotNodeAt } from "./CdpSnapshotNodes.js";
+import { cdpSnapshotString } from "./CdpSnapshotStrings.js";
import {
ingestElectronScriptEvent,
type ElectronScriptDraft,
@@ -332,43 +332,44 @@ const captureDom = async (
invalid(null);
return { total_nodes: 0, nodes: [] };
}
- const strings = result.strings.map((value) =>
- typeof value === "string" ? value : "",
- );
+ const strings = result.strings.map(cdpStringValue);
const nodes: ElectronPageInspection["dom"]["nodes"] = [];
let total = 0;
for (const document of snapshotDocuments(result.documents, invalid)) {
- const documentUrl = stringAt(strings, document.documentURL);
+ const documentUrl = cdpSnapshotString(strings, document.documentURL);
+ if (documentUrl === undefined) {
+ invalid(1);
+ continue;
+ }
if ((await authorizedElectronFile(documentUrl)) === undefined) {
completeness.exclude("dom", "out_of_target_scope");
continue;
}
// The shared snapshot owner validates the parallel node arrays.
- const documentNodes = snapshotDocumentNodes(document.nodes);
+ const documentNodes = snapshotDocumentNodes(document.nodes, strings);
if (documentNodes === undefined) {
invalid(1);
continue;
}
if (documentNodes.excessAttributes > 0)
invalid(documentNodes.excessAttributes);
- const { nodeTypes, nodeNames, nodeValues, parents, attributes } =
- documentNodes;
- const baseIndex = nodes.length;
- total += nodeTypes.length;
- for (let index = 0; index < nodeTypes.length; index += 1) {
- const attributeIndexes = arrayValue(attributes[index]);
- const parent = integer(parents[index], -1);
+ const baseIndex = total;
+ total += documentNodes.nodeTypes.length;
+ for (let index = 0; index < documentNodes.nodeTypes.length; index += 1) {
+ const admitted = snapshotNodeAt(documentNodes, index);
+ if (!admitted.ok) {
+ invalid(1);
+ continue;
+ }
+ const { nodeType, nodeName, nodeValue, parent, attributes } =
+ admitted.value;
nodes.push({
- index: nodes.length,
+ index: baseIndex + index,
parent_index: parent < 0 ? -1 : baseIndex + parent,
- node_type: integer(nodeTypes[index], 0),
- node_name: stringAt(strings, nodeNames[index]),
- node_value_length: Buffer.byteLength(
- stringAt(strings, nodeValues[index]),
- ),
- attribute_names: attributeIndexes
- .filter((_value, attributeIndex) => attributeIndex % 2 === 0)
- .map((value) => stringAt(strings, value)),
+ node_type: nodeType,
+ node_name: nodeName,
+ node_value_length: Buffer.byteLength(nodeValue),
+ attribute_names: attributes.map(([name]) => name),
});
}
}
@@ -381,17 +382,6 @@ const mainFilePath = async (result: unknown): Promise<string | undefined> => {
return await authorizedElectronFile(cdpStringValue(frame?.url) ?? "");
};
-const arrayValue = (value: unknown): readonly unknown[] =>
- Array.isArray(value) ? value : [];
-
-const stringAt = (strings: readonly string[], value: unknown): string =>
- strings[integer(value, -1)] ?? "";
-
-const integer = (value: unknown, fallback: number): number => {
- const number = numberValue(value);
- return number === undefined ? fallback : Math.trunc(number);
-};
-
const report = async (
progress: ProgressReporter | undefined,
completed: number,
diff --git a/src/browser/CdpSnapshotNodes.test.ts b/src/browser/CdpSnapshotNodes.test.ts
new file mode 100644
index 000000000..4131a80c8
--- /dev/null
+++ b/src/browser/CdpSnapshotNodes.test.ts
@@ -0,0 +1,81 @@
+import { expect, it } from "vitest";
+import { snapshotDocumentNodes, snapshotNodeAt } from "./CdpSnapshotNodes.js";
+
+const strings = [
+ "#document",
+ "svg",
+ "xmlns",
+ "http://www.w3.org/2000/svg",
+ "πŸ˜€",
+];
+const raw = () => ({
+ nodeType: [9, 1, 1],
+ nodeName: [0, 1, 1],
+ nodeValue: [-1, -1, 4],
+ parentIndex: [-1, 0, 1],
+ attributes: [[], [2, 3], []],
+});
+
+it("decodes references once while retaining independently unknown facts", () => {
+ const source = raw();
+ source.nodeValue[1] = 999;
+ const nodes = snapshotDocumentNodes(source, strings);
+ if (nodes === undefined) throw new Error("Expected aligned columns");
+ expect(nodes.nodeNames[1]).toBe("svg");
+ expect(nodes.attributes[1]).toEqual([
+ ["xmlns", "http://www.w3.org/2000/svg"],
+ ]);
+ expect(nodes.parents[1]).toBe(0);
+ expect(nodes.nodeValues[1]).toBeUndefined();
+ expect(snapshotNodeAt(nodes, 1)).toEqual({
+ ok: false,
+ error: { _tag: "InvalidCdpSnapshotNode", index: 1 },
+ });
+ expect(snapshotNodeAt(nodes, 2)).toMatchObject({
+ ok: true,
+ value: { nodeValue: "πŸ˜€", parent: 1 },
+ });
+});
+
+it("invalidates only cycle facts without inventing a root for descendants", () => {
+ const source = raw();
+ source.parentIndex = [1, 0, 1];
+ const nodes = snapshotDocumentNodes(source, strings);
+ expect(nodes?.parents).toEqual([undefined, undefined, 1]);
+});
+
+it.each([
+ { parents: [-1, -1, 0] },
+ { parents: [2, 0, -1] },
+ { parents: [-1, 0, 1] },
+])("preserves acyclic root and forward relationships %j", ({ parents }) => {
+ expect(
+ snapshotDocumentNodes({ ...raw(), parentIndex: parents }, strings)?.parents,
+ ).toEqual(parents);
+});
+
+it.each([1.5, -2, 3, NaN, null, "0"])(
+ "keeps malformed parent %s unknown at its original position",
+ (parent) => {
+ const nodes = snapshotDocumentNodes(
+ { ...raw(), parentIndex: [-1, parent, 1] },
+ strings,
+ );
+ expect(nodes?.parents).toEqual([-1, undefined, 1]);
+ },
+);
+
+it.each([
+ { attributes: [2] },
+ { attributes: [999, 3] },
+ { attributes: [2, 999] },
+ { attributes: "invalid" },
+])("refuses malformed attribute references %j", ({ attributes }) => {
+ const nodes = snapshotDocumentNodes(
+ { ...raw(), attributes: [[], attributes, []] },
+ strings,
+ );
+ if (nodes === undefined) throw new Error("Expected aligned columns");
+ expect(snapshotNodeAt(nodes, 1).ok).toBe(false);
+ expect(snapshotNodeAt(nodes, 2).ok).toBe(true);
+});
diff --git a/src/browser/CdpSnapshotNodes.ts b/src/browser/CdpSnapshotNodes.ts
new file mode 100644
index 000000000..0d96ac18b
--- /dev/null
+++ b/src/browser/CdpSnapshotNodes.ts
@@ -0,0 +1,144 @@
+import { err, ok, type Result } from "../domain/result.js";
+import { numberValue, recordValue } from "./CdpCaptureValues.js";
+import {
+ cdpSnapshotString,
+ cdpSnapshotValueString,
+} from "./CdpSnapshotStrings.js";
+
+export type SnapshotAttributes = readonly (readonly [string, string])[];
+
+/** Decoded columns retain source positions and independently unknown facts. */
+export interface SnapshotDocumentNodes {
+ readonly nodeTypes: readonly (number | undefined)[];
+ readonly nodeNames: readonly (string | undefined)[];
+ readonly nodeValues: readonly (string | undefined)[];
+ readonly parents: readonly (number | undefined)[];
+ readonly attributes: readonly (SnapshotAttributes | undefined)[];
+ readonly backendNodeIds: readonly (number | undefined)[];
+ readonly excessAttributes: number;
+}
+
+const integer = (value: unknown): number | undefined => {
+ const parsed = numberValue(value);
+ return parsed !== undefined && Number.isSafeInteger(parsed)
+ ? parsed
+ : undefined;
+};
+
+const attributes = (
+ value: unknown,
+ strings: readonly (string | undefined)[],
+): SnapshotAttributes | undefined => {
+ if (!Array.isArray(value) || value.length % 2 !== 0) return undefined;
+ const pairs: Array<readonly [string, string]> = [];
+ for (let offset = 0; offset < value.length; offset += 2) {
+ const name = cdpSnapshotString(strings, value[offset]);
+ const text = cdpSnapshotValueString(strings, value[offset + 1]);
+ if (name === undefined || text === undefined) return undefined;
+ pairs.push([name, text]);
+ }
+ return pairs;
+};
+
+/** Remove only cyclic parent facts; descendants keep their directly observed links. */
+const invalidateParentCycles = (parents: Array<number | undefined>): void => {
+ const state = new Uint8Array(parents.length);
+ const path: number[] = [];
+ for (let start = 0; start < parents.length; start += 1) {
+ if (state[start] !== 0) continue;
+ path.length = 0;
+ let cursor = start;
+ while (cursor >= 0 && state[cursor] === 0) {
+ state[cursor] = 1;
+ path.push(cursor);
+ // Unknown ancestry ends this walk without inventing a root fact.
+ cursor = parents[cursor] ?? -1;
+ }
+ if (cursor >= 0 && state[cursor] === 1)
+ for (let index = path.indexOf(cursor); index < path.length; index += 1)
+ parents[path[index]!] = undefined;
+ for (const index of path) state[index] = 2;
+ }
+};
+
+/** One boundary owns aligned arrays, string references and parent validity. */
+export const snapshotDocumentNodes = (
+ value: unknown,
+ strings: readonly (string | undefined)[],
+): SnapshotDocumentNodes | undefined => {
+ const raw = recordValue(value);
+ if (
+ raw === undefined ||
+ !Array.isArray(raw.nodeType) ||
+ !Array.isArray(raw.nodeName) ||
+ !Array.isArray(raw.nodeValue) ||
+ !Array.isArray(raw.parentIndex) ||
+ !Array.isArray(raw.attributes)
+ )
+ return undefined;
+ const count = raw.nodeType.length;
+ if (
+ raw.nodeName.length !== count ||
+ raw.nodeValue.length !== count ||
+ raw.parentIndex.length !== count
+ )
+ return undefined;
+ const parents = raw.parentIndex.map((value, index) => {
+ const parent = integer(value);
+ return parent !== undefined &&
+ parent >= -1 &&
+ parent < count &&
+ parent !== index
+ ? parent
+ : undefined;
+ });
+ invalidateParentCycles(parents);
+ const backend = Array.isArray(raw.backendNodeId) ? raw.backendNodeId : [];
+ return {
+ nodeTypes: raw.nodeType.map((value) => {
+ const type = integer(value);
+ return type !== undefined && type >= 0 ? type : undefined;
+ }),
+ nodeNames: raw.nodeName.map((value) => cdpSnapshotString(strings, value)),
+ nodeValues: raw.nodeValue.map((value) =>
+ cdpSnapshotValueString(strings, value),
+ ),
+ parents,
+ attributes: raw.attributes
+ .slice(0, count)
+ .map((value) => attributes(value, strings)),
+ backendNodeIds: backend.slice(0, count).map((value) => {
+ const id = integer(value);
+ return id !== undefined && id > 0 ? id : undefined;
+ }),
+ excessAttributes: Math.max(0, raw.attributes.length - count),
+ };
+};
+
+/** Admit a DOM row from parsed facts without changing its source identity. */
+export const snapshotNodeAt = (
+ nodes: SnapshotDocumentNodes,
+ index: number,
+): Result<
+ {
+ readonly nodeType: number;
+ readonly nodeName: string;
+ readonly nodeValue: string;
+ readonly parent: number;
+ readonly attributes: SnapshotAttributes;
+ },
+ { readonly _tag: "InvalidCdpSnapshotNode"; readonly index: number }
+> => {
+ const nodeType = nodes.nodeTypes[index];
+ const nodeName = nodes.nodeNames[index];
+ const nodeValue = nodes.nodeValues[index];
+ const parent = nodes.parents[index];
+ const attributes = nodes.attributes[index];
+ return nodeType === undefined ||
+ nodeName === undefined ||
+ nodeValue === undefined ||
+ parent === undefined ||
+ attributes === undefined
+ ? err({ _tag: "InvalidCdpSnapshotNode", index })
+ : ok({ nodeType, nodeName, nodeValue, parent, attributes });
+};
diff --git a/src/browser/CdpSnapshotStrings.ts b/src/browser/CdpSnapshotStrings.ts
index 6e8314727..f64149a42 100644
--- a/src/browser/CdpSnapshotStrings.ts
+++ b/src/browser/CdpSnapshotStrings.ts
@@ -23,17 +23,3 @@ export const cdpSnapshotValueString = (
numberValue(index) === CDP_EMPTY_STRING_INDEX
? ""
: cdpSnapshotString(strings, index);
-
-/** Whether flattened name/value attribute indexes all resolve. */
-export const cdpSnapshotAttributesResolve = (
- strings: readonly (string | undefined)[],
- attributes: readonly (number | undefined)[],
-): boolean =>
- attributes.length % 2 === 0 &&
- attributes.every(
- (attribute, offset) =>
- attribute !== undefined &&
- (offset % 2 === 0
- ? cdpSnapshotString(strings, attribute)
- : cdpSnapshotValueString(strings, attribute)) !== undefined,
- );
diff --git a/tests/boundary/cli/electronDomAdmissionCli.test.ts b/tests/boundary/cli/electronDomAdmissionCli.test.ts
new file mode 100644
index 000000000..76d99bc60
--- /dev/null
+++ b/tests/boundary/cli/electronDomAdmissionCli.test.ts
@@ -0,0 +1,126 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { expect } from "vitest";
+import { parseEvidence } from "../../../src/domain/evidence.js";
+import { electronPageInspectionSchema } from "../../../src/domain/javascript/electronObservation.js";
+import { startFakeCdpBrowser } from "../../fixtures/fakeCdpBrowser.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { cliTest } from "../../support/cli/cliFixture.js";
+
+const cases: ReadonlyArray<{
+ name: string;
+ parents: readonly number[];
+ names?: readonly number[];
+ secondDocument?: boolean;
+ indices: readonly number[];
+ invalid: number;
+}> = [
+ { name: "valid parent", parents: [-1, 0, 1], indices: [0, 1, 2], invalid: 0 },
+ {
+ name: "out-of-range parent",
+ parents: [-1, 0, 99999],
+ indices: [0, 1],
+ invalid: 1,
+ },
+ { name: "self parent", parents: [-1, 0, 2], indices: [0, 1], invalid: 1 },
+ { name: "parent cycle", parents: [-1, 2, 1], indices: [0], invalid: 2 },
+ {
+ name: "unknown name before a second document",
+ parents: [-1, 0, 1],
+ names: [1, 999, 3],
+ secondDocument: true,
+ indices: [0, 2, 3, 4, 5],
+ invalid: 1,
+ },
+];
+
+for (const scenario of cases)
+ cliTest(
+ `Electron DOM admission preserves source identities: ${scenario.name}`,
+ async ({ cli, onTestFinished }) => {
+ const root = await createTestTempDirectory("rea-electron-dom-admission-");
+ const main = join(root, "index.html");
+ await writeFile(main, "<html/>");
+ const url = pathToFileURL(main).href;
+ const document = (
+ parents: readonly number[],
+ names: readonly number[],
+ ) => ({
+ documentURL: 0,
+ nodes: {
+ nodeType: [9, 1, 1],
+ nodeName: names,
+ nodeValue: [-1, -1, 4],
+ parentIndex: parents,
+ attributes: [[], [], []],
+ },
+ });
+ const browser = await startFakeCdpBrowser({
+ electronFileUrl: url,
+ commandResult: ({ method }) =>
+ method === "DOMSnapshot.captureSnapshot"
+ ? {
+ strings: [url, "#document", "DIV", "SPAN", "πŸ˜€"],
+ documents: [
+ document(scenario.parents, scenario.names ?? [1, 2, 3]),
+ ...(scenario.secondDocument
+ ? [document([-1, 0, 1], [1, 2, 3])]
+ : []),
+ ],
+ }
+ : undefined,
+ });
+ onTestFinished(() => browser.close());
+ const output = await cli.run({
+ arguments: [
+ "inspect-electron-page",
+ browser.endpoint,
+ "electron-page",
+ "--observation-ms",
+ "0",
+ "--json",
+ ],
+ });
+ expect(output.exitCode, output.stderr).toBe(0);
+ const inspection = electronPageInspectionSchema.parse(
+ parseEvidence(output.json).normalized_result,
+ );
+ expect(inspection.dom.total_nodes).toBe(scenario.secondDocument ? 6 : 3);
+ expect(inspection.dom.nodes.map(({ index }) => index)).toEqual(
+ scenario.indices,
+ );
+ const excluded = inspection.completeness.excluded.filter(
+ ({ section, reason }) =>
+ section === "dom" && reason === "invalid_protocol_value",
+ );
+ expect(excluded).toEqual(
+ scenario.invalid === 0
+ ? []
+ : [
+ {
+ section: "dom",
+ reason: "invalid_protocol_value",
+ count: scenario.invalid,
+ },
+ ],
+ );
+ if (scenario.secondDocument)
+ expect(inspection.dom.nodes.at(-1)).toMatchObject({
+ index: 5,
+ parent_index: 4,
+ node_value_length: 4,
+ });
+ if (scenario.invalid === 0)
+ expect(
+ inspection.dom.nodes.map(({ parent_index, node_value_length }) => [
+ parent_index,
+ node_value_length,
+ ]),
+ ).toEqual([
+ [-1, 0],
+ [0, 0],
+ [1, 4],
+ ]);
+ },
+ );