agent-web-interface 4.0.0

package/dist/src/state/locator-generator.js

@@ -0,0 +1,137 @@
+/**
+ * Locator Generator
+ *
+ * Generate stable locators for actionable elements.
+ * Preference order: AX (accessibility tree) > CSS > XPath (avoid)
+ *
+ * Locators are layer-scoped when in modal/drawer/popover layers.
+ */
+// ============================================================================
+// Layer Scope Configuration
+// ============================================================================
+/**
+ * Layer scope prefixes for Playwright locators.
+ * Used to scope locators to the active layer.
+ */
+const LAYER_SCOPES = {
+    modal: 'role=dialog[aria-modal="true"] >> ',
+    drawer: 'role=complementary >> ',
+    popover: 'role=menu >> ',
+    main: '', // No scope for main layer
+};
+/**
+ * CSS layer scope prefixes.
+ */
+const CSS_LAYER_SCOPES = {
+    modal: '[role="dialog"][aria-modal="true"] ',
+    drawer: '[role="complementary"] ',
+    popover: '[role="menu"] ',
+    main: '',
+};
+// ============================================================================
+// Locator Generation
+// ============================================================================
+/**
+ * Generate locator information for a node.
+ * Always includes preferred AX locator, optionally includes CSS fallback.
+ * Locators are scoped to the active layer when not in main.
+ *
+ * @param node - Node to generate locator for
+ * @param layer - Active layer for scoping (optional)
+ * @returns Locator information
+ */
+export function generateLocator(node, layer) {
+    const role = node.attributes?.role ?? node.kind;
+    const name = node.label.trim();
+    // Determine layer scope
+    const activeLayer = layer ?? getNodeLayer(node);
+    const axScope = LAYER_SCOPES[activeLayer] ?? '';
+    const cssScope = CSS_LAYER_SCOPES[activeLayer] ?? '';
+    // AX locator (most stable - accessibility tree)
+    const axLocator = axScope + buildAxLocator(role, name);
+    // CSS fallback (try test-id, name, aria-label)
+    const cssLocator = buildCssLocator(node, cssScope);
+    return {
+        preferred: { ax: axLocator },
+        fallback: cssLocator ? { css: cssLocator } : undefined,
+    };
+}
+/**
+ * Determine which layer a node belongs to from its region.
+ *
+ * @param node - Node to check
+ * @returns Layer name
+ */
+function getNodeLayer(node) {
+    const region = node.where.region ?? 'unknown';
+    return region === 'dialog' ? 'modal' : 'main';
+}
+// ============================================================================
+// AX Locator (Preferred)
+// ============================================================================
+/**
+ * Build accessibility tree locator.
+ * Format: "role=button[name*="Submit"]"
+ *
+ * @param role - Element role
+ * @param name - Accessible name
+ * @returns AX locator string
+ */
+function buildAxLocator(role, name) {
+    if (name === '') {
+        return `role=${role}`;
+    }
+    // Truncate name to 40 chars and escape
+    const truncatedName = name.substring(0, 40);
+    const escapedName = escapeAttr(truncatedName);
+    return `role=${role}[name*="${escapedName}"]`;
+}
+// ============================================================================
+// CSS Locator (Fallback)
+// ============================================================================
+/**
+ * Build CSS locator fallback.
+ * Try in order:
+ * 1. data-testid
+ * 2. name attribute
+ * 3. aria-label
+ * 4. (skip - no generic selector)
+ *
+ * @param node - Node to generate CSS locator for
+ * @param scope - Layer scope prefix
+ * @returns CSS locator string or undefined
+ */
+function buildCssLocator(node, scope) {
+    const attrs = node.attributes;
+    // Try test-id first (most stable)
+    const testId = attrs?.['data-testid'];
+    if (typeof testId === 'string') {
+        return `${scope}[data-testid="${escapeAttr(testId)}"]`;
+    }
+    // Try name attribute (for inputs)
+    const name = attrs?.name;
+    if (typeof name === 'string') {
+        return `${scope}[name="${escapeAttr(name)}"]`;
+    }
+    // Try aria-label
+    const ariaLabel = attrs?.['aria-label'];
+    if (typeof ariaLabel === 'string') {
+        return `${scope}[aria-label*="${escapeAttr(ariaLabel)}"]`;
+    }
+    // No suitable CSS locator found
+    return undefined;
+}
+// ============================================================================
+// Utilities
+// ============================================================================
+/**
+ * Escape attribute value for use in selectors.
+ * Escapes quotes and backslashes.
+ *
+ * @param value - Raw attribute value
+ * @returns Escaped value
+ */
+function escapeAttr(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+//# sourceMappingURL=locator-generator.js.map

package/dist/src/state/locator-generator.js.map

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

package/dist/src/state/state-manager.d.ts

@@ -0,0 +1,104 @@
+/**
+ * State Manager
+ *
+ * Central orchestrator for state tracking and response generation.
+ * Coordinates layer detection, diff computation, actionables filtering, and atoms extraction.
+ *
+ * Security: Masks sensitive values (passwords, tokens) and sanitizes URLs.
+ * Reliability: Includes concurrency protection and error recovery.
+ */
+import type { BaseSnapshot } from '../snapshot/snapshot.types.js';
+import type { StateResponse, StateManagerConfig, RenderOptions } from './types.js';
+import { ElementRegistry } from './element-registry.js';
+/**
+ * State manager for a single page.
+ * Tracks snapshots and generates state responses.
+ */
+export declare class StateManager {
+    private context;
+    private isProcessing;
+    private pendingSnapshot;
+    private elementRegistry;
+    /**
+     * Create a new state manager.
+     *
+     * @param options - Initialization options
+     */
+    constructor(options: {
+        sessionId?: string;
+        pageId: string;
+        config?: Partial<StateManagerConfig>;
+    });
+    /**
+     * Get the element registry for this page.
+     * Used by action tools to resolve eid to ElementRef.
+     */
+    getElementRegistry(): ElementRegistry;
+    /**
+     * Get the previous snapshot for this page.
+     * Used for dependency tracking to compute effects.
+     */
+    getPreviousSnapshot(): BaseSnapshot | null;
+    /**
+     * Get the active layer for the current snapshot.
+     * Returns 'main' if no snapshot is available.
+     */
+    getActiveLayer(): string;
+    /**
+     * Generate an error response.
+     *
+     * @param errorMessage - The error message to include
+     * @returns XML state response with error baseline
+     */
+    generateErrorResponse(errorMessage: string): StateResponse;
+    /**
+     * Generate state response for a new snapshot.
+     * Includes concurrency protection and error recovery.
+     *
+     * @param snapshot - Current snapshot
+     * @returns State response with StateHandle + Diff/Baseline + Actionables + Atoms
+     */
+    generateResponse(snapshot: BaseSnapshot, options?: RenderOptions): StateResponse;
+    /**
+     * Internal response generation (called with concurrency protection).
+     */
+    private doGenerateResponse;
+    /**
+     * Get baseline decision info with reason.
+     *
+     * Baselines are only sent when absolutely necessary:
+     * - first: No previous snapshot (LLM has no context)
+     * - navigation: URL changed (old elements no longer exist)
+     * - error: State corrupted, need to resync
+     *
+     * For same-page mutations (autocomplete, dropdowns, modals), we always
+     * send diffs regardless of how many elements changed. The LLM already
+     * has context from the previous response - repeating unchanged elements
+     * wastes context window tokens.
+     */
+    private getBaselineInfo;
+    /**
+     * Create error baseline response for recovery.
+     * Always uses 'error' reason - the specific error type is in the message.
+     */
+    private createErrorBaseline;
+    /**
+     * Select actionables with guaranteed focus element inclusion.
+     * Also prioritizes modal close/cancel affordances.
+     */
+    private selectActionablesWithFocusGuarantee;
+    /**
+     * Generate state handle with sanitized URL.
+     */
+    private generateStateHandle;
+    /**
+     * Format actionables with sensitive value masking.
+     * Now includes ref for direct element targeting.
+     */
+    private formatActionables;
+    /**
+     * Estimate token count for response.
+     */
+    private estimateTokens;
+}
+//# sourceMappingURL=state-manager.d.ts.map

package/dist/src/state/state-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../../../src/state/state-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EACV,aAAa,EAIb,kBAAkB,EAOlB,aAAa,EACd,MAAM,YAAY,CAAC;AAQpB,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AA0ExD;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,eAAe,CAAkB;IAEzC;;;;OAIG;gBACS,OAAO,EAAE;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;KACtC;IAaD;;;OAGG;IACH,kBAAkB,IAAI,eAAe;IAIrC;;;OAGG;IACH,mBAAmB,IAAI,YAAY,GAAG,IAAI;IAI1C;;;OAGG;IACH,cAAc,IAAI,MAAM;IAQxB;;;;;OAKG;IACH,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa;IAI1D;;;;;;OAMG;IACH,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa;IAgChF;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyG1B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,eAAe;IAgBvB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA+C3B;;;OAGG;IACH,OAAO,CAAC,mCAAmC;IAsE3C;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyC3B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAkFzB;;OAEG;IACH,OAAO,CAAC,cAAc;CAIvB"}