@startsimpli/ui 0.4.143 → 0.4.144

package/src/components/track-changes/__tests__/rails.test.tsx

@@ -0,0 +1,604 @@
+/**
+ * The rail, the Read view, the Final/Original views and the composer
+ * (bd startsim-whwxd.3).
+ *
+ * What must hold: open suggestions and threads list in document order and are
+ * reachable by keyboard; accept and reject exist only for someone who may
+ * edit; a view-only reviewer can still suggest, comment, reply and resolve;
+ * marks in the RENDERED text sit at their source offsets and are never drawn
+ * at a guessed place; Final applies the open suggestions and names the ones it
+ * could not; a read for another version says so instead of going quiet; and
+ * a mention is a sub carried in-app, never an email.
+ */
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
+import { renderHook } from '@testing-library/react'
+
+// react-markdown ships ESM that this jest config does not transform, so the
+// renderer is stood in by one that runs the SAME rehype plugins over a
+// one-paragraph tree. The transform itself is tested on real hast below.
+jest.mock('../../blog/MarkdownRenderer', () => {
+  const { plainTree } = jest.requireActual('../read-marks')
+  const { renderHast } = jest.requireActual('../TrackedReadView')
+  return {
+    MarkdownRenderer: ({ content, rehypePlugins }: { content: string; rehypePlugins?: Array<() => (t: unknown) => void> }) => {
+      const tree = plainTree(content)
+      for (const p of rehypePlugins ?? []) p()(tree)
+      return <div data-testid="md">{renderHast(tree)}</div>
+    },
+  }
+})
+
+import { ChangesRail, mentionQuery, mentionsIn } from '../ChangesRail'
+import { applyOpenSuggestions } from '../final-text'
+import { createHttpTrackChangesClient, TrackChangesHttpError } from '../http-client'
+import { alignToSource, markTree, plainTree, sourceOffsetOf, type HastElement, type HastRoot } from '../read-marks'
+import { TrackedField } from '../TrackedField'
+import { renderHast, TrackedReadView } from '../TrackedReadView'
+import { useTrackChanges } from '../useTrackChanges'
+import type { CommentThread, Suggestion, TrackActor, TrackChangesClient } from '../types'
+
+const ada: TrackActor = { sub: 'ada', label: 'ada@x.io', kind: 'person', kindSource: 'claim' }
+const bo: TrackActor = { sub: 'bo', label: 'bo@x.io', kind: 'person', kindSource: 'claim' }
+const ghost: TrackActor = { sub: 'g', label: 'g@x.io', kind: 'unknown' }
+
+const TEXT = 'Hello world. A second sentence. The end.'
+
+function sugg(id: string, quote: string, replacement: string, author: TrackActor = bo, extra: Partial<Suggestion> = {}): Suggestion {
+  const from = TEXT.indexOf(quote)
+  return { id, setId: 's', from, to: from + quote.length, quote, replacement, status: 'open', anchorState: 'mapped', author, createdAt: null, ...extra }
+}
+
+function insertAt(id: string, at: number, replacement: string): Suggestion {
+  return { id, setId: 's', from: at, to: at, quote: '', replacement, status: 'open', anchorState: 'mapped', author: bo, createdAt: null }
+}
+
+function thread(id: string, quote: string | null, body: string, extra: Partial<CommentThread> = {}): CommentThread {
+  const from = quote ? TEXT.indexOf(quote) : null
+  return {
+    id,
+    field: 'blog',
+    resolution: null,
+    from,
+    to: from == null ? null : from + quote!.length,
+    quote: quote ?? '',
+    anchorState: 'mapped',
+    resolved: false,
+    redacted: false,
+    comments: [{ id: `${id}-c1`, body, deleted: false, author: ada, createdAt: null, mentions: [], editedAt: null }],
+    ...extra,
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Final / Original                                                          */
+/* -------------------------------------------------------------------------- */
+
+describe('applyOpenSuggestions (the Final view)', () => {
+  it('applies every open, placed suggestion in document order', () => {
+    const r = applyOpenSuggestions(TEXT, [sugg('b', 'second', 'third'), sugg('a', 'Hello', 'Hi')])
+    expect(r.text).toBe('Hi world. A third sentence. The end.')
+    expect(r.applied).toEqual(['a', 'b'])
+    expect(r.skipped).toEqual([])
+  })
+
+  it('skips and names an overlapping one rather than merging by guesswork', () => {
+    const r = applyOpenSuggestions(TEXT, [sugg('a', 'Hello world', 'Hey'), sugg('b', 'world', 'earth')])
+    expect(r.text).toBe('Hey. A second sentence. The end.')
+    expect(r.skipped).toEqual(['b'])
+  })
+
+  it('leaves out orphaned, closed and quote-mismatched suggestions', () => {
+    const r = applyOpenSuggestions(TEXT, [
+      sugg('o', 'Hello', 'X', bo, { anchorState: 'orphaned' }),
+      sugg('c', 'world', 'Y', bo, { status: 'rejected' }),
+      { ...sugg('m', 'The end', 'Z'), quote: 'Not this' },
+    ])
+    expect(r.text).toBe(TEXT)
+    expect(r.applied).toEqual([])
+    expect(r.skipped).toEqual(['m'])
+  })
+
+  it('applies a pure insert', () => {
+    expect(applyOpenSuggestions(TEXT, [insertAt('i', 5, ',')]).text).toBe('Hello, world. A second sentence. The end.')
+  })
+})
+
+/* -------------------------------------------------------------------------- */
+/*  Read-view marks on hast                                                   */
+/* -------------------------------------------------------------------------- */
+
+function text(value: string, start: number, end: number) {
+  return { type: 'text' as const, value, position: { start: { offset: start }, end: { offset: end } } }
+}
+function el(tagName: string, children: unknown[]): HastElement {
+  return { type: 'element', tagName, properties: {}, children: children as HastElement['children'] }
+}
+function html(tree: HastRoot) {
+  const { container } = render(<div>{renderHast(tree)}</div>)
+  return container
+}
+
+describe('alignToSource', () => {
+  it('maps character for character when the text is its source slice', () => {
+    expect(alignToSource('ab', 'xxab', 2, 4)).toEqual([2, 3])
+  })
+  it('skips an escape backslash', () => {
+    expect(alignToSource('a_b', 'a\\_b', 0, 4)).toEqual([0, 2, 3])
+  })
+  it('aligns an entity that decodes to a character of its own spelling', () => {
+    expect(alignToSource('&', '&amp;', 0, 5)).toEqual([0])
+  })
+  it('refuses a node it cannot prove (an entity whose character is not in its source)', () => {
+    expect(alignToSource("'", '&#39;', 0, 5)).toBeNull()
+  })
+})
+
+describe('markTree', () => {
+  it('strikes a suggestion, draws its insert after it, and keeps the source offset on every run', () => {
+    const src = 'Hello world.'
+    const tree: HastRoot = { type: 'root', children: [el('p', [text(src, 0, src.length)])] }
+    const { placed } = markTree(tree, src, [{ id: 's1', kind: 'suggestion', from: 6, to: 11, title: 'Suggestion', insert: 'earth' }])
+    const c = html(tree)
+    expect(placed.has('s1')).toBe(true)
+    expect(c.querySelector('del')?.textContent).toBe('world')
+    expect(c.querySelector('del')?.getAttribute('data-tc-id')).toBe('s1')
+    expect(c.querySelector('ins')?.textContent).toBe('earth')
+    // The insert follows the struck text.
+    expect(c.textContent).toBe('Hello worldearth.')
+    const runs = Array.from(c.querySelectorAll('[data-src-from]')).map((n) => n.getAttribute('data-src-from'))
+    expect(runs).toEqual(['0', '6', '11'])
+  })
+
+  it('draws a range that crosses inline formatting in every text node it covers', () => {
+    // "a **bold** b": the text nodes are "a ", "bold", " b" at 0-2, 4-8, 10-12.
+    const src = 'a **bold** b'
+    const tree: HastRoot = {
+      type: 'root',
+      children: [el('p', [text('a ', 0, 2), el('strong', [text('bold', 4, 8)]), text(' b', 10, 12)])],
+    }
+    const { placed } = markTree(tree, src, [{ id: 'c1', kind: 'comment', from: 0, to: 12, title: 'Comment' }])
+    const c = html(tree)
+    expect(placed.has('c1')).toBe(true)
+    expect(Array.from(c.querySelectorAll('mark')).map((m) => m.textContent)).toEqual(['a ', 'bold', ' b'])
+  })
+
+  it('places marks correctly after an escape', () => {
+    const src = 'a \\_b c'
+    // rendered "a _b c"
+    const tree: HastRoot = { type: 'root', children: [el('p', [text('a _b c', 0, 7)])] }
+    markTree(tree, src, [{ id: 'c', kind: 'comment', from: 5, to: 7, title: 'x' }]) // " c" -> source 5..7
+    const c = html(tree)
+    expect(c.querySelector('mark')?.textContent).toBe(' c')
+  })
+
+  it('never draws inside code, and reports the mark unplaced', () => {
+    const src = 'see `code` here'
+    const tree: HastRoot = {
+      type: 'root',
+      children: [el('p', [text('see ', 0, 4), el('code', [text('code', 5, 9)]), text(' here', 10, 15)])],
+    }
+    const { placed } = markTree(tree, src, [{ id: 's', kind: 'suggestion', from: 5, to: 9, title: 'x', insert: 'y' }])
+    expect(placed.has('s')).toBe(false)
+    expect(html(tree).querySelector('del')).toBeNull()
+  })
+
+  it('leaves a node it cannot align untouched rather than painting a guess', () => {
+    const src = 'it&#39;s'
+    const tree: HastRoot = { type: 'root', children: [el('p', [text("it's", 0, 8)])] }
+    const { placed } = markTree(tree, src, [{ id: 'c', kind: 'comment', from: 0, to: 2, title: 'x' }])
+    expect(placed.size).toBe(0)
+    expect(html(tree).querySelector('mark')).toBeNull()
+  })
+
+  it('maps a DOM point back to its source offset', () => {
+    const tree = plainTree(TEXT)
+    markTree(tree, TEXT, [{ id: 'c', kind: 'comment', from: 6, to: 11, title: 'x' }])
+    const c = html(tree)
+    const mark = c.querySelector('mark')!
+    const node = mark.querySelector('[data-src-from]')!.firstChild!
+    expect(sourceOffsetOf(node, 2)).toBe(8)
+  })
+})
+
+/* -------------------------------------------------------------------------- */
+/*  TrackedReadView                                                           */
+/* -------------------------------------------------------------------------- */
+
+describe('TrackedReadView', () => {
+  it('draws suggestions, inserts and comments over plain text, and a click selects the mark', () => {
+    const onActivate = jest.fn()
+    render(
+      <TrackedReadView
+        source={TEXT}
+        language="plain"
+        suggestions={[sugg('s1', 'second', 'third')]}
+        threads={[thread('t1', 'The end', 'Too abrupt')]}
+        onActivate={onActivate}
+      />,
+    )
+    const view = screen.getByTestId('tracked-read-view')
+    expect(view.querySelector('del')?.textContent).toBe('second')
+    expect(view.querySelector('ins')?.textContent).toBe('third')
+    expect(view.querySelector('mark')?.textContent).toBe('The end')
+    fireEvent.click(view.querySelector('mark')!)
+    expect(onActivate).toHaveBeenCalledWith('t1')
+  })
+
+  it('hides changes when asked, and shows authorship only when asked', () => {
+    const blame = [{ id: 'blame:0', from: 0, to: TEXT.length, author: ada, unknownReason: null, reason: null, version: 1, at: null, via: 'edit' as const, acceptedBy: null, restoredFrom: null }]
+    const { rerender } = render(
+      <TrackedReadView source={TEXT} language="plain" suggestions={[sugg('s1', 'second', 'third')]} blame={blame} showChanges={false} />,
+    )
+    const view = screen.getByTestId('tracked-read-view')
+    expect(view.querySelector('del')).toBeNull()
+    expect(view.querySelector('.tc-read-blame')).toBeNull()
+    rerender(<TrackedReadView source={TEXT} language="plain" blame={blame} showAuthors />)
+    expect(view.querySelector('.tc-read-blame')?.getAttribute('title')).toMatch(/Written by ada@x\.io/)
+  })
+
+  it('reports a text selection as a source anchor', () => {
+    const onSel = jest.fn()
+    render(<TrackedReadView source={TEXT} language="plain" onSelectionChange={onSel} />)
+    const run = screen.getByTestId('tracked-read-view').querySelector('[data-src-from]')!.firstChild!
+    const range = document.createRange()
+    range.setStart(run, 6)
+    range.setEnd(run, 11)
+    const sel = window.getSelection()!
+    sel.removeAllRanges()
+    sel.addRange(range)
+    fireEvent.mouseUp(screen.getByTestId('tracked-read-view'))
+    expect(onSel).toHaveBeenLastCalledWith(expect.objectContaining({ from: 6, to: 11, quote: 'world' }))
+  })
+
+  it('goes through the markdown renderer with the same marks', () => {
+    render(<TrackedReadView source={TEXT} language="markdown" suggestions={[sugg('s1', 'second', 'third')]} />)
+    expect(screen.getByTestId('md').querySelector('del')?.textContent).toBe('second')
+  })
+})
+
+/* -------------------------------------------------------------------------- */
+/*  ChangesRail                                                               */
+/* -------------------------------------------------------------------------- */
+
+describe('ChangesRail', () => {
+  const base = {
+    fieldLabel: 'Blog',
+    currentActorSub: 'ada',
+    suggestions: [sugg('s2', 'The end', 'Fin'), sugg('s1', 'Hello', 'Hi')],
+    threads: [thread('t1', 'second', 'Why second?')],
+  }
+
+  it('lists open items in document order, each named in words with person/machine/unknown', () => {
+    render(<ChangesRail {...base} canAccept suggestions={[...base.suggestions, sugg('s3', 'world', 'earth', ghost)]} />)
+    const items = screen.getAllByRole('listitem').filter((li) => li.hasAttribute('data-rail-item'))
+    expect(items.map((i) => i.getAttribute('data-item-id'))).toEqual(['s1', 's3', 't1', 's2'])
+    expect(items[0]).toHaveAttribute('aria-label', expect.stringMatching(/Suggestion by bo@x\.io.*Written by a person/))
+    expect(items[1]).toHaveAttribute('aria-label', expect.stringMatching(/not recorded/))
+  })
+
+  it('offers accept and reject only to someone who may edit', () => {
+    const { rerender } = render(<ChangesRail {...base} canAccept={false} onAccept={jest.fn()} onReject={jest.fn()} onComment={jest.fn()} />)
+    expect(screen.queryByRole('button', { name: 'Accept' })).toBeNull()
+    expect(screen.queryByRole('button', { name: 'Reject' })).toBeNull()
+    // ...but a view-only reviewer still comments.
+    expect(screen.getByLabelText('New comment on Blog')).toBeInTheDocument()
+    rerender(<ChangesRail {...base} canAccept onAccept={jest.fn()} onReject={jest.fn()} />)
+    expect(screen.getAllByRole('button', { name: 'Accept' })).toHaveLength(2)
+  })
+
+  it('accepts by button and by the A key on a focused item, rejects by R', async () => {
+    const onAccept = jest.fn().mockResolvedValue(undefined)
+    const onReject = jest.fn().mockResolvedValue(undefined)
+    render(<ChangesRail {...base} canAccept onAccept={onAccept} onReject={onReject} />)
+    const first = screen.getAllByRole('listitem').find((li) => li.getAttribute('data-item-id') === 's1')!
+    fireEvent.click(within(first).getByRole('button', { name: 'Accept' }))
+    await waitFor(() => expect(onAccept).toHaveBeenCalledWith(['s1']))
+    const last = screen.getAllByRole('listitem').find((li) => li.getAttribute('data-item-id') === 's2')!
+    fireEvent.keyDown(last, { key: 'a' })
+    await waitFor(() => expect(onAccept).toHaveBeenLastCalledWith(['s2']))
+    fireEvent.keyDown(last, { key: 'r' })
+    await waitFor(() => expect(onReject).toHaveBeenCalledWith(['s2']))
+  })
+
+  it('moves between items with the arrow keys and shows the item in the text on Enter', () => {
+    const onFocusItem = jest.fn()
+    render(<ChangesRail {...base} canAccept onFocusItem={onFocusItem} />)
+    const items = screen.getAllByRole('listitem').filter((li) => li.hasAttribute('data-rail-item'))
+    items[0].focus()
+    fireEvent.keyDown(items[0], { key: 'ArrowDown' })
+    expect(document.activeElement).toBe(items[1])
+    fireEvent.keyDown(items[1], { key: 'Enter' })
+    expect(onFocusItem).toHaveBeenLastCalledWith('t1')
+  })
+
+  it('shows the server sentence when an accept fails, and keeps the item', async () => {
+    const onAccept = jest.fn().mockRejectedValue(new Error('Could not accept this suggestion: the text under this suggestion changed.'))
+    render(<ChangesRail {...base} canAccept onAccept={onAccept} />)
+    fireEvent.click(screen.getAllByRole('button', { name: 'Accept' })[0])
+    expect(await screen.findByRole('alert')).toHaveTextContent(/text under this suggestion changed/)
+  })
+
+  it('lets only the author withdraw', () => {
+    render(<ChangesRail {...base} suggestions={[sugg('mine', 'Hello', 'Hi', ada), sugg('theirs', 'world', 'earth', bo)]} canAccept={false} onWithdraw={jest.fn()} />)
+    expect(screen.getAllByRole('button', { name: 'Withdraw' })).toHaveLength(1)
+  })
+
+  it('replies, resolves, and lists resolved threads to reopen', async () => {
+    const onReply = jest.fn().mockResolvedValue(undefined)
+    const onResolve = jest.fn().mockResolvedValue(undefined)
+    const onReopen = jest.fn().mockResolvedValue(undefined)
+    render(
+      <ChangesRail
+        {...base}
+        threads={[thread('t1', 'second', 'Why?'), thread('t2', 'world', 'Done', { resolved: true, resolution: { action: 'resolved', by: bo, at: null } })]}
+        canAccept={false}
+        onReply={onReply}
+        onResolve={onResolve}
+        onReopen={onReopen}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Reply' }))
+    fireEvent.change(screen.getByLabelText('Reply'), { target: { value: 'Because.' } })
+    const replies = screen.getAllByRole('button', { name: 'Reply' })
+    fireEvent.click(replies[replies.length - 1])
+    await waitFor(() => expect(onReply).toHaveBeenCalledWith('t1', 'Because.', []))
+    fireEvent.click(screen.getByRole('button', { name: 'Resolve' }))
+    await waitFor(() => expect(onResolve).toHaveBeenCalledWith('t1'))
+    expect(screen.getByText('Resolved (1)')).toBeInTheDocument()
+    expect(screen.getByText('Resolved by bo@x.io')).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: 'Reopen' }))
+    await waitFor(() => expect(onReopen).toHaveBeenCalledWith('t2'))
+  })
+
+  it('lists orphaned items with their quote instead of dropping them', () => {
+    render(<ChangesRail {...base} suggestions={[sugg('o', 'Hello', 'Hi', bo, { anchorState: 'orphaned' })]} threads={[]} canAccept />)
+    expect(screen.getByText(/Orphaned \(1\)/)).toBeInTheDocument()
+    expect(screen.getByText(/replace “Hello” with “Hi”/)).toBeInTheDocument()
+  })
+
+  it('comments on the selection with an @mention picked from the roster, and says nobody is emailed', async () => {
+    const onComment = jest.fn().mockResolvedValue(undefined)
+    const selection = { from: 6, to: 11, quote: 'world', prefix: 'Hello ', suffix: '. A' }
+    render(
+      <ChangesRail {...base} canAccept={false} onComment={onComment} selection={selection} mentionable={[{ sub: 'rita', label: 'rita@x.io' }, bo]} />,
+    )
+    expect(screen.getByText(/nobody is emailed/)).toBeInTheDocument()
+    expect(within(screen.getByTestId('new-comment')).getByText('“world”')).toBeInTheDocument()
+    const box = screen.getByLabelText('New comment on Blog')
+    fireEvent.change(box, { target: { value: 'Ask @ri', selectionStart: 7 } })
+    const option = await screen.findByRole('option', { name: 'rita@x.io' })
+    fireEvent.mouseDown(option)
+    expect((box as HTMLTextAreaElement).value).toBe('Ask @rita@x.io ')
+    fireEvent.click(screen.getByRole('button', { name: 'Comment' }))
+    await waitFor(() => expect(onComment).toHaveBeenCalledWith('Ask @rita@x.io', ['rita'], selection))
+  })
+
+  it('keeps the typed comment when the write fails', async () => {
+    const onComment = jest.fn().mockRejectedValue(new Error('Could not add the comment: no.'))
+    render(<ChangesRail {...base} canAccept={false} onComment={onComment} />)
+    const box = screen.getByLabelText('New comment on Blog')
+    fireEvent.change(box, { target: { value: 'Keep me' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Comment' }))
+    expect(await screen.findByRole('alert')).toHaveTextContent('Could not add the comment')
+    expect((box as HTMLTextAreaElement).value).toBe('Keep me')
+  })
+
+  it('says why mentions are limited when the roster cannot be read', () => {
+    render(<ChangesRail {...base} canAccept={false} onComment={jest.fn()} mentionNotice="Your account cannot read the colleague list." />)
+    expect(screen.getByText('Your account cannot read the colleague list.')).toBeInTheDocument()
+  })
+})
+
+describe('mention helpers', () => {
+  it('finds the @query at the caret', () => {
+    expect(mentionQuery('hi @ri', 6)).toEqual({ start: 3, query: 'ri' })
+    expect(mentionQuery('mail a@b', 8)).toBeNull()
+  })
+  it('keeps only picked mentions still in the body', () => {
+    expect(mentionsIn('ping @rita@x.io', [{ sub: 'rita', label: 'rita@x.io' }, { sub: 'bo', label: 'bo@x.io' }])).toEqual(['rita'])
+  })
+})
+
+/* -------------------------------------------------------------------------- */
+/*  useTrackChanges: stale reads, writes, roster                              */
+/* -------------------------------------------------------------------------- */
+
+function page<T>(results: T[], version = 3) {
+  return { offset_unit: 'utf16' as const, version, results, next_cursor: null }
+}
+
+describe('useTrackChanges (rail half)', () => {
+  it('says so when a read describes another version, instead of rendering an empty list', async () => {
+    const client: TrackChangesClient = {
+      listSuggestions: jest.fn().mockResolvedValue(page([{ id: 'x', anchor: { from: 0, to: 5, quote: 'Hello' }, replacement: 'Hi', author: { sub: 'bo' } }], 4)),
+    }
+    const { result } = renderHook(() => useTrackChanges({ client, field: 'blog', value: TEXT, version: 3 }))
+    await waitFor(() => expect(result.current.stale).toBe(true))
+    expect(result.current.suggestions).toEqual([])
+    expect(result.current.notices[0]).toMatch(/Someone changed this record since you opened it/)
+  })
+
+  it('accepts at the version it is given, then re-reads', async () => {
+    const accept = jest.fn().mockResolvedValue({ id: 'd', version: 4, data: { blog: 'x' } })
+    const listSuggestions = jest.fn().mockResolvedValue(page([]))
+    const client: TrackChangesClient = { accept, listSuggestions }
+    const { result } = renderHook(() => useTrackChanges({ client, field: 'blog', value: TEXT, version: 3 }))
+    await waitFor(() => expect(listSuggestions).toHaveBeenCalledTimes(1))
+    let out: unknown
+    await act(async () => {
+      out = await result.current.actions.accept!(['s1'], 3)
+    })
+    expect(accept).toHaveBeenCalledWith({ ids: ['s1'], expectedVersion: 3 })
+    expect(out).toEqual({ id: 'd', version: 4, data: { blog: 'x' } })
+    await waitFor(() => expect(listSuggestions).toHaveBeenCalledTimes(2))
+  })
+
+  it('turns a refusal into the server reason in words', async () => {
+    const client: TrackChangesClient = {
+      accept: jest.fn().mockRejectedValue(new TrackChangesHttpError(409, { detail: 'x', reason: 'conflicted' })),
+    }
+    const { result } = renderHook(() => useTrackChanges({ client, field: 'blog', value: TEXT, version: 3 }))
+    await expect(result.current.actions.accept!(['s1'], 3)).rejects.toThrow(/the text under this suggestion changed/)
+    await expect(
+      renderHook(() =>
+        useTrackChanges({ client: { accept: jest.fn().mockRejectedValue(new TrackChangesHttpError(412, {})) }, field: 'blog', value: TEXT, version: 3 }),
+      ).result.current.actions.accept!(['s1'], 3),
+    ).rejects.toThrow(/someone changed this record/)
+  })
+
+  it('offers the roster plus everyone on the trail, deduped by sub, and never a machine', async () => {
+    const roster = jest
+      .fn()
+      .mockResolvedValueOnce({ results: [{ sub: 'rita', label: 'rita@x.io' }, { sub: 'bo', label: 'bo@x.io' }], next_cursor: 'p2' })
+      .mockResolvedValueOnce({ results: [{ sub: 'rita', label: 'rita@x.io' }], next_cursor: null })
+    const client: TrackChangesClient = {
+      roster,
+      listSuggestions: jest.fn().mockResolvedValue(
+        page([
+          { id: 'a', anchor: { from: 0, to: 5, quote: 'Hello' }, replacement: 'Hi', author: { sub: 'zed', label: 'zed@x.io', kind: 'person' } },
+          { id: 'b', anchor: { from: 6, to: 11, quote: 'world' }, replacement: 'w', author: { sub: 'svc:n8n', label: 'bot', kind: 'machine' } },
+        ]),
+      ),
+    }
+    const { result } = renderHook(() => useTrackChanges({ client, field: 'blog', value: TEXT, version: 3 }))
+    await waitFor(() => expect(result.current.mentionable.map((m) => m.sub)).toEqual(['bo', 'rita', 'zed']))
+    expect(roster).toHaveBeenCalledTimes(2)
+    expect(result.current.rosterNotice).toBeNull()
+  })
+
+  it('says why when the roster is refused (a viewer-role token gets central 403)', async () => {
+    const client: TrackChangesClient = { roster: jest.fn().mockRejectedValue(new TrackChangesHttpError(403, { detail: 'no' })) }
+    const { result } = renderHook(() => useTrackChanges({ client, field: 'blog', value: TEXT, version: 3 }))
+    await waitFor(() => expect(result.current.rosterNotice).toMatch(/cannot read the colleague list/))
+  })
+
+  it('asks for every thread, resolved included, so the rail can list them', async () => {
+    const listComments = jest.fn().mockResolvedValue(page([]))
+    renderHook(() => useTrackChanges({ client: { listComments }, field: 'blog', value: TEXT, version: 3 }))
+    await waitFor(() => expect(listComments).toHaveBeenCalledWith({ field: 'blog', status: 'all' }))
+  })
+})
+
+/* -------------------------------------------------------------------------- */
+/*  The HTTP client                                                           */
+/* -------------------------------------------------------------------------- */
+
+describe('createHttpTrackChangesClient', () => {
+  function fake(status = 200, body: unknown = {}) {
+    return jest.fn().mockResolvedValue({ ok: status < 400, status, json: async () => body })
+  }
+
+  it('accepts with ONE precondition spelling, in the body', async () => {
+    const f = fake(200, { version: 5 })
+    const c = createHttpTrackChangesClient('d1', { headers: () => ({ authorization: 'Bearer t' }), url: (p) => p, fetch: f })
+    await c.accept!({ ids: ['s1'], expectedVersion: 4 })
+    const [url, init] = f.mock.calls[0]
+    expect(url).toBe('/api/v1/entities/d1/suggestions/accept')
+    expect(JSON.parse(init.body)).toEqual({ ids: ['s1'], expected_version: 4 })
+    expect(init.headers).not.toHaveProperty('If-Match')
+    expect(init.headers.authorization).toBe('Bearer t')
+  })
+
+  it('reads with query strings and a trailing slash by default', async () => {
+    const f = fake(200, {})
+    const c = createHttpTrackChangesClient('d1', { headers: async () => ({}), fetch: f })
+    await c.listComments!({ field: 'blog', status: 'all' })
+    await c.roster!({})
+    expect(f.mock.calls[0][0]).toBe('/api/v1/entities/d1/comments/?field=blog&status=all')
+    expect(f.mock.calls[1][0]).toBe('/api/v1/org/roster/')
+  })
+
+  it('throws the status and body on a refusal', async () => {
+    const c = createHttpTrackChangesClient('d1', { headers: () => ({}), fetch: fake(409, { detail: 'nope', reason: 'conflicted' }) })
+    await expect(c.reject!({ ids: ['x'] })).rejects.toMatchObject({ status: 409, body: { reason: 'conflicted' } })
+  })
+})
+
+/* -------------------------------------------------------------------------- */
+/*  TrackedField                                                              */
+/* -------------------------------------------------------------------------- */
+
+describe('TrackedField', () => {
+  const wire = {
+    id: 's1',
+    set_id: 'set',
+    field: 'blog',
+    status: 'open',
+    anchor: { from: 13, to: 14, quote: 'A' },
+    position: { state: 'mapped', from: 13, to: 14, version: 3 },
+    replacement: 'One',
+    author: { sub: 'vee', label: 'vee@x.io', kind: 'person' },
+  }
+  function client(extra: Partial<TrackChangesClient> = {}): TrackChangesClient {
+    return {
+      listSuggestions: jest.fn().mockResolvedValue(page([wire])),
+      listComments: jest.fn().mockResolvedValue(page([])),
+      accept: jest.fn().mockResolvedValue({ version: 4 }),
+      comment: jest.fn().mockResolvedValue({}),
+      ...extra,
+    }
+  }
+
+  it('shows Final with the open suggestions applied, and Original as stored', async () => {
+    render(<TrackedField client={client()} field="blog" label="Blog" language="plain" value={TEXT} version={3} currentActorSub="ada" defaultSurface="read" />)
+    await screen.findByRole('button', { name: 'Accept' })
+    fireEvent.click(screen.getByRole('button', { name: 'Final' }))
+    expect(screen.getByTestId('tracked-read-view')).toHaveTextContent('Hello world. One second sentence. The end.')
+    expect(screen.getByText(/as it would read with 1 open suggestion accepted/i)).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: 'Original' }))
+    expect(screen.getByTestId('tracked-read-view')).toHaveTextContent(TEXT)
+    expect(screen.getByTestId('tracked-read-view').querySelector('del')).toBeNull()
+  })
+
+  it('hands the accept to the host so it asserts its own live version', async () => {
+    const c = client()
+    const runAccept = jest.fn(async (doAccept: (v: number) => Promise<unknown>) => doAccept(9))
+    render(<TrackedField client={c} field="blog" label="Blog" language="plain" value={TEXT} version={3} currentActorSub="ada" defaultSurface="read" runAccept={runAccept} />)
+    fireEvent.click(await screen.findByRole('button', { name: 'Accept' }))
+    await waitFor(() => expect(c.accept).toHaveBeenCalledWith({ ids: ['s1'], expectedVersion: 9 }))
+  })
+
+  it('gives a view-only reviewer no accept, but a Suggest surface and comments', async () => {
+    render(<TrackedField client={client()} field="blog" label="Blog" language="plain" value={TEXT} version={3} currentActorSub="vee" canEdit={false} defaultSurface="read" />)
+    await screen.findByTestId('rail-suggestion')
+    expect(screen.queryByRole('button', { name: 'Accept' })).toBeNull()
+    expect(screen.getByRole('button', { name: 'Suggest' })).toBeInTheDocument()
+    expect(screen.getByLabelText('New comment on Blog')).toBeInTheDocument()
+  })
+
+  it('a selection made in the source editor becomes the comment anchor', async () => {
+    const rect = { x: 0, y: 0, top: 0, left: 0, right: 0, bottom: 0, width: 0, height: 0, toJSON() {} }
+    Range.prototype.getBoundingClientRect = () => rect as DOMRect
+    Range.prototype.getClientRects = () => ({ length: 0, item: () => null, [Symbol.iterator]: [][Symbol.iterator] }) as unknown as DOMRectList
+    const c = client()
+    render(<TrackedField client={c} field="blog" label="Blog" language="plain" value={TEXT} version={3} currentActorSub="ada" defaultSurface="source" />)
+    await screen.findByTestId('rail-suggestion')
+    const { EditorView } = jest.requireActual('@codemirror/view')
+    const view = EditorView.findFromDOM(document.querySelector('.cm-editor') as HTMLElement)!
+    act(() => {
+      view.dispatch({ selection: { anchor: 6, head: 11 } })
+    })
+    expect(within(screen.getByTestId('new-comment')).getByText('“world”')).toBeInTheDocument()
+    fireEvent.change(screen.getByLabelText('New comment on Blog'), { target: { value: 'Hm' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Comment' }))
+    await waitFor(() => expect(c.comment).toHaveBeenCalledWith({ body: 'Hm', field: 'blog', from: 6, to: 11, base_version: 3 }))
+  })
+
+  it('comments on a span at the loaded version', async () => {
+    const c = client()
+    render(<TrackedField client={c} field="blog" label="Blog" language="plain" value={TEXT} version={3} currentActorSub="ada" defaultSurface="read" />)
+    await screen.findByTestId('rail-suggestion')
+    const run = screen.getByTestId('tracked-read-view').querySelector('[data-src-from="0"]')!.firstChild!
+    const range = document.createRange()
+    range.setStart(run, 0)
+    range.setEnd(run, 5)
+    window.getSelection()!.removeAllRanges()
+    window.getSelection()!.addRange(range)
+    fireEvent.mouseUp(screen.getByTestId('tracked-read-view'))
+    fireEvent.change(screen.getByLabelText('New comment on Blog'), { target: { value: 'Warmer?' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Comment' }))
+    await waitFor(() =>
+      expect(c.comment).toHaveBeenCalledWith({ body: 'Warmer?', field: 'blog', from: 0, to: 5, base_version: 3 }),
+    )
+  })
+})

package/src/components/track-changes/final-text.ts

@@ -0,0 +1,54 @@
+/**
+ * The FINAL and ORIGINAL views (bd startsim-whwxd.3; design startsim-xyn25
+ * section d).
+ *
+ * Read literally, the design's two views are the same text: the stored string
+ * never has a suggestion applied, so "the current text" and "the base with no
+ * suggestion applied" are one string. They follow Word's meaning instead:
+ *
+ *   ORIGINAL  the stored text, with no marks.
+ *   FINAL     the stored text with every OPEN, PLACED suggestion applied,
+ *             with no marks: what the record would read if all were accepted.
+ *
+ * Two suggestions that overlap cannot both be applied, so the later one (in
+ * document order) is skipped and NAMED, never merged by guesswork. The server
+ * is the one that applies a real accept; this is a preview only.
+ */
+import type { Suggestion } from './types';
+
+export interface FinalText {
+  text: string;
+  /** Applied, in document order. */
+  applied: string[];
+  /** Open and placed, but overlapping one already applied. */
+  skipped: string[];
+}
+
+export function placedOpen(suggestions: Suggestion[]): Suggestion[] {
+  return suggestions
+    .filter((s) => s.status === 'open' && s.anchorState !== 'orphaned')
+    .slice()
+    .sort((a, b) => a.from - b.from || a.to - b.to);
+}
+
+export function applyOpenSuggestions(text: string, suggestions: Suggestion[]): FinalText {
+  const applied: string[] = [];
+  const skipped: string[] = [];
+  let out = '';
+  let last = 0;
+  let lastInsertAt = -1;
+  for (const s of placedOpen(suggestions)) {
+    const overlaps = s.from < last || (s.from === s.to && s.from === lastInsertAt);
+    // The quote must still be what the text holds there; normalize already
+    // orphans a mismatch, so this is the belt to its braces.
+    if (overlaps || s.to > text.length || text.slice(s.from, s.to) !== s.quote) {
+      skipped.push(s.id);
+      continue;
+    }
+    out += text.slice(last, s.from) + s.replacement;
+    last = s.to;
+    lastInsertAt = s.from === s.to ? s.from : -1;
+    applied.push(s.id);
+  }
+  return { text: out + text.slice(last), applied, skipped };
+}