implements page-numbers-plan

agents.md

@@ -90,10 +90,13 @@ src/
 │   │   └── zip-inflating.service.ts      # Async fflate wrapper
 │   ├── batch.ts                          # Sequential batch engine for multi-file tools
 │   ├── pdf-compression.ts                # Shared compression presets and rasterize pipeline
+│   ├── pdf-errors.ts                     # Shared encrypted-PDF detection and German messages
 │   ├── pdf-metadata.ts                   # PDF metadata inspection and cleaning (pdf-lib only)
-│   ├── pdf-overlay.ts                    # Shared PDF overlay positions and color parsing
+│   ├── pdf-overlay.ts                    # Shared overlay positions, preview CSS and color parsing
+│   ├── pdf-pagination.ts                 # Sheet-number labels and the pagination pipeline
 │   ├── pdf-processing.ts                 # Reusable PDF merge helper
-│   ├── pdf-thumbnails.ts                 # Managed pdfjs thumbnail loading and cleanup
+│   ├── pdf-text-overlay.ts               # Shared framed/rotated text overlay drawing
+│   ├── pdf-thumbnails.ts                 # Managed pdfjs thumbnails, on-demand page previews, cleanup
 │   ├── utils.ts                          # cn() and shared component utility types
 │   └── zip-processing.ts                 # Archive model, transforms, and PDF export
 └── routes/
@@ -104,7 +107,7 @@ src/
     ├── tools/
     │   ├── +layout.svelte                # Shared back-navigation shell
     │   ├── bea/+page.svelte              # Existing ZIP archive workflow
-    │   └── {merge,separate,stamp,watermark,encrypt,decrypt,compress,convert,rotate,metadata}/
+    │   └── {pagination,merge,separate,stamp,watermark,encrypt,decrypt,compress,convert,rotate,metadata}/
     ├── datenschutz/+page.svelte          # Privacy policy
     └── impressum/+page.svelte            # Imprint
 static/                                   # Public logo, footer art, PWA icons, and robots.txt
@@ -146,7 +149,13 @@ committed.
 ## Application flow and state
 
 - `/` is the toolbox hub. A beA ZIP or PDF dropped anywhere on that route is queued in memory and
-  forwarded to `/tools/bea`; the file is not uploaded or persisted.
+  forwarded to `/tools/bea`; the file is not uploaded or persisted. The same `queuePendingFiles` /
+  `takePendingFiles` handoff carries the merged PDF from `/tools/merge` to `/tools/pagination`.
+- `/tools/pagination` is a single-PDF tool: it renders one page at a time through
+  `loadPdfPageRenderer` (never the all-pages thumbnail array), composes every label with
+  `buildPaginationLabel` — the single source for both the live preview and the export — and stamps
+  all pages through `drawTextOverlay`. The page number is always on every page; the optional free
+  text (Aktenzeichen) follows its own “every page” / “first page only” scope.
 - `/tools/metadata` is a single-PDF inspection tool. `src/lib/pdf-metadata.ts` reads document
   properties with pdf-lib only (no rasterization), returns a discriminated `{ status: 'encrypted' }`
   result for password-protected files, and detects embedded-file markers by scanning raw bytes.
@@ -231,6 +240,13 @@ All case-file processing is intentionally local to the browser.
 - Page-set copies (separate/extract tools, PDF splitting) share
   `copyPagesToNewPdf(sourceBytes, pageIndexes)` in `src/lib/pdf-processing.ts` so the copy
   semantics cannot drift apart.
+- `src/lib/pdf-text-overlay.ts` owns text fitting, the rotated-box placement and the optional
+  `/Rotate` compensation. Stamp keeps `compensatePageRotation` off so its output does not change;
+  pagination turns it on so numbers stay at the visual position on rotated scans. Share it instead
+  of re-implementing overlay maths in a route.
+- `src/lib/pdf-thumbnails.ts` offers two loaders: `loadPdfDocument` (all thumbnails, for pickers and
+  page grids) and `loadPdfPageRenderer` (one page at a time, for long documents). Both revoke object
+  URLs and tear down the pdfjs loading task in `destroy()`.
 - `AttachmentPreview.svelte` dynamically loads pdfjs-dist in `onMount`, copies PDF bytes before
   rendering, and revokes object URLs during cleanup. Preserve those memory and data-integrity
   safeguards.
@@ -243,15 +259,15 @@ called in the browser.
 
 ## Batch processing pattern for single-PDF tools
 
-Tools that transform one PDF per run (compress, watermark, encrypt, …) are being retrofitted to
-accept multiple files. Follow the established compress retrofit when adding the pattern to another
-tool; see `plan/batch-processing-plan.md` for the full design.
+Tools that transform one PDF per run (compress, watermark, stamp, encrypt, decrypt) accept multiple
+files. Follow the established compress retrofit when adding the pattern to another tool; see
+`plan/done/batch-processing-plan.md` for the full design.
 
 - `src/lib/batch.ts` owns the engine: `createBatchItem(file)`, `runBatch(items, process, update,
 options?)` and `formatBytes`. `runBatch` processes strictly sequentially (one PDF in flight for
   memory safety), never throws — per-item failures are caught and written to the item as a German
-  error message — and consults the optional `shouldProcess` predicate so rows removed mid-run are
-  skipped.
+  error message (a string, or a formatter that can inspect the thrown error) — and consults the
+  optional `shouldProcess` predicate so rows removed mid-run are skipped.
 - `src/lib/components/BatchFileList.svelte` renders the rows: name, size, status chip
   (Wartet / Verarbeite… / Fertig ✓ / Fehler), per-row download, remove, and retry buttons with
   accessible names including the file name, a progress line (“Datei 3 von 7 wird verarbeitet…”), a
@@ -262,10 +278,11 @@ options?)` and `formatBytes`. `runBatch` processes strictly sequentially (one PD
   deduplicate by name + size), pass a `process(file)` callback that reads the current option state
   so option changes mid-run affect only subsequent files, and gate the run button on pending items.
   Files too large to rasterize (>100 MB) are marked as error rows immediately on selection instead
-  of blocking the batch.
-- Per-tool ZIP base names: compress uses `komprimiert`, watermark `wasserzeichen`, encrypt
-  `geschuetzt`, decrypt `entsperrt`. Choose an analogous German name per tool and cover the batch
-  flow with Playwright tests (multi-file ZIP contents, failure continuation, retry, removal).
+  of blocking the batch. Keep thumbnails, previews, and page-specific selection to a single dropped
+  file; multi-file runs apply the tool to every page of every file.
+- Per-tool ZIP base names: compress uses `komprimiert`, watermark `wasserzeichen`, stamp `stempel`,
+  encrypt `geschuetzt`, decrypt `entsperrt`. Choose an analogous German name per tool and cover the
+  batch flow with Playwright tests (multi-file ZIP contents, failure continuation, retry, removal).
 
 ## Svelte conventions