@realsee/five-webgpu 1.0.0-alpha.6 → 1.0.0-alpha.7

package/five/model/index.d.ts

@@ -4,8 +4,9 @@ export { PBMGaussianSplattingObject, type SplatData, } from "./objects/pbmGaussi
 export { PBMGaussianSplattingObject as PBMGSObject, } from "./objects/pbmGaussianSplattingObject";
 export { PBMPointCloud, type PointCloudData, } from "./objects/pbmPointCloud";
 export { PBMGaussianSplattingRenderMesh, } from "./objects/pbmGaussianSplattingRenderMesh";
-export { PBMGaussianSplattingNodeMaterial, } from "./materials/pbmGaussianSplattingNodeMaterial";
-export { PBMUpdateable, PBMPanoFilter, PBMCustomNode, customNodesCacheKey, type IPBMMaterial, type PBMPanoFilterValue, type PBMAlphaMode, type PBMClipperParameter, type PBMColorStyle, type PBMFloorStyle, type PBMRoofStyle, type PBMPanoPicture, type PBMPanoGainmap, type PBMPanoDepth, type PBMPointBack, type PBMPointCloudShaderType, type PBMPointShape, type PBMPointSize, type PBMRefinedScreen, type PBMTransition, type PBMCustomNodeSlots, type PBMCustomNodeTargetType, type PBMCustomNodeOptions, type PBMCustomNodeContext, type PBMCustomNodePanoContext, } from "./materials/pbmMaterial";
+export { PBMGaussianSplattingNodeMaterial, type PBMGaussianSplattingNodeMaterialOptions, } from "./materials/pbmGaussianSplattingNodeMaterial";
+export { PBMPointCloudMaterial, } from "./materials/pbmPointCloudMaterial";
+export { PBMUpdateable, PBMPanoFilter, PBMCustomNode, PBMVertexMarkFlag, customNodesCacheKey, type IPBMMaterial, type PBMPanoFilterValue, type PBMAlphaMode, type PBMClipperParameter, type PBMColorStyle, type PBMFloorStyle, type PBMRoofStyle, type PBMPanoPicture, type PBMPanoGainmap, type PBMPanoDepth, type PBMPointBack, type PBMPointCloudShaderType, type PBMPointShape, type PBMPointSize, type PBMRefinedScreen, type PBMTransition, type PBMCustomNodeSlots, type PBMCustomNodeTargetType, type PBMCustomNodeOptions, type PBMCustomNodeContext, type PBMCustomNodePanoContext, } from "./materials/pbmMaterial";
 export { type PBMMeshMaterial, PBMMeshBasicMaterial, PBMMeshPhongMaterial, PBMMeshPhysicalMaterial, PBMMeshPanoOnlyMaterial } from './materials/pbmMeshMaterial';
 export { registerPBMMaterials, } from './materials/pbmMaterialRegister';
 export { PBMMeshBasicNodeMaterial, } from './materials/nodes/pbmMeshBasicNodeMaterial';

package/five/model/materials/pbmMaterial.d.ts

@@ -17,6 +17,17 @@ export type PBMColorStyle = 'RGB' | 'ALTITUDE' | 'CONSTANT';
 export type PBMPointShape = 'SQUARE' | 'CIRCLE';
 export type PBMPointSize = 'FIXED' | 'ATTENUATION';
 export type PBMPointBack = 'VISIBLE' | 'HIDDEN' | 'DARK';
