three-base 2.0.180 → 2.0.187

package/MktMesh/MktMesh.ts

@@ -16,7 +16,7 @@
  *     `panoSlotRoster.ts`；皇上旨 2026-10-03 起预览/发布与编辑器共用同一份算法 ⇒ 两边装同一批全景）。
  *     ⭐ 皇上旨 2026-10-07 第二十一道旨：锚点 = 外部控制器的中心点（`setRosterCenter` 注入），没注入才回落相机位置；
  *     中心变化或名册里有空格被补上人时加载新瓦片 → 设置 shader 的 8 个全景槽 panorama + textureMatrix；
- *  4. exportData / importData 支持导入导出（墙点位 + 纹理数组）。
+ *  4. exportData / importData 支持导入导出（墙点位 + 纹理数组 + ⭐ 10-26 旨起的平面图 / 模型两层）。
  *  5. ⚠️ 铁律：激活纹理（墙面上正在绘制的全景）的旋转/位置变化，必须立即同步到
  *     shader 的 textureMatrix uniform（见 setTexture），否则平面纹理不跟着全景球转。
  *
@@ -39,6 +39,7 @@ import {
     SRGBColorSpace,
     Texture,
     Vector3,
+    Vector4,
 } from "three";
 import type { WebGLRenderer } from "three";
 import { createPlaceholderTexture, isPanoTexMode, mktPanoTiledFlag, mktPanoTexUrls, isRtStitchKey, rtStitchKeyParts, RT_STITCH_KEY_PREFIX, RT_STITCH_SLOT_COUNT, type PanoTexMode } from "./mktShader";
@@ -64,6 +65,12 @@ import { subdivideCapTriangles, WALL_CAP_MAX_EDGE_M } from "./wallCapTessellate"
 // ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」：
 //    导出时剥域名（`exportData`）、导入时补回来（`importData`）——**各只有这一处**，⛔ 不许在别处另剥/另补。
 import { stripAssetHost, absAssetUrl } from "./assetUrl";
+// ⭐ 皇上旨 2026-10-26「按这个方案，把图片平面和模型一起搬进库里」：这两层（含每帧喂瓦片那条编排）
+//    原先各住在本站两个渲染器里一份 ⇒ 下游直接用包里的 `MktMesh` 时，存档里的 `images`/`models` 两键没人读。
+//    入库之后它们挂在 `MktMesh` **自己的子树**下，与墙同一棵变换 ⇒ 预览那三根 transform 滑杆搬得动整份展品。
+import { ImagePlane, type ImagePlaneData } from "./imagePlane";
+import { ModelSlot, type ModelSlotData } from "./modelSlot";
+import { ImagePlaneTileLoader } from "./imageTileLoader";
 
 export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
@@ -197,6 +204,33 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     // 复用临时对象（避免每帧 new，降低 GC 压力）
     private _tmpV3: Vector3 = new Vector3();
 
+    /**
+     * 图片平面层（⭐ 10-26 旨入库）：对象挂在**本 MktMesh 的子树**里，⛔ 不是场景根
+     * ⇒ 移动/旋转/缩放这个展品时，墙 + 全景 + 平面图 + 模型一起走。
+     */
+    imagePlanes: ImagePlane[] = [];
+    /** 模型槽层（同一棵子树，口径同上） */
+    models: ModelSlot[] = [];
+    /**
+     * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
+     * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不会再空一格；只随本对象 `dispose()` 释放。
+     */
+    private _imgTileLoader = new ImagePlaneTileLoader();
+    /**
+     * 逐帧绑定用的两张账（2026-10-26 定的方案：地址一次性全部丢给下载，绑材质改成「一帧一颗平面」）。
+     * 全局 rAF 每拍只跑一项 `addWork`，而 `addWork` 按闭包引用判重 ⇒ 每次现造的新闭包它判不出来，
+     * ⛔ 去重闸门必须像全景上传那张 `_uploadQueued` 一样自备。
+     */
+    private _imgBindQueued = new Set<ImagePlane>();
+    /** 平面 → 「它 4 条地址全部落定（就绪或失败）时的那串地址」⇒ 地址不换就不再重排；上传换图会改这串 ⇒ 自动重排 */
+    private _imgBindDone = new Map<ImagePlane, string>();
+    /**
+     * 模型槽「GLB 已取回、等这一帧把它挂进父元素」的在册表 —— 与上面图片绑定同一手法（用户 10-26 需求：
+     * 一次性全部拿去加载，用 `threeUtils.addWork` 逐帧加到场景里）。整层十几个槽同时到货时，
+     * 一帧只有一颗进 `_contentRoot`（进图那一拍要重算包围盒 + 排布 + 首次把几何送上 GPU）。
+     */
+    private _modelMountQueued = new Set<ModelSlot>();
+
     constructor(opts: { wallHeight?: number; wallClosed?: boolean } = {}) {
         // 发布/预览态墙：**固定**用「全景序号直取」着色器（皇上旨 2026-09-29：mktmesh 就只有按照 attribute
         // 配置来显示全景这一种固定的 shader——每帧由 feedFaceMapping 按 panoFaceMapping 把被引用的全景
@@ -1035,6 +1069,167 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         this.projectName = typeof name === "string" ? name : "";
     }
 
