Implement CE-WP-0005 T01-T08: demo app — sessions, uploads, ZIP archive

Turn the MVP into a self-contained demo. Users now: 1. Land on an empty-state and create a named session. 2. Drag-drop or pick arbitrary PDFs into that session. 3. Annotate, build evidence, link to form fields — all session-scoped. 4. Export the whole session as a single .zip archive (manifest + per-document PDFs). 5. Import a .zip back — into a new session, or merged into an existing one (documents deduped by SHA-256 fingerprint; annotations/evidence/links added additively). Architecture: - New shared types: SessionId, Session, SessionArchiveManifest + parseSessionArchiveManifest with schema-version validation. - SessionService (engine/services/sessions.ts) handles lifecycle (create/rename/delete/setActive) + emits 4 new events through its own bus; SharedContracts.md §4 lists the additions. - SessionProvider (work/SessionContext.tsx) owns the cross-session state: service, per-session PdfByteStore registry, per-session version counter that drives EngineProvider remounts after imports. - EngineProvider becomes session-aware (sessionId prop drives per- session localStorage keys). Bumping engineRevision after restoreFromStorage forces consumers to re-render so restored repos show up immediately. - PdfByteStore (source/pdf/byte-store.ts) holds Uint8Array bytes per document and mints blob URLs; ingestPdfFromFile is the upload entry-point that wraps the existing ingestPdf pipeline. - ADR-0008 locks the ZIP layout (manifest.json + documents/<id>.pdf), the manifest schema (schemaVersion 1), and the merge-on-collision policy. JSZip is the only new dependency. - App.tsx restructured: SessionProvider at the root, EngineProvider keyed by ${sessionId}:${version}, hash routing #/s/<id>[/forms/demo], SessionMenu top-bar, CreateFirstSession empty state. - New DocumentRemoved event for per-document delete cleanup in CollectionList; engine.documents.remove() is the new service method. Tests: - Unit: 16 SessionService lifecycle + persistence tests; per-session snapshot round-trip; PdfByteStore + ingestPdfFromFile; SessionArchive parser; exportSessionZip + importSessionZip with create + merge + corrupt-archive paths. - DOM: UploadDropzone, session-scoped CollectionList delete, SessionMenu create/switch/rename, routing parser. - E2E: tests/integration/session-export-reimport.dom.test.tsx walks the full create → annotate → export → reimport flow and asserts the additive merge (deduped doc + doubled evidence rows). - Legacy E2Es updated to use a seed-session helper instead of the removed fixture-button flow. Known limitation (documented in ADR-0008): re-importing your own freshly-exported ZIP creates duplicate annotations. Forward pointer left for an importBundleId follow-up. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-26 14:57:28 +02:00
parent 8632f7b04a
commit 779ae0d317
53 changed files with 5657 additions and 372 deletions
--- a/tests/integration/app-prd-scenario.dom.test.tsx
+++ b/tests/integration/app-prd-scenario.dom.test.tsx
@@ -28,8 +28,6 @@ import userEvent from "@testing-library/user-event";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

 import type { Selector } from "@shared/selector";
-import type { DocumentId, RepresentationId } from "@shared/ids";
-import type { Document, DocumentRepresentation } from "@shared/document";
 import type { PdfSelectionCapture } from "@anchor/index";
 import manifest from "../../fixtures/pdfs/manifest.json" with { type: "json" };

@@ -90,42 +88,8 @@ const SYNTHETIC_CANONICAL = [
  "Trailing prose that comes after the quote.",
 ].join(" ");

-vi.mock("@source/index", async (importOriginal) => {
-  const original = await importOriginal<typeof import("@source/index")>();
-  return {
-    ...original,
-    ingestPdf: vi.fn(async (_input: unknown, options?: { filename?: string }) => {
-      const documentId = ("doc_test_" + Math.random().toString(36).slice(2, 10)) as DocumentId;
-      const representationId = ("rep_test_" + Math.random().toString(36).slice(2, 10)) as RepresentationId;
-      const document: Document = {
-        id: documentId,
-        mediaType: "application/pdf",
-        ...(options?.filename ? { title: options.filename } : {}),
-        fingerprint: "synthetic-fingerprint-for-test",
-        createdAt: "2026-05-25T00:00:00.000Z",
-        updatedAt: "2026-05-25T00:00:00.000Z",
-      };
-      const representation: DocumentRepresentation = {
-        id: representationId,
-        documentId,
-        representationType: "pdf-text",
-        contentHash: "synthetic-fingerprint-for-test",
-        canonicalText: SYNTHETIC_CANONICAL,
-        pageMap: [{ page: 1, width: 595, height: 842 }],
-        offsetMap: [
-          {
-            page: 1,
-            globalStart: 0,
-            globalEnd: SYNTHETIC_CANONICAL.length,
-            pageLength: SYNTHETIC_CANONICAL.length,
-          },
-        ],
-        generatedAt: "2026-05-25T00:00:00.000Z",
-      };
-      return { document, representation };
-    }),
-  };
-});
+// CE-WP-0005: pre-seed a session with the fixture doc; no ingestPdf mock needed.
+import { seedSessionWithDoc, type SeedResult } from "./helpers/seed-session";

 // ---------------------------------------------------------------------------
 // Helpers
