domma-cms 0.73.0 → 0.75.0

package/server/routes/api/blocks.js

@@ -1,15 +1,150 @@
 /**
  * Blocks API
  * CRUD for reusable HTML block templates stored in content/blocks/*.html.
- * GET    /api/blocks              - list all blocks
+ * GET    /api/blocks              - list all blocks (each with hasCss, description, example;
+ *                                    ?usage=1 adds where each is used: pages and views)
+ * GET    /api/blocks/_count       - the sidebar badge (`_` is outside the block-name alphabet)
  * GET    /api/blocks/:name        - get block content
  * GET    /api/blocks/:name/export - download block as .dmblock.json bundle
  * POST   /api/blocks/import       - import a .dmblock.json bundle
  * PUT    /api/blocks/:name        - create or update block
  * DELETE /api/blocks/:name        - delete block
  */
+import fs from 'fs/promises';
+import path from 'path';
 import {authenticate, requirePermission} from '../../middleware/auth.js';
 import {deleteBlock, getBlock, listBlocks, saveBlock} from '../../services/blocks.js';
+import {config} from '../../config.js';
+
+/**
+ * A block's own doc comment - the one every block opens with - read for the
+ * list: its first line ("contact-card - Contact entry summary card.") gives a
+ * description, and the line after "Example:" a shortcode to copy. Plain text;
+ * a block without a comment gives neither.
+ *
+ * @param {string} html
+ * @param {string} name
+ * @returns {{description: string, example: string}}
+ */
+export function blockDoc(html, name = '') {
+    const m = /^\s*<!--([\s\S]*?)-->/.exec(String(html || ''));
+    if (!m) return {description: '', example: ''};
+    const lines = m[1].split('\n').map(l => l.trim());
+    // The first paragraph - a description may wrap over several lines.
+    const start = lines.findIndex(Boolean);
+    const para = [];
+    // …ending at a blank line or the next heading ("Example:", "Parameters (all optional):").
+    for (let i = Math.max(0, start); start >= 0 && i < lines.length && lines[i]; i++) {
+        if (i > start && /^[\w ()/-]+:$/.test(lines[i])) break;
+        para.push(lines[i]);
+    }
+    const first = para.join(' ');
+    const lead = new RegExp(`^${name.replace(/[-]/g, '\\-')}\\s*[-–:]\\s*`, 'i');
+    const description = name && lead.test(first) ? first.replace(lead, '') : (/^[\w-]+\s*[-–:]\s*/.test(first) ? first.replace(/^[\w-]+\s*[-–:]\s*/, '') : first);
+    // The example may wrap over several lines: from its `[` to the line ending `]`.
+    let example = '';
+    const at = lines.findIndex(l => /^example:?$/i.test(l));
+    if (at >= 0) {
+        const from = lines.findIndex((l, i) => i > at && l.startsWith('['));
+        if (from > 0) {
+            const parts = [];
+            for (let i = from; i < lines.length && lines[i]; i++) {
+                parts.push(lines[i]);
+                if (lines[i].endsWith(']')) break;
+            }
+            example = parts.join(' ');
+        }
+    }
+    return {description: description.slice(0, 200), example: example.slice(0, 300)};
+}
+
+/** Escape a block name for a RegExp. Names are [a-z0-9-] so only `-` needs care. */
+const reName = (n) => n.replace(/-/g, '\\-');
+
+/**
+ * Where each block is used, by reading - not rendering - the page sources and
+ * view configs: `block="x"` (collection/view/carousel/listgroup displays),
+ * `template="x"` (the [block] shortcode), the `[x …/]` short tag, and a view's
+ * `display.block`. Cheap enough for the list and the badge; a block pulled in
+ * only by a plugin's own code is not seen (so "unused" means "not used by a
+ * page or view").
+ *
+ * @param {string[]} names
+ * @param {{url: string, raw: string}[]} pages
+ * @param {{slug: string, name?: string, display?: {block?: string}}[]} views
+ * @returns {Record<string, {pages: string[], views: string[]}>}
+ */
+export function blockUsage(names, pages = [], views = []) {
+    const out = Object.fromEntries(names.map(n => [n, {pages: [], views: []}]));
+    for (const n of names) {
+        const re = new RegExp(`(?:\\b(?:block|template)\\s*=\\s*["']${reName(n)}["'])|(?:\\[${reName(n)}(?=[\\s/\\]]))`);
+        for (const p of pages) if (re.test(p.raw)) out[n].pages.push(p.url);
+        for (const v of views) if (v?.display?.block === n) out[n].views.push(v.slug || v.name || '');
+    }
+    return out;
+}
+
+/** Every page's source, with its URL - read from disk, never rendered. */
+async function readPageSources() {
+    const root = path.join(config.content.contentDir, 'pages');
+    const out = [];
+    async function walk(dir) {
+        let entries = [];
+        try { entries = await fs.readdir(dir, {withFileTypes: true}); } catch { return; }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) await walk(full);
+            else if (e.name.endsWith('.md')) {
+                const rel = path.relative(root, full).replace(/\.md$/, '').split(path.sep).join('/');
+                const url = rel === 'index' ? '/' : '/' + rel.replace(/\/index$/, '');
+                try { out.push({url, raw: await fs.readFile(full, 'utf8')}); } catch { /* unreadable - skip */ }
+            }
+        }
+    }
+    await walk(root);
+    return out;
+}
+
+async function usageFor(names) {
+    const [pages, views] = await Promise.all([
+        readPageSources(),
+        import('../../services/views.js').then(m => m.listViews()).catch(() => [])
+    ]);
+    return blockUsage(names, pages, views);
+}
+
+/**
+ * The sidebar badge on Blocks: how many there are, with the unused ones and
+ * the latest changes in the popover. A count to glance at, never a warning.
+ * Plain text throughout - the popover sets it with textContent.
+ *
+ * @param {{name: string, updatedAt?: string, hasCss?: boolean, bundled?: boolean, usage?: {pages: string[], views: string[]}}[]} blocks
+ */
+export function blocksBadge(blocks = []) {
+    const n = blocks.length;
+    const used = (b) => (b.usage?.pages?.length || 0) + (b.usage?.views?.length || 0);
+    const unused = blocks.filter(b => b.usage && !used(b)).length;
+    const recent = [...blocks].sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || ''))).slice(0, 6);
+    return {
+        count: n,
+        label: `${n} block${n === 1 ? '' : 's'}${unused ? `, ${unused} not used on any page` : ''}`,
+        tone: 'info',
+        details: {
+            title: 'Blocks',
+            rows: [
+                {label: 'Blocks', value: String(n)},
+                {label: 'With CSS', value: String(blocks.filter(b => b.hasCss).length)},
+                {label: 'Not used on a page or view', value: String(unused)},
+                {label: 'Built in', value: String(blocks.filter(b => b.bundled).length)}
+            ],
+            items: recent.map(b => ({
+                text: b.name,
+                meta: [b.updatedAt ? `changed ${String(b.updatedAt).slice(0, 10)}` : '', b.usage ? `used ${used(b)} time${used(b) === 1 ? '' : 's'}` : ''].filter(Boolean).join(' · ')
+            })),
+            empty: 'No blocks yet.'
+        }
+    };
+}
 
 /** Current export bundle schema version. Bump when the shape changes. */
 const BUNDLE_FORMAT = 1;
