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

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/model/tile3d/index.d.ts

@@ -73,6 +73,8 @@ export declare class Tile3D extends THREE.Object3D {
     loadContent(tile: Tile): Promise<void>;
     unloadContent(tile: Tile): Promise<void>;
     loadAllTilesets(): Promise<void>;
+    loadTrajectory(trajectory: Trajectory): Promise<void>;
+    unloadTrajectory(trajectory: Trajectory): Promise<void>;
     intersectRaycaster(raycaster: THREE.Raycaster, target?: Intersection[]): Intersection[];
     update(renderer: THREE.WebGPURenderer, camera: Camera, modelScene: ModelScene, model: Model): boolean;
     dispose(): void;

package/five/model/tile3d/tileset.d.ts

@@ -12,6 +12,11 @@ export interface TilesetOptions {
     onTileLoad: (tile: Tile) => any;
     onTileUnload: (tile: Tile) => any;
     onTileError: (tile: Tile, error: Error) => any;
+    trajectoryLoader: (trajectory: Trajectory) => Promise<void>;
+    trajectoryUnloader: (trajectory: Trajectory) => Promise<void>;
+    onTrajectoryLoad: (trajectory: Trajectory) => any;
+    onTrajectoryUnload: (trajectory: Trajectory) => any;
+    onTrajectoryError: (trajectory: Trajectory, error: Error) => any;
 }
 export declare class Tileset {
     asset: {

package/five/model/tile3d/trajectory-content.d.ts

@@ -0,0 +1,53 @@
+import * as THREE from 'three/webgpu';
+import type { Trajectory } from './trajectory';
+import { Fetcher } from '../../utils/ajax';
+/**
+ * 轨迹的两套自定义着色器原为 GLSL `ShaderMaterial`，WebGPURenderer 只支持 NodeMaterial
+ * （其它材质类型会被退化成空白 NodeMaterial），这里按 GLSL 逐层翻译为 TSL：
+ *
+ * 管道 TRAJECTOR_PIPE：
+ *   vertex:   `vUv = uv;` + `transformed += normalize(objectNormal) * displacementScalar`
+ *   fragment: `if (mod(abs(vUv.x * totalLength + dashOffset), dashSize.x + dashSize.y) > dashSize.x) discard;`
+ *             `vec4 diffuseColor = vec4(mix(diffuse, diffuse2, vUv.x), opacity);`
+ * 圆球 TRAJECTOR_SPHERE：
+ *   vertex:   `transformed += normalize(objectNormal) * displacementScalar`
+ *   fragment: `vec4 diffuseColor = vec4(diffuse, opacity);`
+ *
+ * 说明：
+ * - 原 shader 里的 `<tonemapping_fragment>` / `<colorspace_fragment>` 由渲染器的 Output 通道统一处理
+ *   （WebGPURenderer 把 tone mapping 与输出色彩空间放到独立的输出 pass），<fog_fragment> /
+ *   `<premultiplied_alpha_fragment>` 对应 NodeMaterial 的 `fog` / `premultipliedAlpha` 属性（默认 fog 生效）。
+ * - 颜色不再调用 `convertSRGBToLinear()`：r152+ 的 `new THREE.Color(hex)` 已经按 sRGB 解释并转到线性工作空间，
+ *   再转换一次会变暗。
+ * - `uniform()` 生成的 uniform 节点保留 `.value` 读写，所以材质上挂的 `uniforms` 与 GLSL 版本用法一致
+ *   （见 trajectory-node.ts 的 dashOffset 动画）。
+ */
+declare function createPipeUniforms(): {
+    diffuse: THREE.UniformNode<"color", THREE.Color>;
+    diffuse2: THREE.UniformNode<"color", THREE.Color>;
+    opacity: THREE.UniformNode<"float", number>;
+    displacementScalar: THREE.UniformNode<"float", number>;
+    totalLength: THREE.UniformNode<"float", number>;
+    dashSize: THREE.UniformNode<"vec2", THREE.Vector2>;
+    dashOffset: THREE.UniformNode<"float", number>;
+};
+declare function createSphereUniforms(): {
+    diffuse: THREE.UniformNode<"color", THREE.Color>;
+    opacity: THREE.UniformNode<"float", number>;
+    displacementScalar: THREE.UniformNode<"float", number>;
+};
+export type TrajectoryPipeUniforms = ReturnType<typeof createPipeUniforms>;
+export type TrajectorySphereUniforms = ReturnType<typeof createSphereUniforms>;
+export type TrajectoryPipeMaterial = THREE.NodeMaterial & {
+    uniforms: TrajectoryPipeUniforms;
+};
+export type TrajectorySphereMaterial = THREE.NodeMaterial & {
+    uniforms: TrajectorySphereUniforms;
+};
+export declare function loadTrajectory<T extends Trajectory>(trajectory: T, options: {
+    fetcher: Fetcher;
+    search?: string;
+    renderer?: THREE.WebGPURenderer;
+}): Promise<T>;
+export declare function unloadTrajectory(trajectory: Trajectory): void;
+export {};

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/texture/loader.d.ts

@@ -27,6 +27,12 @@ export declare class TextureLoader {
             options?: ImageURLOptions;
         };
         format?: THREE.PixelFormat;
+        /**
+         * 色彩空间
+         * @description 缺省为 `SRGBColorSpace`（颜色贴图）。非颜色数据（如 gainmap）应显式传 `NoColorSpace`，
+         * 否则会被当成 sRGB 解码（WebGPU 下会创建 `rgba8unorm-srgb` 做硬件解码）。
+         */
+        colorSpace?: THREE.ColorSpace;
         minFilter?: THREE.TextureFilter;
         magFilter?: THREE.TextureFilter;
         generateMipmaps?: boolean;

package/five/types/cube.d.ts

@@ -1,2 +1 @@
 export type CubeFace = 'right' | 'left' | 'up' | 'down' | 'front' | 'back';
-export type GainMapFace = 'gainmap_right' | 'gainmap_left' | 'gainmap_up' | 'gainmap_down' | 'gainmap_front' | 'gainmap_back';

package/five/utils/detector.d.ts

@@ -1,8 +1,18 @@
 declare const userAgent: string;
+declare const isHdrHighDynamicRange: () => boolean;
 /**
  * 是否可以使用 webgl
  */
 declare const canWebGL: boolean;
+/**
+ * 是否可以使用 webgpu
+ * @description
+ * 初始值基于 `navigator.gpu` 是否存在做同步判断，随后通过 `navigator.gpu.requestAdapter()`
+ * 异步校正（部分设备/浏览器声明了 `navigator.gpu` 但实际无可用 adapter）。
+ * 因此该值在页面刚加载的极短时间内可能还未完成校正，如需强一致的判断请使用 `canWebGPUAsync`。
+ */
+declare let canWebGPU: boolean;
+declare const canWebGPUAsync: Promise<boolean>;
 /**
  * 是否可以 pushState
  */
@@ -11,4 +21,4 @@ declare const canPushState: boolean;
  * 是否是通过手机访问
  */
 declare const isMobile: boolean;
-export { userAgent, canWebGL, canPushState, isMobile, };
+export { userAgent, isHdrHighDynamicRange, canWebGL, canWebGPU, canWebGPUAsync, canPushState, isMobile, };

package/five/utils/error.d.ts

@@ -0,0 +1 @@
+export declare function toError(error: any): Error;

package/five/utils/event.d.ts

@@ -12,7 +12,10 @@ export interface BaseEvent {
     type: string;
     timeStamp: number;
     preventDefault(): void;
-    defaultPrevented: boolean;
+    readonly defaultPrevented: boolean;
+}
+export interface BaseExtendableEvent extends BaseEvent {
+    waitUntil(f: Promise<any>): void;
 }
 export interface IntersectEvent extends BaseEvent {
     object: THREE.Object3D;
@@ -29,6 +32,17 @@ export interface PanoEvent extends StateEvent {
     options: MovePanoOptions;
     error: Error | null;
 }
+/** 全景图准备事件 */
+export interface PanoPrepareEvent extends BaseExtendableEvent {
+    /** 切换时选项 */
+    options: MovePanoOptions;
+    /** 切换前模态 */
+    prevMode: Mode;
+    /** 切换前的全景图 */
+    prevPano: Pano;
+    /** 全景图 */
+    pano: Pano;
+}
 export interface PanoTextureEvent extends BaseEvent {
     pano: Pano;
     progress: number;
@@ -73,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: {
@@ -112,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: {
@@ -157,3 +178,5 @@ export interface NetworkResourceEvent extends BaseEvent {
     detail: string;
 }
 export declare function createEvent<T extends BaseEvent = BaseEvent>(type: string, eventArgs: Omit<T, keyof BaseEvent>): T;
+export declare function createExtendableEvent<T extends BaseExtendableEvent = BaseExtendableEvent>(type: string, eventArgs: Omit<T, keyof BaseExtendableEvent>): T;
+export declare function waitForExtendableEvent(event: BaseExtendableEvent): Promise<void>;

package/five/utils/gainmap-data.d.ts

@@ -0,0 +1,23 @@
+export interface GainmapCfgData {
+    /** gainmap 最大亮度增益 */
+    maxContentBoost: number;
+    /** gainmap 最小亮度增益（通常为 1） */
+    minContentBoost: number;
+    /** 显示器 HDR 容量下限（通常为 1） */
+    hdrCapacityMin: number;
+    /** 显示器 HDR 容量上限 */
+    hdrCapacityMax: number;
+    /** gainmap gamma 值 */
+    gamma: number;
+    /** SDR 偏移，缺省 1/64（UltraHDR 规范） */
+    offsetSdr: number;
+    /** HDR 偏移，缺省 1/64（UltraHDR 规范） */
+    offsetHdr: number;
+}
+/**
+ * `GainmapCfgData` 的默认值（UltraHDR 规范默认值）
+ *
+ * offset 取规范默认 1/64：编码/解码 offset 必须一致，数据里显式提供时以数据为准
+ */
+export declare const DEFAULT_GAINMAP_CFG_DATA: Readonly<GainmapCfgData>;
+export declare function parseGainmapCfgData(input: unknown): GainmapCfgData;

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 };