@realsee/vr-cli 0.1.3

package/NOTICE.md

@@ -0,0 +1,7 @@
+# Distribution notice
+
+`@realsee/vr-cli` is distributed as developer tooling for creating authorized Realsee spatial applications. The package does not bundle or redistribute `@realsee/five`, `@realsee/dnalogel`, `@realsee/vapor`, their documentation bodies or source code, customer Work data, credentials, access tokens, or production assets. Generated projects declare SDK packages as npm dependencies and install them separately.
+
+Use of Realsee SDK packages, Open Platform services, brands, customer data, and generated integrations remains subject to the applicable agreements, account permissions, and data authorization. Public availability of this CLI does not grant additional rights to those SDKs, services, or resources.
+
+The CLI package is licensed under `SEE LICENSE IN TERMS.txt`; review [TERMS.txt](./TERMS.txt) before use, modification, redistribution, or deployment.

package/README.md

@@ -0,0 +1,216 @@
+# @realsee/vr-cli
+
+`@realsee/vr-cli` 是面向 Realsee 空间 Viewer 应用开发的命令行工程工具，用于创建和检查标准化 TypeScript Viewer 项目，并为自动化流程提供空间能力策略。
+
+## 核心能力
+
+- 通过 `create` 创建 Viewer 项目并安装依赖。
+- 通过 `doctor` 检查开发环境、项目结构、依赖配置和关键实现约束。
+- 通过 `policy` 输出版本化的空间能力策略。
+
+## 安装与执行
+
+CLI 支持临时执行和全局安装，两种方式使用相同的 `vr-cli` 命令与参数。
+
+### 临时执行
+
+无需全局安装即可创建项目：
+
+```bash
+npm exec --yes \
+  --package=@realsee/vr-cli@latest \
+  -- vr-cli create ./my-vrapp
+```
+
+### 全局安装
+
+安装后可直接执行 `vr-cli`：
+
+```bash
+npm install --global @realsee/vr-cli@latest
+vr-cli create ./my-vrapp
+```
+
+更新全局安装：
+
+```bash
+npm install --global @realsee/vr-cli@latest
+```
+
+CI 和自动化生成流程应使用明确版本。当前版本示例：
+
+```bash
+npm exec --yes \
+  --package=@realsee/vr-cli@0.1.3 \
+  -- vr-cli create ./my-vrapp --no-install
+
+cd ./my-vrapp
+npm ci
+npm run check
+npm run build
+```
+
+## 快速开始
+
+`create` 默认在生成目录中执行 `npm ci`。项目创建完成后进入目录并准备环境配置：
+
+```bash
+cd ./my-vrapp
+cp .env.example .env.development
+```
+
+编辑 `.env.development`：
+
+```dotenv
+REALSEE_GATEWAY_ENDPOINT=https://app-gateway.realsee.cn
+REALSEE_GATEWAY_APP_KEY=<your-app-key>
+REALSEE_GATEWAY_APP_SECRET=<your-app-secret>
+```
+
+启动开发环境：
+
+```bash
+npm run dev
+```
+
+访问以下地址，并将 `{resourceCode}` 替换为当前开放平台应用有权访问的资源编码：
+
+```text
+http://127.0.0.1:8087/{resourceCode}
+```
+
+开发环境由 Vite 提供浏览器应用，并将 `/api` 请求代理至 Fastify BFF。使用 `--no-install` 创建项目时，需要先在生成目录中执行 `npm ci`。
+
+## CLI 参考
+
+以下示例使用全局安装后的命令形式。临时执行时，可通过 `npm exec --yes --package=@realsee/vr-cli@<version> --` 调用相同命令。
+
+### `create`
+
+创建 Viewer 项目：
+
+```bash
+vr-cli create <directory> [options]
+```
+
+| 参数 | 说明 |
+| --- | --- |
+| `--name <npm-name>` | 指定生成项目的 npm 包名 |
+| `--preset viewer` | 使用 `viewer` 项目模板 |
+| `--no-install` | 生成文件后不执行 `npm ci` |
+
+目标目录必须不存在或为空。未指定 `--name` 时，CLI 根据目标目录名称生成 npm 包名。
+
+### `doctor`
+
+检查生成项目：
+
+```bash
+vr-cli doctor ./my-vrapp
+vr-cli doctor ./my-vrapp --json
+```
+
+`doctor` 检查运行环境、项目结构、依赖配置和生成文件。`--json` 用于 CI 或其他自动化系统。
+
+### `policy`
+
+输出空间能力策略：
+
+```bash
+vr-cli policy
+vr-cli policy --json
+```
+
+`--json` 输出适用于自动化处理。
+
+### 其他命令
+
+```bash
+vr-cli --version
+vr-cli help
+```
+
+## 生成项目
+
+### 目录结构
+
+```text
+浏览器应用
+├── src/app                         应用组合
+├── src/features                    Viewer 功能模块
+├── src/ui                          Vapor / React 界面
+└── src/vr
+    ├── five                        Five 初始化与生命周期
+    ├── plugins                     dnalogel 与自定义插件基础设施
+    └── work                        Work 数据访问
+
+服务端
+├── server/realsee-open-api.ts      Access Token 与 OpenAPI 请求
+├── server/work-service.ts          Work 服务
+├── server/work-route.ts            同源 HTTP 接口
+└── server/index.ts                 Fastify 服务入口
+```
+
+项目包含以下基础实现：
+
+- 加载 Realsee Work 并初始化 Five Viewer。
+- 切换 Panorama、Mapview 和 Topview 模式。
+- 接入 PanoTag 与 ModelFloorplan 功能。
+- 使用 Vapor/React 构建 Viewer 界面。
+- 通过同源 Fastify BFF 调用 Realsee OpenAPI。
+- 提供 TypeScript、ESLint、Prettier、Vite 和项目检查配置。
+
+## 生成项目核心依赖与版本要求
+
+| 依赖 | 版本要求 | 用途 |
+| --- | --- | --- |
+| Node.js | `>=22.18.0`，推荐 `22.23.2` | CLI 与生成项目运行环境 |
+| npm | `>=11.19.0` | 依赖安装与项目脚本 |
+| `@realsee/five` | `>=6.8.9` | 空间 Viewer 运行时 |
+| `@realsee/dnalogel` | `>=3.81.2` | Five 插件能力 |
+| `@realsee/vapor` | `>=0.2.12` | Viewer 界面组件 |
+| `three` | `0.117.1` | Three.js 运行时 |
+| `react` / `react-dom` | `>=18.3.1` | 浏览器界面运行时 |
+| `fastify` | `>=5.12.1` | 服务端应用运行时 |
+
+## 常见问题
+
+### Node.js 版本不满足要求
+
+确认当前版本：
+
+```bash
+node --version
+```
+
+在支持 nvm 的环境中，可使用生成项目固定的版本：
+
+```bash
+nvm use
+```
+
+### 开发服务提示凭据未配置
+
+确认已从 `.env.example` 创建 `.env.development`，并填写 `REALSEE_GATEWAY_APP_KEY` 与 `REALSEE_GATEWAY_APP_SECRET`。修改环境变量后重新启动开发服务。
+
+### Work 加载失败
+
+依次确认：
+
+1. URL 中的 `resourceCode` 正确；
+2. 开放平台应用有权访问对应资源；
+3. `REALSEE_GATEWAY_ENDPOINT` 配置正确；
+4. BFF 日志中的上游 HTTP 状态符合预期；
+5. 部署环境已配置必要的身份认证和授权。
+
+## 版本与分发
+
+- npm 包：`@realsee/vr-cli`。
+- 可执行命令：`vr-cli`。
+- 当前版本：`0.1.3`。
+
+`0.x` 版本可能调整模板、检查规则和生成内容。生产环境与 CI 应固定 CLI 版本，并在升级时审查生成差异。
+
+## 许可证
+
+本包的许可证声明为 `SEE LICENSE IN TERMS.txt`，完整条款见 [TERMS.txt](./TERMS.txt)。Realsee SDK、开放平台服务、品牌、客户数据及第三方资源的使用应符合相应协议与授权范围。

