statewire 0.0.0-0 → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentbaseAI Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,85 @@
 # statewire
 
-Placeholder for the Statewire protocol client (assistant-ui). Real release coming soon.
+React/TypeScript client for the **Statewire** protocol: a server owns a JSON state object and streams it to clients over SSE (`GET /stream`, snapshot first); clients change it by POSTing method calls (`POST /commands`, body `{"method", "params"}`). The client keeps your UI on the canonical state with optimistic updates rebased on top, survives disconnects, evictions, and reloads of the server, and tells you exactly what happened to every command you sent.
+
+```tsx
+import { useStatewire, StatewireSSE } from "statewire";
+
+type Commands = {
+  increment(): void;
+};
+
+const { state, transport, commands } = useStatewire<State, Commands, Event>({
+  transport: StatewireSSE({ url: "/api/threads/demo" }),
+  optimistic: (draft, command) => {
+    if (command.method === "increment") draft.count += 1;
+  },
+});
+
+const onClick = async () => {
+  await commands.increment(); // resolves when the server has provably applied it
+};
+```
+
+## What you get
+
+- **`state`** — `undefined` until the first snapshot, then canonical server state with your pending commands' optimistic effects rebased on top. When the server's ack arrives, the optimistic overlay drops in the same tick: no flicker.
+- **`transport`** — connection health as a tagged union: `transport.status` is `"connecting" | "live" | "reconnecting" | "gone"`, and each variant carries exactly the data that exists in that situation: `reconnecting` has `cause` (`"dropped"`, `"ended"`, or `"error"`), `attempt`, `nextRetryAt`, `lastError?`, `message?`; `gone` carries the server's `message?`. `transport.reconnect()` re-attaches manually from `gone`, or "retry now" during backoff.
+- **`commands`** — a typed proxy over the `Commands` method map: `commands.increment()` submits `{ method: "increment", params: [] }` and resolves with the handler's result only once the stream ack proves the effect is in canonical state. Rejects with `StatewireSendError`, whose `failure.stage` carries the verdict; the boundary is definitiveness:
+  - `"aborted"` — definitely not applied (never POSTed, or every attempt accounted for); safe to resend
+  - `"lost"` — a POST left the machine and never got a definitive answer; whether the server applied it is unknown — check the snapshot for your payload ids
+  - `"rejected"` — the server said no; not applied (`message`, optional `payload` from the backend's `Reject`)
+  - `"crashed"` — acked, but the processing died before producing a result
+  - `"unavailable"` — acked, but the result can no longer be delivered
+
+  Every failure also carries `reason` — the trigger: `"response"` = the server's response settled it, `"stream-gone"` = terminal `finish(gone)`, `"session-lost"` = the server forgot the client id (eviction), `"superseded"` = another attach took the writer lease, `"unmount"` / `"cascade"` are client-side. `Statewire.SendFailure` is the taxonomy's single exported type; the `stage` and `reason` unions are reachable as `SendFailure["stage"]` / `SendFailure["reason"]`.
+
+Reconnects are not errors: transport drops and server evictions self-heal with exponential backoff while `state` stays renderable. Commands carry a monotonic seq, so retries are deduplicated server-side and a reconnect splices already-applied commands instead of re-running them.
+
+Sessions are single-writer: every attach takes a writer lease, and any older stream for the same client id ends with `finish(superseded)` — that client goes `gone` (no reconnect) and its pending sends fail with reason `"superseded"`.
+
+## Three ways to mount
+
+One implementation, three entry points:
+
+```ts
+useStatewire(options)               // React hook
+StatewireResource(options)          // @assistant-ui/tap resource, for composition
+new Statewire(options)              // framework-free: .state/.transport/.commands,
+                                    // .subscribe(cb), .dispose()
+```
+
+`Statewire#subscribe` follows the external-store contract (`useSyncExternalStore`-compatible). `dispose()` settles pending commands like an unmount.
+
+Every public type merges onto the class as a namespace — `Statewire.Transport`, `Statewire.TransportStatus`, `Statewire.Options`, `Statewire.SendFailure`, … — so one import covers the whole surface.
+
+There is no session key: a transport `url` change reattaches in place and the attach snapshot arbitrates identity (an unknown client evicts — pending settles, the client id rotates). For a forced fresh session, key the resource — `withKey(threadId, StatewireResource(options))`; pending commands settle with reason `"unmount"`.
+
+## Transport
+
+```ts
+StatewireSSE({
+  url,        // endpoint root — the transport appends /stream and /commands
+  headers,    // HeadersInit or (async) () => HeadersInit, re-evaluated per request
+  fetch,      // custom fetch — the escape hatch for everything else
+})
+```
+
+`StatewireWS({ url, protocols, query, webSocket })` is the full-duplex sibling over `/ws`. Transports implement the `Statewire.TransportProps` seam; `createMockTransport` from `statewire/testing` is a complete in-memory driver for tests.
+
+## Backend
+
+Any server speaking the Statewire convention works. The Python implementation lives in this repo (`python/statewire`):
+
+```python
+from statewire import Statewire, Reject, command
+
+class Counter(Statewire):
+    @command
+    async def increment(self):
+        if self.state["count"] >= 10:
+            raise Reject("counter is full", payload={"max": 10})
+        self.state["count"] += 1
+```
+
+See `examples/vite-statewire-example` (frontend) and `python/statewire/examples/demo_app.py` (backend) for a complete runnable pair, and the repo's protocol spec for the wire format.

package/dist/client/changes.d.ts

@@ -0,0 +1,7 @@
+import { StatewirePath } from "../wire/ops.js";
+import { StatewireChanges } from "../types.js";
+//#region src/client/changes.d.ts
+declare const createChanges: (prev: unknown, next: unknown, changedPaths: readonly StatewirePath[]) => StatewireChanges;
+//#endregion
+export { createChanges };
+//# sourceMappingURL=changes.d.ts.map

package/dist/client/changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.d.ts","names":[],"sources":["../../src/client/changes.ts"],"mappings":";;;cAqBa,gBACX,eACA,eACA,uBAAuB,oBACtB"}

package/dist/client/changes.js

@@ -0,0 +1,32 @@
+//#region src/client/changes.ts
+const lookupValue = (state, path) => {
+	let node = state;
+	for (const key of path) {
+		if (typeof node !== "object" || node === null) return void 0;
+		node = Object.hasOwn(node, key) ? node[key] : void 0;
+	}
+	return node;
+};
+const keysAt = (node) => typeof node === "object" && node !== null ? Object.keys(node) : [];
+const isPrefix = (prefix, path) => prefix.length <= path.length && prefix.every((key, i) => String(key) === String(path[i]));
+const createChanges = (prev, next, changedPaths) => ({
+	isChangedAt: (path) => changedPaths.some((p) => isPrefix(p, path) || isPrefix(path, p)),
+	getChangedKeys: (path) => {
+		if (changedPaths.some((p) => p.length <= path.length && isPrefix(p, path))) {
+			const keys = keysAt(lookupValue(next, path));
+			for (const key of keysAt(lookupValue(prev, path))) if (!keys.includes(key)) keys.push(key);
+			return keys;
+		}
+		const keys = [];
+		for (const p of changedPaths) {
+			if (p.length <= path.length || !isPrefix(path, p)) continue;
+			const key = String(p[path.length]);
+			if (!keys.includes(key)) keys.push(key);
+		}
+		return keys;
+	}
+});
+//#endregion
+export { createChanges };
+
+//# sourceMappingURL=changes.js.map

package/dist/client/changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.js","names":["StatewirePath","StatewireChanges","lookupValue","state","path","node","key","undefined","Object","hasOwn","Record","keysAt","keys","isPrefix","prefix","length","every","i","String","createChanges","prev","next","changedPaths","isChangedAt","some","p","getChangedKeys","wiped","includes","push"],"sources":["../../src/client/changes.ts"],"sourcesContent":["import type { StatewirePath } from \"../wire/ops\";\nimport type { StatewireChanges } from \"../types\";\n\nconst lookupValue = (state: unknown, path: StatewirePath): unknown => {\n  let node = state;\n  for (const key of path) {\n    if (typeof node !== \"object\" || node === null) return undefined;\n    node = Object.hasOwn(node, key)\n      ? (node as Record<string, unknown>)[key]\n      : undefined;\n  }\n  return node;\n};\n\nconst keysAt = (node: unknown): string[] =>\n  typeof node === \"object\" && node !== null ? Object.keys(node) : [];\n\nconst isPrefix = (prefix: StatewirePath, path: StatewirePath): boolean =>\n  prefix.length <= path.length &&\n  prefix.every((key, i) => String(key) === String(path[i]));\n\nexport const createChanges = (\n  prev: unknown,\n  next: unknown,\n  changedPaths: readonly StatewirePath[],\n): StatewireChanges => ({\n  isChangedAt: (path) =>\n    changedPaths.some((p) => isPrefix(p, path) || isPrefix(path, p)),\n  getChangedKeys: (path) => {\n    const wiped = changedPaths.some(\n      (p) => p.length <= path.length && isPrefix(p, path),\n    );\n    if (wiped) {\n      const keys = keysAt(lookupValue(next, path));\n      for (const key of keysAt(lookupValue(prev, path))) {\n        if (!keys.includes(key)) keys.push(key);\n      }\n      return keys;\n    }\n    const keys: string[] = [];\n    for (const p of changedPaths) {\n      if (p.length <= path.length || !isPrefix(path, p)) continue;\n      const key = String(p[path.length]);\n      if (!keys.includes(key)) keys.push(key);\n    }\n    return keys;\n  },\n});\n"],"mappings":";AAGA,MAAME,eAAeC,OAAgBC,SAAiC;CACpE,IAAIC,OAAOF;CACX,KAAK,MAAMG,OAAOF,MAAM;EACtB,IAAI,OAAOC,SAAS,YAAYA,SAAS,MAAM,OAAOE,KAAAA;EACtDF,OAAOG,OAAOC,OAAOJ,MAAMC,GAAG,IACzBD,KAAiCC,OAClCC,KAAAA;CACN;CACA,OAAOF;AACT;AAEA,MAAMM,UAAUN,SACd,OAAOA,SAAS,YAAYA,SAAS,OAAOG,OAAOI,KAAKP,IAAI,IAAI,CAAA;AAElE,MAAMQ,YAAYC,QAAuBV,SACvCU,OAAOC,UAAUX,KAAKW,UACtBD,OAAOE,OAAOV,KAAKW,MAAMC,OAAOZ,GAAG,MAAMY,OAAOd,KAAKa,EAAE,CAAC;AAE1D,MAAaE,iBACXC,MACAC,MACAC,kBACsB;CACtBC,cAAcnB,SACZkB,aAAaE,MAAMC,MAAMZ,SAASY,GAAGrB,IAAI,KAAKS,SAAST,MAAMqB,CAAC,CAAC;CACjEC,iBAAiBtB,SAAS;EAIxB,IAHckB,aAAaE,MACxBC,MAAMA,EAAEV,UAAUX,KAAKW,UAAUF,SAASY,GAAGrB,IAAI,CAEhDuB,GAAO;GACT,MAAMf,OAAOD,OAAOT,YAAYmB,MAAMjB,IAAI,CAAC;GAC3C,KAAK,MAAME,OAAOK,OAAOT,YAAYkB,MAAMhB,IAAI,CAAC,GAC9C,IAAI,CAACQ,KAAKgB,SAAStB,GAAG,GAAGM,KAAKiB,KAAKvB,GAAG;GAExC,OAAOM;EACT;EACA,MAAMA,OAAiB,CAAA;EACvB,KAAK,MAAMa,KAAKH,cAAc;GAC5B,IAAIG,EAAEV,UAAUX,KAAKW,UAAU,CAACF,SAAST,MAAMqB,CAAC,GAAG;GACnD,MAAMnB,MAAMY,OAAOO,EAAErB,KAAKW,OAAO;GACjC,IAAI,CAACH,KAAKgB,SAAStB,GAAG,GAAGM,KAAKiB,KAAKvB,GAAG;EACxC;EACA,OAAOM;CACT;AACF"}