+    // ───────────── 平面图 / 模型两层（⭐ 皇上旨 2026-10-26「把图片平面和模型一起搬进库里」） ─────────────
+
+    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 + 起排它自己的逐帧绑定 */
+    addImagePlane(ip: ImagePlane): ImagePlane {
+        this.imagePlanes.push(ip);
+        this.add(ip);
+        this._queueImagePlaneBind(ip);
+        return ip;
+    }
+
+    /** 摘掉一颗并释放它自己的几何/材质；那 4 张瓦片纹理归 `_imgTileLoader` 管 ⇒ ⛔ 不在这里 dispose */
+    removeImagePlane(ip: ImagePlane): void {
+        const i = this.imagePlanes.indexOf(ip);
+        if (i >= 0) this.imagePlanes.splice(i, 1);
+        this._imgBindQueued.delete(ip);
+        this._imgBindDone.delete(ip);
+        this.remove(ip);
+        ip.dispose();
+    }
+
+    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用） */
+    addModel(ms: ModelSlot): ModelSlot {
+        this.models.push(ms);
+        this.add(ms);
+        return ms;
+    }
+
+    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾；排在后头的挂载帧靠「不在册」早退） */
+    removeModel(ms: ModelSlot): void {
+        const i = this.models.indexOf(ms);
+        if (i >= 0) this.models.splice(i, 1);
+        this._modelMountQueued.delete(ms);
+        this.remove(ms);
+        ms.dispose();
+    }
+
+    /**
+     * 整层重建图片平面（`importData` 与预览那一路）。
+     * ⚠️ 进来的地址必须是**已补回域名**的绝对形态：补域名只有 `importData` 那一处（与 `textures` 同一把 `assetUrl` 尺），
+     *   ⛔ 本方法里不许再补一遍，也⛔ 不许在调用方各自补。
+     */
+    setImagePlanes(datas: ImagePlaneData[]): void {
+        this._imgBindQueued.clear();
+        this._imgBindDone.clear();
+        for (const ip of this.imagePlanes) {
+            this.remove(ip);
+            ip.dispose();
+        }
+        this.imagePlanes = [];
+        for (const d of datas) {
+            const ip = new ImagePlane(d.name);
+            ip.applyData(d);
+            this.imagePlanes.push(ip);
+            this.add(ip);
+        }
+        // 整层重建完立刻起排：地址一次性全交给下载、绑材质逐帧一记 ⇒ 宿主不驱动这一层也长得出来
+        this.feedImagePlaneTiles();
+    }
+
+    /**
+     * 整层重建模型槽（`importData` 与预览那一路），地址口径的要求同 `setImagePlanes`。
+     * ⚠️ GLB 逐只**异步取、不 await**（十几只串一条队会把载入卡死），每只落地那一刻各回调一次 `onEachLoad`：
+     *   预览每帧真画 ⇒ 不传；编辑器是按需渲染 ⇒ 传一个「标脏」的钩子，否则模型挂上来屏幕不动。
+     * 2026-10-26 决定：取回与「挂进父元素」分两拍 —— 地址一次性全交给下载（网络 + 解析不占渲染帧），
+     *   真正进场景图那一步交给 `threeUtils.addWork` ⇒ 全局 rAF 每拍只跑一项 = **一帧只挂一颗槽**
+     *   （挂载那一拍要重算包围盒 + 排布 + 首次把整棵子树的几何送上 GPU，十几颗挤在同一帧就是他要拆掉的那一卡）。
+     */
+    setModels(datas: ModelSlotData[], onEachLoad?: () => void): void {
+        this._modelMountQueued.clear();
+        for (const ms of this.models) {
+            this.remove(ms);
+            ms.dispose();
+        }
+        this.models = [];
+        for (const d of datas) {
+            const ms = new ModelSlot(d.name);
+            ms.applyData(d);
+            this.models.push(ms);
+            this.add(ms); // 槽本体（占位小立方体）当场进图 ⇒ GLB 在路上时这一槽不凭空消失
+            if (d.url) void ms.loadModel(d.url).then(() => this._queueModelMount(ms, onEachLoad));
+        }
+    }
+
+    /** 把「备好待挂」的那一槽交给全局队列；⛔ 去重闸门自备（`addWork` 按闭包引用判重，新闭包它判不出来） */
+    private _queueModelMount(ms: ModelSlot, onEachLoad?: () => void): void {
+        if (this._modelMountQueued.has(ms)) return;
+        this._modelMountQueued.add(ms);
+        threeUtils.addWork(() => {});
+        threeUtils.addWork(() => this._mountModelStep(ms, onEachLoad));
+    }
+
+    /** 全局队列里的那一帧：只挂这一槽，挂好才回调（`onEachLoad` = 按需渲染宿主的标脏钩子） */
+    private _mountModelStep(ms: ModelSlot, onEachLoad?: () => void): void {
+        this._modelMountQueued.delete(ms);
+        // 槽已退场（换项目 / 删除）：待挂那棵由 `ModelSlot.dispose` → `_detachModel` 当场释放，这里不挂
+        if (!this.models.includes(ms)) return;
+        if (ms.mountStaged() && onEachLoad) onEachLoad();
+    }
+
+    /**
+     * 把各颗平面那 4 张瓦片的纹理绑进材质（10-22 晚定的口径：不走拼合器 RT）。
+     * 2026-10-26 决定改成**逐帧**：一次把整层地址全丢给下载器（下载/解码在网络与工作线程侧，不占这一帧），
+     * 真正写 uniform 的那一步交给 `threeUtils.addWork` —— 全局 rAF 每拍只跑一项 ⇒ 一帧只绑一颗平面，
+     * 一整层平面的纹理上传被摊到多帧，不再挤在同一记调用里（旧写法一记 `feed` 就把所有平面全绑完）。
+     * ⛔ 不进 `onBeforeRender` 自驱；持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次只是「补排漏网的平面」，
+     * 而整层重建（`setImagePlanes`）末尾自己起排 ⇒ 只调 `importData(整串)` 的宿主不必自己驱动也会长出来。
+     * 还没下载完/缺格的那一格绑 null ⇒ 片元那一格整格 discard，不落像素（用户 10-26 连收两条：先「不要默认图」，
+     * 再「不是显示灰色, 而是直接 discard 丢弃」）。
+     */
+    feedImagePlaneTiles(): void {
+        for (const ip of this.imagePlanes) this._queueImagePlaneBind(ip);
+    }
+
+    /** 一颗平面排一帧的绑定工作：先把它那 4 条地址**一次性全部**交给下载器，再把「写材质」排进全局队列。 */
+    private _queueImagePlaneBind(ip: ImagePlane): void {
+        const tiles = ip.tiles;
+        const sig = (tiles ?? []).join("|");
+        // 两道闸：已排在队里 = 不重复排；这串地址已经落定过 = 不再动它（换图会改这串 ⇒ 自然会重排）
+        if (this._imgBindQueued.has(ip) || this._imgBindDone.get(ip) === sig) return;
+        const zero = new Vector4(0, 0, 1, 1);
+        // ⛔ 旧存档 16 条地址（> 满批 4）直接不收 ⇒ 整张不落像素（四格全 discard），按 10-20 口径重传即可；空 tiles 同样
+        if (!tiles || tiles.length !== 4) {
+            ip.setTileTextures([null, null, null, null], [zero, zero.clone(), zero.clone(), zero.clone()]);
+            this._imgBindDone.set(ip, sig);
+            return;
+        }
+        for (const url of tiles) this._imgTileLoader.preload(url); // ① 一次性全部拿去加载
+        this._imgBindQueued.add(ip);
+        threeUtils.addWork(() => {}); // 占一格（什么都不干），把下面那一项推到下一个 tick —— 与全景上传同一手法
+        threeUtils.addWork(() => this._bindImagePlaneStep(ip, sig));
+    }
+
+    /** 队列里的一格：只绑**这一颗**平面里已就绪的那几格；还有在途的就重新排队，⛔ 不在这里等、也⛔ 不顺手把别的平面一起做完。 */
+    private _bindImagePlaneStep(ip: ImagePlane, sig: string): void {
+        this._imgBindQueued.delete(ip);
+        if (!this.imagePlanes.includes(ip)) return; // 已摘掉（删平面 / 切项目整层重建）⇒ 这一格什么都不做
+        const tiles = ip.tiles;
+        if ((tiles ?? []).join("|") !== sig) return; // 地址中途换了 ⇒ 下一记 feed 按新拼串重排
+        const zero = new Vector4(0, 0, 1, 1);
+        const texs: (Texture | null)[] = [null, null, null, null];
+        const insets: Vector4[] = [zero.clone(), zero.clone(), zero.clone(), zero.clone()];
+        let pending = false;
+        for (let i = 0; i < 4; i++) {
+            const url = tiles[i];
+            if (!url) continue;
+            const e = this._imgTileLoader.get(url);
+            if (e && e.tex) {
+                texs[i] = e.tex;
+                insets[i] = this._imgTileLoader.inset(e, i);
+            } else if (this._imgTileLoader.isPending(url)) {
+                pending = true; // 还在下载/解码 ⇒ 这一格先绑已到的，剩下的下一拍再看
+            }
+        }
+        ip.setTileTextures(texs, insets);
+        if (pending) {
+            this._queueImagePlaneBind(ip);
+            return;
+        }
+        this._imgBindDone.set(ip, sig); // 全部落定（含下载失败那格：它留 null，那一格就永久 discard）
+    }
+
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName?: string): MktMeshData {
@@ -1057,12 +1252,30 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
                 tiles: (t.tiles && t.tiles.length ? t.tiles.map((u) => stripAssetHost(u, pn)) : []) as string[],
                 matrix: t.matrix.toArray(),
             })),
