experimental-a2 0.9.0 → 0.11.0

package/docs/guides/10-transports.mdx

@@ -13,20 +13,33 @@ it:
 ```ts
 // in a 'use client' session module:
 api: '/api/order-events'
+api: (sessionId) => `/api/orders/${encodeURIComponent(sessionId)}/events`
 api: { type: 'http', push: '/api/order-push', stream: '/api/order-stream' }
 api: { type: 'ws', url: '/api/order-events' }
 ```
 
-- **The string** is the default and the recommendation: one route
-  serving GET (SSE stream and history) and POST (push).
+- **One route** is the default and the recommendation. Pass a fixed URL or a
+  session URL function. It serves GET (SSE stream and history) and POST (push).
 - **`http` split** serves the two verbs from separate routes. Use it
   when platform duration limits differ per verb.
-- **`ws`** rides streams, pushes, and presence over one multiplexed
-  WebSocket. One socket carries every session of the client.
+- **`ws`** rides streams, pushes, and presence over WebSocket. It opens
+  one socket per session. Set `multiplex: true` on the client and
+  `multiplexWebSocket: true` on the route to share one socket across the
+  client's sessions.
 
 A split socket is unrepresentable on purpose. The socket is one
 connection in both directions.
 
+Every session-scoped URL may instead be a `(sessionId) => string` function.
+A2 resolves it for each request or reconnect, then adds its standard query
+parameters. This supports paths scoped to a session. Encode the ID when placing
+it in a path segment. The function chooses a route, not authority: if a path or
+connection token is scoped to one session, `authorize` must compare that scope
+to `operation.sessionId`. Bind URL tokens to the same session and keep them
+short-lived because URLs can appear in infrastructure logs. Multiplexed
+WebSockets take one plain URL because the connection carries more than one
+session.
+
 One wire is missing from `ws` by design: the history lane.
 [`loadHistory`](/guides/react#the-client-component) is a bounded cold
 read and rides plain HTTP. On a `ws` API it throws a `TypeError`.
@@ -103,22 +116,61 @@ export function GET(request: Request): Promise<Response> {
 }
 ```
 
-The socket is multiplexed. Subscribe frames open per-session lanes,
-each resuming from its own frontier. Every down frame carries its
-`sessionId`; pushes and presence route by it. One heartbeat and one
-connection serve all of the client's sessions.
+The socket is bound to the `sessionId` in its upgrade URL. The route
+authorizes that session before upgrading, and frames cannot select a
+different session afterward. Each connected session has its own socket.
+
+Authenticate the physical upgrade before calling `server.fetch`. For browser
+sockets authenticated by cookies, validate the request's `Origin` too. A
+WebSocket handshake does not use a CORS preflight.
+Then pass `authorize` to check the session stream and every push or
+presence frame. There is no separate upgrade operation: request policy
+belongs to the route, while A2 operation policy belongs to `authorize`.
+
+To multiplex, opt in on both sides:
+
+```ts app/api/multiplexed-order-events/route.ts
+import { experimental_upgradeWebSocket } from '@vercel/functions'
+import { ordersServer } from '@/server/orders'
+
+export function GET(request: Request): Promise<Response> {
+  return ordersServer.fetch(request, {
+    multiplexWebSocket: true,
+    upgradeWebSocket: (attach) =>
+      experimental_upgradeWebSocket(attach, {
+        maxPayload: 4 * 1024 * 1024,
+      }),
+  })
+}
+```
+
+```ts app/orders/multiplexed-session.ts
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { ordersReducer } from '@/reducer'
+
+export const ordersClient = createClient({
+  reducer: ordersReducer,
+  api: {
+    type: 'ws',
+    url: '/api/multiplexed-order-events',
+    multiplex: true,
+  },
+})
+```
 
-Authenticate the physical upgrade before calling `server.fetch`.
-Then pass `authorize` to check every session subscribe and every push
-or presence frame. There is no separate upgrade operation: request
-policy belongs to the route, while A2 operation policy belongs to
-`authorize`.
+Only enable multiplexing when the request's authentication context may
+open more than one session and `authorize` checks each supplied session
+ID. Subscribe frames open the lanes after the physical upgrade.
 
-A denied subscribe receives an `unsubscribed` notice and leaves other
-sessions connected. A denied event push receives a non-retryable
-`FORBIDDEN` ack. Denied presence is silently dropped because presence
-is fire-and-forget and repaints on the next update. Failed presence
-authorization is dropped the same way and leaves the socket connected.
+On a multiplexed socket, a denied subscribe receives an `unsubscribed`
+notice with a structured `FORBIDDEN` error and leaves other sessions
+connected. A failed stream or thrown authorization check carries
+`STORE_UNAVAILABLE`. The client exposes these as `A2ClientError` instances
+to its reconnection policy. On either socket shape, a
+denied event push receives a non-retryable `FORBIDDEN` ack. Denied
+presence is silently dropped because presence is fire-and-forget and
+repaints on the next update.
 
 A2 reads the platform's ambient invocation deadline and closes the
 socket cleanly before it. `waitUntil` and deadline discovery remain
@@ -148,10 +200,21 @@ shared above the wire seam.
 
 ## Lifecycle
 
-When a socket closes, the client reconnects with backoff, re-subscribes
-every session at its own frontier, receives fresh presence snapshots,
-and re-sends its own latest presence values. Event pushes keep their
-client-generated ids, so retry remains idempotent.
+When a socket closes, the client follows its reconnection policy at the current
+frontier, receives a fresh presence snapshot, and re-sends its own latest
+presence values. A multiplexed socket re-subscribes every active session
+at its own frontier. Event pushes keep their client-generated ids, so
+retry remains idempotent.
+
+Configure `createClient({ reconnect })` to choose a delay or pause by
+returning `false`. A paused session keeps its state and leases; call
+`session.reconnect()` to resume it. The default policy reconnects with
+backoff indefinitely. A clean close also runs the policy, with `error: null`.
+
+Pre-upgrade authorization remains in the HTTP route. Browser WebSockets do
+not expose a rejected upgrade's HTTP status or body, so those failures remain
+opaque `CONNECTION_FAILED` errors. Structured subscription errors are
+available after a multiplexed socket has opened.
 
 SSE and WebSocket are transport choices, not different consistency
 models. Both resume from the durable event frontier and treat presence

package/docs/reference/01-api.mdx

@@ -59,7 +59,8 @@ invalidates, and the next read refolds from raw events. See
 
 ### `A2Error`
 
-Everything A2 throws. One class, discriminated by `code`. See
+The shared base for A2 failures, discriminated by `code`. The session
+client exposes its `A2ClientError` subclass. See
 [Errors](/reference/errors).
 
 ## `experimental-a2/server`
@@ -199,6 +200,7 @@ server.fetch(
     upgradeWebSocket?: (
       attach: (socket: A2Socket) => void,
     ) => Response | Promise<Response>
+    multiplexWebSocket?: boolean
   },
 ): Promise<Response>
 
@@ -307,13 +309,20 @@ export function GET(request: Request): Promise<Response> {
 }
 ```
 
-Authenticate the physical WebSocket GET before calling `server.fetch`. Then
-use `authorize` for each session subscribe and each event or presence push.
-There is no WebSocket-upgrade operation in `A2Operation`. A denied subscribe
-receives `unsubscribed` and does not affect other sessions. A denied event push
-receives a `FORBIDDEN` ack. Denied presence is silently dropped because it is
-fire-and-forget. Failed presence authorization is dropped the same way and does
-not disconnect unrelated sessions on the multiplexed socket.
+By default, the `sessionId` and `index` query parameters bind one session to the
+socket. A2 authorizes the stream before upgrading. Frames on that socket cannot
+select another session.
+
+Set `multiplexWebSocket: true` here and `multiplex: true` in the client's `ws`
+API to share one socket.
+Authenticate the physical WebSocket GET before calling `server.fetch`. Validate
+`Origin` too when browser cookies authenticate it; WebSocket handshakes do not
+use a CORS preflight. Use `authorize` for each session subscribe and each event
+or presence push. Only enable multiplexing when that request context may access
+every session accepted by `authorize`. A denied subscribe receives
+`unsubscribed` and does not affect other sessions. A denied event push receives
+a `FORBIDDEN` ack. Denied presence is silently dropped because it is
+fire-and-forget.
 
 SSE and WebSocket lifetimes use the platform's ambient invocation deadline.
 A2 also uses the platform's ambient `waitUntil` capability for background work.
@@ -674,8 +683,8 @@ session.stream(options: {
 
 A live feed of the session's events. `startAfter` is a non-negative safe integer;
 `startAfter: 20` begins with event 21.
-Server-side only; `server.fetch` exposes it over SSE, and over the multiplexed
-socket when `upgrade` is set. Subscribing never dispatches handlers.
+Server-side only; `server.fetch` exposes it over SSE and WebSocket. Subscribing
+never dispatches handlers.
 
 With `presence: true`, the feed yields one `PresenceSnapshot` first:
 `{ snapshot }`, the current pruned map with each field's own `value`,
@@ -785,25 +794,27 @@ transition and the destination should adopt the same optimistic session.
 | --------------- | ------------------------------------------------------ |
 | `sessionId`     | which session to subscribe to                          |
 | `initialState`  | server-rendered state                                  |
-| `initialIndex`  | the fold's frontier, where the stream resumes          |
+| `initialIndex`  | the fold's frontier, where a new session starts streaming |
 | `initialEvents` | optional earlier raw events for a history UI           |
 | `participant`   | overrides the client's `participant`; one of the two is required to call `setPresence` |
 
 Opens the stream on mount, closes it on unmount, reconnects with
-backoff from the current frontier. `participant` binds at the session's
+backoff from its last streamed event. `participant` binds at the session's
 first resolution; a changed provider prop is ignored for the session's
 runtime lifetime.
 
 `initialState` and `initialIndex` are the complete server-to-client handoff.
-The stream resumes after `initialIndex`, including events appended between the
-server render and the connection. `initialEvents` only preloads the raw
+For a new session, the stream starts after `initialIndex`, including events
+appended between the server render and the connection. `initialEvents` only preloads the raw
 `events` feed for a UI that needs entries from before that frontier. It does
-not affect state hydration or stream resumption.
+not affect state hydration or stream resumption. Later snapshots advance
+state while preserving the stream's resume position, so delayed events
+still enter the feed without folding into state again.
 
 ### `useSession()`
 
 ```ts
-const { state, push, events, index, loadHistory, history, connection,
+const { state, push, reconnect, events, index, loadHistory, history, connection,
   presence, setPresence } = useSession()
 ```
 
@@ -811,7 +822,7 @@ const { state, push, events, index, loadHistory, history, connection,
 shared reducer. `events` is the raw event feed: observed, explicitly
 seeded, or backscrolled. Unless `initialEvents` seeds earlier entries or
 `loadHistory` fetches them, it begins after `initialIndex`. `index` is
-the stream frontier, the `lastSeenIndex` for
+the latest server-confirmed state index, the `lastSeenIndex` for
 [cancellation](/guides/cancellation).
 
 `loadHistory({ before?, limit? })` backscrolls: it fetches a bounded
@@ -820,10 +831,9 @@ query parameters) and merges it into `events`, deduped, ordered, and
 shared across every handle of the session. It resolves with the events
 in the requested range. Defaults walk backward 50 at a time from the
 oldest loaded event; `before` is an exclusive upper bound. After a
-hydrate jump (returning to a session whose frontier advanced while
-away), default paging still continues from the oldest loaded event;
-pass an explicit `before` to fill the gap between the old feed and the
-new frontier. It never touches `state` or the optimistic overlay. Calls
+newer snapshot hydrates the session, default paging still continues from
+the oldest loaded event. Pass an explicit `before` to read another range.
+It never touches `state` or the optimistic overlay. Calls
 serialize per session and already-loaded ranges are not refetched.
 `history` is the progress: `{ loading, complete, oldestLoaded }`, where
 `complete` means the feed reaches index 1 (or the log is empty). The `ws` api has no history lane; there `loadHistory`
@@ -848,7 +858,7 @@ contract; it still never folds presence). `setPresence` requires a
 [Presence](/guides/presence).
 
 `push` appends optimistically: validated locally, rolled back on
-rejection, retried only for `STORE_UNAVAILABLE`. Awaiting it gives the
+rejection, retried for `STORE_UNAVAILABLE` and transport failures. Awaiting it gives the
 server ack; the same result carries `confirmed`, a lazy promise for
 the later moment when the live stream has delivered the batch back and
 the view shows server truth:
@@ -867,18 +877,31 @@ only for the previous call's ack or final rejection, not for `confirmed`.
 Other session IDs and clients remain concurrent; they converge on the log's
 durable order.
 
-A rejected push rejects both promises with the same `A2Error`;
+A rejected push rejects both promises with the same `A2ClientError`;
 `confirmed` is materialized only when accessed, so ignoring it costs
 nothing. It also reads as intent: `await push(...).confirmed` is
 "continue once this is server truth".
 
+`session.reconnect(): void` immediately restarts a leased subscription,
+including one paused by the reconnection policy,
+from its current cursor. It preserves state, pending writes, and leases, and
+does nothing without an active lease. The React `useSession()` result exposes
+the same `reconnect` function. Use it after a custom REST mutation; it requests
+a restart rather than returning a promise for catch-up completion. A
+multiplexed WebSocket keeps its physical socket and other session lanes;
+a single-session WebSocket replaces its socket.
+
 `connection` is a discriminated union; impossible states are
 unrepresentable (an `error` only exists while disconnected):
 
 ```ts
+// in a client module:
+import type { A2ClientError } from 'experimental-a2/client'
+
 type Connection =
   | { status: 'idle' }
-  | { status: 'connecting'; reconnects: number; error: Error | null }
+  | { status: 'connecting'; reconnects: number; error: A2ClientError | null }
+  | { status: 'paused'; reconnects: number; error: A2ClientError | null }
   | { status: 'live'; reconnects: number }
   | { status: 'closed' }
 ```
@@ -1198,20 +1221,59 @@ createClient(options: {
   api: ClientApi
   gcTime?: number // idle session lifetime; 5 minutes by default
   participant?: string // default presence identity for every session
+  reconnect?: (failure: {
+    sessionId: string
+    error: A2ClientError | null
+    attempt: number
+  }) => number | false
 }): A2Client
 
 type ClientApi =
-  | string // one route: GET SSE stream + POST push
-  | { type: 'http'; push: string; stream: string } // split routes
-  | { type: 'ws'; url: string } // one socket, both directions
+  | SessionUrl // one route: GET SSE stream + POST push
+  | { type: 'http'; push: SessionUrl; stream: SessionUrl }
+  | { type: 'ws'; url: SessionUrl; multiplex?: false }
+  | { type: 'ws'; url: string; multiplex: true }
+
+type SessionUrl = string | ((sessionId: string) => string)
 ```
 
+`reconnect` runs after a failed connection or a stream ending, including a
+clean end with `error: null`. Return the delay in milliseconds before the next
+attempt, or `false` to pause automatic reconnection. Delays must be finite,
+non-negative, and at most 2,147,483,647 ms. The callback is synchronous; a
+throw or invalid result pauses the connection with an `A2ClientError`.
+
+`attempt` starts at 1 for the first retry. It counts consecutive attempts
+per session and resets when the stream becomes live or `session.reconnect()`
+explicitly restarts it. It is separate from the lifetime `reconnects` count.
+Without a callback, A2 retries indefinitely with delays starting at 500 ms,
+doubling up to five seconds. The callback does not run for an explicit
+restart, an idle-stream refresh, or a caller closing the stream.
+
+While paused, `connection.status` is `paused` and its last error remains
+available. State, hydration, optimistic writes, and connection leases remain
+intact. Another consumer taking a lease does not resume a paused stream.
+Call `session.reconnect()` to resume immediately with a fresh attempt count.
+Releasing the last lease still closes the stream. A later first lease starts
+a new connection. Push retries are independent of this policy; a push does
+not resume a paused stream. An acknowledged push's `confirmed` promise waits
+until streamed events or a newer hydrated snapshot cover the acknowledged
+state index. Resumption preserves the stream's own position, even when
+hydration has advanced state while paused.
+
+A `SessionUrl` function runs for each HTTP request or WebSocket connection.
+Use it for session-specific paths. A2 still adds its `sessionId` and read-bound
+query parameters. The function does not authorize that ID. Bind any path scope
+or URL token to `operation.sessionId` in `authorize`; keep URL tokens short-lived
+because URLs can appear in infrastructure logs. A multiplexed WebSocket URL is
+a string because its connection carries more than one session.
+
 The framework-agnostic session client `experimental-a2/react` is built on: the SSE
 subscription with frontier resume and reconnection, the optimistic push
 queue with ack/rollback, and the local fold. `client.session(id, {
 initialState?, initialIndex?, initialEvents?, participant? })` returns a
 handle with `getSnapshot()`/`subscribe()` (the `useSyncExternalStore`
-contract), `push()`, `loadHistory()`, `connect()`, and `close()`.
+contract), `push()`, `loadHistory()`, `connect()`, `reconnect()`, and `close()`.
 `connect()` takes a lease on the live stream and returns its release:
 leases refcount per handle (the first connects, releasing the last
 closes, releasing twice is a no-op), so independent consumers of one

package/docs/reference/02-errors.mdx

@@ -1,13 +1,13 @@
 ---
 title: Errors
-description: One error class, stable codes, and clear rules about what append will never throw for.
+description: Stable server and client error codes, transport details, and append guarantees.
 ---
 
 ## `A2Error`
 
-Everything A2 throws is an `A2Error`, a single class discriminated by
-`code`, not a subclass hierarchy. One class serializes cleanly across the
-push-route boundary and keeps `instanceof` working after bundling.
+A2 failures carry an `A2Error` with a stable `code`. The session client exposes
+`A2ClientError`, which extends `A2Error`, for both server failures and failures
+observed locally. Existing `instanceof A2Error` checks also match client errors.
 
 ```ts
 // e.g. in a route handler:
@@ -45,9 +45,39 @@ export async function POST(req: Request) {
 | `STORE_UNAVAILABLE`       | the store backend failed; nothing was written, original error as `cause` | **yes**   |
 | `STORE_NOT_CONFIGURED`    | production boot with no `store` configured (during `next build` page collection, deferred to first use) | no |
 
-Retryability is derivable from the code. `STORE_UNAVAILABLE` is the only one
-worth retrying; the rest are deterministic caller bugs, and retrying them
-is wasted work.
+Of these server codes, only `STORE_UNAVAILABLE` is automatically retried by
+client pushes. Reconnection has its own caller-configurable policy.
+
+## `A2ClientError`
+
+Import `A2ClientError` from `experimental-a2/client`. Connection failures,
+push failures, history read failures, and local A2 validation failures use
+this class. Server failures keep their `code`, `message`, and `details`.
+Unexpected thrown values are retained as `cause`. Invalid API arguments can
+still throw native `TypeError` or `RangeError` exceptions.
+
+| Client code | Meaning |
+| --- | --- |
+| `TIMEOUT` | A2 detected a stream stall or an unconfirmed subscription. `phase` is `stream` or `subscribe`; `timeoutMs` is the expired deadline. |
+| `HTTP_ERROR` | An unsuccessful HTTP response without a recognized A2 error body. `status` carries the HTTP status. |
+| `CONNECTION_FAILED` | The transport could not establish or retain a connection. WebSocket close events preserve `closeCode` and `closeReason` when available. |
+| `UNKNOWN` | An unexpected client failure. The original value is available as `cause`. |
+
+HTTP failures retain `status` even when they carry a recognized server code.
+A browser WebSocket handshake rejection has no readable HTTP status or body;
+it remains `CONNECTION_FAILED`. A2 does not infer an authorization failure or
+a timeout from an opaque socket error.
+
+The stream watchdog detects 35 seconds of silence after connection. A
+multiplexed subscription also has 35 seconds to receive confirmation. There
+is no A2-owned initial connection deadline for HTTP or single-session
+WebSockets. Clean stream termination has no error: the reconnection callback
+and connection snapshot carry `null`.
+
+Pushes retain their three-attempt budget for `STORE_UNAVAILABLE` and client
+transport failures. The reconnection callback controls only the live stream.
+Pausing that stream preserves the writer; it does not guarantee that a push
+can succeed while its WebSocket is unavailable.
 
 On `PARTIAL_DUPLICATE_BATCH`: retrying an *identical* batch is not an
 error. It's an idempotent success, and you get the previously appended
@@ -60,7 +90,7 @@ nothing is written.
 
 ## NonRetriableError
 
-The second exported error class. Throw it (or a subclass, matched by
+Throw it (or a subclass, matched by
 `instanceof`) from a handler when the failure is deterministic: the
 event dead-letters immediately instead of consuming the ten-failure
 retry budget, because a guard that refuses this attempt will refuse
@@ -110,6 +140,10 @@ with a mapped status: `INVALID_PAYLOAD`, `UNKNOWN_EVENT_TYPE`, and
 `PARTIAL_DUPLICATE_BATCH` are 400; `FORBIDDEN` is 403;
 `SUPERSEDED_ATTEMPT` is 409; `STORE_UNAVAILABLE` is 503.
 
-The client's `push` deserializes the body back into an `A2Error`, so client
-and server code branch on identical codes. `push` auto-retries only
-`STORE_UNAVAILABLE`. `server.fetch` owns the HTTP serialization.
+The session client deserializes the body into an `A2ClientError`, so client
+and server code branch on identical server codes. `server.fetch` owns HTTP
+serialization. Multiplexed WebSocket subscription failures carry the same
+error envelope in their `unsubscribed` frame, alongside the legacy `reason`
+string. Older reason-only frames remain readable as `CONNECTION_FAILED`.
+Unknown server exceptions become `STORE_UNAVAILABLE`; their private causes
+are not sent to clients.

package/examples/playground/package.json

@@ -22,7 +22,7 @@
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.9.0",
+    "experimental-a2": "0.11.0",
     "ioredis": "^5.9.0",
     "next": "^16.3.0",
     "pg": "^8.16.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
   "license": "MIT",
   "type": "module",

package/src/actor-client.ts

@@ -22,6 +22,16 @@ import type { ActorCallOptions, ActorCallResult } from './actor.ts'
 
 export { ActorRefusedError }
 
+export class ActorRequestError extends Error {
+  readonly status: number | undefined
+
+  constructor(message: string, options?: { status?: number; cause?: unknown }) {
+    super(message, { cause: options?.cause })
+    this.name = 'ActorRequestError'
+    this.status = options?.status
+  }
+}
+
 /** The loose shape of an `actor()` definition — carried type-only. */
 export type AnyActorDefinition = {
   actor(id: string): {
@@ -58,13 +68,15 @@ export type ActorClient<
 > = {
   /** Typed calls over POST — the response is the answer. */
   readonly call: ActorClientCall<D, View>
+  readonly state: () => Promise<ActorCallResult<View>>
 }
 
-export type CreateActorClientOptions = {
+export type CreateActorClientOptions<View = unknown> = {
   /** The route whose handler delegates to `handle.fetch` for this instance. */
   api: string
   /** Injectable transport (tests, custom auth headers). */
   fetch?: typeof globalThis.fetch
+  onSnapshot?: (snapshot: ActorCallResult<View>) => void
 }
 
 const CALL_TIMEOUT_MS = 30_000
@@ -76,7 +88,7 @@ const callOverWire = async (
   input: unknown,
   options?: ActorCallOptions,
 ): Promise<ActorCallResult<unknown>> => {
-  const response = await fetchImpl(api, {
+  const response = await requestOverWire(fetchImpl, api, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({
@@ -86,10 +98,7 @@ const callOverWire = async (
     }),
     signal: AbortSignal.timeout(options?.timeoutMs ?? CALL_TIMEOUT_MS),
   })
-  const body = (await response.json().catch(() => ({}))) as Record<
-    string,
-    unknown
-  >
+  const body = await responseBody(response)
   if (response.status === 409 && typeof body['error'] === 'string') {
     throw new ActorRefusedError(
       typeof body['event'] === 'string' ? body['event'] : event,
@@ -102,7 +111,53 @@ const callOverWire = async (
       typeof body['error'] === 'string'
         ? body['error']
         : `actor call failed (${response.status})`
-    throw new Error(message)
+    throw new ActorRequestError(message, { status: response.status })
+  }
+  return snapshotBody(body, response.status)
+}
+
+const requestOverWire = async (
+  fetchImpl: typeof globalThis.fetch,
+  api: string,
+  init: RequestInit,
+): Promise<Response> => {
+  try {
+    return await fetchImpl(api, init)
+  } catch (cause) {
+    throw new ActorRequestError('actor request did not receive a response', {
+      cause,
+    })
+  }
+}
+
+const responseBody = async (
+  response: Response,
+): Promise<Record<string, unknown>> => {
+  try {
+    const body: unknown = await response.json()
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+      throw new Error('invalid response')
+    return body as Record<string, unknown>
+  } catch (cause) {
+    throw new ActorRequestError('actor request returned an invalid response', {
+      status: response.status,
+      cause,
+    })
+  }
+}
+
+const snapshotBody = (
+  body: Record<string, unknown>,
+  status: number,
+): ActorCallResult<unknown> => {
+  if (
+    !('state' in body) ||
+    !Number.isSafeInteger(body['index']) ||
+    (body['index'] as number) < 0
+  ) {
+    throw new ActorRequestError('actor request returned an invalid snapshot', {
+      status,
+    })
   }
   return body as ActorCallResult<unknown>
 }
@@ -116,17 +171,62 @@ const callOverWire = async (
 export function createActorClient<
   D extends AnyActorDefinition,
   View = ActorStateOf<D>,
->(options: CreateActorClientOptions): ActorClient<D, View> {
+>(options: CreateActorClientOptions<View>): ActorClient<D, View> {
   const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)
+  const adopt = (snapshot: ActorCallResult<unknown>): ActorCallResult<View> => {
+    const result = snapshot as ActorCallResult<View>
+    options.onSnapshot?.(result)
+    return result
+  }
+  const state = async (): Promise<ActorCallResult<View>> => {
+    const api = options.api.split('#')[0]!
+    const separator = api.includes('?') ? '&' : '?'
+    const response = await requestOverWire(
+      fetchImpl,
+      `${api}${separator}snapshot=1`,
+      {
+        cache: 'no-store',
+        signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+      },
+    )
+    const body = await responseBody(response)
+    if (!response.ok) {
+      throw new ActorRequestError(
+        typeof body['error'] === 'string'
+          ? body['error']
+          : `actor state read failed (${response.status})`,
+        { status: response.status },
+      )
+    }
+    return adopt(snapshotBody(body, response.status))
+  }
+  const methods = new Map<
+    string,
+    (
+      input?: unknown,
+      callOptions?: ActorCallOptions,
+    ) => Promise<ActorCallResult<View>>
+  >()
   const call = new Proxy(
     {},
     {
-      get: (_target, event) =>
-        typeof event === 'string'
-          ? (input?: unknown, callOptions?: ActorCallOptions) =>
-              callOverWire(fetchImpl, options.api, event, input, callOptions)
-          : undefined,
+      get: (_target, event) => {
+        if (typeof event !== 'string') return undefined
+        let method = methods.get(event)
+        if (!method) {
+          method = (input, callOptions) =>
+            callOverWire(
+              fetchImpl,
+              options.api,
+              event,
+              input,
+              callOptions,
+            ).then(adopt)
+          methods.set(event, method)
+        }
+        return method
+      },
     },
   ) as ActorClientCall<D, View>
-  return { call }
+  return { call, state }
 }