Implement CE-WP-0003 T01-T08: form binding + visual guide overlay

T01 EvidenceLink/EvidenceSet types
  - src/shared/evidence-link.ts: status (§2.4), relation (§2.5), target
  - src/shared/evidence-set.ts: ordered group + activeEvidenceItemId
  - enum-conformance test parses SharedContracts.md and asserts the
    runtime lists match exactly

T02 Binding service + in-memory link repo + active-state machine
  - src/binder/repos/in-memory-links.ts: Map-backed EvidenceLinkRepository
  - src/binder/services/bindings.ts: link/unlink/list/update/setActive
    emitting §4 EvidenceLinkCreated / EvidenceLinkUpdated /
    EvidenceItemActivated
  - src/binder/state/active.ts: (target, evidence, annotation) reducer
    + ActiveStateProvider + useActiveState hook
  - extended engine/events/types.ts with EvidenceLinkCreated,
    EvidenceLinkUpdated, FormFieldActivated payloads

T03 Rect registry (SharedContracts §7 — contract FROZEN)
  - src/binder/visual-guide/rect-registry.ts: register/getRect/subscribe
    + invalidate + getVersion for useSyncExternalStore
  - events.ts: scroll/resize/focus pumps via window + ResizeObserver +
    IntersectionObserver, rAF-throttled
  - react-hooks.ts: RectRegistryProvider, useRegisterRect(kind,id,ref),
    useRectRegistryVersion

T04 Form schema + renderer
  - src/app/forms/demo-schema.ts: text/textarea/date minimal schema
  - src/binder/FormRenderer.tsx: renders schema, each field registers
    as rect kind="field"; active field gets aria-current="true"
  - placed in binder/ (not work/) because work cannot import binder per
    DependencyMap.md §2 and the renderer needs the rect-registry hook;
    workplan T04 was amended in-place to document this

T05 Side-by-side Forms layout + click-to-link
  - src/app/forms/FormsApp.tsx + src/app/App.tsx top-bar router with
    hash route #/forms/demo
  - BinderProvider mounted at app root so links survive tab switching
  - stage-evidence-then-click-field linking interaction with banner
    + per-field link-count chip

T06 Active-evidence cycling
  - src/app/forms/ActiveEvidenceChips.tsx: chips per active target,
    Tab cycles natively, first chip auto-activates on field focus,
    each chip registers as rect kind="evidence-card"
  - ScrollBridge in FormsApp wires activeAnnotationId to viewer scroll
  - EvidenceSidebar + EvidenceStrip highlight the active item via the
    new useLastActivatedEvidence hook in work/EngineContext

T07 SVG visual-guide overlay
  - src/binder/visual-guide/Overlay.tsx: single fixed-positioned SVG,
    draws field→card and card→highlight bezier curves for the active
    triple, rAF-throttled via the registry
  - src/anchor exposes getHighlightClientRects(annotationId); the
    spike viewer wraps highlights in [data-highlight-id] so the helper
    can locate them
  - src/app/forms/HighlightRectBridge.tsx: registers the active
    annotation's rect via that helper

T08 End-to-end test (PRD scenario steps 5-9)
  - tests/integration/forms-overlay-e2e.dom.test.tsx: full path from
    Review-mode capture through Forms-mode link to active triple +
    aria-current assertions + 2 SVG paths in the overlay
  - additional integration coverage: forms-link-flow + forms-active-cycling

Gates: typecheck ✓ · lint ✓ · build ✓ · 152/152 tests across 21 files.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

tests/integration/forms-overlay-e2e.dom.test.tsx

