three-base 2.0.137 → 2.0.142

package/MktMesh/panoBitmapTexture.d.ts

@@ -0,0 +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;

package/MktMesh/panoBitmapTexture.js

@@ -0,0 +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();
+}

package/MktMesh/panoBitmapTexture.ts

@@ -0,0 +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();
+}

package/MktMesh/panoSlotBind.d.ts

@@ -0,0 +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;

package/MktMesh/panoSlotBind.js

@@ -0,0 +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;
+}

package/MktMesh/panoSlotBind.ts

@@ -0,0 +1,153 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2026-10-03
+ * @Description: 「一个点槽（同一个全景点的 `RT_STITCH_SLOT_COUNT` 张瓦片）如何换绑进 shader」的**唯一**策略实现
+ * （皇上旨 2026-10-03「整套搬进库（彻底同源）」）。
+ *
+ * ⭐ 2026-10-06 晚皇上旨「每个全景纹理由**左右 2 个 RT** 组成」⇒ 一个点槽的张数从 4 降到 **2**，
+ *    同屏全景数从 4 涨到 **8**。本文件里所有「几张」一律由 `RT_STITCH_SLOT_COUNT` 派生，
+ *    ⛔ 不许再出现字面量 4（槽数再变会漏改 —— 这正是当年两侧分家的老毛病）。
+ *
+ * 来历：这套判据原先只活在编辑态 `mktMeshEditRenderer._bindSlotTiles`（皇上旨 09-24「一张一张替换上去，别 4 张一起换」
+ * + 09-25「未就绪整槽沿用上一批」+ 09-25「绝不让一张已显示的全景因为正在补第 3 格瓦片而整体退出」）。
+ * 库侧（预览 / 发布态 `MktMesh.feedFaceMapping`）走的是另一套「齐活才写、矩阵无条件 copy」⇒ ① 换景点会闪一帧灰，
+ * ② 图与投影矩阵可能来自**不同批**（旧图配新矩阵）。皇上看的是线上观感，两侧必须同一份代码，故整条搬进来。
+ *
+ * ⛔ 本文件是这个问题的**第一份也是唯一一份**实现：编辑器与库都只许「委托一行」并把各自的取图口注入进来。
+ *    出现第二份 = 两侧又会分家（护栏里有反钉）。
+ *
+ * 依赖注入的原因：编辑器与库的纹理来源不同（编辑器有自己的 `_floorTexCache` + `threeUtils` 上传队列；
+ * 库读自身那份），但「什么时候可以换、换要换几个、没换成该怎么办」这个**决策**必须完全一致 ⇒
+ * 决策留在本文件，取货与占位纹理由 `deps` 交进来。
+ */
+import type { ShaderMaterial, Texture } from "three";
+import { RT_STITCH_SLOT_COUNT, setMktPanoTiled } from "./mktShader";
+
+/** 取一张「已解码**且**已上传 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;
+}
+
+/**
+ * 「panoramas[i] 这一格认的是哪张瓦片地址」——逐张换绑的**账本**，按材质实例分 WeakMap 键。
+ * 放模块级 ⇒ 编辑器与库**共一本账**（两侧材质是不同实例，天然不串味）；材质重建后自动从空账开始。
+ */
+const slotTileKeys = new WeakMap<ShaderMaterial, string[]>();
+
+/** 取（必要时建）某材质的逐格地址账本；`len` = `panoramas.length`（= 点数 × `RT_STITCH_SLOT_COUNT`）。 */
+export function panoSlotTileKeys(mat: ShaderMaterial, len: number): string[] {
+    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: ShaderMaterial,
+    panos: Texture[],
+    base: number,
+    tiles: string[],
+    tiled: boolean,
+    slot: number | undefined,
+    deps: PanoSlotBindDeps,
+): boolean {
+    // 单全景材质的 uPanoTiled 是标量（写的时候忽略槽位）；融合/映射材质是每点一个的数组 ⇒ 读法两样，判定同一个。
+    const uv = mat.uniforms.uPanoTiled?.value as number | ArrayLike<number> | undefined;
+    const curTiled = uv === undefined ? tiled
+        : (typeof uv === "number" ? uv > 0.5 : (uv[slot ?? 0] as number) > 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] as Texture;
+                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: (Texture | null)[] = [];
+        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] as Texture;
+            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;
+}

package/MktMesh/panoSlotRoster.d.ts

