@glw907/cairn-cms 0.56.1 → 0.57.0

package/dist/components/markdown-format.js

@@ -6,8 +6,10 @@
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
+import remarkDirective from 'remark-directive';
 import { visit } from 'unist-util-visit';
 import { escapeLinkText } from '../content/links.js';
+import { parseMediaToken } from '../media/reference.js';
 const WRAP = { bold: '**', italic: '_', code: '`', strike: '~~' };
 /**
  * Per-kind line-prefix behavior. `prefix` builds the marker for the line's 0-based index (only ol
@@ -122,6 +124,47 @@ export function insertInlineLink(doc, from, to, href, title) {
     const end = from + inserted.length;
     return { doc: doc.slice(0, from) + inserted + doc.slice(to), from: end, to: end };
 }
+/**
+ * Insert an inline markdown image at the selection. The committed form is `![alt](ref)` where `ref`
+ * is the full `media:slug.hash` token. The alt is escaped the way an inline link's title is (the `[`
+ * and `]` an author types must not break the image syntax); a selection is replaced rather than
+ * wrapped, since an image carries no display text to wrap. The cursor collapses just after the
+ * inserted text, and no surrounding blank lines are added, since an image is inline. Pure, so the
+ * editor dispatches the result.
+ */
+export function insertImage(doc, from, to, alt, ref) {
+    const inserted = `![${escapeLinkText(alt)}](${ref})`;
+    const end = from + inserted.length;
+    return { doc: doc.slice(0, from) + inserted + doc.slice(to), from: end, to: end };
+}
+/**
+ * Scan a markdown body for media images that carry no alt text, the publish-time accessibility debt
+ * the edit page counts. The document is parsed with the same remark pipeline unwrapCairnLink uses,
+ * so the two agree on what an image is. Each `image` node whose url is a valid `media:` reference and
+ * whose alt is empty or whitespace-only is returned with its source offsets and parsed slug and hash.
+ * Parsing (not a raw regex) means a `![](media:x)` written inside a code span or fence is not an
+ * image node and is correctly ignored, as is an alt-bearing media image and any non-media image (an
+ * http or cairn: url). Pure and node-safe, so the edit page derives the live count without a browser.
+ * The bare `media:<hash>` form yields an empty slug.
+ */
+export function findMediaImagesNeedingAlt(doc) {
+    const tree = unified().use(remarkParse).use(remarkGfm).parse(doc);
+    const hits = [];
+    visit(tree, 'image', (node) => {
+        const ref = parseMediaToken(node.url);
+        if (!ref)
+            return;
+        if ((node.alt ?? '').trim() !== '')
+            return;
+        const from = node.position?.start?.offset;
+        const to = node.position?.end?.offset;
+        if (from == null || to == null)
+            return;
+        hits.push({ from, to, ref: node.url, slug: ref.slug ?? '', hash: ref.hash });
+    });
+    hits.sort((a, b) => a.from - b.from);
+    return hits;
+}
 /** Concatenate a link node's text-child values. The parser has already unescaped them, so a source
  *  `Notes \[draft\]` yields `Notes [draft]`. Used instead of mdast-util-to-string, which is not a
  *  direct dependency. Non-text children (a nested emphasis, say) contribute no value, which is fine
@@ -157,3 +200,215 @@ export function unwrapCairnLink(doc, href) {
     }
     return out;
 }
+const FIGURE_ROLES = new Set(['center', 'wide', 'full']);
+/** Parse a doc with the figure-aware pipeline (the render step's grammar), so the editor transforms
+ *  agree with what renders. Container directives need remark-directive on top of the markdown base. */
+function parseFigureDoc(doc) {
+    return unified().use(remarkParse).use(remarkGfm).use(remarkDirective).parse(doc);
+}
+/** Find the media `image` node whose source range contains `pos`, or whose enclosing figure contains
+ *  `pos`, along with its enclosing `figure` directive when there is one. Returns null when `pos` is
+ *  not on a media image nor inside a figure that wraps one. */
+function locateMediaImage(tree, pos) {
+    let bareHit = null;
+    let figureHit = null;
+    // Track the figure ancestor while visiting; unist-util-visit hands the ancestors array last.
+    visit(tree, 'image', (node, _index, _parent) => {
+        if (!parseMediaToken(node.url))
+            return;
+        const from = node.position?.start?.offset;
+        const to = node.position?.end?.offset;
+        if (from == null || to == null)
+            return;
+        const figure = enclosingFigure(tree, node);
+        if (pos >= from && pos <= to) {
+            if (figure)
+                figureHit = { image: node, figure };
+            else if (!bareHit)
+                bareHit = { image: node, figure: null };
+            return;
+        }
+        // The caret can sit in the caption, off the image token; a media image inside a figure whose
+        // block range contains pos still counts as "at" that figure.
+        if (figure) {
+            const f0 = figure.position?.start?.offset;
+            const f1 = figure.position?.end?.offset;
+            if (f0 != null && f1 != null && pos >= f0 && pos <= f1 && !figureHit) {
+                figureHit = { image: node, figure };
+            }
+        }
+    });
+    // A figure hit (the caret on the image or anywhere in its block) wins over a bare hit.
+    return figureHit ?? bareHit;
+}
+/** The `figure`-named container directive that encloses `node`, or null. Walks the tree to find the
+ *  ancestor, since unist-util-visit's per-call ancestors are not retained across the traversal. */
+function enclosingFigure(tree, target) {
+    let found = null;
+    visit(tree, 'containerDirective', (dir) => {
+        if (dir.name !== 'figure')
+            return;
+        let holds = false;
+        visit(dir, 'image', (img) => {
+            if (img === target)
+                holds = true;
+        });
+        if (holds)
+            found = dir;
+    });
+    return found;
+}
+/** Strip one leading backslash sitting immediately before a colon, the inverse of the fence-escape
+ *  wrapImageInFigure/updateFigure apply, so a caption that began with a directive-opening colon run
+ *  round-trips to the author's original text. */
+function unescapeCaption(raw) {
+    return raw.replace(/^\\(?=:)/, '');
+}
+/** Collapse a raw caption source span to the single-line value the control edits: internal newlines
+ *  to single spaces, trimmed, with the leading-colon fence escape stripped. */
+function finishCaption(raw) {
+    return unescapeCaption(raw.replace(/\s*\n\s*/g, ' ').trim());
+}
+/** Read the raw caption source from a figure directive, mirroring the render step's caption: the first
+ *  text-bearing content after the image. The render step (remark-figure.ts) handles both caption
+ *  forms, so the read must too. In the no-blank-line form the caption shares the image's paragraph,
+ *  trailing the token, so it is read from the token end to that block's end; in the blank-line form it
+ *  is the first text-bearing block after the image's paragraph. Only the first such content is the
+ *  caption (a later block is a stray paragraph the render leaves outside the figcaption). Empty when
+ *  the figure has no caption. */
+function readCaption(doc, figure, image) {
+    const imageStart = image.position?.start?.offset;
+    const imageEnd = image.position?.end?.offset;
+    if (imageStart == null || imageEnd == null)
+        return '';
+    // The figure's direct child that holds the image (its paragraph).
+    const imageBlock = figure.children.find((child) => {
+        const start = child.position?.start?.offset;
+        const end = child.position?.end?.offset;
+        return start != null && end != null && start <= imageStart && end >= imageEnd;
+    });
+    // No-blank-line form: caption text trails the token inside the image's own paragraph.
+    const blockEnd = imageBlock?.position?.end?.offset;
+    if (blockEnd != null && doc.slice(imageEnd, blockEnd).trim() !== '') {
+        return finishCaption(doc.slice(imageEnd, blockEnd));
+    }
+    // Blank-line form: the first text-bearing block after the image's paragraph.
+    const afterEnd = blockEnd ?? imageEnd;
+    for (const child of figure.children) {
+        const start = child.position?.start?.offset;
+        const end = child.position?.end?.offset;
+        if (start == null || end == null)
+            continue;
+        if (start < afterEnd)
+            continue;
+        if (!blockHasText(child))
+            continue;
+        return finishCaption(doc.slice(start, end));
+    }
+    return '';
+}
+/** Whether a block's subtree carries any non-whitespace text, the caption-candidate test the render
+ *  step uses (a bare image paragraph has no text node, so it is never read as a caption). */
+function blockHasText(node) {
+    let found = false;
+    visit(node, 'text', (text) => {
+        if (text.value.trim() !== '')
+            found = true;
+    });
+    return found;
+}
+/**
+ * Inspect the media image at caret position `pos`. Returns the image's exact token offsets plus the
+ * enclosing `:::figure` block (its range, raw caption, and role) when the image is wrapped, or
+ * `figure: null` when it is bare. Returns null when `pos` is not on or in a media image. The parse
+ * uses the figure-aware pipeline, so this agrees with what remarkFigure renders. Pure and node-safe.
+ */
+export function figureAtImage(doc, pos) {
+    const tree = parseFigureDoc(doc);
+    const hit = locateMediaImage(tree, pos);
+    if (!hit)
+        return null;
+    const imageFrom = hit.image.position?.start?.offset;
+    const imageTo = hit.image.position?.end?.offset;
+    if (imageFrom == null || imageTo == null)
+        return null;
+    if (!hit.figure)
+        return { imageFrom, imageTo, figure: null };
+    const dir = hit.figure;
+    const from = dir.position?.start?.offset;
+    const to = dir.position?.end?.offset;
+    if (from == null || to == null)
+        return { imageFrom, imageTo, figure: null };
+    const className = dir.attributes?.class ?? undefined;
+    const role = className && FIGURE_ROLES.has(className) ? className : null;
+    return { imageFrom, imageTo, figure: { from, to, caption: readCaption(doc, dir, hit.image), role } };
+}
+/** Sanitize a caption into a single safe body line: collapse internal newlines to single spaces,
+ *  trim, and neutralize ONLY the directive-fence hazard (a leading colon would open a directive at
+ *  line start) by prefixing one backslash. The author's inline markdown is preserved otherwise, so
+ *  emphasis and links survive. figureAtImage strips the backslash on read for a clean round-trip. */
+function sanitizeCaption(caption) {
+    const line = caption.replace(/\s*\n\s*/g, ' ').trim();
+    return line.startsWith(':') ? '\\' + line : line;
+}
+/** Build the canonical figure block source: the opener (with the role brace only for a non-null
+ *  role), the image token verbatim on its own line, then a blank line and the sanitized caption when
+ *  the caption is non-empty, and the closing fence. This is the blank-line form remarkFigure reads as
+ *  its primary path, and it reads cleanly when hand-edited. */
+function buildFigureBlock(imageSrc, caption, role) {
+    const opener = role ? `:::figure{.${role}}` : ':::figure';
+    const cap = sanitizeCaption(caption);
+    const body = cap ? `${imageSrc}\n\n${cap}` : imageSrc;
+    return `${opener}\n${body}\n:::`;
+}
+/**
+ * Wrap a bare media image in a `:::figure` block. The image token is reused EXACTLY from its source
+ * offsets and never reserialized (open risk 3: the atomic `media:` reference stays byte-identical).
+ * The block lands on its own lines, with a blank line before it (unless it starts the document) and
+ * after it, so it reads as a clean block even when the image sat inline in a paragraph. The selection
+ * collapses just past the inserted block.
+ */
+export function wrapImageInFigure(doc, imageFrom, imageTo, caption, role) {
+    const imageSrc = doc.slice(imageFrom, imageTo);
+    const block = buildFigureBlock(imageSrc, caption, role);
+    const before = doc.slice(0, imageFrom);
+    const after = doc.slice(imageTo);
+    // Ensure the block starts on its own line: a blank line before it unless it opens the doc or the
+    // text before it already ends with one. Trailing context gets a matching blank line.
+    const lead = before === '' ? '' : before.endsWith('\n\n') ? '' : before.endsWith('\n') ? '\n' : '\n\n';
+    const trail = after === '' ? '' : after.startsWith('\n\n') ? '' : after.startsWith('\n') ? '\n' : '\n\n';
+    const inserted = lead + block + trail;
+    const blockStart = imageFrom + lead.length;
+    const end = blockStart + block.length;
+    return { doc: before + inserted + after, from: end, to: end };
+}
+/** The inner image token of the figure at `figureRange.from`, sliced verbatim from the source so it
+ *  is reused byte-for-byte (open risk 3). Empty when no media image is found there, which leaves the
+ *  rebuild image-less rather than throwing. Shared by updateFigure and unwrapFigure. */
+function figureImageSrc(doc, figureRange) {
+    const info = figureAtImage(doc, figureRange.from);
+    return info ? doc.slice(info.imageFrom, info.imageTo) : '';
+}
+/**
+ * Rewrite an existing figure's caption and role in place. The inner image token is extracted from the
+ * current block and PRESERVED BYTE-FOR-BYTE (open risk 3); the block is rebuilt in the blank-line
+ * form with the new opener and caption. The selection collapses just past the rewritten block.
+ */
+export function updateFigure(doc, figureRange, caption, role) {
+    const block = buildFigureBlock(figureImageSrc(doc, figureRange), caption, role);
+    const end = figureRange.from + block.length;
+    return { doc: doc.slice(0, figureRange.from) + block + doc.slice(figureRange.to), from: end, to: end };
+}
+/**
+ * Unwrap a figure block back to its bare image line, dropping the caption and the directive fences.
+ * The inner image token is reused verbatim (open risk 3). The selection lands on the restored image
+ * so the author can act on it again.
+ */
+export function unwrapFigure(doc, figureRange) {
+    const imageSrc = figureImageSrc(doc, figureRange);
+    return {
+        doc: doc.slice(0, figureRange.from) + imageSrc + doc.slice(figureRange.to),
+        from: figureRange.from,
+        to: figureRange.from + imageSrc.length,
+    };
+}

