domma-cms 1.8.30 → 1.8.32

package/plugins/quiz/lib/quiz.js

@@ -0,0 +1,225 @@
+/**
+ * Quiz - the rules. PURE: no I/O, so the same decisions run in the routes and
+ * the tests.
+ *
+ *   cleanQuiz(input)          -> {quiz, errors}     what the admin saved, made safe
+ *   isOpen(quiz, now)         -> {open, reason}     can people play it now?
+ *   planPlay(quiz, rand)      -> state              this player's questions, in their order
+ *   publicQuestion(...)       -> what the player may see of a question (never the answer)
+ *   mark(question, given)     -> {correct, given}   one answer marked
+ *   answerText(question, ids) -> "Paris"            an answer in words, for feedback and review
+ *
+ * @module quiz/lib/quiz
+ */
+
+export const KINDS = ['single', 'multiple', 'truefalse', 'text'];
+export const STATUSES = ['draft', 'open', 'closed'];
+export const SHOW_ANSWERS = ['never', 'after-each', 'end'];
+
+export const LIMITS = {questions: 200, options: 8, text: 1000, option: 200, accepted: 20, seconds: 3600, timeLimit: 4 * 3600, points: 100};
+
+const str = (v, max) => String(v ?? '').replace(/\r\n?/g, '\n').trim().slice(0, max);
+const int = (v, min, max, dflt = 0) => {
+    const n = Math.round(Number(v));
+    return Number.isFinite(n) ? Math.max(min, Math.min(max, n)) : dflt;
+};
+const iso = (v) => {
+    const t = Date.parse(String(v || ''));
+    return Number.isFinite(t) ? new Date(t).toISOString() : '';
+};
+const shortId = () => Math.random().toString(36).slice(2, 10);
+const idOf = (v) => (/^[a-z0-9_-]{1,40}$/i.test(String(v || '')) ? String(v) : shortId());
+
+/** "Capital Cities 2026" -> "capital-cities-2026". */
+export function slugify(s) {
+    return String(s || '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60);
+}
+
+/** For comparing typed answers: case, accents, punctuation and spacing do not matter; a leading "the"/"a" neither. */
+export function foldAnswer(s) {
+    return String(s ?? '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase()
+        .replace(/&/g, ' and ').replace(/[^\p{L}\p{N}]+/gu, ' ').trim().replace(/^(the|a|an) /, '');
+}
+
+function cleanQuestion(q, n, errors) {
+    const kind = KINDS.includes(q?.kind) ? q.kind : 'single';
+    const out = {
+        id: idOf(q?.id), kind,
+        text: str(q?.text, LIMITS.text),
+        image: str(q?.image, 500),
+        points: int(q?.points ?? 1, 0, LIMITS.points, 1),
+        seconds: int(q?.seconds, 0, LIMITS.seconds),
+        explanation: str(q?.explanation, LIMITS.text),
+        options: [],
+        accepted: []
+    };
+    const where = `Question ${n}`;
+    if (!out.text) errors[`q${n}`] = `${where} has no question.`;
+    if (out.image && !/^(\/(?!\/)|https:\/\/)/.test(out.image)) errors[`q${n}`] = `${where}: the picture must be on this site (/media/...) or an https:// address.`;
+
+    if (kind === 'text') {
+        const raw = Array.isArray(q?.accepted) ? q.accepted : String(q?.accepted || '').split('\n');
+        out.accepted = [...new Set(raw.map(a => str(a, LIMITS.option)).filter(Boolean))].slice(0, LIMITS.accepted);
+        if (!out.accepted.length) errors[`q${n}`] ??= `${where} needs at least one accepted answer.`;
+        return out;
+    }
+    if (kind === 'truefalse') {
+        const isTrue = Array.isArray(q?.options) ? q.options.find(o => o?.id === 'true')?.correct !== false : true;
+        out.options = [{id: 'true', text: 'True', correct: isTrue}, {id: 'false', text: 'False', correct: !isTrue}];
+        return out;
+    }
+    const seen = new Set();
+    for (const o of (Array.isArray(q?.options) ? q.options : []).slice(0, LIMITS.options)) {
+        const text = str(o?.text, LIMITS.option);
+        if (!text) continue;
+        let id = idOf(o?.id);
+        while (seen.has(id)) id = shortId();
+        seen.add(id);
+        out.options.push({id, text, correct: o?.correct === true});
+    }
+    const right = out.options.filter(o => o.correct).length;
+    if (out.options.length < 2) errors[`q${n}`] ??= `${where} needs at least two answers to choose from.`;
+    else if (!right) errors[`q${n}`] ??= `${where}: tick the right answer.`;
+    else if (kind === 'single' && right > 1) errors[`q${n}`] ??= `${where} allows one answer but has ${right} ticked. Make it "more than one answer" or untick the others.`;
+    return out;
+}
+
+/**
+ * The quiz as the admin saved it, cleaned. `errors` keyed by field (`title`, `q3`...).
+ *
+ * @returns {{quiz: object, errors: Object<string, string>}}
+ */
+export function cleanQuiz(input = {}) {
+    const errors = {};
+    const quiz = {
+        title: str(input.title, 120),
+        slug: slugify(input.slug || input.title),
+        intro: str(input.intro, 2000),
+        status: STATUSES.includes(input.status) ? input.status : 'draft',
+        opensAt: iso(input.opensAt),
+        closesAt: iso(input.closesAt),
+        timeLimit: int(input.timeLimit, 0, LIMITS.timeLimit),
+        questionSeconds: int(input.questionSeconds, 0, LIMITS.seconds),
+        shuffleQuestions: input.shuffleQuestions === true,
+        shuffleOptions: input.shuffleOptions === true,
+        draw: int(input.draw, 0, LIMITS.questions),
+        showAnswers: SHOW_ANSWERS.includes(input.showAnswers) ? input.showAnswers : 'end',
+        leaderboard: input.leaderboard !== false,
+        leaderboardSize: int(input.leaderboardSize ?? 10, 3, 100, 10),
+        attemptsPerName: int(input.attemptsPerName, 0, 100),
+        questions: []
+    };
+    if (!quiz.title) errors.title = 'Give the quiz a title.';
+    if (!quiz.slug) errors.slug = 'Give the quiz a short name for its address (letters and numbers).';
+    if (quiz.opensAt && quiz.closesAt && quiz.closesAt <= quiz.opensAt) errors.closesAt = 'It has to close after it opens.';
+    const raw = Array.isArray(input.questions) ? input.questions.slice(0, LIMITS.questions) : [];
+    const ids = new Set();
+    raw.forEach((q, i) => {
+        const clean = cleanQuestion(q, i + 1, errors);
+        while (ids.has(clean.id)) clean.id = shortId();
+        ids.add(clean.id);
+        quiz.questions.push(clean);
+    });
+    if (quiz.status === 'open' && !quiz.questions.length) errors.questions = 'Add at least one question before opening the quiz.';
+    if (quiz.draw && quiz.draw > quiz.questions.length) quiz.draw = 0;
+    return {quiz, errors};
+}
+
+/** Can people play it right now? `reason` is said to them when not. */
+export function isOpen(quiz, now = Date.now()) {
+    if (!quiz || quiz.status === 'draft') return {open: false, reason: 'This quiz is not open yet.', state: 'draft'};
+    if (quiz.status === 'closed') return {open: false, reason: 'This quiz has closed.', state: 'closed'};
+    if (quiz.opensAt && Date.parse(quiz.opensAt) > now) return {open: false, reason: 'This quiz opens soon.', state: 'scheduled', opensAt: quiz.opensAt};
+    if (quiz.closesAt && Date.parse(quiz.closesAt) <= now) return {open: false, reason: 'This quiz has closed.', state: 'ended'};
+    if (!quiz.questions?.length) return {open: false, reason: 'This quiz has no questions yet.', state: 'empty'};
+    return {open: true, reason: '', state: 'open'};
+}
+
+/** Fisher-Yates with the caller's random (tests pass a fixed one). */
+export function shuffle(list, rand = Math.random) {
+    const a = [...list];
+    for (let i = a.length - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        [a[i], a[j]] = [a[j], a[i]];
+    }
+    return a;
+}
+
+/**
+ * This player's quiz: which questions (all, or `draw` of them), in what order,
+ * and each one's answers in what order. Fixed at the start so a reload shows
+ * the same thing.
+ */
+export function planPlay(quiz, rand = Math.random) {
+    let qs = quiz.shuffleQuestions || quiz.draw ? shuffle(quiz.questions, rand) : [...quiz.questions];
+    if (quiz.draw) qs = qs.slice(0, quiz.draw);
+    return {
+        order: qs.map(q => ({q: q.id, opts: (quiz.shuffleOptions && q.kind !== 'truefalse' ? shuffle(q.options, rand) : q.options).map(o => o.id)})),
+        index: 0,
+        servedAt: [],
+        answers: []
+    };
+}
+
+export const maxScoreOf = (quiz, state) => state.order.reduce((sum, o) => sum + (quiz.questions.find(q => q.id === o.q)?.points ?? 0), 0);
+
+/** A question's time limit in ms (its own, else the quiz's default), 0 = none. */
+export const questionLimitMs = (quiz, q) => ((q?.seconds || quiz.questionSeconds || 0) * 1000);
+
+/** What the player sees: the question and its choices - never which is right. */
+export function publicQuestion(quiz, state) {
+    const slot = state.order[state.index];
+    const q = slot && quiz.questions.find(x => x.id === slot.q);
+    if (!q) return null;
+    const byId = new Map(q.options.map(o => [o.id, o]));
+    return {
+        id: q.id, kind: q.kind, text: q.text, image: q.image, points: q.points,
+        options: q.kind === 'text' ? [] : slot.opts.map(id => byId.get(id)).filter(Boolean).map(o => ({id: o.id, text: o.text})),
+        seconds: questionLimitMs(quiz, q) / 1000
+    };
+}
+
+/**
+ * One answer marked. `given`: an option id (single, truefalse), a list of ids
+ * (multiple), or what they typed (text). Anything else is simply wrong.
+ *
+ * @returns {{correct: boolean, given: string|string[]}}
+ */
+export function mark(q, given) {
+    if (!q) return {correct: false, given: ''};
+    if (q.kind === 'text') {
+        const typed = String(given ?? '').slice(0, LIMITS.option);
+        const f = foldAnswer(typed);
+        return {correct: Boolean(f) && q.accepted.some(a => foldAnswer(a) === f), given: typed};
+    }
+    const ids = new Set(q.options.map(o => o.id));
+    if (q.kind === 'multiple') {
+        const picked = [...new Set((Array.isArray(given) ? given : [given]).map(String).filter(id => ids.has(id)))];
+        const right = q.options.filter(o => o.correct).map(o => o.id);
+        return {correct: picked.length === right.length && right.every(id => picked.includes(id)), given: picked};
+    }
+    const one = ids.has(String(given)) ? String(given) : '';
+    return {correct: Boolean(one) && q.options.find(o => o.id === one)?.correct === true, given: one};
+}
+
+/** An answer (option ids, or typed text) in words. */
+export function answerText(q, given) {
+    if (!q) return '';
+    if (q.kind === 'text') return String(given ?? '');
+    const list = Array.isArray(given) ? given : [given];
+    return list.map(id => q.options.find(o => o.id === id)?.text).filter(Boolean).join(', ');
+}
+
+/** The right answer in words. */
+export const rightText = (q) => (q?.kind === 'text' ? q.accepted[0] || '' : q?.options.filter(o => o.correct).map(o => o.text).join(', ') || '');
+
+/** The quiz as a list row in the admin. */
+export function summary(quiz, plays = []) {
+    const finished = plays.filter(p => p.status === 'finished');
+    return {
+        id: quiz.id, title: quiz.title, slug: quiz.slug, status: quiz.status, opensAt: quiz.opensAt, closesAt: quiz.closesAt,
+        questions: quiz.questions?.length || 0, plays: plays.length, finished: finished.length,
+        best: finished.reduce((m, p) => Math.max(m, p.score || 0), 0), updatedAt: quiz.updatedAt || ''
+    };
+}

package/plugins/quiz/lib/store.js

@@ -0,0 +1,56 @@
+/**
+ * Quiz - where quizzes and plays are kept: the collections `quiz-quizzes` and
+ * `quiz-plays` (made at every boot when missing; API access all off - a quiz
+ * holds its answers, a play the player's name).
+ *
+ * @module quiz/lib/store
+ */
+
+import fs from 'node:fs/promises';
+import {createCollection, createEntry, deleteEntry, getCollection, getEntry, listEntries, updateEntry} from '../../../server/services/collections.js';
+import {PlayStore} from '../../_lib/games/plays.js';
+
+export const QUIZZES = 'quiz-quizzes';
+export const PLAYS = 'quiz-plays';
+
+export const plays = new PlayStore(PLAYS, {order: 'score'});
+
+export async function ensureCollections(log = console) {
+    for (const slug of [QUIZZES, PLAYS]) {
+        if (await getCollection(slug)) continue;
+        const schema = JSON.parse(await fs.readFile(new URL(`../collections/${slug}.json`, import.meta.url), 'utf8'));
+        await createCollection(schema);
+        log.info?.(`[quiz] Created collection: ${slug}`);
+    }
+}
+
+const flat = (e) => (e ? {id: e.id, ...e.data, createdAt: e.meta?.createdAt, updatedAt: e.meta?.updatedAt} : null);
+
+let cache = null;
+export async function allQuizzes() {
+    cache ??= listEntries(QUIZZES, {limit: 100000}).then(r => (r.entries || []).map(flat)).catch(() => []);
+    return cache;
+}
+const forget = () => { cache = null; };
+
+export const getQuiz = async (id) => flat(await getEntry(QUIZZES, String(id)).catch(() => null));
+export const quizBySlug = async (slug) => (await allQuizzes()).find(q => q.slug === String(slug)) || null;
+
+/** A short name no other quiz has. */
+export async function uniqueSlug(slug, selfId = '') {
+    const taken = new Set((await allQuizzes()).filter(q => q.id !== selfId).map(q => q.slug));
+    if (!taken.has(slug)) return slug;
+    for (let n = 2; ; n++) if (!taken.has(`${slug}-${n}`)) return `${slug}-${n}`;
+}
+
+export async function saveQuiz(id, data) {
+    const saved = id ? await updateEntry(QUIZZES, id, data) : await createEntry(QUIZZES, data);
+    forget();
+    return flat(saved);
+}
+
+export async function removeQuiz(id) {
+    await deleteEntry(QUIZZES, String(id));
+    forget();
+    return plays.reset(String(id));
+}

package/plugins/quiz/plugin.js

@@ -0,0 +1,241 @@
+/**
+ * Quiz - the API (mounted at /api/plugins/quiz).
+ *
+ * Admin (the `quiz` permission; read to look, manage to change):
+ *   GET  /count                      sidebar badge: plays finished today
+ *   GET  /quizzes                    every quiz as a list row
+ *   GET  /quizzes/:id · POST /quizzes · PUT /quizzes/:id · DELETE /quizzes/:id
+ *   POST /quizzes/:id/copy           a copy, as a draft
+ *   GET  /quizzes/:id/plays · DELETE /quizzes/:id/plays · PUT /plays/:id · DELETE /plays/:id
+ *
+ * Players (no sign-in), under /public - the server keeps the time and marks every answer:
+ *   GET  /public/quiz/:slug                 title, intro, how many questions, the limits
+ *   GET  /public/quiz/:slug/leaderboard     ?period=today|week|month|all&limit=
+ *   POST /public/quiz/:slug/start           {name} -> {playId, token} (the token is shown once)
+ *   GET  /public/play/:id                   where the play is now: the current question (no answer), time left
+ *   POST /public/play/:id/answer            {q, answer} -> marked; feedback when the quiz shows answers as you go
+ *   GET  /public/play/:id/result            score, time, place, and the answers when the quiz shows them
+ * Each /public/play call carries the token in `X-Play-Token`.
+ *
+ * Shortcodes: [quiz id="<short name>" /] and [quiz-leaderboard id="<short name>" period="week" limit="10" /].
+ */
+
+import {cleanPlayerName} from '../_lib/games/names.js';
+import {boardQuery, fail, isBot, limited, mountPlayAdmin, todayBadge, tokenOf} from '../_lib/games/http.js';
+import {answerText, cleanQuiz, isOpen, maxScoreOf, planPlay, rightText, summary} from './lib/quiz.js';
+import {answer, catchUp, feedbackFor, serve, view} from './lib/engine.js';
+import {allQuizzes, ensureCollections, getQuiz, plays, quizBySlug, removeQuiz, saveQuiz, uniqueSlug} from './lib/store.js';
+
+const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+const slugAttr = (v) => String(v || '').toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 60);
+
+function registerShortcodes(hooks) {
+    if (typeof hooks.registerShortcode !== 'function') return;
+    // Self-closing. The page's script (public/quiz.js, on every page via inject/body.html) mounts on the placeholder.
+    hooks.registerShortcode('quiz', (attrStr, _body, ctx) => {
+        const a = ctx.parseShortcodeAttrs(attrStr || '');
+        const slug = slugAttr(a.id || a.slug);
+        if (!slug) return '<p class="gm-muted">[quiz] needs id="the quiz\'s short name".</p>';
+        return `<div class="gm-app qz-app" data-quiz='${esc(JSON.stringify({slug}))}'><p class="gm-muted">Loading the quiz…</p></div>`;
+    });
+    hooks.registerShortcode('quiz-leaderboard', (attrStr, _body, ctx) => {
+        const a = ctx.parseShortcodeAttrs(attrStr || '');
+        const id = slugAttr(a.id || a.slug);
+        if (!id) return '<p class="gm-muted">[quiz-leaderboard] needs id="the quiz\'s short name".</p>';
+        const cfg = {id, period: String(a.period || 'all'), limit: Math.max(1, Math.min(100, Number(a.limit) || 10)), title: String(a.title || 'Leaderboard').slice(0, 80)};
+        return `<div class="qz-board" data-quiz-board='${esc(JSON.stringify(cfg))}'></div>`;
+    // First: the engine matches [quiz…/] by prefix, so [quiz] would otherwise take [quiz-leaderboard …/] too.
+    }, {priority: 5});
+}
+
+/** What anyone may know about a quiz before playing it. */
+function publicInfo(quiz) {
+    const state = isOpen(quiz);
+    const count = quiz.draw || quiz.questions.length;
+    return {
+        slug: quiz.slug, title: quiz.title, intro: quiz.intro, open: state.open, reason: state.reason, opensAt: state.opensAt || '',
+        questions: count, timeLimit: quiz.timeLimit, questionSeconds: quiz.questionSeconds,
+        perQuestionTimes: quiz.questions.some(q => q.seconds > 0),
+        showAnswers: quiz.showAnswers, leaderboard: quiz.leaderboard, leaderboardSize: quiz.leaderboardSize,
+        attemptsPerName: quiz.attemptsPerName
+    };
+}
+
+/** The review at the end: every question, their answer and the right one - only when the quiz shows answers. */
+function review(quiz, play) {
+    if (quiz.showAnswers === 'never') return null;
+    return play.state.order.map((slot, i) => {
+        const q = quiz.questions.find(x => x.id === slot.q);
+        const a = play.state.answers[i];
+        if (!q) return null;
+        return {
+            text: q.text, image: q.image, points: q.points,
+            yours: a ? (a.given == null ? '' : answerText(q, a.given)) : '',
+            right: rightText(q), correct: a?.correct === true, late: a?.late === true, explanation: q.explanation || ''
+        };
+    }).filter(Boolean);
+}
+
+export default async function quizPlugin(fastify, options) {
+    const {authenticate, requirePermission} = options.auth;
+    const hooks = options.hooks || {};
+    const can = (action) => ({preHandler: [authenticate, requirePermission('quiz', action)]});
+
+    await ensureCollections(fastify.log);
+    registerShortcodes(hooks);
+
+    if (typeof hooks.registerNotificationSource === 'function') {
+        try {
+            hooks.registerNotificationSource({id: 'top-scores', label: 'Quiz top scores', severity: 'info', defaultOn: true,
+                description: 'Someone has gone top of a quiz\'s all-time leaderboard.'});
+        } catch { /* older engine */ }
+    }
+
+    // ---- Admin ------------------------------------------------------------------
+
+    fastify.get('/count', can('read'), async () => todayBadge(plays, 'quiz play'));
+
+    fastify.get('/quizzes', can('read'), async () => {
+        const everyPlay = await plays.all();
+        return {quizzes: (await allQuizzes()).map(q => summary(q, everyPlay.filter(p => p.gameId === q.id)))
+            .sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)))};
+    });
+
+    fastify.get('/quizzes/:id', can('read'), async (request, reply) => {
+        const quiz = await getQuiz(request.params.id);
+        return quiz || fail(reply, 404, 'That quiz is not here any more.');
+    });
+
+    async function save(request, reply, id) {
+        const current = id ? await getQuiz(id) : null;
+        if (id && !current) return fail(reply, 404, 'That quiz is not here any more.');
+        const {quiz, errors} = cleanQuiz(request.body || {});
+        if (Object.keys(errors).length) return fail(reply, 400, Object.values(errors)[0], {errors});
+        quiz.slug = await uniqueSlug(quiz.slug, id || '');
+        const saved = await saveQuiz(id, quiz);
+        return id ? saved : reply.code(201).send(saved);
+    }
+
+    fastify.post('/quizzes', can('manage'), (request, reply) => save(request, reply, ''));
+    fastify.put('/quizzes/:id', can('manage'), (request, reply) => save(request, reply, request.params.id));
+
+    fastify.post('/quizzes/:id/copy', can('manage'), async (request, reply) => {
+        const quiz = await getQuiz(request.params.id);
+        if (!quiz) return fail(reply, 404, 'That quiz is not here any more.');
+        const {id, createdAt, updatedAt, ...rest} = quiz;
+        const copy = {...rest, title: `${quiz.title} (copy)`.slice(0, 120), status: 'draft', slug: await uniqueSlug(quiz.slug)};
+        return reply.code(201).send(await saveQuiz('', copy));
+    });
+
+    fastify.delete('/quizzes/:id', can('manage'), async (request, reply) => {
+        if (!await getQuiz(request.params.id)) return fail(reply, 404, 'That quiz is not here any more.');
+        return {ok: true, playsRemoved: await removeQuiz(request.params.id)};
+    });
+
+    mountPlayAdmin(fastify, {store: plays, base: '/quizzes', can, exists: async (id) => Boolean(await getQuiz(id))});
+
+    // ---- Players ----------------------------------------------------------------
+
+    /** A quiz the public may see: anything but a draft. */
+    const shownQuiz = async (slug) => {
+        const quiz = await quizBySlug(slug);
+        return quiz && quiz.status !== 'draft' ? quiz : null;
+    };
+
+    fastify.get('/public/quiz/:slug', limited(120), async (request, reply) => {
+        const quiz = await shownQuiz(request.params.slug);
+        if (!quiz) return fail(reply, 404, 'There is no quiz here.');
+        return publicInfo(quiz);
+    });
+
+    fastify.get('/public/quiz/:slug/leaderboard', limited(120), async (request, reply) => {
+        const quiz = await shownQuiz(request.params.slug);
+        if (!quiz || !quiz.leaderboard) return fail(reply, 404, 'There is no leaderboard here.');
+        const {period, limit} = boardQuery(request.query, quiz.leaderboardSize);
+        return {title: quiz.title, period, rows: await plays.board(quiz.id, {period, limit})};
+    });
+
+    fastify.post('/public/quiz/:slug/start', limited(20, 10), async (request, reply) => {
+        const quiz = await shownQuiz(request.params.slug);
+        if (!quiz) return fail(reply, 404, 'There is no quiz here.');
+        const state = isOpen(quiz);
+        if (!state.open) return fail(reply, 409, state.reason, {code: 'closed'});
+        if (isBot(request.body)) return fail(reply, 400, 'Something went wrong. Please try again.');
+        const {name, error} = cleanPlayerName(request.body?.name);
+        if (error) return fail(reply, 400, error, {code: 'name'});
+        if (quiz.attemptsPerName && await plays.attemptsBy(quiz.id, name) >= quiz.attemptsPerName) {
+            return fail(reply, 409, quiz.attemptsPerName === 1 ? `${name} has already had a go at this quiz.` : `${name} has already had ${quiz.attemptsPerName} goes at this quiz.`, {code: 'attempts'});
+        }
+        const plan = planPlay(quiz);
+        const play = await plays.start({gameId: quiz.id, name, maxScore: maxScoreOf(quiz, plan), state: plan});
+        return reply.code(201).send({playId: play.id, token: play.token, name, total: plan.order.length, maxScore: play.maxScore});
+    });
+
+    /**
+     * The play behind a request, brought up to date with the clock (and saved
+     * when that changed it). Null after answering with the reason.
+     */
+    async function livePlay(request, reply, {serveNow = false} = {}) {
+        const opened = await plays.open(request.params.id, tokenOf(request));
+        if (!opened) { fail(reply, 404, 'That game is not here any more. Start again.', {code: 'gone'}); return null; }
+        const quiz = await getQuiz(opened.gameId);
+        if (!quiz) { fail(reply, 404, 'That quiz is not here any more.', {code: 'gone'}); return null; }
+        const now = Date.now();
+        const play = await plays.change(opened.id, (p) => {
+            const a = catchUp(quiz, p, now);
+            const b = serveNow && serve(quiz, p, now);
+            return a || b ? p : null;
+        });
+        if (play.status === 'finished' && opened.status === 'playing') await afterFinish(quiz, play);
+        return {quiz, play, now};
+    }
+
+    /** A new top of the all-time board tells the admins. */
+    async function afterFinish(quiz, play) {
+        try {
+            if (!quiz.leaderboard || await plays.placeOf(play, 'all') !== 1) return;
+            hooks.notify?.({
+                title: `New top score on "${quiz.title}"`,
+                body: `${play.name}: ${play.score} of ${play.maxScore} in ${Math.round(play.timeMs / 1000)} seconds`,
+                severity: 'info', link: `#/plugins/quiz/plays/${quiz.id}`, source: 'top-scores', dedupeKey: `quiz-top:${play.id}`
+            });
+        } catch { /* a notice never breaks a play */ }
+    }
+
+    fastify.get('/public/play/:id', limited(240), async (request, reply) => {
+        const live = await livePlay(request, reply, {serveNow: true});
+        if (!live) return reply;
+        return view(live.quiz, live.play, live.now);
+    });
+
+    fastify.post('/public/play/:id/answer', limited(240), async (request, reply) => {
+        const live = await livePlay(request, reply);
+        if (!live) return reply;
+        const {quiz} = live;
+        let outcome = null;
+        const play = await plays.change(live.play.id, (p) => {
+            outcome = answer(quiz, p, request.body?.q, request.body?.answer, Date.now());
+            return outcome.error ? null : p;
+        });
+        if (outcome?.error) return fail(reply, 409, outcome.error, {code: outcome.code || 'finished', play: view(quiz, play)});
+        if (play.status === 'finished') await afterFinish(quiz, play);
+        return {correct: outcome.correct, late: outcome.late, points: outcome.points, feedback: feedbackFor(quiz, outcome.q, outcome), play: view(quiz, play)};
+    });
+
+    fastify.get('/public/play/:id/result', limited(120), async (request, reply) => {
+        const live = await livePlay(request, reply);
+        if (!live) return reply;
+        const {quiz, play} = live;
+        if (play.status !== 'finished') return fail(reply, 409, 'This play has not finished yet.', {code: 'playing'});
+        return {
+            name: play.name, score: play.score, maxScore: play.maxScore, timeMs: play.timeMs, timeUp: play.state.timeUp === true,
+            correct: play.state.answers.filter(a => a.correct).length, total: play.state.order.length,
+            hidden: play.hidden === true,
+            place: quiz.leaderboard && !play.hidden ? await plays.placeOf(play, 'all') : 0,
+            placeToday: quiz.leaderboard && !play.hidden ? await plays.placeOf(play, 'today') : 0,
+            leaderboard: quiz.leaderboard,
+            review: review(quiz, play)
+        };
+    });
+}
+