@@ -0,0 +1,22 @@
+/** ⭐ 槽位「中心死区」（米）：离**锚点**（控制器中心点；发布页未注入时 = 相机位置）水平距离最近的那张是中心；挑战者必须比现任中心**近出这么多**才抢得走。
+ *  没有死区 ⇒ 锚点停在两点的等距带附近每帧换中心 ⇒ 换中心 = 整组邻居重排 = 一整组瓦片重绑（正是 09-24/25 报的「切全景卡一下」）。
+ *  定义在此是因为编辑态与库侧共用（全项目**只此一处**，两侧都 import 它）。 */
+export declare const PANO_SLOT_SWAP_MARGIN_M = 0.5;
+/** 一个候选：`t` 是全景点对象（存引用不存下标 —— 删点会让下标整体前移，引用不会认错人），`d` 是它到**锚点**的水平距离（锚点由调用方决定，本函数不认识它） */
+export interface PanoRosterCand<T> {
+    t: T;
+    d: number;
+}
+/**
+ * 算出下一帧的槽位名册（**不修改传进来的 roster**，返回新数组）。
+ * @param roster   当前名册（0 号槽 = 上一帧的中心），长度可以小于 maxSlots（内部按 undefined 补齐）
+ * @param dists    本帧全部全景点及其到**锚点**的距离（锚点 = 调用方那把尺子的端点；⭐ 10-07 第二十一道旨后 = 控制器中心点），**数组顺序 = 全景列表顺序**（下标就是旨意里说的「几号全景」）
+ * @param maxSlots shader 的槽位上限（= `MKT_PANO_MAX_SLOTS`；⭐ 2026-10-06 晚旨后是 **8**：8 点 × 每个全景
+ *          左右 2 张 RT = 16 sampler 仍是 GLSL 物理上限。⛔ 本函数不许假设它恒等于 4）
+ * @param margin   抢中心的死区（米，= `PANO_SLOT_SWAP_MARGIN_M`）
+ * @returns 长度恒 = maxSlots 的新名册：**0 号槽 = 中心**，其余槽 = 列表里按序号一层层往外扩的那些
+ *          （同一层先取离锚点更近那侧）。⭐ 10-07 旨「尽可能填满」⇒ 越界的序号不占格、外扩继续往有货那侧走，
+ *          所以**填几格 = min(项目全景总数, maxSlots)**；只有列表里的人不够时才留空（= `undefined`）。
+ *          中心没换人 ⇒ 在册的一格都不动，只把**空格**补上。
+ */
+export declare function panoSlotRosterStep<T>(roster: (T | undefined)[], dists: PanoRosterCand<T>[], maxSlots: number, margin: number): (T | undefined)[];

package/MktMesh/panoSlotRoster.js

