Add section summary reader command

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

FIELD_NOTES.md

@@ -37,6 +37,7 @@ Keyboard map:
 - `P`: previous item.
 - `H`: next heading.
 - `I`: next image.
+- `S`: summarize the current section.
 - `R`: repeat current item.
 - `Esc`: stop audio.
 

README.md

@@ -78,6 +78,7 @@ The frontend builds a reading queue from semantic article nodes. When screen-rea
 - `P` moves to the previous item.
 - `H` moves to the next heading.
 - `I` moves to the next image.
+- `S` summarizes the current section.
 - `R` repeats the current item.
 - `Esc` stops the current audio.
 

app.py

@@ -61,6 +61,7 @@ ARTICLE_MANIFEST: dict[str, Any] = {
         {"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"},
     ],
@@ -101,16 +102,33 @@ def _json(data: dict[str, Any], status_code: int = 200) -> JSONResponse:
     return JSONResponse(data, status_code=status_code)
 
 
+def _compact_text(text: str, limit: int = 220) -> str:
+    normalized = " ".join(text.split())
+    if len(normalized) <= limit:
+        return normalized
+    return f"{normalized[: limit - 1].rstrip()}."
+
+
 def reader_brain_core(node_type: str, text: str, position: str | None, mode: str) -> dict[str, Any]:
