domma-cms 0.55.1 → 0.69.3

package/plugins/blog/lib/layouts.js

@@ -0,0 +1,304 @@
+/**
+ * Blog layouts - the pure half of rendering posts through blocks.
+ *
+ * A post page and every listing card are BLOCKS (content/blocks/*.html), so a
+ * site restyles its blog in the Blocks tool rather than in this plugin:
+ *
+ *   blog-post-<name>  a whole post page       (Classic, Feature, Minimal, Sidebar…)
+ *   blog-card-<name>  one post in a listing   (Cards, List, Compact…)
+ *
+ * Any block a site adds with one of those prefixes becomes a further choice -
+ * nothing here needs to know about it. Nothing in this file touches the disk,
+ * so all of it is testable on its own; lib/render.js does the I/O.
+ *
+ * @module blog/lib/layouts
+ */
+
+/** The post layouts the plugin ships. Each is a block of the same name. */
+export const POST_LAYOUTS = [
+    {id: 'blog-post-classic', label: 'Classic', description: 'Title, image, then the story in one centred column.'},
+    {id: 'blog-post-feature', label: 'Feature', description: 'A full-width hero image with the title over it - for the big pieces.'},
+    {id: 'blog-post-minimal', label: 'Minimal', description: 'Just the words: a narrow reading column, no image.'},
+    {id: 'blog-post-sidebar', label: 'Sidebar', description: 'The story beside a sticky contents list, details and share links.'}
+];
+
+/**
+ * The listing displays the plugin ships. A display is a card block plus how the
+ * cards are arranged; Magazine reuses the Cards block and makes the first post
+ * the lead.
+ */
+export const LIST_DISPLAYS = [
+    {id: 'cards',    block: 'blog-card',         arrange: 'grid',  label: 'Cards',    description: 'A grid of picture cards.'},
+    {id: 'list',     block: 'blog-card-row',     arrange: 'stack', label: 'List',     description: 'One post per row, picture beside the text.'},
+    {id: 'magazine', block: 'blog-card',         arrange: 'grid',  label: 'Magazine', description: 'The newest post large across the top, the rest as cards.', lead: true},
+    {id: 'compact',  block: 'blog-card-compact', arrange: 'stack', label: 'Compact',  description: 'Titles and dates only - an archive at a glance.'}
+];
+
+export const DEFAULT_POST_LAYOUT = 'blog-post-classic';
+export const DEFAULT_DISPLAY = 'cards';
+
+const BUILTIN_CARD_BLOCKS = new Set(LIST_DISPLAYS.map(d => d.block));
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/** 'blog-post-long-read' -> 'Long read' */
+function labelFrom(suffix) {
+    const s = suffix.replace(/-/g, ' ');
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * Every post layout on offer: the shipped ones, then any other `blog-post-*`
+ * block the site has. A shipped layout whose block was deleted still counts -
+ * the plugin carries its own copy.
+ *
+ * @param   {string[]} blockNames - names of the blocks on this site
+ * @returns {{id: string, label: string, description: string, custom: boolean}[]}
+ */
+export function postLayouts(blockNames = []) {
+    const shipped = new Set(POST_LAYOUTS.map(l => l.id));
+    const extra = blockNames
+        .filter(n => NAME_RE.test(n) && n.startsWith('blog-post-') && !shipped.has(n))
+        .sort()
+        .map(n => ({id: n, label: labelFrom(n.slice('blog-post-'.length)), description: 'Your own layout, from the Blocks tool.', custom: true}));
+    return [...POST_LAYOUTS.map(l => ({...l, custom: false})), ...extra];
+}
+
+/**
+ * Every listing display on offer: the shipped four, then one per extra
+ * `blog-card-*` block, arranged as a grid.
+ *
+ * @param   {string[]} blockNames
+ * @returns {{id: string, block: string, arrange: string, label: string, description: string, lead?: boolean, custom: boolean}[]}
+ */
+export function listDisplays(blockNames = []) {
+    const extra = blockNames
+        .filter(n => NAME_RE.test(n) && n.startsWith('blog-card-') && !BUILTIN_CARD_BLOCKS.has(n))
+        .sort()
+        .map(n => ({id: n, block: n, arrange: 'grid', label: labelFrom(n.slice('blog-card-'.length)), description: 'Your own card, from the Blocks tool.', custom: true}));
+    return [...LIST_DISPLAYS.map(d => ({...d, custom: false})), ...extra];
+}
+
+/** The layout a post renders with: its own choice if still on offer, else the site default. */
+export function pickPostLayout(post, settings, layouts) {
+    const ids = new Set(layouts.map(l => l.id));
+    if (post?.template && ids.has(post.template)) return post.template;
+    if (settings?.postLayout && ids.has(settings.postLayout)) return settings.postLayout;
+    return DEFAULT_POST_LAYOUT;
+}
+
+/** The display a listing renders with: a valid request wins, then the setting, then Cards. */
+export function pickDisplay(requested, settings, displays) {
+    const byId = new Map(displays.map(d => [d.id, d]));
+    return byId.get(requested) ?? byId.get(settings?.listDisplay) ?? byId.get(DEFAULT_DISPLAY);
+}
+
+// ---------------------------------------------------------------------------
+// Settings
+// ---------------------------------------------------------------------------
+
+/** The display settings and their defaults (the rest live in config.js). */
+export const DISPLAY_DEFAULTS = {
+    postLayout: DEFAULT_POST_LAYOUT,
+    listDisplay: DEFAULT_DISPLAY,
+    displaySwitcher: true,
+    interactive: true,
+    relatedCount: 3
+};
+
+/**
+ * Whitelist the display settings from a request body. Only keys present are
+ * returned, so a PUT carrying one of them leaves the others as stored.
+ *
+ * @param   {object} body
+ * @returns {object}
+ */
+export function pickDisplaySettings(body = {}) {
+    const out = {};
+    if (typeof body.postLayout === 'string' && /^blog-post-[a-z0-9-]+$/.test(body.postLayout)) out.postLayout = body.postLayout;
+    if (typeof body.listDisplay === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(body.listDisplay)) out.listDisplay = body.listDisplay;
+    if (body.displaySwitcher !== undefined) out.displaySwitcher = Boolean(body.displaySwitcher);
+    if (body.interactive !== undefined) out.interactive = Boolean(body.interactive);
+    if (body.relatedCount !== undefined) {
+        const n = Number(body.relatedCount);
+        out.relatedCount = Number.isFinite(n) ? Math.max(0, Math.min(6, Math.round(n))) : DISPLAY_DEFAULTS.relatedCount;
+    }
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// Interpolation
+// ---------------------------------------------------------------------------
+
+export function escapeHtml(str) {
+    return String(str ?? '')
+        .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+const DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+/**
+ * Moment-style date formatting, the same tokens block templates use elsewhere
+ * (`{{publishedAt:D MMM YYYY}}`). UTC, so a page renders the same wherever the
+ * server is.
+ *
+ * @returns {string|null} null when the value is not a date
+ */
+export function formatDate(value, fmt) {
+    if (!value) return null;
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime())) return null;
+    const pad = (n) => String(n).padStart(2, '0');
+    const t = {
+        YYYY: () => d.getUTCFullYear(), YY: () => pad(d.getUTCFullYear() % 100),
+        MMMM: () => MONTHS[d.getUTCMonth()], MMM: () => MONTHS[d.getUTCMonth()].slice(0, 3),
+        MM: () => pad(d.getUTCMonth() + 1), M: () => d.getUTCMonth() + 1,
+        DD: () => pad(d.getUTCDate()), D: () => d.getUTCDate(),
+        dddd: () => DAYS[d.getUTCDay()], ddd: () => DAYS[d.getUTCDay()].slice(0, 3),
+        HH: () => pad(d.getUTCHours()), mm: () => pad(d.getUTCMinutes())
+    };
+    return fmt.replace(/YYYY|YY|MMMM|MMM|MM|M|DD|D|dddd|ddd|HH|mm/g, k => String(t[k]()));
+}
+
+/**
+ * Fill a block template. `{{{key}}}` is raw (for the fragments this plugin
+ * builds and escapes itself), `{{key}}` is escaped, `{{key:D MMM YYYY}}`
+ * formats a date. HTML comments go - a block's header documents its
+ * placeholders, and a listing of fifty cards need not repeat that fifty times.
+ *
+ * @param   {string} tpl
+ * @param   {object} vars
+ * @returns {string}
+ */
+export function interpolate(tpl, vars) {
+    return String(tpl ?? '')
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/\{\{\{(\w+)\}\}\}/g, (_, k) => String(vars[k] ?? ''))
+        .replace(/\{\{(\w+)(?::([^{}]+))?\}\}/g, (_, k, fmt) => {
+            const v = vars[k] ?? '';
+            if (fmt) {
+                const f = formatDate(v, fmt);
+                if (f !== null) return escapeHtml(f);
+            }
+            return escapeHtml(v);
+        })
+        .trim();
+}
+
+// ---------------------------------------------------------------------------
+// What a post page and a card are made of
+// ---------------------------------------------------------------------------
+
+/** An image address safe inside `url('…')` and `src="…"`, or ''. */
+export function safeImageUrl(url) {
+    const s = String(url ?? '').trim();
+    return /^(\/|https?:\/\/)[^\s'"()\\<>]+$/.test(s) ? s : '';
+}
+
+/** "4 min read", from the words in the post (markup stripped). */
+export function readingTime(text) {
+    const words = String(text ?? '').replace(/<[^>]*>/g, ' ').split(/\s+/).filter(Boolean).length;
+    return `${Math.max(1, Math.round(words / 200))} min read`;
+}
+
+function slugify(s) {
+    return String(s).toLowerCase().replace(/<[^>]*>/g, '').replace(/&[a-z#0-9]+;/g, '')
+        .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'section';
+}
+
+/**
+ * Give the body's h2/h3 headings ids and build a contents list from them.
+ * Fewer than two headings is not worth a list, and gets none.
+ *
+ * @param   {string} html - the rendered post body
+ * @returns {{html: string, toc: string, count: number}}
+ */
+export function buildToc(html) {
+    const items = [];
+    const used = new Set();
+    const out = String(html ?? '').replace(/<h([23])([^>]*)>([\s\S]*?)<\/h\1>/g, (m, level, attrs, inner) => {
+        let id = /\sid="([^"]+)"/.exec(attrs)?.[1];
+        if (!id) {
+            const base = slugify(inner);
+            id = base;
+            for (let n = 2; used.has(id); n++) id = `${base}-${n}`;
+            attrs = `${attrs} id="${id}"`;
+        }
+        used.add(id);
+        items.push({level: Number(level), id, text: inner.replace(/<[^>]*>/g, '').trim()});
+        return `<h${level}${attrs}>${inner}</h${level}>`;
+    });
+    if (items.length < 2) return {html: out, toc: '', count: items.length};
+    const lis = items.map(i => `<li class="blog-toc-l${i.level}"><a href="#${escapeHtml(i.id)}">${i.text}</a></li>`).join('');
+    return {html: out, toc: `<nav class="blog-toc" aria-label="On this page" data-blog-toc><p class="blog-toc-title">On this page</p><ol>${lis}</ol></nav>`, count: items.length};
+}
+
+/**
+ * Posts related to this one: shared categories count double, shared tags once;
+ * ties go to the newer post.
+ */
+export function relatedPosts(post, all, count = 3) {
+    if (!count) return [];
+    const cats = new Set(post.categories ?? []);
+    const tags = new Set(post.tags ?? []);
+    return all
+        .filter(p => p.id !== post.id)
+        .map(p => ({p, score: (p.categories ?? []).filter(c => cats.has(c)).length * 2 + (p.tags ?? []).filter(t => tags.has(t)).length}))
+        .filter(x => x.score > 0)
+        .sort((a, b) => b.score - a.score || new Date(b.p.publishedAt || 0) - new Date(a.p.publishedAt || 0))
+        .slice(0, count)
+        .map(x => x.p);
+}
+
+/**
+ * The placeholders a card block can use, for one post. Raw (`{{{…}}}`) ones are
+ * built here from escaped parts; everything else is plain text.
+ *
+ * @param {object} post
+ * @param {object} ctx - {base, catMap: id -> {name, slug}, authorName}
+ */
+export function cardVars(post, {base, catMap = {}, authorName = ''}) {
+    const url = `${base}/${encodeURIComponent(post.slug ?? '')}`;
+    const imageUrl = safeImageUrl(post.featuredImage);
+    const cats = (post.categories ?? []).map(id => catMap[id]).filter(Boolean);
+    return {
+        id: post.id,
+        title: post.title ?? '',
+        url,
+        excerpt: post.excerpt ?? '',
+        publishedAt: post.publishedAt ?? '',
+        date: formatDate(post.publishedAt, 'D MMM YYYY') ?? '',
+        authorName,
+        authorUrl: post.authorId ? `${base}/author/${encodeURIComponent(post.authorId)}` : base,
+        readingTime: readingTime(post.content),
+        imageUrl,
+        imageClass: imageUrl ? 'has-image' : 'no-image',
+        image: imageUrl ? `<img src="${escapeHtml(imageUrl)}" alt="" loading="lazy">` : '',
+        category: cats[0]?.name ?? '',
+        categories: cats.map(c => `<a class="blog-chip" href="${base}/category/${encodeURIComponent(c.slug)}" data-blog-cat="${escapeHtml(c.slug)}">${escapeHtml(c.name)}</a>`).join(''),
+        tags: (post.tags ?? []).map(t => `<a class="blog-tag" href="${base}/tag/${encodeURIComponent(t)}" data-blog-tag="${escapeHtml(t)}">#${escapeHtml(t)}</a>`).join('')
+    };
+}
+
+/**
+ * What the browser needs to filter, sort and right-click a card: plain values,
+ * carried in a data attribute - never markup.
+ */
+export function cardMeta(post, {catMap = {}, authorName = ''}) {
+    return {
+        id: post.id,
+        title: post.title ?? '',
+        excerpt: post.excerpt ?? '',
+        date: post.publishedAt ?? '',
+        cats: (post.categories ?? []).map(id => catMap[id]).filter(Boolean).map(c => ({slug: c.slug, name: c.name})),
+        tags: post.tags ?? [],
+        author: {id: post.authorId ?? '', name: authorName},
+        minutes: Number.parseInt(readingTime(post.content), 10)
+    };
+}
+
+/** Newest first, by publishedAt; undated posts last. */
+export function byNewest(a, b) {
+    return new Date(b.publishedAt || 0) - new Date(a.publishedAt || 0);
+}

package/plugins/blog/lib/page.js

@@ -0,0 +1,158 @@
+/**
+ * A post page, rendered through its layout block - shared by the public route
+ * (plugin.public.js) and the admin preview (plugin.js), which passes `layout`
+ * to try one on before saving.
+ *
+ * @module blog/lib/page
+ */
+import {listEntries} from '../../../server/services/collections.js';
+import {parseMarkdown} from '../../../server/services/markdown.js';
+import {getUserById} from '../../../server/services/users.js';
+import {getPluginStates} from '../../../server/services/plugins.js';
+import defaultConfig from '../config.js';
+import {buildToc, byNewest, cardVars, DEFAULT_POST_LAYOUT, DISPLAY_DEFAULTS, escapeHtml, interpolate, pickPostLayout, relatedPosts, safeImageUrl} from './layouts.js';
+import {catalogue, loadBlock, renderCards, styleTag} from './render.js';
+
+export function isVisible(post) {
+    return post.status === 'published' ||
+        (post.status === 'scheduled' && post.publishedAt && new Date(post.publishedAt) <= new Date());
+}
+
+/** Settings as they are NOW - display choices apply without a restart. */
+export function liveSettings(registered) {
+    return {...defaultConfig, ...DISPLAY_DEFAULTS, ...registered, ...(getPluginStates()?.blog?.settings ?? {})};
+}
+
+/** Always returns the actual array of entries, regardless of adapter shape. */
+export async function loadEntries(slug) {
+    const result = await listEntries(slug, {limit: 100000, sort: 'createdAt', order: 'desc'});
+    const arr = Array.isArray(result) ? result : (Array.isArray(result?.entries) ? result.entries : []);
+    return arr.map((entry) => ({id: entry.id, ...(entry.data ?? entry)}));
+}
+
+/** Render a post body through the full Markdown + shortcode pipeline. */
+export async function renderPostBody(content) {
+    if (!content) return {html: '', usedComponents: []};
+    try {
+        // Anonymous: the [menu] shortcode treats the visitor as signed out.
+        const {html, usedComponents} = await parseMarkdown('---\n---\n' + content, {});
+        return {html, usedComponents: usedComponents || []};
+    } catch {
+        return {html: escapeHtml(content), usedComponents: []};
+    }
+}
+
+export async function resolveAuthorName(authorId) {
+    if (!authorId) return 'Unknown';
+    try {
+        const user = await getUserById(authorId);
+        return user?.name || user?.email || 'Unknown';
+    } catch {
+        return 'Unknown';
+    }
+}
+
+/** One lookup per author, however many posts they wrote. */
+export async function authorNamesFor(posts) {
+    const ids = [...new Set(posts.map(p => p.authorId).filter(Boolean))];
+    const names = await Promise.all(ids.map(resolveAuthorName));
+    return new Map(ids.map((id, i) => [id, names[i]]));
+}
+
+/**
+ * A post, rendered through its layout block.
+ *
+ * @param {object}   post
+ * @param {object[]} allPosts - every post, for older/newer and related
+ * @param {object}   s        - liveSettings()
+ * @param {object}   opts     - {base, siteUrl, layout (preview only), preview}
+ * @returns {Promise<{html: string, usedComponents: string[], layout: string}>}
+ */
+export async function renderPostPage(post, allPosts, s, {base, siteUrl = '', layout = null, preview = false}) {
+    const {postLayouts, listDisplays} = await catalogue();
+    const chosen = layout && postLayouts.some(l => l.id === layout) ? layout : pickPostLayout(post, s, postLayouts);
+    const block = await loadBlock(chosen) ?? await loadBlock(DEFAULT_POST_LAYOUT);
+
+    const categories = await loadEntries('blog-categories');
+    const catMap = Object.fromEntries(categories.map(c => [c.id, {name: c.name, slug: c.slug}]));
+    const authorName = await resolveAuthorName(post.authorId);
+    const vars = cardVars(post, {base, catMap, authorName});
+
+    const {html: bodyHtml, usedComponents} = await renderPostBody(post.content);
+    const {html: content, toc} = buildToc(bodyHtml);
+
+    // Older and newer, among what a reader can actually see.
+    const visible = allPosts.filter(isVisible).sort(byNewest);
+    const at = visible.findIndex(p => p.id === post.id);
+    const newer = at > 0 ? visible[at - 1] : null;
+    const older = at >= 0 && at < visible.length - 1 ? visible[at + 1] : null;
+    const pn = (p, cls, label) => p
+        ? `<a class="${cls}" href="${base}/${encodeURIComponent(p.slug)}"><span>${label}</span><strong>${escapeHtml(p.title)}</strong></a>`
+        : '<span></span>';
+    const prevNext = newer || older
+        ? `<nav class="blog-prevnext" aria-label="More posts">${pn(older, 'is-older', '← Older')}${pn(newer, 'is-newer', 'Newer →')}</nav>`
+        : '';
+
+    let related = '';
+    let relatedStyle = '';
+    const rel = relatedPosts(post, visible, Number(s.relatedCount ?? 3));
+    if (rel.length) {
+        const cards = listDisplays.find(d => d.id === 'cards');
+        const {items, style} = await renderCards(rel, cards, {base, catMap, authorNames: await authorNamesFor(rel)});
+        relatedStyle = style;
+        related = `<section class="blog-related"><h2 class="blog-section-title">Keep reading</h2><div class="blog-items blog-items--grid">${items}</div></section>`;
+    }
+
+    const url = `${siteUrl}${base}/${encodeURIComponent(post.slug ?? '')}`;
+    const share = `<div class="blog-share" data-blog-share>
+  <a class="blog-share-btn" href="mailto:?subject=${encodeURIComponent(post.title ?? '')}&amp;body=${encodeURIComponent(url)}">Email</a>
+  <button type="button" class="blog-share-btn" data-blog-copy hidden>Copy link</button>
+  <button type="button" class="blog-share-btn" data-blog-native hidden>Share…</button>
+</div>`;
+
+    const comments = s.commentsEnabled ? await commentsHtml(post) : '';
+
+    const imageUrl = safeImageUrl(post.featuredImage);
+    const html = `${styleTag(chosen, block?.css)}${relatedStyle}
+<div class="blog-post-page" data-block="${escapeHtml(chosen)}" data-blog-post${preview ? ' data-preview' : ''}>
+${interpolate(block?.content ?? '', {
+...vars,
+image: imageUrl ? `<img src="${escapeHtml(imageUrl)}" alt="">` : '',
+content, toc, share, prevNext, related, comments
+})}
+</div>`;
+    return {html, usedComponents, layout: chosen};
+}
+
+async function commentsHtml(post) {
+    let approved = [];
+    try {
+        approved = (await loadEntries('blog-comments'))
+            .filter((c) => c.postId === post.id && c.status === 'approved')
+            .sort((a, b) => new Date(a.createdAt || 0) - new Date(b.createdAt || 0));
+    } catch { /* non-fatal */ }
+
+    const list = approved.map((c) => `<li class="blog-comment">
+  <p class="blog-comment-head"><strong>${escapeHtml(c.authorName)}</strong> <time datetime="${escapeHtml(c.createdAt)}">${escapeHtml(new Date(c.createdAt).toLocaleDateString('en-GB', {day: 'numeric', month: 'long', year: 'numeric'}))}</time></p>
+  <p class="blog-comment-body">${escapeHtml(c.body)}</p>
+</li>`).join('\n');
+
+    return `<section class="blog-comments" id="comments">
+  <h2 class="blog-section-title">Comments <span class="blog-count" data-blog-comment-count>${approved.length}</span></h2>
+  <ol class="blog-comment-list" data-blog-comment-list>${list}</ol>
+  <form class="blog-comment-form" method="POST" action="/api/plugins/blog/comments" data-blog-comment-form>
+<h3>Leave a comment</h3>
+<input type="hidden" name="postId" value="${escapeHtml(post.id)}">
+<div class="blog-comment-row">
+  <label>Name<input type="text" name="authorName" required maxlength="80" class="form-input" autocomplete="name"></label>
+  <label>Email <small>(never shown)</small><input type="email" name="authorEmail" required maxlength="160" class="form-input" autocomplete="email"></label>
+</div>
+<label class="blog-hp" aria-hidden="true">Website<input type="text" name="website" tabindex="-1" autocomplete="off"></label>
+<label>Comment<textarea name="body" required rows="4" maxlength="5000" class="form-input"></textarea></label>
+<div class="blog-comment-actions">
+  <button type="submit" class="btn btn-primary">Post comment</button>
+  <span class="blog-comment-status" role="status" data-blog-comment-status></span>
+</div>
+  </form>
+</section>`;
+}

package/plugins/blog/lib/render.js

@@ -0,0 +1,119 @@
+/**
+ * Blog rendering through blocks - the half of layouts.js that touches the disk.
+ *
+ * A layout's block is read from the site's Blocks (content/blocks/), where it
+ * can be edited, and from this plugin's own blocks/ folder when the site has
+ * no block of that name - so deleting a shipped block in the Blocks tool puts
+ * the original back rather than breaking the blog.
+ *
+ * @module blog/lib/render
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import {fileURLToPath} from 'url';
+import {getBlock, listBlocks, saveBlock} from '../../../server/services/blocks.js';
+import {getPluginStates, savePluginState} from '../../../server/services/plugins.js';
+import {cardMeta, cardVars, escapeHtml, interpolate, LIST_DISPLAYS, listDisplays, POST_LAYOUTS, postLayouts} from './layouts.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SHIPPED_DIR = path.join(__dirname, '..', 'blocks');
+const SHIPPED = [...new Set([...POST_LAYOUTS.map(l => l.id), ...LIST_DISPLAYS.map(d => d.block)])];
+
+async function readShipped(name) {
+    if (!SHIPPED.includes(name)) return null;
+    try {
+        const content = await fs.readFile(path.join(SHIPPED_DIR, `${name}.html`), 'utf8');
+        const css = await fs.readFile(path.join(SHIPPED_DIR, `${name}.css`), 'utf8').catch(() => '');
+        return {content, css};
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Copy the shipped blocks into the site's Blocks, once each. Remembered in
+ * config/plugins.json, so a block the site deletes on purpose stays deleted
+ * (and the blog quietly falls back to the plugin's copy); one that is already
+ * there is never overwritten.
+ *
+ * @returns {Promise<string[]>} the names copied this time
+ */
+export async function seedBlocks() {
+    const done = new Set(getPluginStates()?.blog?.seededBlocks ?? []);
+    const copied = [];
+    for (const name of SHIPPED.filter(n => !done.has(n))) {
+        const shipped = await readShipped(name);
+        if (!shipped) continue;
+        let exists = true;
+        try { await getBlock(name); } catch { exists = false; }
+        if (!exists) {
+            await saveBlock(name, shipped.content, {css: shipped.css, meta: {plugin: 'blog'}});
+            copied.push(name);
+        }
+        done.add(name);
+    }
+    if (copied.length || done.size !== (getPluginStates()?.blog?.seededBlocks ?? []).length) {
+        savePluginState('blog', {seededBlocks: [...done]});
+    }
+    return copied;
+}
+
+/**
+ * A block's template and CSS - the site's copy, else the shipped one.
+ *
+ * @returns {Promise<{content: string, css: string}|null>}
+ */
+export async function loadBlock(name) {
+    try {
+        const b = await getBlock(name);
+        return {content: b.content, css: b.css ?? ''};
+    } catch {
+        return readShipped(name);
+    }
+}
+
+/** The names of every block on the site, plus the shipped ones. */
+async function allBlockNames() {
+    const names = new Set(SHIPPED);
+    try { for (const b of await listBlocks()) names.add(b.name); } catch { /* no blocks dir yet */ }
+    return [...names];
+}
+
+/** Every post layout and listing display on offer on this site. */
+export async function catalogue() {
+    const names = await allBlockNames();
+    return {postLayouts: postLayouts(names), listDisplays: listDisplays(names)};
+}
+
+/**
+ * A block's CSS, scoped to elements carrying its `data-block` - the same
+ * convention every other block on the site uses, so CSS written in the Blocks
+ * tool behaves identically here.
+ */
+export function styleTag(name, css) {
+    if (!css || !css.trim()) return '';
+    const body = String(css).replace(/<\/style/gi, '<\\/style').replace(/\n\s*\n+/g, '\n').trim();
+    return `<style>[data-block="${escapeHtml(name)}"] {\n${body}\n}</style>`;
+}
+
+/**
+ * Render posts as a listing in one display. Each card is wrapped in the
+ * element the browser script filters and right-clicks - `data-entry-id` and a
+ * `data-post` of plain values, never markup.
+ *
+ * @param {object[]} posts
+ * @param {object}   display - one of catalogue().listDisplays
+ * @param {object}   ctx     - {base, catMap, authorNames: Map}
+ * @returns {Promise<{items: string, style: string}>}
+ */
+export async function renderCards(posts, display, ctx) {
+    const block = await loadBlock(display.block) ?? await loadBlock('blog-card');
+    const items = posts.map((post, i) => {
+        const authorName = ctx.authorNames.get(post.authorId) ?? '';
+        const vars = cardVars(post, {base: ctx.base, catMap: ctx.catMap, authorName});
+        const meta = Buffer.from(JSON.stringify(cardMeta(post, {catMap: ctx.catMap, authorName})), 'utf8').toString('base64');
+        const lead = display.lead && i === 0 ? ' is-lead' : '';
+        return `<article class="blog-item${lead}" data-block="${escapeHtml(display.block)}" data-entry-id="${escapeHtml(post.id)}" data-post="${meta}">${interpolate(block?.content ?? '', vars)}</article>`;
+    }).join('\n');
+    return {items, style: styleTag(display.block, block?.css)};
+}