statewire 0.0.2 → 0.0.3

package/dist/transports/ws.js.map

@@ -1 +1 @@
-{"version":3,"file":"ws.js","names":["useState","flushTapSync","resource","ResourceElement","encodeParams","timing","handleEnvelope","overloadedError","useStatewireConn","Conn","StatewireEnvelope","Statewire","StatewireClient","useStatewireRemote","CLIENT_QUERY_PARAM","RemoteLink","StatewireSubmitResult","StatewireRemoteProps","StatewireWireCommand","PendingCommand","seq","resolve","result","reject","error","Error","WsChannel","socket","WebSocket","pending","OPEN","WS_SUBPROTOCOL","socketUrl","options","WSOptions","clientId","url","query","params","URLSearchParams","set","base","replace","toString","settleOverloaded","w","retryAfterMs","undefined","entry","find","p","filter","resolvePending","matches","remaining","type","push","failPending","runSocket","c","ws","abort","AbortController","Promise","timer","ReturnType","setTimeout","timedOut","outcome","closed","arm","clearTimeout","close","heartbeatTimeoutMs","signal","addEventListener","onerror","stale","Boolean","aborted","fail","processEnv","env","done","ack","res","seqs","Set","map","r","has","onmessage","event","frame","overloaded","JSON","parse","String","data","onclose","attemptSocket","ctx","throwIfAborted","protocols","webSocket","WS","globalThis","extra","sendCommand","command","readyState","send","stringify","method","useWsLink","onChange","attemptOnce","link","connection","args","useStatewireWS","StatewireWS","Commands","TState","TCommands","TEvent"],"sources":["../../src/transports/ws.ts"],"sourcesContent":["import { useState } from \"react\";\nimport { flushTapSync, resource } from \"@assistant-ui/tap\";\nimport type { ResourceElement } from \"@assistant-ui/tap\";\nimport { encodeParams } from \"../wire/meta\";\nimport { timing } from \"../client/timing\";\nimport {\n  handleEnvelope,\n  overloadedError,\n  useStatewireConn,\n} from \"../client/connection\";\nimport type { Conn, StatewireEnvelope } from \"../client/connection\";\nimport type { Statewire } from \"../types\";\nimport type { StatewireClient } from \"../statewire\";\nimport { useStatewireRemote } from \"./remote\";\nimport { CLIENT_QUERY_PARAM } from \"../host/adapter\";\nimport type {\n  RemoteLink,\n  StatewireSubmitResult,\n  StatewireRemoteProps,\n  StatewireWireCommand,\n} from \"./sse\";\n\ntype PendingCommand = {\n  seq: number;\n  resolve: (result: StatewireSubmitResult) => void;\n  reject: (error: Error) => void;\n};\n\ntype WsChannel = {\n  socket: WebSocket | null;\n  pending: PendingCommand[];\n};\n\nconst OPEN = 1;\n\nexport const WS_SUBPROTOCOL = \"statewire.v1\";\n\nconst socketUrl = async (\n  options: StatewireClient.WSOptions,\n  clientId: string,\n) => {\n  const { url, query } = options;\n  const params = new URLSearchParams(\n    typeof query === \"function\" ? await query() : query,\n  );\n  params.set(CLIENT_QUERY_PARAM, clientId);\n  const base = url.replace(/\\/$/, \"\").replace(/^http/, \"ws\");\n  return `${base}/ws?${params.toString()}`;\n};\n\nconst settleOverloaded = (\n  w: WsChannel,\n  { seq, retryAfterMs }: { seq?: number; retryAfterMs?: number },\n) => {\n  if (seq === undefined) throw overloadedError(retryAfterMs);\n  const entry = w.pending.find((p) => p.seq === seq);\n  if (!entry) return;\n  w.pending = w.pending.filter((p) => p !== entry);\n  entry.reject(overloadedError(retryAfterMs));\n};\n\nconst resolvePending = (\n  w: WsChannel,\n  matches: (entry: PendingCommand) => boolean,\n) => {\n  const remaining: PendingCommand[] = [];\n  for (const entry of w.pending) {\n    if (matches(entry)) entry.resolve({ type: \"receipt\" });\n    else remaining.push(entry);\n  }\n  w.pending = remaining;\n};\n\nconst failPending = (w: WsChannel, error: Error) => {\n  const pending = w.pending;\n  w.pending = [];\n  for (const entry of pending) entry.reject(error);\n};\n\nconst runSocket = (\n  c: Conn,\n  w: WsChannel,\n  ws: WebSocket,\n  abort: AbortController,\n): Promise<\"stop\" | \"reattach\"> =>\n  new Promise((resolve, reject) => {\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let timedOut = false;\n    let outcome: \"stop\" | \"reattach\" | null = null;\n    let closed = false;\n    const arm = () => {\n      clearTimeout(timer);\n      timer = setTimeout(() => {\n        timedOut = true;\n        ws.close();\n      }, timing.heartbeatTimeoutMs);\n    };\n    arm();\n    abort.signal.addEventListener(\"abort\", () => ws.close());\n    ws.onerror = () => {};\n    const stale = () => Boolean(outcome) || closed || abort.signal.aborted;\n    const fail = (error: unknown) => {\n      clearTimeout(timer);\n      reject(error instanceof Error ? error : new Error(\"protocol\"));\n      ws.close();\n    };\n    const processEnv = (env: StatewireEnvelope) => {\n      const done = flushTapSync(() => handleEnvelope(c, env));\n      if (env.ack !== undefined) {\n        const ack = env.ack;\n        resolvePending(w, (entry) => entry.seq <= ack);\n      }\n      if (env.res !== undefined) {\n        const seqs = new Set(env.res.map((r) => r.seq));\n        resolvePending(w, (entry) => seqs.has(entry.seq));\n      }\n      if (done) {\n        outcome = done;\n        ws.close();\n      }\n    };\n    ws.onmessage = (event) => {\n      if (stale()) return;\n      arm();\n      let frame: StatewireEnvelope & {\n        overloaded?: { seq?: number; retryAfterMs?: number };\n      };\n      try {\n        frame = JSON.parse(String(event.data)) as typeof frame;\n      } catch {\n        fail(new Error(\"protocol\"));\n        return;\n      }\n      try {\n        if (frame.overloaded !== undefined) {\n          settleOverloaded(w, frame.overloaded);\n        } else {\n          processEnv(frame);\n        }\n      } catch (error) {\n        fail(error);\n      }\n    };\n    ws.onclose = () => {\n      closed = true;\n      clearTimeout(timer);\n      if (w.socket === ws) failPending(w, new Error(\"network\"));\n      if (outcome) resolve(outcome);\n      else reject(new Error(timedOut ? \"timeout\" : \"network\"));\n    };\n  });\n\nconst attemptSocket = async (\n  c: Conn,\n  w: WsChannel,\n  options: StatewireClient.WSOptions,\n  abort: AbortController,\n): Promise<\"stop\" | \"reattach\"> => {\n  let ws: WebSocket | null = null;\n  try {\n    const url = await socketUrl(options, c.ctx.clientId);\n    abort.signal.throwIfAborted();\n    const { protocols, webSocket } = options;\n    const WS = webSocket ?? globalThis.WebSocket;\n    if (!WS) throw new Error(\"no WebSocket implementation\");\n    const extra =\n      protocols === undefined\n        ? []\n        : typeof protocols === \"string\"\n          ? [protocols]\n          : protocols;\n    ws = new WS(url, [WS_SUBPROTOCOL, ...extra]);\n    w.socket = ws;\n    return await runSocket(c, w, ws, abort);\n  } finally {\n    if (w.socket === ws) w.socket = null;\n  }\n};\n\nconst sendCommand = (\n  w: WsChannel,\n  { seq, command }: { seq: number; command: StatewireWireCommand },\n): Promise<StatewireSubmitResult> => {\n  const ws = w.socket;\n  if (!ws || ws.readyState !== OPEN) {\n    return Promise.reject(new Error(\"network\"));\n  }\n  return new Promise((resolve, reject) => {\n    const entry: PendingCommand = {\n      seq,\n      resolve: (result) => {\n        clearTimeout(timer);\n        resolve(result);\n      },\n      reject: (error) => {\n        clearTimeout(timer);\n        reject(error);\n      },\n    };\n    // A timed-out command fails the socket: the retry then rides reconnect +\n    // attach-seq arbitration.\n    const timer = setTimeout(() => {\n      w.pending = w.pending.filter((p) => p !== entry);\n      reject(new Error(\"timeout\"));\n      ws.close();\n    }, timing.heartbeatTimeoutMs);\n    w.pending.push(entry);\n    try {\n      ws.send(\n        JSON.stringify({\n          method: command.method,\n          ...encodeParams(command.params),\n          seq,\n        }),\n      );\n    } catch {\n      clearTimeout(timer);\n      w.pending = w.pending.filter((p) => p !== entry);\n      reject(new Error(\"network\"));\n    }\n  });\n};\n\nconst useWsLink = (\n  options: StatewireClient.WSOptions,\n  ctx: StatewireRemoteProps,\n): RemoteLink => {\n  const [w] = useState((): WsChannel => ({ socket: null, pending: [] }));\n  const c = useStatewireConn({\n    url: options.url,\n    onChange: options.onChange,\n    ctx,\n    attemptOnce: (c, abort) => attemptSocket(c, w, options, abort),\n  });\n  const [link] = useState(\n    (): RemoteLink => ({\n      get connection() {\n        return c.connection;\n      },\n      send: (args) => sendCommand(w, args),\n    }),\n  );\n  return link;\n};\n\nconst useStatewireWS = (\n  options: StatewireClient.WSOptions,\n): Statewire<any, any, any> => useStatewireRemote(options, useWsLink);\n\nexport const StatewireWS = resource(useStatewireWS) as <\n  TState = any,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n  TEvent = any,\n>(\n  options: StatewireClient.WSOptions,\n) => ResourceElement<Statewire<TState | undefined, TCommands, TEvent>>;\n"],"mappings":"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"}
+{"version":3,"file":"ws.js","names":["useState","flushTapSync","resource","ResourceElement","timing","handleEnvelope","overloadedError","useStatewireConn","Conn","StatewireEnvelope","Statewire","StatewireClient","useStatewireRemote","CLIENT_QUERY_PARAM","encodeWireCommand","RemoteLink","StatewireSubmitResult","StatewireRemoteProps","StatewireWireCommand","PendingCommand","seq","resolve","result","reject","error","Error","WsChannel","socket","WebSocket","pending","OPEN","WS_SUBPROTOCOL","socketUrl","options","WSOptions","clientId","url","query","params","URLSearchParams","set","base","replace","toString","settleOverloaded","w","retryAfterMs","undefined","entry","find","p","filter","resolvePending","matches","remaining","type","push","failPending","runSocket","c","ws","abort","AbortController","Promise","timer","ReturnType","setTimeout","timedOut","outcome","closed","arm","clearTimeout","close","heartbeatTimeoutMs","signal","addEventListener","onerror","stale","Boolean","aborted","fail","processEnv","env","done","ack","res","seqs","Set","map","r","has","onmessage","event","frame","overloaded","JSON","parse","String","data","onclose","attemptSocket","ctx","throwIfAborted","protocols","webSocket","WS","globalThis","extra","sendCommand","command","readyState","send","stringify","useWsLink","onChange","attemptOnce","link","connection","args","useStatewireWS","StatewireWS","Commands","TState","TCommands","TEvent"],"sources":["../../src/transports/ws.ts"],"sourcesContent":["import { useState } from \"react\";\nimport { flushTapSync, resource } from \"@assistant-ui/tap\";\nimport type { ResourceElement } from \"@assistant-ui/tap\";\nimport { timing } from \"../client/timing\";\nimport {\n  handleEnvelope,\n  overloadedError,\n  useStatewireConn,\n} from \"../client/connection\";\nimport type { Conn, StatewireEnvelope } from \"../client/connection\";\nimport type { Statewire } from \"../types\";\nimport type { StatewireClient } from \"../statewire\";\nimport { useStatewireRemote } from \"./remote\";\nimport { CLIENT_QUERY_PARAM } from \"../host/adapter\";\nimport { encodeWireCommand } from \"./sse\";\nimport type {\n  RemoteLink,\n  StatewireSubmitResult,\n  StatewireRemoteProps,\n  StatewireWireCommand,\n} from \"./sse\";\n\ntype PendingCommand = {\n  seq: number;\n  resolve: (result: StatewireSubmitResult) => void;\n  reject: (error: Error) => void;\n};\n\ntype WsChannel = {\n  socket: WebSocket | null;\n  pending: PendingCommand[];\n};\n\nconst OPEN = 1;\n\nexport const WS_SUBPROTOCOL = \"statewire.v1\";\n\nconst socketUrl = async (\n  options: StatewireClient.WSOptions,\n  clientId: string,\n) => {\n  const { url, query } = options;\n  const params = new URLSearchParams(\n    typeof query === \"function\" ? await query() : query,\n  );\n  params.set(CLIENT_QUERY_PARAM, clientId);\n  const base = url.replace(/\\/$/, \"\").replace(/^http/, \"ws\");\n  return `${base}/ws?${params.toString()}`;\n};\n\nconst settleOverloaded = (\n  w: WsChannel,\n  { seq, retryAfterMs }: { seq?: number; retryAfterMs?: number },\n) => {\n  if (seq === undefined) throw overloadedError(retryAfterMs);\n  const entry = w.pending.find((p) => p.seq === seq);\n  if (!entry) return;\n  w.pending = w.pending.filter((p) => p !== entry);\n  entry.reject(overloadedError(retryAfterMs));\n};\n\nconst resolvePending = (\n  w: WsChannel,\n  matches: (entry: PendingCommand) => boolean,\n) => {\n  const remaining: PendingCommand[] = [];\n  for (const entry of w.pending) {\n    if (matches(entry)) entry.resolve({ type: \"receipt\" });\n    else remaining.push(entry);\n  }\n  w.pending = remaining;\n};\n\nconst failPending = (w: WsChannel, error: Error) => {\n  const pending = w.pending;\n  w.pending = [];\n  for (const entry of pending) entry.reject(error);\n};\n\nconst runSocket = (\n  c: Conn,\n  w: WsChannel,\n  ws: WebSocket,\n  abort: AbortController,\n): Promise<\"stop\" | \"reattach\"> =>\n  new Promise((resolve, reject) => {\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let timedOut = false;\n    let outcome: \"stop\" | \"reattach\" | null = null;\n    let closed = false;\n    const arm = () => {\n      clearTimeout(timer);\n      timer = setTimeout(() => {\n        timedOut = true;\n        ws.close();\n      }, timing.heartbeatTimeoutMs);\n    };\n    arm();\n    abort.signal.addEventListener(\"abort\", () => ws.close());\n    ws.onerror = () => {};\n    const stale = () => Boolean(outcome) || closed || abort.signal.aborted;\n    const fail = (error: unknown) => {\n      clearTimeout(timer);\n      reject(error instanceof Error ? error : new Error(\"protocol\"));\n      ws.close();\n    };\n    const processEnv = (env: StatewireEnvelope) => {\n      const done = flushTapSync(() => handleEnvelope(c, env));\n      if (env.ack !== undefined) {\n        const ack = env.ack;\n        resolvePending(w, (entry) => entry.seq <= ack);\n      }\n      if (env.res !== undefined) {\n        const seqs = new Set(env.res.map((r) => r.seq));\n        resolvePending(w, (entry) => seqs.has(entry.seq));\n      }\n      if (done) {\n        outcome = done;\n        ws.close();\n      }\n    };\n    ws.onmessage = (event) => {\n      if (stale()) return;\n      arm();\n      let frame: StatewireEnvelope & {\n        overloaded?: { seq?: number; retryAfterMs?: number };\n      };\n      try {\n        frame = JSON.parse(String(event.data)) as typeof frame;\n      } catch {\n        fail(new Error(\"protocol\"));\n        return;\n      }\n      try {\n        if (frame.overloaded !== undefined) {\n          settleOverloaded(w, frame.overloaded);\n        } else {\n          processEnv(frame);\n        }\n      } catch (error) {\n        fail(error);\n      }\n    };\n    ws.onclose = () => {\n      closed = true;\n      clearTimeout(timer);\n      if (w.socket === ws) failPending(w, new Error(\"network\"));\n      if (outcome) resolve(outcome);\n      else reject(new Error(timedOut ? \"timeout\" : \"network\"));\n    };\n  });\n\nconst attemptSocket = async (\n  c: Conn,\n  w: WsChannel,\n  options: StatewireClient.WSOptions,\n  abort: AbortController,\n): Promise<\"stop\" | \"reattach\"> => {\n  let ws: WebSocket | null = null;\n  try {\n    const url = await socketUrl(options, c.ctx.clientId);\n    abort.signal.throwIfAborted();\n    const { protocols, webSocket } = options;\n    const WS = webSocket ?? globalThis.WebSocket;\n    if (!WS) throw new Error(\"no WebSocket implementation\");\n    const extra =\n      protocols === undefined\n        ? []\n        : typeof protocols === \"string\"\n          ? [protocols]\n          : protocols;\n    ws = new WS(url, [WS_SUBPROTOCOL, ...extra]);\n    w.socket = ws;\n    return await runSocket(c, w, ws, abort);\n  } finally {\n    if (w.socket === ws) w.socket = null;\n  }\n};\n\nconst sendCommand = (\n  w: WsChannel,\n  { seq, command }: { seq: number; command: StatewireWireCommand },\n): Promise<StatewireSubmitResult> => {\n  const ws = w.socket;\n  if (!ws || ws.readyState !== OPEN) {\n    return Promise.reject(new Error(\"network\"));\n  }\n  return new Promise((resolve, reject) => {\n    const entry: PendingCommand = {\n      seq,\n      resolve: (result) => {\n        clearTimeout(timer);\n        resolve(result);\n      },\n      reject: (error) => {\n        clearTimeout(timer);\n        reject(error);\n      },\n    };\n    // A timed-out command fails the socket: the retry then rides reconnect +\n    // attach-seq arbitration.\n    const timer = setTimeout(() => {\n      w.pending = w.pending.filter((p) => p !== entry);\n      reject(new Error(\"timeout\"));\n      ws.close();\n    }, timing.heartbeatTimeoutMs);\n    w.pending.push(entry);\n    try {\n      ws.send(JSON.stringify({ ...encodeWireCommand(command), seq }));\n    } catch {\n      clearTimeout(timer);\n      w.pending = w.pending.filter((p) => p !== entry);\n      reject(new Error(\"network\"));\n    }\n  });\n};\n\nconst useWsLink = (\n  options: StatewireClient.WSOptions,\n  ctx: StatewireRemoteProps,\n): RemoteLink => {\n  const [w] = useState((): WsChannel => ({ socket: null, pending: [] }));\n  const c = useStatewireConn({\n    url: options.url,\n    onChange: options.onChange,\n    ctx,\n    attemptOnce: (c, abort) => attemptSocket(c, w, options, abort),\n  });\n  const [link] = useState(\n    (): RemoteLink => ({\n      get connection() {\n        return c.connection;\n      },\n      send: (args) => sendCommand(w, args),\n    }),\n  );\n  return link;\n};\n\nconst useStatewireWS = (\n  options: StatewireClient.WSOptions,\n): Statewire<any, any, any> => useStatewireRemote(options, useWsLink);\n\nexport const StatewireWS = resource(useStatewireWS) as <\n  TState = any,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n  TEvent = any,\n>(\n  options: StatewireClient.WSOptions,\n) => ResourceElement<Statewire<TState | undefined, TCommands, TEvent>>;\n"],"mappings":"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"}

