---
id: CE-WP-0007
type: workplan
title: "Capture view polish — scroll stability, linking UX, layout, rename"
domain: citation_evidence
repo: citation-evidence
repo_id: a677c189-b4e2-4f2a-9e48-faa482c277e6
topic_slug: citation_evidence_mvp
topic_id: 96fa8e80-9f74-40f2-84cd-644e9747b9ec
status: done
owner: Bernd
created: 2026-06-07
updated: 2026-06-08
depends_on_workplan: CE-WP-0006
planning_order: 7
planning_priority: high
spec_refs:
  - wiki/ProductRequirementsDocument.md
  - workplans/CE-WP-0006-forms-ux-refinements.md
state_hub_workstream_id: "988ee7c6-752a-492a-9ef9-76d33af9b2d6"
---

# CE-WP-0007 — Capture View Polish

Follow-on UX fixes after CE-WP-0006 manual demo use. Renames the Forms
mode tab to **Capture**, recentres the document column, and tightens linking
and visual-guide behaviour.

## User requirements (locked)

1. **Scroll stability** — selecting evidence further down the document must
   not jump the viewport back to the beginning.
2. **Focus-gated linking** — only when a form field has focus does clicking
   evidence in the strip link directly (no evidence-first staging flow).
3. **Unlink clears visualization** — removing a link removes the connection
   lines immediately.
4. **Field badge tooltips** — mouseover on a field's evidence-count badge
   shows the first 80 characters of linked evidence, with trailing `…` when
   truncated.
5. **Softer guide lines** — connection indicator lines are grey and thinner.
6. **Centred document column** — Capture layout matches Review: collection |
   **viewer (centre)** | form pane (right).
7. **Rename Forms → Capture** — top-bar tab label and user-facing copy.
8. **Add Field** — button to append new form fields to the demo schema.
9. **Field type + label on add/edit** — when adding a capture field, choose
   `text` | `textarea` | `date` and set the label; existing fields expose a
   ✎ edit control (same interaction pattern as evidence cards in
   `EvidenceSidebar`).

## Dependency order

```
T01 (scroll stability)
T02 (focus-gated linking) ─┬─ T03 (unlink clears viz)
                           └─ T04 (field badge tooltips)
T05 (grey guide lines) — parallel
T06 (layout swap) ── T07 (rename Capture)
T08 (Add Field) — after T06/T07
T09 (integration tests + README)
T10 (add-field type + label) ── T11 (field edit icon)
       └─ T12 (tests)
```

---

## T01 — Fix viewport jump on evidence select

```task
id: CE-WP-0007-T01
priority: critical
status: done
state_hub_task_id: "23f8e8d0-4ccd-48e9-958c-cc8b756dcaec"
```

**Problem:** clicking an evidence item far down the PDF resets scroll to the
document start before (or instead of) centring the passage.

**Fix:**

- Harden `centerHighlightInViewer` with retried rAF passes until highlight
  DOM rects are available.
- Ensure scroll requests do not remount `PdfSpikeViewer`.
- Avoid duplicate/conflicting scroll triggers from auto-activation + card click.

**Acceptance:** click evidence items on page 2+ — viewport stays near the
cited passage, never snaps to page 1 top.

---

## T02 — Link only when a form field has focus

```task
id: CE-WP-0007-T02
priority: high
status: done
depends_on: [T01]
state_hub_task_id: "289bed30-0bb0-42b7-ab6f-8c218133d3df"
```

**Remove** evidence-first staging (click card → click field). **Keep**
field-focus-gated direct link:

- Field receives focus → user clicks evidence card → immediate
  `linkEvidenceToTarget`.
- Evidence click without focused field → activate + scroll only.

Remove evidence-staged banner and `stagedEvidenceId` state paths.

**Acceptance:** focus Summary → click strip card → link created. Click card
with no field focused → no link, no staging banner.

---

## T03 — Unlink removes connection visualization

```task
id: CE-WP-0007-T03
priority: high
status: done
depends_on: [T02]
state_hub_task_id: "328e8936-454f-4092-802b-9b0030d54ce5"
```

On `EvidenceLinkRemoved`, if the active triple no longer has a valid link
between field and evidence, clear `activeEvidenceItemId` / `activeAnnotationId`
(or select the next remaining link on the field).

**Acceptance:** unlink via strip badge → SVG paths disappear immediately.

---

## T04 — Field evidence badge hover preview

```task
id: CE-WP-0007-T04
priority: medium
status: done
depends_on: [T02]
state_hub_task_id: "af6a0c73-c323-4e24-85f7-64403658ae51"
```

On each field's `N evidence` chip in `FormRenderer`, set `title` to the
first 80 characters of the first linked evidence quote (italic), append `…`
when longer. Multiple links: join previews or show first link only (document
choice in commit).

**Acceptance:** hover field badge → tooltip shows truncated quote.

---

## T05 — Grey, thinner visual-guide lines

```task
id: CE-WP-0007-T05
priority: low
status: done
state_hub_task_id: "a415f7df-f641-49d8-9c21-13eb70684c64"
```

