agent-web-interface 4.0.0

package/dist/src/snapshot/snapshot-store.js

@@ -0,0 +1,202 @@
+/**
+ * Snapshot Store
+ *
+ * In-memory storage for page snapshots with optional TTL-based cleanup.
+ * Keeps most recent snapshot per page for element resolution.
+ *
+ * @module snapshot/snapshot-store
+ */
+/**
+ * Simple in-memory store for BaseSnapshot objects.
+ * Tracks one snapshot per page (latest overwrites previous).
+ * Supports optional TTL-based expiration with automatic cleanup.
+ */
+export class SnapshotStore {
+    /** Map of snapshot_id → SnapshotEntry */
+    entries = new Map();
+    /** Map of page_id → snapshot_id (for lookup by page) */
+    pageToSnapshot = new Map();
+    /** TTL in milliseconds (undefined = no expiration) */
+    ttlMs;
+    /** Cleanup interval timer */
+    cleanupTimer;
+    constructor(options) {
+        this.ttlMs = options?.ttlMs;
+        // Start automatic cleanup if TTL is configured
+        if (this.ttlMs !== undefined) {
+            const intervalMs = options?.cleanupIntervalMs ?? this.ttlMs;
+            this.startCleanupTimer(intervalMs);
+        }
+    }
+    /**
+     * Start automatic cleanup timer.
+     * @param intervalMs - Cleanup interval in milliseconds
+     */
+    startCleanupTimer(intervalMs) {
+        this.cleanupTimer = setInterval(() => {
+            this.cleanupExpired();
+        }, intervalMs);
+        // Ensure timer doesn't prevent process exit
+        if (this.cleanupTimer.unref) {
+            this.cleanupTimer.unref();
+        }
+    }
+    /**
+     * Stop automatic cleanup timer.
+     */
+    stopCleanupTimer() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+    }
+    /**
+     * Store a snapshot for a page.
+     * Overwrites any previous snapshot for the same page.
+     *
+     * @param pageId - Page identifier
+     * @param snapshot - Snapshot to store
+     */
+    store(pageId, snapshot) {
+        // Remove previous snapshot for this page if exists
+        const previousSnapshotId = this.pageToSnapshot.get(pageId);
+        if (previousSnapshotId) {
+            this.entries.delete(previousSnapshotId);
+        }
+        // Store new snapshot with metadata
+        const entry = {
+            snapshot,
+            storedAt: Date.now(),
+            pageId,
+        };
+        this.entries.set(snapshot.snapshot_id, entry);
+        this.pageToSnapshot.set(pageId, snapshot.snapshot_id);
+    }
+    /**
+     * Get a snapshot by its ID.
+     *
+     * @param snapshotId - Snapshot identifier
+     * @returns Snapshot or undefined if not found
+     */
+    get(snapshotId) {
+        const entry = this.entries.get(snapshotId);
+        return entry?.snapshot;
+    }
+    /**
+     * Get full entry (with metadata) by snapshot ID.
+     *
+     * @param snapshotId - Snapshot identifier
+     * @returns SnapshotEntry or undefined if not found
+     */
+    getEntry(snapshotId) {
+        return this.entries.get(snapshotId);
+    }
+    /**
+     * Get the most recent snapshot for a page.
+     *
+     * @param pageId - Page identifier
+     * @returns Snapshot or undefined if no snapshot for page
+     */
+    getByPageId(pageId) {
+        const snapshotId = this.pageToSnapshot.get(pageId);
+        return snapshotId ? this.get(snapshotId) : undefined;
+    }
+    /**
+     * Find a node within a snapshot.
+     *
+     * @param snapshotId - Snapshot identifier
+     * @param nodeId - Node identifier
+     * @returns Node or undefined if not found
+     */
+    findNode(snapshotId, nodeId) {
+        const snapshot = this.get(snapshotId);
+        return snapshot?.nodes.find((n) => n.node_id === nodeId);
+    }
+    /**
+     * Remove snapshot for a specific page.
+     *
+     * @param pageId - Page identifier
+     * @returns true if snapshot was removed, false if not found
+     */
+    removeByPageId(pageId) {
+        const snapshotId = this.pageToSnapshot.get(pageId);
+        if (!snapshotId) {
+            return false;
+        }
+        this.entries.delete(snapshotId);
+        this.pageToSnapshot.delete(pageId);
+        return true;
+    }
+    /**
+     * Clear all stored snapshots.
+     */
+    clear() {
+        this.entries.clear();
+        this.pageToSnapshot.clear();
+    }
+    /**
+     * Destroy the store, clearing all data and stopping cleanup timer.
+     */
+    destroy() {
+        this.stopCleanupTimer();
+        this.clear();
+    }
+    /**
+     * Cleanup expired snapshots based on TTL.
+     * Does nothing if TTL is not configured.
+     *
+     * @returns Number of expired snapshots removed
+     */
+    cleanupExpired() {
+        if (this.ttlMs === undefined) {
+            return 0;
+        }
+        const now = Date.now();
+        const expiredIds = [];
+        for (const [snapshotId, entry] of this.entries) {
+            if (now - entry.storedAt > this.ttlMs) {
+                expiredIds.push(snapshotId);
+            }
+        }
+        for (const snapshotId of expiredIds) {
+            const entry = this.entries.get(snapshotId);
+            if (entry) {
+                this.pageToSnapshot.delete(entry.pageId);
+                this.entries.delete(snapshotId);
+            }
+        }
+        return expiredIds.length;
+    }
+    /**
+     * Get store statistics.
+     *
+     * @returns SnapshotStoreStats
+     */
+    getStats() {
+        let totalNodes = 0;
+        let oldestSnapshot;
+        let newestSnapshot;
+        for (const entry of this.entries.values()) {
+            totalNodes += entry.snapshot.nodes.length;
+            if (oldestSnapshot === undefined || entry.storedAt < oldestSnapshot) {
+                oldestSnapshot = entry.storedAt;
+            }
+            if (newestSnapshot === undefined || entry.storedAt > newestSnapshot) {
+                newestSnapshot = entry.storedAt;
+            }
+        }
+        return {
+            snapshotCount: this.entries.size,
+            totalNodes,
+            oldestSnapshot,
+            newestSnapshot,
+        };
+    }
+    /**
+     * Get count of stored snapshots.
+     */
+    get size() {
+        return this.entries.size;
+    }
+}
+//# sourceMappingURL=snapshot-store.js.map

