agent-web-interface 4.3.0 → 4.5.0

package/dist/src/snapshot/heading-index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Heading Index Builder
+ *
+ * Builds a heading context index mapping each backendNodeId to its
+ * heading context based on DOM order traversal.
+ *
+ * @module snapshot/heading-index
+ */
+import type { DomExtractionResult, AxExtractionResult } from './extractors/index.js';
+import type { AdjacencyMaps, IdMapsByContext } from './frame-context.js';
+/**
+ * Build heading index mapping each backendNodeId to its heading context.
+ * Uses DOM order to determine the most recent preceding heading.
+ * Also traverses into shadow roots and iframe content documents.
+ *
+ * Heading context is isolated at iframe boundaries:
+ * - Heading from parent document does NOT propagate into iframe
+ * - Heading from iframe does NOT propagate back to parent document
+ * - Shadow DOM shares heading context with its host document
+ *
+ * @param domResult - DOM extraction result
+ * @param axResult - AX extraction result for heading names
+ * @param idMapsByContext - Context-scoped ID maps for aria-labelledby resolution
+ * @param adjacencyMaps - Precomputed maps for shadow roots and content documents
+ * @returns Map of backendNodeId -> heading context string
+ */
+export declare function buildHeadingIndex(domResult: DomExtractionResult, axResult: AxExtractionResult | undefined, idMapsByContext: IdMapsByContext, adjacencyMaps: AdjacencyMaps): Map<number, string>;
+//# sourceMappingURL=heading-index.d.ts.map

package/dist/src/snapshot/heading-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading-index.d.ts","sourceRoot":"","sources":["../../../src/snapshot/heading-index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGrF,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGzE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,mBAAmB,EAC9B,QAAQ,EAAE,kBAAkB,GAAG,SAAS,EACxC,eAAe,EAAE,eAAe,EAChC,aAAa,EAAE,aAAa,GAC3B,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA2FrB"}

package/dist/src/snapshot/heading-index.js

