@realsee/vr-cli 0.1.3

package/templates/base/server/work-service.ts

@@ -0,0 +1,54 @@
+import type {
+  RealseeSpatialClient,
+  RequestOptions,
+  WorkEnvelope,
+  WorkService,
+} from './types.ts'
+
+const firstString = (...values: unknown[]): string | undefined =>
+  values.find(
+    (value): value is string => typeof value === 'string' && value.length > 0,
+  )
+
+export interface CreateWorkServiceOptions {
+  readonly openApiClient: RealseeSpatialClient
+}
+
+export function createWorkService({
+  openApiClient,
+}: CreateWorkServiceOptions): WorkService {
+  return Object.freeze({
+    async getWorkByResourceCode(
+      resourceCode: string,
+      { signal }: RequestOptions = {},
+    ): Promise<WorkEnvelope> {
+      const floorplanPromise = openApiClient
+        .getModelFloorplan(resourceCode, { signal })
+        .catch((error: unknown) => {
+          if (!signal?.aborted) {
+            console.warn(
+              `资源 ${resourceCode} 的平面图 capability 不可用，继续返回基础 Work。`,
+              error,
+            )
+          }
+          return undefined
+        })
+      const work = await openApiClient.getWorkDetail(resourceCode, { signal })
+      const modelFloorplan = await floorplanPromise
+      const workCode =
+        firstString(
+          work.resource_code,
+          work.workCode,
+          work.work_code,
+          work.basic_code,
+        ) || resourceCode
+      const baseURL = firstString(work.baseURL, work.base_url)
+      return {
+        work,
+        workCode,
+        ...(baseURL ? { baseURL } : {}),
+        ...(modelFloorplan ? { capabilities: { modelFloorplan } } : {}),
+      }
+    },
+  })
+}

package/templates/base/shared/model-floorplan.ts

