domma-cms 1.8.30 → 1.8.32

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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.
+
 ## [1.8.30] - 2026-10-20
 
 - Redraw the St George's Day castle and 26 seasonal details across the patron saints, Halloween and Valentine's Day celebrations. The CMS renderer uses the same shaded flowers, grouped plants, heritage props and characters as [domma-celebrate 1.5.0](https://github.com/pinpointzero73/domma-celebrate/releases/tag/v1.5.0).

package/docs/DommaFeatures.md

@@ -39,8 +39,8 @@ Code was treated as the truth. Where docs disagree with it, the disagreement is
 | `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. |
 | `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.8.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. |
-| `docs-pro` | paid | 0.8.1 | 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) and protected public links (expiry date, password). Adds to Docs. |
+| `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. |
 | `email-pro` | paid | 0.9.0 | Full mail: read, write, send and search, over a synchronised store. Search, threads, rules, scheduled sends, snooze and vacation replies need MongoDB; without it, reading, filing and sending still work. |
 | `feedback` | free | 1.1.4 | Tell Domma what is broken, missing or good - straight from your admin - and see what became of it: seen, planned, in progress, done, with Domma's reply. |
 | `garage` | paid | 1.4.3 | UK vehicle management with DVLA API lookup, save vehicles, and search history. |
@@ -1842,7 +1842,7 @@ A safe way to move collections between file storage and MongoDB, take backups, r
 
 ### Docs (`docs`)
 
-Tier: paid (closed source) · Version: 2.6.0 · Requires: no MongoDB (documents are JSON files under the plugin's `data/`); no `minCmsVersion` declared · Uses: `blog` (Send to a new blog post)
+Tier: paid (closed source) · Version: 2.13.1 · Requires: no MongoDB (documents are JSON files under the plugin's `data/`, PDF files beside them); optional `pdfjs-dist` (CMS optionalDependency) to read the text inside PDFs; no `minCmsVersion` declared · Uses: `blog` (Send to a new blog post)
 
 A document editor inside the admin. Documents are private until shared: share with people as Viewers or Editors, or publish a read-only public link. Import and export Markdown, HTML and text, print to PDF, and send a document on as a draft page, a draft blog post or an email. One person edits at a time; everyone else reads and sees who is editing.
 
@@ -1867,6 +1867,7 @@ A document editor inside the admin. Documents are private until shared: share wi
 - Saving a document accepts up to 5 MB (2.4.0) - documents with built-in pictures were refused at Fastify's 1 MB default.
 - **Suggester** share role (2.5.0, with Docs Pro): reads and suggests changes; without Docs Pro a Suggester is a Viewer. Pending suggestions are kept out of the public link, downloads, print, email and Send to by Docs itself; editors may take over editing from a Suggester.
 - Ready-made templates from an add-on (2.6.0) are listed in Templates after your own, marked with their category, read only.
+- **PDF documents** (2.13.0): New > Upload a PDF, Import or drop - up to 20 MB, kept whole (never rewritten) and shown in the browser's own PDF viewer; the text inside is read (pdfjs-dist, in a worker with a time budget) for search and the card excerpt; a PDF with JavaScript, Launch actions, attached files, rich media or XFA is refused with the reason, looking inside its compressed streams too. Shared, starred, filed, linked (the public page frames the PDF, Download PDF), emailed (attached), copied and trashed like any document; **Replace the PDF…** keeps the old file in Version history (download or restore). Add-ons declare the document kinds they understand (`kinds`, default HTML only).
 - `contentPaths: ["data"]` - documents are carried across plugin updates.
 
 **Where:** Admin sidebar "Docs" (book-open icon) -> `#/plugins/docs`; documents at `#/plugins/docs/d/<id>`; public links at `/docs/s/<token>`; settings under the banner cog; guide under **Documentation > Plugins > Docs**.
