CE-WP-0006/0007: Capture view polish, workplans, and UX refinements

- Blob URL stability, scroll centre, strip-only visual guide
- Focus-gated linking, unlink clears overlay, field badge tooltips
- Capture layout (viewer centre), grey guide lines, Add field button
- Workplans CE-WP-0006 (done) and CE-WP-0007 (T01-T09 done, T10-T12 todo)
- Integration tests and viewer-url helpers

tests/integration/forms-link-flow.dom.test.tsx

@@ -1,19 +1,9 @@
 /**
- * CE-WP-0003-T05 integration — the side-by-side Forms layout +
- * click-evidence-then-click-field linking interaction.
+ * CE-WP-0003-T05 / CE-WP-0006-T05 — bidirectional evidence ↔ field linking.
  *
- * Mirrors `app-prd-scenario.dom.test.tsx` (T09 of CE-WP-0002):
- *   - mocks `@anchor/index` to swap PdfSpikeViewer for an inert div
- *   - mocks `@source/index.ingestPdf` to skip PDF.js
- *
- * The flow:
- *   1. Render <App />, switch to Forms mode via the top-bar button.
- *   2. Open the fixture (CollectionList click).
- *   3. Seed an EvidenceItem directly via the engine (creating one through
- *      the UI requires Review mode and is exercised by T09).
- *   4. Click the evidence card in the strip → staged for linking.
- *   5. Click a form field → BindingService.linkEvidenceToTarget called.
- *   6. The field's link-count chip shows "1 evidence".
+ * Flow:
+ *   1. Review mode: seed session, capture selection, save evidence.
+ *   2. Capture mode: field-focus-gated direct link (focus field, click card).
  */
 
 // @vitest-environment happy-dom
@@ -22,7 +12,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 { AnnotationId } from "@shared/ids";
 import type { Selector } from "@shared/selector";
 
 import type { PdfSelectionCapture } from "@anchor/index";
@@ -35,37 +24,65 @@ interface ViewerProps {
   onSelectionCaptured(capture: PdfSelectionCapture, selectors: Selector[]): void;
 }
 
+interface ViewerSnapshot {
+  onSelectionCaptured: ViewerProps["onSelectionCaptured"] | null;
+}
+
+const viewerSnapshot: ViewerSnapshot = { onSelectionCaptured: null };
+
 vi.mock("@anchor/index", async (importOriginal) => {
   const original = await importOriginal<typeof import("@anchor/index")>();
   const MockPdfSpikeViewer = (props: ViewerProps) => {
-    return (
-      <div
-        data-testid="mock-pdf-viewer"
-        data-pdf-url={props.pdfUrl}
-        data-stored-count={String(props.storedAnnotations.length)}
-      />
-    );
-  };
-  return {
-    ...original,
-    PdfSpikeViewer: MockPdfSpikeViewer,
+    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(" ");
 
-// 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 {
+    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 },
+  };
+}
+
 async function loadApp() {
   const { App } = await import("@app/App");
   return render(<App />);
 }
 
