@realsee/vr-cli 0.1.3

package/skills/threejs-r117-five/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: threejs-r117-five
+description: Use Three.js 0.117.1 core capabilities safely in Realsee Five 6.8.9 applications. Use for Three math, Object3D, geometry, materials, lighting, textures, animation, loaders, GLSL shaders, Five post-processing passes, raycasting, resource cleanup, performance, and version migration. This is a portable Agent Skill, independent of any specific coding agent.
+---
+
+# Three.js r117 foundation for Five
+
+Five is built on Three.js, so its public scene, camera, renderer, coordinate, raycasting and pass APIs interoperate with the single pinned `three@0.117.1` instance. This does not transfer ownership of Five's renderer pipeline to application code.
+
+## 1. Confirm the compatibility contract
+
+Before writing code, verify the compatibility declarations and installed resolutions:
+
+- `@realsee/five`: declared as `>=6.8.9`; inspect the lockfile and installed package for the actual version.
+- `three`: declared and resolved exactly as `0.117.1`.
+
+Do not install another Three version or a separate modern `@types/three`. The installed `three/src/Three.d.ts`, `three/examples/jsm/**/*.d.ts` and Five declarations are authoritative. If Five has moved above the generated baseline, re-check its versioned contract fixtures and browser behavior while keeping the single Three r117 instance.
+
+## 2. Classify the task and rendering mode
+
+Choose the capability route before selecting APIs:
+
+1. **Five feature**: add custom objects, geometry, materials, textures, animation, loaders, shaders, lights, picking or a Five pass to the existing Five runtime. Read [references/five-ownership.md](references/five-ownership.md).
+2. **Version lookup**: map a modern Three example to r117. Read [references/r117-version-guards.md](references/r117-version-guards.md) before adapting it.
+3. **Capability design**: choose among the ten supported knowledge domains. Read [references/r117-capabilities.md](references/r117-capabilities.md).
+
+For image provenance, approved Realsee CDN selection, Five `defaultImageURLTransform`, 数据万象 or CORS, first read the sibling [realsee-image-resources Skill](../realsee-image-resources/SKILL.md). This Skill still owns the pinned Three r117 texture API and application texture ownership rules.
+
+Then select one explicit rendering ownership mode:
+
+1. **Default internal renderer**: Five owns the renderer, canvas, viewport, render scheduling and composer. Application features add owned objects or passes through Five's public APIs.
+2. **Application-owned external renderer/shared viewport**: pass the renderer into `FiveInitArgs` at construction and coordinate canvas, sizing, pixel ratio, viewport/scissor, scheduling and final renderer disposal in one application owner. The owner may render its own Scene/Camera in a controlled viewport, but must not redraw `five.scene` outside Five or wrap Five in a second composer.
+3. **Independent/offscreen Three scene**: a separate Scene/Camera/Renderer is allowed when it does not render Five-owned objects or compete for Five's visible canvas lifecycle.
+
+For generated-project vibe coding in the default mode, inspect `src/vr/plugins/examples/FeatureOwnedMeshPlugin.ts` before adding a custom Three object or plugin. Prefer its opt-in factory/registry pattern and idempotent feature-owned cleanup. Adapt it in a focused feature; never auto-enable the reference from the default App.
+
+## 3. Preserve Five ownership
+
+- Add custom `Object3D` trees to `five.scene`; do not replace `five.scene` or mutate `five.modelScene` internals.
+- Use `five.camera` for projection and raycasting, but use Five State/camera methods for motion. Do not attach OrbitControls to it.
+- In the default mode, let Five own its renderer, canvas, size, viewport, RAF and composer. In external-renderer mode, keep those responsibilities in the single declared application owner.
+- Use `five.needsRender = true` for changed custom visuals under on-demand rendering.
+- Integrate Five post-processing through public `five.addPass`, `insertPass` and `removePass`; do not create a second EffectComposer around `five.renderer`.
+- Prefer Five gesture events and model intersection APIs for Work/model picking; use native Raycaster directly for application-owned custom objects.
+
+## 4. Use r117 APIs, not current Three examples
+
+Core imports come from `three`. Extension modules use `three/examples/jsm/.../*.js`. The package has no `three/addons` export.
+
+Use r117 terminology such as `texture.encoding`, `renderer.outputEncoding`, `THREE.sRGBEncoding`, `TextGeometry`'s `height`, `Matrix4.getInverse`, and explicit `*BufferGeometry` where BufferGeometry behavior matters. Reject modern-only color-space, WebGPU, TSL and PBR optical APIs unless the pinned matrix is upgraded and re-audited.
+
+## 5. Own resources and time
+
+Every feature owns what it creates:
+
+- remove its Object3D root from `five.scene`;
+- stop and uncache AnimationMixer actions;
+- remove Five/DOM event subscriptions;
+- stop media and request/animation work;
+- dispose geometries, materials, textures, render targets, controls, loaders with explicit worker disposal, and custom passes where supported;
+- do not dispose Work/model resources or the Five renderer that the feature does not own.
+
+Run long-lived work through the generated spatial lifetime so StrictMode, HMR and Five teardown wait for it safely.
+
+## 6. Validate
+
+Run type checking and production build, then validate in a real browser. Inspect coordinates, camera mode transitions, draw order, pointer routing, shader compilation, GPU resources and remount cleanup. A screenshot alone cannot prove raycasting, ownership or disposal.
+
+## Provenance
+
+The ten-domain routing model was inspired by [CloudAI-X/threejs-skills](https://github.com/CloudAI-X/threejs-skills). This skill is independently rewritten against the locally installed r117/Five declarations; it does not copy the upstream r160+ examples or assume their APIs are compatible.

package/skills/threejs-r117-five/references/five-ownership.md

@@ -0,0 +1,70 @@
+# Five and Three ownership boundary
+
+Five exposes Three-compatible objects, but application access does not imply application ownership.
+
+## Scene and objects
+
+`five.scene` is the public destination for application-owned custom `Object3D` trees. Add meshes, groups, lines, points, sprites, instanced meshes, helpers and intentional feature lights there. Keep one root per feature so teardown can remove it deterministically.
+
+Do not replace `five.scene`. Do not mutate or dispose `five.modelScene`, Work tiles, internal panorama meshes or model materials as though they were feature-owned. Use Five model/layer/parameter APIs for Work content.
+
+When a custom object changes under on-demand rendering, set its supported render flag or `five.needsRender = true`.
+
+## Camera and coordinates
+
+`five.camera` is a Five camera that participates in Mode and State synchronization. It can be passed to Three projection, frustum and Raycaster math. Motion belongs to `five.setState`, `changeMode`, `moveToPano`, `updateCamera` or `updateCameraWithKeyframes`.
+
+Do not replace the camera, attach Orbit/Map/FirstPerson controls, or continuously write position/quaternion/projection outside Five's controller.
+
+Keep coordinate spaces explicit:
+
+- DOM client coordinates;
+- canvas-relative NDC;
+- Five local/world coordinates;
+- Work ENU/ECEF coordinates;
+- loader model coordinates and up-axis.
+
+Use Five/ViewLayer coordinate conversion APIs where Work identity matters. Validate imported model orientation in a real Work; do not assume every source uses the same up-axis.
+
+## Renderer, canvas and viewport
+
+Three integration has three supported ownership modes:
+
+1. **Default internal renderer**: `new Five(initArgs)` creates and owns its WebGL renderer. `appendTo`, `refresh`, `getElement` and `dispose` define the generated canvas lifecycle.
+2. **Application-owned external renderer/shared viewport**: pass `FiveInitArgs.renderer` at construction and use the public `viewport`/`setViewport` contract. One application owner manages DOM mounting, dimensions, pixel ratio, viewport/scissor state, shared render timing and final renderer release.
+3. **Independent/offscreen scene**: a separate Three Scene/Camera/Renderer may run in isolation without rendering Five-owned objects or competing for Five's visible surface.
+
+In the default mode, application features must not replace `five.renderer`, call `renderer.setSize`, dispose its context, move the Five canvas into React reconciliation, or call `renderer.render(five.scene, five.camera)` from another RAF.
+
+An external-renderer owner may render its own Scene/Camera in a controlled time slot and viewport. It must restore required viewport/scissor state, must not bypass Five to redraw `five.scene`, and must not wrap Five's renderer/scene in a second composer. The public declarations do not guarantee whether `five.dispose()` detaches or clears an externally supplied canvas, so never depend on that side effect; stop Five first, then let the application owner perform final renderer/canvas cleanup.
+
+## Time and animation
+
+Five owns visible render scheduling in the default mode. With an external renderer, the single application owner coordinates shared timing without a second RAF racing Five. Use Five render events, a feature task, or the reviewed external-owner schedule to advance Three animation state. Continuous animation must request rendering and be stoppable.
+
+For an `AnimationMixer`, teardown normally includes stopping actions, uncaching clips/roots, removing the object root, and disposing owned geometry/material/texture resources. Never dispose shared Work resources.
+
+## Post-processing
+
+Five owns its composer and G-buffer pipeline in both internal- and external-renderer modes. Use public Five `Pass`/`FivePass` contracts and `five.addPass`, `insertPass`, `removePass`. Always remove an installed pass at feature teardown. Call `dispose()` only when the concrete declared pass supports it and the feature owns that pass; separately release feature-owned materials, textures and render targets.
+
+Do not wrap `five.renderer` or `five.scene` in `three/examples/jsm/postprocessing/EffectComposer`. An isolated application scene may have its own reviewed pipeline only when it remains outside Five's scene/composer lifecycle.
+
+## Picking and interaction
+
+For gesture-driven picking, prefer Five pointer data such as `event.center.raycaster` and `event.center.coords`; this preserves Five's input and viewport transforms. Use `five.modelScene.intersectRaycaster` when hits must aggregate across loaded Work/models. Use `five.model.intersectRaycaster` only when intentionally targeting the active single model. For application-owned custom objects, use the r117 Raycaster against the feature root only.
+
+When raw DOM input must be converted manually, begin with the actual Five canvas rectangle and then account for the `five.viewport` subregion before mapping to NDC. Using the whole canvas dimensions alone is incorrect for an external renderer or shared viewport. Pair every DOM or Five event subscription with its returned disposer and avoid transparent DOM overlays intercepting canvas input.
+
+## Teardown order
+
+1. mark the feature inactive and stop new work;
+2. abort owned requests and unregister input/events;
+3. await or serialize native async operations that cannot be cancelled;
+4. stop animation/media/workers;
+5. remove custom scene roots and Five passes;
+6. dispose owned render targets, geometry, materials and textures;
+7. release registry entries;
+8. allow the runtime owner—not the feature—to dispose Five and its renderer.
+
+This order must remain safe under React StrictMode, HMR, Work replacement and partial initialization failure.

package/skills/threejs-r117-five/references/r117-capabilities.md

@@ -0,0 +1,82 @@
+# Three.js 0.117.1 capability map
+
+Use this map to choose a capability family, then confirm the exact signature in the installed declaration. It is a routing guide, not a replacement for `node_modules/three/src/Three.d.ts`.
+
+## Import contract
+
+```ts
+import * as THREE from 'three'
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js'
+```
+
+The r117 package exposes `build/three.module.js`, `src/Three.d.ts`, and `examples/jsm`. It has no package export map for `three/addons`.
+
+## Capability domains
+
+### Fundamentals
+
+Available foundations include `Scene`, `Object3D`, `Group`, `Mesh`, `Line`, `LineLoop`, `LineSegments`, `Points`, `Sprite`, `LOD`, `InstancedMesh`, perspective/orthographic/cube/array cameras, `WebGLRenderer`, render targets, `Clock`, helpers and the complete math set (`Vector*`, `Euler`, `Quaternion`, `Matrix*`, `Color`, `Box*`, `Sphere`, `Plane`, `Ray`, `Frustum`).
+
+Inside Five, reuse `five.scene`, `five.camera` and the Five-owned renderer instead of constructing replacements.
+
+### Geometry
+
+r117 supports legacy `Geometry`, `BufferGeometry`, instanced/interleaved buffers, attributes, curves, shapes and the usual primitives. It still has parallel legacy and buffer classes such as `BoxGeometry` and `BoxBufferGeometry`; prefer the explicit buffer class for GPU-oriented custom features. It includes box, plane, sphere, circle, cylinder, cone, ring, torus, torus-knot, tube, shape, extrude, text, lathe, polyhedron, edges and wireframe families.
+
+Useful examples modules include `ConvexGeometry`, `DecalGeometry`, `BoxLineGeometry` and `ParametricGeometries` under `three/examples/jsm/geometries`.
+
+### Materials
+
+Core materials include basic, Lambert, Phong, standard, physical, toon, matcap, normal, depth, distance, line, points, sprite, shadow, `ShaderMaterial` and `RawShaderMaterial`. r117 physical material supports the locally declared clearcoat/sheen-era fields, not modern transmission/IOR/thickness/iridescence APIs.
+
+When cloning or replacing material arrays, dispose each owned unique material once. Do not dispose Five model materials.
+
+### Lighting
+
+Core lights include ambient, hemisphere, directional, point, spot, rectangular area and light probes, plus their helpers and shadow types. `RectAreaLightUniformsLib` and `LightProbeGenerator` are examples modules. Keep shadow maps bounded and update helper/projection state after changes.
+
+Five already owns scene lighting policy. Add feature lights only when their lifecycle, cost and interaction with Work materials are intentional.
+
+### Textures
+
+Core types include regular, canvas, data, 3D data, compressed, cube, video and depth textures; loaders include texture, cube, compressed, data, image and bitmap loaders; PMREM is available. Configure wrapping, filtering, anisotropy, mipmaps and r117 `encoding` explicitly. Color/albedo textures commonly use `THREE.sRGBEncoding`; data maps remain linear according to their installed contract.
+
+Image provenance, approved Realsee CDN hosts, Five `defaultImageURLTransform`, 数据万象 processing and browser CORS belong to the sibling [realsee-image-resources Skill](../../realsee-image-resources/SKILL.md). After that policy produces an authorized browser-readable URL, this reference governs r117 texture configuration and ownership.
+
+Dispose only owned textures, render targets and media sources. A material does not automatically establish application-level ownership of a shared texture.
+
+### Animation
+
+Use `AnimationMixer`, `AnimationClip`, `AnimationAction`, keyframe tracks, bones, skeletons, skinned meshes and morph influences. Advance mixers from a Five-owned timing integration or feature task rather than starting a second renderer loop. Stop actions, uncache roots/clips and release subscriptions on teardown.
+
+### Loaders
+
+Core loaders cover files, objects, buffer geometry, materials, textures, fonts, audio and animations. r117 examples provide GLTF, DRACO, FBX, OBJ/MTL, PLY, STL, SVG, RGBE, EXR, DDS, KTX, Basis, Collada, 3MF and other format loaders under `three/examples/jsm/loaders`.
+
+Loader results require explicit coordinate/up-axis handling before joining a Five scene. Configure decoder/worker paths through injected deployment policy and dispose workers where that loader exposes a disposal method.
+
+### Shaders
+
+Use GLSL with `ShaderMaterial` or `RawShaderMaterial`, typed uniforms, `UniformsUtils`, `ShaderLib`, `ShaderChunk`, or carefully reviewed `onBeforeCompile`. r117 also ships an older examples NodeMaterial system; it is not modern TSL.
+
+Document coordinate spaces for positions, normals and vectors. Mark material/uniform changes for rendering and clean up all owned textures, render targets and materials.
+
+### Post-processing
+
+Standalone Three scenes can use r117 examples modules such as `EffectComposer`, `RenderPass`, `ShaderPass`, bloom, SSAO/SAO, SMAA, Bokeh, film, glitch and afterimage passes. A Five feature instead uses Five's public `Pass`/`FivePass` and `five.addPass`/`insertPass`/`removePass` lifecycle. Never wrap the Five renderer in a second examples composer.
+
+### Interaction
+
+Core `Raycaster`, `Ray`, `Layers` and object event primitives are available. Examples controls include Orbit/Map, Drag, Transform, PointerLock, FirstPerson, Fly and Trackball controls; selection helpers are also available.
+
+Do not attach those controls to `five.camera`. For gesture-driven Work/model picking, prefer `event.center.raycaster` and `event.center.coords`. Use `five.modelScene.intersectRaycaster` to aggregate across loaded Work/models, and reserve `five.model.intersectRaycaster` for an intentionally selected single active model. For custom objects under `five.scene`, raycast only the owned feature root. If raw DOM input must be converted manually, map through both the Five canvas rectangle and the `five.viewport` subregion before producing NDC; whole-canvas normalization is wrong for shared viewports.
+
+## Performance baseline
+
+- reuse geometry, material and texture instances where ownership permits;
+- prefer instancing for repeated identical meshes;
+- avoid per-frame allocations in raycasting, animation and shader updates;
+- bound texture resolution, anisotropy, shadow maps and render-target count;
+- use Five on-demand rendering rather than an independent perpetual render loop;
+- measure real GPU/frame behavior before applying generic optimization advice.

package/skills/threejs-r117-five/references/r117-version-guards.md

@@ -0,0 +1,60 @@
+# r117 version guards
+
+Modern Three.js examples are not source-compatible with `three@0.117.1`. Translate them through installed declarations before use.
+
+## Required r117 mappings
+
+| Modern pattern | r117-compatible direction |
+|---|---|
+| `three/addons/...` | `three/examples/jsm/.../*.js` |
+| `texture.colorSpace = THREE.SRGBColorSpace` | `texture.encoding = THREE.sRGBEncoding` |
+| `renderer.outputColorSpace` | `renderer.outputEncoding` |
+| `TextGeometry` option `depth` | option `height` in the r117 declaration |
+| `new THREE.CapsuleGeometry(...)` | compose reviewed r117 primitives or custom BufferGeometry |
+| `matrix.invert()` | use the declared `target.getInverse(source)` pattern |
+| modern `BoxGeometry` assumed to extend BufferGeometry | choose r117 `BoxBufferGeometry` explicitly when required |
+| `three/tsl`, `Fn`, modern NodeMaterial/TSL | GLSL `ShaderMaterial`/`RawShaderMaterial`, or separately audit r117's old examples nodes |
+| `WebGPURenderer` | unavailable; use the Five-owned WebGL renderer |
+
+## Modern APIs absent from the pinned matrix
+
+Do not generate these without upgrading and re-auditing the complete Five/Three matrix:
+
+- `SRGBColorSpace`, `LinearSRGBColorSpace`, `NoColorSpace`, `outputColorSpace`;
+- `three/addons`, `three/tsl`, WebGPU renderer and modern TSL helpers;
+- `CapsuleGeometry`;
+- current `MeshPhysicalMaterial` transmission, IOR, thickness, attenuation and iridescence fields;
+- current GLTF loader helpers such as KTX2/Meshopt methods unless they exist in the exact installed r117 runtime and declaration;
+- renderer members introduced later, including `useLegacyLights`, `compileAsync()` and `renderAsync()`.
+
+Do not overgeneralize that boundary: r117 already has `physicallyCorrectLights`, tone mapping, `outputEncoding`, synchronous `compile()` and `setAnimationLoop()`.
+
+## r117-specific cautions
+
+- Geometry is in a legacy transition period: many shapes have both `*Geometry` and `*BufferGeometry` with different inheritance.
+- `Texture.encoding` and `WebGLRenderer.outputEncoding` use `TextureEncoding` constants; the sRGB constant begins with lowercase `s`.
+- `MeshPhysicalMaterial` fields must be read from the local declaration; current documentation includes properties r117 never had.
+- Examples modules are not part of the root type barrel. Import their exact `.js` file under `three/examples/jsm`.
+- Avoid adding an independent `@types/three`; r117 already declares `types: src/Three.d.ts`.
+
+## Runtime and type availability
+
+Classify an examples module before using it:
+
+1. **Runtime and declaration both exist**: import the exact `.js` path and use the bundled type declaration directly.
+2. **Runtime `.js` exists but its declaration is missing**: inspect the pinned r117 source, then add the smallest project-local module declaration or augmentation needed for the reviewed API. Keep it version-specific and verify runtime behavior; do not install modern `@types/three` to fill the gap.
+3. **Runtime module or member is absent**: it is unavailable in this matrix. Choose an r117 alternative or upgrade and re-audit the full Five/Three contract.
+
+For example, some r117 examples such as `NodeMaterialLoader.js` may have runtime code without a same-name `.d.ts`; that is a typing gap, not proof that the runtime module is absent.
+
+## Verification workflow
+
+1. Search the installed `three/src/Three.d.ts` root export.
+2. Open the referenced local declaration for the exact field or constructor.
+3. For extension modules, inspect the exact `.js` runtime and check whether a matching declaration exists; apply the three availability classes above.
+4. Confirm the feature does not assume ownership of a Five-controlled subsystem.
+5. Type-check, build, and exercise the behavior in the target browser/GPU.
+
+The doctor/verifier string checks are representative, high-signal regression guards rather than a complete Three API validator. Installed runtime/declarations, any reviewed local augmentation, type checking, production build and browser/GPU validation form the complete gate.
+
+Online current Three docs are useful for concepts, not signatures. Treat a runtime symbol absent from the pinned package as unavailable; treat a declaration-only gap according to the reviewed local-augmentation path instead of guessing a modern alias.

package/templates/base/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/base/.env.example

@@ -0,0 +1,12 @@
+# Fastify BFF server-only configuration. Copy this file to .env.development and replace the credential placeholders.
+# The browser calls only same-origin /api/work/{resourceCode}; never rename these values to VITE_*.
+# 标识当前的应用 ID（可选部署元数据）
+APP_ID=next-vr-develpment
+# Realsee 开放平台网关（中文版；海外版为 https://app-gateway.realsee.jp）
+REALSEE_GATEWAY_ENDPOINT=https://app-gateway.realsee.cn
+# Realsee 的网关 app key
+REALSEE_GATEWAY_APP_KEY=*
+# Realsee 的网关 app secret
+REALSEE_GATEWAY_APP_SECRET=*
+# Realsee 的企业账号 ID（可选部署元数据）
+REALSEE_SOURCE=REALSEE_TECH

package/templates/base/.gitignore.template

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.env*
+!.env.example
+*.log
+.DS_Store

package/templates/base/.node-version

@@ -0,0 +1 @@
+22.23.2

package/templates/base/.npmrc.template

@@ -0,0 +1,3 @@
+engine-strict=true
+package-lock=true
+save-prefix=>=

package/templates/base/.nvmrc

@@ -0,0 +1 @@
+22.23.2

package/templates/base/.prettierignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+.agents/
+.claude/
+.cursor/
+.github/
+.kiro/
+AGENTS.md
+CLAUDE.md
+.vr-cli.json
+package-lock.json
+.env.development

package/templates/base/README.md

@@ -0,0 +1,160 @@
+# Realsee Spatial Viewer
+
+Generated by `@realsee/vr-cli` {{TOOL_VERSION}}.
+
+This project ships a minimal read-only Viewer composition while preserving the complete native Five runtime, the dnalogel preset plugin collection, and an extension point for application-defined Five plugins. Vapor is only the React DOM component layer above the native Five canvas. The generated runtime does not use `@realsee/five/react`.
+
+## Toolchain
+
+Use Node.js `22.23.2` LTS from `.nvmrc` and `.node-version`: it is the current security patch on the oldest LTS line in the [Node.js production support matrix](https://nodejs.org/en/about/previous-releases). The runtime minimum is `>=22.18.0`, where the [native TypeScript type stripping](https://nodejs.org/api/typescript.html) used by the generated BFF is enabled by default. npm `11.19.0` stays pinned by `packageManager`. The committed `package-lock.json` is authoritative; use `npm ci` for deterministic installs. `.npmrc` enforces the declared engines, lockfile creation and the `>=` prefix for newly saved direct dependencies. ESLint covers browser TypeScript/React Hooks and Node BFF/config code; Prettier and EditorConfig keep formatting deterministic.
+
+## Start
+
+```bash
+cp .env.example .env.development
+# Fill REALSEE_GATEWAY_APP_KEY and REALSEE_GATEWAY_APP_SECRET in .env.development.
+npm ci
+npm run dev
+# Open http://127.0.0.1:8087/xZjYOkRkWIz75RwI3x (replace with an authorized resourceCode).
+```
+
+`REALSEE_GATEWAY_ENDPOINT` must be an HTTPS URL; the BFF refuses HTTP so AK/SK cannot be sent in cleartext. `npm run dev` validates `.env.development` before starting Fastify and Vite. After changing `.env.development`, stop the existing dev command and start it again so Node reloads the environment.
+
+Development runs the Fastify BFF on `127.0.0.1:8088` and Vite on `127.0.0.1:8087`; Vite proxies `/api` to Fastify, so the browser uses only the same-origin `GET /api/work/{resourceCode}` contract. Port 8087 is non-privileged; do not change it to privileged port 517.
+
+The BFF posts `REALSEE_GATEWAY_APP_KEY` and `REALSEE_GATEWAY_APP_SECRET` as form fields to `/auth/access_token`, caches the 5-minute token until shortly before `expire_at`, retries once after an upstream 401, then calls `GET /open/v3/vr/info?resource_code={resourceCode}` with the raw token in the `Authorization` header. It returns only the browser-safe `{ work, workCode, baseURL? }` envelope. Generic `tags` are not inferred as PanoTag data. The default gateway is `https://app-gateway.realsee.cn`; overseas deployments use `https://app-gateway.realsee.jp`. See the official [Realsee OpenAPI reference](https://open-platform.realsee.com/developer/openapi/?id=1001).
+
+For a production-style local run, build first and let Fastify serve both `dist` and the API on port 8087:
+
+```bash
+npm run build
+npm start
+```
+
+## Replace the example BFF
+
+The browser depends only on `GET /api/work/{resourceCode}`. Fastify is an example implementation, not an application architecture requirement:
+
+- `server/types.ts` declares the server-side contracts (`ServerConfig`, `WorkEnvelope`, `WorkDetailClient`, `WorkService`);
+- `server/realsee-open-api.ts` owns Realsee token exchange, expiry caching and upstream Work calls;
+- `server/work-service.ts` maps upstream data to the browser envelope without depending on Fastify;
+- `server/work-route.ts` adapts that service to HTTP;
+- `server/app.ts` composes routes and optional production static hosting;
+- `server/index.ts` is the Node.js process entry.
+
+The BFF is TypeScript and runs without a build step: Node executes `.ts` directly through native type stripping, so `npm run dev` and `npm start` need no bundler for the server. Because type stripping only removes erasable syntax, `tsconfig.server.json` enables `erasableSyntaxOnly`; `enum`, `namespace` and constructor parameter properties are rejected at type-check time instead of failing at runtime.
+
+A Go, Java or other backend may replace the entire `server/` directory as long as it preserves the same-origin endpoint and response envelope. Keep AK/SK and access tokens server-side; never put them in `src/`, `VITE_*`, Vite `define/envPrefix`, URLs, browser headers, logs or bundles. AK/SK authorize the BFF to call the upstream API; if an internet-facing deployment also needs caller or tenant authorization, add that policy before the Work route instead of exposing AK/SK to the browser. The generated project does not include `work.json` or customer Work data.
+
+The generated project has one `.env.example`. Only the Fastify BFF reads `REALSEE_GATEWAY_ENDPOINT`, `REALSEE_GATEWAY_APP_KEY` and `REALSEE_GATEWAY_APP_SECRET`; `APP_ID` and `REALSEE_SOURCE` remain optional deployment metadata. Real values belong in `.env.development`, the deployment environment or a secret manager.
+
+## Update dependencies
+
+The manifest intentionally declares every direct dependency except `three` as an open minimum range (`>=baseline`). The committed `package-lock.json` records the generator's reviewed initial resolution, so `npm ci` remains reproducible while an explicit update can move across major versions.
+
+To update every unlocked dependency to the newest release allowed by its open range:
+
+```bash
+npm update
+npm run check
+npm run build
+```
+
+To raise one dependency's declared minimum to its latest release and refresh the lockfile in one step:
+
+```bash
+npm install <pkg>@latest
+npm run check
+npm run build
+```
+
+`.npmrc` uses `save-prefix=>=`, so newly saved direct dependencies and explicit upgrades retain the open-minimum policy. After manually editing a minimum, use `npm run deps:relock`, then `npm run deps:install` to verify a clean lockfile install.
+
+Only one dependency is hard-locked:
+
+- `three` must stay exactly `0.117.1`. Five 6.8.9 targets that release, and the generated code plus the bundled Three capability references assume the r117 API surface. `vr-cli doctor` and the portable verifier reject any other value, including ranges.
+- Every other dependency, including `@realsee/five`, `@realsee/dnalogel`, `@realsee/vapor`, Fastify, React, Vite, TypeScript and the lint stack, must use `>=x.y.z` with a minimum no lower than the generator baseline. Exact, caret, tilde and bounded ranges are rejected because they cannot move freely to the latest release.
+- The lockfile's resolved direct version must satisfy both the declared minimum and the generator baseline. Raising a minimum requires relocking.
+
+When you update Five, dnalogel or Vapor, re-check the versioned contract fixtures and validate them together in a real browser: their spatial behavior is not fully covered by type checking. Do not run `npm audit fix --force`, which would rewrite the locked Three version.
+
+## Generator manifest
+
+`.vr-cli.json` is generator metadata, not application runtime configuration. It records only the schema/tool version, preset, package name, Agent asset mode and generation time. `vr-cli doctor` uses the declared Agent asset mode together with the files currently on disk to validate expected and unexpected Agent assets. Keep it in the generated repository for diagnostics and provenance, but never put credentials in it.
+
+The BFF returns raw Work inside this browser-safe envelope. Only an explicit nested PanoTag preset list is loaded; generic `tags`, `tagList` or `tag_list` fields are never inferred as PanoTag:
+
+```json
+{
+  "work": {},
+  "workCode": "xZjYOkRkWIz75RwI3x",
+  "baseURL": "https://authorized-resource-host.example/",
+  "initialState": {},
+  "presetData": {
+    "panoTagList": []
+  }
+}
+```
+
+## Spatial annotations
+
+“VR spatial tag” (spatial annotation) is the domain concept; PanoTag is only one preset implementation. Before adding a tag, classify its content, renderer, anchor and lifecycle/data ownership. Text, images, video, audio, models, virtual screens, room/item labels and custom spatial content may require different dnalogel presets or an application-defined Five/Three plugin.
+
+The Viewer is read-only. Do not directly edit `work.json`, downloaded Work or customer Work, and do not invent third-party media URLs. Persistent changes require an authoritative editor/API/BFF/source contract and user confirmation; otherwise use a typed patch proposal or runtime-only feature.
+
+## Architecture
+
+```text
+server/
+├── config.mjs               server-only environment validation
+├── realsee-open-api.mjs     token cache and Realsee OpenAPI adapter
+├── work-service.mjs         framework-neutral browser envelope
+├── work-route.mjs           Fastify HTTP adapter
+├── app.mjs                  API and optional dist hosting
+└── index.mjs                Node.js process entry
+src/
+├── app/                     composition root
+├── vr/
+│   ├── five/                native Five runtime and complete supported entry map
+│   ├── plugins/             dnalogel presets, custom Five plugins and lifecycle registry
+│   └── work/                browser-side WorkSource boundary
+├── features/                focused spatial feature adapters
+├── ui/                      Vapor/React DOM only
+└── shared/                  non-domain React utilities
+```
+
+- `.agents/skills/threejs-r117-five` maps all ten Three.js r117 capability domains, Five ownership boundaries and modern API incompatibilities for any Agent.
+- `fiveConfig.ts` returns reviewed `FiveInitArgs`; `SpatialRuntimeProvider` calls `new Five(...)` directly.
+- The provider waits for a positive host size, uses `appendTo` and `refresh`, exposes the native instance through `useSpatialRuntime()`, then owns plugin/Five/canvas cleanup.
+- React is limited to local composition, Context, lifecycle and DOM UI; do not add `createFiveProvider`, `FiveCanvas` or Five React hooks.
+- `src/vr/five/api.ts` maps every supported native Five 6.8.9 public entry point.
+- `src/vr/plugins/dnalogel.ts` exposes the dnalogel 3.81.2 preset plugin root surface; `src/vr/plugins` also hosts application-defined Five plugin infrastructure.
+- `SpatialPluginRegistry` is vendor-neutral: it rejects external name collisions, performs identity-safe registration and continues draining after individual disposal errors; each plugin feature still owns its declared load/hooks/media lifecycle.
+- `src/vr/plugins/examples/FeatureOwnedMeshPlugin.ts` is an opt-in Agent reference for custom Five/Three features. The default App does not import or register it. Vibe coding should copy its feature-owned scene root, registration rollback, render invalidation and idempotent disposal pattern before adding a focused feature.
+- `features/navigation` and `features/tags` are examples, not capability limits. The bundled PanoTag feature is created only for explicit `presetData.panoTagList` data.
+- `ui/ViewerOverlay.tsx` contains the Vapor DOM overlay and imports no spatial SDK.
+
+Prefer narrow direct imports in production features so unused capability families are not bundled.
+
+## Checks
+
+```bash
+npm run typecheck
+npm run typecheck:web
+npm run typecheck:bff
+npm run lint
+npm run format:check
+npm run check
+npm run build
+node .agents/skills/realsee-vr-app/scripts/verify-project.mjs .
+```
+
+Development-time validation is strict by design:
+
+- `typecheck:web` runs `tsconfig.json` over browser sources; `typecheck:bff` runs `tsconfig.server.json` over `server/`. Both enable `strict`, `noUncheckedIndexedAccess`, `noImplicitReturns` and unused-symbol checks; the server project adds `exactOptionalPropertyTypes`, `verbatimModuleSyntax` and `erasableSyntaxOnly`.
+- `lint` is type-aware (`typescript-eslint` `recommendedTypeChecked` over both projects) and fails on any warning. `no-floating-promises` and `no-misused-promises` are enforced everywhere; `no-unnecessary-condition` is enabled for `server/**` where types are fully owned, and left off for browser code that relies on async cancellation flags TypeScript cannot narrow.
+- `check` runs type checking, lint and Prettier; `build` repeats it before the Vite production build.
+
+The portable Skills contain the version-bound native Five lifecycle map, spatial-annotation decision workflow, complete dnalogel plugin family catalog, Three.js r117 capability/ownership/version guards, and Vapor DOM boundary. Installed declarations remain the source of truth for signatures.
+
+This is an internal integration template. Do not commit credentials, customer Work payloads, SDK source or copied SDK documentation.

package/templates/base/eslint.config.mjs

@@ -0,0 +1,75 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import tseslint from 'typescript-eslint'
+
+// Development-time strong validation: TypeScript sources are linted with
+// type-aware rules from both the browser and the server project.
+export default tseslint.config(
+  {
+    ignores: [
+      'node_modules/**',
+      'dist/**',
+      '.agents/**',
+      '.claude/**',
+      '.cursor/**',
+      '.github/**',
+      '.kiro/**',
+    ],
+  },
+  {
+    ...js.configs.recommended,
+    files: ['**/*.{js,mjs,cjs}'],
+  },
+  ...tseslint.configs.recommendedTypeChecked,
+  {
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.json', './tsconfig.server.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/consistent-type-imports': 'error',
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/no-misused-promises': 'error',
+      '@typescript-eslint/switch-exhaustiveness-check': 'error',
+    },
+  },
+  {
+    // Server types are fully owned here, so redundant runtime guards are real findings.
+    // Browser code keeps async cancellation flags that TypeScript cannot narrow, so
+    // this rule stays scoped to the server project.
+    files: ['server/**/*.ts'],
+    rules: {
+      '@typescript-eslint/no-unnecessary-condition': 'error',
+    },
+  },
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    languageOptions: {
+      globals: globals.browser,
+    },
+    plugins: {
+      'react-hooks': reactHooks,
+    },
+    rules: {
+      'react-hooks/exhaustive-deps': 'error',
+      'react-hooks/rules-of-hooks': 'error',
+    },
+  },
+  {
+    files: ['server/**/*.ts'],
+    languageOptions: {
+      globals: globals.node,
+    },
+  },
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    extends: [tseslint.configs.disableTypeChecked],
+    languageOptions: {
+      globals: globals.node,
+    },
+  },
+)

package/templates/base/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#0b1020" />
+    <title>Realsee VR Viewer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>