Add reader transcript and manifest

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

FIELD_NOTES.md

@@ -28,6 +28,8 @@ Tiny Narrator is a small-model accessibility article reader. It is not a generic
 
 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.
 
+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:
 
 - `Space`: play or pause.

README.md

@@ -82,3 +82,5 @@ The frontend builds a reading queue from semantic article nodes. When screen-rea
 - `Esc` stops the current audio.
 
 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.
+
+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.

app.py

@@ -26,6 +26,48 @@ LLAMA_CPP_MODEL = os.getenv("LLAMA_CPP_MODEL", "narrator-brain")
 GRADIO_SERVER_NAME = os.getenv("GRADIO_SERVER_NAME", "0.0.0.0")
 GRADIO_SERVER_PORT = int(os.getenv("PORT", os.getenv("GRADIO_SERVER_PORT", "7860")))
 
+MODEL_MANIFEST: dict[str, dict[str, str]] = {
+    "reader_brain": {
+        "id": "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF",
+        "params": "3.97B",
+        "runtime": "llama.cpp",
+        "role": "Plans concise narration and reading-order phrasing.",
+    },
+    "vision": {
+        "id": "openbmb/MiniCPM-V-2",
+        "params": "3B",
+        "runtime": "Python integration planned",
+        "role": "Describes images and OCR-like visual details.",
+    },
+    "speech": {
+        "id": "hexgrad/Kokoro-82M",
+        "params": "82M",
+        "runtime": "Python",
+        "role": "Speaks the final narration.",
+    },
+    "image_generation": {
+        "id": "black-forest-labs/FLUX.2-klein-4B",
+        "params": "4B",
+        "runtime": "Python integration planned",
+        "role": "Creates article illustrations.",
+    },
+}
+
+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": "R", "action": "Repeat current item"},
+        {"key": "Esc", "action": "Stop audio"},
+    ],
+    "bonus_targets": ["Tiny Titan", "Llama Champion", "Off-Brand", "Field Notes"],
+    "models": MODEL_MANIFEST,
+}
+
 app = Server(title="Tiny Narrator")
 app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
 app.mount("/outputs", StaticFiles(directory=OUTPUT_DIR), name="outputs")
@@ -208,32 +250,16 @@ async def health() -> JSONResponse:
             "app": "Tiny Narrator",
             "frontend": "custom Gradio Server HTML/CSS/JS",
             "llama_cpp_base_url": LLAMA_CPP_BASE_URL,
-            "models": {
-                "reader_brain": {
-                    "id": "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF",
-                    "params": "3.97B",
-                    "runtime": "llama.cpp",
-                },
-                "vision": {
-                    "id": "openbmb/MiniCPM-V-2",
-                    "params": "3B",
-                    "runtime": "Python integration planned",
-                },
-                "speech": {
-                    "id": "hexgrad/Kokoro-82M",
-                    "params": "82M",
-                    "runtime": "Python",
-                },
-                "image_generation": {
-                    "id": "black-forest-labs/FLUX.2-klein-4B",
-                    "params": "4B",
-                    "runtime": "Python integration planned",
-                },
-            },
+            "models": MODEL_MANIFEST,
         }
     )
 
 
+@app.get("/api/article-manifest")
+async def article_manifest() -> JSONResponse:
+    return _json({"ok": True, **ARTICLE_MANIFEST})
+
+
 @app.post("/api/reader-brain")
 async def reader_brain_endpoint(payload: ReaderBrainRequest) -> JSONResponse:
     return _json(reader_brain_core(payload.node_type, payload.text, payload.position, payload.mode))

scripts/verify.py

@@ -61,6 +61,7 @@ def verify_routes() -> None:
     assert_true(home.status_code == 200, "Home route should return 200")
     assert_true("Tiny Narrator" in home.text, "Home route should include app title")
     assert_true("readerToggle" in home.text, "Home route should include reader toggle")
+    assert_true("transcriptLog" in home.text, "Home route should include transcript log")
 
     health = client.get("/api/health")
     assert_true(health.status_code == 200, "Health route should return 200")
@@ -71,6 +72,15 @@ def verify_routes() -> None:
         "Health route should document llama.cpp reader-brain runtime",
     )
 
+    manifest = client.get("/api/article-manifest")
+    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")
+    assert_true(
+        manifest_payload["models"]["speech"]["id"] == "hexgrad/Kokoro-82M",
+        "Manifest should document Kokoro speech model",
+    )
+
 
 def main() -> None:
     py_compile.compile(str(ROOT / "app.py"), doraise=True)

static/app.css

@@ -243,6 +243,12 @@ figcaption {
   text-transform: uppercase;
 }
 