@@ -0,0 +1,169 @@
+/*
+ * ⭐ 槽位名册纯函数：**「中心 + 序号邻居」**定 shader 那 N 格装哪 N 张全景（皇上旨 2026-10-02 晚；
+ *   2026-10-06 晚旨「一次展示 8 个全景」⇒ N 从 4 变 8，靠「每个全景只占左右 2 张 RT」腾出 sampler）。
+ *
+ * 旨意原文（verbatim）：「我想要把按距离筛选的逻辑, 改一改, 首先, 按照 全景到相机的距离选中第一个,
+ *   然后按照这个全景的序号, 前后各添加一个全景, 举个例子, 通过计算 5号 全景距离相机最近,
+ *   那就选出一个 5号全景填入 shader 然后再, 5号前后是 4号 和 6号, 也分别填入 shader,
+ *   最后再判断一下, 如果相机距离4号的距离 比 相机距离6号的距离近 就再追加一个[它外侧那张]全景, 反之就追加一个 7号 全景,
+ *   如果没有 目标全景, 比如 1号全景往前 没有 -1 -2 号全景, shader 里面就留空」
+ * ⭐ 同日追问三择（verbatim）：「补 3 号（顺着往外扩一张）」／「中心没换人就维持整组」／
+ *   探针第一行「打成『中心#5 ＋ 邻居 4/6/7』」。
+ * ⭐ 皇上旨 2026-10-07（第二十道，verbatim）：「shader 是可以支持最多传入8个全景的, 所以尽可能得填满8个全景位置」
+ *   ⇒ 收窄上面那句「如果没有目标全景…就留空」的适用边界：**留空只发生在「项目里的全景总数不够一格一人」时**；
+ *   序号越界的那个位置根本不是一张全景 ⇒ 跳过它、继续往还有货的那一侧扩，槽位不许白留给「不存在的序号」。
+ *   同一道旨还要求：新加的全景点**不必等中心换人**才进 shader ⇒ 中心没换人时在册的人照旧一格不动，空格当场补满。
+ *   ⚠️ 上限仍是 `MKT_PANO_MAX_SLOTS`(=8)：8 点 × 左右 2 张拼合槽 = 16 个 sampler，那是 GLSL 物理闸
+ *   （皇上机器 maxTextures=16）⇒ 本函数不越那道闸，只是把那 8 格**尽量用满**。
+ * ⭐ 皇上旨 2026-10-07 第二十一道旨（verbatim）：「判断使用那些全景球的判断条件, 从距离相机的距离 改成
+ *   判断距离控制器的中心点的距离来判断」⇒ **本函数的尺子另一端换了人**：函数体一个字不改（它只吃调用方算好的
+ *   `d`），改的是**调用方**——编辑态与预览的锚点 = 轨道控制器注视点 `controls.target`（画面正中央那个点），
+ *   发布页那一路没有控制器 ⇒ 回落相机位置。下面所有「相机」二字请按「锚点（= 控制器中心点，未注入时才是相机）」读；
+ *   10-02 那道旨的原文里「距离相机最近」是**历史引文**，逐字保留。
+ *   ⚠️ 同一把尺还喂着 `camW`（混合权重）⇒ 权重跟着换锚点；而面上「取哪一张」的 `score = 顶点距离 − 夹角`
+ *   里**根本没有相机量**（09-28 15:07 七修亲自撤掉 camD 项），不受本道旨影响。
+ *
+ * 一句话口径：
+ *   1) **中心** = 到**锚点**（调用方给的水平距离 XZ；锚点 = 控制器中心点，见上方 10-07 那道旨）最近那张；
+ *      ⚠️ 带死区 `margin`：别人必须比在册中心**近出 margin 米以上**
+ *      才抢走中心 ⇒ 锚点在等距带抖动时整组一动不动（09-26 那条「其他 3 个依然不动」的稳定诉求搬到这里来用）。
+ *   2) 中心定了之后按**列表序号**（= 面板列表顺序 = 日志里那个 `#i`）取邻居：`中心-1`、`中心+1` 各一张。
+ *   3) 再往外一层层扩（`中心±2`、`中心±3`…）直到凑够槽数；**同一层里先取离锚点更近那一侧**
+ *      （平手归序号小的那侧）。⭐ 2026-10-06 晚旨「一次展示 8 个」⇒ 槽数 4 → 8，这里从「只扩一层」
+ *      改成一层层扩下去；前 4 张的顺序与 4 槽时代**逐字相同**（中心、-1、+1、更近那侧的 ±2）。
+ *   4) ⭐ 2026-10-07 皇上旨「shader 是可以支持最多传入 8 个全景的, 所以尽可能得填满 8 个全景位置」
+ *      ⇒ **改写 10-02 那句「没有目标全景就留空」的适用边界**：越界的那个**序号**直接跳过（它本来就不是一个全景），
+ *      外扩**继续往还有货的那一侧**走 ⇒ 只要列表里还有没用过的全景，槽就一直被填，直到凑够 `maxSlots`。
+ *      ⛔ 只有「整个列表都被请进来了还不够一格一人的时候」（= 项目里的全景总数 < 槽数）才留空 ——
+ *      那是物理不够，不是策略留白。旧行为（中心贴列表两端 ⇒ 明明还有 5 张没用上却空着 3 格）作废。
+ *   5) ⭐ 中心没换人 ⇒ **在册的人一格都不动**（10-02 当日亲择，照旧）；但 10-07 那道旨补了后半句：
+ *      **空格要当场补上** ⇒ 新增的全景点不必等「中心换人」才进 shader（否则他一张一张加点时永远填不满）。
+ *
+ * ⚠️ 与历代口径的关系（别搞混）：
+ *   - 09-25「槽位与相机完全无关」→ 09-26「名册增量换人（一进一出）」→ 09-27「在册者按相机距离落槽、取最近 4 个」
+ *     ⇒ 本函数把 09-27 那半条**作废**：不再取「最近 4 个」，改取「最近那一张的序号邻居」，槽号也不再按距离排。
+ *   - 09-26 的「一进一出 + 0.5m 死区」精神保留，但对象从「谁挤掉谁」变成「谁能抢走中心」。
+ *
+ * ⚠️ 为什么 0 号槽必须是中心：立方体（`FurnitureObject`）那份 `BoxGeometry` **没有** `aPanoIndex` attribute ⇒
+ *    序号映射 shader 里 `vPanoIndex` 恒 0 ⇒ 立方体显示的就是名册第 0 格那一张（皇上旨 10-02「模型也按距离相机最近的方式
+ *    设置全景参数」的落点）。中心坐别的格 = 立方体显示错图。
+ *
+ * ⚠️ 为什么单独成文件：本函数零依赖（不碰 three / MobX / DOM），`test/mktmesh.test.js` 的 **AP 组**会用 esbuild
+ *    把**这份源码原文**转译后真跑一遍（中心/邻居/外扩/越界不占格/死区/删点/幂等/空格回填 各断言一次）。
+ *    ⇒ 改这里的算法，那条数字测试立刻知道；⛔ 别把逻辑搬回渲染器里，那样就只能靠正则钉、证不了行为。
+ *
+ * ⭐ 皇上旨 2026-10-03「库侧也一并改成中心 ± 邻居」⇒ 本文件从 `src/views/MktMeshEdit/` **搬进库里**
+ *    （`three-base/MktMesh/`）：编辑态（`mktMeshEditRenderer`）与预览/发布态（`MktMesh.updateTexture` +
+ *    `feedFaceMapping`）**共用这一份算法和下面那一个死区常数**，⛔ 不许在任一侧再抄一份 0.5 或另写一套挑图。
+ */
+/** ⭐ 槽位「中心死区」（米）：离**锚点**（控制器中心点；发布页未注入时 = 相机位置）水平距离最近的那张是中心；挑战者必须比现任中心**近出这么多**才抢得走。
+ *  没有死区 ⇒ 锚点停在两点的等距带附近每帧换中心 ⇒ 换中心 = 整组邻居重排 = 一整组瓦片重绑（正是 09-24/25 报的「切全景卡一下」）。
+ *  定义在此是因为编辑态与库侧共用（全项目**只此一处**，两侧都 import 它）。 */
+export const PANO_SLOT_SWAP_MARGIN_M = 0.5;
+/**
+ * 算出下一帧的槽位名册（**不修改传进来的 roster**，返回新数组）。
+ * @param roster   当前名册（0 号槽 = 上一帧的中心），长度可以小于 maxSlots（内部按 undefined 补齐）
+ * @param dists    本帧全部全景点及其到**锚点**的距离（锚点 = 调用方那把尺子的端点；⭐ 10-07 第二十一道旨后 = 控制器中心点），**数组顺序 = 全景列表顺序**（下标就是旨意里说的「几号全景」）
+ * @param maxSlots shader 的槽位上限（= `MKT_PANO_MAX_SLOTS`；⭐ 2026-10-06 晚旨后是 **8**：8 点 × 每个全景
+ *          左右 2 张 RT = 16 sampler 仍是 GLSL 物理上限。⛔ 本函数不许假设它恒等于 4）
+ * @param margin   抢中心的死区（米，= `PANO_SLOT_SWAP_MARGIN_M`）
+ * @returns 长度恒 = maxSlots 的新名册：**0 号槽 = 中心**，其余槽 = 列表里按序号一层层往外扩的那些
+ *          （同一层先取离锚点更近那侧）。⭐ 10-07 旨「尽可能填满」⇒ 越界的序号不占格、外扩继续往有货那侧走，
+ *          所以**填几格 = min(项目全景总数, maxSlots)**；只有列表里的人不够时才留空（= `undefined`）。
+ *          中心没换人 ⇒ 在册的一格都不动，只把**空格**补上。
+ */
+export function panoSlotRosterStep(roster, dists, maxSlots, margin) {
+    const next = roster.slice(0, maxSlots);
+    while (next.length < maxSlots)
+        next.push(undefined);
+    const alive = new Set(dists.map((n) => n.t));
+    // ① 已被删掉的点先腾槽（名册里躺着一个不存在的点 = 那格的矩阵与权重都是旧账）
+    for (let s = 0; s < maxSlots; s++)
+        if (next[s] && !alive.has(next[s]))
+            next[s] = undefined;
+    if (!dists.length)
+        return next.fill(undefined);
+    // ② 在册中心 = 0 号槽那位；别人必须比它近出 margin 以上才换中心
+    const incumbent = next[0] !== undefined && alive.has(next[0]) ? next[0] : undefined;
+    let nearest = 0;
+    for (let i = 1; i < dists.length; i++)
+        if (dists[i].d < dists[nearest].d)
+            nearest = i;
+    const incIdx = incumbent === undefined ? -1 : dists.findIndex((n) => n.t === incumbent);
+    const centerIdx = incIdx < 0 || dists[nearest].d < dists[incIdx].d - margin ? nearest : incIdx;
+    // ③ 目标清单 = 中心、列表前一张、后一张，然后**按「离锚点更近那一侧优先」一层层往外扩**，
+    //    直到凑够 maxSlots。⭐ 2026-10-06 晚皇上旨「一次能够展示 8 个全景纹理」⇒ maxSlots 由 4 变 8，
+    //    此处从「只扩一层」改成「一层层扩下去」。扩的**顺序**沿用当日那句「更近那侧再往外一张」：
+    //    k=2 那一轮先取更近那侧 ⇒ 前 4 张与 4 槽时代**逐字相同**（中心、-1、+1、更近那侧的 ±2），
+    //    多出来的 4 张继续 ±3、±4…
+    //    ⭐ 2026-10-07 旨「尽可能得填满 8 个全景位置」⇒ 越界的那个**序号**直接跳过、**不占一格**，
+    //    外扩继续往还有货的那一侧走（旧写法把 `undefined` 也塞进清单去占槽 ⇒ 10 个点、中心贴列表首端时
+    //    只填 5 格，剩下 5 张全景明明存在却进不了 shader）。清单里只装真实存在的全景
+    //    ⇒ 填几格 = **min(项目全景总数, maxSlots)**，只有人不够时才留空（⛔ 不复制一张来凑数）。
+    const at = (i) => (i >= 0 && i < dists.length ? dists[i].t : undefined);
+    const lo = centerIdx - 1;
+    const hi = centerIdx + 1;
+    const dLo = lo >= 0 && lo < dists.length ? dists[lo].d : Infinity;
+    const dHi = hi >= 0 && hi < dists.length ? dists[hi].d : Infinity;
+    const nearSign = dLo <= dHi ? -1 : 1; // 更近那侧：-1 = 往前（序号更小），+1 = 往后；平手归序号小的那侧
+    const targets = [];
+    const push = (i) => {
+        if (targets.length >= maxSlots)
+            return;
+        const t = at(i);
+        if (t !== undefined)
+            targets.push(t);
+    };
+    push(centerIdx);
+    push(lo);
+    push(hi);
+    // k 超过列表长度 ⇒ 两侧都再也请不到人，循环自然停（⛔ 别写成「直到填满」的无界循环）
+    for (let k = 2; targets.length < maxSlots && k <= dists.length; k++) {
+        push(centerIdx + nearSign * k);
+        push(centerIdx - nearSign * k);
+    }
+    const used = new Set();
+    used.add(targets[0]);
+    // ④ ⭐ 中心没换人（10-02 当日亲择「维持整组」）⇒ 在册的人**一格都不动**，只把空格补上
+    //    （10-07 那道旨的后半句）：他一张一张加全景时，新增那张立刻进得了 shader，不用等中心换人；
+    //    删掉一张留下的那格也当场补。已有格子一字节都不重绑 ⇒ 没有任何换人/重传代价。
+    if (incIdx >= 0 && centerIdx === incIdx) {
+        const kept = next.slice();
+        kept[0] = targets[0];
+        for (const x of kept)
+            if (x !== undefined)
+                used.add(x);
+        for (const t of targets) {
+            if (used.has(t))
+                continue;
+            const hole = kept.indexOf(undefined);
+            if (hole < 1)
+                break; // -1 = 没有空格；0 = 0 号槽恒归中心（这里不可能发生，兜住）
+            kept[hole] = t;
+            used.add(t);
+        }
+        return kept;
+    }
+    // ⑤ 中心换人 ⇒ 整组按**新中心**的序号清单重算，但「仍在清单里的人留在原格」
+    //    ⇒ 中心挪一格时只有必要的格重绑瓦片。0 号槽恒 = 中心（立方体 `vPanoIndex` 恒 0，它显示的就是这一格）。
+    const placed = new Array(maxSlots).fill(undefined);
+    placed[0] = targets[0];
+    const keepable = (x) => x !== undefined && targets.indexOf(x) >= 0 && !used.has(x);
+    for (let s = 1; s < maxSlots; s++) {
+        if (keepable(next[s])) {
+            placed[s] = next[s];
+            used.add(next[s]);
+        }
+    }
+    for (let s = 1; s < maxSlots; s++) {
+        if (placed[s] !== undefined)
+            continue;
+        const fresh = targets.find((x) => !used.has(x));
+        // 清单里的人全请完了还空 ⇒ 项目里的全景本来就不够一格一人（总数 < maxSlots），这一格留空
+        if (fresh === undefined)
+            continue;
+        placed[s] = fresh;
+        used.add(fresh);
+    }
+    return placed;
+}