agent-web-interface 4.0.0

package/dist/src/state/actionables-filter.js

@@ -0,0 +1,173 @@
+/**
+ * Actionables Filter
+ *
+ * Select and rank interactive elements for LLM context.
+ * Filter to active layer, score by relevance, cap at max count.
+ */
+// Interactive element kinds
+const INTERACTIVE_KINDS = [
+    'link',
+    'button',
+    'input',
+    'textarea',
+    'select',
+    'combobox',
+    'checkbox',
+    'radio',
+    'switch',
+    'slider',
+    'tab',
+    'menuitem',
+];
+/**
+ * Check if node kind is interactive.
+ */
+export function isInteractiveKind(kind) {
+    return INTERACTIVE_KINDS.includes(kind);
+}
+// ============================================================================
+// Actionables Selection
+// ============================================================================
+/**
+ * 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 function selectActionables(snapshot, activeLayer, maxCount, context) {
+    // Filter to candidates
+    const candidates = snapshot.nodes.filter((node) => {
+        // Must be interactive
+        if (!isInteractiveKind(node.kind)) {
+            return false;
+        }
+        // Must be visible
+        if (!node.state?.visible) {
+            return false;
+        }
+        // Must be in active layer
+        const nodeLayer = getNodeLayer(node);
+        if (nodeLayer !== activeLayer) {
+            return false;
+        }
+        return true;
+    });
+    // Score each candidate
+    const scored = candidates.map((node) => ({
+        node,
+        score: scoreActionable(node, context),
+    }));
+    // Sort by score (highest first)
+    scored.sort((a, b) => b.score - a.score);
+    // Cap at maxCount
+    return scored.slice(0, maxCount).map((s) => s.node);
+}
+// ============================================================================
+// Scoring Algorithm
+// ============================================================================
+/**
+ * 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 function scoreActionable(node, context) {
+    let score = 0.5; // Base score
+    // Visibility required (already filtered, but double-check)
+    if (!node.state?.visible) {
+        return 0;
+    }
+    // Enabled state
+    if (node.state?.enabled) {
+        score += 0.2;
+    }
+    // Role importance
+    const roleWeight = {
+        button: 0.3,
+        link: 0.25,
+        input: 0.3,
+        textarea: 0.25,
+        select: 0.25,
+        checkbox: 0.2,
+        radio: 0.2,
+        switch: 0.2,
+        combobox: 0.25,
+        slider: 0.15,
+        tab: 0.2,
+        menuitem: 0.2,
+    };
+    score += roleWeight[node.kind] ?? 0.1;
+    // Semantic region (main/dialog favored)
+    const region = node.where.region ?? 'unknown';
+    if (region === 'main') {
+        score += 0.15;
+    }
+    else if (region === 'dialog') {
+        score += 0.2;
+    }
+    // Above fold (from layout.screen_zone)
+    if (node.layout.screen_zone?.includes('above-fold')) {
+        score += 0.1;
+    }
+    // Has label (actionable without label is suspect)
+    if (node.label.trim().length > 0) {
+        score += 0.15;
+    }
+    // Primary CTA (from FactPack if available)
+    if (context?.primaryCTA?.node_id === node.node_id) {
+        score += 0.3;
+    }
+    // Currently focused
+    if (node.state?.focused) {
+        score += 0.2;
+    }
+    // Cap at 1.0
+    return Math.min(score, 1.0);
+}
+// ============================================================================
+// Layer Determination
+// ============================================================================
+/**
+ * Determine which layer a node belongs to.
+ * Simplified: use region as proxy.
+ *
+ * Modal elements are in 'dialog' region.
+ * Everything else is in 'main'.
+ *
+ * TODO: Make this more sophisticated by checking node ancestry
+ * and matching against detected layer root EIDs.
+ *
+ * @param node - Node to check
+ * @returns Layer name
+ */
+function getNodeLayer(node) {
+    const region = node.where.region ?? 'unknown';
+    // Dialog region maps to modal layer
+    if (region === 'dialog') {
+        return 'modal';
+    }
+    // Everything else maps to main layer
+    // TODO: Add drawer and popover detection based on ancestry
+    return 'main';
+}
+//# sourceMappingURL=actionables-filter.js.map

package/dist/src/state/actionables-filter.js.map

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

