Sync from huggingface/lerobot-dataset-visualizer via hub-sync

AGENTS.md

@@ -0,0 +1,147 @@
+# AGENTS.md — LeRobot Dataset Visualizer
+
+## Package manager
+
+Always use **bun** (`bun install`, `bun dev`, `bun run build`, `bun test`). Never use npm or yarn.
+
+## Post-process — run after every code change
+
+After making any code changes, always run these commands in order and fix any errors before finishing:
+
+```
+bun run format        # auto-fix formatting (prettier)
+bun run type-check    # TypeScript: app + test files
+bun run lint          # ESLint (next lint)
+bun test              # unit tests
+```
+
+Or run them all at once (format first, then the full validate suite):
+
+```
+bun run format && bun run validate
+```
+
+`bun run validate` runs: type-check → lint → format:check → test
+
+## Key scripts
+
+```
+bun dev              # Next.js dev server
+bun test             # Run all unit tests (bun:test)
+bun run type-check   # tsc --noEmit (app) + tsc -p tsconfig.test.json --noEmit (tests)
+bun run lint         # next lint
+bun run validate     # type-check + lint + format:check + test
+```
+
+## Architecture
+
+### Dataset version support
+
+Three versions are supported. Version is detected from `meta/info.json` → `codebase_version`.
+
+| Version  | Path pattern                                                   | Episode metadata                           | Video                                          |
+| -------- | -------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------- |
+| **v2.0** | `data/{episode_chunk:03d}/episode_{episode_index:06d}.parquet` | None (computed from `chunks_size`)         | Full file per episode                          |
+| **v2.1** | Same as v2.0                                                   | None                                       | Full file per episode                          |
+| **v3.0** | `data/chunk-{N:03d}/file-{N:03d}.parquet`                      | `meta/episodes/chunk-{N}/file-{N}.parquet` | Segmented (timestamps per episode, per camera) |
+
+### Routing to parsers
+
+`src/app/[org]/[dataset]/[episode]/fetch-data.ts` → `getEpisodeData()` dispatches to:
+
+- `getEpisodeDataV2()` for v2.0 and v2.1
+- `getEpisodeDataV3()` for v3.0
+
+### `@huggingface/lerobot`
+
+Locating an episode (its video URLs and offsets, its data file and row range) and reading camera sizes go through [`@huggingface/lerobot`](https://github.com/huggingface/huggingface.js/tree/main/packages/lerobot). Don't build v3 data, video or episode-metadata paths by hand.
+
+- Create datasets with `leRobotDataset(repoId)` in `fetch-data.ts`: it passes the `DATASET_URL` endpoint and `authHeaders()`.
+- `episodes({ offset, limit })` reads the v3 episode index across every metadata chunk. `offset` is a position in the listing, not an `episode_index`.
+- `episode.data.fromRow` / `toRow` are row offsets **inside `episode.data.url`**, not dataset-wide frame indexes. Pass them straight to `rowStart` / `rowEnd`; never subtract the file's first `index`. `episode.data` is optional: it is absent when the data file can't be read.
+- Episode charts come from `frames()` (numeric and boolean series, bookkeeping columns left out). `loadEpisodeFrames` reads the task and language columns (`TEXT_COLUMNS`) from the same file alongside it, since `frames()` returns numbers only.
+- Camera sizes come from `parseInfo(...).cameras`. Never read them from `shape[0]` / `shape[1]`: some datasets declare channel-first shapes (`[3, H, W]`).
+- To upgrade, bump the version in `package.json` and run `bun install`. Read the package's changes first: 0.0.4 changed what `fromRow` / `toRow` mean.
+
+### v3.0 specifics
+
+- Integer columns from parquet come out as **BigInt** — always use `bigIntToNumber()` from `src/utils/typeGuards.ts`
+- Fallback format uses numeric keys `"0"`.."9"` when column names are unavailable
+- Multi-task episodes: episodes carry a `tasks` list (`list[str]`) — prefer it over the legacy single `task_index` lookup. `EpisodeMetadataV3.tasks?: string[]` exposes it.
+- `meta/tasks.parquet` lookup: rows are **not** ordered by `task_index`, and the task string lives in a named pandas index (`__index_level_0__`). Always filter by the `task_index` **column** (`row.task_index === taskIndexNum`), never by row position.
+
+### v2.x path construction
+
+```ts
+formatStringWithVars(info.data_path, {
+  episode_chunk: Math.floor(episodeId / chunkSize)
+    .toString()
+    .padStart(3, "0"),
+  episode_index: episodeId.toString().padStart(6, "0"),
+});
+// → "data/000/episode_000042.parquet"
+```
+
+`formatStringWithVars` strips `:03d` format specifiers — padding must be done by the caller.
+
+## Key files
+
+| File                                              | Purpose                                                                                                                                  |
+| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/app/[org]/[dataset]/[episode]/fetch-data.ts` | Main data-loading entry point; v2/v3 parsers; `computeColumnMinMax`                                                                      |
+| `src/utils/versionUtils.ts`                       | `getDatasetInfo`, `getDatasetVersionAndInfo`, `buildVersionedUrl`                                                                        |
+| `src/utils/parquetUtils.ts`                       | `fetchParquetFile`, `readParquetAsObjects`, `formatStringWithVars`                                                                       |
+| `src/utils/dataProcessing.ts`                     | Chart grouping pipeline: `buildSuffixGroupsMap` → `computeGroupStats` → `groupByScale` → `flattenScaleGroups` → `processChartDataGroups` |
+| `src/utils/typeGuards.ts`                         | `bigIntToNumber`, `isNumeric`, `isValidTaskIndex`, etc.                                                                                  |
+| `src/utils/constants.ts`                          | `PADDING`, `EXCLUDED_COLUMNS`, `CHART_CONFIG`, `THRESHOLDS`                                                                              |
+| `src/types/`                                      | TypeScript types: `DatasetVersion`, `EpisodeMetadataV3`, `VideoInfo`, `ChartDataGroup`, etc.                                             |
+
+## Chart data pipeline
+
+Series keys use `" | "` as delimiter (e.g. `observation.state | 0`).
+`groupRowBySuffix` groups by **suffix**: if two different prefixes share suffix `"0"` (e.g. `observation.state | 0` and `action | 0`), they are merged under `result["0"] = { "observation.state": ..., "action": ... }`. A series with a unique suffix stays flat with its full original key.
+
+## Testing
+
+- Test files live in `**/__tests__/` directories alongside source
+- Uses `bun:test` (built-in, no extra install)
+- BigInt literals (`42n`) require `tsconfig.test.json` (target ES2020) — test files are excluded from `tsconfig.json`
+- `@types/bun` is installed as a devDependency for `bun:test` type resolution
+- Mocking fetch: `globalThis.fetch = mock(() => Promise.resolve(new Response(...))) as unknown as typeof fetch`
+- CI: `.github/workflows/test.yml` runs `bun test` on push/PR to main
+
+## URL structure
+
+All dataset URLs:
+
+```
+https://huggingface.co/datasets/{org}/{dataset}/resolve/main/{path}
+```
+
+Built by `buildVersionedUrl(repoId, version, path)`. The `version` param is accepted but currently unused in the URL (always `main` revision).
+
+## Excluded columns (not shown in charts)
+
+Reserved/bookkeeping columns from lerobot — see `EXCLUDED_COLUMNS` in `src/utils/constants.ts`:
+
+- v2.x: `timestamp`, `frame_index`, `episode_index`, `index`, `task_index`, `next.reward`, `next.done`, `next.truncated`
+- v3.0: `index`, `task_index`, `episode_index`, `frame_index`, `next.reward`, `next.done`, `next.truncated`, `subtask_index`
+
+## 3D URDF viewer (`src/components/urdf-viewer.tsx`)
+
+- URDFs and meshes are hosted in the HF bucket `lerobot/robot-urdfs` — base URL `https://huggingface.co/buckets/lerobot/robot-urdfs/resolve` (no `/main` segment; buckets are unbranched). Override with `NEXT_PUBLIC_URDF_BASE_URL` for local development.
+- Asset layout under the bucket: `g1/`, `openarm/`, `so101/` (both SO-100 and SO-101 live here).
+- **URDFLoader gotcha**: after our `loadMeshCb` returns, `URDFLoader.js` does `if (obj instanceof THREE.Mesh) obj.material = <urdf-material>`, overwriting any material we set. Workaround: wrap the loaded mesh in a `THREE.Group` so the `instanceof Mesh` check fails. DAE returns a Group already; STL must be wrapped explicitly.
+- **STLLoader event ordering**: `manager.itemEnd(url)` fires _before_ the user `onLoad` callback, so `manager.onLoad` can fire before meshes are attached to the robot tree. Defer post-load work (auto-fit camera, shadow flags) with `setTimeout(..., 0)`. Don't try to rebuild materials in `manager.onLoad` — pick the archetype color directly inside `loadMeshCb`.
+- **OpenArm DAE files ship 23 stray `PointLight`s** that drown out scene lighting. Strip non-`AmbientLight` lights from `collada.scene` before adding it to the robot.
+- Scene setup: `<Canvas shadows>` with `ACESFilmicToneMapping` (exposure 0.9), 3-point directional + ambient lights, `<Environment preset="studio" background={false} />`, `<color attach="background" args={["#1a2433"]} />`. `<OrbitControls makeDefault />` is required so `useThree().controls` exposes the controls for auto-fit.
+
+## Design system
+
+CSS tokens in `src/app/globals.css` (Tailwind v4 `@theme inline`):
+
+- Surfaces: `--bg #0a0e17`, `--surface-0`, `--surface-1`, `--surface-2`
+- Text: `--text-primary`, `--text-muted`, `--text-faint`
+- Accent: `--accent #38bdf8` (cyan) — primary interactive color across UI
+- Helpers: `.panel`, `.panel-raised`, `.tabular` (tabular-nums)
+- **Color semantics**: cyan = primary/active, orange (`orange-400/500`) is reserved for **flagged-episode** UI only — don't reuse it for generic accents.

CLAUDE.md

@@ -1,140 +1 @@
-# CLAUDE.md — LeRobot Dataset Visualizer
-
-## Package manager
-
-Always use **bun** (`bun install`, `bun dev`, `bun run build`, `bun test`). Never use npm or yarn.
-
-## Post-process — run after every code change
-
-After making any code changes, always run these commands in order and fix any errors before finishing:
-
-```
-bun run format        # auto-fix formatting (prettier)
-bun run type-check    # TypeScript: app + test files
-bun run lint          # ESLint (next lint)
-bun test              # unit tests
-```
-
-Or run them all at once (format first, then the full validate suite):
-
-```
-bun run format && bun run validate
-```
-
-`bun run validate` runs: type-check → lint → format:check → test
-
-## Key scripts
-
-```
-bun dev              # Next.js dev server
-bun test             # Run all unit tests (bun:test)
-bun run type-check   # tsc --noEmit (app) + tsc -p tsconfig.test.json --noEmit (tests)
-bun run lint         # next lint
-bun run validate     # type-check + lint + format:check
-```
-
-## Architecture
-
-### Dataset version support
-
-Three versions are supported. Version is detected from `meta/info.json` → `codebase_version`.
-
-| Version  | Path pattern                                                      | Episode metadata                           | Video                                          |
-| -------- | ----------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------- |
-| **v2.0** | `data/{episode_chunk:03d}/episode_{episode_index:06d}.parquet`    | None (computed from `chunks_size`)         | Full file per episode                          |
-| **v2.1** | Same as v2.0                                                      | None                                       | Full file per episode                          |
-| **v3.0** | `data/chunk-{N:03d}/file-{N:03d}.parquet` (via `buildV3DataPath`) | `meta/episodes/chunk-{N}/file-{N}.parquet` | Segmented (timestamps per episode, per camera) |
-
-### Routing to parsers
-
-`src/app/[org]/[dataset]/[episode]/fetch-data.ts` → `getEpisodeData()` dispatches to:
-
-- `getEpisodeDataV2()` for v2.0 and v2.1
-- `getEpisodeDataV3()` for v3.0
-
-### v3.0 specifics
-
-- Episode metadata row has named keys (`episode_index`, `data/chunk_index`, `data/file_index`, `dataset_from_index`, `dataset_to_index`, `videos/{key}/chunk_index`, etc.)
-- Integer columns from parquet come out as **BigInt** — always use `bigIntToNumber()` from `src/utils/typeGuards.ts`
-- Row-range selection: `dataset_from_index` / `dataset_to_index` allow reading only the episode's rows from a shared parquet file
-- Fallback format uses numeric keys `"0"`.."9"` when column names are unavailable
-- Episode metadata can span **multiple chunks** (when episode count exceeds `chunks_size`). Always walk via the `iterateEpisodeMetadataFilesV3(repoId, version)` async generator in `fetch-data.ts` — it advances chunk-000 → chunk-001 → … and stops on the first missing `file-000`. Never hardcode `chunk-000`.
-- Multi-task episodes: episode-metadata rows carry a `tasks` field (`list[str]`) — prefer it over the legacy single `task_index` lookup. `EpisodeMetadataV3.tasks?: string[]` exposes it.
-- `meta/tasks.parquet` lookup: rows are **not** ordered by `task_index`, and the task string lives in a named pandas index (`__index_level_0__`). Always filter by the `task_index` **column** (`row.task_index === taskIndexNum`), never by row position.
-
-### v2.x path construction
-
-```ts
-formatStringWithVars(info.data_path, {
-  episode_chunk: Math.floor(episodeId / chunkSize)
-    .toString()
-    .padStart(3, "0"),
-  episode_index: episodeId.toString().padStart(6, "0"),
-});
-// → "data/000/episode_000042.parquet"
-```
-
-`formatStringWithVars` strips `:03d` format specifiers — padding must be done by the caller.
-
-## Key files
-
-| File                                              | Purpose                                                                                                                                  |
-| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/app/[org]/[dataset]/[episode]/fetch-data.ts` | Main data-loading entry point; v2/v3 parsers; `computeColumnMinMax`                                                                      |
-| `src/utils/versionUtils.ts`                       | `getDatasetInfo`, `getDatasetVersionAndInfo`, `buildVersionedUrl`                                                                        |
-| `src/utils/stringFormatting.ts`                   | `buildV3DataPath`, `buildV3VideoPath`, `buildV3EpisodesMetadataPath`, padding helpers                                                    |
-| `src/utils/parquetUtils.ts`                       | `fetchParquetFile`, `readParquetAsObjects`, `formatStringWithVars`                                                                       |
-| `src/utils/dataProcessing.ts`                     | Chart grouping pipeline: `buildSuffixGroupsMap` → `computeGroupStats` → `groupByScale` → `flattenScaleGroups` → `processChartDataGroups` |
-| `src/utils/typeGuards.ts`                         | `bigIntToNumber`, `isNumeric`, `isValidTaskIndex`, etc.                                                                                  |
-| `src/utils/constants.ts`                          | `PADDING`, `EXCLUDED_COLUMNS`, `CHART_CONFIG`, `THRESHOLDS`                                                                              |
-| `src/types/`                                      | TypeScript types: `DatasetVersion`, `EpisodeMetadataV3`, `VideoInfo`, `ChartDataGroup`, etc.                                             |
-
-## Chart data pipeline
-
-Series keys use `" | "` as delimiter (e.g. `observation.state | 0`).
-`groupRowBySuffix` groups by **suffix**: if two different prefixes share suffix `"0"` (e.g. `observation.state | 0` and `action | 0`), they are merged under `result["0"] = { "observation.state": ..., "action": ... }`. A series with a unique suffix stays flat with its full original key.
-
-## Testing
-
-- Test files live in `**/__tests__/` directories alongside source
-- Uses `bun:test` (built-in, no extra install)
-- BigInt literals (`42n`) require `tsconfig.test.json` (target ES2020) — test files are excluded from `tsconfig.json`
-- `@types/bun` is installed as a devDependency for `bun:test` type resolution
-- Mocking fetch: `globalThis.fetch = mock(() => Promise.resolve(new Response(...))) as unknown as typeof fetch`
-- CI: `.github/workflows/test.yml` runs `bun test` on push/PR to main
-
-## URL structure
-
-All dataset URLs:
-
-```
-https://huggingface.co/datasets/{org}/{dataset}/resolve/main/{path}
-```
-
-Built by `buildVersionedUrl(repoId, version, path)`. The `version` param is accepted but currently unused in the URL (always `main` revision).
-
-## Excluded columns (not shown in charts)
-
-Reserved/bookkeeping columns from lerobot — see `EXCLUDED_COLUMNS` in `src/utils/constants.ts`:
-
-- v2.x: `timestamp`, `frame_index`, `episode_index`, `index`, `task_index`, `next.reward`, `next.done`, `next.truncated`
-- v3.0: `index`, `task_index`, `episode_index`, `frame_index`, `next.reward`, `next.done`, `next.truncated`, `subtask_index`
-
-## 3D URDF viewer (`src/components/urdf-viewer.tsx`)
-
-- URDFs and meshes are hosted in the HF bucket `lerobot/robot-urdfs` — base URL `https://huggingface.co/buckets/lerobot/robot-urdfs/resolve` (no `/main` segment; buckets are unbranched). Override with `NEXT_PUBLIC_URDF_BASE_URL` for local development.
-- Asset layout under the bucket: `g1/`, `openarm/`, `so101/` (both SO-100 and SO-101 live here).
-- **URDFLoader gotcha**: after our `loadMeshCb` returns, `URDFLoader.js` does `if (obj instanceof THREE.Mesh) obj.material = <urdf-material>`, overwriting any material we set. Workaround: wrap the loaded mesh in a `THREE.Group` so the `instanceof Mesh` check fails. DAE returns a Group already; STL must be wrapped explicitly.
-- **STLLoader event ordering**: `manager.itemEnd(url)` fires _before_ the user `onLoad` callback, so `manager.onLoad` can fire before meshes are attached to the robot tree. Defer post-load work (auto-fit camera, shadow flags) with `setTimeout(..., 0)`. Don't try to rebuild materials in `manager.onLoad` — pick the archetype color directly inside `loadMeshCb`.
-- **OpenArm DAE files ship 23 stray `PointLight`s** that drown out scene lighting. Strip non-`AmbientLight` lights from `collada.scene` before adding it to the robot.
-- Scene setup: `<Canvas shadows>` with `ACESFilmicToneMapping` (exposure 0.9), 3-point directional + ambient lights, `<Environment preset="studio" background={false} />`, `<color attach="background" args={["#1a2433"]} />`. `<OrbitControls makeDefault />` is required so `useThree().controls` exposes the controls for auto-fit.
-
-## Design system
-
-CSS tokens in `src/app/globals.css` (Tailwind v4 `@theme inline`):
-
-- Surfaces: `--bg #0a0e17`, `--surface-0`, `--surface-1`, `--surface-2`
-- Text: `--text-primary`, `--text-muted`, `--text-faint`
-- Accent: `--accent #38bdf8` (cyan) — primary interactive color across UI
-- Helpers: `.panel`, `.panel-raised`, `.tabular` (tabular-nums)
-- **Color semantics**: cyan = primary/active, orange (`orange-400/500`) is reserved for **flagged-episode** UI only — don't reuse it for generic accents.
+@AGENTS.md

bun.lock

@@ -6,7 +6,7 @@
       "name": "lerobot-viewer",
       "dependencies": {
         "@huggingface/hub": "^2.11.0",
-        "@huggingface/lerobot": "^0.0.7",
+        "@huggingface/lerobot": "^0.0.8",
         "@react-three/drei": "^10.7.7",
         "@react-three/fiber": "^9.5.0",
         "hyparquet": "^1.12.1",
@@ -67,7 +67,7 @@
 
     "@huggingface/hub": ["@huggingface/hub@2.11.0", "", { "dependencies": { "@huggingface/tasks": "^0.19.90" }, "optionalDependencies": { "cli-progress": "^3.12.0" }, "bin": { "hfjs": "dist/cli.js" } }, "sha512-WS6QGaXYeBVFlaB4SOn6z4LGUpLB5kRZNL08uUni4izX353KxiwwZMK5+/AWX86MJh8SMZNa/JFcvFCcQsbszQ=="],
 
-    "@huggingface/lerobot": ["@huggingface/lerobot@0.0.7", "", { "dependencies": { "hyparquet": "^1.25.1" } }, "sha512-BJ2CsTW5Z0dRxRqEED70IWK1w9vWTdZu48W36ttFIr+qT5mKRtj+MfrOozf4qbBl/okauyXpHBfVqVqPCTudgA=="],
+    "@huggingface/lerobot": ["@huggingface/lerobot@0.0.8", "", { "dependencies": { "hyparquet": "^1.25.1" } }, "sha512-TeA8U5/idkQH0dmhb79+wkZHvrxkjB5Y+TllirJRg3vExl5SC2/E8LXZbRWSmfZibr7YD4w1kSGxeRL0f8/2/Q=="],
 
     "@huggingface/tasks": ["@huggingface/tasks@0.19.90", "", {}, "sha512-nfV9luJbvwGQ/5oKXkKhCV9h4X7mwh1YaGG3ORd6UMLDSwr1OFSSatcBX0O9OtBtmNK19aGSjbLFqqgcIR6+IA=="],
 

package.json

@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "@huggingface/hub": "^2.11.0",
-    "@huggingface/lerobot": "^0.0.7",
+    "@huggingface/lerobot": "^0.0.8",
     "@react-three/drei": "^10.7.7",
     "@react-three/fiber": "^9.5.0",
     "hyparquet": "^1.12.1",

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

@@ -10,7 +10,7 @@ import {
   buildVersionedUrl,
   getDatasetStats,
 } from "@/utils/versionUtils";
-import { PADDING, CHART_CONFIG, EXCLUDED_COLUMNS } from "@/utils/constants";
+import { CHART_CONFIG, EXCLUDED_COLUMNS } from "@/utils/constants";
 import {
   processChartDataGroups,
   groupRowBySuffix,
@@ -23,7 +23,7 @@ import {
 } from "@/utils/colormaps";
 import type { VideoInfo, AdjacentEpisodeVideos } from "@/types";
 import { LeRobotDataset, parseInfo } from "@huggingface/lerobot";
-import type { LeRobotEpisode, LeRobotEpisodeData } from "@huggingface/lerobot";
+import type { LeRobotEpisode, LeRobotFrames } from "@huggingface/lerobot";
 import { authHeaders } from "@/utils/auth";
 
 const SERIES_NAME_DELIMITER = CHART_CONFIG.SERIES_NAME_DELIMITER;
@@ -197,11 +197,6 @@ type EpisodeMetadataV3 = {
   [key: string]: string | number | string[] | undefined;
 };
 
-type ColumnDef = {
-  key: string;
-  value: string[];
-};
-
 function parsePositiveIntEnv(
   value: string | undefined,
   fallback: number,
@@ -526,9 +521,6 @@ async function getEpisodeDataV2(
   info: DatasetMetadata,
   episodeId: number,
 ): Promise<EpisodeData> {
-  const chunkSize = Math.max(1, info.chunks_size || 1000);
-  const episode_chunk = Math.floor(episodeId / chunkSize);
-
   const datasetInfo: DatasetDisplayInfo = {
     repoId,
     total_frames: info.total_frames,
@@ -553,96 +545,19 @@ async function getEpisodeDataV2(
           .map((x) => parseInt(x.trim(), 10))
           .filter((x) => !isNaN(x));
 
-  // Videos information
+  const leRobotEpisode = await loadLeRobotEpisode(repoId, episodeId);
   const videosInfo =
-    info.video_path !== null
-      ? toVideosInfo(await loadLeRobotEpisode(repoId, episodeId), info, false)
-      : [];
-
-  // Column data
-  const columnNames = Object.entries(info.features)
-    .filter(
-      ([, value]) =>
-        ["float32", "int32"].includes(value.dtype) && value.shape.length === 1,
-    )
-    .map(([key, { shape }]) => ({ key, length: shape[0] }));
-
-  // Exclude specific columns
-  const excludedColumns = EXCLUDED_COLUMNS.V2 as readonly string[];
-  const filteredColumns = columnNames.filter(
-    (column) => !excludedColumns.includes(column.key),
-  );
-  const columns: ColumnDef[] = filteredColumns.map(({ key }) => {
-    let column_names: unknown = info.features[key].names;
-    while (typeof column_names === "object" && column_names !== null) {
-      if (Array.isArray(column_names)) break;
-      column_names = Object.values(column_names)[0];
-    }
-    return {
-      key,
-      value: Array.isArray(column_names)
-        ? column_names.map(
-            (name: string) => `${key}${SERIES_NAME_DELIMITER}${name}`,
-          )
-        : Array.from(
-            { length: columnNames.find((c) => c.key === key)?.length ?? 1 },
-            (_, i) => `${key}${CHART_CONFIG.SERIES_NAME_DELIMITER}${i}`,
-          ),
-    };
-  });
+    info.video_path !== null ? toVideosInfo(leRobotEpisode, info, false) : [];
 
-  const parquetUrl = buildVersionedUrl(
-    repoId,
-    version,
-    formatStringWithVars(info.data_path, {
-      episode_chunk: episode_chunk
-        .toString()
-        .padStart(PADDING.CHUNK_INDEX, "0"),
-      episode_index: episodeId.toString().padStart(PADDING.EPISODE_INDEX, "0"),
-    }),
-  );
-
-  const arrayBuffer = await fetchParquetFile(parquetUrl);
-  const parquetColumns = Array.from(
-    new Set([
-      "timestamp",
-      "task",
-      "task_index",
-      "language_instruction",
-      // v3.1 language schema (lerobot#3467) — list<struct{...}> columns the
-      // annotations panel renders / edits. lerobot can write these onto v2.x
-      // datasets too (the codebase_version stays 2.x), so a v2 episode may
-      // carry annotations. Requesting columns absent from the parquet schema
-      // is a no-op in hyparquet, so this is safe for un-annotated datasets.
-      "language_persistent",
-      "language_events",
-      ...filteredColumns.map((c) => c.key),
-    ]),
-  );
-  const allData = await readParquetAsObjects(arrayBuffer, parquetColumns);
-
-  // Frame timestamps (sorted, seconds) let the annotations editor snap atoms
-  // to exact frames. v3.1 language atoms are broadcast in `language_persistent`
-  // and fired per-row in `language_events`; extract them so annotations written
-  // onto v2.x datasets render in the panel/timeline just like on v3.0.
-  const frameTimestamps = allData
-    .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 languageAtoms = extractLanguageAtoms(allData);
+  const { frames, textRows } = await loadEpisodeFrames(repoId, leRobotEpisode);
+  const frameTimestamps = sortedTimestamps(frames);
+  const languageAtoms = extractLanguageAtoms(textRows);
 
   // Extract task from language_instruction fields, task field, or tasks.jsonl
   let task: string | undefined;
 
-  if (allData.length > 0) {
-    const firstRow = allData[0];
+  if (textRows.length > 0) {
+    const firstRow = textRows[0];
     const languageInstructions: string[] = [];
 
     if (typeof firstRow.language_instruction === "string") {
@@ -664,11 +579,11 @@ async function getEpisodeDataV2(
     }
   }
 
-  if (!task && allData.length > 0 && typeof allData[0].task === "string") {
-    task = allData[0].task;
+  if (!task && textRows.length > 0 && typeof textRows[0].task === "string") {
+    task = textRows[0].task;
   }
 
-  if (!task && allData.length > 0) {
+  if (!task && textRows.length > 0) {
     try {
       const tasksUrl = buildVersionedUrl(repoId, version, "meta/tasks.jsonl");
       const tasksResponse = await fetch(tasksUrl, { cache: "no-store" });
@@ -681,7 +596,7 @@ async function getEpisodeDataV2(
           .map((line) => JSON.parse(line));
 
         if (tasksData && tasksData.length > 0) {
-          const taskIndex = allData[0].task_index;
+          const taskIndex = textRows[0].task_index;
           const taskIndexNum =
             typeof taskIndex === "bigint" ? Number(taskIndex) : taskIndex;
           const taskData = tasksData.find(
@@ -697,28 +612,14 @@ async function getEpisodeDataV2(
     }
   }
 
-  // Build chart data from already-parsed allData (no second parquet parse)
-  const seriesNames = [
-    "timestamp",
-    ...columns.map(({ value }) => value).flat(),
-  ];
-
-  const chartData = allData.map((row) => {
-    const obj: Record<string, number> = {};
-    obj["timestamp"] = Number(row.timestamp);
-    for (const col of columns) {
-      const rawVal = row[col.key];
-      if (Array.isArray(rawVal)) {
-        rawVal.forEach((v: unknown, i: number) => {
-          if (i < col.value.length) obj[col.value[i]] = Number(v);
-        });
-      } else if (rawVal !== undefined) {
-        obj[col.value[0]] = Number(rawVal);
-      }
-    }
-    return obj;
-  });
-  const sampledChartData = evenlySampleArray(chartData, MAX_EPISODE_POINTS);
+  const { chartDataGroups, flatChartData } = frames
+    ? chartDataFromFrames(
+        frames,
+        info,
+        EXCLUDED_COLUMNS.V2,
+        (frameIndex) => frames.timestamps[frameIndex],
+      )
+    : { chartDataGroups: [], flatChartData: [] };
 
   // List of columns that are ignored (e.g., 2D or 3D data)
   const ignoredColumns = Object.entries(info.features)
@@ -728,32 +629,17 @@ async function getEpisodeDataV2(
     )
     .map(([key]) => key);
 
-  // Process chart data into organized groups using utility function
-  const chartGroups = processChartDataGroups(seriesNames, sampledChartData);
-
   const duration =
-    sampledChartData.length > 0
-      ? sampledChartData[sampledChartData.length - 1].timestamp
+    flatChartData.length > 0
+      ? flatChartData[flatChartData.length - 1].timestamp
       : 0;
 
-  const chartDataGroups = chartGroups.map((group) =>
-    sampledChartData.map((row) => {
-      const grouped = groupRowBySuffix(pick(row, [...group, "timestamp"]));
-      // Ensure timestamp is always a number at the top level
-      return {
-        ...grouped,
-        timestamp:
-          typeof grouped.timestamp === "number" ? grouped.timestamp : 0,
-      };
-    }),
-  );
-
   return {
     datasetInfo,
     episodeId,
     videosInfo,
     chartDataGroups,
-    flatChartData: sampledChartData,
+    flatChartData,
     episodes,
     ignoredColumns,
     duration,
@@ -801,7 +687,7 @@ async function getEpisodeDataV3(
     version,
     info,
     episodeMetadata,
-    leRobotEpisode.data,
+    leRobotEpisode,
   );
 
   const duration = episodeMetadata.length
@@ -829,7 +715,7 @@ async function loadEpisodeDataV3(
   version: string,
   info: DatasetMetadata,
   episodeMetadata: EpisodeMetadataV3,
-  data: LeRobotEpisodeData | undefined,
+  episode: LeRobotEpisode,
 ): Promise<{
   chartDataGroups: ChartRow[][];
   flatChartData: Record<string, number>[];
@@ -839,78 +725,44 @@ async function loadEpisodeDataV3(
   frameTimestamps?: number[];
 }> {
   try {
-    if (!data) throw new Error("Episode has no data rows");
-    const parquetFile = await fetchParquetFile(data.url);
-    const v3DataColumns = Array.from(
-      new Set([
-        "index",
-        "timestamp",
-        "task_index",
-        "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();
-            const isNumericOrBool = [
-              "float32",
-              "float64",
-              "int8",
-              "int16",
-              "int32",
-              "int64",
-              "uint8",
-              "uint16",
-              "uint32",
-              "uint64",
-              "bool",
-              "boolean",
-            ].includes(dtype);
-            return isNumericOrBool && feature.shape.length <= 1;
-          })
-          .map(([key]) => key),
-      ]),
-    );
-    // `fromRow`/`toRow` are offsets inside `data.url`, not dataset-wide frame indexes.
-    const episodeRows = await readParquetAsObjects(parquetFile, v3DataColumns, {
-      rowStart: data.fromRow,
-      rowEnd: data.toRow,
-    });
-
-    // 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 { frames, textRows } = await loadEpisodeFrames(repoId, episode);
+    const frameTimestamps = sortedTimestamps(frames);
 
-    const episodeData = evenlySampleArray(episodeRows, MAX_EPISODE_POINTS);
-
-    if (episodeData.length === 0) {
+    if (!frames) {
       return {
         chartDataGroups: [],
         flatChartData: [],
         ignoredColumns: [],
         task: undefined,
-        languageAtoms: extractLanguageAtoms(episodeRows),
+        languageAtoms: extractLanguageAtoms(textRows),
         frameTimestamps,
       };
     }
 
-    // Convert to the same format as v2.x for compatibility with existing chart code
-    const { chartDataGroups, flatChartData, ignoredColumns } =
-      processEpisodeDataForCharts(episodeData, info, episodeMetadata);
+    /// Stretched over the video segment rather than read from `timestamp`, so the chart cursor
+    /// stays in step with the player.
+    const videoDuration =
+      (episodeMetadata.video_to_timestamp || 30) -
+      (episodeMetadata.video_from_timestamp || 0);
+    const { chartDataGroups, flatChartData } = chartDataFromFrames(
+      frames,
+      info,
+      EXCLUDED_COLUMNS.V3,
+      (_, position, count) =>
+        (position / Math.max(count - 1, 1)) * videoDuration,
+    );
+
+    // List of columns that are ignored (now we handle 2D data by flattening)
+    const ignoredColumns = [
+      ...Object.entries(info.features)
+        .filter(
+          ([, value]) =>
+            ["float32", "int32"].includes(value.dtype) &&
+            value.shape.length > 2, // Only ignore 3D+ data
+        )
+        .map(([key]) => key),
+      ...EXCLUDED_COLUMNS.V3,
+    ];
 
     // Prefer the authoritative `tasks` list on the episode's own metadata
     // (v3.0 stores it as list[str] — see lerobot dataset_metadata.save_episode).
@@ -920,7 +772,7 @@ async function loadEpisodeDataV3(
     }
 
     // Fall back to per-frame language_instruction fields
-    if (!task && episodeData.length > 0) {
+    if (!task && textRows.length > 0) {
       const languageInstructions: string[] = [];
 
       const extractInstructions = (row: Record<string, unknown>) => {
@@ -936,15 +788,15 @@ async function loadEpisodeDataV3(
         }
       };
 
-      extractInstructions(episodeData[0]);
+      extractInstructions(textRows[0]);
 
       // If no instructions in first row, check middle and last rows
-      if (languageInstructions.length === 0 && episodeData.length > 1) {
+      if (languageInstructions.length === 0 && textRows.length > 1) {
         for (const idx of [
-          Math.floor(episodeData.length / 2),
-          episodeData.length - 1,
+          Math.floor(textRows.length / 2),
+          textRows.length - 1,
         ]) {
-          extractInstructions(episodeData[idx]);
+          extractInstructions(textRows[idx]);
           if (languageInstructions.length > 0) break;
         }
       }
@@ -955,7 +807,7 @@ async function loadEpisodeDataV3(
     }
 
     // Fall back to tasks metadata parquet
-    if (!task && episodeData.length > 0) {
+    if (!task && textRows.length > 0) {
       try {
         const tasksUrl = buildVersionedUrl(
           repoId,
@@ -966,7 +818,7 @@ async function loadEpisodeDataV3(
         const tasksData = await readParquetAsObjects(tasksArrayBuffer, []);
 
         if (tasksData.length > 0) {
-          const taskIndexNum = bigIntToNumber(episodeData[0].task_index, -1);
+          const taskIndexNum = bigIntToNumber(textRows[0].task_index, -1);
 
           if (taskIndexNum >= 0) {
             // lerobot writes tasks.parquet from a DataFrame with the task
@@ -992,7 +844,7 @@ async function loadEpisodeDataV3(
       flatChartData,
       ignoredColumns,
       task,
-      languageAtoms: extractLanguageAtoms(episodeRows),
+      languageAtoms: extractLanguageAtoms(textRows),
       frameTimestamps,
     };
   } catch {
@@ -1086,191 +938,93 @@ export function extractLanguageAtoms(
   return atoms;
 }
 
-// Process episode data for charts (v3.0 compatible)
-function processEpisodeDataForCharts(
-  episodeData: Record<string, unknown>[],
-  info: DatasetMetadata,
-  episodeMetadata?: EpisodeMetadataV3,
-): {
-  chartDataGroups: ChartRow[][];
-  flatChartData: Record<string, number>[];
-  ignoredColumns: string[];
-} {
-  // Convert parquet data to chart format
-  let seriesNames: string[] = [];
-
-  // Dynamically create a mapping from numeric indices to feature names based on actual dataset features
-  const v3IndexToFeatureMap: Record<string, string> = {};
-
-  // Build mapping based on what features actually exist in the dataset
-  const featureKeys = Object.keys(info.features);
-
-  // Common feature order for v3.0 datasets (but only include if they exist)
-  const expectedFeatureOrder = [
-    "observation.state",
-    "action",
-    "timestamp",
-    "episode_index",
-    "frame_index",
-    "next.reward",
-    "next.done",
-    "index",
-    "task_index",
-  ];
-
-  // Map indices to features that actually exist
-  let currentIndex = 0;
-  expectedFeatureOrder.forEach((feature) => {
-    if (featureKeys.includes(feature)) {
-      v3IndexToFeatureMap[currentIndex.toString()] = feature;
-      currentIndex++;
-    }
-  });
-
-  // Columns to exclude from charts (note: 'task' is intentionally not excluded as we want to access it)
-  const excludedColumns = EXCLUDED_COLUMNS.V3 as readonly string[];
-
-  // Create columns structure similar to V2.1 for proper hierarchical naming
-  const columns: ColumnDef[] = Object.entries(info.features)
-    .filter(
-      ([key, value]) =>
-        ["float32", "int32"].includes(value.dtype) &&
-        value.shape.length === 1 &&
-        !excludedColumns.includes(key),
-    )
-    .map(([key, feature]) => {
-      let column_names: unknown = feature.names;
-      while (typeof column_names === "object" && column_names !== null) {
-        if (Array.isArray(column_names)) break;
-        column_names = Object.values(column_names)[0];
-      }
-      return {
-        key,
-        value: Array.isArray(column_names)
-          ? column_names.map(
-              (name: string) => `${key}${SERIES_NAME_DELIMITER}${name}`,
-            )
-          : Array.from(
-              { length: feature.shape[0] || 1 },
-              (_, i) => `${key}${CHART_CONFIG.SERIES_NAME_DELIMITER}${i}`,
-            ),
-      };
-    });
-
-  // First, extract all series from the first data row to understand the structure
-  if (episodeData.length > 0) {
-    const firstRow = episodeData[0];
-    const allKeys: string[] = [];
-
-    Object.entries(firstRow || {}).forEach(([key, value]) => {
-      if (key === "timestamp") return; // Skip timestamp, we'll add it separately
-
-      // Map numeric key to feature name if available
-      const featureName = v3IndexToFeatureMap[key] || key;
-
-      // Skip if feature doesn't exist in dataset
-      if (!info.features[featureName]) return;
+/**
+ * Columns `frames()` leaves out that the episode view still needs: the task, and the v3.1 language
+ * atoms (lerobot#3467), which lerobot can also write onto v2.x datasets. hyparquet skips requested
+ * columns that are not in the file, so un-annotated datasets cost nothing extra.
+ */
+const TEXT_COLUMNS = [
+  "timestamp",
+  "task",
+  "task_index",
+  "language_instruction",
+  "language_instruction_2",
+  "language_instruction_3",
+  "language_persistent",
+  "language_events",
+];
+
+/** The episode's numeric series from `@huggingface/lerobot`, plus its text columns read alongside. */
+async function loadEpisodeFrames(
+  repoId: string,
+  episode: LeRobotEpisode,
+): Promise<{
+  frames: LeRobotFrames | undefined;
+  textRows: Record<string, unknown>[];
+}> {
+  const data = episode.data;
+  if (!data) return { frames: undefined, textRows: [] };
+  const [frames, textRows] = await Promise.all([
+    leRobotDataset(repoId).frames(episode),
+    fetchParquetFile(data.url).then((file) =>
+      readParquetAsObjects(file, TEXT_COLUMNS, {
+        rowStart: data.fromRow,
+        rowEnd: data.toRow,
+      }),
+    ),
+  ]);
+  return { frames, textRows };
+}
 
-      // Skip excluded columns
-      if (excludedColumns.includes(featureName)) return;
+/** Source-frame timestamps, sorted, for the annotations editor to snap to. */
+function sortedTimestamps(frames: LeRobotFrames | undefined): number[] {
+  return (frames?.timestamps ?? [])
+    .filter((t) => Number.isFinite(t))
+    .sort((a, b) => a - b);
+}
 
-      // Find the matching column definition to get proper names
-      const columnDef = columns.find((col) => col.key === featureName);
-      if (columnDef && Array.isArray(value) && value.length > 0) {
-        // Use the proper hierarchical naming from column definition
-        columnDef.value.forEach((seriesName, idx) => {
-          if (idx < value.length) {
-            allKeys.push(seriesName);
-          }
-        });
-      } else if (typeof value === "number" && !isNaN(value)) {
-        // For scalar numeric values
-        allKeys.push(featureName);
-      } else if (typeof value === "bigint") {
-        // For BigInt values
-        allKeys.push(featureName);
-      }
+/**
+ * Chart rows for an episode, sampled down to MAX_EPISODE_POINTS. An array feature gets one series
+ * per component, named from `info.json` when it lists one name per component and by index otherwise;
+ * a single unnamed component (a reward, a success flag) keeps its bare feature key.
+ */
+function chartDataFromFrames(
+  frames: LeRobotFrames,
+  info: DatasetMetadata,
+  excludedColumns: readonly string[],
+  timestampAt: (frameIndex: number, position: number, count: number) => number,
+): { chartDataGroups: ChartRow[][]; flatChartData: Record<string, number>[] } {
+  const series: [string, number[]][] = [];
+  for (const [key, components] of Object.entries(frames.series)) {
+    if (!info.features[key] || excludedColumns.includes(key)) continue;
+    const names =
+      frames.names[key]?.length === components.length
+        ? frames.names[key]
+        : undefined;
+    components.forEach((values, i) => {
+      const suffix = names?.[i] ?? (components.length > 1 ? i : undefined);
+      series.push([
+        suffix === undefined ? key : `${key}${SERIES_NAME_DELIMITER}${suffix}`,
+        values,
+      ]);
     });
-
-    seriesNames = ["timestamp", ...allKeys];
-  } else {
-    // Fallback to column-based approach like V2.1
-    seriesNames = ["timestamp", ...columns.map(({ value }) => value).flat()];
   }
 
-  const chartData = episodeData.map((row, index) => {
-    const obj: Record<string, number> = {};
-
-    // Add timestamp aligned with video timing
-    // For v3.0, we need to map the episode data index to the actual video duration
-    let videoDuration = episodeData.length; // Fallback to data length
-    if (episodeMetadata) {
-      // Use actual video segment duration if available
-      videoDuration =
-        (episodeMetadata.video_to_timestamp || 30) -
-        (episodeMetadata.video_from_timestamp || 0);
-    }
-    obj["timestamp"] =
-      (index / Math.max(episodeData.length - 1, 1)) * videoDuration;
-
-    // Add all data columns using hierarchical naming
-    if (row && typeof row === "object") {
-      Object.entries(row).forEach(([key, value]) => {
-        if (key === "timestamp") {
-          // Timestamp is already handled above
-          return;
-        }
-
-        // Map numeric key to feature name if available
-        const featureName = v3IndexToFeatureMap[key] || key;
-
-        // Skip if feature doesn't exist in dataset
-        if (!info.features[featureName]) return;
-
-        // Skip excluded columns
-        if (excludedColumns.includes(featureName)) return;
-
-        // Find the matching column definition to get proper series names
-        const columnDef = columns.find((col) => col.key === featureName);
-
-        if (Array.isArray(value) && columnDef) {
-          // For array values like observation.state and action, use proper hierarchical naming
-          value.forEach((val, idx) => {
-            if (idx < columnDef.value.length) {
-              const seriesName = columnDef.value[idx];
-              obj[seriesName] = typeof val === "number" ? val : Number(val);
-            }
-          });
-        } else if (typeof value === "number" && !isNaN(value)) {
-          obj[featureName] = value;
-        } else if (typeof value === "bigint") {
-          obj[featureName] = Number(value);
-        } else if (typeof value === "boolean") {
-          // Convert boolean to number for charts
-          obj[featureName] = value ? 1 : 0;
-        }
-      });
-    }
-
-    return obj;
+  const sampled = evenlySampleIndices(frames.length, MAX_EPISODE_POINTS);
+  const flatChartData = sampled.map((frameIndex, position) => {
+    const row: Record<string, number> = {
+      timestamp: timestampAt(frameIndex, position, sampled.length),
+    };
+    for (const [name, values] of series) row[name] = values[frameIndex];
+    return row;
   });
 
-  // List of columns that are ignored (now we handle 2D data by flattening)
-  const ignoredColumns = [
-    ...Object.entries(info.features)
-      .filter(
-        ([, value]) =>
-          ["float32", "int32"].includes(value.dtype) && value.shape.length > 2, // Only ignore 3D+ data
-      )
-      .map(([key]) => key),
-    ...excludedColumns, // Also include the manually excluded columns
-  ];
-
-  // Process chart data into organized groups using utility function
-  const chartGroups = processChartDataGroups(seriesNames, chartData);
-
-  const chartDataGroups = chartGroups.map((group) =>
-    chartData.map((row) => {
+  const seriesNames = ["timestamp", ...series.map(([name]) => name)];
+  const chartDataGroups = processChartDataGroups(
+    seriesNames,
+    flatChartData,
+  ).map((group) =>
+    flatChartData.map((row) => {
       const grouped = groupRowBySuffix(pick(row, [...group, "timestamp"]));
       // Ensure timestamp is always a number at the top level
       return {
@@ -1281,7 +1035,7 @@ function processEpisodeDataForCharts(
     }),
   );
 
-  return { chartDataGroups, flatChartData: chartData, ignoredColumns };
+  return { chartDataGroups, flatChartData };
 }
 
 // ─── Stats computation ───────────────────────────────────────────
@@ -2252,7 +2006,7 @@ export async function loadEpisodeFlatChartData(
     version,
     info,
     toEpisodeMetadataV3(episode),
-    episode.data,
+    episode,
   );
   return flatChartData;
 }