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

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/compute-renderers/pointcloud-compute-renderer.d.ts

@@ -9,6 +9,8 @@ import type { PBMPointCloud } from '../../model/objects/pbmPointCloud';
 export declare class PointCloudComputeRenderer {
     private device;
     private format;
+    /** 显示 pipeline 的 color target 格式，需与目标 RT 的 GPU 纹理格式一致 */
+    get colorFormat(): GPUTextureFormat;
     private width;
     private height;
     private pointBuffer;

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