package/TERMS.txt

@@ -0,0 +1,54 @@
+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.

package/agent-assets/AGENTS.md

@@ -0,0 +1,113 @@
+# Realsee spatial Viewer agent instructions
+
+This project was generated by `@realsee/vr-cli` {{TOOL_VERSION}}.
+
+## Commands
+
+```bash
+npm ci
+npm run dev
+npm run typecheck
+npm run lint
+npm run format:check
+npm run check
+npm run build
+npm start
+node .agents/skills/realsee-vr-app/scripts/verify-project.mjs .
+```
+
+Use Node.js 22.23.2 from `.nvmrc`/`.node-version`, with `engines.node` set to the oldest supported runtime floor `>=22.18.0`; the generated BFF relies on native TypeScript type stripping being enabled by default. Use npm 11.19.0 from `packageManager`. Keep `package-lock.json` authoritative, use `npm ci` for clean installs, and do not bypass `typecheck`, ESLint or Prettier.
+
+Every direct dependency except `three` must use an open `>=` minimum no lower than the generated baseline. Use `npm update` to move the lockfile to newer releases, or `npm install <pkg>@latest` to raise one declared minimum; then run `npm run check` and `npm run build`. Keep `package-lock.json` authoritative and use `npm ci` for clean installs. `three` is the only hard-locked dependency and must stay exactly at the generated version because Five targets that Three release. Updating Five, dnalogel or Vapor requires re-checking the versioned contract fixtures and validating spatial behavior in a browser. Never run `npm audit fix --force`.
+
+## TypeScript rules
+
+- Both the browser app and the Fastify BFF are TypeScript. Do not add `.js`/`.mjs` runtime modules to `src/` or `server/`.
+- `tsconfig.json` covers browser sources plus `shared/`; `tsconfig.server.json` covers `server/` plus `shared/`. Keep new server files inside its `include`.
+- The server runs through Node native type stripping, so `server/` must stay erasable-only: no `enum`, `namespace`, constructor parameter properties or decorator emit. `erasableSyntaxOnly` enforces this.
+- Server relative imports must keep the explicit `.ts` extension, as Node resolves the real file.
+- Model upstream and browser payloads as `unknown`/`Record<string, unknown>` and narrow them; do not cast untrusted Work data straight to a domain type.
+- Keep the `WorkEnvelope`, `WorkService` and `WorkDetailClient` contracts in `server/types.ts` when replacing the adapter.
+- Lint is type-aware and `--max-warnings=0`. Do not silence rules with broad `eslint-disable`; fix types or narrow the scope with justification.
+
+## Architecture
+
+- Five is the complete spatial runtime; dnalogel is a preset plugin collection, and applications may define additional plugins directly on Five.
+- Three.js 0.117.1 is the shared low-level 3D foundation used through Five's public ownership boundaries.
+- `src/vr/five` exposes native, version-bound Five capabilities; `src/vr/plugins` provides vendor-neutral infrastructure for dnalogel presets and custom Five plugins; `src/vr/work` owns the Work and explicit preset-data boundary.
+- `src/features` composes focused spatial features without hiding the native Five instance.
+- Vapor is only the React DOM component layer in `src/ui`, positioned above the native Five canvas.
+
+## Runtime rules
+
+- Read `.agents/skills/realsee-vr-app/SKILL.md` before changing Work, Five, dnalogel, Vapor, VR spatial annotations or spatial product behavior.
+- External projects do not include Five/dnalogel repository source. For a user-requested spatial feature, first decide whether it needs persisted data. Data-backed features (tags, tours, annotations, routes, floorplans) follow the prompt → OpenAPI/BFF → SDK → cleanup flow in `.agents/skills/realsee-vr-app/references/dnalogel-openapi-recipes.md`. Runtime-only features with no upstream data (screenshot, magnifier, clipping/section view, pano colour grading, camera animation, point picking, custom Three visuals) skip the BFF entirely and follow the native-capability flow in `.agents/skills/realsee-vr-app/references/five-api-capabilities.md`. Never ask for SDK source or repository examples.
+- For a new feature family, an SDK/OpenAPI upgrade or a generator release, also read `.agents/skills/realsee-vr-app/references/continuous-improvement.md`; keep policy, adapter, template, verifier and a sanitized regression fixture aligned.
+- Read `.agents/skills/realsee-image-resources/SKILL.md` before changing image sources, CDN hosts, 数据万象 operations, Five `defaultImageURLTransform`, CORS behavior or Three texture loading.
+- Read `.agents/skills/threejs-r117-five/SKILL.md` before changing Three geometry, materials, lighting, textures, animation, loaders, shaders, passes, picking or renderer integration.
+- Image resources use approved Realsee CDN domains only; never use `ljcdn.com`, `lianjia.com` or their subdomains.
+- Prefer Five `defaultImageURLTransform` over hand-built 数据万象 query strings when its installed contract satisfies the request.
+- URL transformation does not grant CORS access.
+- Ordinary images use the deployment's approved image-4 host.
+- Feature media from OpenAPI or Work data is displayed through a derived sized variant, never the original: pass ordinary images through the reviewed `defaultImageURLTransform` adapter with a bounded `size`, and do not hand a full-resolution URL to a tag, tour, card or DOM thumbnail.
+- Installed package declarations are authoritative. For Five, start at `node_modules/@realsee/five/AI_CONTEXT.md` and `llms.txt`; for dnalogel, start at its installed `package.json`/`exports`, `libs/index.d.ts`, then the selected plugin declaration barrel; for Three, start at `node_modules/three/src/Three.d.ts` and the exact `examples/jsm` declaration.
+- When the user explicitly requests Vapor components, use matching named exports from the installed `@realsee/vapor` package for every applicable DOM control; importing `Vapor` or `vapor.css` alone does not satisfy the request.
+- Do not replace an available Vapor component with raw HTML or a locally styled replica; use raw DOM only for semantics or capabilities absent from the installed Vapor declarations, and record that gap.
+- Before implementing Vapor UI, read `node_modules/@realsee/vapor/AI_CONTEXT.md`, `llms.txt`, `vapor.d.ts`, and the selected component declarations; never invent component names or props.
+- Use the installed `ai_guides` only for component discovery and composition recipes; the target project's root `vapor.d.ts` and selected component declarations are the API contract, and conflicts resolve in favor of installed declarations.
+- Keep the Five canvas in its dedicated sibling host outside `Vapor`; Vapor layout components own DOM chrome only, even when an external recipe nests a placeholder VR component inside a stack.
+- Three stays locked at the generated version because Five targets that release; never install a second Three instance. Five, dnalogel and Vapor may be updated deliberately, keeping their versions consistent with each other and validated in a browser.
+- Three extension imports must use `three/examples/jsm/.../*.js`. Do not use modern `three/addons`, color-space, WebGPU/TSL or other APIs absent from r117.
+- Use `new Five(...)` from `@realsee/five`; never import the delayed `@realsee/five/react` adapter, `createFiveProvider`, `FiveCanvas` or its hooks.
+- Keep the native Five instance available; do not replace complete SDK access with a narrow local facade.
+- Spatial capability resolution order: installed @realsee/dnalogel preset -> native Five -> Three.js.
+- For every spatial, VR or 3D feature request, inspect the installed dnalogel exports and the candidate plugin's exact declarations before designing a custom Five/Three implementation. Use a focused native Five fallback only when no preset matches or the matching preset has a documented capability gap; add Three only through Five's ownership boundaries.
+- VR spatial tag (spatial annotation) is the umbrella concept. It may contain text, images, video, audio, links, models, virtual/VR content, media/model screens, room/item labels or custom content.
+- Classify content, renderer, anchor, and lifecycle/data ownership before selecting a preset. Classification distinguishes tags/hotspots/anchors from model annotations and prevents unrelated spatial content from being forced into one plugin.
+- Tags, hotspots, and anchors default to PanoTagPlugin with GET /open/v3/hot/list.
+- Tours use Five State snapshots with GET /open/v3/observerpicture/search.
+- Model annotations default to ModelMakerPlugin with GET /open/v3/annotation/search.
+- Routes use GuideLinePlugin for rendering and shape-selected CruisePlugin or MovePlugin playback with GET /open/v3/route/search.
+- Tour adapters read `data.list`, map each validated record to `Partial<State>` with the active `workCode`, and never cast an observer-picture record directly to `State`.
+- Model annotation adapters read `data.list`, validate `object_data` for `box`, `triangles` or `prism`, and pass `{ list }` to ModelMaker only for a model-capable Work.
+- dnalogel 3.81.2 route playback is shape-selected: a validated pano group uses `CruisePlugin` `{ panoIndexList }`, while a validated model-space curve uses `MovePlugin` `{ path }`; `GuideLinePlugin` renders route geometry and is not playback input.
+- `CruisePlugin` accepts exactly one of `panoIndexList` or `keyframes`; its installed union has no type discriminator.
+- OpenAPI route records are never passed raw: rename validated style config only for GuideLine `lines`, and never pass GuideLine `PathItem` arrays or style objects to `CruisePlugin` or `MovePlugin`.
+- If a source record contains both `pano_group` and `path`, the route adapter must choose product semantics explicitly and pass only the selected geometry branch to GuideLine.
+- `GuideLinePlugin.load` waits for model readiness; `CruisePlugin` waits only for Work and observers; `MovePlugin` enters Model and awaits Five readiness when playback starts.
+- Reject empty routes, unknown pano indexes, unsupported curves, non-finite coordinates, timing or speed, and ambiguous multi-segment Move paths before plugin load.
+- Route cleanup pauses the owned playback controller before hook removal and disposal; `clear` belongs to GuideLine, is not a public Cruise operation, and GuideLine disposal does not own an external or embedded Cruise controller automatically.
+- Do not invent `RoutePlugin`, `PanoRove`, `stop()`, or a universal route controller; use only the exports and methods declared by the installed package.
+- Feature API, schema, or plugin failures disable only the affected feature; keep the base Viewer usable and never runtime-fallback to raw data or a custom Three implementation.
+- Scope tour, ModelMaker, GuideLine, Cruise and Move work to an active `workCode`/generation token; abort fetches, ignore stale continuations, pause the owned playback controller, remove hooks, clear GuideLine data, wait for pending loads, then let identity-safe unregister dispose each registered controller exactly once before `five.dispose()`.
+- Fetch OpenAPI-backed feature data only through a typed server/BFF adapter, validate its response, and adapt it to the exact installed SDK data type before loading the plugin or applying a Five State. Do not call these authenticated APIs from the browser.
+- Normalize optional OpenAPI configuration fields such as `version`, `globalConfig` and `contentTypeConfig`: treat `null` as absent before validating the installed SDK contract.
+- Load ordinary PanoTag point/plane tags after `five.load` without waiting for `five.model.loaded`; gate only model-dependent tag content or anchors on model readiness.
+- SDK-shaped custom data requires an explicit developer opt-out from Open Platform data.
+- PanoTagPlugin is the default implementation for requests classified as tags, hotspots or anchors, but it is not a synonym for every spatial annotation. Never infer PanoTag from a `tags` field, Panorama mode, or a screenshot; only an explicit typed contract such as `presetData.panoTagList` or a validated `/open/v3/hot/list` adapter may feed it.
+- For a virtual screen, select by behavior: `ModelTVVideoPlugin`, PanoTag `MediaPlane`/`MediaModel`, `CSS3DRenderPlugin`, `PanoVideoPlugin`, or—only when no preset satisfies the requirement—a focused custom Five/Three plugin. Do not invent `VirtualScreenPlugin`.
+- Before implementing an allowed custom Five/Three fallback, inspect `src/vr/plugins/examples/FeatureOwnedMeshPlugin.ts`. It is opt-in and the default App must not import or register it; adapt it from a focused feature, pair registration with `SpatialRuntimeLifetime.own()` and `plugins.unregister(name, expected)`, and dispose only feature-owned Three resources.
+- Add custom Three objects to `five.scene`, but do not replace Five's scene, camera, renderer, canvas, render loop or composer. Use Five State/camera and pass APIs.
+- `Mapview` is the three-dimensional overview; `Topview` is the map/floor structure.
+- Never directly edit `work.json`, downloaded Work, or customer Work. The default Viewer is read-only; persistence needs an authoritative editor/API/BFF/source contract and user confirmation. Otherwise propose a typed patch or keep the feature runtime-only.
+- Use only Work-provided, approved API/CDN or user-authorized media/model assets; never introduce an unrelated third-party URL.
+- Resolve Work identity from `/{resourceCode}` and call only same-origin `/api/work/{resourceCode}`. Never add `VITE_WORK_URL`, a local `/work.json` fallback or browser-side OpenAPI credentials.
+- The generated Fastify BFF is an example adapter: `realsee-open-api.ts` owns token exchange/cache and upstream calls, `work-service.ts` owns the framework-neutral envelope, and `work-route.ts` owns HTTP. Preserve `GET /api/work/{resourceCode}` when replacing it with Go or another backend.
+- The generated project has one `.env.example`; only the server reads `REALSEE_GATEWAY_ENDPOINT`, `REALSEE_GATEWAY_APP_KEY` and `REALSEE_GATEWAY_APP_SECRET`. `APP_ID` and `REALSEE_SOURCE` are optional deployment metadata.
+- Keep the real `REALSEE_GATEWAY_APP_SECRET`, AK/SK and token in the BFF environment or secret manager. They must not enter `VITE_*`, `src/`, Vite `define/envPrefix`, browser requests, logs or bundles.
+- AK/SK authorize the BFF's upstream access. If an internet-facing deployment requires caller or tenant authorization, enforce it before the Work route; never satisfy that requirement by exposing AK/SK to the browser.
+- Construct and append Five only after its host has positive dimensions; use `five.refresh` for later positive resizes.
+- Treat each dnalogel preset or custom Five plugin by its concrete installed/local type; pair hooks, registrations, requests, loops, media and owned Three resources with cleanup.
+- Stop features, wait serialized native work, drain dynamic plugins, call `five.dispose()`, then remove the unmanaged canvas; keep StrictMode/HMR remounts ownership-safe.
+- Transparent Vapor/DOM roots must not intercept the native Five canvas; only visible controls restore pointer events.
+
+## Validation
+
+Run type checking and production build. For spatial changes, validate at `http://127.0.0.1:8087/{resourceCode}` in a real browser; the template uses local IPv4 loopback and non-privileged port 8087, not privileged port 517. Inspect Five state/readiness, native surface dimensions, spatial-tag anchors/renderers, Three coordinates/resources, plugin lifecycle, layer rectangles and hit targets rather than relying only on screenshots.
+
+## Model floorplan contract
+
+- Floorplans default to ModelFloorplanPlugin with GET /open/v3/floorplan/plugins.
+- `data.format_floorplan_url`, not `format_model_url`, resolves to the preferred `{ version, data: FloorplanServerData }` plugin input.
+- Expose `capabilities.modelFloorplan` only after validating the complete wrapper and nested floorplan shape; missing, empty, malformed or failed floorplan data must leave the base Viewer usable.
+- The complete model floorplan contract lives in `.agents/skills/realsee-vr-app/references/dnalogel-api-capabilities.md`: tab naming, `autoShowEnable`/opacity ownership, `appendTo` mounting, multi-floor authority and cleanup order.

