domma-cms 1.8.31 → 1.8.33

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.8.33] - 2026-10-21
+
+- **Test a quiz or a crossword from its Tool.** A **Test** button in the editor, on every quiz and crossword in the list, and on the Plays screen plays the game right there in the admin, exactly as your players see it - the same clock, marking and screens - whatever its status, so a draft can be tried before anyone sees it. A test go never reaches the leaderboard, the Plays list, the goes-per-name limit, the sidebar badge or a notification, and it tells you where it would have come. Quiz and Crossword 1.1.0.
+- **Quiz and Crossword screens rebuilt.** Both Tools' list, editor and Plays screens now run on domma-reactive: right-click (or ⋮, or Shift+F10) a quiz or crossword for everything you can do with it, drag questions by their grip to reorder them, Ctrl+S saves, and help is beside the settings. The crossword preview grid keeps black squares black under dark themes.
+
+## [1.8.32] - 2026-10-20
+
+- **Quiz and Crossword, two new free Tools under Tools > Games.** Visitors play by typing a name, and the server keeps the time and does the marking, so the answers never reach the browser before they are given.
+  - **Quiz:** questions with one answer, several answers, true or false, or a typed answer (case, accents and "the" do not matter). Time limits per question and for the whole quiz, shuffling, a random draw from a question bank, and answers shown after each question, at the end, or never. Put one on a page with `[quiz id="…" /]`.
+  - **Crossword:** type the answers and clues and the grid is laid out for you, with a live preview and "Another layout". Checking and wrong guesses cost time. Put one on a page with `[crossword id="…" /]`.
+  - **Both:** leaderboards for today, this week, this month and all time (each name's best go), `[quiz-leaderboard]` and `[crossword-leaderboard]` to show one anywhere, a Plays screen to hide, delete or reset, a sidebar badge, and a notification when someone takes the top spot. Both arrive switched off.
+
 ## [1.8.31] - 2026-10-20
 
 - Add `pdfjs-dist` and `pdf-lib` as optional dependencies, for the Docs Tool's PDF documents (Docs 2.13: a PDF kept as it is, searchable inside, shown in the browser's viewer) and Docs Pro's PDF signing and PDF tools (0.10 and 0.11: boxes placed on the pages, forms filled in, marks drawn, pages turned, removed, reordered, taken out and merged). A server without them still runs Docs; those features say so and stand aside.

package/docs/DommaFeatures.md

