Expose reader shortcuts to assistive tech

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

FIELD_NOTES.md

@@ -46,6 +46,8 @@ When screen reader mode turns on, the reader cursor starts at the focused articl
 
 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.
 
+The reader bar exposes the same shortcut contract through `aria-keyshortcuts`. Escape also has a visible Stop button, which keeps the assistive command model available to pointer users and easy for judges to inspect.
+
 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.
 
 Keyboard map:

README.md

@@ -107,6 +107,8 @@ When screen-reader mode turns on, it selects the focused or most visible article
 
 Global reader shortcuts ignore buttons, links, selects, and inputs so the voice, speed, and auto-advance controls remain usable while reader mode is active.
 
+Reader buttons expose `aria-keyshortcuts`, and the Escape shortcut is mirrored by a visible Stop control so pointer and keyboard users share the same command surface.
+
 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.

SUBMISSION.md

@@ -48,7 +48,7 @@ The prototype is designed for a live hackathon demo: every model-facing path has
 
 The checks in `/api/demo-script` include curl and PowerShell-friendly `curl.exe` commands generated from `PUBLIC_BASE_URL`, and the POST checks include sample JSON bodies for `/api/reader-brain` and `/api/speak`.
 
-The accessibility audit also documents two reader-mode details that matter during judging: the active item is exposed as a reader cursor with focus, visible outline, stable id, and `aria-current`; global shortcuts ignore form controls so voice, speed, and auto-advance settings remain usable while reader mode is active.
+The accessibility audit also documents reader-mode details that matter during judging: the active item is exposed as a reader cursor with focus, visible outline, stable id, and `aria-current`; global shortcuts ignore form controls so voice, speed, and auto-advance settings remain usable while reader mode is active; reader controls expose `aria-keyshortcuts` and a visible Stop command for Escape.
 
 The image receipts keep the generated-asset claim inspectable: each article illustration names the planned `black-forest-labs/FLUX.2-klein-4B` path, prompt, seed, and bundled fallback asset.
 

app.py

@@ -421,7 +421,7 @@ def accessibility_audit_core() -> dict[str, Any]:
             "id": "keyboard_navigation",
             "label": "Keyboard navigation",
             "status": "pass",
