domma-cms 1.8.30 → 1.8.32

package/plugins/crossword/admin/views/crossword.js

@@ -0,0 +1,317 @@
+/**
+ * Crossword - the Tool. One view, three screens by address:
+ *
+ *   #/plugins/crossword                 every crossword
+ *   #/plugins/crossword/new             a new crossword
+ *   #/plugins/crossword/edit/<id>       its words, clues and settings, with the grid previewed live
+ *   #/plugins/crossword/plays/<id>      who solved it, and its leaderboard
+ *
+ * The preview runs the same layout function the server saves with
+ * (public/lib/layout.js), from the same words and seed, so what you see is
+ * what is saved.
+ */
+
+import {bannerTrail, copyText, errText, esc, field, fmtDuration, fromLocalInput, h, icon, loadKit, playsScreen, refreshBadge, request, toggle, toLocalInput} from '/plugins/_lib/admin/games/kit.js';
+import {MAX_WORDS, cleanAnswer, generate, solutionGrid} from '/plugins/crossword/public/lib/layout.js';
+
+const API = '/plugins/crossword';
+const SIDEBAR = '#/plugins/crossword';
+const ROUTE = /^#\/plugins\/crossword(\/|\?|$)/;
+const STATUS_LABEL = {draft: 'Draft', open: 'Open', closed: 'Closed'};
+const STATUS_TONE = {draft: '', open: 'is-success', closed: 'is-warning'};
+
+let lifetime = null;
+let leaveGuard = null;
+
+function where() {
+    const m = location.hash.split('?')[0].match(/^#\/plugins\/crossword(?:\/([a-z]+))?(?:\/([^/?#]+))?/);
+    return {screen: m?.[1] || 'list', id: m?.[2] ? decodeURIComponent(m[2]) : ''};
+}
+
+const badge = () => refreshBadge(SIDEBAR);
+const shortcodeOf = (slug) => `[crossword id="${slug}" /]`;
+
+export const crosswordView = {
+    templateUrl: '/plugins/crossword/admin/templates/crossword.html',
+
+    async onMount($container) {
+        const kit = await loadKit();
+        lifetime ??= kit.viewLifetime(ROUTE);
+        if (!ROUTE.test(location.hash)) return;
+        lifetime.reset();
+        if (leaveGuard) { window.removeEventListener('beforeunload', leaveGuard); leaveGuard = null; }
+        const container = $container.get(0);
+        const root = container.querySelector('[data-crossword-admin]') || container;
+        const {screen, id} = where();
+
+        if (screen === 'plays' && id) {
+            let title = 'Plays';
+            try { title = (await request('GET', `${API}/puzzles/${encodeURIComponent(id)}`)).title; } catch { /* the screen says so */ }
+            bannerTrail(container, [{text: 'Crossword', href: SIDEBAR}, {text: `${title}: plays`}]);
+            kit.addBannerAction($container, {id: 'crossword-edit', icon: 'edit', title: 'Edit this crossword', onClick: () => { location.hash = `#/plugins/crossword/edit/${encodeURIComponent(id)}`; }});
+            return playsScreen(root, {api: API, gameId: id, title, order: 'time', back: SIDEBAR, base: '/puzzles', badge});
+        }
+        if (screen === 'new' || (screen === 'edit' && id)) return editor(root, container, $container, kit, screen === 'new' ? '' : id);
+        return list(root, container, $container, kit);
+    }
+};
+
+// ---- The list ----------------------------------------------------------------------
+
+async function list(root, container, $container, kit) {
+    bannerTrail(container, [{text: 'Crossword'}]);
+    kit.addBannerAction($container, {id: 'crossword-new', icon: 'plus', title: 'New crossword', onClick: () => { location.hash = '#/plugins/crossword/new'; }});
+    root.innerHTML = '';
+    const slot = h('div', {className: 'gma-note dm-loading-slot', text: 'Loading…'});
+    root.append(slot);
+    let puzzles;
+    try {
+        puzzles = (await kit.whileLoading(slot, request('GET', `${API}/puzzles`), kit.SHAPES.rows)).puzzles || [];
+    } catch (err) {
+        root.innerHTML = '';
+        root.append(h('p', {className: 'gma-error', text: `Crossword could not load: ${errText(err)}`}));
+        return;
+    }
+
+    const draw = () => {
+        root.innerHTML = '';
+        root.append(h('div', {className: 'gma-bar'},
+            h('a', {className: 'btn btn-sm btn-primary', href: '#/plugins/crossword/new'}, icon('plus'), ' New crossword'),
+            h('span', {className: 'gma-spacer'}),
+            h('span', {className: 'gma-note', text: 'Put a crossword on any page with its shortcode.'})));
+        if (!puzzles.length) {
+            root.append(h('div', {className: 'gma-empty'}, icon('grid', 30),
+                h('p', {}, h('strong', {text: 'No crosswords yet.'}), h('br'), 'Type the answers and clues; the grid lays itself out.'),
+                h('a', {className: 'btn btn-primary', href: '#/plugins/crossword/new'}, 'Make a crossword')));
+            I.scan(root);
+            return;
+        }
+        root.append(h('div', {className: 'gma-list'}, puzzles.map(p => h('div', {className: 'gma-row'},
+            h('div', {className: 'gma-row-main'},
+                h('div', {}, h('a', {href: `#/plugins/crossword/edit/${encodeURIComponent(p.id)}`, text: p.title}),
+                    h('span', {className: `gma-chip ${STATUS_TONE[p.status] || ''}`, text: STATUS_LABEL[p.status] || p.status})),
+                h('small', {text: [`${p.words} answers, ${p.size}`, `${p.finished} solved of ${p.plays} play${p.plays === 1 ? '' : 's'}`,
+                    p.finished ? `fastest ${fmtDuration(p.fastest)}` : '', shortcodeOf(p.slug)].filter(Boolean).join(' · ')})),
+            h('div', {className: 'gma-row-actions'},
+                h('a', {className: 'btn btn-sm btn-ghost', href: `#/plugins/crossword/edit/${encodeURIComponent(p.id)}`}, icon('edit'), ' Edit'),
+                h('a', {className: 'btn btn-sm btn-ghost', href: `#/plugins/crossword/plays/${encodeURIComponent(p.id)}`}, icon('award'), ' Plays'),
+                h('button', {type: 'button', className: 'btn btn-sm btn-ghost', title: 'Copy the shortcode', onClick: () => copyText(shortcodeOf(p.slug), 'Shortcode copied')}, icon('copy')),
+                h('button', {type: 'button', className: 'btn btn-sm btn-ghost', title: 'Make a copy', onClick: () => duplicate(p)}, icon('layers')),
+                h('button', {type: 'button', className: 'btn btn-sm btn-ghost gma-danger-text', title: 'Delete', onClick: () => remove(p)}, icon('trash')))))));
+        I.scan(root);
+    };
+
+    async function duplicate(p) {
+        try {
+            const copy = await request('POST', `${API}/puzzles/${encodeURIComponent(p.id)}/copy`);
+            E.toast(`Copied as "${copy.title}" (a draft).`, {type: 'success'});
+            puzzles = (await request('GET', `${API}/puzzles`)).puzzles || [];
+            draw();
+        } catch (err) { E.toast(errText(err), {type: 'error'}); }
+    }
+
+    async function remove(p) {
+        if (!await E.confirm(`Delete the crossword <strong>${esc(p.title)}</strong>? Its ${p.plays} play${p.plays === 1 ? '' : 's'} and leaderboard go with it.`)) return;
+        try {
+            await request('DELETE', `${API}/puzzles/${encodeURIComponent(p.id)}`);
+            puzzles = puzzles.filter(x => x.id !== p.id);
+            draw();
+            badge();
+            E.toast(`${p.title} deleted.`, {type: 'success'});
+        } catch (err) { E.toast(errText(err), {type: 'error'}); }
+    }
+
+    draw();
+}
+
+// ---- The editor --------------------------------------------------------------------
+
+const blankPuzzle = () => ({
+    title: '', slug: '', intro: '', status: 'draft', opensAt: '', closesAt: '', timeLimit: 0, checks: true, checkPenalty: 30, wrongPenalty: 10,
+    leaderboard: true, leaderboardSize: 10, attemptsPerName: 0, seed: 1,
+    words: [{answer: '', clue: ''}, {answer: '', clue: ''}, {answer: '', clue: ''}]
+});
+
+async function editor(root, container, $container, kit, id) {
+    root.innerHTML = '';
+    let puzzle = blankPuzzle();
+    if (id) {
+        const slot = h('div', {className: 'gma-note dm-loading-slot', text: 'Loading…'});
+        root.append(slot);
+        try {
+            const got = await kit.whileLoading(slot, request('GET', `${API}/puzzles/${encodeURIComponent(id)}`), kit.SHAPES.rows);
+            const {layout, ...rest} = got;
+            puzzle = {...blankPuzzle(), ...rest};
+        } catch (err) {
+            root.innerHTML = '';
+            root.append(h('p', {className: 'gma-error', text: `That crossword could not load: ${errText(err)}`}), h('a', {href: SIDEBAR, text: 'Back to Crossword'}));
+            return;
+        }
+    }
+    bannerTrail(container, [{text: 'Crossword', href: SIDEBAR}, {text: id ? puzzle.title : 'New crossword'}]);
+    if (id) kit.addBannerAction($container, {id: 'crossword-plays', icon: 'award', title: 'Plays and leaderboard', onClick: () => { location.hash = `#/plugins/crossword/plays/${encodeURIComponent(id)}`; }});
+
+    const fields = (p) => {
+        const {id: _i, createdAt, updatedAt, unplaced, ...rest} = p;
+        return rest;
+    };
+    const snapshot = () => JSON.stringify(fields(puzzle));
+    let saved = snapshot();
+    const dirty = () => snapshot() !== saved;
+    leaveGuard = (e) => { if (dirty() && ROUTE.test(location.hash)) { e.preventDefault(); e.returnValue = ''; } };
+    window.addEventListener('beforeunload', leaveGuard);
+    lifetime.add(() => { window.removeEventListener('beforeunload', leaveGuard); leaveGuard = null; });
+
+    const dirtyNote = h('span', {className: 'is-dirty', hidden: true, text: 'Unsaved changes'});
+    const errorBox = h('p', {className: 'gma-error', hidden: true, role: 'alert'});
+    const touched = () => { dirtyNote.hidden = !dirty(); };
+
+    const input = (key, attrs = {}) => h('input', {className: 'form-input', value: puzzle[key] ?? '', ...attrs,
+        onInput: (e) => { puzzle[key] = attrs.type === 'number' ? Number(e.target.value) || 0 : e.target.value; touched(); }});
+    const status = h('select', {className: 'form-select', onChange: (e) => { puzzle.status = e.target.value; touched(); }},
+        Object.entries(STATUS_LABEL).map(([v, label]) => h('option', {value: v, text: label})));
+    status.value = puzzle.status;
+
+    const shortcode = h('code');
+    const showShortcode = () => { shortcode.textContent = puzzle.slug ? shortcodeOf(puzzle.slug) : 'Saved crosswords get a shortcode'; };
+    showShortcode();
+
+    const minutes = h('input', {className: 'form-input', type: 'number', min: 0, step: 1, value: puzzle.timeLimit ? Math.round(puzzle.timeLimit / 60) : 0,
+        onInput: (e) => { puzzle.timeLimit = Math.round((Number(e.target.value) || 0) * 60); touched(); }});
+    const intro = h('textarea', {className: 'form-input', rows: 3, onInput: (e) => { puzzle.intro = e.target.value; touched(); }}, puzzle.intro);
+
+    const details = h('section', {className: 'gma-card'},
+        h('h3', {className: 'gma-h', text: 'The crossword'}),
+        h('div', {className: 'gma-grid'},
+            field('Title', input('title', {maxlength: 120, placeholder: 'Friday teaser'})),
+            field('Short name', input('slug', {maxlength: 60, placeholder: 'made from the title'}), 'Used in the shortcode.'),
+            field('Status', status, 'Only an open crossword can be played.')),
+        field('Introduction', intro, 'Shown above the grid.'),
+        h('div', {className: 'gma-grid'},
+            field('Opens', h('input', {className: 'form-input', type: 'datetime-local', value: toLocalInput(puzzle.opensAt), onInput: (e) => { puzzle.opensAt = fromLocalInput(e.target.value); touched(); }}), 'Optional.'),
+            field('Closes', h('input', {className: 'form-input', type: 'datetime-local', value: toLocalInput(puzzle.closesAt), onInput: (e) => { puzzle.closesAt = fromLocalInput(e.target.value); touched(); }}), 'Optional.')),
+        h('div', {className: 'gma-shortcode'}, h('span', {className: 'gma-muted', text: 'Shortcode:'}), shortcode,
+            h('button', {type: 'button', className: 'btn btn-xs btn-ghost', onClick: () => puzzle.slug && copyText(shortcodeOf(puzzle.slug), 'Shortcode copied')}, icon('copy'), ' Copy')));
+
+    const rules = h('section', {className: 'gma-card'},
+        h('h3', {className: 'gma-h', text: 'Rules and leaderboard'}),
+        h('div', {className: 'gma-grid'},
+            field('Time limit (minutes)', minutes, '0 = no limit. Out of time means off the leaderboard.'),
+            field('Seconds added per check', input('checkPenalty', {type: 'number', min: 0, max: 600})),
+            field('Seconds added for a wrong full grid', input('wrongPenalty', {type: 'number', min: 0, max: 600}), 'Stops people guessing their way to the top.'),
+            field('Goes each (per name)', input('attemptsPerName', {type: 'number', min: 0, max: 100}), '0 = as many as they like.'),
+            field('Leaderboard size', input('leaderboardSize', {type: 'number', min: 3, max: 100}))),
+        h('div', {className: 'gma-grid'},
+            toggle('Let players check their letters', puzzle.checks, (v) => { puzzle.checks = v; touched(); }, 'Shows which squares are wrong, at a cost in time.'),
+            toggle('Show a leaderboard', puzzle.leaderboard, (v) => { puzzle.leaderboard = v; touched(); }, 'Fastest time wins, penalties included.')));
+
+    // Words and the live grid.
+    const wordList = h('div', {className: 'cwa-words'});
+    const wordCount = h('span', {className: 'gma-muted'});
+    const preview = h('div', {className: 'cwa-preview'});
+    const previewNote = h('p', {className: 'gma-note'});
+    const unplacedNote = h('p', {className: 'cwa-unplaced', hidden: true, role: 'status'});
+
+    function drawPreview() {
+        const ready = puzzle.words.filter(w => cleanAnswer(w.answer).letters.length >= 2 && w.clue.trim());
+        const layout = generate(ready, {seed: puzzle.seed});
+        preview.innerHTML = '';
+        if (!layout.entries.length) {
+            preview.append(h('p', {className: 'gma-muted', text: 'Type at least two answers with clues and the grid appears here.'}));
+            previewNote.textContent = '';
+        } else {
+            const grid = solutionGrid(layout);
+            const numbers = new Map(layout.entries.map(e => [`${e.row},${e.col}`, e.number]));
+            const table = h('div', {className: 'cwa-grid', style: `grid-template-columns: repeat(${layout.width}, 1.7rem)`});
+            grid.forEach((row, r) => row.forEach((ch, c) => table.append(h('div', {className: ch ? 'cwa-cell' : 'cwa-cell is-block'},
+                numbers.has(`${r},${c}`) ? h('span', {className: 'cwa-num', text: numbers.get(`${r},${c}`)}) : null, ch || ''))));
+            preview.append(table);
+            previewNote.textContent = `${layout.width} × ${layout.height}, ${layout.entries.length} answers. Layout ${puzzle.seed}.`;
+        }
+        unplacedNote.hidden = !layout.unplaced.length;
+        unplacedNote.textContent = layout.unplaced.length
+            ? `Did not fit: ${layout.unplaced.map(u => u.answer).join(', ')}. Try another layout, or change those answers so they share letters with the others.`
+            : '';
+        const shown = puzzle.words.filter(w => w.answer || w.clue).length;
+        wordCount.textContent = `${shown} of ${MAX_WORDS}`;
+    }
+    const redraw = _.debounce ? _.debounce(drawPreview, 250) : drawPreview;
+
+    function wordRow(w, i) {
+        const enumeration = h('span', {className: 'cwa-enum'});
+        const showEnum = () => { const c = cleanAnswer(w.answer); enumeration.textContent = c.letters ? `(${c.enumeration})` : ''; };
+        showEnum();
+        return h('div', {className: 'cwa-word'},
+            h('span', {className: 'cwa-n', text: `${i + 1}`}),
+            h('input', {className: 'form-input cwa-answer', value: w.answer, maxlength: 40, placeholder: 'Answer', 'aria-label': `Answer ${i + 1}`,
+                onInput: (e) => { w.answer = e.target.value; showEnum(); touched(); redraw(); }}),
+            enumeration,
+            h('input', {className: 'form-input cwa-clue', value: w.clue, maxlength: 300, placeholder: 'Clue', 'aria-label': `Clue ${i + 1}`,
+                onInput: (e) => { w.clue = e.target.value; touched(); redraw(); },
+                onKeydown: (e) => { if (e.key === 'Enter' && i === puzzle.words.length - 1) { e.preventDefault(); addWord(); } }}),
+            h('button', {type: 'button', className: 'btn btn-xs btn-ghost', title: 'Remove', onClick: () => { puzzle.words.splice(i, 1); drawWords(); touched(); }}, icon('x')));
+    }
+
+    function drawWords() {
+        wordList.innerHTML = '';
+        puzzle.words.forEach((w, i) => wordList.append(wordRow(w, i)));
+        I.scan(wordList);
+        drawPreview();
+    }
+
+    function addWord() {
+        if (puzzle.words.length >= MAX_WORDS) return;
+        puzzle.words.push({answer: '', clue: ''});
+        drawWords();
+        touched();
+        wordList.lastElementChild?.querySelector('.cwa-answer')?.focus();
+    }
+
+    const words = h('section', {className: 'gma-card'},
+        h('div', {className: 'gma-bar'}, h('h3', {className: 'gma-h', text: 'Answers and clues'}), wordCount),
+        h('p', {className: 'gma-note', text: 'Spaces and hyphens in an answer show in the clue as word lengths, e.g. New York (3,4). Answers that share letters cross more.'}),
+        wordList,
+        h('div', {className: 'gma-bar'}, h('button', {type: 'button', className: 'btn btn-sm btn-outline', onClick: addWord}, icon('plus'), ' Add an answer')));
+
+    const grid = h('section', {className: 'gma-card cwa-side'},
+        h('div', {className: 'gma-bar'}, h('h3', {className: 'gma-h', text: 'The grid'}), h('span', {className: 'gma-spacer'}),
+            h('button', {type: 'button', className: 'btn btn-sm btn-outline', title: 'Try a different arrangement of the same words',
+                onClick: () => { puzzle.seed = (puzzle.seed % 2147483646) + 1; touched(); drawPreview(); }}, icon('refresh-cw'), ' Another layout')),
+        preview, previewNote, unplacedNote,
+        h('p', {className: 'gma-note', text: 'Players see the shape and the numbers, never the letters.'}));
+
+    const saveBtn = h('button', {type: 'button', className: 'btn btn-primary', onClick: () => save()}, icon('check'), ' Save');
+    const bar = h('div', {className: 'gma-save'}, saveBtn,
+        h('a', {className: 'btn btn-ghost', href: SIDEBAR, text: 'Back to the list'}), dirtyNote, h('span', {className: 'gma-spacer'}), errorBox);
+
+    async function save() {
+        errorBox.hidden = true;
+        saveBtn.disabled = true;
+        try {
+            const body = fields(puzzle);
+            const out = id ? await request('PUT', `${API}/puzzles/${encodeURIComponent(id)}`, body) : await request('POST', `${API}/puzzles`, body);
+            const {layout, unplaced, ...rest} = out;
+            puzzle = {...blankPuzzle(), ...rest};
+            if (!puzzle.words.length) puzzle.words.push({answer: '', clue: ''});
+            saved = snapshot();
+            touched();
+            showShortcode();
+            E.toast(unplaced?.length ? `${out.title} saved. ${unplaced.length} answer${unplaced.length === 1 ? '' : 's'} did not fit the grid.` : `${out.title} saved.`,
+                {type: unplaced?.length ? 'warning' : 'success'});
+            if (!id) { location.hash = `#/plugins/crossword/edit/${encodeURIComponent(out.id)}`; return; }
+            bannerTrail(container, [{text: 'Crossword', href: SIDEBAR}, {text: out.title}]);
+            drawWords();
+        } catch (err) {
+            errorBox.textContent = errText(err);
+            errorBox.hidden = false;
+        } finally {
+            saveBtn.disabled = false;
+        }
+    }
+
+    root.innerHTML = '';
+    root.append(details, h('div', {className: 'gma-two'}, words, grid), rules, bar);
+    drawWords();
+    I.scan(root);
+    if (!id) details.querySelector('input')?.focus();
+}

package/plugins/crossword/collections/crossword-plays.json

@@ -0,0 +1,20 @@
+{
+  "slug": "crossword-plays",
+  "title": "Crossword - Plays",
+  "description": "Every go at a crossword: the name and the time. Look at them in Crossword, not here.",
+  "plugin": "crossword",
+  "fields": [
+    {"name": "gameId", "label": "Crossword", "type": "text"},
+    {"name": "name", "label": "Name", "type": "text"},
+    {"name": "status", "label": "Status", "type": "text"},
+    {"name": "score", "label": "Score", "type": "number"},
+    {"name": "timeMs", "label": "Time (ms)", "type": "number"},
+    {"name": "hidden", "label": "Hidden from the leaderboard", "type": "boolean"}
+  ],
+  "api": {
+    "create": {"enabled": false, "access": "admin"},
+    "read":   {"enabled": false, "access": "admin"},
+    "update": {"enabled": false, "access": "admin"},
+    "delete": {"enabled": false, "access": "admin"}
+  }
+}

package/plugins/crossword/collections/crossword-puzzles.json

@@ -0,0 +1,17 @@
+{
+  "slug": "crossword-puzzles",
+  "title": "Crossword - Puzzles",
+  "description": "The crosswords, answers included. Edit them in Crossword, not here.",
+  "plugin": "crossword",
+  "fields": [
+    {"name": "title", "label": "Title", "type": "text"},
+    {"name": "slug", "label": "Short name", "type": "text"},
+    {"name": "status", "label": "Status", "type": "text"}
+  ],
+  "api": {
+    "create": {"enabled": false, "access": "admin"},
+    "read":   {"enabled": false, "access": "admin"},
+    "update": {"enabled": false, "access": "admin"},
+    "delete": {"enabled": false, "access": "admin"}
+  }
+}

package/plugins/crossword/config.js

@@ -0,0 +1,6 @@
+/**
+ * Crossword - default configuration. Every crossword carries its own settings
+ * (time limit, checking, penalties, the leaderboard...), edited with the
+ * crossword; nothing here needs changing.
+ */
+export default {};

package/plugins/crossword/inject/body.html

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

package/plugins/crossword/lib/crossword.js

@@ -0,0 +1,170 @@
+/**
+ * Crossword - the rules. PURE: no I/O, so the routes and the tests share them.
+ *
+ *   cleanPuzzle(input)            -> {puzzle, errors, unplaced}   what the admin saved, laid out by the server
+ *   isOpen(puzzle, now)           -> {open, reason}
+ *   publicPuzzle(puzzle)          -> the grid's shape and the clues - never a letter of the answers
+ *   readCells(raw, puzzle)        -> the player's letters as rows, or null when malformed
+ *   compare(cells, solution)      -> {wrong: [[r, c]], empty: n}
+ *   catchUp / finish              -> the play, by the server's clock
+ *
+ * @module crossword/lib/crossword
+ */
+
+import {GRACE_MS, leftOf, overdue} from '../../_lib/games/timing.js';
+import {MAX_WORDS, generate, shapeOf, solutionGrid} from '../public/lib/layout.js';
+
+export const STATUSES = ['draft', 'open', 'closed'];
+export const LIMITS = {clue: 300, answer: 40, timeLimit: 6 * 3600, penalty: 600};
+
+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() : '';
+};
+
+export function slugify(s) {
+    return String(s || '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60);
+}
+
+/**
+ * The puzzle as the admin saved it. The grid is laid out HERE from the words
+ * and the seed (the same function the builder previews with), so a layout is
+ * never taken from the browser.
+ *
+ * @returns {{puzzle: object, errors: Object<string, string>, unplaced: object[]}}
+ */
+export function cleanPuzzle(input = {}) {
+    const errors = {};
+    const words = (Array.isArray(input.words) ? input.words : []).slice(0, MAX_WORDS)
+        .map(w => ({answer: str(w?.answer, LIMITS.answer), clue: str(w?.clue, LIMITS.clue)}))
+        .filter(w => w.answer || w.clue);
+    const puzzle = {
+        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),
+        checks: input.checks !== false,
+        checkPenalty: int(input.checkPenalty ?? 30, 0, LIMITS.penalty, 30),
+        wrongPenalty: int(input.wrongPenalty ?? 10, 0, LIMITS.penalty, 10),
+        leaderboard: input.leaderboard !== false,
+        leaderboardSize: int(input.leaderboardSize ?? 10, 3, 100, 10),
+        attemptsPerName: int(input.attemptsPerName, 0, 100),
+        seed: int(input.seed ?? 1, 1, 2 ** 31 - 1, 1),
+        words,
+        layout: {width: 0, height: 0, entries: []}
+    };
+    if (!puzzle.title) errors.title = 'Give the crossword a title.';
+    if (!puzzle.slug) errors.slug = 'Give the crossword a short name for its address (letters and numbers).';
+    if (puzzle.opensAt && puzzle.closesAt && puzzle.closesAt <= puzzle.opensAt) errors.closesAt = 'It has to close after it opens.';
+    words.forEach((w, i) => {
+        if (!w.answer) errors[`w${i + 1}`] ??= `Word ${i + 1} has a clue but no answer.`;
+        else if (!w.clue) errors[`w${i + 1}`] ??= `"${w.answer}" needs a clue.`;
+    });
+    const laid = generate(words.filter(w => w.answer && w.clue), {seed: puzzle.seed});
+    puzzle.layout = {width: laid.width, height: laid.height, entries: laid.entries};
+    if (puzzle.status === 'open' && laid.entries.length < 2) errors.words = 'Add at least two answers that cross before opening the crossword.';
+    return {puzzle, errors, unplaced: laid.unplaced};
+}
+
+export function isOpen(puzzle, now = Date.now()) {
+    if (!puzzle || puzzle.status === 'draft') return {open: false, reason: 'This crossword is not open yet.', state: 'draft'};
+    if (puzzle.status === 'closed') return {open: false, reason: 'This crossword has closed.', state: 'closed'};
+    if (puzzle.opensAt && Date.parse(puzzle.opensAt) > now) return {open: false, reason: 'This crossword opens soon.', state: 'scheduled', opensAt: puzzle.opensAt};
+    if (puzzle.closesAt && Date.parse(puzzle.closesAt) <= now) return {open: false, reason: 'This crossword has closed.', state: 'ended'};
+    if ((puzzle.layout?.entries?.length || 0) < 1) return {open: false, reason: 'This crossword is not ready yet.', state: 'empty'};
+    return {open: true, reason: '', state: 'open'};
+}
+
+/** What anyone may see: the shape, the numbers and the clues - no letters. */
+export function publicPuzzle(puzzle) {
+    const {width, height, entries} = puzzle.layout;
+    const grid = solutionGrid(puzzle.layout);
+    const clue = (e) => ({number: e.number, dir: e.dir, clue: e.clue, enumeration: e.enumeration, row: e.row, col: e.col, length: e.letters.length});
+    return {
+        width, height, shape: shapeOf(grid),
+        across: entries.filter(e => e.dir === 'across').map(clue),
+        down: entries.filter(e => e.dir === 'down').map(clue)
+    };
+}
+
+/**
+ * The player's grid: `height` strings of `width` characters, a letter or a
+ * space. Anything else (a black square they typed into, a wrong size) is null.
+ */
+export function readCells(raw, puzzle) {
+    const {width, height} = puzzle.layout;
+    if (!Array.isArray(raw) || raw.length !== height) return null;
+    const rows = [];
+    for (const r of raw) {
+        const row = String(r ?? '').toUpperCase();
+        if (row.length !== width || !/^[A-Z ]*$/.test(row)) return null;
+        rows.push(row);
+    }
+    return rows;
+}
+
+/** Which squares are wrong (a letter that is not the answer's) and how many are still empty. */
+export function compare(cells, solution) {
+    const wrong = [];
+    let empty = 0;
+    solution.forEach((row, r) => row.forEach((ch, c) => {
+        if (!ch) return;
+        const given = cells[r][c];
+        if (given === ' ') empty++;
+        else if (given !== ch) wrong.push([r, c]);
+    }));
+    return {wrong, empty};
+}
+
+const limitMs = (puzzle) => (puzzle.timeLimit || 0) * 1000;
+
+/** Out of time while nobody asked: the play ends, off the board. */
+export function catchUp(puzzle, play, now = Date.now()) {
+    if (play.status !== 'playing' || !overdue(play.startedAt, limitMs(puzzle), now)) return false;
+    play.status = 'timeout';
+    play.finishedAt = new Date(now).toISOString();
+    play.timeMs = limitMs(puzzle);
+    return true;
+}
+
+/** Solved: the time is the server's, plus every penalty. */
+export function finish(play, now = Date.now()) {
+    play.status = 'finished';
+    play.finishedAt = new Date(now).toISOString();
+    play.score = 1;
+    play.timeMs = Math.max(0, now - Date.parse(play.startedAt)) + (play.state.penaltyMs || 0);
+    return play;
+}
+
+/** What the player may know of their play right now. */
+export function view(puzzle, play, now = Date.now()) {
+    const end = play.status === 'playing' ? now : Date.parse(play.finishedAt);
+    return {
+        status: play.status,
+        elapsedMs: Math.max(0, end - Date.parse(play.startedAt)),
+        penaltyMs: play.state.penaltyMs || 0,
+        checks: play.state.checks || 0,
+        totalLeftMs: play.status === 'playing' ? leftOf(play.startedAt, limitMs(puzzle), now) : null,
+        grace: GRACE_MS
+    };
+}
+
+/** The puzzle as a list row in the admin. */
+export function summary(puzzle, plays = []) {
+    const finished = plays.filter(p => p.status === 'finished');
+    return {
+        id: puzzle.id, title: puzzle.title, slug: puzzle.slug, status: puzzle.status,
+        words: puzzle.layout?.entries?.length || 0, size: `${puzzle.layout?.width || 0}×${puzzle.layout?.height || 0}`,
+        plays: plays.length, finished: finished.length,
+        fastest: finished.length ? Math.min(...finished.map(p => p.timeMs || 0)) : 0, updatedAt: puzzle.updatedAt || ''
+    };
+}

