experimental-a2 0.3.0 → 0.5.0

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 { i as STREAM_TIMINGS } from "./internal-gCd5qMry.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-BKlyLiOU.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,14 +49,23 @@ 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);
 		}
 	};
 }
 //#endregion
 export { contract as t };
+
+//# sourceMappingURL=contract-48bUMgcL.js.map

package/dist/contract-48bUMgcL.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-48bUMgcL.js","names":[],"sources":["../src/reducer.ts","../src/contract.ts"],"sourcesContent":["import type { ContractEvent, EventDefs, PresenceDefs } from './contract.ts'\nimport type { StandardSchemaV1 } from './standard-schema.ts'\nimport { validateSync } from './validate.ts'\n\n/**\n * A pure fold over a session's events — `(state, event) => state` —\n * derived from a contract via `contract.reducer(options).fold(fn)`.\n *\n * The name is the reducer's identity. Cached folds (server snapshots,\n * the browser cache) are keyed by it, which makes it the invalidation\n * knob too: changed the fold's logic? Change the name. Snapshots under\n * the old name are ignored and the next read refolds from raw events.\n * See docs/concepts/04-state.mdx.\n */\nexport type Reducer<\n  D extends EventDefs = EventDefs,\n  S = unknown,\n  P extends PresenceDefs = Record<never, never>,\n> = {\n  /** Identity and cache key. Rename when the fold's logic changes. */\n  readonly name: string\n  /** The contract's vocabulary — types every event in the fold. */\n  readonly events: Readonly<D>\n  /**\n   * The contract's presence vocabulary — carried because the reducer\n   * is the client's typed handle on the contract. The fold never sees\n   * presence.\n   */\n  readonly presence: Readonly<P>\n  readonly fold: (state: S, event: ContractEvent<D>) => S\n  readonly initialState: S\n  /**\n   * When present: `initialState` was validated against it at\n   * definition, and any cached fold a2 rehydrates (server snapshots,\n   * the browser cache) is checked against it — failing snapshots are\n   * discarded and refolded, catching shape drift a stale name can't.\n   */\n  readonly stateSchema: StandardSchemaV1<unknown, S> | undefined\n}\n\n/** The second step of `contract.reducer` — see the method's doc. */\nexport type ReducerBuilder<\n  D extends EventDefs,\n  S,\n  P extends PresenceDefs = Record<never, never>,\n> = {\n  fold(fold: (state: S, event: ContractEvent<D>) => S): Reducer<D, S, P>\n}\n\n/** Internal — reducers are created through `contract.reducer(...).fold(...)`. */\nexport function makeReducerBuilder<\n  D extends EventDefs,\n  P extends PresenceDefs,\n  Seed,\n  S,\n>(\n  events: Readonly<D>,\n  presence: Readonly<P>,\n  options: {\n    name: string\n    initialState: Seed\n    stateSchema?: StandardSchemaV1<Seed, S>\n  },\n): ReducerBuilder<D, S, P> {\n  const { name } = options\n  if (typeof name !== 'string' || name.length === 0) {\n    throw new TypeError(\n      'reducer name must be a non-empty string — it identifies the reducer and keys cached snapshots',\n    )\n  }\n\n  // Without a schema, S = Seed (the type parameter default), so the\n  // seed is the state. With one, the seed is the schema's input and the\n  // validated output (defaults applied) becomes the fold's actual seed.\n  let initialState = options.initialState as unknown as S\n  if (options.stateSchema) {\n    const result = validateSync(\n      options.stateSchema,\n      options.initialState,\n      'the stateSchema',\n    )\n    if (result.issues) {\n      throw new TypeError(\n        `reducer initialState does not match its stateSchema: ${result.issues\n          .map((issue) => issue.message)\n          .join('; ')}`,\n      )\n    }\n    initialState = result.value as S\n  }\n\n  return {\n    fold(fold) {\n      if (typeof fold !== 'function') {\n        throw new TypeError('reducer fold must be a function')\n      }\n      return {\n        name,\n        events,\n        presence,\n        fold,\n        initialState,\n        stateSchema: options.stateSchema as\n          StandardSchemaV1<unknown, S> | undefined,\n      }\n    },\n  }\n}\n","/**\n * The contract — a2's primary noun. A named event vocabulary, shared by\n * everything: the server implements it (experimental-a2/server's `createServer`),\n * reducers derive from it (`contract.reducer`), the browser types its\n * pushes off it. Isomorphic by construction: this module imports\n * nothing but schema plumbing.\n *\n * The contract says what can be *said*; the server says how it's\n * *reacted to*; a reducer says how it's *seen*.\n */\n\nimport { makeReducerBuilder, type ReducerBuilder } from './reducer.ts'\nimport type { StandardSchemaV1 } from './standard-schema.ts'\nimport { assertSyncSchema } from './validate.ts'\n\n/** The event vocabulary shape: event name → payload schema. */\nexport type EventDefs = Record<string, StandardSchemaV1>\n\n/** The presence vocabulary shape: field name → value schema. */\nexport type PresenceDefs = Record<string, StandardSchemaV1>\n\n/** One event of a contract, narrowed to type `K`. */\nexport type ContractEvent<\n  D extends EventDefs,\n  K extends keyof D & string = keyof D & string,\n> = {\n  [T in keyof D & string]: {\n    id: string\n    type: T\n    payload: StandardSchemaV1.InferOutput<D[T]>\n    index: number\n    sessionId: string\n    createdAt: Date\n  }\n}[K]\n\n/** Input to `append`/`push`, typed against the contract's schemas. */\nexport type AppendInput<D extends EventDefs> = {\n  [T in keyof D & string]: {\n    type: T\n    payload: StandardSchemaV1.InferInput<D[T]>\n    id?: string\n  }\n}[keyof D & string]\n\nexport type EventBatchFactory<D extends EventDefs> = <\n  const E extends readonly AppendInput<D>[],\n>(\n  ...events: E\n) => E\n\n/**\n * One presence update: a participant's changed fields (`null` marks a\n * cleared one), stamped with the sender's stream frontier (`seen`).\n * This is what `stream({ presence: true })` interleaves with events.\n */\nexport type PresencePatch<P extends PresenceDefs = PresenceDefs> = {\n  participant: string\n  values: {\n    [F in keyof P & string]?: StandardSchemaV1.InferOutput<P[F]> | null\n  }\n  seen: number\n  at: Date\n}\n\n/**\n * The replicated ephemeral map: participant → field → latest value,\n * last-writer-wins per field. Never stored in the log; how long a\n * value stays painted is view logic, decided at render time against\n * `at`.\n */\nexport type PresenceMap<P extends PresenceDefs = PresenceDefs> = {\n  [participant: string]: {\n    [F in keyof P & string]?: {\n      value: StandardSchemaV1.InferOutput<P[F]>\n      seen: number\n      at: Date\n    }\n  }\n}\n\n/**\n * The one item a presence stream yields before live patches: the\n * current pruned map, per-field stamps exact. Discriminate\n * structurally (`'snapshot' in item`).\n */\nexport type PresenceSnapshot<P extends PresenceDefs = PresenceDefs> = {\n  snapshot: PresenceMap<P>\n}\n\n/**\n * Intersect into a surface type to add `Members` only when the\n * contract declares presence fields — on presence-less contracts the\n * members do not exist, a type error rather than a runtime throw.\n */\nexport type WithPresence<\n  P extends PresenceDefs,\n  Members,\n> = keyof P extends never ? unknown : Members\n\nexport type ReducerOptions<Seed, S> = {\n  /**\n   * Identity and snapshot cache key. Rename it when the fold's logic\n   * changes — snapshots under the old name are ignored and refolded.\n   */\n  name: string\n  /**\n   * The seed the fold starts from. With a `stateSchema`, it's typed as\n   * the schema's *input*: validated at definition, and the validated\n   * output (defaults applied) is what the fold actually starts from.\n   */\n  initialState: Seed\n  /**\n   * Optional: declares the state's shape (the fold's state type becomes\n   * the schema's output) and guards cached folds — server snapshots and\n   * the browser cache reject mismatching shapes and refold.\n   */\n  stateSchema?: StandardSchemaV1<Seed, S>\n}\n\nexport type Contract<\n  D extends EventDefs = EventDefs,\n  P extends PresenceDefs = Record<never, never>,\n> = {\n  /** Identity — prefixes storage keys and queue messages. */\n  readonly name: string\n  /** The vocabulary. */\n  readonly events: Readonly<D>\n  /** The presence vocabulary — empty unless declared. */\n  readonly presence: Readonly<P>\n  /** Preserve literal types for a handler-returned event batch. */\n  readonly batch: EventBatchFactory<D>\n  /**\n   * Derive a view from this contract. The reducer's `name` is its\n   * identity and snapshot cache key: rename it when the fold's logic\n   * changes. Two steps by design: this call fixes the state and event\n   * types, so `.fold()` receives fully concrete types — literal unions\n   * in your state survive, with zero annotations. (A single call can't\n   * do this: TypeScript never contextually types the returns of a\n   * context-sensitive argument against generics inferred in the same\n   * call.)\n   */\n  reducer<Seed, S = Seed>(\n    options: ReducerOptions<Seed, S>,\n  ): ReducerBuilder<D, S, P>\n}\n\n/**\n * Define a contract: a name plus the events it understands. Validators\n * must be synchronous — async ones are rejected here, at definition\n * time. The result is a plain, importable, isomorphic value.\n */\nexport function contract<\n  D extends EventDefs,\n  P extends PresenceDefs = Record<never, never>,\n>(options: {\n  /** Identity — prefixes storage keys and queue messages. */\n  name: string\n  /** The vocabulary: event name → payload schema (Standard Schema). */\n  events: D\n  /**\n   * Optional second vocabulary: presence field → value schema.\n   * Per-participant ephemeral state, replicated last-writer-wins and\n   * never stored in the log — reducers cannot see it.\n   */\n  presence?: P\n}): Contract<D, P> {\n  const { name } = options\n  if (typeof name !== 'string' || name.length === 0) {\n    throw new TypeError('contract name must be a non-empty string')\n  }\n  if (name.includes('\\u001f')) {\n    throw new TypeError('contract name contains a reserved control character')\n  }\n  const defs = options.events\n  for (const [type, schema] of Object.entries(defs)) {\n    if (typeof schema?.['~standard']?.validate !== 'function') {\n      throw new TypeError(\n        `contract '${name}': the value for '${type}' is not a Standard Schema (expected an object with '~standard')`,\n      )\n    }\n    assertSyncSchema(schema, `event '${type}'`)\n  }\n  const events = Object.freeze({ ...defs })\n\n  const presenceDefs = options.presence ?? ({} as P)\n  for (const [field, schema] of Object.entries(presenceDefs)) {\n    if (typeof schema?.['~standard']?.validate !== 'function') {\n      throw new TypeError(\n        `contract '${name}': the value for presence field '${field}' is not a Standard Schema (expected an object with '~standard')`,\n      )\n    }\n    assertSyncSchema(schema, `presence field '${field}'`)\n  }\n  const presence = Object.freeze({ ...presenceDefs })\n\n  return {\n    name,\n    events,\n    presence,\n    batch: (...items) => items,\n    reducer(reducerOptions) {\n      return makeReducerBuilder(events, presence, reducerOptions)\n    },\n  }\n}\n"],"mappings":";;;AAkDA,SAAgB,mBAMd,QACA,UACA,SAKyB;CACzB,MAAM,EAAE,SAAS;CACjB,IAAI,OAAO,SAAS,YAAY,KAAK,WAAW,GAC9C,MAAM,IAAI,UACR,+FACF;CAMF,IAAI,eAAe,QAAQ;CAC3B,IAAI,QAAQ,aAAa;EACvB,MAAM,SAAS,aACb,QAAQ,aACR,QAAQ,cACR,iBACF;EACA,IAAI,OAAO,QACT,MAAM,IAAI,UACR,wDAAwD,OAAO,OAC5D,KAAK,UAAU,MAAM,OAAO,CAAC,CAC7B,KAAK,IAAI,GACd;EAEF,eAAe,OAAO;CACxB;CAEA,OAAO,EACL,KAAK,MAAM;EACT,IAAI,OAAO,SAAS,YAClB,MAAM,IAAI,UAAU,iCAAiC;EAEvD,OAAO;GACL;GACA;GACA;GACA;GACA;GACA,aAAa,QAAQ;EAEvB;CACF,EACF;AACF;;;;;;;;;;;;;;;;;;AC6CA,SAAgB,SAGd,SAWiB;CACjB,MAAM,EAAE,SAAS;CACjB,IAAI,OAAO,SAAS,YAAY,KAAK,WAAW,GAC9C,MAAM,IAAI,UAAU,0CAA0C;CAEhE,IAAI,KAAK,SAAS,GAAQ,GACxB,MAAM,IAAI,UAAU,qDAAqD;CAE3E,MAAM,OAAO,QAAQ;CACrB,KAAK,MAAM,CAAC,MAAM,WAAW,OAAO,QAAQ,IAAI,GAAG;EACjD,IAAI,OAAO,SAAS,YAAY,EAAE,aAAa,YAC7C,MAAM,IAAI,UACR,aAAa,KAAK,oBAAoB,KAAK,iEAC7C;EAEF,iBAAiB,QAAQ,UAAU,KAAK,EAAE;CAC5C;CACA,MAAM,SAAS,OAAO,OAAO,EAAE,GAAG,KAAK,CAAC;CAExC,MAAM,eAAe,QAAQ,YAAa,CAAC;CAC3C,KAAK,MAAM,CAAC,OAAO,WAAW,OAAO,QAAQ,YAAY,GAAG;EAC1D,IAAI,OAAO,SAAS,YAAY,EAAE,aAAa,YAC7C,MAAM,IAAI,UACR,aAAa,KAAK,mCAAmC,MAAM,iEAC7D;EAEF,iBAAiB,QAAQ,mBAAmB,MAAM,EAAE;CACtD;CACA,MAAM,WAAW,OAAO,OAAO,EAAE,GAAG,aAAa,CAAC;CAElD,OAAO;EACL;EACA;EACA;EACA,QAAQ,GAAG,UAAU;EACrB,QAAQ,gBAAgB;GACtB,OAAO,mBAAmB,QAAQ,UAAU,cAAc;EAC5D;CACF;AACF"}

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,25 @@ 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 };
+//# sourceMappingURL=contract-jIfaR085.d.ts.map

