feat(editor): add editable image captions (#221)

Add a visible caption (<figcaption>) under images, editable from the
image bubble-menu and persisted across all formats: native Yjs/JSON,
HTML export, and Markdown.

- image node: new plain-text `caption` attribute (parse/render
  `data-caption` on <img>, emitted only when set) + `setImageCaption`
  command. The node stays an atom; the schema shape is unchanged, so the
  server's generateHTML/generateJSON path round-trips it for free.
- resize node-view: re-parent the resizable wrapper into a <figure> and
  render the caption in a <figcaption> BELOW it, outside nodeView.wrapper
  (so onCommit's offsetHeight measurement and the left/right resize
  handles still cover the image only). This path also drives read-only /
  share rendering. React placeholder view renders the caption too.
- bubble-menu: new useCaptionControl panel modeled on useAltTextControl
  (own icon, Caption strings, softer sanitizer, ~500 char limit).
- markdown lossless round-trip: a captioned image is emitted as a raw
  <img data-caption> wrapped in a block <div> (same trick as <video>) in
  both the editor-ext turndown rule and the MCP converter; caption-less
  images stay clean ![alt](src). Import restores the caption via the
  shared markdownToHtml + parseHTML.
- styles + i18n keys; tests for the schema attr round-trip, markdown
  round-trip (editor-ext) and the MCP converter.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/client/src/features/editor/components/common/use-caption-control.tsx

@@ -0,0 +1,141 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { Editor } from "@tiptap/react";
+import {
+  ActionIcon,
+  Button,
+  Group,
+  Paper,
+  Text,
+  Textarea,
+  Tooltip,
+} from "@mantine/core";
+import { IconTextCaption } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+
+const CAPTION_MAX_LENGTH = 500;
+
+// Caption is plain visible text (not a markdown link target like alt), so it is
+// sanitized more softly than alt: collapse runs of whitespace/newlines into a
+// single space and trim, keeping the limit generous.
+function sanitizeCaption(value: string): string {
+  return value.replace(/\s+/g, " ").trim().slice(0, CAPTION_MAX_LENGTH);
+}
+
+type UseCaptionControlArgs = {
+  editor: Editor;
+  nodeName: string;
+  currentCaption: string;
+};
+
+export function useCaptionControl({
+  editor,
+  nodeName,
+  currentCaption,
+}: UseCaptionControlArgs) {
+  const { t } = useTranslation();
+  const [showInput, setShowInput] = useState(false);
+  const [draft, setDraft] = useState("");
+
+  const open = useCallback(() => {
+    setDraft(currentCaption || "");
+    setShowInput(true);
+  }, [currentCaption]);
+
+  useEffect(() => {
+    const handler = () => {
+      if (!editor.isActive(nodeName)) {
+        setShowInput(false);
+      }
+    };
+    editor.on("selectionUpdate", handler);
+    return () => {
+      editor.off("selectionUpdate", handler);
+    };
+  }, [editor, nodeName]);
+
+  const cancel = useCallback(() => {
+    setShowInput(false);
+  }, []);
+
+  const save = useCallback(() => {
+    editor
+      .chain()
+      .focus(undefined, { scrollIntoView: false })
+      .updateAttributes(nodeName, {
+        caption: sanitizeCaption(draft) || undefined,
+      })
+      .run();
+    setShowInput(false);
+  }, [editor, nodeName, draft]);
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        save();
+      } else if (e.key === "Escape") {
+        e.preventDefault();
+        cancel();
+      }
+    },
+    [save, cancel],
+  );
+
+  const button = (
+    <Tooltip position="top" label={t("Caption")} withinPortal={false}>
+      <ActionIcon
+        onClick={open}
+        size="lg"
+        aria-label={t("Caption")}
+        variant="subtle"
+      >
+        <IconTextCaption size={18} />
+      </ActionIcon>
+    </Tooltip>
+  );
+
+  const panel = showInput ? (
+    <Paper
+      withBorder
+      shadow="md"
+      radius={6}
+      p="sm"
+      w={320}
+      style={{ position: "relative", zIndex: 100 }}
+    >
+      <Text size="sm" fw={600} mb={2}>
+        {t("Caption")}
+      </Text>
+      <Text size="xs" c="dimmed" mb="xs">
+        {t("Shown below the image.")}
+      </Text>
+      <Textarea
+        size="xs"
+        placeholder={t("Add a caption")}
+        value={draft}
+        onChange={(e) => setDraft(e.currentTarget.value)}
+        onKeyDown={onKeyDown}
+        autoFocus
+        autosize
+        minRows={2}
+        maxRows={5}
+        maxLength={CAPTION_MAX_LENGTH}
+      />
+      <Group justify="space-between" align="center" mt="xs" wrap="nowrap">
+        <Text size="xs" c="dimmed">
+          {draft.length}/{CAPTION_MAX_LENGTH}
+        </Text>
+        <Group gap="xs">
+          <Button size="compact-xs" variant="default" onClick={cancel}>
+            {t("Cancel")}
+          </Button>
+          <Button size="compact-xs" onClick={save}>
+            {t("Save")}
+          </Button>
+        </Group>
+      </Group>
+    </Paper>
+  ) : null;
+
+  return { button, panel, isEditing: showInput };
+}

