Add refresh-safe dashboard routes

Author: Michal Warda

docs/pipeline/ARCHITECTURE.md

@@ -79,7 +79,9 @@ rule are persisted under `adaptive_routing`.
    displays its channel layout, codec/container, sample rate, bit depth when
    available, bitrate, and lossless/lossy quality tier. The explorer plays the
    full joined result beside its original, retains each chunk join and its
-   diagnostics, and graphs the dataset-wide source-score distribution.
+   diagnostics, and graphs the dataset-wide source-score distribution. Pipeline,
+   review, dataset, job, and source selections use durable browser URLs so a
+   refresh, copied link, or back/forward navigation restores the same context.
 
 ## AWS resources
 

docs/pipeline/OPERATIONS.md

@@ -150,6 +150,22 @@ ssh ubuntu@ec2-44-211-31-38.compute-1.amazonaws.com \
 The command is idempotent; pass one or more `--job-id JOB_ID` arguments instead
 of `--all`, or use `--force` to refresh already-profiled sources.
 
+## Dashboard URLs
+
+Dashboard state is encoded in clean paths and is safe to refresh or share:
+
+```text
+/                                      pipeline and upload overview
+/review                                manual review queue
+/data/{dataset_id}                     dataset explorer
+/data/{dataset_id}/jobs/{job_id}       job within a dataset
+/data/{dataset_id}/jobs/{job_id}/sources/{source_id}
+                                       exact sound detail
+```
+
+Selecting a tab, job, dataset, or sound updates browser history. Back and
+forward navigation restore the corresponding view and selected record.
+
 ## AudioSet validation batches
 
 Acquire a reproducible random sample from the official AudioSet segment CSVs.

docs/pipeline/PROGRESS.md

@@ -36,6 +36,8 @@ was an example batch size, not a workflow limit.
   metrics, and graph the dataset-wide reconstruction score distribution.
 - [x] Persist and display each original's mono/stereo layout and encoding quality
   facts, with an idempotent historical backfill.
+- [x] Give pipeline, review, dataset, job, and source dashboard states durable
+  URLs with refresh and browser-history restoration.
 - [x] Require stereo input, gate SAM targets with source-scene presence, support
   single-stage inference, and use identity pass-through for pure SFX sources.
 - [x] Add persistent datasets, successive upload jobs, and reconciliation of

pipeline/src/sam_audio_pipeline/api.py

@@ -367,6 +367,21 @@ def health(request: Request) -> dict[str, Any]:
     def panel() -> str:
         return (Path(__file__).parent / "web" / "index.html").read_text()
 
+    @app.get("/review", response_class=HTMLResponse)
+    @app.get("/data", response_class=HTMLResponse)
+    @app.get("/data/{dataset_id}", response_class=HTMLResponse)
+    @app.get("/data/{dataset_id}/jobs/{job_id}", response_class=HTMLResponse)
+    @app.get(
+        "/data/{dataset_id}/jobs/{job_id}/sources/{source_id}",
+        response_class=HTMLResponse,
+    )
+    def panel_route(
+        dataset_id: str | None = None,
+        job_id: str | None = None,
+        source_id: str | None = None,
+    ) -> str:
+        return (Path(__file__).parent / "web" / "index.html").read_text()
+
     @app.get("/v1/overview")
     def overview(request: Request) -> dict[str, Any]:
         store = backend(request)

pipeline/src/sam_audio_pipeline/web/index.html

@@ -282,14 +282,55 @@ <h1>SAM Audio Pipeline</h1>
         return `<div class="card similarity-panel"><div class="similarity-head"><div><div class="eyebrow">Reconstruction similarity</div><strong>${formatScore(summary.mean)} mean</strong></div><span>${records.length} joined source(s) · median ${formatScore(summary.median)}<br>sample-aligned · phase + level sensitive</span></div><svg class="similarity-chart" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escapeHtml(description)}"><title>${escapeHtml(description)}</title>${ticks}<line class="axis" x1="${left}" y1="${top + plotHeight}" x2="${width - right}" y2="${top + plotHeight}"></line>${bars}<line class="mean-line" x1="${meanX}" y1="${top - 4}" x2="${meanX}" y2="${top + plotHeight}"></line><text x="${Math.min(meanX + 4, width - 70)}" y="${top - 8}">mean ${formatScore(summary.mean)}</text></svg></div>`;
       }
 
