@rathnasgala2/template 3.1.0 → 3.2.1

package/src/core/internal/editions.js

@@ -0,0 +1,297 @@
+/**
+ * Editions: repository documents of `kind: "edition"` that restate one
+ * article at another depth (a quick read, a standard edition, a deep dive).
+ *
+ * An edition is an ordinary rendered document, not a module: the build input
+ * already carries it as a `content[]` record whose front matter names the
+ * article it restates (`edition.of`, the article's slug) and its depth
+ * (`edition.kind`). Whether the edition is current (generated from the
+ * article's present text) is decided upstream, before the build input exists,
+ * so an edition that arrives here is rendered as given.
+ *
+ * What this renderer does with one:
+ *
+ * - it renders at `<article route>/<segment>` where the segment is
+ *   `quick-read`, `standard` or `deep-dive`, built from `edition.of`
+ *   ({@link editionRoute}), so `/post` has `/post/quick-read` beside it;
+ * - its `<link rel="canonical">` names the article and its robots directive is
+ *   `noindex, follow`, so the article stays the indexed reference;
+ * - it never appears in a listing, tag or series page, a feed, the sitemap, the
+ *   search index or the `llms` documents (each of those selects `kind:
+ *   "article"` / `"page"` records, or skips `noindex` pages);
+ * - the article and each of its editions carry the same accessible selector,
+ *   a `<nav aria-label="Editions">` of links in the core `edition-selector`
+ *   slot, listing the original and each edition that exists, the current page
+ *   marked `aria-current="page"`; an edition page also carries a one-line
+ *   label saying the page is a generated edition and the original is the
+ *   reference.
+ *
+ * Styling is the base layer's: the selector uses the existing pill hooks, so
+ * the published theme styling contract does not change.
+ *
+ * An edition that cannot be placed is a malformed build input and fails closed
+ * before anything is written ({@link resolveEditions}).
+ */
+
+import { BuildInputValidationError } from '../errors.js';
+import { icon } from './icons.js';
+import { escapeHtml, renderSlot } from './skeleton.js';
+
+/** @typedef {'QUICK_READ' | 'STANDARD' | 'DEEP_DIVE'} EditionKind */
+
+/**
+ * One edition placed beside its article.
+ *
+ * @typedef {object} EditionEntry
+ * @property {import('../../../types/index.d.ts').ContentBuildRecord} record
+ *   the edition document
+ * @property {import('../../../types/index.d.ts').ContentBuildRecord} original
+ *   the article it restates
+ * @property {EditionKind} kind its depth
+ * @property {string} route its un-joined route
+ */
+
+/**
+ * Every edition of a build input.
+ *
+ * @typedef {object} EditionResolution
+ * @property {ReadonlyMap<import('../../../types/index.d.ts').ContentBuildRecord, EditionEntry>} byRecord
+ *   each edition record's placement
+ * @property {ReadonlyMap<import('../../../types/index.d.ts').ContentBuildRecord, readonly EditionEntry[]>} byOriginal
+ *   each article's editions, in selector order (quick read, standard, deep dive)
+ */
+
+/**
+ * The edition kinds in the order the selector lists them.
+ *
+ * @type {readonly EditionKind[]}
+ */
+export const EDITION_KINDS = Object.freeze([
+  'QUICK_READ',
+  'STANDARD',
+  'DEEP_DIVE',
+]);
+
+/** @type {Readonly<Record<EditionKind, string>>} */
+const EDITION_SEGMENTS = Object.freeze({
+  QUICK_READ: 'quick-read',
+  STANDARD: 'standard',
+  DEEP_DIVE: 'deep-dive',
+});
+
+/** @type {Readonly<Record<EditionKind, string>>} */
+const EDITION_LABEL_KEYS = Object.freeze({
+  QUICK_READ: 'editionQuickReadLabel',
+  STANDARD: 'editionStandardLabel',
+  DEEP_DIVE: 'editionDeepDiveLabel',
+});
+
+/** Where a reader of an edition diagnostic finds the rule. */
+const DOCUMENTATION_URL = 'https://github.com/rathnasgala2/template#editions';
+
+/**
+ * @param {{of: string, kind: EditionKind}} edition an edition's front-matter
+ *   `edition` object
+ * @returns {string} the edition's un-joined route, `/<of>/<segment>`
+ */
+export function editionRoute(edition) {
+  return `/${edition.of}/${EDITION_SEGMENTS[edition.kind]}`;
+}
+
+/**
+ * @param {EditionKind} kind an edition kind
+ * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} messages
+ *   the resolved message catalog
+ * @returns {string} the kind's plain-text label ("Quick read")
+ */
+export function editionKindLabel(kind, messages) {
+  return /** @type {string} */ (messages[EDITION_LABEL_KEYS[kind]]);
+}
+
+/**
+ * @param {string} code the diagnostic code
+ * @param {number} index the record's index in `content`
+ * @param {string} sourcePath the record's repository source path
+ * @param {string} remediation what the author or producer should change
+ * @returns {Record<string, string>} one diagnostic, shaped like a schema
+ *   validation diagnostic
+ */
+function diagnostic(code, index, sourcePath, remediation) {
+  return {
+    code,
+    severity: 'ERROR',
+    instancePointer: `/content/${index}`,
+    actualValueClass: 'object',
+    rule: 'template:edition',
+    sourcePath,
+    remediation,
+    documentationUrl: DOCUMENTATION_URL,
+  };
+}
+
+/**
+ * Place every edition beside the article it restates, before anything is
+ * written. Fails closed with one diagnostic per edition that cannot be placed:
+ * its `edition.of` names no `kind: "article"` document in this build
+ * (`EDITION_ORIGINAL_UNRESOLVED`), two editions share an article and a depth
+ * (`EDITION_DUPLICATE`), or its route is already another document's route or
+ * redirect (`EDITION_ROUTE_CONFLICT`).
+ *
+ * @param {readonly import('../../../types/index.d.ts').ContentBuildRecord[]} content
+ *   the build input's `content[]`
+ * @param {(frontmatter: import('../../../types/index.d.ts').ContentFrontmatterNormalized) => string} routeOf
+ *   a document's own un-joined route
+ * @returns {EditionResolution} every edition's placement
+ * @throws {BuildInputValidationError} when an edition cannot be placed
+ */
+export function resolveEditions(content, routeOf) {
+  /** @type {Map<string, import('../../../types/index.d.ts').ContentBuildRecord>} */
+  const articles = new Map();
+  /** @type {Set<string>} */
+  const occupied = new Set();
+  for (const record of content) {
+    const { frontmatter } = record;
+    if (frontmatter.kind === 'edition') continue;
+    if (frontmatter.kind === 'article') articles.set(frontmatter.slug, record);
+    occupied.add(routeOf(frontmatter));
+    for (const source of frontmatter.redirects) occupied.add(source);
+  }
+
+  /** @type {Map<import('../../../types/index.d.ts').ContentBuildRecord, EditionEntry>} */
+  const byRecord = new Map();
+  /** @type {Map<import('../../../types/index.d.ts').ContentBuildRecord, EditionEntry[]>} */
+  const byOriginal = new Map();
+  /** @type {Set<string>} */
+  const claimed = new Set();
+  /** @type {Record<string, string>[]} */
+  const diagnostics = [];
+
+  content.forEach((record, index) => {
+    const { frontmatter } = record;
+    if (frontmatter.kind !== 'edition') return;
+    const { edition } = frontmatter;
+    const original = edition ? articles.get(edition.of) : undefined;
+    if (!edition || !original) {
+      diagnostics.push(
+        diagnostic(
+          'EDITION_ORIGINAL_UNRESOLVED',
+          index,
+          record.sourcePath,
+          `The edition ${record.sourcePath} restates "${edition?.of ?? ''}", which is not an article in this build. Publish the article with it, or remove the edition.`,
+        ),
+      );
+      return;
+    }
+    const route = editionRoute(edition);
+    if (occupied.has(route)) {
+      diagnostics.push(
+        diagnostic(
+          'EDITION_ROUTE_CONFLICT',
+          index,
+          record.sourcePath,
+          `The edition ${record.sourcePath} would render at ${route}, which another document already uses. Rename or move that document.`,
+        ),
+      );
+      return;
+    }
+    if (claimed.has(route)) {
+      diagnostics.push(
+        diagnostic(
+          'EDITION_DUPLICATE',
+          index,
+          record.sourcePath,
+          `The article "${edition.of}" already has a ${edition.kind} edition. Keep one.`,
+        ),
+      );
+      return;
+    }
+    claimed.add(route);
+    /** @type {EditionEntry} */
+    const entry = { record, original, kind: edition.kind, route };
+    byRecord.set(record, entry);
+    byOriginal.set(original, [...(byOriginal.get(original) ?? []), entry]);
+  });
+
+  if (diagnostics.length > 0) throw new BuildInputValidationError(diagnostics);
+
+  for (const [original, entries] of byOriginal) {
+    byOriginal.set(
+      original,
+      entries.sort(
+        (a, b) => EDITION_KINDS.indexOf(a.kind) - EDITION_KINDS.indexOf(b.kind),
+      ),
+    );
+  }
+  return { byRecord, byOriginal };
+}
+
+/**
+ * The editions a reader is offered next to an article: every published one,
+ * plus the one being read. An `unlisted` edition stays reachable by its own
+ * address but is not advertised.
+ *
+ * @param {readonly EditionEntry[] | undefined} entries every edition of the
+ *   article, in selector order
+ * @param {EditionEntry | undefined} current the edition being read, if any
+ * @returns {EditionEntry[]} the editions to list
+ */
+export function listedEditions(entries, current) {
+  return (entries ?? []).filter(
+    (entry) =>
+      entry === current || entry.record.frontmatter.status === 'published',
+  );
+}
+
+/**
+ * Render the `edition-selector` slot for an article or one of its editions.
+ *
+ * @param {object} options rendering options
+ * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
+ *   the resolved message catalog
+ * @param {string} options.originalHref the article's joined route
+ * @param {readonly EditionEntry[]} options.entries the editions to list, in
+ *   selector order ({@link listedEditions})
+ * @param {EditionEntry | undefined} options.current the edition being read;
+ *   `undefined` on the article itself
+ * @param {(route: string) => string} options.site joins a route with the
+ *   public base path
+ * @returns {string} the slot, or an empty string when there is no edition to
+ *   offer (a slot with nothing to say is not rendered)
+ */
+export function renderEditionSelector({
+  messages,
+  originalHref,
+  entries,
+  current,
+  site,
+}) {
+  if (entries.length === 0) return '';
+  const text = (/** @type {string} */ key) =>
+    escapeHtml(/** @type {string} */ (messages[key]));
+  const item = (
+    /** @type {string} */ href,
+    /** @type {string} */ label,
+    /** @type {string} */ iconName,
+    /** @type {boolean} */ isCurrent,
+  ) =>
+    `<li><a class="g-pill" href="${escapeHtml(href)}"${isCurrent ? ' aria-current="page"' : ''}>` +
+    `${icon(iconName)}<span>${label}</span></a></li>`;
+  const links = [
+    item(originalHref, text('editionOriginalLabel'), 'pen', !current),
+    ...entries.map((entry) =>
+      item(
+        site(entry.route),
+        escapeHtml(editionKindLabel(entry.kind, messages)),
+        'sparkle',
+        entry === current,
+      ),
+    ),
+  ].join('');
+  return renderSlot('edition-selector', {
+    html:
+      `<nav aria-label="${text('editionsNavigationLabel')}"><ul class="g-pills">${links}</ul></nav>` +
+      (current
+        ? `<p class="g-label">${icon('sparkle')}${text('editionNoticeLabel')}</p>`
+        : ''),
+  });
+}

