@agent-native/core 0.47.1 → 0.48.1

package/dist/client/use-db-sync.js

@@ -38,15 +38,6 @@ function normalizeEventPayload(payload) {
     }
     return [payload];
 }
-function eventVersion(event) {
-    return typeof event.version === "number" ? event.version : 0;
-}
-function hasAppStateEvent(events, key) {
-    return events.some((event) => event.source === "app-state" &&
-        (event.key === key ||
-            event.key === "*" ||
-            (typeof event.key === "string" && event.key.startsWith(`${key}:`))));
-}
 function isAuthFailure(error) {
     return (!!error &&
         typeof error === "object" &&
@@ -72,6 +63,287 @@ async function fetchPollJson(pollUrl, since, interval) {
             clearTimeout(timeout);
     }
 }
+class SyncTransport {
+    pollUrl;
+    sseUrl;
+    subscribers = new Map();
+    versionRef = 0;
+    timer = null;
+    stopped = false;
+    inFlight = false;
+    eventSource = null;
+    sseConnected = false;
+    authFailureUntil = 0;
+    constructor(pollUrl, sseUrl) {
+        this.pollUrl = pollUrl;
+        this.sseUrl = sseUrl;
+    }
+    // -------------------------------------------------------------------------
+    // Subscriber management
+    // -------------------------------------------------------------------------
+    add(id, sub) {
+        const wasEmpty = this.subscribers.size === 0;
+        this.subscribers.set(id, sub);
+        if (wasEmpty) {
+            this.stopped = false;
+            this.start();
+        }
+    }
+    remove(id) {
+        this.subscribers.delete(id);
+        if (this.subscribers.size === 0) {
+            this.teardown();
+        }
+        else {
+            // Recalculate poll interval in case the leaving subscriber was the
+            // fastest caller; reschedule with the updated cadence.
+            this.reschedule();
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Derived settings (aggregate over active subscribers)
+    // -------------------------------------------------------------------------
+    get effectivePauseWhenHidden() {
+        // Pause only if every subscriber has opted in.
+        for (const sub of this.subscribers.values()) {
+            if (!sub.pauseWhenHidden)
+                return false;
+        }
+        return true;
+    }
+    get effectiveInterval() {
+        let min = Infinity;
+        for (const sub of this.subscribers.values()) {
+            if (sub.interval < min)
+                min = sub.interval;
+        }
+        return isFinite(min) ? min : 2000;
+    }
+    get effectiveFallbackInterval() {
+        let min = Infinity;
+        for (const sub of this.subscribers.values()) {
+            if (sub.fallbackInterval < min)
+                min = sub.fallbackInterval;
+        }
+        return isFinite(min) ? min : SSE_FALLBACK_INTERVAL_MS;
+    }
+    // -------------------------------------------------------------------------
+    // Event fan-out
+    // -------------------------------------------------------------------------
+    fan(events, version) {
+        for (const sub of this.subscribers.values()) {
+            sub.onEvents(events, version);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // SSE + poll loop (mirrors the original per-hook logic exactly)
+    // -------------------------------------------------------------------------
+    authFailureDelayMs() {
+        return Math.max(0, this.authFailureUntil - Date.now());
+    }
+    schedulePoll() {
+        if (this.stopped)
+            return;
+        if (this.effectivePauseWhenHidden && isDocumentHidden())
+            return;
+        if (this.timer)
+            clearTimeout(this.timer);
+        const authDelay = this.authFailureDelayMs();
+        if (authDelay > 0) {
+            this.timer = setTimeout(() => {
+                this.timer = null;
+                void this.poll();
+            }, authDelay);
+            return;
+        }
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.poll();
+        }, this.sseConnected
+            ? this.effectiveFallbackInterval
+            : this.effectiveInterval);
+    }
+    reschedule() {
+        // Only need to act if a timer is already pending; next natural tick will
+        // pick up the new effective interval otherwise.
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+            this.schedulePoll();
+        }
+    }
+    closeEvents() {
+        if (!this.eventSource)
+            return;
+        this.eventSource.close();
+        this.eventSource = null;
+        this.sseConnected = false;
+    }
+    connectEvents() {
+        if (this.stopped ||
+            !this.sseUrl ||
+            this.eventSource ||
+            typeof EventSource === "undefined" ||
+            (this.effectivePauseWhenHidden && isDocumentHidden())) {
+            return;
+        }
+        const source = new EventSource(this.sseUrl);
+        this.eventSource = source;
+        source.onopen = () => {
+            this.sseConnected = true;
+            this.schedulePoll();
+        };
+        source.onerror = () => {
+            this.sseConnected = false;
+            // When the browser gives up permanently (HTTP error → readyState
+            // CLOSED), it won't auto-reconnect. Drop the ref so a later
+            // connectEvents() (on focus/visibility) can establish a fresh stream;
+            // otherwise the non-null closed `eventSource` blocks reconnection and
+            // we'd be stuck on polling-only forever.
+            if (source.readyState === EventSource.CLOSED) {
+                this.eventSource = null;
+            }
+            this.schedulePoll();
+        };
+        source.onmessage = (message) => {
+            try {
+                const payload = JSON.parse(message.data);
+                const events = normalizeEventPayload(payload);
+                const version = typeof payload?.version === "number" ? payload.version : undefined;
+                this.applyVersion(events, version);
+                this.fan(events, version);
+            }
+            catch {
+                // Ignore malformed SSE frames; polling is the safety net.
+            }
+        };
+    }
+    /**
+     * Advance the transport's shared version cursor. Subscribers receive the
+     * raw events and decide independently which ones are "fresh" relative to
+     * their own cursor, but the transport-level cursor ensures the poll
+     * `?since=` parameter always advances.
+     */
+    applyVersion(events, version) {
+        let max = typeof version === "number" ? version : 0;
+        for (const evt of events) {
+            const v = typeof evt.version === "number" ? evt.version : 0;
+            if (v > max)
+                max = v;
+        }
+        if (max > this.versionRef)
+            this.versionRef = max;
+    }
+    async poll() {
+        if (this.stopped || this.inFlight)
+            return;
+        this.inFlight = true;
+        try {
+            const data = await fetchPollJson(this.pollUrl, this.versionRef, this.effectiveInterval);
+            if (this.stopped)
+                return;
+            const events = data.events ?? [];
+            this.applyVersion(events, data.version);
+            this.fan(events, data.version);
+        }
+        catch (err) {
+            if (this.stopped)
+                return;
+            if (isAuthFailure(err)) {
+                this.authFailureUntil = Date.now() + POLL_AUTH_FAILURE_COOLDOWN_MS;
+                this.closeEvents();
+            }
+            // Network error — will retry on next interval.
+        }
+        finally {
+            this.inFlight = false;
+            this.schedulePoll();
+        }
+    }
+    pollNow() {
+        if (this.effectivePauseWhenHidden && isDocumentHidden())
+            return;
+        if (this.authFailureDelayMs() > 0) {
+            this.schedulePoll();
+            return;
+        }
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.connectEvents();
+        void this.poll();
+    }
+    handleVisibilityChange = () => {
+        if (document.visibilityState === "visible") {
+            this.connectEvents();
+            this.pollNow();
+        }
+        else if (this.effectivePauseWhenHidden) {
+            this.closeEvents();
+            if (this.timer) {
+                clearTimeout(this.timer);
+                this.timer = null;
+            }
+        }
+    };
+    handleFocus = () => {
+        this.pollNow();
+    };
+    start() {
+        // Universal demo-mode redaction for the UI. Idempotent + browser-only +
+        // a no-op until demo mode is on. Lives here because every template root
+        // already mounts useDbSync, so this needs zero per-template wiring.
+        ensureEmbedAuthFetchInterceptor();
+        ensureDemoModeFetchInterceptor();
+        if (!this.effectivePauseWhenHidden || !isDocumentHidden()) {
+            this.connectEvents();
+            void this.poll();
+        }
+        window.addEventListener("focus", this.handleFocus);
+        document.addEventListener("visibilitychange", this.handleVisibilityChange);
+    }
+    teardown() {
+        this.stopped = true;
+        this.closeEvents();
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        window.removeEventListener("focus", this.handleFocus);
+        document.removeEventListener("visibilitychange", this.handleVisibilityChange);
+    }
+}
+/**
+ * Registry of active transports keyed by "<pollUrl>\0<sseUrl>".
+ * Module-level singleton: survives React render cycles, shared across all
+ * hook instances in the same browser tab.
+ */
+const transportRegistry = new Map();
+function getOrCreateTransport(pollUrl, sseUrl) {
+    const key = `${pollUrl}\0${String(sseUrl)}`;
+    let transport = transportRegistry.get(key);
+    if (!transport) {
+        transport = new SyncTransport(pollUrl, sseUrl);
+        transportRegistry.set(key, transport);
+    }
+    return transport;
+}
+/** Remove a transport from the registry once torn down (last subscriber left). */
+function releaseTransport(pollUrl, sseUrl) {
+    const key = `${pollUrl}\0${String(sseUrl)}`;
+    // Leave the entry in place: SSE/poll is already stopped inside the class;
+    // the next subscriber will re-start it via `add()`. Clearing the map entry
+    // prevents any dangling reference from the old SyncTransport instance.
+    transportRegistry.delete(key);
+}
+// ---------------------------------------------------------------------------
+// Internal test helper — reset transport registry between tests.
+// ---------------------------------------------------------------------------
+/** @internal */
+export function _resetSyncTransportRegistryForTests() {
+    transportRegistry.clear();
+}
 /**
  * Hook that listens to /_agent-native/events for DB change events and
  * invalidates react-query caches when changes are detected. Falls back to
@@ -106,40 +378,15 @@ export function useDbSync(options = {}) {
     const ignoreSourceRef = useRef(options.ignoreSource);
     ignoreSourceRef.current = options.ignoreSource;
     useEffect(() => {
-        // Universal demo-mode redaction for the UI. Idempotent + browser-only +
-        // a no-op until demo mode is on. Lives here because every template root
-        // already mounts useDbSync, so this needs zero per-template wiring.
-        ensureEmbedAuthFetchInterceptor();
-        ensureDemoModeFetchInterceptor();
-        let versionRef = 0;
-        let timer = null;
-        let stopped = false;
-        let inFlight = false;
-        let eventSource = null;
-        let sseConnected = false;
-        let authFailureUntil = 0;
-        function authFailureDelayMs() {
-            return Math.max(0, authFailureUntil - Date.now());
-        }
-        function schedulePoll() {
-            if (stopped)
-                return;
-            if (pauseWhenHidden && isDocumentHidden())
-                return;
-            if (timer)
-                clearTimeout(timer);
-            const authDelay = authFailureDelayMs();
-            if (authDelay > 0) {
-                timer = setTimeout(() => {
-                    timer = null;
-                    void poll();
-                }, authDelay);
-                return;
-            }
-            timer = setTimeout(() => {
-                timer = null;
-                void poll();
-            }, sseConnected ? fallbackInterval : interval);
+        const id = Symbol("useDbSync");
+        // Per-subscriber version cursor: tracks which events have already been
+        // processed by THIS subscriber so stale poll re-deliveries are ignored.
+        let subscriberVersion = 0;
+        function hasAppStateEvent(events, key) {
+            return events.some((event) => event.source === "app-state" &&
+                (event.key === key ||
+                    event.key === "*" ||
+                    (typeof event.key === "string" && event.key.startsWith(`${key}:`))));
         }
         function invalidateForEvents(events) {
             const ignore = ignoreSourceRef.current;
@@ -199,128 +446,33 @@ export function useDbSync(options = {}) {
                 onEventRef.current?.(evt);
             }
         }
-        function applyEvents(events, version) {
+        function onEvents(events, version) {
             const freshEvents = events.filter((event) => {
-                const version = eventVersion(event);
-                return version === 0 || version > versionRef;
+                const v = typeof event.version === "number" ? event.version : 0;
+                return v === 0 || v > subscriberVersion;
             });
             if (freshEvents.length > 0) {
                 invalidateForEvents(freshEvents);
             }
-            const maxEventVersion = freshEvents.reduce((max, event) => Math.max(max, eventVersion(event)), 0);
-            versionRef = Math.max(versionRef, version ?? 0, maxEventVersion);
-        }
-        function closeEvents() {
-            if (!eventSource)
-                return;
-            eventSource.close();
-            eventSource = null;
-            sseConnected = false;
+            const maxEventVersion = freshEvents.reduce((max, event) => Math.max(max, typeof event.version === "number" ? event.version : 0), 0);
+            subscriberVersion = Math.max(subscriberVersion, version ?? 0, maxEventVersion);
         }
-        function connectEvents() {
-            if (stopped ||
-                !sseUrl ||
-                eventSource ||
-                typeof EventSource === "undefined" ||
-                (pauseWhenHidden && isDocumentHidden())) {
-                return;
-            }
-            const source = new EventSource(sseUrl);
-            eventSource = source;
-            source.onopen = () => {
-                sseConnected = true;
-                schedulePoll();
-            };
-            source.onerror = () => {
-                sseConnected = false;
-                // When the browser gives up permanently (HTTP error → readyState
-                // CLOSED), it won't auto-reconnect. Drop the ref so a later
-                // connectEvents() (on focus/visibility) can establish a fresh stream;
-                // otherwise the non-null closed `eventSource` blocks reconnection and
-                // we'd be stuck on polling-only forever.
-                if (source.readyState === EventSource.CLOSED) {
-                    eventSource = null;
-                }
-                schedulePoll();
-            };
-            source.onmessage = (message) => {
-                try {
-                    const payload = JSON.parse(message.data);
-                    const events = normalizeEventPayload(payload);
-                    const version = typeof payload?.version === "number" ? payload.version : undefined;
-                    applyEvents(events, version);
-                }
-                catch {
-                    // Ignore malformed SSE frames; polling is the safety net.
-                }
-            };
-        }
-        async function poll() {
-            if (stopped || inFlight)
-                return;
-            inFlight = true;
-            try {
-                const data = await fetchPollJson(pollUrl, versionRef, interval);
-                if (stopped)
-                    return;
-                applyEvents(data.events ?? [], data.version);
-            }
-            catch (err) {
-                if (stopped)
-                    return;
-                if (isAuthFailure(err)) {
-                    authFailureUntil = Date.now() + POLL_AUTH_FAILURE_COOLDOWN_MS;
-                    closeEvents();
-                }
-                // Network error — will retry on next interval
-            }
-            finally {
-                inFlight = false;
-                schedulePoll();
-            }
-        }
-        function pollNow() {
-            if (pauseWhenHidden && isDocumentHidden()) {
-                return;
-            }
-            if (authFailureDelayMs() > 0) {
-                schedulePoll();
-                return;
-            }
-            if (timer) {
-                clearTimeout(timer);
-                timer = null;
-            }
-            connectEvents();
-            void poll();
-        }
-        function handleVisibilityChange() {
-            if (document.visibilityState === "visible") {
-                connectEvents();
-                pollNow();
-            }
-            else if (pauseWhenHidden) {
-                closeEvents();
-                if (timer) {
-                    clearTimeout(timer);
-                    timer = null;
-                }
-            }
-        }
-        // Initial poll immediately when visible. Hidden tabs catch up on focus.
-        if (!pauseWhenHidden || !isDocumentHidden()) {
-            connectEvents();
-            void poll();
-        }
-        window.addEventListener("focus", pollNow);
-        document.addEventListener("visibilitychange", handleVisibilityChange);
+        const transport = getOrCreateTransport(pollUrl, sseUrl);
+        transport.add(id, {
+            onEvents,
+            pauseWhenHidden,
+            interval,
+            fallbackInterval,
+        });
         return () => {
-            stopped = true;
-            closeEvents();
-            if (timer)
-                clearTimeout(timer);
-            window.removeEventListener("focus", pollNow);
-            document.removeEventListener("visibilitychange", handleVisibilityChange);
+            transport.remove(id);
+            // If the registry still holds this transport, and the transport is now
+            // empty, evict it so the next mount gets a fresh instance rather than a
+            // stopped-but-still-registered one (the registry entry being cleared by
+            // releaseTransport is the signal to rebuild state).
+            if (!transport["subscribers"].size) {
+                releaseTransport(pollUrl, sseUrl);
+            }
         };
     }, [
         pollUrl,
@@ -356,157 +508,32 @@ export function useScreenRefreshKey(options = {}) {
     const { pollUrl = agentNativePath(options.pollUrl ?? "/_agent-native/poll"), sseUrl = resolveSseUrl(options.sseUrl), interval = 2000, fallbackInterval = Math.max(options.fallbackInterval ?? SSE_FALLBACK_INTERVAL_MS, interval), pauseWhenHidden = true, } = options;
     const [key, setKey] = useState(0);
     useEffect(() => {
-        let versionRef = 0;
-        let timer = null;
-        let stopped = false;
-        let inFlight = false;
-        let eventSource = null;
-        let sseConnected = false;
-        let authFailureUntil = 0;
-        function authFailureDelayMs() {
-            return Math.max(0, authFailureUntil - Date.now());
-        }
-        function schedulePoll() {
-            if (stopped)
-                return;
-            if (pauseWhenHidden && isDocumentHidden())
-                return;
-            if (timer)
-                clearTimeout(timer);
-            const authDelay = authFailureDelayMs();
-            if (authDelay > 0) {
-                timer = setTimeout(() => {
-                    timer = null;
-                    void poll();
-                }, authDelay);
-                return;
-            }
-            timer = setTimeout(() => {
-                timer = null;
-                void poll();
-            }, sseConnected ? fallbackInterval : interval);
-        }
-        function applyEvents(events, version) {
+        const id = Symbol("useScreenRefreshKey");
+        // Per-subscriber version cursor (same freshness logic as useDbSync).
+        let subscriberVersion = 0;
+        function onEvents(events, version) {
             const freshEvents = events.filter((event) => {
-                const version = eventVersion(event);
-                return version === 0 || version > versionRef;
+                const v = typeof event.version === "number" ? event.version : 0;
+                return v === 0 || v > subscriberVersion;
             });
             if (freshEvents.some((e) => e.source === "screen-refresh")) {
                 setKey((k) => k + 1);
             }
-            const maxEventVersion = freshEvents.reduce((max, event) => Math.max(max, eventVersion(event)), 0);
-            versionRef = Math.max(versionRef, version ?? 0, maxEventVersion);
-        }
-        function closeEvents() {
-            if (!eventSource)
-                return;
-            eventSource.close();
-            eventSource = null;
-            sseConnected = false;
+            const maxEventVersion = freshEvents.reduce((max, event) => Math.max(max, typeof event.version === "number" ? event.version : 0), 0);
+            subscriberVersion = Math.max(subscriberVersion, version ?? 0, maxEventVersion);
         }
-        function connectEvents() {
-            if (stopped ||
-                !sseUrl ||
-                eventSource ||
-                typeof EventSource === "undefined" ||
-                (pauseWhenHidden && isDocumentHidden())) {
-                return;
-            }
-            const source = new EventSource(sseUrl);
-            eventSource = source;
-            source.onopen = () => {
-                sseConnected = true;
-                schedulePoll();
-            };
-            source.onerror = () => {
-                sseConnected = false;
-                // When the browser gives up permanently (HTTP error → readyState
-                // CLOSED), it won't auto-reconnect. Drop the ref so a later
-                // connectEvents() (on focus/visibility) can establish a fresh stream;
-                // otherwise the non-null closed `eventSource` blocks reconnection and
-                // we'd be stuck on polling-only forever.
-                if (source.readyState === EventSource.CLOSED) {
-                    eventSource = null;
-                }
-                schedulePoll();
-            };
-            source.onmessage = (message) => {
-                try {
-                    const payload = JSON.parse(message.data);
-                    const events = normalizeEventPayload(payload);
-                    const version = typeof payload?.version === "number" ? payload.version : undefined;
-                    applyEvents(events, version);
-                }
-                catch {
-                    // Polling will catch missed screen-refresh events.
-                }
-            };
-        }
-        async function poll() {
-            if (stopped || inFlight)
-                return;
-            inFlight = true;
-            try {
-                const data = await fetchPollJson(pollUrl, versionRef, interval);
-                if (stopped)
-                    return;
-                applyEvents(data.events ?? [], data.version);
-            }
-            catch (err) {
-                if (stopped)
-                    return;
-                if (isAuthFailure(err)) {
-                    authFailureUntil = Date.now() + POLL_AUTH_FAILURE_COOLDOWN_MS;
-                    closeEvents();
-                }
-                // Network error — retry on next interval.
-            }
-            finally {
-                inFlight = false;
-                schedulePoll();
-            }
-        }
-        function pollNow() {
-            if (pauseWhenHidden && isDocumentHidden()) {
-                return;
-            }
-            if (authFailureDelayMs() > 0) {
-                schedulePoll();
-                return;
-            }
-            if (timer) {
-                clearTimeout(timer);
-                timer = null;
-            }
-            connectEvents();
-            void poll();
-        }
-        function handleVisibilityChange() {
-            if (document.visibilityState === "visible") {
-                connectEvents();
-                pollNow();
-            }
-            else if (pauseWhenHidden) {
-                closeEvents();
-                if (timer) {
-                    clearTimeout(timer);
-                    timer = null;
-                }
-            }
-        }
-        if (!pauseWhenHidden || !isDocumentHidden()) {
-            connectEvents();
-            void poll();
-        }
-        window.addEventListener("focus", pollNow);
-        document.addEventListener("visibilitychange", handleVisibilityChange);
+        const transport = getOrCreateTransport(pollUrl, sseUrl);
+        transport.add(id, {
+            onEvents,
+            pauseWhenHidden,
+            interval,
+            fallbackInterval,
+        });
         return () => {
-            stopped = true;
-            closeEvents();
-            if (timer)
-                clearTimeout(timer);
-            window.removeEventListener("focus", pollNow);
-            document.removeEventListener("visibilitychange", handleVisibilityChange);
+            transport.remove(id);
+            if (!transport["subscribers"].size) {
+                releaseTransport(pollUrl, sseUrl);
+            }
         };
     }, [pollUrl, sseUrl, interval, fallbackInterval, pauseWhenHidden]);
     return key;