benchflow 0.7.6.dev2072__tar.gz → 0.7.6.dev2102__tar.gz

{benchflow-0.7.6.dev2072 → benchflow-0.7.6.dev2102}/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 ## [Unreleased]
 
+### Added
+- **ACP rollout directories render as an interactive reviewer page.**
+  `bench eval view <rollout>` now assembles a JSON payload (normalized
+  events + result/timing/verifier metadata) and renders it client-side in a
+  self-contained template (no build step, zero network requests): full
+  event stream with collapse instead of truncation, harness/model/skills
+  identity row, reward badge and `result.json` failure-diagnostic banners,
+  Verifier and Metrics tabs, Focus/Full modes, per-kind filters and hues,
+  text search, and per-event `#e42` anchors. Trajectory content is treated
+  as untrusted end to end (data-only embedding, `textContent` rendering).
+  Raw session JSONL files and legacy `turn*.txt` runs remain supported, and
+  the `--confirm` approve/reject contract remains compatible.
+- **Directories of rollouts serve a run catalog.** Pointing
+  `bench eval view` at a job directory (or a whole `jobs/` tree) serves a
+  browsable index: corpus counts, grouping by task or model + harness with
+  per-group pass/fail aggregates and pass rates, sorting by
+  name/reward/duration/cost, text filtering, collapsible groups with
+  incremental pagination, and URL-preserved state — selecting a run opens
+  the detail page and the back control restores the exact catalog view.
+  Traces load dynamically from `/api/rollout?id=…` (ids resolve only by
+  exact membership in a fresh directory scan, so crafted ids cannot reach
+  the filesystem) and `?run=<id>` deep-links a run. `--confirm` on a
+  multi-run directory errors out: a confirmation needs exactly one
+  trajectory.
+- **`hf://` sources browse HuggingFace trajectory datasets directly.**
+  `bench eval view hf://<org>/<dataset>[@revision][/subpath]` fetches the
+  viewer-relevant slice of a trajectory dataset into the shared
+  `huggingface_hub` cache and serves it through browse mode, making the
+  community ground-truth uploads reviewable with one command. The download
+  allowlist is exact — trajectories, result/timing/prompts, and the four
+  verifier sidecars the viewer renders — with no wildcards, so large run
+  artifacts and `llm_trajectory`/`trainer` exports are never fetched. The
+  CLI passes the spec as a string into a typed
+  `LocalPathSource | HfDatasetSource` parser (never through `pathlib.Path`,
+  whose normalization would mangle `hf://` into `hf:/`), and dataset
+  subpaths are validated.
+- **The viewer renders per-event timelines the moment captures provide
+  timestamps.** Steps gain a `+m:ss` offset chip and tool calls a duration
+  chip whenever events carry `ts` / `started_at` / `finished_at` fields;
+  with today's captures (which carry none) nothing changes visually.
+
 ## 0.7.5 — 2026-08-19
 
 ### Added

{benchflow-0.7.6.dev2072 → benchflow-0.7.6.dev2102}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: benchflow
-Version: 0.7.6.dev2072
+Version: 0.7.6.dev2102
 Summary: Multi-turn agent benchmarking with ACP — run any agent, any model, any provider.
 Project-URL: Homepage, https://github.com/benchflow-ai/benchflow
 Project-URL: Repository, https://github.com/benchflow-ai/benchflow
@@ -45,6 +45,7 @@ Requires-Dist: deepagents>=0.6; extra == 'deepagents'
 Requires-Dist: langchain-openai>=0.2; extra == 'deepagents'
 Provides-Extra: dev
 Requires-Dist: pathspec>=0.12; extra == 'dev'
+Requires-Dist: playwright>=1.49; extra == 'dev'
 Requires-Dist: pre-commit>=3.7; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'