package/plugins/quiz/plugin.json

@@ -0,0 +1,78 @@
+{
+  "name": "quiz",
+  "displayName": "Quiz",
+  "version": "1.0.0",
+  "tier": "free",
+  "description": "Make quizzes in the admin and put them on any page. Players type a name, answer against the clock, and see where they came on the leaderboard. The server keeps the time and marks every answer, so the browser never holds the answers.",
+  "author": "Domma CMS",
+  "date": "2026-10-20",
+  "icon": "help-circle",
+  "permissions": [
+    {
+      "key": "quiz",
+      "label": "Quiz",
+      "group": "Plugins",
+      "icon": "help-circle",
+      "description": "See quizzes and who played them (read), or make, change and remove quizzes and plays (manage).",
+      "actions": [
+        {
+          "key": "read",
+          "label": "See",
+          "description": "Open Quiz and see the quizzes, plays and leaderboards"
+        },
+        {
+          "key": "manage",
+          "label": "Manage",
+          "description": "Make, change and delete quizzes; hide or remove plays; reset a leaderboard"
+        }
+      ],
+      "grant": [
+        "admin"
+      ]
+    }
+  ],
+  "inject": {
+    "bodyEnd": "inject/body.html"
+  },
+  "admin": {
+    "css": [
+      "../_lib/admin/games/games.css",
+      "admin/css/index.css"
+    ],
+    "sidebar": [
+      {
+        "id": "quiz",
+        "text": "Quiz",
+        "icon": "help-circle",
+        "url": "#/plugins/quiz",
+        "section": "#/plugins/quiz",
+        "permission": "quiz",
+        "group": "Games",
+        "countUrl": "/api/plugins/quiz/count"
+      }
+    ],
+    "routes": [
+      {
+        "path": "/plugins/quiz",
+        "view": "plugin-quiz",
+        "title": "Quiz - Domma CMS"
+      },
+      {
+        "path": "/plugins/quiz/:a",
+        "view": "plugin-quiz",
+        "title": "Quiz - Domma CMS"
+      },
+      {
+        "path": "/plugins/quiz/:a/:b",
+        "view": "plugin-quiz",
+        "title": "Quiz - Domma CMS"
+      }
+    ],
+    "views": {
+      "plugin-quiz": {
+        "entry": "quiz/admin/views/quiz.js?v=5be1f180",
+        "exportName": "quizView"
+      }
+    }
+  }
+}