package/dist/components/media-upload-outcome.d.ts

@@ -0,0 +1,52 @@
+import type { MediaEntry } from '../media/manifest.js';
+import type { UploadResult } from '../sveltekit/content-routes.js';
+import type { IngestFailureKind } from './client-ingest.js';
+/** A failure the card surfaces. The ingest taxonomy plus a `generic` catch-all for a refuse reason
+ *  with no specific author-facing card (a binding-missing, a length-required, a parse miss). */
+export type UploadFailureKind = IngestFailureKind | 'generic';
+/** The outcome the popover acts on. `inserted` swaps the placeholder for the reference and records
+ *  the entry; `failed` cancels the placeholder and shows the typed card; `session-expired` cancels
+ *  the placeholder and tells the author to sign in again. */
+export type UploadOutcome = {
+    kind: 'inserted';
+    reference: string;
+    record: MediaEntry;
+    reused: boolean;
+} | {
+    kind: 'failed';
+    failure: UploadFailureKind;
+} | {
+    kind: 'session-expired';
+};
+/** The shape the popover hands in: either a parsed SvelteKit action result (success or failure) or a
+ *  bare response signal for the redirect and network-error cases. The popover deserializes the body
+ *  for the success and failure cases and passes the raw `response.type`/`response.status` for the
+ *  redirect case, so this one mapper covers every branch. */
+export type UploadEnvelope = {
+    type: 'success';
+    status?: number;
+    data: UploadResult;
+} | {
+    type: 'failure';
+    status?: number;
+    data?: {
+        error?: string;
+    };
+} | {
+    type: 'redirect';
+    status?: number;
+} | {
+    type: 'error';
+    status?: number;
+} | {
+    type: 'opaqueredirect';
+    status?: number;
+};
+/**
+ * Map a parsed upload envelope to the single outcome the popover acts on. A success envelope yields
+ * an `inserted` outcome carrying the reference, the record, and the dedup flag. A failure envelope
+ * maps its refuse reason to a typed card, with `session-expired` lifted to its own outcome. An
+ * opaque or status-0 response (the guard's `redirect: 'manual'` 303) is a session-expired signal, as
+ * is any redirect-typed result. An error-typed result with a real status is a generic failure.
+ */
+export declare function uploadOutcome(envelope: UploadEnvelope): UploadOutcome;

