@realsee/vr-cli 0.1.3

package/templates/viewer/src/app/App.tsx

@@ -0,0 +1,182 @@
+import { useEffect, useState } from 'react'
+import { parseWork, type Five } from '@realsee/five'
+import {
+  createModelFloorplanFeature,
+  type ModelFloorplanFeature,
+} from '../features/floorplan/ModelFloorplanFeature'
+import { ModeSwitcher } from '../features/navigation/ModeSwitcher'
+import { createPanoTagFeature } from '../features/tags/PanoTagFeature'
+import { ViewerOverlay } from '../ui/ViewerOverlay'
+import { initialStateFrom } from '../vr/five/initialState'
+import {
+  SpatialRuntimeProvider,
+  useSpatialRuntime,
+  type SpatialRuntimeLifetime,
+} from '../vr/five/SpatialRuntimeProvider'
+import { workSource } from '../vr/work/WorkSource'
+
+function waitForActiveModel(five: Five, lifetime: SpatialRuntimeLifetime) {
+  if (five.model.loaded) return Promise.resolve()
+
+  return new Promise<void>((resolve, reject) => {
+    let settled = false
+    let release = () => {}
+    let stopLoaded = () => {}
+    let stopError = () => {}
+
+    const settle = (error?: Error) => {
+      if (settled) return
+      settled = true
+      release()
+      if (error) reject(error)
+      else resolve()
+    }
+
+    stopLoaded = five.on('models.load', () => {
+      if (five.model.loaded) settle()
+    })
+    stopError = five.on('model.error', () =>
+      settle(new Error('Five 模型加载失败。')),
+    )
+    release = lifetime.own(() => {
+      stopLoaded()
+      stopError()
+      if (!settled) {
+        settled = true
+        reject(new Error('空间运行时已停止。'))
+      }
+    })
+    if (five.model.loaded) settle()
+  })
+}
+
+function ViewerScene() {
+  const { five, plugins, lifetime } = useSpatialRuntime()
+  const [ready, setReady] = useState(false)
+  const [workName, setWorkName] = useState<string | null>(null)
+  const [status, setStatus] = useState('正在加载 VR Work…')
+  const [error, setError] = useState<string | null>(null)
+  const [selectedTagId, setSelectedTagId] = useState<string | null>(null)
+  const [floorplanFeature, setFloorplanFeature] =
+    useState<ModelFloorplanFeature | null>(null)
+
+  useEffect(() => {
+    const request = new AbortController()
+    let active = true
+    let tags: ReturnType<typeof createPanoTagFeature> | null = null
+    let floorplan: ModelFloorplanFeature | null = null
+    const teardown = lifetime.own(() => {
+      active = false
+      request.abort()
+      tags?.dispose()
+      tags = null
+      floorplan?.dispose()
+      floorplan = null
+    })
+
+    const load = async () => {
+      try {
+        setReady(false)
+        setWorkName(null)
+        setError(null)
+        setSelectedTagId(null)
+        setFloorplanFeature(null)
+        const payload = await workSource.load(request.signal)
+        if (!active) return
+        setWorkName(payload.displayName)
+
+        await lifetime.runExclusive(async () => {
+          if (!active) return
+          const work = parseWork(payload.work, {
+            workCode: payload.workCode,
+            ...(payload.baseURL ? { baseURL: payload.baseURL } : {}),
+          })
+          await five.load(
+            [work],
+            initialStateFrom(payload.work, payload.initialState),
+            { duration: 0 },
+          )
+          if (!active) return
+          await waitForActiveModel(five, lifetime)
+          if (!active) return
+
+          const modelFloorplan = payload.capabilities?.modelFloorplan
+          if (modelFloorplan) {
+            const currentFloorplan = createModelFloorplanFeature(five, plugins)
+            floorplan = currentFloorplan
+            try {
+              await currentFloorplan.load(modelFloorplan)
+            } catch (floorplanError) {
+              currentFloorplan.dispose()
+              if (floorplan === currentFloorplan) floorplan = null
+              console.warn(
+                '平面图 capability 初始化失败，继续使用基础 Viewer。',
+                floorplanError,
+              )
+            }
+          }
+
+          const panoTagList = payload.presetData?.panoTagList
+          if (panoTagList?.length) {
+            const currentTags = createPanoTagFeature(five, plugins, (id) => {
+              if (!active) return
+              setSelectedTagId(id)
+              setStatus(`已选择空间标签 ${id}`)
+            })
+            tags = currentTags
+            try {
+              await currentTags.load(panoTagList)
+            } catch (tagError) {
+              currentTags.dispose()
+              if (tags === currentTags) tags = null
+              throw tagError
+            }
+          }
+          if (!active) return
+          setFloorplanFeature(floorplan)
+          setReady(true)
+          setStatus(`空间已就绪 · ${payload.workCode}`)
+        })
+      } catch (loadError) {
+        floorplan?.dispose()
+        floorplan = null
+        if (!active) return
+        setFloorplanFeature(null)
+        setError(
+          loadError instanceof Error ? loadError.message : '空间加载失败',
+        )
+      }
+    }
+
+    if (active) void load()
+    return teardown
+  }, [five, plugins, lifetime])
+
+  return (
+    <ViewerOverlay
+      controls={
+        ready ? (
+          <ModeSwitcher
+            five={five}
+            lifetime={lifetime}
+            floorplan={floorplanFeature}
+          />
+        ) : null
+      }
+      error={error}
+      selectedTagId={selectedTagId}
+      status={status}
+      title={workName}
+    />
+  )
+}
+
+export default function App() {
+  return (
+    <main className="app">
+      <SpatialRuntimeProvider>
+        <ViewerScene />
+      </SpatialRuntimeProvider>
+    </main>
+  )
+}