package/dist/src/state/atoms-extractor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Atoms Extractor
+ *
+ * Extract universal UI state atoms from snapshot.
+ * Domain-agnostic - works on any website.
+ */
+import type { BaseSnapshot } from '../snapshot/snapshot.types.js';
+import type { Atoms } from './types.js';
+/**
+ * Extract universal UI state atoms from snapshot.
+ *
+ * Includes:
+ * - Viewport dimensions (always)
+ * - Scroll position (always)
+ * - Loading indicators (optional)
+ * - Form state (optional)
+ * - Notifications (optional)
+ *
+ * @param snapshot - Compiled snapshot
+ * @returns Atoms object
+ */
+export declare function extractAtoms(snapshot: BaseSnapshot): Atoms;
+//# sourceMappingURL=atoms-extractor.d.ts.map

package/dist/src/state/atoms-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atoms-extractor.d.ts","sourceRoot":"","sources":["../../../src/state/atoms-extractor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,+BAA+B,CAAC;AAC5E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AA8BxC;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,KAAK,CAgC1D"}

package/dist/src/state/atoms-extractor.js

@@ -0,0 +1,160 @@
+/**
+ * Atoms Extractor
+ *
+ * Extract universal UI state atoms from snapshot.
+ * Domain-agnostic - works on any website.
+ */
+import { computeEid } from './element-identity.js';
+// Interactive element kinds (for filtering)
+const INTERACTIVE_KINDS = [
+    'link',
+    'button',
+    'input',
+    'textarea',
+    'select',
+    'combobox',
+    'checkbox',
+    'radio',
+    'switch',
+    'slider',
+    'tab',
+    'menuitem',
+];
+/**
+ * Check if node kind is interactive.
+ */
+function isInteractiveKind(kind) {
+    return INTERACTIVE_KINDS.includes(kind);
+}
+// ============================================================================
+// Atoms Extraction
+// ============================================================================
+/**
+ * Extract universal UI state atoms from snapshot.
+ *
+ * Includes:
+ * - Viewport dimensions (always)
+ * - Scroll position (always)
+ * - Loading indicators (optional)
+ * - Form state (optional)
+ * - Notifications (optional)
+ *
+ * @param snapshot - Compiled snapshot
+ * @returns Atoms object
+ */
+export function extractAtoms(snapshot) {
+    const atoms = {
+        viewport: {
+            w: snapshot.viewport.width,
+            h: snapshot.viewport.height,
+            dpr: 1.0, // TODO: get from CDP or page context
+        },
+        scroll: {
+            x: 0, // TODO: extract from page.evaluate(() => window.scrollX)
+            y: 0, // TODO: extract from page.evaluate(() => window.scrollY)
+        },
+    };
+    // Extract loading indicators
+    const loading = extractLoading(snapshot);
+    if (loading) {
+        atoms.loading = loading;
+    }
+    // Extract form state
+    const forms = extractForms(snapshot);
+    if (forms) {
+        atoms.forms = forms;
+    }
+    // Extract notifications
+    const notifications = extractNotifications(snapshot);
+    if (notifications) {
+        atoms.notifications = notifications;
+    }
+    return atoms;
+}
+// ============================================================================
+// Loading Indicators
+// ============================================================================
+/**
+ * Extract loading indicators from snapshot.
+ *
+ * @param snapshot - Compiled snapshot
+ * @returns Loading state or undefined
+ */
+function extractLoading(snapshot) {
+    // Count spinner elements
+    const spinners = snapshot.nodes.filter((n) => {
+        if (n.attributes?.role === 'progressbar')
+            return true;
+        // Safely check aria-busy using index access
+        const attrs = n.attributes;
+        return attrs?.['aria-busy'] === 'true';
+    }).length;
+    if (spinners > 0) {
+        return {
+            network_busy: false, // TODO: track from CDP Network domain
+            spinners,
+            progress: undefined, // TODO: extract from progressbar value
+        };
+    }
+    return undefined;
+}
+// ============================================================================
+// Form State
+// ============================================================================
+/**
+ * Extract form state from snapshot.
+ *
+ * @param snapshot - Compiled snapshot
+ * @returns Form state or undefined
+ */
+function extractForms(snapshot) {
+    // Check if any forms exist
+    const hasForms = snapshot.nodes.some((n) => n.kind === 'form');
+    if (!hasForms) {
+        return undefined;
+    }
+    // Find focused input
+    const focusedInput = snapshot.nodes.find((n) => isInteractiveKind(n.kind) && n.state?.focused);
+    // Count validation errors
+    const validationErrors = snapshot.nodes.filter((n) => isInteractiveKind(n.kind) && n.state?.invalid).length;
+    // Only return forms object if there's meaningful state
+    if (focusedInput || validationErrors > 0) {
+        return {
+            dirty: false, // TODO: track value changes across snapshots
+            focused_field: focusedInput ? computeEid(focusedInput) : undefined,
+            validation_errors: validationErrors,
+        };
+    }
+    return undefined;
+}
+// ============================================================================
+// Notifications
+// ============================================================================
+/**
+ * Maximum notifications to report (prevent bloat).
+ */
+const MAX_TOASTS = 5;
+const MAX_BANNERS = 3;
+/**
+ * Extract notifications from snapshot.
+ * Capped to prevent response bloat.
+ *
+ * @param snapshot - Compiled snapshot
+ * @returns Notifications state or undefined
+ */
+function extractNotifications(snapshot) {
+    // Count toasts (alerts, status messages) - capped
+    const toastNodes = snapshot.nodes.filter((n) => n.attributes?.role === 'alert' || n.attributes?.role === 'status');
+    const toasts = Math.min(toastNodes.length, MAX_TOASTS);
+    // Count banners (non-header banners) - capped
+    const bannerNodes = snapshot.nodes.filter((n) => n.attributes?.role === 'banner' && n.where.region !== 'header');
+    const banners = Math.min(bannerNodes.length, MAX_BANNERS);
+    if (toasts > 0 || banners > 0) {
+        return {
+            toasts,
+            banners,
+        };
+    }
+    return undefined;
+}
+//# sourceMappingURL=atoms-extractor.js.map

