refactor: move document transcription, annotation, viewer sub-packages

- transcription/: TranscriptionBlock, Column, EditView, PanelHeader, ReadView, Section + transcriptionMarkers, blockConflictMerge, saveBlockWithConflictRetry + useBlockAutoSave, useBlockDragDrop hooks - annotation/: AnnotationLayer, AnnotationShape, AnnotationEditOverlay - viewer/: PdfViewer, PdfControls + useFileLoader, usePdfRenderer hooks Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-05 14:01:39 +02:00
parent e7f8aa5894
commit 1e656d2db4
43 changed files with 32 additions and 27 deletions
--- a/frontend/src/lib/document/viewer/PdfControls.svelte
+++ b/frontend/src/lib/document/viewer/PdfControls.svelte
@@ -0,0 +1,125 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+
+type Props = {
+	currentPage: number;
+	totalPages: number;
+	isLoaded: boolean;
+	showAnnotations: boolean;
+	annotationCount: number;
+	onPrev: () => void;
+	onNext: () => void;
+	onZoomIn: () => void;
+	onZoomOut: () => void;
+	onToggleAnnotations: () => void;
+};
+
+let {
+	currentPage,
+	totalPages,
+	isLoaded,
+	showAnnotations,
+	annotationCount,
+	onPrev,
+	onNext,
+	onZoomIn,
+	onZoomOut,
+	onToggleAnnotations
+}: Props = $props();
+</script>
+
+<div class="flex shrink-0 items-center justify-between gap-2 border-b border-pdf-ctrl px-4 py-2">
+	<!-- Page navigation: prev button, page counter, next button -->
+	<div class="flex items-center gap-2">
+		<button
+			onclick={onPrev}
+			disabled={currentPage <= 1}
+			aria-label="Zurück"
+			class="rounded p-1 text-ink-3 transition hover:bg-surface/10 disabled:opacity-40"
+		>
+			<svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+				<path stroke-linecap="round" stroke-linejoin="round" d="M15 19l-7-7 7-7" />
+			</svg>
+		</button>
+
+		{#if totalPages > 0}
+			<span class="font-sans text-xs text-ink-2 tabular-nums">
+				{currentPage} / {totalPages}
+			</span>
+		{/if}
+
+		<button
+			onclick={onNext}
+			disabled={!isLoaded || currentPage >= totalPages}
+			aria-label="Weiter"
+			class="rounded p-1 text-ink-3 transition hover:bg-surface/10 disabled:opacity-40"
+		>
+			<svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+				<path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7" />
+			</svg>
+		</button>
+	</div>
+
+	<!-- Zoom controls -->
+	<div class="flex items-center gap-1">
+		<button
+			onclick={onZoomOut}
+			aria-label="Verkleinern"
+			class="rounded p-1 text-ink-3 transition hover:bg-surface/10"
+		>
+			<svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+				<circle cx="11" cy="11" r="8" />
+				<path stroke-linecap="round" d="M21 21l-4.35-4.35M8 11h6" />
+			</svg>
+		</button>
+		<button
+			onclick={onZoomIn}
+			aria-label="Vergrößern"
+			class="rounded p-1 text-ink-3 transition hover:bg-surface/10"
+		>
+			<svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+				<circle cx="11" cy="11" r="8" />
+				<path stroke-linecap="round" d="M21 21l-4.35-4.35M11 8v6M8 11h6" />
+			</svg>
+		</button>
+	</div>
+
+	<!-- Annotation visibility toggle (only when annotations exist) -->
+	{#if annotationCount > 0}
+		<button
+			onclick={onToggleAnnotations}
+			aria-label={showAnnotations ? m.pdf_annotations_hide() : m.pdf_annotations_show()}
+			class="flex items-center gap-1.5 rounded px-2 py-1 font-sans text-xs transition {showAnnotations
+				? 'text-ink-2 hover:bg-surface/10'
+				: 'bg-surface/10 text-primary'}"
+		>
+			<svg
+				class="h-3.5 w-3.5 shrink-0"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="2"
+			>
+				{#if showAnnotations}
+					<path
+						stroke-linecap="round"
+						stroke-linejoin="round"
+						d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"
+					/>
+					<path
+						stroke-linecap="round"
+						stroke-linejoin="round"
+						d="M2.458 12C3.732 7.943 7.523 5 12 5c4.478 0 8.268 2.943 9.542 7-1.274 4.057-5.064 7-9.542 7-4.477 0-8.268-2.943-9.542-7z"
+					/>
+				{:else}
+					<path
+						stroke-linecap="round"
+						stroke-linejoin="round"
+						d="M13.875 18.825A10.05 10.05 0 0112 19c-4.478 0-8.268-2.943-9.543-7a9.97 9.97 0 011.563-3.029m5.858.908a3 3 0 114.243 4.243M9.878 9.878l4.242 4.242M9.88 9.88l-3.29-3.29m7.532 7.532l3.29 3.29M3 3l3.59 3.59m0 0A9.953 9.953 0 0112 5c4.478 0 8.268 2.943 9.543 7a10.025 10.025 0 01-4.132 5.411m0 0L21 21"
+					/>
+				{/if}
+			</svg>
+			{showAnnotations ? m.pdf_annotations_hide() : m.pdf_annotations_show()}
+		</button>
+	{/if}
+</div>
--- a/frontend/src/lib/document/viewer/PdfControls.svelte.spec.ts
+++ b/frontend/src/lib/document/viewer/PdfControls.svelte.spec.ts
@@ -0,0 +1,67 @@
+import { vi, describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+
+import PdfControls from './PdfControls.svelte';
+
+afterEach(cleanup);
+
+const defaultProps = {
+	currentPage: 1,
+	totalPages: 3,
+	isLoaded: true,
+	showAnnotations: false,
+	annotationCount: 0,
+	onPrev: vi.fn(),
+	onNext: vi.fn(),
+	onZoomIn: vi.fn(),
+	onZoomOut: vi.fn(),
+	onToggleAnnotations: vi.fn()
+};
+
+describe('PdfControls — annotation toggle visibility', () => {
+	it('renders annotation toggle when annotationCount is greater than zero', async () => {
+		render(PdfControls, { ...defaultProps, annotationCount: 3 });
+		await expect
+			.element(page.getByRole('button', { name: /annotierungen anzeigen/i }))
+			.toBeInTheDocument();
+	});
+
+	it('does not render annotation toggle when annotationCount is zero', async () => {
+		render(PdfControls, { ...defaultProps, annotationCount: 0 });
+		await expect
+			.element(page.getByRole('button', { name: /annotierungen/i }))
+			.not.toBeInTheDocument();
+	});
+});
+
+describe('PdfControls — annotation toggle label', () => {
+	it('shows "Annotierungen anzeigen" label when annotations are hidden', async () => {
+		render(PdfControls, { ...defaultProps, annotationCount: 2, showAnnotations: false });
+		const btn = page.getByRole('button', { name: /annotierungen anzeigen/i });
+		await expect.element(btn).toBeInTheDocument();
+	});
+
+	it('shows "Annotierungen verbergen" label when annotations are visible', async () => {
+		render(PdfControls, { ...defaultProps, annotationCount: 2, showAnnotations: true });
+		const btn = page.getByRole('button', { name: /annotierungen verbergen/i });
+		await expect.element(btn).toBeInTheDocument();
+	});
+});
+
+describe('PdfControls — annotation toggle contrast (WCAG 2.1 AA)', () => {
+	it('uses text-primary class on annotation toggle button when annotations are hidden', async () => {
+		const { container } = render(PdfControls, {
+			...defaultProps,
+			annotationCount: 2,
+			showAnnotations: false
+		});
+		const allButtons = container.querySelectorAll('button');
+		const annotationBtn = Array.from(allButtons).find((b) =>
+			b.getAttribute('aria-label')?.toLowerCase().includes('annotierungen')
+		);
+		expect(annotationBtn).not.toBeNull();
+		expect(annotationBtn!.className).toContain('text-primary');
+		expect(annotationBtn!.className).not.toContain('text-accent');
+	});
+});
--- a/frontend/src/lib/document/viewer/PdfViewer.svelte
+++ b/frontend/src/lib/document/viewer/PdfViewer.svelte
@@ -0,0 +1,277 @@
+<script lang="ts">
+import { onMount, setContext } from 'svelte';
+import { createPdfRenderer } from '$lib/document/viewer/usePdfRenderer.svelte';
+import PdfControls from './PdfControls.svelte';
+import AnnotationLayer from '$lib/document/annotation/AnnotationLayer.svelte';
+import type { Annotation } from '$lib/types';
+import { m } from '$lib/paraglide/messages.js';
+import { parseBackendError, getErrorMessage } from '$lib/errors';
+
+type DrawRect = { x: number; y: number; width: number; height: number; pageNumber: number };
+
+let {
+	url,
+	documentId = '',
+	transcribeMode = false,
+	blockNumbers = {},
+	annotationReloadKey = 0,
+	activeAnnotationId = $bindable<string | null>(null),
+	onAnnotationClick,
+	onTranscriptionDraw,
+	onDeleteAnnotationRequest,
+	documentFileHash,
+	annotationsDimmed = false,
+	flashAnnotationId = null
+}: {
+	url: string;
+	documentId?: string;
+	transcribeMode?: boolean;
+	blockNumbers?: Record<string, number>;
+	annotationReloadKey?: number;
+	activeAnnotationId?: string | null;
+	onAnnotationClick?: (id: string) => void;
+	onTranscriptionDraw?: (rect: DrawRect) => void;
+	onDeleteAnnotationRequest?: (annotationId: string) => void;
+	documentFileHash?: string | null;
+	annotationsDimmed?: boolean;
+	flashAnnotationId?: string | null;
+} = $props();
+
+const renderer = createPdfRenderer();
+
+// Canvas and text layer container refs — bound via bind:this
+let canvasEl = $state<HTMLCanvasElement | null>(null);
+let textLayerEl = $state<HTMLDivElement | null>(null);
+
+let annotations = $state<Annotation[]>([]);
+let showAnnotations = $state(true);
+let annotationUpdateError = $state<string | null>(null);
+
+const TRANSCRIPTION_COLOR = '#00C7B1';
+
+const visibleAnnotations = $derived(
+	annotations.filter((a) => !a.fileHash || !documentFileHash || a.fileHash === documentFileHash)
+);
+const outdatedCount = $derived(annotations.length - visibleAnnotations.length);
+
+onMount(async () => {
+	await renderer.init();
+});
+
+$effect(() => {
+	if (renderer.pdfjsReady && url) {
+		renderer.loadDocument(url);
+	}
+});
+
+// Wire DOM elements to the renderer and trigger rendering.
+// canvasEl is read synchronously so Svelte tracks it as a dependency:
+// when the canvas reappears after the loading spinner (loading → false),
+// this effect re-fires and renders the already-loaded PDF.
+$effect(() => {
+	if (!canvasEl || !textLayerEl) return;
+	renderer.setElements(canvasEl, textLayerEl);
+	// Also track currentPage and scale so page-nav / zoom re-renders work.
+	if (renderer.isLoaded && renderer.currentPage && renderer.scale > 0) {
+		renderer.renderCurrentPage().then(() => renderer.prerender());
+	}
+});
+
+$effect(() => {
+	if (documentId && annotationReloadKey >= 0) {
+		loadAnnotations(documentId);
+	}
+});
+
+$effect(() => {
+	if (transcribeMode) showAnnotations = true;
+});
+
+// Scroll-sync: when activeAnnotationId changes, navigate to its page
+let prevActiveAnnotationId: string | null = null;
+$effect(() => {
+	const id = activeAnnotationId;
+	if (!id || id === prevActiveAnnotationId || !renderer.isLoaded) {
+		prevActiveAnnotationId = id;
+		return;
+	}
+	prevActiveAnnotationId = id;
+
+	const ann = annotations.find((a) => a.id === id);
+	if (!ann) return;
+
+	if (ann.pageNumber !== renderer.currentPage) {
+		renderer.goToPage(ann.pageNumber);
+	}
+
+	requestAnimationFrame(() => {
+		requestAnimationFrame(() => {
+			const el = document.querySelector(`[data-testid="annotation-${id}"]`);
+			el?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+		});
+	});
+});
+
+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 updateAnnotation(
+	annotationId: string,
+	coords: { x: number; y: number; width: number; height: number }
+) {
+	if (!documentId) return;
+	const res = await fetch(`/api/documents/${documentId}/annotations/${annotationId}`, {
+		method: 'PATCH',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify(coords)
+	});
+	if (!res.ok) {
+		const err = await parseBackendError(res);
+		const msg = getErrorMessage(err?.code ?? 'ANNOTATION_UPDATE_FAILED');
+		annotationUpdateError = msg;
+		setTimeout(() => (annotationUpdateError = null), 4000);
+		throw new Error(msg);
+	}
+	const updated = await res.json();
+	annotations = annotations.map((a) => (a.id === annotationId ? updated : a));
+}
+
+setContext('annotationUpdate', updateAnnotation);
+
+async function handleDraw(rect: { x: number; y: number; width: number; height: number }) {
+	if (!documentId || !transcribeMode) return;
+	await onTranscriptionDraw?.({ ...rect, pageNumber: renderer.currentPage });
+	await loadAnnotations(documentId);
+}
+
+function handleAnnotationClick(id: string) {
+	activeAnnotationId = id;
+	onAnnotationClick?.(id);
+}
+</script>
+
+{#if !url}
+	<div class="flex h-full w-full items-center justify-center bg-pdf-bg text-ink-3">
+		<p class="font-sans text-sm">Keine Datei vorhanden</p>
+	</div>
+{:else if renderer.error}
+	<div class="flex h-full w-full flex-col items-center justify-center gap-3 bg-pdf-bg text-ink-3">
+		<p class="font-sans text-sm text-red-400">Fehler beim Laden der PDF</p>
+		<a
+			href={url}
+			target="_blank"
+			rel="noopener noreferrer"
+			class="font-sans text-xs text-primary underline hover:text-ink-2"
+		>
+			Direkt öffnen
+		</a>
+	</div>
+{:else}
+	<div class="flex h-full w-full flex-col bg-pdf-bg">
+		{#if outdatedCount > 0}
+			<div
+				class="flex shrink-0 items-center gap-2 border-b border-amber-500/30 bg-amber-500/10 px-4 py-2"
+				data-testid="annotation-outdated-notice"
+			>
+				<svg
+					class="h-4 w-4 shrink-0 text-amber-400"
+					viewBox="0 0 24 24"
+					fill="none"
+					stroke="currentColor"
+					stroke-width="2"
+				>
+					<path
+						stroke-linecap="round"
+						stroke-linejoin="round"
+						d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z"
+					/>
+				</svg>
+				<span class="font-sans text-xs text-amber-300">{m.annotation_outdated_notice()}</span>
+			</div>
+		{/if}
+		{#if annotationUpdateError}
+			<div
+				class="flex shrink-0 items-center gap-2 border-b border-red-500/30 bg-red-500/10 px-4 py-2"
+				aria-live="assertive"
+				role="alert"
+			>
+				<svg
+					class="h-4 w-4 shrink-0 text-red-400"
+					viewBox="0 0 24 24"
+					fill="none"
+					stroke="currentColor"
+					stroke-width="2"
+				>
+					<circle cx="12" cy="12" r="10" />
+					<line x1="15" y1="9" x2="9" y2="15" />
+					<line x1="9" y1="9" x2="15" y2="15" />
+				</svg>
+				<span class="font-sans text-xs text-red-300">{annotationUpdateError}</span>
+			</div>
+		{/if}
+
+		<PdfControls
+			currentPage={renderer.currentPage}
+			totalPages={renderer.totalPages}
+			isLoaded={renderer.isLoaded}
+			showAnnotations={showAnnotations}
+			annotationCount={annotations.length}
+			onPrev={() => renderer.prevPage()}
+			onNext={() => renderer.nextPage()}
+			onZoomIn={() => renderer.zoomIn()}
+			onZoomOut={() => renderer.zoomOut()}
+			onToggleAnnotations={() => (showAnnotations = !showAnnotations)}
+		/>
+
+		<!-- PDF canvas area -->
+		<div class="relative flex-1 overflow-auto">
+			{#if renderer.loading}
+				<div class="flex h-full items-center justify-center">
+					<div
+						class="h-8 w-8 animate-spin rounded-full border-2 border-white/20 border-t-white"
+					></div>
+				</div>
+			{:else}
+				<div class="flex min-h-full items-start justify-center p-4">
+					<div
+						class="pdf-page relative shadow-xl"
+						data-page-number={renderer.currentPage}
+						style="position: relative"
+					>
+						<canvas bind:this={canvasEl}></canvas>
+						<div
+							bind:this={textLayerEl}
+							class="textLayer"
+							style="position: absolute; top: 0; left: 0; overflow: hidden; pointer-events: none; line-height: 1;"
+						></div>
+						{#if showAnnotations}
+							<AnnotationLayer
+								annotations={visibleAnnotations.filter(
+									(a) => a.pageNumber === renderer.currentPage
+								)}
+								canDraw={transcribeMode}
+								color={TRANSCRIPTION_COLOR}
+								blockNumbers={blockNumbers}
+								activeAnnotationId={activeAnnotationId}
+								dimmed={annotationsDimmed}
+								flashAnnotationId={flashAnnotationId}
+								onDraw={handleDraw}
+								onAnnotationClick={handleAnnotationClick}
+								onDeleteRequest={onDeleteAnnotationRequest}
+							/>
+						{/if}
+					</div>
+				</div>
+			{/if}
+		</div>
+	</div>
+{/if}
--- a/frontend/src/lib/document/viewer/PdfViewer.svelte.spec.ts
+++ b/frontend/src/lib/document/viewer/PdfViewer.svelte.spec.ts
@@ -0,0 +1,53 @@
+import { vi, describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+
+// pdfjs-dist is a rendering dependency — we mock it so unit tests don't need
+// a real browser PDF engine. The interesting behaviour under test here is the
+// component's own UI logic (controls, page counter), not pdfjs internals.
+vi.mock('pdfjs-dist', () => {
+	function TextLayerMock() {}
+	TextLayerMock.prototype.render = () => Promise.resolve();
+	TextLayerMock.prototype.cancel = () => {};
+
+	return {
+		GlobalWorkerOptions: { workerSrc: '' },
+		getDocument: vi.fn().mockReturnValue({
+			promise: Promise.resolve({
+				numPages: 2,
+				getPage: vi.fn().mockResolvedValue({
+					getViewport: vi.fn().mockReturnValue({ width: 595, height: 842 }),
+					render: vi.fn().mockReturnValue({ promise: Promise.resolve() }),
+					streamTextContent: vi.fn().mockReturnValue(new ReadableStream())
+				})
+			})
+		}),
+		TextLayer: TextLayerMock
+	};
+});
+
+vi.mock('pdfjs-dist/build/pdf.worker.min.mjs?url', () => ({ default: '' }));
+
+import PdfViewer from './PdfViewer.svelte';
+
+afterEach(cleanup);
+
+describe('PdfViewer', () => {
+	it('shows previous and next page navigation buttons', async () => {
+		render(PdfViewer, { url: '/api/documents/test-id/file' });
+		await expect.element(page.getByRole('button', { name: /zurück/i })).toBeInTheDocument();
+		await expect.element(page.getByRole('button', { name: /weiter/i })).toBeInTheDocument();
+	});
+
+	it('shows zoom controls', async () => {
+		render(PdfViewer, { url: '/api/documents/test-id/file' });
+		await expect.element(page.getByRole('button', { name: /vergrößern/i })).toBeInTheDocument();
+		await expect.element(page.getByRole('button', { name: /verkleinern/i })).toBeInTheDocument();
+	});
+
+	it('displays the page counter once the PDF has loaded', async () => {
+		render(PdfViewer, { url: '/api/documents/test-id/file' });
+		// Mock resolves synchronously, so "1 / 2" should appear quickly
+		await expect.element(page.getByText(/1\s*\/\s*2/)).toBeInTheDocument();
+	});
+});
--- a/frontend/src/lib/document/viewer/useFileLoader.svelte.test.ts
+++ b/frontend/src/lib/document/viewer/useFileLoader.svelte.test.ts
@@ -0,0 +1,98 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { createFileLoader } from './useFileLoader.svelte';
+
+const FAKE_URL = 'blob:fake-url';
+
+function setupFetch(ok: boolean, body?: Blob) {
+	const blob = body ?? new Blob(['fake'], { type: 'application/pdf' });
+	vi.stubGlobal(
+		'fetch',
+		vi.fn().mockResolvedValue({
+			ok,
+			blob: vi.fn().mockResolvedValue(blob)
+		})
+	);
+}
+
+afterEach(() => {
+	vi.unstubAllGlobals();
+	vi.restoreAllMocks();
+});
+
+describe('createFileLoader', () => {
+	it('sets fileUrl after a successful fetch', async () => {
+		vi.stubGlobal('URL', {
+			createObjectURL: vi.fn().mockReturnValue(FAKE_URL),
+			revokeObjectURL: vi.fn()
+		});
+		setupFetch(true);
+
+		const loader = createFileLoader();
+		await loader.loadFile('/api/documents/1/file');
+
+		expect(loader.fileUrl).toBe(FAKE_URL);
+		expect(loader.isLoading).toBe(false);
+		expect(loader.fileError).toBe('');
+	});
+
+	it('sets fileError on a failed fetch (non-ok response)', async () => {
+		vi.stubGlobal('URL', {
+			createObjectURL: vi.fn(),
+			revokeObjectURL: vi.fn()
+		});
+		setupFetch(false);
+
+		const loader = createFileLoader();
+		await loader.loadFile('/api/documents/1/file');
+
+		expect(loader.fileUrl).toBe('');
+		expect(loader.fileError).not.toBe('');
+		expect(loader.isLoading).toBe(false);
+	});
+
+	it('revokes the previous URL before creating a new one', async () => {
+		const revokeObjectURL = vi.fn();
+		vi.stubGlobal('URL', {
+			createObjectURL: vi.fn().mockReturnValue(FAKE_URL),
+			revokeObjectURL
+		});
+		setupFetch(true);
+
+		const loader = createFileLoader();
+		await loader.loadFile('/api/documents/1/file');
+		// First load: no previous URL to revoke
+		expect(revokeObjectURL).not.toHaveBeenCalled();
+
+		await loader.loadFile('/api/documents/2/file');
+		// Second load: previous URL should be revoked
+		expect(revokeObjectURL).toHaveBeenCalledWith(FAKE_URL);
+	});
+
+	it('revokes the URL on destroy', async () => {
+		const revokeObjectURL = vi.fn();
+		vi.stubGlobal('URL', {
+			createObjectURL: vi.fn().mockReturnValue(FAKE_URL),
+			revokeObjectURL
+		});
+		setupFetch(true);
+
+		const loader = createFileLoader();
+		await loader.loadFile('/api/documents/1/file');
+		loader.destroy();
+
+		expect(revokeObjectURL).toHaveBeenCalledWith(FAKE_URL);
+	});
+
+	it('does not revoke when no URL has been set', () => {
+		const revokeObjectURL = vi.fn();
+		vi.stubGlobal('URL', {
+			createObjectURL: vi.fn(),
+			revokeObjectURL
+		});
+
+		const loader = createFileLoader();
+		loader.destroy();
+
+		expect(revokeObjectURL).not.toHaveBeenCalled();
+	});
+});
--- a/frontend/src/lib/document/viewer/useFileLoader.svelte.ts
+++ b/frontend/src/lib/document/viewer/useFileLoader.svelte.ts
@@ -0,0 +1,47 @@
+import { untrack } from 'svelte';
+
+export function createFileLoader() {
+	let fileUrl = $state('');
+	let isLoading = $state(false);
+	let fileError = $state('');
+
+	async function loadFile(url: string): Promise<void> {
+		isLoading = true;
+		fileError = '';
+		// untrack prevents callers ($effect) from accidentally subscribing to fileUrl.
+		// Without it, the calling effect would re-run every time fileUrl changes (i.e.
+		// on every successful load), creating an infinite load loop.
+		const prev = untrack(() => fileUrl);
+		if (prev) URL.revokeObjectURL(prev);
+		fileUrl = '';
+
+		try {
+			const response = await fetch(url);
+			if (!response.ok) throw new Error('Failed to load file');
+			const blob = await response.blob();
+			fileUrl = URL.createObjectURL(blob);
+		} catch {
+			fileError = 'Vorschau konnte nicht geladen werden.';
+		} finally {
+			isLoading = false;
+		}
+	}
+
+	function destroy(): void {
+		if (fileUrl) URL.revokeObjectURL(fileUrl);
+	}
+
+	return {
+		get fileUrl() {
+			return fileUrl;
+		},
+		get isLoading() {
+			return isLoading;
+		},
+		get fileError() {
+			return fileError;
+		},
+		loadFile,
+		destroy
+	};
+}
--- a/frontend/src/lib/document/viewer/usePdfRenderer.svelte.test.ts
+++ b/frontend/src/lib/document/viewer/usePdfRenderer.svelte.test.ts
@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { createPdfRenderer } from './usePdfRenderer.svelte';
+
+// Note: init() and loadDocument() require pdfjsLib (browser module).
+// These tests cover pure state logic only — bounds clamping and zoom limits.
+
+describe('createPdfRenderer', () => {
+	it('starts at page 1 with scale 1.5 and no error', () => {
+		const r = createPdfRenderer();
+		expect(r.currentPage).toBe(1);
+		expect(r.scale).toBe(1.5);
+		expect(r.totalPages).toBe(0);
+		expect(r.loading).toBe(false);
+		expect(r.error).toBeNull();
+		expect(r.isLoaded).toBe(false);
+		expect(r.pdfjsReady).toBe(false);
+	});
+
+	it('prevPage does not go below page 1', () => {
+		const r = createPdfRenderer();
+		r.prevPage();
+		expect(r.currentPage).toBe(1);
+	});
+
+	it('nextPage does not exceed totalPages', () => {
+		const r = createPdfRenderer();
+		// totalPages = 0, so 1 < 0 is false → stays at 1
+		r.nextPage();
+		expect(r.currentPage).toBe(1);
+	});
+
+	it('goToPage does not navigate when n > totalPages', () => {
+		const r = createPdfRenderer();
+		r.goToPage(5);
+		expect(r.currentPage).toBe(1);
+	});
+
+	it('goToPage does not navigate when n < 1', () => {
+		const r = createPdfRenderer();
+		r.goToPage(0);
+		expect(r.currentPage).toBe(1);
+	});
+
+	it('zoomIn increases scale by 0.25', () => {
+		const r = createPdfRenderer();
+		r.zoomIn();
+		expect(r.scale).toBeCloseTo(1.75);
+	});
+
+	it('zoomOut decreases scale by 0.25', () => {
+		const r = createPdfRenderer();
+		r.zoomOut();
+		expect(r.scale).toBeCloseTo(1.25);
+	});
+
+	it('zoomOut does not go below 0.5', () => {
+		const r = createPdfRenderer();
+		for (let i = 0; i < 20; i++) r.zoomOut();
+		expect(r.scale).toBeCloseTo(0.5);
+	});
+
+	it('loadDocument is a no-op when pdfjsLib not initialized', async () => {
+		const r = createPdfRenderer();
+		await r.loadDocument('/some/path');
+		// No-op because pdfjsLib is null (init not called)
+		expect(r.error).toBeNull();
+		expect(r.loading).toBe(false);
+	});
+});
--- a/frontend/src/lib/document/viewer/usePdfRenderer.svelte.ts
+++ b/frontend/src/lib/document/viewer/usePdfRenderer.svelte.ts
@@ -0,0 +1,203 @@
+import type { PDFDocumentProxy, RenderTask } from 'pdfjs-dist';
+
+export function createPdfRenderer() {
+	// Reactive state — exposed via getters
+	let currentPage = $state(1);
+	let totalPages = $state(0);
+	let scale = $state(1.5);
+	let loading = $state(false);
+	let error = $state<string | null>(null);
+	let pdfjsReady = $state(false);
+
+	// Internal mutable refs — NOT $state to avoid reactive loops
+	let pdfDoc: PDFDocumentProxy | null = null;
+	let canvasEl: HTMLCanvasElement | null = null;
+	let textLayerEl: HTMLDivElement | null = null;
+	let renderTask: RenderTask | null = null;
+	let textLayerInstance: { cancel: () => void } | null = null;
+	let pdfjsLib: typeof import('pdfjs-dist') | null = null;
+
+	async function init(): Promise<void> {
+		const [lib, { default: workerUrl }] = await Promise.all([
+			import('pdfjs-dist'),
+			import('pdfjs-dist/build/pdf.worker.min.mjs?url')
+		]);
+		lib.GlobalWorkerOptions.workerSrc = workerUrl;
+		pdfjsLib = lib;
+		pdfjsReady = true;
+	}
+
+	function setElements(canvas: HTMLCanvasElement, textLayer: HTMLDivElement): void {
+		canvasEl = canvas;
+		textLayerEl = textLayer;
+	}
+
+	async function loadDocument(src: string): Promise<void> {
+		if (!pdfjsLib) return;
+		loading = true;
+		error = null;
+		pdfDoc = null;
+		currentPage = 1;
+		totalPages = 0;
+
+		try {
+			const loadingTask = pdfjsLib.getDocument(src);
+			const doc = await loadingTask.promise;
+			pdfDoc = doc;
+			totalPages = doc.numPages;
+		} catch (e) {
+			error = e instanceof Error ? e.message : 'Failed to load PDF';
+		} finally {
+			loading = false;
+		}
+	}
+
+	async function renderCurrentPage(): Promise<void> {
+		if (!pdfjsLib || !canvasEl || !textLayerEl || !pdfDoc) return;
+
+		if (renderTask) {
+			renderTask.cancel();
+			renderTask = null;
+		}
+		if (textLayerInstance) {
+			textLayerInstance.cancel();
+			textLayerInstance = null;
+		}
+
+		let page;
+		try {
+			page = await pdfDoc.getPage(currentPage);
+		} catch {
+			return;
+		}
+
+		const dpr = window.devicePixelRatio || 1;
+		const viewport = page.getViewport({ scale: scale * dpr });
+
+		const canvas = canvasEl;
+		const ctx = canvas.getContext('2d');
+		if (!ctx) return;
+
+		canvas.width = viewport.width;
+		canvas.height = viewport.height;
+		canvas.style.width = `${viewport.width / dpr}px`;
+		canvas.style.height = `${viewport.height / dpr}px`;
+
+		const task = page.render({ canvas, canvasContext: ctx, viewport });
+		renderTask = task;
+
+		try {
+			await task.promise;
+		} catch (e: unknown) {
+			if (
+				typeof e === 'object' &&
+				e !== null &&
+				'name' in e &&
+				(e as { name: string }).name === 'RenderingCancelledException'
+			)
+				return;
+			return;
+		}
+		renderTask = null;
+
+		const textDiv = textLayerEl;
+		if (!textDiv) return;
+		textDiv.innerHTML = '';
+		textDiv.style.width = `${viewport.width / dpr}px`;
+		textDiv.style.height = `${viewport.height / dpr}px`;
+
+		const tl = new pdfjsLib.TextLayer({
+			textContentSource: page.streamTextContent(),
+			container: textDiv,
+			viewport
+		});
+		textLayerInstance = tl;
+		try {
+			await tl.render();
+		} catch {
+			// cancelled
+		}
+	}
+
+	async function prerender(): Promise<void> {
+		if (!pdfDoc) return;
+		const neighbors = [currentPage - 1, currentPage + 1].filter(
+			(n) => n >= 1 && n <= (pdfDoc?.numPages ?? 0)
+		);
+		for (const n of neighbors) {
+			try {
+				await pdfDoc.getPage(n);
+			} catch {
+				// ignore
+			}
+		}
+	}
+
+	function prevPage(): void {
+		if (currentPage > 1) currentPage -= 1;
+	}
+
+	function nextPage(): void {
+		if (currentPage < totalPages) currentPage += 1;
+	}
+
+	function goToPage(n: number): void {
+		if (n >= 1 && n <= totalPages) currentPage = n;
+	}
+
+	function zoomIn(): void {
+		scale += 0.25;
+	}
+
+	function zoomOut(): void {
+		if (scale > 0.5) scale -= 0.25;
+	}
+
+	function destroy(): void {
+		if (renderTask) {
+			renderTask.cancel();
+			renderTask = null;
+		}
+		if (textLayerInstance) {
+			textLayerInstance.cancel();
+			textLayerInstance = null;
+		}
+		pdfDoc?.destroy();
+		pdfDoc = null;
+	}
+
+	return {
+		get currentPage() {
+			return currentPage;
+		},
+		get totalPages() {
+			return totalPages;
+		},
+		get scale() {
+			return scale;
+		},
+		get loading() {
+			return loading;
+		},
+		get error() {
+			return error;
+		},
+		get isLoaded() {
+			return totalPages > 0;
+		},
+		get pdfjsReady() {
+			return pdfjsReady;
+		},
+		setElements,
+		init,
+		loadDocument,
+		renderCurrentPage,
+		prerender,
+		prevPage,
+		nextPage,
+		goToPage,
+		zoomIn,
+		zoomOut,
+		destroy
+	};
+}