domma-cms 0.88.1 → 0.89.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "0.88.1",
+  "version": "0.89.0",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",

package/plugins/blog/CLAUDE.md

@@ -165,6 +165,12 @@ with `?display=` and swaps the cards, since each display is different block mark
 
 ## Gotchas
 
+- **In the sitemap (1.9.0, core 0.89+).** `registerSitemapSource('blog')` lists the index and every public post at the
+  live base path (a post with `seo.noindex` is left out); a non-GET that succeeds on /posts, /settings or /samples calls
+  `sitemapChanged()`. Post pages pass `baseUrl` (canonical/og:url - they had none before), `noindex` and
+  `item: {type: 'blog:post', id}` to renderBlogPage, so the SEO plugin knows what it is tagging. PUT /posts/:id MERGES
+  `seo` (the editor sends title + description only; the SEO Tool may have set image/noindex/focus).
+
 - **Public handlers must RETURN the reply.** `reply.type(...).send(html)` without `return` in an
   async handler loses the body under @fastify/compress - every browser got a 200 with nothing in it,
   while curl (no Accept-Encoding) saw the page. `tests/public.test.js` drives gzip and brotli.

package/plugins/blog/plugin.js

@@ -291,6 +291,23 @@ export default async function blogPlugin(fastify, options) {
         registerEmbedShortcodes(options.hooks.registerShortcode, () => liveBase(settings));
     }
 
+    // The blog in /sitemap.xml (core 0.89+; feature-detected): the index and
+    // every public post, at the base path as it is saved now. A post marked
+    // "hide from search engines" (seo.noindex) is left out.
+    if (typeof options.hooks?.registerSitemapSource === 'function') {
+        options.hooks.registerSitemapSource({id: 'blog', label: 'Blog posts', list: async () => {
+            const base = liveBase(settings);
+            const posts = (await loadAll('blog-posts')).filter(p => isVisible(p) && p.seo?.noindex !== true);
+            return [{urlPath: base, title: 'Blog', changefreq: 'daily'},
+                ...posts.map(p => ({urlPath: `${base}/${encodeURIComponent(p.slug)}`, title: p.title || '',
+                    lastmod: p.updatedAt || p.publishedAt || null, ...(safeImageUrl(p.featuredImage) && {image: safeImageUrl(p.featuredImage)})}))];
+        }});
+        // A saved post, publish or setting changes the list: the sitemap is rebuilt on its next request.
+        fastify.addHook('onResponse', async (request, reply) => {
+            if (request.method !== 'GET' && reply.statusCode < 400 && /\/(posts|settings|samples)\b/.test(request.url)) options.hooks.sitemapChanged?.();
+        });
+    }
+
     // The layouts are blocks; put the shipped ones where the Blocks tool can
     // edit them. Once each, never over a site's own copy (lib/render.js).
     try {
@@ -487,6 +504,12 @@ export default async function blogPlugin(fastify, options) {
         }
 
         const merged  = { ...entry.data, ...postFields(request.body ?? {}, user) };
+        // `seo` is merged too: the editor sends title and description only, and
+        // must not wipe what the SEO Tool set (image, noindex, focus keyword...).
+        if (merged.seo && typeof merged.seo === 'object' && entry.data.seo && typeof entry.data.seo === 'object') {
+            merged.seo = {...entry.data.seo, ...merged.seo};
+            for (const [k, v] of Object.entries(merged.seo)) if (v === null) delete merged.seo[k];
+        }
 
         const updated = await updateEntry(POSTS_SLUG, id, merged);
         return reply.send(toPost(updated));

package/plugins/blog/plugin.json

@@ -1,11 +1,11 @@
 {
   "name": "blog",
   "displayName": "Blog",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "tier": "free",
   "description": "Public-facing blog with posts, categories and comments - layouts and listings built from editable blocks.",
   "author": "Domma CMS",
-  "date": "2026-09-26",
+  "date": "2026-09-27",
   "icon": "file-text",
   "admin": {
     "css": [

package/plugins/blog/plugin.public.js

@@ -15,6 +15,7 @@
 import path from 'path';
 import {fileURLToPath} from 'url';
 import {renderBlogPage} from '../../server/services/renderer.js';
+import {getConfig} from '../../server/config.js';
 import {byNewest, escapeHtml, matchBlogPath, pickDisplay, safeImageUrl} from './lib/layouts.js';
 import {catalogue, renderCards} from './lib/render.js';
 import {authorNamesFor, isVisible, liveBase, liveSettings, loadEntries, renderPostPage, resolveAuthorName} from './lib/page.js';
@@ -49,6 +50,15 @@ function buildPagination(page, totalPages, basePath, query = '') {
     return `<nav class="blog-pagination" aria-label="Pages">${parts.join('')}</nav>`;
 }
 
+/**
+ * The site's own origin for canonical and og:url - as core's getBaseUrl():
+ * the Settings address when there is one, else the request's.
+ */
+function originOf(request) {
+    const set = String(getConfig('site')?.baseUrl || '').trim().replace(/\/+$/, '');
+    return set || `${request.protocol}://${request.host || request.headers.host || request.hostname}`;
+}
+
 /** JSON inside a <script> element, safe against `</script>` in any value. */
 function scriptJson(value) {
     return JSON.stringify(value).replace(/</g, '\\u003c');
@@ -121,7 +131,7 @@ ${items || ''}
                 pagination: interactive ? '' : buildPagination(safePage, totalPages, base, requested),
                 assetV: ASSET_V
             },
-            {title, urlPath: request.url.split('?')[0]}
+            {title, urlPath: request.url.split('?')[0], baseUrl: originOf(request)}
         );
         return reply.type('text/html').send(html);
     }
@@ -215,7 +225,10 @@ ${items}
                     ogImage: safeImageUrl(post.featuredImage),
                     ogType: 'article',
                     usedComponents: page.usedComponents,
-                    urlPath: `${base}/${slug}`
+                    urlPath: `${base}/${slug}`,
+                    baseUrl: originOf(request),
+                    noindex: post.seo?.noindex === true,
+                    item: {type: 'blog:post', id: post.id}
                 }
             );
             return reply.type('text/html').send(html);

