@rathnasgala2/template 4.0.0 → 4.2.0

package/README.md

@@ -436,6 +436,18 @@ allowlist: raster formats are admitted directly, and SVG is admitted only after
 in scope and expected** (TPL-H6 decision): this sanitizer is what makes a
 theme-declared SVG icon mark safe to publish.
 
+- **Publication palette and "Visitors see" (4.1.0).** Every build with a theme
+  derives the theme's palette-driven tokens from `appearance.tokens` (`{}` is
+  the theme's default palette) with `@rathnasgala2/schemas/palette`, checks the
+  derived values and every contrast pair in both modes (a failure refuses the
+  build with `APPEARANCE_PALETTE_CONTRAST`, naming the pair and mode), and
+  writes `assets/gala-palette-<12 hex of sha256>.css`, linked last with SRI and
+  listed in the manifest. A theme without a `palette` block is refused
+  (`THEME_PALETTE_MISSING`; malformed: `THEME_PALETTE_INVALID`).
+  `appearance.colorMode` reaches the page as `data-gala-color-mode-default` and
+  `data-gala-color-mode-allowed` on the root; a `light`/`dark` default is the
+  server-resolved mode, and a single allowed mode renders no toggle and sets
+  `color-scheme` to it.
 - **`baseUrl` path prefix (2.2.0).** `buildInput.baseUrl` may carry a path (a
   GitHub project site, `https://owner.github.io/g9/`); it is not origin-only.
   `internal/route.js#derivePublicBasePath(baseUrl, basePath)` joins that path
@@ -657,7 +669,7 @@ npm run audit               # npm audit --audit-level=high
 ```
 
 Source development does not require a sibling schema checkout. The exact
-`@rathnasgala2/schemas@3.8.0` release is installed from the npm registry, and
+`@rathnasgala2/schemas@3.10.0` release is installed from the npm registry, and
 the lockfile carries its registry integrity. The exact peer is the public
 consumer contract.
 
@@ -684,10 +696,10 @@ editions: they are a rendered content kind (see Editions).
 
 ## Consuming `@rathnasgala2/schemas`
 
-This source targets `@rathnasgala2/schemas@3.8.0` with an exact manifest pin.
+This source targets `@rathnasgala2/schemas@3.10.0` with an exact manifest pin.
 Generation-4 development verifies against the schema sibling/packed candidate.
-The historical `package-lock.json` is not a 3.8.0 registry claim: it must be
-regenerated, together with the SBOM, from the authoritative published 3.8.0
+The historical `package-lock.json` is not a 3.10.0 registry claim: it must be
+regenerated, together with the SBOM, from the authoritative published 3.10.0
 artifact before release. The 2.8.0->2.11.0 convergence changes none of the four
 roots this renderer validates, for the same reason the 2.7.0-2.8.0 delta below
 did not. Only the `"."` export (`validateGalaDocument`, `GALA_SCHEMA_IDS`) is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala2/template",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Deterministic Eleventy-backed static publication renderer for Galascribe portable repositories.",
   "type": "module",
   "license": "Apache-2.0",
@@ -77,7 +77,7 @@
     "sanitize-html": "2.17.7"
   },
   "peerDependencies": {
-    "@rathnasgala2/schemas": "3.8.0"
+    "@rathnasgala2/schemas": "3.10.0"
   },
   "devDependencies": {
     "@cyclonedx/cyclonedx-npm": "6.0.1",

package/src/core/errors.js

@@ -104,12 +104,16 @@ export class ThemeAssetError extends Error {
    * @param {string} reasonCode a stable, machine-checkable reason code (for
    *   example `THEME_STYLESHEETS_INVALID`, `THEME_CONTRACT_SCHEMA_INVALID`)
    * @param {string} message a human-readable description
+   * @param {Record<string, unknown>} [detail] optional machine-readable
+   *   detail (the palette refusals carry the failing pair and mode)
    */
-  constructor(reasonCode, message) {
+  constructor(reasonCode, message, detail) {
     super(`${reasonCode}: ${message}`);
     this.name = 'ThemeAssetError';
     /** @type {string} */
     this.reasonCode = reasonCode;
+    /** @type {Record<string, unknown> | undefined} */
+    this.detail = detail;
   }
 }
 

package/src/core/index.js

@@ -77,6 +77,8 @@ import {
   GALA_BASE_STYLESHEET_SOURCE,
 } from './internal/appearance/base-layer.js';
 import { renderAppearanceControl } from './internal/appearance/controller-markup.js';
+import { resolveColorModePresentation } from './internal/appearance/contract.js';
+import { TEMPLATE_RENDERER_VERSION } from './internal/package-version.js';
 import {
   ArtifactManifestValidationError,
   BuildInputValidationError,
@@ -190,7 +192,7 @@ export const TEMPLATE_PACKAGE_NAME = '@rathnasgala2/template';
  *
  * @type {string}
  */
-export const TEMPLATE_PACKAGE_VERSION = '4.0.0';
+export const TEMPLATE_PACKAGE_VERSION = TEMPLATE_RENDERER_VERSION;
 
 /**
  * Validate the caller-supplied render options, independent of build-input
@@ -401,8 +403,21 @@ export async function renderPublication(buildInput, options) {
         themeDirectory: path.resolve(options.themeDirectory),
         basePath: validatedInput.basePath,
         publicBasePath,
+        appearanceTokens: validatedInput.appearance.tokens,
       })
     : undefined;
+  // "Visitors see": the author's colour-mode default and allowed modes.
+  const colorMode = resolveColorModePresentation(
+    /** @type {{default: string, allowed: readonly string[]} | undefined} */ (
+      validatedInput.appearance.colorMode
+    ),
+  );
+  const colorModeData = {
+    resolvedColorMode: colorMode.resolvedMode,
+    colorModeDefault: colorMode.defaultMode,
+    colorModeAllowed: colorMode.allowedModes.join(' '),
+    colorScheme: colorMode.colorScheme,
+  };
   const themeStylesheetLinksHtml = themeAssetsResult
     ? themeAssetsResult.linkTagsHtml
     : defaultThemeStylesheetLinksHtml(publicBasePath);
@@ -410,6 +425,7 @@ export async function renderPublication(buildInput, options) {
 
   const appearanceControlHtml = renderAppearanceControl({
     messages: siteMessages,
+    toggle: colorMode.toggle,
   });
 
   // Run before page assembly, not after: resolving each page's own images
@@ -636,6 +652,7 @@ export async function renderPublication(buildInput, options) {
         baseStylesheetHref: baseStylesheetHrefValue,
         themeStylesheetLinksHtml,
         composition,
+        ...colorModeData,
       },
     });
   });
@@ -709,6 +726,7 @@ export async function renderPublication(buildInput, options) {
       baseStylesheetHref: baseStylesheetHrefValue,
       themeStylesheetLinksHtml,
       composition,
+      ...colorModeData,
     },
   });
 

package/src/core/internal/appearance/base-layer.js

@@ -459,8 +459,8 @@ export const GALA_BASE_COMPONENT_CSS = `
   .g-card-media { margin: 0; aspect-ratio: 16 / 10; overflow: hidden; border-radius: var(--gala-radius-media); background: var(--gala-color-surface-raised); border-bottom: var(--gala-border-media-divider); max-width: 100%; }
   .g-card-media img { width: 100%; height: 100%; object-fit: cover; filter: var(--gala-media-filter); transition: transform 1s var(--gala-ease-standard), filter var(--gala-duration-slow) var(--gala-ease-standard); }
   .g-card:hover .g-card-media img { transform: scale(var(--gala-media-zoom)); filter: var(--gala-media-filter-hover); }
