@rathnasgala2/template 2.0.0 → 2.1.0

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,11 @@ 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.basePath 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,22 +1,20 @@
 /**
- * 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';

package/src/core/internal/skeleton.js

@@ -1,12 +1,11 @@
 /**
- * Core semantic HTML skeleton and navigation renderer (task packet S2-T06;
- * brief S2 section 3 "Semantic skeleton and appearance controller").
+ * Core semantic HTML skeleton and navigation renderer.
  *
  * This module renders only inert, static, CSP-`script-src 'self'`-compatible
  * markup: no inline `on*` attribute, no inline `<script>`, no `javascript:`
  * URL. Every user-visible chrome string it emits comes from
  * `internal/messages.js`'s catalog, never an inline literal, so localization
- * can find every string in one place (task packet S2-T06).
+ * can find every string in one place.
  *
  * Landmark contract every page kind in `internal/page-kinds.js` composes
  * through {@link renderPageBody}:
@@ -25,43 +24,43 @@
  *   `conversation`, `newsletter`, `edition-selector`).
  *
  * Core owns nine versioned semantic slots plus the collapsed
- * `article-footer-ad` slot (DEC-060): `header-actions`, `article-preamble`,
+ * `article-footer-ad` slot: `header-actions`, `article-preamble`,
  * `article-end`, `footer-profile`, `footer-auxiliary`, `account-intent`,
- * `conversation`, `newsletter` and `edition-selector`. S2 has no module
- * system (`build-input.modules` is always `{}`), so every slot renders empty
- * except `footer-profile`, which always wraps the publication's own
- * always-rendered footer card/author-profile content (there is no separate
- * module content to distinguish it from in S2). Each slot is one
- * `data-gala-slot="<name>"` attribute on an otherwise plain, non-landmark
- * `<div>` — an empty element with no accessible name contributes nothing to
- * the accessibility tree, so an empty slot is exactly as inert as one that
- * does not exist. The collapsed `article-footer-ad` slot additionally
- * carries the `hidden` attribute, so it produces no visible, accessibility,
- * layout, network or telemetry effect at all (DEC-060) until a later module
- * task (out of S2 scope) removes `hidden` for a selected placement — none
- * exist in S2 (`build-input.placements` is always `[]`).
+ * `conversation`, `newsletter` and `edition-selector`. This renderer has no
+ * module system (`build-input.modules` is always `{}`), so every slot
+ * renders empty except `footer-profile`, which always wraps the
+ * publication's own always-rendered footer card/author-profile content
+ * (there is no separate module content to distinguish it from here). Each
+ * slot is one `data-gala-slot="<name>"` attribute on an otherwise plain,
+ * non-landmark `<div>` — an empty element with no accessible name
+ * contributes nothing to the accessibility tree, so an empty slot is
+ * exactly as inert as one that does not exist. The collapsed
+ * `article-footer-ad` slot additionally carries the `hidden` attribute, so
+ * it produces no visible, accessibility, layout, network or telemetry
+ * effect at all until a later module (not built here) removes `hidden` for
+ * a selected placement — none exist here (`build-input.placements` is
+ * always `[]`).
  *
- * S2-T07 amendment: `header-actions` is no longer always-empty. It is core's
- * own home for the Light/Dark/System appearance control (brief S2 section 3:
- * "the three-mode appearance control in the header-actions slot") — core
- * content, not a module, so this slot's earlier "every slot ... renders
- * empty" description no longer covers it. Every other slot is unaffected.
+ * `header-actions` is not always-empty: it is core's own home for the
+ * Light/Dark/System appearance control (the three-mode appearance control
+ * in the header-actions slot) — core content, not a module, so this slot's
+ * earlier "every slot ... renders empty" description does not cover it.
+ * Every other slot is unaffected.
  *
  * The exact `selectorAtom`/hook-naming decisions here (`data-gala-slot`
- * attribute, one slot name per value) are S2-T06's own scoped proposal for
- * what S2-T12 later locks into the published
- * `contracts/theme-styling-contract.jcs` catalog; T12 has not run yet
- * (S2-T06 precedes it — S2-T07 then S2-T12), so this module documents the
- * decision here rather than pre-authoring that contract file itself.
+ * attribute, one slot name per value) are what
+ * `contracts/theme-styling-contract.jcs` later locks into its published
+ * catalog, so this module documents the decision here rather than
+ * pre-authoring that contract file itself.
  */
 
 /**
  * Every `data-gala-slot` value this renderer ever writes (the nine
- * versioned core slots plus the collapsed `article-footer-ad` slot,
- * DEC-060), sorted by UTF-8 bytes (S2-T12: `contracts/theme-styling-contract.jcs`
- * exposes one public theme hook per entry here, so this is the single
- * source of truth both `renderSlot` below and that contract builder read
- * from — never a second hand-typed literal list).
+ * versioned core slots plus the collapsed `article-footer-ad` slot), sorted
+ * by UTF-8 bytes. `contracts/theme-styling-contract.jcs` exposes one public
+ * theme hook per entry here, so this is the single source of truth both
+ * `renderSlot` below and that contract builder read from — never a second
+ * hand-typed literal list.
  *
  * @type {readonly string[]}
  */
