statewire 0.13.1 → 0.15.0

package/README.md

@@ -1,88 +1,39 @@
 # statewire
 
-React/TypeScript client for the **Statewire** protocol: a server owns a JSON state object and streams it to clients as packets (`POST /stream` attach, hello-snapshot first); clients change it by submitting stamped statement frames (`POST /frames`, `{"cmd": [{"method", "params", "seq"}]}`). 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.
+One JSON object replicated from a server to any number of clients, with typed commands back: the server streams snapshot-first ops, the client keeps optimistic updates rebased on top and settles every command it sent. Part of [harness-sdk](https://github.com/assistant-ui/harness-sdk), with `harness-sdk` and `pinned`.
 
-```tsx
-import { useStatewire, StatewireSSE } from "statewire";
-
-type Commands = {
-  increment(): void;
-};
-
-const { state, connection, commands } = useStatewire<State, Commands>({
-  transport: StatewireSSE({ url: "/api/threads/demo" }),
-  optimistic: (draft, command) => {
-    if (command.method === "increment") draft.count += 1;
-  },
-});
+## Install
 
-const onClick = async () => {
-  await commands.increment(); // resolves when the server has provably applied it
-};
+```sh
+pnpm add statewire react
 ```
 
-## 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.
-- **`connection`** — connection health as a tagged union: `connection.status` is `"connecting" | "live" | "reconnecting" | "gone"`, and each variant carries exactly the data that exists in that situation: `reconnecting` has `cause` (`"dropped"`, `"evicted"`, or `"error"`), `attempt`, `nextRetryAt`, `lastError?`, `message?`; `gone` carries the server's `message?` and `payload?`. `connection.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.fate` 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 `StatewireReject`)
-  - `"unknown-command"` / `"invalid-params"` — the server does not know the method, or the args failed its schema
-  - `"crashed"` — acked, but the processing died before producing a result
-  - `"result-unavailable"` — acked, but the result can no longer be delivered
-
-  Every failure also carries `cause` — which channel settled it: `"server"` = the server's answer, `"stream-gone"` = terminal `finish(gone)`, `"session-lost"` = the server forgot the client id (eviction), `"unmount"` is client-side. An `"aborted"` failure carries `predecessorLost: true` when an earlier in-flight command of the same batch has uncertain fate. The taxonomy's single exported type is `StatewireClient.SendFailure`; the `fate` and `cause` unions are reachable as `SendFailure["fate"]` / `SendFailure["cause"]`.
+## Use
 
-  An eviction replays every unsettled command under the rotated client id, in seq order — fresh seqs, relative order preserved, the original promise settles with the replay's outcome. Context submissions settle as session-lost failures and the stored context re-sends whole; replay may re-run a command the lost session already applied.
-
-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.
-
-A client id may hold any number of concurrent attaches: each gets its own hello and lease, and cmd answers fan out to every live attach of the id. A lease lives and dies with its attach — a `423` means that attach is gone: re-attach and resend.
-
-## Three ways to mount
-
-One implementation, three entry points:
-
-```ts
-useStatewire(options)               // React hook
-StatewireResource(options)          // @assistant-ui/tap resource, for composition
-new StatewireClient(options)        // framework-free: .state/.connection/.commands,
-                                    // .subscribe(cb), .dispose()
-```
-
-`StatewireClient#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 — `StatewireClient.Connection`, `StatewireClient.ConnectionStatus`, `StatewireClient.Options`, `StatewireClient.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
-})
+```tsx
+import { StatewireSSE, useStatewire } from "statewire";
+
+type CounterState = { count: number };
+type CounterCommands = { increment(): void; reset(): void };
+
+export const App = () => {
+  const { state, connection, commands } = useStatewire<
+    CounterState | undefined,
+    CounterCommands
+  >({ transport: StatewireSSE({ url: "/threads/main" }) });
+  return (
+    <main>
+      <p>{connection.status}</p>
+      <h1>{state?.count ?? 0}</h1>
+      <button onClick={() => void commands.increment()}>+1</button>
+    </main>
+  );
+};
 ```
 
