@rathnasgala2/template 2.0.0 → 2.2.0

package/README.md

@@ -5,14 +5,14 @@ portable author repository format. It is one of the three author-facing S2
 artifacts, alongside one `@rathnasgala2/theme-*` package and
 `@rathnasgala2/publish-action`.
 
-This package is JavaScript ESM on Node 24, authored without TypeScript sources
-(DEC-094): every export carries JSDoc types, checked by `tsc --checkJs --noEmit`
-against a hand-maintained `.d.ts` surface.
+This package is JavaScript ESM on Node 24, authored without TypeScript sources:
+every export carries JSDoc types, checked by `tsc --checkJs --noEmit` against a
+hand-maintained `.d.ts` surface.
 
 ## Status
 
-S2-T02's repository scaffold (exact pins, `src/core/`-only layout, module-tree
-absence gate, quality-gate tooling) plus S2-T03's renderer adapter:
+This repository's scaffold (exact pins, `src/core/`-only layout, module-tree
+absence gate, quality-gate tooling) plus its renderer adapter:
 `renderPublication(buildInput, options)`, exported from `src/core/index.js`, is
 the package's one documented entry point. It:
 
@@ -29,7 +29,7 @@ the package's one documented entry point. It:
    `urn:gala:schema:artifact-manifest:2.0.0` instance describing the candidate
    output directory.
 
-S2-T05 adds the media pipeline under `src/core/internal/media/`, run from
+The media pipeline lives under `src/core/internal/media/`, run from
 `renderPublication` after the Eleventy route listing so its output is never
 mistaken for an HTML route:
 
@@ -40,8 +40,8 @@ mistaken for an HTML route:
   entropy decode (a documented scope decision — see
   `webp-probe.js`/`avif-probe.js`). Every format shares one set of resource
   ceilings in `limits.js` (raster dimension, pixel count, decoded-buffer and
-  source-byte caps reused from DEC-097's own closed binary-asset decoder bounds,
-  plus this renderer's own documented per-publication ceilings).
+  source-byte caps reused from the theme package's own closed binary-asset
+  decoder bounds, plus this renderer's own documented per-publication ceilings).
 - **Metadata strip, orientation.** PNG/JPEG derivatives are always re-encoded
   from decoded pixels, never byte-copied, so no ancillary/EXIF metadata survives
   into a derivative; JPEG's EXIF `Orientation` tag is read and applied
@@ -55,7 +55,7 @@ mistaken for an HTML route:
   unconditionally as an image reference (`MEDIA_SVG_REJECTED`) — SVG is never
   processed as author media.
 - **Font policy.** `appearance.fontAssets` entries must be bounded WOFF2 (exact
-  signature, DEC-097's 4,194,304-byte font cap); a remote font reference cannot
+  signature, a fixed 4,194,304-byte font cap); a remote font reference cannot
   enter `build-input` in the first place (`resolvedFile` is always a
   repository-relative path), so "no remote font is ever retrieved" holds
   structurally.
@@ -63,17 +63,16 @@ mistaken for an HTML route:
   mismatch, SVG, unrecognized format, invalid font — is a `MediaPipelineError`
   with a stable `reasonCode`, thrown before the manifest is assembled.
 
-`options.sourceDirectory` (new in S2-T05) is the caller-mounted, read-only
-repository source tree `build-input`'s `resolvedFile` references point into;
-every referenced file's bytes are read from there and verified against
-`build-input`'s declared `sourceDigest` before being decoded.
-
-S2-T04 adds the complete output-security pipeline
-(`src/core/internal/content-security.js`) on top of that adapter. **Division of
-labour** (DEC-097 section 5: normalization replaces an authored body path with a
-`renderableBody` carrying "the deterministic policy output/digest";
-`build-input.schema.json` fixes `renderableBody.bodyMediaType` as
-`const: "text/html"`): a `renderableBody.body` inside a validated
+`options.sourceDirectory` is the caller-mounted, read-only repository source
+tree `build-input`'s `resolvedFile` references point into; every referenced
+file's bytes are read from there and verified against `build-input`'s declared
+`sourceDigest` before being decoded.
+
+The complete output-security pipeline (`src/core/internal/content-security.js`)
+sits on top of that adapter. **Division of labour** (normalization replaces an
+authored body path with a `renderableBody` carrying "the deterministic policy
+output/digest"; `build-input.schema.json` fixes `renderableBody.bodyMediaType`
+as `const: "text/html"`): a `renderableBody.body` inside a validated
 `build-input:2.0.0` instance is **already** render-policy-conformant HTML,
 produced once upstream of this renderer. This package therefore exposes two
 distinct public entry points:
@@ -115,23 +114,37 @@ highlighter grammar/token-class catalog) both surfaces above read from,
 generated deterministically by `scripts/generate-contracts.mjs` from
 `src/core/internal/render-policy-content.js` — the single source of truth, so
 the published contract and the enforced policy cannot drift apart. Every
