Start Tiny Narrator hackathon app

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

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+outputs/*.wav
+outputs/*.mp3
+outputs/*.flac
+.gradio/
+.env

README.md

@@ -0,0 +1,55 @@
+# Tiny Narrator
+
+Tiny Narrator is a Build Small Hackathon prototype: a custom Gradio Server article app that can switch into a guided screen-reader mode.
+
+## Award Strategy
+
+- **Tiny Titan:** every planned model is at or below 4B parameters.
+- **Llama Champion:** the reader-brain layer calls a GGUF model through `llama.cpp`.
+- **Off-Brand:** the visible UI is custom HTML, CSS, and JavaScript served by `gr.Server`.
+- **Field Notes:** the repo documents model sizes, runtime choices, fallbacks, and accessibility decisions.
+
+## Recommended Models
+
+| Role | Model | Params | Runtime |
+| --- | ---: | ---: | --- |
+| Reader brain | `nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF` | 3.97B | `llama.cpp` |
+| Image understanding | `openbmb/MiniCPM-V-2` | 3B | Python integration planned |
+| Text to speech | `hexgrad/Kokoro-82M` | 82M | Python |
+| Image generation | `black-forest-labs/FLUX.2-klein-4B` | 4B | Python integration planned |
+
+## Run Locally
+
+Install dependencies:
+
+```powershell
+python -m pip install -r requirements.txt
+```
+
+Start the llama.cpp reader-brain server:
+
+```powershell
+llama-server -hf nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF:Q4_K_M --alias narrator-brain --port 8080 --host 0.0.0.0
+```
+
+Start the app:
+
+```powershell
+python app.py
+```
+
+Open the local URL printed by Gradio. The custom frontend calls `/api/reader-brain`, `/api/describe-image`, `/api/speak`, and `/api/generate-image`.
+
+## Screen Reader Mode
+
+The frontend builds a reading queue from semantic article nodes. When screen-reader mode is on:
+
+- `Space` plays or pauses.
+- `N` moves to the next item.
+- `P` moves to the previous item.
+- `H` moves to the next heading.
+- `I` moves to the next image.
+- `R` repeats the current item.
+- `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.

app.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+import json
+import os
+import wave
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+import requests
+from fastapi import Request
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from gradio import Server
+from pydantic import BaseModel
+
+
+ROOT = Path(__file__).parent
+STATIC_DIR = ROOT / "static"
+OUTPUT_DIR = ROOT / "outputs"
+OUTPUT_DIR.mkdir(exist_ok=True)
+
+LLAMA_CPP_BASE_URL = os.getenv("LLAMA_CPP_BASE_URL", "http://localhost:8080/v1")
+LLAMA_CPP_MODEL = os.getenv("LLAMA_CPP_MODEL", "narrator-brain")
+
+app = Server(title="Tiny Narrator")
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+app.mount("/outputs", StaticFiles(directory=OUTPUT_DIR), name="outputs")
+
+
+class ReaderBrainRequest(BaseModel):
+    node_type: str = "paragraph"
+    text: str
+    position: str | None = None
+    mode: str = "narrate"
+
+
+class ImageDescriptionRequest(BaseModel):
+    image_id: str
+    caption: str | None = None
+    prompt: str | None = None
+
+
+class SpeechRequest(BaseModel):
+    text: str
+    voice: str = "af_heart"
+    speed: float = 1.0
+
+
+class ImageGenerationRequest(BaseModel):
+    prompt: str
+    seed: int | None = None
+
+
+def _json(data: dict[str, Any], status_code: int = 200) -> JSONResponse:
+    return JSONResponse(data, status_code=status_code)
+
+
+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."
+    )
+
+    try:
+        response = requests.post(
+            f"{LLAMA_CPP_BASE_URL}/chat/completions",
+            json={
+                "model": LLAMA_CPP_MODEL,
+                "messages": [
+                    {
+                        "role": "system",
+                        "content": (
+                            "You are Tiny Narrator's accessibility layer. "
+                            "Produce clear screen-reader narration for article content."
+                        ),
+                    },
+                    {"role": "user", "content": prompt},
+                ],
+                "temperature": 0.2,
+                "max_tokens": 180,
+            },
+            timeout=45,
+        )
+        response.raise_for_status()
+        payload = response.json()
+        narration = payload["choices"][0]["message"]["content"].strip()
+        return {
+            "ok": True,
+            "runtime": "llama.cpp",
+            "model": LLAMA_CPP_MODEL,
+            "narration": narration,
+        }
+    except Exception as exc:
+        prefix = {
+            "heading": "Heading. ",
+            "image": "Image. ",
+            "button": "Control. ",
+            "quote": "Quote. ",
+        }.get(node_type, "")
+        return {
+            "ok": True,
+            "runtime": "fallback",
+            "model": "rule-based local fallback",
+            "warning": f"llama.cpp unavailable: {exc.__class__.__name__}",
+            "narration": f"{prefix}{text}".strip(),
+        }
+
+
+def describe_image_core(image_id: str, caption: str | None, prompt: str | None) -> dict[str, Any]:
+    # The first committed slice keeps the API stable while the MiniCPM-V runtime lands next.
+    # The frontend passes deterministic image ids so cached descriptions can replace this later.
+    descriptions = {
+        "desk-reader": (
+            "A person reads a long article on a laptop while an accessibility toolbar "
+            "highlights the current paragraph."
+        ),
+        "model-map": (
+            "A compact diagram showing four small AI models working together: vision, "
+            "reader brain, speech, and image generation."
+        ),
+        "field-notes": (
+            "A notebook page with short build notes, model sizes, and accessibility checks."
+        ),
+    }
+    alt_text = descriptions.get(
+        image_id,
+        caption or prompt or "A generated article image awaiting model description.",
+    )
+    return {
+        "ok": True,
+        "runtime": "MiniCPM-V placeholder",
+        "model": "OpenBMB MiniCPM-V-2",
+        "alt_text": alt_text,
+    }
+
+
+def _silent_wav(path: Path, seconds: float = 0.35, sample_rate: int = 24000) -> None:
+    frames = int(seconds * sample_rate)
+    with wave.open(str(path), "wb") as wav:
+        wav.setnchannels(1)
+        wav.setsampwidth(2)
+        wav.setframerate(sample_rate)
+        wav.writeframes(b"\x00\x00" * frames)
+
+
+def speak_core(text: str, voice: str, speed: float) -> dict[str, Any]:
+    try:
+        from kokoro import KPipeline
+        import soundfile as sf
+
+        pipeline = KPipeline(lang_code="a")
+        generator = pipeline(text, voice=voice, speed=speed)
+        _, _, audio = next(generator)
+        output_path = OUTPUT_DIR / f"speech-{uuid4().hex}.wav"
+        sf.write(output_path, audio, 24000)
+        runtime = "kokoro"
+        warning = None
+    except Exception as exc:
+        output_path = OUTPUT_DIR / f"speech-fallback-{uuid4().hex}.wav"
+        _silent_wav(output_path)
+        runtime = "fallback"
+        warning = f"Kokoro unavailable: {exc.__class__.__name__}"
+
+    return {
+        "ok": True,
+        "runtime": runtime,
+        "model": "hexgrad/Kokoro-82M",
+        "warning": warning,
+        "audio_url": f"/outputs/{output_path.name}",
+        "transcript": text,
+    }
+
+
+def generate_image_core(prompt: str, seed: int | None) -> dict[str, Any]:
+    return {
+        "ok": True,
+        "runtime": "placeholder",
+        "model": "black-forest-labs/FLUX.2-klein-4B",
+        "image_url": f"/static/generated/{'field-notes.svg' if seed == 3 else 'model-map.svg'}",
+        "prompt": prompt,
+        "seed": seed,
+    }
+
+
+@app.get("/", response_class=HTMLResponse)
+async def home() -> str:
+    return (STATIC_DIR / "index.html").read_text(encoding="utf-8")
+
+
+@app.get("/api/health")
+async def health() -> JSONResponse:
+    return _json(
+        {
+            "ok": True,
+            "app": "Tiny Narrator",
+            "models": {
+                "reader_brain": "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF via llama.cpp",
+                "vision": "openbmb/MiniCPM-V-2",
+                "speech": "hexgrad/Kokoro-82M",
+                "image_generation": "black-forest-labs/FLUX.2-klein-4B",
+            },
+        }
+    )
+
+
+@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))
+
+
+@app.post("/api/describe-image")
+async def describe_image_endpoint(payload: ImageDescriptionRequest) -> JSONResponse:
+    return _json(describe_image_core(payload.image_id, payload.caption, payload.prompt))
+
+
+@app.post("/api/speak")
+async def speak_endpoint(payload: SpeechRequest) -> JSONResponse:
+    return _json(speak_core(payload.text, payload.voice, payload.speed))
+
+
+@app.post("/api/generate-image")
+async def generate_image_endpoint(payload: ImageGenerationRequest) -> JSONResponse:
+    return _json(generate_image_core(payload.prompt, payload.seed))
+
+
+@app.api(name="reader_brain")
+def reader_brain_api(node_type: str, text: str, position: str = "", mode: str = "narrate") -> str:
+    return json.dumps(reader_brain_core(node_type, text, position, mode))
+
+
+@app.api(name="describe_image")
+def describe_image_api(image_id: str, caption: str = "", prompt: str = "") -> str:
+    return json.dumps(describe_image_core(image_id, caption, prompt))
+
+
+@app.api(name="speak")
+def speak_api(text: str, voice: str = "af_heart", speed: float = 1.0) -> str:
+    return json.dumps(speak_core(text, voice, speed))
+
+
+@app.api(name="generate_image")
+def generate_image_api(prompt: str, seed: int | None = None) -> str:
+    return json.dumps(generate_image_core(prompt, seed))
+
+
+@app.exception_handler(Exception)
+async def handle_exception(_: Request, exc: Exception) -> JSONResponse:
+    return _json({"ok": False, "error": exc.__class__.__name__, "detail": str(exc)}, status_code=500)
+
+
+if __name__ == "__main__":
+    app.launch()

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=5.34.0
+requests>=2.32.0
+pydantic>=2.7.0
+kokoro>=0.9.4
+soundfile>=0.12.1

static/app.css

@@ -0,0 +1,360 @@
+:root {
+  color-scheme: light;
+  --ink: #202124;
+  --muted: #62696f;
+  --paper: #fbfaf7;
+  --surface: #ffffff;
+  --line: #d8d3ca;
+  --accent: #1f6f68;
+  --accent-strong: #184d48;
+  --focus: #c5452c;
+  --shadow: 0 18px 45px rgba(32, 33, 36, 0.12);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  margin: 0;
+  background: var(--paper);
+  color: var(--ink);
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  line-height: 1.55;
+}
+
+button,
+input {
+  font: inherit;
+}
+
+button {
+  border: 1px solid var(--line);
+  background: var(--surface);
+  color: var(--ink);
+  cursor: pointer;
+}
+
+button:hover {
+  border-color: var(--accent);
+}
+
+button:focus-visible,
+a:focus-visible,
+input:focus-visible {
+  outline: 3px solid var(--focus);
+  outline-offset: 3px;
+}
+
+.topbar {
+  position: sticky;
+  top: 0;
+  z-index: 20;
+  display: grid;
+  grid-template-columns: max-content 1fr max-content;
+  align-items: center;
+  gap: 24px;
+  min-height: 72px;
+  padding: 12px clamp(18px, 4vw, 48px);
+  border-bottom: 1px solid rgba(216, 211, 202, 0.88);
+  background: rgba(251, 250, 247, 0.92);
+  backdrop-filter: blur(16px);
+}
+
+.brand {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  color: var(--ink);
+  font-weight: 750;
+  text-decoration: none;
+}
+
+.brand-mark {
+  display: grid;
+  width: 38px;
+  height: 38px;
+  place-items: center;
+  border-radius: 6px;
+  background: var(--ink);
+  color: var(--paper);
+  font-size: 0.82rem;
+  letter-spacing: 0;
+}
+
+.topnav {
+  display: flex;
+  justify-content: center;
+  gap: clamp(12px, 3vw, 28px);
+}
+
+.topnav a {
+  color: var(--muted);
+  font-size: 0.92rem;
+  font-weight: 650;
+  text-decoration: none;
+}
+
+.topnav a:hover {
+  color: var(--accent-strong);
+}
+
+.reader-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 174px;
+  min-height: 42px;
+  gap: 10px;
+  border-radius: 999px;
+  padding: 0 16px;
+  font-weight: 700;
+}
+
+.toggle-dot {
+  width: 12px;
+  height: 12px;
+  border-radius: 999px;
+  background: #8b949e;
+}
+
+.reader-toggle[aria-pressed="true"] {
+  border-color: var(--accent);
+  background: var(--accent);
+  color: white;
+}
+
+.reader-toggle[aria-pressed="true"] .toggle-dot {
+  background: #f4d35e;
+}
+
+.article-shell {
+  display: grid;
+  grid-template-columns: minmax(0, 760px) minmax(260px, 340px);
+  gap: clamp(28px, 5vw, 64px);
+  width: min(1180px, calc(100% - 36px));
+  margin: 46px auto 130px;
+  align-items: start;
+}
+
+.article {
+  min-width: 0;
+}
+
+.kicker {
+  margin: 0 0 14px;
+  color: var(--accent-strong);
+  font-size: 0.88rem;
+  font-weight: 800;
+  letter-spacing: 0;
+  text-transform: uppercase;
+}
+
+h1,
+h2 {
+  line-height: 1.08;
+  letter-spacing: 0;
+}
+
+h1 {
+  max-width: 11ch;
+  margin: 0;
+  font-family: Georgia, "Times New Roman", serif;
+  font-size: clamp(3.4rem, 10vw, 6.7rem);
+  font-weight: 540;
+}
+
+h2 {
+  margin: 72px 0 16px;
+  font-size: clamp(1.8rem, 3.6vw, 3rem);
+}
+
+.dek {
+  max-width: 680px;
+  margin: 24px 0 34px;
+  color: #3d4247;
+  font-size: clamp(1.18rem, 2.4vw, 1.5rem);
+}
+
+p,
+blockquote,
+figcaption {
+  font-size: 1.05rem;
+}
+
+blockquote {
+  margin: 32px 0;
+  padding: 0 0 0 24px;
+  border-left: 5px solid var(--accent);
+  color: #33383c;
+  font-size: 1.35rem;
+  font-family: Georgia, "Times New Roman", serif;
+}
+
+figure {
+  margin: 0;
+}
+
+img {
+  display: block;
+  max-width: 100%;
+}
+
+.hero-figure,
+.inline-figure {
+  overflow: hidden;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--surface);
+  box-shadow: var(--shadow);
+}
+
+.hero-figure img,
+.inline-figure img {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  object-fit: cover;
+}
+
+figcaption {
+  padding: 14px 16px 16px;
+  color: var(--muted);
+}
+
+.inline-figure {
+  margin-top: 24px;
+  box-shadow: none;
+}
+
+.status-panel {
+  position: sticky;
+  top: 96px;
+  border-left: 1px solid var(--line);
+  padding-left: 24px;
+}
+
+.status-panel h2 {
+  margin: 0 0 18px;
+  font-size: 1rem;
+  text-transform: uppercase;
+}
+
+dl {
+  display: grid;
+  gap: 12px;
+  margin: 0;
+}
+
+dt {
+  color: var(--muted);
+  font-size: 0.78rem;
+  font-weight: 800;
+  text-transform: uppercase;
+}
+
+dd {
+  margin: 2px 0 0;
+  font-weight: 650;
+}
+
+.live-narration {
+  margin-top: 22px;
+  padding: 16px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--surface);
+}
+
+.reader-bar {
+  position: fixed;
+  right: clamp(14px, 3vw, 32px);
+  bottom: clamp(14px, 3vw, 32px);
+  left: clamp(14px, 3vw, 32px);
+  z-index: 30;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  min-height: 72px;
+  padding: 12px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: rgba(255, 255, 255, 0.96);
+  box-shadow: var(--shadow);
+}
+
+.reader-bar[hidden] {
+  display: none;
+}
+
+.reader-bar button {
+  min-width: 88px;
+  min-height: 42px;
+  border-radius: 6px;
+  font-weight: 750;
+}
+
+.reader-bar label {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--muted);
+  font-size: 0.92rem;
+  font-weight: 750;
+}
+
+.speakable {
+  scroll-margin: 112px;
+}
+
+.reader-active {
+  outline: 4px solid var(--focus);
+  outline-offset: 8px;
+  background: rgba(197, 69, 44, 0.05);
+}
+
+@media (max-width: 900px) {
+  .topbar {
+    grid-template-columns: 1fr;
+    gap: 12px;
+  }
+
+  .topnav {
+    justify-content: flex-start;
+    overflow-x: auto;
+  }
+
+  .reader-toggle {
+    width: 100%;
+  }
+
+  .article-shell {
+    grid-template-columns: 1fr;
+  }
+
+  h1 {
+    max-width: 12ch;
+    font-size: clamp(3rem, 17vw, 5rem);
+  }
+
+  .status-panel {
+    position: static;
+    border-left: 0;
+    border-top: 1px solid var(--line);
+    padding: 24px 0 0;
+  }
+
+  .reader-bar {
+    flex-wrap: wrap;
+    justify-content: flex-start;
+  }
+
+  .reader-bar button {
+    min-width: 76px;
+    flex: 1 1 28%;
+  }
+}

static/app.js

@@ -0,0 +1,180 @@
+const toggle = document.querySelector("#readerToggle");
+const readerBar = document.querySelector(".reader-bar");
+const modeStatus = document.querySelector("#modeStatus");
+const currentStatus = document.querySelector("#currentStatus");
+const runtimeStatus = document.querySelector("#runtimeStatus");
+const liveNarration = document.querySelector("#liveNarration");
+const audio = document.querySelector("#speechAudio");
+const speedControl = document.querySelector("#speedControl");
+
+const controls = {
+  prev: document.querySelector("#prevButton"),
+  play: document.querySelector("#playButton"),
+  next: document.querySelector("#nextButton"),
+  heading: document.querySelector("#headingButton"),
+  image: document.querySelector("#imageButton"),
+};
+
+const nodes = [...document.querySelectorAll(".speakable")].map((element, index) => ({
+  element,
+  index,
+  type: element.dataset.readerType || "paragraph",
+  imageId: element.dataset.imageId || null,
+  get text() {
+    return element.innerText.replace(/\s+/g, " ").trim();
+  },
+}));
+
+let enabled = false;
+let currentIndex = -1;
+let playing = false;
+
+function setEnabled(nextValue) {
+  enabled = nextValue;
+  toggle.setAttribute("aria-pressed", String(enabled));
+  toggle.lastChild.textContent = enabled ? " Screen reader on" : " Screen reader off";
+  readerBar.hidden = !enabled;
+  modeStatus.textContent = enabled ? "Reader on" : "Reader off";
+  if (enabled) {
+    announceIntro();
+  } else {
+    stopAudio();
+    setActive(-1);
+    liveNarration.textContent = "Turn on screen reader mode to begin.";
+  }
+}
+
+function setActive(index) {
+  nodes.forEach((node) => node.element.classList.remove("reader-active"));
+  currentIndex = index;
+  const node = nodes[currentIndex];
+  if (!node) {
+    currentStatus.textContent = "No item selected";
+    return;
+  }
+  node.element.classList.add("reader-active");
+  node.element.setAttribute("tabindex", "-1");
+  node.element.focus({ preventScroll: true });
+  node.element.scrollIntoView({ block: "center", behavior: "smooth" });
+  currentStatus.textContent = `${node.type}, item ${currentIndex + 1} of ${nodes.length}`;
+}
+
+function stopAudio() {
+  audio.pause();
+  audio.removeAttribute("src");
+  playing = false;
+  controls.play.textContent = "Play";
+}
+
+async function postJson(url, payload) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  if (!response.ok) {
+    throw new Error(`${response.status} ${response.statusText}`);
+  }
+  return response.json();
+}
+
+async function narrate(index) {
+  if (!enabled || !nodes[index]) return;
+  setActive(index);
+  const node = nodes[index];
+  runtimeStatus.textContent = "Thinking";
+
+  let sourceText = node.text;
+  if (node.type === "image") {
+    const description = await postJson("/api/describe-image", {
+      image_id: node.imageId,
+      caption: node.text,
+    });
+    sourceText = description.alt_text;
+  }
+
+  const result = await postJson("/api/reader-brain", {
+    node_type: node.type,
+    text: sourceText,
+    position: `item ${index + 1} of ${nodes.length}`,
+    mode: "narrate",
+  });
+
+  runtimeStatus.textContent = result.runtime;
+  liveNarration.textContent = result.narration;
+
+  const speech = await postJson("/api/speak", {
+    text: result.narration,
+    speed: Number(speedControl.value),
+  });
+
+  if (speech.audio_url) {
+    audio.src = speech.audio_url;
+    await audio.play().catch(() => {});
+    playing = true;
+    controls.play.textContent = "Pause";
+  }
+}
+
+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.`;
+  runtimeStatus.textContent = "Ready";
+}
+
+function nextByType(type) {
+  const start = Math.max(currentIndex + 1, 0);
+  const found = nodes.find((node) => node.index >= start && node.type === type);
+  if (found) return narrate(found.index);
+  const wrapped = nodes.find((node) => node.type === type);
+  if (wrapped) return narrate(wrapped.index);
+}
+
+toggle.addEventListener("click", () => setEnabled(!enabled));
+controls.next.addEventListener("click", () => narrate(Math.min(currentIndex + 1, nodes.length - 1)));
+controls.prev.addEventListener("click", () => narrate(Math.max(currentIndex - 1, 0)));
+controls.heading.addEventListener("click", () => nextByType("heading"));
+controls.image.addEventListener("click", () => nextByType("image"));
+controls.play.addEventListener("click", () => {
+  if (!enabled) return;
+  if (currentIndex < 0) {
+    narrate(0);
+    return;
+  }
+  if (playing) {
+    audio.pause();
+    playing = false;
+    controls.play.textContent = "Play";
+  } else if (audio.src) {
+    audio.play();
+    playing = true;
+    controls.play.textContent = "Pause";
+  } else {
+    narrate(currentIndex);
+  }
+});
+
+audio.addEventListener("ended", () => {
+  playing = false;
+  controls.play.textContent = "Play";
+});
+
+document.addEventListener("keydown", (event) => {
+  if (!enabled) return;
+  const key = event.key.toLowerCase();
+  if ([" ", "n", "p", "h", "i", "r", "escape"].includes(key)) {
+    event.preventDefault();
+  }
+  if (key === " ") controls.play.click();
+  if (key === "n") controls.next.click();
+  if (key === "p") controls.prev.click();
+  if (key === "h") controls.heading.click();
+  if (key === "i") controls.image.click();
+  if (key === "r" && currentIndex >= 0) narrate(currentIndex);
+  if (key === "escape") {
+    stopAudio();
+    liveNarration.textContent = "Reading stopped.";
+  }
+});

static/index.html

@@ -0,0 +1,117 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Tiny Narrator</title>
+    <link rel="stylesheet" href="/static/app.css" />
+  </head>
+  <body>
+    <header class="topbar">
+      <a class="brand" href="#article" aria-label="Tiny Narrator home">
+        <span class="brand-mark" aria-hidden="true">TN</span>
+        <span>Tiny Narrator</span>
+      </a>
+      <nav class="topnav" aria-label="Article sections">
+        <a href="#why">Why</a>
+        <a href="#models">Models</a>
+        <a href="#notes">Field Notes</a>
+      </nav>
+      <button id="readerToggle" class="reader-toggle" type="button" aria-pressed="false">
+        <span class="toggle-dot" aria-hidden="true"></span>
+        Screen reader off
+      </button>
+    </header>
+
+    <main id="article" class="article-shell">
+      <article class="article" aria-labelledby="articleTitle">
+        <p class="kicker speakable" data-reader-type="paragraph">Build Small Hackathon concept</p>
+        <h1 id="articleTitle" class="speakable" data-reader-type="heading">
+          A tiny model reader that turns articles into guided narration
+        </h1>
+        <p class="dek speakable" data-reader-type="paragraph">
+          Tiny Narrator is an accessibility-first article experience. It can describe generated images,
+          build a reading path, and speak each part of the page with a lightweight local voice.
+        </p>
+
+        <figure class="hero-figure speakable" data-reader-type="image" data-image-id="desk-reader">
+          <img src="/static/generated/desk-reader.svg" alt="" />
+          <figcaption>
+            The article view doubles as the demo surface, so every feature has a real reading task.
+          </figcaption>
+        </figure>
+
+        <section id="why" aria-labelledby="whyTitle">
+          <h2 id="whyTitle" class="speakable" data-reader-type="heading">Why it belongs in a tiny-model hackathon</h2>
+          <p class="speakable" data-reader-type="paragraph">
+            Accessibility tools should feel immediate, private, and personal. Small models help because they
+            can run closer to the reader, keep latency low, and make the experience easier to inspect.
+          </p>
+          <blockquote class="speakable" data-reader-type="quote">
+            The goal is not to read the whole page at the user. The goal is to make the page navigable by sound.
+          </blockquote>
+        </section>
+
+        <section id="models" aria-labelledby="modelsTitle">
+          <h2 id="modelsTitle" class="speakable" data-reader-type="heading">The model map</h2>
+          <p class="speakable" data-reader-type="paragraph">
+            The reader brain runs through llama.cpp, the vision model writes practical alt text, Kokoro speaks
+            the final narration, and a four-billion-parameter image model creates article illustrations.
+          </p>
+          <figure class="inline-figure speakable" data-reader-type="image" data-image-id="model-map">
+            <img src="/static/generated/model-map.svg" alt="" />
+            <figcaption>Each model stays at or below four billion parameters for Tiny Titan eligibility.</figcaption>
+          </figure>
+        </section>
+
+        <section id="notes" aria-labelledby="notesTitle">
+          <h2 id="notesTitle" class="speakable" data-reader-type="heading">Field notes as a feature</h2>
+          <p class="speakable" data-reader-type="paragraph">
+            The build report will show parameter counts, latency notes, keyboard decisions, and where the app
+            uses deterministic fallbacks so the accessibility layer remains dependable during a live demo.
+          </p>
+          <figure class="inline-figure speakable" data-reader-type="image" data-image-id="field-notes">
+            <img src="/static/generated/field-notes.svg" alt="" />
+            <figcaption>Field notes document the choices behind the screen-reader behavior.</figcaption>
+          </figure>
+        </section>
+      </article>
+
+      <aside class="status-panel" aria-label="Tiny Narrator status">
+        <h2>Session</h2>
+        <dl>
+          <div>
+            <dt>Mode</dt>
+            <dd id="modeStatus">Reader off</dd>
+          </div>
+          <div>
+            <dt>Current</dt>
+            <dd id="currentStatus">No item selected</dd>
+          </div>
+          <div>
+            <dt>Runtime</dt>
+            <dd id="runtimeStatus">Waiting</dd>
+          </div>
+        </dl>
+        <p id="liveNarration" class="live-narration" aria-live="polite">
+          Turn on screen reader mode to begin.
+        </p>
+      </aside>
+    </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>
+      <label>
+        Speed
+        <input id="speedControl" type="range" min="0.75" max="1.35" value="1" step="0.05" />
+      </label>
+      <audio id="speechAudio"></audio>
+    </section>
+
+    <script src="/static/app.js" type="module"></script>
+  </body>
+</html>