# OGS for game developers

> How to make a web game OGS-compatible: the OGS app casts once, a TV launcher frames each game's TV page, phones play its phone page, and the game learns who is playing through profile-kit.

<!-- https://ogs-docs.pages.dev/index.md -->

# Build a game for OGS

OGS (Open Game System) puts web games on the living-room TV. A grown-up casts **once** from the OGS
app; after that the TV shows one page all evening, the **TV launcher**, and every game plays inside
it. Phones and iPads join the couch and play each game's phone page. Your game stays an ordinary web
game: it gets a few `postMessage`s and a small library, and it keeps working in a plain browser.

> **Building with a coding agent?** Point it at [the Quickstart](https://ogs-docs.pages.dev/quickstart.md) or at
> `https://ogs-docs.pages.dev/llms.txt`. Every page here is also plain Markdown: add `.md` to its URL.

## How an evening works

1. **Cast once.** The host opens the OGS app and casts to the TV (Chromecast, or any browser on the
   TV). The TV shows the launcher and a 6-character **TV code**.
2. **Phones join the couch.** Everyone else joins with the TV code. Each person has an OGS profile:
   a name and an avatar.
3. **The launcher frames your game.** When someone picks your game, the launcher loads your **TV page**
   in an iframe and tells it who is on the couch. Swapping games never recasts.
4. **Phones open your phone page.** The app opens your game's `startUrl` in a WebView. Your page asks
   profile-kit who is playing and skips its own name form.
5. **Home parks your game.** When the couch goes Home or switches games, the launcher keeps your frame
   loaded but parked, and tells you to go silent. Continue brings the same frame back instantly.

## Your two pages

| Surface | Where it runs | What it does with OGS |
|---|---|---|
| **TV page** | In an iframe filling the TV launcher (test it at 1280×720 and 1920×1080) | Hears `ogs:start` (who's on the couch, a game token), `ogs:suspend` / `ogs:resume` (parked or back); may report the sitting's label |
| **Phone page** (`startUrl`) | In the OGS app's WebView on phones and iPads | Reads the OGS profile (name, avatar, game token) through the app bridge; reports the sitting's label |

A game with one static TV page lists it as `tvUrl` in its manifest. A room-based game (each room has
its own TV URL) declares the room's TV page from the phone page at runtime. Either way the game never
casts: OGS does.

## What your game gets

- **Who's playing.** On the phone: the player's OGS name, avatar and a **game token**. On the TV: the
  whole couch (`players`) and a game token for the session. No sign-up, no name form.
- **Verified identity.** Game tokens are ES256 JWTs signed by OGS for your game only (`aud` = your
  appId). Your server checks them with one call, `verifyOgsToken`.
- **Sitting labels.** Report "Mission 6" or "Room KQTP" and the OGS app shows it in Playing, so two
  sittings of your game read apart.
- **Pause and resume.** A clear signal when the TV parks your game and when it comes back, so you can
  stop the music and keep state.
- **Casting handled.** No cast SDK, no cast button, no receiver app, no join codes on the TV.
- **Several couches in one room** (optional, `multiCouch`): households in different homes play one
  room of your game.

## What OGS asks of you

The short version of [the rules](https://ogs-docs.pages.dev/rules.md):

- No cast button and no room code or join QR on an OGS TV.
- Nothing covers the TV's focal area; stay inside the safe area.
- Silent while parked.
- Still playable in a plain browser, where every profile-kit call returns `null` or does nothing.

## Where to go next

- [Quickstart for agents](https://ogs-docs.pages.dev/quickstart.md): the step-by-step checklist.
- [The game contract](https://ogs-docs.pages.dev/contract.md): the single source of truth.
- [profile-kit reference](https://ogs-docs.pages.dev/profile-kit.md) and [Messages and manifest](https://ogs-docs.pages.dev/messages.md): exact APIs.
- [Testing your game](https://ogs-docs.pages.dev/testing.md), [Art kit and catalogue](https://ogs-docs.pages.dev/art-and-catalogue.md).

---

<!-- https://ogs-docs.pages.dev/quickstart.md -->

# Quickstart for agents

A checklist a coding agent (Claude Code, Codex, Cursor…) can follow end to end to make a web game
OGS-compatible, new or existing. Each step says what to change and how to know it is done. Work
test-first and commit after each green step.

## Prompt for your agent

Copy this into your agent, in the game's repository:

```text
Make this web game OGS-compatible. Follow the step-by-step checklist at
https://ogs-docs.pages.dev/quickstart.md and treat https://ogs-docs.pages.dev/contract.md as the
contract (if the two disagree, the contract wins). APIs: https://ogs-docs.pages.dev/profile-kit.md and
https://ogs-docs.pages.dev/messages.md. Everything in one file: https://ogs-docs.pages.dev/llms-full.txt

Rules: the game never casts and shows no cast button; on an OGS TV it shows no room code, join QR or
"join at" URL; nothing covers the TV's focal area; the TV page goes silent on ogs:suspend; the game
still works in a plain browser. Work test-first: write the seam tests from
https://ogs-docs.pages.dev/testing.md before the code they cover. Tell me which steps are done,
which tests prove each one, and anything you could not verify.
```

## Before you start

You need:

- A web game with a page for the TV and a page for phones. One page can be both if it changes layout,
  but most OGS games have a separate TV page (big shared screen) and phone page (controller).
- Node 20+ and pnpm. A server is optional; you need one only to trust names and seats (step 6).
- A local clone of the OGS repo for profile-kit (step 1):
  `git clone https://github.com/open-game-system/open-game-system`.

Pick an `appId` now: lowercase letters, digits and hyphens (`[a-z0-9-]+`), for example `space-bakery`.
It names your game everywhere: the catalogue, the art folder and the `aud` of your game tokens.

## The checklist

### 1. Install profile-kit

profile-kit is not on npm yet. Build it in the OGS repo and pack a tarball into your game (it bundles
`ogs-protocol` and the app bridge; it needs `zod` and, for the hooks, `react`):

```bash
cd open-game-system
pnpm install
pnpm --filter @open-game-system/profile-kit build
cd packages/profile-kit && pnpm pack --pack-destination <your-game>/vendor
```

In your game's `package.json`:

```json
"dependencies": {
  "@open-game-system/profile-kit": "file:vendor/open-game-system-profile-kit-0.1.0.tgz"
}
```

Then `pnpm install`. After re-packing a newer build under the same file name, use
`pnpm install --force`.

**Done when** `import { onOgsPause } from "@open-game-system/profile-kit"` type-checks.

### 2. Make the TV page frameable

The launcher loads your TV page in an iframe with `allow="autoplay; fullscreen"`.

- Do not send `X-Frame-Options: DENY`/`SAMEORIGIN`, and no `Content-Security-Policy: frame-ancestors`
  that excludes the launcher.
- Start without a tap: there is no pointer on a TV. Start audio and animation on load.
- Hide any full-screen button when framed (`window.parent !== window`); the launcher already fills the TV.

**Done when** a plain HTML page with `<iframe src="YOUR_TV_URL">` shows your TV page playing.

### 3. TV page: hear the launcher

Create the session source at module load of the TV entry (the launcher posts `ogs:start` as soon as
the frame loads; profile-kit says `ogs:ready` so a missed start is re-sent).

```ts
// tv entry (module scope)
import { getOgsSessionSource, onOgsPause } from "@open-game-system/profile-kit";

getOgsSessionSource(); // start listening now
onOgsPause((paused) => audio.setPaused(paused)); // ogs:suspend → true, ogs:resume → false
```

In React, read the couch with the hook:

```tsx
import { useOgsSession } from "@open-game-system/profile-kit/react";

function TvPlayers() {
  const session = useOgsSession();
  if (session === undefined) return null; // waiting for the launcher (≤ 300 ms)
  if (session === null) return <JoinCodeAndQr />; // not on an OGS TV: keep your own join UI
  return <Seats players={session.players} />; // { id, handle, name, avatar }[]
}
```

- `ogs:start` → `session` with `players`, `token` (a game token, or `""`), `instanceId`, `mode`
  (`"continue"` or `"new"`), and `room` for multi-couch games.
- `ogs:suspend` → `onOgsPause(true)`: **go silent**. Suspend your `AudioContext`, pause every
  `<audio>`/`<video>`, stop timers that make sound. Keep the game state; the frame stays loaded.
- `ogs:resume` → `onOgsPause(false)`: resume only what was playing before.

A safe audio gate (suspends the shared context on pause, resumes it on Continue only if it was
running, and keeps a sound unlocked during the pause silent):

```ts
export function createAudioPause(getCtx: () => AudioContext | null) {
  let paused = false;
  let parked: AudioContext | null = null;
  return {
    setPaused(next: boolean) {
      if (next === paused) return;
      paused = next;
      if (paused) {
        const ctx = getCtx();
        if (ctx?.state === "running") { parked = ctx; void ctx.suspend(); }
        return;
      }
      const ctx = parked;
      parked = null;
      if (ctx?.state === "suspended") void ctx.resume();
    },
    paused: () => paused,
  };
}
```

**Done when** the seam test in [Testing](https://ogs-docs.pages.dev/testing.md#1-the-tv-page-in-a-stand-in-launcher) passes:
every `AudioContext` is `suspended` after `ogs:suspend` and `running` after `ogs:resume`, and the TV
names the players from `ogs:start`.

### 4. TV page: no join UI inside OGS

When `useOgsSession()` (or `getOgsSessionSource().getSnapshot()`) is a session, hide your room code,
join QR, "join at" URL and cast button. OGS draws its own TV code. When it is `null` (a plain browser),
keep them: the game must still be joinable on its own.

**Done when** the framed TV page shows no code or QR after `ogs:start`, and the unframed page still does.

### 5. Phone page: use the OGS profile

```tsx
import { useOgsProfile } from "@open-game-system/profile-kit/react";

function Join() {
  const profile = useOgsProfile();
  if (profile === undefined) return <p>Joining…</p>; // asking the app (≤ 300 ms, ≤ 5 s while it fetches)
  if (profile === null) return <NameForm />; // plain browser: your own form, unchanged
  // In the OGS app: join at once under the OGS name and avatar, and send the token to your server.
  return <AutoJoin name={profile.name} avatar={profile.avatar} token={profile.token} />;
}
```

- Join **once** per seat. The app refreshes the token before it expires; a new token must not join again.
- Hide your join code entry: OGS puts the phone in the right game already.
- No React? `getOgsProfileSource()` is the same store: `getSnapshot()` and `subscribe(listener)`.

**Done when** in a fake WebView (see [Testing](https://ogs-docs.pages.dev/testing.md#2-the-phone-page-in-a-fake-webview)) the
page joins without a form under the OGS name, and in a plain browser the form is unchanged.

### 6. Server: verify game tokens

Anything that matters (a seat, a score, a name other players see) must come from a verified token.

```ts
import { verifyOgsToken } from "@open-game-system/profile-kit/server";

const claims = await verifyOgsToken(token, { appId: "space-bakery", jwksUrl: env.OGS_JWKS_URL });
if (!claims) return joinAsGuest(); // bad signature, other game, expired, or no token: the plain-browser path
seat({ id: claims.sub, name: claims.name, avatar: claims.avatar, couch: claims.couch?.sid });
```

- It checks the ES256 signature against OGS's JWKS, `aud === appId`, and expiry; anything else is `null`.
- Make `jwksUrl` configuration (a Worker var such as `OGS_JWKS_URL`), so seam tests can serve a local
  key set. Point it at the OGS API's `/.well-known/jwks.json`.
- In the page, `readGameToken(token)` only decodes (for display). Never trust it for anything else.

**Done when** a test signs a token with a local key and your server seats that player, and rejects a
token for another `appId` and an expired one.

### 7. Report the sitting's label

```ts
import { reportOgsSitting } from "@open-game-system/profile-kit";

reportOgsSitting({ instanceId, appId: "space-bakery", status: "active", title: "Mission 6" });
```

Call it whenever the label changes, from the TV page, the phone page, or both: in the app's WebView it
goes over the app bridge, on the TV to the launcher, in a plain browser nowhere. On the TV use the
`instanceId` from `ogs:start`. `status` is one of `lobby`, `active`, `suspended`, `waiting`,
`completed`, `expired`.

**Done when** the TV seam test receives an `ogs:instance` message with your title.

### 8. Room games: declare the TV page from the phone

Skip this if your manifest has a static `tvUrl`. If each room has its own TV URL, the host's phone
page declares it while inside OGS (cast-kit, packed from the OGS repo like profile-kit):

```tsx
import { isOGSCastAvailable } from "@open-game-system/cast-kit-core";
import { CastProvider, useCastViewUrl } from "@open-game-system/cast-kit-react";

function DeclareTv({ tvUrl }: { tvUrl: string }) {
  useCastViewUrl(tvUrl); // the app forwards it to the launcher, which frames it
  return null;
}

export function HostPanel({ tvUrl }: { tvUrl: string }) {
  const inOgs = useMemo(() => isOGSCastAvailable(), []);
  return inOgs ? <CastProvider><DeclareTv tvUrl={tvUrl} /></CastProvider> : <OwnTvLinkAndQr />;
}
```

No `<CastButton>`: the app ignores a game's own cast actions.

### 9. Rooms: the couch's phones, and other homes

A game with rooms: call `reportOgsRoom(roomCode)` from the TV page when the room exists, and on the
phone page join `ogsRoomFromUrl(location.href)` instead of making a room when it is not `null`. Every
phone on the couch follows the TV: the one that starts the game makes the room, the others open your
start page with `ogsRoom=<room>` once the TV page reported it (no report, no followers).

Several homes in one room (optional): only if households in different homes should play one room
together. Set `multiCouch: true` in the manifest, join `session.room` instead of creating a room when
`ogs:start` carries one, and group players by `claims.couch.sid`. Details:
[the contract, §7](https://ogs-docs.pages.dev/contract.md#7-several-couches-one-room-multicouch).

### 10. Art kit and manifest

Make the four images and write the manifest: see [Art kit and catalogue](https://ogs-docs.pages.dev/art-and-catalogue.md). The
manifest's fields are in [Messages and manifest](https://ogs-docs.pages.dev/messages.md#manifest).

### 11. Test it

Write the seam tests from [Testing your game](https://ogs-docs.pages.dev/testing.md): the TV page in a stand-in launcher, the
phone page in a fake WebView, no full-screen button when framed, and the plain-browser check. Then run
the whole game end to end in a plain browser once more.

### 12. Submit to the catalogue

Open a pull request to the OGS repository with your manifest and art kit:
[Art kit and catalogue](https://ogs-docs.pages.dev/art-and-catalogue.md#submit-to-the-catalogue).

## Done when

- The seam tests pass, and the game plays end to end in a plain browser.
- In the OGS app: no name form on phones, the TV shows the couch's names, Home silences the TV,
  Continue brings it back with sound, and Playing shows your sitting label.
- Nothing on the OGS TV shows a cast button, a room code or a join QR.

---

<!-- https://ogs-docs.pages.dev/contract.md -->

# The OGS game contract


**Status:** current (October 2026). This page is the single source of truth for what a web game does to
run in OGS. When code and this page disagree, the schemas in `packages/ogs-protocol/src/` win and this
page is fixed. Decision: [ADR 2026-10-04 OGS game contract](https://github.com/open-game-system/open-game-system/blob/main/docs/adrs/2026-10-04-ogs-game-contract.md).

It replaces the March 2026 "OGS Specification v1" (account linking, certification, per-game cast
sessions), which described a model OGS no longer uses. That text is in git history
(`git show c616c6b5:docs/specification.md`).

## The model in one paragraph

A grown-up casts **once** from the OGS app. The Chromecast (or any browser on the TV) shows one page all
evening: the **TV launcher** (`apps/tv`). The launcher frames each game's **TV page** in an iframe and
swaps games without recasting. Phones and iPads play the game's **phone page** inside the app's
WebView. People join the couch with the **TV code** (a 6-character code per couch session), not a game's
room code. A game never casts, never shows a cast button, and still works in a plain browser.

Product spec: [OGS app v3](https://github.com/open-game-system/open-game-system/blob/main/docs/product-specs/ogs-app-v3.html). TV platforms (direct launcher vs WebRTC
stream): [ADR 2026-10-04 TV platforms](https://github.com/open-game-system/open-game-system/blob/main/docs/adrs/2026-10-04-tv-platforms.md).

## 1. Manifest and catalogue

A game is config, not code: one `Manifest` (`ManifestSchema` in
`packages/ogs-protocol/src/manifest.ts`). The catalogue is the list of manifests in
`services/api/src/catalogue.ts` (`CATALOGUE`), served at `GET /api/v1/catalogue`; the app's Library
reads it from there. `apps/mobile/services/game-directory.ts` is the old static list: don't add games to it.

| Field | Meaning |
|---|---|
| `appId` | `[a-z0-9-]+`; also the `aud` of every game token for this game |
| `name`, `tagline` | Shown in Library and on the TV |
| `shape` | `couch` · `live` · `async` |
| `tv` | `none` (phone only) · `optional` · `required` |
| `startUrl` | The phone page (also the controller when the TV shows the TV page) |
| `tvUrl` | Optional static TV page. Room-based games omit it and send the room's TV URL at runtime (§3) |
| `roles` | `{ id, label, audience: grownup \| kid \| little }[]` |
| `art` | See the art kit below |
| `shop` | `ages`, `minutes: [min, max]`, `players` |
| `instanceTtlMs` | How long a silent sitting lives (default 7 days) |
| `multiCouch` | `true`: several couches may join one room (§7). Default `false` |

`catalogueFor(env)` swaps in local `startUrl`s from `CATALOGUE_START_URLS` (JSON `{ appId: url }`) for
dev stacks and e2e runs; it never adds games.

### Art kit

Every catalogue game ships four images under `apps/tv/public/art/<appId>/`, referenced from `art`:

| Field | Image |
|---|---|
| `icon` | 1:1 icon |
| `cover` | 2:3 cover **with the title** |
| `logo` | Transparent logo |
| `heroClean` | 16:9 hero with **no text and no HUD** |

`tile` (required) and `hero` are older captured screenshots; `safe` (`scale`, `ox`, `oy`) crops their HUD
when no clean art exists. `services/api/test/catalogue.test.ts` fails if any catalogue game lacks the kit
or a file is missing. Contact sheet: `apps/tv/public/art/KIT-SHEET.jpg`. No faces on objects; each game
keeps its own look.

`art.theme` (a launcher music loop per game) is not on this branch yet; add it here when it merges.

## 2. The TV page, framed by the launcher

Messages are `LauncherToGameSchema` and `GameToLauncherSchema` in
`packages/ogs-protocol/src/frame.ts`, sent with `postMessage`. Every message is optional for the game:
a game that answers nothing still runs.

| Direction | Message | Payload | When |
|---|---|---|---|
| launcher → game | `ogs:start` | `instanceId`, `mode` (`continue` \| `new`), `roster`, `token`, `players?`, `room?` (§7) | On the frame's load, and again whenever the game says `ogs:ready` |
| game → launcher | `ogs:ready` | none | The page started listening (possibly after load); the launcher re-sends `ogs:start` for the current sitting |
| launcher → game | `ogs:suspend` | none | Home, or a swap to another game: the frame is **parked**, still loaded |
| launcher → game | `ogs:resume` | none | Continue of the parked sitting: the same frame comes back, no reload |
| game → launcher | `ogs:resume-point` | `label` | The sitting's label ("Mission 6") |
| game → launcher | `ogs:room` | `room` | The room the TV page shows. Every room-based game (no static `tvUrl`): the couch's other phones follow into this room (§3); `multiCouch` games also let other couches join it |
| game → launcher | `ogs:instance` | `report` (`InstanceReportSchema`) | Same purpose; the launcher uses `report.title` as the label |

- `token` is a **game token** for this game and this couch session (`aud` = appId, `sid`, `players`), or
  `""` when OGS could not sign one. The launcher's own token never reaches a game's origin.
- `players` is who's on the couch: `{ id, handle, name, avatar }[]` (`GamePlayerSchema`).
- The launcher accepts game messages only from the origin of the game's TV URL
  (`readFrameMessage` in `apps/tv/src/launcher/frames.ts`), and frames with `allow="autoplay; fullscreen"`.
  The TV page must allow being framed (no `X-Frame-Options: DENY` or a `frame-ancestors` that excludes
  the launcher).
- The launcher keeps one active frame and one parked frame (`nextFrames`); a third game unloads the
  oldest parked one.
- If a started game sends no TV page within 20 s (`VIEW_TIMEOUT_MS`), the TV says it didn't open.

With profile-kit (§4) a game doesn't post these by hand:

| Need | profile-kit |
|---|---|
| Who's on the couch, the session's game token | `useOgsSession()` (react) or `getOgsSessionSource()`: `undefined` while waiting, `null` when not framed by OGS (300 ms), else `{ players, token, instanceId, mode }`. Says `ogs:ready` itself |
| Go silent when parked | `onOgsPause((paused) => …)`: `true` on `ogs:suspend`, `false` on `ogs:resume`; never fires in a plain browser |
| The sitting's label | `reportOgsSitting({ instanceId, appId, status, title })`: `ogs:instance` to the launcher on the TV, the app bridge in the WebView, nothing in a plain browser |
| Rooms (§7) | `reportOgsRoom(room)` (TV page: `ogs:room`); `useOgsSession()` gives `room` when this couch joins another's; `ogsRoomFromUrl(location.href)` on the phone page (a second device of this couch, or another couch); `verifyOgsToken` returns `couch: { sid, label }` |

**Parked means silent.** A parked frame stays loaded so Continue is instant, so its audio keeps
playing unless the game stops it. Suspend the `AudioContext` and pause media on `onOgsPause(true)`; resume
on `false`, and only what was playing before. Pattern: `createAudioPause` in
`~/src/night-flight-owls/src/client/audio-pause.ts`.

## 3. Phones: the game page in the app's WebView

- The app opens `startUrl` in a WebView with the app bridge (`@open-game-system/app-bridge-*`).
- **Every couch phone follows the TV.** The phone that starts a game hosts it (its start page makes
  the room). Every other phone on the couch opens the same game when the TV starts it, and goes back
  to the remote on Home. For a room-based game (no static `tvUrl`) it waits until the TV page reports
  its room (`ogs:room`, §2) and opens `startUrl` with `ogsRoom=<room>` added to the query: the phone
  page must join that room (`ogsRoomFromUrl(location.href)`), never make a new one. A game that never
  reports its room gets no followers (their start page would make an empty room). Kids' iPads follow
  the same way (their roster seat when a roster was sent, else as a player). A following phone that
  swipes back steps out to the remote; the TV keeps playing.
- **Who's playing:** `useOgsProfile()` (`@open-game-system/profile-kit/react`) gives
  `{ id, handle, name, avatar, token }` from the app's `profile` bridge store (refreshed before the token
  expires). `undefined` while asking (up to 300 ms for the store, 5 s while the app says `asking`),
  `null` in a plain browser. With a profile, skip the game's name form and join under the OGS name and
  avatar; with `null`, keep the form.
- **The TV page of a room game:** the phone page declares it with cast-kit-react
  `useCastViewUrl(url)`. While cast through OGS the app forwards it to the couch session as `game.view`
  (`apps/mobile/services/game-cast-route.ts`) for the launcher to frame (only the host phone's page
  counts: a following phone's or iPad's `game.view` is ignored), and drops the game's
  `START_CASTING` / `STOP_CASTING` / `SHOW_CAST_PICKER`. A game with a static `tvUrl` needs nothing.
  `isOGSCastAvailable()` (cast-kit-core) tells the page it runs inside the OGS app.
- **Sitting labels:** `reportOgsSitting(...)` goes through the app's `ogs` bridge store as
  `INSTANCE_REPORT`, so two sittings of one game read apart in Playing. When nothing is reported, OGS
  names a sitting by when it started (`sittingName` in `packages/ogs-protocol/src/sitting.ts`).
  While cast, the report labels the couch session's live sitting of the game (the app files it under
  that sitting's id, as the launcher does with the TV page's `ogs:instance`), so the phone page and the
  TV page may both report: one start is one sitting. The game's own `instanceId` is used only when
  the phone plays alone.

## 4. Server: verify the token

- Game tokens are **ES256** JWTs signed by OGS, `aud` = the game's appId, valid 1 hour
  (`GameTokenSchema`, `GAME_TOKEN_TTL_S` in `packages/ogs-protocol/src/game-token.ts`). Claims: `iss`,
  `aud`, `sub` (profile id; the host's for a TV token), `handle`, `name`, `avatar`, `iat`, `exp`, plus
  `sid` and `players` on TV tokens, and `couch` (`{ sid, label }`) on every token issued for a couch (§7). Never friends, other games, device ids, push tokens or age.
- Public keys: `GET /.well-known/jwks.json` on the OGS API.
- Issued by `POST /api/v1/games/:appId/token` (the app, for a phone) and
  `POST /api/v1/sessions/:sid/game-token` (the launcher, for the TV).
- On the game's server: `verifyOgsToken(token, { appId })` from `@open-game-system/profile-kit/server`
  checks signature, `aud` and expiry and returns the claims or `null`. `jwksUrl` overrides the default
  (`OGS_JWKS_URL`, `https://api.opengame.org/.well-known/jwks.json`, a custom domain not yet confirmed
  on 2026-10-04); Rocket Crew sets it per environment as a Worker var (`OGS_JWKS_URL` in its
  `wrangler.toml`), which also lets seam tests use a local key set. Anything that matters (seats, scores) uses the verified
  claims; `readGameToken` in the page only decodes, for display.

## 5. Rules

1. **No cast button, no room code and no join UI on an OGS TV.** OGS casts; people join with the TV code
   or the launcher's QR (§8, planned). Outside OGS the game may keep its own room code, QR and TV link.
2. **Nothing covers the TV's focal area.** HUD and toasts stay at the edges.
3. **Still playable in a plain browser.** Every profile-kit call degrades to `null` / no-op there.
4. **Silent while parked** (§2).
5. **The game never sees the app's or the launcher's own token**, only game tokens for itself.

## 6. How to test it

Self-contained versions of these tests, for games outside this org: [Testing your game](https://ogs-docs.pages.dev/testing.md).

- **TV page:** frame it from a tiny parent page, post the launcher messages to the iframe and assert on
  the page. Examples (Playwright + vitest seam tests):
  - `~/src/night-flight-owls/e2e/ogs-pause.seam.test.ts` and `~/src/rocket-crew/e2e/ogs-pause.seam.test.ts`:
    `ogs:suspend` suspends every `AudioContext`, `ogs:resume` resumes it.
  - Do the same for `ogs:start` (players named on the TV) and for the `ogs:instance` the page posts back.
- **Phone page:** `~/src/rocket-crew/e2e/ogs-bridge.seam.test.ts` fakes the app's WebView bridge and signs
  game tokens with a local JWKS (`--var OGS_JWKS_URL:…`).
- **OGS side:** `packages/profile-kit/src/*.test.ts`, `apps/tv/src/launcher/frames.test.ts`,
  `services/api/test/catalogue.test.ts`; cross-surface suites in [testing/e2e.md](https://github.com/open-game-system/open-game-system/blob/main/docs/testing/e2e.md).

## 7. Several couches, one room (`multiCouch`)

Each living room keeps its own couch session, TV launcher and phones. Several couches can play one
**room** of a game: the game makes the room, the other couches join it, and the game groups players by
couch. Decision: [ADR 2026-10-05 couches join the game's room](https://github.com/open-game-system/open-game-system/blob/main/docs/adrs/2026-10-05-couches-join-the-games-room.md).
Acceptance: [multi-couch.feature](https://github.com/open-game-system/open-game-system/blob/main/docs/acceptance/2026-10-05-multi-couch.feature).

| Piece | Contract |
|---|---|
| Manifest | `multiCouch: true` (default `false`): the game accepts players from several couches in one room. OGS offers Invite and Join with your couch only for these games. |
| Room id | The game's own room code (`[A-Za-z0-9_-]{1,64}`, e.g. Night Flight's `KQTP`). OGS never makes one. |
| Game → launcher | `ogs:room` `{ room }`: the TV page says which room it shows (on create and whenever it changes). The launcher forwards it to the couch session as `game.room`; the sitting keeps it, the couch's other phones follow into it (§3), and friends' presence shows it. Every room-based game sends it, not only `multiCouch` ones. profile-kit: `reportOgsRoom(room)`. |
| Couch session | `game.start` takes `room?`. Starting a game with a room opens (or resumes) this couch's sitting **in that room**; without one the game makes its own as before. `current.room` and each paused sitting's `room` keep it, so Continue goes back into the same room. |
| Launcher → game | `ogs:start` carries `room` when the sitting names one: join that room, don't create one. |
| Phone page | When the sitting names a room, the app opens `startUrl` with `ogsRoom=<room>` added to its query (profile-kit: `ogsRoomFromUrl(location.href)`), so the host phone joins the room too. The same parameter brings this couch's other phones into the room (§3, "Every couch phone follows the TV"), for every room-based game, `multiCouch` or not. |
| Game token | Every token issued for a couch (the TV's, and a phone's when it asks with its session id) carries `couch: { sid, label }`: the couch session id and its label (the host's name). Players with the same `couch.sid` sit on the same couch. A token without `couch` is a phone with no couch (plain WebView): the game seats it with its TV's couch, or alone. |
| Leaving | Home on one TV parks only that couch's frame (`ogs:suspend`); the game marks that couch away and keeps the turn order going for the others. `ogs:resume` brings it back in the same room. |

**Invites.** `POST /api/v1/games/:appId/invites` `{ room, to: [profileId…] }` (a phone in a couch
session; only friends; only `multiCouch` games) sends each friend a push ("Jonathan invites you to Night
Flight") and answers the link `https://opengame.org/play/<appId>?room=<room>` (`PLAY_BASE_URL` overrides
the origin). The app opens that link (and `opengame://play/<appId>?room=<room>`): with a TV cast it sends
`game.start { appId, room }`, else it asks to cast first and then starts. opengame.org/play/… is a web page
that opens the app, or says how to get it.

**Join with your couch.** `GET /api/v1/friends/rooms` lists the rooms of `multiCouch` games your friends'
TVs are in: `{ appId, game, room, couches: [{ sessionId, label, host }], joined }`. Playing shows each as
"Jonathan and Sam are playing Night Flight" with **Join with your couch** (the same start as the link).
Presence (`casting`/`playing`) carries the `room` too. Join a friend's cast (sitting on *their* couch) is
unchanged.

## 8. Joining and invites (planned)

**Status: planned, not implemented.** Everything in this section is new and optional; a game that does
none of it keeps running. Product spec: [ogs-join.html](https://github.com/open-game-system/open-game-system/blob/main/docs/product-specs/ogs-join.html). Decision:
[ADR 2026-10-06 the launcher owns joining](https://github.com/open-game-system/open-game-system/blob/main/docs/adrs/2026-10-06-launcher-owns-joining.md). Acceptance:
[join-and-invite.feature](https://github.com/open-game-system/open-game-system/blob/main/docs/acceptance/2026-10-06-join-and-invite.feature).

| Item | Status | Contract |
|---|---|---|
| Games never draw join codes | planned (strengthens rule 1, §5) | On an OGS TV a game shows no room code, join QR, "join at" URL or cast button. The launcher draws the join QR next to the TV code on Home and Getting ready, and the invite card (below). Outside OGS the game may keep its own. |
| `ogs:invite` | planned | game → launcher, no payload. "Show people how to join now" (for example a "waiting for players" state). The launcher shows its invite card in the safe corner for 30 s; repeated messages restart the timer, they do not stack. Ignored from a frame that is not the current game. Equivalent to a couch phone tapping Invite someone. profile-kit: `requestOgsInvite()`, a no-op outside OGS. |
| `inviteCorner` (manifest) | planned | Optional: `top-right` (default), `top-left`, `bottom-right`, `bottom-left`. The corner where the launcher may draw the invite card, at most 220 x 120 CSS px on a 960 x 540 reference with a 24 px margin. The game keeps its focal area and HUD out of that rectangle. |
| `guest` token claim | planned | A guest (joined from the browser, no OGS profile) gets game tokens with `guest: true`, a per-session `sub`, `name` and `avatar`, and no `handle`. Games must not keep a guest's scores across sessions. `GameTokenSchema` gains `guest?: boolean` and `handle` becomes optional only when `guest` is true. |
| Guest phones | planned | A guest plays the game's `startUrl` in a plain browser (no app bridge): `useOgsProfile()` is `null` and the game keeps its name form unless it reads the guest identity the join page supplies as a game token. |
| Transfer link | planned | A game's own site (outside OGS only) may link "Play on TV with OGS" to `https://opengame.org/play/<appId>?room=<room>`, the same link as a friend invite (§7). It is hidden when `isOGSCastAvailable()` or `useOgsSession()` says the game is inside OGS. Without `room` it just starts the game. |

The join QR itself is launcher-level: it encodes `https://opengame.org/join/<code>` (the couch session's
TV code) and is never a game's job. Several households in one room are §7.

**Built (2026-10-06): every couch phone follows the TV** (§3). When the current game (its sitting) or
its room changes, the couch session sends every online phone and kid's iPad a `follow`: the host
`roleId: "host"`, every other one its roster role or `"player"`, with `room` once the TV named it; on
Home or end, the launcher. A phone or iPad that comes online mid-game is sent into it. Nothing else
re-sends it, so one that stepped out stays on the remote. Only the host's game page picks the TV page
(`game.view`). App phones and iPads only; browser guests follow when the web join page exists.

## Acceptance

- [ogs-game-contract.feature](https://github.com/open-game-system/open-game-system/blob/main/docs/acceptance/2026-10-04-ogs-game-contract.feature): the TV page contract
  (start, ready, pause, labels, plain browser)
- [games-know-you.feature](https://github.com/open-game-system/open-game-system/blob/main/docs/acceptance/2026-10-04-games-know-you.feature): game tokens, profile, players
- [cast-first-app.feature](https://github.com/open-game-system/open-game-system/blob/main/docs/acceptance/2026-10-03-cast-first-app.feature): cast once, launcher, swaps,
  instances
- [ogs-profiles.feature](https://github.com/open-game-system/open-game-system/blob/main/docs/acceptance/2026-10-04-ogs-profiles.feature): profiles and joining with the TV code
- [multi-couch.feature](https://github.com/open-game-system/open-game-system/blob/main/docs/acceptance/2026-10-05-multi-couch.feature): several couches in one room (§7)
- [join-and-invite.feature](https://github.com/open-game-system/open-game-system/blob/main/docs/acceptance/2026-10-06-join-and-invite.feature): launcher join QR, web join, phones
  follow the TV, invite card, transfer link (§8, planned)

---

<!-- https://ogs-docs.pages.dev/profile-kit.md -->

# profile-kit reference

`@open-game-system/profile-kit` is how a game learns who is playing and talks to OGS. It has three
entry points: the main one (browser, no framework), `/react` (hooks) and `/server` (token
verification). Every browser call degrades to `null` or a no-op in a plain browser and on the server,
so the same code runs everywhere. Install: [Quickstart, step 1](https://ogs-docs.pages.dev/quickstart.md#1-install-profile-kit).

This page lists **every** export, and a test fails the docs build when the package gains or loses
one. Source: [packages/profile-kit/src](https://github.com/open-game-system/open-game-system/blob/main/packages/profile-kit/src/index.ts).

## `@open-game-system/profile-kit`

### Use these

#### `getOgsProfileSource`

```ts
function getOgsProfileSource(): Source<ProfileSnapshot>
```

The page's OGS profile as an external store (one per page). In the OGS app's WebView it follows the
app's `profile` bridge store, including refreshed tokens. `getSnapshot()` is `undefined` while asking
the app, `null` with no profile (plain browser, server), or an `OgsProfile`. The React hook
`useOgsProfile()` reads it.

#### `getOgsSessionSource`

```ts
function getOgsSessionSource(): Source<SessionSnapshot>
```

The couch session from the TV launcher (one per page). Created on first call: it starts listening
for `ogs:start` and posts `ogs:ready` to the launcher. Call it at module load of the TV entry.
`getSnapshot()` is `undefined` while waiting, `null` when the page is not framed by the launcher
(after 300 ms, or at once when not framed), or an `OgsSession`.

#### `onOgsPause`

```ts
function onOgsPause(onPause: (paused: boolean) => void): () => void
```

Calls `onPause(true)` on `ogs:suspend` (the launcher parked the frame: Home, or another game) and
`onPause(false)` on `ogs:resume` (Continue). Returns a function that stops listening. Never fires in
a plain browser. Only messages from the parent window count.

#### `reportOgsSitting`

```ts
function reportOgsSitting(report: InstanceReportInput): "bridge" | "launcher" | "none"
```

Tells OGS about this sitting; its `title` is the label people see ("Mission 6"). In the OGS app's
WebView it dispatches `INSTANCE_REPORT` to the app's `ogs` bridge store (`"bridge"`); framed by the
launcher it posts `ogs:instance` (`"launcher"`); elsewhere nothing (`"none"`). Throws if the report
fails `InstanceReportSchema`.

#### `reportOgsRoom`

```ts
function reportOgsRoom(room: string): "launcher" | "none"
```

Room-based games: the TV page says which room it shows (`ogs:room`), so the couch's other phones
follow into that room (and, for `multiCouch` games, other couches can join it). Throws if `room` is not
a valid room id (`[A-Za-z0-9_-]{1,64}`). `"none"` when not framed.

#### `ogsRoomFromUrl`

```ts
function ogsRoomFromUrl(url: string): string | null
```

Phone page of a room-based game: the room in the `ogsRoom` query parameter the app adds when this
phone joins a room it didn't make (a second phone of the couch following the TV, or a couch joining
another couch's room). Join it instead of making one. `null` when there is none or it is not a valid
room id. Use `ogsRoomFromUrl(location.href)`.

#### `readGameToken`

```ts
function readGameToken(token: string): GameToken | null
```

Decodes a game token's claims **without verifying** it, for display only. Anything that matters
must use `verifyOgsToken` on your server.

### Types

#### `OgsProfile`

```ts
type OgsProfile = { id: string; handle: string; name: string; avatar: string; token: string }
```

The player on this device: profile id, @handle, name, avatar URL and a game token for this game.

#### `ProfileSnapshot`

```ts
type ProfileSnapshot = OgsProfile | null | undefined
```

`undefined` = still asking the app · `null` = no OGS profile (plain browser) · the profile.

#### `OgsSession`

```ts
interface OgsSession {
  players: GamePlayer[];
  token: string;
  instanceId: string;
  mode: "continue" | "new";
  room?: string;
}
```

What the TV page knows from `ogs:start`: who is on the couch, a game token for the session (`""`
when OGS could not sign one), the sitting and whether it continues, and the room to join
(`multiCouch` games).

#### `SessionSnapshot`

```ts
type SessionSnapshot = OgsSession | null | undefined
```

`undefined` = waiting for the launcher · `null` = not on an OGS TV · the session.

#### `GamePlayer`

```ts
type GamePlayer = { id: string; handle: string; name: string; avatar: string }
```

Someone on the couch. See [Messages and manifest](https://ogs-docs.pages.dev/messages.md#gameplayer).

#### `InstanceReportInput`

```ts
type InstanceReportInput = {
  instanceId: string;
  appId: string;
  status: "lobby" | "active" | "suspended" | "waiting" | "completed" | "expired";
  title?: string;
  detail?: string;
  yourTurn?: boolean;
  startsAt?: number;
  resumeUrl?: string;
}
```

What `reportOgsSitting` takes: an `InstanceReport` whose `title` and `detail` may be left out
(they default to `""`).

#### `InstanceReport`

```ts
type InstanceReport = {
  instanceId: string;
  appId: string;
  status: "lobby" | "active" | "suspended" | "waiting" | "completed" | "expired";
  title: string;
  detail: string;
  yourTurn?: boolean;
  startsAt?: number;
  resumeUrl?: string;
}
```

The parsed report, as sent. Fields: [Messages and manifest](https://ogs-docs.pages.dev/messages.md#instancereport).

#### `Source`

```ts
interface Source<T> {
  getSnapshot(): T;
  subscribe(listener: () => void): () => void;
}
```

An external store, ready for React's `useSyncExternalStore` (or any framework). `getSnapshot` is
stable while nothing changed.

### Lower level (tests and custom wiring)

You rarely need these: the functions above build them for you. They take their dependencies
(an app bridge, a window) as arguments, which makes them easy to test with fakes.

#### `createProfileSource`

```ts
function createProfileSource(opts: ProfileSourceOptions): Source<ProfileSnapshot>
```

The profile store over any app bridge. Waits `timeoutMs` (300 ms) for the bridge's `profile` store
before deciding there is none, and up to `askingTimeoutMs` (5 s) while the app says `asking`.

#### `ProfileSourceOptions`

```ts
interface ProfileSourceOptions {
  bridge: ProfileBridge;
  timeoutMs?: number;
  askingTimeoutMs?: number;
}
```

#### `ProfileBridge`

```ts
interface ProfileBridge {
  isSupported(): boolean;
  getStore(key: "profile"):
    | { getSnapshot(): unknown; subscribe(listener: (state: unknown) => void): () => void }
    | undefined;
  subscribe(listener: () => void): () => void;
}
```

What profile-kit needs of an app bridge (app-bridge-web's `createWebBridge`, or a mock).

#### `ProfileStores`

```ts
type ProfileStores = { profile: { state: ProfileBridgeState; events: { type: "REFRESH" } } };
```

The app-bridge store the OGS app gives a game's WebView.

#### `ProfileBridgeState`

```ts
type ProfileBridgeState =
  | { status: "asking" }
  | { status: "ready"; profile: OgsProfile }
  | { status: "none" };
```

The `profile` store's state: `asking` while the app fetches the game token, `ready` with it, `none`
when there is no profile or no token for this game.

#### `PROFILE_TIMEOUT_MS`

```ts
const PROFILE_TIMEOUT_MS = 300
```

How long to wait for the app's `profile` store before deciding there is none.

#### `ASKING_TIMEOUT_MS`

```ts
const ASKING_TIMEOUT_MS = 5000
```

How long the app may stay `asking` before the game shows its own form.

#### `createSessionSource`

```ts
function createSessionSource(opts: { win: FrameWindow; timeoutMs?: number }): Source<SessionSnapshot>
```

The session store over any window. Listens for `ogs:start` from `win.parent`, posts `ogs:ready`,
and settles to `null` after `timeoutMs` (300 ms) without a start.

#### `SESSION_TIMEOUT_MS`

```ts
const SESSION_TIMEOUT_MS = 300
```

#### `FrameTarget`

```ts
interface FrameTarget {
  postMessage(message: unknown, targetOrigin: string): void;
}
```

Something a page can post to (its parent window).

#### `FrameWindow`

```ts
interface FrameWindow extends FrameTarget {
  parent: FrameTarget | null;
  addEventListener(type: "message", handler: (ev: { data: unknown; source: unknown }) => void): void;
  removeEventListener(type: "message", handler: (ev: { data: unknown; source: unknown }) => void): void;
}
```

The parts of `window` the TV side uses (a fake in tests).

#### `listenForPause`

```ts
function listenForPause(onPause: (paused: boolean) => void, win: FrameWindow): () => void
```

`onOgsPause` over any window.

#### `reportOgsInstance`

```ts
function reportOgsInstance(
  input: InstanceReportInput,
  deps: { bridge: OgsBridge; win: FrameWindow },
): "bridge" | "launcher" | "none"
```

`reportOgsSitting` over any bridge and window. If the bridge is supported but its `ogs` store is not
there yet, it dispatches as soon as the store appears.

#### `OgsBridge`

```ts
interface OgsBridge {
  isSupported(): boolean;
  getStore(key: "ogs"):
    | { dispatch(event: { type: "INSTANCE_REPORT"; report: InstanceReport }): void }
    | undefined;
  subscribe(listener: () => void): () => void;
}
```

What reporting needs of an app bridge.

#### `OgsStores`

```ts
type OgsStores = {
  ogs: {
    state: { reported: string[] };
    events: { type: "INSTANCE_REPORT"; report: InstanceReport };
  };
};
```

The app's `ogs` bridge store: the page reports its sitting, the app posts it to OGS.

## `@open-game-system/profile-kit/react`

Hooks over the sources above (`useSyncExternalStore`; during server rendering both are `undefined`).
Needs React 18 or later.

### `useOgsProfile`

```ts
function useOgsProfile(source?: Source<ProfileSnapshot>): ProfileSnapshot
```

Who is playing on this device: `undefined` while asking the OGS app, `null` in a plain browser
(show your name form), or `{ id, handle, name, avatar, token }`. `source` defaults to
`getOgsProfileSource()`; pass one in tests.

### `useOgsSession`

```ts
function useOgsSession(source?: Source<SessionSnapshot>): SessionSnapshot
```

On the TV page: `undefined` while waiting for the launcher, `null` when not on an OGS TV, or
`{ players, token, instanceId, mode, room? }`. `source` defaults to `getOgsSessionSource()`.

### Re-exported types

`/react` re-exports these types from the main entry, so a React page needs one import:

#### `OgsProfile` (react)

Same as [`OgsProfile`](#ogsprofile).

#### `ProfileSnapshot` (react)

Same as [`ProfileSnapshot`](#profilesnapshot).

#### `OgsSession` (react)

Same as [`OgsSession`](#ogssession).

#### `SessionSnapshot` (react)

Same as [`SessionSnapshot`](#sessionsnapshot).

## `@open-game-system/profile-kit/server`

For your game's server (Cloudflare Workers, Node 20+, Deno, Bun: anything with `fetch` and Web Crypto).

### `verifyOgsToken`

```ts
function verifyOgsToken(
  token: string,
  opts: { appId: string } & VerifierOptions,
): Promise<GameToken | null>
```

Verifies a game token for your game: the ES256 signature against OGS's key set, `aud === appId`
(a token for another game is rejected), and expiry. Returns the claims, or `null` when any check
fails. The key set is cached per `jwksUrl`; an unknown key id refetches it at most once a minute.
Passing `fetch` or `now` uses a fresh verifier (tests).

```ts
const claims = await verifyOgsToken(token, { appId: "space-bakery", jwksUrl: env.OGS_JWKS_URL });
```

### `createOgsVerifier`

```ts
function createOgsVerifier(opts?: VerifierOptions): (token: string, appId: string) => Promise<GameToken | null>
```

A verifier with its own cached key set, for when you want to hold one explicitly.

### `VerifierOptions`

```ts
interface VerifierOptions {
  jwksUrl?: string;
  fetch?: (url: string) => Promise<Response>;
  now?: () => number;
}
```

`jwksUrl` defaults to `OGS_JWKS_URL`. `fetch` and `now` are for tests.

### `OGS_JWKS_URL`

```ts
const OGS_JWKS_URL = "https://api.opengame.org/.well-known/jwks.json"
```

The default key set. Set `jwksUrl` explicitly from configuration: it lets seam tests serve a local key
set, and lets you point at the OGS API you deploy against.

### `GameToken`

```ts
type GameToken = {
  iss: string; aud: string; sub: string; handle: string; name: string; avatar: string;
  sid?: string; players?: GamePlayer[]; couch?: CouchClaim; iat: number; exp: number;
}
```

The claims OGS signs into a game token. `sub` is the profile id (the host's on a TV token); `sid`
and `players` are on TV tokens; `couch` on every token issued for a couch. Never friends, other
games, device ids, push tokens or age. Field table: [Messages and manifest](https://ogs-docs.pages.dev/messages.md#gametoken).

### `CouchClaim`

```ts
type CouchClaim = { sid: string; label: string }
```

The couch a token was issued for: the couch session id and its label (the host's name). Players
with the same `sid` sit on the same couch.

---

<!-- https://ogs-docs.pages.dev/messages.md -->

# Messages and manifest

The exact shapes OGS and a game exchange. The tables on this page are **generated from the zod
schemas** in [packages/ogs-protocol](https://github.com/open-game-system/open-game-system/blob/main/packages/ogs-protocol/src/frame.ts) when the site is
built, so they match the code. When anything here and the code disagree, the code wins.

With profile-kit you do not post or parse these by hand: see
[profile-kit reference](https://ogs-docs.pages.dev/profile-kit.md). This page is for games that do, for tests that fake the
launcher, and for agents that want the precise contract.

## Transport

- The launcher and the TV page talk with `window.postMessage`. Each message is a plain object with a
  `type` field.
- The launcher posts to your iframe's `contentWindow`. Your page posts to `window.parent` (profile-kit
  uses target origin `"*"`; the launcher checks the origin instead).
- The launcher accepts game messages only from the origin of the current game's TV URL, and drops
  anything that fails `GameToLauncherSchema`. An `ogs:instance` without a `title` labels nothing.
- Validate what you receive: ignore anything whose `event.source` is not `window.parent`, and parse
  with the schema (`LauncherToGameSchema.safeParse(event.data)`). Unknown messages are ignored, never
  errors.
- Every message is optional for the game. A game that answers nothing still runs.

## Launcher → game

`LauncherToGameSchema` in [frame.ts](https://github.com/open-game-system/open-game-system/blob/main/packages/ogs-protocol/src/frame.ts).

### `ogs:start`

The sitting starts or continues. Sent on the frame's load, and again after each `ogs:ready`.

| Field | Type | Required | Description |
|---|---|---|---|
| `instanceId` | string | yes | The OGS sitting this frame is for. |
| `mode` | "continue" \| "new" | yes | `continue` an earlier sitting, or start a `new` one. |
| `roster` | [RosterEntry](#rosterentry)[] | yes | Who sits where: profile, role and device, when the couch picked roles. |
| `token` | string | yes | A game token for this game and session (aud = appId, players + sid); "" when there is none. |
| `players` | [GamePlayer](#gameplayer)[] | no | Who's on the couch: profile id, @id, name, avatar. |
| `room` | [RoomId](#roomid) | no | Join this room (another couch made it) instead of making one (multiCouch games). |

### `ogs:suspend`

The launcher parked the frame (Home, or another game). It stays loaded: go silent.

No payload: `{ type: "ogs:suspend" }`.

### `ogs:resume`

Continue: the same parked frame is shown again, no reload. Resume sound.

No payload: `{ type: "ogs:resume" }`.

## Game → launcher

`GameToLauncherSchema` in [frame.ts](https://github.com/open-game-system/open-game-system/blob/main/packages/ogs-protocol/src/frame.ts).

### `ogs:ready`

The page is listening; the launcher re-sends `ogs:start` for the current sitting.

No payload: `{ type: "ogs:ready" }`.

### `ogs:resume-point`

The sitting's label (older form of `ogs:instance`).

| Field | Type | Required | Description |
|---|---|---|---|
| `label` | string | yes | For example `"Mission 6"`. |

### `ogs:room`

The room the TV page shows (multiCouch games): the couch session keeps it on the sitting.

| Field | Type | Required | Description |
|---|---|---|---|
| `room` | [RoomId](#roomid) | yes | The game's own room code. |

### `ogs:instance`

The sitting's report; the launcher uses `report.title` as its label.

| Field | Type | Required | Description |
|---|---|---|---|
| `report` | [InstanceReport](#instancereport) | yes | What the game says about this sitting. |

## Phone page → app

In the OGS app's WebView a game page talks to the app over the app bridge, not `postMessage` to a
parent. profile-kit uses two bridge stores:

| Store | Direction | Content |
|---|---|---|
| `profile` | app → page | `{ status: "asking" }`, `{ status: "ready", profile: OgsProfile }` or `{ status: "none" }` |
| `ogs` | page → app | event `{ type: "INSTANCE_REPORT", report: InstanceReport }` (`OgsBridgeEventSchema`) |

Room games declare their TV page with cast-kit's `useCastViewUrl(url)`; the app forwards it to the
launcher. See [the contract, §3](https://ogs-docs.pages.dev/contract.md#3-phones-the-game-page-in-the-apps-webview).

## A typical sequence

```
launcher                                   your TV page (iframe)
   |  load iframe (allow="autoplay; fullscreen")  |
   |--- ogs:start {instanceId, mode, roster, token, players} --->|
   |<-------------------------- ogs:ready ---------------------- |  (profile-kit, on start-up)
   |--- ogs:start (again, for the current sitting) ------------> |
   |<---------- ogs:instance {report: {title: "Mission 1"}} ---- |
   |              ... the couch plays ...                        |
   |--- ogs:suspend -------------------------------------------> |  Home: go silent, stay loaded
   |--- ogs:resume --------------------------------------------> |  Continue: sound back, no reload
```

## Manifest

A game is config, not code: one `Manifest` (`ManifestSchema` in
[manifest.ts](https://github.com/open-game-system/open-game-system/blob/main/packages/ogs-protocol/src/manifest.ts)). Fields with a default may be left out.

| Field | Type | Required | Description |
|---|---|---|---|
| `appId` | string (`^[a-z0-9-]+$`) | yes | The game's id; also the `aud` of every game token for this game. |
| `name` | string (non-empty) | yes | Shown in the Library and on the TV. |
| `tagline` | string | no (default `""`) | One line under the name in the Library. |
| `shape` | "couch" \| "live" \| "async" | yes | `couch`: played together in one room; `live`: real-time online; `async`: turns over days. |
| `tv` | "none" \| "optional" \| "required" | yes | Whether the game needs a TV. |
| `startUrl` | string (URL) | yes | Played on a phone or tablet (also the controller URL when the TV shows tvUrl). |
| `tvUrl` | string (URL) | no | A static TV page. Room-based games omit it: their phone page sends the room's TV URL at runtime (cast-kit useCastViewUrl). |
| `roles` | [Role](#role)[] | no (default `[]`) | Who plays: each role's `audience` lets OGS suggest who sits where. |
| `art` | object | yes | The art kit (see Art kit and catalogue). |
| `art.tile` | string (non-empty) | yes | Older captured TV screenshot, 16:9 (required). |
| `art.hero` | string | no | Older captured hero image, 16:9. |
| `art.icon` | string (non-empty) | no | 1:1 icon. |
| `art.cover` | string (non-empty) | no | 2:3 cover with the title. |
| `art.logo` | string (non-empty) | no | Transparent logo. |
| `art.heroClean` | string (non-empty) | no | 16:9 hero with no text and no HUD. |
| `art.theme` | string (non-empty) | no | The game's music theme: a 20–40 s seamless audio loop (music only) the launcher's Home plays while the game is focused. |
| `art.safe` | object | no | Crops a HUD out of `tile`/`hero` when there is no clean art: zoom about a point. |
| `art.safe.scale` | number (> 0) | yes | Zoom factor. |
| `art.safe.ox` | number | yes | Zoom origin x, percent of the width. |
| `art.safe.oy` | number | yes | Zoom origin y, percent of the height. |
| `shop` | object | no (default `{}`) | Shown on the game's page in the app. |
| `shop.ages` | string | no | For example `"4+"`. |
| `shop.minutes` | [number, number] | no | Typical sitting length, `[min, max]` minutes. |
| `shop.players` | string | no | For example `"2-4"`. |
| `multiCouch` | boolean | no | Several couches may join one room of this game (spec §7). Absent = single couch. |
| `instanceTtlMs` | number (> 0) | no (default `604800000`) | How long an instance may stay silent before it expires (ms). |

An example:

```json
{
  "appId": "space-bakery",
  "name": "Space Bakery",
  "tagline": "Bake for aliens, together.",
  "shape": "couch",
  "tv": "required",
  "startUrl": "https://space-bakery.example.com/",
  "roles": [
    { "id": "chef", "label": "Chef", "audience": "grownup" },
    { "id": "helper", "label": "Helper", "audience": "kid" }
  ],
  "art": {
    "icon": "/art/space-bakery/icon.png",
    "cover": "/art/space-bakery/cover.jpg",
    "logo": "/art/space-bakery/logo.png",
    "heroClean": "/art/space-bakery/hero-clean.jpg",
    "tile": "/art/space-bakery/tv.jpg"
  },
  "shop": { "ages": "4+", "minutes": [10, 20], "players": "2-4" }
}
```

No `tvUrl`: this is a room game whose phone page declares the room's TV page at runtime. A game with
one TV page for everyone adds `"tvUrl": "https://space-bakery.example.com/tv"`.

## Shared types

### `GamePlayer`

Someone on the couch (`ogs:start.players`, `GameToken.players`).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string (non-empty) | yes | OGS profile id. |
| `handle` | string (non-empty) | yes | The profile's @handle. |
| `name` | string (non-empty) | yes | Display name. |
| `avatar` | string (URL) | yes | Avatar image URL. |

### `RosterEntry`

Who sits where (`ogs:start.roster`).

| Field | Type | Required | Description |
|---|---|---|---|
| `profileId` | string | yes | OGS profile id. |
| `roleId` | string | yes | One of the manifest's `roles[].id`. |
| `deviceId` | string | no | The device this player plays on. |

### `InstanceReport`

What a game reports about a sitting (`ogs:instance`, `reportOgsSitting`). Only `instanceId`, `appId` and `status` are needed.

| Field | Type | Required | Description |
|---|---|---|---|
| `instanceId` | string (non-empty) | yes | The sitting's id. |
| `appId` | string (non-empty) | yes | The game's appId. |
| `status` | [InstanceStatus](#instancestatus) | yes | Where the sitting is. |
| `title` | string | no (default `""`) | The sitting's label, for example `"Mission 6"` or `"Room KQTP"`. |
| `detail` | string | no (default `""`) | A second line under the label. |
| `yourTurn` | boolean | no | For async games: true when it's this profile's move. |
| `startsAt` | number | no | For scheduled sittings (a game night): when it starts, ms since epoch. |
| `resumeUrl` | string (URL) | no | Where to send people back in. |

### `InstanceStatus`

One of `lobby`, `active`, `suspended`, `waiting`, `completed`, `expired`.

### `GameToken`

The claims of a game token, as `verifyOgsToken` returns them.

| Field | Type | Required | Description |
|---|---|---|---|
| `iss` | string (non-empty) | yes | The OGS API that signed it. |
| `aud` | string (non-empty) | yes | The game (appId) this token is for. |
| `sub` | string (non-empty) | yes | OGS profile id (a session token: the host's). |
| `handle` | string (non-empty) | yes | The profile's @handle. |
| `name` | string (non-empty) | yes | Display name. |
| `avatar` | string (URL) | yes | Avatar image URL. |
| `sid` | string (non-empty) | no | The couch session (TV tokens only). |
| `players` | [GamePlayer](#gameplayer)[] | no | Who's on the couch (TV tokens only). |
| `couch` | [CouchClaim](#couchclaim) | no | The couch this token was issued for (TV tokens, and phones that asked with their session). |
| `iat` | number (integer, ≥ 0) | yes | Issued at, seconds since epoch. |
| `exp` | number (integer, > 0) | yes | Expiry, seconds since epoch (1 hour after `iat`). |

### `CouchClaim`

The couch a token was issued for.

| Field | Type | Required | Description |
|---|---|---|---|
| `sid` | string (non-empty) | yes | The couch session id. Players with the same `sid` sit on the same couch. |
| `label` | string (non-empty) | yes | The couch's label (the host's name). |

### `Role`

One of the manifest's roles.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string (non-empty) | yes | The role's id (`RosterEntry.roleId`). |
| `label` | string (non-empty) | yes | Shown to people, for example `"Captain"`. |
| `audience` | "grownup" \| "kid" \| "little" | yes | Who the role suits: a grown-up, a kid, or a little one. |

### `RoomId`

A string matching `^[A-Za-z0-9_-]{1,64}$`: the game's own room code.

---

<!-- https://ogs-docs.pages.dev/testing.md -->

# Testing your game

You do not need the OGS app, a Chromecast or the real launcher to test an OGS integration. Test at
the seams instead: **frame your TV page from a tiny parent page that plays the launcher**, and **load
your phone page with a fake WebView bridge**. Both run in Playwright under Vitest (or any test runner)
against your local dev server.

Write each test before the code it covers, and see it fail first.

## Setup

```bash
pnpm add -D vitest playwright
pnpm exec playwright install chromium
```

Start your game locally (for example `wrangler dev` on port 8787) and point the tests at it with an
environment variable (`GAME_URL`). Autoplay needs `--autoplay-policy=no-user-gesture-required`,
because the launcher plays without a tap.

## 1. The TV page in a stand-in launcher

The parent page is one iframe, like the launcher's. The test posts the launcher's messages into the
iframe and asserts on the page. This one proves the TV goes silent when parked: it records every
`AudioContext` the page creates, then checks their state after `ogs:suspend` and `ogs:resume`.

```ts
// e2e/ogs-pause.seam.test.ts
import { chromium, type Frame } from "playwright";
import { afterAll, describe, expect, it } from "vitest";

const BASE = process.env.GAME_URL ?? "http://localhost:8787";
const TV_URL = `${BASE}/tv`; // your TV page
const browserP = chromium.launch({ args: ["--autoplay-policy=no-user-gesture-required"] });
afterAll(async () => (await browserP).close());

/** Remember every AudioContext the page makes, so the test can read its state. */
const TRACK_AUDIO = `
  window.__ctxs = [];
  const Real = window.AudioContext;
  window.AudioContext = class extends Real {
    constructor(...a) { super(...a); window.__ctxs.push(this); }
  };
`;
const states = (f: Frame) =>
  f.evaluate(() => Reflect.get(window, "__ctxs").map((c: AudioContext) => c.state));

describe("parked by the OGS launcher", () => {
  it("suspends the TV's sound on ogs:suspend and resumes it on ogs:resume", async () => {
    const page = await (await browserP).newPage();
    await page.addInitScript(TRACK_AUDIO); // runs in the iframe too
    await page.setContent(
      `<iframe id="game" allow="autoplay; fullscreen" src="${TV_URL}" style="width:1280px;height:720px;border:0"></iframe>`,
    );
    const frame = await (await page.waitForSelector("#game")).contentFrame();
    if (!frame) throw new Error("no game frame");
    await expect.poll(() => states(frame), { timeout: 15_000 }).toEqual(["running"]);

    const post = (msg: object) =>
      page.evaluate((m) => {
        const el = document.getElementById("game");
        if (el instanceof HTMLIFrameElement) el.contentWindow?.postMessage(m, "*");
      }, msg);

    await post({ type: "ogs:suspend" });
    await expect.poll(() => states(frame)).toEqual(["suspended"]);
    await page.waitForTimeout(500);
    expect(await states(frame)).toEqual(["suspended"]); // nothing (a music loop) wakes it

    await post({ type: "ogs:resume" });
    await expect.poll(() => states(frame)).toEqual(["running"]);
    await page.close();
  }, 30_000);
});
```

Add the same shape for the rest of the TV contract:

- **`ogs:start` names the couch.** Post
  `{ type: "ogs:start", instanceId: "i1", mode: "new", roster: [], token: "", players: [{ id: "p1", handle: "sam", name: "Sam", avatar: "https://example.com/a.png" }] }`
  and expect `frame.getByText("Sam")` to be visible. Also assert the room code, join QR and cast
  button are gone.
- **`ogs:ready` is said.** Before loading the iframe, collect what the frame posts to the parent:
  `page.exposeFunction("onGameMessage", …)` plus a `message` listener in the parent page. Expect an
  `{ type: "ogs:ready" }`, then answer it with `ogs:start`.
- **Your sitting label comes back.** After `ogs:start`, expect an
  `{ type: "ogs:instance", report: { title: "…" } }` from the frame.
- **No full-screen button when framed.** The launcher already fills the TV:
  `expect(await frame.getByRole("button", { name: /full screen/i }).count()).toBe(0)`. The same page
  opened directly (`page.goto(TV_URL)`) may keep its button.
- **Test at TV sizes.** Run the framed page at 1280×720 and 1920×1080 and check that nothing important
  sits outside the 5% safe area or over the focal area.

## 2. The phone page in a fake WebView

The OGS app injects `window.ReactNativeWebView` and answers the page's `BRIDGE_READY` with each
store's state (`STATE_INIT`). Fake it with an init script, and give the `profile` store a ready
profile whose `token` your test signed:

```ts
const fakeWebView = (stores: Record<string, unknown>) => `
  window.__ogsSent = [];
  window.ReactNativeWebView = {
    postMessage(raw) {
      const msg = JSON.parse(raw);
      window.__ogsSent.push(msg);
      if (msg.type === "BRIDGE_READY") {
        setTimeout(() => {
          for (const [storeKey, data] of Object.entries(${JSON.stringify(stores)}))
            window.dispatchEvent(new MessageEvent("message", {
              data: JSON.stringify({ type: "STATE_INIT", storeKey, data }),
            }));
        }, 50);
      }
    },
  };
`;

const ctx = await browser.newContext({ viewport: { width: 390, height: 844 } });
await ctx.addInitScript(
  fakeWebView({
    profile: {
      status: "ready",
      profile: { id: "p1", handle: "sam", name: "Sam", avatar: "https://example.com/a.png", token },
    },
  }),
);
const page = await ctx.newPage();
await page.goto(`${BASE}/`);
await expect(page.getByLabel("name")).toHaveCount(0); // no name form inside OGS
```

- **Signing test tokens.** Generate an ES256 key pair with Web Crypto, serve its public JWK at
  `http://localhost:8831/.well-known/jwks.json` from the test (`node:http`), and start your server
  with that `jwksUrl` (for a Worker: `wrangler dev --var OGS_JWKS_URL:http://localhost:8831/.well-known/jwks.json`).
  Sign tokens whose claims match [`GameToken`](https://ogs-docs.pages.dev/messages.md#gametoken) with `aud` = your appId.
- **Assert the server's view**, not just the page: the player is seated under the token's `name`, a
  token for another `appId` or an expired one is not.
- **Sitting reports** arrive in `window.__ogsSent` as
  `{ type: "EVENT", storeKey: "ogs", event: { type: "INSTANCE_REPORT", report } }`. Give the fake an
  `ogs` store too (`ogs: { reported: [] }` next to `profile`): profile-kit waits for the store before
  it dispatches.

## 3. Still a plain-browser game

OGS games must keep working without OGS. Keep (or add) one end-to-end test that plays a short round
with no fake bridge and no frame: the name form appears, the TV page shows its own join code, and the
round finishes. profile-kit returns `null` and does nothing there, so this mostly guards your own
`if (inOgs)` branches.

## 4. Unit tests for your own logic

Keep the OGS decisions in small pure functions and test them directly: "given this profile snapshot,
show the form or join?", "given this phase, what is the sitting label?", "paused: which sounds stop?".
profile-kit's lower-level functions take their bridge and window as arguments
(`createSessionSource({ win })`, `createProfileSource({ bridge })`), so you can drive them with fakes.

## 5. In the real app

Last, once the seams pass: run the game in the OGS app against the real launcher. Check that phones
skip the name form, the TV names the couch, Home silences the TV, Continue brings it back with sound,
and the Playing tab shows your label. Say which you did: tests passing, deployed, or verified on a
real TV.

---

<!-- https://ogs-docs.pages.dev/art-and-catalogue.md -->

# Art kit and catalogue

Every game in the OGS catalogue ships an **art kit**: four images the app and the TV launcher use for
the Library, the game page and the launcher's Home. Then it is listed by adding its manifest to the
catalogue.

## The art kit

| Field | Image | Shape | Size we use | Rules |
|---|---|---|---|---|
| `art.icon` | Icon | 1:1 | 512×512 PNG | The game at a glance; readable at 48 px |
| `art.cover` | Cover | 2:3 | 600×900 JPG | **With the title** lettered in |
| `art.logo` | Logo | any, transparent | about 1200 px wide PNG with alpha | The title alone, on transparency |
| `art.heroClean` | Clean hero | 16:9 | 1920×1080 JPG | **No text and no HUD**: the launcher draws its own title and buttons over it |

Older fields, still in the manifest:

- `art.tile` (required): a 16:9 screenshot of the TV page (1920×1080).
- `art.hero`: another 16:9 screenshot.
- `art.safe` (`scale`, `ox`, `oy`): crops a HUD out of `tile`/`hero` when there is no clean art.

Taste, for every image:

- Your game's **own art direction**. Don't borrow another OGS game's look.
- **No faces on objects** (rockets, planets, props). Characters may have faces; things don't.
- No UI, no buttons, no score in `heroClean` and `icon`.
- Check the kit next to the other games: the catalogue's contact sheet is
  [apps/tv/public/art/KIT-SHEET.jpg](https://github.com/open-game-system/open-game-system/blob/main/apps/tv/public/art/KIT-SHEET.jpg).

The images live in the OGS repo at `apps/tv/public/art/<appId>/` and the manifest refers to them by
path from that folder's root:

```json
"art": {
  "icon": "/art/space-bakery/icon.png",
  "cover": "/art/space-bakery/cover.jpg",
  "logo": "/art/space-bakery/logo.png",
  "heroClean": "/art/space-bakery/hero-clean.jpg",
  "tile": "/art/space-bakery/tv.jpg"
}
```

### Theme music (optional)

`art.theme` is a 20–40 s seamless loop of your game's music (music only: no effects or voice).
The launcher's Home plays it quietly while your game is focused and crossfades as focus moves;
every other screen is silent. Ship MP3 (~128 kbps; every browser and the cloud renderer decode it),
loudness around −20 dB with peaks below −1 dB, and fade the seam so the loop is gapless, e.g.
`"theme": "/art/space-bakery/theme.mp3"`. No theme means Home is silent on your game.

## Submit to the catalogue

The catalogue is the list of manifests in
[services/api/src/catalogue.ts](https://github.com/open-game-system/open-game-system/blob/main/services/api/src/catalogue.ts), served at
`GET /api/v1/catalogue`; the app's Library reads it from there. There is no self-serve form yet:
games are added by pull request to
[open-game-system/open-game-system](https://github.com/open-game-system/open-game-system).

1. **Red:** add your `appId` to the expected list in
   [services/api/test/catalogue.test.ts](https://github.com/open-game-system/open-game-system/blob/main/services/api/test/catalogue.test.ts) (`GAMES`), plus
   whatever your game does differently from the defaults that test assumes: your own domain
   (`OWN_DOMAIN`), a game for grown-ups only (`ADULT_GAMES`; otherwise a role must suit a kid), or a
   static `tvUrl`. Run `pnpm --filter @open-game-system/api test` and see it fail.
2. **Art:** add the four images (and `tv.jpg`) under `apps/tv/public/art/<appId>/`. The catalogue test
   fails if any kit field is missing or a file does not exist.
3. **Green:** add your manifest to `SEED` in `services/api/src/catalogue.ts`. Every field is checked by
   `ManifestSchema` ([fields](https://ogs-docs.pages.dev/messages.md#manifest)).
4. Run the repo's gates: `pnpm typecheck && pnpm lint && pnpm test`.
5. Open the pull request. Say in it which of the [rules](https://ogs-docs.pages.dev/rules.md) you checked and how (tests, a
   real TV), and link your game's seam tests.

Don't add games to `apps/mobile/services/game-directory.ts`: that is the old static list.

For local development, the API's `CATALOGUE_START_URLS` (JSON `{ "appId": "url" }`) swaps in local
`startUrl`s for games already in the catalogue; it never adds games.

---

<!-- https://ogs-docs.pages.dev/rules.md -->

# Rules and taste

What every OGS game does, and why. The binding list is [§5 of the contract](https://ogs-docs.pages.dev/contract.md#5-rules);
this page explains each rule and how to check it.

## 1. No cast button

OGS casts once for the whole evening; the launcher frames your game. A game never starts a cast,
never shows a cast button or a "cast to TV" prompt, and never ships a cast receiver for OGS. Inside
the OGS app the app ignores a game's own cast actions anyway.

**Check:** search the phone page for a cast button and remove it; room games keep only
`useCastViewUrl` (see [Quickstart, step 8](https://ogs-docs.pages.dev/quickstart.md#8-room-games-declare-the-tv-page-from-the-phone)).

## 2. No join codes on an OGS TV

People join the couch with the launcher's TV code; phones already land in your game. On an OGS TV,
show no room code, no join QR, no "join at …" URL. Outside OGS (a plain browser) keep them: that is
how people join there.

**Check:** framed after `ogs:start` there is no code or QR; opened directly there is.

> Planned ([contract §8](https://ogs-docs.pages.dev/contract.md#8-joining-and-invites-planned)): the launcher will draw its own
> join QR and an invite card in one corner, and a game may ask for it with `ogs:invite`. Keep that
> corner (top-right by default, at most 220×120 px on a 960×540 reference with a 24 px margin) free of
> your focal area and HUD.

## 3. Nothing over the focal area

The TV is the shared screen everyone watches from the sofa. Whatever the game is about right now
(the board, the character, the question) stays uncovered: HUD, scores and toasts live at the edges,
small and brief.

**Check:** screenshots of every phase at 1280×720 and 1920×1080; nothing overlaps the focal element.

## 4. Inside the safe area

TVs crop their edges. Keep every element that matters at least **5%** in from each edge of the TV
page, and remember that a focus or hover `scale()` grows an element past that line: scale it away from
the edge.

**Check:** at 1280×720, 1920×1080 and 3840×2160, every visible element's bounding box is inside the
5% inset.

## 5. Silent while parked

Home or another game parks your frame: it stays loaded so Continue is instant, so its sound keeps
playing unless you stop it. On `ogs:suspend` (`onOgsPause(true)`) suspend the `AudioContext`, pause
media, and stop anything that would start a sound. On `ogs:resume` resume only what was playing.

**Check:** the [pause seam test](https://ogs-docs.pages.dev/testing.md#1-the-tv-page-in-a-stand-in-launcher).

## 6. Starts without a tap

There is no pointer or keyboard on the TV. The TV page starts, plays sound and animates on load, and
is driven entirely from the phones. No "click to start", no full-screen button when framed.

## 7. Still a plain web game

Without OGS the game is complete: its own name form, room code and TV link, and full play end to end.
Every profile-kit call returns `null` or does nothing there, so keep your own path behind those
`null`s.

**Check:** the [plain-browser test](https://ogs-docs.pages.dev/testing.md#3-still-a-plain-browser-game).

## 8. Trust only verified tokens

Use `verifyOgsToken` on your server for anything that matters: seats, scores, names other people
see. A game sees only **game tokens for itself**, never the app's or the launcher's own token. A
token tells you a profile id, handle, name and avatar, and on a TV the couch: never friends, other
games, device ids or age. Don't ask for more.

## 9. Phones: the OGS profile replaces your name form

Inside the OGS app, join under the OGS name and avatar without a form, and hide your own join-code
entry. Join once per seat; the app refreshes the token and a new token must not join again.

## Taste

- Your game's own look: don't copy another OGS game's art direction.
- No faces on objects (rockets, planets, props).
- Big, legible type on the TV, read from a sofa three metres away.
- Phones and iPads are controllers: big targets where thumbs rest, near the bottom edge.