{benchflow-0.7.6.dev2072 → benchflow-0.7.6.dev2102}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "benchflow"
-version = "0.7.6.dev2072"
+version = "0.7.6.dev2102"
 description = "Multi-turn agent benchmarking with ACP — run any agent, any model, any provider."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -61,6 +61,11 @@ dev = [
     "pathspec>=0.12",
     "pytest>=9.0.3",
     "pytest-asyncio>=0.24.0",
+    # Browser-level viewer tests (tests/trajectories/test_viewer_browser.py):
+    # drives the interactive template in real Chromium. Tests self-skip when
+    # playwright or its browser binary is absent, so plain `pytest tests/`
+    # stays runnable without `playwright install chromium`.
+    "playwright>=1.49",
     "ruff>=0.7.0",
     "ty>=0.0.1a1",
 ]
@@ -154,6 +159,7 @@ testpaths = ["tests"]
 markers = [
     "live: requires real Anthropic API and Docker daemon (run with -m live)",
     "integration: full integration tests — requires GEMINI_API_KEY + DAYTONA_API_KEY (run with -m integration)",
+    "browser: drives the viewer template in real Chromium via Playwright (self-skips without playwright/chromium; deselect with -m 'not browser')",
 ]
 
 [tool.ruff]

{benchflow-0.7.6.dev2072 → benchflow-0.7.6.dev2102}/src/benchflow/cli/eval_artifacts.py