@@ -0,0 +1,108 @@
+/**
+ * Heading Index Builder
+ *
+ * Builds a heading context index mapping each backendNodeId to its
+ * heading context based on DOM order traversal.
+ *
+ * @module snapshot/heading-index
+ */
+import { resolveLabel } from './extractors/index.js';
+import { getTextContent } from '../lib/text-utils.js';
+import { getIdMapForNode } from './frame-context.js';
+/**
+ * Build heading index mapping each backendNodeId to its heading context.
+ * Uses DOM order to determine the most recent preceding heading.
+ * Also traverses into shadow roots and iframe content documents.
+ *
+ * Heading context is isolated at iframe boundaries:
+ * - Heading from parent document does NOT propagate into iframe
+ * - Heading from iframe does NOT propagate back to parent document
+ * - Shadow DOM shares heading context with its host document
+ *
+ * @param domResult - DOM extraction result
+ * @param axResult - AX extraction result for heading names
+ * @param idMapsByContext - Context-scoped ID maps for aria-labelledby resolution
+ * @param adjacencyMaps - Precomputed maps for shadow roots and content documents
+ * @returns Map of backendNodeId -> heading context string
+ */
+export function buildHeadingIndex(domResult, axResult, idMapsByContext, adjacencyMaps) {
+    const headingIndex = new Map();
+    const shadowHostSet = new Set(domResult.shadowRoots);
+    // Helper to check if a node is a heading and resolve its name
+    function isHeading(backendNodeId) {
+        const domNode = domResult.nodes.get(backendNodeId);
+        const axNode = axResult?.nodes.get(backendNodeId);
+        // Check AX role first
+        const scopedIdMap = domNode ? getIdMapForNode(domNode, idMapsByContext) : undefined;
+        if (axNode?.role === 'heading') {
+            // Priority: AX name -> resolveLabel -> DOM text content
+            let name = axNode.name;
+            if (!name && domNode) {
+                const labelResult = resolveLabel(domNode, axNode, scopedIdMap);
+                if (labelResult.source !== 'none') {
+                    name = labelResult.label;
+                }
+            }
+            name ??= getTextContent(backendNodeId, domResult.nodes);
+            return { isHeading: true, name };
+        }
+        // Check DOM tag (H1-H6)
+        if (domNode?.nodeName?.match(/^H[1-6]$/i)) {
+            // Priority: AX name -> resolveLabel -> DOM text content
+            let name = axNode?.name;
+            if (!name) {
+                const labelResult = resolveLabel(domNode, axNode, scopedIdMap);
+                if (labelResult.source !== 'none') {
+                    name = labelResult.label;
+                }
+            }
+            name ??= getTextContent(backendNodeId, domResult.nodes);
+            return { isHeading: true, name };
+        }
+        return { isHeading: false };
+    }
+    // Traverse DOM in pre-order, passing and returning heading context
+    function traverse(nodeId, currentHeading) {
+        const node = domResult.nodes.get(nodeId);
+        if (!node)
+            return currentHeading;
+        // Check if this node is a heading
+        const headingInfo = isHeading(nodeId);
+        if (headingInfo.isHeading && headingInfo.name) {
+            currentHeading = headingInfo.name;
+        }
+        // Record the current heading context for this node
+        if (currentHeading) {
+            headingIndex.set(nodeId, currentHeading);
+        }
+        // 1. Process light DOM children first (pre-order DFS)
+        // Heading context propagates and updates through light DOM
+        if (node.childNodeIds) {
+            for (const childId of node.childNodeIds) {
+                currentHeading = traverse(childId, currentHeading) ?? currentHeading;
+            }
+        }
+        // 2. If this node hosts a shadow root, traverse shadow content (O(1) lookup)
+        // Shadow DOM shares heading context with host document (same logical document)
+        if (shadowHostSet.has(nodeId)) {
+            const shadowRoots = adjacencyMaps.shadowRootsByHost.get(nodeId) ?? [];
+            for (const shadowRootId of shadowRoots) {
+                currentHeading = traverse(shadowRootId, currentHeading) ?? currentHeading;
+            }
+        }
+        // 3. If this node is an iframe, traverse content document (O(1) lookup)
+        // IMPORTANT: Heading context resets at iframe boundary (separate document)
+        // - Pass undefined to reset context inside iframe
+        // - Discard returned heading (iframe headings don't affect parent)
+        if (node.frameId || node.nodeName.toUpperCase() === 'IFRAME') {
+            const contentDocs = adjacencyMaps.contentDocsByFrame.get(nodeId) ?? [];
+            for (const contentDocId of contentDocs) {
+                traverse(contentDocId, undefined);
+            }
+        }
+        return currentHeading;
+    }
+    traverse(domResult.rootId, undefined);
+    return headingIndex;
+}
+//# sourceMappingURL=heading-index.js.map

package/dist/src/snapshot/heading-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading-index.js","sourceRoot":"","sources":["../../../src/snapshot/heading-index.ts"],"names":[],"mappings":"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"}

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

@@ -6,9 +6,11 @@
  * @module snapshot
  */
 export type { BaseSnapshot, Viewport, SnapshotMeta, ReadableNode, NodeKind, SemanticRegion, NodeLocation, NodeLayout, BBox, BoundingBox, ScreenZone, NodeState, NodeLocators, NodeAttributes, SnapshotOptions, SnapshotResult, } from './snapshot.types.js';
-export { isInteractiveNode, isReadableNode, isStructuralNode } from './snapshot.types.js';
+export { isInteractiveNode, isReadableNode, isStructuralNode, isLiveRegionNode, } from './snapshot.types.js';
 export { SnapshotStore, type SnapshotEntry, type SnapshotStoreOptions, type SnapshotStoreStats, } from './snapshot-store.js';