-  .g-card-placeholder { display: grid; place-items: center; aspect-ratio: 16 / 10; width: 100%; overflow: hidden; border-radius: var(--gala-radius-media); background: var(--gala-paint-panel); color: var(--gala-color-panel-text); }
-  .g-card-placeholder .g-icon { width: 2.25rem; height: 2.25rem; opacity: .85; }
+  .g-card-placeholder { display: grid; place-items: center; aspect-ratio: 16 / 10; width: 100%; overflow: hidden; border-radius: var(--gala-radius-media); background: var(--gala-color-surface-raised); color: var(--gala-color-text-muted); }
+  .g-card-placeholder .g-icon { width: 2.25rem; height: 2.25rem; opacity: .7; }
   .g-hero-media .g-card-placeholder { height: 100%; aspect-ratio: auto; border-radius: 0; }
   .g-card-body { display: flex; flex-direction: column; gap: .6rem; padding: var(--gala-card-pad); flex: 1; min-width: 0; }
   .g-card-top { display: flex; align-items: center; justify-content: space-between; gap: var(--gala-space-2); min-height: 1.6rem; }

package/src/core/internal/appearance/bootstrap-script.js

@@ -41,6 +41,8 @@
 
 import { minifyScript } from './minify-script.js';
 import {
+  APPEARANCE_ALLOWED_ATTRIBUTE,
+  APPEARANCE_DEFAULT_ATTRIBUTE,
   APPEARANCE_MODE_DARK,
   APPEARANCE_MODE_LIGHT,
   APPEARANCE_MODE_SYSTEM,
@@ -65,6 +67,8 @@ const READABLE_SCRIPT_SOURCE = String.raw`(function () {
   var SAVED_KEY = ${JSON.stringify(SAVED_STORAGE_KEY)};
   var RESOLVED_ATTRIBUTE = ${JSON.stringify(APPEARANCE_RESOLVED_MODE_ATTRIBUTE)};
   var SELECTION_ATTRIBUTE = ${JSON.stringify(APPEARANCE_SELECTION_ATTRIBUTE)};
+  var DEFAULT_ATTRIBUTE = ${JSON.stringify(APPEARANCE_DEFAULT_ATTRIBUTE)};
+  var ALLOWED_ATTRIBUTE = ${JSON.stringify(APPEARANCE_ALLOWED_ATTRIBUTE)};
   var TOGGLE_ID = ${JSON.stringify(APPEARANCE_TOGGLE_ID)};
   var MODE_LIGHT = ${JSON.stringify(APPEARANCE_MODE_LIGHT)};
   var MODE_DARK = ${JSON.stringify(APPEARANCE_MODE_DARK)};
@@ -75,14 +79,32 @@ const READABLE_SCRIPT_SOURCE = String.raw`(function () {
   function isKnownMode(value) {
     return value === MODE_LIGHT || value === MODE_DARK || value === MODE_SYSTEM;
   }
+  function allowedModes() {
+    var listed = (root.getAttribute(ALLOWED_ATTRIBUTE) || '').split(' ');
+    var modes = [];
+    for (var i = 0; i < listed.length; i++) {
+      if (isKnownMode(listed[i])) modes.push(listed[i]);
+    }
+    return modes.length ? modes : [MODE_SYSTEM, MODE_LIGHT, MODE_DARK];
+  }
+  function isAllowed(value) {
+    return isKnownMode(value) && allowedModes().indexOf(value) !== -1;
+  }
+  // The author's "Visitors see" default, else system.
+  function authorDefault() {
+    var value = root.getAttribute(DEFAULT_ATTRIBUTE);
+    return isAllowed(value) ? value : MODE_SYSTEM;
+  }
+  // The reader's stored choice (when the author still allows it), else the
+  // author's default, else system.
   function readStoredSelection() {
     try {
       var value = window.localStorage.getItem(STORAGE_KEY);
-      if (isKnownMode(value)) return value;
+      if (isAllowed(value)) return value;
     } catch (error) {
-      // Storage blocked: fall back to MODE_SYSTEM below.
+      // Storage blocked: fall back to the author's default below.
     }
-    return MODE_SYSTEM;
+    return authorDefault();
   }
   function writeStoredSelection(mode) {
     try {
@@ -230,7 +252,8 @@ const READABLE_SCRIPT_SOURCE = String.raw`(function () {
   function enhanceMode() {
     var button = document.getElementById(TOGGLE_ID);
     if (!button) return;
-    var order = [MODE_SYSTEM, MODE_LIGHT, MODE_DARK];
+    var order = [MODE_SYSTEM, MODE_LIGHT, MODE_DARK].filter(isAllowed);
+    if (order.length < 2) return;
     var sync = function () {
       var label = button.getAttribute('data-label-' + readStoredSelection());
       if (label) {

package/src/core/internal/appearance/contract.js

@@ -67,6 +67,27 @@ export const APPEARANCE_RESOLVED_MODE_ATTRIBUTE =
  */
 export const APPEARANCE_SELECTION_ATTRIBUTE = 'data-gala-color-mode-selection';
 
+/**
+ * Template-internal bookkeeping attribute carrying the author's "Visitors
+ * see" default (`appearance.colorMode.default`: `light`, `dark` or
+ * `system`), rendered on the root by the server. Not part of the published
+ * theme styling contract; no theme selector may target it.
+ *
+ * @type {string}
+ */
+export const APPEARANCE_DEFAULT_ATTRIBUTE = 'data-gala-color-mode-default';
+
+/**
+ * Template-internal bookkeeping attribute carrying the modes the author
+ * allows (`appearance.colorMode.allowed`), space separated, rendered on the
+ * root so the page script ignores a stored choice the author no longer
+ * offers and cycles only through allowed modes. Not part of the published
+ * theme styling contract.
+ *
+ * @type {string}
+ */
+export const APPEARANCE_ALLOWED_ATTRIBUTE = 'data-gala-color-mode-allowed';
+
 /** @type {'light'} */
 export const APPEARANCE_MODE_LIGHT = 'light';
 /** @type {'dark'} */
@@ -117,6 +138,61 @@ export const APPEARANCE_RESOLVED_MODE_VALUES = Object.freeze([
  */
 export const APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE = APPEARANCE_MODE_LIGHT;
 
+/**
+ * What the server renders for one publication's `appearance.colorMode`
+ * (the "Visitors see" setting).
+ *
+ * - `defaultMode`: the author's default, a root attribute.
+ * - `allowedModes`: the author's allowed list, in canonical order.
+ * - `resolvedMode`: the server-resolved mode. `light` and `dark` defaults
+ *   are used as is; `system` keeps {@link APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE}
+ *   (the script resolves it against the reader's system preference).
+ * - `colorScheme`: the `<meta name="color-scheme">` content. A single
+ *   allowed `light` or `dark` is that mode alone; everything else is
+ *   {@link COLOR_SCHEME_META_CONTENT}.
+ * - `toggle`: whether the colour-mode control is rendered (two or more
+ *   allowed modes).
+ *
+ * @param {{default: string, allowed: readonly string[]} | undefined} colorMode
+ *   `appearance.colorMode`; absent behaves as the former fixed behaviour
+ *   (all three modes allowed, default `system`)
+ * @returns {{
+ *   defaultMode: string,
+ *   allowedModes: string[],
+ *   resolvedMode: string,
+ *   colorScheme: string,
+ *   toggle: boolean,
+ * }} the render facts
+ */
+export function resolveColorModePresentation(colorMode) {
+  const allowedModes = APPEARANCE_MODE_VALUES.filter((mode) =>
+    /** @type {readonly string[]} */ (
+      colorMode?.allowed ?? APPEARANCE_MODE_VALUES
+    ).includes(mode),
+  );
+  const defaultMode =
+    colorMode !== undefined &&
+    /** @type {readonly string[]} */ (allowedModes).includes(colorMode.default)
+      ? colorMode.default
+      : APPEARANCE_DEFAULT_MODE;
+  const resolvedMode =
+    defaultMode === APPEARANCE_MODE_LIGHT ||
+    defaultMode === APPEARANCE_MODE_DARK
+      ? defaultMode
+      : APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE;
+  const only = allowedModes.length === 1 ? allowedModes[0] : undefined;
+  return {
+    defaultMode,
+    allowedModes,
+    resolvedMode,
+    colorScheme:
+      only === APPEARANCE_MODE_LIGHT || only === APPEARANCE_MODE_DARK
+        ? only
+        : COLOR_SCHEME_META_CONTENT,
+    toggle: allowedModes.length > 1,
+  };
+}
+
 /**
  * The initial reader default is `system`.
  *

package/src/core/internal/appearance/controller-markup.js

@@ -30,9 +30,13 @@ import {
  * @param {object} options rendering options
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
  *   the resolved message catalog
- * @returns {string} the control markup
+ * @param {boolean} [options.toggle] whether the control is rendered; `false`
+ *   when the author allows a single colour mode ("Visitors see" offers the
+ *   reader nothing to choose), so no dead control is shown
+ * @returns {string} the control markup (empty when `toggle` is `false`)
  */
-export function renderAppearanceControl({ messages }) {
+export function renderAppearanceControl({ messages, toggle = true }) {
+  if (!toggle) return '';
   const control = /** @type {string} */ (messages.appearanceControlLabel);
   /** @type {Record<string, string>} */
   const modeText = {

package/src/core/internal/appearance/palette-sheet.js

@@ -0,0 +1,217 @@
+/**
+ * The publication palette stylesheet: every build that supplies a theme
+ * package derives the theme's palette-driven tokens from the author's
+ * `appearance.tokens` (`{}` or absent selects the theme's own default
+ * palette), checks them, and writes them as one content-addressed
+ * `assets/gala-palette-<12 hex>.css` file linked after the theme's own
+ * stylesheets.
+ *
+ * All colour mathematics lives in `@rathnasgala2/schemas/palette`
+ * (`derivePalette`, `checkPalette`); this module never re-implements any of
+ * it. It only
+ *
+ * 1. derives the final token values,
+ * 2. re-checks every derived value against the theme-contract token grammar
+ *    (the same closed schema every theme token already passes),
+ * 3. checks every contrast pair in both modes, and
+ * 4. serialises the bound tokens into four blocks inside
+ *    `@layer gala-tokens`: the bare root (light), the
+ *    `prefers-color-scheme: dark` root, and the two resolved-mode selectors,
+ *    exactly the four blocks a theme's own `tokens.css` uses. The sheet is an
+ *    external same-origin file, so the CSP stays free of inline styles.
+ *
+ * The bytes are a pure function of the theme's palette-relevant data and the
+ * author's picks, so sites on the same theme default share identical bytes.
+ */
+
+import { createHash } from 'node:crypto';
+
+import { validateGalaDocument } from '@rathnasgala2/schemas';
+import {
+  checkPalette,
+  derivePalette,
+  PaletteError,
+} from '@rathnasgala2/schemas/palette';
+
+import { ThemeAssetError } from '../../errors.js';
+import {
+  APPEARANCE_RESOLVED_MODE_ATTRIBUTE,
+  APPEARANCE_ROOT_ATTRIBUTE,
+} from './contract.js';
+
+/** @type {string} */
+export const PALETTE_STYLESHEET_DIRECTORY = 'assets';
+/** @type {string} */
+export const PALETTE_STYLESHEET_PREFIX = 'gala-palette-';
+/** @type {string} */
+export const PALETTE_STYLESHEET_MEDIA_TYPE = 'text/css; charset=utf-8';
+/** @type {number} the palette sheet's size ceiling (design D4). */
+export const PALETTE_STYLESHEET_MAXIMUM_BYTES = 16384;
+
+const THEME_CONTRACT_SCHEMA_ID = 'urn:gala:schema:theme-contract:2.0.0';
+
+/**
+ * @param {Record<string, string>} declarations `--gala-<key>` -> value
+ * @param {string} indent line indent
+ * @returns {string} the declaration lines
+ */
+function declarationLines(declarations, indent) {
+  return Object.entries(declarations)
+    .map(([key, value]) => `${indent}--gala-${key}: ${value};\n`)
+    .join('');
+}
+
+/**
+ * Serialise the bound tokens into the four-block sheet.
+ *
+ * @param {Record<string, {light: string, dark: string}>} tokens derived tokens
+ * @param {readonly string[]} bound the bound keys, in the theme's order
+ * @returns {string} the stylesheet text
+ */
+function serialisePaletteSheet(tokens, bound) {
+  const keys = [...bound].sort((a, b) =>
+    Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8')),
+  );
+  /** @type {Record<string, string>} */
+  const light = {};
+  /** @type {Record<string, string>} */
+  const dark = {};
+  for (const key of keys) {
+    light[key] = /** @type {{light: string, dark: string}} */ (
+      tokens[key]
+    ).light;
+    dark[key] = /** @type {{light: string, dark: string}} */ (tokens[key]).dark;
+  }
+  const root = `[${APPEARANCE_ROOT_ATTRIBUTE}]`;
+  const resolved = (/** @type {string} */ mode) =>
+    `[${APPEARANCE_ROOT_ATTRIBUTE}][${APPEARANCE_RESOLVED_MODE_ATTRIBUTE}="${mode}"]`;
+  return (
+    `@layer gala-tokens {\n` +
+    `  ${root} {\n${declarationLines(light, '    ')}  }\n` +
+    `  @media (prefers-color-scheme: dark) {\n` +
+    `    ${root} {\n${declarationLines(dark, '      ')}    }\n` +
+    `  }\n` +
+    `  ${resolved('light')} {\n${declarationLines(light, '    ')}  }\n` +
+    `  ${resolved('dark')} {\n${declarationLines(dark, '    ')}  }\n` +
+    `}\n`
+  );
+}
+
+/**
+ * Map a schemas `PaletteError` to the template's refusal shape.
+ *
+ * @param {unknown} error the thrown value
+ * @returns {never} always throws
+ */
+function rethrowPaletteError(error) {
+  if (error instanceof PaletteError) {
+    throw new ThemeAssetError(error.code, error.detail);
+  }
+  throw error;
+}
+
+/**
+ * Admit a theme's `palette` block: the theme must declare one and it must be
+ * well formed. There is no fallback for a theme without it.
+ *
+ * @param {Record<string, unknown>} themeJson the parsed `theme.json`
+ * @returns {void}
+ * @throws {ThemeAssetError} `THEME_PALETTE_MISSING` or `THEME_PALETTE_INVALID`
+ */
+export function assertThemePalette(themeJson) {
+  try {
+    derivePalette(
+      /** @type {Parameters<typeof derivePalette>[0]} */ (themeJson),
+      {},
+    );
+  } catch (error) {
+    rethrowPaletteError(error);
+  }
+}
+
+/**
+ * Derive, check and serialise the palette sheet for one build.
+ *
+ * @param {Record<string, unknown>} themeJson the admitted `theme.json`
+ * @param {unknown} appearanceTokens `appearance.tokens` (`{}` or absent for
+ *   the theme's default palette)
+ * @returns {{
+ *   text: string,
+ *   bytes: Buffer,
+ *   fileName: string,
+ * }} the sheet and its content-addressed file name
+ * @throws {ThemeAssetError} `APPEARANCE_PALETTE_INVALID` (malformed picks or
+ *   a derived value outside the token grammar), `APPEARANCE_PALETTE_CONTRAST`
+ *   (a pair below its minimum; the message names the pair, mode and ratio)
+ */
+export function buildPaletteStylesheet(themeJson, appearanceTokens) {
+  const theme = /** @type {Parameters<typeof derivePalette>[0]} */ (themeJson);
+  /** @type {ReturnType<typeof derivePalette>} */
+  let derived;
+  try {
+    derived = derivePalette(
+      theme,
+      /** @type {Parameters<typeof derivePalette>[1]} */ (
+        appearanceTokens ?? {}
+      ),
+    );
+  } catch (error) {
+    return rethrowPaletteError(error);
+  }
+
+  // Every derived value passes the closed token grammar: the theme-contract
+  // schema validates each token's value against its type, so substitute the
+  // derived values into the theme's own token rows and validate.
+  const finalTokens =
+    /** @type {{key: string, light: string, dark: string}[]} */ (
+      themeJson.tokens
+    ).map((row) => ({
+      ...row,
+      light: derived.tokens[row.key]?.light ?? row.light,
+      dark: derived.tokens[row.key]?.dark ?? row.dark,
+    }));
+  const validation = validateGalaDocument(THEME_CONTRACT_SCHEMA_ID, {
+    ...themeJson,
+    tokens: finalTokens,
+  });
+  if (!validation.valid) {
+    throw new ThemeAssetError(
+      'APPEARANCE_PALETTE_INVALID',
+      `a derived palette value is outside the token grammar ` +
+        `(${validation.diagnostics.length} diagnostic(s)): ` +
+        JSON.stringify(validation.diagnostics),
+    );
+  }
+
+  for (const mode of /** @type {const} */ (['light', 'dark'])) {
+    const check = checkPalette(derived, mode);
+    const failure = check.failures[0];
+    if (failure) {
+      const ratio =
+        failure.ratio === null
+          ? (failure.reason ?? 'unmeasurable')
+          : `${failure.ratio.toFixed(2)}:1`;
+      throw new ThemeAssetError(
+        'APPEARANCE_PALETTE_CONTRAST',
+        `${failure.pair} in ${mode} mode is ${ratio}, below ${failure.minimum}:1 ` +
+          `(${check.failures.length} failing pair(s) in ${mode} mode)`,
+        { pair: failure.pair, mode, failures: check.failures },
+      );
+    }
+  }
+
+  const text = serialisePaletteSheet(derived.tokens, derived.bound);
+  const bytes = Buffer.from(text, 'utf8');
+  if (bytes.byteLength > PALETTE_STYLESHEET_MAXIMUM_BYTES) {
+    throw new ThemeAssetError(
+      'APPEARANCE_PALETTE_INVALID',
+      `the palette stylesheet is ${bytes.byteLength} bytes, over ${PALETTE_STYLESHEET_MAXIMUM_BYTES}`,
+    );
+  }
+  const hash = createHash('sha256').update(bytes).digest('hex').slice(0, 12);
+  return {
+    text,
+    bytes,
+    fileName: `${PALETTE_STYLESHEET_PREFIX}${hash}.css`,
+  };
+}

package/src/core/internal/components.js

@@ -19,6 +19,7 @@ import { escapeHtml } from './skeleton.js';
 import { icon } from './icons.js';
 import { joinBasePathAndRoute } from './route.js';
 import { resolveOriginalDerivativePath } from './seo.js';
+import { cardMediaOf } from './first-body-image.js';
 
 /** Reading speed used for every reading-time estimate. */
 export const WORDS_PER_MINUTE = 230;
@@ -395,9 +396,10 @@ export function createComponents(context) {
   const card = (record, options = {}, variant = 'grid') => {
     const fm = record.frontmatter;
     const href = escapeHtml(recordHref(record));
-    const hero = mediaImage(fm.hero?.file);
+    const cardMedia = cardMediaOf(record);
+    const hero = mediaImage(cardMedia?.file);
     const media = hero
-      ? `<figure class="g-card-media">${renderImage({ image: hero, alt: fm.hero?.role === 'decorative' ? '' : (fm.hero?.alt ?? '') })}</figure>`
+      ? `<figure class="g-card-media">${renderImage({ image: hero, alt: cardMedia?.role === 'decorative' ? '' : (cardMedia?.alt ?? '') })}</figure>`
       : `<div class="g-card-placeholder" aria-hidden="true">${icon('sparkle')}</div>`;
     const seriesTag = options.partLabel
       ? `<span class="g-series-tag">${icon('book')}${escapeHtml(options.partLabel)}</span>`

package/src/core/internal/eleventy-render.js

@@ -33,10 +33,10 @@
 import Eleventy from '@11ty/eleventy';
 
 import {
+  APPEARANCE_ALLOWED_ATTRIBUTE,
+  APPEARANCE_DEFAULT_ATTRIBUTE,
   APPEARANCE_RESOLVED_MODE_ATTRIBUTE,
   APPEARANCE_ROOT_ATTRIBUTE,
-  APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE,
-  COLOR_SCHEME_META_CONTENT,
 } from './appearance/contract.js';
 import { PAGE_KIND_ATTRIBUTE } from './page-kinds.js';
 
@@ -78,7 +78,8 @@ import { PAGE_KIND_ATTRIBUTE } from './page-kinds.js';
  *   rendered independent of JavaScript, so a theme's own no-JS
  *   `prefers-color-scheme` fallback CSS has a stable root scope to key off;
  * - (TPL-C1 fix) `data-gala-resolved-color-mode`, server-rendered as
- *   {@link APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE} (`"light"`) on the same
+ *   `data.resolvedColorMode` (the author's `light`/`dark` default, else
+ *   `"light"` for a `system` default) on the same
  *   `<html>` element, so `RESOLVED_PALETTE_SELECTORS.light` already matches
  *   before any script runs and a page is never unstyled UA-default HTML for
  *   a no-JS reader, a text-mode/archival crawler, or a load where the
@@ -87,7 +88,12 @@ import { PAGE_KIND_ATTRIBUTE } from './page-kinds.js';
  *   this attribute with the resolved value for the reader's actual stored
  *   selection/system preference the instant it runs, so a scripted reader's
  *   experience is unchanged;
- * - `<meta name="color-scheme" content="light dark">`, so user-agent styling
+ * - `data-gala-color-mode-default` and `data-gala-color-mode-allowed`, the
+ *   author's "Visitors see" default and allowed modes
+ *   (`appearance.colorMode`), which the bootstrap script prefers over
+ *   `system` when the reader has no stored choice;
+ * - `<meta name="color-scheme">`, `light dark` unless the author allows a
+ *   single `light` or `dark` mode, so user-agent styling
  *   (form controls, scrollbars) and the initial paint already follow
  *   `prefers-color-scheme` before any script runs;
  * - the one `<script src>` this renderer ever emits (the appearance
@@ -128,12 +134,12 @@ import { PAGE_KIND_ATTRIBUTE } from './page-kinds.js';
  */
 const SKELETON_LAYOUT_SOURCE = [
   '<!doctype html>',
-  `<html lang="{{ lang }}" dir="{{ dir }}" ${APPEARANCE_ROOT_ATTRIBUTE} ${APPEARANCE_RESOLVED_MODE_ATTRIBUTE}="${APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE}">`,
+  `<html lang="{{ lang }}" dir="{{ dir }}" ${APPEARANCE_ROOT_ATTRIBUTE} ${APPEARANCE_RESOLVED_MODE_ATTRIBUTE}="{{ resolvedColorMode }}" ${APPEARANCE_DEFAULT_ATTRIBUTE}="{{ colorModeDefault }}" ${APPEARANCE_ALLOWED_ATTRIBUTE}="{{ colorModeAllowed }}">`,
   '<head>',
   '<meta charset="utf-8">',
   '<meta name="viewport" content="width=device-width, initial-scale=1">',
   '{{ cspMetaTag | safe }}',
-  `<meta name="color-scheme" content="${COLOR_SCHEME_META_CONTENT}">`,
+  '<meta name="color-scheme" content="{{ colorScheme }}">',
   // The interactions script (article pages, module on) is deferred and sits
   // on the appearance script's line, so a page without it is byte-identical
   // to before.

package/src/core/internal/first-body-image.js

@@ -0,0 +1,91 @@
+/**
+ * The picture a post shows where the post is summarised (cards, the home
+ * hero, `og:image`) when its frontmatter carries no `hero`.
+ *
+ * A content record's `body` is already render-policy-conformant HTML (the
+ * authored Markdown after `normalizeAuthoredMarkdown`), so inline images
+ * (`![alt](assets/x.png)`), `./`-prefixed paths and reference-style images
+ * (`![alt][ref]` with a `[ref]: assets/x.png` definition) have all become
+ * `<img src alt>` elements by the time this module sees them; code samples
+ * are `<pre>`/`<code>` text whose `<` is entity-encoded. The scan is
+ * therefore over `<img>` elements, with the same path rule the prose
+ * renderer resolves them by (`media/content-images.js`).
+ */
+
+import { unescapeHtml } from './skeleton.js';
+import { repositoryPathOfImageSource } from './media/content-images.js';
+
+/** Code regions, removed before the scan so an image shown as code is skipped. */
+const CODE_REGION = /<pre\b[\s\S]*?<\/pre>|<code\b[\s\S]*?<\/code>/g;
+
+const IMG_ELEMENT = /<img\b[^>]*>/g;
+const ATTRIBUTE = /\s([a-zA-Z][a-zA-Z0-9-]*)="([^"]*)"/g;
+
+/** The media types a card picture may be (same set as body images). */
+const IMAGE_MEDIA_TYPES = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/webp',
+  'image/avif',
+  'image/gif',
+]);
+
+/**
+ * @param {string} body a content record's policy-conformant HTML body
+ * @returns {{path: string, alt: string} | undefined} the first image whose
+ *   source is a repository-relative `assets/` path (remote, `data:` and
+ *   code-region images are skipped), with its decoded alt text
+ */
+export function firstBodyImage(body) {
+  for (const element of body.replace(CODE_REGION, '').match(IMG_ELEMENT) ??
+    []) {
+    /** @type {{src?: string, alt?: string}} */
+    const attributes = {};
+    for (const [, name, value] of element.matchAll(ATTRIBUTE)) {
+      if (name === 'src' || name === 'alt') attributes[name] = value;
+    }
+    const path = repositoryPathOfImageSource(attributes.src);
+    if (path?.startsWith('assets/')) {
+      return { path, alt: unescapeHtml(attributes.alt ?? '') };
+    }
+  }
+  return undefined;
+}
+
+/** @type {WeakMap<object, unknown>} */
+const cache = new WeakMap();
+
+/**
+ * The picture a record shows on cards, the home hero and as its social
+ * image: `frontmatter.hero` when present, else the first body image that the
+ * record's own `media[]` inventories (so it carries the `sourceDigest` the
+ * media pipeline processed it by). Computed once per record.
+ *
+ * @param {import('../../../types/index.d.ts').ContentBuildRecord} record
+ * @returns {{file: {path: string, sourceDigest: string}, alt?: string, role: 'informative' | 'decorative'} | undefined}
+ */
+export function cardMediaOf(record) {
+  if (cache.has(record)) {
+    return /** @type {ReturnType<typeof cardMediaOf>} */ (cache.get(record));
+  }
+  /** @type {ReturnType<typeof cardMediaOf>} */
+  let media = /** @type {any} */ (record.frontmatter.hero);
+  if (!media) {
+    const image = firstBodyImage(record.body);
+    const entry = image
+      ? record.media?.find(
+          (file) =>
+            file.path === image.path && IMAGE_MEDIA_TYPES.has(file.mediaType),
+        )
+      : undefined;
+    if (image && entry) {
+      media = {
+        file: { path: entry.path, sourceDigest: entry.sourceDigest },
+        alt: image.alt,
+        role: 'informative',
+      };
+    }
+  }
+  cache.set(record, media);
+  return media;
+}

package/src/core/internal/package-version.js

@@ -0,0 +1,11 @@
+/**
+ * The renderer's own published version, the single constant both the public
+ * `TEMPLATE_PACKAGE_VERSION` export and theme `templateRange` admission read.
+ * It is deliberately separate from the styling contract's
+ * `templateVersion` (`appearance/styling-contract.js`), which records the
+ * version the contract was published at and is part of the contract digest:
+ * a renderer release that does not change the contract keeps that digest.
+ *
+ * @type {string}
+ */
+export const TEMPLATE_RENDERER_VERSION = '4.1.0';

package/src/core/internal/page-kinds.js

@@ -78,6 +78,7 @@ import {
   resolveEditions,
 } from './editions.js';
 import { truncateAtWord } from './seo.js';
+import { cardMediaOf } from './first-body-image.js';
 import { createStructuredData } from './structured-data.js';
 import { icon } from './icons.js';
 import {
@@ -499,21 +500,22 @@ export function buildGeneratedPages(validatedInput, options) {
       }
     : {};
   /**
-   * @param {import('../../../types/index.d.ts').ContentFrontmatterNormalized} fm
+   * @param {import('../../../types/index.d.ts').ContentBuildRecord} record
    * @returns {{socialImageRef?: {path: string, sourceDigest: string}, socialImageAlt?: string}}
    */
-  const socialOfContent = (fm) =>
-    fm.socialImage
+  const socialOfContent = (record) => {
+    const fm = record.frontmatter;
+    const media = cardMediaOf(record);
+    return fm.socialImage
       ? { socialImageRef: fm.socialImage, socialImageAlt: fm.title }
-      : fm.hero
+      : media
         ? {
-            socialImageRef: fm.hero.file,
+            socialImageRef: media.file,
             socialImageAlt:
-              fm.hero.role === 'informative' && fm.hero.alt
-                ? fm.hero.alt
-                : fm.title,
+              media.role === 'informative' && media.alt ? media.alt : fm.title,
           }
         : defaultSocial;
+  };
   /**
    * @param {import('../../../types/index.d.ts').ContentBuildRecord} record
    * @returns {string} the page description: authored, else the body's
@@ -1004,15 +1006,15 @@ export function buildGeneratedPages(validatedInput, options) {
     // An edition with no social image of its own shares its article's.
     const social = socialOfContent(
       isEdition && !frontmatter.socialImage && !frontmatter.hero
-        ? original.frontmatter
-        : frontmatter,
+        ? original
+        : record,
     );
     const articleGraph = isArticle
       ? sd.article({
           url: ownUrl,
           headline: frontmatter.title,
           description: contentDescription(record),
-          image: absoluteImage(socialOfContent(frontmatter).socialImageRef),
+          image: absoluteImage(socialOfContent(record).socialImageRef),
           datePublished: frontmatter.publishedAt,
           dateModified: contentLastModified(frontmatter),
           language: frontmatter.language,
@@ -1095,7 +1097,8 @@ export function buildGeneratedPages(validatedInput, options) {
   const homeFeatured = featured
     ? (() => {
         const fm = featured.frontmatter;
-        const hero = mediaImage(fm.hero?.file);
+        const cardMedia = cardMediaOf(featured);
+        const hero = mediaImage(cardMedia?.file);
         const href = escapeHtml(recordHref(featured));
         return (
           `<section class="g-wrap g-hero" aria-labelledby="hero-title">` +
@@ -1103,7 +1106,10 @@ export function buildGeneratedPages(validatedInput, options) {
           (hero
             ? renderImage({
                 image: hero,
-                alt: fm.hero?.role === 'decorative' ? '' : (fm.hero?.alt ?? ''),
+                alt:
+                  cardMedia?.role === 'decorative'
+                    ? ''
+                    : (cardMedia?.alt ?? ''),
                 priority: true,
               })
             : `<span class="g-card-placeholder">${icon('sparkle')}</span>`) +

package/src/core/internal/source-inventory.js

@@ -6,6 +6,8 @@
  * appears once, and its role is the earliest value in the enum order.
  */
 
+import { cardMediaOf } from './first-body-image.js';
+
 /** @type {readonly string[]} */
 const ROLE_PRIORITY = Object.freeze([
   'publication',
@@ -77,13 +79,12 @@ export function collectIncludedSources(buildInput) {
       'content',
       contentRecord.sourceRevision,
     );
-    if (contentRecord.frontmatter.hero) {
-      recordResolvedFile(
-        record,
-        contentRecord.frontmatter.hero.file,
-        contentRecord.sourceRevision,
-      );
-    }
+    // The hero, else the first body image a card shows in its place.
+    recordResolvedFile(
+      record,
+      cardMediaOf(contentRecord)?.file,
+      contentRecord.sourceRevision,
+    );
     recordResolvedFile(
       record,
       contentRecord.frontmatter.socialImage,

package/src/core/internal/theme-assets.js

@@ -77,9 +77,13 @@ import { validateGalaDocument } from '@rathnasgala2/schemas';
 import { ThemeAssetError } from '../errors.js';
 import { digestBytes } from './canonical-jcs.js';
 import {
-  buildTemplateStylingContract,
-  TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION,
-} from './appearance/styling-contract.js';
+  assertThemePalette,
+  buildPaletteStylesheet,
+  PALETTE_STYLESHEET_DIRECTORY,
+  PALETTE_STYLESHEET_MEDIA_TYPE,
+} from './appearance/palette-sheet.js';
+import { buildTemplateStylingContract } from './appearance/styling-contract.js';
+import { TEMPLATE_RENDERER_VERSION } from './package-version.js';
 import { MEDIA_TYPE_BY_FORMAT, sniffMediaFormat } from './media/sniff.js';
 import { sanitizeThemeSvg } from './media/theme-svg-sanitizer.js';
 import { projectFixedAssetPath } from './route.js';
@@ -414,6 +418,21 @@ function admitPassiveAssetBytes(relativePath, bytes) {
 function assertThemeContractIntegrity(themeJson) {
   const validation = validateGalaDocument(THEME_CONTRACT_SCHEMA_ID, themeJson);
   if (!validation.valid) {
+    // A palette block the closed schema itself refuses (unknown or
+    // non-drivable key, bad profile, bad role) is a palette refusal, not a
+    // generic contract refusal, so the author sees one code for it.
+    if (
+      validation.diagnostics.every((diagnostic) =>
+        String(diagnostic.instancePointer ?? '').startsWith('/palette'),
+      )
+    ) {
+      throw new ThemeAssetError(
+        'THEME_PALETTE_INVALID',
+        `theme.json palette failed ${THEME_CONTRACT_SCHEMA_ID} validation ` +
+          `(${validation.diagnostics.length} diagnostic(s)): ` +
+          JSON.stringify(validation.diagnostics),
+      );
+    }
     throw new ThemeAssetError(
       'THEME_CONTRACT_SCHEMA_INVALID',
       `theme.json failed ${THEME_CONTRACT_SCHEMA_ID} validation ` +
@@ -442,7 +461,7 @@ function assertThemeContractIntegrity(themeJson) {
   let templateRangeSatisfied;
   try {
     templateRangeSatisfied = satisfiesTemplateRange(
-      TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION,
+      TEMPLATE_RENDERER_VERSION,
       /** @type {string} */ (themeJson.templateRange),
     );
   } catch (error) {
@@ -456,7 +475,7 @@ function assertThemeContractIntegrity(themeJson) {
       'THEME_CONTRACT_VERSION_MISMATCH',
       `theme.json.templateRange (${themeJson.templateRange}) does not admit ` +
         `this renderer's own published version ` +
-        `(${TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION})`,
+        `(${TEMPLATE_RENDERER_VERSION})`,
     );
   }
   try {
@@ -467,6 +486,9 @@ function assertThemeContractIntegrity(themeJson) {
       /** @type {Error} */ (error).message,
     );
   }
+  // Template 4.1.0: every theme declares its palette bindings; a theme
+  // without them (any 4.0.0 package) is refused, with no fallback path.
+  assertThemePalette(themeJson);
 }
 
 /**
@@ -495,6 +517,9 @@ function subresourceIntegrityAttribute(bytes) {
  * @param {string} options.basePath the build input's `basePath`
  * @param {string} [options.publicBasePath] the base path emitted `<link href>`
  *   values use (`route.js#derivePublicBasePath`); defaults to `basePath`
+ * @param {unknown} [options.appearanceTokens] `appearance.tokens` (`{}` or
+ *   absent selects the theme's default palette); the derived palette sheet
+ *   is written and linked after the theme's own stylesheets
  * @returns {Promise<{
  *   files: {path: string, bytes: Buffer}[],
  *   assets: import('../../../types/index.d.ts').ManifestAssetEntry[],
@@ -507,6 +532,7 @@ export async function loadThemeAssets({
   themeDirectory,
   basePath,
   publicBasePath = basePath,
+  appearanceTokens = {},
 }) {
   const { bytes: themeJsonBytes } = await readDeclaredThemeFile(
     themeDirectory,
@@ -566,6 +592,27 @@ export async function loadThemeAssets({
     );
   }
 
+  // Template 4.1.0: the publication palette sheet, derived on every build
+  // (`{}` selects the theme's default palette), content-addressed, linked
+  // last with SRI and manifested like every theme stylesheet.
+  const paletteSheet = buildPaletteStylesheet(themeJson, appearanceTokens);
+  const paletteRelativePath = `${PALETTE_STYLESHEET_DIRECTORY}/${paletteSheet.fileName}`;
+  const paletteOutputPath = projectFixedAssetPath(
+    basePath,
+    `/${paletteRelativePath}`,
+  );
+  files.push({ path: paletteOutputPath, bytes: paletteSheet.bytes });
+  assets.push({
+    path: paletteOutputPath,
+    mediaType: PALETTE_STYLESHEET_MEDIA_TYPE,
+    byteLength: String(paletteSheet.bytes.byteLength),
+    sha256: digestBytes(paletteSheet.bytes),
+    immutable: false,
+  });
+  linkTags.push(
+    `<link rel="stylesheet" href="${escapeHtml(`/${projectFixedAssetPath(publicBasePath, `/${paletteRelativePath}`)}`)}" integrity="${subresourceIntegrityAttribute(paletteSheet.bytes)}" crossorigin="anonymous">`,
+  );
+
   // TPL-M2 fix: partition by the already-shape-validated `stylesheets` list
   // itself, not by comparing `asset.mediaType` against the literal string
   // `'text/css'` — a theme declaring its own stylesheet rows with the same