@reticlehq/browser 2.0.1 → 2.2.0

package/dist/observers/perf.js

@@ -0,0 +1,62 @@
+import { EventType, PerfMetric } from '@reticlehq/core';
+/**
+ * Observe the web-perf signals a screenshot tool fundamentally cannot verify — largest-contentful-paint
+ * (LCP), cumulative layout shift (CLS), and long tasks — and emit them into the ring buffer so an agent
+ * can assert "no layout shift on load" or "LCP under 2.5s". No-ops when PerformanceObserver or a given
+ * entry type is unavailable (jsdom / older browsers), so it never throws in an unsupported context.
+ *
+ * Each event carries `at` (the entry's own startTime) so a consumer can reason about WHEN the metric
+ * occurred rather than when it was flushed — buffered:true replays pre-install entries, whose emit time
+ * would otherwise be install time.
+ */
+export function installPerf(emit) {
+    if (typeof PerformanceObserver !== 'function')
+        return () => undefined;
+    const observers = [];
+    const observe = (type, handle) => {
+        try {
+            const po = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries())
+                    handle(entry);
+            });
+            po.observe({ type, buffered: true });
+            observers.push(po);
+        }
+        catch {
+            /* entry type unsupported in this browser — skip it, leave the others installed */
+        }
+    };
+    // CLS is CUMULATIVE: sum qualifying shifts and report the running total, not each isolated shift.
+    // ponytail: naive running sum — no session-windowing (5s window / 1s gap); enough for
+    // "no layout shift on load" and trend, upgrade to windowed sessions if a CWV-exact number is needed.
+    let cls = 0;
+    // LCP only grows across candidates — surface a value only when it exceeds the last, not every candidate.
+    let lcp = 0;
+    observe('largest-contentful-paint', (e) => {
+        const value = Math.round(e.startTime);
+        if (value <= lcp)
+            return;
+        lcp = value;
+        emit(EventType.PERF, { metric: PerfMetric.LCP, value, at: value });
+    });
+    observe('layout-shift', (e) => {
+        const ls = e;
+        // Shifts within 500ms of a user input are expected (not CLS) — the spec's hadRecentInput flag.
+        if (ls.hadRecentInput === true)
+            return;
+        cls += ls.value ?? 0;
+        emit(EventType.PERF, { metric: PerfMetric.CLS, value: cls, at: Math.round(e.startTime) });
+    });
+    observe('longtask', (e) => {
+        emit(EventType.PERF, {
+            metric: PerfMetric.LONGTASK,
+            value: Math.round(e.duration),
+            at: Math.round(e.startTime),
+        });
+    });
+    return () => {
+        for (const po of observers)
+            po.disconnect();
+    };
+}
+//# sourceMappingURL=perf.js.map

package/dist/observers/perf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf.js","sourceRoot":"","sources":["../../src/observers/perf.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AASxD;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU;IACpC,IAAI,OAAO,mBAAmB,KAAK,UAAU;QAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;IACtE,MAAM,SAAS,GAA0B,EAAE,CAAC;IAC5C,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,MAAyC,EAAQ,EAAE;QAChF,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,IAAI,mBAAmB,CAAC,CAAC,IAAI,EAAE,EAAE;gBAC1C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,UAAU,EAAE;oBAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YACvD,CAAC,CAAC,CAAC;YACH,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACrC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;QAAC,MAAM,CAAC;YACP,kFAAkF;QACpF,CAAC;IACH,CAAC,CAAC;IAEF,kGAAkG;IAClG,sFAAsF;IACtF,qGAAqG;IACrG,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,yGAAyG;IACzG,IAAI,GAAG,GAAG,CAAC,CAAC;IAEZ,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAAC,EAAE,EAAE;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,KAAK,IAAI,GAAG;YAAE,OAAO;QACzB,GAAG,GAAG,KAAK,CAAC;QACZ,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE;QAC5B,MAAM,EAAE,GAAG,CAAqB,CAAC;QACjC,+FAA+F;QAC/F,IAAI,EAAE,CAAC,cAAc,KAAK,IAAI;YAAE,OAAO;QACvC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE;QACxB,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE;YACnB,MAAM,EAAE,UAAU,CAAC,QAAQ;YAC3B,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;YAC7B,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;SAC5B,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,EAAE;QACV,KAAK,MAAM,EAAE,IAAI,SAAS;YAAE,EAAE,CAAC,UAAU,EAAE,CAAC;IAC9C,CAAC,CAAC;AACJ,CAAC"}

