statewire 0.0.0-0 → 0.0.2

package/dist/client/timing.js

@@ -0,0 +1,15 @@
+//#region src/client/timing.ts
+const timing = {
+	backoffBaseMs: 250,
+	backoffMaxMs: 3e4,
+	heartbeatTimeoutMs: 3e4
+};
+const backoff = (attempt) => Math.min(timing.backoffBaseMs * 2 ** (attempt - 1), timing.backoffMaxMs);
+const retryDelay = (error, attempt) => {
+	const retryAfterMs = error?.retryAfterMs;
+	return typeof retryAfterMs === "number" ? retryAfterMs : backoff(attempt);
+};
+//#endregion
+export { backoff, retryDelay, timing };
+
+//# sourceMappingURL=timing.js.map

package/dist/client/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","names":["timing","backoffBaseMs","backoffMaxMs","heartbeatTimeoutMs","backoff","attempt","Math","min","retryDelay","error","retryAfterMs"],"sources":["../../src/client/timing.ts"],"sourcesContent":["export const timing = {\n  backoffBaseMs: 250,\n  backoffMaxMs: 30_000,\n  heartbeatTimeoutMs: 30_000,\n};\n\nexport const backoff = (attempt: number) =>\n  Math.min(timing.backoffBaseMs * 2 ** (attempt - 1), timing.backoffMaxMs);\n\nexport const retryDelay = (error: unknown, attempt: number): number => {\n  const retryAfterMs = (error as { retryAfterMs?: unknown } | undefined)\n    ?.retryAfterMs;\n  return typeof retryAfterMs === \"number\" ? retryAfterMs : backoff(attempt);\n};\n"],"mappings":";AAAA,MAAaA,SAAS;CACpBC,eAAe;CACfC,cAAc;CACdC,oBAAoB;AACtB;AAEA,MAAaC,WAAWC,YACtBC,KAAKC,IAAIP,OAAOC,gBAAgB,MAAMI,UAAU,IAAIL,OAAOE,YAAY;AAEzE,MAAaM,cAAcC,OAAgBJ,YAA4B;CACrE,MAAMK,eAAgBD,OAClBC;CACJ,OAAO,OAAOA,iBAAiB,WAAWA,eAAeN,QAAQC,OAAO;AAC1E"}

package/dist/host/adapter.d.ts

@@ -0,0 +1,8 @@
+import { StatewireHostInternal } from "../host-internal.js";
+//#region src/host/adapter.d.ts
+declare const CLIENT_QUERY_PARAM = "client";
+declare const clientIdFromUrl: (url: string | null | undefined) => string;
+declare const textFrameOrClose: (socket: Pick<StatewireHostInternal.Socket, "close">, data: unknown) => string | null;
+//#endregion
+export { CLIENT_QUERY_PARAM, clientIdFromUrl, textFrameOrClose };
+//# sourceMappingURL=adapter.d.ts.map

package/dist/host/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","names":[],"sources":["../../src/host/adapter.ts"],"mappings":";;cAEa;cAEA,kBAAmB;cAqBnB,mBACX,QAAQ,KAAK,sBAAsB,kBACnC"}

package/dist/host/adapter.js

@@ -0,0 +1,23 @@
+//#region src/host/adapter.ts
+const CLIENT_QUERY_PARAM = "client";
+const clientIdFromUrl = (url) => {
+	if (!url) throw new Error("statewire: cannot resolve client id: missing url");
+	let parsed;
+	try {
+		parsed = new URL(url, "http://statewire");
+	} catch {
+		throw new Error(`statewire: cannot resolve client id: unparseable url "${url}"`);
+	}
+	const clientId = parsed.searchParams.get(CLIENT_QUERY_PARAM);
+	if (!clientId) throw new Error(`statewire: url is missing the "${CLIENT_QUERY_PARAM}" query parameter`);
+	return clientId;
+};
+const textFrameOrClose = (socket, data) => {
+	if (typeof data === "string") return data;
+	socket.close(1008, "text frames only");
+	return null;
+};
+//#endregion
+export { CLIENT_QUERY_PARAM, clientIdFromUrl, textFrameOrClose };
+
+//# sourceMappingURL=adapter.js.map

