# totallynotfun — build a party game

This is the whole contract. A game is one directory with four files, written
against `@totallynotfun/sdk`, run on your laptop with `npx totallynotfun play`,
published by pull request. If it is not on this page it is not part of the
contract; do not guess it, ask.

## 1. WHERE THE DIRECTORY GOES — read this before you write a line

There are exactly two correct locations, and which one you are in depends on
what you cloned:

```
games/<id>/          ← the public repo (totallynotfun-games): repo root
lab/games/<id>/      ← the platform monorepo: under lab/, never anywhere else
```

**If you can see a `packages/` directory, you are in the monorepo, and your
game goes in `lab/games/<id>/`.** Create that directory; it is where the
reference games already live. Two things follow, and both are hard:

- **`packages/server/src/games/` is NOT the lab.** It is the platform's own
  built-in catalogue: a different contract, a different registry, six manual
  touch points. A game written there is not a lab game, cannot be submitted,
  and will not load in a lab room. Neither is `packages/controller`, nor any
  plugin registry, nor any dispatch branch — the lab has none of those.
- **Nothing outside your own `lab/games/<id>/` may be edited.** Not a shared
  file, not a check, not a counts or ratchet JSON, not another game. CI
  refuses a pull request that touches any path outside one game directory
  before it runs a single line of your code.

An existing game elsewhere in the tree with a similar name is not your game
and is not a starting point. Copy `lab/games/hello-world/` instead (§10).

## 1b. What a game provides

```
<the directory above>/
  manifest.ts     id, name, author, players, controls, how to play, tutorial
  server.ts       init / onInput / tick / isGameOver / getResults / getPlayerState  (pure)
  Controls.tsx    the phone  — a React component; props: state, send, player
  Renderer.tsx    the TV     — a React component; props: state, players
  Spectator.tsx   optional   — a late joiner's phone; props as Renderer
  checks/         optional   — the game's own harness (a template is provided)
```

- `<id>` is kebab-case, unique in the repository, and equals `manifest.id`.
- Every file imports from `@totallynotfun/sdk` and from the game's own
  directory. Nothing else. No `package.json`, no lockfile, no scripts, no
  other dependency. CI refuses the pull request before it runs anything.
- `server.ts` is pure: state in, state out. It keeps nothing outside the
  value it returns.

## 2. manifest.ts — every field, one line each

```ts
import type { Manifest } from "@totallynotfun/sdk";
// `satisfies`, NOT `: Manifest`. The annotation widens `hiddenInfo` to
// `boolean`, and the compiler then cannot tell which rule to hold you to —
// it asks a public game for projections it does not need. `satisfies`
// checks the same shape and keeps the literal.
export const manifest = { protocolVersion: 1, id: "hello-world", /* ... */ } satisfies Manifest;
```

`Manifest` has these fields and no others:

- `protocolVersion` — the contract version this game targets. `1`.
- `id` — kebab-case; the directory name.
- `name` — shown on the card and the TV.
- `author` — shown verbatim on the card and in the lobby. The only credit.
- `description` — one or two sentences for the card.
- `category` — `"party" | "trivia" | "strategy" | "skill"`.
- `tags` — optional free words. Not used for filtering.
- `minPlayers`, `maxPlayers` — the room refuses to start outside this range.
- `controls` — a `ControllerLayout`: `{ joystick: boolean; actionButton:
  boolean; actionButtonLabel?: string; inputs?: ControllerInput[] }`. What
  the phone declares; the automatic tutorial is drawn from it. Each
  `ControllerInput` is one declared control — a `joystick`, `button`, `dpad`,
  `touchpad`, `tilt`, `text-input` or `choice` — with an `id` and a position.
- `hiddenInfo` — `true` if any player holds state others must not see.
  **Supported — build the hidden-information game if that is the game.**
  `true` makes BOTH projections REQUIRED: `getPlayerState` and
  `getSpectatorState` (§3). The registry refuses a manifest that declares
  `hiddenInfo` with only one of them defined, and a room refuses to start it,
  so one without the other is not a partial implementation — it is a game
  nobody can play. With `true` the TV is sent `getSpectatorState(state)` and
  never the raw state, each phone is sent `getPlayerState(state, id)`, and the
  leak scan in §8 reads both. With `false` everyone is sent the whole state
  and neither projection is needed. Declare it as a literal `true`/`false`,
  not a computed boolean: the compiler checks this rule where the manifest
  meets the server, and it can only check a literal.
- `spectatorView` — optional `"scores" | "full" | "none"`: what a late
  joiner's phone shows.
- `roles` — optional `GameRoleInfo[]` for asymmetric games: `{ id, name,
  color?, maxCount? }`.
- `howToPlay` — `HowToPlay`: `{ objective: string; steps: string[] }`. One
  line and three to five imperative steps, shown on the TV before the game.
  REQUIRED.
