three-base 2.0.142 → 2.0.166

package/MktMesh/panoBitmapTexture.d.ts

@@ -1,25 +1,25 @@
-import { Texture } from "three";
-/**
- * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
- *
- * 为什么要换掉 three 的 `TextureLoader`：它只等 `img.onload`（字节到手），**从不解码** —— 解码是懒的，
- * 真正碰像素的是上传那一拍的 `texImage2D(<img>)`，于是整段 JPEG 解码被拽到主线程上同步做完。
- * 实测（2026-10-05，皇上线上的种子全景 11904×5952 / 解码后 270MB）：
- *   `texImage2D(未解码的 <img>)` = **1266ms 全在主线程**；
- *   `createImageBitmap` 解码 = **768ms 在工作线程**（同期主线程跑完 40 个宏任务只花 6ms），
- *   解完再 `texImage2D(<ImageBitmap>)` = **366ms**（这 366 是 270MB 像素搬运，跟解码无关，只有降尺寸才能压掉）。
- * ⚠️ 试过 `await img.decode()` 这条路：同一张图 **90 秒没回**（超大图的异步解码在 Chrome 上不可靠）⇒ 别再走它。
- *
- * ⚠️ **上下翻这颗雷（实测，别照抄直觉）**：Chrome 对 `ImageBitmap` 源**忽略** `UNPACK_FLIP_Y_WEBGL`
- * （`<img>` / canvas 源认，bitmap 源不认）⇒ 直接把 `<img>` 换成 bitmap 会让全景**上下颠倒**。
- * 解法 = 建图时 `imageOrientation: "flipY"` 把翻转烘进位图，同时把 `texture.flipY = false`
- * 明说「已经翻过了」。1×2 像素对照实测：`<img>`+flipY=true 与 bitmap(flipY)+flipY=false 逐行一致。
- */
-/** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
- *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
- *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
-export declare function loadPanoTexture(url: string): Promise<Texture>;
-/** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**
- *  （不像 `<img>` 能等 GC —— 一张 270MB 的位图挂着不关，切几轮全景就把进程吃爆）。
- *  只在「这张纹理确实被丢掉」的清理路径上调用：关掉的位图再也传不上去，WebGL 上下文丢失后的重建会拿到空图。 */
-export declare function releasePanoTexture(tex: Texture | null | undefined): void;
+import { Texture } from "three";
+/**
+ * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
+ *
+ * 为什么要换掉 three 的 `TextureLoader`：它只等 `img.onload`（字节到手），**从不解码** —— 解码是懒的，
+ * 真正碰像素的是上传那一拍的 `texImage2D(<img>)`，于是整段 JPEG 解码被拽到主线程上同步做完。
+ * 实测（2026-10-05，皇上线上的种子全景 11904×5952 / 解码后 270MB）：
+ *   `texImage2D(未解码的 <img>)` = **1266ms 全在主线程**；
+ *   `createImageBitmap` 解码 = **768ms 在工作线程**（同期主线程跑完 40 个宏任务只花 6ms），
+ *   解完再 `texImage2D(<ImageBitmap>)` = **366ms**（这 366 是 270MB 像素搬运，跟解码无关，只有降尺寸才能压掉）。
+ * ⚠️ 试过 `await img.decode()` 这条路：同一张图 **90 秒没回**（超大图的异步解码在 Chrome 上不可靠）⇒ 别再走它。
+ *
+ * ⚠️ **上下翻这颗雷（实测，别照抄直觉）**：Chrome 对 `ImageBitmap` 源**忽略** `UNPACK_FLIP_Y_WEBGL`
+ * （`<img>` / canvas 源认，bitmap 源不认）⇒ 直接把 `<img>` 换成 bitmap 会让全景**上下颠倒**。
+ * 解法 = 建图时 `imageOrientation: "flipY"` 把翻转烘进位图，同时把 `texture.flipY = false`
+ * 明说「已经翻过了」。1×2 像素对照实测：`<img>`+flipY=true 与 bitmap(flipY)+flipY=false 逐行一致。
+ */
+/** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
+ *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
+ *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
+export declare function loadPanoTexture(url: string): Promise<Texture>;
+/** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**
+ *  （不像 `<img>` 能等 GC —— 一张 270MB 的位图挂着不关，切几轮全景就把进程吃爆）。
+ *  只在「这张纹理确实被丢掉」的清理路径上调用：关掉的位图再也传不上去，WebGL 上下文丢失后的重建会拿到空图。 */
+export declare function releasePanoTexture(tex: Texture | null | undefined): void;

package/MktMesh/panoBitmapTexture.js