package/dist/host/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":["StatewireHostInternal","CLIENT_QUERY_PARAM","clientIdFromUrl","url","Error","parsed","URL","clientId","searchParams","get","textFrameOrClose","socket","Pick","Socket","data","close"],"sources":["../../src/host/adapter.ts"],"sourcesContent":["import type { StatewireHostInternal } from \"../host-internal\";\n\nexport const CLIENT_QUERY_PARAM = \"client\";\n\nexport const clientIdFromUrl = (url: string | null | undefined): string => {\n  if (!url) {\n    throw new Error(\"statewire: cannot resolve client id: missing url\");\n  }\n  let parsed: URL;\n  try {\n    parsed = new URL(url, \"http://statewire\");\n  } catch {\n    throw new Error(\n      `statewire: cannot resolve client id: unparseable url \"${url}\"`,\n    );\n  }\n  const clientId = parsed.searchParams.get(CLIENT_QUERY_PARAM);\n  if (!clientId) {\n    throw new Error(\n      `statewire: url is missing the \"${CLIENT_QUERY_PARAM}\" query parameter`,\n    );\n  }\n  return clientId;\n};\n\nexport const textFrameOrClose = (\n  socket: Pick<StatewireHostInternal.Socket, \"close\">,\n  data: unknown,\n): string | null => {\n  if (typeof data === \"string\") return data;\n  socket.close(1008, \"text frames only\");\n  return null;\n};\n"],"mappings":";AAEA,MAAaC,qBAAqB;AAElC,MAAaC,mBAAmBC,QAA2C;CACzE,IAAI,CAACA,KACH,MAAM,IAAIC,MAAM,kDAAkD;CAEpE,IAAIC;CACJ,IAAI;EACFA,SAAS,IAAIC,IAAIH,KAAK,kBAAkB;CAC1C,QAAQ;EACN,MAAM,IAAIC,MACR,yDAAyDD,IAAG,EAC9D;CACF;CACA,MAAMI,WAAWF,OAAOG,aAAaC,IAAIR,kBAAkB;CAC3D,IAAI,CAACM,UACH,MAAM,IAAIH,MACR,kCAAkCH,mBAAkB,kBACtD;CAEF,OAAOM;AACT;AAEA,MAAaG,oBACXC,QACAG,SACkB;CAClB,IAAI,OAAOA,SAAS,UAAU,OAAOA;CACrCH,OAAOI,MAAM,MAAM,kBAAkB;CACrC,OAAO;AACT"}

package/dist/host/draft.d.ts

@@ -0,0 +1,28 @@
+import { Statewire } from "../types.js";
+import { StatewirePath } from "../wire/ops.js";
+//#region src/host/draft.d.ts
+type ServerOp = Exclude<Statewire.Op, {
+  op: "event";
+}>;
+type DraftHost = {
+  snapshot: () => unknown;
+  record: (op: ServerOp, changedPath: StatewirePath) => void;
+};
+type StateDraft<T> = {
+  proxy: T;
+  /** Seal pending writes and return the committed state. */
+  flush: () => unknown;
+  /** Committed state was replaced externally; cached nodes re-resolve. */
+  invalidate: () => void;
+};
+declare const createStateDraft: <T>(host: DraftHost) => StateDraft<T>;
+/**
+ * Append `suffix` to the string at `parent[key]` on a statewire state draft,
+ * recording a single end-offset text-insert `add` op instead of a full
+ * `replace` — use it on token-streaming hot paths. Throws when the current
+ * value is not a string.
+ */
+declare const append: <TKey extends string | number>(parent: { readonly [P in TKey]: string; }, key: TKey, suffix: string) => void;
+//#endregion
+export { DraftHost, ServerOp, StateDraft, append, createStateDraft };
+//# sourceMappingURL=draft.d.ts.map

package/dist/host/draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.d.ts","names":[],"sources":["../../src/host/draft.ts"],"mappings":";;;KAMY,WAAW,QAAQ,UAAU;EAAM;;KAEnC;EACV;EACA,SAAS,IAAI,UAAU,aAAa;;KAG1B,WAAW;EACrB,OAAO;;EAEP;;EAEA;;cA6BW,mBAAoB,GAAG,MAAM,cAAY,WAAW;;;;;;;cAsQpD,SAAU,8BACrB,oBAAoB,KAAK,kBACzB,KAAK,MACL"}

package/dist/host/draft.js

