@rathnasgala2/template 2.0.0 → 2.2.0

package/src/core/internal/media/png-codec.js

@@ -6,11 +6,11 @@
  * (grayscale+alpha) and 6 (truecolor+alpha), bit depth 8 only, no
  * interlacing. Any other bit depth, interlace method, or PNG structure this
  * module does not recognize is a `MEDIA_FORMAT_INVALID` rejection — never a
- * best-effort guess — matching the fail-closed posture the brief and
- * DEC-097 both require of this pipeline. This is a deliberately smaller
- * surface than DEC-097's own closed `gala-theme-binary-assets-v2` PNG
- * grammar (which the theme packages use for passive presentation assets);
- * author media only needs a decode path sufficient to bound, re-derive
+ * best-effort guess — matching the fail-closed posture required throughout
+ * this pipeline. This is a deliberately smaller surface than this
+ * renderer's own closed passive-theme-asset PNG grammar (which the theme
+ * packages use for passive presentation assets); author media only needs a
+ * decode path sufficient to bound, re-derive
  * orientation-free pixels from, and re-encode ordinary photographic/graphic
  * uploads.
  *
@@ -371,8 +371,8 @@ function crc32(buffer) {
  * Deterministically encode an RGBA8 raster as a minimal truecolor+alpha PNG:
  * one `IHDR`, one "filter type 0 (none)" `IDAT` stream at a fixed zlib
  * level/strategy, one `IEND`. No ancillary chunk (no metadata) is ever
- * emitted, matching the brief's "strip nonessential metadata" requirement
- * for every output this renderer produces.
+ * emitted, stripping nonessential metadata
+ * from every output this renderer produces.
  *
  * @param {{width: number, height: number, rgba: Buffer}} raster the raster
  *   to encode

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

@@ -4,8 +4,8 @@
  *
  * IEEE 754 double-precision arithmetic is fully deterministic — the same
  * inputs always produce the same bit pattern on any conforming engine — so
- * this box filter (unlike a lossy codec's own pixel decode, which DEC-097
- * notes is implementation-dependent) is safe to use directly for the
+ * this box filter (unlike a lossy codec's own pixel decode, which is
+ * implementation-dependent) is safe to use directly for the
  * two-clean-build byte-equality requirement: the same source raster and the
  * same target width always produce the same resized raster, and therefore,
  * fed through this pipeline's own deterministic encoders, the same

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

@@ -1,10 +1,10 @@
 /**
  * Media-type sniffing from decoded bytes, never from a file extension or a
- * caller-declared media type (brief S2 section 3: "Establish media type from
- * decoded bytes, not extension").
+ * caller-declared media type: media type is established from
+ * decoded bytes, not extension.
  *
- * SVG is deliberately excluded from this sniffer's admitted output set: "SVG
- * is never processed as author media" (brief S2 section 3). Any byte
+ * SVG is deliberately excluded from this sniffer's admitted output set: SVG
+ * is never processed as author media. Any byte
  * sequence recognizable as SVG/XML is classified `'svg'` here specifically
  * so the caller can reject it with a distinct, explicit
  * `MEDIA_SVG_REJECTED` reason rather than falling through to a generic

package/src/core/internal/media/theme-svg-sanitizer.js

@@ -0,0 +1,278 @@
+/**
+ * The closed admission grammar a theme-declared passive SVG asset must pass
+ * before it is copied into a published artifact (TPL-C2, prerequisite for
+ * TPL-H6's iconography decision).
+ *
+ * Author-supplied SVG is unconditionally rejected by the media pipeline
+ * (`internal/media/sniff.js`'s `'svg'` classification, `MEDIA_SVG_REJECTED`
+ * in `internal/media/pipeline.js`) — SVG is active content (it admits
+ * `<script>`, event-handler attributes and external references) and the
+ * render-policy's own residual-active-content scan explicitly forbids it in
+ * markdown-derived HTML. A theme package is a lower-trust supply-chain input
+ * than the repository owner's own authored content, so it cannot be held to
+ * a looser standard: this module is the one path an SVG byte sequence may
+ * take to reach a published artifact, and it applies its own closed
+ * tag/attribute/scheme allowlist — independent of, and strictly narrower
+ * than, `sanitize-html`'s author-content configuration in
+ * `internal/content-security.js` — followed by the same class of fail-closed
+ * residual-scan backstop that pipeline uses.
+ *
+ * Scope: this grammar targets exactly one use case — a small, static,
+ * decorative icon or mark referenced from theme CSS (`::before`/`::after`
+ * `content: url(...)`, `background-image`, or an `<img>`/`<use>` a future
+ * theme ships). It is deliberately conservative: no `<script>`, no `<style>`
+ * (inline CSS can itself carry `url()` external references), no
+ * `<foreignObject>` (arbitrary embedded HTML), no `<image>` (a raster/SVG
+ * reference of its own, which would need this same admission recursively),
+ * no event-handler attribute of any kind, and no attribute whose value is a
+ * URL reference other than a same-document `#fragment` (so `<use href="#id">`
+ * referencing a `<symbol>` defined earlier in the same file works; anything
+ * that could reach off-document content does not).
+ */
+
+import sanitizeHtml from 'sanitize-html';
+
+import { ThemeAssetError } from '../../errors.js';
+
+/** @type {string} the reason code every rejection in this module carries. */
+export const THEME_SVG_REJECTED_CODE = 'THEME_ASSET_SVG_REJECTED';
+
+/**
+ * The closed SVG element allowlist: structural/grouping and shape elements,
+ * gradients/clipping used for flat icon artwork, and `<title>`/`<desc>` for
+ * accessible names. No scripting, styling, foreign-content or
+ * external-media element is admitted.
+ *
+ * @type {readonly string[]}
+ */
+const ALLOWED_SVG_TAGS = Object.freeze([
+  'svg',
+  'g',
+  'defs',
+  'symbol',
+  'use',
+  'title',
+  'desc',
+  'path',
+  'rect',
+  'circle',
+  'ellipse',
+  'line',
+  'polyline',
+  'polygon',
+  'clipPath',
+  'mask',
+  'linearGradient',
+  'radialGradient',
+  'stop',
+]);
+
+/** @type {readonly string[]} presentation/geometry attributes admitted on
+ * every allowed tag (a closed union, not per-tag — {@link assertNoResidualActiveSvgContent}
+ * is the fail-closed backstop for anything this allowlist under-restricts). */
+const COMMON_SVG_ATTRIBUTES = Object.freeze([
+  'id',
+  'class',
+  'role',
+  'aria-hidden',
+  'aria-label',
+  'focusable',
+  'viewBox',
+  'width',
+  'height',
+  'x',
+  'y',
+  'x1',
+  'y1',
+  'x2',
+  'y2',
+  'cx',
+  'cy',
+  'r',
+  'rx',
+  'ry',
+  'd',
+  'points',
+  'transform',
+  'fill',
+  'fill-rule',
+  'fill-opacity',
+  'stroke',
+  'stroke-width',
+  'stroke-linecap',
+  'stroke-linejoin',
+  'stroke-dasharray',
+  'stroke-opacity',
+  'opacity',
+  'clip-path',
+  'clip-rule',
+  'mask',
+  'offset',
+  'stop-color',
+  'stop-opacity',
+  'gradientUnits',
+  'gradientTransform',
+  'preserveAspectRatio',
+  'xmlns',
+]);
+
+/** @type {import('sanitize-html').IOptions} */
+const SVG_SANITIZE_OPTIONS = {
+  allowedTags: [...ALLOWED_SVG_TAGS],
+  allowedAttributes: Object.fromEntries(
+    ALLOWED_SVG_TAGS.map((tag) => [
+      tag,
+      tag === 'use'
+        ? [...COMMON_SVG_ATTRIBUTES, 'href', 'xlink:href']
+        : [...COMMON_SVG_ATTRIBUTES],
+    ]),
+  ),
+  // `href`/`xlink:href` are only ever admitted on `use` above, and only a
+  // same-document fragment reference is a legal value (enforced below by
+  // {@link assertNoResidualActiveSvgContent}, since sanitize-html's own
+  // scheme allowlist does not distinguish "no scheme" from "fragment-only").
+  allowedSchemesByTag: { use: [] },
+  allowProtocolRelative: false,
+  nonTextTags: [
+    'script',
+    'style',
+    'foreignObject',
+    'image',
+    'animate',
+    'animateTransform',
+    'animateMotion',
+    'set',
+    'iframe',
+  ],
+  disallowedTagsMode: 'discard',
+  parser: { xmlMode: true, decodeEntities: true },
+};
+
+/** @type {readonly RegExp[]} fail-closed backstop patterns; a hit here is
+ * this module's own configuration defect, never expected of admitted
+ * content — mirrors `content-security.js`'s
+ * `RESIDUAL_ACTIVE_CONTENT_PATTERNS` backstop pattern. */
+const RESIDUAL_ACTIVE_SVG_PATTERNS = Object.freeze([
+  /<script[\s>/]/i,
+  /<style[\s>/]/i,
+  /<foreignobject[\s>/]/i,
+  /<image[\s>/]/i,
+  /<iframe[\s>/]/i,
+  /\son[a-z]+\s*=/i,
+  /url\(\s*['"]?(?:https?:)?\/\//i,
+  /url\(\s*['"]?data:/i,
+]);
+
+/**
+ * @param {string} sanitized the sanitize-html output
+ * @returns {void}
+ */
+function assertNoResidualActiveSvgContent(sanitized) {
+  for (const pattern of RESIDUAL_ACTIVE_SVG_PATTERNS) {
+    if (pattern.test(sanitized)) {
+      throw new ThemeAssetError(
+        THEME_SVG_REJECTED_CODE,
+        `sanitized theme SVG still matches a forbidden pattern (${pattern})`,
+      );
+    }
+  }
+  // Every href/xlink:href that survived sanitization must be a same-document
+  // fragment reference; sanitize-html's own scheme allowlist admits a
+  // schemeless value (including a bare fragment) without distinguishing it
+  // from, say, a schemeless relative path, so this is checked explicitly.
+  for (const match of sanitized.matchAll(
+    /(?:href|xlink:href)\s*=\s*"([^"]*)"/gi,
+  )) {
+    if (!match[1].startsWith('#')) {
+      throw new ThemeAssetError(
+        THEME_SVG_REJECTED_CODE,
+        `theme SVG href must be a same-document fragment reference, got ${JSON.stringify(match[1])}`,
+      );
+    }
+  }
+}
+
+/**
+ * Reject, rather than silently strip, any of the specific constructs the
+ * fix requires an SVG sanitizer to police (no script, no event handlers, no
+ * external references): a theme package is untrusted supply-chain input, so
+ * a file that *contains* one of these is treated as a rejected asset, not
+ * quietly laundered into a smaller, safe file the theme author never
+ * reviewed. The allowlist pass below is defense-in-depth on top of this,
+ * narrowing an already-clean file to the admitted tag/attribute vocabulary.
+ *
+ * @param {string} source the raw SVG text
+ * @returns {void}
+ */
+function assertNoForbiddenSvgConstructs(source) {
+  if (/<!doctype/i.test(source) || /<!entity/i.test(source)) {
+    throw new ThemeAssetError(
+      THEME_SVG_REJECTED_CODE,
+      'theme SVG must not declare a DOCTYPE or an XML entity',
+    );
+  }
+  if (
+    /<\s*(script|style|foreignobject|image|iframe|animate\w*|set)[\s>/]/i.test(
+      source,
+    )
+  ) {
+    throw new ThemeAssetError(
+      THEME_SVG_REJECTED_CODE,
+      'theme SVG must not contain a <script>, <style>, <foreignObject>, ' +
+        '<image>, <iframe>, animation or <set> element',
+    );
+  }
+  if (/\son[a-z]+\s*=/i.test(source)) {
+    throw new ThemeAssetError(
+      THEME_SVG_REJECTED_CODE,
+      'theme SVG must not carry an event-handler attribute',
+    );
+  }
+  for (const match of source.matchAll(
+    /(?:href|xlink:href)\s*=\s*(['"])(.*?)\1/gis,
+  )) {
+    if (!match[2].startsWith('#')) {
+      throw new ThemeAssetError(
+        THEME_SVG_REJECTED_CODE,
+        `theme SVG href must be a same-document fragment reference, got ${JSON.stringify(match[2])}`,
+      );
+    }
+  }
+  if (/url\(\s*['"]?(?:https?:)?\/\//i.test(source)) {
+    throw new ThemeAssetError(
+      THEME_SVG_REJECTED_CODE,
+      'theme SVG must not reference an external url()',
+    );
+  }
+  if (/url\(\s*['"]?data:/i.test(source)) {
+    throw new ThemeAssetError(
+      THEME_SVG_REJECTED_CODE,
+      'theme SVG must not embed a data: url()',
+    );
+  }
+}
+
+/**
+ * Sanitize one theme-declared SVG passive asset's exact bytes against the
+ * closed grammar above, failing closed on anything it does not admit.
+ *
+ * @param {Buffer} bytes the file's raw bytes (already sniffed as `'svg'` by
+ *   {@link ../media/sniff.js})
+ * @returns {Buffer} the sanitized UTF-8 SVG bytes, safe to publish
+ */
+export function sanitizeThemeSvg(bytes) {
+  const source = bytes.toString('utf8');
+  assertNoForbiddenSvgConstructs(source);
+  const sanitized = sanitizeHtml(source, SVG_SANITIZE_OPTIONS);
+  if (sanitized.trim().length === 0 || !/<svg[\s>]/i.test(sanitized)) {
+    throw new ThemeAssetError(
+      THEME_SVG_REJECTED_CODE,
+      'theme SVG did not survive sanitization as a root <svg> element',
+    );
+  }
+  // Fail-closed backstop over the allowlist pass above — a hit here is this
+  // module's own configuration defect, never expected of admitted content
+  // (the explicit rejection checks above should already have caught it).
+  assertNoResidualActiveSvgContent(sanitized);
+  return Buffer.from(sanitized, 'utf8');
+}

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

@@ -5,11 +5,11 @@
  * the `RIFF`/`WEBP` container framing and the `VP8 `/`VP8L` chunk header
  * closely enough to reject a malformed or oversized file and to read the
  * format's own declared width/height, but it does not run a full VP8/VP8L
- * entropy decoder — DEC-097's own closed `gala-theme-binary-assets-v2`
- * profile requires a complete bounded VP8/VP8L bitstream decode for
+ * entropy decoder — this renderer's closed passive-theme-asset decoder
+ * requires a complete bounded VP8/VP8L bitstream decode for
  * *passive theme assets*; hand-authoring an equivalent, independently
  * verifiable decoder for *author media* was judged out of proportion to
- * this task's scope and is flagged to the orchestrator as a follow-up
+ * this module's scope and is flagged to the orchestrator as a follow-up
  * rather than attempted partially. What this module still enforces, fully:
  * exact container framing, a single recognized image chunk (any `VP8X`,
  * animation, or a second image chunk rejects), and the shared

package/src/core/internal/messages.js

@@ -1,17 +1,17 @@
 /**
- * Core-owned chrome message catalog (brief S2 section 3: the semantic
- * skeleton and navigation renderer; task packet S2-T06: "all user-visible
- * chrome strings coming from a message catalog (not inline literals) so
- * localization can find them").
+ * Core-owned chrome message catalog: every user-visible chrome string comes
+ * from a message catalog, not an inline literal, so localization can find
+ * them.
  *
  * Every user-visible string this package's own generated chrome (skip link,
  * navigation labels, breadcrumb labels, pagination controls, generated
- * listing-page headings, the error page kind, the S2-T07 Light/Dark/System
+ * listing-page headings, the error page kind, the Light/Dark/System
  * appearance control's label and its three option labels) emits is looked
  * up here by key
- * rather than written inline at its call site. S2 authors exactly one
- * catalog, `en` (the only language the golden fixture's own core chrome is
- * required to exercise); per-content localization of *authored* content is
+ * rather than written inline at its call site. This renderer authors
+ * exactly one catalog, `en` (the only language the golden fixture's own
+ * core chrome is required to exercise); per-content localization of
+ * *authored* content is
  * `publication`/`content` data, not core chrome, and full chrome
  * localization (additional catalogs, a locale-selection policy) is future
  * work this module is shaped to admit without changing any call site: every

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

@@ -1,19 +1,18 @@
 /**
- * Page-kind assembly (task packet S2-T06): builds every generated page's
+ * Page-kind assembly: builds every generated page's
  * `<main>` content, breadcrumb trail and route from a validated
  * `build-input:2.0.0` instance, and the shared site chrome (header, primary
  * navigation, footer) every page kind is composed with through
  * `internal/skeleton.js`'s {@link import('./skeleton.js').renderPageBody}.
  *
- * Page kinds this module produces, matching brief S2 section 3's "Required
- * generated outputs" and task packet S2-T06's page-kind list:
+ * Page kinds this module produces:
  *
  * - `profile` — the publication's own optional profile page
  *   (`publication.profile`);
- * - `author` — one page per entry in `build-input.authors` (DEC-097 section 5:
- *   this array is already exactly the set of authors referenced by the
- *   selected content, publication contact or footer card — never an
- *   unreferenced author), at `/authors/<id>`;
+ * - `author` — one page per entry in `build-input.authors` (this array is
+ *   already exactly the set of authors referenced by the selected content,
+ *   publication contact or footer card — never an unreferenced author), at
+ *   `/authors/<id>`;
  * - `article` / `page` — one page per `content[]` record, at its own
  *   `contentFrontmatterNormalized` route;
  * - `index` — a paginated reverse-chronological listing of every
@@ -27,10 +26,10 @@
  *   plus one `/archive` root page linking to each year.
  *
  * The `error` page kind ({@link renderErrorPageBody}) is exported as a pure
- * function, not wired into any generated route here: brief S2 section 3
- * assigns the one generated `404.html` artifact to S2-T08, which this task
- * packet's own scope notes forbid touching. S2-T08 composes its `404.html`
- * from this same function.
+ * function, not wired into any generated route here: the one generated
+ * `404.html` artifact is assembled elsewhere, which this module's own scope
+ * notes forbid touching. That module composes its `404.html` from this same
+ * function.
  *
  * Every generated page's own `route` field (see {@link GeneratedPage}) is an
  * un-joined `canonicalRoute`, in the same convention `internal/index.js`
@@ -39,16 +38,18 @@
  * *link href* this module writes into a page's own body (breadcrumbs, tag and
  * series listings, pagination controls) is, by contrast, already joined with
  * `basePath` here, because it is read back only as literal HTML text, never
- * re-joined by a caller. This mirrors DEC-097 section 5's navigation
- * normalization rule: an *authored* navigation item's route is used exactly
- * as authored, never synthesized or rewritten (so `internal/skeleton.js`'s
- * navigation renderer never joins it), while every route this renderer itself
- * derives (every page kind here) is basePath-joined at the point it becomes
- * link text, exactly like S2-T03's own redirect/content route projection.
+ * re-joined by a caller. This mirrors the navigation normalization rule: an
+ * *authored* navigation item's route is used exactly as authored, never
+ * synthesized or rewritten (so `internal/skeleton.js`'s navigation renderer
+ * never joins it), while every route this renderer itself derives (every
+ * page kind here) is basePath-joined at the point it becomes link text,
+ * exactly like the redirect/content route projection elsewhere in this
+ * renderer.
  *
  * Every listing here is a deliberately scoped decision this module documents
  * rather than assumes: page size, sort tie-break and the tag/series/archive
- * root pages are not specified verbatim by the brief text this task read.
+ * root pages have no externally fixed specification this renderer conforms
+ * to verbatim.
  */
 
 import {
@@ -60,25 +61,23 @@ import {
 import { getMessages } from './messages.js';
 import { resolveTextDirection } from './text-direction.js';
 import { routeSegmentForLabel } from './route-labels.js';
-import { joinBasePathAndRoute } from './route.js';
+import { derivePublicBasePath, joinPublicRoute } from './route.js';
 
 /** Listing page size (index and per-year archive pages). Scoped decision:
- * the brief does not fix a page size; 10 is a deterministic, documented
- * default with no author-facing configuration surface in S2.
+ * this renderer has no externally fixed page size; 10 is a deterministic,
+ * documented default with no author-facing configuration surface.
  * @type {number} */
 export const LISTING_PAGE_SIZE = 10;
 
 /**
- * The DEC-097-style semantic template-owned attribute this renderer sets on
- * every generated page's `<body>` (S2-T12: `contracts/theme-styling-contract.jcs`
- * exposes this as a public theme hook, one per {@link PAGE_KIND_VALUES}
- * entry, so a theme can vary presentation by page kind — e.g. a different
- * article vs. listing background — without the template ever promoting a
- * private/incidental selector). Scoped decision: this attribute did not
- * exist before S2-T12; it is this task packet's own addition, introduced
- * specifically because the published styling contract needs a
- * page-kind-targeting hook the brief's "every page-kind ... class/attribute"
- * language calls for.
+ * The semantic template-owned attribute this renderer sets on every
+ * generated page's `<body>`: `contracts/theme-styling-contract.jcs` exposes
+ * this as a public theme hook, one per {@link PAGE_KIND_VALUES} entry, so a
+ * theme can vary presentation by page kind — e.g. a different article vs.
+ * listing background — without the template ever promoting a
+ * private/incidental selector. This attribute is a deliberate addition,
+ * introduced specifically because the published styling contract needs a
+ * page-kind-targeting hook.
  *
  * @type {string}
  */
@@ -87,8 +86,8 @@ export const PAGE_KIND_ATTRIBUTE = 'data-gala-page-kind';
 /**
  * Every value {@link PAGE_KIND_ATTRIBUTE} may carry: every {@link GeneratedPage}
  * `kind` plus the synthetic `error` kind (`internal/index.js`'s always-present
- * generated `404.html`), sorted by UTF-8 bytes (DEC-097's own attribute-value
- * sort convention).
+ * generated `404.html`), sorted by UTF-8 bytes (this renderer's own
+ * attribute-value sort convention throughout).
  *
  * @type {readonly string[]}
  */
@@ -135,8 +134,8 @@ function paginate(items, pageSize) {
 
 /**
  * Resolve an author's display name by ID, failing closed on a dangling
- * reference (an adapter defect: `resolvedAuthorIds` is schema/DEC-097
- * guaranteed to resolve).
+ * reference (an adapter defect: `resolvedAuthorIds` is schema-guaranteed to
+ * resolve).
  *
  * @param {ReadonlyMap<string, import('../../../types/index.d.ts').AuthorNormalized>} authorsById
  * @param {string} authorId
@@ -161,30 +160,29 @@ function requireAuthor(authorsById, authorId) {
  * @property {string} bodyHtml the page's complete `<main>` inner HTML,
  *   starting with exactly one `<h1>`
  * @property {string} [breadcrumbHtml] an optional already-rendered breadcrumb
- * @property {string} [description] task packet S2-T08: an optional plain-text
+ * @property {string} [description] an optional plain-text
  *   description this page's SEO/Open-Graph/Twitter `<meta>` tags are built
  *   from (never HTML, never the sanitized body — a distinct authored or
  *   publication-level plain-text field)
- * @property {'website' | 'article' | 'profile'} [ogType] task packet S2-T08:
+ * @property {'website' | 'article' | 'profile'} [ogType]
  *   the Open Graph `og:type` this page kind maps to; defaults to `'website'`
  *   when omitted
  * @property {{path: string, sourceDigest: string} | undefined} [socialImageRef]
- *   task packet S2-T08: an optional `resolvedFile` reference this page's
+ *   an optional `resolvedFile` reference this page's
  *   social image is resolved from (the caller, `src/core/index.js`, is the
  *   one place that can turn this into an absolute derivative URL, because
- *   only it has run the S2-T05 media pipeline and knows the derivative
+ *   only it has run the media pipeline and knows the derivative
  *   output path a given `sourceDigest` produced)
- * @property {string} [robotsContent] task packet S2-T08: an optional
+ * @property {string} [robotsContent] an optional
  *   `<meta name="robots">` content value (e.g. `'noindex, follow'` for
  *   `status: "unlisted"` content); omitted entirely for ordinarily indexable
  *   pages, matching this renderer's "documented, not silently assumed" style
  *   elsewhere — every page kind's robots decision is made once, here, rather
  *   than re-derived by every later consumer (sitemap, search index)
- * @property {string} [lastModified] task packet S2-T08: an optional
+ * @property {string} [lastModified] an optional
  *   `rfc3339` timestamp the generated sitemap's `<lastmod>` for this page is
  *   drawn from — always derived from authored content timestamps
- *   (`publishedAt`/`updatedAt`), never build time (brief S2 section 3:
- *   "sitemap ... `lastmod` from content timestamps not build time"). Omitted
+ *   (`publishedAt`/`updatedAt`), never build time. Omitted
  *   for a page kind with no natural underlying timestamp (`profile`,
  *   `author`), which the generated sitemap then emits with no `<lastmod>`
  *   element at all (a sitemap's own `<lastmod>` is optional per the Sitemaps
@@ -194,7 +192,7 @@ function requireAuthor(authorsById, authorId) {
 /**
  * The reverse-chronological, deterministically tie-broken set of every
  * `status: "published"`, `kind: "article"` record — the exact selection and
- * ordering the `index` page kind paginates, and (task packet S2-T08) the
+ * ordering the `index` page kind paginates, and the
  * same selection the generated feeds draw from, so a feed's item order can
  * never drift from the index listing's own order. Extracted to its own
  * export rather than duplicated, since `internal/fs-walk.js`'s duplication
@@ -224,7 +222,7 @@ export function selectPublishedArticles(content) {
 /**
  * The most recent of a content record's own `updatedAt` (when authored) or
  * `publishedAt` — this renderer's one definition of "a content record's own
- * last-modified instant" (task packet S2-T08's sitemap `<lastmod>` and the
+ * last-modified instant" (the sitemap's `<lastmod>` and the
  * static search index both read this, rather than each re-deriving it).
  *
  * @param {import('../../../types/index.d.ts').ContentFrontmatterNormalized} frontmatter
@@ -237,7 +235,7 @@ export function contentLastModified(frontmatter) {
 /**
  * The latest {@link contentLastModified} across a non-empty set of records —
  * this renderer's definition of "a generated listing page's own
- * `<lastmod>`" (task packet S2-T08): the most recent authored timestamp
+ * `<lastmod>`": the most recent authored timestamp
  * among the content actually shown on that page, never build time.
  *
  * @param {readonly import('../../../types/index.d.ts').ContentBuildRecord[]} records
@@ -266,7 +264,8 @@ function latestContentTimestamp(records) {
  *   order
  */
 export function buildGeneratedPages(validatedInput) {
-  const { publication, authors, content, basePath } = validatedInput;
+  const { publication, authors, content, basePath, baseUrl } = validatedInput;
+  const publicBasePath = derivePublicBasePath(baseUrl, basePath);
   const messages = getMessages(publication.defaultLanguage);
   const authorsById = new Map(authors.map((author) => [author.id, author]));
 
@@ -274,7 +273,7 @@ export function buildGeneratedPages(validatedInput) {
    * @param {string} route an un-joined route
    * @returns {string} the `basePath`-joined absolute route
    */
-  const site = (route) => joinBasePathAndRoute(basePath, route);
+  const site = (route) => joinPublicRoute(publicBasePath, route);
 
   /**
    * @param {import('../../../types/index.d.ts').ContentBuildRecord} record
@@ -682,10 +681,10 @@ export function buildGeneratedPages(validatedInput) {
 }
 
 /**
- * Render the `error` page kind's `<main>` body (task packet S2-T06). This is
+ * Render the `error` page kind's `<main>` body. This is
  * a pure function with no route/build-input dependency, exported for a
- * future caller (S2-T08's generated `404.html`, out of this task packet's
- * scope) and for this repository's own structural/golden tests.
+ * caller elsewhere (the generated `404.html`, assembled outside this module)
+ * and for this repository's own structural/golden tests.
  *
  * @param {object} options rendering options
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages