agent-web-interface 4.0.0

package/dist/src/observation/observation-accumulator.js

@@ -0,0 +1,213 @@
+/**
+ * Manages persistent DOM observation for a page.
+ *
+ * Lifecycle:
+ * - inject() on page creation
+ * - ensureInjected() after navigation (document context changes)
+ * - getObservations() to retrieve significant mutations
+ */
+import { OBSERVATION_OBSERVER_SCRIPT } from './observer-script.js';
+import { SIGNIFICANCE_THRESHOLD } from './observation.types.js';
+/**
+ * Manages persistent DOM observation for a page.
+ */
+export class ObservationAccumulator {
+    /**
+     * Inject the persistent observer into the page.
+     * Safe to call multiple times - checks for existing injection.
+     */
+    async inject(page) {
+        try {
+            await page.evaluate(OBSERVATION_OBSERVER_SCRIPT);
+        }
+        catch (err) {
+            // Page may be navigating or closed - log but don't throw
+            console.warn('[ObservationAccumulator] Injection failed:', err);
+        }
+    }
+    /**
+     * Ensure observer is injected and valid (re-inject if needed after navigation).
+     *
+     * After navigation or page content changes, the observer might be stale
+     * (observing a detached body). We check if the observer's body reference
+     * matches the current document.body and only re-inject if stale.
+     *
+     * This preserves accumulated observations when the observer is still valid.
+     */
+    async ensureInjected(page) {
+        const needsReinjection = await page
+            .evaluate(() => {
+            // Browser context code - globalThis access is intentional
+            /* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call */
+            const acc = globalThis.__observationAccumulator;
+            // No accumulator - need to inject
+            if (!acc)
+                return true;
+            // Check if observer is stale (observing a different/detached body)
+            // This happens after setContent() or navigation that replaces the body
+            const currentBody = globalThis.document?.body;
+            if (acc.observedBody !== currentBody) {
+                // Observer is stale - disconnect and remove so we can re-inject
+                acc.observer?.disconnect();
+                delete globalThis.__observationAccumulator;
+                return true;
+            }
+            // Observer is still valid - no need to re-inject
+            return false;
+        })
+            .catch(() => {
+            // Error checking - assume we need to inject
+            return true;
+        });
+        if (needsReinjection) {
+            await this.inject(page);
+        }
+    }
+    /**
+     * Get observations for an action.
+     * Returns both action-scoped and unreported accumulated observations.
+     */
+    async getObservations(page, actionStartTime) {
+        try {
+            // Browser context code - uses injected __observationAccumulator
+            /* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any */
+            const result = await page.evaluate((since) => {
+                const acc = globalThis.__observationAccumulator;
+                if (!acc)
+                    return {
+                        duringAction: [],
+                        sincePrevious: [],
+                    };
+                // Get observations during this action
+                const duringAction = acc.getSignificant(since, undefined);
+                // Get unreported observations from before this action
+                const allUnreported = acc.getUnreported();
+                const sincePrevious = allUnreported.filter((e) => e.timestamp < since);
+                // Mark all as reported
+                acc.markReported();
+                return { duringAction, sincePrevious };
+            }, actionStartTime);
+            // Convert raw entries to DOMObservation format
+            return {
+                duringAction: result.duringAction.map((e) => this.rawToObservation(e)),
+                sincePrevious: result.sincePrevious.map((e) => ({
+                    ...this.rawToObservation(e),
+                    ageMs: Date.now() - e.timestamp,
+                })),
+            };
+        }
+        catch {
+            return { duringAction: [], sincePrevious: [] };
+        }
+    }
+    /**
+     * Get accumulated observations without action context.
+     * Used by capture_snapshot to report accumulated changes.
+     */
+    async getAccumulatedObservations(page) {
+        try {
+            // Browser context code - uses injected __observationAccumulator
+            /* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any */
+            const result = await page.evaluate(() => {
+                const acc = globalThis.__observationAccumulator;
+                if (!acc)
+                    return { sincePrevious: [] };
+                // Get all unreported observations
+                const sincePrevious = acc.getUnreported();
+                // Mark all as reported
+                acc.markReported();
+                return { sincePrevious };
+            });
+            return {
+                duringAction: [],
+                sincePrevious: result.sincePrevious.map((e) => ({
+                    ...this.rawToObservation(e),
+                    ageMs: Date.now() - e.timestamp,
+                })),
+            };
+        }
+        catch {
+            return { duringAction: [], sincePrevious: [] };
+        }
+    }
+    /**
+     * Convert raw mutation entry to DOMObservation.
+     */
+    rawToObservation(entry) {
+        const signals = {
+            hasAlertRole: ['alert', 'status', 'log', 'alertdialog'].includes(entry.role ?? ''),
+            hasAriaLive: entry.ariaLive === 'polite' || entry.ariaLive === 'assertive',
+            isDialog: entry.role === 'dialog' || entry.tag === 'dialog' || entry.ariaModal === 'true',
+            isFixedOrSticky: entry.isFixedOrSticky,
+            hasHighZIndex: entry.zIndex > 1000,
+            coversSignificantViewport: entry.viewportCoverage.widthPct > 50 || entry.viewportCoverage.heightPct > 30,
+            isBodyDirectChild: entry.isBodyDirectChild,
+            containsInteractiveElements: entry.hasInteractives,
+            isVisibleInViewport: entry.isVisibleInViewport ?? false,
+            hasNonTrivialText: entry.hasNonTrivialText ?? false,
+            appearedAfterDelay: entry.appearedAfterDelay ?? false,
+            wasShortLived: false, // Computed when we see removal
+        };
+        return {
+            type: entry.type === 'added' ? 'appeared' : 'disappeared',
+            significance: entry.significance,
+            signals,
+            content: {
+                tag: entry.tag,
+                role: entry.role,
+                ariaLabel: entry.ariaLabel,
+                text: entry.text,
+                hasInteractives: entry.hasInteractives,
+            },
+            timestamp: entry.timestamp,
+            reported: false,
+            // Include shadow path if present (for shadow DOM observations)
+            shadowPath: entry.shadowPath,
+        };
+    }
+    /**
+     * Reset observation log (call after navigation).
+     */
+    async reset(page) {
+        try {
+            // Browser context code - uses injected __observationAccumulator
+            /* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any */
+            await page.evaluate(() => {
+                globalThis.__observationAccumulator?.reset();
+            });
+        }
+        catch {
+            // Ignore - page may be navigating
+        }
+    }
+    /**
+     * Check if there are any unreported observations.
+     */
+    async hasUnreported(page) {
+        try {
+            // Browser context code - uses injected __observationAccumulator
+            /* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any */
+            return await page.evaluate(() => {
+                const acc = globalThis.__observationAccumulator;
+                if (!acc)
+                    return false;
+                return acc.getUnreported().length > 0;
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Filter observations by significance threshold.
+     */
+    filterBySignificance(observations, threshold = SIGNIFICANCE_THRESHOLD) {
+        return {
+            duringAction: observations.duringAction.filter((o) => o.significance >= threshold),
+            sincePrevious: observations.sincePrevious.filter((o) => o.significance >= threshold),
+        };
+    }
+}
+// Singleton instance
+export const observationAccumulator = new ObservationAccumulator();
+//# sourceMappingURL=observation-accumulator.js.map

package/dist/src/observation/observation-accumulator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-accumulator.js","sourceRoot":"","sources":["../../../src/observation/observation-accumulator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE;;GAEG;AACH,MAAM,OAAO,sBAAsB;IACjC;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,IAAU;QACrB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,yDAAyD;YACzD,OAAO,CAAC,IAAI,CAAC,4CAA4C,EAAE,GAAG,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,cAAc,CAAC,IAAU;QAC7B,MAAM,gBAAgB,GAAG,MAAM,IAAI;aAChC,QAAQ,CAAC,GAAG,EAAE;YACb,0DAA0D;YAC1D,+KAA+K;YAC/K,MAAM,GAAG,GAAI,UAAkB,CAAC,wBAAwB,CAAC;YAEzD,kCAAkC;YAClC,IAAI,CAAC,GAAG;gBAAE,OAAO,IAAI,CAAC;YAEtB,mEAAmE;YACnE,uEAAuE;YACvE,MAAM,WAAW,GAAI,UAAkB,CAAC,QAAQ,EAAE,IAAI,CAAC;YACvD,IAAI,GAAG,CAAC,YAAY,KAAK,WAAW,EAAE,CAAC;gBACrC,gEAAgE;gBAChE,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,CAAC;gBAC3B,OAAQ,UAAkB,CAAC,wBAAwB,CAAC;gBACpD,OAAO,IAAI,CAAC;YACd,CAAC;YAED,iDAAiD;YACjD,OAAO,KAAK,CAAC;QACf,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE;YACV,4CAA4C;YAC5C,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QAEL,IAAI,gBAAgB,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe,CAAC,IAAU,EAAE,eAAuB;QACvD,IAAI,CAAC;YACH,gEAAgE;YAChE,+KAA+K;YAC/K,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAa,EAAE,EAAE;gBACnD,MAAM,GAAG,GAAI,UAAkB,CAAC,wBAAwB,CAAC;gBACzD,IAAI,CAAC,GAAG;oBACN,OAAO;wBACL,YAAY,EAAE,EAAwB;wBACtC,aAAa,EAAE,EAAwB;qBACxC,CAAC;gBAEJ,sCAAsC;gBACtC,MAAM,YAAY,GAAG,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,SAAS,CAAuB,CAAC;gBAEhF,sDAAsD;gBACtD,MAAM,aAAa,GAAG,GAAG,CAAC,aAAa,EAAwB,CAAC;gBAChE,MAAM,aAAa,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAmB,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,KAAK,CAAC,CAAC;gBAEzF,uBAAuB;gBACvB,GAAG,CAAC,YAAY,EAAE,CAAC;gBAEnB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC;YACzC,CAAC,EAAE,eAAe,CAAC,CAAC;YAEpB,+CAA+C;YAC/C,OAAO;gBACL,YAAY,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAmB,EAAE,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;gBACxF,aAAa,EAAE,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAmB,EAAE,EAAE,CAAC,CAAC;oBAChE,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;oBAC3B,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,SAAS;iBAChC,CAAC,CAAC;aACJ,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,0BAA0B,CAAC,IAAU;QACzC,IAAI,CAAC;YACH,gEAAgE;YAChE,+KAA+K;YAC/K,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;gBACtC,MAAM,GAAG,GAAI,UAAkB,CAAC,wBAAwB,CAAC;gBACzD,IAAI,CAAC,GAAG;oBAAE,OAAO,EAAE,aAAa,EAAE,EAAwB,EAAE,CAAC;gBAE7D,kCAAkC;gBAClC,MAAM,aAAa,GAAG,GAAG,CAAC,aAAa,EAAwB,CAAC;gBAEhE,uBAAuB;gBACvB,GAAG,CAAC,YAAY,EAAE,CAAC;gBAEnB,OAAO,EAAE,aAAa,EAAE,CAAC;YAC3B,CAAC,CAAC,CAAC;YAEH,OAAO;gBACL,YAAY,EAAE,EAAE;gBAChB,aAAa,EAAE,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAmB,EAAE,EAAE,CAAC,CAAC;oBAChE,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;oBAC3B,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,SAAS;iBAChC,CAAC,CAAC;aACJ,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;OAEG;IACK,gBAAgB,CAAC,KAAuB;QAC9C,MAAM,OAAO,GAAwB;YACnC,YAAY,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;YAClF,WAAW,EAAE,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,KAAK,CAAC,QAAQ,KAAK,WAAW;YAC1E,QAAQ,EAAE,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,SAAS,KAAK,MAAM;YACzF,eAAe,EAAE,KAAK,CAAC,eAAe;YACtC,aAAa,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI;YAClC,yBAAyB,EACvB,KAAK,CAAC,gBAAgB,CAAC,QAAQ,GAAG,EAAE,IAAI,KAAK,CAAC,gBAAgB,CAAC,SAAS,GAAG,EAAE;YAC/E,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;YAC1C,2BAA2B,EAAE,KAAK,CAAC,eAAe;YAClD,mBAAmB,EAAE,KAAK,CAAC,mBAAmB,IAAI,KAAK;YACvD,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,IAAI,KAAK;YACnD,kBAAkB,EAAE,KAAK,CAAC,kBAAkB,IAAI,KAAK;YACrD,aAAa,EAAE,KAAK,EAAE,+BAA+B;SACtD,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,aAAa;YACzD,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,OAAO;YACP,OAAO,EAAE;gBACP,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,eAAe,EAAE,KAAK,CAAC,eAAe;aACvC;YACD,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,QAAQ,EAAE,KAAK;YACf,+DAA+D;YAC/D,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,IAAU;QACpB,IAAI,CAAC;YACH,gEAAgE;YAChE,sIAAsI;YACtI,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;gBACtB,UAAkB,CAAC,wBAAwB,EAAE,KAAK,EAAE,CAAC;YACxD,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,kCAAkC;QACpC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa,CAAC,IAAU;QAC5B,IAAI,CAAC;YACH,gEAAgE;YAChE,+KAA+K;YAC/K,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;gBAC9B,MAAM,GAAG,GAAI,UAAkB,CAAC,wBAAwB,CAAC;gBACzD,IAAI,CAAC,GAAG;oBAAE,OAAO,KAAK,CAAC;gBACvB,OAAO,GAAG,CAAC,aAAa,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;YACxC,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;OAEG;IACH,oBAAoB,CAClB,YAA+B,EAC/B,YAAoB,sBAAsB;QAE1C,OAAO;YACL,YAAY,EAAE,YAAY,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,IAAI,SAAS,CAAC;YAClF,aAAa,EAAE,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,IAAI,SAAS,CAAC;SACrF,CAAC;IACJ,CAAC;CACF;AAED,qBAAqB;AACrB,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,sBAAsB,EAAE,CAAC"}

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

@@ -0,0 +1,139 @@
+/**
+ * Types and interfaces for DOM observation capture.
+ *
+ * DOM Observations capture significant mutations (toasts, dialogs, banners, overlays)
+ * that appear during or between actions. These are integrated as "observations" in
+ * the snapshot response.
+ */
+/**
+ * Signals used to compute significance of a DOM mutation.
+ * All signals are derived from universal web standards - no hardcoded patterns.
+ */
+export interface SignificanceSignals {
+    hasAlertRole: boolean;
+    hasAriaLive: boolean;
+    isDialog: boolean;
+    isFixedOrSticky: boolean;
+    hasHighZIndex: boolean;
+    coversSignificantViewport: boolean;
+    isBodyDirectChild: boolean;
+    containsInteractiveElements: boolean;
+    isVisibleInViewport: boolean;
+    hasNonTrivialText: boolean;
+    appearedAfterDelay: boolean;
+    wasShortLived: boolean;
+}
+/**
+ * Significance scoring weights.
+ * Total score >= SIGNIFICANCE_THRESHOLD to be included in observations.
+ */
+export declare const SIGNIFICANCE_WEIGHTS: Record<keyof SignificanceSignals, number>;
+export declare const SIGNIFICANCE_THRESHOLD = 4;
+/**
+ * Higher threshold for attaching observations to tool responses.
+ *
+ * Two-Tier Filtering Strategy:
+ * ----------------------------
+ * Tier 1 (Browser-side, threshold=4): SIGNIFICANCE_THRESHOLD
+ *   - Applied in observer-script.ts during DOM mutation capture
+ *   - Filters out clearly insignificant mutations at capture time
+ *
+ * Tier 2 (Attachment-time, threshold=5): ATTACHMENT_SIGNIFICANCE_THRESHOLD
+ *   - Applied when attaching observations to snapshot responses
+ *   - Requires semantic signal (ARIA role) + visual/structural signals
+ *   - Reduces response verbosity for the LLM
+ */
+export declare const ATTACHMENT_SIGNIFICANCE_THRESHOLD = 5;
+/**
+ * Compute significance score from signals.
+ */
+export declare function computeSignificance(signals: SignificanceSignals): number;
+/**
+ * Content captured from an observed element.
+ */
+export interface ObservedContent {
+    tag: string;
+    role?: string;
+    ariaLabel?: string;
+    text: string;
+    hasInteractives: boolean;
+}
+/**
+ * Child element within an observation.
+ * Represents actionable or notable elements inside an observed container.
+ */
+export interface ObservationChild {
+    /** Element type: 'button', 'link', 'heading', 'text', etc. */
+    tag: string;
+    /** Element identifier for targeting (if available) */
+    eid?: string;
+    /** Visible text content */
+    text: string;
+}
+/**
+ * A single DOM observation - an element that appeared or disappeared.
+ */
+export interface DOMObservation {
+    type: 'appeared' | 'disappeared';
+    /** Computed significance score */
+    significance: number;
+    /** Signals that contributed to the score */
+    signals: SignificanceSignals;
+    /** Element content */
+    content: ObservedContent;
+    /** If element still exists in snapshot, its eid for targeting */
+    eid?: string;
+    /** When the mutation occurred (epoch ms) */
+    timestamp: number;
+    /** For 'disappeared': how long element was visible (ms) */
+    durationMs?: number;
+    /** For unreported observations: time since observation (ms) */
+    ageMs?: number;
+    /** Has this observation been included in a response? */
+    reported: boolean;
+    /** Shadow DOM path - identifiers of shadow host ancestors (for shadow DOM observations) */
+    shadowPath?: string[];
+    /** Interactive/notable children within this observation (for appeared elements) */
+    children?: ObservationChild[];
+    /** Delay in ms from action start to when this element appeared */
+    delayMs?: number;
+}
+/**
+ * Raw mutation entry captured by the persistent observer.
+ * Lives in browser context (window.__observationAccumulator).
+ */
+export interface RawMutationEntry {
+    type: 'added' | 'removed';
+    timestamp: number;
+    tag: string;
+    id?: string;
+    role?: string;
+    ariaLive?: string;
+    ariaLabel?: string;
+    ariaModal?: string;
+    text: string;
+    hasInteractives: boolean;
+    isFixedOrSticky: boolean;
+    zIndex: number;
+    viewportCoverage: {
+        widthPct: number;
+        heightPct: number;
+    };
+    isBodyDirectChild: boolean;
+    isVisibleInViewport?: boolean;
+    hasNonTrivialText?: boolean;
+    appearedAfterDelay?: boolean;
+    /** Shadow path - identifiers of shadow host ancestors (for shadow DOM observations) */
+    shadowPath?: string[];
+    significance: number;
+}
+/**
+ * Observations grouped by when they occurred.
+ */
+export interface ObservationGroups {
+    /** Observations from the current action's time window */
+    duringAction: DOMObservation[];
+    /** Accumulated observations since previous tool call */
+    sincePrevious: DOMObservation[];
+}
+//# sourceMappingURL=observation.types.d.ts.map

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

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

package/dist/src/observation/observation.types.js

@@ -0,0 +1,59 @@
+/**
+ * Types and interfaces for DOM observation capture.
+ *
+ * DOM Observations capture significant mutations (toasts, dialogs, banners, overlays)
+ * that appear during or between actions. These are integrated as "observations" in
+ * the snapshot response.
+ */
+/**
+ * Significance scoring weights.
+ * Total score >= SIGNIFICANCE_THRESHOLD to be included in observations.
+ */
+export const SIGNIFICANCE_WEIGHTS = {
+    // Semantic (strongest signals)
+    hasAlertRole: 3,
+    hasAriaLive: 3,
+    isDialog: 3,
+    // Visual signals
+    isFixedOrSticky: 2,
+    hasHighZIndex: 1,
+    coversSignificantViewport: 2,
+    // Structural signals
+    isBodyDirectChild: 1,
+    containsInteractiveElements: 1,
+    // Universal signals (work without ARIA)
+    isVisibleInViewport: 2,
+    hasNonTrivialText: 1,
+    // Temporal signals
+    appearedAfterDelay: 2,
+    wasShortLived: 2,
+};
+export const SIGNIFICANCE_THRESHOLD = 4;
+/**
+ * Higher threshold for attaching observations to tool responses.
+ *
+ * Two-Tier Filtering Strategy:
+ * ----------------------------
+ * Tier 1 (Browser-side, threshold=4): SIGNIFICANCE_THRESHOLD
+ *   - Applied in observer-script.ts during DOM mutation capture
+ *   - Filters out clearly insignificant mutations at capture time
+ *
+ * Tier 2 (Attachment-time, threshold=5): ATTACHMENT_SIGNIFICANCE_THRESHOLD
+ *   - Applied when attaching observations to snapshot responses
+ *   - Requires semantic signal (ARIA role) + visual/structural signals
+ *   - Reduces response verbosity for the LLM
+ */
+export const ATTACHMENT_SIGNIFICANCE_THRESHOLD = 5;
+/**
+ * Compute significance score from signals.
+ */
+export function computeSignificance(signals) {
+    let score = 0;
+    for (const [key, weight] of Object.entries(SIGNIFICANCE_WEIGHTS)) {
+        if (signals[key]) {
+            score += weight;
+        }
+    }
+    return score;
+}
+//# sourceMappingURL=observation.types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"observation.types.js","sourceRoot":"","sources":["../../../src/observation/observation.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8BH;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA8C;IAC7E,+BAA+B;IAC/B,YAAY,EAAE,CAAC;IACf,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,CAAC;IAEX,iBAAiB;IACjB,eAAe,EAAE,CAAC;IAClB,aAAa,EAAE,CAAC;IAChB,yBAAyB,EAAE,CAAC;IAE5B,qBAAqB;IACrB,iBAAiB,EAAE,CAAC;IACpB,2BAA2B,EAAE,CAAC;IAE9B,wCAAwC;IACxC,mBAAmB,EAAE,CAAC;IACtB,iBAAiB,EAAE,CAAC;IAEpB,mBAAmB;IACnB,kBAAkB,EAAE,CAAC;IACrB,aAAa,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC;AAEnD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA4B;IAC9D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACjE,IAAI,OAAO,CAAC,GAAgC,CAAC,EAAE,CAAC;YAC9C,KAAK,IAAI,MAAM,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/observation/observer-script.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Browser-side script for DOM observation.
+ *
+ * This script is injected into the browser context and runs continuously to capture
+ * significant DOM mutations. It uses universal web standards for significance detection -
+ * NO hardcoded text/class patterns.
+ *
+ * Shadow DOM Support:
+ * - Detects shadow hosts when elements are added
+ * - Attaches MutationObservers to open shadow roots
+ * - Tracks shadow path context for observations
+ * - Cleans up observers when shadow hosts are removed
+ *
+ * Note: Closed shadow roots cannot be observed (browser security).
+ *
+ * The script is returned as a string for page.evaluate().
+ */
+export declare const OBSERVATION_OBSERVER_SCRIPT = "\n(function() {\n  // Prevent double-injection\n  if (window.__observationAccumulator) return;\n\n  const MAX_ENTRIES = 500;\n  const MAX_TEXT_LENGTH = 200;\n  const MAX_SHADOW_OBSERVERS = 50; // Limit to prevent performance issues\n  // IMPORTANT: Must match SIGNIFICANCE_THRESHOLD in observation.types.ts\n  const SIGNIFICANCE_THRESHOLD = 4;\n  // Node type constant for shadow root parent check\n  const DOCUMENT_FRAGMENT_NODE = 11;\n\n  // Significance weights (must match server-side observation.types.ts)\n  const WEIGHTS = {\n    // Semantic signals (strongest)\n    hasAlertRole: 3,\n    hasAriaLive: 3,\n    isDialog: 3,\n\n    // Visual signals\n    isFixedOrSticky: 2,\n    hasHighZIndex: 1,\n    coversSignificantViewport: 2,\n\n    // Structural signals\n    isBodyDirectChild: 1,\n    containsInteractiveElements: 1,\n\n    // New universal signals - work without ARIA\n    isVisibleInViewport: 2,      // Element is visible in viewport\n    hasNonTrivialText: 1,        // Has meaningful text content\n    // Temporal signals computed later\n  };\n\n  // Shadow DOM tracking\n  // Map: shadowRoot -> { observer, hostPath }\n  const shadowObservers = new Map();\n\n  // Track processed elements to avoid duplicate observations\n  // WeakSet allows garbage collection of removed elements\n  let processedElements = new WeakSet();\n\n  /**\n   * Generate a stable identifier for an element (for shadow path tracking).\n   * Format: TAG#id or TAG.className or TAG[index]\n   */\n  function getElementIdentifier(el) {\n    const tag = el.tagName.toLowerCase();\n    if (el.id) {\n      return tag + '#' + el.id;\n    }\n    // For custom elements, use the tag name (usually descriptive like 'my-toast')\n    if (tag.includes('-')) {\n      return tag;\n    }\n    // Fallback: use first class or just tag\n    const className = el.className && typeof el.className === 'string'\n      ? el.className.split(' ')[0]\n      : '';\n    if (className) {\n      return tag + '.' + className;\n    }\n    return tag;\n  }\n\n  // Tags whose text content should be excluded from extraction\n  const EXCLUDED_TEXT_TAGS = new Set(['STYLE', 'SCRIPT', 'NOSCRIPT', 'TEMPLATE', 'SVG']);\n\n  /**\n   * Get clean text content from an element, excluding CSS/JS content.\n   * Uses TreeWalker to iterate only text nodes, skipping those inside\n   * excluded tags (STYLE, SCRIPT, NOSCRIPT, TEMPLATE, SVG).\n   *\n   * @param {Element} el - The DOM element to extract text from\n   * @param {number} maxLength - Maximum text length (truncates result)\n   * @returns {string} Clean text content, space-joined, truncated to maxLength\n   */\n  function getCleanTextContent(el, maxLength) {\n    // If element itself is an excluded tag, return empty\n    if (EXCLUDED_TEXT_TAGS.has(el.tagName.toUpperCase())) {\n      return '';\n    }\n\n    const walker = document.createTreeWalker(el, 4, { // NodeFilter.SHOW_TEXT = 4\n      acceptNode: function(node) {\n        let parent = node.parentElement;\n        while (parent && parent !== el) {\n          if (EXCLUDED_TEXT_TAGS.has(parent.tagName.toUpperCase())) {\n            return 2; // FILTER_REJECT\n          }\n          parent = parent.parentElement;\n        }\n        return 1; // FILTER_ACCEPT\n      }\n    });\n\n    const textParts = [];\n    let totalLength = 0;\n    let node;\n\n    while ((node = walker.nextNode()) && totalLength < maxLength) {\n      const text = node.nodeValue;\n      if (text) {\n        const trimmed = text.trim();\n        if (trimmed) {\n          textParts.push(trimmed);\n          totalLength += trimmed.length;\n        }\n      }\n    }\n\n    return textParts.join(' ').substring(0, maxLength);\n  }\n\n  /**\n   * Compute significance signals from element.\n   * Uses universal web standards (ARIA, CSS positioning, DOM structure, visibility).\n   */\n  function computeSignals(el, shadowPath) {\n    const role = el.getAttribute('role');\n    const ariaLive = el.getAttribute('aria-live');\n    const ariaModal = el.getAttribute('aria-modal');\n    const tagName = el.tagName.toLowerCase();\n\n    // Get computed style (may fail for detached elements)\n    let style = null;\n    let rect = null;\n    try {\n      style = getComputedStyle(el);\n      rect = el.getBoundingClientRect();\n    } catch (e) {\n      // Element may be detached\n    }\n\n    const vw = window.innerWidth;\n    const vh = window.innerHeight;\n\n    // Check if element is visible in viewport\n    const isVisibleInViewport = rect && style &&\n      rect.width > 0 && rect.height > 0 &&\n      rect.bottom > 0 && rect.top < vh &&\n      rect.right > 0 && rect.left < vw &&\n      style.display !== 'none' &&\n      style.visibility !== 'hidden' &&\n      style.opacity !== '0';\n\n    // Check for non-trivial text (at least 3 chars, not just whitespace)\n    // Use short sample for signal check - excludes style/script content\n    const text = getCleanTextContent(el, 100);\n    const hasNonTrivialText = text.length >= 3;\n\n    // For shadow DOM elements, isBodyDirectChild is false but we still want to capture them\n    // Check if parent is a shadow root (which indicates top-level in shadow DOM)\n    const isTopLevelInShadow = shadowPath && shadowPath.length > 0 &&\n      el.parentNode && el.parentNode.nodeType === DOCUMENT_FRAGMENT_NODE;\n\n    return {\n      // Semantic signals\n      hasAlertRole: ['alert', 'status', 'log', 'alertdialog'].includes(role),\n      hasAriaLive: ariaLive === 'polite' || ariaLive === 'assertive',\n      isDialog: role === 'dialog' || tagName === 'dialog' || ariaModal === 'true',\n\n      // Visual signals\n      isFixedOrSticky: style && (style.position === 'fixed' || style.position === 'sticky'),\n      // Note: parseInt returns NaN for non-numeric values like \"auto\", which correctly fails the > 1000 check\n      hasHighZIndex: style && parseInt(style.zIndex, 10) > 1000,\n      coversSignificantViewport: rect && ((rect.width > vw * 0.5) || (rect.height > vh * 0.3)),\n\n      // Structural signals - consider top-level shadow DOM elements as equivalent to body children\n      isBodyDirectChild: el.parentElement === document.body || isTopLevelInShadow,\n      containsInteractiveElements: el.querySelector('button, a, input, select, textarea') !== null,\n\n      // Universal signals (work without ARIA)\n      isVisibleInViewport: !!isVisibleInViewport,\n      hasNonTrivialText: hasNonTrivialText,\n\n      // Temporal signals (set by accumulator later)\n      appearedAfterDelay: false,\n      wasShortLived: false,\n    };\n  }\n\n  /**\n   * Calculate significance score from signals using weighted sum.\n   * @param signals - The computed significance signals for an element\n   * @returns The total significance score\n   */\n  function computeSignificance(signals) {\n    let score = 0;\n    for (const [key, weight] of Object.entries(WEIGHTS)) {\n      if (signals[key]) score += weight;\n    }\n    return score;\n  }\n\n  /**\n   * Capture a mutation entry from an element.\n   * @param node - The DOM node\n   * @param type - 'added' or 'removed'\n   * @param shadowPath - Optional array of shadow host identifiers\n   */\n  function captureEntry(node, type, shadowPath) {\n    if (node.nodeType !== 1) return null; // Element nodes only\n\n    const el = node;\n    const signals = computeSignals(el, shadowPath);\n    const significance = computeSignificance(signals);\n\n    // Only capture if meets threshold\n    if (significance < SIGNIFICANCE_THRESHOLD) return null;\n\n    // Capture content - excludes style/script content\n    const text = getCleanTextContent(el, MAX_TEXT_LENGTH);\n    const hasInteractives = signals.containsInteractiveElements;\n\n    // Get viewport coverage for later analysis\n    let viewportCoverage = { widthPct: 0, heightPct: 0 };\n    try {\n      const rect = el.getBoundingClientRect();\n      viewportCoverage = {\n        widthPct: Math.round((rect.width / window.innerWidth) * 100),\n        heightPct: Math.round((rect.height / window.innerHeight) * 100),\n      };\n    } catch (e) {\n      // Element may be detached\n    }\n\n    // Get z-index\n    let zIndex = 0;\n    try {\n      zIndex = parseInt(getComputedStyle(el).zIndex, 10) || 0;\n    } catch (e) {\n      // Element may be detached\n    }\n\n    const entry = {\n      type: type,\n      timestamp: Date.now(),\n      tag: el.tagName.toLowerCase(),\n      id: el.id || undefined,\n\n      // Semantic attributes\n      role: el.getAttribute('role') || undefined,\n      ariaLive: el.getAttribute('aria-live') || undefined,\n      ariaLabel: el.getAttribute('aria-label') || undefined,\n      ariaModal: el.getAttribute('aria-modal') || undefined,\n\n      // Content\n      text: text,\n      hasInteractives: hasInteractives,\n\n      // Visual signals\n      isFixedOrSticky: signals.isFixedOrSticky,\n      zIndex: zIndex,\n      viewportCoverage: viewportCoverage,\n\n      // Structural\n      isBodyDirectChild: signals.isBodyDirectChild,\n\n      // Universal signals\n      isVisibleInViewport: signals.isVisibleInViewport,\n      hasNonTrivialText: signals.hasNonTrivialText,\n\n      // Shadow DOM context\n      shadowPath: shadowPath && shadowPath.length > 0 ? shadowPath : undefined,\n\n      // Significance\n      significance: significance,\n    };\n\n    return entry;\n  }\n\n  const log = [];\n  const pageLoadTime = Date.now();\n\n  /**\n   * Process added nodes - capture entries and check for shadow roots.\n   * @param node - The added node\n   * @param shadowPath - Current shadow path context\n   */\n  function processAddedNode(node, shadowPath) {\n    // Skip if already processed (prevents duplicates from nested shadow DOM)\n    if (node.nodeType === 1 && processedElements.has(node)) {\n      return;\n    }\n\n    const entry = captureEntry(node, 'added', shadowPath);\n    if (entry) {\n      entry.appearedAfterDelay = (entry.timestamp - pageLoadTime) > 100;\n      log.push(entry);\n      // Mark as processed\n      if (node.nodeType === 1) {\n        processedElements.add(node);\n      }\n    }\n\n    // Check significant children - both ARIA-attributed and visible text elements\n    if (node.nodeType === 1) {\n      // First: ARIA-attributed elements (high confidence)\n      const ariaChildren = node.querySelectorAll(\n        '[role=\"alert\"], [role=\"status\"], [role=\"dialog\"], [role=\"alertdialog\"], [aria-live], [aria-modal], dialog'\n      );\n      for (const child of ariaChildren) {\n        // Skip if already processed\n        if (processedElements.has(child)) continue;\n\n        const childEntry = captureEntry(child, 'added', shadowPath);\n        if (childEntry) {\n          childEntry.appearedAfterDelay = (childEntry.timestamp - pageLoadTime) > 100;\n          log.push(childEntry);\n          processedElements.add(child);\n        }\n      }\n\n      // Second: Any visible element with text (broader capture for sites without ARIA)\n      const textChildren = node.querySelectorAll('span, div, p, small, strong, em, label, li');\n      for (const child of textChildren) {\n        // Skip if already processed\n        if (processedElements.has(child)) continue;\n\n        // Skip if already captured via ARIA query\n        if (child.hasAttribute('role') || child.hasAttribute('aria-live')) continue;\n\n        // Only capture leaf-ish elements (minimal nested structure)\n        const hasDeepNesting = child.querySelector('div, p, ul, ol, table');\n        if (hasDeepNesting) continue;\n\n        const childEntry = captureEntry(child, 'added', shadowPath);\n        if (childEntry) {\n          childEntry.appearedAfterDelay = (childEntry.timestamp - pageLoadTime) > 100;\n          log.push(childEntry);\n          processedElements.add(child);\n        }\n      }\n\n      // Check for shadow roots in this element and its descendants\n      checkAndObserveShadowRoots(node, shadowPath || []);\n    }\n  }\n\n  /**\n   * Process removed nodes - capture entries and cleanup shadow observers.\n   * @param node - The removed node\n   * @param shadowPath - Current shadow path context\n   */\n  function processRemovedNode(node, shadowPath) {\n    const entry = captureEntry(node, 'removed', shadowPath);\n    if (entry) {\n      log.push(entry);\n    }\n\n    // Cleanup shadow observers for removed elements\n    if (node.nodeType === 1) {\n      cleanupShadowObservers(node);\n    }\n  }\n\n  /**\n   * Create a mutation callback for observing a specific context (main DOM or shadow root).\n   * @param shadowPath - The shadow path context for this observer\n   */\n  function createMutationCallback(shadowPath) {\n    return function(mutations) {\n      for (const m of mutations) {\n        // Capture added nodes\n        for (const node of m.addedNodes) {\n          processAddedNode(node, shadowPath);\n        }\n\n        // Capture removed nodes\n        for (const node of m.removedNodes) {\n          processRemovedNode(node, shadowPath);\n        }\n      }\n\n      // Trim if over limit (FIFO)\n      if (log.length > MAX_ENTRIES) {\n        const excess = log.length - MAX_ENTRIES;\n        log.splice(0, excess);\n      }\n    };\n  }\n\n  /**\n   * Observe a shadow root for mutations.\n   * @param shadowRoot - The shadow root to observe\n   * @param shadowPath - The path of shadow host identifiers leading to this shadow root\n   */\n  function observeShadowRoot(shadowRoot, shadowPath) {\n    // Already observing this shadow root\n    if (shadowObservers.has(shadowRoot)) return;\n\n    // Limit number of shadow observers for performance\n    if (shadowObservers.size >= MAX_SHADOW_OBSERVERS) {\n      console.warn('[ObservationAccumulator] Max shadow observers reached, skipping:', shadowPath);\n      return;\n    }\n\n    const observer = new MutationObserver(createMutationCallback(shadowPath));\n    observer.observe(shadowRoot, {\n      childList: true,\n      subtree: true,\n    });\n\n    shadowObservers.set(shadowRoot, { observer, hostPath: shadowPath });\n  }\n\n  /**\n   * Recursively check element and descendants for open shadow roots.\n   * @param element - The element to check\n   * @param currentShadowPath - The current shadow path context\n   * @param visited - Set of already-visited elements to prevent infinite recursion\n   */\n  function checkAndObserveShadowRoots(element, currentShadowPath, visited) {\n    if (!element || element.nodeType !== 1) return;\n\n    // Initialize visited set on first call\n    if (!visited) {\n      visited = new Set();\n    }\n\n    // Prevent infinite recursion from circular references\n    if (visited.has(element)) return;\n    visited.add(element);\n\n    // Check if this element has an open shadow root\n    if (element.shadowRoot) {\n      const newPath = [...currentShadowPath, getElementIdentifier(element)];\n      observeShadowRoot(element.shadowRoot, newPath);\n\n      // Check shadow root's children for nested shadow roots\n      const shadowChildren = element.shadowRoot.querySelectorAll('*');\n      for (const child of shadowChildren) {\n        if (child.shadowRoot) {\n          checkAndObserveShadowRoots(child, newPath, visited);\n        }\n      }\n    }\n\n    // Check light DOM children for shadow roots\n    const children = element.querySelectorAll('*');\n    for (const child of children) {\n      if (child.shadowRoot) {\n        checkAndObserveShadowRoots(child, currentShadowPath, visited);\n      }\n    }\n  }\n\n  /**\n   * Cleanup shadow observers for a removed element and its descendants.\n   * @param element - The element being removed\n   */\n  function cleanupShadowObservers(element) {\n    if (!element || element.nodeType !== 1) return;\n\n    // If element is a shadow host, cleanup its observer\n    if (element.shadowRoot && shadowObservers.has(element.shadowRoot)) {\n      const { observer } = shadowObservers.get(element.shadowRoot);\n      observer.disconnect();\n      shadowObservers.delete(element.shadowRoot);\n    }\n\n    // Recursively cleanup descendant shadow hosts\n    try {\n      const descendants = element.querySelectorAll('*');\n      for (const child of descendants) {\n        if (child.shadowRoot && shadowObservers.has(child.shadowRoot)) {\n          const { observer } = shadowObservers.get(child.shadowRoot);\n          observer.disconnect();\n          shadowObservers.delete(child.shadowRoot);\n        }\n      }\n    } catch (e) {\n      // Element may be detached, ignore errors\n    }\n  }\n\n  // Create main observer for document.body\n  const observer = new MutationObserver(createMutationCallback(null));\n\n  // Start observing\n  if (document.body) {\n    observer.observe(document.body, {\n      childList: true,\n      subtree: true,\n    });\n\n    // Initial scan for existing shadow roots in the DOM\n    checkAndObserveShadowRoots(document.body, []);\n  }\n\n  window.__observationAccumulator = {\n    log: log,\n    observer: observer,\n    shadowObservers: shadowObservers, // Expose for debugging/testing\n    observedBody: document.body, // Track which body we're observing for staleness detection\n    pageLoadTime: pageLoadTime,\n    lastReportedIndex: 0, // Track what's been reported\n\n    // Get all entries since timestamp\n    getSince: function(timestamp) {\n      return this.log.filter(e => e.timestamp >= timestamp);\n    },\n\n    // Get significant entries since timestamp\n    getSignificant: function(timestamp, threshold) {\n      threshold = threshold || SIGNIFICANCE_THRESHOLD;\n      return this.log.filter(e => e.timestamp >= timestamp && e.significance >= threshold);\n    },\n\n    // Get unreported entries (for accumulation between tool calls)\n    getUnreported: function() {\n      const unreported = this.log.slice(this.lastReportedIndex);\n      return unreported.filter(e => e.significance >= SIGNIFICANCE_THRESHOLD);\n    },\n\n    // Mark entries as reported\n    markReported: function() {\n      this.lastReportedIndex = this.log.length;\n    },\n\n    // Reset on navigation\n    reset: function() {\n      this.log.length = 0;\n      this.lastReportedIndex = 0;\n      this.pageLoadTime = Date.now();\n      // Cleanup all shadow observers\n      for (const [shadowRoot, { observer }] of this.shadowObservers) {\n        observer.disconnect();\n      }\n      this.shadowObservers.clear();\n      // Clear processed elements tracking (create fresh WeakSet)\n      processedElements = new WeakSet();\n    },\n\n    // Re-scan for shadow roots (useful after dynamic content load)\n    rescanShadowRoots: function() {\n      if (document.body) {\n        checkAndObserveShadowRoots(document.body, []);\n      }\n    },\n\n    // Get shadow observer count (for debugging)\n    getShadowObserverCount: function() {\n      return this.shadowObservers.size;\n    },\n  };\n})();\n";
+//# sourceMappingURL=observer-script.d.ts.map

package/dist/src/observation/observer-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-script.d.ts","sourceRoot":"","sources":["../../../src/observation/observer-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,2BAA2B,s4kBAsiBvC,CAAC"}