Saved game presets: one-tap 'Family Night' / 'Party' setups

[mholzi]

Priority: high · touches UI

Setup now spans packs, difficulty/auto, rounds, power-ups, wager, lightning, TTS entities, lights, music — a long form every session, and hosts repeat the same 2-3 configs. Named server-side presets collapse setup to one tap and cut time-to-first-question (the README's "10 seconds from scan to playing").

Sketch: presets.json store next to analytics.json (same persistence pattern); CRUD endpoints in server/views.py (admin-token-gated); a preset chip row above the admin setup form with "Save current as preset"; ship 2 built-ins (Quick Game, Full Party).

---

Surfaced by QuizifyBot Fable deep-dive #2 (2026-07-05) on main aef632b. Deduped against existing open/closed issues; genuinely new findings only.

[mholzi]

Scope correction — the built-ins half of this ticket has since shipped.

The sketch above ends with "ship 2 built-ins (Quick Game, Full Party)". That part is done, and then some. admin.js now carries a _PRESETS table with four bundles plus a custom card, rendered as one-tap preset cards in the setup form:

Card	Rounds	Difficulty	Timer
Schnellrunde / Quick round	5	easy	20 s
Klassiker / Classic	10	medium	30 s
Mit Kindern / With kids	5	easy	180 s
Marathon	20	hard	45 s
Eigene / Custom	—	—	—

The "With kids" card landed in #509 (2026-07-21) off the back of #506. So a host opening setup today already gets one-tap configs and does not re-pick rounds/difficulty/timer every session — the original pain point in the first paragraph is largely addressed.

What is still genuinely open is the half that the built-ins cannot cover: host-defined presets. That is the part worth building, and it is the part the sketch describes as presets.json + admin-token-gated CRUD:

• persist named presets server-side (presets.json next to analytics.json, same runtime.data_dir pattern — see analytics.py:73)
• CRUD endpoints in server/views.py, admin-token-gated
• a "Save current setup as preset" affordance plus delete/rename on the existing preset-card row
• decide whether a saved preset also captures the settings the built-ins deliberately leave alone: packs/topics, power-ups, wager, lightning, TTS entities, lights, music. _matchingPreset() currently returns null as soon as the host picks a non-mixed category, so a saved preset that includes topics needs that matcher reworked, not just extended.

Leaving this open with the narrowed scope. Anyone picking it up should build only the save-your-own layer — the built-in bundles already exist and re-adding them would produce a duplicate row.

[mholzi]

Spec — saved game presets

Written against main after the 1.7.0-RC2 tag. No code yet; this fixes the shape so the build is mechanical.

Where they live: on the server, not in the browser

presets.json in runtime.data_dir, written through the same tiny atomic-JSON pattern as server/token_store.py (analytics.py already puts its own file there the same way). Not localStorage: a host who saves "Familienabend" on the living-room tablet must find it on their phone, and a browser-local store silently fails that the first time a second device is used.

The file is a list, not a map, so ordering is the host's:

{
  "version": 1,
  "presets": [
    {
      "id": "p_7f3a",
      "name": "Familienabend",
      "rounds": 5,
      "difficulty": "easy",
      "timer": 180,
      "lightning": false,
      "category": "mixed",
      "packs": ["geographie", "tiere-natur"],
      "created": "2026-08-11T06:00:00Z"
    }
  ]
}

API

/api/quizify/presets, registered in ROUTES next to the other /api/quizify/* entries:

Method	Behaviour
GET	list
POST	create (server assigns id) or update when id is present
DELETE	remove by id

All three behind _is_admin_authenticated (#356). Presets hold nothing secret, but they change what the game will do, and these routes carry no HA auth — so the gate is about writes, not privacy. GET is gated too, for the plain reason that an ungated read would be the odd one out.

Caps: 20 presets, name ≤ 40 characters, both enforced server-side. A JSON file that grows without limit is a slow leak, and the chip row stops being one-tap long before 20.

The part that will actually break: _matchingPreset()

admin.js currently decides the screen's label by walking the four hard-coded bundles in _PRESETS and falling back to "Eigene". Leave that untouched and a freshly saved preset reads as "Eigene" the moment it is re-applied — the host sees their own preset not being recognised and has no way to tell why.

So:

• _matchingPreset() iterates built-ins and loaded custom presets, built-ins first (a custom preset that happens to equal "Klassiker" should still say Klassiker).
• The comparison gains packs. Today the function returns null unless selectedCategory === 'mixed', precisely because a preset could not express a pack choice; a custom preset can, so a pack-specific preset must be matchable.
• _applyPreset() is reused as-is for rounds/difficulty/timer/lightning, then applies the pack selection.

One constraint inherited from #506 and worth restating because it bites silently: a preset's timer must be one of the #timer-chips values. _applyPreset calls _activateChip, which highlights nothing for an unknown value — the setting applies but the UI shows no active chip. Either restrict saving to the chip values, or add the chip. The former is smaller and is what this spec assumes.

UI

A chip row above the existing preset cards: the custom presets, then "Aktuelles speichern". Saving asks for a name inline (no modal). Each custom chip carries a small remove affordance; deletion asks for confirmation, since a preset is not recoverable.

The four built-in cards stay exactly as they are. This feature adds a row; it does not restyle the setup screen.

Deliberately out of scope

TTS and House Plays Along settings are not part of a preset. They belong to devices — which speaker, which lights — not to the shape of an evening, and they already persist separately. A preset that silently repoints your speaker would surprise more than it helps. If that turns out to be wanted, it is a second issue with its own reasoning.

Also out: sharing/exporting presets, and per-user presets. There is one host.

Tests

• Round-trip through the store: create, list, update, delete, and a reload from disk.
• The caps: the 21st preset and a 41-character name are both refused.
• The gate: all three verbs answer 401 without a token.
• _matchingPreset() over the shipped JS text: it must reference the custom list, not only _PRESETS — the pin that stops the "shows Eigene" regression from coming back silently.
• A saved preset's timer is one of the #timer-chips values.

[mholzi]

UI locked — variant A: a chip row above the mode cards

Three variants were rendered against the shipped styles.css at 390×844 (phone width, DPR 2) with the real card markup from www/admin.html, so spacing and type are production, not approximation. Markus picked A.

For the record, why the other two lost:

• B — custom presets as further cards in the same list. The meta line wraps to two lines as soon as the pack count is in it, and with the spec's cap of 20 presets the mode chooser turns into a long scroll. It also blurs the line between what ships and what the host made.
• C — a collapsible "Meine Presets" box. Names the group nicely and folds away, but it costs the most vertical space when open and puts one more tap between the host and the four cards they use most.

What A is

A horizontally scrollable row of chips above the untouched four mode cards, under a small Meine Presets label.

Modus wählen
MEINE PRESETS
[ Familienabend × ] [ Party mit Anna × ] [ Kurz vo…      ← scrolls
┌──────────────────────────────┐
│ ⚡ Schnellrunde   5 · Leicht  │   the four built-in cards,
├──────────────────────────────┤   unchanged
│ 🧠 Klassiker  (active)        │
└──────────────────────────────┘

• The row scrolls sideways and the last visible chip is deliberately clipped. That is the affordance — a chip cut by the viewport edge reads as "there is more", where a tidy fit reads as "that's all". No arrows, no dots.
• Active state matches the cards' is-active treatment (coral fill, dark ink) so "selected" means one thing on this screen.
• + Aktuelles speichern is the last chip, dashed outline, always at the end of the row. Tapping it asks for a name inline — no modal.
• × on each custom chip deletes, with a confirm, because a preset cannot be recovered.
• The four built-in cards do not change — not their markup, not their order, not their styling. This feature adds a row above them and nothing else.

Constraints carried into the build

• Touch target ≥ 44 px on chips including the ×. The mockup used 40 px; raise it. The × needs its own hit area, or deleting becomes a lottery next to selecting.
• No horizontal page overflow. All three variants measured scrollWidth === 390; keep it that way — the row scrolls inside itself, the page does not.
• Empty state: with no saved presets, the label and row are hidden entirely and only + Aktuelles speichern shows. A labelled empty row is furniture that explains nothing.
• The row renders from the GET /api/quizify/presets payload described above; the built-in cards stay client-side as they are today.

Mockups were rendered locally rather than committed. If they are wanted on the issue for future reference, they need a design/ branch to be linkable — say the word.