feat(transcription): swap plain textarea for PersonMentionEditor and thread mentionedPersons through autosave

- TranscriptionBlockData now carries mentionedPersons (matches backend
  schema added in PR-A).
- useBlockAutoSave.saveFn signature widens to (blockId, text, mentions);
  pendingMentions is tracked alongside pendingTexts and is preserved on
  failure so a retry resends the in-flight payload (B12).
- TranscriptionBlock.svelte renders <PersonMentionEditor>, exposing the
  textarea node back through a captureTextarea callback so the existing
  quote-selection feature still works.
- saveBlock in routes/documents/[id]/+page.svelte forwards mentions on
  PUT.
- flushOnUnload sends mentions in the keepalive payload too.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

frontend/src/lib/hooks/__tests__/useBlockAutoSave.svelte.test.ts

@@ -1,6 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from 'vitest';
+import type { PersonMention } from '$lib/types';
 
-const mockSaveFn = vi.fn<(blockId: string, text: string) => Promise<void>>();
+const mockSaveFn =
+	vi.fn<(blockId: string, text: string, mentionedPersons: PersonMention[]) => Promise<void>>();
+
+const NO_MENTIONS: PersonMention[] = [];
 
 const { createBlockAutoSave } = await import('../useBlockAutoSave.svelte');
 
