Sync from GitHub via hub-sync

.env.example

@@ -0,0 +1,8 @@
+# Dataset host URL (defaults to https://huggingface.co/datasets)
+# DATASET_URL=https://huggingface.co/datasets
+
+# Annotation backend (optional). When set, the Annotations tab persists
+# edits, rewrites parquet shards with `language_persistent` + `language_events`
+# columns (lerobot#3467 / #3471), and can push to the HF Hub. When unset, the
+# Annotations tab is read/edit-only with sessionStorage persistence.
+# NEXT_PUBLIC_ANNOTATE_BACKEND_URL=http://127.0.0.1:7861

.prettierignore

@@ -0,0 +1,13 @@
+# Build output
+.next/
+out/
+node_modules/
+
+# Backend (Python)
+backend/.venv/
+backend/__pycache__/
+backend/**/*.pyc
+
+# Lockfiles
+bun.lock
+package-lock.json

README.md

@@ -37,6 +37,7 @@ This tool is designed to help robotics researchers and practitioners quickly ins
 - **Action Insights Panel:** Data-driven analysis tools to guide training configuration — includes autocorrelation, state-action alignment, speed distribution, and cross-episode variance heatmap.
 - **Filtering Panel:** Identify and flag problematic episodes (low movement, jerky motion, outlier length) for removal. Exports flagged episode IDs as a ready-to-run LeRobot CLI command.
 - **3D URDF Viewer:** Visualize robot joint poses frame-by-frame in an interactive 3D scene, with end-effector trail rendering. Supports SO-100, SO-101, and OpenArm bimanual robots.
+- **Annotations Panel:** Hand-edit the v3.1 language schema (`language_persistent` + `language_events`) — subtask, plan, memory, interjection + paired speech, and VQA atoms with bounding-box / keypoint / count / attribute / spatial answers. VQA bboxes and keypoints render as overlays on the video player; drag or click on a camera to draw new ones. Backed by an optional FastAPI service (in `backend/`) for parquet rewrites and HF Hub push.
 - **Efficient Data Loading:** Uses parquet and JSON loading for large dataset support, with pagination, chunking, and lazy-loaded panels for fast initial load.
 - **Responsive UI:** Built with React, Next.js, and Tailwind CSS for a fast, modern user experience.
 
@@ -100,6 +101,43 @@ bun run format
 ### Environment Variables
 
 - `DATASET_URL`: (optional) Base URL for dataset hosting (defaults to HuggingFace Datasets).