package/dist/client/connection.d.ts

@@ -0,0 +1,84 @@
+import { ConnectionState, RemoteLink, StatewireConnection, StatewireTransportProps } from "../transports/sse.js";
+//#region src/client/connection.d.ts
+type Episode = {
+  cause: "dropped" | "ended" | "error";
+  message?: string;
+};
+type StatewireFinish = {
+  reason: "ended" | "error" | "gone" | "superseded" | (string & {});
+  message?: string;
+  payload?: unknown;
+  meta?: unknown;
+};
+type StatewireResponse = {
+  seq: number;
+  type: "accepted" | "rejected" | "pending" | "crashed" | "result-unavailable";
+  code?: string;
+  message?: string;
+  payload?: unknown;
+  meta?: unknown;
+};
+type StatewireSyn = {
+  lastSeq: number;
+  lease?: string;
+};
+type StatewireEnvelope = {
+  ops?: unknown[];
+  res?: StatewireResponse[];
+  ack?: number;
+  syn?: StatewireSyn;
+  fin?: StatewireFinish;
+};
+declare const createGate: () => {
+  take: () => boolean;
+  wait: (timeoutMs?: number) => Promise<void>;
+  open: () => void;
+};
+type Gate = ReturnType<typeof createGate>;
+type ConnBase = {
+  connection: StatewireConnection;
+  hasSnapshot: boolean;
+  lease: string | null;
+  attempt: number;
+  episode: Episode | null;
+  gate: Gate;
+  abort: AbortController | null;
+  lifetime: AbortController | null;
+  latest: {
+    readonly current: {
+      options: {
+        onChange?: (connection: StatewireConnection) => void;
+      };
+      ctx: StatewireTransportProps;
+    };
+  };
+  notify: (connection: StatewireConnection) => void;
+  reconnect: () => void;
+  attemptOnce: (abort: AbortController) => Promise<"stop" | "reattach" | "ended">;
+};
+declare const setStatus: (c: ConnBase, next: ConnectionState) => void;
+declare const deliverEnvelope: (c: ConnBase, env: Pick<StatewireEnvelope, "ops" | "res" | "ack" | "syn">, attached: boolean) => void;
+declare const isTransientFinish: (reason: StatewireFinish["reason"]) => reason is "ended" | "error";
+declare const settleEnvelope: (c: ConnBase, env: StatewireEnvelope) => "stop" | "reattach" | null;
+declare const handleEnvelope: (c: ConnBase, env: StatewireEnvelope, attached: boolean) => "stop" | "reattach" | null;
+declare const scheduleRetry: (c: ConnBase, failure: string | undefined, immediate: boolean, retryAfterMs?: number) => number;
+declare const reconnectConn: (c: ConnBase) => void;
+declare const useStatewireConn: <TOptions extends {
+  url: string;
+  onChange?: (connection: StatewireConnection) => void;
+}>(options: TOptions, ctx: StatewireTransportProps, create: (latest: {
+  readonly current: {
+    options: TOptions;
+    ctx: StatewireTransportProps;
+  };
+}, notify: (connection: StatewireConnection) => void) => ConnBase & {
+  send: RemoteLink["send"];
+}) => RemoteLink;
+declare const classify: (timeout: AbortSignal) => Error;
+declare const parseRetryAfter: (header: string | null) => number | undefined;
+declare const overloadedError: (retryAfterMs?: number) => Error & {
+  retryAfterMs: number | undefined;
+};
+//#endregion
+export { ConnBase, Episode, Gate, StatewireEnvelope, StatewireFinish, StatewireResponse, StatewireSyn, classify, createGate, deliverEnvelope, handleEnvelope, isTransientFinish, overloadedError, parseRetryAfter, reconnectConn, scheduleRetry, setStatus, settleEnvelope, useStatewireConn };
+//# sourceMappingURL=connection.d.ts.map