-rendered page also carries the exact per-artifact CSP baseline as a
+rendered page also carries the meta-safe CSP baseline as a
 `<meta http-equiv="Content-Security-Policy">` tag (byte-identical on every
 route, since S2 materializes no module package/configuration/output/runtime).
 
+**TPL-H4 fix — meta vs. header-only directives.** The CSP specification
+explicitly ignores `frame-ancestors` (and `report-uri`/`sandbox`, neither used
+here) when a policy is delivered via `<meta http-equiv>`; the `<meta>` tag above
+therefore never includes `frame-ancestors`, and
+`contentSecurityPolicyHeaderOnlyDirectives()` (`internal/content-security.js`)
+returns the one directive that is not: `frame-ancestors 'none'`. Clickjacking
+protection for a published artifact is a **hosting-layer requirement**: the
+adapter/deployment serving this artifact must add
+`Content-Security-Policy: frame-ancestors 'none'` (or an equivalent
+`X-Frame-Options` header) as a real HTTP response header. This cannot yet be
+carried in `artifact-manifest:2.0.0`'s own `declarativeHeaders` field, which
+`@rathnasgala2/schemas` currently fixes to `const: []`; surfacing it there is a
+schema-repo change, out of this repository's scope.
+
 `img[src]` is restricted to repository-relative paths only in this pipeline;
-full manifest-coverage verification of media references is the S2-T05 media
-pipeline's job (immediately above). A handful of manifest fields (`builder`,
+full manifest-coverage verification of media references is the media pipeline's
+job (immediately above). A handful of manifest fields (`builder`,
 `sourceIdentity.repository`, `workflowIdentity`, `buildToolVersions`,
 `excludedInputs`) describe facts `build-input` does not itself carry;
 `renderPublication` accepts them as an explicit `options.provenance` bundle
 rather than fabricating them — see `src/core/manifest.js`'s module
-documentation. `contracts/theme-styling-contract.jcs` is S2-T12's real, closed
-`templateStylingContract` catalog (see the S2-T12 section below).
+documentation. `contracts/theme-styling-contract.jcs` is the real, closed
+`templateStylingContract` catalog (see the theme styling contract section
+below).
 
-S2-T06 adds the core semantic skeleton, page kinds and navigation renderer on
-top of the S2-T04 output-security pipeline every generated page still passes
-through:
+The core semantic skeleton, page kinds and navigation renderer sit on top of the
+output-security pipeline every generated page still passes through:
 
 - **`src/core/internal/skeleton.js`** renders the one landmark contract every
   page kind shares, through its one `renderPageBody` composition: a skip link
@@ -144,13 +157,13 @@ through:
   template attribution line). Core owns nine versioned semantic slots
   (`header-actions`, `article-preamble`, `article-end`, `footer-profile`,
   `footer-auxiliary`, `account-intent`, `conversation`, `newsletter`,
-  `edition-selector`) plus the collapsed `article-footer-ad` slot (DEC-060):
-  every slot is one `data-gala-slot="<name>"` attribute on an otherwise empty,
-  non-landmark `<div>`, and the collapsed slot additionally carries `hidden`. S2
+  `edition-selector`) plus the collapsed `article-footer-ad` slot: every slot is
+  one `data-gala-slot="<name>"` attribute on an otherwise empty, non-landmark
+  `<div>`, and the collapsed slot additionally carries `hidden`. This renderer
   has no module system, so every slot except `footer-profile` (which always
-  wraps the publication's own footer card) and `header-actions` (S2-T07's
-  appearance control, core content rather than a module) renders empty. This
-  module also renders breadcrumbs and deterministic pagination controls
+  wraps the publication's own footer card) and `header-actions` (the appearance
+  control, core content rather than a module) renders empty. This module also
+  renders breadcrumbs and deterministic pagination controls
   (`rel="prev"`/`rel="next"`, an `aria-current="page"` status).
 - **`src/core/internal/page-kinds.js`** builds every generated page kind from a
   validated `build-input:2.0.0`: `profile` (the optional publication profile),
@@ -162,10 +175,10 @@ through:
   page per distinct authored value, plus a `/tags`/`/series` root page linking
   to each), and `archive` (one listing page per UTC calendar year, plus a
   `/archive` root page). The `error` page kind (`renderErrorPageBody`) is
