experimental-a2 0.0.0

package/dist/log-sqlite.d.ts

@@ -0,0 +1,17 @@
+import { c as IdSource, i as Clock, t as A2Log } from "./log-Dg1I8NRr.js";
+//#region src/log-sqlite.d.ts
+type SqliteLogOptions = {
+  /** Database file path. Defaults to `.a2/dev.db`; `:memory:` works. */
+  path?: string;
+  /** Injectable clock — every stored timestamp comes from here. */
+  clock?: Clock;
+  /** Injectable id source for generated event ids. */
+  ids?: IdSource;
+};
+type SqliteLog = A2Log & {
+  /** Close the underlying database handle. */
+  close(): void;
+};
+declare function sqlite(options?: SqliteLogOptions): SqliteLog;
+//#endregion
+export { SqliteLog, SqliteLogOptions, sqlite };

package/dist/log-sqlite.js

@@ -0,0 +1,450 @@
+import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./log-yJbXUf72.js";
+import { t as pollingStream } from "./log-polling-RO7kclzR.js";
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+//#region src/log-sqlite.ts
+/**
+* a2/log-sqlite — sqlite log backend (the dev default, `.a2/dev.db`).
+*
+* Built on `node:sqlite` (Node ≥ 22.13) so it ships with zero
+* dependencies. Implements the A2Log interface; the conformance suite
+* in test/conformance is the executable contract.
+*
+* The spec's `index` column is stored as `idx` (a2-implementation.md
+* §11 — `index` collides with a reserved word) and mapped back at the
+* API boundary. Timestamps are epoch milliseconds written from the
+* injected clock — never SQL `now()` — so tests can time-travel against
+* real storage.
+*/
+const SCHEMA = `
+create table if not exists a2_events (
+  session_id   text    not null,
+  idx          integer not null,
+  event_type   text    not null,
+  payload      text    not null,
+  event_id     text    not null,
+  created_at   integer not null,
+  cause        text,
+  processed_at integer,
+  processed_by_attempt integer,
+  first_claimed_at integer,
+  last_claimed_at integer,
+  attempt_count integer not null default 0,
+  failure_count integer not null default 0,
+  last_failed_at integer,
+  last_failed_attempt integer,
+  last_error   text,
+  failed_at    integer,
+  primary key (session_id, idx)
+) strict;
+
+create unique index if not exists a2_events_event_id on a2_events (event_id);
+create index if not exists a2_events_unprocessed
+  on a2_events (session_id, idx) where processed_at is null;
+
+create table if not exists a2_leases (
+  session_id text    primary key,
+  holder     text    not null,
+  expires_at integer not null
+) strict;
+
+create table if not exists a2_snapshots (
+  session_id   text    not null,
+  reducer_name text    not null,
+  up_to_index  integer not null,
+  state        text    not null,
+  updated_at   integer not null,
+  primary key (session_id, reducer_name)
+) strict;
+`;
+/**
+* Switching journal modes takes an exclusive lock, and — unlike normal
+* statements — the switch can return SQLITE_BUSY without consulting the
+* busy handler while several connections race it (instances cold-booting
+* against one file). Bounded synchronous retry; the window is boot-only
+* and tiny. Found by the multi-process torture test.
+*/
+const setWalJournalMode = (db) => {
+	for (let attempt = 0;; attempt += 1) try {
+		db.exec("pragma journal_mode = wal");
+		return;
+	} catch (err) {
+		if (!(err.errcode === 5) || attempt >= 100) throw err;
+		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+	}
+};
+const wrap = (fn) => {
+	try {
+		return fn();
+	} catch (err) {
+		if (err instanceof A2Error || err instanceof TypeError) throw err;
+		throw new A2Error("LOG_UNAVAILABLE", "sqlite log operation failed", { cause: err });
+	}
+};
+const toDate = (ms) => ms === null ? null : new Date(Number(ms));
+const toCause = (json) => {
+	if (json === null) return null;
+	const value = JSON.parse(json);
+	if (!Number.isInteger(value.index) || Number(value.index) < 1 || !Number.isInteger(value.attempt) || Number(value.attempt) < 1) throw new TypeError("stored event has an invalid cause");
+	return {
+		index: Number(value.index),
+		attempt: Number(value.attempt)
+	};
+};
+const toStored = (row) => ({
+	id: row.event_id,
+	type: row.event_type,
+	payload: JSON.parse(row.payload),
+	index: Number(row.idx),
+	sessionId: row.session_id,
+	createdAt: new Date(Number(row.created_at)),
+	cause: toCause(row.cause),
+	processedAt: toDate(row.processed_at),
+	processedByAttempt: row.processed_by_attempt === null ? null : Number(row.processed_by_attempt),
+	firstClaimedAt: toDate(row.first_claimed_at),
+	lastClaimedAt: toDate(row.last_claimed_at),
+	attemptCount: Number(row.attempt_count),
+	failureCount: Number(row.failure_count),
+	lastFailedAt: toDate(row.last_failed_at),
+	lastFailedAttempt: row.last_failed_attempt === null ? null : Number(row.last_failed_attempt),
+	lastError: row.last_error,
+	failedAt: toDate(row.failed_at)
+});
+const toEvent = (row) => ({
+	id: row.event_id,
+	type: row.event_type,
+	payload: JSON.parse(row.payload),
+	index: Number(row.idx),
+	sessionId: row.session_id,
+	createdAt: new Date(Number(row.created_at))
+});
+const requireChange = (changes, what) => {
+	if (Number(changes) === 0) throw new TypeError(what);
+};
+function sqlite(options = {}) {
+	const path = options.path ?? ".a2/dev.db";
+	const clock = options.clock ?? SYSTEM_CLOCK;
+	const generateId = options.ids ?? RANDOM_IDS;
+	if (path !== ":memory:") mkdirSync(dirname(resolve(
+		/* turbopackIgnore: true */
+		path
+	)), { recursive: true });
+	const db = new DatabaseSync(path);
+	db.exec("pragma busy_timeout = 5000");
+	setWalJournalMode(db);
+	db.exec("pragma synchronous = normal");
+	db.exec(SCHEMA);
+	const insertEvent = db.prepare(`insert into a2_events
+       (session_id, idx, event_type, payload, event_id, created_at,
+        cause)
+     values (?, ?, ?, ?, ?, ?, ?)`);
+	const maxIdx = db.prepare("select coalesce(max(idx), 0) as max from a2_events where session_id = ?");
+	const selectByIds = (count) => db.prepare(`select * from a2_events where event_id in (${Array.from({ length: count }, () => "?").join(", ")})
+       order by idx`);
+	const tx = (fn) => {
+		db.exec("begin immediate");
+		try {
+			const result = fn();
+			db.exec("commit");
+			return result;
+		} catch (err) {
+			try {
+				db.exec("rollback");
+			} catch {}
+			throw err;
+		}
+	};
+	return {
+		async append(sessionId, events) {
+			if (events.length === 0) return [];
+			return wrap(() => tx(() => {
+				const suppliedIds = events.filter((e) => e.id !== void 0).map((e) => e.id);
+				if (new Set(suppliedIds).size !== suppliedIds.length) throw new A2Error("PARTIAL_DUPLICATE_BATCH", "batch contains the same event id more than once");
+				if (suppliedIds.length > 0) {
+					const existing = selectByIds(suppliedIds.length).all(...suppliedIds);
+					if (existing.length > 0) {
+						const foreign = existing.find((row) => row.session_id !== sessionId);
+						if (foreign) throw new A2Error("PARTIAL_DUPLICATE_BATCH", `event id '${foreign.event_id}' already exists in another session`);
+						if (existing.length === events.length) return existing.map(toStored);
+						throw new A2Error("PARTIAL_DUPLICATE_BATCH", `batch mixes ${existing.length} already-appended and ${events.length - existing.length} fresh events`);
+					}
+				}
+				const base = Number(maxIdx.get(sessionId).max);
+				const now = clock.now().getTime();
+				return events.map((e, i) => {
+					const id = e.id ?? generateId();
+					const index = base + 1 + i;
+					insertEvent.run(sessionId, index, e.type, JSON.stringify(e.payload) ?? "null", id, now, e.cause ? JSON.stringify(e.cause) : null);
+					return {
+						id,
+						type: e.type,
+						payload: structuredClone(e.payload),
+						index,
+						sessionId,
+						createdAt: new Date(now),
+						cause: e.cause ? { ...e.cause } : null,
+						processedAt: null,
+						processedByAttempt: null,
+						firstClaimedAt: null,
+						lastClaimedAt: null,
+						attemptCount: 0,
+						failureCount: 0,
+						lastFailedAt: null,
+						lastFailedAttempt: null,
+						lastError: null,
+						failedAt: null
+					};
+				});
+			}));
+		},
+		async read(sessionId, opts) {
+			return wrap(() => {
+				const conditions = ["session_id = ?"];
+				const params = [sessionId];
+				if (opts?.afterIndex !== void 0) {
+					conditions.push("idx > ?");
+					params.push(opts.afterIndex);
+				}
+				if (opts?.unprocessedOnly) conditions.push("processed_at is null");
+				return db.prepare(`select * from a2_events where ${conditions.join(" and ")} order by idx`).all(...params).map(toStored);
+			});
+		},
+		async claimNext({ sessionId, holder, ttlMs, expiresAtMs, maxIndex }) {
+			return wrap(() => tx(() => {
+				const next = db.prepare(`select * from a2_events
+               where session_id = ? and processed_at is null
+               order by idx limit 1`).get(sessionId);
+				if (!next || next.failed_at !== null || maxIndex !== void 0 && Number(next.idx) > maxIndex) return { outcome: "settled" };
+				const now = clock.now().getTime();
+				const current = db.prepare("select holder, expires_at from a2_leases where session_id = ?").get(sessionId);
+				if (current && Number(current.expires_at) > now && current.holder !== holder) return { outcome: "busy" };
+				db.prepare(`insert into a2_leases (session_id, holder, expires_at) values (?, ?, ?)
+             on conflict (session_id) do update set
+               holder = excluded.holder,
+               expires_at = excluded.expires_at`).run(sessionId, holder, expiresAtMs ?? now + ttlMs);
+				const claimed = db.prepare(`update a2_events
+               set attempt_count = attempt_count + 1,
+                   first_claimed_at = coalesce(first_claimed_at, ?),
+                   last_claimed_at = ?
+               where session_id = ? and idx = ? and processed_at is null
+               returning *`).get(now, now, sessionId, next.idx);
+				if (!claimed) throw new TypeError(`no pending event at index ${String(next.idx)} in session '${sessionId}'`);
+				return {
+					outcome: "claimed",
+					event: toStored(claimed)
+				};
+			}));
+		},
+		async completeAndClaimNext({ sessionId, holder, completedIndex, attempt, maxIndex }) {
+			return wrap(() => tx(() => {
+				const now = clock.now().getTime();
+				if (!db.prepare(`update a2_events
+               set processed_at = ?, processed_by_attempt = ?
+               where session_id = ? and idx = ?
+                 and processed_at is null and attempt_count = ?
+               returning idx`).get(now, attempt, sessionId, completedIndex, attempt)) {
+					if (!db.prepare("select 1 from a2_events where session_id = ? and idx = ?").get(sessionId, completedIndex)) throw new TypeError(`no event at index ${completedIndex} in session '${sessionId}'`);
+					return { outcome: "superseded" };
+				}
+				const next = db.prepare(`select * from a2_events
+               where session_id = ? and processed_at is null
+               order by idx limit 1`).get(sessionId);
+				if (!next || next.failed_at !== null || maxIndex !== void 0 && Number(next.idx) > maxIndex) return { outcome: "settled" };
+				const lease = db.prepare("select holder, expires_at from a2_leases where session_id = ?").get(sessionId);
+				if (!lease || lease.holder !== holder || Number(lease.expires_at) <= now) return { outcome: "busy" };
+				const claimed = db.prepare(`update a2_events
+               set attempt_count = attempt_count + 1,
+                   first_claimed_at = coalesce(first_claimed_at, ?),
+                   last_claimed_at = ?
+               where session_id = ? and idx = ? and processed_at is null
+               returning *`).get(now, now, sessionId, next.idx);
+				if (!claimed) throw new TypeError(`no pending event at index ${String(next.idx)} in session '${sessionId}'`);
+				return {
+					outcome: "claimed",
+					event: toStored(claimed)
+				};
+			}));
+		},
+		async markProcessed(sessionId, index) {
+			wrap(() => {
+				const { changes } = db.prepare(`update a2_events
+             set processed_at = coalesce(processed_at, ?)
+             where session_id = ? and idx = ?`).run(clock.now().getTime(), sessionId, index);
+				requireChange(changes, `no event at index ${index} in session '${sessionId}'`);
+			});
+		},
+		async failAttempt({ sessionId, index, attempt, error, maxFailures }) {
+			return wrap(() => tx(() => {
+				const current = db.prepare("select * from a2_events where session_id = ? and idx = ?").get(sessionId, index);
+				if (!current) throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+				const failureCount = Number(current.failure_count);
+				if (current.processed_at !== null || Number(current.attempt_count) !== attempt) return {
+					outcome: "superseded",
+					failureCount
+				};
+				if (current.failed_at !== null) return {
+					outcome: "dead_lettered",
+					failureCount
+				};
+				const now = clock.now().getTime();
+				const nextFailureCount = failureCount + 1;
+				const deadLettered = nextFailureCount >= maxFailures;
+				db.prepare(`update a2_events set
+               failure_count = ?,
+               last_error = ?,
+               last_failed_at = ?,
+               last_failed_attempt = ?,
+               failed_at = ?
+             where session_id = ? and idx = ?`).run(nextFailureCount, error, now, attempt, deadLettered ? now : null, sessionId, index);
+				return {
+					outcome: deadLettered ? "dead_lettered" : "failed",
+					failureCount: nextFailureCount
+				};
+			}));
+		},
+		async markFailed(sessionId, index) {
+			wrap(() => {
+				const { changes } = db.prepare("update a2_events set failed_at = ? where session_id = ? and idx = ?").run(clock.now().getTime(), sessionId, index);
+				requireChange(changes, `no event at index ${index} in session '${sessionId}'`);
+			});
+		},
+		async readState(sessionId, reducerName) {
+			return wrap(() => {
+				const rows = db.prepare(`with snapshot as materialized (
+             select up_to_index, state
+               from a2_snapshots
+               where session_id = ? and reducer_name = ?
+             )
+             select 0 as row_order, 'snapshot' as row_kind,
+                    snapshot.up_to_index as snapshot_index,
+                    snapshot.state as snapshot_state,
+                    null as session_id, null as idx, null as event_type,
+                    null as payload, null as event_id, null as created_at,
+                    null as cause, null as processed_at,
+                    null as processed_by_attempt, null as first_claimed_at,
+                    null as last_claimed_at, null as attempt_count,
+                    null as failure_count, null as last_failed_at,
+                    null as last_failed_attempt, null as last_error,
+                    null as failed_at
+             from snapshot
+             union all
+             select 1 as row_order, 'event' as row_kind,
+                    null as snapshot_index, null as snapshot_state,
+                    event.*
+             from a2_events as event
+             where event.session_id = ?
+               and event.idx > coalesce((select up_to_index from snapshot), 0)
+             order by row_order, idx`).all(sessionId, reducerName, sessionId);
+				const snapshot = rows.find((row) => row.row_kind === "snapshot");
+				return {
+					snapshot: snapshot ? {
+						index: Number(snapshot.snapshot_index),
+						state: JSON.parse(snapshot.snapshot_state)
+					} : null,
+					events: rows.filter((row) => row.row_kind === "event").map(toEvent)
+				};
+			});
+		},
+		async putSnapshot(sessionId, reducerName, index, state) {
+			wrap(() => {
+				db.prepare(`insert into a2_snapshots (session_id, reducer_name, up_to_index, state, updated_at)
+           values (?, ?, ?, ?, ?)
+           on conflict (session_id, reducer_name) do update set
+             up_to_index = excluded.up_to_index,
+             state = excluded.state,
+             updated_at = excluded.updated_at
+           where excluded.up_to_index > a2_snapshots.up_to_index`).run(sessionId, reducerName, index, JSON.stringify(state) ?? "null", clock.now().getTime());
+			});
+		},
+		inspect: {
+			async listSessions(inspectionOptions) {
+				return wrap(() => {
+					const conditions = ["substr(session_id, 1, ?) = ?"];
+					const params = [inspectionOptions.prefix.length, inspectionOptions.prefix];
+					if (inspectionOptions.cursor !== void 0) {
+						conditions.push("session_id > ?");
+						params.push(inspectionOptions.cursor);
+					}
+					params.push(inspectionOptions.limit + 1);
+					const rows = db.prepare(`select
+                 session_id,
+                 count(*) as event_count,
+                 sum(case when processed_at is null and failed_at is null then 1 else 0 end) as pending_count,
+                 sum(case when failed_at is not null then 1 else 0 end) as failed_count,
+                 sum(attempt_count) as attempt_count,
+                 sum(failure_count) as failure_count,
+                 min(created_at) as first_event_at,
+                 max(max(
+                   created_at,
+                   coalesce(first_claimed_at, 0),
+                   coalesce(last_claimed_at, 0),
+                   coalesce(last_failed_at, 0),
+                   coalesce(processed_at, 0),
+                   coalesce(failed_at, 0)
+                 )) as updated_at
+               from a2_events
+               where ${conditions.join(" and ")}
+               group by session_id
+               order by session_id
+               limit ?`).all(...params);
+					const hasMore = rows.length > inspectionOptions.limit;
+					const visible = rows.slice(0, inspectionOptions.limit);
+					return {
+						sessions: visible.map((row) => ({
+							sessionId: row.session_id,
+							eventCount: Number(row.event_count),
+							pendingCount: Number(row.pending_count),
+							failedCount: Number(row.failed_count),
+							attemptCount: Number(row.attempt_count),
+							failureCount: Number(row.failure_count),
+							firstEventAt: new Date(Number(row.first_event_at)),
+							updatedAt: new Date(Number(row.updated_at))
+						})),
+						cursor: hasMore ? visible.at(-1)?.session_id ?? null : null
+					};
+				});
+			},
+			async listSnapshots(sessionId) {
+				return wrap(() => {
+					return db.prepare(`select reducer_name, up_to_index, updated_at
+               from a2_snapshots where session_id = ? order by reducer_name`).all(sessionId).map((row) => ({
+						reducerName: row.reducer_name,
+						index: Number(row.up_to_index),
+						updatedAt: new Date(Number(row.updated_at))
+					}));
+				});
+			}
+		},
+		stream(sessionId, opts) {
+			const readAfter = (afterIndex) => wrap(() => {
+				return db.prepare("select * from a2_events where session_id = ? and idx > ? order by idx").all(sessionId, afterIndex).map(toStored);
+			});
+			return pollingStream(readAfter, opts?.startAt !== void 0 ? { startAt: opts.startAt } : {});
+		},
+		lease: {
+			async acquire({ sessionId, holder, ttlMs, expiresAtMs }) {
+				return wrap(() => tx(() => {
+					const now = clock.now().getTime();
+					const expiresAt = expiresAtMs ?? now + ttlMs;
+					const current = db.prepare("select * from a2_leases where session_id = ?").get(sessionId);
+					if (current && Number(current.expires_at) > now && current.holder !== holder) return false;
+					db.prepare(`insert into a2_leases (session_id, holder, expires_at) values (?, ?, ?)
+               on conflict (session_id) do update set holder = excluded.holder, expires_at = excluded.expires_at`).run(sessionId, holder, expiresAt);
+					return true;
+				}));
+			},
+			async release({ sessionId, holder }) {
+				wrap(() => {
+					db.prepare("delete from a2_leases where session_id = ? and holder = ?").run(sessionId, holder);
+				});
+			}
+		},
+		close() {
+			db.close();
+		}
+	};
+}
+//#endregion
+export { sqlite };