package/dist/components/media-upload-outcome.js

@@ -0,0 +1,48 @@
+import { mediaToken } from '../media/reference.js';
+// The server refuse reasons mapped to a card kind. `too-large` keeps its own card; an unsupported
+// type reads as a decode failure to the author (the bytes the browser sent are a type the server
+// will not store); `session-expired` is its own outcome. Every other reason (binding-missing,
+// media-disabled, csrf, length-required, hash-collision) is an operational refusal with no
+// author-actionable specifics, so it collapses to the generic card.
+const REFUSE_TO_FAILURE = {
+    'too-large': 'too-large',
+    'unsupported-type': 'decode-unsupported',
+    'session-expired': 'session-expired',
+};
+/**
+ * Map a parsed upload envelope to the single outcome the popover acts on. A success envelope yields
+ * an `inserted` outcome carrying the reference, the record, and the dedup flag. A failure envelope
+ * maps its refuse reason to a typed card, with `session-expired` lifted to its own outcome. An
+ * opaque or status-0 response (the guard's `redirect: 'manual'` 303) is a session-expired signal, as
+ * is any redirect-typed result. An error-typed result with a real status is a generic failure.
+ */
+export function uploadOutcome(envelope) {
+    switch (envelope.type) {
+        case 'success':
+            return {
+                kind: 'inserted',
+                // Re-derive the reference from the validated record fields rather than trusting the loose
+                // server `reference` string: the token is inserted unescaped into the markdown URL slot, so
+                // the insert depends only on grammar-constrained fields (a 16-hex hash, a slugified slug)
+                // instead of an arbitrary server string. Defense in depth, in case a future server path
+                // returns a reference that does not match the record.
+                reference: mediaToken({ slug: envelope.data.record.slug, hash: envelope.data.record.hash }),
+                record: envelope.data.record,
+                reused: envelope.data.reused,
+            };
+        case 'failure': {
+            const reason = envelope.data?.error ?? '';
+            const mapped = REFUSE_TO_FAILURE[reason];
+            if (mapped === 'session-expired')
+                return { kind: 'session-expired' };
+            return { kind: 'failed', failure: mapped ?? 'generic' };
+        }
+        case 'redirect':
+        case 'opaqueredirect':
+            return { kind: 'session-expired' };
+        case 'error':
+            // A manual-redirect Response surfaces as type 'opaqueredirect' or status 0; a status-0 error
+            // is that same expired-session signal. A real error status is a genuine transport failure.
+            return (envelope.status ?? 0) === 0 ? { kind: 'session-expired' } : { kind: 'failed', failure: 'generic' };
+    }
+}

