Include reader position in transcript

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

FIELD_NOTES.md

@@ -48,7 +48,7 @@ Reader shortcuts deliberately ignore form controls. A user can adjust the Kokoro
 
 The reader bar exposes the same shortcut contract through `aria-keyshortcuts`. Repeat and Stop also have visible buttons, 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. Clipboard failures are labeled in the live narration region instead of being treated as successful copies.
+Each narration is also added to a visible transcript log with reader position, runtime, and latency. 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. Clipboard failures are labeled in the live narration region instead of being treated as successful copies.
 
 Keyboard map:
 

README.md

@@ -109,7 +109,7 @@ Global reader shortcuts ignore buttons, links, selects, and inputs so the voice,
 
 Reader buttons expose `aria-keyshortcuts`, and the Repeat and Stop shortcuts are mirrored by visible controls 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. Copy actions report when browser clipboard access is unavailable, so the visible transcript and commands remain inspectable.
+The session panel keeps a transcript of recent narration with reader position, runtime, latency, copy, and clear controls, making the spoken path inspectable during demos and useful for the Field Notes write-up. Copy actions report when browser clipboard access is unavailable, so the visible transcript and commands remain inspectable.
 
 Images start with meaningful fallback `alt` text in the HTML. Image descriptions are then 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

@@ -6,7 +6,7 @@ Tiny Narrator turns an article into a guided screen-reader experience using smal
 
 ## Short description
 
-Tiny Narrator is a custom Gradio Server app that looks like an article/blog reader until screen-reader mode is switched on. In reader mode, the app builds a semantic reading queue, narrates headings and paragraphs, describes generated images, summarizes the current section, speaks with Kokoro, and keeps a visible transcript of the spoken path.
+Tiny Narrator is a custom Gradio Server app that looks like an article/blog reader until screen-reader mode is switched on. In reader mode, the app builds a semantic reading queue, narrates headings and paragraphs, describes generated images, summarizes the current section, speaks with Kokoro, and keeps a visible transcript of the spoken path with reader position, runtime, and latency.
 
 The prototype is designed for a live hackathon demo: every model-facing path has a deterministic fallback, runtime readiness is labeled in the UI, and the repo exposes machine-readable evidence for model size, setup, demo flow, and accessibility behavior.
 

app.py

@@ -451,7 +451,7 @@ def accessibility_audit_core() -> dict[str, Any]:
             "id": "inspectable_transcript",
             "label": "Inspectable transcript",
             "status": "pass",
-            "evidence": "Narration entries are stored in a visible transcript with copy and clear controls.",
+            "evidence": "Narration entries are stored in a visible transcript with reader position, runtime, latency, copy, and clear controls.",
         },
         {
             "id": "user_control",

scripts/verify.py

@@ -65,6 +65,12 @@ def verify_static_assets() -> None:
         "Transcript is visible, but clipboard access is unavailable." in app_js,
         "Transcript copy should report unavailable clipboard access",
     )
+    assert_true("transcript-position" in app_js, "Transcript should render the narrated reader position")
+    assert_true("readerItemStatus(node)" in app_js, "Narration transcript entries should include reader item position")
+    assert_true(
+        "[${entry.type} / ${entry.position} / ${entry.runtime}]" in app_js,
+        "Copied transcript should include type, position, and runtime",
+    )
     assert_true("function haltPlayback" in app_js, "Reader controls should expose a shared playback halt helper")
     assert_true(
         "haltPlayback({ clearAutoAdvance: false });" in app_js,

static/app.js

@@ -100,6 +100,7 @@ function renderTranscript() {
           <span>${escapeHtml(entry.type)} (${escapeHtml(formatElapsed(entry.elapsedMs))})</span>
           <span>${escapeHtml(entry.runtime)}</span>
         </div>
+        <p class="transcript-position">${escapeHtml(entry.position)}</p>
         <p class="transcript-text">${escapeHtml(entry.text)}</p>
       </li>
     `)
@@ -646,6 +647,7 @@ async function narrate(index) {
     latencyStatus.textContent = formatElapsed(elapsedMs);
     addTranscriptEntry({
       type: node.type,
+      position: readerItemStatus(node),
       runtime: `${result.runtime}/${speech?.runtime || "voice"}`,
       text: result.narration,
       elapsedMs,
@@ -684,6 +686,7 @@ async function summarizeCurrentSection() {
     latencyStatus.textContent = formatElapsed(elapsedMs);
     addTranscriptEntry({
       type: "summary",
+      position: section.title,
       runtime: `${result.runtime}/${speech?.runtime || "voice"}`,
       text: result.narration,
       elapsedMs,
@@ -749,7 +752,7 @@ copyTranscriptButton.addEventListener("click", async () => {
   const text = transcriptEntries
     .slice()
     .reverse()
-    .map((entry) => `[${entry.type} / ${entry.runtime}] ${entry.text}`)
+    .map((entry) => `[${entry.type} / ${entry.position} / ${entry.runtime}] ${entry.text}`)
     .join("\n");
   await copyTextToClipboard(
     text,