@@ -0,0 +1,211 @@
+import { sharedDraftTraps } from "../util/draftTraps.js";
+import { isUnsafeKey } from "../util/statePath.js";
+import { sanitizeValue } from "../wire/ops.js";
+//#region src/host/draft.ts
+const NODE = Symbol("statewire.draftNode");
+const isIndex = (key) => /^(0|[1-9]\d*)$/.test(key);
+const invalid = (path, message) => /* @__PURE__ */ new Error(`statewire: ${message} at path: ${path.join(".")}`);
+const createStateDraft = (host) => {
+	let gen = 0;
+	const dirty = [];
+	const latest = (node) => node.copy ?? node.base;
+	const resolve = (node) => {
+		if (node.gen === gen) return node;
+		node.gen = gen;
+		if (node.parent === null) {
+			if (node.copy === null) node.base = host.snapshot();
+			return node;
+		}
+		const value = latest(resolve(node.parent))[node.key];
+		if (value !== latest(node)) {
+			node.base = value;
+			node.copy = null;
+		}
+		return node;
+	};
+	const prepareForWrite = (node) => {
+		resolve(node);
+		if (node.copy !== null) return node.copy;
+		const base = node.base;
+		node.copy = Array.isArray(base) ? base.slice() : { ...base };
+		dirty.push(node);
+		if (node.parent !== null) prepareForWrite(node.parent)[node.key] = node.copy;
+		return node.copy;
+	};
+	const changedPathFor = (node, key) => Array.isArray(latest(node)) ? node.path : [...node.path, key];
+	const applyAppend = (node, rawKey, suffix) => {
+		const container = latest(resolve(node));
+		const key = Array.isArray(container) && typeof rawKey === "string" && isIndex(rawKey) ? Number(rawKey) : rawKey;
+		const existing = Object.hasOwn(container, key) ? container[key] : void 0;
+		if (typeof existing !== "string") throw invalid([...node.path, key], "cannot append to a non-string");
+		if (suffix === "") return;
+		prepareForWrite(node)[key] = existing + suffix;
+		host.record({
+			op: "add",
+			path: [
+				...node.path,
+				key,
+				existing.length
+			],
+			value: suffix
+		}, changedPathFor(node, key));
+	};
+	const createNode = (parent, key) => {
+		const seed = parent === null ? host.snapshot() : latest(parent)[key];
+		const node = {
+			parent,
+			key,
+			path: parent === null ? [] : [...parent.path, key],
+			gen,
+			base: seed,
+			copy: null,
+			children: /* @__PURE__ */ new Map(),
+			isArray: Array.isArray(seed),
+			proxy: null,
+			handle: null
+		};
+		node.handle = { append: (childKey, suffix) => applyAppend(node, childKey, suffix) };
+		const current = () => latest(resolve(node));
+		const childProxy = (prop, childKey, value) => {
+			let child = node.children.get(prop);
+			if (child === void 0 || child.isArray !== Array.isArray(value)) {
+				child = createNode(node, childKey);
+				node.children.set(prop, child);
+			}
+			return child.proxy;
+		};
+		const assign = (container, key, value) => {
+			const old = Object.hasOwn(container, key) ? container[key] : void 0;
+			if (old === value) return;
+			const isObjectContainer = !Array.isArray(container);
+			if (isObjectContainer && isUnsafeKey(key, node.path[node.path.length - 1])) throw invalid([...node.path, key], `cannot set unsafe key "${key}"`);
+			if (value === void 0) {
+				if (!isObjectContainer) throw invalid([...node.path, key], "cannot serialize undefined");
+				delete prepareForWrite(node)[key];
+				host.record({
+					op: "remove",
+					path: [...node.path, key]
+				}, [...node.path, key]);
+				gen++;
+				return;
+			}
+			prepareForWrite(node)[key] = isObjectContainer ? sanitizeValue(value, key) : sanitizeValue(value);
+			host.record({
+				op: "replace",
+				path: [...node.path, key],
+				value
+			}, changedPathFor(node, key));
+			if (typeof old === "object" && old !== null || typeof value === "object" && value !== null) gen++;
+		};
+		node.proxy = new Proxy(seed, {
+			get: (_target, prop) => {
+				if (prop === NODE) return node.handle;
+				const container = current();
+				if (typeof prop === "symbol") return container[prop];
+				const c = container;
+				const key = Array.isArray(c) && isIndex(prop) ? Number(prop) : prop;
+				const value = c[key];
+				if (typeof value === "object" && value !== null) return childProxy(prop, key, value);
+				return value;
+			},
+			set: (_target, prop, value) => {
+				if (typeof prop === "symbol") return false;
+				const container = current();
+				if (Array.isArray(container)) {
+					if (prop === "length") {
+						const next = Number(value);
+						if (!Number.isInteger(next) || next < 0 || next > container.length) throw invalid(node.path, `cannot set list length to ${String(value)}`);
+						if (next === container.length) return true;
+						const copy = prepareForWrite(node);
+						for (let i = container.length - 1; i >= next; i--) {
+							copy.splice(i, 1);
+							host.record({
+								op: "remove",
+								path: [...node.path, i]
+							}, node.path);
+						}
+						gen++;
+						return true;
+					}
+					if (!isIndex(prop)) throw invalid(node.path, `cannot set key "${prop}" on a list`);
+					const index = Number(prop);
+					if (index > container.length) throw invalid(node.path, `list index ${index} out of range`);
+					if (index === container.length) {
+						if (value === void 0) throw invalid([...node.path, index], "cannot serialize undefined");
+						prepareForWrite(node)[index] = sanitizeValue(value);
+						host.record({
+							op: "add",
+							path: [...node.path, index],
+							value
+						}, node.path);
+						gen++;
+						return true;
+					}
+					assign(container, index, value);
+					return true;
+				}
+				assign(container, prop, value);
+				return true;
+			},
+			deleteProperty: (_target, prop) => {
+				if (typeof prop === "symbol") return false;
+				const container = current();
+				if (Array.isArray(container)) {
+					if (!isIndex(prop) || Number(prop) >= container.length) return true;
+					const index = Number(prop);
+					prepareForWrite(node).splice(index, 1);
+					host.record({
+						op: "remove",
+						path: [...node.path, index]
+					}, node.path);
+					gen++;
+					return true;
+				}
+				if (!Object.hasOwn(container, prop)) return true;
+				if (isUnsafeKey(prop, node.path[node.path.length - 1])) throw invalid([...node.path, prop], `cannot remove unsafe key "${prop}"`);
+				delete prepareForWrite(node)[prop];
+				host.record({
+					op: "remove",
+					path: [...node.path, prop]
+				}, [...node.path, prop]);
+				gen++;
+				return true;
+			},
+			has: (_target, prop) => Reflect.has(current(), prop),
+			...sharedDraftTraps(() => current(), "on a state draft")
+		});
+		return node;
+	};
+	const root = createNode(null, "");
+	return {
+		proxy: root.proxy,
+		flush: () => {
+			if (dirty.length === 0) return host.snapshot();
+			for (const node of dirty) if (node.copy !== null) {
+				node.base = node.copy;
+				node.copy = null;
+			}
+			dirty.length = 0;
+			return root.base;
+		},
+		invalidate: () => {
+			gen++;
+		}
+	};
+};
+/**
+* Append `suffix` to the string at `parent[key]` on a statewire state draft,
+* recording a single end-offset text-insert `add` op instead of a full
+* `replace` — use it on token-streaming hot paths. Throws when the current
+* value is not a string.
+*/
+const append = (parent, key, suffix) => {
+	const handle = parent[NODE];
+	if (handle === void 0) throw new Error("statewire: append expects a state draft object");
+	if (typeof suffix !== "string") throw new Error("statewire: append suffix must be a string");
+	handle.append(key, suffix);
+};
+//#endregion
+export { append, createStateDraft };
+
+//# sourceMappingURL=draft.js.map

