@syncular/react 0.3.0 → 0.4.0

package/dist/use-raw-sql.js

@@ -157,23 +157,35 @@ export function useRawSql(sql, params, options) {
         };
     }, [client, key, enabled, tick]);
     // Subscribe once per client/enabled/query identity; a matching event asks the
-    // scheduler for a run (coalesced). `key`/`scopeKeysKey` re-key the sub.
+    // scheduler for a run (coalesced). `key`/`scopeKeysKey` re-key the sub. The
+    // scheduler is read from the ref AT EVENT TIME (never captured at effect
+    // setup): the lifecycle effect below may replace it on a remount, and a
+    // captured disposed instance would swallow every schedule() silently.
     // biome-ignore lint/correctness/useExhaustiveDependencies: key/scopeKeysKey re-key the subscription intentionally
     useEffect(() => {
         if (!enabled)
             return;
-        const scheduler = schedulerRef.current;
         const unsubscribe = client.onInvalidate((event) => {
             if (eventMatches(event, depTablesRef.current, scopeKeysRef.current)) {
-                scheduler?.schedule();
+                schedulerRef.current?.schedule();
             }
         });
         return unsubscribe;
     }, [client, enabled, key, scopeKeysKey]);
-    // Dispose the scheduler when the hook unmounts (drop any pending frame).
+    // Scheduler lifecycle. Under StrictMode (and any future fiber remount)
+    // React runs mount → cleanup → mount on the SAME hook instance: the cleanup
+    // disposes the scheduler, so the setup must RE-CREATE it — the render-time
+    // lazy init above never runs again (the ref is non-undefined), and a
+    // disposed scheduler turns every later invalidation into a silent no-op
+    // that freezes the live query forever.
     useEffect(() => {
-        const scheduler = schedulerRef.current;
-        return () => scheduler?.dispose();
+        if (schedulerRef.current === undefined) {
+            schedulerRef.current = new FrameScheduler(() => runRef.current?.());
+        }
+        return () => {
+            schedulerRef.current?.dispose();
+            schedulerRef.current = undefined;
+        };
     }, []);
     return { rows, isLoading, error, refresh };
 }

package/dist/use-window.d.ts

@@ -8,20 +8,26 @@
  *
  * - `setWindow(units)` swaps the live set (added units bootstrap via the
  *   image lane; removed units are evicted, fused with unsubscription).
- * - `units` is the current windowed-in set (re-read on mount and whenever
- *   the base's table is invalidated — so a deferred eviction draining, or
- *   a re-entry bootstrapping, updates the verdict).
- * - `isComplete(unit)` is the per-value verdict: a live query whose scope
- *   footprint includes a non-`isComplete` unit is a **window miss** — widen
- *   or show partial, never claim complete.
+ * - `units` is the current windowed-in set, `pending` the subset whose
+ *   bootstrap has not yet landed (re-read on mount and whenever the base's
+ *   table is invalidated — a deferred eviction draining, a re-entry
+ *   bootstrapping, or a bootstrap completing all update the verdict).
+ * - `isComplete(unit)` is the per-value verdict: registered AND
+ *   bootstrap-complete. A live query whose scope footprint includes a
+ *   non-`isComplete` unit is a **window miss or still loading** — widen,
+ *   wait, or show partial, never claim complete. Between `setWindow` and
+ *   the unit's bootstrap landing the verdict is `false` (the local replica
+ *   is empty or partial there — never a false "empty" render).
  */
-import type { WindowBase } from '@syncular/client';
+import { type WindowBase } from '@syncular/client';
 export interface UseWindowResult {
     /** The scope values currently windowed-in for this base. */
     readonly units: readonly string[];
+    /** Registered units whose bootstrap has not yet completed (§4.8). */
+    readonly pending: readonly string[];
     /** Set the live units (widen/shrink diff, §4.8). */
     readonly setWindow: (units: readonly string[]) => Promise<void>;
-    /** True iff `unit` is windowed-in (answerable in full locally, I3). */
+    /** True iff `unit` is windowed-in AND bootstrapped (answerable, I3). */
     readonly isComplete: (unit: string) => boolean;
 }
 export declare function useWindow(base: WindowBase): UseWindowResult;

package/dist/use-window.js

