experimental-a2 0.10.0 → 0.11.0

package/src/client.ts

@@ -14,7 +14,7 @@
  */
 
 // oxlint-disable no-await-in-loop -- retry/backoff/stream loops are sequential by nature
-import { A2Error } from './errors.ts'
+import { A2ClientError, asClientError } from './client-errors.ts'
 import {
   PRESENCE_TIMINGS,
   RESERVED_PARTICIPANT_IDS,
@@ -51,7 +51,17 @@ import {
   type WirePresenceSnapshot,
 } from './wire.ts'
 
-export type ConnectionStatus = 'idle' | 'connecting' | 'live' | 'closed'
+export { A2ClientError } from './client-errors.ts'
+export type { A2ClientErrorOptions } from './client-errors.ts'
+
+export type ReconnectPolicy = (failure: {
+  sessionId: string
+  error: A2ClientError | null
+  attempt: number
+}) => number | false
+
+export type ConnectionStatus =
+  'idle' | 'connecting' | 'paused' | 'live' | 'closed'
 
 /**
  * The connection, as a discriminated union — impossible states are
@@ -63,11 +73,12 @@ export type Connection =
   | { status: 'idle' }
   | {
       status: 'connecting'
-      /** Drops of an established stream so far. `0` = first connect. */
+      /** Stream restarts so far. `0` = first connect. */
       reconnects: number
       /** Why the last connection ended; `null` on the first connect. */
-      error: Error | null
+      error: A2ClientError | null
     }
+  | { status: 'paused'; reconnects: number; error: A2ClientError | null }
   | { status: 'live'; reconnects: number }
   | { status: 'closed' }
 
@@ -123,7 +134,7 @@ export type SessionSnapshot<
    * (provisional indexes past the frontier). `state` never folds
    * backscrolled events; they are display data below the frontier. */
   events: ContractEvent<D>[]
-  /** The stream frontier: the last server-confirmed index. This is the
+  /** The latest server-confirmed state index. This is the
    * `lastSeenIndex` cancellation wants. */
   index: number
   /** Backscroll progress — `loadHistory` moves it. */
@@ -161,7 +172,7 @@ export type SessionClient<
    * Optimistic append: validates locally against the reducer's event
    * schemas (instant `INVALID_PAYLOAD`, no flicker), applies to the
    * local fold, POSTs, swaps in the ack, rolls back on rejection.
-   * Auto-retries only `STORE_UNAVAILABLE`. Resolves with the appended
+   * Auto-retries `STORE_UNAVAILABLE` and transport failures. Resolves with the appended
    * events as the server recorded them. Overlapping calls on this
    * handle enter the transport in invocation order without delaying
    * their optimistic folds.
@@ -184,13 +195,17 @@ export type SessionClient<
    * closes — so independent consumers of one identity-mapped handle
    * (two hooks, a hook plus vanilla code) never fight over the
    * stream. Releasing twice is a no-op. While any lease is held the
-   * stream reconnects with backoff and resumes from the frontier.
+   * stream follows the client's reconnection policy and resumes after
+   * its last streamed event.
    */
   connect(): () => void
+  /** Restart a leased subscription immediately after its last streamed event.
+   * Preserves state, pending writes, and leases. No-op without a lease. */
+  reconnect(): void
   /**
    * The hard stop: drops every outstanding lease and closes the
    * stream now. Not terminal — a later `connect()` starts fresh from
-   * the current frontier.
+   * the last streamed event.
    */
   close(): void
 }
@@ -264,6 +279,8 @@ export type CreateClientOptions<
   reducer: Reducer<D, S, P>
   /** The route (or routes) the client speaks — see `ClientApi`. */
   api: ClientApi
