@glw907/cairn-cms 0.57.1 → 0.58.0

package/dist/content/media-rewrite.js

@@ -0,0 +1,442 @@
+// cairn-cms: the replace-in-place rewrite transform. Given one entry's raw markdown and an old
+// content-hash, it rewrites every reference to that hash (a body image, a figure-wrapped image, or
+// the frontmatter hero image.src) to a new asset's canonical `media:` token, and returns a per
+// placement diff. This is the heart of the media-library "replace" action: the same bytes pointed
+// at a new asset, with the surrounding entry left exact.
+//
+// The output is byte-for-byte identical to the input except for the `media:` token substrings that
+// are replaced. The transform never round-trips through gray-matter or a markdown serializer (those
+// reformat YAML and are not byte stable); it splices strings by source offset. The match keys on the
+// parsed hash, the immutable truth, never the cosmetic slug, so a bare `media:<hash>` and a
+// `media:<slug>.<hash>` for the same bytes both repoint. A malformed or non-matching token is left
+// untouched.
+//
+// The body arm parses with the same figure-aware pipeline the render and Edit-block transforms use
+// (remark-parse + gfm + directive), so a `media:` token inside a code span or fence is not an image
+// node and is correctly never matched, matching extractMediaRefs. It also lets the arm classify an
+// image inside a `:::figure` as a 'figure' placement.
+import matter from 'gray-matter';
+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 { parseMediaToken } from '../media/reference.js';
+import { escapeLinkText } from './links.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
+ *  result, no matter how the locating arms behaved. A pure-insert span (`start === end`) overlaps
+ *  another span only when it sits strictly inside it, so adjacent inserts and edits are kept. */
+function dropOverlappingEdits(edits) {
+    const kept = [];
+    for (const e of edits) {
+        const clashes = kept.some((k) => e.start < k.end && k.start < e.end);
+        if (!clashes)
+            kept.push(e);
+    }
+    return kept;
+}
+/** A locating scan for candidate `media:` token substrings. Deliberately broad (it accepts
+ *  uppercase and other out-of-grammar characters) so a malformed token is still found and then
+ *  rejected by parseMediaToken, never silently skipped by the locator. The character class stops at
+ *  whitespace, a quote, or any YAML or markdown delimiter, so a frontmatter value or an image
+ *  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. */
+function parseFigureDoc(doc) {
+    return unified().use(remarkParse).use(remarkGfm).use(remarkDirective).parse(doc);
+}
+/** Whether `target` sits inside a `figure`-named container directive. Walks the tree to find the
+ *  ancestor, since unist-util-visit's per-call ancestors are not retained across the traversal.
+ *  Mirrors enclosingFigure in markdown-format.ts, reduced to a boolean. */
+function inFigure(tree, target) {
+    let found = false;
+    visit(tree, 'containerDirective', (dir) => {
+        if (dir.name !== 'figure')
+            return;
+        visit(dir, 'image', (img) => {
+            if (img === target)
+                found = true;
+        });
+    });
+    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
+ *  malformed token is found then rejected. Returns null for a flow-style value (no own `src:` line),
+ *  which leaves that shape unanchorable rather than splicing a guessed span. */
+function findSrcLineInRange(lines, fmBlock, range, hash) {
+    const srcKeyRe = /^(\s*)src:[ \t]?/;
+    for (let i = range[0]; i <= range[1]; i += 1) {
+        const lineText = fmBlock.slice(lines[i].start, lines[i].end);
+        const keyMatch = srcKeyRe.exec(lineText);
+        if (!keyMatch)
+            continue;
+        const valueStart = lines[i].start + keyMatch[0].length;
+        const valueText = fmBlock.slice(valueStart, lines[i].end);
+        for (const m of valueText.matchAll(MEDIA_TOKEN_SCAN)) {
+            const token = m[0];
+            const ref = parseMediaToken(token);
+            if (!ref || ref.hash !== hash)
+                continue;
+            const tokenStart = valueStart + m.index;
+            return {
+                lineStart: lines[i].start,
+                lineEnd: lines[i].end,
+                indent: keyMatch[1],
+                tokenStart,
+                tokenEnd: tokenStart + token.length,
+                token,
+            };
+        }
+    }
+    return null;
+}
+/** The image-like top-level frontmatter keys whose `src` parses to `hash`, in source order. A key is
+ *  image-like when its value is an object carrying a string `src`; this is the same shape
+ *  extractMediaRefs reads, so a token in a plain-text value (a `title:`/`note:`) is never treated as a
+ *  reference. The bucket-classifying data comes from gray-matter (which handles every quoting form);
+ *  the byte edit is located structurally by the caller, keyed back to this key name. */
+function imageFieldKeys(data, hash) {
+    const out = [];
+    for (const [key, value] of Object.entries(data)) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            continue;
+        const obj = value;
+        if (typeof obj.src !== 'string')
+            continue;
+        const ref = parseMediaToken(obj.src);
+        if (!ref || ref.hash !== hash)
+            continue;
+        out.push({ key, obj });
+    }
+    return out;
+}
+/** Collect hero src-token edits inside the frontmatter block. Only an image-field `src:` line is
+ *  rewritten: the structure is read via gray-matter (image-like keys), and each key's `src:` line is
+ *  located structurally within that key's block. A `media:` token sitting in a plain-text value (a
+ *  `title:` or `description:`) is on no `src:` line, so it is left untouched, keeping the byte-exact
+ *  contract and agreeing with extractMediaRefs. A flow-style hero has no `src:` line and is skipped. */
+function frontmatterEdits(markdown, fmBlock, oldHash) {
+    if (fmBlock === '')
+        return [];
+    const data = matter(markdown).data;
+    const lines = fmLines(fmBlock);
+    const edits = [];
+    for (const { key } of imageFieldKeys(data, oldHash)) {
+        const range = frontmatterKeyRange(lines, fmBlock, key);
+        if (!range)
+            continue;
+        const src = findSrcLineInRange(lines, fmBlock, range, oldHash);
+        if (!src)
+            continue;
+        edits.push({ start: src.tokenStart, end: src.tokenEnd, before: src.token, kind: 'hero' });
+    }
+    return edits;
+}
+/** Locate the exact `media:` token substring inside one image node's source span. The destination
+ *  begins at the `](` that follows the alt text, so the search starts there to avoid a false match on
+ *  a `media:`-like string inside the alt. Returns null when the token cannot be located, which leaves
+ *  the image untouched rather than splicing a guessed range. */
+function locateImageToken(span, url) {
+    const destStart = span.indexOf('](');
+    const from = destStart === -1 ? 0 : destStart + 2;
+    const at = span.indexOf(url, from);
+    if (at === -1)
+        return null;
+    return { start: at, end: at + url.length };
+}
+/** Find every body image whose url parses to `hash`, in source order, with absolute offsets. Parses
+ *  with the figure-aware pipeline, so a `media:` token inside a code span or fence is not an image
+ *  node and is correctly skipped, matching extractMediaRefs. */
+function matchedBodyImages(body, blockLength, hash) {
+    const tree = parseFigureDoc(body);
+    const hits = [];
+    visit(tree, 'image', (node) => {
+        const ref = parseMediaToken(node.url);
+        if (!ref || ref.hash !== hash)
+            return;
+        const from = node.position?.start?.offset;
+        const to = node.position?.end?.offset;
+        if (from == null || to == null)
+            return;
+        hits.push({
+            node,
+            nodeFrom: blockLength + from,
+            nodeTo: blockLength + to,
+            kind: inFigure(tree, node) ? 'figure' : 'body',
+        });
+    });
+    return hits;
+}
+/** Collect body edits over the body slice. Each matching image is located within its own source span
+ *  and recorded with an absolute offset. The kind is 'figure' when the image is inside a `:::figure`,
+ *  else 'body'. */
+function bodyEdits(body, blockLength, oldHash) {
+    const edits = [];
+    for (const hit of matchedBodyImages(body, blockLength, oldHash)) {
+        const span = body.slice(hit.nodeFrom - blockLength, hit.nodeTo - blockLength);
+        const loc = locateImageToken(span, hit.node.url);
+        if (!loc)
+            continue;
+        const start = hit.nodeFrom + loc.start;
+        const end = hit.nodeFrom + loc.end;
+        edits.push({ start, end, before: hit.node.url, kind: hit.kind });
+    }
+    return edits;
+}
+/**
+ * Rewrite every reference to `oldHash` in one entry's raw markdown to `newToken`, and return the
+ * rewritten markdown plus a per-placement diff. Only an image-field `src:` line is rewritten in the
+ * frontmatter: the image-like keys are read via gray-matter and each key's `src:` line is located
+ * structurally within its own block, so a `media:` token that merely appears in a plain-text value (a
+ * `title:` or `description:`) is left untouched, matching extractMediaRefs. Body and figure images are
+ * matched by mdast offset over the body slice. The output is byte-for-byte identical to the input
+ * apart from the replaced token substrings, so the rest of the entry (alt text, captions, the
+ * `:::figure` fences, every other frontmatter key) is preserved exactly. A non-matching hash returns
+ * the markdown unchanged with an empty placement list; a malformed `media:` reference is left
+ * untouched. Pure and node-safe.
+ */
+export function repointMediaRef(markdown, oldHash, newToken) {
+    const { fmBlock, body } = splitFrontmatter(markdown);
+    const heroEdits = frontmatterEdits(markdown, fmBlock, oldHash);
+    const bodyEditList = bodyEdits(body, fmBlock.length, oldHash);
+    const edits = dropOverlappingEdits([...heroEdits, ...bodyEditList]);
+    if (edits.length === 0)
+        return { markdown, placements: [] };
+    // placements read in document order (frontmatter first, then body in source order, which is the
+    // order each arm already emits). The diff lists each changed reference once.
+    const placements = edits.map((e) => ({
+        kind: e.kind,
+        before: e.before,
+        after: newToken,
+    }));
+    // Apply from last offset to first so each splice leaves the earlier offsets valid.
+    const byOffset = [...edits].sort((a, b) => b.start - a.start);
+    let out = markdown;
+    for (const e of byOffset) {
+        out = out.slice(0, e.start) + newToken + out.slice(e.end);
+    }
+    return { markdown: out, placements };
+}
+/** Classify an existing alt into its non-decorative bucket: an empty (or whitespace-only) alt is
+ *  filled, a non-empty alt is a custom alt the caller may opt in to overwrite. Mirrors the empty-alt
+ *  test findMediaImagesNeedingAlt uses. */
+function classifyAlt(existing) {
+    return existing.trim() === '' ? 'will-fill' : 'customized';
+}
+/** Whether a bucket plus the overwrite choice means the alt text is actually rewritten. A will-fill
+ *  always writes; a customized alt writes only on opt-in; a decorative hero never writes. */
+function altIsEdited(bucket, overwrite) {
+    if (bucket === 'will-fill')
+        return true;
+    if (bucket === 'customized')
+        return overwrite;
+    return false;
+}
+/** Collect the body and figure alt edits over the body slice. The alt source span sits between `![`
+ *  and the `](` inside the image node's span, so the new alt (escaped the way insertImage escapes it,
+ *  so a `]` cannot break the syntax) is spliced there. The existing alt is the parser's already
+ *  unescaped `node.alt`. A body image has no decorative slot, so an empty alt is always will-fill. */
+function bodyAltEdits(body, blockLength, hash, defaultAlt, overwrite) {
+    const edits = [];
+    for (const hit of matchedBodyImages(body, blockLength, hash)) {
+        const span = body.slice(hit.nodeFrom - blockLength, hit.nodeTo - blockLength);
+        if (!span.startsWith('!['))
+            continue;
+        // The alt source runs from `![` to the `](` that opens the destination. Find that closing `](`
+        // from the url's known position, not a forward scan: a forward `indexOf('](')` lands inside an
+        // alt that itself contains `](` or a nested `![x](y)` and would truncate the image on overwrite.
+        const loc = locateImageToken(span, hit.node.url);
+        if (!loc)
+            continue;
+        const close = span.lastIndexOf('](', loc.start);
+        if (close === -1)
+            continue;
+        const before = hit.node.alt ?? '';
+        const bucket = classifyAlt(before);
+        const write = altIsEdited(bucket, overwrite);
+        const after = write ? defaultAlt : before;
+        const placement = { kind: hit.kind, bucket, before, after };
+        if (!write) {
+            edits.push({ apply: false, start: hit.nodeFrom, end: hit.nodeFrom, text: '', placement });
+            continue;
+        }
+        // Replace the alt text between `![` and the destination `](`, writing it escaped so a `]` in the
+        // alt cannot truncate the image (mirrors insertImage).
+        const altStart = hit.nodeFrom - blockLength + 2;
+        const altEnd = hit.nodeFrom - blockLength + close;
+        edits.push({
+            apply: true,
+            start: blockLength + altStart,
+            end: blockLength + altEnd,
+            text: escapeLinkText(defaultAlt),
+            placement,
+        });
+    }
+    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
+ *  spans the whole mapping rather than a same-indent contiguous run: a blank line or a deeper-nested
+ *  child between `src:` and `alt:` no longer hides the existing key (which would otherwise insert a
+ *  duplicate key and break the YAML). Returns the key line's value span (after the key and its space,
+ *  to end of line) or null when the mapping has no such key at that indent. */
+function findSiblingKeyValue(lines, fmBlock, range, indent, key) {
+    const keyRe = new RegExp(`^${escapeForRegExp(indent)}${escapeForRegExp(key)}:[ \\t]?`);
+    for (let i = range[0]; i <= range[1]; i += 1) {
+        const lineText = fmBlock.slice(lines[i].start, lines[i].end);
+        const m = keyRe.exec(lineText);
+        if (m)
+            return { start: lines[i].start + m[0].length, end: lines[i].end };
+    }
+    return null;
+}
+/** Collect the hero alt edits inside the frontmatter block. The image-field objects (and their
+ *  decorative and alt values) are read via gray-matter to classify the bucket robustly across quoting
+ *  forms; the byte edit is then located structurally, scoped to each field's own mapping block, keyed
+ *  back by the top-level field name. Iterating the fields in source order keeps the hero placements in
+ *  document order. A decorative hero is reported and never edited; an empty alt is filled; a custom
+ *  alt is overwritten only on opt-in. An alt key that is present (anywhere in the mapping, even below a
+ *  blank line or a nested child) has its value replaced; an absent one is inserted right after the
+ *  `src:` line at the same indent. The new value is a JSON-quoted scalar, valid YAML that handles a
+ *  colon, a quote, or an empty string. A flow-style hero (`image: { ... }`, no own `src:` line) is
+ *  unanchorable, so it is reported from the gray-matter read but never spliced. */
+function heroAltEdits(markdown, fmBlock, hash, defaultAlt, overwrite) {
+    if (fmBlock === '')
+        return [];
+    const data = matter(markdown).data;
+    const lines = fmLines(fmBlock);
+    const edits = [];
+    const quoted = JSON.stringify(defaultAlt);
+    for (const { key, obj } of imageFieldKeys(data, hash)) {
+        const decorative = obj.decorative === true;
+        const before = typeof obj.alt === 'string' ? obj.alt : '';
+        const bucket = decorative ? 'decorative-skipped' : classifyAlt(before);
+        const write = altIsEdited(bucket, overwrite);
+        const after = write ? defaultAlt : before;
+        const placement = { kind: 'hero', bucket, before, after };
+        const range = write ? frontmatterKeyRange(lines, fmBlock, key) : null;
+        const src = range ? findSrcLineInRange(lines, fmBlock, range, hash) : null;
+        if (!write || !range || !src) {
+            // Reported but not edited: a kept custom alt, a decorative hero, or an unanchorable flow-style
+            // hero (no own `src:` line). It carries a diff entry but no splice, so the bytes stay exact.
+            edits.push({ apply: false, start: 0, end: 0, text: '', placement });
+            continue;
+        }
+        const altSpan = findSiblingKeyValue(lines, fmBlock, range, src.indent, 'alt');
+        if (altSpan) {
+            edits.push({ apply: true, start: altSpan.start, end: altSpan.end, text: quoted, placement });
+        }
+        else {
+            // No alt key: insert one on its own line right after the src line, at the sibling indent.
+            edits.push({
+                apply: true,
+                start: src.lineEnd,
+                end: src.lineEnd,
+                text: `\n${src.indent}alt: ${quoted}`,
+                placement,
+            });
+        }
+    }
+    return edits;
+}
+/**
+ * Set the alt at each placement of `hash` in one entry's raw markdown, and return the rewritten
+ * markdown plus a per-placement diff. An empty alt is filled with `defaultAlt` (bucket will-fill). A
+ * non-empty alt is overwritten with `defaultAlt` only when `opts.overwrite` is true (bucket
+ * customized; otherwise left unchanged but still reported, so the preview can show it and offer the
+ * opt-in). A frontmatter hero with `decorative: true` is bucket decorative-skipped and never changed.
+ * A body or figure image has no decorative slot, so its empty alt is always will-fill.
+ *
+ * The output is byte-for-byte identical to the input apart from the alt text it actually changes. The
+ * hero alt is edited inside the frontmatter block by string splice (no gray-matter serialize round
+ * trip, which would reformat the YAML); the structure read uses gray-matter only to classify buckets
+ * and read the hero alt and decorative flag. A body alt is written escaped (the way insertImage
+ * escapes it) so a `]` in the alt cannot break the image; a hero alt is written as a JSON-quoted YAML
+ * scalar so a colon, a quote, or an empty value is robust. Placements read in document order (hero
+ * first, then body in source order). A non-matching hash returns the markdown unchanged with an empty
+ * placement list. Pure and node-safe.
+ */
+export function fillAltForHash(markdown, hash, defaultAlt, opts) {
+    const { fmBlock, body } = splitFrontmatter(markdown);
+    const heroEditList = heroAltEdits(markdown, fmBlock, hash, defaultAlt, opts.overwrite);
+    const bodyEditList = bodyAltEdits(body, fmBlock.length, hash, defaultAlt, opts.overwrite);
+    const edits = [...heroEditList, ...bodyEditList];
+    if (edits.length === 0)
+        return { markdown, placements: [] };
+    const placements = edits.map((e) => e.placement);
+    // Apply only the edits that change bytes, from last offset to first so the earlier offsets stay
+    // valid. A reported-but-unchanged placement (a kept custom alt, a decorative hero) carries no span.
+    // The overlap guard runs in source order over the writes as a final safety net, so two splices can
+    // never target overlapping bytes and clobber each other into invalid output.
+    const writes = dropOverlappingEdits(edits.filter((e) => e.apply));
+    const byOffset = [...writes].sort((a, b) => b.start - a.start);
+    let out = markdown;
+    for (const e of byOffset) {
+        out = out.slice(0, e.start) + e.text + out.slice(e.end);
+    }
+    return { markdown: out, placements };
+}

