@rindle/react 0.7.12 → 0.8.0

package/src/index.ts

@@ -61,8 +61,26 @@ export type { ResultType } from "@rindle/client";
 export type { Fragment, FragmentData, FragmentRef } from "@rindle/client";
 export { fragmentKey } from "@rindle/client";
 
+// The LM stream plane's client half (LM-STREAM-CHECKPOINT-DESIGN.md): the durable side arrives through
+// an ordinary query, `useStreamedText` adds the live tail and merges the two. The pure reassembly
+// helpers come from `@rindle/client` and are re-exported so a component needs ONE import.
+export {
+  DEFAULT_STREAM_ENDPOINT,
+  eventSourceTransport,
+  streamSubscribeUrl,
+  useStreamedText,
+} from "./stream.ts";
+export type { StreamTransport, UseStreamedTextInput, UseStreamedTextOptions } from "./stream.ts";
+export { assembleDurableText, spliceStreamText } from "@rindle/client";
+export type { StreamFrame, StreamStatus } from "@rindle/client";
+
 export interface RindleProps<S extends ColsMap = ColsMap> {
   store: Store<S>;
+  /** Default grace window (ms) for every query in this tree — how long a view + its server lease are
+   *  kept warm after the last subscriber unmounts. Defaults to 2s; see {@link QueryReleaseOptions}
+   *  for why, and for the per-call-site override. Treat as a constant: changing it rebuilds the
+   *  caches and tears down every live view. */
+  releaseDelayMs?: number;
   children?: ReactNode;
 }
 
