bea-edit/plan/done/page-numbers-plan.md

Plan: Paginierung — fortlaufende Blattnummern mit Aktenzeichen

Goal

Add a new tool „Paginieren“ (/tools/pagination) that stamps every page of one PDF with an ascending sheet number — the way authorities paginate a case file („Bl. 26“) — optionally combined with a static free text (e.g. an Aktenzeichen 123 Ja 60/26) that repeats on every page (default) or only on the first page. The same operation is offered as a follow-up action after „PDFs zusammenfügen“.

Context: mail thread with Nikolai Klute (26.09.2026 / 06.10.2026). Two clarifications shape this plan: pagination needs a simple free text next to the tool-generated number (no {0}/{1} template language), and that text should repeat „auf der ersten oder auf jeder Seite (Default)“.

Related: plan/done/stamp-plan.md already references this plan as page-numbers-plan.

---

Open decisions (defaults marked ✅)

D1 — Free-text model

• ✅ A. Static free text + tool-generated number. No placeholder syntax: the number is always produced by the tool, the free text is an optional label rendered with it. Directly matches Nikolai's answer („Einfach nur ein Text im Zusammenhang mit der Seitenzahl“).
• B. Template field (Seite {n} von {total}). Rejected for v1: more validation and support surface than the use case needs; {total} is not requested.

D2 — What repeats, what increments

• ✅ A. Two independent scopes. Page numbers always on every page (that is the point of pagination). The free text has its own scope: „Auf jeder Seite“ (default) or „Nur auf der ersten Seite“ — on page 2+ only the number remains.
• B. One shared scope (text scope also gates numbering). Rejected: a first-page-only pagination is not a thing.

D3 — Number format

• ✅ A. Select with four fixed formats — Bl. {n} (default), Seite {n}, S. {n}, {n}. Internally a prefix/suffix pair, so no user-visible template language, but „Bl.“ as the German-authority default. Free text is prepended as „{Text}, “.
• B. Free prefix/suffix inputs. More knobs, more invalid combinations.
• C. One free format string. Reopened D1.

D4 — Look and placement

• ✅ A. Restrained authority style: Helvetica, 11 pt (slider 8–18), black #1a1a1a, no frame, no rotation, default position unten mittig with 28 pt margin; the six other positions are selectable via the existing getPositionCoords presets.
• B. Reuse the stamp tool's framed/bold look. Wrong semantics: a page number is a neutral mark, not an authority stamp.

D5 — Files per run

• ✅ A. Exactly one PDF. A Gesamtdokument is paginated in one pass; multi-document cases are handled by „PDFs zusammenfügen“ + handoff. Continuous numbering across several dropped files is a different (and silently wrong) semantic.
• B. Batch with the same start number per file. Ambiguous for users; deferred until requested.

D6 — Integration into „PDF Zusammenfügen“

• ✅ A. Handoff to the pagination tool. Merge writes the merged bytes into a File, queues it via the existing in-memory file handoff, and navigates to /tools/pagination, where options and live preview live. One implementation of pagination, preview included.
• B. Inline pagination options on the merge page. Duplicated UI and no preview.

D7 — Preview renderer

• ✅ A. On-demand single-page renderer. A paginated case file can have hundreds of pages; loadPdfDocument rasterises every page up front. A new loadPdfPageRenderer(bytes) renders only the visible page and disposes the previous one.
• B. Reuse loadPdfDocument (all thumbnails). Unacceptable for long documents.

---

UX

Route /tools/pagination, title „Paginieren“, registry entry after stamp:

{
  slug: 'pagination',
  title: 'Paginieren',
  description: 'Versehen Sie alle Seiten mit fortlaufenden Blattnummern und optional einem Aktenzeichen.',
  icon: 'list-ordered'
}

Page layout (stamp tool as the pattern: options left, preview right):

• FileDropzone (single PDF) — „PDF zum Paginieren hinzufügen“; shows the file name and page count after loading.
• Options card
  • Startnummer (number input, default 1, min 1, max 99999) with hint „Seite 1 erhält diese Nummer.“
  • Zusatztext (optional) — e.g. Aktenzeichen, maxlength="60", placeholder „z. B. 123 Ja 60/26“, plus radio/checkbox „Auf jeder Seite“ (default) / „Nur auf der ersten Seite“.
  • Zahlenformat select: Bl. {n}, Seite {n}, S. {n}, {n}.
  • Position select (default „Unten mittig“), Schriftgröße slider 8–18 pt (default 11).
  • Live example line: 123 Ja 60/26, Bl. 26.
• Preview card — the current page rendered at reading size with an absolutely positioned overlay (same technique as the stamp preview), page counter „Seite 3 von 42“, prev/next buttons and a „Springe zu Seite“ number input (long documents). The overlay shows the number that page will actually receive (start + pageIndex). Label it „Annäherung an die Ausgabe im PDF“.
• Primary action „Paginieren & herunterladen“ → {base}_paginiert.pdf. Options are read at click time, so the button can be pressed again after changing settings.
• Errors: encrypted PDF → the shared German hint pointing to „Passwort entfernen“; text too long for a page → German error instead of silent clipping.

Technical approach

Shared text overlay (src/lib/pdf-text-overlay.ts)

Extract the reusable parts of src/routes/tools/stamp/+page.svelte into a module used by stamp, pagination and exhibit numbering:

export type TextOverlayOptions = {
	font: PDFFont;
	text: string;
	size: number;
	color: RGB;
	position: OverlayPosition;
	margin?: number;
	padding?: number;
	framed?: boolean;
	borderWidth?: number;
	rotation?: number; // degrees
	minSize?: number; // shrink floor before throwing
	compensatePageRotation?: boolean; // default false; new tools set true
};