-describe("FormsApp — click-evidence-then-click-field linking (CE-WP-0003-T05)", () => {
+async function saveEvidenceInReview(
+  user: ReturnType<typeof userEvent.setup>,
+  commentary: string,
+) {
+  await waitFor(() => expect(viewerSnapshot.onSelectionCaptured).not.toBeNull());
+  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.getByTestId("inline-capture-commentary"), commentary);
+  await user.click(screen.getByTestId("inline-capture-save"));
+  await screen.findByText(new RegExp(commentary));
+}
+
+describe("FormsApp — focus-gated linking (CE-WP-0007-T02)", () => {
   beforeEach(() => {
+    viewerSnapshot.onSelectionCaptured = null;
     globalThis.localStorage?.clear();
-    // Forms mode is hash-driven; make sure we start clean.
     if (typeof window !== "undefined") {
       history.replaceState(null, "", window.location.pathname);
     }
@@ -76,74 +93,64 @@ describe("FormsApp — click-evidence-then-click-field linking (CE-WP-0003-T05)"
     cleanup();
   });
 
-  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();
+  it(
+    "links when field has focus: focus field then click strip card",
+    { timeout: 15000 },
+    async () => {
+      seedSessionWithDoc({
+        sessionName: "T05-field-first",
+        documentTitle: FIXTURE.filename,
+        canonicalText: SYNTHETIC_CANONICAL,
+      });
+      const user = userEvent.setup();
+      await loadApp();
+      await saveEvidenceInReview(user, "Field-first link test");
 
-    // Switch to Forms via the top-bar button.
-    await user.click(screen.getByRole("button", { name: "Forms" }));
+      await user.click(screen.getByRole("button", { name: "Capture" }));
+      await screen.findByRole("button", { name: /Field-first link test/ });
 
-    // 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();
-    });
+      await user.click(screen.getByLabelText("Disputed amount"));
+      const stripCard = screen.getByRole("button", {
+        name: /Field-first link test/,
+      });
+      await user.click(stripCard);
 
-    // Seed an EvidenceItem directly via the engine. We grab it through the
-    // EvidenceStrip empty-state lifecycle: capture an item via a mock
-    // dispatch. Since the engine is wrapped inside EngineProvider, we
-    // reach it by emitting a synthetic AnnotationCreated → EvidenceItem
-    // via window for testing isn't easy. Simpler: import the engine
-    // module directly and wire a parallel engine into the rendered app
-    // by patching localStorage. Even simpler for T05: drive the
-    // BindingService through its public API by talking to the engine
-    // through a getter we expose on window for tests.
-    //
-    // The smallest hack: drive engine.evidence.create + annotations.create
-    // by reaching through the engine instance the persister stores in
-    // localStorage. The persister key is "citation-evidence:engine-snapshot:v1".
-    // But the engine hasn't persisted yet — it has no events.
-    //
-    // The cleanest path: use a test-only window hook. We add it during
-    // the next iteration when wiring the active-cycling. For T05 the
-    // proof is the link-creation pipeline given a staged item — we
-    // dispatch the staged event manually with a synthetic id and verify
-    // that clicking a field triggers a link.
-    const SYNTHETIC_EV_ID = "ev_test_synthetic" as const;
-    await act(async () => {
-      window.dispatchEvent(
-        new CustomEvent("citation-evidence:staged-for-linking", {
-          detail: SYNTHETIC_EV_ID,
-        }),
-      );
-    });
+      await waitFor(() => {
+        expect(screen.getByTestId("field-amount-chip").textContent).toMatch(
+          /1 evidence/,
+        );
+      });
+    },
+  );
 
-    // Click the Summary field → triggers FormFieldActivated → BindingService
-    // creates the link.
-    const summaryField = screen.getByLabelText("Summary of the matter");
-    await user.click(summaryField);
+  it(
+    "does not link when no field is focused",
+    { timeout: 15000 },
+    async () => {
+      seedSessionWithDoc({
+        sessionName: "T07-no-focus",
+        documentTitle: FIXTURE.filename,
+        canonicalText: SYNTHETIC_CANONICAL,
+      });
+      const user = userEvent.setup();
+      await loadApp();
+      await saveEvidenceInReview(user, "No-focus link test");
 
-    // The chip on the Summary field should now show 1 evidence.
-    await waitFor(() => {
-      expect(screen.queryByTestId("field-summary-chip")).not.toBeNull();
-    });
-    expect(screen.getByTestId("field-summary-chip").textContent).toMatch(/1 evidence/);
-  });
+      await user.click(screen.getByRole("button", { name: "Capture" }));
+      const stripCard = await screen.findByRole("button", {
+        name: /No-focus link test/,
+      });
+      await user.click(stripCard);
+
+      expect(screen.queryByTestId("field-summary-chip")).toBeNull();
+      expect(screen.queryByTestId("field-amount-chip")).toBeNull();
+    },
+  );
 
   it("starts in the empty state when no session is active (CE-WP-0005 default)", async () => {
-    await loadApp();
-    // 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.
+    const { unmount } = await loadApp();
+    expect(screen.getAllByTestId("empty-state").length).toBeGreaterThanOrEqual(1);
     expect(screen.queryByText("Demo evidence-backed form")).toBeNull();
+    unmount();
   });
-});
-
-// Silence unused-import warnings for type-only imports referenced via JSX.
-void ((): AnnotationId | null => null);
+});