@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/RichTextEditor/RichTextEditor.tsx

@@ -0,0 +1,1910 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type HTMLAttributes,
+} from 'react';
+import { flushSync } from 'react-dom';
+import clsx from 'clsx';
+import type { RichDoc, Range, Mark, MarkType, Point } from '../RichText/engine/model';
+import { nextId } from '../RichText/engine/model';
+import { renderDoc } from '../RichText/engine/renderDoc';
+import type { RenderLink } from '../RichText/engine/renderLink';
+import type { RenderMention } from '../RichText/engine/renderMention';
+import {
+  blockLength,
+  isCollapsed,
+  wholeBlockRange,
+  marksForTypedText,
+} from '../RichText/engine/position';
+import { linkAt, setLink } from './links';
+import { applyTypeAutolink, atomicLinkDeleteRange } from './autolinkInput';
+import { RichTextLinkEditor } from './RichTextLinkEditor';
+import { useLinkEditor } from './useLinkEditor';
+import {
+  insertText,
+  insertFragment,
+  insertMention,
+  deleteRange,
+  setColorMark,
+} from '../RichText/engine/transforms';
+import { linkifyRuns, findUrl } from '../RichText/engine/autolink';
+import { useMention } from './useMention';
+import { RichTextMentionMenu } from './RichTextMentionMenu';
+import type { MentionItem, MentionsConfig } from './mentions';
+import { fromHtml } from '../RichText/engine/fromHtml';
+import { hasMark, withMark, withoutMark } from '../RichText/engine/marks';
+import { useTranslation } from '../../i18n';
+import { readSelection, writeSelection, rangeRect, voidCaretSide, blockOwnText } from './selection';
+import { applyInput, voidDelete } from './input';
+import { matchBlockRule, applyBlockRule } from './inputRules';
+import { runsText } from '../RichText/engine/inlines';
+import { isLetterKey } from '../_internal/letterKey';
+import { shortcutMark } from './shortcuts';
+import {
+  activeMarks as deriveActiveMarks,
+  activeColors as deriveActiveColors,
+  currentBlock as deriveCurrentBlock,
+  runToggleMark,
+  runSetBlock,
+  runToggleList,
+  runIndent,
+  applyExactMarks,
+} from './commands';
+import { RichTextToolbar, type BlockChoice } from './RichTextToolbar';
+import {
+  moveBlockUnit,
+  moveBlockUnitToIndex,
+  duplicateBlockUnit,
+  removeBlockUnit,
+  insertEmptyBlockBelow,
+} from '../RichText/engine/blockUnit';
+import { RichTextBlockControls } from './RichTextBlockControls';
+import { RichTextAttachmentConfig } from './RichTextAttachmentConfig';
+import { useAttachmentConfig } from './useAttachmentConfig';
+import { RichTextImageResizer } from './RichTextImageResizer';
+import { LiveRegion } from '../LiveRegion';
+import { capWidthToHeight } from './imageSize';
+import { imageMaxHeightStyle } from '../RichText/imageMaxHeightStyle';
+import { attachmentIsImage, isAttachmentSettled } from '../RichText/engine/attachment';
+import { safeHref } from '../RichText/engine/safeHref';
+import type { BlockAction } from './RichTextBlockMenu';
+import { useUpload, type UploadConfig } from './useUpload';
+import {
+  reset as historyReset,
+  record as historyRecord,
+  undo as historyUndo,
+  redo as historyRedo,
+  canUndo as historyCanUndo,
+  canRedo as historyCanRedo,
+} from './history';
+import type { History, EditKind } from './history';
+import styles from './RichTextEditor.module.scss';
+
+// Stable sentinel ReactNode passed as `renderLink`'s `defaultNode` when probing
+// whether a link is "resolved" (the consumer returns a custom chip) vs. declined
+// (returns the fallback). A custom return is `!== FALLBACK_SENTINEL` by identity;
+// declining returns the exact sentinel back. A frozen one-off element keeps a
+// stable reference across calls.
+const FALLBACK_SENTINEL: React.ReactNode = Object.freeze(<span key="rt-fallback-sentinel" />);
+
+export interface RichTextEditorProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onChange' | 'children'
+> {
+  /** Controlled document. Render the doc returned by `onChange` back into `value` as-is, right away — a cloned/normalized copy reads as an outside replacement and resets undo history; one stored only after a later edit (debounced, or a deferred render the next keystroke beats) is treated as rejected. Defer expensive consumers (preview, save), not `value`. */
+  value: RichDoc;
+  /** `aria-invalid` on the textbox. Field / SettingRow inject it (#568). @default false */
+  invalid?: boolean;
+  /** `aria-required` on the textbox. Field / SettingRow inject it (#568). @default false */
+  required?: boolean;
+  /** Fires with the new document after every edit. */
+  onChange: (doc: RichDoc) => void;
+  /** Non-editable: renders the content read-only (prefer `<RichText>` for pure display). */
+  readOnly?: boolean;
+  /** Shown when the document is empty. */
+  placeholder?: string;
+  /** Focus the editor on mount. */
+  autoFocus?: boolean;
+  /**
+   * Render the built-in formatting toolbar above the editor — Undo/Redo buttons,
+   * mark toggle buttons (bold/italic/underline/strike), a block-type dropdown
+   * (paragraph/headings/quote/code), and bullet/numbered list toggles. The
+   * toolbar dispatches through the same commit path the keyboard uses and
+   * reflects the active marks + current block of the live selection. Default
+   * `false` (keyboard-only). When `readOnly`, the toolbar renders disabled.
+   *
+   * `'auto'` shows the toolbar only when the editor is **focused or non-empty**,
+   * and keeps it shown while the editor's own overlays (the link editor / mention
+   * menu) are open — so opening the link editor on a focused-but-empty composer
+   * doesn't collapse the bar. The editable is NOT remounted as the bar appears or
+   * hides (the bar toggles in a stable shell), so there's no focus/selection loss.
+   * Use it for a compact, focus-gated composer (e.g. a comment box) instead of
+   * hand-rolling the show-on-focus logic and working around overlay focus theft.
+   */
+  toolbar?: boolean | 'auto';
+  /**
+   * Enable `@`-mention autocomplete. Supply `onQuery` to resolve candidates for
+   * the text typed after the trigger (default `@`); the editor renders a floating
+   * combobox and inserts a styled mention chip carrying the chosen item's `id`.
+   * Omit to disable mentions. See {@link MentionsConfig}.
+   */
+  mentions?: MentionsConfig;
+  /**
+   * Turn typed and pasted URLs into links automatically. While typing, a URL is
+   * linked when you type a space after it; on paste, plain-text URLs are linked
+   * (a single bare URL pasted over a selection links the selection). Default
+   * `true`. Set `false` to disable both the type rule and paste autolinking (the
+   * ⌘/Ctrl+K link tool still works). The href is sanitized — only safe schemes
+   * (http/https/`www.`) become links.
+   */
+  autolink?: boolean;
+  /**
+   * Substitute how a link renders. Called per link with `{ href, text }` and the
+   * default `<a>`; return your own node (e.g. a task/member chip) or the
+   * `defaultNode` to keep the standard anchor. A custom node renders as a
+   * non-editable **atomic chip** — the caret steps over it and a single Backspace/
+   * Delete removes the whole link.
+   *
+   * @remarks Render-time only — the model is unchanged, so `toHtml`/`toMarkdown`
+   * still serialize a plain link. Keep it cheap (it runs on every render): don't
+   * do heavy synchronous work or block on the network inside `renderLink`; return
+   * a component that fetches/caches the lookup itself (falling back to
+   * `defaultNode` while loading). Because the chip is atomic and not editable
+   * text, only links your `renderLink` actually replaces become chips — links you
+   * return `defaultNode` for stay plain, editable anchors.
+   */
+  renderLink?: RenderLink;
+  /**
+   * Substitute how an `@`-mention renders. Called per mention with `{ id, label }`
+   * and the default mention span; return your own node (e.g. an interactive member
+   * chip / popover trigger) or the `defaultNode` to keep the standard
+   * non-interactive span. A custom node renders as a non-editable **atomic chip** —
+   * the caret steps over it as a single unit. Composes with `renderLink` (both
+   * usable together).
+   *
+   * @remarks Render-time only — the model is unchanged, so `toHtml`/`toMarkdown`
+   * still serialize the mention mark. Keep it cheap (it runs on every render):
+   * don't do heavy synchronous work or block on the network inside `renderMention`;
+   * return a component that fetches/caches the lookup itself (falling back to
+   * `defaultNode` while loading).
+   */
+  renderMention?: RenderMention;
+  /**
+   * Maximum DISPLAYED height of image attachments, in px. Default: the
+   * `--size-rich-text-image-max-height` token (480px). A taller image shrinks
+   * (width follows, aspect preserved); the resize handle and width slider stop
+   * where the image hits the cap. Render-time only — stored `width`/`height` are
+   * unchanged. Pass the same value to the read-only `<RichText>` so both agree.
+   */
+  imageMaxHeight?: number;
+  /**
+   * Show Notion-style per-block controls: a left gutter that appears on the
+   * hovered/focused block with an insert button (`＋`, adds an empty paragraph
+   * below) and a drag handle (`⠿`) that opens a block menu (Turn into ▸,
+   * Duplicate, Move up/down, Delete). Reordering is subtree-aware for nested
+   * lists. Keyboard: Shift+F10 / the ContextMenu key opens the focused block's
+   * menu; ⌘/Ctrl+⇧↑ / ⌘/Ctrl+⇧↓ move the block; ⌘/Ctrl+D duplicates. Default
+   * `false`. Ignored when `readOnly`. Independent of `toolbar`.
+   */
+  blockControls?: boolean;
+  /**
+   * Enable file upload: a toolbar button (when `toolbar`) and clipboard-file paste.
+   * `onUpload(file)` resolves with where the file landed; images render inline as a
+   * preview, other files as a download chip. Reject `onUpload` to show a retry/remove
+   * error; reject with `new UploadError(message)` to also show that (user-facing,
+   * localized) reason on the block — any other rejection shows only "Upload
+   * failed". `onUploadingChange` fires while any upload is in flight — wire it to your
+   * submit button's disabled state. Validation (size/type) belongs in `onUpload`
+   * (`accept` is only a native-picker hint and is bypassed by paste). Omit to
+   * disable. Ignored when `readOnly`.
+   * When `blockControls` is also on, a ready image attachment can be configured
+   * (alt text, alignment, replace, open/download) via the block menu's
+   * "Configure" item. The width slider appears only for an image that renders as
+   * a preview (a safe, fetchable src — an embed); an uploaded image whose
+   * object-URL src renders as a download chip isn't resizable here. Alignment +
+   * width round-trip through HTML but not Markdown.
+   */
+  upload?: UploadConfig;
+}
+
+function isEmptyDoc(doc: RichDoc): boolean {
+  return doc.blocks.length === 1 && blockLength(doc.blocks[0]) === 0;
+}
+
+/** Toggle `mark` within a `Mark[]` (used to fold a shortcut into pending marks). */
+function toggleInList(marks: Mark[], mark: Mark): Mark[] {
+  return hasMark(marks, mark.type) ? withoutMark(marks, mark.type) : withMark(marks, mark);
+}
+
+/**
+ * Insert `text` at `point` carrying exactly `marks` (staged pending marks). The
+ * span comes from the insert's resulting caret, not `point`: beside a void block
+ * the text lands in a NEW paragraph after it.
+ */
+function insertWithMarks(
+  doc: RichDoc,
+  point: Point,
+  text: string,
+  marks: Mark[],
+): { doc: RichDoc; selection: Range } {
+  const inserted = insertText(doc, point, text);
+  const end = inserted.selection.focus;
+  const span: Range = {
+    anchor: { blockId: end.blockId, offset: end.offset - text.length },
+    focus: end,
+  };
+  return { doc: applyExactMarks(inserted.doc, span, marks), selection: inserted.selection };
+}
+
+/**
+ * Controlled rich-text editor: a contentEditable surface over the in-house engine with marks, lists, links, mentions, uploads and undo/redo.
+ * @see docs/components/RichTextEditor.md
+ */
+export const RichTextEditor = forwardRef<HTMLDivElement, RichTextEditorProps>(
+  function RichTextEditor(
+    {
+      value,
+      onChange,
+      readOnly = false,
+      placeholder,
+      autoFocus,
+      toolbar = false,
+      blockControls = false,
+      mentions,
+      autolink = true,
+      renderLink,
+      renderMention,
+      imageMaxHeight,
+      upload,
+      invalid = false,
+      required = false,
+      className,
+      style,
+      ...rest
+    },
+    ref,
+  ) {
+    const t = useTranslation();
+    const rootRef = useRef<HTMLDivElement | null>(null);
+    const isComposingRef = useRef(false);
+    // Selection to restore after the next model-driven re-render.
+    // `afterVoid`: a void block whose DOM caret goes AFTER its figure (voidDelete's
+    // caretAfterVoid — a spot the model's single void point can't name). Bundled
+    // with the selection so every path that places a caret replaces both at once:
+    // a stale marker can never fire with someone else's selection. A block id, so
+    // it survives a parent that copies the doc in onChange.
+    const pendingSelectionRef = useRef<{ range: Range; afterVoid: string | null } | null>(null);
+    // Which committed docs had their caret after a void — keyed by the exact doc
+    // object history keeps, so undo/redo restore the same side.
+    const caretAfterVoidDocs = useRef(new WeakMap<RichDoc, string>());
+    // Latest props for the native beforeinput listener (avoids stale closures).
+    const latest = useRef({
+      value,
+      onChange,
+      readOnly,
+      autolink,
+      renderLink,
+      upload,
+    });
+    latest.current = {
+      value,
+      onChange,
+      readOnly,
+      autolink,
+      renderLink,
+      upload,
+    };
+    // The synchronous "live" doc — the doc the parent has taken, possibly ahead of
+    // the last render's `value`, so several async upload settles chain off each
+    // other's result instead of all reading a stale `value` (which would make the
+    // last settle clobber the earlier ones). Never an edit the parent hasn't taken
+    // yet (see unconfirmedRef). Re-synced to `value` each render so external
+    // replacements flow in.
+    const liveDocRef = useRef(value);
+    liveDocRef.current = value;
+
+    // Stable getters for the synchronously-latest doc/flags — passed to the
+    // feature hooks so their handlers read current values without re-subscribing
+    // or depending on `latest`'s shape (keeps the handlers' identity stable).
+    const getValue = useCallback(() => latest.current.value, []);
+    const getLiveDoc = useCallback(() => liveDocRef.current, []);
+    const getReadOnly = useCallback(() => latest.current.readOnly, []);
+
+    // Focus state — only consulted by `toolbar="auto"` to gate the bar's visibility.
+    // Focus moving to an editor overlay (the link editor / mention menu, portaled to
+    // <body>) fires a blur, so `focused` flips false there; the `showToolbar`
+    // formula keeps the bar up via the overlay-open term instead.
+    const [focused, setFocused] = useState(false);
+    // True while any toolbar popover is open — it blurs the editable by opening,
+    // which would otherwise unmount the bar and the popover with it.
+    const [toolbarOverlayOpen, setToolbarOverlayOpen] = useState(false);
+    const autoToolbar = toolbar === 'auto';
+
+    // Toolbar state: the live selection (tracked via `selectionchange`) and any
+    // marks staged at a collapsed caret to apply to the next typed character.
+    const [selection, setSelection] = useState<Range | null>(null);
+    const [pendingMarks, setPendingMarks] = useState<Mark[] | null>(null);
+    // Mirror pending marks into a ref so the native beforeinput listener reads
+    // the current value without re-subscribing.
+    const pendingMarksRef = useRef<Mark[] | null>(null);
+    pendingMarksRef.current = pendingMarks;
+    // The collapsed caret where pending marks were staged. Used to clear them
+    // when the caret moves to a different spot (vs. typing at the same point).
+    const pendingAtRef = useRef<Point | null>(null);
+    // The most recent NON-null editor selection. Survives focus moving into a toolbar
+    // popover (e.g. the emoji/search box), where the live selection reads null. Used by
+    // popover-driven inserts so they target where the caret actually was.
+    const lastSelectionRef = useRef<Range | null>(null);
+
+    const setRefs = useCallback(
+      (node: HTMLDivElement | null) => {
+        rootRef.current = node;
+        if (typeof ref === 'function') ref(node);
+        else if (ref) ref.current = node;
+      },
+      [ref],
+    );
+
+    const controlsOn = blockControls && !readOnly;
+    // Whether the stable `.shell` wrapper is rendered (a toolbar mode is active or
+    // block controls need the anchor). The image resize handle anchors into the
+    // shell, so its hover tracking + element are gated on this. Declared up here
+    // (vs. near the shell render) so the image-hover effect below can depend on it.
+    const usesShell = toolbar === true || autoToolbar || controlsOn;
+    // The same gate the mention menu uses — drives both `useMention`'s `enabled`
+    // and the consolidated selectionchange listener's mention fan-out below.
+    const mentionsEnabled = !!mentions && !readOnly;
+    const shellRef = useRef<HTMLDivElement | null>(null);
+    // Active block = hover wins, else the caret block (keyboard / after the mouse
+    // leaves). Split so clearing hover on editor-leave never wipes the caret target.
+    const [hoverBlockId, setHoverBlockId] = useState<string | null>(null);
+    const [caretBlockId, setCaretBlockId] = useState<string | null>(null);
+    const activeBlockId = hoverBlockId ?? caretBlockId;
+    const [blockMenuOpen, setBlockMenuOpen] = useState(false);
+    // Mirror the open state into a ref so the hover listener can read it without
+    // re-subscribing: while the menu is open, hovering another block must NOT move
+    // the active block (the menu's actions are bound to it — moving it would make
+    // a click act on the wrong block).
+    const blockMenuOpenRef = useRef(false);
+    blockMenuOpenRef.current = blockMenuOpen;
+    // Set by RichTextBlockControls' onDraggingChange. While a block drag is in
+    // progress the active block must not change (it IS the block being dragged), so
+    // the hover handlers below read this ref and bail — mirroring blockMenuOpenRef.
+    const draggingRef = useRef(false);
+    // Stable setter for draggingRef — passed to the image resizer so its memoized
+    // shell doesn't re-render every keystroke on a fresh inline lambda. Used by the
+    // resizer's OWN drag: it sets draggingRef only (NOT blockDragging), so a resize
+    // never hides the handle mid-drag.
+    const setDragging = useCallback((d: boolean) => {
+      draggingRef.current = d;
+    }, []);
+    // The previewable image currently under the pointer → the resize-handle target.
+    // Tracked independently of blockControls/upload/active-block so the handle shows
+    // for ANY previewable image on hover (see the image-hover effect below).
+    const [hoveredImageId, setHoveredImageId] = useState<string | null>(null);
+    // True while a blockControls reorder drag is in flight. Hides the image resize
+    // handle (it can't follow the block's in-place reflow); it reappears at the drop.
+    const [blockDragging, setBlockDragging] = useState(false);
+    // Block-drag report (passed to RichTextBlockControls): set draggingRef so the
+    // hover/caret tracking bails AND set blockDragging so the image handle hides.
+    // Separate from setDragging (which the resizer's own drag uses) on purpose.
+    const onBlockDraggingChange = useCallback((d: boolean) => {
+      draggingRef.current = d;
+      setBlockDragging(d);
+    }, []);
+
+    // Resolve the [data-block-id] of the block element containing a DOM node.
+    const blockIdFromNode = useCallback((node: Node | null): string | null => {
+      let el: HTMLElement | null =
+        node instanceof HTMLElement ? node : (node?.parentElement ?? null);
+      while (el && el !== rootRef.current) {
+        if (el.hasAttribute('data-block-id')) return el.getAttribute('data-block-id');
+        el = el.parentElement;
+      }
+      return null; // reached the root (or ran out of ancestors) — no block
+    }, []);
+
+    // Resolve the [data-block-id] of the previewable-image FIGURE containing a DOM
+    // node, or null. A previewable image renders `<figure data-block-id><img></figure>`;
+    // a non-preview file chip renders `<figure data-block-id><a></figure>` — so a
+    // figure that contains an <img> = a previewable image. DOM-based (no `value`
+    // dep), so it stays stable; the editor re-validates the id against the model.
+    const imageFigureIdAt = useCallback((node: Node | null): string | null => {
+      let el: HTMLElement | null =
+        node instanceof HTMLElement ? node : (node?.parentElement ?? null);
+      while (el && el !== rootRef.current) {
+        if (
+          el.tagName === 'FIGURE' &&
+          el.hasAttribute('data-block-id') &&
+          el.querySelector('img')
+        ) {
+          return el.getAttribute('data-block-id');
+        }
+        el = el.parentElement;
+      }
+      return null;
+    }, []);
+
+    // The block whose vertical band contains viewport-y `clientY`, or null. Used to
+    // resolve a hover over the gutter/padding column (where there is no block element
+    // under the pointer) to the row beside it. Block elements are in document order =
+    // top-to-bottom, so we can stop once a block starts below the pointer; among the
+    // blocks that contain the pointer the LAST in document order is the deepest (a
+    // nested list item comes after — and sits inside — its parent), matching how a
+    // direct hover resolves to the innermost block. Reads a layout rect per block up
+    // to the pointer's row — an accepted cost: the caller only invokes this for the
+    // narrow no-block-under-pointer case (the gutter/padding column), never the hot
+    // text-hover path, so there's no need to cache rects or rAF-throttle.
+    const blockAtPointerY = useCallback((root: HTMLElement, clientY: number): string | null => {
+      let found: string | null = null;
+      for (const el of root.querySelectorAll<HTMLElement>('[data-block-id]')) {
+        const box = el.getBoundingClientRect();
+        if (box.top > clientY) break;
+        if (clientY <= box.bottom) found = el.getAttribute('data-block-id');
+      }
+      return found;
+    }, []);
+
+    const historyRef = useRef<History>(historyReset({ doc: value, selection: null }));
+    // Timestamp of the last ⌘Z/⌘⇧Z/⌘Y keydown — lets the beforeinput net skip the
+    // historyUndo/historyRedo event that a keydown ALSO emits (already handled),
+    // while still honoring a menu/trackpad undo that emits no keydown.
+    const historyKeyAtRef = useRef(0);
+    const [canUndo, setCanUndo] = useState(false);
+    const [canRedo, setCanRedo] = useState(false);
+    const syncHistoryFlags = useCallback(() => {
+      setCanUndo(historyCanUndo(historyRef.current));
+      setCanRedo(historyCanRedo(historyRef.current));
+    }, []);
+
+    // The last doc handed to onChange that `value` hasn't become yet, with the
+    // history to restore if it never does. flushSync renders a synchronously-
+    // accepting parent before onChange returns, so most edits never land here;
+    // one that does was either REJECTED or is still on its way (a parent storing
+    // it in startTransition / useDeferredValue — tolerated for a single edit,
+    // discouraged; see the docs). Resolved by whichever comes
+    // first: that doc arriving as `value` (accepted late — keep everything), a
+    // different `value` arriving (rejected — the layout effect drops its pending
+    // caret), or the next edit / undo / settle (reconcile() rolls its history
+    // entry back). Meanwhile the live doc stays the SHOWN one, so async upload
+    // settles never build on an edit the parent may have refused.
+    const unconfirmedRef = useRef<{ doc: RichDoc; prevHistory: History } | null>(null);
+
+    // Every commit path calls this FIRST — before writing pendingSelectionRef —
+    // since a rollback also drops the refused edit's pending caret.
+    const reconcile = useCallback(() => {
+      const u = unconfirmedRef.current;
+      unconfirmedRef.current = null;
+      if (u && latest.current.value !== u.doc) {
+        historyRef.current = u.prevHistory;
+        syncHistoryFlags();
+        // Its caret too — a caller that returns early (an empty undo/redo) would
+        // otherwise leave it for some unrelated re-render to write.
+        pendingSelectionRef.current = null;
+      }
+    }, [syncHistoryFlags]);
+
+    const emit = useCallback((doc: RichDoc, prevHistory: History) => {
+      const before = latest.current.value;
+      liveDocRef.current = doc;
+      try {
+        flushSync(() => latest.current.onChange(doc));
+      } finally {
+        // `finally`: an onChange that throws counts as not (yet) accepted too.
+        if (latest.current.value === before) {
+          unconfirmedRef.current = { doc, prevHistory };
+          liveDocRef.current = before;
+        }
+      }
+    }, []);
+
+    const commit = useCallback(
+      (
+        result: { doc: RichDoc; selection: Range },
+        kind: EditKind = 'other',
+        options?: {
+          /**
+           * Keep the DOM selection as-is — do NOT writeSelection on the re-render.
+           * Used by edits applied from a floating UI that owns focus (e.g. the ⠿
+           * block-color submenu): writing `result.selection` would both yank focus
+           * out of the open menu and visibly select the whole block. `result.selection`
+           * is still recorded in history so undo lands somewhere sensible.
+           */
+          keepSelection?: boolean;
+          /** Place the DOM caret AFTER this void block's figure on the re-render. */
+          caretAfterVoid?: string;
+        },
+      ) => {
+        // No-op transforms (e.g. Backspace at the very start of the document)
+        // return the SAME doc reference — skip so we don't fire onChange or leave a
+        // stale pending selection that React would never consume (no re-render).
+        if (result.doc === latest.current.value) return;
+        if (options?.caretAfterVoid)
+          caretAfterVoidDocs.current.set(result.doc, options.caretAfterVoid);
+        reconcile();
+        const prevHistory = historyRef.current;
+        historyRef.current = historyRecord(
+          historyRef.current,
+          { doc: result.doc, selection: result.selection },
+          kind,
+          Date.now(),
+        );
+        syncHistoryFlags();
+        // Every commit path writes pendingSelectionRef (null = "place no caret on
+        // this render"), so a pending selection left by a commit the parent
+        // rejected can never fire on a later, unrelated render.
+        pendingSelectionRef.current = options?.keepSelection
+          ? null
+          : { range: result.selection, afterVoid: options?.caretAfterVoid ?? null };
+        emit(result.doc, prevHistory);
+      },
+      [syncHistoryFlags, emit, reconcile],
+    );
+
+    // Live-resize commit path for attachment width drags (used by
+    // useAttachmentConfig's onConfigWidth and the image resizer). Records ONE
+    // coalescing 'resize' history entry per drag (whole drag = one undo step),
+    // clears the pending selection so no caret is placed (the slider/handle keeps
+    // focus mid-drag — a writeSelection into the editable would yank it), and chains off
+    // `liveDocRef` so rapid moves before a re-render stack on each other. The
+    // no-op guard skips an unchanged doc (same width). This stays in the editor
+    // so the history coupling is isolated from the hook.
+    const commitResizeLive = useCallback(
+      (doc: RichDoc) => {
+        if (doc === liveDocRef.current) return;
+        reconcile();
+        pendingSelectionRef.current = null; // the slider/handle keeps focus
+        const prevHistory = historyRef.current;
+        historyRef.current = historyRecord(
+          historyRef.current,
+          { doc, selection: historyRef.current.present.selection },
+          'resize',
+          Date.now(),
+        );
+        syncHistoryFlags();
+        emit(doc, prevHistory);
+      },
+      [syncHistoryFlags, emit, reconcile],
+    );
+
+    // Like commit, but records NO history entry — used for async upload settles so
+    // Undo never steps through an upload resolving. Preserves the caret across the
+    // model-driven re-render by re-pinning the current selection (or placing none
+    // when the selection is outside the editor), and keeps the
+    // history's `present` snapshot in sync with the new doc (without pushing a
+    // past/future entry) so the layout effect's `value !== present.doc` external-
+    // replacement heuristic doesn't mistake a settle for a doc swap and reset undo.
+    const commitSilent = useCallback(
+      (doc: RichDoc) => {
+        if (doc === latest.current.value) return;
+        reconcile();
+        const root = rootRef.current;
+        const sel = root ? readSelection(root) : null;
+        pendingSelectionRef.current = sel ? { range: sel, afterVoid: null } : null;
+        const prevHistory = historyRef.current;
+        historyRef.current = {
+          ...historyRef.current,
+          present: { doc, selection: sel ?? historyRef.current.present.selection },
+        };
+        emit(doc, prevHistory);
+      },
+      [emit, reconcile],
+    );
+
+    const uploadOn = !!upload && !readOnly;
+    // A failure usually lands while the user keeps typing elsewhere in the doc,
+    // so the block's visible text alone is never heard: announce it (Hard rule 10).
+    const [uploadFailure, setUploadFailure] = useState<{ name: string; reason?: string } | null>(
+      null,
+    );
+    const uploader = useUpload({
+      config: upload ?? { onUpload: async () => ({ url: '' }) },
+      getValue: () => liveDocRef.current,
+      applyInsert: (doc) => {
+        const root = rootRef.current;
+        const sel = (root ? readSelection(root) : null) ?? {
+          anchor: { blockId: liveDocRef.current.blocks[0].id, offset: 0 },
+          focus: { blockId: liveDocRef.current.blocks[0].id, offset: 0 },
+        };
+        commit({ doc, selection: sel }, 'other');
+      },
+      applySettle: commitSilent,
+      getCaret: () =>
+        (rootRef.current ? readSelection(rootRef.current)?.anchor : undefined) ?? {
+          blockId: liveDocRef.current.blocks[0].id,
+          offset: 0,
+        },
+      // Cap a freshly-uploaded image's initial width to the editor content width
+      // (mirrors the resizer's maxWidth measurement). `0` when unmounted → no cap.
+      getContentWidth: () => rootRef.current?.getBoundingClientRect().width ?? 0,
+      onFailureChange: setUploadFailure,
+    });
+    // The paste/click handlers close over a stale `uploader`; mirror it in a ref so
+    // we read the current one without re-subscribing the native paste listener.
+    const uploaderRef = useRef(uploader);
+    uploaderRef.current = uploader;
+    // The toolbar's Add-file button clicks this; the input is rendered by the shell.
+    const uploadInputRef = useRef<HTMLInputElement>(null);
+
+    // Drop any caret-staged pending mark — the doc + caret are about to change,
+    // so a mark staged at the old caret must not bleed into the next typed text.
+    const clearPendingMarks = useCallback(() => {
+      setPendingMarks(null);
+      pendingMarksRef.current = null; // ahead of the re-render, for same-tick events
+      pendingAtRef.current = null;
+    }, []);
+
+    // Consume the staged pending marks if they were staged at `point`; marks staged
+    // anywhere else are dropped. The selectionchange cleanup runs only with a
+    // toolbar, so a keyboard-only editor relies on this to keep a ⌘B staged
+    // elsewhere from leaking into text typed here.
+    const takePendingAt = useCallback(
+      (point: Point): Mark[] | null => {
+        const pend = pendingMarksRef.current;
+        const at = pendingAtRef.current;
+        if (!pend) return null;
+        clearPendingMarks();
+        return at && at.blockId === point.blockId && at.offset === point.offset ? pend : null;
+      },
+      [clearPendingMarks],
+    );
+
+    // A voidDelete result that only moves the caret returns the SAME doc, which
+    // commit() skips as a no-op — apply its selection directly instead.
+    const applyVoidDelete = useCallback(
+      (result: ReturnType<typeof voidDelete>) => {
+        if (!result) return;
+        if (result.doc === latest.current.value) {
+          if (rootRef.current) writeSelection(rootRef.current, result.selection);
+          return;
+        }
+        commit(result, 'delete', {
+          caretAfterVoid: result.caretAfterVoid ? result.selection.anchor.blockId : undefined,
+        });
+      },
+      [commit],
+    );
+
+    const onUndo = useCallback(() => {
+      reconcile();
+      const h = historyRef.current;
+      if (!historyCanUndo(h)) return;
+      const next = historyUndo(h);
+      historyRef.current = next;
+      syncHistoryFlags();
+      clearPendingMarks();
+      pendingSelectionRef.current = next.present.selection && {
+        range: next.present.selection,
+        afterVoid: caretAfterVoidDocs.current.get(next.present.doc) ?? null,
+      };
+      emit(next.present.doc, h);
+    }, [syncHistoryFlags, clearPendingMarks, emit, reconcile]);
+
+    const onRedo = useCallback(() => {
+      reconcile();
+      const h = historyRef.current;
+      if (!historyCanRedo(h)) return;
+      const next = historyRedo(h);
+      historyRef.current = next;
+      syncHistoryFlags();
+      clearPendingMarks();
+      pendingSelectionRef.current = next.present.selection && {
+        range: next.present.selection,
+        afterVoid: caretAfterVoidDocs.current.get(next.present.doc) ?? null,
+      };
+      emit(next.present.doc, h);
+    }, [syncHistoryFlags, clearPendingMarks, emit, reconcile]);
+
+    const insertMentionItem = useCallback(
+      (
+        blockId: string,
+        range: { from: number; to: number },
+        trigger: string,
+        item: MentionItem,
+      ) => {
+        commit(insertMention(latest.current.value, blockId, range, trigger, item), 'other');
+        clearPendingMarks();
+      },
+      [commit, clearPendingMarks],
+    );
+
+    const mention = useMention({
+      enabled: mentionsEnabled,
+      rootRef,
+      doc: value,
+      trigger: mentions?.trigger ?? '@',
+      onQuery: mentions?.onQuery,
+      onInsert: insertMentionItem,
+    });
+    const recomputeMention = mention.recompute;
+
+    // Shared by the keyboard shortcut and the toolbar: with a collapsed caret,
+    // stage a pending mark for the next typed text (remembering where); with a
+    // selection, toggle the mark over it now.
+    const stageOrToggleMark = useCallback(
+      (range: Range, mark: Mark) => {
+        if (isCollapsed(range)) {
+          pendingAtRef.current = range.anchor;
+          setPendingMarks((prev) =>
+            toggleInList(prev ?? marksForTypedText(latest.current.value, range.anchor), mark),
+          );
+        } else {
+          commit(runToggleMark(latest.current.value, range, mark));
+        }
+      },
+      [commit],
+    );
+
+    // Color sibling of stageOrToggleMark: with a collapsed caret, stage the color
+    // as a pending mark for the next typed text (replacing any pending color of the
+    // same type, or clearing it when `key` is null); with a selection, set it now.
+    const stageOrSetColor = useCallback(
+      (range: Range, type: 'textColor' | 'bgColor', key: string | null) => {
+        if (isCollapsed(range)) {
+          pendingAtRef.current = range.anchor;
+          setPendingMarks((prev) => {
+            const base = (prev ?? marksForTypedText(latest.current.value, range.anchor)).filter(
+              (m) => m.type !== type,
+            );
+            return key ? [...base, { type, color: key }] : base;
+          });
+        } else {
+          // setColorMark returns a bare RichDoc (a color change never moves the
+          // caret), so wrap it for commit and keep the existing selection.
+          commit({ doc: setColorMark(latest.current.value, range, type, key), selection: range });
+        }
+      },
+      [commit],
+    );
+
+    // Toolbar color dispatch — read the live selection (falling back to the most
+    // recent one, which survives the Popover stealing focus) and route through the
+    // shared color path, then restore focus so typing continues after the pick.
+    const onSetColor = useCallback(
+      (type: 'textColor' | 'bgColor', key: string | null) => {
+        const root = rootRef.current;
+        const range = (root ? readSelection(root) : null) ?? lastSelectionRef.current;
+        if (range) {
+          stageOrSetColor(range, type, key);
+          root?.focus();
+        }
+      },
+      [stageOrSetColor],
+    );
+
+    // Link editor: open-state + apply/remove/cancel handlers (see useLinkEditor).
+    // The toolbar's `linkActive` derivation and the `<RichTextLinkEditor>` render
+    // stay in this file — they need the live selection / render scope.
+    const { linkEditor, openLinkEditor, onLinkApply, onLinkRemove, onLinkCancel } = useLinkEditor({
+      rootRef,
+      commit,
+      getValue,
+      getReadOnly,
+    });
+
+    // Restore the caret/selection after a model-driven re-render.
+    // The `value` the layout effect last saw — it also re-runs on mentions/readOnly
+    // changes, which must not be mistaken for a new value arriving.
+    const seenValueRef = useRef(value);
+    useLayoutEffect(() => {
+      const valueChanged = value !== seenValueRef.current;
+      seenValueRef.current = value;
+      // External value replacement (parent sets a wholly different doc) — reset
+      // history so Undo can't travel back into the old document's timeline. Only
+      // when `value` actually changed: during a pending (unconfirmed) edit,
+      // present.doc runs ahead of an unchanged value.
+      if (valueChanged && value !== historyRef.current.present.doc) {
+        historyRef.current = historyReset({ doc: value, selection: null });
+        syncHistoryFlags();
+        // A programmatic value swap fires no user `selectionchange`, so the
+        // consolidated listener below never re-runs the mention menu for it.
+        // Recompute here so an external swap updates/closes the menu. Internal
+        // commits keep `present.doc === value`, so they DON'T reach this branch —
+        // no per-keystroke double-recompute is reintroduced.
+        if (mentionsEnabled) {
+          const r = rootRef.current;
+          recomputeMention(r ? readSelection(r) : null);
+        }
+      }
+      const root = rootRef.current;
+      // A pending edit's doc arriving late = accepted (keep its caret); any OTHER
+      // value arriving first = it was rejected, so its caret must not fire here.
+      const unconfirmed = unconfirmedRef.current;
+      if (unconfirmed && valueChanged) {
+        if (value !== unconfirmed.doc) pendingSelectionRef.current = null;
+        unconfirmedRef.current = null;
+      }
+      const pending = pendingSelectionRef.current;
+      // Not while an edit is still awaiting acceptance: its caret belongs to a doc
+      // the DOM doesn't show yet (written once that value arrives, or dropped).
+      if (root && pending && !unconfirmedRef.current) {
+        writeSelection(root, pending.range);
+        pendingSelectionRef.current = null;
+        // Only with the selection it was bundled with (a commit / undo / redo) —
+        // never on an unrelated re-run such as a readOnly toggle.
+        const afterVoid = pending.afterVoid;
+        const fig = afterVoid
+          ? root.querySelector(`[data-block-id="${CSS.escape(afterVoid)}"]`)
+          : null;
+        if (fig) {
+          // At the END of the figure's content — where Chrome's own Ctrl+End puts
+          // it. A root-level caret after a trailing contentEditable=false figure
+          // has no visible position: Chrome snaps it to the start of the editor.
+          const r = fig.ownerDocument.createRange();
+          r.setStart(fig, fig.childNodes.length);
+          r.collapse(true);
+          const sel = fig.ownerDocument.getSelection();
+          sel?.removeAllRanges();
+          sel?.addRange(r);
+        }
+      }
+    }, [value, syncHistoryFlags, mentionsEnabled, recomputeMention]);
+
+    // Native beforeinput (React's onBeforeInput is NOT the modern beforeinput —
+    // it's a legacy textInput polyfill that carries no `inputType`).
+    useEffect(() => {
+      const root = rootRef.current;
+      if (!root) return;
+      const onBeforeInput = (e: InputEvent) => {
+        const { value: doc, readOnly: ro, autolink: autolinkOn, renderLink: rl } = latest.current;
+        if (ro || isComposingRef.current) return;
+        // Undo/redo via beforeinput. Always preventDefault so the browser's native
+        // contentEditable undo never mutates the DOM under the controlled model.
+        // A ⌘Z/⌘⇧Z/⌘Y keydown ALSO emits a paired historyUndo/historyRedo here —
+        // the keydown handler already ran onUndo/onRedo, so skip that one (within a
+        // short window of the keydown). A menu/trackpad undo emits no keydown, so it
+        // falls through and is honored here.
+        if (e.inputType === 'historyUndo' || e.inputType === 'historyRedo') {
+          e.preventDefault();
+          if (Date.now() - historyKeyAtRef.current < 100) return;
+          if (e.inputType === 'historyUndo') onUndo();
+          else onRedo();
+          return;
+        }
+        const range = readSelection(root);
+        if (!range) {
+          // Unmappable selection: never cede an editing input to the browser —
+          // an un-prevented default insert/delete mutates the contentEditable
+          // DOM outside the model (permanent DOM/model divergence, #321). A
+          // dropped keystroke is recoverable; a future resolver bug surfaces
+          // as dropped keystrokes instead of DOM corruption — acceptable.
+          if (e.inputType.startsWith('insert') || e.inputType.startsWith('delete'))
+            e.preventDefault();
+          return;
+        }
+        // Markdown block input rules: a marker + space at the start of a paragraph
+        // converts the block (e.g. "# " → heading, "- " → bullet). The space is
+        // consumed; one commit → one undo step (⌘Z reverts the conversion).
+        if (e.inputType === 'insertText' && e.data === ' ' && isCollapsed(range)) {
+          const block = doc.blocks.find((b) => b.id === range.anchor.blockId);
+          if (block) {
+            const before = runsText(block.inlines).slice(0, range.anchor.offset);
+            const match = matchBlockRule(block.type, before, ' ');
+            if (match) {
+              e.preventDefault();
+              clearPendingMarks();
+              commit(applyBlockRule(doc, block.id, match), 'other');
+              return;
+            }
+          }
+        }
+        // Autolink on type: typing a space after a URL links the URL AND inserts the
+        // space — both in one commit (one undo step). `applyTypeAutolink` inserts the
+        // boundary first (so it stays OUTSIDE the link) and links only the URL. Skips
+        // when the caret is already inside a link.
+        if (
+          autolinkOn !== false &&
+          e.inputType === 'insertText' &&
+          e.data === ' ' &&
+          isCollapsed(range)
+        ) {
+          const linked = applyTypeAutolink(doc, range.anchor, e.data);
+          if (linked) {
+            e.preventDefault();
+            clearPendingMarks();
+            commit(linked, 'type');
+            return;
+          }
+        }
+        // Atomic delete: a Backspace just after (or Delete just before) a link that
+        // `renderLink` resolves to a custom chip removes the whole link in one step.
+        // `isResolved` probes `renderLink` with a stable fallback sentinel: a custom
+        // return (chip) is `!== FALLBACK_SENTINEL`; declining returns the sentinel.
+        if (
+          rl &&
+          (e.inputType === 'deleteContentBackward' || e.inputType === 'deleteContentForward') &&
+          isCollapsed(range)
+        ) {
+          const dir = e.inputType === 'deleteContentBackward' ? 'backward' : 'forward';
+          const isResolved = (href: string) =>
+            rl({ href, text: href }, FALLBACK_SENTINEL) !== FALLBACK_SENTINEL;
+          const delRange = atomicLinkDeleteRange(doc, range.anchor, dir, isResolved);
+          if (delRange) {
+            e.preventDefault();
+            clearPendingMarks();
+            commit(deleteRange(doc, delRange), 'delete');
+            return;
+          }
+        }
+        // Delete/Backspace beside a void: the model has one position per void, so
+        // the DOM side decides (see voidDelete) — never delete it from the wrong side.
+        if (/^delete.*(Backward|Forward)$/.test(e.inputType) && isCollapsed(range)) {
+          const vside = voidCaretSide(root, range.anchor.blockId);
+          if (vside) {
+            e.preventDefault();
+            const dir = /Backward$/.test(e.inputType) ? 'backward' : 'forward';
+            applyVoidDelete(voidDelete(doc, range.anchor.blockId, vside.side, dir));
+            return;
+          }
+        }
+        // Pending marks: a mark toggled at a collapsed caret applies to the next
+        // text typed at that same caret (takePendingAt drops it anywhere else).
+        const pend = takePendingAt(range.anchor);
+        if (pend && e.inputType === 'insertText' && isCollapsed(range) && e.data) {
+          e.preventDefault();
+          commit(insertWithMarks(doc, range.anchor, e.data, pend), 'type');
+          return;
+        }
+        const data = e.data ?? e.dataTransfer?.getData('text/plain') ?? null;
+        const result = applyInput(doc, range, e.inputType, data);
+        if (result === null) {
+          // Unsupported (incl. format* from ⌘B) — stop the browser editing, no
+          // model change. Marks are handled in onKeyDown to avoid a double-toggle.
+          if (e.inputType.startsWith('format')) e.preventDefault();
+          return;
+        }
+        e.preventDefault();
+        const kind: EditKind =
+          e.inputType === 'insertText' ||
+          e.inputType === 'insertCompositionText' ||
+          e.inputType === 'insertReplacementText'
+            ? 'type'
+            : e.inputType.startsWith('delete')
+              ? 'delete'
+              : 'other';
+        commit(result, kind);
+      };
+      root.addEventListener('beforeinput', onBeforeInput);
+      return () => root.removeEventListener('beforeinput', onBeforeInput);
+    }, [commit, onUndo, onRedo, takePendingAt, clearPendingMarks, applyVoidDelete]);
+
+    // Rich paste: when the clipboard carries HTML, parse it into the model and
+    // splice it at the selection. No usable HTML → if autolink is on and the
+    // plain text carries a URL, linkify it; otherwise don't preventDefault, so the
+    // native beforeinput path inserts text/plain (unchanged behavior).
+    useEffect(() => {
+      const root = rootRef.current;
+      if (!root) return;
+      const onPaste = (e: ClipboardEvent) => {
+        if (latest.current.readOnly) return;
+        // File paste (images/files from the clipboard) → upload. Takes priority
+        // over HTML/URL paste. Gated on `upload` being configured.
+        if (latest.current.upload && !latest.current.readOnly) {
+          const files = Array.from(e.clipboardData?.files ?? []);
+          if (files.length > 0) {
+            e.preventDefault();
+            uploaderRef.current.uploadFiles(files);
+            return;
+          }
+        }
+        const html = e.clipboardData?.getData('text/html');
+        if (html && html.trim()) {
+          const range = readSelection(root);
+          if (!range) return;
+          const fragment = fromHtml(html);
+          if (isEmptyDoc(fragment)) return;
+          e.preventDefault();
+          commit(insertFragment(latest.current.value, range, fragment));
+          return;
+        }
+        // No usable HTML — autolink plain-text URLs.
+        if (latest.current.autolink === false) return;
+        const plain = e.clipboardData?.getData('text/plain');
+        if (!plain || !plain.trim()) return;
+        const runs = linkifyRuns(plain);
+        const hasLink = runs.some((r) => r.marks.some((m) => m.type === 'link'));
+        if (!hasLink) return; // no URL → let the native path insert the text
+        const range = readSelection(root);
+        if (!range) return;
+        const trimmed = plain.trim();
+        const whole = findUrl(trimmed);
+        // A single bare URL pasted over a selection → link the selection in place.
+        if (!isCollapsed(range) && whole && whole.start === 0 && whole.end === trimmed.length) {
+          e.preventDefault();
+          commit(setLink(latest.current.value, range, trimmed));
+          return;
+        }
+        // Otherwise splice a one-paragraph fragment of linkified runs.
+        const fragment: RichDoc = {
+          blocks: [{ id: nextId(), type: 'paragraph', inlines: runs }],
+        };
+        e.preventDefault();
+        commit(insertFragment(latest.current.value, range, fragment));
+      };
+      root.addEventListener('paste', onPaste);
+      return () => root.removeEventListener('paste', onPaste);
+    }, [commit]);
+
+    useEffect(() => {
+      if (autoFocus) rootRef.current?.focus();
+    }, [autoFocus]);
+
+    // ONE selectionchange subscription shared by the toolbar, block-controls caret
+    // tracking, and the mention menu. A caret move (incl. every keystroke, which
+    // moves the caret) reads the model selection ONCE here and fans it out, instead
+    // of three independent listeners each re-walking the DOM via their own
+    // readSelection. Only subscribed when at least one consumer needs it.
+    useEffect(() => {
+      const toolbarOn = toolbar && !readOnly;
+      if (!toolbarOn && !controlsOn && !mentionsEnabled) return;
+      const onSelChange = () => {
+        const root = rootRef.current;
+        const sel = root ? readSelection(root) : null;
+        if (toolbarOn) {
+          setSelection(sel);
+          if (sel != null) lastSelectionRef.current = sel;
+          // Abandon pending marks if the caret left its staged point (the user
+          // moved the caret or made a selection instead of typing there).
+          const pend = pendingMarksRef.current;
+          const stagedAt = pendingAtRef.current;
+          const sameSpot =
+            sel != null &&
+            isCollapsed(sel) &&
+            stagedAt != null &&
+            sel.anchor.blockId === stagedAt.blockId &&
+            sel.anchor.offset === stagedAt.offset;
+          if (pend && !sameSpot) {
+            clearPendingMarks();
+          }
+        }
+        if (controlsOn) {
+          // Caret → active block (keyboard users get a gutter target too). Reads the
+          // NATIVE selection's anchorNode directly (not the model `sel` above): a
+          // root-level caret beside a void block resolves to no data-block-id here,
+          // leaving the active block unchanged — the original behavior, preserved.
+          const domSel = root?.ownerDocument.getSelection();
+          if (domSel && root && domSel.anchorNode && root.contains(domSel.anchorNode)) {
+            const id = blockIdFromNode(domSel.anchorNode);
+            if (id) setCaretBlockId(id);
+          }
+        }
+        if (mentionsEnabled) recomputeMention(sel);
+      };
+      document.addEventListener('selectionchange', onSelChange);
+      return () => document.removeEventListener('selectionchange', onSelChange);
+    }, [
+      toolbar,
+      readOnly,
+      controlsOn,
+      mentionsEnabled,
+      blockIdFromNode,
+      recomputeMention,
+      clearPendingMarks,
+    ]);
+
+    // Initial mention computation: on mount, when mentions toggle on, or when the
+    // trigger changes. The selectionchange listener above covers caret moves AND
+    // typing (a typed char commits → writeSelection re-sets the DOM selection →
+    // selectionchange fires), so this deliberately omits `value` from its deps —
+    // depending on it would recompute a second time per keystroke, the very
+    // redundancy this consolidation removes.
+    useEffect(() => {
+      if (!mentionsEnabled) return;
+      const root = rootRef.current;
+      recomputeMention(root ? readSelection(root) : null);
+    }, [mentionsEnabled, mentions?.trigger, recomputeMention]);
+
+    // Hover tracking (mouse). Listens on the SHELL (which wraps both the editable and
+    // the gutter) so reaching from a block onto its controls keeps them alive:
+    // `mouseover` over the gutter finds no `data-block-id` on the walk up (the gutter
+    // isn't inside the editable), so blockIdFromNode returns null and hoverBlockId is
+    // left unchanged — keeping the controls alive as you reach for them. `mouseleave`
+    // on the shell fires only when the pointer truly leaves the editor → clear hover.
+    useEffect(() => {
+      if (!controlsOn) return;
+      const shell = shellRef.current;
+      if (!shell) return;
+      const onOver = (e: MouseEvent) => {
+        // Don't let hover steal the active block while the menu is open (its actions
+        // are bound to the active block) or while a drag is in progress.
+        if (blockMenuOpenRef.current || draggingRef.current) return;
+        const id = blockIdFromNode(e.target as Node);
+        if (id) setHoverBlockId(id);
+      };
+      // The gutter (＋ / ⠿) and the reserved left column are NOT inside the editable,
+      // so `mouseover` there resolves to no block id and would leave the controls
+      // stranded on whichever row was last hovered. Track the pointer's height while
+      // it's over that controls column and activate the row at that height — so
+      // hovering the controls area reveals/follows the adjacent row's controls.
+      // Scoped to the no-block case so block-targeted hovers stay on the cheap
+      // `mouseover` path; `mousemove` (not `mouseover`) is needed because sliding
+      // within the column fires no new `mouseover`.
+      // blockAtPointerY is an O(blocks) getBoundingClientRect scan, so resolve the
+      // gutter-column hover at most once per animation frame: capture the latest move
+      // on every event, but coalesce the actual resolution into a single rAF.
+      let moveRaf = 0;
+      let lastMove: { clientY: number; target: EventTarget | null } | null = null;
+      const onMove = (e: MouseEvent) => {
+        if (blockMenuOpenRef.current || draggingRef.current) return;
+        // capture the latest move; resolve at most once per frame
+        lastMove = { clientY: e.clientY, target: e.target };
+        if (moveRaf) return;
+        moveRaf = requestAnimationFrame(() => {
+          moveRaf = 0;
+          const m = lastMove;
+          if (!m) return;
+          const root = rootRef.current;
+          if (!root) return;
+          // Only the editable's OWN area (its reserved left column / padding). The gutter
+          // overlay is a sibling of the editable, not a descendant, so this skips it —
+          // its buttons stay alive via onOver's leave-unchanged path, and we never fight
+          // the controls the pointer is aiming for.
+          if (!root.contains(m.target as Node)) return;
+          if (blockIdFromNode(m.target as Node)) return; // a real block hover — onOver has it
+          const id = blockAtPointerY(root, m.clientY);
+          if (id) setHoverBlockId(id);
+        });
+      };
+      const onLeave = () => {
+        // Keep the active block while the menu is open or a drag is mid-flight.
+        if (blockMenuOpenRef.current || draggingRef.current) return;
+        setHoverBlockId(null);
+      };
+      shell.addEventListener('mouseover', onOver);
+      shell.addEventListener('mousemove', onMove);
+      shell.addEventListener('mouseleave', onLeave);
+      return () => {
+        shell.removeEventListener('mouseover', onOver);
+        shell.removeEventListener('mousemove', onMove);
+        shell.removeEventListener('mouseleave', onLeave);
+        if (moveRaf) cancelAnimationFrame(moveRaf);
+      };
+    }, [controlsOn, blockIdFromNode, blockAtPointerY]);
+
+    // Image-hover tracking (mouse) → drives the resize handle. Independent of the
+    // blockControls hover/caret tracking above so the handle shows for ANY
+    // previewable image, even in a toolbar-only composer (no blockControls/upload).
+    // Gated on `usesShell` because the handle anchors into the shell — without a
+    // shell there's nowhere to position it. Listens on the SHELL so reaching from
+    // the image onto the handle (a shell child, outside the editable) keeps it alive.
+    useEffect(() => {
+      if (readOnly || !usesShell) return;
+      const shell = shellRef.current;
+      if (!shell) return;
+      const onOver = (e: MouseEvent) => {
+        if (draggingRef.current) return; // don't retarget mid-drag (block OR resize)
+        const t = e.target as HTMLElement;
+        const id = imageFigureIdAt(t);
+        if (id) {
+          setHoveredImageId(id);
+          return;
+        }
+        // Over the handle itself → keep it alive (it sits at the image's corner,
+        // just outside the figure, so it wouldn't match imageFigureIdAt).
+        if (t.closest?.('[data-rte-resize-handle]')) return;
+        setHoveredImageId(null); // over text/other content → clear
+      };
+      const onLeave = () => {
+        if (!draggingRef.current) setHoveredImageId(null);
+      };
+      shell.addEventListener('mouseover', onOver);
+      shell.addEventListener('mouseleave', onLeave);
+      return () => {
+        shell.removeEventListener('mouseover', onOver);
+        shell.removeEventListener('mouseleave', onLeave);
+      };
+    }, [readOnly, usesShell, imageFigureIdAt]);
+
+    const onKeyDown = useCallback(
+      (e: React.KeyboardEvent<HTMLDivElement>) => {
+        if (readOnly) return;
+        const root = rootRef.current;
+        if (!root) return;
+        // Undo/redo don't need a live selection — check them BEFORE the
+        // readSelection guard so ⌘Z still works if the caret was lost. stopPropagation
+        // keeps the shortcut from triggering a host app's undo. preventDefault
+        // suppresses the browser's native contentEditable undo. We stamp the time so
+        // the paired historyUndo/historyRedo beforeinput (emitted by this same
+        // keydown) is skipped there rather than double-applied.
+        const mod = e.metaKey || e.ctrlKey;
+        if (mod && isLetterKey(e, 'z') && !e.shiftKey) {
+          e.preventDefault();
+          e.stopPropagation();
+          historyKeyAtRef.current = Date.now();
+          onUndo();
+          return;
+        }
+        if (mod && (isLetterKey(e, 'y') || (isLetterKey(e, 'z') && e.shiftKey))) {
+          e.preventDefault();
+          e.stopPropagation();
+          historyKeyAtRef.current = Date.now();
+          onRedo();
+          return;
+        }
+        const range = readSelection(root);
+        if (!range) return;
+        if (controlsOn) {
+          const caretBlock = range.anchor.blockId;
+          if (mod && e.shiftKey && (e.key === 'ArrowUp' || e.key === 'ArrowDown')) {
+            e.preventDefault();
+            e.stopPropagation();
+            commit(moveBlockUnit(value, caretBlock, e.key === 'ArrowUp' ? -1 : 1), 'other');
+            return;
+          }
+          if (mod && !e.shiftKey && isLetterKey(e, 'd')) {
+            e.preventDefault();
+            e.stopPropagation();
+            commit(duplicateBlockUnit(value, caretBlock), 'other');
+            return;
+          }
+          if ((e.shiftKey && e.key === 'F10') || e.key === 'ContextMenu') {
+            e.preventDefault();
+            // Clear hover so the menu binds to the caret block, not a stale hovered one.
+            setHoverBlockId(null);
+            setCaretBlockId(caretBlock);
+            setBlockMenuOpen(true);
+            return;
+          }
+        }
+        // Caret INSIDE a void block's contentEditable=false figure (e.g. after a
+        // doc-final image): browsers fire NO beforeinput there, only keydown, so
+        // route the editing keys ourselves. Only for keys aimed at the editable —
+        // an attachment's own Retry/Remove buttons keep theirs.
+        const vcaret =
+          e.target === root && isCollapsed(range) && !e.nativeEvent.isComposing
+            ? voidCaretSide(root, range.anchor.blockId)
+            : null;
+        if (vcaret?.inside) {
+          // A single character, not a shortcut. Ctrl+Alt is AltGr on Windows
+          // (e.g. "@" on a German layout), so that still counts as typing.
+          const printable = [...e.key].length === 1 && !e.metaKey && (!e.ctrlKey || e.altKey);
+          if (printable) {
+            e.preventDefault();
+            const pend = takePendingAt(range.anchor);
+            commit(
+              pend
+                ? insertWithMarks(value, range.anchor, e.key, pend)
+                : insertText(value, range.anchor, e.key),
+              'type',
+            );
+            return;
+          }
+          if (!mod && e.key === 'Enter') {
+            e.preventDefault();
+            commit(applyInput(value, range, 'insertParagraph', null)!, 'other');
+            return;
+          }
+          if (!mod && (e.key === 'Backspace' || e.key === 'Delete')) {
+            e.preventDefault();
+            const dir = e.key === 'Backspace' ? 'backward' : 'forward';
+            applyVoidDelete(voidDelete(value, range.anchor.blockId, vcaret.side, dir));
+            return;
+          }
+        }
+        // Mention menu navigation takes priority over editor keys when open.
+        if (mention.open && mention.items.length > 0) {
+          if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            mention.move(1);
+            return;
+          }
+          if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            mention.move(-1);
+            return;
+          }
+          if (e.key === 'Enter' || e.key === 'Tab') {
+            e.preventDefault();
+            mention.commitActive();
+            return;
+          }
+        }
+        if (mention.open && e.key === 'Escape') {
+          e.preventDefault();
+          e.stopPropagation();
+          mention.close();
+          return;
+        }
+        // ⌘/Ctrl+K opens the link editor (create or edit a link). Stop
+        // propagation so the shortcut doesn't ALSO trigger a host app's global
+        // ⌘K (command palette / search) while the editor is focused.
+        if ((e.metaKey || e.ctrlKey) && !e.shiftKey && isLetterKey(e, 'k')) {
+          e.preventDefault();
+          e.stopPropagation();
+          openLinkEditor();
+          return;
+        }
+
+        const blockType = deriveCurrentBlock(value, range)?.type;
+        const inList = blockType === 'bullet_item' || blockType === 'ordered_item';
+
+        // Tab / Shift+Tab indent/outdent — only inside a list, so Tab still
+        // moves focus out of the editor everywhere else (keyboard a11y).
+        if (e.key === 'Tab' && inList) {
+          e.preventDefault();
+          commit(runIndent(value, range, e.shiftKey ? 'out' : 'in'));
+          return;
+        }
+
+        // Enter in an EMPTY list item exits the list (→ paragraph).
+        if (e.key === 'Enter' && inList && isCollapsed(range)) {
+          const idx = value.blocks.findIndex((b) => b.id === range.anchor.blockId);
+          if (idx !== -1 && blockLength(value.blocks[idx]) === 0) {
+            e.preventDefault();
+            commit(runSetBlock(value, range, { type: 'paragraph' }));
+            return;
+          }
+        }
+
+        // Mark shortcut: with a collapsed caret, stage a pending mark for the
+        // next typed text instead of a no-op toggle; with a selection, toggle it.
+        const mark = shortcutMark(e);
+        if (mark) {
+          e.preventDefault();
+          stageOrToggleMark(range, mark);
+          return;
+        }
+      },
+      [
+        value,
+        readOnly,
+        commit,
+        stageOrToggleMark,
+        openLinkEditor,
+        onUndo,
+        onRedo,
+        mention,
+        controlsOn,
+        takePendingAt,
+        applyVoidDelete,
+      ],
+    );
+
+    // Snapshot at compositionstart — the last moment the DOM and the model agree:
+    // the selection, and the anchor block's own DOM text (in model offsets).
+    const compositionRef = useRef<{ range: Range; before: string } | null>(null);
+    const onCompositionStart = useCallback(() => {
+      isComposingRef.current = true;
+      const root = rootRef.current;
+      const range = root ? readSelection(root) : null;
+      const before = range && root ? blockOwnText(root, range.anchor.blockId) : null;
+      compositionRef.current = range && before != null ? { range, before } : null;
+    }, []);
+
+    const onCompositionEnd = useCallback(
+      (e: React.CompositionEvent<HTMLDivElement>) => {
+        isComposingRef.current = false;
+        const snap = compositionRef.current;
+        compositionRef.current = null;
+        const root = rootRef.current;
+        if (readOnly || !root || !snap) return;
+        const { range, before } = snap;
+        // A selection across blocks: the browser merged them in the DOM, so a text
+        // diff of one block can't see it — replace the captured range instead.
+        if (range.anchor.blockId !== range.focus.blockId) {
+          const result = applyInput(value, range, 'insertText', e.data);
+          if (result) commit(result, 'type');
+          return;
+        }
+        // The browser composed into the DOM ahead of the model. Diff the block's
+        // own text before vs after (common prefix + suffix) to find exactly what
+        // changed — no caret math, so an IME that recomposes an existing word
+        // (Android Gboard), leaves the caret mid-word, or commits unchanged is
+        // handled. The re-render then snaps the DOM back to the model.
+        const blockId = range.anchor.blockId;
+        const after = blockOwnText(root, blockId);
+        if (after == null || after === before) return;
+        // Cap the prefix at the composition start: in a repeated run ("ab" + "b")
+        // the change can't begin after the caret it started from.
+        const startCap = Math.min(range.anchor.offset, range.focus.offset);
+        let pre = 0;
+        while (pre < startCap && pre < after.length && before[pre] === after[pre]) pre += 1;
+        // ...and the suffix at the end of the snapshot selection (it was replaced).
+        const endCap = before.length - Math.max(range.anchor.offset, range.focus.offset);
+        let suf = 0;
+        while (
+          suf < Math.min(endCap, before.length - pre) &&
+          suf < after.length - pre &&
+          before[before.length - 1 - suf] === after[after.length - 1 - suf]
+        )
+          suf += 1;
+        const replaced: Range = {
+          anchor: { blockId, offset: pre },
+          focus: { blockId, offset: before.length - suf },
+        };
+        const inserted = after.slice(pre, after.length - suf);
+        const result = inserted
+          ? applyInput(value, replaced, 'insertText', inserted)
+          : applyInput(value, replaced, 'deleteContentBackward', null);
+        if (result) commit(result, 'type');
+      },
+      [value, readOnly, commit],
+    );
+
+    // Active marks + current block derived from the live selection for the toolbar.
+    const toolbarMarks = useMemo<MarkType[]>(
+      () => (selection ? deriveActiveMarks(value, selection, pendingMarks) : []),
+      [value, selection, pendingMarks],
+    );
+    const toolbarColors = useMemo(
+      () => (selection ? deriveActiveColors(value, selection, pendingMarks) : {}),
+      [value, selection, pendingMarks],
+    );
+    const toolbarBlock = useMemo<BlockChoice | null>(
+      () => (selection ? deriveCurrentBlock(value, selection) : null),
+      [value, selection],
+    );
+    const toolbarLinkActive = useMemo<boolean>(
+      () => (selection ? linkAt(value, selection.focus) != null : false),
+      [value, selection],
+    );
+
+    // Toolbar dispatch — read the live selection (falling back to tracked state)
+    // and route through the same commit path the keyboard uses. A mark at a
+    // collapsed caret stages a pending mark, mirroring the keyboard shortcut.
+    const onInsertEmoji = useCallback(
+      (emoji: string) => {
+        const root = rootRef.current;
+        const range = (root ? readSelection(root) : null) ?? lastSelectionRef.current;
+        if (!range) return;
+        const result = applyInput(latest.current.value, range, 'insertText', emoji);
+        if (result) {
+          commit(result);
+          root?.focus(); // keep the editor focused so typing continues after the pick
+        }
+      },
+      [commit],
+    );
+
+    const onToolbarMark = useCallback(
+      (type: MarkType) => {
+        // Value-carrying marks aren't plain toggles: link needs an href, mention an
+        // id+label, textColor/bgColor a palette key — this toolbar path fires none.
+        if (type === 'link' || type === 'mention' || type === 'textColor' || type === 'bgColor')
+          return;
+        const root = rootRef.current;
+        // lastSelectionRef = last non-null selection; survives a toolbar popover taking focus
+        const range = (root ? readSelection(root) : null) ?? lastSelectionRef.current;
+        if (range) stageOrToggleMark(range, { type });
+      },
+      [stageOrToggleMark],
+    );
+    const onToolbarSetBlock = useCallback(
+      (choice: BlockChoice) => {
+        const root = rootRef.current;
+        const range = (root ? readSelection(root) : null) ?? lastSelectionRef.current;
+        if (range) commit(runSetBlock(latest.current.value, range, choice));
+      },
+      [commit],
+    );
+    const onToolbarToggleList = useCallback(
+      (listType: 'bullet_item' | 'ordered_item') => {
+        const root = rootRef.current;
+        const range = (root ? readSelection(root) : null) ?? lastSelectionRef.current;
+        if (range) commit(runToggleList(latest.current.value, range, listType));
+      },
+      [commit],
+    );
+
+    const onPickFiles = useCallback(() => uploadInputRef.current?.click(), []);
+
+    const onBlockInsertBelow = useCallback(
+      (id: string) => commit(insertEmptyBlockBelow(latest.current.value, id), 'other'),
+      [commit],
+    );
+    const onBlockAction = useCallback(
+      (id: string, action: BlockAction) => {
+        const v = latest.current.value;
+        switch (action) {
+          case 'duplicate':
+            commit(duplicateBlockUnit(v, id), 'other');
+            break;
+          case 'moveUp':
+            commit(moveBlockUnit(v, id, -1), 'other');
+            break;
+          case 'moveDown':
+            commit(moveBlockUnit(v, id, 1), 'other');
+            break;
+          case 'delete':
+            commit(removeBlockUnit(v, id), 'other');
+            break;
+          default: {
+            // Exhaustiveness: a new BlockAction must be handled above.
+            const _never: never = action;
+            return _never;
+          }
+        }
+        setBlockMenuOpen(false);
+      },
+      [commit],
+    );
+    const onBlockTurnInto = useCallback(
+      (id: string, choice: BlockChoice) => {
+        const v = latest.current.value;
+        const range = { anchor: { blockId: id, offset: 0 }, focus: { blockId: id, offset: 0 } };
+        // "Turn into X" is an idempotent SET (not a toggle) on the single anchor
+        // block — choosing the block's current type is a no-op, never a revert.
+        // List types carry depth 0; runSetBlock routes both through setBlockType.
+        const patch =
+          choice.type === 'bullet_item' || choice.type === 'ordered_item'
+            ? { type: choice.type, depth: 0 }
+            : choice;
+        commit(runSetBlock(v, range, patch), 'other');
+        setBlockMenuOpen(false);
+      },
+      [commit],
+    );
+    const onBlockReorder = useCallback(
+      (id: string, targetIndex: number) =>
+        commit(moveBlockUnitToIndex(latest.current.value, id, targetIndex), 'other'),
+      [commit],
+    );
+    // Whole-block color from the ⠿ menu's Color submenu. Colors the block's full
+    // range via the shared setColorMark path, but commits with `keepSelection` so it
+    // does NOT writeSelection: the block menu owns focus and stays open, and the block
+    // isn't left visibly fully-selected after the pick.
+    const onBlockColor = useCallback(
+      (id: string, type: 'textColor' | 'bgColor', key: string | null) => {
+        const r = wholeBlockRange(latest.current.value, id);
+        if (r)
+          commit({ doc: setColorMark(latest.current.value, r, type, key), selection: r }, 'other', {
+            keepSelection: true,
+          });
+      },
+      [commit],
+    );
+
+    // Attachment config popover: open-state + alt/align/width/reset/replace
+    // handlers (see useAttachmentConfig). The live-resize history coupling stays
+    // in this file via `commitResizeLive`; the popover JSX (which derives the
+    // configured block + anchor from render scope) is rendered below.
+    const {
+      configBlockId,
+      onConfigOpen,
+      onConfigClose,
+      onConfigAlt,
+      onConfigAlign,
+      onConfigWidth,
+      onConfigWidthReset,
+      onConfigReplace,
+    } = useAttachmentConfig({
+      rootRef,
+      commit,
+      commitResizeLive,
+      getValue,
+      getLiveDoc,
+      uploaderRef,
+    });
+    // Stable resize handler for the image resizer — keeps the memoized resizer from
+    // re-rendering every keystroke on a fresh inline lambda. Targets the hovered
+    // image; guards hoveredImageId so a late move after the hover clears is a no-op.
+    const onImageResize = useCallback(
+      (w: number) => {
+        if (hoveredImageId) onConfigWidth(hoveredImageId, w);
+      },
+      [onConfigWidth, hoveredImageId],
+    );
+
+    // Delegate clicks on the error-state attachment Retry/Remove buttons (they
+    // carry data-attachment-action + data-block-id). On the editable so it works
+    // in every return branch, including the toolbar-less bare-fragment path.
+    const onEditableClick = useCallback((e: React.MouseEvent) => {
+      if (latest.current.readOnly) return; // never mutate a read-only doc
+      const el = (e.target as HTMLElement).closest?.('[data-attachment-action]');
+      if (!el) return;
+      const id = el.getAttribute('data-block-id');
+      const action = el.getAttribute('data-attachment-action');
+      if (!id) return;
+      if (action === 'retry') uploaderRef.current.retry(id);
+      else if (action === 'remove') uploaderRef.current.remove(id);
+    }, []);
+
+    // The rendered doc tree is a pure fn of (value, renderLink, renderMention) — it
+    // does NOT depend on selection/hover/focus. Memoize so the whole element tree is
+    // not rebuilt on selection/hover/focus re-renders that leave the doc unchanged.
+    const content = useMemo(
+      () => renderDoc(value, { editable: true, renderLink, renderMention }),
+      [value, renderLink, renderMention],
+    );
+    // Signature of block order. `value.blocks` is a new array on every edit, so this
+    // recomputes per keystroke (a cheap join) — but the STRING is unchanged while
+    // typing within a block, so the gutter (blockOrderKey) and the image resizer's
+    // layoutKey keep their memoized shells stable.
+    const blockOrderKey = useMemo(() => value.blocks.map((b) => b.id).join('|'), [value.blocks]);
+
+    const editable = (
+      <div
+        // {...rest} FIRST so the component's own role/aria/contentEditable/handlers
+        // below win — the textbox contract must be preserved (Rule 7, Pattern B).
+        // A consumer aria-label still flows in via the spread AND is read above to
+        // decide whether to fall back to the i18n default.
+        {...rest}
+        ref={setRefs}
+        style={imageMaxHeightStyle(imageMaxHeight, style)}
+        className={clsx(
+          styles.root,
+          readOnly && styles.readOnly,
+          controlsOn && styles.withGutter,
+          className,
+        )}
+        contentEditable={!readOnly}
+        suppressContentEditableWarning
+        role="textbox"
+        aria-multiline="true"
+        aria-readonly={readOnly || undefined}
+        aria-invalid={invalid || undefined}
+        aria-required={required || undefined}
+        // Mentions makes the textbox an editable combobox. role stays "textbox"
+        // (ARIA combobox is single-line only; this editor is multiline), with
+        // aria-autocomplete + aria-controls + aria-activedescendant describing the
+        // popup. Gated so a readOnly or mention-less editor advertises no popup.
+        aria-haspopup={mentions && !readOnly ? 'listbox' : undefined}
+        aria-autocomplete={mentions && !readOnly ? 'list' : undefined}
+        aria-expanded={mentions && !readOnly ? mention.open : undefined}
+        aria-controls={mention.open ? mention.listboxId : undefined}
+        aria-activedescendant={mention.open ? mention.activeOptionId : undefined}
+        aria-label={
+          rest['aria-label'] ||
+          (rest['aria-labelledby'] ? undefined : t('richTextEditor.editorLabel'))
+        }
+        data-empty={isEmptyDoc(value) ? '' : undefined}
+        data-placeholder={placeholder}
+        spellCheck
+        onKeyDown={onKeyDown}
+        onClick={onEditableClick}
+        onCompositionStart={onCompositionStart}
+        onCompositionEnd={onCompositionEnd}
+        // Only tracked for `toolbar="auto"` (gates the bar's visibility); omitted
+        // otherwise so other modes never re-render on focus changes.
+        onFocus={autoToolbar ? () => setFocused(true) : undefined}
+        onBlur={autoToolbar ? () => setFocused(false) : undefined}
+      >
+        {content}
+      </div>
+    );
+
+    const linkBubble =
+      linkEditor && !readOnly ? (
+        <RichTextLinkEditor
+          key={linkEditor.key}
+          href={linkEditor.href}
+          editing={linkEditor.editing}
+          anchorRect={linkEditor.anchorRect}
+          // Re-derive the anchor from the captured model range on each reposition so
+          // the bubble tracks the line on scroll (the editor's live selection is
+          // gone once the URL input takes focus, so re-measure the range, not it).
+          getAnchorRect={() =>
+            rootRef.current ? rangeRect(rootRef.current, linkEditor.range) : null
+          }
+          onApply={onLinkApply}
+          onRemove={onLinkRemove}
+          onCancel={onLinkCancel}
+        />
+      ) : null;
+
+    const mentionMenu =
+      mention.open && !readOnly && mention.anchorRect ? (
+        <RichTextMentionMenu
+          items={mention.items}
+          activeIndex={mention.activeIndex}
+          anchorRect={mention.anchorRect}
+          getAnchorRect={mention.getAnchorRect}
+          listboxId={mention.listboxId}
+          getOptionId={mention.getOptionId}
+          label={t('richTextEditor.mentionsLabel')}
+          emptyLabel={t('richTextEditor.mentionsEmpty')}
+          onSelect={mention.selectIndex}
+          onHover={mention.setActiveIndex}
+        />
+      ) : null;
+
+    const activeBlock = activeBlockId
+      ? value.blocks.find((b) => b.id === activeBlockId)
+      : undefined;
+    const activeBlockType = activeBlock?.type;
+    const canConfigure =
+      uploadOn && activeBlock?.type === 'attachment' && isAttachmentSettled(activeBlock);
+    const configBlock = configBlockId
+      ? value.blocks.find((b) => b.id === configBlockId)
+      : undefined;
+    const blockControlsEl = controlsOn ? (
+      <RichTextBlockControls
+        rootRef={shellRef}
+        activeBlockId={activeBlockId}
+        blockOrderKey={blockOrderKey}
+        activeBlockType={activeBlockType}
+        menuOpen={blockMenuOpen}
+        onMenuOpenChange={setBlockMenuOpen}
+        onInsertBelow={onBlockInsertBelow}
+        onAction={onBlockAction}
+        onTurnInto={onBlockTurnInto}
+        onReorder={onBlockReorder}
+        onConfigure={canConfigure ? onConfigOpen : undefined}
+        onColor={onBlockColor}
+        onDraggingChange={onBlockDraggingChange}
+      />
+    ) : null;
+
+    // A bottom-right resize handle on the HOVERED previewable image — shown for any
+    // previewable image (a safe, fetchable src that renders as <img>) on hover, as
+    // long as the editor is editable and has a shell to anchor the handle in
+    // (`usesShell`). Independent of blockControls/upload/active-block: a pasted image
+    // in a toolbar-only composer gets a handle too. The keyboard-accessible Width
+    // slider remains the a11y path where blockControls+upload are configured (the
+    // Configure popover). The layoutKey carries the image's width so the handle
+    // re-measures as it resizes; `hidden` hides it during a block reorder (it can't
+    // track the in-place reflow), reappearing at the drop.
+    const resizableImage = hoveredImageId
+      ? value.blocks.find(
+          (b) =>
+            b.id === hoveredImageId &&
+            b.type === 'attachment' &&
+            // Settled = ready OR no status (a persisted/imported block drops its
+            // transient status); mirrors the renderer's "ready-or-absent" displayable
+            // rule so the handle can't drift from what's shown. See #263.
+            isAttachmentSettled(b) &&
+            attachmentIsImage(b) &&
+            !!safeHref(b.src ?? ''),
+        )
+      : undefined;
+    // Widest an image may be resized to: the content width, further limited so
+    // its height stays within the display cap (#644) — the handle/slider stop
+    // where the rendered image stops growing.
+    const imageWidthMax = (id: string) => {
+      const contentWidth = rootRef.current?.getBoundingClientRect().width ?? 600;
+      const img = rootRef.current?.querySelector<HTMLImageElement>(
+        `[data-block-id="${CSS.escape(id)}"] img`,
+      );
+      return img
+        ? capWidthToHeight(
+            contentWidth,
+            img.naturalWidth,
+            img.naturalHeight,
+            parseFloat(getComputedStyle(img).maxHeight),
+          )
+        : contentWidth;
+    };
+    const imageResizerEl =
+      !readOnly && usesShell && resizableImage ? (
+        <RichTextImageResizer
+          rootRef={shellRef}
+          blockId={hoveredImageId!}
+          layoutKey={`${blockOrderKey}:${resizableImage.width ?? ''}`}
+          maxWidth={imageWidthMax(hoveredImageId!)}
+          onResize={onImageResize}
+          onDraggingChange={setDragging}
+          hidden={blockDragging}
+        />
+      ) : null;
+
+    const configEl =
+      configBlock &&
+      configBlock.type === 'attachment' &&
+      isAttachmentSettled(configBlock) &&
+      uploadOn
+        ? (() => {
+            const figEl = rootRef.current?.querySelector<HTMLElement>(
+              `[data-block-id="${CSS.escape(configBlock.id)}"]`,
+            );
+            const r = figEl?.getBoundingClientRect();
+            if (!r) return null;
+            return (
+              <RichTextAttachmentConfig
+                key={configBlock.id}
+                block={configBlock}
+                anchorRect={{ top: r.top, left: r.left, width: r.width, height: r.height }}
+                getAnchorRect={() => {
+                  // Re-query the figure live so the popover tracks it on scroll.
+                  const el = rootRef.current?.querySelector<HTMLElement>(
+                    `[data-block-id="${CSS.escape(configBlock.id)}"]`,
+                  );
+                  if (!el) return null;
+                  const b = el.getBoundingClientRect();
+                  return { top: b.top, left: b.left, width: b.width, height: b.height };
+                }}
+                maxWidth={imageWidthMax(configBlock.id)}
+                accept={latest.current.upload?.accept}
+                onAltChange={(alt) => onConfigAlt(configBlock.id, alt)}
+                onAlignChange={(align) => onConfigAlign(configBlock.id, align)}
+                onWidthChange={(w) => onConfigWidth(configBlock.id, w)}
+                onWidthReset={() => onConfigWidthReset(configBlock.id)}
+                onReplace={(file) => onConfigReplace(configBlock.id, file)}
+                onClose={onConfigClose}
+              />
+            );
+          })()
+        : null;
+
+    // Toolbar visibility. `true` → always; `'auto'` → focused, non-empty, or while
+    // one of the editor's own overlays is open (so opening the link editor on a
+    // focused-but-empty composer keeps the bar up rather than collapsing it). The
+    // overlay term is what survives the blur caused by the overlay stealing focus.
+    const overlayOpen = linkEditor != null || mention.open || toolbarOverlayOpen;
+    const showToolbar =
+      toolbar === true || (autoToolbar && (focused || !isEmptyDoc(value) || overlayOpen));
+    // `usesShell` (the stable `.shell` gate) is declared near the top so the
+    // image-hover effect can depend on it; it's reused here for the shell render.
+
+    const toolbarBar = showToolbar ? (
+      <RichTextToolbar
+        activeMarks={toolbarMarks}
+        colors={toolbarColors}
+        onSetColor={onSetColor}
+        block={toolbarBlock}
+        disabled={readOnly}
+        onToggleMark={onToolbarMark}
+        onSetBlock={onToolbarSetBlock}
+        onToggleList={onToolbarToggleList}
+        linkActive={toolbarLinkActive}
+        onOpenLink={openLinkEditor}
+        canUndo={canUndo}
+        canRedo={canRedo}
+        onUndo={onUndo}
+        onRedo={onRedo}
+        onPickFiles={uploadOn ? onPickFiles : undefined}
+        onOverlayOpenChange={autoToolbar ? setToolbarOverlayOpen : undefined}
+        onInsertEmoji={onInsertEmoji}
+      />
+    ) : null;
+
+    // The upload picker's input lives HERE, in the always-rendered shell, not in
+    // the toolbar: a native file dialog blurs the editable, and under
+    // `toolbar="auto"` on an empty doc that unmounts the bar — detaching the input
+    // mid-pick, so its `change` never reaches React and the file is silently lost.
+    const uploadInput = uploadOn ? (
+      <input
+        ref={uploadInputRef}
+        type="file"
+        multiple
+        accept={upload?.accept}
+        style={{ display: 'none' }}
+        onChange={(e) => {
+          const files = Array.from(e.target.files ?? []);
+          if (files.length) uploaderRef.current.uploadFiles(files);
+          e.target.value = ''; // allow re-picking the same file
+        }}
+      />
+    ) : null;
+
+    // Always mounted while uploads are on, so only its text changes. Outside the
+    // editable: inside the textbox it would join the document's content.
+    const uploadStatus = uploadOn ? (
+      <LiveRegion>
+        {uploadFailure
+          ? [`${t('richTextEditor.uploadFailed')}: ${uploadFailure.name}`, uploadFailure.reason]
+              .filter(Boolean)
+              .join('. ')
+          : ''}
+      </LiveRegion>
+    ) : null;
+
+    if (!usesShell) {
+      return (
+        <>
+          {uploadStatus}
+          {editable}
+          {linkBubble}
+          {mentionMenu}
+        </>
+      );
+    }
+    return (
+      <div className={styles.shell} ref={shellRef}>
+        {toolbarBar}
+        {uploadInput}
+        {uploadStatus}
+        {editable}
+        {linkBubble}
+        {mentionMenu}
+        {blockControlsEl}
+        {imageResizerEl}
+        {configEl}
+      </div>
+    );
+  },
+);