package/dist/host/draft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.js","names":["Statewire","StatewirePath","sanitizeValue","isUnsafeKey","sharedDraftTraps","ServerOp","Exclude","Op","op","DraftHost","snapshot","record","changedPath","StateDraft","proxy","T","flush","invalidate","NODE","Symbol","NodeHandle","append","key","suffix","isIndex","test","invalid","path","message","Error","join","Container","Record","Node","parent","gen","base","copy","children","Map","isArray","handle","createStateDraft","host","dirty","latest","node","resolve","value","prepareForWrite","Array","slice","push","changedPathFor","applyAppend","rawKey","container","Number","existing","Object","hasOwn","undefined","length","createNode","seed","childKey","current","childProxy","prop","child","get","set","assign","old","isObjectContainer","Proxy","_target","c","next","isInteger","String","i","splice","index","deleteProperty","has","Reflect","root","TKey"],"sources":["../../src/host/draft.ts"],"sourcesContent":["import type { Statewire } from \"../types\";\nimport type { StatewirePath } from \"../wire/ops\";\nimport { sanitizeValue } from \"../wire/ops\";\nimport { isUnsafeKey } from \"../util/statePath\";\nimport { sharedDraftTraps } from \"../util/draftTraps\";\n\nexport type ServerOp = Exclude<Statewire.Op, { op: \"event\" }>;\n\nexport type DraftHost = {\n  snapshot: () => unknown;\n  record: (op: ServerOp, changedPath: StatewirePath) => void;\n};\n\nexport type StateDraft<T> = {\n  proxy: T;\n  /** Seal pending writes and return the committed state. */\n  flush: () => unknown;\n  /** Committed state was replaced externally; cached nodes re-resolve. */\n  invalidate: () => void;\n};\n\nconst NODE = Symbol(\"statewire.draftNode\");\n\ntype NodeHandle = {\n  append: (key: string | number, suffix: string) => void;\n};\n\nconst isIndex = (key: string) => /^(0|[1-9]\\d*)$/.test(key);\n\nconst invalid = (path: StatewirePath, message: string) =>\n  new Error(`statewire: ${message} at path: ${path.join(\".\")}`);\n\ntype Container = Record<string | number, unknown>;\n\ntype Node = {\n  parent: Node | null;\n  key: string | number;\n  path: StatewirePath;\n  gen: number;\n  base: unknown;\n  copy: Container | null;\n  children: Map<string, Node>;\n  isArray: boolean;\n  proxy: object;\n  handle: NodeHandle;\n};\n\nexport const createStateDraft = <T>(host: DraftHost): StateDraft<T> => {\n  let gen = 0;\n  const dirty: Node[] = [];\n\n  const latest = (node: Node): unknown => node.copy ?? node.base;\n\n  const resolve = (node: Node): Node => {\n    if (node.gen === gen) return node;\n    node.gen = gen;\n    if (node.parent === null) {\n      if (node.copy === null) node.base = host.snapshot();\n      return node;\n    }\n    const value = (latest(resolve(node.parent)) as Container)[node.key];\n    if (value !== latest(node)) {\n      node.base = value;\n      node.copy = null;\n    }\n    return node;\n  };\n\n  const prepareForWrite = (node: Node): Container => {\n    resolve(node);\n    if (node.copy !== null) return node.copy;\n    const base = node.base;\n    node.copy = Array.isArray(base)\n      ? (base.slice() as unknown as Container)\n      : { ...(base as Container) };\n    dirty.push(node);\n    if (node.parent !== null) {\n      prepareForWrite(node.parent)[node.key] = node.copy;\n    }\n    return node.copy;\n  };\n\n  const changedPathFor = (node: Node, key: string | number): StatewirePath =>\n    Array.isArray(latest(node)) ? node.path : [...node.path, key];\n\n  const applyAppend = (node: Node, rawKey: string | number, suffix: string) => {\n    const container = latest(resolve(node)) as Container;\n    const key =\n      Array.isArray(container) && typeof rawKey === \"string\" && isIndex(rawKey)\n        ? Number(rawKey)\n        : rawKey;\n    const existing = Object.hasOwn(container as object, key)\n      ? container[key]\n      : undefined;\n    if (typeof existing !== \"string\") {\n      throw invalid([...node.path, key], \"cannot append to a non-string\");\n    }\n    if (suffix === \"\") return;\n    prepareForWrite(node)[key] = existing + suffix;\n    host.record(\n      { op: \"add\", path: [...node.path, key, existing.length], value: suffix },\n      changedPathFor(node, key),\n    );\n  };\n\n  const createNode = (parent: Node | null, key: string | number): Node => {\n    const seed =\n      parent === null ? host.snapshot() : (latest(parent) as Container)[key];\n    const node: Node = {\n      parent,\n      key,\n      path: parent === null ? [] : [...parent.path, key],\n      gen,\n      base: seed,\n      copy: null,\n      children: new Map(),\n      isArray: Array.isArray(seed),\n      proxy: null!,\n      handle: null!,\n    };\n    node.handle = {\n      append: (childKey, suffix) => applyAppend(node, childKey, suffix),\n    };\n\n    const current = () => latest(resolve(node));\n\n    const childProxy = (\n      prop: string,\n      childKey: string | number,\n      value: object,\n    ) => {\n      let child = node.children.get(prop);\n      if (child === undefined || child.isArray !== Array.isArray(value)) {\n        child = createNode(node, childKey);\n        node.children.set(prop, child);\n      }\n      return child.proxy;\n    };\n\n    const assign = (\n      container: Container,\n      key: string | number,\n      value: unknown,\n    ) => {\n      const old = Object.hasOwn(container as object, key)\n        ? container[key]\n        : undefined;\n      if (old === value) return;\n      const isObjectContainer = !Array.isArray(container);\n      if (\n        isObjectContainer &&\n        isUnsafeKey(key, node.path[node.path.length - 1])\n      ) {\n        throw invalid([...node.path, key], `cannot set unsafe key \"${key}\"`);\n      }\n      if (value === undefined) {\n        if (!isObjectContainer) {\n          throw invalid([...node.path, key], \"cannot serialize undefined\");\n        }\n        delete prepareForWrite(node)[key];\n        host.record({ op: \"remove\", path: [...node.path, key] }, [\n          ...node.path,\n          key,\n        ]);\n        gen++;\n        return;\n      }\n      prepareForWrite(node)[key] = isObjectContainer\n        ? sanitizeValue(value, key as string)\n        : sanitizeValue(value);\n      host.record(\n        { op: \"replace\", path: [...node.path, key], value },\n        changedPathFor(node, key),\n      );\n      if (\n        (typeof old === \"object\" && old !== null) ||\n        (typeof value === \"object\" && value !== null)\n      ) {\n        gen++;\n      }\n    };\n\n    node.proxy = new Proxy(seed as object, {\n      get: (_target, prop) => {\n        if (prop === NODE) return node.handle;\n        const container = current();\n        if (typeof prop === \"symbol\") {\n          return (container as Record<symbol, unknown>)[prop];\n        }\n        const c = container as Container;\n        const key = Array.isArray(c) && isIndex(prop) ? Number(prop) : prop;\n        const value = c[key];\n        if (typeof value === \"object\" && value !== null) {\n          return childProxy(prop, key, value);\n        }\n        return value;\n      },\n      set: (_target, prop, value) => {\n        if (typeof prop === \"symbol\") return false;\n        const container = current();\n        if (Array.isArray(container)) {\n          if (prop === \"length\") {\n            const next = Number(value);\n            if (\n              !Number.isInteger(next) ||\n              next < 0 ||\n              next > container.length\n            ) {\n              throw invalid(\n                node.path,\n                `cannot set list length to ${String(value)}`,\n              );\n            }\n            if (next === container.length) return true;\n            const copy = prepareForWrite(node) as unknown as unknown[];\n            for (let i = container.length - 1; i >= next; i--) {\n              copy.splice(i, 1);\n              host.record({ op: \"remove\", path: [...node.path, i] }, node.path);\n            }\n            gen++;\n            return true;\n          }\n          if (!isIndex(prop)) {\n            throw invalid(node.path, `cannot set key \"${prop}\" on a list`);\n          }\n          const index = Number(prop);\n          if (index > container.length) {\n            throw invalid(node.path, `list index ${index} out of range`);\n          }\n          if (index === container.length) {\n            if (value === undefined) {\n              throw invalid(\n                [...node.path, index],\n                \"cannot serialize undefined\",\n              );\n            }\n            prepareForWrite(node)[index] = sanitizeValue(value);\n            host.record(\n              { op: \"add\", path: [...node.path, index], value },\n              node.path,\n            );\n            gen++;\n            return true;\n          }\n          assign(container as unknown as Container, index, value);\n          return true;\n        }\n        assign(container as Container, prop, value);\n        return true;\n      },\n      deleteProperty: (_target, prop) => {\n        if (typeof prop === \"symbol\") return false;\n        const container = current();\n        if (Array.isArray(container)) {\n          if (!isIndex(prop) || Number(prop) >= container.length) return true;\n          const index = Number(prop);\n          (prepareForWrite(node) as unknown as unknown[]).splice(index, 1);\n          host.record({ op: \"remove\", path: [...node.path, index] }, node.path);\n          gen++;\n          return true;\n        }\n        if (!Object.hasOwn(container as object, prop)) return true;\n        if (isUnsafeKey(prop, node.path[node.path.length - 1])) {\n          throw invalid(\n            [...node.path, prop],\n            `cannot remove unsafe key \"${prop}\"`,\n          );\n        }\n        delete prepareForWrite(node)[prop];\n        host.record({ op: \"remove\", path: [...node.path, prop] }, [\n          ...node.path,\n          prop,\n        ]);\n        gen++;\n        return true;\n      },\n      has: (_target, prop) => Reflect.has(current() as object, prop),\n      ...sharedDraftTraps(() => current() as object, \"on a state draft\"),\n    });\n    return node;\n  };\n\n  const root = createNode(null, \"\");\n\n  return {\n    proxy: root.proxy as T,\n    flush: () => {\n      if (dirty.length === 0) return host.snapshot();\n      for (const node of dirty) {\n        if (node.copy !== null) {\n          node.base = node.copy;\n          node.copy = null;\n        }\n      }\n      dirty.length = 0;\n      return root.base;\n    },\n    invalidate: () => {\n      gen++;\n    },\n  };\n};\n\n/**\n * Append `suffix` to the string at `parent[key]` on a statewire state draft,\n * recording a single end-offset text-insert `add` op instead of a full\n * `replace` — use it on token-streaming hot paths. Throws when the current\n * value is not a string.\n */\nexport const append = <TKey extends string | number>(\n  parent: { readonly [P in TKey]: string },\n  key: TKey,\n  suffix: string,\n): void => {\n  const handle = (parent as { [NODE]?: NodeHandle })[NODE];\n  if (handle === undefined) {\n    throw new Error(\"statewire: append expects a state draft object\");\n  }\n  if (typeof suffix !== \"string\") {\n    throw new Error(\"statewire: append suffix must be a string\");\n  }\n  handle.append(key, suffix);\n};\n"],"mappings":"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"}