package/dist/src/snapshot/snapshot-store.js.map

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

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

@@ -0,0 +1,250 @@
+/**
+ * BaseSnapshot Types
+ *
+ * Canonical semantic representation of a web page.
+ * Designed to be:
+ * - Compact: No raw HTML, no class soup
+ * - Semantic: Preserves meaning, order, hierarchy
+ * - Actionable: Interactive elements have stable locators
+ * - Token-efficient: Suitable for LLM context
+ */
+import { BBox } from '../shared/types/base.types.js';
+import type { ObservationGroups } from '../observation/observation.types.js';
+export type { BBox };
+export type BoundingBox = BBox;
+/**
+ * Canonical snapshot of a web page.
+ * Single source of truth for page state at a point in time.
+ */
+export interface BaseSnapshot {
+    /** Unique identifier for this snapshot */
+    snapshot_id: string;
+    /** Page URL at capture time */
+    url: string;
+    /** Page title */
+    title: string;
+    /** Document language (from <html lang="...">) */
+    language?: string;
+    /** ISO 8601 timestamp of capture */
+    captured_at: string;
+    /** Viewport dimensions at capture time */
+    viewport: Viewport;
+    /** Ordered list of semantic nodes (preserves visual/DOM order) */
+    nodes: ReadableNode[];
+    /** Metadata about the snapshot */
+    meta: SnapshotMeta;
+    /**
+     * DOM observations - significant elements that appeared or disappeared.
+     * Split by when they occurred for clarity.
+     */
+    observations?: ObservationGroups;
+}
+/**
+ * Viewport dimensions
+ */
+export interface Viewport {
+    width: number;
+    height: number;
+}
+/**
+ * Snapshot metadata
+ */
+export interface SnapshotMeta {
+    /** True if snapshot is incomplete (e.g., timeout, cross-origin frames) */
+    partial?: boolean;
+    /** Warnings encountered during capture */
+    warnings?: string[];
+    /** Total node count in snapshot */
+    node_count: number;
+    /** Count of interactive nodes */
+    interactive_count: number;
+    /** Capture duration in milliseconds */
+    capture_duration_ms?: number;
+}
+/**
+ * Semantic node representation.
+ * Captures essential information for both reading and interaction.
+ */
+export interface ReadableNode {
+    /** Unique identifier within snapshot (e.g., "n1", "n2") */
+    node_id: string;
+    /** CDP backend node ID - stable within session, guaranteed unique per DOM element.
+     * Used for direct CDP interactions to avoid Playwright locator ambiguity. */
+    backend_node_id: number;
+    /** CDP frame ID containing this node.
+     * Used with loader_id to create globally unique element references. */
+    frame_id: string;
+    /** CDP loader ID at snapshot time - changes on frame navigation.
+     * Combined with frame_id and backend_node_id for safe cross-frame references. */
+    loader_id: string;
+    /** Semantic classification */
+    kind: NodeKind;
+    /** Human-readable label (accessible name, text content, placeholder, etc.) */
+    label: string;
+    /** Semantic location within page */
+    where: NodeLocation;
+    /** Layout/positioning information */
+    layout: NodeLayout;
+    /** State for interactive elements */
+    state?: NodeState;
+    /** Locator strategies for finding/acting on this element */
+    find?: NodeLocators;
+    /** Additional attributes for specific node types */
+    attributes?: NodeAttributes;
+}
+/**
+ * Semantic node classification.
+ * Covers interactive elements and readable content.
+ */
+export type NodeKind = 'link' | 'button' | 'input' | 'textarea' | 'select' | 'combobox' | 'checkbox' | 'radio' | 'switch' | 'slider' | 'tab' | 'menuitem' | 'heading' | 'paragraph' | 'text' | 'list' | 'listitem' | 'image' | 'media' | 'table' | 'form' | 'dialog' | 'navigation' | 'section' | 'generic';
+/**
+ * Semantic region classification.
+ * Based on ARIA landmarks and common page structure.
+ */
+export type SemanticRegion = 'header' | 'nav' | 'main' | 'aside' | 'footer' | 'dialog' | 'search' | 'form' | 'contentinfo' | 'unknown';
+/**
+ * Semantic location within the page.
+ */
+export interface NodeLocation {
+    /** Page region (header, nav, main, footer, etc.) */
+    region: SemanticRegion;
+    /** Group identifier (section/menu/card/form cluster) */
+    group_id?: string;
+    /** Hierarchy path for nested elements (e.g., ["Men", "Shoes", "Running"]) */
+    group_path?: string[];
+    /** Nearest heading context */
+    heading_context?: string;
+}
+/**
+ * Layout and positioning information.
+ */
+export interface NodeLayout {
+    /** Bounding box in viewport coordinates */
+    bbox: BoundingBox;
+    /** CSS display value */
+    display?: string;
+    /** CSS position value */
+    positioning?: string;
+    /** Container flow direction (row/column for flex, etc.) */
+    flow?: 'row' | 'column' | 'grid' | 'block' | 'inline';
+    /** Coarse screen position */
+    screen_zone?: ScreenZone;
+    /** CSS z-index value (used for overlay detection) */
+    zIndex?: number;
+}
+/**
+ * Coarse screen zone (for spatial reasoning).
+ */
+export type ScreenZone = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'above-fold' | 'below-fold';
+/**
+ * State for interactive elements.
+ */
+export interface NodeState {
+    /** Element is visible (not hidden, not zero-size) */
+    visible: boolean;
+    /** Element is enabled (not disabled, not aria-disabled) */
+    enabled: boolean;
+    /** Checked state for checkboxes/radios/switches */
+    checked?: boolean;
+    /** Expanded state for accordions/dropdowns */
+    expanded?: boolean;
+    /** Selected state for tabs/options */
+    selected?: boolean;
+    /** Focused state */
+    focused?: boolean;
+    /** Required for form inputs */
+    required?: boolean;
+    /** Invalid state for form inputs */
+    invalid?: boolean;
+    /** Read-only state */
+    readonly?: boolean;
+}
+/**
+ * Locator strategies for element identification.
+ * Ordered by reliability/stability.
+ */
+export interface NodeLocators {
+    /** Primary (most reliable) locator */
+    primary: string;
+    /** Alternative locators (fallbacks) */
+    alternates?: string[];
+    /** Frame path if element is in iframe */
+    frame_path?: string[];
+    /** Shadow DOM path if element is in shadow root */
+    shadow_path?: string[];
+}
+/**
+ * Additional attributes for specific node types.
+ */
+export interface NodeAttributes {
+    /** Input type (text, email, password, etc.) */
+    input_type?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Current value (redacted by default for sensitive fields) */
+    value?: string;
+    /** Link href */
+    href?: string;
+    /** Image alt text */
+    alt?: string;
+    /** Image src (domain + path only, no query params) */
+    src?: string;
+    /** Heading level (1-6) */
+    heading_level?: number;
+    /** Form action URL */
+    action?: string;
+    /** Form method */
+    method?: string;
+    /** Autocomplete attribute */
+    autocomplete?: string;
+    /** ARIA role (if different from implied role) */
+    role?: string;
+    /** Data-testid or similar test identifier */
+    test_id?: string;
+}
+/**
+ * Snapshot capture options.
+ */
+export interface SnapshotOptions {
+    /** Include hidden elements (default: false) */
+    include_hidden?: boolean;
+    /** Maximum nodes to capture (default: unlimited) */
+    max_nodes?: number;
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Redact sensitive values like passwords (default: true) */
+    redact_sensitive?: boolean;
+    /** Include value attribute for inputs (default: false for security) */
+    include_values?: boolean;
+}
+/**
+ * Snapshot capture result returned by MCP tool.
+ */
+export interface SnapshotResult {
+    /** Snapshot identifier */
+    snapshot_id: string;
+    /** Page URL */
+    url: string;
+    /** Page title */
+    title: string;
+    /** Capture statistics */
+    stats: {
+        node_count: number;
+        interactive_count: number;
+        captured_at: string;
+        duration_ms: number;
+    };
+}
+/**
+ * Type guard for interactive nodes.
+ */
+export declare function isInteractiveNode(node: ReadableNode): boolean;
+/**
+ * Type guard for readable content nodes.
+ */
+export declare function isReadableNode(node: ReadableNode): boolean;
+/**
+ * Type guard for structural nodes.
+ */
+export declare function isStructuralNode(node: ReadableNode): boolean;
+//# sourceMappingURL=snapshot.types.d.ts.map

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * BaseSnapshot Types
+ *
+ * Canonical semantic representation of a web page.
+ * Designed to be:
+ * - Compact: No raw HTML, no class soup
+ * - Semantic: Preserves meaning, order, hierarchy
+ * - Actionable: Interactive elements have stable locators
+ * - Token-efficient: Suitable for LLM context
+ */
+/**
+ * Type guard for interactive nodes.
+ */
+export function isInteractiveNode(node) {
+    const interactiveKinds = [
+        'link',
+        'button',
+        'input',
+        'textarea',
+        'select',
+        'combobox',
+        'checkbox',
+        'radio',
+        'switch',
+        'slider',
+        'tab',
+        'menuitem',
+    ];
+    return interactiveKinds.includes(node.kind);
+}
+/**
+ * Type guard for readable content nodes.
+ */
+export function isReadableNode(node) {
+    const readableKinds = [
+        'heading',
+        'paragraph',
+        'text',
+        'list',
+        'listitem',
+        'image',
+        'media',
+        'table',
+    ];
+    return readableKinds.includes(node.kind);
+}
+/**
+ * Type guard for structural nodes.
+ */
+export function isStructuralNode(node) {
+    const structuralKinds = ['form', 'dialog', 'navigation', 'section'];
+    return structuralKinds.includes(node.kind);
+}
+//# sourceMappingURL=snapshot.types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.types.js","sourceRoot":"","sources":["../../../src/snapshot/snapshot.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA+WH;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAkB;IAClD,MAAM,gBAAgB,GAAe;QACnC,MAAM;QACN,QAAQ;QACR,OAAO;QACP,UAAU;QACV,QAAQ;QACR,UAAU;QACV,UAAU;QACV,OAAO;QACP,QAAQ;QACR,QAAQ;QACR,KAAK;QACL,UAAU;KACX,CAAC;IACF,OAAO,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAkB;IAC/C,MAAM,aAAa,GAAe;QAChC,SAAS;QACT,WAAW;QACX,MAAM;QACN,MAAM;QACN,UAAU;QACV,OAAO;QACP,OAAO;QACP,OAAO;KACR,CAAC;IACF,OAAO,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAkB;IACjD,MAAM,eAAe,GAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;IAChF,OAAO,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC"}

