feat: add PDF annotation feature (#40)

Backend:
- Add ANNOTATE_ALL permission
- Add ANNOTATION_NOT_FOUND and ANNOTATION_OVERLAP error codes
- V10 migration: document_annotations table with page/rect/color/owner
- DocumentAnnotation entity, AnnotationRepository, CreateAnnotationDTO
- AnnotationService: overlap detection (rectangle intersection), ownership enforcement on delete
- AnnotationController: GET (authenticated), POST/DELETE (ANNOTATE_ALL)
- 15 new tests (AnnotationServiceTest, AnnotationControllerTest) — TDD red/green

Frontend:
- AnnotationLayer.svelte: pointer-event drawing, colored rect overlays, delete buttons
- PdfViewer.svelte: annotate toggle, color picker, loads/saves/deletes annotations via API
- Disabled annotate button with tooltip for users without ANNOTATE_ALL
- canAnnotate exposed from layout server, passed to PdfViewer
- errors.ts + de/en/es translations for new error codes
- 3 new unit tests for AnnotationLayer — TDD red/green

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

frontend/messages/de.json

@@ -1,5 +1,7 @@
 {
 	"$schema": "https://inlang.com/schema/inlang-message-format",
+	"error_annotation_not_found": "Die Annotation wurde nicht gefunden.",
+	"error_annotation_overlap": "Die Annotation überschneidet sich mit einer vorhandenen.",
 	"error_document_not_found": "Das Dokument wurde nicht gefunden.",
 	"error_document_no_file": "Diesem Dokument ist noch keine Datei zugeordnet.",
 	"error_file_not_found": "Die Datei konnte im Speicher nicht gefunden werden.",

frontend/messages/en.json

@@ -1,5 +1,7 @@
 {
 	"$schema": "https://inlang.com/schema/inlang-message-format",
+	"error_annotation_not_found": "Annotation not found.",
+	"error_annotation_overlap": "The annotation overlaps an existing one.",
 	"error_document_not_found": "Document not found.",
 	"error_document_no_file": "No file is associated with this document.",
 	"error_file_not_found": "The file could not be found in storage.",

frontend/messages/es.json

@@ -1,5 +1,7 @@
 {
 	"$schema": "https://inlang.com/schema/inlang-message-format",
+	"error_annotation_not_found": "Anotación no encontrada.",
+	"error_annotation_overlap": "La anotación se superpone con una existente.",
 	"error_document_not_found": "Documento no encontrado.",
 	"error_document_no_file": "No hay ningún archivo asociado a este documento.",
 	"error_file_not_found": "El archivo no pudo encontrarse en el almacenamiento.",

frontend/src/lib/components/AnnotationLayer.svelte

@@ -0,0 +1,165 @@
+<script lang="ts">
+type Annotation = {
+	id: string;
+	documentId: string;
+	pageNumber: number;
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	color: string;
+	createdAt: string;
+};
+
+type DrawRect = {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+};
+
+let {
+	annotations = [],
+	canAnnotate,
+	color,
+	onDraw,
+	onDelete
+}: {
+	annotations: Annotation[];
+	canAnnotate: boolean;
+	color: string;
+	onDraw: (rect: { x: number; y: number; width: number; height: number }) => void;
+	onDelete: (id: string) => void;
+} = $props();
+
+let drawStart = $state<{ x: number; y: number } | null>(null);
+let drawRect = $state<DrawRect | null>(null);
+
+function getNormalizedCoords(event: PointerEvent, element: HTMLElement): { x: number; y: number } {
+	const rect = element.getBoundingClientRect();
+	return {
+		x: (event.clientX - rect.left) / rect.width,
+		y: (event.clientY - rect.top) / rect.height
+	};
+}
+
+function handlePointerDown(event: PointerEvent) {
+	if (!canAnnotate) return;
+
+	const target = event.target as HTMLElement;
+	if (target.dataset.annotation !== undefined) return;
+
+	const container = event.currentTarget as HTMLElement;
+	container.setPointerCapture(event.pointerId);
+
+	const coords = getNormalizedCoords(event, container);
+	drawStart = coords;
+	drawRect = { x: coords.x, y: coords.y, width: 0, height: 0 };
+}
+
+function handlePointerMove(event: PointerEvent) {
+	if (!canAnnotate || !drawStart) return;
+
+	const container = event.currentTarget as HTMLElement;
+	const coords = getNormalizedCoords(event, container);
+
+	const x = Math.min(drawStart.x, coords.x);
+	const y = Math.min(drawStart.y, coords.y);
+	const width = Math.abs(coords.x - drawStart.x);
+	const height = Math.abs(coords.y - drawStart.y);
+
+	drawRect = { x, y, width, height };
+}
+
+function handlePointerUp(event: PointerEvent) {
+	if (!canAnnotate || !drawStart || !drawRect) return;
+
+	const container = event.currentTarget as HTMLElement;
+	const coords = getNormalizedCoords(event, container);
+
+	const x = Math.min(drawStart.x, coords.x);
+	const y = Math.min(drawStart.y, coords.y);
+	const width = Math.abs(coords.x - drawStart.x);
+	const height = Math.abs(coords.y - drawStart.y);
+
+	if (width > 0.01 && height > 0.01) {
+		onDraw({ x, y, width, height });
+	}
+
+	drawStart = null;
+	drawRect = null;
+}
+
+const containerStyle = $derived(
+	`position: absolute; top: 0; left: 0; width: 100%; height: 100%;${canAnnotate ? ' cursor: crosshair;' : ''}`
+);
+</script>
+
+<div
+	style={containerStyle}
+	role="presentation"
+	onpointerdown={handlePointerDown}
+	onpointermove={handlePointerMove}
+	onpointerup={handlePointerUp}
+>
+	{#each annotations as annotation (annotation.id)}
+		<div
+			data-testid="annotation-{annotation.id}"
+			data-annotation
+			style="
+				position: absolute;
+				left: {annotation.x * 100}%;
+				top: {annotation.y * 100}%;
+				width: {annotation.width * 100}%;
+				height: {annotation.height * 100}%;
+				background-color: {annotation.color};
+				opacity: 0.3;
+				pointer-events: {canAnnotate ? 'auto' : 'none'};
+			"
+		>
+			{#if canAnnotate}
+				<button
+					aria-label="Annotation löschen"
+					onclick={(e) => {
+						e.stopPropagation();
+						onDelete(annotation.id);
+					}}
+					style="
+						position: absolute;
+						top: -8px;
+						right: -8px;
+						width: 16px;
+						height: 16px;
+						background-color: #ef4444;
+						color: white;
+						border: none;
+						border-radius: 50%;
+						cursor: pointer;
+						display: flex;
+						align-items: center;
+						justify-content: center;
+						font-size: 12px;
+						line-height: 1;
+						padding: 0;
+						pointer-events: auto;
+					">×</button
+				>
+			{/if}
+		</div>
+	{/each}
+
+	{#if drawRect && drawRect.width > 0}
+		<div
+			style="
+				position: absolute;
+				left: {drawRect.x * 100}%;
+				top: {drawRect.y * 100}%;
+				width: {drawRect.width * 100}%;
+				height: {drawRect.height * 100}%;
+				border: 2px dashed {color};
+				opacity: 0.3;
+				pointer-events: none;
+			"
+		></div>
+	{/if}
+</div>

frontend/src/lib/components/AnnotationLayer.svelte.spec.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+
+import AnnotationLayer from './AnnotationLayer.svelte';
+
+afterEach(cleanup);
+
+type Annotation = {
+	id: string;
+	documentId: string;
+	pageNumber: number;
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	color: string;
+	createdAt: string;
+};
+
+function makeAnnotation(id = 'ann-1'): Annotation {
+	return {
+		id,
+		documentId: 'doc-1',
+		pageNumber: 1,
+		x: 0.1,
+		y: 0.1,
+		width: 0.3,
+		height: 0.2,
+		color: '#ff0000',
+		createdAt: new Date().toISOString()
+	};
+}
+
+describe('AnnotationLayer', () => {
+	it('renders a colored element for each annotation', async () => {
+		render(AnnotationLayer, {
+			annotations: [makeAnnotation('ann-1'), makeAnnotation('ann-2')],
+			canAnnotate: false,
+			color: '#ff0000',
+			onDraw: () => {},
+			onDelete: () => {}
+		});
+
+		await expect.element(page.getByTestId('annotation-ann-1')).toBeInTheDocument();
+		await expect.element(page.getByTestId('annotation-ann-2')).toBeInTheDocument();
+	});
+
+	it('shows a delete button for each annotation when canAnnotate is true', async () => {
+		render(AnnotationLayer, {
+			annotations: [makeAnnotation('ann-1')],
+			canAnnotate: true,
+			color: '#ff0000',
+			onDraw: () => {},
+			onDelete: () => {}
+		});
+
+		await expect
+			.element(page.getByRole('button', { name: /annotation löschen/i }))
+			.toBeInTheDocument();
+	});
+
+	it('does not show delete buttons when canAnnotate is false', async () => {
+		render(AnnotationLayer, {
+			annotations: [makeAnnotation('ann-1')],
+			canAnnotate: false,
+			color: '#ff0000',
+			onDraw: () => {},
+			onDelete: () => {}
+		});
+
+		expect(page.getByRole('button', { name: /annotation löschen/i }).query()).toBeNull();
+	});
+});

frontend/src/lib/components/PdfViewer.svelte

@@ -1,8 +1,17 @@
 <script lang="ts">
 import { onMount } from 'svelte';
 import type { PDFDocumentProxy, PDFPageProxy, RenderTask } from 'pdfjs-dist';
+import AnnotationLayer from './AnnotationLayer.svelte';
 
-let { url }: { url: string } = $props();
+let {
+	url,
+	documentId = '',
+	canAnnotate = false
+}: {
+	url: string;
+	documentId?: string;
+	canAnnotate?: boolean;
+} = $props();
 
 let pdfDoc = $state<PDFDocumentProxy | null>(null);
 let currentPage = $state(1);
@@ -24,6 +33,22 @@ let textLayerInstance: { cancel: () => void } | null = null;
 let pdfjsLib: typeof import('pdfjs-dist') | null = null;
 let pdfjsReady = $state(false);
 
+type Annotation = {
+	id: string;
+	documentId: string;
+	pageNumber: number;
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	color: string;
+	createdAt: string;
+};
+
+let annotations = $state<Annotation[]>([]);
+let annotateMode = $state(false);
+let annotateColor = $state('#ffff00');
+
 onMount(async () => {
 	// Dynamic import keeps pdfjs out of the SSR bundle entirely
 	const [lib, { default: workerUrl }] = await Promise.all([
@@ -134,6 +159,54 @@ async function prerender(doc: PDFDocumentProxy, pageNum: number) {
 	}
 }
 
+async function loadAnnotations(docId: string) {
+	if (!docId) return;
+	try {
+		const res = await fetch(`/api/documents/${docId}/annotations`);
+		if (res.ok) annotations = await res.json();
+	} catch {
+		// ignore
+	}
+}
+
+async function handleAnnotationDraw(rect: { x: number; y: number; width: number; height: number }) {
+	if (!documentId) return;
+	try {
+		const res = await fetch(`/api/documents/${documentId}/annotations`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				pageNumber: currentPage,
+				x: rect.x,
+				y: rect.y,
+				width: rect.width,
+				height: rect.height,
+				color: annotateColor
+			})
+		});
+		if (res.ok) {
+			const created: Annotation = await res.json();
+			annotations = [...annotations, created];
+		}
+	} catch {
+		// ignore
+	}
+}
+
+async function handleAnnotationDelete(annotationId: string) {
+	if (!documentId) return;
+	try {
+		const res = await fetch(`/api/documents/${documentId}/annotations/${annotationId}`, {
+			method: 'DELETE'
+		});
+		if (res.ok) {
+			annotations = annotations.filter((a) => a.id !== annotationId);
+		}
+	} catch {
+		// ignore
+	}
+}
+
 $effect(() => {
 	if (pdfjsReady && url) {
 		loadDocument(url);
@@ -151,6 +224,12 @@ $effect(() => {
 	}
 });
 
+$effect(() => {
+	if (documentId) {
+		loadAnnotations(documentId);
+	}
+});
+
 function prevPage() {
 	if (currentPage > 1) currentPage -= 1;
 }
@@ -274,6 +353,37 @@ function zoomOut() {
 					</svg>
 				</button>
 			</div>
+
+			<!-- Annotate controls -->
+			{#if canAnnotate}
+				<div class="flex items-center gap-1">
+					<button
+						onclick={() => (annotateMode = !annotateMode)}
+						aria-label={annotateMode ? 'Annotieren beenden' : 'Annotieren'}
+						class="rounded px-2 py-1 font-sans text-xs text-gray-300 transition hover:bg-white/10 {annotateMode ? 'bg-white/20' : ''}"
+					>
+						{annotateMode ? 'Fertig' : 'Annotieren'}
+					</button>
+					{#if annotateMode}
+						<input
+							type="color"
+							bind:value={annotateColor}
+							aria-label="Farbe wählen"
+							class="h-6 w-6 cursor-pointer rounded border-0 bg-transparent p-0"
+							title="Farbe wählen"
+						/>
+					{/if}
+				</div>
+			{:else}
+				<button
+					disabled
+					title="Sie benötigen die Berechtigung ANNOTATE_ALL zum Annotieren"
+					class="cursor-not-allowed rounded px-2 py-1 font-sans text-xs text-gray-500"
+					aria-label="Annotieren (keine Berechtigung)"
+				>
+					Annotieren
+				</button>
+			{/if}
 		</div>
 
 		<!-- PDF canvas area -->
@@ -297,6 +407,13 @@ function zoomOut() {
 							class="textLayer"
 							style="position: absolute; top: 0; left: 0; overflow: hidden; pointer-events: none; line-height: 1;"
 						></div>
+						<AnnotationLayer
+							annotations={annotations.filter((a) => a.pageNumber === currentPage)}
+							canAnnotate={annotateMode}
+							color={annotateColor}
+							onDraw={handleAnnotationDraw}
+							onDelete={handleAnnotationDelete}
+						/>
 					</div>
 				</div>
 			{/if}

frontend/src/lib/errors.ts

@@ -14,6 +14,8 @@ export type ErrorCode =
 	| 'WRONG_CURRENT_PASSWORD'
 	| 'IMPORT_ALREADY_RUNNING'
 	| 'INVALID_RESET_TOKEN'
+	| 'ANNOTATION_NOT_FOUND'
+	| 'ANNOTATION_OVERLAP'
 	| 'UNAUTHORIZED'
 	| 'FORBIDDEN'
 	| 'VALIDATION_ERROR'
@@ -61,6 +63,10 @@ export function getErrorMessage(code: ErrorCode | string | undefined): string {
 			return m.error_import_already_running();
 		case 'INVALID_RESET_TOKEN':
 			return m.error_invalid_reset_token();
+		case 'ANNOTATION_NOT_FOUND':
+			return m.error_annotation_not_found();
+		case 'ANNOTATION_OVERLAP':
+			return m.error_annotation_overlap();
 		case 'UNAUTHORIZED':
 			return m.error_unauthorized();
 		case 'FORBIDDEN':

frontend/src/routes/+layout.server.ts

@@ -1,11 +1,10 @@
 import type { LayoutServerLoad } from './$types';
 
 export const load: LayoutServerLoad = async ({ locals }) => {
+	const groups: { permissions: string[] }[] = locals.user?.groups ?? [];
 	return {
 		user: locals.user,
-		canWrite:
-			locals.user?.groups?.some((g: { permissions: string[] }) =>
-				g.permissions.includes('WRITE_ALL')
-			) ?? false
+		canWrite: groups.some((g) => g.permissions.includes('WRITE_ALL')),
+		canAnnotate: groups.some((g) => g.permissions.includes('ANNOTATE_ALL'))
 	};
 };

frontend/src/routes/admin/page.svelte.spec.ts

@@ -29,6 +29,7 @@ const makeUser = (overrides = {}) => ({
 const baseData = {
 	user: undefined,
 	canWrite: true,
+	canAnnotate: false,
 	users: [makeUser()],
 	groups: [makeGroup()],
 	tags: []

frontend/src/routes/admin/users/[id]/page.svelte.spec.ts

@@ -24,7 +24,13 @@ const makeUser = (overrides = {}) => ({
 	...overrides
 });
 
-const baseData = { user: undefined, canWrite: true, editUser: makeUser(), groups };
+const baseData = {
+	user: undefined,
+	canWrite: true,
+	canAnnotate: false,
+	editUser: makeUser(),
+	groups
+};
 
 afterEach(cleanup);
 

frontend/src/routes/admin/users/new/page.svelte.spec.ts

@@ -10,7 +10,7 @@ const groups = [
 	{ id: 'g2', name: 'Admins', permissions: ['ADMIN'] }
 ];
 
-const baseData = { user: undefined, canWrite: true, groups };
+const baseData = { user: undefined, canWrite: true, canAnnotate: false, groups };
 
 afterEach(cleanup);
 

frontend/src/routes/conversations/page.svelte.spec.ts

@@ -12,6 +12,7 @@ afterEach(cleanup);
 const baseData = {
 	user: undefined,
 	canWrite: true,
+	canAnnotate: false,
 	documents: [],
 	initialValues: { senderName: '', receiverName: '' },
 	filters: { senderId: '', receiverId: '', from: '', to: '', dir: 'DESC' as const }

frontend/src/routes/documents/[id]/+page.svelte

@@ -875,7 +875,7 @@ function versionLabel(v: VersionSummary, index: number): string {
 					<p class="font-sans text-sm tracking-wide uppercase">{m.doc_no_scan()}</p>
 				</div>
 			{:else if fileUrl && doc.contentType?.startsWith('application/pdf')}
-				<PdfViewer url={fileUrl} />
+				<PdfViewer url={fileUrl} documentId={doc.id} canAnnotate={data.canAnnotate} />
 			{:else if fileUrl}
 				<div class="flex h-full w-full items-center justify-center overflow-auto p-8">
 					<img

frontend/src/routes/documents/new/page.svelte.spec.ts

@@ -10,6 +10,7 @@ afterEach(cleanup);
 const baseData = {
 	user: undefined,
 	canWrite: true,
+	canAnnotate: false,
 	persons: [],
 	initialSenderId: '',
 	initialSenderName: '',

frontend/src/routes/layout.svelte.spec.ts

@@ -22,6 +22,7 @@ const makeData = (overrides = {}) => ({
 		createdAt: ''
 	},
 	canWrite: true,
+	canAnnotate: false,
 	...overrides
 });
 

frontend/src/routes/page.svelte.spec.ts

@@ -20,6 +20,7 @@ afterEach(cleanup);
 const emptyData = {
 	user: undefined,
 	canWrite: true,
+	canAnnotate: false,
 	filters: { q: '', from: '', to: '', senderId: '', receiverId: '', tags: [] },
 	documents: [],
 	initialValues: { senderName: '', receiverName: '' },

frontend/src/routes/persons/page.svelte.spec.ts

@@ -14,7 +14,7 @@ const makePerson = (overrides = {}) => ({
 	...overrides
 });
 
-const emptyData = { user: undefined, canWrite: true, q: '', persons: [] };
+const emptyData = { user: undefined, canWrite: true, canAnnotate: false, q: '', persons: [] };
 const dataWithPersons = { ...emptyData, persons: [makePerson()] };
 
 afterEach(cleanup);