agent-web-interface 4.0.0

package/dist/src/snapshot/extractors/region-resolver.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Region Resolver
+ *
+ * Determines semantic page region for each node.
+ *
+ * @module snapshot/extractors/region-resolver
+ *
+ * Sources:
+ * - ARIA landmark roles (banner, navigation, main, contentinfo)
+ * - HTML5 sectioning elements (header, nav, main, footer, aside)
+ * - Ancestor traversal for inherited region
+ */
+import type { SemanticRegion } from '../snapshot.types.js';
+import type { RawDomNode, RawAxNode } from './types.js';
+/**
+ * Resolve semantic region for a node.
+ *
+ * Priority:
+ * 1. AX role (most reliable)
+ * 2. DOM role attribute
+ * 3. HTML5 tag name
+ * 4. Ancestor traversal (checks DOM tags, DOM role attrs, AND AX roles)
+ *
+ * @param domNode - Raw DOM node data (optional)
+ * @param axNode - Raw AX node data (optional)
+ * @param domTree - Full DOM tree for ancestor lookup
+ * @param axTree - Full AX tree for ancestor AX role lookup (optional)
+ * @returns SemanticRegion
+ */
+export declare function resolveRegion(domNode: RawDomNode | undefined, axNode: RawAxNode | undefined, domTree: Map<number, RawDomNode>, axTree?: Map<number, RawAxNode>): SemanticRegion;
+//# sourceMappingURL=region-resolver.d.ts.map

package/dist/src/snapshot/extractors/region-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"region-resolver.d.ts","sourceRoot":"","sources":["../../../../src/snapshot/extractors/region-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAmExD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAChC,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GAC9B,cAAc,CA4BhB"}

package/dist/src/snapshot/extractors/region-resolver.js

