Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(browser): share DOM snapshot admission
morluto70de702109fd
diff --git a/docs/electron-observation.md b/docs/electron-observation.mdindex 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 DOMstructure, resource metadata, stable script/resource identities, explicitcompleteness, and content-addressed script artifacts. Resource sizes are unknownwhen 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 alsoinventories worker, service-worker, and shared-worker targets withvalidated opener-target and parent-frame IDs. Worker discovery uses passivetarget metadata; REA does not attach to or execute code in those targets.diff --git a/src/browser/CdpCaptureDocuments.ts b/src/browser/CdpCaptureDocuments.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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],+ ]);+ },+ );