agent-web-interface 4.0.0

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

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

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

@@ -0,0 +1,36 @@
+/**
+ * AX Extractor
+ *
+ * Extracts accessibility tree and correlates with DOM nodes.
+ *
+ * @module snapshot/extractors/ax-extractor
+ *
+ * CDP Domains:
+ * - Accessibility.getFullAXTree: Full accessibility tree
+ * - Accessibility.getPartialAXTree: Targeted extraction (optimization)
+ */
+import type { ExtractorContext, AxExtractionResult } from './types.js';
+/**
+ * Role classification result
+ */
+export type RoleClassification = 'interactive' | 'readable' | 'structural' | 'unknown';
+/**
+ * Classify an AX role into category.
+ *
+ * @param role - AX role string
+ * @returns Role classification
+ */
+export declare function classifyAxRole(role: string | undefined): RoleClassification;
+/**
+ * Extract accessibility tree from page via CDP.
+ *
+ * Supports multi-frame extraction for pages with iframes (e.g., cookie consent
+ * dialogs, embedded widgets). When frameIds are provided, the function extracts
+ * AX trees from each frame and merges them into a single result.
+ *
+ * @param ctx - Extractor context with CDP client and options
+ * @param frameIds - Optional array of iframe frame IDs to also extract from
+ * @returns AxExtractionResult with nodes map and classification sets
+ */
+export declare function extractAx(ctx: ExtractorContext, frameIds?: string[]): Promise<AxExtractionResult>;
+//# sourceMappingURL=ax-extractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ax-extractor.d.ts","sourceRoot":"","sources":["../../../../src/snapshot/extractors/ax-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAyB,MAAM,YAAY,CAAC;AAuC9F;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,CAAC;AAEvF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,CAoB3E;AA0ED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,gBAAgB,EACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,OAAO,CAAC,kBAAkB,CAAC,CAyC7B"}

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