package/dist/client/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","names":[],"sources":["../../src/client/connection.ts"],"mappings":";;KAWY;EACV;EACA;;KAGU;EACV;EACA;EACA;EACA;;KAGU;EACV;EACA;EACA;EACA;EACA;EACA;;KAGU;EACV;EACA;;KAGU;EACV;EACA,MAAM;EACN;EACA,MAAM;EACN,MAAM;;cAGK;;EASU,OAAA,uBAAM;;;KA2BjB,OAAO,kBAAkB;KAEzB;EACV,YAAY;EACZ;EACA;EACA;EACA,SAAS;EACT,MAAM;EACN,OAAO;EACP,UAAU;EACV;aACW;MACP;QAAW,YAAY,YAAY;;MACnC,KAAK;;;EAGT,SAAS,YAAY;EACrB;EACA,cACE,OAAO,oBACJ;;cAGM,YAAa,GAAG,UAAU,MAAM;cAOhC,kBACX,GAAG,UACH,KAAK,KAAK,mDACV;cAsBW,oBACX,QAAQ,8BACP;cAEU,iBACX,GAAG,UACH,KAAK;cA+BM,iBACX,GAAG,UACH,KAAK,mBACL;cAMW,gBACX,GAAG,UACH,6BACA,oBACA;cAiBW,gBAAiB,GAAG;cAwEpB,mBACX;EACE;EACA,YAAY,YAAY;GAG1B,SAAS,UACT,KAAK,yBACL,SACE;WACW;IACP,SAAS;IACT,KAAK;;GAGT,SAAS,YAAY,iCAClB;EAAa,MAAM;MACvB;cAqBU,WAAY,SAAS,gBAAW;cAGhC,kBAAmB;cAQnB,kBAAmB,0BAAqB"}

