@spooky-sync/client-solid 0.0.1-canary.27 → 0.0.1-canary.270

package/src/lib/use-download-file.ts

@@ -1,10 +1,31 @@
 import { createSignal, createEffect, onCleanup, type Accessor } from 'solid-js';
 import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
+import type { BlobUrlLease } from '@spooky-sync/core';
 import type { SyncedDb } from '../index';
 import { useDb } from './context';
 
 export interface UseDownloadFileOptions {
+  /**
+   * Master switch, default `true`. `false` gives every hook instance its own
+   * private object URL fetched fresh from the bucket and revoked on unmount —
+   * no sharing, no persistence, no reuse.
+   */
   cache?: boolean;
+  /**
+   * Keep the bytes in OPFS so they survive a reload and are available offline.
+   * Default `true`. Turn off for one-shot or sensitive files; the in-tab object
+   * URL is still shared between components rendering the same path.
+   */
+  persist?: boolean;
+  /** Exempt this file from pressure eviction. Pinned bytes never expire. */
+  pin?: boolean;
+  /**
+   * `'never'` (default) treats a bucket path as immutable, which is how paths
+   * are written (`crypto.randomUUID() + ext`). `'head'` spends a remote `head()`
+   * to compare sizes before trusting the cached copy — for paths the app
+   * overwrites in place.
+   */
+  revalidate?: 'never' | 'head';
 }
 
 export interface UseDownloadFileResult {
@@ -14,28 +35,6 @@ export interface UseDownloadFileResult {
   refetch: () => void;
 }
 
-interface CacheEntry {
-  url: string;
-  refCount: number;
-}
-
-const downloadCache = new Map<string, CacheEntry>();
-const inflightRequests = new Map<string, Promise<string | null>>();
-
-function cacheKey(bucket: string, path: string): string {
-  return `${bucket}:${path}`;
-}
-
-function releaseEntry(key: string): void {
-  const entry = downloadCache.get(key);
-  if (!entry) return;
-  entry.refCount--;
-  if (entry.refCount <= 0) {
-    URL.revokeObjectURL(entry.url);
-    downloadCache.delete(key);
-  }
-}
-
 export function useDownloadFile<S extends SchemaStructure>(
   bucketName: BucketNames<S>,
   path: Accessor<string | null | undefined>,
@@ -76,69 +75,19 @@ export function useDownloadFile<S extends SchemaStructure>(
   const [isLoading, setIsLoading] = createSignal(false);
   const [error, setError] = createSignal<Error | null>(null);
 
-  let currentKey: string | null = null;
+  // Exactly one of these is held at a time: a refcounted lease on the shared
+  // cache entry, or a private URL this instance minted and must revoke itself.
+  let lease: BlobUrlLease | null = null;
   let privateUrl: string | null = null;
-  let refetchTrigger: () => void;
+
   const [refetchSignal, setRefetchSignal] = createSignal(0);
-  refetchTrigger = () => setRefetchSignal((n) => n + 1);
-
-  async function doDownload(key: string, filePath: string): Promise<string | null> {
-    if (useCache) {
-      // Check cache
-      const cached = downloadCache.get(key);
-      if (cached) {
-        cached.refCount++;
-        currentKey = key;
-        return cached.url;
-      }
-
-      // Check inflight
-      const inflight = inflightRequests.get(key);
-      if (inflight) {
-        const result = await inflight;
-        if (result) {
-          const entry = downloadCache.get(key);
-          if (entry) {
-            entry.refCount++;
-            currentKey = key;
-          }
-        }
-        return result;
-      }
-
-      // Start new download
-      const promise = (async () => {
-        const content = await db.bucket(bucketName).get(filePath);
-        if (!content) return null;
-        const objectUrl = URL.createObjectURL(new Blob([content as BlobPart]));
-        downloadCache.set(key, { url: objectUrl, refCount: 1 });
-        return objectUrl;
-      })();
-
-      inflightRequests.set(key, promise);
-      try {
-        const result = await promise;
-        currentKey = key;
-        return result;
-      } finally {
-        inflightRequests.delete(key);
-      }
-    } else {
-      // No caching — private URL per instance
-      const content = await db.bucket(bucketName).get(filePath);
-      if (!content) return null;
-      const objectUrl = URL.createObjectURL(new Blob([content as BlobPart]));
-      privateUrl = objectUrl;
-      return objectUrl;
-    }
-  }
+  /** Consumed by the next effect run, so `refetch()` bypasses every layer once. */
+  let reloadOnce = false;
 
-  function releaseCurrentEntry() {
-    if (useCache && currentKey) {
-      releaseEntry(currentKey);
-      currentKey = null;
-    }
-    if (!useCache && privateUrl) {
+  function releaseCurrent() {
+    lease?.release();
+    lease = null;
+    if (privateUrl) {
       URL.revokeObjectURL(privateUrl);
       privateUrl = null;
     }
@@ -149,8 +98,7 @@ export function useDownloadFile<S extends SchemaStructure>(
     // Subscribe to refetch signal so effect re-runs
     refetchSignal();
 
-    // Release previous entry
-    releaseCurrentEntry();
+    releaseCurrent();
 
     if (!filePath) {
       setUrl(null);
@@ -159,31 +107,47 @@ export function useDownloadFile<S extends SchemaStructure>(
       return;
     }
 
-    const key = cacheKey(bucketName as string, filePath);
-
-    // Synchronous cache hit
-    if (useCache) {
-      const cached = downloadCache.get(key);
-      if (cached) {
-        cached.refCount++;
-        currentKey = key;
-        setUrl(cached.url);
-        setIsLoading(false);
-        setError(null);
-        return;
-      }
-    }
+    const reload = reloadOnce;
+    reloadOnce = false;
 
     let cancelled = false;
     setIsLoading(true);
     setError(null);
 
-    doDownload(key, filePath).then(
+    const bucket = db.bucket(bucketName);
+    const resolve = useCache
+      ? bucket
+          .url(filePath, {
+            persist: options.persist !== false,
+            pin: options.pin,
+            revalidate: options.revalidate,
+            reload,
+          })
+          .then((acquired) => {
+            if (!acquired) return null;
+            if (cancelled) {
+              // Unmounted or the path changed mid-flight — hand the reference
+              // straight back, or the entry never drops to zero and its object
+              // URL leaks for the life of the tab.
+              acquired.release();
+              return null;
+            }
+            lease = acquired;
+            return acquired.url;
+          })
+      : bucket.read(filePath, { persist: false, reload: true }).then((blob) => {
+          if (!blob || cancelled) return null;
+          privateUrl = URL.createObjectURL(blob);
+          return privateUrl;
+        });
+
+    resolve.then(
       (result) => {
         if (!cancelled) {
           setUrl(result);
           setIsLoading(false);
         }
+        return undefined;
       },
       (err) => {
         if (!cancelled) {
@@ -199,20 +163,12 @@ export function useDownloadFile<S extends SchemaStructure>(
   });
 
   onCleanup(() => {
-    releaseCurrentEntry();
+    releaseCurrent();
   });
 
   const refetch = () => {
-    // Evict current entry from cache before re-triggering
-    if (useCache && currentKey) {
-      const entry = downloadCache.get(currentKey);
-      if (entry) {
-        URL.revokeObjectURL(entry.url);
-        downloadCache.delete(currentKey);
-      }
-      currentKey = null;
-    }
-    refetchTrigger();
+    reloadOnce = true;
+    setRefetchSignal((n) => n + 1);
   };
 
   return { url, isLoading, error, refetch };

package/src/lib/use-feature-flag.ts

@@ -0,0 +1,50 @@
+import { createSignal, onCleanup, type Accessor } from 'solid-js';
+import { useDb } from './context';
+import type { FeatureFlagOptions } from '@spooky-sync/core';
+
+export interface UseFeatureFlag {
+  variant: Accessor<string | undefined>;
+  payload: Accessor<unknown | undefined>;
+  enabled: Accessor<boolean>;
+}
+
+/**
+ * Subscribe to a feature flag for the currently authenticated user.
+ *
+ * Returns three Solid accessors that update reactively whenever the
+ * server-materialized assignment in `_00_user_feature` changes. Backed by
+ * the same SSP + sync pipeline that powers `useQuery`, so toggling a flag
+ * via `spky flag enable <key>` propagates to the UI without a refresh.
+ *
+ * `enabled()` is `true` when the resolved variant exists and is not 'off'.
+ * For multi-variant flags, prefer `variant()` directly.
+ */
+export function useFeatureFlag(
+  key: string,
+  options?: FeatureFlagOptions,
+): UseFeatureFlag {
+  const db = useDb();
+  const handle = db.getSp00ky().feature(key, options);
+
+  const [variant, setVariant] = createSignal<string | undefined>(handle.variant());
+  const [payload, setPayload] = createSignal<unknown | undefined>(handle.payload());
+
+  const unsub = handle.subscribe((s) => {
+    setVariant(s.variant ?? options?.fallback);
+    setPayload(s.payload);
+  });
+
+  onCleanup(() => {
+    unsub();
+    handle.close();
+  });
+
+  return {
+    variant,
+    payload,
+    enabled: () => {
+      const v = variant();
+      return v !== undefined && v !== 'off';
+    },
+  };
+}

package/src/lib/use-file-upload.ts

@@ -1,6 +1,7 @@
 import { createSignal, onCleanup } from 'solid-js';
 import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
 import { fileToUint8Array } from '@spooky-sync/core';
+import type { BucketPutOptions, BucketPutResult } from '@spooky-sync/core';
 import type { SyncedDb } from '../index';
 import { useDb } from './context';
 
@@ -8,7 +9,7 @@ export interface FileUploadResult {
   isUploading: () => boolean;
   error: () => Error | null;
   clearError: () => void;
-  upload: (path: string, file: File | Blob) => Promise<void>;
+  upload: (path: string, file: File | Blob, options?: BucketPutOptions) => Promise<BucketPutResult | void>;
   download: (path: string) => Promise<string | null>;
   remove: (path: string) => Promise<void>;
   exists: (path: string) => Promise<boolean>;
@@ -33,6 +34,7 @@ export function useFileUpload<S extends SchemaStructure>(
     bucketName = dbOrBucketName as BucketNames<S>;
   } else {
     db = dbOrBucketName as SyncedDb<S>;
+    // oxlint-disable-next-line no-non-null-assertion
     bucketName = maybeBucketName!;
   }
 
@@ -52,7 +54,7 @@ export function useFileUpload<S extends SchemaStructure>(
     const config = db.getBucketConfig(bucketName as string);
     if (!config) return;
 
-    if (config.maxSize != null && file.size > config.maxSize) {
+    if (config.maxSize !== null && config.maxSize !== undefined && file.size > config.maxSize) {
       const maxMB = (config.maxSize / (1024 * 1024)).toFixed(1);
       throw new Error(`File exceeds maximum size of ${maxMB} MB.`);
     }
@@ -70,7 +72,11 @@ export function useFileUpload<S extends SchemaStructure>(
     }
   };
 
-  const upload = async (path: string, file: File | Blob): Promise<void> => {
+  const upload = async (
+    path: string,
+    file: File | Blob,
+    options?: BucketPutOptions
+  ): Promise<BucketPutResult | void> => {
     setError(null);
     try {
       validate(file);
@@ -82,7 +88,7 @@ export function useFileUpload<S extends SchemaStructure>(
     setIsUploading(true);
     try {
       const bytes = await fileToUint8Array(file);
-      await db.bucket(bucketName).put(path, bytes);
+      return await db.bucket(bucketName).put(path, bytes, options);
     } catch (e) {
       setError(e instanceof Error ? e : new Error(String(e)));
     } finally {

package/src/lib/use-impersonation.ts

@@ -0,0 +1,44 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from 'solid-js';
+import { useDb } from './context';
+import type { ImpersonationInfo } from '@spooky-sync/core';
+
+export interface UseImpersonationOptions {
+  /**
+   * This component renders the app's own impersonation banner. Required with
+   * `impersonationBanner: { mode: 'custom' }`: it acknowledges the banner, so
+   * the client does not fall back to its built-in one.
+   */
+  rendersBanner?: boolean;
+}
+
+export interface UseImpersonation {
+  /** The active impersonation, or `null`. */
+  impersonation: Accessor<ImpersonationInfo | null>;
+  isImpersonating: Accessor<boolean>;
+  /** Return to the admin session. */
+  stop: () => Promise<void>;
+}
+
+/**
+ * Observe admin impersonation (started from the DevTools). The client already
+ * shows its own warning bar with a Stop button; use this for anything extra,
+ * such as hiding actions an admin should not take on someone's behalf.
+ * Must be used within a `<Sp00kyProvider>`.
+ */
+export function useImpersonation(options: UseImpersonationOptions = {}): UseImpersonation {
+  const db = useDb();
+  const [impersonation, setImpersonation] = createSignal<ImpersonationInfo | null>(
+    db.auth.impersonation
+  );
+  onCleanup(db.auth.subscribeImpersonation(setImpersonation));
+  // Re-acknowledged per session: a new impersonation restarts the client's
+  // fallback timer, and this component is what cancels it.
+  createEffect(() => {
+    if (options.rendersBanner && impersonation()) db.acknowledgeImpersonationBanner();
+  });
+  return {
+    impersonation,
+    isImpersonating: () => impersonation() !== null,
+    stop: () => db.auth.stopImpersonating(),
+  };
+}

package/src/lib/use-query.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   ColumnSchema,
   FinalQuery,
   SchemaStructure,
@@ -6,9 +6,10 @@ import {
   QueryResult,
 } from '@spooky-sync/query-builder';
 import { createEffect, createSignal, onCleanup, useContext } from 'solid-js';
+import { createStore, reconcile } from 'solid-js/store';
 import { SyncedDb } from '..';
-import { SpookyQueryResultPromise } from '@spooky-sync/core';
-import { SpookyContext } from './context';
+import type { Sp00kyQueryResultPromise } from '@spooky-sync/core';
+import { Sp00kyContext } from './context';
 
 type QueryArg<
   S extends SchemaStructure,
@@ -17,13 +18,23 @@ type QueryArg<
   RelatedFields extends Record<string, any>,
   IsOne extends boolean,
 > =
-  | FinalQuery<S, TableName, T, RelatedFields, IsOne, SpookyQueryResultPromise>
+  | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
   | (() =>
-      | FinalQuery<S, TableName, T, RelatedFields, IsOne, SpookyQueryResultPromise>
+      | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
       | null
       | undefined);
 
-type QueryOptions = { enabled?: () => boolean };
+type QueryOptions = {
+  enabled?: () => boolean;
+  /**
+   * Tear down the query (remote `_00_query` view + local WASM view) when this
+   * hook is disposed and no other subscriber remains, instead of keeping it
+   * resident for cheap re-subscription. Use for viewport-windowed lists that
+   * mount/unmount a query per scroll window and want off-screen windows
+   * cancelled. Trade-off: scrolling back to a torn-down window re-registers it.
+   */
+  deregisterOnCleanup?: boolean;
+};
 
 // Overload: context-based (no explicit db)
 export function useQuery<
@@ -36,7 +47,13 @@ export function useQuery<
 >(
   finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>,
   options?: QueryOptions,
-): { data: () => TData | undefined; error: () => Error | undefined; isLoading: () => boolean };
+): {
+  data: () => TData | undefined;
+  error: () => Error | undefined;
+  isLoading: () => boolean;
+  isFetching: () => boolean;
+  isSettled: () => boolean;
+};
 
 // Overload: explicit db (backward-compatible)
 export function useQuery<
@@ -50,7 +67,13 @@ export function useQuery<
   db: SyncedDb<S>,
   finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>,
   options?: QueryOptions,
-): { data: () => TData | undefined; error: () => Error | undefined; isLoading: () => boolean };
+): {
+  data: () => TData | undefined;
+  error: () => Error | undefined;
+  isLoading: () => boolean;
+  isFetching: () => boolean;
+  isSettled: () => boolean;
+};
 
 // Implementation
 export function useQuery<
@@ -82,11 +105,11 @@ export function useQuery<
     options = maybeOptions;
   } else {
     // Context-based overload: useQuery(query, options?)
-    const contextDb = useContext(SpookyContext);
+    const contextDb = useContext(Sp00kyContext);
     if (!contextDb) {
       throw new Error(
-        'useQuery: No db argument provided and no SpookyContext found. ' +
-        'Either pass a SyncedDb instance or wrap your app in <SpookyProvider>.'
+        'useQuery: No db argument provided and no Sp00kyContext found. ' +
+        'Either pass a SyncedDb instance or wrap your app in <Sp00kyProvider>.'
       );
     }
     db = contextDb as SyncedDb<S>;
@@ -94,29 +117,98 @@ export function useQuery<
     options = queryOrOptions as QueryOptions | undefined;
   }
 
-  const [data, setData] = createSignal<TData | undefined>(undefined);
   const [error, setError] = createSignal<Error | undefined>(undefined);
   const [isFetched, setIsFetched] = createSignal(false);
-  const [unsubscribe, setUnsubscribe] = createSignal<(() => void) | undefined>(undefined);
+  const [isFetching, setIsFetching] = createSignal(false);
+  // Results live in a store (not a signal) so consecutive live-query emissions
+  // are merged with `reconcile`: unchanged rows keep their object identity and
+  // changed rows are mutated in place. That keeps Solid's reference-keyed `<For>`
+  // rows — and any `useQuery` subscriptions mounted inside them — alive across
+  // updates, instead of tearing every row down and re-registering its queries.
+  const [state, setState] = createStore<{ value: TData | undefined }>({ value: undefined });
+  // `reconcile` (below) merges each emission into `state.value` IN PLACE, keeping
+  // the array reference stable. That's ideal for granular per-row reactivity, but
+  // it means a *coarse* reader of `data()` — `<For each={data()}>`, or an effect
+  // that copies the whole array elsewhere (e.g. GameList's windowed store) — is
+  // NOT re-run when rows are added/removed/reordered within a same-length result
+  // (the classic case: deleting a row in a windowed list shifts the next one in,
+  // so length stays 50 and the array ref never changes). Bump a version on every
+  // emission and read it in `data()` so every consumer re-runs on any change while
+  // reconcile still preserves row identity underneath.
+  const [version, setVersion] = createSignal(0);
+  const data = () => {
+    version();
+    return state.value;
+  };
+
   let prevQueryString: string | undefined;
+  // Monotonic token for each subscription generation. Bumped whenever the query
+  // identity changes or the hook is disposed, so a slow async `initQuery`
+  // continuation can detect it was superseded and avoid installing a stale (and
+  // leaked) subscription.
+  let runId = 0;
+  let activeUnsub: (() => void) | undefined;
+  // The hash of the currently-installed subscription, for opt-in deregister on
+  // dispose (see `deregisterOnCleanup`).
+  let activeHash: string | undefined;
 
-  const spooky = db.getSpooky();
+  const teardownActive = () => {
+    activeUnsub?.();
+    activeUnsub = undefined;
+  };
 
+  const sp00ky = db.getSp00ky();
+
+  /**
+   * Registration can fail — the canonical case is the SSP answering 503
+   * NOT_READY while it bootstraps. Nothing here used to catch that: the
+   * rejection escaped as an unhandled promise, `isFetched` stayed false, and
+   * `isLoading()` therefore stayed true FOREVER, which is what a spinner that
+   * never resolves actually was. Surface it as `error()` instead; the sync
+   * scheduler retries the registration underneath, so a transient failure
+   * still recovers on its own.
+   */
   const initQuery = async (
-    query: FinalQuery<S, TableName, T, RelatedFields, IsOne, SpookyQueryResultPromise>
+    query: FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>,
+    myRun: number
+  ) => {
+    try {
+      await subscribeQuery(query, myRun);
+    } catch (err) {
+      // A superseded run's failure is not this subscription's problem.
+      if (myRun !== runId) return;
+      setError(err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+
+  const subscribeQuery = async (
+    query: FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>,
+    myRun: number
   ) => {
     const { hash } = await query.run();
+    // A newer query identity (or disposal) won the race while we awaited run().
+    if (myRun !== runId) return;
+    activeHash = hash;
     setError(undefined);
 
     let isFirstCall = true;
-    const unsub = await spooky.subscribe(
+    const unsub = await sp00ky.subscribe(
       hash,
       (e) => {
-        const data = (query.isOne ? e[0] : e) as TData;
-        setData(() => data);
+        const queryData = (query.isOne ? e[0] : e) as TData;
+        // Merge into the store by record id: unchanged rows keep their identity,
+        // changed rows update in place. Replaces wholesale for `one()`/null.
+        // Time the reconcile → report as the "frontend" phase for DevTools/MCP.
+        const reconcileStart = performance.now();
+        setState('value', reconcile(queryData as any, { key: 'id' }));
+        // Notify coarse `data()` readers (see the `version` note above): reconcile
+        // keeps the array ref stable, so this is what re-runs `<For>`/copy-effects
+        // on add/remove/reorder.
+        setVersion((v) => v + 1);
+        sp00ky.reportFrontendTiming(hash, performance.now() - reconcileStart);
         // The first (immediate) callback with no data likely means the local DB
         // hasn't synced yet — don't mark as fetched so UI shows loading state
-        const hasData = query.isOne ? data != null : (e as any[]).length > 0;
+        const hasData = query.isOne ? queryData !== null && queryData !== undefined : (e as any[]).length > 0;
         if (!isFirstCall || hasData) {
           setIsFetched(true);
         }
@@ -125,7 +217,25 @@ export function useQuery<
       { immediate: true }
     );
 
-    setUnsubscribe(() => unsub);
+    // Mirror the query's fetch status so the UI can show a "loading more"
+    // state while the sync engine pulls missing records in the background.
+    const unsubStatus = sp00ky.subscribeQueryStatus(
+      hash,
+      (status) => setIsFetching(status === 'fetching'),
+      { immediate: true }
+    );
+
+    const teardown = () => {
+      unsub();
+      unsubStatus();
+    };
+
+    // Superseded while awaiting subscribe()? Don't leak — tear down immediately.
+    if (myRun !== runId) {
+      teardown();
+      return;
+    }
+    activeUnsub = teardown;
   };
 
   createEffect(() => {
@@ -143,30 +253,60 @@ export function useQuery<
       return;
     }
 
-    // Prevent re-running if query hasn't changed
-    const queryString = JSON.stringify(query);
+    // Dedup on the query's stable identity hash (cyrb53 of surql + vars), not a
+    // full `JSON.stringify` of the FinalQuery (which walks the whole schema +
+    // inner query on every reactive tick and isn't guaranteed stable). When the
+    // identity is unchanged we keep the existing subscription alive.
+    const queryString = String(query.hash);
     if (queryString === prevQueryString) {
       return;
     }
     prevQueryString = queryString;
 
-    // Reset fetched state when query changes
+    // New query identity → supersede the previous subscription and start fresh.
+    const myRun = ++runId;
+    teardownActive();
     setIsFetched(false);
-    initQuery(query);
+    // A new identity starts clean: a previous identity's failure must not keep
+    // this one out of its loading state.
+    setError(undefined);
+    void initQuery(query, myRun);
+  });
 
-    // Cleanup
-    onCleanup(() => {
-      unsubscribe()?.();
-    });
+  // Tear down the live subscription when the hook's owner is disposed. Registered
+  // on the hook (component) scope rather than inside the effect, so an effect
+  // re-run that early-returns (unchanged query) doesn't clean up the still-valid
+  // subscription. Bumping runId also invalidates any in-flight initQuery.
+  onCleanup(() => {
+    runId++;
+    teardownActive();
+    // Opt-in: cancel the query once this hook (its last subscriber) is gone.
+    // teardownActive() above already removed this hook's callback, so
+    // deregisterQuery's refcount guard sees the true remaining-subscriber count.
+    if (options?.deregisterOnCleanup && activeHash) {
+      sp00ky.deregisterQuery(activeHash);
+    }
   });
 
   const isLoading = () => {
     return !isFetched() && error() === undefined;
   };
 
+  // True once the query has delivered a result AND no fetch cycle is in flight
+  // (registration + initial sync included — the core holds `fetching` across
+  // the whole registration and flushes debounced results before flipping back
+  // to idle). While settled, the results are authoritative: a windowed query
+  // returning fewer rows than its LIMIT really is the end of the list, so
+  // virtualized lists may size themselves to it without the scrollbar jumping
+  // when a still-syncing window transiently reports short. Resets to false
+  // whenever the query identity changes.
+  const isSettled = () => isFetched() && !isFetching();
+
   return {
     data,
     error,
     isLoading,
+    isFetching,
+    isSettled,
   };
 }