domma-cms 1.8.32 → 1.8.34

package/plugins/quiz/docs/guide.md

@@ -0,0 +1,61 @@
+---
+title: Guide
+order: 1
+---
+
+Run quizzes on your website. Visitors type their name, answer against the clock and land on a leaderboard. Quiz is free.
+
+## What it does
+
+- **Four kinds of question:** one right answer, more than one right answer, true or false, and a typed answer (case, accents, punctuation and a leading "the" do not matter, and you can accept more than one spelling).
+- **Timing kept by the server.** A time limit for the whole quiz, a default per question, or a time on any single question. The clock starts when the question is shown, so a slow connection or a reload does not cost or gain anyone time.
+- **Marking on the server.** The right answers never reach the visitor's browser until they have answered.
+- **Leaderboards** for today, this week, this month and all time. Each name appears once, with its best go. Equal scores are split by time.
+- **Your choice of when to show answers:** after each question, at the end, or never.
+- **Shuffling:** questions, answers, or a random draw of so many questions from a bigger bank.
+- **Opening and closing times**, and a limit on goes per name.
+- The sidebar badge shows how many quizzes have been finished today, and you get a notification when someone takes the top spot.
+
+## Getting started
+
+1. Switch Quiz on in **Tools**.
+2. Open **Tools > Games > Quiz** and choose **New quiz**.
+3. Give it a title and add your questions. Tick the right answer (or answers) on each one.
+4. Press **Test** and play it yourself (see below).
+5. Set the status to **Open** and save.
+6. Put it on any page:
+
+```
+[quiz id="capitals" /]
+```
+
+`id` is the quiz's short name, shown in the list and under the title in the editor.
+
+## Testing a quiz
+
+**Test** (in the editor, on each quiz in the list, and on its Plays screen) plays the quiz right there in the admin, exactly as your players will see it: the same clock, the same marking, the same screens, and the answers shown when the quiz shows them.
+
+- It plays the version you last saved. With unsaved changes the button says **Save and test**, and saves first.
+- It works whatever the status, so you can try a draft before anyone can see it, or a closed quiz.
+- A test go is never saved to the leaderboard. It is not in the Plays list, it does not count towards the goes each name is allowed, and it does not raise a notification. At the end it tells you where it would have come.
+- Each new test clears away the one before.
+
+## A leaderboard on its own
+
+The quiz shows its own leaderboard at the end. To show one somewhere else, for example on your home page:
+
+```
+[quiz-leaderboard id="capitals" period="week" limit="10" title="This week's best" /]
+```
+
+`period` is `today`, `week`, `month` or `all`. Visitors can switch period on the board.
+
+## Players and fair play
+
+- Players only give a name: 2 to 24 letters, numbers, spaces and `. ' - _`. Rude names are refused.
+- A play belongs to the browser that started it. Reloading carries on where they were.
+- Running out of time on a question marks it wrong and moves on. Running out of time on the whole quiz ends it, and the time counted is the limit.
+
+## Looking after the board
+
+Open a quiz's **Plays** to see every go (your own test goes are not shown). You can hide a play from the leaderboard (it stays in the list), delete it, or reset the whole leaderboard, for example before a new quiz night.

package/plugins/quiz/inject/body.html

@@ -1 +1 @@
-<script type="module" src="/plugins/quiz/public/quiz.js?v=1.0.0"></script>
+<script type="module" src="/plugins/quiz/public/quiz.js?v=1.1.0"></script>

package/plugins/quiz/plugin.js

@@ -6,6 +6,9 @@
  *   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/test           what the player's start screen shows, as if it were open
+ *   POST /quizzes/:id/test           a TEST play of it as saved (draft or closed too) -> {playId, token, name, info};
+ *                                    played through the /public/play routes, never on a board (see _lib/games/plays.js)
  *   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:
@@ -21,7 +24,7 @@
  */
 
 import {cleanPlayerName} from '../_lib/games/names.js';
-import {boardQuery, fail, isBot, limited, mountPlayAdmin, todayBadge, tokenOf} from '../_lib/games/http.js';
+import {boardQuery, fail, isBot, limited, mountPlayAdmin, testerName, 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';
@@ -97,7 +100,7 @@ export default async function quizPlugin(fastify, options) {
 
     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)))
+        return {quizzes: (await allQuizzes()).map(q => summary(q, everyPlay.filter(p => p.gameId === q.id && p.test !== true)))
             .sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)))};
     });
 
