statewire 0.0.0-0 → 0.0.1

package/dist/wire/ops.d.ts

@@ -0,0 +1,40 @@
+//#region src/wire/ops.d.ts
+type StatewirePath = readonly (string | number)[];
+type StatewireOp = {
+  op: "replace";
+  path: StatewirePath;
+  value: unknown;
+} | {
+  op: "add";
+  path: StatewirePath;
+  value: unknown;
+} | {
+  op: "append";
+  path: StatewirePath;
+  value: unknown;
+} | {
+  op: "remove";
+  path: StatewirePath;
+} | {
+  op: "event";
+  value: object;
+};
+declare const sanitizeValue: (value: unknown, parent?: string) => unknown;
+type MutableOp = Extract<StatewireOp, {
+  op: "replace" | "add" | "append" | "remove";
+}>;
+declare const applyOp: (root: unknown, op: MutableOp) => {
+  state: unknown;
+  changedPaths: StatewirePath[];
+};
+declare const applyOps: (state: unknown, ops: readonly unknown[]) => {
+  state: unknown;
+  events: {
+    event: unknown;
+    state: unknown;
+  }[];
+  changedPaths: StatewirePath[];
+};
+//#endregion
+export { StatewireOp, StatewirePath, applyOp, applyOps, sanitizeValue };
+//# sourceMappingURL=ops.d.ts.map

package/dist/wire/ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.d.ts","names":[],"sources":["../../src/wire/ops.ts"],"mappings":";KAEY;KAEA;EACN;EAAe,MAAM;EAAe;;EACpC;EAAW,MAAM;EAAe;;EAChC;EAAc,MAAM;EAAe;;EACnC;EAAc,MAAM;;EACpB;EAAa;;cAiBN,gBAAiB,gBAAgB;KAYzC,YAAY,QACf;EACE;;cA6GS,UACX,eACA,IAAI;EACD;EAAgB,cAAc;;cAUtB,WACX,gBACA;EAEA;EACA;IAAU;IAAgB;;EAC1B,cAAc"}

package/dist/wire/ops.js