package/dist/log-yJbXUf72.js

@@ -0,0 +1,5 @@
+//#region src/log.ts
+const SYSTEM_CLOCK = { now: () => /* @__PURE__ */ new Date() };
+const RANDOM_IDS = () => crypto.randomUUID();
+//#endregion
+export { SYSTEM_CLOCK as n, RANDOM_IDS as t };

package/dist/otel.d.ts

@@ -0,0 +1,12 @@
+import { i as A2Telemetry } from "./telemetry-C78al20p.js";
+import { Tracer } from "@opentelemetry/api";
+//#region src/otel.d.ts
+type OtelOptions = {
+  /** Bring your own tracer; defaults to `trace.getTracer(tracerName)`. */
+  tracer?: Tracer;
+  /** Tracer name for the global provider. Default `'a2'`. */
+  tracerName?: string;
+};
+declare function otel(options?: OtelOptions): A2Telemetry;
+//#endregion
+export { OtelOptions, otel };

package/dist/otel.js

@@ -0,0 +1,41 @@
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+//#region src/otel.ts
+/**
+* a2/otel — OpenTelemetry adapter for the A2Telemetry interface.
+*
+* Peer-depends on `@opentelemetry/api` (optional). Spans nest through
+* the active context, so with a context manager registered (any real
+* OTel setup, e.g. `@vercel/otel`) the happy path lands in one trace:
+* request → a2.append → a2.drain → a2.event → the handler's own spans.
+*/
+const fail = (span, error) => {
+	span.recordException(error instanceof Error ? error : new Error(String(error)));
+	span.setStatus({
+		code: SpanStatusCode.ERROR,
+		message: error instanceof Error ? error.message : String(error)
+	});
+};
+function otel(options = {}) {
+	const tracer = options.tracer ?? trace.getTracer(options.tracerName ?? "a2");
+	return { span(name, attributes, fn) {
+		return tracer.startActiveSpan(name, { attributes }, async (span) => {
+			try {
+				return await fn({
+					setAttribute: (key, value) => {
+						span.setAttribute(key, value);
+					},
+					recordError: (error) => {
+						fail(span, error);
+					}
+				});
+			} catch (error) {
+				fail(span, error);
+				throw error;
+			} finally {
+				span.end();
+			}
+		});
+	} };
+}
+//#endregion
+export { otel };

