statewire 0.0.0-0 → 0.0.2

package/dist/host/host.js

@@ -0,0 +1,331 @@
+import { applyOps, sanitizeValue } from "../wire/ops.js";
+import { StatewireReject } from "./engine.js";
+import { createStateDraft } from "./draft.js";
+import { createMethodProxy } from "../util/methodProxy.js";
+import { StatewireSendError } from "../types.js";
+import { useEffect, useState } from "@assistant-ui/tap/react-shim";
+//#region src/host/host.ts
+const isDev = () => typeof process === "undefined" || process.env["NODE_ENV"] !== "production";
+const stateHosts = /* @__PURE__ */ new WeakMap();
+/** Host-side accessor for a `useStatewireState` state object's source (`snapshot()` reads the committed state). */
+const getStateHost = (state) => stateHosts.get(state);
+const useStatewireState = (init) => {
+	const [, setVersion] = useState(0);
+	const [cell] = useState(() => {
+		const commit = () => {
+			if (c.draft) c.current = c.draft.flush();
+			return c.current;
+		};
+		const c = {
+			current: sanitizeValue(init()),
+			draft: null,
+			changed: [[]],
+			onOp: null,
+			onChange: null,
+			bump: () => setVersion((v) => v + 1),
+			ctl: {
+				apply: (ops) => {
+					const result = applyOps(commit(), ops);
+					if (result.events.length > 0) throw new Error("statewire: event ops do not apply to state — route them to emit");
+					c.current = result.state;
+					c.draft?.invalidate();
+					c.changed.push(...result.changedPaths);
+					if (c.onOp) for (const op of ops) c.onOp(op);
+					c.bump();
+					c.onChange?.();
+				},
+				snapshot: commit
+			},
+			host: {
+				snapshot: commit,
+				setOnOp: (listener) => {
+					c.onOp = listener;
+				},
+				setOnChange: (listener_0) => {
+					c.onChange = listener_0;
+				},
+				takeChanged: () => {
+					const changed = c.changed;
+					c.changed = [];
+					return changed;
+				}
+			}
+		};
+		return c;
+	});
+	let value = cell.ctl.snapshot();
+	if (typeof value === "object" && value !== null) {
+		cell.draft ??= createStateDraft({
+			snapshot: () => cell.current,
+			record: (op, changedPath) => {
+				cell.changed.push(changedPath);
+				cell.onOp?.(op);
+				cell.bump();
+				cell.onChange?.();
+			}
+		});
+		stateHosts.set(cell.draft.proxy, cell.host);
+		value = cell.draft.proxy;
+	}
+	return [value, cell.ctl];
+};
+const executionStates = /* @__PURE__ */ new WeakMap();
+/**
+* `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.
+*/
+const CommandExecution = Object.assign((executor) => {
+	const state = {
+		acked: false,
+		settled: null,
+		bind: null
+	};
+	const execution = Object.freeze({});
+	executionStates.set(execution, state);
+	const settle = (settled) => {
+		if (state.settled) return;
+		state.settled = settled;
+		state.acked = true;
+		state.bind?.onSettle(settled);
+	};
+	const ack = () => {
+		if (state.acked) return;
+		state.acked = true;
+		state.bind?.onAck();
+	};
+	(async () => {
+		try {
+			settle({
+				type: "resolved",
+				value: await executor({ ack })
+			});
+		} catch (error) {
+			settle({
+				type: "rejected",
+				error
+			});
+		}
+	})();
+	return execution;
+}, { withResolvers: () => {
+	let resolve;
+	let reject;
+	const promise = new Promise((res, rej) => {
+		resolve = res;
+		reject = rej;
+	});
+	let ack;
+	return [CommandExecution(({ ack: a }) => {
+		ack = a;
+		return promise;
+	}), {
+		ack: () => ack(),
+		resolve,
+		reject
+	}];
+} });
+const commandsHosts = /* @__PURE__ */ new WeakMap();
+const getCommandsHost = (commands) => commandsHosts.get(commands);
+const bindCommandsHost = (commands, host) => {
+	commandsHosts.set(commands, host);
+};
+const STALL_WARN_MS = 5e3;
+const toSendError = (error) => error instanceof StatewireSendError ? error : new StatewireSendError({
+	fate: "rejected",
+	cause: "server",
+	message: error instanceof Error ? error.message : String(error),
+	...error instanceof StatewireReject && error.payload !== void 0 && { payload: error.payload }
+});
+const ackInvocation = (cell, inv) => {
+	if (inv.acked) return;
+	inv.acked = true;
+	cell.listener?.onAck(inv);
+	inv.origin?.onAck?.();
+};
+const settleInvocation = (cell, inv, call, settled) => {
+	ackInvocation(cell, inv);
+	if (settled.type === "resolved") {
+		const outcome = settled.value === void 0 ? { type: "accepted" } : {
+			type: "accepted",
+			payload: sanitizeValue(settled.value)
+		};
+		cell.listener?.onSettle(inv, outcome);
+		inv.origin?.onSettle?.(outcome);
+		call.resolve(outcome.payload);
+	} else {
+		const error = toSendError(settled.error);
+		const outcome = {
+			type: "rejected",
+			error
+		};
+		cell.listener?.onSettle(inv, outcome);
+		inv.origin?.onSettle?.(outcome);
+		call.reject(error);
+	}
+};
+const pump = (cell) => {
+	if (cell.running || !cell.handlers) {
+		watchStall(cell);
+		return;
+	}
+	const call = cell.queue.shift();
+	if (!call) return;
+	const handler = cell.handlers[call.method];
+	if (handler === void 0) {
+		const error = new StatewireSendError({
+			fate: "unknown-command",
+			cause: "server"
+		});
+		call.origin?.onSettle?.({
+			type: "rejected",
+			error
+		});
+		call.reject(error);
+		pump(cell);
+		return;
+	}
+	const inv = {
+		method: call.method,
+		params: call.params,
+		ts: call.ts,
+		seq: ++cell.seq,
+		acked: false,
+		...call.origin !== void 0 && { origin: call.origin },
+		...call.origin?.clientId !== void 0 && { clientId: call.origin.clientId }
+	};
+	cell.running = true;
+	cell.listener?.onStart(inv);
+	cell.listener?.onPosted?.(inv);
+	cell.listener?.onCovered?.(inv);
+	(async () => {
+		try {
+			const value = await handler(...call.params);
+			const execution = typeof value === "object" && value !== null ? executionStates.get(value) : void 0;
+			if (execution) {
+				if (execution.acked) ackInvocation(cell, inv);
+				if (execution.settled) settleInvocation(cell, inv, call, execution.settled);
+				else execution.bind = {
+					onAck: () => ackInvocation(cell, inv),
+					onSettle: (settled) => settleInvocation(cell, inv, call, settled)
+				};
+			} else settleInvocation(cell, inv, call, {
+				type: "resolved",
+				value
+			});
+		} catch (error) {
+			settleInvocation(cell, inv, call, {
+				type: "rejected",
+				error
+			});
+		} finally {
+			cell.running = false;
+			pump(cell);
+		}
+	})();
+};
+const watchStall = (cell) => {
+	if (!isDev() || cell.stallTimer !== null || cell.queue.length === 0) return;
+	if (cell.handlers) return;
+	cell.stallTimer = setTimeout(() => {
+		cell.stallTimer = null;
+		if (cell.handlers === null && cell.queue.length > 0 && !cell.unmounted) console.warn(`statewire: ${cell.queue.length} buffered command(s) waiting over ${STALL_WARN_MS}ms — did the host forget to arm useStatewireCommands?`);
+	}, STALL_WARN_MS);
+};
+const useStatewireCommands = (commands) => {
+	const [built] = useState(() => {
+		const cell = {
+			handlers: null,
+			queue: [],
+			running: false,
+			listener: null,
+			seq: 0,
+			unmounted: false,
+			stallTimer: null
+		};
+		const proxy = createMethodProxy((method, params) => new Promise((resolve, reject) => {
+			if (cell.unmounted) {
+				reject(/* @__PURE__ */ new Error("statewire: commands called after unmount"));
+				return;
+			}
+			cell.queue.push({
+				method,
+				params,
+				ts: Date.now(),
+				resolve,
+				reject
+			});
+			pump(cell);
+		}));
+		commandsHosts.set(proxy, {
+			setListener: (listener) => {
+				cell.listener = listener;
+			},
+			submit: (origin) => new Promise((resolve_0, reject_0) => {
+				if (cell.unmounted) {
+					reject_0(/* @__PURE__ */ new Error("statewire: commands called after unmount"));
+					return;
+				}
+				cell.queue.push({
+					method: origin.method,
+					params: origin.params,
+					ts: Date.now(),
+					resolve: resolve_0,
+					reject: reject_0,
+					origin
+				});
+				pump(cell);
+			})
+		});
+		return {
+			cell,
+			proxy
+		};
+	});
+	useEffect(() => {
+		const { cell: cell_0 } = built;
+		cell_0.unmounted = false;
+		return () => {
+			cell_0.unmounted = true;
+			cell_0.handlers = null;
+			if (cell_0.stallTimer !== null) {
+				clearTimeout(cell_0.stallTimer);
+				cell_0.stallTimer = null;
+			}
+			queueMicrotask(() => {
+				if (!cell_0.unmounted) return;
+				const queued = cell_0.queue;
+				cell_0.queue = [];
+				for (const call of queued) call.reject(/* @__PURE__ */ new Error("statewire: unmounted"));
+			});
+		};
+	}, [built]);
+	useEffect(() => {
+		built.cell.handlers = commands || null;
+		pump(built.cell);
+	});
+	return built.proxy;
+};
+const emitHosts = /* @__PURE__ */ new WeakMap();
+const getEmitHost = (emit) => emit && emitHosts.get(emit);
+const useStatewireEmit = () => {
+	const [built] = useState(_temp);
+	return built;
+};
+function _temp() {
+	const cell = { sink: null };
+	const emit = (event) => {
+		if (!cell.sink) throw new Error("statewire: emit before a host bound the event sink");
+		cell.sink(sanitizeValue(event));
+	};
+	emitHosts.set(emit, { setSink: (sink) => {
+		cell.sink = sink;
+	} });
+	return emit;
+}
+//#endregion
+export { CommandExecution, bindCommandsHost, getCommandsHost, getEmitHost, getStateHost, useStatewireCommands, useStatewireEmit, useStatewireState };
+
+//# sourceMappingURL=host.js.map