apps/client/src/features/editor/components/image/image-menu.tsx

@@ -23,6 +23,7 @@ import { useTranslation } from "react-i18next";
 import { getFileUrl } from "@/lib/config.ts";
 import { uploadImageAction } from "@/features/editor/components/image/upload-image-action.tsx";
 import { useAltTextControl } from "@/features/editor/components/common/use-alt-text-control.tsx";
+import { useCaptionControl } from "@/features/editor/components/common/use-caption-control.tsx";
 import classes from "../common/toolbar-menu.module.css";
 
 export function ImageMenu({ editor }: EditorMenuProps) {
@@ -47,6 +48,7 @@ export function ImageMenu({ editor }: EditorMenuProps) {
         isFloatRight: ctx.editor.isActive("image", { align: "floatRight" }),
         src: imageAttrs?.src || null,
         alt: imageAttrs?.alt || "",
+        caption: imageAttrs?.caption || "",
       };
     },
   });
@@ -168,6 +170,16 @@ export function ImageMenu({ editor }: EditorMenuProps) {
     currentAlt: editorState?.alt || "",
   });
 
+  const {
+    button: captionButton,
+    panel: captionPanel,
+    isEditing: isEditingCaption,
+  } = useCaptionControl({
+    editor,
+    nodeName: "image",
+    currentCaption: editorState?.caption || "",
+  });
+
   return (
     <BaseBubbleMenu
       editor={editor}
@@ -183,6 +195,8 @@ export function ImageMenu({ editor }: EditorMenuProps) {
     >
       {isEditingAlt ? (
         altTextPanel
+      ) : isEditingCaption ? (
+        captionPanel
       ) : (
         <div className={classes.toolbar}>
         <Tooltip position="top" label={t("Align left")} withinPortal={false}>
@@ -249,6 +263,8 @@ export function ImageMenu({ editor }: EditorMenuProps) {
 
         {altTextButton}
 
+        {captionButton}
+
         <div className={classes.divider} />
 
         <Tooltip position="top" label={t("Download")} withinPortal={false}>

apps/client/src/features/editor/components/image/image-view.module.css

@@ -7,6 +7,16 @@
   overflow: hidden;
 }
 
+.imageCaption {
+  display: block;
+  text-align: center;
+  font-size: 0.875em;
+  color: var(--mantine-color-dimmed);
+  margin-top: 0.4em;
+  line-height: 1.35;
+  word-break: break-word;
+}
+
 .skeleton {
   animation: pulse 1.2s ease-in-out infinite;
 

apps/client/src/features/editor/components/image/image-view.tsx

@@ -9,7 +9,9 @@ import { useTranslation } from "react-i18next";
 export default function ImageView(props: NodeViewProps) {
   const { t } = useTranslation();
   const { editor, node, selected } = props;
-  const { src, width, align, alt, aspectRatio, placeholder } = node.attrs;
+  const { src, width, align, alt, caption, aspectRatio, placeholder } =
+    node.attrs;
+  const captionText = (caption || "").trim();
   const alignClass = useMemo(() => {
     if (align === "left") return "alignLeft";
     if (align === "right") return "alignRight";
@@ -29,6 +31,7 @@ export default function ImageView(props: NodeViewProps) {
 
   return (
     <NodeViewWrapper data-drag-handle>
+      <figure style={{ margin: 0 }}>
       <div
         className={clsx(
           selected && "ProseMirror-selectednode",
@@ -66,6 +69,15 @@ export default function ImageView(props: NodeViewProps) {
           </Group>
         )}
       </div>
+      {captionText && (
+        <Text
+          component="figcaption"
+          className={clsx(classes.imageCaption, "image-caption")}
+        >
+          {captionText}
+        </Text>
+      )}
+      </figure>
     </NodeViewWrapper>
   );
 }

apps/client/src/features/editor/styles/media.css

@@ -33,6 +33,15 @@
     }
   }
 
+  .image-caption {
+    text-align: center;
+    font-size: 0.875em;
+    color: var(--mantine-color-dimmed);
+    margin-top: 0.4em;
+    line-height: 1.35;
+    word-break: break-word;
+  }
+
   .uploading-text {
     font-size: var(--mantine-font-size-md);
     line-height: var(--mantine-line-height-md);