-  exported as a pure function for a future `404.html` caller (S2-T08, out of
-  this task's scope), not wired into any generated route here. Listing page size
-  (10), sort tie-break, and the tag/series/archive root pages are documented
-  scoped decisions the brief text this task read does not fix verbatim.
+  exported as a pure function for the `404.html` caller (see below), not wired
+  into any generated route here. Listing page size (10), sort tie-break, and the
+  tag/series/archive root pages are documented scoped decisions this renderer's
+  own governing brief does not fix verbatim.
 - **`src/core/internal/messages.js`** is the message catalog every user-visible
   chrome string above is looked up from (never an inline literal), keyed by
   BCP-47 tag with a fixed `en` fallback — the only catalog S2 authors;
@@ -186,19 +199,19 @@ every page (a scoped decision: navigation/footer text does not flip language
 page to page); each page's own `<html lang>`/`dir` still reflects that
 individual page's own content language.
 
-S2-T07 adds the Light/Dark/System appearance controller
-(`src/core/internal/appearance/`), the only browser bootstrap S2 emits (brief S2
-section 3, "Module absence and CSP equality"):
+The Light/Dark/System appearance controller (`src/core/internal/appearance/`) is
+the only browser bootstrap this renderer emits ("Module absence and CSP
+equality"):
 
 - **`contract.js`** is the one module every other appearance-related file
-  imports every name/value from: the two DEC-097-fixed root attributes
+  imports every name/value from: the two fixed root attributes
   (`data-gala-publication-root` presence, `data-gala-resolved-color-mode`
   exact-value `"light"`/`"dark"`), the template-internal
   `data-gala-color-mode-selection` bookkeeping attribute, the three canonical
   mode values (`light`/`dark`/`system`), the versioned local storage key
   (`gala:appearance:color-mode:v1`), the control's `id`, the bootstrap script's
   fixed output path/media type and the `color-scheme` meta content — the
-  contract S2-T12's published theme styling catalog targets.
+  contract the published theme styling catalog targets.
 - **`controller-markup.js`** renders a native `<select>` (a brief-admitted
   pattern; needs no `aria-pressed`/`aria-checked` bookkeeping of its own, unlike
   a custom button-group or radio-group would) bound to a visible `<label>`, with
@@ -225,29 +238,47 @@ section 3, "Module absence and CSP equality"):
   directory and enters it into the manifest as an ordinary `manifestAsset` row
   (`{path, byteLength, sha256}` plus its fixed
   `application/javascript; charset=utf-8` media type), after the Eleventy route
-  listing — exactly like an S2-T05 media derivative — so it is never mistaken
-  for an HTML route. `src/core/internal/eleventy-render.js`'s skeleton layout
-  carries the `data-gala-publication-root` attribute, the
+  listing — exactly like a media derivative — so it is never mistaken for an
+  HTML route. `src/core/internal/eleventy-render.js`'s skeleton layout carries
+  the `data-gala-publication-root` attribute, the
   `<meta name="color-scheme" content="light dark">` tag and the one
   `<script src>` reference, all fixed literals from `contract.js`, so every
-  route's `<head>` is still byte-identical (S2 materializes no module
+  route's `<head>` is still byte-identical (this renderer materializes no module
   package/configuration/output/runtime).
 - With JavaScript disabled, the control still renders (a native `<select>`,
-  fully keyboard-operable and usable with no script at all) and the resolved
-  root attribute is simply never set; `<meta name="color-scheme">` alone already
-  carries `prefers-color-scheme` through to user-agent styling and the initial
-  paint independent of any script.
-
-S2-T12 replaces `contracts/theme-styling-contract.jcs`'s S2-T02 scaffold
-placeholder with the real, closed `templateStylingContract` catalog DEC-097
-section 4 defines, and wires the selected theme package's stylesheets into every
-generated page:
+  fully keyboard-operable and usable with no script at all). The resolved root
+  attribute is server-rendered as the fixed `light` default, so a no-JS reader,
+  an archival crawler, or a load where the bootstrap script fails still gets a
+  fully themed page instead of unstyled UA-default HTML; a scripted reader's
+  phase 1 bootstrap always overwrites this attribute with the reader's real
+  stored selection/system preference before first paint.
+  `<meta name="color-scheme">` also carries `prefers-color-scheme` through to
+  user-agent styling (form controls, scrollbars) independent of any script.
+
+**Authoring a theme:** see [`docs/theme-authoring.md`](docs/theme-authoring.md)
+for the full guide — how a theme is a delta over the template-owned `gala-base`
+layer, the closed 35-token catalog, the closed five-member pseudo-class catalog,
+passive-asset/SVG admission, the `theme.json` digest chain, and `templateRange`.
+Run `node scripts/scaffold-theme.mjs <directory>` to write a minimal,
+already-conformant theme package skeleton rather than hand-typing one.
+
+The theme styling contract replaces `contracts/theme-styling-contract.jcs`'s
+original scaffold placeholder with the real, closed `templateStylingContract`
+catalog this renderer's own internal styling decision defines, and wires the
+selected theme package's stylesheets into every generated page:
 
 - **`src/core/internal/appearance/styling-contract.js`** is the one reviewed
   source module `scripts/generate-contracts.mjs` emits the contract from: the