@@ -134,6 +137,29 @@ export default async function quizPlugin(fastify, options) {
 
     mountPlayAdmin(fastify, {store: plays, base: '/quizzes', can, exists: async (id) => Boolean(await getQuiz(id))});
 
+    // The admin tries the quiz from the Tool: the saved version, whatever its status or dates, through
+    // the same player routes as anyone. The play is marked `test`, so it never counts anywhere.
+    const testInfo = (quiz) => ({...publicInfo(quiz), open: true, reason: ''});
+
+    fastify.get('/quizzes/:id/test', 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.');
+        return {info: testInfo(quiz)};
+    });
+
+    fastify.post('/quizzes/:id/test', 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.');
+        if (!quiz.questions?.length) return fail(reply, 409, 'Add a question and save, then test it.', {code: 'empty'});
+        await plays.clearTests(quiz.id);
+        const plan = planPlay(quiz);
+        const name = testerName(request);
+        const play = await plays.start({gameId: quiz.id, name, maxScore: maxScoreOf(quiz, plan), state: plan,
+            userId: String(request.user?.id || ''), test: true});
+        return reply.code(201).send({playId: play.id, token: play.token, name, total: plan.order.length, maxScore: play.maxScore,
+            info: testInfo(quiz)});
+    });
+
     // ---- Players ----------------------------------------------------------------
 
     /** A quiz the public may see: anything but a draft. */
@@ -175,6 +201,9 @@ export default async function quizPlugin(fastify, options) {
      * The play behind a request, brought up to date with the clock (and saved
      * when that changed it). Null after answering with the reason.
      */
+    /** The play went while this request was on its way (a reset, a delete, or the next test clearing it). */
+    const gone = (reply) => fail(reply, 404, 'That game is not here any more. Start again.', {code: 'gone'});
+
     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; }
@@ -186,6 +215,7 @@ export default async function quizPlugin(fastify, options) {
             const b = serveNow && serve(quiz, p, now);
             return a || b ? p : null;
         });
+        if (!play) { gone(reply); return null; }
         if (play.status === 'finished' && opened.status === 'playing') await afterFinish(quiz, play);
         return {quiz, play, now};
     }
@@ -193,7 +223,7 @@ export default async function quizPlugin(fastify, options) {
     /** 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;
+            if (play.test || !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`,
@@ -217,6 +247,7 @@ export default async function quizPlugin(fastify, options) {
             outcome = answer(quiz, p, request.body?.q, request.body?.answer, Date.now());
             return outcome.error ? null : p;
         });
+        if (!play) return gone(reply);
         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)};
@@ -231,8 +262,11 @@ export default async function quizPlugin(fastify, options) {
             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,
+            test: play.test === true,
+            place: quiz.leaderboard && !play.hidden && !play.test ? await plays.placeOf(play, 'all') : 0,
+            placeToday: quiz.leaderboard && !play.hidden && !play.test ? await plays.placeOf(play, 'today') : 0,
+            // A test is on no board; this is where it would have come.
+            wouldPlace: quiz.leaderboard && play.test ? await plays.placeOf(play, 'all') : 0,
             leaderboard: quiz.leaderboard,
             review: review(quiz, play)
         };

package/plugins/quiz/plugin.json

@@ -1,11 +1,12 @@
 {
   "name": "quiz",
   "displayName": "Quiz",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "tier": "free",
+  "minCmsVersion": "1.8.33",
   "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",
+  "date": "2026-10-21",
   "icon": "help-circle",
   "permissions": [
     {
@@ -70,7 +71,7 @@
     ],
     "views": {
       "plugin-quiz": {
-        "entry": "quiz/admin/views/quiz.js?v=5be1f180",
+        "entry": "quiz/admin/views/quiz.js?v=1.1.0",
         "exportName": "quizView"
       }
     }

package/plugins/quiz/public/quiz.css

@@ -1 +1,36 @@
-.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}
+/* Quiz - the player. Shared pieces (cards, clock, leaderboard) are in /plugins/_lib/public/games/games.css. */
+
+.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; }

package/plugins/quiz/public/quiz.js

@@ -1,7 +1,32 @@
-import{Countdown as C,addStyles as N,celebrate as Y,configOf as Q,fmtDuration as $,memory as f,mountBoards as W,mountLeaderboard as B,ordinal as I,request as h,uid as D}from"/plugins/_lib/public/games/games.js";const s=window.M,c="/api/plugins/quiz/public",A="games.name",z=n=>`quiz.play.${n}`,F=`
+/**
+ * Quiz - the player, in the browser.
+ *
+ * Mounts on every `[data-quiz]` placeholder the [quiz] shortcode wrote, and
+ * every `[data-quiz-board]` the [quiz-leaderboard] one wrote. The quiz runs on
+ * the SERVER: this asks for one question at a time (never with its answer),
+ * sends each answer to be marked, and shows the clock the server keeps. A play
+ * in progress is remembered for the tab's next load, so a reload carries on
+ * where it was - its clock never stopped.
+ *
+ * domma-reactive (window.M): one template per mount, one M.applyBindings, and
+ * text from the server only through bindings.
+ *
+ * `mount(el, {test})` is the same player for an admin testing the quiz from
+ * its Tool: `test.info()` and `test.start()` go through the admin's own API,
+ * the play is a test one (never on a board), and nothing is remembered.
+ */
+
+import {Countdown, addStyles, celebrate, configOf, fmtDuration, memory, mountBoards, mountLeaderboard, ordinal, request, uid} from '/plugins/_lib/public/games/games.js';
+
+const M = window.M;
+const API = '/api/plugins/quiz/public';
+const NAME_KEY = 'games.name';
+const playKey = (slug) => `quiz.play.${slug}`;
+
+const TEMPLATE = `
 <p class="gm-muted qz-live" role="status" aria-live="polite" data-bind-text="live.value"></p>
 
