domma-cms 1.8.31 → 1.8.33

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,176 @@
+/**
+ * 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.
+ *
+ * A TEST play (`test: true`) is an admin trying the game from its Tool. It
+ * plays exactly like any other, but it is nobody's go: it never counts for a
+ * board, a place, the goes-per-name limit, the badge or the admin's list of
+ * plays, and the next test of the same game clears it away.
+ *
+ * @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; }
+
+    /** The real plays of a game - test plays left out. */
+    async forGame(gameId) {
+        return (await this.all()).filter(p => p.gameId === gameId && p.test !== true);
+    }
+
+    /** Every play of a game, tests included. */
+    async everyForGame(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, test?: boolean}} play
+     *   `test`: an admin trying the game - see the module comment
+     * @returns {Promise<object>} the play, token included - for the player, once
+     */
+    async start({gameId, name, maxScore = 0, state = {}, userId = '', test = false}) {
+        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, ...(test ? {test: true} : {}), token: randomBytes(24).toString('base64url'), state
+            }, {source: test ? 'admin' : '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. Answers how many real plays went. */
+    async reset(gameId) {
+        const mine = await this.everyForGame(gameId);
+        await this.withLock(async () => { for (const p of mine) await deleteEntry(this.slug, p.id).catch(() => {}); });
+        this.forget();
+        return mine.filter(p => p.test !== true).length;
+    }
+
+    /** A game's test plays gone (before the next test starts). */
+    async clearTests(gameId) {
+        const tests = (await this.everyForGame(gameId)).filter(p => p.test === true);
+        if (!tests.length) return 0;
+        await this.withLock(async () => { for (const p of tests) await deleteEntry(this.slug, p.id).catch(() => {}); });
+        this.forget();
+        return tests.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;
+}

package/plugins/_lib/public/games/format.js

@@ -0,0 +1,38 @@
+/**
+ * Games - words and numbers shared by the server and the browser (Quiz,
+ * Crossword). Served from /plugins/_lib/public/games/format.js and imported by
+ * path on the server, so it must stay free of I/O and of DOM.
+ *
+ * @module _lib/public/games/format
+ */
+
+/** "0:42", "3:05", "1:02:09" from milliseconds. Tenths only under a minute, when asked. */
+export function fmtDuration(ms, {tenths = false} = {}) {
+    const n = Math.max(0, Number(ms) || 0);
+    if (tenths && n < 60000) return `${(Math.floor(n / 100) / 10).toFixed(1)}s`;
+    const total = Math.floor(n / 1000);
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = String(total % 60).padStart(2, '0');
+    return h ? `${h}:${String(m).padStart(2, '0')}:${s}` : `${m}:${s}`;
+}
+
+/** "1st", "2nd", "3rd", "11th". */
+export function ordinal(n) {
+    const v = Math.abs(Math.round(Number(n) || 0));
+    const tail = v % 100 >= 11 && v % 100 <= 13 ? 'th' : ({1: 'st', 2: 'nd', 3: 'rd'}[v % 10] || 'th');
+    return `${v}${tail}`;
+}
+
+/** The leaderboard periods, in the order the switcher shows them. */
+export const PERIODS = [
+    {key: 'today', label: 'Today'},
+    {key: 'week', label: 'This week'},
+    {key: 'month', label: 'This month'},
+    {key: 'all', label: 'All time'}
+];
+
+export const PERIOD_KEYS = PERIODS.map(p => p.key);
+
+/** A period key, or 'all'. */
+export const cleanPeriod = (p) => (PERIOD_KEYS.includes(String(p)) ? String(p) : 'all');

package/plugins/_lib/public/games/games.css

@@ -0,0 +1 @@
+.gm-app{--gm-gap: 1rem;--gm-radius: var(--dm-radius, 10px);--gm-line: var(--dm-border, rgba(127, 127, 127, .3));--gm-soft: var(--dm-surface, rgba(127, 127, 127, .08));--gm-accent: var(--dm-primary, #3b82f6);--gm-good: var(--dm-success, #16a34a);--gm-bad: var(--dm-danger, #dc2626);--gm-warn: var(--dm-warning, #d97706);max-width:760px;margin:1.5rem auto;color:var(--dm-text, inherit)}.gm-app [hidden],.gm-board [hidden]{display:none!important}.gm-card{border:1px solid var(--gm-line);border-radius:var(--gm-radius);background:var(--dm-surface-raised, var(--dm-background, transparent));padding:1.25rem 1.5rem;margin-bottom:var(--gm-gap)}.gm-title{margin:0 0 .5rem;font-size:1.6rem;line-height:1.2}.gm-intro{margin:0 0 1rem;white-space:pre-line}.gm-muted{color:var(--dm-text-muted, #6b7280);margin:.25rem 0}.gm-facts{display:flex;flex-wrap:wrap;gap:.5rem 1.25rem;margin:0 0 1rem;padding:0;list-style:none;color:var(--dm-text-muted, #6b7280)}.gm-facts li:before{content:"\2022  "}.gm-facts li:first-child:before{content:""}.gm-start{display:flex;flex-wrap:wrap;gap:.75rem;align-items:flex-end}.gm-field{display:flex;flex-direction:column;gap:.3rem;flex:1 1 220px}.gm-field label{font-weight:600}.gm-input{font:inherit;padding:.6rem .75rem;border:1px solid var(--gm-line);border-radius:8px;background:var(--dm-input-bg, var(--dm-background, #fff));color:inherit;width:100%;box-sizing:border-box}.gm-input:focus{outline:2px solid var(--gm-accent);outline-offset:1px}.gm-hp{position:absolute!important;left:-9999px!important;width:1px;height:1px;overflow:hidden}.gm-error{color:var(--gm-bad);margin:.5rem 0 0;font-weight:600}.gm-note{margin:.5rem 0 0}.gm-bar{display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center;gap:.5rem;margin-bottom:1rem}.gm-progress{font-weight:600}.gm-clock{font-variant-numeric:tabular-nums;font-weight:700;padding:.2rem .65rem;border-radius:999px;background:var(--gm-soft);min-width:4.5rem;text-align:center}.gm-clock.is-low{background:var(--gm-bad);color:#fff}.gm-track{height:6px;border-radius:999px;background:var(--gm-soft);overflow:hidden;margin-bottom:1rem}.gm-track>span{display:block;height:100%;background:var(--gm-accent);transition:width .2s linear}.gm-actions{display:flex;flex-wrap:wrap;gap:.5rem;margin-top:1rem}.gm-result-score{font-size:2.4rem;font-weight:800;margin:.25rem 0}.gm-result-place{font-size:1.15rem;margin:0 0 .75rem}.gm-board{border:1px solid var(--gm-line, rgba(127, 127, 127, .3));border-radius:var(--gm-radius, 10px);padding:1rem 1.25rem;margin:0 0 1rem}.gm-board-head{display:flex;flex-wrap:wrap;align-items:center;justify-content:space-between;gap:.5rem;margin-bottom:.5rem}.gm-board-title{margin:0;font-size:1.2rem}.gm-periods{display:flex;flex-wrap:wrap;gap:.25rem}.gm-period{font:inherit;font-size:.85rem;padding:.2rem .6rem;border-radius:999px;cursor:pointer;border:1px solid var(--gm-line, rgba(127, 127, 127, .3));background:transparent;color:inherit}.gm-period.is-on{background:var(--dm-primary, #3b82f6);border-color:var(--dm-primary, #3b82f6);color:#fff}.gm-board-list{list-style:none;margin:0;padding:0}.gm-board-row{display:grid;grid-template-columns:3.2rem 1fr auto auto;gap:.75rem;align-items:center;padding:.45rem .5rem;border-bottom:1px solid var(--gm-line, rgba(127, 127, 127, .2))}.gm-board-row:last-child{border-bottom:0}.gm-board-row:nth-child(1) .gm-rank{color:#c9a227}.gm-board-row:nth-child(2) .gm-rank{color:#9aa3ad}.gm-board-row:nth-child(3) .gm-rank{color:#b0703a}.gm-board-row.is-mine{background:color-mix(in srgb,var(--dm-primary, #3b82f6) 14%,transparent);border-radius:6px;font-weight:700}.gm-rank{font-weight:800}.gm-name{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.gm-score,.gm-time{font-variant-numeric:tabular-nums;text-align:right}.gm-score{font-weight:700}@media(max-width:520px){.gm-card{padding:1rem}.gm-board-row{grid-template-columns:2.6rem 1fr auto auto;gap:.5rem}}

package/plugins/_lib/public/games/games.js

@@ -0,0 +1,204 @@
+/**
+ * Games - what the Quiz and Crossword pages share in the browser: talking to
+ * the server, the leaderboard, the countdown, the player's remembered name,
+ * the stylesheet and a celebration for a top place.
+ *
+ * Served from /plugins/_lib/public/games/games.js. Domma is on every public
+ * page, so the screens are domma-reactive (window.M): observables, one
+ * M.applyBindings per screen, and text from the server reaches the page only
+ * through bindings (textContent), never as HTML.
+ *
+ * @module _lib/public/games/games
+ */
+
+import {fmtDuration, ordinal, PERIODS} from './format.js';
+
+export {fmtDuration, ordinal, PERIODS};
+
+const M = window.M;
+
+/** JSON in and out (`token`: the play's key); a failure is an Error carrying the server's words, `status` and `code`. */
+export async function request(url, {method = 'GET', body, token} = {}) {
+    const headers = {Accept: 'application/json'};
+    if (body) headers['Content-Type'] = 'application/json';
+    // A play's key travels in a header, so it stays out of addresses and server logs.
+    if (token) headers['X-Play-Token'] = token;
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        credentials: 'same-origin'
+    });
+    let data = null;
+    try { data = await res.json(); } catch { /* not JSON */ }
+    if (!res.ok) {
+        const err = new Error(data?.error || (res.status === 429 ? 'Too many tries just now. Please wait a minute.' : 'Something went wrong. Please try again.'));
+        err.status = res.status;
+        err.code = data?.code || '';
+        throw err;
+    }
+    return data;
+}
+
+/** Remembered conveniences (the name last played under, a play in progress). Storage may be blocked. */
+export const memory = {
+    get(k) { try { return window.S ? S.get(k) : null; } catch { return null; } },
+    set(k, v) { try { window.S?.set(k, v); } catch { /* a convenience */ } },
+    remove(k) { try { window.S?.remove(k); } catch { /* a convenience */ } }
+};
+
+let stylesAdded = false;
+/** The shared stylesheet, once per page. */
+export function addStyles(extra = []) {
+    const want = stylesAdded ? extra : ['/plugins/_lib/public/games/games.css', ...extra];
+    stylesAdded = true;
+    for (const href of want) {
+        if (document.querySelector(`link[href="${href}"]`)) continue;
+        const link = document.createElement('link');
+        link.rel = 'stylesheet';
+        link.href = href;
+        document.head.appendChild(link);
+    }
+}
+
+/** The JSON config a shortcode wrote on its placeholder, or null. */
+export function configOf(el, attr) {
+    try { return JSON.parse(el.getAttribute(attr) || 'null'); } catch { return null; }
+}
+
+/** A short-lived unique prefix for ids inside one mount. */
+let mounts = 0;
+export const uid = (prefix) => `${prefix}${++mounts}${Math.random().toString(36).slice(2, 6)}`;
+
+/** Ticker tape for a top place - skipped when the visitor asked for less motion. */
+export function celebrate() {
+    try {
+        if (window.matchMedia?.('(prefers-reduced-motion: reduce)').matches) return;
+        const fx = window.Domma?.effects;
+        if (typeof fx?.tickerTape === 'function') fx.tickerTape(null, {burst: true, burstCount: 160});
+    } catch { /* a celebration never breaks the page */ }
+}
+
+/**
+ * A countdown to a deadline the SERVER set: the browser only shows it. `left`
+ * is an observable of milliseconds; `onEnd` runs once when it reaches 0.
+ */
+export class Countdown {
+    constructor(onEnd = () => {}) {
+        this.left = M.observable(0);
+        this.onEnd = onEnd;
+        this.timer = null;
+        this.deadline = 0;
+    }
+
+    /** `ms` from now; 0 or less stops it (no limit). */
+    start(ms) {
+        this.stop();
+        if (!(ms > 0)) { this.left.value = 0; return; }
+        this.deadline = performance.now() + ms;
+        const tick = () => {
+            const left = Math.max(0, this.deadline - performance.now());
+            this.left.value = left;
+            if (left <= 0) { this.stop(); this.onEnd(); }
+        };
+        tick();
+        this.timer = setInterval(tick, 200);
+    }
+
+    stop() {
+        if (this.timer) clearInterval(this.timer);
+        this.timer = null;
+    }
+}
+
+/** A running clock from a start the server gave (milliseconds already gone). */
+export class Stopwatch {
+    constructor() {
+        this.shown = M.observable('0:00');
+        this.timer = null;
+    }
+
+    start(elapsedMs = 0) {
+        this.stop();
+        const origin = performance.now() - Math.max(0, elapsedMs);
+        const tick = () => { this.shown.value = fmtDuration(performance.now() - origin); };
+        tick();
+        this.timer = setInterval(tick, 500);
+    }
+
+    stop() {
+        if (this.timer) clearInterval(this.timer);
+        this.timer = null;
+    }
+}
+
+const BOARD = `
+<div class="gm-board-head">
+  <h3 class="gm-board-title" data-bind-text="title.value"></h3>
+  <div class="gm-periods" role="group" aria-label="Period" data-each="periods key=key">
+    <button type="button" class="gm-period" data-bind-class="$root.period.value === key && 'is-on'"
+      data-bind-aria-pressed="$root.period.value === key ? 'true' : 'false'" data-on-click="$root.pick($data)" data-bind-text="label"></button>
+  </div>
+</div>
+<p class="gm-muted" hidden data-bind-hidden="!loading.value">Loading…</p>
+<p class="gm-muted" hidden data-bind-hidden="loading.value || rows.value.length">No scores yet. Be the first!</p>
+<ol class="gm-board-list" hidden data-bind-hidden="!rows.value.length" data-each="rows.value key=id">
+  <li class="gm-board-row" data-bind-class="mine && 'is-mine'">
+    <span class="gm-rank" data-bind-text="place"></span>
+    <span class="gm-name" data-bind-text="name"></span>
+    <span class="gm-score" data-if="showScore" data-bind-text="scoreText"></span>
+    <span class="gm-time" data-bind-text="timeText"></span>
+  </li>
+</ol>`;
+
+/**
+ * A live leaderboard on `el`, fetched from `url` (?period=&limit=).
+ *
+ * @param {HTMLElement} el
+ * @param {{url: string, period?: string, limit?: number, showScore?: boolean, title?: string}} opts
+ * @returns {{refresh: (mineId?: string) => Promise<void>, dispose: () => void}}
+ */
+export function mountLeaderboard(el, {url, period = 'all', limit = 10, showScore = true, title = 'Leaderboard'}) {
+    if (!M) return {refresh: async () => {}, dispose() {}};
+    addStyles();
+    el.classList.add('gm-board');
+    el.innerHTML = BOARD;
+    const state = {
+        title: M.observable(title),
+        period: M.observable(PERIODS.some(p => p.key === period) ? period : 'all'),
+        periods: PERIODS,
+        rows: M.observable([]),
+        loading: M.observable(true),
+        pick: (p) => { state.period.value = p.key; refresh(); }
+    };
+    let mine = '';
+    async function refresh(mineId) {
+        if (mineId) mine = mineId;
+        state.loading.value = !state.rows.peek().length;
+        try {
+            const res = await request(`${url}?period=${encodeURIComponent(state.period.peek())}&limit=${encodeURIComponent(limit)}`);
+            state.rows.value = (res.rows || []).map(r => ({
+                id: r.id, name: r.name, mine: r.id === mine, showScore,
+                place: ordinal(r.rank), scoreText: `${r.score}`, timeText: fmtDuration(r.timeMs)
+            }));
+        } catch {
+            state.rows.value = [];
+        } finally {
+            state.loading.value = false;
+        }
+    }
+    const handle = M.applyBindings(state, el);
+    refresh();
+    return {refresh, dispose: () => handle.dispose()};
+}
+
+/** Every `[data-<kind>-board]` placeholder on the page (the leaderboard shortcodes). */
+export function mountBoards(attr, urlFor, {showScore = true} = {}) {
+    for (const el of document.querySelectorAll(`[${attr}]`)) {
+        if (el.dataset.gmMounted) continue;
+        el.dataset.gmMounted = '1';
+        const cfg = configOf(el, attr);
+        if (!cfg?.id) continue;
+        mountLeaderboard(el, {url: urlFor(cfg.id), period: cfg.period, limit: cfg.limit, showScore, title: cfg.title || 'Leaderboard'});
+    }
+}

package/plugins/crossword/CLAUDE.md

@@ -0,0 +1,37 @@
+# crossword - AI Assistant Guide
+
+## Purpose
+
+Crosswords on the public site, built from a word + clue list, timed by the server, with a fastest-solver
+leaderboard. 1.1.0 (2026-10-21), `tier: free`, disabled on arrival. Sibling of `quiz`; shares `plugins/_lib/games`.
+
+## Files
+
+- `public/lib/layout.js` - PURE, isomorphic, SERVED: `generate(words, {seed})` (greedy, deterministic from the
+  seed, clues never affect the layout), `cleanAnswer` (letters + enumeration), `solutionGrid`, `shapeOf`. The admin
+  builder imports it over HTTP for the live preview; the server runs the same function on save, so a layout is
+  never taken from the browser. It holds no puzzle, which is why it may live under `public/`.
+- `lib/crossword.js` - PURE: `cleanPuzzle`, `isOpen`, `publicPuzzle` (shape + clues, no letters), `readCells`,
+  `compare`, `catchUp`, `finish`, `view`.
+- `lib/store.js` - `crossword-puzzles` + `plays = new PlayStore('crossword-plays', {order: 'time'})`.
+- `plugin.js` - routes (header comment), shortcodes, the `fastest` notification source.
+- `public/crossword.js` - the player: the screens are domma-reactive; the grid is a `Board` class over real
+  `<input>`s (keyboard rules in its header - all focus and keystrokes, which bindings do not reach), letters
+  remembered per play in storage. Exports `mount(el, {test})`, which the admin's Test screen uses.
+- `admin/views/crossword.js` - list, editor with live grid, test and plays screens, all domma-reactive through the
+  admin kit (`_lib/admin/games/kit.js`). The preview grid is a data-each over cells.
+
+## Contracts
+
+- **No letters before solving.** `/public/crossword/:slug` gives only the size; the clues come with the play (so
+  nobody studies them off the clock); `solution` is in `/result` only when `status === 'finished'`. The tests
+  assert no answer string appears in the play payload - keep that test.
+- **Time = server elapsed + `state.penaltyMs`.** Check adds `checkPenalty` seconds (403 when `checks` is off); a
+  FULL but wrong submit adds `wrongPenalty`; a grid with empties only reports the count.
+- Cells travel as `height` strings of `width` chars, `A-Z` or space; anything else is 400.
+- The grid uses fixed ink/paper colours (`--cw-ink`, `--cw-paper`) whatever the theme - a themed grid inverted
+  under dark themes.
+- Same shortcode prefix trap as quiz: `crossword-leaderboard` is registered with `{priority: 5}`.
+- **Test plays** (1.1.0): `GET/POST /puzzles/:id/test` (manage), as in quiz's CLAUDE.md - the saved crossword
+  whatever its status, never on a board, not in the plays list, no notification, cleared by the next test.
+  `/result` answers `test: true` and `wouldPlace`.

package/plugins/crossword/admin/css/index.css

@@ -0,0 +1,18 @@
+/* Crossword admin - the word list and the live grid. Shared pieces are in /plugins/_lib/admin/games/games.css. */
+.cwa-words { display: flex; flex-direction: column; gap: .4rem; }
+.cwa-word { display: grid; grid-template-columns: 1.6rem minmax(7rem, 12rem) 3.5rem minmax(0, 1fr) auto; gap: .4rem; align-items: center; }
+.cwa-n { color: var(--dm-text-muted); font-size: var(--dm-text-sm); text-align: right; }
+.cwa-answer { text-transform: uppercase; font-family: var(--dm-font-mono, monospace); letter-spacing: .04em; }
+.cwa-enum { color: var(--dm-text-muted); font-size: var(--dm-text-xs); white-space: nowrap; }
+@media (max-width: 700px) { .cwa-word { grid-template-columns: 1.4rem 1fr auto; } .cwa-enum { display: none; } .cwa-clue { grid-column: 2 / 4; } }
+
+.cwa-side { position: sticky; top: .5rem; }
+.cwa-preview { overflow: auto; max-height: 70vh; }
+/* Fixed ink and paper, as on the public grid: a themed grid came out inverted under dark themes. */
+.cwa-grid { --cwa-ink: #111827; --cwa-paper: #ffffff; display: grid; gap: 0; width: max-content; border: 2px solid var(--cwa-ink); background: var(--cwa-ink); }
+.cwa-cell { position: relative; width: 1.7rem; height: 1.7rem; display: grid; place-items: center; font-weight: 700; font-size: .85rem;
+    background: var(--cwa-paper); color: var(--cwa-ink); border: 1px solid color-mix(in srgb, var(--cwa-ink) 35%, transparent); box-sizing: border-box; }
+.cwa-cell.is-block { background: var(--cwa-ink); border-color: var(--cwa-ink); }
+.cwa-num { position: absolute; top: 1px; left: 2px; font-size: .5rem; font-weight: 600; line-height: 1; color: #4b5563; }
+.cwa-unplaced { margin: 0; padding: .5rem .75rem; border-radius: 6px; font-size: var(--dm-text-sm);
+    background: color-mix(in srgb, var(--dm-warning) 15%, transparent); color: color-mix(in srgb, var(--dm-warning) 55%, var(--dm-text)); }

package/plugins/crossword/admin/templates/crossword.html

@@ -0,0 +1 @@
+<div class="gma cwa" data-crossword-admin></div>