experimental-a2 0.16.1 → 0.17.0

package/docs/guides/03-react.mdx

@@ -1,384 +1,324 @@
 ---
 title: Live UI with React
-description: "Synchronize one session from server to browser: render its state, stream new events, and push writes optimistically through one reducer."
+description: "Start from a snapshot, fold new events, and push optimistic writes through one shared session."
 ---
 
-## The model
+## One session, one state
 
-A session can be read live from the browser. The server renders the first
-paint, a stream keeps it fresh, and writes apply instantly. One reducer
-produces every one of those views; server and client fold the same log
-with the same function, so they can't disagree.
+A contract can publish one reducer. The client starts from a snapshot of
+that state and folds subsequent events locally. Initial data from a server
+component is optional. Without it, the server sends a snapshot as the first
+data frame of the subscription, then streams events after its index.
 
-That's the trick, really. The client receives one state snapshot and its log
-position, then syncs later events and folds them locally. It does not keep
-synchronizing state. An append-only log with positions is simpler.
+The same connection carries bootstrap and live events, over SSE or WebSocket.
+Events appended while the snapshot is read remain in the durable log and
+are delivered after its index. Reconnecting resumes after the last delivered
+position without fetching another snapshot.
 
-This is session sync. The client follows one known session id; it does not
-subscribe to database tables or queries across many sessions. Keep those
-collection views in your [application database](/guides/application-data).
+This is session sync. A client follows a known session ID. Keep collection
+queries across sessions in your [application database](/guides/application-data).
 
-The pieces: two route handlers (read and write), a factory that binds your
-reducer, and the provider + hook it returns.
+## Publish the state
 
-## The API route
+The reducer lives with the event vocabulary, in a shared module:
 
-`server.fetch` exposes a session over HTTP. It is bound, so the route can
-export it directly: `GET` streams events and serves history slices;
-`POST` appends.
+```ts model.ts
+import { contract } from 'experimental-a2'
+import { z } from 'zod'
 
-```ts app/api/order-events/route.ts
-import { ordersServer } from '@/server/orders'
+export const counter = contract({
+  name: 'counter',
+  events: { added: z.number() },
+  reducer: {
+    name: 'count.v1',
+    initialState: 0,
+    fold: (state, event) => state + event.payload,
+  },
+})
+```
+
+The reducer name identifies its snapshot format. Change it when the fold's
+meaning or stored shape changes. The server and client must use the same
+version. A fold returning a discriminated union may need `as const` on a
+returned literal or an explicit return type. The standalone `reducer`
+builder fixes the state type before its `.fold()` call.
+
+Additional server-side reducers can be read with `session.state(reducer)`;
+those reads do not publish another client state.
+
+```ts server/counter.ts
+import { createServer } from 'experimental-a2/server'
+import { counter } from '../model'
 
-export const GET = ordersServer.fetch
-export const POST = ordersServer.fetch
+export const counterServer = createServer({ contract: counter })
 ```
 
-`GET` is the read path. A plain `GET` is the live stream: a server-sent
-events response of one session's events, resumed after the `index` query
-parameter, so clients pick up exactly where they left off after a first
-paint or a dropped connection. A `GET` carrying `gte`/`lte` query
-parameters is a history slice instead: the bounded log range as JSON,
-the cold read [`loadHistory`](#the-client-component) rides.
-
-`POST` is the write path. The push envelope is validated, then `append` does the
-rest. The response is the appended events: an ack, not a stream. Thrown
-[`A2Error`s](/reference/errors#over-the-wire) serialize onto the wire so
-the client can branch on the same codes.
-
-Wrap `server.fetch` when the route needs authentication, per-operation
-authorization, or response decoration. `authorize` receives the parsed
-A2 operation after envelope parsing and before schema validation or I/O.
-Return `false` to answer `FORBIDDEN`. A thrown error is treated as an
-infrastructure failure.
-
-```ts
-// app/api/order-events/route.ts, now with response decoration:
-import { ordersServer } from '@/server/orders'
-
-export async function GET(request: Request): Promise<Response> {
-  const response = await ordersServer.fetch(request)
-  if (response.headers.get('a2-history-covered') === 'true') {
-    response.headers.set('cache-control', 'private, max-age=31536000')
-  }
-  return response
-}
+```ts app/api/counter/route.ts
+import { counterServer } from '../../../server/counter'
 
-export const POST = ordersServer.fetch
+export const GET = counterServer.fetch
+export const POST = counterServer.fetch
 ```
 