@@ -0,0 +1,125 @@
+import { recordMutations } from "../client/optimistic.js";
+//#region src/wire/ops.ts
+const isUnsafe = (key, parent) => key === "__proto__" || key === "prototype" && parent === "constructor";
+const warnStripped = (key, parent) => {
+	if (typeof process === "undefined" || process.env["NODE_ENV"] !== "production") console.warn(`statewire: stripped unsafe key "${key}"` + (parent === void 0 ? "" : ` under "${parent}"`));
+};
+const sanitizeValue = (value, parent) => {
+	if (typeof value !== "object" || value === null) return value;
+	if (value instanceof Date) return new Date(value.getTime());
+	if (Array.isArray(value)) return value.map((item) => sanitizeValue(item));
+	const out = {};
+	for (const key of Object.keys(value)) if (isUnsafe(key, parent)) warnStripped(key, parent);
+	else out[key] = sanitizeValue(value[key], key);
+	return out;
+};
+const invalid = (op) => /* @__PURE__ */ new Error(`Statewire cannot apply ${op.op} at path: ${op.path.join(".")}`);
+const appended = (current, op) => {
+	if (typeof current !== "string" || typeof op.value !== "string") throw invalid(op);
+	return current + op.value;
+};
+const applyAtRoot = (box, op) => {
+	if (op.op === "replace") box.state = sanitizeValue(op.value);
+	else if (op.op === "append") box.state = appended(box.state, op);
+	else throw invalid(op);
+};
+const applyInList = (list, index, op) => {
+	if (op.op === "replace") {
+		if (index >= list.length) throw invalid(op);
+		list[index] = sanitizeValue(op.value);
+	} else if (op.op === "add") {
+		if (index > list.length) throw invalid(op);
+		list.splice(index, 0, sanitizeValue(op.value));
+	} else if (op.op === "append") {
+		if (index >= list.length) throw invalid(op);
+		list[index] = appended(list[index], op);
+	} else {
+		if (index >= list.length) throw invalid(op);
+		list.splice(index, 1);
+	}
+};
+const applyInObject = (obj, key, op) => {
+	const exists = Object.hasOwn(obj, key);
+	if (op.op === "replace") obj[key] = sanitizeValue(op.value, key);
+	else if (op.op === "append") obj[key] = appended(exists ? obj[key] : void 0, op);
+	else if (op.op === "remove") {
+		if (!exists) throw invalid(op);
+		delete obj[key];
+	} else throw invalid(op);
+};
+const applyOpToDraft = (box, op) => {
+	if (op.path.length === 0) {
+		applyAtRoot(box, op);
+		return;
+	}
+	let node = box.state;
+	for (let depth = 0; depth < op.path.length; depth++) {
+		const key = op.path[depth];
+		const last = depth === op.path.length - 1;
+		if (typeof key === "number") {
+			if (!Array.isArray(node) || !Number.isInteger(key) || key < 0) throw invalid(op);
+			if (last) {
+				applyInList(node, key, op);
+				return;
+			}
+			if (key >= node.length) throw invalid(op);
+			node = node[key];
+		} else {
+			if (isUnsafe(key, op.path[depth - 1]) || typeof node !== "object" || node === null || Array.isArray(node)) throw invalid(op);
+			const obj = node;
+			if (last) {
+				applyInObject(obj, key, op);
+				return;
+			}
+			if (!Object.hasOwn(obj, key)) throw invalid(op);
+			node = obj[key];
+		}
+	}
+};
+const warnedOps = /* @__PURE__ */ new Set();
+const warnUnknownOp = (type) => {
+	if (warnedOps.has(type)) return;
+	warnedOps.add(type);
+	console.warn(`statewire: ignoring unknown op type ${JSON.stringify(type)}`);
+};
+const unboxPaths = (paths) => paths.map((path) => path.slice(1));
+const applyOp = (root, op) => {
+	const recorded = recordMutations({ state: root }, (draft) => applyOpToDraft(draft, op));
+	return {
+		state: recorded.state.state,
+		changedPaths: unboxPaths(recorded.changedPaths)
+	};
+};
+const applyOps = (state, ops) => {
+	const events = [];
+	const changedPaths = [];
+	let segment = [];
+	const flush = () => {
+		if (segment.length === 0) return;
+		const ops = segment;
+		segment = [];
+		const recorded = recordMutations({ state }, (draft) => {
+			for (const op of ops) applyOpToDraft(draft, op);
+		});
+		state = recorded.state.state;
+		changedPaths.push(...unboxPaths(recorded.changedPaths));
+	};
+	for (const op of ops) if (op.op === "event") {
+		flush();
+		events.push({
+			event: sanitizeValue(op.value),
+			state
+		});
+	} else if (op.op === "replace" || op.op === "add" || op.op === "append" || op.op === "remove") segment.push(op);
+	else warnUnknownOp(op.op);
+	flush();
+	return {
+		state,
+		events,
+		changedPaths
+	};
+};
+//#endregion
+export { applyOp, applyOps, sanitizeValue };
+
+//# sourceMappingURL=ops.js.map