package/src/core/internal/feeds.js

@@ -18,7 +18,7 @@
  * media pipeline scope decisions in the package README).
  */
 
-import { escapeHtml } from './skeleton.js';
+import { escapeHtml, unescapeHtml } from './skeleton.js';
 import { derivePublicBasePath, joinPublicRoute } from './route.js';
 import { deriveAuthorSlugs } from './route-labels.js';
 import {
@@ -48,19 +48,6 @@ function toRfc822(rfc3339) {
   return new Date(rfc3339).toUTCString();
 }
 
-/**
- * @param {string} value an attribute value as it appears in HTML source
- * @returns {string} the value with the five predefined entities decoded
- */
-function decodeAttribute(value) {
-  return value
-    .replace(/"/g, '"')
-    .replace(/'/g, "'")
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&amp;/g, '&');
-}
-
 /**
  * Make every `href`/`src` in an article body absolute against the article's
  * own URL: a feed reader renders the body away from the site, so a relative
@@ -75,7 +62,7 @@ export function absolutizeBodyLinks(bodyHtml, pageUrl) {
     /\b(href|src)="([^"]*)"/g,
     (match, attribute, value) => {
       try {
-        return `${attribute}="${escapeHtml(new URL(decodeAttribute(value), pageUrl).toString())}"`;
+        return `${attribute}="${escapeHtml(new URL(unescapeHtml(value), pageUrl).toString())}"`;
       } catch {
         return match;
       }
@@ -99,11 +86,14 @@ function cdata(text) {
  * validated `build-input:2.0.0` instance.
  *
  * @param {import('../../../types/index.d.ts').NormalizedBuildInput} validatedInput
+ * @param {object} options feed options
+ * @param {(body: string) => string} options.feedBody turns an article body
+ *   into its feed form (every image naming its media derivative)
  * @returns {{atomXml: string, rssXml: string, atomSelfUrl: string, rssSelfUrl: string}}
  *   both feed documents' exact UTF-8 text, plus each feed's own absolute
  *   self URL (for the shared layout's feed-discovery `<link>` tags)
  */
-export function buildFeeds(validatedInput) {
+export function buildFeeds(validatedInput, { feedBody }) {
   const { publication, authors, content, basePath, baseUrl } = validatedInput;
   const authorsById = new Map(authors.map((author) => [author.id, author]));
   const authorSlugs = deriveAuthorSlugs(authors);
@@ -144,7 +134,7 @@ export function buildFeeds(validatedInput) {
       const categoriesXml = frontmatter.tags
         .map((tag) => `<category term="${escapeHtml(tag)}"/>`)
         .join('');
-      const contentXml = `<content type="html">${escapeHtml(absolutizeBodyLinks(record.body, entryUrl))}</content>`;
+      const contentXml = `<content type="html">${escapeHtml(absolutizeBodyLinks(feedBody(record.body), entryUrl))}</content>`;
       const summaryXml = frontmatter.description
         ? `<summary>${escapeHtml(frontmatter.description)}</summary>`
         : '';
@@ -200,7 +190,7 @@ export function buildFeeds(validatedInput) {
         creatorsXml +
         categoriesXml +
         descriptionXml +
-        `<content:encoded>${cdata(absolutizeBodyLinks(record.body, itemUrl))}</content:encoded>` +
+        `<content:encoded>${cdata(absolutizeBodyLinks(feedBody(record.body), itemUrl))}</content:encoded>` +
         `</item>`
       );
     })

package/src/core/internal/media/content-images.js

@@ -0,0 +1,262 @@
+/**
+ * Content images: the `<img>` elements a rendered body carries.
+ *
+ * A `renderableBody.body` is already render-policy-conformant HTML, so its
+ * only image form is `<img src="..." alt="...">` with a repository-relative
+ * `src` (`content-security.js` admits no scheme for `img[src]` and strips
+ * the `src` of a remote image). This module resolves every such `src`
+ * against the image assets `build-input` inventories for that document
+ * (`content[].media[]`, each a digest-pinned repository file), before
+ * anything is written, and fails closed on any reference that names no
+ * inventoried image: a body image that cannot be resolved never reaches a
+ * page as a broken `<img>`. The resolved references join the media
+ * pipeline's own reference set (`pipeline.js`), and the pages and feeds
+ * then replace each `<img>` with markup naming the pipeline's derivatives
+ * (`components.js#createContentImage`); the source file itself is never
+ * copied into the output.
+ *
+ * Resolution rule (a build-input producer inventories a document's images
+ * by the same rule): the `src` attribute is entity-decoded;
+ * a scheme, a protocol-relative `//`, a query or a fragment never resolves;
+ * one leading `/` or `./` is dropped (the path is repository-root-relative
+ * either way); the rest is percent-decoded and NFC-normalized; an empty,
+ * `.` or `..` segment never resolves; the result must equal the `path` of an
+ * image entry (`image/png`, `image/jpeg`, `image/webp`, `image/avif`,
+ * `image/gif`) in the same document's `media[]`.
+ */
+
+import {
+  BuildInputValidationError,
+  RenderPolicyViolationError,
+} from '../../errors.js';
+import { unescapeHtml } from '../skeleton.js';
+
+/** @typedef {{path: string, sourceDigest: string}} ImageReference */
+
+/**
+ * One body this module scans, with the image assets it may reference.
+ *
+ * @typedef {object} BodyScope
+ * @property {string} pointer the body's JSON pointer inside `build-input`
+ * @property {string} sourcePath the body's own repository source path
+ * @property {string} body the body HTML
+ * @property {ReadonlyMap<string, ImageReference>} inventory the image
+ *   assets this body may reference, keyed by repository path
+ */
+
+/** The `media[]` media types a body image may resolve to. */
+const IMAGE_MEDIA_TYPES = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/webp',
+  'image/avif',
+  'image/gif',
+]);
+
+/** Every `<img>` element of a policy-conformant body. */
+const IMG_ELEMENT = /<img\b[^>]*>/g;
+
+/** One double-quoted attribute (the only form sanitized HTML carries). */
+const ATTRIBUTE = /\s([a-zA-Z][a-zA-Z0-9-]*)="([^"]*)"/g;
+
+/** Where a reader of an unresolved-reference diagnostic finds the rule. */
+const DOCUMENTATION_URL =
+  'https://github.com/rathnasgala2/template#content-images';
+
+/**
+ * @param {string} element one `<img ...>` element
+ * @returns {{src?: string, alt?: string}} its raw `src` and `alt` values
+ *   (still entity-encoded, exactly as they appear in the body)
+ */
+function attributesOf(element) {
+  /** @type {{src?: string, alt?: string}} */
+  const attributes = {};
+  for (const [, name, value] of element.matchAll(ATTRIBUTE)) {
+    if (name === 'src' || name === 'alt') attributes[name] = value;
+  }
+  return attributes;
+}
+
+/**
+ * Turn a raw `src` attribute value into the repository-relative path it
+ * names, or `undefined` when it is not a repository-relative reference.
+ *
+ * @param {string | undefined} rawSource the attribute value as it appears
+ *   in the body
+ * @returns {string | undefined} the NFC repository-relative path
+ */
+export function repositoryPathOfImageSource(rawSource) {
+  if (rawSource === undefined) return undefined;
+  const source = unescapeHtml(rawSource);
+  if (
+    source === '' ||
+    source.startsWith('//') ||
+    /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(source) ||
+    /[?#\\]/.test(source)
+  ) {
+    return undefined;
+  }
+  const relative = source.startsWith('/')
+    ? source.slice(1)
+    : source.startsWith('./')
+      ? source.slice(2)
+      : source;
+  let decoded;
+  try {
+    decoded = decodeURIComponent(relative).normalize('NFC');
+  } catch {
+    return undefined;
+  }
+  const segments = decoded.split('/');
+  if (
+    decoded.includes('\\') ||
+    decoded.includes('\u0000') ||
+    segments.some((segment) => ['', '.', '..'].includes(segment))
+  ) {
+    return undefined;
+  }
+  return decoded;
+}
+
+/**
+ * @param {readonly {path: string, sourceDigest: string, mediaType: string}[] | undefined} media
+ *   one document's `media[]`
+ * @returns {Map<string, ImageReference>} its image entries, keyed by path
+ */
+function inventoryOf(media) {
+  /** @type {Map<string, ImageReference>} */
+  const inventory = new Map();
+  for (const entry of media ?? []) {
+    if (IMAGE_MEDIA_TYPES.has(entry.mediaType)) {
+      inventory.set(entry.path, {
+        path: entry.path,
+        sourceDigest: entry.sourceDigest,
+      });
+    }
+  }
+  return inventory;
+}
+
+/**
+ * Every body this renderer renders, with the image assets each may
+ * reference: the publication profile, the footer card when enabled, and
+ * every content record. The profile and footer card have no media inventory
+ * of their own, so an image in either never resolves.
+ *
+ * @param {import('../../../../types/index.d.ts').NormalizedBuildInput} buildInput
+ *   the validated build input
+ * @returns {BodyScope[]} every body, in document order
+ */
+function bodyScopes(buildInput) {
+  const { profile, footerCard } = buildInput.publication;
+  /** @type {BodyScope[]} */
+  const scopes = [];
+  if (profile) {
+    scopes.push({
+      pointer: '/publication/profile/body/body',
+      sourcePath: profile.body.sourcePath,
+      body: profile.body.body,
+      inventory: new Map(),
+    });
+  }
+  if (footerCard?.enabled) {
+    scopes.push({
+      pointer: '/publication/footerCard/body/body',
+      sourcePath: footerCard.body.sourcePath,
+      body: footerCard.body.body,
+      inventory: new Map(),
+    });
+  }
+  buildInput.content.forEach((record, index) => {
+    scopes.push({
+      pointer: `/content/${index}/body`,
+      sourcePath: record.sourcePath,
+      body: record.body,
+      inventory: inventoryOf(record.media),
+    });
+  });
+  return scopes;
+}
+
+/**
+ * @param {BodyScope} scope the body the reference sits in
+ * @param {string | undefined} rawSource the reference's raw `src` value
+ * @returns {Record<string, string>} one `MEDIA_REFERENCE_UNRESOLVED`
+ *   diagnostic, shaped like a schema validation diagnostic
+ */
+function unresolvedDiagnostic(scope, rawSource) {
+  const reference = rawSource === undefined ? '' : unescapeHtml(rawSource);
+  return {
+    code: 'MEDIA_REFERENCE_UNRESOLVED',
+    severity: 'ERROR',
+    instancePointer: scope.pointer,
+    actualValueClass: 'string',
+    rule: 'template:content-image-reference',
+    reference,
+    remediation:
+      reference === ''
+        ? `An image in ${scope.sourcePath} has no repository source (remote images are not published). Commit the image and reference it by its repository-relative path, or remove it.`
+        : `The image "${reference}" in ${scope.sourcePath} names no image file inventoried for that document. Commit the image and reference it by its repository-relative path, or remove it.`,
+    documentationUrl: DOCUMENTATION_URL,
+  };
+}
+
+/**
+ * Resolve every image every body references, before anything is written.
+ * Fails closed with one `MEDIA_REFERENCE_UNRESOLVED` diagnostic per image
+ * that names no inventoried image asset.
+ *
+ * @param {import('../../../../types/index.d.ts').NormalizedBuildInput} buildInput
+ *   the validated, render-policy-verified build input
+ * @returns {Map<string, ImageReference>} each distinct raw `src` value to
+ *   the asset it resolves to
+ * @throws {BuildInputValidationError} when any body image is unresolved
+ */
+export function resolveContentImages(buildInput) {
+  /** @type {Map<string, ImageReference>} */
+  const resolved = new Map();
+  /** @type {Record<string, string>[]} */
+  const diagnostics = [];
+  for (const scope of bodyScopes(buildInput)) {
+    for (const element of scope.body.match(IMG_ELEMENT) ?? []) {
+      const { src } = attributesOf(element);
+      const path = repositoryPathOfImageSource(src);
+      const reference =
+        path === undefined ? undefined : scope.inventory.get(path);
+      if (src === undefined || reference === undefined) {
+        diagnostics.push(unresolvedDiagnostic(scope, src));
+      } else if (!resolved.has(src)) {
+        resolved.set(src, reference);
+      }
+    }
+  }
+  if (diagnostics.length > 0) {
+    throw new BuildInputValidationError(diagnostics);
+  }
+  return resolved;
+}
+
+/**
+ * Replace every `<img>` in a body with the markup `render` produces for the
+ * asset its `src` resolved to.
+ *
+ * @param {string} body a policy-conformant body
+ * @param {ReadonlyMap<string, ImageReference>} resolved the result of
+ *   {@link resolveContentImages} for the same build input
+ * @param {(reference: ImageReference, altAttribute: string) => string} render
+ *   the replacement markup for one image, given its raw (still
+ *   entity-encoded) `alt` value
+ * @returns {string} the body with every image replaced
+ */
+export function rewriteBodyImages(body, resolved, render) {
+  return body.replace(IMG_ELEMENT, (element) => {
+    const { src, alt } = attributesOf(element);
+    const reference = src === undefined ? undefined : resolved.get(src);
+    if (reference === undefined) {
+      throw new RenderPolicyViolationError(
+        `a body image (${src ?? 'no src'}) reached rendering unresolved; this is a renderer defect`,
+      );
+    }
+    return render(reference, alt ?? '');
+  });
+}