@glw907/cairn-cms 0.56.2 → 0.57.1

package/dist/components/MarkdownEditor.svelte

@@ -9,8 +9,10 @@ through the adapter's render. Swapping the editor stays a one-file change.
 -->
 <script lang="ts">
   import { onMount, onDestroy } from 'svelte';
-  import { applyMarkdownFormat, insertInlineLink, type FormatKind, type FormatResult } from './markdown-format.js';
+  import { applyMarkdownFormat, figureAtImage, insertImage as insertImageFormat, insertInlineLink, type FigureAtImage, type FormatKind, type FormatResult } from './markdown-format.js';
   import { fenceScan, caretContainerRange, directiveOpenerName } from './markdown-directives.js';
+  import { firstImageFile, guardDropTarget } from './client-ingest.js';
+  import type { MediaLibrary } from '../media/library-entry.js';
 
   /** The directive container at the caret: the opener's name, the block's markdown, and the
    *  document character offsets of its inclusive line range. */
@@ -30,6 +32,30 @@ through the adapter's render. Swapping the editor stays a one-file change.
     registerInsert?: (insert: (text: string) => void) => void;
     /** Receives a `(href, title) => void` that inserts an inline link; the link picker calls it. */
     registerInsertLink?: (insert: (href: string, title: string) => void) => void;
+    /** Receives an `(alt, ref) => void` that inserts an inline image at the caret; the media picker
+     *  and the capture card call it with the chosen alt and the full `media:slug.hash` reference. */
+    registerInsertImage?: (insert: (alt: string, ref: string) => void) => void;
+    /** Called with the first image File of a paste or drop onto the surface; the host opens the
+     *  capture card with the bytes. A paste or drop carrying no image falls through untouched. */
+    onImageIngest?: (file: File) => void;
+    /** The picker's human layer per stored asset, keyed by the 16-hex content hash (EditData's
+     *  `mediaLibrary`). The source decoration reads it to render a `media:` token as a thumbnail chip;
+     *  reactive, so a just-uploaded image decorates once it joins the library. Empty by default. */
+    mediaLibrary?: MediaLibrary;
+    /** Receives a `() => { left; right; top; bottom } | null` returning the caret's viewport
+     *  coordinates; the insert popover anchors itself to the cursor from this. Null before mount or
+     *  when the caret has no measurable position. */
+    registerCaretCoords?: (
+      get: () => { left: number; right: number; top: number; bottom: number } | null,
+    ) => void;
+    /** Receives a `() => void` that returns focus to the editor; the insert popover calls it on close
+     *  or Escape. The selection is preserved automatically, since opening the popover only blurs the
+     *  editor and never edits the doc. */
+    registerFocusEditor?: (focus: () => void) => void;
+    /** Receives the optimistic-placeholder api; the insert popover drives the upload loop through it
+     *  (begin lands a placeholder at the caret, progress moves its bar, resolveTo swaps it for the
+     *  committed image text, cancel removes it leaving the source untouched). */
+    registerImagePlaceholders?: (api: import('./editor-placeholder.js').ImagePlaceholderApi) => void;
     /** Receives a `() => string` returning the selected text; the web link dialog reads it. */
     registerGetSelection?: (get: () => string) => void;
     /** Receives a `(kind) => void` that transforms the current selection; the host's toolbar calls it. */
@@ -37,9 +63,17 @@ through the adapter's render. Swapping the editor stays a one-file change.
     /** Reports the directive container at the caret (or null when outside any container) whenever
      *  the reported value changes; the host resolves it against the registry to offer Edit-block. */
     onComponentAtCaret?: (info: ComponentAtCaret | null) => void;
+    /** Reports the media image at the caret (or null when the caret is not on one) whenever the
+     *  reported value changes; the host opens the figure control over it to wrap, edit, or unwrap a
+     *  `:::figure`. The figure transforms write source through registerReplaceRange. */
+    onMediaImageAtCaret?: (info: FigureAtImage | null) => void;
     /** Receives a `(from, to, text) => void` that overwrites a document span; the dialog's Update
      *  calls it to write an edited block back over its original range. */
     registerReplaceRange?: (replace: (from: number, to: number, text: string) => void) => void;
