@startsimpli/ui 0.4.142 → 0.4.143

package/src/components/track-changes/__tests__/tracked-text-editor.test.tsx

@@ -0,0 +1,476 @@
+/**
+ * The mounted editor (bd startsim-sjuai).
+ *
+ * What must hold: editing mode reports the whole string to the host;
+ * suggesting mode NEVER does (nothing may PATCH the field) and instead posts
+ * the whole proposed text against the base version on a pause, on blur and on
+ * leaving the mode; a view-only reviewer can suggest but not edit; marks are
+ * reachable by keyboard and announced in words; and the transport is the
+ * injected client, called by the hook, never fetched by the component.
+ */
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { createRef } from 'react'
+import { EditorSelection } from '@codemirror/state'
+
+import { TrackedTextEditor, type TrackedTextEditorHandle } from '../TrackedTextEditor'
+import { useTrackChanges } from '../useTrackChanges'
+import type { BlameSpan, Suggestion, TrackActor, TrackChangesClient } from '../types'
+
+beforeAll(() => {
+  // jsdom has no layout; CodeMirror measures text with these.
+  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 bo: TrackActor = { sub: 'bo', label: 'bo@x.io', kind: 'person', kindSource: 'claim' }
+const bot: TrackActor = { sub: 'svc', label: 'svc:n8n', kind: 'machine', kindSource: 'claim' }
+
+const VALUE = 'Hello world. A second sentence.'
+
+function sugg(id: string, quote: string, replacement: string, author = bo): Suggestion {
+  const from = VALUE.indexOf(quote)
+  return { id, setId: 'set', from, to: from + quote.length, quote, replacement, status: 'open', anchorState: 'mapped', author, createdAt: null }
+}
+
+function typeAt(handle: TrackedTextEditorHandle, at: number, insert: string, to = at) {
+  act(() => {
+    handle.view!.dispatch({ changes: { from: at, to, insert }, userEvent: 'input.type' })
+  })
+}
+
+describe('editing mode', () => {
+  it('reports every edit as the whole stored string and never proposes', () => {
+    const onChange = jest.fn()
+    const onPropose = jest.fn()
+    const ref = createRef<TrackedTextEditorHandle>()
+    render(<TrackedTextEditor ref={ref} label="Blog" value={VALUE} version={3} currentActorSub="ada" onChange={onChange} onPropose={onPropose} />)
+    typeAt(ref.current!, VALUE.length, ' More.')
+    expect(onChange).toHaveBeenLastCalledWith(VALUE + ' More.')
+    expect(onPropose).not.toHaveBeenCalled()
+  })
+
+  it('does not echo a host value change back as an edit', () => {
+    const onChange = jest.fn()
+    const { rerender } = render(<TrackedTextEditor label="Blog" value={VALUE} version={3} currentActorSub="ada" onChange={onChange} />)
+    rerender(<TrackedTextEditor label="Blog" value={'Intro. ' + VALUE} version={4} currentActorSub="ada" onChange={onChange} />)
+    expect(onChange).not.toHaveBeenCalled()
+  })
+})
+
+describe('suggesting mode', () => {
+  beforeEach(() => jest.useFakeTimers())
+  afterEach(() => jest.useRealTimers())
+
+  function mountSuggesting(extra: Partial<React.ComponentProps<typeof TrackedTextEditor>> = {}) {
+    const onChange = jest.fn()
+    const onPropose = jest.fn().mockResolvedValue(undefined)
+    const ref = createRef<TrackedTextEditorHandle>()
+    const utils = render(
+      <TrackedTextEditor
+        ref={ref}
+        label="Blog"
+        value={VALUE}
+        version={7}
+        currentActorSub="ada"
+        defaultMode="suggesting"
+        onChange={onChange}
+        onPropose={onPropose}
+        {...extra}
+      />,
+    )
+    return { ...utils, ref, onChange, onPropose }
+  }
+
+  it('never reports an edit to the host, and posts the whole proposed text after a 5 s pause', async () => {
+    const { ref, onChange, onPropose } = mountSuggesting()
+    typeAt(ref.current!, 6, 'big ')
+    act(() => jest.advanceTimersByTime(4900))
+    expect(onPropose).not.toHaveBeenCalled()
+    typeAt(ref.current!, 0, '>> ')
+    act(() => jest.advanceTimersByTime(4900))
+    expect(onPropose).not.toHaveBeenCalled() // the pause restarts on each keystroke
+    await act(async () => {
+      jest.advanceTimersByTime(200)
+    })
+    expect(onPropose).toHaveBeenCalledTimes(1)
+    expect(onPropose).toHaveBeenCalledWith('>> Hello big world. A second sentence.', 7)
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('posts on blur, and not again when nothing changed', async () => {
+    const { ref, onPropose } = mountSuggesting()
+    typeAt(ref.current!, 0, 'X')
+    await act(async () => {
+      await ref.current!.flush()
+    })
+    await act(async () => {
+      await ref.current!.flush()
+    })
+    expect(onPropose).toHaveBeenCalledTimes(1)
+    typeAt(ref.current!, 0, 'Y')
+    await act(async () => {
+      fireEvent.blur(ref.current!.view!.contentDOM) // the blur alone posts
+    })
+    expect(onPropose).toHaveBeenCalledTimes(2)
+    expect(onPropose).toHaveBeenLastCalledWith('YX' + VALUE, 7)
+  })
+
+  it('does not post when the proposal equals the base text', async () => {
+    const { ref, onPropose } = mountSuggesting()
+    typeAt(ref.current!, 0, 'X')
+    typeAt(ref.current!, 0, '', 1)
+    await act(async () => {
+      jest.advanceTimersByTime(6000)
+      await ref.current!.flush()
+    })
+    expect(onPropose).not.toHaveBeenCalled()
+  })
+
+  it('posts the pending proposal when switching back to editing, then shows the stored text', async () => {
+    const onModeChange = jest.fn()
+    const { ref, onPropose, onChange } = mountSuggesting({ onModeChange })
+    typeAt(ref.current!, 0, 'X')
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: 'Editing' }))
+    })
+    expect(onPropose).toHaveBeenCalledWith('X' + VALUE, 7)
+    expect(onModeChange).toHaveBeenCalledWith('editing')
+    expect(ref.current!.view!.state.doc.toString()).toBe(VALUE)
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('keeps the proposal and says so when the post fails', async () => {
+    const onPropose = jest.fn().mockRejectedValue(new Error('network down'))
+    const { ref } = mountSuggesting({ onPropose })
+    typeAt(ref.current!, 0, 'X')
+    await act(async () => {
+      await ref.current!.flush()
+    })
+    expect(ref.current!.proposedText()).toBe('X' + VALUE)
+    expect(screen.getByText(/not sent/i)).toBeInTheDocument()
+    // and retries next time
+    onPropose.mockResolvedValue(undefined)
+    await act(async () => {
+      await ref.current!.flush()
+    })
+    expect(onPropose).toHaveBeenCalledTimes(2)
+  })
+
+  it('shows local inserts and deletions as ins/del marks', () => {
+    const { ref, container } = mountSuggesting()
+    typeAt(ref.current!, 0, 'New ')
+    const at = 'New '.length + VALUE.indexOf('second ')
+    typeAt(ref.current!, at, '', at + 'second '.length)
+    expect(container.querySelector('ins.cm-tc-local-ins')?.textContent).toBe('New ')
+    expect(container.querySelector('del.cm-tc-local-del')?.textContent).toBe('second ')
+  })
+})
+
+describe('who may do what', () => {
+  it('a reviewer who cannot edit is in suggesting mode and cannot switch to editing', () => {
+    const onChange = jest.fn()
+    const ref = createRef<TrackedTextEditorHandle>()
+    render(<TrackedTextEditor ref={ref} label="Blog" value={VALUE} version={1} currentActorSub="v" canEdit={false} onChange={onChange} onPropose={jest.fn()} />)
+    expect(screen.getByRole('button', { name: 'Editing' })).toBeDisabled()
+    expect(screen.getByRole('button', { name: 'Suggesting' })).toHaveAttribute('aria-pressed', 'true')
+    typeAt(ref.current!, 0, 'X')
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('cannot start suggesting while there are unsaved edits', () => {
+    const ref = createRef<TrackedTextEditorHandle>()
+    render(<TrackedTextEditor ref={ref} label="Blog" value={VALUE} version={1} currentActorSub="a" onChange={jest.fn()} onPropose={jest.fn()} />)
+    typeAt(ref.current!, 0, 'X')
+    expect(screen.getByRole('button', { name: 'Suggesting' })).toBeDisabled()
+  })
+
+  it('cannot suggest on a record with no version', () => {
+    render(<TrackedTextEditor label="Blog" value={VALUE} version={null} currentActorSub="a" onChange={jest.fn()} onPropose={jest.fn()} />)
+    expect(screen.getByRole('button', { name: 'Suggesting' })).toBeDisabled()
+  })
+})
+
+describe('accessibility', () => {
+  const blame: BlameSpan[] = [
+    { id: 'blame:0', from: 0, to: 12, author: bot, unknownReason: null, reason: null, version: 2, at: null, via: 'edit', acceptedBy: null, restoredFrom: null },
+    { id: 'blame:12', from: 12, to: VALUE.length, author: null, unknownReason: 'before history began 2026-10-06', reason: 'before_history', version: null, at: null, via: 'unknown', acceptedBy: null, restoredFrom: null },
+  ]
+
+  it('labels the text area and tells a keyboard user how to reach the marks', () => {
+    render(<TrackedTextEditor label="Blog (markdown)" value={VALUE} version={1} currentActorSub="a" />)
+    const box = screen.getByRole('textbox', { name: 'Blog (markdown)' })
+    expect(box).toHaveAttribute('aria-multiline', 'true')
+    const help = document.getElementById(box.getAttribute('aria-describedby')!)
+    expect(help?.textContent).toMatch(/F8/)
+  })
+
+  it('F8 moves to the next suggestion and announces it in words', () => {
+    const ref = createRef<TrackedTextEditorHandle>()
+    const onActiveChange = jest.fn()
+    render(
+      <TrackedTextEditor
+        ref={ref}
+        label="Blog"
+        value={VALUE}
+        version={1}
+        currentActorSub="a"
+        suggestions={[sugg('s1', 'world', 'planet'), sugg('s2', 'second', '2nd')]}
+        onActiveChange={onActiveChange}
+      />,
+    )
+    act(() => {
+      fireEvent.keyDown(ref.current!.view!.contentDOM, { key: 'F8', code: 'F8', keyCode: 119 })
+    })
+    expect(screen.getByRole('status')).toHaveTextContent('Suggestion by bo@x.io: replace “world” with “planet”')
+    expect(onActiveChange).toHaveBeenLastCalledWith(expect.objectContaining({ id: 's1' }))
+    act(() => {
+      fireEvent.keyDown(ref.current!.view!.contentDOM, { key: 'F8', code: 'F8', keyCode: 119 })
+    })
+    expect(screen.getByRole('status')).toHaveTextContent('replace “second” with “2nd”')
+    const s = ref.current!.view!.state
+    expect(s.sliceDoc(s.selection.main.from, s.selection.main.to)).toBe('second')
+  })
+
+  it('names a machine author and an unknown span’s reason, on the mark and when reached', () => {
+    const ref = createRef<TrackedTextEditorHandle>()
+    const { container } = render(
+      <TrackedTextEditor ref={ref} label="Blog" value={VALUE} version={1} currentActorSub="a" blame={blame} defaultShowAuthors />,
+    )
+    const machine = container.querySelector('[data-tc-kind="blame"][data-actor-kind="machine"]')!
+    expect(machine.getAttribute('title')).toMatch(/svc:n8n \(machine\)/)
+    const unknown = container.querySelector('[data-tc-kind="blame"][data-actor-kind="unknown"]')!
+    expect(unknown.getAttribute('title')).toBe('Author unknown: before history began 2026-10-06')
+    act(() => {
+      ref.current!.view!.dispatch({ selection: EditorSelection.cursor(20) })
+    })
+    expect(screen.getByRole('status')).toHaveTextContent('Author unknown: before history began 2026-10-06')
+  })
+
+  it('draws suggestion marks as del/ins elements with the description as title', () => {
+    const { container } = render(
+      <TrackedTextEditor label="Blog" value={VALUE} version={1} currentActorSub="a" suggestions={[sugg('s1', 'world', 'planet')]} />,
+    )
+    const del = container.querySelector('del.cm-tc-sugg-del')!
+    expect(del.textContent).toBe('world')
+    expect(container.querySelector('ins.cm-tc-sugg-ins')?.textContent).toBe('planet')
+    expect(del.getAttribute('title')).toBe('Suggestion by bo@x.io: replace “world” with “planet”')
+  })
+
+  it('the authors toggle is a pressed/unpressed button and hides blame by default', () => {
+    const { container } = render(<TrackedTextEditor label="Blog" value={VALUE} version={1} currentActorSub="a" blame={blame} />)
+    expect(container.querySelector('[data-tc-kind="blame"]')).toBeNull()
+    const toggle = screen.getByRole('button', { name: 'Show authors' })
+    expect(toggle).toHaveAttribute('aria-pressed', 'false')
+    fireEvent.click(toggle)
+    expect(toggle).toHaveAttribute('aria-pressed', 'true')
+    expect(container.querySelector('[data-tc-kind="blame"]')).not.toBeNull()
+  })
+
+  it('sizes its toolbar on its own container, not the viewport', () => {
+    const { container } = render(<TrackedTextEditor label="Blog" value={VALUE} version={1} currentActorSub="a" />)
+    const root = container.querySelector('[data-testid="tracked-text-editor"]')!
+    expect(root.className).toMatch(/@container/)
+    // a viewport breakpoint would be a bare `sm:`/`md:`; container variants are `@md:`
+    expect(container.innerHTML).not.toMatch(/[\s"](sm|md|lg|xl):/)
+  })
+})
+
+describe('selection anchors for comments', () => {
+  it('returns the selection in stored-string coordinates with context', () => {
+    const ref = createRef<TrackedTextEditorHandle>()
+    render(<TrackedTextEditor ref={ref} label="Blog" value={VALUE} version={1} currentActorSub="a" onChange={jest.fn()} />)
+    // Unsaved typing before the selection must not shift the anchor.
+    typeAt(ref.current!, 0, 'Typed. ')
+    const at = 'Typed. '.length + VALUE.indexOf('second')
+    act(() => {
+      ref.current!.view!.dispatch({ selection: EditorSelection.range(at, at + 6) })
+    })
+    expect(ref.current!.selectionAnchor()).toEqual({
+      from: VALUE.indexOf('second'),
+      to: VALUE.indexOf('second') + 6,
+      quote: 'second',
+      prefix: 'Hello world. A ',
+      suffix: ' sentence.',
+    })
+  })
+})
+
+describe('useTrackChanges with an injected client', () => {
+  function Host({ client, value, version }: { client: TrackChangesClient; value: string; version: number }) {
+    const tc = useTrackChanges({ client, field: 'blog', value, version })
+    return (
+      <>
+        <TrackedTextEditor
+          label="Blog"
+          value={value}
+          version={version}
+          currentActorSub="ada"
+          blame={tc.blame}
+          suggestions={tc.suggestions}
+          threads={tc.threads}
+          notices={tc.notices}
+          onPropose={tc.propose}
+          defaultShowAuthors
+        />
+        <output data-testid="count">{tc.suggestions.length}</output>
+      </>
+    )
+  }
+
+  it('reads through the client, converts emoji offsets, and paints on the right words', async () => {
+    const value = '🚀 Launch day. Big news.'
+    const cp = (s: string) => Array.from(value.slice(0, value.indexOf(s))).length
+    const client: TrackChangesClient = {
+      blame: jest.fn().mockResolvedValue({ version: 2, spans: [{ from: 0, to: cp(' Big'), actor_label: 'ada@x', actor_kind: 'person' }] }),
+      listSuggestions: jest.fn().mockResolvedValue({ version: 2, results: [{ id: 's1', anchor: { from: cp('Big'), to: cp('Big') + 3, quote: 'Big' }, replacement: 'Huge', actor_label: 'bo@x' }] }),
+      listComments: jest.fn().mockResolvedValue([]),
+    }
+    const { container } = render(<Host client={client} value={value} version={2} />)
+    await waitFor(() => expect(container.querySelector('del.cm-tc-sugg-del')?.textContent).toBe('Big'))
+    expect(client.blame).toHaveBeenCalledWith({ field: 'blog' })
+    expect(container.querySelector('[data-tc-kind="blame"]')?.textContent).toBe('🚀 Launch day.')
+  })
+
+  it('says so when a read is refused, instead of showing nothing', async () => {
+    const client: TrackChangesClient = {
+      blame: jest.fn().mockRejectedValue(Object.assign(new Error('nope'), { status: 404 })),
+      listSuggestions: jest.fn().mockResolvedValue([]),
+    }
+    render(<Host client={client} value={VALUE} version={1} />)
+    expect(await screen.findByText('You cannot see who wrote each passage for this field.')).toBeInTheDocument()
+  })
+
+  it('does not paint a response for a different version', async () => {
+    const client: TrackChangesClient = {
+      listSuggestions: jest.fn().mockResolvedValue({ version: 9, results: [{ id: 's1', anchor: { from: 0, to: 5, quote: 'Hello' }, replacement: 'Hi' }] }),
+    }
+    render(<Host client={client} value={VALUE} version={1} />)
+    await waitFor(() => expect(client.listSuggestions).toHaveBeenCalled())
+    await act(async () => {})
+    expect(screen.getByTestId('count')).toHaveTextContent('0')
+  })
+
+  it('posts a proposal with field and base version, then re-reads the suggestions', async () => {
+    jest.useFakeTimers()
+    const client: TrackChangesClient = {
+      listSuggestions: jest.fn().mockResolvedValue([]),
+      propose: jest.fn().mockResolvedValue({}),
+    }
+    const ref = createRef<TrackedTextEditorHandle>()
+    function H() {
+      const tc = useTrackChanges({ client, field: 'linkedin', value: VALUE, version: 5 })
+      return (
+        <TrackedTextEditor ref={ref} label="LinkedIn" language="plain" value={VALUE} version={5} currentActorSub="ada" defaultMode="suggesting" suggestions={tc.suggestions} onPropose={tc.propose} />
+      )
+    }
+    render(<H />)
+    typeAt(ref.current!, 0, 'Hi. ')
+    await act(async () => {
+      await ref.current!.flush()
+    })
+    expect(client.propose).toHaveBeenCalledWith({ field: 'linkedin', base_version: 5, proposed: 'Hi. ' + VALUE })
+    await act(async () => {})
+    expect(client.listSuggestions).toHaveBeenCalledTimes(2)
+    jest.useRealTimers()
+  })
+})
+
+describe('late-arriving own suggestions', () => {
+  it('loads the reviewer’s own open suggestions into the proposal when they arrive after suggesting started', () => {
+    const ref = createRef<TrackedTextEditorHandle>()
+    const ada: TrackActor = { sub: 'ada', label: 'ada@x.io', kind: 'person', kindSource: 'claim' }
+    const props = { label: 'Blog', value: VALUE, version: 4, currentActorSub: 'ada', defaultMode: 'suggesting' as const, onPropose: jest.fn() }
+    const { rerender } = render(<TrackedTextEditor ref={ref} {...props} suggestions={[]} />)
+    expect(ref.current!.proposedText()).toBe(VALUE)
+    rerender(<TrackedTextEditor ref={ref} {...props} suggestions={[sugg('m1', 'world', 'planet', ada)]} />)
+    expect(ref.current!.proposedText()).toBe('Hello planet. A second sentence.')
+    expect(props.onPropose).not.toHaveBeenCalled()
+  })
+})
+
+describe('the stored string round-trips through the mounted editor', () => {
+  it('hands back CRLF, tabs and emoji byte for byte', () => {
+    const value = '# Title\r\n\r\n\tIndented 🚀 中文\r\n'
+    const onChange = jest.fn()
+    const ref = createRef<TrackedTextEditorHandle>()
+    render(<TrackedTextEditor ref={ref} label="Blog" value={value} version={1} currentActorSub="a" onChange={onChange} />)
+    typeAt(ref.current!, value.length, 'x')
+    typeAt(ref.current!, value.length, '', value.length + 1)
+    expect(onChange).toHaveBeenLastCalledWith(value)
+  })
+})
+
+describe('switching into suggesting mode', () => {
+  it('does not post the unchanged text when the switch is clicked from a focused editor', async () => {
+    const onPropose = jest.fn().mockResolvedValue(undefined)
+    const ref = createRef<TrackedTextEditorHandle>()
+    render(<TrackedTextEditor ref={ref} label="Blog" value={VALUE} version={2} currentActorSub="ada" onChange={jest.fn()} onPropose={onPropose} />)
+    act(() => ref.current!.view!.focus())
+    const button = screen.getByRole('button', { name: 'Suggesting' })
+    await act(async () => {
+      button.focus() // the editor blurs, as a real click does
+      fireEvent.click(button)
+      await new Promise((r) => setTimeout(r, 50))
+    })
+    expect(ref.current!.view!.state.doc.toString()).toBe(VALUE)
+    await act(async () => {
+      await ref.current!.flush()
+    })
+    expect(onPropose).not.toHaveBeenCalled()
+  })
+})
+
+describe('every page is read, because a proposal supersedes ALL of the author’s open suggestions', () => {
+  it('follows next_cursor to the end for suggestions and comments', async () => {
+    const listSuggestions = jest.fn(async (q: { field: string; cursor?: string }) =>
+      q.cursor
+        ? { next_cursor: null, results: [{ id: 's2', anchor: { from: 13, to: 14, quote: 'A' }, position: { from: 13, to: 14, state: 'mapped' }, replacement: 'One', author: { sub: 'bo' } }] }
+        : { next_cursor: 'c2', results: [{ id: 's1', anchor: { from: 0, to: 5, quote: 'Hello' }, position: { from: 0, to: 5, state: 'mapped' }, replacement: 'Hi', author: { sub: 'bo' } }] },
+    )
+    const listComments = jest.fn(async (q: { field: string; cursor?: string }) =>
+      q.cursor ? { next_cursor: null, results: [{ id: 't2', comments: [] }] } : { next_cursor: 'x', results: [{ id: 't1', comments: [] }] },
+    )
+    function H() {
+      const tc = useTrackChanges({ client: { listSuggestions, listComments }, field: 'blog', value: VALUE, version: 1 })
+      return <output data-testid="n">{`${tc.suggestions.map((s) => s.id).join(',')}|${tc.threads.map((t) => t.id).join(',')}`}</output>
+    }
+    render(<H />)
+    await waitFor(() => expect(screen.getByTestId('n')).toHaveTextContent('s1,s2|t1,t2'))
+    expect(listSuggestions).toHaveBeenLastCalledWith({ field: 'blog', cursor: 'c2' })
+  })
+})
+
+describe('own suggestions that cannot be loaded into the proposal', () => {
+  const ada: TrackActor = { sub: 'ada', label: 'ada@x.io', kind: 'person', kindSource: 'claim' }
+  const orphan: Suggestion = { ...sugg('o1', 'world', 'planet', ada), anchorState: 'orphaned', from: 0, to: 0 }
+
+  it('warns only about live ones the proposal cannot carry, which the next post supersedes', () => {
+    const overlapping = [sugg('m1', 'Hello world', 'Hi there', ada), sugg('m2', 'world', 'earth', ada), sugg('m3', 'Hello', 'Hey', ada)]
+    render(
+      <TrackedTextEditor label="Blog" value={VALUE} version={1} currentActorSub="ada" defaultMode="suggesting" onPropose={jest.fn()} suggestions={[orphan, ...overlapping]} />,
+    )
+    expect(screen.getByText('2 of your earlier suggestions overlap another of yours and could not be placed; your next change will replace them.')).toBeInTheDocument()
+  })
+
+  it('does not warn about an orphaned one: the server keeps it open (kept_orphaned, start-simpli-api #508)', () => {
+    render(
+      <TrackedTextEditor label="Blog" value={VALUE} version={1} currentActorSub="ada" defaultMode="suggesting" onPropose={jest.fn()} suggestions={[orphan]} />,
+    )
+    expect(screen.queryByText(/your next change will replace/)).toBeNull()
+  })
+})
+
+describe('blame with history off on the type', () => {
+  it('shows the server’s reason instead of an empty authorship view', async () => {
+    const client: TrackChangesClient = {
+      blame: jest.fn().mockResolvedValue({ version: 1, offset_unit: 'utf16', recorded: false, spans: null, detail: 'History is turned off for this type.' }),
+    }
+    function H() {
+      const tc = useTrackChanges({ client, field: 'blog', value: VALUE, version: 1 })
+      return <TrackedTextEditor label="Blog" value={VALUE} version={1} currentActorSub="a" blame={tc.blame} notices={tc.notices} />
+    }
+    render(<H />)
+    expect(await screen.findByText('Who wrote each passage is not recorded: History is turned off for this type.')).toBeInTheDocument()
+  })
+})

package/src/components/track-changes/describe.ts

@@ -0,0 +1,76 @@
+/**
+ * The sentence a screen reader hears, and a mouse user sees as a tooltip, for
+ * each mark (bd startsim-sjuai). One function for both, so the visual and the
+ * spoken account of a span can never disagree.
+ *
+ * Follows ActorIdentity's rule: a machine is ALWAYS named as a machine, a
+ * claimed person is not decorated, and `unknown` is stated calmly with its
+ * reason rather than as an error, because most of today's text predates the
+ * revision trail (design startsim-xyn25 section 0: 168 of 183 drafts have no
+ * revision at all).
+ */
+import { actorLabel } from '../ActorIdentity';
+import type { BlameSpan, CommentThread, Suggestion, TrackActor } from './types';
+
+const QUOTE_MAX = 60;
+
+export function quoted(text: string): string {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  const cut = flat.length > QUOTE_MAX ? `${flat.slice(0, QUOTE_MAX - 1)}…` : flat;
+  return `“${cut}”`;
+}
+
+/** "Ada (ada@x.io)" is ActorIdentity's job visually; spoken, the label alone
+ *  plus the kind when it carries information. */
+export function who(actor: TrackActor | null | undefined, fallback = 'someone'): string {
+  const label = actorLabel({ name: actor?.label }) || fallback;
+  if (actor?.kind === 'machine') {
+    return `${label} (machine${actor.kindSource === 'inferred' ? ', inferred' : ''})`;
+  }
+  if (actor?.kind === 'person' && actor.kindSource === 'inferred') return `${label} (person, inferred)`;
+  return label;
+}
+
+function when(at: string | null): string {
+  if (!at) return '';
+  const d = new Date(at);
+  if (Number.isNaN(d.getTime())) return '';
+  return `, ${d.toISOString().slice(0, 10)}`;
+}
+
+export function describeBlame(s: BlameSpan): string {
+  if (!s.author) return `Author unknown: ${s.unknownReason ?? 'not recorded'}`;
+  if (s.via === 'accepted_suggestion') {
+    const by = s.acceptedBy ? `, accepted by ${who(s.acceptedBy)}` : '';
+    return `Suggested by ${who(s.author)}${by}${when(s.at)}`;
+  }
+  if (s.via === 'restore') {
+    const from = s.restoredFrom != null ? ` from version ${s.restoredFrom}` : '';
+    return `Restored by ${who(s.author)}${from}${when(s.at)}`;
+  }
+  return `Written by ${who(s.author)}${when(s.at)}`;
+}
+
+export function describeChange(quote: string, replacement: string): string {
+  if (quote && replacement) return `replace ${quoted(quote)} with ${quoted(replacement)}`;
+  if (replacement) return `insert ${quoted(replacement)}`;
+  return `delete ${quoted(quote)}`;
+}
+
+export function describeSuggestion(s: Suggestion): string {
+  const moved = s.anchorState === 'reanchored' ? ' (the text around it changed)' : '';
+  return `Suggestion by ${who(s.author)}: ${describeChange(s.quote, s.replacement)}${moved}`;
+}
+
+export function describeLocal(deleted: string, inserted: string): string {
+  return `Your suggestion: ${describeChange(deleted, inserted)}`;
+}
+
+export function describeThread(t: CommentThread): string {
+  const root = t.comments[0];
+  const replies = t.comments.length - 1;
+  const tail = replies > 0 ? ` (${replies} ${replies === 1 ? 'reply' : 'replies'})` : '';
+  if (!root) return `Comment on ${quoted(t.quote)}${tail}`;
+  const body = t.redacted || root.body == null ? (root.deleted ? 'deleted comment' : 'comment hidden') : quoted(root.body);
+  return `Comment by ${who(root.author)}: ${body}${tail}`;
+}