-  ordered four-layer catalog (`gala-tokens`/`gala-components`/`gala-utilities`/
-  `gala-print`), the publication-root/resolved-palette selectors, the closed
-  type/class/id/attribute leaf catalogs, and exactly 64 `publicThemeSlotHooks` —
+  ordered five-layer catalog (`gala-base`/`gala-tokens`/`gala-components`/
+  `gala-utilities`/`gala-print` — contract 2.1.0: `gala-base` is the template's
+  own layer, carrying the reset/type-scale/focus-ring defaults documented below
+  `internal/appearance/base-layer.js`, always ordered first so a theme's own
+  layers can override it), the publication-root/ resolved-palette selectors, the
+  closed type/class/id/attribute leaf catalogs, a closed five-member
+  pseudo-class catalog (`hover`, `focus-visible`, `active`, `visited`,
+  `disabled` — contract 2.1.0; see that module's own documentation for why each
+  is admitted and why the token catalog's `color-focus`/`color-link-visited` had
+  no reachable application before it), and exactly 64 `publicThemeSlotHooks` —
   one per catalog leaf, so every leaf a theme could validly select is a named,
   documented hook and no catalog member is orphaned. Every leaf is drawn from
   what this renderer actually renders: 28 type-selector hooks (every
@@ -255,16 +286,16 @@ generated page:
   `internal/page-kinds.js` and the markdown-it CommonMark pipeline can produce),
   15 class-selector hooks (the base Prism `.token` class plus one
   `.language-<grammar>` hook per admitted highlight grammar — fine-grained
-  per-token-kind classes are a documented S2 scope exclusion), 2 id-selector
-  hooks (`#main-content`, the appearance `<select>`'s fixed id) and 19
-  attribute-value hooks (one per `data-gala-slot` value, one per the new
-  `data-gala-page-kind` value). `catalogDigest` is
+  per-token-kind classes are a documented scope exclusion), 2 id-selector hooks
+  (`#main-content`, the appearance `<select>`'s fixed id) and 19 attribute-value
+  hooks (one per `data-gala-slot` value, one per the `data-gala-page-kind`
+  value). `catalogDigest` is
   `SHA256(UTF8("GALA-TEMPLATE-STYLING-CONTRACT-V2\0") || JCS(...))`, matching
-  DEC-097 section 8 and the digest profile `@rathnasgala2/schemas`' own internal
-  `templateStylingContract` profile uses (that function is not exported through
-  the package's public API, so this module reimplements the same
-  domain-separated formula rather than importing it).
-  `assertTemplateStylingContractShape` is this repository's own structural
+  the same domain-separated digest construction and the digest profile
+  `@rathnasgala2/schemas`' own internal `templateStylingContract` profile uses
+  (that function is not exported through the package's public API, so this
+  module reimplements the same domain-separated formula rather than importing
+  it). `assertTemplateStylingContractShape` is this repository's own structural
   self-validator (root/palette attribute rows, fixed layer/selector/composition
   constants, hook count/uniqueness bound, `catalogDigest` recomputation); no
   `urn:gala:schema:template-styling-contract` schema ID is registered in
@@ -286,50 +317,74 @@ generated page:
   `@rathnasgala2/schemas`' own exported `validateGalaDocument`.
 - **`src/core/internal/theme-assets.js`** is the optional theme-asset
   integration layer: given `options.themeDirectory` (an extracted theme package
-  directory, shaped exactly like the S2-T13 package file set — `theme.json`,
-  `tokens.css`, `components.css`, an optional `utilities.css`, `print.css`,
-  `package.json`, `LICENSE`, `README.md`, `assets/*`), it copies the declared
-  stylesheets and any declared non-CSS passive assets into `assets/theme/`,
-  enters each as an ordinary `{path, byteLength, sha256}` `manifestAsset` row,
-  and renders the ordered `<link>` markup every generated page's `<head>`
-  inserts (`print.css` alone carries `media="print"`). It validates the theme's
-  own declared `stylesheets` list against the two admitted shapes (with or
-  without `utilities.css`) and that `cssLayers` byte-equals the corresponding
-  layer projection, but does **not** re-implement DEC-097's full CSS Syntax
-  Module admission grammar — that is the shared `theme-release.yml` conformance
-  runner's job (S2-T11), run once per theme release, never per publication
+  directory, shaped exactly like the theme package's own file set —
+  `theme.json`, `tokens.css`, `components.css`, an optional `utilities.css`,
+  `print.css`, `package.json`, `LICENSE`, `README.md`, `assets/*`), it copies
+  the declared stylesheets and any declared non-CSS passive assets into
+  `assets/theme/`, enters each as an ordinary `{path, byteLength, sha256}`
+  `manifestAsset` row, and renders the ordered `<link>` markup every generated
+  page's `<head>` inserts (`print.css` alone carries `media="print"`). It
+  validates the theme's own declared `stylesheets` list against the two admitted
+  shapes (with or without `utilities.css`) and that `cssLayers` byte-equals the
+  corresponding layer projection, but does **not** re-implement the full CSS
+  Syntax Module admission grammar — that is the shared `theme-release.yml`
+  conformance runner's job, run once per theme release, never per publication
   build. `renderPublication` falls back to the pre-existing fixed
   `assets/theme/print.css` link when no `options.themeDirectory` is supplied
