@cogenta/cli 0.4.0 → 0.6.0

package/dist/commands/theme-render.js

@@ -1,10 +1,12 @@
 import { collectDependencies, } from '@cogenta/api';
-import { CogentaError } from '@cogenta/core';
+import { CogentaError, isCogentaError } from '@cogenta/core';
 import { describeMedia, renderSkin } from '@cogenta/render';
-import { buildPath, matchPath, } from '@cogenta/schema';
-import { query as collectionListQuery, escapeAttribute, escapeText, renderPage, serialize, } from '@cogenta/theme-canonical';
-import { alternatesForEntry, renderSeoHead, seoSiteFor } from './seo.js';
+import { buildPath, matchPath, relationsOf, } from '@cogenta/schema';
+import { buildCollectionListQuery as collectionListQuery, createThemeTranslator, entryExcerpt, entryImage, escapeAttribute, renderCommentsSection, serialize, THEME_TOGGLE_SCRIPT, } from '@cogenta/theme-kit';
+import { DEFAULT_LOGO_PATH } from './default-logo.js';
+import { alternatesForEntry, renderSeoHead, seoSiteFor, siteVerificationMetaTags } from './seo.js';
 import { minifyCss } from './theme-css.js';
+import { DEFAULT_THEME_NAME, resolveTheme } from './theme-registry.js';
 /**
  * The theme's own `ContentEntry`/`QueryRequest` (`theme-contract.ts`) are a
  * deliberately separate, minimal public contract — a theme never imports
@@ -63,6 +65,233 @@ async function listAsTheme(gateway, request, context) {
  */
 /** Where `cogenta serve` publishes image variants. Public: a visitor's browser fetches them. */
 export const DEFAULT_IMAGE_ENDPOINT = '/_image';