-export { clickByBackendNodeId, clickAtCoordinates, clickAtElementOffset, getElementTopLeft, dragBetweenCoordinates, typeByBackendNodeId, pressKey, selectOption, hoverByBackendNodeId, scrollIntoView, scrollPage, clearFocusedText, MODIFIER_ALT, MODIFIER_CTRL, MODIFIER_META, MODIFIER_SHIFT, } from './element-resolver.js';
-export { SnapshotCompiler, compileSnapshot, type CompileOptions } from './snapshot-compiler.js';
+export { clickByBackendNodeId, clickAtCoordinates, clickAtElementOffset, getElementTopLeft, dragBetweenCoordinates, dispatchWheelEvent, typeByBackendNodeId, pressKey, selectOption, hoverByBackendNodeId, scrollIntoView, scrollPage, clearFocusedText, MODIFIER_ALT, MODIFIER_CTRL, MODIFIER_META, MODIFIER_SHIFT, } from './element-resolver.js';
+export { SnapshotCompiler, compileSnapshot } from './snapshot-compiler.js';
+export type { CompileOptions } from './kind-mapping.js';
+export { sliceWithOverlayPriority } from './node-filter.js';
 export * from './extractors/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/snapshot/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/snapshot/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,UAAU,EACV,IAAI,EACJ,WAAW,EACX,UAAU,EACV,SAAS,EACT,YAAY,EACZ,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG1F,OAAO,EACL,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGhG,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/snapshot/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,UAAU,EACV,IAAI,EACJ,WAAW,EACX,UAAU,EACV,SAAS,EACT,YAAY,EACZ,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC3E,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAG5D,cAAc,uBAAuB,CAAC"}

package/dist/src/snapshot/index.js

@@ -6,13 +6,14 @@
  * @module snapshot
  */
 // Type guards
-export { isInteractiveNode, isReadableNode, isStructuralNode } from './snapshot.types.js';
+export { isInteractiveNode, isReadableNode, isStructuralNode, isLiveRegionNode, } from './snapshot.types.js';
 // Store
 export { SnapshotStore, } from './snapshot-store.js';
 // Element resolver - CDP input functions
-export { clickByBackendNodeId, clickAtCoordinates, clickAtElementOffset, getElementTopLeft, dragBetweenCoordinates, typeByBackendNodeId, pressKey, selectOption, hoverByBackendNodeId, scrollIntoView, scrollPage, clearFocusedText, MODIFIER_ALT, MODIFIER_CTRL, MODIFIER_META, MODIFIER_SHIFT, } from './element-resolver.js';
+export { clickByBackendNodeId, clickAtCoordinates, clickAtElementOffset, getElementTopLeft, dragBetweenCoordinates, dispatchWheelEvent, typeByBackendNodeId, pressKey, selectOption, hoverByBackendNodeId, scrollIntoView, scrollPage, clearFocusedText, MODIFIER_ALT, MODIFIER_CTRL, MODIFIER_META, MODIFIER_SHIFT, } from './element-resolver.js';
 // Snapshot compiler
 export { SnapshotCompiler, compileSnapshot } from './snapshot-compiler.js';
+export { sliceWithOverlayPriority } from './node-filter.js';
 // Extractors (advanced usage)
 export * from './extractors/index.js';
 //# sourceMappingURL=index.js.map

package/dist/src/snapshot/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/snapshot/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsBH,cAAc;AACd,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE1F,QAAQ;AACR,OAAO,EACL,aAAa,GAId,MAAM,qBAAqB,CAAC;AAE7B,yCAAyC;AACzC,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC;AAE/B,oBAAoB;AACpB,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAuB,MAAM,wBAAwB,CAAC;AAEhG,8BAA8B;AAC9B,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/snapshot/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsBH,cAAc;AACd,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAE7B,QAAQ;AACR,OAAO,EACL,aAAa,GAId,MAAM,qBAAqB,CAAC;AAE7B,yCAAyC;AACzC,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC;AAE/B,oBAAoB;AACpB,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,8BAA8B;AAC9B,cAAc,uBAAuB,CAAC"}

