@rathnasgala2/template 2.0.0 → 2.1.0

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

@@ -1,32 +1,32 @@
 /**
- * The single module `contracts/theme-styling-contract.jcs` (S2-T12) targets
- * for every Light/Dark/System appearance name this renderer owns (task
- * packet S2-T07: "the `data-` attribute/class names the controller sets must
- * be fixed constants exported from one module"; DEC-097's closed
- * `templateStylingContract` catalog, section "Closed theme-package and
- * stylesheet admission": the required root attribute row
+ * The single module `contracts/theme-styling-contract.jcs` targets for
+ * every Light/Dark/System appearance name this renderer owns: the
+ * `data-` attribute/class names the controller sets must be fixed
+ * constants exported from one module. The published
+ * `templateStylingContract` catalog's closed theme-package and stylesheet
+ * admission requires the root attribute row
  * `{name:data-gala-publication-root,match:presence,values:[],role:root}` and
- * the required palette attribute row
- * `{name:data-gala-resolved-color-mode,match:exact-value,values:[dark,light],role:state}`;
- * "The template renderer emits the exact root attribute and maintains
+ * the palette attribute row
+ * `{name:data-gala-resolved-color-mode,match:exact-value,values:[dark,light],role:state}`:
+ * the template renderer emits the exact root attribute and maintains
  * exactly one `data-gala-resolved-color-mode="light"|"dark"` value on that
- * same element before theme CSS is observed").
+ * same element before theme CSS is observed.
  *
- * Two attributes are exposed, deliberately kept separate (brief S2 section 3:
- * "selection and resolved state are exposed separately through
- * template-owned root attributes; theme CSS consumes only resolved state"):
+ * Two attributes are exposed, deliberately kept separate: selection and
+ * resolved state are exposed separately through template-owned root
+ * attributes; theme CSS consumes only resolved state.
  *
  * - {@link APPEARANCE_ROOT_ATTRIBUTE} and {@link APPEARANCE_RESOLVED_MODE_ATTRIBUTE}
- *   are the two DEC-097-fixed theme-facing attributes above — part of the
- *   published styling contract S2-T12 emits, never renamed here independent
- *   of that contract.
+ *   are the two fixed theme-facing attributes above — part of the published
+ *   styling contract, never renamed here independent of that contract.
  * - {@link APPEARANCE_SELECTION_ATTRIBUTE} is this renderer's own
  *   template-internal bookkeeping attribute (the reader's raw `light` /
  *   `dark` / `system` choice, as opposed to `system`'s *resolved* value). It
- *   is not a theme-styling-contract hook — DEC-097's attribute catalog does
- *   not name it, and no theme selector may target it — but its name is still
- *   fixed here, in this one module, exactly like the two contract-owned
- *   attributes, so no other module ever invents its own literal for it.
+ *   is not a theme-styling-contract hook — the published attribute catalog
+ *   does not name it, and no theme selector may target it — but its name is
+ *   still fixed here, in this one module, exactly like the two
+ *   contract-owned attributes, so no other module ever invents its own
+ *   literal for it.
  *
  * Both the pre-paint bootstrap script ({@link ../appearance/bootstrap-script.js})
  * and the server-rendered control markup ({@link ../appearance/controller-markup.js})
@@ -37,7 +37,7 @@
 import { joinBasePathAndRoute } from '../route.js';
 
 /**
- * The DEC-097 `templateStylingContract.publicationRootSelector` attribute:
+ * The `templateStylingContract.publicationRootSelector` attribute:
  * a bare-presence attribute the template always renders on the document's
  * root element (`<html>`), independent of JavaScript (`match:presence`).
  *
@@ -46,7 +46,7 @@ import { joinBasePathAndRoute } from '../route.js';
 export const APPEARANCE_ROOT_ATTRIBUTE = 'data-gala-publication-root';
 
 /**
- * The DEC-097 `templateStylingContract.resolvedPaletteSelectors` attribute:
+ * The `templateStylingContract.resolvedPaletteSelectors` attribute:
  * an exact-value attribute (`"light"` or `"dark"`, never `"system"`) the
  * pre-paint bootstrap script sets on the root element before first themed
  * paint. Theme CSS consumes only this attribute, never
@@ -75,9 +75,8 @@ export const APPEARANCE_MODE_DARK = 'dark';
 export const APPEARANCE_MODE_SYSTEM = 'system';
 
 /**
- * Every canonical machine-readable selection value (brief S2 section 3:
- * "canonical machine values are `light`, `dark`, `system`; `lite` is not a
- * value").
+ * Every canonical machine-readable selection value: `light`, `dark`,
+ * `system`; `lite` is not a value.
  *
  * @type {readonly ['light', 'dark', 'system']}
  */