@@ -22,25 +26,25 @@ describe('createBlockAutoSave', () => {
 
 	it('debounce coalesces multiple changes — saves once after 1500ms', async () => {
 		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
-		as.handleTextChange('block-1', 'text 1');
-		as.handleTextChange('block-1', 'text 2');
-		as.handleTextChange('block-1', 'text 3');
+		as.handleTextChange('block-1', 'text 1', NO_MENTIONS);
+		as.handleTextChange('block-1', 'text 2', NO_MENTIONS);
+		as.handleTextChange('block-1', 'text 3', NO_MENTIONS);
 		await vi.advanceTimersByTimeAsync(1500);
 		expect(mockSaveFn).toHaveBeenCalledTimes(1);
-		expect(mockSaveFn).toHaveBeenCalledWith('block-1', 'text 3');
+		expect(mockSaveFn).toHaveBeenCalledWith('block-1', 'text 3', NO_MENTIONS);
 	});
 
 	it('handles concurrent blocks independently', async () => {
 		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
-		as.handleTextChange('block-1', 'hello');
-		as.handleTextChange('block-2', 'world');
+		as.handleTextChange('block-1', 'hello', NO_MENTIONS);
+		as.handleTextChange('block-2', 'world', NO_MENTIONS);
 		await vi.advanceTimersByTimeAsync(1500);
 		expect(mockSaveFn).toHaveBeenCalledTimes(2);
 	});
 
 	it('sets save state to saving then saved on success', async () => {
 		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
-		as.handleTextChange('block-1', 'text');
+		as.handleTextChange('block-1', 'text', NO_MENTIONS);
 		vi.advanceTimersByTime(1500);
 		expect(as.getSaveState('block-1')).toBe('saving');
 		await Promise.resolve();
@@ -50,7 +54,7 @@ describe('createBlockAutoSave', () => {
 	it('sets save state to error on save failure', async () => {
 		mockSaveFn.mockRejectedValue(new Error('save failed'));
 		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
-		as.handleTextChange('block-1', 'text');
+		as.handleTextChange('block-1', 'text', NO_MENTIONS);
 		await vi.advanceTimersByTimeAsync(1500);
 		expect(as.getSaveState('block-1')).toBe('error');
 	});
@@ -59,24 +63,24 @@ describe('createBlockAutoSave', () => {
 		mockSaveFn.mockRejectedValueOnce(new Error('first fails'));
 		mockSaveFn.mockResolvedValueOnce(undefined);
 		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
-		as.handleTextChange('block-1', 'original');
+		as.handleTextChange('block-1', 'original', NO_MENTIONS);
 		await vi.advanceTimersByTimeAsync(1500);
 		expect(as.getSaveState('block-1')).toBe('error');
-		await as.handleRetry('block-1', 'original');
+		await as.handleRetry('block-1', 'original', NO_MENTIONS);
 		expect(mockSaveFn).toHaveBeenCalledTimes(2);
 		expect(as.getSaveState('block-1')).toBe('saved');
 	});
 
 	it('clearBlock removes all state for a block', () => {
 		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
-		as.handleTextChange('block-1', 'text');
+		as.handleTextChange('block-1', 'text', NO_MENTIONS);
 		as.clearBlock('block-1');
 		expect(as.getSaveState('block-1')).toBe('idle');
 	});
 
 	it('destroy clears all pending timers so no save occurs', async () => {
 		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
-		as.handleTextChange('block-1', 'text');
+		as.handleTextChange('block-1', 'text', NO_MENTIONS);
 		as.destroy();
 		await vi.advanceTimersByTimeAsync(2000);
 		expect(mockSaveFn).not.toHaveBeenCalled();
@@ -101,8 +105,8 @@ describe('flushOnUnload', () => {
 
 	it('sends a PUT request with keepalive:true for each pending block', () => {
 		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
-		as.handleTextChange('block-1', 'hello');
-		as.handleTextChange('block-2', 'world');
+		as.handleTextChange('block-1', 'hello', NO_MENTIONS);
+		as.handleTextChange('block-2', 'world', NO_MENTIONS);
 		as.flushOnUnload();
 
 		expect(mockFetch).toHaveBeenCalledTimes(2);
@@ -111,7 +115,7 @@ describe('flushOnUnload', () => {
 			expect.objectContaining({
 				method: 'PUT',
 				keepalive: true,
-				body: JSON.stringify({ text: 'hello' })
+				body: JSON.stringify({ text: 'hello', mentionedPersons: [] })
 			})
 		);
 		expect(mockFetch).toHaveBeenCalledWith(
@@ -119,7 +123,7 @@ describe('flushOnUnload', () => {
 			expect.objectContaining({
 				method: 'PUT',
 				keepalive: true,
-				body: JSON.stringify({ text: 'world' })
+				body: JSON.stringify({ text: 'world', mentionedPersons: [] })
 			})
 		);
 	});
@@ -127,7 +131,7 @@ describe('flushOnUnload', () => {
 	it('does not call navigator.sendBeacon', () => {
 		const sendBeaconSpy = vi.spyOn(navigator, 'sendBeacon').mockReturnValue(true);
 		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
-		as.handleTextChange('block-1', 'text');
+		as.handleTextChange('block-1', 'text', NO_MENTIONS);
 		as.flushOnUnload();
 
 		expect(sendBeaconSpy).not.toHaveBeenCalled();
@@ -142,7 +146,7 @@ describe('flushOnUnload', () => {
 
 	it('cancels the debounce timer so saveFn is not also called', async () => {
 		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
-		as.handleTextChange('block-1', 'text');
+		as.handleTextChange('block-1', 'text', NO_MENTIONS);
 		as.flushOnUnload();
 
 		await vi.advanceTimersByTimeAsync(2000);
@@ -151,13 +155,26 @@ describe('flushOnUnload', () => {
 
 	it('does not send fetch if debounce already fired and pendingTexts is empty', async () => {
 		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
-		as.handleTextChange('block-1', 'text');
+		as.handleTextChange('block-1', 'text', NO_MENTIONS);
 		await vi.advanceTimersByTimeAsync(1500);
-		// debounce has fired; pendingTexts should be empty now
 		mockFetch.mockClear();
 
 		as.flushOnUnload();
 
 		expect(mockFetch).not.toHaveBeenCalled();
 	});
+
+	it('flushes the pending mentionedPersons sidecar alongside text', () => {
+		const as = createBlockAutoSave({ saveFn: mockSaveFn, documentId: 'doc-1' });
+		const mentions: PersonMention[] = [{ personId: 'p-1', displayName: 'Auguste Raddatz' }];
+		as.handleTextChange('block-1', '@Auguste Raddatz', mentions);
+		as.flushOnUnload();
+
+		expect(mockFetch).toHaveBeenCalledWith(
+			'/api/documents/doc-1/transcription-blocks/block-1',
+			expect.objectContaining({
+				body: JSON.stringify({ text: '@Auguste Raddatz', mentionedPersons: mentions })
+			})
+		);
+	});
 });

frontend/src/lib/hooks/__tests__/useBlockDragDrop.svelte.test.ts

@@ -12,7 +12,8 @@ function makeBlock(id: string, sortOrder: number): TranscriptionBlockData {
 		sortOrder,
 		version: 1,
 		source: 'MANUAL',
-		reviewed: false
+		reviewed: false,
+		mentionedPersons: []
 	};
 }
 

frontend/src/lib/hooks/useBlockAutoSave.svelte.ts

@@ -1,9 +1,10 @@
 import { SvelteMap } from 'svelte/reactivity';
+import type { PersonMention } from '$lib/types';
 
 export type SaveState = 'idle' | 'saving' | 'saved' | 'fading' | 'error';
 
 type Options = {
-	saveFn: (blockId: string, text: string) => Promise<void>;
+	saveFn: (blockId: string, text: string, mentionedPersons: PersonMention[]) => Promise<void>;
 	documentId: string;
 };
 
@@ -11,6 +12,7 @@ export function createBlockAutoSave({ saveFn, documentId }: Options) {
 	const saveStates = new SvelteMap<string, SaveState>();
 	const debounceTimers = new SvelteMap<string, ReturnType<typeof setTimeout>>();
 	const pendingTexts = new SvelteMap<string, string>();
+	const pendingMentions = new SvelteMap<string, PersonMention[]>();
 	const fadeTimers: ReturnType<typeof setTimeout>[] = [];
 
 	function getSaveState(blockId: string): SaveState {
@@ -21,18 +23,27 @@ export function createBlockAutoSave({ saveFn, documentId }: Options) {
 		saveStates.set(blockId, state);
 	}
 
+	function getPendingMentions(blockId: string, fallback: PersonMention[]): PersonMention[] {
+		return pendingMentions.get(blockId) ?? fallback;
+	}
+
 	async function executeSave(blockId: string): Promise<void> {
 		const text = pendingTexts.get(blockId);
 		if (text === undefined) return;
 
+		const mentions = pendingMentions.get(blockId) ?? [];
 		pendingTexts.delete(blockId);
+		pendingMentions.delete(blockId);
 		setSaveState(blockId, 'saving');
 
 		try {
-			await saveFn(blockId, text);
+			await saveFn(blockId, text, mentions);
 			setSaveState(blockId, 'saved');
 			scheduleSavedFade(blockId);
 		} catch {
+			// Preserve in-flight payload so the user can retry without re-typing.
+			pendingTexts.set(blockId, text);
+			pendingMentions.set(blockId, mentions);
 			setSaveState(blockId, 'error');
 		}
 	}
@@ -69,11 +80,22 @@ export function createBlockAutoSave({ saveFn, documentId }: Options) {
 		}
 	}
 
-	function handleTextChange(blockId: string, text: string): void {
+	function handleTextChange(
+		blockId: string,
+		text: string,
+		mentionedPersons: PersonMention[]
+	): void {
 		pendingTexts.set(blockId, text);
+		pendingMentions.set(blockId, mentionedPersons);
 		scheduleDebounce(blockId);
 	}
 
+	function handleMentionsChange(blockId: string, mentionedPersons: PersonMention[]): void {
+		pendingMentions.set(blockId, mentionedPersons);
+		// Mentions changes always accompany text changes from the editor, so the
+		// text-debounce timer covers them too.
+	}
+
 	function handleBlur(): void {
 		for (const [blockId] of [...debounceTimers]) {
 			clearDebounce(blockId);
@@ -81,29 +103,37 @@ export function createBlockAutoSave({ saveFn, documentId }: Options) {
 		}
 	}
 
-	async function handleRetry(blockId: string, currentText: string): Promise<void> {
-		const pending = pendingTexts.get(blockId);
-		const text = pending ?? currentText;
+	async function handleRetry(
+		blockId: string,
+		currentText: string,
+		currentMentions: PersonMention[]
+	): Promise<void> {
+		const text = pendingTexts.get(blockId) ?? currentText;
+		const mentions = pendingMentions.get(blockId) ?? currentMentions;
 		pendingTexts.set(blockId, text);
+		pendingMentions.set(blockId, mentions);
 		await executeSave(blockId);
 	}
 
 	function clearBlock(blockId: string): void {
 		clearDebounce(blockId);
 		pendingTexts.delete(blockId);
+		pendingMentions.delete(blockId);
 		saveStates.delete(blockId);
 	}
 
 	function flushOnUnload(): void {
 		for (const [blockId, text] of pendingTexts) {
+			const mentions = pendingMentions.get(blockId) ?? [];
 			clearDebounce(blockId);
 			void fetch(`/api/documents/${documentId}/transcription-blocks/${blockId}`, {
 				method: 'PUT',
 				headers: { 'Content-Type': 'application/json' },
-				body: JSON.stringify({ text }),
+				body: JSON.stringify({ text, mentionedPersons: mentions }),
 				keepalive: true
 			});
 			pendingTexts.delete(blockId);
+			pendingMentions.delete(blockId);
 		}
 	}
 
@@ -120,7 +150,9 @@ export function createBlockAutoSave({ saveFn, documentId }: Options) {
 
 	return {
 		getSaveState,
+		getPendingMentions,
 		handleTextChange,
+		handleMentionsChange,
 		handleBlur,
 		handleRetry,
 		clearBlock,