+.status-panel h3 {
+  margin: 0;
+  font-size: 0.86rem;
+  text-transform: uppercase;
+}
+
 dl {
   display: grid;
   gap: 12px;
@@ -269,6 +275,55 @@ dd {
   background: var(--surface);
 }
 
+.history-header {
+  display: grid;
+  grid-template-columns: 1fr max-content max-content;
+  gap: 8px;
+  align-items: center;
+  margin-top: 22px;
+}
+
+.history-header button {
+  min-height: 34px;
+  border-radius: 6px;
+  padding: 0 10px;
+  color: var(--muted);
+  font-size: 0.82rem;
+  font-weight: 750;
+}
+
+.transcript-log {
+  display: grid;
+  gap: 10px;
+  max-height: 340px;
+  margin: 12px 0 0;
+  padding: 0;
+  overflow: auto;
+  list-style: none;
+}
+
+.transcript-log li {
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 10px 12px;
+  background: var(--surface);
+}
+
+.transcript-meta {
+  display: flex;
+  justify-content: space-between;
+  gap: 8px;
+  color: var(--muted);
+  font-size: 0.75rem;
+  font-weight: 800;
+  text-transform: uppercase;
+}
+
+.transcript-text {
+  margin: 6px 0 0;
+  font-size: 0.92rem;
+}
+
 .reader-bar {
   position: fixed;
   right: clamp(14px, 3vw, 32px);

static/app.js

@@ -3,9 +3,13 @@ const readerBar = document.querySelector(".reader-bar");
 const modeStatus = document.querySelector("#modeStatus");
 const currentStatus = document.querySelector("#currentStatus");
 const runtimeStatus = document.querySelector("#runtimeStatus");
+const modelStatus = document.querySelector("#modelStatus");
 const liveNarration = document.querySelector("#liveNarration");
 const audio = document.querySelector("#speechAudio");
 const speedControl = document.querySelector("#speedControl");
+const transcriptLog = document.querySelector("#transcriptLog");
+const copyTranscriptButton = document.querySelector("#copyTranscriptButton");
+const clearTranscriptButton = document.querySelector("#clearTranscriptButton");
 
 const controls = {
   prev: document.querySelector("#prevButton"),
@@ -29,6 +33,46 @@ let enabled = false;
 let currentIndex = -1;
 let playing = false;
 let requestSerial = 0;
+let transcriptEntries = [];
+
+function escapeHtml(value) {
+  return value.replace(/[&<>"']/g, (char) => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+  }[char]));
+}
+
+function renderTranscript() {
+  transcriptLog.innerHTML = transcriptEntries
+    .map((entry) => `
+      <li>
+        <div class="transcript-meta">
+          <span>${escapeHtml(entry.type)}</span>
+          <span>${escapeHtml(entry.runtime)}</span>
+        </div>
+        <p class="transcript-text">${escapeHtml(entry.text)}</p>
+      </li>
+    `)
+    .join("");
+}
+
+function addTranscriptEntry(entry) {
+  transcriptEntries = [entry, ...transcriptEntries].slice(0, 12);
+  renderTranscript();
+}
+
+async function loadManifest() {
+  try {
+    const manifest = await postJson("/api/article-manifest");
+    const modelCount = Object.keys(manifest.models || {}).length;
+    modelStatus.textContent = `${modelCount} tiny models, ${manifest.bonus_targets.join(", ")}`;
+  } catch {
+    modelStatus.textContent = "Manifest unavailable";
+  }
+}
 
 function setEnabled(nextValue) {
   enabled = nextValue;
@@ -68,11 +112,12 @@ function stopAudio() {
 }
 
 async function postJson(url, payload) {
-  const response = await fetch(url, {
+  const options = payload === undefined ? {} : {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(payload),
-  });
+  };
+  const response = await fetch(url, options);
   if (!response.ok) {
     throw new Error(`${response.status} ${response.statusText}`);
   }
@@ -108,6 +153,11 @@ async function narrate(index) {
 
     runtimeStatus.textContent = result.runtime;
     liveNarration.textContent = result.narration;
+    addTranscriptEntry({
+      type: node.type,
+      runtime: result.runtime,
+      text: result.narration,
+    });
 
     const speech = await postJson("/api/speak", {
       text: result.narration,
@@ -153,6 +203,20 @@ controls.next.addEventListener("click", () => narrate(Math.min(currentIndex + 1,
 controls.prev.addEventListener("click", () => narrate(Math.max(currentIndex - 1, 0)));
 controls.heading.addEventListener("click", () => nextByType("heading"));
 controls.image.addEventListener("click", () => nextByType("image"));
+copyTranscriptButton.addEventListener("click", async () => {
+  const text = transcriptEntries
+    .slice()
+    .reverse()
+    .map((entry) => `[${entry.type} / ${entry.runtime}] ${entry.text}`)
+    .join("\n");
+  await navigator.clipboard?.writeText(text);
+  liveNarration.textContent = text ? "Transcript copied." : "Transcript is empty.";
+});
+clearTranscriptButton.addEventListener("click", () => {
+  transcriptEntries = [];
+  renderTranscript();
+  liveNarration.textContent = "Transcript cleared.";
+});
 controls.play.addEventListener("click", () => {
   if (!enabled) return;
   if (currentIndex < 0) {
@@ -172,6 +236,8 @@ controls.play.addEventListener("click", () => {
   }
 });
 
+loadManifest();
+
 audio.addEventListener("ended", () => {
   playing = false;
   controls.play.textContent = "Play";

static/index.html

@@ -92,10 +92,20 @@
             <dt>Runtime</dt>
             <dd id="runtimeStatus">Waiting</dd>
           </div>
+          <div>
+            <dt>Model Stack</dt>
+            <dd id="modelStatus">Loading</dd>
+          </div>
         </dl>
         <p id="liveNarration" class="live-narration" aria-live="polite">
           Turn on screen reader mode to begin.
         </p>
+        <div class="history-header">
+          <h3>Transcript</h3>
+          <button id="copyTranscriptButton" type="button">Copy</button>
+          <button id="clearTranscriptButton" type="button">Clear</button>
+        </div>
+        <ol id="transcriptLog" class="transcript-log" aria-label="Narration transcript"></ol>
       </aside>
     </main>