experimental-a2 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.12.0
+
+### Minor Changes
+
+- 523988e: Add `handler` to `experimental-a2/server` to normalize function and object handler entries into the object shape for composition while preserving event and presence types.
+
+## 0.11.0
+
+### Minor Changes
+
+- bcd0782: Adopt actor call answers into React's live state before resolving, without
+  waiting for the stream. Add authorized, view-projected snapshot reads,
+  `client.state()`, `onSnapshot`, and `useActor().refresh()`. Older snapshots
+  cannot overwrite newer state. Track stream progress separately so delayed
+  commits still enter the event feed and reconnects resume without skipping them.
+  Expose HTTP status through `ActorRequestError`
+  so clients can distinguish request failures from handler refusals.
+- 7bfab77: Add a caller-configurable reconnection policy and a paused connection state. Paused sessions retain their state, optimistic writes, and connection leases; `session.reconnect()` resumes them explicitly.
+
+  Expose `A2ClientError extends A2Error` from the client entry point for server and client failures, preserving available HTTP, WebSocket, and timeout details. Multiplexed subscription failures carry structured errors.
+
+- 853fa79: Back idle event and presence polling off to two seconds. Local pushes reactivate idle streams: SSE refreshes from the current cursor without reconnect backoff, while WebSockets wake the attached session iterator in place. Pending writes keep their stream active until their acknowledged events arrive.
+
+  Add `session.reconnect()` and `useSession().reconnect()` to restart a leased live subscription after custom REST mutations. Reconnection preserves state, pending writes, and leases. Multiplexed WebSockets re-subscribe the selected session without replacing the shared socket.
+
+  Stop the previous session subscription before authorizing its replacement, so denied or failed reconnects cannot retain access through the old lane.
+
+### Patch Changes
+
+- f92e00e: Reduce live-stream read overhead: Postgres selects only the six public event columns, and Redis HTTP reads public events directly without fetching dispatch metadata. Redis live reads use bounded pages while preserving cursor-based replay and delivery.
+- 6080ac2: Add an optional listenConnectionString to the Postgres store for a direct LISTEN connection. Stores share query pools and listeners across module copies in the same runtime, without sharing application state. Transactional triggers notify event and presence subscribers across writers. Reconnects catch up, and the last subscriber releases the listener.
+
+  Pools created by A2 use ambient waitUntil on Vercel to let idle connections close before suspension while preserving reuse between requests.
+
+  Keep LISTEN startup errors visible while allowing transient presence seed-read failures to recover.
+
+  Keep requested presence snapshots independent of listener unsubscribe, returning the real database state while cancelled streams discard late results.
+
+- f13c2cb: Stop idle event and presence subscriptions when clients disconnect or streams reach their invocation deadline. Cancellation now reaches the underlying store iterator while a session is waiting for its next event, preventing abandoned streams from continuing to poll the database.
+- e65dc9a: Use Upstash HTTP subscriptions for live events and presence without extra configuration. Share subscriptions across local viewers, close them on disconnect, and catch up after reconnect. Retain ten-second event safety reads for missed notifications. Publish wake-ups inside Redis write scripts, removing the separate request and application crash gap. Fall back to adaptive event and presence polling when an HTTP endpoint explicitly lacks subscription support.
+
+  Reconcile presence deletions after subscription reconnects while preserving newer patches and discarding superseded initial snapshots.
+
+  Recover from initial presence seed-read failures without suppressing foreground snapshot errors.
+
 ## 0.10.0
 
 ### Minor Changes

package/dist/actor-DJi3RsNu.d.ts

