PR: #655: feat(documents): attention surfaces — margin index, suppress-below-floor, flag-a-grade [Story-2510] by @ankitmaheshwari-com
View PR →

Story 2510: Attention surfaces

Manifest T5b · Wave W5 · RFD-DOC-006 Extraction Record. Covers D12, I-12, I-13 and scenarios ER-04, ER-20, ER-29, ER-30. The Deep Read already grades each section (Story-2501); T5b turns those grades into a margin-resident attention map counsel can act on — an unread-critical completion signal, a fail-safe for low-confidence grades, a flag when a grade is wrong, and the a11y contract that makes all of it keyboard- and screen-reader-workable.

ER-04 — the Deep Read allocates attention on a long filing

Opening the 114-page Statement of Claim shows the AttentionIndexRail: a persistent map in the margin (never a blocking overlay, I-13). Its header carries the total first-read time and the coverage%; each row states the grade, its reason, and a link to the section's exact pages. Every graded section links to its ink.

envelope.rows (attention ⋈ section)
  → toAttentionIndex(envelope)               // entries, coverage%, total time
  → <AttentionIndexRail model />              // margin-resident, sticky, non-blocking

ER-20 / I-12 — a low-confidence grade never suppresses a material section

Below the confidence floor the read declines to allocate: the row renders "Not assessed — read normally", never a false "Skip" and never a silent drop. A suppressed row is carried, not deleted, so the map neither hides the section nor pretends it was graded.

Flag a grade. Every graded row has a Flag this grade button; flagging records the flag against that grade (to feed the re-grade) and the row settles into "Flagged for re-grade".

I-13 — the unread-critical completion signal

The rail header is the first-read completion signal: the count of critical sections still unread. Marking a section read decrements it instantly; at zero the header flips to "First read complete". A declared omission on a critical-graded region (coverage.omissions with critical: true) holds the read open — the machine can never discharge a section it never reached (D13).

ER-30 — keyboard-only, and quotes announced as document text

Contract How
Keyboard list The rail is a <nav> of native links and buttons — the page link, the read toggle (aria-pressed), the flag button (aria-label). Counsel tabs the whole map; no custom key handling to get wrong.
Announced markers Each grade is a text + icon badge (never colour alone, D12 a11y); the text names the grade so a screen reader announces "Critical", not "red pill".
Quote vs prose QuoteText wraps every byte-verified passage in the findings with an sr-only "Quoted document text:" prefix and aria-roledescription="document quote". A quoted admission is announced as the document's words, distinct from the machine's prose.

ER-29 / O-9 — locale split, and the Hindi vocabulary review

Chrome and attention labels render in the counsel's locale; the machine's reasons render in the locale too; the quotes never translate (they are lifted from the document as-is). Every new string is in messages/en.json AND messages/hi.json.

O-9 vocabulary review artifact. The Hindi that ships needs a Hindi-native counsel sign-off before either surface is trusted — a mistranslated "skip" or side label is a safety bug. The vocabulary under review:

Attention grade (EN)Hindi
Criticalअत्यावश्यक
Readपढ़ें
Skimसरसरी पढ़ें
Skipछोड़ें
Not assessed (suppressed)मूल्यांकन नहीं

The side vocabulary (Plaintiff/Defendant, Petitioner/Respondent, …) already exists in both locales under Matters.role.* and is in the same review scope; T5c owns the side-check surface that renders it. No new side keys were minted here — the review is of the existing pair.

Storybook states

Cutover law

Per RFD-DOC-006 the new path is fixture-first until the W5 cutover; the serving Original lens stays authoritative. The attention map is live-wired on the Insights lens (it reads the same Deep Read envelope the dossier already serves). Two seams are fixture-first and stated here honestly:

Files changed

21 file(s), +1018 / -25 lines

Path Role + -
messages/en.jsonConfig+31-1
messages/hi.jsonConfig+31-1
src/components/documents/viewer/attention-grade-badge.stories.tsxComponent+30-0
src/components/documents/viewer/attention-grade-badge.tsxComponent+50-0
src/components/documents/viewer/attention-index-presentation.test.tsComponent+134-0
src/components/documents/viewer/attention-index-presentation.tsComponent+157-0
src/components/documents/viewer/attention-index-rail.stories.tsxComponent+128-0
src/components/documents/viewer/attention-index-rail.tsxComponent+111-0
src/components/documents/viewer/attention-index-row-actions.tsxComponent+72-0
src/components/documents/viewer/attention-index-row.tsxComponent+101-0
src/components/documents/viewer/deep-read-findings.tsxComponent+10-1
src/components/documents/viewer/deep-read-presentation.tsComponent+0-9
src/components/documents/viewer/deep-read-section.tsxComponent+5-8
src/components/documents/viewer/document-insights-dossier.tsxComponent+35-3
src/components/documents/viewer/document-insights-live.tsxComponent+30-0
src/components/documents/viewer/quote-text.stories.tsxComponent+41-0
src/components/documents/viewer/quote-text.tsxComponent+35-0
src/components/documents/viewer/section-finding-card.stories.tsxComponent+4-0
src/components/documents/viewer/section-finding-card.tsxComponent+5-2
src/components/documents/viewer/section-machine-gutter.stories.tsxComponent+4-0
src/components/documents/viewer/use-section-labels.tsComponent+4-0