@glw907/cairn-cms 0.56.2 → 0.57.1

package/dist/components/editor-placeholder.d.ts

@@ -0,0 +1,26 @@
+import { EditorView } from '@codemirror/view';
+import { type Extension } from '@codemirror/state';
+/** The seam the host drives: begin lands a placeholder and returns its id; progress moves its bar;
+ *  resolveTo swaps it for the committed image text; cancel removes it leaving the source untouched.
+ *  Mirrors the register-callback idiom MarkdownEditor uses for its other editor ops. */
+export interface ImagePlaceholderApi {
+    /** Land an optimistic placeholder at the current caret from a local object URL; returns its id. */
+    begin(objectUrl: string): number;
+    /** Update a placeholder's determinate progress bar to the given 0..1 fraction. */
+    progress(id: number, fraction: number): void;
+    /** Swap the placeholder for the committed `![alt](media:ref)` text in one transaction. */
+    resolveTo(id: number, alt: string, ref: string): void;
+    /** Remove the placeholder, leaving the source exactly as it was (the failure/expiry path). */
+    cancel(id: number): void;
+}
+/**
+ * The placeholder extension: the StateField holding the active placeholders, their decorations, and
+ * the position-mapping across doc changes. The host adds it to the initial editor state, then builds
+ * the driving api with imagePlaceholderApi once the view exists.
+ */
+export declare function cairnImagePlaceholders(): Extension;
+/**
+ * Build the api that drives the placeholders against one editor view. The host registers it through
+ * registerImagePlaceholders; the insert popover calls begin, progress, resolveTo, and cancel.
+ */
+export declare function imagePlaceholderApi(view: EditorView): ImagePlaceholderApi;

package/dist/components/editor-placeholder.js

