agent-web-interface 4.0.0

package/dist/src/snapshot/extractors/types.js

@@ -0,0 +1,145 @@
+/**
+ * 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
+ */
+/**
+ * Create an extractor context.
+ *
+ * @param cdp - CDP client instance
+ * @param viewport - Viewport dimensions
+ * @param options - Snapshot capture options
+ * @returns ExtractorContext
+ */
+export function createExtractorContext(cdp, viewport, options = {}) {
+    return { cdp, viewport, options };
+}
+// ============================================================================
+// Type Validation Helpers
+// ============================================================================
+/**
+ * Validate that an object is a valid RawDomNode.
+ *
+ * @param node - Object to validate
+ * @returns true if valid RawDomNode
+ */
+export function isValidRawDomNode(node) {
+    if (!node || typeof node !== 'object') {
+        return false;
+    }
+    return (typeof node.nodeId === 'number' &&
+        typeof node.backendNodeId === 'number' &&
+        typeof node.nodeName === 'string' &&
+        typeof node.nodeType === 'number');
+}
+/**
+ * Validate that an object is a valid RawAxNode.
+ *
+ * @param node - Object to validate
+ * @returns true if valid RawAxNode
+ */
+export function isValidRawAxNode(node) {
+    if (!node || typeof node !== 'object') {
+        return false;
+    }
+    return typeof node.nodeId === 'string';
+}
+/**
+ * Validate that an object is a valid NodeLayoutInfo.
+ *
+ * @param layout - Object to validate
+ * @returns true if valid NodeLayoutInfo
+ */
+export function isValidNodeLayoutInfo(layout) {
+    if (!layout || typeof layout !== 'object') {
+        return false;
+    }
+    return (layout.bbox !== undefined &&
+        typeof layout.bbox === 'object' &&
+        typeof layout.bbox.x === 'number' &&
+        typeof layout.bbox.y === 'number' &&
+        typeof layout.bbox.w === 'number' &&
+        typeof layout.bbox.h === 'number' &&
+        typeof layout.isVisible === 'boolean');
+}
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * DOM node types (subset relevant to extraction)
+ */
+export const DOM_NODE_TYPES = {
+    ELEMENT_NODE: 1,
+    TEXT_NODE: 3,
+    COMMENT_NODE: 8,
+    DOCUMENT_NODE: 9,
+    DOCUMENT_TYPE_NODE: 10,
+    DOCUMENT_FRAGMENT_NODE: 11,
+};
+/**
+ * AX roles that indicate interactive elements
+ */
+export const INTERACTIVE_AX_ROLES = new Set([
+    'button',
+    'link',
+    'textbox',
+    'searchbox',
+    'combobox',
+    'listbox',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'option',
+    'radio',
+    'checkbox',
+    'switch',
+    'tab',
+    'slider',
+    'spinbutton',
+    'scrollbar',
+]);
+/**
+ * AX roles that indicate readable content
+ */
+export const READABLE_AX_ROLES = new Set([
+    'heading',
+    'paragraph',
+    'text',
+    'statictext',
+    'list',
+    'listitem',
+    'image',
+    'figure',
+    'table',
+    'row',
+    'cell',
+    'columnheader',
+    'rowheader',
+]);
+/**
+ * AX roles that indicate structural/landmark elements
+ */
+export const STRUCTURAL_AX_ROLES = new Set([
+    'banner',
+    'navigation',
+    'main',
+    'complementary',
+    'contentinfo',
+    'region',
+    'form',
+    'search',
+    'dialog',
+    'alertdialog',
+    'article',
+    'section',
+]);
+//# sourceMappingURL=types.js.map

package/dist/src/snapshot/extractors/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/snapshot/extractors/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgKH;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAc,EACd,QAAkB,EAClB,UAAoC,EAAE;IAEtC,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AACpC,CAAC;AA6CD,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAgB;IAChD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CACL,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ;QAC/B,OAAO,IAAI,CAAC,aAAa,KAAK,QAAQ;QACtC,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ;QACjC,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAClC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAe;IAC9C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAsB;IAC1D,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CACL,MAAM,CAAC,IAAI,KAAK,SAAS;QACzB,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;QAC/B,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,QAAQ;QACjC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,QAAQ;QACjC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,QAAQ;QACjC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,QAAQ;QACjC,OAAO,MAAM,CAAC,SAAS,KAAK,SAAS,CACtC,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,YAAY,EAAE,CAAC;IACf,SAAS,EAAE,CAAC;IACZ,YAAY,EAAE,CAAC;IACf,aAAa,EAAE,CAAC;IAChB,kBAAkB,EAAE,EAAE;IACtB,sBAAsB,EAAE,EAAE;CAClB,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC;IAC1C,QAAQ;IACR,MAAM;IACN,SAAS;IACT,WAAW;IACX,UAAU;IACV,SAAS;IACT,UAAU;IACV,kBAAkB;IAClB,eAAe;IACf,QAAQ;IACR,OAAO;IACP,UAAU;IACV,QAAQ;IACR,KAAK;IACL,QAAQ;IACR,YAAY;IACZ,WAAW;CACZ,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IACvC,SAAS;IACT,WAAW;IACX,MAAM;IACN,YAAY;IACZ,MAAM;IACN,UAAU;IACV,OAAO;IACP,QAAQ;IACR,OAAO;IACP,KAAK;IACL,MAAM;IACN,cAAc;IACd,WAAW;CACZ,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC;IACzC,QAAQ;IACR,YAAY;IACZ,MAAM;IACN,eAAe;IACf,aAAa;IACb,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,QAAQ;IACR,aAAa;IACb,SAAS;IACT,SAAS;CACV,CAAC,CAAC"}

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