@@ -0,0 +1,144 @@
+/**
+ * AX Extractor
+ *
+ * Extracts accessibility tree and correlates with DOM nodes.
+ *
+ * @module snapshot/extractors/ax-extractor
+ *
+ * CDP Domains:
+ * - Accessibility.getFullAXTree: Full accessibility tree
+ * - Accessibility.getPartialAXTree: Targeted extraction (optimization)
+ */
+import { INTERACTIVE_AX_ROLES, READABLE_AX_ROLES, STRUCTURAL_AX_ROLES } from './types.js';
+/**
+ * Classify an AX role into category.
+ *
+ * @param role - AX role string
+ * @returns Role classification
+ */
+export function classifyAxRole(role) {
+    if (!role) {
+        return 'unknown';
+    }
+    const normalized = role.toLowerCase();
+    if (INTERACTIVE_AX_ROLES.has(normalized)) {
+        return 'interactive';
+    }
+    if (READABLE_AX_ROLES.has(normalized)) {
+        return 'readable';
+    }
+    if (STRUCTURAL_AX_ROLES.has(normalized)) {
+        return 'structural';
+    }
+    return 'unknown';
+}
+/**
+ * Convert CDP AX property to our internal format.
+ *
+ * @param cdpProp - CDP property structure
+ * @returns Internal AxProperty
+ */
+function convertProperty(cdpProp) {
+    return {
+        name: cdpProp.name,
+        value: {
+            type: cdpProp.value.type ?? 'unknown',
+            value: cdpProp.value.value,
+        },
+    };
+}
+/**
+ * Process CDP AX nodes and add them to result collections.
+ *
+ * @param cdpNodes - Array of CDP AX nodes
+ * @param nodes - Map to add processed nodes to
+ * @param interactiveIds - Set to add interactive node IDs to
+ * @param readableIds - Set to add readable node IDs to
+ */
+function processAxNodes(cdpNodes, nodes, interactiveIds, readableIds) {
+    for (const cdpNode of cdpNodes) {
+        // Skip ignored nodes
+        if (cdpNode.ignored) {
+            continue;
+        }
+        // Skip nodes without DOM correlation
+        if (cdpNode.backendDOMNodeId === undefined) {
+            continue;
+        }
+        const backendDOMNodeId = cdpNode.backendDOMNodeId;
+        const role = cdpNode.role?.value;
+        const name = cdpNode.name?.value;
+        // Convert properties
+        const properties = cdpNode.properties?.map(convertProperty);
+        // Create the raw AX node
+        const rawNode = {
+            nodeId: cdpNode.nodeId,
+            backendDOMNodeId,
+            role,
+            name,
+            properties,
+            ignored: cdpNode.ignored,
+            childIds: cdpNode.childIds,
+        };
+        nodes.set(backendDOMNodeId, rawNode);
+        // Classify the node
+        const classification = classifyAxRole(role);
+        if (classification === 'interactive') {
+            interactiveIds.add(backendDOMNodeId);
+        }
+        else if (classification === 'readable') {
+            readableIds.add(backendDOMNodeId);
+        }
+        // Structural nodes are tracked implicitly in the nodes map
+    }
+}
+/**
+ * Extract accessibility tree from page via CDP.
+ *
+ * Supports multi-frame extraction for pages with iframes (e.g., cookie consent
+ * dialogs, embedded widgets). When frameIds are provided, the function extracts
+ * AX trees from each frame and merges them into a single result.
+ *
+ * @param ctx - Extractor context with CDP client and options
+ * @param frameIds - Optional array of iframe frame IDs to also extract from
+ * @returns AxExtractionResult with nodes map and classification sets
+ */
+export async function extractAx(ctx, frameIds) {
+    const { cdp } = ctx;
+    const nodes = new Map();
+    const interactiveIds = new Set();
+    const readableIds = new Set();
+    // Request full accessibility tree for main frame
+    const mainResponse = await cdp.send('Accessibility.getFullAXTree', {
+        depth: -1, // Full depth
+    });
+    processAxNodes(mainResponse.nodes, nodes, interactiveIds, readableIds);
+    // Extract AX trees from additional frames (iframes)
+    if (frameIds && frameIds.length > 0) {
+        // Process frames in parallel for better performance
+        const framePromises = frameIds.map(async (frameId) => {
+            try {
+                const frameResponse = await cdp.send('Accessibility.getFullAXTree', {
+                    depth: -1,
+                    frameId, // Scope to specific frame
+                });
+                return frameResponse.nodes;
+            }
+            catch {
+                // Frame may have been removed, navigated away, or be cross-origin
+                // Silently skip failed frames - this is expected for some iframe types
+                return [];
+            }
+        });
+        const frameResults = await Promise.all(framePromises);
+        for (const frameNodes of frameResults) {
+            processAxNodes(frameNodes, nodes, interactiveIds, readableIds);
+        }
+    }
+    return {
+        nodes,
+        interactiveIds,
+        readableIds,
+    };
+}
+//# sourceMappingURL=ax-extractor.js.map

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

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

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

@@ -0,0 +1,21 @@
+/**
+ * DOM Extractor
+ *
+ * Extracts DOM tree structure via CDP, handling shadow DOM and iframes.
+ *
+ * @module snapshot/extractors/dom-extractor
+ *
+ * CDP Domains:
+ * - DOM.getDocument: Get document root with full tree
+ * - DOM.describeNode: Get details for a specific node (if needed)
+ * - DOM.requestChildNodes: Expand children (for incremental loading)
+ */
+import type { ExtractorContext, DomExtractionResult } from './types.js';
+/**
+ * Extract DOM tree from page via CDP.
+ *
+ * @param ctx - Extractor context with CDP client and options
+ * @returns DomExtractionResult with nodes map, root ID, and metadata
+ */
+export declare function extractDom(ctx: ExtractorContext): Promise<DomExtractionResult>;
+//# sourceMappingURL=dom-extractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dom-extractor.d.ts","sourceRoot":"","sources":["../../../../src/snapshot/extractors/dom-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAc,MAAM,YAAY,CAAC;AAqJpF;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA4BpF"}

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

