@puredesktop/platform-editor 1.0.0-beta.1 → 1.0.0-beta.2

package/src/commentUtils.ts

@@ -1,546 +1,546 @@
-import type { Editor } from '@tiptap/core'
-
-export const COMMENT_TYPES = [
-  'general',
-  'agent-review',
-  'formatting',
-  'copy-editing',
-  'claim',
-  'fact-check',
-  'source',
-  'thread',
-  'conflict',
-  'logic',
-  'copyedit',
-  'voice',
-  'question',
-  'citation',
-] as const
-
-export type CommentType = (typeof COMMENT_TYPES)[number]
-
-export const COMMENT_REVIEW_STATUSES = [
-  'open',
-  'needs-support',
-  'supported',
-  'rejected',
-  'unverified',
-  'verified',
-  'disputed',
-  'needs-source',
-  'suggested',
-  'needs-review',
-  'stale',
-] as const
-
-export type CommentReviewStatus = (typeof COMMENT_REVIEW_STATUSES)[number]
-
-export const COMMENT_SEVERITIES = ['note', 'advisory', 'blocking'] as const
-
-export type CommentSeverity = (typeof COMMENT_SEVERITIES)[number]
-
-export const COMMENT_TYPE_LABELS: Record<CommentType, string> = {
-  general: 'Comment',
-  'agent-review': 'Agent review',
-  formatting: 'Formatting',
-  'copy-editing': 'Edit suggestion',
-  claim: 'Claim',
-  'fact-check': 'Fact check',
-  source: 'Source',
-  thread: 'Thread',
-  conflict: 'Conflict',
-  logic: 'Logic',
-  copyedit: 'Copyedit',
-  voice: 'Voice',
-  question: 'Question',
-  citation: 'Citation',
-}
-
-export interface CommentTypeDefinition {
-  label: string
-  groupLabel: string
-  titlePrefix: string
-  subjectLabel: string
-  noteLabel: string
-  notePlaceholder: string
-  defaultStatus: CommentReviewStatus
-  defaultSeverity: CommentSeverity
-  statuses: CommentReviewStatus[]
-}
-
-export const COMMENT_STATUS_LABELS: Record<CommentReviewStatus, string> = {
-  open: 'Open',
-  'needs-support': 'Needs support',
-  supported: 'Supported',
-  rejected: 'Rejected',
-  unverified: 'Unverified',
-  verified: 'Verified',
-  disputed: 'Disputed',
-  'needs-source': 'Needs source',
-  suggested: 'Suggested',
-  'needs-review': 'Needs review',
-  stale: 'Stale',
-}
-
-export const COMMENT_TYPE_DEFINITIONS: Record<
-  CommentType,
-  CommentTypeDefinition
-> = {
-  general: {
-    label: 'Comment',
-    groupLabel: 'Other notes',
-    titlePrefix: 'Comment',
-    subjectLabel: 'Selected text',
-    noteLabel: 'Note',
-    notePlaceholder: 'Add an editorial note...',
-    defaultStatus: 'open',
-    defaultSeverity: 'note',
-    statuses: ['open'],
-  },
-  'agent-review': {
-    label: 'Agent review',
-    groupLabel: 'Other notes',
-    titlePrefix: 'Agent review',
-    subjectLabel: 'Review target',
-    noteLabel: 'Review note',
-    notePlaceholder: 'Summarize the review finding...',
-    defaultStatus: 'open',
-    defaultSeverity: 'advisory',
-    statuses: ['open'],
-  },
-  formatting: {
-    label: 'Formatting',
-    groupLabel: 'Formatting',
-    titlePrefix: 'Formatting issue',
-    subjectLabel: 'Affected text',
-    noteLabel: 'Formatting note',
-    notePlaceholder: 'Describe the layout, style, or export issue...',
-    defaultStatus: 'open',
-    defaultSeverity: 'advisory',
-    statuses: ['open'],
-  },
-  'copy-editing': {
-    label: 'Edit suggestion',
-    groupLabel: 'Edit suggestions',
-    titlePrefix: 'Edit suggestion',
-    subjectLabel: 'Suggested edit target',
-    noteLabel: 'Suggestion',
-    notePlaceholder: 'Describe the proposed wording change...',
-    defaultStatus: 'open',
-    defaultSeverity: 'note',
-    statuses: ['open'],
-  },
-  claim: {
-    label: 'Claim',
-    groupLabel: 'Claims',
-    titlePrefix: 'Claim',
-    subjectLabel: 'Claim under review',
-    noteLabel: 'Support needed',
-    notePlaceholder: 'What support, citation, or rewrite is needed?',
-    defaultStatus: 'needs-support',
-    defaultSeverity: 'advisory',
-    statuses: ['needs-support', 'supported', 'rejected'],
-  },
-  'fact-check': {
-    label: 'Fact check',
-    groupLabel: 'Fact checks',
-    titlePrefix: 'Fact check',
-    subjectLabel: 'Statement to verify',
-    noteLabel: 'Verification note',
-    notePlaceholder: 'What should be verified, and against what source?',
-    defaultStatus: 'unverified',
-    defaultSeverity: 'advisory',
-    statuses: ['unverified', 'verified', 'disputed'],
-  },
-  source: {
-    label: 'Source',
-    groupLabel: 'Source checks',
-    titlePrefix: 'Source check',
-    subjectLabel: 'Attributed claim',
-    noteLabel: 'Source question',
-    notePlaceholder: 'What should be confirmed against the cited source?',
-    defaultStatus: 'unverified',
-    defaultSeverity: 'advisory',
-    statuses: ['unverified', 'verified', 'disputed'],
-  },
-  thread: {
-    label: 'Thread',
-    groupLabel: 'Thread checks',
-    titlePrefix: 'Thread check',
-    subjectLabel: 'Promise to reader',
-    noteLabel: 'Thread question',
-    notePlaceholder: 'What promise or payoff should be checked?',
-    defaultStatus: 'open',
-    defaultSeverity: 'advisory',
-    statuses: ['open', 'supported', 'rejected'],
-  },
-  conflict: {
-    label: 'Conflict',
-    groupLabel: 'Conflict checks',
-    titlePrefix: 'Conflict check',
-    subjectLabel: 'Conflicting statement',
-    noteLabel: 'Conflict question',
-    notePlaceholder: 'What statements need to be reconciled?',
-    defaultStatus: 'needs-support',
-    defaultSeverity: 'advisory',
-    statuses: ['needs-support', 'supported', 'rejected'],
-  },
-  logic: {
-    label: 'Logic',
-    groupLabel: 'Logic checks',
-    titlePrefix: 'Logic check',
-    subjectLabel: 'Reasoning gap',
-    noteLabel: 'Logic question',
-    notePlaceholder: 'What missing step should be checked?',
-    defaultStatus: 'needs-support',
-    defaultSeverity: 'advisory',
-    statuses: ['needs-support', 'supported', 'rejected'],
-  },
-  copyedit: {
-    label: 'Copyedit',
-    groupLabel: 'Copyedit',
-    titlePrefix: 'Copyedit',
-    subjectLabel: 'Text to correct',
-    noteLabel: 'Suggestion',
-    notePlaceholder: 'Name the rule, correction, or ambiguity...',
-    defaultStatus: 'suggested',
-    defaultSeverity: 'note',
-    statuses: ['suggested', 'stale', 'supported', 'rejected'],
-  },
-  voice: {
-    label: 'Voice',
-    groupLabel: 'Voice',
-    titlePrefix: 'Voice check',
-    subjectLabel: 'Voice drift',
-    noteLabel: 'Voice note',
-    notePlaceholder: 'Point at the drift from the author profile...',
-    defaultStatus: 'needs-review',
-    defaultSeverity: 'advisory',
-    statuses: ['needs-review', 'supported', 'rejected'],
-  },
-  question: {
-    label: 'Question',
-    groupLabel: 'Other notes',
-    titlePrefix: 'Question',
-    subjectLabel: 'Question target',
-    noteLabel: 'Question',
-    notePlaceholder: 'Ask the author or editor a question...',
-    defaultStatus: 'open',
-    defaultSeverity: 'note',
-    statuses: ['open'],
-  },
-  citation: {
-    label: 'Citation issue',
-    groupLabel: 'Citation issues',
-    titlePrefix: 'Citation issue',
-    subjectLabel: 'Citation target',
-    noteLabel: 'Citation note',
-    notePlaceholder: 'Describe the missing, weak, or mismatched source...',
-    defaultStatus: 'needs-source',
-    defaultSeverity: 'advisory',
-    statuses: ['needs-source', 'supported', 'rejected'],
-  },
-}
-
-export function normalizeCommentType(
-  value: string | null | undefined,
-): CommentType {
-  return COMMENT_TYPES.includes(value as CommentType)
-    ? (value as CommentType)
-    : 'general'
-}
-
-export function normalizeCommentReviewStatus(
-  value: string | null | undefined,
-  type: CommentType = 'general',
-): CommentReviewStatus {
-  return COMMENT_REVIEW_STATUSES.includes(value as CommentReviewStatus)
-    ? (value as CommentReviewStatus)
-    : COMMENT_TYPE_DEFINITIONS[type].defaultStatus
-}
-
-export function normalizeCommentSeverity(
-  value: string | null | undefined,
-  type: CommentType = 'general',
-): CommentSeverity {
-  return COMMENT_SEVERITIES.includes(value as CommentSeverity)
-    ? (value as CommentSeverity)
-    : COMMENT_TYPE_DEFINITIONS[type].defaultSeverity
-}
-
-export function defaultCommentReviewStatusForType(
-  type: CommentType,
-): CommentReviewStatus {
-  return COMMENT_TYPE_DEFINITIONS[type].defaultStatus
-}
-
-export function defaultCommentSeverityForType(
-  type: CommentType,
-): CommentSeverity {
-  return COMMENT_TYPE_DEFINITIONS[type].defaultSeverity
-}
-
-export interface CommentReply {
-  id: string
-  text: string
-  author?: string
-  createdAt?: string
-}
-
-export interface CommentMarkAttrs {
-  commentId: string
-  commentText: string
-  author?: string
-  createdAt?: string
-  commentType?: CommentType
-  subjectText?: string
-  reviewStatus?: CommentReviewStatus
-  severity?: CommentSeverity
-  replies?: string
-  resolvedAt?: string
-  resolvedBy?: string
-}
-
-export type CommentMarkAttrPatch = {
-  [Key in keyof CommentMarkAttrs]?: CommentMarkAttrs[Key] | null
-}
-
-export interface CommentMarkMutationOptions {
-  scrollIntoView?: boolean
-  focusEditor?: boolean
-}
-
-export interface AppliedChangeMarkAttrs {
-  originalText: string
-  replacementText: string
-  sourceCommentId?: string
-  sourceType?: string
-  actor?: string
-  createdAt?: string
-}
-
-export function applyCommentMarkToRange(
-  editor: Editor,
-  from: number,
-  to: number,
-  attrs: CommentMarkAttrs,
-  options: CommentMarkMutationOptions = {},
-): boolean {
-  if (editor.isDestroyed) return false
-  const markType = editor.schema.marks.commentMark
-  if (!markType) return false
-  const start = Math.max(0, Math.min(from, to, editor.state.doc.content.size))
-  const end = Math.max(
-    0,
-    Math.min(Math.max(from, to), editor.state.doc.content.size),
-  )
-  if (start === end) return false
-  const tr = editor.state.tr.addMark(start, end, markType.create(attrs))
-  editor.view.dispatch(options.scrollIntoView ? tr.scrollIntoView() : tr)
-  if (options.focusEditor) editor.commands.focus(end)
-  return true
-}
-
-export function updateCommentMarksById(
-  editor: Editor,
-  commentId: string,
-  patch: CommentMarkAttrPatch,
-  options: CommentMarkMutationOptions = {},
-): boolean {
-  if (editor.isDestroyed || !commentId) return false
-  const markType = editor.schema.marks.commentMark
-  if (!markType) return false
-
-  let changed = false
-  const tr = editor.state.tr
-  editor.state.doc.descendants((node, pos) => {
-    if (!node.isText) return true
-    for (const mark of node.marks) {
-      if (mark.type !== markType || mark.attrs.commentId !== commentId) continue
-      const from = pos
-      const to = pos + node.nodeSize
-      const nextAttrs = { ...mark.attrs, ...patch }
-      tr.removeMark(from, to, markType)
-      tr.addMark(from, to, markType.create(nextAttrs))
-      changed = true
-    }
-    return true
-  })
-
-  if (!changed) return false
-  editor.view.dispatch(options.scrollIntoView ? tr.scrollIntoView() : tr)
-  if (options.focusEditor) editor.commands.focus()
-  return true
-}
-
-export function removeCommentMarksById(
-  editor: Editor,
-  commentId: string,
-  options: CommentMarkMutationOptions = {},
-): boolean {
-  if (editor.isDestroyed || !commentId) return false
-  const markType = editor.schema.marks.commentMark
-  if (!markType) return false
-
-  let changed = false
-  const tr = editor.state.tr
-  editor.state.doc.descendants((node, pos) => {
-    if (!node.isText) return true
-    for (const mark of node.marks) {
-      if (mark.type !== markType || mark.attrs.commentId !== commentId) continue
-      tr.removeMark(pos, pos + node.nodeSize, markType)
-      changed = true
-    }
-    return true
-  })
-
-  if (!changed) return false
-  editor.view.dispatch(options.scrollIntoView ? tr.scrollIntoView() : tr)
-  if (options.focusEditor) editor.commands.focus()
-  return true
-}
-
-export function removeAllCommentMarks(
-  editor: Editor,
-  options: CommentMarkMutationOptions = {},
-): number {
-  if (editor.isDestroyed) return 0
-  const markType = editor.schema.marks.commentMark
-  if (!markType) return 0
-
-  const removedIds = new Set<string>()
-  let changed = false
-  editor.state.doc.descendants(node => {
-    if (!node.isText) return true
-    for (const mark of node.marks) {
-      if (mark.type !== markType) continue
-      const commentId = String(mark.attrs.commentId ?? '')
-      if (commentId) removedIds.add(commentId)
-      changed = true
-    }
-    return true
-  })
-
-  if (!changed) return 0
-  const tr = editor.state.tr.removeMark(
-    0,
-    editor.state.doc.content.size,
-    markType,
-  )
-  editor.view.dispatch(options.scrollIntoView ? tr.scrollIntoView() : tr)
-  if (options.focusEditor) editor.commands.focus()
-  return removedIds.size || 1
-}
-
-export function stripCommentMarkupFromHtml(html: string): {
-  html: string
-  removed: number
-} {
-  if (!html.includes('data-comment-id')) return { html, removed: 0 }
-  const parser = new DOMParser()
-  const doc = parser.parseFromString(html, 'text/html')
-  let removed = 0
-  const commentElements = Array.from(
-    doc.body.querySelectorAll<HTMLElement>('[data-comment-id]'),
-  )
-  for (const element of commentElements) {
-    removed += 1
-    element.replaceWith(...Array.from(element.childNodes))
-  }
-  for (const element of Array.from(
-    doc.body.querySelectorAll<HTMLElement>('*'),
-  )) {
-    for (const attribute of Array.from(element.attributes)) {
-      if (
-        attribute.name.startsWith('data-comment-') ||
-        attribute.name === 'data-applied-change'
-      ) {
-        element.removeAttribute(attribute.name)
-      }
-    }
-    element.classList.remove('comment-mark', 'comment-mark--active')
-    if (!element.getAttribute('class')) element.removeAttribute('class')
-  }
-  return { html: doc.body.innerHTML, removed }
-}
-
-export function applyCommentReplacementById(
-  editor: Editor,
-  commentId: string,
-  replacementText: string,
-  attrs: Omit<AppliedChangeMarkAttrs, 'replacementText'>,
-  options: CommentMarkMutationOptions = {},
-): boolean {
-  if (editor.isDestroyed || !commentId) return false
-  const replacement = replacementText.trim()
-  if (!replacement) return false
-  const commentMarkType = editor.schema.marks.commentMark
-  const appliedMarkType = editor.schema.marks.appliedChangeMark
-  if (!commentMarkType || !appliedMarkType) return false
-
-  let from: number | null = null
-  let to: number | null = null
-  editor.state.doc.descendants((node, pos) => {
-    if (!node.isText) return true
-    const hasComment = node.marks.some(
-      mark =>
-        mark.type === commentMarkType && mark.attrs.commentId === commentId,
-    )
-    if (!hasComment) return true
-    from = from === null ? pos : Math.min(from, pos)
-    to = to === null ? pos + node.nodeSize : Math.max(to, pos + node.nodeSize)
-    return true
-  })
-
-  if (from === null || to === null || from >= to) return false
-  const originalText =
-    attrs.originalText || editor.state.doc.textBetween(from, to, ' ')
-  const appliedMark = appliedMarkType.create({
-    ...attrs,
-    originalText,
-    replacementText: replacement,
-    sourceCommentId: attrs.sourceCommentId ?? commentId,
-  })
-  const replacementNode = editor.schema.text(replacement, [appliedMark])
-  const tr = editor.state.tr.replaceWith(from, to, replacementNode)
-  editor.view.dispatch(options.scrollIntoView ? tr.scrollIntoView() : tr)
-  if (options.focusEditor) editor.commands.focus(from + replacement.length)
-  return true
-}
-
-export function parseCommentReplies(
-  value: string | null | undefined,
-): CommentReply[] {
-  if (!value) return []
-  try {
-    const parsed = JSON.parse(value) as unknown
-    if (!Array.isArray(parsed)) return []
-    return parsed
-      .map((reply): CommentReply | null => {
-        if (!reply || typeof reply !== 'object') return null
-        const candidate = reply as Partial<CommentReply>
-        if (typeof candidate.text !== 'string' || !candidate.text.trim())
-          return null
-        return {
-          id:
-            typeof candidate.id === 'string' && candidate.id
-              ? candidate.id
-              : `reply-${Math.random().toString(36).slice(2)}`,
-          text: candidate.text,
-          author:
-            typeof candidate.author === 'string' ? candidate.author : undefined,
-          createdAt:
-            typeof candidate.createdAt === 'string'
-              ? candidate.createdAt
-              : undefined,
-        }
-      })
-      .filter((reply): reply is CommentReply => reply !== null)
-  } catch {
-    return []
-  }
-}
-
-export function serializeCommentReplies(replies: CommentReply[]): string {
-  return JSON.stringify(replies)
-}
+import type { Editor } from '@tiptap/core'
+
+export const COMMENT_TYPES = [
+  'general',
+  'agent-review',
+  'formatting',
+  'copy-editing',
+  'claim',
+  'fact-check',
+  'source',
+  'thread',
+  'conflict',
+  'logic',
+  'copyedit',
+  'voice',
+  'question',
+  'citation',
+] as const
+
+export type CommentType = (typeof COMMENT_TYPES)[number]
+
+export const COMMENT_REVIEW_STATUSES = [
+  'open',
+  'needs-support',
+  'supported',
+  'rejected',
+  'unverified',
+  'verified',
+  'disputed',
+  'needs-source',
+  'suggested',
+  'needs-review',
+  'stale',
+] as const
+
+export type CommentReviewStatus = (typeof COMMENT_REVIEW_STATUSES)[number]
+
+export const COMMENT_SEVERITIES = ['note', 'advisory', 'blocking'] as const
+
+export type CommentSeverity = (typeof COMMENT_SEVERITIES)[number]
+
+export const COMMENT_TYPE_LABELS: Record<CommentType, string> = {
+  general: 'Comment',
+  'agent-review': 'Agent review',
+  formatting: 'Formatting',
+  'copy-editing': 'Edit suggestion',
+  claim: 'Claim',
+  'fact-check': 'Fact check',
+  source: 'Source',
+  thread: 'Thread',
+  conflict: 'Conflict',
+  logic: 'Logic',
+  copyedit: 'Copyedit',
+  voice: 'Voice',
+  question: 'Question',
+  citation: 'Citation',
+}
+
+export interface CommentTypeDefinition {
+  label: string
+  groupLabel: string
+  titlePrefix: string
+  subjectLabel: string
+  noteLabel: string
+  notePlaceholder: string
+  defaultStatus: CommentReviewStatus
+  defaultSeverity: CommentSeverity
+  statuses: CommentReviewStatus[]
+}
+
+export const COMMENT_STATUS_LABELS: Record<CommentReviewStatus, string> = {
+  open: 'Open',
+  'needs-support': 'Needs support',
+  supported: 'Supported',
+  rejected: 'Rejected',
+  unverified: 'Unverified',
+  verified: 'Verified',
+  disputed: 'Disputed',
+  'needs-source': 'Needs source',
+  suggested: 'Suggested',
+  'needs-review': 'Needs review',
+  stale: 'Stale',
+}
+
+export const COMMENT_TYPE_DEFINITIONS: Record<
+  CommentType,
+  CommentTypeDefinition
+> = {
+  general: {
+    label: 'Comment',
+    groupLabel: 'Other notes',
+    titlePrefix: 'Comment',
+    subjectLabel: 'Selected text',
+    noteLabel: 'Note',
+    notePlaceholder: 'Add an editorial note...',
+    defaultStatus: 'open',
+    defaultSeverity: 'note',
+    statuses: ['open'],
+  },
+  'agent-review': {
+    label: 'Agent review',
+    groupLabel: 'Other notes',
+    titlePrefix: 'Agent review',
+    subjectLabel: 'Review target',
+    noteLabel: 'Review note',
+    notePlaceholder: 'Summarize the review finding...',
+    defaultStatus: 'open',
+    defaultSeverity: 'advisory',
+    statuses: ['open'],
+  },
+  formatting: {
+    label: 'Formatting',
+    groupLabel: 'Formatting',
+    titlePrefix: 'Formatting issue',
+    subjectLabel: 'Affected text',
+    noteLabel: 'Formatting note',
+    notePlaceholder: 'Describe the layout, style, or export issue...',
+    defaultStatus: 'open',
+    defaultSeverity: 'advisory',
+    statuses: ['open'],
+  },
+  'copy-editing': {
+    label: 'Edit suggestion',
+    groupLabel: 'Edit suggestions',
+    titlePrefix: 'Edit suggestion',
+    subjectLabel: 'Suggested edit target',
+    noteLabel: 'Suggestion',
+    notePlaceholder: 'Describe the proposed wording change...',
+    defaultStatus: 'open',
+    defaultSeverity: 'note',
+    statuses: ['open'],
+  },
+  claim: {
+    label: 'Claim',
+    groupLabel: 'Claims',
+    titlePrefix: 'Claim',
+    subjectLabel: 'Claim under review',
+    noteLabel: 'Support needed',
+    notePlaceholder: 'What support, citation, or rewrite is needed?',
+    defaultStatus: 'needs-support',
+    defaultSeverity: 'advisory',
+    statuses: ['needs-support', 'supported', 'rejected'],
+  },
+  'fact-check': {
+    label: 'Fact check',
+    groupLabel: 'Fact checks',
+    titlePrefix: 'Fact check',
+    subjectLabel: 'Statement to verify',
+    noteLabel: 'Verification note',
+    notePlaceholder: 'What should be verified, and against what source?',
+    defaultStatus: 'unverified',
+    defaultSeverity: 'advisory',
+    statuses: ['unverified', 'verified', 'disputed'],
+  },
+  source: {
+    label: 'Source',
+    groupLabel: 'Source checks',
+    titlePrefix: 'Source check',
+    subjectLabel: 'Attributed claim',
+    noteLabel: 'Source question',
+    notePlaceholder: 'What should be confirmed against the cited source?',
+    defaultStatus: 'unverified',
+    defaultSeverity: 'advisory',
+    statuses: ['unverified', 'verified', 'disputed'],
+  },
+  thread: {
+    label: 'Thread',
+    groupLabel: 'Thread checks',
+    titlePrefix: 'Thread check',
+    subjectLabel: 'Promise to reader',
+    noteLabel: 'Thread question',
+    notePlaceholder: 'What promise or payoff should be checked?',
+    defaultStatus: 'open',
+    defaultSeverity: 'advisory',
+    statuses: ['open', 'supported', 'rejected'],
+  },
+  conflict: {
+    label: 'Conflict',
+    groupLabel: 'Conflict checks',
+    titlePrefix: 'Conflict check',
+    subjectLabel: 'Conflicting statement',
+    noteLabel: 'Conflict question',
+    notePlaceholder: 'What statements need to be reconciled?',
+    defaultStatus: 'needs-support',
+    defaultSeverity: 'advisory',
+    statuses: ['needs-support', 'supported', 'rejected'],
+  },
+  logic: {
+    label: 'Logic',
+    groupLabel: 'Logic checks',
+    titlePrefix: 'Logic check',
+    subjectLabel: 'Reasoning gap',
+    noteLabel: 'Logic question',
+    notePlaceholder: 'What missing step should be checked?',
+    defaultStatus: 'needs-support',
+    defaultSeverity: 'advisory',
+    statuses: ['needs-support', 'supported', 'rejected'],
+  },
+  copyedit: {
+    label: 'Copyedit',
+    groupLabel: 'Copyedit',
+    titlePrefix: 'Copyedit',
+    subjectLabel: 'Text to correct',
+    noteLabel: 'Suggestion',
+    notePlaceholder: 'Name the rule, correction, or ambiguity...',
+    defaultStatus: 'suggested',
+    defaultSeverity: 'note',
+    statuses: ['suggested', 'stale', 'supported', 'rejected'],
+  },
+  voice: {
+    label: 'Voice',
+    groupLabel: 'Voice',
+    titlePrefix: 'Voice check',
+    subjectLabel: 'Voice drift',
+    noteLabel: 'Voice note',
+    notePlaceholder: 'Point at the drift from the author profile...',
+    defaultStatus: 'needs-review',
+    defaultSeverity: 'advisory',
+    statuses: ['needs-review', 'supported', 'rejected'],
+  },
+  question: {
+    label: 'Question',
+    groupLabel: 'Other notes',
+    titlePrefix: 'Question',
+    subjectLabel: 'Question target',
+    noteLabel: 'Question',
+    notePlaceholder: 'Ask the author or editor a question...',
+    defaultStatus: 'open',
+    defaultSeverity: 'note',
+    statuses: ['open'],
+  },
+  citation: {
+    label: 'Citation issue',
+    groupLabel: 'Citation issues',
+    titlePrefix: 'Citation issue',
+    subjectLabel: 'Citation target',
+    noteLabel: 'Citation note',
+    notePlaceholder: 'Describe the missing, weak, or mismatched source...',
+    defaultStatus: 'needs-source',
+    defaultSeverity: 'advisory',
+    statuses: ['needs-source', 'supported', 'rejected'],
+  },
+}
+
+export function normalizeCommentType(
+  value: string | null | undefined,
+): CommentType {
+  return COMMENT_TYPES.includes(value as CommentType)
+    ? (value as CommentType)
+    : 'general'
+}
+
+export function normalizeCommentReviewStatus(
+  value: string | null | undefined,
+  type: CommentType = 'general',
+): CommentReviewStatus {
+  return COMMENT_REVIEW_STATUSES.includes(value as CommentReviewStatus)
+    ? (value as CommentReviewStatus)
+    : COMMENT_TYPE_DEFINITIONS[type].defaultStatus
+}
+
+export function normalizeCommentSeverity(
+  value: string | null | undefined,
+  type: CommentType = 'general',
+): CommentSeverity {
+  return COMMENT_SEVERITIES.includes(value as CommentSeverity)
+    ? (value as CommentSeverity)
+    : COMMENT_TYPE_DEFINITIONS[type].defaultSeverity
+}
+
+export function defaultCommentReviewStatusForType(
+  type: CommentType,
+): CommentReviewStatus {
+  return COMMENT_TYPE_DEFINITIONS[type].defaultStatus
+}
+
+export function defaultCommentSeverityForType(
+  type: CommentType,
+): CommentSeverity {
+  return COMMENT_TYPE_DEFINITIONS[type].defaultSeverity
+}
+
+export interface CommentReply {
+  id: string
+  text: string
+  author?: string
+  createdAt?: string
+}
+
+export interface CommentMarkAttrs {
+  commentId: string
+  commentText: string
+  author?: string
+  createdAt?: string
+  commentType?: CommentType
+  subjectText?: string
+  reviewStatus?: CommentReviewStatus
+  severity?: CommentSeverity
+  replies?: string
+  resolvedAt?: string
+  resolvedBy?: string
+}
+
+export type CommentMarkAttrPatch = {
+  [Key in keyof CommentMarkAttrs]?: CommentMarkAttrs[Key] | null
+}
+
+export interface CommentMarkMutationOptions {
+  scrollIntoView?: boolean
+  focusEditor?: boolean
+}
+
+export interface AppliedChangeMarkAttrs {
+  originalText: string
+  replacementText: string
+  sourceCommentId?: string
+  sourceType?: string
+  actor?: string
+  createdAt?: string
+}
+
+export function applyCommentMarkToRange(
+  editor: Editor,
+  from: number,
+  to: number,
+  attrs: CommentMarkAttrs,
+  options: CommentMarkMutationOptions = {},
+): boolean {
+  if (editor.isDestroyed) return false
+  const markType = editor.schema.marks.commentMark
+  if (!markType) return false
+  const start = Math.max(0, Math.min(from, to, editor.state.doc.content.size))
+  const end = Math.max(
+    0,
+    Math.min(Math.max(from, to), editor.state.doc.content.size),
+  )
+  if (start === end) return false
+  const tr = editor.state.tr.addMark(start, end, markType.create(attrs))
+  editor.view.dispatch(options.scrollIntoView ? tr.scrollIntoView() : tr)
+  if (options.focusEditor) editor.commands.focus(end)
+  return true
+}
+
+export function updateCommentMarksById(
+  editor: Editor,
+  commentId: string,
+  patch: CommentMarkAttrPatch,
+  options: CommentMarkMutationOptions = {},
+): boolean {
+  if (editor.isDestroyed || !commentId) return false
+  const markType = editor.schema.marks.commentMark
+  if (!markType) return false
+
+  let changed = false
+  const tr = editor.state.tr
+  editor.state.doc.descendants((node, pos) => {
+    if (!node.isText) return true
+    for (const mark of node.marks) {
+      if (mark.type !== markType || mark.attrs.commentId !== commentId) continue
+      const from = pos
+      const to = pos + node.nodeSize
+      const nextAttrs = { ...mark.attrs, ...patch }
+      tr.removeMark(from, to, markType)
+      tr.addMark(from, to, markType.create(nextAttrs))
+      changed = true
+    }
+    return true
+  })
+
+  if (!changed) return false
+  editor.view.dispatch(options.scrollIntoView ? tr.scrollIntoView() : tr)
+  if (options.focusEditor) editor.commands.focus()
+  return true
+}
+
+export function removeCommentMarksById(
+  editor: Editor,
+  commentId: string,
+  options: CommentMarkMutationOptions = {},
+): boolean {
+  if (editor.isDestroyed || !commentId) return false
+  const markType = editor.schema.marks.commentMark
+  if (!markType) return false
+
+  let changed = false
+  const tr = editor.state.tr
+  editor.state.doc.descendants((node, pos) => {
+    if (!node.isText) return true
+    for (const mark of node.marks) {
+      if (mark.type !== markType || mark.attrs.commentId !== commentId) continue
+      tr.removeMark(pos, pos + node.nodeSize, markType)
+      changed = true
+    }
+    return true
+  })
+
+  if (!changed) return false
+  editor.view.dispatch(options.scrollIntoView ? tr.scrollIntoView() : tr)
+  if (options.focusEditor) editor.commands.focus()
+  return true
+}
+
+export function removeAllCommentMarks(
+  editor: Editor,
+  options: CommentMarkMutationOptions = {},
+): number {
+  if (editor.isDestroyed) return 0
+  const markType = editor.schema.marks.commentMark
+  if (!markType) return 0
+
+  const removedIds = new Set<string>()
+  let changed = false
+  editor.state.doc.descendants(node => {
+    if (!node.isText) return true
+    for (const mark of node.marks) {
+      if (mark.type !== markType) continue
+      const commentId = String(mark.attrs.commentId ?? '')
+      if (commentId) removedIds.add(commentId)
+      changed = true
+    }
+    return true
+  })
+
+  if (!changed) return 0
+  const tr = editor.state.tr.removeMark(
+    0,
+    editor.state.doc.content.size,
+    markType,
+  )
+  editor.view.dispatch(options.scrollIntoView ? tr.scrollIntoView() : tr)
+  if (options.focusEditor) editor.commands.focus()
+  return removedIds.size || 1
+}
+
+export function stripCommentMarkupFromHtml(html: string): {
+  html: string
+  removed: number
+} {
+  if (!html.includes('data-comment-id')) return { html, removed: 0 }
+  const parser = new DOMParser()
+  const doc = parser.parseFromString(html, 'text/html')
+  let removed = 0
+  const commentElements = Array.from(
+    doc.body.querySelectorAll<HTMLElement>('[data-comment-id]'),
+  )
+  for (const element of commentElements) {
+    removed += 1
+    element.replaceWith(...Array.from(element.childNodes))
+  }
+  for (const element of Array.from(
+    doc.body.querySelectorAll<HTMLElement>('*'),
+  )) {
+    for (const attribute of Array.from(element.attributes)) {
+      if (
+        attribute.name.startsWith('data-comment-') ||
+        attribute.name === 'data-applied-change'
+      ) {
+        element.removeAttribute(attribute.name)
+      }
+    }
+    element.classList.remove('comment-mark', 'comment-mark--active')
+    if (!element.getAttribute('class')) element.removeAttribute('class')
+  }
+  return { html: doc.body.innerHTML, removed }
+}
+
+export function applyCommentReplacementById(
+  editor: Editor,
+  commentId: string,
+  replacementText: string,
+  attrs: Omit<AppliedChangeMarkAttrs, 'replacementText'>,
+  options: CommentMarkMutationOptions = {},
+): boolean {
+  if (editor.isDestroyed || !commentId) return false
+  const replacement = replacementText.trim()
+  if (!replacement) return false
+  const commentMarkType = editor.schema.marks.commentMark
+  const appliedMarkType = editor.schema.marks.appliedChangeMark
+  if (!commentMarkType || !appliedMarkType) return false
+
+  let from: number | null = null
+  let to: number | null = null
+  editor.state.doc.descendants((node, pos) => {
+    if (!node.isText) return true
+    const hasComment = node.marks.some(
+      mark =>
+        mark.type === commentMarkType && mark.attrs.commentId === commentId,
+    )
+    if (!hasComment) return true
+    from = from === null ? pos : Math.min(from, pos)
+    to = to === null ? pos + node.nodeSize : Math.max(to, pos + node.nodeSize)
+    return true
+  })
+
+  if (from === null || to === null || from >= to) return false
+  const originalText =
+    attrs.originalText || editor.state.doc.textBetween(from, to, ' ')
+  const appliedMark = appliedMarkType.create({
+    ...attrs,
+    originalText,
+    replacementText: replacement,
+    sourceCommentId: attrs.sourceCommentId ?? commentId,
+  })
+  const replacementNode = editor.schema.text(replacement, [appliedMark])
+  const tr = editor.state.tr.replaceWith(from, to, replacementNode)
+  editor.view.dispatch(options.scrollIntoView ? tr.scrollIntoView() : tr)
+  if (options.focusEditor) editor.commands.focus(from + replacement.length)
+  return true
+}
+
+export function parseCommentReplies(
+  value: string | null | undefined,
+): CommentReply[] {
+  if (!value) return []
+  try {
+    const parsed = JSON.parse(value) as unknown
+    if (!Array.isArray(parsed)) return []
+    return parsed
+      .map((reply): CommentReply | null => {
+        if (!reply || typeof reply !== 'object') return null
+        const candidate = reply as Partial<CommentReply>
+        if (typeof candidate.text !== 'string' || !candidate.text.trim())
+          return null
+        return {
+          id:
+            typeof candidate.id === 'string' && candidate.id
+              ? candidate.id
+              : `reply-${Math.random().toString(36).slice(2)}`,
+          text: candidate.text,
+          author:
+            typeof candidate.author === 'string' ? candidate.author : undefined,
+          createdAt:
+            typeof candidate.createdAt === 'string'
+              ? candidate.createdAt
+              : undefined,
+        }
+      })
+      .filter((reply): reply is CommentReply => reply !== null)
+  } catch {
+    return []
+  }
+}
+
+export function serializeCommentReplies(replies: CommentReply[]): string {
+  return JSON.stringify(replies)
+}