@glw907/cairn-cms 0.68.0 → 0.76.0

package/dist/content/frontmatter.js

@@ -3,6 +3,78 @@
 // 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';
+/**
+ * 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) {
+    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, field, form) {
+    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 = { 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 = {};
+            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, item, form) {
+    const indices = new Set();
+    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 = [];
+    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, form) {
     const data = {};
@@ -11,17 +83,20 @@ export function frontmatterFromForm(fields, form) {
             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
@@ -45,6 +120,34 @@ export function frontmatterFromForm(fields, form) {
                 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.
@@ -69,6 +172,30 @@ export function dateInputValue(value) {
     }
     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) {
+    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
@@ -88,6 +215,100 @@ export function isCalendarDate(s) {
         date.getUTCMonth() === month - 1 &&
         date.getUTCDate() === day);
 }
+/**
+ * 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) {
+    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) {
+    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) {
+    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, value) {
+    return formValues([{ ...field, name: '_' }], { _: 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) {
+    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, frontmatter) {
+    const out = {};
+    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 : {};
+            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 : {})
+                    : 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, body) {
     return matter.stringify(body, frontmatter);

package/dist/content/manifest.d.ts

@@ -1,4 +1,5 @@
 import { type CairnRef, type LinkResolve } from './links.js';
+import { type ReferenceEdge } from './references.js';
 import type { ConceptDescriptor } from './types.js';
 /** One entry's projection: its identity, routing, draft flag, and outbound cairn: edges. */
 export interface ManifestEntry {
@@ -16,6 +17,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. */
 export interface Manifest {
@@ -79,6 +87,15 @@ export declare function diffManifests(built: Manifest, committed: Manifest): Man
  *  committed manifest stale fails the build loudly with what drifted.
  */
 export declare 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 declare function verifyReferences(manifest: Manifest): void;
 /**
  * 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.
@@ -99,6 +116,23 @@ export interface InboundLink {
  *  manifest, so the request-time delete path and a unit test call it the same way.
  */
 export declare function inboundLinks(manifest: Manifest, concept: string, id: string): InboundLink[];
+/** 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 declare function inboundReferences(manifest: Manifest, concept: string, id: string): InboundReference[];
 /**
  * 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/dist/content/manifest.js

@@ -8,6 +8,7 @@ import { deriveExcerpt } from './excerpt.js';
 import { entryIdentity, asString } from './identity.js';
 import { extractCairnLinks } from './links.js';
 import { extractMediaRefs } from './media-refs.js';
+import { extractReferenceEdges } from './references.js';
 /**
  * Build one manifest entry from a content file. Drafts are included and flagged. The id, date, and
  *  permalink come from entryIdentity, the same source content-index uses, so a cairn: link resolves to
@@ -19,6 +20,9 @@ export function manifestEntryFromFile(descriptor, file) {
     // 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,
@@ -31,6 +35,7 @@ export function manifestEntryFromFile(descriptor, file) {
         draft: frontmatter.draft === true,
         links: extractCairnLinks(body),
         ...(mediaRefs.length ? { mediaRefs } : {}),
+        ...(references.length ? { references } : {}),
     };
 }
 /** An empty manifest, the starting point when no committed file exists yet. */
@@ -40,6 +45,9 @@ export function emptyManifest() {
 function compareRef(a, b) {
     return a.concept.localeCompare(b.concept) || a.id.localeCompare(b.id);
 }
+function compareEdge(a, b) {
+    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.
@@ -55,6 +63,9 @@ export function serializeManifest(manifest) {
         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`;
 }
@@ -87,6 +98,7 @@ export function parseManifest(raw) {
             (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)}`);
@@ -101,6 +113,18 @@ export function parseManifest(raw) {
                 }
             }
         }
+        // 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) {
+                const r = edge;
+                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.
@@ -172,11 +196,20 @@ export function verifyManifest(built, committedRaw) {
         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);
@@ -191,6 +224,25 @@ export function verifyManifest(built, committedRaw) {
         formatDiff(diff) +
         '\nRegenerate it (npm run cairn:manifest) and commit the result.');
 }
+/**
+ * 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) {
+    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.
@@ -215,6 +267,30 @@ export function inboundLinks(manifest, concept, id) {
         .filter((e) => e.links.some((l) => l.concept === concept && l.id === id))
         .map((e) => ({ concept: e.concept, id: e.id, title: e.title, permalink: e.permalink }));
 }
+/**
+ * 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, concept, id) {
+    const out = [];
+    for (const e of manifest.entries) {
+        if (e.concept === concept && e.id === id)
+            continue;
+        const fields = [];
+        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/dist/content/media-refs.d.ts

@@ -1,4 +1,4 @@
-import type { FrontmatterField } from './types.js';
+import type { NamedField } from './types.js';
 /**
  * The content hashes one entry references, in first-occurrence order, deduped by hash. Reads the
  *  frontmatter hero `image.src` for each `image`-typed field plus every body image node. A
@@ -6,4 +6,4 @@ import type { FrontmatterField } from './types.js';
  *  the manifest build. The body is parsed as mdast, so a `media:` token inside a code span or fence
  *  is never matched.
  */
-export declare function extractMediaRefs(frontmatter: Record<string, unknown>, body: string, fields: FrontmatterField[]): string[];
+export declare function extractMediaRefs(frontmatter: Record<string, unknown>, body: string, fields: NamedField[]): string[];

package/dist/content/media-rewrite.js

@@ -23,6 +23,7 @@ import remarkDirective from 'remark-directive';
 import { visit } from 'unist-util-visit';
 import { parseMediaToken } from '../media/reference.js';
 import { escapeLinkText } from './links.js';
+import { splitFrontmatter, fmLines, frontmatterKeyRange, escapeForRegExp, } from './frontmatter-region.js';
 /**
  * Drop any span that overlaps a span already kept, in source order. A final safety net so two
  *  splices can never target the same or overlapping bytes and clobber each other into a corrupt
@@ -46,17 +47,6 @@ function dropOverlappingEdits(edits) {
  *  destination ends the candidate.
  */
 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) {
-    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.
@@ -81,57 +71,6 @@ function inFigure(tree, target) {
     });
     return found;
 }