+    /** Receives a `(from, to) => void` that selects a document span, focuses the editor, and scrolls
+     *  the range into view; the needs-alt notice's jump control calls it to land the author on an
+     *  image that lacks alt text. */
+    registerSelectRange?: (select: (from: number, to: number) => void) => void;
     /** Generic CodeMirror completion sources wired into the editor; the link autocomplete is one. The
      *  type is referenced inline so no static `@codemirror/*` import sits in this client-only file. */
     completionSources?: import('@codemirror/autocomplete').CompletionSource[];
@@ -57,10 +91,18 @@ through the adapter's render. Swapping the editor stays a one-file change.
     name,
     registerInsert,
     registerInsertLink,
+    registerInsertImage,
+    onImageIngest,
+    mediaLibrary = {},
+    registerCaretCoords,
+    registerFocusEditor,
+    registerImagePlaceholders,
     registerGetSelection,
     registerFormat,
     onComponentAtCaret,
+    onMediaImageAtCaret,
     registerReplaceRange,
+    registerSelectRange,
     completionSources = [],
     focusMode = false,
     typewriter = false,
@@ -80,6 +122,11 @@ through the adapter's render. Swapping the editor stays a one-file change.
   let focusCompartment: import('@codemirror/state').Compartment | null = null;
   let typewriterCompartment: import('@codemirror/state').Compartment | null = null;
   let surfaceCompartment: import('@codemirror/state').Compartment | null = null;
+  // The media: source decoration lives in its own compartment, reconfigured when the mediaLibrary
+  // prop changes so a just-uploaded image decorates the moment it joins the library. The media
+  // module loads with the other dynamic editor modules in onMount.
+  let mediaCompartment: import('@codemirror/state').Compartment | null = null;
+  let mediaMod: typeof import('./editor-media.js') | null = null;
   // The posture themes, swapped through the surface compartment. Each owns its type step and
   // leading (the base theme deliberately sets neither on the content node, so the postures never
   // contest it on adoption order). Built in onMount beside the base theme.
@@ -96,6 +143,8 @@ through the adapter's render. Swapping the editor stays a one-file change.
     const highlightMod = await import('./editor-highlight.js');
     const modesMod = await import('./editor-modes.js');
     const foldingMod = await import('./editor-folding.js');
+    const placeholderMod = await import('./editor-placeholder.js');
+    mediaMod = await import('./editor-media.js');
 
     if (!host) return;
 
@@ -206,6 +255,120 @@ through the adapter's render. Swapping the editor stays a one-file change.
         },
         '.cm-cairn-directive-leaf': directiveInk,
         '.cm-cairn-directive-inline': directiveInk,