@@ -0,0 +1,166 @@
+// The optimistic image placeholder. While an upload runs, the editor shows the image the author is
+// placing right where the caret sits, with a determinate progress bar, so there is no dead wait. The
+// placeholder is a WIDGET decoration at a position, NEVER doc text: the source markdown is untouched
+// until the upload resolves, so a failed or session-expired upload leaves the source exactly as it
+// was (the 2b open-risk-2 acceptance bar). On resolve the placeholder is removed and the real
+// `![alt](media:slug.hash)` text is inserted in ONE transaction, so the surface never shows a frame
+// with neither the placeholder nor the committed text.
+//
+// Client-only like editor-highlight, editor-modes, editor-folding, and editor-media: MarkdownEditor
+// reaches this module through a dynamic import, so the static @codemirror imports here never enter a
+// server bundle (guarded by the editor-boundary test, whose DYNAMIC_ONLY list names this file).
+//
+// The architecture mirrors editor-folding: a StateField<DecorationSet> of active placeholders driven
+// by StateEffects (add, set-progress, remove). The field maps positions across doc changes
+// (deco.map(tr.changes)) and tracks each placeholder's mapped position, so concurrent typing never
+// strands a placeholder. The seam ops (begin, progress, resolveTo, cancel) dispatch the effects; the
+// resolve op dispatches the remove effect AND the real text insert in one transaction.
+import { Decoration, EditorView, WidgetType, } from '@codemirror/view';
+import { StateEffect, StateField } from '@codemirror/state';
+import { insertImage as insertImageFormat } from './markdown-format.js';
+// The effects that drive the placeholder field. add lands a placeholder at a position; set-progress
+// updates its bar; remove takes it out. resolveTo and cancel both end in a remove (resolveTo pairs
+// the remove with the text insert in its dispatch; cancel dispatches only the remove).
+const addPlaceholder = StateEffect.define();
+const setProgress = StateEffect.define();
+const removePlaceholder = StateEffect.define();
+// The widget: a small thumbnail from the local object URL plus a determinate progress bar, in the
+// editor's accent visual language (the same accent tint the media chip uses). The wrapper carries no
+// live region: the widget is recreated on every progress tick (CodeMirror replaces the decoration),
+// so a live region on it could not reliably announce a change. The bar is a real <progress> with an
+// accessible name, so assistive tech exposes it as a determinate progressbar with its current value.
+class PlaceholderWidget extends WidgetType {
+    data;
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+    eq(other) {
+        return (other instanceof PlaceholderWidget &&
+            other.data.id === this.data.id &&
+            other.data.url === this.data.url &&
+            other.data.fraction === this.data.fraction);
+    }
+    toDOM() {
+        const wrap = document.createElement('span');
+        wrap.className = 'cm-cairn-media-placeholder';
+        const img = document.createElement('img');
+        img.className = 'cm-cairn-media-placeholder-thumb';
+        img.src = this.data.url;
+        img.alt = '';
+        img.setAttribute('aria-hidden', 'true');
+        wrap.appendChild(img);
+        // A real <progress> with an accessible name: assistive tech reports it as a progressbar with its
+        // determinate value, the honest indicator. No live region on the wrapper, since the widget is
+        // recreated each tick and could not host one reliably.
+        const bar = document.createElement('progress');
+        bar.className = 'cm-cairn-media-placeholder-bar';
+        bar.setAttribute('aria-label', 'Image upload progress');
+        bar.max = 1;
+        bar.value = this.data.fraction;
+        wrap.appendChild(bar);
+        return wrap;
+    }
+    ignoreEvent() {
+        return false;
+    }
+}
+function buildSet(items) {
+    // Sort by position so the decoration set receives ascending ranges (RangeSet requires it).
+    const sorted = [...items.values()].sort((a, b) => a.pos - b.pos);
+    return Decoration.set(sorted.map((it) => Decoration.widget({ widget: new PlaceholderWidget(it.data), side: 1 }).range(it.pos)));
+}
+const placeholderField = StateField.define({
+    create() {
+        return { set: Decoration.none, items: new Map() };
+    },
+    update(value, tr) {
+        // Map every active placeholder's position across the change, so concurrent typing before a
+        // placeholder shifts it rather than stranding it.
+        let items = value.items;
+        let changed = false;
+        if (tr.docChanged) {
+            const next = new Map();
+            for (const [id, it] of items)
+                next.set(id, { data: it.data, pos: tr.changes.mapPos(it.pos, 1) });
+            items = next;
+            changed = true;
+        }
+        for (const e of tr.effects) {
+            if (e.is(addPlaceholder)) {
+                const next = new Map(items);
+                next.set(e.value.id, { data: { id: e.value.id, url: e.value.url, fraction: 0.1 }, pos: e.value.pos });
+                items = next;
+                changed = true;
+            }
+            else if (e.is(setProgress)) {
+                const it = items.get(e.value.id);
+                if (it) {
+                    const next = new Map(items);
+                    next.set(e.value.id, { data: { ...it.data, fraction: e.value.fraction }, pos: it.pos });
+                    items = next;
+                    changed = true;
+                }
+            }
+            else if (e.is(removePlaceholder)) {
+                if (items.has(e.value.id)) {
+                    const next = new Map(items);
+                    next.delete(e.value.id);
+                    items = next;
+                    changed = true;
+                }
+            }
+        }
+        if (!changed)
+            return value;
+        return { set: buildSet(items), items };
+    },
+    provide: (f) => EditorView.decorations.from(f, (v) => v.set),
+});
+// A module-level id counter. Browser app code, so a monotone counter is the simplest stable id; it
+// never crosses a process boundary, so collision is not a concern.
+let nextId = 1;
+/**
+ * The placeholder extension: the StateField holding the active placeholders, their decorations, and
+ * the position-mapping across doc changes. The host adds it to the initial editor state, then builds
+ * the driving api with imagePlaceholderApi once the view exists.
+ */
+export function cairnImagePlaceholders() {
+    return placeholderField;
+}
+/**
+ * Build the api that drives the placeholders against one editor view. The host registers it through
+ * registerImagePlaceholders; the insert popover calls begin, progress, resolveTo, and cancel.
+ */
+export function imagePlaceholderApi(view) {
+    const api = {
+        begin(objectUrl) {
+            const id = nextId++;
+            const pos = view.state.selection.main.head;
+            view.dispatch({ effects: addPlaceholder.of({ id, pos, url: objectUrl }) });
+            return id;
+        },
+        progress(id, fraction) {
+            view.dispatch({ effects: setProgress.of({ id, fraction }) });
+        },
+        resolveTo(id, alt, ref) {
+            const it = view.state.field(placeholderField).items.get(id);
+            if (!it)
+                return;
+            // Insert the committed text at the placeholder's mapped position, and remove the placeholder,
+            // in ONE transaction: the surface never shows a frame with neither the placeholder nor the
+            // text. insertImageFormat over an empty doc yields the bare `![alt](media:ref)` token, escaping
+            // a bracket in the alt the same way every other inline image insert does.
+            const token = insertImageFormat('', 0, 0, alt, ref).doc;
+            view.dispatch({
+                changes: { from: it.pos, insert: token },
+                effects: removePlaceholder.of({ id }),
+                selection: { anchor: it.pos + token.length },
+            });
+        },
+        cancel(id) {
+            view.dispatch({ effects: removePlaceholder.of({ id }) });
+        },
+    };
+    return api;
+}

