@realsee/vr-cli 0.1.3

package/templates/base/src/vr/five/fiveConfig.ts

@@ -0,0 +1,42 @@
+import type { FiveInitArgs } from '@realsee/five'
+import { BackgroundPlugin, PanoAnimePlugin } from '@realsee/five/plugins'
+
+function supportsWebGL2() {
+  const match = navigator.userAgent.match(/OS (\d+)_/i)
+  const iosVersion = match ? Number(match[1]) : 0
+  return !iosVersion || iosVersion >= 16
+}
+
+export function createFiveInitArgs(): FiveInitArgs {
+  return {
+    panorama: {
+      maxLatitude: Math.PI / 4,
+      minLatitude: -Math.PI / 4,
+      minFov: 40,
+      maxFov: 120,
+      adjustPanoCircleMeshPositionBasedOnModel: true,
+    },
+    floorplan: {
+      minLatitude: 0,
+      maxLatitude: Math.PI / 2,
+      defaultFov: 80,
+    },
+    imageOptions: {
+      size: 512,
+      format: 'avif',
+    },
+    textureOptions: {
+      quality: 95,
+      format: 'avif',
+      autoResize: true,
+    },
+    plugins: [
+      [BackgroundPlugin, 'BackgroundPlugin', {}],
+      [PanoAnimePlugin, 'PanoAnimePlugin', {}],
+    ],
+    backgroundAlpha: 0,
+    onlyRenderIfNeeds: true,
+    poweredByRealsee: false,
+    webgl2: supportsWebGL2(),
+  }
+}

package/templates/base/src/vr/five/initialState.ts

@@ -0,0 +1,48 @@
+import { Five, type State } from '@realsee/five'
+import * as THREE from 'three'
+import type { RawRecord } from '../work/WorkSource'
+
+const asRecord = (value: unknown): RawRecord =>
+  value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as RawRecord)
+    : {}
+
+const finiteNumber = (...values: unknown[]) => {
+  for (const value of values)
+    if (typeof value === 'number' && Number.isFinite(value)) return value
+  return undefined
+}
+
+export function initialStateFrom(
+  work: RawRecord,
+  override?: Partial<State>,
+): Partial<State> {
+  const initial = asRecord(work.initial)
+  const offset = asRecord(initial.offset)
+  const state: Partial<State> = {
+    mode:
+      typeof initial.mode === 'string'
+        ? (initial.mode as State['mode'])
+        : Five.Mode.Panorama,
+  }
+  const panoIndex = finiteNumber(
+    initial.panoIndex,
+    initial.pano_index,
+    initial.pano,
+  )
+  const longitude = finiteNumber(initial.longitude)
+  const latitude = finiteNumber(initial.latitude)
+  const fov = finiteNumber(initial.fov)
+  const distance = finiteNumber(initial.distance)
+  if (panoIndex !== undefined) state.panoIndex = panoIndex
+  if (longitude !== undefined) state.longitude = longitude
+  if (latitude !== undefined) state.latitude = latitude
+  if (fov !== undefined) state.fov = fov
+  if (distance !== undefined) state.distance = distance
+  const x = finiteNumber(offset.x)
+  const y = finiteNumber(offset.y)
+  const z = finiteNumber(offset.z)
+  if (x !== undefined && y !== undefined && z !== undefined)
+    state.offset = new THREE.Vector3(x, y, z)
+  return { ...state, ...override }
+}

package/templates/base/src/vr/plugins/SpatialPluginRegistry.ts

