@realsee/five-webgpu 1.0.0-alpha.1 → 1.0.0-alpha.10

package/five/utils/uuid.mjs

@@ -0,0 +1,255 @@
+/**
+ * @license
+ * @realsee/five-webgpu
+ * Generated: 10/26/2026
+ * Version: 1.0.0-alpha.10
+ * Terms:
+ * Realsee SDK License Agreement
+ * Update: July 28, 2021
+ * THIS LICENSE AGREEMENT BETWEEN YOU AND 【BEIKE REALSEE TECHNOLOGY (HK) 
+ * LIMITED】(“Realsee”) FORMS A LEGALLY BINDING CONTRACT BETWEEN YOU AND REALSEE IN 
+ * RELATION TO YOUR USE OF THE SDK. This License Agreement accompanies the Realsee 
+ * Software Development Kit(s) for the software and related explanatory materials 
+ * (the "SDK") and includes any upgrades, modified versions, updates, additions, 
+ * and copies of the SDK licensed to You by Realsee.
+ * BY DOWNLOADING, INSTALLING, OR OTHERWISE ACCESSING OR USING THE SDK, YOU AGREE 
+ * THAT YOU HAVE READ, UNDERSTOOD, AND AGREE TO BE BOUND BY THIS AGREEMENT. YOU ARE 
+ * AGREEING ON YOUR OWN BEHALF AND/OR ON BEHALF OF YOUR COMPANY OR ORGANIZATION TO 
+ * THE TERMS AND CONDITIONS STATED BELOW.
+ * This Agreement applies to Your use of the SDK in the country in which You 
+ * legally install it (“Territory”) and is subject to the laws of such Territory 
+ * and further subject to Section 12 below. Different terms, conditions, and 
+ * limitations may apply to the use of the SDK in any additional countries.
+ * 1. DEFINITIONS.
+ * “Agreement” means this Realsee SDK License Agreement.
+ * “Developer”, “You” and “Your” means the person(s) or entity acquiring or using 
+ * the SDK or otherwise exercising rights under the terms of this Agreement.
+ * “Documentation” means the technical or other specifications or documentation 
+ * that Realsee may provide to You for use in connection with the SDK.
+ * “Integrated Product” means any software, website, or on-line service developed 
+ * by You based on or using the SDK (collectively, the “Integrated Product”).
+ * “Intellectual Property” means any patents, patent rights, trademarks, service 
+ * marks, registered and unregistered designs, applications for any of the 
+ * foregoing, copyright, and any other similar protected rights in any country and 
+ * to the extent recognised by any relevant jurisdiction as intellectual property, 
+ * trade secrets, know-how and confidential information. Realsee reserves all 
+ * rights not expressly granted to You.
+ * “Realsee” means [Beike Realsee Technology (HK) Limited, a company incorporated 
+ * and validly existing under the laws of Hong Kong].
+ * “SDK” means the Realsee-proprietary Software Development Kits (SDK) provided 
+ * hereunder, includes all development tools (including any compiler and debugger), 
+ * application programming interfaces (“APIs”), libraries, binary utilities, header 
+ * files, Documentation, content, data, code samples, and other materials provided 
+ * to You in connection with this Agreement, whether delivered through a download, 
+ * or any other media or form, and is licensed, not sold, to You by Realsee for use 
+ * only under the terms of this Agreement. The terms of this Agreement will govern 
+ * any updates provided by Realsee that replace and/or supplement the original SDK 
+ * delivered to You, unless such update is accompanied by a separate license, in 
+ * which case the terms of such license will govern.
+ * 2. LICENSED USES AND RESTRICTIONS.
+ * 2.1 Subject to the restrictions contained in this Section 2, Realsee grants to 
+ * You during the term, a limited, non-exclusive, revocable, non-sublicensable, 
+ * non-transferable license to install and use the SDK within the Territory only 
+ * for the purpose of internal development.
+ * 2.2 Restrictions. You acknowledge and agree that, You shall not, and shall 
+ * ensure that Your affiliates, employees, agents, representatives, officers, 
+ * representatives, and subcontractors do not (directly or indirectly):
+ * 2.2.1 decompile, reverse engineer, disassemble or attempt to derive the source 
+ * code of, those components of the SDK provided in object code form, or any part 
+ * thereof;
+ * 2.2.2 remove, alter, or obscure any copyright notice or other proprietary rights 
+ * notice on any part of the SDK;
+ * 2.2.3 sell, assign, pledge, rent, lease, lend, upload to or host on any website 
+ * or server for use by any third party except You, redistribute, or sublicense the 
+ * SDK (or any part thereof), or operate the SDK (or any part thereof) in the 
+ * capacity of a service bureau or other hosted services provider, in whole or in 
+ * part, nor may You enable others to do so;
+ * 2.2.4 or alter, modify, customize or improve the SDK, or any part thereof;
+ * 2.2.5 use the SDK (or any part thereof) for any illegal purpose, in any manner 
+ * that is inconsistent with the terms of this Agreement, or to engage in any 
+ * illegal activity;
+ * 2.2.6 use the SDK (or any part thereof) in any manner that may damage the 
+ * operation of Realsee’s products or services; or
+ * 2.2.7 use the SDK or any information contained therein or otherwise provided by 
+ * Realsee for the purpose of developing, or having developed, any product 
+ * competitive with any Realsee product or service, as determined by Realsee in its 
+ * sole discretion;
+ * 2.2.8 include any portion of the SDK in Your Developer products.
+ * 2.3 Realsee has the right to impose reasonable conditions such as a reasonable 
+ * fee for use of the SDK in Integrated Product in the future.
+ * 2.4 You may make a limited number of copies of the SDK to be used by Your 
+ * employees or consultants as provided herein, and not for general business 
+ * purposes, and such employees or consultants shall be subject to the obligations 
+ * and restrictions in this Agreement.
+ * 2.5 All licenses not expressly granted in this Agreement are reserved and no 
+ * other licenses, immunity, or rights, express or implied, are granted by Realsee, 
+ * by implication, estoppel, or otherwise.
+ * 3. CONFIDENTIALITY.
+ * The SDK and all source code, Documentation, specifications, engineering details, 
+ * and related information pertaining to the SDK, whether in oral, written, 
+ * graphic, or electronic form, are and shall remain the confidential and 
+ * proprietary information of Realsee or its licensors (collectively, the 
+ * “Confidential Information”). You shall (i) disclose Confidential Information to 
+ * only those directors and employees (collectively, “Affiliates”) whose duties 
+ * justify their need to know such information and who have been clearly informed 
+ * of their obligation to maintain the confidential, proprietary, and/or trade 
+ * secret status of such Confidential Information; and (ii) use Confidential 
+ * Information solely in accordance with the license granted hereunder. In any 
+ * event, You and Your Affiliates shall treat Confidential Information as strictly 
+ * confidential and shall use the same care to prevent disclosure of such 
+ * information as You use with respect to Your own similar confidential and/or 
+ * proprietary information, which shall not be less than the care a reasonable 
+ * person would use under similar circumstances. All Confidential Information, and 
+ * any copies thereof, shall be returned promptly to Realsee upon request. You 
+ * shall ensure that Your Affiliates comply with the provisions of this Section 3, 
+ * and You shall be liable for any breach of this Section 3 resulting from the act 
+ * or omission of any of Your Affiliates. You shall not disclose Confidential 
+ * Information to any third party, including, without limitation, any of Your 
+ * subcontractors.
+ * 4. PROPRIETARY RIGHTS.
+ * 4.1 As between You and Realsee, Realsee and/or its licensors retain ownership of 
+ * all right, title, and interest in, to, and under the SDK, including, without 
+ * limitation, all patents, copyrights, trade secrets, trademarks and other 
+ * intellectual property and other proprietary rights therein, and reserve all 
+ * rights not expressly granted to You.
+ * 4.2 The items contained in the SDK are the intellectual property of Realsee and 
+ * its licensors and are protected by PRC copyright and patent law, international 
+ * treaty provisions and applicable laws of the country in which it is being used. 
+ * You agree to protect all copyright and other ownership interests of Realsee 
+ * and/or its licensors in all items in the SDK supplied under this License 
+ * Agreement. You agree that all copies of the items in the SDK, reproduced for any 
+ * reason by You, contain the same copyright notices, and other proprietary notices 
+ * as appropriate, as appear on or in the original items delivered by Realsee in 
+ * the SDK. Realsee and/or its licensors retain title and ownership of the items in 
+ * the SDK, the media on which it is loaded, and all subsequent copies, regardless 
+ * of the form or media in or on which the original and other copies may exist. 
+ * Except as stated above, this Agreement does not grant You any rights to patents, 
+ * copyrights, trade secrets, trademarks or any other rights in respect to the 
+ * items in the SDK.
+ * 5. TERM AND TERMINATION.
+ * 5.1 This Agreement is effective until terminated. Realsee has the right to 
+ * terminate this Agreement immediately, without judicial intervention, if You fail 
+ * to comply with any term herein. Upon any such termination You must remove all 
+ * full and partial copies of the items in the SDK from Your computer and 
+ * discontinue the use of the items in the SDK.
+ * 5.2 Realsee may at any time, terminate the Agreement with You if: (A) You have 
+ * breached any provision of the Agreement; or (B) Realsee is required to do so by 
+ * law; or (C) Realsee decides to no longer provide the SDK or certain parts of the 
+ * SDK to users in the country in which You are resident or from which You use the 
+ * service, or the provision of the SDK or certain SDK services to You by Realsee 
+ * is, in Realsee's sole discretion, no longer legally or commercially viable.
+ * 5.3 When the Agreement comes to an end, all of the legal rights, obligations and 
+ * liabilities that You and Realsee have benefited from, been subject to (or which 
+ * have accrued over time whilst the Agreement has been in force) or which are 
+ * expressed to continue indefinitely, shall be unaffected by this cessation, and 
+ * the provisions of Section 3, 4, 6, 7 and 8 shall continue to apply to such 
+ * rights, obligations and liabilities indefinitely.
+ * 6. DISCLAIMER OF WARRANTY.
+ * YOU EXPRESSLY ACKNOWLEDGE AND AGREE THAT, TO THE EXTENT PERMITTED BY APPLICABLE 
+ * LAW, USE OF THE SDK (OR ANY PART THEREOF) IS AT YOUR SOLE RISK AND THAT THE 
+ * ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY, AND EFFORT IS 
+ * WITH YOU. REALSEE LICENSES THE SDK TO YOU ONLY ON AN "AS-IS" BASIS. REALSEE 
+ * MAKES NO REPRESENTATION WITH RESPECT TO THE ADEQUACY OF ANY ITEMS IN THE SDK, 
+ * WHETHER OR NOT USED BY YOU IN THE DEVELOPMENT OF INTEGRATED PRODUCT, FOR ANY 
+ * PARTICULAR PURPOSE OR WITH RESPECT TO THEIR ADEQUACY TO PRODUCE ANY PARTICULAR 
+ * RESULT. REALSEE AND ITS LICENSORS SHALL NOT BE LIABLE FOR LOSS OR DAMAGE ARISING 
+ * OUT OF THIS AGREEMENT OR FROM THE DISTRIBUTION OR USE OF INTEGRATED PRODUCT 
+ * CONTAINING PORTIONS OF THE SDK. REALSEE AND ITS LICENSORS DISCLAIM ALL 
+ * WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED 
+ * CONDITIONS OR WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
+ * OR NONINFRINGEMENT OF ANY THIRD PARTY RIGHT IN RESPECT OF THE ITEMS IN THE SDK 
+ * OR ANY SERVICES RELATED TO THE SDK.
+ * REALSEE IS UNDER NO OBLIGATION TO PROVIDE ANY SUPPORT UNDER THIS LICENSE 
+ * AGREEMENT, INCLUDING UPGRADES OR FUTURE VERSIONS OF THE SDK OR ANY PORTIONS 
+ * THEREOF, TO YOU, END USER OR TO ANY OTHER PARTY.
+ * 7. LIMITATION OF LIABILITY.
+ * TO THE EXTENT NOT PROHIBITED BY APPLICABLE LAW, IN NO EVENT WILL REALSEE OR ITS 
+ * LICENSORS BE LIABLE FOR ANY DIRECT, INCIDENTAL, SPECIAL, INDIRECT, OR 
+ * CONSEQUENTIAL DAMAGES, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF USE, 
+ * LOSS OF BUSINESS, REVENUE, OR PROFITS, LOSS OF OPPORTUNITY (WHETHER DIRECT OR 
+ * INDIRECT), CORRUPTION OR LOSS OF DATA, LOSS OF REPUTATION OR SAVINGS, DOWNTIME, 
+ * OR DAMAGE TO, LOSS OF OR REPLACEMENT OF DATA OR TRANSACTIONS, COST OF 
+ * PROCUREMENT OF SUBSTITUTE SERVICES, BUSINESS INTERRUPTION, OR ANY OTHER 
+ * COMMERCIAL DAMAGES OR LOSSES, ARISING OUT OF OR RELATED TO YOUR USE OR INABILITY 
+ * TO USE THE SDK (OR ANY PART THEREOF), ANY INTEGRATED PRODUCT, OR ANY THIRD PARTY 
+ * SOFTWARE, APPLICATIONS, OR SERVICES IN CONJUNCTION WITH THE SDK (OR ANY PART 
+ * THEREOF), HOWEVER CAUSED, REGARDLESS OF THE THEORY OF LIABILITY (CONTRACT, TORT, 
+ * OR OTHERWISE) AND EVEN IF REALSEE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH 
+ * DAMAGES. IN NO EVENT WILL REALSEE’S TOTAL LIABILITY TO YOU FOR ALL DAMAGES 
+ * EXCEED ONE HUNDRED DOLLARS ($100.00). THE FOREGOING LIMITATIONS WILL APPLY EVEN 
+ * IF THE ABOVE STATED REMEDY FAILS OF ITS ESSENTIAL PURPOSE. THE LIMITATIONS 
+ * CONTAINED IN SECTIONS 6 AND THIS SECTION 7 ARE A FUNDAMENTAL PART OF THE BASIS 
+ * OF REALSEE’S BARGAIN HEREUNDER, AND REALSEE WOULD NOT ENTER INTO THIS AGREEMENT 
+ * OR PROVIDE YOU WITH ACCESS TO THE SDK ABSENT SUCH LIMITATIONS.
+ * 8. INDEMNIFICATION.
+ * To the extent permitted by applicable law, You agree to indemnify, defend and 
+ * hold harmless Realsee, its affiliates and each of their directors, officers, 
+ * employees, independent contractors, and agents (each a “Realsee Indemnified 
+ * Party”) from any and all claims, losses, liabilities, damages, expenses, and 
+ * costs (including without limitation attorneys’ fees and court costs) incurred by 
+ * a Realsee Indemnified Party as a result of: (i) Your non-compliance with any 
+ * terms of this Agreement; (ii) Your use of the SDK (or any part thereof); or 
+ * (iii) Your use of any Integrated Product, including any claim that Integrated 
+ * Product infringes the copyright, trademark, trade secret or other intellectual 
+ * property right of a third party.
+ * 9. ACKNOWLEDGEMENTS.
+ * Portions of the SDK may utilize or include third party software and other 
+ * copyrighted material. Acknowledgments, licensing terms, and disclaimers for such 
+ * material are contained in Documentation for the SDK or may otherwise accompany 
+ * such material, and Your use of such materials governed by their respective 
+ * terms. In the event of conflict between the terms of this Agreement and an 
+ * applicable open source or third party agreement, the open source or third party 
+ * agreement will control solely with respect to the open source software or third 
+ * party software. Moreover, You shall not subject any items (including not limited 
+ * to source code, object code, and any software)  included in the SDK to any open 
+ * source license.
+ * 10. NON-BLOCKING OF REALSEE DEVELOPMENT.
+ * You acknowledge that Realsee is currently developing or may develop technologies 
+ * and products in the future that have or may have design and/or functionality 
+ * similar to Integrated Product that You may develop based on Your license herein. 
+ * Nothing in this Agreement shall impair, limit or curtail Realsee's right to 
+ * continue with its development, maintenance and/or distribution of Realsee's 
+ * technology or products.
+ * 11. GENERAL.
+ * 11.1 Export Control. You may not use or otherwise export or re-export the SDK 
+ * (or any part thereof) except as authorized by United States law and the laws of 
+ * the jurisdiction(s) in which the SDK (or any part thereof) was obtained. In 
+ * particular, but without limitation, the SDK may not be exported or re-exported 
+ * (i) into any U.S. embargoed countries or (ii) to anyone on the U.S. Treasury 
+ * Department's list of Specially Designated Nationals or the U.S. Department of 
+ * Commerce Denied Person's List or Entity List. By using the SDK (or any part 
+ * thereof), You represent and warrant that You are not located in any such country 
+ * or on any such list.
+ * 11.2 Governing Law. This Agreement and the rights of the parties hereunder shall 
+ * be governed by and construed in accordance with the laws of People’s Republic of 
+ * China (for purpose of this Agreement, excluding Hong Kong, Taiwan, and Macau), 
+ * without reference to its conflict of laws principles. Any dispute, controversy 
+ * or claim arising from or in connection with this Agreement, or the breach, 
+ * termination or invalidity thereof, shall be submitted to China International 
+ * Economic and Trade Arbitration Commission (“CIETAC”) for arbitration in Beijing 
+ * which shall be conducted in accordance with the CIETAC's arbitration rules in 
+ * effect at the time of applying for arbitration. The arbitral award is final and 
+ * binding upon both parties.
+ * 11.3 Severability. If any provision of this Agreement is held by a court of 
+ * competent jurisdiction to be unenforceable for any reason, the remaining 
+ * provisions hereof will be unaffected and remain in full force and effect.
+ * 11.4. Modifications. Realsee reserves the right, from time to time, with or 
+ * without notice to You, to make revisions to this Agreement in our sole and 
+ * absolute discretion.  The most current version of this Agreement will supersede 
+ * all previous versions and shall be made available on the website where the SDK 
+ * is made available, or by such other means as Realsee may determine in its 
+ * discretion. Any modified versions of this Agreement hereto shall take effect 
+ * from the time that it is made available. You shall be responsible for regularly 
+ * checking for notice of any such modifications. You agree that Your continued use 
+ * of the SDK constitutes Your agreement to the modified Agreement.
+ * 11.5 Relationship of the Parties. This Agreement will not be construed as 
+ * creating an agency, partnership, joint venture, fiduciary duty, or any other 
+ * form of legal association between You and Realsee, and You will not represent to 
+ * the contrary, whether expressly, by implication, appearance, or otherwise.
+ * 11.6 Entire Agreement; Governing Language. This Agreement constitutes the entire 
+ * agreement between You and Realsee with respect to the use of the SDK licensed 
+ * hereunder and supersedes all prior understandings regarding such subject matter. 
+ * No amendment to or modification of this Agreement will be binding unless in 
+ * writing and signed by Realsee. You and Realsee hereto confirm that this 
+ * Agreement and all related documents shall be drafted in English.
+*/function e(){return((1+Math.random())*65536|0).toString(16).substring(1)}function t(){return(e()+e()+`-`+e()+`-4`+e().substr(0,3)+`-`+e()+`-`+e()+e()+e()).toLowerCase()}export{t as uuid};

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