package/dist/content/compose.js

@@ -1,4 +1,5 @@
 import { resolveConcepts } from './concepts.js';
+import { normalizeAssets } from '../media/config.js';
 /**
  * Fold an adapter and any extensions into the composed runtime (seam 2). The per-concept URL policy
  * is derived from the site config, the same source the delivery path uses, so the runtime and
@@ -33,6 +34,8 @@ export function composeRuntime({ adapter, siteConfig, extensions = [] }) {
         navMenu: adapter.navMenu,
         preview: adapter.preview,
         assets: adapter.assets,
+        resolvedAssets: normalizeAssets(adapter.assets),
+        mediaManifestPath: adapter.mediaManifestPath ?? 'src/content/.cairn/media.json',
         adminPanels,
         fieldTypes,
     };

package/dist/content/frontmatter.js

@@ -23,6 +23,23 @@ export function frontmatterFromForm(fields, form) {
                         .filter(Boolean)),
                 ];
                 break;
+            case 'image': {
+                // The hero submits three sub-fields under one key. An empty src means no hero, so omit the
+                // whole key. Alt is stored verbatim (it is not markdown, so no escaping). A blank caption
+                // is dropped so committed frontmatter stays minimal.
+                const src = String(form.get(`${field.name}.src`) ?? '').trim();
+                if (src === '')
+                    break;
+                const value = {
+                    src,
+                    alt: String(form.get(`${field.name}.alt`) ?? ''),
+                };
+                const caption = String(form.get(`${field.name}.caption`) ?? '').trim();
+                if (caption !== '')
+                    value.caption = caption;
+                data[field.name] = value;
+                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.

package/dist/content/manifest.d.ts

@@ -10,6 +10,10 @@ export interface ManifestEntry {
     summary?: string;
     draft: boolean;
     links: CairnRef[];
+    /** The content hashes of the media this entry references (its hero plus its body images). The
+     *  main side of the media where-used index. Additive and optional: an entry with no media omits
+     *  the key, and a manifest committed before this field still parses (absent reads as no refs). */
+    mediaRefs?: string[];
 }
 /** The whole corpus as one committed file. `version` guards a future shape migration. */
 export interface Manifest {

package/dist/content/manifest.js

@@ -7,12 +7,16 @@ import { parseMarkdown } from './frontmatter.js';
 import { deriveExcerpt } from './excerpt.js';
 import { entryIdentity, asString } from './identity.js';
 import { extractCairnLinks } from './links.js';
+import { extractMediaRefs } from './media-refs.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
  *  one URL whether the admin preview reads the manifest or the public build reads the content index. */
 export function manifestEntryFromFile(descriptor, file) {
     const { frontmatter, body } = parseMarkdown(file.raw);
     const { id, date, permalink } = entryIdentity(descriptor, file.path, frontmatter);
+    // 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);
     return {
         id,
         concept: descriptor.id,
@@ -24,6 +28,7 @@ export function manifestEntryFromFile(descriptor, file) {
         summary: deriveExcerpt(body, { description: asString(frontmatter.description) }) || undefined,
         draft: frontmatter.draft === true,
         links: extractCairnLinks(body),
+        ...(mediaRefs.length ? { mediaRefs } : {}),
     };
 }
 /** An empty manifest, the starting point when no committed file exists yet. */
@@ -45,6 +50,7 @@ export function serializeManifest(manifest) {
         ...(e.summary ? { summary: e.summary } : {}),
         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() } : {}),
     }));
     return `${JSON.stringify({ version: 1, entries }, null, 2)}\n`;
 }
