domma-cms 0.74.0 → 0.76.0

package/plugins/_lib/mail/readRoutes.js

@@ -38,6 +38,7 @@ import {readPriority} from './priority.js';
 import {listAttachments, renderBody} from './render.js';
 import {readUnsubscribe} from './unsubscribe.js';
 import {MailKeyError} from './secretbox.js';
+import {unreadBadge} from './unreadBadge.js';
 
 /**
  * Flatten an envelope address list into something the browser can render.
@@ -52,7 +53,7 @@ function addresses(list) {
     }));
 }
 
-export function registerReadRoutes(fastify, {auth, hooks, config, pool, pluginName, cachedList = null, diagnostics = null}) {
+export function registerReadRoutes(fastify, {auth, hooks, config, pool, pluginName, cachedList = null, diagnostics = null, unreadBadge: withUnreadBadge = false}) {
     const {authenticate} = auth;
 
     // A deleted user's stored mailbox passwords must not outlive their
@@ -165,6 +166,47 @@ export function registerReadRoutes(fastify, {auth, hooks, config, pool, pluginNa
     // Accounts
     // -------------------------------------------------------------------------
 
+    /**
+     * GET /unread - the sidebar badge (the plugin.json countUrl). Opt-in:
+     * Email Pro counts from its store and registers its own. INBOX only, by
+     * STATUS (no select, so nothing can be marked read), and kept a minute
+     * per user - the sidebar asks every minute from every open admin tab.
+     */
+    if (withUnreadBadge) {
+        const badgeCache = new Map();
+        // A mailbox that failed (a changed password, a server down) is not asked
+        // again every minute: that is a failed IMAP login per minute per open tab,
+        // enough to trip fail2ban or a provider lockout. It backs off 5 min, doubling
+        // to an hour; saving the account (a new updatedAt) retries straight away.
+        const failures = new Map();
+        const failKey = (uid, account) => `${uid}:${account.id}:${account.updatedAt || account.createdAt || ''}`;
+        fastify.get('/unread', {preHandler: [authenticate]}, async (request, reply) => {
+            const uid = userId(request);
+            if (!uid) return reply.code(401).send({error: 'Authentication required.'});
+            const hit = badgeCache.get(uid);
+            if (hit && Date.now() - hit.at < 60_000) return hit.value;
+            const boxes = [];
+            for (const account of await accounts.listAccounts(uid)) {
+                const key = failKey(uid, account);
+                const failed = failures.get(key);
+                if (failed && Date.now() < failed.until) { boxes.push({label: account.label, unseen: null}); continue; }
+                try {
+                    const status = await pool.withClient(`${uid}:${account.id}`, accounts.toConnection(account),
+                        client => client.status('INBOX', {unseen: true}));
+                    failures.delete(key);
+                    boxes.push({label: account.label, unseen: status?.unseen ?? 0});
+                } catch {
+                    const wait = Math.min((failed?.wait || 150_000) * 2, 3_600_000);
+                    failures.set(key, {wait, until: Date.now() + wait});
+                    boxes.push({label: account.label, unseen: null});
+                }
+            }
+            const value = unreadBadge(boxes);
+            badgeCache.set(uid, {at: Date.now(), value});
+            return value;
+        });
+    }
+
     /** GET /accounts - every mailbox this user owns, without passwords. */
     fastify.get('/accounts', {preHandler: [authenticate]}, async (request, reply) => {
         const uid = userId(request);

package/plugins/_lib/mail/unreadBadge.js

@@ -0,0 +1,42 @@
+/**
+ * The free reader's sidebar badge - unread mail in each mailbox's INBOX.
+ *
+ * Pure: the route asks IMAP (STATUS, which reads without selecting and so can
+ * never mark anything read) and hands the figures here. Email Pro has its own
+ * badge over the synchronised store; this is the edition without one, so it
+ * counts INBOX only - asking a server about every folder once a minute is
+ * how a mailbox gets rate-limited.
+ *
+ * Plain text throughout: the sidebar popover sets it with textContent.
+ *
+ * @module _lib/mail/unreadBadge
+ */
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/**
+ * @param   {{label?: string, unseen: number|null, error?: string}[]} boxes - one per mailbox
+ * @returns {{count: number, label: string, tone: string, details: object}}
+ */
+export function unreadBadge(boxes = []) {
+    const known = boxes.filter(b => Number.isFinite(b.unseen));
+    const count = known.reduce((n, b) => n + b.unseen, 0);
+    const failed = boxes.length - known.length;
+    return {
+        count,
+        label: boxes.length
+            ? `${plural(count, 'unread message')} in the inbox${boxes.length > 1 ? 'es' : ''}${failed ? ` (${plural(failed, 'mailbox', 'mailboxes')} could not be checked)` : ''}`
+            : 'No mailbox set up',
+        tone: 'info',
+        details: {
+            title: 'Mail',
+            rows: boxes.map(b => ({
+                label: String(b.label || 'Mailbox'),
+                value: Number.isFinite(b.unseen) ? plural(b.unseen, 'unread', 'unread') : 'not reachable',
+                ...(Number.isFinite(b.unseen) ? {} : {tone: 'danger'})
+            })),
+            items: [],
+            empty: boxes.length ? 'Nothing unread in the inbox.' : 'Add a mailbox to see unread mail here.'
+        }
+    };
+}

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@d9bfe49",
+  "source": "dcms-marketplace@5f64a68",
   "plugins": {
     "blog": {
       "version": "1.6.3",
@@ -67,13 +67,13 @@
       }
     },
     "mail-reader": {
-      "version": "1.0.0",
+      "version": "1.1.0",
       "files": {
-        "CLAUDE.md": "a8dd2cb285e1d24b2f072aa11a644e1c8c1be89013da6f6cc46d9820fe24ccd5",
+        "CLAUDE.md": "7f317e69b560457f2d4c401b466754850afe75f6983bc41414c71d8c276c3583",
         "admin/views/mail.js": "c5c6483f9618c75cac8f4be32d3aea99511db76d4b9d38b8ef43bdc1d35db3c5",
         "config.js": "6e65803ad822a9acda40c203631b8eb32a87cf9d9e5f1c7cb59d01aa406075c6",
-        "plugin.js": "79b17346ed0192b092040460cc8d762d5207ee6e4af7bfc2d1cf654a51e2fa81",
-        "plugin.json": "5f5b98757514aa70d7c7a2be5a1fbfdde8ef21a2ccc7586b3b5aea9b44fbe5e6"
+        "plugin.js": "ebe4c41bdd8836fb3128af3a0e789d47f89b00e9e37dc9378bb308aaae8d41b2",
+        "plugin.json": "ed1f02d9405f6ae1257313ea4155ea49e307fb2210650fd247b92e6988aa78d1"
       }
     }
   }

package/plugins/mail-reader/CLAUDE.md

@@ -24,6 +24,7 @@ All under `/api/plugins/mail-reader`, all requiring authentication.
 
 | Method | Path | Purpose |
 |---|---|---|
+| GET | `/unread` | The sidebar badge: unread in each mailbox's INBOX, by STATUS (never selects, so nothing is marked read), cached a minute per user. `registerReadRoutes({unreadBadge: true})` - Email Pro counts from its store instead. |
 | GET | `/accounts` | Every mailbox this user owns. Never returns passwords, only `hasPassword`. |
 | POST | `/accounts` | Add a mailbox. |
 | PUT | `/accounts/:id` | Update one. A blank password means "keep the stored one". |

package/plugins/mail-reader/plugin.js

@@ -30,7 +30,9 @@ export default async function mailReaderPlugin(fastify, options) {
         hooks: options.hooks,
         config,
         pool,
-        pluginName: 'mail-reader'
+        pluginName: 'mail-reader',
+        // The sidebar badge (plugin.json countUrl): unread in each INBOX.
+        unreadBadge: true
     });
 }
 