package/dist/host/engine.d.ts

@@ -0,0 +1,14 @@
+//#region src/host/engine.d.ts
+/**
+ * Definitive handler rejection: the command settles rejected and
+ * message/payload travel to the client's rejected promise.
+ */
+declare class StatewireReject extends Error {
+  readonly payload?: unknown;
+  constructor(message: string, options?: {
+    payload?: unknown;
+  });
+}
+//#endregion
+export { StatewireReject };
+//# sourceMappingURL=engine.d.ts.map

package/dist/host/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","names":[],"sources":["../../src/host/engine.ts"],"mappings":";;;;;cAIa,wBAAwB;WAC1B;EAEG,YAAA,iBAAiB;IAAY"}

package/dist/host/engine.js

@@ -0,0 +1,17 @@
+//#region src/host/engine.ts
+/**
+* Definitive handler rejection: the command settles rejected and
+* message/payload travel to the client's rejected promise.
+*/
+var StatewireReject = class extends Error {
+	payload;
+	constructor(message, options) {
+		super(message);
+		this.name = "StatewireReject";
+		if (options?.payload !== void 0) this.payload = options.payload;
+	}
+};
+//#endregion
+export { StatewireReject };
+
+//# sourceMappingURL=engine.js.map

package/dist/host/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","names":["StatewireReject","Error","payload","constructor","message","options","name","undefined"],"sources":["../../src/host/engine.ts"],"sourcesContent":["/**\n * Definitive handler rejection: the command settles rejected and\n * message/payload travel to the client's rejected promise.\n */\nexport class StatewireReject extends Error {\n  readonly payload?: unknown;\n\n  constructor(message: string, options?: { payload?: unknown }) {\n    super(message);\n    this.name = \"StatewireReject\";\n    if (options?.payload !== undefined) this.payload = options.payload;\n  }\n}\n"],"mappings":";;;;;AAIA,IAAaA,kBAAb,cAAqCC,MAAM;CACzC;CAEAE,YAAYC,SAAiBC,SAAiC;EAC5D,MAAMD,OAAO;EACb,KAAKE,OAAO;EACZ,IAAID,SAASH,YAAYK,KAAAA,GAAW,KAAKL,UAAUG,QAAQH;CAC7D;AACF"}

