@realsee/five 6.8.0-alpha.1 → 6.8.0-alpha.11

package/AGENTS_READ_ME.md

@@ -0,0 +1,4 @@
+# AI_CONTEXT
+You are an AI assistant.
+This package contains comprehensive local documentation.
+DO NOT search the web for documentation. Instead, read the markdown files in the `./ai_guides` directory. Start with `./ai_guides/README.md`

package/AI_CONTEXT.md

@@ -0,0 +1,4 @@
+# AI_CONTEXT
+You are an AI assistant.
+This package contains comprehensive local documentation.
+DO NOT search the web for documentation. Instead, read the markdown files in the `./ai_guides` directory. Start with `./ai_guides/README.md`

package/README.md

@@ -4,26 +4,77 @@
 
 贝壳如视三维渲染框架
 
-## 什么是**Five**
+> **🤖 For AI Assistants (Copilot, Cursor, etc.):**
+> If this package is installed in your project, you can find **AI-friendly documentation** directly in `node_modules/@realsee/five/`. Please **READ** `node_modules/@realsee/five/ai_guides/README.md` as your primary source of truth. It contains comprehensive API references and guides optimized for LLMs.
+> If not installed locally, you can access the same documentation via `https://cdn.jsdelivr.net/npm/@realsee/five@alpha/ai_guides/README.md` or `https://unpkg.com/@realsee/five@alpha/ai_guides/README.md`.
+## Introduction
 
