@opengeni/react 3.1.0 → 3.1.2

package/src/hooks/shared-query.ts

@@ -0,0 +1,721 @@
+import { useCallback, useLayoutEffect, useReducer, useRef, useSyncExternalStore } from "react";
+import { normalizeError } from "../lib/error-message";
+import { usePageLiveActivity } from "./internal";
+
+/**
+ * A small client-scoped stale-while-revalidate store for read models that many
+ * surfaces show (subscription accounts, their usage limits). Internal to
+ * `@opengeni/react`: hosts reach it only through the hooks built on it and the
+ * `OpenGeniProvider` `retainReadsAcrossMounts` opt-in.
+ *
+ * Scoping:
+ *
+ * - Every entry lives under the exact client object that read it (a WeakMap),
+ *   like `createDiscoveryCache`; the key names the exact read
+ *   (`["codex-accounts", workspaceId, "session", sessionId]`).
+ * - By default nothing outlives its readers: mounted readers of one key share
+ *   one request and one snapshot, and the entry is dropped as soon as the last
+ *   reader unmounts. A reader renders an entry's rows only once it has
+ *   registered on it (layout phase, then a re-render before paint), and only
+ *   the reader instance that let go may take an entry back (StrictMode, effect
+ *   re-runs); a different reader mounting in the same commit (a host
+ *   re-keying its tree for another person) never renders the previous rows,
+ *   starts from nothing, and the earlier read and writes are discarded. Only a scope a host retains
+ *   (`retainSharedQueries`, used by the provider opt-in) keeps unmounted
+ *   entries for `retainMs`, so a host that reuses one client for different
+ *   people never serves one person's rows to the next mount. Ending the last
+ *   retention clears the scope.
+ * - `clearSharedQueries(scope)` drops every row at once. Mounted readers stay
+ *   subscribed and read again; writes from operations that started before the
+ *   clear are discarded.
+ *
+ * Semantics:
+ *
+ * - A mount with retained data renders it immediately and revalidates in the
+ *   background once it is older than `staleTimeMs`. An enabled reader reports
+ *   `loading` until its key's first read completes.
+ * - Page visibility pauses only polling and background revalidation of rows
+ *   already on screen; invalidation and `refresh()` read on a hidden page too.
+ * - A loader is bound to its key when the render that supplied it commits, so a
+ *   render that never commits (a transition) or a key change cannot run one
+ *   key's loader for another key's entry.
+ * - Failures are never cached. An access refusal (401/403/404) also drops the
+ *   retained data; another failure keeps it beside the error.
+ * - `invalidateSharedQueries` supersedes any read in flight (its result is
+ *   discarded), re-reads mounted entries and evicts unmounted ones, so a later
+ *   mount never shows rows a mutation has made wrong.
+ */
+
+export type SharedQueryKey = readonly (string | number | boolean | null)[];
+
+export type SharedQuerySnapshot<T> = {
+  data: T | null;
+  /** True only while there is nothing to show yet (first read for this key). */
+  loading: boolean;
+  /** True while any read for this key is in flight, including background ones. */
+  fetching: boolean;
+  error: Error | null;
+  /** Epoch milliseconds of the last successful read or write, or null. */
+  updatedAt: number | null;
+};
+
+export type SharedQueryOptions = {
+  /** False: never read, and show no data (not even retained rows). */
+  enabled?: boolean | undefined;
+  /** Poll while mounted and the page is visible. Shortest interval wins. */
+  pollIntervalMs?: number | undefined;
+  /** Retained data younger than this is not re-read on mount. Default 10s. */
+  staleTimeMs?: number | undefined;
+  /** How long an unmounted entry is retained in a retained scope. Default 10 minutes. */
+  retainMs?: number | undefined;
+};
+
+export type SharedQueryResult<T> = SharedQuerySnapshot<T> & {
+  /** Force a read now (joining one queued after any in-flight read). */
+  refresh: () => Promise<void>;
+};
+
+/** Records data read some other way; false when the write was refused. */
+export type SharedQueryWriter = <T>(parts: SharedQueryKey, data: T) => boolean;
+
+const DEFAULT_STALE_TIME_MS = 10_000;
+const DEFAULT_RETAIN_MS = 10 * 60_000;
+
+type Loader<T> = (signal: AbortSignal) => Promise<T>;
+type LoaderBinding = { key: string; load: Loader<unknown> };
+
+type Subscriber = {
+  /** The hook instance; only it may take back an entry it just let go of. */
+  owner: object;
+  /** The committed loader and the key it reads; null for subscribe-only readers. */
+  binding: { current: LoaderBinding } | null;
+  enabled: boolean;
+  pageLive: boolean;
+  pollIntervalMs: number | undefined;
+  staleTimeMs: number;
+  retainMs: number;
+};
+
+type Entry = {
+  key: string;
+  parts: SharedQueryKey;
+  snapshot: SharedQuerySnapshot<unknown>;
+  /** The scope that holds this entry; its store listeners are notified per key. */
+  home: Scope;
+  subscribers: Set<Subscriber>;
+  inFlight: Promise<void> | null;
+  trailing: Promise<void> | null;
+  abort: AbortController | null;
+  generation: number;
+  /** The retained data may be wrong; the next reconcile re-reads. */
+  invalidated: boolean;
+  timer: ReturnType<typeof setTimeout> | null;
+  /** The interval `timer` was armed with. */
+  timerInterval: number | null;
+  retainTimer: ReturnType<typeof setTimeout> | null;
+  /** The reader instance that last let go of this entry while it awaits release. */
+  releasedBy: object | null;
+  /** When this entry last started over for a new owner (see `resetSequence`). */
+  resetMark: number;
+};
+
+type Scope = {
+  entries: Map<string, Entry>;
+  /**
+   * Store (useSyncExternalStore) listeners per key, not per entry: a reader
+   * hidden by Suspense keeps its store subscription while it is unregistered,
+   * and must still hear about the entry that replaces an evicted one.
+   */
+  listeners: Map<string, Set<() => void>>;
+  /** Bumped by every clear; writers from an earlier epoch are refused. */
+  epoch: number;
+  /** Active retentions; unmounted entries are kept only while positive. */
+  retainers: number;
+  releaseTimer: ReturnType<typeof setTimeout> | null;
+};
+
+const scopes = new WeakMap<object, Scope>();
+/**
+ * Orders writers against entries that started over for a new owner: a writer
+ * created before an entry's mark never writes to it.
+ */
+let resetSequence = 0;
+
+function idle<T>(loading: boolean): SharedQuerySnapshot<T> {
+  return { data: null, loading, fetching: false, error: null, updatedAt: null };
+}
+const IDLE_LOADING = idle<never>(true);
+const IDLE = idle<never>(false);
+
+function serialize(parts: SharedQueryKey): string {
+  return JSON.stringify(parts);
+}
+
+/** A refusal that repeating the read cannot fix; retained rows must go. */
+export function isSharedQueryAccessRefusal(cause: unknown): boolean {
+  if (!cause || typeof cause !== "object" || !("status" in cause)) return false;
+  const status = (cause as { status: unknown }).status;
+  return status === 401 || status === 403 || status === 404;
+}
+
+function scopeState(scope: object): Scope {
+  let state = scopes.get(scope);
+  if (!state) {
+    state = {
+      entries: new Map(),
+      listeners: new Map(),
+      epoch: 0,
+      retainers: 0,
+      releaseTimer: null,
+    };
+    scopes.set(scope, state);
+  }
+  return state;
+}
+
+function notify(state: Scope, key: string): void {
+  const listeners = state.listeners.get(key);
+  if (!listeners) return;
+  for (const listener of [...listeners]) listener();
+}
+
+function setSnapshot(entry: Entry, next: SharedQuerySnapshot<unknown>): void {
+  entry.snapshot = next;
+  notify(entry.home, entry.key);
+}
+
+/** A store listener for a client's key, whichever entry currently holds it. */
+function listen(scope: object, key: string, listener: () => void): () => void {
+  const state = scopeState(scope);
+  let listeners = state.listeners.get(key);
+  if (!listeners) {
+    listeners = new Set();
+    state.listeners.set(key, listeners);
+  }
+  listeners.add(listener);
+  return () => {
+    const current = state.listeners.get(key);
+    if (!current) return;
+    current.delete(listener);
+    if (current.size === 0) state.listeners.delete(key);
+  };
+}
+
+/** Readers that may read: enabled and bound to this key (visible or not). */
+function readers(entry: Entry): Subscriber[] {
+  return [...entry.subscribers].filter(
+    (each) => each.enabled && each.binding?.current.key === entry.key,
+  );
+}
+
+/**
+ * Registered readers keep an entry. Store listeners don't: they belong to the
+ * client and key (see `Scope.listeners`), React removes them in the passive
+ * phase, and a reader hidden by Suspense keeps one while it is unregistered.
+ */
+function mounted(entry: Entry): boolean {
+  return entry.subscribers.size > 0;
+}
+
+function stopTimer(entry: Entry): void {
+  if (entry.timer !== null) {
+    clearTimeout(entry.timer);
+    entry.timer = null;
+  }
+  entry.timerInterval = null;
+}
+
+function stopRetainTimer(entry: Entry): void {
+  if (entry.retainTimer !== null) {
+    clearTimeout(entry.retainTimer);
+    entry.retainTimer = null;
+  }
+}
+
+/** Any read in flight or queued is superseded: its result is never stored. */
+function supersedeReads(entry: Entry): void {
+  entry.generation += 1;
+  entry.abort?.abort();
+  entry.abort = null;
+  entry.inFlight = null;
+  entry.trailing = null;
+}
+
+function evict(state: Scope, entry: Entry): void {
+  supersedeReads(entry);
+  stopTimer(entry);
+  stopRetainTimer(entry);
+  if (state.entries.get(entry.key) !== entry) return;
+  state.entries.delete(entry.key);
+  // Store subscriptions that outlive the entry (Suspense) now read nothing.
+  notify(state, entry.key);
+}
+
+/** Poll at the shortest interval among readers on a visible page; keep a timer already armed for it. */
+function arm(entry: Entry): void {
+  let interval: number | undefined;
+  for (const each of readers(entry)) {
+    if (!each.pageLive) continue;
+    if (each.pollIntervalMs === undefined || each.pollIntervalMs <= 0) continue;
+    interval =
+      interval === undefined ? each.pollIntervalMs : Math.min(interval, each.pollIntervalMs);
+  }
+  if (entry.timer !== null && entry.timerInterval === interval) return;
+  stopTimer(entry);
+  if (interval === undefined) return;
+  entry.timerInterval = interval;
+  entry.timer = setTimeout(() => {
+    entry.timer = null;
+    entry.timerInterval = null;
+    void run(entry).finally(() => arm(entry));
+  }, interval);
+}
+
+async function runFresh(entry: Entry): Promise<void> {
+  const subscriber = readers(entry).at(-1);
+  if (!subscriber?.binding) return;
+  const { load } = subscriber.binding.current;
+  const ticket = ++entry.generation;
+  const abort = new AbortController();
+  entry.abort = abort;
+  entry.invalidated = false;
+  if (!entry.snapshot.fetching) setSnapshot(entry, { ...entry.snapshot, fetching: true });
+  try {
+    const data = await load(abort.signal);
+    if (ticket !== entry.generation) return;
+    setSnapshot(entry, {
+      data,
+      loading: false,
+      fetching: false,
+      error: null,
+      updatedAt: Date.now(),
+    });
+  } catch (cause) {
+    if (ticket !== entry.generation) return;
+    const refused = isSharedQueryAccessRefusal(cause);
+    setSnapshot(entry, {
+      data: refused ? null : entry.snapshot.data,
+      loading: false,
+      fetching: false,
+      error: normalizeError(cause),
+      // A failure is never a fresh read: the next mount re-reads.
+      updatedAt: null,
+    });
+  } finally {
+    if (entry.abort === abort) entry.abort = null;
+  }
+}
+
+function run(entry: Entry, force = false): Promise<void> {
+  if (entry.inFlight) {
+    if (!force) return entry.inFlight;
+    // A forced read issued during another read must observe whatever changed
+    // since that read started, so queue exactly one successor read.
+    if (entry.trailing) return entry.trailing;
+    const predecessor = entry.inFlight;
+    let trailing!: Promise<void>;
+    trailing = predecessor.then(() => {
+      // Superseded meanwhile: the read that replaced it is the newer one.
+      if (entry.trailing !== trailing) return entry.inFlight ?? undefined;
+      entry.trailing = null;
+      if (readers(entry).length > 0) return run(entry);
+      // Nobody can read now: what the predecessor stored is not known to be
+      // current, so the next mount or resume re-reads.
+      entry.invalidated = true;
+      return undefined;
+    });
+    entry.trailing = trailing;
+    return trailing;
+  }
+  let promise!: Promise<void>;
+  promise = runFresh(entry).finally(() => {
+    if (entry.inFlight === promise) entry.inFlight = null;
+  });
+  entry.inFlight = promise;
+  return promise;
+}
+
+function isStale(entry: Entry, staleTimeMs: number): boolean {
+  const updatedAt = entry.snapshot.updatedAt;
+  return entry.invalidated || updatedAt === null || Date.now() - updatedAt >= staleTimeMs;
+}
+
+function reconcile(entry: Entry): void {
+  const active = readers(entry);
+  if (active.length === 0) {
+    stopTimer(entry);
+    if (entry.snapshot.loading) setSnapshot(entry, { ...entry.snapshot, loading: false });
+    return;
+  }
+  const staleTimeMs = Math.min(...active.map((each) => each.staleTimeMs));
+  // A hidden page still reads what it has nothing (or nothing right) to show;
+  // it only defers revalidating rows already on screen.
+  const due =
+    active.some((each) => each.pageLive) || entry.invalidated || entry.snapshot.data === null;
+  if (due && isStale(entry, staleTimeMs)) {
+    // A mount or resume never inherits an earlier failure: it reads again and
+    // shows a loading state (or retained rows) until that read settles.
+    if (entry.snapshot.error || (entry.snapshot.data === null && !entry.snapshot.loading)) {
+      setSnapshot(entry, {
+        ...entry.snapshot,
+        error: null,
+        loading: entry.snapshot.data === null,
+      });
+    }
+    void run(entry).finally(() => arm(entry));
+    return;
+  }
+  // A reader joined or left: the shortest interval may have changed.
+  arm(entry);
+}
+
+function scheduleRelease(state: Scope, entry: Entry, retainMs: number): void {
+  stopRetainTimer(entry);
+  // Even an unretained entry waits one task, so StrictMode's immediate
+  // unmount/remount keeps sharing the read it already started.
+  entry.retainTimer = setTimeout(() => {
+    entry.retainTimer = null;
+    if (!mounted(entry)) evict(state, entry);
+  }, retainMs);
+}
+
+function getOrCreate(scope: object, key: string, loading: boolean): Entry {
+  const state = scopeState(scope);
+  const existing = state.entries.get(key);
+  if (existing) {
+    stopRetainTimer(existing);
+    return existing;
+  }
+  const created: Entry = {
+    key,
+    parts: JSON.parse(key) as SharedQueryKey,
+    snapshot: idle(loading),
+    home: state,
+    subscribers: new Set(),
+    inFlight: null,
+    trailing: null,
+    abort: null,
+    generation: 0,
+    invalidated: false,
+    timer: null,
+    timerInterval: null,
+    retainTimer: null,
+    releasedBy: null,
+    // Without retention a new entry may be someone else's: writers created
+    // before it (by an earlier, now unmounted reader) never fill it.
+    resetMark: state.retainers === 0 ? ++resetSequence : 0,
+  };
+  state.entries.set(key, created);
+  return created;
+}
+
+/**
+ * Register a reader instance. In an unretained scope an entry that another
+ * instance let go of in this same commit is not adopted: its rows and any read
+ * in flight belonged to that reader (possibly another person), so it starts
+ * over and writes to it begun before now are refused. True when it was reset.
+ */
+function registerSubscriber(scope: object, entry: Entry, subscriber: Subscriber): boolean {
+  const state = scopeState(scope);
+  const foreign =
+    entry.subscribers.size === 0 &&
+    entry.releasedBy !== null &&
+    entry.releasedBy !== subscriber.owner &&
+    state.retainers === 0;
+  if (foreign) {
+    supersedeReads(entry);
+    stopTimer(entry);
+    entry.invalidated = false;
+    entry.resetMark = ++resetSequence;
+    setSnapshot(entry, IDLE);
+  }
+  entry.releasedBy = null;
+  entry.subscribers.add(subscriber);
+  return foreign;
+}
+
+function unsubscribe(scope: object, entry: Entry, subscriber: Subscriber, retainMs: number): void {
+  entry.subscribers.delete(subscriber);
+  if (entry.subscribers.size > 0) {
+    reconcile(entry);
+    return;
+  }
+  entry.releasedBy = subscriber.owner;
+  // Only the poll stops: in a retained scope a read in flight still lands
+  // for the next mount. Otherwise the entry goes with its last reader.
+  stopTimer(entry);
+  if (entry.snapshot.loading) setSnapshot(entry, { ...entry.snapshot, loading: false });
+  const state = scopes.get(scope);
+  if (!state || state.entries.get(entry.key) !== entry) return;
+  scheduleRelease(state, entry, state.retainers > 0 ? retainMs : 0);
+}
+
+/**
+ * The entry a reader may render. Without host retention an entry's rows belong
+ * to the readers registered on it: until this reader has registered (layout
+ * phase) it renders a placeholder, so a reader replacing another in one
+ * commit never renders, or hands its children, the previous rows.
+ */
+function visibleEntry(scope: object, key: string, registered: Entry | null): Entry | null {
+  const state = scopes.get(scope);
+  const entry = state?.entries.get(key);
+  if (!state || !entry) return null;
+  if (state.retainers === 0 && registered !== entry) return null;
+  return entry;
+}
+
+/** The retained snapshot for a key, without subscribing or reading. */
+export function peekSharedQuery<T>(
+  scope: object,
+  parts: SharedQueryKey,
+): SharedQuerySnapshot<T> | null {
+  return (
+    (scopes.get(scope)?.entries.get(serialize(parts))?.snapshot as
+      | SharedQuerySnapshot<T>
+      | undefined) ?? null
+  );
+}
+
+/**
+ * A writer for data read some other way (for example a live provider refresh).
+ * Create it BEFORE starting that read: a clear in between refuses every write,
+ * and an entry that started over for a new owner meanwhile refuses writes to
+ * it, so a retired identity's late result is never recorded. Mounted readers
+ * render a write at once; with no reader, only a retained scope keeps it.
+ */
+export function sharedQueryWriter(scope: object): SharedQueryWriter {
+  const state = scopeState(scope);
+  const epoch = state.epoch;
+  const since = resetSequence;
+  return <T>(parts: SharedQueryKey, data: T): boolean => {
+    if (state.epoch !== epoch) return false;
+    const key = serialize(parts);
+    const existing = state.entries.get(key);
+    if (existing && existing.resetMark > since) return false;
+    if (!(existing && mounted(existing)) && state.retainers === 0) return false;
+    const entry = existing ?? getOrCreate(scope, key, false);
+    // A read already in flight started before this write; its result is older.
+    supersedeReads(entry);
+    entry.invalidated = false;
+    setSnapshot(entry, {
+      data,
+      loading: false,
+      fetching: false,
+      error: null,
+      updatedAt: Date.now(),
+    });
+    if (!mounted(entry)) scheduleRelease(state, entry, DEFAULT_RETAIN_MS);
+    return true;
+  };
+}
+
+/**
+ * Mark every entry whose key starts with `prefix` as wrong. Reads in flight are
+ * superseded. Mounted entries re-read now (keeping their rows on screen
+ * meanwhile); paused ones re-read when they resume; unmounted entries are
+ * evicted so the next mount never renders them.
+ */
+export function invalidateSharedQueries(scope: object, prefix: SharedQueryKey): Promise<void> {
+  const state = scopes.get(scope);
+  if (!state) return Promise.resolve();
+  const reads: Promise<void>[] = [];
+  for (const entry of [...state.entries.values()]) {
+    if (!prefix.every((part, index) => entry.parts[index] === part)) continue;
+    if (!mounted(entry)) {
+      evict(state, entry);
+      continue;
+    }
+    supersedeReads(entry);
+    entry.invalidated = true;
+    // Readers keep their rows on screen while the re-read runs, also on a
+    // hidden page (a sign-in finished in another tab must not blank Settings).
+    if (readers(entry).length > 0) {
+      reads.push(run(entry).finally(() => arm(entry)));
+      continue;
+    }
+    // Only disabled or subscribe-only readers: drop the rows; an enabled
+    // reader reads again when it appears.
+    stopTimer(entry);
+    setSnapshot(entry, IDLE);
+  }
+  return Promise.all(reads).then(() => undefined);
+}
+
+/**
+ * Drop everything retained for a client. Unmounted entries go; mounted ones
+ * are reset in place (their readers stay subscribed) and active ones read
+ * again. Writes from operations that began before the clear are refused.
+ */
+export function clearSharedQueries(scope: object): void {
+  const state = scopes.get(scope);
+  if (!state) return;
+  state.epoch += 1;
+  for (const entry of [...state.entries.values()]) {
+    if (!mounted(entry)) {
+      evict(state, entry);
+      continue;
+    }
+    supersedeReads(entry);
+    stopTimer(entry);
+    stopRetainTimer(entry);
+    entry.invalidated = true;
+    const active = readers(entry).length > 0;
+    setSnapshot(entry, active ? IDLE_LOADING : IDLE);
+    if (active) void run(entry).finally(() => arm(entry));
+  }
+}
+
+/**
+ * Keep unmounted entries for this client until the returned release is
+ * called. Releasing the last retention clears the client's entries (after one
+ * task, so StrictMode's immediate remount keeps them).
+ */
+export function retainSharedQueries(scope: object): () => void {
+  const state = scopeState(scope);
+  state.retainers += 1;
+  if (state.releaseTimer !== null) {
+    clearTimeout(state.releaseTimer);
+    state.releaseTimer = null;
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    state.retainers -= 1;
+    if (state.retainers > 0) return;
+    if (state.releaseTimer !== null) clearTimeout(state.releaseTimer);
+    state.releaseTimer = setTimeout(() => {
+      state.releaseTimer = null;
+      if (state.retainers === 0) clearSharedQueries(scope);
+    }, 0);
+  };
+}
+
+/**
+ * Subscribe to one shared read. `scope` is the client object that performs
+ * the read; `parts` must name every input the loader depends on.
+ */
+export function useSharedQuery<T>(
+  scope: object,
+  parts: SharedQueryKey,
+  load: Loader<T>,
+  options: SharedQueryOptions = {},
+): SharedQueryResult<T> {
+  const enabled = options.enabled ?? true;
+  const pageLive = usePageLiveActivity();
+  const key = serialize(parts);
+  // The loader is bound to its key only when the render that supplied both
+  // commits: a render React discards (a transition) never rebinds it, and a
+  // subscriber whose binding names another key is ignored by every read, so
+  // one key's loader never fills another key's entry.
+  const binding = useRef<LoaderBinding>({ key, load: load as Loader<unknown> });
+  useLayoutEffect(() => {
+    binding.current = { key, load: load as Loader<unknown> };
+  }, [key, load]);
+  const staleTimeMs = options.staleTimeMs ?? DEFAULT_STALE_TIME_MS;
+  const retainMs = options.retainMs ?? DEFAULT_RETAIN_MS;
+  const pollIntervalMs = options.pollIntervalMs;
+
+  const subscribe = useCallback(
+    (listener: () => void) => listen(scope, key, listener),
+    [scope, key],
+  );
+  // The entry this instance is registered on (set in the layout phase).
+  const registered = useRef<Entry | null>(null);
+  const getSnapshot = useCallback(
+    () =>
+      (visibleEntry(scope, key, registered.current)?.snapshot as
+        | SharedQuerySnapshot<T>
+        | undefined) ?? (enabled ? IDLE_LOADING : IDLE),
+    [scope, key, enabled],
+  );
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const owner = useRef<object>({});
+  const [, rerender] = useReducer((count: number) => count + 1, 0);
+
+  // Registered in the layout phase, after any reader this commit unmounts has
+  // let go, so a foreign entry is reset before the browser paints.
+  useLayoutEffect(() => {
+    const entry = getOrCreate(scope, key, enabled);
+    const subscriber: Subscriber = {
+      owner: owner.current,
+      binding,
+      enabled,
+      pageLive,
+      pollIntervalMs,
+      staleTimeMs,
+      retainMs,
+    };
+    registerSubscriber(scope, entry, subscriber);
+    registered.current = entry;
+    reconcile(entry);
+    // Rendered before registering (a placeholder) or before a reset: show
+    // what is registered now, before the browser paints.
+    if (getSnapshot() !== snapshot) rerender();
+    return () => {
+      if (registered.current === entry) registered.current = null;
+      unsubscribe(scope, entry, subscriber, retainMs);
+    };
+    // `snapshot` is what this commit rendered; it never re-registers a reader.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [scope, key, enabled, pageLive, pollIntervalMs, staleTimeMs, retainMs]);
+
+  const refresh = useCallback((): Promise<void> => {
+    const entry = scopes.get(scope)?.entries.get(key);
+    if (!entry || readers(entry).length === 0) return Promise.resolve();
+    return run(entry, true).finally(() => arm(entry));
+  }, [scope, key]);
+
+  // A disabled reader shows nothing, not even rows retained by other readers.
+  if (!enabled) return { ...IDLE, refresh };
+  // Enabled with nothing read yet (also the first render after enabling).
+  const unread = snapshot.data === null && snapshot.error === null && snapshot.updatedAt === null;
+  return { ...snapshot, loading: snapshot.loading || unread, refresh };
+}
+
+/**
+ * Subscribe to an entry that is only ever written (`sharedQueryWriter`), never
+ * read: it renders whatever is recorded and keeps the entry while mounted.
+ */
+export function useSharedQueryValue<T>(
+  scope: object,
+  parts: SharedQueryKey,
+): SharedQuerySnapshot<T> {
+  const key = serialize(parts);
+  const subscribe = useCallback(
+    (listener: () => void) => listen(scope, key, listener),
+    [scope, key],
+  );
+  const registered = useRef<Entry | null>(null);
+  const getSnapshot = useCallback(
+    () =>
+      (visibleEntry(scope, key, registered.current)?.snapshot as
+        | SharedQuerySnapshot<T>
+        | undefined) ?? IDLE,
+    [scope, key],
+  );
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const owner = useRef<object>({});
+  const [, rerender] = useReducer((count: number) => count + 1, 0);
+  useLayoutEffect(() => {
+    const entry = getOrCreate(scope, key, false);
+    const subscriber: Subscriber = {
+      owner: owner.current,
+      binding: null,
+      enabled: false,
+      pageLive: true,
+      pollIntervalMs: undefined,
+      staleTimeMs: DEFAULT_STALE_TIME_MS,
+      retainMs: DEFAULT_RETAIN_MS,
+    };
+    registerSubscriber(scope, entry, subscriber);
+    registered.current = entry;
+    if (getSnapshot() !== snapshot) rerender();
+    return () => {
+      if (registered.current === entry) registered.current = null;
+      unsubscribe(scope, entry, subscriber, DEFAULT_RETAIN_MS);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [scope, key]);
+  return snapshot;
+}