three-base 2.0.181 → 2.0.188

package/MktMesh/MktMesh.d.ts

@@ -130,9 +130,23 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     models: ModelSlot[];
     /**
      * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
-     * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不闪缺图灰；只随本对象 `dispose()` 释放。
+     * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不会再空一格；只随本对象 `dispose()` 释放。
      */
     private _imgTileLoader;
+    /**
+     * 逐帧绑定用的两张账（2026-10-26 定的方案：地址一次性全部丢给下载，绑材质改成「一帧一颗平面」）。
+     * 全局 rAF 每拍只跑一项 `addWork`，而 `addWork` 按闭包引用判重 ⇒ 每次现造的新闭包它判不出来，
+     * ⛔ 去重闸门必须像全景上传那张 `_uploadQueued` 一样自备。
+     */
+    private _imgBindQueued;
+    /** 平面 → 「它 4 条地址全部落定（就绪或失败）时的那串地址」⇒ 地址不换就不再重排；上传换图会改这串 ⇒ 自动重排 */
+    private _imgBindDone;
+    /**
+     * 模型槽「GLB 已取回、等这一帧把它挂进父元素」的在册表 —— 与上面图片绑定同一手法（用户 10-26 需求：
+     * 一次性全部拿去加载，用 `threeUtils.addWork` 逐帧加到场景里）。整层十几个槽同时到货时，
+     * 一帧只有一颗进 `_contentRoot`（进图那一拍要重算包围盒 + 排布 + 首次把几何送上 GPU）。
+     */
+    private _modelMountQueued;
     constructor(opts?: {
         wallHeight?: number;
         wallClosed?: boolean;
@@ -309,13 +323,13 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     projectName: string;
     /** 注入项目名（导出 json 前调一次即可；导入时无须调——还原靠落盘地址自身的首段） */
     setProjectName(name: string): void;
-    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 */
+    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 + 起排它自己的逐帧绑定 */
     addImagePlane(ip: ImagePlane): ImagePlane;
     /** 摘掉一颗并释放它自己的几何/材质；那 4 张瓦片纹理归 `_imgTileLoader` 管 ⇒ ⛔ 不在这里 dispose */
     removeImagePlane(ip: ImagePlane): void;
     /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用） */
     addModel(ms: ModelSlot): ModelSlot;
-    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾） */
+    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾；排在后头的挂载帧靠「不在册」早退） */
     removeModel(ms: ModelSlot): void;
     /**
      * 整层重建图片平面（`importData` 与预览那一路）。
@@ -327,14 +341,30 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      * 整层重建模型槽（`importData` 与预览那一路），地址口径的要求同 `setImagePlanes`。
      * ⚠️ GLB 逐只**异步取、不 await**（十几只串一条队会把载入卡死），每只落地那一刻各回调一次 `onEachLoad`：
      *   预览每帧真画 ⇒ 不传；编辑器是按需渲染 ⇒ 传一个「标脏」的钩子，否则模型挂上来屏幕不动。
+     * 2026-10-26 决定：取回与「挂进父元素」分两拍 —— 地址一次性全交给下载（网络 + 解析不占渲染帧），
+     *   真正进场景图那一步交给 `threeUtils.addWork` ⇒ 全局 rAF 每拍只跑一项 = **一帧只挂一颗槽**
+     *   （挂载那一拍要重算包围盒 + 排布 + 首次把整棵子树的几何送上 GPU，十几颗挤在同一帧就是他要拆掉的那一卡）。
      */
     setModels(datas: ModelSlotData[], onEachLoad?: () => void): void;
+    /** 把「备好待挂」的那一槽交给全局队列；⛔ 去重闸门自备（`addWork` 按闭包引用判重，新闭包它判不出来） */
+    private _queueModelMount;
+    /** 全局队列里的那一帧：只挂这一槽，挂好才回调（`onEachLoad` = 按需渲染宿主的标脏钩子） */
+    private _mountModelStep;
     /**
-     * 每帧把各颗平面那 4 张瓦片的纹理直采绑到材质（⭐ 10-22 晚旨：不走拼合器 RT）。
-     * 库里的**唯一驱动点**：持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次，⛔ 不许在调用方再抄一份循环。
-     * 还没下载完/缺格的那一格绑 null ⇒ 片元画缺图灰（皇上 10-26 收回默认图那条旨：「不要默认图, 没有加到位的时候 就显示深灰色」）。
+     * 把各颗平面那 4 张瓦片的纹理绑进材质（10-22 晚定的口径：不走拼合器 RT）。
+     * 2026-10-26 决定改成**逐帧**：一次把整层地址全丢给下载器（下载/解码在网络与工作线程侧，不占这一帧），
+     * 真正写 uniform 的那一步交给 `threeUtils.addWork` —— 全局 rAF 每拍只跑一项 ⇒ 一帧只绑一颗平面，
+     * 一整层平面的纹理上传被摊到多帧，不再挤在同一记调用里（旧写法一记 `feed` 就把所有平面全绑完）。
+     * ⛔ 不进 `onBeforeRender` 自驱；持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次只是「补排漏网的平面」，
+     * 而整层重建（`setImagePlanes`）末尾自己起排 ⇒ 只调 `importData(整串)` 的宿主不必自己驱动也会长出来。
+     * 还没下载完/缺格的那一格绑 null ⇒ 片元那一格整格 discard，不落像素（用户 10-26 连收两条：先「不要默认图」，
+     * 再「不是显示灰色, 而是直接 discard 丢弃」）。
      */
     feedImagePlaneTiles(): void;
+    /** 一颗平面排一帧的绑定工作：先把它那 4 条地址**一次性全部**交给下载器，再把「写材质」排进全局队列。 */
+    private _queueImagePlaneBind;
+    /** 队列里的一格：只绑**这一颗**平面里已就绪的那几格；还有在途的就重新排队，⛔ 不在这里等、也⛔ 不顺手把别的平面一起做完。 */
+    private _bindImagePlaneStep;
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName?: string): MktMeshData;

package/MktMesh/MktMesh.js

@@ -187,9 +187,23 @@ export default class MktMesh extends Mesh {
     models = [];
     /**
      * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
-     * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不闪缺图灰；只随本对象 `dispose()` 释放。
+     * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不会再空一格；只随本对象 `dispose()` 释放。
      */
     _imgTileLoader = new ImagePlaneTileLoader();
+    /**
+     * 逐帧绑定用的两张账（2026-10-26 定的方案：地址一次性全部丢给下载，绑材质改成「一帧一颗平面」）。
+     * 全局 rAF 每拍只跑一项 `addWork`，而 `addWork` 按闭包引用判重 ⇒ 每次现造的新闭包它判不出来，
+     * ⛔ 去重闸门必须像全景上传那张 `_uploadQueued` 一样自备。
+     */
+    _imgBindQueued = new Set();
+    /** 平面 → 「它 4 条地址全部落定（就绪或失败）时的那串地址」⇒ 地址不换就不再重排；上传换图会改这串 ⇒ 自动重排 */
+    _imgBindDone = new Map();
+    /**
+     * 模型槽「GLB 已取回、等这一帧把它挂进父元素」的在册表 —— 与上面图片绑定同一手法（用户 10-26 需求：
+     * 一次性全部拿去加载，用 `threeUtils.addWork` 逐帧加到场景里）。整层十几个槽同时到货时，
+     * 一帧只有一颗进 `_contentRoot`（进图那一拍要重算包围盒 + 排布 + 首次把几何送上 GPU）。
+     */
+    _modelMountQueued = new Set();
     constructor(opts = {}) {
         // 发布/预览态墙：**固定**用「全景序号直取」着色器（皇上旨 2026-09-29：mktmesh 就只有按照 attribute
         // 配置来显示全景这一种固定的 shader——每帧由 feedFaceMapping 按 panoFaceMapping 把被引用的全景
@@ -1027,10 +1041,11 @@ export default class MktMesh extends Mesh {
         this.projectName = typeof name === "string" ? name : "";
     }
     // ───────────── 平面图 / 模型两层（⭐ 皇上旨 2026-10-26「把图片平面和模型一起搬进库里」） ─────────────
-    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 */
+    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 + 起排它自己的逐帧绑定 */
     addImagePlane(ip) {
         this.imagePlanes.push(ip);
         this.add(ip);
+        this._queueImagePlaneBind(ip);
         return ip;
     }
     /** 摘掉一颗并释放它自己的几何/材质；那 4 张瓦片纹理归 `_imgTileLoader` 管 ⇒ ⛔ 不在这里 dispose */
@@ -1038,6 +1053,8 @@ export default class MktMesh extends Mesh {
         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();
     }
@@ -1047,11 +1064,12 @@ export default class MktMesh extends Mesh {
         this.add(ms);
         return ms;
     }
-    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾） */
+    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾；排在后头的挂载帧靠「不在册」早退） */
     removeModel(ms) {
         const i = this.models.indexOf(ms);
         if (i >= 0)
             this.models.splice(i, 1);
+        this._modelMountQueued.delete(ms);
         this.remove(ms);
         ms.dispose();
     }
@@ -1061,6 +1079,8 @@ export default class MktMesh extends Mesh {
      *   ⛔ 本方法里不许再补一遍，也⛔ 不许在调用方各自补。
      */
     setImagePlanes(datas) {
+        this._imgBindQueued.clear();
+        this._imgBindDone.clear();
         for (const ip of this.imagePlanes) {
             this.remove(ip);
             ip.dispose();
@@ -1072,13 +1092,19 @@ export default class MktMesh extends Mesh {
             this.imagePlanes.push(ip);
             this.add(ip);
         }
+        // 整层重建完立刻起排：地址一次性全交给下载、绑材质逐帧一记 ⇒ 宿主不驱动这一层也长得出来
+        this.feedImagePlaneTiles();
     }
     /**
      * 整层重建模型槽（`importData` 与预览那一路），地址口径的要求同 `setImagePlanes`。
      * ⚠️ GLB 逐只**异步取、不 await**（十几只串一条队会把载入卡死），每只落地那一刻各回调一次 `onEachLoad`：
      *   预览每帧真画 ⇒ 不传；编辑器是按需渲染 ⇒ 传一个「标脏」的钩子，否则模型挂上来屏幕不动。
+     * 2026-10-26 决定：取回与「挂进父元素」分两拍 —— 地址一次性全交给下载（网络 + 解析不占渲染帧），
+     *   真正进场景图那一步交给 `threeUtils.addWork` ⇒ 全局 rAF 每拍只跑一项 = **一帧只挂一颗槽**
+     *   （挂载那一拍要重算包围盒 + 排布 + 首次把整棵子树的几何送上 GPU，十几颗挤在同一帧就是他要拆掉的那一卡）。
      */
     setModels(datas, onEachLoad) {
+        this._modelMountQueued.clear();
         for (const ms of this.models) {
             this.remove(ms);
             ms.dispose();
@@ -1088,42 +1114,93 @@ export default class MktMesh extends Mesh {
             const ms = new ModelSlot(d.name);
             ms.applyData(d);
             this.models.push(ms);
-            this.add(ms);
+            this.add(ms); // 槽本体（占位小立方体）当场进图 ⇒ GLB 在路上时这一槽不凭空消失
             if (d.url)
-                void ms.setModelUrl(d.url).then(() => onEachLoad && onEachLoad());
+                void ms.loadModel(d.url).then(() => this._queueModelMount(ms, onEachLoad));
         }
     }
+    /** 把「备好待挂」的那一槽交给全局队列；⛔ 去重闸门自备（`addWork` 按闭包引用判重，新闭包它判不出来） */
+    _queueModelMount(ms, onEachLoad) {
+        if (this._modelMountQueued.has(ms))
+            return;
+        this._modelMountQueued.add(ms);
+        threeUtils.addWork(() => { });
+        threeUtils.addWork(() => this._mountModelStep(ms, onEachLoad));
+    }
+    /** 全局队列里的那一帧：只挂这一槽，挂好才回调（`onEachLoad` = 按需渲染宿主的标脏钩子） */
+    _mountModelStep(ms, onEachLoad) {
+        this._modelMountQueued.delete(ms);
+        // 槽已退场（换项目 / 删除）：待挂那棵由 `ModelSlot.dispose` → `_detachModel` 当场释放，这里不挂
+        if (!this.models.includes(ms))
+            return;
+        if (ms.mountStaged() && onEachLoad)
+            onEachLoad();
+    }
     /**
-     * 每帧把各颗平面那 4 张瓦片的纹理直采绑到材质（⭐ 10-22 晚旨：不走拼合器 RT）。
-     * 库里的**唯一驱动点**：持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次，⛔ 不许在调用方再抄一份循环。
-     * 还没下载完/缺格的那一格绑 null ⇒ 片元画缺图灰（皇上 10-26 收回默认图那条旨：「不要默认图, 没有加到位的时候 就显示深灰色」）。
+     * 把各颗平面那 4 张瓦片的纹理绑进材质（10-22 晚定的口径：不走拼合器 RT）。
+     * 2026-10-26 决定改成**逐帧**：一次把整层地址全丢给下载器（下载/解码在网络与工作线程侧，不占这一帧），
+     * 真正写 uniform 的那一步交给 `threeUtils.addWork` —— 全局 rAF 每拍只跑一项 ⇒ 一帧只绑一颗平面，
+     * 一整层平面的纹理上传被摊到多帧，不再挤在同一记调用里（旧写法一记 `feed` 就把所有平面全绑完）。
+     * ⛔ 不进 `onBeforeRender` 自驱；持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次只是「补排漏网的平面」，
+     * 而整层重建（`setImagePlanes`）末尾自己起排 ⇒ 只调 `importData(整串)` 的宿主不必自己驱动也会长出来。
+     * 还没下载完/缺格的那一格绑 null ⇒ 片元那一格整格 discard，不落像素（用户 10-26 连收两条：先「不要默认图」，
+     * 再「不是显示灰色, 而是直接 discard 丢弃」）。
      */
     feedImagePlaneTiles() {
-        if (!this.imagePlanes.length)
+        for (const ip of this.imagePlanes)
+            this._queueImagePlaneBind(ip);
+    }
+    /** 一颗平面排一帧的绑定工作：先把它那 4 条地址**一次性全部**交给下载器，再把「写材质」排进全局队列。 */
+    _queueImagePlaneBind(ip) {
+        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);
-        for (const ip of this.imagePlanes) {
-            const tiles = ip.tiles;
-            // ⛔ 旧存档 16 条地址（> 满批 4）直接不收 ⇒ 整张缺图灰，按 10-20 口径重传即可；空 tiles 同样
-            if (!tiles || tiles.length !== 4) {
-                ip.setTileTextures([null, null, null, null], [zero.clone(), zero.clone(), zero.clone(), zero.clone()]);
+        // ⛔ 旧存档 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));
+    }
+    /** 队列里的一格：只绑**这一颗**平面里已就绪的那几格；还有在途的就重新排队，⛔ 不在这里等、也⛔ 不顺手把别的平面一起做完。 */
+    _bindImagePlaneStep(ip, sig) {
+        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 = [null, null, null, null];
+        const insets = [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 texs = [null, null, null, null];
-            const insets = [zero.clone(), zero.clone(), zero.clone(), zero.clone()];
-            for (let i = 0; i < 4; i++) {
-                const url = tiles[i];
-                if (!url)
-                    continue;
-                this._imgTileLoader.preload(url);
-                const e = this._imgTileLoader.get(url);
-                if (!e || !e.tex)
-                    continue;
+            const e = this._imgTileLoader.get(url);
+            if (e && e.tex) {
                 texs[i] = e.tex;
                 insets[i] = this._imgTileLoader.inset(e, i);
             }
-            ip.setTileTextures(texs, insets);
+            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` */
@@ -1230,7 +1307,7 @@ export default class MktMesh extends Mesh {
         this._uploadQueued.clear(); // 排队项即便回调仍触发，也会因 `!this._uploadQueued.delete(tex)` 早退
         this._ossSizeDepKeys.clear();
         // ⭐ 10-26 旨入库的两层：子对象逐个 dispose，平面那 4 张瓦片的缓存**只在这里**整批清
-        //   （与上面 `_texCache` 同一条旨 ⇒ 切工程不重建这一份、也就不会闪缺图灰）。
+        //   （与上面 `_texCache` 同一条旨 ⇒ 切工程不重建这一份、也就不会再空出一格）。
         for (const ip of this.imagePlanes) {
             this.remove(ip);
             ip.dispose();
@@ -1242,6 +1319,9 @@ export default class MktMesh extends Mesh {
         }
         this.models = [];
         this._imgTileLoader.clear();
+        this._imgBindQueued.clear();
+        this._imgBindDone.clear();
+        this._modelMountQueued.clear();
         this._stitcher.dispose();
         this._glRenderer = null;
         if (this._placeholder)

package/MktMesh/MktMesh.ts

@@ -213,9 +213,23 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     models: ModelSlot[] = [];
     /**
      * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
-     * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不闪缺图灰；只随本对象 `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
@@ -1057,10 +1071,11 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
 
     // ───────────── 平面图 / 模型两层（⭐ 皇上旨 2026-10-26「把图片平面和模型一起搬进库里」） ─────────────
 
-    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 */
+    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 + 起排它自己的逐帧绑定 */
     addImagePlane(ip: ImagePlane): ImagePlane {
         this.imagePlanes.push(ip);
         this.add(ip);
+        this._queueImagePlaneBind(ip);
         return ip;
     }
 
@@ -1068,6 +1083,8 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     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();
     }
@@ -1079,10 +1096,11 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         return ms;
     }
 
-    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾） */
+    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `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();
     }
@@ -1093,6 +1111,8 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *   ⛔ 本方法里不许再补一遍，也⛔ 不许在调用方各自补。
      */
     setImagePlanes(datas: ImagePlaneData[]): void {
+        this._imgBindQueued.clear();
+        this._imgBindDone.clear();
         for (const ip of this.imagePlanes) {
             this.remove(ip);
             ip.dispose();
@@ -1104,14 +1124,20 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             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();
@@ -1121,39 +1147,87 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             const ms = new ModelSlot(d.name);
             ms.applyData(d);
             this.models.push(ms);
-            this.add(ms);
-            if (d.url) void ms.setModelUrl(d.url).then(() => onEachLoad && onEachLoad());
+            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）。
-     * 库里的**唯一驱动点**：持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次，⛔ 不许在调用方再抄一份循环。
-     * 还没下载完/缺格的那一格绑 null ⇒ 片元画缺图灰（皇上 10-26 收回默认图那条旨：「不要默认图, 没有加到位的时候 就显示深灰色」）。
+     * 把各颗平面那 4 张瓦片的纹理绑进材质（10-22 晚定的口径：不走拼合器 RT）。
+     * 2026-10-26 决定改成**逐帧**：一次把整层地址全丢给下载器（下载/解码在网络与工作线程侧，不占这一帧），
+     * 真正写 uniform 的那一步交给 `threeUtils.addWork` —— 全局 rAF 每拍只跑一项 ⇒ 一帧只绑一颗平面，
+     * 一整层平面的纹理上传被摊到多帧，不再挤在同一记调用里（旧写法一记 `feed` 就把所有平面全绑完）。
+     * ⛔ 不进 `onBeforeRender` 自驱；持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次只是「补排漏网的平面」，
+     * 而整层重建（`setImagePlanes`）末尾自己起排 ⇒ 只调 `importData(整串)` 的宿主不必自己驱动也会长出来。
+     * 还没下载完/缺格的那一格绑 null ⇒ 片元那一格整格 discard，不落像素（用户 10-26 连收两条：先「不要默认图」，
+     * 再「不是显示灰色, 而是直接 discard 丢弃」）。
      */
     feedImagePlaneTiles(): void {
-        if (!this.imagePlanes.length) return;
+        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);
-        for (const ip of this.imagePlanes) {
-            const tiles = ip.tiles;
-            // ⛔ 旧存档 16 条地址（> 满批 4）直接不收 ⇒ 整张缺图灰，按 10-20 口径重传即可；空 tiles 同样
-            if (!tiles || tiles.length !== 4) {
-                ip.setTileTextures([null, null, null, null], [zero.clone(), zero.clone(), zero.clone(), zero.clone()]);
-                continue;
-            }
-            const texs: (Texture | null)[] = [null, null, null, null];
-            const insets: Vector4[] = [zero.clone(), zero.clone(), zero.clone(), zero.clone()];
-            for (let i = 0; i < 4; i++) {
-                const url = tiles[i];
-                if (!url) continue;
-                this._imgTileLoader.preload(url);
-                const e = this._imgTileLoader.get(url);
-                if (!e || !e.tex) continue;
+        // ⛔ 旧存档 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);
         }
+        ip.setTileTextures(texs, insets);
+        if (pending) {
+            this._queueImagePlaneBind(ip);
+            return;
+        }
+        this._imgBindDone.set(ip, sig); // 全部落定（含下载失败那格：它留 null，那一格就永久 discard）
     }
 
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
@@ -1269,7 +1343,7 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         this._uploadQueued.clear(); // 排队项即便回调仍触发，也会因 `!this._uploadQueued.delete(tex)` 早退
         this._ossSizeDepKeys.clear();
         // ⭐ 10-26 旨入库的两层：子对象逐个 dispose，平面那 4 张瓦片的缓存**只在这里**整批清
-        //   （与上面 `_texCache` 同一条旨 ⇒ 切工程不重建这一份、也就不会闪缺图灰）。
+        //   （与上面 `_texCache` 同一条旨 ⇒ 切工程不重建这一份、也就不会再空出一格）。
         for (const ip of this.imagePlanes) {
             this.remove(ip);
             ip.dispose();
@@ -1281,6 +1355,9 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         }
         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,8 +11,9 @@
  * - 几何 PlaneGeometry(width, height)，原点在平面中心；position.y 由调用者设定（通常 height/2 让底部落地）。
  * - ⭐ 2026-10-22 晚旨：纹理**不走拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，片元按 UV 象限选片 +
  *   用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。材质用 onBeforeCompile 打补丁，
- *   注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片显示灰、逐张就绪逐张显影。
- *   （⭐ 皇上 10-26 一度要默认图，同日收回：「不要默认图, 没有加到位的时候 就显示深灰色」⇒ 默认图那整条已删。）
+ *   注入 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";
@@ -36,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;
@@ -79,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()] };
@@ -114,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;
@@ -124,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);
     }