@puredesktop/platform-editor 1.0.0-beta.1

package/src/DocumentEditor.tsx

@@ -0,0 +1,2631 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from 'react'
+import type { Editor } from '@tiptap/core'
+import { migrateMathStrings } from '@tiptap/extension-mathematics'
+import { EditorContent, EditorContext, useEditor } from '@tiptap/react'
+import type { Extensions } from '@tiptap/react'
+import { styled } from 'styled-components'
+import { CloseOutlined, CommentOutlined } from '@ant-design/icons'
+import {
+  applyCommentMarkToRange,
+  applyCommentReplacementById,
+  COMMENT_STATUS_LABELS,
+  COMMENT_TYPE_DEFINITIONS,
+  COMMENT_TYPE_LABELS,
+  defaultCommentReviewStatusForType,
+  defaultCommentSeverityForType,
+  normalizeCommentReviewStatus,
+  normalizeCommentSeverity,
+  normalizeCommentType,
+  parseCommentReplies,
+  removeAllCommentMarks,
+  removeCommentMarksById,
+  serializeCommentReplies,
+  stripCommentMarkupFromHtml,
+  updateCommentMarksById,
+  type CommentMarkAttrPatch,
+  type CommentReply,
+  type CommentReviewStatus,
+  type CommentSeverity,
+  type CommentType,
+} from './commentUtils.js'
+import {
+  resolveEditorContent,
+  type EditorInputFormat,
+} from './contentFormat.js'
+import {
+  createDefaultSlashCommands,
+  SlashCommands,
+  type SlashCommandItem,
+} from './extensions/slashCommands.js'
+import {
+  applyAutoReviewFindings,
+  collectScopedAutoReviewParagraphs,
+  runAutoReview as runEditorAutoReview,
+  type AutoReviewFindingInput,
+  type AutoReviewParagraph,
+  type RunAutoReviewOptions,
+  type RunAutoReviewResult,
+} from './extensions/autoReviewPrompts.js'
+import { toMd } from './utils/markdownUtils.js'
+import {
+  DocumentEditorRoot,
+  DocumentEditorViewport,
+  DocumentEditorToolbarActions,
+  DocumentEditorToolbarWrap,
+  EditorWrapper,
+} from './styled.js'
+import { Toolbar } from './toolbar/Toolbar.js'
+import type { EditorToolbarOverlays } from './toolbar/overlayTypes.js'
+
+interface ActiveComment {
+  id: string
+  text: string
+  savedText: string
+  commentType: CommentType
+  savedCommentType: CommentType
+  subjectText: string
+  reviewStatus: CommentReviewStatus
+  savedReviewStatus: CommentReviewStatus
+  severity: CommentSeverity
+  author?: string
+  createdAt?: string
+  replies: CommentReply[]
+  resolvedAt?: string
+  resolvedBy?: string
+  x: number
+  y: number
+}
+
+interface SelectionBubbleState {
+  from: number
+  to: number
+  x: number
+  y: number
+  selectedText: string
+}
+
+interface InlineCommentDraft {
+  from: number
+  to: number
+  x: number
+  y: number
+  text: string
+  commentType: CommentType
+  selectedText: string
+}
+
+interface ReviewRailItem {
+  id: string
+  type: CommentType
+  status: CommentReviewStatus
+  resolved: boolean
+  top: number
+  left: number
+}
+
+interface ScrollSnapshot {
+  windowX: number
+  windowY: number
+  entries: Array<{
+    element: HTMLElement
+    left: number
+    top: number
+  }>
+}
+
+const MAX_VISIBLE_REVIEW_RAIL_ITEMS = 18
+const REVIEW_RAIL_SCROLL_IDLE_MS = 160
+const FRESH_COMMENT_HIGHLIGHT_MS = 2200
+const REVIEW_RAIL_COMMENT_TYPES: CommentType[] = [
+  'claim',
+  'fact-check',
+  'source',
+  'thread',
+  'logic',
+  'copyedit',
+  'voice',
+]
+const REVIEW_RAIL_SELECTOR = REVIEW_RAIL_COMMENT_TYPES.map(
+  type => `span[data-comment-id][data-comment-type="${type}"]`,
+).join(', ')
+
+export function isReviewRailCommentType(type: CommentType): boolean {
+  return REVIEW_RAIL_COMMENT_TYPES.includes(type)
+}
+
+export interface DocumentEditorHandle {
+  /** Insert an image or figure using a document `src` the app already chose. */
+  insertImage(options: { src: string; alt?: string; caption?: string }): void
+  /** Insert arbitrary HTML at the cursor. */
+  insertHtml(html: string): void
+  /** Open an existing annotation by id; only scroll when explicitly requested. */
+  openComment(
+    commentId: string,
+    options?: { scrollIntoView?: boolean },
+  ): boolean
+  /** Update an existing annotation mark without changing the selected manuscript text. */
+  updateComment(commentId: string, patch: CommentMarkAttrPatch): boolean
+  /** Accept a suggested edit by replacing its anchored text and leaving an applied-change trace. */
+  applyCommentReplacement(
+    commentId: string,
+    replacementText: string,
+    attrs: {
+      originalText: string
+      sourceType?: string
+      actor?: string
+      createdAt?: string
+    },
+  ): boolean
+  /** Remove an annotation mark without changing the selected manuscript text. */
+  removeComment(commentId: string): boolean
+  /** Remove every annotation mark from the current document. */
+  clearComments(): number
+  /** Run first-pass editorial review and optionally open annotations as they are added. */
+  runAutoReview(
+    options?: RunAutoReviewOptions & {
+      readAlong?: boolean
+      readAlongDelayMs?: number
+    },
+  ): Promise<RunAutoReviewResult>
+  getEditor(): Editor | null
+}
+
+export interface DocumentEditorProps {
+  value: string
+  extensions: Extensions
+  inputFormat?: EditorInputFormat
+  outputFormat?: 'html' | 'markdown'
+  onChange?: (content: string) => void
+  /** Enables toolbar comment marks (in-document only; no host integration). */
+  enableComments?: boolean
+  /**
+   * Show the floating comment bubble on selection. When false, commenting is
+   * still available through the slash menu — used by the quiet page view.
+   */
+  showSelectionComments?: boolean
+  showToolbar?: boolean
+  /**
+   * Chrome level. `'page'` is the quiet/printed view: the toolbar and the
+   * selection comment bubble are hidden and the surface renders as a centered
+   * page. Defaults to `'boxed'` (full chrome) — existing callers are unchanged.
+   */
+  viewMode?: 'boxed' | 'page'
+  toolbarActions?: ReactNode
+  className?: string
+  /** Link/comment prompt dialogs — supply from platform-ui in apps. */
+  toolbarOverlays?: EditorToolbarOverlays
+  /** Controls what appears behind the shared toolbar's three-dot overflow. */
+  toolbarAdvancedTools?: 'full' | 'formatting'
+  inEditorTopElement?: ReactNode
+  inEditorBottomElement?: ReactNode
+  /** App-specific slash commands appended to the shared editor commands. */
+  slashCommands?: SlashCommandItem[]
+}
+
+/**
+ * Environment-agnostic TipTap document surface.
+ * Apps own load/save, asset URLs, paste/drop persistence, and shell integration.
+ */
+export const DocumentEditor = forwardRef<
+  DocumentEditorHandle,
+  DocumentEditorProps
+>(function DocumentEditor(
+  {
+    value,
+    extensions,
+    inputFormat = 'html',
+    outputFormat = 'html',
+    onChange,
+    enableComments = false,
+    showSelectionComments = true,
+    showToolbar = true,
+    viewMode = 'boxed',
+    toolbarActions,
+    className,
+    toolbarOverlays,
+    toolbarAdvancedTools = 'full',
+    inEditorTopElement = null,
+    inEditorBottomElement = null,
+    slashCommands = [],
+  },
+  ref,
+): React.ReactElement {
+  const pageMode = viewMode === 'page'
+  // In the quiet page view the toolbar and selection bubble are hidden;
+  // commenting stays available through the slash menu.
+  const toolbarVisible = showToolbar && !pageMode
+  const selectionCommentsActive = showSelectionComments && !pageMode
+  const onChangeRef = useRef(onChange)
+  onChangeRef.current = onChange
+  const outputFormatRef = useRef(outputFormat)
+  outputFormatRef.current = outputFormat
+  const commentCardRef = useRef<HTMLDivElement>(null)
+  const editorViewportRef = useRef<HTMLDivElement>(null)
+  const annotationButtonRef = useRef<HTMLButtonElement>(null)
+  const inlineCommentDraftRef = useRef<HTMLFormElement>(null)
+  const inlineCommentTextRef = useRef<HTMLTextAreaElement>(null)
+  const scrollSnapshotRef = useRef<ScrollSnapshot | null>(null)
+  const freshCommentTimerRef = useRef<number | null>(null)
+  const [activeComment, setActiveComment] = useState<ActiveComment | null>(null)
+  const [replyText, setReplyText] = useState('')
+  const [selectionBubble, setSelectionBubble] =
+    useState<SelectionBubbleState | null>(null)
+  const [inlineCommentDraft, setInlineCommentDraft] =
+    useState<InlineCommentDraft | null>(null)
+  const [lastCommentType, setLastCommentType] = useState<CommentType>('general')
+  const [reviewRailItems, setReviewRailItems] = useState<ReviewRailItem[]>([])
+  const [commentNavigationIds, setCommentNavigationIds] = useState<string[]>([])
+  const [reviewRailScrolling, setReviewRailScrolling] = useState(false)
+  const [slashMenuOpen, setSlashMenuOpen] = useState(false)
+  const [freshCommentId, setFreshCommentId] = useState<string | null>(null)
+  const openCommentDraftRef = useRef<
+    (range: { from: number; to: number }, commentType: CommentType) => void
+  >(() => {})
+  const annotationRailOpen = Boolean(activeComment || inlineCommentDraft)
+  const [annotationRailTop, setAnnotationRailTop] = useState(0)
+
+  const resolveDisplayContent = useCallback(
+    (nextValue: string): string => resolveEditorContent(nextValue, inputFormat),
+    [inputFormat],
+  )
+  const lastValueRef = useRef(resolveDisplayContent(value))
+
+  // Comment operations live inside the slash menu too, so opening it on a
+  // selection gives one menu with both formatting and commenting.
+  const commentSlashItems = useMemo<SlashCommandItem[]>(() => {
+    if (!enableComments) return []
+    return [...PRIMARY_COMMENT_TYPES, ...SECONDARY_COMMENT_TYPES].map(type => ({
+      id: `comment-${type}`,
+      title: COMMENT_TYPE_LABELS[type],
+      description: 'Add a comment to the selection',
+      section: 'Comments',
+      run: ({ range }: { range: { from: number; to: number } }) =>
+        openCommentDraftRef.current(range, type),
+    }))
+  }, [enableComments])
+
+  const editorExtensions = useMemo(
+    () => [
+      ...extensions,
+      SlashCommands.configure({
+        items: [
+          ...commentSlashItems,
+          ...createDefaultSlashCommands(),
+          ...slashCommands,
+        ],
+      }),
+    ],
+    [commentSlashItems, extensions, slashCommands],
+  )
+
+  const editor = useEditor({
+    extensions: editorExtensions,
+    content: lastValueRef.current,
+    onUpdate: ({ editor: updatedEditor }) => {
+      const html = updatedEditor.getHTML()
+      lastValueRef.current = html
+      onChangeRef.current?.(
+        outputFormatRef.current === 'markdown' ? toMd(html) : html,
+      )
+    },
+  })
+
+  useEffect(() => {
+    if (!editor || editor.isDestroyed) return
+    const resolved = resolveDisplayContent(value)
+    if (resolved === lastValueRef.current) return
+    lastValueRef.current = resolved
+    editor.commands.setContent(resolved, { emitUpdate: false })
+    if (inputFormat === 'markdown') {
+      migrateMathStrings(editor)
+    }
+  }, [editor, inputFormat, resolveDisplayContent, value])
+
+  useEffect(() => {
+    if (!editor || editor.isDestroyed || inputFormat !== 'markdown') return
+    migrateMathStrings(editor)
+  }, [editor, inputFormat])
+
+  useEffect(() => {
+    const syncAnnotationRailTop = (): void => {
+      setAnnotationRailTop(
+        Math.max(
+          0,
+          editorViewportRef.current?.getBoundingClientRect().top ?? 0,
+        ),
+      )
+    }
+    syncAnnotationRailTop()
+    window.addEventListener('resize', syncAnnotationRailTop)
+    return () => window.removeEventListener('resize', syncAnnotationRailTop)
+  }, [])
+
+  useEffect(() => {
+    if (!editor || editor.isDestroyed || !enableComments) return
+    if (!selectionCommentsActive) {
+      setSelectionBubble(null)
+      return
+    }
+    const clamp = (value: number, min: number, max: number): number =>
+      Math.max(min, Math.min(value, max))
+    const syncSelectionBubble = (): void => {
+      if (slashMenuOpen) {
+        setSelectionBubble(null)
+        return
+      }
+      if (inlineCommentDraft) {
+        const { from, to } = editor.state.selection
+        if (from !== inlineCommentDraft.from || to !== inlineCommentDraft.to) {
+          setInlineCommentDraft(null)
+        }
+        setSelectionBubble(null)
+        return
+      }
+      const { from, to, empty } = editor.state.selection
+      if (
+        empty ||
+        from === to ||
+        !editor.isEditable ||
+        !isSelectionAnnotatable(editor, from, to)
+      ) {
+        setSelectionBubble(null)
+        return
+      }
+      try {
+        const start = editor.view.coordsAtPos(from)
+        const end = editor.view.coordsAtPos(to)
+        const x = clamp(start.left - 34, 12, window.innerWidth - 44)
+        const y = clamp(
+          (start.top + end.bottom) / 2,
+          52,
+          window.innerHeight - 52,
+        )
+        setSelectionBubble({
+          from,
+          to,
+          x,
+          y,
+          selectedText: editor.state.doc.textBetween(from, to, ' '),
+        })
+      } catch {
+        setSelectionBubble(null)
+      }
+    }
+    syncSelectionBubble()
+    editor.on('selectionUpdate', syncSelectionBubble)
+    editor.on('transaction', syncSelectionBubble)
+    window.addEventListener('scroll', syncSelectionBubble, true)
+    window.addEventListener('resize', syncSelectionBubble)
+    return () => {
+      editor.off('selectionUpdate', syncSelectionBubble)
+      editor.off('transaction', syncSelectionBubble)
+      window.removeEventListener('scroll', syncSelectionBubble, true)
+      window.removeEventListener('resize', syncSelectionBubble)
+    }
+  }, [editor, enableComments, inlineCommentDraft, selectionCommentsActive, slashMenuOpen])
+
+  // Track the slash menu's open state so the comment bubble can step aside —
+  // when you open the slash menu on a selection it becomes the single menu.
+  useEffect(() => {
+    if (!editor || editor.isDestroyed) return
+    const dom = editor.view.dom
+    const onToggle = (event: Event): void => {
+      const open = (event as CustomEvent<{ open: boolean }>).detail?.open
+      setSlashMenuOpen(Boolean(open))
+    }
+    dom.addEventListener('ps-slash-menu-toggle', onToggle)
+    return () => dom.removeEventListener('ps-slash-menu-toggle', onToggle)
+  }, [editor])
+
+  useEffect(() => {
+    if (!inlineCommentDraft) return
+    window.requestAnimationFrame(() => {
+      inlineCommentTextRef.current?.focus({ preventScroll: true })
+      restoreScrollSnapshot(scrollSnapshotRef.current)
+    })
+  }, [inlineCommentDraft])
+
+  const highlightFreshComment = useCallback((commentId: string): void => {
+    setFreshCommentId(commentId)
+    if (freshCommentTimerRef.current) {
+      window.clearTimeout(freshCommentTimerRef.current)
+    }
+    freshCommentTimerRef.current = window.setTimeout(() => {
+      setFreshCommentId(current => (current === commentId ? null : current))
+      freshCommentTimerRef.current = null
+    }, FRESH_COMMENT_HIGHLIGHT_MS)
+  }, [])
+
+  useEffect(
+    () => () => {
+      if (freshCommentTimerRef.current) {
+        window.clearTimeout(freshCommentTimerRef.current)
+      }
+    },
+    [],
+  )
+
+  useEffect(() => {
+    if (!enableComments) return
+    const onPointerDown = (event: PointerEvent): void => {
+      const target = event.target as Node
+      if (annotationButtonRef.current?.contains(target)) return
+      if (inlineCommentDraftRef.current?.contains(target)) return
+      setSelectionBubble(null)
+      setInlineCommentDraft(draft => {
+        if (!draft || draft.text.trim()) return draft
+        return null
+      })
+    }
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key !== 'Escape') return
+      setSelectionBubble(null)
+      setInlineCommentDraft(null)
+    }
+    document.addEventListener('pointerdown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown)
+    }
+  }, [enableComments])
+
+  useEffect(() => {
+    if (!editor || editor.isDestroyed || !enableComments) return
+    const editorElement = editor.view.dom
+    const openComment = (target: HTMLElement): void => {
+      const commentElement = target.closest<HTMLElement>(
+        'span[data-comment-id]',
+      )
+      if (!commentElement) return
+      const commentType = normalizeCommentType(
+        commentElement.dataset.commentType,
+      )
+      const subjectText =
+        commentElement.dataset.commentSubject?.trim() ||
+        commentElement.textContent?.trim() ||
+        ''
+      setActiveComment({
+        id: commentElement.dataset.commentId ?? '',
+        text: commentElement.dataset.commentText ?? '',
+        savedText: commentElement.dataset.commentText ?? '',
+        commentType,
+        savedCommentType: commentType,
+        subjectText,
+        reviewStatus: normalizeCommentReviewStatus(
+          commentElement.dataset.commentReviewStatus,
+          commentType,
+        ),
+        savedReviewStatus: normalizeCommentReviewStatus(
+          commentElement.dataset.commentReviewStatus,
+          commentType,
+        ),
+        severity: normalizeCommentSeverity(
+          commentElement.dataset.commentSeverity,
+          commentType,
+        ),
+        author: commentElement.dataset.commentAuthor ?? undefined,
+        createdAt: commentElement.dataset.commentCreatedAt ?? undefined,
+        replies: parseCommentReplies(commentElement.dataset.commentReplies),
+        resolvedAt: commentElement.dataset.commentResolvedAt ?? undefined,
+        resolvedBy: commentElement.dataset.commentResolvedBy ?? undefined,
+        x: panelX(),
+        y: panelY(),
+      })
+      setReplyText('')
+    }
+    const onEditorPointerDown = (event: PointerEvent): void => {
+      const target = event.target as HTMLElement | null
+      if (!target) return
+      if (!target.closest('span[data-comment-id]')) return
+      event.preventDefault()
+      openComment(target)
+    }
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape') setActiveComment(null)
+    }
+    editorElement.addEventListener('pointerdown', onEditorPointerDown)
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      editorElement.removeEventListener('pointerdown', onEditorPointerDown)
+      document.removeEventListener('keydown', onKeyDown)
+    }
+  }, [editor, enableComments])
+
+  useEffect(() => {
+    if (!editor || editor.isDestroyed || !enableComments) {
+      setReviewRailItems([])
+      setCommentNavigationIds([])
+      setReviewRailScrolling(false)
+      return
+    }
+    const editorElement = editor.view.dom
+    let frame = 0
+    let scrollIdleTimer = 0
+    let railHiddenForScroll = false
+    const syncReviewRail = (): void => {
+      frame = 0
+      const editorRect = editorElement.getBoundingClientRect()
+      const viewportRect =
+        editorViewportRef.current?.getBoundingClientRect() ?? null
+      const railLeft = annotationRailOpen
+        ? window.innerWidth - ANNOTATION_RAIL_WIDTH
+        : window.innerWidth
+      const viewportTop = Math.max(0, (viewportRect?.top ?? 0) + 8)
+      const viewportBottom = Math.min(
+        window.innerHeight,
+        viewportRect?.bottom ?? window.innerHeight,
+      )
+      const byId = new Map<string, ReviewRailItem>()
+      const navigationIds: string[] = []
+      const marks = Array.from(
+        editorElement.querySelectorAll<HTMLElement>(REVIEW_RAIL_SELECTOR),
+      )
+      for (const mark of marks) {
+        const id = mark.dataset.commentId
+        const type = normalizeCommentType(mark.dataset.commentType)
+        if (!id || !isReviewRailCommentType(type) || byId.has(id))
+          continue
+        const rect = mark.getBoundingClientRect()
+        const markCenter = rect.top + rect.height / 2
+        if (rect.width === 0 && rect.height === 0) continue
+        if (markCenter < viewportTop || markCenter > viewportBottom) continue
+        if (!navigationIds.includes(id)) navigationIds.push(id)
+        byId.set(id, {
+          id,
+          type,
+          status: normalizeCommentReviewStatus(
+            mark.dataset.commentReviewStatus,
+            type,
+          ),
+          resolved: Boolean(mark.dataset.commentResolvedAt),
+          top: markCenter,
+          left: Math.max(10, Math.min(editorRect.right + 10, railLeft - 118)),
+        })
+        if (byId.size >= MAX_VISIBLE_REVIEW_RAIL_ITEMS) break
+      }
+      setCommentNavigationIds(navigationIds)
+      setReviewRailItems(packReviewRailItems(Array.from(byId.values())))
+    }
+    const scheduleReviewRailSync = (): void => {
+      if (frame) return
+      frame = window.requestAnimationFrame(syncReviewRail)
+    }
+    const onScroll = (): void => {
+      if (!railHiddenForScroll) {
+        railHiddenForScroll = true
+        setReviewRailScrolling(true)
+      }
+      if (scrollIdleTimer) window.clearTimeout(scrollIdleTimer)
+      scrollIdleTimer = window.setTimeout(() => {
+        railHiddenForScroll = false
+        setReviewRailScrolling(false)
+        scheduleReviewRailSync()
+      }, REVIEW_RAIL_SCROLL_IDLE_MS)
+    }
+    scheduleReviewRailSync()
+    editor.on('transaction', scheduleReviewRailSync)
+    window.addEventListener('scroll', onScroll, true)
+    window.addEventListener('resize', scheduleReviewRailSync)
+    return () => {
+      if (frame) window.cancelAnimationFrame(frame)
+      if (scrollIdleTimer) window.clearTimeout(scrollIdleTimer)
+      editor.off('transaction', scheduleReviewRailSync)
+      window.removeEventListener('scroll', onScroll, true)
+      window.removeEventListener('resize', scheduleReviewRailSync)
+    }
+  }, [annotationRailOpen, editor, enableComments])
+
+  useEffect(() => {
+    if (!editor || editor.isDestroyed || !enableComments) return
+    const spotlightCommentId = freshCommentId ?? activeComment?.id ?? null
+    const marks = Array.from(
+      editor.view.dom.querySelectorAll<HTMLElement>('span[data-comment-id]'),
+    )
+    for (const mark of marks) {
+      const isSpotlight = Boolean(
+        spotlightCommentId && mark.dataset.commentId === spotlightCommentId,
+      )
+      const isSpotlightMuted = Boolean(spotlightCommentId && !isSpotlight)
+      mark.classList.toggle(
+        'comment-mark--active',
+        Boolean(activeComment && mark.dataset.commentId === activeComment.id),
+      )
+      mark.classList.toggle('comment-mark--spotlight', isSpotlight)
+      mark.classList.toggle('comment-mark--spotlight-muted', isSpotlightMuted)
+    }
+    return () => {
+      for (const mark of marks) {
+        mark.classList.remove(
+          'comment-mark--active',
+          'comment-mark--spotlight',
+          'comment-mark--spotlight-muted',
+        )
+      }
+    }
+  }, [activeComment, editor, enableComments, freshCommentId])
+
+  const updateActiveComment = useCallback(
+    (patch: Partial<ActiveComment>): void => {
+      setActiveComment(comment =>
+        comment ? { ...comment, ...patch } : comment,
+      )
+    },
+    [],
+  )
+
+  const restoreAnnotationScroll = useCallback((): void => {
+    const snapshot = scrollSnapshotRef.current
+    restoreScrollSnapshot(snapshot)
+    window.requestAnimationFrame(() => restoreScrollSnapshot(snapshot))
+  }, [])
+
+  const createCommentMark = useCallback(
+    ({
+      commentText,
+      commentType,
+      from,
+      to,
+    }: {
+      commentText: string
+      commentType: CommentType
+      from: number
+      to: number
+    }): void => {
+      if (!editor || editor.isDestroyed || from === to) return
+      const trimmed = commentText.trim()
+      if (!trimmed) return
+      applyCommentMarkToRange(editor, from, to, {
+        ...commentDefaultsForType(commentType),
+        commentId:
+          globalThis.crypto?.randomUUID?.() ??
+          `comment-${Math.random().toString(36).slice(2)}`,
+        commentText: trimmed,
+        commentType,
+        subjectText: editor.state.doc.textBetween(from, to, ' '),
+        author: 'Author',
+        createdAt: new Date().toISOString(),
+        replies: '[]',
+      })
+      restoreAnnotationScroll()
+      setLastCommentType(commentType)
+      setSelectionBubble(null)
+    },
+    [editor, restoreAnnotationScroll],
+  )
+
+  const openInlineCommentDraft = useCallback(
+    (commentType = lastCommentType): void => {
+      const selection = selectionBubble
+      if (!selection || !editor || editor.isDestroyed) return
+      scrollSnapshotRef.current = captureScrollSnapshot(editor.view.dom)
+      setLastCommentType(commentType)
+      setSelectionBubble(null)
+      setInlineCommentDraft({
+        ...selection,
+        x: panelX(),
+        y: panelY(),
+        text: '',
+        commentType,
+      })
+    },
+    [editor, lastCommentType, selectionBubble],
+  )
+
+  // Open a comment draft for an explicit range — used by the slash menu's
+  // comment commands, which carry the selection range rather than the bubble.
+  const openCommentDraftForRange = useCallback(
+    (range: { from: number; to: number }, commentType: CommentType): void => {
+      if (!editor || editor.isDestroyed) return
+      const { from, to } = range
+      if (from === to) return
+      const clamp = (value: number, min: number, max: number): number =>
+        Math.max(min, Math.min(value, max))
+      try {
+        const start = editor.view.coordsAtPos(from)
+        const end = editor.view.coordsAtPos(to)
+        const x = clamp(
+          (start.left + end.right) / 2,
+          180,
+          window.innerWidth - 180,
+        )
+        const y = clamp(
+          Math.min(start.top, end.top) + 28,
+          56,
+          window.innerHeight - 180,
+        )
+        const selectedText = editor.state.doc.textBetween(from, to, ' ').trim()
+        setLastCommentType(commentType)
+        setSelectionBubble(null)
+        setInlineCommentDraft({
+          from,
+          to,
+          x,
+          y,
+          text: '',
+          commentType,
+          selectedText,
+        })
+      } catch {
+        /* position unavailable — skip */
+      }
+    },
+    [editor],
+  )
+  openCommentDraftRef.current = openCommentDraftForRange
+
+  const confirmInlineCommentDraft = useCallback((): void => {
+    if (!inlineCommentDraft || !editor || editor.isDestroyed) return
+    scrollSnapshotRef.current =
+      scrollSnapshotRef.current ?? captureScrollSnapshot(editor.view.dom)
+    createCommentMark({
+      commentText: inlineCommentDraft.text,
+      commentType: inlineCommentDraft.commentType,
+      from: inlineCommentDraft.from,
+      to: inlineCommentDraft.to,
+    })
+    setInlineCommentDraft(null)
+    restoreAnnotationScroll()
+  }, [createCommentMark, editor, inlineCommentDraft])
+
+  const addReplyToActiveComment = useCallback((): void => {
+    if (!editor || editor.isDestroyed || !activeComment) return
+    const text = replyText.trim()
+    if (!text) return
+    const replies = [
+      ...activeComment.replies,
+      {
+        id:
+          globalThis.crypto?.randomUUID?.() ??
+          `reply-${Math.random().toString(36).slice(2)}`,
+        text,
+        author: 'Author',
+        createdAt: new Date().toISOString(),
+      },
+    ]
+    if (
+      updateCommentMarksById(editor, activeComment.id, {
+        replies: serializeCommentReplies(replies),
+      })
+    ) {
+      restoreAnnotationScroll()
+      updateActiveComment({ replies })
+      setReplyText('')
+    }
+  }, [activeComment, editor, replyText, updateActiveComment])
+
+  const setActiveCommentResolved = useCallback(
+    (resolved: boolean): void => {
+      if (!editor || editor.isDestroyed || !activeComment) return
+      const resolvedAt = resolved ? new Date().toISOString() : null
+      const patch = resolved
+        ? { resolvedAt: resolvedAt ?? undefined, resolvedBy: 'Author' }
+        : { resolvedAt: null, resolvedBy: null }
+      if (updateCommentMarksById(editor, activeComment.id, patch)) {
+        restoreAnnotationScroll()
+        updateActiveComment({
+          resolvedAt: resolvedAt ?? undefined,
+          resolvedBy: resolved ? 'Author' : undefined,
+        })
+      }
+    },
+    [activeComment, editor, restoreAnnotationScroll, updateActiveComment],
+  )
+
+  const setActiveCommentReviewOutcome = useCallback(
+    (reviewStatus: CommentReviewStatus, resolved: boolean): void => {
+      if (!editor || editor.isDestroyed || !activeComment) return
+      const resolvedAt = resolved ? new Date().toISOString() : null
+      if (
+        updateCommentMarksById(editor, activeComment.id, {
+          reviewStatus,
+          resolvedAt: resolvedAt ?? null,
+          resolvedBy: resolved ? 'Author' : null,
+        })
+      ) {
+        restoreAnnotationScroll()
+        updateActiveComment({
+          reviewStatus,
+          savedReviewStatus: reviewStatus,
+          resolvedAt: resolvedAt ?? undefined,
+          resolvedBy: resolved ? 'Author' : undefined,
+        })
+      }
+    },
+    [activeComment, editor, restoreAnnotationScroll, updateActiveComment],
+  )
+
+  const saveActiveCommentEdits = useCallback((): void => {
+    if (!editor || editor.isDestroyed || !activeComment) return
+    const text = activeComment.text.trim()
+    if (!text) return
+    if (
+      updateCommentMarksById(editor, activeComment.id, {
+        commentText: text,
+        commentType: activeComment.commentType,
+        reviewStatus: activeComment.reviewStatus,
+        severity: activeComment.severity,
+      })
+    ) {
+      restoreAnnotationScroll()
+      updateActiveComment({
+        text,
+        savedText: text,
+        savedCommentType: activeComment.commentType,
+        savedReviewStatus: activeComment.reviewStatus,
+      })
+    }
+  }, [activeComment, editor, updateActiveComment])
+
+  const deleteActiveComment = useCallback((): void => {
+    if (!editor || editor.isDestroyed || !activeComment) return
+    if (removeCommentMarksById(editor, activeComment.id)) {
+      restoreAnnotationScroll()
+      setActiveComment(null)
+      setFreshCommentId(null)
+      setReplyText('')
+    }
+  }, [activeComment, editor])
+
+  const clearAllComments = useCallback((): void => {
+    if (!editor || editor.isDestroyed) return
+    const confirmed = window.confirm(
+      'Clear all annotations in this document? This removes comment, claim, fact-check, formatting, and question marks from the manuscript.',
+    )
+    if (!confirmed) return
+    const removed = removeAllCommentMarks(editor, {
+      scrollIntoView: false,
+      focusEditor: false,
+    })
+    if (removed) {
+      restoreAnnotationScroll()
+      setActiveComment(null)
+      setFreshCommentId(null)
+      setInlineCommentDraft(null)
+      setReplyText('')
+      setReviewRailItems([])
+      setCommentNavigationIds([])
+    }
+  }, [editor, restoreAnnotationScroll])
+
+  const cancelInlineCommentDraft = useCallback((): void => {
+    setInlineCommentDraft(null)
+    restoreAnnotationScroll()
+  }, [restoreAnnotationScroll])
+
+  const openReviewRailItem = useCallback(
+    (commentId: string, options: { scrollIntoView?: boolean } = {}): void => {
+      if (!editor || editor.isDestroyed) return
+      const mark = editor.view.dom.querySelector<HTMLElement>(
+        `span[data-comment-id="${cssEscape(commentId)}"]`,
+      )
+      if (!mark) return
+      if (options.scrollIntoView) {
+        mark.scrollIntoView({ block: 'center', behavior: 'smooth' })
+      }
+      const event =
+        typeof PointerEvent === 'function'
+          ? new PointerEvent('pointerdown', { bubbles: true, cancelable: true })
+          : new MouseEvent('pointerdown', { bubbles: true, cancelable: true })
+      mark.dispatchEvent(event)
+    },
+    [editor],
+  )
+
+  const openAdjacentComment = useCallback(
+    (direction: -1 | 1): void => {
+      if (!activeComment || commentNavigationIds.length < 2) return
+      const currentIndex = commentNavigationIds.indexOf(activeComment.id)
+      if (currentIndex === -1) return
+      const nextIndex =
+        (currentIndex + direction + commentNavigationIds.length) %
+        commentNavigationIds.length
+      openReviewRailItem(commentNavigationIds[nextIndex], {
+        scrollIntoView: true,
+      })
+    },
+    [activeComment, commentNavigationIds, openReviewRailItem],
+  )
+
+  const activeCommentChanged = Boolean(
+    activeComment &&
+      (activeComment.text.trim() !== activeComment.savedText ||
+        activeComment.commentType !== activeComment.savedCommentType ||
+        activeComment.reviewStatus !== activeComment.savedReviewStatus),
+  )
+
+  const providerValue = useMemo(() => ({ editor }), [editor])
+
+  const insertImage = useCallback(
+    ({
+      src,
+      alt = '',
+      caption = '',
+    }: {
+      src: string
+      alt?: string
+      caption?: string
+    }) => {
+      if (!editor || editor.isDestroyed) return
+      const stem = alt.trim() || 'image'
+      const commands = editor.chain().focus() as unknown as {
+        insertFigure?: (opts: {
+          src: string
+          alt?: string
+          caption?: string
+        }) => { run: () => void }
+      }
+      if (typeof commands.insertFigure === 'function') {
+        commands.insertFigure({ src, alt: stem, caption }).run()
+        return
+      }
+      editor.chain().focus().setImage({ src, alt: stem }).run()
+    },
+    [editor, restoreAnnotationScroll],
+  )
+
+  const insertHtml = useCallback(
+    (html: string) => {
+      if (!editor || editor.isDestroyed) return
+      editor.chain().focus().insertContent(html).run()
+    },
+    [editor],
+  )
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      insertImage,
+      insertHtml,
+      openComment: (commentId, options) => {
+        const current = editor && !editor.isDestroyed ? editor : null
+        if (!current) return false
+        const mark = current.view.dom.querySelector<HTMLElement>(
+          `span[data-comment-id="${cssEscape(commentId)}"]`,
+        )
+        if (!mark) return false
+        openReviewRailItem(commentId, options)
+        return true
+      },
+      updateComment: (commentId, patch) => {
+        const current = editor && !editor.isDestroyed ? editor : null
+        if (!current) return false
+        return updateCommentMarksById(current, commentId, patch)
+      },
+      applyCommentReplacement: (commentId, replacementText, attrs) => {
+        const current = editor && !editor.isDestroyed ? editor : null
+        if (!current) return false
+        return applyCommentReplacementById(
+          current,
+          commentId,
+          replacementText,
+          {
+            ...attrs,
+            sourceCommentId: commentId,
+          },
+        )
+      },
+      removeComment: commentId => {
+        const current = editor && !editor.isDestroyed ? editor : null
+        if (!current) return false
+        return removeCommentMarksById(current, commentId)
+      },
+      clearComments: () => {
+        const current = editor && !editor.isDestroyed ? editor : null
+        if (!current) return 0
+        let removed = removeAllCommentMarks(current)
+        if (current.getHTML().includes('data-comment-id')) {
+          const stripped = stripCommentMarkupFromHtml(current.getHTML())
+          if (stripped.removed) {
+            removed = Math.max(removed, stripped.removed)
+            current.commands.setContent(stripped.html, { emitUpdate: true })
+          }
+        }
+        if (removed) {
+          setActiveComment(null)
+          setFreshCommentId(null)
+          setInlineCommentDraft(null)
+          setReplyText('')
+          setReviewRailItems([])
+          setCommentNavigationIds([])
+        }
+        return removed
+      },
+      runAutoReview: async options => {
+        const current = editor && !editor.isDestroyed ? editor : null
+        if (!current) {
+          return { paragraphCount: 0, findingCount: 0, applied: [], skipped: 0 }
+        }
+        if (!options?.readAlong) {
+          return await runEditorAutoReview(current, options)
+        }
+        const paragraphs = collectScopedAutoReviewParagraphs(
+          current,
+          options.scope,
+        )
+        if (!options.findingsProvider) {
+          return {
+            paragraphCount: paragraphs.length,
+            findingCount: 0,
+            applied: [],
+            skipped: 0,
+            unavailableReason: 'Editorial review provider is not configured.',
+          }
+        }
+        options.onProgress?.({
+          paragraphCount: paragraphs.length,
+          findingCount: 0,
+          applied: [],
+          skipped: 0,
+        })
+        const applied: RunAutoReviewResult['applied'] = []
+        let skipped = 0
+        let findingCount = 0
+        let providerDone = false
+        let providerError: unknown = null
+        const queue: AutoReviewFindingInput[] = []
+        let notifyQueue: (() => void) | null = null
+        const wakeQueue = (): void => {
+          notifyQueue?.()
+          notifyQueue = null
+        }
+        const waitForQueue = (): Promise<void> =>
+          new Promise(resolve => {
+            notifyQueue = resolve
+          })
+
+        void runProgressiveAutoReviewFindings(paragraphs, options, findings => {
+          const remaining =
+            typeof options.maxFindings === 'number'
+              ? Math.max(0, options.maxFindings - findingCount)
+              : findings.length
+          if (!remaining) return
+          const nextFindings = findings.slice(0, remaining)
+          findingCount += nextFindings.length
+          queue.push(...nextFindings)
+          options.onProgress?.({
+            paragraphCount: paragraphs.length,
+            findingCount,
+            applied: [...applied],
+            skipped,
+          })
+          wakeQueue()
+        })
+          .catch(cause => {
+            providerError = cause
+          })
+          .finally(() => {
+            providerDone = true
+            wakeQueue()
+          })
+
+        while (!providerDone || queue.length) {
+          if (options.signal?.aborted) break
+          const finding = queue.shift()
+          if (!finding) {
+            await waitForQueue()
+            continue
+          }
+          const result = applyAutoReviewFindings(
+            current,
+            paragraphs,
+            [finding],
+            {
+              ...options,
+              author: 'Auto review',
+              idPrefix: 'auto-review',
+            },
+          )
+          skipped += result.skipped
+          const appliedFinding = result.applied[0]
+          if (appliedFinding) {
+            applied.push(appliedFinding)
+            highlightFreshComment(appliedFinding.commentId)
+            options.onProgress?.({
+              paragraphCount: paragraphs.length,
+              findingCount,
+              applied: [...applied],
+              skipped,
+            })
+            window.requestAnimationFrame(() =>
+              window.requestAnimationFrame(() =>
+                openReviewRailItem(appliedFinding.commentId, {
+                  scrollIntoView: true,
+                }),
+              ),
+            )
+            await waitForAutoReviewStep(
+              options.signal,
+              options.readAlongDelayMs,
+            )
+          }
+        }
+        if (providerError && !options.signal?.aborted) throw providerError
+        return {
+          paragraphCount: paragraphs.length,
+          findingCount,
+          applied,
+          skipped,
+        }
+      },
+      getEditor: () => (editor && !editor.isDestroyed ? editor : null),
+    }),
+    [editor, highlightFreshComment, insertHtml, insertImage, openReviewRailItem],
+  )
+
+  const spotlightCommentId = freshCommentId ?? activeComment?.id ?? null
+
+  return (
+    <DocumentEditorRoot className={className} $pageMode={pageMode}>
+      <EditorContext.Provider value={providerValue}>
+        {toolbarVisible && editor ? (
+          <DocumentEditorToolbarWrap>
+            <Toolbar
+              overlays={toolbarOverlays}
+              advancedTools={toolbarAdvancedTools}
+            />
+            {toolbarActions ? (
+              <DocumentEditorToolbarActions>
+                {toolbarActions}
+              </DocumentEditorToolbarActions>
+            ) : null}
+          </DocumentEditorToolbarWrap>
+        ) : null}
+        <DocumentEditorViewport
+          $pageMode={pageMode}
+          ref={editorViewportRef}
+          className={
+            annotationRailOpen
+              ? 'document-editor-viewport--annotation-rail-open'
+              : undefined
+          }
+          style={
+            {
+              '--annotation-rail-top': `${annotationRailTop}px`,
+            } as CSSProperties
+          }
+        >
+          <EditorWrapper $pageMode={pageMode}>
+            {inEditorTopElement}
+
+            <EditorContent editor={editor} />
+            {selectionBubble ? (
+              <MarginAnnotationButton
+                ref={annotationButtonRef}
+                $x={selectionBubble.x}
+                $y={selectionBubble.y}
+                type="button"
+                title="Add annotation"
+                aria-label="Add annotation to selection"
+                onMouseDown={event => event.preventDefault()}
+                onClick={() => openInlineCommentDraft('general')}
+              >
+                <CommentOutlined />
+              </MarginAnnotationButton>
+            ) : null}
+            {reviewRailItems.length ? (
+              <ReviewRailLayer
+                $scrolling={reviewRailScrolling}
+                aria-label="Manuscript review rail"
+              >
+                {reviewRailItems.map(item => (
+                  <ReviewRailButton
+                    key={item.id}
+                    type="button"
+                    $top={item.top}
+                    $left={item.left}
+                    $type={item.type}
+                    $active={activeComment?.id === item.id}
+                    $spotlight={spotlightCommentId === item.id}
+                    $spotlightMuted={Boolean(
+                      spotlightCommentId && spotlightCommentId !== item.id,
+                    )}
+                    $resolved={item.resolved}
+                    onClick={() => openReviewRailItem(item.id)}
+                  >
+                    <ReviewRailLabel>{COMMENT_TYPE_LABELS[item.type]}</ReviewRailLabel>
+                    <ReviewRailStatus>
+                      {item.resolved
+                        ? 'Resolved'
+                        : COMMENT_STATUS_LABELS[item.status]}
+                    </ReviewRailStatus>
+                  </ReviewRailButton>
+                ))}
+              </ReviewRailLayer>
+            ) : null}
+            {inlineCommentDraft ? (
+              <AnnotationPanel
+                ref={inlineCommentDraftRef}
+                $x={inlineCommentDraft.x}
+                $y={inlineCommentDraft.y}
+                $reviewType={reviewPanelType(inlineCommentDraft.commentType)}
+                data-inline-comment-composer
+                role="dialog"
+                aria-label="New annotation"
+                onSubmit={event => {
+                  event.preventDefault()
+                  confirmInlineCommentDraft()
+                }}
+              >
+                <AnnotationPanelHeader>
+                  <AnnotationTitleGroup>
+                    <AnnotationPanelKicker>
+                      {annotationKicker(inlineCommentDraft.commentType)}
+                    </AnnotationPanelKicker>
+                    <AnnotationPanelTitle>
+                      {newAnnotationTitle(inlineCommentDraft.commentType)}
+                    </AnnotationPanelTitle>
+                  </AnnotationTitleGroup>
+                  <AnnotationIconButton
+                    type="button"
+                    aria-label="Close annotation panel"
+                    onClick={cancelInlineCommentDraft}
+                  >
+                    <CloseOutlined />
+                  </AnnotationIconButton>
+                </AnnotationPanelHeader>
+                <AnnotationBody>
+                  <AnnotationQuote>
+                    <AnnotationSubjectLabel>
+                      {
+                        COMMENT_TYPE_DEFINITIONS[inlineCommentDraft.commentType]
+                          .subjectLabel
+                      }
+                    </AnnotationSubjectLabel>
+                    {inlineCommentDraft.selectedText}
+                  </AnnotationQuote>
+                  <AnnotationSectionLabel>
+                    Classification
+                  </AnnotationSectionLabel>
+                  <InlineCommentTypeList aria-label="Primary annotation type">
+                    {PRIMARY_COMMENT_TYPES.map(type => (
+                      <InlineCommentTypeButton
+                        key={type}
+                        type="button"
+                        $active={inlineCommentDraft.commentType === type}
+                        onClick={() => {
+                          setLastCommentType(type)
+                          setInlineCommentDraft(draft =>
+                            draft ? { ...draft, commentType: type } : draft,
+                          )
+                        }}
+                      >
+                        <AnnotationTypeButtonLabel>
+                          {COMMENT_TYPE_LABELS[type]}
+                        </AnnotationTypeButtonLabel>
+                        <AnnotationTypeButtonMeta>
+                          {
+                            COMMENT_STATUS_LABELS[
+                              defaultCommentReviewStatusForType(type)
+                            ]
+                          }
+                        </AnnotationTypeButtonMeta>
+                      </InlineCommentTypeButton>
+                    ))}
+                  </InlineCommentTypeList>
+                  <SecondaryTypeList aria-label="More annotation types">
+                    {SECONDARY_COMMENT_TYPES.map(type => (
+                      <SecondaryTypeButton
+                        key={type}
+                        type="button"
+                        $active={inlineCommentDraft.commentType === type}
+                        onClick={() => {
+                          setLastCommentType(type)
+                          setInlineCommentDraft(draft =>
+                            draft ? { ...draft, commentType: type } : draft,
+                          )
+                        }}
+                      >
+                        {COMMENT_TYPE_LABELS[type]}
+                      </SecondaryTypeButton>
+                    ))}
+                  </SecondaryTypeList>
+                  <AnnotationFieldHeader>
+                    <AnnotationFieldLabel>
+                      {
+                        COMMENT_TYPE_DEFINITIONS[inlineCommentDraft.commentType]
+                          .noteLabel
+                      }
+                    </AnnotationFieldLabel>
+                    <AnnotationFieldHint>
+                      {
+                        COMMENT_STATUS_LABELS[
+                          defaultCommentReviewStatusForType(
+                            inlineCommentDraft.commentType,
+                          )
+                        ]
+                      }
+                    </AnnotationFieldHint>
+                  </AnnotationFieldHeader>
+                  <InlineCommentTextArea
+                    ref={inlineCommentTextRef}
+                    value={inlineCommentDraft.text}
+                    rows={4}
+                    aria-label={
+                      COMMENT_TYPE_DEFINITIONS[inlineCommentDraft.commentType]
+                        .noteLabel
+                    }
+                    placeholder={
+                      COMMENT_TYPE_DEFINITIONS[inlineCommentDraft.commentType]
+                        .notePlaceholder
+                    }
+                    onChange={event =>
+                      setInlineCommentDraft(draft =>
+                        draft ? { ...draft, text: event.target.value } : draft,
+                      )
+                    }
+                    onKeyDown={event => {
+                      if (event.key === 'Escape') {
+                        event.preventDefault()
+                        cancelInlineCommentDraft()
+                      }
+                      if (
+                        (event.metaKey || event.ctrlKey) &&
+                        event.key === 'Enter'
+                      ) {
+                        event.preventDefault()
+                        confirmInlineCommentDraft()
+                      }
+                    }}
+                  />
+                </AnnotationBody>
+                <AnnotationFooter>
+                  <AnnotationSecondaryButton
+                    type="button"
+                    onClick={cancelInlineCommentDraft}
+                  >
+                    Cancel
+                  </AnnotationSecondaryButton>
+                  <AnnotationPrimaryButton
+                    type="submit"
+                    disabled={!inlineCommentDraft.text.trim()}
+                  >
+                    {saveAnnotationLabel(inlineCommentDraft.commentType)}
+                  </AnnotationPrimaryButton>
+                </AnnotationFooter>
+              </AnnotationPanel>
+            ) : null}
+            {activeComment ? (
+              <CommentCard
+                ref={commentCardRef}
+                $x={activeComment.x}
+                $y={activeComment.y}
+                $reviewType={reviewPanelType(activeComment.commentType)}
+                role="note"
+                aria-label="Annotation"
+              >
+                <CommentCardHeader>
+                  <AnnotationTitleGroup>
+                    <AnnotationPanelKicker>
+                      {activeComment.resolvedAt
+                        ? 'Resolved'
+                        : annotationKicker(activeComment.commentType)}
+                    </AnnotationPanelKicker>
+                    <AnnotationPanelTitle>
+                      {annotationTitle(
+                        activeComment.commentType,
+                        activeComment.subjectText,
+                      )}
+                    </AnnotationPanelTitle>
+                  </AnnotationTitleGroup>
+                  <AnnotationHeaderActions>
+                    <AnnotationNavButton
+                      type="button"
+                      onClick={() => openAdjacentComment(-1)}
+                      disabled={commentNavigationIds.length < 2}
+                    >
+                      Previous
+                    </AnnotationNavButton>
+                    <AnnotationNavButton
+                      type="button"
+                      onClick={() => openAdjacentComment(1)}
+                      disabled={commentNavigationIds.length < 2}
+                    >
+                      Next
+                    </AnnotationNavButton>
+                    <AnnotationIconButton
+                      type="button"
+                      aria-label="Close annotation panel"
+                      onClick={() => setActiveComment(null)}
+                    >
+                      <CloseOutlined />
+                    </AnnotationIconButton>
+                  </AnnotationHeaderActions>
+                </CommentCardHeader>
+                <AnnotationBody>
+                  <CommentCardMeta>
+                    {activeComment.author ?? 'Author'}
+                    {activeComment.createdAt
+                      ? ` / ${formatCommentTimestamp(activeComment.createdAt)}`
+                      : ''}
+                  </CommentCardMeta>
+                  <AnnotationQuote>
+                    <AnnotationSubjectLabel>
+                      {
+                        COMMENT_TYPE_DEFINITIONS[activeComment.commentType]
+                          .subjectLabel
+                      }
+                    </AnnotationSubjectLabel>
+                    {activeComment.subjectText}
+                  </AnnotationQuote>
+                  <AnnotationSectionLabel>
+                    Classification
+                  </AnnotationSectionLabel>
+                  <InlineCommentTypeList aria-label="Primary annotation type">
+                    {PRIMARY_COMMENT_TYPES.map(type => (
+                      <InlineCommentTypeButton
+                        key={type}
+                        type="button"
+                        $active={activeComment.commentType === type}
+                        onClick={() =>
+                          updateActiveComment({
+                            commentType: type,
+                            reviewStatus:
+                              defaultCommentReviewStatusForType(type),
+                            severity: defaultCommentSeverityForType(type),
+                          })
+                        }
+                      >
+                        <AnnotationTypeButtonLabel>
+                          {COMMENT_TYPE_LABELS[type]}
+                        </AnnotationTypeButtonLabel>
+                        <AnnotationTypeButtonMeta>
+                          {
+                            COMMENT_STATUS_LABELS[
+                              defaultCommentReviewStatusForType(type)
+                            ]
+                          }
+                        </AnnotationTypeButtonMeta>
+                      </InlineCommentTypeButton>
+                    ))}
+                  </InlineCommentTypeList>
+                  <SecondaryTypeList aria-label="More annotation types">
+                    {SECONDARY_COMMENT_TYPES.map(type => (
+                      <SecondaryTypeButton
+                        key={type}
+                        type="button"
+                        $active={activeComment.commentType === type}
+                        onClick={() =>
+                          updateActiveComment({
+                            commentType: type,
+                            reviewStatus:
+                              defaultCommentReviewStatusForType(type),
+                            severity: defaultCommentSeverityForType(type),
+                          })
+                        }
+                      >
+                        {COMMENT_TYPE_LABELS[type]}
+                      </SecondaryTypeButton>
+                    ))}
+                  </SecondaryTypeList>
+                  <AnnotationSectionLabel>Status</AnnotationSectionLabel>
+                  <ReviewStatusList aria-label="Review status">
+                    {COMMENT_TYPE_DEFINITIONS[
+                      activeComment.commentType
+                    ].statuses.map(status => (
+                      <ReviewStatusButton
+                        key={status}
+                        type="button"
+                        $active={activeComment.reviewStatus === status}
+                        onClick={() =>
+                          updateActiveComment({ reviewStatus: status })
+                        }
+                      >
+                        {COMMENT_STATUS_LABELS[status]}
+                      </ReviewStatusButton>
+                    ))}
+                  </ReviewStatusList>
+                  <AnnotationFieldHeader>
+                    <AnnotationFieldLabel>
+                      {
+                        COMMENT_TYPE_DEFINITIONS[activeComment.commentType]
+                          .noteLabel
+                      }
+                    </AnnotationFieldLabel>
+                    <AnnotationFieldHint>
+                      {COMMENT_STATUS_LABELS[activeComment.reviewStatus]}
+                    </AnnotationFieldHint>
+                  </AnnotationFieldHeader>
+                  <CommentEditTextArea
+                    $spotlight={spotlightCommentId === activeComment.id}
+                    $type={activeComment.commentType}
+                    value={activeComment.text}
+                    rows={4}
+                    aria-label={
+                      COMMENT_TYPE_DEFINITIONS[activeComment.commentType]
+                        .noteLabel
+                    }
+                    placeholder={
+                      COMMENT_TYPE_DEFINITIONS[activeComment.commentType]
+                        .notePlaceholder
+                    }
+                    onChange={event =>
+                      updateActiveComment({ text: event.target.value })
+                    }
+                    onKeyDown={event => {
+                      if (event.key === 'Escape') {
+                        event.preventDefault()
+                        setActiveComment(null)
+                      }
+                      if (
+                        (event.metaKey || event.ctrlKey) &&
+                        event.key === 'Enter'
+                      ) {
+                        event.preventDefault()
+                        saveActiveCommentEdits()
+                      }
+                    }}
+                  />
+                  {activeComment.replies.length > 0 ? (
+                    <CommentReplies>
+                      {activeComment.replies.map(reply => (
+                        <CommentReplyItem key={reply.id}>
+                          <CommentReplyMeta>
+                            {reply.author ?? 'Reply'}
+                            {reply.createdAt
+                              ? ` / ${formatCommentTimestamp(reply.createdAt)}`
+                              : ''}
+                          </CommentReplyMeta>
+                          <div>{reply.text}</div>
+                        </CommentReplyItem>
+                      ))}
+                    </CommentReplies>
+                  ) : null}
+                  <CommentReplyForm
+                    onSubmit={event => {
+                      event.preventDefault()
+                      addReplyToActiveComment()
+                    }}
+                  >
+                    <CommentReplyInput
+                      value={replyText}
+                      rows={2}
+                      placeholder="Add reply..."
+                      onChange={event => setReplyText(event.target.value)}
+                      onKeyDown={event => {
+                        if (
+                          (event.metaKey || event.ctrlKey) &&
+                          event.key === 'Enter'
+                        ) {
+                          event.preventDefault()
+                          addReplyToActiveComment()
+                        }
+                      }}
+                    />
+                    <AnnotationSecondaryButton
+                      type="submit"
+                      disabled={!replyText.trim()}
+                    >
+                      Reply
+                    </AnnotationSecondaryButton>
+                  </CommentReplyForm>
+                </AnnotationBody>
+                <AnnotationFooter>
+                  <AnnotationDangerButton
+                    type="button"
+                    onClick={deleteActiveComment}
+                  >
+                    Delete
+                  </AnnotationDangerButton>
+                  <AnnotationDangerButton
+                    type="button"
+                    onClick={clearAllComments}
+                  >
+                    Clear all
+                  </AnnotationDangerButton>
+                  {activeComment.commentType === 'claim' ? (
+                    <>
+                      {activeComment.reviewStatus !== 'rejected' ? (
+                        <AnnotationSecondaryButton
+                          type="button"
+                          onClick={() =>
+                            setActiveCommentReviewOutcome('rejected', true)
+                          }
+                        >
+                          Reject claim
+                        </AnnotationSecondaryButton>
+                      ) : null}
+                      {activeComment.reviewStatus !== 'supported' ? (
+                        <AnnotationSecondaryButton
+                          type="button"
+                          onClick={() =>
+                            setActiveCommentReviewOutcome('supported', true)
+                          }
+                        >
+                          Mark supported
+                        </AnnotationSecondaryButton>
+                      ) : null}
+                    </>
+                  ) : activeComment.commentType === 'fact-check' ? (
+                    <>
+                      {activeComment.reviewStatus !== 'disputed' ? (
+                        <AnnotationSecondaryButton
+                          type="button"
+                          onClick={() =>
+                            setActiveCommentReviewOutcome('disputed', true)
+                          }
+                        >
+                          Mark disputed
+                        </AnnotationSecondaryButton>
+                      ) : null}
+                      {activeComment.reviewStatus !== 'verified' ? (
+                        <AnnotationSecondaryButton
+                          type="button"
+                          onClick={() =>
+                            setActiveCommentReviewOutcome('verified', true)
+                          }
+                        >
+                          Mark verified
+                        </AnnotationSecondaryButton>
+                      ) : null}
+                    </>
+                  ) : (
+                    <AnnotationSecondaryButton
+                      type="button"
+                      onClick={() =>
+                        setActiveCommentResolved(!activeComment.resolvedAt)
+                      }
+                    >
+                      {activeComment.resolvedAt ? 'Reopen' : 'Resolve'}
+                    </AnnotationSecondaryButton>
+                  )}
+                  <AnnotationPrimaryButton
+                    type="button"
+                    onClick={saveActiveCommentEdits}
+                    disabled={
+                      !activeComment.text.trim() || !activeCommentChanged
+                    }
+                  >
+                    {saveAnnotationLabel(activeComment.commentType)}
+                  </AnnotationPrimaryButton>
+                </AnnotationFooter>
+              </CommentCard>
+            ) : null}
+            {inEditorBottomElement}
+          </EditorWrapper>
+        </DocumentEditorViewport>
+      </EditorContext.Provider>
+    </DocumentEditorRoot>
+  )
+})
+
+const PRIMARY_COMMENT_TYPES: CommentType[] = ['general', 'claim', 'fact-check']
+const ANNOTATION_RAIL_WIDTH = 408
+
+const SECONDARY_COMMENT_TYPES: CommentType[] = [
+  'copy-editing',
+  'formatting',
+  'question',
+]
+
+const MarginAnnotationButton = styled.button<{ $x: number; $y: number }>`
+  position: fixed;
+  left: ${({ $x }) => $x}px;
+  top: ${({ $y }) => $y}px;
+  z-index: 32;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 30px;
+  height: 30px;
+  transform: translateY(-50%);
+  border: 1px solid rgb(from var(--platform-colors-border) r g b / 0.9);
+  border-radius: 50%;
+  background: var(--platform-colors-surface);
+  color: var(--platform-colors-text-secondary);
+  cursor: pointer;
+  box-shadow: 0 8px 24px rgb(from var(--platform-colors-text) r g b / 0.12);
+  padding: 0;
+
+  svg {
+    font-size: 14px;
+  }
+
+  &:hover,
+  &:focus-visible {
+    background: var(--platform-colors-surface-hover);
+    color: var(--platform-colors-text);
+    outline: none;
+  }
+`
+
+const ReviewRailLayer = styled.div<{ $scrolling: boolean }>`
+  position: fixed;
+  inset: 0;
+  z-index: 20;
+  opacity: ${({ $scrolling }) => ($scrolling ? 0 : 1)};
+  pointer-events: none;
+  transition: opacity 90ms ease;
+  visibility: ${({ $scrolling }) => ($scrolling ? 'hidden' : 'visible')};
+`
+
+const ReviewRailButton = styled.button<{
+  $top: number
+  $left: number
+  $type: CommentType
+  $active: boolean
+  $spotlight: boolean
+  $spotlightMuted: boolean
+  $resolved: boolean
+}>`
+  position: fixed;
+  left: ${({ $left }) => $left}px;
+  top: ${({ $top }) => $top}px;
+  display: grid;
+  width: 106px;
+  min-height: 42px;
+  transform: translateY(-50%);
+  border: 1px solid
+    ${({ $type, $active, $spotlight, $resolved }) =>
+      $resolved
+        ? 'var(--platform-colors-border)'
+        : annotationTypeBorderColor($type, $active || $spotlight)};
+  border-left-width: 4px;
+  border-radius: 4px;
+  background: ${({ $type, $active, $resolved }) =>
+    $resolved
+      ? 'rgb(255 255 255)'
+      : $active
+      ? annotationTypeBackgroundColor($type)
+      : 'rgb(255 255 255)'};
+  color: var(--platform-colors-text);
+  cursor: pointer;
+  font-family: var(--platform-typography-font-family, system-ui, sans-serif);
+  line-height: 1.1;
+  padding: 5px 7px 5px 6px;
+  pointer-events: auto;
+  text-align: left;
+  box-shadow: ${({ $active, $spotlight, $type }) =>
+    $spotlight
+      ? `0 10px 30px rgb(15 23 42 / 0.18), 0 0 0 2px rgb(255 255 255), 0 0 0 2px ${annotationTypeBorderColor($type, false)}`
+      : $active
+      ? '0 10px 30px rgb(15 23 42 / 0.2), 0 0 0 2px rgb(255 255 255)'
+      : '0 6px 18px rgb(15 23 42 / 0.14)'};
+  opacity: ${({ $spotlightMuted, $resolved }) =>
+    $spotlightMuted ? 0.26 : $resolved ? 0.58 : 1};
+  transition:
+    opacity 160ms ease,
+    box-shadow 160ms ease,
+    border-color 160ms ease,
+    background-color 160ms ease;
+
+  &:hover,
+  &:focus-visible {
+    border-color: ${({ $type }) => annotationTypeBorderColor($type, true)};
+    outline: none;
+  }
+`
+
+const ReviewRailLabel = styled.span`
+  font-size: 10px;
+  font-weight: 780;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  white-space: nowrap;
+`
+
+const ReviewRailStatus = styled.span`
+  color: var(--platform-colors-text-secondary);
+  font-size: 10px;
+  font-weight: 650;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`
+
+const AnnotationPanel = styled.form<{
+  $x: number
+  $y: number
+  $reviewType?: CommentType
+}>`
+  position: fixed;
+  right: 0;
+  top: var(--annotation-rail-top, 0px);
+  bottom: 0;
+  z-index: 30;
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr) auto;
+  width: min(${ANNOTATION_RAIL_WIDTH}px, calc(100vw - 48px));
+  max-height: none;
+  border: 1px solid
+    ${({ $reviewType }) =>
+      $reviewType
+        ? annotationTypeBorderColor($reviewType, false)
+        : 'rgb(from var(--platform-colors-border) r g b / 0.92)'};
+  border-top-width: ${({ $reviewType }) => ($reviewType ? '4px' : '1px')};
+  border-right: 0;
+  border-bottom: 0;
+  border-radius: 0;
+  background: var(--platform-colors-surface);
+  box-shadow: -12px 0 32px rgb(from var(--platform-colors-text) r g b / 0.1);
+  color: var(--platform-colors-text);
+  font-family: var(--platform-typography-font-family, system-ui, sans-serif);
+  font-size: 13px;
+  line-height: 1.4;
+  overflow: hidden;
+`
+
+const AnnotationPanelHeader = styled.div`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  min-height: 58px;
+  border-bottom: 1px solid var(--platform-colors-border);
+  padding: 12px 14px;
+`
+
+const AnnotationTitleGroup = styled.div`
+  min-width: 0;
+`
+
+const AnnotationPanelKicker = styled.div`
+  color: var(--platform-colors-text-secondary);
+  font-size: 10px;
+  font-weight: 760;
+  letter-spacing: 0.04em;
+  line-height: 1.2;
+  text-transform: uppercase;
+`
+
+const AnnotationPanelTitle = styled.div`
+  color: var(--platform-colors-text);
+  font-size: 14px;
+  font-weight: 720;
+  line-height: 1.25;
+`
+
+const AnnotationIconButton = styled.button`
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: 0 0 auto;
+  width: 28px;
+  height: 28px;
+  border: 1px solid transparent;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--platform-colors-text-secondary);
+  cursor: pointer;
+  padding: 0;
+
+  svg {
+    font-size: 13px;
+  }
+
+  &:hover,
+  &:focus-visible {
+    border-color: var(--platform-colors-border);
+    background: var(--platform-colors-surface-hover);
+    color: var(--platform-colors-text);
+    outline: none;
+  }
+`
+
+const AnnotationHeaderActions = styled.div`
+  display: inline-flex;
+  align-items: center;
+  flex: 0 0 auto;
+  gap: 6px;
+`
+
+const AnnotationNavButton = styled.button`
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  height: 28px;
+  border: 1px solid var(--platform-colors-border);
+  border-radius: 5px;
+  background: var(--platform-colors-surface);
+  color: var(--platform-colors-text-secondary);
+  cursor: pointer;
+  font-family: var(--platform-typography-font-family, system-ui, sans-serif);
+  font-size: 11px;
+  font-weight: 650;
+  line-height: 1;
+  padding: 0 8px;
+
+  &:hover:not(:disabled),
+  &:focus-visible:not(:disabled) {
+    background: var(--platform-colors-surface-hover);
+    color: var(--platform-colors-text);
+    outline: none;
+  }
+
+  &:disabled {
+    cursor: default;
+    opacity: 0.42;
+  }
+`
+
+const AnnotationBody = styled.div`
+  display: grid;
+  gap: 8px;
+  align-content: start;
+  min-height: 0;
+  overflow: auto;
+  padding: 14px;
+`
+
+const AnnotationQuote = styled.blockquote`
+  max-height: 74px;
+  overflow: auto;
+  margin: 0;
+  border-left: 2px solid rgb(from var(--platform-colors-text) r g b / 0.22);
+  color: var(--platform-colors-text-secondary);
+  font-size: 12px;
+  line-height: 1.4;
+  padding: 2px 0 2px 9px;
+  white-space: pre-wrap;
+`
+
+const AnnotationSubjectLabel = styled.span`
+  display: block;
+  margin-bottom: 4px;
+  color: var(--platform-colors-text-disabled);
+  font-size: 10px;
+  font-weight: 760;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+`
+
+const AnnotationSectionLabel = styled.div`
+  margin-top: 4px;
+  color: var(--platform-colors-text-disabled);
+  font-size: 10px;
+  font-weight: 760;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+`
+
+const InlineCommentTypeList = styled.div`
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  overflow: hidden;
+  border: 1px solid var(--platform-colors-border);
+  border-radius: 6px;
+  background: var(--platform-colors-background);
+`
+
+const ReviewStatusList = styled.div`
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+`
+
+const ReviewStatusButton = styled.button<{ $active: boolean }>`
+  min-height: 26px;
+  border: 1px solid
+    ${({ $active }) =>
+      $active
+        ? 'var(--platform-colors-border-strong, var(--platform-colors-text))'
+        : 'var(--platform-colors-border)'};
+  border-radius: 4px;
+  background: ${({ $active }) =>
+    $active
+      ? 'var(--platform-colors-surface-hover)'
+      : 'var(--platform-colors-surface)'};
+  color: ${({ $active }) =>
+    $active
+      ? 'var(--platform-colors-text)'
+      : 'var(--platform-colors-text-secondary)'};
+  cursor: pointer;
+  font: inherit;
+  font-size: 11px;
+  font-weight: 680;
+  padding: 0 9px;
+
+  &:hover,
+  &:focus-visible {
+    border-color: var(--platform-colors-text);
+    outline: none;
+  }
+`
+
+const AnnotationFieldHeader = styled.div`
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
+  margin-top: 6px;
+`
+
+const AnnotationFieldLabel = styled.div`
+  color: var(--platform-colors-text);
+  font-size: 12px;
+  font-weight: 720;
+`
+
+const AnnotationFieldHint = styled.div`
+  color: var(--platform-colors-text-secondary);
+  font-size: 11px;
+  font-weight: 650;
+`
+
+const InlineCommentTypeButton = styled.button<{ $active: boolean }>`
+  display: grid;
+  align-content: center;
+  gap: 2px;
+  min-width: 0;
+  min-height: 34px;
+  border: 0;
+  border-right: 1px solid var(--platform-colors-border);
+  border-bottom: 1px solid var(--platform-colors-border);
+  border-radius: 0;
+  background: ${({ $active }) =>
+    $active
+      ? 'var(--platform-colors-surface-hover)'
+      : 'var(--platform-colors-background)'};
+  color: ${({ $active }) =>
+    $active
+      ? 'var(--platform-colors-text)'
+      : 'var(--platform-colors-text-secondary)'};
+  cursor: pointer;
+  font: inherit;
+  overflow: hidden;
+  padding: 5px 7px;
+  text-overflow: ellipsis;
+
+  &:nth-child(3n) {
+    border-right: 0;
+  }
+
+  &:nth-last-child(-n + 3) {
+    border-bottom: 0;
+  }
+
+  &:hover,
+  &:focus-visible {
+    background: var(--platform-colors-surface-hover);
+    color: var(--platform-colors-text);
+    outline: none;
+  }
+`
+
+const AnnotationTypeButtonLabel = styled.span`
+  overflow: hidden;
+  font-size: 11px;
+  font-weight: 740;
+  line-height: 1.15;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`
+
+const AnnotationTypeButtonMeta = styled.span`
+  overflow: hidden;
+  color: var(--platform-colors-text-secondary);
+  font-size: 9px;
+  font-weight: 640;
+  line-height: 1.15;
+  text-overflow: ellipsis;
+  text-transform: uppercase;
+  white-space: nowrap;
+`
+
+const SecondaryTypeList = styled.div`
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+`
+
+const SecondaryTypeButton = styled.button<{ $active: boolean }>`
+  min-height: 24px;
+  border: 1px solid
+    ${({ $active }) =>
+      $active
+        ? 'var(--platform-colors-text)'
+        : 'var(--platform-colors-border)'};
+  border-radius: 4px;
+  background: ${({ $active }) =>
+    $active
+      ? 'var(--platform-colors-surface-hover)'
+      : 'var(--platform-colors-surface)'};
+  color: ${({ $active }) =>
+    $active
+      ? 'var(--platform-colors-text)'
+      : 'var(--platform-colors-text-secondary)'};
+  cursor: pointer;
+  font: inherit;
+  font-size: 10px;
+  font-weight: 650;
+  padding: 0 7px;
+
+  &:hover,
+  &:focus-visible {
+    border-color: var(--platform-colors-text);
+    color: var(--platform-colors-text);
+    outline: none;
+  }
+`
+
+const InlineCommentTextArea = styled.textarea`
+  min-height: 132px;
+  max-height: 220px;
+  resize: vertical;
+  border: 1px solid var(--platform-colors-border);
+  border-radius: 6px;
+  background: var(--platform-colors-background);
+  color: var(--platform-colors-text);
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.45;
+  padding: 9px 10px;
+  outline: none;
+
+  &:focus {
+    border-color: var(--platform-colors-accent);
+    box-shadow: 0 0 0 2px rgb(from var(--platform-colors-accent) r g b / 0.14);
+  }
+`
+
+const AnnotationFooter = styled.div`
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  align-items: center;
+  gap: 7px;
+  border-top: 1px solid var(--platform-colors-border);
+  background: var(--platform-colors-surface);
+  padding: 10px 12px;
+`
+
+const AnnotationActionButton = styled.button`
+  min-width: 0;
+  min-height: 30px;
+  border: 1px solid var(--platform-colors-border);
+  border-radius: 5px;
+  background: var(--platform-colors-surface);
+  color: var(--platform-colors-text);
+  cursor: pointer;
+  font: inherit;
+  font-size: 11px;
+  font-weight: 680;
+  overflow: hidden;
+  padding: 0 9px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+
+  &:hover:not(:disabled),
+  &:focus-visible {
+    border-color: var(--platform-colors-border-strong);
+    background: var(--platform-colors-surface-hover);
+    outline: none;
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.42;
+  }
+`
+
+const AnnotationPrimaryButton = styled(AnnotationActionButton)`
+  border-color: var(--platform-colors-text);
+  background: var(--platform-colors-text);
+  color: var(--platform-colors-surface);
+  min-width: 92px;
+`
+
+const AnnotationSecondaryButton = AnnotationActionButton
+
+const AnnotationDangerButton = styled(AnnotationActionButton)`
+  margin-right: auto;
+  color: var(--platform-colors-danger, #b42318);
+  min-width: 68px;
+`
+
+function formatCommentTimestamp(value: string): string {
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) return value
+  return date.toLocaleString(undefined, {
+    dateStyle: 'medium',
+    timeStyle: 'short',
+  })
+}
+
+const CommentCard = styled.div<{
+  $x: number
+  $y: number
+  $reviewType?: CommentType
+}>`
+  position: fixed;
+  right: 0;
+  top: var(--annotation-rail-top, 0px);
+  bottom: 0;
+  z-index: 30;
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr) auto;
+  width: min(${ANNOTATION_RAIL_WIDTH}px, calc(100vw - 48px));
+  max-height: none;
+  border: 1px solid
+    ${({ $reviewType }) =>
+      $reviewType
+        ? annotationTypeBorderColor($reviewType, false)
+        : 'rgb(from var(--platform-colors-border) r g b / 0.92)'};
+  border-top-width: ${({ $reviewType }) => ($reviewType ? '4px' : '1px')};
+  border-right: 0;
+  border-bottom: 0;
+  border-radius: 0;
+  background: var(--platform-colors-surface);
+  box-shadow: -12px 0 32px rgb(from var(--platform-colors-text) r g b / 0.1);
+  color: var(--platform-colors-text);
+  font-family: var(--platform-typography-font-family, system-ui, sans-serif);
+  font-size: 13px;
+  line-height: 1.4;
+  overflow: hidden;
+`
+
+const CommentCardHeader = styled.div`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  min-height: 58px;
+  border-bottom: 1px solid var(--platform-colors-border);
+  padding: 12px 14px;
+`
+
+const CommentEditTextArea = styled(InlineCommentTextArea)<{
+  $spotlight: boolean
+  $type: CommentType
+}>`
+  min-height: 112px;
+  border-color: var(--platform-colors-border);
+  background: ${({ $spotlight, $type }) =>
+    $spotlight
+      ? annotationTypeBackgroundColor($type)
+      : 'var(--platform-colors-background)'};
+  box-shadow: ${({ $spotlight, $type }) =>
+    $spotlight
+      ? `inset 2px 0 0 ${annotationTypeBorderColor($type, false)}`
+      : 'none'};
+
+  &:focus {
+    border-color: var(--platform-colors-border);
+    box-shadow: ${({ $spotlight, $type }) =>
+      $spotlight
+        ? `inset 2px 0 0 ${annotationTypeBorderColor($type, false)}, 0 0 0 2px rgb(from var(--platform-colors-accent) r g b / 0.08)`
+        : '0 0 0 2px rgb(from var(--platform-colors-accent) r g b / 0.14)'};
+  }
+`
+
+const CommentCardMeta = styled.div`
+  color: var(--platform-colors-text-disabled);
+  font-size: 11px;
+`
+
+const CommentReplies = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding-top: 10px;
+  border-top: 1px solid rgb(from var(--platform-colors-border) r g b / 0.85);
+`
+
+const CommentReplyItem = styled.div`
+  border-left: 2px solid rgb(from var(--platform-colors-text) r g b / 0.18);
+  padding-left: 8px;
+  white-space: pre-wrap;
+`
+
+const CommentReplyMeta = styled.div`
+  margin-bottom: 2px;
+  color: var(--platform-colors-text-secondary);
+  font-size: 11px;
+  font-weight: 650;
+`
+
+const CommentReplyForm = styled.form`
+  display: grid;
+  grid-template-columns: 1fr auto;
+  gap: 8px;
+  align-items: end;
+  margin-top: 10px;
+`
+
+const CommentReplyInput = styled.textarea`
+  min-height: 42px;
+  max-height: 110px;
+  resize: vertical;
+  border: 1px solid var(--platform-colors-border);
+  border-radius: 6px;
+  background: var(--platform-colors-background);
+  color: var(--platform-colors-text);
+  font: inherit;
+  line-height: 1.35;
+  padding: 7px 8px;
+  outline: none;
+
+  &:focus {
+    border-color: var(--platform-colors-accent);
+    box-shadow: 0 0 0 2px rgb(from var(--platform-colors-accent) r g b / 0.14);
+  }
+`
+
+function panelX(): number {
+  return Math.max(16, window.innerWidth - 392)
+}
+
+function panelY(): number {
+  return 96
+}
+
+function commentDefaultsForType(type: CommentType): {
+  reviewStatus: CommentReviewStatus
+  severity: CommentSeverity
+} {
+  return {
+    reviewStatus: defaultCommentReviewStatusForType(type),
+    severity: defaultCommentSeverityForType(type),
+  }
+}
+
+function newAnnotationTitle(type: CommentType): string {
+  const definition = COMMENT_TYPE_DEFINITIONS[type]
+  return type === 'general'
+    ? 'New note'
+    : `New ${definition.titlePrefix.toLowerCase()}`
+}
+
+function annotationKicker(type: CommentType): string {
+  if (type === 'claim') return 'Claim under review'
+  if (type === 'fact-check') return 'Fact check'
+  return type === 'general' ? 'Annotation' : 'Manuscript review item'
+}
+
+function reviewPanelType(type: CommentType): CommentType | undefined {
+  return type === 'general' ? undefined : type
+}
+
+function annotationTypeBorderColor(type: CommentType, active: boolean): string {
+  if (type === 'claim') return active ? 'rgb(180 83 9 / 0.95)' : 'rgb(217 119 6 / 0.72)'
+  if (type === 'fact-check')
+    return active ? 'rgb(185 28 28 / 0.95)' : 'rgb(220 38 38 / 0.72)'
+  if (type === 'source')
+    return active ? 'rgb(29 78 216 / 0.95)' : 'rgb(37 99 235 / 0.72)'
+  if (type === 'thread')
+    return active ? 'rgb(109 40 217 / 0.95)' : 'rgb(124 58 237 / 0.72)'
+  if (type === 'logic')
+    return active ? 'rgb(51 65 85 / 0.95)' : 'rgb(71 85 105 / 0.72)'
+  if (type === 'conflict')
+    return active ? 'rgb(15 118 110 / 0.95)' : 'rgb(13 148 136 / 0.72)'
+  if (type === 'copyedit')
+    return active ? 'rgb(21 128 61 / 0.95)' : 'rgb(22 163 74 / 0.72)'
+  if (type === 'voice')
+    return active ? 'rgb(190 24 93 / 0.95)' : 'rgb(219 39 119 / 0.72)'
+  if (type === 'citation')
+    return active ? 'rgb(29 78 216 / 0.92)' : 'rgb(37 99 235 / 0.58)'
+  return active
+    ? 'var(--platform-colors-text)'
+    : 'rgb(from var(--platform-colors-border) r g b / 0.92)'
+}
+
+function annotationTypeBackgroundColor(type: CommentType): string {
+  if (type === 'claim') return 'rgb(255 247 237)'
+  if (type === 'fact-check') return 'rgb(254 242 242)'
+  if (type === 'source') return 'rgb(239 246 255)'
+  if (type === 'thread') return 'rgb(245 243 255)'
+  if (type === 'logic') return 'rgb(248 250 252)'
+  if (type === 'conflict') return 'rgb(240 253 250)'
+  if (type === 'copyedit') return 'rgb(240 253 244)'
+  if (type === 'voice') return 'rgb(253 242 248)'
+  return 'rgb(255 255 255)'
+}
+
+function saveAnnotationLabel(type: CommentType): string {
+  if (type === 'claim') return 'Save claim'
+  if (type === 'fact-check') return 'Save fact check'
+  if (type === 'copyedit') return 'Save copyedit'
+  if (type === 'voice') return 'Save voice note'
+  return 'Save'
+}
+
+function annotationTitle(type: CommentType, subjectText: string): string {
+  const prefix = COMMENT_TYPE_DEFINITIONS[type].titlePrefix
+  const subject = subjectText.trim()
+  if (!subject || type === 'general') return prefix
+  return `${prefix}: "${shortAnnotationSubject(subject)}"`
+}
+
+function shortAnnotationSubject(subject: string): string {
+  return subject.length > 62 ? `${subject.slice(0, 59).trim()}...` : subject
+}
+
+function cssEscape(value: string): string {
+  return typeof CSS !== 'undefined' && typeof CSS.escape === 'function'
+    ? CSS.escape(value)
+    : value.replace(/["\\]/g, '\\$&')
+}
+
+function packReviewRailItems(items: ReviewRailItem[]): ReviewRailItem[] {
+  const minGap = 54
+  return [...items]
+    .sort((a, b) => a.top - b.top)
+    .map((item, index, packed) => {
+      if (!index) return item
+      const previous = packed[index - 1]
+      if (!previous || item.top - previous.top >= minGap) return item
+      return { ...item, top: previous.top + minGap }
+    })
+}
+
+function waitForAutoReviewStep(
+  signal?: AbortSignal,
+  delayMs = 3000,
+): Promise<void> {
+  return new Promise(resolve => {
+    if (signal?.aborted) {
+      resolve()
+      return
+    }
+    const timeout = window.setTimeout(resolve, delayMs)
+    signal?.addEventListener(
+      'abort',
+      () => {
+        window.clearTimeout(timeout)
+        resolve()
+      },
+      { once: true },
+    )
+  })
+}
+
+async function runProgressiveAutoReviewFindings(
+  paragraphs: AutoReviewParagraph[],
+  options: RunAutoReviewOptions,
+  onFindings: (findings: AutoReviewFindingInput[]) => void,
+): Promise<void> {
+  if (!options.findingsProvider || !paragraphs.length) return
+  const batches = progressiveAutoReviewBatches(paragraphs)
+  let nextBatchIndex = 0
+  let reportedFindings = 0
+  const concurrency = Math.min(4, batches.length)
+
+  async function runWorker(): Promise<void> {
+    while (nextBatchIndex < batches.length && !options.signal?.aborted) {
+      const batch = batches[nextBatchIndex]
+      nextBatchIndex += 1
+      if (!batch?.length) continue
+      const findings = await options.findingsProvider?.({
+        paragraphs: batch,
+        options: {
+          ...options,
+          maxFindings:
+            typeof options.maxFindings === 'number'
+              ? Math.max(0, options.maxFindings - reportedFindings)
+              : undefined,
+        },
+      })
+      if (!findings?.length) continue
+      const remaining =
+        typeof options.maxFindings === 'number'
+          ? Math.max(0, options.maxFindings - reportedFindings)
+          : findings.length
+      if (!remaining) return
+      const nextFindings = findings.slice(0, remaining)
+      reportedFindings += nextFindings.length
+      onFindings(nextFindings)
+    }
+  }
+
+  await Promise.all(Array.from({ length: concurrency }, () => runWorker()))
+}
+
+export function progressiveAutoReviewBatches(
+  paragraphs: AutoReviewParagraph[],
+): AutoReviewParagraph[][] {
+  const firstBatchSize = 3
+  const firstBatchCount = 4
+  const laterBatchSize = 12
+  const firstParagraphCount = Math.min(
+    paragraphs.length,
+    firstBatchSize * firstBatchCount,
+  )
+  const batches: AutoReviewParagraph[][] = []
+
+  for (let index = 0; index < firstParagraphCount; index += firstBatchSize) {
+    batches.push(paragraphs.slice(index, index + firstBatchSize))
+  }
+  for (
+    let index = firstParagraphCount;
+    index < paragraphs.length;
+    index += laterBatchSize
+  ) {
+    batches.push(paragraphs.slice(index, index + laterBatchSize))
+  }
+
+  return batches
+}
+
+function captureScrollSnapshot(anchor: HTMLElement): ScrollSnapshot {
+  return {
+    windowX: window.scrollX,
+    windowY: window.scrollY,
+    entries: scrollContainersFor(anchor).map(element => ({
+      element,
+      left: element.scrollLeft,
+      top: element.scrollTop,
+    })),
+  }
+}
+
+function restoreScrollSnapshot(snapshot: ScrollSnapshot | null): void {
+  if (!snapshot) return
+  window.scrollTo(snapshot.windowX, snapshot.windowY)
+  for (const entry of snapshot.entries) {
+    entry.element.scrollLeft = entry.left
+    entry.element.scrollTop = entry.top
+  }
+}
+
+function scrollContainersFor(anchor: HTMLElement): HTMLElement[] {
+  const containers: HTMLElement[] = []
+  let element: HTMLElement | null = anchor
+  while (element?.parentElement) {
+    element = element.parentElement
+    const style = window.getComputedStyle(element)
+    const overflow = `${style.overflow} ${style.overflowY} ${style.overflowX}`
+    if (
+      /(auto|scroll|overlay)/.test(overflow) &&
+      (element.scrollHeight > element.clientHeight ||
+        element.scrollWidth > element.clientWidth)
+    ) {
+      containers.push(element)
+    }
+  }
+  const scrollingElement = document.scrollingElement
+  if (
+    scrollingElement instanceof HTMLElement &&
+    !containers.includes(scrollingElement)
+  ) {
+    containers.push(scrollingElement)
+  }
+  return containers
+}
+
+export function isSelectionAnnotatable(
+  editor: Editor,
+  from: number,
+  to: number,
+): boolean {
+  if (editor.isDestroyed || from === to || !editor.isEditable) return false
+  const start = domElementAtPos(editor, Math.min(from, to))
+  const end = domElementAtPos(editor, Math.max(from, to))
+  if (!start || !end) return true
+  const protectedStart = closestAnnotationProtectedElement(start)
+  const protectedEnd = closestAnnotationProtectedElement(end)
+  if (!protectedStart || !protectedEnd) return true
+  return protectedStart !== protectedEnd && !protectedStart.contains(end)
+}
+
+function domElementAtPos(editor: Editor, pos: number): HTMLElement | null {
+  try {
+    const dom = editor.view.domAtPos(pos).node
+    return dom instanceof HTMLElement ? dom : dom.parentElement
+  } catch {
+    return null
+  }
+}
+
+function closestAnnotationProtectedElement(
+  element: HTMLElement,
+): HTMLElement | null {
+  return element.closest(
+    [
+      '[contenteditable="false"]',
+      'cite.ps-citation',
+      '[data-pm-reference-entry="true"]',
+      '[data-pm-generated-references="true"]',
+      '[data-pm-references-empty="true"]',
+    ].join(','),
+  )
+}