agent-web-interface 4.0.0

package/dist/src/state/diff-engine.js

@@ -0,0 +1,475 @@
+/**
+ * Diff Engine
+ *
+ * Compute incremental changes between snapshots.
+ * Returns added/removed/changed actionables and atoms.
+ */
+import { computeEid } from './element-identity.js';
+import { isInteractiveKind } from './actionables-filter.js';
+import { detectLayers } from './layer-detector.js';
+import { extractAtoms } from './atoms-extractor.js';
+// ============================================================================
+// Diff Computation
+// ============================================================================
+/**
+ * Compute diff between previous and current snapshots.
+ *
+ * Includes:
+ * - Document changes (URL, title, navigation type)
+ * - Layer changes (stack changes)
+ * - Actionables changes (added, removed, changed)
+ * - Atoms changes (viewport, scroll, loading, forms, notifications)
+ *
+ * @param prev - Previous snapshot
+ * @param curr - Current snapshot
+ * @returns Diff response
+ */
+export function computeDiff(prev, curr) {
+    // Build EID maps for interactive elements
+    const prevMap = buildEidMap(prev);
+    const currMap = buildEidMap(curr);
+    // Find added/removed actionables
+    const added = findAdded(prevMap, currMap);
+    const removed = findRemoved(prevMap, currMap);
+    // Find changed actionables
+    const changed = findChanged(prevMap, currMap);
+    // Detect document change
+    const doc = detectDocumentChange(prev, curr);
+    // Detect layer change
+    const layer = detectLayerChange(prev, curr);
+    // Compute atomic diffs
+    const atoms = computeAtomicDiffs(prev, curr);
+    // Compute mutations (status-bearing readable elements)
+    const mutations = computeMutations(prev, curr);
+    // Determine if diff is empty (no meaningful changes)
+    const isEmpty = added.length === 0 &&
+        removed.length === 0 &&
+        changed.length === 0 &&
+        mutations.textChanged.length === 0 &&
+        mutations.statusAppeared.length === 0;
+    return {
+        mode: 'diff',
+        diff: {
+            doc,
+            layer,
+            actionables: {
+                added,
+                removed,
+                changed,
+            },
+            mutations,
+            isEmpty,
+            atoms,
+        },
+    };
+}
+// ============================================================================
+// EID Map Building
+// ============================================================================
+/**
+ * Build map of EID -> node for visible interactive elements.
+ *
+ * @param snapshot - Snapshot to build map from
+ * @returns EID map
+ */
+function buildEidMap(snapshot) {
+    const map = new Map();
+    for (const node of snapshot.nodes) {
+        // Only include visible interactive elements
+        if (!isInteractiveKind(node.kind) || !node.state?.visible) {
+            continue;
+        }
+        const eid = computeEid(node);
+        map.set(eid, node);
+    }
+    return map;
+}
+// ============================================================================
+// Added/Removed Detection
+// ============================================================================
+/**
+ * Find added EIDs (present in current but not in previous).
+ *
+ * @param prevMap - Previous EID map
+ * @param currMap - Current EID map
+ * @returns Array of added EIDs
+ */
+function findAdded(prevMap, currMap) {
+    const added = [];
+    for (const eid of currMap.keys()) {
+        if (!prevMap.has(eid)) {
+            added.push(eid);
+        }
+    }
+    return added;
+}
+/**
+ * Find removed EIDs (present in previous but not in current).
+ *
+ * @param prevMap - Previous EID map
+ * @param currMap - Current EID map
+ * @returns Array of removed EIDs
+ */
+function findRemoved(prevMap, currMap) {
+    const removed = [];
+    for (const eid of prevMap.keys()) {
+        if (!currMap.has(eid)) {
+            removed.push(eid);
+        }
+    }
+    return removed;
+}
+// ============================================================================
+// Changed Detection
+// ============================================================================
+/**
+ * Find changed actionables (present in both but with different state/attributes).
+ *
+ * @param prevMap - Previous EID map
+ * @param currMap - Current EID map
+ * @returns Array of changes
+ */
+function findChanged(prevMap, currMap) {
+    const changed = [];
+    for (const [eid, currNode] of currMap) {
+        const prevNode = prevMap.get(eid);
+        if (!prevNode) {
+            continue; // Already in 'added' list
+        }
+        // Compare state and attributes
+        const diffs = compareNodes(eid, prevNode, currNode);
+        changed.push(...diffs);
+    }
+    return changed;
+}
+/**
+ * Compare two nodes and return list of property changes.
+ *
+ * @param eid - Element ID
+ * @param prev - Previous node
+ * @param curr - Current node
+ * @returns Array of changes
+ */
+function compareNodes(eid, prev, curr) {
+    const changes = [];
+    // Compare state flags
+    const stateFields = [
+        'visible',
+        'enabled',
+        'checked',
+        'selected',
+        'expanded',
+        'focused',
+        'required',
+        'invalid',
+        'readonly',
+    ];
+    for (const field of stateFields) {
+        const prevVal = prev.state?.[field];
+        const currVal = curr.state?.[field];
+        if (prevVal !== currVal) {
+            // Map to abbreviated keys
+            const abbrev = {
+                visible: 'vis',
+                enabled: 'ena',
+                checked: 'chk',
+                selected: 'sel',
+                expanded: 'exp',
+                focused: 'foc',
+                required: 'req',
+                invalid: 'inv',
+                readonly: 'rdo',
+            };
+            changes.push({
+                eid,
+                k: abbrev[field] || field,
+                from: prevVal,
+                to: currVal,
+            });
+        }
+    }
+    // Compare value attribute (for inputs)
+    if (prev.attributes?.value !== curr.attributes?.value) {
+        changes.push({
+            eid,
+            k: 'val',
+            from: prev.attributes?.value,
+            to: curr.attributes?.value,
+        });
+    }
+    // Compare label (text content)
+    if (prev.label !== curr.label) {
+        changes.push({
+            eid,
+            k: 'label',
+            from: prev.label,
+            to: curr.label,
+        });
+    }
+    return changes;
+}
+// ============================================================================
+// Document Change Detection
+// ============================================================================
+/**
+ * Detect if document changed (URL or title).
+ *
+ * @param prev - Previous snapshot
+ * @param curr - Current snapshot
+ * @returns Document change or undefined
+ */
+function detectDocumentChange(prev, curr) {
+    if (prev.url === curr.url && prev.title === curr.title) {
+        return undefined;
+    }
+    // Determine navigation type
+    const navType = determineNavType(prev.url, curr.url);
+    return {
+        from: { url: prev.url, title: prev.title },
+        to: { url: curr.url, title: curr.title },
+        nav_type: navType,
+    };
+}
+/**
+ * Determine navigation type (soft vs hard).
+ * Soft: Same pathname, different hash/search
+ * Hard: Different pathname
+ *
+ * @param prevUrl - Previous URL
+ * @param currUrl - Current URL
+ * @returns Navigation type
+ */
+function determineNavType(prevUrl, currUrl) {
+    try {
+        const prev = new URL(prevUrl);
+        const curr = new URL(currUrl);
+        // Different pathname = hard navigation
+        if (prev.pathname !== curr.pathname) {
+            return 'hard';
+        }
+        // Same pathname = soft navigation
+        return 'soft';
+    }
+    catch {
+        // URL parsing failed, assume hard navigation
+        return 'hard';
+    }
+}
+// ============================================================================
+// Layer Change Detection
+// ============================================================================
+/**
+ * Detect if layer stack changed.
+ *
+ * @param prev - Previous snapshot
+ * @param curr - Current snapshot
+ * @returns Layer change or undefined
+ */
+function detectLayerChange(prev, curr) {
+    const prevLayers = detectLayers(prev);
+    const currLayers = detectLayers(curr);
+    // Compare stacks
+    const prevStack = prevLayers.stack.map((l) => l.type);
+    const currStack = currLayers.stack.map((l) => l.type);
+    if (arraysEqual(prevStack, currStack)) {
+        return undefined;
+    }
+    return {
+        stack_from: prevStack,
+        stack_to: currStack,
+    };
+}
+/**
+ * Check if two arrays are equal.
+ */
+function arraysEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+// ============================================================================
+// Atomic Diffs
+// ============================================================================
+/**
+ * Compute atomic state diffs (viewport, scroll, loading, forms, notifications).
+ *
+ * @param prev - Previous snapshot
+ * @param curr - Current snapshot
+ * @returns Array of atom changes
+ */
+function computeAtomicDiffs(prev, curr) {
+    const prevAtoms = extractAtoms(prev);
+    const currAtoms = extractAtoms(curr);
+    const changes = [];
+    // Compare viewport
+    if (prevAtoms.viewport.w !== currAtoms.viewport.w) {
+        changes.push({ k: 'viewport.w', from: prevAtoms.viewport.w, to: currAtoms.viewport.w });
+    }
+    if (prevAtoms.viewport.h !== currAtoms.viewport.h) {
+        changes.push({ k: 'viewport.h', from: prevAtoms.viewport.h, to: currAtoms.viewport.h });
+    }
+    // Compare scroll
+    if (prevAtoms.scroll.x !== currAtoms.scroll.x) {
+        changes.push({ k: 'scroll.x', from: prevAtoms.scroll.x, to: currAtoms.scroll.x });
+    }
+    if (prevAtoms.scroll.y !== currAtoms.scroll.y) {
+        changes.push({ k: 'scroll.y', from: prevAtoms.scroll.y, to: currAtoms.scroll.y });
+    }
+    // Compare loading
+    if (prevAtoms.loading?.spinners !== currAtoms.loading?.spinners) {
+        changes.push({
+            k: 'loading.spinners',
+            from: prevAtoms.loading?.spinners,
+            to: currAtoms.loading?.spinners,
+        });
+    }
+    // Compare forms
+    if (prevAtoms.forms?.focused_field !== currAtoms.forms?.focused_field) {
+        changes.push({
+            k: 'forms.focused_field',
+            from: prevAtoms.forms?.focused_field,
+            to: currAtoms.forms?.focused_field,
+        });
+    }
+    if (prevAtoms.forms?.validation_errors !== currAtoms.forms?.validation_errors) {
+        changes.push({
+            k: 'forms.validation_errors',
+            from: prevAtoms.forms?.validation_errors,
+            to: currAtoms.forms?.validation_errors,
+        });
+    }
+    // Compare notifications
+    if (prevAtoms.notifications?.toasts !== currAtoms.notifications?.toasts) {
+        changes.push({
+            k: 'notifications.toasts',
+            from: prevAtoms.notifications?.toasts,
+            to: currAtoms.notifications?.toasts,
+        });
+    }
+    return changes;
+}
+// ============================================================================
+// Mutations Detection (Status-bearing Readable Elements)
+// ============================================================================
+/**
+ * EVALUATION FLAG: Track all readable element mutations, not just ARIA status roles.
+ *
+ * When true: Tracks ALL visible readable nodes (text, heading, paragraph, etc.)
+ * When false: Only tracks nodes with ARIA roles: status, alert, log, progressbar
+ *
+ * This flag is for evaluation to determine if broader mutation tracking is useful.
+ * Search for "TRACK_ALL_READABLE_MUTATIONS" to find this flag.
+ *
+ * TODO: Remove or make permanent after evaluation is complete.
+ */
+const TRACK_ALL_READABLE_MUTATIONS = false;
+/**
+ * Maximum character length for mutation text content.
+ * Text exceeding this limit will be truncated with "..." suffix.
+ */
+const MUTATION_TEXT_MAX_LENGTH = 100;
+/**
+ * ARIA roles that indicate state-bearing elements.
+ * Only used when TRACK_ALL_READABLE_MUTATIONS is false.
+ */
+const STATUS_ROLES = new Set(['status', 'alert', 'log', 'progressbar']);
+/**
+ * Node kinds considered "readable" for mutation tracking.
+ * Used when TRACK_ALL_READABLE_MUTATIONS is true.
+ */
+const READABLE_KINDS = new Set([
+    'text',
+    'heading',
+    'paragraph',
+    'listitem',
+    'generic', // often used for dynamic content
+]);
+/**
+ * Check if a node should be tracked for mutations.
+ *
+ * When TRACK_ALL_READABLE_MUTATIONS is true: tracks any readable node kind
+ * When false: only tracks nodes with specific ARIA roles (status, alert, log, progressbar)
+ */
+function isTrackableNode(node) {
+    if (TRACK_ALL_READABLE_MUTATIONS) {
+        // Track any readable node kind
+        return READABLE_KINDS.has(node.kind);
+    }
+    // Only track nodes with status-bearing ARIA roles
+    const role = node.attributes?.role?.toLowerCase();
+    return role !== undefined && STATUS_ROLES.has(role);
+}
+/**
+ * Truncate text to max length, adding "..." if truncated.
+ */
+function truncateText(text, maxLength = MUTATION_TEXT_MAX_LENGTH) {
+    const trimmed = text.trim();
+    if (trimmed.length <= maxLength) {
+        return trimmed;
+    }
+    return trimmed.substring(0, maxLength - 3) + '...';
+}
+/**
+ * Generate a readable element ID (rd-* prefix).
+ */
+function computeReadableEid(node) {
+    const baseEid = computeEid(node);
+    return `rd-${baseEid.substring(0, 10)}`;
+}
+/**
+ * Build a map of trackable nodes keyed by a stable identifier.
+ * Uses backend_node_id as the key since it's stable within a session.
+ */
+function buildTrackableNodeMap(snapshot) {
+    const map = new Map();
+    for (const node of snapshot.nodes) {
+        if (isTrackableNode(node) && node.state?.visible) {
+            map.set(node.backend_node_id, node);
+        }
+    }
+    return map;
+}
+/**
+ * Compute mutations in readable elements.
+ *
+ * Tracks:
+ * - Text changes in existing readable elements
+ * - New readable elements that appeared (with ARIA roles or all readable when flag is set)
+ */
+function computeMutations(prev, curr) {
+    const prevMap = buildTrackableNodeMap(prev);
+    const currMap = buildTrackableNodeMap(curr);
+    const textChanged = [];
+    const statusAppeared = [];
+    // Find text changes and new elements
+    for (const [backendNodeId, currNode] of currMap) {
+        const prevNode = prevMap.get(backendNodeId);
+        if (prevNode) {
+            // Node existed before - check for text change
+            if (prevNode.label !== currNode.label) {
+                textChanged.push({
+                    eid: computeReadableEid(currNode),
+                    from: truncateText(prevNode.label),
+                    to: truncateText(currNode.label),
+                });
+            }
+        }
+        else {
+            // New element appeared
+            const role = currNode.attributes?.role?.toLowerCase() ?? currNode.kind;
+            statusAppeared.push({
+                eid: computeReadableEid(currNode),
+                role,
+                text: truncateText(currNode.label),
+            });
+        }
+    }
+    return { textChanged, statusAppeared };
+}
+//# sourceMappingURL=diff-engine.js.map