package/dist/src/snapshot/kind-mapping.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Kind Mapping
+ *
+ * Maps AX roles and HTML tags to NodeKind values.
+ *
+ * @module snapshot/kind-mapping
+ */
+import type { NodeKind, SnapshotOptions } from './snapshot.types.js';
+/**
+ * Snapshot compiler options
+ */
+export interface CompileOptions extends Partial<SnapshotOptions> {
+    /** Include readable content nodes (headings, paragraphs). Default: true */
+    includeReadable?: boolean;
+    /** Extract bounding boxes and layout info. Default: true */
+    includeLayout?: boolean;
+}
+/**
+ * Default compile options
+ */
+export declare const DEFAULT_OPTIONS: Required<CompileOptions>;
+/**
+ * Map AX role to NodeKind.
+ */
+export declare function mapRoleToKind(role: string | undefined): NodeKind | undefined;
+/**
+ * Get NodeKind from HTML tag name.
+ */
+export declare function getKindFromTag(tagName: string): NodeKind | undefined;
+//# sourceMappingURL=kind-mapping.d.ts.map

package/dist/src/snapshot/kind-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kind-mapping.d.ts","sourceRoot":"","sources":["../../../src/snapshot/kind-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,OAAO,CAAC,eAAe,CAAC;IAC9D,2EAA2E;IAC3E,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,4DAA4D;IAC5D,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,cAAc,CAQpD,CAAC;AAoFF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAG5E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAEpE"}

package/dist/src/snapshot/kind-mapping.js

@@ -0,0 +1,114 @@
+/**
+ * Kind Mapping
+ *
+ * Maps AX roles and HTML tags to NodeKind values.
+ *
+ * @module snapshot/kind-mapping
+ */
+/**
+ * Default compile options
+ */
+export const DEFAULT_OPTIONS = {
+    include_hidden: false,
+    max_nodes: 2000,
+    timeout: 30000,
+    redact_sensitive: true,
+    include_values: true, // Enable value extraction with password redaction
+    includeReadable: true,
+    includeLayout: true,
+};
+/** AX role → NodeKind lookup (hoisted to avoid per-call allocation) */
+const ROLE_TO_KIND = {
+    // Interactive
+    button: 'button',
+    link: 'link',
+    textbox: 'input',
+    searchbox: 'input',
+    combobox: 'combobox',
+    listbox: 'select',
+    checkbox: 'checkbox',
+    radio: 'radio',
+    switch: 'switch',
+    slider: 'slider',
+    spinbutton: 'slider',
+    tab: 'tab',
+    menuitem: 'menuitem',
+    menuitemcheckbox: 'menuitem',
+    menuitemradio: 'menuitem',
+    option: 'menuitem',
+    // Readable
+    heading: 'heading',
+    paragraph: 'paragraph',
+    text: 'text',
+    statictext: 'text',
+    list: 'list',
+    listitem: 'listitem',
+    tree: 'list',
+    treeitem: 'listitem',
+    image: 'image',
+    img: 'image',
+    figure: 'image',
+    canvas: 'canvas',
+    table: 'table',
+    grid: 'table',
+    treegrid: 'table',
+    // Structural
+    form: 'form',
+    dialog: 'dialog',
+    alertdialog: 'dialog',
+    navigation: 'navigation',
+    region: 'section',
+    article: 'section',
+    main: 'section',
+    banner: 'section',
+    complementary: 'section',
+    contentinfo: 'section',
+    // Live region / ephemeral feedback
+    alert: 'alert',
+    status: 'status',
+    log: 'log',
+    marquee: 'log',
+    timer: 'timer',
+    tooltip: 'tooltip',
+    progressbar: 'progressbar',
+};
+/** HTML tag → NodeKind lookup (hoisted to avoid per-call allocation) */
+const TAG_TO_KIND = {
+    BUTTON: 'button',
+    A: 'link',
+    INPUT: 'input',
+    TEXTAREA: 'textarea',
+    SELECT: 'select',
+    H1: 'heading',
+    H2: 'heading',
+    H3: 'heading',
+    H4: 'heading',
+    H5: 'heading',
+    H6: 'heading',
+    P: 'paragraph',
+    IMG: 'image',
+    TABLE: 'table',
+    UL: 'list',
+    OL: 'list',
+    LI: 'listitem',
+    FORM: 'form',
+    DIALOG: 'dialog',
+    NAV: 'navigation',
+    OPTION: 'menuitem',
+    CANVAS: 'canvas',
+};
+/**
+ * Map AX role to NodeKind.
+ */
+export function mapRoleToKind(role) {
+    if (!role)
+        return undefined;
+    return ROLE_TO_KIND[role.toLowerCase()];
+}
+/**
+ * Get NodeKind from HTML tag name.
+ */
+export function getKindFromTag(tagName) {
+    return TAG_TO_KIND[tagName.toUpperCase()];
+}
+//# sourceMappingURL=kind-mapping.js.map

