@puredesktop/platform-editor 1.0.0-beta.1

package/src/alignedLineDiff.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+import { buildAlignedLineDiff } from './alignedLineDiff.js'
+
+describe('buildAlignedLineDiff', () => {
+  it('returns matching lines when texts are equal', () => {
+    const { leftLines, rightLines } = buildAlignedLineDiff(
+      'alpha\nbeta',
+      'alpha\nbeta',
+    )
+
+    expect(leftLines).toEqual([
+      { kind: 'same', lineNumber: 1, text: 'alpha' },
+      { kind: 'same', lineNumber: 2, text: 'beta' },
+    ])
+    expect(rightLines).toEqual([
+      { kind: 'same', lineNumber: 1, text: 'alpha' },
+      { kind: 'same', lineNumber: 2, text: 'beta' },
+    ])
+  })
+
+  it('aligns removals on the left and additions on the right', () => {
+    const { leftLines, rightLines } = buildAlignedLineDiff(
+      'keep\nold\nstay',
+      'keep\nnew\nstay',
+    )
+
+    expect(leftLines.map(line => line.kind)).toEqual([
+      'same',
+      'removed',
+      'pad',
+      'same',
+    ])
+    expect(rightLines.map(line => line.kind)).toEqual([
+      'same',
+      'pad',
+      'added',
+      'same',
+    ])
+    expect(leftLines[1]?.text).toBe('old')
+    expect(rightLines[2]?.text).toBe('new')
+    expect(leftLines[1]?.lineNumber).toBe(2)
+    expect(rightLines[2]?.lineNumber).toBe(2)
+  })
+
+  it('pads the opposite column for insertions and deletions', () => {
+    const { leftLines, rightLines } = buildAlignedLineDiff('a\nb', 'a\nc\nd')
+
+    expect(leftLines.some(line => line.kind === 'pad')).toBe(true)
+    expect(rightLines.some(line => line.kind === 'pad')).toBe(true)
+    expect(leftLines.length).toBe(rightLines.length)
+  })
+})

package/src/alignedLineDiff.ts

@@ -0,0 +1,67 @@
+import { diffLines, type Change } from 'diff'
+
+export type AlignedDiffLineKind = 'same' | 'added' | 'removed' | 'pad'
+
+export interface AlignedDiffLine {
+  kind: AlignedDiffLineKind
+  lineNumber: number | null
+  text: string
+}
+
+export interface AlignedLineDiffResult {
+  leftLines: AlignedDiffLine[]
+  rightLines: AlignedDiffLine[]
+}
+
+function stripFinalNewline(value: string): string {
+  return value.endsWith('\n') ? value.slice(0, -1) : value
+}
+
+/**
+ * Line-diff two strings into aligned left/right columns.
+ * Removals stay on the left; additions on the right; the other side pads.
+ */
+export function buildAlignedLineDiff(
+  left: string,
+  right: string,
+): AlignedLineDiffResult {
+  const parts: Change[] = diffLines(left, right)
+  const leftLines: AlignedDiffLine[] = []
+  const rightLines: AlignedDiffLine[] = []
+  let leftLineNumber = 0
+  let rightLineNumber = 0
+
+  for (const part of parts) {
+    const lines = stripFinalNewline(part.value).split('\n')
+    if (part.added) {
+      for (const text of lines) {
+        rightLineNumber += 1
+        rightLines.push({
+          kind: 'added',
+          lineNumber: rightLineNumber,
+          text,
+        })
+        leftLines.push({ kind: 'pad', lineNumber: null, text: '' })
+      }
+    } else if (part.removed) {
+      for (const text of lines) {
+        leftLineNumber += 1
+        leftLines.push({
+          kind: 'removed',
+          lineNumber: leftLineNumber,
+          text,
+        })
+        rightLines.push({ kind: 'pad', lineNumber: null, text: '' })
+      }
+    } else {
+      for (const text of lines) {
+        leftLineNumber += 1
+        rightLineNumber += 1
+        leftLines.push({ kind: 'same', lineNumber: leftLineNumber, text })
+        rightLines.push({ kind: 'same', lineNumber: rightLineNumber, text })
+      }
+    }
+  }
+
+  return { leftLines, rightLines }
+}

package/src/collectionAssetSrc.ts