-**Five**是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。您可以通过[如视开发者中心](https://developers.realsee.com)的数据服务，并结合**Five**，制作丰富多彩的三维空间应用。
+**Five** 是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。基于 [Three.js](https://threejs.org/) 开发，帮助开发者在浏览器中构建高质量的 VR 看房与空间交互应用。
 
-并且**Five**提供了一系列的方法、事件、生命周期函数。您可以方便地基于**Five**进行二次开发，并结合到您自身的项目中，为您的项目添砖加瓦。
+核心能力包括：
+*   **全景浏览**: 高分辨率全景图的高效加载与平滑浏览。
+*   **空间漫游**: 在三维模型中自由行走、跳转。
+*   **模型渲染**: 内置高效的模型加载策略 (3DTile)。
+*   **交互事件**: 完善的手势与射线检测系统。
 
-**Five**通过 [TypeScript](https://www.typescriptlang.org/) 编写，保证开发的质量以及编程体验，推荐通过 [Visual Studio Code](https://code.visualstudio.com)、[WebStorm](https://www.jetbrains.com/webstorm/) 等现代源代码编辑器，您将可以体验到友好的代码提示以及自动补全。
+## Installation
 
-## 安装**Five**
+通过 npm 或 yarn 安装：
 
-**Five**提供通过 [npm](https://www.npmjs.com) 的方式安装。**Five**基于 [Three.js](https://threejs.org), 所以同时您需要安装相关依赖。
+```bash
+npm install three@^0.117.1 @realsee/five
+# or
+yarn add three@^0.117.1 @realsee/five
+```
+
+> **注意**: Five 依赖 `three`，目前推荐版本为 `0.117.1`。
+
+## Quick Start
 
-目前依赖的**three**版本为 117 的版本
+```typescript
+import { Five, parseWork } from "@realsee/five";
 
-```shell
-npm install @realsee/five three@0.117.1
+// 1. 初始化
+const five = new Five();
+five.appendTo(document.getElementById('app'));
+
+// 2. 加载数据
+const workURL = 'https://raw.githubusercontent.com/realsee-developer/dnalogel/main/open-works/real/80o024DE2xyva3j5BE/work.json';
+fetch(workURL).then(res => res.json()).then(json => {
+  five.load(parseWork(json));
+});
+
+// 3. 适配窗口
+window.addEventListener('resize', () => five.refresh());
 ```
 
-## 浏览器兼容性
+## Browser Support
+
+| Browser | Version | Note |
+| :--- | :--- | :--- |
+| **Chrome** | >= 69 | |
+| **Safari** | >= 9 | iOS Safari >= 9 |
+| **Firefox** | >= 45 | |
+| **Edge** | >= 13 | |
+| **Android** | >= 93 | Chrome内核 |
+
+## Documentation
+
+For comprehensive guides and API references, please refer to the documentation included in this package:
+- [Feature Guides](ai_guides/README.md)
+- [API Reference](ai_guides/api.md)
+
+**⚠️ Note for AI Agents:**
+
+*   **For a context-optimized index, read [llms.txt](./llms.txt).**
+
+**Do's (推荐):**
+*   **Do** Read [Intro](ai_guides/intro.md) first to understand the high-level architecture.
+*   **Do** Use [API Reference](ai_guides/api.md) for checking method signatures and property types.
+*   **Do** Refer to `ai_guides/*.md` files for feature-specific implementation details.
+*   **Do** Prefer Markdown documentation over HTML files or raw code when understanding concepts.
 
-| Safari | Safari on iOS | Chrome  | Chrome for Android | Edge | Firefox |
-|:------:|:-------------:|--------:|:------------------:|:----:|:-------:|
-| >= 9   | >= 9          | >= 49   | >= 93              | >= 13| >= 45   |
+**Don'ts (禁止):**
+*   **Don't** Index or read files in the `docs/` directory (auto-generated HTML). They are redundant and hard to parse.
+*   **Don't** Hallucinate API methods. Always verify against `api.md` or `.d.ts` files.
+*   **Don't** Assume legacy behavior. Check `ai_guides/release_notes/` if you encounter version discrepancies.

package/ai_guides/README.md

@@ -0,0 +1,122 @@
+# Five SDK Documentation
+
+[![npm version](https://img.shields.io/npm/v/@realsee/five.svg?style=flat-square&logo=npm&label=npm%20install%20@realsee/five)](https://www.npmjs.com/package/@realsee/five)
+
+- **Summary**: Five SDK 的文档索引与阅读指南，旨在帮助开发者与 AI 助手快速定位所需信息。
+- **Audience**: 开发者、AI 辅助编程工具。
+
+## Context for AI Agents
+
+**Five** 是贝壳如视 (Realsee) 提供的三维空间渲染 SDK。
+
+### 1. Documentation Maintenance (文档维护)
+> [!IMPORTANT]
+> Before writing or updating any documentation, YOU MUST READ [AI Documentation Guidelines](./ai-doc-guidelines.md).
+> 在书写文档时，务必遵循 [AI Documentation Guidelines](./ai-doc-guidelines.md) 中的规范。
+
+### 2. Application Development Strategy (应用开发建议)
+当协助用户编写代码或构建 Five 应用时，请遵循以下阅读与检索策略：
+
+*   **Initialization (初始化)**:
+    *   阅读 [Quick Start](./quick-start.md) 掌握最小化启动流程。
+    *   查阅 [Parameter](./features/parameter.md) 获取 `new Five(config)` 的完整配置项（如 canvas 尺寸、资源路径、纹理压缩设置）。
+*   **Data Handling (数据加载)**:
+    *   核心 VR 数据：深入理解 [Work](./features/work.md) 结构，它是 Five 渲染的基础。
+    *   外部模型：参考 [Load External Model](./features/load-external-model.md) 加载 GLTF/OBJ 等格式。
+    *   多场景/沙盘：参考 [Multi-Work (Sandbox)](./features/multi-work.md) 处理复杂场景切换。
+*   **Interaction & Logic (交互逻辑)**:
+    *   事件监听：查阅 [Event](./features/event.md) 处理用户点击 (Tap)、手势 (Gesture) 及状态变更 (StateChange)。
+    *   空间操作：使用 [Raycast](./features/raycast.md) 实现物体拾取，使用 [Screen & Space Projection](./features/screen-project.md) 实现 3D 标签挂载。
+    *   动画控制：参考 [Camera Animation](./features/camera-animation.md) 和 [Move Pano Effect](./features/move-pano-effect.md) 实现平滑运镜。
+*   **State Management (状态管理)**:
+    *   保存/恢复场景：**必须** 深刻理解 [State](./features/state.md)。它是 Five 的核心快照机制，包含 Pose、Mode 和 PanoIndex。不要尝试手动管理零散的相机参数，应统一使用 State。
+*   **Coding Standards (代码规范)**:
+    *   优先使用 TypeScript 类型提示。
+    *   确保从 `@realsee/five` 导入核心类与类型 (e.g., `import { Five, Mode, Work, State } from "@realsee/five"`).
+
+### 3. General Retrieval (通用检索)
+*   **API Signatures**: [API Reference](./api.md) 是最权威的接口定义来源，包含方法的参数与返回值。
+*   **Terminology**: 遇到不确定的术语 (e.g., Pose vs State, Observer) 时，务必查阅 [Glossary](./glossary.md)。
+*   **Core Relationships**: 理解 [Five](./features/five.md) (渲染器) 与 [Work](./features/work.md) (数据) 的分离设计。
+
+## Documentation Map
+
+### 1. Essential Reference (必读/速查)
+最常用的入口文档。
+
+*   [Intro](./intro.md): Five SDK 简介与能力概览。
+*   [Quick Start](./quick-start.md): 快速集成指南。
+*   [API Reference](./api.md): **核心 API 索引** (Five 类, State, Events, Methods)。
+*   [Glossary](./glossary.md): **术语表** (Work, Observer, Pose, etc.)。
+
+### 2. Core Concepts (核心概念)
+基础架构与生命周期管理。
+
+*   [Five](./features/five.md): 核心类 `Five`，管理渲染循环与全局状态。
+*   [Work](./features/work.md): 数据载体，描述三维空间的数据结构 (VR 看房数据)。
+*   [Panorama UV](./features/pano-uv.md): 全景图 UV 与空间方向转换工具。
+*   [Mode](./features/mode.md): 五种核心浏览模式 (Panorama, Floorplan, Topview, Model, Map)。
+*   [State](./features/state.md): 状态管理 (Pose, Mode, PanoIndex)，用于复原场景。
+*   [Coordinate System](./features/coordinate-system.md): 坐标系定义 (右手坐标系, Y轴向上)。
+
+### 3. Data & Resource (数据与资源)
+数据加载与资源管理配置。
+
+*   [Load External Model](./features/load-external-model.md): 加载外部 3D 模型 (GLTF, OBJ 等)。
+*   [Load Progress](./features/load-progress.md): 监控模型与全景图的加载进度 (Loaded/Refined)。
+*   [Multi-Work (Sandbox)](./features/multi-work.md): 多 Work 加载与沙盘场景管理。
+*   [Request Proxy](./features/request-proxy.md): 请求拦截与代理 (CDN 替换、鉴权)。
+*   [Image Options](./features/image-options.md): 图片资源配置 (CDN, 格式, 尺寸)。
+
+### 4. Rendering & Visuals (渲染与视觉)
+画面表现与渲染管线配置。
+
+*   [Pano Tile](./features/pano-tile.md): 全景瓦片渲染机制（高分辨率分片加载）。
+*   [Model](./features/model.md): 内置模型渲染 (Mesh/Geometry)。
+*   [Postprocessing](./features/postprocessing.md): 后处理效果 (Pass, EffectComposer)。
+*   [Flowing Light 2D Pass](./features/flowing-light-2d-pass.md): 屏幕空间流光特效(InstancedMesh 优化)。
+*   [Flowing Light 3D Pass](./features/flowing-light-3d-pass.md): 3D 世界坐标流光特效(InstancedMesh 优化)。
+*   [Gaussian Blur Pass](./features/gaussian-blur-pass.md): 高斯模糊特效。
+*   [Material](./features/material.md): 材质参数配置 (透明度、点云大小、顶点标记)。
+*   [Get Screen Pixels](./features/get-screen-pixels.md): 获取屏幕像素 (放大镜/截图)。
+*   [Move Pano Effect](./features/move-pano-effect.md): 全景点位切换的过渡效果。
+*   [Clipper](./features/clipper.md): 模型裁切功能 (房屋剖面)。
+*   [3D Tile](./features/3dtile.md): 大场景 3D Tile 渲染策略。
+
+### 5. Interaction & Control (交互与控制)
+用户输入与相机控制。
+
+*   [Event](./features/event.md): 事件系统 (Tap, Gesture, StateChange)。
+*   [Gesture](./features/gesture.md): 手势交互详解。
+*   [Screen & Space Projection](./features/screen-project.md): 屏幕坐标与空间坐标转换 (标签/射线)。
+*   [Raycast](./features/raycast.md): 射线检测 (点击拾取物体)。
+*   [Camera Animation](./features/camera-animation.md): 相机动画控制 API。
+
+### 6. Advanced & Extensions (进阶与扩展)
+复杂配置与功能扩展。
+
+*   [Plugin](./features/plugin.md): 插件开发指南。
+*   [ViewLayer](./features/view-layer.md): 视图层。
+*   [Parameter](./features/parameter.md): Five 初始化详细参数配置。
+
+### 7. Meta & Support (其他)
+*   [Support](./support.md): 浏览器兼容性。
+*   [AI Documentation Guidelines](./ai-doc-guidelines.md): AI 文档编写与维护规范 (必读)。
+*   Release Notes: 版本更新记录。
+    *   [6.8](./release_notes/6.8.md)
+    *   [6.7](./release_notes/6.7.md)
+    *   [6.6](./release_notes/6.6.md)
+
+## Terminology Summary
+
+*   **Work**: 包含全景图、模型、户型数据的 JSON 对象。
+*   **Observer**: 观察点，通常对应一个全景拍摄点位。
+*   **PanoIndex**: 全景点位的索引下标。
+*   **Pose**: 相机位姿 (Longitude, Latitude, Fov)。
+*   **Mode**: 浏览模式 (Panorama, Model, etc.)。
+
+---
+```yaml
+tags: [index, readme, guide, map]
+```
+

package/ai_guides/ai-doc-guidelines.md

@@ -0,0 +1,102 @@
+<!-- AI-friendly guide template for `ai_guides/` -->
+# AI 文档与维护指南 (AI Documentation & Maintenance Guide)
+
+## Summary
+本文档包含两部分内容：
+1.  **Writing Guide**: 供 AI 和人类编写新文档时的标准模板与风格规范。
+2.  **Maintenance Guide**: 供 AI 维护者进行文档更新、同步与体检的操作指南。
+
+---
+
+# Part 1: Writing Guide (编写指南)
+
+## 目的
+提供统一、结构化的 Markdown 模板，便于 AI 自动解析、索引与生成功能性示例。
+
+## 建议风格
+- 使用中文为主，代码示例使用 TypeScript。
+- **受众意识**: 文档面向 SDK 的**外部使用者**。避免暴露无用的内部实现细节（如私有属性、临时状态），除非对调试有帮助。
+- **结构规范**: 严格使用二级标题 (`##`) 作为主要段落分割（如 `## Schema`, `## Concepts`），避免使用中文标题（如 `## 格式说明`）。
+- **代码缩进**: 强制使用 **两个空格** 缩进。
+- **相对路径**: 内部文档链接必须使用 **相对路径**（如 `./state.md`）。
+- **Schema**: 必须提供 TypeScript Interface 定义，并保留关键字段的注释（JSDoc）。
+    - **精简原则**: 仅展示核心与常用字段，避免列出所有内部或废弃字段。
+- **Configuration**: 对于参数较多的配置项，建议按 **“常用 (Common)”**、**“进阶 (Advanced)”**、**“内部 (Internal)”** 进行分类表格展示，并在内部参数处添加“不建议修改”的警告。
+- **Source Link**: 引用源码文件时，请在 `## Schema` 章节中使用 `> **Definition**: [InterfaceName](../../path/to/source.ts)` 的格式。**支持多个链接**（如 `[Five](...), [EventTypes](...)`），以便完整覆盖相关类型。**必须** 指向 `lib/` 目录下的 `.ts` 文件。构建脚本会自动将其转换为发布包中的 `.d.ts` 链接。
+- **Related**: 文档末尾建议包含 `## Related` 章节，提供相关文档的**相对路径链接**。
+    - **语义化**: 链接文字应准确反映目标文档的主题（如 `[Coordinate System](./coordinate.md)`）。
+- **Metadata**: 结尾必须包含 YAML 格式的 `tags`。
+- **文档拆分与审查**: 单个文档应保持精简。若内容过多需拆分为新专题，**必须**在创建新文件前向用户确认并获得批准，严禁擅自创建新文件。
+
+## 最佳实践 (Best Practices)
+
+### 1. 变量命名语义化 (Semantic Variable Naming)
+在示例代码中，变量名应准确反映其通用性或特定上下文。
+- **Good**: `parentParameter` (暗示可用于 Model, ViewLayer 等多种父级)
+- **Bad**: `modelParam` (若该逻辑同样适用于 ViewLayer，则会误导用户)
+
+### 2. 区分属性与方法 (Property vs Method)
+明确区分“直接访问属性”与“调用方法计算”。
+- 若 API 设计为 Getter (如 `parameter.opacity`)，文档应引导用户直接访问属性，避免混淆使用 `get()` 方法。
+- 对于涉及计算或继承的逻辑 (如 `resolveValue()`)，应显式说明其与直接访问的区别。
+
+### 3. 显式说明默认行为 (Explicit Default Behavior)
+对于有默认值或继承逻辑的方法，务必说明“不传参”时的行为。
+- 例如：`resolveValue()` 不传参时仅计算默认值；传入 `upstream` 时会包含继承逻辑。
+
+## 标准模板结构 (Standard Template Structure)
+
+无论是**新建文档**还是**维护现有文档**，都请参考独立模板文件：[template.md](./template.md)。
+
+- **新建文档**: 直接复制模板内容开始编写。
+- **维护文档**: 在修改现有文档时，请检查其结构是否符合模板要求（如 Schema 的 Definition 引用、Configuration 的分类等）。如果发现结构过时，请顺手将其标准化。
+- **特殊说明 (Special Notes)**:
+    - **模板链接格式 (Template Link Format)**:
+        - 模板(`template.md`)中所有的占位符链接（如 `Definition` 处的 `[InterfaceName](...)` 或 `Related` 处的 `[RelatedConcept](...)`）均使用了**代码块**包裹，以避免构建时因路径不存在而报错。
+        - **AI 操作**: 在编写正式文档时，**必须将其还原为可点击的标准 Markdown 链接**（即去掉反引号），并确保路径指向真实存在的文件。
+
+请严格遵循该模板的结构，以保证文档风格一致性。
+
+---
+
+# Part 2: Maintenance Guide (维护指南)
+
+## 核心原则 (Core Principles)
+为了防止文档与代码脱节，我们遵循 **“代码变更驱动文档更新”** 的原则。
+
+## 1. 语义化检索 (Semantic Retrieval)
+不再维护硬编码的“源码-文档”映射表。AI 维护者在修改代码后，应利用自身的语义搜索能力（如 `SearchCodebase` 或 `Grep`）来定位需要更新的文档。
+
+**推荐策略**:
+- 搜索**类名/方法名**: 如修改了 `five.load`，搜索 `five.load` 或 `load`。
+- 搜索**概念关键词**: 如修改了射线检测逻辑，搜索 `Raycast` 或 `project2d`。
+
+## 2. 单一事实来源 (Single Source of Truth)
+- **API 签名**: 以 `package/five/index.d.ts` 和代码中的 TSDoc 为准。
+- **ai_guides/api.md**: 仅作为 **索引 (Index)** 和 **摘要 (Summary)**。不要试图复制所有参数细节，除非是核心参数。
+- **ai_guides/features/*.md**: 重点解释 **“为什么”** 和 **“怎么用”**，避免机械复制类型定义。
+
+## 3. 维护工作流 (Maintenance Workflow)
+
+### 场景 A：代码功能迭代后 (Post-Coding)
+当修改了 SDK 源码后，请执行以下检查：
+1.  **反向查找**: 利用工具搜索关键词（API 名称、Feature 名称），找到 `ai_guides/` 下相关的文档。
+2.  **更新文档**:
+    *   如果修改了 API 签名 -> 更新对应的 `Schema` 和 `Examples`。
+    *   如果废弃了功能 -> 在文档中添加 `> [!WARNING] Deprecated` 提示。
+3.  **更新索引**: 如果是新功能，确保将其添加到 `ai_guides/README.md` 的合适章节中。
+4.  **同步 llms.txt**: 若新增了文档或修改了文档路径，**必须**同步更新项目根目录下的 `llms.txt`，确保外部索引与 `ai_guides/` 保持一致。
+
+### 场景 B：API 文档同步 (Sync API Doc)
+定期检查 `ai_guides/api.md` 的完整性：
+1.  读取 `package/five/index.d.ts` 获取最新公开 API。
+2.  对比 `ai_guides/api.md`，找出缺失的高频 API 或已删除的 API。
+3.  **注意**: 只收录高频/核心 API，低频 API 应引导用户查看源码或专门的 Feature 文档。
+
+## 目录结构说明
+- `ai_guides/`: 文档根目录。
+- `ai_guides/features/`: 功能性文档 (Features)。
+- `ai_guides/release_notes/`: 版本更新记录。
+- `ai_guides/api.md`: 核心 API 索引。
+- `ai_guides/README.md`: 文档总索引。
+- `package/five/index.d.ts`: **API 签名的真理来源**。

package/ai_guides/api.md

@@ -0,0 +1,274 @@
+# Five SDK API Reference
+
+This document provides a summary of the core API for the Five SDK, designed to be easily understood by AI assistants.
+
+## Core Class: `Five`
+
+The `Five` class is the main entry point for the SDK. It manages the rendering, state, and interaction of the 3D scene.
+
+### Constructor
+
+```typescript
+const five = new Five(initArgs?: FiveInitArgs);
+```
+
+### Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `five.state` | `State` | The current state (mode, position, etc.) of the instance. |
+| `five.currentMode` | `Mode` | Shortcut to get the current display mode. |
+| `five.panoIndex` | `number` | Shortcut to get the current panorama index. |
+| `five.work` | `Work` | The currently loaded work data. |
+| `five.model` | `Model` | The 3D model object. |
+| `five.scene` | `THREE.Scene` | The Three.js scene used for non-model elements. |
+| `five.modelScene` | `ModelScene` | The Three.js scene used for the model. |
+| `five.camera` | `Camera` | The internal camera. |
+| `five.renderer` | `THREE.WebGLRenderer` | The WebGL renderer. |
+| `five.needsRender` | `boolean` | Set to `true` to request a render frame in the next loop. |
+| `five.plugins` | `Object` | Access to registered plugins. |
+
+### Static Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `Five.Mode` | `Enum` | Available modes: `Panorama`, `Model`, `Floorplan`, `Topview`, `Mapview`, `VRPanorama`, `XRPanorama`. |
+
+## Initialization Configuration (`FiveInitArgs`)
+
+Configuration object passed to the `Five` constructor.
+
+```typescript
+interface FiveInitArgs {
+  /** External WebGLRenderer. If provided, internal renderer creation is skipped. */
+  renderer?: THREE.WebGLRenderer;
+
+  /** Width/Height of the viewport relative to container (0-1). */
+  viewport?: { left: number; bottom: number; width: number; height: number };
+
+  /** Canvas background color. Default: 0x181A1C */
+  backgroundColor?: number | THREE.Color;
+
+  /** Canvas background alpha (0-1). Default: 1 */
+  backgroundAlpha?: number;
+
+  /** Enable antialiasing. Default: false */
+  antialias?: boolean;
+
+  /** Auto-play rendering loop. Default: true */
+  play?: boolean;
+
+  /** Enable on-demand rendering to save battery. Default: true */
+  onlyRenderIfNeeds?: boolean;
+
+  /** Max FPS limit. false = unlimited. Default: false */
+  maxFps?: number | false;
+
+  /** Mode transition duration in ms. Default: 800 */
+  modeChangeDuration?: number;
+
+  /** Initial plugins to load. */
+  plugins?: FivePlugin[];
+
+  /** Dynamic image configuration for optimization. */
+  imageOptions?: ImageOptions;
+
+  /** Dynamic texture configuration for optimization. */
+  textureOptions?: TextureOptions;
+}
+```
+
+## Core Methods
+
+### `load(work, state?, options?)`
+Loads a "Work" (dataset) into the Five instance.
+
+- **work**: The data object (`LooseWork` or `Work`) containing scene information.
+- **state**: Initial state overrides. `"inherit"`, `"initial"`, or a `State` object.
+- **options**: Loading options (e.g., transition duration).
+
+### `appendTo(element, size?)`
+Mounts the Five canvas to a DOM element.
+
+- **element**: HTMLElement to append to.
+- **size**: Optional `{ width, height }`. Defaults to element size.
+
+### `setState(state, immediately?, userAction?)`
+Updates the current state (position, mode, etc.).
+
+- **state**: Partial `State` object to merge.
+- **immediately**: If `true`, skips animation.
+- **userAction**: Marks the change as triggered by user interaction.
+
+### `changeMode(mode, state?, options?)`
+Switches the viewing mode (e.g., from `Panorama` to `Model`).
+
+- **mode**: Target `Five.Mode`.
+- **state**: Target state after mode change.
+- **options**: Animation duration and effect.
+
+### `moveToPano(panoIndex, options?)`
+Moves to a specific panorama spot.
+
+- **panoIndex**: Index of the panorama.
+- **options**: `{ effect?: MovePanoEffect, duration?: number }`.
+
+### `refresh(size?)`
+Resizes the renderer to fit the container or specified size.
+
+### `getElement()`
+Returns the `<canvas>` element used by Five.
+
+### `project2d(vector, testModel?)`
+Projects a 3D point to 2D screen coordinates.
+
+- **vector**: `THREE.Vector3` (World Space).
+- **testModel**: `boolean` (default `false`). If `true`, checks for occlusion.
+- **returns**: `THREE.Vector2` (Screen Space, px) or `null`.
+
+### `getPixels(x, y, width, height)`
+Get pixel data from the renderer (e.g. for color picking or magnifier).
+
+- **x, y**: Coordinate of the lower-left corner (Screen Space).
+- **width, height**: Size of the rectangle.
+- **returns**: `Uint8Array` (RGBA data).
+
+### `intersectRaycaster(raycaster)`
+(On `five.model`) Performs raycasting against the scene models.
+
+- **raycaster**: `THREE.Raycaster`.
+- **returns**: `THREE.Intersection[]`.
+
+### `addPass(pass)`
+Add a post-processing pass to the rendering chain.
+
+- **pass**: `FivePass` instance (e.g. `Gaussian Blur Pass`).
+
+### `removePass(pass)`
+Remove a post-processing pass from the rendering chain.
+
+- **pass**: `FivePass` instance to remove.
+
+### `dispose()`
+Destroys the Five instance and releases resources.
+
+## State Management
+
+The `State` interface defines the complete status of the Five instance at any moment.
+
+```typescript
+interface State {
+  mode: Mode;          // Current view mode
+  panoIndex: number;   // Current panorama index
+  workCode: string;    // ID of the current work
+  latitude: number;    // Camera latitude (radians)
+  longitude: number;   // Camera longitude (radians)
+  distance: number;    // Camera distance from target
+  fov: number;         // Field of view
+  offset: THREE.Vector3; // Camera target offset
+}
+```
+
+## Data Structures
+
+### `Work`
+The main data object containing the scene description.
+
+```typescript
+interface Work {
+  workCode: string;          // Unique identifier
+  name: string;             // Project name
+  observers: WorkObserver[]; // List of panorama points
+  model: WorkModel;          // 3D model data
+  initial: WorkInitial;      // Initial view state
+  transform: THREE.Matrix4;  // World transform matrix
+}
+```
+
+### `WorkObserver` (Panorama Point)
+Represents a single panorama spot.
+
+```typescript
+interface WorkObserver {
+  index: number;             // Index in the list
+  floorIndex: number;        // Floor number
+  position: THREE.Vector3;   // Position in 3D space
+  quaternion: THREE.Quaternion; // Rotation relative to model
+  accessibleNodes: number[]; // Indices of reachable points
+  images: WorkImage;         // Panorama image URLs
+  active: boolean;           // Whether the point is enabled
+
+  // Coordinate Methods
+  getWorldPosition(): THREE.Vector3;
+  getWorldStandingPosition(): THREE.Vector3;
+
+  // UV Conversion Methods
+  vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;
+  equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+  vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [CubeFace, THREE.Vector2];
+  cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+}
+```
+
+## Events
+
+`Five` extends `Subscribe`, allowing event listening via `.on()`, `.once()`, and `.off()`.
+
+The SDK provides a modern event system (dot-notation, e.g., `gesture.tap`) which is recommended over the legacy system (camelCase, e.g., `wantsTapGesture`).
+
+### Recommended Events (Modern)
+
+These events follow a standard naming convention and provide typed event objects.
+
+#### Interaction & Gestures
+
+| Event Name | Description | Payload |
+| :--- | :--- | :--- |
+| `gesture.tap` | Triggered on tap/click. Replaces `wantsTapGesture`. | `{ pointers, event, ... }` |
+| `gesture.pan` | Triggered on pan/drag. | `{ pointers, ... }` |
+| `gesture.pinch` | Triggered on pinch/zoom. | `{ scale, ... }` |
+| `gesture.press` | Triggered on long press. | `{ pointers, ... }` |
+
+#### State & Mode
+
+| Event Name | Description | Payload |
+| :--- | :--- | :--- |
+| `mode.change` | Triggered when mode changes. | `ModeChangeEvent` |
+| `state.change` | Triggered when state changes (frequent). | `StateEvent` |
+| `camera.update` | Triggered when camera pose updates. | `CameraEvent` |
+
+#### Lifecycle & Resources
+
+| Event Name | Description | Payload |
+| :--- | :--- | :--- |
+| `works.load` | Triggered when work data starts loading. | `WorksEvent` |
+| `models.load` | Triggered when models are loaded. | `ModelSceneEvent` |
+| `model.tileLoad` | Triggered when a 3D tile is loaded. | `Tile` |
+| `model.tileUnload` | Triggered when a 3D tile is unloaded. | `Tile` |
+| `pano.arrived` | Triggered when arrival at a panorama node. | `PanoEvent` |
+| `pano.texture.progress` | Triggered when panorama texture loading progresses. | `{ progress, panoIndex }` |
+| `render` | Triggered after each render frame. | `RenderEvent` |
+| `error` | Triggered on internal errors. | `Error` |
+
+### Legacy Events (Deprecated)
+
+Older events are still supported for compatibility but should be avoided in new code.
+
+| Legacy Event | Recommended Replacement | Notes |
+| :--- | :--- | :--- |
+| `wantsTapGesture` | `gesture.tap` | |
+| `wantsPanGesture` | `gesture.pan` | |
+| `modelLoaded` | `models.load` | |
+| `initAnimationEnded` | `mode.change` | Check payload for details |
+
+### Usage Example
+
+```typescript
+// Recommended: Use the new event system
+five.on('gesture.tap', (event) => {
+  console.log('User tapped at:', event);
+});
+
+// Legacy (Avoid):
+// five.on('wantsTapGesture', (raycaster) => { ... });
+```