package/dist/src/state/atoms-extractor.js.map

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

package/dist/src/state/constants.d.ts

@@ -0,0 +1,125 @@
+/**
+ * State System Constants
+ *
+ * Centralized configuration for magic numbers used across the state system.
+ * Each constant includes rationale for its value.
+ */
+/**
+ * Viewport thresholds for quadrant computation.
+ * Used to compute coarse position hints for element disambiguation.
+ */
+export declare const VIEWPORT: {
+    /**
+     * Horizontal midpoint for quadrant detection.
+     * Assumes common viewport width ~1000px (iPad, small desktop).
+     * Elements left of this are 'L', right are 'R'.
+     */
+    readonly MIDPOINT_X: 500;
+    /**
+     * Vertical midpoint for quadrant detection.
+     * Assumes common viewport height ~800px or fold line at 50%.
+     * Elements above this are 'T', below are 'B'.
+     */
+    readonly MIDPOINT_Y: 400;
+};
+/**
+ * Accessible name normalization limits.
+ */
+export declare const ACCESSIBLE_NAME: {
+    /**
+     * Maximum length for normalized accessible names.
+     * Truncated to prevent excessively long EID inputs.
+     */
+    readonly MAX_LENGTH: 100;
+};
+/**
+ * Layer detection confidence thresholds.
+ */
+export declare const LAYER_CONFIDENCE: {
+    /**
+     * Minimum confidence score to include layer in stack.
+     * Candidates below this are filtered out.
+     * Value chosen empirically: modal detection is high confidence (0.95+),
+     * while class-based detection is lower (0.65-0.75).
+     * 0.6 threshold excludes weak class matches while keeping strong patterns.
+     */
+    readonly MIN_THRESHOLD: 0.6;
+};
+/**
+ * Z-index thresholds for layer type detection.
+ * Modern UI libraries typically use z-index ranges:
+ * - Base content: 0-50
+ * - Fixed headers/footers: 50-100
+ * - Drawers/sidebars: 100-500
+ * - Modals: 500-1000+
+ * - Tooltips/popovers: 100-500
+ */
+export declare const Z_INDEX: {
+    /**
+     * Z-index threshold for high-confidence modal detection.
+     * Dialogs with z-index > 1000 are almost certainly modals.
+     */
+    readonly MODAL_HIGH: 1000;
+    /**
+     * Minimum z-index for portal container detection.
+     * React/Vue portals typically render at z-index >= 100.
+     */
+    readonly PORTAL_MIN: 100;
+    /**
+     * Z-index threshold for portal area coverage check.
+     * Large elements at this z-index likely cover significant viewport.
+     */
+    readonly PORTAL_HIGH: 500;
+    /**
+     * Minimum z-index for drawer overlay detection.
+     * Below this, element is likely inline nav, not overlay drawer.
+     */
+    readonly DRAWER_MIN: 50;
+    /**
+     * Z-index threshold for confident drawer detection.
+     * Drawers with z-index > 100 are likely overlay panels.
+     */
+    readonly DRAWER_HIGH: 100;
+    /**
+     * Minimum z-index for popover detection.
+     * Standard popovers (menus, tooltips) render above this.
+     */
+    readonly POPOVER_MIN: 100;
+};
+/**
+ * Size thresholds for element detection.
+ */
+export declare const ELEMENT_SIZE: {
+    /**
+     * Minimum width for portal container detection.
+     * Portals typically have meaningful content size.
+     */
+    readonly PORTAL_MIN_WIDTH: 200;
+    /**
+     * Minimum height for portal container detection.
+     */
+    readonly PORTAL_MIN_HEIGHT: 200;
+};
+/**
+ * Edge position detection thresholds.
+ * Used to identify drawers positioned at viewport edges.
+ */
+export declare const EDGE_DETECTION: {
+    /**
+     * Maximum x-coordinate for left edge detection.
+     * Elements with x < 10 are considered left-edge positioned.
+     */
+    readonly LEFT_MAX_X: 10;
+    /**
+     * Minimum right edge position.
+     * rightEdge (x + width) must exceed this to be right-edge positioned.
+     * Assumes typical viewport width ~1366px (common laptop).
+     */
+    readonly RIGHT_MIN: 1200;
+    /**
+     * Minimum x-coordinate for right edge detection.
+     * Prevents false positives from wide centered elements.
+     */
+    readonly RIGHT_MIN_X: 800;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/src/state/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/state/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;GAGG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;OAIG;;IAGH;;;;OAIG;;CAEK,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,eAAe;IAC1B;;;OAGG;;CAEK,CAAC;AAMX;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;;;;OAMG;;CAEK,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO;IAClB;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;CAEK,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,YAAY;IACvB;;;OAGG;;IAGH;;OAEG;;CAEK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,cAAc;IACzB;;;OAGG;;IAGH;;;;OAIG;;IAGH;;;OAGG;;CAEK,CAAC"}

package/dist/src/state/constants.js

@@ -0,0 +1,131 @@
+/**
+ * State System Constants
+ *
+ * Centralized configuration for magic numbers used across the state system.
+ * Each constant includes rationale for its value.
+ */
+// ============================================================================
+// Element Identity Constants (element-identity.ts)
+// ============================================================================
+/**
+ * Viewport thresholds for quadrant computation.
+ * Used to compute coarse position hints for element disambiguation.
+ */
+export const VIEWPORT = {
+    /**
+     * Horizontal midpoint for quadrant detection.
+     * Assumes common viewport width ~1000px (iPad, small desktop).
+     * Elements left of this are 'L', right are 'R'.
+     */
+    MIDPOINT_X: 500,
+    /**
+     * Vertical midpoint for quadrant detection.
+     * Assumes common viewport height ~800px or fold line at 50%.
+     * Elements above this are 'T', below are 'B'.
+     */
+    MIDPOINT_Y: 400,
+};
+/**
+ * Accessible name normalization limits.
+ */
+export const ACCESSIBLE_NAME = {
+    /**
+     * Maximum length for normalized accessible names.
+     * Truncated to prevent excessively long EID inputs.
+     */
+    MAX_LENGTH: 100,
+};
+// ============================================================================
+// Layer Detection Constants (layer-detector.ts)
+// ============================================================================
+/**
+ * Layer detection confidence thresholds.
+ */
+export const LAYER_CONFIDENCE = {
+    /**
+     * Minimum confidence score to include layer in stack.
+     * Candidates below this are filtered out.
+     * Value chosen empirically: modal detection is high confidence (0.95+),
+     * while class-based detection is lower (0.65-0.75).
+     * 0.6 threshold excludes weak class matches while keeping strong patterns.
+     */
+    MIN_THRESHOLD: 0.6,
+};
+/**
+ * Z-index thresholds for layer type detection.
+ * Modern UI libraries typically use z-index ranges:
+ * - Base content: 0-50
+ * - Fixed headers/footers: 50-100
+ * - Drawers/sidebars: 100-500
+ * - Modals: 500-1000+
+ * - Tooltips/popovers: 100-500
+ */
+export const Z_INDEX = {
+    /**
+     * Z-index threshold for high-confidence modal detection.
+     * Dialogs with z-index > 1000 are almost certainly modals.
+     */
+    MODAL_HIGH: 1000,
+    /**
+     * Minimum z-index for portal container detection.
+     * React/Vue portals typically render at z-index >= 100.
+     */
+    PORTAL_MIN: 100,
+    /**
+     * Z-index threshold for portal area coverage check.
+     * Large elements at this z-index likely cover significant viewport.
+     */
+    PORTAL_HIGH: 500,
+    /**
+     * Minimum z-index for drawer overlay detection.
+     * Below this, element is likely inline nav, not overlay drawer.
+     */
+    DRAWER_MIN: 50,
+    /**
+     * Z-index threshold for confident drawer detection.
+     * Drawers with z-index > 100 are likely overlay panels.
+     */
+    DRAWER_HIGH: 100,
+    /**
+     * Minimum z-index for popover detection.
+     * Standard popovers (menus, tooltips) render above this.
+     */
+    POPOVER_MIN: 100,
+};
+/**
+ * Size thresholds for element detection.
+ */
+export const ELEMENT_SIZE = {
+    /**
+     * Minimum width for portal container detection.
+     * Portals typically have meaningful content size.
+     */
+    PORTAL_MIN_WIDTH: 200,
+    /**
+     * Minimum height for portal container detection.
+     */
+    PORTAL_MIN_HEIGHT: 200,
+};
+/**
+ * Edge position detection thresholds.
+ * Used to identify drawers positioned at viewport edges.
+ */
+export const EDGE_DETECTION = {
+    /**
+     * Maximum x-coordinate for left edge detection.
+     * Elements with x < 10 are considered left-edge positioned.
+     */
+    LEFT_MAX_X: 10,
+    /**
+     * Minimum right edge position.
+     * rightEdge (x + width) must exceed this to be right-edge positioned.
+     * Assumes typical viewport width ~1366px (common laptop).
+     */
+    RIGHT_MIN: 1200,
+    /**
+     * Minimum x-coordinate for right edge detection.
+     * Prevents false positives from wide centered elements.
+     */
+    RIGHT_MIN_X: 800,
+};
+//# sourceMappingURL=constants.js.map

package/dist/src/state/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/state/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,mDAAmD;AACnD,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB;;;;OAIG;IACH,UAAU,EAAE,GAAG;IAEf;;;;OAIG;IACH,UAAU,EAAE,GAAG;CACP,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B;;;OAGG;IACH,UAAU,EAAE,GAAG;CACP,CAAC;AAEX,+EAA+E;AAC/E,gDAAgD;AAChD,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B;;;;;;OAMG;IACH,aAAa,EAAE,GAAG;CACV,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB;;;OAGG;IACH,UAAU,EAAE,IAAI;IAEhB;;;OAGG;IACH,UAAU,EAAE,GAAG;IAEf;;;OAGG;IACH,WAAW,EAAE,GAAG;IAEhB;;;OAGG;IACH,UAAU,EAAE,EAAE;IAEd;;;OAGG;IACH,WAAW,EAAE,GAAG;IAEhB;;;OAGG;IACH,WAAW,EAAE,GAAG;CACR,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B;;;OAGG;IACH,gBAAgB,EAAE,GAAG;IAErB;;OAEG;IACH,iBAAiB,EAAE,GAAG;CACd,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B;;;OAGG;IACH,UAAU,EAAE,EAAE;IAEd;;;;OAIG;IACH,SAAS,EAAE,IAAI;IAEf;;;OAGG;IACH,WAAW,EAAE,GAAG;CACR,CAAC"}

package/dist/src/state/diff-engine.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Diff Engine
+ *
+ * Compute incremental changes between snapshots.
+ * Returns added/removed/changed actionables and atoms.
+ */
+import type { BaseSnapshot } from '../snapshot/snapshot.types.js';
+import type { DiffResponse } from './types.js';
+/**
+ * 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 declare function computeDiff(prev: BaseSnapshot, curr: BaseSnapshot): DiffResponse;
+//# sourceMappingURL=diff-engine.d.ts.map

package/dist/src/state/diff-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-engine.d.ts","sourceRoot":"","sources":["../../../src/state/diff-engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EACV,YAAY,EAMb,MAAM,YAAY,CAAC;AAUpB;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,GAAG,YAAY,CA+ChF"}