domma-cms 1.8.31 → 1.8.33

package/plugins/crossword/public/lib/layout.js

@@ -0,0 +1,199 @@
+/**
+ * Crossword - laying words out in a grid. PURE, and isomorphic: the admin
+ * builder runs it in the browser for a live preview, the server runs it again
+ * to check what it is given. It holds no puzzle, so it is safe to serve.
+ *
+ *   cleanAnswer("New York")      -> {letters: 'NEWYORK', enumeration: '3,4'}
+ *   generate(words, {seed})      -> {width, height, entries, unplaced}
+ *   solutionGrid(layout)         -> rows of letters ('' = a black square), or throws if entries clash
+ *   numberEntries(entries)       -> entries numbered in reading order
+ *
+ * The generator is greedy: longest words first, each placed where it crosses
+ * the most letters already down without touching any other word side by side,
+ * keeping the grid as square as it can. It tries a number of shuffles from the
+ * seed and keeps the best, so the same seed always gives the same grid.
+ *
+ * @module crossword/public/lib/layout
+ */
+
+export const MAX_WORDS = 60;
+export const MAX_LETTERS = 21;
+export const MIN_LETTERS = 2;
+
+/** Letters only, upper case, accents folded; the word lengths for the clue, e.g. "(3,4)". */
+export function cleanAnswer(raw) {
+    const words = String(raw ?? '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toUpperCase()
+        .split(/[\s-]+/).map(w => w.replace(/[^A-Z]/g, '')).filter(Boolean);
+    const letters = words.join('');
+    const hyphenated = /-/.test(String(raw ?? ''));
+    return {letters, enumeration: words.map(w => w.length).join(hyphenated ? '-' : ',')};
+}
+
+/** A small seeded random (mulberry32), so a seed always lays out the same grid. */
+export function seeded(seed) {
+    let a = (Number(seed) >>> 0) || 1;
+    return () => {
+        a = (a + 0x6D2B79F5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+
+const key = (r, c) => `${r},${c}`;
+const DIRS = {across: [0, 1], down: [1, 0]};
+
+/** One attempt: words in this order, placed greedily on an open board. */
+function attempt(words) {
+    const cells = new Map();   // "r,c" -> {ch, across: bool, down: bool}
+    const placed = [];
+    const unplaced = [];
+    let box = {r0: 0, r1: -1, c0: 0, c1: -1};
+
+    const at = (r, c) => cells.get(key(r, c));
+
+    function fits(w, r, c, dir) {
+        const [dr, dc] = DIRS[dir];
+        // The squares just before and after the word must be empty.
+        if (at(r - dr, c - dc) || at(r + dr * w.length, c + dc * w.length)) return -1;
+        let crossings = 0;
+        for (let i = 0; i < w.length; i++) {
+            const rr = r + dr * i;
+            const cc = c + dc * i;
+            const cell = at(rr, cc);
+            if (cell) {
+                if (cell.ch !== w[i] || cell[dir]) return -1;
+                crossings++;
+                continue;
+            }
+            // An empty square must not sit beside another word's letter (side by side, parallel).
+            if (at(rr + dc, cc + dr) || at(rr - dc, cc - dr)) return -1;
+        }
+        return crossings;
+    }
+
+    function put(w, r, c, dir, item) {
+        const [dr, dc] = DIRS[dir];
+        for (let i = 0; i < w.length; i++) {
+            const k = key(r + dr * i, c + dc * i);
+            const cell = cells.get(k) || {ch: w[i], across: false, down: false};
+            cell[dir] = true;
+            cells.set(k, cell);
+        }
+        const r1 = r + dr * (w.length - 1);
+        const c1 = c + dc * (w.length - 1);
+        box = placed.length
+            ? {r0: Math.min(box.r0, r), r1: Math.max(box.r1, r1), c0: Math.min(box.c0, c), c1: Math.max(box.c1, c1)}
+            : {r0: r, r1, c0: c, c1};
+        placed.push({...item, row: r, col: c, dir});
+    }
+
+    let queue = [...words];
+    let progress = true;
+    // Words that could not cross anything yet get another chance once more are down.
+    while (queue.length && progress) {
+        progress = false;
+        const left = [];
+        for (const item of queue) {
+            const w = item.letters;
+            if (!placed.length) { put(w, 0, 0, 'across', item); progress = true; continue; }
+            let best = null;
+            for (const [k, cell] of cells) {
+                const [cr, cc] = k.split(',').map(Number);
+                for (let i = 0; i < w.length; i++) {
+                    if (w[i] !== cell.ch) continue;
+                    for (const dir of ['across', 'down']) {
+                        if (cell[dir]) continue;
+                        const [dr, dc] = DIRS[dir];
+                        const r = cr - dr * i;
+                        const c = cc - dc * i;
+                        const crossings = fits(w, r, c, dir);
+                        if (crossings < 1) continue;
+                        const r1 = r + dr * (w.length - 1);
+                        const c1 = c + dc * (w.length - 1);
+                        const h = Math.max(box.r1, r1) - Math.min(box.r0, r) + 1;
+                        const wd = Math.max(box.c1, c1) - Math.min(box.c0, c) + 1;
+                        // More crossings, then a smaller, squarer grid.
+                        const score = crossings * 100 - (h * wd) / 4 - Math.abs(h - wd) * 2;
+                        if (!best || score > best.score) best = {score, r, c, dir};
+                    }
+                }
+            }
+            if (best) { put(w, best.r, best.c, best.dir, item); progress = true; }
+            else left.push(item);
+        }
+        queue = left;
+    }
+    unplaced.push(...queue);
+    return {placed, unplaced, box, crossings: [...cells.values()].filter(c => c.across && c.down).length};
+}
+
+/** Entries numbered in reading order: a square that starts any entry gets the next number. */
+export function numberEntries(entries) {
+    const starts = [...new Set(entries.map(e => key(e.row, e.col)))]
+        .map(k => k.split(',').map(Number)).sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    const num = new Map(starts.map(([r, c], i) => [key(r, c), i + 1]));
+    return entries.map(e => ({...e, number: num.get(key(e.row, e.col))}))
+        .sort((a, b) => (a.dir === b.dir ? a.number - b.number : a.dir === 'across' ? -1 : 1));
+}
+
+/**
+ * A layout from a list of {answer, clue}.
+ *
+ * @param {{answer: string, clue: string}[]} words
+ * @param {{seed?: number, tries?: number}} [opts]
+ * @returns {{width: number, height: number, entries: object[], unplaced: object[], seed: number}}
+ */
+export function generate(words, {seed = 1, tries = 40} = {}) {
+    const items = [];
+    const seen = new Set();
+    for (const w of (words || []).slice(0, MAX_WORDS)) {
+        const {letters, enumeration} = cleanAnswer(w?.answer);
+        if (letters.length < MIN_LETTERS || letters.length > MAX_LETTERS || seen.has(letters)) continue;
+        seen.add(letters);
+        items.push({answer: String(w.answer).trim(), letters, enumeration, clue: String(w?.clue ?? '').trim()});
+    }
+    if (!items.length) return {width: 0, height: 0, entries: [], unplaced: [], seed};
+
+    const rand = seeded(seed);
+    let best = null;
+    for (let t = 0; t < Math.max(1, tries); t++) {
+        // The first try is longest-first; the rest shuffle words of similar length.
+        const order = items.map(it => ({it, k: it.letters.length + (t ? rand() * 4 : 0)})).sort((a, b) => b.k - a.k).map(x => x.it);
+        const res = attempt(order);
+        const h = res.box.r1 - res.box.r0 + 1;
+        const w = res.box.c1 - res.box.c0 + 1;
+        const score = res.placed.length * 1000 + res.crossings * 10 - h * w / 2 - Math.abs(h - w) * 3;
+        if (!best || score > best.score) best = {...res, score, h, w};
+    }
+    const entries = numberEntries(best.placed.map(p => ({
+        answer: p.answer, letters: p.letters, enumeration: p.enumeration, clue: p.clue,
+        row: p.row - best.box.r0, col: p.col - best.box.c0, dir: p.dir
+    })));
+    return {width: best.w, height: best.h, entries, unplaced: best.unplaced.map(u => ({answer: u.answer, clue: u.clue})), seed};
+}
+
+/**
+ * The solution as rows of letters ('' = black). Throws when the entries do
+ * not fit the size or disagree about a square - a layout from anywhere but
+ * generate() is checked this way before it is saved.
+ */
+export function solutionGrid({width, height, entries}) {
+    const grid = Array.from({length: height}, () => Array(width).fill(''));
+    for (const e of entries) {
+        const [dr, dc] = DIRS[e.dir] || [];
+        if (dr === undefined) throw new Error('An entry has no direction.');
+        for (let i = 0; i < e.letters.length; i++) {
+            const r = e.row + dr * i;
+            const c = e.col + dc * i;
+            if (r < 0 || c < 0 || r >= height || c >= width) throw new Error(`"${e.answer}" runs off the grid.`);
+            if (grid[r][c] && grid[r][c] !== e.letters[i]) throw new Error(`"${e.answer}" clashes with another answer.`);
+            grid[r][c] = e.letters[i];
+        }
+    }
+    return grid;
+}
+
+/** The grid's shape for the player: '#' black, '.' a square to fill - no letters. */
+export const shapeOf = (grid) => grid.map(row => row.map(ch => (ch ? '.' : '#')).join(''));

package/plugins/free-tier.lock.json

@@ -1,6 +1,6 @@
 {
   "note": "Written by `make sync-free-tier` in dcms-marketplace. Do not edit these plugins here - edit them there and sync.",
-  "source": "dcms-marketplace@af8baa8",
+  "source": "dcms-marketplace@aac25e9",
   "plugins": {
     "blog": {
       "version": "1.10.1",
@@ -125,6 +125,27 @@
         "tests/pure.test.js": "8ba0c8f76b4c9efcc422f39ff29509612544d81f760025a4b9a5594af14e7bcf"
       }
     },
+    "crossword": {
+      "version": "1.1.0",
+      "files": {
+        "CLAUDE.md": "598736eec2dfa833f7bb84ca9376071d1143d98a5c01106d0ff453749af18e43",
+        "admin/css/index.css": "d8d32268504d5aefa9c5fbf48a0c67b978cdd01d3be0bc747205a001972e05db",
+        "admin/templates/crossword.html": "336b4a3b7efff1ab8004c0516d55f11ae2efdc98cb3b18133ea00ca07311e2aa",
+        "admin/views/crossword.js": "42f3aabd09483eddf34d25dae243a853c562a13348eafe4fc1977361c1b03f4e",
+        "collections/crossword-plays.json": "20577250f00ebe0f6503cc2aae83dba93d88381b76b0b1dbc76c7b856d4295ff",
+        "collections/crossword-puzzles.json": "1b70950c96e50ede4d6a0c8e59ca7767b3c684c1a7c68588dc6462e69dad596e",
+        "config.js": "7a15db33506a432f5c43a095366c2e82a3bd20ceded585fb4fb78b93ad6dff29",
+        "docs/guide.md": "1189300bbe20f032e9040fe027e84a6137ab560e2fe9b88219aba66ea336ec4d",
+        "inject/body.html": "9dad7927d5afbd5e53f1edaa4a420403cd2325ce908624f9643a087388c090ab",
+        "lib/crossword.js": "f8149db65fb3a7f82b2fbae6a9f8d3ceeeec95730e426cf6fc36ea058527df34",
+        "lib/store.js": "284b3b8abe9fdaa64a660d5ab0120856b893d166b28e8bda6cf0ef038baa74bc",
+        "plugin.js": "5c1885955d122200c7ff9629d7fb9fcb54c232edb4cec4658574ca90d73730e5",
+        "plugin.json": "c5f9e3d934423161af6ef5fbf52c0c3394e737245a4de21da72da6d75a790f44",
+        "public/crossword.css": "656f369ea6587b000ff56b8ab80010f4f76af10966537c180950074ec5169f61",
+        "public/crossword.js": "8418a2c52a3d351a95e271d3c9f564b7336243ccde75106a9998995575802173",
+        "public/lib/layout.js": "0026afd8b42277838c55e1c031fa07cfea1c640c47aaf385e461cc998c4619c0"
+      }
+    },
     "feedback": {
       "version": "1.2.0",
       "files": {
@@ -164,6 +185,27 @@
         "plugin.json": "e5ac7f3496d9a535fa4899d1de87a514535084d13acecd6a5897744b6174807a"
       }
     },
+    "quiz": {
+      "version": "1.1.0",
+      "files": {
+        "CLAUDE.md": "9d037c11b0de115bf17a6c53387116be037c0d4dcd1b6bf3dafa373539143e16",
+        "admin/css/index.css": "6598225cfb8b58c486eb390ac41c7f359c78f48e0c97bc8b354d3832f618afa8",
+        "admin/templates/quiz.html": "f0b65c406b0b6325a815906ca8da7d884d5d24f2504e05631e46c34a5ca0edb9",
+        "admin/views/quiz.js": "c58ba86ec989df8f29e8acff2266fb3463e301c5516bf9281193de539b7c1f44",
+        "collections/quiz-plays.json": "331d665a90b6dddf069245a2faf8dd454a36d387702343a7e36d1fe6dd5015f8",
+        "collections/quiz-quizzes.json": "ce9bacf6c05fb5c22f9a5c5105f624c7a9c6d78c2bd343072d9cb7587e920b1d",
+        "config.js": "24db3727a804678ef12290ae258c7cf52afbc7a425bb452d87b7b2467ff7c559",
+        "docs/guide.md": "a7f8f449b94ecc726dc82fc7a0ae7c335431fa757f9493859bdf16e633689c3f",
+        "inject/body.html": "07727ead4a04fdeb2759a19e8cc358ba2692b807fb741a6daafaf02463fe8233",
+        "lib/engine.js": "a554c7abfa357288bbd73f47c9bcbf8eab7d8222ff63b1fd119a3ca5f9fb79f4",
+        "lib/quiz.js": "d697bbd1af41575a9ecee49781695f2dfb4a585bf0230cc39ac5d174dc9c2762",
+        "lib/store.js": "a740d879185e20c036ac17ab5cbca74d1f71097f4af3bc121fcddc826d8686c6",
+        "plugin.js": "0ec6f96fc4922c7ef41b36bd757c02926ee99d50e78fe85f7f30b9fbd9605b25",
+        "plugin.json": "788960b6a31c7c1c2d525fb7cae9ab9b7c9310def5d778c275f22302ecaadf78",
+        "public/quiz.css": "e8869fb30e22763357464e9aa7a353306b6631b8a7418ba4e483331e66aada67",
+        "public/quiz.js": "dedc96469e440c979b20d7d95655fbb25062b00b27be569b2a55ec5a8ec0cbb5"
+      }
+    },
     "security": {
       "version": "1.2.1",
       "files": {

package/plugins/quiz/CLAUDE.md

@@ -0,0 +1,43 @@
+# quiz - AI Assistant Guide
+
+## Purpose
+
+Timed quizzes on the public site with name-only players and leaderboards. 1.1.0 (2026-10-21), `tier: free`,
+disabled on arrival. Sibling of `crossword`; both sit in the sidebar's Tools > Games folder (`"group": "Games"`)
+and share `plugins/_lib/games` (server) + `_lib/public/games` (browser) + `_lib/admin/games` (admin kit).
+
+## Files
+
+- `lib/quiz.js` - PURE rules: `cleanQuiz` (the only gate on what the admin saves), `isOpen`, `planPlay` (question
+  order, option order, `draw`, fixed at start), `publicQuestion` (never `correct`), `mark`, `foldAnswer`.
+- `lib/engine.js` - PURE clock: `catchUp`, `serve`, `answer`, `end`, `view`. Each mutates the play and says if it
+  changed; the route saves through `plays.change()` (locked read-modify-write).
+- `lib/store.js` - `quiz-quizzes` collection + `plays = new PlayStore('quiz-plays', {order: 'score'})`.
+- `plugin.js` - routes (header comment lists them), shortcodes, the `top-scores` notification source.
+- `public/quiz.js` - the player (domma-reactive bindings), injected on every page by `inject/body.html`. Exports
+  `mount(el, {test})`, which the admin's Test screen uses.
+- `admin/views/quiz.js` - list, editor, test and plays screens, all domma-reactive through the admin kit
+  (`mountScreen`, `wireRows`, `sortableRows`, `testScreen`, `playsScreen` in `_lib/admin/games/kit.js`). Templates
+  are strings in the JS (a templateUrl goes through `_.render`, which eats data-each `{{ }}`); the questions are an
+  `observableArray` of question models with their answers nested as `{{#each options key=id}}`.
+- Tests: `tests/plugins/games-pure.test.js`, `tests/plugins/games-api.test.js` in the CMS repo.
+
+## Contracts
+
+- **The server keeps time and marks.** A question's clock starts at `serve()` - the GET of `/public/play/:id` -
+  and only then can it be answered (`answer()` refuses an unserved one with `code: 'not-current'`). So the player
+  must GET the next question after each answer, not use the one in the answer response. `GRACE_MS` (3s) covers
+  latency; late answers are marked wrong, never refused.
+- **The play token** (`X-Play-Token`) is returned once by start and compared with `timingSafeEqual`.
+  `PlayStore.adminView` strips it and the state from everything the admin sees.
+- **Leaderboards** rank finished, unhidden plays, best per `nameKey`, score then time (`_lib/games/ranking.js`).
+- **Shortcode prefix trap:** the engine's plugin-shortcode regex is a PREFIX match, so `[quiz` also matches
+  `[quiz-leaderboard`. `quiz-leaderboard` is registered with `{priority: 5}` so it runs first. Keep it that way.
+- **Domma bindings:** a `data-on-submit` handler must return `false` synchronously - an async one returns a
+  Promise and the form submits natively (page reload).
+- Collections' API verbs are all off: nothing here is readable through `/api/v1`.
+- **Test plays** (1.1.0): `GET/POST /quizzes/:id/test` (manage) give the start screen and a play marked `test: true`,
+  for the SAVED quiz whatever its status. It is played through the ordinary `/public/play` routes. `PlayStore` leaves
+  tests out of `forGame` (so boards, places, goes-per-name and the admin list), `todayBadge` skips them,
+  `afterFinish` never notifies for one, and the next test of the game clears them (`clearTests`). `/result` answers
+  `test: true` and `wouldPlace` instead of a place. Tests: `games-api.test.js` "test plays".

package/plugins/quiz/admin/css/index.css

@@ -0,0 +1,13 @@
+/* Quiz admin - the question editor. Shared pieces are in /plugins/_lib/admin/games/games.css. */
+.qza-questions { display: flex; flex-direction: column; gap: .75rem; }
+.qza-question { border: 1px solid var(--gma-line); border-left: 4px solid var(--dm-primary); border-radius: var(--dm-radius-md, 8px);
+    padding: .85rem 1rem; display: flex; flex-direction: column; gap: .6rem; background: var(--dm-background, transparent); }
+.qza-question .form-select { width: auto; }
+.qza-answers { display: flex; flex-direction: column; gap: .4rem; }
+.qza-answer { display: flex; align-items: center; gap: .5rem; padding: .25rem .4rem; border-radius: 6px; }
+.qza-answer.is-right { background: color-mix(in srgb, var(--dm-success) 12%, transparent); }
+.qza-answer .form-input { flex: 1; min-width: 0; }
+.qza-mark { display: inline-flex; align-items: center; cursor: pointer; padding: .2rem; }
+.qza-mark input { width: 1.1rem; height: 1.1rem; accent-color: var(--dm-success); }
+.qza-fixed { flex: 1; font-weight: 500; }
+.qza-more summary { cursor: pointer; color: var(--dm-text-muted); font-size: var(--dm-text-sm); margin-bottom: .5rem; }

package/plugins/quiz/admin/templates/quiz.html

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