domma-cms 1.8.33 → 1.8.35

package/plugins/theme-roller/docs/guide.md

@@ -0,0 +1,104 @@
+---
+title: Guide
+order: 1
+---
+
+Theme Roller lets you make your own themes. Start from any built-in theme, change its colours, fonts, spacing and borders with a live preview, and save it. Open it from **Theme Roller** in the admin sidebar ([Theme Roller](#/plugins/theme-roller)).
+
+## What it does
+
+- A custom theme is a built-in theme (its base) plus the settings you changed. Everything you did not change still comes from the base.
+- Saved themes are listed under **Custom themes** wherever a theme is chosen in **Content > Theme**: the site theme, the admin theme, the day and night themes, and element overrides (one region of a page).
+- You can also use a theme on the site or in the admin straight from Theme Roller.
+- The **Custom CSS** tab edits the site's own CSS, added to every public page after the theme.
+
+Custom themes need Domma CMS 0.73 or later. On an older version a warning says so; themes still save but cannot be used.
+
+## Getting started
+
+1. Open **Theme Roller**. The roller opens on the theme your site shows now.
+2. In the roller, pick a base theme.
+3. Change the colours, fonts, spacing or borders you want. The whole admin changes as you go, so you can see the result.
+4. Press **Save** and give the theme a name (for example "Brand").
+5. Open the **Saved themes** tab, right-click your theme and choose **Use on the site**.
+
+## Screens
+
+The banner has **New theme** and **Save** buttons. **Save** saves the theme on the Roller tab, or the CSS when you are on the Custom CSS tab.
+
+### Roller
+
+The theme editor. The bar above it shows the name of the theme you are editing (or **New theme**), an **Unsaved** tag when you have changes, and where the theme is in use (Site, Admin, Day, Night or Region).
+
+- Pick the base theme and change any setting in the roller. The preview covers the whole admin while you are on this screen. When you leave, the admin goes back to its own theme.
+- **New** - start a new theme.
+- **Save** - save the theme. A new theme asks for a name first. Saving a theme that is in use updates the site straight away.
+- **Save as...** - save your settings as a new theme, leaving the original as it was. Shown when you are editing a saved theme.
+- The menu button next to it has the same actions as a theme in **Saved themes**.
+
+If you leave with unsaved changes you are asked first. Unsaved work (in the roller or in Custom CSS) is offered back the next time you open Theme Roller.
+
+### Saved themes
+
+Every theme you have saved, with where each is used.
+
+- Click a theme (or press Enter on it) to edit it in the roller.
+- Right-click a theme (or use its menu button, or Shift+F10) for:
+  - **Edit in the roller**
+  - **Use on the site** / **Stop using on the site**
+  - **Use in the admin** / **Stop using in the admin**
+  - **Duplicate...** - a copy under a new name.
+  - **Rename...**
+  - **Export CSS** - downloads the theme as a `.css` file. It holds only your changes, as a block for `dm-custom-<id>` to use together with the base theme's class.
+  - **Delete...** - if the theme is in use, each place it was used goes back to its base theme.
+
+Good to know:
+
+- **Use on the site** when day/night switching is on asks first, then switches day/night switching off. The site then shows this one theme.
+- **Stop using** puts that place back on the theme's base.
+- **Use...** uses the saved version. Save first to include changes still in the roller.
+- The admin shows the new admin theme once you leave the Theme Roller screen.
+
+### Custom CSS
+
+Hand-written CSS added to every public page, after the theme, so it has the last word. This is the same CSS as **System > Site Settings > Custom CSS**.
+
+1. Wait for the CSS to load; the box stays locked until it has.
+2. Edit it.
+3. Press **Save CSS** or Ctrl+S.
+
+## Using a custom theme elsewhere
+
+Open **Content > Theme**. Your saved themes are listed under **Custom themes** in each theme picker:
+
+- **Site theme** and **Admin theme**.
+- **Day theme** and **Night theme**, under **Switch between a day and a night theme**.
+- **Element overrides**, to theme one region of a page.
+
+## Settings
+
+Theme Roller has no settings of its own.
+
+## Permissions and roles
+
+Theme Roller uses the built-in **Theme** permission (group Configuration) in **System > Roles**; it adds none of its own.
+
+| Action | Label | Allows |
+| --- | --- | --- |
+| `theme.read` | View | Open Theme Roller and see the saved themes |
+| `theme.update` | Edit | Save, duplicate, rename and delete themes; use them on the site or in the admin |
+
+The **Custom CSS** tab needs **Settings > Edit** (`settings.update`). Without it the tab cannot load or save.
+
+## Tips
+
+- Only what you change is stored. If the base theme is improved in a later version of Domma CMS, your theme picks that up.
+- Duplicate a theme before trying a big change, so you can go back.
+- Changing a theme's base theme while it is in use updates the site straight away.
+- The **Theme Roller** sidebar badge shows how many custom themes you have and how many are in use. Its popover shows the site theme (or the day and night themes) and the admin theme.
+
+## Limitations
+
+- The public theme switcher (**Content > Theme > Theme switcher**) offers built-in themes only. Visitors cannot switch to a custom theme; they can only pick between the built-in ones.
+- For safety, some values are refused: no `url()`, `@import`, comments, braces, semicolons, `<`, `>` or backslashes. A setting with such a value is dropped when the theme is saved.
+- Custom themes need Domma CMS 0.73 or later.

package/plugins/theme-roller/plugin.js

@@ -0,0 +1,263 @@
+/**
+ * Theme Roller Plugin - Server
+ *
+ * Stores custom themes and offers them to the CMS. A theme is a built-in Domma
+ * theme plus the `--dm-*` tokens changed on top of it; the CMS applies it as the
+ * base's class plus `dm-custom-<id>` (core themeSettings.js), so a saved theme
+ * can be chosen anywhere a theme is - the site, the admin, day/night, a region
+ * override - from here or from Content > Theme.
+ *
+ * Needs the CMS's `hooks.registerThemes` (domma-cms 0.73). On an older CMS the
+ * themes still save and load, and the screen says why they cannot be used.
+ *
+ * Endpoints (prefix /api/plugins/theme-roller; the core `theme` permission):
+ *   GET    /status                  - supported?, the built-in themes, what is in use
+ *   GET    /themes                  - saved themes, each with where it is in use
+ *   GET    /themes/:id
+ *   POST   /themes                  - {label, baseTheme, changes}
+ *   PUT    /themes/:id              - {label?, baseTheme?, changes?}
+ *   POST   /themes/:id/duplicate    - {label?}
+ *   DELETE /themes/:id              - anything using it goes back to its base
+ *   POST   /themes/:id/use          - {where: 'site' | 'admin'}
+ *   POST   /themes/:id/unuse        - {where: 'site' | 'admin'} - back to its base
+ *   GET    /count                   - the sidebar badge + popover (countUrl)
+ */
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {listThemeIds, loadThemeConfig, saveThemeConfig} from '../../server/services/themeSettings.js';
+import * as cache from '../../server/services/cache/index.js';
+import {badgeFor, cleanChanges, cleanLabel, ID_RE, uniqueId, usageOf, withoutTheme} from './admin/lib/themes.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_DIR = path.join(__dirname, 'data', 'themes');
+const DEFAULT_BASE = 'charcoal-dark';
+
+/**
+ * A stored file, including the pre-1.1 shape (`name`, no label), as a theme.
+ * The id is the FILE's name: write() and remove() address `<id>.json`, so an
+ * id taken from inside the file could point them at a different file.
+ */
+function normalise(raw, fileId) {
+    const id = String(fileId || '').toLowerCase();
+    if (!ID_RE.test(id)) return null;
+    return {
+        id,
+        label: cleanLabel(raw.label ?? raw.name, id),
+        baseTheme: typeof raw.baseTheme === 'string' && raw.baseTheme ? raw.baseTheme : DEFAULT_BASE,
+        changes: cleanChanges(raw.changes).changes,
+        createdAt: raw.createdAt || raw.updatedAt || new Date().toISOString(),
+        updatedAt: raw.updatedAt || raw.createdAt || new Date().toISOString()
+    };
+}
+
+export default async function themeRollerPlugin(fastify, opts) {
+    const dir = opts.themesDir || DEFAULT_DIR;
+    const {authenticate, requireAdmin, requirePermission} = opts.auth;
+    const can = (action) => ({
+        preHandler: [authenticate, requirePermission ? requirePermission('theme', action) : requireAdmin]
+    });
+
+    // ---- Store: the files are the truth; `themes` mirrors them in memory so
+    // the CMS's provider - called on every page render - never touches disk.
+    const themes = new Map();
+
+    function loadAll() {
+        themes.clear();
+        let entries = [];
+        try { entries = fsSync.readdirSync(dir); } catch { return; }
+        for (const f of entries) {
+            if (!f.endsWith('.json')) continue;
+            try {
+                const t = normalise(JSON.parse(fsSync.readFileSync(path.join(dir, f), 'utf8')), f.slice(0, -5));
+                if (t) themes.set(t.id, t);
+                else fastify.log.warn(`[theme-roller] ${f} skipped - its name is not a usable theme id`);
+            } catch { /* a corrupt file is skipped, not fatal */ }
+        }
+    }
+
+    async function write(theme) {
+        // The directory does not ship (data/ is a site's own), so it is made on
+        // first save - its absence is what made every save fail before 1.1.
+        await fs.mkdir(dir, {recursive: true});
+        const file = path.join(dir, `${theme.id}.json`);
+        // Unique per write: two saves of one theme must not share a temp file.
+        const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+        try {
+            await fs.writeFile(tmp, JSON.stringify(theme, null, 4) + '\n', 'utf8');
+            await fs.rename(tmp, file);
+        } catch (err) {
+            await fs.rm(tmp, {force: true});
+            throw err;
+        }
+        themes.set(theme.id, theme);
+    }
+
+    async function remove(id) {
+        await fs.rm(path.join(dir, `${id}.json`), {force: true});
+        themes.delete(id);
+    }
+
+    loadAll();
+
+    // ---- Offer the themes to the CMS.
+    const supported = typeof opts.hooks?.registerThemes === 'function';
+    if (supported) {
+        opts.hooks.registerThemes(() => [...themes.values()].map(t => ({
+            id: t.id, label: t.label, baseTheme: t.baseTheme, tokens: t.changes
+        })));
+    } else {
+        fastify.log.warn('[theme-roller] this CMS has no hooks.registerThemes (needs domma-cms 0.73) - themes save, but cannot be used');
+    }
+
+    const builtins = () => listThemeIds();
+    // No readable stylesheet means no list to check against - the core treats
+    // that as allow-all, and so does this.
+    const validBase = (b) => typeof b === 'string' && /^[a-z0-9-]+$/.test(b) && (!builtins().length || builtins().includes(b));
+
+    /**
+     * Claim a new id before the first await: two creates of "Brand" at once
+     * must not both get `brand` and have the second overwrite the first.
+     */
+    async function create(theme) {
+        themes.set(theme.id, theme);
+        try {
+            await write(theme);
+        } catch (err) {
+            themes.delete(theme.id);
+            throw err;
+        }
+    }
+    const sorted = () => [...themes.values()].sort((a, b) => a.label.localeCompare(b.label));
+
+    /** A theme a page or the admin already shows changed: drop the cached pages. */
+    async function touched(id) {
+        const cfg = await loadThemeConfig();
+        if (usageOf(id, cfg).length) {
+            try { await cache.invalidateTags(['site']); } catch { /* no cache configured */ }
+        }
+    }
+
+    function fail(reply, code, error) {
+        return reply.code(code).send({error});
+    }
+
+    // -----------------------------------------------------------------------
+
+    fastify.get('/status', can('read'), async () => {
+        const cfg = await loadThemeConfig();
+        return {
+            supported,
+            builtins: builtins(),
+            inUse: {theme: cfg.theme, adminTheme: cfg.adminTheme, autoTheme: cfg.autoTheme?.enabled ? cfg.autoTheme : null}
+        };
+    });
+
+    // The sidebar badge: how many themes, and on hover what the site and the
+    // admin wear and where each saved theme is used.
+    fastify.get('/count', can('read'), async () => {
+        const cfg = await loadThemeConfig();
+        return badgeFor(sorted().map(t => ({...t, usage: usageOf(t.id, cfg)})), cfg);
+    });
+
+    fastify.get('/themes', can('read'), async () => {
+        const cfg = await loadThemeConfig();
+        return sorted().map(t => ({...t, usage: usageOf(t.id, cfg)}));
+    });
+
+    fastify.get('/themes/:id', can('read'), async (req, reply) => {
+        const t = themes.get(req.params.id);
+        return t ? {...t, usage: usageOf(t.id, await loadThemeConfig())} : fail(reply, 404, 'Theme not found');
+    });
+
+    fastify.post('/themes', can('update'), async (req, reply) => {
+        const {label, baseTheme, changes} = req.body || {};
+        const name = cleanLabel(label, '');
+        if (!name) return fail(reply, 400, 'A theme needs a name');
+        if (!validBase(baseTheme)) return fail(reply, 400, `Unknown base theme "${baseTheme}"`);
+        const id = uniqueId(name, {builtins: builtins(), taken: [...themes.keys()]});
+        if (!id) return fail(reply, 400, 'The name needs at least one letter or number');
+        const now = new Date().toISOString();
+        const {changes: clean, dropped} = cleanChanges(changes);
+        const theme = {id, label: name, baseTheme, changes: clean, createdAt: now, updatedAt: now};
+        await create(theme);
+        if (dropped.length) return reply.code(201).send({...theme, usage: [], dropped});
+        return reply.code(201).send({...theme, usage: []});
+    });
+
+    fastify.put('/themes/:id', can('update'), async (req, reply) => {
+        const existing = themes.get(req.params.id);
+        if (!existing) return fail(reply, 404, 'Theme not found');
+        const {label, baseTheme, changes} = req.body || {};
+        if (baseTheme !== undefined && !validBase(baseTheme)) return fail(reply, 400, `Unknown base theme "${baseTheme}"`);
+        const updated = {
+            ...existing,
+            ...(label !== undefined && {label: cleanLabel(label, existing.label)}),
+            ...(baseTheme !== undefined && {baseTheme}),
+            ...(changes !== undefined && {changes: cleanChanges(changes).changes}),
+            updatedAt: new Date().toISOString()
+        };
+        await write(updated);
+        // In use somewhere with a new base: the CMS's remembered base (customBases)
+        // must follow, so re-save the config it is used in.
+        const cfg = await loadThemeConfig();
+        if (baseTheme !== undefined && baseTheme !== existing.baseTheme && usageOf(updated.id, cfg).length) {
+            await saveThemeConfig({});
+        }
+        await touched(updated.id);
+        return {...updated, usage: usageOf(updated.id, cfg)};
+    });
+
+    fastify.post('/themes/:id/duplicate', can('update'), async (req, reply) => {
+        const source = themes.get(req.params.id);
+        if (!source) return fail(reply, 404, 'Theme not found');
+        const name = cleanLabel(req.body?.label, `${source.label} copy`);
+        const id = uniqueId(name, {builtins: builtins(), taken: [...themes.keys()]});
+        if (!id) return fail(reply, 400, 'The name needs at least one letter or number');
+        const now = new Date().toISOString();
+        const copy = {...source, id, label: name, createdAt: now, updatedAt: now};
+        await create(copy);
+        return reply.code(201).send({...copy, usage: []});
+    });
+
+    fastify.delete('/themes/:id', can('update'), async (req, reply) => {
+        const theme = themes.get(req.params.id);
+        if (!theme) return fail(reply, 404, 'Theme not found');
+        // Nothing may be left pointing at a theme that no longer exists: every
+        // use of it goes back to its base, which is what it looked like anyway.
+        const patch = withoutTheme(await loadThemeConfig(), theme.id, theme.baseTheme);
+        if (patch) await saveThemeConfig(patch);
+        await remove(theme.id);
+        return {success: true, replaced: patch ? Object.keys(patch) : []};
+    });
+
+    fastify.post('/themes/:id/use', can('update'), async (req, reply) => {
+        if (!supported) return fail(reply, 409, 'This CMS cannot use custom themes yet - it needs domma-cms 0.73 or later');
+        const theme = themes.get(req.params.id);
+        if (!theme) return fail(reply, 404, 'Theme not found');
+        const where = req.body?.where;
+        if (where === 'admin') {
+            await saveThemeConfig({adminTheme: theme.id});
+        } else if (where === 'site') {
+            // With day/night switching on, the site theme is not what shows -
+            // using this one means switching that off, which the screen asks first.
+            const cfg = await loadThemeConfig();
+            await saveThemeConfig({theme: theme.id, ...(cfg.autoTheme?.enabled && {autoTheme: {...cfg.autoTheme, enabled: false}})});
+        } else {
+            return fail(reply, 400, 'where must be "site" or "admin"');
+        }
+        return {success: true, usage: usageOf(theme.id, await loadThemeConfig())};
+    });
+
+    fastify.post('/themes/:id/unuse', can('update'), async (req, reply) => {
+        const theme = themes.get(req.params.id);
+        if (!theme) return fail(reply, 404, 'Theme not found');
+        const where = req.body?.where;
+        const cfg = await loadThemeConfig();
+        if (where === 'admin' && cfg.adminTheme === theme.id) await saveThemeConfig({adminTheme: theme.baseTheme});
+        else if (where === 'site' && cfg.theme === theme.id) await saveThemeConfig({theme: theme.baseTheme});
+        else if (where !== 'admin' && where !== 'site') return fail(reply, 400, 'where must be "site" or "admin"');
+        return {success: true, usage: usageOf(theme.id, await loadThemeConfig())};
+    });
+}

package/plugins/theme-roller/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "theme-roller",
+  "displayName": "Theme Roller",
+  "version": "1.3.0",
+  "tier": "free",
+  "description": "Make your own themes: start from any built-in theme, change its colours, fonts, spacing and borders with a live preview, and save it. Saved themes join the built-in ones everywhere a theme is chosen - the site, the admin, day and night, a region of a page. Needs Domma CMS 0.73 or later to use them.",
+  "author": "Darryl Waterhouse",
+  "date": "2026-10-21",
+  "icon": "palette",
+  "contentPaths": [
+    "data/themes"
+  ],
+  "admin": {
+    "sidebar": [
+      {
+        "id": "theme-roller",
+        "text": "Theme Roller",
+        "icon": "palette",
+        "url": "#/plugins/theme-roller",
+        "section": "#/plugins/theme-roller",
+        "permission": "theme",
+        "countUrl": "/api/plugins/theme-roller/count"
+      }
+    ],
+    "routes": [
+      {
+        "path": "/plugins/theme-roller",
+        "view": "plugin-theme-roller",
+        "title": "Theme Roller - Domma CMS"
+      }
+    ],
+    "views": {
+      "plugin-theme-roller": {
+        "entry": "theme-roller/admin/views/theme-roller-view.js",
+        "exportName": "themeRollerView"
+      }
+    },
+    "css": [
+      "admin/css/theme-roller.css"
+    ]
+  }
+}

package/plugins/theme-roller/tests/api.test.js

@@ -0,0 +1,161 @@
+/**
+ * The Theme Roller API against the real CMS theme service - the CMS checkout's
+ * config/theme.json and site.json are snapshotted and restored byte for byte,
+ * because `make test` runs inside that checkout.
+ */
+import {test, before, after} from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import Fastify from 'fastify';
+import themeRollerPlugin from '../plugin.js';
+import {listCustomThemes, loadThemeConfig, registerThemeProvider, unregisterThemeProvider}
+    from '../../../server/services/themeSettings.js';
+
+const CONFIG = path.resolve('config');
+const SNAP = ['theme.json', 'site.json'];
+const saved = {};
+let app, dir;
+
+before(async () => {
+    for (const f of SNAP) saved[f] = await fs.readFile(path.join(CONFIG, f), 'utf8').catch(() => null);
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'theme-roller-'));
+    app = Fastify();
+    const pass = async () => {};
+    await app.register(themeRollerPlugin, {
+        themesDir: path.join(dir, 'themes'),       // does not exist yet - saving must make it
+        auth: {authenticate: pass, requireAdmin: pass, requirePermission: () => pass},
+        hooks: {registerThemes: (fn) => registerThemeProvider('theme-roller', fn)}
+    });
+});
+
+after(async () => {
+    await app?.close();
+    unregisterThemeProvider('theme-roller');
+    for (const f of SNAP) {
+        if (saved[f] === null) await fs.rm(path.join(CONFIG, f), {force: true});
+        else await fs.writeFile(path.join(CONFIG, f), saved[f]);
+    }
+    await fs.rm(dir, {recursive: true, force: true});
+});
+
+const call = async (method, url, body) => {
+    const res = await app.inject({method, url, payload: body});
+    return {status: res.statusCode, body: res.json()};
+};
+
+test('a first save works even though the themes folder does not exist yet (the 1.0 bug)', async () => {
+    const r = await call('POST', '/themes', {label: 'Brand Blue', baseTheme: 'ocean-dark',
+        changes: {'--dm-primary': '#1144ff', '--dm-x': 'a;b'}});
+    assert.equal(r.status, 201);
+    assert.equal(r.body.id, 'brand-blue');
+    assert.deepEqual(r.body.changes, {'--dm-primary': '#1144ff'});
+    const onDisk = JSON.parse(await fs.readFile(path.join(dir, 'themes', 'brand-blue.json'), 'utf8'));
+    assert.equal(onDisk.label, 'Brand Blue');
+});
+
+test('saved themes are offered to the CMS', () => {
+    const offered = listCustomThemes().find(t => t.id === 'brand-blue');
+    assert.equal(offered.baseTheme, 'ocean-dark');
+    assert.deepEqual(offered.tokens, {'--dm-primary': '#1144ff'});
+});
+
+test('bad input is refused with a reason', async () => {
+    assert.equal((await call('POST', '/themes', {label: '', baseTheme: 'ocean-dark'})).status, 400);
+    assert.match((await call('POST', '/themes', {label: 'X', baseTheme: 'nope'})).body.error, /Unknown base theme/);
+    // A built-in theme's name gets a suffix rather than shadowing it.
+    const r = await call('POST', '/themes', {label: 'ocean dark', baseTheme: 'ocean-dark'});
+    assert.equal(r.body.id, 'ocean-dark-2');
+    await call('DELETE', '/themes/ocean-dark-2');
+});
+
+test('use on the site and in the admin goes through the CMS theme config', async () => {
+    const site = await call('POST', '/themes/brand-blue/use', {where: 'site'});
+    assert.equal(site.status, 200);
+    const admin = await call('POST', '/themes/brand-blue/use', {where: 'admin'});
+    assert.deepEqual(admin.body.usage.sort(), ['admin', 'site']);
+    const cfg = await loadThemeConfig();
+    assert.equal(cfg.theme, 'brand-blue');
+    assert.equal(cfg.adminTheme, 'brand-blue');
+    assert.equal(cfg.customBases['brand-blue'], 'ocean-dark', 'the CMS remembers the base');
+    const list = await call('GET', '/themes');
+    assert.deepEqual(list.body.find(t => t.id === 'brand-blue').usage.sort(), ['admin', 'site']);
+});
+
+test('changing the base of a theme in use moves the remembered base too', async () => {
+    const r = await call('PUT', '/themes/brand-blue', {baseTheme: 'forest-dark'});
+    assert.equal(r.body.baseTheme, 'forest-dark');
+    assert.equal((await loadThemeConfig()).customBases['brand-blue'], 'forest-dark');
+});
+
+test('duplicate and rename', async () => {
+    const copy = await call('POST', '/themes/brand-blue/duplicate', {label: 'Brand Blue copy'});
+    assert.equal(copy.body.id, 'brand-blue-copy');
+    assert.deepEqual(copy.body.usage, [], 'a copy is not in use');
+    const renamed = await call('PUT', '/themes/brand-blue-copy', {label: 'Second brand'});
+    assert.equal(renamed.body.label, 'Second brand');
+    assert.equal(renamed.body.id, 'brand-blue-copy', 'renaming keeps the id');
+});
+
+test('unuse puts a place back on the base', async () => {
+    await call('POST', '/themes/brand-blue/unuse', {where: 'admin'});
+    assert.equal((await loadThemeConfig()).adminTheme, 'forest-dark');
+});
+
+test('deleting a theme in use leaves nothing pointing at it', async () => {
+    const r = await call('DELETE', '/themes/brand-blue');
+    assert.deepEqual(r.body.replaced, ['theme']);
+    const cfg = await loadThemeConfig();
+    assert.equal(cfg.theme, 'forest-dark');
+    assert.ok(!listCustomThemes().some(t => t.id === 'brand-blue'));
+    await assert.rejects(fs.access(path.join(dir, 'themes', 'brand-blue.json')));
+});
+
+test('a pre-1.1 file (name, no label) still loads', async () => {
+    await fs.writeFile(path.join(dir, 'themes', 'old-one.json'),
+        JSON.stringify({name: 'old-one', baseTheme: 'charcoal-dark', changes: {'--dm-primary': '#abcdef'}}));
+    const app2 = Fastify();
+    const pass = async () => {};
+    await app2.register(themeRollerPlugin, {themesDir: path.join(dir, 'themes'),
+        auth: {authenticate: pass, requireAdmin: pass}, hooks: {}});
+    const list = (await app2.inject({method: 'GET', url: '/themes'})).json();
+    assert.ok(list.some(t => t.id === 'old-one' && t.label === 'old-one'));
+    const status = (await app2.inject({method: 'GET', url: '/status'})).json();
+    assert.equal(status.supported, false, 'no registerThemes: the screen says why they cannot be used');
+    const use = await app2.inject({method: 'POST', url: '/themes/old-one/use', payload: {where: 'site'}});
+    assert.equal(use.statusCode, 409);
+    await app2.close();
+});
+
+test('a crafted id reaches no file', async () => {
+    for (const id of ['..%2Fx', '../x', 'x.json']) {
+        const r = await app.inject({method: 'DELETE', url: `/themes/${id}`});
+        assert.equal(r.statusCode, 404);
+    }
+});
+
+test('two creates of the same name at once get two themes', async () => {
+    const [a, b] = await Promise.all([
+        call('POST', '/themes', {label: 'Twin', baseTheme: 'ocean-dark', changes: {}}),
+        call('POST', '/themes', {label: 'Twin', baseTheme: 'ocean-dark', changes: {}})
+    ]);
+    assert.deepEqual([a.body.id, b.body.id].sort(), ['twin', 'twin-2']);
+    await call('DELETE', '/themes/twin');
+    await call('DELETE', '/themes/twin-2');
+});
+
+test('tokens the server drops are named in the reply', async () => {
+    const r = await call('POST', '/themes', {label: 'Dropper', baseTheme: 'ocean-dark', changes: {'--dm-primary': 'red /*', '--dm-info': '#0a0'}});
+    assert.deepEqual(r.body.changes, {'--dm-info': '#0a0'});
+    assert.deepEqual(r.body.dropped, ['--dm-primary']);
+    await call('DELETE', '/themes/dropper');
+});
+
+test('GET /count answers the sidebar badge contract', async () => {
+    const r = await call('GET', '/count');
+    assert.equal(r.status, 200);
+    assert.equal(typeof r.body.count, 'number');
+    assert.equal(r.body.details.title, 'Theme Roller');
+    assert.ok(Array.isArray(r.body.details.rows) && Array.isArray(r.body.details.items));
+});

package/plugins/theme-roller/tests/prompt-values.test.js

@@ -0,0 +1,22 @@
+/** No prompt here is given its starting value through E.prompt's `inputValue` (a " in it cut the value short) - promptWith in admin/lib/prompt.js. */
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const ADMIN = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'admin');
+
+test('admin prompts set their starting value with promptWith, not inputValue', async () => {
+    const offenders = [];
+    for (const dir of ['views', 'lib']) {
+        for (const name of await fs.readdir(path.join(ADMIN, dir))) {
+            if (!name.endsWith('.js')) continue;
+            const src = await fs.readFile(path.join(ADMIN, dir, name), 'utf8');
+            src.split('\n').forEach((line, i) => {
+                if (/\binputValue\s*:/.test(line) && !/^\s*(\*|\/\/)/.test(line)) offenders.push(`${dir}/${name}:${i + 1}`);
+            });
+        }
+    }
+    assert.deepEqual(offenders, []);
+});