+  /** Delay the next connection attempt in milliseconds, or pause with false. */
+  reconnect?: ReconnectPolicy
   /** Injectable fetch — defaults to the global. */
   fetch?: typeof globalThis.fetch
   /** Injectable WebSocket constructor for the `ws` api — defaults to
@@ -283,6 +300,13 @@ export type CreateClientOptions<
 }
 
 const PUSH_ATTEMPTS = 3
+const RETRYABLE_PUSH_CODES = new Set([
+  'STORE_UNAVAILABLE',
+  'TIMEOUT',
+  'HTTP_ERROR',
+  'CONNECTION_FAILED',
+  'UNKNOWN',
+])
 const DEFAULT_GC_TIME_MS = 5 * 60 * 1_000
 const DEFAULT_HISTORY_LIMIT = 50
 
@@ -297,6 +321,7 @@ type TransportFrame =
   | { kind: 'event'; event: WireEvent }
   | { kind: 'presence'; patch: WirePresencePatch }
   | { kind: 'presence-snapshot'; snapshot: WirePresenceSnapshot }
+  | { kind: 'activity'; idle: boolean }
   | { kind: 'ping' }
 
 type TransportPushBody = {
@@ -327,7 +352,7 @@ type Transport = {
     signal: AbortSignal
   }): AsyncIterable<TransportFrame>
   /** One attempt (the retry loop lives above the seam): resolves with
-   * the acked wire events, throws the wire-deserialized A2Error. */
+   * the acked wire events, throws A2ClientError. */
   push(body: TransportPushBody): Promise<WireEvent[]>
   /** One bounded cold read of the log, oldest first — the lane
    * `loadHistory` rides. Absent on transports without a
@@ -357,6 +382,23 @@ const sessionUrl = (url: SessionUrl, sessionId: string): string => {
   return resolved
 }
 
+const httpError = async (response: Response): Promise<A2ClientError> => {
+  const error = errorFromWire(await response.json().catch(() => null))
+  return error === null
+    ? new A2ClientError(
+        'HTTP_ERROR',
+        `request failed with ${response.status}`,
+        {
+          status: response.status,
+        },
+      )
+    : new A2ClientError(error.code, error.message, {
+        details: error.details,
+        status: response.status,
+        cause: error,
+      })
+}
+
 const httpTransport = (
   routes: { push: SessionUrl; stream: SessionUrl },
   fetchImpl: typeof globalThis.fetch,
@@ -371,8 +413,11 @@ const httpTransport = (
       `${streamUrl}${sep}sessionId=${encodeURIComponent(sessionId)}&index=${startAfter}`,
       { headers: { accept: 'text/event-stream' }, signal },
     )
-    if (!res.ok || !res.body) {
-      throw new Error(`stream failed with ${res.status}`)
+    if (!res.ok) throw await httpError(res)
+    if (!res.body) {
+      throw new A2ClientError('UNKNOWN', 'stream response has no body', {
+        status: res.status,
+      })
     }
     yield { kind: 'ping' } // connected — headers in hand, before any bytes
     const decoder = new TextDecoder()
@@ -416,6 +461,11 @@ const httpTransport = (
             if (isWirePresencePatch(parsed)) {
               yield { kind: 'presence', patch: parsed }
             }
+          } else if (
+            eventName === 'a2-activity' &&
+            (data === 'idle' || data === 'active')
+          ) {
+            yield { kind: 'activity', idle: data === 'idle' }
           }
           // Other named frames: skipped — old clients stay compatible
           // with future lanes the same way.
@@ -435,17 +485,14 @@ const httpTransport = (
     if (res.ok) {
       const rows = (await res.json()) as unknown
       if (!Array.isArray(rows) || !rows.every(isWireEvent)) {
-        throw new A2Error(
+        throw new A2ClientError(
           'STORE_UNAVAILABLE',
           'push ack was not a list of events',
         )
       }
       return rows
     }
-    throw (
-      errorFromWire(await res.json().catch(() => null)) ??
-      new A2Error('STORE_UNAVAILABLE', `push failed with ${res.status}`)
-    )
+    throw await httpError(res)
   },
 
   async history({ sessionId, gte, lte }) {
@@ -456,14 +503,11 @@ const httpTransport = (
       { headers: { accept: 'application/json' } },
     )
     if (!res.ok) {
-      throw (
-        errorFromWire(await res.json().catch(() => null)) ??
-        new A2Error('STORE_UNAVAILABLE', `history failed with ${res.status}`)
-      )
+      throw await httpError(res)
     }
     const rows = (await res.json()) as unknown
     if (!Array.isArray(rows) || !rows.every(isWireEvent)) {
-      throw new A2Error(
+      throw new A2ClientError(
         'STORE_UNAVAILABLE',
         'history response was not a list of events',
       )
@@ -495,7 +539,7 @@ const WS_OPEN = 1
 
 type PendingAck = {
   resolve: (events: WireEvent[]) => void
-  reject: (error: A2Error) => void
+  reject: (error: A2ClientError) => void
 }
 
 const webSocketUrl = (value: string): URL => {
@@ -553,7 +597,7 @@ const socketReadyWaiters = () => {
 
 const rejectPendingAcks = (pending: Map<number, PendingAck>): void => {
   if (pending.size === 0) return
-  const error = new A2Error(
+  const error = new A2ClientError(
     'STORE_UNAVAILABLE',
     'socket closed with the ack outstanding',
   )
@@ -634,7 +678,7 @@ const sessionWsTransport = (
                 frame.events.some((row) => row.sessionId !== sessionId))
             ) {
               waiter.reject(
-                new A2Error(
+                new A2ClientError(
                   'STORE_UNAVAILABLE',
                   'ack does not belong to the socket session',
                 ),
@@ -642,7 +686,7 @@ const sessionWsTransport = (
               return
             }
             if ('events' in frame) waiter.resolve(frame.events)
-            else waiter.reject(frame.error)
+            else waiter.reject(asClientError(frame.error))
             return
           }
           case 'event':
@@ -675,13 +719,15 @@ const sessionWsTransport = (
         finish(
           event.code === 1000
             ? null
-            : new Error(
+            : new A2ClientError(
+                'CONNECTION_FAILED',
                 `socket closed (${event.code}${event.reason ? `: ${event.reason}` : ''})`,
+                { closeCode: event.code, closeReason: event.reason },
               ),
         )
       })
       socket.addEventListener('error', () => {
-        finish(new Error('socket error'))
+        finish(new A2ClientError('CONNECTION_FAILED', 'socket error'))
       })
 
       const onAbort = (): void => {
@@ -727,7 +773,10 @@ const sessionWsTransport = (
         connection === undefined ||
         connection.socket.readyState !== WS_OPEN
       ) {
-        throw new A2Error('STORE_UNAVAILABLE', 'no open socket for the session')
+        throw new A2ClientError(
+          'STORE_UNAVAILABLE',
+          'no open socket for the session',
+        )
       }
       const req = nextReq
       nextReq += 1
@@ -743,7 +792,9 @@ const sessionWsTransport = (
         } catch (cause) {
           connection.pending.delete(req)
           reject(
-            new A2Error('STORE_UNAVAILABLE', 'socket send failed', { cause }),
+            new A2ClientError('STORE_UNAVAILABLE', 'socket send failed', {
+              cause,
+            }),
           )
         }
       })
@@ -898,8 +949,10 @@ const multiplexedWsTransport = (
     watchdog = setTimeout(() => {
       if (socket !== created) return
       failSocket(
-        new Error(
+        new A2ClientError(
+          'TIMEOUT',
           `socket stalled: no data for ${STREAM_TIMINGS.stallTimeoutMs}ms`,
+          { phase: 'stream', timeoutMs: STREAM_TIMINGS.stallTimeoutMs },
         ),
       )
     }, STREAM_TIMINGS.stallTimeoutMs)
@@ -932,7 +985,11 @@ const multiplexedWsTransport = (
         channel.dropped = true
         settleChannel(
           channel,
-          frame.reason === undefined ? null : new Error(frame.reason),
+          frame.error
+            ? asClientError(frame.error)
+            : frame.reason === undefined
+              ? null
+              : new A2ClientError('CONNECTION_FAILED', frame.reason),
         )
         return
       }
@@ -941,7 +998,7 @@ const multiplexedWsTransport = (
         if (waiter === undefined) return
         pending.delete(frame.req)
         if ('events' in frame) waiter.resolve(frame.events)
-        else waiter.reject(frame.error)
+        else waiter.reject(asClientError(frame.error))
         return
       }
       case 'event': {
@@ -1013,14 +1070,16 @@ const multiplexedWsTransport = (
       failSocket(
         event.code === 1000
           ? null // deliberate server close — reconnect, but not an error
-          : new Error(
+          : new A2ClientError(
+              'CONNECTION_FAILED',
               `socket closed (${event.code}${event.reason ? `: ${event.reason}` : ''})`,
+              { closeCode: event.code, closeReason: event.reason },
             ),
       )
     })
     created.addEventListener('error', () => {
       if (socket !== created) return
-      failSocket(new Error('socket error'))
+      failSocket(new A2ClientError('CONNECTION_FAILED', 'socket error'))
     })
   }
 
@@ -1069,8 +1128,10 @@ const multiplexedWsTransport = (
         if (channel.live) return
         settleChannel(
           channel,
-          new Error(
+          new A2ClientError(
+            'TIMEOUT',
             'subscribe not confirmed: is the ws route calling server.fetch with upgradeWebSocket?',
+            { phase: 'subscribe', timeoutMs: STREAM_TIMINGS.stallTimeoutMs },
           ),
         )
       }, STREAM_TIMINGS.stallTimeoutMs)
@@ -1109,7 +1170,10 @@ const multiplexedWsTransport = (
       ) {
         // Retryable by contract: the reconnect loop restores the
         // socket and the retry rides the same event ids.
-        throw new A2Error('STORE_UNAVAILABLE', 'no open socket for the session')
+        throw new A2ClientError(
+          'STORE_UNAVAILABLE',
+          'no open socket for the session',
+        )
       }
       const req = nextReq
       nextReq += 1
@@ -1126,7 +1190,9 @@ const multiplexedWsTransport = (
         } catch (cause) {
           pending.delete(req)
           reject(
-            new A2Error('STORE_UNAVAILABLE', 'socket send failed', { cause }),
+            new A2ClientError('STORE_UNAVAILABLE', 'socket send failed', {
+              cause,
+            }),
           )
         }
       })
@@ -1217,12 +1283,19 @@ export function createClient<
   const presenceDefs: Readonly<PresenceDefs> = reducer.presence
   const declaresPresence = Object.keys(presenceDefs).length > 0
   const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)
+  const clientFetch: typeof globalThis.fetch = async (input, init) => {
+    try {
+      return await fetchImpl(input, init)
+    } catch (error) {
+      throw asClientError(error, { code: 'CONNECTION_FAILED' })
+    }
+  }
   const webSocketImpl =
     options.webSocket ??
     (globalThis as { WebSocket?: ClientWebSocketConstructor }).WebSocket
   const transport = transportFor(
     api,
-    fetchImpl,
+    clientFetch,
     webSocketImpl,
     declaresPresence,
   )
@@ -1260,7 +1333,11 @@ export function createClient<
     sessionOptions?: SessionOptions<D, S>,
   ): SessionRuntime<D, S, P> => {
     // ── server truth ─────────────────────────────────────────────
-    let frontier = sessionOptions?.initialIndex ?? 0
+    let stateIndex = sessionOptions?.initialIndex ?? 0
+    let streamIndex =
+      sessionOptions?.initialState === undefined
+        ? sessionOptions?.initialIndex
+        : stateIndex
     let foldedState: S =
       sessionOptions?.initialState !== undefined
         ? sessionOptions.initialState
@@ -1268,7 +1345,7 @@ export function createClient<
     const serverEvents: ContractEvent<D>[] = (
       sessionOptions?.initialEvents ?? []
     )
-      .filter((event) => event.index <= frontier)
+      .filter((event) => event.index <= stateIndex)
       .toSorted((a, b) => a.index - b.index)
 
     // ── optimistic overlay ───────────────────────────────────────
@@ -1299,7 +1376,7 @@ export function createClient<
     let snapshot: SessionSnapshot<D, S> | null = null
     let status: ConnectionStatus = 'idle'
     let reconnects = 0
-    let lastError: Error | null = null
+    let lastError: A2ClientError | null = null
     let inFlightPushes = 0
     let pushWireTail: Promise<void> = Promise.resolve()
     let deferredHydration: SessionOptions<D, S> | undefined
@@ -1357,7 +1434,7 @@ export function createClient<
         .filter((p) => p.acked)
         .map((p) => p.acked!)
         .toSorted((a, b) => a.index - b.index)
-      const maxKnown = acked.at(-1)?.index ?? frontier
+      const maxKnown = acked.at(-1)?.index ?? stateIndex
       const unacked = pending
         .filter((p) => !p.acked)
         .map(
@@ -1383,7 +1460,8 @@ export function createClient<
         case 'live':
           return { status: 'live', reconnects }
         case 'connecting':
-          return { status: 'connecting', reconnects, error: lastError }
+        case 'paused':
+          return { status, reconnects, error: lastError }
       }
     }
 
@@ -1391,9 +1469,9 @@ export function createClient<
       const oldestLoaded = serverEvents[0]?.index ?? null
       return {
         loading: historyLoads > 0,
-        // Index 1 loaded — or a frontier of 0, an empty log as far as
+        // Index 1 loaded — or a state index of 0, an empty log as far as
         // this client knows — means nothing older is left to fetch.
-        complete: oldestLoaded === 1 || frontier === 0,
+        complete: oldestLoaded === 1 || stateIndex === 0,
         oldestLoaded,
       }
     }
@@ -1405,7 +1483,7 @@ export function createClient<
       return {
         state,
         events: [...serverEvents, ...overlay],
-        index: frontier,
+        index: stateIndex,
         history: historyState(),
         connection: connection(),
         ...(declaresPresence
@@ -1486,7 +1564,7 @@ export function createClient<
       const at = new Date(atMs)
       for (const [field, value] of Object.entries(values)) {
         if (value === null) delete entry[field]
-        else entry[field] = { value, seen: frontier, at }
+        else entry[field] = { value, seen: stateIndex, at }
       }
       const next = Object.assign(nullProtoRecord<PresenceMap>(), presenceState)
       if (Object.keys(entry).length === 0) delete next[id]
@@ -1499,7 +1577,7 @@ export function createClient<
     // dropped silently — the next send repaints. Sends are NOT
     // serialized on the ack and may overlap in flight: safe, because
     // merges are LWW by `at` per (participant, field) and one
-    // sender's stamps are monotonic. `seen` is the frontier at send
+    // sender's stamps are monotonic. `seen` is the state index at send
     // time, not at set time; `at` is the sender's monotonic stamp.
     const sendPresence = (
       values: Record<string, unknown>,
@@ -1510,7 +1588,7 @@ export function createClient<
         sessionId,
         // Every path here starts at setPresence, which requires the
         // participant.
-        presence: { participant: participant!, values, seen: frontier, at },
+        presence: { participant: participant!, values, seen: stateIndex, at },
       })
       touch(sessionId)
     }
@@ -1566,7 +1644,7 @@ export function createClient<
             ? undefined
             : presenceDefs['*']
         if (!schema) {
-          throw new A2Error(
+          throw new A2ClientError(
             'UNKNOWN_PRESENCE_FIELD',
             `no presence field '${field}' in the reducer's vocabulary`,
           )
@@ -1577,7 +1655,7 @@ export function createClient<
         }
         const result = validateSync(schema, value, `presence field '${field}'`)
         if (result.issues) {
-          throw new A2Error(
+          throw new A2ClientError(
             'INVALID_PAYLOAD',
             `invalid value for presence field '${field}'`,
             { details: result.issues },
@@ -1598,20 +1676,25 @@ export function createClient<
     }
 
     /** Pushes awaiting stream confirmation — resolved by `ingest` the
-     * moment the frontier passes their batch. */
+     * moment the state index passes their batch. */
     let confirmWatchers: Array<{ index: number; resolve: () => void }> = []
 
     /** The single ingest point: every server-confirmed event, in log
      * order, from the stream. */
     const ingest = (event: ContractEvent<D>): void => {
-      if (event.index <= frontier) return
-      frontier = event.index
-      serverEvents.push(event)
-      foldedState = reducer.fold(foldedState, event)
+      if (event.index <= (streamIndex ?? 0)) return
+      streamIndex = event.index
+      if (event.index > stateIndex) {
+        stateIndex = event.index
+        serverEvents.push(event)
+        foldedState = reducer.fold(foldedState, event)
+      } else {
+        mergeServerEvents([event], stateIndex)
+      }
       pending = pending.filter((p) => p.id !== event.id)
-      if (confirmWatchers.some((w) => w.index <= frontier)) {
-        const due = confirmWatchers.filter((w) => w.index <= frontier)
-        confirmWatchers = confirmWatchers.filter((w) => w.index > frontier)
+      if (confirmWatchers.some((w) => w.index <= stateIndex)) {
+        const due = confirmWatchers.filter((w) => w.index <= stateIndex)
+        confirmWatchers = confirmWatchers.filter((w) => w.index > stateIndex)
         for (const watcher of due) watcher.resolve()
       }
       notify()
@@ -1627,7 +1710,7 @@ export function createClient<
           ? reducer.events[event.type]
           : undefined
         if (!schema) {
-          throw new A2Error(
+          throw new A2ClientError(
             'UNKNOWN_EVENT_TYPE',
             `no event type '${String(event.type)}' in the reducer's vocabulary`,
           )
@@ -1638,7 +1721,7 @@ export function createClient<
           `event '${String(event.type)}'`,
         )
         if (result.issues) {
-          throw new A2Error(
+          throw new A2ClientError(
             'INVALID_PAYLOAD',
             `invalid payload for event '${String(event.type)}'`,
             { details: result.issues },
@@ -1654,7 +1737,7 @@ export function createClient<
     const post = async (
       body: TransportPushBody,
     ): Promise<ContractEvent<D>[]> => {
-      let lastPushError: A2Error = new A2Error(
+      let lastPushError: A2ClientError = new A2ClientError(
         'STORE_UNAVAILABLE',
         'push failed',
       )
@@ -1663,16 +1746,9 @@ export function createClient<
           const rows = await transport.push(body)
           return rows.map((row) => eventFromWire(row) as ContractEvent<D>)
         } catch (err) {
-          lastPushError =
-            err instanceof A2Error
-              ? err
-              : new A2Error('STORE_UNAVAILABLE', 'push request failed', {
-                  cause: err,
-                })
+          lastPushError = asClientError(err)
         }
-        // Only the documented retryable code retries; identical ids
-        // make the retry idempotent on the server.
-        if (lastPushError.code !== 'STORE_UNAVAILABLE') throw lastPushError
+        if (!RETRYABLE_PUSH_CODES.has(lastPushError.code)) throw lastPushError
         if (attempt < PUSH_ATTEMPTS) {
           const sleepMs = 250 * attempt
           // Wait for the clock AND, when the transport can tell us,
@@ -1707,7 +1783,7 @@ export function createClient<
             (acked) =>
               new Promise<ContractEvent<D>[]>((resolve) => {
                 const last = acked.at(-1)?.index ?? 0
-                if (frontier >= last) {
+                if (stateIndex >= last) {
                   resolve(acked)
                   return
                 }
@@ -1746,6 +1822,7 @@ export function createClient<
           inFlightPushes += 1
 
           try {
+            refreshIdleStream()
             notify() // optimistic — the view updates before the network moves
             await waitForPriorPush
             const acked = await post({
@@ -1760,6 +1837,8 @@ export function createClient<
               const entry = pending.find((p) => p.id === event.id)
               if (entry) entry.acked = event // stream retires it at its index
             }
+            if ((acked.at(-1)?.index ?? 0) > (streamIndex ?? stateIndex))
+              refreshIdleStream()
             notify()
             return acked
           } catch (err) {
@@ -1783,7 +1862,7 @@ export function createClient<
     }
 
     // ── backscroll ───────────────────────────────────────────────
-    // Cold reads of the log below the frontier. Fetched events merge
+    // Cold reads of the log below the state index. Fetched events merge
     // into `serverEvents` only — never the fold, never the overlay.
     let historyLoads = 0
     /** Calls chain per session: each resolves its bounds after the
@@ -1833,11 +1912,11 @@ export function createClient<
       }
       touch(sessionId)
       const run = historyTail.then(async () => {
-        const upper = before ?? serverEvents[0]?.index ?? frontier + 1
-        // Strictly at or below the frontier: the live stream owns
+        const upper = before ?? serverEvents[0]?.index ?? stateIndex + 1
+        // Strictly at or below the state index: the live stream owns
         // everything above it, and the optimistic overlay must never
         // collide with a backscrolled row.
-        const lte = Math.min(upper - 1, frontier)
+        const lte = Math.min(upper - 1, stateIndex)
         const gte = Math.max(1, upper - (limit ?? DEFAULT_HISTORY_LIMIT))
         if (gte > lte) return []
         const missing = missingBetween(gte, lte)
@@ -1848,9 +1927,11 @@ export function createClient<
           const rows = await readHistory({ sessionId, ...missing })
           mergeServerEvents(
             rows.map((row) => eventFromWire(row) as ContractEvent<D>),
-            frontier,
+            stateIndex,
           )
           return eventsBetween(gte, lte)
+        } catch (error) {
+          throw asClientError(error)
         } finally {
           historyLoads -= 1
           notify()
@@ -1872,6 +1953,7 @@ export function createClient<
     // `leaseEpoch` makes the outstanding releases inert).
     let generation = 0
     let active = false
+    let streamIdle = false
     let abort: AbortController | null = null
     let leases = 0
     let leaseEpoch = 0
@@ -1880,6 +1962,7 @@ export function createClient<
       touch(sessionId)
       if (!active) return
       active = false
+      streamIdle = false
       generation += 1 // the running loop notices and exits
       abort?.abort()
       abort = null
@@ -1895,9 +1978,11 @@ export function createClient<
 
     const runStream = async (run: number): Promise<void> => {
       let backoff = STREAM_TIMINGS.reconnectBaseMs
+      let attempt = 0
       // oxlint-disable no-await-in-loop -- sequential reconnect loop
       // oxlint-disable-next-line no-unmodified-loop-condition -- close() bumps `generation`
       while (generation === run) {
+        streamIdle = false
         const controller = new AbortController()
         abort = controller
         // The stall watchdog: the server heartbeats the stream, so a
@@ -1921,7 +2006,7 @@ export function createClient<
         try {
           const frames = transport.connect({
             sessionId,
-            startAfter: frontier,
+            startAfter: (streamIndex ??= stateIndex),
             signal: controller.signal,
           })
           for await (const frame of frames) {
@@ -1933,10 +2018,12 @@ export function createClient<
               // The first frame is the connection signal: the transport
               // yields it the moment the stream is established.
               backoff = STREAM_TIMINGS.reconnectBaseMs
+              attempt = 0
               wasLive = true
               status = 'live'
               lastError = null
               notify()
+              if (generation !== run) break
               if (presenceResend) {
                 const values = presenceResend
                 presenceResend = null
@@ -1944,7 +2031,20 @@ export function createClient<
               }
             }
             if (frame.kind === 'event') {
+              streamIdle = false
               ingest(eventFromWire(frame.event) as ContractEvent<D>)
+            } else if (frame.kind === 'activity') {
+              streamIdle = frame.idle
+              if (
+                streamIdle &&
+                (inFlightPushes > 0 ||
+                  pending.some(
+                    (entry) =>
+                      (entry.acked?.index ?? 0) > (streamIndex ?? stateIndex),
+                  ))
+              ) {
+                refreshIdleStream()
+              }
             } else if (frame.kind === 'presence') {
               applyPresencePatch(presencePatchFromWire(frame.patch))
             } else if (frame.kind === 'presence-snapshot') {
@@ -1961,38 +2061,91 @@ export function createClient<
         } catch (err) {
           if (generation === run) {
             lastError = stalled
-              ? new Error(
+              ? new A2ClientError(
+                  'TIMEOUT',
                   `stream stalled: no data for ${STREAM_TIMINGS.stallTimeoutMs}ms`,
+                  { phase: 'stream', timeoutMs: STREAM_TIMINGS.stallTimeoutMs },
                 )
-              : err instanceof Error
-                ? err
-                : new Error(String(err))
+              : asClientError(err)
           }
         } finally {
           clearTimeout(stall)
         }
         if (generation !== run) break
+        streamIdle = false
         if (wasLive) reconnects += 1
+        attempt += 1
+        let delay: number | false
+        try {
+          delay = options.reconnect
+            ? options.reconnect({ sessionId, error: lastError, attempt })
+            : backoff
+          if (
+            delay !== false &&
+            (!Number.isFinite(delay) || delay < 0 || delay > 2_147_483_647)
+          ) {
+            throw new RangeError(
+              'reconnect must return false or a delay from 0 to 2147483647 ms',
+            )
+          }
+        } catch (error) {
+          if (generation !== run) break
+          lastError = asClientError(error)
+          delay = false
+        }
+        if (generation !== run) break
+        if (delay === false) {
+          abort = null
+          status = 'paused'
+          notify()
+          return
+        }
+        const waiting = new AbortController()
+        abort = waiting
         status = 'connecting'
         notify()
+        if (generation !== run) break
         await new Promise<void>((resolve) => {
           let settled = false
           const finish = (): void => {
             if (settled) return
             settled = true
             clearTimeout(timer)
+            waiting.signal.removeEventListener('abort', finish)
             // oxlint-disable-next-line no-multiple-resolved -- guarded above
             resolve()
           }
-          const timer = setTimeout(finish, backoff)
+          const timer = setTimeout(finish, delay)
           ;(timer as { unref?: () => void }).unref?.()
-          abort?.signal.addEventListener('abort', finish)
+          if (waiting.signal.aborted) finish()
+          else waiting.signal.addEventListener('abort', finish, { once: true })
         })
         backoff = Math.min(backoff * 2, STREAM_TIMINGS.reconnectMaxMs)
       }
       // oxlint-enable no-await-in-loop
     }
 
+    const refreshIdleStream = (): void => {
+      if (streamIdle && status !== 'paused') reconnectStream()
+    }
+
+    const reconnectStream = (): void => {
+      touch(sessionId)
+      if (!active) return
+      streamIdle = false
+      generation += 1
+      const run = generation
+      const previous = abort
+      abort = null
+      reconnects += 1
+      status = 'connecting'
+      lastError = null
+      notify()
+      // Replace the lane before aborting so a multiplexed session keeps its socket.
+      if (active && generation === run) void runStream(run)
+      previous?.abort()
+    }
+
     const runtime: SessionRuntime<D, S, P> = {
       sessionId,
       // Only on presence-declaring contracts — the type surface
@@ -2012,6 +2165,7 @@ export function createClient<
       },
       push,
       loadHistory,
+      reconnect: reconnectStream,
       connect() {
         touch(sessionId)
         leases += 1
@@ -2019,8 +2173,10 @@ export function createClient<
         if (!active) {
           active = true
           status = 'connecting'
+          lastError = null
+          const run = generation
           notify()
-          void runStream(generation)
+          if (active && generation === run) void runStream(run)
         }
         let released = false
         return () => {
@@ -2043,7 +2199,7 @@ export function createClient<
         if (!next) return
         participant ??= next.participant
         const nextIndex = next.initialIndex ?? 0
-        if (nextIndex > frontier && inFlightPushes > 0) {
+        if (nextIndex > stateIndex && inFlightPushes > 0) {
           if (
             !deferredHydration ||
             nextIndex > (deferredHydration.initialIndex ?? 0)
@@ -2055,28 +2211,29 @@ export function createClient<
 
         const historyChanged = mergeServerEvents(
           next.initialEvents,
-          Math.min(nextIndex, frontier),
+          Math.min(nextIndex, stateIndex),
         )
-        if (next.initialState === undefined || nextIndex <= frontier) {
+        if (next.initialState !== undefined) streamIndex ??= nextIndex
+        if (next.initialState === undefined || nextIndex <= stateIndex) {
           if (historyChanged) notifyHydrated()
           return
         }
 
         // The server fold subsumes everything observed through the old
-        // frontier. Keep later optimistic work overlaid, retiring acked
-        // entries the new frontier proves are already durable.
-        frontier = nextIndex
+        // state index. Keep later optimistic work overlaid, retiring acked
+        // entries the new state index proves are already durable.
+        stateIndex = nextIndex
         foldedState = next.initialState
-        mergeServerEvents(next.initialEvents, frontier)
+        mergeServerEvents(next.initialEvents, stateIndex)
         pending = pending.filter(
-          (entry) => !entry.acked || entry.acked.index > frontier,
+          (entry) => !entry.acked || entry.acked.index > stateIndex,
         )
-        if (confirmWatchers.some((watcher) => watcher.index <= frontier)) {
+        if (confirmWatchers.some((watcher) => watcher.index <= stateIndex)) {
           const due = confirmWatchers.filter(
-            (watcher) => watcher.index <= frontier,
+            (watcher) => watcher.index <= stateIndex,
           )
           confirmWatchers = confirmWatchers.filter(
-            (watcher) => watcher.index > frontier,
+            (watcher) => watcher.index > stateIndex,
           )
           for (const watcher of due) watcher.resolve()
         }