statewire 0.15.0 → 0.17.0

package/src/statewire.ts

@@ -1,3 +1,5 @@
+import type { StatewireDocuments } from "./wire/documents";
+import type { StatewireProtocol } from "./wire/protocol";
 import type { StatewireHost } from "./host";
 import { useMemo, useRef, useState, useSyncExternalStore } from "react";
 import {
@@ -13,18 +15,32 @@ import type { ResourceElement } from "@assistant-ui/tap";
 import { CONNECTED_CONNECTION, useStatewireCore } from "./client/core";
 import type { Statewire } from "./types";
 import type { TERMINAL } from "./client/connection";
-import { SessionStorageContext } from "./client/sessionStore";
+import {
+  DocumentStorageContext,
+  ProtocolContext,
+  SessionStorageContext,
+} from "./client/sessionStore";
 
 const useSessionTransport = ({
   transport,
   session,
+  documents,
+  protocol,
 }: {
   transport: ResourceElement<Statewire<any, any>>;
   session: StatewireClient.SessionStorage | undefined;
+  documents: StatewireDocuments.Storage | undefined;
+  protocol: StatewireProtocol.Options;
 }): Statewire<unknown> =>
   useContextProvider(SessionStorageContext, session, () =>
     // oxlint-disable-next-line react-hooks/rules-of-hooks
-    useResource(transport),
+    useContextProvider(DocumentStorageContext, documents, () =>
+      // oxlint-disable-next-line react-hooks/rules-of-hooks
+      useContextProvider(ProtocolContext, protocol, () =>
+        // oxlint-disable-next-line react-hooks/rules-of-hooks
+        useResource(transport),
+      ),
+    ),
   );
 
 // The transport owns the session; it reads the storage off the context this
@@ -45,8 +61,30 @@ export const useStatewire = <
       ? [withKey("session", options.storage.session)]
       : [],
   )[0];
+  const documents = useResources(
+    options.storage?.documents === undefined
+      ? []
+      : [withKey("documents", options.storage.documents)],
+  )[0];
+  const protocol: StatewireProtocol.Options = {
+    ...(options.protocol !== undefined && { protocol: options.protocol }),
+    ...(options.wireVersion !== undefined && {
+      wireVersion: options.wireVersion,
+    }),
+    ...(options.applicationProtocols !== undefined && {
+      applicationProtocols: options.applicationProtocols,
+    }),
+    ...(options.keyPrefixes !== undefined && {
+      keyPrefixes: options.keyPrefixes,
+    }),
+  };
   const value = useResource(
-    SessionTransport({ transport: options.transport, session }),
+    SessionTransport({
+      transport: options.transport,
+      session,
+      documents,
+      protocol,
+    }),
   );
   const core = useStatewireCore(() => latest.current, value);
   const [subscribe] = useState(
@@ -76,6 +114,26 @@ export const useStatewire = <
     };
     return {
       state,
+      documents: value.documents,
+      selection: value.selection,
+      invoke: (
+        protocol: string,
+        method: string,
+        params: readonly unknown[],
+      ) => {
+        if (!value.invoke)
+          throw new Error(
+            "statewire: transport does not support protocol commands",
+          );
+        return value.invoke(protocol, method, params);
+      },
+      updateContext: (ops: readonly unknown[]) => {
+        if (!value.updateContext)
+          throw new Error(
+            "statewire: transport does not support context documents",
+          );
+        value.updateContext(ops);
+      },
       getState: core.getState as () => TState,
       connection,
       commands: core.commands as Statewire.CommandsProxy<TCommands>,
@@ -129,6 +187,23 @@ export class StatewireClient<
     return this.root.getValue().commands;
   }
 
+  get documents(): StatewireDocuments.Source | undefined {
+    return this.root.getValue().documents;
+  }
+  get selection(): StatewireProtocol.Selection | undefined {
+    return this.root.getValue().selection;
+  }
+  invoke(
+    protocol: string,
+    method: string,
+    params: readonly unknown[],
+  ): Promise<unknown> {
+    return this.root.getValue().invoke(protocol, method, params);
+  }
+  updateContext(ops: readonly unknown[]): void {
+    this.root.getValue().updateContext(ops);
+  }
+
   get isBusy(): boolean {
     return this.root.getValue().isBusy;
   }
