game-kit/CONVENTIONS.md

# House conventions for a game in this kit

Every game built from the kit shares one shape, so a player who has been at
one table knows the next, and the keeper runs them all the same way. This is
the shape. When a game strays from it, the reason should be in the game's
README.

## The vocabulary

- **The hall** is the landing page (`/`). Name, *Play now against the bot*,
  *Open a table*, *or join one* with a four-letter code, then *your games*
  (the ledger of tables this browser holds a seat at, with whose move it
  is and unread talk; for someone coming back it comes first, and finished
  games wait further down), *your reports to the keeper*, and *about this game*,
  which opens the about panel: a dialog of tabs (Origins, Games so far,
  More games, Send word; a game may rename the first two in its own world,
  as Waving Hands' Duels so far, or add its own, as Dip's Playing here), `TabbedDialog.svelte`, with each game's words in its hall.
  The address names the dialog (`#about`, `#about/tally`), so a plain link
  opens it; a game may put its guide and rules in dialogs the same way, as
  Dip does. Its strip of tabs is `Tabs.svelte`.
- **A table** is a room. Its code is four letters or digits from an alphabet
  with no look-alikes, and its link is `/join/CODE`. The masthead button
  reads *invite friends · room CODE* and copies the link. Whoever opened
  the table is **the host**; they may *Seat a bot* and they *Begin* when the
  company suits them, at any size of table; there is no automatic start.
- **The Peanut Gallery** is where a link takes anyone without a seat: a
  read-only view showing only what every seat could see, counted for the
  table (*3 in the gallery*). While the table is laid, a watcher is offered
  a seat first; the gallery is the afterthought.
- **Table talk** is the chat panel, seated players only unless the host
  *lets the Peanut Gallery talk*; then a watcher signs a name no seat holds
  and their lines read *Name (gallery)*. Each line is a ledger line, so it
  replays with the game, and the hall counts lines said while you were away.
  A line said while a game is running carries its round (`turn`). A seat
  may also speak privately, naming seats (`room.say(text, to)`): the line
  is shown to its sender and those seats alone, never to the gallery, and
  a game whose talk is its heart puts the choice of whom in its talk box.
- **A rematch**: a finished table may call for one. A new table of the same
  size opens with the same bots, seats held for the same people, and the
  caller as host; a second call finds it already open. Held seats refuse
  strangers until their players are back.
- **The keeper's bell**: while a table is laid, a seated player may
  *Challenge the keeper*. A seat is held under the keeper's name, the call
  goes on the ledger, and the keeper's phone rings through Sentry. The note
  beside the button says what hour it is where the keeper lives, so a
  caller knows whether to wait ten minutes or come back tomorrow.
- **A seat travels by phrase**: *Transfer seat* in the masthead mints four
  words good for ten minutes and one use; the hall's *bring a seat from
  another device* claims them. The browser that claims holds the seat too.
- **The keeper can bring a seat back**: a player whose browser lost the
  seat (Safari's seven days, an app's own browser, cleared data) writes to
  the keeper, and `<slug>-reseat.sh ROOM SEAT` on the host gives the seat
  a new token and prints a link carrying it in the fragment. The old token
  opens nothing after. The script answers through the game server's
  `/keeper` door, which Caddy does not proxy. A spectator at a game in play
  is told both ways back, and the hall asks before forgetting a game in play.
- **Held seats are doubted before they are dropped**: the hall forgets a
  seat only on the second refusal in a row from the server. A restart, a
  stale answer or the wrong backend answer with ignorance, and ignorance
  is not deletion.
- **The ledger** is the append-only JSONL file that *is* the game: room,
  seats, start (seed and rules revision), each seat's submitted input, the
  turn that resolves them, talk, over. A room is its ledger replayed
  through a deterministic engine; nothing else is saved. A half-written
  round survives a restart because every input is written as it arrives.
  Ledgers survive deploys and restarts and are backed up nightly, so they
  hold nothing secret: a seat line carries the SHA-256 of its token, never
  the token, which goes once to the browser that earned it.
- **Report** in the masthead opens the slip: what happened, what you
  expected, a screenshot if you have one. It is pinned to the room and the
  round. **The keeper** replies; the reply appears under the report in the
  player's hall, and the player may answer. Every report and answer rings
  the keeper's phone through Sentry; the desk's own replies ring nothing.
- **The rules page** (`/rules`) is the game's text, structured for reading
  mid-game, with the original source verbatim in collapsible sections. The
  engine follows that text and nothing else; a divergence is a bug. The
  page ends with *send word*.