package/dist/client/connection.js

@@ -0,0 +1,204 @@
+import { reviveOps, reviveResponse, reviveValue } from "../wire/meta.js";
+import { backoff } from "./timing.js";
+import { useEffect, useRef, useState } from "@assistant-ui/tap/react-shim";
+import { flushTapSync } from "@assistant-ui/tap";
+//#region src/client/connection.ts
+const createGate = () => {
+	let latched = false;
+	let wake;
+	return {
+		take: () => {
+			const was = latched;
+			latched = false;
+			return was;
+		},
+		wait: (timeoutMs) => {
+			if (latched) {
+				latched = false;
+				return Promise.resolve();
+			}
+			return new Promise((resolve) => {
+				const timer = timeoutMs === void 0 ? void 0 : setTimeout(() => {
+					wake = void 0;
+					resolve();
+				}, timeoutMs);
+				wake = () => {
+					clearTimeout(timer);
+					wake = void 0;
+					resolve();
+				};
+			});
+		},
+		open: () => {
+			if (wake) wake();
+			else latched = true;
+		}
+	};
+};
+const setStatus = (c, next) => {
+	const changed = next.status !== c.connection.status;
+	c.connection = {
+		...next,
+		reconnect: c.reconnect
+	};
+	c.notify(c.connection);
+	if (changed) c.latest.current.options.onChange?.(c.connection);
+};
+const deliverEnvelope = (c, env, attached) => {
+	if (env.syn?.lease !== void 0) c.lease = env.syn.lease;
+	const ctx = c.latest.current.ctx;
+	const ops = env.ops === void 0 ? [] : reviveOps(env.ops);
+	const res = env.res?.map(reviveResponse);
+	if (!attached) ctx.onSnapshot({
+		ops,
+		lastSeq: env.syn?.lastSeq ?? -1
+	});
+	else if (env.ops !== void 0 || env.res !== void 0 || env.ack !== void 0) ctx.onOps({
+		ops,
+		...res !== void 0 && { res },
+		...env.ack !== void 0 && { ack: env.ack }
+	});
+	c.hasSnapshot = true;
+};
+const isTransientFinish = (reason) => reason === "ended" || reason === "error";
+const settleEnvelope = (c, env) => {
+	let finish = env.fin;
+	if (finish) {
+		if (finish.meta !== void 0) {
+			const { meta, ...rest } = finish;
+			finish = {
+				...rest,
+				payload: reviveValue(rest.payload, meta)
+			};
+		}
+		c.latest.current.ctx.onFinish(finish);
+		if (isTransientFinish(finish.reason)) {
+			c.episode = {
+				cause: finish.reason,
+				...finish.message !== void 0 && { message: finish.message }
+			};
+			return "reattach";
+		}
+		setStatus(c, {
+			status: "gone",
+			...finish.message !== void 0 && { message: finish.message },
+			...finish.payload !== void 0 && { payload: finish.payload }
+		});
+		return "stop";
+	}
+	if (c.connection.status !== "live") {
+		c.attempt = 0;
+		c.episode = null;
+		setStatus(c, { status: "live" });
+	}
+	return null;
+};
+const handleEnvelope = (c, env, attached) => {
+	deliverEnvelope(c, env, attached);
+	return settleEnvelope(c, env);
+};
+const scheduleRetry = (c, failure, immediate, retryAfterMs) => {
+	c.attempt += 1;
+	c.episode ??= { cause: "dropped" };
+	const delay = immediate ? 0 : retryAfterMs ?? backoff(c.attempt);
+	if (c.hasSnapshot) setStatus(c, {
+		status: "reconnecting",
+		...c.episode,
+		attempt: c.attempt,
+		nextRetryAt: Date.now() + delay,
+		...failure !== void 0 && { lastError: failure }
+	});
+	return delay;
+};
+const reconnectConn = (c) => {
+	if (!c.lifetime) return;
+	if (c.connection.status === "gone") {
+		c.attempt = 0;
+		c.episode = { cause: "dropped" };
+		flushTapSync(() => {
+			if (c.hasSnapshot) scheduleRetry(c, void 0, true);
+			else setStatus(c, { status: "connecting" });
+		});
+	}
+	c.gate.open();
+	c.abort?.abort();
+};
+const run = async (c, lifetime, gate) => {
+	const alive = () => c.lifetime === lifetime;
+	while (alive()) {
+		const abort = new AbortController();
+		c.abort = abort;
+		let failure;
+		let retryAfterMs;
+		let gone = false;
+		try {
+			gone = await c.attemptOnce(abort) === "stop";
+		} catch (error) {
+			if (!abort.signal.aborted) {
+				failure = error instanceof Error && error.message ? error.message : "network";
+				if (error instanceof Error && "retryAfterMs" in error && typeof error.retryAfterMs === "number") retryAfterMs = error.retryAfterMs;
+			}
+		}
+		abort.abort();
+		if (!alive()) return;
+		if (gone) {
+			await gate.wait();
+			continue;
+		}
+		const immediate = gate.take();
+		const delay = flushTapSync(() => scheduleRetry(c, failure, immediate, retryAfterMs));
+		if (delay === 0) continue;
+		await gate.wait(delay);
+	}
+};
+const startConn = (c) => {
+	c.hasSnapshot = false;
+	c.lease = null;
+	c.attempt = 0;
+	c.episode = null;
+	if (c.connection.status !== "connecting") setStatus(c, { status: "connecting" });
+	c.lifetime = new AbortController();
+	c.gate = createGate();
+	run(c, c.lifetime, c.gate);
+};
+const stopConn = (c) => {
+	c.abort?.abort();
+	c.lifetime?.abort();
+	c.lifetime = null;
+	c.gate.open();
+};
+const useStatewireConn = (options, ctx, create) => {
+	const latest = useRef({
+		options,
+		ctx
+	});
+	const [connection, setConnection] = useState(null);
+	const [c] = useState(() => create(latest, setConnection));
+	useEffect(() => {
+		latest.current = {
+			options,
+			ctx
+		};
+	});
+	useEffect(() => {
+		startConn(c);
+		return () => stopConn(c);
+	}, [c, options.url]);
+	return {
+		connection: connection ?? c.connection,
+		send: c.send
+	};
+};
+const classify = (timeout) => /* @__PURE__ */ new Error(timeout.aborted ? "timeout" : "network");
+const parseRetryAfter = (header) => {
+	if (!header) return void 0;
+	const value = header.trim();
+	if (/^\d+$/.test(value)) return Number(value) * 1e3;
+	const date = Date.parse(value);
+	return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
+};
+const overloadedError = (retryAfterMs) => Object.assign(/* @__PURE__ */ new Error("overloaded"), { retryAfterMs });
+//#endregion
+export { classify, createGate, deliverEnvelope, handleEnvelope, isTransientFinish, overloadedError, parseRetryAfter, reconnectConn, scheduleRetry, setStatus, settleEnvelope, useStatewireConn };
+
+//# sourceMappingURL=connection.js.map