@@ -1891,7 +1892,7 @@ Tier: paid (closed source) · Version: 0.8.0 · Requires: `docs` 2.6+ (2.8+ for
 
 - **Cloud copies** (0.2.0): copies of your own documents (one folder and its folders, or all; never Trash) in **Google Drive** (scope `drive.file` - only its own files), **OneDrive** (its own app folder, `Files.ReadWrite.AppFolder`), **Dropbox** (App folder) or **S3 / S3-compatible** (Amazon S3, Cloudflare R2, Backblaze B2, Wasabi, MinIO; own SigV4 signing, no SDK) as Markdown, HTML, text and/or PDF, in folders matching your Docs folders under a folder you name. **Every save** (90 s after you stop editing), **Nightly** (after 2am, what changed) or **By hand**; unchanged documents are not sent again; copies stay when a document is trashed or deleted. Each customer makes their own app with the provider - a step-by-step guide per provider in the form, with the site's exact redirect address and a Copy button; Connect opens a sign-in window. Secrets encrypted at rest (AES-256-GCM keyed from JWT_SECRET), never sent back (Saved / last 4 of a key). Cards with state, what/as/when/where, Copy now, Test, See why; menu: Copy everything again, Connect again, Settings, Switch off, Remove. Editor chip ("Copied to Drive 10:42" / failed) and **Copy to the cloud now**. Failures notify the owner (source `docs-pro:cloud`), resolved when copying works again. Permission `cloud.use`, granted to `admin`.
 
-- **Signatures** (0.3.0): **Request signatures…** on a document's menu - people (name + email, up to 20), optional signing order, message, deadline (7-90 days). The document is frozen with a SHA-256 fingerprint. Each signer is emailed their own link (in turn when ordered) to `/docs/sign/<token>`: the document, consent to sign electronically, typed or drawn signature, or decline with a reason. When everyone has signed, the signed copy - document, signatures and a certificate page (who, when, IP, browser, fingerprints, the full record) - is emailed to everyone as a PDF (web page when the server has no Chrome). **Signatures** place: each request's state, signers, Remind (once an hour each), Cancel, downloads, record. Editor chip ("Signed by 1 of 2"). Notifications to the sender (source `docs-pro:signing`). Needs the site's SMTP; a simple electronic signature (not for deeds/wills). Permission `signing.send`, granted to `admin`.
+- **Signatures** (0.3.0): **Request signatures…** on a document's menu - people (name + email, up to 20), optional signing order, message, deadline (7-90 days). The document is frozen with a SHA-256 fingerprint. Each signer is emailed their own link (in turn when ordered) to `/docs/sign/<token>`: the document, consent to sign electronically, typed or drawn signature, or decline with a reason. When everyone has signed, the signed copy - document, signatures and a certificate page (who, when, IP, browser, fingerprints, the full record) - is emailed to everyone as a PDF (web page when the server has no Chrome). **Signatures** place: each request's state, signers, Remind (once an hour each), Cancel, downloads, record. Editor chip ("Signed by 1 of 2"). Notifications to the sender (source `docs-pro:signing`). Needs the site's SMTP; a simple electronic signature (not for deeds/wills). Permission `signing.send`, granted to `admin`. **Signing a PDF** (0.10.0, Docs 2.13): the sender places Signature / Initials / Date / Name / Text boxes on the pages (a modal drawing them with pdf.js, served from the CMS's own copy at `/docs-pro/pdfjs/`), the file is frozen beside the request, the signer's page draws the pages with their boxes and their mark goes into every box; the signed PDF is the file with every box drawn in by pdf-lib (optional CMS dependency) plus a certificate page - no web-page copy. Spaces, Word, comments, suggestions and merge fields do not apply to PDF documents; cloud copies send the file. **PDF tools** (0.11.0): in a PDF document's menu - Fill in the form (the PDF's own AcroForm: text, ticks, choices; from a contact; Save and lock flattens), Annotate (text, date, tick, cross, highlight, stamp, picture, drawing placed on the pages), Pages (turn, remove, reorder), Take pages out (a new document), Add another PDF (merge) - every change a new version in Docs' History.
 - **Protected links** (0.3.0): an expiry date (the whole day counts) and/or a password (scrypt) on a document's public link, set in its Share panel. Expired -> a clear 410 page; password -> a form, then a 12-hour cookie for that link only; a new password asks everyone again; downloads are gated too. Kept with the document across new link addresses.
 - **Word files** (0.4.0): `.docx` in New > Import and drag-and-drop (15 MB) - headings, alignment, bold/italic/underline/strike, super/subscript, highlight, links, nested lists with numbering that carries on, quotes, code, tables with merged cells, pictures (PNG/JPEG/GIF to the Media library as `doc-…`, or up to 2 MB built in without Media rights); tracked changes accepted. **Download as Word (.docx)** on Home's and the editor's document menu. Own zip and XML code (no dependencies); hostile files capped per part, by node count and one import at a time; output validated against the Office 2019 schema.
 - **Merge fields** (0.4.0): **Insert a field** (contact name, first name, company, job title, email, phone, address, website, reference, today's date, your own `{{field}}`) and **Fill in the fields…** - search your Contacts or type values; makes a filled-in copy of your own (the original keeps its fields); values escaped, fields in the title too. A template with fields asks for them as soon as it is used and fills the new document in place.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "1.8.30",
+  "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",
@@ -98,6 +98,8 @@
   },
   "optionalDependencies": {
     "mongodb": "^6.21.0",
+    "pdf-lib": "^1.17.1",
+    "pdfjs-dist": "^6.4.299",
     "puppeteer-core": "^25.11.0"
   },
   "devDependencies": {

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};
+    }
+}