- **How to play** (`/guide`) walks the page in the game's own voice, one
  screenshot per section, from the hall to a first game.
- **Send word** is the contact paragraph: mail, Bluesky and Mastodon, and
  where the keeper roosts. It lives in the about panel; the colophons, the
  rules page and the guide each carry a one-line mail link.
- **The family list** in the about panel, *More games in Kestrel's Hall*,
  comes from `family.json` and its heading links to the family's landing
  page, gamehall.kestrelsnest.social. A new game is added to the kit's
  `family.json` and given a card on that page (`gamehall/` in the kit);
  both are hand-kept.
- **A move names the round it was made for.** The room counts rounds
  played (`resolved` in its view), and a page sends that count with each
  move; the server refuses a move whose count is behind, so a slow
  connection, a second click or a stale tab can never be taken as the
  move for the next round. A page without the count is told to reload.
- **The hosting line** follows the family list in the about panel: the
  games are free and will stay free, the servers cost a few dollars a
  month, and ko-fi.com/kestrelsnest is where anyone may chip in. It says
  chipping in unlocks nothing and nothing is held back without it, and it
  never names a game's rights holder: a tip is for the hosting, not the
  game.

- **Preferences** are what a browser remembers about its player: a panel
  opened from *preferences* in the hall and the masthead, kept in
  localStorage and nowhere else. The kit's own settings are motion (full or
  reduced, and the system's reduced-motion request counts too) and
  confirming a move before it is sent; a game declares more in
  `GameSpec.preferences` and the panel renders them. The hall also
  remembers the host's last table options as the next table's defaults.
- **The tally** sits in the about panel: what the ledgers add up to
  (tables, games begun and finished, names seated, turns, time at the
  table, games with a bot, talk), counted on demand from the files and
  cached a minute. A game adds its own lines through `GameSpec.tally` and
  `GameSpec.tallyBegun`.
- **Table options** are the host's choices when opening a table (a
  variant, a side, a length): the game declares them in `GameSpec.options`,
  the hall renders them as selects, the room line records them, and
  `create` receives them. A game with one way to play declares none. An
  option that changes how many can sit (a smaller map) says so through
  `GameSpec.seatsFor`. The server, the tally and the ledger replay all read
  a room line through `cleanOptions` and size a table with `tableSize`,
  both in `spec.ts`, so each creates the same game from the same ledger.

## The engine

- Pure and deterministic: `create(names, seed, rules, options)` and
  `resolve(state, inputs)` are functions of their arguments with a seeded
  generator inside the state. Bots are functions of the state too. This is
  what lets a ledger be the whole record.
- Simultaneous by default: every seat that `needsInput` submits, then the
  round resolves at once, bots included. A seat that owes an extra turn
  alone (a time stop, a bonus move) is just a state where only it needs
  input; the server resolves rounds owed only to bots straight away. A few
  such rounds are played at once; past that (a table every person is out
  of), the bots play on a round every two seconds so the table can be
  watched and the server answers everyone else between rounds. The view
  says so (`playingOn`), and a seat may ask for the rest at once
  (`room.hurry()`).
- Hidden information is the engine's business: `view(state, viewer)`
  returns what one seat may see, and the SPECTATOR view is the
  intersection of everyone's. The server sends nothing else.
- **The rules revision** is stamped on every game at its start line. Bump
  it only when the deploy gate shows a fix changes how an already-played
  round resolves; keep the old path behind `state.rules < N` and pin both
  with tests. A fix that diverges from no ledger ships without a bump.

## Optional hooks

A game implements only the hooks it needs; without one, the kit behaves as
if it were never there.

- `validate(state, seat, input)`: a reason to refuse a move, shown to the player.
- `seatsFor(options)`: fewer seats for some table options.
- `settled(input)`: whether an input is final. A game with drafts answers
  false until the player says it is done; a draft may be replaced (and a
  settled move taken back as a draft) until the round resolves, and the
  round waits for every seat's settled input. A seat's view carries its
  own input in waiting (`yourInput`), so a page reopened shows the draft,
  and its input in the last round it played (`yourLastInput`), so the page
  can tell it what became of its own choice.
- `rankable(options)`: the choices a table asks each seat to rank before
  the deal (sides, roles, colours). The lobby shows a seat its own ranking
  and how many have ranked, nothing more; the start line records every
  ranking and `create` receives them. A solo table asking for one waits in
  the lobby for the player's.