package/dist/client/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","names":["useEffect","useRef","useState","flushTapSync","reviveOps","reviveResponse","reviveValue","backoff","ConnectionState","RemoteLink","StatewireConnection","StatewireTransportProps","Episode","cause","message","StatewireFinish","reason","payload","meta","StatewireResponse","seq","type","code","StatewireSyn","lastSeq","lease","StatewireEnvelope","ops","res","ack","syn","fin","createGate","latched","wake","take","was","wait","timeoutMs","Promise","resolve","timer","undefined","setTimeout","clearTimeout","open","Gate","ReturnType","ConnBase","connection","hasSnapshot","attempt","episode","gate","abort","AbortController","lifetime","latest","current","options","onChange","ctx","notify","reconnect","attemptOnce","setStatus","c","next","changed","status","deliverEnvelope","env","Pick","attached","map","onSnapshot","onOps","isTransientFinish","settleEnvelope","finish","rest","onFinish","handleEnvelope","scheduleRetry","failure","immediate","retryAfterMs","delay","nextRetryAt","Date","now","lastError","reconnectConn","run","alive","gone","error","signal","aborted","Error","startConn","stopConn","useStatewireConn","url","TOptions","create","send","setConnection","classify","timeout","AbortSignal","parseRetryAfter","header","value","trim","test","Number","date","parse","isNaN","Math","max","overloadedError","Object","assign"],"sources":["../../src/client/connection.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport { flushTapSync } from \"@assistant-ui/tap\";\nimport { reviveOps, reviveResponse, reviveValue } from \"../wire/meta\";\nimport { backoff } from \"./timing\";\nimport type {\n  ConnectionState,\n  RemoteLink,\n  StatewireConnection,\n  StatewireTransportProps,\n} from \"../transports/sse\";\n\nexport type Episode = {\n  cause: \"dropped\" | \"ended\" | \"error\";\n  message?: string;\n};\n\nexport type StatewireFinish = {\n  reason: \"ended\" | \"error\" | \"gone\" | \"superseded\" | (string & {});\n  message?: string;\n  payload?: unknown;\n  meta?: unknown;\n};\n\nexport type StatewireResponse = {\n  seq: number;\n  type: \"accepted\" | \"rejected\" | \"pending\" | \"crashed\" | \"result-unavailable\";\n  code?: string;\n  message?: string;\n  payload?: unknown;\n  meta?: unknown;\n};\n\nexport type StatewireSyn = {\n  lastSeq: number;\n  lease?: string;\n};\n\nexport type StatewireEnvelope = {\n  ops?: unknown[];\n  res?: StatewireResponse[];\n  ack?: number;\n  syn?: StatewireSyn;\n  fin?: StatewireFinish;\n};\n\nexport const createGate = () => {\n  let latched = false;\n  let wake: (() => void) | undefined;\n  return {\n    take: () => {\n      const was = latched;\n      latched = false;\n      return was;\n    },\n    wait: (timeoutMs?: number) => {\n      if (latched) {\n        latched = false;\n        return Promise.resolve();\n      }\n      return new Promise<void>((resolve) => {\n        const timer =\n          timeoutMs === undefined\n            ? undefined\n            : setTimeout(() => {\n                wake = undefined;\n                resolve();\n              }, timeoutMs);\n        wake = () => {\n          clearTimeout(timer);\n          wake = undefined;\n          resolve();\n        };\n      });\n    },\n    open: () => {\n      if (wake) wake();\n      else latched = true;\n    },\n  };\n};\n\nexport type Gate = ReturnType<typeof createGate>;\n\nexport type ConnBase = {\n  connection: StatewireConnection;\n  hasSnapshot: boolean;\n  lease: string | null;\n  attempt: number;\n  episode: Episode | null;\n  gate: Gate;\n  abort: AbortController | null;\n  lifetime: AbortController | null;\n  latest: {\n    readonly current: {\n      options: { onChange?: (connection: StatewireConnection) => void };\n      ctx: StatewireTransportProps;\n    };\n  };\n  notify: (connection: StatewireConnection) => void;\n  reconnect: () => void;\n  attemptOnce: (\n    abort: AbortController,\n  ) => Promise<\"stop\" | \"reattach\" | \"ended\">;\n};\n\nexport const setStatus = (c: ConnBase, next: ConnectionState) => {\n  const changed = next.status !== c.connection.status;\n  c.connection = { ...next, reconnect: c.reconnect };\n  c.notify(c.connection);\n  if (changed) c.latest.current.options.onChange?.(c.connection);\n};\n\nexport const deliverEnvelope = (\n  c: ConnBase,\n  env: Pick<StatewireEnvelope, \"ops\" | \"res\" | \"ack\" | \"syn\">,\n  attached: boolean,\n) => {\n  if (env.syn?.lease !== undefined) c.lease = env.syn.lease;\n  const ctx = c.latest.current.ctx;\n  const ops = env.ops === undefined ? [] : reviveOps(env.ops);\n  const res = env.res?.map(reviveResponse);\n  if (!attached) {\n    ctx.onSnapshot({ ops, lastSeq: env.syn?.lastSeq ?? -1 });\n  } else if (\n    env.ops !== undefined ||\n    env.res !== undefined ||\n    env.ack !== undefined\n  ) {\n    ctx.onOps({\n      ops,\n      ...(res !== undefined && { res }),\n      ...(env.ack !== undefined && { ack: env.ack }),\n    });\n  }\n  c.hasSnapshot = true;\n};\n\nexport const isTransientFinish = (\n  reason: StatewireFinish[\"reason\"],\n): reason is \"ended\" | \"error\" => reason === \"ended\" || reason === \"error\";\n\nexport const settleEnvelope = (\n  c: ConnBase,\n  env: StatewireEnvelope,\n): \"stop\" | \"reattach\" | null => {\n  let finish = env.fin;\n  if (finish) {\n    if (finish.meta !== undefined) {\n      const { meta, ...rest } = finish;\n      finish = { ...rest, payload: reviveValue(rest.payload, meta) };\n    }\n    c.latest.current.ctx.onFinish(finish);\n    if (isTransientFinish(finish.reason)) {\n      c.episode = {\n        cause: finish.reason,\n        ...(finish.message !== undefined && { message: finish.message }),\n      };\n      return \"reattach\";\n    }\n    setStatus(c, {\n      status: \"gone\",\n      ...(finish.message !== undefined && { message: finish.message }),\n      ...(finish.payload !== undefined && { payload: finish.payload }),\n    });\n    return \"stop\";\n  }\n  if (c.connection.status !== \"live\") {\n    c.attempt = 0;\n    c.episode = null;\n    setStatus(c, { status: \"live\" });\n  }\n  return null;\n};\n\nexport const handleEnvelope = (\n  c: ConnBase,\n  env: StatewireEnvelope,\n  attached: boolean,\n): \"stop\" | \"reattach\" | null => {\n  deliverEnvelope(c, env, attached);\n  return settleEnvelope(c, env);\n};\n\nexport const scheduleRetry = (\n  c: ConnBase,\n  failure: string | undefined,\n  immediate: boolean,\n  retryAfterMs?: number,\n) => {\n  c.attempt += 1;\n  c.episode ??= { cause: \"dropped\" };\n  const delay = immediate ? 0 : (retryAfterMs ?? backoff(c.attempt));\n  if (c.hasSnapshot) {\n    setStatus(c, {\n      status: \"reconnecting\",\n      ...c.episode,\n      attempt: c.attempt,\n      nextRetryAt: Date.now() + delay,\n      ...(failure !== undefined && { lastError: failure }),\n    });\n  }\n  return delay;\n};\n\nexport const reconnectConn = (c: ConnBase) => {\n  if (!c.lifetime) return;\n  if (c.connection.status === \"gone\") {\n    c.attempt = 0;\n    c.episode = { cause: \"dropped\" };\n    flushTapSync(() => {\n      if (c.hasSnapshot) scheduleRetry(c, undefined, true);\n      else setStatus(c, { status: \"connecting\" });\n    });\n  }\n  c.gate.open();\n  c.abort?.abort();\n};\n\nconst run = async (c: ConnBase, lifetime: AbortController, gate: Gate) => {\n  const alive = () => c.lifetime === lifetime;\n  while (alive()) {\n    const abort = new AbortController();\n    c.abort = abort;\n    let failure: string | undefined;\n    let retryAfterMs: number | undefined;\n    let gone = false;\n    try {\n      gone = (await c.attemptOnce(abort)) === \"stop\";\n    } catch (error) {\n      if (!abort.signal.aborted) {\n        failure =\n          error instanceof Error && error.message ? error.message : \"network\";\n        if (\n          error instanceof Error &&\n          \"retryAfterMs\" in error &&\n          typeof error.retryAfterMs === \"number\"\n        ) {\n          retryAfterMs = error.retryAfterMs;\n        }\n      }\n    }\n    abort.abort();\n    if (!alive()) return;\n    if (gone) {\n      await gate.wait();\n      continue;\n    }\n    const immediate = gate.take();\n    const delay = flushTapSync(() =>\n      scheduleRetry(c, failure, immediate, retryAfterMs),\n    );\n    if (delay === 0) continue;\n    await gate.wait(delay);\n  }\n};\n\nconst startConn = (c: ConnBase) => {\n  c.hasSnapshot = false;\n  c.lease = null;\n  c.attempt = 0;\n  c.episode = null;\n  if (c.connection.status !== \"connecting\") {\n    setStatus(c, { status: \"connecting\" });\n  }\n  c.lifetime = new AbortController();\n  c.gate = createGate();\n  void run(c, c.lifetime, c.gate);\n};\n\nconst stopConn = (c: ConnBase) => {\n  c.abort?.abort();\n  c.lifetime?.abort();\n  c.lifetime = null;\n  c.gate.open();\n};\n\nexport const useStatewireConn = <\n  TOptions extends {\n    url: string;\n    onChange?: (connection: StatewireConnection) => void;\n  },\n>(\n  options: TOptions,\n  ctx: StatewireTransportProps,\n  create: (\n    latest: {\n      readonly current: {\n        options: TOptions;\n        ctx: StatewireTransportProps;\n      };\n    },\n    notify: (connection: StatewireConnection) => void,\n  ) => ConnBase & { send: RemoteLink[\"send\"] },\n): RemoteLink => {\n  const latest = useRef({ options, ctx });\n  const [connection, setConnection] = useState<StatewireConnection | null>(\n    null,\n  );\n  const [c] = useState(() => create(latest, setConnection));\n\n  useEffect(() => {\n    latest.current = { options, ctx };\n  });\n  useEffect(() => {\n    startConn(c);\n    return () => stopConn(c);\n  }, [c, options.url]);\n\n  return {\n    connection: connection ?? c.connection,\n    send: c.send,\n  };\n};\n\nexport const classify = (timeout: AbortSignal) =>\n  new Error(timeout.aborted ? \"timeout\" : \"network\");\n\nexport const parseRetryAfter = (header: string | null): number | undefined => {\n  if (!header) return undefined;\n  const value = header.trim();\n  if (/^\\d+$/.test(value)) return Number(value) * 1000;\n  const date = Date.parse(value);\n  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());\n};\n\nexport const overloadedError = (retryAfterMs?: number) =>\n  Object.assign(new Error(\"overloaded\"), { retryAfterMs });\n"],"mappings":"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"}