package/dist/host/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","names":["useEffect","useState","applyOps","sanitizeValue","StatewirePath","StatewireReject","createStateDraft","createMethodProxy","ServerOp","StateDraft","StatewireSendError","Statewire","StatewireHost","isDev","process","env","stateHosts","WeakMap","StateHost","getStateHost","state","get","StateCell","current","draft","changed","onOp","op","onChange","ctl","StateCtl","host","bump","useStatewireState","init","TState","setVersion","cell","commit","c","flush","v","apply","ops","result","events","length","Error","invalidate","push","changedPaths","snapshot","setOnOp","listener","setOnChange","takeChanged","value","record","changedPath","set","proxy","const","ExecutionSettled","type","error","ExecutionBind","onAck","onSettle","settled","ExecutionState","acked","bind","executionStates","CommandExecution","Object","assign","executor","resolvers","ack","T","PromiseLike","Execution","execution","freeze","settle","withResolvers","ExecutionResolvers","resolve","reject","promise","Promise","res","rej","a","CommandsInvocation","method","params","ts","seq","clientId","CommandsOutcome","payload","CommandsListener","onStart","inv","onPosted","onCovered","outcome","CommandsSubmission","CommandsHost","setListener","submit","call","commandsHosts","getCommandsHost","commands","bindCommandsHost","QueuedCall","origin","ActiveInvocation","CommandsCell","handlers","Record","args","queue","running","unmounted","stallTimer","ReturnType","setTimeout","STALL_WARN_MS","toSendError","fate","cause","message","String","undefined","ackInvocation","settleInvocation","pump","watchStall","shift","handler","console","warn","useStatewireCommands","Commands","THandlers","CommandsProxy","HandledCommands","built","Date","now","clearTimeout","queueMicrotask","queued","EmitHost","setSink","sink","event","emitHosts","getEmitHost","emit","useStatewireEmit","_temp"],"sources":["../../src/host/host.ts"],"sourcesContent":["import { useEffect, useState } from \"react\";\nimport { applyOps, sanitizeValue } from \"../wire/ops\";\nimport type { StatewirePath } from \"../wire/ops\";\nimport { StatewireReject } from \"./engine\";\nimport { createStateDraft } from \"./draft\";\nimport { createMethodProxy } from \"../util/methodProxy\";\nimport type { ServerOp, StateDraft } from \"./draft\";\nimport { StatewireSendError } from \"../types\";\nimport type { Statewire } from \"../types\";\nimport type { StatewireHost } from \"../host\";\n\nconst isDev = () =>\n  typeof process === \"undefined\" || process.env[\"NODE_ENV\"] !== \"production\";\n\n// ─── state ──────────────────────────────────────────────\n\nconst stateHosts = new WeakMap<object, StatewireHost.StateHost>();\n\n/** Host-side accessor for a `useStatewireState` state object's source (`snapshot()` reads the committed state). */\nexport const getStateHost = (\n  state: object,\n): StatewireHost.StateHost | undefined => stateHosts.get(state);\n\ntype StateCell = {\n  current: unknown;\n  draft: StateDraft<object> | null;\n  changed: StatewirePath[];\n  onOp: ((op: ServerOp) => void) | null;\n  onChange: (() => void) | null;\n  ctl: StatewireHost.StateCtl;\n  host: StatewireHost.StateHost;\n  bump: () => void;\n};\n\nexport const useStatewireState = <TState>(\n  init: () => TState,\n): readonly [TState, StatewireHost.StateCtl<TState>] => {\n  const [, setVersion] = useState(0);\n  const [cell] = useState((): StateCell => {\n    const commit = () => {\n      if (c.draft) c.current = c.draft.flush();\n      return c.current;\n    };\n    const c: StateCell = {\n      current: sanitizeValue(init()),\n      draft: null,\n      changed: [[]],\n      onOp: null,\n      onChange: null,\n      bump: () => setVersion((v) => v + 1),\n      ctl: {\n        apply: (ops) => {\n          const result = applyOps(commit(), ops);\n          if (result.events.length > 0) {\n            throw new Error(\n              \"statewire: event ops do not apply to state — route them to emit\",\n            );\n          }\n          c.current = result.state;\n          c.draft?.invalidate();\n          c.changed.push(...result.changedPaths);\n          if (c.onOp) for (const op of ops) c.onOp(op as ServerOp);\n          c.bump();\n          c.onChange?.();\n        },\n        snapshot: commit,\n      },\n      host: {\n        snapshot: commit,\n        setOnOp: (listener) => {\n          c.onOp = listener;\n        },\n        setOnChange: (listener) => {\n          c.onChange = listener;\n        },\n        takeChanged: () => {\n          const changed = c.changed;\n          c.changed = [];\n          return changed;\n        },\n      },\n    };\n    return c;\n  });\n\n  let value = cell.ctl.snapshot();\n  if (typeof value === \"object\" && value !== null) {\n    cell.draft ??= createStateDraft<object>({\n      snapshot: () => cell.current,\n      record: (op, changedPath) => {\n        cell.changed.push(changedPath);\n        cell.onOp?.(op);\n        cell.bump();\n        cell.onChange?.();\n      },\n    });\n    stateHosts.set(cell.draft.proxy, cell.host);\n    value = cell.draft.proxy;\n  }\n  return [value as TState, cell.ctl as StatewireHost.StateCtl<TState>] as const;\n};\n\n// ─── commands ───────────────────────────────────────────\n\ntype ExecutionSettled =\n  | { type: \"resolved\"; value: unknown }\n  | { type: \"rejected\"; error: unknown };\n\ntype ExecutionBind = {\n  onAck: () => void;\n  onSettle: (settled: ExecutionSettled) => void;\n};\n\ntype ExecutionState = {\n  acked: boolean;\n  settled: ExecutionSettled | null;\n  bind: ExecutionBind | null;\n};\n\nconst executionStates = new WeakMap<object, ExecutionState>();\n\n/**\n * `CommandExecution(executor)` runs the (possibly async) `executor({ ack })`\n * immediately: its return value resolves the execution, a throw/rejection\n * rejects it; `ack()` releases the client's ack watermark before the executor\n * finishes. `CommandExecution.withResolvers()` returns `[execution,\n * { ack, resolve, reject }]` instead — settle them from your own spawned work.\n */\nexport const CommandExecution = Object.assign(\n  <T = void>(\n    executor: (resolvers: {\n      ack: () => void;\n    }) => T | void | PromiseLike<T | void>,\n  ): StatewireHost.Execution<T> => {\n    const state: ExecutionState = { acked: false, settled: null, bind: null };\n    const execution = Object.freeze(\n      {},\n    ) as unknown as StatewireHost.Execution<T>;\n    executionStates.set(execution, state);\n    const settle = (settled: ExecutionSettled) => {\n      if (state.settled) return;\n      state.settled = settled;\n      state.acked = true;\n      state.bind?.onSettle(settled);\n    };\n    const ack = () => {\n      if (state.acked) return;\n      state.acked = true;\n      state.bind?.onAck();\n    };\n    void (async () => {\n      try {\n        settle({ type: \"resolved\", value: await executor({ ack }) });\n      } catch (error) {\n        settle({ type: \"rejected\", error });\n      }\n    })();\n    return execution;\n  },\n  {\n    withResolvers: <T = void>(): [\n      StatewireHost.Execution<T>,\n      StatewireHost.ExecutionResolvers<T>,\n    ] => {\n      let resolve!: (value: T) => void;\n      let reject!: (error: unknown) => void;\n      const promise = new Promise<T>((res, rej) => {\n        resolve = res;\n        reject = rej;\n      });\n      let ack!: () => void;\n      const execution = CommandExecution<T>(({ ack: a }) => {\n        ack = a;\n        return promise;\n      });\n      return [execution, { ack: () => ack(), resolve, reject }];\n    },\n  },\n);\n\nexport type CommandsInvocation = {\n  readonly method: string;\n  readonly params: readonly unknown[];\n  readonly ts: number;\n  readonly seq: number;\n  readonly clientId?: string;\n};\n\nexport type CommandsOutcome =\n  | { type: \"accepted\"; payload?: unknown }\n  | { type: \"rejected\"; error: unknown };\n\nexport type CommandsListener = {\n  onStart: (inv: CommandsInvocation) => void;\n  onPosted?: (inv: CommandsInvocation) => void;\n  onAck: (inv: CommandsInvocation) => void;\n  /** Canonical state now covers the invocation's effect — drop any overlay. */\n  onCovered?: (inv: CommandsInvocation) => void;\n  onSettle: (inv: CommandsInvocation, outcome: CommandsOutcome) => void;\n};\n\nexport type CommandsSubmission = {\n  method: string;\n  params: readonly unknown[];\n  clientId?: string;\n  onAck?: () => void;\n  onSettle?: (outcome: CommandsOutcome) => void;\n};\n\nexport type CommandsHost = {\n  setListener: (listener: CommandsListener | null) => void;\n  submit?: (call: CommandsSubmission) => Promise<unknown>;\n};\n\nconst commandsHosts = new WeakMap<object, CommandsHost>();\n\nexport const getCommandsHost = (commands: object): CommandsHost | undefined =>\n  commandsHosts.get(commands);\n\nexport const bindCommandsHost = (commands: object, host: CommandsHost) => {\n  commandsHosts.set(commands, host);\n};\n\ntype QueuedCall = {\n  method: string;\n  params: readonly unknown[];\n  ts: number;\n  resolve: (value: unknown) => void;\n  reject: (error: unknown) => void;\n  origin?: CommandsSubmission;\n};\n\ntype ActiveInvocation = CommandsInvocation & {\n  acked: boolean;\n  origin?: CommandsSubmission;\n};\n\ntype CommandsCell = {\n  handlers: Record<string, (...args: never[]) => unknown> | null;\n  queue: QueuedCall[];\n  running: boolean;\n  listener: CommandsListener | null;\n  seq: number;\n  unmounted: boolean;\n  stallTimer: ReturnType<typeof setTimeout> | null;\n};\n\nconst STALL_WARN_MS = 5000;\n\nconst toSendError = (error: unknown): StatewireSendError =>\n  error instanceof StatewireSendError\n    ? error\n    : new StatewireSendError({\n        fate: \"rejected\",\n        cause: \"server\",\n        message: error instanceof Error ? error.message : String(error),\n        ...(error instanceof StatewireReject &&\n          error.payload !== undefined && { payload: error.payload }),\n      });\n\nconst ackInvocation = (cell: CommandsCell, inv: ActiveInvocation) => {\n  if (inv.acked) return;\n  inv.acked = true;\n  cell.listener?.onAck(inv);\n  inv.origin?.onAck?.();\n};\n\nconst settleInvocation = (\n  cell: CommandsCell,\n  inv: ActiveInvocation,\n  call: QueuedCall,\n  settled: ExecutionSettled,\n) => {\n  ackInvocation(cell, inv);\n  if (settled.type === \"resolved\") {\n    const outcome: CommandsOutcome =\n      settled.value === undefined\n        ? { type: \"accepted\" }\n        : { type: \"accepted\", payload: sanitizeValue(settled.value) };\n    cell.listener?.onSettle(inv, outcome);\n    inv.origin?.onSettle?.(outcome);\n    call.resolve(outcome.payload);\n  } else {\n    const error = toSendError(settled.error);\n    const outcome: CommandsOutcome = { type: \"rejected\", error };\n    cell.listener?.onSettle(inv, outcome);\n    inv.origin?.onSettle?.(outcome);\n    call.reject(error);\n  }\n};\n\nconst pump = (cell: CommandsCell) => {\n  if (cell.running || !cell.handlers) {\n    watchStall(cell);\n    return;\n  }\n  const call = cell.queue.shift();\n  if (!call) return;\n  const handler = cell.handlers[call.method];\n  if (handler === undefined) {\n    const error = new StatewireSendError({\n      fate: \"unknown-command\",\n      cause: \"server\",\n    });\n    call.origin?.onSettle?.({ type: \"rejected\", error });\n    call.reject(error);\n    pump(cell);\n    return;\n  }\n  const inv: ActiveInvocation = {\n    method: call.method,\n    params: call.params,\n    ts: call.ts,\n    seq: ++cell.seq,\n    acked: false,\n    ...(call.origin !== undefined && { origin: call.origin }),\n    ...(call.origin?.clientId !== undefined && {\n      clientId: call.origin.clientId,\n    }),\n  };\n  cell.running = true;\n  cell.listener?.onStart(inv);\n  cell.listener?.onPosted?.(inv);\n  cell.listener?.onCovered?.(inv);\n  void (async () => {\n    try {\n      const value = await (handler as (...args: readonly unknown[]) => unknown)(\n        ...call.params,\n      );\n      const execution =\n        typeof value === \"object\" && value !== null\n          ? executionStates.get(value)\n          : undefined;\n      if (execution) {\n        if (execution.acked) ackInvocation(cell, inv);\n        if (execution.settled) {\n          settleInvocation(cell, inv, call, execution.settled);\n        } else {\n          execution.bind = {\n            onAck: () => ackInvocation(cell, inv),\n            onSettle: (settled) => settleInvocation(cell, inv, call, settled),\n          };\n        }\n      } else {\n        settleInvocation(cell, inv, call, { type: \"resolved\", value });\n      }\n    } catch (error) {\n      settleInvocation(cell, inv, call, { type: \"rejected\", error });\n    } finally {\n      cell.running = false;\n      pump(cell);\n    }\n  })();\n};\n\nconst watchStall = (cell: CommandsCell) => {\n  if (!isDev() || cell.stallTimer !== null || cell.queue.length === 0) return;\n  if (cell.handlers) return;\n  cell.stallTimer = setTimeout(() => {\n    cell.stallTimer = null;\n    if (cell.handlers === null && cell.queue.length > 0 && !cell.unmounted) {\n      console.warn(\n        `statewire: ${cell.queue.length} buffered command(s) waiting over ${STALL_WARN_MS}ms — did the host forget to arm useStatewireCommands?`,\n      );\n    }\n  }, STALL_WARN_MS);\n};\n\nexport const useStatewireCommands = <THandlers extends Statewire.Commands>(\n  commands: THandlers | undefined | null | false,\n): Statewire.CommandsProxy<StatewireHost.HandledCommands<THandlers>> => {\n  const [built] = useState(() => {\n    const cell: CommandsCell = {\n      handlers: null,\n      queue: [],\n      running: false,\n      listener: null,\n      seq: 0,\n      unmounted: false,\n      stallTimer: null,\n    };\n    const proxy = createMethodProxy<\n      Statewire.CommandsProxy<StatewireHost.HandledCommands<THandlers>>\n    >(\n      (method, params) =>\n        new Promise((resolve, reject) => {\n          if (cell.unmounted) {\n            reject(new Error(\"statewire: commands called after unmount\"));\n            return;\n          }\n          cell.queue.push({\n            method,\n            params,\n            ts: Date.now(),\n            resolve,\n            reject,\n          });\n          pump(cell);\n        }),\n    );\n    commandsHosts.set(proxy, {\n      setListener: (listener) => {\n        cell.listener = listener;\n      },\n      submit: (origin) =>\n        new Promise((resolve, reject) => {\n          if (cell.unmounted) {\n            reject(new Error(\"statewire: commands called after unmount\"));\n            return;\n          }\n          cell.queue.push({\n            method: origin.method,\n            params: origin.params,\n            ts: Date.now(),\n            resolve,\n            reject,\n            origin,\n          });\n          pump(cell);\n        }),\n    });\n    return { cell, proxy };\n  });\n\n  useEffect(() => {\n    const { cell } = built;\n    cell.unmounted = false;\n    return () => {\n      cell.unmounted = true;\n      cell.handlers = null;\n      if (cell.stallTimer !== null) {\n        clearTimeout(cell.stallTimer);\n        cell.stallTimer = null;\n      }\n      queueMicrotask(() => {\n        if (!cell.unmounted) return;\n        const queued = cell.queue;\n        cell.queue = [];\n        for (const call of queued) {\n          call.reject(new Error(\"statewire: unmounted\"));\n        }\n      });\n    };\n  }, [built]);\n\n  useEffect(() => {\n    built.cell.handlers = commands || null;\n    pump(built.cell);\n  });\n\n  return built.proxy;\n};\n\n// ─── emit ───────────────────────────────────────────────\n\nexport type EmitHost = {\n  setSink: (sink: ((event: unknown) => void) | null) => void;\n};\n\nconst emitHosts = new WeakMap<object, EmitHost>();\n\nexport const getEmitHost = (emit: object | undefined): EmitHost | undefined =>\n  emit && emitHosts.get(emit);\n\nexport const useStatewireEmit = <TEvent>(): ((event: TEvent) => void) => {\n  const [built] = useState(() => {\n    const cell = { sink: null as ((event: unknown) => void) | null };\n    const emit = (event: TEvent) => {\n      if (!cell.sink) {\n        throw new Error(\"statewire: emit before a host bound the event sink\");\n      }\n      cell.sink(sanitizeValue(event));\n    };\n    emitHosts.set(emit, {\n      setSink: (sink) => {\n        cell.sink = sink;\n      },\n    });\n    return emit;\n  });\n  return built;\n};\n"],"mappings":"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"}

package/dist/host/socket.d.ts

@@ -0,0 +1,14 @@
+import { Statewire } from "../types.js";
+import { StatewireHostInternal } from "../host-internal.js";
+import { ResourceElement } from "@assistant-ui/tap";
+//#region src/host/socket.d.ts
+/**
+ * Transport-agnostic WS binding over a statewire/host transport:
+ * feed it sockets (anything with `send`/`close`) and raw text frames, and it
+ * speaks the Statewire envelope protocol — snapshot-first attach with `syn`,
+ * delta/ack/res envelopes, per-client-id supersede, and `fin` on finish.
+ */
+declare const StatewireSocketHost: (transport: ResourceElement<Statewire>, options?: StatewireHostInternal.SocketHostOptions) => StatewireHostInternal.SocketHost;
+//#endregion
+export { StatewireSocketHost };
+//# sourceMappingURL=socket.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","names":[],"sources":["../../src/host/socket.ts"],"mappings":";;;;;;;;;;cA2gBa,sBACX,WAAW,gBAAgB,YAC3B,UAAU,sBAAsB,sBAC/B,sBAAsB"}