statewire

One JSON object replicated from a server to any number of clients, with typed commands back: the server streams snapshot-first ops, the client keeps optimistic updates rebased on top and settles every command it sent. Part of harness-sdk, with harness-sdk and pinned.

Install

pnpm add statewire react

Use

import { StatewireHttp, useStatewire } from "statewire";

type CounterState = { count: number };
type CounterCommands = { increment(): void; reset(): void };

export const App = () => {
  const { state, connection, commands } = useStatewire<
    CounterState | undefined,
    CounterCommands
  >({ transport: StatewireHttp({ url: "/threads/main" }) });
  return (
    <main>
      <p>{connection.status}</p>
      <h1>{state?.count ?? 0}</h1>
      <button onClick={() => void commands.increment()}>+1</button>
    </main>
  );
};

Protocols and documents

Connections negotiate date ranges through Statewire-Version and Statewire-Protocol. Protocols are additive and required by default. The server selects versions in syn; WebSockets use statewire.v1.

Each protocol owns its commands, lease context, and state documents. The main document is independent of its optional read key. Command sequences and replay remain shared across protocols. Python hosts support lazy, chained compatibility adapters.

See the protocol registration and migration guide.

Docs

• Get started: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/statewire/docs/get-started/statewire/page.mdx
• Guide: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/statewire/docs/guides/statewire/consume/page.mdx
• Reference: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/statewire/docs/reference/statewire/page.mdx
• Spec: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/statewire/docs/spec/statewire-protocol/page.mdx

Lease context

Native context belongs to a protocol and a connection lease, independently of command history:

const client = new StatewireClient({
  transport,
  context: { "acme-chat": { locale: "en" } },
});
client.setContext("acme-chat", { locale: "de" });

The client restores its latest object on every attachment, including a fresh hello on a preserved socket. Hosts validate through validateContext and react through contextChanged. Command handlers read this.context, captured when the command was admitted; later replacements cannot change queued commands. Context uses document encoding (including dates), full replacements, and a 64 KiB limit per entry. Updates consume no command sequence numbers.