+/** "Nothing has ever been chosen" — the pre-T01 rendering, exactly. */
+export const EMPTY_SITE_IDENTITY = {
+    logoMediaId: null,
+    logoDarkMediaId: null,
+    faviconMediaId: null,
+    shareImageMediaId: null,
+};
+/**
+ * Resolves the four identity media ids into what a page actually needs.
+ *
+ * One batch through the very same `loadMedia` every other image on the page
+ * goes through — never a second lookup path, and never a URL built from an
+ * id this renderer has not confirmed is a live image: a `kind !== 'image'`
+ * asset (a PDF someone picked in the media browser) resolves to `null` and
+ * the site falls back, rather than emitting a `<link rel="icon">` pointing
+ * at a document.
+ *
+ * **The share-image decision (audit T01, left open as "à trancher").**
+ * `seo.defaultSocialImageUrl` stays the one field the SEO pipeline reads;
+ * `shareImageMediaId` becomes a *source* for it, not a rival — when the
+ * appearance screen names a media, its `/_image` URL is what
+ * `fallbackImageFor` sees, and otherwise the SEO screen's URL is used
+ * unchanged. Two screens, one effective value, and neither field is
+ * silently dead: the appearance one wins because it is the more specific
+ * choice (a picked asset beats a typed URL), and because dropping it would
+ * throw away a setting sites have already saved.
+ */
+async function resolveIdentity(siteName, imageEndpoint, options) {
+    const identity = options.identity === undefined ? EMPTY_SITE_IDENTITY : await options.identity();
+    const ids = [
+        identity.logoMediaId,
+        identity.logoDarkMediaId,
+        identity.faviconMediaId,
+        identity.shareImageMediaId,
+    ].filter((id) => id !== null && id !== '');
+    const assets = new Map();
+    if (ids.length > 0 && options.loadMedia !== undefined) {
+        for (const [id, asset] of await options.loadMedia([...new Set(ids)]))
+            assets.set(id, asset);
+    }
+    const sourceFor = (id) => {
+        if (id === null || id === '')
+            return null;
+        const asset = assets.get(id);
+        if (asset === undefined || asset.kind !== 'image')
+            return null;
+        return describeMedia(asset, {}, { endpoint: imageEndpoint, mediaEndpoint: imageEndpoint });
+    };
+    const favicon = sourceFor(identity.faviconMediaId);
+    const share = sourceFor(identity.shareImageMediaId);
+    return {
+        brand: {
+            name: siteName,
+            logo: sourceFor(identity.logoMediaId),
+            logoDark: sourceFor(identity.logoDarkMediaId),
+            faviconUrl: favicon === null ? null : favicon.src,
+        },
+        faviconHref: favicon === null ? null : favicon.src,
+        shareImageUrl: share === null ? null : share.src,
+    };
+}
+/**
+ * `<link rel="icon">`, and what it falls back to.
+ *
+ * The fallback is **branding-aware**, and that is not a detail: Cogenta's
+ * default icon is Cogenta's own logo, so a site that turned the credit off
+ * (fiche L21 task 8) and then got that logo back in its browser tab would
+ * have its white-labelling undone by the very change that started serving a
+ * favicon at all. A white-labelled site therefore falls back to its own
+ * uploaded replacement logo, and to *no icon tag whatsoever* when it has
+ * none — a browser's own blank default, which is the honest answer, not
+ * somebody else's mark.
+ *
+ * The `type` is only ever declared for the default, which really is the PNG
+ * this package ships; a media-library asset goes through `/_image`, which
+ * answers WebP or PNG depending on what the upload pipeline wrote, so
+ * declaring `image/png` there would be a claim this file cannot make. A
+ * browser sniffs the bytes either way.
+ */
+function faviconLinkTag(chosen, branding, imageEndpoint) {
+    const href = chosen ?? defaultFaviconFor(branding, imageEndpoint);
+    if (href === null)
+        return '';
+    const typeAttr = href === DEFAULT_LOGO_PATH ? ' type="image/png"' : '';
+    return `<link rel="icon"${typeAttr} href="${escapeAttribute(href)}">`;
+}
+function defaultFaviconFor(branding, imageEndpoint) {
+    if (branding.showCogentaBranding)
+        return DEFAULT_LOGO_PATH;
+    if (branding.customLogoMediaId !== null && branding.customLogoMediaId !== '') {
+        return `${imageEndpoint}?id=${encodeURIComponent(branding.customLogoMediaId)}&w=64`;
+    }
+    return null;
+}
+/**
+ * Four of the five built-in themes pull their typefaces from Google Fonts
+ * with a CSS `@import`, which the browser only discovers *after* the
+ * stylesheet has downloaded and parsed — two extra round trips before the
+ * first glyph is requested. `preconnect` collapses the DNS/TLS half of that
+ * wait, and it is emitted unconditionally on purpose: the cost of two unused
+ * hints on a system-font theme is a few dozen bytes, while making it
+ * conditional would mean this file keeping a list of which themes use web
+ * fonts — exactly the per-theme knowledge the chrome extension point exists
+ * to keep out of here.
+ *
+ * `font-display: swap` itself is already declared by every one of those four
+ * `@import` URLs (`&display=swap`), so no font blocks first paint today;
+ * these hints are the remaining half of that fix.
+ */
+/**
+ * The site's own feeds, discoverable (audit T03). A reader pasting the site's
+ * URL into a feed reader finds them through these two tags and nothing else —
+ * the routes existed before this and were invisible.
+ *
+ * Both formats are advertised because readers disagree about which they
+ * prefer, and both are served from the same content, so offering one would
+ * only make the other undiscoverable for no gain.
+ */
+function feedLinkTags(siteName) {
+    const title = escapeAttribute(siteName);
+    return (`<link rel="alternate" type="application/rss+xml" title="${title}" href="/feed.xml">` +
+        `<link rel="alternate" type="application/atom+xml" title="${title}" href="/atom.xml">`);
+}
+function fontPreconnectTags() {
+    return (`<link rel="preconnect" href="https://fonts.googleapis.com">` +
+        `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>`);
+}
+const DEFAULT_BRANDING = { showCogentaBranding: true, customLogoMediaId: null };
+async function brandingFor(get) {
+    if (get === undefined)
+        return DEFAULT_BRANDING;
+    return get();
+}
+/** Resolves the active theme module — `theme-registry.ts`'s own fallback covers an absent or unrecognised name. */
+async function themeFor(get) {
+    const name = get === undefined ? DEFAULT_THEME_NAME : await get();
+    return resolveTheme(name);
+}
+const EMPTY_CHROME_EXTRAS = { tagline: '', social: [], footerNote: '' };
+async function chromeExtrasFor(get, locale) {
+    if (get === undefined)
+        return EMPTY_CHROME_EXTRAS;
+    return get(locale);
+}
+/**
+ * The `location` a menu is assigned to for it to become `ChromeInput.headerAction`
+ * (contract D `theme@1.4`) — a site names its own menu at this location from
+ * the admin's menu screen, exactly the way `header-nav`/`footer-nav` already
+ * work for `headerNav`/`footerNav`.
+ */
+export const HEADER_ACTION_MENU_LOCATION = 'header-action';
+/**
+ * The first link of the menu assigned to `HEADER_ACTION_MENU_LOCATION`, or
+ * `undefined` when no menu is assigned there (or it has no menu router
+ * wired at all) — never a legacy-name fallback, unlike
+ * `fetchMenuLinksForSlot`'s header/footer nav: this location is new in L25,
+ * so there is no pre-existing convention it needs to keep working.
+ */
+async function resolveHeaderAction(locale, menus, context) {
+    if (menus?.menuRouter === undefined)
+        return undefined;
+    const links = await fetchMenuLinksByLocation(HEADER_ACTION_MENU_LOCATION, locale, menus, context);
+    const first = links?.[0];
+    if (first === undefined || first.href === null)
+        return undefined;
+    return { label: first.label, href: first.href };
+}
+/**
+ * The one place every `renderChrome` call resolves the four `theme@1.4`
+ * fields (D2) from — `general.tagline`/`general.socialLinks`/
+ * `general.footerNote` through whichever `chromeExtras` reader the caller
+ * wired (`chromeExtrasForSite`, `@cogenta/cli`'s `serve.ts`), and
+ * `headerAction` from the live menu router right here, since it needs no
+ * database read of its own. Every field is omitted, never emitted as `''`/
+ * `[]`, when it has nothing to say — a theme's own "is this set" check
+ * (`input.tagline !== undefined`, say) stays a plain presence check.
+ */
+async function resolveChromeExtras(getExtras, locale, menus, context) {
+    const [extras, headerAction] = await Promise.all([
+        chromeExtrasFor(getExtras, locale),
+        resolveHeaderAction(locale, menus, context),
+    ]);
+    return {
+        ...(extras.tagline === '' ? {} : { tagline: extras.tagline }),
+        ...(extras.social.length === 0 ? {} : { social: extras.social }),
+        ...(extras.footerNote === '' ? {} : { footerNote: extras.footerNote }),
+        ...(headerAction === undefined ? {} : { headerAction }),
+    };
+}
+/**
+ * The footer's own branding block — Cogenta's real logo and a link back to
+ * the project by default, the site's uploaded replacement once Cogenta's
+ * credit is turned off, or nothing at all once it is off with no
+ * replacement. `imageEndpoint` is the same `/_image` (or override) every
+ * other image on the page already resolves through — no second delivery
+ * path for this one image.
+ */
+function renderFooterBranding(branding, imageEndpoint) {
+    if (branding.showCogentaBranding) {
+        const versionSuffix = branding.cogentaVersion === undefined || branding.cogentaVersion === ''
+            ? ''
+            : ` <span class="cg-site-footer__version">v${escapeHtml(branding.cogentaVersion)}</span>`;
+        return (`<div class="cg-site-footer__branding">` +
+            `<a href="https://github.com/cogenta-cms/cogenta" rel="noopener" target="_blank">` +
+            `<img src="${DEFAULT_LOGO_PATH}" width="32" height="32" alt="Cogenta" ` +
+            `class="cg-site-footer__brand-logo" loading="lazy">${versionSuffix}</a></div>`);
+    }
+    if (branding.customLogoMediaId !== null && branding.customLogoMediaId !== '') {
+        const src = `${imageEndpoint}?id=${encodeURIComponent(branding.customLogoMediaId)}&w=64`;
+        return (`<div class="cg-site-footer__branding">` +
+            `<img src="${escapeAttribute(src)}" width="32" height="32" alt="" ` +
+            `class="cg-site-footer__brand-logo" loading="lazy"></div>`);
+    }
+    return '';
+}
+/** The hardcoded fallback every blueprint's home page uses when no `reading.homePath` setting is stored. */
+const DEFAULT_HOME_PATH = '/home';
+async function homePathFor(options) {
+    if (options.homePath === undefined)
+        return DEFAULT_HOME_PATH;
+    const configured = await options.homePath();
+    return configured === null || configured === '' ? DEFAULT_HOME_PATH : configured;
+}
+/** This stand-in theme's own default header slot — see `ThemeRenderOptions.headerMenuLocation`. */
+export const DEFAULT_HEADER_MENU_LOCATION = 'primary';
+/** This stand-in theme's own default footer slot — see `ThemeRenderOptions.footerMenuLocation`. */
+export const DEFAULT_FOOTER_MENU_LOCATION = 'footer';
 /**
  * Where the served stylesheet lives. Under `/_cogenta/` for the same reason
  * `Base.astro` puts the skin there: it is a namespace no collection route can
@@ -99,22 +328,83 @@ function toVocabularyBlocks(entry, collection) {
         },
     ];
 }
-function entryTitle(entry) {
-    const value = entry.values.title;
-    return typeof value === 'string' && value.trim() !== '' ? value : entry.id;
+function richTextRefs(document) {
+    const media = new Set();
+    const links = [];
+    for (const node of document) {
+        if (node._type === 'media') {
+            media.add(node.id);
+            continue;
+        }
+        // A thematic break (fiche 42 task 2) carries no data beyond its key —
+        // no `markDefs` to walk, unlike a text block.
+        if (node._type === 'hr')
+            continue;
+        for (const definition of node.markDefs) {
+            if (definition._type === 'internalLink') {
+                links.push({ collection: definition.collection, id: definition.id });
+            }
+        }
+    }
+    return { media: [...media], links };
 }
 /**
- * Looks a menu up by name, through the exact same `MenuRouter` `/api/menus/*`
- * is mounted with — an in-process call, `RestRequest` in and `RestResponse`
+ * The `media` nodes and `internalLink` marks a page's rich text carries
+ * (ADR-0013), gathered up front for the same reason `collectionList`'s
+ * entries are: `renderBlock` is pure and synchronous (contract D), so
+ * `ctx.image()` and `link()` cannot await a lookup once rendering starts.
+ *
+ * `@cogenta/api`'s `collectDependencies` does not reach inside a `richText`
+ * value — it only walks a collection's own declared `media`/`relation`
+ * fields — so a media node or an internal link living *inside* prose would
+ * otherwise never be fetched, and `ctx.image()` would throw on a perfectly
+ * valid page. Only `prose` carries a top-level `richText` field in contract
+ * B's vocabulary (`body`); a `faq` answer is also rich text, but nested
+ * inside a repeated item the same way gallery/logo media is, which
+ * `collectDependencies` already treats as a known, separate limitation.
+ */
+function collectRichTextAssets(blocks) {
+    const media = new Set();
+    const links = [];
+    for (const block of blocks) {
+        if (block._type !== 'prose')
+            continue;
+        const refs = richTextRefs(block.body);
+        for (const id of refs.media)
+            media.add(id);
+        links.push(...refs.links);
+    }
+    return { media: [...media], links };
+}
+// A collection is free to call its title field anything (`vitrine`'s
+// `service`, `restaurant`'s `menu_item`, `store`'s `product` and `saas`'s
+// `feature` all use `name`, never `title`) — the same fallback chain
+// `@cogenta/theme-kit`'s own `entryTitle` already follows for a theme's
+// cards and lists, so a page's `<title>`/`<h1>` reads the same name rather
+// than falling back to the entry's raw id.
+const TITLE_FIELDS = ['title', 'name', 'label'];
+export function entryTitle(entry) {
+    for (const field of TITLE_FIELDS) {
+        const value = entry.values[field];
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
+    }
+    return entry.id;
+}
+/**
+ * Looks a menu up through the exact same `MenuRouter` `/api/menus/*` is
+ * mounted with — an in-process call, `RestRequest` in and `RestResponse`
  * out, never a second lookup path or a real HTTP round trip to itself.
+ * Shared by the by-location and by-name lookups below; only the path
+ * differs.
  *
- * `null` for "no menu router wired" and "no menu by that name" alike: both
+ * `null` for "no menu router wired" and "no menu found at all" alike: both
  * mean the slot renders empty, exactly as it always has.
  */