-    prompt = (
-        "Convert this article node into concise screen-reader narration.\n"
-        f"Mode: {mode}\n"
-        f"Node type: {node_type}\n"
-        f"Position: {position or 'unknown'}\n"
-        f"Content: {text}\n\n"
-        "Rules: announce the node type only when it helps orientation, keep prose short, "
-        "and never mention implementation details."
-    )
+    if mode == "summarize":
+        prompt = (
+            "Summarize this article section for screen-reader navigation.\n"
+            f"Node type: {node_type}\n"
+            f"Position: {position or 'unknown'}\n"
+            f"Content: {text}\n\n"
+            "Rules: start with 'Summary.', use one or two short sentences, explain what the "
+            "reader can learn in this section, and never mention implementation details."
+        )
+    else:
+        prompt = (
+            "Convert this article node into concise screen-reader narration.\n"
+            f"Mode: {mode}\n"
+            f"Node type: {node_type}\n"
+            f"Position: {position or 'unknown'}\n"
+            f"Content: {text}\n\n"
+            "Rules: announce the node type only when it helps orientation, keep prose short, "
+            "and never mention implementation details."
+        )
 
     try:
         body = json.dumps(
@@ -152,12 +170,14 @@ def reader_brain_core(node_type: str, text: str, position: str | None, mode: str
             "button": "Control. ",
             "quote": "Quote. ",
         }.get(node_type, "")
+        if mode == "summarize":
+            prefix = "Summary. "
         return {
             "ok": True,
             "runtime": "fallback",
             "model": "rule-based local fallback",
             "warning": f"llama.cpp unavailable: {exc.__class__.__name__}",
-            "narration": f"{prefix}{text}".strip(),
+            "narration": f"{prefix}{_compact_text(text)}".strip(),
         }
 
 

scripts/verify.py

@@ -41,6 +41,15 @@ def verify_core_fallbacks() -> None:
     assert_true(narration["ok"], "Reader-brain fallback did not return ok")
     assert_true("Heading." in narration["narration"], "Reader-brain fallback lost heading prefix")
 
+    summary = app.reader_brain_core(
+        node_type="section",
+        text="Tiny models can run close to the reader. They keep latency low and preserve privacy.",
+        position="Why",
+        mode="summarize",
+    )
+    assert_true(summary["ok"], "Reader-brain summary fallback did not return ok")
+    assert_true(summary["narration"].startswith("Summary."), "Summary fallback should announce summary mode")
+
     description = app.describe_image_core("model-map", caption=None, prompt=None)
     assert_true(description["ok"], "Image description did not return ok")
     assert_true("small AI models" in description["alt_text"], "Image description fallback changed unexpectedly")
@@ -61,6 +70,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("summaryButton" in home.text, "Home route should include summary control")
     assert_true("transcriptLog" in home.text, "Home route should include transcript log")
 
     health = client.get("/api/health")
@@ -76,6 +86,10 @@ 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")
+    assert_true(
+        {"key": "S", "action": "Summarize current section"} in manifest_payload["reader_controls"],
+        "Manifest should include summary shortcut",
+    )
     assert_true(
         manifest_payload["models"]["speech"]["id"] == "hexgrad/Kokoro-82M",
         "Manifest should document Kokoro speech model",

static/app.js

@@ -17,6 +17,7 @@ const controls = {
   next: document.querySelector("#nextButton"),
   heading: document.querySelector("#headingButton"),
   image: document.querySelector("#imageButton"),
+  summary: document.querySelector("#summaryButton"),
 };
 
 const nodes = [...document.querySelectorAll(".speakable")].map((element, index) => ({
@@ -64,6 +65,21 @@ function addTranscriptEntry(entry) {
   renderTranscript();
 }
 
+function currentSection() {
+  const activeNode = nodes[currentIndex]?.element;
+  return activeNode?.closest("section") || document.querySelector("#article article");
+}
+
+function currentSectionPayload() {
+  const section = currentSection();
+  const title = section.querySelector("h1, h2, h3")?.innerText.trim() || "Article introduction";
+  const text = [...section.querySelectorAll(".speakable")]
+    .map((element) => element.innerText.replace(/\s+/g, " ").trim())
+    .filter(Boolean)
+    .join(" ");
+  return { title, text };
+}
+
 async function loadManifest() {
   try {
     const manifest = await postJson("/api/article-manifest");
@@ -182,11 +198,59 @@ async function narrate(index) {
   }
 }
 
+async function summarizeCurrentSection() {
+  if (!enabled) return;
+  const serial = ++requestSerial;
+  const section = currentSectionPayload();
+  runtimeStatus.textContent = "Summarizing";
+  controls.summary.disabled = true;
+
+  try {
+    const result = await postJson("/api/reader-brain", {
+      node_type: "section",
+      text: section.text,
+      position: section.title,
+      mode: "summarize",
+    });
+
+    if (serial !== requestSerial) return;
+
+    runtimeStatus.textContent = result.runtime;
+    liveNarration.textContent = result.narration;
+    addTranscriptEntry({
+      type: "summary",
+      runtime: result.runtime,
+      text: result.narration,
+    });
+
+    const speech = await postJson("/api/speak", {
+      text: result.narration,
+      speed: Number(speedControl.value),
+    });
+
+    if (serial !== requestSerial) return;
+
+    if (speech.audio_url) {
+      audio.src = speech.audio_url;
+      await audio.play().catch(() => {
+        liveNarration.textContent = `${result.narration} Audio is ready. Press Play to hear it.`;
+      });
+      playing = !audio.paused;
+      controls.play.textContent = playing ? "Pause" : "Play";
+    }
+  } catch (error) {
+    runtimeStatus.textContent = "Error";
+    liveNarration.textContent = `Summary failed: ${error.message}`;
+  } finally {
+    controls.summary.disabled = false;
+  }
+}
+
 function announceIntro() {
   const headings = nodes.filter((node) => node.type === "heading").length;
   const images = nodes.filter((node) => node.type === "image").length;
   liveNarration.textContent =
-    `Screen reader mode on. Article contains ${headings} headings, ${images} images, and ${nodes.length} readable items. Press N for next, H for heading, I for image, or Space to begin.`;
+    `Screen reader mode on. Article contains ${headings} headings, ${images} images, and ${nodes.length} readable items. Press N for next, H for heading, I for image, S for section summary, or Space to begin.`;
   runtimeStatus.textContent = "Ready";
 }
 
@@ -203,6 +267,7 @@ 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"));
+controls.summary.addEventListener("click", () => summarizeCurrentSection());
 copyTranscriptButton.addEventListener("click", async () => {
   const text = transcriptEntries
     .slice()
@@ -246,7 +311,7 @@ audio.addEventListener("ended", () => {
 document.addEventListener("keydown", (event) => {
   if (!enabled) return;
   const key = event.key.toLowerCase();
-  if ([" ", "n", "p", "h", "i", "r", "escape"].includes(key)) {
+  if ([" ", "n", "p", "h", "i", "s", "r", "escape"].includes(key)) {
     event.preventDefault();
   }
   if (key === " ") controls.play.click();
@@ -254,6 +319,7 @@ document.addEventListener("keydown", (event) => {
   if (key === "p") controls.prev.click();
   if (key === "h") controls.heading.click();
   if (key === "i") controls.image.click();
+  if (key === "s") controls.summary.click();
   if (key === "r" && currentIndex >= 0) narrate(currentIndex);
   if (key === "escape") {
     stopAudio();

static/index.html

@@ -115,6 +115,7 @@
       <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>
       <label>
         Speed
         <input id="speedControl" type="range" min="0.75" max="1.35" value="1" step="0.05" />