@realsee/five-webgpu 1.0.0-alpha.13 → 1.0.0-alpha.15

package/five/meshes/panoCircleMesh.d.ts

@@ -24,6 +24,7 @@ declare class PanoCircleMesh extends THREE.Object3D implements PanoCircleMeshInt
     private panoU;
     constructor(options?: PanoCircleMeshOptions);
     setProgress(progress: number): void;
+    setHDRBoost(boost: number): void;
     setOpacity(opacity: number): void;
     setCurrent(current: boolean): void;
     setLoading(loading: boolean): void;

package/five/meshes/panoCircleMeshCustom.d.ts

@@ -29,6 +29,7 @@ declare class PanoCircleMeshCustom extends THREE.Object3D implements PanoCircleM
     private panoU;
     constructor(options?: PanoCircleMeshCustomOptions);
     setProgress(progress: number): void;
+    setHDRBoost(boost: number): void;
     setOpacity(opacity: number): void;
     setCurrent(current: boolean): void;
     setLoading(loading: boolean): void;

package/five/meshes/panoCircleMeshSolid.d.ts

@@ -23,6 +23,7 @@ declare class PanoCircleMeshSolid extends THREE.Object3D implements PanoCircleMe
     private panoU;
     constructor(options?: PanoCircleMeshSolidOptions);
     setProgress(progress: number): void;
+    setHDRBoost(boost: number): void;
     setOpacity(opacity: number): void;
     setCurrent(current: boolean): void;
     setLoading(loading: boolean): void;

package/five/meshes/panoSphereMesh.d.ts

@@ -18,6 +18,7 @@ declare class PanoSphereMesh extends THREE.Object3D implements PanoCircleMeshInt
     disabled: boolean;
     constructor();
     setProgress(progress: number): void;
+    setHDRBoost(boost: number): void;
     setOpacity(opacity: number): void;
     setCurrent(current: boolean): void;
     setLoading(loading: boolean): void;

package/five/model/index.d.ts

@@ -14,12 +14,24 @@ export { PBMMeshPhongNodeMaterial, } from './materials/nodes/pbmMeshPhongNodeMat
 export { PBMMeshPhysicalNodeMaterial, } from './materials/nodes/pbmMeshPhysicalNodeMaterial';
 export { PBMMeshPanoOnlyNodeMaterial, } from './materials/nodes/pbmMeshPanoOnlyNodeMaterial';
 export { type LoadResultType } from "./loaders/shared";
-export { loadPbm } from "./loaders/pbm";
-export { loadAt3d } from "./loaders/at3d";
-export { loadDome } from "./loaders/dome";
-export { loadDomez } from "./loaders/domez";
-export { loadPly } from "./loaders/ply";
-export { loadGltf } from "./loaders/gltf";
+import type { loadPbm as LoadPbmFn } from "./loaders/pbm";
+import type { loadAt3d as LoadAt3dFn } from "./loaders/at3d";
+import type { loadDome as LoadDomeFn } from "./loaders/dome";
+import type { loadDomez as LoadDomezFn } from "./loaders/domez";
+import type { loadPly as LoadPlyFn } from "./loaders/ply";
+import type { loadGltf as LoadGltfFn } from "./loaders/gltf";
+/** 加载 PBM 格式模型（懒加载版本，实际实现见 `./loaders/pbm` 中的 `loadPbm`）。 */
+export declare const loadPbm: typeof LoadPbmFn;
+/** 加载 AT3D 格式模型（懒加载版本，实际实现见 `./loaders/at3d` 中的 `loadAt3d`）。 */
+export declare const loadAt3d: typeof LoadAt3dFn;
+/** 加载 Dome 格式全景模型（懒加载版本，实际实现见 `./loaders/dome` 中的 `loadDome`）。 */
+export declare const loadDome: typeof LoadDomeFn;
+/** 加载 Domez 格式全景模型（懒加载版本，实际实现见 `./loaders/domez` 中的 `loadDomez`）。 */
+export declare const loadDomez: typeof LoadDomezFn;
+/** 加载 PLY 格式模型（懒加载版本，实际实现见 `./loaders/ply` 中的 `loadPly`）。 */
+export declare const loadPly: typeof LoadPlyFn;
+/** 加载 glTF/GLB 格式模型（懒加载版本，实际实现见 `./loaders/gltf` 中的 `loadGltf`）。 */
+export declare const loadGltf: typeof LoadGltfFn;
 export { type TilesetHeader, type TileHeader, type TrajectoryHeader } from './tile3d/header';
 export { Tile, type TileContentData } from './tile3d/tile';
 export { TileNode } from './tile3d/tile-node';