-  (every caller before S2-T12, and this repository's own tests that do not
-  exercise theme integration). Minimal in-repo fixture theme packages for both
+  (every caller that predates theme integration, and this repository's own tests
+  that do not exercise it). Minimal in-repo fixture theme packages for both
   stylesheet-list shapes live under `test/fixtures/theme-fixture-full/` and
   `test/fixtures/theme-fixture-minimal/` — deliberately not real, conformant
-  theme CSS (authoring one is S2-T13's task); they exist only to exercise the
-  copy/link/manifest mechanism.
+  theme CSS (authoring one is a theme package's own task); they exist only to
+  exercise the copy/link/manifest mechanism.
+
+Hardening at consume time (a theme package is lower-trust supply-chain input
+than the repository owner's own authored content, so it is held to at least the
+same bar): `theme.json` is schema-validated against
+`urn:gala:schema:theme-contract:2.0.0` before anything else, and its
+`contractVersion`/`stylingContractDigest`/ `templateRange` are checked against
+this renderer's own published styling contract and version
+(`internal/semver-range.js`: a deliberately closed exact-version/caret-range
+subset). Every declared file's `byteLength`/ `sha256` is verified against the
+bytes actually read, and `theme.json.budgets` is enforced. Every passive asset's
+bytes are sniffed (never trusted from the declared `mediaType`) against a closed
+allowlist: raster formats are admitted directly, and SVG is admitted only after
+`internal/media/theme-svg-sanitizer.js`'s closed grammar rejects any
+`<script>`/event-handler/external-reference construct outright. **Iconography is
+in scope and expected** (TPL-H6 decision): this sanitizer is what makes a
+theme-declared SVG icon mark safe to publish.
+
+- **`baseUrl` path prefix (2.2.0).** `buildInput.baseUrl` may carry a path (a
+  GitHub project site, `https://owner.github.io/g9/`); it is not origin-only.
+  `internal/route.js#derivePublicBasePath(baseUrl, basePath)` joins that path
+  with `basePath` into the one public base path every emitted URL uses (route
+  and asset hrefs, the appearance script, stylesheet links, canonical/`og:url`,
+  feed, sitemap and search-index URLs). Output file paths still use `basePath`
+  alone, because the artifact is deployed at the hosting site root.
 - **basePath fix (LOCAL-7 follow-up; independent-review finding B2).** Before
-  S2-T12, the appearance bootstrap script's `<script src>` and the social-image
-  `og:image`/`twitter:image` URL were both root-absolute, unprefixed by the
-  publication's own `basePath` — a non-root `basePath` publication would 404
-  them. `internal/appearance/contract.js`'s new
+  theme integration existed, the appearance bootstrap script's `<script src>`
+  and the social-image `og:image`/`twitter:image` URL were both root-absolute,
+  unprefixed by the publication's own `basePath` — a non-root `basePath`
+  publication would 404 them. `internal/appearance/contract.js`'s new
   `appearanceBootstrapScriptHref(basePath)` and `internal/seo.js`'s
   `resolveSocialImageUrl` (now taking `basePath`) both join through
   `internal/route.js`'s shared `joinBasePathAndRoute`/`projectFixedAssetPath`,
   exactly like the pre-existing print-stylesheet convention (now folded into
   `internal/theme-assets.js`) already did for _hrefs_. Independent review
   (finding B2) found that this was only half the fix: the _physical files_ this
-  renderer writes for every asset class — theme CSS/passive assets, every S2-T05
-  media derivative, and the S2-T07 appearance bootstrap script — were still
-  written, and entered into the manifest, at their bare **unprefixed** paths.
-  Since the local-directory adapter serves a `manifestAsset.path` verbatim, a
-  non-root `basePath` publication's `<link>`/`<script src>`/`og:image` href
-  would point at `<basePath>/assets/...` while the actual file sat at the
-  unprefixed `assets/...` — a 404 in practice, not just a theoretical href
-  mismatch. `src/core/index.js` now joins `basePath` into the physical
-  destination path and the `manifestAsset.path` for media derivatives
-  (`joinedMediaAssets`, computed with the same `projectFixedAssetPath` every
-  other fixed-name generated asset already uses) and the appearance bootstrap
-  script (`joinedAppearanceScriptPath`); `internal/theme-assets.js` computes its
-  joined output path once per file and derives both the `<link href>` and the
+  renderer writes for every asset class — theme CSS/passive assets, every media
+  derivative, and the appearance bootstrap script — were still written, and
+  entered into the manifest, at their bare **unprefixed** paths. Since the
+  local-directory adapter serves a `manifestAsset.path` verbatim, a non-root
+  `basePath` publication's `<link>`/`<script src>`/`og:image` href would point
+  at `<basePath>/assets/...` while the actual file sat at the unprefixed
+  `assets/...` — a 404 in practice, not just a theoretical href mismatch.
+  `src/core/index.js` now joins `basePath` into the physical destination path
+  and the `manifestAsset.path` for media derivatives (`joinedMediaAssets`,
+  computed with the same `projectFixedAssetPath` every other fixed-name
+  generated asset already uses) and the appearance bootstrap script
+  (`joinedAppearanceScriptPath`); `internal/theme-assets.js` computes its joined
+  output path once per file and derives both the `<link href>` and the
   file/manifest path from that exact same value, so they cannot drift apart.
   `test/theme-styling-contract.test.js` carries a dedicated non-root,
   multi-segment `basePath` (`/blog/2024`) fixture test asserting every one of
@@ -356,14 +411,15 @@ generated page:
 
 ### Media pipeline scope decisions (documented, not silently assumed)
 
-Neither the S2 brief nor DEC-097 fixes exact derivative widths, output
-formats/quality, or a per-publication media byte/count ceiling for _author_
-media (DEC-097's own numeric bounds are stated for the closed
-`gala-theme-binary-assets-v2` _theme passive-asset_ profile). This renderer
-therefore documents its own choices in `src/core/internal/media/limits.js`
-rather than inventing undocumented magic numbers:
+Neither this renderer's own governing brief nor its internal styling decision
+fixes exact derivative widths, output formats/quality, or a per-publication
+media byte/count ceiling for _author_ media (those numeric bounds are stated
+only for the closed `gala-theme-binary-assets-v2` _theme passive-asset_
+profile). This renderer therefore documents its own choices in
+`src/core/internal/media/limits.js` rather than inventing undocumented magic
+numbers:
 
-- decode/resource ceilings reuse DEC-097's theme binary-asset numbers
+- decode/resource ceilings reuse the theme binary-asset profile's numbers
   (dimension, pixel-count, decoded-buffer, source-byte caps), since the
   decode-bomb risk they defend against is identical regardless of asset class;
 - responsive derivative widths (`320/640/960/1280/1920`), JPEG derivative
@@ -375,8 +431,8 @@ rather than inventing undocumented magic numbers:
   proportion to this task, and is flagged as a follow-up rather than attempted
   partially.
 
-S2-T08 adds every remaining "Required generated output" from brief S2 section 3
-on top of S2-T06's page kinds:
+Every remaining "Required generated output" from this renderer's own governing
+brief sits on top of the page kinds above:
 
 - **Feeds** (`src/core/internal/feeds.js`): deterministic Atom 1.0
   (`/feed/atom.xml`) and RSS 2.0 (`/feed/rss.xml`) documents over the exact
@@ -384,7 +440,8 @@ on top of S2-T06's page kinds:
   `internal/page-kinds.js`'s `index` page kind paginates (the shared
   `selectPublishedArticles` export), every item URL absolute against
   `buildInput.baseUrl`, bounded to the most recent 50 entries (documented scoped
-  decision — neither the brief nor DEC-097 fixes a feed item count).
+  decision — neither the brief nor this renderer's own styling decision fixes a
+  feed item count).
 - **Sitemap** (`src/core/internal/sitemap.js`): `/sitemap.xml` over every page
   `internal/page-kinds.js` generated that this renderer did not itself mark
   `noindex` (unlisted content), deterministically sorted by each entry's own