@@ -80,6 +98,8 @@ interface QueryLease {
 interface SyncLease {
   id: number;
   coverageKey: string;
+  /** Resolved grace window for THIS lease (see {@link QueryReleaseOptions}). */
+  releaseDelayMs: number;
 }
 
 interface MaterializedLease extends QueryLease {
@@ -89,6 +109,8 @@ interface MaterializedLease extends QueryLease {
 
 interface SplitLease extends QueryLease {
   releaseRemote: () => void;
+  /** Resolved grace window for THIS lease (see {@link QueryReleaseOptions}). */
+  releaseDelayMs: number;
 }
 
 type CacheLease = MaterializedLease | SplitLease;
@@ -105,6 +127,11 @@ interface SplitCacheEntry extends BaseCacheEntry {
   leases: SplitLease[];
   pendingReleases: SplitLease[];
   releaseTimer: ReleaseTimer | undefined;
+  /** Absolute monotonic ms this entry's warm window expires at — the latest `release time + that
+   *  lease's delay` asked for by ANY lease on this entry (see {@link QueryReleaseOptions}). Written
+   *  only in `release`, so the clock starts when a subscriber LEAVES. Monotone, and it expires on its
+   *  own, which is what makes a later lease inherit only the residue of an older window. */
+  releaseDeadline: number;
 }
 
 interface MaterializedCacheEntry extends BaseCacheEntry {
@@ -118,6 +145,7 @@ type CacheEntry = SplitCacheEntry | MaterializedCacheEntry;
 const EMPTY_ARRAY: readonly never[] = Object.freeze([]);
 // Keep just-released coverage alive briefly so a changed filter/limit can re-materialize from the
 // local base synchronously while the replacement server lease is still streaming its first answer.
+// Overridable per tree (`<Rindle releaseDelayMs>`) and per call site ({@link QueryReleaseOptions}).
 const REACT_CACHE_RELEASE_DELAY_MS = 2_000;
 
 type ReleaseTimer = ReturnType<typeof setTimeout>;
@@ -126,6 +154,50 @@ interface QueryCacheOptions {
   releaseDelayMs?: number;
 }
 
+/**
+ * Per-call-site override for how long a query is kept warm after its LAST subscriber unmounts.
+ *
+ * The default (2s, or whatever `<Rindle releaseDelayMs>` sets) exists so a changed filter/limit can
+ * re-materialize from the still-warm local base while the replacement server lease streams its first
+ * answer — it's what keeps navigation from flashing empty. That grace window is wrong for queries you
+ * KNOW you will never come back to, the canonical case being typeahead search: every keystroke is a
+ * distinct query, so a 2s window leaves one dead view + server subscription open per character typed.
+ * Pass `0` there to tear down on unmount:
+ *
+ * ```tsx
+ * const results = useQuery(searchIssues(term), { releaseDelayMs: 0 });
+ * ```
+ *
+ * Treat the value as a constant per call site — changing it re-leases the query (drops the old lease
+ * and takes a fresh one), which is wasted work if it changes every render.
+ *
+ * The rule for a query several components share with DIFFERENT delays is a DEADLINE, not a duration:
+ * every release stamps `now + that lease's delay`, and the query stays warm until the latest deadline
+ * any of its leases asked for (max-wins over what REMAINS, matching the SSR preload TTL rule in
+ * `@rindle/client`'s `ssr.ts`). Two consequences worth internalizing:
+ *
+ *   - The clock starts when a subscriber LEAVES, never when it arrives — a mounted reader is never
+ *     timed out, however long it stays.
+ *   - A deadline expires on its own, so a later lease inherits at most the RESIDUE of an older window,
+ *     never a fresh copy of it. Unmount a 2s reader, remount a `releaseDelayMs: 0` one 1.9s later and
+ *     drop it: teardown lands at the original 2s mark, not 1.9s past it.
+ *
+ * Only meaningful against a backend that can retain remote queries. A local-only store (the SSR seed
+ * over `OneShotBackend`, or a store with no remote leg) always tears its views down on release, so
+ * there is no window to shorten.
+ */
+export interface QueryReleaseOptions {
+  /** ms to keep this query warm after the last subscriber unmounts. `0` = release immediately.
+   *  Defaults to the provider's `releaseDelayMs` (2s). */
+  releaseDelayMs?: number;
+}
+
+/** Monotonic clock for release deadlines. Deliberately NOT `Date.now()`: a wall-clock step backwards
+ *  would extend every live warm window, and a step forwards would truncate them. */
+function nowMs(): number {
+  return performance.now();
+}
+
 function setReleaseTimeout(fn: () => void, ms: number): ReleaseTimer {
   const timer = setTimeout(fn, ms);
   (timer as { unref?: () => void }).unref?.();
@@ -137,17 +209,23 @@ class RindleContextValue {
   readonly cache: QueryCache;
   readonly syncCache: SyncQueryCache;
 
-  constructor(store: Store<ColsMap>) {
+  constructor(store: Store<ColsMap>, releaseDelayMs: number) {
     this.store = store;
-    this.cache = new QueryCache(store, { releaseDelayMs: REACT_CACHE_RELEASE_DELAY_MS });
-    this.syncCache = new SyncQueryCache(store, { releaseDelayMs: REACT_CACHE_RELEASE_DELAY_MS });
+    this.cache = new QueryCache(store, { releaseDelayMs });
+    this.syncCache = new SyncQueryCache(store, { releaseDelayMs });
   }
 }
 
 const RindleContext = createContext<RindleContextValue | null>(null);
 
-export function Rindle<S extends ColsMap>({ store, children }: RindleProps<S>) {
-  const value = useMemo(() => new RindleContextValue(store as unknown as Store<ColsMap>), [store]);
+export function Rindle<S extends ColsMap>({ store, releaseDelayMs, children }: RindleProps<S>) {
+  const delay = releaseDelayMs ?? REACT_CACHE_RELEASE_DELAY_MS;
+  // `releaseDelayMs` is tree CONFIG, not state: changing it rebuilds the caches exactly like swapping
+  // `store` does, tearing down every live view. Pass a constant; use the per-hook option to vary it.
+  const value = useMemo(
+    () => new RindleContextValue(store as unknown as Store<ColsMap>, delay),
+    [store, delay],
+  );
   return createElement(RindleContext.Provider, { value }, children);
 }
 
@@ -221,22 +299,23 @@ export function RindleSSR<S extends ColsMap>({ schema, ssrState, boot, children
   return createElement(Rindle<S>, { store: liveStore ?? seedStore }, children);
 }
 
-export function useQuery<Q extends AnyQuery>(query: Q): QueryData<Q> {
+export function useQuery<Q extends AnyQuery>(query: Q, opts?: QueryReleaseOptions): QueryData<Q> {
   const ctx = useRindleContext();
   const descriptor = useMemo(() => describeQuery(query), [query]);
   const queryRef = useRef(query);
   queryRef.current = query;
+  const releaseDelayMs = opts?.releaseDelayMs;
 
   const subscribe = useCallback(
     (onStoreChange: () => void) => {
-      const lease = ctx.cache.retain(descriptor.viewKey, queryRef.current);
+      const lease = ctx.cache.retain(descriptor.viewKey, queryRef.current, releaseDelayMs);
       const unsubscribe = ctx.cache.subscribe(descriptor.viewKey, onStoreChange);
       return () => {
         unsubscribe();
         ctx.cache.release(lease);
       };
     },
-    [ctx.cache, descriptor.leaseKey, descriptor.viewKey],
+    [ctx.cache, descriptor.leaseKey, descriptor.viewKey, releaseDelayMs],
   );
 
   const getSnapshot = useCallback(
@@ -261,22 +340,23 @@ export function useQuery<Q extends AnyQuery>(query: Q): QueryData<Q> {
  *  §7); the `error` variant is reserved and currently unproduced. Shares the same cached/leased view
  *  as {@link useQuery} (so reading both for one query is one subscription), and re-renders only when
  *  the status changes. */
-export function useQueryStatus(query: AnyQuery): ResultType {
+export function useQueryStatus(query: AnyQuery, opts?: QueryReleaseOptions): ResultType {
   const ctx = useRindleContext();
   const descriptor = useMemo(() => describeQuery(query), [query]);
   const queryRef = useRef(query);
   queryRef.current = query;
+  const releaseDelayMs = opts?.releaseDelayMs;
 
   const subscribe = useCallback(
     (onStoreChange: () => void) => {
-      const lease = ctx.cache.retain(descriptor.viewKey, queryRef.current);
+      const lease = ctx.cache.retain(descriptor.viewKey, queryRef.current, releaseDelayMs);
       const unsubscribe = ctx.cache.subscribe(descriptor.viewKey, onStoreChange);
       return () => {
         unsubscribe();
         ctx.cache.release(lease);
       };
     },
-    [ctx.cache, descriptor.leaseKey, descriptor.viewKey],
+    [ctx.cache, descriptor.leaseKey, descriptor.viewKey, releaseDelayMs],
   );
 
   const getSnapshot = useCallback(() => ctx.cache.resultType(descriptor.viewKey), [ctx.cache, descriptor.viewKey]);
@@ -293,22 +373,23 @@ export function useQueryStatus(query: AnyQuery): ResultType {
 /** Retain a named server query for normalized/local-first sync coverage without subscribing React
  *  to that query's broad result tree. The returned value is lifecycle state only; it is `unknown`
  *  until the backend reports that the retained coverage has hydrated. */
-export function useSyncQuery(query: AnyQuery): ResultType {
+export function useSyncQuery(query: AnyQuery, opts?: QueryReleaseOptions): ResultType {
   const ctx = useRindleContext();
   const descriptor = useMemo(() => describeQuery(query), [query]);
   const queryRef = useRef(query);
   queryRef.current = query;
+  const releaseDelayMs = opts?.releaseDelayMs;
 
   const subscribe = useCallback(
     (onStoreChange: () => void) => {
-      const lease = ctx.syncCache.retain(descriptor.leaseKey, queryRef.current);
+      const lease = ctx.syncCache.retain(descriptor.leaseKey, queryRef.current, releaseDelayMs);
       const unsubscribe = ctx.syncCache.subscribe(descriptor.leaseKey, onStoreChange);
       return () => {
         unsubscribe();
         ctx.syncCache.release(lease);
       };
     },
-    [ctx.syncCache, descriptor.leaseKey],
+    [ctx.syncCache, descriptor.leaseKey, releaseDelayMs],
   );
 
   const getSnapshot = useCallback(() => {
@@ -510,8 +591,9 @@ function useRootRefData<Q extends AnyQuery, F extends Fragment<any, any, any, an
 export function useFragment<F extends Fragment<any, any, any, any>>(
   fragment: F,
   ref: FragmentRef<F> | null | undefined,
+  opts?: QueryReleaseOptions,
 ): FragmentData<F> | null {
-  return useLocalFragment(fragment, ref);
+  return useLocalFragment(fragment, ref, opts);
 }
 
 /**
@@ -521,20 +603,23 @@ export function useFragment<F extends Fragment<any, any, any, any>>(
  * nothing). Keeps the per-row subscription isolation — a child-only edit re-renders just this read.
  */
 export function Frag<F extends AnyFragment>(
-  { of, from, fallback = null, children }: {
+  { of, from, fallback = null, releaseDelayMs, children }: {
     of: F;
     from: FragmentRef<F> | null | undefined;
     fallback?: ReactNode;
+    /** Per-call-site grace window — see {@link QueryReleaseOptions}. */
+    releaseDelayMs?: number;
     children: (data: FragmentData<F>) => ReactNode;
   },
 ): ReactNode {
-  const data = useFragment(of, from);
+  const data = useFragment(of, from, { releaseDelayMs });
   return data == null ? fallback : children(data);
 }
 
 function useLocalFragment<F extends Fragment<any, any, any, any>>(
   fragment: F,
   ref: LocalFragmentRef<F> | null | undefined,
+  opts?: QueryReleaseOptions,
 ): FragmentData<F> | null {
   const ctx = useRindleContext();
   const coverage = ref?.coverage;
@@ -550,11 +635,12 @@ function useLocalFragment<F extends Fragment<any, any, any, any>>(
     [ctx.store, coverage, fragment],
   );
 
+  const releaseDelayMs = opts?.releaseDelayMs;
   const subscribe = useCallback(
     (onStoreChange: () => void) => {
       if (!coverage || !descriptor || !query) return () => {};
-      const syncLease = ctx.syncCache.retain(coverage.key, coverage.query);
-      const localLease = ctx.cache.retain(descriptor.viewKey, query);
+      const syncLease = ctx.syncCache.retain(coverage.key, coverage.query, releaseDelayMs);
+      const localLease = ctx.cache.retain(descriptor.viewKey, query, releaseDelayMs);
       const unsubscribeSync = ctx.syncCache.subscribe(coverage.key, onStoreChange);
       const unsubscribeLocal = ctx.cache.subscribe(descriptor.viewKey, onStoreChange);
       return () => {
@@ -564,7 +650,7 @@ function useLocalFragment<F extends Fragment<any, any, any, any>>(
         ctx.syncCache.release(syncLease);
       };
     },
-    [ctx.cache, ctx.syncCache, coverage, descriptor, query],
+    [ctx.cache, ctx.syncCache, coverage, descriptor, query, releaseDelayMs],
   );
 
   // Stale-while-revalidate (see useLocalRootQueryData): project the fragment's local view as soon
@@ -822,6 +908,10 @@ interface SyncCacheEntry {
   listeners: Set<() => void>;
   unsubscribe: () => void;
   releaseTimer: ReleaseTimer | undefined;
+  /** Absolute monotonic ms this coverage's warm window expires at — same deadline rule as
+   *  {@link SplitCacheEntry.releaseDeadline}, so both caches implement the one contract documented on
+   *  {@link QueryReleaseOptions}. */
+  releaseDeadline: number;
 }
 
 interface SyncQueryHandle {
@@ -834,14 +924,17 @@ export class SyncQueryCache {
   private readonly entries = new Map<string, SyncCacheEntry>();
   private nextLeaseId = 1;
   private readonly store: Store<ColsMap>;
-  private readonly releaseDelayMs: number;
+  private readonly defaultReleaseDelayMs: number;
 
   constructor(store: Store<ColsMap>, opts: QueryCacheOptions = {}) {
     this.store = store;
-    this.releaseDelayMs = opts.releaseDelayMs ?? 0;
+    this.defaultReleaseDelayMs = Math.max(0, opts.releaseDelayMs ?? 0);
   }
 
-  retain(coverageKey: string, query: AnyQuery): SyncLease {
+  /** `releaseDelayMs` overrides the cache default for THIS lease only (see
+   *  {@link QueryReleaseOptions}) — `0` asks for no warm window of its own, though an unexpired
+   *  deadline from an earlier lease on this coverage still applies. */
+  retain(coverageKey: string, query: AnyQuery, releaseDelayMs?: number): SyncLease {
     let entry = this.entries.get(coverageKey);
     if (!entry) {
       const handle = this.createHandle(query);
@@ -851,16 +944,20 @@ export class SyncQueryCache {
         listeners: new Set(),
         unsubscribe: () => {},
         releaseTimer: undefined,
+        releaseDeadline: 0,
       };
       entry.unsubscribe = handle.subscribe(() => {
         for (const listener of entry!.listeners) listener();
       });
       this.entries.set(coverageKey, entry);
     } else if (entry.releaseTimer !== undefined) {
+      // Cancel the pending teardown — but NOT `releaseDeadline`. The timer is stale (it was armed for
+      // an entry that is live again); the deadline is an outstanding claim that must survive, or a
+      // remount would silently refresh a window that should only ever decay.
       clearTimeout(entry.releaseTimer);
       entry.releaseTimer = undefined;
     }
-    const lease = { id: this.nextLeaseId++, coverageKey };
+    const lease = { id: this.nextLeaseId++, coverageKey, releaseDelayMs: this.resolveDelay(releaseDelayMs) };
     entry.leases.push(lease);
     return lease;
   }
@@ -870,7 +967,14 @@ export class SyncQueryCache {
     if (!entry) return;
     const index = entry.leases.findIndex((l) => l.id === lease.id);
     if (index < 0) return;
-    entry.leases.splice(index, 1);
+    // Read the delay off the STORED lease, not the caller's handle — a caller can't widen its window
+    // after the fact by mutating the object `retain` handed back.
+    const [released] = entry.leases.splice(index, 1);
+    // Stamp the deadline for EVERY release, not just the last one: a sibling that is still mounted
+    // must not discard the window this lease just asked for, or the result would depend on unmount
+    // order. Recording it can never cause a premature teardown — only the last-out branch below arms
+    // a timer.
+    entry.releaseDeadline = Math.max(entry.releaseDeadline, nowMs() + released.releaseDelayMs);
     if (entry.leases.length > 0) return;
     this.scheduleRelease(lease.coverageKey, entry);
   }
@@ -905,15 +1009,30 @@ export class SyncQueryCache {
     };
   }
 
+  private resolveDelay(releaseDelayMs: number | undefined): number {
+    return Math.max(0, releaseDelayMs ?? this.defaultReleaseDelayMs);
+  }
+
+  /** Arm (or re-arm) the teardown for `entry.releaseDeadline`. Because the deadline is an ABSOLUTE
+   *  instant, re-arming is idempotent — a later release recomputes the same wake-up time instead of
+   *  restarting the window. */
   private scheduleRelease(coverageKey: string, entry: SyncCacheEntry): void {
-    if (this.releaseDelayMs <= 0) {
+    if (entry.releaseTimer !== undefined) {
+      clearTimeout(entry.releaseTimer);
+      entry.releaseTimer = undefined;
+    }
+    const remaining = entry.releaseDeadline - nowMs();
+    if (remaining <= 0) {
       this.finalizeRelease(coverageKey, entry);
       return;
     }
-    entry.releaseTimer = setReleaseTimeout(() => this.finalizeRelease(coverageKey, entry), this.releaseDelayMs);
+    entry.releaseTimer = setReleaseTimeout(() => this.finalizeRelease(coverageKey, entry), remaining);
   }
 
   private finalizeRelease(coverageKey: string, entry: SyncCacheEntry): void {
+    // `entry.leases.length > 0` is the guard that makes a live subscriber safe from a stale timer: a
+    // remount inside the window revives the entry, and the timer armed before it may still fire. Do
+    // not "simplify" this away.
     if (this.entries.get(coverageKey) !== entry || entry.leases.length > 0) return;
     entry.releaseTimer = undefined;
     entry.unsubscribe();
@@ -926,26 +1045,33 @@ export class QueryCache {
   private readonly entries = new Map<string, CacheEntry>();
   private nextLeaseId = 1;
   private readonly store: Store<ColsMap>;
-  private readonly releaseDelayMs: number;
+  private readonly defaultReleaseDelayMs: number;
 
   constructor(store: Store<ColsMap>, opts: QueryCacheOptions = {}) {
     this.store = store;
-    this.releaseDelayMs = opts.releaseDelayMs ?? 0;
+    this.defaultReleaseDelayMs = Math.max(0, opts.releaseDelayMs ?? 0);
   }
 
-  retain<Q extends AnyQuery>(viewKey: string, query: Q): QueryLease {
+  /** `releaseDelayMs` overrides the cache default for THIS lease only (see
+   *  {@link QueryReleaseOptions}). Ignored for a local-only store, whose views are always torn down
+   *  on release. */
+  retain<Q extends AnyQuery>(viewKey: string, query: Q, releaseDelayMs?: number): QueryLease {
     let entry = this.entries.get(viewKey);
     if (!entry) {
       entry = this.store.canRetainRemoteQueries()
-        ? this.createSplitEntry(viewKey, query)
+        ? this.createSplitEntry(viewKey, query, releaseDelayMs)
         : this.createMaterializedEntry(viewKey, query);
       this.entries.set(viewKey, entry);
       const lease = entry.leases[0];
       return { id: lease.id, viewKey };
     }
     if (entry.mode === "split") {
-      const lease = this.createSplitLease(viewKey, entry.handle, query);
+      // Take the new server lease FIRST, then hand the deferred ones back: `handle.retain` mints a
+      // distinct remote qid per call, so overlapping them keeps this query's coverage continuously
+      // live and the backend never re-subscribes.
+      const lease = this.createSplitLease(viewKey, entry.handle, query, releaseDelayMs);
       entry.leases.push(lease);
+      this.flushPendingReleases(entry);
       return { id: lease.id, viewKey };
     }
     const lease = this.createMaterializedLease(viewKey, query);
@@ -961,18 +1087,22 @@ export class QueryCache {
     if (index < 0) return;
     if (entry.mode === "split") {
       const [released] = entry.leases.splice(index, 1);
-      if (entry.leases.length > 0 || this.releaseDelayMs <= 0) {
+      // Stamp the deadline for EVERY release, not just the last one: a sibling that is still mounted
+      // must not discard the window this lease just asked for, or the result would depend on unmount
+      // order. Recording it can never cause a premature teardown — only the last-out branch below
+      // arms a timer.
+      entry.releaseDeadline = Math.max(entry.releaseDeadline, nowMs() + released.releaseDelayMs);
+      // A non-last lease never needs its remote lease held: the entry (and its warm local view)
+      // outlives it, and the surviving leases keep the query subscribed.
+      if (entry.leases.length > 0) {
         released.releaseRemote();
-      } else {
-        entry.pendingReleases.push(released);
-        this.scheduleSplitRelease(lease.viewKey, entry);
-      }
-      if (entry.leases.length > 0) return;
-      if (this.releaseDelayMs <= 0) {
-        entry.canonicalUnsubscribe();
-        entry.handle.destroy();
-        this.entries.delete(lease.viewKey);
+        return;
       }
+      // Last one out. Its remote lease is what keeps the warm view fed until the deadline, so it is
+      // deferred. `scheduleSplitRelease` collapses an already-expired deadline into a synchronous
+      // teardown, so both paths funnel through one place.
+      entry.pendingReleases.push(released);
+      this.scheduleSplitRelease(lease.viewKey, entry);
       return;
     }
     const [released] = entry.leases.splice(index, 1);
@@ -1030,7 +1160,11 @@ export class QueryCache {
     return this.entries.size;
   }
 
-  private createSplitEntry<Q extends AnyQuery>(viewKey: string, query: Q): SplitCacheEntry {
+  private createSplitEntry<Q extends AnyQuery>(
+    viewKey: string,
+    query: Q,
+    releaseDelayMs?: number,
+  ): SplitCacheEntry {
     const handle = this.store.createCachedQueryView(query) as unknown as CachedQueryView<AnyQuery>;
     const entry: SplitCacheEntry = {
       mode: "split",
@@ -1038,10 +1172,11 @@ export class QueryCache {
       leases: [],
       pendingReleases: [],
       releaseTimer: undefined,
+      releaseDeadline: 0,
       canonicalUnsubscribe: () => {},
       listeners: new Set(),
     };
-    entry.leases.push(this.createSplitLease(viewKey, handle, query));
+    entry.leases.push(this.createSplitLease(viewKey, handle, query, releaseDelayMs));
     entry.canonicalUnsubscribe = handle.view.subscribe(() => {
       for (const listener of entry.listeners) listener();
     });
@@ -1052,8 +1187,14 @@ export class QueryCache {
     viewKey: string,
     handle: CachedQueryView<AnyQuery>,
     query: Q,
+    releaseDelayMs?: number,
   ): SplitLease {
-    return { id: this.nextLeaseId++, viewKey, releaseRemote: handle.retain(query) };
+    return {
+      id: this.nextLeaseId++,
+      viewKey,
+      releaseRemote: handle.retain(query),
+      releaseDelayMs: this.resolveDelay(releaseDelayMs),
+    };
   }
 
   private createMaterializedEntry<Q extends AnyQuery>(viewKey: string, query: Q): MaterializedCacheEntry {
@@ -1090,9 +1231,37 @@ export class QueryCache {
     });
   }
 
+  private resolveDelay(releaseDelayMs: number | undefined): number {
+    return Math.max(0, releaseDelayMs ?? this.defaultReleaseDelayMs);
+  }
+
+  /** Hand back every deferred remote lease and cancel the pending teardown, WITHOUT touching
+   *  `entry.releaseDeadline`. Called when a retain revives the entry: the new lease covers the query,
+   *  so the deferred ones are redundant, and the timer armed for an idle entry is stale. The deadline
+   *  is not — it is an outstanding claim, and dropping it here would let a remount silently refresh a
+   *  window that must only ever decay. */
+  private flushPendingReleases(entry: SplitCacheEntry): void {
+    if (entry.releaseTimer !== undefined) {
+      clearTimeout(entry.releaseTimer);
+      entry.releaseTimer = undefined;
+    }
+    for (const stale of entry.pendingReleases.splice(0)) stale.releaseRemote();
+  }
+
+  /** Arm (or re-arm) the teardown for `entry.releaseDeadline`. Because the deadline is an ABSOLUTE
+   *  instant, re-arming is idempotent — a later release recomputes the same wake-up time instead of
+   *  restarting the window. */
   private scheduleSplitRelease(viewKey: string, entry: SplitCacheEntry): void {
-    if (entry.releaseTimer !== undefined) clearTimeout(entry.releaseTimer);
-    entry.releaseTimer = setReleaseTimeout(() => this.finalizeSplitRelease(viewKey, entry), this.releaseDelayMs);
+    if (entry.releaseTimer !== undefined) {
+      clearTimeout(entry.releaseTimer);
+      entry.releaseTimer = undefined;
+    }
+    const remaining = entry.releaseDeadline - nowMs();
+    if (remaining <= 0) {
+      this.finalizeSplitRelease(viewKey, entry);
+      return;
+    }
+    entry.releaseTimer = setReleaseTimeout(() => this.finalizeSplitRelease(viewKey, entry), remaining);
   }
 
   private finalizeSplitRelease(viewKey: string, entry: SplitCacheEntry): void {
@@ -1100,6 +1269,8 @@ export class QueryCache {
     entry.releaseTimer = undefined;
     const pending = entry.pendingReleases.splice(0);
     for (const lease of pending) lease.releaseRemote();
+    // The guard that makes a live subscriber safe from a stale timer: a remount inside the window
+    // revives the entry, and the timer armed before it may still fire. Do not "simplify" this away.
     if (entry.leases.length > 0) return;
     entry.canonicalUnsubscribe();
     entry.handle.destroy();