package/dist/observers/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/observers/route.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAWjD,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CA+CjD"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/observers/route.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAYjD,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CAsDjD"}

package/dist/observers/route.js

@@ -1,4 +1,5 @@
 import { EventType } from '@reticlehq/core';
+import { captureMethod } from '../patching/capture-method.js';
 function snapshotLocation() {
     return {
         pathname: location.pathname,
@@ -11,16 +12,19 @@ function snapshotLocation() {
 export function installRoute(emit) {
     // Keep the true originals for teardown identity; bound copies are used for invocation
     // (History methods throw "Illegal invocation" if called with the wrong `this`).
-    /* eslint-disable @typescript-eslint/unbound-method -- captured to restore exact identity on teardown */
-    const origPush = history.pushState;
-    const origReplace = history.replaceState;
-    /* eslint-enable @typescript-eslint/unbound-method */
+    const origPush = captureMethod(history, 'pushState');
+    const origReplace = captureMethod(history, 'replaceState');
     const callPush = origPush.bind(history);
     const callReplace = origReplace.bind(history);
+    // The `from` baseline for the NEXT popstate/hashchange. Updated in fire on every emitted change
+    // — including pushState/replaceState — so a later Back nav isn't compared against a stale href
+    // (which made `to === from` trip and silently drop the back navigation).
+    let lastHref = location.href;
     const fire = (from) => {
         const to = snapshotLocation();
         if (to.href === from)
             return;
+        lastHref = to.href;
         emit(EventType.ROUTE_CHANGE, {
             from,
             to: to.href,
@@ -29,26 +33,31 @@ export function installRoute(emit) {
             hash: to.hash,
         });
     };
-    history.pushState = (data, unused, url) => {
+    const patchedPush = (data, unused, url) => {
         const from = location.href;
         callPush(data, unused, url ?? null);
         fire(from);
     };
-    history.replaceState = (data, unused, url) => {
+    const patchedReplace = (data, unused, url) => {
         const from = location.href;
         callReplace(data, unused, url ?? null);
         fire(from);
     };
-    let lastHref = location.href;
+    history.pushState = patchedPush;
+    history.replaceState = patchedReplace;
     const onNav = () => {
         fire(lastHref);
-        lastHref = location.href;
     };
     window.addEventListener('popstate', onNav);
     window.addEventListener('hashchange', onNav);
     return () => {
-        history.pushState = origPush;
-        history.replaceState = origReplace;
+        // Restore ONLY if the slot still holds our wrapper. If a router/analytics SDK wrapped
+        // history.pushState AFTER connect(), unconditionally writing origPush back would silently
+        // uninstall THEIR instrumentation too — the SDK harming the app it only meant to observe.
+        if (history.pushState === patchedPush)
+            history.pushState = origPush;
+        if (history.replaceState === patchedReplace)
+            history.replaceState = origReplace;
         window.removeEventListener('popstate', onNav);
         window.removeEventListener('hashchange', onNav);
     };

package/dist/observers/route.js.map

@@ -1 +1 @@
-{"version":3,"file":"route.js","sourceRoot":"","sources":["../../src/observers/route.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,SAAS,gBAAgB;IACvB,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,IAAI,EAAE,QAAQ,CAAC,IAAI;KACpB,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,sFAAsF;IACtF,gFAAgF;IAChF,wGAAwG;IACxG,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IACnC,MAAM,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IACzC,qDAAqD;IACrD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE9C,MAAM,IAAI,GAAG,CAAC,IAAY,EAAQ,EAAE;QAClC,MAAM,EAAE,GAAG,gBAAgB,EAAE,CAAC;QAC9B,IAAI,EAAE,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO;QAC7B,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE;YAC3B,IAAI;YACJ,EAAE,EAAE,EAAE,CAAC,IAAI;YACX,QAAQ,EAAE,EAAE,CAAC,QAAQ;YACrB,MAAM,EAAE,EAAE,CAAC,MAAM;YACjB,IAAI,EAAE,EAAE,CAAC,IAAI;SACd,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO,CAAC,SAAS,GAAG,CAAC,IAAa,EAAE,MAAc,EAAE,GAAyB,EAAQ,EAAE;QACrF,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;QAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,CAAC,CAAC;IACF,OAAO,CAAC,YAAY,GAAG,CAAC,IAAa,EAAE,MAAc,EAAE,GAAyB,EAAQ,EAAE;QACxF,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;QAC3B,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,CAAC,CAAC;IAEF,IAAI,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC7B,MAAM,KAAK,GAAG,GAAS,EAAE;QACvB,IAAI,CAAC,QAAQ,CAAC,CAAC;QACf,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC3B,CAAC,CAAC;IACF,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAC3C,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAE7C,OAAO,GAAG,EAAE;QACV,OAAO,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC7B,OAAO,CAAC,YAAY,GAAG,WAAW,CAAC;QACnC,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAC9C,MAAM,CAAC,mBAAmB,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../src/observers/route.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE9D,SAAS,gBAAgB;IACvB,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,IAAI,EAAE,QAAQ,CAAC,IAAI;KACpB,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,sFAAsF;IACtF,gFAAgF;IAChF,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACrD,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE9C,gGAAgG;IAChG,+FAA+F;IAC/F,yEAAyE;IACzE,IAAI,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC;IAE7B,MAAM,IAAI,GAAG,CAAC,IAAY,EAAQ,EAAE;QAClC,MAAM,EAAE,GAAG,gBAAgB,EAAE,CAAC;QAC9B,IAAI,EAAE,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO;QAC7B,QAAQ,GAAG,EAAE,CAAC,IAAI,CAAC;QACnB,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE;YAC3B,IAAI;YACJ,EAAE,EAAE,EAAE,CAAC,IAAI;YACX,QAAQ,EAAE,EAAE,CAAC,QAAQ;YACrB,MAAM,EAAE,EAAE,CAAC,MAAM;YACjB,IAAI,EAAE,EAAE,CAAC,IAAI;SACd,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,CAAC,IAAa,EAAE,MAAc,EAAE,GAAyB,EAAQ,EAAE;QACrF,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;QAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,CAAC,CAAC;IACF,MAAM,cAAc,GAAG,CAAC,IAAa,EAAE,MAAc,EAAE,GAAyB,EAAQ,EAAE;QACxF,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;QAC3B,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,CAAC,CAAC;IACF,OAAO,CAAC,SAAS,GAAG,WAAW,CAAC;IAChC,OAAO,CAAC,YAAY,GAAG,cAAc,CAAC;IAEtC,MAAM,KAAK,GAAG,GAAS,EAAE;QACvB,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjB,CAAC,CAAC;IACF,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAC3C,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAE7C,OAAO,GAAG,EAAE;QACV,sFAAsF;QACtF,0FAA0F;QAC1F,0FAA0F;QAC1F,IAAI,OAAO,CAAC,SAAS,KAAK,WAAW;YAAE,OAAO,CAAC,SAAS,GAAG,QAAQ,CAAC;QACpE,IAAI,OAAO,CAAC,YAAY,KAAK,cAAc;YAAE,OAAO,CAAC,YAAY,GAAG,WAAW,CAAC;QAChF,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAC9C,MAAM,CAAC,mBAAmB,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC"}

package/dist/observers/scroll.d.ts

@@ -1,4 +1,4 @@
 import type { Emit, Teardown } from './types.js';
-/** Observe scroll position + reveal-on-scroll for modern scroll-reactive UIs (plan/03 §8). */
+/** Observe scroll position + reveal-on-scroll for modern scroll-reactive UIs. */
 export declare function installScroll(emit: Emit): Teardown;
 //# sourceMappingURL=scroll.d.ts.map

package/dist/observers/scroll.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scroll.d.ts","sourceRoot":"","sources":["../../src/observers/scroll.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKjD,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CA2ClD"}
+{"version":3,"file":"scroll.d.ts","sourceRoot":"","sources":["../../src/observers/scroll.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKjD,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CAsElD"}

package/dist/observers/scroll.js

@@ -1,26 +1,44 @@
-import { EventType } from '@reticlehq/core';
+import { EventType, ScrollDirection } from '@reticlehq/core';
 import { refs } from '../dom/refs.js';
+import { nativeSetTimeout, nativeClearTimeout } from '../timers/native-timers.js';
 const THROTTLE_MS = 100;
 const REVEAL_SELECTOR = '[data-reticle-reveal], [data-reveal], section';
-/** Observe scroll position + reveal-on-scroll for modern scroll-reactive UIs (plan/03 §8). */
+/** Observe scroll position + reveal-on-scroll for modern scroll-reactive UIs. */
 export function installScroll(emit) {
     let lastEmit = 0;
     let lastY = 0;
-    const onScroll = () => {
-        const now = performance.now();
-        if (now - lastEmit < THROTTLE_MS)
-            return;
-        lastEmit = now;
+    let trailingTimer;
+    const emitPosition = () => {
+        lastEmit = performance.now();
         const y = window.scrollY;
         const max = Math.max(1, document.documentElement.scrollHeight - window.innerHeight);
         emit(EventType.SCROLL_POSITION, {
             x: window.scrollX,
             y,
             percent: Math.round((y / max) * 100),
-            direction: y >= lastY ? 'down' : 'up',
+            direction: y >= lastY ? ScrollDirection.DOWN : ScrollDirection.UP,
         });
         lastY = y;
     };
+    const onScroll = () => {
+        const elapsed = performance.now() - lastEmit;
+        if (elapsed >= THROTTLE_MS) {
+            if (trailingTimer !== undefined) {
+                nativeClearTimeout(trailingTimer);
+                trailingTimer = undefined;
+            }
+            emitPosition();
+            return;
+        }
+        // Leading-edge only dropped the FINAL, resting position — an agent asserting "scrolled to the
+        // footer" saw the last mid-scroll sample, not where the page settled. Schedule a trailing emit.
+        if (trailingTimer === undefined) {
+            trailingTimer = nativeSetTimeout(() => {
+                trailingTimer = undefined;
+                emitPosition();
+            }, THROTTLE_MS - elapsed);
+        }
+    };
     window.addEventListener('scroll', onScroll, { passive: true });
     let io;
     if (typeof IntersectionObserver === 'function') {
@@ -31,11 +49,20 @@ export function installScroll(emit) {
                 }
             }
         }, { threshold: 0.25 });
+        const observer = io;
+        // Observe reveal targets present at install. Reveal-on-scroll sections are in the initial DOM by
+        // design (they exist hidden and animate in on scroll), so this covers the real case. Watching the
+        // whole body subtree for LATE-mounted reveal targets was tried and reverted: a second body-wide
+        // MutationObserver on EVERY app — running querySelectorAll(section,...) per mutation batch — is
+        // disproportionate overhead for a niche signal. Dynamically-mounted reveal targets are simply not
+        // tracked (an honest blind spot, consistent with the rest of the SDK).
         for (const el of document.querySelectorAll(REVEAL_SELECTOR))
-            io.observe(el);
+            observer.observe(el);
     }
     return () => {
         window.removeEventListener('scroll', onScroll);
+        if (trailingTimer !== undefined)
+            nativeClearTimeout(trailingTimer);
         io?.disconnect();
     };
 }

package/dist/observers/scroll.js.map

@@ -1 +1 @@
-{"version":3,"file":"scroll.js","sourceRoot":"","sources":["../../src/observers/scroll.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAGtC,MAAM,WAAW,GAAG,GAAG,CAAC;AACxB,MAAM,eAAe,GAAG,+CAA+C,CAAC;AAExE,8FAA8F;AAC9F,MAAM,UAAU,aAAa,CAAC,IAAU;IACtC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,MAAM,QAAQ,GAAG,GAAS,EAAE;QAC1B,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAC9B,IAAI,GAAG,GAAG,QAAQ,GAAG,WAAW;YAAE,OAAO;QACzC,QAAQ,GAAG,GAAG,CAAC;QACf,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QACpF,IAAI,CAAC,SAAS,CAAC,eAAe,EAAE;YAC9B,CAAC,EAAE,MAAM,CAAC,OAAO;YACjB,CAAC;YACD,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;YACpC,SAAS,EAAE,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;SACtC,CAAC,CAAC;QACH,KAAK,GAAG,CAAC,CAAC;IACZ,CAAC,CAAC;IACF,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/D,IAAI,EAAoC,CAAC;IACzC,IAAI,OAAO,oBAAoB,KAAK,UAAU,EAAE,CAAC;QAC/C,EAAE,GAAG,IAAI,oBAAoB,CAC3B,CAAC,OAAO,EAAE,EAAE;YACV,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;oBACzB,IAAI,CACF,SAAS,CAAC,YAAY,EACtB,EAAE,KAAK,EAAE,KAAK,CAAC,iBAAiB,EAAE,EAClC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAC1B,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC,EACD,EAAE,SAAS,EAAE,IAAI,EAAE,CACpB,CAAC;QACF,KAAK,MAAM,EAAE,IAAI,QAAQ,CAAC,gBAAgB,CAAC,eAAe,CAAC;YAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO,GAAG,EAAE;QACV,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC/C,EAAE,EAAE,UAAU,EAAE,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"scroll.js","sourceRoot":"","sources":["../../src/observers/scroll.ts"],"names":[],"mappings":"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"}

package/dist/observers/state.d.ts

@@ -0,0 +1,20 @@
+import type { Emit, Teardown } from './types.js';
+interface StateChange {
+    path: string;
+    old: unknown;
+    new: unknown;
+}
+/**
+ * Shallow top-level diff of two store states — the keys whose value changed. Immutable updates
+ * (Zustand/Redux) replace the changed key's reference, so `Object.is` catches them. Pure; deep-nested
+ * diffing behind an unchanged top-level reference is a v2 concern.
+ */
+export declare function diffState(prev: unknown, next: unknown): StateChange[];
+/**
+ * Subscribe to every registered store that exposed a subscribe method, emitting a STATE_CHANGE per
+ * changed top-level path with {name, path, old, new} — automatic diffs, not pull-only readings. Stores
+ * without a subscribe fall back to the pull path (reticle_state). Fully reversible.
+ */
+export declare function installStoreState(emit: Emit): Teardown;
+export {};
+//# sourceMappingURL=state.d.ts.map

package/dist/observers/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/observers/state.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEjD,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,EAAE,OAAO,CAAC;CACd;AAMD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,WAAW,EAAE,CAUrE;AAeD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CA8CtD"}

package/dist/observers/state.js

@@ -0,0 +1,87 @@
+import { EventType, REDACTED_VALUE } from '@reticlehq/core';
+import { subscribableStores, onStoreRegistered, } from '../registry/stores.js';
+import { isSensitiveKey, sanitizeForTransport } from '../security/serialization.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Shallow top-level diff of two store states — the keys whose value changed. Immutable updates
+ * (Zustand/Redux) replace the changed key's reference, so `Object.is` catches them. Pure; deep-nested
+ * diffing behind an unchanged top-level reference is a v2 concern.
+ */
+export function diffState(prev, next) {
+    if (!isRecord(prev) || !isRecord(next)) {
+        return Object.is(prev, next) ? [] : [{ path: '', old: prev, new: next }];
+    }
+    const changes = [];
+    for (const key of new Set([...Object.keys(prev), ...Object.keys(next)])) {
+        if (!Object.is(prev[key], next[key]))
+            changes.push({ path: key, old: prev[key], new: next[key] });
+    }
+    return changes;
+}
+/** Redact a changed value when its path is credential-bearing, else cap it for transport. */
+function project(path, value) {
+    return isSensitiveKey(path) ? REDACTED_VALUE : sanitizeForTransport(value);
+}
+function safeRead(getter) {
+    try {
+        return getter();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Subscribe to every registered store that exposed a subscribe method, emitting a STATE_CHANGE per
+ * changed top-level path with {name, path, old, new} — automatic diffs, not pull-only readings. Stores
+ * without a subscribe fall back to the pull path (reticle_state). Fully reversible.
+ */
+export function installStoreState(emit) {
+    const active = new Map();
+    const watch = ([name, getter, subscribe]) => {
+        // A re-registration under the same name is the HMR cycle: the store INSTANCE is replaced (new
+        // getter + new subscribe). Skipping it (the old `seen` guard) left the subscription bound to the
+        // DEAD getter forever and the live store invisible until a full reload. Rebind: drop the previous
+        // subscription for this name, then subscribe the new tuple. Guard the old unsubscribe — if it throws
+        // (a misbehaving store), the rebind must still proceed, or the live store stays invisible.
+        try {
+            active.get(name)?.();
+        }
+        catch {
+            /* a faulty unsubscribe must not block re-binding to the new instance */
+        }
+        let last = safeRead(getter);
+        active.set(name, subscribe(() => {
+            const next = safeRead(getter);
+            for (const change of diffState(last, next)) {
+                emit(EventType.STATE_CHANGE, {
+                    name,
+                    path: change.path,
+                    value: project(change.path, change.new),
+                    old: project(change.path, change.old),
+                });
+            }
+            last = next;
+        }));
+    };
+    // Stores already registered...
+    for (const entry of subscribableStores())
+        watch(entry);
+    //...and any registered LATER. The SDK installs observers during connect, but apps call
+    // registerStore after that, so without this the common case subscribes to nothing.
+    const offRegistered = onStoreRegistered(watch);
+    return () => {
+        offRegistered();
+        for (const unsubscribe of active.values()) {
+            try {
+                unsubscribe();
+            }
+            catch {
+                /* one faulty store unsubscribe must not abort tearing the rest down */
+            }
+        }
+        active.clear();
+    };
+}
+//# sourceMappingURL=state.js.map

package/dist/observers/state.js.map

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

package/dist/observers/storage.d.ts

@@ -0,0 +1,23 @@
+import { type Emit, type Teardown } from './types.js';
+/** The three readable client-side storage areas. httpOnly cookies are invisible to JS by design. */
+export interface StorageSnapshot {
+    local: Record<string, string>;
+    session: Record<string, string>;
+    cookies: Record<string, string>;
+}
+/**
+ * Read client-side storage on demand (the STORAGE_READ command). Powers `reticle_storage` — the
+ * agent verifies "token persisted after login", "cart survived reload", "logout cleared the session"
+ * from the app's real storage rather than inferring it from the DOM. `area` scopes to one area; omit
+ * for all three. Sensitive keys are redacted; httpOnly cookies are unreadable by design (documented).
+ */
+export declare function readStorage(area?: string): StorageSnapshot | Record<string, string>;
+/**
+ * Observe storage WRITES (not just reads): patch Storage.setItem/removeItem so a token persisted, a
+ * cart updated, or a session cleared emits a STORAGE_CHANGE {area, key, old?, new?} diff — the "before"
+ * the pull path can never see. localStorage and sessionStorage share one prototype, so `this` inside the
+ * patch identifies the area. The native originals are read off the prototype descriptor (not a bare
+ * method access) and re-dispatched via `.call(this)`. Fully reversible; values redacted like the reads.
+ */
+export declare function installStorage(emit: Emit): Teardown;
+//# sourceMappingURL=storage.d.ts.map

package/dist/observers/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/observers/storage.ts"],"names":[],"mappings":"AAEA,OAAO,EAA+B,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEnF,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAmDD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASnF;AAYD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CAwFnD"}

package/dist/observers/storage.js

@@ -0,0 +1,177 @@
+import { EventType, REDACTED_VALUE, StorageArea } from '@reticlehq/core';
+import { isSensitiveKey } from '../security/serialization.js';
+import { observeSafely, observeValue } from './types.js';
+/** Accessing localStorage/sessionStorage throws in a sandboxed iframe / disabled-storage context. */
+function safeArea(get) {
+    try {
+        return get();
+    }
+    catch {
+        return null;
+    }
+}
+function readArea(storage) {
+    const out = {};
+    if (storage === null)
+        return out;
+    for (let i = 0; i < storage.length; i += 1) {
+        const key = storage.key(i);
+        if (key === null)
+            continue;
+        // Redact credential-bearing keys (token/session/password/…) so auth state never leaks verbatim.
+        out[key] = isSensitiveKey(key) ? REDACTED_VALUE : (storage.getItem(key) ?? '');
+    }
+    return out;
+}
+function readCookies() {
+    const out = {};
+    // Reading document.cookie can throw (SecurityError) in a sandboxed / cookie-disabled context — guard
+    // it the same way safeArea guards localStorage, so one bad area never crashes the whole STORAGE read.
+    let raw = '';
+    try {
+        raw = typeof document !== 'undefined' ? document.cookie : '';
+    }
+    catch {
+        return out;
+    }
+    for (const part of raw.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = part.slice(0, eq).trim();
+        if (key === '')
+            continue;
+        if (isSensitiveKey(key)) {
+            out[key] = REDACTED_VALUE;
+            continue;
+        }
+        try {
+            out[key] = decodeURIComponent(part.slice(eq + 1).trim());
+        }
+        catch {
+            out[key] = part.slice(eq + 1).trim();
+        }
+    }
+    return out;
+}
+/**
+ * Read client-side storage on demand (the STORAGE_READ command). Powers `reticle_storage` — the
+ * agent verifies "token persisted after login", "cart survived reload", "logout cleared the session"
+ * from the app's real storage rather than inferring it from the DOM. `area` scopes to one area; omit
+ * for all three. Sensitive keys are redacted; httpOnly cookies are unreadable by design (documented).
+ */
+export function readStorage(area) {
+    if (area === StorageArea.LOCAL)
+        return readArea(safeArea(() => window.localStorage));
+    if (area === StorageArea.SESSION)
+        return readArea(safeArea(() => window.sessionStorage));
+    if (area === 'cookies')
+        return readCookies();
+    return {
+        local: readArea(safeArea(() => window.localStorage)),
+        session: readArea(safeArea(() => window.sessionStorage)),
+        cookies: readCookies(),
+    };
+}
+/** Redact a value when its key is credential-bearing — the same rule the pull path applies. */
+function redactFor(key, value) {
+    if (value === null)
+        return undefined;
+    return isSensitiveKey(key) ? REDACTED_VALUE : value;
+}
+/**
+ * Observe storage WRITES (not just reads): patch Storage.setItem/removeItem so a token persisted, a
+ * cart updated, or a session cleared emits a STORAGE_CHANGE {area, key, old?, new?} diff — the "before"
+ * the pull path can never see. localStorage and sessionStorage share one prototype, so `this` inside the
+ * patch identifies the area. The native originals are read off the prototype descriptor (not a bare
+ * method access) and re-dispatched via `.call(this)`. Fully reversible; values redacted like the reads.
+ */
+export function installStorage(emit) {
+    if (typeof Storage === 'undefined')
+        return () => undefined;
+    const proto = Storage.prototype;
+    const origSet = Object.getOwnPropertyDescriptor(proto, 'setItem')?.value;
+    const origRemove = Object.getOwnPropertyDescriptor(proto, 'removeItem')?.value;
+    const origClear = Object.getOwnPropertyDescriptor(proto, 'clear')?.value;
+    if (origSet === undefined || origRemove === undefined || origClear === undefined) {
+        return () => undefined;
+    }
+    // Resolve sessionStorage at CALL time, not once at install. If the property threw during install
+    // (a transient sandbox state) the captured reference would be null and every session write would be
+    // misreported as `local` for the life of the page. Reads are cheap and safeArea swallows throws.
+    const areaOf = (storage) => storage === safeArea(() => window.sessionStorage) ? StorageArea.SESSION : StorageArea.LOCAL;
+    const readOld = (storage, key) => {
+        try {
+            return storage.getItem(key);
+        }
+        catch {
+            return null;
+        }
+    };
+    const patchedSetItem = function (key, value) {
+        // The app's write happens FIRST and outside the guard — it must succeed or fail on its own terms.
+        const old = observeValue(() => readOld(this, key)) ?? null;
+        origSet.call(this, key, value);
+        observeSafely(() => {
+            emit(EventType.STORAGE_CHANGE, {
+                area: areaOf(this),
+                key,
+                ...(redactFor(key, old) === undefined ? {} : { old: redactFor(key, old) }),
+                new: redactFor(key, value) ?? REDACTED_VALUE,
+            });
+        });
+    };
+    proto.setItem = patchedSetItem;
+    const patchedRemoveItem = function (key) {
+        const old = observeValue(() => readOld(this, key)) ?? null;
+        origRemove.call(this, key);
+        observeSafely(() => {
+            // No `new` field ⇒ the key was removed.
+            emit(EventType.STORAGE_CHANGE, {
+                area: areaOf(this),
+                key,
+                ...(redactFor(key, old) === undefined ? {} : { old: redactFor(key, old) }),
+            });
+        });
+    };
+    proto.removeItem = patchedRemoveItem;
+    const patchedClear = function () {
+        // localStorage.clear() is the most common logout — but it emitted NOTHING, so "logout cleared the
+        // session" was unverifiable from the write path. Snapshot the keys BEFORE clearing (the values are
+        // gone after), then report each as a removal, reusing the {area, key, old} shape removeItem emits.
+        const area = areaOf(this);
+        const removed = [];
+        try {
+            for (let i = 0; i < this.length; i += 1) {
+                const key = this.key(i);
+                if (key !== null)
+                    removed.push({ key, old: readOld(this, key) });
+            }
+        }
+        catch {
+            // Enumerating keys can throw in a locked-down context; clear anyway, just without the diff.
+        }
+        origClear.call(this);
+        for (const { key, old } of removed) {
+            observeSafely(() => {
+                emit(EventType.STORAGE_CHANGE, {
+                    area,
+                    key,
+                    ...(redactFor(key, old) === undefined ? {} : { old: redactFor(key, old) }),
+                });
+            });
+        }
+    };
+    proto.clear = patchedClear;
+    return () => {
+        // Restore only if the slot still holds our wrapper — never uninstall a wrapper the app layered
+        // on top of ours after connect().
+        if (proto.setItem === patchedSetItem)
+            proto.setItem = origSet;
+        if (proto.removeItem === patchedRemoveItem)
+            proto.removeItem = origRemove;
+        if (proto.clear === patchedClear)
+            proto.clear = origClear;
+    };
+}
+//# sourceMappingURL=storage.js.map

package/dist/observers/storage.js.map

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

package/dist/observers/types.d.ts

@@ -3,4 +3,19 @@ import type { EventType } from '@reticlehq/core';
 export type Emit = (type: EventType, data: Record<string, unknown>, ref?: string) => void;
 /** Every observer returns a teardown that fully restores any patched globals. */
 export type Teardown = () => void;
+/**
+ * Run an observation so it can never escape into the app's call stack.
+ *
+ * Every monkey-patch calls its observation INSIDE the function it replaced, so a throw does not surface
+ * as an SDK error — it propagates out of `localStorage.setItem` after the write already succeeded, out
+ * of `history.pushState` (crashing a router's navigate), or out of `console.log` before the message
+ * reaches the console. Guarding the transport hop alone is not enough: the payload is BUILT here too
+ * (reading the old value, resolving the area, redacting), and any of that can throw on a hostile or
+ * exotic object.
+ *
+ * A dev-only observability SDK must never be able to break the app it is observing.
+ */
+export declare function observeSafely(observation: () => void): void;
+/** Like observeSafely, but for reading a value the observation needs; undefined if the read throws. */
+export declare function observeValue<T>(read: () => T): T | undefined;
 //# sourceMappingURL=types.d.ts.map

package/dist/observers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observers/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,yFAAyF;AACzF,MAAM,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAE1F,iFAAiF;AACjF,MAAM,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observers/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,yFAAyF;AACzF,MAAM,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAE1F,iFAAiF;AACjF,MAAM,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,IAAI,GAAG,IAAI,CAM3D;AAED,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAM5D"}