package/dist/log/events.d.ts

@@ -1 +1 @@
-export type CairnLogEvent = 'auth.link.requested' | 'auth.link.send_failed' | 'auth.token.minted' | 'auth.token.confirmed' | 'auth.session.created' | 'auth.session.destroyed' | 'commit.succeeded' | 'commit.failed' | 'config.invalid' | 'entry.published' | 'entry.discarded' | 'publish.failed' | 'github.unreachable' | 'guard.rejected' | 'media.uploaded' | 'media.upload_failed' | 'media.delivery_failed' | 'media.orphan_reconcile' | 'media.resolve_missing' | 'media.deleted' | 'media.delete_blocked';
+export type CairnLogEvent = 'auth.link.requested' | 'auth.link.send_failed' | 'auth.token.minted' | 'auth.token.confirmed' | 'auth.session.created' | 'auth.session.destroyed' | 'commit.succeeded' | 'commit.failed' | 'config.invalid' | 'entry.published' | 'entry.discarded' | 'publish.failed' | 'github.unreachable' | 'guard.rejected' | 'media.uploaded' | 'media.upload_failed' | 'media.delivery_failed' | 'media.orphan_reconcile' | 'media.resolve_missing' | 'media.deleted' | 'media.delete_blocked' | 'media.replaced' | 'media.replace_blocked' | 'media.alt_propagated';