- `tutorial` — a `GameTutorial`, or `"auto"` to derive one from `controls`.
  REQUIRED. What is gated is exactly this: `howToPlay` and `tutorial` are
  required fields, so a missing one fails types. A coach hint or practice
  round on a non-obvious control is strongly recommended and is read at
  graduation, not gated — unintuitive pieces derail a room.

## 3. server.ts — the reducer, one line each

```ts
import type { GameServer, Player, Ctx, InputEvent } from "@totallynotfun/sdk";
export const server: GameServer<State> = { init, onInput, tick, isGameOver, getResults };
```

A `GameServer` is these functions. Each receives a `Ctx` (§4) as its last
argument except `isGameOver` and `getResults`, which are pure reads.

- `init(players, ctx)` → `State` — the starting state for these players.
  `players` is `Player[]`: `{ id, name, color, connected, isHost, role,
  gameRole? }` and a few cosmetic fields you can ignore.
- `onInput(state, playerId, input, ctx)` → `State` — one sanitised input
  (§6) from one phone. Return the new state; ignore what you do not expect.
- `tick(state, deltaMs, ctx)` → `State` — on every tick of the room's loop,
  designed at sixty a second. Do not depend on the cadence: integrate with
  `deltaMs`. Large gaps are capped so a sleeping laptop does not jump (the
  cap is the runtime's). A turn-based game returns `state` unchanged.
- `isGameOver(state)` → `boolean` — asked every tick. `true` ends the game.
- `getResults(state)` → `GameResults` — once, when over: `{ scores, winner,
  placements, outcome?, headline?, valueLabel? }`. `outcome` is a
  `ResultsOutcome`: `{ kind: "ranked" }`, `{ kind: "team", winningTeamId,
  teams }`, `{ kind: "coop", won }` or `{ kind: "solo", winnerId }`.
- `getPlayerState(state, playerId)` → `object` — what THIS phone may see.
  REQUIRED when `hiddenInfo` is true (§2). Optional otherwise.
- `getSpectatorState(state)` → `object` — the view for anyone who is not a
  seated player: the TV under `hiddenInfo`, and a spectator's phone always.
  REQUIRED when `hiddenInfo` is true (§2). Optional otherwise.

Who receives what: the TV receives the whole `State` on every tick it
changes — unless `hiddenInfo` is true, in which case it receives
`getSpectatorState(state)` and never the raw state. Each phone receives
`getPlayerState(state, id)` when you define it, otherwise the whole `State`,
every sixth tick (ten times a second); a spectator's phone receives
`getSpectatorState(state)` every thirtieth tick when defined. **Hidden
information works** (§2) — declare it, write both projections, and the leak
scan in §8 reads them.

State rules, all gated:

- JSON-serialisable: plain objects, arrays, numbers, strings, booleans,
  `null`. No `Map`, `Set`, class instances, functions, `Date`, `bigint`.
- Under the per-tick size cap: **256 KB** of serialized state. Past it the
  sandbox stops the game with `oversize` (§4). Design for a few kilobytes
  anyway — bandwidth is the box's binding constraint.
- Return a new object when something changed. The loop serialises to decide
  whether to send, so an unchanged state costs nothing on the wire.

## 4. ctx — and why it exists

- `ctx.rng()` → a number in `[0, 1)`. Seeded per room. Use it wherever you
  would have used `Math.random`.
- `ctx.now()` → milliseconds on the tick clock, starting at `0` when the
  game starts. Use it wherever you would have used `Date.now`.
- `ctx.connected` → `ReadonlySet<string>` of player ids whose phone is
  attached right now. A player absent from it is offline or gone.

Why (the sandbox): your reducer runs inside a JavaScript interpreter compiled
to WebAssembly, one per room, with **32 MB of memory** and a **50 ms deadline
on every call**. Inside it `Math.random` and `Date.now` are replaced
by `ctx.rng` and `ctx.now`, so two rooms fed the same inputs play the same
game. That is how a reported game is replayed and how a stalled one is
stopped. The server lint fails a `server.ts` that names `Math.random` or
`Date.now`. Nothing else is stable across replays.

When the sandbox stops a game — a throw, running out of memory, a call past
its deadline, an oversize state, or a return that does not serialise — the
room receives an `error` with `{ reason, entry, message }` where `reason` is
one of `"throw" | "deadline" | "memory" | "oversize" | "bad-return"` and
`entry` names the function, and the room returns to the lobby. The results
say the game was stopped; nobody wins.

## 5. Controls.tsx and Renderer.tsx — the phone and the TV

Both are ordinary React components rendered on the lab's origin. They are
not sandboxed; the hard client rules in §8 are what stands between them and
the visitor's browser, and they are enforced before the code is served.

- `Controls` receives `state` (what §3 says a phone gets), `send` (queue one
  input, §6) and `player` (this phone's `Player`).
- `Renderer` receives `state` and `players`.
- `Spectator`, if present, receives what `Renderer` receives.

From the SDK (§12 is the authoritative list, generated from the package):
phone primitives `TapButton`, `BidPad`, `PlayingCard`, `DrawCanvas`,
`VirtualJoystick`, `CoachHint`, `Onboarding`; TV parts `PlayingCardTV`,
`safeRender`, `useNarration`; motion `injectKeyframes`, `DUR`, `EASE`; the
room's `PLAYER_COLORS`; card, poker and chess helpers; `autoTvTutorial`.
These exist in the platform today; the SDK re-exports them. Every control a
phone shows is at least 44pt tall (advisory, §9).

Colours, fonts, canvas, sound: your call. An emoji game that is fun beats a
polished game that is not. Taste is advisory here (§9).

## 6. Input — the six kinds and their caps

`send` takes one `InputEvent`. The server sanitises every message before
your reducer sees it, with these exact numbers. A value past a clamp is
clamped or the whole message is dropped, as stated, silently. Design inside
them; if a control needs a wider range, scale it on the phone.

| kind | fields | what the server does |
|---|---|---|
| `move` | `x`, `y` | each clamped to -1..1; a non-finite value becomes 0, so a quiet stick reads centred and is never latched |
| `position` | `position` | clamped to 0..1; a non-finite value drops the message and the last good position holds |
| `action` | `action`, `angle?`, `aimX?`, `aimY?`, `charge?` | an `action` longer than 256 chars drops the message; `angle` any finite number; `aimX`/`aimY` clamped to -1..1; `charge` clamped to 0..1; a malformed modifier arrives as `undefined` and the verb still arrives |
| `choice` | `choice` | must be an integer or the message is dropped — never coerced to 0, which would commit a move the player never made. Not range-checked: bounds-check the index yourself |
| `text` | `text` | cut to 200 chars; a non-string becomes `""` |
| `draw` | `strokes` | at most 120 strokes per message; at most 512 numbers (256 x,y pairs) per stroke; 20,000 numbers per message, whole strokes dropped once the budget is spent; coordinates clamped to 0..1 and rounded to 1/10000; width clamped 0.001..0.08 with default 0.018; `color` must be `#rgb` or `#rrggbb` or it becomes `#000000`; rate: a burst of 5 messages, then one more every 50 ms, extras dropped |

Inputs are queued and drained in order at the next tick; a phone that queues
more than the room's per-tick budget has the surplus dropped. The precedent
for this table: an aim value sent outside -1..1 arrived clamped and a
two-phone game read a wrong angle for weeks with nothing red anywhere.

## 7. The four commands — all four are built, and two more gates besides

```
npx totallynotfun create <id>   scaffold the game directory from the template
npx totallynotfun check         the hard gates (§8), then the advisory warnings (§9)
npx totallynotfun play          a room on this machine: TV URL + a QR for the phones
npx totallynotfun submit        prove it is green, then print the steps to open the PR
```

`tnf` is the alias: `tnf create <id>`, `tnf check`, `tnf play`,
`tnf submit`. `check` exits 0 only when every hard gate passes; read
the first failure, fix it, run it again. **This is the command CI runs on
your pull request** — same binary, same steps, same exit code.

Its five steps, in order, each reported even when an earlier one failed:
**boundary** (§8's two lints, self-tested on a hostile fixture first),
**types**, **consumer** (your directory built and run in a project that has
never seen this repository), **harness** (your `checks/` — exit code AND
assertion count), **play** (§8's termination rule, in a real room over real
sockets). Flags: `--bail`, `--json`, `--skip-play` (CI does not skip it),
`--timeout <ms>` to move the play bound §8 states. `submit` re-runs all of
that, then prints the pull-request steps; it sends and opens nothing.

`play` binds the runtime on your LAN, prints the TV address and a QR of the
phone address, adds that host to the origin allowlist for this run, and says
one sentence about the firewall prompt; if the machine has no LAN address it
says so instead of printing `localhost`. Flags: `--host`, `--port`,
`--game <path>`.

**In the platform monorepo**, the same two lints run over every game under
`lab/games/` as npm scripts, and these are the two a maintainer will quote
back at you:

```
npm run check:sdk-boundary    the import and purity lint (§8), every lab game
npm run check:lab-consumer    every lab game built and run in a clean project
```

`check:lab-consumer` **exits 1 with zero failed assertions** while the tree is
dirty or your game is uncommitted — its coverage ratchet will not bank a floor
it cannot reproduce, which for a new game is always. Read the line it prints:
`N passed, 0 failed` is a pass whatever the exit code says. Do not "fix" it by
editing the counts file; editing any ratchet or counts JSON is one of the paths
CI refuses outright (§1).

## 8. The rules the gates enforce — hard, because they protect other people

The two glob paths below are written for the public repo; in the monorepo the
same scan reads `lab/games/**` (§1).

- **Client lint** over `games/**/*.tsx`: no `fetch`, `XMLHttpRequest`,
  `WebSocket`, `EventSource`, `sendBeacon`; no `localStorage`,
  `sessionStorage`, `indexedDB`, `document.cookie`; no `<form>`, external
  `href`, `window.open`, `location` assignment; no `eval`, `new Function`,
  URL `import()`, `<script>`, `<iframe>`, `dangerouslySetInnerHTML`; imports
  only from `@totallynotfun/sdk` and the game's own directory.
- **Server lint** over `games/**/server.ts`: no Node builtins, `require`,
  `process`, timers, `fetch`; no `Math.random`/`Date.now` (use `ctx`).
- **Hidden-info leak scan**: if `hiddenInfo` is true, BOTH `getPlayerState`
  and `getSpectatorState` exist, and neither projection contains another
  player's private fields.
- **Termination — THE BOUND IS 120 SECONDS.** `tnf check`'s play step bundles
  your `server.ts`, boots the lab runtime with your directory registered,
  seats bots, clears the ready gate and drives a real room until `game:end`
  arrives. **120,000 ms is one wall-clock ceiling over all of that** — the
  bundle, the boot, the seating and the game. `--timeout <ms>` moves it on
  your machine; CI runs the default, so the default is the rule.
  - **The bots**: as many as `minPlayers`, never fewer than two, never more
    than `maxPlayers`. Each presses **every control the manifest declares** —
    the action verb always, the joystick if you declare one, each `choice`
    (cycling the options), each touchpad, a `text` every tenth press — once
    every 80 ms, from the ready gate until the game ends. A control you
    declare and never read is a control they will press anyway.
  - **Design for under 90 seconds** of gameplay so a loaded CI runner has
    room. The shipped reference game (§10) ends in **20.5 s**.
  - **A real-time game needs a CLOCK, not only a win condition.** "Last one
    standing" and "all five floors cleared" are not termination: bots that
    wander and survive satisfy neither, and the room hangs until the ceiling.
    Put a hard deadline in `tick` — a round count, a timer off `ctx.now()`,
    a sudden-death phase — and let `isGameOver` return true on it.
  A game that cannot end with bots pressing buttons cannot end with people.
- **Budgets**: frame time per renderer (mounted at 4K; ceiling set from the
  heaviest shipped renderer), asset size per directory, serialized state
  size per tick.
- **Types**, and the game's own `checks/` harness with an assertion count.
- **Build rules**: a game directory has no `package.json`, no scripts, no
  dependencies beyond `@totallynotfun/sdk`; CI refuses anything else before
  it runs a single line of it.

## 9. Advisory — warnings, never blockers

Emoji in art, the resolution floor for canvas renderers, sound and music
checks, the visual identity bar, the 44pt touch floor, the coach hint on a
non-obvious control. Printed after the hard gates and posted on the pull
request. Read by a human when a game is considered for the shelves; never
read by the lab.

## 10. Reference games — copy the nearest one

Start with `hello-world`: the whole contract used once each, about 150 server
lines, a prompt on the TV, four answers on the phones, five rounds, results.
`hiddenInfo: false`, `tutorial: "auto"`, `ctx.rng` for the prompt order. Copy
its directory and change things.

**Read its clock, because it is the number §8 is about.** Five rounds, each a
12-second answer window plus a 4-second reveal — but the window closes the
instant every connected phone has answered, so the round is usually just the
reveal. That is 20 seconds against the bots and at most 80 if every phone sits
there, both inside the 120-second bound with room to spare. Measured through
`tnf check`: **20.5 s**, three runs, no variance. If you copy it and add
rounds or lengthen a phase, do that arithmetic again — the worst case is the
one the gate can hit.

Then `pong`: joystick input, a canvas TV, `ctx.now` on a real-time loop and a
match clock in two budgets. Then the showcase, for one thing
each: `sharks-and-minnows` (the art and audio kits; how big a game can get),
`telestrations` (`draw` input and the drawing kit), `trap-happy` (determinism
under the sandbox; real-time and turn-based in one game), `organ-futures`
(the state-size cap and the broadcast budget). They are large. Read them for
that one thing.

**Take your ENDING from any of them now — but read the bottom two first.**
Measured through `tnf check`, a range where it was run more than once:

```
hello-world        20.5 s    five fixed rounds                 a clock
telestrations      51.3 s    62 s worst case, any lobby size   a budget
trap-happy         67.6 s    55 s soft deadline, 85 s fuse     a clock
organ-futures      68.5 s    65 s match + 3 s countdown        a clock
sharks-and-minnows 49-66 s   72 s soft, 88 s fuse, per-round   a clock
pong               31-48 s   60 s soft, 76 s fuse, per-rally   a clock
```

All six now state a total their own `checks/` harness asserts as ARITHMETIC;
copy that habit, not the number. The bottom two are the lesson: until
2026-09-11 both were a win condition with NO length — `pong` measured 31.8 /
62.9 / 79.0 / 31.1 / TIMED OUT / 43.6 s on identical code, `sharks-and-minnows`
failed four of four. A win condition a bot reaches BY CHANCE is not
termination, and each needed a SECOND budget a level down (a round, a rally).

## 11. Publishing

Publishing is a pull request, so **a GitHub account is the prerequisite**.
Players never need one. Fork the repository, one directory per game, one
pull request per game; `check` green locally first. A merge that passes the
hard gates is playable at `lab.totallynotfun.com` with nobody judging it.
Today a maintainer presses the button that publishes a green pull request;
it becomes automatic once the lab's red team has passed. A maintainer may
then list the game, or graduate it into the main app; there is no turnaround
promise, and the lab link works the whole time.

Every lab lobby carries a report link. A reported game can be switched off in
seconds by a maintainer; a person then looks. You keep the copyright; the
platform gets a licence to host, show and sell passes over it
(`LICENSE-GAMES.md`).

## 12. GENERATED FROM @totallynotfun/sdk — do not hand-edit

<!-- BEGIN GENERATED -->
# `@totallynotfun/sdk` — reference

Generated from `packages/sdk/src/index.ts` by `packages/sdk/scripts/gen-reference.mjs`.
Do not edit this file: edit the doc comment on the export and regenerate
(`npm run gen:reference -w packages/sdk`). The consumer test fails when this is stale.

**89 exported symbols** (budget: under 100). A namespace counts as one; its 98 members are listed beneath it.

A game imports from the bare specifier only — `import { … } from "@totallynotfun/sdk"` — plus `react` and its own directory. Nothing else resolves past `check:sdk-boundary`.

## The contract (OD-01)

| symbol | kind | what it is |
|---|---|---|
| `PROTOCOL_VERSION` | const | The protocol version this SDK speaks; a manifest must declare it. — `1` |
| `Manifest` | type | One game's declaration: id, author, players, controls, hidden info, how to play, tutorial. |
| `Ctx` | type | What the runtime hands the server on every call: a seeded rng, the tick clock, who is connected. |
| `GameServer` | type | The pure server: init, onInput, tick, isGameOver, getResults, and the two projections (both required under hiddenInfo). |
| `HiddenInfoServer` | type | A server that must project BOTH per-player state and the TV's view — what hiddenInfo: true demands. |
| `InputEvent` | type | One sanitised controller input, with the ingress clamps documented on each field. |
| `PhoneProps` | type | Props the runtime gives Controls.tsx: this player's state, the player, send, paused. |
| `TvProps` | type | Props the runtime gives Renderer.tsx and Spectator.tsx: the state, the players, paused. |
| `Game` | type | A manifest paired with the server that satisfies it. |
| `defineGame` | function | Pair a manifest with its server; the compiler checks the hidden-info rule here. — `{ <S>(manifest: Manifest & { hiddenInfo: true; }, server: HiddenInfoServer<S>): Game<S>; <S>(manifest: Mani…` |
| `LegacyPlugin` | type | The structural subset of today's GamePlugin that the legacy bridge reads. |
| `LegacyExtras` | type | What a legacy plugin cannot supply and the manifest requires (author, tutorial, howToPlay). |
| `legacy` | function | Bridge a copied server plugin onto the contract without rewriting its logic first. — `<S>(plugin: LegacyPlugin<S>, extras: LegacyExtras) => { manifest: Manifest; server: GameServer<S>; }` |

## Shared types the contract is written in

| symbol | kind | what it is |
|---|---|---|
| `Player` | type | A seat in the room: id, name, colour, connected, ready, host, role, avatar. |
| `PlayerColor` | type | The sixteen player colours, as a literal union of hex strings. |
| `ControllerLayout` | type | The phone's declared controls: joystick, action button, and/or a list of inputs. |
| `ControllerInput` | type | One declared phone control: joystick, button, dpad, touchpad, tilt, text-input or choice. |
| `GameRoleInfo` | type | An asymmetric role a game can assign in the roster: id, name, colour, max count. |
| `GameCategory` | type | The four catalogue buckets: party, trivia, strategy, skill. |
| `GameResults` | type | What getResults returns: scores, winner, placements, and the optional outcome layer. |
| `ResultsStanding` | type | One row of the standings: playerId, place (never rank), value, detail, team, winner. |
| `ResultsOutcome` | type | How a game was won: ranked, team, coop or solo, each with its own fields. |
| `TeamResult` | type | A team's result in a team-outcome game. |
| `HowToPlay` | type | The pre-game card: one objective line and 3–5 imperative steps. |
| `DrawStroke` | type | One freehand stroke: colour, width and a flat [x0,y0,x1,y1,…] array in 0..1. |
| `GameTutorial` | type | The TV tutorial a manifest may hand-author instead of "auto": accent, controls, steps or roles. |
| `TvControlSpec` | type | One control drawn on the tutorial's phone mock-up. |
| `TvTutorialStep` | type | One caption-and-highlight step of a TV tutorial (the TV caps them at three). |
| `TvTutorialRole` | type | One side of an asymmetric game's tutorial: its label, controls and steps. |

## Shared values

| symbol | kind | what it is |
|---|---|---|
| `PLAYER_COLORS` | const | The sixteen player colours with names, in allocation order. — `readonly [{ readonly id: "crimson"; readonly hex: "#FF2B5E"; readonly name: "Crimson"; }, { readonly id: "s…` |
| `autoTvTutorial` | function | Derive a TV tutorial from a controller layout — what tutorial: "auto" does. — `(layout: ControllerLayout \| null \| undefined) => GameTutorial` |
| `clamp` | function | Clamp a number into [min, max]. — `(value: number, min: number, max: number) => number` |
| `lerp` | function | Linear interpolation a + (b - a) * t. — `(a: number, b: number, t: number) => number` |
| `monogramLetter` | function | The initial the platform draws in a player's avatar circle, from their name. — `(name: string) => string` |

## The art kit (GAME_DESIGN_GUIDE §1b)

| symbol | kind | what it is |
|---|---|---|
| `DUR` | const | Motion durations in ms: tick, beat, flourish, idle. — `{ readonly tick: 120; readonly beat: 260; readonly flourish: 600; readonly idle: 2800; }` |
| `EASE` | const | The platform's easing curves as CSS strings. — `{ readonly out: "cubic-bezier(0.16, 1, 0.3, 1)"; readonly outBack: "cubic-bezier(0.34, 1.56, 0.64, 1)"; rea…` |
| `easeFns` | const | The same easings as functions of t in 0..1, for canvas animation. — `{ readonly linear: (t: number) => number; readonly outCubic: (t: number) => number; readonly outExpo: (t: n…` |
| `injectKeyframes` | function | Inject the platform's keyframes (plBob, plPulse, …) once per document; safe to call on every render. — `() => void` |
| `Ramp` | type | A tonal ramp built from one hex: top, base, bot, rim, for gradients and sprite styles. |
| `ramp` | function | Build a Ramp from a hex colour. — `(hex: string, opts?: { spread?: number \| undefined; } \| undefined) => Ramp` |
| `alpha` | function | A hex colour with an alpha, as rgba(). — `(hex: string, a: number) => string` |
| `mix` | function | Mix two hex colours by t. — `(hexA: string, hexB: string, t: number) => string` |
| `lighten` | function | Lighten a hex colour by an amount in HSL lightness. — `(hex: string, amt: number) => string` |
| `darken` | function | Darken a hex colour by an amount in HSL lightness. — `(hex: string, amt: number) => string` |
| `SpriteDef` | type | A drawn sprite: a list of shapes in a 64-unit box, styled by a Ramp at draw time. |
| `SpriteStyle` | type | How a sprite is coloured: a primary ramp and an optional second. |
| `spriteDataUri` | function | Render a sprite to an SVG data: URI for an <img> or a CSS background. — `(def: SpriteDef, style: SpriteStyle, opts?: { shadow?: boolean \| undefined; } \| undefined) => string` |
| `spriteSvg` | function | Render a sprite to an SVG string. — `(def: SpriteDef, style: SpriteStyle, opts?: { shadow?: boolean \| undefined; } \| undefined) => string` |
| `drawSprite` | function | Draw a sprite onto a 2D canvas context at x, y, size, with optional rotation. — `(ctx: Canvas2DLike, def: SpriteDef, style: SpriteStyle, x: number, y: number, size: number, opts?: { angle?…` |
| `SPRITES` | const | The house sprite library: GEM, ROCK, COIN, CROWN, FLAME, STAR, HEART, SKULL — drawn, never emoji. — `{ readonly GEM: SpriteDef; readonly ROCK: SpriteDef; readonly COIN: SpriteDef; readonly CROWN: SpriteDef; r…` |

## The kits, as namespaces (one symbol each)

| symbol | kind | what it is |
|---|---|---|
| `cards` | namespace | Playing cards: Card, Suit, Rank, a 52-card deck, shuffles and parsing (`cards.cardFromCode`). |
| `poker` | namespace | Poker hand evaluation: rank a 5–7 card hand, compare hands, name the result. |
| `chess` | namespace | Chess: legal-move generation, check and mate detection over a plain board. |
| `music` | namespace | The TV's seven generated music beds (start/stop/set*State) and the room's mix (levelOf). |
| `bots` | namespace | CPU seats: makeBots, resolveBotFill, isBot, isPresent, botName — the deterministic half of the kit; draw from ctx.rng for the rest. |

### `cards.` (15 members)

- functions: `cards.buildDeck`, `cards.cardFromCode`, `cards.draw`, `cards.makeCard`, `cards.makeRng`, `cards.shuffle`
- consts: `cards.RANK_LABEL`, `cards.RANKS`, `cards.SUIT_IS_RED`, `cards.SUIT_NAME`, `cards.SUIT_ORDER`, `cards.SUITS`
- types: `cards.Card`, `cards.Rank`, `cards.Suit`

### `poker.` (3 members)

- functions: `poker.evaluate7`
- consts: `poker.HAND_CATEGORY`
- types: `poker.HandEval`

### `chess.` (8 members)

- functions: `chess.legalDestinations`, `chess.moveDistance`, `chess.movePath`, `chess.sqIdx`, `chess.sqName`
- consts: `chess.PIECE_VALUE`
- types: `chess.ChessKind`, `chess.ChessOcc`

### `music.` (29 members)

- functions: `music.antsyIntensity`, `music.chaseThinning`, `music.isSilent`, `music.levelOf`, `music.onRoomAudioChange`, `music.roomAudio`, `music.setAntsyMusicState`, `music.setArenaMusicState`, `music.setChaseMusicState`, `music.setDreadMusicState`, `music.setParlourMusicState`, `music.setRaceMusicState`, `music.setWorkshopMusicState`, `music.startAntsyMusic`, `music.startArenaMusic`, `music.startChaseMusic`, `music.startDreadMusic`, `music.startParlourMusic`, `music.startRaceMusic`, `music.startWorkshopMusic`, `music.stopAntsyMusic`, `music.stopArenaMusic`, `music.stopChaseMusic`, `music.stopDreadMusic`, `music.stopParlourMusic`, `music.stopRaceMusic`, `music.stopWorkshopMusic`
- consts: `music.ANTSY_SCORE`
- types: `music.ChaseStage`

### `bots.` (16 members)

- functions: `bots.botFillCount`, `bots.botId`, `bots.botName`, `bots.fillSeats`, `bots.isBot`, `bots.makeBots`, `bots.makeBotSeats`, `bots.resolveBotFill`
- consts: `bots.BOT_COLORS`, `bots.BOT_PREFIX`, `bots.DEFAULT_SOLO_FILL`, `bots.hasBots`, `bots.isPresent`
- types: `bots.BotFillOptions`, `bots.BotFillPlan`, `bots.BotSeatOptions`

## The server

| symbol | kind | what it is |
|---|---|---|
| `queueSfx` | function | Ask for a sound from tick() or onInput(): queues onto state._sfxEvents, which the runtime drains each tick. — `(state: unknown, name: string, audience?: SfxAudience, volume?: number \| undefined) => void` |
| `SfxAudience` | type | Who feels the haptic that rides with a sound ("all", "controllers", or one player id) — the TV always hears it. |

## The phone

| symbol | kind | what it is |
|---|---|---|
| `TapButton` | const | Release-to-fire button that commits exactly once on touch or mouse; the tap primitive. — `ForwardRefExoticComponent<TapButtonProps & RefAttributes<HTMLButtonElement>>` |
| `TapButtonProps` | type | TapButton's props: onTap, children, className, style, disabled, aria-label, type. |
| `BidPad` | function | A chip-and-stepper bid pad with a confirm button, for auctions and bets. — `({ min, max, seq, accent, confirmLabel, onConfirm, secondary, note, unit, chips }: { min: number; max: numb…` |
| `PlayingCard` | function | A playing card face for the phone, with face-down, highlighted and dimmed states. — `({ card, faceDown, size, highlighted, dimmed, accent, tint }: { card?: string \| Card \| null \| undefined; fa…` |
| `Onboarding` | function | The skippable, illustrated practice round shown before a game starts. — `({ theme, roleLabel, title, steps, onStart, startLabel }: Props) => Element` |
| `OnboardingStep` | type | One practice-round step: title, body, an icon/sprite/art, and an optional try-it demo. |
| `OnboardingTheme` | type | The practice round's palette: accent, bg, panel, ink, dim, fonts. |
| `CoachHint` | function | A small dismissible pulse that points at a live control the first time a player sees it. — `({ text, accent, show, placement }: { text: string; accent?: string \| undefined; show?: boolean \| undefined…` |
| `TutorialReadyBanner` | function | The platform's pre-game Ready banner, rendered by the runtime over the game's controls. — `({ theme, label, buttonLabel, onReady, topOffsetPx, }: { theme: TutorialReadyBannerTheme; label?: string \| …` |
| `TutorialReadyBannerTheme` | type | The Ready banner's palette. |
| `ReadyGateContext` | const | Context the runtime provides so a practice round's Start/Skip signals readiness. — `Context<(() => void) \| null>` |
| `DrawCanvas` | function | A freehand drawing surface with brushes, undo, clear and submit; emits DrawStroke[]. — `({ onSubmit, disabled, submitLabel, timer }: DrawCanvasProps) => Element` |
| `StrokeView` | function | Read-only replay of a DrawStroke[] on a square canvas, with an optional 0..1 progress for a reveal. — `({ strokes, progress, className, style }: StrokeViewProps) => Element` |
| `phonekit` | namespace | The phone's chrome kit: FONT_DISPLAY, FONT_MONO, SAFE_BOTTOM, PieceIcon, CaretLeft. |
| `VirtualJoystick` | function | A thumb joystick that reports a normalised -1..1 vector, with the wire throttle built in. — `({ onMove, color, size, catchRadius, region, rest, label, zIndex, }: VirtualJoystickProps) => Element` |
| `JoystickOutput` | type | What the joystick reports: x, y in -1..1, magnitude, angle, active. |
| `createMoveThrottle` | function | The leading+trailing throttle the joystick uses to be the wire's rate limiter. — `(emit: (out: JoystickOutput) => void, rateMs?: number) => MoveThrottle` |
| `MoveThrottle` | type | A move throttle's handle: push a sample, flush, cancel. |
| `PAUSE_RESERVED_PX` | const | Width in px of the top-right zone the platform's pause button occupies; keep controls out of it. — `60` |
| `PAUSE_RESERVED_CSS` | const | The same gutter as a CSS length that tracks the right safe-area inset. — `"calc(60px + max(0px, env(safe-area-inset-right, 0px) - 10px))"` |
| `PausedOverlay` | function | The platform's pause screen for a phone, themed from the game's own accent; render it when props.paused. — `({ theme, scrim, blur, zIndex, title, subtitle, art, }: PausedOverlayProps) => Element` |
| `PausedOverlayTheme` | type | The pause screen's palette: accent (required), accent2, ink, dim. |

### `phonekit.` (5 members)

- functions: `phonekit.CaretLeft`, `phonekit.PieceIcon`
- consts: `phonekit.FONT_DISPLAY`, `phonekit.FONT_MONO`, `phonekit.SAFE_BOTTOM`

## The TV

| symbol | kind | what it is |
|---|---|---|
| `PlayingCardTV` | function | A playing card face for the TV, with a flip delay for dealing animations. — `({ card, faceDown, size, highlighted, dimmed, flipDelayMs, accent, tint }: { card?: string \| Card \| null \| …` |
| `safeRender` | function | Wrap a canvas frame so a throw cannot kill the RAF loop; a persistent failure paints a tombstone. — `(tag: string, fn: () => void, ctx?: CanvasRenderingContext2D \| null \| undefined) => void` |
| `renderFailureCount` | function | How many frames in a row a tagged renderer has failed; 0 when healthy. — `(tag: string) => number` |
| `useNarration` | function | Speak a line on the TV when its key changes, in the room's narration voice and volume. — `(text: string \| null, key: string, opts?: { muted?: boolean \| undefined; rate?: number \| undefined; pitch?:…` |
| `createFx` | function | A particle layer for a canvas TV: burst, confetti, ring, tracer; update(dt) and draw(ctx) each frame. — `(opts?: { max?: number \| undefined; } \| undefined) => FxApi` |
| `FxApi` | type | The particle layer's handle: burst, confetti, ring, tracer, update, draw, clear. |
| `FxCanvas` | const | A mounted particle overlay for a DOM or SVG TV; owns its own rAF loop and idles at zero cost. — `ForwardRefExoticComponent<{ className?: string \| undefined; style?: CSSProperties \| undefined; zIndex?: num…` |
| `FxHandle` | type | FxCanvas's ref handle: `{ fx }`, the same FxApi a canvas game drives by hand. |
| `tvkit` | namespace | The TV's typography and material kit: display/Num/Clock/Kicker, surface, TopRail, the font tokens. |
| `hidpi` | namespace | The resolution kit: fitCanvas, resolutionScale, MAX_DPR — a canvas TV drawn at real device pixels. |

### `tvkit.` (17 members)

- functions: `tvkit.answerFontSize`, `tvkit.clampText`, `tvkit.Clock`, `tvkit.contactShadow`, `tvkit.Cross`, `tvkit.display`, `tvkit.Kicker`, `tvkit.Mark`, `tvkit.Mark2`, `tvkit.Num`, `tvkit.surface`, `tvkit.Tick`, `tvkit.TopRail`, `tvkit.useMotion`
- consts: `tvkit.FONT_DISPLAY`, `tvkit.FONT_MONO`, `tvkit.FONT_UI`

### `hidpi.` (5 members)

- functions: `hidpi.baseTransform`, `hidpi.fitCanvas`, `hidpi.resetTo`, `hidpi.resolutionScale`
- consts: `hidpi.MAX_DPR`
<!-- END GENERATED -->

## 13. Before `tnf submit` — the checklist an agent should not need

1. The directory is `games/<id>/` or `lab/games/<id>/` (§1) and nothing
   outside it was touched; `manifest.id` equals the directory name;
   `howToPlay` and `tutorial` set.
2. `server.ts` uses `ctx.rng` and `ctx.now`, imports only from the SDK and
   itself, and returns JSON-serialisable state under 256 KB.
3. `hiddenInfo` is `false`, or it is `true` and BOTH `getPlayerState` and
   `getSpectatorState` are defined (§2). Either is fine; one of the two
   projections alone is a game no room will start.
4. Every phone control is inside the caps in §6.
5. The game reaches `game:end` inside §8's 120-second bound with bots
   pressing every declared control — a real-time game has a clock, not only
   a win condition.
6. `checks/` drives the game with inputs and asserts the state changed —
   a harness that never plays passes forever. Six assertions satisfies that
   sentence and catches nothing; aim for dozens, and cover a whole round.
7. `npx totallynotfun check` green, `npx totallynotfun play` reached results
   with two phones.