package/dist/host/host.d.ts

@@ -0,0 +1,62 @@
+import { StatewireHost } from "../host.js";
+import { Statewire } from "../types.js";
+//#region src/host/host.d.ts
+/** Host-side accessor for a `useStatewireState` state object's source (`snapshot()` reads the committed state). */
+declare const getStateHost: (state: object) => StatewireHost.StateHost | undefined;
+declare const useStatewireState: <TState>(init: () => TState) => readonly [TState, StatewireHost.StateCtl<TState>];
+/**
+ * `CommandExecution(executor)` runs the (possibly async) `executor({ ack })`
+ * immediately: its return value resolves the execution, a throw/rejection
+ * rejects it; `ack()` releases the client's ack watermark before the executor
+ * finishes. `CommandExecution.withResolvers()` returns `[execution,
+ * { ack, resolve, reject }]` instead — settle them from your own spawned work.
+ */
+declare const CommandExecution: (<T = void>(executor: (resolvers: {
+  ack: () => void;
+}) => T | void | PromiseLike<T | void>) => StatewireHost.Execution<T>) & {
+  withResolvers: <T = void>() => [StatewireHost.Execution<T>, StatewireHost.ExecutionResolvers<T>];
+};
+type CommandsInvocation = {
+  readonly method: string;
+  readonly params: readonly unknown[];
+  readonly ts: number;
+  readonly seq: number;
+  readonly clientId?: string;
+};
+type CommandsOutcome = {
+  type: "accepted";
+  payload?: unknown;
+} | {
+  type: "rejected";
+  error: unknown;
+};
+type CommandsListener = {
+  onStart: (inv: CommandsInvocation) => void;
+  onPosted?: (inv: CommandsInvocation) => void;
+  onAck: (inv: CommandsInvocation) => void;
+  /** Canonical state now covers the invocation's effect — drop any overlay. */
+  onCovered?: (inv: CommandsInvocation) => void;
+  onSettle: (inv: CommandsInvocation, outcome: CommandsOutcome) => void;
+};
+type CommandsSubmission = {
+  method: string;
+  params: readonly unknown[];
+  clientId?: string;
+  onAck?: () => void;
+  onSettle?: (outcome: CommandsOutcome) => void;
+};
+type CommandsHost = {
+  setListener: (listener: CommandsListener | null) => void;
+  submit?: (call: CommandsSubmission) => Promise<unknown>;
+};
+declare const getCommandsHost: (commands: object) => CommandsHost | undefined;
+declare const bindCommandsHost: (commands: object, host: CommandsHost) => void;
+declare const useStatewireCommands: <THandlers extends Statewire.Commands>(commands: THandlers | undefined | null | false) => Statewire.CommandsProxy<StatewireHost.HandledCommands<THandlers>>;
+type EmitHost = {
+  setSink: (sink: ((event: unknown) => void) | null) => void;
+};
+declare const getEmitHost: (emit: object | undefined) => EmitHost | undefined;
+declare const useStatewireEmit: <TEvent>() => ((event: TEvent) => void);
+//#endregion
+export { CommandExecution, CommandsHost, CommandsInvocation, CommandsListener, CommandsOutcome, CommandsSubmission, EmitHost, bindCommandsHost, getCommandsHost, getEmitHost, getStateHost, useStatewireCommands, useStatewireEmit, useStatewireState };
+//# sourceMappingURL=host.d.ts.map