export const drawTextOverlay = (page: PDFPage, options: TextOverlayOptions) => void;

• Owns fit-to-page shrinking (loop down to minSize), the rotated placement maths already present in the stamp route (getRotatedStampPlacement), optional border, and the text draw.
• The stamp route is rewired to call it with framed: true, rotation: value and its bold font; behaviour must stay identical (guard: tests/e2e/stamp.spec.ts).
• compensatePageRotation maps bottom-center on a /Rotate 90 scan to the correct user-space anchor and counter-rotates the text. Stamp keeps false so its output does not change.
• Move isEncryptedPdfError / the encrypted-PDF message into src/lib/pdf-errors.ts so all three tools share one wording.

Pagination

const numberText = `${formatPrefix}${startNumber + pageIndex}${formatSuffix}`;
const textVisible = textScope === 'all' || pageIndex === 0;
const line = textVisible && freeText.trim() ? `${freeText.trim()}, ${numberText}` : numberText;

for (const [pageIndex, page] of pdfDoc.getPages().entries()) {
	drawTextOverlay(page, {
		font,
		text: line,
		size,
		color: parseHexColor('#1a1a1a'),
		position,
		margin: 28,
		compensatePageRotation: true
	});
}

• Embed one StandardFonts.Helvetica per document, save, name ${base}_paginiert.pdf.
• Page count comes from pdfjs (numPages) for the preview and from pdf-lib for processing; both are cheap, no full rasterisation.
• Renderer: extend src/lib/pdf-thumbnails.ts with loadPdfPageRenderer(bytes): Promise<{ pageCount, render(pageNumber), destroy() }>; render builds the canvas from the requested page's own viewport (mixed page sizes stay correct), revokes the previous object URL, and destroy tears down the pdfjs loading task. Reused by the exhibit tool's page-1 preview.

Merge integration

• Generalise src/lib/pending-files.ts: queueZipFiles / takeQueuedZipFiles become queuePendingFiles / takePendingFiles (same behaviour; update src/routes/+page.svelte and src/routes/tools/bea/+page.svelte).
• src/routes/tools/merge/+page.svelte: keep „PDFs zusammenfügen“ (direct download) and add „Zusammenfügen & paginieren“, which merges, wraps the bytes in new File([bytes], 'zusammengefuegt.pdf', { type: 'application/pdf' }), queues it and calls goto('/tools/pagination'). Keep the change minimal — the page still uses older styling tokens; do not restyle it in this task.
• The pagination route consumes takePendingFiles() in onMount, accepts the first PDF and ignores anything else defensively.

Registry and docs

• src/lib/tools.ts + iconMap in src/routes/+page.svelte (ListOrdered).
• agents.md: new route, shared overlay/error helpers, renderer, pending-file naming, merge handoff.

Files changed

• src/routes/tools/pagination/+page.svelte — new route.
• src/lib/pdf-text-overlay.ts, src/lib/pdf-errors.ts — extracted shared helpers.
• src/routes/tools/stamp/+page.svelte — use the shared helpers (no behaviour change).
• src/lib/pdf-thumbnails.ts — add loadPdfPageRenderer.
• src/lib/pending-files.ts, src/routes/+page.svelte, src/routes/tools/bea/+page.svelte — generic pending-file naming.
• src/routes/tools/merge/+page.svelte — handoff button.
• src/lib/tools.ts, src/routes/+page.svelte — registry + icon map.
• tests/e2e/pagination.spec.ts, tests/e2e/merge.spec.ts — new/updated specs.
• agents.md — structure and flow documentation.

Implementation phases

1. Extract pdf-text-overlay.ts + pdf-errors.ts, rewire stamp, keep stamp.spec.ts green.
2. Add loadPdfPageRenderer and use it for the preview.
3. Build the pagination route (options, live preview, export, errors).
4. Merge handoff + generic pending files.
5. Registry/icon/docs.
6. Playwright coverage + command gauntlet.

Verification

• 3-page PDF, start 26, text 123 Ja 60/26, all pages → each page's content stream contains 123 Ja 60/26, Bl. 26/27/28; page count and page order preserved; download named akte_paginiert.pdf.
• First-page-only text → page 1 contains the Aktenzeichen, page 2 contains Bl. 2 but not the Aktenzeichen; the original page content is preserved on every page.
• Formats Seite {n} / {n} and empty free text → expected strings.
• Preview: navigating to page 2 shows Bl. 27 (start 26); changing the start number updates the preview before export.
• Rotated input (createPreRotatedPdf) → number appears at the visual bottom-center (test asserts the draw coordinates in the content stream or compares stream text plus position).
• Merge: two PDFs (1 + 2 pages) → „Zusammenfügen & paginieren“ lands on /tools/pagination with a 3-page document; running produces continuous Bl. 1…3.
• Encrypted PDF → German error, no download.
• pnpm check, targeted pnpm test:e2e, pnpm build, Prettier on touched files.

Risks

• Long documents: never call loadPdfDocument here; one page in memory at a time. The preview navigation must not leak object URLs or pdfjs tasks.
• Text length on narrow pages: fit-to-page shrinks to minSize; below that, fail with a German message rather than clipping.
• Unsupported characters: StandardFonts use WinAnsi; validate the free text (e.g. no emoji) and show a German hint instead of a pdf-lib save error.
• Rotated pages: compensation is new logic; if the mapping turns out unreliable, ship v1 with a visible warning for rotated pages instead of silently misplaced numbers.
• Preview fidelity: browser font metrics differ slightly from pdf-lib; the panel is labelled as an approximation.

Out of scope

• Placeholder templates ({total}, Roman numerals, ranges) and numbering only selected pages.
• Multiple files per run with continuous numbering (use merge first).
• Persisted pagination settings.
• Automatic pagination inside the beA archive export.