@@ -0,0 +1,104 @@
+import type { Five } from '@realsee/five'
+
+export type SpatialPluginFactory<Parameters extends unknown[], Plugin> = (
+  five: Five,
+  ...parameters: Parameters
+) => Plugin
+
+type DisposablePlugin = {
+  dispose?: () => unknown
+}
+
+const disposePlugin = (plugin: unknown) => {
+  if (!plugin || typeof plugin !== 'object') return
+  const dispose = (plugin as DisposablePlugin).dispose
+  if (typeof dispose === 'function') dispose.call(plugin)
+}
+
+/**
+ * Owns dynamically created spatial plugins for one Five instance.
+ *
+ * dnalogel presets and application-defined Five plugins do not share one
+ * universal lifecycle interface. Feature adapters remain responsible for
+ * plugin-specific hooks, media and load/enable/disable methods; the registry
+ * guarantees conflict-safe ownership and best-effort drain.
+ */
+export class SpatialPluginRegistry {
+  private readonly owned = new Map<string, unknown>()
+
+  constructor(readonly five: Five) {}
+
+  create<Parameters extends unknown[], Plugin>(
+    name: string,
+    factory: SpatialPluginFactory<Parameters, Plugin>,
+    ...parameters: Parameters
+  ) {
+    const plugin = factory(this.five, ...parameters)
+    try {
+      return this.register(name, plugin)
+    } catch (error) {
+      try {
+        disposePlugin(plugin)
+      } catch (disposeError) {
+        console.error(
+          `注册空间插件 ${name} 失败后清理候选实例失败。`,
+          disposeError,
+        )
+      }
+      throw error
+    }
+  }
+
+  register<Plugin>(name: string, plugin: Plugin) {
+    const current = this.owned.get(name)
+    const registered: unknown = this.five.plugins[name]
+    const hasRegisteredPlugin = Object.prototype.hasOwnProperty.call(
+      this.five.plugins,
+      name,
+    )
+    if (
+      hasRegisteredPlugin &&
+      registered !== current &&
+      registered !== plugin
+    ) {
+      throw new Error(
+        `空间插件名称冲突：${name} 已由当前 registry 之外的实例占用。`,
+      )
+    }
+
+    if (current && current !== plugin) {
+      throw new Error(
+        `空间插件名称冲突：${name} 已由当前 registry 中的活动实例占用。`,
+      )
+    }
+    this.five.plugins[name] = plugin
+    this.owned.set(name, plugin)
+    return plugin
+  }
+
+  get<Plugin>(name: string) {
+    return this.five.plugins[name] as Plugin | undefined
+  }
+
+  unregister(name: string, expected?: unknown) {
+    const plugin = this.owned.get(name)
+    if (!plugin || (expected !== undefined && plugin !== expected)) return
+    this.owned.delete(name)
+    if (this.five.plugins[name] === plugin) delete this.five.plugins[name]
+    try {
+      disposePlugin(plugin)
+      return undefined
+    } catch (error) {
+      return error
+    }
+  }
+
+  disposeAll() {
+    const errors: unknown[] = []
+    for (const [name, plugin] of [...this.owned.entries()].reverse()) {
+      const error = this.unregister(name, plugin)
+      if (error) errors.push(error)
+    }
+    return errors
+  }
+}

package/templates/base/src/vr/plugins/dnalogel.ts

@@ -0,0 +1,2 @@
+// Version-bound dnalogel preset surface. Custom Five plugins live beside this file under src/vr/plugins.
+export * from '@realsee/dnalogel'

package/templates/base/src/vr/plugins/examples/FeatureOwnedMeshPlugin.ts

@@ -0,0 +1,73 @@
+import type { Five } from '@realsee/five'
+import { BoxBufferGeometry, Group, Mesh, MeshBasicMaterial } from 'three'
+import type { SpatialPluginRegistry } from '../SpatialPluginRegistry'
+
+// Opt-in reference for Agent-generated Five/Three features. The default App does not import or register it.
+export const FEATURE_OWNED_MESH_PLUGIN_NAME = 'example.featureOwnedMesh'
+
+export interface FeatureOwnedMeshPluginOptions {
+  size?: number
+  color?: string | number
+  position?: readonly [number, number, number]
+}
+
+export interface FeatureOwnedMeshPlugin {
+  readonly root: Group
+  readonly mesh: Mesh<BoxBufferGeometry, MeshBasicMaterial>
+  setVisible(visible: boolean): void
+  dispose(): void
+}
+
+export function createFeatureOwnedMeshPlugin(
+  five: Five,
+  options: FeatureOwnedMeshPluginOptions = {},
+): FeatureOwnedMeshPlugin {
+  const size = options.size ?? 0.2
+  if (!Number.isFinite(size) || size <= 0)
+    throw new Error('自定义 Mesh 插件的 size 必须是正数。')
+
+  const root = new Group()
+  root.name = FEATURE_OWNED_MESH_PLUGIN_NAME
+  const geometry = new BoxBufferGeometry(size, size, size)
+  const material = new MeshBasicMaterial({ color: options.color ?? 0x4f8cff })
+  const mesh = new Mesh(geometry, material)
+  root.add(mesh)
+
+  const [x, y, z] = options.position ?? [0, 0, 0]
+  root.position.set(x, y, z)
+  five.scene.add(root)
+  five.needsRender = true
+
+  let disposed = false
+  return {
+    root,
+    mesh,
+    setVisible(visible) {
+      if (disposed) return
+      root.visible = visible
+      five.needsRender = true
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      root.parent?.remove(root)
+      geometry.dispose()
+      material.dispose()
+      five.needsRender = true
+    },
+  }
+}
+
+export function registerFeatureOwnedMeshPlugin(
+  plugins: SpatialPluginRegistry,
+  options: FeatureOwnedMeshPluginOptions = {},
+) {
+  const plugin = createFeatureOwnedMeshPlugin(plugins.five, options)
+  try {
+    return plugins.register(FEATURE_OWNED_MESH_PLUGIN_NAME, plugin)
+  } catch (error) {
+    // Handles both external name collisions and registry-owned replacement rejection.
+    plugin.dispose()
+    throw error
+  }
+}