package/dist/host/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","names":[],"sources":["../../src/host/host.ts"],"mappings":";;;;cAmBa,eACX,kBACC,cAAc;cAaJ,oBAAqB,QAChC,YAAY,qBACD,QAAQ,cAAc,SAAS;;;;;;;;cA4F/B,oBACV,UAAC,WACW;EACT;MACI,WAAW,YAAY,cAC5B,cAAc,UAAU;EA2BT,gBAAA,gBACd,cAAc,UAAU,IACxB,cAAc,mBAAmB;;KAkB3B;WACD;WACA;WACA;WACA;WACA;;KAGC;EACN;EAAkB;;EAClB;EAAkB;;KAEZ;EACV,UAAU,KAAK;EACf,YAAY,KAAK;EACjB,QAAQ,KAAK;;EAEb,aAAa,KAAK;EAClB,WAAW,KAAK,oBAAoB,SAAS;;KAGnC;EACV;EACA;EACA;EACA;EACA,YAAY,SAAS;;KAGX;EACV,cAAc,UAAU;EACxB,UAAU,MAAM,uBAAuB;;cAK5B,kBAAmB,qBAAmB;cAGtC,mBAAoB,kBAAkB,MAAM;cAqJ5C,uBAAwB,kBAAkB,UAAU,UAC/D,UAAU,yCACT,UAAU,cAAc,cAAc,gBAAgB;KAqF7C;EACV,UAAU,QAAQ;;cAKP,cAAe,6BAA2B;cAG1C,mBAAoB,eAAa,OAAO"}