@@ -111,8 +110,8 @@ export function escapeHtml(value) {
  *   collapsed `article-footer-ad` slot
  * @param {object} [options] rendering options
  * @param {boolean} [options.collapsed] when `true`, additionally sets
- *   `hidden` (DEC-060's collapsed `article-footer-ad` slot)
- * @param {string} [options.html] already-rendered inner markup (S2-T07: the
+ *   `hidden` (the collapsed `article-footer-ad` slot)
+ * @param {string} [options.html] already-rendered inner markup (the
  *   `header-actions` slot's appearance control); every other slot omits this
  *   and stays empty
  * @returns {string} the slot element
@@ -171,9 +170,13 @@ function renderNavItem(item, currentRoute) {
  *   route
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
  *   the resolved message catalog
- * @returns {string} the rendered primary navigation, or an empty string when
- *   there are no authored items (the landmark is still meaningful with no
- *   items for a publication with no authored navigation)
+ * @returns {string} the rendered primary navigation `<nav>`, always present
+ *   even when `items` is empty (TPL-M3): every page kind renders exactly
+ *   one primary-navigation landmark unconditionally
+ *   (`internal/page-kinds.js`'s own module documentation), so a reader
+ *   navigating by landmark list sees the same, predictable chrome structure
+ *   on every page regardless of whether that publication has authored any
+ *   navigation items yet.
  */
 export function renderPrimaryNavigation({ items, currentRoute, messages }) {
   const label = escapeHtml(
@@ -306,8 +309,8 @@ export function renderPagination({
  * @param {{route: string, alt: string} | undefined} options.logo an optional
  *   core logo image, always carrying alternative text
  * @param {string} [options.appearanceControlHtml] the already-rendered
- *   Light/Dark/System appearance control (S2-T07:
- *   `internal/appearance/controller-markup.js`'s `renderAppearanceControl`),
+ *   Light/Dark/System appearance control
+ *   (`internal/appearance/controller-markup.js`'s `renderAppearanceControl`),
  *   inserted into the `header-actions` slot
  * @returns {string} the rendered header
  */

package/src/core/internal/source-inventory.js

@@ -1,10 +1,9 @@
 /**
  * Collect the distinct source records this renderer actually consumed from
- * a validated `build-input:2.0.0` instance, as
- * `manifestIncludedSource[]` rows (DEC-097 section 6: "`includedSources` has
- * set equality with the distinct source records placed in the
- * verified-input carrier ... a file used by multiple records appears once
- * and the role is the earliest value in the enum order").
+ * a validated `build-input:2.0.0` instance, as `manifestIncludedSource[]`
+ * rows: `includedSources` has set equality with the distinct source records
+ * placed in the verified-input carrier, a file used by multiple records
+ * appears once, and its role is the earliest value in the enum order.
  */
 
 /** @type {readonly string[]} */

package/src/core/internal/text-direction.js

@@ -7,8 +7,7 @@
  * against `node_modules/@rathnasgala2/schemas/schemas/build-input.schema.json`:
  * no `$defs` entry or property named `dir`/`direction` exists anywhere in the
  * schema). The semantic skeleton must still set an accurate `dir` attribute
- * per brief S2 section 3 ("localized content with mixed direction" is part of
- * acceptance test A's golden fixture), so this module derives it from the
+ * even for localized content with mixed direction, so this module derives it from the
  * tag's primary language subtag against the closed set of right-to-left
  * script languages in Unicode CLDR's exemplar set — the same approach HTML's
  * own `Intl.Locale` `textInfo.direction` uses, reimplemented here as a small