Document reader cursor audit evidence

Co-authored-by: Codex <codex@openai.com>

FIELD_NOTES.md

@@ -30,11 +30,15 @@ Runtime setup is also data-backed. `/api/runtime-setup` lists the app command, l
 
 The judge runbook lives at `/api/demo-script`. It keeps the live presentation repeatable by pairing visible actions with API checks for health, model budget, runtime setup, runtime status, image descriptions, reader narration, and speech.
 
-Accessibility evidence lives at `/api/accessibility-audit`. It records the reader-mode choices that matter most for this prototype: semantic reading order, keyboard navigation, live narration, image alt text, transcript review, user-controlled playback, and fallback resilience.
+Accessibility evidence lives at `/api/accessibility-audit`. It records the reader-mode choices that matter most for this prototype: semantic reading order, keyboard navigation, reader cursor state, shortcut safety, live narration, image alt text, transcript review, user-controlled playback, and fallback resilience.
 
 ## Reader Mode Behavior
 
-The frontend creates a reading queue from semantic nodes: headings, paragraphs, quotes, figures, captions, and controls. It speaks one item at a time, keeps keyboard focus synchronized with the active node, and exposes the current narration through an `aria-live` region.
+The frontend creates a reading queue from semantic nodes: headings, paragraphs, quotes, figures, captions, and controls. It speaks one item at a time, keeps keyboard focus synchronized with the active node, marks that node with `aria-current`, and exposes the current narration through an `aria-live` region.
+
+When screen reader mode turns on, the reader cursor starts at the focused article node or the most visible article node. That makes the feature feel connected to what the user is already reading instead of always jumping back to the top of the page.
+
+Reader shortcuts deliberately ignore form controls. A user can adjust the Kokoro voice, speed slider, and auto-advance checkbox without the page treating those keystrokes as navigation commands.
 
 Each narration is also added to a visible transcript log. This gives the demo a second accessible surface: users can review what was spoken, copy the session transcript, or clear it before exploring another part of the article.
 

README.md

@@ -77,7 +77,7 @@ The verifier checks syntax, static assets, Space metadata consistency, determini
 
 `/api/demo-script` exposes a compact judge runbook with the visible actions and API checks that prove the submission claims.
 
-`/api/accessibility-audit` exposes structured evidence for semantic reading order, keyboard navigation, live narration, image alt text, transcript review, user-controlled playback, and fallback resilience.
+`/api/accessibility-audit` exposes structured evidence for semantic reading order, keyboard navigation, reader cursor state, shortcut safety, live narration, image alt text, transcript review, user-controlled playback, and fallback resilience.
 
 ## Screen Reader Mode
 
@@ -94,6 +94,10 @@ The frontend builds a reading queue from semantic article nodes. When screen-rea
 
 Each readable node is sent to the reader brain for concise narration, then Kokoro generates speech. If a model is unavailable, the app uses deterministic fallbacks so the demo remains navigable.
 
+When screen-reader mode turns on, it selects the focused or most visible article item, assigns stable reader-node ids, and marks the active item with `aria-current`. Clicking a readable article item while the mode is on reads that item directly.
+
+Global reader shortcuts ignore buttons, links, selects, and inputs so the voice, speed, and auto-advance controls remain usable while reader mode is active.
+
 The session panel keeps a transcript of recent narration with copy and clear controls, making the spoken path inspectable during demos and useful for the Field Notes write-up.
 
 Image descriptions are preloaded into a local cache and written into the page's real `img alt` attributes. When the planned MiniCPM-V runtime is unavailable, deterministic alt-text fallbacks keep the screen-reader path usable.

app.py

@@ -279,6 +279,18 @@ def accessibility_audit_core() -> dict[str, Any]:
             "status": "pass",
             "evidence": "Reader controls expose Space, N, P, H, I, S, R, and Esc shortcuts through the manifest.",
         },
+        {
+            "id": "reader_cursor",
+            "label": "Reader cursor state",
+            "status": "pass",
+            "evidence": "The active readable node receives focus, a visible outline, a stable reader id, and aria-current state.",
+        },
+        {
+            "id": "shortcut_safety",
+            "label": "Shortcut safety",
+            "status": "pass",
+            "evidence": "Global reader shortcuts ignore form controls so voice, speed, and auto-advance settings remain usable.",
+        },
         {
             "id": "live_region",
             "label": "Live narration region",

scripts/verify.py

@@ -324,8 +324,16 @@ def verify_routes() -> None:
     assert_true(audit_payload["passed_checks"] == audit_payload["total_checks"], "All audit checks should pass")
     assert_true(
         {item["id"] for item in audit_payload["checks"]}
-        >= {"semantic_queue", "keyboard_navigation", "live_region", "image_alt_text", "inspectable_transcript"},
-        "Accessibility audit should cover reader semantics, keyboard use, live narration, alt text, and transcript",
+        >= {
+            "semantic_queue",
+            "keyboard_navigation",
+            "reader_cursor",
+            "shortcut_safety",
+            "live_region",
+            "image_alt_text",
+            "inspectable_transcript",
+        },
+        "Accessibility audit should cover reader semantics, keyboard use, cursor state, shortcut safety, live narration, alt text, and transcript",
     )
 
     runtime = client.get("/api/runtime-status")