Games stage 1: settings, round engine, question kit, awards (MAD-783)

[madeofpendletonwool]

Stage 1 of Phase 10, music party games (MAD-783). This adds the foundation every later game plugs into. Design notes are in docs/adr/0015-party-games.md. The issue said ADR 0014, but backups already has that number.

MAD-784: Games setting

• rooms.Settings.Games (settings version 2), off by default. The levels are off, recap, ambient, rounds and gamenight, and each level sets the defaults for the per-game switches, frequency, scores, guests, TV only and breaks per hour.
• A request can leave out any field and it takes the new level's default (RoomGamesChange), so sending only a level resets the fine controls.
• New startRounds permission (Everyone or Owner, Owner by default).
• Web: a Games section in room settings. The level is one control with a plain-words line, the fine controls sit under Adjust, and each device can mute games for itself (stored in localStorage).

MAD-785: Round engine

• New games package. One round at a time per room, in memory: announce → open → reveal → done. Rounds start from the frequency setting or from Start a round in the room menu.
• With a beat map, answers open on a section start and the reveal lands on a section boundary or downbeat. Without one, fixed timers. Lyric questions close when the singer reaches the line.
• POST /rooms/{id}/games/rounds/{roundId}/answers takes choice, number or free text. Free text matches fuzzily (case, punctuation, accents, "the", bracketed asides, small typos). Answers can change until the round closes and are scored by when the server received them.
• Results are saved in game_rounds and game_answers, and tonight's scores honour the off / private / board setting.
• New game.round and game.scores events. A hidden song becomes a "Mystery song" for everyone but the speaker (matched by device on the socket). Lyrics, liner notes and artwork are refused with hidden_for_round while hidden.
• Web: a phone answer sheet over now playing. Ambient rounds start folded, and muted or TV-only rounds show as a chip. The big screen gets an overlay with the question, countdown ring, who answered, the reveal and the leaderboard.

MAD-786: Question kit

• New quiz package, pure. It takes song facts (liner notes, lyrics, beat map, music graph) and returns year, cover, credit, sample and next-line questions.
• Wrong answers come from the song's neighbourhood: similar artists' top songs, tonight's credits, and years that aren't adjacent to the answer or to each other.
• A wrong answer is never also right (co-writers, covers sharing a title). Each question gets a rough difficulty.
• Ready lists the games a song can carry. Facts are gathered a few songs ahead in rooms that play games.
• Liner notes now carry structured coverOf, samples and sampledBy.

MAD-787: Recap awards

• New awards package, pure, with the 11 awards from the issue. At most six per night, at most two per person, ties skipped, and autopilot never wins.
• Awards are computed when the night ends and stored on the night. They show on the crown moment (phone and big screen) and in recaps.

Worth reviewing

• Some trivia already runs. Stage 1 can run year, liner-notes, sample and beat-the-singer questions through the generic sheet and overlay. Stage 2 adds each game's own UI.
• Music-pausing games are held back. Finish the lyric and Name that tune need the music paused, so the engine won't start them until a later stage teaches it to pause and resume.
• The spec change renames some enum constants. New enums in the OpenAPI spec made oapi-codegen prefix every enum constant with its type name (e.g. httpapi.Private → httpapi.RoomVisibilityPrivate). Only tests used the old names.
• Hiding is best effort on clients. The server stops new fetches of hidden lyrics, notes and artwork. The web app also hides anything it had already loaded before the round started.

Testing

• go test -race ./... and golangci-lint are clean. New tests cover the settings levels, the quiz fixtures, awards, the engine lifecycle and scoring, and an end-to-end games API test.
• pnpm typecheck, pnpm lint, pnpm test and pnpm build are clean, with new tests in lib/games.test.ts.
• Not yet tried in a live room with real music data.

🤖 Generated with Claude Code