package/dist/src/snapshot/kind-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kind-mapping.js","sourceRoot":"","sources":["../../../src/snapshot/kind-mapping.ts"],"names":[],"mappings":"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"}

package/dist/src/snapshot/node-filter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Node Filtering
+ *
+ * Filters noise nodes and slices to budget while preserving overlay content.
+ *
+ * @module snapshot/node-filter
+ */
+import type { ReadableNode } from './snapshot.types.js';
+import type { RawNodeData, RawDomNode, RawAxNode } from './extractors/index.js';
+/**
+ * Filter out noise nodes to reduce snapshot size.
+ *
+ * Filters:
+ * 1. Empty list/listitem containers with no semantic name AND no interactive descendants
+ * 2. StaticText/text nodes that mirror their parent's label exactly
+ */
+export declare function filterNoiseNodes(nodes: ReadableNode[], domTree: Map<number, RawDomNode>, axTree: Map<number, RawAxNode>): ReadableNode[];
+/**
+ * Slice nodes to max_nodes budget while preserving high z-index overlay content.
+ *
+ * Portal-rendered content (dropdowns, popovers, modals) appears at the end of
+ * DOM order. On heavy pages, a naive slice truncates it.
+ *
+ * Strategy:
+ * 1. Partition nodes into overlay (z-index > threshold) and main
+ * 2. Take all overlay nodes (up to 30% of budget)
+ * 3. Fill remaining budget with main nodes (DOM order)
+ * 4. Re-sort by original DOM order
+ */
+export declare function sliceWithOverlayPriority(nodes: RawNodeData[], maxNodes: number): RawNodeData[];
+//# sourceMappingURL=node-filter.d.ts.map

package/dist/src/snapshot/node-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-filter.d.ts","sourceRoot":"","sources":["../../../src/snapshot/node-filter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGhF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,EAAE,EACrB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAChC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GAC7B,YAAY,EAAE,CAkFhB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CA2C9F"}

package/dist/src/snapshot/node-filter.js