package/dist/types.d.ts

@@ -50,6 +50,8 @@ interface Statewire<TState = any, TCommands extends Statewire.Commands = Statewi
   emit?: (event: TEvent) => void;
   connection?: StatewireClient.Connection;
   source?: Statewire.StateSource;
+  /** Replace this client's ambient context on the server; absent on transports without a client context channel. */
+  setContext?: (value: Record<string, unknown>) => Promise<unknown>;
 }
 declare class StatewireSendError extends Error {
   readonly failure: StatewireClient.SendFailure;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;kBAGiB;OACH,WAAW,mBAAmB;OAE9B,QAAQ,kBAAkB,WAAW,eAC9C,WAAW;IAAc,QAAQ;IAAG,QAAQ,WAAW,UAAU;aAC5D;OAEI,cAAc,kBAAkB,eACzC,WAAW,gBACP,MAAM,WAAW,UAAU,QAC3B,QAAQ,QAAQ,WAAW,UAAU;OAGhC,cAAc,kBAAkB,WAAW,eACpD,WAAW;IACV,QAAQ;IACR,QAAQ,WAAW,UAAU;IAC7B;IACA;IACA;IACA,UAAU,gBAAgB;aAEtB;;OAGI;IACV;;IAEA,mBAAmB;;IAEnB,cAAc;;OAGJ;IACN;IAAe,MAAM;IAAe;;IACpC;IAAW,MAAM;IAAe;;IAChC;IAAc,MAAM;;IACpB;IAAa;;OAEP;IACV,YAAY;IACZ,eAAe;;;UAIF,UACf,cACA,kBAAkB,UAAU,WAAW,UAAU,UACjD;EAEA,OAAO;EACP,UAAU,UAAU,cAAc;EAClC,QAAQ,OAAO;EACf,aAAa,gBAAgB;EAC7B,SAAS,UAAU;;cAsBR,2BAA2B;WAC7B,SAAS,gBAAgB;EAEtB,YAAA,SAAS,gBAAgB"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;kBAGiB;OACH,WAAW,mBAAmB;OAE9B,QAAQ,kBAAkB,WAAW,eAC9C,WAAW;IAAc,QAAQ;IAAG,QAAQ,WAAW,UAAU;aAC5D;OAEI,cAAc,kBAAkB,eACzC,WAAW,gBACP,MAAM,WAAW,UAAU,QAC3B,QAAQ,QAAQ,WAAW,UAAU;OAGhC,cAAc,kBAAkB,WAAW,eACpD,WAAW;IACV,QAAQ;IACR,QAAQ,WAAW,UAAU;IAC7B;IACA;IACA;IACA,UAAU,gBAAgB;aAEtB;;OAGI;IACV;;IAEA,mBAAmB;;IAEnB,cAAc;;OAGJ;IACN;IAAe,MAAM;IAAe;;IACpC;IAAW,MAAM;IAAe;;IAChC;IAAc,MAAM;;IACpB;IAAa;;OAEP;IACV,YAAY;IACZ,eAAe;;;UAIF,UACf,cACA,kBAAkB,UAAU,WAAW,UAAU,UACjD;EAEA,OAAO;EACP,UAAU,UAAU,cAAc;EAClC,QAAQ,OAAO;EACf,aAAa,gBAAgB;EAC7B,SAAS,UAAU;;EAEnB,cAAc,OAAO,4BAA4B;;cAsBtC,2BAA2B;WAC7B,SAAS,gBAAgB;EAEtB,YAAA,SAAS,gBAAgB"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":["StatewireClient","StatewirePath","Statewire","Commands","Record","args","Command","TCommands","method","K","params","Parameters","CommandsProxy","Promise","Awaited","ReturnType","CommandUpdate","seq","status","result","failure","SendFailure","StateSource","snapshot","takeChanged","setOnChange","listener","Op","op","path","value","Changes","isChangedAt","getChangedKeys","state","TState","commands","emit","event","TEvent","connection","Connection","source","describe","fate","message","cause","StatewireSendError","Error","constructor","name"],"sources":["../src/types.ts"],"sourcesContent":["import type { StatewireClient } from \"./statewire\";\nimport type { StatewirePath } from \"./wire/ops\";\n\nexport namespace Statewire {\n  export type Commands = Record<string, (...args: never[]) => unknown>;\n\n  export type Command<TCommands extends Commands = Commands> = {\n    [K in keyof TCommands]: { method: K; params: Parameters<TCommands[K]> };\n  }[keyof TCommands];\n\n  export type CommandsProxy<TCommands extends Commands> = {\n    [K in keyof TCommands]: (\n      ...args: Parameters<TCommands[K]>\n    ) => Promise<Awaited<ReturnType<TCommands[K]>>>;\n  };\n\n  export type CommandUpdate<TCommands extends Commands = Commands> = {\n    [K in keyof TCommands]: {\n      method: K;\n      params: Parameters<TCommands[K]>;\n      seq: number;\n      status: \"queued\" | \"posted\" | \"acked\" | \"settled\";\n      result?: unknown;\n      failure?: StatewireClient.SendFailure;\n    };\n  }[keyof TCommands];\n\n  /** Push-based canonical state feed a statewire hands to the client core. */\n  export type StateSource = {\n    snapshot: () => unknown;\n    /** Drain the paths changed since the last take (`[]` entry = whole state). */\n    takeChanged: () => StatewirePath[];\n    /** Synchronous, per change; the consumer owns coalescing. */\n    setOnChange: (listener: (() => void) | null) => void;\n  };\n\n  export type Op =\n    | { op: \"replace\"; path: StatewirePath; value: unknown }\n    | { op: \"add\"; path: StatewirePath; value: unknown }\n    | { op: \"remove\"; path: StatewirePath }\n    | { op: \"event\"; value: object };\n\n  export type Changes = {\n    isChangedAt(path: readonly (string | number)[]): boolean;\n    getChangedKeys(path: readonly (string | number)[]): string[];\n  };\n}\n\nexport interface Statewire<\n  TState = any,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n  TEvent = any,\n> {\n  state: TState;\n  commands: Statewire.CommandsProxy<TCommands>;\n  emit?: (event: TEvent) => void;\n  connection?: StatewireClient.Connection;\n  source?: Statewire.StateSource;\n}\n\nconst describe = (failure: StatewireClient.SendFailure): string => {\n  switch (failure.fate) {\n    case \"rejected\":\n      return `statewire: command rejected: ${failure.message}`;\n    case \"unknown-command\":\n      return \"statewire: unknown command\";\n    case \"invalid-params\":\n      return `statewire: invalid params: ${failure.message}`;\n    case \"aborted\":\n      return `statewire: command aborted (${failure.cause})`;\n    case \"lost\":\n      return `statewire: command lost (${failure.cause})`;\n    case \"crashed\":\n      return \"statewire: command crashed\";\n    case \"result-unavailable\":\n      return `statewire: command result unavailable (${failure.cause})`;\n  }\n};\n\nexport class StatewireSendError extends Error {\n  readonly failure: StatewireClient.SendFailure;\n\n  constructor(failure: StatewireClient.SendFailure) {\n    super(describe(failure));\n    this.name = \"StatewireSendError\";\n    this.failure = failure;\n  }\n}\n"],"mappings":";AA4DA,MAAM2C,YAAYvB,YAAiD;CACjE,QAAQA,QAAQwB,MAAhB;EACE,KAAK,YACH,OAAO,gCAAgCxB,QAAQyB;EACjD,KAAK,mBACH,OAAO;EACT,KAAK,kBACH,OAAO,8BAA8BzB,QAAQyB;EAC/C,KAAK,WACH,OAAO,+BAA+BzB,QAAQ0B,MAAK;EACrD,KAAK,QACH,OAAO,4BAA4B1B,QAAQ0B,MAAK;EAClD,KAAK,WACH,OAAO;EACT,KAAK,sBACH,OAAO,0CAA0C1B,QAAQ0B,MAAK;CAClE;AACF;AAEA,IAAaC,qBAAb,cAAwCC,MAAM;CAC5C;CAEAC,YAAY7B,SAAsC;EAChD,MAAMuB,SAASvB,OAAO,CAAC;EACvB,KAAK8B,OAAO;EACZ,KAAK9B,UAAUA;CACjB;AACF"}
