+
+ );
+}
+```
+
+The host must give the viewer an explicit height. The component fills its
+container and does not choose a page height.
+
+## Runtime contract
+
+- React and React DOM `^19.0.0`
+- ESM only
+- browser and client-side rendering only
+- no Node.js, CommonJS, React Server Components, SSR, or hydration support
+
+In Next.js, load the viewer from a Client Component with SSR disabled:
+
+```tsx
+'use client';
+
+import dynamic from 'next/dynamic';
+
+const Viewer = dynamic(
+ () => import('@ioai/lerobot-studio').then((module) => module.LeRobotViewer),
+ { ssr: false },
+);
+```
+
+See the [stable API](./api.md) for custom data sources, callbacks, and errors.
+
+## Develop this repository
+
+```bash
+npm ci
+npm run fixtures:generate
+npm run dev
+```
+
+To work on this documentation site:
+
+```bash
+npm run docs:dev
+```
diff --git a/docs/quick-start.zh-CN.md b/docs/quick-start.zh-CN.md
new file mode 100644
index 0000000..1f5999e
--- /dev/null
+++ b/docs/quick-start.zh-CN.md
@@ -0,0 +1,73 @@
+# 快速开始
+
+> **Language / 语言：** [English](./quick-start.md) | [简体中文](./quick-start.zh-CN.md)
+
+LeRobot Studio 有两个入口：
+
+- 托管应用 [lerobot.studio](https://lerobot.studio)；以及
+- 浏览器专用 React 包（`@ioai/lerobot-studio` 发布后）。
+
+## 使用托管查看器
+
+打开在线应用，选择本地文件夹、本地归档或远程归档。本地内容在浏览器中处理。远程归档须满足 [CORS 与 HTTP Range 要求](./cors) 中的约定。
+
+## 嵌入 React 查看器
+
+::: warning 发布状态
+`@ioai/lerobot-studio@1.0.0` 尚未发布。安装与下方稳定契约仅在 [1.0 发布门禁](./compatibility#_1-0-acceptance-gates) 通过后可用。
+:::
+
+```bash
+npm install @ioai/lerobot-studio
+```
+
+```tsx
+import { LeRobotViewer } from '@ioai/lerobot-studio';
+import '@ioai/lerobot-studio/style.css';
+
+export function DatasetViewer() {
+ return (
+
+
+ );
+}
+```
+
+宿主必须为查看器提供明确高度。组件会填满容器，不会自行决定页面高度。
+
+## 运行时契约
+
+- React 与 React DOM `^19.0.0`
+- 仅 ESM
+- 仅浏览器与客户端渲染
+- 不支持 Node.js、CommonJS、React Server Components、SSR 或 hydration
+
+在 Next.js 中，从 Client Component 加载查看器并禁用 SSR：
+
+```tsx
+'use client';
+
+import dynamic from 'next/dynamic';
+
+const Viewer = dynamic(
+ () => import('@ioai/lerobot-studio').then((module) => module.LeRobotViewer),
+ { ssr: false },
+);
+```
+
+自定义数据源、回调与错误处理见 [稳定 API](./api)。
+
+## 开发本仓库
+
+```bash
+npm ci
+npm run fixtures:generate
+npm run dev
+```
+
+开发本文档站点：
+
+```bash
+npm run docs:dev
+```
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..0479146
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,60 @@
+# Troubleshooting
+
+> **Language / 语言：** [English](./troubleshooting.md) | [简体中文](./troubleshooting.zh-CN.md)
+
+## The viewer has zero height
+
+`LeRobotViewer` fills its container. Give the host element an explicit height
+or a layout constraint that resolves to a non-zero height.
+
+```tsx
+
+
+```
+
+## A remote archive does not open
+
+1. Confirm the final URL is reachable with `GET` from the viewer origin.
+2. Inspect redirects; every final response must preserve the required CORS
+ headers.
+3. Send a small byte request and verify a `206 Partial Content` response with a
+ valid `Content-Range`.
+4. Expose `Accept-Ranges`, `Content-Length`, and `Content-Range` to browser
+ code.
+5. Check whether a signed URL expired or a CDN removed the `Range` header.
+
+See [CORS and HTTP Range](./cors.md) for example headers.
+
+## An archive type is rejected
+
+The public archive factory accepts ZIP, TAR, and TAR.GZ files. For remote
+sources, use a URL and response that allow the archive kind to be identified.
+Use `onFatalError` to distinguish `UNSUPPORTED_ARCHIVE` from network and
+dataset failures.
+
+## A dataset opens with a warning
+
+Only exact declared versions `v2.1` and `v3.0` are intended for 1.0 support.
+Any other or missing `codebase_version` is unknown. Safe inspection may remain
+available in warning-marked read-only mode, but export must stay disabled.
+
+## Video is unavailable
+
+Playback depends on the browser and codec used by the dataset. Test the same
+asset in the target browser and inspect its media errors. A viewer smoke test
+does not establish support for every codec. Non-media data should remain
+inspectable where safe.
+
+## Next.js fails during server rendering
+
+Render the viewer from a Client Component and load it dynamically with
+`ssr: false`. The package is browser-only and does not support React Server
+Components or server rendering. See [Quick Start](./quick-start.md).
+
+## A custom data source leaks memory
+
+Revoke generated object URLs in `invalidateObjectUrl()` or `clear()`, release
+archive handles, and ensure repeated reads do not retain full buffers without a
+bounded cache. The host owns the lifecycle of a custom
+[`DataSource`](./api.md).
diff --git a/docs/troubleshooting.zh-CN.md b/docs/troubleshooting.zh-CN.md
new file mode 100644
index 0000000..2bb23d8
--- /dev/null
+++ b/docs/troubleshooting.zh-CN.md
@@ -0,0 +1,43 @@
+# 故障排查
+
+> **Language / 语言：** [English](./troubleshooting.md) | [简体中文](./troubleshooting.zh-CN.md)
+
+## 查看器高度为零
+
+`LeRobotViewer` 会填满其容器。为宿主元素提供明确高度，或提供可解析为非零高度的布局约束。
+
+```tsx
+
+
+```
+
+## 远程归档无法打开
+
+1. 确认最终 URL 可从查看器源用 `GET` 访问。
+2. 检查重定向；每个最终响应须保留必需的 CORS 头。
+3. 发送小字节请求，验证 `206 Partial Content` 与有效的 `Content-Range`。
+4. 向浏览器代码暴露 `Accept-Ranges`、`Content-Length` 与 `Content-Range`。
+5. 检查签名 URL 是否过期，或 CDN 是否移除了 `Range` 头。
+
+示例头见 [CORS 与 HTTP Range](./cors)。
+
+## 归档类型被拒绝
+
+公开归档工厂接受 ZIP、TAR 与 TAR.GZ 文件。对于远程源，请使用允许识别归档种类的 URL 与响应。使用 `onFatalError` 区分 `UNSUPPORTED_ARCHIVE` 与网络及数据集失败。
+
+## 数据集打开但带警告
+
+仅精确声明的版本 `v2.1` 与 `v3.0` 为 1.0 目标支持范围。任何其他或缺失的 `codebase_version` 均为未知。在安全时可能仍以带警告的只读模式提供检查，但导出须保持禁用。
+
+## 视频不可用
+
+播放取决于浏览器与数据集使用的编解码器。在目标浏览器中测试相同资源并检查媒体错误。查看器冒烟测试并不建立对每个编解码器的支持。在安全时非媒体数据仍应可检查。
+
+## Next.js 在服务端渲染时失败
+
+从 Client Component 渲染查看器，并用 `ssr: false` 动态加载。包仅适用于浏览器，不支持 React Server Components 或服务端渲染。见 [快速开始](./quick-start)。
+
+## 自定义数据源泄漏内存
+
+在 `invalidateObjectUrl()` 或 `clear()` 中撤销生成的 object URL，释放归档句柄，并确保重复读取不会在无界缓存中保留完整 buffer。自定义 [`DataSource`](./api) 的生命周期由宿主拥有。
diff --git a/eslint.config.js b/eslint.config.js
index b7d2d7f..41b81bc 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -13,8 +13,6 @@ export default defineConfig([
'node_modules/**',
'tests/fixtures/datasets/**',
'**/*.d.ts',
- // Pre-monorepo leftover tree; packages/* + apps/* are authoritative.
- 'src/**',
]),
{
files: ['**/*.{ts,tsx}'],
@@ -44,8 +42,26 @@ export default defineConfig([
'@typescript-eslint/no-explicit-any': 'off',
// ESLint 10 新增：既有 Error 包装模式未统一 attach cause
'preserve-caught-error': 'off',
- // shadcn / Context 模式会同时导出组件与 hook/variants
- 'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+ // Context hooks and shadcn variants intentionally share their component module.
+ 'react-refresh/only-export-components': [
+ 'warn',
+ {
+ allowConstantExport: true,
+ allowExportNames: [
+ 'useDockviewApi',
+ 'useLoading',
+ 'useToast',
+ 'useI18nController',
+ 'useTranslationBridge',
+ 'reportIntlError',
+ 'badgeVariants',
+ 'buttonVariants',
+ 'tabsListVariants',
+ 'usePortalContainer',
+ 'metadata',
+ ],
+ },
+ ],
},
},
]);
diff --git a/etc/lerobot-studio.api.md b/etc/lerobot-studio.api.md
new file mode 100644
index 0000000..b3ec763
--- /dev/null
+++ b/etc/lerobot-studio.api.md
@@ -0,0 +1,68 @@
+## API Report File for "@ioai/lerobot-studio"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { default as React_2 } from 'react';
+
+// @public
+export function createArchiveDataSourceFromFile(file: File): DataSource;
+
+// @public
+export function createArchiveDataSourceFromUrl(url: string): DataSource;
+
+// @public
+export interface DataSource {
+ clear(): void | PromiseLoading LeRobot Studio…
, +}); + +export function ViewerClient() { + return
) : null}
@@ -345,7 +352,14 @@ export const Navbar: React.FC