experimental-a2 0.9.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
 }
@@ -217,16 +232,21 @@ export type A2Client<
 }
 
 /**
- * The wire the client rides. The string form is one route serving GET
+ * The wire the client rides. The first form is one route serving GET
  * (SSE stream) + POST (push). `http` splits the verbs across two
  * routes, for when platform duration limits differ per verb. `ws`
- * rides everything — every session of this client — over one
- * multiplexed WebSocket, served by `sessionsSocket`.
+ * rides everything over WebSocket, one socket per session by default.
+ * Multiplexing every session of the client is an explicit opt-in.
  */
+export type SessionUrl = string | ((sessionId: string) => string)
+
 export type ClientApi =
-  | string // one route: GET SSE stream + POST push
-  | { type: 'http'; push: string; stream: string } // split routes
-  | { type: 'ws'; url: string } // one socket, all sessions, both directions
+  | SessionUrl // one route: GET SSE stream + POST push
+  | { type: 'http'; push: SessionUrl; stream: SessionUrl } // split routes
+  /** One socket per session. */
+  | { type: 'ws'; url: SessionUrl; multiplex?: false }
+  /** One socket for every session of this client. */
+  | { type: 'ws'; url: string; multiplex: true }
 
 /**
  * The socket surface the `ws` transport drives — satisfied structurally
@@ -259,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
@@ -278,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
 
@@ -292,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 = {
@@ -322,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
@@ -344,21 +374,50 @@ type Transport = {
   awaitReady?(sessionId: string, maxWaitMs: number): Promise<void>
 }
 
+const sessionUrl = (url: SessionUrl, sessionId: string): string => {
+  const resolved = typeof url === 'function' ? url(sessionId) : url
+  if (typeof resolved !== 'string') {
+    throw new TypeError('a session URL function must return a 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: string; stream: string },
+  routes: { push: SessionUrl; stream: SessionUrl },
   fetchImpl: typeof globalThis.fetch,
   // Contracts that declare no presence skip presence frames unparsed,
   // exactly like unknown named frames.
   presence: boolean,
 ): Transport => ({
   async *connect({ sessionId, startAfter, signal }) {
-    const sep = routes.stream.includes('?') ? '&' : '?'
+    const streamUrl = sessionUrl(routes.stream, sessionId)
+    const sep = streamUrl.includes('?') ? '&' : '?'
     const res = await fetchImpl(
-      `${routes.stream}${sep}sessionId=${encodeURIComponent(sessionId)}&index=${startAfter}`,
+      `${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()
@@ -402,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.
@@ -413,7 +477,7 @@ const httpTransport = (
   },
 
   async push(body) {
-    const res = await fetchImpl(routes.push, {
+    const res = await fetchImpl(sessionUrl(routes.push, body.sessionId), {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify(body),
@@ -421,34 +485,29 @@ 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 }) {
-    const sep = routes.stream.includes('?') ? '&' : '?'
+    const streamUrl = sessionUrl(routes.stream, sessionId)
+    const sep = streamUrl.includes('?') ? '&' : '?'
     const res = await fetchImpl(
-      `${routes.stream}${sep}sessionId=${encodeURIComponent(sessionId)}&gte=${gte}&lte=${lte}`,
+      `${streamUrl}${sep}sessionId=${encodeURIComponent(sessionId)}&gte=${gte}&lte=${lte}`,
       { 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',
       )
@@ -459,11 +518,14 @@ const httpTransport = (
   sendPresence(envelope) {
     void (async () => {
       try {
-        const res = await fetchImpl(routes.push, {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify(envelope),
-        })
+        const res = await fetchImpl(
+          sessionUrl(routes.push, envelope.sessionId),
+          {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(envelope),
+          },
+        )
         await res.arrayBuffer()
       } catch {
         // Dropped by design — nothing was ever true.
@@ -475,6 +537,296 @@ const httpTransport = (
 /** `WebSocket.OPEN` — fixed by the spec, identical in every runtime. */
 const WS_OPEN = 1
 
