iterate 0.2.7 → 0.3.0

package/dist/sdk/capnweb/react.mjs

@@ -0,0 +1,316 @@
+import { r as createLiveStateStore, t as isLiveStateSnapshot } from "../../protocol-DnK_f2m6.mjs";
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+//#region src/sdk/capnweb/react.tsx
+const CapnWebContext = createContext(void 0);
+const CONNECTION_STABLE_MS = 3e4;
+const CONNECTION_RETRY_MAX_MS = 1e4;
+const SUBSCRIBE_RETRY_MS = 1e4;
+const MAX_SUBSCRIBE_RETRIES = 2;
+const SUBSCRIBE_TIMEOUT_MS = 15e3;
+const PING_INTERVAL_MS = 45e3;
+const PING_TIMEOUT_MS = 1e4;
+function releaseLiveStateSubscription(handle) {
+	Promise.resolve().then(() => handle.unsubscribe()).catch(() => {}).finally(() => handle[Symbol.dispose]?.());
+}
+/**
+* Own one reconnectable Cap'n Web root for a React subtree. The factory is the
+* only transport policy: it can dial a WebSocket directly or duplicate a root
+* from a lower-level shared connection keeper. Broken roots are disposed and
+* replaced with bounded exponential backoff.
+*/
+function CapnWebProvider({ children, makeConnection }) {
+	return createElement(CapnWebContext, { value: useCapnWebConnection(makeConnection) }, children);
+}
+function useCapnWebConnection(makeConnection, enabled = true) {
+	const [epoch, setEpoch] = useState(0);
+	const failures = useRef(0);
+	const failureSource = useRef(makeConnection);
+	const reconnect = useCallback(() => setEpoch((current) => current + 1), []);
+	const [snapshot, setSnapshot] = useState({
+		enabled,
+		generation: 0,
+		reconnect,
+		source: makeConnection,
+		status: "connecting"
+	});
+	useEffect(() => {
+		let disposed = false;
+		let root;
+		let retry;
+		let stable;
+		if (failureSource.current !== makeConnection) {
+			failureSource.current = makeConnection;
+			failures.current = 0;
+		}
+		if (!enabled || makeConnection === void 0) {
+			failures.current = 0;
+			setSnapshot((current) => ({
+				enabled,
+				generation: current.generation,
+				reconnect,
+				source: makeConnection,
+				status: "connecting"
+			}));
+		} else {
+			const scheduleReconnect = () => {
+				const nextFailures = failures.current += 1;
+				retry = setTimeout(reconnect, Math.min(250 * 2 ** (nextFailures - 1), CONNECTION_RETRY_MAX_MS));
+			};
+			setSnapshot((current) => ({
+				enabled,
+				generation: current.generation,
+				reconnect,
+				source: makeConnection,
+				status: "connecting"
+			}));
+			Promise.resolve(makeConnection()).then((connected) => {
+				if (disposed) {
+					connected[Symbol.dispose]?.();
+					return;
+				}
+				root = connected;
+				setSnapshot((current) => ({
+					enabled,
+					generation: current.generation + 1,
+					reconnect,
+					root: connected,
+					source: makeConnection,
+					status: "connected"
+				}));
+				stable = setTimeout(() => {
+					if (!disposed && root === connected) failures.current = 0;
+				}, CONNECTION_STABLE_MS);
+				connected.onRpcBroken?.(() => {
+					if (disposed || root !== connected) return;
+					clearTimeout(stable);
+					root = void 0;
+					connected[Symbol.dispose]?.();
+					setSnapshot((current) => ({
+						enabled,
+						generation: current.generation,
+						reconnect,
+						source: makeConnection,
+						status: "connecting"
+					}));
+					scheduleReconnect();
+				});
+			}, (cause) => {
+				if (disposed) return;
+				setSnapshot((current) => ({
+					enabled,
+					error: cause instanceof Error ? cause.message : String(cause),
+					generation: current.generation,
+					reconnect,
+					source: makeConnection,
+					status: "error"
+				}));
+				scheduleReconnect();
+			});
+		}
+		return () => {
+			disposed = true;
+			clearTimeout(retry);
+			clearTimeout(stable);
+			root?.[Symbol.dispose]?.();
+		};
+	}, [
+		enabled,
+		epoch,
+		makeConnection,
+		reconnect
+	]);
+	if (snapshot.enabled !== enabled || snapshot.source !== makeConnection) return {
+		generation: snapshot.generation,
+		reconnect,
+		scope: makeConnection,
+		status: "connecting"
+	};
+	const { enabled: _enabled, source: _source, ...connection } = snapshot;
+	return {
+		...connection,
+		scope: makeConnection
+	};
+}
+/** The current provider root, undefined while its connection is being replaced. */
+function useCapnWebRoot() {
+	const connection = useContext(CapnWebContext);
+	if (connection === void 0) throw new Error("useCapnWebRoot must be rendered under <CapnWebProvider>.");
+	return connection.root;
+}
+/** Resolve provider, owned connection, or borrowed root with one logical scope. */
+function useLiveStateConnection(options) {
+	const provider = useContext(CapnWebContext);
+	const hasRootOverride = options !== void 0 && Object.hasOwn(options, "root");
+	const connectionFactory = hasRootOverride ? void 0 : options?.makeConnection;
+	const owned = useCapnWebConnection(connectionFactory, !hasRootOverride && (options?.enabled ?? true));
+	if (!hasRootOverride && !connectionFactory && !provider) throw new Error("useLiveState needs <CapnWebProvider>, a makeConnection option, or an explicit { root } override.");
+	const connection = hasRootOverride ? void 0 : connectionFactory ? owned : provider;
+	const root = (hasRootOverride ? options.root : connection?.root) ?? void 0;
+	return {
+		connection,
+		root,
+		scope: hasRootOverride ? root : connectionFactory ?? connection?.scope
+	};
+}
+/**
+* Render a selected slice of any LiveStateRpc reachable from the provider root.
+* Pass `{ root }` to borrow an explicit root instead; borrowed roots are never
+* disposed or reconnected by this hook.
+*/
+function useLiveState(live, selector = (state) => state, deps = [], options) {
+	const { connection, root, scope } = useLiveStateConnection(options);
+	const enabled = options?.enabled ?? true;
+	const [epoch, setEpoch] = useState(0);
+	const liveRef = useRef(live);
+	const selectorRef = useRef(selector);
+	useEffect(() => {
+		liveRef.current = live;
+		selectorRef.current = selector;
+	});
+	const store = useMemo(() => createLiveStateStore(), [scope, ...deps]);
+	const subscribeRetries = useMemo(() => ({
+		count: 0,
+		resyncs: 0
+	}), [store]);
+	const refresh = useCallback(() => {
+		subscribeRetries.count = 0;
+		subscribeRetries.resyncs = 0;
+		setEpoch((current) => current + 1);
+	}, [subscribeRetries]);
+	const [subscriptionState, setSubscriptionState] = useState({
+		epoch,
+		generation: connection?.generation,
+		status: "connecting",
+		store
+	});
+	useEffect(() => {
+		let disposed = false;
+		let stale = false;
+		let handle;
+		let pingTimeout;
+		let retry;
+		let timeout;
+		let watchdog;
+		const release = () => {
+			stale = true;
+			if (handle === void 0) return;
+			releaseLiveStateSubscription(handle);
+			handle = void 0;
+		};
+		setSubscriptionState({
+			epoch,
+			generation: connection?.generation,
+			status: "connecting",
+			store
+		});
+		if (enabled && root !== void 0) {
+			const report = (cause, shouldRetry = false) => {
+				if (disposed || stale) return;
+				release();
+				setSubscriptionState({
+					error: cause instanceof Error ? cause.message : String(cause),
+					epoch,
+					generation: connection?.generation,
+					status: "error",
+					store
+				});
+				if (shouldRetry && subscribeRetries.count < MAX_SUBSCRIBE_RETRIES) {
+					subscribeRetries.count += 1;
+					retry = setTimeout(() => setEpoch((current) => current + 1), SUBSCRIBE_RETRY_MS);
+				}
+			};
+			try {
+				const pending = liveRef.current(root).subscribe((update) => {
+					if (disposed || stale) return;
+					try {
+						store.apply(update, () => {
+							throw new Error("Live-state revision gap");
+						});
+						if (!isLiveStateSnapshot(update)) subscribeRetries.resyncs = 0;
+					} catch (error) {
+						const shouldResync = subscribeRetries.resyncs < MAX_SUBSCRIBE_RETRIES;
+						if (shouldResync) subscribeRetries.resyncs += 1;
+						report(error, shouldResync);
+					}
+				}, { patchVersion: 3 });
+				timeout = setTimeout(() => report(/* @__PURE__ */ new Error(`live-state subscription timed out after ${SUBSCRIBE_TIMEOUT_MS}ms`), true), SUBSCRIBE_TIMEOUT_MS);
+				Promise.resolve(pending).then((subscription) => {
+					clearTimeout(timeout);
+					if (disposed || stale) {
+						releaseLiveStateSubscription(subscription);
+						return;
+					}
+					handle = subscription;
+					subscribeRetries.count = 0;
+					setSubscriptionState({
+						epoch,
+						generation: connection?.generation,
+						status: "live",
+						store
+					});
+					watchdog = setInterval(() => {
+						if (handle === void 0) return;
+						Promise.race([Promise.resolve(handle.ping()), new Promise((resolve) => {
+							pingTimeout = setTimeout(() => resolve(false), PING_TIMEOUT_MS);
+						})]).then((alive) => {
+							if (!disposed && !alive) refresh();
+						}, (cause) => report(cause, true)).finally(() => clearTimeout(pingTimeout));
+					}, PING_INTERVAL_MS);
+				}, (cause) => {
+					clearTimeout(timeout);
+					report(cause, true);
+				});
+			} catch (cause) {
+				report(cause, true);
+			}
+		}
+		return () => {
+			disposed = true;
+			clearTimeout(pingTimeout);
+			clearTimeout(timeout);
+			clearTimeout(retry);
+			clearInterval(watchdog);
+			release();
+		};
+	}, [
+		connection?.generation,
+		enabled,
+		epoch,
+		root,
+		store,
+		...deps
+	]);
+	const selected = useRef({
+		state: void 0,
+		value: void 0
+	});
+	const getSelected = () => {
+		const state = store.getState();
+		if (Object.is(selected.current.state, state)) return selected.current.value;
+		const value = state === void 0 ? void 0 : selectorRef.current(state);
+		selected.current = {
+			state,
+			value
+		};
+		return value;
+	};
+	const value = useSyncExternalStore(store.subscribe, getSelected, () => void 0);
+	const providerError = connection?.status === "error" ? connection.error : void 0;
+	const activeSubscriptionState = subscriptionState.store === store && subscriptionState.epoch === epoch && subscriptionState.generation === connection?.generation ? subscriptionState : {
+		epoch,
+		generation: connection?.generation,
+		status: "connecting",
+		store
+	};
+	const connectionIsConnecting = connection?.status === "connecting";
+	return {
+		error: providerError ?? (connectionIsConnecting || !enabled ? void 0 : activeSubscriptionState.error),
+		refresh: connection?.status === "error" ? connection.reconnect : refresh,
+		status: providerError !== void 0 ? "error" : connectionIsConnecting || !enabled ? "connecting" : activeSubscriptionState.status,
+		value
+	};
+}
+//#endregion
+export { CapnWebProvider, useCapnWebRoot, useLiveState };
+
+//# sourceMappingURL=react.mjs.map