@@ -1,52 +1,52 @@
-import { Texture } from "three";
-/**
- * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
- *
- * 为什么要换掉 three 的 `TextureLoader`：它只等 `img.onload`（字节到手），**从不解码** —— 解码是懒的，
- * 真正碰像素的是上传那一拍的 `texImage2D(<img>)`，于是整段 JPEG 解码被拽到主线程上同步做完。
- * 实测（2026-10-05，皇上线上的种子全景 11904×5952 / 解码后 270MB）：
- *   `texImage2D(未解码的 <img>)` = **1266ms 全在主线程**；
- *   `createImageBitmap` 解码 = **768ms 在工作线程**（同期主线程跑完 40 个宏任务只花 6ms），
- *   解完再 `texImage2D(<ImageBitmap>)` = **366ms**（这 366 是 270MB 像素搬运，跟解码无关，只有降尺寸才能压掉）。
- * ⚠️ 试过 `await img.decode()` 这条路：同一张图 **90 秒没回**（超大图的异步解码在 Chrome 上不可靠）⇒ 别再走它。
- *
- * ⚠️ **上下翻这颗雷（实测，别照抄直觉）**：Chrome 对 `ImageBitmap` 源**忽略** `UNPACK_FLIP_Y_WEBGL`
- * （`<img>` / canvas 源认，bitmap 源不认）⇒ 直接把 `<img>` 换成 bitmap 会让全景**上下颠倒**。
- * 解法 = 建图时 `imageOrientation: "flipY"` 把翻转烘进位图，同时把 `texture.flipY = false`
- * 明说「已经翻过了」。1×2 像素对照实测：`<img>`+flipY=true 与 bitmap(flipY)+flipY=false 逐行一致。
- */
-/** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
- *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
- *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
-export function loadPanoTexture(url) {
-    return fetch(url)
-        .then((res) => {
-        if (!res.ok)
-            throw new Error(`HTTP ${res.status}`);
-        return res.blob();
-    })
-        .then((blob) => createImageBitmap(blob, {
-        imageOrientation: "flipY",
-        premultiplyAlpha: "none",
-        colorSpaceConversion: "none",
-    }))
-        .then((bmp) => {
-        const tex = new Texture(bmp);
-        tex.flipY = false; // 翻转已烘进位图（见文件头）
-        tex.needsUpdate = true;
-        // `TextureLoader` 时代的 `<img>.src` 在这里没有了；「打印 shader 数据」探针回退取地址要用它。
-        tex.userData.url = url;
-        return tex;
-    });
-}
-/** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**
- *  （不像 `<img>` 能等 GC —— 一张 270MB 的位图挂着不关，切几轮全景就把进程吃爆）。
- *  只在「这张纹理确实被丢掉」的清理路径上调用：关掉的位图再也传不上去，WebGL 上下文丢失后的重建会拿到空图。 */
-export function releasePanoTexture(tex) {
-    if (!tex)
-        return;
-    const bmp = tex.image;
-    tex.dispose();
-    if (bmp && typeof bmp.close === "function")
-        bmp.close();
-}
+import { Texture } from "three";
+/**
+ * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
+ *
+ * 为什么要换掉 three 的 `TextureLoader`：它只等 `img.onload`（字节到手），**从不解码** —— 解码是懒的，
+ * 真正碰像素的是上传那一拍的 `texImage2D(<img>)`，于是整段 JPEG 解码被拽到主线程上同步做完。
+ * 实测（2026-10-05，皇上线上的种子全景 11904×5952 / 解码后 270MB）：
+ *   `texImage2D(未解码的 <img>)` = **1266ms 全在主线程**；
+ *   `createImageBitmap` 解码 = **768ms 在工作线程**（同期主线程跑完 40 个宏任务只花 6ms），
+ *   解完再 `texImage2D(<ImageBitmap>)` = **366ms**（这 366 是 270MB 像素搬运，跟解码无关，只有降尺寸才能压掉）。
+ * ⚠️ 试过 `await img.decode()` 这条路：同一张图 **90 秒没回**（超大图的异步解码在 Chrome 上不可靠）⇒ 别再走它。
+ *
+ * ⚠️ **上下翻这颗雷（实测，别照抄直觉）**：Chrome 对 `ImageBitmap` 源**忽略** `UNPACK_FLIP_Y_WEBGL`
+ * （`<img>` / canvas 源认，bitmap 源不认）⇒ 直接把 `<img>` 换成 bitmap 会让全景**上下颠倒**。
+ * 解法 = 建图时 `imageOrientation: "flipY"` 把翻转烘进位图，同时把 `texture.flipY = false`
+ * 明说「已经翻过了」。1×2 像素对照实测：`<img>`+flipY=true 与 bitmap(flipY)+flipY=false 逐行一致。
+ */
+/** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
+ *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
+ *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
+export function loadPanoTexture(url) {
+    return fetch(url)
+        .then((res) => {
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return res.blob();
+    })
+        .then((blob) => createImageBitmap(blob, {
+        imageOrientation: "flipY",
+        premultiplyAlpha: "none",
+        colorSpaceConversion: "none",
+    }))
+        .then((bmp) => {
+        const tex = new Texture(bmp);
+        tex.flipY = false; // 翻转已烘进位图（见文件头）
+        tex.needsUpdate = true;
+        // `TextureLoader` 时代的 `<img>.src` 在这里没有了；「打印 shader 数据」探针回退取地址要用它。
+        tex.userData.url = url;
+        return tex;
+    });
+}
+/** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**
+ *  （不像 `<img>` 能等 GC —— 一张 270MB 的位图挂着不关，切几轮全景就把进程吃爆）。
+ *  只在「这张纹理确实被丢掉」的清理路径上调用：关掉的位图再也传不上去，WebGL 上下文丢失后的重建会拿到空图。 */
+export function releasePanoTexture(tex) {
+    if (!tex)
+        return;
+    const bmp = tex.image;
+    tex.dispose();
+    if (bmp && typeof bmp.close === "function")
+        bmp.close();
+}