package/agent-assets/adapters/.cursor/rules/realsee-vr.mdc

@@ -0,0 +1,7 @@
+---
+description: Realsee native spatial runtime, VR spatial annotations, Three r117 foundation and Vapor DOM rules
+globs: ["src/**/*.{ts,tsx}"]
+alwaysApply: false
+---
+
+Follow `AGENTS.md`. Read `.agents/skills/realsee-vr-app/SKILL.md` and its self-contained `references/dnalogel-openapi-recipes.md` for Five/dnalogel/Vapor, prompt-to-OpenAPI implementation and VR spatial annotation changes; do not require SDK repository source. Read `.agents/skills/realsee-image-resources/SKILL.md` for image sources, CDN hosts, 数据万象, `defaultImageURLTransform` or CORS requests, and `.agents/skills/threejs-r117-five/SKILL.md` for Three geometry, materials, loaders, shaders, passes or picking. Classify spatial-tag content, renderer, anchor and lifecycle/data ownership before selecting a preset; PanoTag is not the default meaning of “tag”. Preserve Five ownership and the r117 API boundary.

package/agent-assets/adapters/.github/copilot-instructions.md

@@ -0,0 +1 @@
+Follow `AGENTS.md`. Route Five/dnalogel/Vapor, prompt-to-OpenAPI implementation and VR spatial annotation work through `.agents/skills/realsee-vr-app/SKILL.md` plus its self-contained `references/dnalogel-openapi-recipes.md`; do not require SDK repository source. Route image sources/CDN/数据万象/`defaultImageURLTransform`/CORS work through `.agents/skills/realsee-image-resources/SKILL.md`, and Three geometry/material/loader/shader/picking work through `.agents/skills/threejs-r117-five/SKILL.md`. Treat spatial tag as the umbrella concept; classify content, renderer, anchor and lifecycle/data ownership before selecting a preset, and never infer PanoTag from a `tags` field, Panorama mode or a screenshot. Preserve Five ownership and the pinned Three r117 API; do not use `@realsee/five/react`.