@@ -0,0 +1,310 @@
+import { h as StandardSchemaV1, i as Contract, s as EventDefs, t as Reducer } from "./reducer-DJKWm3cp.js";
+import { t as A2Store } from "./store-DtDOWLSn.js";
+import { f as ScheduleTiming, m as Session, n as A2Server, t as A2Scheduler } from "./server-DjZZa1wr.js";
+import { i as A2Telemetry } from "./telemetry-CpeclqB2.js";
+//#region src/actor-shared.d.ts
+/**
+ * A handler answered by throwing `NonRetriableError`: the event
+ * settled, the state did not change. Isomorphic — the server raises it
+ * from calls and `fetch()` serializes it as a 409; the client's `call`
+ * proxy revives it from that response.
+ */
+declare class ActorRefusedError extends Error {
+  /** The refused event's name. */
+  readonly event: string;
+  /** The refused event's message id. */
+  readonly messageId: string;
+  constructor(event: string, messageId: string, message: string);
+}
+/**
+ * The declaration an actor is defined over: its state shape and its
+ * event vocabulary, as types. Core A2 contracts are schemas because
+ * the wire is untrusted; actor protocols are types because your
+ * server is trusted — same contract-first design language, dialed to
+ * the trust level.
+ */
+type ActorProtocol = {
+  state: object;
+  events: object;
+  /**
+   * Optional third vocabulary: presence field → value type. Ephemeral
+   * audience state (who is here, cursors), replicated to subscribers
+   * and never stored in the log. Declaring it requires `presence:
+   * true` in the actor options — the wire bit types cannot carry.
+   */
+  presence?: object;
+};
+/** The protocol's presence vocabulary, `never` when undeclared. */
+type ActorPresenceOf<D extends ActorProtocol> = D extends {
+  presence: infer P extends object;
+} ? P : never;
+/** A `setPresence` patch: changed fields, `null` clears one. */
+type ActorPresenceValues<P> = { [F in keyof P & string]?: P[F] | null; };
+/**
+ * The replicated presence map: participant → field → latest value,
+ * last write wins per field. Values are peer-authored — render them
+ * like user input.
+ */
+type ActorPresenceMap<P> = {
+  [participant: string]: { [F in keyof P & string]?: {
+    value: P[F];
+    seen: number;
+    at: Date;
+  }; };
+};
+/**
+ * The typed self-send surface: one method per declared event —
+ * `ctx.send.transfer({ ref, amount })`. Buffered, not immediate: every
+ * send requested during a handler commits atomically with that
+ * handler's completion (a serial handler's state commit, a concurrent
+ * handler's settlement), riding core's returned-events semantics — so
+ * a reserve-and-trigger can never half-happen, and re-runs converge on
+ * the same deterministic message ids.
+ */
+type ActorSend<E> = { readonly [K in keyof E]: {} extends E[K] ? (input?: E[K]) => void : (input: E[K]) => void; };
+/**
+ * Timing for a scheduled event: exactly `{ delay: '5d' }` or
+ * `{ at: Date }` (core §6 semantics — relative delays anchor to the
+ * triggering message's durable `createdAt`, so re-runs resolve the
+ * same due time). `name` overrides the timer's identity — it defaults
+ * to the target event name, scoped to the triggering message, so one
+ * handler run gets one timer per target event unless named apart.
+ */
+type ActorScheduleOptions = ScheduleTiming & {
+  name?: string;
+};
+/**
+ * The typed durable-timer surface: one method per declared event —
+ * `ctx.schedule.refund({ ref: ctx.id }, { delay: '1h' })`. Unlike
+ * `send`, scheduling is immediate, not buffered: it awaits provider
+ * acceptance at call time (a timer is provider-side, not a log row),
+ * so a handler that schedules and then refuses has still armed the
+ * timer. That is safe by the guarded-delivery idiom — the stale timer
+ * fires into an idempotent no-op — but it is the one exception to
+ * "refusals are total". Requires a configured `scheduler`.
+ */
+type ActorScheduleSend<E> = { readonly [K in keyof E]: {} extends E[K] ? (input: E[K] | undefined, options: ActorScheduleOptions) => Promise<void> : (input: E[K], options: ActorScheduleOptions) => Promise<void>; };
+/** What a serial handler receives alongside its typed input. */
+type ActorContext<D extends ActorProtocol> = {
+  /** Mutable draft, committed atomically with the handler's completion. */
+  state: D["state"];
+  /** The message id — stable across re-runs; the idempotency key for external I/O. */
+  id: string;
+  /** Durable 1-based dispatch ordinal of this message. */
+  attempt: number;
+  /** The ordinary A2 handler signal — fires on claim expiry or supersession. */
+  signal: AbortSignal;
+  /** Typed buffered self-send — committed atomically with the state commit. */
+  send: ActorSend<D["events"]>;
+  /** Typed durable timers — immediate provider handoff, see ActorScheduleSend. */
+  schedule: ActorScheduleSend<D["events"]>;
+};
+/**
+ * What a `concurrent: true` handler receives. No draft — concurrent
+ * handlers run off the lane, in parallel, so state is a snapshot read
+ * (honest about staleness) and mutations happen by sending events
+ * whose serial handlers decide against fresh state.
+ */
+type ActorConcurrentContext<D extends ActorProtocol> = {
+  /** The message id — stable across re-runs; the idempotency key for external I/O. */
+  id: string;
+  /** Durable 1-based dispatch ordinal of this message. */
+  attempt: number;
+  /** The ordinary A2 handler signal — fires on claim expiry or supersession. */
+  signal: AbortSignal;
+  /** Snapshot read — observational; the world moves while this runs. */
+  state(): Promise<{
+    state: D["state"];
+    index: number;
+  }>;
+  /** Typed buffered self-send — committed atomically with settlement. */
+  send: ActorSend<D["events"]>;
+  /** Typed durable timers — immediate provider handoff, see ActorScheduleSend. */
+  schedule: ActorScheduleSend<D["events"]>;
+};
+type ActorStatePayload<S> = {
+  state: S;
+  /** The event whose handler committed this state. */
+  event: string;
+  /** The message (invocation event) id this state answers. */
+  message: string;
+};
+/** The event vocabulary a client needs to follow an actor's state. */
+type ActorClientEventDefs<S> = {
+  "a2.actor.state": StandardSchemaV1<ActorStatePayload<S>>;
+};
+//#endregion
+//#region src/actor.d.ts
+/**
+ * One event's handler: ordinary server code. Serial by default — read
+ * `ctx.state`, perform I/O, mutate `ctx.state`, one atomic commit at
+ * return. `{ concurrent: true, handle }` opts the handler out of the
+ * lane for slow I/O: state becomes a snapshot read and mutations
+ * happen by sending events. The input is typed by the protocol; the
+ * wire hands handlers parsed JSON, so a wire-exposed event guards its
+ * input in its first line (`schema.parse(input)` if you like schemas —
+ * userland either way).
+ */
+type ActorHandler<D extends ActorProtocol, K extends keyof D["events"]> = ((ctx: ActorContext<D>, input: D["events"][K]) => void | Promise<void>) | {
+  concurrent: true;
+  handle: (ctx: ActorConcurrentContext<D>, input: D["events"][K]) => void | Promise<void>;
+};
+/**
+ * Mark a handler concurrent — off the lane, in parallel with the lane
+ * and with other concurrent handlers, `ctx.state()` a snapshot read.
+ * Sugar for the structural `{ concurrent: true, handle }` form:
+ *
+ * ```ts
+ * handlers: {
+ *   transfer: concurrent(async (ctx, input) => {
+ *     await bank.transfer(input, { idempotencyKey: input.ref })
+ *     ctx.send.settle({ ref: input.ref })
+ *   }),
+ * }
+ * ```
+ */
+declare function concurrent<Ctx, I>(handle: (ctx: Ctx, input: I) => void | Promise<void>): {
+  concurrent: true;
+  handle: (ctx: Ctx, input: I) => void | Promise<void>;
+};
+type ActorOptions<D extends ActorProtocol> = {
+  /** Identity — prefixes storage keys; one contract per actor definition. */
+  name: string;
+  /** The initial state — checked against the protocol, a plain JSON tree. */
+  state: D["state"];
+  /**
+   * One handler per declared event — completeness and payload shapes
+   * are compile-checked against the protocol.
+   */
+  handlers: { [K in keyof D["events"]]: ActorHandler<D, K>; };
+  store?: A2Store;
+  scheduler?: A2Scheduler;
+  telemetry?: A2Telemetry;
+} & ([ActorPresenceOf<D>] extends [never] ? {
+  presence?: never;
+} : {
+  /**
+   * The wire bit for the protocol's `presence` vocabulary — types
+   * erase, so the runtime needs one value to arm the presence
+   * lanes (frames on GET, envelopes on POST). Required exactly
+   * when the protocol declares `presence`; the vocabulary itself
+   * is typed there. Values are validated to the JSON floor and
+   * pass through `authorize` as `{ type: 'presence' }` operations;
+   * meaning stays with your renderers — treat values as user
+   * input.
+   */
+  presence: true;
+});
+/**
+ * One HTTP operation `handle.fetch` is about to serve — the actor
+ * mirror of core's `A2Operation`. `authorize` sees it before any
+ * read, write, or subscription; returning `false` answers 403.
+ */
+type ActorOperation = {
+  readonly type: "state";
+  readonly id: string;
+} | {
+  readonly type: "stream";
+  readonly id: string;
+  readonly startAfter: number;
+} | {
+  readonly type: "call";
+  readonly id: string;
+  readonly event: string;
+  readonly input: unknown;
+  readonly messageId?: string;
+} | {
+  readonly type: "presence";
+  readonly id: string;
+  readonly participant: string;
+  readonly values: Readonly<Record<string, unknown>>;
+};
+type ActorFetchOptions<D extends ActorProtocol> = {
+  /** Per-operation policy — authentication happened in your route. */
+  authorize?: (operation: ActorOperation) => boolean | Promise<boolean>;
+  /**
+   * Request-time projection: what this mount's audience sees. Applied
+   * to every state frame on the stream AND to call answers (the two
+   * untrusted lanes must agree, or the call lane leaks what the
+   * stream hides). The definition stays audience-agnostic — different
+   * routes project the same actor differently, and per-viewer views
+   * are just closures over the route's auth. Output is held to the
+   * JSON-tree floor like everything else. Transport-agnostic: applied
+   * at frame emission, so any wire the door speaks emits projected
+   * frames. Absent, the full state ships (the trusted default).
+   */
+  view?: (state: D["state"]) => unknown;
+};
+type ActorSendOptions = {
+  /** Explicit message id — makes retries of this send idempotent. */
+  id?: string;
+};
+type ActorCallOptions = ActorSendOptions & {
+  /** How long to await the answer before rejecting the wait (default 30s). */
+  timeoutMs?: number;
+};
+type ActorCallResult<S> = {
+  /** The actor's state after this message was processed. */
+  state: S;
+  /** Log index of the state commit that answered this message. */
+  index: number;
+};
+type CallMethod<D extends ActorProtocol, K extends keyof D["events"]> = {} extends D["events"][K] ? (input?: D["events"][K], options?: ActorCallOptions) => Promise<ActorCallResult<D["state"]>> : (input: D["events"][K], options?: ActorCallOptions) => Promise<ActorCallResult<D["state"]>>;
+type SendMethod<D extends ActorProtocol, K extends keyof D["events"]> = {} extends D["events"][K] ? (input?: D["events"][K], options?: ActorSendOptions) => Promise<{
+  id: string;
+  index: number;
+}> : (input: D["events"][K], options?: ActorSendOptions) => Promise<{
+  id: string;
+  index: number;
+}>;
+/** One instance: typed calls and sends, reads, the managed door, the escape hatch. */
+type ActorHandle<D extends ActorProtocol> = {
+  readonly id: string;
+  /**
+   * Send the event and await its answer: the state after the handler
+   * ran, or a rejection with `ActorRefusedError`. Serial events only —
+   * concurrent handlers produce no answer to await; `send` them.
+   */
+  readonly call: { readonly [K in keyof D["events"]]: CallMethod<D, K>; };
+  /** Cast: validate, append the event durably, return without waiting. */
+  readonly send: { readonly [K in keyof D["events"]]: SendMethod<D, K>; };
+  /** Snapshot read — never queues behind pending messages. */
+  readonly state: () => Promise<ActorCallResult<D["state"]>>;
+  /**
+   * The managed door — the actor mirror of `server.fetch`, bound to
+   * this instance. GET streams the state plane (`a2.actor.state`
+   * commits only, `?index` resume, heartbeat, deadline rotation);
+   * POST is the call lane `createActorClient` speaks (`{ event,
+   * input, messageId? }` → the answer, 409 for a refusal). Your route
+   * authenticates and picks the instance; `authorize` sees every
+   * operation. Custom endpoints are route code around this call.
+   */
+  readonly fetch: (request: Request, options?: ActorFetchOptions<D>) => Promise<Response>;
+  /** Escape hatch: the raw A2 session (history, stream, schedule). */
+  readonly session: Session<EventDefs>;
+};
+type ActorDefinition<D extends ActorProtocol> = {
+  readonly name: string;
+  /**
+   * Type-only carrier of the protocol, so clients deriving from
+   * `typeof def` can see the vocabularies (`experimental-a2/actor/react`
+   * types `presence` from it). Never a runtime value.
+   */
+  readonly protocol?: D;
+  /** The assembled contract — declared events plus the reserved a2.actor.* pair. */
+  readonly contract: Contract<EventDefs>;
+  /** The underlying A2 server — `server.fetch` mounts the full session wire. */
+  readonly server: A2Server<EventDefs>;
+  /** The state fold — same identity as the client's follower fold. */
+  readonly reducer: Reducer<ActorClientEventDefs<D["state"]>, D["state"]>;
+  actor(id: string): ActorHandle<D>;
+};
+/**
+ * Define and serve an actor over its protocol: a named, durable
+ * instance-per-id with serialized state handlers, concurrent I/O
+ * handlers, and typed self-sends.
+ */
+declare function actor<D extends ActorProtocol>(options: ActorOptions<D>): ActorDefinition<D>;
+//#endregion
+export { ActorProtocol as _, ActorHandle as a, ActorScheduleSend as b, ActorOptions as c, concurrent as d, ActorConcurrentContext as f, ActorPresenceValues as g, ActorPresenceOf as h, ActorFetchOptions as i, ActorSendOptions as l, ActorPresenceMap as m, ActorCallResult as n, ActorHandler as o, ActorContext as p, ActorDefinition as r, ActorOperation as s, ActorCallOptions as t, actor as u, ActorRefusedError as v, ActorSend as x, ActorScheduleOptions as y };
+//# sourceMappingURL=actor-DJi3RsNu.d.ts.map

