@realsee/five-webgpu 1.0.0-alpha.1 → 1.0.0-alpha.11

package/README.md

@@ -1,15 +1,15 @@
 # Five.js
 
-[![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)
+[![npm version](https://img.shields.io/npm/v/@realsee/five-webgpu.svg?style=flat-square&logo=npm&label=npm%20install%20@realsee/five-webgpu)](https://www.npmjs.com/package/@realsee/five-webgpu)
 
-贝壳如视三维渲染框架
+如视三维渲染框架
 
 > **🤖 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`.
+> If this package is installed in your project, you can find **AI-friendly documentation** directly in `node_modules/@realsee/five-webgpu/`. Please **READ** `node_modules/@realsee/five-webgpu/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-webgpu@alpha/ai_guides/README.md` or `https://unpkg.com/@realsee/five-webgpu@alpha/ai_guides/README.md`.
 ## Introduction
 
-**Five** 是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。基于 [Three.js](https://threejs.org/) 开发，帮助开发者在浏览器中构建高质量的 VR 看房与空间交互应用。
+**Five** 是 [如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。基于 [Three.js](https://threejs.org/) 开发，帮助开发者在浏览器中构建高质量的 VR 看房与空间交互应用。
 
 核心能力包括：
 *   **全景浏览**: 高分辨率全景图的高效加载与平滑浏览。
@@ -22,17 +22,17 @@
 通过 npm 或 yarn 安装：
 
 ```bash
-npm install three@^0.117.1 @realsee/five
+npm install three@^0.183.2 @realsee/five-webgpu
 # or
-yarn add three@^0.117.1 @realsee/five
+yarn add three@^0.183.2 @realsee/five-webgpu
 ```
 
-> **注意**: Five 依赖 `three`，目前推荐版本为 `0.117.1`。
+> **注意**: Five 依赖 `three`，目前推荐版本为 `0.183.2`。
 
 ## Quick Start
 
 ```typescript
-import { Five, parseWork } from "@realsee/five";
+import { Five, parseWork } from "@realsee/five-webgpu";
 
 // 1. 初始化
 const five = new Five();

package/_virtual/_rolldown/runtime.js

@@ -0,0 +1,255 @@
+/**
+ * @license
+ * @realsee/five-webgpu
+ * Generated: 10/27/2026
+ * Version: 1.0.0-alpha.11
+ * Terms:
+ * Realsee SDK License Agreement
+ * Update: July 28, 2021
+ * THIS LICENSE AGREEMENT BETWEEN YOU AND 【BEIKE REALSEE TECHNOLOGY (HK) 
+ * LIMITED】(“Realsee”) FORMS A LEGALLY BINDING CONTRACT BETWEEN YOU AND REALSEE IN 
+ * RELATION TO YOUR USE OF THE SDK. This License Agreement accompanies the Realsee 
+ * Software Development Kit(s) for the software and related explanatory materials 
+ * (the "SDK") and includes any upgrades, modified versions, updates, additions, 
+ * and copies of the SDK licensed to You by Realsee.
+ * BY DOWNLOADING, INSTALLING, OR OTHERWISE ACCESSING OR USING THE SDK, YOU AGREE 
+ * THAT YOU HAVE READ, UNDERSTOOD, AND AGREE TO BE BOUND BY THIS AGREEMENT. YOU ARE 
+ * AGREEING ON YOUR OWN BEHALF AND/OR ON BEHALF OF YOUR COMPANY OR ORGANIZATION TO 
+ * THE TERMS AND CONDITIONS STATED BELOW.
+ * This Agreement applies to Your use of the SDK in the country in which You 
+ * legally install it (“Territory”) and is subject to the laws of such Territory 
+ * and further subject to Section 12 below. Different terms, conditions, and 
+ * limitations may apply to the use of the SDK in any additional countries.
+ * 1. DEFINITIONS.
+ * “Agreement” means this Realsee SDK License Agreement.
+ * “Developer”, “You” and “Your” means the person(s) or entity acquiring or using 
+ * the SDK or otherwise exercising rights under the terms of this Agreement.
+ * “Documentation” means the technical or other specifications or documentation 
+ * that Realsee may provide to You for use in connection with the SDK.
+ * “Integrated Product” means any software, website, or on-line service developed 
+ * by You based on or using the SDK (collectively, the “Integrated Product”).
+ * “Intellectual Property” means any patents, patent rights, trademarks, service 
+ * marks, registered and unregistered designs, applications for any of the 
+ * foregoing, copyright, and any other similar protected rights in any country and 
+ * to the extent recognised by any relevant jurisdiction as intellectual property, 
+ * trade secrets, know-how and confidential information. Realsee reserves all 
+ * rights not expressly granted to You.
+ * “Realsee” means [Beike Realsee Technology (HK) Limited, a company incorporated 
+ * and validly existing under the laws of Hong Kong].
+ * “SDK” means the Realsee-proprietary Software Development Kits (SDK) provided 
+ * hereunder, includes all development tools (including any compiler and debugger), 
+ * application programming interfaces (“APIs”), libraries, binary utilities, header 
+ * files, Documentation, content, data, code samples, and other materials provided 
+ * to You in connection with this Agreement, whether delivered through a download, 
+ * or any other media or form, and is licensed, not sold, to You by Realsee for use 
+ * only under the terms of this Agreement. The terms of this Agreement will govern 
+ * any updates provided by Realsee that replace and/or supplement the original SDK 
+ * delivered to You, unless such update is accompanied by a separate license, in 
+ * which case the terms of such license will govern.
+ * 2. LICENSED USES AND RESTRICTIONS.
+ * 2.1 Subject to the restrictions contained in this Section 2, Realsee grants to 
+ * You during the term, a limited, non-exclusive, revocable, non-sublicensable, 
+ * non-transferable license to install and use the SDK within the Territory only 
+ * for the purpose of internal development.
+ * 2.2 Restrictions. You acknowledge and agree that, You shall not, and shall 
+ * ensure that Your affiliates, employees, agents, representatives, officers, 
+ * representatives, and subcontractors do not (directly or indirectly):
+ * 2.2.1 decompile, reverse engineer, disassemble or attempt to derive the source 
+ * code of, those components of the SDK provided in object code form, or any part 
+ * thereof;
+ * 2.2.2 remove, alter, or obscure any copyright notice or other proprietary rights 
+ * notice on any part of the SDK;
+ * 2.2.3 sell, assign, pledge, rent, lease, lend, upload to or host on any website 
+ * or server for use by any third party except You, redistribute, or sublicense the 
+ * SDK (or any part thereof), or operate the SDK (or any part thereof) in the 
+ * capacity of a service bureau or other hosted services provider, in whole or in 
+ * part, nor may You enable others to do so;
+ * 2.2.4 or alter, modify, customize or improve the SDK, or any part thereof;
+ * 2.2.5 use the SDK (or any part thereof) for any illegal purpose, in any manner 
+ * that is inconsistent with the terms of this Agreement, or to engage in any 
+ * illegal activity;
+ * 2.2.6 use the SDK (or any part thereof) in any manner that may damage the 
+ * operation of Realsee’s products or services; or
+ * 2.2.7 use the SDK or any information contained therein or otherwise provided by 
+ * Realsee for the purpose of developing, or having developed, any product 
+ * competitive with any Realsee product or service, as determined by Realsee in its 
+ * sole discretion;
+ * 2.2.8 include any portion of the SDK in Your Developer products.
+ * 2.3 Realsee has the right to impose reasonable conditions such as a reasonable 
+ * fee for use of the SDK in Integrated Product in the future.
+ * 2.4 You may make a limited number of copies of the SDK to be used by Your 
+ * employees or consultants as provided herein, and not for general business 
+ * purposes, and such employees or consultants shall be subject to the obligations 
+ * and restrictions in this Agreement.
+ * 2.5 All licenses not expressly granted in this Agreement are reserved and no 
+ * other licenses, immunity, or rights, express or implied, are granted by Realsee, 
+ * by implication, estoppel, or otherwise.
+ * 3. CONFIDENTIALITY.
+ * The SDK and all source code, Documentation, specifications, engineering details, 
+ * and related information pertaining to the SDK, whether in oral, written, 
+ * graphic, or electronic form, are and shall remain the confidential and 
+ * proprietary information of Realsee or its licensors (collectively, the 
+ * “Confidential Information”). You shall (i) disclose Confidential Information to 
+ * only those directors and employees (collectively, “Affiliates”) whose duties 
+ * justify their need to know such information and who have been clearly informed 
+ * of their obligation to maintain the confidential, proprietary, and/or trade 
+ * secret status of such Confidential Information; and (ii) use Confidential 
+ * Information solely in accordance with the license granted hereunder. In any 
+ * event, You and Your Affiliates shall treat Confidential Information as strictly 
+ * confidential and shall use the same care to prevent disclosure of such 
+ * information as You use with respect to Your own similar confidential and/or 
+ * proprietary information, which shall not be less than the care a reasonable 
+ * person would use under similar circumstances. All Confidential Information, and 
+ * any copies thereof, shall be returned promptly to Realsee upon request. You 
+ * shall ensure that Your Affiliates comply with the provisions of this Section 3, 
+ * and You shall be liable for any breach of this Section 3 resulting from the act 
+ * or omission of any of Your Affiliates. You shall not disclose Confidential 
+ * Information to any third party, including, without limitation, any of Your 
+ * subcontractors.
+ * 4. PROPRIETARY RIGHTS.
+ * 4.1 As between You and Realsee, Realsee and/or its licensors retain ownership of 
+ * all right, title, and interest in, to, and under the SDK, including, without 
+ * limitation, all patents, copyrights, trade secrets, trademarks and other 
+ * intellectual property and other proprietary rights therein, and reserve all 
+ * rights not expressly granted to You.
+ * 4.2 The items contained in the SDK are the intellectual property of Realsee and 
+ * its licensors and are protected by PRC copyright and patent law, international 
+ * treaty provisions and applicable laws of the country in which it is being used. 
+ * You agree to protect all copyright and other ownership interests of Realsee 
+ * and/or its licensors in all items in the SDK supplied under this License 
+ * Agreement. You agree that all copies of the items in the SDK, reproduced for any 
+ * reason by You, contain the same copyright notices, and other proprietary notices 
+ * as appropriate, as appear on or in the original items delivered by Realsee in 
+ * the SDK. Realsee and/or its licensors retain title and ownership of the items in 
+ * the SDK, the media on which it is loaded, and all subsequent copies, regardless 
+ * of the form or media in or on which the original and other copies may exist. 
+ * Except as stated above, this Agreement does not grant You any rights to patents, 
+ * copyrights, trade secrets, trademarks or any other rights in respect to the 
+ * items in the SDK.
+ * 5. TERM AND TERMINATION.
+ * 5.1 This Agreement is effective until terminated. Realsee has the right to 
+ * terminate this Agreement immediately, without judicial intervention, if You fail 
+ * to comply with any term herein. Upon any such termination You must remove all 
+ * full and partial copies of the items in the SDK from Your computer and 
+ * discontinue the use of the items in the SDK.
+ * 5.2 Realsee may at any time, terminate the Agreement with You if: (A) You have 
+ * breached any provision of the Agreement; or (B) Realsee is required to do so by 
+ * law; or (C) Realsee decides to no longer provide the SDK or certain parts of the 
+ * SDK to users in the country in which You are resident or from which You use the 
+ * service, or the provision of the SDK or certain SDK services to You by Realsee 
+ * is, in Realsee's sole discretion, no longer legally or commercially viable.
+ * 5.3 When the Agreement comes to an end, all of the legal rights, obligations and 
+ * liabilities that You and Realsee have benefited from, been subject to (or which 
+ * have accrued over time whilst the Agreement has been in force) or which are 
+ * expressed to continue indefinitely, shall be unaffected by this cessation, and 
+ * the provisions of Section 3, 4, 6, 7 and 8 shall continue to apply to such 
+ * rights, obligations and liabilities indefinitely.
+ * 6. DISCLAIMER OF WARRANTY.
+ * YOU EXPRESSLY ACKNOWLEDGE AND AGREE THAT, TO THE EXTENT PERMITTED BY APPLICABLE 
+ * LAW, USE OF THE SDK (OR ANY PART THEREOF) IS AT YOUR SOLE RISK AND THAT THE 
+ * ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY, AND EFFORT IS 
+ * WITH YOU. REALSEE LICENSES THE SDK TO YOU ONLY ON AN "AS-IS" BASIS. REALSEE 
+ * MAKES NO REPRESENTATION WITH RESPECT TO THE ADEQUACY OF ANY ITEMS IN THE SDK, 
+ * WHETHER OR NOT USED BY YOU IN THE DEVELOPMENT OF INTEGRATED PRODUCT, FOR ANY 
+ * PARTICULAR PURPOSE OR WITH RESPECT TO THEIR ADEQUACY TO PRODUCE ANY PARTICULAR 
+ * RESULT. REALSEE AND ITS LICENSORS SHALL NOT BE LIABLE FOR LOSS OR DAMAGE ARISING 
+ * OUT OF THIS AGREEMENT OR FROM THE DISTRIBUTION OR USE OF INTEGRATED PRODUCT 
+ * CONTAINING PORTIONS OF THE SDK. REALSEE AND ITS LICENSORS DISCLAIM ALL 
+ * WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED 
+ * CONDITIONS OR WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
+ * OR NONINFRINGEMENT OF ANY THIRD PARTY RIGHT IN RESPECT OF THE ITEMS IN THE SDK 
+ * OR ANY SERVICES RELATED TO THE SDK.
+ * REALSEE IS UNDER NO OBLIGATION TO PROVIDE ANY SUPPORT UNDER THIS LICENSE 
+ * AGREEMENT, INCLUDING UPGRADES OR FUTURE VERSIONS OF THE SDK OR ANY PORTIONS 
+ * THEREOF, TO YOU, END USER OR TO ANY OTHER PARTY.
+ * 7. LIMITATION OF LIABILITY.
+ * TO THE EXTENT NOT PROHIBITED BY APPLICABLE LAW, IN NO EVENT WILL REALSEE OR ITS 
+ * LICENSORS BE LIABLE FOR ANY DIRECT, INCIDENTAL, SPECIAL, INDIRECT, OR 
+ * CONSEQUENTIAL DAMAGES, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF USE, 
+ * LOSS OF BUSINESS, REVENUE, OR PROFITS, LOSS OF OPPORTUNITY (WHETHER DIRECT OR 
+ * INDIRECT), CORRUPTION OR LOSS OF DATA, LOSS OF REPUTATION OR SAVINGS, DOWNTIME, 
+ * OR DAMAGE TO, LOSS OF OR REPLACEMENT OF DATA OR TRANSACTIONS, COST OF 
+ * PROCUREMENT OF SUBSTITUTE SERVICES, BUSINESS INTERRUPTION, OR ANY OTHER 
+ * COMMERCIAL DAMAGES OR LOSSES, ARISING OUT OF OR RELATED TO YOUR USE OR INABILITY 
+ * TO USE THE SDK (OR ANY PART THEREOF), ANY INTEGRATED PRODUCT, OR ANY THIRD PARTY 
+ * SOFTWARE, APPLICATIONS, OR SERVICES IN CONJUNCTION WITH THE SDK (OR ANY PART 
+ * THEREOF), HOWEVER CAUSED, REGARDLESS OF THE THEORY OF LIABILITY (CONTRACT, TORT, 
+ * OR OTHERWISE) AND EVEN IF REALSEE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH 
+ * DAMAGES. IN NO EVENT WILL REALSEE’S TOTAL LIABILITY TO YOU FOR ALL DAMAGES 
+ * EXCEED ONE HUNDRED DOLLARS ($100.00). THE FOREGOING LIMITATIONS WILL APPLY EVEN 
+ * IF THE ABOVE STATED REMEDY FAILS OF ITS ESSENTIAL PURPOSE. THE LIMITATIONS 
+ * CONTAINED IN SECTIONS 6 AND THIS SECTION 7 ARE A FUNDAMENTAL PART OF THE BASIS 
+ * OF REALSEE’S BARGAIN HEREUNDER, AND REALSEE WOULD NOT ENTER INTO THIS AGREEMENT 
+ * OR PROVIDE YOU WITH ACCESS TO THE SDK ABSENT SUCH LIMITATIONS.
+ * 8. INDEMNIFICATION.
+ * To the extent permitted by applicable law, You agree to indemnify, defend and 
+ * hold harmless Realsee, its affiliates and each of their directors, officers, 
+ * employees, independent contractors, and agents (each a “Realsee Indemnified 
+ * Party”) from any and all claims, losses, liabilities, damages, expenses, and 
+ * costs (including without limitation attorneys’ fees and court costs) incurred by 
+ * a Realsee Indemnified Party as a result of: (i) Your non-compliance with any 
+ * terms of this Agreement; (ii) Your use of the SDK (or any part thereof); or 
+ * (iii) Your use of any Integrated Product, including any claim that Integrated 
+ * Product infringes the copyright, trademark, trade secret or other intellectual 
+ * property right of a third party.
+ * 9. ACKNOWLEDGEMENTS.
+ * Portions of the SDK may utilize or include third party software and other 
+ * copyrighted material. Acknowledgments, licensing terms, and disclaimers for such 
+ * material are contained in Documentation for the SDK or may otherwise accompany 
+ * such material, and Your use of such materials governed by their respective 
+ * terms. In the event of conflict between the terms of this Agreement and an 
+ * applicable open source or third party agreement, the open source or third party 
+ * agreement will control solely with respect to the open source software or third 
+ * party software. Moreover, You shall not subject any items (including not limited 
+ * to source code, object code, and any software)  included in the SDK to any open 
+ * source license.
+ * 10. NON-BLOCKING OF REALSEE DEVELOPMENT.
+ * You acknowledge that Realsee is currently developing or may develop technologies 
+ * and products in the future that have or may have design and/or functionality 
+ * similar to Integrated Product that You may develop based on Your license herein. 
+ * Nothing in this Agreement shall impair, limit or curtail Realsee's right to 
+ * continue with its development, maintenance and/or distribution of Realsee's 
+ * technology or products.
+ * 11. GENERAL.
+ * 11.1 Export Control. You may not use or otherwise export or re-export the SDK 
+ * (or any part thereof) except as authorized by United States law and the laws of 
+ * the jurisdiction(s) in which the SDK (or any part thereof) was obtained. In 
+ * particular, but without limitation, the SDK may not be exported or re-exported 
+ * (i) into any U.S. embargoed countries or (ii) to anyone on the U.S. Treasury 
+ * Department's list of Specially Designated Nationals or the U.S. Department of 
+ * Commerce Denied Person's List or Entity List. By using the SDK (or any part 
+ * thereof), You represent and warrant that You are not located in any such country 
+ * or on any such list.
+ * 11.2 Governing Law. This Agreement and the rights of the parties hereunder shall 
+ * be governed by and construed in accordance with the laws of People’s Republic of 
+ * China (for purpose of this Agreement, excluding Hong Kong, Taiwan, and Macau), 
+ * without reference to its conflict of laws principles. Any dispute, controversy 
+ * or claim arising from or in connection with this Agreement, or the breach, 
+ * termination or invalidity thereof, shall be submitted to China International 
+ * Economic and Trade Arbitration Commission (“CIETAC”) for arbitration in Beijing 
+ * which shall be conducted in accordance with the CIETAC's arbitration rules in 
+ * effect at the time of applying for arbitration. The arbitral award is final and 
+ * binding upon both parties.
+ * 11.3 Severability. If any provision of this Agreement is held by a court of 
+ * competent jurisdiction to be unenforceable for any reason, the remaining 
+ * provisions hereof will be unaffected and remain in full force and effect.
+ * 11.4. Modifications. Realsee reserves the right, from time to time, with or 
+ * without notice to You, to make revisions to this Agreement in our sole and 
+ * absolute discretion.  The most current version of this Agreement will supersede 
+ * all previous versions and shall be made available on the website where the SDK 
+ * is made available, or by such other means as Realsee may determine in its 
+ * discretion. Any modified versions of this Agreement hereto shall take effect 
+ * from the time that it is made available. You shall be responsible for regularly 
+ * checking for notice of any such modifications. You agree that Your continued use 
+ * of the SDK constitutes Your agreement to the modified Agreement.
+ * 11.5 Relationship of the Parties. This Agreement will not be construed as 
+ * creating an agency, partnership, joint venture, fiduciary duty, or any other 
+ * form of legal association between You and Realsee, and You will not represent to 
+ * the contrary, whether expressly, by implication, appearance, or otherwise.
+ * 11.6 Entire Agreement; Governing Language. This Agreement constitutes the entire 
+ * agreement between You and Realsee with respect to the use of the SDK licensed 
+ * hereunder and supersedes all prior understandings regarding such subject matter. 
+ * No amendment to or modification of this Agreement will be binding unless in 
+ * writing and signed by Realsee. You and Realsee hereto confirm that this 
+ * Agreement and all related documents shall be drafted in English.
+*/var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));exports.__toESM=s;

package/ai_guides/README.md

@@ -1,6 +1,6 @@
 # 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)
+[![npm version](https://img.shields.io/npm/v/@realsee/five-webgpu.svg?style=flat-square&logo=npm&label=npm%20install%20@realsee/five-webgpu)](https://www.npmjs.com/package/@realsee/five-webgpu)
 
 - **Summary**: Five SDK 的文档索引与阅读指南，旨在帮助开发者与 AI 助手快速定位所需信息。
 - **Audience**: 开发者、AI 辅助编程工具。
@@ -32,7 +32,7 @@
     *   保存/恢复场景：**必须** 深刻理解 [State](./features/state.md)。它是 Five 的核心快照机制，包含 Pose、Mode 和 PanoIndex。不要尝试手动管理零散的相机参数，应统一使用 State。
 *   **Coding Standards (代码规范)**:
     *   优先使用 TypeScript 类型提示。
-    *   确保从 `@realsee/five` 导入核心类与类型 (e.g., `import { Five, Mode, Work, State } from "@realsee/five"`).
+    *   确保从 `@realsee/five-webgpu` 导入核心类与类型 (e.g., `import { Five, Mode, Work, State } from "@realsee/five-webgpu"`).
 
 ### 3. General Retrieval (通用检索)
 *   **API Signatures**: [API Reference](./api.md) 是最权威的接口定义来源，包含方法的参数与返回值。

package/ai_guides/api.md

@@ -24,7 +24,7 @@ const five = new Five(initArgs?: FiveInitArgs);
 | `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.renderer` | `THREE.WebGPURenderer` | The WebGPU renderer. |
 | `five.needsRender` | `boolean` | Set to `true` to request a render frame in the next loop. |
 | `five.plugins` | `Object` | Access to registered plugins. |
 
@@ -32,7 +32,7 @@ const five = new Five(initArgs?: FiveInitArgs);
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
-| `Five.Mode` | `Enum` | Available modes: `Panorama`, `Model`, `Floorplan`, `Topview`, `Mapview`, `VRPanorama`, `XRPanorama`. |
+| `Five.Mode` | `Enum` | Available modes: `Panorama`, `Model`, `Floorplan`, `Topview`, `Mapview`, `VRPanorama`. |
 
 ## Initialization Configuration (`FiveInitArgs`)
 
@@ -40,8 +40,8 @@ Configuration object passed to the `Five` constructor.
 
 ```typescript
 interface FiveInitArgs {
-  /** External WebGLRenderer. If provided, internal renderer creation is skipped. */
-  renderer?: THREE.WebGLRenderer;
+  /** External WebGPURenderer. If provided, internal renderer creation is skipped. */
+  renderer?: THREE.WebGPURenderer;
 
   /** Width/Height of the viewport relative to container (0-1). */
   viewport?: { left: number; bottom: number; width: number; height: number };
@@ -80,12 +80,13 @@ interface FiveInitArgs {
 
 ## Core Methods
 
-### `load(work, state?, options?)`
+### `load(inputWork, state?, options?, userAction?)`
 Loads a "Work" (dataset) into the Five instance.
 
-- **work**: The data object (`LooseWork` or `Work`) containing scene information.
+- **inputWork**: 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).
+- **userAction**: Whether the load was triggered by a user action. Defaults to `true`.
 
 ### `appendTo(element, size?)`
 Mounts the Five canvas to a DOM element.
@@ -243,8 +244,8 @@ These events follow a standard naming convention and provide typed event objects
 | :--- | :--- | :--- |
 | `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` |
+| `models.tileLoad` | Triggered when a 3D tile is loaded. | `ModelTileEvent` |
+| `models.tileUnload` | Triggered when a 3D tile is unloaded. | `ModelTileEvent` |
 | `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` |

package/ai_guides/features/camera-animation.md

@@ -104,7 +104,7 @@ five.changeMode(mode: Mode, options?, animationOptions?): Promise<void>
 
 | Parameter | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `modeChangeDuration` | `number` | `1000` | 模态切换 (如 Panorama -> Mapview) 的默认时长 (ms)。 |
+| `modeChangeDuration` | `number` | `800` | 模态切换 (如 Panorama -> Mapview) 的默认时长 (ms)。 |
 
 ### MovePanoOptions Configuration (移动参数)
 

package/ai_guides/features/clipper.md

@@ -62,7 +62,7 @@ Clipper 的几何定义依赖于 `clippingBoxMatrix`。
 
 ```typescript
 import * as THREE from 'three';
-import { Five } from '@realsee/five';
+import { Five } from '@realsee/five-webgpu';
 
 // 1. 创建一个辅助 Mesh 来定义裁切区域
 // 注意：必须使用 1x1x1 的 BoxGeometry，因为 Shader 是基于单位立方体判断的

package/ai_guides/features/coordinate-system.md

@@ -98,7 +98,7 @@ Five 的渲染场景 (`five.scene`) 和 Observers (观察点) 使用 **Y-up** (Y
 
 ```typescript
 import * as THREE from 'three';
-import { ViewLayer } from '@realsee/five';
+import { ViewLayer } from '@realsee/five-webgpu';
 
 // 假设已加载 ViewLayer
 const viewLayer: ViewLayer = ...;

package/ai_guides/features/event.md

@@ -70,7 +70,6 @@ Five 的事件系统将事件主要分为以下几类：
 
 - `pano.arrived`: 成功到达新点位（移动动画结束）。
 - `pano.moving`: 正在移动到新点位（动画进行中）。
-- `pano.willChange`: 即将发生点位变更（旧版兼容）。
 - `pano.error`: 点位加载或移动出错。
 
 ### State Events (状态变更)
@@ -100,7 +99,7 @@ Five 的事件系统将事件主要分为以下几类：
 监听点击事件并打印日志。
 
 ```typescript
-import { Five } from "@realsee/five";
+import { Five } from "@realsee/five-webgpu";
 
 const five = new Five();
 

package/ai_guides/features/five.md

@@ -1,6 +1,6 @@
 # Five (Five 核心类)
 
-- **Summary**: Five 是 @realsee/five 的核心类，负责 3D 场景的渲染、资源加载、用户交互和状态管理。
+- **Summary**: Five 是 @realsee/five-webgpu 的核心类，负责 3D 场景的渲染、资源加载、用户交互和状态管理。
 - **Schema**: FiveInitArgs 初始化参数接口。
 - **Concepts**: Instance Management, Rendering Loop, Resource Loading, State Sync.
 - **Configuration**: Five 初始化参数详解。
@@ -17,7 +17,7 @@
 ```typescript
 interface FiveInitArgs {
   /** 外部传入的渲染器 (如果传入，部分渲染配置将失效) */
-  renderer?: THREE.WebGLRenderer;
+  renderer?: THREE.WebGPURenderer;
   /**
    * 屏幕渲染区域 { left, bottom, width, height }
    * 必须配合外部 renderer 使用
@@ -35,7 +35,7 @@ interface FiveInitArgs {
   textureOptions?: TextureOptions;
   /** 是否按需渲染 (默认 true, 推荐开启以节省性能) */
   onlyRenderIfNeeds?: boolean;
-  /** 模式切换动画时长 (ms, 默认 1000) */
+  /** 模式切换动画时长 (ms, 默认 800) */
   modeChangeDuration?: number;
   /** 是否支持滚轮缩放 (默认 true) */
   enableWheel?: boolean;
@@ -43,6 +43,17 @@ interface FiveInitArgs {
   plugins?: FivePlugin[];
   /** 是否显示 Powered by Realsee */
   poweredByRealsee?: boolean;
+  /**
+   * 强制使用 WebGL2 回落后端（默认 false）
+   * 进入 XRPanorama（WebXR 头显全景）的前置条件。
+   * 只在构造期生效，后端无法在运行时切换，设备检测必须在 new Five() 之前完成。
+   * 详见下方《forceWebGL 与 XR 回落后端》。
+   */
+  forceWebGL?: boolean;
+  /**
+   * @deprecated 在 five-webgpu 中未接线、无效。需要 WebGL2 后端请使用 `forceWebGL`。
+   */
+  webgl2?: boolean;
 }
 ```
 
@@ -55,7 +66,7 @@ Five 实例是整个 3D 场景的入口。
 
 ### Rendering Loop (渲染循环)
 Five 内部维护了一个 `requestAnimationFrame` 循环。
-- **按需渲染**: 默认开启 `onlyRenderIfNeeds`，仅在画面发生变化（如视角移动、数据加载）时才触发 WebGL 绘制，大幅降低能耗。
+- **按需渲染**: 默认开启 `onlyRenderIfNeeds`，仅在画面发生变化（如视角移动、数据加载）时才触发渲染，大幅降低能耗。
 - **手动触发**: 可以通过 `five.needsRender = true` 强制下一帧进行渲染。
 
 ### Resource Loading (资源加载)
@@ -71,8 +82,66 @@ Five 内部维护了一个 `requestAnimationFrame` 循环。
 | `textureOptions` | `TextureOptions` | `{}` | 贴图加载策略，同上 |
 | `onlyRenderIfNeeds` | `boolean` | `true` | 是否仅在需要时渲染，建议保持 `true` |
 | `antialias` | `boolean` | `false` | 抗锯齿，开启会增加性能消耗 |
-| `modeChangeDuration` | `number` | `1000` | 模式切换动画时长 (ms) |
+| `modeChangeDuration` | `number` | `800` | 模式切换动画时长 (ms) |
 | `enableWheel` | `boolean` | `true` | 是否支持滚轮缩放 |
+| `forceWebGL` | `boolean` | `false` | 强制使用 WebGL2 回落后端，进入 `XRPanorama` 的前置条件，详见下文 |
+| `webgl2` | `boolean` | — | **已废弃**，在 five-webgpu 中未接线。需要 WebGL2 请用 `forceWebGL` |
+
+### forceWebGL 与 XR 回落后端
+
+`forceWebGL` 让 five-webgpu 强制走 WebGL2 回落后端，而不是默认的 WebGPU 后端。它存在的唯一原因是 **进入 `XRPanorama`（WebXR 头显全景）模式**：`three` 的 WebGPU 后端目前不支持 WebXR，而 WebGL2 后端下 `renderer.xr` 完整可用。
+
+**语义与使用约束**
+
+- **语义**：`forceWebGL: true` 时，内部 `WebGPURenderer` 以 `{ forceWebGL: true }` 构造，使用 `WebGLBackend` 而非 WebGPU。
+- **必须在 `new Five()` 时决定**：后端在 renderer 构造期定死，**运行时无法切换**。因此业务侧的「是否需要进入 XR」的设备检测必须发生在 `new Five()` 之前，不能等实例创建后再改。
+- **与 `enableHDR` 互斥**：当 `forceWebGL` 为 `true` 时 `enableHDR` 不生效（`five.enableHDR` 会被置为 `false`），因为 XR 的 projection layer 固定 `colorFormat: RGBA8`，HDR 没有落地路径。
+- **传入外部 `renderer` 时不生效**：如果通过 `renderer` 参数传入了外部渲染器，`forceWebGL` 不会对其生效，需由调用方自行在构造该 renderer 时设置 `forceWebGL`（与 `antialias` 等参数一致）。
+- **`webgl2` 已废弃**：遗留的 `webgl2` 参数在 five-webgpu 中未接线、无任何效果；需要 WebGL2 后端请改用 `forceWebGL`。
+
+**能力降级限制**（开启 `forceWebGL` 后不可规避）
+
+1. **XR 下没有后处理**：`XRPanorama` 模式会整体旁路 `FiveRenderer` 的后处理链路（合成 / EffectComposer 全屏 pass 均不参与），滤镜、泛光等后处理在头显中不生效。
+2. **点云走 NodeMaterial 路径**：`forceWebGL` 下点云不再走 WebGPU compute 光栅化，而是退回 NodeMaterial 渲染路径。
+3. **3DGS 走 CPU 排序，且 VR 中性能预期需放低**：`forceWebGL` 下 3DGS 只能走 CPU 排序（`RASTER_CPU_SORT`）；在 XR 中还要叠加双眼渲染开销，务必对点数 / 显示做降级，不要期待与 WebGPU 后端相同的帧率。
+
+```typescript
+import { Five } from "@realsee/five-webgpu";
+
+// 设备检测需在 new Five() 之前完成
+const needXR = detectNeedXR();
+
+const five = new Five({
+  forceWebGL: needXR, // 一旦创建就无法再切换后端
+});
+
+five.load(workData);
+
+// 进入 XR（需在用户手势回调中调用，会触发 WebXR 权限请求）
+button.addEventListener("click", () => {
+  five.changeMode("XRPanorama").catch((error) => {
+    // 后端非 WebGL2 或浏览器不支持 WebXR 时，这里会收到含 forceWebGL 字样的中文错误
+    console.error(error);
+  });
+});
+
+// 用户摘下头显 / 退出 XR 时切回普通全景
+five.on("xr.session.end", () => five.changeMode("Panorama"));
+```
+
+也可以直接使用内置的 `XRButton`，样式与 API 同原始 five 保持一致（`XRButton.createButton(onClickHook)`）：
+
+```typescript
+import { Five, XRButton } from "@realsee/five-webgpu";
+
+const button = XRButton.createButton(() => five.changeMode("XRPanorama"));
+document.body.appendChild(button);
+```
+
+- 浏览器没有 `navigator.xr` 时显示 `WEBXR NOT AVAILABLE`（非 HTTPS 时显示 `WEBXR NEEDS HTTPS`），不支持 `immersive-vr` 时显示 `VR NOT SUPPORTED`。
+- 回调返回 Promise 时，`XRButton` 会接住 reject。若失败原因是没有开启 `forceWebGL`（后端是 WebGPU），按钮文案会临时变为「需降级到 WebGL2」，3 秒后恢复。其他失败原因不改变按钮，错误通过 `five.on("error")` 上报。
+
+> 更多模式说明（含 `XRPanorama` 与 `VRPanorama` 的区别）见 [mode.md](./mode.md)，可运行示例参见 `examples/xr`。
 
 ## Examples
 
@@ -80,7 +149,7 @@ Five 内部维护了一个 `requestAnimationFrame` 循环。
 创建一个全屏的 Five 实例并加载数据。
 
 ```typescript
-import { Five, parseWork } from "@realsee/five";
+import { Five, parseWork } from "@realsee/five-webgpu";
 
 // 1. 初始化实例
 const five = new Five({
@@ -101,9 +170,9 @@ five.load(workData);
 
 ```typescript
 import * as THREE from "three/webgpu";
-import { Five } from "@realsee/five";
+import { Five } from "@realsee/five-webgpu";
 
-const renderer = new THREE.WebGLRenderer();
+const renderer = new THREE.WebGPURenderer();
 renderer.setSize(window.innerWidth, window.innerHeight);
 document.body.appendChild(renderer.domElement);
 
@@ -152,8 +221,8 @@ five.updateCameraWithKeyframes(keyframes, 2000).then(() => {
 ### 实例方法 (Instance Methods)
 
 - **`appendTo(element: HTMLElement)`**: 将 canvas 挂载到指定 DOM 元素。
-- **`load(work: Work, state?: State, duration?: number)`**: 加载场景数据。详见 [work.md](./work.md)。
-- **`dispose()`**: 销毁实例，释放 WebGL 上下文与内存。
+- **`load(inputWork, state?: "inherit" | "initial" | Partial<State>, options?: number | FiveLoadOptions, userAction?: boolean)`**: 加载场景数据。详见 [work.md](./work.md)。
+- **`dispose()`**: 销毁实例并释放相关渲染资源。
 - **`updateCamera(pose: Partial<Pose>, duration: number, userAction?: boolean)`**: 移动相机（不触发点位移动）。移动相机的视角或位置，不会改变当前所在的 PanoIndex。如果动画中途被打断，Promise 会被 reject。
 - **`updateCameraWithKeyframes(keyframes: { progress: number; value: Pose; key?: string }[], duration: number, userAction?: boolean)`**: 通过关键帧动画移动相机。
 - **`refresh()`**: 强制刷新画布尺寸。通常在窗口 resize 时调用，Five 会自动监听 resize，但在某些布局变化场景下可能需要手动调用。
@@ -164,7 +233,7 @@ five.updateCameraWithKeyframes(keyframes, 2000).then(() => {
     1. **状态同步**：相机姿态已通过动画过渡到目标状态（`stateSynced` 为 true）。
     2. **模型加载**：如果是 Floorplan/Topview/Mapview/Model 模态，需等待模型加载完成 (`modelScene.loaded`)。
     3. **瓦片加载**：如果是 Panorama 模态且传入了 `{ tile: true }`，需等待当前视角的瓦片加载完成。
-- **`setState(state: Partial<State>, options?: ChangeStateOptions)`**: 变更当前状态（如点位、视角）。详见 [state.md](./state.md)。
+- **`setState(state: Partial<State>, immediately?: boolean, userAction?: boolean)`**: 变更当前状态（如点位、视角）。详见 [state.md](./state.md)。
 - **`on(event, callback)` / `off(event, callback)`**: 事件监听。详见 [event.md](./event.md)。
 
 ## Related
@@ -180,5 +249,5 @@ five.updateCameraWithKeyframes(keyframes, 2000).then(() => {
 ---
 
 ```yaml
-tags: [five, initialization, core, instance, lifecycle]
+tags: [five, initialization, core, instance, lifecycle, forceWebGL, webgl2, xr, webxr]
 ```

package/ai_guides/features/gesture.md

@@ -12,7 +12,7 @@
 所有手势事件的回调参数均为 `GestureEvent` 类型：
 
 ```typescript
-import { State } from "@realsee/five";
+import { State } from "@realsee/five-webgpu";
 import * as THREE from "three/webgpu";
 
 interface GestureEvent {
@@ -44,7 +44,7 @@ interface GestureEvent {
 
 Five 的手势系统基于 Hammer.js 封装，主要包含以下几种手势：
 
-*   **gesture.create**: 所有事件创建时。
+*   **gesture.fire**: 任意事件被触发。
 *   **gesture.pan**: 拖拽/平移。
 *   **gesture.pinch**: 双指缩放。
 *   **gesture.tap**: 点击。
@@ -92,7 +92,7 @@ five.on("gesture.tap", (event) => {
 
 ```typescript
 import * as THREE from "three/webgpu";
-import { Five } from "@realsee/five";
+import { Five } from "@realsee/five-webgpu";
 
 const five = new Five();
 

package/ai_guides/features/get-screen-pixels.md

@@ -76,7 +76,7 @@ five.getPixels(
 
 ```typescript
 import * as THREE from 'three';
-import { Five } from '@realsee/five';
+import { Five } from '@realsee/five-webgpu';
 
 // 假设有一个用于显示的 canvas
 const magnifierCanvas = document.getElementById('magnifier-canvas') as HTMLCanvasElement;