@glw907/cairn-cms 0.56.1 → 0.57.0

package/src/lib/components/EditPage.svelte

@@ -21,30 +21,49 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   import { beforeNavigate } from '$app/navigation';
   import { page } from '$app/state';
   import BlocksIcon from '@lucide/svelte/icons/blocks';
+  import SquarePenIcon from '@lucide/svelte/icons/square-pen';
   import LinkIcon from '@lucide/svelte/icons/link';
   import FileSymlinkIcon from '@lucide/svelte/icons/file-symlink';
   import PanelRightIcon from '@lucide/svelte/icons/panel-right';
+  import ImageIcon from '@lucide/svelte/icons/image';
   import { useTopbar } from './topbar-context.js';
   import CsrfField from './CsrfField.svelte';
   import MarkdownEditor from './MarkdownEditor.svelte';
   import EditorToolbar from './EditorToolbar.svelte';
-  import ComponentInsertDialog, { insertableDefs } from './ComponentInsertDialog.svelte';
+  import ComponentInsertDialog, { insertableDefs, hasSchema } from './ComponentInsertDialog.svelte';
   import LinkPicker from './LinkPicker.svelte';
   import WebLinkDialog from './WebLinkDialog.svelte';
+  import MediaInsertPopover from './MediaInsertPopover.svelte';
+  import MediaHeroField from './MediaHeroField.svelte';
+  import MediaFigureControl from './MediaFigureControl.svelte';
   import DeleteDialog from './DeleteDialog.svelte';
   import RenameDialog from './RenameDialog.svelte';
   import MarkdownHelpDialog from './MarkdownHelpDialog.svelte';
   import ShortcutsDialog from './ShortcutsDialog.svelte';
   import { cairnLinkCompletionSource } from './link-completion.js';
-  import { unwrapCairnLink, type FormatKind } from './markdown-format.js';
+  import {
+    findMediaImagesNeedingAlt,
+    unwrapCairnLink,
+    unwrapFigure,
+    updateFigure,
+    wrapImageInFigure,
+    type FigureAtImage,
+    type FigureRole,
+    type FormatKind,
+  } from './markdown-format.js';
   import { buildPreviewDoc, deviceLabel, previewDevice, previewDevices, type PreviewDeviceId } from './preview-doc.js';
   import { directiveLineKind, findInlineDirectives } from './markdown-directives.js';
-  import type { ComponentRegistry } from '../render/registry.js';
+  import type { ComponentRegistry, ComponentDef } from '../render/registry.js';
+  import { parseComponent, componentRoundTripSafety } from '../render/component-grammar.js';
   import type { IconSet } from '../render/glyph.js';
   import type { ContentFormFailure, EditData } from '../sveltekit/content-routes.js';
-  import type { TextareaField, TagsField, FreeTagsField } from '../content/types.js';
+  import type { TextareaField, TagsField, FreeTagsField, ImageValue } from '../content/types.js';
   import type { LinkResolve } from '../content/links.js';
   import { manifestLinkResolver } from '../content/manifest.js';
