iterate 0.2.6 → 0.3.0

package/dist/protocol-DnK_f2m6.mjs

@@ -0,0 +1,251 @@
+//#region src/sdk/capnweb/live-state/diff.ts
+/**
+* Structural diff between two JSON values, producing the minimal `LiveStatePatch`
+* — or `undefined` when nothing changed.
+*
+* The diff is REFERENCE-FIRST: identical references short-circuit immediately
+* (`Object.is`), so the cost is O(changed), not O(size) — *as long as callers
+* update state immutably* (unchanged sub-objects keep their identity). That one
+* discipline is the whole performance story: a single touched row in a
+* thousand-entry index yields one tiny patch instead of a full rescan.
+*
+* PLAIN objects (prototype `Object.prototype` or `null`) are treated as keyed
+* maps and diffed per key. Dense arrays are diffed by position. Everything
+* else — primitives, `null`, sparse arrays, and
+* non-plain instances like `Date`/`Map`/`Set` — is a leaf, replaced wholesale.
+* Descending into an instance would diff its own enumerable keys, which for a
+* `Date` is NONE — two different Dates would read as "unchanged" and the
+* subscriber would stay stale forever. Keyed objects remain preferable for
+* collections whose entries frequently move; positional patches do not infer moves.
+*/
+function diff(prev, next, options = {}) {
+	if (Object.is(prev, next)) return void 0;
+	if (Array.isArray(prev) && Array.isArray(next) && options.arrays !== false) {
+		const items = [];
+		for (let index = 0; index < next.length; index++) {
+			if (!Object.hasOwn(next, index) || index < prev.length && !Object.hasOwn(prev, index)) return { set: next };
+			const patch = index < prev.length ? diff(prev[index], next[index], options) : { set: next[index] };
+			if (patch) items.push([index, patch]);
+		}
+		return items.length > 0 || prev.length !== next.length ? { array: {
+			length: next.length,
+			items
+		} } : void 0;
+	}
+	if (!isPlainObject(prev) || !isPlainObject(next)) return { set: next };
+	const fields = [];
+	const drop = [];
+	for (const key of Object.keys(next)) {
+		if (next[key] === void 0) {
+			if (Object.hasOwn(prev, key)) drop.push(key);
+			continue;
+		}
+		const childPatch = diff(Object.hasOwn(prev, key) ? prev[key] : void 0, next[key], options);
+		if (childPatch !== void 0) fields.push([key, childPatch]);
+	}
+	for (const key of Object.keys(prev)) if (!Object.hasOwn(next, key)) drop.push(key);
+	if (fields.length === 0 && drop.length === 0) return void 0;
+	const patch = {};
+	if (fields.length > 0) patch.fields = Object.fromEntries(fields);
+	if (drop.length > 0) patch.drop = drop;
+	return patch;
+}
+/**
+* Apply a `LiveStatePatch` to a previous value, returning the next value.
+*
+* Like `diff`, this preserves structural sharing: a fresh object is built only
+* along changed paths, so untouched branches keep their previous reference.
+* That's what lets a client selector (`s => s.streamsIndex`) skip re-rendering
+* when an unrelated slice changed — the slice it reads stays `Object.is`-equal
+* across applies.
+*/
+function applyPatch(prev, patch) {
+	if ("set" in patch) return patch.set;
+	if ("array" in patch) {
+		if (!Array.isArray(prev)) throw new Error("Live-state array patch requires an array baseline");
+		const next = prev.slice(0, patch.array.length);
+		next.length = patch.array.length;
+		for (const [index, child] of patch.array.items) {
+			if (!Number.isSafeInteger(index) || index < 0 || index >= next.length) throw new Error("Live-state array patch index is outside its resulting length");
+			next[index] = applyPatch(prev[index], child);
+		}
+		return next;
+	}
+	const base = isPlainObject(prev) ? prev : {};
+	const next = { ...base };
+	if (patch.fields) for (const [key, childPatch] of Object.entries(patch.fields)) Object.defineProperty(next, key, {
+		value: applyPatch(Object.hasOwn(base, key) ? base[key] : void 0, childPatch),
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+	if (patch.drop) for (const key of patch.drop) delete next[key];
+	return next;
+}
+/**
+* A PLAIN object — prototype `Object.prototype` or `null` — the only thing
+* `diff` descends into and `applyPatch` merges over. Arrays and class instances
+* (`Date`, `Map`, `Set`, …) fail this on purpose: they carry state outside
+* their own enumerable keys, so per-key diffing would misread them (see the
+* `diff` docstring) — they are leaves, replaced wholesale.
+*/
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+//#endregion
+//#region src/sdk/capnweb/live-state/compact.ts
+const fieldAddresses = /* @__PURE__ */ new WeakMap();
+function addresses(value) {
+	let cached = fieldAddresses.get(value);
+	if (!cached) {
+		const keys = Object.keys(value).filter((key) => value[key] !== void 0).sort();
+		cached = {
+			keys,
+			indices: new Map(keys.map((key, index) => [key, index]))
+		};
+		fieldAddresses.set(value, cached);
+	}
+	return cached;
+}
+/** Encode only the changed paths of an existing structural diff. */
+function compactPatch(previous, patch) {
+	if ("set" in patch) {
+		const next = patch.set;
+		if (typeof previous === "string" && typeof next === "string" && previous.length >= 16 && previous.length <= 4096 && next.length > previous.length && next.startsWith(previous)) return [previous.length, next.slice(previous.length)];
+		if (next === null || typeof next === "string" || typeof next === "number" || typeof next === "boolean") return next;
+		return [next];
+	}
+	if ("array" in patch) {
+		if (!Array.isArray(previous)) throw new Error("Live-state array patch requires an array baseline");
+		const result = {};
+		if (patch.array.length !== previous.length) result["#"] = patch.array.length;
+		for (const [index, child] of patch.array.items) result[index] = compactPatch(previous[index], child);
+		return result;
+	}
+	if (!isPlainObject(previous)) throw new Error("Live-state object patch requires an object baseline");
+	const { indices } = addresses(previous);
+	const fields = [];
+	for (const [key, child] of Object.entries(patch.fields || {})) {
+		const index = indices.get(key);
+		fields.push([index === void 0 ? `+${key}` : String(index), compactPatch(index === void 0 ? void 0 : previous[key], child)]);
+	}
+	for (const key of patch.drop || []) {
+		const index = indices.get(key);
+		if (index !== void 0) fields.push([String(index), []]);
+	}
+	return Object.fromEntries(fields);
+}
+/** Apply a version 3 patch, retaining every untouched object's identity. */
+function applyCompactPatch(previous, patch) {
+	return applyCompactValue(previous, patch);
+}
+function applyCompactValue(previous, patch) {
+	if (patch === null || typeof patch !== "object") return patch;
+	if (Array.isArray(patch)) {
+		if (patch.length === 1) return patch[0];
+		if (patch.length !== 2 || typeof previous !== "string" || previous.length !== patch[0]) throw new Error("Live-state append does not match its string baseline");
+		return previous + patch[1];
+	}
+	if (Array.isArray(previous)) {
+		const length = Object.hasOwn(patch, "#") ? patch["#"] : previous.length;
+		if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0 || length > 4294967295) throw new Error("Live-state array patch has an invalid length");
+		const next = previous.slice(0, length);
+		next.length = length;
+		for (const [address, child] of Object.entries(patch)) {
+			if (address === "#") continue;
+			const index = position(address, length);
+			next[index] = applyCompactValue(previous[index], child);
+		}
+		return next;
+	}
+	if (!isPlainObject(previous)) throw new Error("Live-state object patch requires an object baseline");
+	const { keys } = addresses(previous);
+	const next = { ...previous };
+	for (const [address, child] of Object.entries(patch)) {
+		const added = address.startsWith("+");
+		const key = added ? address.slice(1) : keys[position(address, keys.length)];
+		if (added && Object.hasOwn(previous, key) && previous[key] !== void 0) throw new Error("Live-state new field already exists in its baseline");
+		if (Array.isArray(child) && child.length === 0) {
+			if (added) throw new Error("Live-state cannot delete a new field");
+			delete next[key];
+		} else Object.defineProperty(next, key, {
+			value: applyCompactValue(added ? void 0 : previous[key], child),
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+	}
+	return next;
+}
+function position(address, length) {
+	const index = Number(address);
+	if (!Number.isSafeInteger(index) || index < 0 || index >= length || String(index) !== address) throw new Error("Live-state field address is outside its baseline");
+	return index;
+}
+//#endregion
+//#region src/sdk/capnweb/live-state/store.ts
+function createLiveStateStore() {
+	let held = {
+		revision: -1,
+		state: void 0
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const notify = () => listeners.forEach((listener) => listener());
+	return {
+		getState: () => held.state,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => void listeners.delete(listener);
+		},
+		reset: () => {
+			held = {
+				revision: -1,
+				state: void 0
+			};
+			notify();
+		},
+		apply: (update, resync) => {
+			if ("s" in update) held = {
+				revision: update.s[0],
+				state: update.s[1]
+			};
+			else if ("p" in update) {
+				if (update.p[0] !== held.revision) {
+					resync();
+					return;
+				}
+				held = {
+					revision: update.p[1],
+					state: applyCompactPatch(held.state, update.p[2])
+				};
+			} else if (update.type === "snapshot") held = {
+				revision: update.revision,
+				state: update.state
+			};
+			else if (update.from !== held.revision) {
+				resync();
+				return;
+			} else held = {
+				revision: update.to,
+				state: applyPatch(held.state, update.patch)
+			};
+			notify();
+		}
+	};
+}
+//#endregion
+//#region src/sdk/capnweb/live-state/protocol.ts
+function isLiveStateSnapshot(update) {
+	return "s" in update || "type" in update && update.type === "snapshot";
+}
+function liveStateRevision(update) {
+	if ("s" in update) return update.s[0];
+	if ("p" in update) return update.p[1];
+	return update.type === "snapshot" ? update.revision : update.to;
+}
+//#endregion
+export { compactPatch as a, applyCompactPatch as i, liveStateRevision as n, applyPatch as o, createLiveStateStore as r, diff as s, isLiveStateSnapshot as t };
+
+//# sourceMappingURL=protocol-DnK_f2m6.mjs.map

package/dist/protocol-DnK_f2m6.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-DnK_f2m6.mjs","names":[],"sources":["../src/sdk/capnweb/live-state/diff.ts","../src/sdk/capnweb/live-state/compact.ts","../src/sdk/capnweb/live-state/store.ts","../src/sdk/capnweb/live-state/protocol.ts"],"sourcesContent":["import type { LiveStatePatch } from \"./protocol.ts\";\n\n/**\n * Structural diff between two JSON values, producing the minimal `LiveStatePatch`\n * — or `undefined` when nothing changed.\n *\n * The diff is REFERENCE-FIRST: identical references short-circuit immediately\n * (`Object.is`), so the cost is O(changed), not O(size) — *as long as callers\n * update state immutably* (unchanged sub-objects keep their identity). That one\n * discipline is the whole performance story: a single touched row in a\n * thousand-entry index yields one tiny patch instead of a full rescan.\n *\n * PLAIN objects (prototype `Object.prototype` or `null`) are treated as keyed\n * maps and diffed per key. Dense arrays are diffed by position. Everything\n * else — primitives, `null`, sparse arrays, and\n * non-plain instances like `Date`/`Map`/`Set` — is a leaf, replaced wholesale.\n * Descending into an instance would diff its own enumerable keys, which for a\n * `Date` is NONE — two different Dates would read as \"unchanged\" and the\n * subscriber would stay stale forever. Keyed objects remain preferable for\n * collections whose entries frequently move; positional patches do not infer moves.\n */\nexport function diff(\n  prev: unknown,\n  next: unknown,\n  options: { arrays?: boolean } = {},\n): LiveStatePatch | undefined {\n  if (Object.is(prev, next)) return undefined;\n  if (Array.isArray(prev) && Array.isArray(next) && options.arrays !== false) {\n    const items: [number, LiveStatePatch][] = [];\n    for (let index = 0; index < next.length; index++) {\n      // Sparse arrays retain the replacement semantics of their wire value.\n      if (!Object.hasOwn(next, index) || (index < prev.length && !Object.hasOwn(prev, index))) {\n        return { set: next };\n      }\n      const patch =\n        index < prev.length ? diff(prev[index], next[index], options) : { set: next[index] };\n      if (patch) items.push([index, patch]);\n    }\n    return items.length > 0 || prev.length !== next.length\n      ? { array: { length: next.length, items } }\n      : undefined;\n  }\n  if (!isPlainObject(prev) || !isPlainObject(next)) return { set: next };\n\n  // Entries + fromEntries, not `bag[key] = …`: assignment with key \"__proto__\"\n  // would SET THE BAG'S PROTOTYPE instead of recording the field — the change\n  // would silently vanish from the patch. `Object.fromEntries` DEFINES own\n  // properties (safe for any key) and yields an ordinary Object.prototype\n  // object — which matters, because patches cross capnweb, whose serializer\n  // accepts exactly Object.prototype (a null-proto bag reads as unsupported\n  // and kills the push). (applyPatch has the mirror-image write guard.)\n  // Own-property checks throughout (`Object.hasOwn`, not `in` / bare reads):\n  // `\"__proto__\" in x` is true for EVERY object via inheritance, so `in` would\n  // misread that key's presence in both directions.\n  const fields: [string, LiveStatePatch][] = [];\n  const drop: string[] = [];\n  for (const key of Object.keys(next)) {\n    if (next[key] === undefined) {\n      if (Object.hasOwn(prev, key)) drop.push(key); // a key set to `undefined` reads as removed\n      continue;\n    }\n    const childPatch = diff(Object.hasOwn(prev, key) ? prev[key] : undefined, next[key], options);\n    if (childPatch !== undefined) fields.push([key, childPatch]);\n  }\n  for (const key of Object.keys(prev)) {\n    if (!Object.hasOwn(next, key)) drop.push(key);\n  }\n\n  if (fields.length === 0 && drop.length === 0) return undefined;\n  const patch: { fields?: Record<string, LiveStatePatch>; drop?: string[] } = {};\n  if (fields.length > 0) patch.fields = Object.fromEntries(fields);\n  if (drop.length > 0) patch.drop = drop;\n  return patch;\n}\n\n/**\n * Apply a `LiveStatePatch` to a previous value, returning the next value.\n *\n * Like `diff`, this preserves structural sharing: a fresh object is built only\n * along changed paths, so untouched branches keep their previous reference.\n * That's what lets a client selector (`s => s.streamsIndex`) skip re-rendering\n * when an unrelated slice changed — the slice it reads stays `Object.is`-equal\n * across applies.\n */\nexport function applyPatch<State>(prev: State, patch: LiveStatePatch): State {\n  if (\"set\" in patch) return patch.set as State;\n  if (\"array\" in patch) {\n    if (!Array.isArray(prev)) throw new Error(\"Live-state array patch requires an array baseline\");\n    const next = prev.slice(0, patch.array.length);\n    next.length = patch.array.length;\n    for (const [index, child] of patch.array.items) {\n      if (!Number.isSafeInteger(index) || index < 0 || index >= next.length) {\n        throw new Error(\"Live-state array patch index is outside its resulting length\");\n      }\n      next[index] = applyPatch(prev[index], child);\n    }\n    // The array operation preserves State's shape; only the generic parameter\n    // prevents TypeScript from expressing the Array.isArray narrowing on return.\n    return next as State;\n  }\n  const base: Record<string, unknown> = isPlainObject(prev) ? prev : {};\n  const next: Record<string, unknown> = { ...base };\n  if (patch.fields) {\n    for (const [key, childPatch] of Object.entries(patch.fields)) {\n      // Define, don't assign: `next[key] =` with key \"__proto__\" would SET THE\n      // PROTOTYPE instead of creating an own property — dropping the field and\n      // letting a hostile patch inject one. (The spread above is already safe:\n      // spread uses define semantics.) `Object.hasOwn` guards the read the same\n      // way — a bare `base[\"__proto__\"]` reads the prototype, not a field.\n      Object.defineProperty(next, key, {\n        value: applyPatch(Object.hasOwn(base, key) ? base[key] : undefined, childPatch),\n        enumerable: true,\n        writable: true,\n        configurable: true,\n      });\n    }\n  }\n  if (patch.drop) {\n    for (const key of patch.drop) delete next[key];\n  }\n  return next as State;\n}\n\n/**\n * A PLAIN object — prototype `Object.prototype` or `null` — the only thing\n * `diff` descends into and `applyPatch` merges over. Arrays and class instances\n * (`Date`, `Map`, `Set`, …) fail this on purpose: they carry state outside\n * their own enumerable keys, so per-key diffing would misread them (see the\n * `diff` docstring) — they are leaves, replaced wholesale.\n */\nexport function isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null) return false;\n  const proto: unknown = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n","import { isPlainObject } from \"./diff.ts\";\nimport type { CompactLiveStatePatch, LiveStatePatch } from \"./protocol.ts\";\n\nconst fieldAddresses = new WeakMap<object, { keys: string[]; indices: Map<string, number> }>();\n\nfunction addresses(value: Record<string, unknown>) {\n  let cached = fieldAddresses.get(value);\n  if (!cached) {\n    // Undefined object fields are absent after a JSON transport. They must not\n    // shift addresses on either side of the next update.\n    const keys = Object.keys(value)\n      .filter((key) => value[key] !== undefined)\n      .sort();\n    cached = { keys, indices: new Map(keys.map((key, index) => [key, index])) };\n    fieldAddresses.set(value, cached);\n  }\n  return cached;\n}\n\n/** Encode only the changed paths of an existing structural diff. */\nexport function compactPatch(previous: unknown, patch: LiveStatePatch): CompactLiveStatePatch {\n  if (\"set\" in patch) {\n    const next = patch.set;\n    if (\n      typeof previous === \"string\" &&\n      typeof next === \"string\" &&\n      previous.length >= 16 &&\n      // Bound prefix checks even for a multi-megabyte string. Immutable text\n      // blocks are ~1 KiB; larger ordinary strings retain replacement semantics.\n      previous.length <= 4096 &&\n      next.length > previous.length &&\n      next.startsWith(previous)\n    )\n      return [previous.length, next.slice(previous.length)];\n    if (\n      next === null ||\n      typeof next === \"string\" ||\n      typeof next === \"number\" ||\n      typeof next === \"boolean\"\n    )\n      return next;\n    return [next];\n  }\n  if (\"array\" in patch) {\n    if (!Array.isArray(previous))\n      throw new Error(\"Live-state array patch requires an array baseline\");\n    const result: Record<string, CompactLiveStatePatch> = {};\n    if (patch.array.length !== previous.length) result[\"#\"] = patch.array.length;\n    for (const [index, child] of patch.array.items)\n      result[index] = compactPatch(previous[index], child);\n    return result;\n  }\n  if (!isPlainObject(previous))\n    throw new Error(\"Live-state object patch requires an object baseline\");\n  const { indices } = addresses(previous);\n  const fields: [string, CompactLiveStatePatch][] = [];\n  for (const [key, child] of Object.entries(patch.fields || {})) {\n    const index = indices.get(key);\n    fields.push([\n      index === undefined ? `+${key}` : String(index),\n      compactPatch(index === undefined ? undefined : previous[key], child),\n    ]);\n  }\n  for (const key of patch.drop || []) {\n    const index = indices.get(key);\n    // An undefined field was already absent on the wire.\n    if (index !== undefined) fields.push([String(index), []]);\n  }\n  return Object.fromEntries(fields);\n}\n\n/** Apply a version 3 patch, retaining every untouched object's identity. */\nexport function applyCompactPatch<State>(previous: State, patch: CompactLiveStatePatch): State {\n  // Like applyPatch, the wire operation preserves the caller's State contract;\n  // TypeScript cannot infer that contract from a recursive, generic JSON codec.\n  return applyCompactValue(previous, patch) as State;\n}\n\nfunction applyCompactValue(previous: unknown, patch: CompactLiveStatePatch): unknown {\n  if (patch === null || typeof patch !== \"object\") return patch;\n  if (Array.isArray(patch)) {\n    if (patch.length === 1) return patch[0];\n    if (patch.length !== 2 || typeof previous !== \"string\" || previous.length !== patch[0]) {\n      throw new Error(\"Live-state append does not match its string baseline\");\n    }\n    return previous + patch[1];\n  }\n  if (Array.isArray(previous)) {\n    const length = Object.hasOwn(patch, \"#\") ? patch[\"#\"] : previous.length;\n    if (\n      typeof length !== \"number\" ||\n      !Number.isSafeInteger(length) ||\n      length < 0 ||\n      length > 0xffffffff\n    ) {\n      throw new Error(\"Live-state array patch has an invalid length\");\n    }\n    const next = previous.slice(0, length);\n    next.length = length;\n    for (const [address, child] of Object.entries(patch)) {\n      if (address === \"#\") continue;\n      const index = position(address, length);\n      next[index] = applyCompactValue(previous[index], child);\n    }\n    return next;\n  }\n  if (!isPlainObject(previous))\n    throw new Error(\"Live-state object patch requires an object baseline\");\n  const { keys } = addresses(previous);\n  const next = { ...previous };\n  for (const [address, child] of Object.entries(patch)) {\n    const added = address.startsWith(\"+\");\n    const key = added ? address.slice(1) : keys[position(address, keys.length)]!;\n    if (added && Object.hasOwn(previous, key) && previous[key] !== undefined) {\n      throw new Error(\"Live-state new field already exists in its baseline\");\n    }\n    if (Array.isArray(child) && child.length === 0) {\n      if (added) throw new Error(\"Live-state cannot delete a new field\");\n      delete next[key];\n    } else {\n      // Define own properties, including __proto__, without mutating prototypes.\n      Object.defineProperty(next, key, {\n        value: applyCompactValue(added ? undefined : previous[key], child),\n        enumerable: true,\n        writable: true,\n        configurable: true,\n      });\n    }\n  }\n  return next;\n}\n\nfunction position(address: string, length: number): number {\n  const index = Number(address);\n  if (!Number.isSafeInteger(index) || index < 0 || index >= length || String(index) !== address) {\n    throw new Error(\"Live-state field address is outside its baseline\");\n  }\n  return index;\n}\n","import { applyPatch } from \"./diff.ts\";\nimport { applyCompactPatch } from \"./compact.ts\";\nimport type { LiveUpdate } from \"./protocol.ts\";\n\n/**\n * The client half of the live-state channel: a tiny external store that folds\n * wire updates (one snapshot, then patches) back into the live value. The\n * server's `LiveState` engine is the producing half; `useLiveState` renders\n * this store via `useSyncExternalStore`.\n *\n * Revision discipline: a patch only applies when its `from` matches the held\n * revision. A mismatch means a message was missed (or arrived from a stale\n * subscription's revision line) — the store calls `resync` and holds its value\n * until the fresh snapshot lands, so a gap can never silently corrupt state.\n */\nexport type LiveStateStore<State> = {\n  getState: () => State | undefined;\n  subscribe: (listener: () => void) => () => void;\n  reset: () => void;\n  /** Fold one wire update into the held value; a revision gap means a missed patch — resync. */\n  apply: (update: LiveUpdate<State>, resync: () => void) => void;\n};\n\nexport function createLiveStateStore<State>(): LiveStateStore<State> {\n  let held: { revision: number; state: State | undefined } = { revision: -1, state: undefined };\n  const listeners = new Set<() => void>();\n  const notify = () => listeners.forEach((listener) => listener());\n  return {\n    getState: () => held.state,\n    subscribe: (listener: () => void) => {\n      listeners.add(listener);\n      return () => void listeners.delete(listener);\n    },\n    reset: () => {\n      held = { revision: -1, state: undefined };\n      notify();\n    },\n    apply: (update: LiveUpdate<State>, resync: () => void) => {\n      if (\"s\" in update) {\n        held = { revision: update.s[0], state: update.s[1] };\n      } else if (\"p\" in update) {\n        if (update.p[0] !== held.revision) {\n          resync();\n          return;\n        }\n        held = { revision: update.p[1], state: applyCompactPatch(held.state, update.p[2]) };\n      } else if (update.type === \"snapshot\") {\n        held = { revision: update.revision, state: update.state };\n      } else if (update.from !== held.revision) {\n        resync();\n        return;\n      } else {\n        held = { revision: update.to, state: applyPatch(held.state, update.patch) };\n      }\n      notify();\n    },\n  };\n}\n","/**\n * Wire types for the live-state channel: what a server engine pushes down a\n * subscription. A subscription always delivers one `snapshot` first (the full\n * current state), then a stream of `patch`es — each the minimal structural diff\n * since the previous revision. `useLiveState` reassembles these into the live\n * value, so feature code never touches these types directly.\n *\n * See `diff.ts` for how patches are produced (`diff`) and applied (`applyPatch`).\n */\n\n/**\n * A structural patch turning a previous JSON value into the next one. Three\n * shapes, discriminated by `set`, `array`, or an object patch:\n * - `{ set }` — replace this position wholesale. Used for primitives,\n *   `null`, type changes,\n *   and newly-added object keys.\n * - `{ fields?, drop? }` — descend into a plain object: `fields` maps each\n *   changed key to its own patch; `drop` lists keys that disappeared. At least\n *   one is present (an empty descend never gets emitted).\n * - `{ array }` — patch changed positions and set the resulting length. Kept\n *   elements retain their identity, including immutable text blocks inside a\n *   changed step. This form is sent only to subscribers requesting version 2.\n */\nexport type LiveStatePatch =\n  | { set: unknown }\n  | { array: { length: number; items: [number, LiveStatePatch][] } }\n  | { fields?: Record<string, LiveStatePatch>; drop?: string[] };\n\n/** Explicit codec negotiation keeps already-open clients valid across deploys. */\nexport type LiveStateSubscriptionOptions = { patchVersion?: 2 | 3 };\n\n/**\n * Version 3 addresses existing object fields by their sorted baseline position;\n * new fields use `+name`. Arrays use indices and an optional `#` length.\n * Primitives replace directly, `[value]` replaces other values, `[length, text]`\n * appends to a string, and `[]` deletes an object field. No dictionary survives\n * an update: every address refers to the acknowledged baseline of that patch.\n */\nexport type CompactLiveStatePatch =\n  | string\n  | number\n  | boolean\n  | null\n  | []\n  | [unknown]\n  | [number, string]\n  | { [address: string]: CompactLiveStatePatch };\n\n/** A transient reader's position; a new engine incarnation always has a new epoch. */\nexport type LiveStateCursor = { epoch: string; revision: number };\n\n/** A pull transports one delta, a fresh snapshot, or no change. No callback is retained. */\nexport type LiveStateRead<State> = { epoch: string; update: LiveUpdate<State> | null };\n\n/**\n * One message pushed down a live-state subscription. The first is always a\n * `snapshot` (a resync sends a fresh one); every message after carries only the\n * diff from revision `from` to `to`. Revisions are monotonic for the life of one\n * subscription, so a gap (`from` ≠ the client's revision) means a message was\n * missed and the client should resubscribe.\n *\n * `State` is asserted by the caller of `useLiveState` — the wire itself is\n * structure-agnostic.\n */\nexport type LiveUpdate<State = unknown> =\n  | { type: \"snapshot\"; revision: number; state: State }\n  | { type: \"patch\"; from: number; to: number; patch: LiveStatePatch }\n  | { s: [revision: number, state: State] }\n  | { p: [from: number, to: number, patch: CompactLiveStatePatch] };\n\nexport function isLiveStateSnapshot<State>(\n  update: LiveUpdate<State>,\n): update is Extract<LiveUpdate<State>, { type: \"snapshot\" } | { s: unknown }> {\n  return \"s\" in update || (\"type\" in update && update.type === \"snapshot\");\n}\n\nexport function liveStateRevision(update: LiveUpdate): number {\n  if (\"s\" in update) return update.s[0];\n  if (\"p\" in update) return update.p[1];\n  return update.type === \"snapshot\" ? update.revision : update.to;\n}\n"],"mappings":"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"}

package/dist/sdk/capnweb/index.d.ts

@@ -0,0 +1,2 @@
+export * from "@iterate-com/capnweb";
+export * from "./live-state/index.ts";

package/dist/sdk/capnweb/live-state/compact.d.ts

@@ -0,0 +1,5 @@
+import type { CompactLiveStatePatch, LiveStatePatch } from "./protocol.ts";
+/** Encode only the changed paths of an existing structural diff. */
+export declare function compactPatch(previous: unknown, patch: LiveStatePatch): CompactLiveStatePatch;
+/** Apply a version 3 patch, retaining every untouched object's identity. */
+export declare function applyCompactPatch<State>(previous: State, patch: CompactLiveStatePatch): State;

package/dist/sdk/capnweb/live-state/diff.d.ts

@@ -0,0 +1,41 @@
+import type { LiveStatePatch } from "./protocol.ts";
+/**
+ * Structural diff between two JSON values, producing the minimal `LiveStatePatch`
+ * — or `undefined` when nothing changed.
+ *
+ * The diff is REFERENCE-FIRST: identical references short-circuit immediately
+ * (`Object.is`), so the cost is O(changed), not O(size) — *as long as callers
+ * update state immutably* (unchanged sub-objects keep their identity). That one
+ * discipline is the whole performance story: a single touched row in a
+ * thousand-entry index yields one tiny patch instead of a full rescan.
+ *
+ * PLAIN objects (prototype `Object.prototype` or `null`) are treated as keyed
+ * maps and diffed per key. Dense arrays are diffed by position. Everything
+ * else — primitives, `null`, sparse arrays, and
+ * non-plain instances like `Date`/`Map`/`Set` — is a leaf, replaced wholesale.
+ * Descending into an instance would diff its own enumerable keys, which for a
+ * `Date` is NONE — two different Dates would read as "unchanged" and the
+ * subscriber would stay stale forever. Keyed objects remain preferable for
+ * collections whose entries frequently move; positional patches do not infer moves.
+ */
+export declare function diff(prev: unknown, next: unknown, options?: {
+    arrays?: boolean;
+}): LiveStatePatch | undefined;
+/**
+ * Apply a `LiveStatePatch` to a previous value, returning the next value.
+ *
+ * Like `diff`, this preserves structural sharing: a fresh object is built only
+ * along changed paths, so untouched branches keep their previous reference.
+ * That's what lets a client selector (`s => s.streamsIndex`) skip re-rendering
+ * when an unrelated slice changed — the slice it reads stays `Object.is`-equal
+ * across applies.
+ */
+export declare function applyPatch<State>(prev: State, patch: LiveStatePatch): State;
+/**
+ * A PLAIN object — prototype `Object.prototype` or `null` — the only thing
+ * `diff` descends into and `applyPatch` merges over. Arrays and class instances
+ * (`Date`, `Map`, `Set`, …) fail this on purpose: they carry state outside
+ * their own enumerable keys, so per-key diffing would misread them (see the
+ * `diff` docstring) — they are leaves, replaced wholesale.
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/sdk/capnweb/live-state/engine.d.ts

@@ -0,0 +1,44 @@
+import type { LiveStateCursor, LiveStateRead, LiveStateSubscriptionOptions, LiveUpdate } from "./protocol.ts";
+/** Handle returned by `LiveState.subscribe` — the ownership + liveness surface for one subscriber. */
+export type LiveStateSubscription = {
+    /** Still registered on a live engine? A dead DO incarnation also makes the call reject. */
+    ping(): boolean;
+    unsubscribe(): void;
+    [Symbol.dispose](): void;
+};
+/**
+ * A source-agnostic live store: hold a state value, and when it changes push the
+ * minimal diff to every subscriber. It does not know or care where the state
+ * comes from — a Durable Object folds events into it, a stateless RpcTarget polls
+ * a third-party API into it — so ANY RpcTarget can expose live state by holding
+ * one and returning a read-only wrapper from a `.live` getter.
+ *
+ * Two rules make it cheap and correct:
+ * - Updates are IMMUTABLE (`setState`/`assign` build a new value, never mutate),
+ *   so the diff short-circuits unchanged branches by identity — O(changed), not
+ *   O(size). See `diff.ts`.
+ * - Push work runs only while a subscriber exists. Transient readers call
+ *   `readSince` explicitly; a dormant engine schedules nothing.
+ *
+ * All subscribers share one revision line. Fast subscribers share a patch;
+ * slow subscribers receive a coalesced patch from their acknowledged state.
+ * A revision mismatch makes the client resync instead of applying stale data.
+ */
+export declare class LiveState<State extends object> {
+    #private;
+    constructor(initial: State, options?: {
+        debounceMs?: number;
+    });
+    /** The current state — reflects every `setState`/`assign`, even while dormant. */
+    getState(): State;
+    /** One retained delta bounds history while a single parent can pull incrementally.
+     * A late reader or a new incarnation receives an explicit snapshot instead. */
+    readSince(cursor?: LiveStateCursor, options?: LiveStateSubscriptionOptions): LiveStateRead<State>;
+    /** True while at least one live subscriber makes projection work observable. */
+    get observed(): boolean;
+    /** Replace the state. Build a NEW value (don't mutate) so the diff stays cheap. */
+    setState(next: State | ((prev: State) => State)): void;
+    /** Shallow-merge a partial into the state — sugar for `setState(p => ({ ...p, ...partial }))`. */
+    assign(partial: Partial<State>): void;
+    subscribe(sink: (update: LiveUpdate<State>) => unknown, options?: LiveStateSubscriptionOptions): LiveStateSubscription;
+}

package/dist/sdk/capnweb/live-state/index.d.ts

@@ -0,0 +1,41 @@
+import { RpcTarget } from "@iterate-com/capnweb";
+import type { LiveState as LiveStateEngine, LiveStateSubscription } from "./engine.ts";
+import type { LiveStateSubscriptionOptions, LiveUpdate } from "./protocol.ts";
+import type { LiveStateRpc, LiveStateSubscriptionHandle } from "./types.ts";
+type LiveStateSource<State extends object> = Pick<LiveStateEngine<State>, "getState" | "subscribe">;
+type RefreshingLiveStateSource<State extends object> = {
+    readonly live: LiveStateSource<State>;
+    loadAndRefreshLive(): void | PromiseLike<void>;
+};
+export { createLiveStateStore, type LiveStateStore } from "./store.ts";
+export { applyPatch, diff } from "./diff.ts";
+export { compactPatch, applyCompactPatch } from "./compact.ts";
+export { isLiveStateSnapshot, liveStateRevision } from "./protocol.ts";
+export type { CompactLiveStatePatch, LiveStateCursor, LiveStateRead, LiveStatePatch, LiveStateSubscriptionOptions, LiveUpdate, } from "./protocol.ts";
+export { LiveState, type LiveStateSubscription } from "./engine.ts";
+export type { LiveStateRpc, LiveStateSubscriptionHandle } from "./types.ts";
+export { disposeIgnoredRpcResult, isThenable, retainCallback, type RetainedCallback, } from "./retain.ts";
+/**
+ * Expose mutable server state as a read-only Cap'n Web capability.
+ * Pass an in-memory `LiveState`, or a stream-processor registry whose engine
+ * must hydrate before its first snapshot.
+ */
+export declare class LiveStateRpcTarget<State extends object> extends RpcTarget implements LiveStateRpc<State> {
+    #private;
+    constructor(source: LiveStateSource<State> | RefreshingLiveStateSource<State>);
+    get(): Promise<State>;
+    subscribe(onUpdate: (update: LiveUpdate<State>) => unknown, options?: LiveStateSubscriptionOptions): Promise<LiveStateSubscriptionRpcTarget>;
+}
+/**
+ * The wire handle for one subscription — `ping`/`unsubscribe` over RPC.
+ * Exported for relays that build their subscription OUTSIDE a `LiveState`
+ * engine (the worker-local liveState-socket relay) but must hand back the
+ * same handle shape `LiveStateRpcTarget.subscribe` does.
+ */
+export declare class LiveStateSubscriptionRpcTarget extends RpcTarget implements LiveStateSubscriptionHandle {
+    #private;
+    constructor(subscription: LiveStateSubscription);
+    ping(): boolean;
+    unsubscribe(): void;
+    [Symbol.dispose](): void;
+}

package/dist/sdk/capnweb/live-state/protocol.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Wire types for the live-state channel: what a server engine pushes down a
+ * subscription. A subscription always delivers one `snapshot` first (the full
+ * current state), then a stream of `patch`es — each the minimal structural diff
+ * since the previous revision. `useLiveState` reassembles these into the live
+ * value, so feature code never touches these types directly.
+ *
+ * See `diff.ts` for how patches are produced (`diff`) and applied (`applyPatch`).
+ */
+/**
+ * A structural patch turning a previous JSON value into the next one. Three
+ * shapes, discriminated by `set`, `array`, or an object patch:
+ * - `{ set }` — replace this position wholesale. Used for primitives,
+ *   `null`, type changes,
+ *   and newly-added object keys.
+ * - `{ fields?, drop? }` — descend into a plain object: `fields` maps each
+ *   changed key to its own patch; `drop` lists keys that disappeared. At least
+ *   one is present (an empty descend never gets emitted).
+ * - `{ array }` — patch changed positions and set the resulting length. Kept
+ *   elements retain their identity, including immutable text blocks inside a
+ *   changed step. This form is sent only to subscribers requesting version 2.
+ */
+export type LiveStatePatch = {
+    set: unknown;
+} | {
+    array: {
+        length: number;
+        items: [number, LiveStatePatch][];
+    };
+} | {
+    fields?: Record<string, LiveStatePatch>;
+    drop?: string[];
+};
+/** Explicit codec negotiation keeps already-open clients valid across deploys. */
+export type LiveStateSubscriptionOptions = {
+    patchVersion?: 2 | 3;
+};
+/**
+ * Version 3 addresses existing object fields by their sorted baseline position;
+ * new fields use `+name`. Arrays use indices and an optional `#` length.
+ * Primitives replace directly, `[value]` replaces other values, `[length, text]`
+ * appends to a string, and `[]` deletes an object field. No dictionary survives
+ * an update: every address refers to the acknowledged baseline of that patch.
+ */
+export type CompactLiveStatePatch = string | number | boolean | null | [] | [unknown] | [number, string] | {
+    [address: string]: CompactLiveStatePatch;
+};
+/** A transient reader's position; a new engine incarnation always has a new epoch. */
+export type LiveStateCursor = {
+    epoch: string;
+    revision: number;
+};
+/** A pull transports one delta, a fresh snapshot, or no change. No callback is retained. */
+export type LiveStateRead<State> = {
+    epoch: string;
+    update: LiveUpdate<State> | null;
+};
+/**
+ * One message pushed down a live-state subscription. The first is always a
+ * `snapshot` (a resync sends a fresh one); every message after carries only the
+ * diff from revision `from` to `to`. Revisions are monotonic for the life of one
+ * subscription, so a gap (`from` ≠ the client's revision) means a message was
+ * missed and the client should resubscribe.
+ *
+ * `State` is asserted by the caller of `useLiveState` — the wire itself is
+ * structure-agnostic.
+ */
+export type LiveUpdate<State = unknown> = {
+    type: "snapshot";
+    revision: number;
+    state: State;
+} | {
+    type: "patch";
+    from: number;
+    to: number;
+    patch: LiveStatePatch;
+} | {
+    s: [revision: number, state: State];
+} | {
+    p: [from: number, to: number, patch: CompactLiveStatePatch];
+};
+export declare function isLiveStateSnapshot<State>(update: LiveUpdate<State>): update is Extract<LiveUpdate<State>, {
+    type: "snapshot";
+} | {
+    s: unknown;
+}>;
+export declare function liveStateRevision(update: LiveUpdate): number;

package/dist/sdk/capnweb/live-state/retain.d.ts

@@ -0,0 +1,23 @@
+/** An RPC callback after retention: still callable, plus disposable and (best-effort) broken-transport aware. */
+export type RetainedCallback<Arg> = ((arg: Arg) => unknown) & Disposable & {
+    onRpcBroken?(handler: (error: unknown) => void): void;
+};
+/**
+ * Retain a single-argument RPC callback so it survives past the call that
+ * carried it. `dup()` duplicates the underlying remote stub (that dup is what
+ * `[Symbol.dispose]` releases); `onRpcBroken` is forwarded defensively — Cap'n
+ * Web stubs expose no own property descriptors and a Workers RPC property access
+ * can fabricate a pipelined method that rejects at call time, so we wire whatever
+ * the stub claims and swallow registration failures. `onRpcBroken` is only a
+ * prompt hint; callers that need a terminal verdict must model one explicitly
+ * (for example, the durable wake lane's independent settlement capability).
+ */
+export declare function retainCallback<Arg>(callback: (arg: Arg) => unknown): RetainedCallback<Arg>;
+/** Thenable probe: RPC stubs and their call results are thenable-shaped. */
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+/**
+ * Dispose the result of an RPC call whose value the caller ignores. Reading a
+ * Cap'n Web / Workers RPC method yields a disposable stub even when unused, and
+ * dropping it without disposal leaks the remote reference.
+ */
+export declare function disposeIgnoredRpcResult(result: unknown): void;

package/dist/sdk/capnweb/live-state/store.d.ts

@@ -0,0 +1,20 @@
+import type { LiveUpdate } from "./protocol.ts";
+/**
+ * The client half of the live-state channel: a tiny external store that folds
+ * wire updates (one snapshot, then patches) back into the live value. The
+ * server's `LiveState` engine is the producing half; `useLiveState` renders
+ * this store via `useSyncExternalStore`.
+ *
+ * Revision discipline: a patch only applies when its `from` matches the held
+ * revision. A mismatch means a message was missed (or arrived from a stale
+ * subscription's revision line) — the store calls `resync` and holds its value
+ * until the fresh snapshot lands, so a gap can never silently corrupt state.
+ */
+export type LiveStateStore<State> = {
+    getState: () => State | undefined;
+    subscribe: (listener: () => void) => () => void;
+    reset: () => void;
+    /** Fold one wire update into the held value; a revision gap means a missed patch — resync. */
+    apply: (update: LiveUpdate<State>, resync: () => void) => void;
+};
+export declare function createLiveStateStore<State>(): LiveStateStore<State>;

package/dist/sdk/capnweb/live-state/types.d.ts

@@ -0,0 +1,11 @@
+import type { LiveStateSubscriptionOptions, LiveUpdate } from "./protocol.ts";
+/** Owned handle for one live-state subscription. */
+export type LiveStateSubscriptionHandle = Disposable & {
+    ping(): boolean | Promise<boolean>;
+    unsubscribe(): void;
+};
+/** Read-only live value exposed across a Cap'n Web capability boundary. */
+export interface LiveStateRpc<State = unknown> {
+    get(): Promise<State>;
+    subscribe(onUpdate: (update: LiveUpdate<State>) => unknown, options?: LiveStateSubscriptionOptions): Promise<LiveStateSubscriptionHandle>;
+}

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

@@ -0,0 +1,45 @@
+import { type ReactNode } from "react";
+import type { LiveStateRpc } from "./live-state/types.ts";
+export type CapnWebRoot = object & Partial<Disposable> & {
+    onRpcBroken?(callback: (error?: unknown) => void): void;
+};
+export type MakeCapnWebConnection<Root extends CapnWebRoot> = () => Root | PromiseLike<Root>;
+export type LiveStateStatus = "connecting" | "live" | "error";
+type ConnectionSnapshot = {
+    error?: string;
+    generation: number;
+    reconnect: () => void;
+    root?: CapnWebRoot;
+    /** Stable for one connection factory, across all of that factory's reconnects. */
+    scope: object | undefined;
+    status: "connecting" | "connected" | "error";
+};
+/**
+ * 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.
+ */
+export declare function CapnWebProvider<Root extends CapnWebRoot>({ children, makeConnection, }: {
+    children?: ReactNode;
+    makeConnection: MakeCapnWebConnection<Root>;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<ConnectionSnapshot | undefined>>;
+/** The current provider root, undefined while its connection is being replaced. */
+export declare function useCapnWebRoot<Root extends CapnWebRoot>(): Root | undefined;
+type LiveStateOptions<Root extends CapnWebRoot> = {
+    enabled?: boolean;
+    makeConnection?: MakeCapnWebConnection<Root>;
+    root?: Root | null;
+};
+/**
+ * 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.
+ */
+export declare function useLiveState<Root extends CapnWebRoot, State, Selected = State>(live: (root: Root) => LiveStateRpc<State>, selector?: (state: State) => Selected, deps?: unknown[], options?: LiveStateOptions<Root>): {
+    error?: string;
+    refresh: () => void;
+    status: LiveStateStatus;
+    value: Selected | undefined;
+};
+export {};