package/plugins/quiz/public/quiz.css

@@ -0,0 +1 @@
+.qz-q{font-size:1.35rem;line-height:1.35;margin:0 0 1rem;outline:none}.qz-image{display:block;max-width:100%;max-height:320px;border-radius:8px;margin:0 0 1rem}.qz-hint{margin:-.5rem 0 .75rem}.qz-options{display:grid;gap:.6rem}@media(min-width:640px){.qz-options{grid-template-columns:1fr 1fr}}.qz-option{display:flex;align-items:center;gap:.75rem;width:100%;text-align:left;font:inherit;cursor:pointer;padding:.8rem 1rem;border-radius:10px;border:2px solid var(--gm-line);background:var(--gm-soft);color:inherit;transition:border-color .12s,transform .12s}.qz-option:hover:not(:disabled){border-color:var(--gm-accent);transform:translateY(-1px)}.qz-option:focus-visible{outline:2px solid var(--gm-accent);outline-offset:2px}.qz-option:disabled{cursor:default;opacity:.7}.qz-option.is-picked{border-color:var(--gm-accent);background:color-mix(in srgb,var(--gm-accent) 15%,transparent)}.qz-letter{flex:none;display:inline-grid;place-items:center;width:1.8rem;height:1.8rem;border-radius:50%;background:var(--gm-accent);color:#fff;font-weight:700;font-size:.9rem}.qz-typed{display:flex;flex-direction:column;gap:.35rem;max-width:420px}.qz-verdict{font-size:1.8rem;margin:0 0 .5rem;outline:none}.qz-verdict.is-right{color:var(--gm-good)}.qz-verdict.is-wrong{color:var(--gm-bad)}.qz-review{margin-top:1.5rem}.qz-review h3{margin:0 0 .5rem;font-size:1.1rem}.qz-review-list{margin:0;padding-left:0;list-style:none;display:grid;gap:.5rem}.qz-review-list li{padding:.6rem .8rem;border-radius:8px;border-left:4px solid var(--gm-line);background:var(--gm-soft)}.qz-review-list li.is-right{border-left-color:var(--gm-good)}.qz-review-list li.is-wrong{border-left-color:var(--gm-bad)}.qz-review-q{margin:0 0 .25rem;font-weight:600}.qz-review-a{margin:0}.qz-live{position:absolute;left:-9999px}