@rindle/react 0.7.12 → 0.8.0

package/README.md

@@ -71,3 +71,31 @@ runtime dependency of these base React bindings.
 - `queryCacheKey(query)` — the stable string key (`@rindle/client`'s `stableKey(ast)`) under which
   the cache stores that view. Same AST → same key → one shared entry, and it matches the SSR seed
   key so hydration finds the dehydrated view. Keys the view (bare AST), not the lease.
+
+## Streaming an LM response
+
+`useStreamedText({ streamId, durable, live })` renders a language-model response that is arriving on
+two planes: the checkpointed prefix through your ordinary query, and the not-yet-checkpointed tail
+over SSE. It returns the merged text.
+
+```tsx
+const data = useFragment(MessageFragment, message);
+const streaming = data.status === "streaming" || data.status === "pending";
+const text = useStreamedText({
+  streamId: data.id,
+  durable: assembleDurableText(data, data.chunks),   // body ++ the un-compacted chunk rows
+  live: streaming,
+});
+```
+
+`durable` is a string, not the row, because the column names belong to your schema — the hook never
+guesses where `body` lives. It handles the parts that are easy to get wrong: not reconnecting when the
+durable text advances, seeding the tail with the offset it joined at, closing its own `EventSource` on
+a terminal frame (`EventSource` reconnects on *any* close), keying the tail to its stream so
+switching messages can't show the previous one's text, and splicing a resumed replay at its own
+offset so an `EventSource` reconnect (which can rewind behind the tail) never duplicates text. Losing the live leg is not an error — without
+`EventSource`, or on the wrong server instance, the text still advances through the query at
+checkpoint granularity.
+
+`StreamTransport` is injectable for WebSocket, a fetch stream, or a test. Server side:
+**[`@rindle/api-server`](https://rindle.sh/docs/api-server)** (`openStream` / `subscribeStream`).

package/dist/index.d.ts

@@ -13,8 +13,17 @@ export type RootRefResult<Q extends AnyQuery, F extends Fragment<any, any, any,
 export type { ResultType } from "@rindle/client";
 export type { Fragment, FragmentData, FragmentRef } from "@rindle/client";
 export { fragmentKey } from "@rindle/client";
+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;
 }
 interface QueryLease {
@@ -24,17 +33,56 @@ interface QueryLease {
 interface SyncLease {
     id: number;
     coverageKey: string;
+    /** Resolved grace window for THIS lease (see {@link QueryReleaseOptions}). */
+    releaseDelayMs: number;
 }
 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;
+}
 declare class RindleContextValue {
     readonly store: Store<ColsMap>;
     readonly cache: QueryCache;
     readonly syncCache: SyncQueryCache;
-    constructor(store: Store<ColsMap>);
+    constructor(store: Store<ColsMap>, releaseDelayMs: number);
 }
-export declare function Rindle<S extends ColsMap>({ store, children }: RindleProps<S>): import("react").FunctionComponentElement<import("react").ProviderProps<RindleContextValue | null>>;
+export declare function Rindle<S extends ColsMap>({ store, releaseDelayMs, children }: RindleProps<S>): import("react").FunctionComponentElement<import("react").ProviderProps<RindleContextValue | null>>;
 export declare const RindleProvider: typeof Rindle;
 export declare function useRindleStore<S extends ColsMap = ColsMap>(): Store<S>;
 export interface RindleSSRProps<S extends ColsMap = ColsMap> {
@@ -69,18 +117,18 @@ export interface RindleSSRProps<S extends ColsMap = ColsMap> {
  * hand-rolled per app as `src/RindleApp.tsx`).
  */
 export declare function RindleSSR<S extends ColsMap>({ schema, ssrState, boot, children }: RindleSSRProps<S>): import("react").FunctionComponentElement<RindleProps<S>>;
-export declare function useQuery<Q extends AnyQuery>(query: Q): QueryData<Q>;
+export declare function useQuery<Q extends AnyQuery>(query: Q, opts?: QueryReleaseOptions): QueryData<Q>;
 /** The SERVER-CHANNEL state of a query's view (`@rindle/client` {@link ResultType}): `unknown` while
  *  it loads (not yet server-authoritative), `complete` once the server has answered. A pending
  *  optimistic mutation no longer moves this — that is a separate axis now (FOLDED-MUTATIONS-DESIGN
  *  §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 declare function useQueryStatus(query: AnyQuery): ResultType;
+export declare function useQueryStatus(query: AnyQuery, opts?: QueryReleaseOptions): 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 declare function useSyncQuery(query: AnyQuery): ResultType;
+export declare function useSyncQuery(query: AnyQuery, opts?: QueryReleaseOptions): ResultType;
 /** Run a named root query and expose its local React-facing data. Fragment child relationships are
  *  refs, so child components can keep owning their own local reads. Passing a root fragment as the
  *  final argument switches the result to opaque root refs for that fragment. */
@@ -102,31 +150,40 @@ export declare function useRoot<Args, Ctx extends readonly unknown[], Q extends
  * The hook opens a narrow local-only query for this exact fragment and keeps the root coverage
  * lease retained while mounted. Passing a legacy projected data object is unsupported.
  */
-export declare function useFragment<F extends Fragment<any, any, any, any>>(fragment: F, ref: FragmentRef<F> | null | undefined): FragmentData<F> | null;
+export declare function useFragment<F extends Fragment<any, any, any, any>>(fragment: F, ref: FragmentRef<F> | null | undefined, opts?: QueryReleaseOptions): FragmentData<F> | null;
 /**
  * Render-prop sugar over {@link useFragment}: does the `null` check once. `from` is a fragment ref
  * (or null/undefined — an absent to-one relationship, an emptied `.one()`, or a row deleted out from
  * under a live read); when the row is present `children(data)` renders, otherwise `fallback` (default
  * nothing). Keeps the per-row subscription isolation — a child-only edit re-renders just this read.
  */
-export declare function Frag<F extends AnyFragment>({ of, from, fallback, children }: {
+export declare function Frag<F extends AnyFragment>({ of, from, fallback, 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;
 export declare class SyncQueryCache {
     private readonly entries;
     private nextLeaseId;
     private readonly store;
-    private readonly releaseDelayMs;
+    private readonly defaultReleaseDelayMs;
     constructor(store: Store<ColsMap>, opts?: QueryCacheOptions);
-    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;
     release(lease: SyncLease): void;
     subscribe(coverageKey: string, listener: () => void): () => void;
     resultType(coverageKey: string): ResultType;
     size(): number;
     private createHandle;
+    private resolveDelay;
+    /** 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;
     private finalizeRelease;
 }
@@ -134,9 +191,12 @@ export declare class QueryCache {
     private readonly entries;
     private nextLeaseId;
     private readonly store;
-    private readonly releaseDelayMs;
+    private readonly defaultReleaseDelayMs;
     constructor(store: Store<ColsMap>, opts?: QueryCacheOptions);
-    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;
     release(lease: QueryLease): void;
     subscribe(viewKey: string, listener: () => void): () => void;
     snapshot(viewKey: string, one: boolean): unknown;
@@ -156,6 +216,16 @@ export declare class QueryCache {
     private createMaterializedLease;
     private chooseCanonical;
     private setCanonical;
+    private resolveDelay;
+    /** 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;
+    /** 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;
     private finalizeSplitRelease;
 }

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,10 +1,21 @@
 import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
 import { createLocalFragmentRefForTable, fragmentAst, isFragment, isFragmentRelationship, localQueryReadAst, localFragmentReadAst, localRootFragmentRefsAst, OneShotBackend, queryFromAst, stableKey, Store, tableMeta, } 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.js";
+export { assembleDurableText, spliceStreamText } from "@rindle/client";
 const EMPTY_ARRAY = 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;
+/** 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() {
+    return performance.now();
+}
 function setReleaseTimeout(fn, ms) {
     const timer = setTimeout(fn, ms);
     timer.unref?.();
@@ -14,15 +25,18 @@ class RindleContextValue {
     store;
     cache;
     syncCache;
-    constructor(store) {
+    constructor(store, releaseDelayMs) {
         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(null);
-export function Rindle({ store, children }) {
-    const value = useMemo(() => new RindleContextValue(store), [store]);
+export function Rindle({ store, releaseDelayMs, children }) {
+    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, delay), [store, delay]);
     return createElement(RindleContext.Provider, { value }, children);
 }
 export const RindleProvider = Rindle;
@@ -77,19 +91,20 @@ export function RindleSSR({ schema, ssrState, boot, children }) {
     }, []);
     return createElement((Rindle), { store: liveStore ?? seedStore }, children);
 }
-export function useQuery(query) {
+export function useQuery(query, opts) {
     const ctx = useRindleContext();
     const descriptor = useMemo(() => describeQuery(query), [query]);
     const queryRef = useRef(query);
     queryRef.current = query;
+    const releaseDelayMs = opts?.releaseDelayMs;
     const subscribe = useCallback((onStoreChange) => {
-        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.snapshot(descriptor.viewKey, descriptor.one), [ctx.cache, descriptor.viewKey, descriptor.one]);
     // SSR (SSR-DESIGN.md §6): the server calls `getServerSnapshot` (never `subscribe`), so it must
     // surface the dehydrated/preloaded seed directly — not the live cache, which is never retained
@@ -103,19 +118,20 @@ export function useQuery(query) {
  *  §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) {
+export function useQueryStatus(query, opts) {
     const ctx = useRindleContext();
     const descriptor = useMemo(() => describeQuery(query), [query]);
     const queryRef = useRef(query);
     queryRef.current = query;
+    const releaseDelayMs = opts?.releaseDelayMs;
     const subscribe = useCallback((onStoreChange) => {
-        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]);
     // SSR: a seeded query is server-authoritative for first paint (`complete`); otherwise `unknown`.
     const getServerSnapshot = useCallback(() => ctx.cache.serverResultType(descriptor.viewKey), [ctx.cache, descriptor.viewKey]);
@@ -124,19 +140,20 @@ export function useQueryStatus(query) {
 /** 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) {
+export function useSyncQuery(query, opts) {
     const ctx = useRindleContext();
     const descriptor = useMemo(() => describeQuery(query), [query]);
     const queryRef = useRef(query);
     queryRef.current = query;
+    const releaseDelayMs = opts?.releaseDelayMs;
     const subscribe = useCallback((onStoreChange) => {
-        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(() => {
         const live = ctx.syncCache.resultType(descriptor.leaseKey);
         return live === "unknown" && ctx.cache.serverResultType(descriptor.viewKey) === "complete" ? "complete" : live;
@@ -250,8 +267,8 @@ function useRootRefData(query, fragment) {
  * The hook opens a narrow local-only query for this exact fragment and keeps the root coverage
  * lease retained while mounted. Passing a legacy projected data object is unsupported.
  */
-export function useFragment(fragment, ref) {
-    return useLocalFragment(fragment, ref);
+export function useFragment(fragment, ref, opts) {
+    return useLocalFragment(fragment, ref, opts);
 }
 /**
  * Render-prop sugar over {@link useFragment}: does the `null` check once. `from` is a fragment ref
@@ -259,11 +276,11 @@ export function useFragment(fragment, ref) {
  * under a live read); when the row is present `children(data)` renders, otherwise `fallback` (default
  * nothing). Keeps the per-row subscription isolation — a child-only edit re-renders just this read.
  */
-export function Frag({ of, from, fallback = null, children }) {
-    const data = useFragment(of, from);
+export function Frag({ of, from, fallback = null, releaseDelayMs, children }) {
+    const data = useFragment(of, from, { releaseDelayMs });
     return data == null ? fallback : children(data);
 }
-function useLocalFragment(fragment, ref) {
+function useLocalFragment(fragment, ref, opts) {
     const ctx = useRindleContext();
     const coverage = ref?.coverage;
     const coverageDescriptor = useMemo(() => (coverage ? describeQuery(coverage.query) : undefined), [coverage]);
@@ -271,11 +288,12 @@ function useLocalFragment(fragment, ref) {
     const query = useMemo(() => (ast ? queryFromAst(ast) : undefined), [ast]);
     const descriptor = useMemo(() => (query ? describeQuery(query) : undefined), [query]);
     const projection = useMemo(() => (coverage ? new LocalFragmentProjection(fragmentAst(fragment), coverage, (table) => ctx.store.primaryKeyFor(table)) : undefined), [ctx.store, coverage, fragment]);
+    const releaseDelayMs = opts?.releaseDelayMs;
     const subscribe = useCallback((onStoreChange) => {
         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 () => {
@@ -284,7 +302,7 @@ function useLocalFragment(fragment, ref) {
             ctx.cache.release(localLease);
             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
     // as the row exists locally instead of returning null until its coverage is server-complete —
     // otherwise every nested fragment (UserBadge, TagChip, CommentCard, …) flashes empty for a
@@ -511,12 +529,15 @@ export class SyncQueryCache {
     entries = new Map();
     nextLeaseId = 1;
     store;
-    releaseDelayMs;
+    defaultReleaseDelayMs;
     constructor(store, opts = {}) {
         this.store = store;
-        this.releaseDelayMs = opts.releaseDelayMs ?? 0;
+        this.defaultReleaseDelayMs = Math.max(0, opts.releaseDelayMs ?? 0);
     }
-    retain(coverageKey, query) {
+    /** `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, query, releaseDelayMs) {
         let entry = this.entries.get(coverageKey);
         if (!entry) {
             const handle = this.createHandle(query);
@@ -526,6 +547,7 @@ export class SyncQueryCache {
                 listeners: new Set(),
                 unsubscribe: () => { },
                 releaseTimer: undefined,
+                releaseDeadline: 0,
             };
             entry.unsubscribe = handle.subscribe(() => {
                 for (const listener of entry.listeners)
@@ -534,10 +556,13 @@ export class SyncQueryCache {
             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;
     }
@@ -548,7 +573,14 @@ export class SyncQueryCache {
         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);
@@ -581,14 +613,28 @@ export class SyncQueryCache {
             release: () => view.destroy(),
         };
     }
+    resolveDelay(releaseDelayMs) {
+        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. */
     scheduleRelease(coverageKey, entry) {
-        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);
     }
     finalizeRelease(coverageKey, entry) {
+        // `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;
@@ -601,24 +647,31 @@ export class QueryCache {
     entries = new Map();
     nextLeaseId = 1;
     store;
-    releaseDelayMs;
+    defaultReleaseDelayMs;
     constructor(store, opts = {}) {
         this.store = store;
-        this.releaseDelayMs = opts.releaseDelayMs ?? 0;
+        this.defaultReleaseDelayMs = Math.max(0, opts.releaseDelayMs ?? 0);
     }
-    retain(viewKey, query) {
+    /** `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(viewKey, query, releaseDelayMs) {
         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);
@@ -636,20 +689,22 @@ export class QueryCache {
             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);
             }
+            // 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);
@@ -705,7 +760,7 @@ export class QueryCache {
     size() {
         return this.entries.size;
     }
-    createSplitEntry(viewKey, query) {
+    createSplitEntry(viewKey, query, releaseDelayMs) {
         const handle = this.store.createCachedQueryView(query);
         const entry = {
             mode: "split",
@@ -713,18 +768,24 @@ 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();
         });
         return entry;
     }
-    createSplitLease(viewKey, handle, query) {
-        return { id: this.nextLeaseId++, viewKey, releaseRemote: handle.retain(query) };
+    createSplitLease(viewKey, handle, query, releaseDelayMs) {
+        return {
+            id: this.nextLeaseId++,
+            viewKey,
+            releaseRemote: handle.retain(query),
+            releaseDelayMs: this.resolveDelay(releaseDelayMs),
+        };
     }
     createMaterializedEntry(viewKey, query) {
         const lease = this.createMaterializedLease(viewKey, query);
@@ -757,10 +818,36 @@ export class QueryCache {
                 listener();
         });
     }
+    resolveDelay(releaseDelayMs) {
+        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. */
+    flushPendingReleases(entry) {
+        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. */
     scheduleSplitRelease(viewKey, entry) {
-        if (entry.releaseTimer !== undefined)
+        if (entry.releaseTimer !== undefined) {
             clearTimeout(entry.releaseTimer);
-        entry.releaseTimer = setReleaseTimeout(() => this.finalizeSplitRelease(viewKey, entry), this.releaseDelayMs);
+            entry.releaseTimer = undefined;
+        }
+        const remaining = entry.releaseDeadline - nowMs();
+        if (remaining <= 0) {
+            this.finalizeSplitRelease(viewKey, entry);
+            return;
+        }
+        entry.releaseTimer = setReleaseTimeout(() => this.finalizeSplitRelease(viewKey, entry), remaining);
     }
     finalizeSplitRelease(viewKey, entry) {
         if (this.entries.get(viewKey) !== entry)
@@ -769,6 +856,8 @@ export class QueryCache {
         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();