From 61256942e1e77915799162da01a0811d8bfc7290 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Thu, 4 Jun 2026 16:56:36 +0200
Subject: [PATCH] feat(transcribe): wire keyboard shortcuts into the document
 panel (#327)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Attaches the transcribeShortcuts action to the document page and wires every
command to existing context setters: j/k walk the sortOrder-sorted regions
and set activeAnnotationId, e toggles read/edit, n arms a draw cue (edit
only), Delete routes to the existing confirm path, ? opens the cheatsheet,
and Esc is now owned solely by the action — the inline onMount Esc listener
is removed (decision B1). Renders ShortcutCheatsheet and a draw-armed hint.

"t" toggles the document-level KURRENT_RECOGNITION training enrollment (the
only training surface that exists; there is no per-region flag yet — see
#321) and no-ops unless a region is active. Also reconciles annotation
Delete: the shape no longer self-handles the key, with onfocus syncing the
active region so the action deletes exactly once.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/lib/document/DocumentViewer.svelte    |  6 +-
 .../annotation/AnnotationLayer.svelte         |  6 +-
 .../annotation/AnnotationShape.svelte         | 15 +++-
 .../annotation/AnnotationShape.svelte.spec.ts | 60 +++++++++----
 .../src/lib/document/viewer/PdfViewer.svelte  |  6 +-
 .../src/routes/documents/[id]/+page.svelte    | 84 +++++++++++++++++--
 6 files changed, 142 insertions(+), 35 deletions(-)

diff --git a/frontend/src/lib/document/DocumentViewer.svelte b/frontend/src/lib/document/DocumentViewer.svelte
index aa8a575f..6b189961 100644
--- a/frontend/src/lib/document/DocumentViewer.svelte
+++ b/frontend/src/lib/document/DocumentViewer.svelte
@@ -25,7 +25,7 @@ type Props = {
 	flashAnnotationId?: string | null;
 	onAnnotationClick: (id: string) => void;
 	onTranscriptionDraw?: (rect: DrawRect) => void;
-	onDeleteAnnotationRequest?: (annotationId: string) => void;
+	onAnnotationFocus?: (id: string) => void;
 };
 
 let {
@@ -42,7 +42,7 @@ let {
 	flashAnnotationId = null,
 	onAnnotationClick,
 	onTranscriptionDraw,
-	onDeleteAnnotationRequest
+	onAnnotationFocus
 }: Props = $props();
 </script>
 
@@ -104,7 +104,7 @@ let {
 			flashAnnotationId={flashAnnotationId}
 			onAnnotationClick={onAnnotationClick}
 			onTranscriptionDraw={onTranscriptionDraw}
-			onDeleteAnnotationRequest={onDeleteAnnotationRequest}
+			onAnnotationFocus={onAnnotationFocus}
 			documentFileHash={doc.fileHash ?? null}
 		/>
 	{:else if fileUrl}
diff --git a/frontend/src/lib/document/annotation/AnnotationLayer.svelte b/frontend/src/lib/document/annotation/AnnotationLayer.svelte
index d392628c..35b321de 100644
--- a/frontend/src/lib/document/annotation/AnnotationLayer.svelte
+++ b/frontend/src/lib/document/annotation/AnnotationLayer.svelte
@@ -19,7 +19,7 @@ let {
 	flashAnnotationId = null,
 	onDraw,
 	onAnnotationClick,
-	onDeleteRequest
+	onAnnotationFocus
 }: {
 	annotations: Annotation[];
 	canDraw: boolean;
@@ -30,7 +30,7 @@ let {
 	flashAnnotationId?: string | null;
 	onDraw: (rect: DrawRect) => void;
 	onAnnotationClick?: (id: string) => void;
-	onDeleteRequest?: (annotationId: string) => void;
+	onAnnotationFocus?: (id: string) => void;
 } = $props();
 
 let drawStart = $state<{ x: number; y: number } | null>(null);
@@ -115,8 +115,8 @@ const containerStyle = $derived(
 			blockNumber={blockNumbers[annotation.id]}
 			isFlashing={flashAnnotationId === annotation.id}
 			showDelete={canDraw}
-			onDeleteRequest={() => onDeleteRequest?.(annotation.id)}
 			onclick={() => onAnnotationClick?.(annotation.id)}
+			onfocus={() => onAnnotationFocus?.(annotation.id)}
 			onpointerenter={() => (hoveredId = annotation.id)}
 			onpointerleave={() => (hoveredId = null)}
 		/>
diff --git a/frontend/src/lib/document/annotation/AnnotationShape.svelte b/frontend/src/lib/document/annotation/AnnotationShape.svelte
index c0cb985f..7b301d76 100644
--- a/frontend/src/lib/document/annotation/AnnotationShape.svelte
+++ b/frontend/src/lib/document/annotation/AnnotationShape.svelte
@@ -1,5 +1,6 @@
 <script lang="ts">
 import type { Annotation } from '$lib/shared/types';
+import { m } from '$lib/paraglide/messages.js';
 import AnnotationEditOverlay from './AnnotationEditOverlay.svelte';
 
 let {
@@ -12,8 +13,8 @@ let {
 	isFlashing = false,
 	isResizable = false,
 	showDelete = false,
-	onDeleteRequest,
 	onclick,
+	onfocus,
 	onpointerenter,
 	onpointerleave
 }: {
@@ -26,12 +27,17 @@ let {
 	isFlashing?: boolean;
 	isResizable?: boolean;
 	showDelete?: boolean;
-	onDeleteRequest?: () => void;
 	onclick: () => void;
+	onfocus?: () => void;
 	onpointerenter: () => void;
 	onpointerleave: () => void;
 } = $props();
 
+// When deletion is available (transcribe mode), announce the otherwise-hidden
+// Delete affordance to assistive tech (issue #327). The transcribeShortcuts
+// action is the single owner of the key itself.
+const ariaLabel = $derived(showDelete ? m.annotation_label_with_delete() : 'Block anzeigen');
+
 function hexToRgba(hex: string, alpha: number): string {
 	const r = parseInt(hex.slice(1, 3), 16);
 	const g = parseInt(hex.slice(3, 5), 16);
@@ -83,11 +89,12 @@ let shapeStyle = $derived(
 	class:annotation-flash={isFlashing}
 	role="button"
 	tabindex="0"
-	aria-label="Block anzeigen"
+	aria-label={ariaLabel}
+	aria-keyshortcuts={showDelete ? 'Delete' : undefined}
 	onclick={onclick}
+	onfocus={onfocus}
 	onkeydown={(e) => {
 		if (e.key === 'Enter' || e.key === ' ') onclick();
-		if (e.key === 'Delete' && showDelete) onDeleteRequest?.();
 	}}
 	onpointerenter={onpointerenter}
 	onpointerleave={onpointerleave}
diff --git a/frontend/src/lib/document/annotation/AnnotationShape.svelte.spec.ts b/frontend/src/lib/document/annotation/AnnotationShape.svelte.spec.ts
index 79cb7680..0170bbc9 100644
--- a/frontend/src/lib/document/annotation/AnnotationShape.svelte.spec.ts
+++ b/frontend/src/lib/document/annotation/AnnotationShape.svelte.spec.ts
@@ -43,7 +43,6 @@ describe('AnnotationShape', () => {
 			isHovered: true,
 			isActive: true,
 			showDelete: true,
-			onDeleteRequest: vi.fn(),
 			onclick: () => {},
 			onpointerenter: () => {},
 			onpointerleave: () => {}
@@ -57,16 +56,17 @@ describe('AnnotationShape', () => {
 		expect(annotationEl.querySelectorAll('button').length).toBe(0);
 	});
 
-	it('calls onDeleteRequest when Delete key is pressed on the annotation', async () => {
-		const onDeleteRequest = vi.fn();
-
+	// Deletion is owned solely by the transcribeShortcuts action (issue #327,
+	// decision: action is the single Delete owner). The shape must NOT handle
+	// the Delete key itself, or the key would delete twice.
+	it('does not act on the Delete key itself (the action owns deletion)', async () => {
+		const onclick = vi.fn();
 		render(AnnotationShape, {
 			annotation: makeAnnotation(),
 			isHovered: false,
 			isActive: true,
 			showDelete: true,
-			onDeleteRequest,
-			onclick: () => {},
+			onclick,
 			onpointerenter: () => {},
 			onpointerleave: () => {}
 		});
@@ -74,26 +74,58 @@ describe('AnnotationShape', () => {
 		const annotationEl = page.getByTestId('annotation-ann-1').element() as HTMLElement;
 		annotationEl.dispatchEvent(new KeyboardEvent('keydown', { key: 'Delete', bubbles: true }));
 
-		expect(onDeleteRequest).toHaveBeenCalledOnce();
+		// No side effect from the shape; it stays in the document for the action to act on.
+		expect(onclick).not.toHaveBeenCalled();
+		await expect.element(page.getByTestId('annotation-ann-1')).toBeInTheDocument();
 	});
 
-	it('does not call onDeleteRequest on Delete key when showDelete is false', async () => {
-		const onDeleteRequest = vi.fn();
-
+	it('announces the Delete affordance via aria when deletion is available', async () => {
 		render(AnnotationShape, {
 			annotation: makeAnnotation(),
 			isHovered: false,
 			isActive: true,
-			showDelete: false,
-			onDeleteRequest,
+			showDelete: true,
 			onclick: () => {},
 			onpointerenter: () => {},
 			onpointerleave: () => {}
 		});
 
 		const annotationEl = page.getByTestId('annotation-ann-1').element() as HTMLElement;
-		annotationEl.dispatchEvent(new KeyboardEvent('keydown', { key: 'Delete', bubbles: true }));
+		expect(annotationEl.getAttribute('aria-keyshortcuts')).toBe('Delete');
+		expect(annotationEl.getAttribute('aria-label')).toContain('Entf');
+	});
 
-		expect(onDeleteRequest).not.toHaveBeenCalled();
+	it('keeps the plain label and no key hint when deletion is unavailable', async () => {
+		render(AnnotationShape, {
+			annotation: makeAnnotation(),
+			isHovered: false,
+			isActive: false,
+			showDelete: false,
+			onclick: () => {},
+			onpointerenter: () => {},
+			onpointerleave: () => {}
+		});
+
+		const annotationEl = page.getByTestId('annotation-ann-1').element() as HTMLElement;
+		expect(annotationEl.getAttribute('aria-keyshortcuts')).toBe(null);
+		expect(annotationEl.getAttribute('aria-label')).toBe('Block anzeigen');
+	});
+
+	it('calls onfocus when the annotation receives focus', async () => {
+		const onfocus = vi.fn();
+		render(AnnotationShape, {
+			annotation: makeAnnotation(),
+			isHovered: false,
+			isActive: false,
+			onfocus,
+			onclick: () => {},
+			onpointerenter: () => {},
+			onpointerleave: () => {}
+		});
+
+		const annotationEl = page.getByTestId('annotation-ann-1').element() as HTMLElement;
+		annotationEl.dispatchEvent(new FocusEvent('focus'));
+
+		expect(onfocus).toHaveBeenCalledOnce();
 	});
 });
diff --git a/frontend/src/lib/document/viewer/PdfViewer.svelte b/frontend/src/lib/document/viewer/PdfViewer.svelte
index 5164178d..90aa8853 100644
--- a/frontend/src/lib/document/viewer/PdfViewer.svelte
+++ b/frontend/src/lib/document/viewer/PdfViewer.svelte
@@ -20,7 +20,7 @@ let {
 	activeAnnotationId = $bindable<string | null>(null),
 	onAnnotationClick,
 	onTranscriptionDraw,
-	onDeleteAnnotationRequest,
+	onAnnotationFocus,
 	documentFileHash,
 	annotationsDimmed = false,
 	flashAnnotationId = null,
@@ -35,7 +35,7 @@ let {
 	activeAnnotationId?: string | null;
 	onAnnotationClick?: (id: string) => void;
 	onTranscriptionDraw?: (rect: DrawRect) => void;
-	onDeleteAnnotationRequest?: (annotationId: string) => void;
+	onAnnotationFocus?: (id: string) => void;
 	documentFileHash?: string | null;
 	annotationsDimmed?: boolean;
 	flashAnnotationId?: string | null;
@@ -294,7 +294,7 @@ function handleAnnotationClick(id: string) {
 								flashAnnotationId={flashAnnotationId}
 								onDraw={handleDraw}
 								onAnnotationClick={handleAnnotationClick}
-								onDeleteRequest={onDeleteAnnotationRequest}
+								onAnnotationFocus={onAnnotationFocus}
 							/>
 						{/if}
 					</div>
diff --git a/frontend/src/routes/documents/[id]/+page.svelte b/frontend/src/routes/documents/[id]/+page.svelte
index 32cd894e..8cc746d6 100644
--- a/frontend/src/routes/documents/[id]/+page.svelte
+++ b/frontend/src/routes/documents/[id]/+page.svelte
@@ -8,6 +8,8 @@ import DocumentViewer from '$lib/document/DocumentViewer.svelte';
 import TranscriptionEditView from '$lib/document/transcription/TranscriptionEditView.svelte';
 import TranscriptionReadView from '$lib/document/transcription/TranscriptionReadView.svelte';
 import TranscriptionPanelHeader from '$lib/document/transcription/TranscriptionPanelHeader.svelte';
+import ShortcutCheatsheet from '$lib/document/transcription/ShortcutCheatsheet.svelte';
+import { transcribeShortcuts } from '$lib/shared/actions/transcribeShortcuts';
 import { createOcrJob } from '$lib/ocr/useOcrJob.svelte';
 import { createTranscriptionBlocks } from '$lib/document/transcription/useTranscriptionBlocks.svelte';
 import { createFileLoader } from '$lib/document/viewer/useFileLoader.svelte';
@@ -42,6 +44,8 @@ let activeAnnotationId = $state<string | null>(null);
 let highlightBlockId = $state<string | null>(null);
 let flashAnnotationId = $state<string | null>(null);
 let pdfStripExpanded = $state(false);
+let cheatsheetOpen = $state(false);
+let drawArmed = $state(false);
 // Flag set by the deep-link helper so the transcribe-mode $effect does not
 // overwrite the panelMode it picked (e.g. forcing 'edit' on notification
 // click-through). One-shot: consumed after the effect's loadBlocks resolves.
@@ -86,12 +90,69 @@ async function createBlockFromDraw(rect: {
 	height: number;
 	pageNumber: number;
 }) {
+	drawArmed = false;
 	const created = await transcription.createFromDraw(rect);
 	if (created) {
 		activeAnnotationId = created.annotationId;
 	}
 }
 
+// ── Keyboard shortcuts (issue #327) ──────────────────────────────────────────
+
+const sortedBlocks = $derived([...transcription.blocks].sort((a, b) => a.sortOrder - b.sortOrder));
+
+function goToRegion(delta: 1 | -1) {
+	if (sortedBlocks.length === 0) return;
+	const current = sortedBlocks.findIndex((b) => b.annotationId === activeAnnotationId);
+	const next =
+		current === -1
+			? delta > 0
+				? 0
+				: sortedBlocks.length - 1
+			: (current + delta + sortedBlocks.length) % sortedBlocks.length;
+	activeAnnotationId = sortedBlocks[next].annotationId;
+}
+
+function toggleMode() {
+	if (canWrite) panelMode = panelMode === 'read' ? 'edit' : 'read';
+}
+
+// Training enrollment is document-level — two fixed script-type chips
+// (KURRENT_RECOGNITION / KURRENT_SEGMENTATION); there is no per-region training
+// flag (that would arrive with #321). "t" toggles the primary recognition
+// enrollment and stays a no-op unless a region is active, so it reads as an
+// action on the region the transcriber is working on.
+const RECOGNITION_TRAINING_LABEL = 'KURRENT_RECOGNITION';
+
+function toggleTrainingMark() {
+	if (!activeAnnotationId) return;
+	const enrolled = !(doc.trainingLabels ?? []).includes(RECOGNITION_TRAINING_LABEL);
+	transcription.toggleTrainingLabel(RECOGNITION_TRAINING_LABEL, enrolled);
+}
+
+function deleteCurrentRegion() {
+	if (activeAnnotationId) handleAnnotationDeleteRequest(activeAnnotationId);
+}
+
+// Disarm the draw cue whenever we leave edit mode.
+$effect(() => {
+	if (panelMode !== 'edit') drawArmed = false;
+});
+
+const shortcutOptions = {
+	isPanelOpen: () => transcribeMode,
+	isCheatsheetOpen: () => cheatsheetOpen,
+	panelMode: () => panelMode,
+	goToNextRegion: () => goToRegion(1),
+	goToPrevRegion: () => goToRegion(-1),
+	toggleMode,
+	closePanel: () => (transcribeMode = false),
+	startDrawMode: () => (drawArmed = true),
+	toggleTrainingMark,
+	deleteCurrentRegion,
+	openCheatsheet: () => (cheatsheetOpen = true)
+};
+
 function handleBlockFocus(blockId: string) {
 	const block = transcription.blocks.find((b) => b.id === blockId);
 	if (block) {
@@ -208,14 +269,9 @@ onMount(() => {
 		onStripUrl: () => replaceState(page.url.pathname, page.state ?? {})
 	}).catch((e) => console.error('deep-link scroll failed', e));
 
-	function onKeyDown(e: KeyboardEvent) {
-		if (e.key === 'Escape' && transcribeMode) {
-			transcribeMode = false;
-		}
-	}
-	document.addEventListener('keydown', onKeyDown);
+	// Esc is owned solely by the transcribeShortcuts action (issue #327, decision
+	// B1) — no competing inline keydown listener here.
 	return () => {
-		document.removeEventListener('keydown', onKeyDown);
 		ocrJob.destroy();
 	};
 });
@@ -229,6 +285,7 @@ onMount(() => {
 	class="fixed right-0 bottom-0 left-0 z-40 flex flex-col overflow-hidden bg-surface"
 	style="top: {navHeight}px"
 	data-hydrated
+	use:transcribeShortcuts={shortcutOptions}
 >
 	<DocumentTopBar
 		doc={doc}
@@ -260,7 +317,7 @@ onMount(() => {
 				bind:activeAnnotationId={activeAnnotationId}
 				onAnnotationClick={handleAnnotationClick}
 				onTranscriptionDraw={createBlockFromDraw}
-				onDeleteAnnotationRequest={handleAnnotationDeleteRequest}
+				onAnnotationFocus={(id) => (activeAnnotationId = id)}
 			/>
 		</div>
 
@@ -369,4 +426,15 @@ onMount(() => {
 			</div>
 		{/if}
 	</div>
+
+	{#if drawArmed && panelMode === 'edit'}
+		<div
+			class="pointer-events-none absolute bottom-4 left-1/2 z-50 -translate-x-1/2 rounded-full bg-ink px-4 py-2 font-sans text-xs text-white shadow-lg"
+			role="status"
+		>
+			{m.shortcut_draw_hint()}
+		</div>
+	{/if}
+
+	<ShortcutCheatsheet open={cheatsheetOpen} onClose={() => (cheatsheetOpen = false)} />
 </div>