experimental-a2 0.16.1 → 0.18.0

package/dist/{errors-DvhSXnxk.d.ts → initial-snapshot-Bx-c0pDP.d.ts}

@@ -1,5 +1,6 @@
+import { i as StateSnapshot } from "./reducer-CqA59Q6U.js";
 //#region src/errors.d.ts
-type A2ServerErrorCode = "INVALID_PAYLOAD" | "FORBIDDEN" | "UNKNOWN_EVENT_TYPE" | "PARTIAL_DUPLICATE_BATCH" | "SUPERSEDED_ATTEMPT" | "CLAIM_EXPIRED" | "STORE_UNAVAILABLE" | "STORE_NOT_CONFIGURED" | "UNKNOWN_PRESENCE_FIELD" | "PRESENCE_NOT_SUPPORTED";
+type A2ServerErrorCode = "INVALID_PAYLOAD" | "FORBIDDEN" | "UNKNOWN_EVENT_TYPE" | "PARTIAL_DUPLICATE_BATCH" | "SUPERSEDED_ATTEMPT" | "SESSION_CLEARED" | "CLAIM_EXPIRED" | "STORE_UNAVAILABLE" | "STORE_NOT_CONFIGURED" | "UNKNOWN_PRESENCE_FIELD" | "PRESENCE_NOT_SUPPORTED";
 type A2ErrorCode = A2ServerErrorCode | "TIMEOUT" | "HTTP_ERROR" | "CONNECTION_FAILED" | "UNKNOWN";
 declare class A2Error extends Error {
   readonly code: A2ErrorCode;
@@ -24,5 +25,8 @@ declare class NonRetriableError extends Error {
   });
 }
 //#endregion
-export { NonRetriableError as i, A2ErrorCode as n, A2ServerErrorCode as r, A2Error as t };
-//# sourceMappingURL=errors-DvhSXnxk.d.ts.map
+//#region src/initial-snapshot.d.ts
+type InitialSnapshot<S> = StateSnapshot<S> | null | undefined | Promise<StateSnapshot<S> | null | undefined>;
+//#endregion
+export { NonRetriableError as a, A2ServerErrorCode as i, A2Error as n, A2ErrorCode as r, InitialSnapshot as t };
+//# sourceMappingURL=initial-snapshot-Bx-c0pDP.d.ts.map

package/dist/initial-snapshot-Bx-c0pDP.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initial-snapshot-Bx-c0pDP.d.ts","names":[],"sources":["../src/errors.ts","../src/initial-snapshot.ts"],"mappings":";;KAAY;KAaA,cACV;cAEW,gBAAgB;WAClB,MAAM;;WAEN;EAET,YACE,MAAM,aACN,iBACA;IAAY;IAAmB;;;;;;;;;;;cA2CtB,0BAA0B;EACrC,YAAY,iBAAiB;IAAY;;;;;KClE/B,gBAAgB,KACxB,cAAc,wBAGd,QAAQ,cAAc"}

package/dist/{internal-Dq2qYxou.js → internal-B2T3U4Rq.js}

@@ -28,6 +28,12 @@ const RESERVED_PARTICIPANT_IDS = /* @__PURE__ */ new Set([
 	"prototype"
 ]);
 const serverInternals = /* @__PURE__ */ new WeakMap();
