domma-cms 0.116.8 → 0.118.0

package/server/routes/public.js

@@ -9,11 +9,10 @@
 import {getPage, getPageMtime} from '../services/content.js';
 import {getProjectForPage, isProjectEnabled} from '../services/projects.js';
 import {renderPage} from '../services/renderer.js';
+import {resolvePublishedPage} from '../services/pagePublishing.js';
 import {buildRobotsTxt, generate as generateSitemap} from '../services/sitemap.js';
-import {checkVisibility} from '../middleware/auth.js';
 import {resolveViewer} from '../services/viewerSession.js';
 import {touchPreviewLink, verifyPreviewToken} from '../services/previewLinks.js';
-import {getPermissionsFor} from '../services/roles.js';
 import {getEffectiveRoles} from '../services/userRoles.js';
 import {hooks} from '../services/hooks.js';
 import {getConfig} from '../config.js';
@@ -184,70 +183,36 @@ export async function publicRoutes(fastify) {
 
         const urlPath = '/' + (rawPath || '');
 
-        // First-pass page lookup - used only for the visibility decision
-        // (metadata-only is sufficient). We re-fetch below with `user` once
-        // it is resolved so the body's [menu] shortcode renders against the
-        // correct role.
-        let page = await getPage(urlPath);
-
-        // Try fetching index of a directory path
-        if (!page && !urlPath.endsWith('/index')) {
-            page = await getPage(urlPath.replace(/\/$/, '') || '/');
-        }
-
-        if (!page) {
-            reply.status(404);
-            return sendHtml(request, reply, await render404(urlPath));
-        }
-
-        // Hard kill-switch: a disabled project takes its pages off the public
-        // site entirely - 404 (no oracle), regardless of page visibility.
-        const pageProject = await getProjectForPage(page.urlPath || urlPath, page.project);
-        if (!(await isProjectEnabled(pageProject))) {
-            reply.status(404);
-            return sendHtml(request, reply, await render404(urlPath));
-        }
-
-        // Draft preview: a page that is not published stays invisible to the
-        // public, but is served in full to a signed-in user who could read it
-        // in the admin anyway. Everyone else gets the same 404 as before - the
-        // response must not reveal that an unpublished page exists there.
-        const isDraft = page.status !== 'published';
-
-        // Enforce page visibility. The viewer is resolved on EVERY request,
-        // not only for gated pages: the navbar, footers, overlays and [menu]
-        // shortcodes on a public page filter their items by role too, and a
-        // signed-in visitor rendered as anonymous never sees the items meant
-        // for them. Resolving is a cookie read plus a JWT verify, and returns
-        // null at once for anonymous traffic, which still shares one entry.
+        // The viewer is resolved on EVERY request, not only for gated pages:
+        // the navbar, footers, overlays and [menu] shortcodes on a public page
+        // filter their items by role too, and a signed-in visitor rendered as
+        // anonymous never sees the items meant for them. Resolving is a cookie
+        // read plus a JWT verify, and returns null at once for anonymous
+        // traffic, which still shares one entry.
         //
-        // `visibility` may be a string ('public' | 'private' | role name) or
-        // an array of role names - see checkVisibility() for full semantics.
-        // Effectively-public values (missing, 'public', or an array containing
-        // 'public') skip viewer resolution entirely so anonymous traffic hits
-        // the shared cache without auth cost - unless the page is a draft,
-        // which needs the viewer regardless of its visibility.
         // The cache key carries every role the viewer holds (sorted), since
         // exact-role visibility (`=candidate`) makes an additional role change
         // what renders. Real sites hold a handful of role combinations, so
         // the entry count stays bounded by what users actually have.
-        const vis      = page.visibility;
-        const isPublic = !vis
-            || vis === 'public'
-            || (Array.isArray(vis) && (vis.length === 0 || vis.includes('public')));
-
         const userObj  = await resolveViewer(request);
         const userRole = userObj ? [...getEffectiveRoles(userObj)].sort().join('+') : null;
 
-        if (isDraft && !canPreviewDrafts(userObj)) {
+        // The access decision - the directory-index fallback, the project
+        // kill-switch, drafts and visibility - is resolvePublishedPage(), shared
+        // with the Content API so the two can never disagree. Drafts are allowed
+        // here: a viewer holding pages.read gets the real page plus a banner;
+        // everyone else gets the same 404 as a missing page, so the response
+        // never reveals that an unpublished page exists there.
+        const verdict = await resolvePublishedPage(urlPath, userObj, {allowDrafts: true});
+        if (verdict.status === 'not-found') {
             reply.status(404);
             return sendHtml(request, reply, await render404(urlPath));
         }
-
-        if (!isPublic && !checkVisibility(userObj, vis)) {
+        if (verdict.status === 'forbidden') {
             reply.status(403);
             return reply.type('text/html; charset=utf-8').send(accessDeniedHtml(urlPath));
         }
+        const {page, isDraft} = verdict;
 
         const baseUrl = getBaseUrl(request);
 
@@ -294,22 +259,6 @@ export async function publicRoutes(fastify) {
     });
 }
 
-/**
- * May this viewer see unpublished pages on the public site?
- *
- * Gated on `pages.read` - the same permission that opens the Pages list in the
- * admin. Anyone who can already read the draft's source there loses nothing by
- * seeing it rendered, and nobody else gains anything.
- *
- * @param {object|null} user - Resolved viewer (`{role, additionalRoles}`) or null
- * @returns {boolean}
- */
-function canPreviewDrafts(user) {
-    if (!user) return false;
-    const allowed = getPermissionsFor('pages', 'read');
-    return getEffectiveRoles(user).some(role => allowed.includes(role));
-}
-
 /**
  * Render a 404 response - tries content/pages/404.md first, falls back to
  * a minimal inline page so the site theme is applied when possible.

package/server/server.js

@@ -460,14 +460,15 @@ app.setErrorHandler((error, request, reply) => {
 // ---------------------------------------------------------------------------
 // The admin SPA must always see the live state of the site - a stale list is
 // indistinguishable from a missing artefact, and the user is left arguing with
-// their own CMS. Everything under /api is no-store EXCEPT the two externally
+// their own CMS. Everything under /api is no-store EXCEPT the three externally
 // consumable surfaces, which have their own caching contracts:
-//   /api/v1/*  - collection access by API token
-//   /api/x/*   - API Builder endpoints
+//   /api/v1/*          - collection access by API token
+//   /api/x/*           - API Builder endpoints
+//   /api/content/v1/*  - the Content API (public / private / no-store per access mode)
 app.addHook('onSend', async (request, reply) => {
     const url = request.raw.url || '';
     if (!url.startsWith('/api/')) return;
-    if (url.startsWith('/api/v1/') || url.startsWith('/api/x/')) return;
+    if (url.startsWith('/api/v1/') || url.startsWith('/api/x/') || url.startsWith('/api/content/v1/')) return;
     reply.header('Cache-Control', 'no-store, must-revalidate');
     reply.header('Pragma', 'no-cache');
     reply.header('Expires', '0');
@@ -497,6 +498,8 @@ const {rolesRoutes}         = await import('./routes/api/roles.js');
 const {apiTokensRoutes}     = await import('./routes/api/api-tokens.js');
 const {apiEndpointsRoutes}  = await import('./routes/api/api-endpoints.js');
 const {endpointsPublicRoutes} = await import('./routes/api/endpoints-public.js');
+const {contentPublicRoutes} = await import('./routes/api/content-public.js');
+const {contentApiRoutes}    = await import('./routes/api/content-api.js');
 const {sidebarRoutes}       = await import('./routes/api/sidebar.js');
 const {documentationRoutes} = await import('./routes/api/documentation.js');
 const { mediaRoutes }      = await import('./routes/api/media.js');
@@ -536,6 +539,8 @@ await app.register(rolesRoutes,         {prefix: '/api'});
 await app.register(apiTokensRoutes,     {prefix: '/api'});
 await app.register(apiEndpointsRoutes,  {prefix: '/api'});
 await app.register(endpointsPublicRoutes, {prefix: '/api'});
+await app.register(contentPublicRoutes, {prefix: '/api'});
+await app.register(contentApiRoutes,    {prefix: '/api'});
 await app.register(sidebarRoutes,       {prefix: '/api'});
 await app.register(documentationRoutes, {prefix: '/api'});
 await app.register(mediaRoutes,       { prefix: '/api' });
@@ -657,6 +662,7 @@ registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Layouts
 registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Plugins', url: '#/plugins', icon: 'package', permission: 'plugins', countUrl: '/api/plugins/_count', inventory: true}});
 registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'API Tokens', url: '#/api-tokens', icon: 'key', permission: 'api-tokens', countUrl: '/api/api-tokens/_count'}});
 registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Search', url: '#/search', icon: 'search', permission: 'settings', countUrl: '/api/search/_count', inventory: true}});
+registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Content API', url: '#/content-api', icon: 'file-text', permission: 'settings', countUrl: '/api/content-api/_count', inventory: true}});
 // Documentation pages added after the sidebar menu was seeded (0.93.1). The menu is
 // seeded once, so new pages reach existing sites only by registering here. The two
 // sub-folders have no key in older menus; findFolder() falls back to their name.
@@ -666,6 +672,7 @@ registerSidebarItem({folder: 'Usage', item: {source: 'Built in', text: 'Editions
 registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'Forms', url: '#/docs/api/forms', icon: 'layout'}});
 registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'Scaffold', url: '#/docs/api/scaffold', icon: 'package'}});
 registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'External API & Tokens', url: '#/docs/api/external', icon: 'key'}});
+registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'Content API', url: '#/docs/api/content', icon: 'file-text'}});
 registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'API Builder', url: '#/docs/api/builder', icon: 'code'}});
 
 // Core's notification sources, before plugins add theirs (0.80).

package/server/services/apiTokens.js

@@ -17,6 +17,12 @@ export const API_TOKENS_COLLECTION_SLUG = 'api-tokens';
 
 const TOKEN_RE = /^dcms_[a-f0-9]{64}$/;
 const VERBS = ['create', 'read', 'update', 'delete'];
+
+/**
+ * What a `{content}` scope may name - the Content API's resources. Content
+ * scopes are read-only (the API has no writes yet), so they carry no verbs.
+ */
+export const CONTENT_RESOURCES = Object.freeze(['pages', 'menus', 'site', 'search']);
 const LAST_USED_THROTTLE_MS = 60_000;
 
 /** In-memory hash → entry cache; null = needs rebuild. */
@@ -75,16 +81,23 @@ function sanitise(entry) {
 }
 
 /**
- * Validate a scopes declaration: array of { collection, verbs[] }.
- * Empty array = the token covers every collection in its project.
+ * Validate a scopes declaration. Each scope is EITHER a collection scope
+ * `{collection, verbs?}` OR a content scope `{content}` (a Content API
+ * resource). Empty array = the token covers everything in its project.
  *
  * @param {*} scopes
  * @returns {string|null} Error message, or null when valid
  */
-function validateScopes(scopes) {
+export function validateScopes(scopes) {
     if (scopes == null) return null;
     if (!Array.isArray(scopes)) return 'scopes must be an array';
     for (const s of scopes) {
+        if (s && typeof s === 'object' && s.content !== undefined) {
+            if (s.collection !== undefined) return 'a scope names either a collection or a content resource, not both';
+            if (!CONTENT_RESOURCES.includes(s.content)) return `unknown content resource "${s.content}"`;
+            if (s.verbs != null) return 'content scopes are read-only and take no verbs';
+            continue;
+        }
         if (!s || typeof s !== 'object' || typeof s.collection !== 'string' || !s.collection.trim()) {
             return 'each scope needs a collection slug';
         }
@@ -101,18 +114,61 @@ function validateScopes(scopes) {
  * Check whether a token's scopes permit an operation on a collection.
  * Empty/missing scopes → everything in the token's project is allowed.
  *
- * @param {Array<{collection: string, verbs?: string[]}>} scopes
+ * @param {Array<{collection?: string, verbs?: string[], content?: string}>} scopes
  * @param {string} collectionSlug
  * @param {string} verb - create | read | update | delete
  * @returns {boolean}
  */
 export function scopeAllows(scopes, collectionSlug, verb) {
     if (!Array.isArray(scopes) || scopes.length === 0) return true;
-    const scope = scopes.find(s => s.collection === collectionSlug);
+    // Content scopes never match: a collection named `pages` is still a collection.
+    const scope = scopes.find(s => s.collection !== undefined && s.collection === collectionSlug);
     if (!scope) return false;
     return !Array.isArray(scope.verbs) || scope.verbs.length === 0 || scope.verbs.includes(verb);
 }
 
+/**
+ * Does a token's scope list permit a Content API resource? Empty = everything
+ * in the project. A list that names no content resource permits none - a token
+ * scoped to collections is never widened by the Content API existing.
+ *
+ * @param {object[]} scopes
+ * @param {string} resource - one of CONTENT_RESOURCES
+ * @returns {boolean}
+ */
+export function contentScopeAllows(scopes, resource) {
+    if (!Array.isArray(scopes) || scopes.length === 0) return true;
+    return scopes.some(s => s.content === resource);
+}
+
+const BEARER_RE = /^Bearer (dcms_[a-f0-9]{64})$/;
+
+/**
+ * The strict token check, shared by every externally consumable gate - the
+ * collections API (and the API Builder endpoints that reuse it) and the
+ * Content API. A token is the ONLY credential accepted: callers decide when
+ * token mode applies, and this never looks at a JWT.
+ *
+ * `project` binds the token to the resource's project. Omit it when the
+ * caller binds per resource instead (a Content API page list spans projects
+ * and is filtered to the token's). `allows` receives the token's scopes.
+ *
+ * @param {{headers?: object}} request
+ * @param {{project?: string, allows: (scopes: object[]) => boolean, projectError?: string}} opts
+ * @returns {Promise<{ok: true, token: object} | {ok: false, status: 401|403, error: string}>}
+ */
+export async function authenticateApiToken(request, {project, allows, projectError}) {
+    const match = (request.headers?.authorization || '').match(BEARER_RE);
+    if (!match) return {ok: false, status: 401, error: 'API token required'};
+    const token = await validateToken(match[1]);
+    if (!token) return {ok: false, status: 401, error: 'Invalid, disabled or expired API token'};
+    if (project !== undefined && token.project !== project) {
+        return {ok: false, status: 403, error: projectError || "Token is not valid for this resource's project"};
+    }
+    if (!allows(token.scopes)) return {ok: false, status: 403, error: 'Token scope does not permit this operation'};
+    return {ok: true, token};
+}
+
 /**
  * Create a new token. The plaintext is returned ONCE here and never again.
  *

package/server/services/content.js

@@ -167,7 +167,7 @@ export async function createPage(urlPath, frontmatter, body) {
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body || ''), 'utf8');
     const page = await readPageFile(filePath);
-    await cache.invalidateTags([`page:${urlPath}`, 'sitemap']);
+    await cache.invalidateTags([`page:${urlPath}`, 'sitemap', 'pages:list']);
     hooks.emit('content:pageCreated', {page, urlPath});
     return page;
 }
@@ -222,7 +222,7 @@ export async function updatePage(urlPath, frontmatter, body, {author} = {}) {
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body ?? existingContent), 'utf8');
     const page = await readPageFile(filePath);
-    await cache.invalidateTags([`page:${urlPath}`, 'sitemap']);
+    await cache.invalidateTags([`page:${urlPath}`, 'sitemap', 'pages:list']);
     hooks.emit('content:pageUpdated', {page, urlPath});
     return page;
 }
@@ -240,7 +240,7 @@ export async function renamePage(oldUrlPath, newUrlPath) {
     const newFile = urlPathToFilePath(newUrlPath);
     await fs.mkdir(path.dirname(newFile), { recursive: true });
     await fs.rename(oldFile, newFile);
-    await cache.invalidateTags([`page:${oldUrlPath}`, `page:${newUrlPath}`, 'sitemap']);
+    await cache.invalidateTags([`page:${oldUrlPath}`, `page:${newUrlPath}`, 'sitemap', 'pages:list']);
     try {
         await renameVersionDir(oldUrlPath, newUrlPath);
     } catch {
@@ -259,7 +259,7 @@ export async function renamePage(oldUrlPath, newUrlPath) {
 export async function deletePage(urlPath) {
     const filePath = await resolveExistingFilePath(urlPath);
     await fs.unlink(filePath);
-    await cache.invalidateTags([`page:${urlPath}`, 'sitemap']);
+    await cache.invalidateTags([`page:${urlPath}`, 'sitemap', 'pages:list']);
     hooks.emit('content:pageDeleted', {urlPath});
     try {
         await deleteAllVersions(urlPath);

package/server/services/contentApi.js

@@ -0,0 +1,248 @@
+/**
+ * Content API - settings and payloads.
+ *
+ * Settings live in config/content-api.json (optional; absence = the defaults,
+ * which are OFF - an upgrade must not expose a site that never chose to be).
+ *
+ * Every payload is built from an ALLOWLIST. Frontmatter is open-ended (authors
+ * and plugins add keys freely) and site.json holds SMTP credentials, so a
+ * spread-then-delete is one forgotten key away from a leak.
+ */
+import {getConfig, saveConfig} from '../config.js';
+import {CONTENT_RESOURCES} from './apiTokens.js';
+import {isPubliclyListed} from './search.js';
+import {plural} from './sidebarBadges.js';
+
+export const FORMATS = Object.freeze(['html', 'markdown']);
+
+export const CONTENT_API_DEFAULTS = Object.freeze({
+    enabled: false,
+    access: 'token',
+    resources: Object.freeze(Object.fromEntries(CONTENT_RESOURCES.map(k => [k, Object.freeze({enabled: true})]))),
+    formats: Object.freeze(['html']),
+    listable: true,
+    maxLimit: 200
+});
+
+const MAX_LIMIT = 200;
+
+/**
+ * @param {object} [raw] - config/content-api.json as stored, or a patch merged onto it
+ * @returns {object} A fresh, complete settings object
+ */
+export function normaliseContentApiSettings(raw) {
+    const r = raw && typeof raw === 'object' ? raw : {};
+    const access = typeof r.access === 'string' && r.access.trim() ? r.access.trim() : CONTENT_API_DEFAULTS.access;
+    const formats = Array.isArray(r.formats) ? FORMATS.filter(f => r.formats.includes(f)) : [];
+    const limit = Math.trunc(Number(r.maxLimit));
+    return {
+        enabled: r.enabled === true,
+        access,
+        resources: Object.fromEntries(CONTENT_RESOURCES.map(k => [k, {enabled: r.resources?.[k]?.enabled !== false}])),
+        formats: formats.length ? formats : [...CONTENT_API_DEFAULTS.formats],
+        listable: r.listable !== false,
+        maxLimit: Number.isFinite(limit) ? Math.min(MAX_LIMIT, Math.max(1, limit)) : CONTENT_API_DEFAULTS.maxLimit
+    };
+}
+
+/** Current settings, defaults filled in. A site with no file gets the (off) defaults. */
+export function getContentApiSettings() {
+    try {
+        return normaliseContentApiSettings(getConfig('content-api'));
+    } catch {
+        return normaliseContentApiSettings({});
+    }
+}
+
+/**
+ * Save settings, returning what was actually stored.
+ *
+ * @param {object} patch - Partial or complete settings
+ * @returns {object}
+ */
+export function saveContentApiSettings(patch) {
+    const next = normaliseContentApiSettings({...getContentApiSettings(), ...(patch || {})});
+    saveConfig('content-api', next);
+    return next;
+}
+
+// ---------------------------------------------------------------------------
+// Payloads
+// ---------------------------------------------------------------------------
+
+const SUMMARY_KEYS = ['urlPath', 'title', 'description', 'tags', 'category', 'layout', 'updatedAt'];
+const DETAIL_KEYS  = [...SUMMARY_KEYS, 'createdAt'];
+const SEO_KEYS     = ['title', 'description', 'image', 'canonical', 'noindex'];
+
+const pick = (obj, keys) => Object.fromEntries(keys.filter(k => obj?.[k] !== undefined).map(k => [k, obj[k]]));
+
+/**
+ * The Domma behaviour a page's HTML relies on: the markup public/js/site.js
+ * (and public/js/effects.js) initialise. A client rendering `html` without Domma gets these inert, so
+ * the API names them. `usedComponents` does not cover them - it lists only
+ * custom `[component]`s, and a page of tabs reports none.
+ *
+ * Matched on real attributes only: markup shown in a code block is escaped
+ * (`<div class="tabs`) and never matches. Keep in step with site.js.
+ */
+const DOMMA_MARKERS = [
+    ['tabs',             {cls: 'tabs'}],
+    ['accordion',        {cls: 'accordion'}],
+    ['carousel',         {cls: 'carousel'}],
+    ['countdown',        {cls: 'dm-countdown'}],
+    ['progression',      {cls: 'dm-progression'}],
+    ['slideover',        {cls: 'dm-so-trigger'}],
+    ['cta',              {cls: 'dm-cta-trigger'}],
+    ['collapsible',      {attr: 'data-collapsible'}],
+    ['tooltip',          {attr: 'data-tooltip'}],
+    ['reveal',           {attr: 'data-reveal'}],
+    ['collection-table', {attr: 'data-collection-table'}],
+    ['form',             {attr: 'data-form-inline'}],
+    ['collection',       {cls: 'dm-collection-hydrate'}],
+    ['page-config',      {cls: 'dm-page-config'}],
+    // Every effect (scribe, reveal, celebrate, counter, …) is a dm-fx-<name> class.
+    ['effects',          {prefix: 'dm-fx-'}]
+];
+
+/**
+ * @param {string} html
+ * @returns {string[]} Marker names found, in DOMMA_MARKERS order
+ */
+export function domma(html) {
+    if (typeof html !== 'string' || !html) return [];
+    const classes = new Set();
+    for (const m of html.matchAll(/<[^>]*?\sclass="([^"]*)"/g)) {
+        for (const c of m[1].split(/\s+/)) if (c) classes.add(c);
+    }
+    const hasAttr = (name) => new RegExp(`<[^>]*\\s${name}(?=[\\s=/>])`).test(html);
+    return DOMMA_MARKERS
+        .filter(([, m]) => {
+            if (m.prefix) return [...classes].some(c => c.startsWith(m.prefix));
+            return m.cls ? classes.has(m.cls) : hasAttr(m.attr);
+        })
+        .map(([name]) => name);
+}
+
+/**
+ * A page in a list: enough to link to it, never its body - the list must stay
+ * cheap enough to run over every page without rendering any.
+ *
+ * @param {object} page - a listPages() row
+ * @returns {object}
+ */
+export function pageSummary(page) {
+    return pick(page, SUMMARY_KEYS);
+}
+
+/**
+ * One page. `html` is the body only (page.html), not the full document with
+ * navbar and footer; `markdown` is the source, shortcodes and all.
+ *
+ * @param {object} page - a getPage() result the caller is allowed to see
+ * @param {{format: 'html'|'markdown'|'both'}} opts
+ * @returns {object}
+ */
+export function pageDetail(page, {format}) {
+    const out = pick(page, DETAIL_KEYS);
+    if (page.seo && typeof page.seo === 'object') out.seo = pick(page.seo, SEO_KEYS);
+    if (format === 'html' || format === 'both') out.html = page.html || '';
+    if (format === 'markdown' || format === 'both') out.markdown = page.content || '';
+    const custom = Array.isArray(page.usedComponents) ? page.usedComponents : [];
+    const components = [...new Set([...domma(page.html), ...custom])];
+    out.requires = {domma: components.length > 0, components};
+    out.perViewer = Boolean(page.perViewer);
+    return out;
+}
+
+/**
+ * Site settings safe for any caller: exactly what every public page already
+ * shows - the title, navbar brand, footer (hidden links stay hidden, as in
+ * renderer.js), social links, the SEO defaults in its meta tags, and the theme
+ * class. `tagline`, `url`, `smtp` and the admin settings never reach a public
+ * page, so they never reach this either.
+ *
+ * @param {object} [site] - config/site.json
+ * @returns {object}
+ */
+export function publicSiteSettings(site = {}) {
+    const out = pick(site, ['title', 'social', 'theme']);
+    if (site.brand && typeof site.brand === 'object') out.brand = pick(site.brand, ['text', 'logo', 'url']);
+    if (site.footer && typeof site.footer === 'object') {
+        out.footer = {...site.footer, links: (site.footer.links || []).filter(l => !l?.hidden)};
+    }
+    if (site.seo && typeof site.seo === 'object') out.seo = pick(site.seo, ['defaultTitle', 'titleSeparator', 'defaultDescription']);
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// The admin screen: coverage, and the sidebar badge
+// ---------------------------------------------------------------------------
+
+/**
+ * How many pages the API can serve an anonymous caller - the same rule as its
+ * page list (isPubliclyListed, then `api: false`). A signed-in role-mode caller
+ * may get more: the gated pages they can open.
+ *
+ * @param {object[]} pages - listPages()
+ * @param {{offline?: Set<string>, noindex?: Set<string>}|null} [exclusions] - searchExclusions()
+ * @returns {{served: number, keptOff: number, total: number}}
+ */
+export function contentApiCoverage(pages = [], exclusions = null) {
+    let served = 0;
+    let keptOff = 0;
+    for (const p of pages) {
+        if (!isPubliclyListed(p, null, exclusions)) continue;
+        if (p.api === false) keptOff++;
+        else served++;
+    }
+    return {served, keptOff, total: pages.length};
+}
+
+/** How a settings `access` value reads to a person. */
+export function accessLabel(access) {
+    if (access === 'public') return 'public';
+    if (access === 'token') return 'API token';
+    return `role: ${access} and above`;
+}
+
+const FORMAT_LABEL = {html: 'HTML', markdown: 'Markdown'};
+
+/**
+ * The sidebar badge on System › Content API (its countUrl, GET
+ * /api/content-api/_count): the pages served, and how the API is set up in
+ * the popover. An inventory, not a signal - plain text throughout.
+ *
+ * @param {object} settings
+ * @param {object[]} pages
+ * @param {object|null} [exclusions]
+ */
+export function contentApiBadge(settings, pages = [], exclusions = null) {
+    const s = normaliseContentApiSettings(settings);
+    const c = contentApiCoverage(pages, exclusions);
+    const served = plural(c.served, 'page');
+    const access = accessLabel(s.access);
+    const resources = CONTENT_RESOURCES.filter(k => s.resources[k].enabled);
+    return {
+        count: c.served,
+        label: s.enabled
+            ? `Content API is on (${access}) - ${served} served`
+            : `Content API is off - ${served} would be served`,
+        tone: 'info',
+        details: {
+            title: 'Content API',
+            rows: [
+                {label: 'Status', value: s.enabled ? 'On' : 'Off'},
+                {label: 'Access', value: access.charAt(0).toUpperCase() + access.slice(1)},
+                {label: 'Resources', value: resources.length ? resources.join(', ') : 'none'},
+                {label: 'Formats', value: s.formats.map(f => FORMAT_LABEL[f]).join(', ')},
+                {label: 'Page list', value: s.listable ? 'On' : 'Off - single pages only'},
+                {label: 'Pages served', value: String(c.served)},
+                {label: 'Kept off (api: false)', value: String(c.keptOff)}
+            ],
+            items: [],
+            empty: s.enabled
+                ? 'Callers get the published pages an anonymous visitor could open, except pages marked api: false.'
+                : 'The Content API is switched off - every /api/content/v1 address answers 404.'
+        }
+    };
+}

package/server/services/menuRender.js

@@ -14,7 +14,7 @@ import {colourToCss, floatToCss, floatBehaviour, spacerSize} from './menus.js';
 // Highlight helpers live once, in the browser module, and are imported here -
 // the same shared-module arrangement collection-export.mjs has with
 // collections.js. Nothing in them touches the DOM.
-import {highlightAttrs, itemHighlightAttrs, isCurrentItem, menuAlign} from '../../public/js/menu-decor.mjs';
+import {highlightAttrs, itemHighlightAttrs, isCurrentItem, menuAlign, cssClasses} from '../../public/js/menu-decor.mjs';
 
 /** Attribute-safe escaping - mirrors escapeAttr in markdown.js. */
 function esc(str) {
@@ -56,6 +56,10 @@ export function renderMenuItemsAsUl(items, currentPath = '') {
         // needs an explicit allowlist entry.
         const current   = isCurrentItem(it.url, currentPath);
         const classAttr = current ? ' class="is-active" aria-current="page"' : '';
+        // The designer's own classes go on the <li>, so they can lay the item
+        // out (push it right, size it) as well as style its link.
+        const liClasses = cssClasses(it.class);
+        const liAttr    = liClasses.length ? ` class="${esc(liClasses.join(' '))}"` : '';
 
         // Per-item highlight override. `data-menu-item-*` rather than the
         // menu's `data-menu-*` so the CSS can let the item win without the two
@@ -86,7 +90,7 @@ export function renderMenuItemsAsUl(items, currentPath = '') {
             badge = `<span class="dm-menu-badge"${badgeStyle}>${esc(String(it.badge.text))}</span>`;
         }
 
-        return `<li><a href="${href}"${classAttr}${styleAttr}${ihlAttrs}>${text}${badge}</a>${child}</li>`;
+        return `<li${liAttr}><a href="${href}"${classAttr}${styleAttr}${ihlAttrs}>${text}${badge}</a>${child}</li>`;
     }).join('');
     return `<ul>${lis}</ul>`;
 }
@@ -106,7 +110,9 @@ export function renderMenuItemsAsUl(items, currentPath = '') {
  * @returns {string}
  */
 export function buildMenuNav(menu, items, opts = {}) {
-    const klass        = opts.class   ? ` ${esc(opts.class)}`                    : '';
+    // The menu's own designer classes, then this placement's `[menu class=…]`.
+    const menuClasses  = cssClasses(menu.class).join(' ');
+    const klass        = [menuClasses, opts.class].filter(Boolean).map(c => ` ${esc(c)}`).join('');
     const variantClass = opts.variant ? ` dm-menu--variant-${esc(opts.variant)}` : '';
 
     // A menu that declares no orientation emits no class at all and keeps the

package/server/services/menus.js

@@ -19,7 +19,7 @@ import * as cache from './cache/index.js';
 import {
     HIGHLIGHT_HOVER, HIGHLIGHT_ACTIVE, MENU_ALIGN,
     LEGACY_STYLE_HOVER, LEGACY_STYLE_ACTIVE, legacyStyleHighlight,
-    PRESET_COLOUR_VARS, PRESET_COLOUR_FALLBACKS, colourToCss
+    PRESET_COLOUR_VARS, PRESET_COLOUR_FALLBACKS, colourToCss, cssClassProblems
 } from '../../public/js/menu-decor.mjs';
 
 /**
@@ -722,6 +722,8 @@ export function validateMenu(menu) {
             }
         }
     }
+    // Designer classes on the menu's outer element - see cssClasses in menu-decor.mjs.
+    for (const p of cssClassProblems(menu.class)) errors.push(`class: ${p}`);
     if (menu.align != null && menu.align !== '' && !MENU_ALIGN.includes(menu.align)) {
         errors.push(`align must be one of: ${MENU_ALIGN.join(', ')}`);
     }
@@ -815,6 +817,7 @@ export function validateMenu(menu) {
             if (item.colour != null && !isValidColour(item.colour)) {
                 errors.push(`Item ${path}: colour must be a preset key or #rrggbb`);
             }
+            for (const p of cssClassProblems(item.class)) errors.push(`Item ${path}: class: ${p}`);
             // Per-item highlight override. Same shape and same value sets as
             // the menu-level `highlight` block validated above - an item that
             // omits a half falls through to the menu's choice for that half.