package/dist/client/core.d.ts

@@ -0,0 +1,18 @@
+import { StatewireConnection } from "../transports/sse.js";
+import { StatewireCommandsProxy, StatewireOptions, StatewireTransport } from "../types.js";
+//#region src/client/core.d.ts
+declare const LIVE_CONNECTION: StatewireConnection;
+type StatewireCore = ReturnType<typeof createStatewireCore>;
+declare const createStatewireCore: (getOptions: () => StatewireOptions<any, any, any>) => {
+  attach: (next: StatewireTransport<unknown>) => void;
+  detach: () => void;
+  dispose: () => void;
+  getState: () => unknown;
+  getConnection: () => StatewireConnection;
+  commands: StatewireCommandsProxy<any>;
+  flush: () => void;
+  subscribe: (listener: () => void) => () => void;
+};
+//#endregion
+export { LIVE_CONNECTION, StatewireCore, createStatewireCore };
+//# sourceMappingURL=core.d.ts.map

package/dist/client/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","names":[],"sources":["../../src/client/core.ts"],"mappings":";;;cAkBa,iBAAiB;KA0ClB,gBAAgB,kBAAkB;cAEjC,sBACX,kBAAkB;EA8LI,SAAA,MAAA;;;;EAtGI,qBAAA;;;EA2LF,YAAA"}