Merge remote-tracking branch 'origin/main' into HEAD

# Conflicts:
#	frontend/src/lib/shared/dashboard/ReaderRecentDocs.svelte.spec.ts
#	frontend/src/routes/+page.server.ts

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

@@ -10,8 +10,9 @@ type DashboardPulseDTO = components['schemas']['DashboardPulseDTO'];
 type ActivityFeedItemDTO = components['schemas']['ActivityFeedItemDTO'];
 type IncompleteDocumentDTO = components['schemas']['IncompleteDocumentDTO'];
 type PersonSummaryDTO = components['schemas']['PersonSummaryDTO'];
-type Document = components['schemas']['Document'];
+type DocumentListItem = components['schemas']['DocumentListItem'];
 type Geschichte = components['schemas']['Geschichte'];
+type TagTreeNodeDTO = components['schemas']['TagTreeNodeDTO'];
 
 function settled<T>(res: PromiseSettledResult<unknown> | undefined): T | null {
 	if (res?.status !== 'fulfilled') return null;
@@ -40,7 +41,8 @@ export async function load({ fetch, parent }) {
 				api.GET('/api/documents/search', {
 					params: { query: { sort: 'UPDATED_AT', dir: 'DESC', size: 5 } }
 				}),
-				api.GET('/api/geschichten', { params: { query: { status: 'PUBLISHED', limit: 3 } } })
+				api.GET('/api/geschichten', { params: { query: { status: 'PUBLISHED', limit: 3 } } }),
+				api.GET('/api/tags/tree')
 			];
 			if (canBlogWrite) {
 				readerFetches.push(
@@ -48,14 +50,15 @@ export async function load({ fetch, parent }) {
 				);
 			}
 
-			const [statsRes, topPersonsRes, recentDocsRes, recentStoriesRes, draftsRes] =
+			const [statsRes, topPersonsRes, recentDocsRes, recentStoriesRes, tagTreeRes, draftsRes] =
 				await Promise.allSettled(readerFetches);
 
 			const readerStats = settled<StatsDTO>(statsRes);
 			const topPersons = settled<{ items: PersonSummaryDTO[] }>(topPersonsRes)?.items ?? [];
-			const searchData = settled<{ items: { document: Document }[] }>(recentDocsRes);
-			const recentDocs = searchData?.items.map((i) => i.document) ?? [];
+			const searchData = settled<{ items: DocumentListItem[] }>(recentDocsRes);
+			const recentDocs = searchData?.items ?? [];
 			const recentStories = settled<Geschichte[]>(recentStoriesRes) ?? [];
+			const tagTree = settled<TagTreeNodeDTO[]>(tagTreeRes) ?? [];
 			const drafts = settled<Geschichte[]>(draftsRes) ?? [];
 
 			return {
@@ -65,6 +68,7 @@ export async function load({ fetch, parent }) {
 				topPersons,
 				recentDocs,
 				recentStories,
+				tagTree,
 				drafts,
 				error: null as string | null
 			};
@@ -80,7 +84,8 @@ export async function load({ fetch, parent }) {
 			readyResult,
 			weeklyStatsResult,
 			incompleteResult,
-			incompleteCountResult
+			incompleteCountResult,
+			tagTreeResult
 		] = await Promise.allSettled([
 			api.GET('/api/stats'),
 			api.GET('/api/dashboard/resume'),
@@ -91,7 +96,8 @@ export async function load({ fetch, parent }) {
 			api.GET('/api/transcription/ready-to-read'),
 			api.GET('/api/transcription/weekly-stats'),
 			api.GET('/api/documents/incomplete', { params: { query: { size: 5 } } }),
-			api.GET('/api/documents/incomplete-count')
+			api.GET('/api/documents/incomplete-count'),
+			api.GET('/api/tags/tree')
 		]);
 
 		let stats: StatsDTO | null = null;
@@ -104,6 +110,7 @@ export async function load({ fetch, parent }) {
 		let weeklyStats: TranscriptionWeeklyStatsDTO | null = null;
 		let incompleteDocs: IncompleteDocumentDTO[] = [];
 		let incompleteTotal = 0;
+		let tagTree: TagTreeNodeDTO[] = [];
 
 		if (statsResult.status === 'fulfilled' && statsResult.value.response.ok) {
 			stats = statsResult.value.data ?? null;
@@ -135,6 +142,9 @@ export async function load({ fetch, parent }) {
 		if (incompleteCountResult.status === 'fulfilled' && incompleteCountResult.value.response.ok) {
 			incompleteTotal = (incompleteCountResult.value.data?.count as number | undefined) ?? 0;
 		}
+		if (tagTreeResult.status === 'fulfilled' && tagTreeResult.value.response.ok) {
+			tagTree = (tagTreeResult.value.data as TagTreeNodeDTO[]) ?? [];
+		}
 
 		return {
 			isReader: false as const,
@@ -148,6 +158,7 @@ export async function load({ fetch, parent }) {
 			weeklyStats,
 			incompleteDocs,
 			incompleteTotal,
+			tagTree,
 			error: null as string | null
 		};
 	} catch (e) {
@@ -167,8 +178,9 @@ export async function load({ fetch, parent }) {
 			incompleteTotal: 0,
 			readerStats: null,
 			topPersons: [] as PersonSummaryDTO[],
-			recentDocs: [] as Document[],
+			recentDocs: [] as DocumentListItem[],
 			recentStories: [] as Geschichte[],
+			tagTree: [] as TagTreeNodeDTO[],
 			drafts: [] as Geschichte[],
 			error: 'Daten konnten nicht geladen werden.' as string | null
 		};

frontend/src/routes/+page.svelte

@@ -10,6 +10,7 @@ import ReaderPersonChips from '$lib/shared/dashboard/ReaderPersonChips.svelte';
 import ReaderDraftsModule from '$lib/shared/dashboard/ReaderDraftsModule.svelte';
 import ReaderRecentDocs from '$lib/shared/dashboard/ReaderRecentDocs.svelte';
 import ReaderRecentStories from '$lib/shared/dashboard/ReaderRecentStories.svelte';
+import ThemenWidget from '$lib/shared/dashboard/ThemenWidget.svelte';
 import { m } from '$lib/paraglide/messages.js';
 
 let { data } = $props();
@@ -45,6 +46,8 @@ const greetingText = $derived.by(() => {
 
 			<ReaderPersonChips persons={data.topPersons ?? []} />
 
+			<ThemenWidget tags={data.tagTree ?? []} />
+
 			<div class="grid grid-cols-1 gap-1.5 sm:grid-cols-2">
 				<ReaderRecentDocs documents={data.recentDocs ?? []} />
 				<ReaderRecentStories stories={data.recentStories ?? []} />
@@ -56,36 +59,40 @@ const greetingText = $derived.by(() => {
 				<h1 class="font-serif text-[2rem] text-ink">{greetingText}</h1>
 			</div>
 		{/if}
-		<div class="grid grid-cols-1 gap-5 lg:grid-cols-[1fr_320px] lg:items-start">
-			<div class="flex flex-col gap-5">
-				<DashboardResumeStrip resumeDoc={data.resumeDoc ?? null} />
+		<div class="flex flex-col gap-5">
+			<DashboardResumeStrip resumeDoc={data.resumeDoc ?? null} />
 
-				<EnrichmentBlock
-					topDocs={data.incompleteDocs ?? []}
-					totalCount={data.incompleteTotal ?? 0}
-					bannerCount={bannerCount}
-					onBannerClose={() => (bannerCount = 0)}
-				/>
+			<ThemenWidget tags={data.tagTree ?? []} />
 
-				<section aria-label={m.dashboard_mission_caption()}>
-					<h2 class="mb-3 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
-						{m.dashboard_mission_caption()}
-					</h2>
-					<MissionControlStrip
-						segmentationDocs={data.segmentationDocs ?? []}
-						transcriptionDocs={data.transcriptionDocs ?? []}
-						readyDocs={data.readyDocs ?? []}
-						weeklyStats={data.weeklyStats ?? null}
+			<div class="grid grid-cols-1 gap-5 lg:grid-cols-[1fr_320px] lg:items-start">
+				<div class="flex flex-col gap-5">
+					<EnrichmentBlock
+						topDocs={data.incompleteDocs ?? []}
+						totalCount={data.incompleteTotal ?? 0}
+						bannerCount={bannerCount}
+						onBannerClose={() => (bannerCount = 0)}
 					/>
-				</section>
-			</div>
 
-			<div class="flex flex-col gap-5 lg:sticky lg:top-[80px]">
-				<DashboardFamilyPulse pulse={data.pulse ?? null} />
-				<DashboardActivityFeed feed={data.activityFeed ?? []} />
-				{#if data.canWrite}
-					<DropZone onUploadComplete={(count) => (bannerCount = count)} />
-				{/if}
+					<section aria-label={m.dashboard_mission_caption()}>
+						<h2 class="mb-3 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
+							{m.dashboard_mission_caption()}
+						</h2>
+						<MissionControlStrip
+							segmentationDocs={data.segmentationDocs ?? []}
+							transcriptionDocs={data.transcriptionDocs ?? []}
+							readyDocs={data.readyDocs ?? []}
+							weeklyStats={data.weeklyStats ?? null}
+						/>
+					</section>
+				</div>
+
+				<div class="flex flex-col gap-5 lg:sticky lg:top-[80px]">
+					<DashboardFamilyPulse pulse={data.pulse ?? null} />
+					<DashboardActivityFeed feed={data.activityFeed ?? []} />
+					{#if data.canWrite}
+						<DropZone onUploadComplete={(count) => (bannerCount = count)} />
+					{/if}
+				</div>
 			</div>
 		</div>
 	{/if}

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

@@ -108,7 +108,8 @@ describe('home page load — dashboard', () => {
 				data: { segmentationCount: 0, transcriptionCount: 0, readyCount: 0 }
 			}) // weekly-stats
 			.mockResolvedValueOnce({ response: { ok: true }, data: [] }) // incomplete
-			.mockResolvedValueOnce({ response: { ok: true }, data: { count: 0 } }); // incomplete-count
+			.mockResolvedValueOnce({ response: { ok: true }, data: { count: 0 } }) // incomplete-count
+			.mockResolvedValueOnce({ response: { ok: true }, data: [] }); // tags/tree
 		vi.mocked(createApiClient).mockReturnValue({ GET: mockGet } as ReturnType<
 			typeof createApiClient
 		>);
@@ -146,7 +147,8 @@ describe('home page load — dashboard', () => {
 				data: { segmentationCount: 0, transcriptionCount: 0, readyCount: 0 }
 			}) // weekly-stats
 			.mockResolvedValueOnce({ response: { ok: true }, data: [] }) // incomplete
-			.mockResolvedValueOnce({ response: { ok: true }, data: { count: 0 } }); // incomplete-count
+			.mockResolvedValueOnce({ response: { ok: true }, data: { count: 0 } }) // incomplete-count
+			.mockResolvedValueOnce({ response: { ok: true }, data: [] }); // tags/tree
 		vi.mocked(createApiClient).mockReturnValue({ GET: mockGet } as ReturnType<
 			typeof createApiClient
 		>);
@@ -394,6 +396,56 @@ describe('home page load — reader branch (isReader = !canWrite && !canAnnotate
 		expect(result.isReader).toBe(false);
 	});
 
+	it('maps search result items directly to recentDocs without wrapping in a .document property', async () => {
+		const searchItem = {
+			id: 'd1',
+			title: 'Liebesbrief',
+			originalFilename: 'letter.pdf',
+			completionPercentage: 80,
+			receivers: [],
+			tags: [],
+			contributors: [],
+			matchData: { titleOffsets: [], senderMatched: false },
+			createdAt: '2026-05-01T10:00:00Z',
+			updatedAt: '2026-05-10T08:00:00Z'
+		};
+		const mockGet = vi
+			.fn()
+			.mockResolvedValueOnce({ response: { ok: true, status: 200 }, data: [] }) // initial persons
+			.mockResolvedValueOnce({
+				response: { ok: true },
+				data: { totalDocuments: 1, totalPersons: 1 }
+			}) // stats
+			.mockResolvedValueOnce({ response: { ok: true }, data: [] }) // topPersons
+			.mockResolvedValueOnce({
+				response: { ok: true },
+				data: { items: [searchItem], totalElements: 1, pageNumber: 0, pageSize: 5, totalPages: 1 }
+			}) // search
+			.mockResolvedValueOnce({ response: { ok: true }, data: [] }) // stories
+			.mockResolvedValueOnce({ response: { ok: true }, data: [] }); // tags/tree
+		vi.mocked(createApiClient).mockReturnValue({ GET: mockGet } as ReturnType<
+			typeof createApiClient
+		>);
+
+		const result = await load({
+			url: makeUrl(),
+			request: new Request('http://localhost/'),
+			fetch: vi.fn() as unknown as typeof fetch,
+			parent: vi
+				.fn()
+				.mockResolvedValue({ canWrite: false, canAnnotate: false, canBlogWrite: false })
+		} as Parameters<typeof load>[0]);
+
+		expect(result.isReader).toBe(true);
+		if (result.isReader) {
+			expect(result.recentDocs).toHaveLength(1);
+			expect(result.recentDocs[0]).toBeDefined();
+			expect(result.recentDocs[0].id).toBe('d1');
+			expect(result.recentDocs[0].createdAt).toBe('2026-05-01T10:00:00Z');
+			expect(result.recentDocs[0].updatedAt).toBe('2026-05-10T08:00:00Z');
+		}
+	});
+
 	it('returns topPersons=[] when topPersons fetch fails, rest of data still loads', async () => {
 		const okStats = {
 			response: { ok: true, status: 200 },
@@ -409,7 +461,8 @@ describe('home page load — reader branch (isReader = !canWrite && !canAnnotate
 			.mockResolvedValueOnce(okStats)
 			.mockReturnValueOnce(failPersons)
 			.mockResolvedValueOnce(okSearch)
-			.mockResolvedValueOnce(okStories);
+			.mockResolvedValueOnce(okStories)
+			.mockResolvedValueOnce({ response: { ok: true, status: 200 }, data: [] }); // tags/tree
 		vi.mocked(createApiClient).mockReturnValue({ GET: mockGet } as ReturnType<
 			typeof createApiClient
 		>);

frontend/src/routes/themen/+page.server.ts

@@ -0,0 +1,12 @@
+import { error } from '@sveltejs/kit';
+import { createApiClient } from '$lib/shared/api.server';
+import type { components } from '$lib/generated/api';
+
+type TagTreeNodeDTO = components['schemas']['TagTreeNodeDTO'];
+
+export async function load({ fetch }: Parameters<import('./$types').PageServerLoad>[0]) {
+	const api = createApiClient(fetch);
+	const result = await api.GET('/api/tags/tree');
+	if (!result.response.ok) throw error(500, 'Themen konnten nicht geladen werden.');
+	return { tree: (result.data ?? []) as TagTreeNodeDTO[] };
+}

frontend/src/routes/themen/+page.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+import * as m from '$lib/paraglide/messages.js';
+import BackButton from '$lib/shared/primitives/BackButton.svelte';
+import { hasAnyDocuments } from '$lib/shared/utils/tagUtils';
+import type { components } from '$lib/generated/api';
+
+type TagTreeNodeDTO = components['schemas']['TagTreeNodeDTO'];
+
+const MAX_VISIBLE_CHILDREN = 5;
+
+let { data }: { data: { tree: TagTreeNodeDTO[] } } = $props();
+
+const visibleTree = $derived.by(() => data.tree.filter(hasAnyDocuments));
+</script>
+
+<svelte:head>
+	<title>{m.themen_widget_title()}</title>
+</svelte:head>
+
+<main class="mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8">
+	<div class="mb-6 flex items-center gap-3">
+		<BackButton />
+		<h1 class="font-serif text-2xl font-semibold text-ink">{m.themen_widget_title()}</h1>
+	</div>
+
+	{#if visibleTree.length === 0}
+		<p class="font-sans text-sm text-ink-3">{m.themen_leer()}</p>
+	{:else}
+		<div class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+			{#each visibleTree as tag (tag.id)}
+				{@const visibleChildren = (tag.children ?? []).filter(hasAnyDocuments)}
+				{@const shownChildren = visibleChildren.slice(0, MAX_VISIBLE_CHILDREN)}
+				{@const hiddenCount = visibleChildren.length - shownChildren.length}
+
+				<div class="overflow-hidden rounded-sm border border-line bg-surface shadow-sm">
+					<div
+						class="h-1.5 w-full flex-shrink-0"
+						aria-hidden="true"
+						style="background: var(--c-tag-{tag.color ?? 'slate'})"
+					></div>
+
+					<a
+						href="/documents?tag={encodeURIComponent(tag.name)}"
+						aria-label="{tag.name}{tag.documentCount > 0
+							? ', ' + m.themen_dokumente({ count: tag.documentCount })
+							: ''}"
+						class="flex min-h-[56px] items-center justify-between px-4 pt-4 pb-3 hover:bg-canvas focus-visible:ring-2 focus-visible:ring-brand-navy focus-visible:outline-none focus-visible:ring-inset"
+					>
+						<span class="font-serif text-base font-semibold text-ink">{tag.name}</span>
+						<span class="mr-1 ml-auto font-sans text-sm text-ink-3 tabular-nums">
+							{#if tag.documentCount > 0}{tag.documentCount}{/if}
+						</span>
+						<span aria-hidden="true" class="h-3.5 w-3.5 flex-shrink-0 text-brand-mint">›</span>
+					</a>
+
+					{#if shownChildren.length > 0}
+						<div class="mx-4 border-t border-line"></div>
+
+						{#each shownChildren as child (child.id)}
+							<a
+								href="/documents?tag={encodeURIComponent(child.name)}"
+								class="flex min-h-[44px] items-center justify-between px-4 py-2.5 hover:bg-canvas focus-visible:bg-canvas focus-visible:ring-2 focus-visible:ring-brand-navy focus-visible:outline-none focus-visible:ring-inset"
+							>
+								<span class="font-sans text-sm text-ink">{child.name}</span>
+								<span class="mr-1 ml-auto font-sans text-xs text-ink-3 tabular-nums">
+									{#if child.documentCount > 0}{child.documentCount}{/if}
+								</span>
+								<span aria-hidden="true" class="h-3 w-3 flex-shrink-0 text-brand-mint">›</span>
+							</a>
+						{/each}
+
+						{#if hiddenCount > 0}
+							<a
+								href="/documents?tag={encodeURIComponent(tag.name)}"
+								class="block min-h-[44px] px-4 py-2.5 font-sans text-sm text-ink-3 hover:bg-canvas hover:text-ink focus-visible:ring-2 focus-visible:ring-brand-navy focus-visible:outline-none focus-visible:ring-inset"
+							>
+								{m.themen_weitere({ count: hiddenCount })} →
+							</a>
+						{/if}
+					{/if}
+				</div>
+			{/each}
+		</div>
+	{/if}
+</main>

frontend/src/routes/themen/page.server.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+vi.mock('$lib/shared/api.server', () => ({
+	createApiClient: vi.fn(),
+	extractErrorCode: (e: unknown) => (e as { code?: string } | undefined)?.code
+}));
+
+import { createApiClient } from '$lib/shared/api.server';
+
+beforeEach(() => vi.clearAllMocks());
+
+function mockApiGet(ok: boolean, data: unknown) {
+	vi.mocked(createApiClient).mockReturnValue({
+		GET: vi.fn().mockResolvedValue({ response: { ok }, data })
+	} as ReturnType<typeof createApiClient>);
+}
+
+const makeTag = (name: string, documentCount = 0) => ({
+	id: 'id-' + name,
+	name,
+	documentCount,
+	children: []
+});
+
+describe('/themen +page.server load', () => {
+	function makeLoadEvent() {
+		return {
+			fetch: vi.fn() as unknown as typeof fetch,
+			request: new Request('http://localhost/themen'),
+			url: new URL('http://localhost/themen')
+		};
+	}
+
+	it('returns tag tree when API succeeds', async () => {
+		const tree = [makeTag('Briefe', 5), makeTag('Fotos', 3)];
+		mockApiGet(true, tree);
+
+		const { load } = await import('./+page.server');
+		const result = await load(makeLoadEvent());
+
+		expect(result.tree).toEqual(tree);
+	});
+
+	it('returns empty array when API returns empty list', async () => {
+		mockApiGet(true, []);
+
+		const { load } = await import('./+page.server');
+		const result = await load(makeLoadEvent());
+
+		expect(result.tree).toEqual([]);
+	});
+
+	it('throws 500 when API call fails', async () => {
+		mockApiGet(false, null);
+
+		const { load } = await import('./+page.server');
+
+		await expect(load(makeLoadEvent())).rejects.toMatchObject({ status: 500 });
+	});
+});

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

@@ -0,0 +1,57 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import ThemenPage from './+page.svelte';
+import type { components } from '$lib/generated/api';
+
+afterEach(() => {
+	cleanup();
+});
+
+type TagTreeNodeDTO = components['schemas']['TagTreeNodeDTO'];
+
+function makeTag(
+	name: string,
+	documentCount: number,
+	children: TagTreeNodeDTO[] = []
+): TagTreeNodeDTO {
+	return { id: 'id-' + name, name, documentCount, children };
+}
+
+describe('/themen +page', () => {
+	it('renders one card per visible root tag', async () => {
+		const tree = [makeTag('Briefe', 5), makeTag('Fotos', 3)];
+		render(ThemenPage, { data: { tree } });
+		expect(document.body.textContent).toContain('Briefe');
+		expect(document.body.textContent).toContain('Fotos');
+	});
+
+	it('does not render a tag with no documents in its subtree', async () => {
+		const tree = [makeTag('Briefe', 5), makeTag('Leer', 0)];
+		render(ThemenPage, { data: { tree } });
+		expect(document.body.textContent).not.toContain('Leer');
+	});
+
+	it('shows empty state when all tags filtered out', async () => {
+		render(ThemenPage, { data: { tree: [makeTag('Leer', 0)] } });
+		expect(document.body.textContent).toMatch(/Noch keine Themen/);
+	});
+
+	it('shows empty state when tree is empty', async () => {
+		render(ThemenPage, { data: { tree: [] } });
+		expect(document.body.textContent).toMatch(/Noch keine Themen/);
+	});
+
+	it('renders child tags for a root tag', async () => {
+		const tree = [makeTag('Briefe', 5, [makeTag('Brautbriefe', 3), makeTag('Kriegsbriefe', 2)])];
+		render(ThemenPage, { data: { tree } });
+		expect(document.body.textContent).toContain('Brautbriefe');
+		expect(document.body.textContent).toContain('Kriegsbriefe');
+	});
+
+	it('shows "+ N weitere" when a root tag has more than 5 children', async () => {
+		const children = Array.from({ length: 7 }, (_, i) => makeTag(`Kind${i}`, i + 1));
+		const tree = [makeTag('Briefe', 10, children)];
+		render(ThemenPage, { data: { tree } });
+		expect(document.body.textContent).toMatch(/\+\s*2\s*weitere/);
+	});
+});