Add fallback alt text for generated images

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

FIELD_NOTES.md

@@ -65,7 +65,7 @@ Keyboard map:
 
 Live accessibility demos need dependable behavior. If llama.cpp is not available, the app uses deterministic local narration prefixes. If Kokoro is not installed or cannot load a voice, the app returns a short silent WAV while keeping the transcript visible. If the VLM integration is unavailable, image ids map to cached alt text.
 
-The app preloads image descriptions through `/api/image-descriptions`, caches them in the frontend, and writes the descriptions back into each image's `alt` attribute. That keeps the visible article, transcript, and spoken image narration aligned.
+The HTML starts with meaningful fallback `alt` text for each generated image. The app then preloads image descriptions through `/api/image-descriptions`, caches them in the frontend, and writes the descriptions back into each image's `alt` attribute. That keeps the visible article, transcript, and spoken image narration aligned even if the model path is unavailable.
 
 The same payload carries image-generation receipts. In fallback mode, the app is explicit that bundled assets stand in for the FLUX.2 klein runtime instead of presenting static files as live model output.
 

README.md

@@ -111,7 +111,7 @@ Reader buttons expose `aria-keyshortcuts`, and the Repeat and Stop shortcuts are
 
 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.
 
-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.
+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.
 
 The session panel also renders image receipts from `/api/image-descriptions`, so judges can inspect the prompt, seed, planned <=4B image model, and fallback status behind each bundled article illustration.
 

SUBMISSION.md

@@ -58,4 +58,4 @@ The Copy Evidence button pulls `/api/evidence-bundle` and writes the formatted J
 
 ## Reliability notes
 
-The demo remains navigable when local models are unavailable. The reader brain falls back to deterministic narration, image descriptions fall back to cached alt text, speech falls back to browser speech plus transcript, and generated images fall back to bundled article assets. Fallback states are labeled instead of hidden.
+The demo remains navigable when local models are unavailable. The reader brain falls back to deterministic narration, generated images start with meaningful HTML alt text, image descriptions fall back to cached alt text, speech falls back to browser speech plus transcript, and generated images fall back to bundled article assets. Fallback states are labeled instead of hidden.

app.py

@@ -445,7 +445,7 @@ def accessibility_audit_core() -> dict[str, Any]:
             "id": "image_alt_text",
             "label": "Image descriptions",
             "status": "pass",
-            "evidence": "The app preloads article image descriptions and writes them into real img alt attributes.",
+            "evidence": "Article images start with meaningful fallback alt text, then model descriptions are written into real img alt attributes.",
         },
         {
             "id": "inspectable_transcript",

scripts/verify.py

@@ -36,6 +36,11 @@ def verify_static_assets() -> None:
     index_html = (ROOT / "static" / "index.html").read_text(encoding="utf-8")
     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('alt=""' not in index_html, "Article images should not start with empty alt text")
+    assert_true(
+        "reader brain, vision, speech, and image generation models" in index_html,
+        "Article should include meaningful fallback alt text for generated images",
+    )
     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="R"', 'aria-keyshortcuts="S"']:
         assert_true(shortcut in index_html, f"Reader controls should expose {shortcut}")

static/index.html

@@ -35,7 +35,10 @@
         </p>
 
         <figure class="hero-figure speakable" data-reader-type="image" data-image-id="desk-reader">
-          <img src="/static/generated/desk-reader.svg" alt="" />
+          <img
+            src="/static/generated/desk-reader.svg"
+            alt="Illustration of an article reader with narration controls and a highlighted reading path."
+          />
           <figcaption>
             The article view doubles as the demo surface, so every feature has a real reading task.
           </figcaption>
@@ -59,7 +62,10 @@
             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="" />
+            <img
+              src="/static/generated/model-map.svg"
+              alt="Diagram showing the reader brain, vision, speech, and image generation models working together."
+            />
             <figcaption>Each model stays at or below four billion parameters for Tiny Titan eligibility.</figcaption>
           </figure>
         </section>
@@ -71,7 +77,10 @@
             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="" />
+            <img
+              src="/static/generated/field-notes.svg"
+              alt="Notebook-style field notes about model sizes, keyboard controls, and accessibility checks."
+            />
             <figcaption>Field notes document the choices behind the screen-reader behavior.</figcaption>
           </figure>
         </section>