experimental-a2 0.2.0 → 0.4.0

package/dist/client.d.ts

@@ -1,90 +1,2 @@
-import { a as EventDefs, c as Reducer, r as ContractEvent, t as AppendInput } from "./contract-C_3dIIEU.js";
-//#region src/client.d.ts
-type ConnectionStatus = "idle" | "connecting" | "live" | "closed";
-/**
- * The connection, as a discriminated union — impossible states are
- * unrepresentable: an error only exists while disconnected,
- * `reconnects` only once a connection has been attempted.
- * "Reconnecting…" is `status === 'connecting' && reconnects > 0`.
- */
-type Connection = {
-  status: "idle";
-} | {
-  status: "connecting";
-  /** Drops of an established stream so far. `0` = first connect. */
-  reconnects: number;
-  /** Why the last connection ended; `null` on the first connect. */
-  error: Error | null;
-} | {
-  status: "live";
-  reconnects: number;
-} | {
-  status: "closed";
-};
-/**
- * What `push` returns: resolves at the server ack (exactly like a
- * plain promise — `await push(...)` gives the acked events), and
- * carries `confirmed` for the later moment when the live stream has
- * delivered the whole batch back and the optimistic overlay entry
- * retired — the view now shows server truth. `confirmed` is lazy:
- * never accessed, never created. A rejected push rejects both.
- */
-type PushResult<D extends EventDefs> = Promise<ContractEvent<D>[]> & {
-  readonly confirmed: Promise<ContractEvent<D>[]>;
-};
-/** One immutable view of the session — stable identity between changes. */
-type SessionSnapshot<D extends EventDefs, S> = {
-  /** The live view: server events folded, optimistic pushes applied. */
-  state: S;
-  /** The observed feed `state` is folded from — server truth plus
-   * pending optimistic events (provisional indexes past the frontier). */
-  events: ContractEvent<D>[];
-  /** The stream frontier: the last server-confirmed index. This is the
-   * `lastSeenIndex` cancellation wants. */
-  index: number;
-  connection: Connection;
-};
-type SessionClient<D extends EventDefs, S> = {
-  readonly sessionId: string;
-  subscribe(listener: () => void): () => void;
-  getSnapshot(): SessionSnapshot<D, S>;
-  /**
-   * Optimistic append: validates locally against the reducer's event
-   * schemas (instant `INVALID_PAYLOAD`, no flicker), applies to the
-   * local fold, POSTs, swaps in the ack, rolls back on rejection.
-   * Auto-retries only `LOG_UNAVAILABLE`. Resolves with the appended
-   * events as the server recorded them.
-   */
-  push(...events: AppendInput<D>[]): PushResult<D>;
-  /** Open the live stream (idempotent while open). Reconnects with
-   * backoff and resumes from the frontier until `close()`. */
-  connect(): void;
-  /**
-   * Stop the live stream. Not terminal: `connect()` starts it again
-   * from the current frontier — which is what makes the React
-   * StrictMode mount dance (setup → cleanup → setup) work.
-   */
-  close(): void;
-};
-type SessionOptions<D extends EventDefs, S> = {
-  initialState?: S;
-  initialIndex?: number;
-  /** Server-rendered history through `initialIndex`. Seeds the event feed. */
-  initialEvents?: ContractEvent<D>[];
-};
-type A2Client<D extends EventDefs, S> = {
-  session(sessionId: string, options?: SessionOptions<D, S>): SessionClient<D, S>;
-};
-type CreateClientOptions<D extends EventDefs, S> = {
-  reducer: Reducer<D, S>;
-  /** Base path (or absolute URL) of the route exposing GET/POST. */
-  api: string;
-  /** Injectable fetch — defaults to the global. */
-  fetch?: typeof globalThis.fetch;
-  /** How long an idle session keeps its in-memory identity, in
-   * milliseconds. Defaults to five minutes; `Infinity` disables GC. */
-  gcTime?: number;
-};
-declare function createClient<D extends EventDefs, S>(options: CreateClientOptions<D, S>): A2Client<D, S>;
-//#endregion
-export { A2Client, Connection, ConnectionStatus, CreateClientOptions, PushResult, SessionClient, SessionOptions, SessionSnapshot, createClient };
+import { a as Connection, c as PushResult, d as SessionOptions, f as SessionSnapshot, i as ClientWebSocketConstructor, l as SessionClient, n as ClientApi, o as ConnectionStatus, p as createClient, r as ClientWebSocket, s as CreateClientOptions, t as A2Client, u as SessionClientPresence } from "./client-BrfDXQ8A.js";
+export { A2Client, ClientApi, ClientWebSocket, ClientWebSocketConstructor, Connection, ConnectionStatus, CreateClientOptions, PushResult, SessionClient, SessionClientPresence, SessionOptions, SessionSnapshot, createClient };