package/templates/base/src/vr/work/WorkSource.ts

@@ -0,0 +1,247 @@
+import type { State } from '@realsee/five'
+import type { Tags } from '@realsee/dnalogel/libs/PanoTagPlugin'
+import {
+  asModelFloorplanServerData,
+  type ModelFloorplanServerData,
+} from '../../../shared/model-floorplan'
+
+export type RawRecord = Record<string, unknown>
+
+export type WorkPresetData = {
+  panoTagList?: Tags['tagList']
+}
+
+export type WorkCapabilities = {
+  modelFloorplan?: ModelFloorplanServerData
+}
+
+export type WorkPayload = {
+  work: RawRecord
+  workCode: string
+  displayName: string
+  baseURL?: string
+  initialState?: Partial<State>
+  presetData?: WorkPresetData
+  capabilities?: WorkCapabilities
+}
+
+const RESOURCE_CODE_PATTERN = /^[A-Za-z0-9_-]{1,128}$/
+
+const isRecord = (value: unknown): value is RawRecord =>
+  Boolean(value && typeof value === 'object' && !Array.isArray(value))
+
+const asRecord = (value: unknown): RawRecord => (isRecord(value) ? value : {})
+
+const firstString = (...values: unknown[]) =>
+  values.find(
+    (value): value is string => typeof value === 'string' && value.length > 0,
+  )
+
+const displayNameFrom = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') return undefined
+  const displayName = value.trim()
+  return displayName || undefined
+}
+
+const PANO_TAG_CONTENT_TYPES = new Set([
+  'Text',
+  'Audio',
+  'ImageText',
+  'Image',
+  'Video',
+  'Panorama',
+  'Link',
+  'VRLink',
+  'Sticker',
+  'PanoLink',
+  'Marketing',
+  'MediaPlane',
+  'MediaModel',
+  'Model',
+  'Custom',
+  'Unknown',
+])
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0
+
+const isNumberArray = (value: unknown, minimumLength = 1): value is number[] =>
+  Array.isArray(value) &&
+  value.length >= minimumLength &&
+  value.every((item) => typeof item === 'number' && Number.isFinite(item))
+
+const isPosition = (value: unknown): value is number[] =>
+  isNumberArray(value, 3)
+
+const isPositionList = (value: unknown, length: number, exact = false) =>
+  Array.isArray(value) &&
+  (exact ? value.length === length : value.length >= length) &&
+  value.every(isPosition)
+
+const isMediaDataList = (value: unknown) =>
+  Array.isArray(value) &&
+  value.every((item) => {
+    if (!isRecord(item) || !isNonEmptyString(item.url)) return false
+    return item.type === 'Image' || item.type === 'Video'
+  })
+
+const hasCanonicalPanoTagData = (contentType: string, data: RawRecord) => {
+  switch (contentType) {
+    case 'Audio':
+      return isNonEmptyString(data.audioUrl)
+    case 'ImageText':
+    case 'Image':
+    case 'Video':
+    case 'Panorama':
+      return isMediaDataList(data.mediaData)
+    case 'Marketing':
+      return isNonEmptyString(data.title)
+    case 'MediaPlane':
+      return isMediaDataList(data.mediaData)
+    case 'MediaModel':
+      return (
+        isNonEmptyString(data.modelUrl) &&
+        isMediaDataList(data.mediaData) &&
+        isPositionList(data.mediaPosition, 4, true)
+      )
+    case 'Model':
+      return isNonEmptyString(data.modelUrl)
+    default:
+      return true
+  }
+}
+
+const hasCanonicalPanoTagAnchor = (tag: RawRecord) => {
+  const stickType = tag.stickType ?? '2DPoint'
+  switch (stickType) {
+    case '2DPoint':
+      return isPosition(tag.position)
+    case '3DPoint':
+      return isPosition(tag.position) && isPosition(tag.normal)
+    case 'Plane':
+      return isPositionList(tag.position, 4, true)
+    case 'Model':
+      return isPosition(tag.position) && isNumberArray(tag.matrix, 16)
+    case '3DBox': {
+      if (!isRecord(tag.position)) return false
+      return (
+        isPosition(tag.position.start) &&
+        isPosition(tag.position.end) &&
+        isPosition(tag.position.rotation)
+      )
+    }
+    case 'Polygon':
+      return isPositionList(tag.position, 3)
+    case 'Mask':
+      return (
+        isPosition(tag.position) &&
+        isNonEmptyString(tag.mask) &&
+        (typeof tag.color === 'string' ||
+          typeof tag.color === 'number' ||
+          isNumberArray(tag.color, 3))
+      )
+    default:
+      return false
+  }
+}
+
+const hasExplicitPanoTagShape = (
+  value: unknown,
+): value is Tags['tagList'][number] => {
+  if (
+    !isRecord(value) ||
+    !isNonEmptyString(value.contentType) ||
+    !isRecord(value.data)
+  )
+    return false
+  return (
+    PANO_TAG_CONTENT_TYPES.has(value.contentType) &&
+    hasCanonicalPanoTagData(value.contentType, value.data) &&
+    hasCanonicalPanoTagAnchor(value)
+  )
+}
+
+const asExplicitPanoTagList = (value: unknown): Tags['tagList'] | undefined => {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value))
+    throw new Error('presetData.panoTagList 必须是数组。')
+  return value.map((item, index) => {
+    if (!hasExplicitPanoTagShape(item)) {
+      throw new Error(
+        `presetData.panoTagList[${index}] 不符合 canonical content/data/stickType anchor 契约。`,
+      )
+    }
+    return item
+  })
+}
+
+export function resourceCodeFromPathname(pathname: string) {
+  const segments = pathname.split('/').filter(Boolean)
+  if (segments.length !== 1) throw new Error('访问路径必须为 /{resourceCode}。')
+  const [encodedResourceCode = ''] = segments
+
+  let resourceCode: string
+  try {
+    resourceCode = decodeURIComponent(encodedResourceCode)
+  } catch {
+    throw new Error('resourceCode 不是有效的 URL 路径参数。')
+  }
+  if (!RESOURCE_CODE_PATTERN.test(resourceCode))
+    throw new Error('resourceCode 格式无效。')
+  return resourceCode
+}
+
+export interface WorkSource {
+  load(signal?: AbortSignal): Promise<WorkPayload>
+}
+
+export class RouteWorkSource implements WorkSource {
+  async load(signal?: AbortSignal): Promise<WorkPayload> {
+    const resourceCode = resourceCodeFromPathname(window.location.pathname)
+    // The generated Fastify BFF implements this contract; another language may replace it without changing the browser.
+    const response = await fetch(
+      `/api/work/${encodeURIComponent(resourceCode)}`,
+      {
+        signal,
+        headers: { Accept: 'application/json' },
+      },
+    )
+    if (!response.ok) throw new Error(`Work 请求失败：HTTP ${response.status}`)
+
+    const raw = (await response.json()) as unknown
+    const envelope = asRecord(raw)
+    const nestedWork = asRecord(envelope.work)
+    const work = Object.keys(nestedWork).length ? nestedWork : envelope
+    if (!Object.keys(work).length) throw new Error('Work 响应不是有效对象。')
+
+    const workCode =
+      firstString(
+        envelope.workCode,
+        envelope.work_code,
+        work.workCode,
+        work.work_code,
+        work.code,
+      ) ?? resourceCode
+    const presetData = asRecord(envelope.presetData)
+    const panoTagList = asExplicitPanoTagList(presetData.panoTagList)
+    const modelFloorplan = asModelFloorplanServerData(
+      asRecord(envelope.capabilities).modelFloorplan,
+    )
+    return {
+      work,
+      workCode,
+      displayName: displayNameFrom(work.name) ?? workCode,
+      baseURL: firstString(
+        envelope.baseURL,
+        envelope.base_url,
+        work.baseURL,
+        work.base_url,
+      ),
+      initialState: asRecord(envelope.initialState),
+      ...(panoTagList !== undefined ? { presetData: { panoTagList } } : {}),
+      ...(modelFloorplan ? { capabilities: { modelFloorplan } } : {}),
+    }
+  }
+}
+
+export const workSource: WorkSource = new RouteWorkSource()

package/templates/base/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "jsx": "react-jsx",
+    "types": ["vite/client"]
+  },
+  "include": ["src", "shared", "vite.config.ts"]
+}

package/templates/base/tsconfig.server.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "strict": true,
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true
+  },
+  "include": ["server", "shared"]
+}

package/templates/base/vite.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: '127.0.0.1',
+    port: 8087,
+    strictPort: true,
+    proxy: {
+      '/api': {
+        target: 'http://127.0.0.1:8088',
+      },
+    },
+  },
+  preview: {
+    host: '127.0.0.1',
+    port: 8087,
+    strictPort: true,
+  },
+})