+type PendingAck = {
+  resolve: (events: WireEvent[]) => void
+  reject: (error: A2ClientError) => void
+}
+
+const webSocketUrl = (value: string): URL => {
+  let resolved: URL
+  if (/^(https?|wss?):\/\//i.test(value)) {
+    resolved = new URL(value)
+  } else {
+    const base = (globalThis as { location?: { href: string } }).location?.href
+    if (base === undefined) {
+      throw new TypeError(
+        `cannot resolve the relative ws url '${value}' without a browser location — pass an absolute ws:// or wss:// url`,
+      )
+    }
+    resolved = new URL(value, base)
+  }
+  if (resolved.protocol === 'http:') resolved.protocol = 'ws:'
+  else if (resolved.protocol === 'https:') resolved.protocol = 'wss:'
+  return resolved
+}
+
+const socketReadyWaiters = () => {
+  const sessions = new Map<string, Set<() => void>>()
+
+  const notify = (sessionId: string): void => {
+    const waiters = sessions.get(sessionId)
+    if (!waiters) return
+    sessions.delete(sessionId)
+    for (const waiter of waiters) waiter()
+  }
+
+  const wait = (sessionId: string, maxWaitMs: number): Promise<void> =>
+    new Promise((resolve) => {
+      let waiters = sessions.get(sessionId)
+      if (!waiters) {
+        waiters = new Set()
+        sessions.set(sessionId, waiters)
+      }
+      let settled = false
+      const done = (): void => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        waiters.delete(done)
+        if (waiters.size === 0) sessions.delete(sessionId)
+        // oxlint-disable-next-line promise/no-multiple-resolved -- `settled` guards the timer and notification callers
+        resolve()
+      }
+      const timer = setTimeout(done, maxWaitMs)
+      ;(timer as { unref?: () => void }).unref?.()
+      waiters.add(done)
+    })
+
+  return { notify, wait }
+}
+
+const rejectPendingAcks = (pending: Map<number, PendingAck>): void => {
+  if (pending.size === 0) return
+  const error = new A2ClientError(
+    'STORE_UNAVAILABLE',
+    'socket closed with the ack outstanding',
+  )
+  for (const waiter of pending.values()) waiter.reject(error)
+  pending.clear()
+}
+
+const sessionWsTransport = (
+  url: SessionUrl,
+  webSocketImpl: ClientWebSocketConstructor | undefined,
+  presence: boolean,
+): Transport => {
+  type SocketConnection = {
+    socket: ClientWebSocket
+    pending: Map<number, PendingAck>
+  }
+
+  const connections = new Map<string, SocketConnection>()
+  const ready = socketReadyWaiters()
+  let nextReq = 1
+
+  const socketUrl = (sessionId: string, startAfter: number): string => {
+    const resolved = webSocketUrl(sessionUrl(url, sessionId))
+    resolved.searchParams.set('sessionId', sessionId)
+    resolved.searchParams.set('index', String(startAfter))
+    return resolved.href
+  }
+
+  return {
+    async *connect({ sessionId, startAfter, signal }) {
+      if (webSocketImpl === undefined) {
+        throw new TypeError(
+          'no WebSocket implementation available — pass one via createClient({ webSocket }) where the global is missing',
+        )
+      }
+      const socket = new webSocketImpl(socketUrl(sessionId, startAfter))
+      const connection: SocketConnection = { socket, pending: new Map() }
+      connections.set(sessionId, connection)
+
+      const queue: TransportFrame[] = []
+      let ended = false
+      let failure: Error | null = null
+      let wake: (() => void) | null = null
+      const notify = (): void => {
+        wake?.()
+        wake = null
+      }
+      const finish = (error: Error | null): void => {
+        if (ended) return
+        ended = true
+        failure = error
+        if (connections.get(sessionId) === connection) {
+          connections.delete(sessionId)
+        }
+        rejectPendingAcks(connection.pending)
+        notify()
+      }
+
+      socket.addEventListener('open', () => {
+        if (connections.get(sessionId) !== connection || ended) return
+        queue.push({ kind: 'ping' })
+        notify()
+        ready.notify(sessionId)
+      })
+      socket.addEventListener('message', (event) => {
+        if (connections.get(sessionId) !== connection || ended) return
+        if (typeof event.data !== 'string') return
+        const frame = parseSocketFrame(event.data)
+        if (frame === null) return
+        switch (frame.kind) {
+          case 'ack': {
+            const waiter = connection.pending.get(frame.req)
+            if (waiter === undefined) return
+            connection.pending.delete(frame.req)
+            if (
+              frame.sessionId !== undefined ||
+              ('events' in frame &&
+                frame.events.some((row) => row.sessionId !== sessionId))
+            ) {
+              waiter.reject(
+                new A2ClientError(
+                  'STORE_UNAVAILABLE',
+                  'ack does not belong to the socket session',
+                ),
+              )
+              return
+            }
+            if ('events' in frame) waiter.resolve(frame.events)
+            else waiter.reject(asClientError(frame.error))
+            return
+          }
+          case 'event':
+            if (frame.event.sessionId !== sessionId) return
+            queue.push({ kind: 'event', event: frame.event })
+            break
+          case 'presence':
+            if (presence && frame.sessionId === undefined) {
+              queue.push({ kind: 'presence', patch: frame.patch })
+            }
+            break
+          case 'presence-snapshot':
+            if (presence && frame.sessionId === undefined) {
+              queue.push({
+                kind: 'presence-snapshot',
+                snapshot: frame.snapshot,
+              })
+            }
+            break
+          case 'ping':
+            queue.push(frame)
+            break
+          case 'subscribed':
+          case 'unsubscribed':
+            return
+        }
+        notify()
+      })
+      socket.addEventListener('close', (event) => {
+        finish(
+          event.code === 1000
+            ? null
+            : new A2ClientError(
+                'CONNECTION_FAILED',
+                `socket closed (${event.code}${event.reason ? `: ${event.reason}` : ''})`,
+                { closeCode: event.code, closeReason: event.reason },
+              ),
+        )
+      })
+      socket.addEventListener('error', () => {
+        finish(new A2ClientError('CONNECTION_FAILED', 'socket error'))
+      })
+
+      const onAbort = (): void => {
+        finish(
+          signal.reason instanceof Error
+            ? signal.reason
+            : new Error('stream aborted'),
+        )
+        try {
+          socket.close(1000)
+        } catch {
+          // Already closed.
+        }
+      }
+      if (signal.aborted) onAbort()
+      else signal.addEventListener('abort', onAbort, { once: true })
+
+      try {
+        for (;;) {
+          while (queue.length > 0) yield queue.shift()!
+          if (ended) {
+            if (failure) throw failure
+            return
+          }
+          await new Promise<void>((resolve) => {
+            wake = resolve
+          })
+        }
+      } finally {
+        signal.removeEventListener('abort', onAbort)
+        finish(null)
+        try {
+          socket.close(1000)
+        } catch {
+          // Already closed.
+        }
+      }
+    },
+
+    async push(body) {
+      const connection = connections.get(body.sessionId)
+      if (
+        connection === undefined ||
+        connection.socket.readyState !== WS_OPEN
+      ) {
+        throw new A2ClientError(
+          'STORE_UNAVAILABLE',
+          'no open socket for the session',
+        )
+      }
+      const req = nextReq
+      nextReq += 1
+      return await new Promise<WireEvent[]>((resolve, reject) => {
+        connection.pending.set(req, { resolve, reject })
+        const frame: SocketPushFrame = {
+          kind: 'push',
+          req,
+          events: body.events,
+        }
+        try {
+          connection.socket.send(JSON.stringify(frame))
+        } catch (cause) {
+          connection.pending.delete(req)
+          reject(
+            new A2ClientError('STORE_UNAVAILABLE', 'socket send failed', {
+              cause,
+            }),
+          )
+        }
+      })
+    },
+
+    awaitReady(sessionId, maxWaitMs) {
+      const connection = connections.get(sessionId)
+      if (connection?.socket.readyState === WS_OPEN) return Promise.resolve()
+      return ready.wait(sessionId, maxWaitMs)
+    },
+
+    sendPresence(envelope) {
+      const connection = connections.get(envelope.sessionId)
+      if (
+        connection === undefined ||
+        connection.socket.readyState !== WS_OPEN
+      ) {
+        return
+      }
+      const frame: SocketPresenceFrame = {
+        kind: 'presence',
+        ...envelope.presence,
+      }
+      try {
+        connection.socket.send(JSON.stringify(frame))
+      } catch {
+        return
+      }
+    },
+  }
+}
+
 /** One session's lane on the shared ws socket — created per `connect`
  * attempt, so `startAfter` is that attempt's resume frontier. */
 type WsChannel = {
@@ -502,15 +854,11 @@ const subscribeFrame = (
   return JSON.stringify(frame)
 }
 
-const wsTransport = (
+const multiplexedWsTransport = (
   url: string,
   webSocketImpl: ClientWebSocketConstructor | undefined,
   presence: boolean,
 ): Transport => {
-  type PendingAck = {
-    resolve: (events: WireEvent[]) => void
-    reject: (error: A2Error) => void
-  }
   // ONE socket serves every session of this client (specs §13's
   // multiplexed superset): channels subscribe on it at their own
   // frontiers, down frames route back by sessionId, acks by req.
@@ -518,41 +866,12 @@ const wsTransport = (
   const pending = new Map<number, PendingAck>()
   /** Push retries parked in `awaitReady`, flushed per session on its
    * subscribe confirmation. */
-  const readyWaiters = new Map<string, Set<() => void>>()
+  const ready = socketReadyWaiters()
   let socket: ClientWebSocket | null = null
   let socketOpen = false
   let watchdog: ReturnType<typeof setTimeout> | undefined
   let nextReq = 1
 
-  const flushReadyWaiters = (sessionId: string): void => {
-    const waiters = readyWaiters.get(sessionId)
-    if (!waiters) return
-    readyWaiters.delete(sessionId)
-    for (const waiter of waiters) waiter()
-  }
-
-  const socketUrl = (): string => {
-    let resolved: URL
-    if (/^(https?|wss?):\/\//i.test(url)) {
-      resolved = new URL(url)
-    } else {
-      // A relative url resolves against the page, exactly like fetch.
-      // Outside a browser (SSR, tests) there is nothing to resolve
-      // against — demand an absolute url there.
-      const base = (globalThis as { location?: { href: string } }).location
-        ?.href
-      if (base === undefined) {
-        throw new TypeError(
-          `cannot resolve the relative ws url '${url}' without a browser location — pass an absolute ws:// or wss:// url`,
-        )
-      }
-      resolved = new URL(url, base)
-    }
-    if (resolved.protocol === 'http:') resolved.protocol = 'ws:'
-    else if (resolved.protocol === 'https:') resolved.protocol = 'wss:'
-    return resolved.href
-  }
-
   const trySend = (data: string): void => {
     if (socket === null || !socketOpen) return
     try {
@@ -584,14 +903,7 @@ const wsTransport = (
     socketOpen = false
     clearTimeout(watchdog)
     watchdog = undefined
-    if (pending.size > 0) {
-      const rejection = new A2Error(
-        'STORE_UNAVAILABLE',
-        'socket closed with the ack outstanding',
-      )
-      for (const waiter of pending.values()) waiter.reject(rejection)
-      pending.clear()
-    }
+    rejectPendingAcks(pending)
     return current
   }
 
@@ -637,8 +949,10 @@ const wsTransport = (
     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)
@@ -662,7 +976,7 @@ const wsTransport = (
         if (channel === undefined || channel.ended || channel.live) return
         channel.live = true
         deliver(channel, { kind: 'ping' }) // the connected signal
-        flushReadyWaiters(frame.sessionId)
+        ready.notify(frame.sessionId)
         return
       }
       case 'unsubscribed': {
@@ -671,7 +985,11 @@ const wsTransport = (
         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
       }
@@ -680,7 +998,7 @@ const wsTransport = (
         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': {
@@ -723,7 +1041,7 @@ const wsTransport = (
         'no WebSocket implementation available — pass one via createClient({ webSocket }) where the global is missing',
       )
     }
-    const created = new webSocketImpl(socketUrl())
+    const created = new webSocketImpl(webSocketUrl(url).href)
     socket = created
     socketOpen = false
     armWatchdog(created)
@@ -752,14 +1070,16 @@ const wsTransport = (
       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'))
     })
   }
 
@@ -808,8 +1128,10 @@ const wsTransport = (
         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)
@@ -848,7 +1170,10 @@ const wsTransport = (
       ) {
         // 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
@@ -865,7 +1190,9 @@ const wsTransport = (
         } catch (cause) {
           pending.delete(req)
           reject(
-            new A2Error('STORE_UNAVAILABLE', 'socket send failed', { cause }),
+            new A2ClientError('STORE_UNAVAILABLE', 'socket send failed', {
+              cause,
+            }),
           )
         }
       })
@@ -881,29 +1208,7 @@ const wsTransport = (
       ) {
         return Promise.resolve()
       }
-      return new Promise((resolve) => {
-        let waiters = readyWaiters.get(sessionId)
-        if (!waiters) {
-          waiters = new Set()
-          readyWaiters.set(sessionId, waiters)
-        }
-        let settled = false
-        const done = (): void => {
-          if (settled) return
-          settled = true
-          clearTimeout(timer)
-          waiters.delete(done)
-          if (waiters.size === 0) readyWaiters.delete(sessionId)
-          // oxlint-disable-next-line promise/no-multiple-resolved -- `settled` guards the two callers (timer, open flush); the rule cannot see through the flag
-          resolve()
-        }
-        // The cap keeps a session nobody reconnects (write-only usage,
-        // an unreachable server) from parking a push forever — the
-        // attempt then fails fast and the loop moves on.
-        const timer = setTimeout(done, maxWaitMs)
-        ;(timer as { unref?: () => void }).unref?.()
-        waiters.add(done)
-      })
+      return ready.wait(sessionId, maxWaitMs)
     },
     sendPresence(envelope) {
       const channel = channels.get(envelope.sessionId)
@@ -926,7 +1231,7 @@ const transportFor = (
   webSocketImpl: ClientWebSocketConstructor | undefined,
   presence: boolean,
 ): Transport => {
-  if (typeof api === 'string') {
+  if (typeof api === 'string' || typeof api === 'function') {
     return httpTransport({ push: api, stream: api }, fetchImpl, presence)
   }
   if (api.type === 'http') {
@@ -936,7 +1241,13 @@ const transportFor = (
       presence,
     )
   }
-  return wsTransport(api.url, webSocketImpl, presence)
+  if (api.multiplex === true) {
+    if (typeof api.url !== 'string') {
+      throw new TypeError('a multiplexed WebSocket URL must be a string')
+    }
+    return multiplexedWsTransport(api.url, webSocketImpl, presence)
+  }
+  return sessionWsTransport(api.url, webSocketImpl, presence)
 }
 
 type Pending<D extends EventDefs> = {
@@ -972,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,
   )
@@ -1015,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
@@ -1023,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 ───────────────────────────────────────
@@ -1054,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
@@ -1112,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(
@@ -1138,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 }
       }
     }
 
@@ -1146,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,
       }
     }
@@ -1160,7 +1483,7 @@ export function createClient<
       return {
         state,
         events: [...serverEvents, ...overlay],
-        index: frontier,
+        index: stateIndex,
         history: historyState(),
         connection: connection(),
         ...(declaresPresence
@@ -1241,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]
@@ -1254,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>,
@@ -1265,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)
     }
@@ -1321,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`,
           )
@@ -1332,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 },
@@ -1353,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()
@@ -1382,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`,
           )
@@ -1393,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 },
@@ -1409,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',
       )
@@ -1418,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,
@@ -1462,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
                 }
@@ -1501,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({
@@ -1515,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) {
@@ -1538,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
@@ -1588,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)
@@ -1603,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()
@@ -1627,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
@@ -1635,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
@@ -1650,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
@@ -1676,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) {
@@ -1688,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
@@ -1699,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') {
@@ -1716,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
@@ -1767,6 +2165,7 @@ export function createClient<
       },
       push,
       loadHistory,
+      reconnect: reconnectStream,
       connect() {
         touch(sessionId)
         leases += 1
@@ -1774,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 () => {
@@ -1798,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)
@@ -1810,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()
         }