添加VR360播放功能

web/src/components/PlayerControls.tsx

@@ -16,6 +16,7 @@ import {
   PictureInPicture,
   Play,
   Rewind,
+  Rotate3d,
   SkipBack,
   SkipForward,
   Timer,
@@ -24,6 +25,7 @@ import {
 } from 'lucide-react'
 import type { SubtitleTrack } from '../api/subtitles'
 import type { PlaybackQuality } from '../types'
+import type { Vr360Profile } from '../utils/vr360'
 import {
   formatPlaybackRate,
   normalizePlaybackRate,
@@ -116,6 +118,11 @@ type PlayerControlsProps = {
   selectedQuality?: string
   onSelectQuality?: (quality: PlaybackQuality) => void
   showQuality?: boolean
+  /** VR 全景播放配置；非 null 表示当前处于 VR 模式。 */
+  vr360?: Vr360Profile | null
+  /** 是否由文件名/画幅自动识别为 VR 素材（按钮上加一个小圆点提示）。 */
+  vr360Detected?: boolean
+  onToggleVr360?: () => void
   /** Media metadata duration (seconds). Used when HLS only knows transcoded length. */
   knownDuration?: number
   /** Absolute source offset of the current HLS session (seconds). */
@@ -159,6 +166,9 @@ export function PlayerControls({
   selectedQuality = '',
   onSelectQuality,
   showQuality = false,
+  vr360 = null,
+  vr360Detected = false,
+  onToggleVr360,
   knownDuration = 0,
   streamOffset = 0,
   onSeekAbsolute,
@@ -1090,6 +1100,24 @@ export function PlayerControls({
           {danmakuEnabled && <span className="h-1.5 w-1.5 rounded-full bg-lime-400" />}
         </button>
 
+        {/* VR 全景播放开关 */}
+        {onToggleVr360 && (
+          <button
+            onClick={onToggleVr360}
+            className={
+              'flex items-center gap-1.5 rounded-full px-2.5 py-1.5 text-xs font-medium transition ' +
+              (vr360
+                ? 'bg-rose-500/90 text-white hover:bg-rose-500'
+                : 'bg-white/10 text-white/80 hover:bg-white/20')
+            }
+            title={vr360 ? '退出 VR 全景播放' : '切换到 VR 全景播放（可用鼠标或陀螺仪转动视角）'}
+          >
+            <Rotate3d size={15} />
+            <span className="hidden sm:inline">VR</span>
+            {vr360Detected && !vr360 && <span className="h-1.5 w-1.5 rounded-full bg-amber-300" />}
+          </button>
+        )}
+
         <button
           onClick={toggleMute}
           className="rounded-full p-1.5 transition hover:bg-white/15"

web/src/components/Vr360Stage.tsx

@@ -0,0 +1,613 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { PointerEvent as ReactPointerEvent, RefObject } from 'react'
+import { Check, Compass, Minus, Plus, RotateCcw, Settings2, Smartphone } from 'lucide-react'
+
+import {
+  VR360_DEFAULT_FOV,
+  VR360_MAX_FOV,
+  VR360_MIN_FOV,
+  VR360_PROJECTION_OPTIONS,
+  VR360_STEREO_OPTIONS,
+  vr360FrameUv,
+  type Vr360Profile,
+} from '../utils/vr360'
+import {
+  applyViewOffset,
+  cameraForward,
+  cameraFromDeviceOrientation,
+  cameraFromYawPitch,
+  clampNumber,
+  degToRad,
+  forwardPitch,
+  forwardYaw,
+  viewMatrixFromCamera,
+  type Mat3,
+} from '../utils/vr360Math'
+// 只引入类型：渲染器本体走动态 import，普通播放不会下载 WebGL 全景渲染代码。
+import type { Vr360Renderer } from '../utils/vr360Renderer'
+
+// 全景播放舞台：一个覆盖整个播放区域的 WebGL 画布。视频元素本身仍在后台正常
+// 播放（音轨、进度、弹幕、字幕都不受影响），只是画面被贴到了球面上。
+//
+// 视角控制：
+//   1. 鼠标/手指拖拽 → 转动视角（画面跟随手指），滚轮/双指捏合 → 变焦；
+//   2. 手机陀螺仪 → 转动设备即转动视角。iOS 13+ 必须在用户手势里调用
+//      DeviceOrientationEvent.requestPermission，所以这里做成显式按钮。
+
+type ViewState = {
+  /** 拖拽模式下的方位角（弧度，0 = 默认正前方）。 */
+  yaw: number
+  /** 拖拽模式下的俯仰角（弧度，+ 为抬头）。 */
+  pitch: number
+  fov: number
+  /** 陀螺仪是否接管视角。 */
+  gyroActive: boolean
+  /** 最近一次设备姿态对应的相机旋转矩阵。 */
+  deviceCamera: Mat3 | null
+  gyroYawOffset: number
+  gyroPitchOffset: number
+}
+
+type PointerState = {
+  x: number
+  y: number
+  startX: number
+  startY: number
+  startAt: number
+  moved: boolean
+}
+
+type GyroState = 'off' | 'pending' | 'active' | 'denied' | 'unsupported' | 'unavailable'
+
+type Vr360StageProps = {
+  videoRef: RefObject<HTMLVideoElement>
+  profile: Vr360Profile
+  /** 控制栏是否可见：不可见时隐藏 VR 自身的浮层按钮。 */
+  uiVisible: boolean
+  /** 轻触画面（未发生拖拽）时回调，与普通播放一致：唤出控制栏或切换播放。 */
+  onSurfaceTap: () => void
+  onReady: () => void
+  onError: (message: string) => void
+  /** 用户调整投影方式/立体布局时回调，由播放页保存为下次进入的默认值。 */
+  onProfileChange?: (profile: Vr360Profile) => void
+}
+
+/** 每像素拖拽对应的转角（弧度）。视场角越小时画面越「拉近」，拖拽也应更细腻。 */
+const DRAG_RAD_PER_PIXEL = 0.0035
+const TAP_MAX_DISTANCE = 8
+const TAP_MAX_DURATION_MS = 400
+const GYRO_PROBE_MS = 1500
+const PITCH_LIMIT = Math.PI / 2 - 0.03
+const WHEEL_ZOOM_SPEED = 0.0015
+
+function screenOrientationAngle(): number {
+  if (
+    typeof screen !== 'undefined' &&
+    screen.orientation &&
+    typeof screen.orientation.angle === 'number'
+  ) {
+    return screen.orientation.angle
+  }
+  const legacy = (window as unknown as { orientation?: number }).orientation
+  return typeof legacy === 'number' ? legacy : 0
+}
+
+type DeviceOrientationEventConstructor = {
+  requestPermission?: () => Promise<'granted' | 'denied' | 'default'>
+}
+
+function gyroStateHint(state: GyroState): string {
+  if (state === 'active') return '陀螺仪已开启：转动设备即可改变视角'
+  if (state === 'pending') return '正在等待陀螺仪数据…'
+  if (state === 'denied') return '陀螺仪权限被拒绝，请在浏览器设置里允许「运动与方向」访问'
+  if (state === 'unavailable') return '没有收到陀螺仪数据，当前设备可能不支持'
+  if (state === 'unsupported') return '当前浏览器不支持陀螺仪'
+  return ''
+}
+
+export function Vr360Stage({
+  videoRef,
+  profile,
+  uiVisible,
+  onSurfaceTap,
+  onReady,
+  onError,
+  onProfileChange,
+}: Vr360StageProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const rendererRef = useRef<Vr360Renderer | null>(null)
+  const viewRef = useRef<ViewState>({
+    yaw: 0,
+    pitch: 0,
+    fov: VR360_DEFAULT_FOV,
+    gyroActive: false,
+    deviceCamera: null,
+    gyroYawOffset: 0,
+    gyroPitchOffset: 0,
+  })
+  const dirtyRef = useRef(true)
+  const readyRef = useRef(false)
+  const pointersRef = useRef(new Map<number, PointerState>())
+  const pinchDistanceRef = useRef<number | null>(null)
+  const alignmentRef = useRef<{ yaw: number; pitch: number } | null>(null)
+  const gyroProbeRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const absoluteSeenRef = useRef(false)
+  const profileRef = useRef(profile)
+  const [gyroState, setGyroState] = useState<GyroState>('off')
+  const [fovHint, setFovHint] = useState(VR360_DEFAULT_FOV)
+  const [settingsOpen, setSettingsOpen] = useState(false)
+
+  // 回调放进 ref：渲染器只在挂载时创建一次，不因父组件重渲染而重建。
+  const callbacksRef = useRef({ onSurfaceTap, onReady, onError })
+  useEffect(() => {
+    callbacksRef.current = { onSurfaceTap, onReady, onError }
+  }, [onSurfaceTap, onReady, onError])
+
+  const markDirty = useCallback(() => {
+    dirtyRef.current = true
+  }, [])
+
+  // 当前相机姿态：陀螺仪接管时以设备姿态为基准叠加拖拽偏移，否则纯拖拽角度。
+  const currentCamera = useCallback((): Mat3 => {
+    const view = viewRef.current
+    if (view.gyroActive && view.deviceCamera) {
+      return applyViewOffset(view.deviceCamera, view.gyroYawOffset, view.gyroPitchOffset)
+    }
+    return cameraFromYawPitch(view.yaw, view.pitch)
+  }, [])
+
+  const draw = useCallback(() => {
+    const renderer = rendererRef.current
+    if (!renderer) return
+    renderer.setView(viewMatrixFromCamera(currentCamera()))
+    renderer.setFov(viewRef.current.fov)
+    renderer.draw()
+    if (!readyRef.current) {
+      // 第一帧真正画出来之后才通知上层：渲染失败时上层会退出 VR 模式。
+      readyRef.current = true
+      callbacksRef.current.onReady()
+    }
+  }, [currentCamera])
+
+  const applyProfile = useCallback((renderer: Vr360Renderer, next: Vr360Profile) => {
+    renderer.setProjection(next.projection)
+    const { scale, offset } = vr360FrameUv(next.stereo)
+    renderer.setFrameUv(scale, offset)
+    dirtyRef.current = true
+  }, [])
+
+  // 创建渲染器（懒加载 WebGL 模块，普通播放不会下载全景渲染代码）。
+  useEffect(() => {
+    const canvas = canvasRef.current
+    const video = videoRef.current
+    if (!canvas || !video) return
+    let cancelled = false
+    let created: Vr360Renderer | null = null
+
+    void import('../utils/vr360Renderer')
+      .then((module) => {
+        if (cancelled) return
+        created = module.createVr360Renderer(canvas, video, {
+          onContextLost: () => callbacksRef.current.onError('VR 渲染上下文已丢失，已退出 VR 播放'),
+          onTextureError: () => callbacksRef.current.onError('无法读取视频画面用于 VR 渲染'),
+        })
+        if (!created) {
+          callbacksRef.current.onError('当前浏览器不支持 WebGL，无法使用 VR 播放')
+          return
+        }
+        rendererRef.current = created
+        const rect = canvas.getBoundingClientRect()
+        created.resize(rect.width, rect.height)
+        applyProfile(created, profileRef.current)
+      })
+      .catch(() => {
+        if (!cancelled) callbacksRef.current.onError('VR 渲染组件加载失败')
+      })
+
+    return () => {
+      cancelled = true
+      rendererRef.current = null
+      created?.dispose()
+    }
+  }, [applyProfile, videoRef])
+
+  // 投影方式/立体布局变化时重建网格与 UV 裁切。
+  useEffect(() => {
+    profileRef.current = profile
+    const renderer = rendererRef.current
+    if (renderer) applyProfile(renderer, profile)
+  }, [applyProfile, profile])
+
+  // 画布尺寸跟随舞台（窗口缩放、全屏切换、首次布局）。
+  // 观测父容器而不是画布自身：画布尺寸由 CSS 撑满父容器，观测自身会在
+  // 「设置绘制缓冲区分辨率 → 布局变化 → 再次触发观测」之间来回放大。
+  useEffect(() => {
+    const canvas = canvasRef.current
+    if (!canvas) return
+    const target = canvas.parentElement ?? canvas
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0]
+      if (!entry) return
+      rendererRef.current?.resize(entry.contentRect.width, entry.contentRect.height)
+      markDirty()
+    })
+    observer.observe(target)
+    const rect = target.getBoundingClientRect()
+    rendererRef.current?.resize(rect.width, rect.height)
+    return () => observer.disconnect()
+  }, [markDirty])
+
+  // 渲染循环：requestVideoFrameCallback 标记「有新画面」，rAF 按需绘制。
+  // 暂停且无输入时不出图，避免持续占用 GPU。
+  useEffect(() => {
+    let handle = 0
+    let cancelled = false
+    const video = videoRef.current as
+      | (HTMLVideoElement & { requestVideoFrameCallback?: (callback: () => void) => number })
+      | null
+
+    if (video && typeof video.requestVideoFrameCallback === 'function') {
+      const onVideoFrame = () => {
+        if (cancelled) return
+        dirtyRef.current = true
+        video.requestVideoFrameCallback?.(onVideoFrame)
+      }
+      video.requestVideoFrameCallback(onVideoFrame)
+    }
+
+    const tick = () => {
+      if (cancelled) return
+      handle = requestAnimationFrame(tick)
+      if (!dirtyRef.current) return
+      dirtyRef.current = false
+      draw()
+    }
+    handle = requestAnimationFrame(tick)
+    return () => {
+      cancelled = true
+      cancelAnimationFrame(handle)
+    }
+  }, [draw, videoRef])
+
+  // 设备姿态 → 相机姿态。第一帧有效数据到达时把视角对齐过去，避免画面跳动。
+  const handleOrientation = useCallback((event: DeviceOrientationEvent) => {
+    if (event.alpha === null && event.beta === null && event.gamma === null) return
+    if (event.type === 'deviceorientationabsolute') absoluteSeenRef.current = true
+    // 同时收到绝对与相对事件时以绝对朝向为准（方位角才有意义）。
+    else if (absoluteSeenRef.current) return
+
+    const camera = cameraFromDeviceOrientation(
+      degToRad(event.alpha ?? 0),
+      degToRad(event.beta ?? 0),
+      degToRad(event.gamma ?? 0),
+      degToRad(screenOrientationAngle()),
+    )
+    const view = viewRef.current
+    view.deviceCamera = camera
+
+    const alignment = alignmentRef.current
+    if (alignment) {
+      const forward = cameraForward(camera)
+      view.gyroYawOffset = alignment.yaw - forwardYaw(forward)
+      view.gyroPitchOffset = clampNumber(alignment.pitch - forwardPitch(forward), -1.2, 1.2)
+      alignmentRef.current = null
+      if (gyroProbeRef.current) {
+        clearTimeout(gyroProbeRef.current)
+        gyroProbeRef.current = null
+      }
+      setGyroState('active')
+    }
+
+    view.gyroActive = true
+    dirtyRef.current = true
+  }, [])
+
+  const stopGyro = useCallback(() => {
+    window.removeEventListener('deviceorientation', handleOrientation)
+    window.removeEventListener('deviceorientationabsolute', handleOrientation)
+    if (gyroProbeRef.current) {
+      clearTimeout(gyroProbeRef.current)
+      gyroProbeRef.current = null
+    }
+    alignmentRef.current = null
+    absoluteSeenRef.current = false
+  }, [handleOrientation])
+
+  const startGyro = useCallback(() => {
+    alignmentRef.current = { yaw: viewRef.current.yaw, pitch: viewRef.current.pitch }
+    absoluteSeenRef.current = false
+    window.addEventListener('deviceorientation', handleOrientation)
+    window.addEventListener('deviceorientationabsolute', handleOrientation)
+    // 桌面浏览器/无陀螺仪设备会一直收不到事件，超时后提示并回退到拖拽模式。
+    gyroProbeRef.current = setTimeout(() => {
+      gyroProbeRef.current = null
+      if (alignmentRef.current) {
+        stopGyro()
+        setGyroState('unavailable')
+      }
+    }, GYRO_PROBE_MS)
+  }, [handleOrientation, stopGyro])
+
+  const toggleGyro = useCallback(() => {
+    if (gyroState === 'active' || gyroState === 'pending') {
+      // 关闭陀螺仪时用当前合成视角续上，画面不会跳。
+      const forward = cameraForward(currentCamera())
+      viewRef.current.yaw = forwardYaw(forward)
+      viewRef.current.pitch = clampNumber(forwardPitch(forward), -PITCH_LIMIT, PITCH_LIMIT)
+      viewRef.current.gyroActive = false
+      viewRef.current.gyroYawOffset = 0
+      viewRef.current.gyroPitchOffset = 0
+      stopGyro()
+      setGyroState('off')
+      markDirty()
+      return
+    }
+
+    const orientationEvent = (
+      window as unknown as { DeviceOrientationEvent?: DeviceOrientationEventConstructor }
+    ).DeviceOrientationEvent
+    if (!orientationEvent) {
+      setGyroState('unsupported')
+      return
+    }
+    setGyroState('pending')
+    const requestPermission = orientationEvent.requestPermission
+    if (typeof requestPermission !== 'function') {
+      startGyro()
+      return
+    }
+    // iOS 13+ 必须在用户手势里申请权限，这里由按钮点击直接触发。
+    void requestPermission
+      .call(orientationEvent)
+      .then((result) => {
+        if (result === 'granted') startGyro()
+        else setGyroState('denied')
+      })
+      .catch(() => setGyroState('denied'))
+  }, [currentCamera, gyroState, markDirty, startGyro, stopGyro])
+
+  useEffect(() => () => stopGyro(), [stopGyro])
+
+  const zoomBy = useCallback(
+    (factor: number) => {
+      const view = viewRef.current
+      view.fov = clampNumber(view.fov * factor, VR360_MIN_FOV, VR360_MAX_FOV)
+      setFovHint(view.fov)
+      markDirty()
+    },
+    [markDirty],
+  )
+
+  const resetView = useCallback(() => {
+    const view = viewRef.current
+    view.yaw = 0
+    view.pitch = 0
+    view.fov = VR360_DEFAULT_FOV
+    view.gyroYawOffset = 0
+    view.gyroPitchOffset = 0
+    setFovHint(view.fov)
+    markDirty()
+  }, [markDirty])
+
+  const pinchDistance = useCallback((): number => {
+    const pointers = [...pointersRef.current.values()]
+    if (pointers.length < 2) return 0
+    return Math.hypot(pointers[0].x - pointers[1].x, pointers[0].y - pointers[1].y)
+  }, [])
+
+  const handlePointerDown = (event: ReactPointerEvent<HTMLCanvasElement>) => {
+    try {
+      event.currentTarget.setPointerCapture?.(event.pointerId)
+    } catch {
+      // 某些环境（合成事件、非活跃指针）会抛 InvalidPointerId，退化为普通拖拽即可。
+    }
+    pointersRef.current.set(event.pointerId, {
+      x: event.clientX,
+      y: event.clientY,
+      startX: event.clientX,
+      startY: event.clientY,
+      startAt: Date.now(),
+      moved: false,
+    })
+    if (pointersRef.current.size === 2) {
+      pinchDistanceRef.current = pinchDistance()
+      // 双指手势一律不算轻触，避免捏合缩放时误触发播放/暂停。
+      for (const pointer of pointersRef.current.values()) pointer.moved = true
+    }
+  }
+
+  const handlePointerMove = (event: ReactPointerEvent<HTMLCanvasElement>) => {
+    const pointer = pointersRef.current.get(event.pointerId)
+    if (!pointer) return
+    const dx = event.clientX - pointer.x
+    const dy = event.clientY - pointer.y
+    pointer.x = event.clientX
+    pointer.y = event.clientY
+    if (
+      Math.hypot(event.clientX - pointer.startX, event.clientY - pointer.startY) > TAP_MAX_DISTANCE
+    ) {
+      pointer.moved = true
+    }
+
+    if (pointersRef.current.size >= 2) {
+      const distance = pinchDistance()
+      const previous = pinchDistanceRef.current
+      pinchDistanceRef.current = distance
+      if (previous && distance > 0) zoomBy(previous / distance)
+      return
+    }
+
+    const view = viewRef.current
+    const scale = DRAG_RAD_PER_PIXEL * (view.fov / VR360_DEFAULT_FOV)
+    if (view.gyroActive && view.deviceCamera) {
+      view.gyroYawOffset -= dx * scale
+      view.gyroPitchOffset = clampNumber(
+        view.gyroPitchOffset + dy * scale,
+        -PITCH_LIMIT,
+        PITCH_LIMIT,
+      )
+    } else {
+      view.yaw -= dx * scale
+      view.pitch = clampNumber(view.pitch + dy * scale, -PITCH_LIMIT, PITCH_LIMIT)
+    }
+    markDirty()
+  }
+
+  const endPointer = (event: ReactPointerEvent<HTMLCanvasElement>) => {
+    const pointer = pointersRef.current.get(event.pointerId)
+    pointersRef.current.delete(event.pointerId)
+    if (pointersRef.current.size < 2) pinchDistanceRef.current = null
+    if (!pointer) return
+    const isTap =
+      !pointer.moved &&
+      Date.now() - pointer.startAt <= TAP_MAX_DURATION_MS &&
+      pointersRef.current.size === 0
+    if (isTap) onSurfaceTap()
+  }
+
+  useEffect(() => {
+    const canvas = canvasRef.current
+    if (!canvas) return
+    const onWheel = (event: WheelEvent) => {
+      event.preventDefault()
+      zoomBy(1 + event.deltaY * WHEEL_ZOOM_SPEED)
+    }
+    canvas.addEventListener('wheel', onWheel, { passive: false })
+    return () => canvas.removeEventListener('wheel', onWheel)
+  }, [zoomBy])
+
+  const hint = gyroStateHint(gyroState)
+
+  return (
+    <>
+      <canvas
+        ref={canvasRef}
+        data-vr360-surface
+        className="absolute inset-0 h-full w-full cursor-grab touch-none select-none active:cursor-grabbing"
+        onPointerDown={handlePointerDown}
+        onPointerMove={handlePointerMove}
+        onPointerUp={endPointer}
+        onPointerCancel={endPointer}
+        // 轻触由指针逻辑自己处理（拖动时不能误触发播放/暂停），
+        // 同时阻止冒泡到舞台的点击逻辑，避免一次触摸切换两次播放状态。
+        onClick={(event) => event.stopPropagation()}
+      />
+      <div
+        className={`pointer-events-none absolute inset-x-0 top-2 z-20 flex flex-col items-center gap-1.5 px-2 transition-opacity duration-300 ${
+          uiVisible ? 'opacity-100' : 'opacity-0'
+        }`}
+      >
+        <div className="pointer-events-auto flex flex-wrap items-center justify-center gap-1.5 rounded-2xl border border-white/15 bg-black/65 px-2 py-1.5 text-white shadow-2xl backdrop-blur">
+          <button
+            type="button"
+            onClick={toggleGyro}
+            className={`flex items-center gap-1.5 rounded-full px-2.5 py-1 text-xs font-medium transition ${
+              gyroState === 'active'
+                ? 'bg-rose-500/90 text-white hover:bg-rose-500'
+                : 'bg-white/10 text-white/85 hover:bg-white/20'
+            }`}
+            title="用手机陀螺仪转动视角"
+          >
+            <Smartphone size={14} />
+            陀螺仪
+            {gyroState === 'active' && <Compass size={13} className="text-white/85" />}
+          </button>
+          <button
+            type="button"
+            onClick={resetView}
+            className="flex items-center gap-1.5 rounded-full bg-white/10 px-2.5 py-1 text-xs font-medium text-white/85 transition hover:bg-white/20"
+            title="恢复默认视角与视场角"
+          >
+            <RotateCcw size={14} />
+            重置
+          </button>
+          <button
+            type="button"
+            onClick={() => setSettingsOpen((open) => !open)}
+            className={`flex items-center gap-1.5 rounded-full px-2.5 py-1 text-xs font-medium transition ${
+              settingsOpen
+                ? 'bg-rose-500/90 text-white hover:bg-rose-500'
+                : 'bg-white/10 text-white/85 hover:bg-white/20'
+            }`}
+            title="投影方式与画幅布局"
+          >
+            <Settings2 size={14} />
+            画面
+          </button>
+          <div className="flex items-center gap-0.5">
+            <button
+              type="button"
+              onClick={() => zoomBy(1.15)}
+              className="rounded-full p-1.5 transition hover:bg-white/15"
+              title="视野拉远"
+            >
+              <Minus size={15} />
+            </button>
+            <span className="w-9 text-center text-[10px] tabular-nums text-white/75">
+              {(VR360_DEFAULT_FOV / fovHint).toFixed(1)}×
+            </span>
+            <button
+              type="button"
+              onClick={() => zoomBy(1 / 1.15)}
+              className="rounded-full p-1.5 transition hover:bg-white/15"
+              title="视野拉近"
+            >
+              <Plus size={15} />
+            </button>
+          </div>
+        </div>
+        <p className="pointer-events-none rounded-full bg-black/45 px-3 py-1 text-[10px] text-white/70 backdrop-blur">
+          {hint || '拖动旋转视角 · 滚轮或双指缩放'}
+        </p>
+        {settingsOpen ? (
+          <div className="pointer-events-auto w-[min(92vw,420px)] rounded-2xl border border-white/15 bg-black/75 px-3 py-2.5 text-white shadow-2xl backdrop-blur">
+            <p className="mb-1.5 text-[10px] uppercase tracking-wide text-white/45">投影方式</p>
+            <div className="flex flex-wrap gap-1.5">
+              {VR360_PROJECTION_OPTIONS.map(([value, label]) => (
+                <button
+                  key={value}
+                  type="button"
+                  onClick={() => onProfileChange?.({ ...profile, projection: value })}
+                  className={`flex items-center gap-1 rounded-lg px-2.5 py-1 text-[11px] transition ${
+                    profile.projection === value
+                      ? 'bg-rose-500/25 text-rose-200'
+                      : 'bg-white/5 text-white/75 hover:bg-white/15'
+                  }`}
+                >
+                  {profile.projection === value && <Check size={11} />}
+                  {label}
+                </button>
+              ))}
+            </div>
+            <p className="mb-1.5 mt-2.5 text-[10px] uppercase tracking-wide text-white/45">
+              画幅布局
+            </p>
+            <div className="flex flex-wrap gap-1.5">
+              {VR360_STEREO_OPTIONS.map(([value, label]) => (
+                <button
+                  key={value}
+                  type="button"
+                  onClick={() => onProfileChange?.({ ...profile, stereo: value })}
+                  className={`flex items-center gap-1 rounded-lg px-2.5 py-1 text-[11px] transition ${
+                    profile.stereo === value
+                      ? 'bg-rose-500/25 text-rose-200'
+                      : 'bg-white/5 text-white/75 hover:bg-white/15'
+                  }`}
+                >
+                  {profile.stereo === value && <Check size={11} />}
+                  {label}
+                </button>
+              ))}
+            </div>
+            {profile.stereo !== 'mono' && (
+              <p className="mt-2 text-[10px] leading-relaxed text-white/45">
+                左右/上下并排素材在当前屏幕上只显示左眼画面；真正的双眼立体画面需要 VR
+                头显（WebXR）。
+              </p>
+            )}
+          </div>
+        ) : null}
+      </div>
+    </>
+  )
+}

web/src/pages/PlayerPage.tsx

@@ -42,6 +42,13 @@ import { PlayerDanmakuPanel } from '../components/PlayerDanmakuPanel'
 import { PlayerPlaylistPanel } from '../components/PlayerPlaylistPanel'
 import { MediaVersionSwitcher } from '../components/MediaVersionSwitcher'
 import { mediaVersionsOf } from '../utils/mediaVersion'
+import {
+  detectVr360Profile,
+  loadVr360Preference,
+  saveVr360Preference,
+  type Vr360Detection,
+  type Vr360Profile,
+} from '../utils/vr360'
 
 // Fullscreen, dark-themed video page.
 //
@@ -96,6 +103,11 @@ export function PlayerPage() {
   const fallbackTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
   const [media, setMedia] = useState<Media | null>(null)
+  // VR 全景播放：null = 普通播放。识别结果与用户开关只存本机，
+  // 不改动数据库，换设备/换浏览器不会互相影响。
+  const [vr360, setVr360] = useState<Vr360Profile | null>(null)
+  const [vr360Detected, setVr360Detected] = useState(false)
+  const vr360TouchedRef = useRef(false)
   const [mode, setMode] = useState<PlayerMode>('direct')
   const [subs, setSubs] = useState<SubtitleTrack[]>([])
   const [subtitleIndex, setSubtitleIndex] = useState<number>(0)
@@ -458,6 +470,9 @@ export function PlayerPage() {
   useEffect(() => {
     setMedia(null)
     setLoadError('')
+    vr360TouchedRef.current = false
+    setVr360(null)
+    setVr360Detected(false)
     setHlsStartSec(0)
     setPlaybackInfo(null)
     setHlsSource('local')
@@ -537,6 +552,68 @@ export function PlayerPage() {
     }
   }, [id, modeParam, directOnly])
 
+  // VR 全景素材识别：只在用户没手动改过开关时自动进入 VR 模式。
+  // 识别完全基于文件名/路径关键词与画幅比例，误判时点一下 VR 按钮即可退出。
+  useEffect(() => {
+    if (!media || media.id !== id) return
+    const detection = detectVr360Profile({
+      title: media.title,
+      originalName: media.original_name,
+      path: media.path,
+      relativePath: media.relative_path,
+      width: media.width,
+      height: media.height,
+    })
+    setVr360Detected(detection.confident)
+    if (vr360TouchedRef.current) return
+    const preference = loadVr360Preference()
+    if (!preference.autoDetect || !detection.confident) {
+      setVr360(null)
+      return
+    }
+    if (detection.profile.projection !== preference.profile.projection) {
+      // 投影方式由文件名决定（360 / 180 / 鱼眼），记住它作为下次的默认值。
+      saveVr360Preference({ ...preference, profile: detection.profile })
+    }
+    setVr360(detection.profile)
+  }, [id, media])
+
+  const toggleVr360 = useCallback(() => {
+    vr360TouchedRef.current = true
+    if (vr360) {
+      setVr360(null)
+      return
+    }
+    const current = mediaRef.current
+    const detection: Vr360Detection | null = current
+      ? detectVr360Profile({
+          title: current.title,
+          originalName: current.original_name,
+          path: current.path,
+          relativePath: current.relative_path,
+          width: current.width,
+          height: current.height,
+        })
+      : null
+    const preference = loadVr360Preference()
+    const profile = detection?.profile ?? preference.profile
+    saveVr360Preference({ ...preference, profile })
+    setVr360(profile)
+  }, [vr360])
+
+  const changeVr360Profile = useCallback((profile: Vr360Profile) => {
+    vr360TouchedRef.current = true
+    setVr360(profile)
+    saveVr360Preference({ ...loadVr360Preference(), profile })
+  }, [])
+
+  const handleVr360Error = useCallback((message: string) => {
+    vr360TouchedRef.current = true
+    setVr360(null)
+    setPlayerError(message)
+    toast.error(message)
+  }, [])
+
   // Wire up the actual <video> element when we know the mode.
   // Depend on media.id (not the media object): refreshing duration after
   // MANIFEST_PARSED must not remount HLS or it storms EnsureJob / DELETE.
@@ -1499,6 +1576,11 @@ export function PlayerPage() {
         showQuality={showQuality}
         waiting={cloudWaiting}
         waitingMessage={cloudWaitMessage}
+        vr360={vr360}
+        vr360Detected={vr360Detected}
+        onToggleVr360={toggleVr360}
+        onVr360ProfileChange={changeVr360Profile}
+        onVr360Error={handleVr360Error}
         playlistPanel={
           <PlayerPlaylistPanel
             open={playlistOpen}

web/src/pages/PlayerVideoStage.tsx

@@ -12,6 +12,8 @@ import {
 import { AssSubtitleStage } from '../components/AssSubtitleStage'
 import { DanmakuStage } from '../components/DanmakuStage'
 import { PlayerControls } from '../components/PlayerControls'
+import { Vr360Stage } from '../components/Vr360Stage'
+import type { Vr360Profile } from '../utils/vr360'
 import {
   subtitleTextStyle,
   type SubtitlePosition,
@@ -186,6 +188,13 @@ type PlayerVideoStageProps = {
   selectedQuality?: string
   onSelectQuality?: (quality: PlaybackQuality) => void
   showQuality?: boolean
+  /** VR 全景播放配置；非 null 表示当前处于 VR 模式。 */
+  vr360?: Vr360Profile | null
+  /** 是否由文件名/画幅自动识别出 VR 素材（用于在菜单里提示）。 */
+  vr360Detected?: boolean
+  onToggleVr360?: () => void
+  onVr360ProfileChange?: (profile: Vr360Profile) => void
+  onVr360Error?: (message: string) => void
   waiting?: boolean
   waitingMessage?: string
 }
@@ -241,6 +250,11 @@ export function PlayerVideoStage({
   selectedQuality = '',
   onSelectQuality,
   showQuality = false,
+  vr360 = null,
+  vr360Detected = false,
+  onToggleVr360,
+  onVr360ProfileChange,
+  onVr360Error,
   waiting = false,
   waitingMessage = '',
 }: PlayerVideoStageProps) {
@@ -248,6 +262,8 @@ export function PlayerVideoStage({
   const [videoRatio, setVideoRatio] = useState<number | null>(null)
   const [stageRect, setStageRect] = useState<{ width: number; height: number } | null>(null)
   const [controlsVisible, setControlsVisible] = useState(true)
+  // VR 渲染器是否已经画出第一帧（在此之前给出「正在启动」提示，避免只看到黑屏）。
+  const [vrReady, setVrReady] = useState(false)
   const revealControlsOnlyRef = useRef(false)
   // 当前展示的字幕文本（由自定义字幕层渲染，100% 透明无黑框）
   const [activeCues, setActiveCues] = useState<SubtitleCue[]>([])
@@ -270,6 +286,11 @@ export function PlayerVideoStage({
     setAssFallbackPath(null)
   }, [media?.id, activeSubtitleTrack?.path, subs])
 
+  // 切换媒体或 VR 配置后重新等待渲染器的第一帧。
+  useEffect(() => {
+    setVrReady(false)
+  }, [media?.id, vr360?.projection, vr360?.stereo])
+
   useEffect(() => {
     const selectedTrack = subs[subtitleIndex]
     let cancelled = false
@@ -392,7 +413,9 @@ export function PlayerVideoStage({
   const handleStagePointerDown = (event: PointerEvent<HTMLDivElement>) => {
     revealControlsOnlyRef.current = event.pointerType === 'touch' && !controlsVisible
   }
-  const handleStageClick = () => {
+  // 舞台任意位置的「激活」（轻触/单击）：移动端控制栏隐藏时首次轻触只唤出
+  // 控制栏，控制栏已显示时再次轻触才切换播放/暂停。
+  const handleSurfaceActivate = () => {
     if (revealControlsOnlyRef.current) {
       revealControlsOnlyRef.current = false
       setControlsVisible(true)
@@ -550,7 +573,14 @@ export function PlayerVideoStage({
       : true
 
   const assTrack = subtitleIndex >= 0 ? subs[subtitleIndex] : undefined
-  const wrapperStyle = videoRatio
+  // VR 模式下画面由 WebGL 画布输出，舞台窗口本身就是「镜头」，
+  // 不再按视频宽高比留黑边。
+  const wrapperStyle = vr360
+    ? {
+        width: '100%',
+        height: '100%',
+      }
+    : videoRatio
       ? {
           aspectRatio: `${videoRatio}`,
           width: isWiderThanStage ? '100%' : 'auto',
@@ -569,7 +599,7 @@ export function PlayerVideoStage({
       data-player-stage
       className="relative flex h-full w-full flex-1 items-center justify-center overflow-hidden bg-black"
       onPointerDown={handleStagePointerDown}
-      onClick={handleStageClick}
+      onClick={handleSurfaceActivate}
       onDoubleClick={toggleFullscreen}
     >
       {media ? (
@@ -602,6 +632,18 @@ export function PlayerVideoStage({
                   )
                 })}
             </video>
+            {vr360 ? (
+              <Vr360Stage
+                key={`${media.id}:vr360`}
+                videoRef={videoRef}
+                profile={vr360}
+                uiVisible={controlsVisible}
+                onSurfaceTap={handleSurfaceActivate}
+                onReady={() => setVrReady(true)}
+                onError={(message) => onVr360Error?.(message)}
+                onProfileChange={onVr360ProfileChange}
+              />
+            ) : null}
             <DanmakuStage
               key={media.id}
               media={media}
@@ -692,6 +734,9 @@ export function PlayerVideoStage({
             selectedQuality={selectedQuality}
             onSelectQuality={onSelectQuality}
             showQuality={showQuality}
+            vr360={vr360}
+            vr360Detected={vr360Detected}
+            onToggleVr360={onToggleVr360}
           />
           {danmakuPanel}
           {playlistPanel}
@@ -701,6 +746,14 @@ export function PlayerVideoStage({
       ) : (
         <p className="text-sand-500">加载中…</p>
       )}
+      {vr360 && media && !vrReady ? (
+        <div className="pointer-events-none absolute inset-0 z-30 flex items-center justify-center bg-black/60">
+          <div className="flex items-center gap-2 rounded-full border border-white/15 bg-black/80 px-5 py-3 text-sm text-white shadow-2xl backdrop-blur">
+            <Loader2 className="animate-spin text-rose-400" size={18} />
+            正在启动 VR 全景渲染…
+          </div>
+        </div>
+      ) : null}
       {playerError ? (
         <div className="absolute bottom-20 left-1/2 w-[min(92vw,720px)] -translate-x-1/2 rounded-2xl border border-white/15 bg-black/75 px-5 py-4 text-sm text-white shadow-2xl backdrop-blur">
           {playerError}

web/src/utils/vr360.test.ts

@@ -0,0 +1,162 @@
+import {
+  detectVr360Profile,
+  normalizeVr360Profile,
+  sameVr360Profile,
+  vr360FrameUv,
+  type Vr360Profile,
+} from './vr360.ts'
+import {
+  applyDirection,
+  applyViewOffset,
+  cameraForward,
+  cameraFromDeviceOrientation,
+  cameraFromYawPitch,
+  forwardPitch,
+  forwardYaw,
+  multiply3,
+  perspectiveMatrix,
+  rotationY,
+  rotationZ,
+  transpose3,
+  viewMatrixFromCamera,
+} from './vr360Math.ts'
+
+function check(name: string, condition: boolean) {
+  if (!condition) throw new Error(`vr360: ${name}`)
+}
+
+function close(a: number, b: number, tolerance = 1e-6): boolean {
+  return Math.abs(a - b) <= tolerance
+}
+
+function closeAll(a: number[], b: number[], tolerance = 1e-6): boolean {
+  return a.length === b.length && a.every((value, index) => close(value, b[index], tolerance))
+}
+
+function profileOf(profile: Vr360Profile): string {
+  return `${profile.projection}/${profile.stereo}`
+}
+
+// ---------- 命名/画幅识别 ----------
+
+const plain = detectVr360Profile({ title: '普通电影', path: '/media/电影/movie.mkv', width: 1920, height: 1080 })
+check('普通素材不自动进入 VR', !plain.confident)
+check('普通素材默认 360 单眼', profileOf(plain.profile) === 'equirect360/mono')
+
+const pano360 = detectVr360Profile({
+  title: '全景演示',
+  path: '/media/360/equirect_demo.mp4',
+  width: 3840,
+  height: 1920,
+})
+check('360 关键词可识别', pano360.confident && pano360.profile.projection === 'equirect360')
+check('2:1 的 360 保持单眼', pano360.profile.stereo === 'mono')
+
+const vr360Sbs = detectVr360Profile({ path: '/media/vr/vr360-sbs-8k.mp4', width: 7680, height: 1920 })
+check('4:1 画幅识别为左右并排', vr360Sbs.profile.stereo === 'sbs')
+
+const ou360 = detectVr360Profile({ path: '/media/vr/pano360-ou.mp4', width: 3840, height: 3840 })
+check('1:1 的 360 识别为上下并排', ou360.profile.stereo === 'ou')
+
+const fisheye = detectVr360Profile({ path: '/media/vr/abc-fisheye-180.mp4', width: 1920, height: 1920 })
+check('鱼眼关键词优先于其它信号', fisheye.profile.projection === 'fisheye180')
+
+const vr180Sbs = detectVr360Profile({
+  path: '/media/云下载/sivr-270/sivr-270-1.mp4',
+  width: 3840,
+  height: 1920,
+})
+check('编号里的 vr 可识别为 VR180', vr180Sbs.confident && vr180Sbs.profile.projection === 'equirect180')
+check('VR180 的 2:1 画幅为左右并排', vr180Sbs.profile.stereo === 'sbs')
+
+const vr180Mono = detectVr360Profile({ path: '/media/vr/vr180-mono.mp4', width: 1920, height: 1920 })
+check('VR180 的 1:1 画幅为单眼', vr180Mono.profile.stereo === 'mono')
+
+const vr180Ou = detectVr360Profile({ path: '/media/vr/vr180-tb.mp4', width: 1920, height: 3840 })
+check('VR180 的 1:2 画幅为上下并排', vr180Ou.profile.stereo === 'ou')
+
+const topBottom = detectVr360Profile({ path: '/media/vr/vr360-top-bottom.mp4' })
+check('top-bottom 关键词为上下并排', topBottom.profile.stereo === 'ou')
+
+// ---------- 立体裁切与偏好归一化 ----------
+
+check('单眼不裁切', closeAll(vr360FrameUv('mono').scale, [1, 1]))
+check('左右并排取左半张', closeAll(vr360FrameUv('sbs').scale, [0.5, 1]))
+check('上下并排取上半张', closeAll(vr360FrameUv('ou').scale, [1, 0.5]))
+check('并排画面不做偏移', closeAll(vr360FrameUv('sbs').offset, [0, 0]))
+
+check('未知投影回退到 360 全景', normalizeVr360Profile({ projection: 'nope', stereo: 'nope' }).projection === 'equirect360')
+check('未知布局回退到单眼', normalizeVr360Profile({}).stereo === 'mono')
+check(
+  '相同配置判定相等',
+  sameVr360Profile({ projection: 'equirect180', stereo: 'sbs' }, { projection: 'equirect180', stereo: 'sbs' }),
+)
+check(
+  '不同配置判定不等',
+  !sameVr360Profile({ projection: 'equirect180', stereo: 'sbs' }, { projection: 'equirect180', stereo: 'ou' }),
+)
+
+// ---------- 相机姿态与设备陀螺仪 ----------
+
+const identityForward = cameraForward(new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1]))
+check('单位姿态朝向地面（设备平放）', closeAll([...identityForward], [0, 0, -1]))
+
+const level = cameraFromYawPitch(0, 0)
+check('默认视角水平看向正前方', closeAll([...cameraForward(level)], [0, 1, 0]))
+
+const east = cameraFromYawPitch(Math.PI / 2, 0)
+check('方位角 90° 转向正东', closeAll([...cameraForward(east)], [1, 0, 0], 1e-6))
+
+const up = cameraFromYawPitch(0, Math.PI / 2)
+check('俯仰角 90° 抬头看天', closeAll([...cameraForward(up)], [0, 0, 1], 1e-6))
+
+const northEast = cameraFromYawPitch(Math.PI / 4, 0)
+check('方位角 45° 落在东北方向', close(forwardYaw(cameraForward(northEast)), Math.PI / 4))
+
+const tilted = cameraFromYawPitch(0.3, -0.4)
+check('朝向角可反解出方位角', close(forwardYaw(cameraForward(tilted)), 0.3, 1e-6))
+check('朝向角可反解出俯仰角', close(forwardPitch(cameraForward(tilted)), -0.4, 1e-6))
+
+check(
+  '旋转矩阵转置等于反向旋转',
+  closeAll([...transpose3(rotationY(0.7))], [...rotationY(-0.7)], 1e-6),
+)
+check(
+  '正反旋转相乘为单位矩阵',
+  closeAll(
+    [...multiply3(rotationZ(1.1), rotationZ(-1.1))],
+    [1, 0, 0, 0, 1, 0, 0, 0, 1],
+    1e-6,
+  ),
+)
+
+// 视图矩阵 = 相机姿态的逆（纯旋转）
+const view = viewMatrixFromCamera(east)
+check('视图矩阵为相机矩阵的转置', closeAll([...view], [...transpose3(east)], 1e-6))
+
+// 设备姿态约定（与 W3C 规范一致）：相机看向设备背面，
+// 因此设备平放时（alpha 任意、beta = 0）视线朝下。
+const flat = cameraFromDeviceOrientation(Math.PI / 3, 0, 0, 0)
+check('设备平放时看向地面', closeAll([...cameraForward(flat)], [0, 0, -1], 1e-6))
+
+// 竖持手机（beta = 90°）时视线水平
+const portrait = cameraFromDeviceOrientation(0, Math.PI / 2, 0, 0)
+check('竖持手机时视线水平', close(cameraForward(portrait)[2], 0, 1e-6))
+check('竖持手机时视线朝北', close(forwardYaw(cameraForward(portrait)), 0, 1e-6))
+
+// 横屏（屏幕旋转 90°）时相机「上方向」跟随屏幕
+const landscape = cameraFromDeviceOrientation(0, Math.PI / 2, 0, Math.PI / 2)
+check('横屏时画面随屏幕转向', closeAll([...applyDirection(landscape, 0, 1, 0)], [1, 0, 0], 1e-6))
+
+// 陀螺仪开启瞬间的视角对齐：叠加偏移后朝向应等于对齐前记录的拖拽视角
+const aligned = applyViewOffset(cameraFromDeviceOrientation(0, Math.PI / 2, 0, 0), 0.5, 0.25)
+check('叠加偏移后方位角对齐', close(forwardYaw(cameraForward(aligned)), 0.5, 1e-6))
+check('叠加偏移后俯仰角对齐', close(forwardPitch(cameraForward(aligned)), 0.25, 1e-6))
+
+// ---------- 透视投影 ----------
+
+const projection = perspectiveMatrix(Math.PI / 2, 2, 0.1, 10)
+check('透视矩阵缩放项随视场角变化', close(projection[0], 0.5))
+check('透视矩阵写入 w = -1（右手系）', projection[11] === -1)
+
+console.log('vr360.test.ts: ok')

web/src/utils/vr360.ts

@@ -0,0 +1,229 @@
+// VR360（全景）播放的配置模型、命名启发式识别与本地偏好。
+//
+// 网页端只能从文件名/路径和画幅比例推断「这段视频是不是全景/VR」，任何信号
+// 都不绝对可靠，所以这里只负责给出「大概率正确」的初始配置：识别结果不写入
+// 数据库，用户随时可以在播放器菜单里改投影方式与立体布局，改动只影响本机。
+
+export type Vr360Projection = 'equirect360' | 'equirect180' | 'fisheye180'
+export type Vr360Stereo = 'mono' | 'sbs' | 'ou'
+
+export type Vr360Profile = {
+  /** 画面投影方式：360 等距柱状、180 等距柱状、180 鱼眼。 */
+  projection: Vr360Projection
+  /** 立体布局：单眼、左右并排、上下并排。 */
+  stereo: Vr360Stereo
+}
+
+export const DEFAULT_VR360_PROFILE: Vr360Profile = {
+  projection: 'equirect360',
+  stereo: 'mono',
+}
+
+/** 视场角可调范围（度）：数值越小画面越「拉近」。 */
+export const VR360_MIN_FOV = 35
+export const VR360_MAX_FOV = 110
+export const VR360_DEFAULT_FOV = 75
+
+export const VR360_PROJECTION_OPTIONS: Array<[Vr360Projection, string]> = [
+  ['equirect360', '360° 全景'],
+  ['equirect180', '180° 半景'],
+  ['fisheye180', '180° 鱼眼'],
+]
+
+export const VR360_STEREO_OPTIONS: Array<[Vr360Stereo, string]> = [
+  ['mono', '单眼'],
+  ['sbs', '左右并排'],
+  ['ou', '上下并排'],
+]
+
+export function vr360ProjectionLabel(projection: Vr360Projection): string {
+  return VR360_PROJECTION_OPTIONS.find(([value]) => value === projection)?.[1] ?? '360° 全景'
+}
+
+export function vr360StereoLabel(stereo: Vr360Stereo): string {
+  return VR360_STEREO_OPTIONS.find(([value]) => value === stereo)?.[1] ?? '单眼'
+}
+
+export function normalizeVr360Projection(value: unknown): Vr360Projection {
+  return value === 'equirect180' || value === 'fisheye180' ? value : 'equirect360'
+}
+
+export function normalizeVr360Stereo(value: unknown): Vr360Stereo {
+  return value === 'sbs' || value === 'ou' ? value : 'mono'
+}
+
+export function normalizeVr360Profile(value: unknown): Vr360Profile {
+  const profile = (value ?? {}) as Partial<Vr360Profile>
+  return {
+    projection: normalizeVr360Projection(profile.projection),
+    stereo: normalizeVr360Stereo(profile.stereo),
+  }
+}
+
+export function sameVr360Profile(a: Vr360Profile, b: Vr360Profile): boolean {
+  return a.projection === b.projection && a.stereo === b.stereo
+}
+
+// 立体素材（左右/上下并排）在普通屏幕上只取左眼画面：真正的双眼渲染需要
+// WebXR 头显，网页里把两半都画出来只会得到重复画面。
+export function vr360FrameUv(stereo: Vr360Stereo): {
+  scale: [number, number]
+  offset: [number, number]
+} {
+  if (stereo === 'sbs') return { scale: [0.5, 1], offset: [0, 0] }
+  if (stereo === 'ou') return { scale: [1, 0.5], offset: [0, 0] }
+  return { scale: [1, 1], offset: [0, 0] }
+}
+
+export type Vr360DetectInput = {
+  title?: string
+  originalName?: string
+  path?: string
+  relativePath?: string
+  /** 视频画面宽度（媒体元数据或 ffprobe 结果）。 */
+  width?: number
+  /** 视频画面高度。 */
+  height?: number
+}
+
+export type Vr360Detection = {
+  profile: Vr360Profile
+  /** 文件名/路径里出现了明确的 VR 或全景关键词，可以放心自动进入 VR 模式。 */
+  confident: boolean
+}
+
+// 关键词分两类：明确的关键词按子串匹配（"vr360" 里也含 "360"），
+// 容易误伤的两字母缩写按独立词元匹配（避免 "1ou" / "sivr" 之类误判）。
+const PANORAMA_SUBSTRINGS = ['360', 'equirect', 'insta360', 'pano', 'vuze', 'theta', '全景']
+const FISHEYE_SUBSTRINGS = ['fisheye', '鱼眼']
+const VR180_SUBSTRINGS = ['vr180', '180vr', '180°', '180度', '半景']
+const SBS_SUBSTRINGS = ['side-by-side', 'sidebyside', 'side_by_side', '左右']
+const OU_SUBSTRINGS = ['over-under', 'top-bottom', 'topbottom', '上下']
+const VR_TOKENS = ['vr']
+const SBS_TOKENS = ['sbs', 'hsbs', 'lr']
+const OU_TOKENS = ['ou', 'tb', 'vou', 'tou']
+
+function detectText(input: Vr360DetectInput): string {
+  return [input.path, input.relativePath, input.originalName, input.title]
+    .filter((value): value is string => Boolean(value))
+    .join(' ')
+    .toLowerCase()
+}
+
+// 文件名比标题可靠：标题里可能出现「VR」之类的普通单词，文件名里的 "vr" 通常
+// 是作品编号的一部分（如 sivr-270、ipvr00192）。
+function detectNameText(input: Vr360DetectInput): string {
+  return [input.path, input.relativePath, input.originalName]
+    .filter((value): value is string => Boolean(value))
+    .join(' ')
+    .toLowerCase()
+}
+
+function detectTokens(text: string): Set<string> {
+  return new Set(text.split(/[^a-z0-9]+/).filter(Boolean))
+}
+
+function hasSubstring(text: string, needles: string[]): boolean {
+  return needles.some((needle) => text.includes(needle))
+}
+
+function hasToken(tokens: Set<string>, needles: string[]): boolean {
+  return needles.some((needle) => tokens.has(needle))
+}
+
+function aspectRatio(input: Vr360DetectInput): number | null {
+  const width = input.width ?? 0
+  const height = input.height ?? 0
+  if (width <= 0 || height <= 0) return null
+  const ratio = width / height
+  return Number.isFinite(ratio) && ratio > 0 ? ratio : null
+}
+
+/**
+ * 依据文件名/路径关键词与画幅比例推断 VR 配置。
+ *
+ * 关键词比画幅可靠：2:1 既可能是 360 单眼，也可能是 180 左右并排，所以比例只
+ * 在没有明确关键词时补默认值（4:1 ⇒ 左右并排；约 1:1 的 360 ⇒ 上下并排）。
+ */
+export function detectVr360Profile(input: Vr360DetectInput): Vr360Detection {
+  const text = detectText(input)
+  const nameText = detectNameText(input)
+  const tokens = detectTokens(text)
+
+  const fisheye = hasSubstring(text, FISHEYE_SUBSTRINGS)
+  const vr180 = hasSubstring(text, VR180_SUBSTRINGS)
+  const panorama = hasSubstring(text, PANORAMA_SUBSTRINGS)
+  const vrToken = hasToken(tokens, VR_TOKENS) || nameText.includes('vr')
+  const confident = fisheye || vr180 || panorama || vrToken
+
+  let projection: Vr360Projection = DEFAULT_VR360_PROFILE.projection
+  if (fisheye) projection = 'fisheye180'
+  else if (vr180) projection = 'equirect180'
+  // 只有 "VR" 一个信号、没有 360/全景关键词时，按更常见的 VR180 处理。
+  else if (vrToken && !panorama) projection = 'equirect180'
+
+  const sbs = hasSubstring(text, SBS_SUBSTRINGS) || hasToken(tokens, SBS_TOKENS)
+  const ou = hasSubstring(text, OU_SUBSTRINGS) || hasToken(tokens, OU_TOKENS)
+
+  let stereo: Vr360Stereo = 'mono'
+  if (sbs !== ou) stereo = sbs ? 'sbs' : 'ou'
+
+  const ratio = aspectRatio(input)
+  if (ratio !== null && stereo === 'mono') {
+    if (projection === 'equirect360') {
+      // 4:1 基本只可能是 360 左右并排（如 7680x1920）；
+      // 约 1:1 的 360 素材多为上下并排（如 3840x3840）。
+      if (ratio >= 3.4) stereo = 'sbs'
+      else if (ratio <= 1.05) stereo = 'ou'
+    } else {
+      // VR180 单眼是 1:1，左右并排是 2:1，上下并排是 1:2。
+      if (ratio >= 1.8 && ratio <= 2.2) stereo = 'sbs'
+      else if (ratio <= 0.6) stereo = 'ou'
+    }
+  }
+
+  return { profile: { projection, stereo }, confident }
+}
+
+const VR360_PREF_KEY = 'mebox.player.vr360'
+
+export type Vr360Preference = {
+  /** 是否按文件名/画幅自动进入 VR 模式；用户可以关掉，避免误判干扰正常播放。 */
+  autoDetect: boolean
+  /** 用户上次选定的投影与布局，作为下次手动进入 VR 模式时的默认值。 */
+  profile: Vr360Profile
+}
+
+export const DEFAULT_VR360_PREFERENCE: Vr360Preference = {
+  autoDetect: true,
+  profile: DEFAULT_VR360_PROFILE,
+}
+
+export function loadVr360Preference(): Vr360Preference {
+  if (typeof window === 'undefined') return DEFAULT_VR360_PREFERENCE
+  try {
+    const raw = window.localStorage.getItem(VR360_PREF_KEY)
+    if (!raw) return DEFAULT_VR360_PREFERENCE
+    const parsed = JSON.parse(raw) as Partial<Vr360Preference>
+    return {
+      autoDetect: parsed.autoDetect !== false,
+      profile: normalizeVr360Profile(parsed.profile),
+    }
+  } catch {
+    return DEFAULT_VR360_PREFERENCE
+  }
+}
+
+export function saveVr360Preference(preference: Vr360Preference): void {
+  try {
+    window.localStorage.setItem(
+      VR360_PREF_KEY,
+      JSON.stringify({
+        autoDetect: preference.autoDetect !== false,
+        profile: normalizeVr360Profile(preference.profile),
+      }),
+    )
+  } catch {
+    // 隐私模式下 localStorage 不可用；播放器仍可正常使用 VR 模式。
+  }
+}

web/src/utils/vr360Math.ts

@@ -0,0 +1,154 @@
+// VR360 播放用到的纯数学：3x3 旋转矩阵、设备姿态到相机姿态、透视投影。
+//
+// 坐标约定（与 W3C DeviceOrientation 规范一致，右手系）：
+//   x = 东（设备右侧），y = 北（设备顶部），z = 天空（设备屏幕朝外）
+//   相机看向相机局部坐标的 -z，设备平放时 -z 指向地面，因此设备平放时视角朝下，
+//   竖持手机（beta=90°）时视角水平向前 —— 与手机陀螺仪的实际手感一致。
+//
+// 所有 3x3 矩阵都是 WebGL 默认的列主序（column-major）Float32Array(9)，
+// 可以直接交给 gl.uniformMatrix3fv，不需要转置。
+
+export type Mat3 = Float32Array
+
+export function degToRad(degrees: number): number {
+  return (degrees * Math.PI) / 180
+}
+
+export function clampNumber(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min
+  return Math.min(max, Math.max(min, value))
+}
+
+export function createMat3(
+  m00: number, m10: number, m20: number,
+  m01: number, m11: number, m21: number,
+  m02: number, m12: number, m22: number,
+): Mat3 {
+  // WebGL 列主序内存布局：[col0, col1, col2]
+  return new Float32Array([m00, m10, m20, m01, m11, m21, m02, m12, m22])
+}
+
+export function identity3(): Mat3 {
+  return createMat3(1, 0, 0, 0, 1, 0, 0, 0, 1)
+}
+
+export function rotationX(radians: number): Mat3 {
+  const c = Math.cos(radians)
+  const s = Math.sin(radians)
+  return createMat3(1, 0, 0, 0, c, s, 0, -s, c)
+}
+
+export function rotationY(radians: number): Mat3 {
+  const c = Math.cos(radians)
+  const s = Math.sin(radians)
+  return createMat3(c, 0, -s, 0, 1, 0, s, 0, c)
+}
+
+export function rotationZ(radians: number): Mat3 {
+  const c = Math.cos(radians)
+  const s = Math.sin(radians)
+  return createMat3(c, s, 0, -s, c, 0, 0, 0, 1)
+}
+
+/** 先施加 b，再施加 a（即矩阵乘积 a·b）。 */
+export function multiply3(a: Mat3, b: Mat3): Mat3 {
+  const out = new Float32Array(9)
+  for (let col = 0; col < 3; col++) {
+    for (let row = 0; row < 3; row++) {
+      let sum = 0
+      for (let k = 0; k < 3; k++) {
+        sum += a[k * 3 + row] * b[col * 3 + k]
+      }
+      out[col * 3 + row] = sum
+    }
+  }
+  return out
+}
+
+/** 旋转矩阵的逆等于转置。 */
+export function transpose3(m: Mat3): Mat3 {
+  const out = new Float32Array(9)
+  for (let col = 0; col < 3; col++) {
+    for (let row = 0; row < 3; row++) {
+      out[col * 3 + row] = m[row * 3 + col]
+    }
+  }
+  return out
+}
+
+export function applyDirection(m: Mat3, x: number, y: number, z: number): [number, number, number] {
+  return [
+    m[0] * x + m[3] * y + m[6] * z,
+    m[1] * x + m[4] * y + m[7] * z,
+    m[2] * x + m[5] * y + m[8] * z,
+  ]
+}
+
+/** 相机在世界坐标中的朝向（相机局部 -z）。 */
+export function cameraForward(camera: Mat3): [number, number, number] {
+  const forward = applyDirection(camera, 0, 0, -1)
+  const length = Math.hypot(forward[0], forward[1], forward[2]) || 1
+  return [forward[0] / length, forward[1] / length, forward[2] / length]
+}
+
+/** 相机朝向的水平方位角（0 = +y 即正北，顺时针转向 +x 即正东）。 */
+export function forwardYaw(forward: [number, number, number]): number {
+  return Math.atan2(forward[0], forward[1])
+}
+
+/** 相机朝向的俯仰角（+ 抬头，- 低头）。 */
+export function forwardPitch(forward: [number, number, number]): number {
+  return Math.asin(clampNumber(forward[2], -1, 1))
+}
+
+/**
+ * 由「用户拖拽/默认视角」的方位角与俯仰角构造相机姿态。
+ * 默认（yaw = 0, pitch = 0）时相机水平看向 +y，画面中的地平线保持水平。
+ */
+export function cameraFromYawPitch(yaw: number, pitch: number): Mat3 {
+  return multiply3(rotationZ(-yaw), rotationX(Math.PI / 2 + pitch))
+}
+
+/**
+ * 由设备姿态构造相机姿态（W3C 规范：R = Rz(α)·Rx(β)·Ry(γ)），
+ * 再按屏幕旋转角做一次横滚校正，使画面正向与屏幕正向一致。
+ */
+export function cameraFromDeviceOrientation(
+  alpha: number,
+  beta: number,
+  gamma: number,
+  screenAngle: number,
+): Mat3 {
+  const device = multiply3(multiply3(rotationZ(alpha), rotationX(beta)), rotationY(gamma))
+  return multiply3(device, rotationZ(-screenAngle))
+}
+
+/**
+ * 在设备姿态之上叠加用户拖拽产生的视角偏移：水平方向围绕世界 z 轴旋转，
+ * 垂直方向围绕相机自身的右轴倾斜（小角度下等效于抬头/低头）。
+ */
+export function applyViewOffset(camera: Mat3, yawOffset: number, pitchOffset: number): Mat3 {
+  return multiply3(rotationZ(-yawOffset), multiply3(camera, rotationX(pitchOffset)))
+}
+
+/** 世界坐标 → 相机坐标的视图矩阵（纯旋转，所以就是转置）。 */
+export function viewMatrixFromCamera(camera: Mat3): Mat3 {
+  return transpose3(camera)
+}
+
+/** 标准透视投影矩阵（列主序 4x4）。 */
+export function perspectiveMatrix(
+  fovY: number,
+  aspect: number,
+  near: number,
+  far: number,
+): Float32Array {
+  const f = 1 / Math.tan(fovY / 2)
+  const rangeInv = 1 / (near - far)
+  return new Float32Array([
+    f / aspect, 0, 0, 0,
+    0, f, 0, 0,
+    0, 0, (far + near) * rangeInv, -1,
+    0, 0, 2 * far * near * rangeInv, 0,
+  ])
+}

web/src/utils/vr360Renderer.ts

@@ -0,0 +1,365 @@
+// 用一段 WebGL 把 <video> 贴到球面/半球面上，实现 360°/180° 全景播放。
+//
+// 不引入 three.js：整个渲染器只是一段着色器 + 一个网格 + 一张视频纹理，依赖
+// 极小，同时也不会把播放页首屏体积撑大（该模块由播放器按需懒加载）。
+//
+// 视频元素始终是同一个正在播放的 <video>，这里只把它当前的帧采样到球面上，
+// 因此 HLS、直连、115 云转码等所有播放方式都能直接复用。
+
+import type { Mat3 } from './vr360Math'
+import { perspectiveMatrix } from './vr360Math'
+import {
+  VR360_DEFAULT_FOV,
+  VR360_MAX_FOV,
+  VR360_MIN_FOV,
+  type Vr360Projection,
+} from './vr360'
+
+export type Vr360Renderer = {
+  setProjection(projection: Vr360Projection): void
+  /** 立体素材裁切：只取左眼所在的半张画面。 */
+  setFrameUv(scale: [number, number], offset: [number, number]): void
+  setView(view: Mat3): void
+  setFov(fovDeg: number): void
+  resize(width: number, height: number): void
+  draw(): void
+  dispose(): void
+}
+
+export type Vr360RendererOptions = {
+  /** WebGL 上下文丢失（移动端切后台、系统回收 GPU 资源）时回调，由调用方退出 VR 模式。 */
+  onContextLost?: () => void
+  /** 视频帧无法写入纹理（跨域污染等）时回调。 */
+  onTextureError?: (error: unknown) => void
+}
+
+const VERTEX_SHADER = `
+attribute vec3 aPosition;
+attribute vec2 aUv;
+uniform mat3 uView;
+uniform mat4 uProjection;
+uniform vec2 uUvScale;
+uniform vec2 uUvOffset;
+varying vec2 vUv;
+void main() {
+  vUv = aUv * uUvScale + uUvOffset;
+  gl_Position = uProjection * vec4(uView * aPosition, 1.0);
+}
+`
+
+const FRAGMENT_SHADER = `
+precision mediump float;
+uniform sampler2D uTexture;
+varying vec2 vUv;
+void main() {
+  gl_FragColor = texture2D(uTexture, vUv);
+}
+`
+
+// 球面半径为 1 个单位，相机固定在球心，远近裁剪面据此选取。
+const NEAR_PLANE = 0.1
+const FAR_PLANE = 10
+
+type Mesh = {
+  positions: Float32Array
+  uvs: Float32Array
+  indices: Uint16Array
+  indexCount: number
+}
+
+type GridPoint = {
+  position: [number, number, number]
+  uv: [number, number]
+}
+
+function buildGrid(
+  columns: number,
+  rows: number,
+  point: (col: number, row: number) => GridPoint,
+): Mesh {
+  const positions = new Float32Array((columns + 1) * (rows + 1) * 3)
+  const uvs = new Float32Array((columns + 1) * (rows + 1) * 2)
+  for (let row = 0; row <= rows; row++) {
+    for (let col = 0; col <= columns; col++) {
+      const index = row * (columns + 1) + col
+      const { position, uv } = point(col, row)
+      positions[index * 3] = position[0]
+      positions[index * 3 + 1] = position[1]
+      positions[index * 3 + 2] = position[2]
+      uvs[index * 2] = uv[0]
+      uvs[index * 2 + 1] = uv[1]
+    }
+  }
+
+  const indices = new Uint16Array(columns * rows * 6)
+  let cursor = 0
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < columns; col++) {
+      const topLeft = row * (columns + 1) + col
+      const topRight = topLeft + 1
+      const bottomLeft = topLeft + columns + 1
+      const bottomRight = bottomLeft + 1
+      indices[cursor++] = topLeft
+      indices[cursor++] = bottomLeft
+      indices[cursor++] = topRight
+      indices[cursor++] = topRight
+      indices[cursor++] = bottomLeft
+      indices[cursor++] = bottomRight
+    }
+  }
+
+  return { positions, uvs, indices, indexCount: indices.length }
+}
+
+/**
+ * 等距柱状投影：水平覆盖 ±span，垂直覆盖 -90°~+90°。
+ * u 从 0（左端）到 1（右端），v 从 0（画面顶部）到 1（画面底部）。
+ */
+function buildEquirectMesh(span: number): Mesh {
+  const columns = 96
+  const rows = 48
+  return buildGrid(columns, rows, (col, row) => {
+    const lambda = -span + (2 * span * col) / columns
+    const phi = -Math.PI / 2 + (Math.PI * row) / rows
+    const cosPhi = Math.cos(phi)
+    return {
+      position: [Math.sin(lambda) * cosPhi, Math.cos(lambda) * cosPhi, Math.sin(phi)],
+      uv: [(lambda + span) / (2 * span), 0.5 - phi / Math.PI],
+    }
+  })
+}
+
+/**
+ * 180° 鱼眼（等距投影）：画面中心是正前方，纹理半径 r 与偏角 θ 成正比。
+ * 方画幅内切圆之外的区域不参与采样，标准 VR180 鱼眼素材即如此。
+ */
+function buildFisheyeMesh(): Mesh {
+  const radial = 64
+  const azimuth = 96
+  const thetaMax = Math.PI / 2
+  return buildGrid(azimuth, radial, (col, row) => {
+    const psi = (2 * Math.PI * col) / azimuth
+    const theta = (thetaMax * row) / radial
+    const sinTheta = Math.sin(theta)
+    const radius = theta / thetaMax
+    return {
+      position: [sinTheta * Math.cos(psi), Math.cos(theta), sinTheta * Math.sin(psi)],
+      uv: [0.5 + 0.5 * radius * Math.cos(psi), 0.5 - 0.5 * radius * Math.sin(psi)],
+    }
+  })
+}
+
+function buildMesh(projection: Vr360Projection): Mesh {
+  if (projection === 'fisheye180') return buildFisheyeMesh()
+  if (projection === 'equirect180') return buildEquirectMesh(Math.PI / 2)
+  return buildEquirectMesh(Math.PI)
+}
+
+function compileShader(gl: WebGLRenderingContext, type: number, source: string): WebGLShader | null {
+  const shader = gl.createShader(type)
+  if (!shader) return null
+  gl.shaderSource(shader, source)
+  gl.compileShader(shader)
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    gl.deleteShader(shader)
+    return null
+  }
+  return shader
+}
+
+/**
+ * 在给定画布上创建全景渲染器；浏览器不支持 WebGL 时返回 null，调用方据此
+ * 退回普通播放，而不是给用户一个黑屏。
+ */
+export function createVr360Renderer(
+  canvas: HTMLCanvasElement,
+  video: HTMLVideoElement,
+  options: Vr360RendererOptions = {},
+): Vr360Renderer | null {
+  const attributes: WebGLContextAttributes = {
+    alpha: false,
+    antialias: false,
+    depth: false,
+    stencil: false,
+    premultipliedAlpha: false,
+    preserveDrawingBuffer: false,
+    powerPreference: 'high-performance',
+  }
+  const gl = (canvas.getContext('webgl2', attributes) ??
+    canvas.getContext('webgl', attributes)) as WebGLRenderingContext | null
+  if (!gl) return null
+
+  const vertexShader = compileShader(gl, gl.VERTEX_SHADER, VERTEX_SHADER)
+  const fragmentShader = compileShader(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER)
+  if (!vertexShader || !fragmentShader) return null
+  const program = gl.createProgram()
+  if (!program) return null
+  gl.attachShader(program, vertexShader)
+  gl.attachShader(program, fragmentShader)
+  gl.linkProgram(program)
+  gl.deleteShader(vertexShader)
+  gl.deleteShader(fragmentShader)
+  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    gl.deleteProgram(program)
+    return null
+  }
+
+  const positionLocation = gl.getAttribLocation(program, 'aPosition')
+  const uvLocation = gl.getAttribLocation(program, 'aUv')
+  const viewLocation = gl.getUniformLocation(program, 'uView')
+  const projectionLocation = gl.getUniformLocation(program, 'uProjection')
+  const uvScaleLocation = gl.getUniformLocation(program, 'uUvScale')
+  const uvOffsetLocation = gl.getUniformLocation(program, 'uUvOffset')
+  const textureLocation = gl.getUniformLocation(program, 'uTexture')
+
+  const positionBuffer = gl.createBuffer()
+  const uvBuffer = gl.createBuffer()
+  const indexBuffer = gl.createBuffer()
+  const texture = gl.createTexture()
+  if (!positionBuffer || !uvBuffer || !indexBuffer || !texture) return null
+
+  gl.bindTexture(gl.TEXTURE_2D, texture)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR)
+  // 先放一张 1x1 黑色占位图，视频帧尚未就绪时也不会出现未定义内容。
+  gl.texImage2D(
+    gl.TEXTURE_2D,
+    0,
+    gl.RGBA,
+    1,
+    1,
+    0,
+    gl.RGBA,
+    gl.UNSIGNED_BYTE,
+    new Uint8Array([0, 0, 0, 255]),
+  )
+
+  gl.disable(gl.CULL_FACE)
+  gl.disable(gl.DEPTH_TEST)
+  gl.disable(gl.BLEND)
+  gl.clearColor(0, 0, 0, 1)
+
+  let indexCount = 0
+  let uvScale: [number, number] = [1, 1]
+  let uvOffset: [number, number] = [0, 0]
+  let view: Mat3 = new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1])
+  let fov = VR360_DEFAULT_FOV
+  let displayWidth = 1
+  let displayHeight = 1
+  let disposed = false
+  let contextLost = false
+
+  const uploadMesh = (mesh: Mesh) => {
+    indexCount = mesh.indexCount
+    gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer)
+    gl.bufferData(gl.ARRAY_BUFFER, mesh.positions, gl.STATIC_DRAW)
+    gl.bindBuffer(gl.ARRAY_BUFFER, uvBuffer)
+    gl.bufferData(gl.ARRAY_BUFFER, mesh.uvs, gl.STATIC_DRAW)
+    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer)
+    gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, mesh.indices, gl.STATIC_DRAW)
+  }
+  uploadMesh(buildMesh('equirect360'))
+
+  const handleContextLost = (event: Event) => {
+    // 必须 preventDefault，否则上下文不会被标记为可恢复；这里直接让上层退出 VR。
+    event.preventDefault()
+    contextLost = true
+    options.onContextLost?.()
+  }
+  canvas.addEventListener('webglcontextlost', handleContextLost)
+
+  return {
+    setProjection(projection: Vr360Projection) {
+      if (disposed) return
+      uploadMesh(buildMesh(projection))
+    },
+    setFrameUv(scale: [number, number], offset: [number, number]) {
+      uvScale = scale
+      uvOffset = offset
+    },
+    setView(next: Mat3) {
+      view = next
+    },
+    setFov(next: number) {
+      fov = Math.min(VR360_MAX_FOV, Math.max(VR360_MIN_FOV, next))
+    },
+    resize(nextWidth: number, nextHeight: number) {
+      if (disposed) return
+      // 画布位置与尺寸完全交给 CSS（inset-0 + 100%），绘制缓冲区只跟随它。
+      // 否则「观测到画布变大 → 设置更大的缓冲区 → 布局再次变大」会指数放大。
+      canvas.style.width = '100%'
+      canvas.style.height = '100%'
+      // 移动端按 DPR 渲染 4K 视频纹理代价很高，上限锁 2 倍。
+      const dpr = Math.min(2, Math.max(1, window.devicePixelRatio || 1))
+      displayWidth = Math.max(1, nextWidth)
+      displayHeight = Math.max(1, nextHeight)
+      const pixelWidth = Math.max(1, Math.round(displayWidth * dpr))
+      const pixelHeight = Math.max(1, Math.round(displayHeight * dpr))
+      if (canvas.width !== pixelWidth) canvas.width = pixelWidth
+      if (canvas.height !== pixelHeight) canvas.height = pixelHeight
+    },
+    draw() {
+      if (disposed || contextLost) return
+      if (canvas.width < 1 || canvas.height < 1) return
+
+      gl.viewport(0, 0, canvas.width, canvas.height)
+      gl.clear(gl.COLOR_BUFFER_BIT)
+
+      if (video.readyState >= 2 && video.videoWidth > 0) {
+        try {
+          gl.bindTexture(gl.TEXTURE_2D, texture)
+          gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 0)
+          gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, video)
+        } catch (error) {
+          options.onTextureError?.(error)
+        }
+      }
+
+      gl.useProgram(program)
+      gl.uniformMatrix3fv(viewLocation, false, view)
+      gl.uniformMatrix4fv(
+        projectionLocation,
+        false,
+        perspectiveMatrix(
+          (fov * Math.PI) / 180,
+          displayWidth / displayHeight,
+          NEAR_PLANE,
+          FAR_PLANE,
+        ),
+      )
+      gl.uniform2f(uvScaleLocation, uvScale[0], uvScale[1])
+      gl.uniform2f(uvOffsetLocation, uvOffset[0], uvOffset[1])
+      gl.uniform1i(textureLocation, 0)
+
+      gl.activeTexture(gl.TEXTURE0)
+      gl.bindTexture(gl.TEXTURE_2D, texture)
+
+      gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer)
+      gl.enableVertexAttribArray(positionLocation)
+      gl.vertexAttribPointer(positionLocation, 3, gl.FLOAT, false, 0, 0)
+
+      gl.bindBuffer(gl.ARRAY_BUFFER, uvBuffer)
+      gl.enableVertexAttribArray(uvLocation)
+      gl.vertexAttribPointer(uvLocation, 2, gl.FLOAT, false, 0, 0)
+
+      gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer)
+      gl.drawElements(gl.TRIANGLES, indexCount, gl.UNSIGNED_SHORT, 0)
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      canvas.removeEventListener('webglcontextlost', handleContextLost)
+      gl.bindBuffer(gl.ARRAY_BUFFER, null)
+      gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, null)
+      gl.deleteBuffer(positionBuffer)
+      gl.deleteBuffer(uvBuffer)
+      gl.deleteBuffer(indexBuffer)
+      gl.deleteTexture(texture)
+      gl.deleteProgram(program)
+      // 主动释放上下文：移动端同时存活多个 WebGL 上下文会被浏览器强制回收。
+      gl.getExtension('WEBGL_lose_context')?.loseContext()
+    },
+  }
+}