coulomb/citation-evidence
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
Bernd Worsch
2026-06-08 00:37:34 +02:00
parent d25b01f6d5
commit 2fd085b65e
26 changed files with 1767 additions and 356 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
tests/integration/anchor-source-roundtrip.test.ts
View File

@@ -42,7 +42,7 @@ beforeAll(async () => {
);
});
describe("create + resolve round-trip — fixture corpus", () => {
describe("create + resolve round-trip — fixture corpus", { timeout: 30_000 }, () => {
for (const fixture of FIXTURES) {
it(`${fixture.id}: known-good quote round-trips with confidence ≥ 0.9`, async () => {
const bytes = new Uint8Array(readFileSync(resolve(FIXTURE_DIR, fixture.filename)));

14
tests/integration/app-prd-scenario.dom.test.tsx
View File

@@ -168,14 +168,16 @@ describe("App — PRD scenario steps 1-8 (CE-WP-0002-T09)", () => {
);
});
// The toolbar should appear with the quoted text preview.
const toolbar = await screen.findByText(/New annotation/);
expect(toolbar).toBeTruthy();
// The inline capture form should appear with the quoted text preview.
await screen.findByTestId("inline-capture-form");
await screen.findByText(/New evidence/);
// Step 4: add a comment and save.
const textarea = screen.getByPlaceholderText(/Add a one-line comment/);
await user.type(textarea, "Important deadline clause");
await user.click(screen.getByRole("button", { name: /Save evidence/ }));
await user.type(
screen.getByTestId("inline-capture-commentary"),
"Important deadline clause",
);
await user.click(screen.getByTestId("inline-capture-save"));
// Step 5: the item appears in the sidebar. The commentary text is
// unique to the right pane (the collection list never echoes it back).

25
tests/integration/forms-active-cycling.dom.test.tsx
View File

@@ -128,25 +128,25 @@ describe("FormsApp — active-evidence cycling (CE-WP-0003-T06)", () => {
[{ type: "TextQuoteSelector", exact: FIXTURE.known_good_quote }],
);
});
const textarea = screen.getByPlaceholderText(/Add a one-line comment/);
await user.type(textarea, "Form-cycling test evidence");
await user.click(screen.getByRole("button", { name: /Save evidence/ }));
await user.type(
screen.getByTestId("inline-capture-commentary"),
"Form-cycling test evidence",
);
await user.click(screen.getByTestId("inline-capture-save"));
await screen.findByText(/Form-cycling test evidence/);
// --- Switch to Forms mode.
await user.click(screen.getByRole("button", { name: "Forms" }));
await user.click(screen.getByRole("button", { name: "Capture" }));
// The evidence should appear in the Forms strip too (it queries by doc).
const stripCard = await screen.findByRole("button", {
name: /Form-cycling test evidence/,
});
// Stage it.
await user.click(stripCard);
// Click the Summary field → link gets created.
// Focus Summary, then click strip card → link gets created.
const summaryField = screen.getByLabelText("Summary of the matter");
await user.click(summaryField);
await user.click(stripCard);
// Link chip on Summary now shows "1 evidence"
await waitFor(
@@ -170,12 +170,13 @@ describe("FormsApp — active-evidence cycling (CE-WP-0003-T06)", () => {
await user.click(screen.getByLabelText("Disputed amount"));
await user.click(summaryField);
// The chip rendered inside the form pane has aria-current="true".
// The strip card for the linked evidence has aria-current="true".
await waitFor(() => {
const chip = document.querySelector(
'[data-evidence-id][aria-current="true"]',
const card = document.querySelector(
'button[aria-current="true"]',
);
expect(chip).not.toBeNull();
expect(card).not.toBeNull();
expect(card!.textContent).toMatch(/Form-cycling test evidence/);
});
// The viewer was asked to scroll to the underlying annotation.

189
tests/integration/forms-link-flow.dom.test.tsx
View File

@@ -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);
});

18
tests/integration/forms-overlay-e2e.dom.test.tsx
View File

@@ -136,25 +136,24 @@ describe("CE-WP-0003-T08 — PRD scenario steps 5-9 end-to-end", () => {
);
});
await user.type(
screen.getByPlaceholderText(/Add a one-line comment/),
screen.getByTestId("inline-capture-commentary"),
"Overlay E2E evidence",
);
await user.click(screen.getByRole("button", { name: /Save evidence/ }));
await user.click(screen.getByTestId("inline-capture-save"));
await screen.findByText(/Overlay E2E evidence/);
// Step 5: navigate to forms via the top-bar.
await user.click(screen.getByRole("button", { name: "Forms" }));
await user.click(screen.getByRole("button", { name: "Capture" }));
// 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.
// Step 6: focus summary, then click the strip card to link directly.
const summaryField = screen.getByLabelText("Summary of the matter");
await user.click(summaryField);
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
@@ -170,8 +169,9 @@ describe("CE-WP-0003-T08 — PRD scenario steps 5-9 end-to-end", () => {
);
expect(fieldRow).not.toBeNull();
});
const activeChip = document.querySelector('[data-evidence-id][aria-current="true"]');
expect(activeChip).not.toBeNull();
const activeCard = document.querySelector('button[aria-current="true"]');
expect(activeCard).not.toBeNull();
expect(activeCard!.textContent).toMatch(/Overlay E2E evidence/);
// Step 9: SVG overlay renders 2 paths (field→card + card→highlight).
// HighlightRectBridge registers via the mocked getHighlightClientRects.

124
tests/integration/forms-strip-filter.dom.test.tsx Normal file
View File

@@ -0,0 +1,124 @@
/**
* CE-WP-0006-T04 — evidence strip filter (all vs attached-to-active-field).
*/
// @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 { 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;
}
const viewerSnapshot: { onSelectionCaptured: ViewerProps["onSelectionCaptured"] | null } = {
onSelectionCaptured: null,
};
vi.mock("@anchor/index", async (importOriginal) => {
const original = await importOriginal<typeof import("@anchor/index")>();
const MockPdfSpikeViewer = (props: ViewerProps) => {
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 = [
"Alpha.",
FIXTURE.known_good_quote,
"Beta.",
].join(" ");
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 />);
}
async function captureAndSave(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 — evidence strip filter (CE-WP-0006-T04)", () => {
beforeEach(() => {
viewerSnapshot.onSelectionCaptured = null;
globalThis.localStorage?.clear();
if (typeof window !== "undefined") {
history.replaceState(null, "", window.location.pathname);
}
seedSessionWithDoc({
sessionName: "T04-filter",
documentTitle: FIXTURE.filename,
canonicalText: SYNTHETIC_CANONICAL,
});
});
afterEach(() => {
vi.restoreAllMocks();
cleanup();
});
it(
"narrows to attached evidence on field focus and restores on All toggle",
{ timeout: 20000 },
async () => {
const user = userEvent.setup();
await loadApp();
await captureAndSave(user, "Linked to summary");
await captureAndSave(user, "Unlinked orphan");
await user.click(screen.getByRole("button", { name: "Capture" }));
const linkedCard = await screen.findByRole("button", {
name: /Linked to summary/,
});
expect(screen.getByRole("button", { name: /Unlinked orphan/ })).toBeTruthy();
// Link the first item to summary; field focus keeps attached filter active.
await user.click(screen.getByLabelText("Summary of the matter"));
await user.click(linkedCard);
await waitFor(() => {
expect(screen.getByTestId("field-summary-chip").textContent).toMatch(
/1 evidence/,
);
expect(screen.queryByRole("button", { name: /Unlinked orphan/ })).toBeNull();
});
await user.click(screen.getByRole("button", { name: "All" }));
await waitFor(() => {
expect(screen.getByRole("button", { name: /Unlinked orphan/ })).toBeTruthy();
});
},
);
});