Deploy Orbit Video Viewer to Hugging Face Spaces

.gitattributes

@@ -0,0 +1,6 @@
+* text=auto eol=lf
+
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.DS_Store
+*.log
+*.tsbuildinfo
+
+# Local publishing plans; not part of the public repository.
+publishing/huggingface-article/

ASSETS.md

@@ -0,0 +1,31 @@
+# Demo media
+
+The sample image and video in `public/demo/` were created by the repository owner with Jimeng AI and are included so the interactive work can be experienced immediately.
+
+They are made available under the [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/), to the extent the repository owner holds rights in the generated media:
+
+- `public/demo/poster.png`
+- `public/demo/video_01.mp4`
+
+Suggested attribution: **“Orbit Comic demo artwork, created with Jimeng AI.”**
+
+The MIT software license and the CC BY 4.0 media license are separate. You may replace both files with your own media; your replacement media keeps whatever license you choose for it.
+
+## README media
+
+The current README preview and its reproducible recording sources were created from Jimeng AI media supplied by the repository owner. They follow the same CC BY 4.0 terms, to the extent the repository owner holds rights in the generated media:
+
+- `recording-comic/assets/shot.png`
+- `recording-comic/assets/impact.png`
+- `recording-comic/output/orbit-comic-demo.gif`
+- `recording-comic/output/orbit-comic-demo.mp4`
+
+The following concept images were generated for this repository with OpenAI ImageGen and are also offered under CC BY 4.0, to the extent the repository owner holds rights in them:
+
+- `docs/assets/concepts/product-viewer.jpg`
+- `docs/assets/concepts/game-item-inspection.jpg`
+- `docs/assets/concepts/interactive-comic.jpg`
+
+They illustrate possible uses only. They are not screenshots of completed bundled applications.
+
+The exact generation prompts are recorded in [`docs/assets/concepts/PROMPTS.md`](docs/assets/concepts/PROMPTS.md).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orbit Panel Viewer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.huggingface.md