-            "evidence": "Reader controls expose Space, N, P, H, I, S, R, and Esc shortcuts through the manifest.",
+            "evidence": "Reader controls expose Space, N, P, H, I, S, R, and Esc shortcuts through the manifest and aria-keyshortcuts.",
         },
         {
             "id": "reader_cursor",
@@ -478,14 +478,14 @@ def accessibility_audit_core() -> dict[str, Any]:
 ARTICLE_MANIFEST: dict[str, Any] = {
     "title": "A tiny model reader that turns articles into guided narration",
     "reader_controls": [
-        {"key": "Space", "action": "Play or pause"},
-        {"key": "N", "action": "Next item"},
-        {"key": "P", "action": "Previous item"},
-        {"key": "H", "action": "Next heading"},
-        {"key": "I", "action": "Next image"},
-        {"key": "S", "action": "Summarize current section"},
-        {"key": "R", "action": "Repeat current item"},
-        {"key": "Esc", "action": "Stop audio"},
+        {"key": "Space", "aria_keyshortcuts": "Space", "action": "Play or pause"},
+        {"key": "N", "aria_keyshortcuts": "N", "action": "Next item"},
+        {"key": "P", "aria_keyshortcuts": "P", "action": "Previous item"},
+        {"key": "H", "aria_keyshortcuts": "H", "action": "Next heading"},
+        {"key": "I", "aria_keyshortcuts": "I", "action": "Next image"},
+        {"key": "S", "aria_keyshortcuts": "S", "action": "Summarize current section"},
+        {"key": "R", "aria_keyshortcuts": "R", "action": "Repeat current item"},
+        {"key": "Esc", "aria_keyshortcuts": "Escape", "action": "Stop audio"},
     ],
     "bonus_targets": ["Tiny Titan", "Llama Champion", "Off-Brand", "Field Notes"],
     "images": ARTICLE_IMAGES,

scripts/verify.py

@@ -37,7 +37,10 @@ def verify_static_assets() -> None:
     assert_true('data-reader-type="heading"' in index_html, "Article should mark heading reader nodes")
     assert_true('data-reader-type="image"' in index_html, "Article should mark image reader nodes")
     assert_true('aria-live="polite"' in index_html, "Article should expose an aria-live narration region")
+    for shortcut in ['aria-keyshortcuts="Space"', 'aria-keyshortcuts="N"', 'aria-keyshortcuts="S"']:
+        assert_true(shortcut in index_html, f"Reader controls should expose {shortcut}")
     assert_true("transcriptLog" in index_html, "Article should expose a visible transcript log")
+    assert_true("stopButton" in index_html, "Reader controls should expose a visible stop command")
     assert_true("demoScriptList" in index_html, "Article should expose the judge demo runbook")
     assert_true("demoApiCheckList" in index_html, "Article should expose judge API evidence checks")
     assert_true("imageReceiptList" in index_html, "Article should expose generated image receipts")
@@ -55,6 +58,7 @@ def verify_static_assets() -> None:
     )
     assert_true("aria-current" in app_js, "Reader mode should expose the active item as current")
     assert_true("shouldHandleReaderShortcut" in app_js, "Reader shortcuts should not hijack form controls")
+    assert_true("controls.stop.click()" in app_js, "Escape should route through the visible stop command")
     assert_true("reader-node-" in app_js, "Reader nodes should receive stable ids for control context")
     assert_true("narrate(node.index)" in app_js, "Reader mode should support click-to-read article items")
 
@@ -237,9 +241,17 @@ def verify_routes() -> None:
     assert_true(manifest.status_code == 200, "Article manifest route should return 200")
     manifest_payload = manifest.json()
     assert_true("Tiny Titan" in manifest_payload["bonus_targets"], "Manifest should include Tiny Titan target")
+    reader_controls = manifest_payload["reader_controls"]
+    summary_shortcut = next((item for item in reader_controls if item["key"] == "S"), None)
+    assert_true(summary_shortcut is not None, "Manifest should include summary shortcut")
     assert_true(
-        {"key": "S", "action": "Summarize current section"} in manifest_payload["reader_controls"],
-        "Manifest should include summary shortcut",
+        summary_shortcut["action"] == "Summarize current section"
+        and summary_shortcut["aria_keyshortcuts"] == "S",
+        "Manifest summary shortcut should include action and aria-keyshortcuts value",
+    )
+    assert_true(
+        {item["aria_keyshortcuts"] for item in reader_controls} >= {"Space", "N", "P", "H", "I", "S", "R", "Escape"},
+        "Manifest should expose aria-keyshortcuts values for reader controls",
     )
     assert_true(
         manifest_payload["models"]["speech"]["id"] == "hexgrad/Kokoro-82M",

static/app.js

@@ -38,6 +38,7 @@ const controls = {
   heading: document.querySelector("#headingButton"),
   image: document.querySelector("#imageButton"),
   summary: document.querySelector("#summaryButton"),
+  stop: document.querySelector("#stopButton"),
 };
 
 const nodes = [...document.querySelectorAll(".speakable")].map((element, index) => ({
@@ -675,6 +676,10 @@ controls.prev.addEventListener("click", () => narrate(Math.max(currentIndex - 1,
 controls.heading.addEventListener("click", () => nextByType("heading"));
 controls.image.addEventListener("click", () => nextByType("image"));
 controls.summary.addEventListener("click", () => summarizeCurrentSection());
+controls.stop.addEventListener("click", () => {
+  stopAudio();
+  liveNarration.textContent = "Reading stopped.";
+});
 nodes.forEach((node) => {
   node.element.addEventListener("click", (event) => {
     if (!enabled || isControlTarget(event.target)) return;
@@ -772,8 +777,5 @@ document.addEventListener("keydown", (event) => {
   if (key === "i") controls.image.click();
   if (key === "s") controls.summary.click();
   if (key === "r" && currentIndex >= 0) narrate(currentIndex);
-  if (key === "escape") {
-    stopAudio();
-    liveNarration.textContent = "Reading stopped.";
-  }
+  if (key === "escape") controls.stop.click();
 });

static/index.html

@@ -157,12 +157,13 @@
     </main>
 
     <section class="reader-bar" aria-label="Screen reader controls" hidden>
-      <button id="prevButton" type="button" title="Previous item">Prev</button>
-      <button id="playButton" type="button" title="Play or pause">Play</button>
-      <button id="nextButton" type="button" title="Next item">Next</button>
-      <button id="headingButton" type="button" title="Next heading">Heading</button>
-      <button id="imageButton" type="button" title="Next image">Image</button>
-      <button id="summaryButton" type="button" title="Summarize current section">Summary</button>
+      <button id="prevButton" type="button" title="Previous item" aria-keyshortcuts="P">Prev</button>
+      <button id="playButton" type="button" title="Play or pause" aria-keyshortcuts="Space">Play</button>
+      <button id="nextButton" type="button" title="Next item" aria-keyshortcuts="N">Next</button>
+      <button id="headingButton" type="button" title="Next heading" aria-keyshortcuts="H">Heading</button>
+      <button id="imageButton" type="button" title="Next image" aria-keyshortcuts="I">Image</button>
+      <button id="summaryButton" type="button" title="Summarize current section" aria-keyshortcuts="S">Summary</button>
+      <button id="stopButton" type="button" title="Stop audio" aria-keyshortcuts="Escape">Stop</button>
       <label>
         Voice
         <select id="voiceControl" aria-label="Reader voice"></select>