@@ -38,6 +38,7 @@ Code was treated as the truth. Where docs disagree with it, the disagreement is
 | `calendar` | paid | 1.15.4 | Events calendar - month, day and list views, online meetings as a video call on your site (with the call's chat kept, and Add people during the call), call anyone now from a contact or an email, all-day and recurring events, sharing with people and roles, RSVPs and an iCal feed. |
 | `campaigns-pro` | paid | 1.0.2 | Marketing campaigns, one paid Tool: compose a message, send it to an audience imported from Contacts (shared with Surveys), schedule sends, attach an offer that closes by a date or a claim limit. Opens and clicks (cookieless), links tagged for Analytics, a linked Shop discount code, send a survey as a campaign, follow-up sequences, resend to non-openers, A/B subject tests, and a version-1 stats feed other Tools read. |
 | `contacts-pro` | paid | 0.12.0 | Contacts, with more to them: your own custom fields, birthdays and ages with the ones coming up and a reminder in the sidebar, and groups with their own emblem and colours. Share a contact, several, or a whole group with people or roles - to view, or to edit. Call a contact now on a video call on your site. Works over the same contacts as the built-in Tool, so nothing moves and nothing is lost. |
+| `crossword` | free | 1.1.0 | Crosswords on your site: type the answers and clues and the grid lays itself out (live preview, Another layout). Players type a name and race the server's clock, checks and wrong guesses cost time, fastest solvers on a leaderboard. Test it from the Tool - a test go never reaches the board. |
 | `data-transfer` | paid | 1.3.3 | Move collections between file and MongoDB storage, back them up and restore them (all or some, merged or replaced) - keeping every entry's id - and clone them (cloned entries get new ids, so references stay unambiguous). Every restore and transfer takes a safety snapshot first. |
 | `docs` | paid | 2.13.1 | Document editor: Home and editor screens, sharing with Viewers/Editors, public links, import/export, send to page/blog/email, edit lock, Trash, version history, templates. PDF documents (2.13): a PDF kept as it is, shown in the browser's viewer, searchable inside, versioned on replace. |
 | `docs-pro` | paid | 0.11.0 | Domma Spaces (publish a Docs folder at `/spaces` with a Kindle-style reader), Cloud copies (Google Drive, OneDrive, Dropbox, S3), Signatures (emailed signing links, typed or drawn, signed copy with a certificate page; 0.10: boxes placed on a PDF document's pages, the signed PDF stamped with pdf-lib), PDF tools (0.11: fill the PDF's own form, annotate, pages) and protected public links (expiry date, password). Adds to Docs. |
@@ -50,6 +51,7 @@ Code was treated as the truth. Where docs disagree with it, the disagreement is
 | `messages` | paid | 1.7.2 | Internal user-to-user and group messaging with real-time delivery and video calls (what is typed in a call lands in the conversation; ring another team member into a call) - conversations you can archive, mark unread and search, drafts kept per conversation, attachments, and an unread badge in the sidebar. |
 | `mongodb-adapter` | paid | 1.0.2 | Provision a dedicated MongoDB database per site. Credentials are managed centrally by the manager. |
 | `onboard-pro` | paid | 1.0.1 | Onboarding journeys, one paid Tool: read/form/details/manual steps, a personal link per person, signature steps through Docs Pro, admin-approved account steps (never an administrator), due dates, automatic nudges and auto-enrolment from a contact group, countersigned steps, waive-with-a-reason, and a funnel showing where people stop. |
+| `quiz` | free | 1.1.0 | Timed quizzes on your site: one or several right answers, true or false, or a typed answer, marked by the server so answers never reach the browser early. Name-only players, leaderboards by day, week, month and all time. Test it from the Tool - a test go never reaches the board. |
 | `security` | free | 1.1.3 | Keeps a Domma CMS site safe: a health check of what is weak and how to fix it, sign-in lockout after repeated wrong passwords, password rules, a log of every sign-in, and blocking of the scanners that probe every site for WordPress, .env files and the like. |
 | `security-pro` | paid | 1.3.2 | Everything in Security, plus two-factor sign-in (authenticator apps, recovery codes, required per role), a firewall that bans scanners for longer each time they return, per-route rate limits, country rules for the admin, breached-password checks and every signed-in session in one place. |
 | `seo-pro` | paid | 0.6.2 | More for SEO: Google Search Console in the admin (with your own Google client) - searches, clicks, positions and where to win more; structured data for rich results (FAQ, how-to, product, event, local business); links worth adding between pages, pages competing for one search, readability, near duplicates and image checks; every title and description in one grid, and moving an old site's addresses across as redirects; a not-found log with one-click redirects; a scheduled check of every link; SEO history and notices. Adds to SEO, which is built into Domma CMS (0.90 and later). |
@@ -2400,9 +2402,19 @@ Tier: paid (closed source) · Version: 0.4.0 · Requires: nothing; no MongoDB (w
 
 **Where:** Admin sidebar "Sheets" (`#/plugins/sheets`).
 
+### Quiz (`quiz`) and Crossword (`crossword`)
+
+Tier: free, bundled in the engine, off on arrival · Version: 1.1.0 each (needs Domma CMS 1.8.33 for the games library) · Sidebar: Tools > Games
+
+**1.0.0 (CMS 1.8.32)** - see the 1.8.32 changelog: server-kept time and marking, name-only players with a play token, leaderboards by period (best go per name), Plays screen (hide, delete, reset), sidebar badge, top-spot notifications, `[quiz]`/`[crossword]` and `-leaderboard` shortcodes.
+
+**1.1.0 - Test from the Tool, domma-reactive admin.** **Test** (editor, list rows, Plays screen; `#/plugins/quiz/test/<id>`, `#/plugins/crossword/test/<id>`) mounts the real public player in the admin and plays the SAVED game whatever its status or dates ("Save and test" when there are unsaved changes). The play is stored with `test: true` and played through the ordinary `/public/play` routes, but `PlayStore` leaves it out of boards, places, goes-per-name, the admin's plays list and counts and the sidebar badge; it never notifies; the next test of the game clears it. The result says where it would have come (`wouldPlace`). Routes: `GET/POST /api/plugins/quiz/quizzes/:id/test`, `GET/POST /api/plugins/crossword/puzzles/:id/test` (manage permission). Both admin screens are rebuilt on domma-reactive through the shared kit (`plugins/_lib/admin/games/kit.js`: `mountScreen`, `wireRows`, `sortableRows`, `saveKey`, `playsScreen`, `testScreen`): list rows with a context menu (right-click, ⋮, Shift+F10), questions dragged by a grip to reorder, Ctrl+S, help popovers; the crossword preview grid uses fixed ink and paper colours.
+
+**Where:** Tools > Games > Quiz (`#/plugins/quiz`) and Crossword (`#/plugins/crossword`).
+
 ### Other plugin directories
 
-No other directories exist in `dcms-marketplace/plugins/` beyond the 29 plugins above and `_lib`. `_lib` is not a plugin (skipped by plugin discovery): it holds the shared mail core used by Mail Reader and Email Pro, plus shared `dataStore.js` and `schemaSync.js`.
+No other directories exist in `dcms-marketplace/plugins/` beyond the plugins above and `_lib`. `_lib` is not a plugin (skipped by plugin discovery): it holds the shared mail core used by Mail Reader and Email Pro, plus shared `dataStore.js` and `schemaSync.js`.
 
 ### Reserved slugs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "1.8.31",
+  "version": "1.8.33",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",

package/plugins/_lib/admin/games/games.css

@@ -0,0 +1 @@
+.gma{--gma-line: var(--dm-border, rgba(128, 128, 128, .3));--gma-soft: color-mix(in srgb, var(--dm-text) 5%, transparent);display:flex;flex-direction:column;gap:1rem;min-width:0}.gma [hidden]{display:none!important}.gma-screen{display:flex;flex-direction:column;gap:1rem;min-width:0}.gma-bar{display:flex;flex-wrap:wrap;gap:.5rem;align-items:center}.gma-spacer{flex:1}.gma-muted{color:var(--dm-text-muted)}.gma-note{margin:0;font-size:var(--dm-text-sm);color:var(--dm-text-muted)}.gma-error{color:var(--dm-danger);margin:0}.gma-danger-text{color:var(--dm-danger)!important}.gma-h{margin:0 0 .5rem;font-size:1rem;font-weight:600}.gma-card{border:1px solid var(--gma-line);border-radius:var(--dm-radius-md, 8px);padding:1rem;background:var(--dm-surface, transparent);display:flex;flex-direction:column;gap:.75rem;min-width:0}.gma-two{display:grid;grid-template-columns:minmax(0,2fr) minmax(16rem,1fr);gap:1rem;align-items:start}@media(max-width:1000px){.gma-two{grid-template-columns:minmax(0,1fr)}}.gma-chip{display:inline-flex;align-items:center;font-size:var(--dm-text-xs);font-weight:600;padding:.1rem .55rem;border-radius:999px;white-space:nowrap;background:color-mix(in srgb,var(--dm-text) 9%,transparent);color:var(--dm-text-muted);margin-left:.4rem}.gma-chip.is-success{background:color-mix(in srgb,var(--dm-success) 15%,transparent);color:var(--dm-success)}.gma-chip.is-warning{background:color-mix(in srgb,var(--dm-warning) 16%,transparent);color:color-mix(in srgb,var(--dm-warning) 55%,var(--dm-text))}.gma-chip.is-primary{background:color-mix(in srgb,var(--dm-primary) 14%,transparent);color:var(--dm-primary)}.gma-list{display:flex;flex-direction:column;gap:.5rem}.gma-row{display:flex;flex-wrap:wrap;align-items:center;gap:.75rem;padding:.75rem 1rem;border:1px solid var(--gma-line);border-radius:var(--dm-radius-md, 8px);background:var(--dm-surface, transparent)}.gma-row:hover{border-color:color-mix(in srgb,var(--dm-primary) 45%,var(--gma-line))}.gma-row-main{flex:1 1 16rem;min-width:0;display:flex;flex-direction:column;gap:.15rem}.gma-row-main a{font-weight:600;color:var(--dm-text);text-decoration:none}.gma-row-main a:hover{color:var(--dm-primary)}.gma-row-main small{color:var(--dm-text-muted)}.gma-row-actions{display:flex;flex-wrap:wrap;gap:.25rem}.gma-empty{display:flex;flex-direction:column;align-items:center;gap:.5rem;text-align:center;padding:2.5rem 1rem;color:var(--dm-text-muted)}.gma-empty strong{color:var(--dm-text)}.gma-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(14rem,1fr));gap:.25rem 1rem}.gma-field{margin:0;min-width:0}.gma-toggle{display:inline-flex;align-items:center;gap:.5rem;cursor:pointer;font-weight:500}.gma-shortcode{display:flex;gap:.5rem;align-items:center;flex-wrap:wrap}.gma-shortcode code{padding:.3rem .55rem;border-radius:6px;background:var(--gma-soft);font-size:var(--dm-text-sm)}.gma-save{position:sticky;bottom:0;z-index:5;display:flex;gap:.5rem;align-items:center;flex-wrap:wrap;padding:.75rem 1rem;border:1px solid var(--gma-line);border-radius:var(--dm-radius-md, 8px);background:var(--dm-background, var(--dm-surface))}.gma-save .is-dirty{color:color-mix(in srgb,var(--dm-warning) 60%,var(--dm-text));font-size:var(--dm-text-sm)}.gma-stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(9rem,1fr));gap:.75rem}.gma-stat{padding:.75rem 1rem}.gma-table-wrap{overflow-x:auto}.gma-table{width:100%;border-collapse:collapse;font-size:var(--dm-text-sm)}.gma-table th,.gma-table td{padding:.45rem .5rem;border-bottom:1px solid var(--gma-line);text-align:left;vertical-align:middle}.gma-table th{font-weight:600;color:var(--dm-text-muted)}.gma-table tr.is-hidden td{opacity:.55}.gma-num{text-align:right!important;font-variant-numeric:tabular-nums;white-space:nowrap}.gma-actions{white-space:nowrap;text-align:right!important}.gma-board{margin:0;padding:0;list-style:none;display:flex;flex-direction:column}.gma-board li{display:grid;grid-template-columns:2.6rem 1fr auto auto;gap:.5rem;padding:.35rem 0;border-bottom:1px solid var(--gma-line);align-items:center}.gma-board li:last-child{border-bottom:0}.gma-rank{font-weight:700}.gma-name{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.gma-row{cursor:pointer}.gma-row:focus-visible{outline:2px solid var(--dm-primary);outline-offset:2px}.gma-kebab{border:0;background:transparent;color:var(--dm-text-muted);font-size:1.1rem;line-height:1;padding:.25rem .5rem;border-radius:6px;cursor:pointer}.gma-kebab:hover{background:var(--gma-soft);color:var(--dm-text)}.gma-quiet{opacity:.6}.gma-quiet:hover{opacity:1}.gma-grip{cursor:grab;color:var(--dm-text-muted);display:inline-flex;padding:.2rem;touch-action:none}.gma-grip:active{cursor:grabbing}.gma-test-stage{border:1px dashed var(--gma-line);border-radius:var(--dm-radius-md, 8px);padding:.5rem 1rem;background:var(--gma-soft)}.gma-test-stage .gm-app{margin:.5rem auto}

package/plugins/_lib/admin/games/kit.js

@@ -0,0 +1,446 @@
+/**
+ * Games admin - what the Quiz and Crossword screens share: the admin's helpers
+ * (loaded at run time; a plugin never imports admin/ statically - the updater
+ * replaces it), API calls, mounting a domma-reactive screen, list rows with a
+ * context menu, drag to reorder, the Plays screen (every go at one game, its
+ * leaderboard, hide / remove / reset) and the Test screen (the real player,
+ * playing a test go that never reaches a board).
+ *
+ * Every screen is domma-reactive: a template string (in the JS - a templateUrl
+ * goes through _.render, which eats the {{ }} of a data-each row), observables,
+ * and one M.applyBindings, disposed when the view goes.
+ *
+ * Served from /plugins/_lib/admin/games/kit.js; its stylesheet is games.css
+ * beside it, listed in each Tool's manifest `admin.css`.
+ *
+ * @module _lib/admin/games/kit
+ */
+
+import {fmtDateTime} from '/plugins/_lib/admin/ui/dates.js';
+import {fmtDuration, ordinal} from '/plugins/_lib/public/games/format.js';
+
+export {fmtDateTime, fmtDuration, ordinal};
+
+let kit = null;
+/** tool-kit, plugin-chrome, loading and help popovers, once, with stand-ins for an older admin. */
+export function loadKit() {
+    kit ??= Promise.all([
+        import('/admin/js/lib/tool-kit.js').catch(() => ({})),
+        import('/admin/js/lib/plugin-chrome.js').catch(() => ({})),
+        import('/admin/js/lib/loading.js').catch(() => ({})),
+        import('/admin/js/lib/help-popover.js').catch(() => ({}))
+    ]).then(([tk, chrome, loading, help]) => ({
+        viewLifetime: tk.viewLifetime || (() => ({add() {}, reset() {}})),
+        openMenuAt: tk.openMenuAt || ((el) => {
+            const r = el.getBoundingClientRect();
+            el.dispatchEvent(new MouseEvent('contextmenu', {bubbles: true, cancelable: true, clientX: r.left, clientY: r.bottom, view: window}));
+        }),
+        addBannerAction: chrome.addBannerAction || (() => null),
+        whileLoading: loading.whileLoading || ((slot, p) => (typeof p === 'function' ? p() : p)),
+        SHAPES: loading.SHAPES || {},
+        helpPopovers: help.helpPopovers || (() => () => {})
+    }));
+    return kit;
+}
+
+let requester = null;
+/**
+ * A call to the API through the admin's apiRequest (it attaches the token and
+ * refreshes it on a 401, and keeps `err.status` / `err.body` on an error); H is
+ * the stand-in on an older admin.
+ */
+export function request(method, path, body) {
+    requester ??= import('/admin/js/api.js').then(m => m.apiRequest).catch(() => null);
+    return requester.then(fn => {
+        if (fn) return fn(path, {method, ...(body !== undefined ? {body: JSON.stringify(body)} : {})});
+        const url = `/api${path}`;
+        return method === 'GET' ? H.get(url) : method === 'DELETE' ? H.delete(url) : H[method.toLowerCase()](url, body);
+    });
+}
+
+export const errText = (err) => err?.body?.error || err?.message || String(err);
+
+/** E.confirm, toasts and templates render HTML: user text goes in escaped. */
+export const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/** An icon for a template: drawn by I.scan. Never put a data-bind-* on it (I.scan swaps the span for an svg). */
+export const ico = (name, size = 14) => `<span data-icon="${name}" data-icon-size="${size}" aria-hidden="true"></span>`;
+
+/**
+ * Put `html` in `root` and bind `model` to it: the one M.applyBindings of a
+ * screen. `before(el)` runs first (take element refs and wire help popovers
+ * there - data-if lifts elements out). Icons are drawn after binding, and again
+ * whenever `rescan` (observables) change, so rows added later get theirs.
+ *
+ * @returns {HTMLElement} the screen's element; everything is disposed through `lifetime`
+ */
+export function mountScreen(root, {html, model, lifetime, k, className = '', before = null, rescan = []}) {
+    root.innerHTML = '';
+    const el = document.createElement('div');
+    el.className = `gma-screen ${className}`.trim();
+    el.innerHTML = html;
+    root.append(el);
+    const disposeHelp = k?.helpPopovers ? k.helpPopovers(el, {position: 'bottom'}) : () => {};
+    before?.(el);
+    const bindings = M.applyBindings(model, el, {methods: model});
+    const scan = () => { if (el.isConnected && typeof I !== 'undefined') I.scan(el); };
+    scan();
+    const stops = rescan.map(obs => M.effect(() => { obs.value; queueMicrotask(scan); }));
+    lifetime?.add(() => { stops.forEach(s => s?.()); bindings?.dispose?.(); disposeHelp?.(); });
+    return el;
+}
+
+/**
+ * Rows with one menu and three ways in: right-click, the ⋮ button, Shift+F10.
+ * A click (or Enter) on the row does `main`. `items(id)` lists the menu.
+ */
+export function wireRows(list, {items, main, k, lifetime, match = '.gma-row'}) {
+    const menu = typeof E !== 'undefined' && E.contextMenu
+        ? E.contextMenu(list, {cursor: 'glyph', match, inherit: false, density: 'compact', items: (row) => items(row.dataset.id, row)})
+        : null;
+    const onClick = (e) => {
+        const row = e.target.closest(match);
+        if (!row) return;
+        if (e.target.closest('.gma-kebab')) { e.stopPropagation(); k.openMenuAt(row); return; }
+        if (e.target.closest('a, button, input, [data-stop]')) return;
+        main(row.dataset.id, row);
+    };
+    const onKey = (e) => {
+        const row = e.target.closest(match);
+        if (!row) return;
+        if (e.key === 'F10' && e.shiftKey) { e.preventDefault(); k.openMenuAt(row); }
+        else if (e.key === 'Enter' && e.target === row) { e.preventDefault(); main(row.dataset.id, row); }
+        else if ((e.key === 'ArrowDown' || e.key === 'ArrowUp') && e.target === row) {
+            e.preventDefault();
+            const rows = [...list.querySelectorAll(match)];
+            rows[rows.indexOf(row) + (e.key === 'ArrowDown' ? 1 : -1)]?.focus();
+        }
+    };
+    list.addEventListener('click', onClick);
+    list.addEventListener('keydown', onKey);
+    lifetime?.add(() => { list.removeEventListener('click', onClick); list.removeEventListener('keydown', onKey); menu?.destroy?.(); });
+}
+
+/**
+ * Drag to reorder the rows of a data-each list (by their grip). E.sortable in
+ * live mode moves the row element itself, but a data-each row sits between a
+ * pair of comment anchors the reconciler places it by - so the row is put back
+ * where it was first, and the move is made in the data (`onMove(from, to)`),
+ * which redraws the list.
+ */
+export function sortableRows(list, {items, handle, key = 'data-id', onMove, lifetime}) {
+    if (typeof E === 'undefined' || typeof E.sortable !== 'function') return;
+    let at = null;
+    const restore = (item) => {
+        if (!at) return;
+        at.parent.insertBefore(item, at.next?.parentNode === at.parent ? at.next : null);
+        at = null;
+    };
+    const drag = E.sortable(list, {
+        items, handle, key,
+        // Alt+arrows would move the row without onStart, so it could not be put back by its anchors.
+        keyboard: false,
+        onStart: ({item}) => { at = {parent: item.parentNode, next: item.nextSibling}; },
+        onEnd: ({item}) => restore(item),
+        onSort: ({item, from, to}) => { restore(item); if (from !== to) onMove(from, to); }
+    });
+    lifetime?.add(() => drag?.destroy?.());
+}
+
+/** Ctrl+S (Cmd+S) runs `save` while the screen is up. Captured: app.js has a global Ctrl+S of its own. */
+export function saveKey(save, here, lifetime) {
+    const onKey = (e) => {
+        if (!(e.ctrlKey || e.metaKey) || e.key !== 's' || !here()) return;
+        e.preventDefault();
+        e.stopImmediatePropagation();
+        save();
+    };
+    document.addEventListener('keydown', onKey, true);
+    lifetime?.add(() => document.removeEventListener('keydown', onKey, true));
+}
+
+export async function copyText(text, done = 'Copied') {
+    try {
+        if (typeof _ !== 'undefined' && typeof _.copyToClipboard === 'function') await _.copyToClipboard(text);
+        else await navigator.clipboard.writeText(text);
+        E.toast(done, {type: 'success'});
+    } catch {
+        E.toast('Could not copy. Select the text and copy it yourself.', {type: 'warning'});
+    }
+}
+
+/** The sidebar re-asks a Tool's badge. */
+export function refreshBadge(url) {
+    try { window.dispatchEvent(new CustomEvent('dm:sidebar-count', {detail: {url}})); } catch { /* no sidebar */ }
+}
+
+/** "Quiz › Capitals" in the plugin banner (the chrome's, outside the screen's bindings). */
+export function bannerTrail(container, parts) {
+    const name = container.querySelector('.dm-plugin-banner-name');
+    if (!name) return;
+    name.innerHTML = parts.map((p, i) => (i ? '<span class="dm-plugin-banner-sep" aria-hidden="true">›</span>' : '')
+        + (i < parts.length - 1 ? `<a class="dm-plugin-banner-parent" href="${esc(p.href || '#')}">${esc(p.text)}</a>` : esc(p.text))).join('');
+}
+
+/** A loading note while `promise` runs (the admin's skeleton where it has one). */
+export async function loading(root, promise, k, shape = 'rows') {
+    root.innerHTML = '<div class="gma-note dm-loading-slot">Loading…</div>';
+    return k.whileLoading(root.firstElementChild, promise, k.SHAPES[shape]);
+}
+
+/** A screen that could not load: the reason, and the way back. */
+export function failed(root, text, back = null) {
+    root.innerHTML = `<p class="gma-error">${esc(text)}</p>${back ? `<p><a href="${esc(back.href)}">${esc(back.text)}</a></p>` : ''}`;
+}
+
+// ---- Plays ---------------------------------------------------------------------------
+
+const STATUS_LABEL = {playing: 'Playing', finished: 'Finished', abandoned: 'Left unfinished', timeout: 'Out of time'};
+
+const PLAYS_HTML = `
+<div class="gma-bar">
+  <a class="btn btn-sm btn-ghost" data-bind-href="back">${ico('arrow-left')} All</a>
+  <a class="btn btn-sm btn-ghost" data-bind-href="testHref" hidden data-bind-hidden="!testHref">${ico('play')} Test it</a>
+  <span class="gma-spacer"></span>
+  <button type="button" class="btn btn-sm btn-outline gma-danger-text" hidden data-bind-hidden="!canManage || !rows.value.length"
+    data-on-click="reset">${ico('refresh-cw')} Reset the leaderboard…</button>
+</div>
+<div class="gma-stats">
+  <div class="stat-card gma-stat"><div class="stat-value" data-bind-text="stats.value.plays"></div><div class="stat-label">Plays</div></div>
+  <div class="stat-card gma-stat"><div class="stat-value" data-bind-text="stats.value.finished"></div><div class="stat-label">Finished</div></div>
+  <div class="stat-card gma-stat" hidden data-bind-hidden="!showScore"><div class="stat-value" data-bind-text="stats.value.best"></div><div class="stat-label">Best score</div></div>
+  <div class="stat-card gma-stat"><div class="stat-value" data-bind-text="stats.value.fastest"></div><div class="stat-label">Fastest</div></div>
+</div>
+<div class="gma-two">
+  <section class="gma-card">
+    <h3 class="gma-h">Every play <span data-help-title="Every play" data-help="Every go anyone has had, newest first. Hide takes a play off the leaderboard without deleting it (a rude name, a known cheat); Show puts it back. Your own test goes are never listed or counted."></span></h3>
+    <p class="gma-muted" hidden data-bind-hidden="rows.value.length">No plays yet. Once people play, every go shows here.</p>
+    <div class="gma-table-wrap" hidden data-bind-hidden="!rows.value.length">
+      <table class="gma-table">
+        <thead><tr><th>Name</th><th>State</th><th class="gma-num" hidden data-bind-hidden="!showScore">Score</th><th class="gma-num">Time</th><th>Started</th><th hidden data-bind-hidden="!canManage"></th></tr></thead>
+        <tbody data-part="rows" data-each="rows.value key=id"></tbody>
+      </table>
+    </div>
+  </section>
+  <section class="gma-card">
+    <h3 class="gma-h">Leaderboard <span class="gma-muted">(all time, best go per name)</span></h3>
+    <p class="gma-muted" hidden data-bind-hidden="board.value.length">Nobody has finished yet.</p>
+    <ol class="gma-board" data-each="board.value key=id"></ol>
+  </section>
+</div>`;
+
+const PLAY_ROW = `
+<tr data-bind-class="hidden && 'is-hidden'">
+  <td><strong data-bind-text="name"></strong><span class="gma-chip" hidden data-bind-hidden="!hidden">Hidden</span></td>
+  <td data-bind-text="state"></td>
+  <td class="gma-num" hidden data-bind-hidden="!$root.showScore" data-bind-text="scoreText"></td>
+  <td class="gma-num" data-bind-text="timeText"></td>
+  <td data-bind-text="started"></td>
+  <td class="gma-actions" hidden data-bind-hidden="!$root.canManage">
+    <button type="button" class="btn btn-xs btn-ghost" data-bind-title="hidden ? 'Show on the leaderboard' : 'Hide from the leaderboard'"
+      data-on-click="$root.hide($data)"><span data-bind-text="hidden ? 'Show' : 'Hide'"></span></button>
+    <button type="button" class="btn btn-xs btn-ghost gma-quiet" title="Delete this play" aria-label="Delete this play"
+      data-on-click="$root.remove($data)">${ico('x')}</button>
+  </td>
+</tr>`;
+
+const BOARD_ROW = `
+<li><span class="gma-rank" data-bind-text="place"></span><span class="gma-name" data-bind-text="name"></span>
+  <strong hidden data-bind-hidden="!$root.showScore" data-bind-text="scoreText"></strong><span class="gma-muted" data-bind-text="timeText"></span></li>`;
+
+/**
+ * The Plays screen for one game.
+ *
+ * @param {HTMLElement} root
+ * @param {{api: string, gameId: string, title: string, order: 'score'|'time', canManage?: boolean, back: string,
+ *   base?: string, badge?: () => void, lifetime: object, testHref?: string, alive?: () => boolean}} opts
+ *   `alive` says the admin is still on this screen (checked after the load).
+ *   `api` is the Tool's base under /api ('/plugins/quiz'), `back` the list's address.
+ */
+export async function playsScreen(root, {api, gameId, title, order, canManage = true, back, base = '/quizzes', badge = () => {}, lifetime, testHref = '', alive = () => true}) {
+    const k = await loadKit();
+    const url = `${api}${base}/${encodeURIComponent(gameId)}/plays`;
+    let data;
+    try {
+        data = await loading(root, request('GET', url), k, 'table');
+    } catch (err) {
+        if (alive()) failed(root, `The plays could not load: ${errText(err)}`, {href: back, text: 'Back'});
+        return;
+    }
+    if (!alive()) return;
+
+    const showScore = order === 'score';
+    const plays = M.observable(data.plays);
+    const boardRows = M.observable(data.board);
+    const rows = M.observable([]);
+    const board = M.observable([]);
+    const stats = M.observable({});
+    const draw = () => {
+        const list = plays.peek();
+        const finished = list.filter(p => p.status === 'finished');
+        rows.value = list.map(p => ({
+            id: p.id, name: p.name, hidden: p.hidden === true, state: STATUS_LABEL[p.status] || p.status,
+            scoreText: p.status === 'finished' ? `${p.score} / ${p.maxScore}` : '-',
+            timeText: p.status === 'finished' ? fmtDuration(p.timeMs) : '-', started: fmtDateTime(p.startedAt)
+        }));
+        board.value = boardRows.peek().slice(0, 20).map(r => ({id: r.id, name: r.name, place: ordinal(r.rank), scoreText: `${r.score}`, timeText: fmtDuration(r.timeMs)}));
+        stats.value = {
+            plays: list.length, finished: finished.length,
+            best: finished.reduce((m, p) => Math.max(m, p.score || 0), 0),
+            fastest: finished.length ? fmtDuration(Math.min(...finished.map(p => p.timeMs || 0))) : '-'
+        };
+    };
+    draw();
+
+    async function reload() {
+        const next = await request('GET', url);
+        plays.value = next.plays;
+        boardRows.value = next.board;
+        draw();
+        badge();
+    }
+
+    const byId = (id) => plays.peek().find(p => p.id === id);
+    const model = {
+        back, testHref, showScore, canManage, rows, board, stats,
+        async hide(row) {
+            const p = byId(row.id);
+            if (!p) return;
+            try {
+                await request('PUT', `${api}/plays/${encodeURIComponent(p.id)}`, {hidden: !p.hidden});
+                E.toast(p.hidden ? `${p.name} is back on the leaderboard.` : `${p.name} is hidden from the leaderboard.`, {type: 'success'});
+                await reload();
+            } catch (err) { E.toast(errText(err), {type: 'error'}); }
+        },
+        async remove(row) {
+            const p = byId(row.id);
+            if (!p || !await E.confirm(`Delete <strong>${esc(p.name)}</strong>'s play? It leaves the leaderboard for good.`)) return;
+            try {
+                await request('DELETE', `${api}/plays/${encodeURIComponent(p.id)}`);
+                await reload();
+            } catch (err) { E.toast(errText(err), {type: 'error'}); }
+        },
+        async reset() {
+            if (!await E.confirm(`Reset the leaderboard for <strong>${esc(title)}</strong>? Every play (${plays.peek().length}) is deleted. This cannot be undone.`)) return;
+            try {
+                const r = await request('DELETE', url);
+                E.toast(`${r.removed} play${r.removed === 1 ? '' : 's'} deleted. The leaderboard starts again.`, {type: 'success'});
+                await reload();
+            } catch (err) { E.toast(errText(err), {type: 'error'}); }
+        }
+    };
+
+    mountScreen(root, {
+        html: PLAYS_HTML, model, lifetime, k, className: 'gma-plays', rescan: [rows],
+        before: (el) => {
+            el.querySelector('[data-part="rows"]').innerHTML = PLAY_ROW;
+            el.querySelector('.gma-board').innerHTML = BOARD_ROW;
+        }
+    });
+}
+
+// ---- Test ----------------------------------------------------------------------------
+
+const TEST_HTML = `
+<div class="gma-bar">
+  <a class="btn btn-sm btn-ghost" data-bind-href="editHref">${ico('arrow-left')} Back to the editor</a>
+  <a class="btn btn-sm btn-ghost" data-bind-href="playsHref">${ico('award')} Plays</a>
+  <span class="gma-spacer"></span>
+  <span class="gma-chip is-primary" data-bind-text="statusText"></span>
+  <span data-help-title="Testing" data-help="This is the real player, exactly as it is on a page - the same clock, the same marking, the same screens. It plays the version you last saved, even a draft or a closed one. A test go is not saved to the leaderboard or counted in the plays, and the next test clears it away."></span>
+</div>
+<p class="gma-note">Plays the saved version as your players see it. Test goes never reach the leaderboard.</p>
+<div class="gma-test-stage"><div data-part="player"></div></div>`;
+
+/**
+ * The Test screen: the Tool's own public player, mounted with test hooks that
+ * fetch the start screen and start a test play through the admin API.
+ *
+ * @param {HTMLElement} root
+ * @param {{api: string, base: string, gameId: string, player: string, appClass: string,
+ *   editHref: string, playsHref: string, statusText?: string, lifetime: object, alive?: () => boolean}} opts
+ *   `player` is the public script that exports `mount(el, {test})`.
+ */
+export async function testScreen(root, {api, base, gameId, player, appClass, editHref, playsHref, statusText = '', lifetime, alive = () => true}) {
+    const k = await loadKit();
+    let mod;
+    try {
+        mod = await loading(root, import(player), k, 'card');
+    } catch (err) {
+        if (alive()) failed(root, `The player could not load: ${errText(err)}`, {href: editHref, text: 'Back to the editor'});
+        return;
+    }
+    if (!alive()) return;
+    const url = `${api}${base}/${encodeURIComponent(gameId)}/test`;
+    let host = null;
+    mountScreen(root, {
+        html: TEST_HTML, model: {editHref, playsHref, statusText: statusText ? `${statusText} - testing` : 'Testing'},
+        lifetime, k, className: 'gma-test',
+        before: (el) => { host = el.querySelector('[data-part="player"]'); }
+    });
+    host.className = `gm-app ${appClass}`;
+    const handle = mod.mount(host, {test: {info: () => request('GET', url).then(r => r.info), start: () => request('POST', url)}});
+    lifetime?.add(() => handle?.dispose?.());
+}
+
+// ---- Dates ---------------------------------------------------------------------------
+
+/** A datetime-local value ('YYYY-MM-DDTHH:mm', the browser's time) from ISO, and back. */
+export const toLocalInput = (iso) => {
+    const t = Date.parse(iso || '');
+    if (!Number.isFinite(t)) return '';
+    const d = new Date(t);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}T${p(d.getHours())}:${p(d.getMinutes())}`;
+};
+export const fromLocalInput = (v) => {
+    const t = Date.parse(v || '');
+    return Number.isFinite(t) ? new Date(t).toISOString() : '';
+};
+
+// ---- 1.0.0 ---------------------------------------------------------------------------
+// Quiz and Crossword 1.0.0 drew their screens by hand with these. 1.1.0 is
+// domma-reactive throughout and uses none of them; they stay so a 1.0.0 copy
+// installed from the catalogue keeps working on a newer engine.
+
+/** @deprecated 1.0.0 screens only. */
+export function h(tag, props = {}, ...children) {
+    const el = document.createElement(tag);
+    for (const [key, v] of Object.entries(props || {})) {
+        if (v === false || v == null) continue;
+        if (key === 'className') el.className = v;
+        else if (key === 'text') el.textContent = v;
+        else if (key === 'html') el.innerHTML = v;
+        else if (key === 'dataset') Object.assign(el.dataset, v);
+        else if (key.startsWith('on') && typeof v === 'function') el.addEventListener(key.slice(2).toLowerCase(), v);
+        else if (key === 'value') el.value = v;
+        else if (key === 'checked') el.checked = Boolean(v);
+        else el.setAttribute(key, v === true ? '' : String(v));
+    }
+    for (const c of children.flat()) {
+        if (c == null || c === false) continue;
+        el.append(c instanceof Node ? c : document.createTextNode(String(c)));
+    }
+    return el;
+}
+
+/** @deprecated 1.0.0 screens only. */
+export const icon = (name, size = 14) => h('span', {'data-icon': name, 'data-icon-size': size, 'aria-hidden': 'true'});
+
+/** @deprecated 1.0.0 screens only. */
+export function field(label, control, hint = '', {id} = {}) {
+    const fid = id || control.id || `gmf-${Math.random().toString(36).slice(2, 8)}`;
+    control.id = fid;
+    return h('div', {className: 'form-group gma-field'},
+        h('label', {className: 'form-label', for: fid, text: label}),
+        control,
+        hint ? h('p', {className: 'form-hint', text: hint}) : null);
+}
+
+/** @deprecated 1.0.0 screens only. */
+export function toggle(label, checked, onChange, hint = '') {
+    const input = h('input', {type: 'checkbox', checked, onChange: (e) => onChange(e.target.checked)});
+    return h('div', {className: 'form-group gma-field'},
+        h('label', {className: 'gma-toggle'}, input, h('span', {text: label})),
+        hint ? h('p', {className: 'form-hint', text: hint}) : null);
+}

package/plugins/_lib/games/http.js

@@ -0,0 +1,92 @@
+/**
+ * Games - what the Quiz and Crossword routes share: the play's key from the
+ * request, the rate limits, the honeypot and the admin's view of plays.
+ *
+ * @module _lib/games/http
+ */
+
+import {cleanPeriod} from '../public/games/format.js';
+import {PlayStore} from './plays.js';
+
+/** The play's key: the `X-Play-Token` header (kept out of addresses and logs). */
+export const tokenOf = (request) => String(request.headers['x-play-token'] || request.body?.t || '').slice(0, 100);
+
+export const fail = (reply, status, error, extra = {}) => reply.code(status).send({error, ...extra});
+
+/** Route options for the public side: a rate limit per visitor's address. */
+export const limited = (max, minutes = 1) => ({config: {rateLimit: {max, timeWindow: `${minutes} minute${minutes === 1 ? '' : 's'}`}}});
+
+/**
+ * A field people never see. A bot that fills it gets nothing (a 400 with the
+ * ordinary words, so it learns nothing either).
+ */
+export const isBot = (body) => Boolean(String(body?.website ?? '').trim());
+
+/**
+ * The name on an admin's test play: their first name (or the part of the
+ * email before the @) and "(test)", within a player name's 24 characters.
+ */
+export function testerName(request) {
+    const u = request?.user || {};
+    const who = String(u.name || u.username || u.email || '').trim().split(/[\s@]/)[0];
+    return who ? `${who.slice(0, 17)} (test)` : 'Test';
+}
+
+/** `?period=&limit=` for a board, the limit within the game's own size. */
+export function boardQuery(query, size = 10) {
+    const max = Math.max(1, Math.min(100, Number(size) || 10));
+    const limit = Math.max(1, Math.min(max, Math.round(Number(query?.limit) || max)));
+    return {period: cleanPeriod(query?.period), limit};
+}
+
+/**
+ * The admin's routes for one game's plays, under `base` (e.g. '/quizzes'):
+ *   GET    <base>/:id/plays          every play of it (no keys), newest first, plus its board
+ *   DELETE <base>/:id/plays          a fresh board: every play gone
+ *   PUT    /plays/:playId            {hidden} - off or back on the board
+ *   DELETE /plays/:playId            one play gone
+ */
+export function mountPlayAdmin(fastify, {store, base, can, exists}) {
+    fastify.get(`${base}/:id/plays`, can('read'), async (request, reply) => {
+        if (!await exists(request.params.id)) return fail(reply, 404, 'Not found.');
+        const all = await store.forGame(request.params.id);
+        const list = all.map(PlayStore.adminView).sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt)));
+        return {plays: list, board: await store.board(request.params.id, {period: 'all', limit: 100})};
+    });
+
+    fastify.delete(`${base}/:id/plays`, can('manage'), async (request, reply) => {
+        if (!await exists(request.params.id)) return fail(reply, 404, 'Not found.');
+        return {removed: await store.reset(request.params.id)};
+    });
+
+    fastify.put('/plays/:playId', can('manage'), async (request, reply) => {
+        const saved = await store.setHidden(request.params.playId, request.body?.hidden === true);
+        if (!saved) return fail(reply, 404, 'Not found.');
+        return PlayStore.adminView(saved);
+    });
+
+    fastify.delete('/plays/:playId', can('manage'), async (request, reply) => {
+        if (!await store.get(request.params.playId)) return fail(reply, 404, 'Not found.');
+        await store.remove(request.params.playId);
+        return {ok: true};
+    });
+}
+
+/** The sidebar badge: plays finished today across every game of the Tool. */
+export async function todayBadge(store, noun = 'play') {
+    const start = new Date();
+    start.setHours(0, 0, 0, 0);
+    const today = (await store.all()).filter(p => p.test !== true && p.status === 'finished' && Date.parse(p.finishedAt) >= start.getTime());
+    return {
+        count: today.length,
+        label: `${today.length} ${noun}${today.length === 1 ? '' : 's'} finished today`,
+        tone: 'info',
+        inventory: true,
+        details: {
+            title: 'Finished today',
+            items: today.sort((a, b) => String(b.finishedAt).localeCompare(String(a.finishedAt))).slice(0, 8)
+                .map(p => ({text: p.name, meta: p.score != null && store.order === 'score' ? `${p.score} points` : ''})),
+            empty: `No ${noun}s finished today yet.`
+        }
+    };
+}