package/five/model/loaders/glTF-helpers/extensions/KHR_gaussian_splatting_compression_spz.d.ts

@@ -1,7 +1,7 @@
 import * as THREE from 'three/webgpu';
 import { BaseExtension } from './base';
 import type { Parser } from '../parser';
-import { PBMGaussianSplattingObject } from '../../../objects/pbmGaussianSplattingObject';
+import type { PBMGaussianSplattingObject } from '../../../objects/pbmGaussianSplattingObject';
 export declare const EXTENSION_NAME = "KHR_gaussian_splatting_compression_spz";
 export declare class KHR_gaussian_splatting_compression_spz extends BaseExtension {
     load(gaussianSplattingExtension: {

package/five/model/loaders/glTF-helpers/extensions/KHR_gaussian_splatting_compression_spz_2.d.ts

@@ -1,7 +1,7 @@
 import * as THREE from 'three/webgpu';
 import { BaseExtension } from './base';
 import type { Parser } from '../parser';
-import { PBMGaussianSplattingObject } from '../../../objects/pbmGaussianSplattingObject';
+import type { PBMGaussianSplattingObject } from '../../../objects/pbmGaussianSplattingObject';
 export interface GaussianSplattingExtensionSpz2 {
     bufferView: number;
 }

package/five/model/loaders/spz.d.ts

@@ -1,5 +1,4 @@
 import { Fetcher } from "../../utils/ajax";
-import { PBMGaussianSplattingObject } from '../objects/pbmGaussianSplattingObject';
 import { LoadResultType } from './shared';
 import type { DecodeKind } from '../../gaussian-splatting/worker/decodeWorker';
 export { detectPlyKind } from '../../gaussian-splatting/worker/decodeWorker';
@@ -14,7 +13,7 @@ export declare function decodeInWorker<T>(kind: DecodeKind, bytes: Uint8Array, t
  * 解析 spz 格式数据为 `PBMGaussianSplattingObject`。
  * 解码 + WASM pack 全部在共享解码 Worker 内完成，主线程不阻塞。
  */
-export declare function parseSpz(fileBytes: Uint8Array | ArrayBuffer): Promise<PBMGaussianSplattingObject>;
+export declare function parseSpz(fileBytes: Uint8Array | ArrayBuffer): Promise<any>;
 export declare function loadSpz(url: string, options?: {
     modelUpAxis?: 'Y' | 'Z';
     upAxis?: 'Y' | 'Z';

package/five/model/loaders/spz.worker.d.ts

@@ -0,0 +1,37 @@
+/**
+ * SPZ 纯解码的输出：仅包含原始属性数组（无 THREE / DOM 依赖），
+ * 因此可在 Worker 中安全运行。`packedData` 为 Worker 内 WASM pack 后回填。
+ */
+export interface DecodedSpz {
+    numPoints: number;
+    shDegree: number;
+    positions: Float32Array;
+    colors: Uint8Array;
+    scales: Float32Array;
+    rotations: Float32Array;
+    sh1?: Float32Array;
+    sh2?: Float32Array;
+    sh3?: Float32Array;
+    /** Worker 内 WASM pack 好的 8 uint32/splat GPU 数据。 */
+    packedData?: Uint32Array;
+}
+/**
+ * 纯解码函数：把 SPZ 字节流（gzip）解码为原始属性数组。
+ *
+ * - 不触碰主线程 / DOM，仅使用 `DecompressionStream`、`DataView`、TypedArray，
+ *   因此可在 Worker 内直接运行。
+ * - 保留 magic / version 校验（非法魔数或不支持的版本会 reject）。
+ * - 数据不足（读越界）时由 `GunzipReader` 抛出 `Unexpected EOF` 而 reject。
+ */
+export declare function decodeSpz(fileBytes: Uint8Array | ArrayBuffer): Promise<DecodedSpz>;
+/** SPZ_Decode_Worker 的解码请求。 */
+export interface SpzDecodeRequest {
+    requestId: number;
+    fileBytes: ArrayBuffer;
+}
+/** SPZ_Decode_Worker 的解码响应（成功回传 decoded，失败回传 error）。 */
+export interface SpzDecodeResponse {
+    requestId: number;
+    decoded?: DecodedSpz;
+    error?: string;
+}

package/five/renderer/five-renderer.d.ts

@@ -23,7 +23,7 @@ export declare class FiveRenderer {
     /** 只存值与标记，不触碰 GPU，WebGL 后端下同样可安全读写 */
     private readonly transparencySettings;
     /**
-     * 计算着色器点云的半透明处理方式：'blend' | 'opaque'，默认 'opaque'。
+     * 计算着色器点云的半透明处理方式：'blend' | 'opaque'，默认 'blend'。
      * 非法值保持原值并输出警告；值改变时置 needsRender。
      */
     get pointCloudTransparencyMode(): PointCloudTransparencyMode;

package/five/renderer/index.d.ts

@@ -1,3 +1,3 @@
 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';
+export { FiveRenderer, type PointCloudTransparencyMode } from './five-renderer';

package/five/renderer/postprocessing/passes/pass.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/10/30
- * Version: 1.0.0-alpha.13
+ * Generated: 2026/11/4
+ * Version: 1.0.0-alpha.15
  * License:
  * Realsee SDK License Agreement
 
@@ -335,4 +335,4 @@
  * writing and signed by Realsee. You and Realsee hereto confirm that this 
  * Agreement and all related documents shall be drafted in English.
 
-*/const e=require("../../tools/full-screen-quad.js");var t=class{constructor(e){this.enabled=!0,this.needsSwap=!0,this.clear=!1,this.renderToScreen=!0,this.dependencies=e==null?[]:e}setSize(e,t){}render(e,t,n,r,i){}dispose(){}};t.FullScreenQuad=e.FullScreenQuad,exports.FivePass=t;
+*/const require_full_screen_quad=require("../../tools/full-screen-quad.js");var FivePass=class{constructor(dependencies){this.enabled=!0,this.needsSwap=!0,this.clear=!1,this.renderToScreen=!0,this.dependencies=dependencies==null?[]:dependencies}setSize(width,height){}render(renderer,writeBuffer,readBuffer,deltaTime,maskActive){}dispose(){}};FivePass.FullScreenQuad=require_full_screen_quad.FullScreenQuad,exports.FivePass=FivePass;

package/five/renderer/postprocessing/passes/pass.mjs

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/10/30
- * Version: 1.0.0-alpha.13
+ * Generated: 2026/11/4
+ * Version: 1.0.0-alpha.15
  * License:
  * Realsee SDK License Agreement
 
@@ -335,4 +335,4 @@
  * writing and signed by Realsee. You and Realsee hereto confirm that this 
  * Agreement and all related documents shall be drafted in English.
 
-*/import{FullScreenQuad as e}from"../../tools/full-screen-quad.mjs";var t=class{constructor(e){this.enabled=!0,this.needsSwap=!0,this.clear=!1,this.renderToScreen=!0,this.dependencies=e==null?[]:e}setSize(e,t){}render(e,t,n,r,i){}dispose(){}};t.FullScreenQuad=e;export{t as FivePass};
+*/import{FullScreenQuad}from"../../tools/full-screen-quad.mjs";var FivePass=class{constructor(dependencies){this.enabled=!0,this.needsSwap=!0,this.clear=!1,this.renderToScreen=!0,this.dependencies=dependencies==null?[]:dependencies}setSize(width,height){}render(renderer,writeBuffer,readBuffer,deltaTime,maskActive){}dispose(){}};FivePass.FullScreenQuad=FullScreenQuad;export{FivePass};

package/five/renderer/tools/full-screen-quad.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/10/30
- * Version: 1.0.0-alpha.13
+ * Generated: 2026/11/4
+ * Version: 1.0.0-alpha.15
  * License:
  * Realsee SDK License Agreement
 
@@ -335,4 +335,4 @@
  * writing and signed by Realsee. You and Realsee hereto confirm that this 
  * Agreement and all related documents shall be drafted in English.
 
-*/const e=require("../../../_virtual/_rolldown/runtime.js");let t=require("three/webgpu");t=e.__toESM(t,1);var n=class e{constructor(n){this._scene=new t.Scene,this._mesh=new t.Mesh(e.geometry,n),this._mesh.frustumCulled=!1,this._scene.add(this._mesh)}get material(){return this._mesh.material}set material(e){this._mesh.material=e}dispose(){this._mesh.geometry.dispose()}render(t){t.render(this._scene,e.camera)}};n.camera=new t.OrthographicCamera(-1,1,1,-1,0,1),n.geometry=(()=>{let e=new t.PlaneGeometry(2,2,1,1);for(let t=1;t<e.attributes.uv.array.length;t+=2)e.attributes.uv.array[t]=1-e.attributes.uv.array[t];return e})(),exports.FullScreenQuad=n;
+*/const require_runtime=require("../../../_virtual/_rolldown/runtime.js");let three_webgpu=require("three/webgpu");three_webgpu=require_runtime.__toESM(three_webgpu,1);var FullScreenQuad=class FullScreenQuad{constructor(material){this._scene=new three_webgpu.Scene,this._mesh=new three_webgpu.Mesh(FullScreenQuad.geometry,material),this._mesh.frustumCulled=!1,this._scene.add(this._mesh)}get material(){return this._mesh.material}set material(value){this._mesh.material=value}dispose(){this._mesh.geometry.dispose()}render(renderer){renderer.render(this._scene,FullScreenQuad.camera)}};FullScreenQuad.camera=new three_webgpu.OrthographicCamera(-1,1,1,-1,0,1),FullScreenQuad.geometry=(()=>{let ge=new three_webgpu.PlaneGeometry(2,2,1,1);for(let i=1;i<ge.attributes.uv.array.length;i+=2)ge.attributes.uv.array[i]=1-ge.attributes.uv.array[i];return ge})(),exports.FullScreenQuad=FullScreenQuad;

package/five/renderer/tools/full-screen-quad.mjs

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/10/30
- * Version: 1.0.0-alpha.13
+ * Generated: 2026/11/4
+ * Version: 1.0.0-alpha.15
  * License:
  * Realsee SDK License Agreement
 
@@ -335,4 +335,4 @@
  * writing and signed by Realsee. You and Realsee hereto confirm that this 
  * Agreement and all related documents shall be drafted in English.
 
-*/import*as e from"three/webgpu";var t=class t{constructor(n){this._scene=new e.Scene,this._mesh=new e.Mesh(t.geometry,n),this._mesh.frustumCulled=!1,this._scene.add(this._mesh)}get material(){return this._mesh.material}set material(e){this._mesh.material=e}dispose(){this._mesh.geometry.dispose()}render(e){e.render(this._scene,t.camera)}};t.camera=new e.OrthographicCamera(-1,1,1,-1,0,1),t.geometry=(()=>{let t=new e.PlaneGeometry(2,2,1,1);for(let e=1;e<t.attributes.uv.array.length;e+=2)t.attributes.uv.array[e]=1-t.attributes.uv.array[e];return t})();export{t as FullScreenQuad};
+*/import*as THREE from"three/webgpu";var FullScreenQuad=class FullScreenQuad{constructor(material){this._scene=new THREE.Scene,this._mesh=new THREE.Mesh(FullScreenQuad.geometry,material),this._mesh.frustumCulled=!1,this._scene.add(this._mesh)}get material(){return this._mesh.material}set material(value){this._mesh.material=value}dispose(){this._mesh.geometry.dispose()}render(renderer){renderer.render(this._scene,FullScreenQuad.camera)}};FullScreenQuad.camera=new THREE.OrthographicCamera(-1,1,1,-1,0,1),FullScreenQuad.geometry=(()=>{let ge=new THREE.PlaneGeometry(2,2,1,1);for(let i=1;i<ge.attributes.uv.array.length;i+=2)ge.attributes.uv.array[i]=1-ge.attributes.uv.array[i];return ge})();export{FullScreenQuad};

package/five/texture/initTexture.d.ts

@@ -1,3 +1,11 @@
 import * as THREE from "three/webgpu";
+/**
+ * 提前把纹理上传到 GPU。
+ *
+ * three 的 `renderer.initTexture()` 要求 backend 已初始化，否则会抛错。
+ * 模型/瓦片加载流程可能早于 renderer 就绪，因此这里在未就绪时先等待：
+ * - InternalWebGPURenderer：等待 `ready`（含 init 之后安装的 WebGL 补丁）；
+ * - 其他 WebGPURenderer：回退到 `init()`（重复调用返回同一个缓存 Promise）。
+ */
 export declare function initTexture<T extends THREE.Texture>(texture: T, renderer: THREE.WebGPURenderer): Promise<T>;
 export declare function initTextures<T extends THREE.Texture[]>(textures: T, renderer: THREE.WebGPURenderer): Promise<T>;

package/five/texture/videoTextureBridge.d.ts

@@ -1,43 +1,152 @@
 import * as THREE from "three/webgpu";
+/**
+ * 视频纹理桥（WebGPU / WebGL 后端通用）。
+ *
+ * ## 为什么需要
+ *
+ * 把 `<video>` 直接交给 three 的 `VideoTexture` 上传，在部分「浏览器 × 后端」组合下得到的是黑色：
+ *
+ * - Safari 18（WebGPU）：`copyExternalImageToTexture(video)` 校验失败，纹理没有被写入；
+ * - 小米浏览器（WebGL，Chromium 内核）：`texImage2D(video)`、`drawImage(video)`、`createImageBitmap(video)`
+ *   全部读到黑色，只有 `new VideoFrame(video)` 能拿到画面。
+ *
+ * 没有任何一条上传路径在所有环境里都可靠，所以这里不按 UA 猜，而是**运行时探测**：
+ * 按优先级依次用小尺寸采样验证每条候选路径「真的有画面」，选第一条有画面的并锁定。
+ *
+ * ## 候选路径（按优先级）
+ *
+ * | 候选                   | 取帧                           | WebGPU 后端                    | WebGL 后端                |
+ * | ---------------------- | ------------------------------ | ------------------------------ | ------------------------- |
+ * | `videoFrame`           | `new VideoFrame(video)`        | importExternalTexture + blit   | texImage2D(VideoFrame)    |
+ * | `video`                | `<video>` 元素本身             | importExternalTexture + blit   | texImage2D(video)         |
+ * | `canvasFromVideoFrame` | VideoFrame → canvas2d.drawImage | three 上传 canvas              | three 上传 canvas         |
+ * | `canvasFromVideo`      | video → canvas2d.drawImage     | three 上传 canvas              | three 上传 canvas         |
+ *
+ * WebGPU 后端下前两条是「external texture → 全屏三角形 render pass → 自持中间纹理」，全程在 GPU 上，
+ * 没有 CPU 读写。后两条经过 canvas2d（有一定性能损耗），是前两条都不可用时的兜底。
+ *
+ * ## 探测与锁定
+ *
+ * - 探测只读一块 16x16（WebGL / canvas）或 64x16（WebGPU）的小采样，取各通道最大值，
+ *   `>= BRIGHT_THRESHOLD` 视为有画面；
+ * - 探测通过的第一条候选被锁定，之后不再探测；
+ * - 全部候选都是黑（视频本身可能就是黑场）时保持默认候选，退避重试，直到出现有画面的候选；
+ * - 视频 `src` 变化（`loadstart`）时解除锁定并重新探测；
+ * - 当前候选连续多帧抛错时，拉黑它并换下一条。
+ *
+ * ## 调用约定
+ *
+ * 由使用方在 `Object3D.onBeforeRender` 中调用 {@link VideoTextureBridge.update}，
+ * 然后把 {@link VideoTextureBridge.texture} 赋给材质。`onBeforeRender` 早于该对象的
+ * 节点构建与绑定更新，所以本帧绑定的一定是更新后的纹理。
+ */
+type CandidateId = 'videoFrame' | 'video' | 'canvasFromVideoFrame' | 'canvasFromVideo';
 declare class VideoTextureBridge {
-    /** 原始视频纹理：WebGL 后端或中转不可用时直接使用 */
+    /** 原始视频纹理：所有候选都不可用（或桥无法识别后端）时原样使用 */
     readonly videoTexture: THREE.VideoTexture;
+    /**
+     * 诊断信息（只读，供排查用）。
+     * - `path`：`pending` 未见过 renderer / `webgpu` / `webgl` / `fallback` 全部候选失败、退回原 VideoTexture
+     * - `candidate`：当前候选；`locked`：是否已探测通过并锁定
+     * - `probe`：最近一次探测结果，如 `vf:210 video:0`（数字为采样最大值，`n/a` 不可用，`-1` 失败）
+     * - `updateCalls` update 调用次数（为 0 说明 onBeforeRender 没触发，即对象没被渲染）；
+     *   `skipNotReady` 因视频未就绪跳过的次数；`blitCount` 实际产出帧数；`rvfcCount` rVFC 回调次数；`fails` 产出失败次数
+     */
+    readonly debug: {
+        path: "pending" | "webgpu" | "webgl" | "fallback";
+        candidate: string;
+        locked: boolean;
+        probe: string;
+        updateCalls: number;
+        skipNotReady: number;
+        blitCount: number;
+        rvfcCount: number;
+        fails: number;
+        targetSize: string;
+        lastError: string;
+    };
+    private mode;
     private device;
-    /** 当前后端是否走 GPU 中转；`null` 表示还没见过 renderer */
-    private useBlit;
-    /** 中转失败（例如 importExternalTexture 抛错）后永久回退 */
+    /** 所有候选都不可用后置位，永久退回原 VideoTexture */
     private broken;
+    private disposed;
+    private current;
+    private locked;
+    /** 被拉黑的候选及其解除时间（performance.now() 时间戳）；到期后会重新参与探测 */
+    private readonly blacklist;
+    private probing;
+    private nextProbeAt;
+    private probeInterval;
+    private consecutiveFails;
+    /** 本轮连续失败的起点时间 */
+    private failingSince;
+    /** three 上传的输出纹理：image 在 VideoFrame / video / canvas 之间切换 */
+    private frameTexture;
+    private frameReady;
+    /** 挂在 frameTexture 上、需要在被替换时关闭的 VideoFrame */
+    private heldFrame;
+    private canvas;
+    private canvasContext;
+    /** WebGPU 的 blit 中间纹理及其 three 包装 */
     private gpuTexture;
     private externalTexture;
+    private externalReady;
     private width;
     private height;
-    /** 是否有未中转的新帧 */
     private frameDirty;
-    /** 上一次中转时的 currentTime，配合 frameDirty 判断是否有新帧 */
     private lastVideoTime;
     private videoFrameCallbackId;
-    private disposed;
+    private glProbe;
+    private glProbeFailed;
+    private gpuProbe;
+    private probeCanvas;
+    /** 被 {@link forceCandidate} 强制指定后，不再自动探测 / 换源重探 */
+    private forced;
+    private readonly onSourceChange;
     constructor(videoTexture: THREE.VideoTexture);
     private get video();
     private scheduleVideoFrameCallback;
     /**
      * 当前应被材质采样的纹理。
-     * - WebGL 后端 / 中转不可用 / 尚未见过 renderer：原 `VideoTexture`；
-     * - WebGPU 后端：中转纹理，首帧中转完成前为 1x1 黑色占位。
+     * 输出尚未就绪时返回 1x1 黑色占位（不会触发有问题的上传路径）；识别不了后端或全部失败时返回原 `VideoTexture`。
      */
     get texture(): THREE.Texture;
     /**
-     * 有新视频帧时执行一次 GPU 中转。应在 `onBeforeRender` 中调用，同一帧多次调用只会中转一次。
+     * 有新视频帧时产出一次。应在 `onBeforeRender` 中调用，同一帧多次调用只会产出一次。
      */
     update(renderer: unknown): void;
-    private ensureTarget;
+    /**
+     * 强制使用某条候选路径（仅用于诊断 / 测试），传 `null` 恢复自动探测。
+     * 强制期间不探测、换视频也不重探；候选连续失败时仍会被拉黑并换下一条。
+     */
+    forceCandidate(candidate: CandidateId | null): void;
+    private resolveMode;
+    private ensureFrameTexture;
+    private produce;
+    /** 把图像源交给 frameTexture，并关闭被替换掉的 VideoFrame */
+    private setFrame;
+    private drawCanvas;
+    private isBlacklisted;
+    private onProduceFailed;
     private blit;
-    private releaseTarget;
+    private ensureTarget;
+    private startProbe;
+    private runProbe;
+    private select;
+    private probeCandidate;
+    /** canvas2d 探测：把视频缩到 16x16 再读回 */
+    private probe2d;
+    /** WebGL 探测：用独立的小 WebGL2 上下文做 texImage2D → 绘制 → readPixels，行为与 three 的 WebGL 后端一致 */
+    private probeGL;
+    /** WebGPU 探测：external texture → 64x16 小目标 → 回读（异步） */
+    private probeGPU;
+    private releaseProbeResources;
+    private releaseOutputs;
     dispose(): void;
 }
 /**
- * 取得某个 `VideoTexture` 对应的中转器（同一个 `VideoTexture` 共用一个）。
- * `VideoTexture` 被 dispose 时中转器一并释放，之后再取会新建。
+ * 取得某个 `VideoTexture` 对应的桥（同一个 `VideoTexture` 共用一个）。
+ * `VideoTexture` 被 dispose 时桥一并释放，之后再取会新建。
  */
 declare function getVideoTextureBridge(videoTexture: THREE.VideoTexture): VideoTextureBridge;
-export { VideoTextureBridge, getVideoTextureBridge };
+export { VideoTextureBridge, getVideoTextureBridge, type CandidateId };

package/five/thirdparty/sha256.d.ts

@@ -0,0 +1,149 @@
+type Message = string | number[] | ArrayBuffer | Uint8Array;
+
+interface Hasher {
+  /**
+   * Update hash
+   *
+   * @param message The message you want to hash.
+   */
+  update(message: Message): Hasher;
+
+  /**
+   * Return hash in hex string.
+   */
+  hex(): string;
+
+  /**
+   * Return hash in hex string.
+   */
+  toString(): string;
+
+  /**
+   * Return hash in ArrayBuffer.
+   */
+  arrayBuffer(): ArrayBuffer;
+
+  /**
+   * Return hash in integer array.
+   */
+  digest(): number[];
+
+  /**
+   * Return hash in integer array.
+   */
+  array(): number[];
+}
+
+interface Hmac {
+  /**
+   * Computes a Hash-based message authentication code (HMAC) using a secret key
+   *
+   * @param secretKey The Secret Key
+   * @param message The message you want to hash.
+   */
+  (secretKey: Message, message: Message): string;
+
+  /**
+   * Create a hash object using a secret key.
+   *
+   * @param secretKey The Secret Key
+   */
+  create(secretKey: Message): Hasher;
+
+  /**
+   * Create a hash object and hash message using a secret key
+   *
+   * @param secretKey The Secret Key
+   * @param message The message you want to hash.
+   */
+  update(secretKey: Message, message: Message): Hasher;
+
+  /**
+   * Return hash in hex string.
+   *
+   * @param secretKey The Secret Key
+   * @param message The message you want to hash.
+   */
+  hex(secretKey: Message, message: Message): string;
+
+  /**
+   * Return hash in ArrayBuffer.
+   *
+   * @param secretKey The Secret Key
+   * @param message The message you want to hash.
+   */
+  arrayBuffer(secretKey: Message, message: Message): ArrayBuffer;
+
+  /**
+   * Return hash in integer array.
+   *
+   * @param secretKey The Secret Key
+   * @param message The message you want to hash.
+   */
+  digest(secretKey: Message, message: Message): number[];
+
+  /**
+   * Return hash in integer array.
+   *
+   * @param secretKey The Secret Key
+   * @param message The message you want to hash.
+   */
+  array(secretKey: Message, message: Message): number[];
+}
+
+interface Hash {
+  /**
+   * Hash and return hex string.
+   *
+   * @param message The message you want to hash.
+   */
+  (message: Message): string;
+
+  /**
+   * Create a hash object.
+   */
+  create(): Hasher;
+
+  /**
+   * Create a hash object and hash message.
+   *
+   * @param message The message you want to hash.
+   */
+  update(message: Message): Hasher;
+
+  /**
+   * Return hash in hex string.
+   *
+   * @param message The message you want to hash.
+   */
+  hex(message: Message): string;
+
+  /**
+   * Return hash in ArrayBuffer.
+   *
+   * @param message The message you want to hash.
+   */
+  arrayBuffer(message: Message): ArrayBuffer;
+
+  /**
+   * Return hash in integer array.
+   *
+   * @param message The message you want to hash.
+   */
+  digest(message: Message): number[];
+
+  /**
+   * Return hash in integer array.
+   *
+   * @param message The message you want to hash.
+   */
+  array(message: Message): number[];
+
+  /**
+   * HMAC interface
+   */
+  hmac: Hmac;
+}
+
+export var sha256: Hash;
+export var sha224: Hash;

package/five/types/panoCircleMeshInterface.d.ts

@@ -26,6 +26,12 @@ interface PanoCircleMeshInterface extends THREE.Object3D {
     setProgress(progress: number): void;
     opacity: number;
     setOpacity(opacity: number): void;
+    /**
+     * 设置 HDR 提亮倍数（可选实现）
+     * @description 由控制器每帧同步：开启 HDR 时为 `parameter.maxDisplayBoost`，否则为 1。
+     * 实现方应将该倍数乘到输出 rgb 上（不影响 alpha）。
+     */
+    setHDRBoost?(boost: number): void;
     updateTime?(time: number, deltaTime: number): void;
     /** 点击交互 */
     tap?(): Promise<void>;

package/five/utils/calculateThreeMouse.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/10/30
- * Version: 1.0.0-alpha.13
+ * Generated: 2026/11/4
+ * Version: 1.0.0-alpha.15
  * License:
  * Realsee SDK License Agreement
 
@@ -335,4 +335,4 @@
  * writing and signed by Realsee. You and Realsee hereto confirm that this 
  * Agreement and all related documents shall be drafted in English.
 
-*/const e=require("../../_virtual/_rolldown/runtime.js");let t=require("three/webgpu");t=e.__toESM(t,1);function n(e,n,r){let{top:i,left:a,width:o,height:s}=n.getBoundingClientRect();return r&&(a+=o*r.left,i+=s*(1-r.bottom-r.height),o*=r.width,s*=r.height),new t.Vector2((e.x-a)/o*2-1,-(e.y-i)/s*2+1)}exports.calculateThreeMouse=n;
+*/const require_runtime=require("../../_virtual/_rolldown/runtime.js");let three_webgpu=require("three/webgpu");three_webgpu=require_runtime.__toESM(three_webgpu,1);function calculateThreeMouse(mouseXY,element,viewport){let{top,left,width,height}=element.getBoundingClientRect();return viewport&&(left+=width*viewport.left,top+=height*(1-viewport.bottom-viewport.height),width*=viewport.width,height*=viewport.height),new three_webgpu.Vector2((mouseXY.x-left)/width*2-1,-(mouseXY.y-top)/height*2+1)}exports.calculateThreeMouse=calculateThreeMouse;

package/five/utils/calculateThreeMouse.mjs

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/10/30
- * Version: 1.0.0-alpha.13
+ * Generated: 2026/11/4
+ * Version: 1.0.0-alpha.15
  * License:
  * Realsee SDK License Agreement
 
@@ -335,4 +335,4 @@
  * writing and signed by Realsee. You and Realsee hereto confirm that this 
  * Agreement and all related documents shall be drafted in English.
 
-*/import*as e from"three/webgpu";function t(t,n,r){let{top:i,left:a,width:o,height:s}=n.getBoundingClientRect();return r&&(a+=o*r.left,i+=s*(1-r.bottom-r.height),o*=r.width,s*=r.height),new e.Vector2((t.x-a)/o*2-1,-(t.y-i)/s*2+1)}export{t as calculateThreeMouse};
+*/import*as THREE from"three/webgpu";function calculateThreeMouse(mouseXY,element,viewport){let{top,left,width,height}=element.getBoundingClientRect();return viewport&&(left+=width*viewport.left,top+=height*(1-viewport.bottom-viewport.height),width*=viewport.width,height*=viewport.height),new THREE.Vector2((mouseXY.x-left)/width*2-1,-(mouseXY.y-top)/height*2+1)}export{calculateThreeMouse};

package/five/utils/distance.js

@@ -1,8 +1,8 @@
 /**
  * @license
  * @realsee/five-webgpu
- * Generated: 2026/10/30
- * Version: 1.0.0-alpha.13
+ * Generated: 2026/11/4
+ * Version: 1.0.0-alpha.15
  * License:
  * Realsee SDK License Agreement
 
@@ -335,4 +335,4 @@
  * writing and signed by Realsee. You and Realsee hereto confirm that this 
  * Agreement and all related documents shall be drafted in English.
 
-*/function e(e,t){return Math.sqrt(Math.pow(e.x-t.x,2)+Math.pow(e.y-t.y,2)+(`z`in e?Math.pow(e.z-t.z,2):0))}exports.distance=e;
+*/function distance(p0,p1){return Math.sqrt(Math.pow(p0.x-p1.x,2)+Math.pow(p0.y-p1.y,2)+(`z`in p0?Math.pow(p0.z-p1.z,2):0))}exports.distance=distance;