@glw907/cairn-cms 0.62.2 → 0.76.0

package/src/lib/content/frontmatter.ts

@@ -3,11 +3,84 @@
 // on-disk write/read pair. Kept as one seam so a site owns its serialization contract
 // (quoting, key order) without the save endpoint reaching for gray-matter directly.
 import matter from 'gray-matter';
-import type { FrontmatterField, ImageValue } from './types.js';
+import type { ImageValue, NamedField } from './types.js';
+import type { FieldDescriptor } from './fields.js';
+
+/**
+ * True when a multiselect field is a closed checkbox group: it declares an options vocabulary and is
+ *  not author-extendable. The save decoder and the editor render arm both call this, so the
+ *  closed-versus-open multiselect decision can never drift between decode and display.
+ */
+export function isClosedMultiselect(field: {
+  type: string;
+  options?: readonly string[];
+  creatable?: boolean;
+}): boolean {
+  return field.type === 'multiselect' && !!field.options && !field.creatable;
+}
+
+// Decode one field addressed by `name`, for NESTED use (object leaves, array rows). Returns undefined
+// when empty so the caller omits the key; this nested contract differs from the top-level arms, which
+// preserve '' / [] for back-compat. Recurses one level for an object item.
+function decodeField(name: string, field: FieldDescriptor, form: FormData): unknown {
+  switch (field.type) {
+    case 'boolean':
+      return form.get(name) === 'on' ? true : undefined;
+    case 'multiselect': {
+      const list = isClosedMultiselect(field)
+        ? form.getAll(name).map(String)
+        : [...new Set(String(form.get(name) ?? '').split(',').map((t) => t.trim()).filter(Boolean))];
+      return list.length > 0 ? list : undefined;
+    }
+    case 'image': {
+      const src = String(form.get(`${name}.src`) ?? '').trim();
+      if (src === '') return undefined;
+      const value: ImageValue = { src, alt: String(form.get(`${name}.alt`) ?? '') };
+      const caption = String(form.get(`${name}.caption`) ?? '').trim();
+      if (caption !== '') value.caption = caption;
+      if (String(form.get(`${name}.decorative`) ?? '') === 'true') value.decorative = true;
+      return value;
+    }
+    case 'object': {
+      const obj: Record<string, unknown> = {};
+      for (const [leafKey, leaf] of Object.entries(field.fields)) {
+        const v = decodeField(`${name}.${leafKey}`, leaf, form);
+        if (v !== undefined) obj[leafKey] = v;
+      }
+      return Object.keys(obj).length > 0 ? obj : undefined;
+    }
+    default: {
+      // text, textarea, number-as-string, url, email, date, datetime: a trimmed non-empty string.
+      const s = String(form.get(name) ?? '').trim();
+      return s === '' ? undefined : s;
+    }
+  }
+}
+
+// Enumerate array rows by any present name.<i>.* key, decode each item, and drop a row that decodes to
+// empty (minimal-frontmatter). A row with any non-default content emits at least one key (a text leaf
+// submits even when empty; a checked boolean submits its key), so a present-but-meaningful row is always
+// seen; a fully all-default row carries no data and is correctly pruned. Output order follows ascending
+// index, which the editor's keyed rows keep in sync.
+function decodeRows(name: string, item: FieldDescriptor, form: FormData): unknown[] {
+  const indices = new Set<number>();
+  const prefix = `${name}.`;
+  for (const k of form.keys()) {
+    if (!k.startsWith(prefix)) continue;
+    const n = Number(k.slice(prefix.length).split('.')[0]);
+    if (Number.isInteger(n)) indices.add(n);
+  }
+  const rows: unknown[] = [];
+  for (const i of [...indices].sort((a, b) => a - b)) {
+    const v = decodeField(`${name}.${i}`, item, form);
+    if (v !== undefined) rows.push(v);
+  }
+  return rows;
+}
 
 /** Decode submitted form data into raw frontmatter, one rule per field type. */
 export function frontmatterFromForm(
-  fields: FrontmatterField[],
+  fields: NamedField[],
   form: FormData,
 ): Record<string, unknown> {
   const data: Record<string, unknown> = {};
@@ -16,19 +89,21 @@ export function frontmatterFromForm(
       case 'boolean':
         data[field.name] = form.get(field.name) === 'on';
         break;
-      case 'tags':
-        data[field.name] = form.getAll(field.name).map(String);
-        break;
-      case 'freetags':
-        // One comma-separated input to trimmed, de-duplicated, non-empty tags.
-        data[field.name] = [
-          ...new Set(
-            String(form.get(field.name) ?? '')
-              .split(',')
-              .map((tag) => tag.trim())
-              .filter(Boolean),
-          ),
-        ];
+      case 'multiselect':
+        if (isClosedMultiselect(field)) {
+          // A closed vocabulary submits one form value per checked box.
+          data[field.name] = form.getAll(field.name).map(String);
+        } else {
+          // An open or creatable set is one comma-separated input to trimmed, de-duplicated tags.
+          data[field.name] = [
+            ...new Set(
+              String(form.get(field.name) ?? '')
+                .split(',')
+                .map((tag) => tag.trim())
+                .filter(Boolean),
+            ),
+          ];
+        }
         break;
       case 'image': {
         // The hero submits three sub-fields under one key. An empty src means no hero, so omit the
@@ -49,6 +124,30 @@ export function frontmatterFromForm(
         data[field.name] = value;
         break;
       }
+      case 'reference': {
+        // One submitted id. An empty value means no edge, so omit the key (like the image arm)
+        // rather than committing a blank scalar the extractor would have to skip.
+        const id = String(form.get(field.name) ?? '').trim();
+        if (id !== '') data[field.name] = id;
+        break;
+      }
+      case 'array': {
+        if (field.item.type === 'reference') {
+          // One submitted id per selected element. Drop empties and omit the key on an empty list,
+          // so a cleared array leaves no dead key in committed frontmatter.
+          const ids = form.getAll(field.name).map(String).map((id) => id.trim()).filter(Boolean);
+          if (ids.length > 0) data[field.name] = ids;
+          break;
+        }
+        const rows = decodeRows(field.name, field.item, form);
+        if (rows.length > 0) data[field.name] = rows;
+        break;
+      }
+      case 'object': {
+        const obj = decodeField(field.name, field, form);
+        if (obj !== undefined) data[field.name] = obj;
+        break;
+      }
       default:
         // FormData.get returns null for an absent field; normalize to an empty string so
         // a caller reading a text value never gets null.
@@ -75,6 +174,30 @@ export function dateInputValue(value: unknown): string {
   return '';
 }
 
+/**
+ * Coerce a frontmatter datetime value to the naive-local, minute-precision `YYYY-MM-DDTHH:mm` an
+ * `<input type="datetime-local">` wants. A datetime is round-tripped as TEXT, so a stored value is
+ * already this string; the `Date` branch is the fallback for a value gray-matter parsed into a JS
+ * `Date` from an unquoted full-ISO scalar. UTC getters read the value back as it was written,
+ * avoiding a local-timezone shift.
+ */
+export function datetimeInputValue(value: unknown): string {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return '';
+    const yyyy = value.getUTCFullYear().toString().padStart(4, '0');
+    const mm = (value.getUTCMonth() + 1).toString().padStart(2, '0');
+    const dd = value.getUTCDate().toString().padStart(2, '0');
+    const hh = value.getUTCHours().toString().padStart(2, '0');
+    const min = value.getUTCMinutes().toString().padStart(2, '0');
+    return `${yyyy}-${mm}-${dd}T${hh}:${min}`;
+  }
+  if (typeof value === 'string') {
+    const match = value.match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/);
+    return match ? match[0] : '';
+  }
+  return '';
+}
+
 /**
  * True when `s` is a canonical zero-padded `YYYY-MM-DD` string naming a real calendar date.
  * Rejects a wrong format, an impossible month or day, and a JS date-rollover such as
@@ -96,6 +219,99 @@ export function isCalendarDate(s: string): boolean {
   );
 }
 
+/**
+ * Canonicalize one raw reference value to its target id. A Date (a YAML-parsed unquoted date-shaped id)
+ * becomes its UTC-sliced `YYYY-MM-DD` string, so a stored id never depends on the reader's timezone; a
+ * string is trimmed; anything else is the empty string. `validate`, `extractReferenceEdges`, and
+ * `formValues` all read through this, so a hand-edited or rewriter-emitted value canonicalizes identically.
+ */
+export function referenceIdFromValue(value: unknown): string {
+  if (value instanceof Date) return dateInputValue(value);
+  if (typeof value === 'string') return value.trim();
+  return '';
+}
+
+/**
+ * Canonicalize a raw `array(reference)` value to its list of target ids. An array maps each element
+ * through `referenceIdFromValue`; a lone non-empty scalar is one element (a single id a YAML scalar
+ * carries, never dropped to an empty list); anything else is empty. Empty ids are dropped.
+ */
+export function referenceIdsFromValue(value: unknown): string[] {
+  const list = Array.isArray(value)
+    ? value.map(referenceIdFromValue)
+    : typeof value === 'string' && value.trim() !== ''
+      ? [referenceIdFromValue(value)]
+      : [];
+  return list.filter((id) => id !== '');
+}
+
+/** The NamedField[] shape formValues iterates, derived from a container's keyed sub-field record. */
+function namedLeaves(record: Record<string, FieldDescriptor>): NamedField[] {
+  return Object.entries(record).map(([name, f]) => ({ ...f, name }));
+}
+
+/** The form value for one leaf array element, reusing the per-type rules so dates/images/etc. coerce identically. */
+function oneLeafFormValue(field: FieldDescriptor, value: unknown): unknown {
+  return formValues([{ ...field, name: '_' } as NamedField], { _: value })._;
+}
+
+/**
+ * Coerce a raw multiselect value to the string[] the editor's tag/checkbox inputs read. An array maps
+ *  each element through String; a lone non-empty scalar (a single tag a YAML scalar carries) is one
+ *  element rather than dropping to []; anything else is the empty list.
+ */
+function multiselectFormValue(value: unknown): string[] {
+  if (Array.isArray(value)) return value.map(String);
+  if (typeof value === 'string' && value.trim() !== '') return [value.trim()];
+  return [];
+}
+
+/** Coerce parsed frontmatter to the form-ready values the editor inputs expect, one rule per field type. */
+export function formValues(
+  fields: NamedField[],
+  frontmatter: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const field of fields) {
+    const value = frontmatter[field.name];
+    if (field.type === 'date') out[field.name] = dateInputValue(value);
+    // A datetime round-trips as text; a value gray-matter parsed into a Date reformats to the
+    // naive-local minute-precision string the datetime-local input wants.
+    else if (field.type === 'datetime') out[field.name] = datetimeInputValue(value);
+    else if (field.type === 'boolean') out[field.name] = value === true;
+    else if (field.type === 'multiselect') out[field.name] = multiselectFormValue(value);
+    // A hero is a nested object; the default String() arm would corrupt it to '[object Object]'.
+    // Hand the stored object back as-is so the editor reads .src/.alt/.caption on open.
+    else if (field.type === 'image') out[field.name] = value !== null && typeof value === 'object' ? value : undefined;
+    // A reference canonicalizes through the shared coercer: a YAML-parsed Date becomes its UTC-sliced
+    // id, never String(Date) timezone garbage.
+    else if (field.type === 'reference') out[field.name] = referenceIdFromValue(value);
+    // An object recurses one level into a nested form-ready record.
+    else if (field.type === 'object') {
+      const raw = value !== null && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+      out[field.name] = formValues(namedLeaves(field.fields), raw);
+    }
+    else if (field.type === 'array') {
+      // An array(reference) canonicalizes through the shared coercer: a lone scalar becomes a
+      // single-element list rather than dropping to [], and each element is UTC-sliced.
+      if (field.item.type === 'reference') out[field.name] = referenceIdsFromValue(value);
+      else {
+        const elements = Array.isArray(value) ? value : [];
+        const item = field.item;
+        out[field.name] = elements.map((el) =>
+          item.type === 'object'
+            ? formValues(namedLeaves(item.fields), el !== null && typeof el === 'object' ? (el as Record<string, unknown>) : {})
+            : oneLeafFormValue(item, el),
+        );
+      }
+    }
+    // Every other type is a plain string input: a nullish value reads as empty, anything else
+    // stringifies (a string passes through unchanged).
+    else out[field.name] = value == null ? '' : String(value);
+  }
+  return out;
+}
+
 /** Reassemble a markdown file from frontmatter and body for committing. */
 export function serializeMarkdown(frontmatter: object, body: string): string {
   return matter.stringify(body, frontmatter);

package/src/lib/content/manifest.ts

@@ -8,6 +8,7 @@ import { deriveExcerpt } from './excerpt.js';
 import { entryIdentity, asString } from './identity.js';
 import { extractCairnLinks, type CairnRef, type LinkResolve } from './links.js';
 import { extractMediaRefs } from './media-refs.js';
+import { extractReferenceEdges, type ReferenceEdge } from './references.js';
 import type { ConceptDescriptor } from './types.js';
 
 /** One entry's projection: its identity, routing, draft flag, and outbound cairn: edges. */
@@ -26,6 +27,13 @@ export interface ManifestEntry {
    *  the key, and a manifest committed before this field still parses (absent reads as no refs).
    */
   mediaRefs?: string[];
+  /**
+   * The typed frontmatter reference edges this entry declares (`{ field, concept, id }` each). The
+   *  main side of the cross-branch reference index and the reverse `inboundReferences` reader.
+   *  Additive and optional: an entry with no reference fields omits the key, and a manifest committed
+   *  before this field still parses (absent reads as no edges).
+   */
+  references?: ReferenceEdge[];
 }
 
 /** The whole corpus as one committed file. `version` guards a future shape migration. */
@@ -55,6 +63,9 @@ export function manifestEntryFromFile(descriptor: ConceptDescriptor, file: { pat
   // Set mediaRefs only when non-empty, so an image-free entry's row stays byte-identical to before
   // (matching the optional-spread for date and summary).
   const mediaRefs = extractMediaRefs(frontmatter, body, descriptor.fields);
+  // Set references only when non-empty, mirroring mediaRefs, so a reference-free entry's row stays
+  // byte-identical to a manifest committed before this field.
+  const references = extractReferenceEdges(frontmatter, descriptor.fields);
   return {
     id,
     concept: descriptor.id,
@@ -67,6 +78,7 @@ export function manifestEntryFromFile(descriptor: ConceptDescriptor, file: { pat
     draft: frontmatter.draft === true,
     links: extractCairnLinks(body),
     ...(mediaRefs.length ? { mediaRefs } : {}),
+    ...(references.length ? { references } : {}),
   };
 }
 
@@ -79,6 +91,10 @@ function compareRef(a: CairnRef, b: CairnRef): number {
   return a.concept.localeCompare(b.concept) || a.id.localeCompare(b.id);
 }
 
+function compareEdge(a: ReferenceEdge, b: ReferenceEdge): number {
+  return a.field.localeCompare(b.field) || a.concept.localeCompare(b.concept) || a.id.localeCompare(b.id);
+}
+
 /**
  * Serialize canonically: entries sorted by concept then id, links sorted and deduped, a fixed key
  *  order, two-space pretty, and a trailing newline, so the committed file diffs cleanly in a PR.
@@ -94,6 +110,9 @@ export function serializeManifest(manifest: Manifest): string {
     draft: e.draft,
     links: [...e.links].sort(compareRef).map((r) => ({ concept: r.concept, id: r.id })),
     ...(e.mediaRefs && e.mediaRefs.length ? { mediaRefs: [...e.mediaRefs].sort() } : {}),
+    ...(e.references && e.references.length
+      ? { references: [...e.references].sort(compareEdge).map((r) => ({ field: r.field, concept: r.concept, id: r.id })) }
+      : {}),
   }));
   return `${JSON.stringify({ version: 1, entries }, null, 2)}\n`;
 }
@@ -128,6 +147,7 @@ export function parseManifest(raw: string): Manifest {
       (e.date === undefined || typeof e.date === 'string') &&
       (e.summary === undefined || typeof e.summary === 'string') &&
       (e.mediaRefs === undefined || Array.isArray(e.mediaRefs)) &&
+      (e.references === undefined || Array.isArray(e.references)) &&
       Array.isArray(e.links);
     if (!ok) {
       throw new Error(`content manifest: malformed entry ${JSON.stringify(e)}`);
@@ -142,6 +162,18 @@ export function parseManifest(raw: string): Manifest {
         }
       }
     }
+    // references is additive and optional: an entry without it parses (the field reads as absent), so
+    // a manifest committed before this field still builds. When present, validate each edge's shape,
+    // mirroring the link-element validation, so a hand-edited file fails loudly rather than dropping a
+    // malformed edge to undefined.
+    if (e.references !== undefined) {
+      for (const edge of e.references as unknown[]) {
+        const r = edge as Record<string, unknown> | null;
+        if (!r || typeof r !== 'object' || typeof r.field !== 'string' || typeof r.concept !== 'string' || typeof r.id !== 'string') {
+          throw new Error(`content manifest: malformed reference ${JSON.stringify(edge)} in entry ${JSON.stringify(e)}`);
+        }
+      }
+    }
     // Validate each link element's shape, not just that links is an array. inboundLinks and the
     // delete guard read l.concept and l.id, so a string, null, or id-less element would read as
     // undefined and silently drop a real inbound linker. Reject it here instead.
@@ -227,11 +259,20 @@ export function verifyManifest(built: Manifest, committedRaw: string): void {
     version: 1,
     entries: built.entries.map((b) => {
       const c = committedByKey.get(keyOf(b));
-      if (b.mediaRefs && c && c.mediaRefs === undefined) {
-        const { mediaRefs: _dropped, ...rest } = b;
-        return rest;
+      let entry = b;
+      if (entry.mediaRefs && c && c.mediaRefs === undefined) {
+        const { mediaRefs: _dropped, ...rest } = entry;
+        entry = rest;
+      }
+      // references is additive: a site whose committed manifest predates the field must still build,
+      // even when its content carries reference edges. Drop the built entry's references only when the
+      // committed counterpart omits the key, so an un-regenerated site matches while a regenerated one
+      // (committed carries references) still detects real drift in that field.
+      if (entry.references && c && c.references === undefined) {
+        const { references: _dropped, ...rest } = entry;
+        entry = rest;
       }
-      return b;
+      return entry;
     }),
   };
   const normalizedRaw = serializeManifest(normalized);
@@ -248,6 +289,28 @@ export function verifyManifest(built: Manifest, committedRaw: string): void {
   );
 }
 
+/**
+ * Throw if any entry's reference edge points at a target absent from the corpus. The match is the
+ *  `(concept, id)` pair, never id alone, since ids are unique only within a concept. The error names
+ *  the source entry, the field the edge was declared on, and the missing target, so a build failure
+ *  reads as a content fix. References have no prerender backstop the way body links do, so this build
+ *  gate is the only integrity authority; it runs inside the generated virtual-module source (where the
+ *  built manifest is in scope), beside `verifyManifest`.
+ */
+export function verifyReferences(manifest: Manifest): void {
+  const present = new Set(manifest.entries.map(keyOf));
+  for (const entry of manifest.entries) {
+    for (const edge of entry.references ?? []) {
+      const target = `${edge.concept}/${edge.id}`;
+      if (!present.has(target)) {
+        throw new Error(
+          `content reference is dangling: ${entry.concept}/${entry.id} field "${edge.field}" points at ${target}, which does not exist.`,
+        );
+      }
+    }
+  }
+}
+
 /**
  * Replace the entry with the same concept and id, or add it. Order does not matter, since
  *  serializeManifest sorts. This is the save path's incremental patch.
@@ -283,6 +346,40 @@ export function inboundLinks(manifest: Manifest, concept: string, id: string): I
     .map((e) => ({ concept: e.concept, id: e.id, title: e.title, permalink: e.permalink }));
 }
 
+/** One inbound referencer: its identity plus the distinct fields through which it references the target. */
+export interface InboundReference {
+  concept: string;
+  id: string;
+  title: string;
+  permalink: string;
+  /** The distinct fields whose reference edges point at the target, in first-seen order. */
+  fields: string[];
+}
+
+/**
+ * Every entry holding a reference edge at the target, excluding the target itself. The match is the
+ *  `(concept, id)` pair, never id alone, since ids are unique only within a concept (the same keyOf
+ *  identity upsertEntry and removeEntry use). Each referencer carries the distinct fields through
+ *  which it points at the target, for the rename repoint and the delete refusal. Pure over the
+ *  manifest, so the request-time paths and a unit test call it the same way.
+ */
+export function inboundReferences(manifest: Manifest, concept: string, id: string): InboundReference[] {
+  const out: InboundReference[] = [];
+  for (const e of manifest.entries) {
+    if (e.concept === concept && e.id === id) continue;
+    const fields: string[] = [];
+    for (const edge of e.references ?? []) {
+      if (edge.concept === concept && edge.id === id && !fields.includes(edge.field)) {
+        fields.push(edge.field);
+      }
+    }
+    if (fields.length > 0) {
+      out.push({ concept: e.concept, id: e.id, title: e.title, permalink: e.permalink, fields });
+    }
+  }
+  return out;
+}
+
 /**
  * A resolver backed by manifest targets, for the admin preview. A miss returns undefined, so the
  *  render step marks the link broken rather than throwing. The build resolver throws instead.

package/src/lib/content/media-refs.ts

@@ -18,7 +18,7 @@ import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
 import { visit } from 'unist-util-visit';
 import { parseMediaToken } from '../media/reference.js';
-import type { FrontmatterField, ImageValue } from './types.js';
+import type { ImageValue, NamedField } from './types.js';
 
 /**
  * The content hashes one entry references, in first-occurrence order, deduped by hash. Reads the
@@ -30,7 +30,7 @@ import type { FrontmatterField, ImageValue } from './types.js';
 export function extractMediaRefs(
   frontmatter: Record<string, unknown>,
   body: string,
-  fields: FrontmatterField[],
+  fields: NamedField[],
 ): string[] {
   const seen = new Set<string>();
   const hashes: string[] = [];

package/src/lib/content/media-rewrite.ts

@@ -25,6 +25,13 @@ import type { Image, Root } from 'mdast';
 import type { ContainerDirective } from 'mdast-util-directive';
 import { parseMediaToken } from '../media/reference.js';
 import { escapeLinkText } from './links.js';
+import {
+  type FmLine,
+  splitFrontmatter,
+  fmLines,
+  frontmatterKeyRange,
+  escapeForRegExp,
+} from './frontmatter-region.js';
 
 /** One repointed reference: which surface it lived on, the old token as written, and the new token. */
 export interface RepointPlacement {
@@ -73,18 +80,6 @@ function dropOverlappingEdits<T extends { start: number; end: number }>(edits: T
  */
 const MEDIA_TOKEN_SCAN = /media:[A-Za-z0-9._-]+/g;
 
-/**
- * Split a leading frontmatter block off the markdown. `fmBlock` is the `---` fenced block including
- *  both fences and the trailing newline (empty when there is none); `body` is everything after it.
- *  The block leads the document, so a frontmatter offset is already absolute and a body offset needs
- *  `fmBlock.length` added. Shared by every arm so they agree on the boundary.
- */
-function splitFrontmatter(markdown: string): { fmBlock: string; body: string } {
-  const m = markdown.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
-  const fmBlock = m ? m[0] : '';
-  return { fmBlock, body: markdown.slice(fmBlock.length) };
-}
-
 /**
  * Parse a doc with the figure-aware pipeline, so the body arm agrees with what remarkFigure renders
  *  and can see the enclosing `:::figure` container. Mirrors parseFigureDoc in markdown-format.ts.
@@ -109,66 +104,6 @@ function inFigure(tree: Root, target: Image): boolean {
   return found;
 }
 
-/**
- * The split of fmBlock into its lines, each with its block-relative start and end offsets (the end
- *  is the index of the trailing newline, or the block length for the last line). Block offsets are
- *  already absolute since the frontmatter leads the document.
- */
-interface FmLine {
-  start: number;
-  end: number;
-}
-
-/**
- * Split fmBlock into lines once, so the locator helpers walk a shared structure instead of
- *  re-scanning the block per call.
- */
-function fmLines(fmBlock: string): FmLine[] {
-  const lines: FmLine[] = [];
-  let pos = 0;
-  while (pos <= fmBlock.length) {
-    const nl = fmBlock.indexOf('\n', pos);
-    const end = nl === -1 ? fmBlock.length : nl;
-    lines.push({ start: pos, end });
-    if (nl === -1) break;
-    pos = nl + 1;
-  }
-  return lines;
-}
-
-/**
- * The inclusive line-index range `[lo, hi]` of the block-style mapping a top-level key opens: the
- *  line `^<key>:` at indent 0 through the last line before the next top-level key (or the document
- *  end). A flow-style value (`key: { ... }` all on one line) yields a single-line range. Returns null
- *  when the key has no top-level line, which a malformed or non-canonical block can cause. Scoping the
- *  per-key search to this range is what lets two image fields that share one hash, or an image field
- *  whose hash also appears in a sibling text value, resolve to distinct, correct spans.
- */
-function frontmatterKeyRange(lines: FmLine[], fmBlock: string, key: string): [number, number] | null {
-  const opener = new RegExp(`^${escapeForRegExp(key)}:`);
-  const topLevelKey = /^[^\s#][^:]*:/;
-  const isBoundary = (i: number) => {
-    const text = fmBlock.slice(lines[i].start, lines[i].end);
-    // A new top-level key or the closing `---` fence ends the current key's block.
-    return topLevelKey.test(text) || text === '---';
-  };
-  let lo = -1;
-  for (let i = 1; i < lines.length - 1; i += 1) {
-    // Skip the leading `---` fence (line 0) and the trailing empty line after the closing fence.
-    if (opener.test(fmBlock.slice(lines[i].start, lines[i].end))) {
-      lo = i;
-      break;
-    }
-  }
-  if (lo === -1) return null;
-  let hi = lo;
-  for (let i = lo + 1; i < lines.length - 1; i += 1) {
-    if (isBoundary(i)) break;
-    hi = i;
-  }
-  return [lo, hi];
-}
-
 /**
  * A located `src:` line inside a block-style mapping: the line's start and end, its leading indent,
  *  and the exact `media:` token's block-relative offsets and text.
@@ -470,14 +405,6 @@ function bodyAltEdits(body: string, blockLength: number, hash: string, defaultAl
   return edits;
 }
 
-/**
- * Escape a literal string for safe interpolation into a RegExp source. A key name or an indent is
- *  matched literally, so its characters must not act as metacharacters.
- */
-function escapeForRegExp(literal: string): string {
-  return literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 /**
  * Find a sibling key line (`alt:` or `decorative:`) at exactly `indent` within the inclusive
  *  line-index range `[lo, hi]` of one mapping. The range is the mapping's own block, so the search