package/agent-assets/adapters/.kiro/steering/realsee-vr.md

@@ -0,0 +1,6 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "src/**/*.{ts,tsx}"
+---
+
+Follow `AGENTS.md`. Read `.agents/skills/realsee-vr-app/SKILL.md` and its self-contained `references/dnalogel-openapi-recipes.md` for Five/dnalogel/Vapor, prompt-to-OpenAPI implementation and VR spatial annotation work; do not require SDK repository source. Read `.agents/skills/realsee-image-resources/SKILL.md` for image sources, CDN hosts, 数据万象, `defaultImageURLTransform` or CORS work, and `.agents/skills/threejs-r117-five/SKILL.md` for Three.js work inside Five. Treat spatial tag as the umbrella concept; classify content, renderer, anchor and lifecycle/data ownership before selecting a preset, and never infer PanoTag from a `tags` field, Panorama mode or a screenshot. Preserve native Five ownership, the Three r117 API boundary and DOM-only Vapor; do not use `@realsee/five/react`.

package/agent-assets/adapters/CLAUDE.md

@@ -0,0 +1,3 @@
+# Realsee spatial Viewer project
+
+Follow `AGENTS.md`. Use `.agents/skills/realsee-vr-app/SKILL.md` and its self-contained `references/dnalogel-openapi-recipes.md` for the native Five runtime, user-prompt-to-OpenAPI implementation, VR spatial annotations, dnalogel presets and custom Five plugin infrastructure; do not require SDK repository source. Use `.agents/skills/realsee-image-resources/SKILL.md` for image sources, CDN hosts, 数据万象, `defaultImageURLTransform` and CORS, and `.agents/skills/threejs-r117-five/SKILL.md` for version-bound Three.js foundations inside Five. Treat VR spatial tag as the umbrella concept and classify content, renderer, anchor and lifecycle/data ownership before selecting a preset; never infer PanoTag from a `tags` field, Panorama mode or a screenshot. Vapor is DOM-only. Do not use `@realsee/five/react` or modern Three APIs absent from r117.

package/bin/vr-cli.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../dist/cli.mjs'
+await main(process.argv.slice(2))