- `botPress(state, seat, press, people, trigger)`: bots that talk. A bot
  speaks when a round opens and when a person writes to it (or says a first
  word to the table); its lines go privately to the people it names, as
  ledger lines, with a `note` for its own memory that no view ever carries.
  `botInput` receives the same press, so a bot can keep what was agreed.
  `parting(press, viewer)` gives the bots' last words once the game is
  over. Without `botPress`, private talk to a bot is refused.
- `tally(state)`: the game's own lines for the tally, from a finished game;
  `tallyBegun(options)`: lines from every game begun, finished or not, by
  its table's options (games begun on each variant).
- `preferences`, `options`: the preferences panel's settings and the
  host's table choices (above).

## The server

One Node process per game, on its own port, run from source with `tsx` as
a sandboxed systemd service, behind Caddy `handle` blocks that route `/api`
and `/ws` before the static files. Rooms in memory are evicted after a week
idle and come back from disk on the next visit. Rate limits sit on the doors
a stranger can knock on (rooms, seats, talk, the desk), and a looser one
on a seat's own actions, each a ledger line; a table of friends never nears
them. An address holds at most twenty sockets, a socket that stops
answering pings is closed, and a request has seconds, not minutes, to
arrive. A seat token is minted once, sent once, and compared by
hash in constant time ever after; a shared link carries none. Room codes
are checked against the disk as well as memory, so an evicted room's code
is never reissued over its ledger. A game may refuse a move with a reason
(`validate`), and the player sees the reason.

## Operations

Every game gets the same tools, installed by `deploy.sh` on every deploy:

- `deploy/deploy.sh <ip>`: checks, tests, build, **the determinism gate**
  (every production ledger replayed with the engine about to ship and
  compared with the server; a DIFFERS or REFUSED stops the deploy), rsync,
  restart. Hashed assets from the previous week stay so an open page can
  still fetch what it was built against.
- `<slug>-visitors.sh` (skill `<slug>-visitors`): who is here now, who came
  today, every room opened and how far it got. Names seated for the first
  time are marked NEW.
- `<slug>-reseat.sh ROOM [SEAT]`: who sits at a table and when each last
  acted; with a seat, a new token for a player locked out, as a link.
- `<slug>-pulse.sh` (skill `<slug>-pulse`): service health, journal errors,
  the rollup's last week, the backup's last word, the box's vitals.
- `<slug>-rollup.sh` nightly at 00:12 UTC: one JSON line a day of counts,
  no addresses. `<slug>-backup.sh` nightly at 07:23 UTC: rclone to the
  shared Space, mirror plus dated snapshots pruned after 90 days. On the
  shared host the hall's `hall-nightly.sh` runs both for every game and
  checks in with Sentry Crons once for all, so a missed night is noticed.
- The reports desk (skill `<slug>-reports`): `pull-reports.sh` mirrors the
  desk to the Desktop with a digest; `report-reply.sh <ip> <id> <status>
  "text"` answers with `resolved`, `by-design` or `open`. A fix goes live
  before its reply goes out.
- Sentry: one project per game; `sentry-slack-alert.sh` routes every issue
  to `#<slug>-notifications`, run once by the keeper with their own token.
- `KEEPER` and `KEEPER_TZ` in the service unit name the keeper a table may
  call and where they sleep.

## The look

Each game chooses its own palette and typeface in `src/app.css`; the
components name only the tokens. Keep the page quiet: one accent, no
animation that does not answer an action, the game itself as the hero. No
emoji in the interface; the words do the work. Phone width first: a sticky
bar for the move if the board runs long, lists that shorten, gutters of
16px, no horizontal scroll.

## The voice

Every game speaks in its own world. Wherever the page tells a player what
happened, it gives an image as well as the fact: not "Corwin takes 5 from
a fireball" but "A fireball bursts over Corwin, for 5". The fact stays
exact and whole (the number, the duration, who is affected, the turn a
thing will happen), and the image carries it.

- **The chronicle** is where the voice matters most. Each move, blow,
  enchantment, arrival and death gets its own picture. Something that
  unfolds over turns (an illness, a siege, a fuse) is told a turn at a
  time, names the turn it ends on when it begins, and warns on the last
  turn anything can be done about it.
- **The rest of the surround** speaks the same way: the lobby, the guide,
  the status lines, the verdict. Plain words for controls and buttons;
  the images belong to what happens, not to what you press.
- **Our own words.** An older implementation's prose is a guide to the
  tone, never a source to copy.
- **Plain chrome.** Headings, tabs, captions and notes say what is there
  in ordinary words. The images live in what happens, not in the labels
  around it. The patterns readers take as generated text are listed under
  "Writing for players" below.