+        // The media: source chip: the inline widget that stands in for a media reference token, in the
+        // directive accent language (the 8% accent chip, the accent ink that holds AA on it). An
+        // inline-flex pill carrying a small thumbnail and the asset's display name, so a reference
+        // reads as the image it points at without leaving the source view.
+        '.cm-cairn-media-chip': {
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: '0.3em',
+          verticalAlign: 'baseline',
+          padding: '0.05em 0.4em 0.05em 0.25em',
+          borderRadius: '0.375rem',
+          backgroundColor: 'color-mix(in oklab, var(--color-accent) 8%, transparent)',
+          color: 'var(--color-accent)',
+          fontFamily: 'var(--font-body, ui-sans-serif, sans-serif)',
+          fontSize: '0.8125rem',
+          lineHeight: '1.4',
+        },
+        // The thumbnail: a small square crop, rounded to match the chip. object-fit keeps a
+        // non-square source from distorting. A faint border lifts a light image off the chip tint.
+        '.cm-cairn-media-thumb': {
+          width: '1.4em',
+          height: '1.4em',
+          objectFit: 'cover',
+          borderRadius: '0.25rem',
+          border: '1px solid color-mix(in oklab, var(--color-accent) 20%, transparent)',
+          flex: '0 0 auto',
+        },
+        '.cm-cairn-media-name': {
+          fontWeight: '500',
+          // Keep a long name from stretching the line; the title and the picker carry the full text.
+          maxWidth: '18ch',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+          whiteSpace: 'nowrap',
+        },
+        // The needs-alt marker: a glyph plus a label, never hue alone (the spec accessibility rule).
+        // It rides the warning tone so it reads as a caution, with the label spelling out the state.
+        // The text uses --cairn-warning-ink, the on-surface warning text token, not --color-warning
+        // (a fill tone that fails small-text contrast on the light chip tint, WCAG 1.4.3). The ink
+        // holds AA on the chip's tint on both themes and stands apart from the accent name.
+        '.cm-cairn-media-needs-alt': {
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: '0.2em',
+          color: 'var(--cairn-warning-ink, oklch(50% 0.13 70))',
+          fontSize: '0.6875rem',
+          fontWeight: '600',
+          textTransform: 'uppercase',
+          letterSpacing: '0.02em',
+        },
+        '.cm-cairn-media-needs-alt-glyph': { fontSize: '0.85em', lineHeight: '1' },
+        // The figure/role pill: a small bordered pill carrying the placement role (or "figure" for
+        // the measure default) when a media token sits inside a :::figure, in the directive accent
+        // language. The accent ink and a color-mix accent border on the base-100 surface read as a
+        // quiet tag beside the name. The ink is theme-defined, so it holds contrast in both themes
+        // (Task 8's polish confirms it visually). A bare token renders no pill at all.
+        '.cm-cairn-media-role': {
+          fontFamily: 'var(--font-body, ui-sans-serif, sans-serif)',
+          fontSize: '0.625rem',
+          fontWeight: '600',
+          letterSpacing: '0.01em',
+          color: 'var(--color-accent)',
+          backgroundColor: 'var(--color-base-100)',
+          border: '1px solid color-mix(in oklab, var(--color-accent) 35%, transparent)',
+          borderRadius: '0.3rem',
+          padding: '0.04rem 0.34rem',
+          flex: '0 0 auto',
+        },
+        // The optimistic upload placeholder: an inline pill in the accent language, carrying a small
+        // thumbnail of the image the author is placing and a determinate progress bar beneath it. It
+        // stands in for the committed image text only while the upload runs; on resolve the seam
+        // swaps it for the real reference, and on failure the seam removes it (the source untouched).
+        // The accent tint matches the media chip so the two read as one visual family.
+        '.cm-cairn-media-placeholder': {
+          display: 'inline-flex',
+          flexDirection: 'column',
+          gap: '0.2em',
+          verticalAlign: 'baseline',
+          padding: '0.2em 0.35em',
+          borderRadius: '0.375rem',
+          backgroundColor: 'color-mix(in oklab, var(--color-accent) 8%, transparent)',
+          border: '1px solid color-mix(in oklab, var(--color-accent) 20%, transparent)',
+        },
+        '.cm-cairn-media-placeholder-thumb': {
+          width: '2.4em',
+          height: '2.4em',
+          objectFit: 'cover',
+          borderRadius: '0.25rem',
+          // A gentle pulse marks the placeholder as in-flight; reduced-motion drops it below.
+          opacity: '0.85',
+        },
+        // The determinate bar: native <progress> restyled to the accent ink so the fill reads as the
+        // upload's progress. Sized to the thumbnail width so the pill stays compact.
+        '.cm-cairn-media-placeholder-bar': {
+          width: '2.4em',
+          height: '0.3em',
+          appearance: 'none',
+          border: '0',
+          borderRadius: '0.15em',
+          backgroundColor: 'color-mix(in oklab, var(--color-accent) 18%, transparent)',
+          overflow: 'hidden',
+        },
+        '.cm-cairn-media-placeholder-bar::-webkit-progress-bar': {
+          backgroundColor: 'transparent',
+        },
+        '.cm-cairn-media-placeholder-bar::-webkit-progress-value': {
+          backgroundColor: 'var(--color-accent)',
+          borderRadius: '0.15em',
+          transition: 'width 200ms ease',
+        },
+        '.cm-cairn-media-placeholder-bar::-moz-progress-bar': {
+          backgroundColor: 'var(--color-accent)',
+          borderRadius: '0.15em',
+        },
         // Container folding lives in a real gutter column now, not an in-text band. The gutter is a
         // fixed-x column left of the content; the chevron is empty at rest and reveals on hovering
         // the gutter cell (the VS Code / Zed / Obsidian standard), forced on when folded or when the
@@ -266,6 +429,7 @@ through the adapter's render. Swapping the editor stays a one-file change.
         '@media (prefers-reduced-motion: reduce)': {
           '.cm-cairn-fold-btn svg': { transition: 'none' },
           '.cm-cairn-fold-flash': { transition: 'none' },
+          '.cm-cairn-media-placeholder-bar::-webkit-progress-value': { transition: 'none' },
         },
         // The folded-row wash: a soft accent tint, square and full-row, returning as a STATE signal
         // so folded spots read in a scan. The rails are inset box-shadows on the same line element