@@ -0,0 +1,64 @@
+---
+title: Orbit Comic Demo
+emoji: 🎞️
+colorFrom: gray
+colorTo: red
+sdk: static
+app_file: dist/index.html
+app_build_command: npm run build:demo
+fullWidth: true
+header: mini
+short_description: A live demo of the Orbit Video Viewer library.
+---
+
+# Orbit Video Viewer
+
+**Turn pre-rendered orbit videos into interactive, drag-controlled views. No 3D models required.**
+
+Orbit Comic is the live demonstration above. Drag horizontally across the artwork to browse the viewpoints encoded in the MP4. Use **Change video** to try your own local MP4; the file stays in your browser and is not uploaded by this app.
+
+The reusable open-source project provides `OrbitViewer`, browser-side MP4 processing, a public control API, an integration Skill for AI coding agents, and a standalone consumer example.
+
+> **Technique credit:** This project studies an interaction technique shared by [monoradio (@monoradio102)](https://x.com/monoradio102) through a Claude Artifact. The code was independently implemented with Codex and does not copy the Artifact's source.
+
+## Source and local use
+
+The canonical source is [boryzoo/orbit-video-viewer on GitHub](https://github.com/boryzoo/orbit-video-viewer). Use GitHub for the editable source, installation documentation, version history, and [issue tracking](https://github.com/boryzoo/orbit-video-viewer/issues). This Space is the live demonstration of the same project.
+
+For a local source checkout:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+The verified release target is Chromium with H.264 MP4. Safari and Firefox support remains pending the same manual interaction matrix. This is controlled viewpoint playback rather than real 3D; it cannot reveal angles absent from the source video.
+
+---
+
+# Orbit Video Viewer（中文）
+
+**把预先生成的环绕视频变成可拖动控制视角的网页交互，不需要 3D 模型。**
+
+上方的 Orbit Comic 是在线演示。请在画面中水平拖动，浏览 MP4 已经包含的不同观察视角。使用 **Change video** 可以尝试自己的本地 MP4；文件只在浏览器内处理，不会由这个应用上传。
+
+可复用的开源项目包含 `OrbitViewer`、浏览器端 MP4 处理、公开控制 API、供 AI 编程工具使用的接入 Skill，以及一个独立消费示例。
+
+> **技术灵感署名：** 本项目研究了 [monoradio（@monoradio102）](https://x.com/monoradio102) 通过 Claude Artifact 分享的交互思路。代码由 Codex 独立实现，没有复制该 Artifact 的源码。
+
+## 源码与本地运行
+
+项目的唯一源码基准是 GitHub 上的 [boryzoo/orbit-video-viewer](https://github.com/boryzoo/orbit-video-viewer)。可编辑源码、安装说明和版本历史以 GitHub 为准；问题可提交到 [GitHub Issues](https://github.com/boryzoo/orbit-video-viewer/issues)。这个 Space 是同一项目的在线演示入口。
+
+本地源码运行方式：
+
+```bash
+pnpm install
+pnpm dev
+```
+
+当前已经验证的发布目标是 Chromium + H.264 MP4；Safari 与 Firefox 尚待完成同等手动交互测试。这是受控的视角回放，不是真实 3D，不能生成源视频中不存在的角度。
+
+## License / 许可
+
+Software is MIT licensed. Demo media has separate terms documented in `ASSETS.md`. 技术代码使用 MIT License；演示媒体的独立条款见 `ASSETS.md`。

README.md

@@ -0,0 +1,64 @@
+---
+title: Orbit Comic Demo
+emoji: 🎞️
+colorFrom: gray
+colorTo: red
+sdk: static
+app_file: dist/index.html
+app_build_command: npm run build:demo
+fullWidth: true
+header: mini
+short_description: A live demo of the Orbit Video Viewer library.
+---
+
+# Orbit Video Viewer
+
+**Turn pre-rendered orbit videos into interactive, drag-controlled views. No 3D models required.**
+
+Orbit Comic is the live demonstration above. Drag horizontally across the artwork to browse the viewpoints encoded in the MP4. Use **Change video** to try your own local MP4; the file stays in your browser and is not uploaded by this app.
+
+The reusable open-source project provides `OrbitViewer`, browser-side MP4 processing, a public control API, an integration Skill for AI coding agents, and a standalone consumer example.
+
+> **Technique credit:** This project studies an interaction technique shared by [monoradio (@monoradio102)](https://x.com/monoradio102) through a Claude Artifact. The code was independently implemented with Codex and does not copy the Artifact's source.
+
+## Source and local use
+
+The canonical source is [boryzoo/orbit-video-viewer on GitHub](https://github.com/boryzoo/orbit-video-viewer). Use GitHub for the editable source, installation documentation, version history, and [issue tracking](https://github.com/boryzoo/orbit-video-viewer/issues). This Space is the live demonstration of the same project.
+
+For a local source checkout:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+The verified release target is Chromium with H.264 MP4. Safari and Firefox support remains pending the same manual interaction matrix. This is controlled viewpoint playback rather than real 3D; it cannot reveal angles absent from the source video.
+
+---
+
+# Orbit Video Viewer（中文）
+
+**把预先生成的环绕视频变成可拖动控制视角的网页交互，不需要 3D 模型。**
+
+上方的 Orbit Comic 是在线演示。请在画面中水平拖动，浏览 MP4 已经包含的不同观察视角。使用 **Change video** 可以尝试自己的本地 MP4；文件只在浏览器内处理，不会由这个应用上传。
+
+可复用的开源项目包含 `OrbitViewer`、浏览器端 MP4 处理、公开控制 API、供 AI 编程工具使用的接入 Skill，以及一个独立消费示例。
+
+> **技术灵感署名：** 本项目研究了 [monoradio（@monoradio102）](https://x.com/monoradio102) 通过 Claude Artifact 分享的交互思路。代码由 Codex 独立实现，没有复制该 Artifact 的源码。
+
+## 源码与本地运行
+
+项目的唯一源码基准是 GitHub 上的 [boryzoo/orbit-video-viewer](https://github.com/boryzoo/orbit-video-viewer)。可编辑源码、安装说明和版本历史以 GitHub 为准；问题可提交到 [GitHub Issues](https://github.com/boryzoo/orbit-video-viewer/issues)。这个 Space 是同一项目的在线演示入口。
+
+本地源码运行方式：
+
+```bash
+pnpm install
+pnpm dev
+```
+
+当前已经验证的发布目标是 Chromium + H.264 MP4；Safari 与 Firefox 尚待完成同等手动交互测试。这是受控的视角回放，不是真实 3D，不能生成源视频中不存在的角度。
+
+## License / 许可
+
+Software is MIT licensed. Demo media has separate terms documented in `ASSETS.md`. 技术代码使用 MIT License；演示媒体的独立条款见 `ASSETS.md`。

README.zh-CN.md

@@ -0,0 +1,153 @@
+<p align="right"><a href="README.md">English</a> · <strong>简体中文</strong></p>
+
+<p align="center">
+  <img src="recording-comic/output/orbit-comic-demo.gif" alt="三格漫画演示：拖动指示器移动时，主画面的观察视角随之变化" width="720">
+</p>
+
+<h1 align="center">Orbit Video Viewer</h1>
+
+<p align="center"><strong>把预先生成的环绕视频变成可拖动控制视角的网页交互，不需要 3D 模型。</strong></p>
+
+<p align="center">
+  <a href="#体验-demo">体验 Demo</a> ·
+  <a href="#通过-ai-编程工具使用-skill">使用 Skill</a> ·
+  <a href="#直接使用-sdk">使用 SDK</a>
+</p>
+
+Orbit Comic 是仓库内附的演示作品；这个开源项目的主体是其下方可复用的交互能力：载入一段环绕 MP4，让用户通过拖动浏览不同视角，读取或设置当前角度，并把它嵌入自己的产品。
+
+> **技术灵感署名：** 本项目研究了 [monoradio（@monoradio102）](https://x.com/monoradio102) 通过 Claude Artifact 分享的交互思路。代码由 Codex 独立实现，没有复制该 Artifact 的源码。
+
+## 可以用它做什么？
+
+<table>
+  <tr>
+    <td width="33%"><img src="docs/assets/concepts/product-viewer.jpg" alt="可拖动商品查看器概念图"></td>
+    <td width="33%"><img src="docs/assets/concepts/game-item-inspection.jpg" alt="游戏道具多视角检查概念图"></td>
+    <td width="33%"><img src="docs/assets/concepts/interactive-comic.jpg" alt="互动漫画视角探索概念图"></td>
+  </tr>
+  <tr>
+    <td align="center"><strong>商品查看器</strong></td>
+    <td align="center"><strong>游戏道具检查</strong></td>
+    <td align="center"><strong>互动漫画</strong></td>
+  </tr>
+</table>
+
+这些图片只用于说明可能的应用方向，不是仓库内已经完成的独立产品。同一种交互也可以用于展览、角色展示、教育、建筑和互动艺术。
+
+## 开始使用
+
+### 通过 AI 编程工具使用 Skill
+
+[`integrate-orbit-video` Skill](skills/integrate-orbit-video/SKILL.md) 会指导 AI 编程工具把 SDK 和你的 MP4 接入现有网页项目，同时尽量保留原项目的视觉设计。
+
+最简单的使用方式是下载本仓库，在 AI 编程工具中打开你自己的项目，并向工具提供三个路径：你的项目、你的 MP4 和这个 Skill 文件。然后输入：
+
+```text
+使用 integrate-orbit-video Skill，把我的环绕 MP4 接入这个项目。
+```
+
+如果需要反复使用，可以把整个 `skills/integrate-orbit-video` 文件夹安装到工具的 Skill 目录。Claude Code 项目级 Skill 可放在 `.claude/skills/integrate-orbit-video/`；兼容 Codex 的工具可以使用其本地或项目 Skill 目录，也可以直接读取仓库中的 `SKILL.md`。
+
+这个 Skill 采用 OpenAI 与 Claude Code 所描述的开放 `SKILL.md` Agent Skills 格式。它已经在 Codex 工作流中完成真实接入测试；其他工具是否能自动发现和调用，取决于其具体版本与配置。详见 [Skill 验证记录](docs/SKILL_VALIDATION.md)。
+
+### 直接使用 SDK
+
+npm 包尚未公开发布。当前可先构建本仓库，再通过本地文件依赖安装：
+
+```bash
+pnpm install
+pnpm build:library
+pnpm add /absolute/path/to/orbit-panel-viewer
+```
+
+```html
+<div id="orbit-view" tabindex="0"></div>
+```
+
+```css
+#orbit-view {
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  cursor: grab;
+  touch-action: pan-y;
+  user-select: none;
+}
+
+#orbit-view canvas { display: block; width: 100%; height: 100%; }
+```
+
+```ts
+import { OrbitViewer, createMp4Source } from 'orbit-video-viewer';
+
+const element = document.querySelector<HTMLElement>('#orbit-view');
+if (!element) throw new Error('Missing orbit view.');
+
+const viewer = new OrbitViewer({ element, initialAngle: 0 });
+await viewer.load(createMp4Source('/assets/orbit.mp4'));
+
+viewer.setAngle(90, { animate: true });
+viewer.reset();
+```
+
+更多内容见[接入指南](docs/INTEGRATION.md)、[公开 API](#公开-api)和独立的 [`basic-integration`](examples/basic-integration) 消费项目。
+
+## 公开 API
+
+| API | 用途 |
+|---|---|
+| `createMp4Source(urlOrFile)` | 载入 MP4 URL、`File` 或 `Blob` |
+| `load(source, options?)` | 准备并显示素材 |
+| `getAngle()` / `getState()` | 读取当前视图状态 |
+| `setAngle(degrees, options?)` | 移动到指定视角 |
+| `rotateBy(degrees, options?)` | 相对当前视角旋转 |
+| `reset(options?)` | 回到当前视频的初始视角 |
+| `setInteractionEnabled(boolean)` | 启用或禁用用户输入 |
+| `destroy()` | 释放资源和事件监听 |
+
+通用 `OrbitSource` 接口把 Viewer 与解码逻辑分开。当前版本只实现浏览器端 MP4 处理，不包含预处理工具。
+
+## 源视频要求
+
+建议使用 H.264 MP4：画面应是一段连续的水平环绕运动，主体大小和相机高度保持稳定，不要切镜；如果希望首尾循环，结束视角应尽量接近开场视角。
+
+这是一种受控的视角回放，不是真实 3D。它不能生成视频中不存在的角度、改变几何结构、提供碰撞或重新打光。MP4 中的音频会被忽略。
+
+## 体验 Demo
+
+不要直接双击 `index.html`。请启动开发服务器：
+
+```bash
+pnpm install
+pnpm dev
+```
+
+然后打开 Vite 输出的本地地址。使用 **Change video** 可以尝试自己的 MP4；**Reset view** 会回到当前已载入视频的初始视角。
+
+## 项目结构
+
+```text
+src/core/                    内部运动、帧、缓存和素材契约
+src/library/                 对外 OrbitViewer SDK
+src/demo/                    Orbit Comic 展示界面
+skills/integrate-orbit-video AI 辅助接入流程
+examples/basic-integration  独立 SDK 消费项目
+public/demo/                 内置 Orbit Comic 媒体
+```
+
+## 文档
+
+- [English README](README.md)
+- [接入指南](docs/INTEGRATION.md)
+- [技术报告](docs/TECHNICAL_REPORT.md)
+- [浏览器兼容性](docs/COMPATIBILITY.md)
+- [来源与署名](docs/ORIGIN_AND_ATTRIBUTION.md)
+- [验证记录](VALIDATION.md)
+- [发布清单](docs/RELEASE_CHECKLIST.md)
+- [发布执行手册](docs/PUBLISHING_RUNBOOK.zh-CN.md)
+- [产品与发布决策](docs/PROJECT_AND_PUBLISHING.zh-CN.md)
+- [Hugging Face Space README 模板](README.huggingface.md)
+
+## 许可
+
+Library、Demo 源码和 Skill 使用 [MIT License](LICENSE)。Demo 与 README 媒体采用单独条款，见 [ASSETS.md](ASSETS.md)；第三方软件见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,17 @@
+# Third-party notices
+
+The distributed Library has one runtime dependency:
+
+| Package | Version checked | License | Purpose |
+|---|---:|---|---|
+| `mp4box` | 2.4.1 | BSD-3-Clause | MP4 parsing and encoded sample extraction |
+
+Development and validation use:
+
+| Package | Version checked | License |
+|---|---:|---|
+| `vite` | 8.3.4 | MIT |
+| `vitest` | 5.0.3 | MIT |
+| `typescript` | 7.0.2 | Apache-2.0 |
+
+These entries were checked against the installed packages' own `package.json` metadata on 2026-10-12. Their licenses remain their authors' licenses; the repository's MIT License does not replace them.

VALIDATION.md

@@ -0,0 +1,82 @@
+# V0.3 验证记录
+
+验证日期：2026-10-12（Asia/Shanghai）
+
+## 本次验收范围
+
+- Core、Library、Demo 已明确分层；
+- Orbit Comic 改为通过公开 Library API 运行；
+- Library 可以生成独立 ES Module 和 TypeScript 类型声明；
+- 独立项目通过本地包依赖安装 Library，没有直接引用主项目 `src/`；
+- 没有实现预处理工具或其他超出范围的扩展。
+- 新增基于同一 Library 的 `integrate-orbit-video` Skill；
+- 完成 Skill 驱动的全新临时项目接入验收；
+- README 已按“作品效果 → 使用想象 → Skill / SDK”重新组织；
+- 完成依赖许可、参考来源和浏览器支持范围检查。
+
+## 测试素材
+
+- `public/demo/video_01.mp4`；
+- H.264，852 × 480，约 10.05 秒，约 14 MB；
+- 视频包含 AAC 音轨，但 Library 只使用视频轨；
+- 内容经过正面、侧面、背面、另一侧并返回正面。
+
+## 自动检查
+
+- TypeScript 严格检查：通过；
+- Vitest：1 个文件、4 个用例通过；
+- Orbit Comic Demo 生产构建：通过；
+- Library ES Module 构建：通过；
+- Library TypeScript 类型声明构建：通过；
+- npm tarball 内容检查：通过；
+- `examples/basic-integration` 独立项目 TypeScript 检查与 Vite 构建：通过。
+- Skill 官方结构验证器：通过；
+- Skill 临时消费项目安装、TypeScript 与 Vite 生产构建：通过。
+
+Library 构建结果：
+
+- `dist/library/orbit-viewer.js`：约 15.8 KB，gzip 后约 5.1 KB；
+- `dist/types/`：公开 API 及其依赖类型声明。
+
+## 独立项目浏览器实测
+
+独立项目位于 `examples/basic-integration`，拥有自己的 `package.json`，通过 `file:../..` 安装构建后的 `orbit-video-viewer` 包。
+
+实测结果：
+
+- MP4 成功加载并显示第 0 帧；
+- `onChange` 正确报告 `0° · frame 0`；
+- `setAngle(90)` 到达 `90° · frame 31`；
+- `setAngle(180)` 到达 `180° · frame 62`；
+- `reset()` 返回 `0° · frame 0`；
+- 鼠标拖动后角度与帧持续变化；
+- 浏览器控制台无 warning、无 error。
+
+## Orbit Comic 回归实测
+
+- 默认沙漠作品成功加载；
+- 原页面视觉、标题、署名、Change video 和 Reset view 保留；
+- 拖动正常；
+- Reset view 返回当前视频的初始视角；
+- 浏览器控制台无 warning、无 error。
+
+## Skill 独立接入实测
+
+- 在系统临时目录新建了独立 Vite / TypeScript 项目；
+- 项目从 npm tarball 安装 `orbit-video-viewer@0.1.0`，没有引用主仓库 `src/`；
+- 页面采用与 Orbit Comic 不同的“Relic Study”视觉，不复制 Demo UI；
+- MP4 加载成功，拖动后角度发生变化；
+- Reset view 返回当前视频的 `0°` 初始视角；
+- 控制台无 warning、无 error；
+- 详细步骤见 `docs/SKILL_VALIDATION.md`。
+
+## 已知边界
+
+- 已验证的快速路径是 H.264 MP4，不代表所有 MP4 编码都已验证；
+- `video fallback` 已保留，但本轮没有强制关闭 WebCodecs 单独覆盖该路径；
+- 当前只实现浏览器即时处理 MP4；
+- 已添加通用 `OrbitSource` 接口，但没有实现预处理工具或图片清单加载；
+- 首尾连续性和角色一致性仍由源视频决定；
+- Library 尚未发布到 npm，本轮验证使用本地构建包。
+- Skill 使用开放的 `SKILL.md` 格式并通过结构验证，但目前只在 Codex 执行流程中完成真实接入测试；Claude Code 的目录兼容性有官方依据，尚未在本机 Claude Code 中运行同一验收。
+- Safari 和 Firefox 尚未完成与 Chromium 相同的手动交互矩阵，因此 README 不宣称它们已经完整验证。

docs/COMPATIBILITY.md

@@ -0,0 +1,19 @@
+# Browser compatibility
+
+## What has been verified
+
+- The Demo and independent integration project were exercised in a Chromium-based browser.
+- The WebCodecs H.264 path loaded the bundled 852 × 480 MP4, supported dragging, angle controls, reset, and cleanup without console errors.
+- The package build and TypeScript declarations were consumed by a separate Vite project.
+
+## Runtime requirements
+
+The Viewer needs JavaScript modules, Canvas, Pointer Events, `fetch`, `Blob`, and normal browser media support. The fast path also needs WebCodecs and H.264 decoding.
+
+The code feature-detects the fast path and includes an offscreen `<video>` fallback. That fallback still depends on the browser being able to play the source codec.
+
+## Honest support statement
+
+Chromium with H.264 MP4 is the verified target for this release. Safari and Firefox are intended to use the feature-detected paths, but they have not yet completed the same manual browser matrix. Until that testing is done, they should be described as expected rather than guaranteed support.
+
+The Skill does not change these runtime requirements. It integrates the same SDK into another browser project.

docs/INTEGRATION.md

@@ -0,0 +1,143 @@
+# Library integration guide
+
+Orbit Comic is the Demo. External projects should use the `orbit-video-viewer` Library instead of copying the Demo page or its internal files.
+
+## Build the local package
+
+The first release is not yet published to npm:
+
+```bash
+pnpm install
+pnpm build:library
+```
+
+In another project, add a local file dependency:
+
+```json
+{
+  "dependencies": {
+    "orbit-video-viewer": "file:../path/to/orbit-panel-viewer"
+  }
+}
+```
+
+Run that project's normal package installation after the Library has been built.
+
+## Minimal example
+
+```html
+<div id="viewer" tabindex="0"></div>
+```
+
+```css
+#viewer {
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  cursor: grab;
+  touch-action: pan-y;
+  user-select: none;
+}
+
+#viewer canvas { width: 100%; height: 100%; display: block; }
+```
+
+```ts
+import { OrbitViewer, createMp4Source } from 'orbit-video-viewer';
+
+const element = document.querySelector<HTMLElement>('#viewer')!;
+
+const viewer = new OrbitViewer({
+  element,
+  initialAngle: 0,
+  onProgress(progress) {
+    console.log(`Loading ${Math.round(progress * 100)}%`);
+  },
+  onChange(state) {
+    console.log(`${state.angle.toFixed(0)}°`, state.frame);
+  },
+});
+
+await viewer.load(createMp4Source('/assets/orbit.mp4'), {
+  frameCount: 124,
+  width: 852,
+  height: 480,
+  quality: 0.9,
+});
+
+viewer.setAngle(90, { animate: true });
+viewer.rotateBy(-45);
+viewer.reset({ animate: true });
+
+window.addEventListener('beforeunload', () => viewer.destroy());
+```
+
+`OrbitViewer` creates a Canvas inside the supplied element when a Canvas is not provided. An existing Canvas can be passed with the `canvas` option.
+
+## Loading a visitor's file
+
+```ts
+const file = fileInput.files?.[0];
+if (file) await viewer.load(createMp4Source(file));
+```
+
+The file stays in that browser session and is not uploaded by the Library.
+
+## Connecting product behavior
+
+Use `onChange` to connect viewpoint changes to the surrounding product:
+
+```ts
+const viewer = new OrbitViewer({
+  element,
+  onChange({ angle }) {
+    if (angle >= 80 && angle <= 100) showDetails('left-side');
+    else hideDetails();
+  },
+});
+```
+
+This can drive product labels, game events, sounds, subtitles, or educational annotations. Those features remain in the host product rather than the Library.
+
+## Controls
+
+```ts
+viewer.getAngle();
+viewer.getState();
+viewer.setAngle(180);
+viewer.setAngle(180, { animate: true, duration: 500 });
+viewer.rotateBy(30);
+viewer.reset();
+viewer.setInteractionEnabled(false);
+viewer.destroy();
+```
+
+## Independent example
+
+[`examples/basic-integration`](../examples/basic-integration) is a separate Vite project with its own `package.json`. It installs the built Library through a file dependency rather than importing `src/` directly.
+
+It verifies:
+
+- package exports and TypeScript declarations;
+- MP4 loading from a normal consumer application;
+- automatic Canvas creation;
+- drag interaction;
+- `setAngle()` for front, side, and back views;
+- angle/frame reporting;
+- `reset()` and `destroy()`.
+
+Run it with:
+
+```bash
+pnpm --dir examples/basic-integration install
+pnpm --dir examples/basic-integration dev
+```
+
+Or run the repeatable build check from the repository root:
+
+```bash
+pnpm test:integration
+```
+
+## Future source types
+
+The public `OrbitSource` interface separates the Viewer from MP4 decoding. A future source may load preprocessed image frames, but no preprocessing command or manifest loader is implemented in this release.

docs/ORIGIN_AND_ATTRIBUTION.md

@@ -0,0 +1,19 @@
+# Origin and attribution
+
+## Technique inspiration
+
+The project was inspired by an interaction technique shared publicly by [monoradio (@monoradio102)](https://x.com/monoradio102) through a Claude Artifact.
+
+The repository does not include, translate, or adapt the Artifact's source code. The implementation was written independently with Codex after studying the visible behavior and underlying technique.
+
+Because the reference Artifact's code license has not been established here, none of its code is treated as a dependency or redistributable source. Attribution is included for the technical inspiration, not as a claim that its code is licensed under this repository's MIT License.
+
+## Code and media
+
+- Repository software and the integration Skill: MIT License.
+- Orbit Comic Demo image and video: created by the repository owner with Jimeng AI; terms are listed in `ASSETS.md`.
+- README concept images: generated for this repository with OpenAI ImageGen; terms are listed in `ASSETS.md`.
+
+## Tooling
+
+Codex was used to implement, test, document, and package the project. Tool assistance does not change the repository's license boundaries.

docs/PROJECT_AND_PUBLISHING.zh-CN.md

@@ -0,0 +1,178 @@
+# Orbit Video Viewer：产品与发布决策
+
+这份文档记录当前已经确定的产品规则，以及 GitHub、Hugging Face 的发布分工。以后继续设计或发布时，以这里为共同基准，不必依赖聊天记录。
+
+## 1. 产品定位
+
+开源项目的主体是 **Orbit Video Viewer**：一种可以集成到游戏、商品展示、互动叙事、教育内容和其他网页中的浏览器 Library。
+
+它把预生成的环绕视角视频转换成可实时操控的观察视图，不要求真实 3D 模型或 3D 引擎。
+
+**Orbit Comic** 是面向普通访问者的演示作品，不是开源项目的全部。
+
+- 页面首先服务普通访问者：打开、看见画面、拖动并发现视角变化。
+- 技术人员看到同一件简洁的作品；架构、实现原理和部署说明放在 README 与技术文章中。
+- 页面只保留作品身份、必要操作、克制的加载和错误反馈。
+- 不在主界面解释 WebCodecs、抽帧、缓存、服务器架构等技术细节。
+
+### 三个层次
+
+- **Core**：角度、帧映射、惯性、缓存、Canvas 渲染和素材接口等内部能力；
+- **Library**：开发者直接使用的 `OrbitViewer`、`createMp4Source()` 和公开控制方法；
+- **Demo**：Orbit Comic 的标题、按钮、样式、加载界面和沙漠素材。
+
+对外提供两个使用入口，但底层不是两套技术：
+
+- **Skill**：给不熟悉开发的人使用。用户把项目文件夹和环绕视频交给 Codex、Claude Code 等兼容工具，Skill 指导 AI 调用 Library 完成接入；
+- **SDK / Library**：给开发者直接安装和编程使用。
+
+Skill 只是“如何使用 SDK”的操作说明，不复制、不替代 Core 或 Library。当前真实接入测试已在 Codex 工作流中通过；Claude Code 支持相同的 `SKILL.md` 开放格式和项目级 `.claude/skills/` 目录，但仍应如实区分“格式兼容”和“已经在该工具中实测”。
+
+GitHub 使用英文 `README.md` 与中文 `README.zh-CN.md`，并在顶部互相切换。GitHub README 优先介绍 Library 的用途、集成方法、公开接口、素材要求和技术边界。Hugging Face Space 展示 Orbit Comic；技术报告解释具体实现原理。
+
+### README 浏览顺序
+
+README 应按以下顺序组织：
+
+1. 首先看到 Orbit Comic 的拖动效果动图和一句核心说明；
+2. 看到商品查看、游戏道具检查、互动漫画三种用途概念图；
+3. 再选择通过 Skill 或 SDK 开始使用；
+4. API、素材要求、技术边界和详细原理放在后面。
+
+三张用途图只表达想象空间，必须写明不是已经完成的独立产品。
+
+### 技术来源声明
+
+本项目学习的交互技术思路来自 [monoradio（@monoradio102）](https://x.com/monoradio102) 发布在 Claude Artifact 上的作品。页面头部和 README 都必须保留这一来源声明。
+
+当前项目没有沿用或复制原 Artifact 的源码、HTML 或 CSS，而是理解“环绕视频 → 浏览器抽帧 → 拖动控制帧序号 → Canvas 显示”这条路线后，使用 Codex 独立重新实现。若以后取得原 Artifact 的直接网址，应在现有作者主页链接之外补充该直达链接。
+
+## 2. 当前界面与交互语义
+
+### Reset view
+
+界面使用 **Reset view**，其无障碍说明是 “Return to the original view”。
+
+它只重置**当前已加载视频**的视角：
+
+- 默认沙漠视频中，回到沙漠视频的初始视角；
+- 用户换成自己的视频后，回到该视频的初始视角；
+- 它不会重新加载默认沙漠视频，也不会撤销换视频操作。
+
+如果将来需要恢复内置作品，应另设语义完全不同的操作，例如 **Restore original artwork**，不能让 Reset view 同时承担两种职责。
+
+### Change video
+
+**Change video** 是低频的“更换作品”操作，不与高频的视角重置并排。它位于画面下方的作品说明区域。
+
+用户选择的文件：
+
+- 只在本机浏览器内读取和抽帧；
+- 不上传服务器、不写入项目，也不会永久保存；
+- 刷新或关闭页面后消失；
+- 更换成功后成为当前作品，Reset view 以它为准。
+
+### 标题规则
+
+- 内置演示作品保留专属标题 **Desert Standoff**。
+- 用户载入本地视频后，标题改为中性的 **Untitled Orbit**。
+- 原始文件名作为较小的作品信息显示，长文件名会被省略显示，但完整文件名保留在悬停提示中。
+
+这样既保留沙漠作品的个性，也不会把它的名字错误套用到访问者自己的内容上。未来如果增加作品命名功能，可允许用户直接编辑 “Untitled Orbit”，但当前版本不需要增加这一层操作。
+
+## 3. GitHub 发布什么
+
+GitHub 是项目的**唯一源代码基准（source of truth）**。公开仓库包含：
+
+- 可编辑的完整源代码；
+- README、验证记录和技术文档；
+- 测试、依赖清单与锁文件；
+- 构建和本地运行方法；
+- 授权文件；
+- 当前演示媒��（前提是先确定媒体授权）。
+
+不提交 `node_modules/`、临时缓存、日志等生成内容。访问者既可以 `git clone`，也可以直接使用 GitHub 的 **Download ZIP** 下载源码。正式公开时建议创建 `v0.1.0` 标签和 GitHub Release，后续版本按相同方式发布。
+
+当前视频约 14 MB，低于 GitHub 单文件 100 MiB 的阻止限制，可以作为普通 Git 文件提交。若以后演示媒体显著变大，再考虑 Git LFS 或外部媒体托管。
+
+官方资料：
+
+- [About releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases)
+- [Downloading source code archives](https://docs.github.com/en/repositories/working-with-files/using-files/downloading-source-code-archives)
+- [About large files on GitHub](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-large-files-on-github)
+
+## 4. Hugging Face 发布什么
+
+Hugging Face Space 是同一项目的**在线体验展览页**，不是另一套独立产品。
+
+- 建立公开的 Static Space；
+- 放入与 GitHub 某个正式版本相同的源码；
+- 将仓库中的 `README.huggingface.md` 作为 Space 根目录的 `README.md`：保留英文在前、中文在后的单文件说明，以及最顶部的 Static Space YAML；
+- Hugging Face 根据 README 顶部配置运行 `npm run build:demo`，发布 `dist/index.html`；
+- 不需要 GPU、后端服务器或模型推理端点；
+- 访问者可以直接体验，也可以查看和克隆公开 Space 的代码仓库。
+
+推荐维护方式：先在 GitHub 完成修改、测试和版本标记，再把**同一个发布提交**同步到 Hugging Face。不要分别在两个网站修改代码，否则两个版本很快会漂移。
+
+官方资料：
+
+- [Spaces overview](https://huggingface.co/docs/hub/en/spaces-overview)
+- [Static HTML Spaces](https://huggingface.co/docs/hub/main/spaces-sdks-static)
+
+## 5. 技术文章扮演什么角色
+
+技术文章是开源项目的解释与展示，不是一个不同的软件包。文章应同时链接：
+
+- GitHub：源码、版本、安装、贡献与授权；
+- Hugging Face Space：无需安装即可体验的在线作品。
+
+文章可以采用以下结构：
+
+1. 最终交互效果与创作目标；
+2. 为什么采用“环绕视频 → 浏览器抽帧 → 拖动映射帧序号”；
+3. 浏览器端内存、缓存和兼容性方案；
+4. 如何替换成自己的环绕视频；
+5. 局限、适合的源视频条件与后续方向；
+6. GitHub 与在线 Space 链接。
+
+Hugging Face 的站内 Blog Articles 当前要求个人账号具有有效 PRO，或由符合条件的 Team / Enterprise 组织发布。如果账号不满足条件，可以先把技术说明写进 Space README 和 GitHub 文档，再发布到其他博客平台；这不影响 Space 本身公开展示。
+
+官方资料：[Hugging Face Blog Articles](https://huggingface.co/docs/hub/blog-articles)
+
+## 6. 推荐发布流程
+
+1. 确认演示视频和海报的公开授权；
+2. 运行 `pnpm check:release`，完成测试、生产构建、独立消费项目和 npm 包内容检查；
+3. 补入最终 GitHub、主页和问题反馈 URL；
+4. 在 GitHub 建立公开仓库并推送源码；
+5. 打 `v0.1.0` 标签并创建 GitHub Release；
+6. 把同一发布提交同步到 Hugging Face Static Space，并把 `README.huggingface.md` 用作 Space 根 `README.md`；
+7. 验证线上拖动、Reset view、Change video、移动端布局和错误提示；
+8. 发布技术文章，并互相链接 GitHub 与 Space。
+
+### 当前发布前状态
+
+已经完成：Library 构建、类型声明、npm tarball、独立项目安装、Skill 结构验证、Skill 全新项目接入、Chromium 浏览器交互、第三方依赖许可清单、参考技术来源说明、README 视觉重组。
+
+GitHub 源码仓库已经发布：<https://github.com/boryzoo/orbit-video-viewer>。仓库名为 `orbit-video-viewer`，公开项目名为 **Orbit Video Viewer**。
+
+仍待完成：
+
+- 决定是否同时发布 npm 包；
+- 建立 Hugging Face Static Space 并填写线上 Demo 链接；
+- 在 Safari、Firefox 做同等手动浏览器验收；
+- 如即梦平台条款或画面中的第三方权利存在疑问，发布前再次确认或替换素材。
+
+在用户最终确认前，不创建公开仓库、不推送、不发布 npm 包、不建立公开 Space。
+
+## 7. 授权边界
+
+代码采用 MIT License。演示视频和海报由项目所有者使用即梦 AI 制作，并在权利允许的范围内采用 CC BY 4.0 开放许可；具体说明记录在 `ASSETS.md`。
+
+代码与媒体是两套许可：
+
+- 源代码：MIT；
+- `public/demo/poster.png` 与 `public/demo/video_01.mp4`：CC BY 4.0；
+- 用户自行导入的文件：仍由用户自己决定授权，不会因为使用本项目而改变许可。
+
+若即梦平台条款或素材中包含的第三方权利对公开再分发另有限制，应以这些限制为准，并在发布前替换有疑问的素材。

docs/PUBLISHING_RUNBOOK.zh-CN.md

@@ -0,0 +1,94 @@
+# Orbit Video Viewer 发布执行手册
+
+这份手册只描述正式发布时的顺序和核对点，不授权创建公开仓库、发布 npm 包或建立 Hugging Face Space。任何对外操作都必须等仓库所有者最终确认。
+
+## 1. 当前本地产物
+
+| 对外表面 | 准备使用的文件 | 发布角色 |
+|---|---|---|
+| GitHub 英文首页 | `README.md` | 英文项目入口、SDK 与 Skill 用法 |
+| GitHub 中文首页 | `README.zh-CN.md` | 与英文首页对应的中文入口 |
+| GitHub 首屏动图 | `recording-comic/output/orbit-comic-demo.gif` | 三格漫画交互预览 |
+| 视频发布素材 | `recording-comic/output/orbit-comic-demo.mp4` | 支持视频的平台或文章嵌入 |
+| Hugging Face Space 说明 | `README.huggingface.md` | 发布时改名为 Space 根 `README.md` |
+| Static Space 应用 | 根项目源码，由 `npm run build:demo` 生成 `dist/index.html` | 在线可操作 Demo |
+| npm 包（若决定发布） | `orbit-video-viewer@0.1.0` | Library、类型声明与许可文件 |
+
+`recording-comic/` 只是可复现首屏素材的录制页，不应被描述成 SDK 功能或漫画编辑器。
+
+## 2. 发布前必须由所有者确定
+
+1. 对外项目名与 GitHub 仓库名；
+2. GitHub 账号或组织；
+3. Hugging Face Space 名称与账号或组织；
+4. 是否同步发布 npm `0.1.0`，以及 npm 包名是否继续使用 `orbit-video-viewer`；
+5. 即梦生成媒体及画面内可识别元素是否允许按 `ASSETS.md` 所述方式公开再分发；
+6. Safari、Firefox 是在首发前补测，还是继续明确标记为未完整验证。
+
+这些决定会产生最终 URL。在 URL 确定前，不要在 `package.json` 中编造 `repository`、`homepage` 或 `bugs` 字段。
+
+## 3. 本地候选版本检查
+
+在项目根目录执行：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check:release
+```
+
+检查输出应同时覆盖：
+
+- Vitest 单元测试；
+- Demo 与 Library 生产构建；
+- TypeScript 类型声明；
+- `examples/basic-integration` 独立消费构建；
+- npm tarball 文件清单。
+
+另外手动打开普通 Demo 和 `recording-comic/?capture=1`，确认控制台无报错，三格录制页可以在独立 clone 中载入自己的 `assets/shot.png` 与 `assets/impact.png`。
+
+## 4. GitHub 发布顺序
+
+1. 得到最终确认后再初始化 Git，并创建公开 GitHub 仓库；
+2. 在 `package.json` 写入真实的 `repository`、`homepage` 与 `bugs` URL；
+3. 把 Hugging Face 在线地址补入 `README.md` 与 `README.zh-CN.md`；如果 Space 尚未建立，先保持本地 Demo 说明，不放假链接；
+4. 重新运行本地候选版本检查；
+5. 推送同一个通过检查的提交；
+6. 建立 `v0.1.0` 标签和 GitHub Release；
+7. Release 说明至少列出 Library、Demo、Skill、浏览器验证范围和已知限制。
+
+推荐仓库 Topics：`orbit-viewer`、`interactive-video`、`canvas`、`webcodecs`、`typescript`。Topics 是发布后仓库设置，不需要写进源码。
+
+## 5. Hugging Face Static Space 顺序
+
+1. 建立 **Static Space**，不要建立 Dataset；
+2. 从 GitHub 的正式发布提交同步源码，不在两个平台分别维护功能修改；
+3. 将 `README.huggingface.md` 的占位源码段落换成真实 GitHub、Release 和问题反馈链接；
+4. 在 Space 仓库中让该文件成为根 `README.md`，并保留最顶部 YAML；
+5. 确认构建命令为 `npm run build:demo`，入口为 `dist/index.html`；
+6. 记录 Space 实际对应的 Git commit SHA；
+7. 在线测试拖动、键盘方向键、Reset view、Change video、本地文件隐私说明、窄屏布局、加载与错误反馈。
+
+[Hugging Face 官方文档](https://huggingface.co/docs/hub/main/spaces-sdks-static)确认 Static Space 通过根 `README.md` 顶部 YAML 中的 `sdk: static` 配置，并可使用 `app_build_command` 生成由 `app_file` 指向的静态入口。
+
+## 6. npm 可选发布
+
+只有在所有者明确决定同时发布 npm 后才执行：
+
+1. 确认包名可用且最终包名与 import 示例一致；
+2. 确认 `package.json` 的 URL 字段已经是真实公开地址；
+3. 再次运行 `pnpm pack --dry-run`，确认只包含 Library、类型声明、双语 README 和许可文件；
+4. 在临时消费项目中安装最终 tarball并构建；
+5. 发布 `0.1.0`，然后用公开 registry 安装再做一次最小接入验证。
+
+如果首发不发布 npm，README 继续保留本地文件依赖方式，不把未存在的 registry 安装命令写成可用路径。
+
+## 7. 发布完成判定
+
+只有以下条件同时满足，才把本次发布标记为完成：
+
+- GitHub Release、Hugging Face Space（以及可选 npm 包）来自同一候选版本；
+- GitHub 双语 README 的语言切换、图片和内部链接有效；
+- Space 显示英文在前、中文在后的说明，并能实际操作 Demo；
+- monoradio 技术灵感署名、Codex 独立实现说明、即梦素材来源和许可边界均保留；
+- 线上浏览器检查结果与文档声明一致；
+- 没有把 `recording-comic/` 误称为 SDK 核心能力，也没有宣称存在预处理工具。

docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,55 @@
+# Release checklist
+
+Last updated: 2026-10-12
+
+## Complete
+
+- [x] Core, Library, Demo, and Skill responsibilities are separated.
+- [x] Unit tests pass.
+- [x] Demo production build passes.
+- [x] Library ES module build passes.
+- [x] TypeScript declarations build and work in a consumer project.
+- [x] Public exports include the Viewer, MP4 source, controls, state, and source contracts.
+- [x] `examples/basic-integration` builds without importing repository source files.
+- [x] npm tarball contains JavaScript, declarations, README, MIT License, and third-party notices.
+- [x] Skill manifest passes the Skill creator validator.
+- [x] Skill workflow was followed in a fresh project using the packed SDK.
+- [x] Fresh Skill integration loads, drags, resets, and reports no Chromium console errors.
+- [x] Chromium H.264 MP4 behavior is documented as the verified browser target.
+- [x] Runtime and development dependency licenses are recorded.
+- [x] Reference technique credit and independent-implementation boundary are recorded.
+- [x] Demo and README media licensing is recorded.
+- [x] README leads with the interaction, then use cases, then Skill and SDK entry points.
+- [x] GitHub README uses the three-panel comic recording and links to a complete Chinese README.
+- [x] Hugging Face has a separate bilingual Static Space README template with build metadata.
+- [x] The recording page is self-contained inside the repository and its media is listed in `ASSETS.md`.
+- [x] Package metadata declares Node.js 20+, public npm access, and both README languages in the tarball.
+- [x] A single release-check command covers tests, both production builds, the consumer build, and package contents.
+- [x] Technical report describes the same engine, Skill, runtime processing, and limitations.
+
+## Before public release
+
+- [ ] Repository owner gives final approval to publish.
+- [x] Confirm the public project name **Orbit Video Viewer** and repository name `orbit-video-viewer`.
+- [x] Create the local Git repository and public GitHub remote at `boryzoo/orbit-video-viewer`.
+- [ ] Decide whether version `0.1.0` will also be published to npm.
+- [x] Add the final `repository`, `homepage`, and issue-tracker fields to `package.json`.
+- [ ] Replace the placeholder source paragraph in `README.huggingface.md`, then use that file as the Space repository's root `README.md`.
+- [ ] Create the Hugging Face Static Space and add its public URL to both GitHub READMEs.
+- [ ] Run the manual interaction matrix in Safari and Firefox, or keep their support explicitly unverified.
+- [ ] Reconfirm that Jimeng's applicable terms and all visible media elements permit the intended CC BY 4.0 redistribution; replace the Demo media if uncertain.
+- [ ] Add the direct Claude Artifact URL if it becomes available.
+- [ ] Verify the deployed GitHub and Hugging Face versions come from the same release commit.
+
+## Final local gate
+
+Run from the repository root:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check:release
+```
+
+Then inspect the package file list printed by `pnpm pack --dry-run`. Do not publish it yet. The owner approval, final public URLs, browser matrix, and media-rights confirmation remain human release gates.
+
+No public repository, npm package, or Hugging Face Space should be created until the owner approves release.

docs/SKILL_VALIDATION.md

@@ -0,0 +1,38 @@
+# Skill integration validation
+
+Validation date: 2026-10-12 (Asia/Shanghai)
+
+## Scope
+
+This test checked whether the `integrate-orbit-video` Skill can guide a clean consumer integration rather than merely describing the existing Demo.
+
+The test project was created in a new temporary directory. It did not import repository source files or copy the Orbit Comic Demo interface.
+
+## Procedure
+
+1. Built and packed `orbit-video-viewer@0.1.0` as an npm tarball.
+2. Created a new Vite and TypeScript project with its own visual design.
+3. Installed the tarball as a normal dependency.
+4. Copied an orbit MP4 into the consumer project's public assets.
+5. Added a viewer container, minimal integration CSS, `OrbitViewer`, `createMp4Source()`, progress feedback, a Reset control, and cleanup.
+6. Ran the consumer TypeScript check and production build.
+7. Opened the consumer project in a Chromium-based browser and tested loading, dragging, reset, and console output.
+
+## Result
+
+- Package installation: passed.
+- Public package exports: passed.
+- TypeScript declarations: passed.
+- Consumer production build: passed.
+- Initial MP4 render: passed.
+- Horizontal drag changed the reported angle: passed.
+- Reset returned to `0°`: passed.
+- Browser warnings and errors: none.
+
+The initial consumer build reported a missing declaration for the CSS side-effect import under TypeScript 7. The host project was corrected by adding Vite's client type reference; no SDK source change was needed.
+
+## What this proves
+
+The Skill instructions are sufficient for a coding agent to integrate the built SDK into a separate browser project and handle a normal host-project issue. This is one real validation on a Vite/TypeScript/Chromium stack, not a guarantee that every framework, browser, codec, or AI coding tool has been tested.
+
+The Skill manifest also passes the `skill-creator` structural validator.

docs/TECHNICAL_REPORT.md

@@ -0,0 +1,61 @@
+# Orbit Video Viewer: turning an authored orbit video into a controllable view
+
+## Summary
+
+Orbit Video Viewer is a browser Library that maps user input to viewpoints sampled from a pre-generated orbit video. It creates an art-directed, 3D-like viewing interaction without shipping geometry, materials, lighting, or a 3D runtime.
+
+Orbit Comic is the demonstration application. The open-source capability is the reusable Viewer API beneath it. The optional `integrate-orbit-video` Skill is a workflow layer that teaches compatible AI coding agents how to add the same SDK to an existing browser project; it is not a second engine.
+
+## Input and processing
+
+The current source adapter accepts an MP4 URL or a browser `Blob`. MP4Box reads the H.264 track and supplies encoded samples to WebCodecs. The decoder walks the timeline once and selects evenly spaced target timestamps. Each selected frame is resized and encoded to an in-memory JPEG blob.
+
+When WebCodecs or the H.264 path is unavailable, an offscreen `<video>` element seeks to the same target positions and copies them through Canvas.
+
+The current Demo requests 124 frames at up to 852 × 480 pixels. These are application choices, not protocol requirements.
+
+## Runtime interaction
+
+Horizontal pointer distance is converted into a continuous turn value. The turn wraps cyclically and maps to a frame index. The same mapping supports both directions and any number of complete rotations.
+
+Recent pointer samples estimate release velocity. Exponential decay creates a short inertial glide. Reset and programmatic angle changes can use an eased animation.
+
+The public Library exposes the current angle and frame, allowing a host product to attach labels, game events, sound, educational annotations, or other state to a viewpoint.
+
+## Frame storage and memory
+
+JPEG blobs hold the sampled sequence. Rendering uses decoded `ImageBitmap` objects. A least-recently-used cache retains a small number of bitmaps, while directional prefetch prepares nearby frames.
+
+Destroying a Viewer aborts active work, removes input listeners, closes cached bitmaps, and releases the prepared source.
+
+All extracted frames remain in the visitor's browser memory. The Library does not upload them.
+
+## Architecture
+
+The repository separates three responsibilities:
+
+1. **Core:** angle math, motion, frame storage, rendering, and the general source contract.
+2. **Library:** the stable `OrbitViewer` API and the current `Mp4Source` adapter.
+3. **Demo:** Orbit Comic's artwork, layout, title, buttons, loading UI, and local-file control.
+
+The Demo uses the public Library API instead of assembling Core classes directly. A separate consumer project installs the built package to verify that the Library boundary is real.
+
+Distribution adds a fourth, non-runtime layer: the integration Skill. Its `SKILL.md` inspects a host project, installs the Library, follows that project's component lifecycle, and verifies the resulting build. Applications created with the Skill still import the public Library API and do not depend on the Demo.
+
+## Runtime MP4 versus preprocessed frames
+
+Runtime MP4 processing keeps authoring simple and enables local visitor uploads. Its trade-offs are startup decoding work, memory use, and browser codec differences.
+
+A production deployment may eventually preprocess frames and load them from a manifest or CDN. The `OrbitSource` contract was added so that such a source can be introduced later without changing the Viewer API. This release deliberately does not include that preprocessing tool.
+
+## Limits
+
+The Library can only show viewpoints present in its source. It cannot move freely through 3D space, repair discontinuities, change geometry, calculate collisions, or relight a scene.
+
+The verified fast path uses H.264 MP4. Browser fallbacks depend on codecs supported by each browser. Source continuity remains an authoring responsibility.
+
+The current manual browser verification covers a Chromium-based browser. Other modern browsers are feature-detected but should not be described as fully verified until the same interaction matrix has been run there.
+
+## Credits
+
+The interaction direction was learned from a Claude Artifact shared by [monoradio (@monoradio102)](https://x.com/monoradio102). This repository is an independent implementation written with Codex and does not copy the reference Artifact's source code.

docs/assets/concepts/PROMPTS.md

@@ -0,0 +1,21 @@
+# README concept image prompts
+
+These images were generated with OpenAI ImageGen on 2026-10-12 and resized for the README. The full-resolution originals remain in the local ImageGen output directory used during development.
+
+## Product Viewer
+
+> Create a high-end landscape concept image for an open-source README, 16:9. Scene: an elegant unbranded contemporary sneaker on a low matte stone plinth in a restrained warm-gray studio. The product is the only subject, shown with subtle ghosted side-angle silhouettes and a delicate curved orbit cue suggesting that a viewer can drag to rotate it. Visual style: mature editorial product photography blended with refined digital-art direction; quiet, international, premium, believable materials, soft directional light, generous negative space. Constraints: no people, no logos, no words, no readable UI text, no watermark, no brand marks, no busy dashboard, no split screen. The image must read clearly at a small README width. Output intent: inspiration card titled externally as “Product Viewer”; do not put the title inside the image.
+
+Saved as `product-viewer.jpg`.
+
+## Game Item Inspection
+
+> Create a high-end landscape concept image for an open-source README, 16:9. Scene: a single mysterious fantasy game artifact—a weathered dark-metal compass-like relic with a luminous amber core—floating above a minimal inspection pedestal in a deep charcoal environment. Show a few restrained technical tick marks and a subtle circular orbit cue around the item, communicating that a player can drag and inspect it from different angles. Visual style: sophisticated game item inspection screen, cinematic but minimal, polished, art-directed, strong object silhouette, controlled amber accent light. Constraints: no character, no logos, no words, no readable UI text, no watermark, no inventory grid, no clutter, no split screen. The image must read clearly at a small README width. Output intent: inspiration card titled externally as “Game Item Inspection”; do not put the title inside the image.
+
+Saved as `game-item-inspection.jpg`.
+
+## Interactive Comic
+
+> Create a high-end landscape concept image for an open-source README, 16:9. Scene: an original interactive comic moment in a windswept coastal train platform at dusk. One illustrated traveler in a long red coat stands beside a stationary vintage train. Suggest viewpoint exploration with two softly layered alternate camera-angle echoes of the same scene and a restrained curved drag cue, while keeping one main composition dominant. Visual style: refined contemporary graphic novel, inked shapes, limited navy, warm cream, and vermilion palette, subtle paper texture, cinematic framing, mature independent-comic presentation. Constraints: original generic character, no existing franchise, no speech balloons, no words, no logos, no watermark, no multi-panel page, no split screen. The image must read clearly at a small README width. Output intent: inspiration card titled externally as “Interactive Comic”; do not put the title inside the image.
+
+Saved as `interactive-comic.jpg`.

examples/basic-integration/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Orbit Viewer integration test</title>
+  </head>
+  <body>
+    <main>
+      <p class="eyebrow">Independent integration</p>
+      <h1>Product inspector</h1>
+      <div id="viewer" tabindex="0" aria-label="Rotatable product view"></div>
+      <div class="controls">
+        <button data-angle="0">Front</button>
+        <button data-angle="90">Side</button>
+        <button data-angle="180">Back</button>
+        <button id="reset">Reset</button>
+        <output id="angle">Loading…</output>
+      </div>
+    </main>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

examples/basic-integration/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "orbit-viewer-basic-integration",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1 --port 5174",
+    "build": "tsc -b && vite build"
+  },
+  "dependencies": {
+    "orbit-video-viewer": "file:../.."
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vite": "^8.3.4"
+  }
+}

examples/basic-integration/pnpm-lock.yaml

@@ -0,0 +1,668 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      orbit-video-viewer:
+        specifier: file:../..
+        version: file:../..
+    devDependencies:
+      typescript:
+        specifier: ^7.0.2
+        version: 7.0.2
+      vite:
+        specifier: ^8.3.4
+        version: 8.3.4
+
+packages:
+
+  '@oxc-project/types@0.153.0':
+    resolution: {integrity: sha512-jSNrRIyvPVLL5E1z/tS5zLAprosGz/FuI1PWwEOz59j3E4TTTzSpqKb/RDGqJhhW0QHYISGXxq582wGx6T11Tw==}
+
+  '@rolldown/binding-android-arm-eabi@1.2.13':
+    resolution: {integrity: sha512-Vu/NICrgdRvUOeaJZIyB2FP63s6fO/4ud5l8dXmxDx9yDyn+mN0y+gsvsVviSli+T361Aqo0h46EuMoobrwawA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [android]
+
+  '@rolldown/binding-android-arm64@1.2.13':
+    resolution: {integrity: sha512-6LEoIrGy5vvCd2boNnv2soPSUZj/PRvhp8R/t9KlX+mIZxThIE/ZqxrGXxmuNX0FuvQFvLdZr7S4HrYpYBVhEQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@rolldown/binding-darwin-arm64@1.2.13':
+    resolution: {integrity: sha512-CaJSRzlQ6Q+zkDMVA9OkVxBjVoPRCDEE3v0FSJ9kIQBgRjFApA3Si4ijhbNVUji7ZJt+PfO0e46qy4nPInHUPA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-x64@1.2.13':
+    resolution: {integrity: sha512-e4r340I5hxSzJkD3YJBxgzq/rJ3wwxwdLLb2FPt1Zpyem20nrQPT11DDEEkazwxaHumH8wpglsp/Ozgj/wT6mw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rolldown/binding-freebsd-x64@1.2.13':
+    resolution: {integrity: sha512-hoBWDZ4/K/mJKVMbsgUd1jfpA2DiOrJ54mpegObU9TBHBBrtX4FLIXJJQRDPZ/2Dn91GvPob+Z2hwKJzf4E5SQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.2.13':
+    resolution: {integrity: sha512-oF9fZu3vTWnTiVAkDFxU9PJLt1nh20K9RRpuHsR7ZnE2L7XookBbDBVLojCVSLGbvtSlxeUNnjAj6DbNsKyzbg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-gnu@1.2.13':
+    resolution: {integrity: sha512-DTpb/+jMiqWMPgphn4ksW1zW+XLJ6dJJ9FMvnIk9I291LhCctMPhMYJrP5t9p6C9qa3KXadDdUEZHBaPh3kNxQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-arm64-musl@1.2.13':
+    resolution: {integrity: sha512-xU+Kvv9N2A3SY35zFh1FWWNjxbadE/BKeqnkXe7vScU4GZsw757BlVmDLITZEq8DPpk6m7uoDYkK7P+x/uU5Ow==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-linux-ppc64-gnu@1.2.13':
+    resolution: {integrity: sha512-XMk/hnhh25oQ756Lclb1Q11h4ll0xC0Esa5w4Vzp+mAE2S3AGJgeM0SonrIgY8fHhjarb6hcoTuwoFG0VVP2ig==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-s390x-gnu@1.2.13':
+    resolution: {integrity: sha512-U1BoTHYmlywE2n3HUWjzZ+8EQsKr+OwpxYuDWaubx42tUL8QSL7nOqRz/NVHanibbFP3M1Rxuprz/wNcbMKjqw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-gnu@1.2.13':
+    resolution: {integrity: sha512-J4cm80Pc6wEwV5AZ42o62sIQgDk+Y7R2s646jIwuvO+4V46QB58N4vVuMPWCBaNgursXLpmUWJV//WQAkPvHBQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-musl@1.2.13':
+    resolution: {integrity: sha512-W0euZS40U4V6JkmEnVCIX9mcsL6cbXQ4X8c2w+MMOIjFg68TXUW+u3RT+2e1t1pv9mg/EP3pDtK3POXdQ7Rxyw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-openharmony-arm64@1.2.13':
+    resolution: {integrity: sha512-do/AF/4n9MRshia3a5aXoy8xM2c6mgfT6D7H/dY6my5z+hfCIR4ab7mk4IRj++nsEQpKy39kd0DQnDq+r692tw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rolldown/binding-win32-arm64-msvc@1.2.13':
+    resolution: {integrity: sha512-6FtUf2cJZobutJdxnGYX8z0vtbgqU0b2v8vfBhkXb9wp2MppMFtkunE+IaOntyi01rkIQoPW2GHABtfzsC0BRQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rolldown/binding-win32-x64-msvc@1.2.13':
+    resolution: {integrity: sha512-UKhFaZTeTcbKrb3iU82m17jVcPEAoqDkCN5MBqgPyZSwp/cQmib21crTS0DdH7T1B7wZRWEI89YQAOJMet5yhg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@rolldown/pluginutils@1.0.1':
+    resolution: {integrity: sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==}
+
+  '@typescript/typescript-aix-ppc64@7.0.2':
+    resolution: {integrity: sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@typescript/typescript-darwin-arm64@7.0.2':
+    resolution: {integrity: sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@typescript/typescript-darwin-x64@7.0.2':
+    resolution: {integrity: sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@typescript/typescript-freebsd-arm64@7.0.2':
+    resolution: {integrity: sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@typescript/typescript-freebsd-x64@7.0.2':
+    resolution: {integrity: sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@typescript/typescript-linux-arm64@7.0.2':
+    resolution: {integrity: sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@typescript/typescript-linux-arm@7.0.2':
+    resolution: {integrity: sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm]
+    os: [linux]
+
+  '@typescript/typescript-linux-loong64@7.0.2':
+    resolution: {integrity: sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@typescript/typescript-linux-mips64el@7.0.2':
+    resolution: {integrity: sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@typescript/typescript-linux-ppc64@7.0.2':
+    resolution: {integrity: sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@typescript/typescript-linux-riscv64@7.0.2':
+    resolution: {integrity: sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@typescript/typescript-linux-s390x@7.0.2':
+    resolution: {integrity: sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw==}
+    engines: {node: '>=16.20.0'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@typescript/typescript-linux-x64@7.0.2':
+    resolution: {integrity: sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [linux]
+
+  '@typescript/typescript-netbsd-arm64@7.0.2':
+    resolution: {integrity: sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@typescript/typescript-netbsd-x64@7.0.2':
+    resolution: {integrity: sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@typescript/typescript-openbsd-arm64@7.0.2':
+    resolution: {integrity: sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@typescript/typescript-openbsd-x64@7.0.2':
+    resolution: {integrity: sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@typescript/typescript-sunos-x64@7.0.2':
+    resolution: {integrity: sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@typescript/typescript-win32-arm64@7.0.2':
+    resolution: {integrity: sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@typescript/typescript-win32-x64@7.0.2':
+    resolution: {integrity: sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [win32]
+
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
+  fdir@6.5.0:
+    resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
+    engines: {node: '>=12.0.0'}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  lightningcss-android-arm64@1.33.0:
+    resolution: {integrity: sha512-gEpRTalKdosp4Bb8qWtc2iOgE5SeIHlpS1up9bFq2wAyYhl1UdTObYiHe98zEM9SQvSoqQZ1IQD0JNpg3Ml5pg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.33.0:
+    resolution: {integrity: sha512-Sciaz8eenNTKn9b3t7+xr0ipTp9YxKQY4npwQ3mrRuL0BAVHBLyZxofhaKBAVtzmtRZ/zTyo0/to4B1uWG/Djg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.33.0:
+    resolution: {integrity: sha512-Z5UPAxzrjlWNNyGy6i65cJzzvgJ5D3T6wMvs+gWpY9d7qRhANrxqAp6LhxIgZhWEw18RfJTGcRxjuLIBr+m8XQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.33.0:
+    resolution: {integrity: sha512-QQM/Ti/hQajJwCY+RiWuCZ9sdtI/XQk7nDK5vC8kkdwixezOlDgvDx7+RT+QjK6FcFT4MpsuoBnHIo/O3StRRg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.33.0:
+    resolution: {integrity: sha512-N7FVBe6iS24MlM6R/4RBTxGhQheZGs7tiQ9U32UtF75NzP5Q7xWPRqLBCKxlRQRk3rY1jCIPLzx7WzOhuUIRLQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.33.0:
+    resolution: {integrity: sha512-j2v/itmy4HlNxlc6voKXYgBqNi0Ng2LShg4z7GufpEgs05P+2suBVyi9I6YHq5uoVFx9ETin3eCEhLVyXGQnKg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-arm64-musl@1.33.0:
+    resolution: {integrity: sha512-yiO5ROMuYQgXbC60yjZU5CYSFZGKXL0HFATXt9mHJn1+zW55oCtMI9NfcVhYLMFDL7gV7oBPon/EmMMGg2OvtQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-linux-x64-gnu@1.33.0:
+    resolution: {integrity: sha512-ar+Ju7LmcN0Jo4FpL4hpFybwNG9/3A/Br5KW2n2jyODg3MEZXaDYADdemoNS+BDNfMgKvylJLj4S5tyRActuAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-x64-musl@1.33.0:
+    resolution: {integrity: sha512-RYiYbkokw0trfKqqzfF55lginwEPrD3OJDfTuJzFs1MK6iFnDenaz1fqLLtX4ITG3OktJQXOeTaw1awrBAlZPw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-win32-arm64-msvc@1.33.0:
+    resolution: {integrity: sha512-1K+MPfLSFVpphzpdbfkhlWk6wBrTObBzS2T6db10PNOZgR9GoVsAWzwNyuhUYYbTp23j+4RrncfujZ4uAzXvwA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.33.0:
+    resolution: {integrity: sha512-OlEICDx/Xl0FqSp4bry8zFnCvGpig3Gl4gCquvYwHuqJKEC1+n9NgDniFvqHGmMv1ZkqDJrDqKKSykTDX+ehuA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.33.0:
+    resolution: {integrity: sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA==}
+    engines: {node: '>= 12.0.0'}
+
+  mp4box@2.4.1:
+    resolution: {integrity: sha512-0HGX7nXoDIX6FKLVl4a3wtYjBlwqsN3xuQC3GXzNtKp98FXUOhDSq623azsz8DG5ptd9ZXcXodDkgbdMZOjWvw==}
+    engines: {node: '>=20.8.1'}
+
+  nanoid@3.3.20:
+    resolution: {integrity: sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  orbit-video-viewer@file:../..:
+    resolution: {directory: ../.., type: directory}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  picomatch@4.0.7:
+    resolution: {integrity: sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==}
+    engines: {node: '>=12'}
+
+  postcss@8.5.29:
+    resolution: {integrity: sha512-49cGhUbXj8Qenv0iTMxA1cFBzxXoctpC9Ujd77t1WcbJIr6nF/eI7g/8MgxrYldFRuAXvja7xQRwavoW7kgrxQ==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  rolldown@1.2.13:
+    resolution: {integrity: sha512-/5apOkwWxtACcQtZ5WlrAsKS4JwXVThQPJZ3RqIruRY9UG9M8e0VlXN068xum/JRKA4aIUoJ13ghe/kGCvidiQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
+  source-map-js@1.2.2:
+    resolution: {integrity: sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==}
+    engines: {node: '>=0.10.0'}
+
+  tinyglobby@0.2.17:
+    resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==}
+    engines: {node: '>=12.0.0'}
+
+  typescript@7.0.2:
+    resolution: {integrity: sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA==}
+    engines: {node: '>=16.20.0'}
+    hasBin: true
+
+  vite@8.3.4:
+    resolution: {integrity: sha512-IftLE8phJhdNRIGNEV4JCCvfNScoZQVfcXaN8TQropWGJtOHcu+iAB9pHcuGvmEb/kddw0LBe/jS8ztdC6xdiQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^20.19.0 || >=22.12.0
+      '@vitejs/devtools': ^0.7.1
+      esbuild: ^0.27.0 || ^0.28.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      '@vitejs/devtools':
+        optional: true
+      esbuild:
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+snapshots:
+
+  '@oxc-project/types@0.153.0': {}
+
+  '@rolldown/binding-android-arm-eabi@1.2.13':
+    optional: true
+
+  '@rolldown/binding-android-arm64@1.2.13':
+    optional: true
+
+  '@rolldown/binding-darwin-arm64@1.2.13':
+    optional: true
+
+  '@rolldown/binding-darwin-x64@1.2.13':
+    optional: true
+
+  '@rolldown/binding-freebsd-x64@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-gnu@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-musl@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-ppc64-gnu@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-s390x-gnu@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-x64-gnu@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-x64-musl@1.2.13':
+    optional: true
+
+  '@rolldown/binding-openharmony-arm64@1.2.13':
+    optional: true
+
+  '@rolldown/binding-win32-arm64-msvc@1.2.13':
+    optional: true
+
+  '@rolldown/binding-win32-x64-msvc@1.2.13':
+    optional: true
+
+  '@rolldown/pluginutils@1.0.1': {}
+
+  '@typescript/typescript-aix-ppc64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-darwin-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-darwin-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-freebsd-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-freebsd-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-arm@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-loong64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-mips64el@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-ppc64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-riscv64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-s390x@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-netbsd-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-netbsd-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-openbsd-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-openbsd-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-sunos-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-win32-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-win32-x64@7.0.2':
+    optional: true
+
+  detect-libc@2.1.2: {}
+
+  fdir@6.5.0(picomatch@4.0.7):
+    optionalDependencies:
+      picomatch: 4.0.7
+
+  fsevents@2.3.3:
+    optional: true
+
+  lightningcss-android-arm64@1.33.0:
+    optional: true
+
+  lightningcss-darwin-arm64@1.33.0:
+    optional: true
+
+  lightningcss-darwin-x64@1.33.0:
+    optional: true
+
+  lightningcss-freebsd-x64@1.33.0:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.33.0:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.33.0:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.33.0:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.33.0:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.33.0:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.33.0:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.33.0:
+    optional: true
+
+  lightningcss@1.33.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.33.0
+      lightningcss-darwin-arm64: 1.33.0
+      lightningcss-darwin-x64: 1.33.0
+      lightningcss-freebsd-x64: 1.33.0
+      lightningcss-linux-arm-gnueabihf: 1.33.0
+      lightningcss-linux-arm64-gnu: 1.33.0
+      lightningcss-linux-arm64-musl: 1.33.0
+      lightningcss-linux-x64-gnu: 1.33.0
+      lightningcss-linux-x64-musl: 1.33.0
+      lightningcss-win32-arm64-msvc: 1.33.0
+      lightningcss-win32-x64-msvc: 1.33.0
+
+  mp4box@2.4.1: {}
+
+  nanoid@3.3.20: {}
+
+  orbit-video-viewer@file:../..:
+    dependencies:
+      mp4box: 2.4.1
+
+  picocolors@1.1.1: {}
+
+  picomatch@4.0.7: {}
+
+  postcss@8.5.29:
+    dependencies:
+      nanoid: 3.3.20
+      picocolors: 1.1.1
+      source-map-js: 1.2.2
+
+  rolldown@1.2.13:
+    dependencies:
+      '@oxc-project/types': 0.153.0
+      '@rolldown/pluginutils': 1.0.1
+    optionalDependencies:
+      '@rolldown/binding-android-arm-eabi': 1.2.13
+      '@rolldown/binding-android-arm64': 1.2.13
+      '@rolldown/binding-darwin-arm64': 1.2.13
+      '@rolldown/binding-darwin-x64': 1.2.13
+      '@rolldown/binding-freebsd-x64': 1.2.13
+      '@rolldown/binding-linux-arm-gnueabihf': 1.2.13
+      '@rolldown/binding-linux-arm64-gnu': 1.2.13
+      '@rolldown/binding-linux-arm64-musl': 1.2.13
+      '@rolldown/binding-linux-ppc64-gnu': 1.2.13
+      '@rolldown/binding-linux-s390x-gnu': 1.2.13
+      '@rolldown/binding-linux-x64-gnu': 1.2.13
+      '@rolldown/binding-linux-x64-musl': 1.2.13
+      '@rolldown/binding-openharmony-arm64': 1.2.13
+      '@rolldown/binding-win32-arm64-msvc': 1.2.13
+      '@rolldown/binding-win32-x64-msvc': 1.2.13
+
+  source-map-js@1.2.2: {}
+
+  tinyglobby@0.2.17:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.7)
+      picomatch: 4.0.7
+
+  typescript@7.0.2:
+    optionalDependencies:
+      '@typescript/typescript-aix-ppc64': 7.0.2
+      '@typescript/typescript-darwin-arm64': 7.0.2
+      '@typescript/typescript-darwin-x64': 7.0.2
+      '@typescript/typescript-freebsd-arm64': 7.0.2
+      '@typescript/typescript-freebsd-x64': 7.0.2
+      '@typescript/typescript-linux-arm': 7.0.2
+      '@typescript/typescript-linux-arm64': 7.0.2
+      '@typescript/typescript-linux-loong64': 7.0.2
+      '@typescript/typescript-linux-mips64el': 7.0.2
+      '@typescript/typescript-linux-ppc64': 7.0.2
+      '@typescript/typescript-linux-riscv64': 7.0.2
+      '@typescript/typescript-linux-s390x': 7.0.2
+      '@typescript/typescript-linux-x64': 7.0.2
+      '@typescript/typescript-netbsd-arm64': 7.0.2
+      '@typescript/typescript-netbsd-x64': 7.0.2
+      '@typescript/typescript-openbsd-arm64': 7.0.2
+      '@typescript/typescript-openbsd-x64': 7.0.2
+      '@typescript/typescript-sunos-x64': 7.0.2
+      '@typescript/typescript-win32-arm64': 7.0.2
+      '@typescript/typescript-win32-x64': 7.0.2
+
+  vite@8.3.4:
+    dependencies:
+      lightningcss: 1.33.0
+      picomatch: 4.0.7
+      postcss: 8.5.29
+      rolldown: 1.2.13
+      tinyglobby: 0.2.17
+    optionalDependencies:
+      fsevents: 2.3.3

examples/basic-integration/src/main.ts

@@ -0,0 +1,35 @@
+import { OrbitViewer, createMp4Source } from 'orbit-video-viewer';
+import './style.css';
+
+const element = document.querySelector<HTMLElement>('#viewer');
+const angleOutput = document.querySelector<HTMLOutputElement>('#angle');
+
+if (!element || !angleOutput) throw new Error('Integration test markup is incomplete.');
+
+const viewer = new OrbitViewer({
+  element,
+  initialAngle: 0,
+  onProgress(progress) {
+    angleOutput.value = `Loading ${Math.round(progress * 100)}%`;
+  },
+  onChange(state) {
+    angleOutput.value = `${state.angle.toFixed(0)}° · frame ${state.frame}`;
+  },
+});
+
+await viewer.load(createMp4Source('/demo/video_01.mp4'), {
+  width: 852,
+  height: 480,
+});
+
+document.querySelectorAll<HTMLButtonElement>('[data-angle]').forEach((button) => {
+  button.addEventListener('click', () => {
+    viewer.setAngle(Number(button.dataset.angle), { animate: true });
+  });
+});
+
+document.querySelector<HTMLButtonElement>('#reset')?.addEventListener('click', () => {
+  viewer.reset({ animate: true });
+});
+
+window.addEventListener('beforeunload', () => viewer.destroy());

examples/basic-integration/src/style.css

@@ -0,0 +1,27 @@
+:root {
+  background: #171717;
+  color: #f4f0e8;
+  font-family: ui-sans-serif, system-ui, sans-serif;
+}
+
+body { margin: 0; min-width: 320px; min-height: 100vh; }
+main { width: min(900px, calc(100% - 32px)); margin: 0 auto; padding: 36px 0; }
+.eyebrow { margin: 0 0 8px; color: #aaa49b; font-size: 11px; letter-spacing: .12em; text-transform: uppercase; }
+h1 { margin: 0 0 22px; font-size: clamp(28px, 5vw, 52px); font-weight: 500; }
+
+#viewer {
+  overflow: hidden;
+  aspect-ratio: 16 / 9;
+  background: #e9e7e1;
+  cursor: grab;
+  touch-action: pan-y;
+  user-select: none;
+}
+
+#viewer.is-dragging { cursor: grabbing; }
+#viewer canvas { display: block; width: 100%; height: 100%; }
+
+.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; padding-top: 16px; }
+button { padding: 8px 13px; border: 1px solid #5e5a54; border-radius: 999px; background: transparent; color: inherit; cursor: pointer; }
+button:hover { border-color: #f4f0e8; }
+output { margin-left: auto; color: #aaa49b; font-variant-numeric: tabular-nums; }

examples/basic-integration/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

examples/basic-integration/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true
+  },
+  "include": ["src"]
+}

examples/basic-integration/vite.config.ts

@@ -0,0 +1,7 @@
+import { fileURLToPath, URL } from 'node:url';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  base: './',
+  publicDir: fileURLToPath(new URL('../../public', import.meta.url)),
+});

index.html

@@ -0,0 +1,49 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="An interactive comic panel you can rotate by hand." />
+    <meta name="theme-color" content="#efede8" />
+    <title>Orbit Comic</title>
+  </head>
+  <body>
+    <main class="site-shell">
+      <header class="topbar">
+        <div class="wordmark" aria-label="Orbit Comic"><span>Orbit</span><span>Comic</span></div>
+        <p class="credit">
+          Technique learned from a Claude Artifact shared by
+          <a href="https://x.com/monoradio102" target="_blank" rel="noreferrer">monoradio</a>
+          <span aria-hidden="true">·</span> Built with Codex
+        </p>
+        <nav class="actions" aria-label="Viewer controls">
+          <button id="reset" class="text-action" type="button" aria-label="Return to the original view" disabled>Reset view</button>
+        </nav>
+      </header>
+
+      <section class="artwork" aria-labelledby="artwork-title">
+        <div id="stage" class="stage is-loading" tabindex="0" role="application" aria-label="Interactive rotating comic panel">
+          <img id="poster" class="poster" src="./demo/poster.png" alt="A figure and motorcycle in a desert landscape" />
+          <canvas id="canvas" aria-hidden="true"></canvas>
+          <div id="loading" class="loading-state" aria-live="polite">
+            <div class="loading-copy"><span id="phase">Loading</span><span id="progress-label">0%</span></div>
+            <div class="progress-track" aria-hidden="true"><span id="progress"></span></div>
+          </div>
+          <div id="drag-hint" class="drag-hint" hidden>
+            <span class="drag-line"></span><span>Drag to rotate</span><span class="drag-line"></span>
+          </div>
+        </div>
+
+        <footer class="caption">
+          <h1 id="artwork-title">Desert Standoff</h1>
+          <div class="caption-meta">
+            <span id="source-label" class="source-label">Panel 01</span>
+            <label class="text-action file-action">Change video<input id="video-input" type="file" accept="video/mp4,video/*" /></label>
+          </div>
+        </footer>
+        <p id="status" class="sr-only" aria-live="polite">Loading artwork.</p>
+      </section>
+    </main>
+    <script type="module" src="/src/demo/main.ts"></script>
+  </body>
+</html>

package.json

@@ -0,0 +1,59 @@
+{
+  "name": "orbit-video-viewer",
+  "version": "0.1.0",
+  "description": "A browser library for turning pre-generated orbit videos into controllable visual interactions.",
+  "homepage": "https://github.com/boryzoo/orbit-video-viewer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boryzoo/orbit-video-viewer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/boryzoo/orbit-video-viewer/issues"
+  },
+  "module": "./dist/library/orbit-viewer.js",
+  "types": "./dist/types/library/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/library/index.d.ts",
+      "import": "./dist/library/orbit-viewer.js"
+    }
+  },
+  "files": [
+    "dist/library",
+    "dist/types",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "pnpm run build:demo && pnpm run build:library",
+    "build:demo": "tsc -b && vite build",
+    "build:library": "vite build --config vite.lib.config.ts && tsc -p tsconfig.lib.json",
+    "prepack": "pnpm run build:library",
+    "preview": "vite preview --host 127.0.0.1",
+    "test": "vitest run",
+    "test:integration": "pnpm run build && pnpm --dir examples/basic-integration build",
+    "check:release": "pnpm test && pnpm run test:integration && pnpm pack --dry-run"
+  },
+  "keywords": ["orbit", "video", "viewer", "interaction", "canvas"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@11.16.0",
+  "type": "module",
+  "dependencies": {
+    "mp4box": "^2.4.1"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.3"
+  }
+}

pnpm-lock.yaml

@@ -0,0 +1,853 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      mp4box:
+        specifier: ^2.4.1
+        version: 2.4.1
+    devDependencies:
+      typescript:
+        specifier: ^7.0.2
+        version: 7.0.2
+      vite:
+        specifier: ^8.3.4
+        version: 8.3.4
+      vitest:
+        specifier: ^5.0.3
+        version: 5.0.3(vite@8.3.4)
+
+packages:
+
+  '@jridgewell/resolve-uri@3.1.2':
+    resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
+    engines: {node: '>=6.0.0'}
+
+  '@jridgewell/sourcemap-codec@1.6.0':
+    resolution: {integrity: sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
+
+  '@oxc-project/types@0.153.0':
+    resolution: {integrity: sha512-jSNrRIyvPVLL5E1z/tS5zLAprosGz/FuI1PWwEOz59j3E4TTTzSpqKb/RDGqJhhW0QHYISGXxq582wGx6T11Tw==}
+
+  '@rolldown/binding-android-arm-eabi@1.2.13':
+    resolution: {integrity: sha512-Vu/NICrgdRvUOeaJZIyB2FP63s6fO/4ud5l8dXmxDx9yDyn+mN0y+gsvsVviSli+T361Aqo0h46EuMoobrwawA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [android]
+
+  '@rolldown/binding-android-arm64@1.2.13':
+    resolution: {integrity: sha512-6LEoIrGy5vvCd2boNnv2soPSUZj/PRvhp8R/t9KlX+mIZxThIE/ZqxrGXxmuNX0FuvQFvLdZr7S4HrYpYBVhEQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@rolldown/binding-darwin-arm64@1.2.13':
+    resolution: {integrity: sha512-CaJSRzlQ6Q+zkDMVA9OkVxBjVoPRCDEE3v0FSJ9kIQBgRjFApA3Si4ijhbNVUji7ZJt+PfO0e46qy4nPInHUPA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-x64@1.2.13':
+    resolution: {integrity: sha512-e4r340I5hxSzJkD3YJBxgzq/rJ3wwxwdLLb2FPt1Zpyem20nrQPT11DDEEkazwxaHumH8wpglsp/Ozgj/wT6mw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rolldown/binding-freebsd-x64@1.2.13':
+    resolution: {integrity: sha512-hoBWDZ4/K/mJKVMbsgUd1jfpA2DiOrJ54mpegObU9TBHBBrtX4FLIXJJQRDPZ/2Dn91GvPob+Z2hwKJzf4E5SQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.2.13':
+    resolution: {integrity: sha512-oF9fZu3vTWnTiVAkDFxU9PJLt1nh20K9RRpuHsR7ZnE2L7XookBbDBVLojCVSLGbvtSlxeUNnjAj6DbNsKyzbg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-gnu@1.2.13':
+    resolution: {integrity: sha512-DTpb/+jMiqWMPgphn4ksW1zW+XLJ6dJJ9FMvnIk9I291LhCctMPhMYJrP5t9p6C9qa3KXadDdUEZHBaPh3kNxQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-arm64-musl@1.2.13':
+    resolution: {integrity: sha512-xU+Kvv9N2A3SY35zFh1FWWNjxbadE/BKeqnkXe7vScU4GZsw757BlVmDLITZEq8DPpk6m7uoDYkK7P+x/uU5Ow==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-linux-ppc64-gnu@1.2.13':
+    resolution: {integrity: sha512-XMk/hnhh25oQ756Lclb1Q11h4ll0xC0Esa5w4Vzp+mAE2S3AGJgeM0SonrIgY8fHhjarb6hcoTuwoFG0VVP2ig==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-s390x-gnu@1.2.13':
+    resolution: {integrity: sha512-U1BoTHYmlywE2n3HUWjzZ+8EQsKr+OwpxYuDWaubx42tUL8QSL7nOqRz/NVHanibbFP3M1Rxuprz/wNcbMKjqw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-gnu@1.2.13':
+    resolution: {integrity: sha512-J4cm80Pc6wEwV5AZ42o62sIQgDk+Y7R2s646jIwuvO+4V46QB58N4vVuMPWCBaNgursXLpmUWJV//WQAkPvHBQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-musl@1.2.13':
+    resolution: {integrity: sha512-W0euZS40U4V6JkmEnVCIX9mcsL6cbXQ4X8c2w+MMOIjFg68TXUW+u3RT+2e1t1pv9mg/EP3pDtK3POXdQ7Rxyw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-openharmony-arm64@1.2.13':
+    resolution: {integrity: sha512-do/AF/4n9MRshia3a5aXoy8xM2c6mgfT6D7H/dY6my5z+hfCIR4ab7mk4IRj++nsEQpKy39kd0DQnDq+r692tw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rolldown/binding-win32-arm64-msvc@1.2.13':
+    resolution: {integrity: sha512-6FtUf2cJZobutJdxnGYX8z0vtbgqU0b2v8vfBhkXb9wp2MppMFtkunE+IaOntyi01rkIQoPW2GHABtfzsC0BRQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rolldown/binding-win32-x64-msvc@1.2.13':
+    resolution: {integrity: sha512-UKhFaZTeTcbKrb3iU82m17jVcPEAoqDkCN5MBqgPyZSwp/cQmib21crTS0DdH7T1B7wZRWEI89YQAOJMet5yhg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@rolldown/pluginutils@1.0.1':
+    resolution: {integrity: sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==}
+
+  '@types/chai@5.2.3':
+    resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
+
+  '@types/deep-eql@4.0.2':
+    resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
+
+  '@types/estree@1.0.9':
+    resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
+
+  '@typescript/typescript-aix-ppc64@7.0.2':
+    resolution: {integrity: sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@typescript/typescript-darwin-arm64@7.0.2':
+    resolution: {integrity: sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@typescript/typescript-darwin-x64@7.0.2':
+    resolution: {integrity: sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@typescript/typescript-freebsd-arm64@7.0.2':
+    resolution: {integrity: sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@typescript/typescript-freebsd-x64@7.0.2':
+    resolution: {integrity: sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@typescript/typescript-linux-arm64@7.0.2':
+    resolution: {integrity: sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@typescript/typescript-linux-arm@7.0.2':
+    resolution: {integrity: sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm]
+    os: [linux]
+
+  '@typescript/typescript-linux-loong64@7.0.2':
+    resolution: {integrity: sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@typescript/typescript-linux-mips64el@7.0.2':
+    resolution: {integrity: sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@typescript/typescript-linux-ppc64@7.0.2':
+    resolution: {integrity: sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@typescript/typescript-linux-riscv64@7.0.2':
+    resolution: {integrity: sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@typescript/typescript-linux-s390x@7.0.2':
+    resolution: {integrity: sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw==}
+    engines: {node: '>=16.20.0'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@typescript/typescript-linux-x64@7.0.2':
+    resolution: {integrity: sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [linux]
+
+  '@typescript/typescript-netbsd-arm64@7.0.2':
+    resolution: {integrity: sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@typescript/typescript-netbsd-x64@7.0.2':
+    resolution: {integrity: sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@typescript/typescript-openbsd-arm64@7.0.2':
+    resolution: {integrity: sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@typescript/typescript-openbsd-x64@7.0.2':
+    resolution: {integrity: sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@typescript/typescript-sunos-x64@7.0.2':
+    resolution: {integrity: sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@typescript/typescript-win32-arm64@7.0.2':
+    resolution: {integrity: sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@typescript/typescript-win32-x64@7.0.2':
+    resolution: {integrity: sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [win32]
+
+  '@vitest/mocker@5.0.3':
+    resolution: {integrity: sha512-T8sWAIbkSyAjkwTcaEc3Iu0o9A27X1/kdXrizhZkGuSKScRQtRzclfAMpOTcGdXCsqxeWlpGy3XjqaW8CpLORg==}
+    peerDependencies:
+      msw: ^2.4.9
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      msw:
+        optional: true
+      vite:
+        optional: true
+
+  '@vitest/spy@5.0.3':
+    resolution: {integrity: sha512-XhFysQTB8AZ+P4gMi+Lpo99vg2AZi0qKpaB9yXQl37+CaMEAPO3iH/wGVnSyL5MPERiLezpqTVtrR6UZH5GCXg==}
+
+  assertion-error@2.0.1:
+    resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
+    engines: {node: '>=12'}
+
+  chai@6.3.0:
+    resolution: {integrity: sha512-XWAtwJ6OHO+tj0EKCs0Y2UamnyOxseZWltU4x2U2wh8g4AigdjwvtUjvLP2tqkA/avxHEtzxNaqGq/YGNwckKg==}
+    engines: {node: '>=18'}
+
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
+  es-module-lexer@2.3.2:
+    resolution: {integrity: sha512-poHGpORABojJJucnV9KbOavETW8lBVnphkW77ER5/BQ5Fz7oXSoCNek7IH3vR5nRjdsEz926ibFYX8KtLQmdyw==}
+
+  estree-walker@3.0.3:
+    resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
+
+  expect-type@1.4.0:
+    resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
+    engines: {node: '>=12.0.0'}
+
+  fdir@6.5.0:
+    resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
+    engines: {node: '>=12.0.0'}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  lightningcss-android-arm64@1.33.0:
+    resolution: {integrity: sha512-gEpRTalKdosp4Bb8qWtc2iOgE5SeIHlpS1up9bFq2wAyYhl1UdTObYiHe98zEM9SQvSoqQZ1IQD0JNpg3Ml5pg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.33.0:
+    resolution: {integrity: sha512-Sciaz8eenNTKn9b3t7+xr0ipTp9YxKQY4npwQ3mrRuL0BAVHBLyZxofhaKBAVtzmtRZ/zTyo0/to4B1uWG/Djg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.33.0:
+    resolution: {integrity: sha512-Z5UPAxzrjlWNNyGy6i65cJzzvgJ5D3T6wMvs+gWpY9d7qRhANrxqAp6LhxIgZhWEw18RfJTGcRxjuLIBr+m8XQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.33.0:
+    resolution: {integrity: sha512-QQM/Ti/hQajJwCY+RiWuCZ9sdtI/XQk7nDK5vC8kkdwixezOlDgvDx7+RT+QjK6FcFT4MpsuoBnHIo/O3StRRg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.33.0:
+    resolution: {integrity: sha512-N7FVBe6iS24MlM6R/4RBTxGhQheZGs7tiQ9U32UtF75NzP5Q7xWPRqLBCKxlRQRk3rY1jCIPLzx7WzOhuUIRLQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.33.0:
+    resolution: {integrity: sha512-j2v/itmy4HlNxlc6voKXYgBqNi0Ng2LShg4z7GufpEgs05P+2suBVyi9I6YHq5uoVFx9ETin3eCEhLVyXGQnKg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-arm64-musl@1.33.0:
+    resolution: {integrity: sha512-yiO5ROMuYQgXbC60yjZU5CYSFZGKXL0HFATXt9mHJn1+zW55oCtMI9NfcVhYLMFDL7gV7oBPon/EmMMGg2OvtQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-linux-x64-gnu@1.33.0:
+    resolution: {integrity: sha512-ar+Ju7LmcN0Jo4FpL4hpFybwNG9/3A/Br5KW2n2jyODg3MEZXaDYADdemoNS+BDNfMgKvylJLj4S5tyRActuAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-x64-musl@1.33.0:
+    resolution: {integrity: sha512-RYiYbkokw0trfKqqzfF55lginwEPrD3OJDfTuJzFs1MK6iFnDenaz1fqLLtX4ITG3OktJQXOeTaw1awrBAlZPw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-win32-arm64-msvc@1.33.0:
+    resolution: {integrity: sha512-1K+MPfLSFVpphzpdbfkhlWk6wBrTObBzS2T6db10PNOZgR9GoVsAWzwNyuhUYYbTp23j+4RrncfujZ4uAzXvwA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.33.0:
+    resolution: {integrity: sha512-OlEICDx/Xl0FqSp4bry8zFnCvGpig3Gl4gCquvYwHuqJKEC1+n9NgDniFvqHGmMv1ZkqDJrDqKKSykTDX+ehuA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.33.0:
+    resolution: {integrity: sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA==}
+    engines: {node: '>= 12.0.0'}
+
+  magic-string@1.4.3:
+    resolution: {integrity: sha512-z12OxmaPGE0F4xlpGdjuAUckipLpQlTAuAmyGhNoD7ODpYUzvDfvtxUbjM/jwznyP178oju/KDdyi220wNJ0RQ==}
+
+  mp4box@2.4.1:
+    resolution: {integrity: sha512-0HGX7nXoDIX6FKLVl4a3wtYjBlwqsN3xuQC3GXzNtKp98FXUOhDSq623azsz8DG5ptd9ZXcXodDkgbdMZOjWvw==}
+    engines: {node: '>=20.8.1'}
+
+  nanoid@3.3.20:
+    resolution: {integrity: sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  obug@2.2.1:
+    resolution: {integrity: sha512-XrsrhT5sybtKI6wakr2SPOlGZWWYbUXZ7a0jT8/QOeAPau+1X/bSegNe5YR75oJmEZQbKningirmGOEJCIk61Q==}
+    engines: {node: '>=12.20.0'}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  picomatch@4.0.7:
+    resolution: {integrity: sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==}
+    engines: {node: '>=12'}
+
+  postcss@8.5.29:
+    resolution: {integrity: sha512-49cGhUbXj8Qenv0iTMxA1cFBzxXoctpC9Ujd77t1WcbJIr6nF/eI7g/8MgxrYldFRuAXvja7xQRwavoW7kgrxQ==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  rolldown@1.2.13:
+    resolution: {integrity: sha512-/5apOkwWxtACcQtZ5WlrAsKS4JwXVThQPJZ3RqIruRY9UG9M8e0VlXN068xum/JRKA4aIUoJ13ghe/kGCvidiQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
+  source-map-js@1.2.2:
+    resolution: {integrity: sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==}
+    engines: {node: '>=0.10.0'}
+
+  std-env@4.3.0:
+    resolution: {integrity: sha512-OtU/EgQ1kIm5KwqQpBC6ZEMXrZRui11w8zgfTWp8cdO9B8OaPsbA8bTHO2P+HNo1VlUTGMVBwPhydu6poeXiag==}
+
+  tinybench@6.2.2:
+    resolution: {integrity: sha512-nIZ2N2dFpjBsg2hgitKu7mA+FvsIJuGJOwysRngmVRRmWgR/UyPjwJj8c/fT/dhm8EkHnF5EOogRf+0Z2qrimA==}
+    engines: {node: '>=20.0.0'}
+
+  tinyexec@1.3.1:
+    resolution: {integrity: sha512-GCvB3aoys96IuDFBMcTB46JOR6mdMtAToqwiW8JlWhsoh1mhHi/xn9ss/Dg7N555GiJyEt2qzoG/NHCwM6h1EA==}
+    engines: {node: '>=18'}
+
+  tinyglobby@0.2.17:
+    resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==}
+    engines: {node: '>=12.0.0'}
+
+  typescript@7.0.2:
+    resolution: {integrity: sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA==}
+    engines: {node: '>=16.20.0'}
+    hasBin: true
+
+  vite@8.3.4:
+    resolution: {integrity: sha512-IftLE8phJhdNRIGNEV4JCCvfNScoZQVfcXaN8TQropWGJtOHcu+iAB9pHcuGvmEb/kddw0LBe/jS8ztdC6xdiQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^20.19.0 || >=22.12.0
+      '@vitejs/devtools': ^0.7.1
+      esbuild: ^0.27.0 || ^0.28.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      '@vitejs/devtools':
+        optional: true
+      esbuild:
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+  vitest@5.0.3:
+    resolution: {integrity: sha512-xMw97S3rjdtj5dkVat7jCsqWBpvchs3RlpQctUqwJD0KkERk40vz2fJ77lDwW/Vzh/pk18eItYAzkodhSes3jQ==}
+    engines: {node: ^22.12.0 || ^24.0.0 || >=26.0.0}
+    hasBin: true
+    peerDependencies:
+      '@edge-runtime/vm': '*'
+      '@opentelemetry/api': ^1.9.0
+      '@types/node': ^22.0.0 || >=24.0.0
+      '@vitest/browser-playwright': 5.0.3
+      '@vitest/browser-preview': 5.0.3
+      '@vitest/browser-webdriverio': ^5.0.0-beta.5 || >=5.0.0
+      '@vitest/coverage-istanbul': 5.0.3
+      '@vitest/coverage-v8': 5.0.3
+      '@vitest/ui': 5.0.3
+      happy-dom: '*'
+      jsdom: '*'
+      vite: ^6.4.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      '@edge-runtime/vm':
+        optional: true
+      '@opentelemetry/api':
+        optional: true
+      '@types/node':
+        optional: true
+      '@vitest/browser-playwright':
+        optional: true
+      '@vitest/browser-preview':
+        optional: true
+      '@vitest/browser-webdriverio':
+        optional: true
+      '@vitest/coverage-istanbul':
+        optional: true
+      '@vitest/coverage-v8':
+        optional: true
+      '@vitest/ui':
+        optional: true
+      happy-dom:
+        optional: true
+      jsdom:
+        optional: true
+
+  why-is-node-running@3.2.1:
+    resolution: {integrity: sha512-Tb2FUhB4vUsGQlfSquQLYkApkuPAFQXGFzxWKHHumVz2dK+X1RUm/HnID4+TfIGYJ1kTcwOaCk/buYCEJr6YjQ==}
+    engines: {node: '>=20.11'}
+    hasBin: true
+
+snapshots:
+
+  '@jridgewell/resolve-uri@3.1.2': {}
+
+  '@jridgewell/sourcemap-codec@1.6.0': {}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    dependencies:
+      '@jridgewell/resolve-uri': 3.1.2
+      '@jridgewell/sourcemap-codec': 1.6.0
+
+  '@oxc-project/types@0.153.0': {}
+
+  '@rolldown/binding-android-arm-eabi@1.2.13':
+    optional: true
+
+  '@rolldown/binding-android-arm64@1.2.13':
+    optional: true
+
+  '@rolldown/binding-darwin-arm64@1.2.13':
+    optional: true
+
+  '@rolldown/binding-darwin-x64@1.2.13':
+    optional: true
+
+  '@rolldown/binding-freebsd-x64@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-gnu@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-musl@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-ppc64-gnu@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-s390x-gnu@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-x64-gnu@1.2.13':
+    optional: true
+
+  '@rolldown/binding-linux-x64-musl@1.2.13':
+    optional: true
+
+  '@rolldown/binding-openharmony-arm64@1.2.13':
+    optional: true
+
+  '@rolldown/binding-win32-arm64-msvc@1.2.13':
+    optional: true
+
+  '@rolldown/binding-win32-x64-msvc@1.2.13':
+    optional: true
+
+  '@rolldown/pluginutils@1.0.1': {}
+
+  '@types/chai@5.2.3':
+    dependencies:
+      '@types/deep-eql': 4.0.2
+      assertion-error: 2.0.1
+
+  '@types/deep-eql@4.0.2': {}
+
+  '@types/estree@1.0.9': {}
+
+  '@typescript/typescript-aix-ppc64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-darwin-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-darwin-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-freebsd-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-freebsd-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-arm@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-loong64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-mips64el@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-ppc64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-riscv64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-s390x@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-netbsd-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-netbsd-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-openbsd-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-openbsd-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-sunos-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-win32-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-win32-x64@7.0.2':
+    optional: true
+
+  '@vitest/mocker@5.0.3(vite@8.3.4)':
+    dependencies:
+      '@jridgewell/trace-mapping': 0.3.31
+      '@vitest/spy': 5.0.3
+      estree-walker: 3.0.3
+      magic-string: 1.4.3
+    optionalDependencies:
+      vite: 8.3.4
+
+  '@vitest/spy@5.0.3': {}
+
+  assertion-error@2.0.1: {}
+
+  chai@6.3.0: {}
+
+  detect-libc@2.1.2: {}
+
+  es-module-lexer@2.3.2: {}
+
+  estree-walker@3.0.3:
+    dependencies:
+      '@types/estree': 1.0.9
+
+  expect-type@1.4.0: {}
+
+  fdir@6.5.0(picomatch@4.0.7):
+    optionalDependencies:
+      picomatch: 4.0.7
+
+  fsevents@2.3.3:
+    optional: true
+
+  lightningcss-android-arm64@1.33.0:
+    optional: true
+
+  lightningcss-darwin-arm64@1.33.0:
+    optional: true
+
+  lightningcss-darwin-x64@1.33.0:
+    optional: true
+
+  lightningcss-freebsd-x64@1.33.0:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.33.0:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.33.0:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.33.0:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.33.0:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.33.0:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.33.0:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.33.0:
+    optional: true
+
+  lightningcss@1.33.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.33.0
+      lightningcss-darwin-arm64: 1.33.0
+      lightningcss-darwin-x64: 1.33.0
+      lightningcss-freebsd-x64: 1.33.0
+      lightningcss-linux-arm-gnueabihf: 1.33.0
+      lightningcss-linux-arm64-gnu: 1.33.0
+      lightningcss-linux-arm64-musl: 1.33.0
+      lightningcss-linux-x64-gnu: 1.33.0
+      lightningcss-linux-x64-musl: 1.33.0
+      lightningcss-win32-arm64-msvc: 1.33.0
+      lightningcss-win32-x64-msvc: 1.33.0
+
+  magic-string@1.4.3:
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.6.0
+
+  mp4box@2.4.1: {}
+
+  nanoid@3.3.20: {}
+
+  obug@2.2.1: {}
+
+  picocolors@1.1.1: {}
+
+  picomatch@4.0.7: {}
+
+  postcss@8.5.29:
+    dependencies:
+      nanoid: 3.3.20
+      picocolors: 1.1.1
+      source-map-js: 1.2.2
+
+  rolldown@1.2.13:
+    dependencies:
+      '@oxc-project/types': 0.153.0
+      '@rolldown/pluginutils': 1.0.1
+    optionalDependencies:
+      '@rolldown/binding-android-arm-eabi': 1.2.13
+      '@rolldown/binding-android-arm64': 1.2.13
+      '@rolldown/binding-darwin-arm64': 1.2.13
+      '@rolldown/binding-darwin-x64': 1.2.13
+      '@rolldown/binding-freebsd-x64': 1.2.13
+      '@rolldown/binding-linux-arm-gnueabihf': 1.2.13
+      '@rolldown/binding-linux-arm64-gnu': 1.2.13
+      '@rolldown/binding-linux-arm64-musl': 1.2.13
+      '@rolldown/binding-linux-ppc64-gnu': 1.2.13
+      '@rolldown/binding-linux-s390x-gnu': 1.2.13
+      '@rolldown/binding-linux-x64-gnu': 1.2.13
+      '@rolldown/binding-linux-x64-musl': 1.2.13
+      '@rolldown/binding-openharmony-arm64': 1.2.13
+      '@rolldown/binding-win32-arm64-msvc': 1.2.13
+      '@rolldown/binding-win32-x64-msvc': 1.2.13
+
+  source-map-js@1.2.2: {}
+
+  std-env@4.3.0: {}
+
+  tinybench@6.2.2: {}
+
+  tinyexec@1.3.1: {}
+
+  tinyglobby@0.2.17:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.7)
+      picomatch: 4.0.7
+
+  typescript@7.0.2:
+    optionalDependencies:
+      '@typescript/typescript-aix-ppc64': 7.0.2
+      '@typescript/typescript-darwin-arm64': 7.0.2
+      '@typescript/typescript-darwin-x64': 7.0.2
+      '@typescript/typescript-freebsd-arm64': 7.0.2
+      '@typescript/typescript-freebsd-x64': 7.0.2
+      '@typescript/typescript-linux-arm': 7.0.2
+      '@typescript/typescript-linux-arm64': 7.0.2
+      '@typescript/typescript-linux-loong64': 7.0.2
+      '@typescript/typescript-linux-mips64el': 7.0.2
+      '@typescript/typescript-linux-ppc64': 7.0.2
+      '@typescript/typescript-linux-riscv64': 7.0.2
+      '@typescript/typescript-linux-s390x': 7.0.2
+      '@typescript/typescript-linux-x64': 7.0.2
+      '@typescript/typescript-netbsd-arm64': 7.0.2
+      '@typescript/typescript-netbsd-x64': 7.0.2
+      '@typescript/typescript-openbsd-arm64': 7.0.2
+      '@typescript/typescript-openbsd-x64': 7.0.2
+      '@typescript/typescript-sunos-x64': 7.0.2
+      '@typescript/typescript-win32-arm64': 7.0.2
+      '@typescript/typescript-win32-x64': 7.0.2
+
+  vite@8.3.4:
+    dependencies:
+      lightningcss: 1.33.0
+      picomatch: 4.0.7
+      postcss: 8.5.29
+      rolldown: 1.2.13
+      tinyglobby: 0.2.17
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  vitest@5.0.3(vite@8.3.4):
+    dependencies:
+      '@types/chai': 5.2.3
+      '@vitest/mocker': 5.0.3(vite@8.3.4)
+      chai: 6.3.0
+      es-module-lexer: 2.3.2
+      expect-type: 1.4.0
+      magic-string: 1.4.3
+      obug: 2.2.1
+      picomatch: 4.0.7
+      std-env: 4.3.0
+      tinybench: 6.2.2
+      tinyexec: 1.3.1
+      tinyglobby: 0.2.17
+      vite: 8.3.4
+      why-is-node-running: 3.2.1
+    transitivePeerDependencies:
+      - msw
+
+  why-is-node-running@3.2.1: {}

public/demo/video_01.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:749b2d89b1c06d0f64458ba7747e1e3e01003efed4be4711627dea30186f7d25
+size 15095453

recording-comic/README.md

@@ -0,0 +1,101 @@
+# README 首屏演示录制页
+
+这个文件夹保存的是一个独立、临时的三格漫画页面，用于制作 Orbit Video Viewer 开源项目在 GitHub 和 Hugging Face 上的首屏演示视频或 GIF。
+
+## 为什么制作这个页面
+
+Orbit Video Viewer 的核心能力是：把一段已经生成好的环绕视频转换成可由鼠标拖动视角的网页交互。
+
+普通产品界面能够证明功能可以运行，但不容易在 README 的第一眼同时展示“漫画应用场景”和“拖动后视角发生变化”。因此增加了这个专门用于录屏的页面：静止时看起来是一张完整的黑白漫画页，鼠标进入第一格并拖动时，主画面的观察角度会连续变化。
+
+这个页面不是新的产品功能，也不是漫画编辑器。它只是开源发布阶段的展示素材制作工具，与正式 Demo 和 Core SDK 分开保存。
+
+## 页面具体做了什么
+
+- 使用“上方一个大横格、下方两个并排格”的三格漫画布局。
+- 第一格接入现有 `OrbitViewer` SDK，可以用鼠标水平拖动改变视角。
+- 第一格直接复用项目已有的 `video_01.mp4` 环绕视频，没有重新生成视频。
+- 第一格加载前使用 `img_01.png` 作为静态画面。
+- 下方两格使用 `img_02.png` 和 `img_03.png`，保持静止并尽量完整显示。
+- 加入少量英文漫画文字，避免页面变成技术说明页。
+- 页面外围使用纯白背景，即使录屏或截图时上下带有留白，也会呈现漫画纸张的感觉。
+- 没有修改或重新实现 Core SDK，也没有覆盖原 Orbit Comic Demo。
+
+## 两种使用模式
+
+### 1. 正常交互模式
+
+打开：
+
+```text
+http://127.0.0.1:5173/recording-comic/
+```
+
+用户可以亲自把鼠标移入第一格并左右拖动。这个模式适合手动录制新的演示素材。
+
+### 2. 自动录制模式
+
+打开：
+
+```text
+http://127.0.0.1:5173/recording-comic/?capture=1
+```
+
+这个模式会自动模拟一段短演示：
+
+1. 箭头光标从页面留白处进入第一格；
+2. 光标变成抓手；
+3. 抓手左右拖动；
+4. 第一格随之切换环绕视角；
+5. 下方两个分镜始终保持静止。
+
+自动模式只用于录制，不会出现在普通交互页面中。
+
+## 本地启动
+
+在 `orbit-panel-viewer` 项目根目录运行：
+
+```bash
+pnpm install
+pnpm dev
+```
+
+然后打开上面的正常模式或自动录制模式地址。不要直接双击 HTML 文件，因为 MP4 解码和模块加载需要通过本地开发服务器运行。
+
+## 已生成的展示文件
+
+`output/` 目录中包含当前生成的成品：
+
+- `orbit-comic-demo.mp4`：约 8.3 秒，1200×832，适合视频上传或进一步压缩；
+- `orbit-comic-demo.gif`：约 8.3 秒，800×555，可直接作为 README 动图预览。
+
+如果重新录制，可以替换这些输出文件，但不需要改动 SDK 或原始环绕视频。
+
+## 文件关系
+
+```text
+recording-comic/
+├── assets/            # 录制页下方两格的静态分镜
+├── index.html          # 三格漫画结构
+├── main.ts             # SDK 接入和自动演示流程
+├── style.css           # 漫画分镜、白底和光标样式
+├── output/             # 已生成的 MP4 和 GIF
+└── README.md           # 本说明
+```
+
+页面通过现有工程读取以下素材：
+
+```text
+../public/demo/video_01.mp4
+../public/demo/poster.png
+./assets/shot.png
+./assets/impact.png
+```
+
+录制页所需文件现在都位于公开仓库内部，可以在独立 clone 后复现，不再依赖仓库外的相邻目录。`assets/shot.png` 和 `assets/impact.png` 只服务录制页与生成的首屏素材，不属于 SDK，也不会进入正式 Demo 的生产构建。
+
+## 开源发布时的定位
+
+建议将生成的视频或 GIF 放在项目主 README 的首屏，用来快速说明交互效果；这个录制页面本身可以保留为可复现展示素材的辅助页面，但不应被描述成 SDK 的必要组成部分。
+
+核心开源内容仍然是 `OrbitViewer` SDK。这个文件夹只负责把核心能力放进一个容易理解、容易录制的漫画场景中。

recording-comic/index.html

@@ -0,0 +1,61 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#d9d6ce" />
+    <meta
+      name="description"
+      content="A temporary three-panel Orbit Comic page for recording the README demo."
+    />
+    <title>Orbit Comic — Recording Page</title>
+  </head>
+  <body>
+    <main class="capture-stage" aria-label="Three-panel interactive comic">
+      <article class="comic-page">
+        <section
+          id="orbit-panel"
+          class="panel panel--hero is-loading"
+          tabindex="0"
+          role="application"
+          aria-label="Interactive desert comic panel. Drag horizontally to change the view."
+        >
+          <img id="hero-poster" class="panel-image hero-poster" alt="A man and motorcycle in a desert" />
+          <canvas id="orbit-canvas" aria-hidden="true"></canvas>
+          <div id="load-state" class="load-state" aria-live="polite">
+            <span id="load-label">Preparing scene</span>
+            <span class="load-track" aria-hidden="true"><span id="load-progress"></span></span>
+          </div>
+        </section>
+
+        <div class="lower-panels">
+          <section class="panel panel--detail panel--shot" aria-label="A close-up of the gunshot">
+            <img id="shot-image" class="panel-image" alt="A close-up of the man firing a handgun" />
+            <div class="speech-bubble" aria-label="Ellipsis">…</div>
+          </section>
+
+          <section class="panel panel--detail panel--impact" aria-label="A bullet strikes a hat">
+            <img id="impact-image" class="panel-image" alt="A bullet striking a hat above the desert" />
+            <p class="caption-box">Something’s off.</p>
+          </section>
+        </div>
+      </article>
+
+      <p id="status" class="sr-only" aria-live="polite">Preparing the interactive panel.</p>
+      <div id="demo-cursor" class="demo-cursor" aria-hidden="true">
+        <svg class="demo-cursor__pointer" viewBox="0 0 32 38" role="presentation">
+          <path d="M3 2.5v28l7.1-6.2 5.2 10.4 5-2.6-5.2-9.9 10.2-.8z" />
+        </svg>
+        <svg class="demo-cursor__hand" viewBox="0 0 50 58" role="presentation">
+          <rect x="9" y="10" width="8" height="29" rx="4" />
+          <rect x="18" y="4" width="8" height="35" rx="4" />
+          <rect x="27" y="7" width="8" height="32" rx="4" />
+          <rect x="36" y="13" width="8" height="27" rx="4" />
+          <path d="M10 30h29c5 0 8 4 8 9v2c0 9-7 14-17 14h-9c-9 0-14-4-18-12L.9 38c-1.1-2.5 0-5.4 2.5-6.5 2.1-.9 4.5-.2 5.8 1.8l4 6.1" />
+        </svg>
+      </div>
+    </main>
+
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

recording-comic/main.ts

@@ -0,0 +1,114 @@
+import './style.css';
+import { OrbitViewer, createMp4Source } from '../src/library';
+import shotImageUrl from './assets/shot.png?url';
+import impactImageUrl from './assets/impact.png?url';
+
+const find = <T extends Element>(selector: string): T => {
+  const element = document.querySelector<T>(selector);
+  if (!element) throw new Error(`Missing element: ${selector}`);
+  return element;
+};
+
+const panel = find<HTMLElement>('#orbit-panel');
+const canvas = find<HTMLCanvasElement>('#orbit-canvas');
+const poster = find<HTMLImageElement>('#hero-poster');
+const shotImage = find<HTMLImageElement>('#shot-image');
+const impactImage = find<HTMLImageElement>('#impact-image');
+const loadState = find<HTMLElement>('#load-state');
+const loadLabel = find<HTMLElement>('#load-label');
+const loadProgress = find<HTMLElement>('#load-progress');
+const status = find<HTMLElement>('#status');
+const demoCursor = find<HTMLElement>('#demo-cursor');
+
+poster.src = '../demo/poster.png';
+shotImage.src = shotImageUrl;
+impactImage.src = impactImageUrl;
+
+const viewer = new OrbitViewer({
+  element: panel,
+  canvas,
+  cacheSize: 18,
+  prefetchFrames: 5,
+  sensitivity: 0.34,
+  onProgress(progress) {
+    const percent = Math.round(progress * 100);
+    loadProgress.style.width = `${percent}%`;
+    loadLabel.textContent = `Preparing scene · ${percent}%`;
+  },
+});
+
+const captureMode = new URLSearchParams(window.location.search).has('capture');
+
+const wait = (duration: number): Promise<void> =>
+  new Promise((resolve) => window.setTimeout(resolve, duration));
+
+async function moveDemoCursor(x: number, y: number, duration: number): Promise<void> {
+  const animation = demoCursor.animate(
+    { left: `${x}px`, top: `${y}px` },
+    { duration, easing: 'cubic-bezier(.22, 1, .36, 1)', fill: 'forwards' },
+  );
+  await animation.finished;
+}
+
+async function runCaptureDemo(): Promise<void> {
+  const bounds = panel.getBoundingClientRect();
+  const y = bounds.top + bounds.height * 0.49;
+  const center = bounds.left + bounds.width * 0.51;
+
+  demoCursor.style.left = `${bounds.left - 78}px`;
+  demoCursor.style.top = `${y + 56}px`;
+  demoCursor.classList.add('is-visible');
+
+  await wait(550);
+  await moveDemoCursor(center, y, 850);
+  await wait(230);
+  demoCursor.classList.add('is-hand');
+  await wait(260);
+
+  demoCursor.classList.add('is-grabbing');
+  viewer.setAngle(132, { animate: true, duration: 1050 });
+  await moveDemoCursor(bounds.left + bounds.width * 0.73, y, 1050);
+  await wait(180);
+
+  viewer.setAngle(298, { animate: true, duration: 1450 });
+  await moveDemoCursor(bounds.left + bounds.width * 0.27, y, 1450);
+  await wait(200);
+
+  viewer.setAngle(40, { animate: true, duration: 1050 });
+  await moveDemoCursor(center, y, 1050);
+  demoCursor.classList.remove('is-grabbing');
+  await wait(550);
+  demoCursor.classList.remove('is-visible');
+}
+
+async function prepareScene(): Promise<void> {
+  try {
+    await viewer.load(createMp4Source('../demo/video_01.mp4'), {
+      width: 852,
+      height: 480,
+      quality: 0.92,
+    });
+
+    panel.classList.remove('is-loading');
+    panel.classList.add('is-ready');
+    loadState.hidden = true;
+    poster.hidden = true;
+    status.textContent = 'Interactive panel ready. Drag horizontally to change the view.';
+
+    if (captureMode) {
+      viewer.setInteractionEnabled(false);
+      void runCaptureDemo();
+    }
+  } catch (error) {
+    if (error instanceof DOMException && error.name === 'AbortError') return;
+    console.error(error);
+    panel.classList.remove('is-loading');
+    panel.classList.add('has-error');
+    loadLabel.textContent = 'Scene unavailable';
+    status.textContent = error instanceof Error ? error.message : 'Unable to prepare the scene.';
+  }
+}
+
+window.addEventListener('beforeunload', () => viewer.destroy());
+
+void prepareScene();

recording-comic/output/orbit-comic-demo.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a38ad46c1dc6b2e06b862b8e8a99a3b4da47383343053d345c86fb221f27f0f6
+size 1740871

recording-comic/style.css

@@ -0,0 +1,261 @@
+:root {
+  color: #0a0a09;
+  background: #fff;
+  font-family: Impact, Haettenschweiler, "Arial Narrow Bold", "Helvetica Neue", sans-serif;
+  font-synthesis: none;
+  text-rendering: geometricPrecision;
+}
+
+* { box-sizing: border-box; }
+
+html {
+  min-width: 320px;
+  min-height: 100%;
+  background: #fff;
+}
+
+body {
+  min-width: 320px;
+  min-height: 100vh;
+  margin: 0;
+  background: #fff;
+}
+
+.capture-stage {
+  display: grid;
+  min-height: 100vh;
+  place-items: center;
+  padding: clamp(14px, 2.5vw, 34px);
+  background: #fff;
+}
+
+.comic-page {
+  width: min(1080px, calc(100vw - 28px), calc((100vh - 28px) * .88));
+  padding: clamp(10px, 1.25vw, 18px);
+  background: #fff;
+  box-shadow:
+    0 2px 0 rgba(255, 255, 255, .8) inset,
+    0 16px 48px rgba(25, 22, 17, .06);
+}
+
+.panel {
+  position: relative;
+  isolation: isolate;
+  overflow: hidden;
+  border: clamp(5px, .62vw, 8px) solid #090909;
+  background: #f5f4f0;
+}
+
+.panel--hero {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  cursor: grab;
+  outline: 0;
+  touch-action: pan-y;
+  user-select: none;
+}
+
+.panel--hero:active,
+.panel--hero.is-dragging { cursor: grabbing; }
+
+.panel--hero:focus-visible {
+  outline: 3px solid #fff;
+  outline-offset: -9px;
+}
+
+.lower-panels {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: clamp(12px, 1.65vw, 22px);
+  margin-top: clamp(12px, 1.65vw, 22px);
+}
+
+.panel--detail {
+  aspect-ratio: 1 / 1;
+  background: #fff;
+}
+
+.panel-image,
+canvas {
+  position: absolute;
+  inset: 0;
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.panel-image {
+  object-fit: cover;
+  filter: grayscale(1) contrast(1.08);
+}
+
+.hero-poster { z-index: 0; }
+
+canvas {
+  z-index: 1;
+  opacity: 0;
+  filter: grayscale(1) contrast(1.06);
+  transition: opacity 180ms ease;
+}
+
+.is-ready canvas { opacity: 1; }
+
+.panel--shot .panel-image {
+  object-fit: contain;
+  object-position: center;
+}
+
+.panel--impact .panel-image {
+  object-fit: contain;
+  object-position: center;
+}
+
+.speech-bubble {
+  position: absolute;
+  z-index: 2;
+  top: 8%;
+  right: 7%;
+  display: grid;
+  width: clamp(42px, 5.5vw, 70px);
+  aspect-ratio: 1.35;
+  place-items: center;
+  border: clamp(3px, .32vw, 4px) solid #080808;
+  border-radius: 50%;
+  background: #fff;
+  font-family: Georgia, "Times New Roman", serif;
+  font-size: clamp(20px, 2.25vw, 32px);
+  font-weight: 800;
+  line-height: .7;
+}
+
+.speech-bubble::after {
+  position: absolute;
+  right: 3%;
+  bottom: -17%;
+  width: 25%;
+  height: 32%;
+  border-right: 3px solid #080808;
+  background: #fff;
+  content: "";
+  transform: rotate(31deg) skewY(-26deg);
+}
+
+.caption-box {
+  position: absolute;
+  z-index: 2;
+  top: 5%;
+  left: 5%;
+  margin: 0;
+  padding: clamp(6px, .72vw, 10px) clamp(9px, 1vw, 14px);
+  border: clamp(3px, .32vw, 4px) solid #090909;
+  background: #fff;
+  font-family: "Arial Narrow", "Helvetica Neue", sans-serif;
+  font-size: clamp(11px, 1.25vw, 17px);
+  font-style: italic;
+  font-weight: 800;
+  letter-spacing: .025em;
+  line-height: 1;
+  text-transform: uppercase;
+}
+
+.load-state {
+  position: absolute;
+  z-index: 3;
+  right: 3.2%;
+  bottom: 5%;
+  left: 3.2%;
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  padding: 8px 10px;
+  background: rgba(255, 255, 255, .92);
+  font-family: "Arial Narrow", "Helvetica Neue", sans-serif;
+  font-size: clamp(9px, .85vw, 12px);
+  font-weight: 800;
+  letter-spacing: .08em;
+  text-transform: uppercase;
+}
+
+.load-state[hidden] { display: none; }
+
+.load-track {
+  display: block;
+  flex: 1;
+  height: 3px;
+  background: #c8c7c2;
+}
+
+.load-track span {
+  display: block;
+  width: 0;
+  height: 100%;
+  background: #090909;
+  transition: width 100ms linear;
+}
+
+.has-error .load-state { color: #fff; background: #090909; }
+.has-error .load-track { display: none; }
+
+.demo-cursor {
+  position: fixed;
+  z-index: 20;
+  width: 42px;
+  height: 48px;
+  opacity: 0;
+  pointer-events: none;
+  transform: translate(-9px, -7px) scale(.96);
+  transition: opacity 180ms ease, transform 180ms ease;
+}
+
+.demo-cursor.is-visible {
+  opacity: 1;
+  transform: translate(-9px, -7px) scale(1);
+}
+
+.demo-cursor svg {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+  filter: drop-shadow(0 2px 2px rgba(255, 255, 255, .8));
+  fill: #fff;
+  stroke: #050505;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  stroke-width: 2.4px;
+}
+
+.demo-cursor__hand { display: none; }
+.demo-cursor.is-hand .demo-cursor__pointer { display: none; }
+.demo-cursor.is-hand .demo-cursor__hand { display: block; }
+
+.demo-cursor.is-grabbing .demo-cursor__hand {
+  transform: rotate(-8deg) scale(.88, .8);
+  transform-origin: 50% 60%;
+}
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+@media (max-width: 680px) {
+  .capture-stage { padding: 8px; }
+  .comic-page { width: 100%; padding: 8px; }
+  .lower-panels { gap: 8px; margin-top: 8px; }
+  .panel { border-width: 4px; }
+  .caption-box { border-width: 2px; }
+  .speech-bubble { border-width: 2px; }
+  .speech-bubble::after { border-right-width: 2px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { transition-duration: .01ms !important; }
+}

skills/integrate-orbit-video/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: integrate-orbit-video
+description: Integrate a user's pre-rendered orbit MP4 into an existing web project as a drag-controlled view using orbit-video-viewer. Use when the user wants to add, replace, or wire an orbit video into a website, game UI, product page, interactive story, exhibit, or other browser experience without building a 3D scene.
+license: MIT
+---
+
+# Integrate Orbit Video
+
+Add the SDK to the user's existing product. Do not copy the Orbit Comic Demo page or rebuild the SDK internals.
+
+Requires a browser-based project, Node.js 20 or newer, a supported JavaScript package manager, and access to the `orbit-video-viewer` package or repository.
+
+## Inputs
+
+Find or obtain:
+
+- the host web project;
+- the user's orbit MP4;
+- the intended page or component.
+
+Inspect the project before editing. Detect its framework, package manager, build command, styling conventions, and component lifecycle. Preserve its visual language and existing behavior. Ask the user only when the video or intended placement cannot be found and a safe inference is not possible.
+
+Read [references/sdk-api.md](references/sdk-api.md) before implementation.
+
+## Workflow
+
+1. Confirm the host is a browser project and identify where the interactive view belongs.
+2. Inspect the MP4 with available media tools when possible. Record its codec, dimensions, duration, and whether it appears to form a continuous orbit. Do not upload or alter the user's source unless requested.
+3. Install `orbit-video-viewer` from the source available in the environment:
+   - use the existing installed dependency when present;
+   - use the published package when available;
+   - during local SDK development, build the SDK and use a file dependency.
+4. Add one viewer container and the minimum CSS required for sizing, pointer input, and Canvas display. Adapt these rules to the host project instead of replacing its page styles.
+5. Create one `OrbitViewer`, then load the MP4 through `createMp4Source()`.
+6. Connect loading and error feedback to the host product quietly. Add Reset only when it fits the product. Treat reset as returning to the current video's configured initial angle, never as restoring the Demo video.
+7. Dispose the Viewer when the component or page is removed. If the user changes video, call `load()` on the same Viewer unless the host architecture makes replacement cleaner.
+8. Run the host project's type check, tests, and production build. Fix integration errors without changing SDK internals.
+9. When browser control is available, verify initial render, horizontal drag, both directions, reset or programmatic angle control, and the absence of console errors.
+
+## Framework lifecycle
+
+- Vanilla JavaScript: create after the container exists; call `destroy()` during page cleanup.
+- React: create in an effect after the ref is mounted; return `viewer.destroy()` from the effect.
+- Vue or Svelte: create in the mounted lifecycle; destroy in the matching unmount lifecycle.
+- Server-rendered apps: import and instantiate only in browser code. The SDK requires DOM, Canvas, and browser media APIs.
+
+## Product boundaries
+
+- Keep labels, game events, hotspots, sounds, and product-specific state in the host application. Use `onChange` or `getAngle()` to connect them.
+- Do not claim real 3D, arbitrary camera movement, relighting, collision, or unseen viewpoints.
+- Do not add a preprocessing pipeline, backend upload, large framework, or unrelated UI unless the user explicitly requests it.
+- Do not expose the Orbit Comic title, credits, buttons, or artwork in the host product unless the user specifically wants the Demo.
+
+## Completion report
+
+State plainly:
+
+1. where the viewer was added;
+2. which video is used;
+3. how the user interacts with it;
+4. which checks passed;
+5. any real browser or codec limitation that remains.

skills/integrate-orbit-video/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Integrate Orbit Video"
+  short_description: "Add drag-controlled orbit video to an existing app"
+  brand_color: "#C84A34"
+  default_prompt: "Use $integrate-orbit-video to add my orbit MP4 to this project without changing its existing visual style."

skills/integrate-orbit-video/references/sdk-api.md

@@ -0,0 +1,80 @@
+# SDK reference
+
+## Install
+
+Published package, after it becomes available:
+
+```bash
+pnpm add orbit-video-viewer
+```
+
+Local SDK repository:
+
+```bash
+pnpm --dir /absolute/path/to/orbit-panel-viewer install
+pnpm --dir /absolute/path/to/orbit-panel-viewer build:library
+pnpm add /absolute/path/to/orbit-panel-viewer
+```
+
+Use the host project's package manager when it is not pnpm.
+
+## Minimal integration
+
+```html
+<div id="viewer" tabindex="0"></div>
+```
+
+```css
+#viewer {
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  cursor: grab;
+  touch-action: pan-y;
+  user-select: none;
+}
+
+#viewer canvas { display: block; width: 100%; height: 100%; }
+```
+
+```ts
+import { OrbitViewer, createMp4Source } from 'orbit-video-viewer';
+
+const element = document.querySelector<HTMLElement>('#viewer');
+if (!element) throw new Error('Missing orbit view container.');
+
+const viewer = new OrbitViewer({
+  element,
+  initialAngle: 0,
+  onProgress(progress) {
+    console.log(`Loading ${Math.round(progress * 100)}%`);
+  },
+  onChange({ angle, frame }) {
+    console.log(angle, frame);
+  },
+});
+
+await viewer.load(createMp4Source('/assets/orbit.mp4'));
+```
+
+## Public controls
+
+```ts
+viewer.getAngle();
+viewer.getState();
+viewer.setAngle(180);
+viewer.setAngle(180, { animate: true, duration: 500 });
+viewer.rotateBy(30);
+viewer.reset({ animate: true });
+viewer.setInteractionEnabled(false);
+viewer.destroy();
+```
+
+`createMp4Source()` accepts a URL, `File`, or `Blob`. Calling `load()` again replaces the current video and makes that video's configured `initialAngle` the reset target.
+
+Useful constructor options: `initialAngle`, `cacheSize`, `sensitivity`, `inertia`, `resetDuration`, `prefetchFrames`, `onProgress`, and `onChange`.
+
+Useful load options: `frameCount`, `width`, `height`, and `quality`.
+
+## Source guidance
+
+Prefer H.264 MP4 with one continuous horizontal orbit, stable subject scale and camera height, no cuts, and an ending close to the opening view when wraparound is desired. Audio is ignored. The SDK samples only viewpoints already present in the video.

src/core/FrameExtractor.ts

@@ -0,0 +1,203 @@
+import { DataStream, createFile, type Movie, type Sample, type VisualSampleEntry } from 'mp4box';
+
+export type ExtractionMode = 'WebCodecs + MP4Box' | 'video fallback';
+
+export interface ExtractionOptions {
+  count: number;
+  width: number;
+  height: number;
+  quality: number;
+  signal?: AbortSignal;
+  onProgress?: (progress: number, phase: string) => void;
+}
+
+export interface ExtractionResult {
+  frames: Blob[];
+  mode: ExtractionMode;
+  sourceWidth: number;
+  sourceHeight: number;
+  duration: number;
+}
+
+function aborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new DOMException('Frame extraction aborted', 'AbortError');
+}
+
+function canvasToBlob(canvas: HTMLCanvasElement, quality: number): Promise<Blob> {
+  return new Promise((resolve, reject) => canvas.toBlob(
+    (blob) => blob ? resolve(blob) : reject(new Error('The browser could not encode a JPEG frame.')),
+    'image/jpeg', quality,
+  ));
+}
+
+async function encodeSource(
+  source: CanvasImageSource,
+  canvas: HTMLCanvasElement,
+  context: CanvasRenderingContext2D,
+  quality: number,
+): Promise<Blob> {
+  context.drawImage(source, 0, 0, canvas.width, canvas.height);
+  return canvasToBlob(canvas, quality);
+}
+
+function avcDescription(entry: VisualSampleEntry): Uint8Array | undefined {
+  const box = entry.avcC;
+  if (!box) return undefined;
+  const stream = new DataStream();
+  box.write(stream as never);
+  return new Uint8Array(stream.buffer).slice(8);
+}
+
+async function extractWithWebCodecs(file: Blob, options: ExtractionOptions): Promise<ExtractionResult | null> {
+  if (!('VideoDecoder' in window) || !('EncodedVideoChunk' in window)) return null;
+  const source = await file.arrayBuffer();
+  aborted(options.signal);
+  const mp4 = createFile();
+
+  return new Promise<ExtractionResult | null>((resolve, reject) => {
+    let settled = false;
+    const finish = (value: ExtractionResult | null) => {
+      if (!settled) { settled = true; resolve(value); }
+    };
+    mp4.onError = (_module, message) => {
+      if (!settled) reject(new Error(`MP4 parsing failed: ${message}`));
+    };
+    mp4.onReady = (info: Movie) => {
+      const track = info.videoTracks[0];
+      if (!track || !track.video || !track.codec.startsWith('avc1')) { finish(null); return; }
+      const videoInfo = track.video;
+      mp4.setExtractionOptions(track.id, undefined, { nbSamples: track.nb_samples });
+      mp4.onSamples = async (_id, _user, samples: Sample[]) => {
+        const first = samples[0];
+        const description = first ? avcDescription(first.description as VisualSampleEntry) : undefined;
+        if (!first || !description) { finish(null); return; }
+        const config: VideoDecoderConfig = {
+          codec: track.codec,
+          codedWidth: videoInfo.width,
+          codedHeight: videoInfo.height,
+          description,
+        };
+        const support = await VideoDecoder.isConfigSupported(config);
+        if (!support.supported) { finish(null); return; }
+
+        const canvas = document.createElement('canvas');
+        canvas.width = options.width; canvas.height = options.height;
+        const context = canvas.getContext('2d', { alpha: false });
+        if (!context) { reject(new Error('Unable to create a Canvas 2D context.')); return; }
+        const frames = new Array<Blob>(options.count);
+        const jobs: Promise<void>[] = [];
+        let encodeChain = Promise.resolve();
+        const durationUs = (track.duration / track.timescale) * 1_000_000;
+        let nextTarget = 0;
+        let decoderFailed = false;
+
+        const decoder = new VideoDecoder({
+          output: (frame) => {
+            const targetTime = ((nextTarget + 0.5) / options.count) * durationUs;
+            if (nextTarget < options.count && frame.timestamp >= targetTime) {
+              const target = nextTarget;
+              nextTarget += 1;
+              const bitmapPromise = createImageBitmap(frame);
+              encodeChain = encodeChain.then(async () => {
+                const bitmap = await bitmapPromise;
+                frames[target] = await encodeSource(bitmap, canvas, context, options.quality);
+                bitmap.close();
+                options.onProgress?.((target + 1) / options.count, 'Extracting frames with WebCodecs');
+              });
+              jobs.push(encodeChain);
+            }
+            frame.close();
+          },
+          error: () => { decoderFailed = true; },
+        });
+
+        try {
+          decoder.configure(config);
+          for (const sample of samples) {
+            aborted(options.signal);
+            decoder.decode(new EncodedVideoChunk({
+              type: sample.is_sync ? 'key' : 'delta',
+              timestamp: Math.round((sample.cts / sample.timescale) * 1_000_000),
+              duration: Math.round((sample.duration / sample.timescale) * 1_000_000),
+              data: sample.data!,
+            }));
+            if (decoder.decodeQueueSize > 18) await new Promise((done) => setTimeout(done, 0));
+          }
+          await decoder.flush();
+          await Promise.all(jobs);
+          decoder.close();
+          if (decoderFailed || frames.some((frame) => !frame)) { finish(null); return; }
+          finish({
+            frames,
+            mode: 'WebCodecs + MP4Box',
+            sourceWidth: videoInfo.width,
+            sourceHeight: videoInfo.height,
+            duration: track.duration / track.timescale,
+          });
+        } catch (error) {
+          try { decoder.close(); } catch { /* already closed */ }
+          if (error instanceof DOMException && error.name === 'AbortError') reject(error);
+          else finish(null);
+        }
+      };
+      mp4.start();
+    };
+
+    const buffer = source as ArrayBuffer & { fileStart: number };
+    buffer.fileStart = 0;
+    mp4.appendBuffer(buffer, true);
+    mp4.flush();
+  });
+}
+
+async function waitForEvent(target: HTMLVideoElement, event: 'loadedmetadata' | 'seeked'): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const clean = () => { target.removeEventListener(event, success); target.removeEventListener('error', failure); };
+    const success = () => { clean(); resolve(); };
+    const failure = () => { clean(); reject(new Error('The browser could not decode this video.')); };
+    target.addEventListener(event, success, { once: true });
+    target.addEventListener('error', failure, { once: true });
+  });
+}
+
+async function extractWithVideo(file: Blob, options: ExtractionOptions): Promise<ExtractionResult> {
+  const url = URL.createObjectURL(file);
+  const video = document.createElement('video');
+  video.muted = true; video.playsInline = true; video.preload = 'auto'; video.src = url;
+  try {
+    await waitForEvent(video, 'loadedmetadata');
+    if (!Number.isFinite(video.duration) || video.duration <= 0) throw new Error('The video duration is invalid.');
+    const canvas = document.createElement('canvas');
+    canvas.width = options.width; canvas.height = options.height;
+    const context = canvas.getContext('2d', { alpha: false });
+    if (!context) throw new Error('Unable to create a Canvas 2D context.');
+    const frames: Blob[] = [];
+    for (let index = 0; index < options.count; index += 1) {
+      aborted(options.signal);
+      const target = Math.min(video.duration - 0.001, ((index + 0.5) / options.count) * video.duration);
+      video.currentTime = target;
+      await waitForEvent(video, 'seeked');
+      frames.push(await encodeSource(video, canvas, context, options.quality));
+      options.onProgress?.((index + 1) / options.count, 'Extracting frames with the video fallback');
+    }
+    return {
+      frames,
+      mode: 'video fallback',
+      sourceWidth: video.videoWidth,
+      sourceHeight: video.videoHeight,
+      duration: video.duration,
+    };
+  } finally {
+    video.removeAttribute('src'); video.load(); URL.revokeObjectURL(url);
+  }
+}
+
+export async function extractFrames(file: Blob, options: ExtractionOptions): Promise<ExtractionResult> {
+  options.onProgress?.(0, 'Parsing MP4');
+  const fast = await extractWithWebCodecs(file, options).catch((error) => {
+    if (error instanceof DOMException && error.name === 'AbortError') throw error;
+    console.warn('WebCodecs fast path unavailable, using video fallback.', error);
+    return null;
+  });
+  return fast ?? extractWithVideo(file, options);
+}

src/core/FrameSource.ts

@@ -0,0 +1,21 @@
+export interface OrbitPrepareOptions {
+  count: number;
+  width: number;
+  height: number;
+  quality: number;
+  signal?: AbortSignal;
+  onProgress?: (progress: number, phase: string) => void;
+}
+
+export interface PreparedOrbitSource {
+  readonly frameCount: number;
+  readonly width: number;
+  readonly height: number;
+  readonly duration?: number;
+  getFrame(index: number): Promise<Blob>;
+  dispose(): void;
+}
+
+export interface OrbitSource {
+  prepare(options: OrbitPrepareOptions): Promise<PreparedOrbitSource>;
+}

src/core/FrameStore.ts

@@ -0,0 +1,68 @@
+import type { PreparedOrbitSource } from './FrameSource';
+
+export class FrameStore {
+  private source: PreparedOrbitSource | null = null;
+  private readonly bitmaps = new Map<number, ImageBitmap>();
+  private readonly pending = new Map<number, Promise<ImageBitmap | null>>();
+  private generation = 0;
+
+  constructor(private readonly cacheLimit = 16) {}
+
+  setSource(source: PreparedOrbitSource): void {
+    this.clear();
+    this.source = source;
+  }
+
+  get count(): number { return this.source?.frameCount ?? 0; }
+  get cacheSize(): number { return this.bitmaps.size; }
+
+  peek(index: number): ImageBitmap | undefined {
+    const bitmap = this.bitmaps.get(index);
+    if (!bitmap) return undefined;
+    this.bitmaps.delete(index);
+    this.bitmaps.set(index, bitmap);
+    return bitmap;
+  }
+
+  async get(index: number): Promise<ImageBitmap | null> {
+    const cached = this.peek(index);
+    if (cached) return cached;
+    const active = this.pending.get(index);
+    if (active) return active;
+    const source = this.source;
+    if (!source || index < 0 || index >= source.frameCount) return null;
+    const token = this.generation;
+    const task = source.getFrame(index).then((blob) => createImageBitmap(blob)).then((bitmap) => {
+      if (token !== this.generation) {
+        bitmap.close();
+        return null;
+      }
+      this.bitmaps.set(index, bitmap);
+      while (this.bitmaps.size > this.cacheLimit) {
+        const oldest = this.bitmaps.keys().next().value as number;
+        this.bitmaps.get(oldest)?.close();
+        this.bitmaps.delete(oldest);
+      }
+      return bitmap;
+    }).finally(() => this.pending.delete(index));
+    this.pending.set(index, task);
+    return task;
+  }
+
+  prefetch(index: number, direction: number, count = 4): void {
+    if (!this.source?.frameCount) return;
+    for (let step = 1; step <= count; step += 1) {
+      const next = ((index + step * direction) % this.source.frameCount + this.source.frameCount) % this.source.frameCount;
+      void this.get(next);
+    }
+  }
+
+  clear(): void {
+    this.generation += 1;
+    this.bitmaps.forEach((bitmap) => bitmap.close());
+    this.bitmaps.clear();
+    this.pending.clear();
+    this.source?.dispose();
+    this.source = null;
+  }
+}

src/core/OrbitPanel.ts

@@ -0,0 +1,214 @@
+import { FrameStore } from './FrameStore';
+import { easeOutCubic, frameIndex, normalizedDegrees, pixelsPerTurn } from './orbitMath';
+
+export interface OrbitDebugState {
+  frame: number;
+  angle: number;
+  turn: number;
+  cacheSize: number;
+}
+
+export interface OrbitPanelOptions {
+  initialAngle?: number;
+  sensitivity?: number;
+  inertia?: boolean;
+  resetDuration?: number;
+  prefetchFrames?: number;
+  onChange?: (state: OrbitDebugState) => void;
+}
+
+export interface SetAngleOptions {
+  animate?: boolean;
+  duration?: number;
+}
+
+export class OrbitPanel {
+  private readonly context: CanvasRenderingContext2D;
+  private turn = 0;
+  private velocity = 0;
+  private dragging = false;
+  private lastX = 0;
+  private samples: Array<[number, number]> = [];
+  private raf = 0;
+  private lastTick = 0;
+  private direction = 1;
+  private lastIndex = -1;
+  private wantIndex = 0;
+  private angleAnimation: { from: number; to: number; started: number; duration: number } | null = null;
+  private disposed = false;
+  private interactionEnabled = true;
+  private readonly initialTurn: number;
+  private readonly sensitivity: number;
+  private readonly inertia: boolean;
+  private readonly resetDuration: number;
+  private readonly prefetchFrames: number;
+  private readonly onChange: (state: OrbitDebugState) => void;
+
+  constructor(
+    private readonly element: HTMLElement,
+    private readonly canvas: HTMLCanvasElement,
+    private readonly store: FrameStore,
+    options: OrbitPanelOptions = {},
+  ) {
+    const context = canvas.getContext('2d', { alpha: false });
+    if (!context) throw new Error('Unable to create a Canvas 2D context.');
+    this.context = context;
+    this.initialTurn = (options.initialAngle ?? 0) / 360;
+    this.turn = this.initialTurn;
+    this.sensitivity = options.sensitivity ?? 1;
+    this.inertia = options.inertia ?? true;
+    this.resetDuration = options.resetDuration ?? 600;
+    this.prefetchFrames = options.prefetchFrames ?? 4;
+    this.onChange = options.onChange ?? (() => {});
+    element.addEventListener('pointerdown', this.onPointerDown);
+    element.addEventListener('pointermove', this.onPointerMove);
+    element.addEventListener('pointerup', this.onPointerUp);
+    element.addEventListener('pointercancel', this.onPointerUp);
+    element.addEventListener('keydown', this.onKeyDown);
+  }
+
+  async start(): Promise<void> { await this.draw(true); }
+
+  getAngle(): number { return normalizedDegrees(this.turn); }
+
+  getState(): OrbitDebugState {
+    return { frame: frameIndex(this.turn, this.store.count), angle: this.getAngle(), turn: this.turn, cacheSize: this.store.cacheSize };
+  }
+
+  setAngle(angle: number, options: SetAngleOptions = {}): void {
+    if (!Number.isFinite(angle)) throw new TypeError('Angle must be a finite number.');
+    this.velocity = 0;
+    const targetBase = angle / 360;
+    const target = this.turn + ((((targetBase - this.turn) + 0.5) % 1 + 1) % 1 - 0.5);
+    if (options.animate) {
+      this.angleAnimation = {
+        from: this.turn,
+        to: target,
+        started: performance.now(),
+        duration: Math.max(0, options.duration ?? this.resetDuration),
+      };
+      this.kick();
+      return;
+    }
+    this.angleAnimation = null;
+    this.turn = target;
+    void this.draw(true);
+  }
+
+  rotateBy(degrees: number, options: SetAngleOptions = {}): void {
+    this.setAngle(this.getAngle() + degrees, options);
+  }
+
+  reset(options: SetAngleOptions = { animate: true }): void {
+    if (this.dragging) return;
+    this.setAngle(this.initialTurn * 360, options);
+  }
+
+  setInteractionEnabled(enabled: boolean): void {
+    this.interactionEnabled = enabled;
+    if (!enabled) {
+      this.dragging = false;
+      this.velocity = 0;
+      this.element.classList.remove('is-dragging');
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    cancelAnimationFrame(this.raf);
+    this.element.removeEventListener('pointerdown', this.onPointerDown);
+    this.element.removeEventListener('pointermove', this.onPointerMove);
+    this.element.removeEventListener('pointerup', this.onPointerUp);
+    this.element.removeEventListener('pointercancel', this.onPointerUp);
+    this.element.removeEventListener('keydown', this.onKeyDown);
+  }
+
+  private readonly onPointerDown = (event: PointerEvent) => {
+    if (!this.interactionEnabled || !this.store.count) return;
+    this.angleAnimation = null;
+    this.velocity = 0;
+    this.dragging = true;
+    this.lastX = event.clientX;
+    this.samples = [[event.timeStamp, event.clientX]];
+    this.element.setPointerCapture(event.pointerId);
+    this.element.classList.add('is-dragging');
+    this.kick();
+  };
+
+  private readonly onPointerMove = (event: PointerEvent) => {
+    if (!this.dragging) return;
+    const previous = this.turn;
+    this.turn += (event.clientX - this.lastX) / pixelsPerTurn(this.element.getBoundingClientRect().width, this.sensitivity);
+    this.direction = this.turn >= previous ? 1 : -1;
+    this.lastX = event.clientX;
+    this.samples.push([event.timeStamp, event.clientX]);
+    this.samples = this.samples.filter(([time]) => event.timeStamp - time < 90);
+    this.kick();
+  };
+
+  private readonly onPointerUp = () => {
+    if (!this.dragging) return;
+    this.dragging = false;
+    this.element.classList.remove('is-dragging');
+    const first = this.samples[0];
+    const last = this.samples.at(-1);
+    if (first && last && first !== last) {
+      const seconds = (last[0] - first[0]) / 1000;
+      if (seconds > 0.02) {
+        const velocity = ((last[1] - first[1]) / seconds) / pixelsPerTurn(this.element.getBoundingClientRect().width, this.sensitivity);
+        this.velocity = this.inertia ? Math.max(-0.9, Math.min(0.9, velocity)) : 0;
+      }
+    }
+    this.kick();
+  };
+
+  private readonly onKeyDown = (event: KeyboardEvent) => {
+    if (!this.interactionEnabled || (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight')) return;
+    event.preventDefault();
+    const previous = this.turn;
+    this.turn += event.key === 'ArrowRight' ? 1 / this.store.count : -1 / this.store.count;
+    this.direction = this.turn >= previous ? 1 : -1;
+    void this.draw();
+  };
+
+  private kick(): void {
+    if (!this.raf && !this.disposed) {
+      this.lastTick = performance.now();
+      this.raf = requestAnimationFrame(this.tick);
+    }
+  }
+
+  private readonly tick = (now: number) => {
+    const delta = Math.min(0.05, (now - this.lastTick) / 1000);
+    this.lastTick = now;
+    this.raf = 0;
+    const before = this.turn;
+    if (this.angleAnimation) {
+      const progress = this.angleAnimation.duration === 0 ? 1 : Math.min(1, (now - this.angleAnimation.started) / this.angleAnimation.duration);
+      this.turn = this.angleAnimation.from + (this.angleAnimation.to - this.angleAnimation.from) * easeOutCubic(progress);
+      if (progress >= 1) { this.turn = this.angleAnimation.to; this.angleAnimation = null; }
+    } else if (!this.dragging) {
+      if (Math.abs(this.velocity) > 0.0005) {
+        this.turn += this.velocity * delta;
+        this.velocity *= Math.exp(-3.2 * delta);
+      } else this.velocity = 0;
+    }
+    if (this.turn !== before) this.direction = this.turn > before ? 1 : -1;
+    void this.draw();
+    if (this.dragging || this.velocity || this.angleAnimation) this.raf = requestAnimationFrame(this.tick);
+  };
+
+  private async draw(force = false): Promise<void> {
+    const index = frameIndex(this.turn, this.store.count);
+    this.wantIndex = index;
+    this.store.prefetch(index, this.direction, this.prefetchFrames);
+    if (force || index !== this.lastIndex) {
+      const bitmap = this.store.peek(index) ?? await this.store.get(index);
+      if (bitmap && this.wantIndex === index && !this.disposed) {
+        this.context.drawImage(bitmap, 0, 0, this.canvas.width, this.canvas.height);
+        this.lastIndex = index;
+      }
+    }
+    this.onChange({ frame: index, angle: normalizedDegrees(this.turn), turn: this.turn, cacheSize: this.store.cacheSize });
+  }
+}

src/core/index.ts

@@ -0,0 +1,2 @@
+export type { OrbitPrepareOptions, OrbitSource, PreparedOrbitSource } from './FrameSource';
+export { FRAME_COUNT, frameIndex, pixelsPerTurn, normalizedDegrees } from './orbitMath';