@@ -394,9 +451,10 @@ on top of S2-T06's page kinds:
   `/search-index.json`, a deterministic JSON document indexing every published
   `article`/`page` record's title, description, a bounded plain-text excerpt,
   tags and timestamps. Its shape is a documented scoped decision (neither the
-  brief nor DEC-097 fixes one). **No runtime search JavaScript accompanies it**
-  — the Light/Dark/System appearance controller (S2-T07) remains the only
-  browser bootstrap this renderer ever emits in all of S2 (acceptance test C).
+  brief nor this renderer's own styling decision fixes one). **No runtime search
+  JavaScript accompanies it** — the Light/Dark/System appearance controller
+  remains the only browser bootstrap this renderer ever emits (acceptance test
+  C).
 - **SEO/Open-Graph/Twitter/localization metadata**: every generated page's
   `<head>` now carries a viewport meta, an optional description, an optional
   `robots` directive (`noindex, follow` for `status: "unlisted"` content and for
@@ -406,16 +464,15 @@ on top of S2-T06's page kinds:
   `<link>`s. **hreflang** is a documented scope decision, not a silent omission:
   `build-input:2.0.0` has no translation/locale-variant linkage between distinct
   `content[]` records (see `internal/seo.js`'s module documentation), so no
-  `<link rel="alternate" hreflang="...">` is ever emitted in S2.
-- **`404.html`**: the S2-T06 `error` page kind's pure `renderErrorPageBody`, now
-  actually wired into `renderPublication` at DEC-097's exact `errorDocumentKey`
+  `<link rel="alternate" hreflang="...">` is ever emitted by this renderer.
+- **`404.html`**: the `error` page kind's pure `renderErrorPageBody`, now
+  actually wired into `renderPublication` at the fixed `errorDocumentKey`
   (`internal/route.js#errorDocumentPath`) — `404.html` at the root, or
   `<basePath>/404.html` otherwise.
-- **Redirect documents**: unchanged from S2-T03
+- **Redirect documents**: unchanged from the renderer adapter
   (`internal/route.js#renderRedirectDocument`) — every authored redirect was
   already an ordinary generated artifact with manifest status fixed at `200`;
-  this task's own scope note is documenting that fact here, not re-implementing
-  it.
+  this is documenting that fact here, not re-implementing it.
 - **Print CSS hookup** (`src/core/internal/print-stylesheet.js`): every page's
   `<head>` carries a `<link rel="stylesheet" media="print">` at the documented
   conventional path `<basePath>/assets/theme/print.css`. A selected theme's own
@@ -430,11 +487,16 @@ by the route's own fixed output path.
 
 ## Prerequisites
 
-- Node.js 24.18.0
-- npm 11.16.0
+- Node.js >= 24.0.0 (this repository's own development/CI toolchain is Node.js
+  24.18.0)
+- npm >= 11.0.0 (this repository's own development/CI toolchain is npm 11.16.0)
 
-Both are enforced by `package.json` `engines`/`devEngines`; `.nvmrc` and
-`.node-version` carry the same pin.
+`package.json`'s published `engines` field declares the supported _range_
+(TPL-H5 fix: an exact pin published in the tarball rejects every consumer not on
+that precise patch version, including under a consumer's own `engine-strict`
+setting). This repository's own exact toolchain is pinned separately in
+`devEngines` (evaluated only for this project root, never for a consumer) and in
+`.nvmrc`/`.node-version`.
 
 ## Commands
 
@@ -443,11 +505,15 @@ npm install
 npm run verify
 ```
 
-`npm run verify` runs, in order: Prettier format check, ESLint,
+`npm run verify` (this description is kept in sync with `package.json`'s own
+`verify` script string by `test/readme-verify-description.test.js`, not
+hand-maintained) runs, in order: Prettier format check, ESLint,
 `tsc --checkJs --noEmit`, the dependency-cruiser
 architecture/module-tree-absence gate, `jscpd` duplication scan, the
-`contracts/*.jcs` canonical-form check, `node --test`, the license inventory
-check, and `cyclonedx-npm` SBOM generation plus presence check.
+`contracts/*.jcs` canonical-form check, the no-local-schema-pin check,
+`node --test`, the license inventory check, the SBOM currency check
+(`sbom:check` compares `sbom.cdx.json` against the current lockfile — it is not
+a presence check), the workflow-pin check, and `npm audit --audit-level=high`.
 
 Individual gates:
 
@@ -458,21 +524,25 @@ npm run lint            # ESLint flat config
 npm run typecheck       # tsc --checkJs --noEmit against types/index.d.ts
 npm run architecture    # dependency-cruiser: no src/modules/, no circular deps
 npm run duplication     # jscpd, 3% / 50 tokens
-npm run contracts:generate  # (re)write contracts/*.jcs placeholders
+npm run contracts:generate  # (re)write contracts/*.jcs from their reviewed source modules
 npm run contracts:check     # fail if committed contracts drifted
+npm run schema-pin:check    # fail on a file: @rathnasgala2/schemas specifier
 npm test                # node --test
 npm run licenses:generate   # (re)write THIRD_PARTY_LICENSES.json
 npm run licenses:check      # fail if it drifted from package-lock.json
 npm run sbom:generate       # cyclonedx-npm -> sbom.cdx.json
-npm run sbom:check          # fail if sbom.cdx.json is missing
+npm run sbom:check          # fail if sbom.cdx.json is stale against package-lock.json
+npm run workflows:check     # fail if a GitHub Actions ref is not SHA-pinned
+npm run workflows:drift     # fail if workflow files diverge from their own baseline
+npm run audit               # npm audit --audit-level=high
 ```
 
 ## Package layout
 
 ```text
 src/core/                                # the only source root
-contracts/render-policy.jcs              # normalized-body policy identity (S2-T04, real content)
-contracts/theme-styling-contract.jcs     # published styling catalog (S2-T12, real and closed)
+contracts/render-policy.jcs              # normalized-body policy identity (real content)
+contracts/theme-styling-contract.jcs     # published styling catalog (real and closed)
 ```
 
 No `src/modules/` tree, module import edge, registration stub, module
@@ -481,7 +551,7 @@ configuration, module output or module runtime is ever admitted beside
 `only-src-core-is-a-source-root` rule both enforce this; `interactions`,
 `whitelabel`, `newsletter` and `prism` have no module directory, package,
 configuration schema, stub, output, runtime code, network target or
-compatibility promise in this MVP (DEC-097 section 2).
+compatibility promise in this MVP.
 
 ## Consuming `@rathnasgala2/schemas`
 
@@ -508,8 +578,12 @@ and `artifact-manifest` are byte-identical from 2.6.1 to 2.8.0.
 
 ## Governing documents
 
-- [Slice brief S2: author-owned publication](../../orchestration/slice-briefs/S2-author-owned-publication.md),
-  section 3 (`@rathnasgala2/template`)
-- [DEC-094](../../orchestration/decisions/DEC-094-javascript-esm-public-packages.md):
-  JavaScript ESM for public packages
-- [WORKSPACE.md](../../orchestration/WORKSPACE.md), sections 4-8 and 13
+The internal specifications this package is built against live outside this
+repository and have no public URL, so they are named here as plain text rather
+than as dead links:
+
+- Slice brief S2: author-owned publication, section 3 (`@rathnasgala2/template`)
+  (internal)
+- The internal decision record establishing JavaScript ESM for public packages
+  (internal)
+- WORKSPACE.md, sections 4-8 and 13 (internal)

package/contracts/render-policy.jcs

@@ -1 +1 @@
-{"contentSecurityPolicy":"default-src 'none'; base-uri 'none'; object-src 'none'; frame-ancestors 'none'; form-action 'none'; script-src 'self'; style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'none'; media-src 'self'; manifest-src 'self'; worker-src 'none'","highlighter":{"grammars":["bash","css","diff","java","javascript","json","jsx","markdown","markup","python","sql","tsx","typescript","yaml"],"package":"@11ty/eleventy-plugin-syntaxhighlight","tokenClasses":["atrule","attr-equals","attr-name","attr-value","bold","boolean","builtin","cdata","char","class-name","comment","constant","content","coord","deleted","deleted-sign","doctype","entity","for-or-select","function","function-variable","important","inserted","inserted-sign","interpolation","interpolation-punctuation","italic","key","keyword","namespace","null","number","operator","prefix","prolog","property","punctuation","regex","rule","selector","shebang","string","symbol","tag","template-punctuation","template-string","title","token","url","variable"],"version":"5.0.2"},"markdownIt":{"options":{"html":false,"linkify":false,"typographer":false},"package":"markdown-it","version":"14.3.1"},"name":"gala-render-policy","sanitizer":{"allowedAttributes":{"a":["href","rel"],"code":["class"],"h1":["id"],"h2":["id"],"h3":["id"],"h4":["id"],"h5":["id"],"h6":["id"],"img":["src","alt"],"ol":["start"],"pre":["class"],"span":["class"]},"allowedTags":["p","br","hr","h1","h2","h3","h4","h5","h6","ul","ol","li","blockquote","pre","code","strong","em","b","i","u","s","del","ins","sub","sup","mark","small","wbr","a","img","table","thead","tbody","tr","th","td","dl","dt","dd","figure","figcaption","span"],"allowedUrlSchemes":["https","http","mailto"],"package":"sanitize-html","version":"2.17.7"},"version":"2.0.0"}
+{"contentSecurityPolicy":"default-src 'none'; base-uri 'none'; object-src 'none'; frame-ancestors 'none'; form-action 'none'; script-src 'self'; style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'none'; media-src 'self'; manifest-src 'self'; worker-src 'none'","contentSecurityPolicyHeaderOnlyDirectives":["frame-ancestors 'none'"],"contentSecurityPolicyMeta":"default-src 'none'; base-uri 'none'; object-src 'none'; form-action 'none'; script-src 'self'; style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'none'; media-src 'self'; manifest-src 'self'; worker-src 'none'","highlighter":{"grammars":["bash","css","diff","java","javascript","json","jsx","markdown","markup","python","sql","tsx","typescript","yaml"],"package":"@11ty/eleventy-plugin-syntaxhighlight","tokenClasses":["atrule","attr-equals","attr-name","attr-value","bold","boolean","builtin","cdata","char","class-name","comment","constant","content","coord","deleted","deleted-sign","doctype","entity","for-or-select","function","function-variable","important","inserted","inserted-sign","interpolation","interpolation-punctuation","italic","key","keyword","namespace","null","number","operator","prefix","prolog","property","punctuation","regex","rule","selector","shebang","string","symbol","tag","template-punctuation","template-string","title","token","url","variable"],"version":"5.0.2"},"markdownIt":{"options":{"html":false,"linkify":false,"typographer":false},"package":"markdown-it","version":"14.3.1"},"name":"gala-render-policy","sanitizer":{"allowedAttributes":{"a":["href","rel"],"code":["class"],"h1":["id"],"h2":["id"],"h3":["id"],"h4":["id"],"h5":["id"],"h6":["id"],"img":["src","alt"],"ol":["start"],"pre":["class"],"span":["class"]},"allowedTags":["p","br","hr","h1","h2","h3","h4","h5","h6","ul","ol","li","blockquote","pre","code","strong","em","b","i","u","s","del","ins","sub","sup","mark","small","wbr","a","img","table","thead","tbody","tr","th","td","dl","dt","dd","figure","figcaption","span"],"allowedUrlSchemes":["https","http","mailto"],"package":"sanitize-html","version":"2.17.7"},"version":"2.0.0"}