@@ -0,0 +1,137 @@
+/**
+ * DOM Extractor
+ *
+ * Extracts DOM tree structure via CDP, handling shadow DOM and iframes.
+ *
+ * @module snapshot/extractors/dom-extractor
+ *
+ * CDP Domains:
+ * - DOM.getDocument: Get document root with full tree
+ * - DOM.describeNode: Get details for a specific node (if needed)
+ * - DOM.requestChildNodes: Expand children (for incremental loading)
+ */
+/**
+ * Parse CDP attributes array into key-value object.
+ * CDP returns attributes as flat array: [name1, value1, name2, value2, ...]
+ *
+ * @param attributes - Flat array of attribute name-value pairs
+ * @returns Record of attribute names to values
+ */
+function parseAttributes(attributes) {
+    if (!attributes || attributes.length === 0) {
+        return undefined;
+    }
+    const result = {};
+    for (let i = 0; i < attributes.length; i += 2) {
+        const name = attributes[i];
+        const value = attributes[i + 1] ?? '';
+        result[name] = value;
+    }
+    return result;
+}
+/**
+ * Recursively traverse DOM tree and extract nodes.
+ *
+ * @param cdpNode - CDP DOM node
+ * @param parentId - Parent node's backendNodeId (undefined for root)
+ * @param nodes - Map to accumulate extracted nodes
+ * @param frameIds - Set to accumulate discovered frame IDs
+ * @param shadowRoots - Array to accumulate shadow root host backendNodeIds
+ * @param ctx - Traversal context tracking frame and shadow paths
+ */
+function traverseNode(cdpNode, parentId, nodes, frameIds, shadowRoots, ctx) {
+    const backendNodeId = cdpNode.backendNodeId;
+    // Determine shadow root type if this node hosts a shadow root
+    let shadowRootType;
+    if (cdpNode.shadowRoots && cdpNode.shadowRoots.length > 0) {
+        // Get the shadow root type from the first shadow root
+        const firstShadowRoot = cdpNode.shadowRoots[0];
+        shadowRootType = firstShadowRoot.shadowRootType;
+        shadowRoots.push(backendNodeId);
+    }
+    // Track frame ID if this is an iframe
+    let frameId;
+    if (cdpNode.frameId) {
+        frameId = cdpNode.frameId;
+        frameIds.add(frameId);
+    }
+    // Collect child backendNodeIds
+    const childNodeIds = [];
+    if (cdpNode.children) {
+        for (const child of cdpNode.children) {
+            childNodeIds.push(child.backendNodeId);
+        }
+    }
+    // Create the raw DOM node with frame/shadow path information
+    const rawNode = {
+        nodeId: cdpNode.nodeId,
+        backendNodeId,
+        nodeName: cdpNode.nodeName,
+        nodeType: cdpNode.nodeType,
+        attributes: parseAttributes(cdpNode.attributes),
+        childNodeIds: childNodeIds.length > 0 ? childNodeIds : undefined,
+        shadowRootType,
+        frameId,
+        parentId,
+        nodeValue: cdpNode.nodeValue,
+        // Include frame/shadow paths if non-empty
+        framePath: ctx.framePath.length > 0 ? [...ctx.framePath] : undefined,
+        shadowPath: ctx.shadowPath.length > 0 ? [...ctx.shadowPath] : undefined,
+    };
+    nodes.set(backendNodeId, rawNode);
+    // Recursively process children (same context)
+    if (cdpNode.children) {
+        for (const child of cdpNode.children) {
+            traverseNode(child, backendNodeId, nodes, frameIds, shadowRoots, ctx);
+        }
+    }
+    // Process shadow roots (add this host to shadow path)
+    if (cdpNode.shadowRoots) {
+        const shadowCtx = {
+            framePath: ctx.framePath,
+            shadowPath: [...ctx.shadowPath, backendNodeId],
+        };
+        for (const shadowRoot of cdpNode.shadowRoots) {
+            traverseNode(shadowRoot, backendNodeId, nodes, frameIds, shadowRoots, shadowCtx);
+        }
+    }
+    // Process content document (add this iframe to frame path, reset shadow path)
+    if (cdpNode.contentDocument) {
+        const frameCtx = {
+            framePath: [...ctx.framePath, backendNodeId],
+            shadowPath: [], // Reset shadow path when entering new frame
+        };
+        traverseNode(cdpNode.contentDocument, backendNodeId, nodes, frameIds, shadowRoots, frameCtx);
+    }
+}
+/**
+ * Extract DOM tree from page via CDP.
+ *
+ * @param ctx - Extractor context with CDP client and options
+ * @returns DomExtractionResult with nodes map, root ID, and metadata
+ */
+export async function extractDom(ctx) {
+    const { cdp } = ctx;
+    // Request full DOM tree with shadow DOM piercing
+    const response = await cdp.send('DOM.getDocument', {
+        depth: -1, // Full depth
+        pierce: true, // Pierce through iframes and shadow DOM
+    });
+    const nodes = new Map();
+    const frameIds = new Set();
+    const shadowRoots = [];
+    // Initial traversal context (empty paths for root document)
+    const initialCtx = {
+        framePath: [],
+        shadowPath: [],
+    };
+    // Traverse the tree starting from root
+    traverseNode(response.root, undefined, nodes, frameIds, shadowRoots, initialCtx);
+    return {
+        nodes,
+        rootId: response.root.backendNodeId,
+        frameIds: Array.from(frameIds),
+        shadowRoots,
+    };
+}
+//# sourceMappingURL=dom-extractor.js.map

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

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

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