@@ -352,6 +516,7 @@ through the adapter's render. Swapping the editor stays a one-file change.
     focusCompartment = new stateMod.Compartment();
     typewriterCompartment = new stateMod.Compartment();
     surfaceCompartment = new stateMod.Compartment();
+    mediaCompartment = new stateMod.Compartment();
 
     view = new EditorView({
       parent: host,
@@ -378,6 +543,44 @@ through the adapter's render. Swapping the editor stays a one-file change.
           // invariant. Placed after the directive plugin so its chevron widget on an opener row
           // composes with the row's rail and gutter; its keymap is internal to the extension.
           foldingMod.cairnFolding(),
+          // The optimistic image placeholder field: a widget-only decoration the insert popover
+          // drives through the registerImagePlaceholders api. It never writes doc text, so a failed
+          // upload leaves the source untouched (open risk 2). Placed after folding so a placeholder
+          // landing inside a directive composes with the rails.
+          placeholderMod.cairnImagePlaceholders(),
+          // The media: source decoration, in its own compartment so a mediaLibrary prop change
+          // reconfigures it without rebuilding the editor. The chip and the atomic ranges read the
+          // library; an empty library decorates nothing.
+          mediaCompartment.of(mediaMod.cairnMediaDecorations(mediaLibrary)),
+          // Paste and drop ingest: an image carried by either gesture is preventDefault'd and handed
+          // to onImageIngest (the host opens the capture card with the bytes); a gesture carrying no
+          // image falls through to CodeMirror's default. 2b is single-file per gesture (open risk 3),
+          // so only the first image routes.
+          EditorView.domEventHandlers({
+            dragover(event) {
+              // Allow the drop only when the drag carries image files; otherwise let it pass so a
+              // non-image drag (text, a link) keeps its native behavior.
+              if (event.dataTransfer && firstImageFile(event.dataTransfer)) {
+                guardDropTarget(event);
+                return true;
+              }
+              return false;
+            },
+            drop(event) {
+              const file = event.dataTransfer ? firstImageFile(event.dataTransfer) : null;
+              if (!file) return false;
+              guardDropTarget(event);
+              onImageIngest?.(file);
+              return true;
+            },
+            paste(event) {
+              const file = event.clipboardData ? firstImageFile(event.clipboardData) : null;
+              if (!file) return false; // a text or markdown paste falls through untouched
+              event.preventDefault();
+              onImageIngest?.(file);
+              return true;
+            },
+          }),
           EditorView.contentAttributes.of({ spellcheck: 'true', autocorrect: 'on', autocapitalize: 'sentences' }),
           theme,
           surfaceCompartment.of(surface === 'prose' ? proseTheme : markupTheme),
@@ -387,6 +590,10 @@ through the adapter's render. Swapping the editor stays a one-file change.
             // caret sits in, so the reporter runs on either; the dedupe below absorbs the no-ops.
             if (onComponentAtCaret && (update.docChanged || update.selectionSet))
               reportComponentAtCaret(update.state);
+            // The media-image reporter rides the same two triggers: a caret move lands on or off an
+            // image, an edit shifts the figure's span. The dedupe absorbs the keystroke no-ops.
+            if (onMediaImageAtCaret && (update.docChanged || update.selectionSet))
+              reportMediaImageAtCaret(update.state);
           }),
         ],
       }),
@@ -394,12 +601,18 @@ through the adapter's render. Swapping the editor stays a one-file change.
 
     registerInsert?.(insertAtCursor);
     registerInsertLink?.(insertLink);
+    registerInsertImage?.(insertImage);
+    registerCaretCoords?.(caretCoords);
+    registerFocusEditor?.(focusEditor);
+    registerImagePlaceholders?.(placeholderMod.imagePlaceholderApi(view));
     registerGetSelection?.(selectedText);
     registerFormat?.(applyFormat);
     registerReplaceRange?.(replaceRange);
+    registerSelectRange?.(selectRange);
     // Report the caret's starting container once the editor exists, so a caret that mounts inside
     // a block is known without waiting for the first move.
     if (onComponentAtCaret) reportComponentAtCaret(view.state);
+    if (onMediaImageAtCaret) reportMediaImageAtCaret(view.state);
     mounted = true;
   });
 
