@rathnasgala2/template 2.0.0

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

@@ -0,0 +1,145 @@
+/**
+ * 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").
+ */
+
+/** @type {readonly string[]} */
+const ROLE_PRIORITY = Object.freeze([
+  'publication',
+  'author',
+  'content',
+  'navigation',
+  'appearance',
+  'asset',
+]);
+
+/**
+ * @param {string} role a `manifestIncludedSource.role` value
+ * @returns {number} its position in the enum priority order
+ */
+function rolePriority(role) {
+  const index = ROLE_PRIORITY.indexOf(role);
+  return index === -1 ? ROLE_PRIORITY.length : index;
+}
+
+/**
+ * Collect every distinct `{path, sha256, sourceRevision, role}` row this
+ * renderer read out of `buildInput`, deduplicated by path with the
+ * earliest-enum role kept on collision.
+ *
+ * @param {import('../../../types/index.d.ts').NormalizedBuildInput} buildInput
+ *   the validated build input
+ * @returns {import('../../../types/index.d.ts').ManifestIncludedSourceEntry[]}
+ *   the unique-by-path row set, sorted by UTF-8 path bytes
+ */
+export function collectIncludedSources(buildInput) {
+  /** @type {Map<string, import('../../../types/index.d.ts').ManifestIncludedSourceEntry>} */
+  const byPath = new Map();
+
+  /**
+   * @param {string | undefined} path repository-relative path
+   * @param {string | undefined} sha256 tagged digest
+   * @param {import('../../../types/index.d.ts').ManifestIncludedSourceEntry['role']} role
+   *   manifestIncludedSource role
+   * @param {string} sourceRevision the record's own source revision, when
+   *   known; falls back to the root `sourceRevision`
+   * @returns {void}
+   */
+  const record = (path, sha256, role, sourceRevision) => {
+    if (!path || !sha256) return;
+    const existing = byPath.get(path);
+    if (existing && rolePriority(existing.role) <= rolePriority(role)) return;
+    byPath.set(path, { path, sha256, sourceRevision, role });
+  };
+
+  const rootRevision = buildInput.sourceRevision;
+
+  record(
+    buildInput.publication.sourcePath,
+    buildInput.publication.sourceDigest,
+    'publication',
+    rootRevision,
+  );
+  recordResolvedFile(record, buildInput.publication.defaultImage, rootRevision);
+
+  for (const author of buildInput.authors) {
+    record(author.sourcePath, author.sourceDigest, 'author', rootRevision);
+    recordResolvedFile(record, author.avatar, rootRevision);
+  }
+
+  for (const contentRecord of buildInput.content) {
+    record(
+      contentRecord.sourcePath,
+      contentRecord.sourceDigest,
+      'content',
+      contentRecord.sourceRevision,
+    );
+    if (contentRecord.frontmatter.hero) {
+      recordResolvedFile(
+        record,
+        contentRecord.frontmatter.hero.file,
+        contentRecord.sourceRevision,
+      );
+    }
+    recordResolvedFile(
+      record,
+      contentRecord.frontmatter.socialImage,
+      contentRecord.sourceRevision,
+    );
+  }
+
+  if (buildInput.navigation.source.kind === 'authored') {
+    record(
+      buildInput.navigation.source.sourcePath,
+      buildInput.navigation.source.sourceDigest,
+      'navigation',
+      rootRevision,
+    );
+  }
+
+  if (buildInput.appearance.source.kind === 'authored') {
+    record(
+      buildInput.appearance.source.sourcePath,
+      buildInput.appearance.source.sourceDigest,
+      'appearance',
+      rootRevision,
+    );
+  }
+  recordResolvedFile(record, buildInput.appearance.brandMark, rootRevision);
+  recordResolvedFile(record, buildInput.appearance.wordmark, rootRevision);
+  for (const fontAsset of buildInput.appearance.fontAssets ?? []) {
+    recordResolvedFile(record, fontAsset, rootRevision);
+  }
+
+  return [...byPath.values()].sort((a, b) => compareUtf8Bytes(a.path, b.path));
+}
+
+/**
+ * @param {(path: string | undefined, sha256: string | undefined, role: import('../../../types/index.d.ts').ManifestIncludedSourceEntry['role'], sourceRevision: string) => void} record
+ *   the accumulator closure from {@link collectIncludedSources}
+ * @param {{path?: string, sourceDigest?: string} | undefined} resolvedFile
+ *   a `resolvedFile`-shaped reference, if present
+ * @param {string} sourceRevision the owning record's source revision
+ * @returns {void}
+ */
+function recordResolvedFile(record, resolvedFile, sourceRevision) {
+  if (!resolvedFile) return;
+  record(resolvedFile.path, resolvedFile.sourceDigest, 'asset', sourceRevision);
+}
+
+/**
+ * Compare two strings by their UTF-8 byte sequence, ascending.
+ *
+ * @param {string} a first path
+ * @param {string} b second path
+ * @returns {number} negative, zero or positive per `Array#sort` contract
+ */
+export function compareUtf8Bytes(a, b) {
+  const bytesA = Buffer.from(a, 'utf8');
+  const bytesB = Buffer.from(b, 'utf8');
+  return Buffer.compare(bytesA, bytesB);
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Deterministic base-direction resolution from a BCP-47 language tag.
+ *
+ * `build-input:2.0.0` carries a validated `bcp47` language tag on the
+ * publication (`defaultLanguage`) and on every content record
+ * (`frontmatter.language`) but no separate `dir`/direction field (checked
+ * 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
+ * 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
+ * static table so this renderer adds no new runtime dependency and stays
+ * fully deterministic (no ICU data version drift across Node builds).
+ *
+ * This is a deliberately scoped decision, not a full BCP-47 script/region
+ * override resolver (a tag can in principle override direction with an
+ * explicit script subtag, e.g. `az-Arab` vs `az-Latn`); the closed language
+ * subtag list below is sufficient for every right-to-left language in the S2
+ * fixture corpus and is documented here for the same reason `route.js` scopes
+ * its own route-projection engine.
+ */
+
+/**
+ * Primary BCP-47 language subtags (lowercase) whose default script is
+ * written right-to-left.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const RTL_PRIMARY_LANGUAGE_SUBTAGS = new Set([
+  'ar', // Arabic
+  'arc', // Aramaic
+  'dv', // Divehi
+  'fa', // Persian
+  'ha', // Hausa (Arabic script usage)
+  'he', // Hebrew
+  'khw', // Khowar
+  'ks', // Kashmiri
+  'ku', // Kurdish (Sorani, Arabic script usage)
+  'ps', // Pashto
+  'sd', // Sindhi
+  'ug', // Uyghur
+  'ur', // Urdu
+  'yi', // Yiddish
+]);
+
+/**
+ * Resolve the base text direction for a validated `bcp47` language tag.
+ *
+ * @param {string} bcp47 a schema-validated BCP-47 language tag (structurally
+ *   already `^[A-Za-z0-9-]+$`)
+ * @returns {'ltr' | 'rtl'} the resolved base direction
+ */
+export function resolveTextDirection(bcp47) {
+  const primarySubtag = bcp47.split('-')[0]?.toLowerCase() ?? '';
+  return RTL_PRIMARY_LANGUAGE_SUBTAGS.has(primarySubtag) ? 'rtl' : 'ltr';
+}

package/src/core/internal/theme-assets.js

@@ -0,0 +1,387 @@
+/**
+ * Theme package asset integration (task packet S2-T12): copy the selected
+ * theme package's stylesheets (and any declared passive assets) into the
+ * candidate output directory's `<basePath>/assets/theme/`, produce their
+ * `manifestAsset` rows, and render the ordered `<link>` elements every
+ * generated page's `<head>` inserts, in `cssLayers` order.
+ *
+ * Scope note (documented, not silently assumed, same style as
+ * `internal/print-stylesheet.js`'s own module documentation): this module
+ * trusts the theme package's own `theme.json` file-set/`cssLayers`/
+ * `stylesheets` declarations to the extent needed to *consume* them —
+ * closed stylesheet-list shape, `cssLayers` projection matching the
+ * published `contracts/theme-styling-contract.jcs`'s `orderedLayers`, and
+ * the declared files actually existing. It does **not** re-implement
+ * DEC-097's full CSS Syntax Module admission grammar (selector/property/
+ * at-rule closed catalogs, byte/token/rule ceilings, etc.) — that is the
+ * shared `theme-release.yml` conformance runner's job (S2-T11), run once
+ * per theme package release, not per publication build. Authoring real
+ * theme CSS is S2-T13's task, forbidden here; this module only moves bytes
+ * an already-conformant theme package supplies.
+ *
+ * The theme package directory this module reads from (`options.themeDirectory`
+ * on `renderPublication`) is optional: a caller that does not yet resolve a
+ * theme package (e.g. most of this repository's own S2-T02 through S2-T11
+ * tests) gets the S2-T08 default — a `<link>` at the fixed conventional
+ * `assets/theme/print.css` path, matching `internal/print-stylesheet.js`'s
+ * pre-existing convention — so this task's addition is purely additive.
+ *
+ * Path-containment hardening (independent-review finding B1): every
+ * declared `theme.json` path this module reads — a `stylesheets` entry or a
+ * non-CSS `assets[].path` entry — is untrusted input from the selected
+ * theme package, not a fixed literal. `assertSafeThemeRelativePath` rejects
+ * anything that is not a normalized (NFC), forward-slash, `/`-free,
+ * `..`-free, backslash-free, non-absolute relative path with no empty or
+ * dot segment, then walks every path component under `themeDirectory` with
+ * `lstat` and rejects a symlink at any component (so a symlink planted
+ * inside the theme directory cannot be used to escape it), then verifies
+ * the fully resolved path still starts inside the resolved `themeDirectory`.
+ * Only paths this module itself reads off `theme.json`'s `stylesheets`/
+ * `assets` arrays are ever opened or copied — a file physically present in
+ * `themeDirectory` but never declared there is never enumerated, so it can
+ * never be copied into the candidate output directory.
+ *
+ * basePath fix (independent-review finding B2, LOCAL-7 follow-up): every
+ * file this module writes, and every `manifestAsset.path` it produces, is
+ * now `basePath`-joined through `internal/route.js`'s
+ * `projectFixedAssetPath` — the exact same join `internal/route.js` already
+ * uses for the generated `404.html`/feeds/sitemap/search-index paths — so
+ * the physical file the local-directory adapter serves at
+ * `<basePath>/assets/theme/<name>` matches the `<link href>` this module
+ * also emits. `<link href>` and the physical/manifest path are derived from
+ * the exact same joined value, so they cannot drift apart.
+ */
+
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { ThemeAssetError } from '../errors.js';
+import { digestBytes } from './canonical-jcs.js';
+import { ORDERED_LAYERS } from './appearance/styling-contract.js';
+import { projectFixedAssetPath } from './route.js';
+import { escapeHtml } from './skeleton.js';
+
+/** @type {string} the fixed, non-content-addressed output directory every
+ * theme asset (stylesheet or passive file) is copied under, relative to
+ * `basePath`. */
+export const THEME_ASSET_DIRECTORY = 'assets/theme';
+
+/** @type {readonly string[]} the stylesheet-list shape without `utilities.css`. */
+const STYLESHEETS_WITHOUT_UTILITIES = Object.freeze([
+  'tokens.css',
+  'components.css',
+  'print.css',
+]);
+
+/** @type {readonly string[]} the stylesheet-list shape with `utilities.css`. */
+const STYLESHEETS_WITH_UTILITIES = Object.freeze([
+  'tokens.css',
+  'components.css',
+  'utilities.css',
+  'print.css',
+]);
+
+/** @type {Readonly<Record<string, string>>} theme stylesheet filename to its
+ * fixed `@layer` name (DEC-097 section 4). */
+const LAYER_BY_STYLESHEET = Object.freeze({
+  'tokens.css': 'gala-tokens',
+  'components.css': 'gala-components',
+  'utilities.css': 'gala-utilities',
+  'print.css': 'gala-print',
+});
+
+/**
+ * @param {readonly unknown[]} candidate
+ * @returns {void}
+ */
+function assertStylesheetListShape(candidate) {
+  const withoutUtilities =
+    JSON.stringify(candidate) === JSON.stringify(STYLESHEETS_WITHOUT_UTILITIES);
+  const withUtilities =
+    JSON.stringify(candidate) === JSON.stringify(STYLESHEETS_WITH_UTILITIES);
+  if (!withoutUtilities && !withUtilities) {
+    throw new ThemeAssetError(
+      'THEME_STYLESHEETS_INVALID',
+      'theme.json stylesheets must be exactly ["tokens.css","components.css","print.css"] ' +
+        'or the same list with "utilities.css" inserted before "print.css"',
+    );
+  }
+}
+
+/**
+ * @param {readonly unknown[]} stylesheets the already-shape-validated
+ *   stylesheet list
+ * @param {unknown} cssLayers the candidate `theme.json.cssLayers`
+ * @returns {void}
+ */
+function assertCssLayersProjection(stylesheets, cssLayers) {
+  const expected = /** @type {readonly string[]} */ (stylesheets).map(
+    (filename) => LAYER_BY_STYLESHEET[/** @type {string} */ (filename)],
+  );
+  if (JSON.stringify(cssLayers) !== JSON.stringify(expected)) {
+    throw new ThemeAssetError(
+      'THEME_CSS_LAYERS_INVALID',
+      'theme.json cssLayers must byte-equal the exact ordered layer ' +
+        'projection of its own stylesheets list',
+    );
+  }
+  if (
+    !expected.every(
+      (layer, index) =>
+        layer === ORDERED_LAYERS[index] ||
+        (layer === 'gala-print' && index === expected.length - 1),
+    )
+  ) {
+    throw new ThemeAssetError(
+      'THEME_CSS_LAYERS_INVALID',
+      'theme.json cssLayers must be a subsequence of the published ' +
+        'templateStylingContract.orderedLayers, in that exact relative order',
+    );
+  }
+}
+
+/** @type {string} the reason code every path-containment rejection below
+ * carries. */
+const PATH_CONTAINMENT_CODE = 'THEME_ASSET_PATH_UNSAFE';
+
+/**
+ * Reject anything that is not a normalized (NFC), forward-slash-only,
+ * absolute-free, `..`-free relative path with no empty or dot segment.
+ * Purely syntactic — {@link assertContainedThemePath} does the filesystem
+ * containment/symlink walk.
+ *
+ * @param {unknown} candidate a declared `theme.json` path
+ * @returns {string} the same value, once it is known to be a syntactically
+ *   safe relative path
+ */
+function assertSafeThemeRelativePath(candidate) {
+  if (typeof candidate !== 'string' || candidate.length === 0) {
+    throw new ThemeAssetError(
+      PATH_CONTAINMENT_CODE,
+      `declared path must be a non-empty string (got ${JSON.stringify(candidate)})`,
+    );
+  }
+  if (candidate.normalize('NFC') !== candidate) {
+    throw new ThemeAssetError(
+      PATH_CONTAINMENT_CODE,
+      `declared path must be NFC-normalized: ${candidate}`,
+    );
+  }
+  if (candidate.includes('\\')) {
+    throw new ThemeAssetError(
+      PATH_CONTAINMENT_CODE,
+      `declared path must not contain a backslash: ${candidate}`,
+    );
+  }
+  if (candidate.startsWith('/') || /^[a-zA-Z]:/.test(candidate)) {
+    throw new ThemeAssetError(
+      PATH_CONTAINMENT_CODE,
+      `declared path must be relative, not absolute: ${candidate}`,
+    );
+  }
+  const segments = candidate.split('/');
+  for (const segment of segments) {
+    if (segment.length === 0 || segment === '.' || segment === '..') {
+      throw new ThemeAssetError(
+        PATH_CONTAINMENT_CODE,
+        `declared path has an empty, "." or ".." segment: ${candidate}`,
+      );
+    }
+  }
+  if (path.posix.normalize(candidate) !== candidate) {
+    throw new ThemeAssetError(
+      PATH_CONTAINMENT_CODE,
+      `declared path is not already in normalized form: ${candidate}`,
+    );
+  }
+  return candidate;
+}
+
+/**
+ * Walk every path component of an already syntactically-safe relative path
+ * under `themeDirectory`, rejecting a symlink at any component, then verify
+ * the fully resolved path still starts inside the resolved
+ * `themeDirectory` (belt-and-suspenders on top of the syntactic check
+ * above).
+ *
+ * @param {string} themeDirectory the absolute, caller-mounted theme package
+ *   directory
+ * @param {string} relativePath an already syntactically-safe relative path
+ *   (see {@link assertSafeThemeRelativePath})
+ * @returns {Promise<string>} the absolute, verified-contained path
+ */
+async function assertContainedThemePath(themeDirectory, relativePath) {
+  const resolvedRoot = path.resolve(themeDirectory);
+  let current = resolvedRoot;
+  for (const segment of relativePath.split('/')) {
+    current = path.join(current, segment);
+    let stats;
+    try {
+      stats = await lstat(current);
+    } catch {
+      throw new ThemeAssetError(
+        PATH_CONTAINMENT_CODE,
+        `declared theme file does not exist: ${relativePath}`,
+      );
+    }
+    if (stats.isSymbolicLink()) {
+      throw new ThemeAssetError(
+        PATH_CONTAINMENT_CODE,
+        `declared theme file path contains a symlink component: ${relativePath}`,
+      );
+    }
+  }
+  const resolved = path.resolve(current);
+  if (
+    resolved !== resolvedRoot &&
+    !resolved.startsWith(resolvedRoot + path.sep)
+  ) {
+    throw new ThemeAssetError(
+      PATH_CONTAINMENT_CODE,
+      `declared theme file resolves outside the theme directory: ${relativePath}`,
+    );
+  }
+  return resolved;
+}
+
+/**
+ * Validate and read one declared theme-package-relative file, failing
+ * closed on any traversal, absolute-path, backslash, non-NFC, dot-segment,
+ * or symlink-escape attempt.
+ *
+ * @param {string} themeDirectory the absolute theme package directory
+ * @param {unknown} candidatePath the declared `theme.json` path
+ * @returns {Promise<{relativePath: string, bytes: Buffer}>} the validated
+ *   relative path and the file's bytes
+ */
+async function readDeclaredThemeFile(themeDirectory, candidatePath) {
+  const relativePath = assertSafeThemeRelativePath(candidatePath);
+  const absolutePath = await assertContainedThemePath(
+    themeDirectory,
+    relativePath,
+  );
+  const bytes = await readFile(absolutePath);
+  return { relativePath, bytes };
+}
+
+/**
+ * The `basePath`-joined output-relative path (no leading slash, safe to
+ * both `path.join(outputDirectory, ...)` and a `manifestAsset.path`) for
+ * one theme-owned file. `href` is always derived from this exact same
+ * value, never computed independently, so the emitted `<link>` and the
+ * physical/manifest path can never drift apart.
+ *
+ * @param {string} basePath the build input's `basePath`
+ * @param {string} themeRelativePath the file's path relative to
+ *   `THEME_ASSET_DIRECTORY` (e.g. `"tokens.css"` or `"assets/mark.svg"`)
+ * @returns {string} the joined output-relative path
+ */
+function joinedThemeOutputPath(basePath, themeRelativePath) {
+  return projectFixedAssetPath(
+    basePath,
+    `/${THEME_ASSET_DIRECTORY}/${themeRelativePath}`,
+  );
+}
+
+/**
+ * Load and validate a selected theme package's `theme.json`, copy its
+ * stylesheets (and any declared non-CSS passive assets) into
+ * `<basePath>/assets/theme/`, and build the ordered `<link>` HTML fragment
+ * every generated page's `<head>` inserts.
+ *
+ * @param {object} options load options
+ * @param {string} options.themeDirectory an absolute, caller-mounted,
+ *   read-only directory holding one extracted theme package (the exact
+ *   file set `theme.json.stylesheets`/`assets` and `package.json.files`
+ *   name)
+ * @param {string} options.basePath the build input's `basePath`
+ * @returns {Promise<{
+ *   files: {path: string, bytes: Buffer}[],
+ *   assets: import('../../../types/index.d.ts').ManifestAssetEntry[],
+ *   linkTagsHtml: string,
+ * }>} the files to write (already `basePath`-joined), their manifest rows
+ *   (same joined paths), and the ready-to-insert `<link>` markup
+ */
+export async function loadThemeAssets({ themeDirectory, basePath }) {
+  const { bytes: themeJsonBytes } = await readDeclaredThemeFile(
+    themeDirectory,
+    'theme.json',
+  );
+  /** @type {{stylesheets: unknown, cssLayers: unknown, assets?: {path: string, mediaType: string}[]}} */
+  const themeJson = JSON.parse(themeJsonBytes.toString('utf8'));
+
+  if (!Array.isArray(themeJson.stylesheets)) {
+    throw new ThemeAssetError(
+      'THEME_STYLESHEETS_INVALID',
+      'theme.json.stylesheets must be an array',
+    );
+  }
+  assertStylesheetListShape(themeJson.stylesheets);
+  assertCssLayersProjection(themeJson.stylesheets, themeJson.cssLayers);
+
+  /** @type {{path: string, bytes: Buffer}[]} */
+  const files = [];
+  /** @type {import('../../../types/index.d.ts').ManifestAssetEntry[]} */
+  const assets = [];
+  /** @type {string[]} */
+  const linkTags = [];
+
+  for (const filename of /** @type {string[]} */ (themeJson.stylesheets)) {
+    const { relativePath, bytes } = await readDeclaredThemeFile(
+      themeDirectory,
+      filename,
+    );
+    const outputPath = joinedThemeOutputPath(basePath, relativePath);
+    files.push({ path: outputPath, bytes });
+    assets.push({
+      path: outputPath,
+      mediaType: 'text/css; charset=utf-8',
+      byteLength: String(bytes.byteLength),
+      sha256: digestBytes(bytes),
+      immutable: false,
+    });
+    const mediaAttribute = filename === 'print.css' ? ' media="print"' : '';
+    linkTags.push(
+      `<link rel="stylesheet" href="${escapeHtml(`/${outputPath}`)}"${mediaAttribute}>`,
+    );
+  }
+
+  const passiveAssets = (themeJson.assets ?? []).filter(
+    (asset) => asset.mediaType !== 'text/css',
+  );
+  for (const asset of passiveAssets) {
+    const { relativePath, bytes } = await readDeclaredThemeFile(
+      themeDirectory,
+      asset.path,
+    );
+    const outputPath = joinedThemeOutputPath(basePath, relativePath);
+    files.push({ path: outputPath, bytes });
+    assets.push({
+      path: outputPath,
+      mediaType: asset.mediaType,
+      byteLength: String(bytes.byteLength),
+      sha256: digestBytes(bytes),
+      immutable: false,
+    });
+  }
+
+  return { files, assets, linkTagsHtml: linkTags.join('') };
+}
+
+/**
+ * The S2-T08 default theme stylesheet markup, used only when
+ * `renderPublication` is not given a resolved `options.themeDirectory`
+ * (this repository's own tests, and any caller that has not yet resolved a
+ * theme package): one `media="print"` `<link>` at the fixed conventional
+ * `<basePath>/assets/theme/print.css` path, matching
+ * `internal/print-stylesheet.js`'s pre-existing convention exactly. No
+ * file is written for this fallback path — see the module's own "purely
+ * additive" documentation above.
+ *
+ * @param {string} basePath the build input's `basePath`
+ * @returns {string} the `<link>` HTML fragment
+ */
+export function defaultThemeStylesheetLinksHtml(basePath) {
+  const outputPath = joinedThemeOutputPath(basePath, 'print.css');
+  return `<link rel="stylesheet" href="${escapeHtml(`/${outputPath}`)}" media="print">`;
+}

package/src/core/internal/uuid.js

@@ -0,0 +1,51 @@
+/**
+ * A minimal RFC 9562 UUIDv7 generator for `artifactId`. DEC-097's
+ * `stableId` pattern requires the version nibble `7` and an `8`/`9`/`a`/`b`
+ * variant nibble; `node:crypto`'s `randomUUID()` only produces v4. The
+ * decision text is explicit that "equal artifact bytes may have distinct
+ * artifact IDs" (DEC-097 section 6), so this value is intentionally not
+ * required to be deterministic across two otherwise byte-identical builds.
+ */
+
+import { randomBytes } from 'node:crypto';
+
+/**
+ * Generate one lowercase canonical UUIDv7 string.
+ *
+ * @returns {string} a UUIDv7 matching `stableId`'s pattern
+ */
+export function generateUuidV7() {
+  const timestampMs = BigInt(Date.now());
+  const random = randomBytes(10);
+
+  const bytes = new Uint8Array(16);
+  bytes[0] = Number((timestampMs >> 40n) & 0xffn);
+  bytes[1] = Number((timestampMs >> 32n) & 0xffn);
+  bytes[2] = Number((timestampMs >> 24n) & 0xffn);
+  bytes[3] = Number((timestampMs >> 16n) & 0xffn);
+  bytes[4] = Number((timestampMs >> 8n) & 0xffn);
+  bytes[5] = Number(timestampMs & 0xffn);
+  // Version nibble 7 in the high nibble of byte 6.
+  bytes[6] = 0x70 | (random[0] & 0x0f);
+  bytes[7] = random[1];
+  // Variant bits 10 in the top two bits of byte 8.
+  bytes[8] = 0x80 | (random[2] & 0x3f);
+  bytes[9] = random[3];
+  bytes[10] = random[4];
+  bytes[11] = random[5];
+  bytes[12] = random[6];
+  bytes[13] = random[7];
+  bytes[14] = random[8];
+  bytes[15] = random[9];
+
+  const hex = Array.from(bytes, (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('');
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32),
+  ].join('-');
+}

package/types/eleventy-plugin-syntaxhighlight.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal ambient typing for the one internal helper
+ * `src/core/internal/content-security.js` calls directly:
+ * `@11ty/eleventy-plugin-syntaxhighlight`'s markdown-it `highlight` option
+ * factory. The package ships no published type declarations, publishes no
+ * `exports` map (so this deep import path is a plain, resolvable file), and
+ * this typing is deliberately narrow rather than a full re-authoring of its
+ * API.
+ */
+declare module '@11ty/eleventy-plugin-syntaxhighlight/src/markdownSyntaxHighlightOptions.js' {
+  export interface MarkdownSyntaxHighlightOptions {
+    lineSeparator?: string;
+    alwaysWrapLineHighlights?: boolean;
+    preAttributes?: Record<string, unknown>;
+    codeAttributes?: Record<string, unknown>;
+  }
+
+  export type MarkdownItHighlightFn = (
+    code: string,
+    language: string,
+  ) => string;
+
+  export default function markdownSyntaxHighlightOptions(
+    options?: MarkdownSyntaxHighlightOptions,
+  ): MarkdownItHighlightFn;
+}