@rathnasgala2/template 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala2/template",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Deterministic Eleventy-backed static publication renderer for Galascribe portable repositories.",
   "type": "module",
   "license": "Apache-2.0",
@@ -25,12 +25,11 @@
     "contracts/",
     "types/",
     "LICENSE",
-    "NOTICE",
     "README.md"
   ],
   "engines": {
-    "node": "24.18.0",
-    "npm": "11.16.0"
+    "node": ">=24.0.0",
+    "npm": ">=11.0.0"
   },
   "devEngines": {
     "runtime": {
@@ -61,7 +60,7 @@
     "test": "node --test",
     "licenses:generate": "node scripts/generate-license-inventory.mjs",
     "licenses:check": "node scripts/generate-license-inventory.mjs --check",
-    "sbom:generate": "cyclonedx-npm --output-file sbom.cdx.json --output-format JSON --spec-version 1.6 && node scripts/apply-sbom-normalization.mjs",
+    "sbom:generate": "cyclonedx-npm --package-lock-only --output-file sbom.cdx.json --output-format JSON --spec-version 1.6 && node scripts/apply-sbom-normalization.mjs",
     "sbom:check": "node scripts/check-sbom-current.mjs",
     "workflows:check": "node scripts/check-workflow-pins.mjs",
     "workflows:drift": "node scripts/check-workflow-drift.mjs",

package/src/core/errors.js

@@ -4,7 +4,7 @@
  * bare `Error`, so a caller (eventually `publish-kernel`) can distinguish
  * "the supplied build input is not schema-valid" from "the caller's own
  * adapter options are incomplete or unsafe" without string-matching a
- * message (brief S2 section 3: "fails closed on invalid input").
+ * message: this renderer fails closed on invalid input.
  */
 
 /**
@@ -43,14 +43,14 @@ export class RenderOptionsError extends Error {
 }
 
 /**
- * The media pipeline (S2-T05) rejected an image or font reference: an
- * unrecognized or malformed format, a decompression or resource ceiling
- * crossing, an unconditionally-rejected SVG image input, a font that is not
- * bounded WOFF2, or a source file whose bytes do not match its declared
+ * The media pipeline rejected an image or font reference: an unrecognized or
+ * malformed format, a decompression or resource ceiling crossing, an
+ * unconditionally-rejected SVG image input, a font that is not bounded
+ * WOFF2, or a source file whose bytes do not match its declared
  * `build-input` digest. Every one of these fails closed — before any
  * derivative is written and before rendering completes — never as a warning
- * or silent fallback (brief S2 section 3: "Reject decompression or resource
- * excess"; "SVG is never processed as author media").
+ * or silent fallback: decompression or resource excess is always rejected,
+ * and SVG is never processed as author media.
  */
 export class MediaPipelineError extends Error {
   /**
@@ -78,8 +78,8 @@ export class MediaPipelineError extends Error {
  * byte-equal the published render-policy identity, a non-empty module or
  * placement value, or sanitized output that still matched a forbidden
  * pattern (an adapter defect, never expected of admitted content). Rendering
- * never completes for the affected build (brief S2 section 3: "fail-closed
- * behaviour on any content the policy rejects").
+ * never completes for the affected build: this renderer has fail-closed
+ * behaviour on any content the policy rejects.
  */
 export class RenderPolicyViolationError extends Error {
   /**
@@ -95,14 +95,14 @@ export class RenderPolicyViolationError extends Error {
  * The selected theme package's `theme.json` (or its declared file set) did
  * not conform to the closed shape `internal/theme-assets.js` needs to copy
  * its stylesheets/passive assets and render its `<link>` elements: an
- * invalid `stylesheets` list shape, a `cssLayers` projection that does not
- * byte-equal the corresponding ordered layer names, or a missing declared
- * file (task packet S2-T12).
+ * invalid `stylesheets` list shape, a schema/contract-integrity violation
+ * (which also covers an inadmissible `cssLayers` projection — see
+ * `urn:gala:schema:theme-contract:2.0.0`), or a missing declared file.
  */
 export class ThemeAssetError extends Error {
   /**
    * @param {string} reasonCode a stable, machine-checkable reason code (for
-   *   example `THEME_STYLESHEETS_INVALID`, `THEME_CSS_LAYERS_INVALID`)
+   *   example `THEME_STYLESHEETS_INVALID`, `THEME_CONTRACT_SCHEMA_INVALID`)
    * @param {string} message a human-readable description
    */
   constructor(reasonCode, message) {

package/src/core/index.js

@@ -1,11 +1,9 @@
 /**
  * `@rathnasgala2/template` public entry point.
  *
- * This is S2-T03's Eleventy-confined renderer adapter, extended by S2-T05's
- * media pipeline: it consumes one validated
+ * This is the Eleventy-confined renderer adapter: it consumes one validated
  * `urn:gala:schema:build-input:2.0.0` instance and emits a candidate output
- * directory plus one `urn:gala:schema:artifact-manifest:2.0.0` instance
- * (brief S2 section 3).
+ * directory plus one `urn:gala:schema:artifact-manifest:2.0.0` instance.
  *
  * `renderPublication` is the only documented *rendering* entry point. It
  * fails closed: an invalid `build-input` is rejected with
@@ -14,7 +12,7 @@
  * Eleventy ever runs, and a rejected image or font is rejected with
  * {@link MediaPipelineError} before the manifest is assembled.
  *
- * `normalizeAuthoredMarkdown` (re-exported here from S2-T04's
+ * `normalizeAuthoredMarkdown` (re-exported here from
  * `internal/content-security.js`) is this package's second public entry
  * point: the upstream normalization step a `build-input:2.0.0` producer
  * (`publish-kernel`/`publish-action`) calls once per authored Markdown
@@ -25,38 +23,36 @@
  * reaches this renderer, and how `renderPublication` verifies that instead
  * of re-deriving it.
  *
- * S2-T05 adds `options.sourceDirectory` (the caller-mounted, read-only
- * repository source tree `build-input`'s `resolvedFile` references point
- * into) and runs `processMedia` after the Eleventy route listing is already
- * computed, so generated derivative files under `assets/media/` are never
- * mistaken for an HTML route.
+ * `options.sourceDirectory` is the caller-mounted, read-only repository
+ * source tree `build-input`'s `resolvedFile` references point into.
+ * `processMedia` runs after the Eleventy route listing is already computed,
+ * so generated derivative files under `assets/media/` are never mistaken for
+ * an HTML route.
  *
- * Output-security (markdown/sanitizer/highlighter/CSP; S2-T04) and the media
- * pipeline (S2-T05) are layered on the same adapter. S2-T06 adds the core
- * semantic skeleton and navigation renderer (`internal/skeleton.js`) and
- * every generated page kind (`internal/page-kinds.js`): publication profile,
+ * Output-security (markdown/sanitizer/highlighter/CSP) and the media
+ * pipeline are layered on the same adapter, alongside the core semantic
+ * skeleton and navigation renderer (`internal/skeleton.js`) and every
+ * generated page kind (`internal/page-kinds.js`): publication profile,
  * author, article/page, index, tag, series and archive pages, each composed
- * with one shared header/primary-navigation/footer chrome and, where the
- * brief requires it, a breadcrumb trail. Feeds/search/sitemap remain
- * S2-T08. This adapter also emits every authored static redirect, shaped so
- * that later task extends the page-body pipeline without touching the
- * confinement, route-projection or manifest-assembly mechanics here.
+ * with one shared header/primary-navigation/footer chrome and, where
+ * required, a breadcrumb trail. This adapter also emits every authored
+ * static redirect and the feeds/search/sitemap outputs, shaped so that later
+ * work can extend the page-body pipeline without touching the confinement,
+ * route-projection or manifest-assembly mechanics here.
  *
- * S2-T07 adds the Light/Dark/System appearance controller
- * (`internal/appearance/`): the server-rendered control in the header's
- * `header-actions` slot (`controller-markup.js`), the one deterministic
- * pre-paint bootstrap script this renderer ever emits, written into the
- * candidate output directory and entered into the manifest as an ordinary
- * `manifestAsset` row exactly like an S2-T05 media derivative
- * (`bootstrap-script.js`), and the fixed `data-` attribute names, mode
- * values and storage key every one of those pieces shares
- * (`contract.js`) — the contract S2-T12's published theme styling catalog
+ * The Light/Dark/System appearance controller (`internal/appearance/`) adds:
+ * the server-rendered control in the header's `header-actions` slot
+ * (`controller-markup.js`), the one deterministic pre-paint bootstrap script
+ * this renderer ever emits, written into the candidate output directory and
+ * entered into the manifest as an ordinary `manifestAsset` row exactly like a
+ * media derivative (`bootstrap-script.js`), and the fixed `data-` attribute
+ * names, mode values and storage key every one of those pieces shares
+ * (`contract.js`) — the same contract the published theme styling catalog
  * targets.
  *
  * `src/core/` is the only admitted source root in this repository. No
  * `src/modules/` tree, module import edge, registration stub, module
  * configuration, module output or module runtime is ever added beside it
- * (brief S2 section 3; DEC-097 sections 2 and 5).
  */
 
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
@@ -70,6 +66,11 @@ import {
   appearanceBootstrapScriptHref,
 } from './internal/appearance/contract.js';
 import { APPEARANCE_BOOTSTRAP_SCRIPT_SOURCE } from './internal/appearance/bootstrap-script.js';
+import {
+  GALA_BASE_STYLESHEET_MEDIA_TYPE,
+  GALA_BASE_STYLESHEET_PATH,
+  GALA_BASE_STYLESHEET_SOURCE,
+} from './internal/appearance/base-layer.js';
 import { renderAppearanceControl } from './internal/appearance/controller-markup.js';
 import {
   ArtifactManifestValidationError,
@@ -151,7 +152,7 @@ export const TEMPLATE_PACKAGE_NAME = '@rathnasgala2/template';
  *
  * @type {string}
  */
-export const TEMPLATE_PACKAGE_VERSION = '2.0.0';
+export const TEMPLATE_PACKAGE_VERSION = '2.1.0';
 
 /**
  * Validate the caller-supplied render options, independent of build-input
@@ -180,10 +181,9 @@ function assertOptions(options) {
       throw new RenderOptionsError(`options.${key} must be an absolute path`);
     }
   }
-  // S2-T12: an optional caller-mounted, read-only extracted theme package
-  // directory (`internal/theme-assets.js`). Absent entirely by default
-  // (every pre-S2-T12 caller, including this repository's own test suite)
-  // so this addition is purely additive.
+  // An optional caller-mounted, read-only extracted theme package directory
+  // (`internal/theme-assets.js`). Absent entirely by default, so this
+  // addition is purely additive.
   if (options.themeDirectory !== undefined) {
     if (
       typeof options.themeDirectory !== 'string' ||
@@ -228,9 +228,9 @@ function assertOptions(options) {
  * render-policy identity, and that no module or placement value leaked
  * through (belt-and-suspenders on top of the `build-input:2.0.0` schema's
  * own `modules: {}` / `placements: []` closure). Fails closed before any
- * directory is created or Eleventy ever runs (DEC-097 section 5: "An absent
- * policy file, wrong path/name/version/digest, mixed identity between
- * records or body produced under a different policy rejects before build").
+ * directory is created or Eleventy ever runs: an absent policy file, wrong
+ * path/name/version/digest, mixed identity between records, or body
+ * produced under a different policy rejects before build.
  *
  * @param {import('../../types/index.d.ts').NormalizedBuildInput} validatedInput
  *   the schema-validated build input
@@ -320,7 +320,7 @@ export async function renderPublication(buildInput, options) {
   // `page.language` below); only the *chrome strings surrounding it* are
   // rendered in one consistent language, matching a reader's expectation
   // that navigation/footer text does not flip language from page to page
-  // (task packet S2-T06 scoped decision; see `internal/messages.js`).
+  // (see `internal/messages.js`).
   const siteMessages = getMessages(validatedInput.publication.defaultLanguage);
   const homeRoute = joinBasePathAndRoute(validatedInput.basePath, '/');
 
@@ -350,31 +350,38 @@ export async function renderPublication(buildInput, options) {
     messages: siteMessages,
   });
 
-  // Run before page assembly, not after (task packet S2-T08): resolving
-  // each page's own `og:image`/`twitter:image` needs the S2-T05 media
-  // pipeline's own finished `assets` list (only it knows which derivative
-  // file extension a given source image's `sourceDigest` produced — see
-  // `internal/seo.js`). This only moves the in-memory computation earlier;
-  // `mediaFiles`' actual bytes are still written to `outputDirectory` only
-  // after the route listing below (unchanged from S2-T05), so
-  // `outputDirectory/assets/media/` still can never be mistaken for an
-  // Eleventy-rendered HTML route.
+  // Run before page assembly, not after: resolving each page's own
+  // `og:image`/`twitter:image` needs the media pipeline's own finished
+  // `assets` list (only it knows which derivative file extension a given
+  // source image's `sourceDigest` produced — see `internal/seo.js`). This
+  // only moves the in-memory computation earlier; `mediaFiles`' actual
+  // bytes are still written to `outputDirectory` only after the route
+  // listing below, so `outputDirectory/assets/media/` still can never be
+  // mistaken for an Eleventy-rendered HTML route.
   const { assets: mediaAssets, files: mediaFiles } = await processMedia(
     validatedInput,
     { sourceDirectory: path.resolve(options.sourceDirectory) },
   );
 
-  // S2-T08: the site-wide feeds, resolved once so every page's feed-
-  // discovery `<link>` tags and the feed documents themselves agree on the
-  // exact same self URLs.
+  // The site-wide feeds, resolved once so every page's feed-discovery
+  // `<link>` tags and the feed documents themselves agree on the exact same
+  // self URLs.
   const feeds = buildFeeds(validatedInput);
   const siteName = validatedInput.publication.title;
   const appearanceScriptHrefValue = appearanceBootstrapScriptHref(
     validatedInput.basePath,
   );
+  // TPL-H3/TPL-M7: the template-owned gala-base stylesheet's own basePath-
+  // joined href, computed the same way as the appearance script href above
+  // so it can never drift from the physical file/manifest path written
+  // below.
+  const baseStylesheetHrefValue = `/${projectFixedAssetPath(
+    validatedInput.basePath,
+    `/${GALA_BASE_STYLESHEET_PATH}`,
+  )}`;
 
-  // S2-T12: the selected theme package's copied stylesheets/passive assets
-  // and the ordered `<link>` markup every generated page's `<head>` inserts.
+  // The selected theme package's copied stylesheets/passive assets and the
+  // ordered `<link>` markup every generated page's `<head>` inserts.
   // Run before page assembly (same reasoning as the media pipeline above):
   // every page's `data.themeStylesheetLinksHtml` needs the same one
   // already-rendered fragment.
@@ -438,6 +445,7 @@ export async function renderPublication(buildInput, options) {
         atomFeedUrl: feeds.atomSelfUrl,
         rssFeedUrl: feeds.rssSelfUrl,
         appearanceScriptHref: appearanceScriptHrefValue,
+        baseStylesheetHref: baseStylesheetHrefValue,
         themeStylesheetLinksHtml,
       },
     });
@@ -473,10 +481,10 @@ export async function renderPublication(buildInput, options) {
     );
   }
 
-  // S2-T08: the one ordinary generated `404.html` error page, using the
-  // S2-T06 `error` page kind's own pure body function. Pushed after the
-  // guard above so the guard's own "is there anything authored to render"
-  // check is unaffected by this always-present synthetic page.
+  // The one ordinary generated `404.html` error page, using the `error`
+  // page kind's own pure body function. Pushed after the guard above so the
+  // guard's own "is there anything authored to render" check is unaffected
+  // by this always-present synthetic page.
   const errorNavHtml = renderPrimaryNavigation({
     items: validatedInput.navigation.items,
     currentRoute: undefined,
@@ -509,11 +517,12 @@ export async function renderPublication(buildInput, options) {
       atomFeedUrl: feeds.atomSelfUrl,
       rssFeedUrl: feeds.rssSelfUrl,
       appearanceScriptHref: appearanceScriptHrefValue,
+      baseStylesheetHref: baseStylesheetHrefValue,
       themeStylesheetLinksHtml,
     },
   });
 
-  // S2-T08: feeds, sitemap and the static search index. Each is a fixed,
+  // Feeds, sitemap and the static search index. Each is a fixed,
   // literal-extension file — never route-normalized like an ordinary
   // content route (`internal/route.js#projectFixedAssetPath`) — and each
   // bypasses the shared HTML skeleton layout entirely (no `layout` field,
@@ -570,10 +579,9 @@ export async function renderPublication(buildInput, options) {
     outputDirectory,
   });
 
-  // S2-T08: the exact `routeClass`/`mediaType` this renderer's own generated
+  // The exact `routeClass`/`mediaType` this renderer's own generated
   // non-HTML routes carry, keyed by their fixed output path. Every other
-  // route defaults to `'html'`/`text/html; charset=utf-8`, unchanged from
-  // S2-T03.
+  // route defaults to `'html'`/`text/html; charset=utf-8`.
   /** @type {Map<string, {routeClass: import('../../types/index.d.ts').ManifestRouteEntry['routeClass'], mediaType: string}>} */
   const specialRoutes = new Map([
     [
@@ -663,8 +671,8 @@ export async function renderPublication(buildInput, options) {
     await writeFile(destination, file.bytes);
   }
 
-  // S2-T12: the selected theme package's stylesheet/passive-asset bytes,
-  // written for the same reason and at the same point as the media pipeline
+  // The selected theme package's stylesheet/passive-asset bytes, written
+  // for the same reason and at the same point as the media pipeline
   // output immediately above (`themeAssetsResult` is `undefined` when no
   // `options.themeDirectory` was supplied, in which case there is nothing to
   // write — the fallback `defaultThemeStylesheetLinksHtml` link above points
@@ -677,10 +685,10 @@ export async function renderPublication(buildInput, options) {
     }
   }
 
-  // S2-T07's one deterministic pre-paint appearance-controller bootstrap
-  // script (brief S2 section 3: "the appearance controller is the only
-  // browser bootstrap"). Written after the routes listing above for the same
-  // reason as the media pipeline output immediately above: it must never be
+  // The one deterministic pre-paint appearance-controller bootstrap script:
+  // the appearance controller is the only browser bootstrap this renderer
+  // ever emits. Written after the routes listing above for the same reason
+  // as the media pipeline output immediately above: it must never be
   // mistaken for an Eleventy-rendered HTML route. Its bytes are a pure
   // function of `internal/appearance/contract.js`'s own fixed constants, so
   // this asset row is identical on every build regardless of build input.
@@ -714,9 +722,36 @@ export async function renderPublication(buildInput, options) {
     immutable: false,
   };
 
+  // TPL-H3/TPL-M7: the template-owned gala-base stylesheet, written and
+  // manifested for the same reason and at the same point as the appearance
+  // bootstrap script immediately above. Always emitted, independent of
+  // whether a theme was selected (`baseStylesheetHrefValue` above is
+  // likewise unconditional), because it is what makes contract-mandated
+  // chrome presentable even with no theme at all.
+  const baseStylesheetBytes = Buffer.from(GALA_BASE_STYLESHEET_SOURCE, 'utf8');
+  const joinedBaseStylesheetPath = projectFixedAssetPath(
+    validatedInput.basePath,
+    `/${GALA_BASE_STYLESHEET_PATH}`,
+  );
+  const baseStylesheetDestination = path.join(
+    outputDirectory,
+    joinedBaseStylesheetPath,
+  );
+  await mkdir(path.dirname(baseStylesheetDestination), { recursive: true });
+  await writeFile(baseStylesheetDestination, baseStylesheetBytes);
+  /** @type {import('../../types/index.d.ts').ManifestAssetEntry} */
+  const baseStylesheetAsset = {
+    path: joinedBaseStylesheetPath,
+    mediaType: GALA_BASE_STYLESHEET_MEDIA_TYPE,
+    byteLength: String(baseStylesheetBytes.byteLength),
+    sha256: digestBytes(baseStylesheetBytes),
+    immutable: false,
+  };
+
   const assets = [
     ...joinedMediaAssets,
     appearanceScriptAsset,
+    baseStylesheetAsset,
     ...(themeAssetsResult ? themeAssetsResult.assets : []),
   ].sort((a, b) => compareUtf8Bytes(a.path, b.path));
 
@@ -754,5 +789,6 @@ export {
 
 export {
   computeBodyDigest,
+  computeRenderPolicyIdentity,
   normalizeAuthoredMarkdown,
 } from './internal/content-security.js';

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

@@ -0,0 +1,180 @@
+/**
+ * The template-owned `gala-base` cascade layer (TPL-H3/TPL-M7): a
+ * stylesheet this renderer itself writes on every build, independent of
+ * whether a theme is selected, carrying sane defaults for every
+ * contract-mandated chrome element (`internal/skeleton.js`'s skip link,
+ * headings, code/table overflow, image sizing, responsive spacing) plus the
+ * one rule that makes the closed token catalog's
+ * `color-focus`/`focus-width` tokens actually paint a ring (THD-H1): a real
+ * `outline-style: solid` under `:focus-visible`.
+ *
+ * This file is not admitted through, or generated from, the theme package
+ * pipeline in `internal/theme-assets.js` — it is not subject to
+ * `check-css-hooks.mjs`'s closed selector-admission grammar and may use any
+ * selector, property or pseudo-class, including `:focus-visible`,
+ * `html`/`body` and functional colors, because it is authored by the
+ * template, not by a theme. Its bytes are a pure function of this module's
+ * own literal source, not of any per-publication or per-theme input, so a
+ * fixed, non-content-addressed output path carries no collision risk
+ * (mirrors `internal/appearance/bootstrap-script.js`'s own reasoning for its
+ * fixed path).
+ *
+ * Every custom property this file reads (`--gala-*`) is read through a
+ * fallback value, since a theme is optional (`internal/theme-assets.js`'s
+ * `defaultThemeStylesheetLinksHtml` fallback path never defines any
+ * `--gala-*` property at all) — this layer must still produce a sane,
+ * legible default with no theme selected whatsoever.
+ *
+ * Cascade-layer precedence (TPL-M7): this layer's own declarations always
+ * lose to a theme's `gala-tokens`/`gala-components`/`gala-utilities` layer
+ * declarations for the same property on the same element, because this
+ * stylesheet's own first line is the fixed `@layer gala-base, gala-tokens,
+ * gala-components, gala-utilities, gala-print;` order statement — layer
+ * order is declared once, explicitly, independent of `<link>` emission
+ * order, and independent of which optional stylesheets a theme ships (a
+ * theme that omits `utilities.css` never populates `gala-utilities`, which
+ * is harmless: an empty layer in a declared order does nothing). A bare
+ * `@layer name, name, ...;` statement is not itself a style rule, so it
+ * needs no `'unsafe-inline'`/nonce/hash exemption from the
+ * `style-src 'self'` CSP baseline the way an inline `<style>` element would
+ * (TPL-H4): it ships as the first bytes of this external, same-origin
+ * stylesheet, and `internal/eleventy-render.js` always emits this
+ * stylesheet's own `<link>` before every theme stylesheet `<link>`.
+ */
+
+import { ORDERED_LAYERS } from './styling-contract.js';
+
+/** @type {string} the candidate-output-directory-relative path this
+ * stylesheet is always written to (never content-addressed; see module
+ * documentation). */
+export const GALA_BASE_STYLESHEET_PATH = 'assets/gala-base-v1.css';
+
+/** @type {string} the `manifestAsset`/`manifestRoute` `mediaType` for this
+ * stylesheet. */
+export const GALA_BASE_STYLESHEET_MEDIA_TYPE = 'text/css; charset=utf-8';
+
+/**
+ * The exact `gala-base` layer source, byte-for-byte deterministic across
+ * builds (no interpolated per-build value of any kind). Its first line is
+ * the fixed layer-order statement every published page relies on (see
+ * module documentation).
+ *
+ * @type {string}
+ */
+export const GALA_BASE_STYLESHEET_SOURCE = `@layer ${ORDERED_LAYERS.join(', ')};
+
+@layer gala-base {
+  [data-gala-publication-root] {
+    box-sizing: border-box;
+  }
+  [data-gala-publication-root] *,
+  [data-gala-publication-root] *::before,
+  [data-gala-publication-root] *::after {
+    box-sizing: inherit;
+  }
+
+  /* Skip link: the first focusable element on every page, visually hidden
+     until it receives keyboard focus, so it is announced and reachable by
+     assistive technology and keyboard users without being the first visible
+     line of every published page. */
+  [data-gala-publication-root] a[href="#main-content"] {
+    position: absolute;
+    top: -9999px;
+    left: 0;
+    z-index: 9999;
+    padding: var(--gala-space-2, 0.5rem) var(--gala-space-4, 1rem);
+    background-color: var(--gala-color-surface, Canvas);
+    color: var(--gala-color-text, CanvasText);
+  }
+  [data-gala-publication-root] a[href="#main-content"]:focus-visible {
+    top: 0;
+  }
+
+  /* The one rule that makes the closed token catalog's color-focus/
+     focus-width tokens actually paint a ring: outline-style is never set by
+     the token catalog alone (outline-color/outline-width longhands paint
+     nothing without it), and this layer's own low cascade precedence means
+     any theme-declared outline-color/outline-width in gala-components still
+     wins for the same element. */
+  [data-gala-publication-root] :focus-visible {
+    outline-style: solid;
+    outline-width: var(--gala-focus-width, 2px);
+    outline-color: var(--gala-color-focus, Highlight);
+    outline-offset: 2px;
+  }
+
+  /* Type scale, expressed with clamp() so it scales between a phone and a
+     desktop viewport without a discrete breakpoint; no theme sets this. */
+  [data-gala-publication-root] h1 {
+    font-size: clamp(1.75rem, 1.4rem + 1.5vw, 2.5rem);
+    line-height: 1.2;
+  }
+  [data-gala-publication-root] h2 {
+    font-size: clamp(1.375rem, 1.2rem + 0.8vw, 1.875rem);
+    line-height: 1.25;
+  }
+  [data-gala-publication-root] h3 {
+    font-size: clamp(1.125rem, 1.05rem + 0.4vw, 1.375rem);
+    line-height: 1.3;
+  }
+  [data-gala-publication-root] h4,
+  [data-gala-publication-root] h5,
+  [data-gala-publication-root] h6 {
+    font-size: clamp(1rem, 0.96rem + 0.2vw, 1.125rem);
+    line-height: 1.35;
+  }
+  [data-gala-publication-root] p,
+  [data-gala-publication-root] li {
+    font-size: 1rem;
+    line-height: 1.6;
+  }
+  [data-gala-publication-root] code,
+  [data-gala-publication-root] pre {
+    /* Corrects the monospace optical-size mismatch against surrounding
+       proportional text at the same nominal font-size. */
+    font-size: 0.9em;
+  }
+
+  /* Overflow/wrap containment: constrains a fenced code block or an
+     unbroken long token in prose to the viewport, never the whole page. */
+  [data-gala-publication-root] pre {
+    overflow-x: auto;
+  }
+  [data-gala-publication-root] article {
+    overflow-wrap: anywhere;
+  }
+  [data-gala-publication-root] img {
+    max-width: 100%;
+    height: auto;
+  }
+
+  /* Responsive spacing: a small step at a tablet-and-up viewport width, so
+     header/main padding is not identical at 320px and 2560px. */
+  [data-gala-publication-root] header,
+  [data-gala-publication-root] footer {
+    padding: var(--gala-space-4, 1rem) var(--gala-space-4, 1rem);
+  }
+  [data-gala-publication-root] main {
+    padding: var(--gala-space-4, 1rem);
+  }
+  @media (min-width: 48rem) {
+    [data-gala-publication-root] header,
+    [data-gala-publication-root] footer {
+      padding: var(--gala-space-4, 1rem) var(--gala-space-6, 1.5rem);
+    }
+    [data-gala-publication-root] main {
+      padding: var(--gala-space-6, 1.5rem);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-gala-publication-root] *,
+    [data-gala-publication-root] *::before,
+    [data-gala-publication-root] *::after {
+      animation-duration: 0.001ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.001ms !important;
+    }
+  }
+}
+`;

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

@@ -1,15 +1,15 @@
 /**
- * The exact deterministic pre-paint appearance bootstrap script (brief S2
- * section 3: "a versioned deterministic pre-paint bootstrap owned by
- * `template`/`core` resolves local selection plus system preference and sets
+ * The exact deterministic pre-paint appearance bootstrap script: a versioned
+ * deterministic pre-paint bootstrap owned by `template`/`core` that resolves
+ * local selection plus system preference and sets
  * the root state before first themed paint. It is covered by the artifact
  * digest, is CSP-compatible under `script-src 'self'` (therefore an external
  * file, not inline), touches no network, account, content or unrelated
- * storage key, and cannot hide the document indefinitely").
+ * storage key, and cannot hide the document indefinitely.
  *
- * This is the one and only browser bootstrap S2 ever emits ("Module absence
- * and CSP equality": "the appearance controller is the only browser
- * bootstrap"). Every name and value it embeds is read from
+ * This is the one and only browser bootstrap this renderer ever emits: the
+ * appearance controller is the only browser
+ * bootstrap it ships. Every name and value it embeds is read from
  * `internal/appearance/contract.js`, the one module that owns them, so the
  * server-rendered control markup and this script can never drift apart on a
  * literal.
@@ -29,12 +29,12 @@
  *    any earlier: the control has not been parsed yet at phase 1's own
  *    execution point) and subscribes to live `prefers-color-scheme` changes,
  *    updating the resolved attribute only while the current selection is
- *    exactly `system` (brief: "an explicit `light`/`dark` choice is not
- *    overridden by later system changes").
+ *    exactly `system`: an explicit `light`/`dark` choice is not
+ *    overridden by later system changes.
  *
  * Deliberately absent: no `document.documentElement.style` mutation of any
- * kind (in particular, no hide-until-ready visibility toggle — brief:
- * "cannot hide the document indefinitely" — this script never needs one,
+ * kind (in particular, no hide-until-ready visibility toggle — this script
+ * must never hide the document indefinitely, and never needs to,
  * since it only ever sets attributes, never inline style), no network
  * request, no cookie, no account/tracking identifier, no storage key other
  * than {@link APPEARANCE_STORAGE_KEY}.