@openturn/react

bun add @openturn/react

const {
  OpenturnProvider,
  createLocalMatch,
  useMatch,          // discriminated MatchView — works in local and hosted
  useRoom,           // full HostedRoomState — lobby, bridge, invite URL (multiplayer only)
  useInspector,      // inspector timeline + state for the active match
  useReplayInspector, // replay-only variant (no live match required)
  runtime,           // mirrors options.runtime for downstream branching
} = createOpenturnBindings(game, {
  runtime: "local",        // or "multiplayer"
  match: { players: game.playerIDs },   // required for "local"; ignored for "multiplayer"
  hosted: { /* HostedMatchOptions */ }, // optional, applied in multiplayer mode
});

interface CreateOpenturnBindingsOptions<TGame> {
  runtime: "local" | "multiplayer";
  match?: MatchInput<GamePlayers<TGame>>;
  hosted?: HostedMatchOptions;
}

<OpenturnProvider>
  <Board />
</OpenturnProvider>

<OpenturnProvider match={fixtureStore}>{children}</OpenturnProvider>

type MatchView<TGame> =
  | { mode: "local"; snapshot; dispatch; status; state: OpenturnMatchState<TGame> }
  | { mode: "hosted"; snapshot; dispatch; status; state: HostedMatchState<TGame> };

function Page() {
  const room = useRoom();

  if (room.phase === "missing_backend") return <MissingBackend />;
  if (room.lobby !== null) return <Lobby lobby={room.lobby} />;
  if (room.game !== null) return <InGame match={room.game} />;
  return <Connecting />;
}

function DebugPane() {
  const inspector = bindings.useInspector();
  if (inspector === null) return null;
  // Feed `inspector` into a custom inspector layout, or use
  // `<InspectorPanel>` from `@openturn/inspector-ui` for a shell-owned view.
  return <CustomInspectorLayout inspector={inspector} />;
}

const inspector = bindings.useReplayInspector({ envelope: loadedEnvelope });

interface UseInspectorResult {
  state: InspectorState;
  dispatch: (action: InspectorAction) => void;
  timeline: InspectorTimeline;
  currentFrame: InspectorFrame;
  canReturnToLive: boolean;
  canReplay: boolean;
  maxRevision: number;
  minReplayRevision: number;
  effectiveRevision: number;
}

interface OpenturnMatchState<TGame> {
  dispatch: GameDispatchMap<TGame>;
  game: TGame;
  lastBatch: GameSuccessResult<TGame>["batch"] | null;
  replayData: GameReplayData<TGame>;
  snapshot: GameSnapshot<...>;
  status: SessionStatus;
  reset: () => void;
  getPlayerView: (playerID) => GamePlayerView<TGame>;
}

const match = useMatch();
if (match.mode !== "local") throw new Error("expected local match");
const { dispatch, snapshot, getPlayerView } = match.state;

interface HostedMatchState<TGame, TPublicState, TResult> {
  activePlayers: readonly string[];
  batchHistory: readonly BatchApplied[];
  canAct: (event) => boolean;
  canDispatch: HostedCanDispatchMap<TGame>;
  dispatch: HostedDispatchMap<TGame>;
  disconnect: () => void;
  error: string | null;
  initialSnapshot: HostedSnapshot | null;
  isActivePlayer: boolean;
  isFinished: boolean;
  lastAcknowledgedActionID: string | null;
  lastBatch: BatchApplied | null;
  playerID: string | null;
  reconnect: () => Promise<void>;
  requestResync: () => void;
  requestSync: () => void;
  result: TResult | null;
  roomID: string | null;
  self: { playerID; isActive } | null;
  snapshot: HostedSnapshot | null;
  status: HostedMatchStatus;
}

const outcome = await match.dispatch.placeMark({ row: 0, col: 0 });
if (!outcome.ok) {
  setError(outcome.error); // server rejection, disconnect, or send failure
}

type HostedLastAction<TGame> = {
  [E in keyof TGame["events"] & string]: {
    event: E;
    payload: TGame["events"][E];
    playerID: string;
    actionID: string;
    turn: number;
    revision: number;
  };
}[keyof TGame["events"] & string];

const last = match.lastAction;
if (last?.event === "placeMark") {
  const { row, col } = last.payload; // typed
}

const outcome = await match.dispatch.placeMark({ row, col });
if (!outcome.ok) {
  setMessage(formatDispatchError(outcome, {
    byReason: { occupied: "That square is already occupied." },
  }));
}

interface DispatchErrorLike {
  error: string;
  reason?: string;
  details?: ProtocolValue;
}

interface FormatDispatchErrorOptions {
  byError?: Readonly<Record<string, string>>;
  byReason?: Readonly<Record<string, string>>;   // wins over byError
  fallback?: string;
}

<HostedRoom
  room={room}
  missingBackend={<MissingBackend />}
  connecting={<Connecting />}
  closed={<Closed />}
  error={(msg) => <Error msg={msg} />}
  fallback={<Loading />}
  lobby={(lobby) => <Lobby lobby={lobby} />}
  game={(match) => <Game match={match} />}
/>

interface HostedRoomState<TGame> {
  phase: HostedRoomPhase;
  error: string | null;
  roomID: string | null;
  userID: string | null;
  userName: string | null;
  isHost: boolean;
  inviteURL: string | null;
  lobby: LobbyView | null;
  game: HostedMatchState<TGame> | null;
  bridge: GameBridge | null;
}

function DevShell({ children }) {
  const observed = useShellHostedMatch(game);
  return (
    <>
      <InspectorToolbar state={observed} />
      <HostedMatchShellObserver>{children}</HostedMatchShellObserver>
    </>
  );
}