package/dist/react.d.ts

@@ -0,0 +1,54 @@
+import { i as EventDefs, r as ContractEvent, s as Reducer, t as AppendInput } from "./contract-DL8btVd9.js";
+import { A2Client, Connection, PushResult } from "./client.js";
+import { ReactElement, ReactNode } from "react";
+//#region src/react.d.ts
+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>[];
+  children?: ReactNode;
+};
+type BoundSessionProviderProps<D extends EventDefs, S> = Omit<SessionProviderProps<D, S>, "api">;
+type UseSessionResult<D extends EventDefs, S> = {
+  /** The live view, folded through the shared reducer. */
+  state: S;
+  /** The raw observed feed `state` is folded from. */
+  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>;
+};
+type A2React<D extends EventDefs, S> = {
+  SessionProvider: (props: SessionProviderProps<D, S>) => ReactElement;
+  useSession: () => UseSessionResult<D, S>;
+};
+type BoundA2React<D extends EventDefs, S> = {
+  SessionProvider: (props: BoundSessionProviderProps<D, S>) => ReactElement;
+  useSession: () => UseSessionResult<D, S>;
+};
+declare function createReact<D extends EventDefs, S>(options: {
+  client: A2Client<D, S>;
+}): BoundA2React<D, S>;
+declare function createReact<D extends EventDefs, S>(options: {
+  reducer: Reducer<D, S>;
+}): A2React<D, S>;
+//#endregion
+export { A2React, BoundA2React, BoundSessionProviderProps, SessionProviderProps, UseSessionResult, createReact };

