domma-cms 1.8.31 → 1.8.32

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "1.8.31",
+  "version": "1.8.32",
   "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-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}

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

@@ -0,0 +1,241 @@
+/**
+ * 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, a small element builder, and the Plays screen
+ * (every go at one game, its leaderboard, hide / remove / reset).
+ *
+ * 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 and loading, 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(() => ({}))
+    ]).then(([tk, chrome, loading]) => ({
+        viewLifetime: tk.viewLifetime || (() => ({add() {}, reset() {}})),
+        addBannerAction: chrome.addBannerAction || (() => null),
+        whileLoading: loading.whileLoading || ((slot, p) => (typeof p === 'function' ? p() : p)),
+        SHAPES: loading.SHAPES || {}
+    }));
+    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 and toasts 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;');
+
+/**
+ * A DOM element. `props`: className, text, html (static markup only - never
+ * user data), dataset, on<Event> handlers, anything else as an attribute
+ * (false/null leave it off). Children: elements, strings (as text) or falsy.
+ */
+export function h(tag, props = {}, ...children) {
+    const el = document.createElement(tag);
+    for (const [k, v] of Object.entries(props || {})) {
+        if (v === false || v == null) continue;
+        if (k === 'className') el.className = v;
+        else if (k === 'text') el.textContent = v;
+        else if (k === 'html') el.innerHTML = v;
+        else if (k === 'dataset') Object.assign(el.dataset, v);
+        else if (k.startsWith('on') && typeof v === 'function') el.addEventListener(k.slice(2).toLowerCase(), v);
+        else if (k === 'value') el.value = v;
+        else if (k === 'checked') el.checked = Boolean(v);
+        else el.setAttribute(k, 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;
+}
+
+/** An icon span, drawn by I.scan on the container afterwards. */
+export const icon = (name, size = 14) => h('span', {'data-icon': name, 'data-icon-size': size, 'aria-hidden': 'true'});
+
+/** A labelled field: label, control, optional hint. */
+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);
+}
+
+/** A switch (checkbox) with its words beside it. */
+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);
+}
+
+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. */
+export function bannerTrail(container, parts) {
+    const name = container.querySelector('.dm-plugin-banner-name');
+    if (!name) return;
+    name.textContent = '';
+    parts.forEach((p, i) => {
+        if (i) name.append(h('span', {className: 'dm-plugin-banner-sep', 'aria-hidden': 'true', text: '›'}));
+        name.append(i < parts.length - 1 ? h('a', {className: 'dm-plugin-banner-parent', href: p.href || '#', text: p.text}) : document.createTextNode(p.text));
+    });
+}
+
+const STATUS_LABEL = {playing: 'Playing', finished: 'Finished', abandoned: 'Left unfinished', timeout: 'Out of time'};
+
+/**
+ * The Plays screen for one game.
+ *
+ * @param {HTMLElement} root
+ * @param {{api: string, gameId: string, title: string, order: 'score'|'time', canManage: boolean, back: string, refreshBadge?: () => void}} opts
+ *   `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 = () => {}}) {
+    const k = await loadKit();
+    root.innerHTML = '';
+    const slot = h('div', {className: 'gma-note dm-loading-slot', text: 'Loading…'});
+    root.append(slot);
+    let data;
+    try {
+        data = await k.whileLoading(slot, request('GET', `${api}${base}/${encodeURIComponent(gameId)}/plays`), k.SHAPES.table);
+    } catch (err) {
+        root.innerHTML = '';
+        root.append(h('p', {className: 'gma-error', text: `The plays could not load: ${errText(err)}`}));
+        return;
+    }
+    root.innerHTML = '';
+
+    const showScore = order === 'score';
+    const draw = () => {
+        root.innerHTML = '';
+        const finished = data.plays.filter(p => p.status === 'finished');
+        const bar = h('div', {className: 'gma-bar'},
+            h('a', {className: 'btn btn-sm btn-ghost', href: back}, icon('arrow-left'), ' All'),
+            h('span', {className: 'gma-spacer'}),
+            canManage && data.plays.length ? h('button', {type: 'button', className: 'btn btn-sm btn-outline gma-danger-text', onClick: reset}, icon('refresh-cw'), ' Reset the leaderboard…') : null);
+
+        const stats = h('div', {className: 'gma-stats'},
+            stat('Plays', data.plays.length), stat('Finished', finished.length),
+            showScore ? stat('Best score', finished.reduce((m, p) => Math.max(m, p.score || 0), 0)) : null,
+            stat('Fastest', finished.length ? fmtDuration(Math.min(...finished.map(p => p.timeMs || 0))) : '-'));
+
+        const boardCard = h('section', {className: 'gma-card'},
+            h('h3', {className: 'gma-h', text: 'Leaderboard (all time, best go per name)'}),
+            data.board.length
+                ? h('ol', {className: 'gma-board'}, data.board.slice(0, 20).map(r => h('li', {},
+                    h('span', {className: 'gma-rank', text: ordinal(r.rank)}), h('span', {className: 'gma-name', text: r.name}),
+                    showScore ? h('strong', {text: `${r.score}`}) : null, h('span', {className: 'gma-muted', text: fmtDuration(r.timeMs)}))))
+                : h('p', {className: 'gma-muted', text: 'Nobody has finished yet.'}));
+
+        const rows = data.plays.map(p => h('tr', {className: p.hidden ? 'is-hidden' : ''},
+            h('td', {}, h('strong', {text: p.name}), p.hidden ? h('span', {className: 'gma-chip', text: 'Hidden'}) : null),
+            h('td', {text: STATUS_LABEL[p.status] || p.status}),
+            showScore ? h('td', {className: 'gma-num', text: p.status === 'finished' ? `${p.score} / ${p.maxScore}` : '-'}) : null,
+            h('td', {className: 'gma-num', text: p.status === 'finished' ? fmtDuration(p.timeMs) : '-'}),
+            h('td', {text: fmtDateTime(p.startedAt)}),
+            canManage ? h('td', {className: 'gma-actions'},
+                h('button', {type: 'button', className: 'btn btn-xs btn-ghost', title: p.hidden ? 'Show on the leaderboard' : 'Hide from the leaderboard',
+                    onClick: () => hide(p)}, icon(p.hidden ? 'eye' : 'eye-off'), p.hidden ? ' Show' : ' Hide'),
+                h('button', {type: 'button', className: 'btn btn-xs btn-ghost gma-danger-text', title: 'Delete this play', onClick: () => remove(p)}, icon('trash'))) : null));
+
+        const table = data.plays.length
+            ? h('div', {className: 'gma-table-wrap'}, h('table', {className: 'gma-table'},
+                h('thead', {}, h('tr', {}, h('th', {text: 'Name'}), h('th', {text: 'State'}), showScore ? h('th', {className: 'gma-num', text: 'Score'}) : null,
+                    h('th', {className: 'gma-num', text: 'Time'}), h('th', {text: 'Started'}), canManage ? h('th', {}) : null)),
+                h('tbody', {}, rows)))
+            : h('p', {className: 'gma-muted', text: 'No plays yet. Once people play, every go shows here.'});
+
+        root.append(bar, stats, h('div', {className: 'gma-two'}, h('section', {className: 'gma-card'}, h('h3', {className: 'gma-h', text: 'Every play'}), table), boardCard));
+        I.scan(root);
+    };
+
+    const stat = (label, value) => h('div', {className: 'stat-card gma-stat'}, h('div', {className: 'stat-value', text: String(value)}), h('div', {className: 'stat-label', text: label}));
+
+    async function reload() {
+        data = await request('GET', `${api}${base}/${encodeURIComponent(gameId)}/plays`);
+        draw();
+        badge();
+    }
+
+    async function hide(p) {
+        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 function remove(p) {
+        if (!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 function reset() {
+        if (!await E.confirm(`Reset the leaderboard for <strong>${esc(title)}</strong>? Every play (${data.plays.length}) is deleted. This cannot be undone.`)) return;
+        try {
+            const r = await request('DELETE', `${api}${base}/${encodeURIComponent(gameId)}/plays`);
+            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'}); }
+    }
+
+    draw();
+}
+
+/** 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() : '';
+};

package/plugins/_lib/games/http.js

@@ -0,0 +1,82 @@
+/**
+ * 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());
+
+/** `?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.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.`
+        }
+    };
+}

package/plugins/_lib/games/names.js

@@ -0,0 +1,42 @@
+/**
+ * Games - the name a player puts on the leaderboard. PURE.
+ *
+ * Names are typed by strangers and shown to everyone, so they are cleaned
+ * hard: letters (any script), digits, spaces and . ' - _ only, 2 to 24
+ * characters, and a short list of words that never go on a public board.
+ * A name is compared by its key (lower case, accents and spacing folded), so
+ * "Sam", "sam " and "SÁM" are one player for attempts and best-per-name.
+ *
+ * @module _lib/games/names
+ */
+
+export const NAME_MIN = 2;
+export const NAME_MAX = 24;
+
+/** Folded to a-z first, so leetspeak and accents do not slip past. Kept short on purpose. */
+const BLOCKED = ['fuck', 'shit', 'cunt', 'wank', 'twat', 'bitch', 'bastard', 'nigg', 'fag', 'slut', 'whore', 'rape', 'nazi', 'hitler', 'penis', 'vagina', 'dick', 'cock', 'pussy', 'arse', 'asshole', 'admin', 'moderator'];
+
+const LEET = {0: 'o', 1: 'i', 3: 'e', 4: 'a', 5: 's', 7: 't', '@': 'a', $: 's'};
+
+/** Lower case, accents gone, spacing collapsed - the identity of a name. */
+export function nameKey(name) {
+    return String(name ?? '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function blocked(name) {
+    const folded = nameKey(name).replace(/[013457@$]/g, c => LEET[c] || c).replace(/[^a-z]/g, '');
+    return BLOCKED.some(w => folded.includes(w));
+}
+
+/**
+ * @param {*} raw - what the player typed
+ * @returns {{name: string, error: string}} name is '' whenever error is set
+ */
+export function cleanPlayerName(raw) {
+    const name = String(raw ?? '').normalize('NFC').replace(/\s+/g, ' ').trim();
+    if (name.length < NAME_MIN) return {name: '', error: `Please type a name of at least ${NAME_MIN} characters.`};
+    if (name.length > NAME_MAX) return {name: '', error: `Please keep your name to ${NAME_MAX} characters or fewer.`};
+    if (!/^[\p{L}\p{N}][\p{L}\p{N} .'_-]*$/u.test(name)) return {name: '', error: 'Letters, numbers, spaces and . \' - _ only, please.'};
+    if (blocked(name)) return {name: '', error: 'Please choose another name.'};
+    return {name, error: ''};
+}

package/plugins/_lib/games/plays.js

@@ -0,0 +1,155 @@
+/**
+ * Games - the plays of one game Tool, in a collection of its own
+ * (`quiz-plays`, `crossword-plays`).
+ *
+ * A play is one person's go at one game: who (the name they typed), when it
+ * started and finished BY THE SERVER'S CLOCK, the score, and the game's own
+ * state (`state` - which question they are on, penalties...). Its `token` is
+ * the player's key to it: handed over once, at the start, and asked for on
+ * every move, so nobody can answer for someone else's play. The token never
+ * leaves the server again - not to the board, not to the admin.
+ *
+ * Writes go one at a time (`withLock`), so two answers sent at once cannot
+ * both be marked.
+ *
+ * @module _lib/games/plays
+ */
+
+import {randomBytes, timingSafeEqual} from 'node:crypto';
+import {createEntry, deleteEntry, getEntry, listEntries, updateEntry} from '../../../server/services/collections.js';
+import {nameKey} from './names.js';
+import {placeOf, rankPlays} from './ranking.js';
+import {ABANDON_MS} from './timing.js';
+
+const flat = (e) => (e ? {id: e.id, ...e.data} : null);
+
+export class PlayStore {
+    /**
+     * @param {string} slug - the plays collection
+     * @param {{order?: 'score'|'time'}} [opts] - how the board is ordered
+     */
+    constructor(slug, {order = 'score'} = {}) {
+        this.slug = slug;
+        this.order = order;
+        this.queue = Promise.resolve();
+        this.cache = null;
+    }
+
+    /** Run `fn` after every write before it has finished. */
+    withLock(fn) {
+        const run = this.queue.then(fn, fn);
+        this.queue = run.catch(() => {});
+        return run;
+    }
+
+    async all() {
+        if (!this.cache) {
+            this.cache = listEntries(this.slug, {limit: 100000})
+                .then(r => (r.entries || []).map(flat))
+                .catch(() => []);
+        }
+        return this.cache;
+    }
+
+    forget() { this.cache = null; }
+
+    async forGame(gameId) {
+        return (await this.all()).filter(p => p.gameId === gameId);
+    }
+
+    async get(id) {
+        return flat(await getEntry(this.slug, String(id)).catch(() => null));
+    }
+
+    /** The play, if `token` is its key; else null. */
+    async open(id, token) {
+        const play = await this.get(id);
+        if (!play || !PlayStore.tokenOk(play.token, token)) return null;
+        return play;
+    }
+
+    static tokenOk(stored, given) {
+        const a = Buffer.from(String(stored || ''));
+        const b = Buffer.from(String(given || ''));
+        return a.length > 0 && a.length === b.length && timingSafeEqual(a, b);
+    }
+
+    /** How many goes this name has had at this game (any state but hidden ones the admin removed). */
+    async attemptsBy(gameId, name) {
+        const key = nameKey(name);
+        return (await this.forGame(gameId)).filter(p => p.nameKey === key).length;
+    }
+
+    /**
+     * @param {{gameId: string, name: string, maxScore?: number, state?: object, userId?: string}} play
+     * @returns {Promise<object>} the play, token included - for the player, once
+     */
+    async start({gameId, name, maxScore = 0, state = {}, userId = ''}) {
+        return this.withLock(async () => {
+            const now = new Date().toISOString();
+            const saved = await createEntry(this.slug, {
+                gameId, name, nameKey: nameKey(name), userId,
+                status: 'playing', startedAt: now, finishedAt: '', timeMs: 0, score: 0, maxScore,
+                hidden: false, token: randomBytes(24).toString('base64url'), state
+            }, {source: 'public'});
+            this.forget();
+            return flat(saved);
+        });
+    }
+
+    /** Re-read the play inside the lock, let `fn` change it, write it back. `fn` returning null writes nothing. */
+    async change(id, fn) {
+        return this.withLock(async () => {
+            const current = await this.get(id);
+            if (!current) return null;
+            const next = await fn(structuredClone(current));
+            if (!next) return current;
+            const {id: _id, ...data} = next;
+            const saved = flat(await updateEntry(this.slug, id, data));
+            this.forget();
+            return saved;
+        });
+    }
+
+    /** Finished now: the time is the server's, plus any penalty the game added. */
+    static finish(play, {score = play.score, penaltyMs = 0, status = 'finished', now = Date.now()} = {}) {
+        play.status = status;
+        play.finishedAt = new Date(now).toISOString();
+        play.score = score;
+        play.timeMs = Math.max(0, now - Date.parse(play.startedAt)) + Math.max(0, penaltyMs);
+        return play;
+    }
+
+    async setHidden(id, hidden) {
+        return this.change(id, (p) => { p.hidden = hidden === true; return p; });
+    }
+
+    async remove(id) {
+        await this.withLock(() => deleteEntry(this.slug, String(id)));
+        this.forget();
+    }
+
+    /** Every play of a game gone: a fresh board. */
+    async reset(gameId) {
+        const mine = await this.forGame(gameId);
+        await this.withLock(async () => { for (const p of mine) await deleteEntry(this.slug, p.id).catch(() => {}); });
+        this.forget();
+        return mine.length;
+    }
+
+    async board(gameId, {period = 'all', limit = 10} = {}) {
+        return rankPlays(await this.forGame(gameId), {order: this.order, period, limit});
+    }
+
+    async placeOf(play, period = 'all') {
+        return placeOf(play, await this.forGame(play.gameId), {order: this.order, period});
+    }
+
+    /** A play as the admin sees it: everything but the key and the game's inner state. */
+    static adminView(p) {
+        if (!p) return p;
+        const {token, state, ...rest} = p;
+        const open = rest.status === 'playing' && Date.now() - Date.parse(rest.startedAt) > ABANDON_MS;
+        return {...rest, status: open ? 'abandoned' : rest.status};
+    }
+}

package/plugins/_lib/games/ranking.js

@@ -0,0 +1,68 @@
+/**
+ * Games - who is top. PURE: plays in, leaderboard rows out.
+ *
+ * Only finished, visible plays count. A player (by name key) appears once,
+ * with their best play, so one person replaying cannot fill the board. Order:
+ *
+ *   'score'  higher score first, then the faster time, then whoever got there first (Quiz)
+ *   'time'   the faster time first, then whoever got there first (Crossword - every finisher solved it)
+ *
+ * Periods are calendar ones in the server's own day: today, this week (from
+ * Monday), this month, all time.
+ *
+ * @module _lib/games/ranking
+ */
+
+import {cleanPeriod} from '../public/games/format.js';
+
+/** The instant a period starts, or 0 for all time. */
+export function periodStart(period, now = Date.now()) {
+    const d = new Date(now);
+    d.setHours(0, 0, 0, 0);
+    switch (cleanPeriod(period)) {
+        case 'today': return d.getTime();
+        case 'week': d.setDate(d.getDate() - ((d.getDay() + 6) % 7)); return d.getTime();
+        case 'month': d.setDate(1); return d.getTime();
+        default: return 0;
+    }
+}
+
+/** a before b? - the board's order. */
+export function comparePlays(a, b, order = 'score') {
+    if (order === 'score' && (b.score ?? 0) !== (a.score ?? 0)) return (b.score ?? 0) - (a.score ?? 0);
+    if ((a.timeMs ?? Infinity) !== (b.timeMs ?? Infinity)) return (a.timeMs ?? Infinity) - (b.timeMs ?? Infinity);
+    return String(a.finishedAt).localeCompare(String(b.finishedAt));
+}
+
+/**
+ * @param {object[]} plays - {id, name, nameKey, status, hidden, score, timeMs, finishedAt}
+ * @param {{order?: 'score'|'time', period?: string, now?: number, limit?: number, bestPerName?: boolean}} [opts]
+ * @returns {{id: string, rank: number, name: string, score: number, timeMs: number, finishedAt: string}[]}
+ */
+export function rankPlays(plays, {order = 'score', period = 'all', now = Date.now(), limit = 10, bestPerName = true} = {}) {
+    const from = periodStart(period, now);
+    const counted = (plays || []).filter(p => p && p.status === 'finished' && p.hidden !== true
+        && Date.parse(p.finishedAt) >= from).sort((a, b) => comparePlays(a, b, order));
+    const seen = new Set();
+    const rows = [];
+    for (const p of counted) {
+        const key = p.nameKey || String(p.name).toLowerCase();
+        if (bestPerName && seen.has(key)) continue;
+        seen.add(key);
+        rows.push({id: p.id, rank: 0, name: p.name, score: p.score ?? 0, timeMs: p.timeMs ?? 0, finishedAt: p.finishedAt});
+    }
+    // Equal score and time share a rank ("=2nd"); the next is placed after them.
+    rows.forEach((r, i) => {
+        const prev = rows[i - 1];
+        r.rank = prev && (order === 'time' || prev.score === r.score) && prev.timeMs === r.timeMs ? prev.rank : i + 1;
+    });
+    return Math.max(0, Number(limit) || 0) ? rows.slice(0, Math.max(1, Math.min(100, Number(limit)))) : rows;
+}
+
+/** Where one play stands on its board for a period, counting it even when it is not the player's best. */
+export function placeOf(play, plays, {order = 'score', period = 'all', now = Date.now()} = {}) {
+    if (!play || play.status !== 'finished') return 0;
+    const others = (plays || []).filter(p => p.id !== play.id);
+    const board = rankPlays([...others, play], {order, period, now, limit: 0, bestPerName: false});
+    return board.find(r => r.id === play.id)?.rank || 0;
+}

package/plugins/_lib/games/timing.js

@@ -0,0 +1,27 @@
+/**
+ * Games - how the server keeps time. PURE.
+ *
+ * Every clock that decides anything is the server's: when a play started, when
+ * a question was put in front of the player, when the answer arrived. The
+ * browser's countdown is only a picture of these. A little grace covers the
+ * network, so an answer sent in the last second still counts.
+ *
+ * @module _lib/games/timing
+ */
+
+/** A late answer is still on time within this much, for the network. */
+export const GRACE_MS = 3000;
+
+/** A play still open this long after it started counts as abandoned. */
+export const ABANDON_MS = 24 * 3600 * 1000;
+
+/** Milliseconds left before `startIso + limitMs`, never below 0; null when there is no limit. */
+export function leftOf(startIso, limitMs, now = Date.now()) {
+    if (!(limitMs > 0)) return null;
+    return Math.max(0, Date.parse(startIso) + limitMs - now);
+}
+
+/** Past `startIso + limitMs` by more than the grace? */
+export function overdue(startIso, limitMs, now = Date.now()) {
+    return limitMs > 0 && now > Date.parse(startIso) + limitMs + GRACE_MS;
+}