package/dist/client.js

@@ -1,410 +1,2 @@
-import { n as validateSync } from "./validate-XKT4FSNn.js";
-import { t as A2Error } from "./errors-BJRMd-h6.js";
-import { r as STREAM_TIMINGS } from "./internal-D6wNxTck.js";
-import { i as eventFromWire, o as isWireEvent, t as errorFromWire } from "./wire-BVsgR8o9.js";
-//#region src/client.ts
-/**
-* experimental-a2/client — the framework-agnostic session client.
-*
-* Everything the browser needs to read a session live and push
-* optimistically, with no framework attached: the SSE subscription with
-* frontier resume and reconnection, the optimistic push queue with
-* ack/rollback, and the local fold through the same reducer the server
-* uses. `experimental-a2/react`'s `createReact` is a thin binding over it, and the
-* store contract (`subscribe`/`getSnapshot`) is exactly what
-* `useSyncExternalStore` wants.
-*
-* The client is a replica, never an access path — the routes it talks
-* to authorize every read and write.
-*/
-const PUSH_ATTEMPTS = 3;
-const RECONNECT_BASE_MS = 500;
-const RECONNECT_MAX_MS = 5e3;
-const DEFAULT_GC_TIME_MS = 3e5;
-function createClient(options) {
-	const { reducer, api } = options;
-	const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
-	const gcTime = options.gcTime ?? DEFAULT_GC_TIME_MS;
-	if (Number.isNaN(gcTime) || gcTime < 0) throw new RangeError("gcTime must be a non-negative number or Infinity");
-	const sessions = /* @__PURE__ */ new Map();
-	const scheduleGc = (sessionId, delay = gcTime) => {
-		const entry = sessions.get(sessionId);
-		if (!entry) return;
-		clearTimeout(entry.timer);
-		if (gcTime === Infinity) return;
-		entry.timer = setTimeout(() => {
-			if (sessions.get(sessionId) !== entry) return;
-			if (entry.runtime.canEvict()) {
-				sessions.delete(sessionId);
-				return;
-			}
-			scheduleGc(sessionId, Math.max(gcTime, 1e3));
-		}, delay);
-		entry.timer.unref?.();
-	};
-	const touch = (sessionId) => {
-		scheduleGc(sessionId);
-	};
-	const makeSession = (sessionId, sessionOptions) => {
-		let frontier = sessionOptions?.initialIndex ?? 0;
-		let foldedState = sessionOptions?.initialState !== void 0 ? sessionOptions.initialState : reducer.initialState;
-		const serverEvents = (sessionOptions?.initialEvents ?? []).filter((event) => event.index <= frontier).toSorted((a, b) => a.index - b.index);
-		let pending = [];
-		const listeners = /* @__PURE__ */ new Set();
-		let snapshot = null;
-		let status = "idle";
-		let reconnects = 0;
-		let lastError = null;
-		let inFlightPushes = 0;
-		let deferredHydration;
-		let hydrationNotification;
-		const emit = () => {
-			for (const listener of [...listeners]) listener();
-		};
-		const notify = () => {
-			snapshot = null;
-			emit();
-		};
-		const notifyHydrated = () => {
-			snapshot = null;
-			clearTimeout(hydrationNotification);
-			hydrationNotification = setTimeout(emit, 0);
-			hydrationNotification.unref?.();
-		};
-		const mergeServerEvents = (events, throughIndex) => {
-			if (!events || events.length === 0) return false;
-			const byIndex = new Map(serverEvents.map((event) => [event.index, event]));
-			let changed = false;
-			for (const event of events) {
-				if (event.index > throughIndex) continue;
-				if (byIndex.get(event.index)?.id === event.id) continue;
-				byIndex.set(event.index, event);
-				changed = true;
-			}
-			if (!changed) return false;
-			serverEvents.splice(0, serverEvents.length, ...[...byIndex.values()].toSorted((a, b) => a.index - b.index));
-			return true;
-		};
-		const overlayEvents = () => {
-			const acked = pending.filter((p) => p.acked).map((p) => p.acked).toSorted((a, b) => a.index - b.index);
-			const maxKnown = acked.at(-1)?.index ?? frontier;
-			const unacked = pending.filter((p) => !p.acked).map((p, i) => ({
-				id: p.id,
-				type: p.type,
-				payload: p.payload,
-				index: maxKnown + 1 + i,
-				sessionId,
-				createdAt: p.createdAt
-			}));
-			return [...acked, ...unacked];
-		};
-		const connection = () => {
-			switch (status) {
-				case "idle": return { status: "idle" };
-				case "closed": return { status: "closed" };
-				case "live": return {
-					status: "live",
-					reconnects
-				};
-				case "connecting": return {
-					status: "connecting",
-					reconnects,
-					error: lastError
-				};
-			}
-		};
-		const buildSnapshot = () => {
-			const overlay = overlayEvents();
-			let state = foldedState;
-			for (const event of overlay) state = reducer.fold(state, event);
-			return {
-				state,
-				events: [...serverEvents, ...overlay],
-				index: frontier,
-				connection: connection()
-			};
-		};
-		/** Pushes awaiting stream confirmation — resolved by `ingest` the
-		* moment the frontier passes their batch. */
-		let confirmWatchers = [];
-		/** The single ingest point: every server-confirmed event, in log
-		* order, from the stream. */
-		const ingest = (event) => {
-			if (event.index <= frontier) return;
-			frontier = event.index;
-			serverEvents.push(event);
-			foldedState = reducer.fold(foldedState, event);
-			pending = pending.filter((p) => p.id !== event.id);
-			if (confirmWatchers.some((w) => w.index <= frontier)) {
-				const due = confirmWatchers.filter((w) => w.index <= frontier);
-				confirmWatchers = confirmWatchers.filter((w) => w.index > frontier);
-				for (const watcher of due) watcher.resolve();
-			}
-			notify();
-			touch(sessionId);
-		};
-		const validated = (events) => events.map((event) => {
-			const schema = Object.hasOwn(reducer.events, event.type) ? reducer.events[event.type] : void 0;
-			if (!schema) throw new A2Error("UNKNOWN_EVENT_TYPE", `no event type '${String(event.type)}' in the reducer's vocabulary`);
-			const result = validateSync(schema, event.payload, `event '${String(event.type)}'`);
-			if (result.issues) throw new A2Error("INVALID_PAYLOAD", `invalid payload for event '${String(event.type)}'`, { details: result.issues });
-			return {
-				id: event.id ?? crypto.randomUUID(),
-				type: event.type,
-				payload: result.value
-			};
-		});
-		const post = async (body) => {
-			let lastPushError = new A2Error("LOG_UNAVAILABLE", "push failed");
-			for (let attempt = 1; attempt <= PUSH_ATTEMPTS; attempt += 1) {
-				try {
-					const res = await fetchImpl(api, {
-						method: "POST",
-						headers: { "content-type": "application/json" },
-						body: JSON.stringify(body)
-					});
-					if (res.ok) {
-						const rows = await res.json();
-						if (!Array.isArray(rows) || !rows.every(isWireEvent)) throw new A2Error("LOG_UNAVAILABLE", "push ack was not a list of events");
-						return rows.map((row) => eventFromWire(row));
-					}
-					lastPushError = errorFromWire(await res.json().catch(() => null)) ?? new A2Error("LOG_UNAVAILABLE", `push failed with ${res.status}`);
-				} catch (err) {
-					lastPushError = err instanceof A2Error ? err : new A2Error("LOG_UNAVAILABLE", "push request failed", { cause: err });
-				}
-				if (lastPushError.code !== "LOG_UNAVAILABLE") throw lastPushError;
-				if (attempt < PUSH_ATTEMPTS) await new Promise((resolve) => setTimeout(resolve, 250 * attempt));
-			}
-			throw lastPushError;
-		};
-		/**
-		* Decorate the ack promise into a PushResult. `confirmed` is a
-		* lazy getter — materialized on first access, so callers that
-		* ignore it can't leak an unhandled rejection.
-		*/
-		const withConfirmed = (ack) => {
-			let confirmed;
-			return Object.defineProperty(ack, "confirmed", { get() {
-				confirmed ??= ack.then((acked) => new Promise((resolve) => {
-					const last = acked.at(-1)?.index ?? 0;
-					if (frontier >= last) {
-						resolve(acked);
-						return;
-					}
-					confirmWatchers.push({
-						index: last,
-						resolve: () => resolve(acked)
-					});
-				}));
-				return confirmed;
-			} });
-		};
-		const push = (...events) => {
-			touch(sessionId);
-			return withConfirmed((async () => {
-				if (events.length === 0) throw new TypeError("push requires at least one event");
-				const entries = validated(events).map((e) => ({
-					id: e.id,
-					type: e.type,
-					payload: e.payload,
-					createdAt: /* @__PURE__ */ new Date()
-				}));
-				pending.push(...entries);
-				inFlightPushes += 1;
-				notify();
-				try {
-					const acked = await post({
-						sessionId,
-						events: entries.map(({ id, type, payload }) => ({
-							id,
-							type,
-							payload
-						}))
-					});
-					for (const event of acked) {
-						const entry = pending.find((p) => p.id === event.id);
-						if (entry) entry.acked = event;
-					}
-					notify();
-					return acked;
-				} catch (err) {
-					const ids = new Set(entries.map((e) => e.id));
-					pending = pending.filter((p) => !ids.has(p.id));
-					notify();
-					throw err;
-				} finally {
-					inFlightPushes -= 1;
-					if (inFlightPushes === 0 && deferredHydration) {
-						const next = deferredHydration;
-						deferredHydration = void 0;
-						runtime.hydrate(next);
-					}
-					touch(sessionId);
-				}
-			})());
-		};
-		let generation = 0;
-		let active = false;
-		let abort = null;
-		const streamUrl = () => {
-			const sep = api.includes("?") ? "&" : "?";
-			return `${api}${sep}sessionId=${encodeURIComponent(sessionId)}&index=${frontier}`;
-		};
-		const consume = async (body, onActivity) => {
-			const decoder = new TextDecoder();
-			const reader = body.getReader();
-			let buffer = "";
-			try {
-				for (;;) {
-					const { done, value } = await reader.read();
-					if (done) return;
-					onActivity();
-					buffer += decoder.decode(value, { stream: true });
-					for (;;) {
-						const boundary = buffer.indexOf("\n\n");
-						if (boundary === -1) break;
-						const frame = buffer.slice(0, boundary);
-						buffer = buffer.slice(boundary + 2);
-						const data = frame.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
-						if (!data) continue;
-						const parsed = JSON.parse(data);
-						if (isWireEvent(parsed)) ingest(eventFromWire(parsed));
-					}
-				}
-			} finally {
-				reader.cancel().catch(() => {});
-			}
-		};
-		const runStream = async (run) => {
-			let backoff = RECONNECT_BASE_MS;
-			while (generation === run) {
-				const controller = new AbortController();
-				abort = controller;
-				let stall;
-				let stalled = false;
-				const armStall = () => {
-					clearTimeout(stall);
-					stall = setTimeout(() => {
-						stalled = true;
-						controller.abort();
-					}, STREAM_TIMINGS.stallTimeoutMs);
-					stall.unref?.();
-				};
-				let wasLive = false;
-				try {
-					const res = await fetchImpl(streamUrl(), {
-						headers: { accept: "text/event-stream" },
-						signal: controller.signal
-					});
-					if (!res.ok || !res.body) throw new Error(`stream failed with ${res.status}`);
-					if (generation !== run) break;
-					backoff = RECONNECT_BASE_MS;
-					wasLive = true;
-					status = "live";
-					lastError = null;
-					notify();
-					armStall();
-					await consume(res.body, armStall);
-					if (generation === run) lastError = null;
-				} catch (err) {
-					if (generation === run) lastError = stalled ? /* @__PURE__ */ new Error(`stream stalled: no data for ${STREAM_TIMINGS.stallTimeoutMs}ms`) : err instanceof Error ? err : new Error(String(err));
-				} finally {
-					clearTimeout(stall);
-				}
-				if (generation !== run) break;
-				if (wasLive) reconnects += 1;
-				status = "connecting";
-				notify();
-				await new Promise((resolve) => {
-					let settled = false;
-					const finish = () => {
-						if (settled) return;
-						settled = true;
-						clearTimeout(timer);
-						resolve();
-					};
-					const timer = setTimeout(finish, backoff);
-					timer.unref?.();
-					abort?.signal.addEventListener("abort", finish);
-				});
-				backoff = Math.min(backoff * 2, RECONNECT_MAX_MS);
-			}
-		};
-		const runtime = {
-			sessionId,
-			subscribe(listener) {
-				touch(sessionId);
-				listeners.add(listener);
-				return () => {
-					listeners.delete(listener);
-					touch(sessionId);
-				};
-			},
-			getSnapshot() {
-				snapshot ??= buildSnapshot();
-				return snapshot;
-			},
-			push,
-			connect() {
-				touch(sessionId);
-				if (active) return;
-				active = true;
-				status = "connecting";
-				notify();
-				runStream(generation);
-			},
-			close() {
-				touch(sessionId);
-				if (!active) return;
-				active = false;
-				generation += 1;
-				abort?.abort();
-				abort = null;
-				status = "closed";
-				notify();
-			},
-			hydrate(next) {
-				touch(sessionId);
-				if (!next) return;
-				const nextIndex = next.initialIndex ?? 0;
-				if (nextIndex > frontier && inFlightPushes > 0) {
-					if (!deferredHydration || nextIndex > (deferredHydration.initialIndex ?? 0)) deferredHydration = next;
-					return;
-				}
-				const historyChanged = mergeServerEvents(next.initialEvents, Math.min(nextIndex, frontier));
-				if (next.initialState === void 0 || nextIndex <= frontier) {
-					if (historyChanged) notifyHydrated();
-					return;
-				}
-				frontier = nextIndex;
-				foldedState = next.initialState;
-				mergeServerEvents(next.initialEvents, frontier);
-				pending = pending.filter((entry) => !entry.acked || entry.acked.index > frontier);
-				if (confirmWatchers.some((watcher) => watcher.index <= frontier)) {
-					const due = confirmWatchers.filter((watcher) => watcher.index <= frontier);
-					confirmWatchers = confirmWatchers.filter((watcher) => watcher.index > frontier);
-					for (const watcher of due) watcher.resolve();
-				}
-				notifyHydrated();
-			},
-			canEvict() {
-				return listeners.size === 0 && !active && inFlightPushes === 0 && confirmWatchers.length === 0;
-			}
-		};
-		return runtime;
-	};
-	return { session(sessionId, sessionOptions) {
-		const existing = sessions.get(sessionId);
-		if (existing) {
-			existing.runtime.hydrate(sessionOptions);
-			touch(sessionId);
-			return existing.runtime;
-		}
-		const runtime = makeSession(sessionId, sessionOptions);
-		sessions.set(sessionId, { runtime });
-		touch(sessionId);
-		return runtime;
-	} };
-}
-//#endregion
+import { t as createClient } from "./client-Bt4tAKi9.js";
 export { createClient };

