@rathnasgala2/template 2.0.0 → 2.2.0

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 }}">`,

package/src/core/internal/feeds.js

@@ -1,28 +1,25 @@
 /**
- * RSS 2.0 and Atom 1.0 feed generation (task packet S2-T08; brief S2
- * section 3 "Required generated outputs": "RSS and Atom feeds").
+ * RSS 2.0 and Atom 1.0 feed generation.
  *
  * Both feeds are built from the exact same {@link selectPublishedArticles}
  * selection and ordering `internal/page-kinds.js`'s `index` page kind
  * paginates (most recently published first, `publishedAt` descending, tied
  * broken by ascending `id`), so a feed's item order can never drift from the
  * site's own index listing. Every URL is an absolute `https://` URL resolved
- * against `buildInput.baseUrl` (brief S2 section 3: "absolute URLs from the
- * build input's public origin"), never a relative path — a feed reader has
- * no notion of the publication's own base path to resolve a relative URL
- * against.
+ * against `buildInput.baseUrl` — always the build input's public origin,
+ * never a relative path — since a feed reader has no notion of the
+ * publication's own base path to resolve a relative URL against.
  *
- * Item count (documented scoped decision, not fixed by the brief or
- * DEC-097): neither source specifies a maximum feed item count. This module
- * bounds it at {@link FEED_ITEM_LIMIT} — a conservative, deterministic
- * default with no author-facing configuration surface in S2, matching this
- * renderer's own established style for an unspecified numeric bound (see
- * `internal/page-kinds.js`'s `LISTING_PAGE_SIZE` and the media pipeline
- * scope decisions in the package README).
+ * Item count: this renderer's build input carries no maximum feed item
+ * count. This module bounds it at {@link FEED_ITEM_LIMIT} — a conservative,
+ * deterministic default with no author-facing configuration surface,
+ * matching this renderer's own established style for an unspecified
+ * numeric bound (see `internal/page-kinds.js`'s `LISTING_PAGE_SIZE` and the
+ * media pipeline scope decisions in the package README).
  */
 
 import { escapeHtml } from './skeleton.js';