-`StatewireWS({ url, protocols, query, webSocket })` is the full-duplex sibling over `/ws`. A transport is a tap resource producing the `Statewire` value the client consumes; `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/statewire`):
-
-```python
-from statewire import Statewire, StatewireReject, command
-
-class Counter(Statewire):
-    @command
-    async def increment(self):
-        if self.state["count"] >= 10:
-            raise StatewireReject("counter is full", payload={"max": 10})
-        self.state["count"] += 1
-```
+## Docs
 
-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.
+- Get started: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/get-started/statewire/page.mdx
+- Guide: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/guides/statewire/consume/page.mdx
+- Reference: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/reference/statewire/page.mdx
+- Spec: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/spec/statewire-protocol/page.mdx

package/dist/client/connection.d.ts

@@ -1,10 +1,11 @@
 import { StatewireHost } from "../host.js";
-import { StatewireRemoteProps } from "../transports/sse.js";
+import { ConnectionState, RemoteLink, StatewireFrame, StatewireRemoteProps, StatewireSubmitResult } from "../transports/sse.js";
 import { StatewireClient } from "../statewire.js";
 //#region src/client/connection.d.ts
 type Episode = {
-  cause: "dropped" | "evicted" | "error" | "unauthorized";
+  cause: "dropped" | "reconnect" | "error" | "unauthorized";
   message?: string;
+  code?: string;
 };
 /** The terminal cmd verdict types; "applied" is the sole non-terminal type. */
 declare const TERMINAL: readonly ["result", "rejected", "failed", "crashed", "expired"];
