wenay-react2 1.0.32 → 1.0.33

package/lib/common/src/hooks/useReplay.d.ts

@@ -2,6 +2,7 @@ import { ObserveAll2, Replay } from "wenay-common2";
 type StorePatch = ObserveAll2.StorePatch;
 type ReplayEvent<Z extends any[]> = Replay.ReplayEvent<Z>;
 type ReplayRemote<Z extends any[]> = Replay.ReplayRemote<Z>;
+type StaleInfo = Replay.StaleInfo;
 export type UseReplaySubscribeOptions = {
     /** Start position for the first subscription: journal tail after this seq; omit = keyframe. */
     since?: number;
@@ -11,13 +12,30 @@ export type UseReplaySubscribeOptions = {
     enabled?: boolean;
     onSeq?: (seq: number) => void;
     onError?: (e: unknown) => void;
+    /**
+     * Producer-freshness watchdog (detection lives in wenay-common2): no event with a fresh
+     * producer ts for staleMs -> `stale` flips true, flips back on resume. Omitted = zero cost
+     * (no watchdog, no extra state updates). Changing staleMs resubscribes (reconnects by tail
+     * under keepSeq, so it is cheap).
+     */
+    staleMs?: number;
+    /** Edge-triggered mirror of common2's onStale (fresh<->stale transitions only). Goes through a ref — a new identity does not resubscribe. */
+    onStale?: (info: StaleInfo) => void;
 };
 export type ReplaySubscribeController = {
     /** Keyframe/tail catch-up finished, events are live from here. */
     readonly ready: boolean;
     readonly error: unknown;
+    /**
+     * Line is stale by the staleMs watchdog. React state, but it updates ONLY on fresh<->stale
+     * transitions — a high-frequency line causes zero extra renders while fresh.
+     * Always false without staleMs.
+     */
+    readonly stale: boolean;
     /** Last seen seq (reconnect point). Getter — reading it does not re-render. */
     seq(): number;
+    /** Producer ts of the last delivered event (0 before the first delivery). Getter — reading it does not re-render. */
+    lastTs(): number;
     /** Drop and re-create the subscription. since omitted = continue by keepSeq rules; a number = explicit position. */
     restart(since?: number): void;
 };

package/lib/common/src/hooks/useReplay.js

@@ -11,7 +11,9 @@ import { ObserveAll2, Replay } from "wenay-common2";
  *   (ref/store/canvas). If the consumer state resets on resubscribe, pass {keepSeq: false};
  * - a FULL unmount loses the hook's refs: to reconnect by tail after a remount, keep the position
  *   outside via onSeq and pass it back as `since` (see the QA card for the pattern);
- * - a different `remote` identity always starts from scratch (seq from another line is meaningless).
+ * - a different `remote` identity always starts from scratch (seq from another line is meaningless);
+ * - freshness (staleMs/onStale, controller.stale/lastTs()) is detected by wenay-common2;
+ *   the hooks only mirror the fresh<->stale edges into React state.
  *
  * Server-side parts of the stack (conflateReplay, archiveReplay) are per-connection/per-process
  * and intentionally have no hooks here.
@@ -28,14 +30,15 @@ function useLatestRef(value) {
  * cb goes through a ref — a new cb identity does not resubscribe.
  */
 export function useReplaySubscribe(remote, cb, options = {}) {
-    const { since, keepSeq = true, enabled = true, onSeq, onError } = options;
+    const { since, keepSeq = true, enabled = true, onSeq, onError, staleMs, onStale } = options;
     const cbRef = useLatestRef(cb);
-    const hooksRef = useLatestRef({ onSeq, onError });
+    const hooksRef = useLatestRef({ onSeq, onError, onStale });
     const seqRef = useRef(since);
     const subRef = useRef(null);
     const lastRemoteRef = useRef(undefined);
     const [ready, setReady] = useState(false);
     const [error, setError] = useState(null);
+    const [stale, setStale] = useState(false);
     const [epoch, setEpoch] = useState(0);
     useEffect(() => {
         if (!remote || !enabled)
@@ -46,6 +49,10 @@ export function useReplaySubscribe(remote, cb, options = {}) {
         let alive = true;
         setReady(false);
         setError(null);
+        // stale is NOT reset here: it re-syncs from common2 after the first delivery (a stale
+        // keyframe must show stale from the start, not flicker through false on resubscribe)
+        if (staleMs === undefined)
+            setStale(false);
         const off = Replay.replaySubscribe(remote, (...event) => cbRef.current(...event), {
             since: seqRef.current,
             onSeq: seq => {
@@ -57,10 +64,23 @@ export function useReplaySubscribe(remote, cb, options = {}) {
                     setError(e);
                 hooksRef.current.onError?.(e);
             },
+            ...(staleMs !== undefined ? {
+                staleMs,
+                onStale: (info) => {
+                    if (alive)
+                        setStale(info.stale);
+                    hooksRef.current.onStale?.(info);
+                },
+            } : null),
         });
         subRef.current = off;
-        off.ready.then(() => { if (alive)
-            setReady(true); }, e => { if (alive)
+        off.ready.then(() => {
+            if (!alive)
+                return;
+            setReady(true);
+            if (staleMs !== undefined)
+                setStale(off.isStale()); // fresh line after a stale one: no edge from common2, sync by hand
+        }, e => { if (alive)
             setError(e); });
         return () => {
             alive = false;
@@ -69,16 +89,18 @@ export function useReplaySubscribe(remote, cb, options = {}) {
             if (!keepSeq)
                 seqRef.current = since;
         };
-        // keepSeq/since are start-position config, not subscription identity — no resubscribe on change
+        // keepSeq/since are start-position config, not subscription identity — no resubscribe on change;
+        // staleMs is subscribe-time config in common2, so changing it resubscribes
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [remote, enabled, epoch]);
+    }, [remote, enabled, epoch, staleMs]);
     const seq = useCallback(() => subRef.current?.seq() ?? seqRef.current ?? -1, []);
+    const lastTs = useCallback(() => subRef.current?.lastTs() ?? 0, []);
     const restart = useCallback((at) => {
         if (at !== undefined)
             seqRef.current = at;
         setEpoch(v => v + 1);
     }, []);
-    return useMemo(() => ({ ready, error, seq, restart }), [ready, error, seq, restart]);
+    return useMemo(() => ({ ready, error, stale, seq, lastTs, restart }), [ready, error, stale, seq, lastTs, restart]);
 }
 /**
  * Sync an existing mirror store from a store replay line (`ObserveAll2.exposeStoreReplay(...).api.replay`).
@@ -87,13 +109,14 @@ export function useReplaySubscribe(remote, cb, options = {}) {
  * (useStoreNode/useStoreSelect).
  */
 export function useStoreReplaySync(store, remote, options = {}) {
-    const { since, keepSeq = true, enabled = true, onSeq, onError } = options;
-    const hooksRef = useLatestRef({ onSeq, onError });
+    const { since, keepSeq = true, enabled = true, onSeq, onError, staleMs, onStale } = options;
+    const hooksRef = useLatestRef({ onSeq, onError, onStale });
     const seqRef = useRef(since);
     const subRef = useRef(null);
     const lastRemoteRef = useRef(undefined);
     const [ready, setReady] = useState(false);
     const [error, setError] = useState(null);
+    const [stale, setStale] = useState(false);
     const [epoch, setEpoch] = useState(0);
     useEffect(() => {
         if (!store || !remote || !enabled)
@@ -104,6 +127,8 @@ export function useStoreReplaySync(store, remote, options = {}) {
         let alive = true;
         setReady(false);
         setError(null);
+        if (staleMs === undefined)
+            setStale(false); // see useReplaySubscribe: stale re-syncs from common2, no reset-to-false flicker
         const off = ObserveAll2.syncStoreReplay(store, remote, {
             since: seqRef.current,
             onSeq: seq => {
@@ -115,10 +140,23 @@ export function useStoreReplaySync(store, remote, options = {}) {
                     setError(e);
                 hooksRef.current.onError?.(e);
             },
+            ...(staleMs !== undefined ? {
+                staleMs,
+                onStale: (info) => {
+                    if (alive)
+                        setStale(info.stale);
+                    hooksRef.current.onStale?.(info);
+                },
+            } : null),
         });
         subRef.current = off;
-        off.ready.then(() => { if (alive)
-            setReady(true); }, e => { if (alive)
+        off.ready.then(() => {
+            if (!alive)
+                return;
+            setReady(true);
+            if (staleMs !== undefined)
+                setStale(off.isStale());
+        }, e => { if (alive)
             setError(e); });
         return () => {
             alive = false;
@@ -128,14 +166,15 @@ export function useStoreReplaySync(store, remote, options = {}) {
                 seqRef.current = since;
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [store, remote, enabled, epoch]);
+    }, [store, remote, enabled, epoch, staleMs]);
     const seq = useCallback(() => subRef.current?.seq() ?? seqRef.current ?? -1, []);
+    const lastTs = useCallback(() => subRef.current?.lastTs() ?? 0, []);
     const restart = useCallback((at) => {
         if (at !== undefined)
             seqRef.current = at;
         setEpoch(v => v + 1);
     }, []);
-    return useMemo(() => ({ ready, error, seq, restart }), [ready, error, seq, restart]);
+    return useMemo(() => ({ ready, error, stale, seq, lastTs, restart }), [ready, error, stale, seq, lastTs, restart]);
 }
 /**
  * Convenience: create a local mirror store and keep it synced from a store replay line.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wenay-react2",
-  "version": "1.0.32",
+  "version": "1.0.33",
   "description": "Common react",
   "strict": true,
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-rnd": "^10.5.3",
-    "wenay-common2": "^1.0.56"
+    "wenay-common2": "^1.0.57"
   },
   "peerDependencies": {
     "react": "^19.2.0",