package/dist/contract-jIfaR085.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-jIfaR085.d.ts","names":[],"sources":["../src/standard-schema.ts","../src/reducer.ts","../src/contract.ts"],"mappings":";;;;;;;;UAQiB,iBAAiB,iBAAiB,SAAS;;WAEjD,aAAa,iBAAiB,MAAM,OAAO;;kBAG7B;;mBAEN,MAAM,iBAAiB,SAAS;;aAEtC;;aAEA;;aAEA,WACP,mBACG,OAAO,UAAU,QAAQ,OAAO;;aAE5B,QAAQ,MAAM,OAAO;;;cAIpB,OAAO,UAAU,cAAc,UAAU;;mBAGpC,cAAc;;aAEpB,OAAO;;aAEP;;;mBAIM;;aAEN,QAAQ,cAAc;;;mBAIhB;;aAEN;;aAEA,OAAO,cAAc,cAAc;;;mBAI7B;;aAEN,KAAK;;;mBAIC,MAAM,iBAAiB,SAAS;;aAEtC,OAAO;;aAEP,QAAQ;;;cAIP,WAAW,eAAe,oBAAoB,YACxD;;cAIU,YAAY,eAAe,oBAAoB,YACzD;;;;;;;;;;;;;;KC5DQ,QACV,UAAU,YAAY,WACtB,aACA,UAAU,eAAe;;WAGhB;;WAEA,QAAQ,SAAS;;;;;;WAMjB,UAAU,SAAS;WACnB,OAAO,OAAO,GAAG,OAAO,cAAc,OAAO;WAC7C,cAAc;;;;;;;WAOd,aAAa,0BAA0B;;;KAItC,eACV,UAAU,WACV,GACA,UAAU,eAAe;EAEzB,KAAK,OAAO,OAAO,GAAG,OAAO,cAAc,OAAO,IAAI,QAAQ,GAAG,GAAG;;;;;KC9B1D,YAAY,eAAe;;KAG3B,eAAe,eAAe;;KAG9B,cACV,UAAU,WACV,gBAAgB,mBAAmB,iBAElC,WAAW;EACV;EACA,MAAM;EACN,SAAS,iBAAiB,YAAY,EAAE;EACxC;EACA;EACA,WAAW;KAEb;;KAGU,YAAY,UAAU,gBAC/B,WAAW;EACV,MAAM;EACN,SAAS,iBAAiB,WAAW,EAAE;EACvC;WAEI;KAEI,kBAAkB,UAAU,oBAChC,mBAAmB,YAAY,SAElC,QAAQ,MACR;;;;;;KAOO,cAAc,UAAU,eAAe;EACjD;EACA,WACG,WAAW,cAAc,iBAAiB,YAAY,EAAE;EAE3D;EACA,IAAI;;;;;;;;KASM,YAAY,UAAU,eAAe;GAE5C,yBAAA,WAAW;IACV,OAAO,iBAAiB,YAAY,EAAE;IACtC;IACA,IAAI;;;;;;;;KAUE,iBAAiB,UAAU,eAAe;EACpD,UAAU,YAAY;;;;;;;KAQZ,aACV,UAAU,cACV,iBACQ,4BAA4B;KAE1B,eAAe,MAAM;;;;;EAK/B;;;;;;EAMA,cAAc;;;;;;EAMd,cAAc,iBAAiB,MAAM;;KAG3B,SACV,UAAU,YAAY,WACtB,UAAU,eAAe;;WAGhB;;WAEA,QAAQ,SAAS;;WAEjB,UAAU,SAAS;;WAEnB,OAAO,kBAAkB;;;;;;;;;;;EAWlC,QAAQ,MAAM,IAAI,MAChB,SAAS,eAAe,MAAM,KAC7B,eAAe,GAAG,GAAG;;;;;;;iBAQV,SACd,UAAU,WACV,UAAU,eAAe,sBACzB;;EAEA;;EAEA,QAAQ;;;;;;EAMR,WAAW;IACT,SAAS,GAAG"}