package/MktMesh/panoBitmapTexture.ts

@@ -1,54 +1,54 @@
-import { Texture } from "three";
-
-/**
- * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
- *
- * 为什么要换掉 three 的 `TextureLoader`：它只等 `img.onload`（字节到手），**从不解码** —— 解码是懒的，
- * 真正碰像素的是上传那一拍的 `texImage2D(<img>)`，于是整段 JPEG 解码被拽到主线程上同步做完。
- * 实测（2026-10-05，皇上线上的种子全景 11904×5952 / 解码后 270MB）：
- *   `texImage2D(未解码的 <img>)` = **1266ms 全在主线程**；
- *   `createImageBitmap` 解码 = **768ms 在工作线程**（同期主线程跑完 40 个宏任务只花 6ms），
- *   解完再 `texImage2D(<ImageBitmap>)` = **366ms**（这 366 是 270MB 像素搬运，跟解码无关，只有降尺寸才能压掉）。
- * ⚠️ 试过 `await img.decode()` 这条路：同一张图 **90 秒没回**（超大图的异步解码在 Chrome 上不可靠）⇒ 别再走它。
- *
- * ⚠️ **上下翻这颗雷（实测，别照抄直觉）**：Chrome 对 `ImageBitmap` 源**忽略** `UNPACK_FLIP_Y_WEBGL`
- * （`<img>` / canvas 源认，bitmap 源不认）⇒ 直接把 `<img>` 换成 bitmap 会让全景**上下颠倒**。
- * 解法 = 建图时 `imageOrientation: "flipY"` 把翻转烘进位图，同时把 `texture.flipY = false`
- * 明说「已经翻过了」。1×2 像素对照实测：`<img>`+flipY=true 与 bitmap(flipY)+flipY=false 逐行一致。
- */
-
-/** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
- *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
- *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
-export function loadPanoTexture(url: string): Promise<Texture> {
-    return fetch(url)
-        .then((res) => {
-            if (!res.ok) throw new Error(`HTTP ${res.status}`);
-            return res.blob();
-        })
-        .then((blob) =>
-            createImageBitmap(blob, {
-                imageOrientation: "flipY",
-                premultiplyAlpha: "none",
-                colorSpaceConversion: "none",
-            })
-        )
-        .then((bmp) => {
-            const tex = new Texture(bmp);
-            tex.flipY = false; // 翻转已烘进位图（见文件头）
-            tex.needsUpdate = true;
-            // `TextureLoader` 时代的 `<img>.src` 在这里没有了；「打印 shader 数据」探针回退取地址要用它。
-            tex.userData.url = url;
-            return tex;
-        });
-}
-
-/** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**
- *  （不像 `<img>` 能等 GC —— 一张 270MB 的位图挂着不关，切几轮全景就把进程吃爆）。
- *  只在「这张纹理确实被丢掉」的清理路径上调用：关掉的位图再也传不上去，WebGL 上下文丢失后的重建会拿到空图。 */
-export function releasePanoTexture(tex: Texture | null | undefined): void {
-    if (!tex) return;
-    const bmp = tex.image as ImageBitmap | undefined;
-    tex.dispose();
-    if (bmp && typeof bmp.close === "function") bmp.close();
-}
+import { Texture } from "three";
+
+/**
+ * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
+ *
+ * 为什么要换掉 three 的 `TextureLoader`：它只等 `img.onload`（字节到手），**从不解码** —— 解码是懒的，
+ * 真正碰像素的是上传那一拍的 `texImage2D(<img>)`，于是整段 JPEG 解码被拽到主线程上同步做完。
+ * 实测（2026-10-05，皇上线上的种子全景 11904×5952 / 解码后 270MB）：
+ *   `texImage2D(未解码的 <img>)` = **1266ms 全在主线程**；
+ *   `createImageBitmap` 解码 = **768ms 在工作线程**（同期主线程跑完 40 个宏任务只花 6ms），
+ *   解完再 `texImage2D(<ImageBitmap>)` = **366ms**（这 366 是 270MB 像素搬运，跟解码无关，只有降尺寸才能压掉）。
+ * ⚠️ 试过 `await img.decode()` 这条路：同一张图 **90 秒没回**（超大图的异步解码在 Chrome 上不可靠）⇒ 别再走它。
+ *
+ * ⚠️ **上下翻这颗雷（实测，别照抄直觉）**：Chrome 对 `ImageBitmap` 源**忽略** `UNPACK_FLIP_Y_WEBGL`
+ * （`<img>` / canvas 源认，bitmap 源不认）⇒ 直接把 `<img>` 换成 bitmap 会让全景**上下颠倒**。
+ * 解法 = 建图时 `imageOrientation: "flipY"` 把翻转烘进位图，同时把 `texture.flipY = false`
+ * 明说「已经翻过了」。1×2 像素对照实测：`<img>`+flipY=true 与 bitmap(flipY)+flipY=false 逐行一致。
+ */
+
+/** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
+ *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
+ *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
+export function loadPanoTexture(url: string): Promise<Texture> {
+    return fetch(url)
+        .then((res) => {
+            if (!res.ok) throw new Error(`HTTP ${res.status}`);
+            return res.blob();
+        })
+        .then((blob) =>
+            createImageBitmap(blob, {
+                imageOrientation: "flipY",
+                premultiplyAlpha: "none",
+                colorSpaceConversion: "none",
+            })
+        )
+        .then((bmp) => {
+            const tex = new Texture(bmp);
+            tex.flipY = false; // 翻转已烘进位图（见文件头）
+            tex.needsUpdate = true;
+            // `TextureLoader` 时代的 `<img>.src` 在这里没有了；「打印 shader 数据」探针回退取地址要用它。
+            tex.userData.url = url;
+            return tex;
+        });
+}
+
+/** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**
+ *  （不像 `<img>` 能等 GC —— 一张 270MB 的位图挂着不关，切几轮全景就把进程吃爆）。
+ *  只在「这张纹理确实被丢掉」的清理路径上调用：关掉的位图再也传不上去，WebGL 上下文丢失后的重建会拿到空图。 */
+export function releasePanoTexture(tex: Texture | null | undefined): void {
+    if (!tex) return;
+    const bmp = tex.image as ImageBitmap | undefined;
+    tex.dispose();
+    if (bmp && typeof bmp.close === "function") bmp.close();
+}