@@ -0,0 +1,39 @@
+/**
+ * Grouping Resolver
+ *
+ * Computes group hierarchy and heading context.
+ *
+ * @module snapshot/extractors/grouping-resolver
+ *
+ * Concepts:
+ * - group_id: Unique identifier for containing group (form, menu, card)
+ * - group_path: Breadcrumb hierarchy ["Men", "Shoes", "Running"]
+ * - heading_context: Nearest preceding heading text
+ */
+import type { RawDomNode, RawAxNode, RawNodeData } from './types.js';
+/**
+ * Grouping information for a node
+ */
+export interface GroupingInfo {
+    /** Unique identifier for containing group */
+    group_id?: string;
+    /** Hierarchy path from nested groups */
+    group_path?: string[];
+    /** Nearest preceding heading text */
+    heading_context?: string;
+}
+/**
+ * Resolve grouping information for a node.
+ *
+ * @param nodeId - Backend node ID
+ * @param domTree - Full DOM tree
+ * @param axTree - Full AX tree (backendDOMNodeId -> RawAxNode)
+ * @param allNodes - All extracted nodes for heading context
+ * @returns GroupingInfo
+ */
+export interface GroupingOptions {
+    /** Include heading context resolution (default: true) */
+    includeHeadingContext?: boolean;
+}
+export declare function resolveGrouping(nodeId: number, domTree: Map<number, RawDomNode>, axTree: Map<number, RawAxNode>, allNodes: RawNodeData[], options?: GroupingOptions): GroupingInfo;
+//# sourceMappingURL=grouping-resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grouping-resolver.d.ts","sourceRoot":"","sources":["../../../../src/snapshot/extractors/grouping-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAKrE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoOD;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAChC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAC9B,QAAQ,EAAE,WAAW,EAAE,EACvB,OAAO,CAAC,EAAE,eAAe,GACxB,YAAY,CAyDd"}

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