package/dist/sdk/capnweb/react.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.mjs","names":[],"sources":["../../../src/sdk/capnweb/react.tsx"],"sourcesContent":["// oxlint-disable react/only-export-components -- this public entry deliberately colocates its provider with the hooks that consume it.\nimport {\n  createContext,\n  createElement,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n  type ReactNode,\n} from \"react\";\nimport { createLiveStateStore } from \"./live-state/store.ts\";\nimport { isLiveStateSnapshot } from \"./live-state/protocol.ts\";\nimport type { LiveStateRpc, LiveStateSubscriptionHandle } from \"./live-state/types.ts\";\n\nexport type CapnWebRoot = object &\n  Partial<Disposable> & {\n    onRpcBroken?(callback: (error?: unknown) => void): void;\n  };\n\nexport type MakeCapnWebConnection<Root extends CapnWebRoot> = () => Root | PromiseLike<Root>;\nexport type LiveStateStatus = \"connecting\" | \"live\" | \"error\";\n\ntype ConnectionSnapshot = {\n  error?: string;\n  generation: number;\n  reconnect: () => void;\n  root?: CapnWebRoot;\n  /** Stable for one connection factory, across all of that factory's reconnects. */\n  scope: object | undefined;\n  status: \"connecting\" | \"connected\" | \"error\";\n};\n\nconst CapnWebContext = createContext<ConnectionSnapshot | undefined>(undefined);\nconst CONNECTION_STABLE_MS = 30_000;\nconst CONNECTION_RETRY_MAX_MS = 10_000;\nconst SUBSCRIBE_RETRY_MS = 10_000;\nconst MAX_SUBSCRIBE_RETRIES = 2;\nconst SUBSCRIBE_TIMEOUT_MS = 15_000;\nconst PING_INTERVAL_MS = 45_000;\nconst PING_TIMEOUT_MS = 10_000;\n\nfunction releaseLiveStateSubscription(handle: LiveStateSubscriptionHandle): void {\n  // Teardown commonly races a dead transport: the remote unsubscribe may\n  // reject, but the local capability must still leave Cap'n Web's import table.\n  void Promise.resolve()\n    .then(() => handle.unsubscribe())\n    .catch(() => {})\n    .finally(() => handle[Symbol.dispose]?.());\n}\n\n/**\n * Own one reconnectable Cap'n Web root for a React subtree. The factory is the\n * only transport policy: it can dial a WebSocket directly or duplicate a root\n * from a lower-level shared connection keeper. Broken roots are disposed and\n * replaced with bounded exponential backoff.\n */\nexport function CapnWebProvider<Root extends CapnWebRoot>({\n  children,\n  makeConnection,\n}: {\n  children?: ReactNode;\n  makeConnection: MakeCapnWebConnection<Root>;\n}) {\n  const snapshot = useCapnWebConnection(makeConnection);\n\n  return createElement(CapnWebContext, { value: snapshot }, children);\n}\n\nfunction useCapnWebConnection<Root extends CapnWebRoot>(\n  makeConnection: MakeCapnWebConnection<Root> | undefined,\n  enabled = true,\n): ConnectionSnapshot {\n  const [epoch, setEpoch] = useState(0);\n  const failures = useRef(0);\n  const failureSource = useRef(makeConnection);\n  const reconnect = useCallback(() => setEpoch((current) => current + 1), []);\n  const [snapshot, setSnapshot] = useState<InternalConnectionSnapshot<Root>>({\n    enabled,\n    generation: 0,\n    reconnect,\n    source: makeConnection,\n    status: \"connecting\",\n  });\n\n  // react-doctor-disable-next-line effect-needs-cleanup -- the unconditional cleanup below owns both timers assigned by async connection callbacks and the root\n  useEffect(() => {\n    let disposed = false;\n    let root: Root | undefined;\n    let retry: ReturnType<typeof setTimeout> | undefined;\n    let stable: ReturnType<typeof setTimeout> | undefined;\n    if (failureSource.current !== makeConnection) {\n      failureSource.current = makeConnection;\n      failures.current = 0;\n    }\n    if (!enabled || makeConnection === undefined) {\n      failures.current = 0;\n      setSnapshot((current) => ({\n        enabled,\n        generation: current.generation,\n        reconnect,\n        source: makeConnection,\n        status: \"connecting\",\n      }));\n    } else {\n      const scheduleReconnect = () => {\n        const nextFailures = (failures.current += 1);\n        retry = setTimeout(\n          reconnect,\n          Math.min(250 * 2 ** (nextFailures - 1), CONNECTION_RETRY_MAX_MS),\n        );\n      };\n      setSnapshot((current) => ({\n        enabled,\n        generation: current.generation,\n        reconnect,\n        source: makeConnection,\n        status: \"connecting\",\n      }));\n\n      void Promise.resolve(makeConnection()).then(\n        (connected) => {\n          if (disposed) {\n            connected[Symbol.dispose]?.();\n            return;\n          }\n          root = connected;\n          setSnapshot((current) => ({\n            enabled,\n            generation: current.generation + 1,\n            reconnect,\n            root: connected,\n            source: makeConnection,\n            status: \"connected\",\n          }));\n          stable = setTimeout(() => {\n            if (!disposed && root === connected) failures.current = 0;\n          }, CONNECTION_STABLE_MS);\n          connected.onRpcBroken?.(() => {\n            if (disposed || root !== connected) return;\n            clearTimeout(stable);\n            root = undefined;\n            connected[Symbol.dispose]?.();\n            setSnapshot((current) => ({\n              enabled,\n              generation: current.generation,\n              reconnect,\n              source: makeConnection,\n              status: \"connecting\",\n            }));\n            scheduleReconnect();\n          });\n        },\n        (cause: unknown) => {\n          if (disposed) return;\n          setSnapshot((current) => ({\n            enabled,\n            error: cause instanceof Error ? cause.message : String(cause),\n            generation: current.generation,\n            reconnect,\n            source: makeConnection,\n            status: \"error\",\n          }));\n          scheduleReconnect();\n        },\n      );\n    }\n\n    return () => {\n      disposed = true;\n      clearTimeout(retry);\n      clearTimeout(stable);\n      root?.[Symbol.dispose]?.();\n    };\n  }, [enabled, epoch, makeConnection, reconnect]);\n\n  if (snapshot.enabled !== enabled || snapshot.source !== makeConnection) {\n    return {\n      generation: snapshot.generation,\n      reconnect,\n      scope: makeConnection,\n      status: \"connecting\",\n    };\n  }\n  const { enabled: _enabled, source: _source, ...connection } = snapshot;\n  return { ...connection, scope: makeConnection };\n}\n\ntype InternalConnectionSnapshot<Root extends CapnWebRoot> = Omit<ConnectionSnapshot, \"scope\"> & {\n  enabled: boolean;\n  source: MakeCapnWebConnection<Root> | undefined;\n};\n\n/** The current provider root, undefined while its connection is being replaced. */\nexport function useCapnWebRoot<Root extends CapnWebRoot>(): Root | undefined {\n  const connection = useContext(CapnWebContext);\n  if (connection === undefined) {\n    throw new Error(\"useCapnWebRoot must be rendered under <CapnWebProvider>.\");\n  }\n  return connection.root as Root | undefined;\n}\n\ntype LiveStateOptions<Root extends CapnWebRoot> = {\n  enabled?: boolean;\n  makeConnection?: MakeCapnWebConnection<Root>;\n  root?: Root | null;\n};\n\n/** Resolve provider, owned connection, or borrowed root with one logical scope. */\nfunction useLiveStateConnection<Root extends CapnWebRoot>(options?: LiveStateOptions<Root>) {\n  const provider = useContext(CapnWebContext);\n  const hasRootOverride = options !== undefined && Object.hasOwn(options, \"root\");\n  const connectionFactory = hasRootOverride ? undefined : options?.makeConnection;\n  const owned = useCapnWebConnection(\n    connectionFactory,\n    !hasRootOverride && (options?.enabled ?? true),\n  );\n  if (!hasRootOverride && !connectionFactory && !provider) {\n    throw new Error(\n      \"useLiveState needs <CapnWebProvider>, a makeConnection option, or an explicit { root } override.\",\n    );\n  }\n  const connection = hasRootOverride ? undefined : connectionFactory ? owned : provider;\n  const root = (hasRootOverride ? options.root : connection?.root) ?? undefined;\n  const scope = hasRootOverride ? root : (connectionFactory ?? connection?.scope);\n  return { connection, root, scope };\n}\n\n/**\n * Render a selected slice of any LiveStateRpc reachable from the provider root.\n * Pass `{ root }` to borrow an explicit root instead; borrowed roots are never\n * disposed or reconnected by this hook.\n */\nexport function useLiveState<Root extends CapnWebRoot, State, Selected = State>(\n  live: (root: Root) => LiveStateRpc<State>,\n  selector: (state: State) => Selected = (state) => state as unknown as Selected,\n  deps: unknown[] = [],\n  options?: LiveStateOptions<Root>,\n): {\n  error?: string;\n  refresh: () => void;\n  status: LiveStateStatus;\n  value: Selected | undefined;\n} {\n  const { connection, root, scope } = useLiveStateConnection(options);\n  const enabled = options?.enabled ?? true;\n  const [epoch, setEpoch] = useState(0);\n  const liveRef = useRef(live);\n  const selectorRef = useRef(selector);\n  useEffect(() => {\n    liveRef.current = live;\n    selectorRef.current = selector;\n  });\n\n  // A different provider/factory, explicit borrowed root, or logical node gets\n  // an empty store synchronously. A new transport generation within the same\n  // connection scope keeps the last value visible while it re-subscribes.\n  // oxlint-disable-next-line react-hooks/exhaustive-deps -- this memo is intentionally keyed; deps complete the caller's logical-node identity\n  const store = useMemo(() => createLiveStateStore<State>(), [scope, ...deps]);\n  // oxlint-disable-next-line react-hooks/exhaustive-deps -- store is the logical subscription identity; its replacement must reset the retry budget\n  const subscribeRetries = useMemo(() => ({ count: 0, resyncs: 0 }), [store]);\n  const refresh = useCallback(() => {\n    subscribeRetries.count = 0;\n    subscribeRetries.resyncs = 0;\n    setEpoch((current) => current + 1);\n  }, [subscribeRetries]);\n  const [subscriptionState, setSubscriptionState] = useState<{\n    error?: string;\n    epoch: number;\n    generation: number | undefined;\n    status: LiveStateStatus;\n    store: typeof store;\n  }>({ epoch, generation: connection?.generation, status: \"connecting\", store });\n\n  // react-doctor-disable-next-line effect-needs-cleanup -- the unconditional cleanup below owns subscribe/retry/ping timers and the subscription handle\n  useEffect(() => {\n    let disposed = false;\n    let stale = false;\n    let handle: LiveStateSubscriptionHandle | undefined;\n    let pingTimeout: ReturnType<typeof setTimeout> | undefined;\n    let retry: ReturnType<typeof setTimeout> | undefined;\n    let timeout: ReturnType<typeof setTimeout> | undefined;\n    let watchdog: ReturnType<typeof setInterval> | undefined;\n    const release = () => {\n      stale = true;\n      if (handle === undefined) return;\n      releaseLiveStateSubscription(handle);\n      handle = undefined;\n    };\n    setSubscriptionState({\n      epoch,\n      generation: connection?.generation,\n      status: \"connecting\",\n      store,\n    });\n    if (enabled && root !== undefined) {\n      const report = (cause: unknown, shouldRetry = false) => {\n        if (disposed || stale) return;\n        release();\n        setSubscriptionState({\n          error: cause instanceof Error ? cause.message : String(cause),\n          epoch,\n          generation: connection?.generation,\n          status: \"error\",\n          store,\n        });\n        if (shouldRetry && subscribeRetries.count < MAX_SUBSCRIBE_RETRIES) {\n          subscribeRetries.count += 1;\n          retry = setTimeout(() => setEpoch((current) => current + 1), SUBSCRIBE_RETRY_MS);\n        }\n      };\n\n      // The context erases its root parameter; this hook's provider/factory/root\n      // inputs are the only sources, so restoring the caller's Root is safe.\n      try {\n        const pending = liveRef.current(root as Root).subscribe(\n          (update) => {\n            if (disposed || stale) return;\n            try {\n              store.apply(update, () => {\n                throw new Error(\"Live-state revision gap\");\n              });\n              if (!isLiveStateSnapshot(update)) subscribeRetries.resyncs = 0;\n            } catch (error) {\n              // A successful subscribe alone cannot reset this budget: a host\n              // could repeatedly seed a valid snapshot followed by a bad patch.\n              const shouldResync = subscribeRetries.resyncs < MAX_SUBSCRIBE_RETRIES;\n              if (shouldResync) subscribeRetries.resyncs += 1;\n              report(error, shouldResync);\n            }\n          },\n          { patchVersion: 3 },\n        );\n        timeout = setTimeout(\n          () =>\n            report(\n              new Error(`live-state subscription timed out after ${SUBSCRIBE_TIMEOUT_MS}ms`),\n              true,\n            ),\n          SUBSCRIBE_TIMEOUT_MS,\n        );\n        void Promise.resolve(pending).then(\n          (subscription) => {\n            clearTimeout(timeout);\n            if (disposed || stale) {\n              releaseLiveStateSubscription(subscription);\n              return;\n            }\n            handle = subscription;\n            subscribeRetries.count = 0;\n            setSubscriptionState({\n              epoch,\n              generation: connection?.generation,\n              status: \"live\",\n              store,\n            });\n            watchdog = setInterval(() => {\n              if (handle === undefined) return;\n              void Promise.race([\n                Promise.resolve(handle.ping()),\n                new Promise<boolean>((resolve) => {\n                  pingTimeout = setTimeout(() => resolve(false), PING_TIMEOUT_MS);\n                }),\n              ])\n                .then(\n                  (alive) => {\n                    if (!disposed && !alive) refresh();\n                  },\n                  (cause: unknown) => report(cause, true),\n                )\n                .finally(() => clearTimeout(pingTimeout));\n            }, PING_INTERVAL_MS);\n          },\n          (cause: unknown) => {\n            clearTimeout(timeout);\n            report(cause, true);\n          },\n        );\n      } catch (cause) {\n        report(cause, true);\n      }\n    }\n\n    return () => {\n      disposed = true;\n      clearTimeout(pingTimeout);\n      clearTimeout(timeout);\n      clearTimeout(retry);\n      clearInterval(watchdog);\n      release();\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps -- deps define the caller's logical node\n  }, [connection?.generation, enabled, epoch, root, store, ...deps]);\n\n  const selected = useRef<{ state: State | undefined; value: Selected | undefined }>({\n    state: undefined,\n    value: undefined,\n  });\n  const getSelected = () => {\n    const state = store.getState();\n    if (Object.is(selected.current.state, state)) return selected.current.value;\n    const value = state === undefined ? undefined : selectorRef.current(state);\n    selected.current = { state, value };\n    return value;\n  };\n  const value = useSyncExternalStore(store.subscribe, getSelected, () => undefined);\n  const providerError = connection?.status === \"error\" ? connection.error : undefined;\n  const activeSubscriptionState =\n    subscriptionState.store === store &&\n    subscriptionState.epoch === epoch &&\n    subscriptionState.generation === connection?.generation\n      ? subscriptionState\n      : {\n          epoch,\n          generation: connection?.generation,\n          status: \"connecting\" as const,\n          store,\n        };\n  const connectionIsConnecting = connection?.status === \"connecting\";\n  return {\n    error:\n      providerError ??\n      (connectionIsConnecting || !enabled ? undefined : activeSubscriptionState.error),\n    refresh: connection?.status === \"error\" ? connection.reconnect : refresh,\n    status:\n      providerError !== undefined\n        ? \"error\"\n        : connectionIsConnecting || !enabled\n          ? \"connecting\"\n          : activeSubscriptionState.status,\n    value,\n  };\n}\n"],"mappings":"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"}