@@ -0,0 +1,168 @@
+/**
+ * Region Resolver
+ *
+ * Determines semantic page region for each node.
+ *
+ * @module snapshot/extractors/region-resolver
+ *
+ * Sources:
+ * - ARIA landmark roles (banner, navigation, main, contentinfo)
+ * - HTML5 sectioning elements (header, nav, main, footer, aside)
+ * - Ancestor traversal for inherited region
+ */
+/**
+ * Mapping of ARIA roles to semantic regions
+ */
+const ROLE_TO_REGION = {
+    banner: 'header',
+    navigation: 'nav',
+    main: 'main',
+    complementary: 'aside',
+    contentinfo: 'footer',
+    dialog: 'dialog',
+    alertdialog: 'dialog',
+    search: 'search',
+    form: 'form',
+    region: 'unknown', // Generic region
+};
+/**
+ * Mapping of HTML5 sectioning tags to semantic regions
+ */
+const TAG_TO_REGION = {
+    HEADER: 'header',
+    NAV: 'nav',
+    MAIN: 'main',
+    ASIDE: 'aside',
+    FOOTER: 'footer',
+    DIALOG: 'dialog',
+    FORM: 'form',
+    SEARCH: 'search',
+};
+/**
+ * Get region from AX role.
+ *
+ * @param role - AX role string
+ * @returns SemanticRegion or undefined
+ */
+function getRegionFromRole(role) {
+    if (!role)
+        return undefined;
+    return ROLE_TO_REGION[role.toLowerCase()];
+}
+/**
+ * Get region from DOM tag name.
+ *
+ * @param tagName - DOM tag name
+ * @returns SemanticRegion or undefined
+ */
+function getRegionFromTag(tagName) {
+    if (!tagName)
+        return undefined;
+    return TAG_TO_REGION[tagName.toUpperCase()];
+}
+/**
+ * Get region from DOM role attribute.
+ *
+ * @param attributes - DOM attributes
+ * @returns SemanticRegion or undefined
+ */
+function getRegionFromDomRole(attributes) {
+    if (!attributes?.role)
+        return undefined;
+    return ROLE_TO_REGION[attributes.role.toLowerCase()];
+}
+/**
+ * Resolve semantic region for a node.
+ *
+ * Priority:
+ * 1. AX role (most reliable)
+ * 2. DOM role attribute
+ * 3. HTML5 tag name
+ * 4. Ancestor traversal (checks DOM tags, DOM role attrs, AND AX roles)
+ *
+ * @param domNode - Raw DOM node data (optional)
+ * @param axNode - Raw AX node data (optional)
+ * @param domTree - Full DOM tree for ancestor lookup
+ * @param axTree - Full AX tree for ancestor AX role lookup (optional)
+ * @returns SemanticRegion
+ */
+export function resolveRegion(domNode, axNode, domTree, axTree) {
+    // 1. Check AX role (highest priority)
+    const axRegion = getRegionFromRole(axNode?.role);
+    if (axRegion && axRegion !== 'unknown') {
+        return axRegion;
+    }
+    // 2. Check DOM role attribute
+    const domRoleRegion = getRegionFromDomRole(domNode?.attributes);
+    if (domRoleRegion && domRoleRegion !== 'unknown') {
+        return domRoleRegion;
+    }
+    // 3. Check current node's tag
+    const tagRegion = getRegionFromTag(domNode?.nodeName);
+    if (tagRegion && tagRegion !== 'unknown') {
+        return tagRegion;
+    }
+    // 4. Traverse ancestors to find containing landmark
+    if (domNode && domTree.size > 0) {
+        const ancestorRegion = findAncestorRegion(domNode, domTree, axTree);
+        if (ancestorRegion && ancestorRegion !== 'unknown') {
+            return ancestorRegion;
+        }
+    }
+    return 'unknown';
+}
+/**
+ * Find region by traversing DOM ancestors.
+ *
+ * Checks (in priority order):
+ * 1. Parent's AX role (if axTree provided)
+ * 2. Parent's DOM tag name
+ * 3. Parent's DOM role attribute
+ *
+ * @param node - Starting node
+ * @param domTree - Full DOM tree
+ * @param axTree - Full AX tree (optional)
+ * @returns SemanticRegion from nearest ancestor landmark, or undefined
+ */
+function findAncestorRegion(node, domTree, axTree) {
+    let currentId = node.parentId;
+    const visited = new Set();
+    // Traverse up to 50 levels (prevent infinite loops)
+    let depth = 0;
+    const maxDepth = 50;
+    while (currentId !== undefined && depth < maxDepth) {
+        if (visited.has(currentId)) {
+            // Cycle detected
+            break;
+        }
+        visited.add(currentId);
+        const parentNode = domTree.get(currentId);
+        if (!parentNode) {
+            break;
+        }
+        // Check parent's AX role (highest priority if available)
+        if (axTree) {
+            const parentAx = axTree.get(currentId);
+            if (parentAx?.role) {
+                const axRoleRegion = getRegionFromRole(parentAx.role);
+                if (axRoleRegion && axRoleRegion !== 'unknown') {
+                    return axRoleRegion;
+                }
+            }
+        }
+        // Check parent's tag for landmark
+        const tagRegion = getRegionFromTag(parentNode.nodeName);
+        if (tagRegion && tagRegion !== 'unknown') {
+            return tagRegion;
+        }
+        // Check parent's role attribute
+        const roleRegion = getRegionFromDomRole(parentNode.attributes);
+        if (roleRegion && roleRegion !== 'unknown') {
+            return roleRegion;
+        }
+        currentId = parentNode.parentId;
+        depth++;
+    }
+    return undefined;
+}
+//# sourceMappingURL=region-resolver.js.map