@@ -0,0 +1,14 @@
+/**
+ * Snapshot Module
+ *
+ * Exports snapshot types, compiler, and storage.
+ *
+ * @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 { SnapshotStore, type SnapshotEntry, type SnapshotStoreOptions, type SnapshotStoreStats, } from './snapshot-store.js';
+export { clickByBackendNodeId, 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 * from './extractors/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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,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"}

package/dist/src/snapshot/index.js

@@ -0,0 +1,18 @@
+/**
+ * Snapshot Module
+ *
+ * Exports snapshot types, compiler, and storage.
+ *
+ * @module snapshot
+ */
+// Type guards
+export { isInteractiveNode, isReadableNode, isStructuralNode } from './snapshot.types.js';
+// Store
+export { SnapshotStore, } from './snapshot-store.js';
+// Element resolver - CDP input functions
+export { clickByBackendNodeId, 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';
+// Extractors (advanced usage)
+export * from './extractors/index.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +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,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"}

package/dist/src/snapshot/snapshot-compiler.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Snapshot Compiler
+ *
+ * Orchestrates all extractors to produce a complete BaseSnapshot.
+ *
+ * @module snapshot/snapshot-compiler
+ *
+ * CDP Domains Required:
+ * - DOM: Document structure
+ * - Accessibility: Semantic information
+ * - CSS: Computed styles (optional, for layout)
+ */
+import type { Page } from 'puppeteer-core';
+import type { CdpClient } from '../cdp/cdp-client.interface.js';
+import type { BaseSnapshot, 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;
+}
+/**
+ * SnapshotCompiler class
+ *
+ * Orchestrates the extraction and compilation of page snapshots.
+ */
+export declare class SnapshotCompiler {
+    private readonly options;
+    /** Counter for generating unique snapshot IDs */
+    private snapshotCounter;
+    constructor(options?: Partial<CompileOptions>);
+    /**
+     * Generate a unique snapshot ID.
+     */
+    private generateSnapshotId;
+    /**
+     * Compile a snapshot from the current page state.
+     *
+     * @param cdp - CDP client for the page
+     * @param page - Puppeteer Page instance
+     * @param _pageId - Page identifier (for logging/tracking)
+     * @returns Complete BaseSnapshot
+     */
+    compile(cdp: CdpClient, page: Page, _pageId: string): Promise<BaseSnapshot>;
+    /**
+     * Extract layout with error handling.
+     */
+    private extractLayoutSafe;
+    /**
+     * Transform raw node data to ReadableNode.
+     */
+    private transformNode;
+    /**
+     * Get NodeKind from HTML tag name.
+     */
+    private getKindFromTag;
+    /**
+     * 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
+     */
+    private filterNoiseNodes;
+}
+/**
+ * Export a compile function for simpler usage.
+ */
+export declare function compileSnapshot(cdp: CdpClient, page: Page, pageId: string, options?: Partial<CompileOptions>): Promise<BaseSnapshot>;
+//# sourceMappingURL=snapshot-compiler.d.ts.map

package/dist/src/snapshot/snapshot-compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-compiler.d.ts","sourceRoot":"","sources":["../../../src/snapshot/snapshot-compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,KAAK,EACV,YAAY,EAGZ,eAAe,EAMhB,MAAM,qBAAqB,CAAC;AAoT7B;;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;AAuED;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IAEnD,iDAAiD;IACjD,OAAO,CAAC,eAAe,CAAK;gBAEhB,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAI7C;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAK1B;;;;;;;OAOG;IACG,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAwPjF;;OAEG;YACW,iBAAiB;IAe/B;;OAEG;IACH,OAAO,CAAC,aAAa;IA8GrB;;OAEG;IACH,OAAO,CAAC,cAAc;IA2BtB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;CAqGzB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAChC,OAAO,CAAC,YAAY,CAAC,CAGvB"}