@@ -165,10 +240,17 @@ export namespace StatewireClient {
     TState,
     TCommands extends Statewire.Commands = Statewire.Commands,
   > = {
+    protocol?: string;
+    keyPrefixes?: Readonly<Record<string, readonly string[]>>;
+    wireVersion?: StatewireProtocol.Range;
+    applicationProtocols?: readonly StatewireProtocol.Offer[] | "*";
     transport: ResourceElement<Statewire<TState, TCommands>>;
     /** Durable session: the mounted storage holds this client's lane identity and its un-durable commands, which resend on the next attach. */
     storage?:
-      | { session?: ResourceElement<SessionStorage> | undefined }
+      | {
+          session?: ResourceElement<SessionStorage> | undefined;
+          documents?: ResourceElement<StatewireDocuments.Storage> | undefined;
+        }
       | undefined;
     /** Served as the canonical state until the attach snapshot; own commands fold over it. */
     initialState?: TState;
@@ -197,6 +279,14 @@ export namespace StatewireClient {
   > = {
     /** The statewire's state type — remote statewires include `undefined` until the first attach snapshot applies. */
     state: TState;
+    documents: StatewireDocuments.Source | undefined;
+    selection: StatewireProtocol.Selection | undefined;
+    invoke: (
+      protocol: string,
+      method: string,
+      params: readonly unknown[],
+    ) => Promise<unknown>;
+    updateContext: (ops: readonly unknown[]) => void;
     /** Identity-stable across renders; reads the current canonical state without subscribing the caller. */
     getState: () => TState;
     connection: Connection;
@@ -318,6 +408,8 @@ export namespace StatewireClient {
 
   /** A non-accepted send retained for the user: the wire statement, its failure, and its original clocks. */
   export type FailedCommand = {
+    readonly protocol: string;
+    readonly produced?: SessionCommand["produced"];
     readonly command: string;
     readonly params: readonly unknown[];
     readonly meta?: unknown;
@@ -329,6 +421,11 @@ export namespace StatewireClient {
   /** A command as persisted while un-durable: its lane seq plus the wire statement. */
   export type SessionCommand = {
     seq: number;
+    protocol: string;
+    produced?: {
+      wire: StatewireProtocol.Range;
+      protocols: readonly StatewireProtocol.Offer[] | "*";
+    };
     method: string;
     params: unknown[];
     meta?: unknown;
@@ -339,6 +436,7 @@ export namespace StatewireClient {
     clientId: string;
     nextSeq: number;
     ctxNextSeq: number;
+    context?: { ops: unknown[]; pending: { seq: number; ops: unknown[] }[] };
     commands: readonly SessionCommand[];
     /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */
     verdicts?: readonly SessionVerdict[];
@@ -360,6 +458,11 @@ export namespace StatewireClient {
   export type SessionStorage = {
     load: () => SessionRecord | null;
     save: (record: SessionRecord) => void;
+    /** Upgrade incompatible stored commands; null discards the old record and starts a new client identity. */
+    migrate?: (
+      record: SessionRecord,
+      current: NonNullable<SessionCommand["produced"]>,
+    ) => SessionRecord | null;
     /** Serializes record mutations across sharers; presence marks the storage shared. */
     lock?: <T>(fn: () => T | Promise<T>) => Promise<T>;
     /** Notifies of record saves by other sharers; returns unsubscribe. Required alongside `lock`. */
@@ -373,7 +476,7 @@ export namespace StatewireClient {
     | HeadersInit
     | ((ctx: { staleAuth: boolean }) => HeadersInit | Promise<HeadersInit>);
 
-  export type SSEOptions = {
+  export type HttpOptions = StatewireProtocol.Options & {
     sessionStore?: SessionStorage | undefined;
     url: string;
     /** The session does not exist on the server yet: the first attach waits for the first command send (or an explicit `reconnect()`). */
@@ -387,7 +490,7 @@ export namespace StatewireClient {
     onDone?: () => void;
   };
 
-  export type WSOptions = {
+  export type WebsocketOptions = StatewireProtocol.Options & {
     sessionStore?: SessionStorage | undefined;
     url: string;
     /** The session does not exist on the server yet: the first attach waits for the first command send (or an explicit `reconnect()`). */

package/src/transports/fixtures.ts

@@ -24,7 +24,7 @@ export const commandFrame = (
   method: string,
   seq: number,
   params: unknown[] = [],
-) => JSON.stringify({ cmd: [{ method, params, seq }] });
+) => JSON.stringify({ cmd: [{ protocol: "default", method, params, seq }] });
 
 export type SocketRecorder = {
   sent: string[];

package/src/transports/remote.ts

@@ -1,6 +1,10 @@
-import { useEffect } from "react";
+import { useContext, useEffect } from "react";
+import { ProtocolContext } from "../client/sessionStore";
 import type { Statewire } from "../types";
 import {
+  documentSource,
+  invokeProtocol,
+  updateContext,
   discardFailed,
   failedCommands,
   retryFailed,
@@ -22,16 +26,21 @@ export const useStatewireRemote = <
   options: TOptions,
   useLink: (options: TOptions, ctx: StatewireRemoteProps) => RemoteLink,
 ): Statewire<any, any> => {
-  const s = useStatewireSession({
-    sessionStore: options.sessionStore,
-    onSessionLost: options.onSessionLost,
-    onDone: options.onDone,
-  });
-  const conn = useLink(options, s.ctx);
+  const inherited = useContext(ProtocolContext);
+  const configured = { ...inherited, ...options };
+  const s = useStatewireSession(configured);
+  const conn = useLink(configured, s.ctx);
   useEffect(() => setTransport(s, conn), [s, conn]);
 
   return {
     state: s.canonical,
+    documents: documentSource(s),
+    get selection() {
+      return s.selection;
+    },
+    invoke: (protocol, method, params) =>
+      invokeProtocol(s, protocol, method, params),
+    updateContext: (ops) => updateContext(s, ops),
     commands: s.commands,
     connection: conn.connection,
     source: s.source,

package/src/transports/sse.ts

@@ -7,7 +7,6 @@ import {
   classify,
   handleEnvelope,
   resolveHeaders,
-  unsupportedVersion,
   useLink,
   validateRefusalSyn,
 } from "../client/connection";
@@ -22,7 +21,7 @@ import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 import type { StatewireHost } from "../host";
 import { useStatewireRemote } from "./remote";
-import { PROTOCOL_VERSION, VERSION_HEADER } from "../wire/version";
+import { negotiationHeaders, parseNegotiation } from "../wire/protocol";
 
 /** A client frame's lanes: stamped statements, strictly consecutive per lane. */
 export type StatewireFrame = {
@@ -61,7 +60,7 @@ export type RemoteLink = {
 
 const LEASE_HEADER = "Statewire-Lease";
 
-const baseUrl = (options: StatewireClient.SSEOptions) =>
+const baseUrl = (options: StatewireClient.HttpOptions) =>
   options.url.replace(/\/$/, "");
 
 const withExtra = (headers: Headers, extra: Record<string, string>) => {
@@ -71,7 +70,7 @@ const withExtra = (headers: Headers, extra: Record<string, string>) => {
 };
 
 const timedFetch = async (
-  options: StatewireClient.SSEOptions,
+  options: StatewireClient.HttpOptions,
   input: string,
   init: RequestInit & { signal: AbortSignal },
   timeout: AbortSignal,
@@ -116,11 +115,15 @@ const consume = async (
 
 const attemptStream = async (
   c: Conn,
-  options: StatewireClient.SSEOptions,
+  options: StatewireClient.HttpOptions,
   abort: AbortController,
 ): Promise<AttemptOutcome> => {
   c.lease = null;
   const headers = await resolveHeaders(options.headers, c.authStale);
+  for (const [name, value] of Object.entries(negotiationHeaders(options))) {
+    if (!headers.has(name)) headers.set(name, value);
+  }
+  c.negotiation = parseNegotiation(headers);
   c.authStale = false;
   const lanes = flushTapSync(() => c.ctx.takeAttachLanes());
   const body = lanes === null ? undefined : JSON.stringify(lanes);
@@ -150,14 +153,21 @@ const attemptStream = async (
   } finally {
     clearTimeout(headerTimer);
   }
-  if (!res.ok) return flushTapSync(() => settleFin(c, httpFin(res)));
+  if (!res.ok) {
+    const body = await res
+      .clone()
+      .json()
+      .catch(() => null);
+    return (
+      flushTapSync(() =>
+        body?.fin === undefined
+          ? settleFin(c, httpFin(res))
+          : handleEnvelope(c, body),
+      ) ?? "stop"
+    );
+  }
   if (!res.body)
     throw new Error("statewire: protocol error: stream response has no body");
-  const version = res.headers.get(VERSION_HEADER)?.trim();
-  if (version !== undefined && version !== PROTOCOL_VERSION) {
-    res.body.cancel().catch(() => {});
-    return unsupportedVersion(c, version);
-  }
   c.lease = res.headers.get(LEASE_HEADER);
   const reader = res.body.getReader();
   try {
@@ -169,7 +179,7 @@ const attemptStream = async (
 
 const postFrame = async (
   c: Conn,
-  options: StatewireClient.SSEOptions,
+  options: StatewireClient.HttpOptions,
   lease: string,
   frame: StatewireFrame,
   timeout: AbortSignal,
@@ -230,7 +240,7 @@ const refusalSyn = async (res: Response): Promise<StatewireSyn> => {
 
 const sendFrame = async (
   c: Conn,
-  options: StatewireClient.SSEOptions,
+  options: StatewireClient.HttpOptions,
   frame: StatewireFrame,
 ): Promise<StatewireSubmitResult> => {
   const lease = c.lease;
@@ -256,7 +266,7 @@ const sendFrame = async (
 };
 
 const useSseLink = (
-  options: StatewireClient.SSEOptions,
+  options: StatewireClient.HttpOptions,
   ctx: StatewireRemoteProps,
 ): RemoteLink =>
   useLink({
@@ -282,13 +292,13 @@ const useSseLink = (
     },
   });
 
-const useStatewireSSE = (
-  options: StatewireClient.SSEOptions,
+const useStatewireHttp = (
+  options: StatewireClient.HttpOptions,
 ): Statewire<any, any> => useStatewireRemote(options, useSseLink);
 
-export const StatewireSSE = resource(useStatewireSSE) as <
+export const StatewireHttp = resource(useStatewireHttp) as <
   TState = any,
   TCommands extends Statewire.Commands = Statewire.Commands,
 >(
-  options: StatewireClient.SSEOptions,
+  options: StatewireClient.HttpOptions,
 ) => ResourceElement<Statewire<TState | undefined, TCommands>>;

package/src/transports/testing.ts

@@ -1,6 +1,6 @@
 import type { ResourceElement } from "@assistant-ui/tap";
 import type { StatewireEnvelope } from "../client/connection";
-import { StatewireSSE } from "./sse";
+import { StatewireHttp } from "./sse";
 import type { StatewireFrame } from "./sse";
 import type { Statewire } from "../types";
 import { openSSEStream, sseFrame } from "./fake-sse";
@@ -41,6 +41,7 @@ let mockCount = 0;
 
 export const createMockTransport = <TState>(
   initialState: TState,
+  protocol = "default",
 ): MockTransport<TState> => {
   let state: unknown = initialState;
   let clientId = "";
@@ -57,11 +58,13 @@ export const createMockTransport = <TState>(
   const admit = (id: string, frame: StatewireFrame) => {
     const rec = clients.get(id)!;
     for (const statement of frame.ctx ?? []) {
+      if (statement.seq <= rec.ctxSeq) continue;
       rec.ctxSeq = Math.max(rec.ctxSeq, statement.seq);
       const root = statement.ops[0] as { value?: unknown } | undefined;
       commands.push({ context: root?.value });
     }
     for (const statement of frame.cmd ?? []) {
+      if (statement.seq <= rec.seq) continue;
       rec.seq = Math.max(rec.seq, statement.seq);
       commands.push({ method: statement.method, params: statement.params });
     }
@@ -87,8 +90,13 @@ export const createMockTransport = <TState>(
         (handle) => {
           handle.send(
             sseFrame({
-              ops: [{ op: "replace", path: [], value: state }],
-              syn: { seq: rec.seq, ctxSeq: rec.ctxSeq },
+              ops: [{ op: "mount", protocol, main: true, value: state }],
+              syn: {
+                seq: rec.seq,
+                ctxSeq: rec.ctxSeq,
+                version: "2026-09-07",
+                protocols: [{ name: protocol, version: "2026-09-07" }],
+              },
             }),
           );
         },
@@ -104,7 +112,7 @@ export const createMockTransport = <TState>(
   }) as typeof fetch;
 
   return {
-    transport: StatewireSSE({
+    transport: StatewireHttp({
       url: `http://mock-${++mockCount}/api`,
       fetch: fakeFetch,
     }),

package/src/transports/ws.ts

@@ -34,7 +34,7 @@ const OPEN = 1;
 export { WS_SUBPROTOCOL };
 
 const socketUrl = async (
-  options: StatewireClient.WSOptions,
+  options: StatewireClient.WebsocketOptions,
   clientId: string,
 ) => {
   const { url, query } = options;
@@ -72,7 +72,7 @@ const runSocket = (
     ws.onerror = () => {};
     ws.onopen = () => {
       const negotiated = ws.protocol.trim();
-      if (negotiated !== "" && negotiated !== WS_SUBPROTOCOL) {
+      if (negotiated !== WS_SUBPROTOCOL) {
         outcome = unsupportedVersion(c, negotiated);
         ws.close();
         return;
@@ -124,7 +124,7 @@ const runSocket = (
 const attemptSocket = async (
   c: Conn,
   w: WsChannel,
-  options: StatewireClient.WSOptions,
+  options: StatewireClient.WebsocketOptions,
   abort: AbortController,
 ): Promise<AttemptOutcome> => {
   let ws: WebSocket | null = null;
@@ -166,7 +166,7 @@ const sendFrame = (
 };
 
 const useWsLink = (
-  options: StatewireClient.WSOptions,
+  options: StatewireClient.WebsocketOptions,
   ctx: StatewireRemoteProps,
 ): RemoteLink => {
   const [w] = useState((): WsChannel => ({ socket: null }));
@@ -178,13 +178,13 @@ const useWsLink = (
   });
 };
 
-const useStatewireWS = (
-  options: StatewireClient.WSOptions,
+const useStatewireWebsocket = (
+  options: StatewireClient.WebsocketOptions,
 ): Statewire<any, any> => useStatewireRemote(options, useWsLink);
 
-export const StatewireWS = resource(useStatewireWS) as <
+export const StatewireWebsocket = resource(useStatewireWebsocket) as <
   TState = any,
   TCommands extends Statewire.Commands = Statewire.Commands,
 >(
-  options: StatewireClient.WSOptions,
+  options: StatewireClient.WebsocketOptions,
 ) => ResourceElement<Statewire<TState | undefined, TCommands>>;

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { StatewireDocuments } from "./wire/documents";
+import type { StatewireProtocol } from "./wire/protocol";
 import type { StatewireClient } from "./statewire";
 import type { StatewirePath } from "./wire/ops";
 
@@ -16,6 +18,7 @@ export namespace Statewire {
 
   export type CommandUpdate<TCommands extends Commands = Commands> = {
     [K in keyof TCommands]: {
+      readonly protocol?: string;
       method: K;
       params: Parameters<TCommands[K]>;
       seq: number;
@@ -50,6 +53,14 @@ export interface Statewire<
   TCommands extends Statewire.Commands = Statewire.Commands,
 > {
   state: TState;
+  documents?: StatewireDocuments.Source;
+  selection?: StatewireProtocol.Selection | undefined;
+  invoke?: (
+    protocol: string,
+    method: string,
+    params: readonly unknown[],
+  ) => Promise<unknown>;
+  updateContext?: (ops: readonly unknown[]) => void;
   commands: Statewire.CommandsProxy<TCommands>;
   connection?: StatewireClient.Connection;
   source?: Statewire.StateSource;

package/src/util/randomId.ts

@@ -1,4 +1,4 @@
 export const randomId = (): string =>
-  typeof crypto !== "undefined" && "randomUUID" in crypto
-    ? crypto.randomUUID()
-    : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+  Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");