用途：为 Three.js 应用添加 WebXR（VR/AR）支持，或在 Meta Quest 上调试 WebXR 渲染与交互问题。可用 /webxr-dev 调用。
主要能力：区分 immersive-vr 与 immersive-ar 两种会话模式；提供会话初始化与特性列表（如 local-floor、bounded-floor、hand-tracking、layers、hit-test 等）；用 XRWebGLLayer 的 getNativeFramebufferScaleFactor 提升帧缓冲分辨率；相机装置（cameraRig）架构与控制器摇杆映射；地面/飞行移动、传送、VR 面板 UI；后处理替代方案；远程调试与常见陷阱。
关键规则：默认使用 immersive-vr；仅在明确需要透视、能真机测试且已处理所有材质与着色器 alpha 时才用 immersive-ar。会话模式在请求时固定，中途不可切换。AR 中 framebuffer alpha 控制相机混合，Three.js 会跳过背景渲染，每个像素需显式输出 alpha=1.0 才能遮挡摄像头画面。
使用方式：调用 navigator.xr.requestSession 并设置 renderer.xr.setReferenceSpaceType("local-floor") 与 setSession；在会话启动时用 XRWebGLLayer 设置原生缩放因子，否则画面模糊。相机与控制器应置于 cameraRig 组下；射线命中世界坐标后赋给 rig 子对象前须 cameraRig.worldToLocal()。右摇杆做水平转向与垂直飞行，不要对 rig 做 rotateX。传送时相机高度归零。
限制：postprocessing 库不支持 WebXR，VR 下必须绕过 composer 直接渲染，屏幕空间泛光、扭曲、色调映射在 VR 中不可见，需用 3D 场景对象替代。VR 无法脱离头显测试；PWA 缓存会干扰调试，应优先在 Quest 浏览器硬刷新测试。透明材质、几何反转加 BackSide、忘记 frustumCulled=false、未释放几何/材质等均为常见坑。