package/plugins/free-tier.lock.json

@@ -1,11 +1,11 @@
 {
   "note": "Written by `make sync-free-tier` in dcms-marketplace. Do not edit these plugins here - edit them there and sync.",
-  "source": "dcms-marketplace@6301533",
+  "source": "dcms-marketplace@466a485",
   "plugins": {
     "blog": {
-      "version": "1.8.0",
+      "version": "1.9.0",
       "files": {
-        "CLAUDE.md": "026438d4d93f5a637be16ac22d5131e8248e93d2df1bd9b30d5f1cfe357ba2cc",
+        "CLAUDE.md": "5f3260acc22f202ce3dd1a262a41d4a98016a71e05da8f95732dcd73b6e08e33",
         "admin/css/index.css": "6142a6b756e1218157842528830b1e84f592f0b84b7d5ce6449db421b6f4b039",
         "admin/templates/blog.html": "a6054c1febe764bb1edf5c9e466d44a9080d9c83ba5486437b7a8244acf5ba54",
         "admin/templates/categories.html": "ab7d6fc2fedd48876c585bc216a1532b3bdd78c946dee976c1171bfe4664feb6",
@@ -48,9 +48,9 @@
         "lib/page.js": "464face32871185368de096ed9a6aa635523bf319af6459308cfceb77d66f82c",
         "lib/render.js": "0e97c6a950bc962c8d8ea4b2f21d06cb73fbcdc738d8942d6935d01309a29b1d",
         "lib/samples.js": "e8cdb77ce22e43937707f6854d3a5cb722437dc584e22ac7b24480bef686cf85",
-        "plugin.js": "db93fd831f6ff6762c6768d47e658830b6284b6f4a9efd2bbffaab5966ba0361",
-        "plugin.json": "d6a254e9ec114cbc469e8e2b5a9ca33376c3f88e49c54d42ea589ac883e3dac3",
-        "plugin.public.js": "8efc1ff3a2ead68d36fbd545f8ce590f600b293896ba6f4947418b1efcdf2947",
+        "plugin.js": "a6e4442400594116c43aab1db706f0b9c2953e85699aa458709752c6c27fd781",
+        "plugin.json": "234c8067a4bf9f214667b5c99e05933c3321f0b8b35815a76e8ac8eacbbda857",
+        "plugin.public.js": "ab23fadd5655fab8eea0e636a3e1f8ced78432d6da929059a4a147f0805ff3a4",
         "public/blog.css": "fd733e6b624190da1e70dc1b6613e2376efd7f7570a28fab311d81006d03d960",
         "public/blog.js": "d01c72a9834dcc7c5241923371f2b164ac30d20ac9f1a5c5dc5b71fa3cb09f08",
         "public/samples/aurora.svg": "feb29e2b46465913fc29de9eda221b00b1541f1fa3ea7120f0c1d1cd11a9a4f6",
@@ -106,6 +106,25 @@
         "tests/security.test.js": "f0cb70dcb28bc8b3de8d3b39064616296382c5b0f97bfd615ee8e24fe3b031bc"
       }
     },
+    "seo": {
+      "version": "1.0.0",
+      "files": {
+        "CLAUDE.md": "c4b326afeacded36d076f96ec3554b6cd875087ea5c84b29dffb144059292ff7",
+        "admin/lib/analyse.js": "368b9e20bc1eac957870272ee6909b5f7c09ecf0a2fc2c344fb5cd85473f18cd",
+        "admin/lib/redirects.js": "a506ca40b712c3d8087d6698397b900fe5005ae6094f80dbc3f3091d5d9b6819",
+        "admin/lib/schema.js": "4313e0ed528562ee8b85c18479663c8216101f892848b44426baefc8d7c1c7e8",
+        "admin/lib/settings.js": "94e76c2960376f0cc0570128a7226af177f5de7ee115357e37baba45b1e05e19",
+        "admin/templates/seo.html": "e8684d98bd0649c001d7395b75b2bc3c74234f947d3dbda508ff4ecb91e20d1c",
+        "admin/views/seo.js": "b37774a5df642bdbdb6f7fb89b12dbc6d45d06d2b70bd2de7faf4c3098c26189",
+        "config.js": "d90f4cfb10b2f44b528de37522d31fd01351a6ebbab95556b5dfa2820d69e1a8",
+        "plugin.js": "3dd88bec75535349e6a748bae90fc49e54e2781c4765b9c8ff02898795ef476d",
+        "plugin.json": "6fe2fb5d50d37cc9749cf84db7ed59c5557a52c1b38f63c8e7bc1744065cd7d6",
+        "server/audit.js": "f51fcf9403ad40fde9e9ba5f31e58ed95fc2a5c8514c921146f23ee1ca2e0bd3",
+        "server/registry.js": "9336614bff3ab8b4fe9d50de074a9633307ab41c46fa62113ca82379cfad90a6",
+        "server/store.js": "3584ec3efd8a2d0ba8fd5be7e56d97cca76b5b2358a7dda99e379c42be67253c",
+        "tests/seo.test.js": "bdc52f2a9f8f02aaa0cb907f76f1acf8ff887034172e18d9ae108d3675b68f1a"
+      }
+    },
     "shopping-cart": {
       "version": "1.0.0",
       "files": {

package/plugins/seo/CLAUDE.md

@@ -0,0 +1,48 @@
+# SEO (free) - AI Assistant Guide
+
+How the site looks to search engines, and what to fix. Free tier (`make sync-free-tier` ships it with the engine).
+SEO Pro (paid) is an ADD-ON (`requires: ["seo"]`, no supersedes) that plugs in through `server/registry.js`.
+Social (paid, planned) will be its own plugin, sold with SEO Pro.
+
+Needs core 0.89 for: `hooks.registerSitemapSource` / `sitemapChanged`, and the `seo:meta`, `sitemap:entries`,
+`robots:lines` transforms (core `renderer.js` buildSeoMeta/renderSeoTags, `sitemap.js`). On an older engine the plugin
+logs it, the screen says so, and the audit, editor and redirects still work (`hasCore` in plugin.js).
+
+## What it does
+- **Audit** (`server/audit.js`): every sitemap URL (`listSitemapEntries`) plus published pages kept out of it, fetched
+  IN-PROCESS with `fastify.inject` (UA `DommaSEO/1 (audit)`, header `x-domma-seo: audit` - analytics / SEO Pro skip
+  those), judged by `admin/lib/analyse.js` (pure: `scanHtml` regex scanner - no DOM, `analyse`, `siteIssues`, `snippet`).
+  Every `audit.everyHours` (first run 3 min after start if stale), or POST /audit. Kept in `data/audit.json`.
+- **Editor per URL** (GET/PUT /item): a core page is edited IN PLACE (`updatePage(path, {seo})`, empty -> null so core's
+  merge removes the key); anything else (a blog post) gets an override in `data/overrides.json`, applied by the
+  `seo:meta` transform (`admin/lib/schema.js applySeo`). Fields: title, description, image, noindex, focus.
+- **Redirects** (`admin/lib/redirects.js`, pure): exact and "/prefix/*" rules, 301/302/307/308/410, query kept, no
+  loops (checkRule follows the chain), `onMoved` on core's `content:pageRenamed` re-aims older rules (no chains) and
+  drops a rule FROM the new address. Guard = global `onRequest` (fastify-plugin), GET/HEAD, never /api or /admin.
+  Hits counted in memory, saved each minute.
+- **Sitemap/robots**: `sitemap:entries` drops excluded paths, switched-off sources, overridden noindex and redirected
+  addresses; `robots:lines` adds rules (plain rules into the `*` group; `User-agent:` blocks as their own groups) or
+  blocks everything. JSON-LD: Organization/LocalBusiness/Person on `/`, BlogPosting when `page.item.type === 'blog:post'`.
+
+## Data (plugins/seo/data - kept by updates, never bundled)
+`redirects.json`, `overrides.json`, `audit.json` - in memory (the guard and transform run on every request), debounced
+writes, re-read within ~3 s when changed on disk (`server/store.js`).
+
+## Permission
+`seo` (read / manage), granted to admin. Routes: /overview /count /audit (GET, POST) /item (GET, PUT) /redirects
+(GET, POST, PUT/:id, DELETE/:id - ids comma-separated) /redirects/import /redirects/test /sitemap /settings /extensions.
+
+## Extensions (SEO Pro)
+`globalThis[Symbol.for('domma.seo')]` (`server/registry.js`): `register(owner, {label, tabs})`, `on('audit', fn)`,
+`services` {settings, listEntries, auditList, fetchPage, scanHtml, analyse, audit {latest, summary, run},
+redirects {list, match, add}, auditUserAgent}. Tabs: `{key, label, icon, module, help}`; `module` is a
+`/plugins/<slug>/...` URL exporting `mount(root, ctx)` -> dispose; ctx = {kit, api, scope, here, openItem, reload, E, M, I}.
+
+## Admin
+`admin/views/seo.js` + `admin/templates/seo.html` (prefix `sox-`): Pages (the audit + "Across the site"), Redirects,
+Sitemap, extension tabs; page editor slideover (search result + share card previews, meters, checks); settings
+slideover. Rows by index, text through data-bind-text only.
+
+## Tests
+`tests/seo.test.js` (pure). Headless: throwaway CMS from a clean domma-cms worktree with plugins/seo + blog copied in;
+puppeteer-core + ~/.cache/ms-playwright chromium_headless_shell for screenshots.

package/plugins/seo/admin/lib/analyse.js

@@ -0,0 +1,286 @@
+/**
+ * SEO - reading a rendered page and judging it. Pure: no DOM, no network, so
+ * the server's audit, the admin screen and the tests share it.
+ *
+ *   scanHtml(html)            -> facts (title, description, headings, images, links, words...)
+ *   analyse(facts, opts)      -> {score, checks: [{id, group, status, title, detail, fix}]}
+ *   siteIssues(results)       -> duplicates across pages (titles, descriptions)
+ *   snippet({title, ...})     -> what a search result would show, cut where Google cuts
+ *
+ * A status is 'pass' | 'warn' | 'fail' | 'info'. The score counts a pass as
+ * 1, a warn as 0.5, a fail as 0, and leaves 'info' out - as Security does.
+ *
+ * @module seo/admin/lib/analyse
+ */
+
+export const LIMITS = {titleMin: 30, titleMax: 60, descMin: 70, descMax: 160, minWords: 300};
+
+const ENTITIES = {amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', ndash: '–', mdash: '—', hellip: '…',
+    lsquo: '‘', rsquo: '’', ldquo: '“', rdquo: '”', pound: '£', euro: '€', copy: '©'};
+
+/** Undo HTML entities in text. */
+export function decode(s) {
+    return String(s ?? '').replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => {
+        if (e[0] === '#') {
+            const n = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+            return Number.isFinite(n) && n > 0 && n < 0x110000 ? String.fromCodePoint(n) : m;
+        }
+        return ENTITIES[e.toLowerCase()] ?? m;
+    });
+}
+
+const squash = (s) => decode(String(s ?? '').replace(/<[^>]*>/g, ' ')).replace(/\s+/g, ' ').trim();
+
+/** The attributes of one start tag: `<meta name="x" content='y' async>` -> {name, content, async: ''}. */
+export function attrs(tag) {
+    const out = {};
+    const body = String(tag).replace(/^<\s*[a-z0-9-]+/i, '').replace(/\/?>$/, '');
+    const re = /([^\s"'=<>`/]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+    let m;
+    while ((m = re.exec(body))) out[m[1].toLowerCase()] = decode(m[2] ?? m[3] ?? m[4] ?? '');
+    return out;
+}
+
+/**
+ * The facts of one page, from its HTML. Scripts, styles, templates and
+ * comments are removed first, so nothing inside them counts.
+ *
+ * @param {string} html
+ * @returns {object}
+ */
+export function scanHtml(html) {
+    const src = String(html ?? '');
+    const headEnd = src.search(/<\/head\s*>/i);
+    const head = headEnd >= 0 ? src.slice(0, headEnd) : src;
+
+    const jsonLdTypes = [];
+    for (const m of src.matchAll(/<script\b[^>]*type\s*=\s*["']?application\/ld\+json["']?[^>]*>([\s\S]*?)<\/script>/gi)) {
+        try {
+            const j = JSON.parse(m[1]);
+            for (const x of [j, ...(Array.isArray(j) ? j : []), ...(Array.isArray(j?.['@graph']) ? j['@graph'] : [])]) {
+                const t = x?.['@type'];
+                if (t) jsonLdTypes.push(...(Array.isArray(t) ? t : [t]).map(String));
+            }
+        } catch { jsonLdTypes.push('(invalid)'); }
+    }
+
+    const clean = src
+        .replace(/<!--[\s\S]*?-->/g, ' ')
+        .replace(/<(script|style|template|noscript|svg)\b[\s\S]*?<\/\1\s*>/gi, ' ');
+
+    const metas = [...head.matchAll(/<meta\b[^>]*>/gi)].map(m => attrs(m[0]));
+    const meta = (key, val) => metas.find(a => (a[key] || '').toLowerCase() === val)?.content;
+    const links = [...head.matchAll(/<link\b[^>]*>/gi)].map(m => attrs(m[0]));
+
+    const bodyStart = clean.search(/<body\b/i);
+    const body = bodyStart >= 0 ? clean.slice(bodyStart) : clean;
+
+    const headings = [...body.matchAll(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1\s*>/gi)].map(m => ({level: Number(m[1]), text: squash(m[2])}));
+    const images = [...body.matchAll(/<img\b[^>]*>/gi)].map(m => {
+        const a = attrs(m[0]);
+        return {src: a.src || a['data-src'] || '', alt: 'alt' in a ? a.alt : null, role: a.role || ''};
+    });
+    const anchors = [...body.matchAll(/<a\b([^>]*)>([\s\S]*?)<\/a\s*>/gi)].map(m => {
+        const a = attrs(`<a ${m[1]}>`);
+        return {href: a.href || '', text: squash(m[2]), rel: a.rel || '', title: a.title || ''};
+    });
+    const text = squash(body);
+    const firstPara = squash(body.match(/<p\b[^>]*>([\s\S]*?)<\/p\s*>/i)?.[1] || '');
+
+    return {
+        title: squash(head.match(/<title\b[^>]*>([\s\S]*?)<\/title\s*>/i)?.[1] || ''),
+        description: meta('name', 'description') ?? null,
+        robots: meta('name', 'robots') || '',
+        viewport: Boolean(meta('name', 'viewport')),
+        canonical: links.find(l => (l.rel || '').toLowerCase() === 'canonical')?.href || '',
+        lang: attrs(src.match(/<html\b[^>]*>/i)?.[0] || '<html>').lang || '',
+        og: {
+            title: meta('property', 'og:title') || '',
+            description: meta('property', 'og:description') || '',
+            image: meta('property', 'og:image') || '',
+            type: meta('property', 'og:type') || ''
+        },
+        twitter: {card: meta('name', 'twitter:card') || '', image: meta('name', 'twitter:image') || ''},
+        headings,
+        images,
+        links: anchors,
+        words: text ? text.split(/\s+/).filter(w => /[\p{L}\p{N}]/u.test(w)).length : 0,
+        text: text.slice(0, 20000),
+        firstPara: firstPara.slice(0, 1000),
+        jsonLdTypes: [...new Set(jsonLdTypes)]
+    };
+}
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const has = (hay, needle) => Boolean(needle) && String(hay || '').toLowerCase().includes(needle);
+const slugWords = (s) => String(s || '').toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+/**
+ * Judge one page.
+ *
+ * @param {object} f - scanHtml() facts
+ * @param {object} [opts]
+ * @param {string} [opts.urlPath]
+ * @param {string} [opts.focus] - the focus keyphrase, if one is set
+ * @param {object} [opts.limits] - LIMITS overrides
+ * @param {string} [opts.origin] - the site's own origin, to tell internal links
+ * @returns {{score: number, failing: number, checks: object[]}}
+ */
+export function analyse(f, {urlPath = '/', focus = '', limits = {}, origin = ''} = {}) {
+    const L = {...LIMITS, ...limits};
+    const checks = [];
+    const add = (id, group, status, title, detail, fix = '') => checks.push({id, group, status, title, detail, fix});
+    const noindex = /noindex/i.test(f.robots);
+
+    // --- Search result ---
+    const tl = f.title.length;
+    if (!tl) add('title', 'Search result', 'fail', 'Title', 'The page has no title.', 'Give it one: it is the blue link people click in the results.');
+    else if (tl < L.titleMin) add('title', 'Search result', 'warn', 'Title', `${tl} characters - short. Search engines may write their own.`, `Aim for ${L.titleMin}-${L.titleMax} characters that say what the page is about.`);
+    else if (tl > L.titleMax) add('title', 'Search result', 'warn', 'Title', `${tl} characters - it will be cut off after about ${L.titleMax}.`, 'Put the words that matter first, or shorten it.');
+    else add('title', 'Search result', 'pass', 'Title', `${tl} characters.`);
+
+    const d = f.description;
+    const dl = (d || '').length;
+    if (!dl) add('description', 'Search result', 'fail', 'Description', 'No description: search engines pick any sentence from the page.', 'Write one or two sentences that make someone want to click.');
+    else if (dl < L.descMin) add('description', 'Search result', 'warn', 'Description', `${dl} characters - short.`, `Aim for ${L.descMin}-${L.descMax} characters.`);
+    else if (dl > L.descMax) add('description', 'Search result', 'warn', 'Description', `${dl} characters - it will be cut off after about ${L.descMax}.`, 'Shorten it, keeping the point in the first half.');
+    else add('description', 'Search result', 'pass', 'Description', `${dl} characters.`);
+
+    const slug = urlPath.split('/').filter(Boolean).pop() || '';
+    if (urlPath !== '/' && (slug.length > 60 || /[A-Z_ %]/.test(slug) || /\d{5,}/.test(slug))) {
+        add('url', 'Search result', 'warn', 'Address', `"${slug}" is long or hard to read.`, 'Short, lower-case words joined by hyphens read best - rename the page (a redirect is added for you).');
+    } else {
+        add('url', 'Search result', 'pass', 'Address', urlPath === '/' ? 'The home page.' : `"${slug}" reads well.`);
+    }
+
+    // --- Content ---
+    const h1s = f.headings.filter(h => h.level === 1);
+    if (!h1s.length) add('h1', 'Content', 'fail', 'Main heading', 'There is no H1 heading.', 'Start the page with one main heading (# in Markdown) saying what it is about.');
+    else if (h1s.length > 1) add('h1', 'Content', 'warn', 'Main heading', `${h1s.length} H1 headings: "${h1s.slice(0, 3).map(h => h.text).join('", "')}".`, 'Keep one H1; make the others H2.');
+    else if (!h1s[0].text) add('h1', 'Content', 'warn', 'Main heading', 'The H1 heading is empty.', 'Give it words.');
+    else add('h1', 'Content', 'pass', 'Main heading', `"${h1s[0].text.slice(0, 80)}".`);
+
+    const skips = [];
+    for (let i = 1; i < f.headings.length; i++) {
+        if (f.headings[i].level > f.headings[i - 1].level + 1) skips.push(`H${f.headings[i - 1].level} → H${f.headings[i].level}`);
+    }
+    if (skips.length) add('headings', 'Content', 'warn', 'Heading order', `Levels are skipped: ${[...new Set(skips)].slice(0, 3).join(', ')}.`, 'Go down one level at a time (H2, then H3) - screen readers and search engines read them as an outline.');
+    else if (f.headings.length > 1) add('headings', 'Content', 'pass', 'Heading order', `${plural(f.headings.length, 'heading')}, in order.`);
+
+    if (f.words < Math.round(L.minWords / 3)) add('words', 'Content', 'warn', 'Length', `${plural(f.words, 'word')}. Very little for a search engine to go on.`, `Pages that rank usually have ${L.minWords}+ words - unless the page is a form or a contact page.`);
+    else if (f.words < L.minWords) add('words', 'Content', 'info', 'Length', `${plural(f.words, 'word')}.`, `Pages that rank usually have ${L.minWords}+ words.`);
+    else add('words', 'Content', 'pass', 'Length', `${f.words.toLocaleString('en-GB')} words.`);
+
+    const content = f.images.filter(i => i.role !== 'presentation');
+    const noAlt = content.filter(i => i.alt === null);
+    if (noAlt.length) add('alt', 'Content', 'fail', 'Image descriptions', `${plural(noAlt.length, 'image')} of ${content.length} ${noAlt.length === 1 ? 'has' : 'have'} no alt text.`, 'Describe each image in a few words (empty alt="" only for decoration). It is how search and screen readers see them.');
+    else if (content.length) add('alt', 'Content', 'pass', 'Image descriptions', `All ${plural(content.length, 'image')} described.`);
+
+    const internal = f.links.filter(l => isInternal(l.href, origin));
+    if (!internal.length && f.links.length < 50) add('links', 'Content', 'warn', 'Links to your other pages', 'None in the page itself.', 'Link to related pages: it helps visitors, and search engines find pages through links.');
+    else add('links', 'Content', 'pass', 'Links to your other pages', `${plural(internal.length, 'link')}.`);
+
+    // --- Focus keyphrase ---
+    const k = String(focus || '').trim().toLowerCase();
+    if (k) {
+        const where = [
+            ['title', has(f.title, k)],
+            ['description', has(d, k)],
+            ['main heading', h1s.some(h => has(h.text, k))],
+            ['address', slugWords(urlPath).includes(slugWords(k))],
+            ['first paragraph', has(f.firstPara, k)]
+        ];
+        const missing = where.filter(([, ok]) => !ok).map(([w]) => w);
+        const count = countPhrase(f.text, k);
+        const density = f.words ? (count * k.split(/\s+/).length * 100) / f.words : 0;
+        if (missing.length >= 3) add('focus', 'Keyphrase', 'fail', `"${focus}"`, `Missing from the ${missing.join(', ')}.`, 'Use the phrase people search for where they look first: the title, the heading and the opening.');
+        else if (missing.length) add('focus', 'Keyphrase', 'warn', `"${focus}"`, `Missing from the ${missing.join(', ')}.`, 'Work it in naturally - never at the cost of reading well.');
+        else add('focus', 'Keyphrase', 'pass', `"${focus}"`, 'In the title, description, heading, address and opening.');
+        if (f.words < 100) { /* too short for a share of the words to mean anything */ }
+        else if (density > 3) add('density', 'Keyphrase', 'warn', 'Repetition', `The phrase is ${density.toFixed(1)}% of the words (${plural(count, 'time')}).`, 'Over about 3% reads as stuffing - use other words for the same thing.');
+        else if (count) add('density', 'Keyphrase', 'pass', 'Repetition', `Used ${plural(count, 'time')} (${density.toFixed(1)}%).`);
+    } else {
+        add('focus', 'Keyphrase', 'info', 'Focus keyphrase', 'None set.', 'Say which search this page should be found for, and the checks will look for it.');
+    }
+
+    // --- Sharing and technical ---
+    if (noindex) add('index', 'Technical', 'info', 'Search engines', 'Hidden from search engines (noindex).', 'On purpose for thank-you pages and the like; otherwise switch it off.');
+    else add('index', 'Technical', 'pass', 'Search engines', 'May be indexed.');
+    if (!f.canonical) add('canonical', 'Technical', 'warn', 'Canonical address', 'No canonical link.', 'Set the site address in Settings so every page names its one true address.');
+    else if (!f.canonical.replace(/\/$/, '').endsWith(urlPath === '/' ? '' : urlPath)) add('canonical', 'Technical', 'info', 'Canonical address', `Points elsewhere: ${f.canonical}.`, 'Right when this page is a copy of that one; otherwise it hides this page.');
+    else add('canonical', 'Technical', 'pass', 'Canonical address', f.canonical);
+    if (!f.og.image) add('share-image', 'Sharing', 'warn', 'Share image', 'No image when the page is shared.', 'Choose an image (1200 × 630 is ideal), or set a default one for the site.');
+    else add('share-image', 'Sharing', 'pass', 'Share image', f.og.image);
+    if (f.jsonLdTypes.includes('(invalid)')) add('schema', 'Technical', 'fail', 'Structured data', 'A JSON-LD block is not valid JSON.', 'Fix or remove it - search engines ignore the lot.');
+    else if (f.jsonLdTypes.length) add('schema', 'Technical', 'pass', 'Structured data', f.jsonLdTypes.join(', '));
+    else add('schema', 'Technical', 'info', 'Structured data', 'None.', 'Structured data lets search engines show rich results.');
+    if (!f.lang) add('lang', 'Technical', 'warn', 'Language', 'The page does not say what language it is in.', 'The site template sets <html lang="…">.');
+
+    return {...score(checks), checks};
+}
+
+function isInternal(href, origin) {
+    const h = String(href || '').trim();
+    if (!h || h.startsWith('#') || /^(mailto|tel|javascript|data):/i.test(h)) return false;
+    if (h.startsWith('/') && !h.startsWith('//')) return true;
+    if (!origin) return false;
+    try { return new URL(h).origin === new URL(origin).origin; } catch { return false; }
+}
+
+function countPhrase(text, phrase) {
+    if (!phrase) return 0;
+    const esc = phrase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
+    return (String(text).match(new RegExp(`(^|[^\\p{L}\\p{N}])${esc}(?=$|[^\\p{L}\\p{N}])`, 'giu')) || []).length;
+}
+
+/** Score and failing count of a list of checks. */
+export function score(checks) {
+    const counted = checks.filter(c => c.status !== 'info');
+    const got = counted.reduce((n, c) => n + (c.status === 'pass' ? 1 : c.status === 'warn' ? 0.5 : 0), 0);
+    return {
+        score: counted.length ? Math.round((got / counted.length) * 100) : 100,
+        failing: checks.filter(c => c.status === 'fail').length,
+        warnings: checks.filter(c => c.status === 'warn').length
+    };
+}
+
+/**
+ * Problems only visible across pages: the same title or description on more
+ * than one. `results` are audit rows `{urlPath, title, description, noindex}`.
+ *
+ * @returns {{duplicateTitles: Array<{text, paths}>, duplicateDescriptions: Array<{text, paths}>}}
+ */
+export function siteIssues(results) {
+    const dupes = (key) => {
+        const by = new Map();
+        for (const r of results) {
+            const v = String(r[key] || '').trim().toLowerCase();
+            if (!v || r.noindex || r.error) continue;
+            if (!by.has(v)) by.set(v, {text: r[key], paths: []});
+            by.get(v).paths.push(r.urlPath);
+        }
+        return [...by.values()].filter(x => x.paths.length > 1).sort((a, b) => b.paths.length - a.paths.length);
+    };
+    return {duplicateTitles: dupes('title'), duplicateDescriptions: dupes('description')};
+}
+
+/**
+ * A search result as Google would show it, cut where it cuts (roughly: it
+ * measures pixels; characters are close enough to show the problem).
+ */
+export function snippet({title = '', description = '', url = '', limits = {}} = {}) {
+    const L = {...LIMITS, ...limits};
+    const cut = (s, n) => (s.length > n ? `${s.slice(0, n - 1).replace(/\s+\S*$/, '')} …` : s);
+    let crumbs = url;
+    try {
+        const u = new URL(url);
+        crumbs = [u.hostname, ...u.pathname.split('/').filter(Boolean)].join(' › ');
+    } catch { /* a path */ }
+    return {
+        title: cut(String(title), L.titleMax),
+        description: cut(String(description), L.descMax),
+        crumbs,
+        titleCut: String(title).length > L.titleMax,
+        descriptionCut: String(description).length > L.descMax
+    };
+}