statewire 0.19.3 → 0.20.0

package/src/host/socket.ts

@@ -1,3 +1,5 @@
+import { contextValue, captureContext } from "../wire/context";
+import { MAX_CONTEXT_BYTES } from "../wire/limits";
 import { encodeDocument } from "../document";
 import {
   DEFAULT_PROTOCOL,
@@ -127,6 +129,7 @@ export type Conn = {
   /** The awaited `authorize` return captured at this attach's authorization. */
   auth: unknown;
   lanes: Map<string, Lane>;
+  contexts: Map<string, Statewire.Context>;
   documents: Map<string, StatewireHost.Document>;
   included: Set<string>;
   view: Map<string, { doc: number; value: unknown }>;
@@ -164,7 +167,10 @@ type CmdStatement = {
   meta?: unknown;
 };
 
-export type ParsedFrame = { cmd: CmdStatement[] };
+export type ParsedFrame = {
+  cmd: CmdStatement[];
+  ctx?: { protocol: string; value: Statewire.Context }[];
+};
 
 const isPlainObject = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
@@ -175,12 +181,13 @@ export const parseFrameValue = (frame: unknown): ParsedFrame => {
   if (!isPlainObject(frame)) return violation("malformed frame");
   const keys = Object.keys(frame);
   if (keys.length === 0) return violation("malformed frame");
-  const unknown = keys.filter((key) => key !== "cmd").sort();
+  const unknown = keys.filter((key) => key !== "cmd" && key !== "ctx").sort();
   if (unknown.length > 0)
     return violation(`unknown frame key: '${unknown[0]}'`);
-  const lane = frame["cmd"];
+  const lane = frame["cmd"] ?? [];
   if (!Array.isArray(lane)) return violation("malformed frame");
-  if (lane.length === 0) return violation("empty lane");
+  if (Object.hasOwn(frame, "cmd") && lane.length === 0)
+    return violation("empty lane");
   if (lane.length > MAX_COMMANDS_PER_FRAME)
     return violation("too many commands");
   const prev = new Map<string, number>();
@@ -212,7 +219,47 @@ export const parseFrameValue = (frame: unknown): ParsedFrame => {
       ...(statement["meta"] !== undefined && { meta: statement["meta"] }),
     });
   }
-  return { cmd };
+  const contexts = frame["ctx"];
+  const ctx: NonNullable<ParsedFrame["ctx"]> = [];
+  if (contexts !== undefined) {
+    if (!Array.isArray(contexts) || contexts.length === 0)
+      return violation("empty context lane");
+    const seen = new Set<string>();
+    for (const entry of contexts) {
+      if (
+        !isPlainObject(entry) ||
+        typeof entry["protocol"] !== "string" ||
+        !Object.hasOwn(entry, "value") ||
+        Object.keys(entry).some(
+          (key) => !["protocol", "value", "meta"].includes(key),
+        )
+      )
+        return violation("malformed context");
+      const protocol = entry["protocol"];
+      if (seen.has(protocol)) return violation("duplicate context protocol");
+      seen.add(protocol);
+      if (
+        frameEncoder.encode(JSON.stringify(entry)).byteLength >
+        MAX_CONTEXT_BYTES
+      )
+        return violation("context entry too large");
+      try {
+        ctx.push({
+          protocol,
+          value: contextValue({
+            value: entry["value"],
+            ...(entry["meta"] !== undefined && { meta: entry["meta"] }),
+          }),
+        });
+      } catch (error) {
+        return violation(
+          error instanceof Error ? error.message : "invalid context",
+        );
+      }
+    }
+  }
+  if (cmd.length === 0 && ctx.length === 0) return violation("empty frame");
+  return { cmd, ...(ctx.length > 0 && { ctx }) };
 };
 
 export const parseFrame = (raw: string): ParsedFrame => {
@@ -554,6 +601,13 @@ const attachOf = (h: SocketHostState, conn: Conn): StatewireHost.Attach => {
     return entry;
   };
   return {
+    get caller() {
+      return callerOf(h, h.clients.get(conn.clientId)!, conn);
+    },
+    context: (protocol) => {
+      requireSelected(protocol);
+      return captureContext(conn.contexts.get(protocol) ?? {});
+    },
     document: (protocol, key) => {
       if (key === undefined && protocol === h.protocol.name)
         return h.stateHost!.snapshot();
@@ -916,6 +970,7 @@ const admitCmd = (
     clientId: rec.id,
     caller: callerOf(h, rec, conn),
     attach: conn.attach,
+    context: captureContext(conn.contexts.get(statement.protocol) ?? {}),
     onApplied: () => {
       if (adm.settled || adm.applied) return;
       adm.applied = true;
@@ -959,11 +1014,65 @@ const refusal = (
   },
 });
 
+const validateContexts = (
+  h: SocketHostState,
+  conn: Conn,
+  frame: ParsedFrame,
+) => {
+  for (const statement of frame.cmd) {
+    if (!selects(conn, statement.protocol))
+      return violation("unsupported protocol");
+    const selected = conn.selection.protocols.find(
+      (p) => p.name === statement.protocol,
+    )!;
+    if (selected.record === "ephemeral") {
+      const through = watermark(h, conn, statement.protocol);
+      const first = frame.cmd.find(
+        (s) => s.protocol === statement.protocol && s.seq > through,
+      );
+      if (first && first.seq !== through + 1)
+        return violation("ephemeral lane gap");
+    }
+  }
+  for (const entry of frame.ctx ?? []) {
+    if (!selects(conn, entry.protocol))
+      return violation("unsupported context protocol");
+    try {
+      h.current?.validateContext?.(
+        entry.protocol,
+        captureContext(entry.value),
+        conn.attach,
+      );
+    } catch (error) {
+      return violation(
+        error instanceof Error ? error.message : "invalid context",
+      );
+    }
+  }
+};
+
+const installContexts = (
+  h: SocketHostState,
+  conn: Conn,
+  frame: ParsedFrame,
+) => {
+  for (const entry of frame.ctx ?? [])
+    conn.contexts.set(entry.protocol, captureContext(entry.value));
+  for (const entry of frame.ctx ?? [])
+    h.current?.contextChanged?.(
+      entry.protocol,
+      captureContext(entry.value),
+      conn.attach,
+    );
+};
+
 export const admitFrame = (
   h: SocketHostState,
   conn: Conn,
   frame: ParsedFrame,
 ): FrameAdmission => {
+  validateContexts(h, conn, frame);
+  installContexts(h, conn, frame);
   const rec = h.clients.get(conn.clientId)!;
   rec.touched = Date.now();
   const lanes = new Map(
@@ -1048,7 +1157,7 @@ const message = (h: SocketHostState, conn: Conn, data: string) => {
   let admission: ReturnType<typeof admitFrame>;
   try {
     const frame = first ? parseInitialFrame(data).frame : parseFrame(data);
-    if (frame.cmd.length === 0) return;
+    if (frame.cmd.length === 0 && !frame.ctx?.length) return;
     admission = admitFrame(h, conn, frame);
   } catch (error) {
     const reason = violationReason(error);
@@ -1445,6 +1554,7 @@ export const register = (
     lease: null,
     auth,
     lanes: new Map(),
+    contexts: new Map(),
     documents: new Map(),
     included: new Set(),
     view: new Map(),
@@ -1456,9 +1566,13 @@ export const register = (
   conn.attach = attachOf(h, conn);
   h.conns.add(conn);
   try {
+    validateContexts(h, conn, frame);
+    installContexts(h, conn, frame);
     h.current?.attaching?.(conn.attach);
   } catch (error) {
-    closeConn(h, conn, 1011, "attach failed");
+    const reason = violationReason(error);
+    if (reason !== null) violate(h, conn, reason);
+    else closeConn(h, conn, 1011, "attach failed");
     throw error;
   }
   gcClients(h);

package/src/host.ts

@@ -53,8 +53,11 @@ export namespace StatewireHost {
    * optimistic overlay — before the handler settles (idempotent, a no-op after
    * settle). The command settles when the handler's returned promise does.
    */
+  export type CommandsOptions = { context?: () => Statewire.Context };
+
   export type Ctx = {
     readonly caller: Caller;
+    readonly context: Statewire.Context;
     readonly attach: Attach;
     readonly signal: AbortSignal;
     readonly applied: () => void;
@@ -76,6 +79,8 @@ export namespace StatewireHost {
 
   /** The admitting attach's view: its ephemeral documents plus the shared documents included for it. */
   export type Attach = {
+    readonly caller: Caller;
+    context: (protocol: string) => Statewire.Context;
     document: (protocol: string, key?: readonly string[]) => unknown;
     /** `protocol` must be ephemeral; the encoded value is bounded by `MAX_EPHEMERAL_DOCUMENT_BYTES`. */
     mount: (

package/src/statewire.ts

@@ -40,7 +40,10 @@ const useSessionTransport = ({
   session: StatewireClient.SessionStorage | undefined;
   documents: StatewireDocuments.Storage | undefined;
   protocol: StatewireProtocol.Options;
-  link: { isNew?: boolean | undefined };
+  link: {
+    isNew?: boolean | undefined;
+    context?: Readonly<Record<string, Statewire.Context>> | undefined;
+  };
 }): Statewire<unknown> =>
   useContextProvider(SessionStorageContext, session, () =>
     // oxlint-disable-next-line react-hooks/rules-of-hooks
@@ -92,8 +95,11 @@ export const useStatewire = <
     }),
   };
   const link = useMemo(
-    () => (options.isNew === undefined ? {} : { isNew: options.isNew }),
-    [options.isNew],
+    () => ({
+      ...(options.isNew === undefined ? {} : { isNew: options.isNew }),
+      ...(options.context === undefined ? {} : { context: options.context }),
+    }),
+    [options.isNew, options.context],
   );
   const value = useResource(
     SessionTransport({
@@ -104,6 +110,14 @@ export const useStatewire = <
       link,
     }),
   );
+  const localContext =
+    value.connection === undefined ? value.setContext : undefined;
+  useEffect(() => {
+    const current = latest.current;
+    if (localContext === undefined || current.context === undefined) return;
+    for (const [protocol, context] of Object.entries(current.context))
+      localContext(protocol, context);
+  }, [options.context, localContext]);
   const core = useStatewireCore(() => latest.current, value);
   useEffect(() => core.rematerialize(), [core, options.materializeKey]);
   const [subscribe] = useState(
@@ -127,6 +141,7 @@ export const useStatewire = <
     documents: source,
     selection,
     invoke: transportInvoke,
+    setContext: transportSetContext,
     failures: transportFailures,
   } = value;
 
@@ -153,6 +168,11 @@ export const useStatewire = <
       documents: source,
       selection,
       invoke,
+      setContext: (protocol: string, value: Statewire.Context) => {
+        if (!transportSetContext)
+          throw new Error("statewire: transport does not support context");
+        transportSetContext(protocol, value);
+      },
       getState: core.getState as () => TState,
       connection,
       commands: core.commands as Statewire.CommandsProxy<TCommands>,
@@ -173,6 +193,7 @@ export const useStatewire = <
     selection,
     invoke,
     transportFailures,
+    transportSetContext,
   ]);
 };
 
@@ -221,6 +242,9 @@ export class StatewireClient<
   ): Promise<unknown> {
     return this.root.getValue().invoke(protocol, method, params);
   }
+  setContext(protocol: string, value: Statewire.Context): void {
+    this.root.getValue().setContext(protocol, value);
+  }
   get isBusy(): boolean {
     return this.root.getValue().isBusy;
   }
@@ -254,6 +278,7 @@ export namespace StatewireClient {
     TCommands extends Statewire.Commands = Statewire.Commands,
   > = {
     protocol?: string;
+    context?: Readonly<Record<string, Statewire.Context>>;
     keyPrefixes?: Readonly<Record<string, readonly string[]>>;
     wireVersion?: StatewireProtocol.Range;
     applicationProtocols?: readonly StatewireProtocol.Offer[] | "*";
@@ -298,6 +323,7 @@ export namespace StatewireClient {
     state: TState;
     documents: StatewireDocuments.Source | undefined;
     selection: StatewireProtocol.Selection | undefined;
+    setContext: (protocol: string, value: Statewire.Context) => void;
     invoke: (
       protocol: string,
       method: string,

package/src/transports/remote.ts

@@ -9,6 +9,7 @@ import {
   retryFailed,
   setTransport,
   useStatewireSession,
+  setContext,
 } from "../client/session";
 import type { StatewireSessionOptions } from "../client/session";
 import type { StatewireClient } from "../statewire";
@@ -35,6 +36,8 @@ export const useStatewireRemote = <
   const lanes = useMemo(
     () => ({
       documents: documentSource(s),
+      setContext: (protocol: string, value: Statewire.Context) =>
+        setContext(s, protocol, value),
       invoke: (protocol: string, method: string, params: readonly unknown[]) =>
         invokeProtocol(s, protocol, method, params),
       failures: {

package/src/transports/sse.ts

@@ -1,3 +1,4 @@
+import type { StatewireDocument } from "../document";
 import { flushTapSync, resource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
 import { createSseParser } from "./sse-parser";
@@ -25,6 +26,7 @@ import { negotiationHeaders, parseNegotiation } from "../wire/protocol";
 
 /** A client frame's lanes: stamped statements, strictly consecutive per lane. */
 export type StatewireFrame = {
+  ctx?: ({ protocol: string } & StatewireDocument.Encoded)[];
   cmd?: {
     protocol: string;
     method: string;
@@ -180,9 +182,14 @@ const attemptStream = async (
     throw new Error("statewire: protocol error: stream response has no body");
   c.lease = res.headers.get(LEASE_HEADER);
   const reader = res.body.getReader();
+  const cancel = () => {
+    void reader.cancel().catch(() => {});
+  };
+  abort.signal.addEventListener("abort", cancel, { once: true });
   try {
     return await consume(c, reader, heartbeat, () => abort.signal.aborted);
   } finally {
+    abort.signal.removeEventListener("abort", cancel);
     reader.cancel().catch(() => {});
   }
 };

package/src/transports/testing.ts

@@ -5,7 +5,7 @@ import type { StatewireFrame } from "./sse";
 import type { Statewire } from "../types";
 import { openSSEStream, sseFrame } from "./fake-sse";
 import type { FakeStreamHandle } from "./fake-sse";
-import { WIRE_VERSION } from "../wire/protocol";
+import { WIRE_VERSION, parseNegotiation } from "../wire/protocol";
 
 export * from "./fixtures";
 
@@ -19,6 +19,7 @@ export type MockTransport<TState> = {
   transport: ResourceElement<Statewire<TState | undefined, any>>;
   /** Captured statements in arrival order. */
   commands: { protocol: string; method: string; params: unknown[] }[];
+  contexts: NonNullable<StatewireFrame["ctx"]>;
   /** Replace the replicated state and broadcast it as a root snapshot op. */
   setState: (state: TState) => Promise<void>;
   /** Deliver a bare ack cmd packet on the stream. */
@@ -54,6 +55,7 @@ export const createMockTransport = <TState>(
   const clients = new Map<string, Record<string, number>>();
   const streams = new Set<FakeStreamHandle>();
   const commands: MockTransport<unknown>["commands"] = [];
+  const contexts: MockTransport<unknown>["contexts"] = [];
 
   const sendEnvelope = (envelope: StatewireEnvelope) => {
     for (const stream of streams) stream.send(sseFrame(envelope));
@@ -62,6 +64,7 @@ export const createMockTransport = <TState>(
 
   const admit = (id: string, frame: StatewireFrame) => {
     const rec = clients.get(id)!;
+    contexts.push(...(frame.ctx ?? []));
     for (const statement of frame.cmd ?? []) {
       if (statement.seq <= (rec[statement.protocol] ?? 0)) continue;
       rec[statement.protocol] = statement.seq;
@@ -86,6 +89,13 @@ export const createMockTransport = <TState>(
       if (!clients.has(id)) clients.set(id, {});
       const rec = clients.get(id)!;
       const ephemeral = ephemeralLanes();
+      const offers = parseNegotiation(headers).applicationProtocols;
+      const applicationVersion =
+        offers === "*"
+          ? WIRE_VERSION
+          : offers.find((offer) => offer.name === protocol)?.version;
+      if (applicationVersion === undefined)
+        throw new Error("mock protocol was not offered");
       for (const lane of ephemeral) delete rec[lane];
       const frame = JSON.parse(String(init?.body ?? "{}")) as StatewireFrame;
       admit(id, frame);
@@ -101,12 +111,12 @@ export const createMockTransport = <TState>(
                 protocols: [
                   {
                     name: protocol,
-                    version: WIRE_VERSION,
+                    version: applicationVersion,
                     seq: rec[protocol] ?? 0,
                   },
                   ...ephemeral.map((name) => ({
                     name,
-                    version: WIRE_VERSION,
+                    version: applicationVersion,
                     record: "ephemeral" as const,
                     seq: 0,
                   })),
@@ -132,6 +142,7 @@ export const createMockTransport = <TState>(
       fetch: fakeFetch,
     }),
     commands,
+    contexts,
     setState: (next) => {
       state = next;
       return sendEnvelope({ ops: [{ op: "replace", path: [], value: next }] });

package/src/types.ts

@@ -5,6 +5,7 @@ import type { StatewireClient } from "./statewire";
 import type { StatewirePath } from "./wire/ops";
 
 export namespace Statewire {
+  export type Context = Readonly<Record<string, unknown>>;
   export type Commands = Record<string, (...args: never[]) => unknown>;
 
   export type Command<TCommands extends Commands = Commands> = {
@@ -56,6 +57,17 @@ export interface Statewire<
   state: TState;
   documents?: StatewireDocuments.Source;
   selection?: StatewireProtocol.Selection | undefined;
+  setContext?: (protocol: string, value: Statewire.Context) => void;
+  validateContext?: (
+    protocol: string,
+    value: Statewire.Context,
+    attach: StatewireHost.Attach,
+  ) => void;
+  contextChanged?: (
+    protocol: string,
+    value: Statewire.Context,
+    attach: StatewireHost.Attach,
+  ) => void;
   invoke?: (
     protocol: string,
     method: string,

package/src/wire/context.ts

@@ -0,0 +1,40 @@
+import { decodeDocument, encodeDocument } from "../document";
+import type { Statewire } from "../types";
+import { MAX_CONTEXT_BYTES } from "./limits";
+import { protocolToken } from "./protocol";
+
+const freeze = (value: unknown): void => {
+  if (typeof value !== "object" || value === null) return;
+  for (const child of Object.values(value)) freeze(child);
+  Object.freeze(value);
+};
+
+export const contextValue = (encoded: unknown): Statewire.Context => {
+  const value = decodeDocument(encoded);
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    Array.isArray(value) ||
+    value instanceof Date
+  )
+    throw new TypeError("statewire: context root must be an object");
+  freeze(value);
+  return value as Statewire.Context;
+};
+
+export const encodeContext = (protocol: string, value: Statewire.Context) => {
+  if (!protocolToken.test(protocol))
+    throw new TypeError("statewire: invalid context protocol");
+  const encoded = encodeDocument(value);
+  contextValue(encoded);
+  const entry = { protocol, ...encoded };
+  if (
+    new TextEncoder().encode(JSON.stringify(entry)).byteLength >
+    MAX_CONTEXT_BYTES
+  )
+    throw new TypeError("statewire: context entry too large");
+  return entry;
+};
+
+export const captureContext = (value: Statewire.Context): Statewire.Context =>
+  contextValue(encodeDocument(value));

package/src/wire/limits.ts

@@ -4,3 +4,5 @@ export const MAX_FRAME_BODY_BYTES = 8 * 1024 * 1024;
 export const MAX_EPHEMERAL_DOCUMENT_BYTES = 64 * 1024;
 export const MAX_INFLIGHT_COMMANDS_PER_HOST = 1024;
 export const COMMAND_CAPACITY_RETRY_MS = 1_000;
+
+export const MAX_CONTEXT_BYTES = 64 * 1024;

package/src/wire/protocol.ts

@@ -18,7 +18,7 @@ export namespace StatewireProtocol {
   };
 }
 
-export const WIRE_VERSION = "2026-09-13";
+export const WIRE_VERSION = "2026-09-30";
 export const DEFAULT_PROTOCOL = "default";
 export const PROTOCOL_HEADER = "Statewire-Protocol";
 export const VERSION_HEADER = "Statewire-Version";