@rindle/react

The durable half of the splice for the mapped-table layout: the compacted body followed by whatever chunk rows have not been folded into it yet.

Chunks are ALWAYS the suffix after body — the closing checkpoint rewrites body and drops the chunks it absorbed in ONE transaction — so a reader never observes a torn state where a chunk both is and is not in the body.

Where {@link useStreamedText} subscribes by default — DEFAULT_RINDLE_API_ROUTES.stream, mirrored here rather than imported so the browser never pulls @rindle/api-server.

The default SSE transport. Absent EventSource (SSR, an older runtime, a test without jsdom) it attaches nothing and the reader stays on the durable plane — correct, just chunkier.

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.

A reusable, typed selection over a table — Relay's "fragment", promoted to a first-class value. Two verbs compose a fragment, on one axis — does its data belong to THIS row or to a related one:

• SAME node — q.include(Frag): merge its selection into this node. This is also how you root a fragment onto a base query — queries.t.where.id(x).include(Frag).
• CHILD node — q.sub(alias, child, corr, Frag): nest it under a relationship (sub's 4th arg).

A Fragment is therefore also a build transform ((q: Query<C>) => Query<C, Rels>); that call signature is the mechanism by which sub accepts a fragment as its build. Prefer include to root a fragment (canonical + merged) over calling it directly. It additionally carries its table (for {@link FragmentRef}/useFragment typing and masking). Composing fragments assembles ONE {@link Ast} → one materialization → one /query — the whole point (no request waterfall; design §1).

The data returned by useFragment(fragment, ref): the fragment's own selected columns plus immediate relationship values. Relationships whose builder is another fragment surface as opaque {@link FragmentRef}s, so child-owned payload is read only by the child fragment reader.

The opaque token a parent passes to a component that reads {@link FragmentData} for F.

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:

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.

A query's SERVER-CHANNEL state, surfaced on its {@link ArrayView } (FOLDED-MUTATIONS-DESIGN §7 — formerly conflated with pending-ness, OPTIMISTIC-WRITES-DESIGN.md §6):

• unknown — not hydrated: the server has not produced a first result for this query yet;
• complete — the server has answered. STAYS complete while a local mutation is pending (the prediction is the client's best current answer); reversion on rejection is an event (onRejected), not a downgrade of completeness;
• error — RESERVED for a future server-side, query-level error signal (see designs/101-QUERY-ERRORS-DESIGN.md); no longer produced by a pending mutation. "Is a prediction pending here?" is now a separate reactive axis (the backend's pending(qid) / onPending), not folded into this type. A backend with no server lifecycle (the in-process engine) leaves every view complete.

The SSR→SPA store handoff (SSR-DESIGN.md §6.1). Renders <Rindle> with a store that swaps from a transport-less SSR seed to the live engine WITHOUT changing a single useQuery caller — bind the app's schema + bootClient and drop it in above the tree:

• Server render + browser HYDRATION: a seed {@link Store} over a {@link OneShotBackend}, hydrated from ssrState. useQuery reads its seed via getServerSnapshot, so the server and the client's first render produce identical markup with NO engine on either side — first paint is the server-rendered data, never a "Starting…" splash that would break hydration.
• After hydration: boot() starts the wasm IVM engine (browser only), its views are seeded from the SAME snapshot (so the swap shows the SSR rows with no flash), and the live subscribe reconciles — the page is now a live SPA.

Framework-agnostic of the app: everything but schema/boot/ssrState is owned here (previously hand-rolled per app as src/RindleApp.tsx).

Merge the durable plane with the live tail.

durable is what the IVM view shows; produced is what a subscription has accumulated (the prefix it joined at, plus every chunk). Both are prefixes of the same response, so the merge is "take the longer" — no diffing, no overlap handling, no ranges.

The length comparison is the whole algorithm, which is why a caller MUST seed its accumulator with the text it joined at: a tail carrying only the chunks it received would read as shorter than the durable text and be discarded. useStreamedText does that for you.

One frame of a subscription. A subscription always begins with open and always ends with exactly one terminal frame — end, stale, or absent — after which the iterator completes.

stale and absent are the two "you are on the durable plane now" answers, and both are SAFE: the store holds everything below floorSeq and everything through durableSeq, so the reader's IVM view converges without the stream. Neither is an error.

How a stream ended.

• complete — the model finished.
• cancelled — the reader asked it to stop and the producer honoured it.
• error — the generation threw.
• interrupted — the host went away mid-generation. The one status that implies the store may be short of what was produced.

<endpoint>?streamId=…&from=…. from is the join offset; a reconnecting EventSource overrides it with its own Last-Event-ID header, which the server prefers.

How the live plane is reached. The default ({@link eventSourceTransport}) is SSE, which is what the api-server's streamFramesToSse serves and what gets Last-Event-ID resume for free. Supply your own for a WebSocket, a fetch-stream, or a test.

Read a {@link Fragment}'s local data from an opaque ref.

The query boundary calls {@link useRoot} with a fragment argument to retain the full named coverage query and receive root refs. Descendants call useFragment with those refs (or child refs returned by a parent fragment read) to open narrow local-only reads for the fields their fragment owns.

ref is an opaque token created by {@link useRoot} or returned from another local fragment read. 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.

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.

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.

The response text as it should be rendered right now: the durable prefix spliced with the live tail.

const data = useFragment(MessageFragment, message);
const text = useStreamedText({
  streamId: data.id,
  durable: assembleDurableText(data, data.chunks),
  live: data.status === "streaming" || data.status === "pending",
});

The value is monotone in practice — it only grows while a stream runs — and when the closing checkpoint compacts the chunks into the body it returns the identical string, so there is no flicker at the handoff.

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.