@@ -432,6 +645,15 @@ through the adapter's render. Swapping the editor stays a one-file change.
     });
   });
 
+  // Reconfigure the media decoration when the mediaLibrary prop changes, so a just-uploaded image
+  // (added to the library by the host) decorates without rebuilding the editor. Reading the prop
+  // tracks it; the guard waits for the mounted editor and its media module.
+  $effect(() => {
+    const library = mediaLibrary;
+    if (!mounted || !view || !mediaMod || !mediaCompartment) return;
+    view.dispatch({ effects: mediaCompartment.reconfigure(mediaMod.cairnMediaDecorations(library)) });
+  });
+
   // The last value handed to onComponentAtCaret, so the reporter fires only on a change. The
   // identity compared is name + markdown + from + to. A pure caret move within one block leaves all
   // four unchanged, so it does not refire; an edit inside the block changes the markdown even when
@@ -473,6 +695,32 @@ through the adapter's render. Swapping the editor stays a one-file change.
     onComponentAtCaret?.(next);
   }
 
+  // The last media-image report, so the reporter fires only on a change. The compared identity is
+  // the image span plus the figure's range/caption/role; a pure caret move within one image (or one
+  // figure) leaves them unchanged, so it does not refire, while an edit that shifts the figure span
+  // or rewrites the caption does. A null transitions to or from null on entering/leaving an image.
+  let lastMediaReport: FigureAtImage | null = null;
+
+  // Compute the media image at the caret from a CodeMirror state and report it through
+  // onMediaImageAtCaret, deduped so a caret move that stays on the same image does not refire.
+  function reportMediaImageAtCaret(state: import('@codemirror/state').EditorState) {
+    const next = figureAtImage(state.doc.toString(), state.selection.main.head);
+    const prev = lastMediaReport;
+    const same =
+      prev === next ||
+      (prev !== null &&
+        next !== null &&
+        prev.imageFrom === next.imageFrom &&
+        prev.imageTo === next.imageTo &&
+        (prev.figure?.from ?? null) === (next.figure?.from ?? null) &&
+        (prev.figure?.to ?? null) === (next.figure?.to ?? null) &&
+        (prev.figure?.caption ?? null) === (next.figure?.caption ?? null) &&
+        (prev.figure?.role ?? null) === (next.figure?.role ?? null));
+    if (same) return;
+    lastMediaReport = next;
+    onMediaImageAtCaret?.(next);
+  }
+
   // Overwrite a document span with new text and drop the caret after it, mirroring insertAtCursor's
   // dispatch shape. A no-op before the editor mounts, the same guard the other seams carry.
   function replaceRange(from: number, to: number, text: string) {
@@ -481,6 +729,15 @@ through the adapter's render. Swapping the editor stays a one-file change.
     view.focus();
   }
 