-## The session module
+`GET` serves the subscription and bounded history reads. `POST` appends
+writes. Wrap `server.fetch` with its `authorize` option for application
+checks. Bootstrap is authorized as a stream operation with `bootstrap: true`
+before reading state.
+
+## Bind React once
 
-Bind your reducer once, in a `'use client'` file, and export the pair:
+The factory binds the client's types into the Provider and hook. It does
+not create a separate connection pool.
 
-```tsx app/orders/[orderId]/session.ts
+```tsx app/counter/session.ts
 'use client'
 import { createClient } from 'experimental-a2/client'
 import { createReact } from 'experimental-a2/react'
-import { ordersReducer } from '@/reducer'
+import { counter } from '../../model'
 
-export const ordersClient = createClient({
-  reducer: ordersReducer,
-  api: '/api/order-events',
+export const counterClient = createClient({
+  contract: counter,
+  api: '/api/counter',
+})
+
+export const { SessionProvider, useSession } = createReact({
+  client: counterClient,
 })
-export const { SessionProvider, useSession } = createReact({ client: ordersClient })
 ```
 
-This is the whole client/server seam. `createReact` is a factory (like
-`createContext`): everything it returns is typed by the reducer value;
-the state from its fold, the pushable events from its vocabulary. No type
-arguments anywhere, and nothing in this file touches the server module.
-The client also gives every session a stable in-memory identity. Calling
-`ordersClient.session(orderId)` before navigation and mounting the provider
-after navigation reaches the same optimistic state, with no handoff store.
+```tsx app/counter/counter.tsx
+'use client'
+import { useSession } from './session'
 
-## The server component
+export function Counter() {
+  const { state, connection, push } = useSession()
+  const error = 'error' in connection ? connection.error : null
 
-The first paint costs no client JavaScript: fold on the server, pass the
-result down.
+  return (
+    <>
+      <button onClick={() => void push({ type: 'added', payload: 1 })}>
+        Count: {state}
+      </button>
+      {error && <p role="alert">{error.message}</p>}
+    </>
+  )
+}
+```
 
-```tsx app/orders/[orderId]/page.tsx
-import { ordersServer } from '@/server/orders'
-import { ordersReducer } from '@/reducer'
+`state` has the reducer's client state type. A supplied snapshot seeds the
+first render; otherwise the client displays `reducer.initialState` (through
+the reducer's client projection when present). The connection snapshot
+replaces that seed atomically, then new events update it. The seed can look
+empty while an existing session loads. Supply a server snapshot to render
+its current state immediately.
+
+`connection` stays `connecting` until bootstrap completes. Failures use its
+existing error and retry policy. A slow snapshot can keep loading while the
+connection sends heartbeats. The ordinary stream stall watchdog handles a
+silent connection. A reconnect preserves the last state.
+
+A push made during bootstrap is sent right away; it does not wait for the
+snapshot. Its optimistic update appears once the snapshot is applied. If
+the push was already sent when the snapshot arrives and has no
+acknowledgement yet, it stays hidden until the acknowledgement arrives,
+because the snapshot may already contain it. Pushes queued behind it stay
+hidden with it, so the view never skips a write. As usual, the push promise
+resolves on the server acknowledgement; `.confirmed` waits for delivery
+through the stream, and the bootstrap snapshot counts as delivery through
+its index.
+
+## Without server rendering
+
+A Provider only needs the session ID. It supplies scope and optional data;
+mounted hooks own connection leases.
+
+```tsx app/counter/page.tsx
+import { Counter } from './counter'
 import { SessionProvider } from './session'
-import { OrderClient } from './order-client'
-
-export default async function OrderPage({
-  params,
-}: {
-  params: Promise<{ orderId: string }>
-}) {
-  const { orderId } = await params
-  const session = ordersServer.session(orderId)
-  const { state, index } = await session.state(ordersReducer)
 
+export default function Page() {
   return (
-    <SessionProvider
-      sessionId={orderId}
-      initialState={state}
-      initialIndex={index}
-    >
-      <OrderClient />
+    <SessionProvider sessionId="shared">
+      <Counter />
     </SessionProvider>
   )
 }
 ```
 
-Two props do the heavy lifting. `initialState` is the fold. `initialIndex` is
-its frontier, the log position the fold reflects. The client opens its stream
-after that position. The stream catches up any events appended after the server
-fold, then stays live. No history read is needed to hydrate state.
-(No `reducer` or `api` prop: the provider got both from the shared client.)
+You can also omit the Provider. The bound hook already knows its client:
 
-## The client component
-
-```tsx app/orders/[orderId]/order-client.tsx
+```tsx app/counter/standalone.tsx
 'use client'
 import { useSession } from './session'
 
-export function OrderClient() {
-  const { state, push } = useSession()
-
+export function StandaloneCounter({ sessionId }: { sessionId: string }) {
+  const { state, push } = useSession({ sessionId })
   return (
-    <button onClick={() => push({ type: 'shop.started', payload: {} })}>
-      Start
+    <button
+      onClick={() => void push({ type: 'added', payload: 1 })}
+    >
+      {state}
     </button>
   )
 }
 ```
 
-What the hook gives you:
-
-- **`state`**: the live view, folded through the shared reducer. It
-  updates three ways: optimistically when you push, corrected when the
-  server acks, and continuously as the stream delivers events, yours and
-  everyone else's.
-- **`push`**: typed against the contract's vocabulary (via the reducer). Payloads are
-  validated locally before anything leaves the browser, apply instantly,
-  swap in the real event when the `POST` acks, and refold without it if
-  the server says no. Rejections carry the same
-  [`A2Error` codes](/reference/errors) the server throws, so both sides
-  branch on `code`. Awaiting `push(...)` gives the server ack; the
-  result also carries **`.confirmed`**, a promise for the moment the
-  live stream delivers the batch back and the view shows server truth.
-  `await push(...).confirmed` is "continue once this is real"; two
-  `performance.now()` calls around the two awaits are a complete
-  push→ack→stream latency meter. Overlapping calls on the same
-  session still apply immediately, then enter the transport in call
-  order. Controls do not need to wait or disable themselves to preserve
-  that order.
-- **`events`**: the raw events this client has observed or was explicitly
-  seeded with. With only the server snapshot, it begins after `initialIndex`.
-  Use it for UI that wants the log itself: an activity feed, a debug panel.
-  Earlier events are not needed to hydrate `state`. Later hydration can
-  advance state ahead of this feed; the stream keeps its own resume position
-  and adds delayed events without folding them again.
-- **`loadHistory`**: backscroll. `loadHistory({ before?, limit? })`
-  fetches a bounded slice of the log from below the frontier (the same
-  route, `gte`/`lte` query parameters) and merges it into `events`:
-  deduped, ordered, shared across every handle of the session. By
-  default each call walks backward 50 events at a time from the oldest
-  one loaded, including after a newer snapshot hydrates the session.
-  Pass an explicit `before` to read another range. It never touches `state`
-  or the optimistic overlay; backscrolled events are display data.
-  Calls serialize per session, so
-  a double-tap never fetches the same range twice. The `ws` api has no
-  history lane; `loadHistory` throws a `TypeError` there.
-- **`history`**: backscroll progress, `{ loading, complete,
-  oldestLoaded }`. `complete` means the feed reaches index 1 (or the
-  log is empty): nothing older is left, hide the "load older" button.
-- **`index`**: the latest server-confirmed state index, advanced by
-  snapshots and streamed events. This is the `lastSeenIndex` that makes
-  [cancellation](/guides/cancellation) exact.
-- **`connection`**: a discriminated union of `{ status: 'idle' }`,
-  `{ status: 'connecting', reconnects, error }`,
-  `{ status: 'paused', reconnects, error }`,
-  `{ status: 'live', reconnects }`, or `{ status: 'closed' }`. A status
-  dot is one ternary away; "reconnecting…" is
-  `status === 'connecting' && reconnects > 0`; `error` (why the last
-  connection ended) only exists while disconnected, so impossible
-  states don't compile. It's honest about silence, too: the server
-  heartbeats the stream (`: ping` every 15s), and a client that hears
-  nothing for two beats treats the connection as dead and reconnects, so
-  `live` means bytes are flowing, not "the socket hasn't errored yet".
-
-The provider opens the stream on mount, closes it on unmount, and
-reconnects with backoff, resuming from `index`, when the connection
-drops. Components that only write don't need the hook; `POST` to the
-route directly, or call `ordersClient.session(id).push(...)` so a later
-provider sees the same optimistic session.
-
-Polling streams start fast and back off to a two-second interval when idle.
-Idle is a polling state; the connection remains live and heartbeats continue.
-When you call `push()` on an idle SSE stream, the client refreshes that stream
-immediately, without reconnect backoff. It resumes from its existing `index`,
-so concurrent events before the write's acknowledged index are still read.
-Overlapping pushes share the refreshed stream. If a slow push is still pending
-when the stream idles again, or its acknowledged events have not arrived, the
-client refreshes again. WebSockets wake the session's attached read loop
-without replacing the socket. This is internal and requires no component
-configuration.
-
-Use `reconnect()` after a custom REST request commits a change outside
-`push()`. It is available on the session client and the `useSession()` result.
-It immediately restarts the live subscription from its current `index`, even
-when the stream is active. State, optimistic writes, and connection leases
-are preserved. Without an active lease it does nothing.
-
-`reconnect()` returns `void`; observe `connection` and `index` for progress.
-SSE opens a fresh GET. A single-session WebSocket opens a fresh socket; a
-multiplexed WebSocket re-subscribes only this session on its existing socket.
-Other subscribed sessions keep running. Any outstanding write interrupted by
-a socket replacement uses the normal idempotent retry path.
-
-The server stops the old session lane before authorizing its replacement.
-That lane stays closed if authorization denies access or fails. Successful
-authorization catches up from the cursor. Already accepted writes can finish,
-and failed subscription attempts follow the normal reconnect retry policy.
-
-Configure `createClient({ reconnect })` on a shared client to choose each
-retry's delay or return `false` to pause automatic reconnection. The callback
-receives `{ sessionId, error, attempt }`; `error` is an `A2ClientError`, or
-`null` when the stream ended cleanly. `attempt` starts at 1 and resets when
-the connection becomes live or you call `reconnect()` explicitly.
-
-A paused connection keeps the hydrated session, its writer, and its existing
-state. Observe `connection.status === 'paused'` and use the hook's
-`reconnect()` to resume when your application is ready. New consumers and
-pushes do not automatically resume it. Configure the policy where you create
-the client, without changing the hook's `hydrate` input.
-
-That identity is an in-memory L1, not another source of truth. Repeated
-`session(id)` calls reuse it while active and for five idle minutes by
-default. A newer server fold advances it, pending pushes stay overlaid,
-and a stale server render cannot rewind it. The optional IndexedDB cache
-is the L2: it survives reloads; the memory runtime does not. The
-stream is shared the same way: `connect()` takes a lease and returns
-its release, so however many hooks, providers, or plain calls hold one
-session open, the first lease connects and the last release closes
-(`close()` is the hard stop).
-
-One detail worth knowing: every push carries a client-generated event id.
-That id is how the ack finds its optimistic entry, and it makes retrying
-a failed `POST` idempotent. `push` retries `STORE_UNAVAILABLE` and client
-transport failures, with a three-attempt budget.
-
-Optimistic pushes are also what make [cancellation](/guides/cancellation)
-feel instant: the `cancelled` event folds locally before the server ever
-sees it.
-
-Sessions can outlive the tab, too: hand `createReact` a `cache` and
-revisits paint from the local copy, the stream resumes from the cached
-frontier, and offline pushes queue and replay. See
-[Local-first](/guides/local-first).
-
-## Client-first sessions
-
-Everything above assumes a server component hands the first fold down.
-A client-rendered app often has nothing to hand: a sidebar showing ten
-channel sessions, a user session read from deep inside a menu, panes
-that mount from client-side navigation. No server fold, and no natural
-provider boundary for components that reach sessions ad hoc.
-
-For that shape, `experimental-a2/react` exports a standalone hook. Any
-component can mount any session, no provider needed:
-
-```tsx app/orders/[orderId]/order-badge.tsx
-'use client'
-import { useSession } from 'experimental-a2/react'
-import { ordersClient } from './session'
-
-export function OrderBadge({ orderId }: { orderId: string }) {
-  // your fetch (SWR, a router loader, a parent's payload): anything
-  // that lands the { state, index } your route returns (below), e.g.
-  // const { data } = useSWR(`/api/orders/${orderId}/state`)
-  const data = undefined // still loading
-
-  const { state } = useSession(ordersClient, orderId, { hydrate: data })
-  if (!data) return <span>…</span> // your loading state IS the pending state
-  return <span>{state.status}</span>
+The direct `useSession(client, sessionId, options?)` export is available
+when you do not use the factory. It has the same bootstrap and connection
+ownership behavior.
+
+## Seed the first render
+
+Server rendering can skip the bootstrap read. Supply the state and its
+index together:
+
+```tsx app/seeded-counter/page.tsx
+import { counterServer } from '../../server/counter'
+import { Counter } from '../counter/counter'
+import { SessionProvider } from '../counter/session'
+
+export default async function Page() {
+  const initial = await counterServer.session('shared').state()
+  return (
+    <SessionProvider
+      sessionId="shared"
+      initial={initial}
+    >
+      <Counter />
+    </SessionProvider>
+  )
 }
 ```
 
-The fold comes from your own route, and the route is one line of A2:
+Index 10 means this state already includes events through 10. The stream
+starts after 10. Index 0 is valid when paired with the reducer's initial
+state; that explicitly requests replay from the beginning. An index by
+itself cannot describe a reducer state.
+
+A standalone hook can receive the same pair as `initial`. Omitting
+it enables automatic bootstrap. For an asynchronous server read, pass its
+Promise as described below.
+
+SSR uses render-local snapshots. One request's seed does not modify another
+request's state, and browser hydration first renders the supplied snapshot
+even when the shared browser cache has already advanced.
+
+`hydrated` distinguishes the reducer seed from a known state/index snapshot.
+It is `false` until a supplied snapshot or subscription bootstrap initializes
+the session, including while a cold preload is pending or rejected. A snapshot
+at index 0 counts. Once initialized, it stays `true` through disconnections,
+reconnects, and disabled readers while the session retains its state. A new
+session without a seed starts at `false` again.
+
+Use `hydrated` when a decision needs initialized state, such as distinguishing
+an empty queue from one that has not loaded. `connection` describes the
+transport independently. A hydrated snapshot may be stale and does not imply
+permission to write. Imperative code reads the same flag from
+`client.session(id).getSnapshot().hydrated`.
+
+## Start a preload on the server
+
+`initial` also accepts a stable Promise of a snapshot. A pending preload
+blocks only cold startup: A2 waits before opening its subscription, displaying
+`reducer.initialState` without suspending the UI by default. A snapshot result
+replaces that seed and skips the
+bootstrap read. A `null` or `undefined` result uses ordinary subscription
+bootstrap. No additional request is started to resolve the Promise.
+
+```tsx app/preloaded-counter/page.tsx
+import { Suspense } from 'react'
+import { counterServer } from '../../server/counter'
+import { SessionProvider } from '../counter/session'
+import { PreloadedCounter } from './counter'
+
+export default function Page() {
+  const initial = counterServer.session('shared').state()
+  return (
+    <SessionProvider sessionId="shared" initial={initial}>
+      <h1>Counter</h1>
+      <Suspense fallback={<p>Loading counter…</p>}>
+        <PreloadedCounter />
+      </Suspense>
+    </SessionProvider>
+  )
+}
+```
 
-```ts app/api/orders/[orderId]/state/route.ts
-import { ordersServer } from '@/server/orders'
-import { ordersReducer } from '@/reducer'
+```tsx app/preloaded-counter/counter.tsx
+'use client'
+import { useSession } from '../counter/session'
 
-export async function GET(
-  _req: Request,
-  { params }: { params: Promise<{ orderId: string }> },
-) {
-  const { orderId } = await params
-  // here's where you'd do auth, or any other checks
-  return Response.json(
-    await ordersServer.session(orderId).state(ordersReducer),
+export function PreloadedCounter() {
+  const { state, push } = useSession({ suspend: true })
+  return (
+    <button
+      onClick={() => void push({ type: 'added', payload: 1 })}
+    >
+      {state}
+    </button>
   )
 }
 ```
 
-Note what is not on the wire: a reducer name. The route calls
-`session.state(reducer)` with the reducer by reference, the same
-module your client bundle folds with. That matters because renaming a
-reducer is the [snapshot invalidation knob](/concepts/state): if the
-name traveled on the wire, every rename would open a version-skew
-window between deployed clients and servers. By reference, the knob
-stays free. And unlike a history slice, which is immutable once read
-and earns a standard wire shape, a state read is a moving snapshot;
-there is nothing for the library to standardize, so the read stays
-behind your route, under your auth and caching policy.
-
-`hydrate` is one atomic option: the `{ state, index }` pair
-`session.state(reducer)` returns. State and its frontier travel
-together or not at all; a half-present handoff cannot compile. While
-it is `undefined` (your fetch has not landed), the hook holds the
-stream and `state` is the reducer's `initialState`. There is no
-pending flag on the result: whether the fold has been handed over is
-your own input, so your data layer's loading state is the pending
-state. When the value arrives, the session hydrates
-and the stream connects at that frontier. The hold is deliberate:
-connecting without a fold means replaying the whole log through the
-browser, and the library never picks the expensive path silently. When
-a full replay is what you want (a short log, a debug view), hand the
-fold's true starting point:
-`hydrate: { state: ordersReducer.initialState, index: 0 }`. State at
-index 0 is the reducer's seed by definition, so the explicit replay
-needs no special vocabulary; the stream then delivers every event
-live.
-
-The rest behaves like the provider. The handle is identity-mapped
-(every hook and provider mounting the same session shares one runtime)
-and each mount holds a lease on the shared stream (see
-[the client identity note](#the-client-component)). A later, further
-fold handed to the same session
-advances it and a stale one is ignored, the same never-move-backward
-rule as everywhere else. For presence, identity comes from the
-client's `participant` (set once on `createClient`) or the hook's
-`participant` option, which overrides it. The
-result is exactly the shape the bound hook returns. There is no
-loading or error member: the
-library performs no fetch here, so your data layer's states are the
-states, retried however your data layer retries.
-
-`SessionProvider` keeps its required `initialState`/`initialIndex`.
-The provider is the server-handoff tool; the hook is the client-first
-tool.
-
-## Keep the backend out of the bundle
-
-The split is structural, not disciplinary. Core `experimental-a2` (the contract,
-reducers, errors) imports no backend, ever; only `experimental-a2/server` can reach
-one, and its exports map resolves to a loud error under the browser
-condition. The layout above rides that:
-
-1. `contracts.ts` and `reducer.ts` import nothing but schemas and `experimental-a2`,
-   isomorphic by construction.
-2. The session module imports the reducer, never `experimental-a2/server`. Client
-   components don't need the server's *type*, even: the factory carries
-   all the typing.
-
-Belt and suspenders: put `import 'server-only'` at the top of your
-server module and enable `verbatimModuleSyntax` in your tsconfig; an
-accidental value import then fails your build too, with your own error
-message.
+A rejected cold preload pauses startup and reports its error through
+`connection`. A2 cannot retry an externally created Promise: supply a new
+Promise, a snapshot, or `null` to continue. The caller can catch a preload
+failure and return `null` when bootstrap fallback is appropriate.
+
+A warm session keeps its state and connection while another initial Promise
+is pending. A newer successful snapshot follows the normal hydration rules;
+a rejected late preload does not disrupt a working session. Replaced sources
+and hard close invalidate pending results, including deferred hydration.
+Unmounting releases that hook's connection lease; it does not cancel the
+caller's fetch. Within a cached session, repeating the same Promise does not
+restart cancelled work.
+
+Each hook can opt into React Suspense with `useSession({ suspend: true })`.
+It reads the supplied Promise with React `use()`. The nearest Suspense and
+Error boundaries handle its pending and rejected states. The Provider itself
+does not suspend. Without a Promise, or when it resolves to no snapshot,
+ordinary subscription bootstrap displays the reducer seed without suspending.
+`enabled` continues to control connection ownership separately.
+
+A non-suspending preload renders the reducer seed on the server. Await the
+snapshot upstream or use the suspending hook within an appropriate boundary
+to render the loaded session in the server response. Keep
+Promise identity stable across client renders; do not create it inside the
+component that consumes it.
+
+## Connections and activation
+
+Hooks using the same client instance and session ID share one runtime,
+connection, state, and optimistic queue. Providers do not determine deduplication.
+Another client instance is isolated, even when its URL matches.
+
+`useSession({ enabled: false })` observes cached or initial data without
+acquiring an automatic connection lease. The default is `true`. Disabling
+or unmounting a hook releases only its own lease. Another enabled consumer
+continues normally. Explicit pushes still work and acquire a connection
+when needed; disabling is not an authorization boundary.
+
+The bound hook accepts `sessionId`, `client`, `participant`, `initial`,
+`enabled`, and `suspend` options. Initial data and participant defaults are inherited
+only when the resolved client and session ID match the Provider's scope.
+
+## Events and history
+
+`useSession()` returns `state`, `events`, `index`, `connection`, `push`,
+`reconnect`, `loadHistory`, and `history`. Presence contracts also return
+`presence` and `setPresence`.
+
+`events` contains supplied history, loaded history, received events, and
+pending optimistic events. A bootstrap snapshot does not invent historical
+rows. Without `initialEvents`, the array starts empty and receives events
+after the snapshot's index.
+
+`loadHistory({ before, limit })` reads older log entries into that array.
+Omit the options to load up to 50 events before the oldest loaded event.
+History reads do not change state or rewind the live cursor. `history`
+reports loading, the oldest loaded index, and whether the beginning is
+loaded. History reads currently require the HTTP transport.
+
+The array is an in-memory collection, not a paginated projection. Long-lived
+sessions can accumulate many events; a state snapshot bounds replay work,
+not the size of state or retained history.