+            // ⭐ 10-26 旨入库：这两层的地址与 `textures` 共用上面那一条剥域名口径（⛔ 不是另起一把尺），
+            //   其余字段（位置/旋转/宽高/瓦片数/落点面/原始包围盒）由各自的 `toData()` 逐字存。
+            images: this.imagePlanes.map((ip) => {
+                const d = ip.toData();
+                return {
+                    ...d,
+                    url: d.url ? stripAssetHost(d.url, pn) : "",
+                    tiles: d.tiles.length ? d.tiles.map((u) => stripAssetHost(u, pn)) : [],
+                };
+            }),
+            models: this.models.map((ms) => {
+                const d = ms.toData();
+                return { ...d, url: d.url ? stripAssetHost(d.url, pn) : "" };
+            }),
         };
     }
 
     /** 导入数据：重建墙体几何与纹理列表，并激活第一个纹理
-     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址 */
-    importData(data: MktMeshData, projName?: string): void {
+     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址
+     *  @param onModelLoad 每只 GLB 落地时回调一次（可选）——按需渲染的宿主（编辑器）拿它标脏；每帧真画的预览不传 */
+    importData(data: MktMeshData, projName?: string, onModelLoad?: () => void): void {
+        // ⭐ 10-08 旨的「补回域名」那颗项目名，10-26 旨之后全景/平面图/模型**三层共用同一个**（原来在 textures 的
+        //   map 里就地取，下面那两层也要用 ⇒ 提到方法开头，⛔ 不是第二处口径）。
+        const pn = typeof projName === "string" && projName ? projName : this.projectName;
         this.setWallPoints(data.wallPoints ?? [], {
             closed: data.wallClosed,
             height: data.wallHeight,
@@ -1078,7 +1291,6 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
                 //     （`/three-base_upload/…`）不必重存也能正常加载，不会被拼成 `https://host/https://host/…`
                 //   · 19:53 旨后还要把 `{项目名}/x_0.jpg` **还原**成真身 OSS 地址（顶掉的上传目录要补回来），
                 //     否则 json 里的地址指不回原图（图片裂）。`pn` 取入参、回落 `setProjectName` 注入的那个。
-                const pn = typeof projName === "string" && projName ? projName : this.projectName;
                 const urlAbs = absAssetUrl(t.url as string, pn);
                 return {
                     url: urlAbs,
@@ -1102,11 +1314,25 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             for (let f = 0; f < restore; f++) this.panoFaceMapping[f] = imported[f];
             this.rebuildPanoIndexAttribute();
         }
+        // ⭐ 10-26 旨「把图片平面和模型一起搬进库里」的另一半：这两层也从**同一份 JSON** 里读，
+        //   地址在这一处补回域名（与上面 textures 同一条尺）⇒ 下游只调 `importData(整串)` 就全画出来。
+        //   旧存档没有这两个键 ⇒ 空数组 = 整层清空，与「墙 + 全景」那套逐字同口径。
+        this.setImagePlanes(
+            (data.images ?? []).map((d) => ({
+                ...d,
+                url: d.url ? absAssetUrl(d.url, pn) : "",
+                tiles: (d.tiles ?? []).map((u) => absAssetUrl(u, pn)),
+            }))
+        );
+        this.setModels(
+            (data.models ?? []).map((d) => ({ ...d, url: d.url ? absAssetUrl(d.url, pn) : "" })),
+            onModelLoad
+        );
     }
 
     // ───────────────────────── 释放 ─────────────────────────
 
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、几何、材质 */
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
     dispose(): this {
         // ⚠️ rt 虚拟键从不进 `_texCache`（拼合槽纹理由 `_stitcher` 自己持有并释放），这里清的都是本类下载的 Texture。
         // ⭐ 甲（2026-10-05）：`releasePanoTexture` 除 `dispose()` 外还要 `ImageBitmap.close()` —— 位图的原生内存
@@ -1116,6 +1342,22 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         this._texUploaded = new WeakSet(); // WeakSet 无 clear ⇒ 整只换掉
         this._uploadQueued.clear(); // 排队项即便回调仍触发，也会因 `!this._uploadQueued.delete(tex)` 早退
         this._ossSizeDepKeys.clear();
+        // ⭐ 10-26 旨入库的两层：子对象逐个 dispose，平面那 4 张瓦片的缓存**只在这里**整批清
+        //   （与上面 `_texCache` 同一条旨 ⇒ 切工程不重建这一份、也就不会再空出一格）。
+        for (const ip of this.imagePlanes) {
+            this.remove(ip);
+            ip.dispose();
+        }
+        this.imagePlanes = [];
+        for (const ms of this.models) {
+            this.remove(ms);
+            ms.dispose();
+        }
+        this.models = [];
+        this._imgTileLoader.clear();
+        this._imgBindQueued.clear();
+        this._imgBindDone.clear();
+        this._modelMountQueued.clear();
         this._stitcher.dispose();
         this._glRenderer = null;
         if (this._placeholder) this._placeholder.dispose();

package/MktMesh/imagePlane.d.ts

@@ -46,8 +46,11 @@ export declare class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
     get url(): string;
     get naturalW(): number | undefined;
     get naturalH(): number | undefined;
-    /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 显示灰）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
+    /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 那一片整格 discard，不落像素）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
     setTileTextures(texs: (Texture | null)[], insets: Vector4[]): void;
+    /** 只读「此刻材质里绑了什么」的戳记：4 格就绪位 + 已绑纹理的版本号。
+     *  按需渲染的宿主拿它比对画面：逐帧绑定只写 uniform 值，⛔ 不动 `material.version`、也不动几何 ⇒ 场景指纹看不见这一变。 */
+    tilesBindingStamp(): string;
     highlight(): void;
     restoreColor(): void;
     toData(): ImagePlaneData;

package/MktMesh/imagePlane.js

@@ -11,7 +11,9 @@
  * - 几何 PlaneGeometry(width, height)，原点在平面中心；position.y 由调用者设定（通常 height/2 让底部落地）。
  * - ⭐ 2026-10-22 晚旨：纹理**不走拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，片元按 UV 象限选片 +
  *   用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。材质用 onBeforeCompile 打补丁，
- *   注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片显示灰、逐张就绪逐张显影。
+ *   注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片整格 `discard`（一片像素都不落），逐张就绪逐张显影。
+ *   （⭐ 2026-10-26 用户先要默认图、当晚收回改要灰，同一晚再收：「平面图的图片还没有加载出来的时候, 不是显示灰色,
+ *     而是直接 discrad 丢弃」⇒ 默认图与缺图灰两条都已删，没就绪就是透明没有。）
  * - UV 标准 [0,1]²（PlaneGeometry 自带），4 张瓦片按 2×2 象限铺满 ⇒ 不需要投影 shader，也不需要离屏 RT。
  */
 import { Color, DataTexture, FrontSide, Mesh, MeshBasicMaterial, PlaneGeometry, RGBAFormat, Vector4, } from "three";
@@ -35,21 +37,25 @@ const ZERO_INSET = new Vector4(0, 0, 1, 1);
  */
 export const IMAGE_PLANE_EDGE_CLIP_UV = 0.004;
 const EDGE_MAX_UV = 1 - IMAGE_PLANE_EDGE_CLIP_UV;
-/** 片元打补丁：4 张瓦片按 UV 象限选片，缺图那片显示灰（与旧缺失灰同一观感）。索引用字面量 0..3 ⇒ GLSL ES 1.00 合法。 */
+/** 片元打补丁：4 张瓦片按 UV 象限选片；⭐ 2026-10-26 用户决定「图片还没有加载出来的时候, 不是显示灰色, 而是直接 discrad 丢弃」
+ *  ⇒ 这一格没就绪就 `discard`（一片像素都不落，透过去看到的是平面背后的东西），⛔ 不铺灰、⛔ 不画默认图。
+ *  索引用字面量 0..3 ⇒ GLSL ES 1.00 合法。 */
 const IMG_PLANE_MAP_FRAG = `
     if ( vUv.x < ${IMAGE_PLANE_EDGE_CLIP_UV} || vUv.x > ${EDGE_MAX_UV} || vUv.y < ${IMAGE_PLANE_EDGE_CLIP_UV} || vUv.y > ${EDGE_MAX_UV} ) discard;
-    vec4 imgTexel = vec4(0.8, 0.8, 0.8, 1.0); // 缺图灰
+    vec4 imgTexel;
+    bool ready = false;
     vec2 cell = floor(vUv * 2.0);
     vec2 local = fract(vUv * 2.0);
     if (cell.y >= 0.5 && cell.x < 0.5) {
-        if (uValid[0] > 0.5) { vec4 ins = uInset[0]; imgTexel = texture2D(uTiles[0], mix(ins.xy, ins.zw, local)); }
+        if (uValid[0] > 0.5) { vec4 ins = uInset[0]; imgTexel = texture2D(uTiles[0], mix(ins.xy, ins.zw, local)); ready = true; }
     } else if (cell.y >= 0.5 && cell.x >= 0.5) {
-        if (uValid[1] > 0.5) { vec4 ins = uInset[1]; imgTexel = texture2D(uTiles[1], mix(ins.xy, ins.zw, local)); }
+        if (uValid[1] > 0.5) { vec4 ins = uInset[1]; imgTexel = texture2D(uTiles[1], mix(ins.xy, ins.zw, local)); ready = true; }
     } else if (cell.y < 0.5 && cell.x < 0.5) {
-        if (uValid[2] > 0.5) { vec4 ins = uInset[2]; imgTexel = texture2D(uTiles[2], mix(ins.xy, ins.zw, local)); }
+        if (uValid[2] > 0.5) { vec4 ins = uInset[2]; imgTexel = texture2D(uTiles[2], mix(ins.xy, ins.zw, local)); ready = true; }
     } else {
-        if (uValid[3] > 0.5) { vec4 ins = uInset[3]; imgTexel = texture2D(uTiles[3], mix(ins.xy, ins.zw, local)); }
+        if (uValid[3] > 0.5) { vec4 ins = uInset[3]; imgTexel = texture2D(uTiles[3], mix(ins.xy, ins.zw, local)); ready = true; }
     }
+    if (!ready) discard;
     diffuseColor *= imgTexel;
 `;
 const DEFAULT_WIDTH = 2;
@@ -78,7 +84,7 @@ export class ImagePlane extends Mesh {
         });
         // ⭐ 2026-10-22 晚旨：图片平面**不用拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，
         //   片元按 UV 象限选片 + 用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。
-        //   材质打补丁（onBeforeCompile）注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片显示灰。
+        //   材质打补丁（onBeforeCompile）注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片整格 discard。
         mat.defines = { USE_UV: "" };
         const uTiles = { value: [PLACEHOLDER_TEX, PLACEHOLDER_TEX, PLACEHOLDER_TEX, PLACEHOLDER_TEX] };
         const uInset = { value: [ZERO_INSET.clone(), ZERO_INSET.clone(), ZERO_INSET.clone(), ZERO_INSET.clone()] };
@@ -113,7 +119,7 @@ export class ImagePlane extends Mesh {
     get url() { return this._data.url; }
     get naturalW() { return this._data.naturalW; }
     get naturalH() { return this._data.naturalH; }
-    /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 显示灰）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
+    /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 那一片整格 discard，不落像素）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
     setTileTextures(texs, insets) {
         for (let i = 0; i < 4; i++) {
             const t = texs[i] || null;
@@ -123,6 +129,16 @@ export class ImagePlane extends Mesh {
             this._uValid.value[i] = t ? 1 : 0;
         }
     }
+    /** 只读「此刻材质里绑了什么」的戳记：4 格就绪位 + 已绑纹理的版本号。
+     *  按需渲染的宿主拿它比对画面：逐帧绑定只写 uniform 值，⛔ 不动 `material.version`、也不动几何 ⇒ 场景指纹看不见这一变。 */
+    tilesBindingStamp() {
+        let s = "";
+        for (let i = 0; i < 4; i++) {
+            const t = this._uTiles.value[i];
+            s += this._uValid.value[i] ? `1@${t ? t.version : -1},` : "0,";
+        }
+        return s;
+    }
     highlight() {
         this.material.color.set(HIGHLIGHT_COLOR);
     }

package/MktMesh/imagePlane.ts

@@ -11,7 +11,9 @@
  * - 几何 PlaneGeometry(width, height)，原点在平面中心；position.y 由调用者设定（通常 height/2 让底部落地）。
  * - ⭐ 2026-10-22 晚旨：纹理**不走拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，片元按 UV 象限选片 +
  *   用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。材质用 onBeforeCompile 打补丁，
- *   注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片显示灰、逐张就绪逐张显影。
+ *   注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片整格 `discard`（一片像素都不落），逐张就绪逐张显影。
+ *   （⭐ 2026-10-26 用户先要默认图、当晚收回改要灰，同一晚再收：「平面图的图片还没有加载出来的时候, 不是显示灰色,
+ *     而是直接 discrad 丢弃」⇒ 默认图与缺图灰两条都已删，没就绪就是透明没有。）
  * - UV 标准 [0,1]²（PlaneGeometry 自带），4 张瓦片按 2×2 象限铺满 ⇒ 不需要投影 shader，也不需要离屏 RT。
  */
 import {
@@ -48,21 +50,25 @@ const ZERO_INSET = new Vector4(0, 0, 1, 1);
 export const IMAGE_PLANE_EDGE_CLIP_UV = 0.004;
 const EDGE_MAX_UV = 1 - IMAGE_PLANE_EDGE_CLIP_UV;
 
-/** 片元打补丁：4 张瓦片按 UV 象限选片，缺图那片显示灰（与旧缺失灰同一观感）。索引用字面量 0..3 ⇒ GLSL ES 1.00 合法。 */
+/** 片元打补丁：4 张瓦片按 UV 象限选片；⭐ 2026-10-26 用户决定「图片还没有加载出来的时候, 不是显示灰色, 而是直接 discrad 丢弃」
+ *  ⇒ 这一格没就绪就 `discard`（一片像素都不落，透过去看到的是平面背后的东西），⛔ 不铺灰、⛔ 不画默认图。
+ *  索引用字面量 0..3 ⇒ GLSL ES 1.00 合法。 */
 const IMG_PLANE_MAP_FRAG = `
     if ( vUv.x < ${IMAGE_PLANE_EDGE_CLIP_UV} || vUv.x > ${EDGE_MAX_UV} || vUv.y < ${IMAGE_PLANE_EDGE_CLIP_UV} || vUv.y > ${EDGE_MAX_UV} ) discard;
-    vec4 imgTexel = vec4(0.8, 0.8, 0.8, 1.0); // 缺图灰
+    vec4 imgTexel;
+    bool ready = false;
     vec2 cell = floor(vUv * 2.0);
     vec2 local = fract(vUv * 2.0);
     if (cell.y >= 0.5 && cell.x < 0.5) {
-        if (uValid[0] > 0.5) { vec4 ins = uInset[0]; imgTexel = texture2D(uTiles[0], mix(ins.xy, ins.zw, local)); }
+        if (uValid[0] > 0.5) { vec4 ins = uInset[0]; imgTexel = texture2D(uTiles[0], mix(ins.xy, ins.zw, local)); ready = true; }
     } else if (cell.y >= 0.5 && cell.x >= 0.5) {
-        if (uValid[1] > 0.5) { vec4 ins = uInset[1]; imgTexel = texture2D(uTiles[1], mix(ins.xy, ins.zw, local)); }
+        if (uValid[1] > 0.5) { vec4 ins = uInset[1]; imgTexel = texture2D(uTiles[1], mix(ins.xy, ins.zw, local)); ready = true; }
     } else if (cell.y < 0.5 && cell.x < 0.5) {
-        if (uValid[2] > 0.5) { vec4 ins = uInset[2]; imgTexel = texture2D(uTiles[2], mix(ins.xy, ins.zw, local)); }
+        if (uValid[2] > 0.5) { vec4 ins = uInset[2]; imgTexel = texture2D(uTiles[2], mix(ins.xy, ins.zw, local)); ready = true; }
     } else {
-        if (uValid[3] > 0.5) { vec4 ins = uInset[3]; imgTexel = texture2D(uTiles[3], mix(ins.xy, ins.zw, local)); }
+        if (uValid[3] > 0.5) { vec4 ins = uInset[3]; imgTexel = texture2D(uTiles[3], mix(ins.xy, ins.zw, local)); ready = true; }
     }
+    if (!ready) discard;
     diffuseColor *= imgTexel;
 `;
 
@@ -111,7 +117,7 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
         });
         // ⭐ 2026-10-22 晚旨：图片平面**不用拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，
         //   片元按 UV 象限选片 + 用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。
-        //   材质打补丁（onBeforeCompile）注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片显示灰。
+        //   材质打补丁（onBeforeCompile）注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片整格 discard。
         mat.defines = { USE_UV: "" };
         const uTiles = { value: [PLACEHOLDER_TEX, PLACEHOLDER_TEX, PLACEHOLDER_TEX, PLACEHOLDER_TEX] as Texture[] };
         const uInset = { value: [ZERO_INSET.clone(), ZERO_INSET.clone(), ZERO_INSET.clone(), ZERO_INSET.clone()] };
@@ -154,7 +160,7 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
     get naturalW(): number | undefined { return this._data.naturalW; }
     get naturalH(): number | undefined { return this._data.naturalH; }
 
-    /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 显示灰）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
+    /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 那一片整格 discard，不落像素）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
     setTileTextures(texs: (Texture | null)[], insets: Vector4[]): void {
         for (let i = 0; i < 4; i++) {
             const t = texs[i] || null;
@@ -164,6 +170,17 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
         }
     }
 
+    /** 只读「此刻材质里绑了什么」的戳记：4 格就绪位 + 已绑纹理的版本号。
+     *  按需渲染的宿主拿它比对画面：逐帧绑定只写 uniform 值，⛔ 不动 `material.version`、也不动几何 ⇒ 场景指纹看不见这一变。 */
+    tilesBindingStamp(): string {
+        let s = "";
+        for (let i = 0; i < 4; i++) {
+            const t = this._uTiles.value[i];
+            s += this._uValid.value[i] ? `1@${t ? t.version : -1},` : "0,";
+        }
+        return s;
+    }
+
     highlight(): void {
         this.material.color.set(HIGHLIGHT_COLOR);
     }

package/MktMesh/imageTileLoader.d.ts

@@ -11,6 +11,8 @@ export declare class ImagePlaneTileLoader {
     preload(url: string): void;
     /** 取已就绪的瓦片（未就绪返回 null） */
     get(url: string): TileEntry | null;
+    /** 这张是否还在下载/解码途中。既不在缓存又不在途 ⇒ 要么没发起、要么已经失败（调用方据此决定「再排一帧等」还是「就此收工」） */
+    isPending(url: string): boolean;
     /** 第 i 片（行优先、图像左上起）的采样窗口；瓦片未就绪时返回整张 [0,0,1,1] */
     inset(entry: TileEntry, i: number): Vector4;
     /** 释放本 loader 持有的全部瓦片纹理（项目重置 / 卸载场景时调用；⛔ 不关共享占位纹理） */

package/MktMesh/imageTileLoader.js

@@ -9,7 +9,7 @@
  *   与全景同一套上下翻约定）；本类只补 `colorSpace = SRGBColorSpace`（硬件采样即解 sRGB→linear，与旧 RT 方案逐字节同口径）。
  * - inset 用库的 `rtStitchTileInset(i, tw, th, IMAGE_TILE_GRID)`：上传多切 8px、采样只取中间干净块 ⇒ 接缝不回潮，
  *   与上传切片 `rtStitchTileRects` 共用同一份几何（⛔ 不许在这里另算一份）。
- * - 逐张就绪、逐张显影：未就绪那张 `get()` 返回 null ⇒ 调方把那片传 null（材质显示灰），下一帧就绪后即亮。
+ * - 逐张就绪、逐张显影：未就绪那张 `get()` 返回 null ⇒ 调方把那片传 null（材质那一格整格 discard，不落像素），下一帧就绪后即亮。
  */
 import { SRGBColorSpace, Vector4 } from "three";
 import { loadPanoTexture, releasePanoTexture } from "./panoBitmapTexture";
@@ -39,6 +39,10 @@ export class ImagePlaneTileLoader {
     get(url) {
         return this.cache.get(url) || null;
     }
+    /** 这张是否还在下载/解码途中。既不在缓存又不在途 ⇒ 要么没发起、要么已经失败（调用方据此决定「再排一帧等」还是「就此收工」） */
+    isPending(url) {
+        return this.inflight.has(url);
+    }
     /** 第 i 片（行优先、图像左上起）的采样窗口；瓦片未就绪时返回整张 [0,0,1,1] */
     inset(entry, i) {
         if (!entry.w || !entry.h)

package/MktMesh/imageTileLoader.ts

@@ -9,7 +9,7 @@
  *   与全景同一套上下翻约定）；本类只补 `colorSpace = SRGBColorSpace`（硬件采样即解 sRGB→linear，与旧 RT 方案逐字节同口径）。
  * - inset 用库的 `rtStitchTileInset(i, tw, th, IMAGE_TILE_GRID)`：上传多切 8px、采样只取中间干净块 ⇒ 接缝不回潮，
  *   与上传切片 `rtStitchTileRects` 共用同一份几何（⛔ 不许在这里另算一份）。
- * - 逐张就绪、逐张显影：未就绪那张 `get()` 返回 null ⇒ 调方把那片传 null（材质显示灰），下一帧就绪后即亮。
+ * - 逐张就绪、逐张显影：未就绪那张 `get()` 返回 null ⇒ 调方把那片传 null（材质那一格整格 discard，不落像素），下一帧就绪后即亮。
  */
 import { SRGBColorSpace, Texture, Vector4 } from "three";
 import { loadPanoTexture, releasePanoTexture } from "./panoBitmapTexture";
@@ -48,6 +48,11 @@ export class ImagePlaneTileLoader {
         return this.cache.get(url) || null;
     }
 
+    /** 这张是否还在下载/解码途中。既不在缓存又不在途 ⇒ 要么没发起、要么已经失败（调用方据此决定「再排一帧等」还是「就此收工」） */
+    isPending(url: string): boolean {
+        return this.inflight.has(url);
+    }
+
     /** 第 i 片（行优先、图像左上起）的采样窗口；瓦片未就绪时返回整张 [0,0,1,1] */
     inset(entry: TileEntry, i: number): Vector4 {
         if (!entry.w || !entry.h) return new Vector4(0, 0, 1, 1);

package/MktMesh/mktMappingShader.d.ts

@@ -1,19 +1,19 @@
 import { ShaderMaterial } from "three";
 /**
  * ⭐ 融合材质的全景点数**上限**：每点占 **3** 张拼合槽纹理（皇上旨 2026-10-23「全景的 RT 由原来的 2 个分成 3 个、
- *   每个 4096×6144、竖直排列 3 个瓦片」⇒ 原图切 3×3=9 片，按**列**分 3 槽）⇒ 点数 × 3 必须 ≤ sampler 硬顶。
- *   本机 `MAX_TEXTURE_IMAGE_UNITS` 实测 **16**：旧版 8 点 × 2 槽 = 16 正好用满，现每点 3 槽 ⇒ 只能取 ⌊16/3⌋ = **5**
- *   （5 × 3 = 15）。皇上旨 2026-10-23 在「A」里拍板：保 3 槽不降画质，**同屏全景点数 8 → 5**。
+ *   每个 RT 上面 3×3=9 片」⇒ 原图切 6×3=18 片，按**半幅**分 2 槽）⇒ 点数 × 2 必须 ≤ sampler 硬顶。
+ *   本机 `MAX_TEXTURE_IMAGE_UNITS` 实测 **16**：每点 2 槽 ⇒ 取 ⌊16/2⌋ = **8** 点（10-23 那版每点 3 槽只能坐 5 点）
+ *   （8 × 2 = 16 正好用满）。2026-10-26 需求回到「2 个 RT / 每 RT 3×3」⇒ **同屏全景点数 5 → 8**。
  *
  * ⭐⭐ 2026-10-09 皇上旨「MktMesh 只有映射一种，blend/selected 归编辑器」⇒ 该常量从 `mktShader.ts`
  *   **搬到这里**（映射材质的所在地）。它同时是库与编辑器那份 blend 的**共同上限**，两边必须同值。
  */
-export declare const MKT_PANO_MAX_SLOTS = 5;
+export declare const MKT_PANO_MAX_SLOTS = 8;
 /**
  * 创建「全景序号直取」着色器材质（皇上旨 2026-09-29「三模式三 shader」之二）：
  * 编辑器「映射设置模式」的墙材质 + **基类 MktMesh（发布/预览）的固定墙材质**
  * （皇上旨：mktmesh 就只有按照 attribute 配置来显示全景这一种固定的 shader）。
- * uniform 形状与 blend 工厂同档（panoramas[15]/textureMatrices[5]/weights[5]/uPanoTiled[5]）⇒
+ * uniform 形状与 blend 工厂同档（panoramas[16]/textureMatrices[8]/weights[8]/uPanoTiled[8]）⇒
  * 喂料复用 feedBlendProjection 的槽位指派路（feedFaceMapping），零新喂料路。
  * uFloorCoreRadius/uFloorFadeRange/uFloorOpacity 三根本 shader 不读，但喂料统一入口会写 ⇒ JS 侧留着（静默忽略）。
  */