-<section class="gm-card" hidden data-bind-hidden="screen.value !== 'loading'"><p class="gm-muted">Loading the quiz\u2026</p></section>
+<section class="gm-card" hidden data-bind-hidden="screen.value !== 'loading'"><p class="gm-muted">Loading the quiz…</p></section>
 
 <section class="gm-card" hidden data-bind-hidden="screen.value !== 'error'">
   <p class="gm-error" data-bind-text="problem.value"></p>
@@ -13,13 +38,14 @@ import{Countdown as C,addStyles as N,celebrate as Y,configOf as Q,fmtDuration as
   <ul class="gm-facts" data-each="facts.value key=k"><li data-bind-text="k"></li></ul>
   <p class="gm-note" hidden data-bind-hidden="info.value.open" data-bind-text="info.value.reason"></p>
   <form class="gm-start" hidden data-bind-hidden="!info.value.open" data-on-submit="start" novalidate>
-    <div class="gm-field">
+    <p class="gm-note gm-test-note" hidden data-bind-hidden="!testing">A test go: it plays exactly as your players see it, and it is not saved to the leaderboard.</p>
+    <div class="gm-field" hidden data-bind-hidden="testing">
       <label for="%U%-name">Your name</label>
       <input id="%U%-name" class="gm-input" maxlength="24" autocomplete="nickname" data-model="name.value"
         data-bind-aria-invalid="problem.value ? 'true' : false" aria-describedby="%U%-err">
     </div>
     <div class="gm-hp" aria-hidden="true"><label>Website <input tabindex="-1" autocomplete="off" data-model="website.value"></label></div>
-    <button type="submit" class="btn btn-primary" data-bind-disabled="busy.value">Start the quiz</button>
+    <button type="submit" class="btn btn-primary" data-bind-disabled="busy.value" data-bind-text="testing ? 'Start the test' : 'Start the quiz'">Start the quiz</button>
   </form>
   <p class="gm-error" id="%U%-err" hidden data-bind-hidden="!problem.value" data-bind-text="problem.value"></p>
 </section>
@@ -62,7 +88,7 @@ import{Countdown as C,addStyles as N,celebrate as Y,configOf as Q,fmtDuration as
   <p class="gm-muted" data-bind-text="res.value.detail"></p>
   <p class="gm-result-place" hidden data-bind-hidden="!res.value.placeText" data-bind-text="res.value.placeText"></p>
   <div class="gm-actions">
-    <button type="button" class="btn btn-primary" data-on-click="again">Play again</button>
+    <button type="button" class="btn btn-primary" data-on-click="again" data-bind-text="testing ? 'Test again' : 'Play again'">Play again</button>
   </div>
   <div class="qz-review" hidden data-bind-hidden="!review.value.length">
     <h3>Your answers</h3>
@@ -77,4 +103,270 @@ import{Countdown as C,addStyles as N,celebrate as Y,configOf as Q,fmtDuration as
   </div>
 </section>
 
-<div class="qz-board-slot"></div>`,H="ABCDEFGH";function K(n){const l=[`${n.questions} question${n.questions===1?"":"s"}`];return n.timeLimit&&l.push(`${$(n.timeLimit*1e3)} to finish`),n.questionSeconds?l.push(`${n.questionSeconds} seconds a question`):n.perQuestionTimes&&l.push("Some questions are timed"),n.attemptsPerName===1?l.push("One go each"):n.attemptsPerName>1&&l.push(`${n.attemptsPerName} goes each`),n.leaderboard&&l.push("Fastest top score wins"),l.map(g=>({k:g}))}function G(n){const l=Q(n,"data-quiz");if(!l?.slug||!s)return;N(["/plugins/quiz/public/quiz.css?v=1.0.0"]);const g=D("qz");n.innerHTML=F.replaceAll("%U%",g);const t={screen:s.observable("loading"),live:s.observable(""),problem:s.observable(""),busy:s.observable(!1),info:s.observable({title:"",intro:"",open:!1,reason:""}),facts:s.observable([]),name:s.observable(String(f.get(A)||"")),website:s.observable(""),progress:s.observable(""),q:s.observable({text:"",kind:"single",image:""}),options:s.observable([]),typed:s.observable(""),clockText:s.observable(""),clockShown:s.observable(!1),clockLow:s.observable(!1),trackWidth:s.observable("0%"),fb:s.observable({}),res:s.observable({}),review:s.observable([])};let r=f.get(z(l.slug))||null,k=null,d=null,u=null,m=null;const b=e=>setTimeout(()=>n.querySelector(`#${g}-${e}`)?.focus({preventScroll:!1}),30),q=e=>{t.live.value="",setTimeout(()=>{t.live.value=e},20)};function T(){const e=u?.left.peek()??0,i=m?.left.peek()??0,a=d?.questionLeftMs!=null&&(d?.totalLeftMs==null||e<=i),o=a?e:i,M=a?(d?.question?.seconds||0)*1e3:(t.info.peek().timeLimit||0)*1e3;t.clockShown.value=d?.questionLeftMs!=null||d?.totalLeftMs!=null,t.clockText.value=$(o),t.clockLow.value=o>0&&o<=5e3,t.trackWidth.value=M?`${Math.max(0,Math.min(100,o/M*100)).toFixed(1)}%`:`${(d?.index||0)/(d?.total||1)*100}%`}function y(){u?.stop(),m?.stop()}u=new C(()=>{t.screen.peek()==="question"&&v(null,{timeout:!0})}),m=new C(()=>{["question","feedback"].includes(t.screen.peek())&&setTimeout(p,600)});const R=s.effect(()=>{u.left.value,m.left.value,T()});function x(){f.remove(z(l.slug)),r=null}async function L(){const e=await h(`${c}/quiz/${encodeURIComponent(l.slug)}`);return t.info.value=e,t.facts.value=K(e),e.leaderboard&&!k&&(k=B(n.querySelector(".qz-board-slot"),{url:`${c}/quiz/${encodeURIComponent(l.slug)}/leaderboard`,limit:e.leaderboardSize,title:"Leaderboard"})),e}async function p(){if(!r){t.screen.value="intro";return}try{const e=await h(`${c}/play/${encodeURIComponent(r.playId)}`,{token:r.token});if(d=e,e.status!=="playing")return y(),w();E(e)}catch(e){if(e.code==="gone"||e.status===404){x(),t.screen.value="intro";return}t.problem.value=e.message,t.screen.value="error"}}function E(e){const i=e.question;t.q.value={text:i.text,kind:i.kind,image:i.image||""},t.options.value=i.options.map((a,o)=>({id:a.id,text:a.text,letter:H[o]||"",picked:!1})),t.typed.value="",t.progress.value=`Question ${e.index+1} of ${e.total}`,t.busy.value=!1,t.screen.value="question",u.start(e.questionLeftMs??0),m.start(e.totalLeftMs??0),T(),i.kind==="text"?b("typed"):b("q"),q(`Question ${e.index+1} of ${e.total}. ${i.text}`)}async function v(e,{timeout:i=!1}={}){if(!(t.busy.peek()||!d?.question)){t.busy.value=!0,u.stop();try{const a=await h(`${c}/play/${encodeURIComponent(r.playId)}/answer`,{method:"POST",token:r.token,body:{q:d.question.id,answer:e}});d=a.play;const o=a.play.status!=="playing";if(a.feedback){t.fb.value={correct:a.correct,title:a.correct?"Right!":i||a.late?"Out of time":"Not quite",rightAnswer:a.feedback.rightAnswer,explanation:a.feedback.explanation,nextLabel:o?"See your score":"Next question"},t.screen.value="feedback",q(t.fb.peek().title),b("fb");return}if(o)return y(),w();await p()}catch(a){if(a.code==="not-current"||a.code==="finished")return p();t.busy.value=!1,t.live.value=a.message}}}async function w(){y();try{const e=await h(`${c}/play/${encodeURIComponent(r.playId)}/result`,{token:r.token}),i=e.place?`You came ${I(e.place)} of all time${e.placeToday&&e.placeToday!==e.place?`, ${I(e.placeToday)} today`:""}.`:"";t.res.value={title:e.timeUp?`Time's up, ${e.name}!`:`Well done, ${e.name}!`,scoreText:`${e.score} / ${e.maxScore}`,detail:`${e.correct} of ${e.total} right in ${$(e.timeMs)}.`,placeText:i},t.review.value=(e.review||[]).map((a,o)=>({k:`r${o}`,text:`${o+1}. ${a.text}`,correct:a.correct,right:a.right,explanation:a.explanation,mark:a.correct?"\u2713":"\u2717",yoursText:a.yours?`You said: ${a.yours}`:a.late?"Out of time":"No answer"})),t.screen.value="result",q(`${t.res.peek().title} ${t.res.peek().detail} ${i}`),b("res"),k?.refresh(r.playId),e.place===1&&Y()}catch(e){if(e.status===404){x(),t.screen.value="intro";return}t.problem.value=e.message,t.screen.value="error"}}async function O(){if(!t.busy.peek()){t.problem.value="",t.busy.value=!0;try{const e=await h(`${c}/quiz/${encodeURIComponent(l.slug)}/start`,{method:"POST",body:{name:t.name.peek(),website:t.website.peek()}});f.set(A,e.name),r={playId:e.playId,token:e.token},f.set(z(l.slug),r),await p()}catch(e){t.problem.value=e.message,t.busy.value=!1,b("name")}}}const U={start(){return O(),!1},choose(e){if(!t.busy.peek()){if(t.q.peek().kind==="multiple"){t.options.value=t.options.peek().map(i=>i.id===e.id?{...i,picked:!i.picked}:i);return}v(e.id)}},sendPicked(){if(t.q.peek().kind==="text")return v(t.typed.peek());v(t.options.peek().filter(e=>e.picked).map(e=>e.id))},sendTyped(){return v(t.typed.peek()),!1},next(){if(d?.status!=="playing")return w();p()},async again(){x(),t.problem.value="",t.busy.value=!1,await L().catch(()=>{}),t.screen.value="intro",b("name")}};s.applyBindings({...t,...U},n,{methods:U}),L().then(p).catch(e=>{t.problem.value=e.status===404?"This quiz is not available.":e.message,t.screen.value="error"});const S=new MutationObserver(()=>{n.isConnected||(y(),R?.(),S.disconnect())});S.observe(document.body,{childList:!0,subtree:!0})}function P(){for(const n of document.querySelectorAll("[data-quiz]"))n.dataset.gmMounted||(n.dataset.gmMounted="1",G(n));W("data-quiz-board",n=>`${c}/quiz/${encodeURIComponent(n)}/leaderboard`)}document.readyState==="loading"?document.addEventListener("DOMContentLoaded",P):P();
+<div class="qz-board-slot"></div>`;
+
+const LETTERS = 'ABCDEFGH';
+
+/** The server's words: the public request's Error, or the admin's (its reply is on `err.body`). */
+const errText = (err) => err?.body?.error || err?.message || String(err);
+
+function facts(info) {
+    const out = [`${info.questions} question${info.questions === 1 ? '' : 's'}`];
+    if (info.timeLimit) out.push(`${fmtDuration(info.timeLimit * 1000)} to finish`);
+    if (info.questionSeconds) out.push(`${info.questionSeconds} seconds a question`);
+    else if (info.perQuestionTimes) out.push('Some questions are timed');
+    if (info.attemptsPerName === 1) out.push('One go each');
+    else if (info.attemptsPerName > 1) out.push(`${info.attemptsPerName} goes each`);
+    if (info.leaderboard) out.push('Fastest top score wins');
+    return out.map(k => ({k}));
+}
+
+/**
+ * @param {HTMLElement} el
+ * @param {{test?: {info: () => Promise<object>, start: () => Promise<{playId: string, token: string, name: string, info: object}>}}} [opts]
+ */
+export function mount(el, {test = null} = {}) {
+    const cfg = test ? {slug: 'test'} : configOf(el, 'data-quiz');
+    if (!cfg?.slug || !M) return;
+    addStyles(['/plugins/quiz/public/quiz.css?v=1.1.0']);
+    const U = uid('qz');
+    el.innerHTML = TEMPLATE.replaceAll('%U%', U);
+
+    const s = {
+        testing: Boolean(test),
+        screen: M.observable('loading'),
+        live: M.observable(''),
+        problem: M.observable(''),
+        busy: M.observable(false),
+        info: M.observable({title: '', intro: '', open: false, reason: ''}),
+        facts: M.observable([]),
+        name: M.observable(String(memory.get(NAME_KEY) || '')),
+        website: M.observable(''),
+        progress: M.observable(''),
+        q: M.observable({text: '', kind: 'single', image: ''}),
+        options: M.observable([]),
+        typed: M.observable(''),
+        clockText: M.observable(''),
+        clockShown: M.observable(false),
+        clockLow: M.observable(false),
+        trackWidth: M.observable('0%'),
+        fb: M.observable({}),
+        res: M.observable({}),
+        review: M.observable([])
+    };
+
+    let play = test ? null : memory.get(playKey(cfg.slug)) || null;   // {playId, token}
+    let board = null;
+    let current = null;                                   // the play's last view from the server
+    let qClock = null;
+    let totalClock = null;
+
+    const focus = (id) => setTimeout(() => el.querySelector(`#${U}-${id}`)?.focus({preventScroll: false}), 30);
+    const say = (t) => { s.live.value = ''; setTimeout(() => { s.live.value = t; }, 20); };
+
+    function showClock() {
+        const qLeft = qClock?.left.peek() ?? 0;
+        const tLeft = totalClock?.left.peek() ?? 0;
+        const useQ = current?.questionLeftMs != null && (current?.totalLeftMs == null || qLeft <= tLeft);
+        const left = useQ ? qLeft : tLeft;
+        const whole = useQ ? (current?.question?.seconds || 0) * 1000 : (s.info.peek().timeLimit || 0) * 1000;
+        s.clockShown.value = current?.questionLeftMs != null || current?.totalLeftMs != null;
+        s.clockText.value = fmtDuration(left);
+        s.clockLow.value = left > 0 && left <= 5000;
+        s.trackWidth.value = whole ? `${Math.max(0, Math.min(100, (left / whole) * 100)).toFixed(1)}%` : `${((current?.index || 0) / (current?.total || 1)) * 100}%`;
+    }
+
+    function stopClocks() {
+        qClock?.stop();
+        totalClock?.stop();
+    }
+
+    qClock = new Countdown(() => { if (s.screen.peek() === 'question') send(null, {timeout: true}); });
+    totalClock = new Countdown(() => { if (['question', 'feedback'].includes(s.screen.peek())) setTimeout(load, 600); });
+    const stopTicks = M.effect(() => { qClock.left.value; totalClock.left.value; showClock(); });
+
+    function forget() {
+        if (!test) memory.remove(playKey(cfg.slug));
+        play = null;
+    }
+
+    async function loadInfo() {
+        const info = test ? await test.info() : await request(`${API}/quiz/${encodeURIComponent(cfg.slug)}`);
+        s.info.value = info;
+        s.facts.value = facts(info);
+        if (info.leaderboard && !board && !test) {
+            board = mountLeaderboard(el.querySelector('.qz-board-slot'), {url: `${API}/quiz/${encodeURIComponent(cfg.slug)}/leaderboard`, limit: info.leaderboardSize, title: 'Leaderboard'});
+        }
+        return info;
+    }
+
+    /** Where the play is now, from the server; draws the screen that goes with it. */
+    async function load() {
+        if (!play) { s.screen.value = 'intro'; return; }
+        try {
+            const v = await request(`${API}/play/${encodeURIComponent(play.playId)}`, {token: play.token});
+            current = v;
+            if (v.status !== 'playing') { stopClocks(); return showResult(); }
+            drawQuestion(v);
+        } catch (err) {
+            if (err.code === 'gone' || err.status === 404) { forget(); s.screen.value = 'intro'; return; }
+            s.problem.value = err.message;
+            s.screen.value = 'error';
+        }
+    }
+
+    function drawQuestion(v) {
+        const q = v.question;
+        s.q.value = {text: q.text, kind: q.kind, image: q.image || ''};
+        s.options.value = q.options.map((o, i) => ({id: o.id, text: o.text, letter: LETTERS[i] || '', picked: false}));
+        s.typed.value = '';
+        s.progress.value = `Question ${v.index + 1} of ${v.total}`;
+        s.busy.value = false;
+        s.screen.value = 'question';
+        qClock.start(v.questionLeftMs ?? 0);
+        totalClock.start(v.totalLeftMs ?? 0);
+        showClock();
+        if (q.kind === 'text') focus('typed');
+        else focus('q');
+        say(`Question ${v.index + 1} of ${v.total}. ${q.text}`);
+    }
+
+    async function send(answer, {timeout = false} = {}) {
+        if (s.busy.peek() || !current?.question) return;
+        s.busy.value = true;
+        qClock.stop();
+        try {
+            const r = await request(`${API}/play/${encodeURIComponent(play.playId)}/answer`, {
+                method: 'POST', token: play.token, body: {q: current.question.id, answer}
+            });
+            current = r.play;
+            const done = r.play.status !== 'playing';
+            if (r.feedback) {
+                s.fb.value = {
+                    correct: r.correct,
+                    title: r.correct ? 'Right!' : timeout || r.late ? 'Out of time' : 'Not quite',
+                    rightAnswer: r.feedback.rightAnswer, explanation: r.feedback.explanation,
+                    nextLabel: done ? 'See your score' : 'Next question'
+                };
+                s.screen.value = 'feedback';
+                say(s.fb.peek().title);
+                focus('fb');
+                return;
+            }
+            if (done) { stopClocks(); return showResult(); }
+            // The next question's clock starts when the server hands it over, so ask for it.
+            await load();
+        } catch (err) {
+            if (err.code === 'not-current' || err.code === 'finished') return load();
+            s.busy.value = false;
+            s.live.value = err.message;
+        }
+    }
+
+    async function showResult() {
+        stopClocks();
+        try {
+            const r = await request(`${API}/play/${encodeURIComponent(play.playId)}/result`, {token: play.token});
+            const placeText = r.test
+                ? `A test go, so it is not on the leaderboard.${r.wouldPlace ? ` It would have come ${ordinal(r.wouldPlace)} of all time.` : ''}`
+                : r.place ? `You came ${ordinal(r.place)} of all time${r.placeToday && r.placeToday !== r.place ? `, ${ordinal(r.placeToday)} today` : ''}.` : '';
+            s.res.value = {
+                title: r.timeUp ? `Time's up, ${r.name}!` : `Well done, ${r.name}!`,
+                scoreText: `${r.score} / ${r.maxScore}`,
+                detail: `${r.correct} of ${r.total} right in ${fmtDuration(r.timeMs)}.`,
+                placeText
+            };
+            s.review.value = (r.review || []).map((x, i) => ({
+                k: `r${i}`, text: `${i + 1}. ${x.text}`, correct: x.correct, right: x.right, explanation: x.explanation,
+                mark: x.correct ? '✓' : '✗', yoursText: x.yours ? `You said: ${x.yours}` : x.late ? 'Out of time' : 'No answer'
+            }));
+            s.screen.value = 'result';
+            say(`${s.res.peek().title} ${s.res.peek().detail} ${placeText}`);
+            focus('res');
+            board?.refresh(play.playId);
+            if (r.place === 1 && !r.test) celebrate();
+        } catch (err) {
+            if (err.status === 404) { forget(); s.screen.value = 'intro'; return; }
+            s.problem.value = err.message;
+            s.screen.value = 'error';
+        }
+    }
+
+    async function begin() {
+        if (s.busy.peek()) return;
+        s.problem.value = '';
+        s.busy.value = true;
+        try {
+            const r = test ? await test.start() : await request(`${API}/quiz/${encodeURIComponent(cfg.slug)}/start`, {
+                method: 'POST', body: {name: s.name.peek(), website: s.website.peek()}
+            });
+            play = {playId: r.playId, token: r.token};
+            if (test) {
+                if (r.info) { s.info.value = r.info; s.facts.value = facts(r.info); }
+            } else {
+                memory.set(NAME_KEY, r.name);
+                memory.set(playKey(cfg.slug), play);
+            }
+            await load();
+        } catch (err) {
+            s.problem.value = errText(err);
+            s.busy.value = false;
+            if (!test) focus('name');
+        }
+    }
+
+    const methods = {
+        // Form handlers answer false at once (no native submit, no reload); the work runs after.
+        start() { begin(); return false; },
+        choose(opt) {
+            if (s.busy.peek()) return;
+            if (s.q.peek().kind === 'multiple') {
+                s.options.value = s.options.peek().map(o => (o.id === opt.id ? {...o, picked: !o.picked} : o));
+                return;
+            }
+            send(opt.id);
+        },
+        sendPicked() {
+            if (s.q.peek().kind === 'text') return send(s.typed.peek());
+            send(s.options.peek().filter(o => o.picked).map(o => o.id));
+        },
+        sendTyped() { send(s.typed.peek()); return false; },
+        next() {
+            if (current?.status !== 'playing') return showResult();
+            load();
+        },
+        async again() {
+            forget();
+            s.problem.value = '';
+            s.busy.value = false;
+            await loadInfo().catch(() => {});
+            s.screen.value = 'intro';
+            focus('name');
+        }
+    };
+
+    const bindings = M.applyBindings({...s, ...methods}, el, {methods});
+
+    loadInfo().then(load).catch((err) => {
+        s.problem.value = err.status === 404 ? 'This quiz is not available.' : errText(err);
+        s.screen.value = 'error';
+    });
+
+    // Gone from the page (an SPA swap): stop the clocks.
+    const dispose = () => { stopClocks(); stopTicks?.(); board?.dispose(); bindings?.dispose?.(); watch.disconnect(); };
+    const watch = new MutationObserver(() => { if (!el.isConnected) dispose(); });
+    watch.observe(document.body, {childList: true, subtree: true});
+    return {dispose};
+}
+
+function mountAll() {
+    for (const el of document.querySelectorAll('[data-quiz]')) {
+        if (el.dataset.gmMounted) continue;
+        el.dataset.gmMounted = '1';
+        mount(el);
+    }
+    mountBoards('data-quiz-board', (slug) => `${API}/quiz/${encodeURIComponent(slug)}/leaderboard`);
+}
+
+if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', mountAll);
+else mountAll();

package/plugins/theme-roller/CLAUDE.md

@@ -0,0 +1,65 @@
+# Theme Roller
+
+Makes custom themes - a built-in Domma theme plus the `--dm-*` tokens changed on top - and offers them to
+the CMS with `hooks.registerThemes` (domma-cms 0.73+). The CMS does the rest: they are listed under
+Custom themes in Content › Theme and applied as `dm-theme-<base> dm-custom-<id>` (core
+`server/services/themeSettings.js`, "Custom themes"). This plugin only stores them and offers them.
+
+## Files
+
+- `plugin.js` - API + provider. Themes live in `data/themes/<id>.json` (a site's own, declared in
+  `contentPaths`, never shipped); an in-memory Map mirrors them so the provider - called on every page
+  render - never touches disk. Writes are tmp+rename. "Use" goes through the core's `saveThemeConfig`.
+- `admin/lib/themes.js` - PURE, shared by server and browser: slug/unique ids (never a built-in id),
+  cleaning tokens (same safe-value rule as the core), `usageOf`, `withoutTheme` (delete in use -> base),
+  `themeCss` (export).
+- `admin/views/theme-roller-view.js`, `admin/templates/theme-roller.html`, `admin/css/theme-roller.css`.
+- **The Custom CSS tab** edits the site-wide `content/custom.css` (inlined into every public page after the
+  theme) through CORE's `GET/PUT /api/settings/custom-css` - not this plugin's API - so it needs the
+  `settings.update` permission (Site Settings > Edit); without it the tab cannot load or save. The box stays
+  locked until the file has loaded (saving an empty box would replace the whole file); Ctrl+S saves.
+- `tests/themes.test.js` (pure), `tests/api.test.js` (API against the real core theme service -
+  snapshots and restores the CMS checkout's config/theme.json and site.json).
+
+A stored theme is `{id, label, baseTheme, changes, createdAt, updatedAt}`. Files from 1.0 (`name`, no
+label) load as id = label = name.
+
+## Gotchas (the ThemeRoller component, from Domma's tools bundle)
+
+- It re-themes the WHOLE admin while it runs (theme.set + a preview `<style>` on `body, :root` with
+  `!important`). The view takes the admin's `dm-custom-*` class off `<body>` while it runs, and on
+  leaving destroys the roller and re-applies the admin theme via the core's `admin-theme.js`.
+- There is NO `getBaseTheme()` (1.0 called it on Save and threw - that was "it doesn't save", along with
+  `data/themes/` never being created). The tools bundle has its OWN theme engine, so the roller's
+  dropdown and `Domma.theme.get()` can disagree: the base is `#theme-select`'s value (`currentBase`).
+- `loadPreset()` / `_refreshInputs()` wipe the changes. `loadInto` sets the base, builds a fresh
+  roller, puts `_changes` in place and re-renders its inputs (`_render` + accordion + `_bindEvents`),
+  falling back to `setAll` if those privates disappear. `_render` reads `_changes[var] || computed`.
+- E.prompt/E.confirm render HTML (sanitised): labels in the message go in `esc()`d. Never give a prompt its starting
+  value through `inputValue` (a `"` cuts it short) - use `promptWith` (admin/lib/prompt.js); a test bans it.
+- The public theme switcher cannot offer custom themes (the core refuses them there): a visitor can only switch
+  between built-in themes. Say so to a site owner who expects their custom theme in the switcher.
+
+## 1.2.0 (2026-10-15 Tool Upgrade, second pass)
+
+- Saved themes: All / In use / Not in use with counts, a search box, and core's skeleton on the first load
+  (`loading.js` at run time; `.trx-loading` keeps its text on an older core). `load()` checks `here()` after awaits.
+- **Saves never swallow newer edits**: `save()` compares what it sent (`base|changesKey`) with the roller after the
+  PUT and `saveCss()` the box with what it sent - anything changed meanwhile stays unsaved (and is drafted on leave).
+- **Drafts know their age**: the theme draft carries `was` (the theme's `updatedAt` when editing began) and the CSS
+  draft `cssWas` (the file as loaded or last saved). `staleNote()` (admin/lib/view.js, tests/view.test.js) adds to the
+  restore question when the theme was saved again or deleted since, or custom.css changed.
+
+## 1.2.1 - unsaved-work sweep
+
+The draft is per user (`theme-roller.drafts.<uid>`; the old shared `theme-roller.draft` is removed unread). Restore asks
+"Throw away the changes you left unsaved to …?" (OK throws away, Cancel/Escape keeps; `restoreQuestion` in
+admin/lib/view.js). A CSS draft whose file cannot be loaded is kept for next time, never dropped - `pendingCss` carries it
+into the leave write so unsaved theme changes cannot overwrite it. Row Enter and every menu action run a task later, so
+the Enter cannot answer the confirm they open.
+
+## 1.3.0 (2026-10-21): free
+
+`tier: free`, no `closedSource` - no licence is needed or checked any more (the engine only checks a
+`closedSource` plugin). Included in every hosted plan and free to self-host; not `bundle: false`, so the next
+`make sync-free-tier` ships it in the engine.