package/templates/viewer/src/features/floorplan/ModelFloorplanFeature.ts

@@ -0,0 +1,141 @@
+import type { Five } from '@realsee/five'
+import ModelFloorplanPlugin, {
+  type ModelFloorplanPluginReturnType,
+} from '@realsee/dnalogel/libs/floorplan/ModelFloorplanPlugin'
+import type { ModelFloorplanServerData } from '../../../shared/model-floorplan'
+import type { SpatialPluginRegistry } from '../../vr/plugins/SpatialPluginRegistry'
+const PLUGIN_NAME = 'dnalogel.modelFloorplan'
+type VisibilityListener = (visible: boolean) => void
+export function createModelFloorplanFeature(
+  five: Five,
+  plugins: SpatialPluginRegistry,
+) {
+  const modelSurface = five.getElement()
+  const wrapper = modelSurface?.parentElement
+  if (!modelSurface || !wrapper) {
+    throw new Error('ModelFloorplanPlugin 找不到 Five DOM 宿主。')
+  }
+  const restoreModelSurface = () => {
+    modelSurface.style.opacity = '1'
+    modelSurface.style.transition = 'none'
+    for (const element of Array.from(wrapper.children)) {
+      if (element instanceof HTMLElement && element.dataset.infive === '1') {
+        element.style.opacity = '1'
+      }
+    }
+  }
+  const candidate = ModelFloorplanPlugin(five, { autoShowEnable: false })
+  let plugin: ModelFloorplanPluginReturnType
+  try {
+    plugin = plugins.register(PLUGIN_NAME, candidate)
+  } catch (error) {
+    try {
+      candidate.dispose()
+    } catch (disposeError) {
+      console.error(
+        'ModelFloorplanPlugin 注册失败后清理候选实例失败。',
+        disposeError,
+      )
+    }
+    throw error
+  }
+  try {
+    plugin.appendTo(wrapper)
+  } catch (error) {
+    const disposeError = plugins.unregister(PLUGIN_NAME, plugin)
+    if (disposeError) {
+      console.error(
+        'ModelFloorplanPlugin 挂载失败后清理实例失败。',
+        disposeError,
+      )
+    }
+    throw error
+  }
+  const visibilityListeners = new Set<VisibilityListener>()
+  const emitVisibility = () => {
+    for (const listener of visibilityListeners) listener(plugin.state.visible)
+  }
+  const stopShow = plugin.hooks.on('show', emitVisibility)
+  const stopHide = plugin.hooks.on('hide', emitVisibility)
+  const stopStateChange = plugin.hooks.on(
+    'stateChange',
+    ({ state, prevState }) => {
+      if (state.visible === prevState?.visible) return
+      if (!state.visible) restoreModelSurface()
+      emitVisibility()
+    },
+  )
+  let loading: Promise<void> | null = null
+  let disposeRequested = false
+  let finalized = false
+  const finalize = () => {
+    if (finalized) return
+    finalized = true
+    restoreModelSurface()
+    visibilityListeners.clear()
+    const disposeError = plugins.unregister(PLUGIN_NAME, plugin)
+    if (disposeError)
+      console.error('ModelFloorplanPlugin 实例清理失败。', disposeError)
+  }
+  return {
+    plugin,
+    get visible() {
+      return plugin.state.visible
+    },
+    subscribeVisibility(listener: VisibilityListener) {
+      visibilityListeners.add(listener)
+      listener(plugin.state.visible)
+      return () => visibilityListeners.delete(listener)
+    },
+    async load(serverData: ModelFloorplanServerData) {
+      if (disposeRequested)
+        throw new Error('ModelFloorplanPlugin feature 已停止。')
+      if (loading)
+        throw new Error('ModelFloorplanPlugin feature 不支持并发加载。')
+      const task = plugin.load(serverData)
+      loading = task
+      try {
+        await task
+      } finally {
+        if (loading === task) loading = null
+        if (disposeRequested) finalize()
+      }
+    },
+    show() {
+      if (disposeRequested)
+        return Promise.reject(
+          new Error('ModelFloorplanPlugin feature 已停止。'),
+        )
+      return plugin
+        .show({ userAction: true, modelOpacity: 0 })
+        .catch((error) => {
+          restoreModelSurface()
+          throw error
+        })
+    },
+    hide() {
+      if (disposeRequested)
+        return Promise.reject(
+          new Error('ModelFloorplanPlugin feature 已停止。'),
+        )
+      return plugin.hide({ userAction: true }).finally(restoreModelSurface)
+    },
+    dispose() {
+      if (disposeRequested) return
+      disposeRequested = true
+      if (plugin.state.visible) {
+        void plugin.hide({ userAction: false }).catch((error) => {
+          console.error('ModelFloorplanPlugin 停止时隐藏平面图失败。', error)
+        })
+      }
+      restoreModelSurface()
+      stopShow()
+      stopHide()
+      stopStateChange()
+      if (!loading) finalize()
+    },
+  }
+}
+export type ModelFloorplanFeature = ReturnType<
+  typeof createModelFloorplanFeature
+>

