SDK

@omni-arena/react — the headless React SDK for OmniArena: blind side-by-side comparisons over one SSE stream, blind voting with identity reveal, multi-turn continuation, and the Bradley-Terry leaderboard. No UI, no styling — just state and actions.

Two layers

Which layer you want depends on who owns the conversation state.

Install

From another package in this monorepo, depend on it the same way web/ does:

{
  "dependencies": {
    "@omni-arena/react": "*"
  }
}

react (>=18) is a peer dependency. Once published to npm: npm install @omni-arena/react react.

Exports

The primitives, three arena hooks, six analytics hooks (one per /api/arena/analytics/* endpoint), and their public types:

Primitives (host-app integration)

Stateless and free of React and DOM assumptions, so each one can be called from a Next.js route handler, an edge function, or a non-React client.

The normalised round

{
  matchupId: string;           // always present; the control-plane stream id
  matchupToken: string | null; // null on a round with nothing to vote on
  conversationId?: string;     // omitted when the server persisted nothing
  turnIndex?: number;          // omitted with conversationId
  slots: ArenaSlot[];          // defaults to ["A", "B"]
  mode: ArenaMode;             // defaults to "matchup"
  votable: boolean;            // authoritative; defaults to true for older servers
}

The reveal

{
  models: Record<ArenaSlot, RevealedModel>; // RevealedModel = { id, displayName }
  vote: ArenaVote | null;                    // the vote it was granted for
  continuable: boolean;                      // may the next turn continue this conversation?
  conversationId?: string;                   // echoed by the vote response
}

A host app that owns its own stream typically needs three of these: getSessionId() when it starts a round, parseArenaMatchup() on the round's metadata, and submitArenaVote()/useArenaVote() when the user votes.

// A host's own proxy route: forward the vote, keep the reveal server-side.
import { submitArenaVote } from "@omni-arena/react";

export async function POST(request: Request) {
  const { matchupId, matchupToken, vote } = await request.json();
  const reveal = await submitArenaVote({
    matchupId,
    matchupToken,
    vote,
    baseUrl: process.env.OMNIARENA_URL,
  });
  return Response.json(reveal);
}

useArenaChat(options?)

Starts and continues matchups, streams both responses into per-slot state, and records votes.

useArenaLeaderboard(options?)

Fetches standings once on mount; call refresh() after a vote to update them.

Analytics hooks

One hook per /api/arena/analytics/* endpoint, powering the demo's insights dashboard. Each fetches once on mount and returns the same shape, exported as AnalyticsResource<T>:

{ data: T | null; refresh(): Promise<void>; error: string | null }

Endpoints are relative to /api/arena; the hooks prepend baseUrl and that prefix themselves.

The baseUrl option

Every hook — and submitArenaVote() — takes baseUrl?: string: the origin/path prefix the arena API is served from. Default "" hits the same-origin /api/arena/* routes (e.g. behind a dev proxy, as the demo does). Pass an absolute origin to target a remote server.

useArenaChat({ baseUrl: "https://arena.example.com" });
useArenaLeaderboard({ baseUrl: "https://arena.example.com" });

Integration example

A full blind-comparison-and-vote flow in under ten lines — bring your own markup:

import { useArenaChat } from "@omni-arena/react";

export function Arena() {
  const { sendPrompt, slots, canVote, vote } = useArenaChat();
  return (
    <div>
      <button onClick={() => sendPrompt("Explain quantum tunneling")}>Ask</button>
      <pre>{slots.A.content}</pre><pre>{slots.B.content}</pre>
      <button disabled={!canVote} onClick={() => vote("left")}>A wins</button>
    </div>
  );
}