citation-evidence/workplans/CE-WP-0006-forms-ux-refinements.md

id, type, title, domain, repo, repo_id, topic_slug, topic_id, status, owner, created, updated, depends_on_workplan, planning_order, planning_priority, spec_refs, state_hub_workstream_id

id	type	title	domain	repo	repo_id	topic_slug	topic_id	status	owner	created	updated	depends_on_workplan	planning_order	planning_priority	spec_refs	state_hub_workstream_id
CE-WP-0006	workplan	Forms & review UX refinements — blob stability, scroll-center, linking, visual guide	citation_evidence	citation-evidence	a677c189-b4e2-4f2a-9e48-faa482c277e6	citation_evidence_mvp	96fa8e80-9f74-40f2-84cd-644e9747b9ec	done	Bernd	2026-06-07	2026-06-07	CE-WP-0005	6	high	wiki/ProductRequirementsDocument.md wiki/ArchitectureOverview.md wiki/SharedContracts.md history/2026-06-07-ecosystem-state-assessment.md	97493fdb-a793-4e79-bc7c-6a56b6085873

CE-WP-0006 — Forms & Review UX Refinements

User-facing polish before architectural expansion (Markdown/HTML, citation recovery, subsystem extraction). Addresses six issues observed during manual demo use on http://localhost:5173/.

User requirements (locked)

1. PDF blob load failure on evidence capture — saving a new evidence item with commentary triggers Unexpected server response (0) while retrieving PDF "blob:http://…".
2. Center cited region on evidence select — clicking an evidence item must scroll the document viewport so the marked passage is centred, not merely brought into view at an edge.
3. Visual guide from footer strip only — in Forms mode, connection lines must originate from the bottom evidence strip cards, not duplicate cards below the form. The field end of each line should attach to the bottom edge of the form pane to reduce overlap with field inputs.
4. Evidence strip visibility filter — the bottom row supports an optional filter (all | attached). Focusing a form field switches the filter to attached (evidence linked to that field only).
5. Bidirectional linking — linking must work both ways:
   • evidence → field (existing staged flow), and
   • field → evidence (select/focus field, then click evidence card to link).
6. Link indicators on evidence cards — connected cards show one or more link symbols in the upper-right. Hover shows a tooltip listing connected form field titles. Clicking a symbol removes that specific link.

Scoping decisions

• No architecture extraction in this workplan — all changes stay in the umbrella repo under existing src/{work,binder,app,anchor,source}/ folders.
• Review mode and Forms mode both benefit from T01 (blob stability) and T02 (scroll centre); T03–T06 are Forms-mode focused.
• ActiveEvidenceChips (src/app/forms/ActiveEvidenceChips.tsx) is removed from the form pane layout; its rect-registration responsibility moves to the footer EvidenceStrip. The module may remain as a thin helper or be inlined — but it must not render duplicate cards below the form.
• Unlink uses bindings.unlinkEvidence(linkId) (hard delete per current MVP semantics in src/binder/services/bindings.ts).

Dependency order

T01 (blob URL stability)
  └─ T02 (viewport centre on evidence select)
T03 (strip-only visual guide + remove duplicate chips)
  ├─ T04 (strip filter: all | attached)
  ├─ T05 (bidirectional linking)
  └─ T06 (link badges + tooltip + unlink)
       └─ T07 (integration tests)
T08 (update workplans/README.md) — parallel once file exists

---

T01 — Fix PDF blob URL failure during evidence capture

id: CE-WP-0006-T01
priority: critical
status: done
state_hub_task_id: "3cc6a93a-e506-4477-8ef7-8c6dee405bc8"

Problem: uploaded PDFs are served via ephemeral blob: URLs minted by PdfByteStore and stamped onto document.uri. A full viewer remount (e.g. ViewerShell re-keyed on scrollVersion) or persistence round-trip can leave PDF.js fetching a revoked or stale blob URL.

Investigate and fix:

• ViewerShell should resolve the viewer URL from the live PdfByteStore entry for document.id when bytes are present; treat persisted document.uri blob URLs as hints only, never as the sole source after reload.
• Avoid unnecessary full PdfSpikeViewer remounts when only scroll-target changes (split scroll trigger from component key if that is the root cause).
• Ensure captureSnapshot / restore does not persist blob URLs that cannot be rehydrated, or re-mint blob URLs from stored bytes on session/engine restore when ZIP import or upload repopulates the byte store.
• Add a regression test reproducing capture-after-upload without blob error (src/work/ or tests/integration/).

Acceptance: upload a PDF, select text, add commentary, save evidence — no PDF.js blob fetch error; viewer remains usable.

---

T02 — Centre viewport on marked region when selecting evidence

id: CE-WP-0006-T02
priority: high
status: done
depends_on: [T01]
state_hub_task_id: "e09d8fa1-862e-4c83-b1c4-19c6826e4610"

Problem: scrollToHighlight brings the passage into view but does not centre it. Users lose context when the highlight lands at the viewport edge.

Implement:

• Extend the viewer adapter scroll contract (PdfSpikeViewer / react-pdf-highlighter-plus utils) so scroll-to-annotation centres the highlight rect vertically (and horizontally when wider than viewport).
• Wire through useScrollToAnnotation callers: EvidenceSidebar, ViewerShell highlight click, ScrollBridge in Forms mode.
• Unit test for scroll math helper if extracted; DOM integration test asserting scroll request includes centre intent (mock utils acceptable per ADR-0004).