+/**
+ * 顶点标注档位（按位掩码）。
+ * 每一类标注对应一位，可按位独立启用；新增档位时在此追加一位即可。
+ */
+export declare const PBMVertexMarkFlag: {
+    readonly none: 0;
+    readonly roof: 2;
+    readonly hidden: 4;
+    /** 全开，默认包含未来新增的所有标注档位 */
+    readonly all: 255;
+};
 export declare class PBMUpdateable extends Subscribe<{
     "update": () => void;
 }> {
@@ -401,7 +412,8 @@ export interface IPBMMaterial {
     pointScale: number;
     pointMinPixel: number;
     pointMaxPixel: number;
-    vertexMarks: boolean;
+    useVertexMarkRoof: boolean;
+    useVertexMarkHidden: boolean;
     colorAlpha: number;
     alphaMode: string;
     modelAlpha: number;

package/five/model/materials/pbmMeshMaterial.d.ts

@@ -46,12 +46,3 @@ export type PBMMeshMaterial = PBMMeshBasicMaterial | PBMMeshPhongMaterial | PBMM
 export declare function createPBMMeshMaterial(shaderType?: PBMMeshShaderType | {
     shaderType?: PBMMeshShaderType;
 }): PBMMeshMaterial;
-export interface PBMPointCloudMaterial extends THREE.Material, IPBMMaterial {
-}
-export declare class PBMPointCloudMaterial extends THREE.Material implements IPBMMaterial {
-    readonly isPBMMaterial: true;
-    readonly shaderType = "standard";
-    constructor();
-    copy(source: PBMPointCloudMaterial): this;
-}
-export declare function createPBMPointCloudMaterial(): PBMPointCloudMaterial;

package/five/model/materials/pbmPointCloudNodeMaterial.d.ts

@@ -16,7 +16,7 @@ export declare class PBMPointCloudNodeMaterial extends THREE.NodeMaterial {
     pointBack: PBMPointBack;
     colorStyle: PBMColorStyle;
     floorStyle: PBMFloorStyle;
-    vertexMarks: boolean;
+    vertexMarks: boolean | number;
     pointScale: number;
     pointMinPixel: number;
     pointMaxPixel: number;

package/five/model/objects/pbmPointCloud.d.ts

@@ -60,7 +60,6 @@ export declare class PBMPointCloud extends THREE.Mesh<THREE.InstancedBufferGeome
     outlineGain: number;
     distanceGain: number;
     useAddBlend: boolean;
-    vertexMarks: boolean;
     clippers: readonly PBMClipperParameter[];
     readonly modelBoundingMin: THREE.Vector3;
     readonly modelBoundingMax: THREE.Vector3;

package/five/model/objects/pbmPointCloudObject.d.ts

@@ -42,7 +42,7 @@ export declare class PBMPointCloudObject extends THREE.Object3D {
     outlineGain: number;
     distanceGain: number;
     useAddBlend: boolean;
-    vertexMarks: boolean;
+    vertexMarks: boolean | number;
     clippers: readonly PBMClipperParameter[];
     readonly modelBoundingMin: THREE.Vector3;
     readonly modelBoundingMax: THREE.Vector3;

package/five/model/parameter.d.ts

@@ -4,11 +4,12 @@ import type { TileRequestOrder } from './tile3d/types';
 import type { Camera } from '../core/camera';
 export interface ParameterMaterialValue {
     /**
-     * 是否生效标注
-     * 开启后，模型顶点上会预置 `_feature_id_rsmask` 标记。
-     * _feature_id_rsmask=1，在俯视等特定视角下，引擎会自动隐藏被标记的顶点对应的 Mesh，从而实现“开盖”效果，让室内布局观测更加清晰、观感更好。
+     * 是否生效标注（按位掩码 PBMVertexMarkFlag）
+     * 开启后，模型顶点上会预置 `_feature_id_rsmask` 标记，可按位独立控制开盖(roof)与隐藏(hidden)。
+     * _feature_id_rsmask=1 对应 roof，在俯视等特定视角下引擎会自动隐藏被标记的顶点对应的 Mesh，从而实现“开盖”效果，让室内布局观测更加清晰、观感更好。
+     * 兼容旧的 boolean：true=全开(all)，false=全关(none)。
      */
-    vertexMarks: boolean;
+    vertexMarks: boolean | number;
     /** 起始点 */
     pano0: PBMPanoPicture | null;
     /** 结束点 */

package/five/renderer/index.d.ts

@@ -1,3 +1,3 @@
-export { EffectComposer, FivePass, type Pass, AdaptiveLuminancePass, EyeDomeLightingPass, FlowingLight2DPass, type FlowingLight2DPassLine, FlowingLight3DPass, type FlowingLight3DPassLine, GaussianBlurPass, FlowingFireworks3DPass, type FlowingFireworks3DPassLine, } from './postprocessing';
+export { EffectComposer, FivePass, type Pass, AdaptiveLuminancePass, EyeDomeLightingPass, FlowingLight2DPass, type FlowingLight2DPassLine, FlowingLight3DPass, type FlowingLight3DPassLine, type FlowingLightLineInput, GaussianBlurPass, FlowingFireworks3DPass, type FlowingFireworks3DPassLine, } from './postprocessing';
 export { FullScreenQuad } from './tools/full-screen-quad';
 export { FiveRenderer } from './five-renderer';

package/five/renderer/postprocessing/index.d.ts

@@ -4,5 +4,5 @@ export { AdaptiveLuminancePass } from './passes/adaptive-luminance-pass';
 export { EyeDomeLightingPass } from './passes/eye-dome-lighting-pass';
 export { GaussianBlurPass } from './passes/gaussian-blur-pass';
 export { FlowingLight2DPass, type FlowingLight2DPassLine } from './passes/flowing-light-2d-pass';
-export { FlowingLight3DPass, type FlowingLight3DPassLine } from './passes/flowing-light-3d-pass';
+export { FlowingLight3DPass, type FlowingLight3DPassLine, type FlowingLightLineInput } from './passes/flowing-light-3d-pass';
 export { FlowingFireworks3DPass, type FlowingFireworks3DPassLine } from './passes/flowing-fireworks-3d-pass';

package/five/utils/event.d.ts

@@ -87,9 +87,16 @@ export interface GestureEvent extends StateEvent {
     overallVelocityX: number;
     overallVelocityY: number;
 }
+/**
+ * XR 设备类型。
+ * - `Pico`：字节 Pico 系列
+ * - `Oculus`：Meta Quest / Oculus 系列
+ * - `VP`：Apple Vision Pro
+ */
+export type XRMachineType = 'Pico' | 'Oculus' | 'VP';
 export interface XRSessionEvent extends BaseEvent {
     session: XRSession | null;
-    machineType: 'Pico' | 'Oculus';
+    machineType: XRMachineType;
 }
 export interface XRControllerEvent extends BaseEvent {
     left: {
@@ -126,7 +133,7 @@ export interface XRControllerEvent extends BaseEvent {
 export interface XRGestureEvent extends BaseEvent {
     session: XRSession | null;
     buttons: 'A' | 'B' | 'X' | 'Y' | 'RightTrigger' | 'RightPinch' | 'LeftTrigger' | 'LeftPinch' | 'LeftAxesLeft' | 'LeftAxesRight' | 'LeftAxesUp' | 'LeftAxesDown' | 'RightAxesLeft' | 'RightAxesRight' | 'RightAxesUp' | 'RightAxesDown';
-    machineType: 'Pico' | 'Oculus';
+    machineType: XRMachineType;
     isFirst: boolean;
     isFinal: boolean;
     controllers: {

package/five/webxr/XRControllerModelFactory.d.ts

@@ -0,0 +1,55 @@
+import { Object3D } from 'three/webgpu';
+import * as THREE from 'three/webgpu';
+/**
+  * @description Builds a motion controller with components and visual responses based on the
+  * supplied profile description. Data is polled from the xrInputSource's gamepad.
+  * @author Nell Waliczek / https://github.com/NellWaliczek
+*/
+declare class MotionController {
+    /**
+     * @param {Object} xrInputSource - The XRInputSource to build the MotionController around
+     * @param {Object} profile - The best matched profile description for the supplied xrInputSource
+     * @param {Object} assetUrl
+     */
+    xrInputSource: XRInputSource;
+    assetUrl: string;
+    id: any;
+    layoutDescription: any;
+    components: any;
+    constructor(xrInputSource: XRInputSource, profile: any, assetUrl: string);
+    get gripSpace(): XRSpace | undefined;
+    get targetRaySpace(): XRSpace;
+    /**
+     * @description Returns a subset of component data for simplified debugging
+     */
+    get data(): any[];
+    /**
+     * @description Poll for updated data based on current gamepad state
+     */
+    updateFromGamepad(): void;
+}
+declare class XRControllerModel extends Object3D {
+    motionController: MotionController | null;
+    envMap: THREE.Texture | null;
+    constructor();
+    setEnvironmentMap(envMap: THREE.Texture): this;
+    /**
+     * Polls data from the XRInputSource and updates the model's components to match
+     * the real world data
+     */
+    updateMatrixWorld(force: boolean): void;
+}
+declare class XRControllerModelFactory {
+    path: string;
+    _assetCache: any;
+    gltfLoader: {
+        load: (url: string, callback: (result: {
+            scene: THREE.Object3D;
+        }) => void) => any;
+    } | null;
+    constructor(gltfLoader?: {
+        load: () => any;
+    } | null);
+    createControllerModel(controller: any): XRControllerModel;
+}
+export { XRControllerModelFactory };

package/five/webxr/buttonStateMachine.d.ts

@@ -0,0 +1,31 @@
+export type ButtonName = 'A' | 'B' | 'X' | 'Y' | 'LeftTrigger' | 'RightTrigger' | 'LeftPinch' | 'RightPinch';
+export type ButtonEventType = 'buttonDown' | 'press' | 'buttonUp' | 'tap';
+export interface ButtonEvent {
+    type: ButtonEventType;
+    name: ButtonName;
+    source: XRInputSource;
+    time: number;
+    duration: number;
+}
+/** 区分 tap 与 press 的阈值（毫秒）：时长 < 300 为 tap，>= 300（含恰好 300）为 press */
+export declare const TAP_PRESS_THRESHOLD_MS = 300;
+export declare class ButtonStateMachine {
+    /** 以输入源对象为外层键；使用 Map 以便 removeSource / reset 遍历 */
+    private readonly states;
+    /**
+     * 采样一个按键，返回按派发顺序排列的事件（可能为空）。
+     * 严格遵循设计 4.5 的状态转移表。
+     */
+    sample(source: XRInputSource, name: ButtonName, pressed: boolean, time: number): ButtonEvent[];
+    /**
+     * 输入源被移除：该输入源每个按下中的键只派发 buttonUp（不派发 tap / press），
+     * 并清除该输入源的全部状态。
+     */
+    removeSource(source: XRInputSource, time: number): ButtonEvent[];
+    /**
+     * 会话结束：全部按下中的键只派发 buttonUp（不派发 tap / press），并清空全部状态。
+     */
+    reset(time: number): ButtonEvent[];
+    /** 删除单个键的状态；输入源下无按下键时一并移除外层条目 */
+    private deleteState;
+}

package/five/webxr/deviceProfile.d.ts

@@ -0,0 +1,70 @@
+export type DeviceType = 'Pico' | 'Oculus' | 'VP' | 'Default';
+/** 对外事件（`machineType`）中出现的设备类型，不含 `Default`。 */
+export type PublicMachineType = 'Pico' | 'Oculus' | 'VP';
+/** 手柄按键 / 轴映射与模型选择（需求 11.11）。 */
+export interface DeviceProfile {
+    /** `gamepad.buttons` 下标，`null` 表示不映射（VP） */
+    buttons: {
+        trigger: number | null;
+        grip: number | null;
+        primary: number | null;
+        secondary: number | null;
+        pinch: number | null;
+    };
+    /** `gamepad.axes` 下标，`null` 表示不映射 */
+    axes: {
+        x: number | null;
+        y: number | null;
+    };
+    /** `'auto'`：由 `XRControllerModelFactory` 按 profiles 加载；`'none'`：不加载模型 */
+    model: 'auto' | 'none';
+}
+/** 调用方对 {@link DeviceProfile} 的按字段覆盖（需求 11.4）。 */
+export type DeviceProfileOverride = {
+    buttons?: Partial<DeviceProfile['buttons']>;
+    axes?: Partial<DeviceProfile['axes']>;
+    model?: DeviceProfile['model'];
+};
+/** 非法覆盖字段的告警回调，参数为字段名，例如 `'buttons.trigger'`、`'axes.x'`、`'model'`。 */
+export type DeviceProfileWarn = (field: string) => void;
+/**
+ * 四种设备类型的默认 Device_Profile（深冻结，只读）。
+ *
+ * 需要可修改的副本时使用 {@link resolveProfile}。
+ */
+export declare const DEFAULT_PROFILES: Readonly<Record<DeviceType, Readonly<DeviceProfile>>>;
+/**
+ * 通过 UA 判定设备类型（需求 11.3）。
+ *
+ * 判定顺序，命中第一个即返回：
+ * 1. UA 含 `PICO` 或 `Pico`（区分大小写）→ `Pico`（Pico 4 的 UA 同时含 `OculusBrowser`，必须先判 Pico）
+ * 2. UA 含 `Macintosh` 且 `maxTouchPoints === 5` → `VP`
+ * 3. UA 含 `Oculus` → `Oculus`
+ * 4. 其它 → `Default`
+ *
+ * 参数缺省时读取 `navigator.userAgent` / `navigator.maxTouchPoints`；读取抛错一律返回 `Default`，永不抛错。
+ *
+ * @param ua - User-Agent，缺省取 `navigator.userAgent`
+ * @param maxTouchPoints - 最大触点数，缺省取 `navigator.maxTouchPoints`
+ */
+export declare function detectDeviceType(ua?: string, maxTouchPoints?: number): DeviceType;
+/**
+ * 生成实际生效的 Device_Profile（需求 11.4）。
+ *
+ * - 先深拷贝 `type` 对应的默认值（未知类型回落 `Default`），不修改 {@link DEFAULT_PROFILES}。
+ * - 覆盖字段为合法值（`null` 或 ≥ 0 的整数）才覆盖；非法下标回落默认值并调用 `warn(字段名)`。
+ * - `model` 只接受 `'auto'` / `'none'`，非法回落默认值并 `warn('model')`。
+ * - 未提供（`undefined`）的字段保留默认值，不告警。
+ *
+ * @param type - 设备类型
+ * @param override - 调用方覆盖
+ * @param warn - 非法字段告警回调，参数为字段名（如 `'buttons.trigger'`）
+ * @returns 新对象，可自由修改
+ */
+export declare function resolveProfile(type: DeviceType, override?: DeviceProfileOverride, warn?: DeviceProfileWarn): DeviceProfile;
+/**
+ * 把内部设备类型映射为事件中 `machineType` 的公开取值（需求 13.1）。
+ *
+ * `Default` 映射为 `'Pico'`，与迁移前“其余归为 Pico”的行为一致；其余原样返回。
+ */
+export declare function toPublicMachineType(device: DeviceType): PublicMachineType;

package/five/webxr/inputSourceTracker.d.ts

@@ -0,0 +1,59 @@
+import * as THREE from "three/webgpu";
+/**
+ * 单个输入源的追踪条目。
+ */
+export interface TrackedInput {
+    /** 对应的 XR 输入源（条目的键，与 `session.inputSources` 下标无关） */
+    source: XRInputSource;
+    /** target ray 节点，位置/朝向直接写世界值（已加 offset） */
+    targetRay: THREE.Object3D;
+    /** grip 节点，位置/朝向直接写世界值（已加 offset） */
+    grip: THREE.Object3D;
+    /** 最近一次 target ray 成功更新（pose 非空）时的帧号 */
+    rayFrame: number;
+}
+export declare class InputSourceTracker {
+    /** 所有手柄节点的父节点；调用方负责把它加入 scene，`clear()` 不会移除它自身 */
+    readonly root: THREE.Group<THREE.Object3DEventMap>;
+    private readonly _entries;
+    /** `fill` 用的临时向量，避免每次调用分配 */
+    private readonly _dir;
+    /**
+     * 为 `inputsourceschange` 中 `added` 的输入源新增追踪条目。
+     * 已存在的输入源被忽略（不重建节点）。新节点初始不可见，待首个有效 pose 到来后显示。
+     */
+    add(sources: readonly XRInputSource[]): void;
+    /**
+     * 删除 `inputsourceschange` 中 `removed` 的输入源条目，并把节点从 `root` 移除。
+     *
+     * @returns 实际被删除的条目（未追踪的输入源不会出现在结果中）
+     */
+    remove(sources: readonly XRInputSource[]): TrackedInput[];
+    update(frame: XRFrame, ref: XRReferenceSpace, offset: THREE.Vector3, frameNo: number): void;
+    /**
+     * 隐藏全部节点，保持上一帧的位置与朝向不变（需求 6.10：Head_Pose 为 `null` 时调用）。
+     * 不触碰 `rayFrame`，由 `fill` 对 `visible` 的检查保证不会再填充射线。
+     */
+    hideAll(): void;
+    /**
+     * 用指定输入源本帧的 target ray 填充复用的 Raycaster（需求 6.8）。
+     *
+     * 仅当该输入源有条目、`rayFrame === frameNo` 且 target ray 节点可见时才写入：
+     * origin 为节点世界位置，direction 为局部 -Z 经世界旋转后的单位向量。
+     * 否则不修改 `raycaster`。
+     *
+     * @returns 本帧是否已填充
+     */
+    fill(source: XRInputSource, raycaster: THREE.Raycaster, frameNo: number): boolean;
+    /**
+     * 清空全部追踪条目，并把所有节点从 `root` 移除（需求 6.11）。
+     * `root` 自身不移除，由调用方管理。
+     */
+    clear(): void;
+    /** 当前全部追踪条目（键为 `XRInputSource` 对象） */
+    entries(): ReadonlyMap<XRInputSource, TrackedInput>;
+    /**
+     * 把参考空间位姿写入节点：位置加 offset、朝向直接取 pose，并同步世界矩阵。
+     */
+    private _applyPose;
+}

package/five/webxr/referenceSpace.d.ts

@@ -0,0 +1,60 @@
+/** 单个类型的失败原因：被拒绝 / 超时。 */
+export type ReferenceSpaceFailureReason = 'rejected' | 'timeout';
+/** 一次失败的尝试记录。 */
+export interface ReferenceSpaceFailure {
+    type: XRReferenceSpaceType;
+    reason: ReferenceSpaceFailureReason;
+}
+/** 解析结果。 */
+export interface ResolvedReferenceSpace {
+    /** 实际采用的参考空间对象 */
+    space: XRReferenceSpace;
+    /** 实际采用的类型 */
+    type: XRReferenceSpaceType;
+    /** 采用之前失败的类型（按尝试顺序） */
+    failures: ReferenceSpaceFailure[];
+}
+/** 解析选项。 */
+export interface ResolveReferenceSpaceOptions {
+    /** 单次请求的超时毫秒数，默认 5000 */
+    timeoutMs?: number;
+    /** 会话是否已提前结束；每次 await 之后检查，为真则抛出 aborted 错误 */
+    isAborted?: () => boolean;
+    /** 注入的 setTimeout，便于假计时器；默认使用全局 setTimeout */
+    schedule?: (callback: () => void, ms: number) => unknown;
+    /** 注入的 clearTimeout，与 schedule 配对；默认使用全局 clearTimeout */
+    clear?: (handle: any) => void;
+}
+/** 全部类型失败时抛出的错误：附带按尝试顺序排列的 `attempts`。 */
+export interface ReferenceSpaceExhaustedError extends Error {
+    attempts: ReferenceSpaceFailure[];
+}
+/** 会话提前结束时抛出的错误：带 `aborted: true` 标记。 */
+export interface ReferenceSpaceAbortedError extends Error {
+    aborted: true;
+}
+/** 单次请求默认超时（毫秒）。 */
+export declare const DEFAULT_REFERENCE_SPACE_TIMEOUT_MS = 5000;
+/** 判断一个错误是否为「会话在参考空间解析前已结束」。 */
+export declare function isReferenceSpaceAbortedError(error: unknown): error is ReferenceSpaceAbortedError;
+/**
+ * 构造降级链：`[preferred, 'local', 'viewer']` 去重并保持顺序，且以 'viewer' 收尾。
+ *
+ * 去重后在第一个 'viewer' 处截断：期望类型为 'viewer' 时链仅含 'viewer'，
+ * 不会在 viewer 失败后再多请求一次 'local'（需求 10.1）。
+ *
+ * @param preferred - 期望的参考空间类型
+ * @returns 降级链（preferred 为 'local' 时 ['local','viewer']；为 'viewer' 时 ['viewer']；
+ *          其它类型 x 时 [x,'local','viewer']）
+ */
+export declare function buildChain(preferred: XRReferenceSpaceType): XRReferenceSpaceType[];
+/**
+ * 解析参考空间：按降级链串行请求，采用第一个成功的类型。
+ *
+ * @param session - 当前 XRSession
+ * @param preferred - 期望的参考空间类型
+ * @param opts - 超时、中止检查与计时器注入
+ * @returns 采用的空间、类型与此前的失败记录
+ * @throws 会话提前结束时抛出 `aborted: true` 的错误；全部失败时抛出带 `attempts` 的错误
+ */
+export declare function resolveReferenceSpace(session: XRSession, preferred: XRReferenceSpaceType, opts?: ResolveReferenceSpaceOptions): Promise<ResolvedReferenceSpace>;

package/five/webxr/renderTargetBridge.d.ts

@@ -0,0 +1,45 @@
+import * as THREE from "three/webgpu";
+/** 每只眼的渲染信息：viewport 为 XRViewport 语义（左下原点的 x, y, width, height） */
+export interface BridgeEye {
+    camera: THREE.PerspectiveCamera;
+    viewport: THREE.Vector4;
+}
+export interface RenderTargetBridgeOptions {
+    /** 眼图集 MSAA 采样数，默认 0 */
+    atlasSamples?: number;
+}
+export declare class RenderTargetBridge {
+    private readonly renderer;
+    private readonly atlasSamples;
+    private resources;
+    private warnedRevision;
+    private _outputBufferType;
+    private readonly clearColorScratch;
+    private readonly viewportScratch;
+    constructor(renderer: THREE.WebGPURenderer, opts?: RenderTargetBridgeOptions);
+    /** `init` 时读取的 `renderer.getOutputBufferType()`（未初始化为 `null`），只供诊断（风险 R5）。 */
+    get outputBufferType(): number | null;
+    /**
+     * 检查 three 内部 API 是否存在、四个标志位值是否符合预期（需求 4.6）。
+     * 缺失或不符时抛出含全部问题名称与 `THREE.REVISION` 的错误。
+     */
+    verify(): void;
+    /** 检查 Eye_Camera 与 renderer 的 `coordinateSystem` 一致（design「进入时校验 camera.coordinateSystem」）。 */
+    verifyCameras(cameras: ReadonlyArray<THREE.Camera>): void;
+    /** 为 layer 创建眼图集、XR 输出目标与解析 quad；重复调用会先释放旧资源。 */
+    init(layer: XRWebGLLayer): void;
+    /**
+     * 一帧：清图集 → 逐眼渲染 → 解析。任何异常在 `finally` 恢复 renderer 状态后原样抛出（需求 4.7）。
+     * `eyes[i].viewport` 是 XRViewport 语义（左下原点）。
+     */
+    renderFrame(layer: XRWebGLLayer, scene: THREE.Scene, eyes: ReadonlyArray<BridgeEye>): void;
+    /** 幂等释放（需求 4.4）：目标各 dispose 至多一次，输出目标与 XR framebuffer 复位为 `null`。 */
+    dispose(): void;
+    /** 尺寸或 baseLayer 变化（或尚未创建）时重建，返回当前可用的资源（需求 4.8）。 */
+    private syncResources;
+    private build;
+    /** 释放当前资源（不动 renderer 状态；状态由 renderFrame 的 finally 与 dispose 负责）。 */
+    private releaseResources;
+    /** 检测 `EXT_color_buffer_float` / `EXT_color_buffer_half_float`；拿不到 GL 上下文时按不支持处理。 */
+    private supportsHalfFloat;
+}

package/five/webxr/xrButton.d.ts

@@ -0,0 +1,4 @@
+declare class XRButton {
+    static createButton(onClickHook: () => void | Promise<unknown>): HTMLAnchorElement | HTMLButtonElement;
+}
+export { XRButton };

package/five/webxr/xrManager.d.ts

@@ -0,0 +1,174 @@
+import * as THREE from "three/webgpu";
+import { InputSourceTracker } from "./inputSourceTracker";
+import { DeviceType, DeviceProfile, DeviceProfileOverride } from "./deviceProfile";
+export type { DeviceType } from "./deviceProfile";
+export interface XRManagerOptions {
+    /** 期望参考空间类型，默认 'local-floor'（需求 10） */
+    referenceSpaceType?: XRReferenceSpaceType;
+    /** 0..1，XR_Layer 支持 fixedFoveation 时设置（需求 1.13） */
+    foveation?: number;
+    /** 调用方覆盖 Device_Profile（需求 11.4） */
+    deviceProfile?: DeviceProfileOverride;
+    /** 首帧超时，默认 5000ms（需求 2.9） */
+    firstFrameTimeoutMs?: number;
+    /** 眼图集 MSAA 采样数，默认 0，透传给 RenderTargetBridge */
+    atlasSamples?: number;
+}
+export interface XRManagerCallbacks {
+    onSessionStart(session: XRSession, device: DeviceType): void;
+    onSessionEnd(device: DeviceType): void;
+    /**
+     * 会话结束归还流程中、`inputs.clear()` 之前调用，供控制器重置按键状态（需求 8.9）。
+     * 回调抛错不会中断归还。
+     */
+    onSessionEnding?(): void;
+    /** session 'select' 事件，供 gaze / transient-pointer 走点（需求 9.4） */
+    onSelect?(source: XRInputSource): void;
+    /** inputsourceschange，供控制器创建 / 移除手柄模型（需求 7.3、7.5） */
+    onInputSourcesChange?(added: readonly XRInputSource[], removed: readonly XRInputSource[]): void;
+}
+export interface FrameInfo {
+    time: number;
+    /** Head_Pose 为 null 或 views 数量不是 1/2 时为 false（需求 3.6） */
+    hasPose: boolean;
+    /** 仅 hasPose 时有效 */
+    headOrientation: THREE.Quaternion;
+    /** 各 view 平移均值（需求 6.2），仅 hasPose 时有效 */
+    headLocal: THREE.Vector3;
+    /** 与 Eye_Camera 对应的 view 列表，保持 Head_Pose.views 顺序；viewport 为 XRViewport 语义（左下原点） */
+    views: ReadonlyArray<{
+        eye: 0 | 1;
+        viewport: THREE.Vector4;
+    }>;
+}
+export declare class XRManager {
+    /**
+     * 后端是否支持 XR（后端非 WebGPU 即可）。
+     * 以实际 backend 为准：`backend.isWebGPUBackend !== true`。
+     */
+    static isBackendXRCapable(renderer: THREE.WebGPURenderer): boolean;
+    /** 浏览器是否暴露了 WebXR 入口（只检查 `navigator.xr` 是否存在，不发起权限请求）。 */
+    static isBrowserXRCapable(): boolean;
+    /** 恒为长度 2 的元组，会话内（实际是整个 XRManager 生命周期内）同一对实例（需求 3.1） */
+    readonly eyeCameras: readonly [THREE.PerspectiveCamera, THREE.PerspectiveCamera];
+    readonly inputs: InputSourceTracker;
+    readonly device: DeviceType;
+    readonly profile: Readonly<DeviceProfile>;
+    get isPresenting(): boolean;
+    get session(): XRSession | null;
+    get frame(): XRFrame | null;
+    /** 实际采用的参考空间类型，未进入或已结束时为 null（需求 10.5） */
+    get referenceSpaceType(): XRReferenceSpaceType | null;
+    private readonly renderer;
+    private readonly options;
+    private readonly callbacks;
+    private readonly bridge;
+    private _isPresenting;
+    private _session;
+    private _frame;
+    private _referenceSpaceType;
+    private refSpace;
+    private layer;
+    /** enter 流程进行中 */
+    private entering;
+    /** enter 流程已完成且尚未归还 */
+    private entered;
+    /** 进入期间会话已结束（需求 1.11） */
+    private endedDuringEnter;
+    private snapshot;
+    private readonly listeners;
+    private firstFrameArrived;
+    private firstFrameWaiter;
+    private frameNo;
+    private submittedNear;
+    private submittedFar;
+    private readonly offset;
+    private readonly info;
+    /** 池化的 view 条目，最多 2 个 */
+    private readonly viewPool;
+    /** 当前帧有效的 view（`info.views` 指向它） */
+    private readonly frameViews;
+    private readonly bridgeEyes;
+    private readonly tmpViewport;
+    private readonly tmpSize;
+    constructor(renderer: THREE.WebGPURenderer, options: XRManagerOptions, callbacks: XRManagerCallbacks);
+    /**
+     * 进入 XR（design 4.1 的 11 个步骤）。
+     * 幂等：进入中或已进入时直接返回。失败时回滚到进入前状态并抛出原始错误。
+     */
+    enter(session: XRSession): Promise<void>;
+    /**
+     * 主动退出：已进入时调用一次 `session.end()`，归还由随后的 `end` 事件完成（需求 1.5）。
+     * `end()` reject 时在本地完成归还且不外抛（需求 1.12）。未进入时直接返回。
+     */
+    exit(): Promise<void>;
+    /**
+     * 析构，幂等。
+     * - 进入中：中止进入（enter 会以“会话在进入过程中已结束”reject）并尝试结束会话；
+     * - 已进入：同步完成本地归还，再尝试 `session.end()`（其后到达的 end 事件因监听已移除而被忽略）；
+     * - 未进入：直接返回。
+     */
+    dispose(): void;
+    /**
+     * 每帧第一步（design 4.2）：计算 Head_Pose、更新两个 Eye_Camera 与手柄位姿、同步深度范围、统计诊断。
+     *
+     * 返回的 `FrameInfo` 是内部复用的对象，仅在下一次 `beginFrame` 之前有效。
+     * 尚未就绪（参考空间还没解析完，例如 `Five.changeMode` 提前 `setContext(session)` 后到达的帧）时返回 `hasPose = false`，
+     * 且不计入首帧、不计入统计。
+     *
+     * @param station Station_Position（five Camera 位置）
+     */
+    beginFrame(frame: XRFrame, time: number, station: THREE.Vector3, near: number, far: number): FrameInfo;
+    /**
+     * 渲染本帧：清图集一次 → 逐眼 render → 解析 pass。
+     * `hasPose` 为假或尚未就绪返回 `false`（本帧被跳过）；否则返回 `true`。
+     * `renderer.render` 抛错时由 Bridge 恢复状态后原样抛出。
+     */
+    renderEyes(scene: THREE.Scene): boolean;
+    /** 以 target ray 填充射线，返回本帧是否已填充（需求 6.8） */
+    fillRaycaster(source: XRInputSource, raycaster: THREE.Raycaster): boolean;
+    private markNoPose;
+    /**
+     * 建立眼映射并读取各 view 的 viewport，写入 `frameViews`（需求 3.2）。
+     * `left` / `none` → 0，`right` → 1；该下标已被前一个 view 占用时取另一只。
+     * 任一 view 取不到 viewport 时返回 false，调用方按无姿态处理（此时尚未改动任何 Eye_Camera）。
+     */
+    private collectViews;
+    /** near/far 与最近一次提交值不同时才更新一次 renderState（需求 1.10） */
+    private syncDepthRange;
+    private notifyFirstFrame;
+    private throwIfEnded;
+    private waitFirstFrame;
+    /** 把 `session.inputSources` 里尚未追踪的输入源补进来并通知控制器 */
+    private syncExistingInputSources;
+    private listen;
+    private removeListeners;
+    /** 稳定的箭头函数字段，保证 add / remove 用同一个引用 */
+    private onSessionEndEvent;
+    private onInputSourcesChangeEvent;
+    private onSelectEvent;
+    /** 沿用同一参考空间对象；Station_Position 不变，下一帧 beginFrame 会依据新 Head_Pose 重算 */
+    private onReferenceSpaceReset;
+    /** 记录渲染器状态（视口、autoClear*、pixelRatio、尺寸）。不主动调用 setPixelRatio / setSize。 */
+    private captureRendererState;
+    /** 恢复记录点；仅在值不同时才还原（避免无谓的 setPixelRatio / setSize 重置视口） */
+    private restoreRendererState;
+    /** 仅当 AnimationFrameLoop 的 context 仍是本 session 时才置 null，避免误清别人的 context */
+    private releaseFrameSource;
+    /** 清空会话相关引用（不含回调） */
+    private clearReferences;
+    /**
+     * 进入失败的回滚（幂等）：移除监听、`bridge.dispose`、`setContext(null)`、恢复渲染器状态、清引用。
+     * 不调用任何回调；不结束 session（交给调用方决定）。
+     */
+    private rollback;
+    /**
+     * 会话结束归还（`end` 事件 / `exit` 中 `end()` reject / `dispose` 共用），固定顺序（design 4.1）：
+     * isPresenting=false → onSessionEnding → inputs.clear → bridge.dispose → 移除监听 → setContext(null)
+     * → 恢复渲染器状态 → 清引用 → onSessionEnd。
+     * `_session` 已为 null 时（重复调用）直接忽略。
+     */
+    private teardown;
+    /** fire-and-forget 结束会话，吞掉可能的 reject（会话可能已在结束中） */
+    private endQuietly;
+}