package/dist/components/index.d.ts

@@ -4,6 +4,7 @@ export { default as LoginPage } from './LoginPage.svelte';
 export { default as ConfirmPage } from './ConfirmPage.svelte';
 export { default as CsrfField } from './CsrfField.svelte';
 export { default as ConceptList } from './ConceptList.svelte';
+export { default as CairnMediaLibrary } from './CairnMediaLibrary.svelte';
 export { default as EditPage } from './EditPage.svelte';
 export { default as ManageEditors } from './ManageEditors.svelte';
 export { default as MarkdownEditor } from './MarkdownEditor.svelte';

package/dist/components/index.js

@@ -6,6 +6,7 @@ export { default as LoginPage } from './LoginPage.svelte';
 export { default as ConfirmPage } from './ConfirmPage.svelte';
 export { default as CsrfField } from './CsrfField.svelte';
 export { default as ConceptList } from './ConceptList.svelte';
+export { default as CairnMediaLibrary } from './CairnMediaLibrary.svelte';
 export { default as EditPage } from './EditPage.svelte';
 export { default as ManageEditors } from './ManageEditors.svelte';
 export { default as MarkdownEditor } from './MarkdownEditor.svelte';

package/dist/components/markdown-directives.d.ts

@@ -56,6 +56,18 @@ export declare function caretContainerRange(scan: FenceScan, caretLine: number):
  * example can neither open nor close a range. This is the sole source of fold ranges.
  */
 export declare function containerRanges(scan: FenceScan): ContainerRange[];
+/** The figure placement role for a media token sitting on `lineIndex`, derived from the editor's
+ *  line scan without a remark parse (the chip rebuild runs on every doc and viewport change).
+ *
+ *  Returns the closed-set role (`center`/`wide`/`full`) when the innermost container holding the
+ *  line is a `:::figure` carrying exactly that one class, `'figure'` for a figure with no role (the
+ *  measure default), an out-of-set class, or more than one class, and null when the line sits in no
+ *  container or in a non-figure one. A bare media token earns no role pill (the no-hidden-state rule:
+ *  the visible decoration and the source agree, including the multi-class case remark-figure ignores).
+ *  Robust to a half-typed or unpaired fence, since {@link caretContainerRange} already disowns
+ *  fence-shaped lines inside code blocks and runs an unclosed container to the end.
+ */
+export declare function figureRoleAtLine(scan: FenceScan, lines: string[], lineIndex: number): 'center' | 'wide' | 'full' | 'figure' | null;
 /** One span of a fence line, in line-local offsets: machinery (`mark`) or meaning (`label`). */
 export interface FenceToken {
     from: number;

package/dist/components/markdown-directives.js

@@ -145,6 +145,48 @@ export function containerRanges(scan) {
     }
     return out;
 }
+/** The closed placement-role set for the reserved `figure` directive, mirroring remark-figure.ts.
+ *  A class outside this set is the measure default, never passed through as a role. */
+const FIGURE_ROLES = new Set(['center', 'wide', 'full']);
+// The directive `{attrs}` brace, and the `.class` shorthands inside it. mdast-util-directive folds
+// every `.class` into a space-joined node.attributes.class, and remark-figure honors a role only when
+// that whole value is exactly one closed-set name. The chip reads the opener line directly (the
+// editor has no mdast), so it collects all class shorthands and applies the same exactly-one rule, so
+// a multi-class brace reads as the measure default on the chip exactly as it renders.
+const ATTR_BRACE = /\{([^}]*)\}/;
+const CLASS_SHORTHAND = /\.([\w-]+)/g;
+const CLASS_ATTR = /class\s*=\s*"([^"]*)"/;
+/** The figure placement role for a media token sitting on `lineIndex`, derived from the editor's
+ *  line scan without a remark parse (the chip rebuild runs on every doc and viewport change).
+ *
+ *  Returns the closed-set role (`center`/`wide`/`full`) when the innermost container holding the
+ *  line is a `:::figure` carrying exactly that one class, `'figure'` for a figure with no role (the
+ *  measure default), an out-of-set class, or more than one class, and null when the line sits in no
+ *  container or in a non-figure one. A bare media token earns no role pill (the no-hidden-state rule:
+ *  the visible decoration and the source agree, including the multi-class case remark-figure ignores).
+ *  Robust to a half-typed or unpaired fence, since {@link caretContainerRange} already disowns
+ *  fence-shaped lines inside code blocks and runs an unclosed container to the end.
+ */
+export function figureRoleAtLine(scan, lines, lineIndex) {
+    const container = caretContainerRange(scan, lineIndex);
+    if (!container)
+        return null;
+    const opener = lines[container.fromLine] ?? '';
+    if (directiveOpenerName(opener) !== 'figure')
+        return null;
+    const brace = ATTR_BRACE.exec(opener)?.[1] ?? '';
+    // mdast folds both the `.class` shorthand and an explicit `class="a b"` into one class value, so
+    // collect from both to mirror what remark-figure reads off node.attributes.class.
+    const classes = [...brace.matchAll(CLASS_SHORTHAND)].map((m) => m[1]);
+    const explicit = CLASS_ATTR.exec(brace)?.[1];
+    if (explicit)
+        classes.push(...explicit.split(/\s+/).filter(Boolean));
+    // remark-figure keeps the role only when the whole class value is one closed-set name; a multi-class
+    // or out-of-set brace renders as the measure default, so the pill reads `figure` to match.
+    return classes.length === 1 && FIGURE_ROLES.has(classes[0])
+        ? classes[0]
+        : 'figure';
+}
 /**
  * Split a fence line into machinery and meaning. The colon run, the label's brackets, and the
  * whole {attrs} group are machinery; the directive name and the label text are meaning, the

package/dist/components/markdown-format.d.ts

@@ -12,6 +12,34 @@ export declare function applyMarkdownFormat(doc: string, from: number, to: numbe
  * blank lines, since a link is inline. Pure, so the editor dispatches the result.
  */
 export declare function insertInlineLink(doc: string, from: number, to: number, href: string, title: string): FormatResult;