package/MktMesh/panoSlotBind.d.ts

@@ -1,29 +1,29 @@
-import type { ShaderMaterial, Texture } from "three";
-/** 取一张「已解码**且**已上传 GPU」的瓦片；未就绪要**当场**自行起载 / 排上传，然后返回 null。
- *  ⚠️ 语义硬约束（皇上旨 09-25「队列里的代码就是把加载好的纹理设进 shader 这一句」）：
- *     本回调**不许**做同步的重活（解码、上传、绑定判断都不许在 render 里现场发生），只负责「发起 + 报告就绪」。 */
-export interface PanoSlotBindDeps {
-    peek(key: string, original: boolean): Texture | null;
-    /** 整槽口径（**只**给跨形态翻转那一次用）：同一个点的 `RT_STITCH_SLOT_COUNT` 张一起要，缺的返回 null。
-     *  编辑器实现 = `_peekSlotGen`（带 `proxy:` 过渡档墓碑分支），库实现 = 逐张 `peek`；
-     *  「判不齐就整档不换」这个**决定**仍然只在本文件里下。 */
-    peekSlot(tiles: string[], original: boolean): (Texture | null)[];
-    /** 该槽从没成功绑过任何图时用来垫 sampler 的 1×1 占位（⛔ 空 sampler 会报错） */
-    placeholder: Texture;
-}
-/** 取（必要时建）某材质的逐格地址账本；`len` = `panoramas.length`（= 点数 × `RT_STITCH_SLOT_COUNT`）。 */
-export declare function panoSlotTileKeys(mat: ShaderMaterial, len: number): string[];
-/**
- * 把一个「点槽」的 `RT_STITCH_SLOT_COUNT` 张瓦片换绑进 `panoramas[base .. base + RT_STITCH_SLOT_COUNT - 1]`。
- *
- * 返回 true = 本槽这一帧的图与点位**配好了**（调用方据此写投影矩阵）；false = 沿用上一批（调用方矩阵也别动）。
- *
- * ⚠️ 只有一条例外必须整槽同帧：`uPanoTiled` 是**按槽一个标记**（每点一个数，不是每张一个），
- *    它告诉着色器「这几个槽装的是左右两张拼合槽(1) 还是一张整图(0)」。跨形态那一次（瓦片 ↔ 整片、
- *    或某点压根没切过片）若逐张换，中间几帧会拿整图按半幅采（或反之）⇒ 瞬间拉伸错位。
- *    所以「目标形态 ≠ 本槽现有形态」时走整档判齐口径。
- * ⚠️ 同形态内也分两条路（09-25 治本）：**整槽换人**（有格正贴着另一批的真图 ⇒ 全部同帧换，判不齐一张都不动）与
- *    **逐张补格**（本槽空着或同一批地址还缺的格 ⇒ 到一张补一张）。
- *    「这一格认的是哪张地址」记在 `panoSlotTileKeys`，换人不成就连账本都不改，下一帧重试。
- */
-export declare function panoSlotBind(mat: ShaderMaterial, panos: Texture[], base: number, tiles: string[], tiled: boolean, slot: number | undefined, deps: PanoSlotBindDeps): boolean;
+import type { ShaderMaterial, Texture } from "three";
+/** 取一张「已解码**且**已上传 GPU」的瓦片；未就绪要**当场**自行起载 / 排上传，然后返回 null。
+ *  ⚠️ 语义硬约束（皇上旨 09-25「队列里的代码就是把加载好的纹理设进 shader 这一句」）：
+ *     本回调**不许**做同步的重活（解码、上传、绑定判断都不许在 render 里现场发生），只负责「发起 + 报告就绪」。 */
+export interface PanoSlotBindDeps {
+    peek(key: string, original: boolean): Texture | null;
+    /** 整槽口径（**只**给跨形态翻转那一次用）：同一个点的 `RT_STITCH_SLOT_COUNT` 张一起要，缺的返回 null。
+     *  编辑器实现 = `_peekSlotGen`（带 `proxy:` 过渡档墓碑分支），库实现 = 逐张 `peek`；
+     *  「判不齐就整档不换」这个**决定**仍然只在本文件里下。 */
+    peekSlot(tiles: string[], original: boolean): (Texture | null)[];
+    /** 该槽从没成功绑过任何图时用来垫 sampler 的 1×1 占位（⛔ 空 sampler 会报错） */
+    placeholder: Texture;
+}
+/** 取（必要时建）某材质的逐格地址账本；`len` = `panoramas.length`（= 点数 × `RT_STITCH_SLOT_COUNT`）。 */
+export declare function panoSlotTileKeys(mat: ShaderMaterial, len: number): string[];
+/**
+ * 把一个「点槽」的 `RT_STITCH_SLOT_COUNT` 张瓦片换绑进 `panoramas[base .. base + RT_STITCH_SLOT_COUNT - 1]`。
+ *
+ * 返回 true = 本槽这一帧的图与点位**配好了**（调用方据此写投影矩阵）；false = 沿用上一批（调用方矩阵也别动）。
+ *
+ * ⚠️ 只有一条例外必须整槽同帧：`uPanoTiled` 是**按槽一个标记**（每点一个数，不是每张一个），
+ *    它告诉着色器「这几个槽装的是左右两张拼合槽(1) 还是一张整图(0)」。跨形态那一次（瓦片 ↔ 整片、
+ *    或某点压根没切过片）若逐张换，中间几帧会拿整图按半幅采（或反之）⇒ 瞬间拉伸错位。
+ *    所以「目标形态 ≠ 本槽现有形态」时走整档判齐口径。
+ * ⚠️ 同形态内也分两条路（09-25 治本）：**整槽换人**（有格正贴着另一批的真图 ⇒ 全部同帧换，判不齐一张都不动）与
+ *    **逐张补格**（本槽空着或同一批地址还缺的格 ⇒ 到一张补一张）。
+ *    「这一格认的是哪张地址」记在 `panoSlotTileKeys`，换人不成就连账本都不改，下一帧重试。
+ */
+export declare function panoSlotBind(mat: ShaderMaterial, panos: Texture[], base: number, tiles: string[], tiled: boolean, slot: number | undefined, deps: PanoSlotBindDeps): boolean;