- **Changing text is not changing rules.** Chronicle wording is not part
  of the ledger, so it ships without a rules revision; the deploy gate
  compares outcomes, not sentences. A test that pins a phrase should pin
  the fact inside it.

## Writing for players

Players have learned the habits of generated text, and once they spot one
they trust the rest of the page less. Every game built from this kit has
needed an editing pass to remove them. Write without them from the start,
and read each new page against this list before it ships.

- **One semicolon is fine. A semicolon in every paragraph is a tell.** Use
  two sentences, or join with "and" or "so". Lists of rules may keep their
  semicolons.
- **No statement, colon, explanation.** "The table is yours: seat a bot,
  invite a friend" becomes "You can seat a bot or invite a friend". The
  same goes for a label and a colon at the start of a line ("Shieldwall:
  two or more pieces..."), and for a heading that ends in a colon.
- **No headings made of "The" and an abstract noun** ("The game", "The
  tally"). Name what is there ("Origins", "Games so far").
- **A button may name its action and its cost** ("Absorb: take 2
  instead"). The colon rule is for sentences, not for controls.
- **No clipped fragments in threes** as a habit. "Four towers. One crown.
  No second chances." Write one sentence instead. A game may keep one
  deliberate triplet as its tagline when the energy is the point, as
  Wiz-War's "Steal treasure. Blast through walls. Outwit your friends."
  does. Once is a choice, and a pattern is a tell.
- **No closing aphorisms.** A paragraph ends on its last fact, not on a line
  meant to sound wise ("This is the whole art", "Nothing is unlocked by it
  and nothing is withheld without it").
- **No "X, not Y" flourishes** ("drawn, not borrowed"). Say what it is.
- **No page that talks about itself.** Avoid "This page walks the room", "the
  page keeps watch" and "a walk through the page". Describe the game and
  what the player does.
- **No spaced em dashes** in the interface, and few anywhere.
- **Nothing copied from another game that is untrue here.** Text carried over
  from the kit or a sibling game is the most common source of errors. Look
  for hidden information in a game with none, points in a game without
  them, a bot's name from another game, and "both" at a table that seats
  more than two. Read every inherited line as if it were new.
- **Every claim checked.** A date, a count, "only" or "never" is checked
  against the source and the engine. "A thousand years before chess" was
  wrong, and so was "a shield is the only defence".
- **Words for any table size.** Use "every player" for what each does on a
  turn, and plurals for opponents ("your rivals"), unless the game seats
  exactly two.
- **Some words are load-bearing.** Before rewording, grep for the string.
  An end-of-game reason written to a ledger line is matched later by exact
  text, and rewording one needs a migration. The client may match a server
  error by its words. Replay screenshots kept as goldens include captions,
  and stored shares carry event text. A bot's lines may be told apart by
  their shape, and the examples it gives players must still parse.
- **Bots should not share scaffolding.** When each personality recites the
  same clause ("I keep out of X, you keep out of Y, through 1903"), they
  stop sounding like people. Give each its own way of saying the terms, and
  avoid assistant phrasing ("Certainly", "Happy to help", "I hope you
  understand").

The game's own voice (above) is not on this list. The chronicle's images,
the in-world names, the keeper and a game's whimsy are what the editing
passes protect. The template's plain lines are a default. A game may say
the same thing in its own voice ("The gallery listens. The host has not
opened its mouth.") as long as the fact survives.

## The move

- **Every history reads top to bottom**, oldest first, and scrolls to the
  newest line: the ledger, the chronicle, table talk. That is the order
  people already know from chat.
- **The move and its button stay together and in view.** Whatever the
  player has chosen this turn, what it will do, any warning, and the
  button that commits it sit in one row that does not scroll away.
- **Warn before, not after.** A move that is legal but wasted is pointed
  out while it can still be changed, and left legal.
- **A move can be typed** when the game's moves have short names, with
  Enter to commit and Backspace to take one back.

## Things learned the hard way

- Caddy's `try_files` rewrites `/api` before `reverse_proxy` unless the
  proxy sits in its own `handle` block first.
- `npm install --omit=optional` on the droplet breaks Vite; the server
  carries its own small `package.json` and installs only that.
- A dynamic `/join/[code]` route must set `prerender = false`.
- Two tabs on one origin share a seat; test a second player from
  `127.0.0.1` against `localhost` (Vite needs `--host`).
- Svelte proxies do not `structuredClone`: hand the engine `$state.snapshot`.
- Old saved states lack fields added later: backfill on load, and bump the
  save version when the shape changes.
- A token typed into a session lands in the transcript; run token-bearing
  scripts yourself and revoke afterwards.