package/dist/media/rewrite-plan.d.ts

@@ -0,0 +1,65 @@
+import type { ConceptDescriptor } from '../content/types.js';
+import type { RepoRef } from '../github/types.js';
+import type { Manifest } from '../content/manifest.js';
+/** One main entry the rewrite will touch: its identity, its file path, the transform's per-placement
+ *  diff, and the rewritten markdown a later apply commits. `P` is the transform's placement type
+ *  (a RepointPlacement for replace, an AltPlacement for fill-alt). */
+export interface PlannedEntry<P = unknown> {
+    /** The concept id, e.g. "posts". */
+    concept: string;
+    /** The entry id (its filename stem). */
+    id: string;
+    /** The entry's repo path, `${concept.dir}/${filenameFromId(id)}`. */
+    path: string;
+    /** The transform's diff for this entry: one placement per rewritten reference. */
+    placements: P[];
+    /** The entry's markdown after the transform, byte-identical to the source apart from the rewrite. */
+    newMarkdown: string;
+}
+/** One open edit branch that also references the asset, with the entries on it. Report-only: an apply
+ *  rewrites main, never a branch, so the screen surfaces these as a delta the editor handles by
+ *  republishing the draft. */
+export interface BranchRef {
+    /** The cairn/* branch name. */
+    branch: string;
+    /** The entries on that branch that reference the asset. */
+    entries: {
+        concept: string;
+        id: string;
+    }[];
+}
+/** The preview plan: the main entries to rewrite, the report-only branch delta, and the distinct
+ *  count of affected main entries (the entries the transform actually changed). */
+export interface RewritePlan<P = unknown> {
+    entries: PlannedEntry<P>[];
+    branchDelta: BranchRef[];
+    affectedCount: number;
+}
+/**
+ * Plan a media rewrite for one asset hash. Builds the cross-branch usage index in strict mode (so an
+ * unverifiable branch read rejects, failing closed), then splits the rows for `args.hash` by origin:
+ *
+ * - Published rows are the main work. Each entry's file is read in parallel and run through
+ *   `args.transform`. An entry is included only when the transform reports at least one placement, so
+ *   a row whose body holds the token in a non-image position (a code span, raw HTML) drops out rather
+ *   than committing an unchanged file. A row whose concept is not configured, or whose file read
+ *   returns null (a stale manifest row), is skipped.
+ * - Branch rows are the report-only delta, grouped by branch in first-seen order. Branch rows are
+ *   never the published origin, so main never appears in the delta.
+ *
+ * `affectedCount` is the number of distinct entries in `entries` (the ones the transform changed). The
+ * planner does not read the media manifest: the transform closure already carries the new token or
+ * the default alt, so the planner needs only the entry markdown and the usage index. Pure of the
+ * editor surface and node-safe; the only IO is the usage index build and the per-entry reads.
+ */
+export declare function planMediaRewrite<P = unknown>(args: {
+    backend: RepoRef;
+    token: string;
+    concepts: ConceptDescriptor[];
+    contentManifest: Manifest;
+    hash: string;
+    transform: (markdown: string) => {
+        markdown: string;
+        placements: P[];
+    };
+}): Promise<RewritePlan<P>>;