package/MktMesh/panoSlotBind.js

@@ -1,106 +1,106 @@
-import { RT_STITCH_SLOT_COUNT, setMktPanoTiled } from "./mktShader";
-/**
- * 「panoramas[i] 这一格认的是哪张瓦片地址」——逐张换绑的**账本**，按材质实例分 WeakMap 键。
- * 放模块级 ⇒ 编辑器与库**共一本账**（两侧材质是不同实例，天然不串味）；材质重建后自动从空账开始。
- */
-const slotTileKeys = new WeakMap();
-/** 取（必要时建）某材质的逐格地址账本；`len` = `panoramas.length`（= 点数 × `RT_STITCH_SLOT_COUNT`）。 */
-export function panoSlotTileKeys(mat, len) {
-    let keys = slotTileKeys.get(mat);
-    if (!keys) {
-        keys = new Array(len).fill("");
-        slotTileKeys.set(mat, keys);
-    }
-    return keys;
-}
-/**
- * 把一个「点槽」的 `RT_STITCH_SLOT_COUNT` 张瓦片换绑进 `panoramas[base .. base + RT_STITCH_SLOT_COUNT - 1]`。
- *
- * 返回 true = 本槽这一帧的图与点位**配好了**（调用方据此写投影矩阵）；false = 沿用上一批（调用方矩阵也别动）。
- *
- * ⚠️ 只有一条例外必须整槽同帧：`uPanoTiled` 是**按槽一个标记**（每点一个数，不是每张一个），
- *    它告诉着色器「这几个槽装的是左右两张拼合槽(1) 还是一张整图(0)」。跨形态那一次（瓦片 ↔ 整片、
- *    或某点压根没切过片）若逐张换，中间几帧会拿整图按半幅采（或反之）⇒ 瞬间拉伸错位。
- *    所以「目标形态 ≠ 本槽现有形态」时走整档判齐口径。
- * ⚠️ 同形态内也分两条路（09-25 治本）：**整槽换人**（有格正贴着另一批的真图 ⇒ 全部同帧换，判不齐一张都不动）与
- *    **逐张补格**（本槽空着或同一批地址还缺的格 ⇒ 到一张补一张）。
- *    「这一格认的是哪张地址」记在 `panoSlotTileKeys`，换人不成就连账本都不改，下一帧重试。
- */
-export function panoSlotBind(mat, panos, base, tiles, tiled, slot, deps) {
-    // 单全景材质的 uPanoTiled 是标量（写的时候忽略槽位）；融合/映射材质是每点一个的数组 ⇒ 读法两样，判定同一个。
-    const uv = mat.uniforms.uPanoTiled?.value;
-    const curTiled = uv === undefined ? tiled
-        : (typeof uv === "number" ? uv > 0.5 : uv[slot ?? 0] > 0.5);
-    if (curTiled !== tiled) {
-        // ── 跨形态：整槽判齐、一次写入、同一帧翻标记（见上面 ⚠️）──
-        //    ⭐ 09-28 旨「瓦片纹理不需要添加 oss 的参数」后，过渡缩图档与原图档下载的是**同一张图**，
-        //    「原图没齐先上缩图」的兜底只剩双下载 ⇒ 整条删除；判不齐就沿用上一批。
-        const ready = deps.peekSlot(tiles, tiled);
-        // ⛔ 判齐用「本点槽数」派生（不许写 `ready[0] && ready[1] && ready[2] && ready[3]`）
-        const all = ready.length >= RT_STITCH_SLOT_COUNT && ready.slice(0, RT_STITCH_SLOT_COUNT).every((t) => !!t);
-        if (all) {
-            const keys = panoSlotTileKeys(mat, panos.length);
-            for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-                panos[base + k] = ready[k];
-                keys[base + k] = tiles[k];
-            }
-            // ⚠️ 纹理与形态标记必须同一帧落地（分叉过一次 = 整片形态按瓦片 UV 采整图 ⇒ 半幅拉伸）
-            setMktPanoTiled(mat, tiled ? 1 : 0, slot);
-            return true;
-        }
-        // 整档还没齐：本槽沿用上一批（sampler 读到 undefined 会报错，所以压根没绑过才填占位）
-        if (!panos[base]) {
-            const keys = panoSlotTileKeys(mat, panos.length);
-            for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-                panos[base + k] = deps.placeholder;
-                keys[base + k] = tiles[k];
-            }
-            setMktPanoTiled(mat, tiled ? 1 : 0, slot); // 占位是 1×1 素色，两种采法无差别，直接把标记对准目标
-        }
-        return false;
-    }
-    // ── 同形态 ──
-    const keys = panoSlotTileKeys(mat, panos.length);
-    // ⭐ 换人（皇上旨 09-25「绝不让一张已显示的全景因为正在补第 3 格瓦片而整体退出」）：
-    //    只要**有任何一格正贴着别的批次的真图**，本槽这次就是「整槽换人」⇒ 整槽所有张必须同帧落地，
-    //    判不齐就一张都不动（连账本也不动 ⇒ 下一帧照判「要换」继续重试，缺的那几张的下载/上传已由 `deps.peek` 当场发起）。
-    //    否则旧全景的第 1 张会配新全景的投影矩阵、且权重照给 ⇒ 墙上的图一会儿这张一会儿那张（正是他报的现象）。
-    let swapping = false;
-    for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-        const cur = panos[base + k];
-        if (cur && cur !== deps.placeholder && keys[base + k] !== tiles[k]) {
-            swapping = true;
-            break;
-        }
-    }
-    if (swapping) {
-        const got = [];
-        for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-            // ⭐ 09-28 旨后不再退缩图档（过渡档去参 = 同一张原图，兜底只剩双下载）
-            got.push(deps.peek(tiles[k], tiled));
-        }
-        if (!got.every((t) => !!t))
-            return false; // 沿用上一批：图 + 矩阵 + 账本一概留着
-        for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-            panos[base + k] = got[k];
-            keys[base + k] = tiles[k];
-        }
-        return true;
-    }
-    // ── 逐张补格（皇上的口径）：走到这里说明本槽没有任何一格贴着别的批次的真图
-    //    ⇒ 不是「首次那几帧」（整槽都是 1×1 占位），就是「同一批地址里还缺的格」。
-    //    两种都各判各的、到一张补一张，缺的格露的是素色占位而非另一张全景 ⇒ 无需攒齐。──
-    let bound = false;
-    for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-        const i = base + k;
-        // ⭐ 09-28 旨后不再退缩图档（过渡档去参 = 同一张原图，兜底只剩双下载）
-        const tex = deps.peek(tiles[k], tiled);
-        if (!tex)
-            continue; // 还在路上（缺的这张已由 deps.peek 当场发起下载 / 排上传）
-        keys[i] = tiles[k];
-        if (panos[i] !== tex)
-            panos[i] = tex;
-        bound = true;
-    }
-    return bound;
-}
+import { RT_STITCH_SLOT_COUNT, setMktPanoTiled } from "./mktShader";
+/**
+ * 「panoramas[i] 这一格认的是哪张瓦片地址」——逐张换绑的**账本**，按材质实例分 WeakMap 键。
+ * 放模块级 ⇒ 编辑器与库**共一本账**（两侧材质是不同实例，天然不串味）；材质重建后自动从空账开始。
+ */
+const slotTileKeys = new WeakMap();
+/** 取（必要时建）某材质的逐格地址账本；`len` = `panoramas.length`（= 点数 × `RT_STITCH_SLOT_COUNT`）。 */
+export function panoSlotTileKeys(mat, len) {
+    let keys = slotTileKeys.get(mat);
+    if (!keys) {
+        keys = new Array(len).fill("");
+        slotTileKeys.set(mat, keys);
+    }
+    return keys;
+}
+/**
+ * 把一个「点槽」的 `RT_STITCH_SLOT_COUNT` 张瓦片换绑进 `panoramas[base .. base + RT_STITCH_SLOT_COUNT - 1]`。
+ *
+ * 返回 true = 本槽这一帧的图与点位**配好了**（调用方据此写投影矩阵）；false = 沿用上一批（调用方矩阵也别动）。
+ *
+ * ⚠️ 只有一条例外必须整槽同帧：`uPanoTiled` 是**按槽一个标记**（每点一个数，不是每张一个），
+ *    它告诉着色器「这几个槽装的是左右两张拼合槽(1) 还是一张整图(0)」。跨形态那一次（瓦片 ↔ 整片、
+ *    或某点压根没切过片）若逐张换，中间几帧会拿整图按半幅采（或反之）⇒ 瞬间拉伸错位。
+ *    所以「目标形态 ≠ 本槽现有形态」时走整档判齐口径。
+ * ⚠️ 同形态内也分两条路（09-25 治本）：**整槽换人**（有格正贴着另一批的真图 ⇒ 全部同帧换，判不齐一张都不动）与
+ *    **逐张补格**（本槽空着或同一批地址还缺的格 ⇒ 到一张补一张）。
+ *    「这一格认的是哪张地址」记在 `panoSlotTileKeys`，换人不成就连账本都不改，下一帧重试。
+ */
+export function panoSlotBind(mat, panos, base, tiles, tiled, slot, deps) {
+    // 单全景材质的 uPanoTiled 是标量（写的时候忽略槽位）；融合/映射材质是每点一个的数组 ⇒ 读法两样，判定同一个。
+    const uv = mat.uniforms.uPanoTiled?.value;
+    const curTiled = uv === undefined ? tiled
+        : (typeof uv === "number" ? uv > 0.5 : uv[slot ?? 0] > 0.5);
+    if (curTiled !== tiled) {
+        // ── 跨形态：整槽判齐、一次写入、同一帧翻标记（见上面 ⚠️）──
+        //    ⭐ 09-28 旨「瓦片纹理不需要添加 oss 的参数」后，过渡缩图档与原图档下载的是**同一张图**，
+        //    「原图没齐先上缩图」的兜底只剩双下载 ⇒ 整条删除；判不齐就沿用上一批。
+        const ready = deps.peekSlot(tiles, tiled);
+        // ⛔ 判齐用「本点槽数」派生（不许写 `ready[0] && ready[1] && ready[2] && ready[3]`）
+        const all = ready.length >= RT_STITCH_SLOT_COUNT && ready.slice(0, RT_STITCH_SLOT_COUNT).every((t) => !!t);
+        if (all) {
+            const keys = panoSlotTileKeys(mat, panos.length);
+            for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+                panos[base + k] = ready[k];
+                keys[base + k] = tiles[k];
+            }
+            // ⚠️ 纹理与形态标记必须同一帧落地（分叉过一次 = 整片形态按瓦片 UV 采整图 ⇒ 半幅拉伸）
+            setMktPanoTiled(mat, tiled ? 1 : 0, slot);
+            return true;
+        }
+        // 整档还没齐：本槽沿用上一批（sampler 读到 undefined 会报错，所以压根没绑过才填占位）
+        if (!panos[base]) {
+            const keys = panoSlotTileKeys(mat, panos.length);
+            for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+                panos[base + k] = deps.placeholder;
+                keys[base + k] = tiles[k];
+            }
+            setMktPanoTiled(mat, tiled ? 1 : 0, slot); // 占位是 1×1 素色，两种采法无差别，直接把标记对准目标
+        }
+        return false;
+    }
+    // ── 同形态 ──
+    const keys = panoSlotTileKeys(mat, panos.length);
+    // ⭐ 换人（皇上旨 09-25「绝不让一张已显示的全景因为正在补第 3 格瓦片而整体退出」）：
+    //    只要**有任何一格正贴着别的批次的真图**，本槽这次就是「整槽换人」⇒ 整槽所有张必须同帧落地，
+    //    判不齐就一张都不动（连账本也不动 ⇒ 下一帧照判「要换」继续重试，缺的那几张的下载/上传已由 `deps.peek` 当场发起）。
+    //    否则旧全景的第 1 张会配新全景的投影矩阵、且权重照给 ⇒ 墙上的图一会儿这张一会儿那张（正是他报的现象）。
+    let swapping = false;
+    for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+        const cur = panos[base + k];
+        if (cur && cur !== deps.placeholder && keys[base + k] !== tiles[k]) {
+            swapping = true;
+            break;
+        }
+    }
+    if (swapping) {
+        const got = [];
+        for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+            // ⭐ 09-28 旨后不再退缩图档（过渡档去参 = 同一张原图，兜底只剩双下载）
+            got.push(deps.peek(tiles[k], tiled));
+        }
+        if (!got.every((t) => !!t))
+            return false; // 沿用上一批：图 + 矩阵 + 账本一概留着
+        for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+            panos[base + k] = got[k];
+            keys[base + k] = tiles[k];
+        }
+        return true;
+    }
+    // ── 逐张补格（皇上的口径）：走到这里说明本槽没有任何一格贴着别的批次的真图
+    //    ⇒ 不是「首次那几帧」（整槽都是 1×1 占位），就是「同一批地址里还缺的格」。
+    //    两种都各判各的、到一张补一张，缺的格露的是素色占位而非另一张全景 ⇒ 无需攒齐。──
+    let bound = false;
+    for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+        const i = base + k;
+        // ⭐ 09-28 旨后不再退缩图档（过渡档去参 = 同一张原图，兜底只剩双下载）
+        const tex = deps.peek(tiles[k], tiled);
+        if (!tex)
+            continue; // 还在路上（缺的这张已由 deps.peek 当场发起下载 / 排上传）
+        keys[i] = tiles[k];
+        if (panos[i] !== tex)
+            panos[i] = tex;
+        bound = true;
+    }
+    return bound;
+}