package/templates/viewer/src/features/navigation/ModeSwitcher.tsx

@@ -0,0 +1,111 @@
+import { useEffect, useState } from 'react'
+import { Five } from '@realsee/five'
+import { Button, Font, HStack, VStack, useDimension } from '@realsee/vapor'
+import type { ModelFloorplanFeature } from '../floorplan/ModelFloorplanFeature'
+import type { SpatialRuntimeLifetime } from '../../vr/five/SpatialRuntimeProvider'
+
+type ViewerTab = 'tour' | 'model' | 'floorplan'
+
+const tabFromFiveMode = (mode: string): ViewerTab =>
+  mode === Five.Mode.Panorama ? 'tour' : 'model'
+
+export function ModeSwitcher({
+  five,
+  lifetime,
+  floorplan,
+}: {
+  five: Five
+  lifetime: SpatialRuntimeLifetime
+  floorplan?: ModelFloorplanFeature | null
+}) {
+  const { match, orientation } = useDimension()
+  const [tab, setTab] = useState<ViewerTab>(() =>
+    floorplan?.visible ? 'floorplan' : tabFromFiveMode(five.currentMode),
+  )
+
+  useEffect(() => {
+    const syncMode = ({ mode }: { mode: string }) => {
+      if (!floorplan?.visible) setTab(tabFromFiveMode(mode))
+    }
+    const releaseMode = lifetime.own(five.on('mode.change', syncMode))
+    const stopVisibility = floorplan?.subscribeVisibility((visible) => {
+      setTab(visible ? 'floorplan' : tabFromFiveMode(five.currentMode))
+    })
+    return () => {
+      stopVisibility?.()
+      releaseMode()
+    }
+  }, [five, floorplan, lifetime])
+
+  const changeTab = async (nextTab: ViewerTab) => {
+    try {
+      await lifetime.runExclusive(async () => {
+        if (nextTab === 'floorplan') {
+          if (!floorplan) return
+          await floorplan.show()
+          return
+        }
+
+        if (floorplan?.visible) await floorplan.hide()
+        if (nextTab === 'model') {
+          await five.changeMode(
+            Five.Mode.Mapview,
+            { longitude: Math.PI / 4, latitude: Math.PI / 5 },
+            { duration: 300 },
+            true,
+          )
+          return
+        }
+        await five.changeMode(Five.Mode.Panorama)
+      })
+    } catch (error) {
+      setTab(
+        floorplan?.visible ? 'floorplan' : tabFromFiveMode(five.currentMode),
+      )
+      if (lifetime.active) console.error(`切换到 ${nextTab} 视图失败。`, error)
+    }
+  }
+
+  const options: Array<{ value: ViewerTab; text: string }> = [
+    { value: 'tour', text: '漫游' },
+    { value: 'model', text: '三维模型' },
+    ...(floorplan ? [{ value: 'floorplan' as const, text: '平面图' }] : []),
+  ]
+  const compact = match('sm') || (match('md') && orientation === 'portrait')
+  const controlWidth = compact
+    ? `min(calc(100vw - 2rem), ${options.length === 3 ? '20rem' : '15rem'})`
+    : options.length === 3
+      ? '26.625rem'
+      : '20rem'
+
+  return (
+    <div className="mode-switcher" role="group" aria-label="空间浏览模式">
+      <Font size={compact ? 'lg' : 'xl'} opacity="80">
+        <HStack
+          width={controlWidth}
+          height={compact ? '3rem' : '5rem'}
+          align={{ horizontal: 'space-around' }}
+        >
+          {options.map((option) => {
+            const selected = option.value === tab
+            return (
+              <VStack key={option.value}>
+                <Button
+                  appearance="shadow"
+                  weight={selected ? 'bold' : 'regular'}
+                  opacity={selected ? '100' : '80'}
+                  onClick={() => void changeTab(option.value)}
+                >
+                  {option.text}
+                </Button>
+                {selected ? (
+                  <div className="mode-switcher-indicator" aria-hidden="true" />
+                ) : null}
+              </VStack>
+            )
+          })}
+        </HStack>
+      </Font>
+    </div>
+  )
+}