package/dist/src/snapshot/extractors/region-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"region-resolver.js","sourceRoot":"","sources":["../../../../src/snapshot/extractors/region-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH;;GAEG;AACH,MAAM,cAAc,GAAmC;IACrD,MAAM,EAAE,QAAQ;IAChB,UAAU,EAAE,KAAK;IACjB,IAAI,EAAE,MAAM;IACZ,aAAa,EAAE,OAAO;IACtB,WAAW,EAAE,QAAQ;IACrB,MAAM,EAAE,QAAQ;IAChB,WAAW,EAAE,QAAQ;IACrB,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,SAAS,EAAE,iBAAiB;CACrC,CAAC;AAEF;;GAEG;AACH,MAAM,aAAa,GAAmC;IACpD,MAAM,EAAE,QAAQ;IAChB,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;CACjB,CAAC;AAEF;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,IAAwB;IACjD,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,OAAO,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,OAA2B;IACnD,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,OAAO,aAAa,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,SAAS,oBAAoB,CAC3B,UAA8C;IAE9C,IAAI,CAAC,UAAU,EAAE,IAAI;QAAE,OAAO,SAAS,CAAC;IACxC,OAAO,cAAc,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAC3B,OAA+B,EAC/B,MAA6B,EAC7B,OAAgC,EAChC,MAA+B;IAE/B,sCAAsC;IACtC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACjD,IAAI,QAAQ,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACvC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,8BAA8B;IAC9B,MAAM,aAAa,GAAG,oBAAoB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAChE,IAAI,aAAa,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QACjD,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,8BAA8B;IAC9B,MAAM,SAAS,GAAG,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACtD,IAAI,SAAS,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QACzC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,oDAAoD;IACpD,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,cAAc,GAAG,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACpE,IAAI,cAAc,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;YACnD,OAAO,cAAc,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,kBAAkB,CACzB,IAAgB,EAChB,OAAgC,EAChC,MAA+B;IAE/B,IAAI,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC9B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,oDAAoD;IACpD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,QAAQ,GAAG,EAAE,CAAC;IAEpB,OAAO,SAAS,KAAK,SAAS,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;QACnD,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,iBAAiB;YACjB,MAAM;QACR,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAEvB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM;QACR,CAAC;QAED,yDAAyD;QACzD,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACvC,IAAI,QAAQ,EAAE,IAAI,EAAE,CAAC;gBACnB,MAAM,YAAY,GAAG,iBAAiB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;gBACtD,IAAI,YAAY,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;oBAC/C,OAAO,YAAY,CAAC;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;QAED,kCAAkC;QAClC,MAAM,SAAS,GAAG,gBAAgB,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QACxD,IAAI,SAAS,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YACzC,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,gCAAgC;QAChC,MAAM,UAAU,GAAG,oBAAoB,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAC/D,IAAI,UAAU,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC3C,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC;QAChC,KAAK,EAAE,CAAC;IACV,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/src/snapshot/extractors/state-extractor.d.ts

@@ -0,0 +1,30 @@
+/**
+ * State Extractor
+ *
+ * Extracts interactive element state (visible, enabled, checked, etc.)
+ * by merging data from AX tree properties, DOM attributes, and layout.
+ *
+ * @module snapshot/extractors/state-extractor
+ *
+ * Sources (priority order):
+ * 1. AX tree properties (checked, expanded, selected, disabled)
+ * 2. DOM attributes (disabled, readonly, required)
+ * 3. Computed visibility from layout
+ */
+import type { NodeState } from '../snapshot.types.js';
+import type { RawDomNode, RawAxNode, NodeLayoutInfo } from './types.js';
+/**
+ * Extract state for an interactive element.
+ *
+ * Merges state from multiple sources:
+ * - AX properties (primary source)
+ * - DOM attributes (fallback)
+ * - Layout information (visibility)
+ *
+ * @param domNode - Raw DOM node data (optional)
+ * @param axNode - Raw AX node data (optional)
+ * @param layout - Node layout info (optional)
+ * @returns NodeState object
+ */
+export declare function extractState(domNode: RawDomNode | undefined, axNode: RawAxNode | undefined, layout: NodeLayoutInfo | undefined): NodeState;
+//# sourceMappingURL=state-extractor.d.ts.map

package/dist/src/snapshot/extractors/state-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-extractor.d.ts","sourceRoot":"","sources":["../../../../src/snapshot/extractors/state-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAc,MAAM,YAAY,CAAC;AAuEpF;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,SAAS,CAyFX"}

package/dist/src/snapshot/extractors/state-extractor.js

@@ -0,0 +1,181 @@
+/**
+ * State Extractor
+ *
+ * Extracts interactive element state (visible, enabled, checked, etc.)
+ * by merging data from AX tree properties, DOM attributes, and layout.
+ *
+ * @module snapshot/extractors/state-extractor
+ *
+ * Sources (priority order):
+ * 1. AX tree properties (checked, expanded, selected, disabled)
+ * 2. DOM attributes (disabled, readonly, required)
+ * 3. Computed visibility from layout
+ */
+/**
+ * Get AX property value by name.
+ *
+ * @param properties - Array of AX properties
+ * @param name - Property name to find
+ * @returns Property value or undefined
+ */
+function getAxProperty(properties, name) {
+    if (!properties)
+        return undefined;
+    const prop = properties.find((p) => p.name === name);
+    return prop?.value?.value;
+}
+/**
+ * Check if DOM node has a boolean attribute (present = true).
+ *
+ * @param attributes - DOM attributes record
+ * @param name - Attribute name
+ * @returns true if attribute is present
+ */
+function hasBooleanAttribute(attributes, name) {
+    if (!attributes)
+        return false;
+    return name in attributes;
+}
+/**
+ * Get ARIA attribute value from DOM.
+ *
+ * @param attributes - DOM attributes record
+ * @param name - ARIA attribute name (e.g., 'aria-disabled')
+ * @returns Attribute value or undefined
+ */
+function getAriaAttribute(attributes, name) {
+    if (!attributes)
+        return undefined;
+    return attributes[name];
+}
+/**
+ * Parse checked state from AX property value.
+ * AX uses tristate: 'true', 'false', 'mixed'
+ *
+ * @param value - AX property value
+ * @returns boolean for true/false, undefined for mixed or unset
+ */
+function parseCheckedState(value) {
+    if (value === true || value === 'true')
+        return true;
+    if (value === false || value === 'false')
+        return false;
+    // 'mixed' or undefined results in undefined
+    return undefined;
+}
+/**
+ * Parse boolean state from various value types.
+ *
+ * @param value - Value to parse
+ * @returns boolean or undefined
+ */
+function parseBooleanState(value) {
+    if (value === true || value === 'true')
+        return true;
+    if (value === false || value === 'false')
+        return false;
+    return undefined;
+}
+/**
+ * Extract state for an interactive element.
+ *
+ * Merges state from multiple sources:
+ * - AX properties (primary source)
+ * - DOM attributes (fallback)
+ * - Layout information (visibility)
+ *
+ * @param domNode - Raw DOM node data (optional)
+ * @param axNode - Raw AX node data (optional)
+ * @param layout - Node layout info (optional)
+ * @returns NodeState object
+ */
+export function extractState(domNode, axNode, layout) {
+    const attributes = domNode?.attributes;
+    const properties = axNode?.properties;
+    // === Visibility ===
+    // Primary: layout.isVisible
+    // Default: true (assume visible if no layout info)
+    const visible = layout?.isVisible ?? true;
+    // === Enabled ===
+    // Priority: AX disabled > DOM disabled > aria-disabled
+    let enabled = true;
+    // Check AX disabled property
+    const axDisabled = getAxProperty(properties, 'disabled');
+    if (axDisabled !== undefined) {
+        enabled = !parseBooleanState(axDisabled);
+    }
+    else {
+        // Fallback to DOM attributes
+        if (hasBooleanAttribute(attributes, 'disabled')) {
+            enabled = false;
+        }
+        else if (getAriaAttribute(attributes, 'aria-disabled') === 'true') {
+            enabled = false;
+        }
+    }
+    // === Checked (checkboxes, radios, switches) ===
+    const axChecked = getAxProperty(properties, 'checked');
+    const checked = parseCheckedState(axChecked);
+    // === Expanded (accordions, dropdowns) ===
+    const axExpanded = getAxProperty(properties, 'expanded');
+    const expanded = parseBooleanState(axExpanded);
+    // === Selected (tabs, options) ===
+    const axSelected = getAxProperty(properties, 'selected');
+    const selected = parseBooleanState(axSelected);
+    // === Focused ===
+    const axFocused = getAxProperty(properties, 'focused');
+    const focused = parseBooleanState(axFocused);
+    // === Required ===
+    // Check DOM required attribute or aria-required
+    let required;
+    if (hasBooleanAttribute(attributes, 'required')) {
+        required = true;
+    }
+    else if (getAriaAttribute(attributes, 'aria-required') === 'true') {
+        required = true;
+    }
+    // === Invalid ===
+    // Check AX invalid or aria-invalid
+    const axInvalid = getAxProperty(properties, 'invalid');
+    let invalid;
+    if (axInvalid !== undefined) {
+        // AX invalid can be 'true', 'false', 'grammar', 'spelling'
+        invalid =
+            axInvalid === true ||
+                axInvalid === 'true' ||
+                (typeof axInvalid === 'string' && axInvalid !== 'false');
+    }
+    else if (getAriaAttribute(attributes, 'aria-invalid') === 'true') {
+        invalid = true;
+    }
+    // === Readonly ===
+    // Check DOM readonly attribute or aria-readonly
+    let readonly;
+    if (hasBooleanAttribute(attributes, 'readonly')) {
+        readonly = true;
+    }
+    else if (getAriaAttribute(attributes, 'aria-readonly') === 'true') {
+        readonly = true;
+    }
+    // Build state object, omitting undefined values
+    const state = {
+        visible,
+        enabled,
+    };
+    if (checked !== undefined)
+        state.checked = checked;
+    if (expanded !== undefined)
+        state.expanded = expanded;
+    if (selected !== undefined)
+        state.selected = selected;
+    if (focused !== undefined)
+        state.focused = focused;
+    if (required !== undefined)
+        state.required = required;
+    if (invalid !== undefined)
+        state.invalid = invalid;
+    if (readonly !== undefined)
+        state.readonly = readonly;
+    return state;
+}
+//# sourceMappingURL=state-extractor.js.map

package/dist/src/snapshot/extractors/state-extractor.js.map

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

package/dist/src/snapshot/extractors/types.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Extractor Types
+ *
+ * Shared types for all extractors to ensure consistent data flow.
+ * These types represent the raw CDP data structures and intermediate
+ * representations used during snapshot compilation.
+ *
+ * @module snapshot/extractors/types
+ *
+ * CDP Domains:
+ * - DOM: getDocument, describeNode, requestChildNodes
+ * - Accessibility: getFullAXTree
+ * - CSS: getComputedStyleForNode
+ */
+import type { CdpClient } from '../../cdp/cdp-client.interface.js';
+import type { BBox, Viewport, ScreenZone, SnapshotOptions } from '../snapshot.types.js';
+/**
+ * Raw DOM node data from CDP DOM.getDocument / DOM.describeNode
+ */
+export interface RawDomNode {
+    /** CDP node ID (ephemeral, changes between calls) */
+    nodeId: number;
+    /** Backend node ID (stable within session) */
+    backendNodeId: number;
+    /** Node name (uppercase tag or #text, #comment, etc.) */
+    nodeName: string;
+    /** DOM node type (1=Element, 3=Text, etc.) */
+    nodeType: number;
+    /** Node attributes as key-value pairs */
+    attributes?: Record<string, string>;
+    /** Child node IDs (backendNodeIds) */
+    childNodeIds?: number[];
+    /** Shadow root type if this node hosts a shadow root */
+    shadowRootType?: 'open' | 'closed';
+    /** Frame ID if this node is an iframe content document */
+    frameId?: string;
+    /** Loader ID from the frame at extraction time.
+     * Changes on frame navigation. Used for delta computation. */
+    loaderId?: string;
+    /** Parent node's backendNodeId */
+    parentId?: number;
+    /** Text content for text nodes */
+    nodeValue?: string;
+    /**
+     * Frame path - backendNodeIds of iframe ancestors (outermost first).
+     * Used to scope selectors to the correct frame context.
+     */
+    framePath?: number[];
+    /**
+     * Shadow path - backendNodeIds of shadow host ancestors (outermost first).
+     * Used to pierce shadow boundaries when finding elements.
+     */
+    shadowPath?: number[];
+}
+/**
+ * AX property value structure from CDP
+ */
+export interface AxPropertyValue {
+    type: string;
+    value?: unknown;
+}
+/**
+ * AX property structure from CDP
+ */
+export interface AxProperty {
+    name: string;
+    value: AxPropertyValue;
+}
+/**
+ * Raw accessibility node data from CDP Accessibility.getFullAXTree
+ */
+export interface RawAxNode {
+    /** AX tree node ID */
+    nodeId: string;
+    /** Corresponding DOM backend node ID (for correlation) */
+    backendDOMNodeId?: number;
+    /** ARIA role (button, link, textbox, etc.) */
+    role?: string;
+    /** Computed accessible name */
+    name?: string;
+    /** AX properties (focusable, checked, expanded, etc.) */
+    properties?: AxProperty[];
+    /** Whether this node is ignored in the AX tree */
+    ignored?: boolean;
+    /** Child AX node IDs */
+    childIds?: string[];
+}
+/**
+ * Layout and positioning information for a node
+ */
+export interface NodeLayoutInfo {
+    /** Bounding box in viewport coordinates */
+    bbox: BBox;
+    /** CSS display value */
+    display?: string;
+    /** CSS visibility value */
+    visibility?: string;
+    /** Whether the element is visible (computed from display, visibility, size) */
+    isVisible: boolean;
+    /** Coarse screen position (above/below fold, quadrant) */
+    screenZone?: ScreenZone;
+    /** CSS z-index value (used for overlay detection) */
+    zIndex?: number;
+}
+/**
+ * Combined raw data for a single node from all extraction phases
+ */
+export interface RawNodeData {
+    /** Raw DOM node data */
+    domNode?: RawDomNode;
+    /** Raw AX node data */
+    axNode?: RawAxNode;
+    /** Layout information */
+    layout?: NodeLayoutInfo;
+    /** Backend node ID (primary key for correlation) */
+    backendNodeId: number;
+}
+/**
+ * Context passed to all extractors for accessing CDP and configuration
+ */
+export interface ExtractorContext {
+    /** CDP client for making protocol calls */
+    cdp: CdpClient;
+    /** Viewport dimensions */
+    viewport: Viewport;
+    /** Snapshot options */
+    options: Partial<SnapshotOptions>;
+}
+/**
+ * Create an extractor context.
+ *
+ * @param cdp - CDP client instance
+ * @param viewport - Viewport dimensions
+ * @param options - Snapshot capture options
+ * @returns ExtractorContext
+ */
+export declare function createExtractorContext(cdp: CdpClient, viewport: Viewport, options?: Partial<SnapshotOptions>): ExtractorContext;
+/**
+ * Result from DOM extractor
+ */
+export interface DomExtractionResult {
+    /** Map of backendNodeId -> RawDomNode */
+    nodes: Map<number, RawDomNode>;
+    /** Root document backendNodeId */
+    rootId: number;
+    /** Frame IDs found during extraction */
+    frameIds: string[];
+    /** BackendNodeIds of shadow roots */
+    shadowRoots: number[];
+}
+/**
+ * Result from AX extractor
+ */
+export interface AxExtractionResult {
+    /** Map of backendDOMNodeId -> RawAxNode */
+    nodes: Map<number, RawAxNode>;
+    /** BackendDOMNodeIds of interactive elements */
+    interactiveIds: Set<number>;
+    /** BackendDOMNodeIds of readable content elements */
+    readableIds: Set<number>;
+}
+/**
+ * Result from layout extractor
+ */
+export interface LayoutExtractionResult {
+    /** Map of backendNodeId -> NodeLayoutInfo */
+    layouts: Map<number, NodeLayoutInfo>;
+}
+/**
+ * Validate that an object is a valid RawDomNode.
+ *
+ * @param node - Object to validate
+ * @returns true if valid RawDomNode
+ */
+export declare function isValidRawDomNode(node: RawDomNode): boolean;
+/**
+ * Validate that an object is a valid RawAxNode.
+ *
+ * @param node - Object to validate
+ * @returns true if valid RawAxNode
+ */
+export declare function isValidRawAxNode(node: RawAxNode): boolean;
+/**
+ * Validate that an object is a valid NodeLayoutInfo.
+ *
+ * @param layout - Object to validate
+ * @returns true if valid NodeLayoutInfo
+ */
+export declare function isValidNodeLayoutInfo(layout: NodeLayoutInfo): boolean;
+/**
+ * DOM node types (subset relevant to extraction)
+ */
+export declare const DOM_NODE_TYPES: {
+    readonly ELEMENT_NODE: 1;
+    readonly TEXT_NODE: 3;
+    readonly COMMENT_NODE: 8;
+    readonly DOCUMENT_NODE: 9;
+    readonly DOCUMENT_TYPE_NODE: 10;
+    readonly DOCUMENT_FRAGMENT_NODE: 11;
+};
+/**
+ * AX roles that indicate interactive elements
+ */
+export declare const INTERACTIVE_AX_ROLES: Set<string>;
+/**
+ * AX roles that indicate readable content
+ */
+export declare const READABLE_AX_ROLES: Set<string>;
+/**
+ * AX roles that indicate structural/landmark elements
+ */
+export declare const STRUCTURAL_AX_ROLES: Set<string>;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/snapshot/extractors/types.d.ts.map

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