package/dist/{contract-CG_adnu_.js → contract-48bUMgcL.js}

@@ -1,7 +1,7 @@
 import { n as validateSync, t as assertSyncSchema } from "./validate-XKT4FSNn.js";
 //#region src/reducer.ts
 /** Internal — reducers are created through `contract.reducer(...).fold(...)`. */
-function makeReducerBuilder(events, options) {
+function makeReducerBuilder(events, presence, options) {
 	const { name } = options;
 	if (typeof name !== "string" || name.length === 0) throw new TypeError("reducer name must be a non-empty string — it identifies the reducer and keys cached snapshots");
 	let initialState = options.initialState;
@@ -15,6 +15,7 @@ function makeReducerBuilder(events, options) {
 		return {
 			name,
 			events,
+			presence,
 			fold,
 			initialState,
 			stateSchema: options.stateSchema
@@ -48,12 +49,19 @@ function contract(options) {
 		assertSyncSchema(schema, `event '${type}'`);
 	}
 	const events = Object.freeze({ ...defs });
+	const presenceDefs = options.presence ?? {};
+	for (const [field, schema] of Object.entries(presenceDefs)) {
+		if (typeof schema?.["~standard"]?.validate !== "function") throw new TypeError(`contract '${name}': the value for presence field '${field}' is not a Standard Schema (expected an object with '~standard')`);
+		assertSyncSchema(schema, `presence field '${field}'`);
+	}
+	const presence = Object.freeze({ ...presenceDefs });
 	return {
 		name,
 		events,
+		presence,
 		batch: (...items) => items,
 		reducer(reducerOptions) {
-			return makeReducerBuilder(events, reducerOptions);
+			return makeReducerBuilder(events, presence, reducerOptions);
 		}
 	};
 }

package/dist/{contract-C_3dIIEU.d.ts → contract-jIfaR085.d.ts}

@@ -72,11 +72,17 @@ declare namespace StandardSchemaV1 {
  * the old name are ignored and the next read refolds from raw events.
  * See docs/concepts/04-state.mdx.
  */
-type Reducer<D extends EventDefs = EventDefs, S = unknown> = {
+type Reducer<D extends EventDefs = EventDefs, S = unknown, P extends PresenceDefs = Record<never, never>> = {
   /** Identity and cache key. Rename when the fold's logic changes. */
   readonly name: string;
   /** The contract's vocabulary — types every event in the fold. */
   readonly events: Readonly<D>;
+  /**
+   * The contract's presence vocabulary — carried because the reducer
+   * is the client's typed handle on the contract. The fold never sees
+   * presence.
+   */
+  readonly presence: Readonly<P>;
   readonly fold: (state: S, event: ContractEvent<D>) => S;
   readonly initialState: S;
   /**
@@ -88,13 +94,15 @@ type Reducer<D extends EventDefs = EventDefs, S = unknown> = {
   readonly stateSchema: StandardSchemaV1<unknown, S> | undefined;
 };
 /** The second step of `contract.reducer` — see the method's doc. */
-type ReducerBuilder<D extends EventDefs, S> = {
-  fold(fold: (state: S, event: ContractEvent<D>) => S): Reducer<D, S>;
+type ReducerBuilder<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = {
+  fold(fold: (state: S, event: ContractEvent<D>) => S): Reducer<D, S, P>;
 };
 //#endregion
 //#region src/contract.d.ts
 /** The event vocabulary shape: event name → payload schema. */
 type EventDefs = Record<string, StandardSchemaV1>;
+/** The presence vocabulary shape: field name → value schema. */
+type PresenceDefs = Record<string, StandardSchemaV1>;
 /** One event of a contract, narrowed to type `K`. */
 type ContractEvent<D extends EventDefs, K extends keyof D & string = keyof D & string> = { [T in keyof D & string]: {
   id: string;
@@ -111,6 +119,44 @@ type AppendInput<D extends EventDefs> = { [T in keyof D & string]: {
   id?: string;
 }; }[keyof D & string];
 type EventBatchFactory<D extends EventDefs> = <const E extends readonly AppendInput<D>[]>(...events: E) => E;
+/**
+ * One presence update: a participant's changed fields (`null` marks a
+ * cleared one), stamped with the sender's stream frontier (`seen`).
+ * This is what `stream({ presence: true })` interleaves with events.
+ */
+type PresencePatch<P extends PresenceDefs = PresenceDefs> = {
+  participant: string;
+  values: { [F in keyof P & string]?: StandardSchemaV1.InferOutput<P[F]> | null; };
+  seen: number;
+  at: Date;
+};
+/**
+ * The replicated ephemeral map: participant → field → latest value,
+ * last-writer-wins per field. Never stored in the log; how long a
+ * value stays painted is view logic, decided at render time against
+ * `at`.
+ */
+type PresenceMap<P extends PresenceDefs = PresenceDefs> = {
+  [participant: string]: { [F in keyof P & string]?: {
+    value: StandardSchemaV1.InferOutput<P[F]>;
+    seen: number;
+    at: Date;
+  }; };
+};
+/**
+ * The one item a presence stream yields before live patches: the
+ * current pruned map, per-field stamps exact. Discriminate
+ * structurally (`'snapshot' in item`).
+ */
+type PresenceSnapshot<P extends PresenceDefs = PresenceDefs> = {
+  snapshot: PresenceMap<P>;
+};
+/**
+ * Intersect into a surface type to add `Members` only when the
+ * contract declares presence fields — on presence-less contracts the
+ * members do not exist, a type error rather than a runtime throw.
+ */
+type WithPresence<P extends PresenceDefs, Members> = keyof P extends never ? unknown : Members;
 type ReducerOptions<Seed, S> = {
   /**
    * Identity and snapshot cache key. Rename it when the fold's logic
@@ -130,11 +176,13 @@ type ReducerOptions<Seed, S> = {
    */
   stateSchema?: StandardSchemaV1<Seed, S>;
 };
-type Contract<D extends EventDefs = EventDefs> = {
+type Contract<D extends EventDefs = EventDefs, P extends PresenceDefs = Record<never, never>> = {
   /** Identity — prefixes storage keys and queue messages. */
   readonly name: string;
   /** The vocabulary. */
   readonly events: Readonly<D>;
+  /** The presence vocabulary — empty unless declared. */
+  readonly presence: Readonly<P>;
   /** Preserve literal types for a handler-returned event batch. */
   readonly batch: EventBatchFactory<D>;
   /**
@@ -147,18 +195,24 @@ type Contract<D extends EventDefs = EventDefs> = {
    * context-sensitive argument against generics inferred in the same
    * call.)
    */
-  reducer<Seed, S = Seed>(options: ReducerOptions<Seed, S>): ReducerBuilder<D, S>;
+  reducer<Seed, S = Seed>(options: ReducerOptions<Seed, S>): ReducerBuilder<D, S, P>;
 };
 /**
  * Define a contract: a name plus the events it understands. Validators
  * must be synchronous — async ones are rejected here, at definition
  * time. The result is a plain, importable, isomorphic value.
  */
-declare function contract<D extends EventDefs>(options: {
+declare function contract<D extends EventDefs, P extends PresenceDefs = Record<never, never>>(options: {
   /** Identity — prefixes storage keys and queue messages. */
   name: string;
   /** The vocabulary: event name → payload schema (Standard Schema). */
   events: D;
-}): Contract<D>;
+  /**
+   * Optional second vocabulary: presence field → value schema.
+   * Per-participant ephemeral state, replicated last-writer-wins and
+   * never stored in the log — reducers cannot see it.
+   */
+  presence?: P;
+}): Contract<D, P>;
 //#endregion
-export { EventDefs as a, Reducer as c, EventBatchFactory as i, ReducerBuilder as l, Contract as n, ReducerOptions as o, ContractEvent as r, contract as s, AppendInput as t, StandardSchemaV1 as u };
+export { EventDefs as a, PresencePatch as c, WithPresence as d, contract as f, StandardSchemaV1 as h, EventBatchFactory as i, PresenceSnapshot as l, ReducerBuilder as m, Contract as n, PresenceDefs as o, Reducer as p, ContractEvent as r, PresenceMap as s, AppendInput as t, ReducerOptions as u };