@@ -0,0 +1,242 @@
+export interface FloorplanServerPosition {
+  x: number
+  y: number
+}
+
+export interface FloorplanServerImagePosition {
+  x: number
+  y: number
+}
+
+export interface FloorplanServerOutlineItem {
+  url: string
+  index: number
+  checksum?: string
+  svg_url?: string
+}
+
+export interface FloorplanServerEntrance {
+  rad: number
+  position: FloorplanServerPosition
+  position_in_image: FloorplanServerImagePosition
+  north_rad: number
+  room_id: string
+  floor_index: number
+}
+
+export interface FloorplanServerBounding {
+  max: FloorplanServerPosition
+  min: FloorplanServerPosition
+  origin: FloorplanServerPosition
+}
+
+export interface FloorplanServerRoomLabelItem {
+  position: FloorplanServerPosition
+  position_in_image: FloorplanServerImagePosition
+}
+
+export interface FloorplanServerRoomItem {
+  id: string
+  size: number
+  type: number
+  name: string
+  customizedName?: string
+  path: FloorplanServerPosition[]
+  room_type: string
+  floor_type: number
+  room_label: FloorplanServerRoomLabelItem
+  observer_indexs: number[]
+  dimension?: {
+    width: number
+    height: number
+  }
+}
+
+export type FloorplanServerRuleLabels = Record<
+  'top' | 'right' | 'bottom' | 'left',
+  FloorplanServerPosition[][]
+>
+
+export interface FloorplanServerFloorData {
+  floor_name: string
+  floor_index: number
+  rooms: FloorplanServerRoomItem[]
+  rules: FloorplanServerRuleLabels
+  is_has_wall?: boolean
+}
+
+export interface FloorplanServerObserver {
+  index: number
+  floor_index: number
+  position: FloorplanServerPosition
+  position_in_image: FloorplanServerImagePosition
+}
+
+export interface FloorplanServerDoorItem {
+  id: string
+  localName: string
+  name: string
+  position: {
+    x: number
+    y: number
+    z: number
+  }
+  rad: number
+}
+
+export interface FloorplanServerComputedData {
+  floor_datas: FloorplanServerFloorData[]
+  entrance: FloorplanServerEntrance | null
+  bounding: FloorplanServerBounding
+  observers: FloorplanServerObserver[]
+  doors: FloorplanServerDoorItem[]
+}
+
+export interface FloorplanServerData {
+  outlines: FloorplanServerOutlineItem[]
+  computed_data: FloorplanServerComputedData
+}
+
+/** Preferred ModelFloorplanPlugin.load input returned by format_floorplan_url. */
+export interface ModelFloorplanServerData {
+  version: number
+  data: FloorplanServerData
+}
+
+type RawRecord = Record<string, unknown>
+
+const isRecord = (value: unknown): value is RawRecord =>
+  Boolean(value && typeof value === 'object' && !Array.isArray(value))
+const isFiniteNumber = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value)
+const isInteger = (value: unknown): value is number => Number.isInteger(value)
+const isString = (value: unknown): value is string => typeof value === 'string'
+const isOptionalString = (value: unknown): value is string | undefined =>
+  value === undefined || isString(value)
+const isArrayOf = <Item>(
+  value: unknown,
+  guard: (item: unknown) => item is Item,
+): value is Item[] => Array.isArray(value) && value.every(guard)
+
+const isPosition = (value: unknown): value is FloorplanServerPosition =>
+  isRecord(value) && isFiniteNumber(value.x) && isFiniteNumber(value.y)
+
+const isOutline = (value: unknown): value is FloorplanServerOutlineItem =>
+  isRecord(value) &&
+  isString(value.url) &&
+  value.url.length > 0 &&
+  isInteger(value.index) &&
+  isOptionalString(value.checksum) &&
+  isOptionalString(value.svg_url)
+
+const isEntrance = (value: unknown): value is FloorplanServerEntrance =>
+  isRecord(value) &&
+  isFiniteNumber(value.rad) &&
+  isPosition(value.position) &&
+  isPosition(value.position_in_image) &&
+  isFiniteNumber(value.north_rad) &&
+  isString(value.room_id) &&
+  isInteger(value.floor_index)
+
+const isBounding = (value: unknown): value is FloorplanServerBounding =>
+  isRecord(value) &&
+  isPosition(value.max) &&
+  isPosition(value.min) &&
+  isPosition(value.origin)
+
+const isRoomLabel = (value: unknown): value is FloorplanServerRoomLabelItem =>
+  isRecord(value) &&
+  isPosition(value.position) &&
+  isPosition(value.position_in_image)
+
+const isRoom = (value: unknown): value is FloorplanServerRoomItem => {
+  if (!isRecord(value)) return false
+  const dimension = value.dimension
+  return (
+    isString(value.id) &&
+    isFiniteNumber(value.size) &&
+    isFiniteNumber(value.type) &&
+    isString(value.name) &&
+    isOptionalString(value.customizedName) &&
+    isArrayOf(value.path, isPosition) &&
+    isString(value.room_type) &&
+    isFiniteNumber(value.floor_type) &&
+    isRoomLabel(value.room_label) &&
+    isArrayOf(value.observer_indexs, isInteger) &&
+    (dimension === undefined ||
+      (isRecord(dimension) &&
+        isFiniteNumber(dimension.width) &&
+        isFiniteNumber(dimension.height)))
+  )
+}
+
+const isRuleLines = (value: unknown): value is FloorplanServerPosition[][] =>
+  Array.isArray(value) && value.every((line) => isArrayOf(line, isPosition))
+
+const isRules = (value: unknown): value is FloorplanServerRuleLabels =>
+  isRecord(value) &&
+  isRuleLines(value.top) &&
+  isRuleLines(value.right) &&
+  isRuleLines(value.bottom) &&
+  isRuleLines(value.left)
+
+const isFloorData = (value: unknown): value is FloorplanServerFloorData =>
+  isRecord(value) &&
+  isString(value.floor_name) &&
+  isInteger(value.floor_index) &&
+  isArrayOf(value.rooms, isRoom) &&
+  isRules(value.rules) &&
+  (value.is_has_wall === undefined || typeof value.is_has_wall === 'boolean')
+
+const isObserver = (value: unknown): value is FloorplanServerObserver =>
+  isRecord(value) &&
+  isInteger(value.index) &&
+  isInteger(value.floor_index) &&
+  isPosition(value.position) &&
+  isPosition(value.position_in_image)
+
+const isDoor = (value: unknown): value is FloorplanServerDoorItem => {
+  if (!isRecord(value) || !isRecord(value.position)) return false
+  return (
+    isString(value.id) &&
+    isString(value.localName) &&
+    isString(value.name) &&
+    isFiniteNumber(value.position.x) &&
+    isFiniteNumber(value.position.y) &&
+    isFiniteNumber(value.position.z) &&
+    isFiniteNumber(value.rad)
+  )
+}
+
+const isComputedData = (value: unknown): value is FloorplanServerComputedData =>
+  isRecord(value) &&
+  isArrayOf(value.floor_datas, isFloorData) &&
+  value.floor_datas.length > 0 &&
+  (value.entrance === null || isEntrance(value.entrance)) &&
+  isBounding(value.bounding) &&
+  isArrayOf(value.observers, isObserver) &&
+  isArrayOf(value.doors, isDoor)
+
+const isFloorplanServerData = (value: unknown): value is FloorplanServerData =>
+  isRecord(value) &&
+  isArrayOf(value.outlines, isOutline) &&
+  value.outlines.length > 0 &&
+  isComputedData(value.computed_data)
+
+/**
+ * Narrows the browser/server boundary without guessing data from raw Work.
+ * Empty or partial floorplan payloads are intentionally treated as unavailable.
+ */
+export function asModelFloorplanServerData(
+  value: unknown,
+): ModelFloorplanServerData | undefined {
+  if (
+    !isRecord(value) ||
+    !isInteger(value.version) ||
+    value.version < 0 ||
+    !isFloorplanServerData(value.data)
+  ) {
+    return undefined
+  }
+  return { version: value.version, data: value.data }
+}