package/dist/wire/ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.js","names":["recordMutations","StatewirePath","StatewireOp","op","path","value","isUnsafe","key","parent","warnStripped","process","env","console","warn","undefined","sanitizeValue","Date","getTime","Array","isArray","map","item","out","Record","Object","keys","MutableOp","Extract","invalid","Error","join","appended","current","applyAtRoot","box","state","applyInList","list","index","length","splice","applyInObject","obj","exists","hasOwn","applyOpToDraft","node","depth","last","Number","isInteger","warnedOps","Set","warnUnknownOp","type","has","add","JSON","stringify","unboxPaths","paths","slice","applyOp","root","changedPaths","recorded","draft","applyOps","ops","events","event","segment","flush","push"],"sources":["../../src/wire/ops.ts"],"sourcesContent":["import { recordMutations } from \"../client/optimistic\";\n\nexport type StatewirePath = readonly (string | number)[];\n\nexport type StatewireOp =\n  | { op: \"replace\"; path: StatewirePath; value: unknown }\n  | { op: \"add\"; path: StatewirePath; value: unknown }\n  | { op: \"append\"; path: StatewirePath; value: unknown }\n  | { op: \"remove\"; path: StatewirePath }\n  | { op: \"event\"; value: object };\n\nconst isUnsafe = (key: string, parent: string | number | undefined) =>\n  key === \"__proto__\" || (key === \"prototype\" && parent === \"constructor\");\n\nconst warnStripped = (key: string, parent: string | undefined) => {\n  if (\n    typeof process === \"undefined\" ||\n    process.env[\"NODE_ENV\"] !== \"production\"\n  ) {\n    console.warn(\n      `statewire: stripped unsafe key \"${key}\"` +\n        (parent === undefined ? \"\" : ` under \"${parent}\"`),\n    );\n  }\n};\n\nexport const sanitizeValue = (value: unknown, parent?: string): unknown => {\n  if (typeof value !== \"object\" || value === null) return value;\n  if (value instanceof Date) return new Date(value.getTime());\n  if (Array.isArray(value)) return value.map((item) => sanitizeValue(item));\n  const out: Record<string, unknown> = {};\n  for (const key of Object.keys(value)) {\n    if (isUnsafe(key, parent)) warnStripped(key, parent);\n    else out[key] = sanitizeValue((value as Record<string, unknown>)[key], key);\n  }\n  return out;\n};\n\ntype MutableOp = Extract<\n  StatewireOp,\n  { op: \"replace\" | \"add\" | \"append\" | \"remove\" }\n>;\n\nconst invalid = (op: MutableOp) =>\n  new Error(`Statewire cannot apply ${op.op} at path: ${op.path.join(\".\")}`);\n\nconst appended = (\n  current: unknown,\n  op: Extract<MutableOp, { op: \"append\" }>,\n): string => {\n  if (typeof current !== \"string\" || typeof op.value !== \"string\") {\n    throw invalid(op);\n  }\n  return current + op.value;\n};\n\nconst applyAtRoot = (box: { state: unknown }, op: MutableOp) => {\n  if (op.op === \"replace\") {\n    box.state = sanitizeValue(op.value);\n  } else if (op.op === \"append\") {\n    box.state = appended(box.state, op);\n  } else {\n    throw invalid(op);\n  }\n};\n\nconst applyInList = (list: unknown[], index: number, op: MutableOp) => {\n  if (op.op === \"replace\") {\n    if (index >= list.length) throw invalid(op);\n    list[index] = sanitizeValue(op.value);\n  } else if (op.op === \"add\") {\n    if (index > list.length) throw invalid(op);\n    list.splice(index, 0, sanitizeValue(op.value));\n  } else if (op.op === \"append\") {\n    if (index >= list.length) throw invalid(op);\n    list[index] = appended(list[index], op);\n  } else {\n    if (index >= list.length) throw invalid(op);\n    list.splice(index, 1);\n  }\n};\n\nconst applyInObject = (\n  obj: Record<string, unknown>,\n  key: string,\n  op: MutableOp,\n) => {\n  const exists = Object.hasOwn(obj, key);\n  if (op.op === \"replace\") {\n    obj[key] = sanitizeValue(op.value, key);\n  } else if (op.op === \"append\") {\n    obj[key] = appended(exists ? obj[key] : undefined, op);\n  } else if (op.op === \"remove\") {\n    if (!exists) throw invalid(op);\n    delete obj[key];\n  } else {\n    throw invalid(op);\n  }\n};\n\nconst applyOpToDraft = (box: { state: unknown }, op: MutableOp): void => {\n  if (op.path.length === 0) {\n    applyAtRoot(box, op);\n    return;\n  }\n  let node: unknown = box.state;\n  for (let depth = 0; depth < op.path.length; depth++) {\n    const key = op.path[depth]!;\n    const last = depth === op.path.length - 1;\n    if (typeof key === \"number\") {\n      if (!Array.isArray(node) || !Number.isInteger(key) || key < 0) {\n        throw invalid(op);\n      }\n      if (last) {\n        applyInList(node, key, op);\n        return;\n      }\n      if (key >= node.length) throw invalid(op);\n      node = node[key];\n    } else {\n      if (\n        isUnsafe(key, op.path[depth - 1]) ||\n        typeof node !== \"object\" ||\n        node === null ||\n        Array.isArray(node)\n      ) {\n        throw invalid(op);\n      }\n      const obj = node as Record<string, unknown>;\n      if (last) {\n        applyInObject(obj, key, op);\n        return;\n      }\n      if (!Object.hasOwn(obj, key)) throw invalid(op);\n      node = obj[key];\n    }\n  }\n};\n\nconst warnedOps = new Set<unknown>();\nconst warnUnknownOp = (type: unknown) => {\n  if (warnedOps.has(type)) return;\n  warnedOps.add(type);\n  console.warn(`statewire: ignoring unknown op type ${JSON.stringify(type)}`);\n};\n\nconst unboxPaths = (paths: readonly StatewirePath[]): StatewirePath[] =>\n  paths.map((path) => path.slice(1));\n\nexport const applyOp = (\n  root: unknown,\n  op: MutableOp,\n): { state: unknown; changedPaths: StatewirePath[] } => {\n  const recorded = recordMutations({ state: root }, (draft) =>\n    applyOpToDraft(draft, op),\n  );\n  return {\n    state: recorded.state.state,\n    changedPaths: unboxPaths(recorded.changedPaths),\n  };\n};\n\nexport const applyOps = (\n  state: unknown,\n  ops: readonly unknown[],\n): {\n  state: unknown;\n  events: { event: unknown; state: unknown }[];\n  changedPaths: StatewirePath[];\n} => {\n  const events: { event: unknown; state: unknown }[] = [];\n  const changedPaths: StatewirePath[] = [];\n  let segment: MutableOp[] = [];\n  const flush = () => {\n    if (segment.length === 0) return;\n    const ops = segment;\n    segment = [];\n    const recorded = recordMutations({ state }, (draft) => {\n      for (const op of ops) applyOpToDraft(draft, op);\n    });\n    state = recorded.state.state;\n    changedPaths.push(...unboxPaths(recorded.changedPaths));\n  };\n  for (const op of ops as StatewireOp[]) {\n    if (op.op === \"event\") {\n      flush();\n      events.push({ event: sanitizeValue(op.value), state });\n    } else if (\n      op.op === \"replace\" ||\n      op.op === \"add\" ||\n      op.op === \"append\" ||\n      op.op === \"remove\"\n    ) {\n      segment.push(op);\n    } else {\n      warnUnknownOp((op as { op: unknown }).op);\n    }\n  }\n  flush();\n  return { state, events, changedPaths };\n};\n"],"mappings":"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"}