package/dist/media/rewrite-plan.js

@@ -0,0 +1,61 @@
+import { findConcept } from '../content/concepts.js';
+import { filenameFromId } from '../content/ids.js';
+import { readRaw } from '../github/repo.js';
+import { buildUsageIndex } from './usage.js';
+/**
+ * Plan a media rewrite for one asset hash. Builds the cross-branch usage index in strict mode (so an
+ * unverifiable branch read rejects, failing closed), then splits the rows for `args.hash` by origin:
+ *
+ * - Published rows are the main work. Each entry's file is read in parallel and run through
+ *   `args.transform`. An entry is included only when the transform reports at least one placement, so
+ *   a row whose body holds the token in a non-image position (a code span, raw HTML) drops out rather
+ *   than committing an unchanged file. A row whose concept is not configured, or whose file read
+ *   returns null (a stale manifest row), is skipped.
+ * - Branch rows are the report-only delta, grouped by branch in first-seen order. Branch rows are
+ *   never the published origin, so main never appears in the delta.
+ *
+ * `affectedCount` is the number of distinct entries in `entries` (the ones the transform changed). The
+ * planner does not read the media manifest: the transform closure already carries the new token or
+ * the default alt, so the planner needs only the entry markdown and the usage index. Pure of the
+ * editor surface and node-safe; the only IO is the usage index build and the per-entry reads.
+ */
+export async function planMediaRewrite(args) {
+    // Strict so an unverifiable branch read rejects here rather than degrading to an absent reference.
+    // Do NOT wrap this: the throw is the fail-closed contract the apply relies on.
+    const index = await buildUsageIndex(args.backend, args.token, args.concepts, args.contentManifest, {
+        strict: true,
+    });
+    const rows = index.get(args.hash) ?? [];
+    // The main arm: read each referencing published entry in parallel (one round-trip latency floor,
+    // mirroring buildUsageIndex's per-branch batch), run the transform, and keep only the entries it
+    // changed. A null is a row whose concept is not configured or whose file is absent: it is skipped.
+    const published = rows.filter((row) => row.origin.kind === 'published');
+    const planned = await Promise.all(published.map(async (row) => {
+        const concept = findConcept(args.concepts, row.concept);
+        if (!concept)
+            return null;
+        const path = `${concept.dir}/${filenameFromId(row.id)}`;
+        const markdown = await readRaw(args.backend, path, args.token);
+        if (markdown === null)
+            return null;
+        const result = args.transform(markdown);
+        if (result.placements.length === 0)
+            return null;
+        return { concept: row.concept, id: row.id, path, placements: result.placements, newMarkdown: result.markdown };
+    }));
+    const entries = planned.filter((entry) => entry !== null);
+    // The branch arm: group the branch rows by branch in first-seen order, preserving the row order the
+    // index emits within each group. Branch rows are never the published origin, so main never appears.
+    const byBranch = new Map();
+    for (const row of rows) {
+        if (row.origin.kind !== 'branch')
+            continue;
+        const list = byBranch.get(row.origin.branch);
+        if (list)
+            list.push({ concept: row.concept, id: row.id });
+        else
+            byBranch.set(row.origin.branch, [{ concept: row.concept, id: row.id }]);
+    }
+    const branchDelta = [...byBranch].map(([branch, branchEntries]) => ({ branch, entries: branchEntries }));
+    return { entries, branchDelta, affectedCount: entries.length };
+}