+/**
+* Handler contexts whose previous attempt ended in a failure the handler
+* threw, as opposed to a claim that lapsed (a crash, a timeout, a frozen
+* process). Only the attempt's own outcome is known, not how far it got.
+*/
+const failedPreviousAttempt = /* @__PURE__ */ new WeakSet();
 const objectLike = (value) => typeof value === "object" && value !== null || typeof value === "function";
 const TOOL_SCOPE_STORAGE = Symbol.for("experimental-a2.ai.tool-scope");
 function ambientToolScopeStorage() {
@@ -151,6 +157,27 @@ const POLL_TIMINGS = {
 * white-box test seam.
 */
 const NOTIFY_TIMINGS = { safetyReadMs: 1e4 };
+/**
+* Bounds for each server instance's in-memory reducer-state cache. Sizes are
+* encoded JSON lengths, re-measured every `measureEvery` folded events, so
+* the byte budget is approximate. Mutable only as a white-box test seam.
+*/
+const STATE_CACHE = {
+	maxEntries: 1e3,
+	maxBytes: 33554432,
+	snapshotEvery: 128,
+	maxTail: 255,
+	measureEvery: 16
+};
+/**
+* Warm state-read tails for stores that can serve one in a single request:
+* events from `fromIndex` (inclusive) through `throughIndex` or the newest
+* event, or null when that needs more than one request. Like every store
+* read, a tail starts no lower than the latest clear marker. Keyed by the exact
+* store object, so a wrapper built by spreading or proxying a store reads
+* through its own `readHistory` instead.
+*/
+const stateTailReaders = /* @__PURE__ */ new WeakMap();
 const STREAM_TIMINGS = {
 	sseHeartbeatMs: 15e3,
 	sseDeadlineGraceMs: 1e3,
@@ -183,6 +210,6 @@ const SOCKET_TIMINGS = {
 */
 const PRESENCE_TIMINGS = { sendIntervalMs: 66 };
 //#endregion
-export { PRESENCE_TIMINGS as a, STREAM_TIMINGS as c, classifySchedulerSendFailure as d, consumeSchedulerSendFailure as f, serverInternals as g, nullProtoRecord as h, POLL_TIMINGS as i, ambientToolScopeStorage as l, markSchedulerSendFailure as m, MAX_DATE_MS as n, RESERVED_PARTICIPANT_IDS as o, installAmbientToolScopeStorage as p, NOTIFY_TIMINGS as r, SOCKET_TIMINGS as s, DRAIN_TIMINGS as t, assertSchedulerTargets as u };
+export { nullProtoRecord as _, PRESENCE_TIMINGS as a, STATE_CACHE as c, assertSchedulerTargets as d, classifySchedulerSendFailure as f, markSchedulerSendFailure as g, installAmbientToolScopeStorage as h, POLL_TIMINGS as i, STREAM_TIMINGS as l, failedPreviousAttempt as m, MAX_DATE_MS as n, RESERVED_PARTICIPANT_IDS as o, consumeSchedulerSendFailure as p, NOTIFY_TIMINGS as r, SOCKET_TIMINGS as s, DRAIN_TIMINGS as t, ambientToolScopeStorage as u, serverInternals as v, stateTailReaders as y };
 
-//# sourceMappingURL=internal-Dq2qYxou.js.map
+//# sourceMappingURL=internal-B2T3U4Rq.js.map

package/dist/internal-B2T3U4Rq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-B2T3U4Rq.js","names":[],"sources":["../src/internal.ts"],"sourcesContent":["/**\n * Private seams shared by a2 entry points and a2's own tests. Not exported\n * from the package. Nothing here is public API.\n */\n\nimport type { ScheduledEvent } from './scheduler-task.ts'\nimport type { DrainableServer } from './server.ts'\nimport type { Event } from './store.ts'\n\nexport type DrainOutcome = 'busy' | 'stalled' | 'settled'\n\n/**\n * A null-prototype record for maps keyed by caller-controlled strings\n * (participant ids, presence field names). On a normal object,\n * assigning to '__proto__' rewrites the prototype instead of creating\n * an own property — the prototype-pollution class. Null-prototype\n * objects still satisfy Record types and JSON.stringify cleanly.\n */\nexport function nullProtoRecord<T extends object>(): T {\n  return Object.create(null) as T\n}\n\n/**\n * ECMA-262's maximum Date value (±8.64e15 ms). A presence stamp past\n * it becomes an Invalid Date whose toISOString throws — one hostile\n * stamp would poison every subscriber's snapshot frame — so both\n * seams bound `at` to the representable range.\n */\nexport const MAX_DATE_MS = 8_640_000_000_000_000\n\n/**\n * Participant ids that collide with Object.prototype plumbing.\n * Null-prototype construction already defuses them, but they are\n * rejected at both seams (`parsePushBody`, `setPresence`) so a hostile\n * id never propagates into userland maps either.\n */\nexport const RESERVED_PARTICIPANT_IDS: ReadonlySet<string> = new Set([\n  '__proto__',\n  'constructor',\n  'prototype',\n])\n\nexport type DrainResult = {\n  settled: boolean\n  outcome: DrainOutcome\n  /** Existing successor arm a scheduler callback may join before acking. */\n  schedulerArm?: Promise<void>\n}\n\nexport type ServerInternals = {\n  /**\n   * Await every in-flight background drain this machine has scheduled,\n   * including ones scheduled while waiting. Lets tests flush the\n   * fire-and-forget inline path deterministically — no sleeps.\n   */\n  settle(): Promise<void>\n  /** The public `server.drain()` result deliberately remains `{ settled }`. */\n  schedulerDrain(\n    sessionId: string,\n    opts?: { watchdogDueAt?: number },\n  ): Promise<DrainResult>\n  /** Deliver a scheduler-owned delayed append through the normal root path. */\n  schedulerAppend(\n    sessionId: string,\n    events: readonly ScheduledEvent[],\n    originIndex?: number,\n  ): Promise<void>\n  /** Deliver a scheduler-owned conditional clear, deletion included. */\n  schedulerClear(sessionId: string, ifLastIndex: number): Promise<void>\n  /** `session.history` with clear markers kept; reads start at the latest one. */\n  historyWithMarkers(sessionId: string, gte: number): Promise<Event[]>\n}\n\nexport const serverInternals: WeakMap<object, ServerInternals> = new WeakMap()\n\n/**\n * Handler contexts whose previous attempt ended in a failure the handler\n * threw, as opposed to a claim that lapsed (a crash, a timeout, a frozen\n * process). Only the attempt's own outcome is known, not how far it got.\n */\nexport const failedPreviousAttempt: WeakSet<object> = new WeakSet()\n\nconst objectLike = (value: unknown): value is object =>\n  (typeof value === 'object' && value !== null) || typeof value === 'function'\n\n/** The ambient value delivered to `handlerContext` during a tool execution. */\nexport type AmbientToolScope = {\n  /** Executing server identity; a test scope from `runWithHandlerContext` has none. */\n  contract?: { readonly name: string }\n  context: unknown\n}\n\n/**\n * Structural AsyncLocalStorage surface for the ambient tool scope. The\n * instance is created by the server-only AI entry point (the only place\n * `node:async_hooks` may be imported) and shared through a global\n * symbol slot, so `handlerContext` in the isomorphic AI entry point and\n * independently bundled A2 copies all read the same scope.\n */\nexport type AmbientToolScopeStorage = {\n  getStore(): AmbientToolScope | undefined\n  run<R>(store: AmbientToolScope, callback: () => R): R\n}\n\nconst TOOL_SCOPE_STORAGE = Symbol.for('experimental-a2.ai.tool-scope')\n\nexport function ambientToolScopeStorage(): AmbientToolScopeStorage | undefined {\n  const value = Reflect.get(globalThis, TOOL_SCOPE_STORAGE)\n  if (\n    !objectLike(value) ||\n    typeof Reflect.get(value, 'getStore') !== 'function' ||\n    typeof Reflect.get(value, 'run') !== 'function'\n  ) {\n    return undefined\n  }\n  return value as AmbientToolScopeStorage\n}\n\nexport function installAmbientToolScopeStorage(\n  create: () => AmbientToolScopeStorage,\n): AmbientToolScopeStorage {\n  const existing = ambientToolScopeStorage()\n  if (existing !== undefined) return existing\n  const storage = create()\n  Reflect.set(globalThis, TOOL_SCOPE_STORAGE, storage)\n  return storage\n}\n\nexport type SchedulerSendFailureDisposition = 'retryable' | 'terminal'\n\ntype SchedulerSendFailureMarker = {\n  readonly version: 1\n  readonly pending: SchedulerSendFailureDisposition[]\n  readonly active: SchedulerSendFailureDisposition[]\n}\n\nconst SCHEDULER_SEND_FAILURE = Symbol.for(\n  'experimental-a2.scheduler.send-failure',\n)\n\nconst schedulerSendFailureMarker = (\n  value: unknown,\n): SchedulerSendFailureMarker | undefined => {\n  if (!objectLike(value)) return undefined\n  const marker = Reflect.get(value, SCHEDULER_SEND_FAILURE)\n  if (\n    !objectLike(marker) ||\n    Reflect.get(marker, 'version') !== 1 ||\n    !Array.isArray(Reflect.get(marker, 'pending')) ||\n    !Array.isArray(Reflect.get(marker, 'active'))\n  ) {\n    return undefined\n  }\n  return marker as SchedulerSendFailureMarker\n}\n\nconst schedulerFailureObject = (error: unknown): object => {\n  if (\n    objectLike(error) &&\n    (schedulerSendFailureMarker(error) !== undefined ||\n      Object.isExtensible(error))\n  ) {\n    return error\n  }\n  return new Error(String(error), { cause: error })\n}\n\nconst schedulerSendFailureState = (\n  error: object,\n): SchedulerSendFailureMarker => {\n  const existing = schedulerSendFailureMarker(error)\n  if (existing !== undefined) return existing\n  const marker: SchedulerSendFailureMarker = {\n    version: 1,\n    pending: [],\n    active: [],\n  }\n  Object.defineProperty(error, SCHEDULER_SEND_FAILURE, {\n    value: marker,\n    enumerable: false,\n    configurable: true,\n    writable: false,\n  })\n  return marker\n}\n\nconst clearSchedulerSendFailureState = (\n  error: object,\n  marker: SchedulerSendFailureMarker,\n): void => {\n  if (marker.pending.length === 0 && marker.active.length === 0) {\n    Reflect.deleteProperty(error, SCHEDULER_SEND_FAILURE)\n  }\n}\n\n/**\n * Classify an adapter error before throwing it. Unclassified adapter failures\n * are retryable because the caller cannot know whether a remote send landed.\n */\nexport function classifySchedulerSendFailure(\n  error: unknown,\n  disposition: SchedulerSendFailureDisposition,\n): unknown {\n  const classified = schedulerFailureObject(error)\n  schedulerSendFailureState(classified).pending.push(disposition)\n  return classified\n}\n\n/** Consume a pending adapter classification and count this rejected send. */\nexport function markSchedulerSendFailure(error: unknown): unknown {\n  const marked = schedulerFailureObject(error)\n  const marker = schedulerSendFailureState(marked)\n  marker.active.push(marker.pending.pop() ?? 'retryable')\n  return marked\n}\n\nexport function consumeSchedulerSendFailure(\n  error: unknown,\n): SchedulerSendFailureDisposition | undefined {\n  if (!objectLike(error)) return undefined\n  const marker = schedulerSendFailureMarker(error)\n  const disposition = marker?.active.pop()\n  if (marker !== undefined) clearSchedulerSendFailureState(error, marker)\n  return disposition\n}\n\nconst isDrainableServer = (value: unknown): value is DrainableServer => {\n  if (value === null || typeof value !== 'object') return false\n  const contract = Reflect.get(value, 'contract')\n  return (\n    contract !== null &&\n    typeof contract === 'object' &&\n    typeof Reflect.get(contract, 'name') === 'string' &&\n    typeof Reflect.get(value, 'drain') === 'function'\n  )\n}\n\n/**\n * Validate the server list captured by a scheduler route at construction time.\n * The seam stays structural so custom scheduler integrations can supply their\n * own drainable targets.\n */\nexport function assertSchedulerTargets(\n  servers: readonly unknown[],\n): asserts servers is readonly DrainableServer[] {\n  const contracts = new Set<string>()\n  for (const target of servers) {\n    if (!isDrainableServer(target)) {\n      throw new TypeError('a2 scheduler: expected a server from createServer()')\n    }\n    const name = target.contract.name\n    if (contracts.has(name)) {\n      throw new TypeError(\n        `a2 scheduler: duplicate server contract '${name}' in one handler`,\n      )\n    }\n    contracts.add(name)\n  }\n}\n\n/**\n * Drain timing knobs. Mutable only as a white-box test seam. Claim\n * heartbeats run on real timers, so tests shrink these to keep suites\n * fast. Production always uses the defaults.\n */\nexport const DRAIN_TIMINGS: {\n  /** How long a claim lives without renewal. */\n  claimTtlMs: number\n  /** Heartbeat cadence while a handler is running. */\n  claimHeartbeatMs: number\n  /** Base delay before retrying a failed renewal while the lease lives. */\n  renewRetryMs: number\n  /** Delay between a claim's expiry and its scheduler watchdog. */\n  watchdogGraceMs: number\n  /** Maximum time a top-level append waits for its initial scheduler arm. */\n  schedulerArmTimeoutMs: number\n} = {\n  claimTtlMs: 5_000,\n  claimHeartbeatMs: 2_000,\n  renewRetryMs: 400,\n  watchdogGraceMs: 1_000,\n  schedulerArmTimeoutMs: 2_000,\n}\n\n/**\n * Stream liveness knobs — the server-side SSE heartbeat and the\n * client-side stall watchdog. Paired by design: the client declares a\n * connection dead after roughly two missed heartbeats. Mutable only as\n * a white-box test seam; production always uses the defaults.\n */\n/**\n * Poll cadence for the poll-based store streams (sqlite, postgres) —\n * owned, not configurable: adaptive polling removed the operator's\n * reason to tune it (the floor keeps active streams smooth; the\n * ceiling bounds idle cost). Mutable only as a white-box test seam so\n * suites don't wait out real idle gaps.\n */\nexport const POLL_TIMINGS: {\n  /** Gap between polls while a session is producing events. */\n  activeFloorMs: number\n  /** The idle ceiling — the longest gap between polls. */\n  idleCeilingMs: number\n} = {\n  activeFloorMs: 25,\n  idleCeilingMs: 2_000,\n}\n\n/**\n * Safety-read cadence for the notify-driven redis live stream. A\n * parked feed re-reads the store at this interval even without a\n * pub/sub wake-up, so a lost notification (subscriber reconnect gap,\n * dropped PUBLISH) costs latency, never an event. Mutable only as a\n * white-box test seam.\n */\nexport const NOTIFY_TIMINGS: {\n  safetyReadMs: number\n} = {\n  safetyReadMs: 10_000,\n}\n\n/**\n * Bounds for each server instance's in-memory reducer-state cache. Sizes are\n * encoded JSON lengths, re-measured every `measureEvery` folded events, so\n * the byte budget is approximate. Mutable only as a white-box test seam.\n */\nexport const STATE_CACHE: {\n  maxEntries: number\n  maxBytes: number\n  /** Events a cached state may advance before it writes a snapshot. */\n  snapshotEvery: number\n  /** Events a warm read may fold; longer tails read the stored snapshot. */\n  maxTail: number\n  /** Events folded between re-measuring a cached state's encoded size. */\n  measureEvery: number\n} = {\n  maxEntries: 1_000,\n  maxBytes: 32 * 1024 * 1024,\n  snapshotEvery: 128,\n  maxTail: 255,\n  measureEvery: 16,\n}\n\n/**\n * Warm state-read tails for stores that can serve one in a single request:\n * events from `fromIndex` (inclusive) through `throughIndex` or the newest\n * event, or null when that needs more than one request. Like every store\n * read, a tail starts no lower than the latest clear marker. Keyed by the exact\n * store object, so a wrapper built by spreading or proxying a store reads\n * through its own `readHistory` instead.\n */\nexport const stateTailReaders: WeakMap<\n  object,\n  (\n    sessionId: string,\n    fromIndex: number,\n    throughIndex?: number,\n  ) => Promise<Event[] | null>\n> = new WeakMap()\n\nexport const STREAM_TIMINGS: {\n  /** Cadence of `: ping` comment frames from `sseResponse`. */\n  sseHeartbeatMs: number\n  /** How far ahead of an invocation deadline an SSE response closes. */\n  sseDeadlineGraceMs: number\n  /** Client: silence longer than this means the connection is dead. */\n  stallTimeoutMs: number\n  /** Client reconnect backoff: first retry delay, doubling per attempt. */\n  reconnectBaseMs: number\n  /** Client reconnect backoff ceiling. */\n  reconnectMaxMs: number\n} = {\n  sseHeartbeatMs: 15_000,\n  sseDeadlineGraceMs: 1_000,\n  stallTimeoutMs: 35_000,\n  reconnectBaseMs: 500,\n  reconnectMaxMs: 5_000,\n}\n\n/**\n * WebSocket down-pump backpressure — `sessionsSocket` parks its pull\n * loop while the socket reports more buffered bytes than the\n * high-water mark and re-checks on the poll cadence, so a slow reader\n * applies backpressure to the store subscription instead of buffering\n * without bound in the socket. Acks and heartbeats stay exempt: they\n * are small and correctness-relevant. Mutable only as a white-box test\n * seam.\n */\nexport const SOCKET_TIMINGS: {\n  highWaterMarkBytes: number\n  resumePollMs: number\n  /** Up-lane bound: concurrent push/presence handlers per socket. POST\n   * gets per-request platform limits for free; the socket must bring\n   * its own. Over the cap, pushes are answered with a retryable error\n   * ack and presence frames are shed (that plane repaints). */\n  maxInFlightMessages: number\n  /** Hard ceiling on `bufferedAmount`: past it the peer is a\n   * non-reader (acks and pings are park-exempt, so only a peer that\n   * never reads can reach it) and the socket closes 1008. */\n  disconnectWaterMarkBytes: number\n} = {\n  highWaterMarkBytes: 1_048_576,\n  resumePollMs: 25,\n  maxInFlightMessages: 32,\n  disconnectWaterMarkBytes: 8_388_608,\n}\n\n/**\n * Client presence send cadence — a leading send immediately, then at\n * most one merged send per interval (~15Hz). Owned, not configurable\n * (decision #36's rule): coupling the cadence to the POST ack tied\n * remote cursor smoothness to RTT, and the ack serves no correctness\n * purpose on a fire-and-forget LWW plane. Mutable only as a white-box\n * test seam.\n */\nexport const PRESENCE_TIMINGS: {\n  sendIntervalMs: number\n} = {\n  sendIntervalMs: 66,\n}\n"],"mappings":"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"}

package/dist/otel.d.ts

@@ -1,4 +1,4 @@
-import { i as A2Telemetry } from "./telemetry-B5jzpy6y.js";
+import { i as A2Telemetry } from "./telemetry-Cyfqo6Qt.js";
 import { Tracer } from "@opentelemetry/api";
 //#region src/otel.d.ts
 type OtelOptions = {

package/dist/react-BBXgHWFc.d.ts

@@ -0,0 +1,86 @@
+import { c as ContractEvent, d as PresenceDefs, f as PresenceMap, g as WithPresence, o as AppendInput, p as PresencePatch, s as Contract, t as Reducer, u as EventDefs } from "./reducer-CqA59Q6U.js";
+import { t as InitialSnapshot } from "./initial-snapshot-Bx-c0pDP.js";
+import { a as Connection, c as HistoryState, l as LoadHistoryOptions, t as A2Client, u as PushResult } from "./client-h_DKFAjj.js";
+import { ReactElement, ReactNode } from "react";
+//#region src/react.d.ts
+type UseSessionOptions<S> = {
+  participant?: string;
+  initial?: InitialSnapshot<S>;
+  enabled?: boolean;
+  suspend?: boolean;
+};
+type SessionProviderProps<D extends EventDefs, S> = {
+  sessionId: string;
+  api: string;
+  initial?: InitialSnapshot<S>;
+  initialEvents?: ContractEvent<D>[];
+  participant?: string;
+  children?: ReactNode;
+};
+type BoundSessionProviderProps<D extends EventDefs, S> = Omit<SessionProviderProps<D, S>, "api">;
+type UseSessionPresence<P extends PresenceDefs> = {
+  /** The replicated presence map, this client included (local echo). */
+  presence: PresenceMap<P>;
+  /**
+   * Fire-and-forget: validated locally, echoed into the map
+   * immediately, coalesced on the wire to a fixed cadence (a leading
+   * send immediately, then at most one merged send per interval;
+   * later values win per field), stamped with the frontier at send
+   * time as `seen`. Requires the provider's `participant`.
+   */
+  setPresence: (values: PresencePatch<P>["values"]) => void;
+};
+type UseSessionResult<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = WithPresence<P, UseSessionPresence<P>> & {
+  /** The live view, folded through the shared reducer. */
+  state: S;
+  /** A state/index snapshot has been applied; independent of connection status. */
+  hydrated: boolean;
+  /** The raw event feed — observed, seeded, or backscrolled. */
+  events: ContractEvent<D>[];
+  /** The stream frontier — `lastSeenIndex` for cancellation. */
+  index: number;
+  /**
+   * The connection, as a discriminated union — `error` exists only
+   * while disconnected; "reconnecting…" is
+   * `status === 'connecting' && reconnects > 0`.
+   */
+  connection: Connection;
+  /**
+   * Typed optimistic append. Awaiting it gives the server ack;
+   * `.confirmed` resolves when the live stream has delivered the batch
+   * back. Rejects with the server's A2Error codes.
+   */
+  push: (...events: AppendInput<D>[]) => PushResult<D>;
+  /** Restart the live subscription without resetting its state or cursor. */
+  reconnect: () => void;
+  /**
+   * Backscroll: fetch a bounded slice of older events into `events`.
+   * Defaults page backward 50 at a time from the oldest loaded event.
+   * Display data only — `state` and the optimistic overlay never move.
+   */
+  loadHistory: (options?: LoadHistoryOptions) => Promise<ContractEvent<D>[]>;
+  /** Backscroll progress: `complete` means the feed reaches index 1. */
+  history: HistoryState;
+};
+type BoundSessionOptions<D extends EventDefs, S, P extends PresenceDefs> = UseSessionOptions<S> & {
+  sessionId?: string;
+  client?: A2Client<D, S, P>;
+};
+type A2React<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = {
+  SessionProvider: (props: SessionProviderProps<D, S>) => ReactElement;
+  useSession: (options?: BoundSessionOptions<D, S, P>) => UseSessionResult<D, S, P>;
+};
+type BoundA2React<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = {
+  SessionProvider: (props: BoundSessionProviderProps<D, S>) => ReactElement;
+  useSession: (options?: BoundSessionOptions<D, S, P>) => UseSessionResult<D, S, P>;
+};
+declare function createReact<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>>(options: {
+  client: A2Client<D, S, P>;
+}): BoundA2React<D, S, P>;
+declare function createReact<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>>(options: {
+  contract: Contract<D, P, Reducer<D, S, P>>;
+}): A2React<D, S, P>;
+declare function useSession<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>>(client: A2Client<D, S, P>, sessionId: string, options?: UseSessionOptions<NoInfer<S>>): UseSessionResult<D, S, P>;
+//#endregion
+export { SessionProviderProps as a, UseSessionResult as c, BoundSessionProviderProps as i, createReact as l, BoundA2React as n, UseSessionOptions as o, BoundSessionOptions as r, UseSessionPresence as s, A2React as t, useSession as u };
+//# sourceMappingURL=react-BBXgHWFc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"react-BBXgHWFc.d.ts","names":[],"sources":["../src/react.ts"],"mappings":";;;;;KAwCY,kBAAkB;EAC5B;EACA,UAAU,gBAAgB;EAC1B;EACA;;KAGU,qBAAqB,UAAU,WAAW;EACpD;EACA;EACA,UAAU,gBAAgB;EAC1B,gBAAgB,cAAc;EAC9B;EACA,WAAW;;KAGD,0BAA0B,UAAU,WAAW,KAAK,KAC9D,qBAAqB,GAAG;KAId,mBAAmB,UAAU;;EAEvC,UAAU,YAAY;;;;;;;;EAQtB,cAAc,QAAQ,cAAc;;KAG1B,iBACV,UAAU,WACV,GACA,UAAU,eAAe,wBACvB,aAAa,GAAG,mBAAmB;;EAErC,OAAO;;EAEP;;EAEA,QAAQ,cAAc;;EAEtB;;;;;;EAMA,YAAY;;;;;;EAMZ,UAAU,QAAQ,YAAY,SAAS,WAAW;;EAElD;;;;;;EAMA,cAAc,UAAU,uBAAuB,QAAQ,cAAc;;EAErE,SAAS;;KAGC,oBACV,UAAU,WACV,GACA,UAAU,gBACR,kBAAkB;EACpB;EACA,SAAS,SAAS,GAAG,GAAG;;KAGd,QACV,UAAU,WACV,GACA,UAAU,eAAe;EAEzB,kBAAkB,OAAO,qBAAqB,GAAG,OAAO;EACxD,aACE,UAAU,oBAAoB,GAAG,GAAG,OACjC,iBAAiB,GAAG,GAAG;;KAGlB,aACV,UAAU,WACV,GACA,UAAU,eAAe;EAEzB,kBAAkB,OAAO,0BAA0B,GAAG,OAAO;EAC7D,aACE,UAAU,oBAAoB,GAAG,GAAG,OACjC,iBAAiB,GAAG,GAAG;;iBAGd,YACd,UAAU,WACV,GACA,UAAU,eAAe,sBACzB;EAAW,QAAQ,SAAS,GAAG,GAAG;IAAO,aAAa,GAAG,GAAG;iBAC9C,YACd,UAAU,WACV,GACA,UAAU,eAAe,sBACzB;EAAW,UAAU,SAAS,GAAG,GAAG,QAAQ,GAAG,GAAG;IAAQ,QAAQ,GAAG,GAAG;iBA4J1D,WACd,UAAU,WACV,GACA,UAAU,eAAe,sBAEzB,QAAQ,SAAS,GAAG,GAAG,IACvB,mBACA,UAAS,kBAAkB,QAAQ,MAClC,iBAAiB,GAAG,GAAG"}

package/dist/react.d.ts

@@ -1,122 +1,2 @@
-import { a as ContractEvent, c as PresenceDefs, l as PresenceMap, p as WithPresence, r as AppendInput, s as EventDefs, t as Reducer, u as PresencePatch } from "./reducer-otzHjuJj.js";
-import { a as Connection, c as HistoryState, l as LoadHistoryOptions, t as A2Client, u as PushResult } from "./client-CzyacQpJ.js";
-import { ReactElement, ReactNode } from "react";
-//#region src/react.d.ts
-type UseSessionOptions<S> = {
-  /** Overrides the client's `participant` for this session — for apps
-   * whose identity is only known at mount time. Bound once per
-   * session handle. */
-  participant?: string;
-  /**
-   * The server fold this session mounts from: the `{ state, index }`
-   * pair `session.state(reducer)` returns, fetched by the app through
-   * its own route. Atomic on purpose — the fold and its frontier
-   * travel together or not at all. While `undefined` (the app's fetch
-   * has not landed), the hook holds the stream; when the value
-   * arrives, the session hydrates through the ordinary re-hydration
-   * seam and the stream connects at that frontier. To fold from the log's start
-   * deliberately, hand the fold's true starting point:
-   * `{ state: reducer.initialState, index: 0 }` — state at index 0 is
-   * the reducer's seed by definition, so the explicit replay needs no
-   * special vocabulary. There is no pending/ready echo on the result:
-   * whether the fold has been handed over is this option — the
-   * caller's own input — so the data layer's loading state IS the
-   * pending state.
-   */
-  hydrate?: {
-    state: S;
-    index: number;
-  } | undefined;
-};
-type SessionProviderProps<D extends EventDefs, S> = {
-  /** Which session to subscribe to. */
-  sessionId: string;
-  /** Base path of the route exposing GET (stream) and POST (push). */
-  api: string;
-  /** The server-rendered fold — the first paint, no client JS needed. */
-  initialState: S;
-  /** The fold's frontier — the stream resumes exactly there. */
-  initialIndex: number;
-  /** Server-rendered event history through `initialIndex`. */
-  initialEvents?: ContractEvent<D>[];
-  /** Overrides the client's `participant` for this session — for apps
-   * whose identity is only known at mount time. */
-  participant?: string;
-  children?: ReactNode;
-};
-type BoundSessionProviderProps<D extends EventDefs, S> = Omit<SessionProviderProps<D, S>, "api">;
-/**
- * The presence members of the hook result — intersected in via
- * `WithPresence`, so they exist exactly when the contract declares
- * presence fields (the reducer is the client's typed handle on it).
- */
-type UseSessionPresence<P extends PresenceDefs> = {
-  /** The replicated presence map, this client included (local echo). */
-  presence: PresenceMap<P>;
-  /**
-   * Fire-and-forget: validated locally, echoed into the map
-   * immediately, coalesced on the wire to a fixed cadence (a leading
-   * send immediately, then at most one merged send per interval;
-   * later values win per field), stamped with the frontier at send
-   * time as `seen`. Requires the provider's `participant`.
-   */
-  setPresence: (values: PresencePatch<P>["values"]) => void;
-};
-type UseSessionResult<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = WithPresence<P, UseSessionPresence<P>> & {
-  /** The live view, folded through the shared reducer. */
-  state: S;
-  /** The raw event feed — observed, seeded, or backscrolled. */
-  events: ContractEvent<D>[];
-  /** The stream frontier — `lastSeenIndex` for cancellation. */
-  index: number;
-  /**
-   * The connection, as a discriminated union — `error` exists only
-   * while disconnected; "reconnecting…" is
-   * `status === 'connecting' && reconnects > 0`.
-   */
-  connection: Connection;
-  /**
-   * Typed optimistic append. Awaiting it gives the server ack;
-   * `.confirmed` resolves when the live stream has delivered the batch
-   * back. Rejects with the server's A2Error codes.
-   */
-  push: (...events: AppendInput<D>[]) => PushResult<D>;
-  /** Restart the live subscription without resetting its state or cursor. */
-  reconnect: () => void;
-  /**
-   * Backscroll: fetch a bounded slice of older events into `events`.
-   * Defaults page backward 50 at a time from the oldest loaded event.
-   * Display data only — `state` and the optimistic overlay never move.
-   */
-  loadHistory: (options?: LoadHistoryOptions) => Promise<ContractEvent<D>[]>;
-  /** Backscroll progress: `complete` means the feed reaches index 1. */
-  history: HistoryState;
-};
-type A2React<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>, V = S> = {
-  SessionProvider: (props: SessionProviderProps<D, S>) => ReactElement;
-  useSession: () => UseSessionResult<D, V, P>;
-};
-type BoundA2React<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>, V = S> = {
-  SessionProvider: (props: BoundSessionProviderProps<D, S>) => ReactElement;
-  useSession: () => UseSessionResult<D, V, P>;
-};
-declare function createReact<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>, V = S>(options: {
-  client: A2Client<D, S, P, V>;
-}): BoundA2React<D, S, P, V>;
-declare function createReact<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>, V = S>(options: {
-  reducer: Reducer<D, S, P, V>;
-}): A2React<D, S, P, V>;
-/**
- * The standalone, provider-less hook — for apps whose components reach
- * sessions ad hoc (a sidebar of channel sessions, a user session read
- * from a menu). Takes the shared client and a session id; the handle
- * is identity-mapped, so every hook and provider mounting the same
- * session shares one runtime and one leased stream. Hydration is
- * app-owned: pass `hydrate` when your fetch lands; until then the
- * stream is held, and your data layer's loading state is the pending
- * state.
- */
-declare function useSession<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>, V = S>(client: A2Client<D, S, P, V>, sessionId: string, options?: UseSessionOptions<S>): UseSessionResult<D, V, P>;
-//#endregion
-export { A2React, BoundA2React, BoundSessionProviderProps, SessionProviderProps, UseSessionOptions, UseSessionPresence, UseSessionResult, createReact, useSession };
-//# sourceMappingURL=react.d.ts.map
+import { a as SessionProviderProps, c as UseSessionResult, i as BoundSessionProviderProps, l as createReact, n as BoundA2React, o as UseSessionOptions, r as BoundSessionOptions, s as UseSessionPresence, t as A2React, u as useSession } from "./react-BBXgHWFc.js";
+export { A2React, BoundA2React, BoundSessionOptions, BoundSessionProviderProps, SessionProviderProps, UseSessionOptions, UseSessionPresence, UseSessionResult, createReact, useSession };

package/dist/react.js

@@ -1,138 +1,145 @@
 "use client";
-import { t as createClient } from "./client-BYzHjkwU.js";
-import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
+import { i as isInitialPromise, n as createRenderSession, r as resolveInitialForReact, t as createClient } from "./client-BReKqwZC.js";
+import { createContext, createElement, use, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
 //#region src/react.ts
-/**
-* experimental-a2/react — React bindings over experimental-a2/client.
-*
-* `createReact({ client })` is a factory (like createContext): call it
-* once in a `'use client'` module with a shared A2 client and export the
-* bound pair. Server components import `SessionProvider` from that module
-* as a client reference; client components import `useSession` from the
-* same file. The shared client also makes imperative pushes and provider
-* renders resolve the same live session. Everything is typed by the
-* reducer value — no type arguments, and nothing here ever touches the
-* machine module.
-*
-* The standalone `useSession(client, sessionId, options?)` is the
-* provider-less primitive for client-first apps: identity-mapped
-* handles, one leased stream per session, and an app-owned hydration
-* input — the hook holds the stream until the app hands it a
-* `{ state, index }` fold.
-*/
 function createReact(options) {
 	const Context = createContext(null);
-	const resolveSession = "client" in options ? (sessionId, _api, initialState, initialIndex, initialEvents, participant) => options.client.session(sessionId, {
-		initialState,
-		initialIndex,
-		...initialEvents === void 0 ? {} : { initialEvents },
-		...participant === void 0 ? {} : { participant }
-	}) : (() => {
-		const clients = /* @__PURE__ */ new Map();
-		return (sessionId, api, initialState, initialIndex, initialEvents, participant) => {
-			if (api === void 0) throw new TypeError("SessionProvider requires api when createReact binds a reducer");
-			let client = clients.get(api);
-			if (!client) {
-				client = createClient({
-					reducer: options.reducer,
-					api
-				});
-				clients.set(api, client);
-			}
-			return client.session(sessionId, {
-				initialState,
-				initialIndex,
-				...initialEvents === void 0 ? {} : { initialEvents },
-				...participant === void 0 ? {} : { participant }
+	const clients = /* @__PURE__ */ new Map();
+	const resolveClient = (api) => {
+		if ("client" in options) return options.client;
+		if (api === void 0) throw new TypeError("SessionProvider requires api when createReact binds a contract");
+		let client = clients.get(api);
+		if (!client) {
+			client = createClient({
+				contract: options.contract,
+				api
 			});
-		};
-	})();
+			clients.set(api, client);
+		}
+		return client;
+	};
 	function SessionProvider(props) {
-		const { sessionId, initialState, initialIndex, initialEvents, participant } = props;
+		const { sessionId, initial, initialEvents, participant } = props;
 		const api = "api" in props ? props.api : void 0;
-		const client = useMemo(() => resolveSession(sessionId, api, initialState, initialIndex, initialEvents, participant), [
+		const scope = useMemo(() => ({
+			client: resolveClient(api),
+			sessionId,
+			settings: {
+				...initial === void 0 ? {} : { initial },
+				...initialEvents === void 0 ? {} : { initialEvents },
+				...participant === void 0 ? {} : { participant }
+			}
+		}), [
 			sessionId,
 			api,
-			initialState,
-			initialIndex,
+			initial,
 			initialEvents,
 			participant
 		]);
-		useSessionLifecycle(client, true);
-		return createElement(Context.Provider, { value: client }, props.children);
+		return createElement(Context.Provider, { value: scope }, props.children);
 	}
-	function useBoundSession() {
-		const client = useContext(Context);
-		if (!client) throw new Error("useSession must be rendered inside its matching SessionProvider");
-		return useSessionResult(client);
+	function useBoundSession(overrides = {}) {
+		const scope = useContext(Context);
+		const client = overrides.client ?? scope?.client ?? ("client" in options ? options.client : void 0);
+		const sessionId = overrides.sessionId ?? scope?.sessionId;
+		if (!client || sessionId === void 0) throw new TypeError("provide client and sessionId through SessionProvider or hook options");
+		const inherited = client === scope?.client && sessionId === scope?.sessionId ? scope.settings : void 0;
+		const { initial, participant } = overrides;
+		return useLiveSession({
+			client,
+			sessionId,
+			settings: useMemo(() => ({
+				...inherited,
+				...initial === void 0 ? {} : { initial },
+				...participant === void 0 ? {} : { participant }
+			}), [
+				inherited,
+				initial,
+				participant
+			]),
+			enabled: overrides.enabled ?? true,
+			suspend: overrides.suspend ?? false
+		});
 	}
 	return {
 		SessionProvider,
 		useSession: useBoundSession
 	};
 }
-/**
-* Hold a stream lease while mounted and `live` — the client refcounts
-* leases per handle, so however many providers and hooks mount one
-* session, the first connects and the last release closes
-* (StrictMode-safe: the lease is retaken on remount). A standalone
-* hook without a `hydrate` value passes `live: false` and holds the
-* stream — connecting an unhydrated session would replay the whole
-* log, and the library never picks the expensive path silently.
-*/
-function useSessionLifecycle(session, live) {
+function useLiveSession(options) {
+	const { client, sessionId, settings, enabled, suspend } = options;
+	const browserSession = useMemo(() => {
+		if (typeof window === "undefined") {
+			if (isInitialPromise(settings.initial)) settings.initial.catch(() => {});
+			return;
+		}
+		return client.session(sessionId, settings);
+	}, [
+		client,
+		sessionId,
+		settings
+	]);
+	const promise = isInitialPromise(settings.initial) ? settings.initial : void 0;
+	const resolved = promise && suspend ? use(promise) : void 0;
+	const renderInitial = promise ? resolved : settings.initial;
+	const renderSession = useMemo(() => {
+		let session;
+		return () => {
+			session ??= createRenderSession({
+				client,
+				sessionId,
+				settings: {
+					...settings,
+					initial: renderInitial
+				}
+			});
+			return session;
+		};
+	}, [
+		client,
+		sessionId,
+		settings,
+		renderInitial
+	]);
+	const session = browserSession ?? renderSession();
+	if (browserSession && promise && suspend) resolveInitialForReact({
+		client,
+		session: browserSession,
+		source: promise,
+		value: resolved
+	});
+	const serverSnapshot = useMemo(() => () => renderSession().getSnapshot(), [renderSession]);
+	const snapshot = useSyncExternalStore(session.subscribe, session.getSnapshot, serverSnapshot);
 	useEffect(() => {
-		if (!live) return;
-		return session.connect();
-	}, [session, live]);
-}
-function useSessionResult(session) {
-	const snapshot = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+		if (enabled) return session.connect();
+	}, [session, enabled]);
 	return useMemo(() => {
 		const { setPresence } = session;
 		const { presence } = snapshot;
 		return {
-			state: snapshot.state,
-			events: snapshot.events,
-			index: snapshot.index,
-			connection: snapshot.connection,
+			...snapshot,
 			push: session.push,
 			reconnect: session.reconnect,
 			loadHistory: session.loadHistory,
-			history: snapshot.history,
 			...setPresence && presence ? {
 				presence,
 				setPresence
 			} : {}
 		};
-	}, [snapshot, session]);
+	}, [session, snapshot]);
 }
-/**
-* The standalone, provider-less hook — for apps whose components reach
-* sessions ad hoc (a sidebar of channel sessions, a user session read
-* from a menu). Takes the shared client and a session id; the handle
-* is identity-mapped, so every hook and provider mounting the same
-* session shares one runtime and one leased stream. Hydration is
-* app-owned: pass `hydrate` when your fetch lands; until then the
-* stream is held, and your data layer's loading state is the pending
-* state.
-*/
-function useSession(client, sessionId, options) {
-	const { participant, hydrate } = options ?? {};
-	const session = useMemo(() => client.session(sessionId, {
-		...hydrate === void 0 ? {} : {
-			initialState: hydrate.state,
-			initialIndex: hydrate.index
-		},
-		...participant === void 0 ? {} : { participant }
-	}), [
+function useSession(client, sessionId, options = {}) {
+	const { initial, participant } = options;
+	return useLiveSession({
 		client,
 		sessionId,
-		hydrate,
-		participant
-	]);
-	useSessionLifecycle(session, hydrate !== void 0);
-	return useSessionResult(session);
+		settings: useMemo(() => ({
+			...initial === void 0 ? {} : { initial },
+			...participant === void 0 ? {} : { participant }
+		}), [initial, participant]),
+		enabled: options.enabled ?? true,
+		suspend: options.suspend ?? false
+	});
 }
 //#endregion
 export { createReact, useSession };