@@ -74,10 +80,21 @@ export function parseManifest(raw) {
             typeof e.draft === 'boolean' &&
             (e.date === undefined || typeof e.date === 'string') &&
             (e.summary === undefined || typeof e.summary === 'string') &&
+            (e.mediaRefs === undefined || Array.isArray(e.mediaRefs)) &&
             Array.isArray(e.links);
         if (!ok) {
             throw new Error(`content manifest: malformed entry ${JSON.stringify(e)}`);
         }
+        // mediaRefs 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 element
+        // is a string, mirroring the link-element validation, so a hand-edited file fails loudly.
+        if (e.mediaRefs !== undefined) {
+            for (const hash of e.mediaRefs) {
+                if (typeof hash !== 'string') {
+                    throw new Error(`content manifest: malformed mediaRefs element ${JSON.stringify(hash)} 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.
@@ -132,11 +149,34 @@ export function verifyManifest(built, committedRaw) {
     const builtRaw = serializeManifest(built);
     if (committedRaw === builtRaw)
         return;
+    // mediaRefs is additive: a site whose committed manifest predates the field must still build,
+    // even when its content references media (open risk 3, the migration landmine). Before diffing,
+    // normalize the built manifest against the committed one: for any built entry whose committed
+    // counterpart carries no mediaRefs key, drop mediaRefs from the built entry. An un-regenerated
+    // site (committed omits mediaRefs) then matches; a regenerated site (committed carries mediaRefs)
+    // still detects real drift in that field. The normalization is per entry and per missing key, so
+    // it never masks drift in any other field or in an entry the committed manifest already tracks.
+    const committed = parseManifest(committedRaw);
+    const committedByKey = new Map(committed.entries.map((e) => [keyOf(e), e]));
+    const normalized = {
+        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;
+            }
+            return b;
+        }),
+    };
+    const normalizedRaw = serializeManifest(normalized);
+    if (committedRaw === normalizedRaw)
+        return;
     // Diff the canonical built form, not the raw one. serializeManifest sorts each entry's links, so a
     // build whose links are in extraction order would otherwise report a false (links) drift for an
     // entry whose link set is identical and only the order differs. Reuse the serialized form so both
     // sides are canonical.
-    const diff = diffManifests(parseManifest(builtRaw), parseManifest(committedRaw));
+    const diff = diffManifests(parseManifest(normalizedRaw), committed);
     throw new Error('content manifest is stale: the committed file does not match the corpus.\n' +
         formatDiff(diff) +
         '\nRegenerate it (npm run cairn:manifest) and commit the result.');

package/dist/content/media-refs.d.ts

@@ -0,0 +1,7 @@
+import type { FrontmatterField } 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
+ *  non-media or malformed token is skipped, never thrown, so a stray `![](/x.png)` does not break
+ *  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[];

package/dist/content/media-refs.js

@@ -0,0 +1,52 @@
+// cairn-cms: the media-reference extractor. Given one entry's parsed frontmatter and body, it
+// returns the deduped content hashes the entry references. This is the main side of the media
+// where-used index: manifestEntryFromFile records the result per entry, and the usage-index
+// builder runs it directly over each open branch's edited markdown. It mirrors extractCairnLinks
+// (the same remark pipeline, the same first-occurrence dedup) but visits image nodes and the
+// frontmatter hero rather than link nodes.
+//
+// A media reference lives in two places, and both are load-bearing. Body image nodes carry the
+// inline `![](media:...)` placements (a 3a :::figure also lands here, since the figure directive
+// wraps a real image node). The frontmatter hero is the other site: a hero is `image: { src }` in
+// frontmatter, outside the markdown body, so an extractor that visited only body nodes would read
+// every in-use hero as orphaned and let safe-delete remove an in-use image.
+//
+// Every match is keyed by the parsed hash, the immutable truth, never the cosmetic slug, so a bare
+// `media:<hash>` and a `media:<slug>.<hash>` for the same bytes collapse to one.
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { visit } from 'unist-util-visit';
+import { parseMediaToken } from '../media/reference.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
+ *  non-media or malformed token is skipped, never thrown, so a stray `![](/x.png)` does not break
+ *  the manifest build. The body is parsed as mdast, so a `media:` token inside a code span or fence
+ *  is never matched. */
+export function extractMediaRefs(frontmatter, body, fields) {
+    const seen = new Set();
+    const hashes = [];
+    const add = (href) => {
+        const ref = parseMediaToken(href);
+        if (!ref || seen.has(ref.hash))
+            return;
+        seen.add(ref.hash);
+        hashes.push(ref.hash);
+    };
+    // The frontmatter hero arm: each `image`-typed field stores an ImageValue, so read its `.src`.
+    for (const field of fields) {
+        if (field.type !== 'image')
+            continue;
+        const value = frontmatter[field.name];
+        if (value && typeof value === 'object' && typeof value.src === 'string') {
+            add(value.src);
+        }
+    }
+    // The body arm: every image node's url. A 3a figure's inner image is a real image node.
+    const tree = unified().use(remarkParse).use(remarkGfm).parse(body);
+    visit(tree, 'image', (node) => {
+        if (node.url)
+            add(node.url);
+    });
+    return hashes;
+}

package/dist/content/schema.d.ts

@@ -1,4 +1,4 @@
-import type { FrontmatterField, ValidationResult } from './types.js';
+import type { FrontmatterField, ImageValue, ValidationResult } from './types.js';
 /** The validate input the cairn adapter takes: the raw frontmatter and the body. */
 export interface StandardInput {
     frontmatter: Record<string, unknown>;
@@ -27,10 +27,13 @@ type StandardResult<Output> = {
     }>;
 };
 /** Map one field descriptor to the TS type of its normalized value. text, textarea, and date
- *  normalize to a string; a closed-vocabulary `tags` field to the option-union array. */
+ *  normalize to a string; a closed-vocabulary `tags` field to the option-union array; an `image`
+ *  field to its nested object. */
 type FieldValue<K extends FrontmatterField> = K extends {
     type: 'boolean';
 } ? boolean : K extends {
+    type: 'image';
+} ? ImageValue : K extends {
     type: 'tags';
     options: readonly (infer O extends string)[];
 } ? O[] : K extends {

package/dist/content/schema.js

@@ -41,10 +41,27 @@ function compilePatterns(fields) {
     }
     return compiled;
 }
+// True when an image field feeds the social card: an explicit `seo: true`, or the back-compat
+// default that the field named `image` is the SEO image. The SEO unify (Task 4) reads this flag.
+function isSeoImage(field) {
+    return field.type === 'image' && (field.seo === true || (field.seo === undefined && field.name === 'image'));
+}
+// A concept declares at most one SEO image field, so the social card is unambiguous. More than one
+// is a site config error: a hero named `cover` plus an explicit `seo` on another, or two explicit
+// `seo` fields. Fail loudly at declaration rather than emit a silent or wrong og:image.
+function checkSeoImageFields(fields) {
+    const seo = fields.filter(isSeoImage);
+    if (seo.length > 1) {
+        const names = seo.map((field) => `"${field.name}"`).join(', ');
+        throw new Error(`cairn: a concept declares at most one SEO image field, but found ${seo.length} (${names}). ` +
+            'Set seo: false on all but one, or rename the extra image fields so only one feeds the social card.');
+    }
+}
 /** Declare a concept's fields once. Returns the schema's faces derived from that one declaration. */
 export function defineFields(fields, options = {}) {
     const list = [...fields];
     const patterns = compilePatterns(list);
+    checkSeoImageFields(list);
     const validate = (frontmatter, body) => {
         const base = validateFields(list, frontmatter);
         if (!base.ok)