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), your reports to the keeper, and about this game — a labor of love.

• 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 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.

• 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 in the blog repo; both are hand-kept.

• 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 nothing is unlocked by it and nothing withheld 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.

• 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.

The engine

• Pure and deterministic: create(names, seed, rules) 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.
• 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.

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); a table of friends never nears them. 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>-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. Both check in with Sentry Crons 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.

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.