> ## Documentation Index
> Fetch the complete documentation index at: https://openturn.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Packages overview

> Every openturn package, its runtime, and when to reach for it.

Openturn is split across eighteen packages. This page is the decision tree: "I want to do X, which one do I import."

## Authoring

| Package                                   | Runtime | Why                                                                                                                                                                                       |
| ----------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`@openturn/core`](/docs/reference/core)       | worker  | The engine. `defineGame`, `definePlayerIDs`, events, states, transitions, `createLocalSession`.                                                                                           |
| [`@openturn/gamekit`](/docs/reference/gamekit) | worker  | Move-first sugar over core: `defineGame`, moves, phases, outcomes. Use this unless you need the core escape hatch.                                                                        |
| [`@openturn/json`](/docs/reference/json)       | worker  | `JsonValue` types, `JsonValueSchema`, and validators. Re-exported by most packages; you will import it directly for explicit JSON validation.                                             |
| [`@openturn/bot`](/docs/reference/bot)         | worker  | Plug-and-play AI bots over a game. `defineBot({ decide })`, `attachLocalBot` / `attachLocalBots` / `attachHostedBot`, `simulate`. Same bot shape for random, heuristic, and MCTS players. |

## Hosting and transport

| Package                                     | Runtime | Why                                                                                                                                                                              |
| ------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`@openturn/protocol`](/docs/reference/protocol) | worker  | Wire protocol: `ClientAction`, `BatchApplied`, lobby messages, Zod schemas. Shared between client and server.                                                                    |
| [`@openturn/server`](/docs/reference/server)     | worker  | Authoritative `RoomRuntime`, `LobbyRuntime`, `createGameWorker` factory for Cloudflare, room tokens, persistence.                                                                |
| [`@openturn/client`](/docs/reference/client)     | worker  | WebSocket client. `createHostedClient` handles connect, dispatch, and state synchronization.                                                                                     |
| [`@openturn/bridge`](/docs/reference/bridge)     | browser | Iframe↔shell wire. `createGameBridge` on the iframe, `createBridgeHost` on the shell, plus the shell-controls registry the host renders save / load / reset / lobby chrome from. |
| [`@openturn/manifest`](/docs/reference/manifest) | worker  | Deployment manifest schema + HTML generator. Shared by `@openturn/deploy` (writer) and the cloud shell (reader). Owns `SHELL_CONTROL_IDS`.                                       |

## UI and tooling

| Package                                             | Runtime | Why                                                                                                                                                              |
| --------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`@openturn/react`](/docs/reference/react)               | browser | React hooks: `createOpenturnBindings`, `<OpenturnProvider>`, `useMatch`, `useRoom`, `useInspector`, `Lobby`.                                                     |
| [`@openturn/lobby`](/docs/reference/lobby)               | mixed   | Unified lobby surface — protocol extensions, runtime helpers, React UI, bot registry, and bot supervisors. Five subpath exports; only `./react` touches the DOM. |
| [`@openturn/replay`](/docs/reference/replay)             | worker  | Saved replay envelopes, timeline materialization, cursor-based playback, branching.                                                                              |
| [`@openturn/inspector`](/docs/reference/inspector)       | worker  | Non-UI inspector logic: `buildInspectorTimelineFromSource` (unified replay/hosted entry), diffs, graph highlights.                                               |
| [`@openturn/inspector-ui`](/docs/reference/inspector-ui) | browser | Ready-made React inspector components: `createInspector` returns `{ Inspector, ReplayInspector, HostedInspector }`.                                              |
| [`@openturn/deploy`](/docs/reference/deploy)             | Bun     | Build pipeline: `discoverOpenturnProject`, `buildOpenturnProject`, manifest, Worker bundle generation.                                                           |
| [`@openturn/cli`](/docs/reference/cli)                   | Bun     | The `openturn` binary: `create`, `dev`, `build`, `deploy`, `login`.                                                                                              |

## Plugins

| Package                                           | Runtime | Why                                                                                                                                                                                   |
| ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`@openturn/plugins`](/docs/reference/plugins)         | worker  | Plugin authoring + composition: `definePlugin`, `definePluginMove`, `withPlugins`. Compose cross-cutting features (chat, votes, emotes) into a gamekit game without forking the host. |
| [`@openturn/plugin-chat`](/docs/reference/plugin-chat) | mixed   | First-party in-room chat plugin: `chatPlugin` (worker-safe) plus a `<ChatBubble />` React widget under `./react`.                                                                     |