package/dist/actor-DJi3RsNu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-DJi3RsNu.d.ts","names":[],"sources":["../src/actor-shared.ts","../src/actor.ts"],"mappings":";;;;;;;;;;;cAgCa,0BAA0B;;WAE5B;;WAEA;EACT,YAAY,eAAe,mBAAmB;;;;;;;;;KAepC;EACV;EACA;;;;;;;EAOA;;;KAIU,gBAAgB,UAAU,iBAAiB;EACrD,gBAAgB;IAEd;;KAIQ,oBAAoB,QAC7B,WAAW,cAAc,EAAE;;;;;;KAQlB,iBAAiB;GAExB,yBAAA,WAAW;IAAgB,OAAO,EAAE;IAAI;IAAc,IAAI;;;;;;;;;;;;KAanD,UAAU,iBACV,WAAW,eAAe,EAAE,MACjC,QAAQ,EAAE,eACV,OAAO,EAAE;;;;;;;;;KAWJ,uBAAuB;EAAmB;;;;;;;;;;;;KAY1C,kBAAkB,iBAClB,WAAW,eAAe,EAAE,MACjC,OAAO,EAAE,gBAAgB,SAAS,yBAAyB,iBAC3D,OAAO,EAAE,IAAI,SAAS,yBAAyB;;KAI1C,aAAa,UAAU;;EAEjC,OAAO;;EAEP;;EAEA;;EAEA,QAAQ;;EAER,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;;;;;;;KASlB,uBAAuB,UAAU;;EAE3C;;EAEA;;EAEA,QAAQ;;EAER,SAAS;IAAU,OAAO;IAAY;;;EAEtC,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;KAGlB,kBAAkB;EAC5B,OAAO;;EAEP;;EAEA;;;KAWU,qBAAqB;EAC/B,kBAAkB,iBAAiB,kBAAkB;;;;;;;;;;;;;;KCzE3C,aAAa,UAAU,eAAe,gBAAgB,iBAC5D,KAAK,aAAa,IAAI,OAAO,YAAY,cAAc;EAEvD;EACA,SACE,KAAK,uBAAuB,IAC5B,OAAO,YAAY,cACT;;;;;;;;;;;;;;;;iBAiBF,WAAW,KAAK,GAC9B,SAAS,KAAK,KAAK,OAAO,aAAa;EACpC;EAAkB,SAAS,KAAK,KAAK,OAAO,aAAa;;KAIlD,aAAa,UAAU;;EAEjC;;EAEA,OAAO;;;;;EAKP,aAAa,WAAW,cAAc,aAAa,GAAG;EACtD,QAAQ;EACR,YAAY;EACZ,YAAY;MACR,gBAAgB;EAChB;;;;;;;;;;;;EAYA;;;;;;;KAQM;WACG;WAAwB;;WAExB;WACA;WACA;;WAGA;WACA;WACA;WACA;WACA;;WAGA;WACA;WACA;WACA,QAAQ,SAAS;;KAGpB,kBAAkB,UAAU;;EAEtC,aAAa,WAAW,6BAA6B;;;;;;;;;;;;EAYrD,QAAQ,OAAO;;KAGL;;EAEV;;KAGU,mBAAmB;;EAE7B;;KAGU,gBAAgB;;EAE1B,OAAO;;EAEP;;KAGG,WACH,UAAU,eACV,gBAAgB,0BACH,YAAY,MAErB,QAAQ,YAAY,IACpB,UAAU,qBACP,QAAQ,gBAAgB,gBAE3B,OAAO,YAAY,IACnB,UAAU,qBACP,QAAQ,gBAAgB;KAE5B,WACH,UAAU,eACV,gBAAgB,0BACH,YAAY,MAErB,QAAQ,YAAY,IACpB,UAAU,qBACP;EAAU;EAAY;MAEzB,OAAO,YAAY,IACnB,UAAU,qBACP;EAAU;EAAY;;;KAGnB,YAAY,UAAU;WACvB;;;;;;WAMA,kBAAkB,WAAW,cAAc,WAAW,GAAG;;WAEzD,kBAAkB,WAAW,cAAc,WAAW,GAAG;;WAEzD,aAAa,QAAQ,gBAAgB;;;;;;;;;;WAUrC,QACP,SAAS,SACT,UAAU,kBAAkB,OACzB,QAAQ;;WAEJ,SAAS,QAAQ;;KAGhB,gBAAgB,UAAU;WAC3B;;;;;;WAMA,WAAW;;WAEX,UAAU,SAAS;;WAEnB,QAAQ,SAAS;;WAEjB,SAAS,QAAQ,qBAAqB,aAAa;EAC5D,MAAM,aAAa,YAAY;;;;;;;iBAsDjB,MAAM,UAAU,eAC9B,SAAS,aAAa,KACrB,gBAAgB"}