package/templates/base/src/main.tsx

@@ -0,0 +1,11 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import '@realsee/vapor/vapor.css'
+import App from './app/App'
+import './styles.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

package/templates/base/src/shared/useElementSize.ts

@@ -0,0 +1,28 @@
+import { useEffect, useRef, useState } from 'react'
+
+export function useElementSize() {
+  const ref = useRef<HTMLDivElement>(null)
+  const [size, setSize] = useState({ width: 0, height: 0 })
+
+  useEffect(() => {
+    const element = ref.current
+    if (!element) return
+    const measure = (width: number, height: number) => {
+      const next = { width: Math.round(width), height: Math.round(height) }
+      setSize((current) =>
+        current.width === next.width && current.height === next.height
+          ? current
+          : next,
+      )
+    }
+    measure(element.clientWidth, element.clientHeight)
+    const observer = new ResizeObserver(([entry]) => {
+      if (!entry) return
+      measure(entry.contentRect.width, entry.contentRect.height)
+    })
+    observer.observe(element)
+    return () => observer.disconnect()
+  }, [])
+
+  return { ref, size }
+}

package/templates/base/src/styles.css

@@ -0,0 +1,91 @@
+:root {
+  color: #f7f9ff;
+  background: #090e1b;
+  font-family:
+    Inter,
+    ui-sans-serif,
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    sans-serif;
+  font-synthesis: none;
+}
+
+html,
+body,
+#root {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  overflow: hidden;
+}
+
+.app {
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  background: #090e1b;
+}
+
+.spatial-stage {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  background: #101728;
+}
+
+.five-surface {
+  position: absolute;
+  inset: 0;
+  min-width: 0;
+  min-height: 0;
+}
+
+.five-surface canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.dom-overlay {
+  position: absolute;
+  inset: 0;
+  z-index: 20;
+  pointer-events: none;
+}
+
+.viewer-vapor {
+  width: 100%;
+  height: 100%;
+}
+
+.viewer-controls,
+.mode-switcher {
+  pointer-events: auto;
+}
+
+.mode-switcher-indicator {
+  position: absolute;
+  bottom: -0.5rem;
+  left: 50%;
+  width: 3.375rem;
+  height: 0.125rem;
+  transform: translateX(-50%);
+  background-image: linear-gradient(
+    to right,
+    rgba(255, 255, 255, 0),
+    rgba(255, 255, 255, 1) 50%,
+    rgba(255, 255, 255, 0)
+  );
+}
+
+.viewer-status {
+  max-width: calc(100vw - 2rem);
+  pointer-events: none;
+}