package/templates/viewer/src/features/tags/PanoTagFeature.ts

@@ -0,0 +1,110 @@
+import { Five } from '@realsee/five'
+import {
+  PanoTagPlugin,
+  type PanoTagPluginExportInterface,
+  type TagClickParams,
+  type Tags,
+} from '@realsee/dnalogel/libs/PanoTagPlugin'
+import type { SpatialPluginRegistry } from '../../vr/plugins/SpatialPluginRegistry'
+
+const PLUGIN_NAME = 'dnalogel.panoTag'
+
+export type TagPlugin = PanoTagPluginExportInterface
+
+export function createPanoTagFeature(
+  five: Five,
+  plugins: SpatialPluginRegistry,
+  onSelect?: (id: string) => void,
+) {
+  const candidate = PanoTagPlugin(five, {
+    containerZIndex: 2,
+    config: {
+      globalConfig: {
+        initialState: { unfolded: false },
+        unfoldedConfig: { autoUnfold: { enable: false } },
+      },
+      contentTypeConfig: {
+        Image: { unfoldedConfig: { keep: 'folded' } },
+        ImageText: { unfoldedConfig: { keep: 'folded' } },
+        Video: { unfoldedConfig: { keep: 'folded' } },
+        Audio: { unfoldedConfig: { keep: 'folded' } },
+        Panorama: { unfoldedConfig: { keep: 'folded' } },
+        MediaPlane: { unfoldedConfig: { keep: 'folded' } },
+        MediaModel: { unfoldedConfig: { keep: 'folded' } },
+        Model: { unfoldedConfig: { keep: 'folded' } },
+      },
+    },
+  })
+  let plugin: TagPlugin
+  try {
+    plugin = plugins.register(PLUGIN_NAME, candidate)
+  } catch (error) {
+    try {
+      candidate.dispose()
+    } catch (disposeError) {
+      console.error('PanoTag preset 注册失败后清理候选实例失败。', disposeError)
+    }
+    throw error
+  }
+  const unsubscribe = plugin.hooks.on('click', ({ tag }: TagClickParams) =>
+    onSelect?.(String(tag.id)),
+  )
+  let loading: Promise<void> | null = null
+  let disposeRequested = false
+  let finalized = false
+
+  const finalize = () => {
+    if (finalized) return
+    finalized = true
+    const disposeError = plugins.unregister(PLUGIN_NAME, plugin)
+    if (disposeError)
+      console.error('PanoTag preset 实例清理失败。', disposeError)
+  }
+
+  return {
+    plugin,
+    async load(panoTagList: Tags['tagList']) {
+      if (disposeRequested) throw new Error('PanoTag preset feature 已停止。')
+      if (loading) throw new Error('PanoTag preset feature 不支持并发加载。')
+      const task = plugin.load({ tagList: panoTagList })
+      loading = task
+      try {
+        await task
+      } finally {
+        if (loading === task) loading = null
+        if (disposeRequested) finalize()
+      }
+    },
+    dispose() {
+      if (disposeRequested) return
+      disposeRequested = true
+      unsubscribe()
+      if (!loading) finalize()
+    },
+  }
+}
+
+export function getTag(plugin: TagPlugin, id: string) {
+  const numericId = Number(id)
+  return (
+    plugin.getTagById(id) ??
+    (Number.isNaN(numericId) ? undefined : plugin.getTagById(numericId))
+  )
+}
+
+export async function locateTagInCurrentMode(
+  five: Five,
+  plugin: TagPlugin,
+  id: string,
+) {
+  const tag = getTag(plugin, id)
+  if (!tag) throw new Error(`空间标签 ${id} 当前无法定位。`)
+  const targetMode =
+    five.currentMode === Five.Mode.Mapview
+      ? Five.Mode.Mapview
+      : Five.Mode.Panorama
+  await tag.find({ targetMode })
+  plugin.changeUnfoldedById(tag.id, false)
+  await tag.blink({ loop: 4, autoplay: true })
+  return targetMode
+}