package/dist/sveltekit/cairn-admin.d.ts

@@ -81,6 +81,11 @@ export declare function createCairnAdmin(runtime: CairnRuntime, deps?: CairnAdmi
         delete: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
         mediaDelete: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
         mediaUpdate: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaUpload: (event: AdminEvent) => Promise<import("./content-routes.js").UploadResult | import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaReplacePreview: (event: AdminEvent) => Promise<import("./content-routes.js").MediaReplacePreviewPlan | import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaReplace: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaAltPreview: (event: AdminEvent) => Promise<import("./content-routes.js").MediaAltPreviewPlan | import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaAltPropagate: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
         publishAll: (event: AdminEvent) => Promise<never>;
         addEditor: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<{
             error: string;

package/dist/sveltekit/cairn-admin.js

@@ -125,6 +125,15 @@ export function createCairnAdmin(runtime, deps = {}) {
             : content.listDeleteAction(contentEvent(event, { concept: view.concept.id }))),
         mediaDelete: viewAction(['media'], (event) => content.mediaDeleteAction(contentEvent(event, {}))),
         mediaUpdate: viewAction(['media'], (event) => content.mediaUpdateAction(contentEvent(event, {}))),
+        // The Library is not entry-scoped, so a replace uploads its new file through the same content-
+        // addressed ingest mounted media-scoped (uploadAction reads no concept/id), then previews and
+        // applies the repoint. Alt propagation previews and applies the alt fill. The preview pair are 2a
+        // fetch actions; the apply pair are form posts. All gate on the media view.
+        mediaUpload: viewAction(['media'], (event) => content.uploadAction(contentEvent(event, {}))),
+        mediaReplacePreview: viewAction(['media'], (event) => content.mediaReplacePreview(contentEvent(event, {}))),
+        mediaReplace: viewAction(['media'], (event) => content.mediaReplaceApply(contentEvent(event, {}))),
+        mediaAltPreview: viewAction(['media'], (event) => content.mediaAltPreview(contentEvent(event, {}))),
+        mediaAltPropagate: viewAction(['media'], (event) => content.mediaAltApply(contentEvent(event, {}))),
         publishAll: viewAction(authedViews, (event) => content.publishAllAction(contentEvent(event, {}))),
         addEditor: viewAction(['editors'], (event) => editors.addEditorAction(event)),
         removeEditor: viewAction(['editors'], (event) => editors.removeEditorAction(event)),