-import { joinBasePathAndRoute } from './route.js';
+import { derivePublicBasePath, joinPublicRoute } from './route.js';
 import {
   contentLastModified,
   contentRoute,
@@ -69,7 +66,10 @@ export function buildFeeds(validatedInput) {
    * @returns {string} the absolute `https://` URL
    */
   const absoluteUrl = (route) =>
-    new URL(joinBasePathAndRoute(basePath, route), baseUrl).toString();
+    new URL(
+      joinPublicRoute(derivePublicBasePath(baseUrl, basePath), route),
+      baseUrl,
+    ).toString();
 
   const siteUrl = absoluteUrl('/');
   const atomSelfUrl = absoluteUrl(ATOM_FEED_ROUTE);

package/src/core/internal/fs-walk.js

@@ -3,8 +3,8 @@
  *
  * Filesystem readdir order is not portable, so every caller that needs a
  * reproducible route/asset ordering must sort explicitly; this module never
- * returns raw enumeration order (brief S2 section 3: "no
- * filesystem-enumeration-order dependence").
+ * returns raw enumeration order, so this renderer has no
+ * filesystem-enumeration-order dependence.
  */
 
 import { readdir } from 'node:fs/promises';

package/src/core/internal/media/avif-probe.js

@@ -7,17 +7,17 @@
  * enough to confirm an `ftyp` box with major brand `avif`, locate the
  * `meta` box, and read the primary item's `ispe` (image spatial extents)
  * property for declared width/height, but it does not run a full AV1
- * bitstream decode. DEC-097's closed `gala-theme-binary-assets-v2` profile
+ * bitstream decode. This renderer's closed passive-theme-asset decoder
  * requires a complete single-frame AV1 decode for *passive theme assets*;
  * an equivalent from-scratch AV1 decoder for *author media* is out of
- * proportion to this task's scope, flagged to the orchestrator as a
+ * proportion to this module's scope, flagged to the orchestrator as a
  * follow-up. AVIF is therefore admitted as a *source* reference
  * (recorded, digest-verified, dimension-bounded) with no generated
  * responsive derivative; its original bytes pass through as the sole asset
  * entry, exactly like WebP.
  *
- * The box walk is bounded: at most 4,096 boxes are visited (matching
- * DEC-097's own "4,096 container structures" isolation bound for the binary
+ * The box walk is bounded: at most 4,096 boxes are visited (matching this
+ * renderer's own container-structure isolation bound for the binary
  * decoder family) and every box's declared size is checked against the
  * remaining buffer length before it is used to slice, so a malformed or
  * adversarial box table cannot cause an out-of-bounds read or an unbounded

package/src/core/internal/media/font-policy.js

@@ -1,7 +1,7 @@
 /**
- * Font policy for `appearance.fontAssets` (brief S2 section 3: "Custom fonts
+ * Font policy for `appearance.fontAssets`: custom fonts
  * require licensing, glyph and language coverage plus fallback evidence, and
- * no remote font is ever retrieved").
+ * no remote font is ever retrieved.
  *
  * `build-input:2.0.0`'s `resolvedFile` shape (the only shape
  * `appearance.fontAssets` entries use) is `{path, sourceDigest}` — a

package/src/core/internal/media/limits.js

@@ -1,37 +1,34 @@
 import { MediaPipelineError } from '../../errors.js';
 
 /**
- * Media pipeline resource ceilings (brief S2 section 3, S2-T05: "bounded
- * decoding worker", "decompression and resource limits").
+ * Media pipeline resource ceilings: a bounded decoding worker with fixed
+ * decompression and resource limits, so a hostile or malformed image/font
+ * can never trigger unbounded allocation or a decode bomb.
  *
- * The raster-specific numbers below are DEC-097's own closed
- * `gala-theme-binary-assets-v2` bounds (decision document section titled
- * "Binary theme assets"): non-animated raster, width/height each `1..8192`,
- * at most 16,777,216 pixels, at most 67,108,864 decoded RGBA8 buffer bytes,
- * source raster at most 16,777,216 bytes, source font at most 4,194,304
- * bytes. DEC-097 states those bounds for the closed theme *passive-asset*
- * decoder profile; the brief's author-media pipeline (S2-T05) gives no
- * separate numeric profile of its own, so this renderer reuses the same
- * numbers for the author-media decode-bound worker rather than inventing an
- * unrelated set — the physical decode-bomb risk (integer overflow, unbounded
- * allocation) is identical for both call sites. This is an explicit,
- * documented implementer decision, not a value taken from author-media text.
+ * The raster-specific numbers below are this renderer's closed binary-asset
+ * bounds, shared between the theme passive-asset decoder profile and the
+ * author-media pipeline (which has no separate numeric profile of its own):
+ * non-animated raster, width/height each `1..8192`, at most 16,777,216
+ * pixels, at most 67,108,864 decoded RGBA8 buffer bytes, source raster at
+ * most 16,777,216 bytes, source font at most 4,194,304 bytes. Reusing the
+ * same numbers for both call sites, rather than inventing an unrelated set,
+ * is a deliberate choice: the physical decode-bomb risk (integer overflow,
+ * unbounded allocation) is identical for both.
  *
- * DEC-097's separate "document-22 operational release" MVP launch gate also
- * fixes a smaller general per-source-file ceiling (10,485,760 bytes) that
- * applies to *every* repository source file regardless of kind, with "the
- * smaller declared per-file/package budget still wins." Applied here: the
+ * A separate, smaller general per-source-file ceiling (10,485,760 bytes)
+ * applies to *every* repository source file regardless of kind, and the
+ * smaller declared per-file/package budget always wins. Applied here: the
  * effective per-image source-byte ceiling is `min(16,777,216, 10,485,760)`.
  * The font ceiling (4,194,304) is already smaller than the general cap, so
  * it is unaffected.
  *
  * `MAX_IMAGES_PER_PUBLICATION` and `MAX_TOTAL_MEDIA_BYTES_PER_PUBLICATION`
- * are not fixed anywhere in the brief or DEC-097; there is no cited
- * per-publication *media-specific* aggregate. These two values are this
- * renderer's own conservative, documented ceilings (well under DEC-097's
- * unrelated 50,000-file / 1,073,741,824-byte whole-artifact ceiling), so a
- * publication cannot exhaust the media pipeline's bounded decode budget by
- * sheer reference count even though each individual file is itself bounded.
+ * have no externally fixed per-publication *media-specific* aggregate to
+ * conform to. These two values are this renderer's own conservative,
+ * documented ceilings (well under this renderer's separate, unrelated
+ * 50,000-file / 1,073,741,824-byte whole-artifact ceiling), so a publication
+ * cannot exhaust the media pipeline's bounded decode budget by sheer
+ * reference count even though each individual file is itself bounded.
  */
 
 /** Maximum admitted raster width or height, in pixels, inclusive. */
@@ -44,15 +41,15 @@ export const MAX_IMAGE_PIXELS = 16_777_216;
 export const MAX_DECODED_RGBA_BYTES = 67_108_864;
 
 /**
- * Maximum admitted raster source byte length: the smaller of DEC-097's
- * raster-specific cap (16,777,216) and its general per-source-file cap
- * (10,485,760).
+ * Maximum admitted raster source byte length: the smaller of this
+ * renderer's raster-specific cap (16,777,216) and its general
+ * per-source-file cap (10,485,760).
  */
 export const MAX_IMAGE_SOURCE_BYTES = 10_485_760;
 
 /**
- * Maximum admitted font source byte length (DEC-097's binary font cap,
- * already smaller than the general per-source-file cap).
+ * Maximum admitted font source byte length (this renderer's binary font
+ * cap, already smaller than the general per-source-file cap).
  */
 export const MAX_FONT_SOURCE_BYTES = 4_194_304;
 
@@ -74,8 +71,9 @@ export const MAX_FONTS_PER_PUBLICATION = 8;
 /**
  * Maximum aggregate decoded-plus-derivative byte budget the media pipeline
  * will spend for one publication (implementer-chosen; see module
- * documentation). Comfortably under DEC-097's unrelated 1,073,741,824-byte
- * whole-artifact ceiling, which this constant does not replace or relax.
+ * documentation). Comfortably under this renderer's separate, unrelated
+ * 1,073,741,824-byte whole-artifact ceiling, which this constant does not
+ * replace or relax.
  */
 export const MAX_TOTAL_MEDIA_BYTES_PER_PUBLICATION = 268_435_456;
 
@@ -116,9 +114,9 @@ export function assertDimensionsWithinCeiling(
 
 /**
  * Non-resetting wall-clock budget for one file's bounded decode, in
- * milliseconds. DEC-097's own closed binary-asset decoder uses a ten-second
- * non-resetting deadline; this renderer reuses that figure for the same
- * documented reason as the size/pixel ceilings above.
+ * milliseconds. This renderer's closed binary-asset decoder uses a
+ * ten-second non-resetting deadline, for the same documented reason as the
+ * size/pixel ceilings above.
  */
 export const DECODE_DEADLINE_MS = 10_000;
 

package/src/core/internal/media/pipeline.js

@@ -1,10 +1,10 @@
 /**
- * Media pipeline orchestration (brief S2 section 3, S2-T05).
+ * Media pipeline orchestration.
  *
  * `build-input:2.0.0` never carries raw asset bytes for a `resolvedFile`
- * reference — only its repository-relative `path` and a `sourceDigest`
- * (DEC-097 section 6: "`build` exposes this decoded set as a read-only
- * source mount"). This pipeline therefore reads actual bytes from
+ * reference — only its repository-relative `path` and a `sourceDigest`:
+ * `build` exposes this decoded set as a read-only source mount. This
+ * pipeline therefore reads actual bytes from
  * `options.sourceDirectory`, the caller-mounted read-only source tree, and
  * fails closed (`MEDIA_SOURCE_DIGEST_MISMATCH`) if what it reads there does
  * not hash to the digest `build-input` declared — the same fail-closed