package/plugins/crossword/lib/store.js

@@ -0,0 +1,56 @@
+/**
+ * Crossword - where puzzles and plays are kept: the collections `crossword-puzzles` and
+ * `crossword-plays` (made at every boot when missing; API access all off - a puzzle
+ * holds its answers, a play the player's name).
+ *
+ * @module crossword/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 PUZZLES = 'crossword-puzzles';
+export const PLAYS = 'crossword-plays';
+
+export const plays = new PlayStore(PLAYS, {order: 'time'});
+
+export async function ensureCollections(log = console) {
+    for (const slug of [PUZZLES, 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?.(`[crossword] 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 allPuzzles() {
+    cache ??= listEntries(PUZZLES, {limit: 100000}).then(r => (r.entries || []).map(flat)).catch(() => []);
+    return cache;
+}
+const forget = () => { cache = null; };
+
+export const getPuzzle = async (id) => flat(await getEntry(PUZZLES, String(id)).catch(() => null));
+export const puzzleBySlug = async (slug) => (await allPuzzles()).find(q => q.slug === String(slug)) || null;
+
+/** A short name no other crossword has. */
+export async function uniqueSlug(slug, selfId = '') {
+    const taken = new Set((await allPuzzles()).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 savePuzzle(id, data) {
+    const saved = id ? await updateEntry(PUZZLES, id, data) : await createEntry(PUZZLES, data);
+    forget();
+    return flat(saved);
+}
+
+export async function removePuzzle(id) {
+    await deleteEntry(PUZZLES, String(id));
+    forget();
+    return plays.reset(String(id));
+}