package/dist/src/state/actionables-filter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Actionables Filter
+ *
+ * Select and rank interactive elements for LLM context.
+ * Filter to active layer, score by relevance, cap at max count.
+ */
+import type { BaseSnapshot, ReadableNode, NodeKind } from '../snapshot/snapshot.types.js';
+import type { ScoringContext } from './types.js';
+/**
+ * Check if node kind is interactive.
+ */
+export declare function isInteractiveKind(kind: NodeKind): boolean;
+/**
+ * Select actionable elements from snapshot.
+ *
+ * Filtering rules:
+ * 1. Only interactive elements
+ * 2. Only visible elements
+ * 3. Only from active layer
+ * 4. Score by relevance
+ * 5. Cap at maxCount
+ *
+ * @param snapshot - Compiled snapshot
+ * @param activeLayer - Active layer name
+ * @param maxCount - Maximum number of actionables to return
+ * @param context - Scoring context (optional)
+ * @returns Selected nodes sorted by relevance
+ */
+export declare function selectActionables(snapshot: BaseSnapshot, activeLayer: string, maxCount: number, context?: ScoringContext): ReadableNode[];
+/**
+ * Score an actionable element by relevance.
+ *
+ * Scoring factors:
+ * - Enabled state (+0.2)
+ * - Role importance (button/input: +0.3, link: +0.25, etc.)
+ * - Semantic region (main: +0.15, dialog: +0.2)
+ * - Screen position (above-fold: +0.1)
+ * - Has label (+0.15)
+ * - Primary CTA (+0.3)
+ * - Currently focused (+0.2)
+ *
+ * @param node - Node to score
+ * @param context - Scoring context
+ * @returns Score from 0-1
+ */
+export declare function scoreActionable(node: ReadableNode, context?: ScoringContext): number;
+//# sourceMappingURL=actionables-filter.d.ts.map

package/dist/src/state/actionables-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionables-filter.d.ts","sourceRoot":"","sources":["../../../src/state/actionables-filter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAkBjD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEzD;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,EACtB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,YAAY,EAAE,CAiChB;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CA4DpF"}