From 1e656d2db46bbd0a33aea0edd799c090ec9f22be Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Tue, 5 May 2026 14:01:39 +0200
Subject: [PATCH] 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>
---
 .../src/lib/components/MissionControlStrip.svelte  |  2 +-
 .../src/lib/document/BulkDocumentEditLayout.svelte |  2 +-
 .../src/lib/document/DocumentEditLayout.svelte     |  2 +-
 frontend/src/lib/document/DocumentViewer.svelte    |  2 +-
 .../annotation}/AnnotationEditOverlay.svelte       |  0
 .../AnnotationEditOverlay.svelte.test.ts           |  0
 .../annotation}/AnnotationLayer.svelte             |  0
 .../annotation}/AnnotationLayer.svelte.spec.ts     |  0
 .../annotation}/AnnotationLayer.svelte.test.ts     |  0
 .../annotation}/AnnotationShape.svelte             |  0
 .../annotation}/AnnotationShape.svelte.spec.ts     |  0
 .../annotation}/AnnotationShape.svelte.test.ts     |  0
 .../transcription}/TranscriptionBlock.svelte       |  4 ++--
 .../TranscriptionBlock.svelte.spec.ts              |  0
 .../TranscriptionBlock.test-host.svelte            |  0
 .../transcription}/TranscriptionColumn.svelte      |  2 +-
 .../TranscriptionColumn.svelte.spec.ts             |  0
 .../transcription}/TranscriptionEditView.svelte    |  8 ++++----
 .../TranscriptionEditView.svelte.spec.ts           |  0
 .../transcription}/TranscriptionPanelHeader.svelte |  2 +-
 .../TranscriptionPanelHeader.svelte.test.ts        |  0
 .../transcription}/TranscriptionReadView.svelte    |  4 ++--
 .../TranscriptionReadView.svelte.spec.ts           |  0
 .../TranscriptionReadView.svelte.test.ts           |  0
 .../transcription}/blockConflictMerge.spec.ts      |  0
 .../transcription}/blockConflictMerge.ts           |  0
 .../saveBlockWithConflictRetry.spec.ts             |  0
 .../transcription}/saveBlockWithConflictRetry.ts   |  5 ++++-
 .../transcription}/transcriptionMarkers.spec.ts    |  0
 .../transcription}/transcriptionMarkers.ts         |  0
 .../transcription}/useBlockAutoSave.svelte.test.ts |  2 +-
 .../transcription}/useBlockAutoSave.svelte.ts      |  0
 .../transcription}/useBlockDragDrop.svelte.test.ts |  2 +-
 .../transcription}/useBlockDragDrop.svelte.ts      |  0
 .../viewer}/PdfControls.svelte                     |  0
 .../viewer}/PdfControls.svelte.spec.ts             |  0
 .../viewer}/PdfViewer.svelte                       |  4 ++--
 .../viewer}/PdfViewer.svelte.spec.ts               |  0
 .../viewer}/useFileLoader.svelte.test.ts           |  2 +-
 .../viewer}/useFileLoader.svelte.ts                |  0
 .../viewer}/usePdfRenderer.svelte.test.ts          |  2 +-
 .../viewer}/usePdfRenderer.svelte.ts               |  0
 frontend/src/routes/documents/[id]/+page.svelte    | 14 ++++++++------
 43 files changed, 32 insertions(+), 27 deletions(-)
 rename frontend/src/lib/{components => document/annotation}/AnnotationEditOverlay.svelte (100%)
 rename frontend/src/lib/{components => document/annotation}/AnnotationEditOverlay.svelte.test.ts (100%)
 rename frontend/src/lib/{components => document/annotation}/AnnotationLayer.svelte (100%)
 rename frontend/src/lib/{components => document/annotation}/AnnotationLayer.svelte.spec.ts (100%)
 rename frontend/src/lib/{components => document/annotation}/AnnotationLayer.svelte.test.ts (100%)
 rename frontend/src/lib/{components => document/annotation}/AnnotationShape.svelte (100%)
 rename frontend/src/lib/{components => document/annotation}/AnnotationShape.svelte.spec.ts (100%)
 rename frontend/src/lib/{components => document/annotation}/AnnotationShape.svelte.test.ts (100%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionBlock.svelte (98%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionBlock.svelte.spec.ts (100%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionBlock.test-host.svelte (100%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionColumn.svelte (97%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionColumn.svelte.spec.ts (100%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionEditView.svelte (96%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionEditView.svelte.spec.ts (100%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionPanelHeader.svelte (97%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionPanelHeader.svelte.test.ts (100%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionReadView.svelte (98%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionReadView.svelte.spec.ts (100%)
 rename frontend/src/lib/{components => document/transcription}/TranscriptionReadView.svelte.test.ts (100%)
 rename frontend/src/lib/{utils => document/transcription}/blockConflictMerge.spec.ts (100%)
 rename frontend/src/lib/{utils => document/transcription}/blockConflictMerge.ts (100%)
 rename frontend/src/lib/{utils => document/transcription}/saveBlockWithConflictRetry.spec.ts (100%)
 rename frontend/src/lib/{utils => document/transcription}/saveBlockWithConflictRetry.ts (94%)
 rename frontend/src/lib/{utils => document/transcription}/transcriptionMarkers.spec.ts (100%)
 rename frontend/src/lib/{utils => document/transcription}/transcriptionMarkers.ts (100%)
 rename frontend/src/lib/{hooks/__tests__ => document/transcription}/useBlockAutoSave.svelte.test.ts (99%)
 rename frontend/src/lib/{hooks => document/transcription}/useBlockAutoSave.svelte.ts (100%)
 rename frontend/src/lib/{hooks/__tests__ => document/transcription}/useBlockDragDrop.svelte.test.ts (98%)
 rename frontend/src/lib/{hooks => document/transcription}/useBlockDragDrop.svelte.ts (100%)
 rename frontend/src/lib/{components => document/viewer}/PdfControls.svelte (100%)
 rename frontend/src/lib/{components => document/viewer}/PdfControls.svelte.spec.ts (100%)
 rename frontend/src/lib/{components => document/viewer}/PdfViewer.svelte (98%)
 rename frontend/src/lib/{components => document/viewer}/PdfViewer.svelte.spec.ts (100%)
 rename frontend/src/lib/{hooks/__tests__ => document/viewer}/useFileLoader.svelte.test.ts (97%)
 rename frontend/src/lib/{hooks => document/viewer}/useFileLoader.svelte.ts (100%)
 rename frontend/src/lib/{hooks/__tests__ => document/viewer}/usePdfRenderer.svelte.test.ts (96%)
 rename frontend/src/lib/{hooks => document/viewer}/usePdfRenderer.svelte.ts (100%)

diff --git a/frontend/src/lib/components/MissionControlStrip.svelte b/frontend/src/lib/components/MissionControlStrip.svelte
index 21122cd8..e2dd6402 100644
--- a/frontend/src/lib/components/MissionControlStrip.svelte
+++ b/frontend/src/lib/components/MissionControlStrip.svelte
@@ -2,7 +2,7 @@
 import * as m from '$lib/paraglide/messages.js';
 import type { components } from '$lib/generated/api';
 import SegmentationColumn from '$lib/document/SegmentationColumn.svelte';
-import TranscriptionColumn from './TranscriptionColumn.svelte';
+import TranscriptionColumn from '$lib/document/transcription/TranscriptionColumn.svelte';
 import ReadyColumn from '$lib/document/ReadyColumn.svelte';
 
 type TranscriptionQueueItemDTO = components['schemas']['TranscriptionQueueItemDTO'];
diff --git a/frontend/src/lib/document/BulkDocumentEditLayout.svelte b/frontend/src/lib/document/BulkDocumentEditLayout.svelte
index 63327edb..700e1eeb 100644
--- a/frontend/src/lib/document/BulkDocumentEditLayout.svelte
+++ b/frontend/src/lib/document/BulkDocumentEditLayout.svelte
@@ -13,7 +13,7 @@ import ScopeCard from './ScopeCard.svelte';
 import UploadSaveBar from './UploadSaveBar.svelte';
 import WhoWhenSection from './WhoWhenSection.svelte';
 import DescriptionSection from './DescriptionSection.svelte';
-import PdfViewer from '$lib/components/PdfViewer.svelte';
+import PdfViewer from '$lib/document/viewer/PdfViewer.svelte';
 import { bulkTitleFromFilename } from '$lib/document/filename';
 import type { Tag } from '$lib/components/TagInput.svelte';
 import type { components } from '$lib/generated/api';
diff --git a/frontend/src/lib/document/DocumentEditLayout.svelte b/frontend/src/lib/document/DocumentEditLayout.svelte
index 665bc4f9..b13754c4 100644
--- a/frontend/src/lib/document/DocumentEditLayout.svelte
+++ b/frontend/src/lib/document/DocumentEditLayout.svelte
@@ -3,7 +3,7 @@ import { enhance } from '$app/forms';
 import { invalidate } from '$app/navigation';
 import { onMount, onDestroy, untrack } from 'svelte';
 import type { Snippet } from 'svelte';
-import { createFileLoader } from '$lib/hooks/useFileLoader.svelte';
+import { createFileLoader } from '$lib/document/viewer/useFileLoader.svelte';
 import { m } from '$lib/paraglide/messages.js';
 import { countRequiredFilled } from '$lib/utils/requiredFields';
 import { validateFile } from '$lib/document/validateFile';
diff --git a/frontend/src/lib/document/DocumentViewer.svelte b/frontend/src/lib/document/DocumentViewer.svelte
index a3aa29a7..789a68d7 100644
--- a/frontend/src/lib/document/DocumentViewer.svelte
+++ b/frontend/src/lib/document/DocumentViewer.svelte
@@ -1,6 +1,6 @@
 <script lang="ts">
 import { m } from '$lib/paraglide/messages.js';
-import PdfViewer from '$lib/components/PdfViewer.svelte';
+import PdfViewer from '$lib/document/viewer/PdfViewer.svelte';
 
 type Doc = {
 	id: string;
diff --git a/frontend/src/lib/components/AnnotationEditOverlay.svelte b/frontend/src/lib/document/annotation/AnnotationEditOverlay.svelte
similarity index 100%
rename from frontend/src/lib/components/AnnotationEditOverlay.svelte
rename to frontend/src/lib/document/annotation/AnnotationEditOverlay.svelte
diff --git a/frontend/src/lib/components/AnnotationEditOverlay.svelte.test.ts b/frontend/src/lib/document/annotation/AnnotationEditOverlay.svelte.test.ts
similarity index 100%
rename from frontend/src/lib/components/AnnotationEditOverlay.svelte.test.ts
rename to frontend/src/lib/document/annotation/AnnotationEditOverlay.svelte.test.ts
diff --git a/frontend/src/lib/components/AnnotationLayer.svelte b/frontend/src/lib/document/annotation/AnnotationLayer.svelte
similarity index 100%
rename from frontend/src/lib/components/AnnotationLayer.svelte
rename to frontend/src/lib/document/annotation/AnnotationLayer.svelte
diff --git a/frontend/src/lib/components/AnnotationLayer.svelte.spec.ts b/frontend/src/lib/document/annotation/AnnotationLayer.svelte.spec.ts
similarity index 100%
rename from frontend/src/lib/components/AnnotationLayer.svelte.spec.ts
rename to frontend/src/lib/document/annotation/AnnotationLayer.svelte.spec.ts
diff --git a/frontend/src/lib/components/AnnotationLayer.svelte.test.ts b/frontend/src/lib/document/annotation/AnnotationLayer.svelte.test.ts
similarity index 100%
rename from frontend/src/lib/components/AnnotationLayer.svelte.test.ts
rename to frontend/src/lib/document/annotation/AnnotationLayer.svelte.test.ts
diff --git a/frontend/src/lib/components/AnnotationShape.svelte b/frontend/src/lib/document/annotation/AnnotationShape.svelte
similarity index 100%
rename from frontend/src/lib/components/AnnotationShape.svelte
rename to frontend/src/lib/document/annotation/AnnotationShape.svelte
diff --git a/frontend/src/lib/components/AnnotationShape.svelte.spec.ts b/frontend/src/lib/document/annotation/AnnotationShape.svelte.spec.ts
similarity index 100%
rename from frontend/src/lib/components/AnnotationShape.svelte.spec.ts
rename to frontend/src/lib/document/annotation/AnnotationShape.svelte.spec.ts
diff --git a/frontend/src/lib/components/AnnotationShape.svelte.test.ts b/frontend/src/lib/document/annotation/AnnotationShape.svelte.test.ts
similarity index 100%
rename from frontend/src/lib/components/AnnotationShape.svelte.test.ts
rename to frontend/src/lib/document/annotation/AnnotationShape.svelte.test.ts
diff --git a/frontend/src/lib/components/TranscriptionBlock.svelte b/frontend/src/lib/document/transcription/TranscriptionBlock.svelte
similarity index 98%
rename from frontend/src/lib/components/TranscriptionBlock.svelte
rename to frontend/src/lib/document/transcription/TranscriptionBlock.svelte
index 417c3fbe..5441fe57 100644
--- a/frontend/src/lib/components/TranscriptionBlock.svelte
+++ b/frontend/src/lib/document/transcription/TranscriptionBlock.svelte
@@ -1,8 +1,8 @@
 <script lang="ts">
 import { m } from '$lib/paraglide/messages.js';
 import { getConfirmService } from '$lib/services/confirm.svelte.js';
-import CommentThread from './CommentThread.svelte';
-import PersonMentionEditor from './PersonMentionEditor.svelte';
+import CommentThread from '$lib/components/CommentThread.svelte';
+import PersonMentionEditor from '$lib/components/PersonMentionEditor.svelte';
 import type { PersonMention } from '$lib/types';
 
 const { confirm } = getConfirmService();
diff --git a/frontend/src/lib/components/TranscriptionBlock.svelte.spec.ts b/frontend/src/lib/document/transcription/TranscriptionBlock.svelte.spec.ts
similarity index 100%
rename from frontend/src/lib/components/TranscriptionBlock.svelte.spec.ts
rename to frontend/src/lib/document/transcription/TranscriptionBlock.svelte.spec.ts
diff --git a/frontend/src/lib/components/TranscriptionBlock.test-host.svelte b/frontend/src/lib/document/transcription/TranscriptionBlock.test-host.svelte
similarity index 100%
rename from frontend/src/lib/components/TranscriptionBlock.test-host.svelte
rename to frontend/src/lib/document/transcription/TranscriptionBlock.test-host.svelte
diff --git a/frontend/src/lib/components/TranscriptionColumn.svelte b/frontend/src/lib/document/transcription/TranscriptionColumn.svelte
similarity index 97%
rename from frontend/src/lib/components/TranscriptionColumn.svelte
rename to frontend/src/lib/document/transcription/TranscriptionColumn.svelte
index 19b40950..5f3f38b7 100644
--- a/frontend/src/lib/components/TranscriptionColumn.svelte
+++ b/frontend/src/lib/document/transcription/TranscriptionColumn.svelte
@@ -3,7 +3,7 @@ import * as m from '$lib/paraglide/messages.js';
 import { getLocale } from '$lib/paraglide/runtime.js';
 import { formatMCDate } from '$lib/utils/date.js';
 import type { components } from '$lib/generated/api';
-import ContributorStack from './ContributorStack.svelte';
+import ContributorStack from '$lib/components/ContributorStack.svelte';
 
 type TranscriptionQueueItemDTO = components['schemas']['TranscriptionQueueItemDTO'];
 
diff --git a/frontend/src/lib/components/TranscriptionColumn.svelte.spec.ts b/frontend/src/lib/document/transcription/TranscriptionColumn.svelte.spec.ts
similarity index 100%
rename from frontend/src/lib/components/TranscriptionColumn.svelte.spec.ts
rename to frontend/src/lib/document/transcription/TranscriptionColumn.svelte.spec.ts
diff --git a/frontend/src/lib/components/TranscriptionEditView.svelte b/frontend/src/lib/document/transcription/TranscriptionEditView.svelte
similarity index 96%
rename from frontend/src/lib/components/TranscriptionEditView.svelte
rename to frontend/src/lib/document/transcription/TranscriptionEditView.svelte
index 64e97fef..149f8551 100644
--- a/frontend/src/lib/components/TranscriptionEditView.svelte
+++ b/frontend/src/lib/document/transcription/TranscriptionEditView.svelte
@@ -1,11 +1,11 @@
 <script lang="ts">
 import { m } from '$lib/paraglide/messages.js';
 import TranscriptionBlock from './TranscriptionBlock.svelte';
-import OcrTrigger from './OcrTrigger.svelte';
-import TranscribeCoachEmptyState from './TranscribeCoachEmptyState.svelte';
+import OcrTrigger from '$lib/components/OcrTrigger.svelte';
+import TranscribeCoachEmptyState from '$lib/components/TranscribeCoachEmptyState.svelte';
 import type { PersonMention, TranscriptionBlockData } from '$lib/types';
-import { createBlockAutoSave } from '$lib/hooks/useBlockAutoSave.svelte';
-import { createBlockDragDrop } from '$lib/hooks/useBlockDragDrop.svelte';
+import { createBlockAutoSave } from '$lib/document/transcription/useBlockAutoSave.svelte';
+import { createBlockDragDrop } from '$lib/document/transcription/useBlockDragDrop.svelte';
 
 type Props = {
 	documentId: string;
diff --git a/frontend/src/lib/components/TranscriptionEditView.svelte.spec.ts b/frontend/src/lib/document/transcription/TranscriptionEditView.svelte.spec.ts
similarity index 100%
rename from frontend/src/lib/components/TranscriptionEditView.svelte.spec.ts
rename to frontend/src/lib/document/transcription/TranscriptionEditView.svelte.spec.ts
diff --git a/frontend/src/lib/components/TranscriptionPanelHeader.svelte b/frontend/src/lib/document/transcription/TranscriptionPanelHeader.svelte
similarity index 97%
rename from frontend/src/lib/components/TranscriptionPanelHeader.svelte
rename to frontend/src/lib/document/transcription/TranscriptionPanelHeader.svelte
index 6bf40a5d..95c4b576 100644
--- a/frontend/src/lib/components/TranscriptionPanelHeader.svelte
+++ b/frontend/src/lib/document/transcription/TranscriptionPanelHeader.svelte
@@ -1,7 +1,7 @@
 <script lang="ts">
 import { m } from '$lib/paraglide/messages.js';
 import { getLocale } from '$lib/paraglide/runtime.js';
-import HelpPopover from './HelpPopover.svelte';
+import HelpPopover from '$lib/components/HelpPopover.svelte';
 
 type Props = {
 	mode: 'read' | 'edit';
diff --git a/frontend/src/lib/components/TranscriptionPanelHeader.svelte.test.ts b/frontend/src/lib/document/transcription/TranscriptionPanelHeader.svelte.test.ts
similarity index 100%
rename from frontend/src/lib/components/TranscriptionPanelHeader.svelte.test.ts
rename to frontend/src/lib/document/transcription/TranscriptionPanelHeader.svelte.test.ts
diff --git a/frontend/src/lib/components/TranscriptionReadView.svelte b/frontend/src/lib/document/transcription/TranscriptionReadView.svelte
similarity index 98%
rename from frontend/src/lib/components/TranscriptionReadView.svelte
rename to frontend/src/lib/document/transcription/TranscriptionReadView.svelte
index c800037a..a6c040eb 100644
--- a/frontend/src/lib/components/TranscriptionReadView.svelte
+++ b/frontend/src/lib/document/transcription/TranscriptionReadView.svelte
@@ -1,14 +1,14 @@
 <script lang="ts">
 import type { TranscriptionBlockData } from '$lib/types';
 import type { components } from '$lib/generated/api';
-import { splitByMarkers } from '$lib/utils/transcriptionMarkers';
+import { splitByMarkers } from '$lib/document/transcription/transcriptionMarkers';
 import {
 	renderTranscriptionBody,
 	type SafeHtml,
 	PERSON_MENTION_SELECTOR
 } from '$lib/utils/mention';
 import { computeHoverCardPosition } from '$lib/utils/hoverCardPosition';
-import PersonHoverCard from './PersonHoverCard.svelte';
+import PersonHoverCard from '$lib/components/PersonHoverCard.svelte';
 import type { HoverData, LoadState } from '$lib/types/personHoverCard';
 import { goto } from '$app/navigation';
 import { SvelteMap, SvelteSet } from 'svelte/reactivity';
diff --git a/frontend/src/lib/components/TranscriptionReadView.svelte.spec.ts b/frontend/src/lib/document/transcription/TranscriptionReadView.svelte.spec.ts
similarity index 100%
rename from frontend/src/lib/components/TranscriptionReadView.svelte.spec.ts
rename to frontend/src/lib/document/transcription/TranscriptionReadView.svelte.spec.ts
diff --git a/frontend/src/lib/components/TranscriptionReadView.svelte.test.ts b/frontend/src/lib/document/transcription/TranscriptionReadView.svelte.test.ts
similarity index 100%
rename from frontend/src/lib/components/TranscriptionReadView.svelte.test.ts
rename to frontend/src/lib/document/transcription/TranscriptionReadView.svelte.test.ts
diff --git a/frontend/src/lib/utils/blockConflictMerge.spec.ts b/frontend/src/lib/document/transcription/blockConflictMerge.spec.ts
similarity index 100%
rename from frontend/src/lib/utils/blockConflictMerge.spec.ts
rename to frontend/src/lib/document/transcription/blockConflictMerge.spec.ts
diff --git a/frontend/src/lib/utils/blockConflictMerge.ts b/frontend/src/lib/document/transcription/blockConflictMerge.ts
similarity index 100%
rename from frontend/src/lib/utils/blockConflictMerge.ts
rename to frontend/src/lib/document/transcription/blockConflictMerge.ts
diff --git a/frontend/src/lib/utils/saveBlockWithConflictRetry.spec.ts b/frontend/src/lib/document/transcription/saveBlockWithConflictRetry.spec.ts
similarity index 100%
rename from frontend/src/lib/utils/saveBlockWithConflictRetry.spec.ts
rename to frontend/src/lib/document/transcription/saveBlockWithConflictRetry.spec.ts
diff --git a/frontend/src/lib/utils/saveBlockWithConflictRetry.ts b/frontend/src/lib/document/transcription/saveBlockWithConflictRetry.ts
similarity index 94%
rename from frontend/src/lib/utils/saveBlockWithConflictRetry.ts
rename to frontend/src/lib/document/transcription/saveBlockWithConflictRetry.ts
index 4daeca50..44263bf1 100644
--- a/frontend/src/lib/utils/saveBlockWithConflictRetry.ts
+++ b/frontend/src/lib/document/transcription/saveBlockWithConflictRetry.ts
@@ -1,5 +1,8 @@
 import type { PersonMention, TranscriptionBlockData } from '$lib/types';
-import { BlockConflictResolvedError, mergeBlockOnConflict } from '$lib/utils/blockConflictMerge';
+import {
+	BlockConflictResolvedError,
+	mergeBlockOnConflict
+} from '$lib/document/transcription/blockConflictMerge';
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
diff --git a/frontend/src/lib/utils/transcriptionMarkers.spec.ts b/frontend/src/lib/document/transcription/transcriptionMarkers.spec.ts
similarity index 100%
rename from frontend/src/lib/utils/transcriptionMarkers.spec.ts
rename to frontend/src/lib/document/transcription/transcriptionMarkers.spec.ts
diff --git a/frontend/src/lib/utils/transcriptionMarkers.ts b/frontend/src/lib/document/transcription/transcriptionMarkers.ts
similarity index 100%
rename from frontend/src/lib/utils/transcriptionMarkers.ts
rename to frontend/src/lib/document/transcription/transcriptionMarkers.ts
diff --git a/frontend/src/lib/hooks/__tests__/useBlockAutoSave.svelte.test.ts b/frontend/src/lib/document/transcription/useBlockAutoSave.svelte.test.ts
similarity index 99%
rename from frontend/src/lib/hooks/__tests__/useBlockAutoSave.svelte.test.ts
rename to frontend/src/lib/document/transcription/useBlockAutoSave.svelte.test.ts
index f6a87a8f..90f95831 100644
--- a/frontend/src/lib/hooks/__tests__/useBlockAutoSave.svelte.test.ts
+++ b/frontend/src/lib/document/transcription/useBlockAutoSave.svelte.test.ts
@@ -6,7 +6,7 @@ const mockSaveFn =
 
 const NO_MENTIONS: PersonMention[] = [];
 
-const { createBlockAutoSave } = await import('../useBlockAutoSave.svelte');
+const { createBlockAutoSave } = await import('./useBlockAutoSave.svelte');
 
 describe('createBlockAutoSave', () => {
 	beforeEach(() => {
diff --git a/frontend/src/lib/hooks/useBlockAutoSave.svelte.ts b/frontend/src/lib/document/transcription/useBlockAutoSave.svelte.ts
similarity index 100%
rename from frontend/src/lib/hooks/useBlockAutoSave.svelte.ts
rename to frontend/src/lib/document/transcription/useBlockAutoSave.svelte.ts
diff --git a/frontend/src/lib/hooks/__tests__/useBlockDragDrop.svelte.test.ts b/frontend/src/lib/document/transcription/useBlockDragDrop.svelte.test.ts
similarity index 98%
rename from frontend/src/lib/hooks/__tests__/useBlockDragDrop.svelte.test.ts
rename to frontend/src/lib/document/transcription/useBlockDragDrop.svelte.test.ts
index 3e4adaa2..93b59862 100644
--- a/frontend/src/lib/hooks/__tests__/useBlockDragDrop.svelte.test.ts
+++ b/frontend/src/lib/document/transcription/useBlockDragDrop.svelte.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { createBlockDragDrop } from '../useBlockDragDrop.svelte';
+import { createBlockDragDrop } from './useBlockDragDrop.svelte';
 import type { TranscriptionBlockData } from '$lib/types';
 
 function makeBlock(id: string, sortOrder: number): TranscriptionBlockData {
diff --git a/frontend/src/lib/hooks/useBlockDragDrop.svelte.ts b/frontend/src/lib/document/transcription/useBlockDragDrop.svelte.ts
similarity index 100%
rename from frontend/src/lib/hooks/useBlockDragDrop.svelte.ts
rename to frontend/src/lib/document/transcription/useBlockDragDrop.svelte.ts
diff --git a/frontend/src/lib/components/PdfControls.svelte b/frontend/src/lib/document/viewer/PdfControls.svelte
similarity index 100%
rename from frontend/src/lib/components/PdfControls.svelte
rename to frontend/src/lib/document/viewer/PdfControls.svelte
diff --git a/frontend/src/lib/components/PdfControls.svelte.spec.ts b/frontend/src/lib/document/viewer/PdfControls.svelte.spec.ts
similarity index 100%
rename from frontend/src/lib/components/PdfControls.svelte.spec.ts
rename to frontend/src/lib/document/viewer/PdfControls.svelte.spec.ts
diff --git a/frontend/src/lib/components/PdfViewer.svelte b/frontend/src/lib/document/viewer/PdfViewer.svelte
similarity index 98%
rename from frontend/src/lib/components/PdfViewer.svelte
rename to frontend/src/lib/document/viewer/PdfViewer.svelte
index 7642b197..ecf8c971 100644
--- a/frontend/src/lib/components/PdfViewer.svelte
+++ b/frontend/src/lib/document/viewer/PdfViewer.svelte
@@ -1,8 +1,8 @@
 <script lang="ts">
 import { onMount, setContext } from 'svelte';
-import { createPdfRenderer } from '$lib/hooks/usePdfRenderer.svelte';
+import { createPdfRenderer } from '$lib/document/viewer/usePdfRenderer.svelte';
 import PdfControls from './PdfControls.svelte';
-import AnnotationLayer from './AnnotationLayer.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';
diff --git a/frontend/src/lib/components/PdfViewer.svelte.spec.ts b/frontend/src/lib/document/viewer/PdfViewer.svelte.spec.ts
similarity index 100%
rename from frontend/src/lib/components/PdfViewer.svelte.spec.ts
rename to frontend/src/lib/document/viewer/PdfViewer.svelte.spec.ts
diff --git a/frontend/src/lib/hooks/__tests__/useFileLoader.svelte.test.ts b/frontend/src/lib/document/viewer/useFileLoader.svelte.test.ts
similarity index 97%
rename from frontend/src/lib/hooks/__tests__/useFileLoader.svelte.test.ts
rename to frontend/src/lib/document/viewer/useFileLoader.svelte.test.ts
index 4dc4bec3..948dcbfa 100644
--- a/frontend/src/lib/hooks/__tests__/useFileLoader.svelte.test.ts
+++ b/frontend/src/lib/document/viewer/useFileLoader.svelte.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
-import { createFileLoader } from '../useFileLoader.svelte';
+import { createFileLoader } from './useFileLoader.svelte';
 
 const FAKE_URL = 'blob:fake-url';
 
diff --git a/frontend/src/lib/hooks/useFileLoader.svelte.ts b/frontend/src/lib/document/viewer/useFileLoader.svelte.ts
similarity index 100%
rename from frontend/src/lib/hooks/useFileLoader.svelte.ts
rename to frontend/src/lib/document/viewer/useFileLoader.svelte.ts
diff --git a/frontend/src/lib/hooks/__tests__/usePdfRenderer.svelte.test.ts b/frontend/src/lib/document/viewer/usePdfRenderer.svelte.test.ts
similarity index 96%
rename from frontend/src/lib/hooks/__tests__/usePdfRenderer.svelte.test.ts
rename to frontend/src/lib/document/viewer/usePdfRenderer.svelte.test.ts
index d36b5c66..aa7a5509 100644
--- a/frontend/src/lib/hooks/__tests__/usePdfRenderer.svelte.test.ts
+++ b/frontend/src/lib/document/viewer/usePdfRenderer.svelte.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { createPdfRenderer } from '../usePdfRenderer.svelte';
+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.
diff --git a/frontend/src/lib/hooks/usePdfRenderer.svelte.ts b/frontend/src/lib/document/viewer/usePdfRenderer.svelte.ts
similarity index 100%
rename from frontend/src/lib/hooks/usePdfRenderer.svelte.ts
rename to frontend/src/lib/document/viewer/usePdfRenderer.svelte.ts
diff --git a/frontend/src/routes/documents/[id]/+page.svelte b/frontend/src/routes/documents/[id]/+page.svelte
index e0811a14..3e88b95a 100644
--- a/frontend/src/routes/documents/[id]/+page.svelte
+++ b/frontend/src/routes/documents/[id]/+page.svelte
@@ -5,13 +5,13 @@ import { page } from '$app/state';
 import { replaceState } from '$app/navigation';
 import DocumentTopBar from '$lib/document/DocumentTopBar.svelte';
 import DocumentViewer from '$lib/document/DocumentViewer.svelte';
-import TranscriptionEditView from '$lib/components/TranscriptionEditView.svelte';
-import TranscriptionReadView from '$lib/components/TranscriptionReadView.svelte';
-import TranscriptionPanelHeader from '$lib/components/TranscriptionPanelHeader.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 type { TranscriptionBlockData } from '$lib/types';
 import { getErrorMessage } from '$lib/errors';
 import { translateOcrProgress } from '$lib/ocr/translateOcrProgress';
-import { createFileLoader } from '$lib/hooks/useFileLoader.svelte';
+import { createFileLoader } from '$lib/document/viewer/useFileLoader.svelte';
 import { scrollToCommentFromQuery } from '$lib/utils/deepLinkScroll';
 import { getConfirmService } from '$lib/services/confirm.svelte.js';
 
@@ -93,8 +93,10 @@ async function saveBlock(
 	text: string,
 	mentionedPersons: import('$lib/types').PersonMention[]
 ) {
-	const { saveBlockWithConflictRetry } = await import('$lib/utils/saveBlockWithConflictRetry');
-	const { BlockConflictResolvedError } = await import('$lib/utils/blockConflictMerge');
+	const { saveBlockWithConflictRetry } =
+		await import('$lib/document/transcription/saveBlockWithConflictRetry');
+	const { BlockConflictResolvedError } =
+		await import('$lib/document/transcription/blockConflictMerge');
 	try {
 		const updated = await saveBlockWithConflictRetry({
 			fetchImpl: fetch,