package/plugins/mail-reader/plugin.json

@@ -1,11 +1,11 @@
 {
   "name": "mail-reader",
   "displayName": "Mail Reader",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "tier": "free",
   "description": "Read-only IMAP mailbox reader. Connects to a standard IMAP server and reads mail without ever writing to it.",
   "author": "Darryl Waterhouse",
-  "date": "2026-09-19",
+  "date": "2026-09-25",
   "icon": "mail",
   "admin": {
     "sidebar": [
@@ -14,7 +14,8 @@
         "text": "Mail Reader",
         "icon": "mail",
         "url": "#/plugins/mail-reader",
-        "section": "#/plugins/mail-reader"
+        "section": "#/plugins/mail-reader",
+        "countUrl": "/api/plugins/mail-reader/unread"
       }
     ],
     "routes": [
@@ -26,7 +27,7 @@
     ],
     "views": {
       "plugin-mail-reader": {
-        "entry": "mail-reader/admin/views/mail.js?v=1",
+        "entry": "mail-reader/admin/views/mail.js?v=2",
         "exportName": "mailView"
       }
     }

package/server/routes/api/actions.js

@@ -3,6 +3,7 @@
  *
  * Admin endpoints (authenticated + actions permission):
  * GET    /actions                        - List all action configs
+ * GET    /actions/_count                 - Sidebar badge (never 503: file mode answers count 0, available: false)
  * POST   /actions                        - Create action config
  * GET    /actions/:slug                  - Get action config
  * PUT    /actions/:slug                  - Update action config
@@ -24,12 +25,63 @@ import {
     updateAction
 } from '../../services/actions.js';
 import {getEntry} from '../../services/collections.js';
-import {authenticate, requirePermission} from '../../middleware/auth.js';
+import {
+    authenticate as defaultAuthenticate,
+    requirePermission as defaultRequirePermission
+} from '../../middleware/auth.js';
 import {getRoleLevel} from '../../services/roles.js';
 import {getEffectiveLevel} from '../../services/userRoles.js';
 import {checkEntryAccess} from '../../services/rowAccess.js';
 
-export async function actionsRoutes(fastify) {
+/**
+ * The sidebar badge on Actions (its countUrl): how many actions this user can
+ * see, which collections they act on, which are state-machine transitions.
+ * Plain text throughout - the popover sets it with textContent. `null` (no
+ * MongoDB) answers count 0, so the sidebar shows no badge and logs nothing;
+ * `available` lets the list screen find that out without a 503 of its own.
+ *
+ * @param {object[]|null} actions
+ * @returns {{count: number, label: string, tone: string, details: object}}
+ */
+export function actionsBadge(actions) {
+    if (!Array.isArray(actions)) {
+        return {
+            count: 0, label: 'Actions need MongoDB', tone: 'info', available: false,
+            details: {title: 'Actions', rows: [], items: [],
+                empty: 'Actions are a Pro feature: they need a MongoDB connection.'}
+        };
+    }
+    const n = actions.length;
+    const collections = new Set(actions.map(a => a.collection).filter(Boolean));
+    const transitions = actions.filter(a => a.transition?.field).length;
+    const sorted = [...actions].sort((a, b) => String(a.title || a.slug).localeCompare(String(b.title || b.slug)));
+    return {
+        count: n,
+        label: `${n} action${n === 1 ? '' : 's'}`,
+        tone: 'info',
+        available: true,
+        details: {
+            title: 'Actions',
+            rows: [
+                {label: 'Collections', value: String(collections.size)},
+                {label: 'Transitions', value: String(transitions)}
+            ],
+            items: sorted.slice(0, 8).map(a => ({
+                text: String(a.title || a.slug),
+                meta: [a.collection, `${(a.steps || []).length} step${(a.steps || []).length === 1 ? '' : 's'}`].filter(Boolean).join(' · ')
+            })),
+            empty: 'No actions yet.'
+        }
+    };
+}
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {{authenticate?: Function, requirePermission?: Function}} [opts] - auth as DI, so tests can stub it
+ */
+export async function actionsRoutes(fastify, opts = {}) {
+    const authenticate      = opts.authenticate      || defaultAuthenticate;
+    const requirePermission = opts.requirePermission || defaultRequirePermission;
     const canRead = {preHandler: [authenticate, requirePermission('actions', 'read')]};
     const canCreate = {preHandler: [authenticate, requirePermission('actions', 'create')]};
     const canUpdate = {preHandler: [authenticate, requirePermission('actions', 'update')]};
@@ -60,6 +112,16 @@ export async function actionsRoutes(fastify) {
         }
     });
 
+    // `_count`: slugify() turns '_' into '-', so no action slug can shadow it.
+    fastify.get('/actions/_count', canRead, async (request) => {
+        try {
+            const {canSeeArtefact} = await import('../../services/projects.js');
+            return actionsBadge((await listActions()).filter(a => canSeeArtefact(request.user, a)));
+        } catch {
+            return actionsBadge(null);
+        }
+    });
+
     // Static sub-route declared before parameterised :slug for radix-tree priority
     fastify.get('/actions/collection/:collectionSlug', canRead, async (request, reply) => {
         try {

package/server/routes/api/api-endpoints.js

@@ -2,6 +2,7 @@
  * API Endpoints API (admin management of custom endpoint definitions)
  *
  * GET    /api/api-endpoints      - list definitions visible to the caller
+ * GET    /api/api-endpoints/_count - the sidebar badge (ids are uuids - `_count` is never one)
  * GET    /api/api-endpoints/:id  - single definition (the builder editor)
  * POST   /api/api-endpoints      - create (400 validation, 409 duplicate path shape)
  * PUT    /api/api-endpoints/:id  - update (project binding immutable)
@@ -42,6 +43,43 @@ async function canUseCollection(user, slug) {
     return canSeeArtefact(user, schema);
 }
 
+/**
+ * The sidebar badge on API Builder (its countUrl): how many endpoints the
+ * caller can see, with the public ones called out - they answer anyone, so
+ * they are the ones worth a glance. Plain text throughout: the sidebar
+ * popover sets it with textContent.
+ *
+ * @param {object[]} endpoints - sanitised definitions
+ * @returns {{count: number, label: string, tone: string, details: object}}
+ */
+export function endpointsBadge(endpoints = []) {
+    const list = [...endpoints].sort((a, b) => String(a.project).localeCompare(String(b.project))
+        || String(a.path).localeCompare(String(b.path)));
+    const n = list.length;
+    const off = list.filter(e => e.enabled === false).length;
+    const pub = list.filter(e => e.enabled !== false && e.auth === 'public').length;
+    const url = (e) => `/api/x/${e.project}${e.path}`;
+    return {
+        count: n,
+        label: `${n} endpoint${n === 1 ? '' : 's'}${pub ? `, ${pub} public` : ''}${off ? `, ${off} disabled` : ''}`,
+        tone: 'info',
+        details: {
+            title: 'API Builder',
+            rows: [
+                {label: 'Enabled', value: String(n - off)},
+                {label: 'Public', value: String(pub)},
+                {label: 'Disabled', value: String(off)}
+            ],
+            items: list.slice(0, 8).map(e => ({
+                text: `GET ${url(e)}`,
+                meta: [e.name, e.auth === 'public' ? 'public' : e.auth === 'token' ? 'API token' : `role ${e.auth}`,
+                    e.enabled === false ? 'disabled' : ''].filter(Boolean).join(' · ')
+            })),
+            empty: 'No endpoints yet.'
+        }
+    };
+}
+
 /**
  * Register the api-endpoints routes.
  *
@@ -64,6 +102,9 @@ export async function apiEndpointsRoutes(fastify, opts = {}) {
         return listEndpointsSanitised(request.user);
     });
 
+    // Before /:id in intent (Fastify matches the static segment first anyway).
+    fastify.get('/api-endpoints/_count', canRead, async (request) => endpointsBadge(await listEndpointsSanitised(request.user)));
+
     fastify.get('/api-endpoints/:id', canRead, async (request, reply) => {
         const def = await getEndpointSanitised(request.params.id);
         if (!def) return reply.status(404).send({error: 'Endpoint not found'});

package/server/routes/api/api-tokens.js

@@ -2,6 +2,7 @@
  * API Tokens API
  *
  * GET    /api/api-tokens      - list tokens visible to the caller (sanitised; never the hash)
+ * GET    /api/api-tokens/_count - the sidebar badge: tokens that need attention (expired / expiring)
  * POST   /api/api-tokens      - create; response carries the plaintext ONCE
  * PUT    /api/api-tokens/:id  - rename, enable/disable, edit scopes/expiry
  * DELETE /api/api-tokens/:id  - revoke (immediate)
@@ -23,6 +24,58 @@ import {
 } from '../../services/apiTokens.js';
 import {canSeeArtefact} from '../../services/projects.js';
 
+/** A token this close to its expiry is called out - SOON_DAYS in admin/js/lib/api-tokens-arrange.js. */
+const SOON_DAYS = 14;
+const DAY = 86_400_000;
+
+/**
+ * The sidebar badge on API Tokens (its countUrl, GET /api/api-tokens/_count).
+ *
+ * The number is a signal, not an inventory: the tokens that need someone -
+ * switched on but already expired (every call with one is being refused, and
+ * nothing else says so), and switched on and expiring within SOON_DAYS. Zero is
+ * no badge. Red while any has expired. Plain text - the popover sets it with
+ * textContent; token names are the admin's own, never the secret.
+ *
+ * @param {object[]} tokens - sanitised, as listTokensSanitised returns them
+ * @param {number} [now]
+ */
+export function apiTokensBadge(tokens = [], now = Date.now()) {
+    const on = tokens.filter(t => t.enabled !== false);
+    const at = (t) => (t.expiresAt ? Date.parse(t.expiresAt) : NaN);
+    const expired = on.filter(t => at(t) <= now);
+    const soon = on.filter(t => at(t) > now && at(t) - now <= SOON_DAYS * DAY)
+        .sort((a, b) => at(a) - at(b));
+    const off = tokens.length - on.length;
+    const need = expired.length + soon.length;
+    const plural = (n, one) => `${n} ${one}${n === 1 ? '' : 's'}`;
+    const days = (t) => {
+        const d = Math.ceil((at(t) - now) / DAY);
+        return d <= 0 ? 'today' : d === 1 ? 'tomorrow' : `in ${d} days`;
+    };
+    return {
+        count: need,
+        label: need
+            ? [expired.length && `${plural(expired.length, 'token')} expired`, soon.length && `${soon.length} expiring soon`].filter(Boolean).join(', ')
+            : `${plural(tokens.length, 'token')}, none expiring soon`,
+        tone: expired.length ? 'danger' : 'attention',
+        details: {
+            title: 'API Tokens',
+            rows: [
+                {label: 'Working', value: String(on.length - expired.length)},
+                {label: 'Expiring soon', value: String(soon.length)},
+                {label: 'Expired', value: String(expired.length), ...(expired.length && {tone: 'danger'})},
+                {label: 'Switched off', value: String(off)}
+            ],
+            items: [
+                ...expired.map(t => ({text: String(t.name || '(unnamed)'), meta: `${t.project} · expired - callers are refused`, tone: 'danger'})),
+                ...soon.map(t => ({text: String(t.name || '(unnamed)'), meta: `${t.project} · expires ${days(t)}`}))
+            ].slice(0, 8),
+            empty: 'No token has expired or expires in the next two weeks.'
+        }
+    };
+}
+
 /**
  * Register the api-tokens routes.
  *
@@ -43,6 +96,9 @@ export async function apiTokensRoutes(fastify, opts = {}) {
         return listTokensSanitised(request.user);
     });
 
+    // There is no GET /api-tokens/:id, and ids are uuids - nothing can shadow this.
+    fastify.get('/api-tokens/_count', canRead, async (request) => apiTokensBadge(await listTokensSanitised(request.user)));
+
     fastify.post('/api-tokens', canCreate, async (request, reply) => {
         const {name, project, scopes, expiresAt} = request.body || {};
         if (project && !canSeeArtefact(request.user, {meta: {project}})) {

package/server/routes/api/auth.js

@@ -170,7 +170,13 @@ export async function authRoutes(fastify) {
         if (email) coreUpdates.email = email;
         if (password) coreUpdates.password = password;
 
-        const user = await updateUser(id, coreUpdates);
+        let user;
+        try {
+            user = await updateUser(id, coreUpdates);
+        } catch (err) {
+            if (err.code === 'EMAIL_TAKEN') return reply.status(409).send({error: err.message});
+            throw err;
+        }
 
         if (profile && typeof profile === 'object') {
             await updateProfile(id, profile);

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