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

> ## Agent Instructions
> These are the customer docs for kinematic, a name written in lowercase except at the start of a sentence. Kinematic provides provably fair casino games, served to a casino's site by a game server: a Cloudflare Worker that the kinematic dashboard deploys into the casino's own Cloudflare account.
> Never put SESSION_SECRET or WALLET_SECRET in code, prompts, logs, commits or chat. Read them from environment variables and ask the person you work with to set them. The dashboard's Integration page shows each secret once.
> Values such as lucky-star, luckystar.example, og-rgs-lucky-star.luckystar.workers.dev, games.luckystar.example and player_48213 are examples. Use the casino's own casino ID, game server origin, element tag, session issuer and currencies: the Instructions for your coding agent on the dashboard's Integration page hold them, or ask the person you work with.
> To debug, start at https://docs.kinematic.run/troubleshooting and https://docs.kinematic.run/reference/errors. The wallet contract is at https://docs.kinematic.run/api/wallet.openapi.yaml.
> Sandbox bets are recorded on Solana devnet. Live game servers record nothing on Solana until the audited mainnet program is deployed.

# Element

> This page lists everything a page can reach: the loader's exports, connect(), the element's attributes, members and events, the page's client, its styling tokens and parts, its fonts and its storage.

The games are one custom element, served with a loader by your game server. [Embed the games](https://docs.kinematic.run/integrate/embed.md) shows how to use it; this page lists everything a page can reach.

## Loader

`GET https://<game server>/element/v1/loader.js` answers a JavaScript module built from your casino's settings. It is revalidated on every page load, so a page sees saved changes on its next load; a page already open keeps what it loaded. The game files it imports are content-hashed and cached for a year.

| Export | Type | Meaning |
| - | - | - |
| `config` | object | Your casino's element settings. |
| `connect` | function | Connects an element to your game server. |

### config

| Field | Type | Meaning |
| - | - | - |
| `tag` | string | Your element's tag, `og-game` by default. |
| `games` | string\[] | The IDs of the games you turned on, in the order you saved them. |
| `theme` | object | The theme keys you saved on **Appearance**. Keys you left empty are absent. |
| `logo` | string or `null` | Your logo as a `data:image/png;base64,...` URL, at most 512 × 160 pixels. The games never draw it. |
| `providerMark` | boolean | Whether the kinematic mark shows while a game loads. |
| `mode` | `"sandbox"` or `"live"` | The mode your game server runs. In live mode the element keeps a player's browser storage apart from their sandbox play. |

### connect(element, options)

```ts theme={null}
connect(element: Element | null, options: {
  token: (request: { publicKey?: string }) => Promise<string>;
  onError?: (error: unknown) => void;
}): Promise<{ client: RgsClient; disconnect(): void } | undefined>
```

| Option | Meaning |
| - | - |
| `token` | Required. Returns a session token as text. Called with `{}` first, then with `{ publicKey }` when the browser holds a device key, and again before each token expires. |
| `onError` | Receives every failure of `connect()` and every `og-error` of the element. Without it, errors go to `console.error`. |

`connect()` writes your saved theme as inline `--og-*` tokens on the element, unless the element already has that token inline, then binds the element to a connection for the token's player and currency. It resolves before the connection opens, to:

* `client`: the page's connection for this player and currency, shared by every element of that player and currency.
* `disconnect()`: unbinds the element. When no element of that player and currency is left, it closes the connection.

It resolves to `undefined` after it passed the failure to `onError`:

| Failure | Cause |
| - | - |
| `connect() needs a <tag> element` | The element is missing, or has another tag. |
| `no_games` | Your casino offers no game. |
| `<tag> is already defined by another element; choose another tag.` | Another script on the page defined your tag. |
| `catalog_unavailable` | The game server refused the catalog: origin, currency or settings. |
| Your `token` function's error | Your session endpoint failed. |

## Attributes

| Attribute | Values | Meaning |
| - | - | - |
| `game` | A game ID | The game to show. Changing it loads the new game and resets its options. A game you did not turn on falls back to your first game. |
| `controls` | Boolean | Shows the bet controls. Players bet only through them. |
| `minimal` | Boolean | The game's screen and readouts only, without the title bar, the toolbar and the 600-pixel minimum height. |
| `stats` | Boolean | Adds a **Live stats** button that fires `og-intent` with the action `stats`. |
| `fairness` | Boolean | Adds the **Provably fair** button. The loader sets it on every element and opens the dialog. |

`stats` and `fairness` are read when the element builds its view. The game IDs are `mines`, `plinko`, `dice`, `limbo`, `crash`, `roulette`, `keno`, `baccarat`, `wheel`, `pump`, `diamonds`, `hilo` and `blackjack`. See [Games](https://docs.kinematic.run/reference/games.md).

## Properties and methods

Available once the tag is defined, for example after `await customElements.whenDefined(config.tag)`.

| Member | Meaning |
| - | - |
| `game` | The game shown, after any fallback. |
| `configuration` | A copy of the player's current settings in the controls: amount, mode, Auto settings and the game's options. |
| `animationSpeed` | `normal`, `fast` or `turbo`. |
| `outcome` | The last result shown: `win`, `loss`, `neutral` or `undefined`. |
| `setSpeed(speed)` | Sets `normal`, `fast` or `turbo`. Kept when the element rebuilds. |
| `setVolume(volume)` | Sets the volume from 0 to 1. |
| `setMuted(muted)` | Mutes or unmutes, and updates the toolbar. |
| `unlockAudio()` | Starts audio from your own click handler, when your page has its own controls. |
| `applyTheme(theme)` | Writes the theme keys you pass as inline tokens, then re-themes the game. |
| `refreshTheme()` | Re-reads the tokens. Call it after you change a token on an ancestor. |

The loader drives the element's other members, such as `setState()` and `present()`, for you. Calling them from your page conflicts with it.

## Events

All events bubble and cross the shadow boundary.

| Event | `detail` | When |
| - | - | - |
| `og-ready` | none | The game's scene is built: on first load, after a `game` change and after a reload of the scene. |
| `og-intent` | `{ game, action, config, index }` | The player pressed something. A request, not an accepted bet. |
| `og-presented` | `{ id }` | A confirmed result became visible to the player. Never credit or settle anything from it. |
| `og-error` | An `Error` whose `message` is the code | A bet or action was refused, or the connection reported an error. |

The `og-intent` actions are `bet`, `configure`, `start-auto`, `stop-auto`, `amount-half`, `amount-double`, `stats`, `fairness`, and each game's own: Mines `reveal`, `cashout` and `random-tile`; Crash `cashout`; Keno `quick-pick`; Pump `pump` and `cashout`; HiLo `higher`, `lower`, `same`, `skip` and `cashout`; Blackjack `hit`, `stand`, `double`, `split`, `insure` and `decline`.

## The connection's client

`client` is the page's connection to your game server for one player and currency.

| Member | Meaning |
| - | - |
| `connected` | Whether the connection is open. |
| `balanceKnown`, `displayedBalance` | Whether the balance is known, and the balance the game shows. |
| `sync()` | Reads the balance again. Call it when your own cashier closes in the page. |
| `history(after)` | The player's settled bets, page by page. |
| `close()` | Closes the connection. |

| Event | When |
| - | - |
| `receipt` | A bet's receipt arrived. |
| `balance` | The balance changed. |
| `connection` | The connection opened or closed: `{ connected }`. |
| `error` | The client reported an error code. |
| `proof-error` | A proof could not be stored or checked in the browser. It never blocks a result. |

## Styling

Set `--og-*` tokens on the element, an ancestor or `:root`. The element reads them when it builds its view and whenever its `style` or `class` changes; after changing a token on an ancestor, call `refreshTheme()`. Colours take any CSS colour the browser resolves; transparency is dropped.

| Token | Sets | Default |
| - | - | - |
| `--og-accent` | Your brand colour: the bet key, highlights, focus and the screen's line of light. | `#1a1a1a` |
| `--og-color-scheme` | `light` or `dark` panels. | `light` |
| `--og-stage` | `screen` keeps the play area dark in both schemes; `ambient` follows the scheme. | `screen` |
| `--og-background` | The level behind the frame. | Derived |
| `--og-surface` | The frame: title bar, controls and toolbar. | Derived |
| `--og-text` | Main text, held at 7:1 contrast or more. | Derived |
| `--og-muted` | Labels and captions, held at 4.5:1 or more. | Derived |
| `--og-accent-ink` | The label on the bet key, held at 4.5:1 on it. | Derived |
| `--og-accent-bright` | The lighter accent for highlights. | Derived |
| `--og-win` | Win digits, the win plate and the history. | Green |
| `--og-loss` | `quiet` keeps losses neutral; a colour marks them. | `quiet` |
| `--og-danger` | Hazards and errors only: a mine, a crash, a burst. | Rose |
| `--og-radius` | The frame's corner radius. | `0px` |
| `--og-roundness` | Control shape from `0` (sharp) to `1` (round); the bet key is a pill from `0.5`. | `0.6` |
| `--og-density` | `comfortable`, or `compact` for short embeds. | `comfortable` |
| `--og-font` | Text face. Setting it skips the bundled Geist. | Geist |
| `--og-font-numeric` | Numbers face. Setting it skips the bundled Geist Mono. | Geist Mono |
| `--og-provider-mark` | `on` shows the kinematic mark while a game loads. The loader always sets it from your settings. | `off` |
| `--og-height` | Desktop height, at least 600 pixels. | `720px` |
| `--og-mobile-height` | Height of the compact layout's screen and controls. | `min(760px, 100svh)` |
| `--og-card-face`, `--og-card-ink`, `--og-card-red`, `--og-card-spades`, `--og-card-hearts`, `--og-card-diamonds`, `--og-card-clubs`, `--og-card-back`, `--og-card-back-accent` | Playing cards in Baccarat, Blackjack and HiLo. | Derived |
| `--og-gem-ruby`, `--og-gem-citrine`, `--og-gem-emerald`, `--og-gem-aqua`, `--og-gem-sapphire`, `--og-gem-amethyst` | Diamonds' gem colours. | Set per gem |

When a colour you set would make text hard to read, the element moves its lightness until the pair reaches its contrast floor, and keeps its hue. `--og-background`, `--og-surface` and `--og-accent-bright` are used exactly as given.

### Precedence

The loader writes your saved theme as inline tokens on the element, except tokens the element already has inline. To override a saved value for one element, set the token inline, in the `style` attribute or with `element.style.setProperty()`, before `connect()`, or call `applyTheme()`. A stylesheet rule loses to an inline token unless it is `!important`.

### Shadow parts

Style inside the element with `::part()`, for example `og-game::part(primary-button) { letter-spacing: 0.02em; }`.

| Part | What it is |
| - | - |
| `shell` | The whole frame. |
| `header` | The title bar: game, options and balance. |
| `controls` | The controls column. |
| `mode-switch`, `auto-controls` | Manual and Auto, and the Auto settings. |
| `primary-button` | The bet key. |
| `stage` | The game's screen. |
| `footer` | The toolbar. |
| `settings`, `fairness`, `viewport-lock` | The settings popover, the Provably fair button and the lock key. |
| `result` | The large result number of Dice, Limbo, Crash, Roulette and Wheel. |
| `win-tag`, `win-multiplier`, `win-details` | The win plate and its multiplier and payout. |
| `stream-status`, `stream-tape` | The Turbo Auto status plate and result tape. |
| `roll-indicator`, `dice-direction` | Dice's result pin and its under and over switch. |
| `random-tile` | Mines' random tile key. |
| `keno-payouts` | Keno's payout strip. |
| `roulette-table`, `baccarat-table` | The Roulette and Baccarat tables. |
| `blackjack-actions` | Blackjack's hand keys. |
| `diamonds-legend`, `diamonds-plate` | Diamonds' payout legend and its plates. |

The Provably fair dialog sits in its own shadow root on `document.body` and takes the opening element's colours, radius and fonts. It exposes no parts.

## Fonts

The element ships Geist and Geist Mono and loads them from your game server, so it contacts no font service. Setting `--og-font` or `--og-font-numeric` before the element connects skips the bundled face. The fonts you name must be loaded by your page: the element never downloads a font you name.

## Browser storage

The element keeps its working state in the player's browser:

* `sessionStorage`, under keys starting with `og:`, for bets in flight, so a reload does not lose them.
* IndexedDB, for the player's device key and the proofs of their bets.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.