-async function fetchMenuLinks(name, locale, options, context) {
+async function fetchMenuLinksFromPath(path, locale, options, context) {
     if (options.menuRouter === undefined)
         return null;
-    const response = await options.menuRouter.handle({ method: 'GET', path: `/api/menus/by-name/${encodeURIComponent(name)}`, query: { locale } }, context);
+    const response = await options.menuRouter.handle({ method: 'GET', path, query: { locale } }, context);
     if (response.status !== 200)
         return null;
     const body = response.body;
@@ -123,34 +413,164 @@ async function fetchMenuLinks(name, locale, options, context) {
         return null;
     return items.map((item) => ({
         label: item.resolvedLabel ?? item.label,
-        href: item.kind === 'url' ? item.url : item.kind === 'entry' ? (item.resolvedRoute ?? null) : null,
+        // `url` carries its own stored destination; every other resolvable kind
+        // (`entry`, `taxonomy`, `home`) is only ever linked through the
+        // resolver's answer — never a second, ad hoc way to derive a route. A
+        // `submenu-placeholder` has no resolver call at all, so `resolvedRoute`
+        // is `undefined` for it and this falls through to `null`, exactly the
+        // "no link, just a heading" case `renderMenuLinks` keeps.
+        href: item.kind === 'url' ? item.url : (item.resolvedRoute ?? null),
         openInNewTab: item.openInNewTab,
+        kind: item.kind,
+        title: item.title,
     }));
 }
+/** Looks a menu up by its `location` (fiche 09, task 3) — the generic, theme-agnostic resolution. */
+function fetchMenuLinksByLocation(location, locale, options, context) {
+    return fetchMenuLinksFromPath(`/api/menus/by-location/${encodeURIComponent(location)}`, locale, options, context);
+}
+/** Looks a menu up by its machine `name` — the legacy resolution `fetchMenuLinksForSlot` falls back to. */
+function fetchMenuLinksByName(name, locale, options, context) {
+    return fetchMenuLinksFromPath(`/api/menus/by-name/${encodeURIComponent(name)}`, locale, options, context);
+}
+/**
+ * Resolves the menu for one render slot (header or footer): by `location`
+ * first — the only mechanism a future second theme needs, since it is a
+ * property of the *menu*, never a name this file hardcodes — and, only when
+ * nothing is assigned there, by the legacy `name` convention (`main`,
+ * `footer`) this stand-in theme shipped with before locations existed. That
+ * fallback is what lets a site created before task 3 keep its navigation
+ * showing up unchanged: nothing about its data has to move for `/` to keep
+ * rendering the menu it already had.
+ */
+async function fetchMenuLinksForSlot(location, legacyName, locale, options, context) {
+    const byLocation = await fetchMenuLinksByLocation(location, locale, options, context);
+    if (byLocation !== null)
+        return byLocation;
+    return fetchMenuLinksByName(legacyName, locale, options, context);
+}
 /**
- * A flat list of links (task 2's documented MVP): every item of the menu, in
- * the order the store returns them, regardless of `parent`/`depth`. A real
- * sub-menu render is left for later — the hierarchy is already in the data
- * (`parent`, `depth`), so nothing here would need to change to add it, only
- * this function's markup.
+ * The one page frame every public page shares: skip link, `color-scheme`
+ * meta, site header with the primary navigation, the page's own content, the
+ * footer with its own navigation.
  *
- * `null`/empty renders nothing: the caller's slot stays exactly as empty as
- * it was before this was wired, for a site with no menu by that name.
+ * Extracted from `renderEntryPage` (below) so `/search` and `/forms/{name}`
+ * (L20 audit, points 8-9) stop hand-rolling a second, thinner `<html>` shell
+ * that carried the stylesheet link but none of the site's chrome — the two
+ * pages looked unstyled not because the stylesheet failed to load, but
+ * because the markup the stylesheet's selectors target (`.cg-site-header`,
+ * `.cg-site-footer`, the skip link) was never there. `renderEntryPage` itself
+ * is not routed through this helper: its admin bar, comments section and
+ * analytics beacon are specific to a real content entry, and duplicating
+ * `renderPageChrome`'s call there would only move the divergence risk rather
+ * than remove it.
  */
-function renderMenuLinks(links) {
-    if (links === null || links.length === 0)
-        return '';
-    const items = links
-        .map((link) => {
-        const label = escapeText(link.label);
-        if (link.href === null)
-            return `<li><span>${label}</span></li>`;
-        const href = escapeAttribute(link.href);
-        const target = link.openInNewTab ? ' target="_blank" rel="noopener"' : '';
-        return `<li><a href="${href}"${target}>${label}</a></li>`;
-    })
-        .join('');
-    return `<ul class="cg-menu">${items}</ul>`;
+export async function renderPageChrome(options, context) {
+    let headerNav = [];
+    let footerNav = [];
+    if (options.menus?.menuRouter !== undefined) {
+        const [headerMenu, footerMenu] = await Promise.all([
+            fetchMenuLinksForSlot(options.menus.headerMenuLocation ?? DEFAULT_HEADER_MENU_LOCATION, 'main', options.locale, options.menus, context),
+            fetchMenuLinksForSlot(options.menus.footerMenuLocation ?? DEFAULT_FOOTER_MENU_LOCATION, 'footer', options.locale, options.menus, context),
+        ]);
+        headerNav = headerMenu ?? [];
+        footerNav = footerMenu ?? [];
+    }
+    const branding = await brandingFor(options.branding);
+    const brandingHtml = renderFooterBranding(branding, DEFAULT_IMAGE_ENDPOINT);
+    const theme = await themeFor(options.activeTheme);
+    const identity = await resolveIdentity(options.site.name, DEFAULT_IMAGE_ENDPOINT, options);
+    const chromeExtras = await resolveChromeExtras(options.chromeExtras, options.locale, options.menus, context);
+    const chrome = theme.renderChrome({
+        site: options.site,
+        locale: options.locale,
+        // Not locale-prefixed on purpose, matching this route's pre-existing
+        // behaviour — a genuine, pre-existing gap in a multi-locale deployment,
+        // tracked separately rather than folded into this change.
+        homeHref: '/',
+        headerNav,
+        footerNav,
+        brandingHtml,
+        brand: identity.brand,
+        ...chromeExtras,
+    });
+    const verificationTags = siteVerificationMetaTags(options.seo === undefined ? null : await options.seo());
+    return `<!doctype html>
+<html lang="${escapeAttribute(options.locale)}" dir="auto">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<script>${THEME_TOGGLE_SCRIPT}</script>
+${faviconLinkTag(identity.faviconHref, branding, DEFAULT_IMAGE_ENDPOINT)}
+${feedLinkTags(options.site.name)}
+${fontPreconnectTags()}
+${options.headHtml}
+${verificationTags === '' ? '' : `${verificationTags}\n`}${options.styles === null ? '' : `<link rel="stylesheet" href="${STYLESHEET_PATH}">`}
+</head>
+<body>
+<a class="cg-skip-link" href="#cg-main">Skip to content</a>
+${chrome.header}
+${options.bodyHtml}
+${chrome.footer}
+</body>
+</html>
+`;
+}
+/**
+ * The public-site admin bar (fiche 35 task 6) — WordPress's most-used
+ * shortcut, in the three links this codebase can actually back today:
+ * straight into the admin shell, to editing this exact entry, and to
+ * starting a new one in the same collection.
+ *
+ * Plain `<a href>`s and one scoped `<style>` block, nothing else: the
+ * theme's own zero-executable-client-JavaScript policy (`serve.test.ts`,
+ * "no executable client JavaScript anywhere on the page") applies to this
+ * markup exactly as it does to the rest of the page — there is no `onclick`,
+ * no toggle, nothing that needs a script to work.
+ *
+ * Its three labels used to be hardcoded English, and its first one hardcoded
+ * the word "Cogenta" — visible to every signed-in editor of a French, or
+ * white-labelled, site (audit 2026-09-01, 10-coquille-reglages-dashboard.md
+ * T02). Both are now resolved: the name follows the same
+ * `showCogentaBranding` switch the footer credit already follows, and the
+ * labels come from the two-language table below.
+ *
+ * A table rather than `react-i18next` (ADR-0019's library) because this is
+ * pure server-rendered HTML with no React runtime anywhere near it; three
+ * strings do not justify pulling an i18n runtime into the render path. The
+ * language is the page's own — a visitor reading the French edition of a
+ * page gets French chrome, which is also the only locale signal this render
+ * has (an `Actor` carries `id` and `roles`, and no locale).
+ */
+const ADMIN_BAR_LABELS = {
+    en: { edit: 'Edit this page', create: 'New' },
+    fr: { edit: 'Modifier cette page', create: 'Nouveau' },
+};
+function adminBarLabels(locale) {
+    // `fr-CA` and `fr` get the same table entry; anything with no entry gets
+    // English rather than a key or an empty string.
+    const base = locale.split('-')[0]?.toLowerCase() ?? 'en';
+    return ADMIN_BAR_LABELS[base] ?? ADMIN_BAR_LABELS.en;
+}
+function renderAdminBar(collectionName, entryId, options) {
+    const collection = encodeURIComponent(collectionName);
+    const entry = encodeURIComponent(entryId);
+    const labels = adminBarLabels(options.locale);
+    // A white-labelled site names itself, never the CMS behind it — the same
+    // rule `renderFooterBranding` already applies to the credit below.
+    const adminName = options.showCogentaBranding ? 'Cogenta' : options.siteName;
+    const home = escapeHtml(adminName);
+    return `<div class="cg-admin-bar" role="navigation" aria-label="${escapeAttribute(adminName)}">
+<style>
+.cg-admin-bar{display:flex;gap:1rem;align-items:center;padding:0.4rem 1rem;background:#1a1a1a;color:#fff;font:500 0.8125rem/1.4 system-ui,sans-serif;position:sticky;top:0;z-index:1000}
+.cg-admin-bar a{color:#fff;text-decoration:none;opacity:0.85}
+.cg-admin-bar a:hover,.cg-admin-bar a:focus-visible{opacity:1;text-decoration:underline}
+</style>
+<a href="/admin">${home}</a>
+<a href="/admin/collections/${collection}/${entry}">${escapeHtml(labels.edit)}</a>
+<a href="/admin/collections/${collection}/new">${escapeHtml(labels.create)}</a>
+</div>`;
 }
 async function fetchOne(gateway, request, context) {
     const page = await gateway.list({ ...request, limit: 1 }, context);
@@ -163,14 +583,15 @@ async function fetchOne(gateway, request, context) {
  * this rather than each re-deriving the same filter from `match.params`.
  *
  * `/` itself matches no collection's route (every `page` pattern is
- * `/:slug`, which needs a real segment) — every `create-cogenta` blueprint
- * seeds its home page at the real, consistent slug `home`, so `/` retries
- * once as `/home` rather than 404ing on the one URL a real visitor always
- * tries first. Not a magic redirect: a site with no page at that slug still
- * 404s honestly, exactly like every other unmatched path.
+ * `/:slug`, which needs a real segment), so `/` retries once as
+ * `homePathFor(options)` — the `reading.homePath` site setting when one is
+ * stored (fiche 23 task 4), `/home` otherwise, the slug every
+ * `create-cogenta` blueprint seeds its home page at. Not a magic redirect: a
+ * site with no page at that path still 404s honestly, exactly like every
+ * other unmatched path.
  */
-async function resolveEntry(pathname, options, context) {
-    const effectivePath = pathname === '/' ? '/home' : pathname;
+export async function resolveEntry(pathname, options, context) {
+    const effectivePath = pathname === '/' ? await homePathFor(options) : pathname;
     const match = matchPath(options.collections, effectivePath, {
         locales: options.site.locales,
         defaultLocale: options.site.defaultLocale,
@@ -246,6 +667,78 @@ export async function renderDraftPage(draft, options, context) {
     const pathname = buildPath(collection, Object.fromEntries(Object.entries(entry.values).filter((pair) => typeof pair[1] === 'string')), entry.locale ?? undefined);
     return renderEntryPage(pathname, collection, entry, options, context);
 }
+/** ~200 words/minute, rounded up — `PageContent.entry.readingMinutes` (contract D `theme@1.4`). `0` (no text at all) is not a reading time, so it is left unset instead. */
+function richTextWordCount(document) {
+    let words = 0;
+    for (const node of document) {
+        if (node._type !== 'block')
+            continue;
+        const text = node.children.map((span) => span.text).join(' ');
+        words += text.split(/\s+/u).filter((word) => word.length > 0).length;
+    }
+    return words;
+}
+/**
+ * Every taxonomy term this entry is classified under, resolved to a label
+ * and a route through `options.resolveTerm` — one taxonomy field per
+ * `relationsOf(collection)` entry of `kind: 'taxonomy'`, a to-many field's
+ * value being an array of ids and a to-one field's a single id.
+ *
+ * `undefined` when `options.resolveTerm` was never wired — the pre-1.4
+ * behaviour — never a half-resolved list with some terms silently dropped.
+ */
+async function entryTerms(entry, collection, resolveTerm) {
+    if (resolveTerm === undefined)
+        return undefined;
+    const taxonomyFields = relationsOf(collection).filter((relation) => relation.kind === 'taxonomy');
+    if (taxonomyFields.length === 0)
+        return undefined;
+    const terms = [];
+    for (const field of taxonomyFields) {
+        const raw = entry.values[field.field];
+        const ids = Array.isArray(raw) ? raw : typeof raw === 'string' && raw !== '' ? [raw] : [];
+        for (const id of ids) {
+            if (typeof id !== 'string' || id === '')
+                continue;
+            const resolved = await resolveTerm(field.to, id);
+            if (resolved === null)
+                continue;
+            terms.push({ taxonomy: field.to, label: resolved.label, href: resolved.route });
+        }
+    }
+    return terms.length === 0 ? undefined : terms;
+}
+/**
+ * `PageContent.entry` (contract D `theme@1.4`) — every field a theme's
+ * `renderEntryHeader` needs, beyond the blocks a page already carries.
+ * `themeEntry` is the already-flattened theme-shaped entry (`toThemeEntry`),
+ * which is what `entryImage`/`entryExcerpt` read; `entry`/`collection` are
+ * the raw schema shapes, which is what system fields and taxonomy field
+ * declarations live on.
+ */
+async function buildEntryMeta(entry, collection, themeEntry, themeContext, options) {
+    const author = options.authorFor === undefined || entry.createdBy === null
+        ? undefined
+        : ((await options.authorFor(entry.createdBy)) ?? undefined);
+    const richTextField = Object.entries(collection.fields).find(([, field]) => field.kind === 'richText')?.[0];
+    const richTextValue = richTextField === undefined ? undefined : entry.values[richTextField];
+    const words = Array.isArray(richTextValue)
+        ? richTextWordCount(richTextValue)
+        : 0;
+    const image = entryImage(themeEntry, themeContext);
+    const excerpt = entryExcerpt(themeEntry);
+    const terms = await entryTerms(entry, collection, options.resolveTerm);
+    return {
+        collection: collection.name,
+        ...(entry.publishedAt === null ? {} : { publishedAt: entry.publishedAt }),
+        updatedAt: entry.updatedAt,
+        ...(image === undefined ? {} : { image }),
+        ...(excerpt === undefined ? {} : { excerpt }),
+        ...(author === undefined ? {} : { author }),
+        ...(terms === undefined ? {} : { terms }),
+        ...(words === 0 ? {} : { readingMinutes: Math.ceil(words / 200) }),
+    };
+}
 /**
  * The one page renderer. Both `renderRequestedPage` (published) and
  * `renderDraftPage` (unsaved) end here, having only differed in how they got
@@ -274,20 +767,41 @@ async function renderEntryPage(pathname, collection, entry, options, context) {
         }
     }
     const collectionsByName = new Map(options.collections.map((entry) => [entry.name, entry]));
+    // Rich text (ADR-0013) can carry its own `media` nodes and `internalLink`
+    // marks, invisible to `collectDependencies` (see `collectRichTextAssets`).
+    // Every linked entry is fetched through the same permission-checked
+    // `gateway.read` a preview already uses: a target that is trashed, still a
+    // draft, or simply gone comes back `null` and is left out of `knownEntries`
+    // — `link()` below then resolves it to `'#'`, and `renderRichText` turns
+    // that into plain text rather than a dead anchor, never a 404.
+    const richTextAssets = collectRichTextAssets(blocks);
+    for (const target of richTextAssets.links) {
+        if (knownEntries.has(target.id))
+            continue;
+        if (!collectionsByName.has(target.collection))
+            continue;
+        const found = await options.gateway.read(target.collection, target.id, context);
+        if (found === null)
+            continue;
+        knownEntries.set(found.id, found);
+        entryCollections.set(found.id, target.collection);
+    }
     // Which media this page references, from the same walk `/api/content` uses
     // to declare a response's dependencies (`collectDependencies`): declared
     // `media` fields *and* the media inside every block, resolved through the
     // block registry rather than guessed at from the JSON. A `ContentEntry`
     // plus its collection name is exactly a `SerialisedEntry`, which is why
-    // this reuse costs nothing.
+    // this reuse costs nothing. Rich text's own media nodes are merged in
+    // separately, above.
     const mediaAssets = new Map();
     if (options.loadMedia !== undefined) {
         const dependencies = collectDependencies([...knownEntries].map(([id, found]) => ({
             ...found,
             collection: entryCollections.get(id) ?? collection.name,
         })), { collection: (name) => collectionsByName.get(name) });
-        if (dependencies.media.length > 0) {
-            for (const [id, asset] of await options.loadMedia(dependencies.media)) {
+        const mediaIds = new Set([...dependencies.media, ...richTextAssets.media]);
+        if (mediaIds.size > 0) {
+            for (const [id, asset] of await options.loadMedia([...mediaIds])) {
                 mediaAssets.set(id, asset);
             }
         }
@@ -307,13 +821,26 @@ async function renderEntryPage(pathname, collection, entry, options, context) {
             // doesn't build one.
             return '#';
         }
-        return buildPath(targetCollection, Object.fromEntries(Object.entries(found.values).filter((pair) => typeof pair[1] === 'string')), found.locale ?? undefined);
+        try {
+            return buildPath(targetCollection, Object.fromEntries(Object.entries(found.values).filter((pair) => typeof pair[1] === 'string')), found.locale ?? undefined);
+        }
+        catch (error) {
+            // A route param can be missing on real content — a routed collection's
+            // slug-kind field is not `required`, so a saved-but-incomplete entry
+            // (a draft published without a slug, for instance) is reachable through
+            // a `collectionList` or a rich-text link long before anyone fixes it.
+            // One unresolvable target must not fail the whole page: the same "the
+            // honest answer is unresolvable" rule above applies here too.
+            if (isCogentaError(error) && error.code === 'CONTENT_ROUTE_INVALID')
+                return '#';
+            throw error;
+        }
     };
     const themeContext = {
         site: options.site,
         locale: entry.locale,
         url: new URL(pathname, options.site.url),
-        t: (key) => key,
+        t: createThemeTranslator(entry.locale),
         // The real `srcset`, from `@cogenta/render`'s own `describeMedia` (L10
         // task 5). Pure and synchronous, as contract D requires: the asset was
         // loaded before this render started, and this only builds URLs against
@@ -363,15 +890,66 @@ async function renderEntryPage(pathname, collection, entry, options, context) {
             list: (request) => listAsTheme(options.gateway, request, context),
         },
     };
-    const pageContent = { title: entryTitle(entry), blocks };
-    const node = renderPage(pageContent, themeContext, fetchedEntries);
+    const themeEntry = toThemeEntry(entry, collection.name);
+    const entryMeta = await buildEntryMeta(entry, collection, themeEntry, themeContext, options);
+    const pageContent = { title: entryTitle(entry), blocks, entry: entryMeta };
+    const theme = await themeFor(options.activeTheme);
+    const node = theme.renderPage(pageContent, themeContext, fetchedEntries, options.blocks);
     const bodyHtml = serialize(node);
+    // The comment thread and form (fiche 15 task 6) — a property of the route,
+    // not of the page's own blocks, so it is appended after `<main>` rather
+    // than folded into `renderPage`'s tree (see `ThemeRenderOptions.comments`'s
+    // own comment for why that also keeps the L16 fidelity test true).
+    const commentsOptions = options.comments;
+    let commentsHtml = '';
+    if (commentsOptions !== undefined) {
+        const data = await commentsOptions.forEntry(collection.name, entry.id, entry.locale);
+        // Closed and empty means "this page has no discussion", not "here is a
+        // discussion you may not join": a home page whose collection opted out
+        // of comments (every blueprint's `page` collection, L25) used to end on
+        // a "Comments (0) — closed" section anyway. A closed thread that already
+        // holds approved comments still shows them, read-only.
+        const hasThread = data.open || data.items.length > 0;
+        if (hasThread)
+            commentsHtml = serialize(renderCommentsSection({
+                comments: data.items,
+                open: data.open,
+                action: commentsOptions.action,
+                collection: collection.name,
+                entryId: entry.id,
+                locale: entry.locale,
+                pagePath: pathname,
+                ...(commentsOptions.honeypotField === undefined
+                    ? {}
+                    : { honeypotField: commentsOptions.honeypotField }),
+                renderedAt: Date.now(),
+            }));
+    }
     // The head is `@cogenta/seo`'s, not this file's: title, description,
     // canonical, hreflang, Open Graph, Twitter Card and JSON-LD, all derived
     // from the real entry and the real collection (L10 task 1). Nothing here
     // decides what is indexable — `buildMetaTags` asks `isPublished` itself, so
     // a preview render carries `noindex` without this caller remembering to.
-    const seoSite = seoSiteFor(options.site);
+    //
+    // `seoSettings` (fiche 21 task 3) is fetched once here, read fresh on every
+    // render rather than cached at server startup — see `ThemeRenderOptions.seo`'s
+    // own doc comment. It feeds both the site-wide fields below (`description`,
+    // `twitterSite`) and the per-page title template/fallback image.
+    const storedSeoSettings = options.seo === undefined ? null : await options.seo();
+    // The site's own identity (audit T01). Resolved here rather than beside
+    // the chrome below because the share image it carries has to reach the SEO
+    // pipeline: `shareImageMediaId` is a *source* for
+    // `seo.defaultSocialImageUrl`, not a second social-image mechanism — see
+    // `resolveIdentity`.
+    const identity = await resolveIdentity(options.site.name, imageEndpoint, options);
+    // Resolved here, above both its consumers: the admin bar's own name follows
+    // the same white-label switch as the footer credit, and the favicon's
+    // fallback follows it too (see `faviconLinkTag`).
+    const branding = await brandingFor(options.branding);
+    const seoSettings = identity.shareImageUrl === null || storedSeoSettings === null
+        ? storedSeoSettings
+        : { ...storedSeoSettings, defaultSocialImageUrl: identity.shareImageUrl };
+    const seoSite = seoSiteFor(options.site, seoSettings);
     const resource = { collection, entry };
     const alternates = await alternatesForEntry(seoSite, collection, entry, options.gateway, context, options.site.locales);
     // `og:image` and JSON-LD's `image` come from the same assets the page just
@@ -393,24 +971,60 @@ async function renderEntryPage(pathname, collection, entry, options, context) {
     };
     // `head` already carries a real `<title>` (`renderSeoHead`, above) — no
     // second one is written into the template below.
-    const head = renderSeoHead(seoSite, resource, {
-        ...(alternates.length === 0 ? {} : { alternates }),
-        ...(mediaAssets.size === 0 ? {} : { media: seoMedia }),
-    });
-    const siteName = escapeAttribute(options.site.name);
-    // The navigation menus (audit follow-up to L13's menu system): `main` in
-    // the header, `footer` in the footer — see `ThemeRenderOptions.menuRouter`
-    // for the convention and why it lives here rather than in contract A/D.
-    // Both are `null`, rendering nothing, on a site with no menu router wired
-    // or no menu by that name — the same empty slots as before this was wired.
+    const head = [
+        renderSeoHead(seoSite, resource, {
+            ...(alternates.length === 0 ? {} : { alternates }),
+            ...(mediaAssets.size === 0 ? {} : { media: seoMedia }),
+            ...(seoSettings === null ? {} : { seo: seoSettings }),
+        }),
+        // Search Console/Webmaster Tools verification (fiche 50 task 2) — the
+        // same site-wide tags on every page, not just the home page: neither
+        // provider documents which page it fetches to check ownership.
+        siteVerificationMetaTags(seoSettings),
+    ]
+        .filter((part) => part !== '')
+        .join('\n');
+    // Precaution 1 of 3 (fiche 35 task 6): only ever rendered for an actor
+    // this request's own `resolveActor` actually authenticated — the flag
+    // alone (set for every request on this path, anonymous included) is not
+    // the gate, this check is.
+    const adminBar = options.adminBar === true && context.actor.id !== null
+        ? renderAdminBar(collection.name, entry.id, {
+            siteName: options.site.name,
+            showCogentaBranding: branding.showCogentaBranding,
+            locale: themeContext.locale,
+        })
+        : '';
+    // The navigation menus (audit follow-up to L13's menu system, generalised
+    // to real `location`s by fiche 09 task 3): the menu assigned to the header
+    // location, the one assigned to the footer location — see
+    // `ThemeRenderOptions.headerMenuLocation`/`footerMenuLocation` for why the
+    // location key is a per-render option rather than a name this file
+    // hardcodes, and `fetchMenuLinksForSlot` for the legacy-name fallback that
+    // keeps a pre-task-3 site's navigation rendering unchanged. Both are
+    // `null`, rendering nothing, on a site with no menu router wired or no
+    // menu in that slot at all — the same empty slots as before this was
+    // wired.
     const [headerMenu, footerMenu] = await Promise.all([
-        fetchMenuLinks('main', themeContext.locale, options, context),
-        fetchMenuLinks('footer', themeContext.locale, options, context),
+        fetchMenuLinksForSlot(options.headerMenuLocation ?? DEFAULT_HEADER_MENU_LOCATION, 'main', themeContext.locale, options, context),
+        fetchMenuLinksForSlot(options.footerMenuLocation ?? DEFAULT_FOOTER_MENU_LOCATION, 'footer', themeContext.locale, options, context),
     ]);
-    const headerNav = renderMenuLinks(headerMenu);
-    const footerNav = renderMenuLinks(footerMenu);
+    const brandingHtml = renderFooterBranding(branding, imageEndpoint);
+    const chromeExtras = await resolveChromeExtras(options.chromeExtras, themeContext.locale, options, context);
+    const chrome = theme.renderChrome({
+        site: options.site,
+        locale: themeContext.locale,
+        // Not locale-prefixed on purpose, matching this route's pre-existing
+        // behaviour — see `renderPageChrome`'s own identical comment.
+        homeHref: '/',
+        headerNav: headerMenu ?? [],
+        footerNav: footerMenu ?? [],
+        brandingHtml,
+        brand: identity.brand,
+        ...chromeExtras,
+    });
     // The same frame `Base.astro` builds for a real Astro build: a skip link
-    // first, the site name as a header, the content, a footer. Rendering the
+    // first, the site's own chrome, the content, a footer. Rendering the
     // `<main>` alone — which this did until the theme's own stylesheet started
     // being served — left every page with no landmark to skip to and no way back
     // to the home page.
@@ -420,14 +1034,20 @@ async function renderEntryPage(pathname, collection, entry, options, context) {
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="color-scheme" content="light dark">
+<script>${THEME_TOGGLE_SCRIPT}</script>
+${faviconLinkTag(identity.faviconHref, branding, imageEndpoint)}
+${feedLinkTags(options.site.name)}
+${fontPreconnectTags()}
 ${head}
 ${options.styles === null ? '' : `<link rel="stylesheet" href="${STYLESHEET_PATH}">`}
 </head>
 <body>
 <a class="cg-skip-link" href="#cg-main">Skip to content</a>
-<header class="cg-site-header"><div class="cg-site-header__inner"><a class="cg-site-header__home" href="/">${siteName}</a>${headerNav === '' ? '' : `<nav class="cg-site-header__nav" aria-label="Primary">${headerNav}</nav>`}</div></header>
+${adminBar}
+${chrome.header}
 ${bodyHtml}
-<footer class="cg-site-footer"><div class="cg-site-footer__inner"><span>${siteName}</span>${footerNav === '' ? '' : `<nav class="cg-site-footer__nav" aria-label="Footer">${footerNav}</nav>`}</div></footer>
+${commentsHtml}
+${chrome.footer}
 ${analyticsBeaconTag(pathname, options.analyticsBeacon)}
 </body>
 </html>
@@ -491,4 +1111,250 @@ export function joinStyles(skinCss, themeCss) {
     ].filter((sheet) => sheet !== null);
     return sheets.length === 0 ? null : sheets.join('\n');
 }
+/**
+ * The appearance screen's theme gallery preview (fiche L24 task 5) — one
+ * fixed, database-free demo page, rendered through whichever theme package
+ * is asked for by name.
+ *
+ * **Option (a) of the task's own note, chosen over (b) ("preview the site's
+ * real home page")**, for two reasons:
+ *
+ *  1. an admin comparing themes is often doing it *before* the site has any
+ *     content at all — the moment a real-home-page preview would have
+ *     nothing to show, or would 404 the whole comparison;
+ *  2. every candidate theme has to render the *same* page for the
+ *     comparison to mean anything. A real home page would let one theme's
+ *     card look richer than another's purely because that site's current
+ *     home happens to use more blocks — an artifact of this site's content,
+ *     not of the theme.
+ *
+ * The three blocks below (hero, collectionList, featureGrid) are the same
+ * shape `create-cogenta`'s "blog" blueprint seeds a real home page with
+ * (`packages/create-cogenta/src/blueprints/blog.ts`) — realistic content a
+ * theme actually has to lay out, not lorem ipsum — but the `collectionList`
+ * entries are fabricated in-process rather than queried, and nothing here
+ * ever touches `ContentGateway`/the database: a card in this gallery cannot
+ * leak draft or private content because it never reads content of any kind.
+ * `link()` and `image()` below reflect that — an entry link resolves to
+ * `'#'` rather than a real route, and `image()` refuses, because the demo
+ * page never references a real media asset in the first place.
+ */
+const GALLERY_PREVIEW_BLOCK_VERSION = '1.0.0';
+const GALLERY_PREVIEW_COLLECTION_LIST_KEY = 'gallery-preview-posts';
+function galleryPreviewPage() {
+    return {
+        title: 'A site that looks like yours',
+        blocks: [
+            {
+                _key: 'gallery-preview-hero',
+                _type: 'hero',
+                _version: GALLERY_PREVIEW_BLOCK_VERSION,
+                eyebrow: 'Preview',
+                title: 'A site that looks like yours',
+                subtitle: 'This is fixed demo content, shown identically across every theme, so you can compare layouts on equal footing.',
+                actions: [
+                    { label: 'Get started', target: { href: '#' }, emphasis: 'primary' },
+                    { label: 'Learn more', target: { href: '#' }, emphasis: 'secondary' },
+                ],
+            },
+            {
+                _key: GALLERY_PREVIEW_COLLECTION_LIST_KEY,
+                _type: 'collectionList',
+                _version: GALLERY_PREVIEW_BLOCK_VERSION,
+                title: 'Latest posts',
+                collection: 'post',
+                sort: { field: 'createdAt', direction: 'desc' },
+                limit: 3,
+                layout: 'list',
+            },
+            {
+                _key: 'gallery-preview-features',
+                _type: 'featureGrid',
+                _version: GALLERY_PREVIEW_BLOCK_VERSION,
+                title: 'What you get',
+                items: [
+                    {
+                        _key: 'gallery-preview-feature-1',
+                        icon: 'blocks',
+                        title: 'Blocks, not HTML',
+                        text: 'Every section of a page is structured data. The theme decides what it looks like.',
+                    },
+                    {
+                        _key: 'gallery-preview-feature-2',
+                        icon: 'content',
+                        title: 'Your real content',
+                        text: 'Switching themes never touches your entries — only how they are laid out.',
+                    },
+                    {
+                        _key: 'gallery-preview-feature-3',
+                        icon: 'zero-js',
+                        title: 'No client JavaScript',
+                        text: 'Every theme in this gallery ships zero executable client JavaScript.',
+                    },
+                ],
+            },
+        ],
+    };
+}
+/** Three fabricated posts for the demo `collectionList` above — never a real query result. */
+function galleryPreviewEntries(locale) {
+    const posts = [
+        {
+            title: 'Welcome to your new site',
+            excerpt: 'A short introduction to what you can do here, once real content replaces this demo.',
+        },
+        {
+            title: 'How themes work',
+            excerpt: 'A theme lays out your content; it never stores any of it. Switch freely.',
+        },
+        {
+            title: 'Zero client JavaScript, by policy',
+            excerpt: 'Every theme in the gallery renders without shipping a single script to the browser.',
+        },
+    ];
+    return posts.map((post, index) => ({
+        id: `gallery-preview-${index}`,
+        collection: 'post',
+        locale,
+        status: 'published',
+        title: post.title,
+        excerpt: post.excerpt,
+        createdAt: new Date(Date.now() - index * 86_400_000).toISOString(),
+    }));
+}
+/** Demo navigation for the gallery preview's header/footer — never a real menu lookup. */
+const GALLERY_PREVIEW_HEADER_NAV = [
+    { label: 'Home', href: '/', openInNewTab: false, kind: 'url', title: null },
+    { label: 'Blog', href: '#', openInNewTab: false, kind: 'url', title: null },
+    { label: 'About', href: '#', openInNewTab: false, kind: 'url', title: null },
+];
+const GALLERY_PREVIEW_FOOTER_NAV = [
+    { label: 'Privacy', href: '#', openInNewTab: false, kind: 'url', title: null },
+];
+/**
+ * Synthetic `theme@1.4` chrome (contract D, L25 D2) — this route reads no
+ * database (see `renderThemeGalleryPreview`'s own comment), so a real
+ * `general.socialLinks`/`general.tagline`/`general.footerNote` never reaches
+ * it; fixed demo values instead, the same way the nav above is fixed rather
+ * than empty, so the gallery actually shows what a candidate theme does with
+ * these fields rather than leaving them permanently blank.
+ */
+const GALLERY_PREVIEW_TAGLINE = 'A site that looks like yours';
+const GALLERY_PREVIEW_SOCIAL = [
+    { label: 'X', href: 'https://x.com/cogenta' },
+    { label: 'GitHub', href: 'https://github.com/cogenta-cms' },
+    { label: 'Mastodon', href: 'https://mastodon.social/@cogenta' },
+];
+const GALLERY_PREVIEW_FOOTER_NOTE = 'Built with Cogenta — a CMS that runs itself.';
+const GALLERY_PREVIEW_HEADER_ACTION = { label: 'Get started', href: '#' };
+/**
+ * Renders the fixed demo page above through `themeName`, resolved through
+ * the same `theme-registry.ts` every other theme lookup on this server uses.
+ * An unrecognised name is the caller's responsibility to refuse before
+ * calling this — `resolveTheme` itself falls back to the built-in default
+ * rather than throwing (see its own comment), which is the right behaviour
+ * for a live page render but not for a gallery card that claims to preview
+ * one specific theme.
+ */
+export async function renderThemeGalleryPreview(themeName, options) {
+    const theme = await resolveTheme(themeName);
+    const locale = options.site.defaultLocale;
+    const link = (target) => {
+        if (typeof target === 'string')
+            return target;
+        if ('path' in target)
+            return target.path;
+        // A demo entry has no real route — same "honest unresolvable answer" as
+        // `renderEntryPage`'s own `link`, just never populated here.
+        return '#';
+    };
+    const image = (media, _imageOptions) => {
+        throw new CogentaError({
+            code: 'THEME_IMAGE_UNSUPPORTED',
+            message: `No media asset "${media}" is available to the theme gallery preview.`,
+            hint: 'This preview renders fixed, image-free demo content by design — see renderThemeGalleryPreview.',
+            details: { media },
+        });
+    };
+    const themeContext = {
+        site: options.site,
+        locale,
+        url: new URL('/', options.site.url),
+        t: createThemeTranslator(locale),
+        image,
+        link,
+        content: {
+            entry: async () => null,
+            byPath: async () => null,
+            list: async () => ({ items: [], nextCursor: null }),
+        },
+    };
+    const pageContent = galleryPreviewPage();
+    const fetchedEntries = {
+        [GALLERY_PREVIEW_COLLECTION_LIST_KEY]: galleryPreviewEntries(locale),
+    };
+    const bodyHtml = serialize(theme.renderPage(pageContent, themeContext, fetchedEntries));
+    const brandingHtml = renderFooterBranding(await brandingFor(options.branding), DEFAULT_IMAGE_ENDPOINT);
+    const chrome = theme.renderChrome({
+        site: options.site,
+        locale,
+        homeHref: '/',
+        headerNav: GALLERY_PREVIEW_HEADER_NAV,
+        footerNav: GALLERY_PREVIEW_FOOTER_NAV,
+        brandingHtml,
+        tagline: GALLERY_PREVIEW_TAGLINE,
+        social: GALLERY_PREVIEW_SOCIAL,
+        footerNote: GALLERY_PREVIEW_FOOTER_NOTE,
+        headerAction: GALLERY_PREVIEW_HEADER_ACTION,
+    });
+    return `<!doctype html>
+<html lang="${escapeAttribute(locale)}" dir="auto">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<script>${THEME_TOGGLE_SCRIPT}</script>
+<meta name="robots" content="noindex, nofollow">
+<title>${escapeHtml(pageContent.title)}</title>
+${options.styles === null ? '' : `<style>${options.styles}</style>`}
+</head>
+<body>
+<a class="cg-skip-link" href="#cg-main">Skip to content</a>
+${chrome.header}
+${bodyHtml}
+${chrome.footer}
+</body>
+</html>
+`;
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;');
+}
+/**
+ * The public wait page for maintenance mode (fiche 24 task 5) — deliberately
+ * theme-agnostic (no skin, no block, no `RenderContext`): a site down for
+ * maintenance may be down for exactly the reason its theme cannot render, so
+ * this page must stand on its own, unstyled beyond a few inline rules.
+ */
+export function renderMaintenancePage(siteName, message) {
+    const body = message === null ? 'We are performing scheduled maintenance. Please check back soon.' : message;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(siteName)} — Maintenance</title>
+<style>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;color:#1a1a1a}h1{font-size:1.25rem}</style>
+</head>
+<body>
+<h1>${escapeHtml(siteName)}</h1>
+<p>${escapeHtml(body)}</p>
+</body>
+</html>
+`;
+}
 //# sourceMappingURL=theme-render.js.map