@@ -19,18 +154,45 @@ export async function blocksRoutes(fastify) {
     const canUpdate = {preHandler: [authenticate, requirePermission('pages', 'update')]};
     const canDelete = {preHandler: [authenticate, requirePermission('pages', 'delete')]};
 
-    // List all blocks
-    fastify.get('/blocks', canRead, async (request) => {
+    /**
+     * The blocks this user may see, each with what the list shows beyond the
+     * file: whether it has CSS, and its doc comment's description and example.
+     * getBlock was already read per block for the project check, so these come free.
+     */
+    async function visibleBlocks(user) {
         const {canSeeArtefact} = await import('../../services/projects.js');
-        const all = await listBlocks();
-        const filtered = [];
-        for (const b of all) {
+        const out = [];
+        for (const b of await listBlocks()) {
             // listBlocks returns metadata only; getBlock returns full record with meta
             let full = null;
             try { full = await getBlock(b.name); } catch { /* skip */ }
-            if (canSeeArtefact(request.user, full)) filtered.push(b);
+            if (!canSeeArtefact(user, full)) continue;
+            out.push({...b, hasCss: Boolean(full?.css), cssSize: full?.css?.length || 0, ...blockDoc(full?.content, b.name)});
+        }
+        return out;
+    }
+
+    // List all blocks (?usage=1: where each is used)
+    fastify.get('/blocks', canRead, async (request) => {
+        const blocks = await visibleBlocks(request.user);
+        if (request.query?.usage !== '1') return blocks;
+        const usage = await usageFor(blocks.map(b => b.name));
+        return blocks.map(b => ({...b, usage: usage[b.name]}));
+    });
+
+    // The sidebar badge. Registered before /blocks/:name; `_` is not a valid block name.
+    // Usage reads every page's source, and the badge is asked for every minute from
+    // every admin tab: it is kept a minute (the list's ?usage=1 always reads afresh).
+    let usageCache = {at: 0, key: '', value: null};
+    fastify.get('/blocks/_count', canRead, async (request) => {
+        const blocks = await visibleBlocks(request.user);
+        const names = blocks.map(b => b.name);
+        const key = names.join('\n');
+        if (!usageCache.value || usageCache.key !== key || Date.now() - usageCache.at > 60_000) {
+            usageCache = {at: Date.now(), key, value: await usageFor(names)};
         }
-        return filtered;
+        const usage = usageCache.value;
+        return blocksBadge(blocks.map(b => ({...b, usage: usage[b.name]})));
     });
 
     // Get single block

package/server/routes/api/collections.js

@@ -3,6 +3,7 @@
  *
  * Admin endpoints (authenticated + collections role):
  * GET    /collections                    - List all collections
+ * GET    /collections/_count             - The sidebar badge (count + popover details)
  * POST   /collections                    - Create collection
  * GET    /collections/:slug              - Get schema
  * PUT    /collections/:slug              - Update schema
@@ -64,6 +65,45 @@ import {isProjectEnabled, resolveArtefactProject} from '../../services/projects.
 
 const ALL_PRESET_SLUGS = new Set(['roles', 'user-profiles', ...PRESET_COLLECTION_SLUGS]);
 
+/**
+ * The sidebar badge on Collections (GET /collections/_count): how many
+ * collections this user sees and how many entries they hold, with where they
+ * are stored and the biggest ones. Plain text throughout - the popover sets it
+ * with textContent.
+ *
+ * @param {object[]} list - collections with entryCount, as listCollections answers
+ * @returns {{count: number, label: string, tone: string, details: object}}
+ */
+export function collectionsBadge(list = []) {
+    const plural = (n, one, many = `${one}s`) => `${n.toLocaleString('en-GB')} ${n === 1 ? one : many}`;
+    const kind = (c) => (ALL_PRESET_SLUGS.has(c.slug) ? 'builtin' : c.plugin ? 'plugin' : 'own');
+    const counts = {own: 0, builtin: 0, plugin: 0};
+    for (const c of list) counts[kind(c)]++;
+    const entries = list.reduce((s, c) => s + (Number(c.entryCount) || 0), 0);
+    const mongo = list.filter(c => c.storage?.adapter === 'mongodb').length;
+    const biggest = list.filter(c => Number(c.entryCount) > 0)
+        .sort((a, b) => b.entryCount - a.entryCount || String(a.title || a.slug).localeCompare(String(b.title || b.slug)));
+    return {
+        count: list.length,
+        label: `${plural(list.length, 'collection')}, ${plural(entries, 'entry', 'entries')}`,
+        tone: 'info',
+        details: {
+            title: 'Collections',
+            rows: [
+                {label: 'Yours', value: String(counts.own)},
+                {label: 'Built in', value: String(counts.builtin)},
+                {label: 'Plugins', value: String(counts.plugin)},
+                {label: 'On MongoDB', value: String(mongo)}
+            ],
+            items: biggest.slice(0, 6).map(c => ({
+                text: String(c.title || c.slug),
+                meta: `${plural(Number(c.entryCount), 'entry', 'entries')} · ${c.slug}`
+            })),
+            empty: 'No entries in any collection yet.'
+        }
+    };
+}
+
 /**
  * Resolve the role level number for a named role.
  *
@@ -242,11 +282,23 @@ export async function collectionsRoutes(fastify) {
         for (const c of all) {
             // listCollections returns metadata only; getCollection returns full record with meta
             const full = await getCollection(c.slug);
-            if (canSeeArtefact(request.user, full)) filtered.push(c);
+            // builtIn: the ones DELETE refuses (seeding turns `preset` into `bundled`, which
+            // also covers deletable seeded collections - so the list says which is which).
+            if (canSeeArtefact(request.user, full)) filtered.push(ALL_PRESET_SLUGS.has(c.slug) ? {...c, builtIn: true} : c);
         }
         return filtered;
     });
 
+    // The sidebar badge. Static, so it wins over /collections/:slug; `_` is never in a slug.
+    fastify.get('/collections/_count', canRead, async (request) => {
+        const {canSeeArtefact} = await import('../../services/projects.js');
+        const visible = [];
+        for (const c of await listCollections()) {
+            if (canSeeArtefact(request.user, await getCollection(c.slug))) visible.push(c);
+        }
+        return collectionsBadge(visible);
+    });
+
     fastify.get('/collections/pro-status', canRead, async () => {
     try {
       const connections = getConfig('connections');

package/server/routes/api/components.js

@@ -3,6 +3,7 @@
  * CRUD + compilation + export/import for .dmc components.
  *
  * GET    /api/components              - list
+ * GET    /api/components/_count       - the sidebar badge (`_` is outside NAME_RE, so no component shadows it)
  * GET    /api/components/:name        - raw source + parsed props
  * GET    /api/components/:name.js     - compiled JS module (public)
  * POST   /api/components/compile      - transient compile for preview
@@ -12,6 +13,7 @@
  * DELETE /api/components/:name        - delete
  */
 import {authenticate, requirePermission} from '../../middleware/auth.js';
+import {ago, plural} from '../../services/sidebarBadges.js';
 import {
     compileComponent,
     deleteComponent,
@@ -23,6 +25,43 @@ import {
     saveComponent
 } from '../../services/components.js';
 
+/**
+ * The sidebar badge on Components (its countUrl): how many there are, split
+ * by where they come from, with the most recently changed ones in the popover.
+ * A count to glance at, never a warning. Plain text throughout - the popover
+ * sets it with textContent.
+ *
+ * @param {object[]} list - as listComponents() returns them, already scoped to the viewer
+ * @param {number} [now]
+ * @returns {{count: number, label: string, tone: string, details: object}}
+ */
+export function componentsBadge(list = [], now = Date.now()) {
+    const plugin = list.filter(c => c.origin === 'plugin');
+    const builtin = list.filter(c => c.origin !== 'plugin' && c.bundled);
+    const mine = list.length - plugin.length - builtin.length;
+    const recent = list.filter(c => c.updatedAt)
+        .sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)))
+        .slice(0, 6);
+    return {
+        count: list.length,
+        label: `${plural(list.length, 'component')}${mine ? `, ${mine} of yours` : ''}`,
+        tone: 'info',
+        details: {
+            title: 'Components',
+            rows: [
+                {label: 'Yours', value: String(mine)},
+                {label: 'Built in', value: String(builtin.length)},
+                {label: 'From plugins', value: String(plugin.length)}
+            ],
+            items: recent.map(c => {
+                const props = Object.keys(c.props || {}).length;
+                return {text: `<dm-${c.name}>`, meta: `${plural(props, 'prop')} · changed ${ago(c.updatedAt, now)}`};
+            }),
+            empty: 'No components yet.'
+        }
+    };
+}
+
 export async function componentsRoutes(fastify) {
     const canRead   = {preHandler: [authenticate, requirePermission('components', 'read')]};
     const canUpdate = {preHandler: [authenticate, requirePermission('components', 'update')]};
@@ -53,6 +92,13 @@ export async function componentsRoutes(fastify) {
         return all.filter(c => canSeeArtefact(request.user, c));
     });
 
+    // Static, so it wins over /components/:name; `_count` can never be a component name.
+    fastify.get('/components/_count', canRead, async (request) => {
+        const {canSeeArtefact} = await import('../../services/projects.js');
+        const all = await listComponents();
+        return componentsBadge(all.filter(c => canSeeArtefact(request.user, c)));
+    });
+
     fastify.get('/components/:name', canRead, async (request, reply) => {
         let component;
         try { component = await getComponent(request.params.name); }

package/server/routes/api/context-menus.js

@@ -2,6 +2,7 @@
  * Context menus API
  *
  * GET    /api/context-menus                  - list (metadata only)
+ * GET    /api/context-menus/_count           - the sidebar badge (the underscore can never be a slug)
  * GET    /api/context-menus/:slug            - full menu
  * POST   /api/context-menus                  - create
  * PUT    /api/context-menus/:slug            - replace
@@ -18,6 +19,7 @@ import {
 } from '../../middleware/auth.js';
 import {
     ACTION_TYPES,
+    contextMenusBadge,
     createContextMenu,
     deleteContextMenu,
     duplicateContextMenu,
@@ -45,6 +47,12 @@ export async function contextMenusRoutes(fastify, opts = {}) {
         return all.filter((m) => canSeeArtefact(request.user, m));
     });
 
+    // Registered before /context-menus/:slug; `_` is outside the slug alphabet, so no menu can shadow it.
+    fastify.get('/context-menus/_count', canRead, async (request) => {
+        const {canSeeArtefact} = await import('../../services/projects.js');
+        return contextMenusBadge((await listContextMenus()).filter((m) => canSeeArtefact(request.user, m)));
+    });
+
     fastify.get('/context-menus/:slug', canRead, async (request, reply) => {
         const menu = await getContextMenu(request.params.slug);
         if (!menu) return reply.code(404).send({error: 'Context menu not found'});

package/server/routes/api/forms.js

@@ -36,6 +36,7 @@ import {authenticate, requireAdmin, requirePermission} from '../../middleware/au
 import {hooks} from '../../services/hooks.js';
 import {saveMedia} from '../../services/content.js';
 import {v4 as uuidv4} from 'uuid';
+import {ago, clip, plural} from '../../services/sidebarBadges.js';
 
 /**
  * Detect form↔collection mismatches at save time so admins know BEFORE
@@ -228,6 +229,104 @@ function submissionsToCSV(form, entries) {
     return [headers.join(','), ...rows].join('\n');
 }
 
+/**
+ * Where a form's submissions are stored: its collection action's collection
+ * when that is on, else a collection named after the form. The submissions
+ * screen reads from here, so every count must too - the list used to count
+ * `form.slug` and disagreed with it for any form writing elsewhere.
+ *
+ * @param {object} form
+ * @returns {string}
+ */
+export function submissionsCollectionFor(form) {
+    const c = form?.actions?.collection;
+    return c?.enabled && c.slug ? c.slug : form?.slug;
+}
+
+const DAY_MS = 86_400_000;
+
+/**
+ * Submission figures for one form: total, this week (last 7 days), today
+ * (last 24 hours) and the newest one's time. A form whose collection does not
+ * exist yet has none.
+ *
+ * @param {object} form
+ * @param {number} [now]
+ * @returns {Promise<{total: number, week: number, today: number, last: string|null}>}
+ */
+async function submissionStats(form, now = Date.now()) {
+    try {
+        const r = await listEntries(submissionsCollectionFor(form), {limit: 0});
+        const entries = r.entries || [];
+        let week = 0;
+        let today = 0;
+        let last = null;
+        for (const e of entries) {
+            const at = e.meta?.createdAt;
+            const t = at ? Date.parse(at) : NaN;
+            if (!Number.isFinite(t)) continue;
+            if (now - t <= 7 * DAY_MS) week++;
+            if (now - t <= DAY_MS) today++;
+            if (!last || at > last) last = at;
+        }
+        return {total: r.total ?? entries.length, week, today, last};
+    } catch {
+        return {total: 0, week: 0, today: 0, last: null};
+    }
+}
+
+/**
+ * The sidebar badge on Forms (its countUrl, GET /api/forms/_count): the
+ * submissions that came in over the last 7 days, with the forms they came
+ * through. There is no "read" state for a submission, so recent is the
+ * useful number. Plain text throughout - the popover sets it with textContent.
+ *
+ * @param {{title: string, slug: string, stats: {total, week, today, last}}[]} forms
+ * @param {number} [now]
+ */
+/**
+ * Each form's submission stats, kept a minute: the sidebar asks for the Forms
+ * badge every minute from every open admin tab, and stats read every
+ * submission. Per form, not per user - who may see which form is still
+ * decided on each request.
+ */
+const statsCache = new Map();
+async function cachedStats(form, now) {
+    const hit = statsCache.get(form.slug);
+    if (hit && now - hit.at < 60_000) return hit.value;
+    const value = await submissionStats(form, now);
+    statsCache.set(form.slug, {at: now, value});
+    return value;
+}
+
+export function formsBadge(forms = [], now = Date.now()) {
+    const week = forms.reduce((n, f) => n + (f.stats?.week || 0), 0);
+    const today = forms.reduce((n, f) => n + (f.stats?.today || 0), 0);
+    const total = forms.reduce((n, f) => n + (f.stats?.total || 0), 0);
+    const busy = forms.filter(f => f.stats?.week > 0)
+        .sort((a, b) => String(b.stats.last).localeCompare(String(a.stats.last)));
+    return {
+        // The number stays what the sidebar has always shown on Forms (how many); submissions are the label.
+        count: forms.length,
+        label: `${plural(forms.length, 'form')}${week ? `, ${plural(week, 'submission')} this week` : ', no submissions this week'}`,
+        tone: 'info',
+        details: {
+            title: 'Forms',
+            rows: [
+                {label: 'Last 24 hours', value: String(today)},
+                {label: 'Last 7 days', value: String(week)},
+                {label: 'All time', value: String(total)},
+                {label: 'Forms', value: String(forms.length)}
+            ],
+            items: busy.slice(0, 6).map(f => ({
+                text: clip(f.title || f.slug),
+                meta: `${f.stats.week} this week · last ${ago(f.stats.last, now)}`
+            })),
+            empty: 'No submissions in the last 7 days.'
+        }
+    };
+}
+
 export async function formsRoutes(fastify) {
     await ensureFormsDir();
 
@@ -242,26 +341,40 @@ export async function formsRoutes(fastify) {
     fastify.get('/forms', canRead, async (request) => {
         const {canSeeArtefact} = await import('../../services/projects.js');
         const forms = await listForms();
+        const now = Date.now();
         const result = await Promise.all(forms.map(async form => {
-            let submissionCount = 0;
-            try {
-                // listEntries returns { entries, total, page, limit } - total is the
-                // unpaginated count which is what we want for the badge here.
-                const r = await listEntries(form.slug, { limit: 0 });
-                submissionCount = r.total ?? (r.entries || []).length;
-            } catch {
-                // collection may not exist yet
-            }
+            // Counted where the submissions screen reads them (submissionsCollectionFor).
+            const stats = await submissionStats(form, now);
             // listForms returns metadata only; readForm returns full record with meta
             let full = null;
             try { full = await readForm(form.slug); } catch { /* skip */ }
-            return { form: { ...form, submissionCount }, full };
+            return {
+                form: {...form, submissionCount: stats.total, submissionsThisWeek: stats.week, lastSubmissionAt: stats.last},
+                full
+            };
         }));
         return result
             .filter(({ full }) => canSeeArtefact(request.user, full))
             .map(({ form }) => form);
     });
 
+    // -----------------------------------------------------------------------
+    // GET /forms/_count - the sidebar badge (formsBadge). `_` is outside the
+    // slug alphabet (slugify), so no form can shadow it.
+    // -----------------------------------------------------------------------
+    fastify.get('/forms/_count', canRead, async (request) => {
+        const {canSeeArtefact} = await import('../../services/projects.js');
+        const now = Date.now();
+        const forms = await listForms();
+        const seen = await Promise.all(forms.map(async (form) => {
+            let full = null;
+            try { full = await readForm(form.slug); } catch { /* skip */ }
+            if (!canSeeArtefact(request.user, full)) return null;
+            return {title: form.title, slug: form.slug, stats: await cachedStats(form, now)};
+        }));
+        return formsBadge(seen.filter(Boolean), now);
+    });
+
     // -----------------------------------------------------------------------
     // POST /forms - create new form
     // -----------------------------------------------------------------------

package/server/routes/api/media.js

@@ -1,6 +1,7 @@
 /**
  * Media API
  * GET    /api/media       - list media files
+ * GET    /api/media/_count - the sidebar badge (plain text; see mediaBadge)
  * POST   /api/media       - upload a file
  * DELETE /api/media/:name - delete a file
  */
@@ -8,6 +9,7 @@ import path from 'path';
 import {deleteMedia, listMedia, renameMedia, saveMedia} from '../../services/content.js';
 import {getImageInfo, isEditableImage, transformImage} from '../../services/images.js';
 import {authenticate, requirePermission} from '../../middleware/auth.js';
+import {ago, clip, plural} from '../../services/sidebarBadges.js';
 
 const ALLOWED_MIME_TYPES = new Set([
   // Images
@@ -30,6 +32,50 @@ function sanitiseFilename(name) {
     return path.basename(name).replace(/[^a-zA-Z0-9._-]/g, '_');
 }
 
+/** 0 B, 812 B, 14.2 KB, 3.1 MB - the badge's sizes. */
+function bytes(n) {
+    const v0 = Number(n) || 0;
+    if (v0 < 1024) return `${v0} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let v = v0 / 1024;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) { v /= 1024; i++; }
+    return `${v.toFixed(1)} ${units[i]}`;
+}
+
+const IMAGE_RE = /\.(png|jpe?g|gif|webp|svg|avif|ico|bmp|tiff?)$/i;
+
+/**
+ * The badge on Content › Media: how many files, how much space, the newest
+ * few. Informational - nothing on this screen is ever overdue. Every value is
+ * plain text; the sidebar popover sets it with textContent (file names are
+ * whatever was uploaded).
+ *
+ * @param {{name: string, size: number, createdAt: string}[]} files
+ * @param {number} [now]
+ */
+export function mediaBadge(files = [], now = Date.now()) {
+    const total = files.reduce((s, f) => s + (Number(f.size) || 0), 0);
+    const images = files.filter(f => IMAGE_RE.test(f.name)).length;
+    const newest = [...files].sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+    return {
+        count: files.length,
+        label: files.length ? `${plural(files.length, 'file')}, ${bytes(total)}` : 'No media yet',
+        tone: 'info',
+        details: {
+            title: 'Media',
+            rows: [
+                {label: 'Files', value: String(files.length)},
+                {label: 'Images', value: String(images)},
+                {label: 'Other files', value: String(files.length - images)},
+                {label: 'Space used', value: bytes(total)}
+            ],
+            items: newest.slice(0, 5).map(f => ({text: clip(f.name, 48), meta: `${bytes(f.size)} · ${ago(f.createdAt, now)}`})),
+            empty: 'Nothing uploaded yet.'
+        }
+    };
+}
+
 export async function mediaRoutes(fastify) {
     const canRead = {preHandler: [authenticate, requirePermission('media', 'read')]};
     const canCreate = {preHandler: [authenticate, requirePermission('media', 'create')]};
@@ -40,6 +86,9 @@ export async function mediaRoutes(fastify) {
         return listMedia();
     });
 
+    // `_count` is not a file route: the only GET under /media/:name is /media/:name/info.
+    fastify.get('/media/_count', canRead, async () => mediaBadge(await listMedia()));
+
     fastify.post('/media', canCreate, async (request, reply) => {
       const results = [];
       for await (const data of request.files()) {
@@ -84,7 +133,13 @@ export async function mediaRoutes(fastify) {
 
     fastify.delete('/media/:name', canDelete, async (request, reply) => {
         const name = sanitiseFilename(request.params.name);
-        await deleteMedia(name);
+        try {
+            await deleteMedia(name);
+        } catch (err) {
+            // Gone already (another tab, another admin) is a 404, not a server error.
+            if (err.code === 'ENOENT') return reply.status(404).send({error: 'File not found'});
+            throw err;
+        }
         return { success: true };
     });