package/dist/sdk/capnweb.mjs

@@ -0,0 +1,4 @@
+import { a as isThenable, i as disposeIgnoredRpcResult, n as LiveStateSubscriptionRpcTarget, o as retainCallback, r as LiveState, t as LiveStateRpcTarget } from "../live-state-BJNqOwFw.mjs";
+import { a as compactPatch, i as applyCompactPatch, n as liveStateRevision, o as applyPatch, r as createLiveStateStore, s as diff, t as isLiveStateSnapshot } from "../protocol-DnK_f2m6.mjs";
+export * from "@iterate-com/capnweb";
+export { LiveState, LiveStateRpcTarget, LiveStateSubscriptionRpcTarget, applyCompactPatch, applyPatch, compactPatch, createLiveStateStore, diff, disposeIgnoredRpcResult, isLiveStateSnapshot, isThenable, liveStateRevision, retainCallback };

package/dist/sdk/itx/react.d.ts

@@ -0,0 +1,191 @@
+/**
+ * `iterate/sdk/itx/react` — hooks over the framework-free session keeper in
+ * ../../itx/itx-session.ts (one WebSocket per tab, generations, invisible
+ * reconnect — the session model lives there) plus TanStack Query for reads.
+ *
+ * Renderer-agnostic on purpose: nothing here touches the DOM, so the same
+ * hooks run under react-dom (the OS dashboard), @opentui/react (the chat TUI),
+ * and React Native — TanStack Query itself only uses React primitives. The
+ * browser-specific pieces (cookie auth, window-derived URL, visibility/online
+ * wake probes) live in the keeper behind runtime guards; non-browser apps
+ * point the keeper at a deployment with `configureIterateSession`.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * THE PRIMITIVES
+ * ───────────────────────────────────────────────────────────────────────────
+ *
+ *   SESSION (the catalog authenticate() returned)
+ *     useIterateSession()            in render; suspends once on first connect
+ *     connectIterateSession()        imperative (handlers/closures); a Promise
+ *
+ *   ITX (a project capability handle — session.projects.get(slug))
+ *     useItx(slug?)           in render; slug (or prj_ id) from the arg or <ProjectScope>
+ *     connectItx(slug)        imperative; a Promise
+ *
+ *   READ ONCE   useItxQuery({ key, query })              project read; SUSPENDS
+ *               useIterateSessionQuery({ key, query })   session read; NON-suspending (shell)
+ *   LIVE STATE  useLiveState((itx) => itx.liveState, selector)  project snapshot + diffs
+ *               useIterateSessionLiveState(...)                 session snapshot + diffs
+ *   CONNECT     useStreamConnection((itx) => handle, deps)  raw event batches (escape hatch)
+ *   MOUNT       <ProjectScope slug>   ambient project + reconnectable Cap'n Web provider
+ *
+ *   ACTIONS (mutations) — imperative on the handle, no extra primitive:
+ *     const itx = useItx();
+ *     <button onClick={() => itx.chat.sendMessage(text)} />
+ *
+ * RECONNECT, AS REACT SEES IT: components read an immutable Snapshot via
+ * `useSyncExternalStore`; `snapshot.session` holds the LAST live session and is
+ * kept across a transport gap. So `useIterateSession()` suspends exactly once —
+ * first load, on the stable first-connect promise — and never again: when the
+ * socket dies we keep showing the last session while a fresh generation connects
+ * in the background, then swap when it establishes. TanStack keeps cached read
+ * data through a reconnect (no re-suspend, no spinner); only an in-flight read
+ * retries, on the transport-only policy — see useItxQuery. A stray action fired
+ * during the sub-second gap rides the dead stub and rejects — the one accepted
+ * edge.
+ *
+ * CONNECTING THROWS ON THE SERVER (never SSRs): a forever-pending `use()`
+ * during streaming SSR would hang the response. Render itx consumers under an
+ * `ssr: false` route or `<ClientOnly>` + `<Suspense>`.
+ */
+import { type ReactNode } from "react";
+import { type QueryKey, type UseQueryResult } from "@tanstack/react-query";
+import type { LiveStateRpc } from "../../itx-api.generated.ts";
+import { type LiveStateStatus } from "../capnweb/react.tsx";
+import { type ItxRecoverableConnectionHandle, type ProjectStub, type SessionStub } from "../../itx/itx-session.ts";
+export { configureIterateSession, connectIterateSession, connectItx, disconnectIterateSession, isItxTransportError, reconnectIterateSession, retryFailedIterateSession, reportTransportSuspicion, type Itx, type ItxRecoverableConnectionHandle, type IterateSessionConfig, type ProjectStub, type SessionStub, } from "../../itx/itx-session.ts";
+export { createIterateQueryClient } from "../../itx/query-client.ts";
+export type * from "../../itx-api.generated.ts";
+/**
+ * The Session — the catalog `authenticate()` returned (`projects.list/create`,
+ * admin `streams`). Suspends exactly ONCE, on first connect; a later reconnect
+ * keeps returning the last session (no re-suspend — see module header).
+ */
+export declare function useIterateSession(): SessionStub;
+/**
+ * The project itx for `slug` — `session.projects.get(slug)`, the real capnweb
+ * stub. `slug` comes from the argument or the nearest <ProjectScope>; an
+ * explicit argument wins. The returned stub's identity is stable within a socket
+ * and changes once per reconnect (which re-runs effects/memos keyed on it).
+ *
+ *   const itx = useItx();               // ambient project (under <ProjectScope>)
+ *   const itx = useItx("other-slug");   // a specific project
+ *   const onSend = () => itx.chat.sendMessage(text);
+ */
+export declare function useItx(explicitSlug?: string): ProjectStub;
+/**
+ * Set the ambient project for a subtree and provide its reconnectable Cap'n Web
+ * root. The project-specific layer is deliberately only a connection factory;
+ * live-state ownership and recovery live in `iterate/sdk/capnweb/react`.
+ *
+ * The provider dials in an effect, never during render, so this context remains
+ * safe to render on the server. The duplicate belongs to the provider; the
+ * lower-level session keeper keeps owning and reconnecting the shared socket
+ * beneath it.
+ */
+export declare function ProjectScope({ slug, children }: {
+    slug: string;
+    children?: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<string | undefined>>;
+/**
+ * Read once through a project itx, suspending until it resolves. A thin adapter
+ * over TanStack Query's `useSuspenseQuery`. `key` (prefixed with "itx"
+ * internally) is the cache key — it must encode what the result is scoped to,
+ * INCLUDING the project, so two projects' data can't collide: a per-project read
+ * keys by the project, e.g. `["repo-files", projectId, repoPath]`. (The ambient
+ * slug drives the CONNECTION, not the key — so a mutation invalidates with the
+ * same `["itx", ...key]` it was written under.)
+ *
+ *   const files = useItxQuery({
+ *     key: ["repo-files", projectId, repoPath],
+ *     query: (itx) => itx.repos.get(repoPath).listFiles(),
+ *   });
+ *
+ * The connection is resolved PER FETCH (never a render-captured stub — that
+ * would pin a dead socket after a reconnect), and the per-fetch project stub is
+ * disposed once the read resolves. A resolved query keeps its cached data across
+ * a reconnect (no re-suspend, no spinner); only an in-flight read retries, on a
+ * finite transport-only policy. Errors with no cached data throw to the nearest
+ * error boundary; refetch after a mutation with
+ * `queryClient.invalidateQueries({ queryKey: ["itx", ...key] })`.
+ */
+export declare function useItxQuery<T>({ key, query, }: {
+    key: QueryKey;
+    query: (itx: ProjectStub) => Promise<T>;
+}): T;
+/**
+ * Read once through the SESSION (the catalog — `projects.list`, admin `streams`),
+ * the session-scoped sibling of {@link useItxQuery}. NON-suspending: session
+ * reads live in the always-mounted shell (sidebar, ⌘K, admin) which must not
+ * suspend on the socket, so this returns the full TanStack result (`data`,
+ * `isPending`, …) and accepts the usual options (`enabled`, `staleTime`). Same
+ * `["itx", ...key]` namespace and the same transport-only retry as useItxQuery,
+ * resolved per fetch (never a render-captured session stub).
+ *
+ *   const { data } = useIterateSessionQuery({ key: ["projects"], query: (s) => s.projects.list() });
+ */
+export declare function useIterateSessionQuery<T>({ key, query, enabled, staleTime, }: {
+    key: QueryKey;
+    query: (session: SessionStub) => Promise<T>;
+    enabled?: boolean;
+    staleTime?: number;
+}): UseQueryResult<T>;
+export type ItxConnectionStatus = LiveStateStatus;
+/**
+ * Hold one raw stream callback connection for the component's lifetime.
+ * Reconnects, silent connection death, and transport-failed open attempts recover
+ * through the shared watchdog; permanent failures remain in `"error"` until
+ * `refresh()` or a reconnect. Reopening replays the first push, so callbacks
+ * must be replay-tolerant. Teardown closes and disposes the handle.
+ *
+ * `enabled: false` is inert; `deps` reopen on change. `opts.slug` targets
+ * a project outside the ambient {@link ProjectScope} without suspending.
+ */
+export declare function useStreamConnection(open: (itx: ProjectStub) => Promise<ItxRecoverableConnectionHandle>, deps: unknown[], opts?: {
+    enabled?: boolean;
+    slug?: string;
+}): {
+    status: ItxConnectionStatus;
+    error?: string;
+    refresh: () => void;
+};
+/**
+ * THE live-state primitive: subscribe to any `.liveState` node, render the slice
+ * you pick. The server pushes a snapshot then minimal diffs; this hook
+ * reassembles them and hands back `selector(state)`.
+ *
+ *   const streams = useLiveState((itx) => itx.liveState, (s) => s.streamsIndex);
+ *
+ * THE SELECTOR CONTRACT — a pure function of the state, nothing else:
+ * - Return a STABLE slice (`s => s.rows`), not a fresh object; map downstream.
+ * - Do NOT close over props/state (`s => s.rows[props.id]`): selection is cached
+ *   by STATE identity, so a closure-captured value going stale is invisible until
+ *   the next push. Select the broader slice and index in render, or route the
+ *   changing input through `deps`.
+ *
+ * `value` is `undefined` between mount and the first snapshot (one round trip);
+ * render a loading row for that window. It never suspends — a reconnect keeps the
+ * last value while the subscription silently re-establishes. `deps` (or a changed
+ * `opts.slug`) re-point the hook at a different node, and the held value drops to
+ * `undefined` immediately — the previous node's state is never shown against the
+ * new one. To read a DIFFERENT project's live state from OUTSIDE its scope (⌘K in
+ * the app shell), pass `opts.slug`.
+ */
+export declare function useLiveState<State, Selected = State>(live: (itx: ProjectStub) => LiveStateRpc<State>, selector: (state: State) => Selected, deps?: unknown[], opts?: {
+    slug?: string;
+    enabled?: boolean;
+}): {
+    value: Selected | undefined;
+    status: ItxConnectionStatus;
+    error?: string;
+    refresh: () => void;
+};
+/** Session-scoped sibling of {@link useLiveState}, for deployment-wide live nodes. */
+export declare function useIterateSessionLiveState<State, Selected = State>(live: (session: SessionStub) => LiveStateRpc<State>, selector: (state: State) => Selected, deps?: unknown[], opts?: {
+    enabled?: boolean;
+}): {
+    value: Selected | undefined;
+    status: ItxConnectionStatus;
+    error?: string;
+    refresh: () => void;
+};