@@ -66,7 +66,9 @@ def postprocess_eval_artifacts(
     eval_config = _apply_source_sidecar(eval_config, resolved_tasks_dir)
     from benchflow.eval_artifacts import (
         TaskManifestOptions,
+        canonical_task_rows,
         materialize_canonical_job,
+        render_run_summary_markdown,
         write_canonical_selection,
         write_health_summary,
         write_task_manifest,
@@ -138,6 +140,12 @@ def postprocess_eval_artifacts(
             console.print(
                 f"[green]Canonical jobs:[/green] {escape(str(req.canonical_jobs_dir))}"
             )
+    if req.publish_hf is not None or req.publish_bucket is not None:
+        (job_dir / "README.md").write_text(
+            render_run_summary_markdown(
+                job_dir, agent=eval_config.agent, model=eval_config.model
+            )
+        )
     if req.publish_hf is not None:
         from benchflow.publish.huggingface import publish_folder_to_hf
 
@@ -154,6 +162,42 @@ def postprocess_eval_artifacts(
             print_error(str(exc))
             raise typer.Exit(1) from None
         console.print(f"[green]Published HF artifacts:[/green] {escape(published.url)}")
+    if req.publish_bucket is not None:
+        from benchflow.publish.huggingface import publish_folder_to_bucket
+
+        prefix = req.hf_prefix or job_dir.name
+        try:
+            published = publish_folder_to_bucket(
+                job_dir, bucket_id=req.publish_bucket, path_in_repo=prefix
+            )
+        except ValueError as exc:
+            print_error(str(exc))
+            raise typer.Exit(1) from None
+        console.print(f"[green]Published HF bucket:[/green] {escape(published.url)}")
+    if req.eval_results_model is not None:
+        from benchflow.publish.huggingface import open_eval_results_pr
+
+        rewards = [
+            row["reward"] for row in canonical_task_rows(job_dir) if row["scored"]
+        ]
+        if rewards:
+            value = round(100.0 * sum(rewards) / len(rewards), 2)
+            try:
+                pr_url = open_eval_results_pr(
+                    model_repo=req.eval_results_model,
+                    dataset_id=cast(str, req.eval_results_dataset),
+                    task_id=cast(str, req.eval_results_task),
+                    value=value,
+                )
+            except ValueError as exc:
+                print_error(str(exc))
+                raise typer.Exit(1) from None
+            console.print(f"[green]Eval-results PR:[/green] {escape(pr_url or '')}")
+        else:
+            console.print(
+                "[yellow]--eval-results-model set but no scored rollouts were "
+                "found; skipping eval-results PR[/yellow]"
+            )
 
 
 def _load_eval_matrix(path: Path) -> dict[str, dict]:

{benchflow-0.7.6.dev2072 → benchflow-0.7.6.dev2102}/src/benchflow/cli/main.py

@@ -581,6 +581,31 @@ def eval_run(
             "--hf-public-read-check", help="Verify public HF reads after upload"
         ),
     ] = False,
+    publish_bucket: Annotated[
+        str | None,
+        typer.Option(
+            "--publish-bucket", help="Upload final eval artifacts to a HF bucket"
+        ),
+    ] = None,
+    eval_results_model: Annotated[
+        str | None,
+        typer.Option(
+            "--eval-results-model",
+            help="HF model repo to open a community eval-results PR on",
+        ),
+    ] = None,
+    eval_results_dataset: Annotated[
+        str | None,
+        typer.Option(
+            "--eval-results-dataset", help="HF benchmark dataset id, e.g. org/benchmark"
+        ),
+    ] = None,
+    eval_results_task: Annotated[
+        str | None,
+        typer.Option(
+            "--eval-results-task", help="Benchmark task_id from the dataset's eval.yaml"
+        ),
+    ] = None,
     matrix: Annotated[
         Path | None,
         typer.Option("--matrix", help="YAML model matrix for repeated evals"),
@@ -653,6 +678,10 @@ def eval_run(
         publish_hf=publish_hf,
         hf_prefix=hf_prefix,
         hf_public_read_check=hf_public_read_check,
+        publish_bucket=publish_bucket,
+        eval_results_model=eval_results_model,
+        eval_results_dataset=eval_results_dataset,
+        eval_results_task=eval_results_task,
         matrix=matrix,
         trials=trials,
     )
@@ -1222,9 +1251,15 @@ def eval_metrics(
 @eval_app.command("view")
 def eval_view(
     rollout_dir: Annotated[
-        Path,
+        # A str, not a Path: hf:// specs must arrive verbatim — Path
+        # normalization would collapse the double slash into hf:/.
+        str,
         typer.Argument(
-            help="Rollout directory, job directory, or trajectory JSONL file"
+            help=(
+                "Rollout directory, job directory, trajectory JSONL file, or "
+                "an hf://<org>/<dataset> trajectory dataset "
+                "(optionally with /subpath)"
+            )
         ),
     ],
     port: Annotated[int, typer.Option(help="Server port")] = 8888,
@@ -1256,7 +1291,7 @@ def eval_view(
     from benchflow.trajectories import viewer
 
     decision = viewer.serve(
-        str(rollout_dir), port, confirm=confirm, redaction_summary=redaction_summary
+        rollout_dir, port, confirm=confirm, redaction_summary=redaction_summary
     )
     # Exit-code contract for --confirm: 0 approved, 3 rejected. 3 is chosen
     # so a rejection never collides with the CLI's existing error exits

{benchflow-0.7.6.dev2072 → benchflow-0.7.6.dev2102}/src/benchflow/eval_artifacts.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from typing import Any, Literal
 
 from benchflow._utils.task_authoring import task_digest
+from benchflow._utils.text import truncate_end
 from benchflow.task.discovery import is_task_dir, resolve_task_collection_root
 from benchflow.trajectories.export_prime_sft import (
     PrimeSftTrajectoryJsonlError,
@@ -268,6 +269,62 @@ def write_health_summary(path: Path, job_dir: Path) -> dict[str, Any]:
     return summary
 
 
+def _escape_md_cell(text: str) -> str:
+    return text.replace("|", "\\|").replace("\n", " ").strip()
+
+
+_ISSUE_CELL_LIMIT = 120
+
+
+def canonical_task_rows(job_dir: Path) -> list[dict[str, Any]]:
+    """One row per task_id — the best-scored/highest-reward rollout.
+
+    Reused by the README summary and ``--eval-results-model`` so retry
+    attempts (multiple rollout dirs for the same task) are never counted
+    or averaged as if they were distinct tasks.
+    """
+    return build_canonical_selection(job_dir, policy="one-healthy-per-task")["selected"]
+
+
+def render_run_summary_markdown(
+    job_dir: Path, *, agent: str | None = None, model: str | None = None
+) -> str:
+    """Render a Markdown run summary (results + issues) for publish folders."""
+    rows = canonical_task_rows(job_dir)
+    rewards = [row["reward"] for row in rows if row["scored"]]
+    mean_reward = sum(rewards) / len(rewards) if rewards else None
+    scored_count = sum(1 for row in rows if row["scored"])
+    tool_call_count = sum(1 for row in rows if row["tool_calls"] > 0)
+
+    lines = ["# BenchFlow run summary", ""]
+    if agent:
+        lines.append(f"- Agent: `{agent}`")
+    if model:
+        lines.append(f"- Model: `{model}`")
+    lines += [
+        f"- Tasks: {len(rows)}",
+        f"- Scored: {scored_count} / Unscored: {len(rows) - scored_count}",
+        f"- Mean reward: {mean_reward:.3f}"
+        if mean_reward is not None
+        else "- Mean reward: n/a",
+        f"- Tasks with tool calls: {tool_call_count}",
+        "",
+        "## Tasks",
+        "",
+        "| Task | Reward | Tool calls | Issue |",
+        "| --- | --- | --- | --- |",
+    ]
+    for row in rows:
+        reward = f"{row['reward']:.3f}" if isinstance(row["reward"], float) else "—"
+        issue = row.get("error") or row.get("verifier_error") or ""
+        issue = truncate_end(_escape_md_cell(str(issue)), _ISSUE_CELL_LIMIT)
+        lines.append(
+            f"| {_escape_md_cell(str(row['task_id']))} | {reward} | "
+            f"{row['tool_calls']} | {issue} |"
+        )
+    return "\n".join(lines) + "\n"
+
+
 def _canonical_score(row: dict[str, Any]) -> tuple[int, float, int]:
     scored = 1 if row["scored"] else 0
     reward = row["reward"] if isinstance(row["reward"], float) else float("-inf")

{benchflow-0.7.6.dev2072 → benchflow-0.7.6.dev2102}/src/benchflow/eval_plan.py

@@ -126,6 +126,10 @@ class EvalCreateRequest:
     publish_hf: str | None = None
     hf_prefix: str | None = None
     hf_public_read_check: bool = False
+    publish_bucket: str | None = None
+    eval_results_model: str | None = None
+    eval_results_dataset: str | None = None
+    eval_results_task: str | None = None
     matrix: Path | None = None
     trials: int = 1
 
@@ -274,8 +278,14 @@ def build_eval_plan(request: EvalCreateRequest) -> EvalPlan:
         raise EvalPlanError("--retry-attempts must be >= 0")
     if request.retry_concurrency is not None and request.retry_concurrency < 1:
         raise EvalPlanError("--retry-concurrency must be >= 1")
-    if request.hf_prefix and not request.publish_hf:
-        raise EvalPlanError("--hf-prefix requires --publish-hf")
+    if request.hf_prefix and not (request.publish_hf or request.publish_bucket):
+        raise EvalPlanError("--hf-prefix requires --publish-hf or --publish-bucket")
+    if request.eval_results_model and not (
+        request.eval_results_dataset and request.eval_results_task
+    ):
+        raise EvalPlanError(
+            "--eval-results-model requires --eval-results-dataset and --eval-results-task"
+        )
     if request.tasks_dir and not Path(request.tasks_dir).exists():
         raise EvalPlanError(f"--tasks-dir not found: {request.tasks_dir}")
     if request.matrix is not None and not Path(request.matrix).is_file():

{benchflow-0.7.6.dev2072 → benchflow-0.7.6.dev2102}/src/benchflow/publish/huggingface.py

@@ -38,6 +38,14 @@ def _resolve_url(repo_id: str, repo_type: str, path_in_repo: str) -> str:
     return f"https://huggingface.co/{kind}{repo_id}/resolve/main/{path_in_repo}"
 
 
+def _bucket_tree_url(bucket_id: str, path_in_repo: str) -> str:
+    # Buckets are non-versioned (no "main" branch), so the browsable listing
+    # is /tree/<path> directly, not /resolve/<path> (which 404s) or
+    # /tree/main/<path> (the git-repo convention _tree_url uses).
+    suffix = f"/tree/{path_in_repo.strip('/')}" if path_in_repo else ""
+    return f"https://huggingface.co/buckets/{bucket_id}{suffix}"
+
+
 def _check_public_files(repo_id: str, repo_type: str, path_in_repo: str) -> None:
     index_url = _tree_url(repo_id, repo_type, path_in_repo)
     response = httpx.get(index_url, follow_redirects=True, timeout=20)
@@ -79,6 +87,106 @@ def publish_folder_to_hf(
     )
 
 
+def publish_folder_to_bucket(
+    folder: Path,
+    *,
+    bucket_id: str,
+    path_in_repo: str = "",
+    private: bool = False,
+) -> HfPublishResult:
+    if not folder.is_dir():
+        raise ValueError(f"publish source folder not found: {folder}")
+    try:
+        from huggingface_hub import create_bucket, sync_bucket
+        from huggingface_hub.errors import HfHubHTTPError
+    except ImportError as exc:  # pragma: no cover - depends on env
+        raise ValueError(
+            "huggingface_hub with bucket support (create_bucket/sync_bucket) is "
+            "required for --publish-bucket; upgrade huggingface_hub"
+        ) from exc
+    try:
+        create_bucket(bucket_id, private=private)
+    except HfHubHTTPError as exc:
+        if exc.response is None or exc.response.status_code != 409:
+            raise
+    prefix = path_in_repo.strip("/")
+    remote = (
+        f"hf://buckets/{bucket_id}/{prefix}" if prefix else f"hf://buckets/{bucket_id}"
+    )
+    sync_bucket(str(folder), remote)
+    return HfPublishResult(
+        repo_id=bucket_id,
+        repo_type="bucket",
+        path_in_repo=prefix,
+        url=_bucket_tree_url(bucket_id, prefix),
+    )
+
+
+_EVAL_RESULTS_PATH = ".eval_results/benchflow.yaml"
+
+
+def _existing_eval_results(model_repo: str) -> list[dict]:
+    from huggingface_hub import hf_hub_download
+    from huggingface_hub.errors import EntryNotFoundError, RepositoryNotFoundError
+
+    try:
+        downloaded = hf_hub_download(
+            repo_id=model_repo, filename=_EVAL_RESULTS_PATH, repo_type="model"
+        )
+    except (EntryNotFoundError, RepositoryNotFoundError):
+        return []
+    import yaml
+
+    data = yaml.safe_load(Path(downloaded).read_text())
+    return data if isinstance(data, list) else []
+
+
+def _upsert_eval_result(existing: list[dict], entry: dict) -> list[dict]:
+    key = (entry["dataset"]["id"], entry["dataset"]["task_id"])
+    kept = [
+        row
+        for row in existing
+        if (row.get("dataset", {}).get("id"), row.get("dataset", {}).get("task_id"))
+        != key
+    ]
+    return [*kept, entry]
+
+
+def open_eval_results_pr(
+    *,
+    model_repo: str,
+    dataset_id: str,
+    task_id: str,
+    value: float,
+    source_url: str | None = None,
+    notes: str | None = None,
+) -> str | None:
+    try:
+        import yaml
+        from huggingface_hub import CommitOperationAdd, HfApi
+    except ImportError as exc:  # pragma: no cover - depends on env
+        raise ValueError(
+            "huggingface_hub is required for --eval-results-model"
+        ) from exc
+    entry: dict = {"dataset": {"id": dataset_id, "task_id": task_id}, "value": value}
+    if source_url:
+        entry["source"] = {"url": source_url}
+    if notes:
+        entry["notes"] = notes
+    merged = _upsert_eval_result(_existing_eval_results(model_repo), entry)
+    content = yaml.safe_dump(merged, sort_keys=False).encode("utf-8")
+    commit = HfApi().create_commit(
+        repo_id=model_repo,
+        repo_type="model",
+        operations=[
+            CommitOperationAdd(path_in_repo=_EVAL_RESULTS_PATH, path_or_fileobj=content)
+        ],
+        commit_message=f"Add {dataset_id} eval results",
+        create_pr=True,
+    )
+    return commit.pr_url
+
+
 def publish_file_to_hf(
     file_path: Path,
     *,

benchflow-0.7.6.dev2102/src/benchflow/trajectories/viewer/__init__.py

@@ -0,0 +1,77 @@
+"""Trajectory viewer package.
+
+Import surface preserved from the former single-module viewer: everything
+tests and the CLI reached via ``benchflow.trajectories.viewer`` re-exports
+here. See the sibling modules for the actual responsibilities.
+"""
+
+from .catalog import (
+    _discover_rollouts,
+    _resolve_browse_rollout,
+    _rollout_summary,
+    _runs_cap,
+)
+from .legacy import (
+    _NO_TRAJECTORIES_HTML,
+    _VIEWER_CSS,
+    _confirm_bar_html,
+    _inject_confirm_bar,
+    _tool_accent_class,
+    render_jsonl_file,
+    render_rollout,
+    render_turn,
+)
+from .payload import (
+    _DIAGNOSTIC_KEYS_FALLBACK,
+    _build_acp_payload,
+    _diagnostic_keys,
+    _is_acp_rollout_dir,
+    _load_prompts,
+    _parse_jsonl,
+    _safe_json,
+    _tool_content_texts,
+)
+from .render import _render_acp_trajectory, _render_shell
+from .server import serve
+from .sources import (
+    _HF_VIEWER_FILES,
+    HfDatasetSource,
+    LocalPathSource,
+    ViewerSourceError,
+    parse_source,
+    resolve_hf_dataset,
+)
+
+__all__ = [
+    # public surface
+    "render_rollout",
+    "render_turn",
+    "render_jsonl_file",
+    "serve",
+    "parse_source",
+    "resolve_hf_dataset",
+    "LocalPathSource",
+    "HfDatasetSource",
+    "ViewerSourceError",
+    # internals reached by tests and siblings through the historical module
+    "_DIAGNOSTIC_KEYS_FALLBACK",
+    "_HF_VIEWER_FILES",
+    "_NO_TRAJECTORIES_HTML",
+    "_VIEWER_CSS",
+    "_build_acp_payload",
+    "_confirm_bar_html",
+    "_diagnostic_keys",
+    "_discover_rollouts",
+    "_inject_confirm_bar",
+    "_is_acp_rollout_dir",
+    "_load_prompts",
+    "_parse_jsonl",
+    "_render_acp_trajectory",
+    "_render_shell",
+    "_resolve_browse_rollout",
+    "_rollout_summary",
+    "_runs_cap",
+    "_safe_json",
+    "_tool_accent_class",
+    "_tool_content_texts",
+]

benchflow-0.7.6.dev2102/src/benchflow/trajectories/viewer/__main__.py

@@ -0,0 +1,13 @@
+"""``python -m benchflow.trajectories.viewer <rollout_dir_or_jsonl> [port]``"""
+
+import sys
+
+from .server import serve
+
+if len(sys.argv) < 2:
+    print(
+        "Usage: python -m benchflow.trajectories.viewer <rollout_dir_or_jsonl> [port]"
+    )
+    sys.exit(1)
+port = int(sys.argv[2]) if len(sys.argv) > 2 else 8888
+serve(sys.argv[1], port)

benchflow-0.7.6.dev2102/src/benchflow/trajectories/viewer/assets/boot.js

@@ -0,0 +1,135 @@
+BF.navigation = (() => {
+  let generation = 0;
+  let request = null;
+  let loadedRun = null;
+  let selectedRun = null;
+
+  function beginTransition() {
+    generation += 1;
+    if (request) request.abort();
+    request = null;
+    BF.detail.cancel();
+    return generation;
+  }
+
+  function showCatalog(push) {
+    beginTransition();
+    loadedRun = null;
+    if (push) BF.catalog.writeURL(null, true);
+    BF.catalog.show({ focusRun: selectedRun });
+    document.title = "runs - benchflow trajectory";
+  }
+
+  async function openRun(runId, push, sourceButton = null) {
+    const index = document.getElementById("view-index");
+    if (!index.classList.contains("hidden")) BF.catalog.rememberScroll();
+    selectedRun = runId;
+    const transition = beginTransition();
+    loadedRun = null;
+    if (push) BF.catalog.writeURL(runId, true);
+    BF.core.showDetailShell(true);
+    BF.detail.showLoading(runId);
+
+    const controller = new AbortController();
+    request = controller;
+    try {
+      const response = await fetch("/api/rollout?id=" + encodeURIComponent(runId), {
+        signal: controller.signal,
+      });
+      if (!response.ok) throw new Error("HTTP " + response.status + " loading run " + runId);
+      const body = await response.text();
+      let payload;
+      try {
+        payload = JSON.parse(body);
+      } catch (error) {
+        throw new TypeError("malformed JSON from the rollout API: " + error.message);
+      }
+      BF.core.requirePayload(payload);
+      if (transition !== generation) return;
+      BF.detail.loadPayload(payload, { focusHeading: Boolean(sourceButton) });
+      loadedRun = runId;
+      window.scrollTo(0, 0);
+    } catch (error) {
+      if (controller.signal.aborted || transition !== generation) return;
+      BF.detail.showError("Failed to load run " + runId + ": " + error.message);
+    } finally {
+      if (transition === generation) request = null;
+    }
+  }
+
+  function showUnknownRun(runId) {
+    selectedRun = runId;
+    beginTransition();
+    loadedRun = null;
+    BF.core.showDetailShell(true);
+    BF.detail.showError(BF.catalog.unknownRunMessage(runId));
+  }
+
+  function applyLocation() {
+    const runId = BF.catalog.readURL();
+    if (runId && runId === loadedRun && !document.getElementById("content").classList.contains("hidden")) {
+      return;
+    }
+    if (runId && BF.catalog.hasRun(runId)) openRun(runId, false);
+    else if (runId) showUnknownRun(runId);
+    else showCatalog(false);
+  }
+
+  function startBrowse(boot) {
+    BF.catalog.init(boot, (runId, sourceButton) => openRun(runId, true, sourceButton));
+    const back = document.getElementById("backbtn");
+    back.addEventListener("click", () => showCatalog(true));
+    window.addEventListener("popstate", applyLocation);
+    applyLocation();
+  }
+
+  function startSingle(payload) {
+    beginTransition();
+    BF.core.showDetailShell(false);
+    try {
+      BF.detail.loadPayload(payload);
+    } catch (error) {
+      BF.detail.showError("The embedded trajectory payload is malformed: " + error.message, "viewer data error");
+    }
+  }
+
+  return { startBrowse, startSingle };
+})();
+
+(() => {
+  function bootError(message) {
+    BF.core.showDetailShell(false);
+    BF.detail.showError(message, "viewer data error");
+  }
+
+  const node = document.getElementById("bf-payload");
+  let boot;
+  try {
+    boot = JSON.parse(node ? node.textContent : "");
+  } catch (error) {
+    bootError("The embedded viewer data is not valid JSON: " + error.message);
+    return;
+  }
+  if (!BF.core.isRecord(boot)) {
+    bootError("The embedded viewer data must be a JSON object.");
+    return;
+  }
+  if (boot.mode === "single") {
+    BF.navigation.startSingle(boot.payload);
+    return;
+  }
+  if (boot.mode === "browse") {
+    if (!Array.isArray(boot.rollouts)) {
+      bootError("Browse-mode viewer data must contain a rollouts array.");
+      return;
+    }
+    const invalid = boot.rollouts.find((run) => !BF.core.isRecord(run) || typeof run.id !== "string" || !run.id);
+    if (invalid) {
+      bootError("A catalog entry is malformed: every rollout must be an object with a non-empty string id.");
+      return;
+    }
+    BF.navigation.startBrowse(boot);
+    return;
+  }
+  bootError('Unknown viewer mode: expected "single" or "browse".');
+})();