@privchat/react

Headless React integration layer for @privchat/sdk. Provides a Provider, hooks, and ViewModel selectors. Does not ship visual components, a router, or browser multi-tab logic — those belong to the consuming app (e.g. privchat-web).

Status: R0 skeleton. Currently private: true (workspace-only). Will graduate to a published @privchat/react once privchat-web exercises the hook surface against real UI.

Scope

See docs/PRIVCHAT_REACT_ARCHITECTURE.md for the full boundary contract. Short version:

| In scope | Out of scope (lives in privchat-web / host app) | | --------------------------------------------------------- | ------------------------------------------------- | | <PrivchatProvider> + useContext plumbing | Visual components (bubbles, lists, layout) | | useSyncExternalStore-based hooks over SDK events | shadcn/ui, Tailwind, theming | | ViewModel selectors over SDK records | Router, page composition | | Headless timeline / composer state controllers (R3+) | BroadcastChannel, multi-tab leader election | | PrivchatClientAdapter seam for direct / worker setups | SharedWorker / DedicatedWorker instantiation | | Pure logic; no browser globals | Media viewer, file uploader, virtualization |

Install (local development)

This package links to the SDK via file:. From the workspace root:

cd privchat-sdk-typescript && npm install && npm run build
cd ../privchat-react && npm install

react is declared as a peerDependency so that the consuming app owns the single React copy. Two React copies → Invalid Hook Call at runtime.

R0 surface

import { PrivchatClient } from '@privchat/sdk';
import {
  PrivchatProvider,
  DirectClientAdapter,
  useConnectionState,
  usePrivchatClient,
} from '@privchat/react';

const client = new PrivchatClient({ transport });
const adapter = new DirectClientAdapter(client);

function App() {
  return (
    <PrivchatProvider adapter={adapter}>
      <ConnectionBadge />
    </PrivchatProvider>
  );
}

function ConnectionBadge() {
  const state = useConnectionState();
  return <span data-state={state}>{state}</span>;
}

The Provider does not call connect(), authenticate(), or dispose() — the host owns lifecycle because policy varies sharply between web (visibility

• multi-tab), Tauri (single process), and Cocos (scene transitions).

Roadmap

| Phase | Surface | Driven by | | ----- | -------------------------------------------------------------- | ------------------------------------ | | R0 | Provider, adapter, usePrivchatClient, useConnectionState | this skeleton | | R1 | Channel list, open conversation | first privchat-web real page | | R2 | Messages, send, outbox + first ViewModels | timeline page in privchat-web | | R3 | Headless timeline / composer controllers | scroll & input in privchat-web | | R4+ | Read cursors, typing, presence | feature-by-feature |

Each phase ships only when a real UI need surfaces. No speculative API.

License

Apache-2.0