-/**
- * Split fmBlock into lines once, so the locator helpers walk a shared structure instead of
- *  re-scanning the block per call.
- */
-function fmLines(fmBlock) {
-    const lines = [];
-    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, fmBlock, key) {
-    const opener = new RegExp(`^${escapeForRegExp(key)}:`);
-    const topLevelKey = /^[^\s#][^:]*:/;
-    const isBoundary = (i) => {
-        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];
-}
 /**
  * Find the block-style `src:` line within `[lo, hi]` whose value token parses to `hash`. The token
  *  is located by the broad scan and validated through parseMediaToken (matching on hash), so a
@@ -365,13 +304,6 @@ function bodyAltEdits(body, blockLength, hash, defaultAlt, overwrite) {
     }
     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) {
-    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

package/dist/content/reference-index.d.ts

@@ -0,0 +1,56 @@
+import type { ConceptDescriptor } from './types.js';
+import type { Backend } from '../github/backend.js';
+import type { Manifest } from './manifest.js';
+/**
+ * Where a reference lives: the published corpus on main, or a named open edit branch. Re-declared here
+ *  (rather than imported from media/usage.ts) so the content layer does not depend on the media layer.
+ */
+export type UsageOrigin = {
+    kind: 'published';
+} | {
+    kind: 'branch';
+    branch: string;
+};
+/** One entry that references a target, in a shape the rename and delete gates name and group by. */
+export interface ReferenceUsageEntry {
+    /** The referencing (source) entry's concept id, e.g. "posts". */
+    concept: string;
+    /** The referencing (source) entry's id (its filename stem). */
+    id: string;
+    /** The referencing entry's title for display, from the manifest (published) or frontmatter (branch). */
+    title: string;
+    /** The referencing entry's public permalink, present for a published entry (carried from the manifest). */
+    permalink?: string;
+    /** The frontmatter field the edge was declared on. */
+    field: string;
+    /** Published vs the cairn/* branch the edit lives on. */
+    origin: UsageOrigin;
+}
+/**
+ * The target's `${concept}/${id}` pair to the distinct entries that reference it. A pair with no row is
+ *  not referenced anywhere the index could read (main plus the listed open branches).
+ */
+export type ReferenceIndex = Map<string, ReferenceUsageEntry[]>;
+/**
+ * Build options. `branches` lets a caller that already listed the open cairn/* branches pass them in so
+ *  the index does not list them a second time. `strict` flips the per-branch read from degrade-and-skip
+ *  to fail-closed: a delete or rename gate must not treat a transient branch-read failure as an absent
+ *  reference, so it rethrows instead.
+ */
+export interface BuildReferenceOptions {
+    /** The open cairn/* branch names, already listed. When present the index skips its own listing. */
+    branches?: string[];
+    /** When true a branch read that throws rejects the whole build, so the caller can fail closed. */
+    strict?: boolean;
+}
+/**
+ * Build the pair-keyed reference index over main (from the manifest's per-entry references) plus every
+ * open cairn/* branch (parsed from its edited markdown).
+ *
+ * By default a single branch read that throws degrades that one branch and is skipped, the way the
+ * admin loaders degrade a failed read. That tolerance is wrong for the rename and delete gates: a
+ * transient branch-read failure would make a still-referenced target look free. Pass `strict: true` to
+ * rethrow a branch failure so the caller fails closed. Pass `branches` to reuse a branch list the
+ * caller already has rather than listing them a second time.
+ */
+export declare function buildReferenceIndex(backend: Backend, concepts: ConceptDescriptor[], manifest: Manifest, opts?: BuildReferenceOptions): Promise<ReferenceIndex>;