## Quick recipes

**"I want to author a game."** — Start with [`@openturn/gamekit`](/docs/reference/gamekit). Drop to [`@openturn/core`](/docs/reference/core) if gamekit doesn't fit.

**"I want to run a game in my React app."** — [`@openturn/react`](/docs/reference/react)'s `createOpenturnBindings(game, { runtime, match? })` returns a zero-prop `<OpenturnProvider>` that auto-resolves transport (in-process for local, bridge fragment for multiplayer — same provider in dev and prod). Read state with `useMatch` (just the game) or `useRoom` (full room with lobby, bridge, invite URL).

**"I want multiplayer."** — [`@openturn/server`](/docs/reference/server) on the server, [`@openturn/client`](/docs/reference/client) (via React) on the client, [`@openturn/protocol`](/docs/reference/protocol) as the wire format, [`@openturn/bridge`](/docs/reference/bridge) to connect an embedded iframe to its hosting shell.

**"I want replays."** — [`@openturn/replay`](/docs/reference/replay) for capture and load, [`@openturn/inspector-ui`](/docs/reference/inspector-ui) for the inspector UI.

**"I want to deploy."** — `openturn build` and `openturn deploy` from [`@openturn/cli`](/docs/reference/cli); the build pipeline is [`@openturn/deploy`](/docs/reference/deploy).

**"I want a player to play vs the computer."** — [`@openturn/bot`](/docs/reference/bot). `defineBot({ decide })` writes the bot, `attachLocalBot` / `attachLocalBots` binds it to a seat, the runner dispatches autonomously. Same bot works in CLI and over WebSocket via `attachHostedBot`.

## Dependency layering

Packages fan out from `@openturn/core`. A short dependency map (arrows point "depends on"):

```
@openturn/core ──┬── @openturn/gamekit
                 ├── @openturn/server ──── @openturn/protocol ── @openturn/json
                 ├── @openturn/client ────┘
                 ├── @openturn/bot ───────┘
                 ├── @openturn/replay
                 ├── @openturn/lobby (depends on core/protocol/server/client/bot)
                 ├── @openturn/plugins ── @openturn/plugin-chat
                 └── @openturn/inspector ── @openturn/inspector-ui
                                           └── @openturn/react ── @openturn/bridge ── @openturn/manifest
                                                                 └── @openturn/deploy ── @openturn/cli
```

Everything downstream of core treats `GameSnapshot` and `GameDefinition` as the canonical interface. You can drop any downstream package from your app and still have a working authored game.

## When to reach for the uncommon packages

**I need a custom transport (not WebSocket).**
Implement `HostedTransport` in `@openturn/client` — pass it as `transport` to `createHostedClient`. The `@openturn/protocol` message types let you serialize over any duplex channel (BroadcastChannel, Web Transport, an RPC bus for tests).

**I'm building my own inspector UI (not React).**
Use `@openturn/inspector` directly — `buildInspectorTimelineFromSource` produces a replay-safe timeline of steps from snapshots, batches, and (optionally) a compiled graph. It returns plain data you can render with any UI framework.

**I'm writing a CLI tool that runs games outside openturn-cloud.**
Bun-only tools can depend on `@openturn/deploy` (build pipeline) and `@openturn/server` (local room runtime) together. See [`scripts/`](https://github.com/openturn-io/openturn/tree/main/openturn/scripts) for examples.

**I want to render a saved replay without connecting to any live match.**
Import `@openturn/replay` for the envelope schema and `@openturn/inspector-ui`'s `createInspector(bindings).ReplayInspector`. No server, no client, no bridge.

**I'm embedding a game iframe into a non-openturn host.**
`@openturn/bridge` is the whole wire. `createGameBridge` inside the iframe, `createBridgeHost` on your shell — no dependency on openturn-cloud itself.

## Runtime boundaries

Worker-target packages cannot import Node or Bun APIs. Browser packages cannot import Node. Bun packages can import anything. See [concepts: runtime boundaries](/docs/concepts/runtime-boundaries) for why and how the checker enforces it.