@rathnasgala2/template 2.0.0 → 2.2.0

package/src/core/internal/render-policy-content.js

@@ -1,7 +1,7 @@
 /**
- * The single source of truth for `contracts/render-policy.jcs`'s content
- * (brief S2 section 3 "Markdown, sanitizer, highlighter" and "Per-artifact
- * CSP baseline"; DEC-097 section 5 `renderPolicyIdentity`).
+ * The single source of truth for `contracts/render-policy.jcs`'s content:
+ * the markdown, sanitizer, highlighter and per-artifact CSP baseline, and
+ * the `renderPolicyIdentity` derived from them.
  *
  * `scripts/generate-contracts.mjs` emits this exact document as compact JCS
  * to `contracts/render-policy.jcs`; `src/core/internal/content-security.js`
@@ -17,9 +17,9 @@
 export const RENDER_POLICY_NAME = 'gala-render-policy';
 
 /**
- * Byte-equal to the template lock's `contractVersion` (DEC-097 section 5),
- * which every S2 `build-input:2.0.0` fixture carries as the literal string
- * `"2.0.0"` (matches `manifest.js`'s `buildInputContractVersion`).
+ * Byte-equal to the template lock's `contractVersion`, which every
+ * `build-input:2.0.0` fixture in this repository carries as the literal
+ * string `"2.0.0"` (matches `manifest.js`'s `buildInputContractVersion`).
  *
  * @type {string}
  */
@@ -31,7 +31,7 @@ export const MARKDOWN_IT_PACKAGE = 'markdown-it';
 export const MARKDOWN_IT_VERSION = '14.3.1';
 
 /**
- * The exact markdown-it construction options brief S2 section 3 requires.
+ * The exact markdown-it construction options this renderer requires.
  *
  * @type {{html: false, linkify: false, typographer: false}}
  */
@@ -56,7 +56,7 @@ export const ALLOWED_URL_SCHEMES = Object.freeze(['https', 'http', 'mailto']);
 
 /**
  * The closed allowlist of tags this renderer ever emits from author
- * markdown: "semantic text and content tags" only (brief S2 section 3).
+ * markdown: semantic text and content tags only.
  * No form, frame, SVG, MathML, script, style, object or template element is
  * ever admitted.
  *
@@ -110,8 +110,7 @@ export const ALLOWED_TAGS = Object.freeze([
 /**
  * The closed per-tag attribute allowlist. `id` is admitted only on headings
  * (this renderer's own generated heading IDs); `style`, every `on*` handler,
- * `srcdoc` and every other undeclared attribute is always stripped (brief S2
- * section 3).
+ * `srcdoc` and every other undeclared attribute is always stripped.
  *
  * @type {Readonly<Record<string, readonly string[]>>}
  */
@@ -138,7 +137,7 @@ export const HIGHLIGHTER_VERSION = '5.0.2';
 /**
  * The closed grammar-name catalog the owned highlighter accepts. A fence
  * language outside this list always falls back to escaped, unhighlighted
- * code (brief S2 section 3).
+ * code.
  *
  * @type {readonly string[]}
  */