+/**
+ * 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 declare function insertImage(doc: string, from: number, to: number, alt: string, ref: string): FormatResult;
+/** One media image whose alt is empty, located by its source offsets and parsed to its ref parts. */
+export interface MediaImageNeedingAlt {
+    from: number;
+    to: number;
+    ref: string;
+    slug: string;
+    hash: string;
+}
+/**
+ * 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 declare function findMediaImagesNeedingAlt(doc: string): MediaImageNeedingAlt[];
 /**
  * Unwrap every cairn: link whose href is exactly `href`, replacing it with its plain display text.
  * The save guard's one-click fix calls this to drop a broken link while keeping the words. The
@@ -22,3 +50,64 @@ export declare function insertInlineLink(doc: string, from: number, to: number,
  * is left in place.
  */
 export declare function unwrapCairnLink(doc: string, href: string): string;
+/** The closed placement role set the figure render step honors. A role outside it is the measure
+ *  default (null), so the control never writes one. Mirrors the set in render/remark-figure.ts. */
+export type FigureRole = 'center' | 'wide' | 'full';
+/**
+ * The media image at a caret, with the enclosing `:::figure` block when there is one. `imageFrom`
+ * and `imageTo` are the EXACT source offsets of the inner `![alt](media:slug.hash)` token, so a
+ * transform reuses the token byte-for-byte and never reserializes it (open risk 3). `figure` is null
+ * for a bare image (not in a figure); otherwise it carries the figure BLOCK's source offsets, the raw
+ * caption source the author wrote (inline markdown preserved, the directive-fence escape stripped),
+ * and the placement role (or null for the measure default).
+ */
+export interface FigureAtImage {
+    /** The start offset of the inner `![...](media:...)` token. */
+    imageFrom: number;
+    /** The end offset of the inner `![...](media:...)` token. */
+    imageTo: number;
+    /** The enclosing figure, or null when the image is bare. */
+    figure: {
+        /** The figure block's start offset (the `:::figure` opener). */
+        from: number;
+        /** The figure block's end offset (just past the closing `:::`). */
+        to: number;
+        /** The raw caption source, inline markdown preserved; empty when the figure has no caption. */
+        caption: string;
+        /** The placement role, or null for the measure default. */
+        role: FigureRole | null;
+    } | null;
+}
+/**
+ * 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 declare function figureAtImage(doc: string, pos: number): FigureAtImage | null;
+/**
+ * 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 declare function wrapImageInFigure(doc: string, imageFrom: number, imageTo: number, caption: string, role: FigureRole | null): FormatResult;
+/**
+ * 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 declare function updateFigure(doc: string, figureRange: {
+    from: number;
+    to: number;
+}, caption: string, role: FigureRole | null): FormatResult;
+/**
+ * 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 declare function unwrapFigure(doc: string, figureRange: {
+    from: number;
+    to: number;
+}): FormatResult;

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,
+    };
+}