@@ -0,0 +1,137 @@
+/**
+ * Node Filtering
+ *
+ * Filters noise nodes and slices to budget while preserving overlay content.
+ *
+ * @module snapshot/node-filter
+ */
+import { isInteractiveKind } from '../state/actionables-filter.js';
+/**
+ * Filter out noise nodes to reduce snapshot size.
+ *
+ * Filters:
+ * 1. Empty list/listitem containers with no semantic name AND no interactive descendants
+ * 2. StaticText/text nodes that mirror their parent's label exactly
+ */
+export function filterNoiseNodes(nodes, domTree, axTree) {
+    // Build set of interactive node backend IDs for descendant checking
+    const interactiveBackendIds = new Set(nodes.filter((n) => isInteractiveKind(n.kind)).map((n) => n.backend_node_id));
+    // Build parent-child relationship from DOM tree
+    const childToParent = new Map();
+    for (const [nodeId, domNode] of domTree) {
+        if (domNode.parentId !== undefined) {
+            childToParent.set(nodeId, domNode.parentId);
+        }
+    }
+    // Check if a node has any interactive descendants in the DOM tree
+    const hasInteractiveDescendant = (nodeId) => {
+        const domNode = domTree.get(nodeId);
+        if (!domNode)
+            return false;
+        // Check direct children
+        if (domNode.childNodeIds) {
+            for (const childId of domNode.childNodeIds) {
+                if (interactiveBackendIds.has(childId)) {
+                    return true;
+                }
+                if (hasInteractiveDescendant(childId)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    };
+    // Get label of parent node in the node list
+    const getParentLabel = (nodeId) => {
+        const parentId = childToParent.get(nodeId);
+        if (parentId === undefined)
+            return undefined;
+        // Look up parent in our node list
+        const parentNode = nodes.find((n) => n.backend_node_id === parentId);
+        if (parentNode) {
+            return parentNode.label;
+        }
+        // Parent might be further up - check AX tree for parent's name
+        const parentAx = axTree.get(parentId);
+        return parentAx?.name;
+    };
+    // Container kinds that can be noisy when empty
+    const containerKinds = new Set(['list', 'listitem']);
+    // Text kinds that can duplicate parent labels
+    const textKinds = new Set(['text']);
+    return nodes.filter((node) => {
+        // Rule 1: Filter empty container nodes without interactive descendants
+        if (containerKinds.has(node.kind)) {
+            const hasSemanticName = node.label && node.label.trim().length > 0;
+            if (!hasSemanticName) {
+                const hasInteractive = hasInteractiveDescendant(node.backend_node_id);
+                if (!hasInteractive) {
+                    return false; // Filter out empty container without interactive content
+                }
+            }
+        }
+        // Rule 2: Filter text nodes that mirror parent's label
+        if (textKinds.has(node.kind)) {
+            const parentLabel = getParentLabel(node.backend_node_id);
+            if (parentLabel && node.label) {
+                // Normalize and compare
+                const normalizedParent = parentLabel.trim().toLowerCase();
+                const normalizedNode = node.label.trim().toLowerCase();
+                if (normalizedNode === normalizedParent) {
+                    return false; // Filter out duplicate text
+                }
+            }
+        }
+        return true; // Keep the node
+    });
+}
+/**
+ * Slice nodes to max_nodes budget while preserving high z-index overlay content.
+ *
+ * Portal-rendered content (dropdowns, popovers, modals) appears at the end of
+ * DOM order. On heavy pages, a naive slice truncates it.
+ *
+ * Strategy:
+ * 1. Partition nodes into overlay (z-index > threshold) and main
+ * 2. Take all overlay nodes (up to 30% of budget)
+ * 3. Fill remaining budget with main nodes (DOM order)
+ * 4. Re-sort by original DOM order
+ */
+export function sliceWithOverlayPriority(nodes, maxNodes) {
+    if (nodes.length <= maxNodes) {
+        return nodes;
+    }
+    const OVERLAY_Z_THRESHOLD = 100;
+    const MAX_OVERLAY_RATIO = 0.3;
+    const overlayNodes = [];
+    const mainNodes = [];
+    for (const node of nodes) {
+        const zIndex = node.layout?.zIndex;
+        if (zIndex !== undefined && zIndex > OVERLAY_Z_THRESHOLD) {
+            overlayNodes.push(node);
+        }
+        else {
+            mainNodes.push(node);
+        }
+    }
+    // No overlay content → simple slice
+    if (overlayNodes.length === 0) {
+        return nodes.slice(0, maxNodes);
+    }
+    // Reserve budget for overlay (capped at 30% of total)
+    const maxOverlay = Math.min(overlayNodes.length, Math.floor(maxNodes * MAX_OVERLAY_RATIO));
+    const overlaySlice = overlayNodes.slice(0, maxOverlay);
+    // Fill remaining budget with main content
+    const mainBudget = maxNodes - overlaySlice.length;
+    const mainSlice = mainNodes.slice(0, mainBudget);
+    // Merge and re-sort by original DOM order
+    const merged = [...mainSlice, ...overlaySlice];
+    const indexMap = new Map(nodes.map((n, i) => [n.backendNodeId, i]));
+    merged.sort((a, b) => {
+        const ia = indexMap.get(a.backendNodeId) ?? Infinity;
+        const ib = indexMap.get(b.backendNodeId) ?? Infinity;
+        return ia - ib;
+    });
+    return merged;
+}
+//# sourceMappingURL=node-filter.js.map

package/dist/src/snapshot/node-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-filter.js","sourceRoot":"","sources":["../../../src/snapshot/node-filter.ts"],"names":[],"mappings":"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"}

package/dist/src/snapshot/node-synthesizer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Node Synthesizer
+ *
+ * Synthesizes nodes from DOM data that the AX tree misses or misclassifies:
+ * - Option nodes from <select> children (often marked as ignored by Chrome)
+ * - Canvas nodes (classified as generic/ignored by AX tree)
+ * - Toast library nodes (promoted to alert role for unsemantic toast libraries)
+ *
+ * @module snapshot/node-synthesizer
+ */
+import type { RawNodeData, RawDomNode, DomExtractionResult } from './extractors/index.js';
+/**
+ * Data attributes used by unsemantic toast libraries.
+ * Keep in sync with TOAST_LIBRARY_SELECTOR in observer-script.ts.
+ */
+export declare const TOAST_DATA_ATTRS: string[];
+/**
+ * CSS class substrings used by unsemantic toast libraries.
+ * Keep in sync with TOAST_LIBRARY_SELECTOR in observer-script.ts.
+ */
+export declare const TOAST_CLASS_PATTERNS: string[];
+/**
+ * Check if a DOM node belongs to a known unsemantic toast library.
+ */
+export declare function isToastLibraryNode(domNode: RawDomNode): boolean;
+/**
+ * Synthesize option nodes from <select> children.
+ *
+ * Chrome's AX tree often marks <option> nodes as ignored when the select
+ * is collapsed, and their bounding boxes are zero (OS-rendered).
+ * We inject them from the DOM so AI agents can discover available options.
+ *
+ * @param nodesToProcess - Current node list (mutated in place)
+ * @param domResult - DOM extraction result
+ */
+export declare function synthesizeOptionNodes(nodesToProcess: RawNodeData[], domResult: DomExtractionResult): void;
+/**
+ * Synthesize canvas nodes from DOM.
+ *
+ * Canvas elements are classified as generic/ignored by the AX tree,
+ * so we inject them from the DOM so AI agents can discover and interact with them.
+ *
+ * @param nodesToProcess - Current node list (mutated in place)
+ * @param domResult - DOM extraction result
+ */
+export declare function synthesizeCanvasNodes(nodesToProcess: RawNodeData[], domResult: DomExtractionResult): void;
+/**
+ * Promote unsemantic toast library nodes to alert role.
+ *
+ * Popular toast libraries (Sonner, react-hot-toast, Toastify, Ant Design, Chakra UI)
+ * don't use ARIA roles. Detect them by data attributes and CSS classes.
+ * Selectors mirror TOAST_LIBRARY_SELECTOR in observer-script.ts — keep in sync.
+ *
+ * Some toast elements (e.g., Sonner's <li data-sonner-toast>) are already in
+ * nodesToProcess via the AX tree (as listitem/generic), so we must also override
+ * their axNode role — not just add new nodes.
+ *
+ * @param nodesToProcess - Current node list (mutated in place)
+ * @param domResult - DOM extraction result
+ */
+export declare function promoteToastNodes(nodesToProcess: RawNodeData[], domResult: DomExtractionResult): void;
+//# sourceMappingURL=node-synthesizer.d.ts.map

package/dist/src/snapshot/node-synthesizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-synthesizer.d.ts","sourceRoot":"","sources":["../../../src/snapshot/node-synthesizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EAEV,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAG/B;;;GAGG;AACH,eAAO,MAAM,gBAAgB,UAA0C,CAAC;AAExE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,UAKhC,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAgB/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,WAAW,EAAE,EAC7B,SAAS,EAAE,mBAAmB,GAC7B,IAAI,CA6DN;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,WAAW,EAAE,EAC7B,SAAS,EAAE,mBAAmB,GAC7B,IAAI,CAsBN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,WAAW,EAAE,EAC7B,SAAS,EAAE,mBAAmB,GAC7B,IAAI,CA2BN"}