add examples and update readme

README.md

@@ -5,8 +5,61 @@ colorFrom: indigo
 colorTo: gray
 sdk: docker
 pinned: true
-license: apache-2.0
+license: agpl-3.0
 short_description: SPICE metric evaluation and visualization
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# SPICE Evaluator
+
+Evaluate image captions using the [SPICE metric](https://panderson.me/spice/) with interactive scene graph visualization.
+
+## Local Setup
+
+### Prerequisites
+
+- **Python 3.10+**
+- **Java 11** (SPICE requires the Nashorn JS engine, removed in Java 15+)
+- **SPICE-1.0 JAR files** (~416MB)
+
+### 1. Download SPICE-1.0
+
+```bash
+pip install huggingface_hub
+python -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='Gayanukaa/spice-1.0-jar', repo_type='dataset', local_dir='SPICE-1.0')"
+```
+
+Or manually download from [huggingface.co/datasets/Gayanukaa/spice-1.0-jar](https://huggingface.co/datasets/Gayanukaa/spice-1.0-jar) and place files in a `SPICE-1.0/` directory.
+
+### 2. Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 3. Run the app
+
+```bash
+uvicorn app:app --host 0.0.0.0 --port 7860 --reload
+```
+
+Open [http://localhost:7860](http://localhost:7860) in your browser.
+
+### Docker
+
+```bash
+docker build -t spice-evaluator .
+docker run -p 7860:7860 spice-evaluator
+```
+
+## Verify Java version
+
+```bash
+java -version
+# Should show: openjdk version "11.x.x"
+```
+
+If you have multiple Java versions, set `JAVA_HOME` to your Java 11 installation.
+
+## License
+
+AGPL-3.0 (SPICE and Stanford CoreNLP are GPL v3+ / AGPL v3 compatible)

app.py

@@ -1,13 +1,16 @@
 import asyncio
 import json
 import logging
+import os
 import queue
+import ssl
+import urllib.request
 from contextlib import asynccontextmanager
 from typing import Optional
 
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import StreamingResponse
+from fastapi.responses import Response, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel
 
@@ -52,6 +55,44 @@ def health():
     return {"status": "ready" if evaluator else "loading"}
 
 
+_examples_cache = None
+
+
+@app.get("/api/examples")
+def get_examples():
+    global _examples_cache
+    if _examples_cache is None:
+        examples_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "example_input_larger.json")
+        if not os.path.exists(examples_path):
+            raise HTTPException(404, "Examples data file not found. Place example_input_larger.json next to app.py.")
+        with open(examples_path) as f:
+            _examples_cache = json.load(f)
+    return _examples_cache
+
+
+@app.get("/api/coco-image/{image_id}")
+async def coco_image(image_id: int):
+    """Proxy a COCO image through the server to work around the SSL cert mismatch
+    on images.cocodataset.org (cert is issued to s3.amazonaws.com)."""
+    padded = str(image_id).zfill(12)
+    url = f"https://images.cocodataset.org/train2017/{padded}.jpg"
+
+    def _fetch():
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+        req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
+        with urllib.request.urlopen(req, context=ctx, timeout=10) as resp:
+            return resp.read()
+
+    loop = asyncio.get_event_loop()
+    try:
+        data = await loop.run_in_executor(None, _fetch)
+    except Exception:
+        raise HTTPException(404, f"COCO image {image_id} not found")
+    return Response(content=data, media_type="image/jpeg")
+
+
 @app.post("/api/evaluate")
 async def evaluate(req: EvaluateRequest):
     if not evaluator:

static/index.html

@@ -416,7 +416,9 @@
         font-size: 0.82rem;
         font-weight: 500;
         color: var(--primary);
-        transition: background 0.2s, border-color 0.2s;
+        transition:
+          background 0.2s,
+          border-color 0.2s;
       }
 
       .about-links a:hover {
@@ -439,6 +441,181 @@
         display: block;
       }
 
+      /* ── Gallery ─────────────────────────────────────────── */
+      .gallery-card {
+        display: flex;
+        min-height: 280px;
+      }
+
+      .gallery-img-wrap {
+        flex: 0 0 220px;
+        background: var(--bg);
+        border-right: 1px solid var(--border);
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        overflow: hidden;
+      }
+
+      .gallery-img-wrap img {
+        width: 100%;
+        height: 240px;
+        object-fit: cover;
+        display: block;
+      }
+
+      .gallery-img-id {
+        font-size: 0.7rem;
+        color: var(--text-dim);
+        padding: 4px 8px;
+        align-self: flex-start;
+      }
+
+      .gallery-img-placeholder {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        height: 240px;
+        width: 100%;
+        color: var(--text-dim);
+        font-size: 0.8rem;
+        gap: 6px;
+      }
+
+      .gallery-captions {
+        flex: 1;
+        padding: 14px 16px;
+        display: flex;
+        flex-direction: column;
+        gap: 8px;
+        overflow: hidden;
+        min-width: 0;
+      }
+
+      .gallery-section-label {
+        font-size: 0.7rem;
+        font-weight: 700;
+        text-transform: uppercase;
+        letter-spacing: 0.5px;
+        color: var(--text-dim);
+        margin-bottom: 3px;
+      }
+
+      .gallery-candidate-text {
+        font-size: 0.88rem;
+        color: var(--text);
+        font-style: italic;
+        line-height: 1.45;
+        background: var(--bg);
+        border-radius: 6px;
+        padding: 7px 10px;
+        border-left: 3px solid var(--accent);
+      }
+
+      .gallery-refs-list {
+        list-style: none;
+        font-size: 0.78rem;
+        color: var(--text-dim);
+        line-height: 1.7;
+        max-height: 160px;
+        overflow-y: auto;
+        padding: 0;
+      }
+
+      .gallery-refs-list li::before {
+        content: "·  ";
+        color: var(--primary-light);
+        font-weight: 700;
+      }
+
+      .gallery-nav {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        padding: 10px 14px;
+        border-top: 1px solid var(--border);
+        background: var(--bg);
+        border-radius: 0 0 var(--radius) var(--radius);
+        flex-wrap: wrap;
+      }
+
+      .gallery-btn {
+        padding: 5px 13px;
+        border: 1px solid var(--border);
+        border-radius: 6px;
+        background: var(--card-bg);
+        color: var(--text);
+        font-size: 0.82rem;
+        font-weight: 500;
+        cursor: pointer;
+        transition:
+          background 0.15s,
+          border-color 0.15s;
+        white-space: nowrap;
+      }
+
+      .gallery-btn:hover {
+        background: #edf2f8;
+        border-color: var(--primary-light);
+      }
+
+      .gallery-btn-load {
+        margin-left: auto;
+        background: var(--primary);
+        color: #fff;
+        border-color: var(--primary);
+        font-weight: 600;
+      }
+
+      .gallery-btn-load:hover {
+        background: var(--primary-light);
+        border-color: var(--primary-light);
+      }
+
+      .gallery-counter {
+        font-size: 0.82rem;
+        color: var(--text-dim);
+        white-space: nowrap;
+        min-width: 70px;
+        text-align: center;
+      }
+
+      .gallery-jump input {
+        width: 54px;
+        padding: 4px 7px;
+        border: 1px solid var(--border);
+        border-radius: 6px;
+        font-size: 0.82rem;
+        color: var(--text);
+        background: var(--card-bg);
+        text-align: center;
+      }
+
+      .gallery-jump input:focus {
+        outline: none;
+        border-color: var(--primary-light);
+        box-shadow: 0 0 0 2px rgba(74, 111, 165, 0.1);
+      }
+
+      @media (max-width: 600px) {
+        .gallery-card {
+          flex-direction: column;
+        }
+        .gallery-img-wrap {
+          flex: none;
+          border-right: none;
+          border-bottom: 1px solid var(--border);
+        }
+        .gallery-img-wrap img {
+          height: 200px;
+        }
+        .gallery-btn-load {
+          margin-left: 0;
+        }
+      }
+
       footer {
         text-align: center;
         padding: 16px;
@@ -463,6 +640,101 @@
     </header>
 
     <div class="container">
+      <!-- MS-COCO Examples Gallery -->
+      <div class="collapsible" id="gallerySection">
+        <div
+          class="collapsible-header"
+          onclick="toggleCollapsible('gallerySection')"
+        >
+          Browse MS-COCO Examples
+          <span
+            style="
+              font-weight: 400;
+              color: var(--text-dim);
+              font-size: 0.8rem;
+              margin-left: 6px;
+            "
+            id="galleryHeaderCount"
+          ></span>
+          <span class="arrow">&#9654;</span>
+        </div>
+        <div class="collapsible-body" style="padding: 0">
+          <div
+            id="galleryLoading"
+            style="padding: 16px; color: var(--text-dim); font-size: 0.85rem"
+          >
+            Loading examples…
+          </div>
+          <div id="galleryContent" style="display: none">
+            <div class="gallery-card">
+              <div class="gallery-img-wrap">
+                <div id="galleryImgPlaceholder" class="gallery-img-placeholder">
+                  <span style="font-size: 1.8rem">🖼</span>
+                  <span>Loading image…</span>
+                </div>
+                <img id="galleryImg" src="" alt="" style="display: none" />
+                <div class="gallery-img-id">
+                  COCO ID: <span id="galleryImgId">—</span>
+                </div>
+              </div>
+              <div class="gallery-captions">
+                <div>
+                  <div class="gallery-section-label">Candidate Caption</div>
+                  <div id="galleryCandText" class="gallery-candidate-text">
+                    —
+                  </div>
+                </div>
+                <div style="flex: 1; min-height: 0">
+                  <div class="gallery-section-label">Reference Captions</div>
+                  <ul id="galleryRefsList" class="gallery-refs-list"></ul>
+                </div>
+              </div>
+            </div>
+            <div class="gallery-nav">
+              <button
+                class="gallery-btn"
+                onclick="galleryNav(-1)"
+                title="Previous (←)"
+              >
+                ◀ Prev
+              </button>
+              <button
+                class="gallery-btn"
+                onclick="galleryRandom()"
+                title="Random example"
+              >
+                ⚄ Random
+              </button>
+              <div class="gallery-counter">
+                <span id="galleryCurr">—</span> / <span id="galleryTot">—</span>
+              </div>
+              <div class="gallery-jump">
+                <input
+                  type="number"
+                  id="galleryJumpInput"
+                  min="1"
+                  placeholder="#"
+                  title="Jump to example number"
+                />
+              </div>
+              <button
+                class="gallery-btn"
+                onclick="galleryNav(1)"
+                title="Next (→)"
+              >
+                Next ▶
+              </button>
+              <button
+                class="gallery-btn gallery-btn-load"
+                onclick="galleryLoad()"
+              >
+                Use this Example →
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+
       <!-- Input Section -->
       <div class="input-section">
         <h2>Caption Inputs</h2>
@@ -483,11 +755,13 @@
           </div>
           <div class="input-group">
             <label for="references">Reference Captions (one per line)</label>
-            <textarea id="references">a couple of giraffes that are walking around
+            <textarea id="references">
+a couple of giraffes that are walking around
 a herd of giraffe standing on top of a dirt field.
 Several smaller giraffes that are in an enclosure.
 The giraffes are walking in different directions outside.
-A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea>
+A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea
+            >
           </div>
         </div>
         <button class="btn-evaluate" id="evalBtn" onclick="runEvaluation()">
@@ -500,8 +774,11 @@ A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea>
       <div class="error-banner" id="errorBanner"></div>
 
       <!-- Logs (above results, shown during evaluation) -->
-      <div class="collapsible" id="logsSection" style="display: none;">
-        <div class="collapsible-header" onclick="toggleCollapsible('logsSection')">
+      <div class="collapsible" id="logsSection" style="display: none">
+        <div
+          class="collapsible-header"
+          onclick="toggleCollapsible('logsSection')"
+        >
           Evaluation Logs
           <span class="arrow">&#9654;</span>
         </div>
@@ -541,14 +818,35 @@ A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea>
 
         <!-- Tuples -->
         <div class="collapsible" id="tuplesSection">
-          <div class="collapsible-header" onclick="toggleCollapsible('tuplesSection')">
+          <div
+            class="collapsible-header"
+            onclick="toggleCollapsible('tuplesSection')"
+          >
             Extracted Tuples
             <span class="arrow">&#9654;</span>
           </div>
           <div class="collapsible-body">
-            <label style="font-size: 0.82rem; font-weight: 600; color: var(--text-dim); display: block; margin-bottom: 6px;">Candidate Tuples</label>
+            <label
+              style="
+                font-size: 0.82rem;
+                font-weight: 600;
+                color: var(--text-dim);
+                display: block;
+                margin-bottom: 6px;
+              "
+              >Candidate Tuples</label
+            >
             <div class="tuple-list" id="candidateTuples"></div>
-            <label style="font-size: 0.82rem; font-weight: 600; color: var(--text-dim); display: block; margin: 12px 0 6px;">Reference Tuples</label>
+            <label
+              style="
+                font-size: 0.82rem;
+                font-weight: 600;
+                color: var(--text-dim);
+                display: block;
+                margin: 12px 0 6px;
+              "
+              >Reference Tuples</label
+            >
             <div class="tuple-list" id="referenceTuples"></div>
           </div>
         </div>
@@ -556,31 +854,53 @@ A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea>
 
       <!-- About (always visible, collapsed) -->
       <div class="collapsible open" id="aboutSection">
-        <div class="collapsible-header" onclick="toggleCollapsible('aboutSection')">
+        <div
+          class="collapsible-header"
+          onclick="toggleCollapsible('aboutSection')"
+        >
           About This Project
           <span class="arrow">&#9654;</span>
         </div>
         <div class="collapsible-body about-body">
           <p>
-            <strong>SPICE Evaluator</strong> is an interactive tool for evaluating image captions using the
-            <a href="https://panderson.me/spice/" target="_blank">SPICE</a> (Semantic Propositional Image Caption Evaluation) metric.
-            It computes precision, recall, and F1 scores by comparing semantic scene graphs extracted from candidate and reference captions.
+            <strong>SPICE Evaluator</strong> is an interactive tool for
+            evaluating image captions using the
+            <a href="https://panderson.me/spice/" target="_blank">SPICE</a>
+            (Semantic Propositional Image Caption Evaluation) metric. It
+            computes precision, recall, and F1 scores by comparing semantic
+            scene graphs extracted from candidate and reference captions.
           </p>
           <p>
-            The evaluation pipeline invokes the official SPICE-1.0 Java implementation, which uses Stanford CoreNLP for dependency parsing
-            and scene graph extraction. Extracted tuples are matched using WordNet-based synonym matching.
+            The evaluation pipeline invokes the official SPICE-1.0 Java
+            implementation, which uses Stanford CoreNLP for dependency parsing
+            and scene graph extraction. Extracted tuples are matched using
+            WordNet-based synonym matching.
           </p>
           <div class="about-links">
-            <a href="https://gayanukaa.com/projects/spice-evaluator" target="_blank">Project Page</a>
-            <a href="https://gayanukaa.com/blog/2025-05-29-understanding-spice-metric" target="_blank">Understanding SPICE - Blog Post</a>
-            <a href="https://github.com/Gayanukaa/SPICE-Evaluator" target="_blank">Source Code</a>
+            <a
+              href="https://gayanukaa.com/projects/spice-evaluator"
+              target="_blank"
+              >Project Page</a
+            >
+            <a
+              href="https://gayanukaa.com/blog/2025-05-29-understanding-spice-metric"
+              target="_blank"
+              >Understanding SPICE - Blog Post</a
+            >
+            <a
+              href="https://github.com/Gayanukaa/SPICE-Evaluator"
+              target="_blank"
+              >Source Code</a
+            >
           </div>
         </div>
       </div>
 
       <footer>
-        Developed by <a href="https://gayanukaa.com" target="_blank">Gayanukaa</a>
-        &middot; Powered by <a href="https://panderson.me/spice/" target="_blank">SPICE</a>
+        Developed by
+        <a href="https://gayanukaa.com" target="_blank">Gayanukaa</a> &middot;
+        Powered by
+        <a href="https://panderson.me/spice/" target="_blank">SPICE</a>
       </footer>
     </div>
 
@@ -724,13 +1044,83 @@ A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea>
         document.getElementById(id).classList.toggle("open");
       }
 
+      /* ── Graph auto-reset management ───────────────────── */
+      const graphResetTimers = {};
+      const graphInstances = {};
+      const graphInitialStates = {};
+
+      function setupAutoReset(network, containerId) {
+        let resetTimer = null;
+
+        const resetToInitial = () => {
+          if (graphInitialStates[containerId]) {
+            const { positions, scale, viewPosition } =
+              graphInitialStates[containerId];
+
+            // Restore node positions
+            network.body.data.nodes.update(
+              Object.keys(positions).map((nodeId) => ({
+                id: parseInt(nodeId),
+                x: positions[nodeId].x,
+                y: positions[nodeId].y,
+              })),
+            );
+
+            // Restore view with animation
+            network.moveTo({
+              position: viewPosition,
+              scale: scale,
+              animation: {
+                duration: 800,
+                easingFunction: "easeInOutQuad",
+              },
+            });
+          }
+        };
+
+        const scheduleReset = () => {
+          clearTimeout(resetTimer);
+          resetTimer = setTimeout(resetToInitial, 3000);
+        };
+
+        // Capture initial state once physics stabilizes
+        network.once("stabilized", () => {
+          const positions = network.getPositions();
+          const viewPosition = network.getViewPosition();
+          const scale = network.getScale();
+
+          graphInitialStates[containerId] = {
+            positions,
+            viewPosition,
+            scale,
+          };
+        });
+
+        // Listen for user interactions
+        network.on("zoom", scheduleReset);
+        network.on("dragStart", scheduleReset);
+        network.on("dragging", () => {
+          clearTimeout(resetTimer);
+        });
+        network.on("dragEnd", scheduleReset);
+
+        graphResetTimers[containerId] = resetTimer;
+      }
+
       /* ── Graph rendering ───────────────────────────────── */
       function renderGraph(containerId, tuples, nodeColor, edgeColor) {
         const container = document.getElementById(containerId);
         container.innerHTML = "";
 
+        // Clear any existing timer
+        if (graphResetTimers[containerId]) {
+          clearTimeout(graphResetTimers[containerId]);
+          delete graphResetTimers[containerId];
+        }
+
         if (!tuples || tuples.length === 0) {
-          container.innerHTML = '<div class="graph-empty">No tuples to visualize</div>';
+          container.innerHTML =
+            '<div class="graph-empty">No tuples to visualize</div>';
           return;
         }
 
@@ -752,7 +1142,12 @@ A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea>
             for (let i = 0; i < tpl.length - 1; i++) {
               const fromId = getNodeId(tpl[i]);
               const toId = getNodeId(tpl[i + 1]);
-              edgesArr.push({ from: fromId, to: toId, color: { color: edgeColor }, arrows: "to" });
+              edgesArr.push({
+                from: fromId,
+                to: toId,
+                color: { color: edgeColor },
+                arrows: "to",
+              });
             }
           }
         });
