From 419b784f9cf757852c310dedfdb291229a54dc36 Mon Sep 17 00:00:00 2001
From: Fluory <florian.hein.sh@web.de>
Date: Mon, 28 Sep 2026 18:21:11 +0200
Subject: [PATCH 1/4] build(deps): add pdfjs-dist to show the original PDF page
 in review (#74)

The review screen shall show the cited PDF page with the stored bounding
box highlighted. pdf.js renders the original in the browser from the
existing tenant-checked document route: no new route, no public URL, no
third-party request, no extra load on the stateless AI service.
Apache-2.0, pinned; loaded lazily only when a PDF source is shown.
Decision and rejected options: ADR-0002.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/decisions/ADR-0002-pdf-page-view.md |  51 +++++++++
 docs/decisions/INDEX.md                  |   1 +
 package.json                             |   1 +
 pnpm-lock.yaml                           | 129 +++++++++++++++++++++++
 4 files changed, 182 insertions(+)
 create mode 100644 docs/decisions/ADR-0002-pdf-page-view.md

diff --git a/docs/decisions/ADR-0002-pdf-page-view.md b/docs/decisions/ADR-0002-pdf-page-view.md
new file mode 100644
index 0000000..3a1d7aa
--- /dev/null
+++ b/docs/decisions/ADR-0002-pdf-page-view.md
@@ -0,0 +1,51 @@
+# ADR-0002 · Original PDF page in the review screen: pdf.js in the browser
+
+- **Status:** Accepted – decided by the orchestrator on 2026-09-28 in #74
+- **Date:** 2026-09-28
+- **Context issue:** #74 (showcase review 2026-09-27, P1 item 2; epic #19)
+- **Relates to:** ADR-0001 D5 (originals only through the tenant-checked route), D8 (grounding, stored bounding boxes)
+
+## Context
+
+The review screen shows a value's source as text in reading order with the cited segment marked
+(#8, #25). For PDFs the AI service already stores the cited segment's page and bounding box
+(`PdfLocator.bbox`, PDF points, origin top-left); #8 left the rendered view as "decision needed".
+The showcase review asked for the original page beside the values so a visitor sees within a minute
+that every value can be checked against the original.
+
+Constraints: originals are read only through `GET /api/documents/:id` (tenant-checked, private
+bucket, no public URLs); no third-party requests from the review screen; the AI service stays
+stateless and never gets storage credentials (D8); the web app runs on Vercel Hobby (D11).
+
+## Options
+
+| Option | + | − |
+|---|---|---|
+| **A · pdf.js (`pdfjs-dist`) in the browser** | renders the exact original from the existing route; bbox → overlay is a percentage of the page; no server cost; Apache-2.0; widely used, maintained by Mozilla | new dependency (~35 MB unpacked in `node_modules`, the page loads it lazily); a worker file must be served by the app |
+| B · server-side page image (pdfium in the AI service or a Node renderer) | no PDF code in the browser | the AI service would need the original bytes again per view or storage access (breaks D8 statelessness) or the web runtime needs a native renderer; extra CPU per page view; images must be cached and tenant-scoped |
+| C · the browser's own PDF viewer (`<iframe>` / `#page=`) | no dependency | no reliable way to highlight a region; the route answers `content-disposition: attachment`; viewer differs per browser |
+
+## Decision
+
+**Option A.** The review page loads `pdfjs-dist` lazily in a client component, fetches the original
+through `GET /api/documents/:id` (same origin, the session cookie – no new route, no public URL),
+renders the cited page to a canvas and lays the stored bounding box over it as a percentage of the
+page size. The pdf.js worker is served from the app's own build output (`new URL(…, import.meta.url)`),
+never from a CDN. `isEvalSupported: false`. The text source view stays below the page: it is the
+accessible equivalent of the canvas, and the only view for mail, XLSX, DOCX and PDFs inside an
+Outlook message (the route serves the `.msg`, not the attachment).
+
+Verified: docling's boxes are in the displayed page's space – for a page with `/Rotate 90` they are
+already rotated – so the default pdf.js viewport (which applies `/Rotate`) needs no extra rotation.
+
+## Consequences
+
+- One new runtime dependency, pinned; `pnpm audit` covers it in `verify`.
+- The review page's JavaScript grows only when a PDF source is shown (dynamic import).
+- A PDF the renderer cannot open falls back to the text view with a note – the review never depends on it.
+
+## Re-evaluate when
+
+- a customer needs PDFs inside `.msg` attachments rendered (needs an attachment download route), or
+- a strict Content-Security-Policy is introduced (worker and canvas rules), or
+- `pdfjs-dist` has an unpatched advisory that `pnpm audit` reports.
diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md
index 0f225b6..5cc3059 100644
--- a/docs/decisions/INDEX.md
+++ b/docs/decisions/INDEX.md
@@ -6,3 +6,4 @@ A dated amendment decided by the orchestrator is appended to the decision it cha
 | ADR | Date | Title | Status |
 |---|---|---|---|
 | [ADR-0001](ADR-0001-pilot-architecture.md) | 2026-09-22 | Pilot architecture baseline (D1–D11) | Accepted; amended 2026-09-24 (D11: Supabase instead of Neon + R2) |
+| [ADR-0002](ADR-0002-pdf-page-view.md) | 2026-09-28 | Original PDF page in the review screen: pdf.js in the browser | Accepted (orchestrator, #74) |
diff --git a/package.json b/package.json
index b1d7006..8682f2a 100644
--- a/package.json
+++ b/package.json
@@ -38,6 +38,7 @@
     "better-auth": "1.7.5",
     "drizzle-orm": "0.45.3",
     "next": "16.3.6",
+    "pdfjs-dist": "6.3.289",
     "pg": "8.23.0",
     "pg-boss": "12.33.6",
     "pino": "10.3.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index cf50eae..87866ba 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -29,6 +29,9 @@ importers:
       next:
         specifier: 16.3.6
         version: 16.3.6(@babel/core@7.29.7)(@playwright/test@1.63.0)(@types/node@24.13.6)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)
+      pdfjs-dist:
+        specifier: 6.3.289
+        version: 6.3.289
       pg:
         specifier: 8.23.0
         version: 8.23.0
@@ -1007,6 +1010,76 @@ packages:
   '@jridgewell/trace-mapping@0.3.31':
     resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
 
+  '@napi-rs/canvas-android-arm64@1.0.9':
+    resolution: {integrity: sha512-4LGXk2/0HVzE29K8SzML5WubgCp++B1FH3qgl35XmSZE+lLdr6P9VRQEnZ0MCLZMTSuJP41yyhtoiVNEuvrTIA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [android]
+
+  '@napi-rs/canvas-darwin-arm64@1.0.9':
+    resolution: {integrity: sha512-YNdfLBzY0W/Pep9fo2L6RmoNlNksnn05LRnX66W63R3ij58S25QOTcjdtEt2v8+PnCESzqZsYzUo+QPeIR44NA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@napi-rs/canvas-darwin-x64@1.0.9':
+    resolution: {integrity: sha512-ceZQSknTEcy3dOXoekv59LTCkXjvnLsq+VW5PeNNDHEPQbRS5Ervkm1EaDa7WLAjiYWMLuSQTRTHao1dEX4prg==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@napi-rs/canvas-linux-arm-gnueabihf@1.0.9':
+    resolution: {integrity: sha512-XhfI0Wwv4llhd6nnWDtY3kQKjq0r+y1i91PlJlJI24ag2U9WrnwbG1qS3+fDLEyouwEVFchiKkTEHozK+5iUNA==}
+    engines: {node: '>= 10'}
+    cpu: [arm]
+    os: [linux]
+
+  '@napi-rs/canvas-linux-arm64-gnu@1.0.9':
+    resolution: {integrity: sha512-012oiYtKaE7i9oxc8q7nraT7kDOpLcaCmFLzVe9Ty34RHDdoDzbWLrVh827CNxYh/EADX1eSikA3ymLjo/nNuw==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@napi-rs/canvas-linux-arm64-musl@1.0.9':
+    resolution: {integrity: sha512-Ls5UWYFFn63casTZEczbeyEg3vRDRkv9lscuGwfchtY5yLLQhgOB8SN4YGxmfJ5vTaBwZ2YUxBS3NtmjJmFXdA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@napi-rs/canvas-linux-riscv64-gnu@1.0.9':
+    resolution: {integrity: sha512-hLKEGxV7ZiRHqndePTokgDMdBlo/rDfzg7P4p4QIv9pUhuYobnu3R2NIFLCRghG0nwfo+s2sw+c1xZFeCmEAsw==}
+    engines: {node: '>= 10'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@napi-rs/canvas-linux-x64-gnu@1.0.9':
+    resolution: {integrity: sha512-6kaz3w0QMy77PDWk6rJ1ksIihdad3qzEyX2o2oGT8GwCaypfT5mhjr8buOO5hstyLxcWXDScuz56RsINLtBPIQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@napi-rs/canvas-linux-x64-musl@1.0.9':
+    resolution: {integrity: sha512-xrGvmS3v55hmZ86ls/kBLVNMUTYio3f6Ik0DireemG994VfPAwiA3ZXA0Uf1bByctkB3NQ1Sfb+H5bkdUnnzfQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@napi-rs/canvas-win32-arm64-msvc@1.0.9':
+    resolution: {integrity: sha512-yjmVS3ArZeRVCP7jqbPq4rpZa/BhTeI7ELE2XqJg3snICQBDevLZyArxswHkiTnT34KRic33/4fLirrHI+SY8A==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@napi-rs/canvas-win32-x64-msvc@1.0.9':
+    resolution: {integrity: sha512-QlSYQdMQslB81nlABo9wNfQ6npFhE7/O+saCZdqVGueGanyRk4jCogD5EwQenfP3kIq9e+mm6GreQBjX5MrA8g==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@napi-rs/canvas@1.0.9':
+    resolution: {integrity: sha512-QviPdJImDi/jMAvBfqaw+19BndMd/sizXVW3NnpMd3VJGz++QXkOHcP9kWR/smHG0hNjHeyuHFyrx/5lD0oNcQ==}
+    engines: {node: '>= 10'}
+
   '@napi-rs/wasm-runtime@1.2.4':
     resolution: {integrity: sha512-AJxoUD2/15ESHbvpcyjU274nsAPLuOtPHCk0vKJM5pj//Fg/B1FXNWjPnXTT9PymCYYiHo4zPj0ZomXBKhoy7g==}
     engines: {node: ^20.19.0 || ^22.13.0 || >=23.5.0}
@@ -2722,6 +2795,10 @@ packages:
   path-parse@1.0.7:
     resolution: {integrity: sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==}
 
+  pdfjs-dist@6.3.289:
+    resolution: {integrity: sha512-ZHjSVpDa3D6izMq8/04lvkhkATUmL9px6ChPaXc1k6nU2Mrhlg1/7F0bdUqCwUjw3NsPTfPZsMDUU6ZIcRaeQw==}
+    engines: {node: '>=22.13.0 || >=24'}
+
   pg-boss@12.33.6:
     resolution: {integrity: sha512-kVGyVSFyG2xa5hn0TN1286PeTtkIVwTbIvGeVo2kme/vSkXrdcuaiXfcggID1cSHY7QG6k2CwNYRsbP7bVJeHg==}
     engines: {node: '>=22.12.0'}
@@ -4138,6 +4215,54 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.6.0
 
+  '@napi-rs/canvas-android-arm64@1.0.9':
+    optional: true
+
+  '@napi-rs/canvas-darwin-arm64@1.0.9':
+    optional: true
+
+  '@napi-rs/canvas-darwin-x64@1.0.9':
+    optional: true
+
+  '@napi-rs/canvas-linux-arm-gnueabihf@1.0.9':
+    optional: true
+
+  '@napi-rs/canvas-linux-arm64-gnu@1.0.9':
+    optional: true
+
+  '@napi-rs/canvas-linux-arm64-musl@1.0.9':
+    optional: true
+
+  '@napi-rs/canvas-linux-riscv64-gnu@1.0.9':
+    optional: true
+
+  '@napi-rs/canvas-linux-x64-gnu@1.0.9':
+    optional: true
+
+  '@napi-rs/canvas-linux-x64-musl@1.0.9':
+    optional: true
+
+  '@napi-rs/canvas-win32-arm64-msvc@1.0.9':
+    optional: true
+
+  '@napi-rs/canvas-win32-x64-msvc@1.0.9':
+    optional: true
+
+  '@napi-rs/canvas@1.0.9':
+    optionalDependencies:
+      '@napi-rs/canvas-android-arm64': 1.0.9
+      '@napi-rs/canvas-darwin-arm64': 1.0.9
+      '@napi-rs/canvas-darwin-x64': 1.0.9
+      '@napi-rs/canvas-linux-arm-gnueabihf': 1.0.9
+      '@napi-rs/canvas-linux-arm64-gnu': 1.0.9
+      '@napi-rs/canvas-linux-arm64-musl': 1.0.9
+      '@napi-rs/canvas-linux-riscv64-gnu': 1.0.9
+      '@napi-rs/canvas-linux-x64-gnu': 1.0.9
+      '@napi-rs/canvas-linux-x64-musl': 1.0.9
+      '@napi-rs/canvas-win32-arm64-msvc': 1.0.9
+      '@napi-rs/canvas-win32-x64-msvc': 1.0.9
+    optional: true
+
   '@napi-rs/wasm-runtime@1.2.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)':
     dependencies:
       '@emnapi/core': 1.10.0
@@ -5890,6 +6015,10 @@ snapshots:
 
   path-parse@1.0.7: {}
 
+  pdfjs-dist@6.3.289:
+    optionalDependencies:
+      '@napi-rs/canvas': 1.0.9
+
   pg-boss@12.33.6:
     dependencies:
       cron-parser: 5.10.1

From c355b49361080ca856ef57615458c8d7a360ce22 Mon Sep 17 00:00:00 2001
From: Fluory <florian.hein.sh@web.de>
Date: Mon, 28 Sep 2026 18:31:51 +0200
Subject: [PATCH 2/4] feat(review): original PDF page beside the values with
 the cited box highlighted

- source view carries the cited segment's page and box for a PDF document
  itself (not for a PDF inside an Outlook message: the route serves the .msg)
- client component renders that page with pdf.js from the tenant-checked
  document route, magnified around the highlight, "Ganze Seite" toggle;
  falls back to the text view when the page cannot be rendered
- uncertain, missing and unverified values say why in plain language

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/decisions/ADR-0002-pdf-page-view.md   |   3 +-
 src/app/requests/[id]/page.tsx             |   7 +
 src/app/requests/[id]/pdf-overlay.test.ts  |  25 ++++
 src/app/requests/[id]/pdf-overlay.ts       |  29 +++++
 src/app/requests/[id]/pdf-page.tsx         | 141 +++++++++++++++++++++
 src/app/requests/[id]/reason-label.test.ts |  22 ++++
 src/app/requests/[id]/reason-label.ts      |  30 +++++
 src/app/requests/[id]/review-parts.tsx     |   9 +-
 src/app/review.css                         |  70 ++++++++++
 src/features/review/index.ts               |   2 +-
 src/features/review/source-view.test.ts    |  39 ++++++
 src/features/review/source-view.ts         |  30 ++++-
 12 files changed, 401 insertions(+), 6 deletions(-)
 create mode 100644 src/app/requests/[id]/pdf-overlay.test.ts
 create mode 100644 src/app/requests/[id]/pdf-overlay.ts
 create mode 100644 src/app/requests/[id]/pdf-page.tsx
 create mode 100644 src/app/requests/[id]/reason-label.test.ts
 create mode 100644 src/app/requests/[id]/reason-label.ts

diff --git a/docs/decisions/ADR-0002-pdf-page-view.md b/docs/decisions/ADR-0002-pdf-page-view.md
index 3a1d7aa..0655758 100644
--- a/docs/decisions/ADR-0002-pdf-page-view.md
+++ b/docs/decisions/ADR-0002-pdf-page-view.md
@@ -31,7 +31,8 @@ stateless and never gets storage credentials (D8); the web app runs on Vercel Ho
 through `GET /api/documents/:id` (same origin, the session cookie – no new route, no public URL),
 renders the cited page to a canvas and lays the stored bounding box over it as a percentage of the
 page size. The pdf.js worker is served from the app's own build output (`new URL(…, import.meta.url)`),
-never from a CDN. `isEvalSupported: false`. The text source view stays below the page: it is the
+never from a CDN. XFA forms stay off; pdf.js 6 evaluates no code from a PDF (no `eval` or
+`new Function` in the build) and its scripting sandbox is never loaded. The text source view stays below the page: it is the
 accessible equivalent of the canvas, and the only view for mail, XLSX, DOCX and PDFs inside an
 Outlook message (the route serves the `.msg`, not the attachment).
 
diff --git a/src/app/requests/[id]/page.tsx b/src/app/requests/[id]/page.tsx
index 56e237c..5bac4c2 100644
--- a/src/app/requests/[id]/page.tsx
+++ b/src/app/requests/[id]/page.tsx
@@ -8,6 +8,7 @@ import { requestRowView } from "../row-view";
 import { SAMPLE_EXPLANATION, SAMPLE_LABEL } from "../sample-label";
 import { StatusPill } from "../status-pill";
 import { DONE_MESSAGES, ERROR_MESSAGES, messageFor } from "./messages";
+import { reasonText } from "./reason-label";
 import { displayValue } from "./value-label";
 import { approveAction, confirmNotDuplicateAction, correctFieldAction, rejectAction, rejectAsDuplicateAction } from "./actions";
 import { DocumentList, needsAttention, Source, STATUS_LABEL, StatusBadge } from "./review-parts";
@@ -180,6 +181,7 @@ export default async function RequestPage({
                           <td className="nowrap">
                             <StatusBadge status={field.reviewStatus} />
                             {field.corrected && <div className="field-hint">erkannt: {STATUS_LABEL[field.status]}</div>}
+                            {reasonText(field) && <div className="field-hint field-reason">{reasonText(field)}</div>}
                           </td>
                           <td className="source-col">{field.source ? <Link href={fieldHref(field)}>Quelle anzeigen</Link> : <span className="muted">–</span>}</td>
                           {inReview && (
@@ -276,6 +278,11 @@ export default async function RequestPage({
                   <strong data-testid={selected.itemIndex === null ? undefined : "selected-item-value"}>{displayValue(selected) ?? "–"}</strong>
                   <StatusBadge status={selected.reviewStatus} />
                 </div>
+                {reasonText(selected) && (
+                  <p className="field-reason" data-testid="selected-reason">
+                    {reasonText(selected)}
+                  </p>
+                )}
                 {selected.corrected && (
                   <p className="field-hint">
                     erkannt: {displayValue({ key: selected.key, value: selected.extractedValue }) ?? "–"} ({STATUS_LABEL[selected.status]})
diff --git a/src/app/requests/[id]/pdf-overlay.test.ts b/src/app/requests/[id]/pdf-overlay.test.ts
new file mode 100644
index 0000000..b7f891b
--- /dev/null
+++ b/src/app/requests/[id]/pdf-overlay.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { overlayOf } from "./pdf-overlay";
+
+// The highlight on the rendered page (#74): the stored box as a share of the page, so it scales with the canvas.
+const a4 = { width: 595, height: 842 };
+
+describe("overlayOf", () => {
+  it("places the box as percentages of the page, with a small margin around the text", () => {
+    expect(overlayOf({ l: 56, t: 278.82, r: 205.49, b: 288.07 }, a4)).toEqual({ left: 9.08, top: 32.88, width: 25.8, height: 1.57 });
+  });
+
+  it("keeps a box at the page edge inside the page", () => {
+    expect(overlayOf({ l: 0, t: 0, r: 595, b: 20 }, a4)).toEqual({ left: 0, top: 0, width: 100, height: 2.61 });
+  });
+
+  it("uses the displayed page – a rotated page is simply wider than high", () => {
+    expect(overlayOf({ l: 783.1, t: 56, r: 796.05, b: 239.6 }, { width: 842, height: 595 })).toEqual({ left: 92.77, top: 9.08, width: 2.01, height: 31.53 });
+  });
+
+  it("has no overlay for a box outside the page or a page without size", () => {
+    expect(overlayOf({ l: 700, t: 10, r: 750, b: 20 }, a4)).toBeNull();
+    expect(overlayOf({ l: 10, t: 900, r: 50, b: 920 }, a4)).toBeNull();
+    expect(overlayOf({ l: 10, t: 10, r: 50, b: 20 }, { width: 0, height: 842 })).toBeNull();
+  });
+});
diff --git a/src/app/requests/[id]/pdf-overlay.ts b/src/app/requests/[id]/pdf-overlay.ts
new file mode 100644
index 0000000..2966389
--- /dev/null
+++ b/src/app/requests/[id]/pdf-overlay.ts
@@ -0,0 +1,29 @@
+import type { PageRegion } from "@/features/review";
+
+// The highlight on the rendered PDF page (#74): the stored box as a share of the page, so it scales with
+// the canvas. docling's boxes are in the displayed page's space – already rotated for `/Rotate` – which is
+// also pdf.js's default viewport (ADR-0002): no rotation here.
+export interface Overlay {
+  /** Percent of the page width or height. */
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/** Margin around the text in PDF points, so the highlight does not touch the glyphs. */
+const MARGIN = 2;
+
+const clamp = (value: number, max: number) => Math.min(Math.max(value, 0), max);
+const percent = (value: number, of: number) => Math.round((value / of) * 10_000) / 100;
+
+/** Null for a page without size or a box outside the page. */
+export function overlayOf(bbox: PageRegion["bbox"], page: { width: number; height: number }): Overlay | null {
+  if (!(page.width > 0 && page.height > 0)) return null;
+  const left = clamp(bbox.l - MARGIN, page.width);
+  const right = clamp(bbox.r + MARGIN, page.width);
+  const top = clamp(bbox.t - MARGIN, page.height);
+  const bottom = clamp(bbox.b + MARGIN, page.height);
+  if (right <= left || bottom <= top) return null;
+  return { left: percent(left, page.width), top: percent(top, page.height), width: percent(right - left, page.width), height: percent(bottom - top, page.height) };
+}
diff --git a/src/app/requests/[id]/pdf-page.tsx b/src/app/requests/[id]/pdf-page.tsx
new file mode 100644
index 0000000..8b79417
--- /dev/null
+++ b/src/app/requests/[id]/pdf-page.tsx
@@ -0,0 +1,141 @@
+"use client";
+
+import { useEffect, useId, useRef, useState } from "react";
+import type { PageRegion } from "@/features/review";
+import { overlayOf } from "./pdf-overlay";
+
+// The original PDF page beside the values, with the cited box highlighted (#74, ADR-0002). pdf.js loads
+// only here, in the browser, and only when a PDF source is shown. The original comes from the
+// tenant-checked document route with the session cookie – no other request leaves the page. The text
+// source view below stays the accessible equivalent of the canvas.
+
+type Pdfjs = typeof import("pdfjs-dist");
+type PdfDocument = Awaited<ReturnType<Pdfjs["getDocument"]>["promise"]>;
+
+let pdfjs: Promise<Pdfjs> | undefined;
+function loadPdfjs(): Promise<Pdfjs> {
+  pdfjs ??= import("pdfjs-dist").then((module) => {
+    // The worker is part of the app's own build output, never a CDN.
+    module.GlobalWorkerOptions.workerSrc = new URL("pdfjs-dist/build/pdf.worker.min.mjs", import.meta.url).toString();
+    return module;
+  });
+  return pdfjs;
+}
+
+// One download per document while the page is open: choosing another value renders from memory.
+const documents = new Map<string, Promise<PdfDocument>>();
+function openDocument(documentId: string): Promise<PdfDocument> {
+  let document = documents.get(documentId);
+  if (!document) {
+    document = loadPdfjs().then(async (module) => {
+      const response = await fetch(`/api/documents/${documentId}`, { credentials: "same-origin" });
+      if (!response.ok) throw new Error(`document request failed: ${response.status}`);
+      const data = new Uint8Array(await response.arrayBuffer());
+      // No XFA forms; pdf.js 6 evaluates no code from a PDF, and its scripting sandbox is never loaded.
+      return module.getDocument({ data, enableXfa: false }).promise;
+    });
+    document.catch(() => documents.delete(documentId));
+    documents.set(documentId, document);
+  }
+  return document;
+}
+
+/** CSS pixels per PDF point in the magnified view: 10 pt text reads like 13 px. */
+const MAGNIFIED = 1.35;
+
+interface Outcome {
+  key: string;
+  /** Page size in PDF points (displayed page, i.e. after `/Rotate`); absent when rendering failed. */
+  size?: { width: number; height: number };
+}
+
+export function PdfPage({ documentId, region, label }: { documentId: string; region: PageRegion; label: string }) {
+  const captionId = useId();
+  const frame = useRef<HTMLDivElement>(null);
+  const canvas = useRef<HTMLCanvasElement>(null);
+  const highlight = useRef<HTMLDivElement>(null);
+  const [wholePage, setWholePage] = useState(false);
+  const [outcome, setOutcome] = useState<Outcome | null>(null);
+  const key = `${documentId}#${region.page}#${wholePage ? "page" : "magnified"}`;
+
+  useEffect(() => {
+    let cancelled = false;
+    let task: { cancel(): void } | undefined;
+    openDocument(documentId)
+      .then((pdf) => pdf.getPage(region.page))
+      .then(async (page) => {
+        const target = canvas.current;
+        const box = frame.current;
+        if (cancelled || !target || !box) return;
+        const size = page.getViewport({ scale: 1 });
+        const scale = wholePage ? box.clientWidth / size.width : MAGNIFIED;
+        // Drawn at device resolution, shown at CSS size: sharp on high-density screens.
+        const viewport = page.getViewport({ scale: scale * (window.devicePixelRatio || 1) });
+        target.width = Math.floor(viewport.width);
+        target.height = Math.floor(viewport.height);
+        target.style.width = `${Math.floor(size.width * scale)}px`;
+        target.style.height = `${Math.floor(size.height * scale)}px`;
+        const rendering = page.render({ canvas: target, viewport });
+        task = rendering;
+        await rendering.promise;
+        if (!cancelled) setOutcome({ key, size: { width: size.width, height: size.height } });
+      })
+      .catch(() => {
+        if (!cancelled) setOutcome({ key });
+      });
+    return () => {
+      cancelled = true;
+      task?.cancel();
+    };
+  }, [documentId, region.page, wholePage, key]);
+
+  const current = outcome?.key === key ? outcome : null;
+  const state = current === null ? "loading" : current.size ? "rendered" : "failed";
+  const overlay = current?.size ? overlayOf(region.bbox, current.size) : null;
+  const overlayKey = overlay && `${key}:${overlay.left}:${overlay.top}:${overlay.width}:${overlay.height}`;
+
+  // The cited place in the middle of the frame – the frame scrolls, never the page.
+  useEffect(() => {
+    const box = frame.current;
+    const target = highlight.current;
+    if (!overlayKey || !box || !target) return;
+    box.scrollTo({ left: target.offsetLeft + target.offsetWidth / 2 - box.clientWidth / 2, top: target.offsetTop + target.offsetHeight / 2 - box.clientHeight / 2 });
+  }, [overlayKey]);
+
+  if (state === "failed") {
+    return (
+      <p className="field-hint" data-testid="pdf-page" data-state="failed">
+        Die Originalseite lässt sich hier nicht anzeigen – die Fundstelle steht unten als Text.
+      </p>
+    );
+  }
+  return (
+    <figure className="pdf-page" data-testid="pdf-page" data-state={state}>
+      <div className="pdf-bar">
+        <figcaption id={captionId}>Original, Seite {region.page}</figcaption>
+        <button type="button" className="btn-small" aria-pressed={wholePage} onClick={() => setWholePage((value) => !value)}>
+          Ganze Seite
+        </button>
+      </div>
+      {/* Focusable, so the scrollable frame works by keyboard too. */}
+      <div ref={frame} className={wholePage ? "pdf-frame whole" : "pdf-frame"} tabIndex={0} aria-labelledby={captionId}>
+        <div className="pdf-sheet">
+          <canvas ref={canvas} role="img" aria-label={label} />
+          {overlay && (
+            <div
+              ref={highlight}
+              className="pdf-highlight"
+              data-testid="pdf-highlight"
+              style={{ left: `${overlay.left}%`, top: `${overlay.top}%`, width: `${overlay.width}%`, height: `${overlay.height}%` }}
+            />
+          )}
+        </div>
+        {state === "loading" && (
+          <p className="pdf-status" role="status">
+            Originalseite wird geladen …
+          </p>
+        )}
+      </div>
+    </figure>
+  );
+}
diff --git a/src/app/requests/[id]/reason-label.test.ts b/src/app/requests/[id]/reason-label.test.ts
new file mode 100644
index 0000000..236c2d0
--- /dev/null
+++ b/src/app/requests/[id]/reason-label.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { reasonText } from "./reason-label";
+
+// Why a value needs a look, in plain language (#74).
+describe("reasonText", () => {
+  it("names the verifier's reason", () => {
+    expect(reasonText({ reviewStatus: "uncertain", reason: "calendar_week_only" })).toBe("Kalenderwoche ohne Datum – bitte das genaue Datum klären.");
+    expect(reasonText({ reviewStatus: "unverified", reason: "quote_not_in_segment" })).toBe("Zitat nicht in der Quelle gefunden.");
+    expect(reasonText({ reviewStatus: "uncertain", reason: "ocr_only" })).toBe("Nur per Texterkennung aus einem Scan gelesen – bitte mit dem Original vergleichen.");
+  });
+
+  it("falls back to a sentence per status when the reason is absent or unknown", () => {
+    expect(reasonText({ reviewStatus: "missing", reason: null })).toBe("In den Unterlagen nicht gefunden.");
+    expect(reasonText({ reviewStatus: "uncertain", reason: null })).toBe("Die KI war sich bei diesem Wert nicht sicher.");
+    expect(reasonText({ reviewStatus: "unverified", reason: "something_new" })).toBe("Der Wert ließ sich an keiner Fundstelle bestätigen.");
+  });
+
+  it("says nothing for a confirmed or corrected value", () => {
+    expect(reasonText({ reviewStatus: "found", reason: null })).toBeNull();
+    expect(reasonText({ reviewStatus: "corrected", reason: "calendar_week_only" })).toBeNull();
+  });
+});
diff --git a/src/app/requests/[id]/reason-label.ts b/src/app/requests/[id]/reason-label.ts
new file mode 100644
index 0000000..b8e4ba6
--- /dev/null
+++ b/src/app/requests/[id]/reason-label.ts
@@ -0,0 +1,30 @@
+import type { FieldResult } from "@/features/extraction";
+import type { ReviewStatus } from "@/features/review";
+
+// Why a value needs a look, in plain language (#74). The reasons are the AI service's grounding verifier's
+// (contract `FieldResult.reason`); the record type makes a new contract reason a type error here.
+const REASON: Record<NonNullable<FieldResult["reason"]>, string> = {
+  missing_with_value: "Als fehlend gemeldet, aber mit einem Wert – widersprüchlich.",
+  no_value: "Als gefunden gemeldet, aber ohne Wert.",
+  no_evidence: "Keine Fundstelle angegeben.",
+  unknown_segment: "Die angegebene Fundstelle gibt es in der Quelle nicht.",
+  empty_quote: "Die Fundstelle enthält kein Zitat.",
+  quote_not_in_segment: "Zitat nicht in der Quelle gefunden.",
+  value_not_in_quote: "Der Wert steht nicht im zitierten Text.",
+  ambiguous_quote: "Die Fundstelle nennt mehrere Daten – bitte prüfen, welches gemeint ist.",
+  calendar_week_only: "Kalenderwoche ohne Datum – bitte das genaue Datum klären.",
+  ocr_only: "Nur per Texterkennung aus einem Scan gelesen – bitte mit dem Original vergleichen.",
+};
+
+const BY_STATUS: Partial<Record<ReviewStatus, string>> = {
+  uncertain: "Die KI war sich bei diesem Wert nicht sicher.",
+  missing: "In den Unterlagen nicht gefunden.",
+  unverified: "Der Wert ließ sich an keiner Fundstelle bestätigen.",
+};
+
+/** For an uncertain, missing or unverified value; null for a confirmed or corrected one. */
+export function reasonText(field: { reviewStatus: ReviewStatus; reason: string | null }): string | null {
+  const fallback = BY_STATUS[field.reviewStatus];
+  if (fallback === undefined) return null;
+  return field.reason !== null && Object.hasOwn(REASON, field.reason) ? REASON[field.reason as keyof typeof REASON] : fallback;
+}
diff --git a/src/app/requests/[id]/review-parts.tsx b/src/app/requests/[id]/review-parts.tsx
index e0c343f..0d02d76 100644
--- a/src/app/requests/[id]/review-parts.tsx
+++ b/src/app/requests/[id]/review-parts.tsx
@@ -1,4 +1,5 @@
 import type { ReviewField, ReviewStatus, ReviewView } from "@/features/review";
+import { PdfPage } from "./pdf-page";
 
 // Presentational parts of the review page (#8, #23, #25), styled after design prototype A (#52).
 
@@ -32,7 +33,10 @@ export function StatusBadge({ status }: { status: ReviewStatus }) {
   );
 }
 
-/** Source of the selected value: document, heading and the cited lines with the value marked. */
+/**
+ * Source of the selected value: document, heading, for a PDF document the original page with the cited box
+ * (#74), and the cited lines with the value marked – the text stays the accessible equivalent of the page.
+ */
 export function Source({ field }: { field: ReviewField }) {
   if (!field.source) return <p className="muted">Für diesen Wert gibt es keine Fundstelle.</p>;
   const { source } = field;
@@ -50,6 +54,9 @@ export function Source({ field }: { field: ReviewField }) {
         </p>
       )}
       {field.corrected && <p className="field-hint">Fundstelle des erkannten Werts „{field.extractedValue ?? "–"}“ – der aktuelle Wert wurde manuell korrigiert.</p>}
+      {source.region && (
+        <PdfPage documentId={source.documentId} region={source.region} label={`Seite ${source.region.page} von ${source.filename}, Fundstelle markiert`} />
+      )}
       <ol className="source-lines">
         {source.lines.map((line) => (
           <li key={line.segmentId} className={line.cited ? "cited" : undefined} aria-current={line.cited ? "true" : undefined}>
diff --git a/src/app/review.css b/src/app/review.css
index 7ea38ee..cf39670 100644
--- a/src/app/review.css
+++ b/src/app/review.css
@@ -272,6 +272,76 @@ td.attention .item-cell {
 .line-text {
   word-break: break-word;
 }
+/* Why a value needs a look (#74) – wraps even inside the nowrap status cell. */
+.field-reason {
+  margin: 0;
+  font-size: 12.5px;
+  color: var(--warn-text);
+  white-space: normal;
+  text-wrap: pretty;
+}
+.fields-table .field-reason {
+  min-width: 160px;
+  max-width: 240px;
+}
+
+/* Original PDF page with the cited box (#74, ADR-0002) */
+.pdf-page {
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.pdf-bar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+  color: var(--muted);
+}
+.pdf-frame {
+  position: relative;
+  max-height: 320px;
+  overflow: auto;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--grey-bg);
+}
+.pdf-frame.whole {
+  max-height: none;
+}
+.pdf-frame:focus-visible {
+  outline: 2px solid var(--brand);
+  outline-offset: 2px;
+}
+.pdf-sheet {
+  position: relative;
+  width: fit-content;
+  background: #fff;
+}
+.pdf-sheet canvas {
+  display: block;
+}
+.pdf-highlight {
+  position: absolute;
+  border: 2px solid var(--warn-line);
+  border-radius: 2px;
+  background: color-mix(in srgb, var(--mark) 35%, transparent);
+  pointer-events: none;
+}
+.pdf-status {
+  margin: 0;
+  padding: 24px 12px;
+  font-size: 12.5px;
+  color: var(--muted);
+}
+@media (forced-colors: active) {
+  .pdf-highlight {
+    border-color: Highlight;
+    background: none;
+  }
+}
 mark {
   background: var(--mark);
   color: var(--text);
diff --git a/src/features/review/index.ts b/src/features/review/index.ts
index 231d120..9df4ae0 100644
--- a/src/features/review/index.ts
+++ b/src/features/review/index.ts
@@ -21,5 +21,5 @@ export {
   type ReviewLineItem,
   type ReviewView,
 } from "./review";
-export { buildSourceView, type SourceLine, type SourceView } from "./source-view";
+export { buildSourceView, type PageRegion, type SourceLine, type SourceView } from "./source-view";
 export { summarizeReview, type ReviewSummary } from "./summary";
diff --git a/src/features/review/source-view.test.ts b/src/features/review/source-view.test.ts
index 0e8726c..3f0e385 100644
--- a/src/features/review/source-view.test.ts
+++ b/src/features/review/source-view.test.ts
@@ -118,3 +118,42 @@ describe("buildSourceView – where a value comes from", () => {
   });
 });
 
+describe("buildSourceView – the place on the rendered PDF page (#74)", () => {
+  const onPage = (page: unknown, bbox: unknown): StoredSegment[] => [
+    { segmentId: "p2-26", position: 0, text: "Gewünschter Liefertermin: KW 48", locator: { kind: "pdf", page, bbox, coordOrigin: "TOPLEFT" } },
+  ];
+  const evidence = { segmentId: "p2-26", quote: "KW 48" };
+
+  it("carries page and box of the cited segment of a PDF document", () => {
+    const view = buildSourceView(onPage(2, { l: 56, t: 278.82, r: 205.49, b: 288.07 }), evidence);
+
+    expect(view?.region).toEqual({ page: 2, bbox: { l: 56, t: 278.82, r: 205.49, b: 288.07 } });
+  });
+
+  it("has none for a mail, a PDF inside an Outlook message (the route serves the .msg) or a box that is not one", () => {
+    expect(buildSourceView(mail, { segmentId: "b2", quote: "KW 42" })?.region).toBeNull();
+    const inMsg: StoredSegment[] = [
+      {
+        segmentId: "m1",
+        position: 0,
+        text: "KW 48",
+        locator: { kind: "msg", part: "attachment", line: null, header: null, attachment: { index: 0, name: "liste.pdf" }, inner: { kind: "pdf", page: 1, bbox: { l: 1, t: 1, r: 9, b: 9 } } },
+      },
+    ];
+    expect(buildSourceView(inMsg, { segmentId: "m1", quote: "KW 48" })?.region).toBeNull();
+
+    const box = { l: 56, t: 278, r: 205, b: 288 };
+    for (const [page, bbox] of [
+      [2, undefined],
+      [2, { ...box, r: 56 }],
+      [2, { ...box, b: 278 }],
+      [2, { ...box, l: "56" }],
+      [2, { ...box, t: Number.NaN }],
+      [0, box],
+      [1.5, box],
+      ["2", box],
+    ] as const) {
+      expect(buildSourceView(onPage(page, bbox), evidence)?.region, JSON.stringify({ page, bbox })).toBeNull();
+    }
+  });
+});
diff --git a/src/features/review/source-view.ts b/src/features/review/source-view.ts
index 283f1da..6df33e5 100644
--- a/src/features/review/source-view.ts
+++ b/src/features/review/source-view.ts
@@ -1,7 +1,7 @@
 // Source view of the review screen (#8, all formats #25): the page, sheet, document or mail around a
-// value's evidence, with the cited segment and quote marked. Pure – rendered by the page, tested with fixtures. The pilot shows PDF
-// pages as text in reading order (decision-needed in #8); bounding boxes are stored for a later
-// rendered view.
+// value's evidence, with the cited segment and quote marked. Pure – rendered by the page, tested with fixtures. PDF
+// pages show as text in reading order – the accessible equivalent – and, for a PDF document itself,
+// as the rendered original with the cited box (#74, ADR-0002).
 export interface StoredSegment {
   segmentId: string;
   position: number;
@@ -16,11 +16,23 @@ export interface SourceLine {
   parts: Array<{ text: string; mark: boolean }>;
 }
 
+/** Where a segment sits on a PDF page: PDF points, origin top-left of the displayed page (docling). */
+export interface PageRegion {
+  /** 1-based. */
+  page: number;
+  bbox: { l: number; t: number; r: number; b: number };
+}
+
 export interface SourceView {
   kind: "pdf" | "email" | "xlsx" | "docx";
   heading: string;
   /** The cited segment comes from text recognition (scanned PDF) – the page says so (#25). */
   ocr: boolean;
+  /**
+   * The cited segment on the original page (#74) – only for a PDF document itself: for a PDF inside an
+   * Outlook message the document route serves the `.msg`, which the browser cannot render as a page.
+   */
+  region: PageRegion | null;
   lines: SourceLine[];
 }
 
@@ -82,6 +94,17 @@ function headingOf({ inner, attachments }: ReturnType<typeof unwrap>): string {
   return attachments.length > 0 ? `${attachments.map((name) => `Anhang ${name}`).join(" – ")} – ${base}` : base;
 }
 
+const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+
+function regionOf({ inner, attachments }: ReturnType<typeof unwrap>): PageRegion | null {
+  if (inner.kind !== "pdf" || attachments.length > 0) return null;
+  const { page, bbox } = inner;
+  if (typeof page !== "number" || !Number.isInteger(page) || page < 1 || !bbox || typeof bbox !== "object") return null;
+  const { l, t, r, b } = bbox as Record<string, unknown>;
+  if (!finite(l) || !finite(t) || !finite(r) || !finite(b) || r <= l || b <= t) return null;
+  return { page, bbox: { l, t, r, b } };
+}
+
 function markQuote(text: string, quote: string): SourceLine["parts"] {
   // Exact match first; the case-insensitive fallback only when lowercasing keeps the length, so the
   // index is valid in the original text (e.g. "İ" grows) – otherwise the whole segment is marked.
@@ -108,6 +131,7 @@ export function buildSourceView(segments: StoredSegment[], evidence: { segmentId
     kind: kind === "pdf" || kind === "xlsx" || kind === "docx" ? kind : "email",
     heading: headingOf(where),
     ocr: where.inner.ocr === true,
+    region: regionOf(where),
     lines: context.map((segment) => ({
       segmentId: segment.segmentId,
       label: label(unwrap(segment.locator).inner),

From 869feb2c2a0e66f6e3effe4491b6109c81c57f91 Mon Sep 17 00:00:00 2001
From: Fluory <florian.hein.sh@web.de>
Date: Mon, 28 Sep 2026 18:37:58 +0200
Subject: [PATCH 3/4] wip(samples): a sample may consist of several files;
 review sample gets a PDF position list (#74)

Recordings follow in the next commit (tests red until then).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../samples/data/werk-ost-positionen.pdf      | Bin 0 -> 2564 bytes
 src/features/samples/data/werk-ost.eml        |   9 +-
 src/features/samples/index.ts                 |  14 +++-
 src/features/samples/samples.test.ts          |  64 ++++++++++----
 src/features/samples/samples.ts               |  78 +++++++++++++-----
 src/features/samples/seed.ts                  |   6 +-
 src/samples-record.ts                         |  26 +++---
 7 files changed, 134 insertions(+), 63 deletions(-)
 create mode 100644 src/features/samples/data/werk-ost-positionen.pdf

diff --git a/src/features/samples/data/werk-ost-positionen.pdf b/src/features/samples/data/werk-ost-positionen.pdf
new file mode 100644
index 0000000000000000000000000000000000000000..a4e1a2191f29387c031091ac0ecf3154f42b12d8
GIT binary patch
literal 2564
zcmbVO+iu%95PkPo%u9e4Xl;qQST2eH@#fNPo7RYp%|o*fvPIcUWHKvCO`EUZLz?uh
z+Mrm&Flf%<%sIp1kSCM#%eP@a?u8VPn&0={zo)_M=Od@VA9<5kYDt4hzT}!105^1c
z+T*e?K=c1_!3H<@BnnO6A_M;$UQ{a^3ilQo%dZPfn3@B+i8Hw7g~-S12Ym~GPeuu4
zF@wJwu2owvK*%t?R9ImLA;l&lrWhr5bb5-QhJb9~S5xX{y#Rwh<YB!HrtQ432{360
zX)w+;-&j8I>N{`5BB#NHT&O}wWan1MGpWUPVwWL9<9`NtJ62Wkdr^!mALTQb%VtI4
zFbYh<byM?v-5bwrR>GKOB_$~hvy^59y&7|&9|f=IOjg)pInP_VTF*bcrrAAR%z8mT
zN@z)Tc}OF_dKlQ%7eYSdZAo`59ny8H8(t$`eiubUj{UaNA&cT<Ys`zrxd!FsmKO7l
z83=;bL}}3oC3Pj>l%Crf1j`x>>APAJ3;V&S&jOZuo{nG$UK@RZ*9ZM&`HpVXs-7z-
zq*fMmS>;kMR-DSaXc*UY%j*aFsy#Qz9z~Fy1e7Kj#i%^Ss0RFiwGWo2iD%tEAjD`x
zXvD~4uCYD56BNdX<~$*>D=xNl{O;L+;V9kW#{8L!#Y(nv+37Pf3Y^cg`I>9}U&uJ!
zAx$=PqssEYXXwPBdeS(ug2PULQR@I%C%`Ioh-ve1m@^;7%5<RJ=8Xcns`H}LtrhE5
zoPVJ#=tNne4mDv>a<#4X;~Gj?XjQUKKSrekgxzImWje^qG9BnIRih}MxG)E(+>~f%
zY^&5QvPx<4h2j_VdZPUR@;hB(SCbLWHx6Ia34mS?ctNj+yr|cMa0(Zz0`=P*SEVlk
zBh;gRN2tf5MjltY^Aq$lda|cE3usLV8d8c;MN^#g*qLz9oe85uQ<QoWMu#SJRJRJF
zjmgDIkg<))jEw2Hz!D_gB>aj$nKooP5;`b-7QEy&Mr$G8(WhIAyN{9CvM942#-c%+
zlw9IVQ^9Fcqp{moxABHH(a=5SU1RM&bH-zUUJOnjbD5LB9o~@Z^u98XwY_Tr9Bk8#
zH)N(iWwXK^X&S8F`tYr`0J|IhPs??4S*fSD=X|YjQ?QgCxR9K<NrI&F9KW8W?Yek#
zxXaAFK8Aa@-b^$V|K;A;we`WIRz<r&c3<rUC!Mb!EB=PGqr7;%_elAHo1+&{)(f^D
zTn7m*#FBP%BeGVKyE)X)@mv_<C15^#IF{hSbu<?thsSd<4#CkJV-em+el4zCQSsWo
p+os}~Q-(K^Qs&8JpF@AjQjy7)eY@!<uN$ikPO{#~$;H>p-oK6PnqB|^

literal 0
HcmV?d00001

diff --git a/src/features/samples/data/werk-ost.eml b/src/features/samples/data/werk-ost.eml
index 91752cc..0f59e9d 100644
--- a/src/features/samples/data/werk-ost.eml
+++ b/src/features/samples/data/werk-ost.eml
@@ -7,13 +7,8 @@ Content-Type: text/plain; charset=utf-8
 
 Guten Tag,
 
-wir bitten um ein Angebot fuer folgende Positionen:
-
-1) 8 Stk. Rohrbogen 90 Grad DN 80, Werkstoff P235GH
-2) 16 Stk. Vorschweissflansch DN 80 PN 40, Werkstoff 1.0460
-3) 16 Stk. Flachdichtung DN 80 PN 40, Werkstoff Graphit
-
-Gewuenschter Liefertermin: KW 48
+wir bitten um ein Angebot fuer die Positionen der beigefuegten Positionsliste (PDF).
+Den gewuenschten Liefertermin finden Sie ebenfalls dort.
 
 Mit freundlichen Gruessen
 Jana Beispiel
diff --git a/src/features/samples/index.ts b/src/features/samples/index.ts
index cec5915..38511af 100644
--- a/src/features/samples/index.ts
+++ b/src/features/samples/index.ts
@@ -1,3 +1,15 @@
 // Public API of the `samples` module (#71): prepared showcase cases from recorded AI answers.
-export { freshSampleMail, RECORDED_MODEL_PREFIX, recordedAiClient, recordingFile, SAMPLES, sampleMail, sampleRecording, type Sample } from "./samples";
+export {
+  freshSampleFiles,
+  RECORDED_MODEL_PREFIX,
+  recordedAiClient,
+  recordingDocumentId,
+  recordingFile,
+  SAMPLES,
+  sampleFile,
+  sampleRecording,
+  sampleRecordings,
+  type Sample,
+  type SampleFile,
+} from "./samples";
 export { seedSamples, type SampleDeps, type SeededSample, type SeedResult } from "./seed";
diff --git a/src/features/samples/samples.test.ts b/src/features/samples/samples.test.ts
index 8754e82..8a6b1d0 100644
--- a/src/features/samples/samples.test.ts
+++ b/src/features/samples/samples.test.ts
@@ -1,41 +1,69 @@
 import { describe, expect, it } from "vitest";
-import { freshSampleMail, RECORDED_MODEL_PREFIX, recordedAiClient, SAMPLES, sampleMail, sampleRecording } from "./samples";
+import { mergeFields } from "@/features/extraction";
+import { freshSampleFiles, RECORDED_MODEL_PREFIX, recordedAiClient, SAMPLES, sampleFile, sampleRecording, sampleRecordings } from "./samples";
 
 // Prepared samples (#71): the committed recordings are valid AI answers, and replaying one never looks
-// like a live model call.
-const input = (documentId: string) => ({ bytes: new Uint8Array(), filename: "x.eml", mediaType: "message/rfc822", documentId, correlationId: "c" });
+// like a live model call. #74: the review sample carries a PDF, so a visitor sees the original page.
+const input = (filename: string) => ({ bytes: new Uint8Array(), filename, mediaType: "application/octet-stream", documentId: "doc-42", correlationId: "c" });
+const review = SAMPLES.find((sample) => sample.purpose === "review")!;
 
 describe("samples", () => {
-  it("has a valid recording for every sample, and the review sample shows why a person must check", () => {
-    for (const sample of SAMPLES) expect(() => sampleRecording(sample)).not.toThrow();
+  it("has a valid recording for every file, and the review sample shows why a person must check", () => {
+    for (const sample of SAMPLES) for (const file of sample.files) expect(() => sampleRecording(file)).not.toThrow();
 
-    const review = SAMPLES.find((sample) => sample.purpose === "review")!;
-    const statuses = Object.values(sampleRecording(review).fields).map((field) => field.status);
+    const merged = mergeFields([...sampleRecordings(review)].map(([filename, response]) => ({ documentId: filename, response })));
+    const statuses = Object.values(merged).map((field) => field.status);
     expect(statuses).toContain("uncertain");
     expect(statuses).toContain("missing");
   });
 
-  it("replays the recording for the given document, marked as recorded, with no tokens or model time spent", async () => {
-    const recording = sampleRecording(SAMPLES[0]!);
+  it("opens the review sample's first uncertain value on a PDF page with its box (#74)", () => {
+    const recordings = sampleRecordings(review);
+    const merged = mergeFields([...recordings].map(([filename, response]) => ({ documentId: filename, response })));
+    const uncertain = Object.values(merged).find((field) => field.status === "uncertain")!;
+    const pdf = review.files.find((file) => file.mediaType === "application/pdf")!;
 
-    const answer = await recordedAiClient(recording).extract(input("doc-42"));
+    expect(uncertain.documentId).toBe(pdf.filename);
+    const segment = recordings.get(pdf.filename)!.segments.find((candidate) => candidate.id === uncertain.evidence?.segmentId);
+    expect(segment?.locator).toMatchObject({ kind: "pdf", page: 1, bbox: { l: expect.any(Number), t: expect.any(Number), r: expect.any(Number), b: expect.any(Number) } });
+  });
+
+  it("replays the recording of the given file, marked as recorded, with no tokens or model time spent", async () => {
+    const recordings = sampleRecordings(review);
+    const pdf = review.files.find((file) => file.mediaType === "application/pdf")!;
+    const recording = recordings.get(pdf.filename)!;
+
+    const answer = await recordedAiClient(recordings).extract(input(pdf.filename));
 
     expect(answer.documentId).toBe("doc-42");
     expect(answer.run.modelId).toBe(`${RECORDED_MODEL_PREFIX}${recording.run.modelId}`);
     expect(answer.run.latencyMs).toBe(0);
     expect(answer.run.tokens).toEqual({ inputTokens: null, outputTokens: null, totalTokens: null });
     expect(answer.fields).toEqual(recording.fields);
+    expect(answer.segments).toEqual(recording.segments);
+    // A file without a recording is an error, never another file's answer.
+    await expect(recordedAiClient(recordings).extract(input("fremd.pdf"))).rejects.toThrow("no recording for fremd.pdf");
   });
 
-  it("gives every seeded copy a new Message-ID and changes nothing else", () => {
-    const sample = SAMPLES[0]!;
-    const original = new TextDecoder().decode(sampleMail(sample));
+  it("gives every seeded copy's mail a new Message-ID and changes nothing else", () => {
+    const copy = freshSampleFiles(review, "<fresh@example.com>");
 
-    const copy = new TextDecoder().decode(freshSampleMail(sample, "<fresh@example.com>"));
+    expect(copy.map((file) => file.name)).toEqual(review.files.map((file) => file.filename));
+    for (const [index, file] of review.files.entries()) {
+      const original = sampleFile(file);
+      if (file.mediaType !== "message/rfc822") {
+        expect(copy[index]!.bytes).toEqual(original);
+        continue;
+      }
+      const text = new TextDecoder().decode(copy[index]!.bytes);
+      expect(text).toContain("Message-ID: <fresh@example.com>");
+      expect(text.replace(/^Message-ID: .*$/m, "")).toBe(new TextDecoder().decode(original).replace(/^Message-ID: .*$/m, ""));
+      // The header is not evidence: no recorded segment quotes it.
+      expect(sampleRecording(file).segments.some((segment) => /Message-ID/i.test(segment.text))).toBe(false);
+    }
+  });
 
-    expect(copy).toContain("Message-ID: <fresh@example.com>");
-    expect(copy.replace(/^Message-ID: .*$/m, "")).toBe(original.replace(/^Message-ID: .*$/m, ""));
-    // The header is not evidence: no recorded segment quotes it.
-    expect(sampleRecording(sample).segments.some((segment) => /Message-ID/i.test(segment.text))).toBe(false);
+  it("has exactly one mail per sample – the fresh Message-ID keeps a re-seeded sample from being a duplicate", () => {
+    for (const sample of SAMPLES) expect(sample.files.filter((file) => file.mediaType === "message/rfc822")).toHaveLength(1);
   });
 });
diff --git a/src/features/samples/samples.ts b/src/features/samples/samples.ts
index 165ad5d..ae6ffb0 100644
--- a/src/features/samples/samples.ts
+++ b/src/features/samples/samples.ts
@@ -2,57 +2,91 @@ import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { parseExtractResponse, type AiServiceClient, type ExtractResponse } from "@/features/extraction";
 
-// Prepared showcase cases (#71): synthetic mails whose AI answer was recorded once
+// Prepared showcase cases (#71): synthetic requests whose AI answer was recorded once per file
 // (`pnpm samples:record`) and is replayed when a sample is seeded – no live model call.
+export interface SampleFile {
+  filename: string;
+  mediaType: string;
+}
+
 export interface Sample {
   key: string;
-  filename: string;
+  /** Uploaded together as one request, in this order; exactly one mail (it gets a fresh Message-ID). */
+  files: readonly SampleFile[];
   /** `review`: stays in review for visitors to try; `exported`: approved and exported through the normal path. */
   purpose: "review" | "exported";
 }
 
+const MAIL = "message/rfc822";
+
 export const SAMPLES: readonly Sample[] = [
-  { key: "werk-ost", filename: "werk-ost.eml", purpose: "review" },
-  { key: "pumpe-p204", filename: "pumpe-p204.eml", purpose: "exported" },
+  // #74: the positions and the delivery week come from a PDF, so a visitor sees the original page.
+  {
+    key: "werk-ost",
+    files: [
+      { filename: "werk-ost.eml", mediaType: MAIL },
+      { filename: "werk-ost-positionen.pdf", mediaType: "application/pdf" },
+    ],
+    purpose: "review",
+  },
+  { key: "pumpe-p204", files: [{ filename: "pumpe-p204.eml", mediaType: MAIL }], purpose: "exported" },
 ];
 
 const dataFile = (name: string) => new URL(`./data/${name}`, import.meta.url);
 
-export const recordingFile = (sample: Sample) => dataFile(`${sample.key}.recording.json`);
+const stem = (file: SampleFile) => file.filename.replace(/\.[^.]+$/, "");
 
-/** The committed mail. */
-export function sampleMail(sample: Sample): Uint8Array {
-  return new Uint8Array(readFileSync(dataFile(sample.filename)));
+/** `werk-ost-positionen.pdf` → `werk-ost-positionen.recording.json`. */
+export const recordingFile = (file: SampleFile) => dataFile(`${stem(file)}.recording.json`);
+
+/** The document id a recording was made with – checked when it is read. */
+export const recordingDocumentId = (file: SampleFile) => `sample-${stem(file)}`;
+
+/** The committed file. */
+export function sampleFile(file: SampleFile): Uint8Array {
+  return new Uint8Array(readFileSync(dataFile(file.filename)));
 }
 
 /**
- * The mail as a new arrival: a fresh Message-ID, so a sample seeded again is not flagged as a duplicate of
- * an earlier one. The header is not a segment of the recording, so the recorded evidence still matches.
+ * The files as a new arrival: the mail gets a fresh Message-ID, so a sample seeded again is not flagged as
+ * a duplicate of an earlier one (neither by Message-ID nor by the set of file hashes). The header is not a
+ * segment of the recording, so the recorded evidence still matches; other files stay byte for byte.
  */
-export function freshSampleMail(sample: Sample, messageId: string = `<sample-${randomUUID()}@example.com>`): Uint8Array {
-  const text = new TextDecoder().decode(sampleMail(sample));
-  const replaced = text.replace(/^Message-ID: .*$/m, `Message-ID: ${messageId}`);
-  if (replaced === text) throw new Error(`sample ${sample.key} has no Message-ID header`);
-  return new TextEncoder().encode(replaced);
+export function freshSampleFiles(sample: Sample, messageId: string = `<sample-${randomUUID()}@example.com>`): Array<{ name: string; bytes: Uint8Array }> {
+  return sample.files.map((file) => {
+    const bytes = sampleFile(file);
+    if (file.mediaType !== MAIL) return { name: file.filename, bytes };
+    const text = new TextDecoder().decode(bytes);
+    const replaced = text.replace(/^Message-ID: .*$/m, `Message-ID: ${messageId}`);
+    if (replaced === text) throw new Error(`sample ${sample.key} has no Message-ID header`);
+    return { name: file.filename, bytes: new TextEncoder().encode(replaced) };
+  });
 }
 
-/** The committed recording, validated like a live answer (#83 review): a damaged file fails here, not later. */
-export function sampleRecording(sample: Sample): ExtractResponse {
-  const recording = parseExtractResponse(JSON.parse(readFileSync(recordingFile(sample), "utf8")), `sample-${sample.key}`);
-  if (!recording) throw new Error(`recording of sample ${sample.key} does not match the AI service contract`);
+/** The committed recording of one file, validated like a live answer (#83 review): a damaged file fails here, not later. */
+export function sampleRecording(file: SampleFile): ExtractResponse {
+  const recording = parseExtractResponse(JSON.parse(readFileSync(recordingFile(file), "utf8")), recordingDocumentId(file));
+  if (!recording) throw new Error(`recording of sample file ${file.filename} does not match the AI service contract`);
   return recording;
 }
 
+/** The recordings of a sample by file name. */
+export function sampleRecordings(sample: Sample): Map<string, ExtractResponse> {
+  return new Map(sample.files.map((file) => [file.filename, sampleRecording(file)]));
+}
+
 /** Marks a replayed run in its stored model id, so a recorded answer is never mistaken for a live one. */
 export const RECORDED_MODEL_PREFIX = "recorded:";
 
 /**
- * An AI client that answers with the recording – for the document it is given, without any network call.
- * The replayed run is marked as recorded and consumed no tokens and no model time (#83 review).
+ * An AI client that answers with the recording of the file it is given, without any network call. The
+ * replayed run is marked as recorded and consumed no tokens and no model time (#83 review).
  */
-export function recordedAiClient(recording: ExtractResponse): AiServiceClient {
+export function recordedAiClient(recordings: ReadonlyMap<string, ExtractResponse>): AiServiceClient {
   return {
     async extract(input) {
+      const recording = recordings.get(input.filename);
+      if (!recording) throw new Error(`no recording for ${input.filename}`);
       return {
         ...recording,
         documentId: input.documentId,
diff --git a/src/features/samples/seed.ts b/src/features/samples/seed.ts
index 27f8900..25cdf7c 100644
--- a/src/features/samples/seed.ts
+++ b/src/features/samples/seed.ts
@@ -6,7 +6,7 @@ import { submitUpload, type IntakeDeps } from "@/features/intake";
 import { markProcessingFailed, processRequestJob, type JobSender } from "@/features/jobs";
 import { countSamples, listSampleLeftoverIds, lockRequest, retireSampleLeftover, type RequestRow } from "@/features/requests";
 import { approveRequest } from "@/features/review";
-import { freshSampleMail, recordedAiClient, SAMPLES, sampleRecording, type Sample } from "./samples";
+import { freshSampleFiles, recordedAiClient, SAMPLES, sampleRecordings, type Sample } from "./samples";
 
 // While a sample of a purpose is in one of these statuses it still serves that purpose – no new one.
 // Only settled states count (#83 review): a sample left in NEW/PROCESSING/ERROR by an aborted run must
@@ -99,12 +99,12 @@ async function retireLeftovers(deps: SampleDeps, actor: Actor): Promise<number>
 async function createSample(deps: SampleDeps, actor: Actor, sample: Sample): Promise<string> {
   // Processing is never queued: a queued job could reach the live model.
   const processing = recordingSender();
-  const { requestId } = await submitUpload({ ...deps, boss: processing.sender }, actor, [{ name: sample.filename, bytes: freshSampleMail(sample) }], {
+  const { requestId } = await submitUpload({ ...deps, boss: processing.sender }, actor, freshSampleFiles(sample), {
     source: "sample",
   });
   const job = { id: processing.jobId(), data: { requestId, companyId: actor.companyId } };
   try {
-    const outcome = await processRequestJob({ tenancy: deps.tenancy, storage: deps.storage, ai: recordedAiClient(sampleRecording(sample)) }, job);
+    const outcome = await processRequestJob({ tenancy: deps.tenancy, storage: deps.storage, ai: recordedAiClient(sampleRecordings(sample)) }, job);
     if (outcome !== "processed") throw new Error(`sample ${sample.key} was not processed`);
   } catch (error) {
     // Visible and settled instead of "in progress" forever; reprocessing a sample is refused (no live call).
diff --git a/src/samples-record.ts b/src/samples-record.ts
index 49f864a..9231d2f 100644
--- a/src/samples-record.ts
+++ b/src/samples-record.ts
@@ -1,10 +1,11 @@
-// Records the AI service's answer for every sample mail (`pnpm samples:record`, #71). Run once against a
-// deployed AI service; the answers are committed next to the mails and replayed by `pnpm seed:samples`.
-// Synthetic mails only. Needs AI_SERVICE_URL and AI_SERVICE_TOKEN (never printed). Optional arguments: sample keys.
+// Records the AI service's answer for every file of every sample (`pnpm samples:record`, #71, #74). Run once
+// against a deployed AI service; the answers are committed next to the files and replayed by
+// `pnpm seed:samples`. Synthetic files only. Needs AI_SERVICE_URL and AI_SERVICE_TOKEN (never printed).
+// Optional arguments: sample keys.
 import { randomUUID } from "node:crypto";
 import { writeFileSync } from "node:fs";
 import { AiServiceError, createAiServiceClient } from "@/features/extraction";
-import { recordingFile, SAMPLES, sampleMail } from "@/features/samples";
+import { recordingDocumentId, recordingFile, SAMPLES, sampleFile } from "@/features/samples";
 
 const ATTEMPTS = 8;
 const WAIT_MS = 30_000;
@@ -19,24 +20,25 @@ async function main(): Promise<void> {
   const client = createAiServiceClient({ baseUrl: required("AI_SERVICE_URL"), token: required("AI_SERVICE_TOKEN"), timeoutMs: 120_000 });
   // `pnpm samples:record <key> …` records only these samples and keeps the other recordings.
   const only = process.argv.slice(2);
-  for (const sample of SAMPLES.filter(({ key }) => only.length === 0 || only.includes(key))) {
+  const files = SAMPLES.filter(({ key }) => only.length === 0 || only.includes(key)).flatMap((sample) => sample.files);
+  for (const file of files) {
     for (let attempt = 1; ; attempt++) {
       try {
         const response = await client.extract({
-          bytes: sampleMail(sample),
-          filename: sample.filename,
-          mediaType: "message/rfc822",
-          documentId: `sample-${sample.key}`,
+          bytes: sampleFile(file),
+          filename: file.filename,
+          mediaType: file.mediaType,
+          documentId: recordingDocumentId(file),
           correlationId: randomUUID(),
         });
-        writeFileSync(recordingFile(sample), `${JSON.stringify(response, null, 2)}\n`);
+        writeFileSync(recordingFile(file), `${JSON.stringify(response, null, 2)}\n`);
         const statuses = Object.entries(response.fields).map(([key, field]) => `${key}=${field.status}`).join(" ");
-        console.log(`recorded ${sample.key}: ${statuses}; ${response.lineItems.length} line items; model ${response.run.modelId}`);
+        console.log(`recorded ${file.filename}: ${statuses}; ${response.lineItems.length} line items; model ${response.run.modelId}`);
         break;
       } catch (error) {
         // Overload of the model provider is common on the free tier: wait and try again.
         if (!(error instanceof AiServiceError) || !error.retryable || attempt >= ATTEMPTS) throw error;
-        console.log(`${sample.key}: ${error.code}, attempt ${attempt} of ${ATTEMPTS} – retrying`);
+        console.log(`${file.filename}: ${error.code}, attempt ${attempt} of ${ATTEMPTS} – retrying`);
         await new Promise((resolve) => setTimeout(resolve, WAIT_MS));
       }
     }

From 6ad54dd4a09102a7a03b54a591265b15cc62e9d0 Mon Sep 17 00:00:00 2001
From: Fluory <florian.hein.sh@web.de>
Date: Mon, 28 Sep 2026 19:02:33 +0200
Subject: [PATCH 4/4] test(samples): PDF source on the review sample in
 integration and E2E; docs (#74)

- integration: the review sample has mail + PDF, and its uncertain value
  opens on the PDF page with a region
- E2E: page rendered, highlight visible, plain-language reason; moving to a
  position by keyboard moves the highlight
- architecture map and CHANGELOG

The recordings of werk-ost (mail + PDF) are still missing: the Gemini free
tier answered 503/429 on two recording runs. Sample tests stay red until then.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                      |  7 +++++++
 docs/technical/architecture.md    |  4 ++--
 tests/e2e/sample-smoke.spec.ts    | 19 ++++++++++++++++++-
 tests/integration/samples.test.ts |  4 ++++
 4 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7b01285..8db6f4f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,13 @@ This file records what changes **in the product** – process and session state
 
 ## [Unreleased]
 
+### Added
+- The review page shows the original PDF page beside the values, with the place the AI read a value from
+  highlighted; selecting another value (mouse or keyboard) moves the highlight. Uncertain, missing and
+  unverified values say why in plain language (e.g. "Kalenderwoche ohne Datum"). The page is rendered in the
+  browser with pdf.js from the protected document download – no third-party request (#74, ADR-0002). The
+  review sample now comes with its position list as a PDF.
+
 ### Changed
 - Request list leads with the next work decision: customer, need for review (the same count as the detail
   page) and the next action ("Prüfen", "Duplikat entscheiden", "Fehler ansehen", "Export läuft"); attempts, last
diff --git a/docs/technical/architecture.md b/docs/technical/architecture.md
index c6d2387..1f25bad 100644
--- a/docs/technical/architecture.md
+++ b/docs/technical/architecture.md
@@ -27,10 +27,10 @@ Every new file belongs to one of these modules – otherwise add the module here
 | `documents` | `src/features/documents/` | document records, storage references, hashes | internal | confidential | tenant context | built: records, SHA-256, storage keys |
 | `extraction` | `src/features/extraction/` | AI-service client, persists runs/fields/evidence | internal | confidential + personal | tenant context, contract validation | built: AI-service client (timeout, error classes), field merge, runs/segments/fields |
 | `requests` | `src/features/requests/` | request aggregate, status machine | internal | confidential | tenant context | built: repository, status machine, processing state, list filters (status, possible duplicate) |
-| `review` | `src/features/review/` | review UI, corrections, approve/reject | authenticated UI | confidential + personal | session, role check, audit | built: review page (fields + status badges + source view for mail, PDF incl. OCR label, XLSX cells, DOCX paragraphs/tables, attachments; line items as a table with per-field status and audited corrections), corrections with history, approve (→ export job) / reject with reason, duplicate decision (confirm or reject as duplicate) |
+| `review` | `src/features/review/` | review UI, corrections, approve/reject | authenticated UI | confidential + personal | session, role check, audit | built: review page (fields + status badges + plain-language reason for uncertain/missing/unverified values + source view for mail, PDF incl. OCR label, XLSX cells, DOCX paragraphs/tables, attachments; a PDF document itself also as the rendered original page with the cited box highlighted – pdf.js in the browser, loaded from the document route, ADR-0002; line items as a table with per-field status and audited corrections), corrections with history, approve (→ export job) / reject with reason, duplicate decision (confirm or reject as duplicate) |
 | `export` | `src/features/export/` | ERP port + REST adapter, idempotency | outbound HTTP | confidential | idempotency key, unique export, timeout | built: REST adapter (timeout, error classes, contract validation), export handler under row lock, `drainExports()`, `request_exports` |
 | `erp-mock` | `src/features/erp-mock/` | simulated ERP REST API | route behind flag | synthetic | disabled unless `ERP_MOCK_ENABLED` | built: idempotent receiver (replay → same reference, 409 on a different body), fault injection, bounded in-memory store, route `/api/erp-mock/v1/quote-requests` |
-| `samples` | `src/features/samples/`, entrypoints `src/seed-samples.ts` (`pnpm seed:samples`) and `src/samples-record.ts` (`pnpm samples:record`) | prepared showcase cases: synthetic mails with a recorded AI answer, seeded through intake → processing → approval | operator scripts only | synthetic | no model call when seeding (recording replayed inline, no queued processing job); requests marked `source = 'sample'` (CHECK, migration 0019) | built: two samples per demo company – one in review (uncertain + missing value), one approved with its export queued (#71) |
+| `samples` | `src/features/samples/`, entrypoints `src/seed-samples.ts` (`pnpm seed:samples`) and `src/samples-record.ts` (`pnpm samples:record`) | prepared showcase cases: synthetic requests (mail, the review sample with a PDF position list) with a recorded AI answer per file, seeded through intake → processing → approval | operator scripts only | synthetic | no model call when seeding (recording replayed inline, no queued processing job); requests marked `source = 'sample'` (CHECK, migration 0019) | built: two samples per demo company – one in review (uncertain + missing value), one approved with its export queued (#71) |
 | `identity` | `src/features/identity/` | Better Auth, users, companies, roles | public login route | personal (staff) | rate limit, invite-only | built: Better Auth (invite-only, organization + admin plugins), `authorize()`, audited invite, user management (`/users`: roles, deactivate/reactivate, last-admin rule), seed |
 | `tenancy` | `src/features/tenancy/` | `withTenant()`, RLS policies | internal | – | forced RLS, `app_rw` without BYPASSRLS | built: `withTenant()`, forced RLS on `app.*`, guard test (every `app` table: `company_id`, forced RLS, only company policies; allow-list empty) |
 | `audit` | `src/features/audit/` | append-only audit events | internal | personal (staff) | INSERT/SELECT only | partial: `recordAudit()` (append-only enforced by grants) |
diff --git a/tests/e2e/sample-smoke.spec.ts b/tests/e2e/sample-smoke.spec.ts
index 2990642..cc92ab1 100644
--- a/tests/e2e/sample-smoke.spec.ts
+++ b/tests/e2e/sample-smoke.spec.ts
@@ -1,7 +1,8 @@
 import { expect, test } from "@playwright/test";
 
 // Smoke (#71): the prepared samples from the global setup are labelled in list and detail, the review
-// sample shows why a person must check, and the exported sample carries its ERP reference.
+// sample shows why a person must check – on the original PDF page (#74) – and the exported sample carries
+// its ERP reference.
 test("a visitor finds the prepared samples, clearly labelled, one to review and one exported", async ({ page }) => {
   await page.goto("/login");
   await page.getByLabel("E-Mail").fill("sachbearbeitung@musterbau.example.com");
@@ -36,6 +37,22 @@ test("a visitor finds the prepared samples, clearly labelled, one to review and
   await expect(page.getByTestId("request-status")).toHaveText("Zur Prüfung");
   await expect(page.getByText(/braucht Aufmerksamkeit|brauchen Aufmerksamkeit/)).toBeVisible();
 
+  // #74: the uncertain delivery week sits on the original PDF page – rendered, its box highlighted – and
+  // the panel says why in plain language.
+  await page.getByRole("row", { name: /Gewünschter Liefertermin/ }).getByRole("link", { name: "Quelle anzeigen" }).click();
+  const pdfPage = page.getByTestId("pdf-page");
+  await expect(pdfPage).toHaveAttribute("data-state", "rendered");
+  const highlight = page.getByTestId("pdf-highlight");
+  await expect(highlight).toBeVisible();
+  await expect(page.getByTestId("selected-reason")).toContainText("Kalenderwoche ohne Datum");
+  const lineWidth = (await highlight.boundingBox())!.width;
+  // By keyboard to a position's quantity: the highlight moves to that table cell – far narrower than the line.
+  await page.getByRole("link", { name: /^Position 1, Menge:/ }).focus();
+  await page.keyboard.press("Enter");
+  await expect(page.getByTestId("selected-item-value")).toHaveText("8");
+  await expect(pdfPage).toHaveAttribute("data-state", "rendered");
+  await expect.poll(async () => (await highlight.boundingBox())?.width ?? lineWidth).toBeLessThan(lineWidth / 3);
+
   await page.goto("/requests");
   await page.getByRole("link", { name: "Anfrage Dichtungssatz fuer Pumpe P-204", exact: true }).first().click();
   await expect(page.getByTestId("sample-notice")).toBeVisible();
diff --git a/tests/integration/samples.test.ts b/tests/integration/samples.test.ts
index 83b526d..fa5cd5e 100644
--- a/tests/integration/samples.test.ts
+++ b/tests/integration/samples.test.ts
@@ -77,6 +77,10 @@ describe("prepared samples", () => {
     expect(statuses).toContain("uncertain");
     expect(statuses).toContain("missing");
     expect(view!.lineItems.length).toBeGreaterThan(0);
+    // #74: the positions come as a PDF, and the uncertain delivery week opens on its page with the box.
+    expect(view!.documents.map((document) => document.filename)).toEqual(["werk-ost.eml", "werk-ost-positionen.pdf"]);
+    const uncertain = view!.fields.find((field) => field.status === "uncertain");
+    expect(uncertain?.source).toMatchObject({ kind: "pdf", filename: "werk-ost-positionen.pdf", region: { page: 1 } });
     // The original is stored like any upload, so "Original öffnen" works.
     expect(new TextDecoder().decode(await storage.get(view!.documents[0]!.storageKey))).toContain("Subject: Anfrage Rohrbogen und Flansche fuer Werk Ost");