+  import type { MediaResolve } from '../render/resolve-media.js';
+  import { manifestMediaResolver } from '../render/resolve-media.js';
+  import type { MediaEntry } from '../media/manifest.js';
+  import { mediaLibraryEntry } from '../media/library-entry.js';
 
   interface Props {
     /** The edit load's data, plus the site name for the heading. */
@@ -52,7 +71,10 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
     /** The site's component registry, for the insert palette. */
     registry?: ComponentRegistry;
     /** The site's design-accurate render pipeline; the preview pane renders its output, which the floored pipeline already sanitized. */
-    render?: (md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }) => string | Promise<string>;
+    render?: (
+      md: string,
+      opts?: { stagger?: boolean; resolve?: LinkResolve; resolveMedia?: MediaResolve },
+    ) => string | Promise<string>;
     /** The site's icon set, for the guided form's icon fields. */
     icons?: IconSet;
     /** The last content action's failure: the save guard's broken links, the delete guard's
@@ -124,6 +146,12 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
     if (target?.closest('dialog, #cairn-pane-write')) return;
     fieldsDirty = true;
   }
+  // Mark the details fields dirty without a form input event. The hero field writes its value to
+  // hidden inputs, whose programmatic value changes do not fire the form's oninput, so it signals
+  // dirty through this helper instead.
+  function markFieldsDirty() {
+    fieldsDirty = true;
+  }
 
   // The edit form element, for the Ctrl/Cmd+S shortcut's requestSubmit.
   let editForm = $state<HTMLFormElement | null>(null);
@@ -263,6 +291,10 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   // Which pane the editor card shows. The toolbar's tablist drives it; Write is always the
   // landing tab.
   let mode = $state<'write' | 'preview'>('write');
+  // Preview is read-only, so the insert controls the page renders into the toolbar disable with the
+  // strip's own format buttons. Declared here (above the Edit-block derivations that read it) so it
+  // is in scope before its first use.
+  const insertDisabled = $derived(mode === 'preview');
   let previewHtml = $state('');
   // True after a render call threw, so the preview pane can say so instead of going blank.
   let previewFailed = $state(false);
@@ -353,12 +385,65 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   // preview knob, or a styleless document (behind the hint below) when the site sets none.
   const previewDoc = $derived(buildPreviewDoc(previewHtml, data.preview));
   let insert = $state.raw<(text: string) => void>(() => {});
+  // The editor's range-replace seam, registered by MarkdownEditor on mount; the dialog's Update
+  // routes through it to overwrite an edited block's source span. A no-op until then.
+  let replaceRange = $state.raw<(from: number, to: number, text: string) => void>(() => {});
+  // The editor's select-range seam, registered by MarkdownEditor on mount; the needs-alt notice's
+  // jump control routes through it to land the author on an image that lacks alt. A no-op until then.
+  let selectRange = $state.raw<(from: number, to: number) => void>(() => {});
   let insertLink = $state.raw<(href: string, title: string) => void>(() => {});
   // The editor's current selection, registered by MarkdownEditor on mount; the web link dialog
   // reads it for the Text field's default.
   let getSelection = $state.raw<() => string>(() => '');
   // The editor's selection transform, registered by MarkdownEditor on mount; a no-op until then.
   let format = $state.raw<(kind: FormatKind) => void>(() => {});
+
+  // The media insert seams, registered by MarkdownEditor on mount, mirroring the range holders
+  // above. The popover drives the optimistic upload loop through them: the caret anchor, the focus
+  // restore, the placeholder api, and the direct-insert path for a picked image. The placeholder
+  // api type is referenced inline (import('...').Type), never a static `import type ... from`, so
+  // no static edge to the dynamically-imported editor-placeholder module sits in this component
+  // (the editor-boundary test bars that edge by a textual `from` scan).
+  let caretCoords = $state.raw<() => { left: number; right: number; top: number; bottom: number } | null>(
+    () => null,
+  );
+  let focusEditor = $state.raw<() => void>(() => {});
+  let placeholders = $state.raw<import('./editor-placeholder.js').ImagePlaceholderApi | null>(null);
+  let insertImageFn = $state.raw<(alt: string, ref: string) => void>(() => {});
+
+  // A no-op placeholder api so the editor object handed to the popover is never null before the
+  // editor registers its real one on mount.
+  const noopPlaceholders: import('./editor-placeholder.js').ImagePlaceholderApi = {
+    begin: () => 0,
+    progress: () => {},
+    resolveTo: () => {},
+    cancel: () => {},
+  };
+
+  // The editor object the popover drives, delegating through the holders so the latest registered
+  // function is always used (the holders start as no-ops and are replaced on mount).
+  const editorApi = $derived({
+    caretCoords: () => caretCoords(),
+    focusEditor: () => focusEditor(),
+    placeholders: placeholders ?? noopPlaceholders,
+    insertImage: (alt: string, ref: string) => insertImageFn(alt, ref),
+  });
+
+  // The headless media insert popover, opened from the toolbar control, paste, or drop.
+  let mediaPopover = $state<MediaInsertPopover | null>(null);
+
+  // The rendered hero fields' refs (for the needs-alt notice's "Add alt text" action, which focuses
+  // the field's own alt input) and their reported needs-alt signals, keyed by field name. A hero is
+  // a frontmatter value with no body offset, so its needs-alt signal comes from the field, not the
+  // body scanner (findMediaImagesNeedingAlt), and its remediation focuses the alt input, never a
+  // source range (selectRange). The records are keyed by field name; `data.fields` is static for the
+  // page's lifetime, so a key never goes stale (no per-key cleanup on unmount is needed).
+  let heroFieldRefs = $state<Record<string, MediaHeroField>>({});
+  let heroNeedsAlt = $state<Record<string, boolean>>({});
+
+  // The server-owned records from each successful upload this session. They ride the save form as
+  // the hidden `media` field, so the save action merges them into media.json.
+  let uploadedRecords = $state<MediaEntry[]>([]);
   // A headless dialog instance, typed structurally over its exported open() (the linkPicker idiom).
   type DialogHandle = { open: () => void };
   // The toolbar's insert dialogs. Each holds its own <form>, so they mount outside the edit form
@@ -366,7 +451,9 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   // breaks SSR and hydration); the toolbar snippet renders plain triggers that open them here.
   let webLinkDialog = $state<DialogHandle | null>(null);
   let linkPicker = $state<DialogHandle | null>(null);
-  let insertDialog = $state<DialogHandle | null>(null);
+  // The insert dialog binds the full instance, not the bare DialogHandle: the Edit-block control
+  // drives editComponent(def, values, range) on it, beyond the shared open().
+  let insertDialog = $state<ComponentInsertDialog | null>(null);
   // The lifecycle dialogs, opened from the header's overflow menu.
   let deleteDialog = $state<DialogHandle | null>(null);
   let renameDialog = $state<DialogHandle | null>(null);
@@ -379,6 +466,183 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   // by, so the toolbar trigger and the dialog appear and disappear together.
   const hasComponents = $derived(insertableDefs(registry).length > 0);
 
+  // The directive container at the editor caret, reported by MarkdownEditor whenever it changes
+  // (null outside any container). The Edit-block control resolves it against the registry and the
+  // round-trip safety gate below; its identity is the key the async gate guards against a stale
+  // result. The reporter's name+markdown+from+to shape; declared locally because MarkdownEditor's
+  // matching interface is not exported.
+  type CaretComponent = { name: string | null; markdown: string; from: number; to: number };
+  let caretComponent = $state<CaretComponent | null>(null);
+
+  // The media image at the editor caret, reported by MarkdownEditor whenever it changes (null off any
+  // media image). The Figure control reads it to wrap a bare image or edit an existing figure; it
+  // writes source through the replaceRange seam. The figure dialog is mounted headless below.
+  let mediaAtCaret = $state<FigureAtImage | null>(null);
+  // The figure control's host <dialog>, opened by the toolbar control. Mounted outside the edit form
+  // (a form nested in a form is invalid HTML), the Edit-block dialog pattern.
+  let figureDialog = $state<HTMLDialogElement | null>(null);
+  // Whether the Figure control is available: a media image sits at the caret and Preview is not
+  // showing (the insert controls disable together with the Write surface). The control is always
+  // rendered (it never mounts on caret move); only its enabled state changes.
+  const figureAvailable = $derived(mediaAtCaret != null && !insertDisabled);
+  const figureLabel = $derived(
+    figureAvailable
+      ? mediaAtCaret?.figure
+        ? 'Edit the figure at the cursor'
+        : 'Wrap the image at the cursor in a figure'
+      : 'Place the cursor on an image to add a figure',
+  );
+  // Whether the image at the caret is decorative (empty or whitespace-only alt). The token came from
+  // a parsed image node, so the alt is the source between `![` and the closing `]` before `](`. An
+  // empty alt is the needs-alt signal; the figure control surfaces it and the decorative-plus-caption
+  // warning. Derived from the reported token so it tracks the caret.
+  const figureDecorative = $derived.by(() => {
+    if (!mediaAtCaret) return false;
+    const token = body.slice(mediaAtCaret.imageFrom, mediaAtCaret.imageTo);
+    const match = /^!\[([\s\S]*?)\]\(/.exec(token);
+    return (match?.[1] ?? '').trim() === '';
+  });
+  // A def is actionable for guided edit when it has a schema (the same notion the insert catalog
+  // lists by): a template-only def has no form to re-open into. Reuses the dialog's exported
+  // hasSchema so the two surfaces can never drift on what counts as editable.
+  function editableDef(name: string | null): ComponentDef | undefined {
+    if (!name) return undefined;
+    const def = registry?.get(name);
+    if (!def) return undefined;
+    return hasSchema(def) ? def : undefined;
+  }
+  // The resolved editability: the def, the source range, and the validated markdown when the caret
+  // sits on a known, schema-bearing component whose round-trip safety check passed for the CURRENT
+  // caret; null otherwise. The def, range, and markdown are captured from one caretComponent
+  // snapshot, so editBlock() never mixes a newer markdown with an older range. The Edit-block
+  // control enables only when this is set.
+  let editable = $state<{ def: ComponentDef; range: { from: number; to: number }; markdown: string } | null>(null);
+  // Why edit is unavailable, distinguishing "not on a component" from "on an unsafe one" so the
+  // disabled tooltip is honest. 'none' covers both no-caret-component and an unknown/template-only
+  // one (no guided form either way); 'unsafe' is a known component the safety gate refused.
+  let editReason = $state<'none' | 'unsafe'>('none');
+  // Resolve editability when the caret-component changes, async-safe. componentRoundTripSafety is
+  // async, so a slow check could resolve after a newer caret move; guard latest-wins on the
+  // caretComponent identity (the EditPage preview-debounce pattern), only applying a result when
+  // the caret has not moved since the check started. A block whose check did not pass for the
+  // current caret never enables edit.
+  $effect(() => {
+    const current = caretComponent;
+    const def = editableDef(current?.name ?? null);
+    if (!current || !def) {
+      editable = null;
+      editReason = 'none';
+      return;
+    }
+    let stale = false;
+    void componentRoundTripSafety(current.markdown, def)
+      .then((result) => {
+        if (stale || caretComponent !== current) return;
+        if (result.safe) {
+          editable = { def, range: { from: current.from, to: current.to }, markdown: current.markdown };
+          editReason = 'none';
+        } else {
+          editable = null;
+          editReason = 'unsafe';
+        }
+      })
+      .catch(() => {
+        // A parse throw during the safety check must never leave a stale block enabled. Guarded by
+        // the same latest-wins identity, fall back to the safe default of no editable block.
+        if (stale || caretComponent !== current) return;
+        editable = null;
+        editReason = 'none';
+      });
+    return () => {
+      stale = true;
+    };
+  });
+  // The Edit-block control's accessible label and tooltip: a plain reason in each state. Enabled
+  // names the action; the two disabled reasons are honest about why.
+  const editBlockLabel = $derived(
+    editable
+      ? 'Edit the component at the cursor'
+      : editReason === 'unsafe'
+        ? "This block can't be edited in the form. Edit it as markdown."
+        : 'Place the cursor in a component to edit it',
+  );
+  // Whether the Edit-block control is unavailable: either Preview hides the Write surface, or the
+  // caret is not on a safe, schema-bearing component. The control stays focusable and announced in
+  // this state (aria-disabled, not the native disabled attribute), so its reason reaches assistive
+  // technology; the dead click is made inert in editBlock().
+  const editBlockUnavailable = $derived(insertDisabled || !editable);
+  // Activate edit: parse the block into form values, then open the dialog in edit mode over the
+  // stored source range. Guarded by editable AND the preview-mode disable, so the control is inert
+  // unless the gate passed and the editor is on the Write tab. The def, range, and markdown all come
+  // from the one editable snapshot, so a newer caret markdown is never paired with an older range.
+  async function editBlock() {
+    if (insertDisabled || !editable) return;
+    const values = await parseComponent(editable.markdown, editable.def);
+    insertDialog?.editComponent(editable.def, values, editable.range);
+  }
+
+  // The figure dialog's pre-fill, snapshotted when the control opens so the form never mixes a newer
+  // caret with the values it opened on. Captured from mediaAtCaret at open time: edit mode with the
+  // figure's caption/role when a figure wraps the image, else wrap mode with empty caption and the
+  // measure default. decorative rides the snapshot too. Null while the dialog is closed.
+  let figurePrefill = $state<{
+    mode: 'wrap' | 'edit';
+    caption: string;
+    role: FigureRole | null;
+    decorative: boolean;
+    image: { from: number; to: number };
+    figureRange: { from: number; to: number } | null;
+  } | null>(null);
+
+  // Open the figure control over the media image at the caret. Inert unless a media image sits there
+  // and the Write surface is up, the same gate the toolbar control shows. The snapshot is the source
+  // of truth for the apply handlers, so a caret move while the dialog is open never re-targets it.
+  function openFigure() {
+    if (!figureAvailable || !mediaAtCaret) return;
+    const at = mediaAtCaret;
+    figurePrefill = {
+      mode: at.figure ? 'edit' : 'wrap',
+      caption: at.figure?.caption ?? '',
+      role: at.figure?.role ?? null,
+      decorative: figureDecorative,
+      image: { from: at.imageFrom, to: at.imageTo },
+      figureRange: at.figure ? { from: at.figure.from, to: at.figure.to } : null,
+    };
+    figureDialog?.showModal();
+  }
+
+  // Apply the control's choice through the replaceRange seam, then close. Wrap a bare image or update
+  // an existing figure, off the snapshot the dialog opened on. The pure transform owns the source
+  // shape and keeps the media token byte-intact; the preview stays read-only.
+  function applyFigure(choice: { caption: string; role: FigureRole | null }) {
+    const pre = figurePrefill;
+    if (!pre) return;
+    const result =
+      pre.mode === 'edit' && pre.figureRange
+        ? updateFigure(body, pre.figureRange, choice.caption, choice.role)
+        : wrapImageInFigure(body, pre.image.from, pre.image.to, choice.caption, choice.role);
+    writeFigureResult(result);
+  }
+
+  // Unwrap the figure back to its bare image, then close. Edit mode only (the snapshot carries the
+  // figure range). The bare image token is restored verbatim by the pure transform.
+  function unwrapFigureAction() {
+    const pre = figurePrefill;
+    if (!pre || !pre.figureRange) return;
+    writeFigureResult(unwrapFigure(body, pre.figureRange));
+  }
+
+  // Write a figure transform's result back to the editor: overwrite the whole doc through the
+  // replaceRange seam, then place the selection the transform chose (the seam alone drops the caret
+  // at the end). replaceRange dispatches the doc change and focuses the surface; selectRange then
+  // dispatches a selection-only transaction, which CodeMirror's history does not record as its own
+  // undoable event, so one undo reverts the whole figure write. Close the dialog last.
+  function writeFigureResult(result: { doc: string; from: number; to: number }) {
+    replaceRange(0, body.length, result.doc);
+    selectRange(result.from, result.to);
+    figureDialog?.close();
+  }
+
   // The header's status badge, in ConceptList's vocabulary: a pending entry reads Edited (or New
   // when it has never been published); otherwise the live site matches and it reads Published.
   const status = $derived.by(() => {
@@ -444,6 +708,21 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
     }
   }
 
+  // The media images in the live body that carry no alt text, recomputed as the author types. Alt is
+  // accessibility debt, never a render or publish failure, so this drives a non-blocking warning the
+  // author can act on or leave; the count drops and the notice clears as each alt is filled.
+  const needsAlt = $derived(findMediaImagesNeedingAlt(body));
+
+  // The declared image (hero) fields, for labelling the needs-alt notice's frontmatter rows.
+  const imageFields = $derived(
+    data.fields.filter((f) => f.type === 'image').map((f) => ({ name: f.name, label: f.label })),
+  );
+  // The frontmatter-hero needs-alt rows: each image field whose hero reports a needs-alt signal. The
+  // row's action focuses the field's alt input (the body scanner and its source-range jump cannot
+  // reach a frontmatter value). The headline count sums these with the body scanner's hits.
+  const heroRows = $derived(imageFields.filter((f) => heroNeedsAlt[f.name]));
+  const needsAltCount = $derived(needsAlt.length + heroRows.length);
+
   // The delete guard's inbound linkers, from a refused delete (fail 409). Empty when the delete was
   // not refused. When set, a delete was blocked by a link that appeared since the page loaded.
   const deleteRefusedLinks = $derived(form?.inboundLinks ?? []);
@@ -556,6 +835,28 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   // returns undefined for a missing target so the render step marks it cairn-broken-link.
   const resolveLink = $derived(manifestLinkResolver(data.linkTargets));
 
+  // The media analog: it turns a media: reference into its /media delivery path in the preview, and
+  // returns undefined for a missing target so the render step marks it cairn-broken-media. The
+  // committed mediaTargets projection is merged with this session's uploaded records (the same
+  // override the picker's library does), so a just-uploaded image renders its thumbnail in the live
+  // preview before the next save commits it, rather than reading as a broken reference.
+  const resolveMediaTargets = $derived({
+    ...data.mediaTargets,
+    ...Object.fromEntries(
+      uploadedRecords.map((r) => [r.hash, { slug: r.slug, ext: r.ext, contentType: r.contentType }]),
+    ),
+  });
+  const resolveMedia = $derived(manifestMediaResolver(resolveMediaTargets));
+
+  // The picker's library, the committed projection merged with this session's uploaded records,
+  // keyed by content hash. An uploaded record overrides a committed entry on a hash match (the same
+  // hash is the same bytes, so the override is harmless). This is what the editor decorates with, so
+  // a just-uploaded image carries its source chip before the next save commits it.
+  const mediaLibrary = $derived({
+    ...data.mediaLibrary,
+    ...Object.fromEntries(uploadedRecords.map((r) => [r.hash, mediaLibraryEntry(r)])),
+  });
+
   // The [[ autocomplete source over the same link targets, handed to the editor's generic seam.
   const completionSources = $derived([cairnLinkCompletionSource(data.linkTargets)]);
 
@@ -563,10 +864,6 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
     mode = m;
   }
 
-  // Preview is read-only, so the insert controls the page renders into the toolbar disable with
-  // the strip's own format buttons.
-  const insertDisabled = $derived(mode === 'preview');
-
   // The editor card's keyboard shortcuts. Bound to the card so they fire wherever focus sits in the
   // strip or the surface, without claiming the keys page-wide. The listener attaches
   // programmatically: it is event delegation, not an interaction affordance, which Svelte's a11y
@@ -626,10 +923,11 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
     if (mode !== 'preview' || !render) return;
     const md = body;
     const resolve = resolveLink; // tracked read in the effect body
+    const resolveMediaRef = resolveMedia; // tracked read in the effect body
     const run = ++previewRun;
     const handle = setTimeout(async () => {
       try {
-        const html = await render(md, { resolve });
+        const html = await render(md, { resolve, resolveMedia: resolveMediaRef });
         if (run === previewRun) {
           previewHtml = html;
           previewFailed = false;
@@ -828,6 +1126,45 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
     </ul>
   </div>
 {/if}
+<!-- The publish-time needs-alt notice: a non-blocking warning, never a block. Alt text is
+     accessibility debt, so the author can add it now or save without it; the count drops live as
+     each alt is filled and the notice clears at zero. The leading glyph carries the state alongside
+     the count, so the caution reads without relying on hue. Each row's jump control selects the
+     image in the source through the editor's select-range seam, landing the author on it to type
+     the alt. The role="status" live region renders unconditionally (present and empty at load), so
+     when the first debt appears its count change announces; a region conditionally mounted with its
+     first content may not be observed by assistive tech (WCAG 4.1.3). The visible alert chrome and
+     content gate on the count, so an empty region shows nothing. A plain wrapper (not display:contents)
+     carries the role, since some assistive tech drops a role off a display:contents box. -->
+<div role="status">
+  {#if needsAltCount}
+    <div class="alert alert-warning mb-4 flex-col items-start text-sm">
+      <p class="flex items-center gap-2 font-medium">
+        <svg class="h-4 w-4 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" aria-hidden="true">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v4m0 4h.01M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z" />
+        </svg>
+        <span>{needsAltCount} {needsAltCount === 1 ? 'image needs' : 'images need'} alt text</span>
+      </p>
+      <p>Alt text describes an image for readers who cannot see it. Add it now, or save and come back to it.</p>
+      <ul class="mt-1 w-full">
+        {#each needsAlt as item (item.from)}
+          <li class="flex items-center justify-between gap-2">
+            <code class="text-xs">{item.ref}</code>
+            <button type="button" class="btn btn-xs" onclick={() => selectRange(item.from, item.to)}>Add alt text</button>
+          </li>
+        {/each}
+        <!-- The frontmatter-hero rows: a hero has no body offset, so its action focuses the field's
+             own alt input rather than a source range. -->
+        {#each heroRows as hero (hero.name)}
+          <li class="flex items-center justify-between gap-2">
+            <span class="text-xs font-medium">{hero.label}</span>
+            <button type="button" class="btn btn-xs" onclick={() => heroFieldRefs[hero.name]?.focusAlt()}>Add alt text</button>
+          </li>
+        {/each}
+      </ul>
+    </div>
+  {/if}
+</div>
 {#if draftWarning}
   <div class="alert alert-warning mb-4 text-sm">
     Saved. Note: this page links to unpublished {draftWarning.includes(',') ? 'pages' : 'a page'} ({draftWarning}), which will 404 until published.
@@ -903,6 +1240,24 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
             >
               <BlocksIcon class="h-4 w-4" aria-hidden="true" />
             </button>
+            <!-- Edit block re-opens the component at the caret into the guided form. It is
+                 unavailable while Preview shows (like the insert controls) and whenever the caret is
+                 not on a safe, schema-bearing component; the tooltip names the reason in each state.
+                 The unavailable state uses aria-disabled, not the native disabled attribute, so the
+                 control stays focusable and its reason reaches assistive technology; the disabled
+                 look rides a class and editBlock() early-returns so the dead click is inert. -->
+            <button
+              type="button"
+              class="btn btn-sm btn-ghost btn-square"
+              class:btn-disabled={editBlockUnavailable}
+              aria-haspopup="dialog"
+              aria-label={editBlockLabel}
+              title={editBlockLabel}
+              aria-disabled={editBlockUnavailable}
+              onclick={editBlock}
+            >
+              <SquarePenIcon class="h-4 w-4" aria-hidden="true" />
+            </button>
           {/if}
           <button
             type="button"
@@ -929,9 +1284,10 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
           <button
             type="button"
             class="btn btn-ghost btn-sm btn-square"
-            disabled
-            aria-label="Image (coming soon)"
-            title="Image (coming soon)"
+            disabled={insertDisabled}
+            aria-label="Insert image"
+            title="Insert image"
+            onclick={() => mediaPopover?.open('chooser')}
           >
             <svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
               <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
@@ -939,6 +1295,26 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
               <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21" />
             </svg>
           </button>
+          <!-- The Figure control: always rendered, enabled only when the caret sits on a media image
+               (and the Write surface is up). It never mounts or unmounts on caret movement; only its
+               enabled state changes (the Edit-block pattern). The unavailable state uses aria-disabled,
+               not the native disabled attribute, so the control stays focusable and its reason reaches
+               assistive technology; openFigure() early-returns so the dead click is inert. The dimming
+               uses opacity and cursor utilities, never .btn-disabled, because that sets
+               pointer-events: none and would suppress the title tooltip a mouse user reads for the why. -->
+          <button
+            type="button"
+            class="btn btn-sm btn-ghost btn-square"
+            class:opacity-50={!figureAvailable}
+            class:cursor-not-allowed={!figureAvailable}
+            aria-haspopup="dialog"
+            aria-label={figureLabel}
+            title={figureLabel}
+            aria-disabled={!figureAvailable}
+            onclick={openFigure}
+          >
+            <ImageIcon class="h-4 w-4" aria-hidden="true" />
+          </button>
         {/snippet}
       </EditorToolbar>
       {/if}
@@ -950,13 +1326,26 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
           name="body"
           {surface}
           registerInsert={(fn) => (insert = fn)}
+          onComponentAtCaret={(info) => (caretComponent = info)}
+          onMediaImageAtCaret={(info) => (mediaAtCaret = info)}
+          registerReplaceRange={(fn) => (replaceRange = fn)}
+          registerSelectRange={(fn) => (selectRange = fn)}
           registerInsertLink={(fn) => (insertLink = fn)}
           registerGetSelection={(fn) => (getSelection = fn)}
           registerFormat={(fn) => (format = fn)}
+          registerCaretCoords={(fn) => (caretCoords = fn)}
+          registerFocusEditor={(fn) => (focusEditor = fn)}
+          registerImagePlaceholders={(api) => (placeholders = api)}
+          registerInsertImage={(fn) => (insertImageFn = fn)}
+          onImageIngest={(file) => mediaPopover?.open('capture', file)}
           {completionSources}
+          {mediaLibrary}
           {focusMode}
           {typewriter}
         />
+        <!-- The accumulated uploaded records ride the save form alongside the body. The save action
+             reads `media` and merges these records into media.json (publish submits the same form). -->
+        <input type="hidden" name="media" value={JSON.stringify(uploadedRecords)} />
       </div>
       {#if mode === 'preview'}
         <!-- The preview ground: recessed under the floating frame card so the page reads as a
@@ -1177,6 +1566,19 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
               value={tagValue}
             />
           </label>
+        {:else if field.type === 'image'}
+          {@const heroValue = data.frontmatter[field.name] as ImageValue | undefined}
+          <MediaHeroField
+            bind:this={heroFieldRefs[field.name]}
+            field={{ name: field.name, label: field.label }}
+            value={heroValue}
+            mediaLibrary={mediaLibrary}
+            conceptId={data.conceptId}
+            id={data.id}
+            onuploaded={(record) => (uploadedRecords = [...uploadedRecords, record])}
+            ondirty={markFieldsDirty}
+            onneedsaltchange={(n) => (heroNeedsAlt = { ...heroNeedsAlt, [field.name]: n })}
+          />
         {:else}
           <label class="flex flex-col gap-1">
             <span class="text-sm font-medium">{field.label}</span>
@@ -1239,10 +1641,70 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
      <form>, and a form nested in a form is invalid HTML the parser repairs by dropping the outer
      tag, which breaks the SSR'd document and hydration. The toolbar snippet's triggers drive them
      through their exported open(). -->
-<ComponentInsertDialog bind:this={insertDialog} trigger={false} {registry} {insert} {icons} />
+<ComponentInsertDialog
+  bind:this={insertDialog}
+  trigger={false}
+  {registry}
+  {insert}
+  update={(range, md) => replaceRange(range.from, range.to, md)}
+  {icons}
+  {render}
+  preview={data.preview}
+/>
 <WebLinkDialog bind:this={webLinkDialog} trigger={false} insert={insertLink} selection={getSelection} />
 <LinkPicker bind:this={linkPicker} trigger={false} linkTargets={data.linkTargets} insert={insertLink} />
 
+<!-- The media insert popover, mounted headless: the toolbar control, a paste, or a drop drives it
+     through its exported open(). On a successful upload it hands the server-owned record up; the
+     record joins uploadedRecords (the hidden save field) and the merged library (the source chip). -->
+<MediaInsertPopover
+  bind:this={mediaPopover}
+  trigger={false}
+  conceptId={data.conceptId}
+  id={data.id}
+  library={mediaLibrary}
+  editor={editorApi}
+  onuploaded={(record) => (uploadedRecords = [...uploadedRecords, record])}
+/>
+
+<!-- The figure control's host dialog, mounted headless outside the edit form (the control holds its
+     own <form>). The toolbar Figure control opens it through openFigure(), pre-filled from the caret
+     snapshot. The control is keyed on figurePrefill so it remounts fresh per open, seeding its fields
+     from the new caption/role. The native <dialog> gives the focus trap and Escape for free, and the
+     close event (the X, the backdrop, Escape, and the apply path all fire it) clears the snapshot so
+     the host state matches the closed dialog. -->
+<dialog
+  class="modal"
+  aria-labelledby="cairn-figure-dialog-title"
+  bind:this={figureDialog}
+  onclose={() => (figurePrefill = null)}
+>
+  <div class="modal-box max-w-sm">
+    <div class="mb-3 flex items-center justify-between">
+      <h2 id="cairn-figure-dialog-title" class="flex items-center gap-2 text-base font-semibold">
+        <ImageIcon class="h-4 w-4 text-[var(--color-accent)]" aria-hidden="true" />
+        {figurePrefill?.mode === 'edit' ? 'Edit figure' : 'Wrap in a figure'}
+      </h2>
+      <button type="button" class="btn btn-ghost btn-sm" aria-label="Close" onclick={() => figureDialog?.close()}>✕</button>
+    </div>
+    {#if figurePrefill}
+      {#key figurePrefill}
+        <MediaFigureControl
+          caption={figurePrefill.caption}
+          role={figurePrefill.role}
+          mode={figurePrefill.mode}
+          decorative={figurePrefill.decorative}
+          onapply={applyFigure}
+          onunwrap={unwrapFigureAction}
+        />
+      {/key}
+    {/if}
+  </div>
+  <form method="dialog" class="modal-backdrop">
+    <button tabindex="-1" aria-label="Close">close</button>
+  </form>
+</dialog>
+
 <!-- The lifecycle dialogs, mounted headless: the header's overflow menu drives them through their
      exported open(). Their POST forms flip the leaving flag so the leave guard stands down. -->
 <RenameDialog