@@ -89,9 +88,9 @@ export const APPEARANCE_MODE_VALUES = Object.freeze([
 
 /**
  * Every value {@link APPEARANCE_RESOLVED_MODE_ATTRIBUTE} may carry. `system`
- * always resolves to one of these two; it is never a third selector value
- * (DEC-097: "`system` is resolved to one of those values rather than
- * becoming a third selector").
+ * always resolves to one of these two; it is never a third selector value —
+ * `system` is resolved to one of those values rather than becoming a third
+ * selector.
  *
  * @type {readonly ['light', 'dark']}
  */
@@ -101,8 +100,25 @@ export const APPEARANCE_RESOLVED_MODE_VALUES = Object.freeze([
 ]);
 
 /**
- * The initial reader default (brief S2 section 3: "initial reader default is
- * `system`").
+ * TPL-C1 fix: the server-rendered default for
+ * {@link APPEARANCE_RESOLVED_MODE_ATTRIBUTE} on `<html>`, present on every
+ * page independent of JavaScript (`internal/eleventy-render.js`'s
+ * `SKELETON_LAYOUT_SOURCE`). `light` is chosen because it is the value the
+ * bootstrap script's own `resolveMode` already falls back to when
+ * `prefers-color-scheme` cannot be read (`internal/appearance/
+ * bootstrap-script.js`'s `systemPrefersDark` catch branch), so the
+ * server-rendered default and the script's own no-signal fallback agree.
+ * The bootstrap script's phase 1 always overwrites this attribute
+ * synchronously before first paint for a reader whose browser runs it, so
+ * this default is observed only by a reader (or crawler) that never runs
+ * script at all.
+ *
+ * @type {'light'}
+ */
+export const APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE = APPEARANCE_MODE_LIGHT;
+
+/**
+ * The initial reader default is `system`.
  *
  * @type {'system'}
  */
@@ -110,9 +126,9 @@ export const APPEARANCE_DEFAULT_MODE = APPEARANCE_MODE_SYSTEM;
 
 /**
  * The one versioned local-storage key the pre-paint bootstrap script and the
- * control's change handler both read/write (brief S2 section 3: "selection
- * is stored under one versioned local key"). The trailing `v1` is this
- * key's own version; a future incompatible storage format change mints a new
+ * control's change handler both read/write. Selection is stored under one
+ * versioned local key. The trailing `v1` is this key's own version; a
+ * future incompatible storage format change mints a new
  * key rather than reinterpreting old values, so an old browser's already
  * stored `v1` value is simply orphaned (ignored, never migrated or deleted)
  * rather than misread as a new format.
@@ -133,10 +149,10 @@ export const APPEARANCE_SELECT_ID = 'gala-appearance-color-mode';
 
 /**
  * The candidate-output-directory-relative path the deterministic pre-paint
- * bootstrap script is written to (task packet S2-T07: "entered into the
- * manifest through the S2-T03 path with `{path,byteLength,sha256}`"). Not
- * content-addressed (unlike the S2-T05 media pipeline's derivative paths):
- * this file's bytes are a pure function of this module's own constants, not
+ * bootstrap script is written to, entered into the manifest as an ordinary
+ * `{path,byteLength,sha256}` asset row. Not content-addressed (unlike the
+ * media pipeline's derivative paths): this file's bytes are a pure
+ * function of this module's own constants, not
  * of any per-publication input, so a stable path carries no collision risk.
  * The `v1` component versions the bootstrap script's own behaviour,
  * independent of {@link APPEARANCE_STORAGE_KEY}'s own versioning.
@@ -150,9 +166,9 @@ export const APPEARANCE_BOOTSTRAP_SCRIPT_PATH =
  * The root-absolute `<script src>` reference for a root (`/`) `basePath`
  * publication. Every actual render joins this with the publication's own
  * `basePath` through {@link appearanceBootstrapScriptHref} instead of using
- * this literal directly (S2-T12 basePath fix, LOCAL-7 follow-up: an earlier
- * version of this module used this root-absolute literal unconditionally,
- * which 404s under a non-root `basePath` publication). This constant is
+ * this literal directly (basePath fix: an earlier version of this module
+ * used this root-absolute literal unconditionally, which 404s under a
+ * non-root `basePath` publication). This constant is
  * retained as the one-place root-`basePath` literal every test and the
  * `joinBasePathAndRoute` call below both agree on.
  *
@@ -162,7 +178,7 @@ export const APPEARANCE_BOOTSTRAP_SCRIPT_HREF = `/${APPEARANCE_BOOTSTRAP_SCRIPT_
 
 /**
  * The `basePath`-joined `<script src>` reference every generated page's
- * skeleton layout actually uses (S2-T12 basePath fix).
+ * skeleton layout actually uses.
  *
  * @param {string} basePath the build input's `basePath`
  * @returns {string} the joined `href`
@@ -184,9 +200,8 @@ export const APPEARANCE_BOOTSTRAP_SCRIPT_MEDIA_TYPE =
  * The `<meta name="color-scheme">` content value: both palettes are
  * admitted, so the browser's own user-agent styling (form controls,
  * scrollbars) and initial paint follow `prefers-color-scheme` immediately,
- * independent of this renderer's own resolved-mode attribute (brief S2
- * section 3: "`color-scheme` meta/CSS handling"; "with JavaScript disabled,
- * CSS media queries preserve `system`").
+ * independent of this renderer's own resolved-mode attribute — with
+ * JavaScript disabled, CSS media queries preserve `system`.
  *
  * @type {string}
  */

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

@@ -1,11 +1,10 @@
 /**
- * The server-rendered Light/Dark/System appearance control (task packet
- * S2-T07: "the three-mode appearance control in the header-actions slot";
- * brief S2 section 3: "the control is a native `select`, a radio group, or a
- * conforming menu/radio pattern. A three-state unlabeled icon cycle is
- * rejected").
+ * The server-rendered Light/Dark/System appearance control, placed in the
+ * header-actions slot. The control must be a native `select`, a radio
+ * group, or a conforming menu/radio pattern; a three-state unlabeled icon
+ * cycle is rejected.
  *
- * Scoped decision (documented, not silently assumed): of the brief's three
+ * Scoped decision (documented, not silently assumed): of those three
  * admitted patterns, this module implements a native `<select>` bound to a
  * visible, programmatically associated `<label>`. A native select needs no
  * `aria-pressed`/`aria-checked` bookkeeping of its own — its accessible
@@ -19,8 +18,8 @@
  * `DOMContentLoaded` phase once it runs (see `bootstrap-script.js`), so this
  * server-rendered default is only ever visible for the brief instant before
  * that phase completes, or permanently with JavaScript disabled — exactly
- * the no-JS fallback the brief requires ("with JavaScript disabled, ...
- * `system` [is preserved]").
+ * the required no-JS fallback: with JavaScript disabled, `system` is
+ * preserved.
  *
  * This markup carries no inline `on*` handler and no `javascript:` URL, so
  * it needs no CSP allowance beyond the renderer's existing

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

@@ -1,26 +1,26 @@
 /**
- * `contracts/theme-styling-contract.jcs` builder and structural validator
- * (task packet S2-T12; DEC-097 section 4 "Closed theme-package and
- * stylesheet admission": the `templateStylingContract` closed object).
+ * `contracts/theme-styling-contract.jcs` builder and structural validator:
+ * the `templateStylingContract` closed object governing closed
+ * theme-package and stylesheet admission.
  *
  * This is the one reviewed source module `scripts/generate-contracts.mjs`
  * reads from to emit the published contract file, and the one module
  * `test/theme-styling-contract.test.js` reads from to drift-check the
  * contract against what this renderer actually renders. Every catalog leaf
- * below is drawn from (or, for the two new S2-T12 hooks documented inline,
+ * below is drawn from (or, for the two hooks documented inline,
  * wired into) the actual rendering modules — `internal/skeleton.js`,
  * `internal/page-kinds.js`, `internal/render-policy-content.js` and
  * `internal/appearance/contract.js` — never a hand-typed literal
  * independent of what those modules emit.
  *
- * Public-hook budget (DEC-097: `publicThemeSlotHooks:[1..64] set`): every
- * catalog leaf below (28 type + 15 class + 2 id + 19 attribute-value) has
- * exactly one corresponding public hook, for exactly 64 entries — this
- * renderer's complete public theming surface for S2. A leaf with no
- * matching hook would be a catalog member no theme could ever validly
- * select (DEC-097: "a used-but-undeclared public slot hook rejects"), so
- * catalogs and hooks are generated from one shared list rather than two
- * independently maintained ones.
+ * Public-hook budget (`publicThemeSlotHooks` is a `[1..64]`-entry set):
+ * every catalog leaf below (28 type + 15 class + 2 id + 19 attribute-value)
+ * has exactly one corresponding public hook, for exactly 64 entries — this
+ * renderer's complete public theming surface. A leaf with no matching hook
+ * would be a catalog member no theme could ever validly select (a
+ * used-but-undeclared public slot hook rejects), so catalogs and hooks are
+ * generated from one shared list rather than two independently maintained
+ * ones.
  *
  * Deliberately out of the S2 public hook surface (documented scope
  * decisions, not omissions):
@@ -29,19 +29,41 @@
  *   `.language-<grammar>` class are public, so a theme can style a
  *   highlighted code block's overall presentation but not recolor
  *   individual token kinds in S2;
- * - `html`/`body` type selectors and interactive pseudo-classes
- *   (`:hover`, `:focus`, `:visited`, ...): themes reach the document root
- *   only through {@link PUBLICATION_ROOT_SELECTOR}/
- *   {@link RESOLVED_PALETTE_SELECTORS}, and no pseudo-class hook is
- *   published in S2 (an empty `pseudoClasses` catalog is schema-valid: `[0..64]`).
+ * - `html`/`body` type selectors: themes reach the document root only
+ *   through {@link PUBLICATION_ROOT_SELECTOR}/{@link RESOLVED_PALETTE_SELECTORS}.
+ *
+ * Iconography (TPL-H6 decision, recorded here rather than left as an
+ * accident of theme authorship): **in scope, and expected.** Nothing in this
+ * contract restricts it — `::before`/`::after` are public pseudo-elements, a
+ * theme package may declare non-CSS passive assets (`theme.json.assets[]`),
+ * and a package-relative `url()` is permitted in theme CSS (only an
+ * external-origin `url()` is a theme-tooling lint concern, not a template
+ * restriction). The only reason no theme shipped an icon before this
+ * decision was recorded is that the prerequisite — safe admission of a
+ * theme-declared SVG — did not exist yet. It does now:
+ * `internal/media/theme-svg-sanitizer.js`, wired into
+ * `internal/theme-assets.js`'s passive-asset pipeline (TPL-C2), is the
+ * mechanism that makes shipping an SVG icon mark safe. A theme is free to
+ * declare one and reference it from `::before`/`::after` `content: url(...)`
+ * or a `background-image`.
+ *
+ * Contract 2.1.0 (TPL-H2/TPL-H3/TPL-M7 fix): S2.0's empty `pseudoClasses`
+ * catalog made every interaction state unstylable while the closed 35-token
+ * catalog already required `color-focus` and `color-link-visited`, tokens
+ * only a pseudo-class can ever apply. {@link PSEUDO_CLASSES} publishes a
+ * small closed catalog instead of widening indefinitely; the module
+ * documentation on that constant records why each member is admitted and
+ * why the set stops there. This is a template-owned, backward-compatible
+ * *contract* addition (a theme still validates if it uses none of these), so
+ * it ships as a minor bump: 2.0.0 -> 2.1.0.
  *
  * Every tag in `internal/render-policy-content.js`'s `ALLOWED_TAGS` that
  * markdown-it's own CommonMark grammar (with `html:false`) never actually
  * produces — `b`, `i`, `u`, `s`, `del`, `ins`, `sub`, `sup`, `mark`, `small`,
  * `wbr`, `table`, `thead`, `tbody`, `tr`, `th`, `td`, `dl`, `dt`, `dd`,
  * `figure`, `figcaption` — is likewise excluded from `typeSelectors`: this
- * catalog is "every hook the template actually renders" (task packet
- * S2-T12), not the sanitizer's own defence-in-depth superset.
+ * catalog is every hook the template actually renders, not the sanitizer's
+ * own defence-in-depth superset.
  */
 
 import { HIGHLIGHT_GRAMMARS } from '../render-policy-content.js';
@@ -57,15 +79,85 @@ import { canonicalizeJcs, domainDigest } from '../canonical-jcs.js';
 /** @type {string} */
 export const TEMPLATE_STYLING_CONTRACT_PACKAGE = '@rathnasgala2/template';
 /** @type {string} */
-export const TEMPLATE_STYLING_CONTRACT_VERSION = '2.0.0';
+export const TEMPLATE_STYLING_CONTRACT_VERSION = '2.1.0';
 /** @type {string} */
-export const TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION = '2.0.0';
+export const TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION = '2.1.0';
 
 /** @type {string} the `main-content` landmark's fixed `id`. */
 const MAIN_CONTENT_ID = 'main-content';
 
-/** @type {readonly string[]} the ordered `@layer` names DEC-097 fixes. */
+/**
+ * The closed pseudo-class catalog (contract 2.1.0, TPL-H2 fix). Each member
+ * is admitted for a specific, already-published reason — this is a closed
+ * list, not a starting point:
+ *
+ * - `hover`: pointer affordance on links and the appearance control; the
+ *   only way any theme can differentiate a hovered interactive element.
+ * - `focus-visible`: the keyboard/assistive-technology focus indicator
+ *   (WCAG 2.2 SC 2.4.11/2.4.13 are about this indicator specifically).
+ *   `:focus` is deliberately *not* admitted instead: `:focus-visible` is
+ *   what lets a theme paint a ring for keyboard focus without also painting
+ *   one on every mouse click, which is why `internal/appearance/
+ *   base-layer.js`'s own template-owned default ring (unconstrained by this
+ *   catalog) uses it too.
+ * - `active`: pressed-state affordance, the pointer-down counterpart to
+ *   `hover`.
+ * - `visited`: the only way to consume the closed token catalog's own
+ *   `color-link-visited`, which had no reachable application before this.
+ * - `disabled`: the appearance `<select>` is a native form control, which
+ *   may legitimately be disabled by a later module; themes need a way to
+ *   style that state today so it is not a breaking addition later.
+ *
+ * Deliberately still excluded: `:target`, `:checked`, `:required`,
+ * `:invalid` and every other state this renderer's own markup can never
+ * produce (no form beyond the one native `<select>`, no fragment-target
+ * styling contract) — the same "every leaf has a matching hook" discipline
+ * {@link ALL_HOOKS} documents above applies to pseudo-classes too: a
+ * catalog member with nothing that can ever be in that state is a
+ * specification defect, not a convenience.
+ *
+ * @type {readonly string[]}
+ */
+export const PSEUDO_CLASSES = Object.freeze(
+  ['active', 'disabled', 'focus-visible', 'hover', 'visited'].sort(),
+);
+
+/**
+ * Contract 2.1.0 (TPL-H2 fix, alongside {@link PSEUDO_CLASSES}): the
+ * `nth-child`/`nth-last-child` functional pseudo-classes were already
+ * admitted (see `functionalPseudos` below) but only under
+ * `nthExpressionProfile: 'gala-positive-an-plus-b-v2'`, an arithmetic
+ * `an+b` grammar with no keyword form — so a theme could not express the
+ * conventional "every other row" zebra-striping pattern without a
+ * (legal but obscure) `2n`/`2n+1` expression. This publishes the two
+ * keyword arguments as an explicit, closed extension of that same
+ * profile, admitted only as the sole argument to `nth-child`/
+ * `nth-last-child`.
+ *
+ * @type {readonly string[]}
+ */
+export const FUNCTIONAL_PSEUDO_KEYWORD_ARGUMENTS = Object.freeze([
+  'even',
+  'odd',
+]);
+
+/**
+ * TPL-H3/TPL-M7: the ordered `@layer` names this renderer fixes, including
+ * the template-owned `gala-base` layer as the first (lowest-precedence)
+ * entry. `gala-base` is emitted by this renderer itself, never by a theme
+ * package (no `theme.json.cssLayers` entry ever names it —
+ * `urn:gala:schema:theme-contract:2.0.0` only ever admits a theme's own
+ * four-or-five-stylesheet subsequence of the layers *after* it), so it
+ * stays first in this list unconditionally: cascade-layer
+ * precedence is later-wins, and a theme's own `gala-tokens`/`gala-components`/
+ * `gala-utilities` declarations must always be able to override the
+ * template's own base defaults (its focus ring, its type scale, ...),
+ * never the reverse.
+ *
+ * @type {readonly string[]}
+ */
 export const ORDERED_LAYERS = Object.freeze([
+  'gala-base',
   'gala-tokens',
   'gala-components',
   'gala-utilities',
@@ -222,9 +314,9 @@ function sortedUniqueBytes(values) {
 
 /**
  * Build the complete `templateStylingContract` object, including
- * `catalogDigest` (DEC-097 section 8:
+ * `catalogDigest`:
  * `SHA256(UTF8("GALA-TEMPLATE-STYLING-CONTRACT-V2\0") || JCS(the catalog
- * with catalogDigest omitted))`).
+ * with catalogDigest omitted))`.
  *
  * @returns {Record<string, unknown>} the complete, digested contract object
  */
@@ -294,7 +386,7 @@ export function buildTemplateStylingContract() {
       ID_HOOKS.map((hook) => hook.selectorAtom.replace(/^#/, '')),
     ),
     attributes: attributesRows,
-    pseudoClasses: [],
+    pseudoClasses: [...PSEUDO_CLASSES],
     pseudoElements: ['after', 'before', 'marker', 'selection'],
     functionalPseudos: ['is', 'where', 'not', 'nth-child', 'nth-last-child'],
     combinators: [' ', ' > ', ' + ', ' ~ '],
@@ -312,6 +404,9 @@ export function buildTemplateStylingContract() {
       functionalSelectorArguments: 'compound-only',
       maximumFunctionalDepth: 1,
       nthExpressionProfile: 'gala-positive-an-plus-b-v2',
+      functionalPseudoKeywordArguments: [
+        ...FUNCTIONAL_PSEUDO_KEYWORD_ARGUMENTS,
+      ],
     },
   };
 
@@ -353,9 +448,9 @@ export const TEMPLATE_STYLING_CONTRACT_INVALID =
 
 /**
  * Structural self-validation of a `templateStylingContract` object against
- * DEC-097 section 4's closed shape (the checks this repository can run
+ * its closed shape (the checks this repository can run
  * without a published `urn:gala:schema:template-styling-contract` schema
- * entry — no such schema ID is registered in `@rathnasgala2/schemas@2.8.0`;
+ * entry — no such schema ID is registered in `@rathnasgala2/schemas@2.11.0`;
  * only `urn:gala:schema:theme-contract:2.0.0` is, which this module's sibling
  * theme fixtures are validated against with the schema package's own
  * exported `validateGalaDocument`, see `test/theme-styling-contract.test.js`).
@@ -375,7 +470,7 @@ export function assertTemplateStylingContractShape(contract) {
   if (contract.profile !== 'gala-template-styling-contract-v2') {
     fail('profile');
   }
-  if (contract.contractVersion !== '2.0.0') fail('contractVersion');
+  if (contract.contractVersion !== '2.1.0') fail('contractVersion');
   if (contract.templatePackage !== '@rathnasgala2/template') {
     fail('templatePackage');
   }
@@ -438,6 +533,12 @@ export function assertTemplateStylingContractShape(contract) {
   if (rootRows.length !== 1) fail('root attribute row');
   if (paletteRows.length !== 1) fail('palette attribute row');
 
+  if (
+    JSON.stringify(contract.pseudoClasses) !==
+    JSON.stringify([...PSEUDO_CLASSES])
+  ) {
+    fail('pseudoClasses');
+  }
   if (
     JSON.stringify(contract.pseudoElements) !==
     JSON.stringify(['after', 'before', 'marker', 'selection'])
@@ -474,7 +575,9 @@ export function assertTemplateStylingContractShape(contract) {
       ]) ||
     composition.functionalSelectorArguments !== 'compound-only' ||
     composition.maximumFunctionalDepth !== 1 ||
-    composition.nthExpressionProfile !== 'gala-positive-an-plus-b-v2'
+    composition.nthExpressionProfile !== 'gala-positive-an-plus-b-v2' ||
+    JSON.stringify(composition.functionalPseudoKeywordArguments) !==
+      JSON.stringify([...FUNCTIONAL_PSEUDO_KEYWORD_ARGUMENTS])
   ) {
     fail('composition');
   }

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

@@ -3,9 +3,8 @@
  * Every other module reaches rendered output only through
  * {@link renderPagesWithEleventy}'s plain-data return value: no Eleventy
  * instance, plug-in API, config object or Nunjucks environment crosses back
- * out of this module (brief S2 section 3: "No Eleventy object, plug-in API,
- * config object or Nunjucks environment may cross the adapter boundary in
- * either direction").
+ * out of this module: no Eleventy object, plug-in API, config object or
+ * Nunjucks environment may cross the adapter boundary in either direction.
  *
  * Confinement enforced here:
  * - `configPath: false` on the `Eleventy` constructor disables discovery of
@@ -24,8 +23,8 @@
  *   interpreted as Nunjucks/Liquid template syntax.
  * - `elev.write()` runs exactly one full build; this module never calls
  *   `.watch()` or constructs an incremental build, and never sets
- *   `runMode: "watch"` (brief S2 section 3: "Incremental and watch mode
- *   ... cannot produce a releasable artifact").
+ *   `runMode: "watch"`: incremental and watch mode cannot produce a
+ *   releasable artifact.
  * - No plugin that performs network access is registered, and Eleventy's
  *   own default plugins (`HtmlBasePlugin`, `BundlePlugin`) perform no
  *   network access.
@@ -34,7 +33,9 @@
 import Eleventy from '@11ty/eleventy';
 
 import {
+  APPEARANCE_RESOLVED_MODE_ATTRIBUTE,
   APPEARANCE_ROOT_ATTRIBUTE,
+  APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE,
   COLOR_SCHEME_META_CONTENT,
 } from './appearance/contract.js';
 import { contentSecurityPolicyMetaTag } from './content-security.js';
@@ -57,32 +58,41 @@ import { PAGE_KIND_ATTRIBUTE } from './page-kinds.js';
 
 /**
  * The one skeleton layout this repository ships. It is core-owned static
- * markup, not discovered from or influenced by the author repository. As of
- * S2-T06, `{{ content | safe }}` is the page's *complete* body content
- * (skip link, header, primary navigation, main, footer — see
- * `internal/skeleton.js`'s `renderPageBody`), so this layout only supplies
- * the outer document shell, the per-page `lang`/`dir` attributes, the CSP
- * baseline, the S2-T07 appearance-controller wiring and the S2-T08
- * SEO/localization `<head>` metadata below; it does not itself wrap
- * anything in `<main>`.
+ * markup, not discovered from or influenced by the author repository.
+ * `{{ content | safe }}` is the page's *complete* body content (skip link,
+ * header, primary navigation, main, footer — see `internal/skeleton.js`'s
+ * `renderPageBody`), so this layout only supplies the outer document shell,
+ * the per-page `lang`/`dir` attributes, the CSP baseline, the
+ * appearance-controller wiring and the SEO/localization `<head>` metadata
+ * below; it does not itself wrap anything in `<main>`.
  *
- * The one S2-T04 addition on top of S2-T03's minimal layout is the
- * byte-exact per-artifact CSP `<meta>` baseline (brief S2 section 3): S2
- * materializes no module package, configuration, output or runtime, so the
- * same constant tag is correct on every route.
+ * On top of that minimal layout is the byte-exact per-artifact CSP
+ * `<meta>` baseline: this renderer materializes no module package,
+ * configuration, output or runtime, so the same constant tag is correct on
+ * every route.
  *
- * S2-T07 additions, all fixed literals from `internal/appearance/contract.js`
- * (never re-typed here), each byte-identical on every route exactly like the
- * CSP tag above:
+ * Appearance-controller additions, all fixed literals from
+ * `internal/appearance/contract.js` (never re-typed here), each
+ * byte-identical on every route exactly like the CSP tag above:
  *
  * - the `data-gala-publication-root` presence attribute on `<html>`, always
  *   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
+ *   `<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
+ *   blocking bootstrap `<script src>` fails. The bootstrap script's phase 1
+ *   ({@link ../appearance/bootstrap-script.js}) unconditionally overwrites
+ *   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
  *   (form controls, scrollbars) and the initial paint already follow
  *   `prefers-color-scheme` before any script runs;
- * - the one `<script src>` this renderer ever emits (brief S2 section 3:
- *   "the appearance controller is the only browser bootstrap"): a plain,
+ * - the one `<script src>` this renderer ever emits (the appearance
+ *   controller is the only browser bootstrap it ever ships): a plain,
  *   same-origin, non-`defer`/non-`async`/non-`module` classic script, placed
  *   after the CSP `<meta>` so it is governed by the policy it declares.
  *   Being a blocking `<script src>` in `<head>`, it always finishes running
@@ -90,36 +100,36 @@ import { PAGE_KIND_ATTRIBUTE } from './page-kinds.js';
  *   `<body>` (and so any themed paint) is even parsed, satisfying the
  *   pre-paint requirement with no visibility-hiding trick of any kind (see
  *   `internal/appearance/bootstrap-script.js`'s own module documentation).
- *   Its `href` (S2-T12 basePath fix) is supplied per-page as
- *   `data.appearanceScriptHref`, already `basePath`-joined by the caller
+ *   Its `href` is supplied per-page as `data.appearanceScriptHref`, already
+ *   `basePath`-joined by the caller
  *   (`internal/appearance/contract.js`'s `appearanceBootstrapScriptHref`),
  *   never a literal embedded in this fixed layout source.
  *
- * S2-T08 adds every other `<head>` element: a viewport meta, an optional
- * plain-text description, an optional `robots` directive
+ * Every other `<head>` element is added on top of that: a viewport meta, an
+ * optional plain-text description, an optional `robots` directive
  * (`internal/page-kinds.js`'s per-page-kind `robotsContent`), an optional
  * canonical link, Open Graph and Twitter Card meta tags and the Atom/RSS
  * feed discovery links (present on every page, unconditionally — the feeds
- * themselves are site-wide, not per-page). S2-T12 adds the theme stylesheet
- * `<link>` elements (`internal/theme-assets.js`, in `cssLayers` order,
- * including the print stylesheet hookup that used to be a fixed literal
- * line here) as one already-rendered `data.themeStylesheetLinksHtml`
- * fragment, and the `data-gala-page-kind` attribute on `<body>`
+ * themselves are site-wide, not per-page). The theme stylesheet `<link>`
+ * elements (`internal/theme-assets.js`, in `cssLayers` order, including the
+ * print stylesheet hookup) are added as one already-rendered
+ * `data.themeStylesheetLinksHtml` fragment, along with the
+ * `data-gala-page-kind` attribute on `<body>`
  * (`internal/page-kinds.js`'s `PAGE_KIND_ATTRIBUTE`). Every interpolated
  * `{{ variable }}`
  * below relies on Nunjucks' own default `autoescape: true` (verified: no
  * `nunjucksEnvironmentOptions.autoescape` override exists anywhere in this
  * repository or in `@11ty/eleventy`'s own source, so Nunjucks' own
  * documented default stands) for HTML-entity escaping — the same implicit
- * contract `{{ title }}` already relied on before S2-T08; only
- * `{{ content | safe }}` is deliberately exempted, because that value is
- * already sanitized HTML markup, not plain text.
+ * contract `{{ title }}` already relied on; only `{{ content | safe }}` is
+ * deliberately exempted, because that value is already sanitized HTML
+ * markup, not plain text.
  *
  * @type {string}
  */
 const SKELETON_LAYOUT_SOURCE = [
   '<!doctype html>',
-  `<html lang="{{ lang }}" dir="{{ dir }}" ${APPEARANCE_ROOT_ATTRIBUTE}>`,
+  `<html lang="{{ lang }}" dir="{{ dir }}" ${APPEARANCE_ROOT_ATTRIBUTE} ${APPEARANCE_RESOLVED_MODE_ATTRIBUTE}="${APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE}">`,
   '<head>',
   '<meta charset="utf-8">',
   '<meta name="viewport" content="width=device-width, initial-scale=1">',
@@ -142,6 +152,13 @@ const SKELETON_LAYOUT_SOURCE = [
   '{% if ogImage %}<meta name="twitter:image" content="{{ ogImage }}">{% endif %}',
   '<link rel="alternate" type="application/atom+xml" href="{{ atomFeedUrl }}" title="{{ siteName }}">',
   '<link rel="alternate" type="application/rss+xml" href="{{ rssFeedUrl }}" title="{{ siteName }}">',
+  // TPL-H3/TPL-M7: the template-owned gala-base layer's own `<link>`,
+  // always first among the stylesheets — before any theme `<link>` — so its
+  // own first-line `@layer` order statement (`internal/appearance/
+  // base-layer.js`) is the one every browser sees first, and so a theme's
+  // later-loaded gala-tokens/gala-components/gala-utilities layers can
+  // always override its defaults.
+  '<link rel="stylesheet" href="{{ baseStylesheetHref }}">',
   '{{ themeStylesheetLinksHtml | safe }}',
   '</head>',
   `<body ${PAGE_KIND_ATTRIBUTE}="{{ pageKind }}">`,