@@ -167,8 +166,8 @@ export const HIGHLIGHT_GRAMMARS = Object.freeze(
  * can produce (Prism's documented generic token set plus this
  * repository's own empirical sample across every admitted grammar). `token`
  * itself is always the base class; every other admitted value is a
- * secondary token-class (brief S2 section 3: "`span` elements carrying
- * `token` and admitted token-class values").
+ * secondary token-class: `span` elements carry `token` plus admitted
+ * token-class values.
  *
  * @type {readonly string[]}
  */
@@ -241,15 +240,51 @@ export const ADMITTED_LANGUAGE_CLASSES = Object.freeze(
 );
 
 /**
- * The exact per-artifact CSP baseline (brief S2 section 3). Directive order
- * is byte-exact as written in the brief; every directive's value list is
- * already sorted bytewise and duplicate-free because S2 materializes no
- * module package, configuration, output or runtime, so this string is
+ * The CSP specification explicitly ignores `frame-ancestors`
+ * (and `report-uri`/`sandbox`, neither used here) when a policy is
+ * delivered via `<meta http-equiv>` — browsers drop the directive and log a
+ * console warning on every page load. `frame-ancestors` is therefore
+ * split out as the one header-only directive: clickjacking protection for a
+ * published artifact is a hosting-layer obligation (a response header, most
+ * commonly `Content-Security-Policy` or `X-Frame-Options`), recorded here so
+ * every consuming adapter/deployment knows to add it, rather than a directive
+ * that silently does nothing inside the `<meta>` tag every page already
+ * carries.
+ *
+ * @type {readonly string[]}
+ */
+export const CSP_HEADER_ONLY_DIRECTIVES = Object.freeze([
+  "frame-ancestors 'none'",
+]);
+
+/**
+ * The exact per-artifact CSP baseline actually deliverable inside a
+ * `<meta http-equiv="Content-Security-Policy">` tag: {@link CSP_HEADER_ONLY_DIRECTIVES}
+ * is excluded. Directive order is byte-exact, minus
+ * the excluded directive; every directive's value list is already sorted
+ * bytewise and duplicate-free because this renderer materializes no module
+ * package, configuration, output or runtime, so this string is
  * byte-identical on every route.
  *
  * @type {string}
  */
-export const CONTENT_SECURITY_POLICY_BASELINE =
+export const CONTENT_SECURITY_POLICY_META_BASELINE =
+  "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'";
+
+/**
+ * The complete CSP baseline this renderer originally specified as one
+ * string — the meta-safe directives plus the header-only directive, in
+ * this fixed byte-exact order — kept only as the render-policy identity's own
+ * digest input (`renderPolicyDocument`'s `contentSecurityPolicy` field): a
+ * hosting adapter that delivers this policy as a response header, rather
+ * than a `<meta>` tag, may deliver this complete string unmodified.
+ *
+ * @type {string}
+ */
+export const CONTENT_SECURITY_POLICY_COMPLETE =
   "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'; " +
@@ -258,8 +293,7 @@ export const CONTENT_SECURITY_POLICY_BASELINE =
 /**
  * Build the exact plain-object document `contracts/render-policy.jcs`
  * publishes: `name`, `version` byte-equal to the template lock's
- * `contractVersion`, a closed sanitizer/parser catalog, and no self-digest
- * (DEC-097 section 5).
+ * `contractVersion`, a closed sanitizer/parser catalog, and no self-digest.
  *
  * @returns {Record<string, unknown>} the render-policy document
  */
@@ -267,7 +301,9 @@ export function renderPolicyDocument() {
   return {
     name: RENDER_POLICY_NAME,
     version: RENDER_POLICY_VERSION,
-    contentSecurityPolicy: CONTENT_SECURITY_POLICY_BASELINE,
+    contentSecurityPolicy: CONTENT_SECURITY_POLICY_COMPLETE,
+    contentSecurityPolicyMeta: CONTENT_SECURITY_POLICY_META_BASELINE,
+    contentSecurityPolicyHeaderOnlyDirectives: [...CSP_HEADER_ONLY_DIRECTIVES],
     markdownIt: {
       package: MARKDOWN_IT_PACKAGE,
       version: MARKDOWN_IT_VERSION,

package/src/core/internal/route-labels.js

@@ -1,7 +1,6 @@
 /**
  * Deterministic route-segment derivation for generated listing pages (tag,
- * series, archive) from an authored `plainLabel` (task packet S2-T06:
- * navigation renderer/page kinds).
+ * series, archive) from an authored `plainLabel`.
  *
  * `contentFrontmatterNormalized.tags`/`.series` are `plainLabel` values:
  * normalized Unicode text, 1..80 graphemes, with no further route-safety
@@ -12,12 +11,12 @@
  * or series label can therefore contain spaces, uppercase letters, or any
  * non-Latin script.
  *
- * `route.js` already documents that this renderer's route projection is
- * deliberately not DEC-097 section 8's full Unicode-17 percent-encoding and
+ * `route.js` already documents that this renderer's route projection
+ * deliberately excludes a full Unicode percent-encoding and
  * collision-resolution engine (out of scope; it only ever projects
  * already-schema-validated `canonicalRoute` values, never derives a route
- * from an arbitrary label). This module makes the same scoped choice for the
- * one new case S2-T06 introduces — turning an arbitrary label into a route
+ * from an arbitrary label). This module makes the same scoped choice for
+ * the one new case it introduces — turning an arbitrary label into a route
  * segment — and closes the collision risk a lossy ASCII-only slug would
  * otherwise introduce (two distinct Unicode labels both losing all their
  * characters to filtering) by always appending a short, deterministic content

package/src/core/internal/route.js

@@ -1,16 +1,14 @@
 /**
  * Route-to-output-path projection and the byte-exact generated redirect
- * document (brief S2 section 3 "Required generated outputs"; DEC-097
- * section 6 artifact-manifest redirect subsection).
+ * document.
  *
  * This module implements the `directory-index` and `explicit-file` cases of
- * DEC-097 section 7's `gala-portable-v2` route projection only for routes
- * that are already valid `canonicalRoute` strings (schema-enforced before
- * this module ever runs). The full Unicode-17 percent-encoding/collision
- * engine DEC-097 section 8 describes is out of S2-T03's scope: it governs
- * arbitrary repository-relative source paths, which this renderer never
- * derives routes from (every route it projects comes from an
- * already-schema-validated `canonicalRoute` field in `build-input`).
+ * route projection only for routes that are already valid `canonicalRoute`
+ * strings (schema-enforced before this module ever runs). A full Unicode
+ * percent-encoding/collision engine for arbitrary repository-relative
+ * source paths is out of scope here: this renderer never derives routes
+ * from source paths — every route it projects comes from an
+ * already-schema-validated `canonicalRoute` field in `build-input`.
  */
 
 /**
@@ -35,6 +33,48 @@ export function joinBasePathAndRoute(basePath, route) {
   return `/${segments.join('/')}`;
 }
 
+/**
+ * Derive the public base path every emitted URL must carry from the build
+ * input: the path component of `baseUrl` (for example `/g9/` for a GitHub
+ * project site published at `https://owner.github.io/g9/`) joined with the
+ * build input's own `basePath`. Only emitted URLs (hrefs, `src`, canonical,
+ * feed, sitemap and search-index URLs) use this value; candidate-directory
+ * output file paths keep using `basePath` alone, because the artifact is
+ * deployed at the root of the hosting site.
+ *
+ * @param {string} baseUrl the build input's validated `baseUrl`
+ * @param {string} basePath the build input's `basePath`
+ * @returns {string} the public base path with a leading slash and no double
+ *   slashes. When `baseUrl` carries a path it also has a trailing slash
+ *   (`/g9/`); with an origin-only `baseUrl` the result is exactly
+ *   `basePath`'s legacy joined form (`/` or `/blog`), so origin-only output
+ *   is byte-identical to earlier releases.
+ */
+export function derivePublicBasePath(baseUrl, basePath) {
+  const urlPath = new URL(baseUrl).pathname;
+  const joined = joinBasePathAndRoute(
+    joinBasePathAndRoute(urlPath, basePath),
+    '/',
+  );
+  return joined !== '/' && urlPath !== '/' ? `${joined}/` : joined;
+}
+
+/**
+ * Join a public base path (see {@link derivePublicBasePath}) and a route
+ * into one emitted URL path. The site root route is the public base path
+ * itself (`/site/` when `baseUrl` carries a path); every other route is
+ * joined exactly like {@link joinBasePathAndRoute}.
+ *
+ * @param {string} publicBasePath the public base path
+ * @param {string} route a `canonicalRoute`
+ * @returns {string} the emitted absolute URL path
+ */
+export function joinPublicRoute(publicBasePath, route) {
+  return route === '/'
+    ? publicBasePath
+    : joinBasePathAndRoute(publicBasePath, route);
+}
+
 /**
  * Project one already-joined absolute route to its candidate-directory-
  * relative output file path.
@@ -75,16 +115,14 @@ export function projectFilePathToRoute(filePath, profile) {
 }
 
 /**
- * Project a `basePath` to the one fixed generated error-document output path
- * DEC-097's Spaces website-configuration subsection defines: `errorDocumentKey`
- * is exactly `404.html` when `basePath` is `/`; otherwise the base path with
- * its one leading and terminal slash removed, followed by `/404.html`. This
- * is deliberately independent of the selected `RouteNormalizationProfile`
- * (`directory-index` vs `explicit-file`): the generated error document is
- * always this one literal filename, never route-normalized like an ordinary
- * content route (brief S2 section 3: "one ordinary generated `404.html` at
- * the selected base path"; DEC-097's Spaces/Pages/local-directory adapters
- * all bind their provider error-document configuration to this exact key).
+ * Project a `basePath` to the one fixed generated error-document output
+ * path: exactly `404.html` when `basePath` is `/`; otherwise the base path
+ * with its one leading and terminal slash removed, followed by
+ * `/404.html`. This is deliberately independent of the selected
+ * `RouteNormalizationProfile` (`directory-index` vs `explicit-file`): the
+ * generated error document is always this one literal filename, never
+ * route-normalized like an ordinary content route — this fixed key is what
+ * each hosting adapter's provider error-document configuration binds to.
  *
  * @param {string} basePath the build input's `basePath` (`canonicalRoute`,
  *   always starts with `/`)
@@ -143,7 +181,7 @@ export function escapeRedirectTarget(targetRoute) {
 
 /**
  * Render the exact UTF-8, no-BOM, LF-terminated generated redirect document
- * DEC-097 section 6 and brief S2 section 3 specify byte-for-byte.
+ * this renderer must produce byte-for-byte.
  *
  * @param {string} targetRoute the route this redirect document points to
  * @returns {string} the complete document text

package/src/core/internal/search-index.js

@@ -1,12 +1,10 @@
 /**
- * Static search index generation (task packet S2-T08; brief S2 section 3
- * "Required generated outputs": "static search index").
+ * Static search index generation.
  *
- * Scope note (documented, not silently assumed): neither the brief text this
- * task read nor DEC-097 fixes an exact search-index document shape (checked
- * with a full-text grep of both for "search" — no hit beyond this brief
- * phrase). This module therefore documents its own deterministic shape here,
- * matching this renderer's established style for an unfixed structural
+ * Scope note (documented, not silently assumed): this renderer has no
+ * externally fixed search-index document shape to conform to. This module
+ * therefore documents its own deterministic shape here, matching this
+ * renderer's established style for an unfixed structural
  * decision (see `internal/route-labels.js`'s route-segment grammar and the
  * media pipeline scope decisions in the package README): one JSON document,
  * `{schemaVersion, generatedAt, publication, documents[]}`, sorted by each
@@ -15,17 +13,17 @@
  * `internal/source-inventory.js#compareUtf8Bytes`).
  *
  * `generatedAt` is `buildInput.buildEpoch` — a build-input *field*, sourced
- * deterministically from the selected Git commit's own committer timestamp
- * (DEC-097 section 5), not read from the wall clock at build time — matching
+ * deterministically from the selected Git commit's own committer timestamp,
+ * not read from the wall clock at build time — matching
  * `src/core/manifest.js`'s own `manifest.generatedAt` convention, so two
  * clean builds of the same `build-input` still produce byte-identical index
  * bytes.
  *
- * No runtime search JavaScript accompanies this document (brief S2 section
- * 1: "reads completely with JavaScript disabled"; acceptance test C: "the
- * appearance controller is the only browser bootstrap" — this renderer's one
- * admitted client-side script in all of S2). This module's only output is
- * the index document's bytes; nothing wires a `<script>` to it.
+ * No runtime search JavaScript accompanies this document: this renderer
+ * must read completely with JavaScript disabled, and the appearance
+ * controller is the only client-side script it ever admits. This module's
+ * only output is the index document's bytes; nothing wires a `<script>` to
+ * it.
  *
  * Only actual authored content (`article`/`page` records, `status:
  * "published"`) is indexed — never a synthetic listing page
@@ -34,7 +32,7 @@
  * full-text search.
  */
 
-import { joinBasePathAndRoute } from './route.js';
+import { derivePublicBasePath, joinPublicRoute } from './route.js';
 import { compareUtf8Bytes } from './source-inventory.js';
 import { contentLastModified, contentRoute } from './page-kinds.js';
 
@@ -79,7 +77,10 @@ export function buildSearchIndex(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 documents = content
     .filter(

package/src/core/internal/semver-range.js

@@ -0,0 +1,84 @@
+/**
+ * A closed subset of npm-compatible SemVer range satisfaction (TPL-H1), used
+ * only to check a theme package's own declared `theme.json.templateRange`
+ * against this renderer's published version. This is deliberately not a
+ * general-purpose SemVer range engine: `@rathnasgala2/schemas`'
+ * `theme-contract.schema.json` `templateRange` field (`$defs/semverRange`)
+ * admits an open-ended npm range grammar, but every legitimate value this
+ * closed-contract ecosystem actually emits is either an exact version or a
+ * caret range — the same two forms `package.json` dependency pins in this
+ * very repository use — so this module supports exactly those two forms and
+ * fails closed (rejects) on anything else, exactly like every other closed
+ * catalog in this repository (`nthExpressionProfile`, the pseudo-class
+ * catalog, `functionalSelectorArguments`, ...).
+ */
+
+const EXACT_VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/;
+const CARET_RANGE_PATTERN = /^\^(\d+)\.(\d+)\.(\d+)$/;
+
+/**
+ * @param {string} version a canonical `major.minor.patch` SemVer string
+ * @returns {[number, number, number]} the parsed components
+ */
+function parseExactVersion(version) {
+  const match = EXACT_VERSION_PATTERN.exec(version);
+  if (!match) {
+    throw new Error(`not a canonical major.minor.patch version: ${version}`);
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/**
+ * @param {[number, number, number]} a
+ * @param {[number, number, number]} b
+ * @returns {number} negative, zero or positive per standard comparator
+ *   contract
+ */
+function compareVersions(a, b) {
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index];
+  }
+  return 0;
+}
+
+/**
+ * Whether `version` satisfies `range`, supporting only an exact
+ * `major.minor.patch` range (equality) or a caret range `^major.minor.patch`
+ * (matches `>=major.minor.patch <(major+1).0.0`, or, for a `0.x.y` caret
+ * range, npm's own tightened `0.x` semantics: `>=0.minor.patch <0.(minor+1).0`).
+ *
+ * @param {string} version this renderer's own exact published version
+ * @param {string} range the theme's declared `templateRange`
+ * @returns {boolean} whether `version` satisfies `range`
+ * @throws {Error} when `range` is not one of the two closed forms this
+ *   module admits
+ */
+export function satisfiesTemplateRange(version, range) {
+  const parsedVersion = parseExactVersion(version);
+  const exactMatch = EXACT_VERSION_PATTERN.exec(range);
+  if (exactMatch) {
+    return compareVersions(parsedVersion, parseExactVersion(range)) === 0;
+  }
+  const caretMatch = CARET_RANGE_PATTERN.exec(range);
+  if (caretMatch) {
+    const lower = /** @type {[number, number, number]} */ ([
+      Number(caretMatch[1]),
+      Number(caretMatch[2]),
+      Number(caretMatch[3]),
+    ]);
+    if (compareVersions(parsedVersion, lower) < 0) return false;
+    const [major, minor] = lower;
+    if (major > 0) {
+      return parsedVersion[0] === major;
+    }
+    if (minor > 0) {
+      return parsedVersion[0] === 0 && parsedVersion[1] === minor;
+    }
+    // ^0.0.z: npm pins this to the exact patch version.
+    return compareVersions(parsedVersion, lower) === 0;
+  }
+  throw new Error(
+    `templateRange must be an exact "major.minor.patch" version or a ` +
+      `"^major.minor.patch" caret range, got ${JSON.stringify(range)}`,
+  );
+}

package/src/core/internal/seo.js

@@ -1,28 +1,26 @@
 /**
- * SEO/localization metadata assembly (task packet S2-T08; brief S2 section 3
- * "Required generated outputs": "canonical share and copy affordances,
- * localization metadata, SEO metadata").
+ * SEO/localization metadata assembly: canonical share and copy affordances,
+ * localization metadata, SEO metadata.
  *
  * This module resolves the per-page facts `internal/page-kinds.js` already
  * decided (`description`, `ogType`, `socialImageRef`, `robotsContent`) into
  * the concrete absolute-URL strings a page's `<head>` needs. It is kept
  * separate from `page-kinds.js` because resolving a `socialImageRef` into an
  * absolute derivative URL needs two facts only `src/core/index.js` has at
- * that point: the S2-T05 media pipeline's own finished `assets` list (so the
- * exact derivative file extension a given source image produced is known —
+ * that point: the media pipeline's own finished `assets` list (so the exact
+ * derivative file extension a given source image produced is known —
  * `page-kinds.js` never decodes an image) and `buildInput.baseUrl` (the
  * origin every absolute URL this renderer emits is resolved against).
  *
- * S2-T12 basePath fix (LOCAL-7 follow-up): every derivative-asset URL this
- * module resolves is now `basePath`-joined through `internal/route.js`'s
- * shared {@link import('./route.js').joinBasePathAndRoute} before being
- * resolved against `baseUrl`, exactly like every other renderer-derived
- * route (`internal/page-kinds.js`, `internal/print-stylesheet.js`). Before
- * this fix, {@link resolveSocialImageUrl} joined a bare root-absolute
+ * basePath fix: every derivative-asset URL this module resolves is
+ * `basePath`-joined through `internal/route.js`'s shared
+ * {@link import('./route.js').joinBasePathAndRoute} before being resolved
+ * against `baseUrl`, exactly like every other renderer-derived route
+ * (`internal/page-kinds.js`, `internal/print-stylesheet.js`). Without this,
+ * {@link resolveSocialImageUrl} would join a bare root-absolute
  * `/${derivativePath}` against `baseUrl`, which 404s under a non-root
- * `basePath` publication (`internal/theme-assets.js` is the S2-T12 module
- * that fixes the equivalent theme/print stylesheet and appearance-script
- * hrefs).
+ * `basePath` publication (`internal/theme-assets.js` applies the equivalent
+ * fix for the theme/print stylesheet and appearance-script hrefs).
  *
  * hreflang note (documented scope decision, not a silent omission):
  * `build-input:2.0.0` has no translation/locale-variant linkage between
@@ -31,11 +29,11 @@
  * `$defs` entry named anything like `translation`/`localizedContent`/
  * `alternateLanguage` exists anywhere in the schema; `authorNormalized`'s own
  * `localized` array carries only a translated author bio, never a route). A
- * page's own `<html lang>` already carries its resolved language (S2-T06),
- * which is the entire localization signal this build-input shape declares.
- * `<link rel="alternate" hreflang="...">` is therefore correctly *empty* for
- * S2 — brief S2 section 3's "hreflang/localization metadata... where the
- * input declares translations" is satisfied vacuously, since the input never
+ * page's own `<html lang>` already carries its resolved language, which is
+ * the entire localization signal this build-input shape declares.
+ * `<link rel="alternate" hreflang="...">` is therefore correctly *empty*
+ * here — the requirement to emit hreflang/localization metadata where the
+ * input declares translations is satisfied vacuously, since the input never
  * declares one. This module has no `hreflang` export for that reason; a
  * later build-input major version that adds translation linkage is the
  * natural place to add one, at which point every page-kind call site below
@@ -52,14 +50,14 @@ import { joinBasePathAndRoute } from './route.js';
  * know this path shape, so a change to either stays a one-place fix).
  *
  * @param {readonly {path: string, mediaType: string}[]} mediaAssets the
- *   S2-T05 media pipeline's own finished `assets` list
+ *   media pipeline's own finished `assets` list
  * @param {{path: string, sourceDigest: string} | undefined} reference a
  *   `resolvedFile`-shaped reference (`publication.defaultImage`,
  *   `author.avatar`, `frontmatter.socialImage`, `frontmatter.hero.file`)
  * @returns {string | undefined} the derivative asset's own output-relative
  *   path (never the raw source path), or `undefined` when no reference was
  *   supplied or the media pipeline produced no matching derivative (an image
- *   this renderer's own S2-T05 pipeline was never asked to process, e.g. a
+ *   this renderer's own media pipeline was never asked to process, e.g. a
  *   test fixture exercising SEO metadata without the media pipeline)
  */
 export function resolveOriginalDerivativePath(mediaAssets, reference) {
@@ -77,11 +75,13 @@ export function resolveOriginalDerivativePath(mediaAssets, reference) {
  *
  * @param {object} options resolution options
  * @param {readonly {path: string, mediaType: string}[]} options.mediaAssets
- *   the S2-T05 media pipeline's own finished `assets` list
+ *   the media pipeline's own finished `assets` list
  * @param {{path: string, sourceDigest: string} | undefined} options.reference
  *   the candidate `resolvedFile` reference
- * @param {string} options.baseUrl the build input's origin-only `baseUrl`
- * @param {string} options.basePath the build input's `basePath` (S2-T12: the
+ * @param {string} options.baseUrl the build input's `baseUrl`
+ * @param {string} options.basePath the public base path
+ *   (`route.js#derivePublicBasePath`, the `baseUrl` path joined with the
+ *   build input's `basePath`; the
  *   derivative path is joined with this before being resolved against
  *   `baseUrl`, so a non-root publication's social-image URL is correct)
  * @returns {string | undefined} the absolute derivative image URL, or

package/src/core/internal/sitemap.js

@@ -1,26 +1,24 @@
 /**
- * Sitemap generation (task packet S2-T08; brief S2 section 3 "Required
- * generated outputs": "sitemap"; task packet instructions: "published routes
- * only, deterministic order, `lastmod` from content timestamps not build
- * time").
+ * Sitemap generation: published routes only, deterministic order, with
+ * `lastmod` derived from content timestamps rather than build time.
  *
  * Every entry comes from `internal/page-kinds.js`'s own
  * {@link import('./page-kinds.js').GeneratedPage} list — the single source
  * of truth for which page kinds exist and what each one's own
  * `robotsContent`/`lastModified` is — filtered to exclude any page this
- * renderer itself marked `noindex` (task packet: "robots handling for
- * unlisted content"; `status: "unlisted"` content is exactly the case
+ * renderer itself marked `noindex` (robots handling for unlisted content:
+ * `status: "unlisted"` content is exactly the case
  * `internal/page-kinds.js` sets `robotsContent` for). The generated `404`
  * error page, the feeds, the sitemap document itself and the static search
  * index are never `GeneratedPage` entries, so they are structurally excluded
  * without a second exclusion list. A `manifestRedirect` route is likewise
  * never in this list; a redirect's fixed byte-for-byte document already
- * carries its own `<link rel="canonical">` to the real content page (brief
- * S2 section 3), which is what a crawler should index instead.
+ * carries its own `<link rel="canonical">` to the real content page, which
+ * is what a crawler should index instead.
  */
 
 import { escapeHtml } from './skeleton.js';
-import { joinBasePathAndRoute } from './route.js';
+import { joinPublicRoute } from './route.js';
 import { compareUtf8Bytes } from './source-inventory.js';
 
 /**
@@ -39,8 +37,9 @@ function isNoindex(page) {
  * @param {object} options build options
  * @param {readonly import('./page-kinds.js').GeneratedPage[]} options.generatedPages
  *   every page `internal/page-kinds.js` produced
- * @param {string} options.basePath the build input's `basePath`
- * @param {string} options.baseUrl the build input's origin-only `baseUrl`
+ * @param {string} options.basePath the public base path
+ *   (`route.js#derivePublicBasePath`)
+ * @param {string} options.baseUrl the build input's `baseUrl`
  * @returns {string} the exact UTF-8 `sitemap.xml` text
  */
 export function buildSitemap({ generatedPages, basePath, baseUrl }) {
@@ -49,7 +48,7 @@ export function buildSitemap({ generatedPages, basePath, baseUrl }) {
    * @returns {string} the absolute `https://` URL
    */
   const absoluteUrl = (route) =>
-    new URL(joinBasePathAndRoute(basePath, route), baseUrl).toString();
+    new URL(joinPublicRoute(basePath, route), baseUrl).toString();
 
   const entries = generatedPages
     .filter((page) => !isNoindex(page))