package/dist/actor-client.d.ts

@@ -1,5 +1,12 @@
-import { c as ActorRefusedError } from "./actor-shared-USo5MyuF.js";
+import { n as ActorCallResult, v as ActorRefusedError } from "./actor-DJi3RsNu.js";
 //#region src/actor-client.d.ts
+declare class ActorRequestError extends Error {
+  readonly status: number | undefined;
+  constructor(message: string, options?: {
+    status?: number;
+    cause?: unknown;
+  });
+}
 /** The loose shape of an `actor()` definition — carried type-only. */
 type AnyActorDefinition = {
   actor(id: string): {
@@ -27,12 +34,14 @@ type ActorClientCall<D extends AnyActorDefinition, View = ActorStateOf<D>> = { r
 type ActorClient<D extends AnyActorDefinition, View = ActorStateOf<D>> = {
   /** Typed calls over POST — the response is the answer. */
   readonly call: ActorClientCall<D, View>;
+  readonly state: () => Promise<ActorCallResult<View>>;
 };
-type CreateActorClientOptions = {
+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;
 };
 /**
  * A typed call surface for one actor instance's route. When the route
@@ -40,7 +49,7 @@ type CreateActorClientOptions = {
  * answers carry the projected state:
  * `createActorClient<typeof vault, PublicVault>({ api })`.
  */
-declare function createActorClient<D extends AnyActorDefinition, View = ActorStateOf<D>>(options: CreateActorClientOptions): ActorClient<D, View>;
+declare function createActorClient<D extends AnyActorDefinition, View = ActorStateOf<D>>(options: CreateActorClientOptions<View>): ActorClient<D, View>;
 //#endregion
-export { ActorClient, ActorClientCall, ActorRefusedError, ActorStateOf, AnyActorDefinition, CreateActorClientOptions, createActorClient };
+export { ActorClient, ActorClientCall, ActorRefusedError, ActorRequestError, ActorStateOf, AnyActorDefinition, CreateActorClientOptions, createActorClient };
 //# sourceMappingURL=actor-client.d.ts.map

package/dist/actor-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actor-client.d.ts","names":[],"sources":["../src/actor-client.ts"],"mappings":";;;KAyBY;EACV,MAAM;IACJ,SAAS;MAAU;MAAgB;;IACnC;;;KAIC,SAAS,UAAU,sBAAsB,WAAW;KAE7C,aAAa,UAAU,sBAAsB,QACvD,WAAW,SAAS;;;;;;KAQV,gBACV,UAAU,oBACV,OAAO,aAAa,kBAEV,WAAW,SAAS,aAAa,SAAS,WAAW,gBAC1D,YAAY,MACZ;EAAU;EAAgB;UACvB,MAAM,MAAM;EAAU,OAAO;EAAM;;KAIjC,YACV,UAAU,oBACV,OAAO,aAAa;;WAGX,MAAM,gBAAgB,GAAG;;KAGxB;;EAEV;;EAEA,eAAe,WAAW;;;;;;;;iBAiDZ,kBACd,UAAU,oBACV,OAAO,aAAa,IACpB,SAAS,2BAA2B,YAAY,GAAG"}
+{"version":3,"file":"actor-client.d.ts","names":[],"sources":["../src/actor-client.ts"],"mappings":";;cAwBa,0BAA0B;WAC5B;EAET,YAAY,iBAAiB;IAAY;IAAiB;;;;KAQhD;EACV,MAAM;IACJ,SAAS;MAAU;MAAgB;;IACnC;;;KAIC,SAAS,UAAU,sBAAsB,WAAW;KAE7C,aAAa,UAAU,sBAAsB,QACvD,WAAW,SAAS;;;;;;KAQV,gBACV,UAAU,oBACV,OAAO,aAAa,kBAEV,WAAW,SAAS,aAAa,SAAS,WAAW,gBAC1D,YAAY,MACZ;EAAU;EAAgB;UACvB,MAAM,MAAM;EAAU,OAAO;EAAM;;KAIjC,YACV,UAAU,oBACV,OAAO,aAAa;;WAGX,MAAM,gBAAgB,GAAG;WACzB,aAAa,QAAQ,gBAAgB;;KAGpC,yBAAyB;;EAEnC;;EAEA,eAAe,WAAW;EAC1B,cAAc,UAAU,gBAAgB;;;;;;;;iBA4F1B,kBACd,UAAU,oBACV,OAAO,aAAa,IACpB,SAAS,yBAAyB,QAAQ,YAAY,GAAG"}

package/dist/actor-client.js

@@ -18,9 +18,17 @@ import { i as ActorRefusedError } from "./actor-shared-DI7J5upy.js";
 * await client.call.withdraw({ amount: 60 }) // ActorRefusedError on refusal
 * ```
 */
+var ActorRequestError = class extends Error {
+	status;
+	constructor(message, options) {
+		super(message, { cause: options?.cause });
+		this.name = "ActorRequestError";
+		this.status = options?.status;
+	}
+};
 const CALL_TIMEOUT_MS = 3e4;
 const callOverWire = async (fetchImpl, api, event, input, options) => {
-	const response = await fetchImpl(api, {
+	const response = await requestOverWire(fetchImpl, api, {
 		method: "POST",
 		headers: { "content-type": "application/json" },
 		body: JSON.stringify({
@@ -30,12 +38,32 @@ const callOverWire = async (fetchImpl, api, event, input, options) => {
 		}),
 		signal: AbortSignal.timeout(options?.timeoutMs ?? CALL_TIMEOUT_MS)
 	});
-	const body = await response.json().catch(() => ({}));
+	const body = await responseBody(response);
 	if (response.status === 409 && typeof body["error"] === "string") throw new ActorRefusedError(typeof body["event"] === "string" ? body["event"] : event, typeof body["messageId"] === "string" ? body["messageId"] : "", body["error"]);
-	if (!response.ok) {
-		const message = typeof body["error"] === "string" ? body["error"] : `actor call failed (${response.status})`;
-		throw new Error(message);
+	if (!response.ok) throw new ActorRequestError(typeof body["error"] === "string" ? body["error"] : `actor call failed (${response.status})`, { status: response.status });
+	return snapshotBody(body, response.status);
+};
+const requestOverWire = async (fetchImpl, api, init) => {
+	try {
+		return await fetchImpl(api, init);
+	} catch (cause) {
+		throw new ActorRequestError("actor request did not receive a response", { cause });
 	}
+};
+const responseBody = async (response) => {
+	try {
+		const body = await response.json();
+		if (!body || typeof body !== "object" || Array.isArray(body)) throw new Error("invalid response");
+		return body;
+	} catch (cause) {
+		throw new ActorRequestError("actor request returned an invalid response", {
+			status: response.status,
+			cause
+		});
+	}
+};
+const snapshotBody = (body, status) => {
+	if (!("state" in body) || !Number.isSafeInteger(body["index"]) || body["index"] < 0) throw new ActorRequestError("actor request returned an invalid snapshot", { status });
 	return body;
 };
 /**
@@ -46,9 +74,37 @@ const callOverWire = async (fetchImpl, api, event, input, options) => {
 */
 function createActorClient(options) {
 	const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
-	return { call: new Proxy({}, { get: (_target, event) => typeof event === "string" ? (input, callOptions) => callOverWire(fetchImpl, options.api, event, input, callOptions) : void 0 }) };
+	const adopt = (snapshot) => {
+		const result = snapshot;
+		options.onSnapshot?.(result);
+		return result;
+	};
+	const state = async () => {
+		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 = /* @__PURE__ */ new Map();
+	return {
+		call: new Proxy({}, { get: (_target, event) => {
+			if (typeof event !== "string") return void 0;
+			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;
+		} }),
+		state
+	};
 }
 //#endregion
-export { ActorRefusedError, createActorClient };
+export { ActorRefusedError, ActorRequestError, createActorClient };
 
 //# sourceMappingURL=actor-client.js.map

package/dist/actor-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"actor-client.js","names":[],"sources":["../src/actor-client.ts"],"sourcesContent":["/**\n * experimental-a2/actor/client — typed calls to an actor over HTTP.\n * Framework-agnostic: no React, no framework machinery; works in any\n * browser code and server-to-server.\n *\n * `client.call` mirrors the server handle's `call` record over the\n * call lane `handle.fetch` serves — POST `{ event, input, messageId? }`\n * → the answer (post-state), a 409 refusal (revived as\n * `ActorRefusedError`), or a 400. Both ends of that wire are library\n * code: the types here are backed by `handle.fetch`, not by a\n * hand-written convention.\n *\n * ```ts\n * import type { vault } from '@/app/vault/server' // type-only, erased\n * const client = createActorClient<typeof vault>({ api: `/vault/${id}` })\n * await client.call.withdraw({ amount: 60 }) // ActorRefusedError on refusal\n * ```\n */\n\nimport { ActorRefusedError } from './actor-shared.ts'\nimport type { ActorCallOptions, ActorCallResult } from './actor.ts'\n\nexport { ActorRefusedError }\n\n/** The loose shape of an `actor()` definition — carried type-only. */\nexport type AnyActorDefinition = {\n  actor(id: string): {\n    state(): Promise<{ state: unknown; index: number }>\n    call: object\n  }\n}\n\ntype HandleOf<D extends AnyActorDefinition> = ReturnType<D['actor']>\n\nexport type ActorStateOf<D extends AnyActorDefinition> = Awaited<\n  ReturnType<HandleOf<D>['state']>\n>['state']\n\n/**\n * The server handle's `call` record mirrored to the client, with\n * answers carrying `View` — the projected shape when the route mounts\n * `fetch(req, { view })`, the full state otherwise (the default).\n */\nexport type ActorClientCall<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n> = {\n  readonly [K in keyof HandleOf<D>['call']]: HandleOf<D>['call'][K] extends (\n    ...args: infer P\n  ) => Promise<{ state: unknown; index: number }>\n    ? (...args: P) => Promise<{ state: View; index: number }>\n    : never\n}\n\nexport type ActorClient<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n> = {\n  /** Typed calls over POST — the response is the answer. */\n  readonly call: ActorClientCall<D, View>\n}\n\nexport type CreateActorClientOptions = {\n  /** The route whose handler delegates to `handle.fetch` for this instance. */\n  api: string\n  /** Injectable transport (tests, custom auth headers). */\n  fetch?: typeof globalThis.fetch\n}\n\nconst CALL_TIMEOUT_MS = 30_000\n\nconst callOverWire = async (\n  fetchImpl: typeof globalThis.fetch,\n  api: string,\n  event: string,\n  input: unknown,\n  options?: ActorCallOptions,\n): Promise<ActorCallResult<unknown>> => {\n  const response = await fetchImpl(api, {\n    method: 'POST',\n    headers: { 'content-type': 'application/json' },\n    body: JSON.stringify({\n      event,\n      ...(input === undefined ? {} : { input }),\n      ...(options?.id === undefined ? {} : { messageId: options.id }),\n    }),\n    signal: AbortSignal.timeout(options?.timeoutMs ?? CALL_TIMEOUT_MS),\n  })\n  const body = (await response.json().catch(() => ({}))) as Record<\n    string,\n    unknown\n  >\n  if (response.status === 409 && typeof body['error'] === 'string') {\n    throw new ActorRefusedError(\n      typeof body['event'] === 'string' ? body['event'] : event,\n      typeof body['messageId'] === 'string' ? body['messageId'] : '',\n      body['error'],\n    )\n  }\n  if (!response.ok) {\n    const message =\n      typeof body['error'] === 'string'\n        ? body['error']\n        : `actor call failed (${response.status})`\n    throw new Error(message)\n  }\n  return body as ActorCallResult<unknown>\n}\n\n/**\n * A typed call surface for one actor instance's route. When the route\n * mounts a `view`, pass its shape as the second type argument so call\n * answers carry the projected state:\n * `createActorClient<typeof vault, PublicVault>({ api })`.\n */\nexport function createActorClient<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n>(options: CreateActorClientOptions): ActorClient<D, View> {\n  const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)\n  const call = new Proxy(\n    {},\n    {\n      get: (_target, event) =>\n        typeof event === 'string'\n          ? (input?: unknown, callOptions?: ActorCallOptions) =>\n              callOverWire(fetchImpl, options.api, event, input, callOptions)\n          : undefined,\n    },\n  ) as ActorClientCall<D, View>\n  return { call }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqEA,MAAM,kBAAkB;AAExB,MAAM,eAAe,OACnB,WACA,KACA,OACA,OACA,YACsC;CACtC,MAAM,WAAW,MAAM,UAAU,KAAK;EACpC,QAAQ;EACR,SAAS,EAAE,gBAAgB,mBAAmB;EAC9C,MAAM,KAAK,UAAU;GACnB;GACA,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;GACvC,GAAI,SAAS,OAAO,KAAA,IAAY,CAAC,IAAI,EAAE,WAAW,QAAQ,GAAG;EAC/D,CAAC;EACD,QAAQ,YAAY,QAAQ,SAAS,aAAa,eAAe;CACnE,CAAC;CACD,MAAM,OAAQ,MAAM,SAAS,KAAK,CAAC,CAAC,aAAa,CAAC,EAAE;CAIpD,IAAI,SAAS,WAAW,OAAO,OAAO,KAAK,aAAa,UACtD,MAAM,IAAI,kBACR,OAAO,KAAK,aAAa,WAAW,KAAK,WAAW,OACpD,OAAO,KAAK,iBAAiB,WAAW,KAAK,eAAe,IAC5D,KAAK,QACP;CAEF,IAAI,CAAC,SAAS,IAAI;EAChB,MAAM,UACJ,OAAO,KAAK,aAAa,WACrB,KAAK,WACL,sBAAsB,SAAS,OAAO;EAC5C,MAAM,IAAI,MAAM,OAAO;CACzB;CACA,OAAO;AACT;;;;;;;AAQA,SAAgB,kBAGd,SAAyD;CACzD,MAAM,YAAY,QAAQ,SAAS,WAAW,MAAM,KAAK,UAAU;CAWnE,OAAO,EAAE,MAAA,IAVQ,MACf,CAAC,GACD,EACE,MAAM,SAAS,UACb,OAAO,UAAU,YACZ,OAAiB,gBAChB,aAAa,WAAW,QAAQ,KAAK,OAAO,OAAO,WAAW,IAChE,KAAA,EACR,CAEU,EAAE;AAChB"}
+{"version":3,"file":"actor-client.js","names":[],"sources":["../src/actor-client.ts"],"sourcesContent":["/**\n * experimental-a2/actor/client — typed calls to an actor over HTTP.\n * Framework-agnostic: no React, no framework machinery; works in any\n * browser code and server-to-server.\n *\n * `client.call` mirrors the server handle's `call` record over the\n * call lane `handle.fetch` serves — POST `{ event, input, messageId? }`\n * → the answer (post-state), a 409 refusal (revived as\n * `ActorRefusedError`), or a 400. Both ends of that wire are library\n * code: the types here are backed by `handle.fetch`, not by a\n * hand-written convention.\n *\n * ```ts\n * import type { vault } from '@/app/vault/server' // type-only, erased\n * const client = createActorClient<typeof vault>({ api: `/vault/${id}` })\n * await client.call.withdraw({ amount: 60 }) // ActorRefusedError on refusal\n * ```\n */\n\nimport { ActorRefusedError } from './actor-shared.ts'\nimport type { ActorCallOptions, ActorCallResult } from './actor.ts'\n\nexport { ActorRefusedError }\n\nexport class ActorRequestError extends Error {\n  readonly status: number | undefined\n\n  constructor(message: string, options?: { status?: number; cause?: unknown }) {\n    super(message, { cause: options?.cause })\n    this.name = 'ActorRequestError'\n    this.status = options?.status\n  }\n}\n\n/** The loose shape of an `actor()` definition — carried type-only. */\nexport type AnyActorDefinition = {\n  actor(id: string): {\n    state(): Promise<{ state: unknown; index: number }>\n    call: object\n  }\n}\n\ntype HandleOf<D extends AnyActorDefinition> = ReturnType<D['actor']>\n\nexport type ActorStateOf<D extends AnyActorDefinition> = Awaited<\n  ReturnType<HandleOf<D>['state']>\n>['state']\n\n/**\n * The server handle's `call` record mirrored to the client, with\n * answers carrying `View` — the projected shape when the route mounts\n * `fetch(req, { view })`, the full state otherwise (the default).\n */\nexport type ActorClientCall<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n> = {\n  readonly [K in keyof HandleOf<D>['call']]: HandleOf<D>['call'][K] extends (\n    ...args: infer P\n  ) => Promise<{ state: unknown; index: number }>\n    ? (...args: P) => Promise<{ state: View; index: number }>\n    : never\n}\n\nexport type ActorClient<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n> = {\n  /** Typed calls over POST — the response is the answer. */\n  readonly call: ActorClientCall<D, View>\n  readonly state: () => Promise<ActorCallResult<View>>\n}\n\nexport type CreateActorClientOptions<View = unknown> = {\n  /** The route whose handler delegates to `handle.fetch` for this instance. */\n  api: string\n  /** Injectable transport (tests, custom auth headers). */\n  fetch?: typeof globalThis.fetch\n  onSnapshot?: (snapshot: ActorCallResult<View>) => void\n}\n\nconst CALL_TIMEOUT_MS = 30_000\n\nconst callOverWire = async (\n  fetchImpl: typeof globalThis.fetch,\n  api: string,\n  event: string,\n  input: unknown,\n  options?: ActorCallOptions,\n): Promise<ActorCallResult<unknown>> => {\n  const response = await requestOverWire(fetchImpl, api, {\n    method: 'POST',\n    headers: { 'content-type': 'application/json' },\n    body: JSON.stringify({\n      event,\n      ...(input === undefined ? {} : { input }),\n      ...(options?.id === undefined ? {} : { messageId: options.id }),\n    }),\n    signal: AbortSignal.timeout(options?.timeoutMs ?? CALL_TIMEOUT_MS),\n  })\n  const body = await responseBody(response)\n  if (response.status === 409 && typeof body['error'] === 'string') {\n    throw new ActorRefusedError(\n      typeof body['event'] === 'string' ? body['event'] : event,\n      typeof body['messageId'] === 'string' ? body['messageId'] : '',\n      body['error'],\n    )\n  }\n  if (!response.ok) {\n    const message =\n      typeof body['error'] === 'string'\n        ? body['error']\n        : `actor call failed (${response.status})`\n    throw new ActorRequestError(message, { status: response.status })\n  }\n  return snapshotBody(body, response.status)\n}\n\nconst requestOverWire = async (\n  fetchImpl: typeof globalThis.fetch,\n  api: string,\n  init: RequestInit,\n): Promise<Response> => {\n  try {\n    return await fetchImpl(api, init)\n  } catch (cause) {\n    throw new ActorRequestError('actor request did not receive a response', {\n      cause,\n    })\n  }\n}\n\nconst responseBody = async (\n  response: Response,\n): Promise<Record<string, unknown>> => {\n  try {\n    const body: unknown = await response.json()\n    if (!body || typeof body !== 'object' || Array.isArray(body))\n      throw new Error('invalid response')\n    return body as Record<string, unknown>\n  } catch (cause) {\n    throw new ActorRequestError('actor request returned an invalid response', {\n      status: response.status,\n      cause,\n    })\n  }\n}\n\nconst snapshotBody = (\n  body: Record<string, unknown>,\n  status: number,\n): ActorCallResult<unknown> => {\n  if (\n    !('state' in body) ||\n    !Number.isSafeInteger(body['index']) ||\n    (body['index'] as number) < 0\n  ) {\n    throw new ActorRequestError('actor request returned an invalid snapshot', {\n      status,\n    })\n  }\n  return body as ActorCallResult<unknown>\n}\n\n/**\n * A typed call surface for one actor instance's route. When the route\n * mounts a `view`, pass its shape as the second type argument so call\n * answers carry the projected state:\n * `createActorClient<typeof vault, PublicVault>({ api })`.\n */\nexport function createActorClient<\n  D extends AnyActorDefinition,\n  View = ActorStateOf<D>,\n>(options: CreateActorClientOptions<View>): ActorClient<D, View> {\n  const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)\n  const adopt = (snapshot: ActorCallResult<unknown>): ActorCallResult<View> => {\n    const result = snapshot as ActorCallResult<View>\n    options.onSnapshot?.(result)\n    return result\n  }\n  const state = async (): Promise<ActorCallResult<View>> => {\n    const api = options.api.split('#')[0]!\n    const separator = api.includes('?') ? '&' : '?'\n    const response = await requestOverWire(\n      fetchImpl,\n      `${api}${separator}snapshot=1`,\n      {\n        cache: 'no-store',\n        signal: AbortSignal.timeout(CALL_TIMEOUT_MS),\n      },\n    )\n    const body = await responseBody(response)\n    if (!response.ok) {\n      throw new ActorRequestError(\n        typeof body['error'] === 'string'\n          ? body['error']\n          : `actor state read failed (${response.status})`,\n        { status: response.status },\n      )\n    }\n    return adopt(snapshotBody(body, response.status))\n  }\n  const methods = new Map<\n    string,\n    (\n      input?: unknown,\n      callOptions?: ActorCallOptions,\n    ) => Promise<ActorCallResult<View>>\n  >()\n  const call = new Proxy(\n    {},\n    {\n      get: (_target, event) => {\n        if (typeof event !== 'string') return undefined\n        let method = methods.get(event)\n        if (!method) {\n          method = (input, callOptions) =>\n            callOverWire(\n              fetchImpl,\n              options.api,\n              event,\n              input,\n              callOptions,\n            ).then(adopt)\n          methods.set(event, method)\n        }\n        return method\n      },\n    },\n  ) as ActorClientCall<D, View>\n  return { call, state }\n}\n"],"mappings":"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"}

package/dist/actor-react.d.ts

@@ -1,7 +1,7 @@
 import { a as ContractEvent, s as EventDefs } from "./reducer-DJKWm3cp.js";
-import { i as ActorPresenceMap, o as ActorPresenceValues } from "./actor-shared-USo5MyuF.js";
+import { g as ActorPresenceValues, m as ActorPresenceMap } from "./actor-DJi3RsNu.js";
 import { ActorClientCall, ActorStateOf, AnyActorDefinition } from "./actor-client.js";
-import { Connection } from "./client.js";
+import { a as Connection } from "./client-P_NNNRM-.js";
 //#region src/actor-react.d.ts
 /** The server-to-client handoff: `await def.actor(id).state()`. */
 type ActorSnapshot<S> = {
@@ -25,13 +25,14 @@ type PresenceOf<D extends AnyActorDefinition> = D extends {
   presence: infer Values extends object;
 } ? Values : never : never;
 type UseActorResult<D extends AnyActorDefinition, View> = {
-  /** The actor's state, live: every commit streams in and replaces it. */
+  /** The live view, advanced by call answers, refreshes, and stream commits. */
   state: View;
-  /** The stream frontier. */
+  /** The latest adopted state index. */
   index: number;
   connection: Connection;
   /** Typed calls over POST — the response is the answer. */
   call: ActorClientCall<D, View>;
+  refresh: () => Promise<ActorSnapshot<View>>;
   /** The state-commit feed this browser has observed. */
   events: ContractEvent<EventDefs>[];
   /**

package/dist/actor-react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actor-react.d.ts","names":[],"sources":["../src/actor-react.ts"],"mappings":";;;;;;KA6CY,cAAc;EAAO,OAAO;EAAG;;KAE/B,gBAAgB;;EAE1B;;EAEA;;EAEA,SAAS,cAAc;;EAEvB;;;KAIG,WAAW,UAAU,sBAAsB;EAC9C,iBAAiB;IAEf,YAAY;EAAa,gBAAgB;IACvC;KAIM,eAAe,UAAU,oBAAoB;;EAEvD,OAAO;;EAEP;EACA,YAAY;;EAEZ,MAAM,gBAAgB,GAAG;;EAEzB,QAAQ,cAAc;;;;;;;EAOtB,UAAU,iBAAiB,WAAW;;;;;EAKtC,cAAc,QAAQ,oBAAoB,WAAW;;;iBA2BvC,SAAS,UAAU,oBAAoB,OAAO,aAAa,IACzE,SAAS,gBAAgB,QACxB,eAAe,GAAG"}
+{"version":3,"file":"actor-react.d.ts","names":[],"sources":["../src/actor-react.ts"],"mappings":";;;;;;KA8CY,cAAc;EAAO,OAAO;EAAG;;KAE/B,gBAAgB;;EAE1B;;EAEA;;EAEA,SAAS,cAAc;;EAEvB;;;KAIG,WAAW,UAAU,sBAAsB;EAC9C,iBAAiB;IAEf,YAAY;EAAa,gBAAgB;IACvC;KAIM,eAAe,UAAU,oBAAoB;;EAEvD,OAAO;;EAEP;EACA,YAAY;;EAEZ,MAAM,gBAAgB,GAAG;EACzB,eAAe,QAAQ,cAAc;;EAErC,QAAQ,cAAc;;;;;;;EAOtB,UAAU,iBAAiB,WAAW;;;;;EAKtC,cAAc,QAAQ,oBAAoB,WAAW;;;iBA2BvC,SAAS,UAAU,oBAAoB,OAAO,aAAa,IACzE,SAAS,gBAAgB,QACxB,eAAe,GAAG"}

package/dist/actor-react.js

@@ -1,8 +1,9 @@
 "use client";
-import { createClient } from "./client.js";
+import { t as createClient } from "./client-Bf6uSEAk.js";
 import { useSession } from "./react.js";
 import { l as openPresenceDefs } from "./actor-shared-DI7J5upy.js";
 import { createActorClient } from "./actor-client.js";
+import { useMemo } from "react";
 //#region src/actor-react.ts
 /**
 * experimental-a2/actor/react — use an actor from React: live state
@@ -62,12 +63,25 @@ function useActor(options) {
 		hydrate: options.initial,
 		...options.participant === void 0 ? {} : { participant: options.participant }
 	});
-	const { call } = createActorClient({ api });
+	const { call, state: refresh } = useMemo(() => createActorClient({
+		api,
+		onSnapshot: ({ state, index }) => {
+			client.session(options.id, {
+				initialState: state,
+				initialIndex: index
+			});
+		}
+	}), [
+		api,
+		client,
+		options.id
+	]);
 	return {
 		state: session.state,
 		index: session.index,
 		connection: session.connection,
 		call,
+		refresh,
 		events: session.events,
 		presence: session.presence,
 		setPresence: session.setPresence