+{"version":3,"file":"types.js","names":["StatewireClient","StatewirePath","Statewire","Commands","Record","args","Command","TCommands","method","K","params","Parameters","CommandsProxy","Promise","Awaited","ReturnType","CommandUpdate","seq","status","result","failure","SendFailure","StateSource","snapshot","takeChanged","setOnChange","listener","Op","op","path","value","Changes","isChangedAt","getChangedKeys","state","TState","commands","emit","event","TEvent","connection","Connection","source","setContext","describe","fate","message","cause","StatewireSendError","Error","constructor","name"],"sources":["../src/types.ts"],"sourcesContent":["import type { StatewireClient } from \"./statewire\";\nimport type { StatewirePath } from \"./wire/ops\";\n\nexport namespace Statewire {\n  export type Commands = Record<string, (...args: never[]) => unknown>;\n\n  export type Command<TCommands extends Commands = Commands> = {\n    [K in keyof TCommands]: { method: K; params: Parameters<TCommands[K]> };\n  }[keyof TCommands];\n\n  export type CommandsProxy<TCommands extends Commands> = {\n    [K in keyof TCommands]: (\n      ...args: Parameters<TCommands[K]>\n    ) => Promise<Awaited<ReturnType<TCommands[K]>>>;\n  };\n\n  export type CommandUpdate<TCommands extends Commands = Commands> = {\n    [K in keyof TCommands]: {\n      method: K;\n      params: Parameters<TCommands[K]>;\n      seq: number;\n      status: \"queued\" | \"posted\" | \"acked\" | \"settled\";\n      result?: unknown;\n      failure?: StatewireClient.SendFailure;\n    };\n  }[keyof TCommands];\n\n  /** Push-based canonical state feed a statewire hands to the client core. */\n  export type StateSource = {\n    snapshot: () => unknown;\n    /** Drain the paths changed since the last take (`[]` entry = whole state). */\n    takeChanged: () => StatewirePath[];\n    /** Synchronous, per change; the consumer owns coalescing. */\n    setOnChange: (listener: (() => void) | null) => void;\n  };\n\n  export type Op =\n    | { op: \"replace\"; path: StatewirePath; value: unknown }\n    | { op: \"add\"; path: StatewirePath; value: unknown }\n    | { op: \"remove\"; path: StatewirePath }\n    | { op: \"event\"; value: object };\n\n  export type Changes = {\n    isChangedAt(path: readonly (string | number)[]): boolean;\n    getChangedKeys(path: readonly (string | number)[]): string[];\n  };\n}\n\nexport interface Statewire<\n  TState = any,\n  TCommands extends Statewire.Commands = Statewire.Commands,\n  TEvent = any,\n> {\n  state: TState;\n  commands: Statewire.CommandsProxy<TCommands>;\n  emit?: (event: TEvent) => void;\n  connection?: StatewireClient.Connection;\n  source?: Statewire.StateSource;\n  /** Replace this client's ambient context on the server; absent on transports without a client context channel. */\n  setContext?: (value: Record<string, unknown>) => Promise<unknown>;\n}\n\nconst describe = (failure: StatewireClient.SendFailure): string => {\n  switch (failure.fate) {\n    case \"rejected\":\n      return `statewire: command rejected: ${failure.message}`;\n    case \"unknown-command\":\n      return \"statewire: unknown command\";\n    case \"invalid-params\":\n      return `statewire: invalid params: ${failure.message}`;\n    case \"aborted\":\n      return `statewire: command aborted (${failure.cause})`;\n    case \"lost\":\n      return `statewire: command lost (${failure.cause})`;\n    case \"crashed\":\n      return \"statewire: command crashed\";\n    case \"result-unavailable\":\n      return `statewire: command result unavailable (${failure.cause})`;\n  }\n};\n\nexport class StatewireSendError extends Error {\n  readonly failure: StatewireClient.SendFailure;\n\n  constructor(failure: StatewireClient.SendFailure) {\n    super(describe(failure));\n    this.name = \"StatewireSendError\";\n    this.failure = failure;\n  }\n}\n"],"mappings":";AA8DA,MAAM4C,YAAYxB,YAAiD;CACjE,QAAQA,QAAQyB,MAAhB;EACE,KAAK,YACH,OAAO,gCAAgCzB,QAAQ0B;EACjD,KAAK,mBACH,OAAO;EACT,KAAK,kBACH,OAAO,8BAA8B1B,QAAQ0B;EAC/C,KAAK,WACH,OAAO,+BAA+B1B,QAAQ2B,MAAK;EACrD,KAAK,QACH,OAAO,4BAA4B3B,QAAQ2B,MAAK;EAClD,KAAK,WACH,OAAO;EACT,KAAK,sBACH,OAAO,0CAA0C3B,QAAQ2B,MAAK;CAClE;AACF;AAEA,IAAaC,qBAAb,cAAwCC,MAAM;CAC5C;CAEAC,YAAY9B,SAAsC;EAChD,MAAMwB,SAASxB,OAAO,CAAC;EACvB,KAAK+B,OAAO;EACZ,KAAK/B,UAAUA;CACjB;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "statewire",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "State over the wire: snapshot-first delta streaming and command submission for any state and any command",
   "license": "MIT",
   "repository": {

package/src/client/session.ts

@@ -40,7 +40,8 @@ type PendingState =
 type Pending = {
   readonly seq: number;
   readonly command: StatewireWireCommand;
-  readonly inv: CommandsInvocation;
+  /** null for context submissions — they carry no command lifecycle. */
+  readonly inv: CommandsInvocation | null;
   state: PendingState;
   resolve: (payload: unknown) => void;
   reject: (error: StatewireSendError) => void;
@@ -102,20 +103,22 @@ const transition = (
   }
   const covers = !isStateSettled(prev) && isStateSettled(next);
   entry.state = next;
-  if (covers) s.lifecycle?.onCovered?.(entry.inv);
+  if (covers && entry.inv) s.lifecycle?.onCovered?.(entry.inv);
   if (settles && outcome !== undefined) {
     if (outcome.ok) {
       entry.resolve(outcome.payload);
-      s.lifecycle?.onSettle(entry.inv, {
-        type: "accepted",
-        payload: outcome.payload,
-      });
+      if (entry.inv)
+        s.lifecycle?.onSettle(entry.inv, {
+          type: "accepted",
+          payload: outcome.payload,
+        });
     } else {
       entry.reject(new StatewireSendError(outcome.failure));
-      s.lifecycle?.onSettle(entry.inv, {
-        type: "rejected",
-        error: new StatewireSendError(outcome.failure),
-      });
+      if (entry.inv)
+        s.lifecycle?.onSettle(entry.inv, {
+          type: "rejected",
+          error: new StatewireSendError(outcome.failure),
+        });
     }
   }
   if (next.at === "done") {
@@ -150,6 +153,7 @@ type Session = {
   recordPersisted: boolean;
   store: StatewireSessionStore;
   lastAck: number;
+  context: Record<string, unknown> | undefined;
   pending: Pending[];
   canonical: unknown;
   lastPublished: unknown;
@@ -185,6 +189,7 @@ const createSession = (options: StatewireSessionStoreOptions): Session => {
     recordPersisted: stored !== null,
     store,
     lastAck: -1,
+    context: undefined,
     pending: [],
     canonical: undefined,
     lastPublished: undefined,
@@ -294,6 +299,9 @@ const evict = (
   s.record = { clientId: newClientId(), nextSeq: 1 };
   s.store.save(s.record);
   s.attach = "detached";
+  // The server dropped this client's record and its stored context with it:
+  // the new session opens with a fresh full root replace.
+  if (s.context !== undefined) void s.send({ context: s.context });
   publish(s);
   wake(s);
 };
@@ -301,7 +309,7 @@ const evict = (
 const noteAcked = (s: Session, seq: number) => {
   for (const entry of s.pending) {
     if (entry.seq > seq || isStateSettled(entry.state)) continue;
-    s.lifecycle?.onAck(entry.inv);
+    if (entry.inv) s.lifecycle?.onAck(entry.inv);
   }
 };
 
@@ -546,7 +554,7 @@ const pump = async (s: Session) => {
         ) {
           transition(s, entry, { ...state, posted: true });
         }
-        s.lifecycle?.onPosted?.(entry.inv);
+        if (entry.inv) s.lifecycle?.onPosted?.(entry.inv);
         if (response !== undefined) {
           applyResponse(s, response);
           publish(s);
@@ -653,13 +661,16 @@ const sendCommand = (
   const entry: Pending = {
     seq,
     command,
-    inv: {
-      method: command.method,
-      params: command.params,
-      ts: Date.now(),
-      seq,
-      clientId: s.record.clientId,
-    },
+    inv:
+      command.method === undefined
+        ? null
+        : {
+            method: command.method,
+            params: command.params,
+            ts: Date.now(),
+            seq,
+            clientId: s.record.clientId,
+          },
     state: { at: "queued", pendingMarked: false },
     resolve: () => {},
     reject: () => {},
@@ -670,11 +681,22 @@ const sendCommand = (
   });
   result.catch(() => {});
   s.pending.push(entry);
-  s.lifecycle?.onStart(entry.inv);
+  if (entry.inv) s.lifecycle?.onStart(entry.inv);
   void pump(s);
   return result;
 };
 
+const setContext = (
+  s: Session,
+  value: Record<string, unknown>,
+): Promise<unknown> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("statewire: context must be a plain object");
+  }
+  s.context = value;
+  return s.send({ context: value });
+};
+
 export const useStatewireSession = (
   options: StatewireSessionStoreOptions,
   emit: (event: unknown) => void,
@@ -693,4 +715,4 @@ export const useStatewireSession = (
   return s;
 };
 
-export { setTransport };
+export { setContext, setTransport };

package/src/host/host.ts

@@ -203,6 +203,7 @@ export type CommandsSubmission = {
   method: string;
   params: readonly unknown[];
   clientId?: string;
+  caller?: StatewireHost.Caller;
   onAck?: () => void;
   onSettle?: (outcome: CommandsOutcome) => void;
 };
@@ -247,6 +248,12 @@ type CommandsCell = {
 
 const STALL_WARN_MS = 5000;
 
+// In-process dispatch has no wire client: never any ambient context, trivially attached.
+const LOCAL_CALLER: StatewireHost.Caller = Object.freeze({
+  context: null,
+  isConnected: true,
+});
+
 const toSendError = (error: unknown): StatewireSendError =>
   error instanceof StatewireSendError
     ? error
@@ -324,9 +331,9 @@ const pump = (cell: CommandsCell) => {
   cell.listener?.onCovered?.(inv);
   void (async () => {
     try {
-      const value = await (handler as (...args: readonly unknown[]) => unknown)(
-        ...call.params,
-      );
+      const value = await (
+        handler as (...args: readonly unknown[]) => unknown
+      ).call(call.origin?.caller ?? LOCAL_CALLER, ...call.params);
       const execution =
         typeof value === "object" && value !== null
           ? executionStates.get(value)
@@ -367,7 +374,11 @@ const watchStall = (cell: CommandsCell) => {
 };
 
 export const useStatewireCommands = <THandlers extends Statewire.Commands>(
-  commands: THandlers | undefined | null | false,
+  commands:
+    | (THandlers & ThisType<StatewireHost.Caller>)
+    | undefined
+    | null
+    | false,
 ): Statewire.CommandsProxy<StatewireHost.HandledCommands<THandlers>> => {
   const [built] = useState(() => {
     const cell: CommandsCell = {

package/src/host/socket.ts

@@ -40,6 +40,7 @@ type Admission = {
 type ClientRec = {
   id: string;
   lastSeq: number;
+  context: Record<string, unknown> | null;
   results: Map<number, { ts: number; res: StatewireResponse }>;
   inflight: Map<number, Admission>;
 };
@@ -51,7 +52,12 @@ type Conn = {
   lastSentAt: number;
 };
 
-type Frame = { method: string; seq: number; params: unknown[] };
+type Frame = {
+  method?: string;
+  seq: number;
+  params: unknown[];
+  context?: unknown;
+};
 
 const parseFrame = (raw: string): Frame | null => {
   let frame: unknown;
@@ -63,9 +69,16 @@ const parseFrame = (raw: string): Frame | null => {
   if (typeof frame !== "object" || frame === null || Array.isArray(frame)) {
     return null;
   }
-  const { method, seq, params, meta } = frame as Record<string, unknown>;
-  if (typeof method !== "string") return null;
+  const { method, seq, params, meta, context } = frame as Record<
+    string,
+    unknown
+  >;
+  if (method === undefined && context === undefined) return null;
   if (typeof seq !== "number" || !Number.isInteger(seq) || seq < 1) return null;
+  if (method === undefined) {
+    return { seq, params: [], ...(context !== undefined && { context }) };
+  }
+  if (typeof method !== "string") return null;
   if (!Array.isArray(params)) return null;
   if (meta !== undefined) {
     try {
@@ -74,7 +87,29 @@ const parseFrame = (raw: string): Frame | null => {
       return null;
     }
   }
-  return { method, seq, params };
+  return { method, seq, params, ...(context !== undefined && { context }) };
+};
+
+/** v1 context submissions are exactly one root replace with an object value. */
+const contextValue = (context: unknown): Record<string, unknown> => {
+  if (!Array.isArray(context) || context.length !== 1) {
+    throw new Error("context must be a single-op array");
+  }
+  const op = context[0] as Record<string, unknown> | null;
+  if (
+    typeof op !== "object" ||
+    op === null ||
+    op["op"] !== "replace" ||
+    !Array.isArray(op["path"]) ||
+    op["path"].length !== 0
+  ) {
+    throw new Error("context op must be a root replace");
+  }
+  const value = op["value"];
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("context value must be an object");
+  }
+  return value as Record<string, unknown>;
 };
 
 const encodePayload = (
@@ -321,15 +356,14 @@ const createSocketHost = (
     return { seq, type: "result-unavailable" };
   };
 
-  const settleWire = (
+  const settleResponse = (
     rec: ClientRec,
     adm: Admission,
-    outcome: CommandsOutcome,
+    response: StatewireResponse,
   ) => {
     if (adm.settled) return;
     adm.settled = true;
     rec.inflight.delete(adm.seq);
-    const response = responseOf(adm, outcome);
     retain(rec, response);
     if (!adm.acked) {
       adm.acked = true;
@@ -346,6 +380,25 @@ const createSocketHost = (
     adm.release();
   };
 
+  const settleWire = (
+    rec: ClientRec,
+    adm: Admission,
+    outcome: CommandsOutcome,
+  ) => settleResponse(rec, adm, responseOf(adm, outcome));
+
+  const callerOf = (rec: ClientRec): StatewireHost.Caller => ({
+    get context() {
+      return rec.context;
+    },
+    get isConnected() {
+      if (clients.get(rec.id) !== rec) return false;
+      for (const conn of conns) {
+        if (conn.clientId === rec.id && conn.open) return true;
+      }
+      return false;
+    },
+  });
+
   const admit = (conn: Conn, frame: Frame): Promise<void> | void => {
     if (!conn.open || disposed || finished !== null) return;
     const rec = clients.get(conn.clientId)!;
@@ -364,20 +417,42 @@ const createSocketHost = (
     }
     const adm: Admission = {
       seq: frame.seq,
-      method: frame.method,
+      method: frame.method ?? "",
       acked: false,
       pendingSent: false,
       settled: false,
       release: () => {},
     };
+    if (frame.context !== undefined) {
+      let value: Record<string, unknown>;
+      try {
+        value = contextValue(frame.context);
+      } catch (error) {
+        rec.inflight.set(frame.seq, adm);
+        settleResponse(rec, adm, {
+          seq: frame.seq,
+          type: "rejected",
+          code: "invalid-context",
+          message: `invalid context: ${(error as Error).message}`,
+        });
+        return;
+      }
+      rec.context = value;
+      if (frame.method === undefined) {
+        rec.inflight.set(frame.seq, adm);
+        settleResponse(rec, adm, { seq: frame.seq, type: "accepted" });
+        return;
+      }
+    }
     const released = new Promise<void>((resolve) => {
       adm.release = resolve;
     });
     rec.inflight.set(frame.seq, adm);
     commandsHost!.submit!({
-      method: frame.method,
+      method: frame.method!,
       params: frame.params,
       clientId: rec.id,
+      caller: callerOf(rec),
       onAck: () => {
         if (adm.settled || adm.acked) return;
         adm.acked = true;
@@ -437,6 +512,7 @@ const createSocketHost = (
           const created: ClientRec = {
             id: clientId,
             lastSeq: 0,
+            context: null,
             results: new Map(),
             inflight: new Map(),
           };

package/src/host.ts

@@ -46,6 +46,17 @@ export namespace StatewireHost {
     reject: (error: unknown) => void;
   };
 
+  /**
+   * The submitting client, bound as `this` of a command handler. Holdable
+   * across a long run: `context` reads the client's current ambient context
+   * live (null until the client sends one), `isConnected` reports whether the
+   * client has an active stream attachment.
+   */
+  export type Caller = {
+    readonly context: Record<string, unknown> | null;
+    readonly isConnected: boolean;
+  };
+
   export type HandledCommands<THandlers extends Statewire.Commands> = {
     [K in keyof THandlers]: (
       ...args: Parameters<THandlers[K]>

package/src/statewire.ts

@@ -41,8 +41,16 @@ export const useStatewire = <
       getState: core.getState as () => TState,
       connection,
       commands: core.commands as Statewire.CommandsProxy<TCommands>,
+      setContext: (contextValue: Record<string, unknown>) => {
+        if (!value.setContext) {
+          throw new Error(
+            "statewire: this transport has no client context channel",
+          );
+        }
+        return value.setContext(contextValue);
+      },
     }),
-    [state, connection, core],
+    [state, connection, core, value],
   );
 };
 
@@ -80,6 +88,10 @@ export class StatewireClient<
     return this.root.getValue().commands;
   }
 
+  setContext(value: Record<string, unknown>): Promise<unknown> {
+    return this.root.getValue().setContext(value);
+  }
+
   subscribe(listener: () => void): () => void {
     return this.root.subscribe(listener);
   }
@@ -120,6 +132,8 @@ export namespace StatewireClient {
     getState: () => TState;
     connection: Connection;
     commands: Statewire.CommandsProxy<TCommands>;
+    /** Replace this client's ambient context on the server; throws on transports without a client context channel. */
+    setContext: (value: Record<string, unknown>) => Promise<unknown>;
   };
 
   export type Connection = ConnectionState & { reconnect: () => void };

package/src/transports/remote.ts

@@ -1,7 +1,11 @@
 import { useEffect } from "react";
 import { useStatewireEmit } from "../host/host";
 import type { Statewire } from "../types";
-import { setTransport, useStatewireSession } from "../client/session";
+import {
+  setContext,
+  setTransport,
+  useStatewireSession,
+} from "../client/session";
 import type { StatewireSessionStoreOptions } from "../client/sessionStore";
 import type { StatewireClient } from "../statewire";
 import type { RemoteLink, StatewireRemoteProps } from "./sse";
@@ -26,5 +30,6 @@ export const useStatewireRemote = <
     emit,
     connection: conn.connection,
     source: s.source,
+    setContext: (value) => setContext(s, value),
   };
 };

package/src/transports/sse.ts

@@ -32,10 +32,24 @@ export type StatewireRemoteProps = {
   onFinish: (args: StatewireHost.Fin) => void;
 };
 
-export type StatewireWireCommand = {
-  method: string;
-  params: readonly unknown[];
-};
+export type StatewireWireCommand =
+  | { method: string; params: readonly unknown[]; context?: never }
+  | { method?: never; params?: never; context: Record<string, unknown> };
+
+/** The wire shape of a client context submission: one root replace op. */
+export const contextOps = (value: Record<string, unknown>) => [
+  { op: "replace", path: [], value },
+];
+
+export const encodeWireCommand = (command: StatewireWireCommand) => ({
+  ...(command.method !== undefined && {
+    method: command.method,
+    ...encodeParams(command.params),
+  }),
+  ...(command.context !== undefined && {
+    context: contextOps(command.context),
+  }),
+});
 
 export type StatewireSubmitResult =
   | { type: "receipt"; response?: StatewireResponse }
@@ -184,10 +198,7 @@ const sendCommand = async (
         "Statewire-Command-Seq": String(seq),
         ...(c.lease !== null && { "Statewire-Lease": c.lease }),
       }),
-      body: JSON.stringify({
-        method: command.method,
-        ...encodeParams(command.params),
-      }),
+      body: JSON.stringify(encodeWireCommand(command)),
       signal: AbortSignal.any([
         c.lifetime?.signal ?? AbortSignal.abort(),
         timeout,

package/src/transports/testing.ts

@@ -20,8 +20,8 @@ export const applyOptimistic = <TState>(
 export type MockTransport<TState> = {
   /** Pass as the `transport:` option of useStatewire / Harness. */
   transport: ResourceElement<Statewire<TState | undefined, any, any>>;
-  /** Captured `{ method, params }` command bodies, in POST order. */
-  commands: { method: string; params: unknown[] }[];
+  /** Captured `/commands` POST bodies, in POST order. */
+  commands: { method?: string; params?: unknown[]; context?: unknown }[];
   /** Replace the replicated state and broadcast it as a root snapshot op. */
   setState: (state: TState) => Promise<void>;
   /** Deliver an ack watermark on the stream. */
@@ -49,7 +49,7 @@ export const createMockTransport = <TState>(
   let finished = false;
   const clients = new Map<string, number>();
   const streams = new Set<FakeStreamHandle>();
-  const commands: { method: string; params: unknown[] }[] = [];
+  const commands: MockTransport<unknown>["commands"] = [];
 
   const sendEnvelope = (envelope: StatewireEnvelope) => {
     for (const stream of streams) stream.send(sseFrame(envelope));
@@ -86,7 +86,9 @@ export const createMockTransport = <TState>(
       const seq = Number(headers.get("Statewire-Command-Seq"));
       clients.set(id, Math.max(clients.get(id) ?? 0, seq));
       commands.push(
-        JSON.parse(String(init?.body)) as { method: string; params: unknown[] },
+        JSON.parse(
+          String(init?.body),
+        ) as MockTransport<unknown>["commands"][number],
       );
       return Response.json({});
     }

package/src/transports/ws.ts

@@ -1,7 +1,6 @@
 import { useState } from "react";
 import { flushTapSync, resource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
-import { encodeParams } from "../wire/meta";
 import { timing } from "../client/timing";
 import {
   handleEnvelope,
@@ -13,6 +12,7 @@ import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 import { useStatewireRemote } from "./remote";
 import { CLIENT_QUERY_PARAM } from "../host/adapter";
+import { encodeWireCommand } from "./sse";
 import type {
   RemoteLink,
   StatewireSubmitResult,
@@ -206,13 +206,7 @@ const sendCommand = (
     }, timing.heartbeatTimeoutMs);
     w.pending.push(entry);
     try {
-      ws.send(
-        JSON.stringify({
-          method: command.method,
-          ...encodeParams(command.params),
-          seq,
-        }),
-      );
+      ws.send(JSON.stringify({ ...encodeWireCommand(command), seq }));
     } catch {
       clearTimeout(timer);
       w.pending = w.pending.filter((p) => p !== entry);

package/src/types.ts

@@ -56,6 +56,8 @@ export interface Statewire<
   emit?: (event: TEvent) => void;
   connection?: StatewireClient.Connection;
   source?: Statewire.StateSource;
+  /** Replace this client's ambient context on the server; absent on transports without a client context channel. */
+  setContext?: (value: Record<string, unknown>) => Promise<unknown>;
 }
 
 const describe = (failure: StatewireClient.SendFailure): string => {