Acceptance: click any evidence item in Review or Forms — the cited passage appears centred in the document pane.

---

T03 — Visual guide from footer evidence strip; remove duplicate form cards

id: CE-WP-0006-T03
priority: high
status: done
depends_on: [T02]
state_hub_task_id: "f30df6ee-a1c4-4a1b-80e0-d44e54f7b9b6"

Problem: FormPane renders ActiveEvidenceChips below the form while EvidenceStrip already shows the same cards at the bottom. The SVG overlay (Overlay.tsx) draws field→card→highlight using rects registered by the duplicate chips.

Implement:

• Remove ActiveEvidenceChips from FormPane in FormsApp.tsx.
• Register kind="evidence-card" rects from EvidenceStrip buttons instead (one registration per visible card).
• Update Overlay path geometry:
  • field end → bottom-centre of the active field row (or bottom of form pane when no specific field is active),
  • card end → top-centre of the strip card,
  • highlight end → unchanged.
• Adjust forms-overlay-e2e.dom.test.tsx expectations for the new anchor points and single card location.

Acceptance: only one evidence card row (footer strip); visual guide connects form bottom → strip card → PDF highlight with no duplicate cards under the form.

---

T04 — Evidence strip filter (all vs attached-to-active-field)

id: CE-WP-0006-T04
priority: medium
status: done
depends_on: [T03]
state_hub_task_id: "1dafa73d-1d8c-43b6-8934-2fbf038fc3be"

Implement in EvidenceStrip:

• Filter state: all (default) | attached.
• UI toggle in the strip header (e.g. "All" / "Linked to field").
• When a form field receives focus (FormFieldActivated or useActiveState().activeTarget), set filter to attached and show only evidence items with an EvidenceLink to that target.
• When no field is active, attached filter shows evidence linked to any field in the demo schema, or falls back to all — pick the less surprising option and document it in the task commit message.
• Clearing field focus returns filter to user’s last explicit choice (not forced back to all).

Acceptance: focus "Summary" field → strip shows only evidence linked to summary; toggle restores full list.

---

T05 — Bidirectional evidence ↔ field linking

id: CE-WP-0006-T05
priority: high
status: done
depends_on: [T03]
state_hub_task_id: "2d7c9278-1ecc-4b59-ae3b-1a5d1e513885"

Current: evidence-first only — stage card in strip, then click field.

Add field-first:

• Click/focus a form field → enter "field staged for linking" state (banner parallel to existing evidence-staged banner).
• Click an evidence card in the strip → bindings.linkEvidenceToTarget with the staged field as target; clear staging.
• Evidence-first path remains unchanged.
• Mutual exclusion: staging evidence clears field staging and vice versa.
• Emit existing EvidenceLinkCreated event; link count chips on fields update.

Acceptance: link works via evidence→field and field→evidence; cancel clears staging; duplicate link to same target is prevented or noop with user feedback.

---

T06 — Link badges on evidence cards (tooltip + unlink)

id: CE-WP-0006-T06
priority: high
status: done
depends_on: [T05]
state_hub_task_id: "064f6e48-e791-4cf5-9d04-df3fb7a11e48"

On each evidence card in EvidenceStrip:

• Query bindings.listTargetsForEvidence(item.id).
• Render one link icon per connected form field in the card’s upper-right (stack or count badge when >3).
• title / aria-label on hover: field label from DEMO_SCHEMA (fallback to targetId).
• Click icon → bindings.unlinkEvidence(linkId) for that target; refresh strip and field link counts.
• Do not trigger link-staging when clicking the unlink control (stop propagation).

Acceptance: linked cards show indicators; tooltip names fields; click removes link without staging a new one.

---

T07 — Integration tests for refined Forms UX

id: CE-WP-0006-T07
priority: high
status: done
depends_on: [T04, T05, T06]
state_hub_task_id: "c50f9700-9902-4520-b8e2-6a010431b7ef"

Extend or add happy-dom integration tests:

• tests/integration/forms-link-flow.dom.test.tsx — bidirectional linking.
• tests/integration/forms-overlay-e2e.dom.test.tsx — strip-only rects, bottom anchor geometry (path count / data attributes).
• tests/integration/app-prd-scenario.dom.test.tsx — capture-after-upload no blob error (if not covered in T01 unit test).
• New or extended test for strip attached filter behaviour.

Acceptance: pnpm test green; tests document the six user requirements.

---

T08 — Update workplans README index

id: CE-WP-0006-T08
priority: low
status: done
state_hub_task_id: "715edb39-9b97-4d7f-b89b-71a0130326e8"

Update workplans/README.md to list CE-WP-0001..0006 with correct statuses (0001–0005 done, 0006 active).

Acceptance: README table matches workplan frontmatter.

---

Acceptance for the workplan

After CE-WP-0006:

1. Evidence capture on uploaded PDFs does not break the viewer.
2. Selecting evidence centres the cited passage in the document viewport.
3. Forms visual guide uses footer strip cards only; lines attach to form bottom.
4. Evidence strip supports all/attached filter; field focus narrows to attached.
5. Linking works evidence→field and field→evidence.
6. Linked evidence cards show unlinkable field indicators with tooltips.