three-base 2.0.198 → 2.0.199

package/MktMesh/MktMesh.d.ts

@@ -5,6 +5,7 @@ import { type PanoStitcher } from "./panoTileStitcher";
 import type { MktMeshData, MktTextureInfo, WallPoint, WallSide } from "./types";
 import { ImagePlane, type ImagePlaneData } from "./imagePlane";
 import { ModelSlot, type ModelSlotData } from "./modelSlot";
+import { MktResourceManager } from "./mktResManager";
 export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
     textures: MktTextureInfo[];
@@ -122,8 +123,10 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *  必须与基类喂纹理处用同一个值，否则标记与地址不同源 ⇒ 整图被按 1/2 横向铺满球面（10-06 晚起纵向不分块，四槽时代是 1/4）。 */
     get panoTexMode(): PanoTexMode;
     /** 优先加载的全景个数（存档 `textures` 的前 n 项）：**-1 = 全部、0 = 一个都不提前、n = 前 n 个**（2026-11-05 需求）。
-     *  默认取 `PANO_IMPORT_PRIORITY_DEFAULT`（=4）；宿主想换档在渲染循环跑起来之前 `setPanoPriorityCount(-1)` 一行即可
-     *  （与 `_ossSize`、`_panoTexMode` 同一套注入路径 ⇒ 编辑器与预览各自的配置各自推下来）。 */
+     *  默认取 `PANO_IMPORT_PRIORITY_DEFAULT`（= -1，同日需求「不管有没有显示出来的全景图都应该默认全部加载」）；
+     *  宿主想收窄，在渲染循环跑起来之前 `setPanoPriorityCount(4)` 一行即可
+     *  （与 `_ossSize`、`_panoTexMode` 同一套注入路径 ⇒ 编辑器与预览各自的配置各自推下来）。
+     *  ⚠️ 这一档只定**下载与拼合的次序**；隐藏期里谁来推那一拍 = `preRender(renderer)`（需求第 1、2 点）。 */
     private _panoPriorityCount;
     /** 当前优先加载个数（只读，回显用）。 */
     get panoPriorityCount(): number;
@@ -168,6 +171,14 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *    否则它会在轮到自身那一帧被写回可见（`boolean` 只有一个位，放行那里分不出这笔是谁写的）。
      */
     private _revealPending;
+    /**
+     * ⭐ 2026-11-05 需求「专门写一个资源管理器来管理，每个 mktmesh 都有自己的一个资源管理器」：本对象一份。
+     * 它不下载、不解码、不上传 ⇒ 全部经下面那几只手点本对象上**现成**的入口（拼合器 `pump` / `prefetchHeadPanoramas` /
+     * `feedImagePlaneTiles` / 隐藏期预热），只多管两件事：隐藏期由谁来推那一拍、以及「哪一档真画进过显存」这本账。
+     */
+    private _res;
+    /** 本对象的资源管理器（只读）。宿主只管调 `preRender`，需要看账本时才用它。 */
+    get resManager(): MktResourceManager;
     /**
      * 隐藏期 GPU 预热的在册清单（元素 = 一个「会进渲染列表的物件」，即它的材质组合 × 几何）。
      * null = 没在预热（未启动 / 已跑完 / `stopGpuPrewarm` / `dispose` 四种都是它）。
@@ -424,8 +435,27 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *    表空了它就是一句 `length` 判断，⛔ 不需要再像旧写法那样把钩子置 null（钩子上还挂着全景投影那三件事）。
      * ⚠️ 这里写的 `visible` 只针对**自己压进表的那几颗** ⇒ 表外的对象（单颗新增、已 dispose、被 `releaseReveal`
      *    摘牌的）一律不碰；要在放行前接管某颗，调 `releaseReveal(o)`。
+     * ⭐ 2026-11-05 需求第 4 点「只已经预载入的资源才显示出来」：内容落定（`o.loaded`）之后还要问一句资源管理器
+     *    「这一档画进显存了吗」—— 只有宿主调过 `preRender` 且预热还挂着牌时才拦，摘牌 / 没调过 ⇒ 一律放行（⛔ 不许拦出永久黑屏）。
      */
     tickProgressiveReveal(): void;