@@ -765,12 +1160,12 @@ A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea>
             font: { size: 13, color: "#2c3e50" },
             size: 18,
             borderWidth: 2,
-          }))
+          })),
         );
 
         const edges = new vis.DataSet(edgesArr);
 
-        new vis.Network(
+        const network = new vis.Network(
           container,
           { nodes, edges },
           {
@@ -793,8 +1188,12 @@ A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea>
               zoomView: true,
               dragView: true,
             },
-          }
+          },
         );
+
+        // Store network instance and setup auto-reset
+        graphInstances[containerId] = network;
+        setupAutoReset(network, containerId);
       }
 
       /* ── Format tuples for display ─────────────────────── */
@@ -872,7 +1271,8 @@ A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea>
               } else if (line.startsWith("data: ")) {
                 const data = line.slice(6);
                 if (eventType === "log") {
-                  logOutput.textContent += (logOutput.textContent ? "\n" : "") + data;
+                  logOutput.textContent +=
+                    (logOutput.textContent ? "\n" : "") + data;
                   logOutput.scrollTop = logOutput.scrollHeight;
                 } else if (eventType === "result") {
                   resultData = JSON.parse(data);
@@ -892,15 +1292,32 @@ A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea>
           logsSection.classList.remove("open");
           document.getElementById("aboutSection").classList.remove("open");
 
-          document.getElementById("metricF1").textContent = resultData.spice_f1.toFixed(3);
-          document.getElementById("metricPrec").textContent = resultData.spice_precision.toFixed(3);
-          document.getElementById("metricRec").textContent = resultData.spice_recall.toFixed(3);
-
-          renderGraph("candidateGraph", resultData.test_tuples, "#a8d5f2", "#4a6fa5");
-          renderGraph("referenceGraph", resultData.ref_tuples, "#a8f0c6", "#27ae60");
-
-          document.getElementById("candidateTuples").textContent = formatTuples(resultData.test_tuples);
-          document.getElementById("referenceTuples").textContent = formatTuples(resultData.ref_tuples);
+          document.getElementById("metricF1").textContent =
+            resultData.spice_f1.toFixed(3);
+          document.getElementById("metricPrec").textContent =
+            resultData.spice_precision.toFixed(3);
+          document.getElementById("metricRec").textContent =
+            resultData.spice_recall.toFixed(3);
+
+          renderGraph(
+            "candidateGraph",
+            resultData.test_tuples,
+            "#a8d5f2",
+            "#4a6fa5",
+          );
+          renderGraph(
+            "referenceGraph",
+            resultData.ref_tuples,
+            "#a8f0c6",
+            "#27ae60",
+          );
+
+          document.getElementById("candidateTuples").textContent = formatTuples(
+            resultData.test_tuples,
+          );
+          document.getElementById("referenceTuples").textContent = formatTuples(
+            resultData.ref_tuples,
+          );
 
           resultsSection.classList.add("visible");
         } catch (e) {
@@ -916,6 +1333,121 @@ A giraffe standing next to three baby giraffes in a zoo exhibit.</textarea>
         banner.textContent = msg;
         banner.classList.add("visible");
       }
+
+      /* ── MS-COCO Examples Gallery ───────────────────────── */
+      let galleryExamples = [];
+      let galleryIdx = 0;
+
+      function cocoImageUrl(imageId) {
+        // Proxy through the backend: images.cocodataset.org cert is for s3.amazonaws.com
+        // and the images live under train2017/, not val2017/
+        return `/api/coco-image/${imageId}`;
+      }
+
+      async function loadGallery() {
+        try {
+          const res = await fetch("/api/examples");
+          if (!res.ok) throw new Error("HTTP " + res.status);
+          galleryExamples = await res.json();
+
+          document.getElementById("galleryLoading").style.display = "none";
+          document.getElementById("galleryContent").style.display = "block";
+          document.getElementById("galleryTot").textContent =
+            galleryExamples.length;
+          document.getElementById("galleryHeaderCount").textContent = "";
+
+          const jumpInput = document.getElementById("galleryJumpInput");
+          jumpInput.max = galleryExamples.length;
+          jumpInput.addEventListener("keydown", (e) => {
+            if (e.key === "Enter") {
+              const n = parseInt(jumpInput.value, 10);
+              if (n >= 1 && n <= galleryExamples.length) galleryShow(n - 1);
+            }
+          });
+          jumpInput.addEventListener("change", () => {
+            const n = parseInt(jumpInput.value, 10);
+            if (n >= 1 && n <= galleryExamples.length) galleryShow(n - 1);
+          });
+
+          // Start at a random example for variety
+          galleryShow(Math.floor(Math.random() * galleryExamples.length));
+        } catch (e) {
+          document.getElementById("galleryLoading").textContent =
+            "Could not load examples (" + e.message + ").";
+        }
+      }
+
+      function galleryShow(idx) {
+        if (!galleryExamples.length) return;
+        idx =
+          ((idx % galleryExamples.length) + galleryExamples.length) %
+          galleryExamples.length;
+        galleryIdx = idx;
+
+        const ex = galleryExamples[idx];
+        document.getElementById("galleryCurr").textContent = idx + 1;
+        document.getElementById("galleryImgId").textContent = ex.image_id;
+        document.getElementById("galleryCandText").textContent = ex.test;
+        document.getElementById("galleryJumpInput").value = idx + 1;
+
+        const refsList = document.getElementById("galleryRefsList");
+        refsList.innerHTML = ex.refs.map((r) => `<li>${r}</li>`).join("");
+
+        // Image with placeholder while loading
+        const img = document.getElementById("galleryImg");
+        const placeholder = document.getElementById("galleryImgPlaceholder");
+        img.style.display = "none";
+        placeholder.style.display = "flex";
+        placeholder.innerHTML =
+          '<span style="font-size:1.8rem;">⏳</span><span>Loading…</span>';
+
+        const url = cocoImageUrl(ex.image_id);
+        const probe = new Image();
+        probe.onload = () => {
+          img.src = url;
+          img.style.display = "block";
+          placeholder.style.display = "none";
+        };
+        probe.onerror = () => {
+          placeholder.innerHTML =
+            '<span style="font-size:1.5rem;">🚫</span><span>Image unavailable</span>';
+        };
+        probe.src = url;
+      }
+
+      function galleryNav(dir) {
+        galleryShow(galleryIdx + dir);
+      }
+
+      function galleryRandom() {
+        galleryShow(Math.floor(Math.random() * galleryExamples.length));
+      }
+
+      function galleryLoad() {
+        if (!galleryExamples.length) return;
+        const ex = galleryExamples[galleryIdx];
+        document.getElementById("candidate").value = ex.test;
+        document.getElementById("references").value = ex.refs.join("\n");
+        document
+          .querySelector(".input-section")
+          .scrollIntoView({ behavior: "smooth" });
+      }
+
+      // Keyboard arrow navigation (when not typing in an input)
+      document.addEventListener("keydown", (e) => {
+        const tag = document.activeElement.tagName;
+        if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return;
+        if (e.key === "ArrowLeft") {
+          e.preventDefault();
+          galleryNav(-1);
+        }
+        if (e.key === "ArrowRight") {
+          e.preventDefault();
+          galleryNav(1);
+        }
+      });
+
+      loadGallery();
     </script>
   </body>
 </html>