+  // Select a document span, focus the surface, and scroll the range into view. The needs-alt notice's
+  // jump control calls it to land the author on an image that lacks alt text. A no-op before the
+  // editor mounts, the same guard the other seams carry.
+  function selectRange(from: number, to: number) {
+    if (!view) return;
+    view.dispatch({ selection: { anchor: from, head: to }, scrollIntoView: true });
+    view.focus();
+  }
+
   function insertAtCursor(text: string) {
     if (!view) {
       value = value ? `${value}\n\n${text}` : text;
@@ -518,12 +775,37 @@ through the adapter's render. Swapping the editor stays a one-file change.
     transformSelection((doc, from, to) => insertInlineLink(doc, from, to, href, title));
   }
 
+  function insertImage(alt: string, ref: string) {
+    if (!view) {
+      // The editor has not mounted yet; append the image to the raw value so a pick is never lost,
+      // mirroring insertLink's pre-mount fallback.
+      const image = insertImageFormat('', 0, 0, alt, ref).doc;
+      value = value ? `${value} ${image}` : image;
+      return;
+    }
+    transformSelection((doc, from, to) => insertImageFormat(doc, from, to, alt, ref));
+  }
+
   function selectedText(): string {
     if (!view) return '';
     const { from, to } = view.state.selection.main;
     return view.state.sliceDoc(from, to);
   }
 
+  // The caret's viewport coordinates, for the insert popover to anchor itself to the cursor. Null
+  // before the editor mounts or when the caret has no measurable position (an unrendered line).
+  function caretCoords(): { left: number; right: number; top: number; bottom: number } | null {
+    if (!view) return null;
+    const rect = view.coordsAtPos(view.state.selection.main.head);
+    return rect ? { left: rect.left, right: rect.right, top: rect.top, bottom: rect.bottom } : null;
+  }
+
+  // Return focus to the editor surface; the popover calls it on close or Escape. The selection is
+  // intact because opening the popover only blurred the editor, it never edited the doc.
+  function focusEditor() {
+    view?.focus();
+  }
+
   function applyFormat(kind: FormatKind) {
     transformSelection((doc, from, to) => applyMarkdownFormat(doc, from, to, kind));
   }

package/dist/components/MarkdownEditor.svelte.d.ts

@@ -1,4 +1,5 @@
-import { type FormatKind } from './markdown-format.js';
+import { type FigureAtImage, type FormatKind } from './markdown-format.js';
+import type { MediaLibrary } from '../media/library-entry.js';
 /** The directive container at the caret: the opener's name, the block's markdown, and the
  *  document character offsets of its inclusive line range. */
 interface ComponentAtCaret {
@@ -16,6 +17,33 @@ interface Props {
     registerInsert?: (insert: (text: string) => void) => void;
     /** Receives a `(href, title) => void` that inserts an inline link; the link picker calls it. */
     registerInsertLink?: (insert: (href: string, title: string) => void) => void;
+    /** Receives an `(alt, ref) => void` that inserts an inline image at the caret; the media picker
+     *  and the capture card call it with the chosen alt and the full `media:slug.hash` reference. */
+    registerInsertImage?: (insert: (alt: string, ref: string) => void) => void;
+    /** Called with the first image File of a paste or drop onto the surface; the host opens the
+     *  capture card with the bytes. A paste or drop carrying no image falls through untouched. */
+    onImageIngest?: (file: File) => void;
+    /** The picker's human layer per stored asset, keyed by the 16-hex content hash (EditData's
+     *  `mediaLibrary`). The source decoration reads it to render a `media:` token as a thumbnail chip;
+     *  reactive, so a just-uploaded image decorates once it joins the library. Empty by default. */
+    mediaLibrary?: MediaLibrary;
+    /** Receives a `() => { left; right; top; bottom } | null` returning the caret's viewport
+     *  coordinates; the insert popover anchors itself to the cursor from this. Null before mount or
+     *  when the caret has no measurable position. */
+    registerCaretCoords?: (get: () => {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    } | null) => void;
+    /** Receives a `() => void` that returns focus to the editor; the insert popover calls it on close
+     *  or Escape. The selection is preserved automatically, since opening the popover only blurs the
+     *  editor and never edits the doc. */
+    registerFocusEditor?: (focus: () => void) => void;
+    /** Receives the optimistic-placeholder api; the insert popover drives the upload loop through it
+     *  (begin lands a placeholder at the caret, progress moves its bar, resolveTo swaps it for the
+     *  committed image text, cancel removes it leaving the source untouched). */
+    registerImagePlaceholders?: (api: import('./editor-placeholder.js').ImagePlaceholderApi) => void;
     /** Receives a `() => string` returning the selected text; the web link dialog reads it. */
     registerGetSelection?: (get: () => string) => void;
     /** Receives a `(kind) => void` that transforms the current selection; the host's toolbar calls it. */
@@ -23,9 +51,17 @@ interface Props {
     /** Reports the directive container at the caret (or null when outside any container) whenever
      *  the reported value changes; the host resolves it against the registry to offer Edit-block. */
     onComponentAtCaret?: (info: ComponentAtCaret | null) => void;
+    /** Reports the media image at the caret (or null when the caret is not on one) whenever the
+     *  reported value changes; the host opens the figure control over it to wrap, edit, or unwrap a
+     *  `:::figure`. The figure transforms write source through registerReplaceRange. */
+    onMediaImageAtCaret?: (info: FigureAtImage | null) => void;
     /** Receives a `(from, to, text) => void` that overwrites a document span; the dialog's Update
      *  calls it to write an edited block back over its original range. */
     registerReplaceRange?: (replace: (from: number, to: number, text: string) => void) => void;
+    /** Receives a `(from, to) => void` that selects a document span, focuses the editor, and scrolls
+     *  the range into view; the needs-alt notice's jump control calls it to land the author on an
+     *  image that lacks alt text. */
+    registerSelectRange?: (select: (from: number, to: number) => void) => void;
     /** Generic CodeMirror completion sources wired into the editor; the link autocomplete is one. The
      *  type is referenced inline so no static `@codemirror/*` import sits in this client-only file. */
     completionSources?: import('@codemirror/autocomplete').CompletionSource[];

package/dist/components/MediaCaptureCard.svelte

@@ -0,0 +1,135 @@
+<!--
+@component
+The one-step capture card for a media insert. Shown when an author already has bytes in hand (a
+paste, a drop, or a chosen file), it captures three things and emits them to its host: the file, an
+editable display name, and the alt text. It is a presentational form card, not a dialog of its own;
+Task 6's insert popover hosts it.
+
+The display name pre-fills from proposedNameFor(file.name): a real specific stem (blue-shoes.png)
+arrives as a Suggested value, while a generic camera stem (IMG_4821.jpg) leaves the field empty and
+required with no tag, so the author never accepts machine noise.
+
+Alt is a real role="radiogroup" of two radios: write a description, or mark decorative. The
+requirement is surfaced through aria-describedby, never by disabling the submit. Insert is never
+disabled (the locked no-skipped-disabled-reason rule); an author may proceed with alt unset and the
+emitted record carries an empty alt, which the host treats as needs-alt debt. A decorative choice
+also resolves alt to the empty string. The committed reference keys off an empty alt as the
+needs-alt signal, so the emitted record uses an empty alt string for both the decorative and the
+left-blank cases, and a separate decorative flag distinguishes them for the host.
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { proposedNameFor } from './client-ingest.js';
+
+  /** The record the card emits to its host on insert. */
+  interface CaptureRecord {
+    /** The image bytes the author is placing. */
+    file: File;
+    /** The editable display name, the proposed stem or the author's edit. */
+    displayName: string;
+    /** The alt text. Empty for a decorative image or for an author who proceeded without alt; the
+     *  host commits an empty alt as the needs-alt signal in the `![](media:...)` reference. */
+    alt: string;
+    /** True when the author marked the image decorative, distinguishing a deliberate empty alt from
+     *  a left-blank one. The committed alt is empty either way. */
+    decorative: boolean;
+  }
+
+  interface Props {
+    /** The image to capture; the card previews it from a local object URL. */
+    file: File;
+    /** Emit the captured record to the host on insert. */
+    oncapture: (record: CaptureRecord) => void;
+  }
+
+  let { file, oncapture }: Props = $props();
+
+  // The proposed display name for this file, computed once. A real stem pre-fills the field and shows
+  // the Suggested tag; a generic stem yields null, leaving the field empty, required, and untagged.
+  const proposed = $derived(proposedNameFor(file.name));
+  // Seeded once from the file the card opened with; untrack marks it a deliberate one-time read, not
+  // a reactive miss. The card lives for one file, so a later file swap is out of scope.
+  let displayName = $state(untrack(() => proposedNameFor(file.name) ?? ''));
+
+  // The alt mode: unset until the author picks one, then 'describe' or 'decorative'. Unset emits an
+  // empty alt (needs-alt debt); insert never blocks on it.
+  let altMode = $state<'describe' | 'decorative' | null>(null);
+  let altText = $state('');
+
+  // A local object URL for the preview. Allocation and revoke live in ONE $effect keyed on the file,
+  // never in a $derived: a derivation that calls createObjectURL allocates a resource as a side
+  // effect, which can desync from the revoke (a re-derive leaks the prior URL). The matched effect
+  // revokes on teardown and on any file change, so the blob never leaks.
+  let previewUrl = $state('');
+  $effect(() => {
+    const url = URL.createObjectURL(file);
+    previewUrl = url;
+    return () => URL.revokeObjectURL(url);
+  });
+
+  function submit(e: SubmitEvent) {
+    e.preventDefault();
+    // Decorative and write-but-blank both commit an empty alt; the decorative flag distinguishes
+    // them for the host. A described image carries the trimmed alt text.
+    const alt = altMode === 'describe' ? altText.trim() : '';
+    oncapture({ file, displayName: displayName.trim(), alt, decorative: altMode === 'decorative' });
+  }
+</script>
+
+<form class="flex flex-col gap-4" onsubmit={submit}>
+  <div class="flex items-start gap-3">
+    <img
+      src={previewUrl}
+      alt=""
+      class="h-16 w-16 flex-none rounded-box border border-[var(--cairn-card-border)] object-cover"
+    />
+    <label class="flex flex-1 flex-col gap-1">
+      <span class="flex items-center gap-2 text-sm font-medium">
+        Name
+        {#if proposed !== null}
+          <span class="badge badge-ghost badge-sm">Suggested</span>
+        {/if}
+      </span>
+      <input
+        class="input w-full"
+        aria-required={proposed === null ? 'true' : undefined}
+        placeholder="What is this image?"
+        bind:value={displayName}
+      />
+    </label>
+  </div>
+
+  <fieldset
+    class="flex flex-col gap-2"
+    role="radiogroup"
+    aria-label="Alt text"
+    aria-required="true"
+    aria-describedby="cairn-capture-alt-note"
+  >
+    <legend class="text-sm font-medium">Alt text</legend>
+    <p id="cairn-capture-alt-note" class="text-xs text-[var(--color-muted)]">
+      Describe the image for screen readers, or mark it decorative. You can insert without alt text
+      and add it later.
+    </p>
+    <label class="flex cursor-pointer items-center gap-2">
+      <input type="radio" class="radio radio-sm" name="cairn-capture-alt" value="describe" bind:group={altMode} />
+      <span class="text-sm">Write a description</span>
+    </label>
+    {#if altMode === 'describe'}
+      <input
+        class="input input-sm ml-6 w-[calc(100%-1.5rem)]"
+        aria-label="Alt text description"
+        placeholder="A short description"
+        bind:value={altText}
+      />
+    {/if}
+    <label class="flex cursor-pointer items-center gap-2">
+      <input type="radio" class="radio radio-sm" name="cairn-capture-alt" value="decorative" bind:group={altMode} />
+      <span class="text-sm">Mark as decorative</span>
+    </label>
+  </fieldset>
+
+  <div class="flex justify-end">
+    <button type="submit" class="btn btn-sm btn-primary">Insert image</button>
+  </div>
+</form>

package/dist/components/MediaCaptureCard.svelte.d.ts

@@ -0,0 +1,40 @@
+/** The record the card emits to its host on insert. */
+interface CaptureRecord {
+    /** The image bytes the author is placing. */
+    file: File;
+    /** The editable display name, the proposed stem or the author's edit. */
+    displayName: string;
+    /** The alt text. Empty for a decorative image or for an author who proceeded without alt; the
+     *  host commits an empty alt as the needs-alt signal in the `![](media:...)` reference. */
+    alt: string;
+    /** True when the author marked the image decorative, distinguishing a deliberate empty alt from
+     *  a left-blank one. The committed alt is empty either way. */
+    decorative: boolean;
+}
+interface Props {
+    /** The image to capture; the card previews it from a local object URL. */
+    file: File;
+    /** Emit the captured record to the host on insert. */
+    oncapture: (record: CaptureRecord) => void;
+}
+/**
+ * The one-step capture card for a media insert. Shown when an author already has bytes in hand (a
+ * paste, a drop, or a chosen file), it captures three things and emits them to its host: the file, an
+ * editable display name, and the alt text. It is a presentational form card, not a dialog of its own;
+ * Task 6's insert popover hosts it.
+ *
+ * The display name pre-fills from proposedNameFor(file.name): a real specific stem (blue-shoes.png)
+ * arrives as a Suggested value, while a generic camera stem (IMG_4821.jpg) leaves the field empty and
+ * required with no tag, so the author never accepts machine noise.
+ *
+ * Alt is a real role="radiogroup" of two radios: write a description, or mark decorative. The
+ * requirement is surfaced through aria-describedby, never by disabling the submit. Insert is never
+ * disabled (the locked no-skipped-disabled-reason rule); an author may proceed with alt unset and the
+ * emitted record carries an empty alt, which the host treats as needs-alt debt. A decorative choice
+ * also resolves alt to the empty string. The committed reference keys off an empty alt as the
+ * needs-alt signal, so the emitted record uses an empty alt string for both the decorative and the
+ * left-blank cases, and a separate decorative flag distinguishes them for the host.
+ */
+declare const MediaCaptureCard: import("svelte").Component<Props, {}, "">;
+type MediaCaptureCard = ReturnType<typeof MediaCaptureCard>;
+export default MediaCaptureCard;