package/package.json

@@ -1,11 +1,54 @@
 {
   "name": "statewire",
-  "version": "0.0.0-0",
-  "description": "Statewire: replicate one JSON object over an SSE op stream + a command endpoint. Placeholder — real package coming from assistant-ui.",
+  "version": "0.0.1",
+  "description": "State over the wire: snapshot-first delta streaming and command submission for any state and any command",
+  "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/assistant-ui/harness-sdk"
+    "url": "git+https://github.com/assistant-ui/harness-sdk.git",
+    "directory": "packages/statewire"
   },
-  "author": "assistant-ui",
-  "license": "MIT"
-}
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./testing": {
+      "types": "./dist/transports/testing.d.ts",
+      "default": "./dist/transports/testing.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@assistant-ui/tap": "^0.9.6"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "^0.0.20",
+    "@types/react": "^19.2.17",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "react": "^19.2.8",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "aui-build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/client/changes.ts

@@ -0,0 +1,48 @@
+import type { StatewirePath } from "../wire/ops";
+import type { StatewireChanges } from "../types";
+
+const lookupValue = (state: unknown, path: StatewirePath): unknown => {
+  let node = state;
+  for (const key of path) {
+    if (typeof node !== "object" || node === null) return undefined;
+    node = Object.hasOwn(node, key)
+      ? (node as Record<string, unknown>)[key]
+      : undefined;
+  }
+  return node;
+};
+
+const keysAt = (node: unknown): string[] =>
+  typeof node === "object" && node !== null ? Object.keys(node) : [];
+
+const isPrefix = (prefix: StatewirePath, path: StatewirePath): boolean =>
+  prefix.length <= path.length &&
+  prefix.every((key, i) => String(key) === String(path[i]));
+
+export const createChanges = (
+  prev: unknown,
+  next: unknown,
+  changedPaths: readonly StatewirePath[],
+): StatewireChanges => ({
+  isChangedAt: (path) =>
+    changedPaths.some((p) => isPrefix(p, path) || isPrefix(path, p)),
+  getChangedKeys: (path) => {
+    const wiped = changedPaths.some(
+      (p) => p.length <= path.length && isPrefix(p, path),
+    );
+    if (wiped) {
+      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: string[] = [];
+    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;
+  },
+});

package/src/client/connection.ts

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