-      function show(view) {
+      function routeState(pathname = window.location.pathname) {
+        const segments = pathname.split("/").filter(Boolean).map(segment => decodeURIComponent(segment));
+        if (segments[0] === "review") return {view: "review"};
+        if (segments[0] !== "data") return {view: "dashboard"};
+        return {
+          view: "data",
+          datasetId: segments[1] || null,
+          jobId: segments[2] === "jobs" ? segments[3] || null : null,
+          sourceId: segments[4] === "sources" ? segments[5] || null : null
+        };
+      }
+
+      function dataRoutePath(datasetId, jobId = null, sourceId = null) {
+        if (!datasetId) return "/data";
+        let path = `/data/${encodeURIComponent(datasetId)}`;
+        if (jobId) path += `/jobs/${encodeURIComponent(jobId)}`;
+        if (jobId && sourceId) path += `/sources/${encodeURIComponent(sourceId)}`;
+        return path;
+      }
+
+      function setView(view) {
         activeView = view;
         for (const name of ["dashboard", "data", "review"]) {
           $(`#${name}`).hidden = view !== name;
           $(`#${name}-tab`).classList.toggle("active", view === name);
         }
-        if (view === "review") loadReview();
-        if (view === "data") loadDataset();
+      }
+
+      async function navigateTo(path) {
+        if (window.location.pathname !== path) history.pushState({}, "", path);
+        await renderRoute();
+      }
+
+      async function navigateToSource(jobId, sourceId) {
+        const datasetId = currentDataset?.dataset?.dataset_id || $("#data-dataset").value;
+        const path = dataRoutePath(datasetId, jobId, sourceId);
+        if (window.location.pathname !== path) history.pushState({}, "", path);
+        await loadSource(jobId, sourceId);
+      }
+
+      async function renderRoute() {
+        const route = routeState();
+        currentSourceId = route.sourceId || null;
+        currentJobId = route.jobId || null;
+        await loadDatasets(route.datasetId);
+        setView(route.view);
+        if (route.view === "review") return loadReview();
+        if (route.view === "data") return loadDataset(route.sourceId, route.jobId);
+        return refresh();
       }
 
       async function refresh() {
@@ -321,7 +362,10 @@ <h1>SAM Audio Pipeline</h1>
         const options = datasets.map(dataset => `<option value="${escapeHtml(dataset.dataset_id)}">${escapeHtml(dataset.name)}</option>`).join("");
         $("#dataset").innerHTML = options;
         $("#data-dataset").innerHTML = options;
-        const value = selected || $("#dataset").value || datasets[0]?.dataset_id;
+        const requested = selected || $("#dataset").value;
+        const value = datasets.some(dataset => dataset.dataset_id === requested)
+          ? requested
+          : datasets[0]?.dataset_id;
         if (value) {
           $("#dataset").value = value;
           $("#data-dataset").value = value;
@@ -377,7 +421,7 @@ <h1>SAM Audio Pipeline</h1>
         return `<div class="card"><div class="eyebrow">${escapeHtml(label)}</div><div class="metric-value">${escapeHtml(value)}</div><div class="metric-detail">${escapeHtml(detail)}</div></div>`;
       }
 
-      async function loadDataset(preferredSource) {
+      async function loadDataset(preferredSource, preferredJob) {
         const datasetId = $("#data-dataset").value || $("#dataset").value;
         if (!datasetId) return;
         $("#dataset").value = datasetId;
@@ -401,22 +445,21 @@ <h1>SAM Audio Pipeline</h1>
           const skipped = source.skip_reason === "non_stereo_input" ? " · skipped: input is not stereo" : "";
           const similarity = source.similarity_score == null ? "" : ` · ${formatScore(source.similarity_score)} joined`;
           const audioProfile = audioProfileText(source.audio_profile);
-          return `<button class="source-item ${source.source_id === currentSourceId ? "active" : ""}" data-source="${escapeHtml(source.source_id)}" onclick="loadSource('${escapeHtml(source.job_id)}', '${escapeHtml(source.source_id)}')">
+          return `<button class="source-item ${source.source_id === currentSourceId ? "active" : ""}" data-source="${escapeHtml(source.source_id)}" onclick="navigateToSource('${escapeHtml(source.job_id)}', '${escapeHtml(source.source_id)}')">
             <strong>${escapeHtml(source.filename)}</strong>
             <small>${escapeHtml(source.pipeline_status)} · ${formatDuration(source.duration_seconds)} · ${source.stem_count} stem(s)${escapeHtml(route)}${escapeHtml(skipped)}${escapeHtml(similarity)}${needsReview ? ` · ${needsReview} need review` : ""}</small>
             ${audioProfile ? `<small class="source-audio-profile">${escapeHtml(audioProfile)}</small>` : ""}
           </button>`;
         }).join("") || '<div class="empty">No uploaded sounds yet.</div>';
         const target = preferredSource || currentSourceId;
-        const source = currentDataset.sources.find(item => item.source_id === target) || currentDataset.sources[0];
+        const source = currentDataset.sources.find(item => item.source_id === target)
+          || currentDataset.sources.find(item => item.job_id === preferredJob)
+          || currentDataset.sources[0];
         if (source) await loadSource(source.job_id, source.source_id);
       }
 
       async function openJob(jobId, datasetId) {
-        await loadDatasets(datasetId);
-        show("data");
-        const source = currentDataset?.sources.find(item => item.job_id === jobId);
-        if (source) await loadSource(source.job_id, source.source_id);
+        await navigateTo(dataRoutePath(datasetId, jobId));
       }
 
       function trackRow(kind, label, subtitle, rawUrl, stereoUrl = null) {
@@ -558,22 +601,23 @@ <h2>${escapeHtml(item.assertion)}</h2>
         await loadReview();
       }
 
-      $("#dashboard-tab").onclick = () => show("dashboard");
-      $("#data-tab").onclick = () => show("data");
-      $("#review-tab").onclick = () => show("review");
+      $("#dashboard-tab").onclick = () => navigateTo("/");
+      $("#data-tab").onclick = () => navigateTo(dataRoutePath($("#data-dataset").value || $("#dataset").value));
+      $("#review-tab").onclick = () => navigateTo("/review");
       $("#submit").onclick = submitFiles;
       $("#new-dataset").onclick = newDataset;
-      $("#refresh-dataset").onclick = () => loadDataset(currentSourceId);
+      $("#refresh-dataset").onclick = () => loadDataset(currentSourceId, currentJobId);
       $("#dataset").onchange = event => { $("#data-dataset").value = event.target.value; };
-      $("#data-dataset").onchange = event => { $("#dataset").value = event.target.value; currentSourceId = null; loadDataset(); };
+      $("#data-dataset").onchange = event => navigateTo(dataRoutePath(event.target.value));
+      window.addEventListener("popstate", () => renderRoute());
       document.addEventListener("keydown", event => {
         if (activeView !== "review" || !currentReview || event.repeat) return;
         if (event.key === "1") decide("pass");
         if (event.key === "2") decide("fail");
         if (event.key === "3") decide("pending");
         if (event.key === " ") { event.preventDefault(); const audio = $("#review-audio"); audio.paused ? audio.play() : audio.pause(); }
       });
-      loadDatasets().then(refresh);
+      renderRoute();
       setInterval(() => {
         if (activeView === "dashboard") refresh();
         if (activeView === "review") loadReviewStats();

pipeline/tests/test_api.py

@@ -3,6 +3,7 @@
 from collections import defaultdict
 from typing import Any
 
+import pytest
 from fastapi.testclient import TestClient
 
 from sam_audio_pipeline.api import create_app
@@ -131,6 +132,27 @@ def settings() -> Settings:
     )
 
 
+@pytest.mark.parametrize(
+    "path",
+    [
+        "/",
+        "/review",
+        "/data",
+        "/data/dataset-1",
+        "/data/dataset-1/jobs/job-1",
+        "/data/dataset-1/jobs/job-1/sources/source-1",
+    ],
+)
+def test_dashboard_routes_support_direct_load_and_refresh(path: str) -> None:
+    config = settings()
+    with TestClient(create_app(config, FakeAWS(config))) as client:
+        response = client.get(path)
+
+    assert response.status_code == 200
+    assert "SAM Audio Pipeline" in response.text
+    assert "routeState" in response.text
+
+
 def test_persistent_dataset_accepts_successive_unbounded_jobs() -> None:
     config = settings()
     aws = FakeAWS(config)