@glw907/cairn-cms 0.56.1 → 0.57.0

package/src/lib/components/editor-placeholder.ts

@@ -0,0 +1,213 @@
+// 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,
+  type DecorationSet,
+} from '@codemirror/view';
+import { StateEffect, StateField, type Extension } from '@codemirror/state';
+import { insertImage as insertImageFormat } from './markdown-format.js';
+
+/** One active placeholder's data: its stable id, the object URL for the thumbnail, and the upload
+ *  progress as a 0..1 fraction. The widget reads this to render the thumbnail and the bar. */
+interface PlaceholderData {
+  id: number;
+  url: string;
+  fraction: number;
+}
+
+// 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<{ id: number; pos: number; url: string }>();
+const setProgress = StateEffect.define<{ id: number; fraction: number }>();
+const removePlaceholder = StateEffect.define<{ id: number }>();
+
+// 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 {
+  constructor(readonly data: PlaceholderData) {
+    super();
+  }
+
+  eq(other: WidgetType): boolean {
+    return (
+      other instanceof PlaceholderWidget &&
+      other.data.id === this.data.id &&
+      other.data.url === this.data.url &&
+      other.data.fraction === this.data.fraction
+    );
+  }
+
+  toDOM(): HTMLElement {
+    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(): boolean {
+    return false;
+  }
+}
+
+/** The active placeholders as a decoration set plus the per-id position map, so a resolve can find
+ *  the mapped position to insert at and the field can rebuild after a position shift. */
+interface PlaceholderState {
+  set: DecorationSet;
+  // Each active placeholder's current data and its mapped document position.
+  items: Map<number, { data: PlaceholderData; pos: number }>;
+}
+
+function buildSet(items: Map<number, { data: PlaceholderData; pos: number }>): DecorationSet {
+  // 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<PlaceholderState>({
+  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<number, { data: PlaceholderData; pos: number }>();
+      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),
+});
+
+/** 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;
+}
+
+// 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(): Extension {
+  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: EditorView): ImagePlaceholderApi {
+  const api: ImagePlaceholderApi = {
+    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/src/lib/components/index.ts

@@ -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/src/lib/components/markdown-directives.ts

@@ -17,6 +17,17 @@ const INLINE = /(?<![:\w]):[\w-]+\[[^\]]*\](\{[^}]*\})?/g;
 // never opens a real container.
 const CODE_FENCE = /^\s{0,3}(`{3,}|~{3,})/;
 
+/**
+ * The directive name from a container opener line (`:::callout{...}` -> `callout`,
+ * `::::cta[Book]` -> `cta`), or null when the line is not a named container opener. Reads the
+ * same FENCE match the scan uses: group 2 is the name, empty on a bare closer, so a closer or a
+ * non-fence line returns null.
+ */
+export function directiveOpenerName(line: string): string | null {
+  const m = FENCE.exec(line);
+  return m && m[2] ? m[2] : null;
+}
+
 /** Classify a whole line as a container fence, a leaf directive, or neither. */
 export function directiveLineKind(line: string): 'fence' | 'leaf' | null {
   if (FENCE.test(line)) return 'fence';
@@ -150,6 +161,52 @@ export function containerRanges(scan: FenceScan): ContainerRange[] {
   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: FenceScan,
+  lines: string[],
+  lineIndex: number,
+): 'center' | 'wide' | 'full' | 'figure' | null {
+  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] as 'center' | 'wide' | 'full')
+    : 'figure';
+}
+
 /** One span of a fence line, in line-local offsets: machinery (`mark`) or meaning (`label`). */
 export interface FenceToken {
   from: number;

package/src/lib/components/markdown-format.ts

@@ -6,9 +6,12 @@
 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 type { Link } from 'mdast';
+import type { Image, Link, Root, RootContent } from 'mdast';
+import type { ContainerDirective } from 'mdast-util-directive';
 import { escapeLinkText } from '../content/links.js';
+import { parseMediaToken } from '../media/reference.js';
 
 export type FormatKind =
   | 'bold'
@@ -163,6 +166,55 @@ export function insertInlineLink(doc: string, from: number, to: number, href: st
   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: string, from: number, to: number, alt: string, ref: string): FormatResult {
+  const inserted = `![${escapeLinkText(alt)}](${ref})`;
+  const end = from + inserted.length;
+  return { doc: doc.slice(0, from) + inserted + doc.slice(to), from: end, to: end };
+}
+
+/** 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 function findMediaImagesNeedingAlt(doc: string): MediaImageNeedingAlt[] {
+  const tree = unified().use(remarkParse).use(remarkGfm).parse(doc);
+  const hits: MediaImageNeedingAlt[] = [];
+  visit(tree, 'image', (node: Image) => {
+    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
@@ -197,3 +249,257 @@ export function unwrapCairnLink(doc: string, href: string): string {
   }
   return out;
 }
+
+/** 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';
+const FIGURE_ROLES = new Set<string>(['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;
+}
+
+/** 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: string): Root {
+  return unified().use(remarkParse).use(remarkGfm).use(remarkDirective).parse(doc) as Root;
+}
+
+/** 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: Root,
+  pos: number,
+): { image: Image; figure: ContainerDirective | null } | null {
+  let bareHit: { image: Image; figure: ContainerDirective | null } | null = null;
+  let figureHit: { image: Image; figure: ContainerDirective } | null = null;
+  // Track the figure ancestor while visiting; unist-util-visit hands the ancestors array last.
+  visit(tree, 'image', (node: Image, _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: Root, target: Image): ContainerDirective | null {
+  let found: ContainerDirective | null = null;
+  visit(tree, 'containerDirective', (dir: ContainerDirective) => {
+    if (dir.name !== 'figure') return;
+    let holds = false;
+    visit(dir, 'image', (img: Image) => {
+      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: string): string {
+  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: string): string {
+  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: string, figure: ContainerDirective, image: Image): string {
+  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: RootContent): boolean {
+  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: string, pos: number): FigureAtImage | null {
+  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 as FigureRole) : 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: string): string {
+  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: string, caption: string, role: FigureRole | null): string {
+  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: string,
+  imageFrom: number,
+  imageTo: number,
+  caption: string,
+  role: FigureRole | null,
+): FormatResult {
+  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: string, figureRange: { from: number; to: number }): string {
+  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: string,
+  figureRange: { from: number; to: number },
+  caption: string,
+  role: FigureRole | null,
+): FormatResult {
+  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: string, figureRange: { from: number; to: number }): FormatResult {
+  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,
+  };
+}