+- `NEXT_PUBLIC_ANNOTATE_BACKEND_URL`: (optional) URL of the FastAPI annotation
+  backend (`backend/app.py`). When set, the Annotations tab can save edits and
+  rewrite parquet shards / push to the Hub. When unset the tab is read/edit
+  only with sessionStorage persistence.
+
+## Annotations backend (optional)
+
+The Annotations tab edits LeRobot v3.1 language atoms — `language_persistent`
+(broadcast subtask/plan/memory) and `language_events` (per-frame
+interjection / vqa / speech) — and renders existing bbox/keypoint atoms over
+the video player. Edits live in `sessionStorage` by default; to write the
+new columns into `data/chunk-*/file-*.parquet` (matching the writer in
+[lerobot#3471](https://github.com/huggingface/lerobot/pull/3471)) and push the
+result to the Hub, run the bundled FastAPI service:
+
+```bash
+# 1. install + start the backend (port 7861 by default)
+cd backend
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn app:app --port 7861 --reload
+
+# 2. start the visualizer with the backend URL configured
+cd ..
+NEXT_PUBLIC_ANNOTATE_BACKEND_URL=http://127.0.0.1:7861 bun run dev
+```
+
+The backend exposes:
+
+- `POST /api/dataset/load` — load a dataset by `repo_id` or `local_path`
+- `GET  /api/episodes/{ep}/atoms` — list atoms for an episode
+- `POST /api/episodes/{ep}/atoms` — replace atoms (event timestamps are
+  snapped to exact source-frame timestamps before persisting)
+- `GET  /api/episodes/{ep}/frame_timestamps` — used client-side for snapping
+- `POST /api/export` — rewrite parquet with the new language columns plus
+  the dataset-level `tools` column (drops legacy `subtask_index`)
+- `POST /api/push_to_hub` — export and push to a target repo
 
 ## Docker Deployment
 

backend/README.md

@@ -0,0 +1,72 @@
+# Annotations backend
+
+FastAPI service that lets the visualizer write the LeRobot v3.1 language
+schema (`language_persistent` + `language_events`) directly into
+`data/chunk-*/file-*.parquet`. Mirrors the conventions of the steerable
+annotation pipeline in [lerobot#3471](https://github.com/huggingface/lerobot/pull/3471):
+
+- per-episode persistent identity (every frame in the episode sees the same
+  `language_persistent` list)
+- exact-frame timestamps for events (`language_events`)
+- column routing per `column_for_style(style)` — `subtask`/`plan`/`memory`
+  go to `language_persistent`, `interjection`/`vqa` and speech tool-call
+  atoms (`style=null`) go to `language_events`
+- dataset-level `tools` column carrying the JSON schema for the `say` tool
+- legacy `subtask_index` column dropped
+
+## Run
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn app:app --port 7861 --reload
+```
+
+Then start the Next.js visualizer with the backend URL configured:
+
+```bash
+NEXT_PUBLIC_ANNOTATE_BACKEND_URL=http://127.0.0.1:7861 bun run dev
+```
+
+## API
+
+| Method | Path                                  | Purpose                                                              |
+| ------ | ------------------------------------- | -------------------------------------------------------------------- |
+| GET    | `/api/health`                         | Liveness + style catalog                                             |
+| POST   | `/api/dataset/load`                   | Cache + read a dataset's `meta/`                                     |
+| GET    | `/api/episodes/{ep}/atoms`            | Read saved atoms                                                     |
+| POST   | `/api/episodes/{ep}/atoms`            | Write atoms (event timestamps are snapped to exact frame timestamps) |
+| GET    | `/api/episodes/{ep}/frame_timestamps` | Frame timestamps for client-side snapping                            |
+| POST   | `/api/export`                         | Rewrite parquet shards into a new directory                          |
+| POST   | `/api/push_to_hub`                    | Export and push to a target repo                                     |
+
+## Storage layout
+
+Annotations are persisted to `<dataset_root>/meta/lerobot_annotations.json`,
+v2 schema:
+
+```json
+{
+  "version": 2,
+  "schema": {
+    "persistent_styles": ["memory", "plan", "subtask"],
+    "event_styles": ["interjection", "vqa"]
+  },
+  "episodes": {
+    "0": {
+      "atoms": [
+        {
+          "role": "assistant",
+          "content": "grasp the sponge",
+          "style": "subtask",
+          "timestamp": 0.0,
+          "tool_calls": null
+        }
+      ]
+    }
+  }
+}
+```
+
+The legacy v1 layout (`subtasks`/`high_levels` from earlier `lerobot-annotate`)
+is auto-migrated on load.

backend/app.py

@@ -0,0 +1,871 @@
+"""LeRobot dataset visualizer — annotation backend.
+
+A small FastAPI service that lets the Next.js visualizer write the v3.1
+language schema introduced in lerobot#3467 (PR1) and used by the steerable
+annotation pipeline in lerobot#3471 (PR2). Specifically it owns:
+
+- per-episode annotation state, persisted to ``meta/lerobot_annotations.json``
+- snapping event-style atom timestamps to exact source-frame timestamps
+  (the writer in lerobot#3471 enforces exact match)
+- exporting the annotated dataset by rewriting ``data/chunk-*/file-*.parquet``
+  with two new columns:
+    * ``language_persistent`` — broadcast per-episode (subtask/plan/memory)
+    * ``language_events``     — per-frame (interjection/vqa, plus speech
+      tool-call atoms with style=None)
+  and a dataset-level ``tools`` column carrying the JSON schema for ``say``.
+- pushing the result back to the Hugging Face Hub.
+
+The frontend can run without this backend (read-only browsing). Annotation
+write paths only light up when ``NEXT_PUBLIC_ANNOTATE_BACKEND_URL`` points to
+an instance of this service.
+
+Run locally:
+
+    cd backend && pip install -r requirements.txt
+    uvicorn app:app --port 7861 --reload
+
+Then in another terminal:
+
+    NEXT_PUBLIC_ANNOTATE_BACKEND_URL=http://127.0.0.1:7861 bun run dev
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+import pyarrow as pa
+import pyarrow.parquet as pq
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from huggingface_hub import HfApi, hf_hub_download, snapshot_download
+from pydantic import BaseModel
+
+logger = logging.getLogger("lerobot-annotate")
+logging.basicConfig(level=logging.INFO)
+
+CACHE_ROOT = Path(os.environ.get("LEROBOT_ANNOTATE_CACHE", "/tmp/lerobot_visualizer_annotate_cache"))
+EXPORT_ROOT = Path(os.environ.get("LEROBOT_ANNOTATE_EXPORT", "/tmp/lerobot_visualizer_annotate_exports"))
+
+# --- Schema mirrors src/lerobot/datasets/language.py --------------------------
+
+PERSISTENT_STYLES = {"task_aug", "subtask", "plan", "memory"}
+EVENT_ONLY_STYLES = {"interjection", "vqa"}
+KNOWN_STYLES = PERSISTENT_STYLES | EVENT_ONLY_STYLES
+LANGUAGE_PERSISTENT = "language_persistent"
+LANGUAGE_EVENTS = "language_events"
+
+SAY_TOOL_SCHEMA: dict[str, Any] = {
+    "type": "function",
+    "function": {
+        "name": "say",
+        "description": "Speak a short utterance to the user via the TTS executor.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "text": {"type": "string", "description": "The verbatim text to speak."},
+            },
+            "required": ["text"],
+        },
+    },
+}
+
+
+def column_for_style(style: str | None) -> str:
+    if style is None:
+        return LANGUAGE_EVENTS
+    if style in PERSISTENT_STYLES:
+        return LANGUAGE_PERSISTENT
+    if style in EVENT_ONLY_STYLES:
+        return LANGUAGE_EVENTS
+    raise ValueError(f"Unknown language style: {style!r}")
+
+
+# --- Pydantic models ----------------------------------------------------------
+
+
+class DatasetRef(BaseModel):
+    repo_id: str | None = None
+    revision: str | None = None
+    local_path: str | None = None
+
+
+class LoadRequest(DatasetRef):
+    pass
+
+
+class LanguageAtom(BaseModel):
+    role: str
+    content: str | None = None
+    style: str | None = None
+    timestamp: float
+    # ``observation.images.*`` feature key for view-dependent atoms
+    # (vqa / trace). ``None`` for camera-agnostic atoms. Mirrors the
+    # row-level ``camera`` field added in lerobot PR 3467.
+    camera: str | None = None
+    tool_calls: list[dict[str, Any]] | None = None
+
+
+class EpisodeAtomsPayload(BaseModel):
+    repo_id: str | None = None
+    local_path: str | None = None
+    episode_index: int
+    atoms: list[LanguageAtom] = []
+
+
+class ExportRequest(DatasetRef):
+    output_dir: str | None = None
+    copy_videos: bool = False
+
+
+class PushToHubRequest(DatasetRef):
+    hf_token: str
+    push_in_place: bool = True
+    new_repo_id: str | None = None
+    private: bool = False
+    commit_message: str = "Add language annotations"
+
+
+@dataclass
+class EpisodeAnnotations:
+    atoms: list[dict[str, Any]] = field(default_factory=list)
+
+
+# --- Per-dataset state cache --------------------------------------------------
+
+
+@dataclass
+class DatasetState:
+    repo_id: str | None
+    local_path: str | None
+    revision: str | None
+    root: Path
+    info: dict[str, Any]
+    episodes_df: pd.DataFrame
+    annotations: dict[int, EpisodeAnnotations] = field(default_factory=dict)
+    frame_ts_cache: dict[int, list[float]] = field(default_factory=dict)
+
+    @property
+    def annotations_path(self) -> Path:
+        return self.root / "meta" / "lerobot_annotations.json"
+
+
+_states: dict[str, DatasetState] = {}
+
+
+def _state_key(req: DatasetRef) -> str:
+    if req.local_path:
+        return f"local::{Path(req.local_path).expanduser().resolve()}"
+    if req.repo_id:
+        return f"hf::{req.repo_id}@{req.revision or 'main'}"
+    raise HTTPException(status_code=400, detail="need repo_id or local_path")
+
+
+def _ensure_state(req: DatasetRef) -> DatasetState:
+    key = _state_key(req)
+    if key in _states:
+        return _states[key]
+    return _load_state(req, key)
+
+
+def _load_state(req: DatasetRef, key: str) -> DatasetState:
+    if req.local_path:
+        root = Path(req.local_path).expanduser().resolve()
+        if not root.exists():
+            raise HTTPException(status_code=404, detail=f"Dataset path not found: {root}")
+    elif req.repo_id:
+        CACHE_ROOT.mkdir(parents=True, exist_ok=True)
+        slug = req.repo_id.replace("/", "__") + (f"@{req.revision}" if req.revision else "")
+        root = CACHE_ROOT / slug
+        root.mkdir(parents=True, exist_ok=True)
+        snapshot_download(
+            req.repo_id,
+            repo_type="dataset",
+            revision=req.revision,
+            local_dir=root,
+            allow_patterns=["meta/*"],
+        )
+    else:
+        raise HTTPException(status_code=400, detail="need repo_id or local_path")
+
+    info_path = root / "meta" / "info.json"
+    if not info_path.exists():
+        raise HTTPException(status_code=404, detail=f"Missing meta/info.json at {root}")
+    info = json.loads(info_path.read_text())
+
+    episodes_root = root / "meta" / "episodes"
+    if not episodes_root.exists():
+        raise HTTPException(status_code=404, detail="Missing meta/episodes/ directory")
+    files = sorted(episodes_root.rglob("*.parquet"))
+    if not files:
+        raise HTTPException(status_code=404, detail="No episodes parquet files found")
+    episodes_df = (
+        pd.concat([pd.read_parquet(p) for p in files], ignore_index=True)
+        .sort_values("episode_index")
+        .reset_index(drop=True)
+    )
+
+    state = DatasetState(
+        repo_id=req.repo_id,
+        local_path=str(root) if req.local_path else None,
+        revision=req.revision,
+        root=root,
+        info=info,
+        episodes_df=episodes_df,
+    )
+    _load_existing_annotations(state)
+    _states[key] = state
+    return state
+
+
+def _load_existing_annotations(state: DatasetState) -> None:
+    path = state.annotations_path
+    if not path.exists():
+        return
+    data = json.loads(path.read_text())
+    for ep_str, payload in data.get("episodes", {}).items():
+        ep_idx = int(ep_str)
+        atoms = payload.get("atoms")
+        if atoms is None:
+            # v1 format from older lerobot-annotate (legacy)
+            atoms = []
+            for seg in payload.get("subtasks", []):
+                if "label" in seg and "start" in seg:
+                    atoms.append(
+                        {
+                            "role": "assistant",
+                            "content": str(seg["label"]),
+                            "style": "subtask",
+                            "timestamp": float(seg["start"]),
+                            "tool_calls": None,
+                        }
+                    )
+            for seg in payload.get("high_levels", []):
+                ts = float(seg.get("start", 0.0))
+                if seg.get("user_prompt"):
+                    atoms.append(
+                        {
+                            "role": "user",
+                            "content": str(seg["user_prompt"]),
+                            "style": "interjection",
+                            "timestamp": ts,
+                            "tool_calls": None,
+                        }
+                    )
+                if seg.get("robot_utterance"):
+                    atoms.append(
+                        {
+                            "role": "assistant",
+                            "content": None,
+                            "style": None,
+                            "timestamp": ts,
+                            "tool_calls": [
+                                {
+                                    "type": "function",
+                                    "function": {
+                                        "name": "say",
+                                        "arguments": {"text": str(seg["robot_utterance"])},
+                                    },
+                                }
+                            ],
+                        }
+                    )
+        state.annotations[ep_idx] = EpisodeAnnotations(atoms=[dict(a) for a in atoms])
+
+
+def _save_annotations(state: DatasetState) -> None:
+    path = state.annotations_path
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "version": 2,
+        "schema": {
+            "persistent_styles": sorted(PERSISTENT_STYLES),
+            "event_styles": sorted(EVENT_ONLY_STYLES),
+        },
+        "episodes": {str(ep): {"atoms": ann.atoms} for ep, ann in state.annotations.items()},
+    }
+    path.write_text(json.dumps(payload, indent=2))
+
+
+# --- Frame-timestamp helpers --------------------------------------------------
+
+
+def _episode_data_path(state: DatasetState, episode_index: int) -> Path | None:
+    rows = state.episodes_df[state.episodes_df["episode_index"] == episode_index]
+    if rows.empty:
+        return None
+    row = rows.iloc[0]
+    chunk_col = "data/chunk_index"
+    file_col = "data/file_index"
+    if chunk_col not in row or file_col not in row:
+        return None
+    chunk_index = int(row[chunk_col])
+    file_index = int(row[file_col])
+    rel = state.info.get("data_path") or "data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet"
+    rel = rel.format(chunk_index=chunk_index, file_index=file_index)
+    full = (state.root / rel).resolve()
+    if full.exists():
+        return full
+    if state.repo_id:
+        try:
+            hf_hub_download(
+                repo_id=state.repo_id,
+                repo_type="dataset",
+                filename=rel,
+                revision=state.revision,
+                local_dir=state.root,
+            )
+        except Exception as e:  # noqa: BLE001
+            logger.warning("frame_ts download failed for ep %s: %s", episode_index, e)
+            return None
+    return full if full.exists() else None
+
+
+def _frame_timestamps(state: DatasetState, episode_index: int) -> list[float]:
+    if episode_index in state.frame_ts_cache:
+        return state.frame_ts_cache[episode_index]
+    path = _episode_data_path(state, episode_index)
+    if path is None:
+        return []
+    try:
+        df = pd.read_parquet(path, columns=["episode_index", "timestamp"])
+    except Exception as e:  # noqa: BLE001
+        logger.warning("frame_ts read failed for ep %s: %s", episode_index, e)
+        return []
+    ts = df.loc[df["episode_index"] == episode_index, "timestamp"].astype(float).tolist()
+    ts.sort()
+    state.frame_ts_cache[episode_index] = ts
+    return ts
+
+
+def _coerce_existing_atom(
+    raw: Any, fallback_ts: float | None = None
+) -> dict[str, Any] | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, dict):
+        try:
+            raw = dict(raw)
+        except Exception:  # noqa: BLE001
+            return None
+    if not raw.get("role"):
+        return None
+    tool_calls = raw.get("tool_calls")
+    if tool_calls is not None and not isinstance(tool_calls, list):
+        tool_calls = [tool_calls]
+    camera = raw.get("camera")
+    if isinstance(camera, str) and not camera:
+        camera = None
+    raw_ts = raw.get("timestamp")
+    if raw_ts is None:
+        # v3.1 event rows don't carry a ``timestamp`` field in the struct —
+        # the writer drops it because the parquet row's frame timestamp is
+        # already the event's firing time. Use the caller-provided fallback
+        # so dedup doesn't collapse every event atom into one (timestamp=0.0)
+        # entry.
+        timestamp = float(fallback_ts) if fallback_ts is not None else 0.0
+    else:
+        timestamp = float(raw_ts)
+    return {
+        "role": str(raw["role"]),
+        "content": None if raw.get("content") is None else str(raw.get("content")),
+        "style": raw.get("style"),
+        "timestamp": timestamp,
+        "camera": camera if isinstance(camera, str) else None,
+        "tool_calls": tool_calls or None,
+    }
+
+
+def _extract_existing_atoms_from_table(table: pa.Table, episode_index: int) -> list[dict[str, Any]]:
+    if "episode_index" not in table.column_names:
+        return []
+
+    episode_col = table.column("episode_index").to_pylist()
+    persistent_col = (
+        table.column(LANGUAGE_PERSISTENT).to_pylist()
+        if LANGUAGE_PERSISTENT in table.column_names
+        else None
+    )
+    events_col = (
+        table.column(LANGUAGE_EVENTS).to_pylist()
+        if LANGUAGE_EVENTS in table.column_names
+        else None
+    )
+    # Event rows don't carry their own ``timestamp`` in the v3.1 struct;
+    # the parquet row's frame timestamp IS the event's firing time. Read
+    # the timestamp column so we can pass it as a fallback to
+    # ``_coerce_existing_atom`` — without this, every event row defaults
+    # to timestamp=0.0 and dedup collapses them all into one.
+    ts_col = (
+        table.column("timestamp").to_pylist()
+        if "timestamp" in table.column_names
+        else None
+    )
+
+    atoms: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    persistent_loaded = False
+
+    def add_many(raw_atoms: Any, fallback_ts: float | None = None) -> None:
+        if not raw_atoms:
+            return
+        for raw in raw_atoms:
+            atom = _coerce_existing_atom(raw, fallback_ts=fallback_ts)
+            if atom is None:
+                continue
+            key = json.dumps(atom, sort_keys=True, default=str)
+            if key in seen:
+                continue
+            seen.add(key)
+            atoms.append(atom)
+
+    for row_idx, ep_value in enumerate(episode_col):
+        if int(ep_value) != int(episode_index):
+            continue
+        if persistent_col is not None and not persistent_loaded:
+            add_many(persistent_col[row_idx])
+            persistent_loaded = True
+        if events_col is not None:
+            row_ts = float(ts_col[row_idx]) if ts_col is not None else None
+            add_many(events_col[row_idx], fallback_ts=row_ts)
+
+    atoms.sort(key=lambda a: (a["timestamp"], a.get("style") or "", a.get("role") or ""))
+    return atoms
+
+
+def _snap(ts: float, frame_ts: list[float]) -> float:
+    if not frame_ts:
+        return float(ts)
+    return float(min(frame_ts, key=lambda f: abs(f - ts)))
+
+
+VIEW_DEPENDENT_STYLES = {"vqa", "trace"}
+
+
+def _validate_atom(atom: dict[str, Any]) -> None:
+    style = atom.get("style")
+    if style is not None and style not in KNOWN_STYLES:
+        raise HTTPException(status_code=400, detail=f"Unknown language style: {style!r}")
+    has_content = atom.get("content") is not None
+    has_tools = bool(atom.get("tool_calls"))
+    if not (has_content or has_tools):
+        raise HTTPException(status_code=400, detail="atom must have content or tool_calls")
+    if style is None and not has_tools:
+        raise HTTPException(status_code=400, detail="style=None requires tool_calls (speech atom)")
+    camera = atom.get("camera")
+    if camera is not None and not isinstance(camera, str):
+        raise HTTPException(status_code=400, detail="camera must be a string or null")
+    # Mirror lerobot's row-level invariant: camera is set iff the style is
+    # view-dependent. We don't enforce camera-required here because the
+    # visualizer accepts in-progress edits where the user hasn't picked a
+    # camera yet — the writer (or the next save round-trip) will surface
+    # the missing tag. We DO reject camera-on-non-view-dependent so the
+    # field can't drift onto task_aug/subtask/plan/memory rows.
+    if (
+        camera is not None
+        and style is not None
+        and style not in VIEW_DEPENDENT_STYLES
+    ):
+        raise HTTPException(
+            status_code=400,
+            detail=f"camera must be null for style={style!r} (only vqa/trace are view-dependent)",
+        )
+
+
+def _normalize_atom(atom: dict[str, Any], *, with_timestamp: bool) -> dict[str, Any]:
+    """Coerce an atom into a language-column struct row.
+
+    Field order matches the canonical schema in ``lerobot.datasets.language``
+    (``PERSISTENT_ROW_FIELDS`` / ``EVENT_ROW_FIELDS``); pyarrow infers the
+    struct schema from insertion order. Persistent rows carry their own
+    ``timestamp`` (the moment the state became active); event rows do NOT —
+    the parquet frame's ``timestamp`` column IS the event's firing time, so a
+    per-row ``timestamp`` field would be redundant (matches lerobot#3471's
+    ``language_event_row_arrow_type``, which omits it).
+    """
+    camera = atom.get("camera")
+    if isinstance(camera, str) and not camera:
+        camera = None
+    row: dict[str, Any] = {
+        "role": str(atom["role"]),
+        "content": None if atom.get("content") is None else str(atom["content"]),
+        "style": atom.get("style"),
+    }
+    if with_timestamp:
+        row["timestamp"] = float(atom.get("timestamp", 0.0))
+    row["camera"] = camera if isinstance(camera, str) else None
+    row["tool_calls"] = list(atom["tool_calls"]) if atom.get("tool_calls") else None
+    return row
+
+
+# --- Export -------------------------------------------------------------------
+
+
+def _materialize_table(table: pa.Table, atoms_by_ep: dict[int, list[dict[str, Any]]]) -> tuple[pa.Table, int, int]:
+    if "episode_index" not in table.column_names or "timestamp" not in table.column_names:
+        raise HTTPException(
+            status_code=400,
+            detail="data parquet missing 'episode_index' or 'timestamp' columns",
+        )
+
+    episode_col = table.column("episode_index").to_pylist()
+    ts_col = [float(x) for x in table.column("timestamp").to_pylist()]
+    n_rows = table.num_rows
+
+    persistent_by_ep: dict[int, list[dict[str, Any]]] = {}
+    events_by_ep_ts: dict[int, dict[float, list[dict[str, Any]]]] = {}
+
+    n_persistent_total = 0
+    n_event_total = 0
+
+    unique_eps = sorted(set(episode_col))
+    for ep_idx in unique_eps:
+        atoms = atoms_by_ep.get(int(ep_idx))
+        if atoms is None:
+            atoms = _extract_existing_atoms_from_table(table, int(ep_idx))
+        persistent_rows: list[dict[str, Any]] = []
+        frame_ts = sorted({ts_col[i] for i in range(n_rows) if episode_col[i] == ep_idx})
+
+        buckets: dict[float, list[dict[str, Any]]] = {}
+        for atom in atoms:
+            col = column_for_style(atom.get("style"))
+            if col == LANGUAGE_PERSISTENT:
+                persistent_rows.append(_normalize_atom(atom, with_timestamp=True))
+            else:
+                # The event row's firing time lives in the parquet frame's
+                # ``timestamp`` column, so we bucket by the snapped timestamp
+                # but do NOT store it inside the event struct (matches the
+                # lerobot#3471 writer / canonical schema).
+                ts = float(atom.get("timestamp", 0.0))
+                if frame_ts:
+                    ts = _snap(ts, frame_ts)
+                buckets.setdefault(ts, []).append(_normalize_atom(atom, with_timestamp=False))
+
+        persistent_rows.sort(
+            key=lambda r: (r["timestamp"], r.get("style") or "", r.get("role") or "")
+        )
+        persistent_by_ep[ep_idx] = persistent_rows
+
+        for ts in buckets:
+            buckets[ts].sort(key=lambda r: (r.get("style") or "", r.get("role") or ""))
+        events_by_ep_ts[ep_idx] = buckets
+
+        n_persistent_total += len(persistent_rows)
+        n_event_total += sum(len(v) for v in buckets.values())
+
+    per_row_persistent = [persistent_by_ep.get(episode_col[i], []) for i in range(n_rows)]
+    per_row_events = [
+        events_by_ep_ts.get(episode_col[i], {}).get(ts_col[i], []) for i in range(n_rows)
+    ]
+
+    keep_names: list[str] = []
+    keep_cols: list[Any] = []
+    for name in table.column_names:
+        if name == "subtask_index":
+            continue
+        if name in {LANGUAGE_PERSISTENT, LANGUAGE_EVENTS, "tools"}:
+            continue
+        keep_names.append(name)
+        keep_cols.append(table.column(name))
+
+    persistent_arr = pa.array(per_row_persistent)
+    events_arr = pa.array(per_row_events)
+
+    # NOTE: we deliberately do NOT add a per-row ``tools`` column. The ``say``
+    # tool *schema* is dataset-level metadata and lives in
+    # ``meta/info.json["tools"]`` (written in ``_do_export``), exactly as the
+    # lerobot#3471 pipeline does. Tool *calls* travel per-row inside the
+    # ``tool_calls`` field of the language structs. Any pre-existing ``tools``
+    # column is stripped in the keep-loop above.
+    new_names = keep_names + [LANGUAGE_PERSISTENT, LANGUAGE_EVENTS]
+    new_cols = keep_cols + [persistent_arr, events_arr]
+    return pa.Table.from_arrays(new_cols, names=new_names), n_persistent_total, n_event_total
+
+
+def _materialize_tree(src: Path, dst: Path, *, force_copy: bool) -> None:
+    """Recreate ``src`` under ``dst`` as real files (no symlinks).
+
+    Hardlinks each file when ``force_copy`` is False and the source/target sit
+    on the same filesystem (cheap, self-contained, uploadable); otherwise
+    falls back to a byte copy. The result is always a standalone tree that
+    survives being moved and is uploaded verbatim by ``upload_folder``.
+    """
+
+    def _copy_file(s: str, d: str) -> None:
+        if not force_copy:
+            try:
+                os.link(s, d)
+                return
+            except OSError:
+                pass
+        shutil.copy2(s, d)
+
+    shutil.copytree(src, dst, copy_function=_copy_file)
+
+
+def _do_export(state: DatasetState, output_dir: str | None, copy_videos: bool) -> dict[str, Any]:
+    if output_dir:
+        out_root = Path(output_dir).expanduser().resolve()
+    else:
+        EXPORT_ROOT.mkdir(parents=True, exist_ok=True)
+        name = (state.repo_id or Path(state.root).name or "dataset").replace("/", "__")
+        out_root = EXPORT_ROOT / f"{name}_annotated"
+
+    out_root.mkdir(parents=True, exist_ok=True)
+
+    # Copy meta/
+    src_meta = state.root / "meta"
+    dst_meta = out_root / "meta"
+    if dst_meta.exists():
+        shutil.rmtree(dst_meta)
+    shutil.copytree(src_meta, dst_meta)
+
+    info_path = dst_meta / "info.json"
+    info = json.loads(info_path.read_text())
+    info.setdefault("features", {})
+    info["features"].pop("subtask_index", None)
+    info["features"][LANGUAGE_PERSISTENT] = {"dtype": "language", "shape": [1], "names": None}
+    info["features"][LANGUAGE_EVENTS] = {"dtype": "language", "shape": [1], "names": None}
+    # The ``say`` tool schema is dataset-level metadata, stored at the top of
+    # info.json under "tools" (NOT as a per-frame feature). Mirrors the
+    # lerobot#3471 pipeline's ``_ensure_annotation_metadata_in_info``: merge
+    # additively so any user-declared tools are preserved, and stop emitting
+    # the stray ``tools`` feature older exports added.
+    info["features"].pop("tools", None)
+    existing_tools = info.get("tools") or []
+    tool_names = {
+        (t.get("function") or {}).get("name") for t in existing_tools if isinstance(t, dict)
+    }
+    if SAY_TOOL_SCHEMA["function"]["name"] not in tool_names:
+        info["tools"] = [*existing_tools, SAY_TOOL_SCHEMA]
+    info_path.write_text(json.dumps(info, indent=2))
+
+    # Drop legacy meta files if present
+    for legacy in ("subtasks.parquet", "tasks_high_level.parquet"):
+        p = dst_meta / legacy
+        if p.exists():
+            p.unlink()
+
+    # Make sure data AND videos are downloaded for HF datasets. The export
+    # must be a self-contained, loadable dataset (the writer only rewrites
+    # the parquet shards; videos are carried over untouched), so we pull the
+    # video shards too — otherwise the exported folder is missing the
+    # observation videos and won't load. Mirrors the lerobot#3471 pipeline,
+    # which annotates a full local snapshot in place.
+    data_dir = state.root / "data"
+    data_files = sorted(data_dir.rglob("*.parquet"))
+    if not data_files and state.repo_id:
+        snapshot_download(
+            state.repo_id,
+            repo_type="dataset",
+            revision=state.revision,
+            local_dir=state.root,
+            allow_patterns=["data/**/*.parquet", "videos/**"],
+        )
+        data_files = sorted(data_dir.rglob("*.parquet"))
+    if not data_files:
+        raise HTTPException(status_code=404, detail="No data parquet files found")
+
+    atoms_by_ep = {ep: ann.atoms for ep, ann in state.annotations.items()}
+
+    n_persistent = 0
+    n_events = 0
+    for src_path in data_files:
+        rel_path = src_path.relative_to(state.root)
+        dst_path = out_root / rel_path
+        dst_path.parent.mkdir(parents=True, exist_ok=True)
+        table = pq.read_table(src_path)
+        new_table, np_n, ne_n = _materialize_table(table, atoms_by_ep)
+        n_persistent += np_n
+        n_events += ne_n
+        pq.write_table(new_table, dst_path)
+
+    # Carry over the video shards so the export is self-contained. We
+    # materialize *real* files (hardlink where the filesystem allows it, else
+    # copy) rather than symlinking the source tree: a symlinked ``videos/``
+    # breaks as soon as the folder is moved and is not uploaded by
+    # ``HfApi.upload_folder``, which is exactly the "downloaded dataset isn't
+    # usable" problem. ``copy_videos=True`` forces a full byte copy (used by
+    # the push-to-hub path, where the upload reads the bytes anyway).
+    src_videos = state.root / "videos"
+    dst_videos = out_root / "videos"
+    if src_videos.exists():
+        if dst_videos.exists() or dst_videos.is_symlink():
+            if dst_videos.is_symlink():
+                dst_videos.unlink()
+            else:
+                shutil.rmtree(dst_videos)
+        _materialize_tree(src_videos, dst_videos, force_copy=copy_videos)
+
+    return {"output_dir": str(out_root), "persistent_rows": n_persistent, "event_rows": n_events}
+
+
+# --- FastAPI app --------------------------------------------------------------
+
+app = FastAPI(title="LeRobot dataset visualizer — annotation backend")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/api/health")
+def health() -> JSONResponse:
+    return JSONResponse(
+        {
+            "ok": True,
+            "service": "lerobot-visualizer-annotate",
+            "persistent_styles": sorted(PERSISTENT_STYLES),
+            "event_styles": sorted(EVENT_ONLY_STYLES),
+        }
+    )
+
+
+@app.post("/api/dataset/load")
+def load_dataset(req: LoadRequest) -> JSONResponse:
+    state = _ensure_state(req)
+    return JSONResponse(
+        {
+            "repo_id": state.repo_id,
+            "local_path": state.local_path,
+            "revision": state.revision,
+            "root": str(state.root),
+            "fps": float(state.info.get("fps", 30)),
+            "num_episodes": int(state.episodes_df["episode_index"].nunique()),
+            "persistent_styles": sorted(PERSISTENT_STYLES),
+            "event_styles": sorted(EVENT_ONLY_STYLES),
+        }
+    )
+
+
+@app.get("/api/episodes/{episode_index}/atoms")
+def get_episode_atoms(
+    episode_index: int,
+    repo_id: str | None = None,
+    revision: str | None = None,
+    local_path: str | None = None,
+) -> JSONResponse:
+    state = _ensure_state(DatasetRef(repo_id=repo_id, revision=revision, local_path=local_path))
+    ann = state.annotations.get(episode_index)
+    if ann is None:
+        path = _episode_data_path(state, episode_index)
+        atoms: list[dict[str, Any]] = []
+        if path is not None:
+            try:
+                schema = pq.read_schema(path)
+                columns = ["episode_index"]
+                # Always pull the row timestamp — needed as a fallback for
+                # event rows whose v3.1 struct intentionally omits it.
+                if "timestamp" in schema.names:
+                    columns.append("timestamp")
+                if LANGUAGE_PERSISTENT in schema.names:
+                    columns.append(LANGUAGE_PERSISTENT)
+                if LANGUAGE_EVENTS in schema.names:
+                    columns.append(LANGUAGE_EVENTS)
+                if (
+                    LANGUAGE_PERSISTENT in columns
+                    or LANGUAGE_EVENTS in columns
+                ):
+                    atoms = _extract_existing_atoms_from_table(
+                        pq.read_table(path, columns=columns),
+                        episode_index,
+                    )
+            except Exception as e:  # noqa: BLE001
+                logger.warning("language column read failed for ep %s: %s", episode_index, e)
+        ann = EpisodeAnnotations(atoms=atoms)
+        if atoms:
+            state.annotations[episode_index] = ann
+    return JSONResponse({"episode_index": episode_index, "atoms": ann.atoms})
+
+
+@app.post("/api/episodes/{episode_index}/atoms")
+def set_episode_atoms(episode_index: int, payload: EpisodeAtomsPayload) -> JSONResponse:
+    if episode_index != payload.episode_index:
+        raise HTTPException(status_code=400, detail="episode index mismatch")
+    state = _ensure_state(DatasetRef(repo_id=payload.repo_id, local_path=payload.local_path))
+    atoms = [a.dict() for a in payload.atoms]
+    for atom in atoms:
+        _validate_atom(atom)
+    # Snap event timestamps to exact frame timestamps (matches lerobot#3471).
+    frame_ts = _frame_timestamps(state, episode_index)
+    for atom in atoms:
+        if column_for_style(atom.get("style")) == LANGUAGE_EVENTS and frame_ts:
+            atom["timestamp"] = _snap(float(atom["timestamp"]), frame_ts)
+    state.annotations[episode_index] = EpisodeAnnotations(atoms=atoms)
+    _save_annotations(state)
+    return JSONResponse(
+        {"ok": True, "saved": len(atoms), "path": str(state.annotations_path)}
+    )
+
+
+@app.get("/api/episodes/{episode_index}/frame_timestamps")
+def episode_frame_timestamps(
+    episode_index: int,
+    repo_id: str | None = None,
+    revision: str | None = None,
+    local_path: str | None = None,
+) -> JSONResponse:
+    state = _ensure_state(DatasetRef(repo_id=repo_id, revision=revision, local_path=local_path))
+    ts = _frame_timestamps(state, episode_index)
+    return JSONResponse({"episode_index": episode_index, "timestamps": ts})
+
+
+@app.post("/api/export")
+def export_dataset(req: ExportRequest) -> JSONResponse:
+    state = _ensure_state(req)
+    return JSONResponse(_do_export(state, req.output_dir, req.copy_videos))
+
+
+@app.post("/api/push_to_hub")
+def push_to_hub(req: PushToHubRequest) -> JSONResponse:
+    state = _ensure_state(req)
+    if not state.repo_id and not req.new_repo_id:
+        raise HTTPException(status_code=400, detail="repo_id or new_repo_id required")
+
+    # Ensure data + videos are present locally before exporting.
+    if state.repo_id:
+        snapshot_download(
+            state.repo_id,
+            repo_type="dataset",
+            revision=state.revision,
+            local_dir=state.root,
+            allow_patterns=["data/**/*.parquet", "videos/**/*.mp4"],
+        )
+    export_result = _do_export(state, output_dir=None, copy_videos=True)
+    export_dir = Path(export_result["output_dir"])
+
+    target_repo = state.repo_id if req.push_in_place else req.new_repo_id
+    if not target_repo:
+        raise HTTPException(status_code=400, detail="No target repo")
+
+    api = HfApi(token=req.hf_token)
+    if not req.push_in_place:
+        api.create_repo(
+            repo_id=target_repo,
+            repo_type="dataset",
+            private=req.private,
+            exist_ok=True,
+        )
+    api.upload_folder(
+        folder_path=str(export_dir),
+        repo_id=target_repo,
+        repo_type="dataset",
+        commit_message=req.commit_message,
+    )
+    return JSONResponse(
+        {
+            "ok": True,
+            "repo_id": target_repo,
+            "url": f"https://huggingface.co/datasets/{target_repo}",
+            "message": f"Pushed annotated dataset to {target_repo}",
+        }
+    )

backend/requirements.txt

@@ -0,0 +1,6 @@
+fastapi>=0.110
+uvicorn[standard]>=0.27
+pydantic>=2.5
+pandas>=2.0
+pyarrow>=15
+huggingface_hub>=0.24

src/app/[org]/[dataset]/[episode]/episode-viewer.tsx

@@ -7,6 +7,12 @@ import { SimpleVideosPlayer } from "@/components/simple-videos-player";
 import PlaybackBar from "@/components/playback-bar";
 import { TimeProvider, useTime } from "@/context/time-context";
 import { FlaggedEpisodesProvider } from "@/context/flagged-episodes-context";
+import {
+  AnnotationsProvider,
+  useAnnotations,
+} from "@/context/annotations-context";
+import { AnnotationsPanel } from "@/components/annotations-panel";
+import { AnnotationsTimeline } from "@/components/annotations-timeline";
 import Sidebar from "@/components/side-nav";
 import StatsPanel from "@/components/stats-panel";
 import OverviewPanel from "@/components/overview-panel";
@@ -39,8 +45,25 @@ const FilteringPanel = lazy(() => import("@/components/filtering-panel"));
 // videos start downloading in parallel with the chart bundle.
 const DataRecharts = lazy(() => import("@/components/data-recharts"));
 
+/** Skip global playback / navigation shortcuts while typing in a field. */
+function isKeyboardFocusInsideTextEntry(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable || target.closest('[contenteditable="true"]')) {
+    return true;
+  }
+  const tag = target.tagName;
+  return (
+    tag === "TEXTAREA" ||
+    tag === "SELECT" ||
+    tag === "INPUT" ||
+    tag === "BUTTON" ||
+    (tag === "A" && target.hasAttribute("href"))
+  );
+}
+
 type ActiveTab =
   | "episodes"
+  | "annotations"
   | "statistics"
   | "frames"
   | "insights"
@@ -180,12 +203,35 @@ export default function EpisodeViewer({
   return (
     <TimeProvider duration={data!.duration}>
       <FlaggedEpisodesProvider>
-        <EpisodeViewerInner data={data!} org={org} dataset={dataset} />
+        <AnnotationsProvider>
+          <EpisodeBootstrap data={data!} />
+          <EpisodeViewerInner data={data!} org={org} dataset={dataset} />
+        </AnnotationsProvider>
       </FlaggedEpisodesProvider>
     </TimeProvider>
   );
 }
 
+/** Wires the loaded episode into the AnnotationsProvider. */
+function EpisodeBootstrap({ data }: { data: EpisodeData }) {
+  const { setEpisode } = useAnnotations();
+  useEffect(() => {
+    setEpisode(
+      data.episodeId,
+      { repoId: data.datasetInfo.repoId },
+      data.languageAtoms,
+      data.frameTimestamps,
+    );
+  }, [
+    data.episodeId,
+    data.datasetInfo.repoId,
+    data.languageAtoms,
+    data.frameTimestamps,
+    setEpisode,
+  ]);
+  return null;
+}
+
 function EpisodeViewerInner({
   data,
   org,
@@ -212,8 +258,29 @@ function EpisodeViewerInner({
   const router = useRouter();
   const searchParams = useSearchParams();
 
-  // Tab state & lazy stats
-  const [activeTab, setActiveTab] = useState<ActiveTab>("episodes");
+  // Tab state & lazy stats — read sessionStorage in the initializer so the
+  // correct tab renders on the very first frame (no post-mount flash).
+  // Safe because EpisodeViewerInner only mounts client-side (behind a loading gate).
+  const [activeTab, setActiveTab] = useState<ActiveTab>(() => {
+    if (typeof window !== "undefined") {
+      const stored = sessionStorage.getItem("activeTab");
+      if (
+        stored &&
+        [
+          "episodes",
+          "annotations",
+          "statistics",
+          "frames",
+          "insights",
+          "filtering",
+          "urdf",
+        ].includes(stored)
+      ) {
+        return stored as ActiveTab;
+      }
+    }
+    return "episodes";
+  });
   const isLoading = activeTab === "episodes" && (!videosReady || !chartsReady);
 
   useEffect(() => {
@@ -232,8 +299,16 @@ function EpisodeViewerInner({
     useState<EpisodeFramesData | null>(null);
   const [framesLoading, setFramesLoading] = useState(false);
   const framesLoadedRef = useRef(false);
-  const [framesFlaggedOnly, setFramesFlaggedOnly] = useState(false);
-  const [sidebarFlaggedOnly, setSidebarFlaggedOnly] = useState(false);
+  const [framesFlaggedOnly, setFramesFlaggedOnly] = useState(() =>
+    typeof window !== "undefined"
+      ? sessionStorage.getItem("framesFlaggedOnly") === "true"
+      : false,
+  );
+  const [sidebarFlaggedOnly, setSidebarFlaggedOnly] = useState(() =>
+    typeof window !== "undefined"
+      ? sessionStorage.getItem("sidebarFlaggedOnly") === "true"
+      : false,
+  );
   const [crossEpData, setCrossEpData] =
     useState<CrossEpisodeVarianceData | null>(null);
   const [insightsLoading, setInsightsLoading] = useState(false);
@@ -267,28 +342,6 @@ function EpisodeViewerInner({
     }
   }, [datasetInfo.robot_type, datasetInfo.codebase_version]);
 
-  // Hydrate UI state from sessionStorage after mount (avoids SSR/client mismatch)
-  useEffect(() => {
-    const stored = sessionStorage.getItem("activeTab");
-    if (
-      stored &&
-      [
-        "episodes",
-        "statistics",
-        "frames",
-        "insights",
-        "filtering",
-        "urdf",
-      ].includes(stored)
-    ) {
-      setActiveTab(stored as ActiveTab);
-    }
-    if (sessionStorage.getItem("framesFlaggedOnly") === "true")
-      setFramesFlaggedOnly(true);
-    if (sessionStorage.getItem("sidebarFlaggedOnly") === "true")
-      setSidebarFlaggedOnly(true);
-  }, []);
-
   // Persist UI state across episode navigations. One effect instead of
   // three near-identical writes — fewer commit hooks per render and the
   // intent (mirror three primitives to sessionStorage) reads as one unit.
@@ -483,8 +536,10 @@ function EpisodeViewerInner({
     const onKeyDown = (e: KeyboardEvent) => {
       const { key } = e;
       const s = keyStateRef.current;
+      const inTextEntry = isKeyboardFocusInsideTextEntry(e.target);
 
       if (key === " ") {
+        if (inTextEntry) return;
         e.preventDefault();
         if (s.activeTab === "urdf") {
           urdfPlayToggleRef.current?.();
@@ -492,6 +547,7 @@ function EpisodeViewerInner({
           setIsPlaying((prev: boolean) => !prev);
         }
       } else if (key === "ArrowDown" || key === "ArrowUp") {
+        if (inTextEntry) return;
         e.preventDefault();
         if (s.activeTab === "urdf") {
           const nextEp =
@@ -550,6 +606,11 @@ function EpisodeViewerInner({
       {/* Top tab bar */}
       <div className="flex items-center border-b border-white/5 bg-[var(--surface-0)] shrink-0">
         {renderTab("episodes", "Episodes")}
+        {renderTab(
+          "annotations",
+          "Annotations",
+          "Edit subtask / plan / memory / interjection / VQA atoms (lerobot v3.1 schema)",
+        )}
         {hasURDFSupport(datasetInfo.robot_type) &&
           datasetInfo.codebase_version >= "v3.0" &&
           renderTab("urdf", "3D Replay")}
@@ -570,7 +631,9 @@ function EpisodeViewerInner({
       {/* Body: sidebar + content */}
       <div className="flex flex-1 min-h-0">
         {/* Sidebar — on Episodes and 3D Replay tabs */}
-        {(activeTab === "episodes" || activeTab === "urdf") && (
+        {(activeTab === "episodes" ||
+          activeTab === "annotations" ||
+          activeTab === "urdf") && (
           <Sidebar
             datasetInfo={datasetInfo}
             paginatedEpisodes={paginatedEpisodes}
@@ -587,7 +650,9 @@ function EpisodeViewerInner({
                     setUrdfEpisode(ep);
                     urdfChangerRef.current?.(ep);
                   }
-                : undefined
+                : activeTab === "annotations"
+                  ? (ep) => router.push(`./episode_${ep}`)
+                  : undefined
             }
           />
         )}
@@ -668,6 +733,45 @@ function EpisodeViewerInner({
             </>
           )}
 
+          {activeTab === "annotations" && (
+            <div className="annotations-skin flex flex-col gap-4">
+              <div className="flex items-center gap-3">
+                <p className="text-base font-medium text-slate-200 truncate">
+                  {datasetInfo.repoId}
+                </p>
+                <p className="text-[10px] uppercase tracking-wide text-slate-500 tabular">
+                  Episode · {episodeId}
+                </p>
+              </div>
+              {videosInfo.length > 0 && (
+                <SimpleVideosPlayer
+                  videosInfo={videosInfo}
+                  onVideosReady={() => setVideosReady(true)}
+                />
+              )}
+              <div className="grounding-intro">
+                <span className="section-kicker">Grounded VQA</span>
+                <ul>
+                  <li>
+                    Draw directly on the active video to create visual
+                    questions. Drag for a bounding box, click for a point. The
+                    camera is detected from the video you draw on.
+                  </li>
+                  <li>
+                    Drag on any video to add a bbox question. Click any video to
+                    add a keypoint question. Confirm the popup with <kbd>↵</kbd>
+                    , or cancel with <kbd>Esc</kbd>.
+                  </li>
+                </ul>
+              </div>
+              <PlaybackBar />
+              <AnnotationsTimeline duration={data.duration} />
+              <AnnotationsPanel
+                cameraKeys={videosInfo.map((v) => v.filename)}
+              />
+            </div>
+          )}
+
           {activeTab === "statistics" && (
             <StatsPanel
               datasetInfo={datasetInfo}

src/app/[org]/[dataset]/[episode]/fetch-data.ts

@@ -84,6 +84,20 @@ export type EpisodeData = {
   ignoredColumns: string[];
   duration: number;
   task?: string;
+  /**
+   * v3.1 language atoms read from `language_persistent` and `language_events`
+   * (lerobot#3467). Empty when the dataset hasn't been annotated yet.
+   * The annotations panel uses this to seed its editor state when no
+   * annotation backend is running.
+   */
+  languageAtoms?: import("@/types/language.types").LanguageAtom[];
+  /**
+   * Sorted source-frame timestamps from the data parquet, in seconds. Used by
+   * the annotations editor to snap atom timestamps to exact frame times —
+   * avoiding sub-frame drift from a throttled `currentTime` and keeping
+   * events compatible with the writer in lerobot#3471.
+   */
+  frameTimestamps?: number[];
 };
 
 type EpisodeMetadataV3 = {
@@ -708,8 +722,14 @@ async function getEpisodeDataV3(
   );
 
   // Load episode data for charts
-  const { chartDataGroups, flatChartData, ignoredColumns, task } =
-    await loadEpisodeDataV3(repoId, version, info, episodeMetadata);
+  const {
+    chartDataGroups,
+    flatChartData,
+    ignoredColumns,
+    task,
+    languageAtoms,
+    frameTimestamps,
+  } = await loadEpisodeDataV3(repoId, version, info, episodeMetadata);
 
   const duration = episodeMetadata.length
     ? episodeMetadata.length / info.fps
@@ -725,6 +745,8 @@ async function getEpisodeDataV3(
     ignoredColumns,
     duration,
     task,
+    languageAtoms,
+    frameTimestamps,
   };
 }
 
@@ -739,6 +761,8 @@ async function loadEpisodeDataV3(
   flatChartData: Record<string, number>[];
   ignoredColumns: string[];
   task?: string;
+  languageAtoms?: import("@/types/language.types").LanguageAtom[];
+  frameTimestamps?: number[];
 }> {
   // Build data file path using chunk and file indices
   const dataChunkIndex = bigIntToNumber(episodeMetadata.data_chunk_index, 0);
@@ -756,6 +780,10 @@ async function loadEpisodeDataV3(
         "language_instruction",
         "language_instruction_2",
         "language_instruction_3",
+        // v3.1 language schema (lerobot#3467) — list<struct{...}> columns
+        // that the annotations panel renders / edits.
+        "language_persistent",
+        "language_events",
         ...Object.entries(info.features)
           .filter(([, feature]) => {
             const dtype = feature.dtype.toLowerCase();
@@ -815,6 +843,20 @@ async function loadEpisodeDataV3(
       episodeRows = await readParquetAsObjects(parquetFile, v3DataColumns);
     }
 
+    // Extract frame timestamps from the *full* (non-sampled) row set so the
+    // annotations editor can snap to the exact frame the user is on.
+    const frameTimestamps = episodeRows
+      .map((r) => {
+        const t = r.timestamp;
+        return typeof t === "number"
+          ? t
+          : typeof t === "bigint"
+            ? Number(t)
+            : Number.NaN;
+      })
+      .filter((t) => Number.isFinite(t))
+      .sort((a, b) => a - b);
+
     const episodeData = evenlySampleArray(episodeRows, MAX_EPISODE_POINTS);
 
     if (episodeData.length === 0) {
@@ -823,6 +865,8 @@ async function loadEpisodeDataV3(
         flatChartData: [],
         ignoredColumns: [],
         task: undefined,
+        languageAtoms: extractLanguageAtoms(episodeRows),
+        frameTimestamps,
       };
     }
 
@@ -905,7 +949,14 @@ async function loadEpisodeDataV3(
       }
     }
 
-    return { chartDataGroups, flatChartData, ignoredColumns, task };
+    return {
+      chartDataGroups,
+      flatChartData,
+      ignoredColumns,
+      task,
+      languageAtoms: extractLanguageAtoms(episodeRows),
+      frameTimestamps,
+    };
   } catch {
     return {
       chartDataGroups: [],
@@ -916,6 +967,87 @@ async function loadEpisodeDataV3(
   }
 }
 
+/**
+ * Extract `LanguageAtom`s from a list of v3.1 parquet rows.
+ *
+ * Each row may carry two arrays:
+ *   - `language_persistent`: broadcast — same content on every row in the
+ *     episode. We sample row 0 (skipping nulls/empties).
+ *   - `language_events`: per-row, mostly empty. We collect every event whose
+ *     row's `timestamp` falls within the episode.
+ *
+ * Hyparquet decodes `list<struct<...>>` to `Array<Record<string, unknown>>`.
+ * We coerce loosely-typed values to the canonical `LanguageAtom` shape and
+ * drop rows that don't validate.
+ */
+function extractLanguageAtoms(
+  episodeRows: Record<string, unknown>[],
+): import("@/types/language.types").LanguageAtom[] {
+  if (!episodeRows.length) return [];
+  type LanguageAtom = import("@/types/language.types").LanguageAtom;
+  const atoms: LanguageAtom[] = [];
+  const seenPersistent: Set<string> = new Set(); // dedupe broadcast copies
+
+  const coerce = (raw: unknown, fallbackTs?: number): LanguageAtom | null => {
+    if (!raw || typeof raw !== "object") return null;
+    const r = raw as Record<string, unknown>;
+    const role =
+      typeof r.role === "string" ? (r.role as LanguageAtom["role"]) : null;
+    if (!role) return null;
+    const style =
+      typeof r.style === "string" ? (r.style as LanguageAtom["style"]) : null;
+    const content = typeof r.content === "string" ? r.content : null;
+    const timestamp =
+      typeof r.timestamp === "number"
+        ? r.timestamp
+        : typeof r.timestamp === "bigint"
+          ? Number(r.timestamp)
+          : (fallbackTs ?? 0);
+    const tool_calls = Array.isArray(r.tool_calls)
+      ? (r.tool_calls as LanguageAtom["tool_calls"])
+      : null;
+    const camera =
+      typeof r.camera === "string" && r.camera.length > 0 ? r.camera : null;
+    return { role, content, style, timestamp, camera, tool_calls };
+  };
+
+  // Persistent slice: read once from the first row that has a non-empty list.
+  for (const row of episodeRows) {
+    const list = row["language_persistent"];
+    if (Array.isArray(list) && list.length > 0) {
+      for (const raw of list) {
+        const atom = coerce(raw);
+        if (!atom) continue;
+        const key = `${atom.style}|${atom.role}|${atom.timestamp}|${atom.camera ?? ""}|${atom.content}`;
+        if (seenPersistent.has(key)) continue;
+        seenPersistent.add(key);
+        atoms.push(atom);
+      }
+      break;
+    }
+  }
+
+  // Event slice: every non-empty per-row list contributes its rows. Each
+  // event's timestamp should already match its frame timestamp; we use the
+  // row timestamp as a fallback if it's missing.
+  for (const row of episodeRows) {
+    const list = row["language_events"];
+    if (!Array.isArray(list) || list.length === 0) continue;
+    const rowTs =
+      typeof row.timestamp === "number"
+        ? row.timestamp
+        : typeof row.timestamp === "bigint"
+          ? Number(row.timestamp)
+          : 0;
+    for (const raw of list) {
+      const atom = coerce(raw, rowTs);
+      if (atom) atoms.push(atom);
+    }
+  }
+
+  return atoms;
+}
+
 // Process episode data for charts (v3.0 compatible)
 function processEpisodeDataForCharts(
   episodeData: Record<string, unknown>[],

src/components/annotations-panel.tsx

@@ -0,0 +1,1021 @@
+"use client";
+
+import "./annotations-skin.css";
+
+/**
+ * Editor UI for v3.1 language atoms.
+ *
+ * Three vertical sections:
+ *   1. Inline quick-add bar above the timeline (style picker + label + Add).
+ *   2. Annotations timeline (in `annotations-timeline.tsx`).
+ *   3. Workspace below the timeline:
+ *        - Left rail: full atom list grouped by style; click to select.
+ *        - Right pane: editor for the selected atom (or empty state).
+ *
+ * Bbox / keypoint VQA atoms are still added through the canvas overlay's
+ * quick-label popup; the inline quick-add covers subtask / plan / memory /
+ * interjection / speech / count / attribute / spatial.
+ */
+
+import React, { useMemo, useState } from "react";
+import { useTime } from "../context/time-context";
+import { useAnnotations } from "../context/annotations-context";
+import {
+  buildSpeechAtom,
+  classifyVqa,
+  isSpeechAtom,
+  parseVqaAnswer,
+  speechText,
+  type LanguageAtom,
+} from "../types/language.types";
+import {
+  exportDataset as apiExport,
+  isAnnotateBackendEnabled,
+} from "../utils/annotationsClient";
+
+interface Props {
+  cameraKeys: string[];
+}
+
+function fmtTime(s: number): string {
+  return s.toFixed(3) + "s";
+}
+
+function StylePill({ style }: { style: string | null }) {
+  const cls = style ?? "speech";
+  return <span className={`style-pill ${cls}`}>{style ?? "speech"}</span>;
+}
+
+/**
+ * Highlight a row when its timestamp is within ~half a frame of currentTime.
+ */
+function isActiveAt(ts: number, currentTime: number, fps = 30): boolean {
+  return Math.abs(ts - currentTime) < 0.5 / fps;
+}
+
+type QuickAddKind =
+  | "task_aug"
+  | "subtask"
+  | "plan"
+  | "memory"
+  | "interjection"
+  | "speech"
+  | "count"
+  | "attribute"
+  | "spatial";
+
+interface QuickAddField {
+  name: string;
+  placeholder: string;
+  type?: "text" | "number";
+  width?: string;
+  grow?: boolean;
+}
+
+interface QuickAddBuildCtx {
+  ts: number;
+  vqaCamera: string | null;
+}
+
+interface QuickAddDef {
+  kind: QuickAddKind;
+  label: string;
+  /** When true, the displayed timestamp is 0 (atom is pinned to episode start). */
+  atEpisodeStart?: boolean;
+  fields: QuickAddField[];
+  build: (
+    values: Record<string, string>,
+    ctx: QuickAddBuildCtx,
+  ) => LanguageAtom[] | null;
+}
+
+// Each text-style atom kind (and the simpler VQA shapes) is one entry: how
+// it appears in the dropdown, what fields the user fills, and how those
+// values map to one or two language atoms.
+const QUICK_ADD_DEFS: QuickAddDef[] = [
+  {
+    kind: "task_aug",
+    label: "task augmentation",
+    atEpisodeStart: true,
+    fields: [
+      {
+        name: "label",
+        placeholder: "pick up the blue cube and place it in the green box",
+        grow: true,
+      },
+    ],
+    build: ({ label }) => {
+      const text = label.trim();
+      if (!text) return null;
+      return [
+        {
+          role: "user",
+          content: text,
+          style: "task_aug",
+          timestamp: 0,
+          camera: null,
+          tool_calls: null,
+        },
+      ];
+    },
+  },
+  {
+    kind: "subtask",
+    label: "subtask",
+    fields: [
+      {
+        name: "label",
+        placeholder: "grasp the handle of the sponge",
+        grow: true,
+      },
+    ],
+    build: ({ label }, { ts }) => {
+      const text = label.trim();
+      if (!text) return null;
+      return [
+        {
+          role: "assistant",
+          content: text,
+          style: "subtask",
+          timestamp: ts,
+          camera: null,
+          tool_calls: null,
+        },
+      ];
+    },
+  },
+  {
+    kind: "plan",
+    label: "plan",
+    fields: [
+      {
+        name: "label",
+        placeholder: "1. grab sponge / 2. wipe / 3. tidy",
+        grow: true,
+      },
+    ],
+    build: ({ label }, { ts }) => {
+      const text = label.trim();
+      if (!text) return null;
+      return [
+        {
+          role: "assistant",
+          content: text,
+          style: "plan",
+          timestamp: ts,
+          camera: null,
+          tool_calls: null,
+        },
+      ];
+    },
+  },
+  {
+    kind: "memory",
+    label: "memory",
+    fields: [
+      {
+        name: "label",
+        placeholder: "sponge picked up; counter still dirty",
+        grow: true,
+      },
+    ],
+    build: ({ label }, { ts }) => {
+      const text = label.trim();
+      if (!text) return null;
+      return [
+        {
+          role: "assistant",
+          content: text,
+          style: "memory",
+          timestamp: ts,
+          camera: null,
+          tool_calls: null,
+        },
+      ];
+    },
+  },
+  {
+    kind: "interjection",
+    label: "interjection (user)",
+    fields: [
+      {
+        name: "label",
+        placeholder: "user: actually skip the wipe…",
+        grow: true,
+      },
+    ],
+    build: ({ label }, { ts }) => {
+      const text = label.trim();
+      if (!text) return null;
+      return [
+        {
+          role: "user",
+          content: text,
+          style: "interjection",
+          timestamp: ts,
+          camera: null,
+          tool_calls: null,
+        },
+      ];
+    },
+  },
+  {
+    kind: "speech",
+    label: "speech (robot say)",
+    fields: [
+      {
+        name: "label",
+        placeholder: "robot say: Got it, skipping the wipe.",
+        grow: true,
+      },
+    ],
+    build: ({ label }, { ts }) => {
+      const text = label.trim();
+      if (!text) return null;
+      return [buildSpeechAtom(ts, text)];
+    },
+  },
+  {
+    kind: "count",
+    label: "vqa: count",
+    fields: [
+      { name: "label", placeholder: "object label (e.g. cup)", grow: true },
+      { name: "count", placeholder: "count", type: "number", width: "80px" },
+    ],
+    build: ({ label, count }, { ts, vqaCamera }) => {
+      const text = label.trim();
+      if (!text || !count) return null;
+      return [
+        {
+          role: "user",
+          content: `How many ${text}?`,
+          style: "vqa",
+          timestamp: ts,
+          camera: vqaCamera,
+          tool_calls: null,
+        },
+        {
+          role: "assistant",
+          content: JSON.stringify({ label: text, count: Number(count) }),
+          style: "vqa",
+          timestamp: ts,
+          camera: vqaCamera,
+          tool_calls: null,
+        },
+      ];
+    },
+  },
+  {
+    kind: "attribute",
+    label: "vqa: attribute",
+    fields: [
+      { name: "label", placeholder: "label", width: "120px" },
+      { name: "attribute", placeholder: "attribute (color)", width: "120px" },
+      { name: "value", placeholder: "value (red)", grow: true },
+    ],
+    build: ({ label, attribute, value }, { ts, vqaCamera }) => {
+      const text = label.trim();
+      if (!text || !attribute || !value) return null;
+      return [
+        {
+          role: "user",
+          content: `What ${attribute} is the ${text}?`,
+          style: "vqa",
+          timestamp: ts,
+          camera: vqaCamera,
+          tool_calls: null,
+        },
+        {
+          role: "assistant",
+          content: JSON.stringify({ label: text, attribute, value }),
+          style: "vqa",
+          timestamp: ts,
+          camera: vqaCamera,
+          tool_calls: null,
+        },
+      ];
+    },
+  },
+  {
+    kind: "spatial",
+    label: "vqa: spatial relation",
+    fields: [
+      { name: "subject", placeholder: "subject", width: "100px" },
+      { name: "relation", placeholder: "relation (right_of)", width: "130px" },
+      { name: "object", placeholder: "object", grow: true },
+    ],
+    build: ({ subject, relation, object }, { ts, vqaCamera }) => {
+      if (!subject || !relation || !object) return null;
+      return [
+        {
+          role: "user",
+          content: `Where is the ${subject} relative to the ${object}?`,
+          style: "vqa",
+          timestamp: ts,
+          camera: vqaCamera,
+          tool_calls: null,
+        },
+        {
+          role: "assistant",
+          content: JSON.stringify({ subject, relation, object }),
+          style: "vqa",
+          timestamp: ts,
+          camera: vqaCamera,
+          tool_calls: null,
+        },
+      ];
+    },
+  },
+];
+
+const QUICK_ADD_DEFS_BY_KIND: Record<QuickAddKind, QuickAddDef> =
+  QUICK_ADD_DEFS.reduce(
+    (acc, def) => {
+      acc[def.kind] = def;
+      return acc;
+    },
+    {} as Record<QuickAddKind, QuickAddDef>,
+  );
+
+interface RailGroupDef {
+  key: string;
+  title: string;
+  dotClass: string;
+  // Which v3.1 language column this style is written to. Used to group the
+  // rail under "Persistent" vs "Events" headers so it's clear at a glance
+  // that task_aug / subtask / plan / memory broadcast across the whole
+  // episode (language_persistent) while interjection / speech / vqa fire on
+  // a single frame (language_events). Mirrors columnForStyle() exactly.
+  column: "persistent" | "events";
+  match: (
+    atom: LanguageAtom,
+    otherCamera: (a: LanguageAtom) => boolean,
+  ) => boolean;
+  label: (
+    atom: LanguageAtom,
+    helpers: {
+      activeCamera: string | null;
+      firstLine: (s: string | null) => string;
+    },
+  ) => string;
+}
+
+const RAIL_GROUPS: RailGroupDef[] = [
+  {
+    key: "task_aug",
+    title: "task aug",
+    dotClass: "dot-task-aug",
+    column: "persistent",
+    match: (a) => a.style === "task_aug",
+    label: (a) => a.content || "(empty)",
+  },
+  {
+    key: "subtask",
+    title: "subtask",
+    dotClass: "dot-subtask",
+    column: "persistent",
+    match: (a) => a.style === "subtask",
+    label: (a) => a.content || "(empty)",
+  },
+  {
+    key: "plan",
+    title: "plan",
+    dotClass: "dot-plan",
+    column: "persistent",
+    match: (a) => a.style === "plan",
+    label: (a, { firstLine }) => firstLine(a.content),
+  },
+  {
+    key: "memory",
+    title: "memory",
+    dotClass: "dot-memory",
+    column: "persistent",
+    match: (a) => a.style === "memory",
+    label: (a, { firstLine }) => firstLine(a.content),
+  },
+  {
+    key: "interjection",
+    title: "interjection",
+    dotClass: "dot-interjection",
+    column: "events",
+    match: (a) => a.style === "interjection",
+    label: (a) => a.content || "(empty)",
+  },
+  {
+    key: "speech",
+    title: "speech",
+    dotClass: "dot-speech",
+    column: "events",
+    match: (a) => isSpeechAtom(a),
+    label: (a) => speechText(a) || "(empty)",
+  },
+  {
+    key: "vqa",
+    title: "vqa",
+    dotClass: "dot-vqa",
+    column: "events",
+    match: (a, otherCamera) => a.style === "vqa" && !otherCamera(a),
+    label: (a, { activeCamera }) => {
+      const role = a.role === "user" ? "Q" : "A";
+      const t = a.content || "";
+      const cameraSuffix =
+        a.camera && a.camera !== activeCamera ? `  [${a.camera}]` : "";
+      return `${role}: ${t.slice(0, 60)}${t.length > 60 ? "…" : ""}${cameraSuffix}`;
+    },
+  },
+];
+
+function useJump(): (ts: number) => void {
+  const { seek, setIsPlaying } = useTime();
+  return React.useCallback(
+    (ts: number) => {
+      seek(ts, "external");
+      setIsPlaying(false);
+    },
+    [seek, setIsPlaying],
+  );
+}
+
+export const AnnotationsPanel: React.FC<Props> = ({ cameraKeys }) => {
+  const {
+    atoms,
+    addAtoms,
+    updateAtom,
+    deleteAtom,
+    snap,
+    save,
+    saving,
+    dirty,
+    backendEnabled,
+    activeCamera,
+    setActiveCamera,
+    setDrawMode,
+    selectedIdx,
+    selectAtom,
+    ident,
+  } = useAnnotations();
+  const { currentTime } = useTime();
+
+  // ============ Inline quick-add state ============
+  const [qaKind, setQaKind] = useState<QuickAddKind>("subtask");
+  const [qaValues, setQaValues] = useState<Record<string, string>>({});
+  const [exportStatus, setExportStatus] = useState<string | null>(null);
+  const qaDef = QUICK_ADD_DEFS_BY_KIND[qaKind];
+
+  // Initialize active camera once cameras arrive.
+  React.useEffect(() => {
+    if (!activeCamera && cameraKeys.length > 0) setActiveCamera(cameraKeys[0]);
+  }, [activeCamera, cameraKeys, setActiveCamera]);
+
+  // The Annotations tab keeps the canvas overlay in "auto" mode the whole
+  // time — drag = bbox, click = keypoint.
+  React.useEffect(() => {
+    setDrawMode("auto");
+    return () => setDrawMode("off");
+  }, [setDrawMode]);
+
+  // ============ Atom grouping for the rail ============
+  // The rail shows one section per atom-kind. Each kind is a single config
+  // entry: how to detect atoms in this kind, and how to label them in the row.
+  // VQA filters out other-camera answers when the dataset has multiple
+  // cameras so the rail mirrors the active video.
+  const groups = useMemo(() => {
+    const firstLine = (s: string | null) =>
+      (s || "").split("\n")[0] || "(empty)";
+    const otherCamera = (a: LanguageAtom): boolean =>
+      !!activeCamera &&
+      cameraKeys.length > 1 &&
+      a.camera != null &&
+      a.camera !== activeCamera;
+    return RAIL_GROUPS.map((def) => {
+      const entries = atoms
+        .map((atom, idx) => ({ atom, idx }))
+        .filter(({ atom }) => def.match(atom, otherCamera))
+        .map(({ atom, idx }) => ({
+          atom,
+          idx,
+          label: def.label(atom, { activeCamera, firstLine }),
+        }))
+        .sort((a, b) => a.atom.timestamp - b.atom.timestamp);
+      return { def, entries };
+    });
+  }, [atoms, activeCamera, cameraKeys.length]);
+
+  // ============ Quick-add handler ============
+  // VQA quick-adds inherit the active camera so per-camera filtering shows
+  // them in the right rail / overlay. Non-VQA atoms stay camera-agnostic
+  // (the def's `build` ignores `vqaCamera` for those).
+  const handleQuickAdd = () => {
+    const ts = snap(currentTime);
+    const vqaCamera = activeCamera ?? cameraKeys[0] ?? null;
+    const newAtoms = qaDef.build(qaValues, { ts, vqaCamera });
+    if (!newAtoms || !newAtoms.length) return;
+    addAtoms(newAtoms);
+    // Select the freshly added atom (last one added) so the editor opens for it.
+    selectAtom(atoms.length + newAtoms.length - 1);
+    setQaValues({});
+  };
+
+  // ============ Save / export ============
+  const handleSave = async () => {
+    const r = await save();
+    if (!r.ok) {
+      setExportStatus(`Save failed: ${r.error || "unknown"}`);
+    } else {
+      setExportStatus(
+        r.path
+          ? `Saved episode to ${r.path}`
+          : "Saved episode (backend did not report a path — update/restart backend/app.py).",
+      );
+    }
+  };
+
+  const handleSaveDataset = async () => {
+    if (!isAnnotateBackendEnabled()) {
+      setExportStatus(
+        "Backend not configured. Set NEXT_PUBLIC_ANNOTATE_BACKEND_URL and run backend/app.py.",
+      );
+      return;
+    }
+    setExportStatus("Saving dataset…");
+    try {
+      const r = await apiExport(ident);
+      setExportStatus(
+        `Saved dataset to ${r.output_dir} (persistent: ${r.persistent_rows}, events: ${r.event_rows}).`,
+      );
+    } catch (e) {
+      setExportStatus(
+        `Save dataset failed: ${e instanceof Error ? e.message : String(e)}`,
+      );
+    }
+  };
+
+  const selectedAtom =
+    selectedIdx != null && selectedIdx >= 0 && selectedIdx < atoms.length
+      ? atoms[selectedIdx]
+      : null;
+
+  // ============ Render ============
+  return (
+    <div className="annotation-workbench">
+      <div className="annotation-actionbar">
+        <div>
+          <h3>
+            Language annotations
+            {dirty && <span className="dirty-pill">unsaved</span>}
+          </h3>
+          <p>
+            Select an atom from the timeline or list, then edit it in the
+            inspector.
+          </p>
+        </div>
+        <div className="actionbar-actions">
+          {!backendEnabled && (
+            <span className="backend-offline">
+              backend offline — edits saved to sessionStorage only
+            </span>
+          )}
+          <button
+            disabled={saving || !dirty}
+            onClick={handleSave}
+            className="text-xs h-7 px-3 rounded border border-cyan-500/40 bg-cyan-500/10 text-cyan-200 hover:bg-cyan-500/20 disabled:opacity-40"
+          >
+            {saving ? "Saving…" : "Save episode"}
+          </button>
+          <button
+            disabled={!backendEnabled}
+            onClick={handleSaveDataset}
+            className="text-xs h-7 px-3 rounded border border-emerald-500/40 bg-emerald-500/10 text-emerald-200 hover:bg-emerald-500/20 disabled:opacity-40"
+          >
+            Save dataset
+          </button>
+        </div>
+      </div>
+
+      {exportStatus && <div className="save-status">{exportStatus}</div>}
+
+      <section className="annotation-composer">
+        <div className="composer-copy">
+          <span className="section-kicker">Add text annotation</span>
+          <p>
+            Adds task phrasing, subtask, plan, memory, speech, or non-spatial
+            VQA atoms. Task phrasings are saved at episode start.
+          </p>
+        </div>
+        <div className="quick-add">
+          <span className="ts-pill">
+            t = {qaDef.atEpisodeStart ? fmtTime(0) : fmtTime(currentTime)}
+          </span>
+          <select
+            value={qaKind}
+            onChange={(e) => {
+              setQaKind(e.target.value as QuickAddKind);
+              setQaValues({});
+            }}
+          >
+            {QUICK_ADD_DEFS.map((d) => (
+              <option key={d.kind} value={d.kind}>
+                {d.label}
+              </option>
+            ))}
+          </select>
+          {qaDef.fields.map((f, i) => (
+            <input
+              key={f.name}
+              type={f.type === "number" ? "number" : "text"}
+              placeholder={f.placeholder}
+              className={f.grow ? "grow" : undefined}
+              style={f.width ? { width: f.width } : undefined}
+              value={qaValues[f.name] ?? ""}
+              onChange={(e) =>
+                setQaValues((v) => ({ ...v, [f.name]: e.target.value }))
+              }
+              onKeyDown={
+                i === qaDef.fields.length - 1
+                  ? (e) => e.key === "Enter" && handleQuickAdd()
+                  : undefined
+              }
+            />
+          ))}
+          <button className="add-btn" onClick={handleQuickAdd}>
+            + Add at frame
+          </button>
+        </div>
+      </section>
+
+      <div className="workspace inspector-workspace">
+        <div className="rail annotation-list">
+          <div className="list-head">
+            <div>
+              <span className="section-kicker">Annotations</span>
+              <p>{atoms.length} atoms in this episode</p>
+            </div>
+            <span className="ts-pill">{fmtTime(currentTime)}</span>
+          </div>
+          {atoms.length === 0 && (
+            <div className="rail-empty">
+              No annotations yet.
+              <br />
+              Add text above or draw on the active video.
+            </div>
+          )}
+          {(["persistent", "events"] as const).map((column) => {
+            const colGroups = groups.filter(({ def }) => def.column === column);
+            const total = colGroups.reduce(
+              (n, { entries }) => n + entries.length,
+              0,
+            );
+            if (total === 0) return null;
+            return (
+              <div className="rail-column" key={column}>
+                <div className={`rail-column-head ${column}`}>
+                  <span className="rail-column-title">
+                    {column === "persistent" ? "Persistent" : "Events"}
+                  </span>
+                  <span className="rail-column-sub">
+                    {column === "persistent"
+                      ? "language_persistent · broadcast across every frame"
+                      : "language_events · fire on a single frame"}
+                  </span>
+                </div>
+                {colGroups.map(({ def, entries }) => (
+                  <RailGroup
+                    key={def.key}
+                    title={def.title}
+                    dotClass={def.dotClass}
+                    entries={entries}
+                    currentTime={currentTime}
+                  />
+                ))}
+              </div>
+            );
+          })}
+        </div>
+
+        <div className="editor inspector">
+          {selectedAtom == null ? (
+            <div className="editor-empty">
+              <span className="section-kicker">Inspector</span>
+              <p>
+                Select an annotation from the list or timeline, or draw a new
+                bbox/keypoint on the video.
+              </p>
+            </div>
+          ) : (
+            <AtomEditor
+              atom={selectedAtom}
+              cameraKeys={cameraKeys}
+              onChange={(updates) => updateAtom(selectedIdx as number, updates)}
+              onDelete={() => deleteAtom(selectedAtom)}
+            />
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Rail group — one row per atom, click selects.
+// ---------------------------------------------------------------------------
+
+const RailGroup: React.FC<{
+  title: string;
+  dotClass: string;
+  entries: { atom: LanguageAtom; idx: number; label: string }[];
+  currentTime: number;
+}> = ({ title, dotClass, entries, currentTime }) => {
+  const { selectedIdx, selectAtom } = useAnnotations();
+  const jump = useJump();
+  if (entries.length === 0) return null;
+  return (
+    <div className="rail-group">
+      <div className="rail-group-head">
+        <span style={{ display: "inline-flex", alignItems: "center", gap: 6 }}>
+          <span className={`style-dot ${dotClass}`} />
+          {title}
+        </span>
+        <span className="count">{entries.length}</span>
+      </div>
+      {entries.map(({ atom, idx, label }) => {
+        const sel = idx === selectedIdx;
+        const active = isActiveAt(atom.timestamp, currentTime);
+        return (
+          <div
+            key={idx}
+            className={`rail-row ${sel ? "selected" : ""} ${active ? "active-now" : ""}`}
+            onClick={() => {
+              selectAtom(idx);
+              jump(atom.timestamp);
+            }}
+          >
+            <span className="ts">{fmtTime(atom.timestamp)}</span>
+            <span className="body">{label}</span>
+          </div>
+        );
+      })}
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// AtomEditor — form for the currently selected atom.
+// ---------------------------------------------------------------------------
+
+const AtomEditor: React.FC<{
+  atom: LanguageAtom;
+  cameraKeys: string[];
+  onChange: (updates: Partial<LanguageAtom>) => void;
+  onDelete: () => void;
+}> = ({ atom, cameraKeys, onChange, onDelete }) => {
+  const jump = useJump();
+  const { snap } = useAnnotations();
+  const isSpeech = isSpeechAtom(atom);
+  const cameraLabel = atom.camera ?? "all cameras";
+  const roleLabel = isSpeech ? "speech" : atom.role;
+  const [timestampDraft, setTimestampDraft] = useState(() =>
+    String(atom.timestamp),
+  );
+
+  React.useEffect(() => {
+    setTimestampDraft(String(atom.timestamp));
+  }, [atom.timestamp]);
+
+  const commitTimestamp = React.useCallback(
+    (raw = timestampDraft) => {
+      const next = Number(raw);
+      if (!Number.isFinite(next) || next < 0) {
+        setTimestampDraft(String(atom.timestamp));
+        return;
+      }
+      onChange({ timestamp: next });
+      setTimestampDraft(String(next));
+    },
+    [atom.timestamp, onChange, timestampDraft],
+  );
+
+  const commitSnappedTimestamp = () => {
+    const parsed = Number(timestampDraft);
+    const next = snap(Number.isFinite(parsed) ? parsed : atom.timestamp);
+    onChange({ timestamp: next });
+    setTimestampDraft(String(next));
+  };
+
+  return (
+    <div className="inspector-body">
+      <div className="editor-head inspector-head">
+        <div className="inspector-title">
+          <StylePill style={atom.style} />
+          <div>
+            <strong>{fmtTime(atom.timestamp)}</strong>
+            <span>
+              {roleLabel} · {cameraLabel}
+            </span>
+          </div>
+        </div>
+        <div className="right">
+          <button
+            className="icon-btn"
+            title="Jump to this atom's frame"
+            onClick={() => jump(atom.timestamp)}
+          >
+            ▶
+          </button>
+          <button
+            className="icon-btn danger"
+            title="Delete this atom"
+            onClick={onDelete}
+          >
+            ×
+          </button>
+        </div>
+      </div>
+
+      <div className="field">
+        <label className="field-label">Timestamp (s)</label>
+        <div className="ts-row">
+          <input
+            type="text"
+            inputMode="decimal"
+            value={timestampDraft}
+            onChange={(e) => setTimestampDraft(e.target.value)}
+            onBlur={() => commitTimestamp()}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") commitTimestamp();
+              if (e.key === "Escape") setTimestampDraft(String(atom.timestamp));
+            }}
+          />
+          <button
+            type="button"
+            className="frame-pill"
+            onPointerDown={(e) => {
+              e.preventDefault();
+              commitSnappedTimestamp();
+            }}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                commitSnappedTimestamp();
+              }
+            }}
+          >
+            snap to frame
+          </button>
+        </div>
+      </div>
+
+      {/* Content / role-specific fields */}
+      {(atom.style === "task_aug" ||
+        atom.style === "subtask" ||
+        atom.style === "plan" ||
+        atom.style === "memory" ||
+        atom.style === "interjection") && (
+        <div className="field">
+          <label className="field-label">
+            {atom.style === "subtask"
+              ? "Subtask"
+              : atom.style === "task_aug"
+                ? "Task augmentation"
+                : atom.style === "plan"
+                  ? "Plan"
+                  : atom.style === "memory"
+                    ? "Memory"
+                    : "Interjection"}
+          </label>
+          {atom.style === "task_aug" ||
+          atom.style === "subtask" ||
+          atom.style === "interjection" ? (
+            <textarea
+              rows={3}
+              value={atom.content || ""}
+              onChange={(e) => onChange({ content: e.target.value })}
+            />
+          ) : (
+            <textarea
+              rows={4}
+              value={atom.content || ""}
+              onChange={(e) => onChange({ content: e.target.value })}
+            />
+          )}
+        </div>
+      )}
+
+      {isSpeech && atom.tool_calls && (
+        <div className="field">
+          <label className="field-label">Robot speech (say tool call)</label>
+          <input
+            type="text"
+            value={speechText(atom) || ""}
+            onChange={(e) => {
+              const next = atom.tool_calls
+                ? atom.tool_calls.map((tc, i) =>
+                    i === 0
+                      ? {
+                          ...tc,
+                          function: {
+                            ...tc.function,
+                            arguments: { text: e.target.value },
+                          },
+                        }
+                      : tc,
+                  )
+                : null;
+              onChange({ tool_calls: next });
+            }}
+          />
+        </div>
+      )}
+
+      {atom.style === "vqa" && (
+        <>
+          <CameraField
+            atom={atom}
+            cameraKeys={cameraKeys}
+            onChange={onChange}
+          />
+          <VqaEditorFields atom={atom} onChange={onChange} />
+        </>
+      )}
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// CameraField — surface the row-level camera tag for VQA atoms (PR 3467).
+// ---------------------------------------------------------------------------
+
+const CameraField: React.FC<{
+  atom: LanguageAtom;
+  cameraKeys: string[];
+  onChange: (updates: Partial<LanguageAtom>) => void;
+}> = ({ atom, cameraKeys, onChange }) => {
+  if (atom.style !== "vqa") return null;
+  if (cameraKeys.length === 0) return null;
+  const value = atom.camera ?? "";
+  return (
+    <div className="field">
+      <label className="field-label">Camera</label>
+      <select
+        value={value}
+        onChange={(e) =>
+          onChange({ camera: e.target.value === "" ? null : e.target.value })
+        }
+      >
+        <option value="">(any — renders on every camera)</option>
+        {cameraKeys.map((k) => (
+          <option key={k} value={k}>
+            {k}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+const VqaEditorFields: React.FC<{
+  atom: LanguageAtom;
+  onChange: (updates: Partial<LanguageAtom>) => void;
+}> = ({ atom, onChange }) => {
+  const parsed = parseVqaAnswer(atom.content);
+  const kind = parsed ? classifyVqa(parsed) : null;
+
+  if (atom.role === "user") {
+    return (
+      <div className="field">
+        <label className="field-label">Question</label>
+        <input
+          type="text"
+          value={atom.content || ""}
+          onChange={(e) => onChange({ content: e.target.value })}
+        />
+      </div>
+    );
+  }
+
+  // Assistant atom — answer JSON (raw + structured viewer)
+  return (
+    <div className="field">
+      <label className="field-label">Answer ({kind || "unknown"})</label>
+      <textarea
+        rows={5}
+        style={{
+          fontFamily:
+            "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
+        }}
+        value={atom.content || ""}
+        onChange={(e) => onChange({ content: e.target.value })}
+      />
+      {parsed && kind === "bbox" && (
+        <p className="text-[11px] text-slate-400 mt-1">
+          Tip: bbox values are 0..1 image-relative (xyxy). Edit on the video
+          itself by deleting this and re-drawing.
+        </p>
+      )}
+      {parsed && kind === "keypoint" && (
+        <p className="text-[11px] text-slate-400 mt-1">
+          Tip: point values are 0..1 image-relative (xy).
+        </p>
+      )}
+    </div>
+  );
+};

src/components/annotations-skin.css

@@ -0,0 +1,1044 @@
+/* ==========================================================================
+   Annotations tab — dark-mode skin scoped under .annotations-skin.
+   Borrows the *functional* patterns from the Claude Design handoff
+   (per-style pill colors, row layout, timeline shapes) but recolored to
+   match the visualizer's existing dark theme. The complaint we're fixing
+   here is contrast — earlier inputs were near-black on near-black; these
+   are still dark but legible.
+   ========================================================================== */
+
+.annotations-skin {
+  /* Brand accents (kept bright; visible on dark) */
+  --hf-yellow: #ffd21e;
+  --hf-orange: #ff9d00;
+  --hf-blue: #5b8cff;
+  --hf-cyan: #38bdf8;
+  --hf-red: #ef5350;
+  --hf-green: #34d399;
+  --hf-purple: #b78bff;
+
+  /* Dark surface scale */
+  --surface-0: rgba(255, 255, 255, 0.02);
+  --surface-1: rgba(255, 255, 255, 0.06);
+  --surface-2: rgba(255, 255, 255, 0.1);
+  --border-1: rgba(255, 255, 255, 0.12);
+  --border-2: rgba(255, 255, 255, 0.2);
+  --fg-1: #f1f5f9;
+  --fg-2: #cbd5e1;
+  --fg-3: #94a3b8;
+
+  --radius-xs: 4px;
+  --radius-sm: 6px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+}
+
+/* All form controls in the annotations area: brighter than the rest of the
+   visualizer so users can see what they're typing. */
+.annotations-skin input[type="text"],
+.annotations-skin input[type="number"],
+.annotations-skin input[type="password"],
+.annotations-skin input[type="search"],
+.annotations-skin textarea,
+.annotations-skin select {
+  background: var(--surface-1) !important;
+  color: var(--fg-1) !important;
+  border: 1px solid var(--border-1) !important;
+  border-radius: var(--radius-sm) !important;
+  font: inherit;
+  font-size: 13px;
+  padding: 6px 9px;
+}
+.annotations-skin input::placeholder,
+.annotations-skin textarea::placeholder {
+  color: var(--fg-3);
+}
+.annotations-skin input:focus,
+.annotations-skin textarea:focus,
+.annotations-skin select:focus {
+  outline: 2px solid var(--hf-blue) !important;
+  outline-offset: -1px;
+  border-color: var(--hf-blue) !important;
+}
+
+.annotations-skin kbd {
+  background: var(--surface-2);
+  border: 1px solid var(--border-1);
+  border-radius: var(--radius-xs);
+  padding: 1px 5px;
+  font-size: 10.5px;
+  color: var(--fg-1);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}
+
+/* ----- Style pills (per atom style) — bright on dark ----- */
+.annotations-skin .style-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 10.5px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  padding: 2px 8px;
+  border-radius: 999px;
+  border: 1px solid currentColor;
+}
+.annotations-skin .style-pill.subtask {
+  color: var(--hf-yellow);
+  background: rgba(255, 210, 30, 0.12);
+}
+.annotations-skin .style-pill.task_aug {
+  color: var(--hf-cyan);
+  background: rgba(56, 189, 248, 0.12);
+}
+.annotations-skin .style-pill.plan {
+  color: var(--hf-blue);
+  background: rgba(91, 140, 255, 0.12);
+}
+.annotations-skin .style-pill.memory {
+  color: var(--hf-purple);
+  background: rgba(183, 139, 255, 0.12);
+}
+.annotations-skin .style-pill.interjection {
+  color: var(--hf-red);
+  background: rgba(239, 83, 80, 0.12);
+}
+.annotations-skin .style-pill.vqa {
+  color: var(--hf-green);
+  background: rgba(52, 211, 153, 0.12);
+}
+.annotations-skin .style-pill.speech {
+  color: var(--hf-orange);
+  background: rgba(255, 157, 0, 0.12);
+}
+
+.annotations-skin .style-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 999px;
+  display: inline-block;
+}
+.annotations-skin .dot-subtask {
+  background: var(--hf-yellow);
+}
+.annotations-skin .dot-task-aug {
+  background: var(--hf-cyan);
+}
+.annotations-skin .dot-plan {
+  background: var(--hf-blue);
+}
+.annotations-skin .dot-memory {
+  background: var(--hf-purple);
+}
+.annotations-skin .dot-interjection {
+  background: var(--hf-red);
+}
+.annotations-skin .dot-vqa {
+  background: var(--hf-green);
+}
+.annotations-skin .dot-speech {
+  background: var(--hf-orange);
+}
+
+/* ----- Annotation rows ----- */
+.annotations-skin .row-anno {
+  display: flex;
+  gap: 8px;
+  padding: 6px 8px;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  align-items: center;
+  position: relative;
+  transition: background 80ms ease;
+}
+.annotations-skin .row-anno:hover {
+  background: var(--surface-1);
+}
+.annotations-skin .row-anno.active {
+  background: rgba(91, 140, 255, 0.12);
+  outline: 1px solid rgba(91, 140, 255, 0.4);
+}
+.annotations-skin .row-anno.active.subtask {
+  background: rgba(255, 210, 30, 0.1);
+  outline-color: rgba(255, 210, 30, 0.4);
+}
+.annotations-skin .row-anno.active.vqa {
+  background: rgba(52, 211, 153, 0.1);
+  outline-color: rgba(52, 211, 153, 0.4);
+}
+.annotations-skin .row-anno.active.interjection {
+  background: rgba(239, 83, 80, 0.1);
+  outline-color: rgba(239, 83, 80, 0.4);
+}
+.annotations-skin .row-anno .ts {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 10.5px;
+  color: var(--fg-3);
+  width: 56px;
+  flex: none;
+  text-align: right;
+  white-space: nowrap;
+}
+.annotations-skin .row-anno .delete {
+  width: 22px;
+  height: 22px;
+  border: 1px solid var(--border-1);
+  background: var(--surface-1);
+  color: var(--fg-3);
+  border-radius: var(--radius-xs);
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 11px;
+  flex: none;
+}
+.annotations-skin .row-anno .delete:hover {
+  color: var(--hf-red);
+  border-color: var(--hf-red);
+}
+.annotations-skin .jump {
+  width: 22px;
+  height: 22px;
+  border: 1px solid var(--border-1);
+  background: var(--surface-1);
+  color: var(--hf-blue);
+  border-radius: var(--radius-xs);
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 11px;
+  flex: none;
+}
+.annotations-skin .jump:hover {
+  background: var(--hf-blue);
+  color: #0b0e14;
+  border-color: var(--hf-blue);
+}
+
+/* ----- Section heads ----- */
+.annotations-skin .section-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+.annotations-skin .section-head .label {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 11.5px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--fg-1);
+}
+.annotations-skin .section-head .hint {
+  font-size: 11.5px;
+  color: var(--fg-3);
+}
+
+/* ----- Field labels ----- */
+.annotations-skin .field-label {
+  display: block;
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--fg-3);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  margin-bottom: 4px;
+}
+
+.annotations-skin .annotation-workbench {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.annotations-skin .annotation-actionbar,
+.annotations-skin .annotation-composer {
+  background: var(--surface-0);
+  border: 1px solid var(--border-1);
+  border-radius: var(--radius-lg);
+}
+.annotations-skin .annotation-actionbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 12px 14px;
+}
+.annotations-skin .annotation-actionbar h3 {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0;
+  font-size: 15px;
+  font-weight: 700;
+  color: var(--fg-1);
+}
+.annotations-skin .annotation-actionbar p,
+.annotations-skin .annotation-composer p,
+.annotations-skin .list-head p {
+  margin: 2px 0 0;
+  font-size: 12px;
+  color: var(--fg-3);
+}
+.annotations-skin .actionbar-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
+.annotations-skin .dirty-pill {
+  border: 1px solid rgba(251, 146, 60, 0.35);
+  border-radius: 999px;
+  background: rgba(251, 146, 60, 0.12);
+  color: #fdba74;
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  padding: 2px 7px;
+  text-transform: uppercase;
+}
+.annotations-skin .backend-offline,
+.annotations-skin .save-status {
+  font-size: 11px;
+  color: var(--fg-3);
+}
+.annotations-skin .section-kicker {
+  display: inline-flex;
+  color: var(--fg-2);
+  font-size: 10.5px;
+  font-weight: 800;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+.annotations-skin .annotation-composer {
+  display: grid;
+  grid-template-columns: minmax(180px, 260px) 1fr;
+  gap: 12px;
+  padding: 12px;
+  align-items: center;
+}
+.annotations-skin .camera-picker {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--fg-3);
+  font-size: 12px;
+  white-space: nowrap;
+}
+
+/* ----- Timeline ----- */
+.annotations-skin .tl {
+  background: var(--surface-0);
+  border: 1px solid var(--border-1);
+  border-radius: var(--radius-lg);
+  padding: 10px 12px;
+}
+.annotations-skin .tl-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  font-size: 11px;
+  color: var(--fg-3);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  margin-bottom: 8px;
+}
+.annotations-skin .tl-head .ts-display {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 12px;
+  color: var(--fg-1);
+  text-transform: none;
+  letter-spacing: 0;
+}
+.annotations-skin .tl-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  height: 24px;
+  margin-bottom: 4px;
+}
+.annotations-skin .tl-row .label {
+  width: 84px;
+  flex: none;
+  font-size: 10.5px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--fg-2);
+  font-weight: 600;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+.annotations-skin .tl-row .track {
+  position: relative;
+  flex: 1;
+  height: 20px;
+  background: var(--surface-1);
+  border: 1px solid var(--border-1);
+  border-radius: 3px;
+}
+.annotations-skin .tl-seg {
+  position: absolute;
+  top: 1px;
+  bottom: 1px;
+  border-radius: 2px;
+  font-size: 10px;
+  line-height: 16px;
+  padding: 0 6px;
+  cursor: pointer;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  user-select: none;
+  font-weight: 500;
+}
+.annotations-skin .tl-seg.task_aug {
+  background: rgba(56, 189, 248, 0.18);
+  border: 1px solid #38bdf8;
+  color: #bae6fd;
+}
+.annotations-skin .tl-seg.subtask {
+  background: rgba(255, 210, 30, 0.25);
+  border: 1px solid var(--hf-yellow);
+  color: var(--hf-yellow);
+}
+.annotations-skin .tl-seg.plan {
+  background: rgba(91, 140, 255, 0.25);
+  border: 1px solid var(--hf-blue);
+  color: #c7d6ff;
+}
+.annotations-skin .tl-seg.memory {
+  background: rgba(183, 139, 255, 0.25);
+  border: 1px solid var(--hf-purple);
+  color: #e3d4ff;
+}
+.annotations-skin .tl-tick {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 4px;
+  border-radius: 2px;
+  cursor: pointer;
+  transform: translateX(-2px);
+}
+.annotations-skin .tl-tick.plan {
+  background: var(--hf-blue);
+}
+.annotations-skin .tl-tick.task_aug {
+  background: var(--hf-cyan);
+}
+.annotations-skin .tl-tick.memory {
+  background: var(--hf-purple);
+}
+.annotations-skin .tl-tick.interjection {
+  background: var(--hf-red);
+}
+.annotations-skin .tl-tick.speech {
+  background: var(--hf-orange);
+}
+.annotations-skin .tl-tick.vqa {
+  background: var(--hf-green);
+}
+.annotations-skin .tl-playhead {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 0;
+  border-left: 2px solid var(--hf-yellow);
+  pointer-events: none;
+  z-index: 5;
+  box-shadow: 0 0 8px rgba(255, 210, 30, 0.6);
+}
+.annotations-skin .tl-playhead::before {
+  content: "";
+  position: absolute;
+  top: -3px;
+  left: -6px;
+  width: 10px;
+  height: 10px;
+  background: var(--hf-yellow);
+  transform: rotate(45deg);
+}
+.annotations-skin .tl-ruler {
+  position: relative;
+  height: 16px;
+  margin-left: 94px;
+  border-bottom: 1px solid var(--border-1);
+  margin-bottom: 6px;
+}
+.annotations-skin .tl-ruler .tick-mark {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  border-left: 1px solid var(--border-1);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 10px;
+  color: var(--fg-3);
+  padding-left: 3px;
+}
+
+/* ----- Persistent / Events section banding (timeline + rail) ----- */
+.annotations-skin .tl-section {
+  margin-bottom: 6px;
+}
+.annotations-skin .tl-section-head,
+.annotations-skin .rail-column-head {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  padding: 4px 0 4px 2px;
+  margin-bottom: 4px;
+  border-left: 3px solid var(--border-2, #2a3344);
+  padding-left: 8px;
+}
+.annotations-skin .tl-section-head.persistent,
+.annotations-skin .rail-column-head.persistent {
+  border-left-color: var(--hf-blue, #5b8cff);
+}
+.annotations-skin .tl-section-head.events,
+.annotations-skin .rail-column-head.events {
+  border-left-color: var(--hf-green, #34d399);
+}
+.annotations-skin .tl-section-title,
+.annotations-skin .rail-column-title {
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--fg-1);
+}
+.annotations-skin .tl-section-sub,
+.annotations-skin .rail-column-sub {
+  font-size: 10px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  color: var(--fg-3);
+}
+.annotations-skin .rail-column {
+  margin-bottom: 10px;
+}
+.annotations-skin .rail-column-head {
+  margin-top: 2px;
+}
+
+/* ----- Quick label popup over the video ----- */
+.annotations-skin .quick-popup {
+  position: absolute;
+  z-index: 30;
+  background: rgba(15, 23, 42, 0.96);
+  border: 1px solid var(--border-2);
+  border-radius: var(--radius-md);
+  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
+  padding: 8px;
+  min-width: 220px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  pointer-events: auto;
+  backdrop-filter: blur(6px);
+}
+.annotations-skin .quick-popup-head {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 10.5px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--fg-3);
+}
+.annotations-skin .quick-popup-actions {
+  display: flex;
+  gap: 6px;
+  justify-content: flex-end;
+}
+.annotations-skin .quick-popup .kind-pill {
+  padding: 2px 6px;
+  border-radius: var(--radius-xs);
+  border: 1px solid currentColor;
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+.annotations-skin .quick-popup .kind-pill.bbox {
+  color: var(--hf-cyan);
+  background: rgba(56, 189, 248, 0.16);
+}
+.annotations-skin .quick-popup .kind-pill.keypoint {
+  color: var(--hf-yellow);
+  background: rgba(255, 210, 30, 0.16);
+}
+.annotations-skin .quick-popup .popup-btn {
+  font-size: 11px;
+  height: 24px;
+  padding: 0 10px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-1);
+  background: transparent;
+  color: var(--fg-2);
+  cursor: pointer;
+}
+.annotations-skin .quick-popup .popup-btn:hover {
+  background: var(--surface-1);
+  color: var(--fg-1);
+}
+.annotations-skin .quick-popup .popup-btn.primary {
+  border-color: rgba(56, 189, 248, 0.4);
+  background: rgba(56, 189, 248, 0.12);
+  color: #c5ecff;
+}
+.annotations-skin .quick-popup .popup-btn.primary:hover {
+  background: rgba(56, 189, 248, 0.2);
+}
+.annotations-skin .quick-popup .popup-btn:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+/* ----- Inline quick-add bar (above the timeline) ----- */
+.annotations-skin .quick-add {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+  padding: 0;
+  background: transparent;
+  border: 0;
+}
+.annotations-skin .annotation-composer .quick-add {
+  justify-content: flex-end;
+}
+.annotations-skin .ts-pill {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 11px;
+  padding: 3px 8px;
+  border-radius: 999px;
+  background: var(--surface-2);
+  color: var(--fg-2);
+  white-space: nowrap;
+}
+.annotations-skin .quick-add .ts-pill {
+  flex: none;
+}
+/* ----- Grounded VQA intro card (under video) ----- */
+.annotations-skin .grounding-intro {
+  background: var(--surface-0);
+  border: 1px solid var(--border-1);
+  border-radius: var(--radius-lg);
+  padding: 10px 14px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.annotations-skin .grounding-intro ul {
+  margin: 0;
+  padding-left: 18px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--fg-3);
+}
+.annotations-skin .grounding-intro li::marker {
+  color: var(--fg-3);
+}
+
+/* ----- Workspace: annotation list + inspector ----- */
+.annotations-skin .workspace.inspector-workspace {
+  grid-template-columns: minmax(300px, 34%) minmax(0, 1fr);
+  gap: 12px;
+}
+.annotations-skin .rail.annotation-list {
+  padding: 0;
+  max-height: min(60vh, 560px);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+.annotations-skin .list-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 12px;
+  border-bottom: 1px solid var(--border-1);
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  background: rgba(15, 23, 42, 0.96);
+  backdrop-filter: blur(6px);
+}
+.annotations-skin .rail.annotation-list .rail-group {
+  margin: 8px;
+}
+.annotations-skin .rail.annotation-list .rail-row {
+  align-items: flex-start;
+  padding: 7px 8px;
+}
+.annotations-skin .rail.annotation-list .rail-row .body {
+  white-space: normal;
+  overflow: visible;
+  text-overflow: clip;
+  line-height: 1.3;
+}
+.annotations-skin .rail.annotation-list .rail-row.selected {
+  background: rgba(91, 140, 255, 0.2);
+  box-shadow: inset 3px 0 0 var(--hf-blue);
+}
+.annotations-skin .rail.annotation-list .rail-row.active-now:not(.selected) {
+  border-color: rgba(255, 210, 30, 0.45);
+  outline: none;
+}
+.annotations-skin .inspector {
+  position: sticky;
+  top: 8px;
+}
+.annotations-skin .inspector .editor-empty {
+  min-height: 220px;
+  display: grid;
+  place-content: center;
+  gap: 8px;
+}
+.annotations-skin .inspector .editor-empty p {
+  margin: 0;
+  max-width: 360px;
+}
+.annotations-skin .inspector-body {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.annotations-skin .inspector-head {
+  align-items: flex-start;
+}
+.annotations-skin .inspector-title {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  min-width: 0;
+}
+.annotations-skin .inspector-title strong {
+  display: block;
+  color: var(--fg-1);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 12px;
+  line-height: 1.4;
+}
+.annotations-skin .inspector-title span:not(.style-pill) {
+  display: block;
+  color: var(--fg-3);
+  font-size: 11.5px;
+  line-height: 1.35;
+}
+
+@media (max-width: 900px) {
+  .annotations-skin .annotation-actionbar {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+  .annotations-skin .annotation-composer,
+  .annotations-skin .workspace.inspector-workspace {
+    grid-template-columns: 1fr;
+  }
+  .annotations-skin .annotation-composer .quick-add {
+    justify-content: flex-start;
+  }
+  .annotations-skin .inspector {
+    position: static;
+  }
+}
+
+/* Legacy quick-add styles kept for popup/control compatibility. */
+.annotations-skin .quick-add {
+  border-radius: var(--radius-md);
+}
+.annotations-skin .quick-add.legacy {
+  padding: 8px 10px;
+  background: var(--surface-0);
+  border: 1px solid var(--border-1);
+}
+.annotations-skin .quick-add .ts-pill {
+  flex: none;
+}
+.annotations-skin .quick-add .grow {
+  flex: 1;
+  min-width: 200px;
+}
+.annotations-skin .quick-add .add-btn {
+  background: var(--hf-blue);
+  color: #0b0e14;
+  border: 1px solid var(--hf-blue);
+  border-radius: var(--radius-sm);
+  padding: 6px 14px;
+  font-size: 13px;
+  font-weight: 700;
+  cursor: pointer;
+  white-space: nowrap;
+}
+.annotations-skin .quick-add .add-btn:hover {
+  filter: brightness(1.1);
+}
+.annotations-skin .quick-add .add-btn:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+/* ----- Workspace: 2-column rail + editor ----- */
+.annotations-skin .workspace {
+  display: grid;
+  grid-template-columns: 280px 1fr;
+  gap: 10px;
+  align-items: start;
+}
+@media (max-width: 900px) {
+  .annotations-skin .workspace {
+    grid-template-columns: 1fr;
+  }
+}
+.annotations-skin .rail {
+  background: var(--surface-0);
+  border: 1px solid var(--border-1);
+  border-radius: var(--radius-md);
+  padding: 8px;
+  max-height: 60vh;
+  overflow-y: auto;
+}
+.annotations-skin .rail-empty {
+  padding: 24px 8px;
+  font-size: 12px;
+  color: var(--fg-3);
+  text-align: center;
+}
+.annotations-skin .rail-group {
+  margin-bottom: 6px;
+}
+.annotations-skin .rail-group-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 6px 8px;
+  font-size: 10.5px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--fg-3);
+}
+.annotations-skin .rail-group-head .count {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 10px;
+}
+.annotations-skin .rail-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 5px 8px;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  font-size: 12px;
+  color: var(--fg-1);
+  border: 1px solid transparent;
+}
+.annotations-skin .rail-row:hover {
+  background: var(--surface-1);
+}
+.annotations-skin .rail-row.selected {
+  background: rgba(91, 140, 255, 0.16);
+  border-color: var(--hf-blue);
+}
+.annotations-skin .rail-row .ts {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 10.5px;
+  color: var(--fg-3);
+  width: 56px;
+  flex: none;
+  text-align: right;
+}
+.annotations-skin .rail-row .body {
+  flex: 1;
+  min-width: 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.annotations-skin .rail-row.active-now {
+  outline: 2px solid var(--hf-yellow);
+  outline-offset: -1px;
+}
+
+/* ----- Editor pane (right side of workspace) ----- */
+.annotations-skin .editor {
+  background: var(--surface-0);
+  border: 1px solid var(--border-1);
+  border-radius: var(--radius-md);
+  padding: 14px 16px;
+}
+.annotations-skin .editor-empty {
+  padding: 40px 16px;
+  font-size: 13px;
+  color: var(--fg-3);
+  text-align: center;
+}
+.annotations-skin .editor-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 12px;
+  padding-bottom: 10px;
+  border-bottom: 1px solid var(--border-1);
+}
+.annotations-skin .editor-head .right {
+  margin-left: auto;
+  display: flex;
+  gap: 6px;
+}
+.annotations-skin .editor-head .icon-btn {
+  width: 28px;
+  height: 28px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-1);
+  background: var(--surface-1);
+  color: var(--fg-2);
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 12px;
+}
+.annotations-skin .editor-head .icon-btn:hover {
+  color: var(--fg-1);
+  border-color: var(--border-2);
+}
+.annotations-skin .editor-head .icon-btn.danger:hover {
+  color: var(--hf-red);
+  border-color: var(--hf-red);
+}
+.annotations-skin .editor .field {
+  margin-bottom: 10px;
+}
+.annotations-skin .editor .field > input,
+.annotations-skin .editor .field > select,
+.annotations-skin .editor .field > textarea {
+  width: 100%;
+}
+.annotations-skin .editor .field > textarea {
+  min-height: 74px;
+  resize: vertical;
+  line-height: 1.45;
+}
+.annotations-skin .editor .ts-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+.annotations-skin .editor .ts-row input {
+  width: 100px;
+}
+.annotations-skin .editor .ts-row .frame-pill {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 11px;
+  padding: 3px 8px;
+  border: 0;
+  border-radius: 999px;
+  background: var(--surface-2);
+  color: var(--fg-3);
+  cursor: pointer;
+}
+.annotations-skin .editor .ts-row .frame-pill:hover {
+  color: var(--fg-1);
+  background: var(--surface-1);
+}
+
+/* ----- Timeline drag handles + tooltip + draggable playhead ----- */
+.annotations-skin .tl-seg .resize {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 6px;
+  cursor: ew-resize;
+  z-index: 2;
+}
+.annotations-skin .tl-seg .resize.l {
+  left: 0;
+}
+.annotations-skin .tl-seg .resize.r {
+  right: 0;
+}
+.annotations-skin .tl-seg .resize:hover {
+  background: rgba(255, 255, 255, 0.18);
+}
+.annotations-skin .tl-seg.dragging {
+  opacity: 0.85;
+  outline: 2px solid var(--hf-yellow);
+  outline-offset: -1px;
+}
+.annotations-skin .tl-row .track.creating {
+  outline: 1px dashed var(--hf-blue);
+}
+.annotations-skin .tl-create-preview {
+  position: absolute;
+  top: 1px;
+  bottom: 1px;
+  background: rgba(255, 210, 30, 0.3);
+  border: 1px dashed var(--hf-yellow);
+  border-radius: 2px;
+  pointer-events: none;
+  z-index: 4;
+}
+.annotations-skin .tl-playhead-handle {
+  position: absolute;
+  top: -6px;
+  width: 14px;
+  height: 14px;
+  background: var(--hf-yellow);
+  border: 2px solid #0b0e14;
+  border-radius: 999px;
+  transform: translate(-7px, 0);
+  cursor: ew-resize;
+  pointer-events: auto;
+  z-index: 6;
+}
+.annotations-skin .tl-tooltip {
+  position: fixed;
+  z-index: 1000;
+  background: rgba(15, 23, 42, 0.96);
+  color: var(--fg-1);
+  border: 1px solid var(--border-2);
+  border-radius: var(--radius-sm);
+  padding: 6px 10px;
+  font-size: 12px;
+  max-width: 320px;
+  pointer-events: none;
+  box-shadow: 0 8px 22px rgba(0, 0, 0, 0.4);
+  backdrop-filter: blur(6px);
+  line-height: 1.35;
+  white-space: pre-line;
+}
+.annotations-skin .tl-tooltip .meta {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 10px;
+  color: var(--fg-3);
+  margin-bottom: 2px;
+}
+
+/* ----- Collapsed task-augmentation bar ----- */
+.annotations-skin .tl-seg.task_aug .aug-count {
+  flex: none;
+  margin-left: auto;
+  padding: 0 5px;
+  border-radius: 999px;
+  background: rgba(56, 189, 248, 0.28);
+  border: 1px solid rgba(56, 189, 248, 0.7);
+  color: #e0f2fe;
+  font-size: 9.5px;
+  font-weight: 700;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  line-height: 14px;
+}

src/components/annotations-timeline.tsx

@@ -0,0 +1,818 @@
+"use client";
+
+/**
+ * Multi-track timeline for v3.1 language atoms — like a video-editing
+ * scrubber, but stacked vertically by style and split into two banded
+ * sections that mirror the two language columns:
+ *
+ *   PERSISTENT (language_persistent — broadcast across every frame):
+ *   - task_aug: task phrasings shown as point-in-time ticks at episode start.
+ *   - subtask: filled spans from each emit time until the next subtask emit
+ *     (or episode end). Numbered. Resizable edges; the empty subtask track
+ *     also accepts drag-to-create.
+ *   - plan: filled (read-only) spans from each plan emit until the next plan
+ *     refresh (or episode end) — a plan is the active state until superseded,
+ *     so it reads as a span, not an instantaneous event.
+ *   - memory: tick marks (state snapshots captured at subtask boundaries).
+ *
+ *   EVENTS (language_events — fire on a single frame):
+ *   - interjections + speech: combined event track.
+ *   - vqa: event track.
+ *
+ * Interactions:
+ *   - Click a marker → seek + select (handled by the panel's listening to
+ *     `selectAtom` via context).
+ *   - Drag a subtask span's left edge → retime that subtask's start.
+ *   - Drag a subtask span's right edge → retime the *next* subtask's start
+ *     (since the right edge of subtask[i] *is* the start of subtask[i+1]).
+ *   - Drag from empty area on the subtask track → create a new subtask span;
+ *     a label popup appears at the draw end so you can name it.
+ *   - Drag the playhead handle (or click anywhere on the track band) → scrub
+ *     the video time. Pauses the player while dragging.
+ *   - Hover over any marker → custom tooltip shows the atom's content.
+ */
+
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { useTime } from "../context/time-context";
+import { useAnnotations } from "../context/annotations-context";
+import {
+  classifyVqa,
+  isSpeechAtom,
+  parseVqaAnswer,
+  type LanguageAtom,
+} from "../types/language.types";
+
+const LABEL_WIDTH = 84;
+const DRAG_THRESHOLD_PX = 4;
+
+// `render` controls how a lane draws: "span-edit" = resizable + drag-to-create
+// (subtask), "span-ro" = read-only spans (task_aug / plan), "tick" = point
+// markers.
+const TRACK_GROUPS = [
+  {
+    column: "persistent",
+    title: "Persistent",
+    sub: "language_persistent · broadcast across every frame",
+    tracks: [
+      // task_aug applies to the whole episode (it's a rephrasing of the task,
+      // stored at t0 but persistent across every frame), so it reads as a
+      // full-episode span — matching how the annotation pipeline treats it.
+      // We collapse all rephrasings into a single full-width bar with a ×N badge;
+      // clicking opens a popover listing every phrasing.
+      {
+        key: "task_aug",
+        label: "task aug",
+        color: "#38bdf8",
+        render: "task-aug",
+      },
+      {
+        key: "subtask",
+        label: "subtask",
+        color: "#ffd21e",
+        render: "span-edit",
+      },
+      { key: "plan", label: "plan", color: "#5b8cff", render: "span-ro" },
+      { key: "memory", label: "memory", color: "#b78bff", render: "tick" },
+    ],
+  },
+  {
+    column: "events",
+    title: "Events",
+    sub: "language_events · fire on a single frame",
+    tracks: [
+      {
+        key: "interjection",
+        label: "speech",
+        color: "#ef5350",
+        render: "tick",
+      },
+      { key: "vqa", label: "vqa", color: "#34d399", render: "tick" },
+    ],
+  },
+] as const;
+
+interface Props {
+  /** Episode duration in seconds. */
+  duration: number;
+}
+
+interface Tooltip {
+  x: number;
+  y: number;
+  meta: string;
+  text: string;
+}
+
+interface DragState {
+  kind: "edge" | "playhead" | "create";
+  /** Atom index whose timestamp is being moved (edge / create). */
+  atomIdx?: number;
+  /** Episode-second timestamps captured at drag start (for cancel/clamp). */
+  origTs?: number;
+  prevTs?: number; // previous subtask's timestamp (lower bound)
+  nextTs?: number; // next subtask's timestamp (upper bound, exclusive)
+  /** For drag-to-create only. */
+  startTs?: number;
+  endTs?: number;
+}
+
+interface PendingCreate {
+  start: number;
+  end: number;
+  /** Anchor for the label popup (canvas-relative px). */
+  anchorX: number;
+  anchorY: number;
+}
+
+export const AnnotationsTimeline: React.FC<Props> = ({ duration }) => {
+  const { atoms, addAtom, updateAtom, snap, selectAtom } = useAnnotations();
+  const { currentTime, seek, setIsPlaying } = useTime();
+  const trackBandRef = useRef<HTMLDivElement | null>(null);
+
+  const [tooltip, setTooltip] = useState<Tooltip | null>(null);
+  const [drag, setDrag] = useState<DragState | null>(null);
+  const [pendingCreate, setPendingCreate] = useState<PendingCreate | null>(
+    null,
+  );
+  const [createLabel, setCreateLabel] = useState("");
+
+  // Pause + select helper
+  const jumpAndSelect = React.useCallback(
+    (ts: number, idx: number | null) => {
+      seek(ts, "external");
+      setIsPlaying(false);
+      if (idx != null) selectAtom(idx);
+    },
+    [seek, setIsPlaying, selectAtom],
+  );
+
+  // ============ Lane derivation ============
+  const lanes = useMemo(() => {
+    type SpanMarker = {
+      kind: "span";
+      start: number;
+      end: number;
+      label: string;
+      atom: LanguageAtom;
+      atomIdx: number; // index of the *start* atom in atoms[]
+    };
+    type TickMarker = {
+      kind: "tick";
+      t: number;
+      label: string;
+      atom: LanguageAtom;
+      atomIdx: number;
+      subtype?: string;
+    };
+
+    const subtask: SpanMarker[] = [];
+    const task_aug: SpanMarker[] = [];
+    const plan: SpanMarker[] = [];
+    const memory: TickMarker[] = [];
+    const interjection: TickMarker[] = [];
+    const vqa: TickMarker[] = [];
+
+    // Subtasks → spans, sorted by ts. Track the original atom index so drag
+    // operations can update via updateAtom(idx, ...).
+    const subWithIdx = atoms
+      .map((a, i) => ({ a, i }))
+      .filter(({ a }) => a.style === "subtask")
+      .sort((x, y) => x.a.timestamp - y.a.timestamp);
+    subWithIdx.forEach(({ a, i }, k) => {
+      const start = a.timestamp;
+      const end =
+        k + 1 < subWithIdx.length ? subWithIdx[k + 1].a.timestamp : duration;
+      subtask.push({
+        kind: "span",
+        start,
+        end,
+        label: a.content || "",
+        atom: a,
+        atomIdx: i,
+      });
+    });
+
+    // Plans → read-only spans: a plan is the active state from its emit time
+    // until the next plan refresh (or episode end), exactly like a subtask
+    // span. Rendering it as a span (not a tick) makes its persistent nature
+    // visible — it isn't a point-in-time event.
+    const planWithIdx = atoms
+      .map((a, i) => ({ a, i }))
+      .filter(({ a }) => a.style === "plan")
+      .sort((x, y) => x.a.timestamp - y.a.timestamp);
+    planWithIdx.forEach(({ a, i }, k) => {
+      const start = a.timestamp;
+      const end =
+        k + 1 < planWithIdx.length ? planWithIdx[k + 1].a.timestamp : duration;
+      plan.push({
+        kind: "span",
+        start,
+        end,
+        label: a.content || "plan",
+        atom: a,
+        atomIdx: i,
+      });
+    });
+
+    // Task augmentations → full-episode spans: each is a rephrasing of the
+    // task and applies to the whole episode (persistent, stored at t0), so it
+    // spans [t0, t_last] rather than sitting as a tick at the start.
+    atoms.forEach((a, i) => {
+      if (a.style === "task_aug") {
+        task_aug.push({
+          kind: "span",
+          start: 0,
+          end: duration,
+          label: a.content || "task augmentation",
+          atom: a,
+          atomIdx: i,
+        });
+      }
+    });
+
+    atoms.forEach((a, i) => {
+      if (a.style === "memory") {
+        memory.push({
+          kind: "tick",
+          t: a.timestamp,
+          label: a.content || "memory",
+          atom: a,
+          atomIdx: i,
+        });
+      } else if (a.style === "interjection" || isSpeechAtom(a)) {
+        interjection.push({
+          kind: "tick",
+          t: a.timestamp,
+          label: a.style === "interjection" ? a.content || "" : "say(…)",
+          atom: a,
+          atomIdx: i,
+          subtype: a.style === "interjection" ? "user" : "speech",
+        });
+      } else if (a.style === "vqa" && a.role === "assistant") {
+        const parsed = parseVqaAnswer(a.content);
+        const kind = parsed ? classifyVqa(parsed) : null;
+        vqa.push({
+          kind: "tick",
+          t: a.timestamp,
+          label: kind || "vqa",
+          atom: a,
+          atomIdx: i,
+          subtype: kind || undefined,
+        });
+      }
+    });
+
+    return { task_aug, subtask, plan, memory, interjection, vqa, subWithIdx };
+  }, [atoms, duration]);
+
+  // ============ Pixel <-> time mapping ============
+  // The full-width track band (no label margin) is `trackBandRef`. Convert
+  // mouse client.x to a 0..duration timestamp.
+  const trackXToTs = (clientX: number): number => {
+    const r = trackBandRef.current?.getBoundingClientRect();
+    if (!r || !duration) return 0;
+    const frac = Math.max(0, Math.min(1, (clientX - r.left) / r.width));
+    return frac * duration;
+  };
+
+  // ============ Event-track click → seek + select ============
+  const onTickClick = (e: React.MouseEvent, atomIdx: number, t: number) => {
+    e.stopPropagation();
+    jumpAndSelect(t, atomIdx);
+  };
+
+  // ============ task_aug collapsed-bar click ============
+  // All phrasings share t0, so there is no spatial way to disambiguate them
+  // on the track — clicking just selects the first one (the full list is
+  // shown on hover). The inspector + rail still expose every rewording.
+  const onTaskAugClick = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    const augs = lanes.task_aug;
+    if (augs.length === 0) return;
+    jumpAndSelect(0, augs[0].atomIdx);
+  };
+
+  // ============ Subtask span drag ============
+  const onSpanBodyClick = (
+    e: React.MouseEvent,
+    atomIdx: number,
+    start: number,
+  ) => {
+    if (drag || pendingCreate) return;
+    e.stopPropagation();
+    jumpAndSelect(start, atomIdx);
+  };
+
+  const onEdgeDown = (
+    e: React.PointerEvent,
+    side: "l" | "r",
+    spanK: number,
+  ) => {
+    e.stopPropagation();
+    e.preventDefault();
+    (e.target as HTMLElement).setPointerCapture?.(e.pointerId);
+    const sub = lanes.subWithIdx;
+    // Left edge of span k → moves sub[k] timestamp.
+    // Right edge of span k → moves sub[k+1] timestamp (if exists).
+    const idxToMove = side === "l" ? spanK : spanK + 1;
+    if (idxToMove < 0 || idxToMove >= sub.length) return;
+    const target = sub[idxToMove];
+    const lower = idxToMove > 0 ? sub[idxToMove - 1].a.timestamp : 0;
+    const upper =
+      idxToMove + 1 < sub.length ? sub[idxToMove + 1].a.timestamp : duration;
+    setDrag({
+      kind: "edge",
+      atomIdx: target.i,
+      origTs: target.a.timestamp,
+      prevTs: lower,
+      nextTs: upper,
+    });
+  };
+
+  // ============ Drag-to-create new subtask span ============
+  const onSubtaskTrackDown = (e: React.PointerEvent) => {
+    // Only fire when the mousedown lands on the track itself, not on a
+    // child span/edge (those stop propagation in their own handlers).
+    if (drag || pendingCreate) return;
+    if (e.button !== 0) return;
+    (e.target as HTMLElement).setPointerCapture?.(e.pointerId);
+    const ts = snap(trackXToTs(e.clientX));
+    setDrag({ kind: "create", startTs: ts, endTs: ts });
+  };
+
+  // ============ Playhead drag ============
+  const onPlayheadDown = (e: React.PointerEvent) => {
+    e.stopPropagation();
+    e.preventDefault();
+    (e.target as HTMLElement).setPointerCapture?.(e.pointerId);
+    setIsPlaying(false);
+    setDrag({ kind: "playhead" });
+  };
+
+  const onTrackBandClick = (e: React.MouseEvent) => {
+    // Clicks anywhere on the track band that bubbled up: seek to that point.
+    if (drag || pendingCreate) return;
+    if ((e.target as HTMLElement).dataset.role === "ruler") {
+      // Already handled by the dedicated ruler bar
+    }
+    const ts = trackXToTs(e.clientX);
+    seek(ts, "external");
+    setIsPlaying(false);
+  };
+
+  // ============ Global pointermove / pointerup for drag commits ============
+  useEffect(() => {
+    if (!drag) return;
+    const move = (e: PointerEvent) => {
+      const ts = trackXToTs(e.clientX);
+      if (drag.kind === "playhead") {
+        seek(Math.max(0, Math.min(duration, ts)), "external");
+        return;
+      }
+      if (drag.kind === "edge" && drag.atomIdx != null) {
+        const lower = drag.prevTs ?? 0;
+        const upper = drag.nextTs ?? duration;
+        const clamped = Math.max(lower + 0.001, Math.min(upper - 0.001, ts));
+        const snapped = snap(clamped);
+        updateAtom(drag.atomIdx, { timestamp: snapped });
+        return;
+      }
+      if (drag.kind === "create") {
+        const snapped = snap(Math.max(0, Math.min(duration, ts)));
+        setDrag((d) => (d ? { ...d, endTs: snapped } : d));
+      }
+    };
+    const up = (e: PointerEvent) => {
+      if (drag.kind === "create") {
+        const a = Math.min(drag.startTs ?? 0, drag.endTs ?? 0);
+        const b = Math.max(drag.startTs ?? 0, drag.endTs ?? 0);
+        const distFrac = Math.abs(b - a) / Math.max(0.001, duration);
+        // Need at least a few px of drag to count, otherwise treat as click.
+        const trackWidth =
+          trackBandRef.current?.getBoundingClientRect().width ?? 1;
+        if (distFrac * trackWidth >= DRAG_THRESHOLD_PX) {
+          // Anchor the label popup at the upper-right of the new span.
+          const r = trackBandRef.current?.getBoundingClientRect();
+          if (r) {
+            const xFrac = b / Math.max(0.001, duration);
+            setPendingCreate({
+              start: a,
+              end: b,
+              anchorX: r.left + xFrac * r.width + 4,
+              anchorY: r.top - 8,
+            });
+          }
+        } else {
+          // Tap, not drag — treat as a seek to that point.
+          seek(a, "external");
+          setIsPlaying(false);
+        }
+      } else if (drag.kind === "edge" && drag.atomIdx != null) {
+        // Already updated in `move`; nothing more to do beyond final snap.
+      }
+      setDrag(null);
+      // We don't release pointerCapture here because the original target is
+      // already cleaned up by the browser when we release the pointer.
+      void e;
+    };
+    window.addEventListener("pointermove", move);
+    window.addEventListener("pointerup", up);
+    return () => {
+      window.removeEventListener("pointermove", move);
+      window.removeEventListener("pointerup", up);
+    };
+  }, [drag, duration, seek, setIsPlaying, snap, updateAtom]);
+
+  // ============ Tooltip helpers ============
+  const showTip = (e: React.MouseEvent, meta: string, text: string) => {
+    setTooltip({
+      x: e.clientX + 12,
+      y: e.clientY + 12,
+      meta,
+      text,
+    });
+  };
+  const moveTip = (e: React.MouseEvent) => {
+    setTooltip((t) => (t ? { ...t, x: e.clientX + 12, y: e.clientY + 12 } : t));
+  };
+  const hideTip = () => setTooltip(null);
+
+  // ============ Pending-create label popup commit ============
+  const commitPendingCreate = () => {
+    if (!pendingCreate) return;
+    const text = createLabel.trim();
+    if (!text) {
+      setPendingCreate(null);
+      setCreateLabel("");
+      return;
+    }
+    addAtom({
+      role: "assistant",
+      content: text,
+      style: "subtask",
+      timestamp: snap(pendingCreate.start),
+      camera: null,
+      tool_calls: null,
+    });
+    // The next subtask boundary is implicit (next sibling's timestamp); if
+    // the user wants a different end they can drag the right edge afterwards.
+    setPendingCreate(null);
+    setCreateLabel("");
+  };
+  const cancelPendingCreate = () => {
+    setPendingCreate(null);
+    setCreateLabel("");
+  };
+
+  // ============ Render ============
+  if (!duration) return null;
+
+  return (
+    <div className="tl">
+      <div className="tl-head">
+        <span>Annotations timeline</span>
+        <span className="ts-display">
+          {currentTime.toFixed(2)}s / {duration.toFixed(2)}s
+        </span>
+      </div>
+
+      {/* Time-axis ruler — clicking it scrubs */}
+      <div
+        className="tl-ruler"
+        data-role="ruler"
+        onClick={(e) => {
+          const ts = trackXToTs(e.clientX);
+          seek(ts, "external");
+          setIsPlaying(false);
+        }}
+      >
+        {Array.from({ length: Math.floor(duration / 5) + 1 }).map((_, i) => {
+          const t = i * 5;
+          const left = (t / duration) * 100;
+          return (
+            <div key={i} className="tick-mark" style={{ left: `${left}%` }}>
+              {t}s
+            </div>
+          );
+        })}
+      </div>
+
+      {/* Tracks, grouped into Persistent / Events sections that mirror the
+           two language columns. The whole region is position:relative so the
+           playhead can span its full height via top/bottom (no brittle
+           per-track pixel math that section headers would throw off). The
+           playhead's x uses calc() to start at the track band's left edge
+           (after the LABEL_WIDTH label column + 10px gap). */}
+      {(() => {
+        const bandLeft = `${LABEL_WIDTH + 10}px`;
+        const playheadLeft = `calc(${bandLeft} + ${
+          duration ? currentTime / duration : 0
+        } * (100% - ${bandLeft}))`;
+        return (
+          <div className="tl-tracks" style={{ position: "relative" }}>
+            {TRACK_GROUPS.map((group) => (
+              <div className="tl-section" key={group.column}>
+                <div className={`tl-section-head ${group.column}`}>
+                  <span className="tl-section-title">{group.title}</span>
+                  <span className="tl-section-sub">{group.sub}</span>
+                </div>
+                {group.tracks.map((tk) => (
+                  <div className="tl-row" key={tk.key}>
+                    <div className="label">
+                      <span className={`style-dot dot-${tk.key}`} />
+                      {tk.label}
+                    </div>
+                    <div
+                      className={`track ${
+                        tk.key === "subtask" && drag?.kind === "create"
+                          ? "creating"
+                          : ""
+                      }`}
+                      ref={tk.key === "subtask" ? trackBandRef : undefined}
+                      onClick={
+                        tk.render === "span-edit" ? undefined : onTrackBandClick
+                      }
+                      onPointerDown={
+                        tk.key === "subtask" ? onSubtaskTrackDown : undefined
+                      }
+                    >
+                      {/* Editable subtask spans (resize + drag-to-create) */}
+                      {tk.render === "span-edit" &&
+                        lanes.subtask.map((s, k) => {
+                          const left = (s.start / duration) * 100;
+                          const width = Math.max(
+                            0.3,
+                            ((s.end - s.start) / duration) * 100,
+                          );
+                          return (
+                            <div
+                              key={k}
+                              className={`tl-seg subtask ${drag?.kind === "edge" && drag.atomIdx === s.atomIdx ? "dragging" : ""}`}
+                              style={{ left: `${left}%`, width: `${width}%` }}
+                              onClick={(e) =>
+                                onSpanBodyClick(e, s.atomIdx, s.start)
+                              }
+                              onMouseEnter={(e) =>
+                                showTip(
+                                  e,
+                                  `subtask · ${s.start.toFixed(2)}s → ${s.end.toFixed(2)}s`,
+                                  s.label,
+                                )
+                              }
+                              onMouseMove={moveTip}
+                              onMouseLeave={hideTip}
+                            >
+                              <span style={{ opacity: 0.7, fontSize: 10 }}>
+                                {k}
+                              </span>
+                              <span
+                                style={{
+                                  whiteSpace: "nowrap",
+                                  overflow: "hidden",
+                                  textOverflow: "ellipsis",
+                                }}
+                              >
+                                {s.label}
+                              </span>
+                              <div
+                                className="resize l"
+                                onPointerDown={(e) => onEdgeDown(e, "l", k)}
+                              />
+                              {k + 1 < lanes.subtask.length && (
+                                <div
+                                  className="resize r"
+                                  onPointerDown={(e) => onEdgeDown(e, "r", k)}
+                                />
+                              )}
+                            </div>
+                          );
+                        })}
+
+                      {/* Drag-to-create preview rectangle (subtask only) */}
+                      {tk.render === "span-edit" && drag?.kind === "create" && (
+                        <div
+                          className="tl-create-preview"
+                          style={{
+                            left: `${(Math.min(drag.startTs ?? 0, drag.endTs ?? 0) / duration) * 100}%`,
+                            width: `${(Math.abs((drag.endTs ?? 0) - (drag.startTs ?? 0)) / duration) * 100}%`,
+                          }}
+                        />
+                      )}
+
+                      {/* Collapsed task-augmentation bar: one full-width bar
+                          (rephrasings carry no temporal info), with a ×N badge
+                          when there is more than one. Click selects the single
+                          phrasing, or opens the rewordings popover. */}
+                      {tk.render === "task-aug" &&
+                        lanes.task_aug.length > 0 &&
+                        (() => {
+                          const augs = lanes.task_aug;
+                          const primary = augs[0];
+                          const count = augs.length;
+                          return (
+                            <div
+                              className="tl-seg task_aug"
+                              style={{ left: "0%", width: "100%" }}
+                              onClick={onTaskAugClick}
+                              onMouseEnter={(e) =>
+                                showTip(
+                                  e,
+                                  `task aug · ${count} phrasing${count > 1 ? "s" : ""}`,
+                                  count > 1
+                                    ? augs.map((s) => `• ${s.label}`).join("\n")
+                                    : primary.label,
+                                )
+                              }
+                              onMouseMove={moveTip}
+                              onMouseLeave={hideTip}
+                            >
+                              <span
+                                style={{
+                                  whiteSpace: "nowrap",
+                                  overflow: "hidden",
+                                  textOverflow: "ellipsis",
+                                }}
+                              >
+                                {primary.label}
+                              </span>
+                              {count > 1 && (
+                                <span className="aug-count">×{count}</span>
+                              )}
+                            </div>
+                          );
+                        })()}
+
+                      {/* Read-only persistent spans (plan is active until its
+                          next refresh). Click seeks + selects; no resize. */}
+                      {tk.render === "span-ro" &&
+                        (
+                          lanes[tk.key as "plan"] as Array<{
+                            kind: "span";
+                            start: number;
+                            end: number;
+                            label: string;
+                            atom: LanguageAtom;
+                            atomIdx: number;
+                          }>
+                        ).map((s, k) => {
+                          const left = (s.start / duration) * 100;
+                          const width = Math.max(
+                            0.3,
+                            ((s.end - s.start) / duration) * 100,
+                          );
+                          return (
+                            <div
+                              key={k}
+                              className={`tl-seg ${tk.key}`}
+                              style={{ left: `${left}%`, width: `${width}%` }}
+                              onClick={(e) =>
+                                onSpanBodyClick(e, s.atomIdx, s.start)
+                              }
+                              onMouseEnter={(e) =>
+                                showTip(
+                                  e,
+                                  `${tk.label} · ${s.start.toFixed(2)}s → ${s.end.toFixed(2)}s`,
+                                  s.label,
+                                )
+                              }
+                              onMouseMove={moveTip}
+                              onMouseLeave={hideTip}
+                            >
+                              <span
+                                style={{
+                                  whiteSpace: "nowrap",
+                                  overflow: "hidden",
+                                  textOverflow: "ellipsis",
+                                }}
+                              >
+                                {s.label}
+                              </span>
+                            </div>
+                          );
+                        })}
+
+                      {/* Point-in-time tick markers (task_aug / memory /
+                          interjection / vqa) */}
+                      {tk.render === "tick" &&
+                        (
+                          lanes[
+                            tk.key as "memory" | "interjection" | "vqa"
+                          ] as Array<{
+                            kind: "tick";
+                            t: number;
+                            label: string;
+                            atom: LanguageAtom;
+                            atomIdx: number;
+                            subtype?: string;
+                          }>
+                        ).map((m, i) => {
+                          const left = (m.t / duration) * 100;
+                          return (
+                            <div
+                              key={i}
+                              className={`tl-tick ${tk.key}`}
+                              style={{ left: `${left}%` }}
+                              onClick={(e) => onTickClick(e, m.atomIdx, m.t)}
+                              onMouseEnter={(e) =>
+                                showTip(
+                                  e,
+                                  `${tk.label}${m.subtype ? ` · ${m.subtype}` : ""} · ${m.t.toFixed(3)}s`,
+                                  m.label,
+                                )
+                              }
+                              onMouseMove={moveTip}
+                              onMouseLeave={hideTip}
+                            />
+                          );
+                        })}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            ))}
+
+            {/* Playhead — spans the full tracks region via top/bottom. */}
+            <div className="tl-playhead" style={{ left: playheadLeft }} />
+            <div
+              className="tl-playhead-handle"
+              style={{ left: playheadLeft, top: -6 }}
+              onPointerDown={onPlayheadDown}
+              title="Drag to scrub"
+            />
+          </div>
+        );
+      })()}
+
+      {/* Tooltip */}
+      {tooltip && (
+        <div className="tl-tooltip" style={{ left: tooltip.x, top: tooltip.y }}>
+          <div className="meta">{tooltip.meta}</div>
+          {tooltip.text}
+        </div>
+      )}
+
+      {/* Drag-to-create label popup */}
+      {pendingCreate && (
+        <div
+          className="quick-popup"
+          style={{
+            left: pendingCreate.anchorX,
+            top: pendingCreate.anchorY,
+            position: "fixed",
+          }}
+        >
+          <div className="quick-popup-head">
+            <span className="style-pill subtask">subtask</span>
+            <span style={{ marginLeft: "auto", fontFamily: "monospace" }}>
+              {pendingCreate.start.toFixed(2)}s → {pendingCreate.end.toFixed(2)}
+              s
+            </span>
+          </div>
+          <input
+            type="text"
+            placeholder="label (e.g. grasp the sponge)"
+            autoFocus
+            value={createLabel}
+            onChange={(e) => setCreateLabel(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") commitPendingCreate();
+              if (e.key === "Escape") cancelPendingCreate();
+            }}
+          />
+          <div className="quick-popup-actions">
+            <button
+              onClick={cancelPendingCreate}
+              style={{
+                fontSize: 11,
+                padding: "4px 8px",
+                borderRadius: 6,
+                border: "1px solid rgba(255,255,255,0.12)",
+                background: "transparent",
+                color: "var(--fg-2, #cbd5e1)",
+                cursor: "pointer",
+              }}
+            >
+              cancel
+            </button>
+            <button
+              onClick={commitPendingCreate}
+              disabled={!createLabel.trim()}
+              style={{
+                fontSize: 11,
+                padding: "4px 8px",
+                borderRadius: 6,
+                border: "1px solid #5b8cff",
+                background: "rgba(91,140,255,0.15)",
+                color: "#c7d6ff",
+                cursor: "pointer",
+                opacity: createLabel.trim() ? 1 : 0.4,
+              }}
+            >
+              add ↵
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};

src/components/playback-bar.tsx

@@ -15,17 +15,20 @@ const PlaybackBar: React.FC = () => {
 
   const sliderActiveRef = React.useRef(false);
   const wasPlayingRef = React.useRef(false);
+  const sliderValueRef = React.useRef(currentTime);
   const [sliderValue, setSliderValue] = React.useState(currentTime);
 
   // Only update sliderValue from context if not dragging
   React.useEffect(() => {
     if (!sliderActiveRef.current) {
+      sliderValueRef.current = currentTime;
       setSliderValue(currentTime);
     }
   }, [currentTime]);
 
   const handleSliderChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     const t = Number(e.target.value);
+    sliderValueRef.current = t;
     setSliderValue(t);
     // Seek videos immediately while dragging (no debounce)
     seek(t);
@@ -40,7 +43,7 @@ const PlaybackBar: React.FC = () => {
   const handleSliderMouseUp = () => {
     sliderActiveRef.current = false;
     // Final seek to exact slider position
-    seek(sliderValue);
+    seek(sliderValueRef.current);
     if (wasPlayingRef.current) {
       setIsPlaying(true);
     }

src/components/simple-videos-player.tsx

@@ -5,6 +5,7 @@ import { useTime } from "../context/time-context";
 import { FaExpand, FaCompress, FaTimes, FaEye } from "react-icons/fa";
 import type { VideoInfo } from "@/types";
 import { proxyHfUrl } from "@/utils/auth";
+import { VideoOverlayCanvas } from "./video-overlay-canvas";
 
 const THRESHOLDS = {
   VIDEO_SYNC_TOLERANCE: 0.2,
@@ -27,6 +28,31 @@ export const SimpleVideosPlayer = ({
   const { currentTime, seek, externalSeekVersion, isPlaying, setIsPlaying } =
     useTime();
   const videoRefs = useRef<(HTMLVideoElement | null)[]>([]);
+  // Mirror videoRefs into state so the absolutely-positioned VQA overlay can
+  // re-render with the actual <video> element once it mounts. Using a ref
+  // alone means the overlay's first render still sees `null`.
+  const [videoEls, setVideoEls] = React.useState<(HTMLVideoElement | null)[]>(
+    () => [],
+  );
+  // Stable ref callbacks per index. If we used inline `(el) => { ... }` here
+  // React would re-invoke the callback on every render (the function identity
+  // changes), which combined with `setVideoEls` would toggle state on each
+  // tick and produce a "Maximum update depth exceeded" loop.
+  const videoRefCallbacksRef = useRef<
+    ((el: HTMLVideoElement | null) => void)[]
+  >([]);
+  while (videoRefCallbacksRef.current.length < videosInfo.length) {
+    const idx = videoRefCallbacksRef.current.length;
+    videoRefCallbacksRef.current.push((el: HTMLVideoElement | null) => {
+      videoRefs.current[idx] = el;
+      setVideoEls((prev) => {
+        if (prev[idx] === el) return prev;
+        const next = prev.slice();
+        next[idx] = el;
+        return next;
+      });
+    });
+  }
   const [hiddenVideos, setHiddenVideos] = React.useState<string[]>([]);
   const [enlargedVideo, setEnlargedVideo] = React.useState<string | null>(null);
   const [showHiddenMenu, setShowHiddenMenu] = React.useState(false);
@@ -369,20 +395,27 @@ export const SimpleVideosPlayer = ({
                   </button>
                 </span>
               </p>
-              <video
-                ref={(el: HTMLVideoElement | null) => {
-                  videoRefs.current[idx] = el;
-                }}
-                className={`w-full object-contain ${
-                  isEnlarged ? "max-h-[90vh] max-w-[90vw]" : ""
-                }`}
-                muted
-                preload="auto"
-                crossOrigin="anonymous"
-              >
-                <source src={proxyHfUrl(info.url)} type="video/mp4" />
-                Your browser does not support the video tag.
-              </video>
+              <div className="relative w-full">
+                <video
+                  ref={videoRefCallbacksRef.current[idx]}
+                  className={`w-full object-contain ${
+                    isEnlarged ? "max-h-[90vh] max-w-[90vw]" : ""
+                  }`}
+                  muted
+                  preload="auto"
+                  crossOrigin="anonymous"
+                >
+                  <source src={proxyHfUrl(info.url)} type="video/mp4" />
+                  Your browser does not support the video tag.
+                </video>
+                {/* VQA bbox/keypoint overlay. Reads atoms + drawMode from
+                    AnnotationsContext; pointer-events fall through when
+                    not in draw mode so video controls remain usable. */}
+                <VideoOverlayCanvas
+                  videoEl={videoEls[idx] ?? null}
+                  cameraKey={info.filename}
+                />
+              </div>
             </div>
           );
         })}

src/components/video-overlay-canvas.tsx

@@ -0,0 +1,799 @@
+"use client";
+
+/**
+ * Canvas overlay rendered on top of a single `<video>` element. Two roles:
+ *
+ * 1. Display VQA bbox/keypoint atoms whose `timestamp` matches the current
+ *    video time (within ~one frame) and whose optional `camera` field matches
+ *    this video's camera key (or has no camera, which we treat as
+ *    "render on every camera").
+ *
+ * 2. When the user is in "draw mode" — bbox or keypoint — capture mouse input
+ *    and stage a `pendingDraw` in the AnnotationsContext so the AnnotationsPanel
+ *    can pick it up and persist it as a VQA atom.
+ *
+ * Coordinates are stored in 0..1 image-relative space. Drawing is computed
+ * against the actually-rendered video rect (i.e. taking `object-contain`
+ * letterboxing into account).
+ */
+
+import React, { useEffect, useRef, useState } from "react";
+import {
+  useAnnotations,
+  type PendingBboxDraw,
+  type PendingPointDraw,
+} from "../context/annotations-context";
+import { useTime } from "../context/time-context";
+import {
+  classifyVqa,
+  parseVqaAnswer,
+  type LanguageAtom,
+  type VqaAnswer,
+} from "../types/language.types";
+
+interface Props {
+  videoEl: HTMLVideoElement | null;
+  cameraKey: string;
+}
+
+interface RenderedRect {
+  // Position of the video's actual rendered image area inside the canvas
+  // (which is positioned to fill the video's bounding box). The video uses
+  // `object-contain` so for a video aspect mismatched with its container,
+  // there's letterboxing — we need to compute the inner rect to map 0..1
+  // image-relative coordinates correctly.
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  // Source image dimensions in pixels — needed so we can also map
+  // pixel-space VQA answers (the annotation pipeline emits bboxes in
+  // ``[x_min, y_min, x_max, y_max]`` source pixels per Module 3's prompt).
+  sourceWidth: number;
+  sourceHeight: number;
+}
+
+function computeRenderedRect(
+  canvas: HTMLCanvasElement,
+  video: HTMLVideoElement,
+): RenderedRect {
+  // Use CSS dimensions, not bitmap dimensions — the canvas is HiDPI-scaled
+  // (canvas.width = cssWidth * dpr) and the 2D context already has a
+  // transform applied, so all drawing happens in CSS-pixel space.
+  const cssW = canvas.clientWidth || canvas.width;
+  const cssH = canvas.clientHeight || canvas.height;
+  const vw = video.videoWidth;
+  const vh = video.videoHeight;
+  if (!vw || !vh) {
+    // Metadata not yet loaded — fall back to the full canvas. The
+    // `loadedmetadata` listener forces a redraw the moment vw/vh are known
+    // so this fallback is short-lived.
+    return {
+      left: 0,
+      top: 0,
+      width: cssW,
+      height: cssH,
+      sourceWidth: 0,
+      sourceHeight: 0,
+    };
+  }
+  const videoAspect = vw / vh;
+  const containerAspect = cssW / cssH;
+  if (containerAspect > videoAspect) {
+    // Container is wider than the video → vertical fill, horizontal letterbox.
+    const renderedW = cssH * videoAspect;
+    return {
+      left: (cssW - renderedW) / 2,
+      top: 0,
+      width: renderedW,
+      height: cssH,
+      sourceWidth: vw,
+      sourceHeight: vh,
+    };
+  } else {
+    const renderedH = cssW / videoAspect;
+    return {
+      left: 0,
+      top: (cssH - renderedH) / 2,
+      width: cssW,
+      height: renderedH,
+      sourceWidth: vw,
+      sourceHeight: vh,
+    };
+  }
+}
+
+const GROUNDING_COORDINATE_SCALE = 1000;
+
+function isUnitCoord(x: number, y: number): boolean {
+  return Math.max(Math.abs(x), Math.abs(y)) <= 1.5;
+}
+
+function isGroundingCoord(x: number, y: number): boolean {
+  return (
+    Math.max(Math.abs(x), Math.abs(y)) <= GROUNDING_COORDINATE_SCALE &&
+    Math.max(Math.abs(x), Math.abs(y)) > 1.5
+  );
+}
+
+function mapPointToCanvas(
+  rect: RenderedRect,
+  x: number,
+  y: number,
+): [number, number] {
+  if (isUnitCoord(x, y)) {
+    return [rect.left + x * rect.width, rect.top + y * rect.height];
+  }
+
+  // Model-generated grounding annotations commonly use a 0..1000 image grid.
+  // The videos are often lower resolution, so treating those values as source
+  // pixels makes boxes/points too large after rendering.
+  const scaleX = isGroundingCoord(x, y)
+    ? GROUNDING_COORDINATE_SCALE
+    : rect.sourceWidth || rect.width;
+  const scaleY = isGroundingCoord(x, y)
+    ? GROUNDING_COORDINATE_SCALE
+    : rect.sourceHeight || rect.height;
+
+  return [
+    rect.left + (x / scaleX) * rect.width,
+    rect.top + (y / scaleY) * rect.height,
+  ];
+}
+
+function drawBbox(
+  ctx: CanvasRenderingContext2D,
+  rect: RenderedRect,
+  bbox: [number, number, number, number],
+  bboxFormat: string,
+  label: string,
+  color: string,
+) {
+  const [bx1, by1, bx2, by2] = bbox;
+  const x1 = bx1;
+  const y1 = by1;
+  let x2 = bx2;
+  let y2 = by2;
+  if (bboxFormat === "xywh") {
+    x2 = x1 + bx2;
+    y2 = y1 + by2;
+  }
+  const [px1, py1] = mapPointToCanvas(rect, x1, y1);
+  const [px2, py2] = mapPointToCanvas(rect, x2, y2);
+  ctx.lineWidth = 2;
+  ctx.strokeStyle = color;
+  ctx.fillStyle = color + "26"; // ~15% alpha
+  ctx.fillRect(px1, py1, px2 - px1, py2 - py1);
+  ctx.strokeRect(px1, py1, px2 - px1, py2 - py1);
+  if (label) {
+    ctx.font = "12px ui-sans-serif, system-ui";
+    const m = ctx.measureText(label);
+    ctx.fillStyle = "#0b0e14";
+    ctx.fillRect(px1, py1 - 16, m.width + 8, 16);
+    ctx.fillStyle = color;
+    ctx.fillText(label, px1 + 4, py1 - 4);
+  }
+}
+
+function drawPoint(
+  ctx: CanvasRenderingContext2D,
+  rect: RenderedRect,
+  point: [number, number],
+  label: string,
+  color: string,
+) {
+  const [x, y] = point;
+  const [px, py] = mapPointToCanvas(rect, x, y);
+  ctx.lineWidth = 2;
+  ctx.strokeStyle = color;
+  ctx.fillStyle = color;
+  ctx.beginPath();
+  ctx.arc(px, py, 5, 0, Math.PI * 2);
+  ctx.fill();
+  ctx.beginPath();
+  ctx.arc(px, py, 11, 0, Math.PI * 2);
+  ctx.stroke();
+  if (label) {
+    ctx.font = "12px ui-sans-serif, system-ui";
+    const m = ctx.measureText(label);
+    ctx.fillStyle = "#0b0e14";
+    ctx.fillRect(px + 8, py - 18, m.width + 8, 16);
+    ctx.fillStyle = color;
+    ctx.fillText(label, px + 12, py - 6);
+  }
+}
+
+function vqaMatchesCamera(answer: VqaAnswer, cameraKey: string): boolean {
+  // If the answer doesn't carry a camera field, render it on every camera.
+  // If it does, only render where it matches.
+  const kind = classifyVqa(answer);
+  if (kind === "bbox") {
+    const dets = (answer as { detections: Array<{ camera?: string }> })
+      .detections;
+    if (!dets.length) return false;
+    return dets.some((d) => !d.camera || d.camera === cameraKey);
+  }
+  if (kind === "keypoint") {
+    const c = (answer as { camera?: string }).camera;
+    return !c || c === cameraKey;
+  }
+  return false; // other VQA kinds aren't drawn
+}
+
+/** Pixel distance below which a pointer up counts as a click, not a drag. */
+const CLICK_THRESHOLD_PX = 4;
+
+interface FinalizingState {
+  /** Where the popup anchors itself, in canvas-relative pixels (top-right of bbox / right of point). */
+  anchor: { x: number; y: number };
+  /** What the user just drew (label/camera filled in on submit). */
+  draw:
+    | Pick<PendingBboxDraw, "kind" | "bbox">
+    | Pick<PendingPointDraw, "kind" | "point">;
+}
+
+export const VideoOverlayCanvas: React.FC<Props> = ({ videoEl, cameraKey }) => {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const {
+    atoms,
+    setPendingDraw,
+    pendingDraw,
+    drawMode: ctxDrawMode,
+    drawLabel,
+    activeCamera,
+    setActiveCamera,
+    setActiveVideoEl,
+    snap,
+    addAtoms,
+    clearPendingDraw,
+    selectedIdx,
+  } = useAnnotations();
+  // Register this camera's <video> as the "active" one so the panel can read
+  // its authoritative `currentTime` instead of the throttled context value
+  // when adding annotations.
+  useEffect(() => {
+    if (activeCamera === cameraKey) {
+      setActiveVideoEl(videoEl);
+      return () => setActiveVideoEl(null);
+    }
+  }, [activeCamera, cameraKey, videoEl, setActiveVideoEl]);
+  const drawMode = ctxDrawMode;
+  const { currentTime, isPlaying } = useTime();
+  // Pointer-down origin in canvas pixels and 0..1 image-relative coords.
+  const dragOriginRef = useRef<{
+    px: [number, number];
+    norm: [number, number];
+  } | null>(null);
+  const [dragMoved, setDragMoved] = useState(false);
+  const [finalizing, setFinalizing] = useState<FinalizingState | null>(null);
+  const [labelInput, setLabelInput] = useState("");
+  const [questionKind, setQuestionKind] = useState<"detect" | "point">(
+    "detect",
+  );
+
+  // Keep the canvas exactly aligned with the video. Two listeners:
+  //   - ResizeObserver picks up CSS resize.
+  //   - `loadedmetadata` picks up the moment `video.videoWidth` becomes
+  //     non-zero so `computeRenderedRect` stops returning the full-canvas
+  //     fallback (which is what causes drawn bboxes to land in the wrong
+  //     spot when the user starts annotating before metadata arrives).
+  useEffect(() => {
+    if (!videoEl || !canvasRef.current) return;
+    const canvas = canvasRef.current;
+    const sync = () => {
+      const r = videoEl.getBoundingClientRect();
+      // Use the device-pixel ratio for crisp drawing on HiDPI displays.
+      const dpr = window.devicePixelRatio || 1;
+      const w = Math.max(1, Math.round(r.width));
+      const h = Math.max(1, Math.round(r.height));
+      canvas.width = Math.round(w * dpr);
+      canvas.height = Math.round(h * dpr);
+      canvas.style.width = `${w}px`;
+      canvas.style.height = `${h}px`;
+      const ctx = canvas.getContext("2d");
+      if (ctx) ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+      redraw();
+    };
+    const ro = new ResizeObserver(sync);
+    ro.observe(videoEl);
+    videoEl.addEventListener("loadedmetadata", sync);
+    videoEl.addEventListener("loadeddata", sync);
+    sync();
+    return () => {
+      ro.disconnect();
+      videoEl.removeEventListener("loadedmetadata", sync);
+      videoEl.removeEventListener("loadeddata", sync);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [videoEl]);
+
+  const redraw = React.useCallback(() => {
+    const canvas = canvasRef.current;
+    if (!canvas || !videoEl) return;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+    // clearRect is in CSS-px after the dpr transform is applied; using the
+    // bitmap dims here would clear a region too large but still works.
+    ctx.clearRect(
+      0,
+      0,
+      canvas.clientWidth || canvas.width,
+      canvas.clientHeight || canvas.height,
+    );
+    const rect = computeRenderedRect(canvas, videoEl);
+
+    // Saved VQA atoms within ~one frame of currentTime. We compare against
+    // the episode-local `currentTime` from useTime(), not the <video>'s
+    // `currentTime`, because the latter is in *global* video-file time for
+    // segmented (concatenated) videos.
+    const selectedAtom =
+      selectedIdx != null && selectedIdx >= 0 && selectedIdx < atoms.length
+        ? atoms[selectedIdx]
+        : null;
+    const matches: LanguageAtom[] = atoms.filter((a, idx) => {
+      if (a.style !== "vqa" || a.role !== "assistant") return false;
+      const isSelectedAnswer =
+        idx === selectedIdx ||
+        (selectedAtom?.style === "vqa" &&
+          selectedAtom.role === "user" &&
+          selectedAtom.timestamp === a.timestamp &&
+          selectedAtom.camera === a.camera);
+      const isCurrentFrame = Math.abs(a.timestamp - (currentTime || 0)) < 0.05;
+      if (!isCurrentFrame && !(isSelectedAnswer && !isPlaying)) return false;
+      // Row-level camera is authoritative (lerobot PR 3467). Camera-agnostic
+      // atoms (a.camera == null) draw on every camera.
+      return a.camera == null || a.camera === cameraKey;
+    });
+    for (const atom of matches) {
+      const ans = parseVqaAnswer(atom.content);
+      if (!ans) continue;
+      // For atoms that already carry a row-level camera tag, the filter above
+      // is sufficient. The legacy in-payload camera field still matters for
+      // pre-PR-3467 annotations the user may have on disk — keep the fallback
+      // check so old datasets don't suddenly render on every camera.
+      if (atom.camera == null && !vqaMatchesCamera(ans, cameraKey)) continue;
+      const kind = classifyVqa(ans);
+      if (kind === "bbox") {
+        const dets = (ans as { detections: Array<unknown> })
+          .detections as Array<{
+          label?: string;
+          bbox: [number, number, number, number];
+          bbox_format?: string;
+          camera?: string;
+        }>;
+        for (const d of dets) {
+          if (d.camera && d.camera !== cameraKey) continue;
+          drawBbox(
+            ctx,
+            rect,
+            d.bbox,
+            d.bbox_format || "xyxy",
+            d.label || "",
+            "#22d3ee",
+          );
+        }
+      } else if (kind === "keypoint") {
+        const k = ans as { point: [number, number]; label?: string };
+        drawPoint(ctx, rect, k.point, k.label || "", "#facc15");
+      }
+    }
+
+    // Pending (in-progress) draw for this camera.
+    if (
+      pendingDraw &&
+      (!pendingDraw.camera || pendingDraw.camera === cameraKey)
+    ) {
+      if (pendingDraw.kind === "bbox") {
+        drawBbox(
+          ctx,
+          rect,
+          pendingDraw.bbox,
+          "xyxy",
+          pendingDraw.label || "",
+          "#f97316",
+        );
+      } else {
+        drawPoint(
+          ctx,
+          rect,
+          pendingDraw.point,
+          pendingDraw.label || "",
+          "#f97316",
+        );
+      }
+    }
+  }, [
+    atoms,
+    pendingDraw,
+    cameraKey,
+    videoEl,
+    currentTime,
+    selectedIdx,
+    isPlaying,
+  ]);
+
+  // Redraw on time tick / atoms / pendingDraw / videoEl changes.
+  useEffect(() => {
+    redraw();
+  }, [redraw, currentTime]);
+
+  // Also redraw the moment the video reports a seek completing — the
+  // throttled `currentTime` from TimeContext can lag a paused frame by enough
+  // that the overlay first paints empty. Listening directly to `seeked`
+  // closes that gap so bbox/keypoint atoms appear instantly after jumping.
+  useEffect(() => {
+    if (!videoEl) return;
+    const onSeeked = () => redraw();
+    videoEl.addEventListener("seeked", onSeeked);
+    return () => videoEl.removeEventListener("seeked", onSeeked);
+  }, [videoEl, redraw]);
+
+  // Pointer handlers. The disambiguation:
+  //   - drawMode "auto":     drag (>4px) → bbox; release without dragging → keypoint
+  //   - drawMode "bbox":     drag → bbox (no implicit keypoint)
+  //   - drawMode "keypoint": down-then-up at same spot → keypoint
+  const onPointerDown = (e: React.PointerEvent<HTMLCanvasElement>) => {
+    if (drawMode === "off") return;
+    const canvas = canvasRef.current;
+    if (!canvas || !videoEl) return;
+    if (finalizing) return; // wait for the user to confirm/cancel current draw
+    e.preventDefault();
+    setActiveCamera(cameraKey);
+    setActiveVideoEl(videoEl);
+    canvas.setPointerCapture(e.pointerId);
+    const rect = computeRenderedRect(canvas, videoEl);
+    const cr = canvas.getBoundingClientRect();
+    const px: [number, number] = [e.clientX - cr.left, e.clientY - cr.top];
+    const norm: [number, number] = [
+      Math.max(0, Math.min(1, (px[0] - rect.left) / rect.width)),
+      Math.max(0, Math.min(1, (px[1] - rect.top) / rect.height)),
+    ];
+    dragOriginRef.current = { px, norm };
+    setDragMoved(false);
+    // Start a tentative bbox-shaped pendingDraw; if the user releases without
+    // moving (auto/keypoint mode) we'll flip it to a keypoint on pointerup.
+    setPendingDraw({
+      kind: "bbox",
+      bbox: [norm[0], norm[1], norm[0], norm[1]],
+      label: drawLabel || "",
+      camera: cameraKey,
+    });
+  };
+
+  const onPointerMove = (e: React.PointerEvent<HTMLCanvasElement>) => {
+    if (drawMode === "off" || !dragOriginRef.current) return;
+    const canvas = canvasRef.current;
+    if (!canvas || !videoEl) return;
+    const rect = computeRenderedRect(canvas, videoEl);
+    const cr = canvas.getBoundingClientRect();
+    const cx = e.clientX - cr.left;
+    const cy = e.clientY - cr.top;
+    const dx = cx - dragOriginRef.current.px[0];
+    const dy = cy - dragOriginRef.current.px[1];
+    if (
+      !dragMoved &&
+      Math.hypot(dx, dy) > CLICK_THRESHOLD_PX &&
+      drawMode !== "keypoint"
+    ) {
+      setDragMoved(true);
+    }
+    if (drawMode === "keypoint") return;
+    const x = Math.max(0, Math.min(1, (cx - rect.left) / rect.width));
+    const y = Math.max(0, Math.min(1, (cy - rect.top) / rect.height));
+    const start = dragOriginRef.current.norm;
+    setPendingDraw({
+      kind: "bbox",
+      bbox: [
+        Math.min(start[0], x),
+        Math.min(start[1], y),
+        Math.max(start[0], x),
+        Math.max(start[1], y),
+      ],
+      label: drawLabel || "",
+      camera: cameraKey,
+    });
+  };
+
+  const onPointerUp = (e: React.PointerEvent<HTMLCanvasElement>) => {
+    if (drawMode === "off" || !dragOriginRef.current) {
+      dragOriginRef.current = null;
+      setDragMoved(false);
+      return;
+    }
+    const canvas = canvasRef.current;
+    if (!canvas || !videoEl) {
+      dragOriginRef.current = null;
+      setDragMoved(false);
+      return;
+    }
+    const rect = computeRenderedRect(canvas, videoEl);
+    const cr = canvas.getBoundingClientRect();
+    const cx = e.clientX - cr.left;
+    const cy = e.clientY - cr.top;
+
+    // Decide the gesture's kind.
+    const treatAsBbox =
+      drawMode === "bbox" || (drawMode === "auto" && dragMoved);
+
+    if (treatAsBbox) {
+      const x = Math.max(0, Math.min(1, (cx - rect.left) / rect.width));
+      const y = Math.max(0, Math.min(1, (cy - rect.top) / rect.height));
+      const start = dragOriginRef.current.norm;
+      const bbox: [number, number, number, number] = [
+        Math.min(start[0], x),
+        Math.min(start[1], y),
+        Math.max(start[0], x),
+        Math.max(start[1], y),
+      ];
+      // Anchor popup at the bbox top-right in canvas-px space.
+      setPendingDraw({
+        kind: "bbox",
+        bbox,
+        label: drawLabel || "",
+        camera: cameraKey,
+      });
+      setFinalizing({
+        anchor: {
+          x: rect.left + bbox[2] * rect.width,
+          y: rect.top + bbox[1] * rect.height,
+        },
+        draw: { kind: "bbox", bbox },
+      });
+      setQuestionKind("detect");
+    } else {
+      // Click → keypoint at the up position.
+      const x = Math.max(0, Math.min(1, (cx - rect.left) / rect.width));
+      const y = Math.max(0, Math.min(1, (cy - rect.top) / rect.height));
+      const point: [number, number] = [x, y];
+      setPendingDraw({
+        kind: "keypoint",
+        point,
+        label: drawLabel || "",
+        camera: cameraKey,
+      });
+      setFinalizing({
+        anchor: {
+          x: rect.left + point[0] * rect.width + 14,
+          y: rect.top + point[1] * rect.height,
+        },
+        draw: { kind: "keypoint", point },
+      });
+      setQuestionKind("point");
+    }
+    dragOriginRef.current = null;
+    setDragMoved(false);
+  };
+
+  const onPointerCancel = () => {
+    dragOriginRef.current = null;
+    setDragMoved(false);
+  };
+
+  const closeFinalize = React.useCallback(() => {
+    setFinalizing(null);
+    setLabelInput("");
+    clearPendingDraw();
+  }, [clearPendingDraw]);
+
+  const submitFinalize = () => {
+    if (!finalizing) return;
+    const label = labelInput.trim();
+    if (!label) return;
+    // Episode-local time only — `videoEl.currentTime` is the *global* time
+    // inside a shared/concatenated video file, which would push every
+    // annotation past the parquet's [0..duration] frame range and collapse
+    // them to the boundary on snap. `currentTime` from useTime() is already
+    // normalized to episode-local space by SimpleVideosPlayer.
+    const ts = snap(currentTime);
+    const question =
+      questionKind === "point"
+        ? `Point to the ${label}.`
+        : `Where is the ${label} in the image?`;
+    let answer:
+      | {
+          detections: Array<{
+            label: string;
+            bbox_format: "xyxy";
+            bbox: [number, number, number, number];
+            camera?: string;
+          }>;
+        }
+      | {
+          label: string;
+          point_format: "xy";
+          point: [number, number];
+          camera?: string;
+        };
+    if (finalizing.draw.kind === "bbox") {
+      answer = {
+        detections: [
+          {
+            label,
+            bbox_format: "xyxy",
+            bbox: finalizing.draw.bbox.map((v) => Number(v.toFixed(4))) as [
+              number,
+              number,
+              number,
+              number,
+            ],
+            camera: cameraKey,
+          },
+        ],
+      };
+    } else {
+      answer = {
+        label,
+        point_format: "xy",
+        point: finalizing.draw.point.map((v) => Number(v.toFixed(4))) as [
+          number,
+          number,
+        ],
+        camera: cameraKey,
+      };
+    }
+    addAtoms([
+      {
+        role: "user",
+        content: question,
+        style: "vqa",
+        timestamp: ts,
+        camera: cameraKey,
+        tool_calls: null,
+      },
+      {
+        role: "assistant",
+        content: JSON.stringify(answer),
+        style: "vqa",
+        timestamp: ts,
+        camera: cameraKey,
+        tool_calls: null,
+      },
+    ]);
+    closeFinalize();
+  };
+
+  // ESC / click-outside to cancel the popup.
+  useEffect(() => {
+    if (!finalizing) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") closeFinalize();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [finalizing, closeFinalize]);
+
+  return (
+    <>
+      <canvas
+        ref={canvasRef}
+        onPointerDown={onPointerDown}
+        onPointerMove={onPointerMove}
+        onPointerUp={onPointerUp}
+        onPointerCancel={onPointerCancel}
+        style={{
+          position: "absolute",
+          inset: 0,
+          pointerEvents: drawMode === "off" ? "none" : "auto",
+          cursor:
+            drawMode === "off"
+              ? "default"
+              : drawMode === "keypoint"
+                ? "pointer"
+                : "crosshair",
+        }}
+      />
+      {finalizing && (
+        <QuickLabelPopup
+          anchor={finalizing.anchor}
+          kind={finalizing.draw.kind}
+          questionKind={questionKind}
+          onQuestionKindChange={setQuestionKind}
+          label={labelInput}
+          onLabelChange={setLabelInput}
+          onSubmit={submitFinalize}
+          onCancel={closeFinalize}
+        />
+      )}
+    </>
+  );
+};
+
+/**
+ * Floating "what is this?" popup that appears next to a freshly drawn bbox or
+ * keypoint. The label gets templated into a question — bbox → "Where is the X
+ * in the image?", keypoint → "Point to the X." — and the assistant message
+ * carries the JSON answer the steerable validator expects.
+ */
+const QuickLabelPopup: React.FC<{
+  anchor: { x: number; y: number };
+  kind: "bbox" | "keypoint";
+  questionKind: "detect" | "point";
+  onQuestionKindChange: (k: "detect" | "point") => void;
+  label: string;
+  onLabelChange: (s: string) => void;
+  onSubmit: () => void;
+  onCancel: () => void;
+}> = ({
+  anchor,
+  kind,
+  questionKind,
+  onQuestionKindChange,
+  label,
+  onLabelChange,
+  onSubmit,
+  onCancel,
+}) => {
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const popupRef = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+  // Position the popup just to the right of the bbox/point anchor, but flip
+  // to the left when it would overflow the parent's right edge so it stays
+  // visible for bboxes drawn near the right side of the video. Uses
+  // useLayoutEffect so the measurement + reposition happens before the
+  // browser paints — no flicker.
+  React.useLayoutEffect(() => {
+    const popup = popupRef.current;
+    const parent = popup?.parentElement;
+    if (!popup || !parent) return;
+    const popW = popup.offsetWidth;
+    const popH = popup.offsetHeight;
+    const parW = parent.clientWidth;
+    const parH = parent.clientHeight;
+    const desiredLeft = anchor.x + 6;
+    const overflowsRight = desiredLeft + popW > parW - 4;
+    const finalLeft = overflowsRight
+      ? Math.max(4, anchor.x - popW - 6)
+      : Math.max(4, desiredLeft);
+    const finalTop = Math.max(4, Math.min(parH - popH - 4, anchor.y - 4));
+    popup.style.left = `${finalLeft}px`;
+    popup.style.top = `${finalTop}px`;
+  }, [anchor.x, anchor.y]);
+  return (
+    <div
+      ref={popupRef}
+      className="quick-popup"
+      onPointerDown={(e) => e.stopPropagation()}
+    >
+      <div className="quick-popup-head">
+        <span className={`kind-pill ${kind}`}>{kind}</span>
+        <select
+          value={questionKind}
+          onChange={(e) =>
+            onQuestionKindChange(e.target.value as "detect" | "point")
+          }
+          style={{ marginLeft: "auto" }}
+        >
+          <option value="detect">where is …?</option>
+          <option value="point">point to …</option>
+        </select>
+      </div>
+      <input
+        ref={inputRef}
+        type="text"
+        placeholder={
+          kind === "bbox" ? "label (e.g. carrot)" : "label (e.g. handle)"
+        }
+        value={label}
+        onChange={(e) => onLabelChange(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === "Enter") onSubmit();
+          if (e.key === "Escape") onCancel();
+        }}
+      />
+      <div className="quick-popup-actions">
+        <button onClick={onCancel} className="popup-btn">
+          cancel
+        </button>
+        <button
+          onClick={onSubmit}
+          disabled={!label.trim()}
+          className="popup-btn primary"
+        >
+          add ↵
+        </button>
+      </div>
+    </div>
+  );
+};

src/context/annotations-context.tsx

@@ -0,0 +1,404 @@
+"use client";
+
+/**
+ * Per-episode annotation state for the v3.1 language schema.
+ *
+ * - Atoms live in memory + sessionStorage so the user can browse without a
+ *   backend (read/edit, but no parquet rewrite).
+ * - When `NEXT_PUBLIC_ANNOTATE_BACKEND_URL` is set, the context syncs with
+ *   the FastAPI service in `backend/`: GET on episode entry, POST on save,
+ *   plus frame-timestamp fetches used to snap event-style atoms to exact
+ *   source-frame timestamps (the writer in lerobot#3471 enforces exact match).
+ *
+ * - VQA drawings (active `pendingDraw`) live here too so the panel and the
+ *   video overlay component share a single source of truth.
+ */
+
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type { LanguageAtom } from "../types/language.types";
+import { snapToFrame } from "../types/language.types";
+import {
+  fetchEpisodeAtoms,
+  saveEpisodeAtoms,
+  fetchFrameTimestamps,
+  isAnnotateBackendEnabled,
+} from "../utils/annotationsClient";
+
+const STORAGE_PREFIX = "lerobot-annotations:v2:";
+
+function storageKey(repoOrPath: string, episodeId: number): string {
+  return `${STORAGE_PREFIX}${repoOrPath}::${episodeId}`;
+}
+
+export interface PendingBboxDraw {
+  kind: "bbox";
+  bbox: [number, number, number, number]; // 0..1, image-relative
+  label: string;
+  camera?: string;
+}
+
+export interface PendingPointDraw {
+  kind: "keypoint";
+  point: [number, number]; // 0..1, image-relative
+  label: string;
+  camera?: string;
+}
+
+export type PendingDraw = PendingBboxDraw | PendingPointDraw | null;
+/**
+ * `"auto"` — drag = bbox, single click = keypoint (the natural mode the
+ * Annotations tab boots into). The other values force a single gesture
+ * and exist for the legacy panel-driven flow.
+ */
+export type DrawMode = "off" | "auto" | "bbox" | "keypoint";
+
+interface DatasetIdent {
+  repoId?: string | null;
+  localPath?: string | null;
+  revision?: string | null;
+}
+
+interface AnnotationsContextType {
+  episodeId: number | null;
+  ident: DatasetIdent;
+  atoms: LanguageAtom[];
+  frameTimestamps: number[];
+  /**
+   * Index in `atoms` of the currently selected atom (the one the right-rail
+   * editor is bound to). `null` means nothing is selected — the editor shows
+   * an empty state. Selection survives content edits because we mutate atoms
+   * in place at the same index; we clear it on delete or when atoms reset.
+   */
+  selectedIdx: number | null;
+  selectAtom: (idx: number | null) => void;
+  /**
+   * Active <video> element for the camera the user is currently drawing on.
+   * Registered by `VideoOverlayCanvas`. Used by the panel to read the
+   * authoritative `currentTime` (the time-context's value is throttled and
+   * can lag the real video by tens of ms — enough to land an annotation on
+   * the wrong frame after a snap to the nearest frame timestamp).
+   */
+  activeVideoEl: HTMLVideoElement | null;
+  setActiveVideoEl: (el: HTMLVideoElement | null) => void;
+  pendingDraw: PendingDraw;
+  // Selected camera for the drawing overlay (e.g. "observation.images.top").
+  // Determines which video the next drawn bbox/point should be associated with.
+  activeCamera: string | null;
+  drawMode: DrawMode;
+  drawLabel: string;
+  backendEnabled: boolean;
+  dirty: boolean;
+  saving: boolean;
+
+  setEpisode: (
+    episodeId: number,
+    ident: DatasetIdent,
+    initialAtoms?: LanguageAtom[],
+    initialFrameTimestamps?: number[],
+  ) => void;
+  setActiveCamera: (camera: string | null) => void;
+  setDrawMode: (mode: DrawMode) => void;
+  setDrawLabel: (label: string) => void;
+
+  addAtom: (atom: LanguageAtom) => void;
+  addAtoms: (atoms: LanguageAtom[]) => void;
+  updateAtom: (index: number, updates: Partial<LanguageAtom>) => void;
+  deleteAtom: (atom: LanguageAtom) => void;
+  resetAtoms: () => void;
+
+  setPendingDraw: (draw: PendingDraw) => void;
+  clearPendingDraw: () => void;
+
+  save: () => Promise<{ ok: boolean; error?: string; path?: string | null }>;
+  // Snap an arbitrary timestamp to the nearest source frame (when known).
+  snap: (ts: number) => number;
+}
+
+const AnnotationsContext = createContext<AnnotationsContextType | undefined>(
+  undefined,
+);
+
+export function useAnnotations(): AnnotationsContextType {
+  const ctx = useContext(AnnotationsContext);
+  if (!ctx) {
+    throw new Error("useAnnotations must be used within AnnotationsProvider");
+  }
+  return ctx;
+}
+
+function identKey(ident: DatasetIdent): string {
+  return ident.localPath || ident.repoId || "unknown";
+}
+
+export const AnnotationsProvider: React.FC<{ children: React.ReactNode }> = ({
+  children,
+}) => {
+  const [episodeId, setEpisodeId] = useState<number | null>(null);
+  const [ident, setIdent] = useState<DatasetIdent>({});
+  const [atoms, setAtoms] = useState<LanguageAtom[]>([]);
+  const [frameTimestamps, setFrameTimestamps] = useState<number[]>([]);
+  const [pendingDraw, setPendingDrawState] = useState<PendingDraw>(null);
+  const [activeCamera, setActiveCameraState] = useState<string | null>(null);
+  const [drawMode, setDrawModeState] = useState<DrawMode>("off");
+  const [drawLabel, setDrawLabelState] = useState<string>("");
+  const [activeVideoEl, setActiveVideoElState] =
+    useState<HTMLVideoElement | null>(null);
+  const [selectedIdx, setSelectedIdxState] = useState<number | null>(null);
+  const [dirty, setDirty] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const backendEnabled = isAnnotateBackendEnabled();
+
+  // Track the last saved snapshot to detect dirtiness honestly.
+  const savedSnapshotRef = useRef<string>("[]");
+
+  // Hydrate from sessionStorage when episode/ident changes; if the backend
+  // is enabled, also fetch authoritative atoms + frame timestamps.
+  const setEpisode = useCallback(
+    (
+      newEpisodeId: number,
+      newIdent: DatasetIdent,
+      initialAtoms?: LanguageAtom[],
+      initialFrameTimestamps?: number[],
+    ) => {
+      setEpisodeId(newEpisodeId);
+      setIdent(newIdent);
+      setPendingDrawState(null);
+      setSelectedIdxState(null);
+
+      // Hydrate from session first (so user edits survive episode toggles).
+      // If session is empty, fall back to initialAtoms (parquet-extracted).
+      let initial: LanguageAtom[] = [];
+      try {
+        const raw = sessionStorage.getItem(
+          storageKey(identKey(newIdent), newEpisodeId),
+        );
+        if (raw) initial = JSON.parse(raw) as LanguageAtom[];
+      } catch {
+        /* ignore */
+      }
+      if (initial.length === 0 && initialAtoms && initialAtoms.length > 0) {
+        initial = initialAtoms;
+      }
+      setAtoms(initial);
+      savedSnapshotRef.current = JSON.stringify(initial);
+      setDirty(false);
+      // Seed frame timestamps from the parquet (no backend dependency); the
+      // backend will optionally overwrite this below.
+      setFrameTimestamps(initialFrameTimestamps ?? []);
+
+      // Fetch from backend if available.
+      if (isAnnotateBackendEnabled()) {
+        fetchEpisodeAtoms(newEpisodeId, newIdent)
+          .then((remoteAtoms) => {
+            // Prefer backend if it has anything; otherwise keep session-cached
+            // edits the user made before the backend came online.
+            if (remoteAtoms && remoteAtoms.length > 0) {
+              setAtoms(remoteAtoms);
+              savedSnapshotRef.current = JSON.stringify(remoteAtoms);
+              setDirty(false);
+            }
+          })
+          .catch(() => {
+            /* backend offline — silent fallback to sessionStorage */
+          });
+
+        fetchFrameTimestamps(newEpisodeId, newIdent)
+          .then(setFrameTimestamps)
+          .catch(() => setFrameTimestamps([]));
+      }
+    },
+    [],
+  );
+
+  // Persist to sessionStorage on every change once we have an episode.
+  useEffect(() => {
+    if (episodeId == null) return;
+    try {
+      sessionStorage.setItem(
+        storageKey(identKey(ident), episodeId),
+        JSON.stringify(atoms),
+      );
+    } catch {
+      /* ignore */
+    }
+    setDirty(JSON.stringify(atoms) !== savedSnapshotRef.current);
+  }, [atoms, episodeId, ident]);
+
+  const snap = useCallback(
+    (ts: number) =>
+      frameTimestamps.length > 0 ? snapToFrame(frameTimestamps, ts) : ts,
+    [frameTimestamps],
+  );
+
+  const addAtom = useCallback((atom: LanguageAtom) => {
+    setAtoms((prev) => [...prev, atom]);
+  }, []);
+
+  const addAtoms = useCallback((newAtoms: LanguageAtom[]) => {
+    setAtoms((prev) => [...prev, ...newAtoms]);
+  }, []);
+
+  const updateAtom = useCallback(
+    (index: number, updates: Partial<LanguageAtom>) => {
+      setAtoms((prev) => {
+        if (index < 0 || index >= prev.length) return prev;
+        const next = prev.slice();
+        next[index] = { ...next[index], ...updates };
+        return next;
+      });
+    },
+    [],
+  );
+
+  const deleteAtom = useCallback((atom: LanguageAtom) => {
+    setAtoms((prev) => {
+      const next = prev.filter((a) => a !== atom);
+      // If the deleted index was selected (or the selected index was after the
+      // deleted one), nudge selection so it remains pointing at a valid atom
+      // — or null when the list is empty.
+      setSelectedIdxState((cur) => {
+        if (cur == null) return null;
+        const oldIdx = prev.indexOf(atom);
+        if (oldIdx < 0) return cur;
+        if (cur === oldIdx) return null;
+        if (cur > oldIdx) return cur - 1;
+        return cur;
+      });
+      return next;
+    });
+  }, []);
+
+  const resetAtoms = useCallback(() => {
+    setAtoms([]);
+    setSelectedIdxState(null);
+  }, []);
+
+  const setPendingDraw = useCallback((draw: PendingDraw) => {
+    setPendingDrawState(draw);
+  }, []);
+
+  const clearPendingDraw = useCallback(() => setPendingDrawState(null), []);
+
+  const setActiveCamera = useCallback((c: string | null) => {
+    setActiveCameraState(c);
+  }, []);
+
+  const setDrawMode = useCallback((m: DrawMode) => setDrawModeState(m), []);
+  const setDrawLabel = useCallback((l: string) => setDrawLabelState(l), []);
+  const setActiveVideoEl = useCallback(
+    (el: HTMLVideoElement | null) => setActiveVideoElState(el),
+    [],
+  );
+
+  const selectAtom = useCallback(
+    (idx: number | null) => setSelectedIdxState(idx),
+    [],
+  );
+
+  const save = useCallback(async (): Promise<{
+    ok: boolean;
+    error?: string;
+    path?: string | null;
+  }> => {
+    if (episodeId == null) return { ok: false, error: "no episode" };
+    if (!isAnnotateBackendEnabled()) {
+      // Persistence is sessionStorage-only — that already happened in the
+      // effect above. Report the storage key as the location so the UI can
+      // show a concrete "path" instead of a vague offline message.
+      savedSnapshotRef.current = JSON.stringify(atoms);
+      setDirty(false);
+      return {
+        ok: true,
+        path: `sessionStorage://${storageKey(identKey(ident), episodeId)}`,
+      };
+    }
+    setSaving(true);
+    try {
+      const { path } = await saveEpisodeAtoms(episodeId, ident, atoms);
+      savedSnapshotRef.current = JSON.stringify(atoms);
+      setDirty(false);
+      return { ok: true, path };
+    } catch (e) {
+      return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    } finally {
+      setSaving(false);
+    }
+  }, [atoms, episodeId, ident]);
+
+  const value = useMemo<AnnotationsContextType>(
+    () => ({
+      episodeId,
+      ident,
+      atoms,
+      frameTimestamps,
+      pendingDraw,
+      activeCamera,
+      activeVideoEl,
+      setActiveVideoEl,
+      drawMode,
+      drawLabel,
+      selectedIdx,
+      selectAtom,
+      backendEnabled,
+      dirty,
+      saving,
+      setEpisode,
+      setActiveCamera,
+      setDrawMode,
+      setDrawLabel,
+      addAtom,
+      addAtoms,
+      updateAtom,
+      deleteAtom,
+      resetAtoms,
+      setPendingDraw,
+      clearPendingDraw,
+      save,
+      snap,
+    }),
+    [
+      episodeId,
+      ident,
+      atoms,
+      frameTimestamps,
+      pendingDraw,
+      activeCamera,
+      activeVideoEl,
+      setActiveVideoEl,
+      drawMode,
+      drawLabel,
+      selectedIdx,
+      selectAtom,
+      backendEnabled,
+      dirty,
+      saving,
+      setEpisode,
+      setActiveCamera,
+      setDrawMode,
+      setDrawLabel,
+      addAtom,
+      addAtoms,
+      updateAtom,
+      deleteAtom,
+      resetAtoms,
+      setPendingDraw,
+      clearPendingDraw,
+      save,
+      snap,
+    ],
+  );
+
+  return (
+    <AnnotationsContext.Provider value={value}>
+      {children}
+    </AnnotationsContext.Provider>
+  );
+};

