@lovett/ui 0.0.11 → 0.2.0

package/src/thread/rich-composer-impl.tsx

@@ -0,0 +1,1601 @@
+/**
+ * RichThreadComposerImpl — the TipTap surface behind the rich composer.
+ *
+ * ADR-148. This module is reached ONLY through the `lazy()` boundary in
+ * rich-composer.tsx (D5): every TipTap import here is static and ordinary, so
+ * Vite splits the whole editor into one chunk and the D6 fallback wraps one
+ * promise. Nothing in this file is re-exported from the package barrel.
+ *
+ * Two components. The default export is the GATE (D3 rule 2): it runs
+ * `isRichEditable` on the draft before any editor exists and, if the body
+ * holds syntax the subset cannot carry, renders the plain composer with the
+ * source untouched and a one-line notice. `RichSurface` below it owns the
+ * editor. The gate lives here rather than in the shell because the detector
+ * needs the subset's schema, and the shell must stay free of TipTap.
+ *
+ * The seam stays `ThreadComposerProps`: markdown in through `value`, markdown
+ * out through `onChange`, and verified attachment ticket ids out through the
+ * optional `onSubmit` argument (ADR-151 D1). Hooks and host capabilities sit
+ * on top: `onEditor`, `mentionItems`, upload/GIF callbacks, limits, and the
+ * shell's polite `announce` region. Missing capabilities render no inert UI.
+ *
+ * DRAFT TIMING (D12). `onChange` receives serialized markdown on a 300 ms
+ * trailing debounce, not on every transaction, and is flushed on blur, send
+ * and unmount. Because the parent is therefore up to 300 ms behind the editor,
+ * SEND does not call `onSubmit` until the parent has caught up: `requestSubmit`
+ * flushes, and an effect fires `onSubmit` once `value` equals what was flushed
+ * and every attachment has a verified ticket — so `useThread.submit`, which
+ * reads the draft it was rendered with, always sends the latest keystrokes.
+ * `canSend` reads the editor's own emptiness for the same reason.
+ *
+ * KEYBOARD (D9). Every Escape level lives in ONE `handleKeyDown`: bubble menu,
+ * then Suggestion popup, then `onCancel`. `editorProps` handlers run before
+ * any extension keymap, which is what makes the order a fact rather than a
+ * hope. Tab is answered from `handleDOMEvents.keydown` returning true — that
+ * skips ProseMirror's keymaps (StarterKit binds Tab to indent a list item)
+ * WITHOUT preventing the browser default, so focus leaves the editor. While a
+ * suggestion popup is open Tab is NOT waved through: ADR-149 D5 gives it to
+ * the popup, so the DOM-event handler stands down and `handleKeyDown` inserts.
+ *
+ * SUGGESTIONS (ADR-149). Two triggers, ONE popup. `markdown-spec.ts` owns the
+ * data half (what `@` and `:` offer, and what choosing inserts); this file
+ * owns the UI half: the `render()` lifecycle each trigger gets, the single
+ * `<SuggestionList>` both of them draw into, and the keys. The popup NEVER
+ * takes focus — it is mounted in a portal outside the editor and pointed at by
+ * `aria-controls` / `aria-activedescendant` on the contenteditable itself, so
+ * `document.activeElement` is the editor through open, arrow, insert and
+ * escape (D5, AC#6).
+ *
+ * IME (D11). The bubble predicate refuses while `view.composing` or our own
+ * composition flag is set; `compositionstart` closes an open menu outright.
+ *
+ * What jsdom cannot verify here, and the tests say so: the bubble menu's
+ * pixel placement (floating-ui needs layout) and real composition sessions.
+ * Both are on the owner's eyeball + IME pass (AC#13).
+ */
+
+import type { CSSProperties, KeyboardEvent as ReactKeyboardEvent } from 'react'
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import {
+  Bold,
+  Check,
+  Code,
+  CornerDownRight,
+  Heading1,
+  Heading2,
+  Heading3,
+  Italic,
+  Images,
+  Link as LinkIcon,
+  List,
+  ListOrdered,
+  Minus,
+  SquareCode,
+  Strikethrough,
+  TextQuote,
+  Underline as UnderlineIcon,
+  Unlink,
+  X,
+} from 'lucide-react'
+import { isTextSelection, type Editor } from '@tiptap/core'
+import { Placeholder } from '@tiptap/extension-placeholder'
+import { Fragment, Node as ProseMirrorNode, Slice } from '@tiptap/pm/model'
+import type { PluginKey } from '@tiptap/pm/state'
+import { PluginKey as ProseMirrorPluginKey } from '@tiptap/pm/state'
+import type { EditorView } from '@tiptap/pm/view'
+import { EditorContent, useEditor, useEditorState } from '@tiptap/react'
+import { BubbleMenu } from '@tiptap/react/menus'
+import { Button } from '../button'
+import { Kbd } from '../kbd'
+import { cn } from '../lib/utils'
+import { Popover } from '../popover'
+import {
+  ATTACHMENT_ACCEPT,
+  AttachmentButton,
+  AttachmentDropZone,
+  AttachmentTray,
+  GifPicker,
+} from './attachments'
+import type { MentionTargetType } from './comment-body'
+import type { MentionSuggestionItem } from './types'
+import { ThreadComposer, type ThreadComposerProps } from './composer'
+import { ComposerFooter } from './composer-footer'
+import { caretScrollDelta } from './scroll-caret'
+import { searchEmoji } from './emoji'
+import {
+  EMOJI_SUGGESTION_MIN_QUERY,
+  MENTION_SUGGESTION_MIN_QUERY,
+  THREAD_EMOJI_SUGGESTION_KEY,
+  THREAD_MENTION_SUGGESTION_KEY,
+  isRichEditable,
+  parseRichMarkdown,
+  richSubsetExtensions,
+  serializeRichMarkdown,
+  type EmojiSuggestionAttrs,
+} from './markdown-spec'
+import { ComposerNotice, type RichComposerAttachmentProps } from './rich-composer'
+import { SuggestionList, wrapIndex, type SuggestionOption } from './suggestion-list'
+import { useAttachments } from './use-attachments'
+
+/** D12: the draft leaves the editor on this trailing debounce. */
+export const DRAFT_DEBOUNCE_MS = 300
+
+/** D3 rule 2, in the user's words. Rendered above the plain composer and spoken once. */
+export const FAIL_CLOSED_NOTICE =
+  'Opened in the plain editor: this comment uses formatting the rich editor cannot hold. Nothing was changed.'
+
+export type { MentionSuggestionItem } from './types'
+
+/** Hooks on top of the seam. None of these is part of `ThreadComposerProps`. */
+export interface RichComposerHooks extends RichComposerAttachmentProps {
+  /** Receives the live editor once created, and null when it goes away. */
+  readonly onEditor?: ((editor: Editor | null) => void) | undefined
+  /** ADR-149's seam: items for the `@` picker. Absent, the popup never opens. */
+  readonly mentionItems?: ((query: string) => readonly MentionSuggestionItem[]) | undefined
+  /** The shell's polite live region. */
+  readonly announce?: ((message: string) => void) | undefined
+}
+
+export type RichThreadComposerImplProps = ThreadComposerProps & RichComposerHooks
+
+/* ── Platform spelling, read once (same reasoning as composer.tsx) ─────────── */
+
+const IS_APPLE: boolean =
+  typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.userAgent)
+const SEND_KEYCAP = IS_APPLE ? '⌘↵' : 'Ctrl ↵'
+const MOD_NAME = IS_APPLE ? 'Command' : 'Control'
+
+/** React accepts CSS custom properties in `style`; the DOM typings do not declare them. */
+type StyleWithVars = CSSProperties & Record<`--${string}`, string>
+
+const BUBBLE_MENU_KEY = new ProseMirrorPluginKey('threadBubbleMenu')
+
+/* ── The gate (D3 rule 2) ─────────────────────────────────────────────────── */
+
+export default function RichThreadComposerImpl(props: RichThreadComposerImplProps) {
+  const { value, onChange, announce } = props
+
+  // What the parent currently holds BECAUSE we emitted it. A `value` that
+  // differs from it arrived from outside — a resumed draft, a comment opened
+  // for editing, a reset after send — and is the only kind that can change the
+  // gate's answer. Our own emissions never re-run the detector: the editor
+  // cannot produce syntax the editor cannot hold.
+  const lastEmitted = useRef<string | null>(null)
+  const [gate, setGate] = useState(() => ({ value, rich: isRichEditable(value) }))
+  if (value !== gate.value) {
+    setGate({ value, rich: value === lastEmitted.current ? gate.rich : isRichEditable(value) })
+  }
+
+  const emit = useCallback(
+    (next: string) => {
+      lastEmitted.current = next
+      onChange(next)
+    },
+    [onChange],
+  )
+
+  useEffect(() => {
+    if (!gate.rich) announce?.(FAIL_CLOSED_NOTICE)
+  }, [announce, gate.rich])
+
+  if (!gate.rich) {
+    const {
+      onEditor: _onEditor,
+      mentionItems: _items,
+      announce: _announce,
+      uploadAttachment: _uploadAttachment,
+      attachGif: _attachGif,
+      searchGifs: _searchGifs,
+      attachmentAccept: _attachmentAccept,
+      attachmentMaxPerComment: _attachmentMaxPerComment,
+      attachmentMaxFileBytes: _attachmentMaxFileBytes,
+      attachmentMaxTotalBytes: _attachmentMaxTotalBytes,
+      ...plain
+    } = props
+    return (
+      <div className="flex flex-col gap-[var(--space-1)]">
+        <ComposerNotice>{FAIL_CLOSED_NOTICE}</ComposerNotice>
+        <ThreadComposer {...plain} onChange={emit} />
+      </div>
+    )
+  }
+  return <RichSurface {...props} onChange={emit} />
+}
+
+/* ── The suggestion popup (ADR-149) ───────────────────────────────────────── */
+
+/** Which trigger a popup session belongs to. Two configs, one popup (D1). */
+type SuggestionKind = 'mention' | 'emoji'
+
+/** What choosing an option hands back. Both shapes carry `id` + `label`. */
+type SuggestionAttrs = MentionSuggestionItem | EmojiSuggestionAttrs
+
+/**
+ * The slice of `@tiptap/suggestion`'s render props this file actually uses,
+ * declared locally and precisely.
+ *
+ * `@tiptap/suggestion` types `SuggestionProps` with `I = any`, so reading
+ * `props.items` or `props.command` through its own types would leak `any` into
+ * this file (CLAUDE.md §3). A narrower parameter type is still assignable — a
+ * handler that accepts less than it is given always is — so this costs
+ * nothing and keeps the file free of `any`.
+ */
+interface SuggestionRenderProps {
+  readonly query: string
+  readonly command: (attrs: SuggestionAttrs) => void
+  readonly mount: (
+    element: HTMLElement,
+    options?: {
+      onPosition?: (data: { x: number; y: number; strategy: 'absolute' | 'fixed' }) => void
+    },
+  ) => () => void
+}
+
+/** The rows a session is showing: what to draw, and what to insert. */
+interface SuggestionRows {
+  readonly options: readonly SuggestionOption[]
+  readonly attrs: readonly SuggestionAttrs[]
+}
+
+const EMPTY_ROWS: SuggestionRows = { options: [], attrs: [] }
+
+const SUGGESTION_KEYS: Readonly<Record<SuggestionKind, PluginKey>> = {
+  mention: THREAD_MENTION_SUGGESTION_KEY,
+  emoji: THREAD_EMOJI_SUGGESTION_KEY,
+}
+
+const SUGGESTION_LABELS: Readonly<Record<SuggestionKind, string>> = {
+  mention: 'Mention someone',
+  emoji: 'Emoji',
+}
+
+/** The same two, as the noun the polite announcement counts. */
+const SUGGESTION_NOUNS: Readonly<Record<SuggestionKind, string>> = {
+  mention: 'mention',
+  emoji: 'emoji',
+}
+
+/**
+ * D4's thresholds, enforced HERE and not only on the plugin.
+ *
+ * `minQueryLength` in the Suggestion config stops the plugin doing needless
+ * `items()` work, but all it does to the renderer is hand it an empty item
+ * list — and this file computes its rows from the QUERY rather than from
+ * `props.items` (see `SuggestionRenderProps`). So the threshold has to be a
+ * rule the popup itself applies, or a host whose `mentionItems` ignores its
+ * query would open the popup on a bare `@`. Same constants, one behaviour.
+ */
+const SUGGESTION_MIN_QUERY: Readonly<Record<SuggestionKind, number>> = {
+  mention: MENTION_SUGGESTION_MIN_QUERY,
+  emoji: EMOJI_SUGGESTION_MIN_QUERY,
+}
+
+/** User-facing names for the three mention schemes (ADR-147 D11). */
+const MENTION_KIND_LABELS: Readonly<Record<MentionTargetType, string>> = {
+  user: 'Person',
+  task_item: 'Task',
+  task_board: 'Board',
+}
+
+/**
+ * Close a Suggestion plugin without touching the document.
+ *
+ * This is the exact transaction `@tiptap/suggestion`'s own `exitSuggestion()`
+ * dispatches. It is re-spelled here rather than imported because that package
+ * is transitive — ADR-148 D2 deliberately did not install it, and AC#1 forbids
+ * adding it — so under pnpm's strict layout `@lovett/ui` cannot resolve it.
+ * The meta also marks the range dismissed, which is what keeps the popup shut
+ * after Escape instead of reopening on the next keystroke.
+ */
+function exitSuggestionPlugin(view: EditorView, kind: SuggestionKind): void {
+  view.dispatch(view.state.tr.setMeta(SUGGESTION_KEYS[kind], { exit: true }))
+}
+
+/** The `:` picker's rows: the glyph, its canonical `:shortcode:`. */
+function emojiRows(query: string): SuggestionRows {
+  const entries = searchEmoji(query)
+  return {
+    options: entries.map((entry) => ({
+      key: entry.name,
+      label: `:${entry.name}:`,
+      glyph: entry.glyph,
+    })),
+    attrs: entries.map((entry) => ({ id: entry.name, label: entry.glyph })),
+  }
+}
+
+/** The first character of a label, for the leading slot. */
+function leadingInitial(label: string): string {
+  return ([...label][0] ?? '').toUpperCase()
+}
+
+/** The `@` picker's rows, from whatever list the host handed us (D6). */
+function mentionRows(items: readonly MentionSuggestionItem[]): SuggestionRows {
+  return {
+    options: items.map((item) => ({
+      key: `${item.type}:${item.id}`,
+      label: item.label,
+      hint: MENTION_KIND_LABELS[item.type],
+      glyph: leadingInitial(item.label),
+      // The initial is the label's own first letter — decoration, not
+      // information. The emoji rows above deliberately do NOT set this.
+      glyphDecorative: true,
+    })),
+    attrs: [...items],
+  }
+}
+
+/* ── Helpers ──────────────────────────────────────────────────────────────── */
+
+function isPlainTab(event: KeyboardEvent): boolean {
+  return event.key === 'Tab' && !event.altKey && !event.ctrlKey && !event.metaKey
+}
+
+const BARE_URL = /^(?:https?:\/\/|www\.)\S+$/i
+
+/**
+ * What the link field accepts: an http(s) / mailto / tel URL, or a bare domain
+ * that gets `https://` in front. Anything with another scheme is refused —
+ * `javascript:` above all — before it can reach `setLink`, which refuses it
+ * again by its own allowlist. Two locks, same door.
+ */
+function normalizeHref(input: string): string | null {
+  const trimmed = input.trim()
+  if (trimmed === '') return null
+  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) {
+    return /^(?:https?:|mailto:|tel:)/i.test(trimmed) ? trimmed : null
+  }
+  if (/^(?:www\.)?[\w-]+(?:\.[\w-]+)+(?:[/?#]\S*)?$/i.test(trimmed)) return `https://${trimmed}`
+  return null
+}
+
+/** A `--space-*` token as a number, for floating-ui's offset. Falls back to the token's documented value. */
+function readSpaceToken(element: HTMLElement | null, token: string, fallback: number): number {
+  if (element === null || typeof getComputedStyle !== 'function') return fallback
+  const raw = parseFloat(getComputedStyle(element).getPropertyValue(token))
+  return Number.isFinite(raw) && raw > 0 ? raw : fallback
+}
+
+function focusableButtons(root: HTMLElement | null): HTMLButtonElement[] {
+  if (root === null) return []
+  return Array.from(root.querySelectorAll<HTMLButtonElement>('button:not([disabled])'))
+}
+
+/* ── The editor ───────────────────────────────────────────────────────────── */
+
+interface LatestProps {
+  readonly value: string
+  readonly onChange: (value: string) => void
+  readonly onSubmit: (attachmentIds?: readonly string[]) => void
+  readonly onCancel: (() => void) | undefined
+  readonly mentionItems: ((query: string) => readonly MentionSuggestionItem[]) | undefined
+  readonly announce: ((message: string) => void) | undefined
+}
+
+function RichSurface({
+  value,
+  onChange,
+  onSubmit,
+  onCancel,
+  placeholder = 'Add a comment…',
+  submitLabel = 'Comment',
+  cancelLabel = 'Cancel',
+  sending = false,
+  disabled = false,
+  replyingTo,
+  avatar,
+  rows = 3,
+  mode,
+  onModeChange,
+  autoFocus = false,
+  toolbar = true,
+  maxLength,
+  label,
+  className,
+  onEditor,
+  mentionItems,
+  announce,
+  uploadAttachment,
+  attachGif,
+  searchGifs,
+  attachmentAccept,
+  attachmentMaxPerComment,
+  attachmentMaxFileBytes,
+  attachmentMaxTotalBytes,
+}: RichThreadComposerImplProps) {
+  const labelId = useId()
+  const hintId = useId()
+  const linkErrorId = useId()
+  const listboxId = useId()
+  const shellRef = useRef<HTMLDivElement>(null)
+  const bubbleRef = useRef<HTMLDivElement>(null)
+  const linkInputRef = useRef<HTMLInputElement>(null)
+  const [gifPickerOpen, setGifPickerOpen] = useState(false)
+  const attachments = useAttachments({
+    ...(uploadAttachment === undefined ? {} : { upload: uploadAttachment }),
+    ...(attachGif === undefined ? {} : { attachGif }),
+    ...(announce === undefined ? {} : { onError: announce }),
+    ...(attachmentMaxPerComment === undefined
+      ? {}
+      : { maxPerComment: attachmentMaxPerComment }),
+    ...(attachmentMaxFileBytes === undefined ? {} : { maxFileBytes: attachmentMaxFileBytes }),
+    ...(attachmentMaxTotalBytes === undefined
+      ? {}
+      : { maxTotalBytes: attachmentMaxTotalBytes }),
+  })
+
+  // The editor is created once; its callbacks read the latest props through
+  // this ref rather than the closures they were created with.
+  const latest = useRef<LatestProps>({ value, onChange, onSubmit, onCancel, mentionItems, announce })
+  useLayoutEffect(() => {
+    latest.current = { value, onChange, onSubmit, onCancel, mentionItems, announce }
+  })
+  const editorRef = useRef<Editor | null>(null)
+
+  // D12 — draft emission.
+  const lastEmitted = useRef<string>(value)
+  const emitTimer = useRef<number | null>(null)
+  const [pendingSubmit, setPendingSubmit] = useState<string | null>(null)
+
+  // D7 / D9 / D11 — menu state. Refs are the truth the ProseMirror handlers
+  // read synchronously; the React state mirrors them for rendering.
+  const composing = useRef(false)
+  const bubbleOpenRef = useRef(false)
+
+  // ADR-149 — the suggestion popup. The ref is what `handleKeyDown` reads
+  // (a keystroke cannot wait for a render); the state is what draws.
+  const suggestionRef = useRef<{
+    readonly kind: SuggestionKind
+    readonly attrs: readonly SuggestionAttrs[]
+    readonly command: (attrs: SuggestionAttrs) => void
+  } | null>(null)
+  const activeIndexRef = useRef(0)
+  const [suggestion, setSuggestion] = useState<{
+    readonly kind: SuggestionKind
+    readonly container: HTMLElement
+    readonly options: readonly SuggestionOption[]
+  } | null>(null)
+  const [activeIndex, setActiveIndex] = useState(0)
+
+  const setActiveOption = useCallback((index: number) => {
+    activeIndexRef.current = index
+    setActiveIndex(index)
+  }, [])
+
+  const optionDomId = useCallback(
+    (index: number) => `${listboxId}-option-${String(index)}`,
+    [listboxId],
+  )
+
+  /** Insert the row at `index`; the plugin's own command owns the document. */
+  const commitSuggestion = useCallback((index: number) => {
+    const active = suggestionRef.current
+    const attrs = active?.attrs[index]
+    if (active === undefined || active === null || attrs === undefined) return
+    active.command(attrs)
+  }, [])
+  const dismissedSelection = useRef<{ from: number; to: number } | null>(null)
+  const [bubbleOpen, setBubbleOpen] = useState(false)
+  const [focusRequest, setFocusRequest] = useState<'toolbar' | 'link' | null>(null)
+  const [linkMode, setLinkMode] = useState(false)
+  const [linkDraft, setLinkDraft] = useState('')
+  const [linkError, setLinkError] = useState(false)
+  const [rovingIndex, setRovingIndex] = useState(0)
+
+  const setBubble = useCallback((open: boolean) => {
+    bubbleOpenRef.current = open
+    setBubbleOpen((prev) => (prev === open ? prev : open))
+    if (!open) {
+      setLinkMode(false)
+      setLinkError(false)
+      setFocusRequest(null)
+    }
+  }, [])
+
+  /** D7: the one predicate both the plugin and the React state answer to. */
+  const shouldShowBubble = useCallback((editor: Editor): boolean => {
+    if (!editor.isEditable) return false
+    const { selection, doc } = editor.state
+    if (selection.empty || !isTextSelection(selection)) return false
+    if (doc.textBetween(selection.from, selection.to, ' ').trim() === '') return false
+    if (editor.isActive('codeBlock')) return false
+    if (editor.view.composing || composing.current) return false
+    if (suggestionRef.current !== null) return false
+    const dismissed = dismissedSelection.current
+    if (dismissed !== null) {
+      if (dismissed.from === selection.from && dismissed.to === selection.to) return false
+      dismissedSelection.current = null
+    }
+    return true
+  }, [])
+
+  const syncBubble = useCallback(
+    (editor: Editor) => {
+      setBubble(shouldShowBubble(editor))
+    },
+    [setBubble, shouldShowBubble],
+  )
+
+  const dismissBubble = useCallback(
+    (editor: Editor) => {
+      const { from, to } = editor.state.selection
+      dismissedSelection.current = { from, to }
+      setBubble(false)
+      editor.view.dispatch(editor.state.tr.setMeta(BUBBLE_MENU_KEY, 'hide'))
+    },
+    [setBubble],
+  )
+
+  const emitNow = useCallback((editor: Editor): string => {
+    const markdown = serializeRichMarkdown(editor.getJSON())
+    if (markdown !== lastEmitted.current) {
+      lastEmitted.current = markdown
+      latest.current.onChange(markdown)
+    }
+    return markdown
+  }, [])
+
+  const clearEmitTimer = useCallback(() => {
+    if (emitTimer.current !== null) {
+      window.clearTimeout(emitTimer.current)
+      emitTimer.current = null
+    }
+  }, [])
+
+  const scheduleEmit = useCallback(
+    (editor: Editor) => {
+      clearEmitTimer()
+      emitTimer.current = window.setTimeout(() => {
+        emitTimer.current = null
+        if (!editor.isDestroyed) emitNow(editor)
+      }, DRAFT_DEBOUNCE_MS)
+    },
+    [clearEmitTimer, emitNow],
+  )
+
+  const flushEmit = useCallback(
+    (editor: Editor): string => {
+      clearEmitTimer()
+      return emitNow(editor)
+    },
+    [clearEmitTimer, emitNow],
+  )
+
+  const requestSubmit = useCallback(
+    (editor: Editor) => {
+      if (editor.isEmpty) return
+      const markdown = flushEmit(editor)
+      setPendingSubmit(markdown)
+    },
+    [flushEmit],
+  )
+
+  /**
+   * D8 — pasted text. A single URL becomes a link whose text is the URL; text
+   * that parses within the subset is parsed as markdown; anything else — a
+   * plain paste (Shift), or markdown holding a table, raw HTML, an h4 — lands
+   * as literal paragraphs so no character is dropped.
+   */
+  const parsePastedText = useCallback(
+    (text: string, plain: boolean, view: EditorView): Slice => {
+      const { schema } = view.state
+      const trimmed = text.trim()
+      const linkType = schema.marks['link']
+      const paragraphType = schema.nodes['paragraph']
+      if (linkType !== undefined && BARE_URL.test(trimmed)) {
+        const href = /^www\./i.test(trimmed) ? `https://${trimmed}` : trimmed
+        return new Slice(Fragment.from(schema.text(trimmed, [linkType.create({ href })])), 0, 0)
+      }
+      if (!plain && isRichEditable(text)) {
+        try {
+          const doc = ProseMirrorNode.fromJSON(schema, parseRichMarkdown(text))
+          doc.check()
+          return Slice.maxOpen(doc.content)
+        } catch {
+          // Fall through to literal text; nothing is dropped either way.
+        }
+      }
+      if (paragraphType === undefined) return Slice.empty
+      const paragraphs = text
+        .split(/\r\n?|\n/)
+        .map((line) => paragraphType.create(null, line === '' ? null : schema.text(line)))
+      return Slice.maxOpen(Fragment.from(paragraphs))
+    },
+    [],
+  )
+
+  /**
+   * One `render()` per trigger, both drawing the same `<SuggestionList>`
+   * (ADR-149 D1). The closure per plugin owns exactly two things: the portal
+   * element the popup lives in, and the `unmount` that floating-ui hands back.
+   *
+   * The rows are recomputed here from `props.query` rather than read off
+   * `props.items`, because `@tiptap/suggestion` types its items as `any` and
+   * this file does not take `any` (CLAUDE.md §3). The plugin still owns the
+   * threshold — below `minQueryLength` it reports an empty query's worth of
+   * items and we close, which is the same door "no matches" comes through.
+   */
+  const makeSuggestionRenderer = useCallback(
+    (kind: SuggestionKind) => {
+      let container: HTMLElement | null = null
+      let unmount: (() => void) | null = null
+      let lastQuery: string | null = null
+
+      const rowsFor = (query: string): SuggestionRows => {
+        // D4: a bare sigil is punctuation, not a trigger.
+        if (query.length < SUGGESTION_MIN_QUERY[kind]) return EMPTY_ROWS
+        if (kind === 'emoji') return emojiRows(query)
+        const items = latest.current.mentionItems?.(query)
+        return items === undefined ? EMPTY_ROWS : mentionRows(items)
+      }
+
+      const close = () => {
+        if (unmount !== null) {
+          unmount()
+          unmount = null
+        }
+        container = null
+        lastQuery = null
+        if (suggestionRef.current?.kind === kind) suggestionRef.current = null
+        setSuggestion((prev) => (prev !== null && prev.kind === kind ? null : prev))
+      }
+
+      const sync = (props: SuggestionRenderProps) => {
+        const rows = rowsFor(props.query)
+        // D4: nothing to show is one of the four things that mean "no".
+        if (rows.options.length === 0) {
+          close()
+          return
+        }
+        const opening = container === null
+        let element = container
+        if (element === null) {
+          element = document.createElement('div')
+          element.className = 'ds-thread-suggestions-anchor'
+          container = element
+          // The plugin owns anchoring — it re-reads the caret rect on scroll,
+          // resize and layout shift. `onPosition` is what keeps it from
+          // hiding the element until it has measured, which would make the
+          // popup invisible to a jsdom role query for no benefit.
+          const anchored = element
+          unmount = props.mount(element, {
+            onPosition: ({ x, y, strategy }) => {
+              anchored.style.position = strategy
+              anchored.style.left = `${String(x)}px`
+              anchored.style.top = `${String(y)}px`
+            },
+          })
+        }
+        // The plugin dispatches `started` and `updated` for one keystroke;
+        // redrawing the same query would also reset the active option under a
+        // user who had already arrowed down. The ref is refreshed on the SAME
+        // side of this gate as the drawn rows, deliberately: `attrs` is what
+        // an index resolves against, so letting it move while the options on
+        // screen stay put would let Enter insert a row nobody was looking at.
+        if (!opening && lastQuery === props.query) return
+        suggestionRef.current = { kind, attrs: rows.attrs, command: props.command }
+        lastQuery = props.query
+        setActiveOption(0)
+        setBubble(false)
+        setSuggestion({ kind, container: element, options: rows.options })
+        // A `role="textbox"` cannot carry `aria-expanded` (ARIA reserves it
+        // for combobox), so nothing in the markup tells a screen-reader user
+        // the popup appeared. One polite line at OPEN does — once per
+        // session, not once per keystroke, because a count that re-announces
+        // on every letter is worse than no count at all.
+        if (opening) {
+          latest.current.announce?.(
+            `${String(rows.options.length)} ${SUGGESTION_NOUNS[kind]} suggestions. Use the arrow keys to choose, Enter to insert, Escape to close.`,
+          )
+        }
+      }
+
+      return {
+        onStart: sync,
+        onUpdate: sync,
+        onExit: close,
+        // Escape, the arrows, Enter and Tab are all answered in
+        // `handleKeyDown` below — `editorProps` handlers run before any
+        // plugin's, which is what makes ADR-148 D9's Escape order a fact.
+        onKeyDown: () => false,
+      }
+    },
+    [setActiveOption, setBubble],
+  )
+
+  const editor = useEditor(
+    {
+      extensions: [
+        ...richSubsetExtensions({
+          mention: { render: () => makeSuggestionRenderer('mention') },
+          emoji: { render: () => makeSuggestionRenderer('emoji') },
+        }),
+        Placeholder.configure({ placeholder }),
+      ],
+      content: value,
+      contentType: 'markdown',
+      editable: !disabled,
+      autofocus: autoFocus ? 'end' : false,
+      // D8 is implemented once, in `clipboardTextParser` below. TipTap's
+      // regex paste rules (bold, italic, strike, code, …) would run a second,
+      // looser pass over the pasted text — and re-format a Shift-paste that
+      // was meant to stay literal. Input rules (typing `**x**`, `- `, `---`)
+      // are unaffected.
+      enablePasteRules: false,
+      editorProps: {
+        /**
+         * THE fix for "the entire viewport is scrolling down" on Enter.
+         *
+         * ProseMirror scrolls the selection into view after any transaction
+         * that asks for it — every Enter, every arrow key, most typing. Its
+         * `scrollRectIntoView` walks UP from the editor and scrolls *every*
+         * scrollable ancestor it finds until the caret is visible: the
+         * thread's own body, then `PageShell`'s content region, then whatever
+         * else. Capping the editor's height does not stop that; it only
+         * changes which ancestor moves. The ancestors have to be taken out of
+         * the walk entirely, and this hook is the only supported way to do it.
+         *
+         * Returning `true` means "handled — do not run the default". We then
+         * do the one scroll that is legitimate: bring the caret into view
+         * inside the EDITOR, and touch nothing else. `scrollTop` on a single
+         * element cannot chain.
+         */
+        handleScrollToSelection: (view) => {
+          const dom = view.dom as HTMLElement
+          const head = view.state.selection.head
+          let caret: { top: number; bottom: number }
+          try {
+            caret = view.coordsAtPos(head)
+          } catch {
+            // A position with no coords yet (mid-reconfigure). Nothing to
+            // scroll to, and the default would be no better.
+            return true
+          }
+          const box = dom.getBoundingClientRect()
+          // One line of slack so the caret is never flush against the edge.
+          const pad = parseFloat(getComputedStyle(dom).lineHeight) || 0
+          dom.scrollTop += caretScrollDelta(box, caret, pad)
+          return true
+        },
+        attributes: {
+          role: 'textbox',
+          'aria-multiline': 'true',
+          'aria-labelledby': labelId,
+          'aria-describedby': hintId,
+        },
+        handleDOMEvents: {
+          // D9: Tab is never captured. Returning true here skips ProseMirror's
+          // own keydown handling (and every keymap) without preventDefault, so
+          // the browser moves focus. ADR-149 D5 is the one exception: while a
+          // suggestion popup is open Tab INSERTS, so this stands down and
+          // `handleKeyDown` answers it (and does preventDefault, so focus
+          // stays where it already is — on the editor).
+          keydown: (_view, event) => isPlainTab(event) && suggestionRef.current === null,
+          compositionstart: () => {
+            composing.current = true
+            setBubble(false)
+            return false
+          },
+          compositionend: () => {
+            composing.current = false
+            return false
+          },
+        },
+        handleKeyDown: (view, event) => {
+          const editorFromView = editorRef.current
+          if (editorFromView === null) return false
+          const mod = event.metaKey || event.ctrlKey
+          if (event.key === 'Escape') {
+            if (bubbleOpenRef.current) {
+              dismissBubble(editorFromView)
+              return true
+            }
+            const openSuggestion = suggestionRef.current
+            if (openSuggestion !== null) {
+              // D5 / AC#7: close WITHOUT inserting, and do not fall through to
+              // the reply composer's cancel — that is the third slot, not the
+              // second. The plugin also records the range as dismissed, so the
+              // popup does not spring back on the next keystroke.
+              exitSuggestionPlugin(view, openSuggestion.kind)
+              return true
+            }
+            const cancel = latest.current.onCancel
+            if (cancel !== undefined) {
+              cancel()
+              return true
+            }
+            return false
+          }
+          if (mod && event.key === 'Enter') {
+            requestSubmit(editorFromView)
+            return true
+          }
+          // ADR-149 D5 — the popup's keys, intercepted before the editor's own
+          // keymap. Every one of them is unmodified: Cmd+Enter above still
+          // sends, and Shift+Enter still makes a hard break.
+          const navigating = suggestionRef.current
+          if (navigating !== null && !mod && !event.altKey && !event.shiftKey) {
+            const count = navigating.attrs.length
+            if (event.key === 'ArrowDown') {
+              setActiveOption(wrapIndex(activeIndexRef.current, count, 1))
+              return true
+            }
+            if (event.key === 'ArrowUp') {
+              setActiveOption(wrapIndex(activeIndexRef.current, count, -1))
+              return true
+            }
+            if (event.key === 'Enter' || event.key === 'Tab') {
+              commitSuggestion(activeIndexRef.current)
+              return true
+            }
+          }
+          if (mod && event.shiftKey && !event.altKey && event.key.toLowerCase() === 'x') {
+            editorFromView.chain().focus().toggleStrike().run()
+            return true
+          }
+          if (mod && event.key === '.') {
+            if (!shouldShowBubble(editorFromView)) return false
+            dismissedSelection.current = null
+            setBubble(true)
+            setLinkMode(false)
+            setRovingIndex(0)
+            setFocusRequest('toolbar')
+            return true
+          }
+          if (mod && !event.shiftKey && !event.altKey && event.key.toLowerCase() === 'k') {
+            if (editorFromView.isActive('link') && view.state.selection.empty) {
+              editorFromView.commands.extendMarkRange('link')
+            }
+            if (!shouldShowBubble(editorFromView)) return true
+            dismissedSelection.current = null
+            setBubble(true)
+            setLinkDraft(readHref(editorFromView))
+            setLinkError(false)
+            setLinkMode(true)
+            setFocusRequest('link')
+            return true
+          }
+          return false
+        },
+        handlePaste: (_view, event) => {
+          const dt = event.clipboardData
+          if (!dt || dt.files.length > 0 || dt.types.includes('text/html')) return false
+          return attachments.addPastedText(dt.getData('text/plain'))
+        },
+        clipboardTextParser: (text, _context, plain, view) => parsePastedText(text, plain, view),
+      },
+      onCreate: ({ editor: created }) => {
+        editorRef.current = created
+      },
+      onUpdate: ({ editor: updated }) => {
+        setPendingSubmit(null)
+        scheduleEmit(updated)
+        syncBubble(updated)
+      },
+      onSelectionUpdate: ({ editor: updated }) => {
+        syncBubble(updated)
+      },
+      onFocus: ({ editor: focused }) => {
+        syncBubble(focused)
+      },
+      onBlur: ({ editor: blurred, event }) => {
+        flushEmit(blurred)
+        const next = event.relatedTarget
+        const insideMenu = next instanceof Node && bubbleRef.current?.contains(next) === true
+        if (!insideMenu) setBubble(false)
+        // D4: blur is one of the four things that close the popup. Clicking an
+        // option cannot reach here — the option's `mousedown` is prevented, so
+        // the editor never loses focus (D5, AC#6).
+        const openSuggestion = suggestionRef.current
+        if (openSuggestion !== null) exitSuggestionPlugin(blurred.view, openSuggestion.kind)
+      },
+    },
+    [],
+  )
+
+  useLayoutEffect(() => {
+    editorRef.current = editor
+  }, [editor])
+
+  useEffect(() => {
+    onEditor?.(editor)
+    return () => {
+      onEditor?.(null)
+    }
+  }, [editor, onEditor])
+
+  useEffect(() => {
+    editor.setEditable(!disabled)
+  }, [disabled, editor])
+
+  const insertPastedText = useCallback(
+    (localId: string) => {
+      const text = attachments.insertAsText(localId)
+      if (text === null) return
+      const slice = parsePastedText(text, true, editor.view)
+      editor.view.dispatch(editor.state.tr.replaceSelection(slice).scrollIntoView())
+      editor.commands.focus()
+    },
+    [attachments, editor, parsePastedText],
+  )
+
+  // An external `value` — a resumed draft, a reset after send — replaces the
+  // document. Our own emissions never come back through here, and a pending
+  // emission is dropped rather than allowed to resurrect what was just replaced.
+  useEffect(() => {
+    if (value === lastEmitted.current) return
+    clearEmitTimer()
+    lastEmitted.current = value
+    editor.commands.setContent(value, { contentType: 'markdown', emitUpdate: false })
+  }, [clearEmitTimer, editor, value])
+
+  // Send fires once the parent holds what was flushed AND every upload has a
+  // verified ticket. Uploading never disables Send: pressing it records the
+  // intent here, then this effect finishes the post when the last ticket lands.
+  useEffect(() => {
+    if (pendingSubmit === null || value !== pendingSubmit || attachments.isUploading) return
+    if (attachments.attachments.some((attachment) => attachment.state !== 'ready')) return
+    setPendingSubmit(null)
+    onSubmit(attachments.ticketIds.length === 0 ? undefined : attachments.ticketIds)
+    attachments.clear()
+  }, [attachments, onSubmit, pendingSubmit, value])
+
+  // Unmount: keystrokes still inside the debounce window reach the draft —
+  // unless the parent moved on in the meantime, in which case they are stale
+  // and must not clobber what replaced them.
+  useEffect(
+    () => () => {
+      if (emitTimer.current === null) return
+      window.clearTimeout(emitTimer.current)
+      emitTimer.current = null
+      if (latest.current.value === lastEmitted.current && !editor.isDestroyed) emitNow(editor)
+    },
+    [editor, emitNow],
+  )
+
+  // D10 — the counter's polite announcement at 90 %, once per crossing.
+  const announced = useRef(false)
+  useEffect(() => {
+    if (maxLength === undefined) return
+    const over = value.length > maxLength * 0.9
+    if (over && !announced.current) {
+      announced.current = true
+      announce?.(
+        `Approaching the comment length limit: ${String(value.length)} of ${String(maxLength)} characters`,
+      )
+    } else if (!over) {
+      announced.current = false
+    }
+  }, [announce, maxLength, value.length])
+
+  /**
+   * D5 — the editor is the accessible OWNER of the popup. It keeps DOM focus,
+   * points at the listbox with `aria-controls`, and names the active option
+   * with `aria-activedescendant`; nothing inside the popup is ever focused.
+   *
+   * Written straight onto the contenteditable because `editorProps.attributes`
+   * are fixed when the editor is created. That is safe: ProseMirror's document
+   * decoration only removes attribute names IT set on a previous pass, so a
+   * name it has never seen survives every transaction.
+   */
+  useLayoutEffect(() => {
+    if (editor.isDestroyed) return
+    const dom = editor.view.dom
+    if (suggestion === null) {
+      dom.removeAttribute('aria-controls')
+      dom.removeAttribute('aria-activedescendant')
+      return
+    }
+    dom.setAttribute('aria-controls', listboxId)
+    dom.setAttribute('aria-activedescendant', optionDomId(activeIndex))
+  }, [activeIndex, editor, listboxId, optionDomId, suggestion])
+
+  // Keyboard-opened menu (D7): focus lands on the first button or the link field.
+  useEffect(() => {
+    if (focusRequest === null || !bubbleOpen) return
+    const target =
+      focusRequest === 'link' ? linkInputRef.current : focusableButtons(bubbleRef.current)[0]
+    if (target instanceof HTMLElement) {
+      target.focus()
+      setFocusRequest(null)
+    }
+  }, [bubbleOpen, focusRequest, linkMode])
+
+  const active = useEditorState({
+    editor,
+    selector: ({ editor: current }) => ({
+      isEmpty: current.isEmpty,
+      bold: current.isActive('bold'),
+      italic: current.isActive('italic'),
+      underline: current.isActive('underline'),
+      strike: current.isActive('strike'),
+      code: current.isActive('code'),
+      link: current.isActive('link'),
+      h1: current.isActive('heading', { level: 1 }),
+      h2: current.isActive('heading', { level: 2 }),
+      h3: current.isActive('heading', { level: 3 }),
+      bulletList: current.isActive('bulletList'),
+      orderedList: current.isActive('orderedList'),
+      blockquote: current.isActive('blockquote'),
+      codeBlock: current.isActive('codeBlock'),
+    }),
+  })
+
+  const overLimit = maxLength !== undefined && value.length > maxLength
+  const canSend =
+    !active.isEmpty &&
+    !sending &&
+    !disabled &&
+    !overLimit &&
+    pendingSubmit === null &&
+    !attachments.attachments.some((attachment) => attachment.state === 'failed')
+
+  /* ── Bubble menu actions ───────────────────────────────────────────────── */
+
+  const openLinkField = useCallback(() => {
+    setLinkDraft(readHref(editor))
+    setLinkError(false)
+    setLinkMode(true)
+    setFocusRequest('link')
+  }, [editor])
+
+  const applyLink = useCallback(() => {
+    const href = normalizeHref(linkDraft)
+    if (href === null) {
+      setLinkError(true)
+      return
+    }
+    const applied = editor.chain().focus().extendMarkRange('link').setLink({ href }).run()
+    if (!applied) {
+      setLinkError(true)
+      return
+    }
+    setLinkMode(false)
+    setLinkError(false)
+  }, [editor, linkDraft])
+
+  const removeLink = useCallback(() => {
+    editor.chain().focus().extendMarkRange('link').unsetLink().run()
+    setLinkMode(false)
+    setLinkError(false)
+  }, [editor])
+
+  const closeLinkField = useCallback(() => {
+    setLinkMode(false)
+    setLinkError(false)
+    setRovingIndex(BUBBLE_ACTIONS.length - 1)
+    setFocusRequest('toolbar')
+  }, [])
+
+  /** Roving focus across the bubble toolbar; Escape returns to the editor. */
+  const onToolbarKeyDown = useCallback(
+    (event: ReactKeyboardEvent<HTMLDivElement>) => {
+      const buttons = focusableButtons(event.currentTarget)
+      const current = buttons.findIndex((button) => button === document.activeElement)
+      const move = (index: number) => {
+        const next = buttons[(index + buttons.length) % buttons.length]
+        if (next === undefined) return
+        setRovingIndex(buttons.indexOf(next))
+        next.focus()
+      }
+      switch (event.key) {
+        case 'ArrowRight':
+        case 'ArrowDown':
+          event.preventDefault()
+          move(current + 1)
+          return
+        case 'ArrowLeft':
+        case 'ArrowUp':
+          event.preventDefault()
+          move(current - 1)
+          return
+        case 'Home':
+          event.preventDefault()
+          move(0)
+          return
+        case 'End':
+          event.preventDefault()
+          move(buttons.length - 1)
+          return
+        case 'Escape':
+          event.preventDefault()
+          event.stopPropagation()
+          dismissBubble(editor)
+          editor.commands.focus()
+          return
+        default:
+          return
+      }
+    },
+    [dismissBubble, editor],
+  )
+
+  const onLinkFieldKeyDown = useCallback(
+    (event: ReactKeyboardEvent<HTMLInputElement>) => {
+      if (event.key === 'Enter') {
+        event.preventDefault()
+        applyLink()
+      } else if (event.key === 'Escape') {
+        event.preventDefault()
+        event.stopPropagation()
+        closeLinkField()
+      }
+    },
+    [applyLink, closeLinkField],
+  )
+
+  const bubbleActive: Readonly<Record<BubbleAction, boolean>> = {
+    bold: active.bold,
+    italic: active.italic,
+    underline: active.underline,
+    strike: active.strike,
+    code: active.code,
+    link: active.link,
+  }
+
+  const runBubbleAction = useCallback(
+    (action: BubbleAction) => {
+      switch (action) {
+        case 'bold':
+          editor.chain().focus().toggleBold().run()
+          return
+        case 'italic':
+          editor.chain().focus().toggleItalic().run()
+          return
+        case 'underline':
+          editor.chain().focus().toggleUnderline().run()
+          return
+        case 'strike':
+          editor.chain().focus().toggleStrike().run()
+          return
+        case 'code':
+          editor.chain().focus().toggleCode().run()
+          return
+        case 'link':
+          openLinkField()
+          return
+      }
+    },
+    [editor, openLinkField],
+  )
+
+  const runBlockAction = useCallback(
+    (action: BlockAction) => {
+      const chain = editor.chain().focus()
+      switch (action) {
+        case 'h1':
+          chain.toggleHeading({ level: 1 }).run()
+          return
+        case 'h2':
+          chain.toggleHeading({ level: 2 }).run()
+          return
+        case 'h3':
+          chain.toggleHeading({ level: 3 }).run()
+          return
+        case 'bulletList':
+          chain.toggleBulletList().run()
+          return
+        case 'orderedList':
+          chain.toggleOrderedList().run()
+          return
+        case 'blockquote':
+          chain.toggleBlockquote().run()
+          return
+        case 'codeBlock':
+          chain.toggleCodeBlock().run()
+          return
+        case 'divider':
+          chain.setHorizontalRule().run()
+          return
+      }
+    },
+    [editor],
+  )
+
+  const blockActive: Readonly<Record<BlockAction, boolean>> = {
+    h1: active.h1,
+    h2: active.h2,
+    h3: active.h3,
+    bulletList: active.bulletList,
+    orderedList: active.orderedList,
+    blockquote: active.blockquote,
+    codeBlock: active.codeBlock,
+    divider: false,
+  }
+
+  const shellStyle: StyleWithVars = {
+    // Concentric: the host panel declares --thread-inner-radius as its own
+    // radius minus its padding. Nothing here eyeballs a corner.
+    borderRadius: 'var(--thread-inner-radius, var(--radius-sm))',
+    borderColor: 'rgb(var(--border))',
+    background: 'rgb(var(--surface-card))',
+    '--composer-rows': String(rows),
+  }
+
+  const controlsDisabled = disabled || sending || pendingSubmit !== null
+
+  return (
+    <div className={cn('flex flex-col gap-[var(--space-1)]', className)}>
+      {replyingTo === undefined ? null : (
+        <p
+          className="flex items-center gap-[var(--space-1)] text-[12px]"
+          style={{ color: 'rgb(var(--text-tertiary))' }}
+        >
+          <CornerDownRight size={10} strokeWidth={1.5} aria-hidden="true" />
+          Replying to{' '}
+          <span className="font-semibold" style={{ color: 'rgb(var(--text-secondary))' }}>
+            {replyingTo}
+          </span>
+        </p>
+      )}
+      <div className="flex items-start gap-[var(--space-2)]">
+        {avatar}
+        <AttachmentDropZone
+          onFiles={attachments.addFiles}
+          disabled={controlsDisabled || uploadAttachment === undefined}
+          className="min-w-0 flex-1"
+        >
+          <div
+            ref={shellRef}
+            className={cn(
+              'ds-thread-rich-composer relative min-w-0 w-full border',
+              'transition-[border-color,box-shadow] duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+              'motion-reduce:transition-none',
+              'focus-within:border-[rgb(var(--accent))] focus-within:[box-shadow:var(--ring-focus)]',
+            )}
+            style={shellStyle}
+          >
+          {/* A contenteditable has no implicit name; these two are what the
+              textbox points at (D10). */}
+          <span id={labelId} className="sr-only">
+            {label}
+          </span>
+          <span id={hintId} className="sr-only">
+            {`${MOD_NAME}+Enter sends. ${MOD_NAME}+Period opens the formatting menu on a selection. Type @ to mention someone, or a colon and two letters for emoji, then use the arrow keys and Enter. Escape closes the menu${onCancel === undefined ? '' : ', then cancels the reply'}.`}
+          </span>
+
+          <EditorContent editor={editor} />
+
+          {/* ADR-149 — ONE popup for both triggers. It is portalled into the
+              element the Suggestion plugin mounts and anchors (floating-ui,
+              already a dependency of that plugin), so it escapes the thread's
+              own scroll clipping. It is still the editor's, through
+              `aria-controls` above. */}
+          {suggestion === null
+            ? null
+            : createPortal(
+                <SuggestionList
+                  id={listboxId}
+                  label={SUGGESTION_LABELS[suggestion.kind]}
+                  options={suggestion.options}
+                  activeIndex={activeIndex}
+                  optionId={optionDomId}
+                  onSelect={commitSuggestion}
+                  onActivate={setActiveOption}
+                />,
+                suggestion.container,
+              )}
+
+          <BubbleMenu
+            ref={bubbleRef}
+            editor={editor}
+            pluginKey={BUBBLE_MENU_KEY}
+            updateDelay={0}
+            shouldShow={({ editor: current }) => shouldShowBubble(current)}
+            appendTo={() => shellRef.current ?? document.body}
+            options={{
+              placement: 'top',
+              offset: readSpaceToken(shellRef.current, '--space-2', 8),
+              flip: true,
+              shift: true,
+            }}
+            className="ds-thread-bubble-menu"
+            data-open={bubbleOpen}
+          >
+            {!bubbleOpen ? null : linkMode ? (
+              <div
+                role="group"
+                aria-label="Link"
+                className="flex items-center gap-[var(--space-1)]"
+                style={{
+                  padding: 'var(--space-1)',
+                  background: 'rgb(var(--surface-card))',
+                  border: '1px solid rgb(var(--border))',
+                  borderRadius: 'var(--radius-sm)',
+                  boxShadow: 'var(--shadow-lg)',
+                }}
+              >
+                <input
+                  ref={linkInputRef}
+                  type="url"
+                  aria-label="Link URL"
+                  aria-invalid={linkError}
+                  {...(linkError ? { 'aria-describedby': linkErrorId } : {})}
+                  placeholder="https://"
+                  value={linkDraft}
+                  onChange={(event) => {
+                    setLinkDraft(event.target.value)
+                    setLinkError(false)
+                  }}
+                  onKeyDown={onLinkFieldKeyDown}
+                  className="min-w-0 bg-transparent text-[12.5px] outline-none"
+                  style={{
+                    inlineSize: '22ch',
+                    blockSize: 'var(--ctrl-sm)',
+                    paddingInline: 'var(--space-2)',
+                    color: 'rgb(var(--foreground))',
+                    borderRadius: 'var(--radius-xs)',
+                    border: linkError
+                      ? '1px solid rgb(var(--warning))'
+                      : '1px solid rgb(var(--border))',
+                  }}
+                />
+                <Button
+                  variant="icon"
+                  size="sm"
+                  aria-label="Apply link"
+                  title="Apply link"
+                  onMouseDown={(event) => {
+                    event.preventDefault()
+                  }}
+                  onClick={applyLink}
+                >
+                  <Check size={12} strokeWidth={2} aria-hidden="true" />
+                </Button>
+                {active.link ? (
+                  <Button
+                    variant="icon"
+                    size="sm"
+                    aria-label="Remove link"
+                    title="Remove link"
+                    onMouseDown={(event) => {
+                      event.preventDefault()
+                    }}
+                    onClick={removeLink}
+                  >
+                    <Unlink size={12} strokeWidth={1.75} aria-hidden="true" />
+                  </Button>
+                ) : null}
+                <Button
+                  variant="icon"
+                  size="sm"
+                  aria-label="Close link field"
+                  title="Close"
+                  onMouseDown={(event) => {
+                    event.preventDefault()
+                  }}
+                  onClick={closeLinkField}
+                >
+                  <X size={12} strokeWidth={1.75} aria-hidden="true" />
+                </Button>
+                {linkError ? (
+                  <span id={linkErrorId} role="alert" className="sr-only">
+                    Enter a web, email or phone link.
+                  </span>
+                ) : null}
+              </div>
+            ) : (
+              <div
+                role="toolbar"
+                aria-label="Format selection"
+                aria-orientation="horizontal"
+                onKeyDown={onToolbarKeyDown}
+              >
+                {BUBBLE_ACTIONS.map((action, index) => {
+                  const Icon = action.icon
+                  return (
+                    <Button
+                      key={action.id}
+                      variant="icon"
+                      size="sm"
+                      aria-label={action.label}
+                      aria-pressed={bubbleActive[action.id]}
+                      title={`${action.label} (${MOD_NAME}+${action.keycap})`}
+                      tabIndex={index === rovingIndex ? 0 : -1}
+                      onMouseDown={(event) => {
+                        // Keep the editor's selection: a click here must
+                        // format it, not collapse it.
+                        event.preventDefault()
+                      }}
+                      onClick={() => {
+                        runBubbleAction(action.id)
+                      }}
+                    >
+                      <Icon size={12} strokeWidth={1.75} aria-hidden="true" />
+                    </Button>
+                  )
+                })}
+              </div>
+            )}
+          </BubbleMenu>
+
+          <AttachmentTray
+            attachments={attachments.attachments}
+            onRemove={attachments.remove}
+            onInsertAsText={insertPastedText}
+            className="px-[var(--space-2)]"
+          />
+
+          {/* Switching composer implementations would unmount this hook and
+              discard its local upload tickets. Remove the chips first; never
+              turn a mode switch into a silent attachment loss. */}
+          <ComposerFooter
+            {...(mode === undefined ? {} : { mode })}
+            {...(onModeChange === undefined ? {} : { onModeChange })}
+            modeDisabled={controlsDisabled || attachments.attachments.length > 0}
+            toolbar={
+              <>
+                {uploadAttachment === undefined ? null : (
+                  <AttachmentButton
+                    onFiles={attachments.addFiles}
+                    accept={attachmentAccept ?? ATTACHMENT_ACCEPT}
+                    disabled={controlsDisabled}
+                  />
+                )}
+                {attachGif === undefined || searchGifs === undefined ? null : (
+                  <Popover open={gifPickerOpen} onOpenChange={setGifPickerOpen}>
+                    <Popover.Trigger asChild>
+                      <Button
+                        variant="icon"
+                        size="sm"
+                        aria-label="Choose a GIF"
+                        title="Choose a GIF"
+                        disabled={controlsDisabled}
+                      >
+                        <Images size={12} strokeWidth={1.75} aria-hidden="true" />
+                      </Button>
+                    </Popover.Trigger>
+                    <Popover.Content
+                      aria-label="Choose a GIF"
+                      align="start"
+                      className="p-[var(--space-3)]"
+                      style={{
+                        inlineSize: 'calc(var(--space-12) * 8)',
+                        maxInlineSize: 'calc(100vw - var(--space-6))',
+                      }}
+                    >
+                      <GifPicker
+                        search={searchGifs}
+                        onPick={(gif) => {
+                          attachments.addGif(gif)
+                          setGifPickerOpen(false)
+                        }}
+                      />
+                    </Popover.Content>
+                  </Popover>
+                )}
+                {toolbar
+              ? BLOCK_ACTIONS.map((action) => {
+                  const Icon = action.icon
+                  return (
+                    <Button
+                      key={action.id}
+                      variant="icon"
+                      size="sm"
+                      aria-label={action.label}
+                      title={action.label}
+                      {...(action.id === 'divider' ? {} : { 'aria-pressed': blockActive[action.id] })}
+                      disabled={controlsDisabled}
+                      onMouseDown={(event) => {
+                        event.preventDefault()
+                      }}
+                      onClick={() => {
+                        runBlockAction(action.id)
+                      }}
+                    >
+                      <Icon size={12} strokeWidth={1.75} aria-hidden="true" />
+                    </Button>
+                  )
+                })
+              : null}
+              </>
+            }
+            meta={
+              <>
+                {maxLength === undefined ? null : (
+              <span
+                className="tabular-nums text-right"
+                // Reserved slot so the counter cannot push the buttons around.
+                style={{
+                  minInlineSize: '7ch',
+                  fontSize: '11.5px',
+                  color:
+                    value.length > maxLength * 0.9
+                      ? 'rgb(var(--warning-ink))'
+                      : 'rgb(var(--text-tertiary))',
+                }}
+              >
+                {value.length}/{maxLength}
+              </span>
+            )}
+              </>
+            }
+            actions={
+              <>
+                {onCancel === undefined ? null : (
+              <Button variant="secondary" size="sm" onClick={onCancel} disabled={controlsDisabled}>
+                {cancelLabel}
+              </Button>
+            )}
+            <Button
+              variant="primary"
+              size="sm"
+              onClick={() => {
+                requestSubmit(editor)
+              }}
+              disabled={!canSend}
+              aria-label={sending ? 'Sending…' : submitLabel}
+              trailingIcon={
+                <span aria-hidden="true" className="ds-composer-keycap">
+                  <Kbd size="sm" tone="on-accent">
+                    {SEND_KEYCAP}
+                  </Kbd>
+                </span>
+              }
+            >
+              {sending ? 'Sending…' : submitLabel}
+            </Button>
+              </>
+            }
+          />
+          </div>
+        </AttachmentDropZone>
+      </div>
+    </div>
+  )
+}
+
+function readHref(editor: Editor): string {
+  const href = editor.getAttributes('link')['href']
+  return typeof href === 'string' ? href : ''
+}
+
+/* ── The two action tables ────────────────────────────────────────────────── */
+
+type BubbleAction = 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'link'
+
+interface BubbleActionSpec {
+  readonly id: BubbleAction
+  readonly label: string
+  readonly icon: typeof Bold
+  readonly keycap: string
+}
+
+/** D7: six actions on a real selection, nothing else. */
+const BUBBLE_ACTIONS: readonly BubbleActionSpec[] = [
+  { id: 'bold', label: 'Bold', icon: Bold, keycap: 'B' },
+  { id: 'italic', label: 'Italic', icon: Italic, keycap: 'I' },
+  { id: 'underline', label: 'Underline', icon: UnderlineIcon, keycap: 'U' },
+  { id: 'strike', label: 'Strikethrough', icon: Strikethrough, keycap: 'Shift+X' },
+  { id: 'code', label: 'Code', icon: Code, keycap: 'E' },
+  { id: 'link', label: 'Link', icon: LinkIcon, keycap: 'K' },
+]
+
+type BlockAction =
+  | 'h1'
+  | 'h2'
+  | 'h3'
+  | 'bulletList'
+  | 'orderedList'
+  | 'blockquote'
+  | 'codeBlock'
+  | 'divider'
+
+interface BlockActionSpec {
+  readonly id: BlockAction
+  readonly label: string
+  readonly icon: typeof Bold
+}
+
+/** The persistent row: block-level actions act on the block, not the selection. */
+const BLOCK_ACTIONS: readonly BlockActionSpec[] = [
+  { id: 'h1', label: 'Heading 1', icon: Heading1 },
+  { id: 'h2', label: 'Heading 2', icon: Heading2 },
+  { id: 'h3', label: 'Heading 3', icon: Heading3 },
+  { id: 'bulletList', label: 'Bulleted list', icon: List },
+  { id: 'orderedList', label: 'Numbered list', icon: ListOrdered },
+  { id: 'blockquote', label: 'Quote', icon: TextQuote },
+  { id: 'codeBlock', label: 'Code block', icon: SquareCode },
+  { id: 'divider', label: 'Divider', icon: Minus },
+]