@@ -0,0 +1,260 @@
+/**
+ * Grouping Resolver
+ *
+ * Computes group hierarchy and heading context.
+ *
+ * @module snapshot/extractors/grouping-resolver
+ *
+ * Concepts:
+ * - group_id: Unique identifier for containing group (form, menu, card)
+ * - group_path: Breadcrumb hierarchy ["Men", "Shoes", "Running"]
+ * - heading_context: Nearest preceding heading text
+ */
+/** Maximum length for slugified names in group IDs */
+const MAX_SLUG_LENGTH = 40;
+/**
+ * DOM tags that indicate grouping elements
+ */
+const GROUPING_TAGS = new Set([
+    'FORM',
+    'FIELDSET',
+    'ARTICLE',
+    'SECTION',
+    'NAV',
+    'UL',
+    'OL',
+    'DL',
+    'TABLE',
+    'TBODY',
+    'THEAD',
+]);
+/**
+ * AX roles that indicate grouping elements
+ */
+const GROUPING_ROLES = new Set([
+    'form',
+    'group',
+    'menu',
+    'menubar',
+    'navigation',
+    'list',
+    'listbox',
+    'tree',
+    'treegrid',
+    'grid',
+    'table',
+    'tablist',
+    'radiogroup',
+    'toolbar',
+    'directory',
+]);
+/**
+ * Check if a node is a grouping container.
+ *
+ * @param domNode - DOM node
+ * @param axNode - AX node
+ * @returns true if this node is a grouping container
+ */
+function isGroupingContainer(domNode, axNode) {
+    // Check AX role
+    if (axNode?.role && GROUPING_ROLES.has(axNode.role.toLowerCase())) {
+        return true;
+    }
+    // Check DOM tag
+    if (domNode?.nodeName && GROUPING_TAGS.has(domNode.nodeName.toUpperCase())) {
+        return true;
+    }
+    // Check DOM role attribute
+    const domRole = domNode?.attributes?.role?.toLowerCase();
+    if (domRole && GROUPING_ROLES.has(domRole)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Slugify a string for use in group IDs.
+ *
+ * Converts "Shop and Learn" → "shop-and-learn"
+ * Removes special characters, normalizes whitespace.
+ *
+ * @param text - Input text
+ * @returns Slugified string
+ */
+function slugify(text) {
+    return (text
+        .toLowerCase()
+        // Replace common separators with hyphens
+        .replace(/[\s_]+/g, '-')
+        // Remove apostrophes and quotes
+        .replace(/[''"`]/g, '')
+        // Replace & with "and" word or just remove
+        .replace(/&/g, '-')
+        // Remove all non-alphanumeric except hyphens
+        .replace(/[^a-z0-9-]/g, '')
+        // Collapse multiple hyphens
+        .replace(/-+/g, '-')
+        // Trim leading/trailing hyphens
+        .replace(/^-+|-+$/g, '')
+        // Truncate to max length
+        .slice(0, MAX_SLUG_LENGTH)
+        // Remove trailing hyphen if truncated mid-word
+        .replace(/-$/, ''));
+}
+/**
+ * Generate a group ID from node information.
+ *
+ * Format: {role}-{slugified-name}
+ *
+ * @param domNode - DOM node
+ * @param axNode - AX node
+ * @param headingContext - Optional heading context as fallback name
+ * @returns Group ID string
+ */
+function generateGroupId(domNode, axNode, headingContext) {
+    const role = axNode?.role?.toLowerCase() ??
+        domNode?.attributes?.role?.toLowerCase() ??
+        domNode?.nodeName?.toLowerCase() ??
+        'group';
+    // Use name, aria-label, or id as identifier
+    const rawName = axNode?.name ?? domNode?.attributes?.['aria-label'] ?? domNode?.attributes?.id ?? '';
+    // Only use name if it's not empty after trimming
+    if (rawName?.trim()) {
+        const sluggedName = slugify(rawName);
+        if (sluggedName) {
+            return `${role}-${sluggedName}`;
+        }
+    }
+    // Fallback to heading context if available
+    if (headingContext?.trim()) {
+        const sluggedHeading = slugify(headingContext);
+        if (sluggedHeading) {
+            return `${role}-${sluggedHeading}`;
+        }
+    }
+    // Generate a simple ID from backendNodeId
+    const nodeId = axNode?.backendDOMNodeId ?? domNode?.backendNodeId;
+    if (nodeId) {
+        return `${role}-${nodeId}`;
+    }
+    return role;
+}
+/**
+ * Get group name for path building.
+ *
+ * @param domNode - DOM node
+ * @param axNode - AX node
+ * @returns Group name or undefined
+ */
+function getGroupName(domNode, axNode) {
+    return (axNode?.name ?? domNode?.attributes?.['aria-label'] ?? domNode?.attributes?.title ?? undefined);
+}
+/**
+ * Check if a node is a heading.
+ *
+ * @param domNode - DOM node
+ * @param axNode - AX node
+ * @returns true if this is a heading
+ */
+function isHeading(domNode, axNode) {
+    if (axNode?.role === 'heading')
+        return true;
+    if (domNode?.nodeName?.match(/^H[1-6]$/i))
+        return true;
+    return false;
+}
+/**
+ * Find nearest preceding heading in the node list.
+ *
+ * @param targetNodeId - Backend node ID of target element
+ * @param allNodes - All nodes in document order
+ * @param domTree - DOM tree for parent lookup
+ * @returns Heading text or undefined
+ */
+function findHeadingContext(targetNodeId, allNodes, domTree) {
+    // Find the target node's position and parent
+    const targetNode = domTree.get(targetNodeId);
+    if (!targetNode)
+        return undefined;
+    const parentId = targetNode.parentId;
+    if (parentId === undefined)
+        return undefined;
+    // Find the parent's children to check siblings
+    const parent = domTree.get(parentId);
+    if (!parent?.childNodeIds)
+        return undefined;
+    // Get index of target in parent's children
+    const targetIndex = parent.childNodeIds.indexOf(targetNodeId);
+    if (targetIndex === -1)
+        return undefined;
+    // Look at preceding siblings for headings
+    for (let i = targetIndex - 1; i >= 0; i--) {
+        const siblingId = parent.childNodeIds[i];
+        const siblingData = allNodes.find((n) => n.backendNodeId === siblingId);
+        if (siblingData && isHeading(siblingData.domNode, siblingData.axNode)) {
+            return siblingData.axNode?.name;
+        }
+    }
+    // Also check all preceding nodes in document order
+    let foundTarget = false;
+    for (let i = allNodes.length - 1; i >= 0; i--) {
+        const node = allNodes[i];
+        if (node.backendNodeId === targetNodeId) {
+            foundTarget = true;
+            continue;
+        }
+        if (foundTarget && isHeading(node.domNode, node.axNode) && node.axNode?.name) {
+            return node.axNode.name;
+        }
+    }
+    return undefined;
+}
+export function resolveGrouping(nodeId, domTree, axTree, allNodes, options) {
+    const result = {};
+    const node = domTree.get(nodeId);
+    if (!node)
+        return result;
+    // Traverse ancestors to find grouping containers
+    const groupPath = [];
+    let groupId;
+    let currentId = node.parentId;
+    const visited = new Set();
+    const maxDepth = 50;
+    let depth = 0;
+    while (currentId !== undefined && depth < maxDepth) {
+        if (visited.has(currentId))
+            break;
+        visited.add(currentId);
+        const parentDom = domTree.get(currentId);
+        const parentAx = axTree.get(currentId);
+        if (isGroupingContainer(parentDom, parentAx)) {
+            // Set group_id to the innermost group
+            // Use heading context as fallback for unnamed groups
+            if (groupId === undefined) {
+                const containerHeadingContext = findHeadingContext(currentId, allNodes, domTree);
+                groupId = generateGroupId(parentDom, parentAx, containerHeadingContext);
+            }
+            // Add to path if named
+            const groupName = getGroupName(parentDom, parentAx);
+            if (groupName) {
+                groupPath.unshift(groupName);
+            }
+        }
+        currentId = parentDom?.parentId;
+        depth++;
+    }
+    if (groupId) {
+        result.group_id = groupId;
+    }
+    if (groupPath.length > 0) {
+        result.group_path = groupPath;
+    }
+    if (options?.includeHeadingContext ?? true) {
+        // Find heading context
+        const headingContext = findHeadingContext(nodeId, allNodes, domTree);
+        if (headingContext) {
+            result.heading_context = headingContext;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=grouping-resolver.js.map