src/context/time-context.tsx

@@ -64,7 +64,10 @@ export const TimeProvider: React.FC<{
       listeners.current.forEach((fn) => fn(t));
 
       if (source === "external") {
+        lastRenderTime.current = performance.now();
+        setCurrentTimeState(t);
         setExternalSeekVersion((v) => v + 1);
+        return;
       }
 
       // Throttle React state updates — during playback, timeupdate fires ~4×/sec

src/types/language.types.ts

@@ -0,0 +1,266 @@
+/**
+ * v3.1 language schema (lerobot#3467 + lerobot#3471).
+ *
+ * Each row in `language_persistent` and `language_events` has the same shape:
+ *
+ *     { role, content, style, timestamp, tool_calls }
+ *
+ * Persistent styles (task_aug / subtask / plan / memory) live in
+ * `language_persistent` and are broadcast across every frame in the episode. Event styles
+ * (interjection / vqa) plus speech tool-call atoms (style=null) live in
+ * `language_events` and only appear on the exact frames where they were
+ * emitted.
+ *
+ * VQA assistant rows encode their answer as a JSON string in `content`, in one
+ * of five shapes (bbox / keypoint / count / attribute / spatial), matching
+ * `VQA_ANSWER_SHAPES` in lerobot's steerable-pipeline validator.
+ */
+
+export type Role = "user" | "assistant" | "system" | "tool";
+
+export type LanguageStyle =
+  | "task_aug"
+  | "subtask"
+  | "plan"
+  | "memory"
+  | "interjection"
+  | "vqa";
+
+export interface ToolCallFn {
+  name: string;
+  arguments: Record<string, unknown>;
+}
+export interface ToolCall {
+  type: "function";
+  function: ToolCallFn;
+}
+
+export interface LanguageAtom {
+  role: Role;
+  content: string | null;
+  // null is reserved for tool-call-only atoms (speech).
+  style: LanguageStyle | null;
+  timestamp: number;
+  /**
+   * `observation.images.*` feature key when this atom is grounded against a
+   * specific camera view (`vqa`, `trace`). `null` for camera-agnostic atoms
+   * (`task_aug`, `subtask`, `plan`, `memory`, `motion`, `interjection`, speech).
+   * Mirrors lerobot's row-level `camera` field (PR 3467).
+   */
+  camera: string | null;
+  tool_calls: ToolCall[] | null;
+}
+
+export const PERSISTENT_STYLES: ReadonlySet<LanguageStyle> = new Set([
+  "task_aug",
+  "subtask",
+  "plan",
+  "memory",
+]);
+export const EVENT_STYLES: ReadonlySet<LanguageStyle> = new Set([
+  "interjection",
+  "vqa",
+]);
+
+export function columnForStyle(
+  style: LanguageStyle | null,
+): "language_persistent" | "language_events" {
+  if (style === null) return "language_events";
+  if (PERSISTENT_STYLES.has(style)) return "language_persistent";
+  if (EVENT_STYLES.has(style)) return "language_events";
+  throw new Error(`Unknown style: ${String(style)}`);
+}
+
+export function isSpeechAtom(a: LanguageAtom): boolean {
+  return (
+    a.style === null &&
+    a.role === "assistant" &&
+    !!a.tool_calls &&
+    a.tool_calls.length > 0 &&
+    a.tool_calls[0]?.function?.name === "say"
+  );
+}
+
+export function speechText(a: LanguageAtom): string | null {
+  if (!isSpeechAtom(a)) return null;
+  const args = a.tool_calls?.[0]?.function?.arguments as
+    | { text?: unknown }
+    | undefined;
+  return typeof args?.text === "string" ? args.text : null;
+}
+
+export function buildSpeechAtom(timestamp: number, text: string): LanguageAtom {
+  return {
+    role: "assistant",
+    content: null,
+    style: null,
+    timestamp,
+    camera: null,
+    tool_calls: [
+      {
+        type: "function",
+        function: { name: "say", arguments: { text } },
+      },
+    ],
+  };
+}
+
+/**
+ * Whether ``atom`` should render on the camera identified by ``cameraKey``.
+ *
+ * - row-level ``atom.camera`` is the source of truth (lerobot PR 3467);
+ *   ``null`` means camera-agnostic and renders everywhere;
+ *   a non-null value matches only its own camera.
+ * - For backwards compatibility with annotations that were created before the
+ *   row-level field existed (visualizer-only payloads with an in-JSON
+ *   ``camera`` key inside the VQA answer), the caller is responsible for the
+ *   payload-level fallback — see ``video-overlay-canvas.tsx``.
+ */
+export function atomMatchesCamera(
+  atom: LanguageAtom,
+  cameraKey: string,
+): boolean {
+  return atom.camera == null || atom.camera === cameraKey;
+}
+
+// --- VQA answer shapes -------------------------------------------------------
+
+export type VqaAnswer =
+  | VqaBboxAnswer
+  | VqaKeypointAnswer
+  | VqaCountAnswer
+  | VqaAttributeAnswer
+  | VqaSpatialAnswer;
+
+export interface VqaBboxAnswer {
+  detections: Array<{
+    label: string;
+    bbox_format: "xyxy" | "xywh";
+    bbox: [number, number, number, number];
+    /**
+     * Optional camera key for the visualizer (e.g. `observation.images.top`).
+     * Not enforced by lerobot's writer but accepted as a passthrough JSON
+     * field since the validator checks only required keys.
+     */
+    camera?: string;
+  }>;
+}
+
+export interface VqaKeypointAnswer {
+  label: string;
+  point_format: "xy";
+  point: [number, number];
+  camera?: string;
+}
+
+export interface VqaCountAnswer {
+  label: string;
+  count: number;
+  note?: string;
+}
+
+export interface VqaAttributeAnswer {
+  label: string;
+  attribute: string;
+  value: string;
+}
+
+export interface VqaSpatialAnswer {
+  subject: string;
+  relation: string;
+  object: string;
+}
+
+export type VqaKind = "bbox" | "keypoint" | "count" | "attribute" | "spatial";
+
+export function classifyVqa(answer: unknown): VqaKind | null {
+  if (!answer || typeof answer !== "object") return null;
+  const a = answer as Record<string, unknown>;
+  if (Array.isArray(a.detections)) return "bbox";
+  if (a.point_format && Array.isArray(a.point)) return "keypoint";
+  if (typeof a.count === "number" && typeof a.label === "string")
+    return "count";
+  if (typeof a.attribute === "string" && a.value != null) return "attribute";
+  if (typeof a.subject === "string" && typeof a.relation === "string")
+    return "spatial";
+  return null;
+}
+
+export function parseVqaAnswer(
+  raw: string | null | undefined,
+): VqaAnswer | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return classifyVqa(parsed) ? (parsed as VqaAnswer) : null;
+  } catch {
+    return null;
+  }
+}
+
+// --- Atom helpers used by the editor UI --------------------------------------
+
+export interface EpisodeAtoms {
+  persistent: LanguageAtom[];
+  events: LanguageAtom[];
+}
+
+/** Group all atoms for an episode by their target column. */
+export function partitionAtoms(atoms: LanguageAtom[]): EpisodeAtoms {
+  const persistent: LanguageAtom[] = [];
+  const events: LanguageAtom[] = [];
+  for (const a of atoms) {
+    if (columnForStyle(a.style) === "language_persistent") persistent.push(a);
+    else events.push(a);
+  }
+  persistent.sort((a, b) => a.timestamp - b.timestamp);
+  events.sort((a, b) => a.timestamp - b.timestamp);
+  return { persistent, events };
+}
+
+export function atomsByStyle(
+  atoms: LanguageAtom[],
+  style: LanguageStyle,
+): LanguageAtom[] {
+  return atoms.filter((a) => a.style === style);
+}
+
+export function activeAt(
+  persistent: LanguageAtom[],
+  style: LanguageStyle,
+  t: number,
+): LanguageAtom | null {
+  let best: LanguageAtom | null = null;
+  for (const a of persistent) {
+    if (a.style !== style) continue;
+    if (a.timestamp > t) break;
+    best = a;
+  }
+  return best;
+}
+
+export function eventsAt(
+  events: LanguageAtom[],
+  t: number,
+  windowSec = 1 / 60,
+): LanguageAtom[] {
+  return events.filter((a) => Math.abs(a.timestamp - t) <= windowSec);
+}
+
+/**
+ * Snap a timestamp to the nearest source-frame timestamp. Linear scan; episodes
+ * are typically a few thousand frames so this is fine without a tree.
+ */
+export function snapToFrame(frameTimestamps: number[], ts: number): number {
+  if (!frameTimestamps.length) return ts;
+  let best = frameTimestamps[0];
+  let dist = Math.abs(ts - best);
+  for (let i = 1; i < frameTimestamps.length; i++) {
+    const d = Math.abs(ts - frameTimestamps[i]);
+    if (d < dist) {
+      dist = d;
+      best = frameTimestamps[i];
+    }
+  }
+  return best;
+}