@@ -160,40 +124,40 @@ async function loadApp() {
 // ---------------------------------------------------------------------------

 describe("App — PRD scenario steps 1-8 (CE-WP-0002-T09)", () => {
+  let seeded: SeedResult;
+
  beforeEach(() => {
    resetViewerSnapshot();
    // Each test starts with empty localStorage.
    globalThis.localStorage?.clear();
-    // The fetch isn't reached (ingestPdf is mocked) — but stub it so that
-    // any accidental call returns gracefully instead of TypeError.
-    globalThis.fetch = vi.fn(async () =>
-      new Response(new Uint8Array([0x25, 0x50, 0x44, 0x46]).buffer, {
-        status: 200,
-        headers: { "Content-Type": "application/pdf" },
-      }),
-    );
+    if (typeof window !== "undefined") {
+      history.replaceState(null, "", window.location.pathname);
+    }
+    seeded = seedSessionWithDoc({
+      sessionName: "Demo",
+      documentTitle: FIXTURE.filename,
+      canonicalText: SYNTHETIC_CANONICAL,
+    });
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

-  it("walks the full slice-1 scenario: load → select → save → reload → click → scroll", async () => {
+  it("walks the full slice-1 scenario: load → select → save → reload → click → scroll", { timeout: 15000 }, async () => {
    const user = userEvent.setup();

-    // Step 1: open the app.
+    // Step 1: open the app. CE-WP-0005: a pre-seeded session boots
+    // straight into the active layout (no empty state).
    const { unmount } = await loadApp();
-    expect(screen.getByText("Collection")).toBeTruthy();
+    expect(screen.queryByTestId("empty-state")).toBeNull();
+    expect(screen.getByTestId("session-menu-toggle").textContent).toContain("Demo");

-    // Step 2: pick a fixture.
-    const fixtureButton = screen.getByRole("button", { name: new RegExp(FIXTURE.id) });
-    await user.click(fixtureButton);
-
-    // The mock viewer should have mounted with our test URL.
+    // Step 2: the fixture doc is pre-seeded into the active session, so
+    // the viewer mounts automatically — no fixture-button click needed.
    await waitFor(() => {
-      expect(viewerSnapshot.pdfUrl).toBeTruthy();
+      expect(viewerSnapshot.onSelectionCaptured).not.toBeNull();
    });
-    expect(decodeURIComponent(viewerSnapshot.pdfUrl!)).toContain(FIXTURE.filename);

    // Step 3: programmatically inject a selection for the known-good quote.
    expect(viewerSnapshot.onSelectionCaptured).not.toBeNull();
@@ -223,9 +187,11 @@ describe("App — PRD scenario steps 1-8 (CE-WP-0002-T09)", () => {
    });
    const savedAnnotationId = viewerSnapshot.storedAnnotationIds[0]!;

-    // Snapshot key from EngineContext.STORAGE_KEY — implementation detail
+    // Per-session snapshot key from CE-WP-0005 — implementation detail
    // but worth asserting once at the integration layer.
-    const stored = globalThis.localStorage?.getItem("citation-evidence:engine-snapshot:v1");
+    const stored = globalThis.localStorage?.getItem(
+      `citation-evidence:session:${seeded.sessionId}:engine-snapshot:v1`,
+    );
    expect(stored).toBeTruthy();

    // Step 6: reload — unmount and remount the App. The same localStorage is
@@ -237,9 +203,8 @@ describe("App — PRD scenario steps 1-8 (CE-WP-0002-T09)", () => {
    // The viewer should re-mount automatically because the active document
    // was persisted.
    await waitFor(() => {
-      expect(viewerSnapshot.pdfUrl).toBeTruthy();
+      expect(viewerSnapshot.onSelectionCaptured).not.toBeNull();
    });
-    expect(decodeURIComponent(viewerSnapshot.pdfUrl!)).toContain(FIXTURE.filename);

    // The sidebar should show the restored item.
    const restoredItem = await screen.findByText(/Important deadline clause/);
--- a/tests/integration/forms-active-cycling.dom.test.tsx
+++ b/tests/integration/forms-active-cycling.dom.test.tsx
@@ -20,8 +20,6 @@ import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

-import type { Document, DocumentRepresentation } from "@shared/document";
-import type { DocumentId, RepresentationId } from "@shared/ids";
 import type { Selector } from "@shared/selector";

 import type { PdfSelectionCapture } from "@anchor/index";
@@ -73,42 +71,8 @@ const SYNTHETIC_CANONICAL = [
  "Post quote.",
 ].join(" ");

-vi.mock("@source/index", async (importOriginal) => {
-  const original = await importOriginal<typeof import("@source/index")>();
-  return {
-    ...original,
-    ingestPdf: vi.fn(async (_input: unknown, options?: { filename?: string }) => {
-      const documentId = ("doc_test_" + Math.random().toString(36).slice(2, 10)) as DocumentId;
-      const representationId = ("rep_test_" + Math.random().toString(36).slice(2, 10)) as RepresentationId;
-      const document: Document = {
-        id: documentId,
-        mediaType: "application/pdf",
-        ...(options?.filename ? { title: options.filename } : {}),
-        fingerprint: "synthetic-fingerprint-for-test",
-        createdAt: "2026-05-25T00:00:00.000Z",
-        updatedAt: "2026-05-25T00:00:00.000Z",
-      };
-      const representation: DocumentRepresentation = {
-        id: representationId,
-        documentId,
-        representationType: "pdf-text",
-        contentHash: "synthetic-fingerprint-for-test",
-        canonicalText: SYNTHETIC_CANONICAL,
-        pageMap: [{ page: 1, width: 595, height: 842 }],
-        offsetMap: [
-          {
-            page: 1,
-            globalStart: 0,
-            globalEnd: SYNTHETIC_CANONICAL.length,
-            pageLength: SYNTHETIC_CANONICAL.length,
-          },
-        ],
-        generatedAt: "2026-05-25T00:00:00.000Z",
-      };
-      return { document, representation };
-    }),
-  };
-});
+// CE-WP-0005: pre-seed a session with the fixture doc; no ingestPdf mock needed.
+import { seedSessionWithDoc } from "./helpers/seed-session";

 function syntheticCaptureFor(text: string, page: number): PdfSelectionCapture {
  return {
@@ -136,15 +100,14 @@ describe("FormsApp — active-evidence cycling (CE-WP-0003-T06)", () => {
  beforeEach(() => {
    resetSnapshot();
    globalThis.localStorage?.clear();
-    globalThis.fetch = vi.fn(async () =>
-      new Response(new Uint8Array([0x25, 0x50, 0x44, 0x46]).buffer, {
-        status: 200,
-        headers: { "Content-Type": "application/pdf" },
-      }),
-    );
    if (typeof window !== "undefined") {
      history.replaceState(null, "", window.location.pathname);
    }
+    seedSessionWithDoc({
+      sessionName: "T06-cycling",
+      documentTitle: FIXTURE.filename,
+      canonicalText: SYNTHETIC_CANONICAL,
+    });
  });

  afterEach(() => {
@@ -157,8 +120,7 @@ describe("FormsApp — active-evidence cycling (CE-WP-0003-T06)", () => {
    await loadApp();

    // --- Review mode: create an evidence item via the captured-selection flow.
-    const fixtureBtn = screen.getByRole("button", { name: new RegExp(FIXTURE.id) });
-    await user.click(fixtureBtn);
+    // CE-WP-0005: doc pre-seeded — skip fixture click.
    await waitFor(() => expect(viewerSnapshot.onSelectionCaptured).not.toBeNull());
    await act(async () => {
      viewerSnapshot.onSelectionCaptured!(
--- a/tests/integration/forms-link-flow.dom.test.tsx
+++ b/tests/integration/forms-link-flow.dom.test.tsx
@@ -22,8 +22,7 @@ import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

-import type { Document, DocumentRepresentation } from "@shared/document";
-import type { AnnotationId, DocumentId, RepresentationId } from "@shared/ids";
+import type { AnnotationId } from "@shared/ids";
 import type { Selector } from "@shared/selector";

 import type { PdfSelectionCapture } from "@anchor/index";
@@ -55,38 +54,8 @@ vi.mock("@anchor/index", async (importOriginal) => {

 const FIXTURE = manifest.fixtures.find((f) => f.id === "fristsetzung-bezifferung")!;

-vi.mock("@source/index", async (importOriginal) => {
-  const original = await importOriginal<typeof import("@source/index")>();
-  return {
-    ...original,
-    ingestPdf: vi.fn(async (_input: unknown, options?: { filename?: string }) => {
-      const documentId = ("doc_test_" + Math.random().toString(36).slice(2, 10)) as DocumentId;
-      const representationId = ("rep_test_" + Math.random().toString(36).slice(2, 10)) as RepresentationId;
-      const synthetic = "Synthetic canonical text for the form-link test.";
-      const document: Document = {
-        id: documentId,
-        mediaType: "application/pdf",
-        ...(options?.filename ? { title: options.filename } : {}),
-        fingerprint: "synthetic-fingerprint-for-test",
-        createdAt: "2026-05-25T00:00:00.000Z",
-        updatedAt: "2026-05-25T00:00:00.000Z",
-      };
-      const representation: DocumentRepresentation = {
-        id: representationId,
-        documentId,
-        representationType: "pdf-text",
-        contentHash: "synthetic-fingerprint-for-test",
-        canonicalText: synthetic,
-        pageMap: [{ page: 1, width: 595, height: 842 }],
-        offsetMap: [
-          { page: 1, globalStart: 0, globalEnd: synthetic.length, pageLength: synthetic.length },
-        ],
-        generatedAt: "2026-05-25T00:00:00.000Z",
-      };
-      return { document, representation };
-    }),
-  };
-});
+// CE-WP-0005: pre-seed a session with the fixture doc; no ingestPdf mock needed.
+import { seedSessionWithDoc } from "./helpers/seed-session";

 async function loadApp() {
  const { App } = await import("@app/App");
@@ -96,12 +65,6 @@ async function loadApp() {
 describe("FormsApp — click-evidence-then-click-field linking (CE-WP-0003-T05)", () => {
  beforeEach(() => {
    globalThis.localStorage?.clear();
-    globalThis.fetch = vi.fn(async () =>
-      new Response(new Uint8Array([0x25, 0x50, 0x44, 0x46]).buffer, {
-        status: 200,
-        headers: { "Content-Type": "application/pdf" },
-      }),
-    );
    // Forms mode is hash-driven; make sure we start clean.
    if (typeof window !== "undefined") {
      history.replaceState(null, "", window.location.pathname);
@@ -114,17 +77,19 @@ describe("FormsApp — click-evidence-then-click-field linking (CE-WP-0003-T05)"
  });

  it("stages an evidence item then links it to the clicked field", async () => {
+    seedSessionWithDoc({
+      sessionName: "T05-link",
+      documentTitle: FIXTURE.filename,
+      canonicalText: "Synthetic canonical text for the form-link test.",
+    });
    const user = userEvent.setup();
    await loadApp();

    // Switch to Forms via the top-bar button.
    await user.click(screen.getByRole("button", { name: "Forms" }));

-    // The collection list is in the Forms layout too.
-    const fixtureBtn = screen.getByRole("button", { name: new RegExp(FIXTURE.id) });
-    await user.click(fixtureBtn);
-
-    // Wait for the fixture to load and the form to appear.
+    // CE-WP-0005: doc is pre-seeded into the active session.
+    // Wait for the form to appear.
    await waitFor(() => {
      expect(screen.queryByLabelText("Summary of the matter")).not.toBeNull();
    });
@@ -170,12 +135,12 @@ describe("FormsApp — click-evidence-then-click-field linking (CE-WP-0003-T05)"
    expect(screen.getByTestId("field-summary-chip").textContent).toMatch(/1 evidence/);
  });

-  it("starts in Review mode by default and switches to Forms via hash", async () => {
+  it("starts in the empty state when no session is active (CE-WP-0005 default)", async () => {
    await loadApp();
-    expect(screen.getByText("Collection")).toBeTruthy();
-    // Review pane's no-doc-open hint from EvidenceSidebar:
-    expect(screen.queryByText(/No document open/)).not.toBeNull();
-    // No demo form rendered yet
+    // The empty-state landing is what users see now until they create
+    // a session.
+    expect(screen.getByTestId("empty-state")).toBeTruthy();
+    // No demo form rendered yet.
    expect(screen.queryByText("Demo evidence-backed form")).toBeNull();
  });
 });
--- a/tests/integration/forms-overlay-e2e.dom.test.tsx
+++ b/tests/integration/forms-overlay-e2e.dom.test.tsx
@@ -27,8 +27,6 @@ import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

-import type { Document, DocumentRepresentation } from "@shared/document";
-import type { DocumentId, RepresentationId } from "@shared/ids";
 import type { Selector } from "@shared/selector";

 import type { PdfSelectionCapture } from "@anchor/index";
@@ -82,37 +80,8 @@ vi.mock("@anchor/index", async (importOriginal) => {
 const FIXTURE = manifest.fixtures.find((f) => f.id === "fristsetzung-bezifferung")!;
 const SYNTHETIC_CANONICAL = ["Pre.", FIXTURE.known_good_quote, "Post."].join(" ");

-vi.mock("@source/index", async (importOriginal) => {
-  const original = await importOriginal<typeof import("@source/index")>();
-  return {
-    ...original,
-    ingestPdf: vi.fn(async (_input: unknown, options?: { filename?: string }) => {
-      const documentId = ("doc_test_" + Math.random().toString(36).slice(2, 10)) as DocumentId;
-      const representationId = ("rep_test_" + Math.random().toString(36).slice(2, 10)) as RepresentationId;
-      const document: Document = {
-        id: documentId,
-        mediaType: "application/pdf",
-        ...(options?.filename ? { title: options.filename } : {}),
-        fingerprint: "synthetic-fingerprint-for-test",
-        createdAt: "2026-05-25T00:00:00.000Z",
-        updatedAt: "2026-05-25T00:00:00.000Z",
-      };
-      const representation: DocumentRepresentation = {
-        id: representationId,
-        documentId,
-        representationType: "pdf-text",
-        contentHash: "synthetic-fingerprint-for-test",
-        canonicalText: SYNTHETIC_CANONICAL,
-        pageMap: [{ page: 1, width: 595, height: 842 }],
-        offsetMap: [
-          { page: 1, globalStart: 0, globalEnd: SYNTHETIC_CANONICAL.length, pageLength: SYNTHETIC_CANONICAL.length },
-        ],
-        generatedAt: "2026-05-25T00:00:00.000Z",
-      };
-      return { document, representation };
-    }),
-  };
-});
+// CE-WP-0005: pre-seed a session with the fixture doc; no ingestPdf mock needed.
+import { seedSessionWithDoc } from "./helpers/seed-session";

 function syntheticCaptureFor(text: string, page: number): PdfSelectionCapture {
  return {
@@ -135,15 +104,14 @@ describe("CE-WP-0003-T08 — PRD scenario steps 5-9 end-to-end", () => {
    viewerSnapshot.scrollToAnnotationId = null;
    viewerSnapshot.onSelectionCaptured = null;
    globalThis.localStorage?.clear();
-    globalThis.fetch = vi.fn(async () =>
-      new Response(new Uint8Array([0x25, 0x50, 0x44, 0x46]).buffer, {
-        status: 200,
-        headers: { "Content-Type": "application/pdf" },
-      }),
-    );
    if (typeof window !== "undefined") {
      history.replaceState(null, "", window.location.pathname);
    }
+    seedSessionWithDoc({
+      sessionName: "T08-forms",
+      documentTitle: FIXTURE.filename,
+      canonicalText: SYNTHETIC_CANONICAL,
+    });
  });

  afterEach(() => {
@@ -159,8 +127,7 @@ describe("CE-WP-0003-T08 — PRD scenario steps 5-9 end-to-end", () => {
      await loadApp();

      // Steps 1-4 (CE-WP-0002 setup): create an evidence item in Review mode.
-      const fixtureBtn = screen.getByRole("button", { name: new RegExp(FIXTURE.id) });
-      await user.click(fixtureBtn);
+      // CE-WP-0005: doc pre-seeded into the session — skip fixture click.
      await waitFor(() => expect(viewerSnapshot.onSelectionCaptured).not.toBeNull());
      await act(async () => {
        viewerSnapshot.onSelectionCaptured!(
@@ -175,9 +142,10 @@ describe("CE-WP-0003-T08 — PRD scenario steps 5-9 end-to-end", () => {
      await user.click(screen.getByRole("button", { name: /Save evidence/ }));
      await screen.findByText(/Overlay E2E evidence/);

-      // Step 5: navigate to /forms/demo via the top-bar.
+      // Step 5: navigate to forms via the top-bar.
      await user.click(screen.getByRole("button", { name: "Forms" }));
-      expect(window.location.hash).toBe("#/forms/demo");
+      // CE-WP-0005: route is now session-scoped.
+      expect(window.location.hash).toMatch(/^#\/s\/sess_[^/]+\/forms\/demo$/);

      // Step 6: stage the evidence in the strip, then click the summary
      // field to create the link.
--- a/tests/integration/helpers/seed-session.ts
+++ b/tests/integration/helpers/seed-session.ts
@@ -0,0 +1,116 @@
+/**
+ * Test helper: pre-seed `localStorage` with an active session that holds
+ * one document + one representation, so an integration test can skip
+ * the empty-state + upload flow and mount straight into a populated
+ * Review/Forms layout.
+ *
+ * Pre-CE-WP-0005 integration tests clicked a "fixture button" in the
+ * `CollectionList` to load a sample PDF; after the session refactor
+ * there is no fixture list directly in the active-session UI. These
+ * legacy tests now call `seedSessionWithDoc` in `beforeEach` instead.
+ *
+ * The seed bypasses `SessionService.create()` (which mints a random
+ * id) so tests can reference the resulting `documentId` /
+ * `representationId` synchronously, before the app boots.
+ */
+
+import type { Document, DocumentRepresentation } from "@shared/document";
+import type { DocumentId, RepresentationId, SessionId } from "@shared/ids";
+import type { Session } from "@shared/session";
+
+export interface SeedOptions {
+  readonly sessionName?: string;
+  readonly documentTitle?: string;
+  readonly canonicalText: string;
+  readonly mode?: "review" | "forms";
+}
+
+export interface SeedResult {
+  readonly sessionId: SessionId;
+  readonly documentId: DocumentId;
+  readonly representationId: RepresentationId;
+}
+
+function rid(prefix: string): string {
+  return `${prefix}_seed_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function seedSessionWithDoc(opts: SeedOptions): SeedResult {
+  const sessionId = rid("sess") as SessionId;
+  const documentId = rid("doc") as DocumentId;
+  const representationId = rid("rep") as RepresentationId;
+  const now = "2026-05-25T00:00:00.000Z";
+
+  const session: Session = {
+    id: sessionId,
+    name: opts.sessionName ?? "Test Session",
+    createdAt: now,
+    updatedAt: now,
+    lastOpenedAt: now,
+  };
+
+  const document: Document = {
+    id: documentId,
+    mediaType: "application/pdf",
+    ...(opts.documentTitle ? { title: opts.documentTitle } : {}),
+    fingerprint: "seed-fingerprint",
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  const representation: DocumentRepresentation = {
+    id: representationId,
+    documentId,
+    representationType: "pdf-text",
+    contentHash: "seed-fingerprint",
+    canonicalText: opts.canonicalText,
+    pageMap: [{ page: 1, width: 595, height: 842 }],
+    offsetMap: [
+      {
+        page: 1,
+        globalStart: 0,
+        globalEnd: opts.canonicalText.length,
+        pageLength: opts.canonicalText.length,
+      },
+    ],
+    generatedAt: now,
+  };
+
+  const snapshot = {
+    version: 1,
+    documents: [document],
+    representations: [representation],
+    annotations: [],
+    evidenceItems: [],
+  };
+
+  const sessionsFile = {
+    version: 1,
+    sessions: [session],
+    activeSessionId: sessionId,
+  };
+
+  localStorage.setItem("citation-evidence:sessions:v1", JSON.stringify(sessionsFile));
+  localStorage.setItem("citation-evidence:active-session-id:v1", sessionId);
+  localStorage.setItem(
+    `citation-evidence:session:${sessionId}:engine-snapshot:v1`,
+    JSON.stringify(snapshot),
+  );
+  localStorage.setItem(
+    `citation-evidence:session:${sessionId}:active-document-id:v1`,
+    documentId,
+  );
+
+  // Set the hash so the App routes straight into the session.
+  const hash =
+    opts.mode === "forms"
+      ? `#/s/${sessionId}/forms/demo`
+      : `#/s/${sessionId}`;
+  history.replaceState(
+    null,
+    "",
+    window.location.pathname + window.location.search + hash,
+  );
+
+  return { sessionId, documentId, representationId };
+}
--- a/tests/integration/session-export-reimport.dom.test.tsx
+++ b/tests/integration/session-export-reimport.dom.test.tsx
@@ -0,0 +1,350 @@
+/**
+ * CE-WP-0005-T08 — full create → annotate → export → reimport E2E.
+ *
+ * Walks the demo loop end-to-end:
+ *
+ *   1.  Load app → empty state.
+ *   2.  Create session "Demo" via the inline name input.
+ *   3.  Upload a synthetic PDF.
+ *   4.  Inject a selection for the manifest's known-good quote → save
+ *       evidence with a commentary.
+ *   5.  (Sanity) Click Export → Copy as Markdown; assert the clipboard
+ *       payload contains the quote + commentary + openContextUrl.
+ *   6.  Click Export ZIP; capture the Blob via a URL.createObjectURL
+ *       spy.
+ *   7.  Click Import ZIP with the captured Blob; assert merge:
+ *       - one document (deduped by fingerprint)
+ *       - two evidence rows (additive merge)
+ *   8.  Click Export → Copy as Markdown on the merged evidence; assert
+ *       the citation card text matches the original.
+ */
+
+// @vitest-environment happy-dom
+
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { Document, DocumentRepresentation } from "@shared/document";
+import type { DocumentId, RepresentationId } from "@shared/ids";
+import type { Selector } from "@shared/selector";
+import type { PdfSelectionCapture } from "@anchor/index";
+import manifest from "../../fixtures/pdfs/manifest.json" with { type: "json" };
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+interface ViewerProps {
+  pdfUrl: string;
+  storedAnnotations: readonly { id: string; text: string; selectors: readonly Selector[] }[];
+  scrollToAnnotationId?: string;
+  onSelectionCaptured(capture: PdfSelectionCapture, selectors: Selector[]): void;
+}
+
+interface ViewerSnapshot {
+  pdfUrl: string | null;
+  onSelectionCaptured: ViewerProps["onSelectionCaptured"] | null;
+}
+
+const viewerSnapshot: ViewerSnapshot = {
+  pdfUrl: null,
+  onSelectionCaptured: null,
+};
+
+vi.mock("@anchor/index", async (importOriginal) => {
+  const original = await importOriginal<typeof import("@anchor/index")>();
+  const MockPdfSpikeViewer = (props: ViewerProps) => {
+    viewerSnapshot.pdfUrl = props.pdfUrl;
+    viewerSnapshot.onSelectionCaptured = props.onSelectionCaptured;
+    return <div data-testid="mock-pdf-viewer" />;
+  };
+  return { ...original, PdfSpikeViewer: MockPdfSpikeViewer };
+});
+
+const FIXTURE = manifest.fixtures.find((f) => f.id === "fristsetzung-bezifferung")!;
+const SYNTHETIC_CANONICAL = ["Pre.", FIXTURE.known_good_quote, "Post."].join(" ");
+
+// Bypass real PDF.js extraction. The mock returns a stable fingerprint
+// so the merge-on-fingerprint dedup logic actually fires on re-import.
+vi.mock("@source/index", async (importOriginal) => {
+  const original = await importOriginal<typeof import("@source/index")>();
+  let counter = 0;
+  return {
+    ...original,
+    ingestPdfFromFile: vi.fn(
+      async (file: File | Blob, store: import("@source/index").PdfByteStore) => {
+        counter += 1;
+        const filename =
+          "name" in file && typeof file.name === "string" ? file.name : "uploaded.pdf";
+        const documentId = ("doc_e2e_" + counter) as DocumentId;
+        const representationId = ("rep_e2e_" + counter) as RepresentationId;
+        const bytes = new Uint8Array(await file.arrayBuffer());
+        const record = store.put(documentId, bytes);
+        const document: Document = {
+          id: documentId,
+          mediaType: "application/pdf",
+          title: filename,
+          uri: record.blobUrl,
+          // Stable fingerprint — the importer dedupes by fingerprint, so
+          // re-importing the export merges into the same doc.
+          fingerprint: "fp-stable-e2e",
+          createdAt: "2026-05-25T00:00:00.000Z",
+          updatedAt: "2026-05-25T00:00:00.000Z",
+        };
+        const representation: DocumentRepresentation = {
+          id: representationId,
+          documentId,
+          representationType: "pdf-text",
+          contentHash: "fp-stable-e2e",
+          canonicalText: SYNTHETIC_CANONICAL,
+          pageMap: [{ page: 1, width: 595, height: 842 }],
+          offsetMap: [
+            {
+              page: 1,
+              globalStart: 0,
+              globalEnd: SYNTHETIC_CANONICAL.length,
+              pageLength: SYNTHETIC_CANONICAL.length,
+            },
+          ],
+          generatedAt: "2026-05-25T00:00:00.000Z",
+        };
+        return { document, representation };
+      },
+    ),
+  };
+});
+
+// ---------------------------------------------------------------------------
+// Test-time intercepts: clipboard, URL.createObjectURL, file-picker input.
+// ---------------------------------------------------------------------------
+
+function syntheticCaptureFor(text: string, page: number): PdfSelectionCapture {
+  return {
+    kind: "pdf",
+    text,
+    page,
+    rects: [{ x: 0.1, y: 0.2, width: 0.4, height: 0.04 }],
+    boundingRect: { x: 0.1, y: 0.2, width: 0.4, height: 0.04 },
+  };
+}
+
+let writeText: ReturnType<typeof vi.fn>;
+function installClipboardSpy() {
+  writeText = vi.fn(async () => undefined);
+  const proto = Object.getPrototypeOf(navigator.clipboard);
+  Object.defineProperty(proto, "writeText", {
+    configurable: true,
+    writable: true,
+    value: writeText,
+  });
+}
+
+interface UrlInterceptor {
+  blobs: Blob[];
+  restore(): void;
+}
+function installUrlInterceptor(): UrlInterceptor {
+  const blobs: Blob[] = [];
+  const origCreate = URL.createObjectURL;
+  const origRevoke = URL.revokeObjectURL;
+  let counter = 0;
+  URL.createObjectURL = ((b: Blob) => {
+    blobs.push(b);
+    counter += 1;
+    return `blob:test-${counter}`;
+  }) as typeof URL.createObjectURL;
+  URL.revokeObjectURL = (() => {}) as typeof URL.revokeObjectURL;
+  return {
+    blobs,
+    restore() {
+      URL.createObjectURL = origCreate;
+      URL.revokeObjectURL = origRevoke;
+    },
+  };
+}
+
+interface FilePickerInterceptor {
+  inputs: HTMLInputElement[];
+  restore(): void;
+}
+function installFilePickerInterceptor(): FilePickerInterceptor {
+  const inputs: HTMLInputElement[] = [];
+  const origCreate = document.createElement.bind(document);
+  (document.createElement as unknown) = (tag: string) => {
+    const el = origCreate(tag);
+    if (tag === "input") inputs.push(el as HTMLInputElement);
+    return el;
+  };
+  return {
+    inputs,
+    restore() {
+      document.createElement = origCreate;
+    },
+  };
+}
+
+async function loadApp() {
+  const { App } = await import("@app/App");
+  return render(<App />);
+}
+
+// ---------------------------------------------------------------------------
+// Test
+// ---------------------------------------------------------------------------
+
+describe("CE-WP-0005-T08 — full create → annotate → export → reimport E2E", () => {
+  let url: UrlInterceptor;
+  let picker: FilePickerInterceptor;
+
+  beforeEach(() => {
+    viewerSnapshot.pdfUrl = null;
+    viewerSnapshot.onSelectionCaptured = null;
+    globalThis.localStorage?.clear();
+    if (typeof window !== "undefined") {
+      history.replaceState(null, "", window.location.pathname);
+    }
+    url = installUrlInterceptor();
+    picker = installFilePickerInterceptor();
+  });
+
+  afterEach(() => {
+    cleanup();
+    url.restore();
+    picker.restore();
+    vi.restoreAllMocks();
+  });
+
+  it(
+    "creates session, annotates, exports ZIP, re-imports ZIP, and round-trips the citation card",
+    { timeout: 30000 },
+    async () => {
+      const user = userEvent.setup();
+      await loadApp();
+
+      // Step 1: empty state.
+      await screen.findByTestId("empty-state");
+
+      // Step 2: create session "Demo".
+      const nameInput = screen.getByTestId("empty-state-input");
+      await user.type(nameInput, "Demo");
+      await user.click(screen.getByTestId("empty-state-create"));
+
+      // Wait for the active session UI (collection list + upload dropzone).
+      await screen.findByTestId("upload-dropzone");
+
+      // Step 3: upload a synthetic PDF.
+      installClipboardSpy();
+      const fileBytes = new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d]); // %PDF-
+      const pdfFile = new File([fileBytes], "e2e.pdf", { type: "application/pdf" });
+      const uploadInput = screen.getByTestId("upload-file-input") as HTMLInputElement;
+      await user.upload(uploadInput, pdfFile);
+
+      // Wait for the viewer to mount with the uploaded doc.
+      await waitFor(() => expect(viewerSnapshot.onSelectionCaptured).not.toBeNull());
+
+      // Step 4: inject a selection + save evidence with commentary.
+      await act(async () => {
+        viewerSnapshot.onSelectionCaptured!(
+          syntheticCaptureFor(FIXTURE.known_good_quote, FIXTURE.known_good_quote_page),
+          [{ type: "TextQuoteSelector", exact: FIXTURE.known_good_quote }],
+        );
+      });
+      await user.type(
+        screen.getByPlaceholderText(/Add a one-line comment/),
+        "E2E session commentary",
+      );
+      await user.click(screen.getByRole("button", { name: /Save evidence/ }));
+      await screen.findByText(/E2E session commentary/);
+
+      // Step 5 (sanity): export the evidence as Markdown via the sidebar.
+      installClipboardSpy();
+      await user.click(await screen.findByLabelText("Export evidence item"));
+      await user.click(await screen.findByRole("menuitem", { name: "Copy as Markdown" }));
+      await waitFor(() => expect(writeText).toHaveBeenCalled());
+      const firstCard = writeText.mock.calls[0]![0] as string;
+      expect(firstCard).toContain(FIXTURE.known_good_quote);
+      expect(firstCard).toContain("E2E session commentary");
+      expect(firstCard).toMatch(/\/viewer\?document=doc_[^&]+&annotation=ann_[^)]+/);
+
+      // Step 6: click Export ZIP from the session menu and capture the
+      // generated Blob via the URL.createObjectURL spy.
+      const urlCountBeforeExport = url.blobs.length;
+      await user.click(screen.getByTestId("session-menu-toggle"));
+      await user.click(await screen.findByTestId("session-menu-export"));
+      await waitFor(() => expect(url.blobs.length).toBeGreaterThan(urlCountBeforeExport));
+      // The exported ZIP is the most-recently-minted blob URL'd to <a download>.
+      const zipBlob = url.blobs[url.blobs.length - 1]!;
+      expect(zipBlob.size).toBeGreaterThan(0);
+
+      // Step 7: import the ZIP back via the menu. Intercept the file
+      // input the App opens, set our captured blob as its file, fire
+      // change.
+      const inputsBefore = picker.inputs.length;
+      await user.click(screen.getByTestId("session-menu-toggle"));
+      await user.click(await screen.findByTestId("session-menu-import"));
+      // The handler created a new file input.
+      await waitFor(() => expect(picker.inputs.length).toBeGreaterThan(inputsBefore));
+      const importInput = picker.inputs[picker.inputs.length - 1]!;
+      const zipFile = new File([await zipBlob.arrayBuffer()], "demo.zip", {
+        type: "application/zip",
+      });
+      // happy-dom's `files` is a getter on HTMLInputElement.prototype;
+      // a value-override on the instance silently doesn't take effect.
+      // Replace with a property getter that returns our fake FileList.
+      const fakeFileList = {
+        0: zipFile,
+        length: 1,
+        item: (i: number) => (i === 0 ? zipFile : null),
+        [Symbol.iterator]: function* () {
+          yield zipFile;
+        },
+      };
+      Object.defineProperty(importInput, "files", {
+        configurable: true,
+        get: () => fakeFileList,
+      });
+      await act(async () => {
+        if (typeof importInput.onchange === "function") {
+          importInput.onchange(new Event("change"));
+        }
+        // Yield so the import promise gets a chance to start.
+        await new Promise((r) => setTimeout(r, 0));
+      });
+
+      // Wait for the merge to manifest in the DOM. ADR-0008's additive
+      // policy means we should now see TWO evidence rows for the same
+      // commentary (the original + the imported copy), and the
+      // collection should still show ONE document (deduped by
+      // fingerprint).
+      await waitFor(
+        () => {
+          const matches = screen.queryAllByText(/E2E session commentary/);
+          expect(matches.length).toBeGreaterThanOrEqual(2);
+        },
+        { timeout: 12000 },
+      );
+
+      await waitFor(() => {
+        const items = screen
+          .getByTestId("collection-list-items")
+          .querySelectorAll("li");
+        expect(items.length).toBe(1);
+      });
+
+      // Step 8: export the *merged* evidence as Markdown and assert the
+      // round-trip preserves quote + commentary + URL shape.
+      installClipboardSpy();
+      const toggles = screen.getAllByLabelText("Export evidence item");
+      // Use the last evidence row (the one from the import) just to
+      // distinguish from the original.
+      await user.click(toggles[toggles.length - 1]!);
+      await user.click(await screen.findByRole("menuitem", { name: "Copy as Markdown" }));
+      await waitFor(() => expect(writeText).toHaveBeenCalled());
+      const mergedCard = writeText.mock.calls[0]![0] as string;
+      expect(mergedCard).toContain(FIXTURE.known_good_quote);
+      expect(mergedCard).toContain("E2E session commentary");
+      expect(mergedCard).toMatch(/\/viewer\?document=doc_[^&]+&annotation=ann_[^)]+/);
+    },
+  );
+});