@@ -0,0 +1,2 @@
+/** Sidecar attribute for collection-relative image paths (shell usage scan compat). */
+export const COLLECTION_ASSET_SRC_ATTR = 'data-writer-asset-src'

package/src/commentUtils.test.ts

@@ -0,0 +1,350 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  COMMENT_STATUS_LABELS,
+  COMMENT_TYPE_DEFINITIONS,
+  applyCommentMarkToRange,
+  applyCommentReplacementById,
+  normalizeCommentReviewStatus,
+  removeAllCommentMarks,
+  removeCommentMarksById,
+  serializeCommentReplies,
+  stripCommentMarkupFromHtml,
+  updateCommentMarksById,
+} from './commentUtils.js'
+import { AppliedChangeMark } from './extensions/appliedChangeMark.js'
+import { CommentMark } from './extensions/commentMark.js'
+
+describe('comment marks', () => {
+  it('does not scroll or focus the editor by default when creating marks', () => {
+    const editor = new Editor({
+      extensions: [StarterKit, CommentMark],
+      content: '<p>Review this sentence.</p>',
+    })
+    const dispatchSpy = vi.spyOn(editor.view, 'dispatch')
+    const focusSpy = vi.spyOn(editor.view, 'focus')
+
+    expect(
+      applyCommentMarkToRange(editor, 1, 7, {
+        commentId: 'comment-quiet',
+        commentText: 'No viewport jump.',
+      }),
+    ).toBe(true)
+
+    expect(dispatchSpy).toHaveBeenCalledOnce()
+    expect(dispatchSpy.mock.calls[0]?.[0].scrolledIntoView).toBe(false)
+    expect(focusSpy).not.toHaveBeenCalled()
+    editor.destroy()
+  })
+
+  it('can opt into scroll and focus behavior for compatibility', () => {
+    const mark = { id: 'mark' }
+    const transaction = {
+      scrolledIntoView: false,
+      addMark: vi.fn(() => transaction),
+      scrollIntoView: vi.fn(() => {
+        transaction.scrolledIntoView = true
+        return transaction
+      }),
+    }
+    const focusSpy = vi.fn()
+    const dispatchSpy = vi.fn()
+    const editor = {
+      isDestroyed: false,
+      schema: {
+        marks: {
+          commentMark: {
+            create: vi.fn(() => mark),
+          },
+        },
+      },
+      state: {
+        doc: { content: { size: 24 } },
+        tr: transaction,
+      },
+      view: { dispatch: dispatchSpy },
+      commands: { focus: focusSpy },
+    } as unknown as Editor
+
+    expect(
+      applyCommentMarkToRange(
+        editor,
+        1,
+        7,
+        {
+          commentId: 'comment-scroll',
+          commentText: 'Scroll on purpose.',
+        },
+        { scrollIntoView: true, focusEditor: true },
+      ),
+    ).toBe(true)
+
+    expect(transaction.scrollIntoView).toHaveBeenCalledOnce()
+    expect(dispatchSpy).toHaveBeenCalledWith(transaction)
+    expect(focusSpy).toHaveBeenCalledWith(7)
+  })
+
+  it('does not scroll or focus the editor by default when updating or deleting marks', () => {
+    const editor = new Editor({
+      extensions: [StarterKit, CommentMark],
+      content: '<p>Review this sentence.</p>',
+    })
+    expect(
+      applyCommentMarkToRange(editor, 1, 7, {
+        commentId: 'comment-static',
+        commentText: 'Static viewport.',
+      }),
+    ).toBe(true)
+    const dispatchSpy = vi.spyOn(editor.view, 'dispatch')
+    const focusSpy = vi.spyOn(editor.view, 'focus')
+
+    expect(
+      updateCommentMarksById(editor, 'comment-static', {
+        commentText: 'Still static.',
+      }),
+    ).toBe(true)
+    expect(removeCommentMarksById(editor, 'comment-static')).toBe(true)
+
+    expect(dispatchSpy).toHaveBeenCalledTimes(2)
+    expect(dispatchSpy.mock.calls[0]?.[0].scrolledIntoView).toBe(false)
+    expect(dispatchSpy.mock.calls[1]?.[0].scrolledIntoView).toBe(false)
+    expect(focusSpy).not.toHaveBeenCalled()
+    editor.destroy()
+  })
+
+  it('clears every comment mark without deleting manuscript text', () => {
+    const editor = new Editor({
+      extensions: [StarterKit, CommentMark],
+      content: '<p>Review this sentence and verify that statement.</p>',
+    })
+
+    expect(
+      applyCommentMarkToRange(editor, 1, 7, {
+        commentId: 'comment-clear-1',
+        commentText: 'Support this.',
+        commentType: 'claim',
+      }),
+    ).toBe(true)
+    expect(
+      applyCommentMarkToRange(editor, 26, 32, {
+        commentId: 'comment-clear-2',
+        commentText: 'Verify this.',
+        commentType: 'fact-check',
+      }),
+    ).toBe(true)
+
+    expect(removeAllCommentMarks(editor)).toBe(2)
+    expect(editor.getHTML()).not.toContain('data-comment-id=')
+    expect(editor.getText()).toContain(
+      'Review this sentence and verify that statement.',
+    )
+    editor.destroy()
+  })
+
+  it('serializes comment text into persisted editor HTML', () => {
+    const editor = new Editor({
+      extensions: [StarterKit, CommentMark],
+      content: '<p>Review this sentence.</p>',
+    })
+
+    const start = editor.state.doc
+      .textBetween(0, editor.state.doc.content.size)
+      .indexOf('Review')
+    expect(start).toBeGreaterThanOrEqual(0)
+
+    const from = start + 1
+    const to = from + 'Review'.length
+    const applied = applyCommentMarkToRange(editor, from, to, {
+      commentId: 'comment-1',
+      commentText: 'Clarify the claim.',
+      commentType: 'claim',
+      subjectText: 'Review',
+      author: 'Reviewer',
+      createdAt: '2026-06-11T12:00:00.000Z',
+    })
+
+    expect(applied).toBe(true)
+    expect(editor.getHTML()).toContain('data-comment-id="comment-1"')
+    expect(editor.getHTML()).toContain('data-comment-text="Clarify the claim."')
+    expect(editor.getHTML()).toContain('data-comment-type="claim"')
+    expect(editor.getHTML()).toContain('data-comment-subject="Review"')
+    expect(editor.getHTML()).toContain(
+      'data-comment-review-status="needs-support"',
+    )
+    expect(editor.getHTML()).toContain('data-comment-severity="advisory"')
+    expect(editor.getHTML()).toContain('comment-mark--claim')
+    expect(editor.getHTML()).toContain('data-comment-author="Reviewer"')
+    editor.destroy()
+  })
+
+  it('serializes comment replies and resolution state', () => {
+    const editor = new Editor({
+      extensions: [StarterKit, CommentMark],
+      content: '<p>Review this sentence.</p>',
+    })
+
+    expect(
+      applyCommentMarkToRange(editor, 1, 7, {
+        commentId: 'comment-2',
+        commentText: 'Check this.',
+        commentType: 'fact-check',
+        subjectText: 'Review',
+        author: 'Reviewer',
+        createdAt: '2026-06-11T12:00:00.000Z',
+      }),
+    ).toBe(true)
+
+    expect(
+      updateCommentMarksById(editor, 'comment-2', {
+        replies: serializeCommentReplies([
+          {
+            id: 'reply-1',
+            text: 'Updated.',
+            author: 'Author',
+            createdAt: '2026-06-11T12:05:00.000Z',
+          },
+        ]),
+        resolvedAt: '2026-06-11T12:10:00.000Z',
+        resolvedBy: 'Author',
+      }),
+    ).toBe(true)
+
+    expect(editor.getHTML()).toContain('data-comment-replies=')
+    expect(editor.getHTML()).toContain('Updated.')
+    expect(editor.getHTML()).toContain(
+      'data-comment-resolved-at="2026-06-11T12:10:00.000Z"',
+    )
+    expect(editor.getHTML()).toContain('comment-mark--resolved')
+    expect(editor.getHTML()).toContain('data-comment-review-status="unverified"')
+
+    expect(
+      updateCommentMarksById(editor, 'comment-2', {
+        resolvedAt: null,
+        resolvedBy: null,
+      }),
+    ).toBe(true)
+
+    expect(editor.getHTML()).not.toContain('data-comment-resolved-at')
+    editor.destroy()
+  })
+
+  it('updates review status without changing manuscript text', () => {
+    const editor = new Editor({
+      extensions: [StarterKit, CommentMark],
+      content: '<p>Review this sentence.</p>',
+    })
+
+    expect(
+      applyCommentMarkToRange(editor, 1, 7, {
+        commentId: 'comment-status',
+        commentText: 'Needs support.',
+        commentType: 'claim',
+        subjectText: 'Review',
+      }),
+    ).toBe(true)
+
+    expect(
+      updateCommentMarksById(editor, 'comment-status', {
+        reviewStatus: 'supported',
+      }),
+    ).toBe(true)
+
+    expect(editor.getHTML()).toContain('data-comment-review-status="supported"')
+    expect(editor.getText()).toContain('Review this sentence.')
+    editor.destroy()
+  })
+
+  it('supports question annotations as a built-in comment type', () => {
+    const editor = new Editor({
+      extensions: [StarterKit, CommentMark],
+      content: '<p>Can this claim be clearer?</p>',
+    })
+
+    expect(
+      applyCommentMarkToRange(editor, 1, 4, {
+        commentId: 'comment-question',
+        commentText: 'Ask the author to clarify.',
+        commentType: 'question',
+      }),
+    ).toBe(true)
+
+    expect(editor.getHTML()).toContain('data-comment-type="question"')
+    expect(editor.getHTML()).toContain('comment-mark--question')
+    editor.destroy()
+  })
+
+  it('strips stale comment spans while preserving manuscript text', () => {
+    const result = stripCommentMarkupFromHtml(
+      '<p>Keep <span data-comment-id="c1" data-comment-type="claim" class="comment-mark comment-mark--claim">this text</span> clean.</p>',
+    )
+
+    expect(result.removed).toBe(1)
+    expect(result.html).toBe('<p>Keep this text clean.</p>')
+    expect(result.html).not.toContain('data-comment-id')
+    expect(result.html).not.toContain('comment-mark')
+  })
+
+  it('supports stale copyedit annotations after standards change', () => {
+    expect(COMMENT_STATUS_LABELS.stale).toBe('Stale')
+    expect(COMMENT_TYPE_DEFINITIONS.copyedit.statuses).toContain('stale')
+    expect(normalizeCommentReviewStatus('stale', 'copyedit')).toBe('stale')
+  })
+
+  it('removes all marks for a deleted comment', () => {
+    const editor = new Editor({
+      extensions: [StarterKit, CommentMark],
+      content: '<p>Delete this annotation.</p>',
+    })
+
+    expect(
+      applyCommentMarkToRange(editor, 1, 7, {
+        commentId: 'comment-delete',
+        commentText: 'Remove me.',
+        commentType: 'general',
+      }),
+    ).toBe(true)
+
+    expect(removeCommentMarksById(editor, 'comment-delete')).toBe(true)
+    expect(editor.getHTML()).not.toContain('data-comment-id="comment-delete"')
+    expect(editor.getHTML()).toContain('Delete this annotation.')
+    editor.destroy()
+  })
+
+  it('accepts a copy edit as an applied manuscript change', () => {
+    const editor = new Editor({
+      extensions: [StarterKit, CommentMark, AppliedChangeMark],
+      content: '<p>Review this sentence.</p>',
+    })
+
+    expect(
+      applyCommentMarkToRange(editor, 1, 7, {
+        commentId: 'comment-edit',
+        commentText: 'Revise',
+        commentType: 'copy-editing',
+        subjectText: 'Review',
+      }),
+    ).toBe(true)
+
+    expect(
+      applyCommentReplacementById(editor, 'comment-edit', 'Revise', {
+        originalText: 'Review',
+        sourceType: 'copy-editing',
+        actor: 'Author',
+        createdAt: '2026-06-18T12:00:00.000Z',
+      }),
+    ).toBe(true)
+
+    const html = editor.getHTML()
+    expect(editor.getText()).toContain('Revise this sentence.')
+    expect(html).toContain('data-pm-applied-change="true"')
+    expect(html).toContain('data-pm-applied-original="Review"')
+    expect(html).toContain('data-pm-applied-replacement="Revise"')
+    expect(html).toContain('data-pm-applied-source-comment-id="comment-edit"')
+    expect(html).not.toContain('data-comment-id="comment-edit"')
+    editor.destroy()
+  })
+})