src/utils/annotationsClient.ts

@@ -0,0 +1,186 @@
+/**
+ * Client for the FastAPI annotation backend in `backend/`.
+ *
+ * The backend URL is configured via the `NEXT_PUBLIC_ANNOTATE_BACKEND_URL`
+ * env var so it can be statically substituted by Next.js. When unset, all
+ * annotation write paths are disabled and the UI falls back to sessionStorage
+ * for read/edit only.
+ */
+
+import type { LanguageAtom } from "../types/language.types";
+
+const ENV_URL = (() => {
+  const v =
+    typeof process !== "undefined"
+      ? process.env.NEXT_PUBLIC_ANNOTATE_BACKEND_URL
+      : undefined;
+  return (v || "").trim() || null;
+})();
+
+export function isAnnotateBackendEnabled(): boolean {
+  return !!ENV_URL;
+}
+
+export function getAnnotateBackendUrl(): string | null {
+  return ENV_URL;
+}
+
+interface DatasetIdent {
+  repoId?: string | null;
+  localPath?: string | null;
+  revision?: string | null;
+}
+
+function buildUrl(path: string, ident: DatasetIdent): string {
+  if (!ENV_URL) throw new Error("Annotate backend not configured");
+  const url = new URL(path, ENV_URL);
+  if (ident.repoId) url.searchParams.set("repo_id", ident.repoId);
+  if (ident.revision) url.searchParams.set("revision", ident.revision);
+  if (ident.localPath) url.searchParams.set("local_path", ident.localPath);
+  return url.toString();
+}
+
+export async function pingBackend(): Promise<boolean> {
+  if (!ENV_URL) return false;
+  try {
+    const res = await fetch(new URL("/api/health", ENV_URL).toString());
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function loadDataset(
+  ident: DatasetIdent,
+): Promise<{ ok: boolean }> {
+  if (!ENV_URL) return { ok: false };
+  const res = await fetch(new URL("/api/dataset/load", ENV_URL).toString(), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      repo_id: ident.repoId || null,
+      revision: ident.revision || null,
+      local_path: ident.localPath || null,
+    }),
+  });
+  return { ok: res.ok };
+}
+
+export async function fetchEpisodeAtoms(
+  episodeId: number,
+  ident: DatasetIdent,
+): Promise<LanguageAtom[]> {
+  if (!ENV_URL) return [];
+  await loadDataset(ident);
+  const res = await fetch(buildUrl(`/api/episodes/${episodeId}/atoms`, ident));
+  if (!res.ok) {
+    throw new Error(`fetch atoms: ${res.status}`);
+  }
+  const data = (await res.json()) as { atoms?: LanguageAtom[] };
+  return data.atoms || [];
+}
+
+export async function saveEpisodeAtoms(
+  episodeId: number,
+  ident: DatasetIdent,
+  atoms: LanguageAtom[],
+): Promise<{ path: string | null }> {
+  if (!ENV_URL) return { path: null };
+  const res = await fetch(
+    new URL(`/api/episodes/${episodeId}/atoms`, ENV_URL).toString(),
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        episode_index: episodeId,
+        repo_id: ident.repoId || null,
+        local_path: ident.localPath || null,
+        atoms,
+      }),
+    },
+  );
+  if (!res.ok) {
+    const text = await res.text().catch(() => `${res.status}`);
+    throw new Error(text || `save atoms: ${res.status}`);
+  }
+  const data = (await res.json().catch(() => ({}))) as { path?: string | null };
+  return { path: data.path ?? null };
+}
+
+export async function fetchFrameTimestamps(
+  episodeId: number,
+  ident: DatasetIdent,
+): Promise<number[]> {
+  if (!ENV_URL) return [];
+  const res = await fetch(
+    buildUrl(`/api/episodes/${episodeId}/frame_timestamps`, ident),
+  );
+  if (!res.ok) return [];
+  const data = (await res.json()) as { timestamps?: number[] };
+  return data.timestamps || [];
+}
+
+export async function exportDataset(
+  ident: DatasetIdent,
+  outputDir?: string | null,
+  copyVideos = false,
+): Promise<{
+  output_dir: string;
+  persistent_rows: number;
+  event_rows: number;
+}> {
+  if (!ENV_URL) throw new Error("Annotate backend not configured");
+  const res = await fetch(new URL("/api/export", ENV_URL).toString(), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      repo_id: ident.repoId || null,
+      revision: ident.revision || null,
+      local_path: ident.localPath || null,
+      output_dir: outputDir || null,
+      copy_videos: !!copyVideos,
+    }),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => `${res.status}`);
+    throw new Error(text || `export: ${res.status}`);
+  }
+  return res.json();
+}
+
+export interface PushToHubResult {
+  ok: boolean;
+  repo_id: string;
+  url: string;
+  message: string;
+}
+
+export async function pushToHub(
+  ident: DatasetIdent,
+  hfToken: string,
+  pushInPlace: boolean,
+  newRepoId: string | null,
+  privateRepo: boolean,
+  commitMessage: string,
+): Promise<PushToHubResult> {
+  if (!ENV_URL) throw new Error("Annotate backend not configured");
+  const res = await fetch(new URL("/api/push_to_hub", ENV_URL).toString(), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      repo_id: ident.repoId || null,
+      revision: ident.revision || null,
+      local_path: ident.localPath || null,
+      hf_token: hfToken,
+      push_in_place: pushInPlace,
+      new_repo_id: newRepoId || null,
+      private: privateRepo,
+      commit_message: commitMessage,
+    }),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => `${res.status}`);
+    throw new Error(text || `push: ${res.status}`);
+  }
+  return res.json();
+}