@@ -0,0 +1,218 @@
+/**
+ * CE-WP-0003-T08 — end-to-end test of the form-binding slice (PRD
+ * scenario steps 5-9 from CE-WP-0002-T09's continuation):
+ *
+ *   5. Navigate to /forms/demo (hash route).
+ *   6. Link the previously-created evidence item to the "summary" field.
+ *   7. Click the "summary" field.
+ *   8. The field, the evidence card, and the highlight all have
+ *      aria-current="true".
+ *   9. The SVG visual-guide overlay contains exactly two <path> elements
+ *      (one field→card, one card→highlight).
+ *
+ * The viewer is mocked (same pattern as CE-WP-0002-T09) and
+ * `getHighlightClientRects` is stubbed to return a non-null DOMRect so
+ * the HighlightRectBridge can register a highlight rect — without that
+ * stub there is no real highlight DOM for the bridge to find.
+ *
+ * Step 10 (scroll → paths update next frame) is exercised by
+ * `Overlay.dom.test.tsx`'s invalidate-on-rect-change case; reproducing
+ * it through the full app stack would require driving the rAF scheduler
+ * deterministically, which is overkill given the dedicated unit test.
+ */
+
+// @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" };
+
+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;
+  scrollToAnnotationId: string | null;
+  onSelectionCaptured: ViewerProps["onSelectionCaptured"] | null;
+}
+
+const viewerSnapshot: ViewerSnapshot = {
+  pdfUrl: null,
+  scrollToAnnotationId: null,
+  onSelectionCaptured: null,
+};
+
+function fakeHighlightRect(): DOMRect {
+  // happy-dom may not expose a stable DOMRect constructor; use a literal.
+  return {
+    x: 700, y: 400, width: 200, height: 20,
+    top: 400, left: 700, right: 900, bottom: 420,
+    toJSON() { return {}; },
+  } as DOMRect;
+}
+
+vi.mock("@anchor/index", async (importOriginal) => {
+  const original = await importOriginal<typeof import("@anchor/index")>();
+  const MockPdfSpikeViewer = (props: ViewerProps) => {
+    viewerSnapshot.pdfUrl = props.pdfUrl;
+    viewerSnapshot.scrollToAnnotationId = props.scrollToAnnotationId ?? null;
+    viewerSnapshot.onSelectionCaptured = props.onSelectionCaptured;
+    return <div data-testid="mock-pdf-viewer" />;
+  };
+  return {
+    ...original,
+    PdfSpikeViewer: MockPdfSpikeViewer,
+    // Always return a non-null rect so the HighlightRectBridge has
+    // something to register and the Overlay can draw the second leg.
+    getHighlightClientRects: vi.fn(() => fakeHighlightRect()),
+  };
+});
+
+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 };
+    }),
+  };
+});
+
+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("CE-WP-0003-T08 — PRD scenario steps 5-9 end-to-end", () => {
+  beforeEach(() => {
+    viewerSnapshot.pdfUrl = null;
+    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);
+    }
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    cleanup();
+  });
+
+  it(
+    "navigates to /forms/demo, links evidence, focuses field, asserts active triple + 2 SVG paths",
+    { timeout: 15000 },
+    async () => {
+      const user = userEvent.setup();
+      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);
+      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.getByPlaceholderText(/Add a one-line comment/),
+        "Overlay E2E evidence",
+      );
+      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.
+      await user.click(screen.getByRole("button", { name: "Forms" }));
+      expect(window.location.hash).toBe("#/forms/demo");
+
+      // Step 6: stage the evidence in the strip, then click the summary
+      // field to create the link.
+      const stripCard = await screen.findByRole("button", {
+        name: /Overlay E2E evidence/,
+      });
+      await user.click(stripCard);
+      const summaryField = screen.getByLabelText("Summary of the matter");
+      await user.click(summaryField);
+
+      // Move focus elsewhere and back to re-fire focus on summary so that
+      // ActiveStateProvider triggers focus-target (the previous click that
+      // created the link consumed the staged state).
+      await user.click(screen.getByLabelText("Disputed amount"));
+      await user.click(summaryField);
+
+      // Step 8: aria-current on field row, chip, and (via the active
+      // state) the strip card.
+      await waitFor(() => {
+        const fieldRow = document.querySelector(
+          '[data-field-id="summary"][aria-current="true"]',
+        );
+        expect(fieldRow).not.toBeNull();
+      });
+      const activeChip = document.querySelector('[data-evidence-id][aria-current="true"]');
+      expect(activeChip).not.toBeNull();
+
+      // Step 9: SVG overlay renders 2 paths (field→card + card→highlight).
+      // HighlightRectBridge registers via the mocked getHighlightClientRects.
+      await waitFor(() => {
+        const svg = document.querySelector('[data-testid="visual-guide-overlay"]');
+        expect(svg).not.toBeNull();
+        expect(svg!.getAttribute("data-path-count")).toBe("2");
+        expect(svg!.querySelectorAll("path").length).toBe(2);
+      });
+    },
+  );
+});