package/templates/base/src/vr/five/SpatialRuntimeProvider.tsx

@@ -0,0 +1,234 @@
+import {
+  createContext,
+  useContext,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react'
+import { Five } from '@realsee/five'
+import { SpatialPluginRegistry } from '../plugins/SpatialPluginRegistry'
+import { createFiveInitArgs } from './fiveConfig'
+
+export class SpatialRuntimeLifetime {
+  private disposed = false
+  private teardowns = new Set<() => void>()
+  private pending = new Set<Promise<unknown>>()
+  private idleCallbacks = new Set<() => void>()
+
+  get active() {
+    return !this.disposed
+  }
+
+  own(teardown: () => void) {
+    let owned = true
+    const release = () => {
+      if (!owned) return
+      owned = false
+      this.teardowns.delete(release)
+      teardown()
+    }
+    if (this.disposed) release()
+    else this.teardowns.add(release)
+    return release
+  }
+
+  track<T>(task: Promise<T>) {
+    if (this.disposed) {
+      return task.then<T>(
+        () => Promise.reject(new Error('空间运行时已停止。')),
+        () => Promise.reject(new Error('空间运行时已停止。')),
+      )
+    }
+    const tracked = task.finally(() => {
+      this.pending.delete(tracked)
+      this.flushIdleCallbacks()
+    })
+    this.pending.add(tracked)
+    return tracked
+  }
+
+  private queue: Promise<void> = Promise.resolve()
+
+  runExclusive<T>(operation: () => Promise<T>) {
+    const task = this.queue.then(async () => {
+      if (this.disposed) throw new Error('空间运行时已停止。')
+      return operation()
+    })
+    this.queue = task.then(
+      () => undefined,
+      () => undefined,
+    )
+    return this.track(task)
+  }
+
+  disposeFeatures() {
+    if (this.disposed) return []
+    this.disposed = true
+    const errors: unknown[] = []
+    for (const teardown of [...this.teardowns].reverse()) {
+      try {
+        teardown()
+      } catch (error) {
+        errors.push(error)
+      }
+    }
+    this.flushIdleCallbacks()
+    return errors
+  }
+
+  afterPending(callback: () => void) {
+    if (this.pending.size === 0) callback()
+    else this.idleCallbacks.add(callback)
+  }
+
+  private flushIdleCallbacks() {
+    if (this.pending.size !== 0) return
+    const callbacks = [...this.idleCallbacks]
+    this.idleCallbacks.clear()
+    for (const callback of callbacks) {
+      try {
+        callback()
+      } catch (error) {
+        console.error('空间运行时延迟清理失败。', error)
+      }
+    }
+  }
+}
+
+export type SpatialRuntime = {
+  five: Five
+  plugins: SpatialPluginRegistry
+  lifetime: SpatialRuntimeLifetime
+}
+
+const SpatialRuntimeContext = createContext<SpatialRuntime | null>(null)
+
+export function SpatialRuntimeProvider({ children }: { children: ReactNode }) {
+  const hostRef = useRef<HTMLDivElement>(null)
+  const [runtime, setRuntime] = useState<SpatialRuntime | null>(null)
+
+  useLayoutEffect(() => {
+    const host = hostRef.current
+    if (!host) return
+
+    let five: Five | null = null
+    let plugins: SpatialPluginRegistry | null = null
+    let lifetime: SpatialRuntimeLifetime | null = null
+    let observer: ResizeObserver | null = null
+    let published = false
+    let disposed = false
+
+    const finalizeRuntime = (
+      ownedFive: Five,
+      ownedPlugins: SpatialPluginRegistry | null,
+    ) => {
+      const pluginErrors = ownedPlugins?.disposeAll() ?? []
+      if (pluginErrors.length)
+        console.error('部分空间插件清理失败。', pluginErrors)
+
+      const canvas = ownedFive.getElement()
+      try {
+        ownedFive.dispose()
+      } catch (error) {
+        console.error('Five 运行时清理失败。', error)
+      } finally {
+        canvas?.remove()
+      }
+    }
+
+    const teardown = () => {
+      if (disposed) return
+      disposed = true
+      observer?.disconnect()
+      observer = null
+
+      const ownedFive = five
+      const ownedPlugins = plugins
+      const ownedLifetime = lifetime
+      five = null
+      plugins = null
+      lifetime = null
+
+      if (published && ownedFive) {
+        setRuntime((current) => (current?.five === ownedFive ? null : current))
+      }
+      const featureErrors = ownedLifetime?.disposeFeatures() ?? []
+      if (featureErrors.length)
+        console.error('部分空间 feature 清理失败。', featureErrors)
+      if (!ownedFive) return
+
+      const finalize = () => finalizeRuntime(ownedFive, ownedPlugins)
+      if (ownedLifetime) ownedLifetime.afterPending(finalize)
+      else finalize()
+    }
+
+    const applySize = (rawWidth: number, rawHeight: number) => {
+      if (disposed) return
+      const width = Math.round(rawWidth)
+      const height = Math.round(rawHeight)
+      if (width <= 0 || height <= 0) return
+
+      if (five) {
+        five.refresh({ width, height }, window.devicePixelRatio)
+        return
+      }
+
+      const nextFive = new Five(createFiveInitArgs())
+      const nextLifetime = new SpatialRuntimeLifetime()
+      five = nextFive
+      lifetime = nextLifetime
+      try {
+        nextFive.appendTo(host, { width, height })
+        nextFive.refresh({ width, height }, window.devicePixelRatio)
+        const nextPlugins = new SpatialPluginRegistry(nextFive)
+        plugins = nextPlugins
+        published = true
+        setRuntime({
+          five: nextFive,
+          plugins: nextPlugins,
+          lifetime: nextLifetime,
+        })
+      } catch (error) {
+        teardown()
+        throw error
+      }
+    }
+
+    try {
+      observer = new ResizeObserver(([entry]) => {
+        if (!entry) return
+        try {
+          applySize(entry.contentRect.width, entry.contentRect.height)
+        } catch (error) {
+          console.error('Five 原生 surface 初始化失败。', error)
+        }
+      })
+      observer.observe(host)
+      applySize(host.clientWidth, host.clientHeight)
+    } catch (error) {
+      teardown()
+      throw error
+    }
+
+    return teardown
+  }, [])
+
+  return (
+    <div className="spatial-stage">
+      <div ref={hostRef} className="five-surface" />
+      {runtime && (
+        <SpatialRuntimeContext.Provider value={runtime}>
+          {children}
+        </SpatialRuntimeContext.Provider>
+      )}
+    </div>
+  )
+}
+
+export function useSpatialRuntime() {
+  const runtime = useContext(SpatialRuntimeContext)
+  if (!runtime)
+    throw new Error('useSpatialRuntime 必须在 SpatialRuntimeProvider 内调用。')
+  return runtime
+}

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

@@ -0,0 +1,10 @@
+// Version-bound public Five API surface. Import only the capability a feature uses.
+// The runtime is constructed directly from @realsee/five; do not use its React subpath.
+export * from '@realsee/five'
+export * as FivePlugins from '@realsee/five/plugins'
+export * as FiveLine from '@realsee/five/line'
+export * as FiveSticker from '@realsee/five/sticker'
+export * as FiveVfx from '@realsee/five/vfx'
+export * as FiveGltfLoader from '@realsee/five/gltf-loader'
+export * as FiveShaderLib from '@realsee/five/shader-lib'
+export * as FiveWorkDownloader from '@realsee/five/work-downloader'