@@ -1,8 +1,31 @@
+/**
+ * `useWindow(base)` — the windowed-sync surface for a component
+ * (SPEC.md §4.8 / DESIGN-eviction.md W1, I3). It manages the live window
+ * units for a base and exposes the **completeness oracle**: which scope
+ * values are held locally in full, so a consumer can render "this data may
+ * be partial" honestly instead of silently serving a partial replica as
+ * complete.
+ *
+ * - `setWindow(units)` swaps the live set (added units bootstrap via the
+ *   image lane; removed units are evicted, fused with unsubscription).
+ * - `units` is the current windowed-in set, `pending` the subset whose
+ *   bootstrap has not yet landed (re-read on mount and whenever the base's
+ *   table is invalidated — a deferred eviction draining, a re-entry
+ *   bootstrapping, or a bootstrap completing all update the verdict).
+ * - `isComplete(unit)` is the per-value verdict: registered AND
+ *   bootstrap-complete. A live query whose scope footprint includes a
+ *   non-`isComplete` unit is a **window miss or still loading** — widen,
+ *   wait, or show partial, never claim complete. Between `setWindow` and
+ *   the unit's bootstrap landing the verdict is `false` (the local replica
+ *   is empty or partial there — never a false "empty" render).
+ */
+import { windowComplete, } from '@syncular/client';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useSyncClient } from './use-client.js';
+const EMPTY = { units: [], pending: [] };
 export function useWindow(base) {
     const client = useSyncClient();
-    const [units, setUnits] = useState([]);
+    const [state, setState] = useState(EMPTY);
     // A stable key so the effects re-run only when the base identity changes,
     // not on every render's fresh object. The latest `base` is read via a ref
     // inside the closures (the useRawSql pattern), so the dep list stays on
@@ -17,9 +40,9 @@ export function useWindow(base) {
         let cancelled = false;
         const read = () => {
             Promise.resolve(client.windowState(baseRef.current))
-                .then((state) => {
+                .then((next) => {
                 if (!cancelled)
-                    setUnits(state.units);
+                    setState(next);
             })
                 .catch(() => {
                 /* transient — the next invalidation re-reads */
@@ -40,10 +63,17 @@ export function useWindow(base) {
     const setWindow = useCallback((next) => {
         const result = Promise.resolve(client.setWindow(baseRef.current, next));
         // Optimistically reflect the new set; the invalidation-driven re-read
-        // reconciles against the registry (e.g. a pinned unit lingering).
-        setUnits(next);
+        // reconciles against the registry (e.g. a pinned unit lingering). The
+        // optimistic update MUST NOT claim completeness: a unit stays (or
+        // becomes) pending unless the previous snapshot already had it
+        // complete — entering units are mid-bootstrap until the re-read
+        // confirms otherwise (§4.8: registration ≠ completeness).
+        setState((prev) => ({
+            units: next,
+            pending: next.filter((unit) => !windowComplete(prev, unit)),
+        }));
         return result;
     }, [client]);
-    const isComplete = useCallback((unit) => units.includes(unit), [units]);
-    return { units, setWindow, isComplete };
+    const isComplete = useCallback((unit) => windowComplete(state, unit), [state]);
+    return { units: state.units, pending: state.pending, setWindow, isComplete };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/react",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "React hooks for Syncular offline-first sync",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,15 +48,15 @@
     "test": "bun test --preload ./test/setup.ts"
   },
   "dependencies": {
-    "@syncular/client": "0.2.1"
+    "@syncular/client": "0.3.1"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^15.11.0",
-    "@syncular/core": "0.2.1",
-    "@syncular/server": "0.2.1",
+    "@syncular/core": "0.3.1",
+    "@syncular/server": "0.3.1",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
     "react": "^18.3.1",

package/src/use-raw-sql.ts

@@ -200,23 +200,35 @@ export function useRawSql<Row = SqlRow>(
   }, [client, key, enabled, tick]);
 
   // Subscribe once per client/enabled/query identity; a matching event asks the
-  // scheduler for a run (coalesced). `key`/`scopeKeysKey` re-key the sub.
+  // scheduler for a run (coalesced). `key`/`scopeKeysKey` re-key the sub. The
+  // scheduler is read from the ref AT EVENT TIME (never captured at effect
+  // setup): the lifecycle effect below may replace it on a remount, and a
+  // captured disposed instance would swallow every schedule() silently.
   // biome-ignore lint/correctness/useExhaustiveDependencies: key/scopeKeysKey re-key the subscription intentionally
   useEffect(() => {
     if (!enabled) return;
-    const scheduler = schedulerRef.current;
     const unsubscribe = client.onInvalidate((event) => {
       if (eventMatches(event, depTablesRef.current, scopeKeysRef.current)) {
-        scheduler?.schedule();
+        schedulerRef.current?.schedule();
       }
     });
     return unsubscribe;
   }, [client, enabled, key, scopeKeysKey]);
 
-  // Dispose the scheduler when the hook unmounts (drop any pending frame).
+  // Scheduler lifecycle. Under StrictMode (and any future fiber remount)
+  // React runs mount → cleanup → mount on the SAME hook instance: the cleanup
+  // disposes the scheduler, so the setup must RE-CREATE it — the render-time
+  // lazy init above never runs again (the ref is non-undefined), and a
+  // disposed scheduler turns every later invalidation into a silent no-op
+  // that freezes the live query forever.
   useEffect(() => {
-    const scheduler = schedulerRef.current;
-    return () => scheduler?.dispose();
+    if (schedulerRef.current === undefined) {
+      schedulerRef.current = new FrameScheduler(() => runRef.current?.());
+    }
+    return () => {
+      schedulerRef.current?.dispose();
+      schedulerRef.current = undefined;
+    };
   }, []);
 
   return { rows, isLoading, error, refresh };

package/src/use-window.ts

@@ -8,29 +8,41 @@
  *
  * - `setWindow(units)` swaps the live set (added units bootstrap via the
  *   image lane; removed units are evicted, fused with unsubscription).
- * - `units` is the current windowed-in set (re-read on mount and whenever
- *   the base's table is invalidated — so a deferred eviction draining, or
- *   a re-entry bootstrapping, updates the verdict).
- * - `isComplete(unit)` is the per-value verdict: a live query whose scope
- *   footprint includes a non-`isComplete` unit is a **window miss** — widen
- *   or show partial, never claim complete.
+ * - `units` is the current windowed-in set, `pending` the subset whose
+ *   bootstrap has not yet landed (re-read on mount and whenever the base's
+ *   table is invalidated — a deferred eviction draining, a re-entry
+ *   bootstrapping, or a bootstrap completing all update the verdict).
+ * - `isComplete(unit)` is the per-value verdict: registered AND
+ *   bootstrap-complete. A live query whose scope footprint includes a
+ *   non-`isComplete` unit is a **window miss or still loading** — widen,
+ *   wait, or show partial, never claim complete. Between `setWindow` and
+ *   the unit's bootstrap landing the verdict is `false` (the local replica
+ *   is empty or partial there — never a false "empty" render).
  */
-import type { WindowBase } from '@syncular/client';
+import {
+  type WindowBase,
+  type WindowState,
+  windowComplete,
+} from '@syncular/client';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useSyncClient } from './use-client';
 
 export interface UseWindowResult {
   /** The scope values currently windowed-in for this base. */
   readonly units: readonly string[];
+  /** Registered units whose bootstrap has not yet completed (§4.8). */
+  readonly pending: readonly string[];
   /** Set the live units (widen/shrink diff, §4.8). */
   readonly setWindow: (units: readonly string[]) => Promise<void>;
-  /** True iff `unit` is windowed-in (answerable in full locally, I3). */
+  /** True iff `unit` is windowed-in AND bootstrapped (answerable, I3). */
   readonly isComplete: (unit: string) => boolean;
 }
 
+const EMPTY: WindowState = { units: [], pending: [] };
+
 export function useWindow(base: WindowBase): UseWindowResult {
   const client = useSyncClient();
-  const [units, setUnits] = useState<readonly string[]>([]);
+  const [state, setState] = useState<WindowState>(EMPTY);
 
   // A stable key so the effects re-run only when the base identity changes,
   // not on every render's fresh object. The latest `base` is read via a ref
@@ -49,8 +61,8 @@ export function useWindow(base: WindowBase): UseWindowResult {
     let cancelled = false;
     const read = () => {
       Promise.resolve(client.windowState(baseRef.current))
-        .then((state) => {
-          if (!cancelled) setUnits(state.units);
+        .then((next) => {
+          if (!cancelled) setState(next);
         })
         .catch(() => {
           /* transient — the next invalidation re-reads */
@@ -72,17 +84,24 @@ export function useWindow(base: WindowBase): UseWindowResult {
     (next: readonly string[]) => {
       const result = Promise.resolve(client.setWindow(baseRef.current, next));
       // Optimistically reflect the new set; the invalidation-driven re-read
-      // reconciles against the registry (e.g. a pinned unit lingering).
-      setUnits(next);
+      // reconciles against the registry (e.g. a pinned unit lingering). The
+      // optimistic update MUST NOT claim completeness: a unit stays (or
+      // becomes) pending unless the previous snapshot already had it
+      // complete — entering units are mid-bootstrap until the re-read
+      // confirms otherwise (§4.8: registration ≠ completeness).
+      setState((prev) => ({
+        units: next,
+        pending: next.filter((unit) => !windowComplete(prev, unit)),
+      }));
       return result;
     },
     [client],
   );
 
   const isComplete = useCallback(
-    (unit: string) => units.includes(unit),
-    [units],
+    (unit: string) => windowComplete(state, unit),
+    [state],
   );
 
-  return { units, setWindow, isComplete };
+  return { units: state.units, pending: state.pending, setWindow, isComplete };
 }