@@ -42,11 +43,13 @@ type AttemptOutcome = "stop" | "reattach" | "ended" | "idle";
 type Conn = {
   connection: StatewireClient.Connection;
   parked: boolean;
-  hasSnapshot: boolean;
   lease: string | null;
   attempt: number;
   authDenials: number;
+  authStale: boolean;
   liveAt: number | null;
+  retryAt: number;
+  error: StatewireClient.ConnectionError | undefined;
   episode: Episode | null;
   awaitingHello: boolean;
   held: StatewireCmd[];
@@ -54,21 +57,32 @@ type Conn = {
   abort: AbortController | null;
   lifetime: AbortController | null;
   ctx: StatewireRemoteProps;
+  onError: (error: StatewireClient.ConnectionError) => void;
   onChange: (connection: StatewireClient.Connection) => void;
   attemptOnce: (abort: AbortController) => Promise<AttemptOutcome>;
   notify: (connection: StatewireClient.Connection) => void;
   reconnect: () => void;
 };
+declare const degradedOf: (state: ConnectionState) => boolean;
 declare const validateRefusalSyn: (value: unknown) => StatewireSyn;
+declare const settleFin: (c: Conn, fin: StatewireHost.Fin) => AttemptOutcome;
 declare const handleEnvelope: (c: Conn, value: unknown) => AttemptOutcome | null;
-declare const useStatewireConn: (props: {
+declare const unsupportedVersion: (c: Conn, version: string) => AttemptOutcome;
+declare const resolveHeaders: (headers: StatewireClient.HeadersOption | undefined, staleAuth: boolean) => Promise<Headers>;
+declare const attachFrame: (c: Conn, headers: StatewireClient.HeadersOption | undefined) => Promise<{
+  headers: Headers;
+  body: string;
+}>;
+declare const useLink: (props: {
   url: string;
   isNew?: boolean | undefined;
   onChange?: ((connection: StatewireClient.Connection) => void) | undefined;
+  onError?: ((error: StatewireClient.ConnectionError) => void) | undefined;
   ctx: StatewireRemoteProps;
   attemptOnce: (c: Conn, abort: AbortController) => Promise<AttemptOutcome>;
-}) => Conn;
+  send: (c: Conn, frame: StatewireFrame) => Promise<StatewireSubmitResult>;
+}) => RemoteLink;
 declare const classify: (timeout: AbortSignal) => Error;
 //#endregion
-export { AttemptOutcome, Conn, Episode, Gate, StatewireCmd, StatewireEnvelope, StatewireSyn, TERMINAL, classify, handleEnvelope, useStatewireConn, validateRefusalSyn };
+export { AttemptOutcome, Conn, Episode, Gate, StatewireCmd, StatewireEnvelope, StatewireSyn, TERMINAL, attachFrame, classify, degradedOf, handleEnvelope, resolveHeaders, settleFin, unsupportedVersion, useLink, validateRefusalSyn };
 //# sourceMappingURL=connection.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","names":[],"sources":["../../src/client/connection.ts"],"mappings":";;;;KAQY;EACV;EACA;;;cAIW;KAQD;EACV;EACA,2BAA2B;EAC3B;EACA;EACA;EACA;;EAEA;;KAGU;EACV;EACA;EACA;EACA;EACA;EACA;;KAGU;EACV;EACA,MAAM;EACN;EACA;EACA,MAAM;EACN,MAAM,cAAc;;KAGV;EAAS;EAAkB;;KAoC3B;KAEA;EACV,YAAY,gBAAgB;EAC5B;EACA;EACA;EACA;EACA;EACA;EACA,SAAS;EACT;EACA,MAAM;EACN,MAAM;EACN,OAAO;EACP,UAAU;EACV,KAAK;EACL,WAAW,YAAY,gBAAgB;EACvC,cAAc,OAAO,oBAAoB,QAAQ;EACjD,SAAS,YAAY,gBAAgB;EACrC;;cA8CW,qBAAsB,mBAAiB;cA8NvC,iBACX,GAAG,MACH,mBACC;cA6FU,mBAAoB;EAC/B;EACA;EACA,aAAa,YAAY,gBAAgB;EACzC,KAAK;EACL,cAAc,GAAG,MAAM,OAAO,oBAAoB,QAAQ;MACxD;cAuDS,WAAY,SAAS,gBAAW"}
+{"version":3,"file":"connection.d.ts","names":[],"sources":["../../src/client/connection.ts"],"mappings":";;;;KAcY;EACV;EACA;EACA;;;cAIW;KAQD;EACV;EACA,2BAA2B;EAC3B;EACA;EACA;EACA;;EAEA;;KAGU;EACV;EACA;EACA;EACA;EACA;EACA;;KAGU;EACV;EACA,MAAM;EACN;EACA;EACA,MAAM;EACN,MAAM,cAAc;;KAGV;EAAS;EAAkB;;KAoC3B;KAEA;EACV,YAAY,gBAAgB;EAC5B;EACA;EACA;EACA;EACA;EACA;EACA;EACA,OAAO,gBAAgB;EACvB,SAAS;EACT;EACA,MAAM;EACN,MAAM;EACN,OAAO;EACP,UAAU;EACV,KAAK;EACL,UAAU,OAAO,gBAAgB;EACjC,WAAW,YAAY,gBAAgB;EACvC,cAAc,OAAO,oBAAoB,QAAQ;EACjD,SAAS,YAAY,gBAAgB;EACrC;;cAGW,aAAc,OAAO;cAuErB,qBAAsB,mBAAiB;cAyKvC,YAAa,GAAG,MAAM,KAAK,cAAc,QAAM;cA+D/C,iBACX,GAAG,MACH,mBACC;cAkIU,qBAAsB,GAAG,MAAM,oBAAkB;cAUjD,iBACX,SAAS,gBAAgB,2BACzB,uBACC,QAAQ;cAME,cACX,GAAG,MACH,SAAS,gBAAgB,8BAAyB;;;;cAcvC,UAAW;EACtB;EACA;EACA,aAAa,YAAY,gBAAgB;EACzC,YAAY,OAAO,gBAAgB;EACnC,KAAK;EACL,cAAc,GAAG,MAAM,OAAO,oBAAoB,QAAQ;EAC1D,OAAO,GAAG,MAAM,OAAO,mBAAmB,QAAQ;MAChD;cA+ES,WAAY,SAAS,gBAAW"}

package/dist/client/connection.js

@@ -41,14 +41,23 @@ const openGate = (g) => {
 	if (g.wake) g.wake();
 	else g.latched = true;
 };
+const degradedOf = (state) => state.status === "connecting" && state.attempt > 0 || state.status === "disconnected" && state.reason !== "idle" && state.reason !== "deferred";
+const sameState = (a, b) => {
+	if (a.status !== b.status) return false;
+	if (a.status === "connecting" && b.status === "connecting") return a.attempt === b.attempt && a.cause === b.cause && a.code === b.code && a.nextRetryAt === b.nextRetryAt && a.lastError === b.lastError;
+	if (a.status === "disconnected" && b.status === "disconnected") return a.reason === b.reason;
+	return true;
+};
 const setStatus = (c, next) => {
-	const changed = next.status !== c.connection.status;
+	if (sameState(next, c.connection) && c.connection.error === c.error) return;
 	c.connection = {
 		...next,
-		reconnect: c.reconnect
+		...c.error === void 0 ? {} : { error: c.error },
+		reconnect: c.reconnect,
+		degraded: degradedOf(next)
 	};
 	c.notify(c.connection);
-	if (changed) c.onChange(c.connection);
+	c.onChange(c.connection);
 };
 const protocolError = (message) => {
 	throw new Error(`statewire: protocol error: ${message}`);
@@ -87,6 +96,9 @@ const validateFin = (value) => {
 	if (!isObject(value)) return protocolError("fin must be an object");
 	if (typeof value["reason"] !== "string") protocolError("fin.reason must be a string");
 	validateOptionalString(value["message"], "fin.message");
+	validateOptionalString(value["code"], "fin.code");
+	if (value["status"] !== void 0 && !isNonnegativeSafeInteger(value["status"])) protocolError("fin.status must be a nonnegative safe integer");
+	if (value["retry"] !== void 0 && !isNonnegativeSafeInteger(value["retry"])) protocolError("fin.retry must be a nonnegative safe integer");
 	return true;
 };
 const validateEnvelope = (value) => {
@@ -118,9 +130,7 @@ const cmdsOf = (env) => {
 const snapshotOf = (env) => {
 	const ops = env.ops;
 	if (ops === void 0) return protocolError("hello missing snapshot");
-	if (ops.length !== 1 || !isObject(ops[0])) return protocolError("hello snapshot must be one root replace op");
-	const op = ops[0];
-	if (op["op"] !== "replace" || !Array.isArray(op["path"]) || op["path"].length !== 0 || !Object.hasOwn(op, "value")) return protocolError("hello snapshot must be one root replace op");
+	if (ops.length === 0) return protocolError("hello missing snapshot");
 	return reviveOps(ops);
 };
 const helloSynOf = (env) => {
@@ -138,11 +148,11 @@ const handleHello = (c, env) => {
 	});
 	c.ctx.onIdle(syn.idle ?? false);
 	c.awaitingHello = false;
-	c.hasSnapshot = true;
+	c.error = void 0;
 	c.liveAt = Date.now();
 	c.authDenials = 0;
 	c.episode = null;
-	setStatus(c, { status: "live" });
+	setStatus(c, { status: "connected" });
 };
 let warnedUnknownSynFact = false;
 const warnUnknownSynFact = () => {
@@ -178,48 +188,45 @@ const deliverEnvelope = (c, env) => {
 	}
 	if (typeof env.idle === "boolean") c.ctx.onIdle(env.idle);
 };
-const transientCauseOf = (reason) => {
-	switch (reason) {
-		case "evicted": return "evicted";
-		case "error": return "error";
-		case "unauthorized": return "unauthorized";
-		default: return "error";
-	}
-};
 const settleFin = (c, fin) => {
-	let finish = fin;
-	if (finish.meta !== void 0) {
-		const { meta, ...rest } = finish;
-		finish = {
-			...rest,
-			payload: reviveValue(rest.payload, meta)
-		};
-	}
+	const finish = fin.meta === void 0 ? fin : {
+		...fin,
+		payload: reviveValue(fin.payload, fin.meta)
+	};
 	releaseHeld(c);
+	c.retryAt = Date.now() + (finish.retry ?? 0);
 	if (finish.reason === "idle") {
 		c.ctx.onIdle(true);
 		c.attempt = 0;
 		c.episode = null;
-		setStatus(c, { status: "idle" });
+		c.error = void 0;
+		setStatus(c, {
+			status: "disconnected",
+			reason: "idle"
+		});
 		return "idle";
 	}
 	const denial = finish.reason === "unauthorized";
-	const terminal = finish.reason === "gone" || denial && c.authDenials > 0;
-	if (denial) c.authDenials += 1;
-	c.ctx.onFinish(terminal ? finish : {
-		...finish,
-		reason: "error"
-	});
+	const terminal = finish.reason === "gone" || finish.reason === "forbidden" || finish.reason === "protocol-error" || denial && c.authDenials > 0;
+	if (denial) {
+		c.authDenials += 1;
+		c.authStale = true;
+	}
+	c.error = finish.reason !== "reconnect" && finish.reason !== "gone" && (!denial || terminal) ? Object.assign(new Error(finish.message ?? finish.reason), { fin: finish }) : void 0;
+	if (c.error) c.onError(c.error);
 	if (!terminal) {
 		c.episode = {
-			cause: transientCauseOf(finish.reason),
-			...finish.message !== void 0 && { message: finish.message }
+			cause: finish.reason === "reconnect" ? "reconnect" : denial ? "unauthorized" : "error",
+			...finish.message !== void 0 && { message: finish.message },
+			...finish.code !== void 0 && { code: finish.code }
 		};
 		if (denial) openGate(c.gate);
 		return "reattach";
 	}
+	c.ctx.onFinish(finish);
 	setStatus(c, {
-		status: "gone",
+		status: "disconnected",
+		reason: denial ? "unauthorized" : finish.reason === "forbidden" ? "forbidden" : finish.reason === "protocol-error" ? "protocol-error" : "gone",
 		...finish.message !== void 0 && { message: finish.message },
 		...finish.payload !== void 0 && { payload: finish.payload }
 	});
@@ -234,23 +241,27 @@ const handleEnvelope = (c, value) => {
 	}
 	deliverEnvelope(c, env);
 	if (env.fin !== void 0) return settleFin(c, env.fin);
-	if (c.connection.status !== "live") {
+	if (c.connection.status !== "connected") {
 		c.attempt = 0;
 		c.episode = null;
-		setStatus(c, { status: "live" });
+		setStatus(c, { status: "connected" });
 	}
 	return null;
 };
+const dialing = (c) => setStatus(c, {
+	status: "connecting",
+	attempt: c.attempt
+});
 const scheduleRetry = (c, failure, immediate) => {
 	if (c.liveAt !== null && Date.now() - c.liveAt >= timing.backoffResetMs) c.attempt = 0;
 	c.liveAt = null;
 	c.attempt += 1;
 	c.episode ??= { cause: "dropped" };
-	const delay = immediate ? 0 : backoff(c.attempt);
+	const delay = Math.max(immediate ? 0 : backoff(c.attempt), c.retryAt - Date.now());
 	setStatus(c, {
-		status: "reconnecting",
-		...c.episode,
+		status: "connecting",
 		attempt: c.attempt,
+		...c.episode,
 		nextRetryAt: Date.now() + delay,
 		...failure !== void 0 && { lastError: failure }
 	});
@@ -258,13 +269,11 @@ const scheduleRetry = (c, failure, immediate) => {
 };
 const reconnectConn = (c) => {
 	if (!c.lifetime) return;
-	if (c.connection.status === "gone" || c.connection.status === "idle") {
+	if (c.connection.status === "disconnected") {
 		c.attempt = 0;
 		c.authDenials = 0;
-		c.episode = { cause: "dropped" };
-		flushTapSync(() => {
-			scheduleRetry(c, void 0, true);
-		});
+		c.episode = null;
+		flushTapSync(() => dialing(c));
 	}
 	openGate(c.gate);
 	c.abort?.abort();
@@ -277,6 +286,11 @@ const run = async (c, lifetime, gate) => {
 		c.parked = false;
 	}
 	while (alive()) {
+		if (c.retryAt > Date.now()) {
+			await waitGate(gate, c.retryAt - Date.now());
+			continue;
+		}
+		flushTapSync(() => dialing(c));
 		const abort = new AbortController();
 		c.abort = abort;
 		c.awaitingHello = true;
@@ -286,7 +300,17 @@ const run = async (c, lifetime, gate) => {
 		try {
 			outcome = await c.attemptOnce(abort);
 		} catch (error) {
-			if (!abort.signal.aborted) failure = error instanceof Error && error.message ? error.message : "network";
+			if (!abort.signal.aborted) {
+				if (error instanceof SyntaxError || error instanceof Error && /^(statewire: protocol error:|Statewire cannot apply)/.test(error.message)) outcome = flushTapSync(() => settleFin(c, {
+					reason: "protocol-error",
+					message: error.message
+				}));
+				else if (c.authStale) outcome = flushTapSync(() => settleFin(c, {
+					reason: "unauthorized",
+					message: error instanceof Error ? error.message : "credential refresh failed"
+				}));
+				failure = error instanceof Error && error.message ? error.message : "network";
+			}
 		}
 		abort.abort();
 		if (!alive()) return;
@@ -295,6 +319,7 @@ const run = async (c, lifetime, gate) => {
 			c.ctx.onDetach();
 		});
 		if (!alive()) return;
+		if (c.connection.status === "disconnected" && !["deferred", "idle"].includes(c.connection.reason)) outcome = "stop";
 		if (outcome === "stop" || outcome === "idle") {
 			await waitGate(gate);
 			continue;
@@ -305,18 +330,37 @@ const run = async (c, lifetime, gate) => {
 		await waitGate(gate, delay);
 	}
 };
-const useStatewireConn = (props) => {
+const unsupportedVersion = (c, version) => flushTapSync(() => handleEnvelope(c, { fin: {
+	reason: "protocol-error",
+	message: `unsupported protocol version: ${version || "\"\""}`
+} })) ?? "stop";
+const resolveHeaders = async (headers, staleAuth) => new Headers(typeof headers === "function" ? await headers({ staleAuth }) : headers);
+const attachFrame = async (c, headers) => {
+	const resolved = await resolveHeaders(headers, c.authStale);
+	c.authStale = false;
+	const lanes = flushTapSync(() => c.ctx.takeAttachLanes());
+	return {
+		headers: resolved,
+		body: JSON.stringify({
+			headers: Object.fromEntries(resolved),
+			...lanes ?? {}
+		})
+	};
+};
+const useLink = (props) => {
 	const latest = useRef(props);
 	latest.current = props;
 	const [, setConnection] = useState(null);
 	const [c] = useState(() => {
 		const conn = {
 			parked: props.isNew ?? false,
-			hasSnapshot: false,
 			lease: null,
 			attempt: 0,
 			authDenials: 0,
+			authStale: false,
 			liveAt: null,
+			retryAt: 0,
+			error: void 0,
 			episode: null,
 			awaitingHello: true,
 			held: [],
@@ -326,25 +370,49 @@ const useStatewireConn = (props) => {
 			get ctx() {
 				return latest.current.ctx;
 			},
+			onError: (error) => latest.current.onError?.(error),
 			onChange: (connection) => latest.current.onChange?.(connection),
 			attemptOnce: (abort) => latest.current.attemptOnce(conn, abort),
 			notify: setConnection,
 			reconnect: () => reconnectConn(conn),
 			connection: {
-				status: "connecting",
+				...props.isNew ?? false ? {
+					status: "disconnected",
+					reason: "deferred"
+				} : {
+					status: "connecting",
+					attempt: 0
+				},
+				degraded: false,
 				reconnect: () => conn.reconnect()
 			}
 		};
 		return conn;
 	});
+	const [link] = useState(() => ({
+		get connection() {
+			return c.connection;
+		},
+		get parked() {
+			return c.parked;
+		},
+		send: (frame) => latest.current.send(c, frame)
+	}));
 	useEffect(() => {
-		c.hasSnapshot = false;
 		c.lease = null;
 		c.attempt = 0;
 		c.authDenials = 0;
+		c.authStale = false;
 		c.liveAt = null;
+		c.retryAt = 0;
 		c.episode = null;
-		if (c.connection.status !== "connecting") setStatus(c, { status: "connecting" });
+		setStatus(c, c.parked ? {
+			status: "disconnected",
+			reason: "deferred"
+		} : {
+			status: "connecting",
+			attempt: 0
+		});
 		const lifetime = new AbortController();
 		c.lifetime = lifetime;
 		c.gate = newGate();
@@ -356,10 +424,10 @@ const useStatewireConn = (props) => {
 			openGate(c.gate);
 		};
 	}, [c, props.url]);
-	return c;
+	return link;
 };
 const classify = (timeout) => /* @__PURE__ */ new Error(timeout.aborted ? "timeout" : "network");
 //#endregion
-export { TERMINAL, classify, handleEnvelope, useStatewireConn, validateRefusalSyn };
+export { TERMINAL, attachFrame, classify, degradedOf, handleEnvelope, resolveHeaders, settleFin, unsupportedVersion, useLink, validateRefusalSyn };
 
 //# sourceMappingURL=connection.js.map