package/templates/viewer/src/ui/ViewerOverlay.tsx

@@ -0,0 +1,141 @@
+import type { ReactNode } from 'react'
+import {
+  Layer,
+  Text,
+  TitleBar,
+  Vapor,
+  VStack,
+  ZStack,
+  useDimension,
+  useSaveAreaInsets,
+} from '@realsee/vapor'
+
+export type ViewerOverlayProps = {
+  controls?: ReactNode
+  title?: string | null
+  status: string
+  error?: string | null
+  selectedTagId?: string | null
+}
+
+type ViewerChromeProps = Omit<ViewerOverlayProps, 'title'> & {
+  title?: string | null
+}
+
+const cssSafeInset = (
+  side: 'top' | 'right' | 'bottom' | 'left',
+  vaporInset: number,
+  spacing = '0px',
+) => `calc(env(safe-area-inset-${side}, 0px) + ${vaporInset}px + ${spacing})`
+
+function ViewerChrome({
+  controls,
+  title,
+  status,
+  error,
+  selectedTagId,
+}: ViewerChromeProps) {
+  const saveAreaInsets = useSaveAreaInsets()
+  const { match, orientation } = useDimension()
+  const stackControls =
+    match('sm') || (match('md') && orientation === 'portrait')
+  const topSpacing = match('sm')
+    ? '0.75rem'
+    : match('md') && orientation === 'landscape'
+      ? '0.75rem'
+      : match('md') || match('lg')
+        ? '1.25rem'
+        : '1.875rem'
+  const sideSpacing = match('sm')
+    ? '1rem'
+    : match('md') && orientation === 'landscape'
+      ? '2rem'
+      : match('md') || match('lg')
+        ? '1.5rem'
+        : '2rem'
+  const titleMaxWidth = stackControls
+    ? `calc(100vw - ${sideSpacing} - ${sideSpacing})`
+    : 'min(28rem, calc(50vw - 15rem))'
+  const statusText = `${error ?? status}${selectedTagId ? ` · tag ${selectedTagId}` : ''}`
+  const horizontalPadding = {
+    left: cssSafeInset('left', saveAreaInsets.left, sideSpacing),
+    right: cssSafeInset('right', saveAreaInsets.right, sideSpacing),
+  }
+
+  return (
+    <ZStack width="100%" height="100%" align={{ vertical: 'start' }}>
+      <Layer vignetting />
+      <VStack
+        width="100%"
+        margin={{ top: cssSafeInset('top', saveAreaInsets.top) }}
+        padding={{
+          top: topSpacing,
+          ...horizontalPadding,
+        }}
+      >
+        {title ? (
+          <TitleBar labelMaxWidth={titleMaxWidth}>{title}</TitleBar>
+        ) : null}
+      </VStack>
+      {controls ? (
+        <VStack
+          className="viewer-controls"
+          width="100%"
+          margin={{ top: cssSafeInset('top', saveAreaInsets.top) }}
+          padding={{
+            top: stackControls ? '3.5rem' : '0.25rem',
+            ...horizontalPadding,
+          }}
+          align={{ horizontal: 'center' }}
+        >
+          {controls}
+        </VStack>
+      ) : null}
+      <ZStack
+        width="100%"
+        height="100%"
+        align={{ horizontal: 'start', vertical: 'end' }}
+        padding={{
+          right: cssSafeInset('right', saveAreaInsets.right, '1rem'),
+          bottom: cssSafeInset('bottom', saveAreaInsets.bottom, '1rem'),
+          left: cssSafeInset('left', saveAreaInsets.left, '1rem'),
+        }}
+      >
+        <div
+          className="viewer-status"
+          role={error ? 'alert' : 'status'}
+          aria-live={error ? 'assertive' : 'polite'}
+          aria-atomic="true"
+          title={statusText}
+        >
+          <Text
+            appearance="solid"
+            size="sm"
+            opacity={error ? '100' : '80'}
+            wrap={1}
+            maxWidth="min(32rem, calc(100vw - 2rem))"
+            {...(error ? { color: '#ffd6d6' } : {})}
+          >
+            {statusText}
+          </Text>
+        </div>
+      </ZStack>
+    </ZStack>
+  )
+}
+
+/** DOM-only UI mounted above the native Five canvas; it owns no spatial state or rendering. */
+export function ViewerOverlay(props: ViewerOverlayProps) {
+  return (
+    <div className="dom-overlay">
+      <Vapor
+        className="viewer-vapor"
+        width="100%"
+        height="100%"
+        theme="arc_beauty"
+      >
+        <ViewerChrome {...props} />
+      </Vapor>
+    </div>
+  )
+}