+    /**
+     * ⭐ 2026-11-05 需求第 1 点逐字：「需要提供一个 `preRender` 方法, 传入一个渲染器对象, 然后在这个方法里面使用
+     *  渲染来预载入已经准备好的资源到 GPU」。隐藏期（`visible = false`）里 three 遍历第一句就把本对象连同子树跳过
+     *  ⇒ `onBeforeRender` 一次都不触发，全景瓦片不下载不拼合、平面不绑、GLB 与墙的 program 不编不传；
+     *  本方法就是那句「藏起来的时候替它跑一遍渲染循环里的推进」，交进来的渲染器同时供拼合器与预热用。
+     *
+     * 一次点齐三族（次序固定，与 `onBeforeRender` 里同一相对位置）：
+     *   ① 全景 —— `stitcher.pump(renderer)` 逐 tick 走「补下载 → 画已进显存的格 → 传一张新的」，
+     *      额度由 `panoPriorityCount` 点的批排在前（默认 -1 = 整份存档，需求第 2 点）；
+     *   ② 平面图 —— `feedImagePlaneTiles()` 一次把整层地址交给下载、绑定一帧一颗（需求第 3 点：这两族本来就全量发起）；
+     *   ③ GLB / 平面 / 墙 —— 下面的 `startGpuPrewarm` 那一族逐 tick 画一件进 1×1 目标（program 编译 + 顶点缓冲首传）。
+     *
+     * 幂等 ⇒ 隐藏期里每帧点一次、或只在载入后点一次都行；已排进队列的那条链不会被重复起。
+     * 本对象一旦 `visible`（进厅），链自己停 ⇒ 之后交回 `onBeforeRender` 每帧那一路，⛔ 不抢同一帧的额度。
+     * ⛔ 不调本方法的宿主（发布页直接亮墙、编辑器画布）行为与改造前逐字一致：显示闸只在 `preRender` 点过之后才生效。
+     */
+    preRender(renderer: WebGLRenderer): void;
     /**
      * 开始隐藏期预热：把「进厅第一帧要现编的那些 program + 要第一次上传的那些几何/纹理」提前跑掉，一帧只放**一件**。
      *

package/MktMesh/MktMesh.js

@@ -51,11 +51,16 @@ import { stripAssetHost, absAssetUrl } from "./assetUrl";
 import { ImagePlane } from "./imagePlane";
 import { ModelSlot, glbFileName } from "./modelSlot";
 import { ImagePlaneTileLoader } from "./imageTileLoader";
+// ⭐ 用户需求 2026-11-05「专门写一个资源管理器来管理, 每个 mktmesh 都有自己的一个资源管理器来管理」：
+//    隐藏期（`visible = false` ⇒ `onBeforeRender` 一次都不触发）里那三族资源的**驱动次序**与**是否已进显存**这本账。
+import { MktResourceManager } from "./mktResManager";
 /** 载入 JSON 时**优先**加载几个全景的素材的**默认档**（数值只写这一处）。
  *  口径 = 存档 `textures` 数组的前 n 项（n = -1 视为整份全加载）；其余全景照常按每帧的槽位名册（离注视点最近 8 个）排队，只是排在它们后面。
  *  2026-10-29 需求「优先加载前 2 个全景图的素材，然后再加载其他的」立的是 2；
- *  2026-11-05 需求逐字「现在要默认把全景全部都要默认加载, 现在需要通过配置来设置, 提前加载多少个全景 -1 就是全加载 0就是不加载 1就是加载个 2就提前加载2个 一次类推, 默认加载前4个」⇒ 换成 4，并让这一档可被实例覆写。 */
-const PANO_IMPORT_PRIORITY_DEFAULT = 4;
+ *  2026-11-05 需求逐字「现在要默认把全景全部都要默认加载, 现在需要通过配置来设置, 提前加载多少个全景 -1 就是全加载 0就是不加载 1就是加载个 2就提前加载2个 一次类推, 默认加载前4个」⇒ 换成可配置的 4；
+ *  同日需求逐字「panoPriorityCount 设置为 -1, 不管有没有显示出来的全景图都应该默认全部加载, 等待渲染器的预载入」⇒ 默认档落 **-1（整份全加载）**。
+ *  ⚠️ 这一档管的是**下载与拼合的次序**；「亮出来之前先把它推进显存」是 `preRender(renderer)` 那一手（见 `./mktResManager`）。 */
+const PANO_IMPORT_PRIORITY_DEFAULT = -1;
 /** 隐藏期预热那一次绘制用的镜头（模块级共用：它只是个「有合法的投影矩阵可读」的载体，永不动 ⇒ ⛔ 不必每实例造一份）。 */
 const GPU_WARM_CAMERA = new OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
 /**
@@ -196,8 +201,10 @@ export default class MktMesh extends Mesh {
         return this._panoTexMode;
     }
     /** 优先加载的全景个数（存档 `textures` 的前 n 项）：**-1 = 全部、0 = 一个都不提前、n = 前 n 个**（2026-11-05 需求）。
-     *  默认取 `PANO_IMPORT_PRIORITY_DEFAULT`（=4）；宿主想换档在渲染循环跑起来之前 `setPanoPriorityCount(-1)` 一行即可
-     *  （与 `_ossSize`、`_panoTexMode` 同一套注入路径 ⇒ 编辑器与预览各自的配置各自推下来）。 */
+     *  默认取 `PANO_IMPORT_PRIORITY_DEFAULT`（= -1，同日需求「不管有没有显示出来的全景图都应该默认全部加载」）；
+     *  宿主想收窄，在渲染循环跑起来之前 `setPanoPriorityCount(4)` 一行即可
+     *  （与 `_ossSize`、`_panoTexMode` 同一套注入路径 ⇒ 编辑器与预览各自的配置各自推下来）。
+     *  ⚠️ 这一档只定**下载与拼合的次序**；隐藏期里谁来推那一拍 = `preRender(renderer)`（需求第 1、2 点）。 */
     _panoPriorityCount = PANO_IMPORT_PRIORITY_DEFAULT;
     /** 当前优先加载个数（只读，回显用）。 */
     get panoPriorityCount() {
@@ -245,6 +252,25 @@ export default class MktMesh extends Mesh {
      *    否则它会在轮到自身那一帧被写回可见（`boolean` 只有一个位，放行那里分不出这笔是谁写的）。
      */
     _revealPending = [];
+    /**
+     * ⭐ 2026-11-05 需求「专门写一个资源管理器来管理，每个 mktmesh 都有自己的一个资源管理器」：本对象一份。
+     * 它不下载、不解码、不上传 ⇒ 全部经下面那几只手点本对象上**现成**的入口（拼合器 `pump` / `prefetchHeadPanoramas` /
+     * `feedImagePlaneTiles` / 隐藏期预热），只多管两件事：隐藏期由谁来推那一拍、以及「哪一档真画进过显存」这本账。
+     */
+    _res = new MktResourceManager({
+        prewarm: (renderer) => this.startGpuPrewarm(renderer),
+        stopPrewarm: () => this.stopGpuPrewarm(),
+        // 挂着牌 = 还没摘牌且还没亮出来 ⇒ 与 `_topUpGpuPrewarm` 用的同一颗尺（⛔ 不自立第二道闸）
+        prewarming: () => this._warmSeen !== null && !this.visible,
+        shown: () => this.visible,
+        pumpPano: (renderer) => this._stitcher.pump(renderer),
+        prefetchPano: () => this.prefetchHeadPanoramas(),
+        feedPlanes: () => this.feedImagePlaneTiles(),
+    });
+    /** 本对象的资源管理器（只读）。宿主只管调 `preRender`，需要看账本时才用它。 */
+    get resManager() {
+        return this._res;
+    }
     /**
      * 隐藏期 GPU 预热的在册清单（元素 = 一个「会进渲染列表的物件」，即它的材质组合 × 几何）。
      * null = 没在预热（未启动 / 已跑完 / `stopGpuPrewarm` / `dispose` 四种都是它）。
@@ -294,7 +320,8 @@ export default class MktMesh extends Mesh {
             //   `updateTexture`（它里面那记 `pump` 是「第一次拿到 renderer ⇒ 在册组整份作废」的现场）之后、
             //   `feedFaceMapping`（名册逐槽入册）之前 —— 顺序倒过来就是「名册在前、我们垫底」= 静默失效。
             //   编辑态那份在 `MktDevMesh` 的宿主循环里照同一相对位置点（⛔ 别在这儿加第三处）。
-            //   2026-11-05 需求：这一批点几颗改由 `panoPriorityCount` 定（默认 4，-1 = 存档全部）⇒ 本句不动。
+            //   2026-11-05 需求：这一批点几颗改由 `panoPriorityCount` 定（默认 -1 = 存档全部）⇒ 本句不动；
+            //   同一批在**隐藏期**由 `preRender(renderer)` 逐 tick 推（本钩子在那时一次都不触发）。
             this.prefetchHeadPanoramas();
             this.feedFaceMapping();
             this.tickProgressiveReveal();
@@ -1328,6 +1355,8 @@ export default class MktMesh extends Mesh {
      *    表空了它就是一句 `length` 判断，⛔ 不需要再像旧写法那样把钩子置 null（钩子上还挂着全景投影那三件事）。
      * ⚠️ 这里写的 `visible` 只针对**自己压进表的那几颗** ⇒ 表外的对象（单颗新增、已 dispose、被 `releaseReveal`
      *    摘牌的）一律不碰；要在放行前接管某颗，调 `releaseReveal(o)`。
+     * ⭐ 2026-11-05 需求第 4 点「只已经预载入的资源才显示出来」：内容落定（`o.loaded`）之后还要问一句资源管理器
+     *    「这一档画进显存了吗」—— 只有宿主调过 `preRender` 且预热还挂着牌时才拦，摘牌 / 没调过 ⇒ 一律放行（⛔ 不许拦出永久黑屏）。
      */
     tickProgressiveReveal() {
         const q = this._revealPending;
@@ -1335,12 +1364,33 @@ export default class MktMesh extends Mesh {
             const o = q[i];
             if (!o.loaded)
                 continue; // 内容还在路上 ⇒ 这一颗继续压着，先看后面已经落定的
+            if (this._res.holdsReveal(o))
+                continue; // 内容到了但还没进显存 ⇒ 等 `preRender` 那一拍画过它
             q.splice(i, 1);
             o.visible = true;
             return;
         }
     }
     // ─────────────────── 隐藏期 GPU 预热（2026-11-01 需求：进厅那一下不要再现编着色器） ───────────────────
+    /**
+     * ⭐ 2026-11-05 需求第 1 点逐字：「需要提供一个 `preRender` 方法, 传入一个渲染器对象, 然后在这个方法里面使用
+     *  渲染来预载入已经准备好的资源到 GPU」。隐藏期（`visible = false`）里 three 遍历第一句就把本对象连同子树跳过
+     *  ⇒ `onBeforeRender` 一次都不触发，全景瓦片不下载不拼合、平面不绑、GLB 与墙的 program 不编不传；
+     *  本方法就是那句「藏起来的时候替它跑一遍渲染循环里的推进」，交进来的渲染器同时供拼合器与预热用。
+     *
+     * 一次点齐三族（次序固定，与 `onBeforeRender` 里同一相对位置）：
+     *   ① 全景 —— `stitcher.pump(renderer)` 逐 tick 走「补下载 → 画已进显存的格 → 传一张新的」，
+     *      额度由 `panoPriorityCount` 点的批排在前（默认 -1 = 整份存档，需求第 2 点）；
+     *   ② 平面图 —— `feedImagePlaneTiles()` 一次把整层地址交给下载、绑定一帧一颗（需求第 3 点：这两族本来就全量发起）；
+     *   ③ GLB / 平面 / 墙 —— 下面的 `startGpuPrewarm` 那一族逐 tick 画一件进 1×1 目标（program 编译 + 顶点缓冲首传）。
+     *
+     * 幂等 ⇒ 隐藏期里每帧点一次、或只在载入后点一次都行；已排进队列的那条链不会被重复起。
+     * 本对象一旦 `visible`（进厅），链自己停 ⇒ 之后交回 `onBeforeRender` 每帧那一路，⛔ 不抢同一帧的额度。
+     * ⛔ 不调本方法的宿主（发布页直接亮墙、编辑器画布）行为与改造前逐字一致：显示闸只在 `preRender` 点过之后才生效。
+     */
+    preRender(renderer) {
+        this._res.preRender(renderer);
+    }
     /**
      * 开始隐藏期预热：把「进厅第一帧要现编的那些 program + 要第一次上传的那些几何/纹理」提前跑掉，一帧只放**一件**。
      *
@@ -1442,6 +1492,9 @@ export default class MktMesh extends Mesh {
                 return;
             seen.add(key);
             items.push({ src: o, m: mesh.material, g });
+            // ⭐ 2026-11-05 需求第 4 点：把「这一颗属于哪一档」交给资源管理器记账（键的算式仍只在这里这一处），
+            //   等 `_runGpuWarmStep` 真画过它再翻成「已进显存」⇒ `tickProgressiveReveal` 才放行。
+            this._res.noteWarmKey(o, key);
             added++;
         });
         return added;
@@ -1492,6 +1545,9 @@ export default class MktMesh extends Mesh {
         renderer.setRenderTarget(this._warmRt);
         renderer.render(scene, GPU_WARM_CAMERA);
         renderer.setRenderTarget(prevTarget);
+        // ⭐ 2026-11-05 需求第 4 点：这一档刚刚真画进显存（program 编了、顶点缓冲与纹理首传也做了）⇒ 记上「已常驻」，
+        //   `tickProgressiveReveal` 那一拍才许把对应那颗亮出来（同一档的第二、第三颗跟着一起放行）。
+        this._res.markWarmDrawn(it.src);
         this._scheduleGpuWarmStep(renderer);
     }
     /**
@@ -1750,6 +1806,7 @@ export default class MktMesh extends Mesh {
         this._revealPending = [];
         // 隐藏期预热：清单、去重表与小屋子那套临时资源随本对象一起退场（那张 1×1 渲染目标是本类**唯一**自建的 RT）。
         // 走 `stopGpuPrewarm` 而不是 `_finishGpuPrewarm`：本对象都要没了，去重表再留着就是泄漏。
+        this._res.stop(); // 资源管理器：全景/平面那条链停、显示闸开、显存账作废（内部同样落到 `stopGpuPrewarm`）
         this.stopGpuPrewarm();
         this._stitcher.dispose();
         this._glRenderer = null;

package/MktMesh/MktMesh.ts

@@ -77,12 +77,17 @@ import { stripAssetHost, absAssetUrl } from "./assetUrl";
 import { ImagePlane, type ImagePlaneData } from "./imagePlane";
 import { ModelSlot, glbFileName, type ModelSlotData } from "./modelSlot";
 import { ImagePlaneTileLoader } from "./imageTileLoader";
+// ⭐ 用户需求 2026-11-05「专门写一个资源管理器来管理, 每个 mktmesh 都有自己的一个资源管理器来管理」：
+//    隐藏期（`visible = false` ⇒ `onBeforeRender` 一次都不触发）里那三族资源的**驱动次序**与**是否已进显存**这本账。
+import { MktResourceManager } from "./mktResManager";
 
 /** 载入 JSON 时**优先**加载几个全景的素材的**默认档**（数值只写这一处）。
  *  口径 = 存档 `textures` 数组的前 n 项（n = -1 视为整份全加载）；其余全景照常按每帧的槽位名册（离注视点最近 8 个）排队，只是排在它们后面。
  *  2026-10-29 需求「优先加载前 2 个全景图的素材，然后再加载其他的」立的是 2；
- *  2026-11-05 需求逐字「现在要默认把全景全部都要默认加载, 现在需要通过配置来设置, 提前加载多少个全景 -1 就是全加载 0就是不加载 1就是加载个 2就提前加载2个 一次类推, 默认加载前4个」⇒ 换成 4，并让这一档可被实例覆写。 */
-const PANO_IMPORT_PRIORITY_DEFAULT = 4;
+ *  2026-11-05 需求逐字「现在要默认把全景全部都要默认加载, 现在需要通过配置来设置, 提前加载多少个全景 -1 就是全加载 0就是不加载 1就是加载个 2就提前加载2个 一次类推, 默认加载前4个」⇒ 换成可配置的 4；
+ *  同日需求逐字「panoPriorityCount 设置为 -1, 不管有没有显示出来的全景图都应该默认全部加载, 等待渲染器的预载入」⇒ 默认档落 **-1（整份全加载）**。
+ *  ⚠️ 这一档管的是**下载与拼合的次序**；「亮出来之前先把它推进显存」是 `preRender(renderer)` 那一手（见 `./mktResManager`）。 */
+const PANO_IMPORT_PRIORITY_DEFAULT = -1;
 
 /** 隐藏期预热那一次绘制用的镜头（模块级共用：它只是个「有合法的投影矩阵可读」的载体，永不动 ⇒ ⛔ 不必每实例造一份）。 */
 const GPU_WARM_CAMERA = new OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
@@ -234,8 +239,10 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     }
 
     /** 优先加载的全景个数（存档 `textures` 的前 n 项）：**-1 = 全部、0 = 一个都不提前、n = 前 n 个**（2026-11-05 需求）。
-     *  默认取 `PANO_IMPORT_PRIORITY_DEFAULT`（=4）；宿主想换档在渲染循环跑起来之前 `setPanoPriorityCount(-1)` 一行即可
-     *  （与 `_ossSize`、`_panoTexMode` 同一套注入路径 ⇒ 编辑器与预览各自的配置各自推下来）。 */
+     *  默认取 `PANO_IMPORT_PRIORITY_DEFAULT`（= -1，同日需求「不管有没有显示出来的全景图都应该默认全部加载」）；
+     *  宿主想收窄，在渲染循环跑起来之前 `setPanoPriorityCount(4)` 一行即可
+     *  （与 `_ossSize`、`_panoTexMode` 同一套注入路径 ⇒ 编辑器与预览各自的配置各自推下来）。
+     *  ⚠️ 这一档只定**下载与拼合的次序**；隐藏期里谁来推那一拍 = `preRender(renderer)`（需求第 1、2 点）。 */
     private _panoPriorityCount: number = PANO_IMPORT_PRIORITY_DEFAULT;
     /** 当前优先加载个数（只读，回显用）。 */
     get panoPriorityCount(): number {
@@ -286,6 +293,26 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      */
     private _revealPending: Array<ImagePlane | ModelSlot> = [];
 
+    /**
+     * ⭐ 2026-11-05 需求「专门写一个资源管理器来管理，每个 mktmesh 都有自己的一个资源管理器」：本对象一份。
+     * 它不下载、不解码、不上传 ⇒ 全部经下面那几只手点本对象上**现成**的入口（拼合器 `pump` / `prefetchHeadPanoramas` /
+     * `feedImagePlaneTiles` / 隐藏期预热），只多管两件事：隐藏期由谁来推那一拍、以及「哪一档真画进过显存」这本账。
+     */
+    private _res = new MktResourceManager({
+        prewarm: (renderer) => this.startGpuPrewarm(renderer),
+        stopPrewarm: () => this.stopGpuPrewarm(),
+        // 挂着牌 = 还没摘牌且还没亮出来 ⇒ 与 `_topUpGpuPrewarm` 用的同一颗尺（⛔ 不自立第二道闸）
+        prewarming: () => this._warmSeen !== null && !this.visible,
+        shown: () => this.visible,
+        pumpPano: (renderer) => this._stitcher.pump(renderer),
+        prefetchPano: () => this.prefetchHeadPanoramas(),
+        feedPlanes: () => this.feedImagePlaneTiles(),
+    });
+    /** 本对象的资源管理器（只读）。宿主只管调 `preRender`，需要看账本时才用它。 */
+    get resManager(): MktResourceManager {
+        return this._res;
+    }
+
     /**
      * 隐藏期 GPU 预热的在册清单（元素 = 一个「会进渲染列表的物件」，即它的材质组合 × 几何）。
      * null = 没在预热（未启动 / 已跑完 / `stopGpuPrewarm` / `dispose` 四种都是它）。
@@ -334,7 +361,8 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             //   `updateTexture`（它里面那记 `pump` 是「第一次拿到 renderer ⇒ 在册组整份作废」的现场）之后、
             //   `feedFaceMapping`（名册逐槽入册）之前 —— 顺序倒过来就是「名册在前、我们垫底」= 静默失效。
             //   编辑态那份在 `MktDevMesh` 的宿主循环里照同一相对位置点（⛔ 别在这儿加第三处）。
-            //   2026-11-05 需求：这一批点几颗改由 `panoPriorityCount` 定（默认 4，-1 = 存档全部）⇒ 本句不动。
+            //   2026-11-05 需求：这一批点几颗改由 `panoPriorityCount` 定（默认 -1 = 存档全部）⇒ 本句不动；
+            //   同一批在**隐藏期**由 `preRender(renderer)` 逐 tick 推（本钩子在那时一次都不触发）。
             this.prefetchHeadPanoramas();
             this.feedFaceMapping();
             this.tickProgressiveReveal();
@@ -1372,12 +1400,15 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *    表空了它就是一句 `length` 判断，⛔ 不需要再像旧写法那样把钩子置 null（钩子上还挂着全景投影那三件事）。
      * ⚠️ 这里写的 `visible` 只针对**自己压进表的那几颗** ⇒ 表外的对象（单颗新增、已 dispose、被 `releaseReveal`
      *    摘牌的）一律不碰；要在放行前接管某颗，调 `releaseReveal(o)`。
+     * ⭐ 2026-11-05 需求第 4 点「只已经预载入的资源才显示出来」：内容落定（`o.loaded`）之后还要问一句资源管理器
+     *    「这一档画进显存了吗」—— 只有宿主调过 `preRender` 且预热还挂着牌时才拦，摘牌 / 没调过 ⇒ 一律放行（⛔ 不许拦出永久黑屏）。
      */
     tickProgressiveReveal(): void {
         const q = this._revealPending;
         for (let i = 0; i < q.length; i++) {
             const o = q[i];
             if (!o.loaded) continue; // 内容还在路上 ⇒ 这一颗继续压着，先看后面已经落定的
+            if (this._res.holdsReveal(o)) continue; // 内容到了但还没进显存 ⇒ 等 `preRender` 那一拍画过它
             q.splice(i, 1);
             o.visible = true;
             return;
@@ -1386,6 +1417,26 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
 
     // ─────────────────── 隐藏期 GPU 预热（2026-11-01 需求：进厅那一下不要再现编着色器） ───────────────────
 
+    /**
+     * ⭐ 2026-11-05 需求第 1 点逐字：「需要提供一个 `preRender` 方法, 传入一个渲染器对象, 然后在这个方法里面使用
+     *  渲染来预载入已经准备好的资源到 GPU」。隐藏期（`visible = false`）里 three 遍历第一句就把本对象连同子树跳过
+     *  ⇒ `onBeforeRender` 一次都不触发，全景瓦片不下载不拼合、平面不绑、GLB 与墙的 program 不编不传；
+     *  本方法就是那句「藏起来的时候替它跑一遍渲染循环里的推进」，交进来的渲染器同时供拼合器与预热用。
+     *
+     * 一次点齐三族（次序固定，与 `onBeforeRender` 里同一相对位置）：
+     *   ① 全景 —— `stitcher.pump(renderer)` 逐 tick 走「补下载 → 画已进显存的格 → 传一张新的」，
+     *      额度由 `panoPriorityCount` 点的批排在前（默认 -1 = 整份存档，需求第 2 点）；
+     *   ② 平面图 —— `feedImagePlaneTiles()` 一次把整层地址交给下载、绑定一帧一颗（需求第 3 点：这两族本来就全量发起）；
+     *   ③ GLB / 平面 / 墙 —— 下面的 `startGpuPrewarm` 那一族逐 tick 画一件进 1×1 目标（program 编译 + 顶点缓冲首传）。
+     *
+     * 幂等 ⇒ 隐藏期里每帧点一次、或只在载入后点一次都行；已排进队列的那条链不会被重复起。
+     * 本对象一旦 `visible`（进厅），链自己停 ⇒ 之后交回 `onBeforeRender` 每帧那一路，⛔ 不抢同一帧的额度。
+     * ⛔ 不调本方法的宿主（发布页直接亮墙、编辑器画布）行为与改造前逐字一致：显示闸只在 `preRender` 点过之后才生效。
+     */
+    preRender(renderer: WebGLRenderer): void {
+        this._res.preRender(renderer);
+    }
+
     /**
      * 开始隐藏期预热：把「进厅第一帧要现编的那些 program + 要第一次上传的那些几何/纹理」提前跑掉，一帧只放**一件**。
      *
@@ -1482,6 +1533,9 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             if (seen.has(key)) return;
             seen.add(key);
             items.push({ src: o, m: mesh.material as Material | Material[], g });
+            // ⭐ 2026-11-05 需求第 4 点：把「这一颗属于哪一档」交给资源管理器记账（键的算式仍只在这里这一处），
+            //   等 `_runGpuWarmStep` 真画过它再翻成「已进显存」⇒ `tickProgressiveReveal` 才放行。
+            this._res.noteWarmKey(o, key);
             added++;
         });
         return added;
@@ -1531,6 +1585,9 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         renderer.setRenderTarget(this._warmRt!);
         renderer.render(scene, GPU_WARM_CAMERA);
         renderer.setRenderTarget(prevTarget);
+        // ⭐ 2026-11-05 需求第 4 点：这一档刚刚真画进显存（program 编了、顶点缓冲与纹理首传也做了）⇒ 记上「已常驻」，
+        //   `tickProgressiveReveal` 那一拍才许把对应那颗亮出来（同一档的第二、第三颗跟着一起放行）。
+        this._res.markWarmDrawn(it.src);
         this._scheduleGpuWarmStep(renderer);
     }
 
@@ -1791,6 +1848,7 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         this._revealPending = [];
         // 隐藏期预热：清单、去重表与小屋子那套临时资源随本对象一起退场（那张 1×1 渲染目标是本类**唯一**自建的 RT）。
         // 走 `stopGpuPrewarm` 而不是 `_finishGpuPrewarm`：本对象都要没了，去重表再留着就是泄漏。
+        this._res.stop(); // 资源管理器：全景/平面那条链停、显示闸开、显存账作废（内部同样落到 `stopGpuPrewarm`）
         this.stopGpuPrewarm();
         this._stitcher.dispose();
         this._glRenderer = null;

package/MktMesh/mktResManager.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `MktMesh` 的资源管理器（2026-11-05 需求逐字：「只已经预载入的资源才显示出来, 或者放到 shader 里面去显示出来.
+ *  可以专门写一个资源管理器来管理, 每个 mktmesh 都有自己的一个资源管理器来管理」）。
+ *
+ * 管的是三族资源：全景（32 片拼成左右 2 张槽纹理）、GLB（模型槽）、平面图（4 格瓦片）。
+ * 职责只有两件事：
+ *   ① **推**：`preRender(renderer)` 起一条全局队列链，每 tick 推进一步（全景 = 补下载 → 画已进显存的格 → 传一张新的；
+ *      平面 = 把瓦片交给下载并补排绑定；GLB/平面/墙 = 隐藏期预热那件 1×1 绘制）。
+ *      为什么非得有人推：`visible = false` 时 three 遍历第一句就 `if ( object.visible === false ) return;`
+ *      ⇒ 墙一次都收不到 `onBeforeRender`，藏起来的展厅里那三族本来一帧都不推进（这就是「资源等不到渲染器」的根）。
+ *   ② **记账**：哪一档真的画进过显存。`MktMesh.tickProgressiveReveal` 拿这本账决定一颗平面 / 一槽模型许不许亮
+ *      ⇒ 「已经预载入的才显示出来」落在这一条上（需求第 4 点）。
+ *
+ * ⛔ 本文件不下载、不解码、不 `initTexture`、不建纹理、不拼合、不编译 —— 那几件事各自只有一份实现
+ *   （`./panoTileStitcher` 的三道工序、`./imageTileLoader`、`./modelSlot`、`MktMesh` 的隐藏期预热）。
+ *   这里只经 `MktResHost` 那几只手**点它们**，并把预热报回来的那一档记上账 ⇒ 全工程只此一把「进显存」尺。
+ * ⚠️ 全景「进 shader」那一道闸不在这里：`MktMesh._peekTileAt` 见拼合器 `resident()` 为假就返回 null ⇒ 那一格当帧不绑，
+ *   已由「没进显存不许绑」管住；这里只管**驱动**与**亮出来的那一族**。
+ */
+import type { Object3D, WebGLRenderer } from "three";
+/** 管理器向宿主（一颗 `MktMesh`）要的那几只手 —— 全部是宿主上现成的入口，⛔ 不许在这里另起一套实现。 */
+export interface MktResHost {
+    /** 隐藏期 GPU 预热（一 tick 画一件：program 编译 + 顶点缓冲/纹理首传）；重复点不重建清单 */
+    prewarm(renderer: WebGLRenderer): void;
+    /** 摘牌（进厅 / 退场）：清单作废，晚到的内容不再补排 */
+    stopPrewarm(): void;
+    /** 预热还挂着牌吗（`_warmSeen` 非空且还没 `visible`）⇒ 只有挂着牌，「没进显存先别亮」这道闸才谈得上生效 */
+    prewarming(): boolean;
+    /** 已经亮出来了 ⇒ 每帧由 `onBeforeRender` 自己驱动，本管理器那条链就该停下来不抢额度 */
+    shown(): boolean;
+    /** 全景拼合推进一步（补下载 → 画已进显存的格 → 传一张新的）；⚠️ 必须排在 `prefetchPano` **之前** */
+    pumpPano(renderer: WebGLRenderer): void;
+    /** 把存档前 n 颗全景（`panoPriorityCount`，n = -1 为整份）点名回加载任务队列头部；幂等 */
+    prefetchPano(): void;
+    /** 把整层平面的瓦片地址交给下载并补排「一帧一颗」的绑定；幂等 */
+    feedPlanes(): void;
+}
+/**
+ * 一颗 `MktMesh` 一份（`MktMesh._res`，由构造期注入的 `MktResHost` 绑回宿主）。
+ * 状态机很简单：`preRender` 把链起起来并开闸，链每 tick 推进一步，宿主亮出来（`shown()`）就自停；
+ * 摘牌（`stop()`）同时关掉显示闸 ⇒ 没用过 `preRender` 的宿主行为与改造前逐字一致。
+ */
+export declare class MktResourceManager {
+    private host;
+    /** 宿主交进来的那台渲染器（隐藏期库里自己拿不到 ⇒ 只有 `preRender` 这一路） */
+    private renderer;
+    /** 全景/平面那条链是否还排在 `threeUtils.workList` 里（防重复起链） */
+    private driving;
+    /** `preRender` 点过 ⇒ 显示闸才生效（⛔ 没点过的宿主一律照常放行，不许凭空黑屏） */
+    private armed;
+    /** 对象 → 预热清单里那一档的去重键。键的**算式**只在 `MktMesh._collectWarmItems` 一处，这里只登记结果 */
+    private warmKey;
+    /** 已经真画进显存的那几档（键）⇒ 同一档的第二第三颗也算过了，不必再压 */
+    private warmDrawn;
+    constructor(host: MktResHost);
+    /**
+     * 预载入：拿宿主的渲染器，把「已经准备好的」逐 tick 推进 GPU（需求第 1 点）。
+     * 幂等 ⇒ 隐藏期里宿主每帧点一次、或只点一次都行；换了渲染器再点 ⇒ 拼合器自己会把在册组整份作废（`_switchRenderer`）。
+     */
+    preRender(renderer: WebGLRenderer | null): void;
+    /** 摘牌（宿主进厅 / `MktMesh.dispose`）：链停、闸开、账清；预热交回宿主那句 `stopGpuPrewarm` 去收。 */
+    stop(): void;
+    /** 登记「这一颗对应预热清单里哪一档」（`_collectWarmItems` 收进来那一拍调）。 */
+    noteWarmKey(o: Object3D, key: string): void;
+    /** 记这一档刚刚真画进显存（`_runGpuWarmStep` 画完那一拍调）⇒ 这颗从此许亮。 */
+    markWarmDrawn(o: Object3D): void;
+    /**
+     * 显示闸（需求第 4 点）：这颗平面 / 模型此刻该不该被压着不亮。
+     * 只在「`preRender` 点过 + 预热还挂着牌 + 这一档登记过但还没画过」三条同时成立时才拦；
+     * ⛔ 压根没进过预热清单的一律放行 —— 那属于「还没扫到」，把它当「没进显存」就是永久黑屏。
+     */
+    holdsReveal(o: Object3D): boolean;
+    /** 队列里那一格：推进一步，然后只再排自己下一格（⛔ 不在这里一轮推光）。 */
+    private step;
+    /** 一步里干的三件事，次序固定：先推拼合（第一次拿到渲染器时它把在册组整份作废），再点名，再补排平面绑定。 */
+    private feed;
+}

package/MktMesh/mktResManager.js

@@ -0,0 +1,89 @@
+import threeUtils from "../threeUtils";
+/**
+ * 一颗 `MktMesh` 一份（`MktMesh._res`，由构造期注入的 `MktResHost` 绑回宿主）。
+ * 状态机很简单：`preRender` 把链起起来并开闸，链每 tick 推进一步，宿主亮出来（`shown()`）就自停；
+ * 摘牌（`stop()`）同时关掉显示闸 ⇒ 没用过 `preRender` 的宿主行为与改造前逐字一致。
+ */
+export class MktResourceManager {
+    host;
+    /** 宿主交进来的那台渲染器（隐藏期库里自己拿不到 ⇒ 只有 `preRender` 这一路） */
+    renderer = null;
+    /** 全景/平面那条链是否还排在 `threeUtils.workList` 里（防重复起链） */
+    driving = false;
+    /** `preRender` 点过 ⇒ 显示闸才生效（⛔ 没点过的宿主一律照常放行，不许凭空黑屏） */
+    armed = false;
+    /** 对象 → 预热清单里那一档的去重键。键的**算式**只在 `MktMesh._collectWarmItems` 一处，这里只登记结果 */
+    warmKey = new WeakMap();
+    /** 已经真画进显存的那几档（键）⇒ 同一档的第二第三颗也算过了，不必再压 */
+    warmDrawn = new Set();
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * 预载入：拿宿主的渲染器，把「已经准备好的」逐 tick 推进 GPU（需求第 1 点）。
+     * 幂等 ⇒ 隐藏期里宿主每帧点一次、或只点一次都行；换了渲染器再点 ⇒ 拼合器自己会把在册组整份作废（`_switchRenderer`）。
+     */
+    preRender(renderer) {
+        if (!renderer)
+            return;
+        this.armed = true;
+        this.renderer = renderer;
+        this.host.prewarm(renderer); // GLB / 平面图 / 墙：一 tick 一件，它自己会接着排下一件
+        this.feed(); // 全景 + 平面：先立刻推一步，别让第一格空转
+        if (this.driving)
+            return;
+        this.driving = true;
+        threeUtils.addWork(() => { }); // 占一格 ⇒ 真活落下一 tick，与预热 / 上传 / 绑定同一手法
+        threeUtils.addWork(() => this.step());
+    }
+    /** 摘牌（宿主进厅 / `MktMesh.dispose`）：链停、闸开、账清；预热交回宿主那句 `stopGpuPrewarm` 去收。 */
+    stop() {
+        this.driving = false;
+        this.armed = false;
+        this.renderer = null;
+        this.warmDrawn.clear();
+        this.host.stopPrewarm();
+    }
+    /** 登记「这一颗对应预热清单里哪一档」（`_collectWarmItems` 收进来那一拍调）。 */
+    noteWarmKey(o, key) {
+        this.warmKey.set(o, key);
+    }
+    /** 记这一档刚刚真画进显存（`_runGpuWarmStep` 画完那一拍调）⇒ 这颗从此许亮。 */
+    markWarmDrawn(o) {
+        const key = this.warmKey.get(o);
+        if (key)
+            this.warmDrawn.add(key);
+    }
+    /**
+     * 显示闸（需求第 4 点）：这颗平面 / 模型此刻该不该被压着不亮。
+     * 只在「`preRender` 点过 + 预热还挂着牌 + 这一档登记过但还没画过」三条同时成立时才拦；
+     * ⛔ 压根没进过预热清单的一律放行 —— 那属于「还没扫到」，把它当「没进显存」就是永久黑屏。
+     */
+    holdsReveal(o) {
+        if (!this.armed || !this.host.prewarming())
+            return false;
+        const key = this.warmKey.get(o);
+        return key !== undefined && !this.warmDrawn.has(key);
+    }
+    /** 队列里那一格：推进一步，然后只再排自己下一格（⛔ 不在这里一轮推光）。 */
+    step() {
+        if (!this.driving)
+            return; // `stop()` 已摘牌 ⇒ 这一项作废
+        if (this.host.shown()) { // 亮出来了 ⇒ 交回 `onBeforeRender` 每帧那一路，不再抢额度
+            this.driving = false;
+            return;
+        }
+        this.feed();
+        threeUtils.addWork(() => { });
+        threeUtils.addWork(() => this.step());
+    }
+    /** 一步里干的三件事，次序固定：先推拼合（第一次拿到渲染器时它把在册组整份作废），再点名，再补排平面绑定。 */
+    feed() {
+        const renderer = this.renderer;
+        if (!renderer)
+            return;
+        this.host.pumpPano(renderer);
+        this.host.prefetchPano();
+        this.host.feedPlanes();
+    }
+}

package/MktMesh/mktResManager.ts

@@ -0,0 +1,130 @@
+/**
+ * `MktMesh` 的资源管理器（2026-11-05 需求逐字：「只已经预载入的资源才显示出来, 或者放到 shader 里面去显示出来.
+ *  可以专门写一个资源管理器来管理, 每个 mktmesh 都有自己的一个资源管理器来管理」）。
+ *
+ * 管的是三族资源：全景（32 片拼成左右 2 张槽纹理）、GLB（模型槽）、平面图（4 格瓦片）。
+ * 职责只有两件事：
+ *   ① **推**：`preRender(renderer)` 起一条全局队列链，每 tick 推进一步（全景 = 补下载 → 画已进显存的格 → 传一张新的；
+ *      平面 = 把瓦片交给下载并补排绑定；GLB/平面/墙 = 隐藏期预热那件 1×1 绘制）。
+ *      为什么非得有人推：`visible = false` 时 three 遍历第一句就 `if ( object.visible === false ) return;`
+ *      ⇒ 墙一次都收不到 `onBeforeRender`，藏起来的展厅里那三族本来一帧都不推进（这就是「资源等不到渲染器」的根）。
+ *   ② **记账**：哪一档真的画进过显存。`MktMesh.tickProgressiveReveal` 拿这本账决定一颗平面 / 一槽模型许不许亮
+ *      ⇒ 「已经预载入的才显示出来」落在这一条上（需求第 4 点）。
+ *
+ * ⛔ 本文件不下载、不解码、不 `initTexture`、不建纹理、不拼合、不编译 —— 那几件事各自只有一份实现
+ *   （`./panoTileStitcher` 的三道工序、`./imageTileLoader`、`./modelSlot`、`MktMesh` 的隐藏期预热）。
+ *   这里只经 `MktResHost` 那几只手**点它们**，并把预热报回来的那一档记上账 ⇒ 全工程只此一把「进显存」尺。
+ * ⚠️ 全景「进 shader」那一道闸不在这里：`MktMesh._peekTileAt` 见拼合器 `resident()` 为假就返回 null ⇒ 那一格当帧不绑，
+ *   已由「没进显存不许绑」管住；这里只管**驱动**与**亮出来的那一族**。
+ */
+import type { Object3D, WebGLRenderer } from "three";
+import threeUtils from "../threeUtils";
+
+/** 管理器向宿主（一颗 `MktMesh`）要的那几只手 —— 全部是宿主上现成的入口，⛔ 不许在这里另起一套实现。 */
+export interface MktResHost {
+    /** 隐藏期 GPU 预热（一 tick 画一件：program 编译 + 顶点缓冲/纹理首传）；重复点不重建清单 */
+    prewarm(renderer: WebGLRenderer): void;
+    /** 摘牌（进厅 / 退场）：清单作废，晚到的内容不再补排 */
+    stopPrewarm(): void;
+    /** 预热还挂着牌吗（`_warmSeen` 非空且还没 `visible`）⇒ 只有挂着牌，「没进显存先别亮」这道闸才谈得上生效 */
+    prewarming(): boolean;
+    /** 已经亮出来了 ⇒ 每帧由 `onBeforeRender` 自己驱动，本管理器那条链就该停下来不抢额度 */
+    shown(): boolean;
+    /** 全景拼合推进一步（补下载 → 画已进显存的格 → 传一张新的）；⚠️ 必须排在 `prefetchPano` **之前** */
+    pumpPano(renderer: WebGLRenderer): void;
+    /** 把存档前 n 颗全景（`panoPriorityCount`，n = -1 为整份）点名回加载任务队列头部；幂等 */
+    prefetchPano(): void;
+    /** 把整层平面的瓦片地址交给下载并补排「一帧一颗」的绑定；幂等 */
+    feedPlanes(): void;
+}
+
+/**
+ * 一颗 `MktMesh` 一份（`MktMesh._res`，由构造期注入的 `MktResHost` 绑回宿主）。
+ * 状态机很简单：`preRender` 把链起起来并开闸，链每 tick 推进一步，宿主亮出来（`shown()`）就自停；
+ * 摘牌（`stop()`）同时关掉显示闸 ⇒ 没用过 `preRender` 的宿主行为与改造前逐字一致。
+ */
+export class MktResourceManager {
+    private host: MktResHost;
+    /** 宿主交进来的那台渲染器（隐藏期库里自己拿不到 ⇒ 只有 `preRender` 这一路） */
+    private renderer: WebGLRenderer | null = null;
+    /** 全景/平面那条链是否还排在 `threeUtils.workList` 里（防重复起链） */
+    private driving = false;
+    /** `preRender` 点过 ⇒ 显示闸才生效（⛔ 没点过的宿主一律照常放行，不许凭空黑屏） */
+    private armed = false;
+    /** 对象 → 预热清单里那一档的去重键。键的**算式**只在 `MktMesh._collectWarmItems` 一处，这里只登记结果 */
+    private warmKey = new WeakMap<Object3D, string>();
+    /** 已经真画进显存的那几档（键）⇒ 同一档的第二第三颗也算过了，不必再压 */
+    private warmDrawn = new Set<string>();
+
+    constructor(host: MktResHost) {
+        this.host = host;
+    }
+
+    /**
+     * 预载入：拿宿主的渲染器，把「已经准备好的」逐 tick 推进 GPU（需求第 1 点）。
+     * 幂等 ⇒ 隐藏期里宿主每帧点一次、或只点一次都行；换了渲染器再点 ⇒ 拼合器自己会把在册组整份作废（`_switchRenderer`）。
+     */
+    preRender(renderer: WebGLRenderer | null): void {
+        if (!renderer) return;
+        this.armed = true;
+        this.renderer = renderer;
+        this.host.prewarm(renderer); // GLB / 平面图 / 墙：一 tick 一件，它自己会接着排下一件
+        this.feed(); // 全景 + 平面：先立刻推一步，别让第一格空转
+        if (this.driving) return;
+        this.driving = true;
+        threeUtils.addWork(() => {}); // 占一格 ⇒ 真活落下一 tick，与预热 / 上传 / 绑定同一手法
+        threeUtils.addWork(() => this.step());
+    }
+
+    /** 摘牌（宿主进厅 / `MktMesh.dispose`）：链停、闸开、账清；预热交回宿主那句 `stopGpuPrewarm` 去收。 */
+    stop(): void {
+        this.driving = false;
+        this.armed = false;
+        this.renderer = null;
+        this.warmDrawn.clear();
+        this.host.stopPrewarm();
+    }
+
+    /** 登记「这一颗对应预热清单里哪一档」（`_collectWarmItems` 收进来那一拍调）。 */
+    noteWarmKey(o: Object3D, key: string): void {
+        this.warmKey.set(o, key);
+    }
+
+    /** 记这一档刚刚真画进显存（`_runGpuWarmStep` 画完那一拍调）⇒ 这颗从此许亮。 */
+    markWarmDrawn(o: Object3D): void {
+        const key = this.warmKey.get(o);
+        if (key) this.warmDrawn.add(key);
+    }
+
+    /**
+     * 显示闸（需求第 4 点）：这颗平面 / 模型此刻该不该被压着不亮。
+     * 只在「`preRender` 点过 + 预热还挂着牌 + 这一档登记过但还没画过」三条同时成立时才拦；
+     * ⛔ 压根没进过预热清单的一律放行 —— 那属于「还没扫到」，把它当「没进显存」就是永久黑屏。
+     */
+    holdsReveal(o: Object3D): boolean {
+        if (!this.armed || !this.host.prewarming()) return false;
+        const key = this.warmKey.get(o);
+        return key !== undefined && !this.warmDrawn.has(key);
+    }
+
+    /** 队列里那一格：推进一步，然后只再排自己下一格（⛔ 不在这里一轮推光）。 */
+    private step(): void {
+        if (!this.driving) return; // `stop()` 已摘牌 ⇒ 这一项作废
+        if (this.host.shown()) { // 亮出来了 ⇒ 交回 `onBeforeRender` 每帧那一路，不再抢额度
+            this.driving = false;
+            return;
+        }
+        this.feed();
+        threeUtils.addWork(() => {});
+        threeUtils.addWork(() => this.step());
+    }
+
+    /** 一步里干的三件事，次序固定：先推拼合（第一次拿到渲染器时它把在册组整份作废），再点名，再补排平面绑定。 */
+    private feed(): void {
+        const renderer = this.renderer;
+        if (!renderer) return;
+        this.host.pumpPano(renderer);
+        this.host.prefetchPano();
+        this.host.feedPlanes();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-base",
-  "version": "2.0.198",
+  "version": "2.0.199",
   "description": "A Three.js extension library providing common 3D components, animations, materials, and utilities",
   "author": "xiaosihan",
   "publishConfig": {