+
+ );
+}
+```
+
+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/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..6cddc23
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,58 @@
+# Troubleshooting
+
+## 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/eslint.config.js b/eslint.config.js
index b7d2d7f..9669df6 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,25 @@ 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',
+ ],
+ },
+ ],
},
},
]);
diff --git a/etc/lerobot-studio.api.md b/etc/lerobot-studio.api.md
new file mode 100644
index 0000000..c3927e9
--- /dev/null
+++ b/etc/lerobot-studio.api.md
@@ -0,0 +1,70 @@
+## 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 default_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