package/dist/src/state/diff-engine.js.map

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

package/dist/src/state/element-identity.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Element Identity
+ *
+ * Generate stable, semantic element IDs (eids) that survive DOM mutations.
+ * Uses semantic hashing instead of transient CDP backend_node_id.
+ */
+import type { ReadableNode } from '../snapshot/snapshot.types.js';
+/**
+ * Compute stable semantic element ID for a node.
+ *
+ * Uses hash of semantic components:
+ * - Role (or kind)
+ * - Accessible name (normalized label)
+ * - Href (for links)
+ * - Landmark path (region + group_path)
+ * - Layer context (modal vs main - prevents collision across layers)
+ * - Position hint (heading context from group_path - scroll-stable)
+ * - Shadow path (disambiguates elements in different shadow roots)
+ *
+ * @param node - Node to compute EID for
+ * @param layer - Optional layer context for disambiguation
+ * @returns 12-character hex hash
+ */
+export declare function computeEid(node: ReadableNode, layer?: string): string;
+/**
+ * Normalize accessible name for stable hashing.
+ * - Trim whitespace
+ * - Lowercase
+ * - Collapse multiple spaces
+ * - Cap length at 100 chars
+ *
+ * @param label - Raw label text
+ * @returns Normalized label
+ */
+export declare function normalizeAccessibleName(label: string): string;
+/**
+ * Compute landmark path for a node.
+ * Format: "region/group1/group2"
+ *
+ * @param node - Node to compute path for
+ * @returns Landmark path string
+ */
+export declare function computeLandmarkPath(node: ReadableNode): string;
+/**
+ * Compute position hint for stable EID disambiguation.
+ *
+ * Uses only scroll-stable semantic context:
+ * - Nearest heading from group_path (semantic grouping)
+ *
+ * Note: Viewport-dependent data (screen_zone, bbox quadrant) was removed
+ * because it caused EID instability when scrolling. The collision resolution
+ * mechanism (resolveEidCollision) handles any increased collision rate.
+ *
+ * @param node - Node to compute hint for
+ * @returns Position hint string
+ */
+export declare function computePositionHint(node: ReadableNode): string;
+/**
+ * Hash string components to generate EID.
+ * Uses SHA-256 and returns first 12 hex chars.
+ *
+ * @param components - String components to hash
+ * @returns 12-character hex hash
+ */
+export declare function hashComponents(components: string[]): string;
+/**
+ * Resolve EID collisions by appending suffix.
+ * If EID already exists in map, append "-2", "-3", etc.
+ *
+ * @param baseEid - Base EID before collision resolution
+ * @param existingEids - Set of already-used EIDs
+ * @returns Unique EID
+ */
+export declare function resolveEidCollision(baseEid: string, existingEids: Set<string>): string;
+//# sourceMappingURL=element-identity.d.ts.map

package/dist/src/state/element-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-identity.d.ts","sourceRoot":"","sources":["../../../src/state/element-identity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAMlE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAgBrE;AAcD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAI9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAI9D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAI3D;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAWtF"}