package/dist/react.js

@@ -0,0 +1,85 @@
+"use client";
+import { createClient } from "./client.js";
+import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
+//#region src/react.ts
+/**
+* a2/react — React bindings over 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.
+*/
+function createReact(options) {
+	const Context = createContext(null);
+	const providerMounts = /* @__PURE__ */ new WeakMap();
+	const resolveSession = "client" in options ? (sessionId, _api, initialState, initialIndex, initialEvents) => options.client.session(sessionId, {
+		initialState,
+		initialIndex,
+		...initialEvents === void 0 ? {} : { initialEvents }
+	}) : (() => {
+		const clients = /* @__PURE__ */ new Map();
+		return (sessionId, api, initialState, initialIndex, initialEvents) => {
+			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 }
+			});
+		};
+	})();
+	function SessionProvider(props) {
+		const { sessionId, initialState, initialIndex, initialEvents } = props;
+		const api = "api" in props ? props.api : void 0;
+		const client = useMemo(() => resolveSession(sessionId, api, initialState, initialIndex, initialEvents), [
+			sessionId,
+			api,
+			initialState,
+			initialIndex,
+			initialEvents
+		]);
+		useEffect(() => {
+			const mounts = providerMounts.get(client) ?? 0;
+			providerMounts.set(client, mounts + 1);
+			if (mounts === 0) client.connect();
+			return () => {
+				const remaining = (providerMounts.get(client) ?? 1) - 1;
+				if (remaining === 0) {
+					providerMounts.delete(client);
+					client.close();
+				} else providerMounts.set(client, remaining);
+			};
+		}, [client]);
+		return createElement(Context.Provider, { value: client }, props.children);
+	}
+	function useSession() {
+		const client = useContext(Context);
+		if (!client) throw new Error("useSession must be rendered inside its matching SessionProvider");
+		const snapshot = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
+		return useMemo(() => ({
+			state: snapshot.state,
+			events: snapshot.events,
+			index: snapshot.index,
+			connection: snapshot.connection,
+			push: client.push
+		}), [snapshot, client]);
+	}
+	return {
+		SessionProvider,
+		useSession
+	};
+}
+//#endregion
+export { createReact };