Update `Overlay` defaults (or Capture-mode props): stroke `#999` (or similar
grey), width `1` px. Update `Overlay.dom.test.tsx` if it asserts colour/width.

**Acceptance:** connection lines are visibly grey and thinner than before.

---

## T06 — Capture layout: document in centre column

```task
id: CE-WP-0007-T06
priority: high
status: done
state_hub_task_id: "1fa3cd2c-c264-4599-9e8a-bd1d74ac1faa"
```

Reorder `FormsApp` columns to match `ReviewLayout`:

```
Collection | ViewerShell | FormPane
```

Evidence strip remains full-width footer.

**Acceptance:** PDF viewer is the centre pane in Capture mode.

---

## T07 — Rename Forms view to Capture

```task
id: CE-WP-0007-T07
priority: medium
status: done
depends_on: [T06]
state_hub_task_id: "7c326eaa-839c-45ad-bef6-aab77b324332"
```

- Top-bar tab: `Forms` → `Capture`.
- User-facing strings in Capture mode (banners, empty hints).
- Internal route slug may remain `forms` for deep-link compat; update tests
  that query the tab by visible label.

**Acceptance:** tab reads "Capture"; integration tests updated.

---

## T08 — Add Field button

```task
id: CE-WP-0007-T08
priority: medium
status: done
depends_on: [T06]
state_hub_task_id: "04586602-491b-46c2-9ced-48258d11bfed"
```

Add **Add field** control above the form. Appends a new `text` field with
auto-generated id (`field_<n>`) and editable label placeholder. Schema held
in React state (seeded from `DEMO_SCHEMA`); rect registry and linking use
dynamic field ids.

**Acceptance:** click Add field → new row appears; can link evidence to it.

---

## T09 — Tests and README index

```task
id: CE-WP-0007-T09
priority: high
status: done
depends_on: [T03, T04, T05, T07, T08]
state_hub_task_id: "823d4986-892d-467e-819e-54f0f2a363e8"
```

- Update integration tests for Capture label, layout, focus-gated linking.
- Add/adjust tests for unlink visualization and field badge tooltip.
- Update `workplans/README.md` with CE-WP-0007.

**Acceptance:** `npm run test` green.

---

## T10 — Add-field dialog: type selection + label

```task
id: CE-WP-0007-T10
priority: medium
status: done
depends_on: [T08]
state_hub_task_id: "dab723e6-66a6-4587-8ab7-e0c5e4cb5d0a"
```

**Current:** **Add field** immediately appends a `text` field with a
generated label (`New field N`).

**Implement:**

- Click **Add field** → lightweight inline form or small modal (match
  `EvidenceFormBody` / `InlineCaptureForm` styling, not a new design system).
- User picks field type: `text` | `textarea` | `date` (same union as
  `FormFieldSchema`).
- User enters/edits the label before confirm.
- **Add** inserts the field; **Cancel** discards.
- Stable auto-id (`field_<n>`); label is user-facing only.

**Acceptance:** add a `date` field labelled "Hearing date" — row renders with
correct input type and label.

---

## T11 — Field edit icon (evidence-sidebar pattern)

```task
id: CE-WP-0007-T11
priority: medium
status: done
depends_on: [T10]
state_hub_task_id: "c55541c7-57e2-4f5d-a4ef-ed54c470cbd9"
```

Mirror `EvidenceSidebar` edit UX (`✎` button, `data-testid` hooks,
inline editor, save/cancel):

- Each `FieldRow` in `FormRenderer` gets an upper-right **edit** control
  (pencil icon, `aria-label`, stop propagation on click).
- Edit mode shows type selector + label input (reuse T10 controls).
- **Save** updates schema state in `FormsApp`; **Cancel** reverts.
- Changing type swaps the rendered input; field `id` stays stable so
  existing `EvidenceLink` targets and rect registrations remain valid.
- Demo-schema seed fields are editable too.

**Acceptance:** edit "Summary of the matter" → rename + switch to `text`;
links and visual guide still resolve by field id.

---

## T12 — Tests for field add/edit UX

```task
id: CE-WP-0007-T12
priority: high
status: done
depends_on: [T10, T11]
state_hub_task_id: "585b054e-eb5e-410e-90ee-84e698b13f7f"
```

Happy-dom integration or `FormRenderer` DOM tests:

- Add field with chosen type + custom label.
- Edit existing field label and type via pencil icon.
- Link to an added/edited field still works (focus-gated linking).

**Acceptance:** `npm run test` green.

---

## Acceptance for the workplan

After CE-WP-0007:

1. Evidence select does not jump viewport to document start.
2. Linking requires focused field; evidence click links directly.
3. Unlink clears visual guide lines.
4. Field badges show 80-char quote preview on hover.
5. Guide lines are grey and thin.
6. Capture mode centres the document viewer.
7. Tab reads "Capture".
8. Users can add form fields dynamically.
9. Add-field flow picks type and label; existing fields edit via ✎ control.