three-base 2.0.195 → 2.0.197

package/EventMap.d.ts

@@ -20,6 +20,22 @@ export interface BeforeRenderEvent {
 export interface AfterRenderEvent {
     type: "afterRender";
 }
+export interface LoadErrorEvent {
+    type: "loadError";
+    url: string;
+    /** asset = 走 manager 计数的素材（全景整图/切片、平面瓦片、模型内嵌贴图）；model = 模型槽那颗 GLB 整体没出来 */
+    kind: "asset" | "model";
+    /** 仅 kind="model"：那一颗模型槽的名字，页面据此点名是哪一颗没出来 */
+    label?: string;
+    /** 全站累计失败地址数（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零） */
+    failed: number;
+    /** 这个地址是不是第一次失败（同地址的后续重试仍发事件，但 isNew=false、不计数） */
+    isNew: boolean;
+    /** 服务端回的状态码（只在真的拿到过回复时有：全景/平面瓦片的 fetch 非 2xx、GLB 下载失败）；网络层失败为 undefined */
+    status?: number;
+    /** 服务端**明说这个地址没有**（404 / 403）⇒ 页面据此把引用它的那条数据整条删掉；断网一类没有回复的失败不算 */
+    missing: boolean;
+}
 export interface RAFEvent {
     type: "requestAnimationFrame";
     timeTemp: number;
@@ -60,6 +76,7 @@ export interface ThreeLoaderEventMap extends Object3DEventMap {
     "loadding": LoadingEvent;
     "onLoad": OnLoadEvent;
     "progress": LoaderProgressEvent;
+    "loadError": LoadErrorEvent;
 }
 export interface ThreeBaseEventTypeMap extends Object3DEventMap {
     "loadding": LoadingEvent;

package/EventMap.ts

@@ -38,6 +38,24 @@ export interface LoaderProgressEvent {
 }
 export interface BeforeRenderEvent { type: "beforeRender"; }
 export interface AfterRenderEvent { type: "afterRender"; }
+// 资源加载失败：`DefaultLoadingManager.onError`（素材那一路）与模型槽取回失败（GLB 那一路）都汇到这一个出口。
+// `url` 同一地址只计一次数（全景/平面瓦片失败会每帧重试 ⇒ 不去重会把失败数刷成无穷大）。
+export interface LoadErrorEvent {
+    type: "loadError";
+    url: string;
+    /** asset = 走 manager 计数的素材（全景整图/切片、平面瓦片、模型内嵌贴图）；model = 模型槽那颗 GLB 整体没出来 */
+    kind: "asset" | "model";
+    /** 仅 kind="model"：那一颗模型槽的名字，页面据此点名是哪一颗没出来 */
+    label?: string;
+    /** 全站累计失败地址数（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零） */
+    failed: number;
+    /** 这个地址是不是第一次失败（同地址的后续重试仍发事件，但 isNew=false、不计数） */
+    isNew: boolean;
+    /** 服务端回的状态码（只在真的拿到过回复时有：全景/平面瓦片的 fetch 非 2xx、GLB 下载失败）；网络层失败为 undefined */
+    status?: number;
+    /** 服务端**明说这个地址没有**（404 / 403）⇒ 页面据此把引用它的那条数据整条删掉；断网一类没有回复的失败不算 */
+    missing: boolean;
+}
 
 export interface RAFEvent {
     type: "requestAnimationFrame";
@@ -85,6 +103,7 @@ export interface ThreeLoaderEventMap extends Object3DEventMap {
     "loadding": LoadingEvent;
     "onLoad": OnLoadEvent;
     "progress": LoaderProgressEvent;
+    "loadError": LoadErrorEvent;
 }
 
 export interface ThreeBaseEventTypeMap extends Object3DEventMap {

package/MktMesh/MktMesh.d.ts

@@ -1,4 +1,5 @@
 import { BufferGeometry, Camera, Matrix4, Mesh, ShaderMaterial, Texture, Vector3 } from "three";
+import type { WebGLRenderer } from "three";
 import { type PanoTexMode } from "./mktShader";
 import { type PanoStitcher } from "./panoTileStitcher";
 import type { MktMeshData, MktTextureInfo, WallPoint, WallSide } from "./types";
@@ -161,6 +162,22 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *    否则它会在轮到自身那一帧被写回可见（`boolean` 只有一个位，放行那里分不出这笔是谁写的）。
      */
     private _revealPending;
+    /**
+     * 隐藏期 GPU 预热的在册清单（元素 = 一个「会进渲染列表的物件」，即它的材质组合 × 几何）。
+     * null = 没在预热（未启动 / 已跑完 / `stopGpuPrewarm` / `dispose` 四种都是它）。
+     */
+    private _warmItems;
+    /** 已收过的去重键（`几何 × 材质数组 × 各材质的 map`）⇒ 跨轮次只补收新出现的组合，不重复编同一条 GL 路径。
+     *  自然收尾时**故意留着**（晚到的内容补排时靠它跳过旧档）；只有 `stopGpuPrewarm`/`dispose` 把它归 null = 摘牌。 */
+    private _warmSeen;
+    /** 预热用的小场景：只挂当前这一件的替身 + 宿主灯光的克隆，`fog`/`environment` 照抄（都进 program 缓存键） */
+    private _warmScene;
+    /** 此刻挂在预热小场景里的那一颗替身（一帧只画一件 ⇒ 换件时先把上一颗摘下来） */
+    private _warmActive;
+    /** 预热小场景里的那几盏灯 = 宿主灯的克隆体（各持一份 `shadow` ⇒ 收尾时释放的是它们自己的阴影图，碰不到宿主的） */
+    private _warmLights;
+    /** 预热落点：1×1 渲染目标（只有像素不要，要的是「这条 GL 路径确实走完了」），随预热结束/dispose 释放 */
+    private _warmRt;
     constructor(opts?: {
         wallHeight?: number;
         wallClosed?: boolean;
@@ -398,6 +415,82 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *    摘牌的）一律不碰；要在放行前接管某颗，调 `releaseReveal(o)`。
      */
     tickProgressiveReveal(): void;
+    /**
+     * 开始隐藏期预热：把「进厅第一帧要现编的那些 program + 要第一次上传的那些几何/纹理」提前跑掉，一帧只放**一件**。
+     *
+     * 为什么必须在隐藏期做：`visible = false` 时 three 的遍历第一句就 `if (object.visible === false) return`
+     *   （与上面 `tickProgressiveReveal` 注释同一颗雷）⇒ 墙根本进不了渲染列表，那份大 shader 从来没进过
+     *   three 的 program 缓存。进厅那一帧才第一次画它 = 编译 + 链接 + 顶点缓冲上传全压在那一帧，
+     *   这就是「像有很多资源要载入 GPU」的另一半（前一半「16 张 6144² 渲染目标」已在拼合器里治掉）。
+     *
+     * ⛔ 不用 `renderer.compile()` / `compileAsync()`：那两个吃**整个场景**、一次把里面全部 program 编完，
+     *   没地方按帧配额（`compileAsync` 的完成回调还会在同一帧落一坨主线程开销）。这里的做法是
+     *   「拿同一个材质对象 + 同一个几何对象真画一次，画进 1×1 的渲染目标」⇒ 走的就是进厅那一条 GL 路径，
+     *   编出来的正是同一份 program（three 的缓存按 `材质 × 几何属性形态 × 场景光照/雾` 计键），
+     *   顶点缓冲也真上了 GPU；那 1×1 的像素直接扔掉，不占显存、不污染画面。
+     *
+     * ⚠️ 2026-11-01 第二版：清单从「只收不带灯」放宽到**全收**，替身从「自造一颗裸 Mesh」换成「原对象自己克隆一颗」。
+     *   量出来的账（本地 dev，进厅三连帧 100/250/234 ms）：进厅那几帧里 89 份几何第一次上传（`bufferData` ×72）、
+     *   504 次 `drawElements`、6 份 program 现编 —— 第一版一道都没挡住：展厅里的展品（`ModelSlot` 那些 GLB 件，
+     *   Lambert/Standard 带灯材质）既没上传也没编，因为它们既不是 ShaderMaterial 也不是 MeshBasicMaterial。
+     *   带灯材质的 program 缓存键里有「方向光/点光/聚光数量 + 阴影档 + 环境图」
+     *   （`three.module.js:20901-20913`：`numDirLights`…`numDirLightShadows`、`shadowMapType`，另有 `envMap`/`fog` 两个位）
+     *   ⇒ 预热那间小屋子把宿主的灯**克隆一份**摆进去、`fog`/`environment` 照抄，否则编出来是另一份 define 组 = 白编。
+     *   替身必须是**克隆**不是裸 Mesh：`instancing`/`skinning`/`morphTargets` 也各占缓存键一个位
+     *   （`getProgramCacheKeyBooleans` 里那段 `_programLayers`）⇒ 拿裸 Mesh 画实例化材质编的是非实例化那一份。
+     *   克隆的灯只活在预热期，收尾时连各自的阴影图一起释放（`light.clone()` 给的是 `shadow.clone()` 的新份，
+     *   实测不与宿主共享 ⇒ 不会误释放宿主那张）；阴影边长压到 `GPU_WARM_SHADOW_MAP_SIZE`，理由写在那颗常量上。
+     *
+     * ⚠️ 一次性清单不等于收工：隐藏期里展厅的内容**还没长齐**（GLB 逐帧各挂一颗、平面的 4 格瓦片逐张就绪逐张绑），
+     *   所以补收有两只手 —— ① 排空那一拍再扫一遍；② 内容落位那两个落点各调一次 `_topUpGpuPrewarm()`
+     *   （GLB 挂进子树、平面绑上瓦片）。去重键 = `几何 id × 材质 id 串 × 各材质的 map id`（平面再带绑定戳记）
+     *   ⇒ 补收只针对「没见过的那一档」，同一件不会被画第二遍。
+     *
+     * @param renderer 宿主那一份渲染器（隐藏期 `onBeforeRender` 不触发，库里拿不到 ⇒ 必须由宿主交进来；
+     *                 站侧的落点就是 `FloorMktBase.preloadFirstPano(renderer)`，它本来就是隐藏期的入口）
+     */
+    startGpuPrewarm(renderer: WebGLRenderer): void;
+    /** 停止隐藏期预热（宿主进入展厅时调）：剩下的清单直接作废并**摘牌** —— 亮出来那一帧本来就要编要传，不必再抢额度；摘牌后晚到的内容也不再来补排。 */
+    stopGpuPrewarm(): void;
+    /**
+     * 内容后落位时补排预热（GLB 挂进子树那一拍、平面绑上瓦片纹理那一拍各调一次）。
+     *
+     * 为什么必须有这一颗：预热是隐藏期跑的，而隐藏期里展厅的内容**还没长齐** —— GLB 十几只各走一条异步下载链、
+     *   逐帧只挂一颗，平面那 4 格图也是逐张就绪逐张绑。一次性清单在几拍之内就排空了 ⇒ 晚到的那一族一件都没被画过，
+     *   进厅那一帧照样现编现传（这就是第一版「预热跑了、人还是卡了一下」的根）。
+     *
+     * 只在隐藏期响应：`_warmSeen` 归 null = 宿主已叫停（进厅）⇒ 晚到的东西交给「逐帧点亮」那一拍自己编，⛔ 别再抢额度。
+     */
+    private _topUpGpuPrewarm;
+    /**
+     * 扫一遍本对象的子树，把「还没收过的那一档」压进清单。
+     * @returns 这次新收了几个（0 = 确实没有新东西 ⇒ 调用方据此收尾，⛔ 不是每帧空转）
+     */
+    private _collectWarmItems;
+    /** 排下一件：先垫一个空函数占一格（全局队列每 tick 只跑一项 ⇒ 真活落在下一个 tick），与全景上传、平面绑定同一手法。 */
+    private _scheduleGpuWarmStep;
+    /** 队列回调的全部内容：预热**一件**（一次 1×1 绘制）。清单空了/已被摘牌就收尾。 */
+    private _runGpuWarmStep;
+    /**
+     * 造（并记住）预热那间小屋子：只建一次。
+     * `fog` / `environment` 照抄、宿主的灯**逐盏克隆**摆进来 —— 这三样都进 program 缓存键，
+     *   少一样就是编出一份进厅用不上的 program。
+     */
+    private _ensureWarmScene;
+    /** 沿 `parent` 往上找到的第一个 Scene = 宿主场景（本站是 `largeScreenRender` 那一棵）。 */
+    private _findHostScene;
+    /**
+     * 收尾（跑完 / 进厅 / 宿主叫停 / `dispose` 四条路都汇到这里）：清单作废 + 临时资源拆掉。
+     *
+     * ⚠️ **不动 `_warmSeen`**：自然跑完那一路后面还会有内容落位（GLB、后绑的瓦片），补排时全靠这张表跳过已经画过的旧档
+     *   —— 清掉它等于把同一批东西再画一遍。真正的「摘牌」只有 `stopGpuPrewarm`/`dispose`，它们先把这颗归 null。
+     */
+    private _finishGpuPrewarm;
+    /**
+     * 拆掉预热那套临时资源（1×1 渲染目标 + 克隆的灯 + 小场景）。
+     * 替身只是从小屋子里摘出来 —— 它的 `geometry`/`material` 都是宿主那一份对象 ⇒ ⛔ 在此 dispose，会把展厅要用的资源释放掉。
+     */
+    private _releaseWarmHarness;
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName?: string): MktMeshData;

package/MktMesh/MktMesh.js

@@ -23,7 +23,7 @@
  * 说明：所有实例共享同一份 material（单一 panorama uniform），
  * 同一时刻只激活名册 0 号槽（中心）那一个纹理（全局共享单激活方案）。
  */
-import { BufferGeometry, BackSide, Float32BufferAttribute, Matrix4, Mesh, Shape, ShapeGeometry, SRGBColorSpace, Vector3, Vector4, } from "three";
+import { BufferGeometry, BackSide, Float32BufferAttribute, Matrix4, OrthographicCamera, Scene, Mesh, Shape, ShapeGeometry, SRGBColorSpace, Vector3, Vector4, WebGLRenderTarget, } from "three";
 import { createPlaceholderTexture, isPanoTexMode, mktPanoTiledFlag, mktPanoTexUrls, isRtStitchKey, rtStitchKeyParts, RT_STITCH_KEY_PREFIX, RT_STITCH_SLOT_COUNT } from "./mktShader";
 import { MKT_PANO_MAX_SLOTS } from "./mktMappingShader";
 import { createMktFloorMappingShaderMaterial } from "./mktMappingShader";
@@ -54,6 +54,20 @@ import { ImagePlaneTileLoader } from "./imageTileLoader";
 /** 载入 JSON 时**优先**加载几个全景的素材（2026-10-29 需求「优先加载前 2 个全景图的素材，然后再加载其他的」）。
  *  口径 = 存档 `textures` 数组的前 n 项；其余全景照常按每帧的槽位名册（离注视点最近 8 个）排队，只是排在它们后面。 */
 const PANO_IMPORT_PRIORITY = 2;
+/** 隐藏期预热那一次绘制用的镜头（模块级共用：它只是个「有合法的投影矩阵可读」的载体，永不动 ⇒ ⛔ 不必每实例造一份）。 */
+const GPU_WARM_CAMERA = new OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
+/**
+ * 预热小屋子里那几盏克隆灯的**阴影图边长**（宿主一般是 4096²）。
+ * 压小不是降质量：这张图只在预热那间小屋子里用、像素当场扔掉，宿主自己那张阴影图归宿主每帧照画。
+ * 判据 = three 的 program 缓存键里只有 `shadowMapType` 与「几盏灯投影」这两档，**没有** `mapSize`
+ *   （`three.module.js:20913` 一段 `numDirLightShadows / shadowMapType`，`mapSize` 只是 uniform）
+ *   ⇒ 256² 编出来的 depth program 与 4096² 那份是同一个。
+ * 不压小的代价：预热每跑一件就等于替宿主重画一张 4096² 深度图（`shadow.autoUpdate` 默认开）
+ *   ⇒ 隐藏期那圈自由视角跟着掉帧，那正是「卡」本身，⛔ 不能拿它换。
+ */
+const GPU_WARM_SHADOW_MAP_SIZE = 256;
+/** 「同一件」判据里要看的那张主图 id：ShaderMaterial 那一族没有 `map` 这一档 ⇒ 恒 0；图片平面绑上图才换一档。 */
+const warmMapId = (m) => m.map?.id ?? 0;
 export default class MktMesh extends Mesh {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
     textures = [];
@@ -221,6 +235,22 @@ export default class MktMesh extends Mesh {
      *    否则它会在轮到自身那一帧被写回可见（`boolean` 只有一个位，放行那里分不出这笔是谁写的）。
      */
     _revealPending = [];
+    /**
+     * 隐藏期 GPU 预热的在册清单（元素 = 一个「会进渲染列表的物件」，即它的材质组合 × 几何）。
+     * null = 没在预热（未启动 / 已跑完 / `stopGpuPrewarm` / `dispose` 四种都是它）。
+     */
+    _warmItems = null;
+    /** 已收过的去重键（`几何 × 材质数组 × 各材质的 map`）⇒ 跨轮次只补收新出现的组合，不重复编同一条 GL 路径。
+     *  自然收尾时**故意留着**（晚到的内容补排时靠它跳过旧档）；只有 `stopGpuPrewarm`/`dispose` 把它归 null = 摘牌。 */
+    _warmSeen = null;
+    /** 预热用的小场景：只挂当前这一件的替身 + 宿主灯光的克隆，`fog`/`environment` 照抄（都进 program 缓存键） */
+    _warmScene = null;
+    /** 此刻挂在预热小场景里的那一颗替身（一帧只画一件 ⇒ 换件时先把上一颗摘下来） */
+    _warmActive = null;
+    /** 预热小场景里的那几盏灯 = 宿主灯的克隆体（各持一份 `shadow` ⇒ 收尾时释放的是它们自己的阴影图，碰不到宿主的） */
+    _warmLights = null;
+    /** 预热落点：1×1 渲染目标（只有像素不要，要的是「这条 GL 路径确实走完了」），随预热结束/dispose 释放 */
+    _warmRt = null;
     constructor(opts = {}) {
         // 发布/预览态墙：**固定**用「全景序号直取」着色器（皇上旨 2026-09-29：mktmesh 就只有按照 attribute
         // 配置来显示全景这一种固定的 shader——每帧由 feedFaceMapping 按 panoFaceMapping 把被引用的全景
@@ -1190,6 +1220,8 @@ export default class MktMesh extends Mesh {
             return;
         if (ms.mountStaged() && onEachLoad)
             onEachLoad();
+        // 挂进来的那一族此刻才在子树里 ⇒ 补排预热（清单已排空时，这一颗是重新开工的唯一触发点）
+        this._topUpGpuPrewarm();
     }
     /**
      * 把各颗平面那 4 张瓦片的纹理绑进材质（10-22 晚定的口径：不走拼合器 RT）。
@@ -1251,6 +1283,9 @@ export default class MktMesh extends Mesh {
             }
         }
         ip.setTileTextures(texs, insets);
+        // 瓦片是一张一张就绪的 ⇒ 每绑上一张，这一颗的「待画纹理」就换一档（去重键带绑定戳记）⇒ 补排一次，
+        // 让上传发生在隐藏期而不是进厅那一帧。
+        this._topUpGpuPrewarm();
         if (pending) {
             this._queueImagePlaneBind(ip);
             return;
@@ -1276,6 +1311,243 @@ export default class MktMesh extends Mesh {
             return;
         }
     }
+    // ─────────────────── 隐藏期 GPU 预热（2026-11-01 需求：进厅那一下不要再现编着色器） ───────────────────
+    /**
+     * 开始隐藏期预热：把「进厅第一帧要现编的那些 program + 要第一次上传的那些几何/纹理」提前跑掉，一帧只放**一件**。
+     *
+     * 为什么必须在隐藏期做：`visible = false` 时 three 的遍历第一句就 `if (object.visible === false) return`
+     *   （与上面 `tickProgressiveReveal` 注释同一颗雷）⇒ 墙根本进不了渲染列表，那份大 shader 从来没进过
+     *   three 的 program 缓存。进厅那一帧才第一次画它 = 编译 + 链接 + 顶点缓冲上传全压在那一帧，
+     *   这就是「像有很多资源要载入 GPU」的另一半（前一半「16 张 6144² 渲染目标」已在拼合器里治掉）。
+     *
+     * ⛔ 不用 `renderer.compile()` / `compileAsync()`：那两个吃**整个场景**、一次把里面全部 program 编完，
+     *   没地方按帧配额（`compileAsync` 的完成回调还会在同一帧落一坨主线程开销）。这里的做法是
+     *   「拿同一个材质对象 + 同一个几何对象真画一次，画进 1×1 的渲染目标」⇒ 走的就是进厅那一条 GL 路径，
+     *   编出来的正是同一份 program（three 的缓存按 `材质 × 几何属性形态 × 场景光照/雾` 计键），
+     *   顶点缓冲也真上了 GPU；那 1×1 的像素直接扔掉，不占显存、不污染画面。
+     *
+     * ⚠️ 2026-11-01 第二版：清单从「只收不带灯」放宽到**全收**，替身从「自造一颗裸 Mesh」换成「原对象自己克隆一颗」。
+     *   量出来的账（本地 dev，进厅三连帧 100/250/234 ms）：进厅那几帧里 89 份几何第一次上传（`bufferData` ×72）、
+     *   504 次 `drawElements`、6 份 program 现编 —— 第一版一道都没挡住：展厅里的展品（`ModelSlot` 那些 GLB 件，
+     *   Lambert/Standard 带灯材质）既没上传也没编，因为它们既不是 ShaderMaterial 也不是 MeshBasicMaterial。
+     *   带灯材质的 program 缓存键里有「方向光/点光/聚光数量 + 阴影档 + 环境图」
+     *   （`three.module.js:20901-20913`：`numDirLights`…`numDirLightShadows`、`shadowMapType`，另有 `envMap`/`fog` 两个位）
+     *   ⇒ 预热那间小屋子把宿主的灯**克隆一份**摆进去、`fog`/`environment` 照抄，否则编出来是另一份 define 组 = 白编。
+     *   替身必须是**克隆**不是裸 Mesh：`instancing`/`skinning`/`morphTargets` 也各占缓存键一个位
+     *   （`getProgramCacheKeyBooleans` 里那段 `_programLayers`）⇒ 拿裸 Mesh 画实例化材质编的是非实例化那一份。
+     *   克隆的灯只活在预热期，收尾时连各自的阴影图一起释放（`light.clone()` 给的是 `shadow.clone()` 的新份，
+     *   实测不与宿主共享 ⇒ 不会误释放宿主那张）；阴影边长压到 `GPU_WARM_SHADOW_MAP_SIZE`，理由写在那颗常量上。
+     *
+     * ⚠️ 一次性清单不等于收工：隐藏期里展厅的内容**还没长齐**（GLB 逐帧各挂一颗、平面的 4 格瓦片逐张就绪逐张绑），
+     *   所以补收有两只手 —— ① 排空那一拍再扫一遍；② 内容落位那两个落点各调一次 `_topUpGpuPrewarm()`
+     *   （GLB 挂进子树、平面绑上瓦片）。去重键 = `几何 id × 材质 id 串 × 各材质的 map id`（平面再带绑定戳记）
+     *   ⇒ 补收只针对「没见过的那一档」，同一件不会被画第二遍。
+     *
+     * @param renderer 宿主那一份渲染器（隐藏期 `onBeforeRender` 不触发，库里拿不到 ⇒ 必须由宿主交进来；
+     *                 站侧的落点就是 `FloorMktBase.preloadFirstPano(renderer)`，它本来就是隐藏期的入口）
+     */
+    startGpuPrewarm(renderer) {
+        if (!renderer)
+            return;
+        // 顺手记下渲染器：全景瓦片那道「每 tick 一张 initTexture」的闸在隐藏期也就能落下去了
+        //（原先 `_glRenderer` 只在 `onBeforeRender` 里捕获 ⇒ 隐藏期排上的队全走「three 自己绑」的降级路）。
+        this._glRenderer = renderer;
+        if (this._warmItems)
+            return; // 已在预热 ⇒ ⛔ 不重建清单（重复点会打断还没跑的那几件）
+        this._warmItems = [];
+        this._warmSeen = new Set();
+        this._collectWarmItems();
+        this._scheduleGpuWarmStep(renderer);
+    }
+    /** 停止隐藏期预热（宿主进入展厅时调）：剩下的清单直接作废并**摘牌** —— 亮出来那一帧本来就要编要传，不必再抢额度；摘牌后晚到的内容也不再来补排。 */
+    stopGpuPrewarm() {
+        this._warmSeen = null; // 这颗就是「摘牌」本身：`_topUpGpuPrewarm` 只认它
+        this._finishGpuPrewarm();
+    }
+    /**
+     * 内容后落位时补排预热（GLB 挂进子树那一拍、平面绑上瓦片纹理那一拍各调一次）。
+     *
+     * 为什么必须有这一颗：预热是隐藏期跑的，而隐藏期里展厅的内容**还没长齐** —— GLB 十几只各走一条异步下载链、
+     *   逐帧只挂一颗，平面那 4 格图也是逐张就绪逐张绑。一次性清单在几拍之内就排空了 ⇒ 晚到的那一族一件都没被画过，
+     *   进厅那一帧照样现编现传（这就是第一版「预热跑了、人还是卡了一下」的根）。
+     *
+     * 只在隐藏期响应：`_warmSeen` 归 null = 宿主已叫停（进厅）⇒ 晚到的东西交给「逐帧点亮」那一拍自己编，⛔ 别再抢额度。
+     */
+    _topUpGpuPrewarm() {
+        if (!this._warmSeen || this.visible)
+            return;
+        if (!this._warmItems) {
+            this._warmItems = []; // 上一轮已经收尾 ⇒ 重新开工（去重表还在 ⇒ 只补新出现的那几档，旧的不会重画）
+            this._scheduleGpuWarmStep(this._glRenderer); // `_warmSeen` 非空 ⇒ `startGpuPrewarm` 早已把渲染器交进来
+        }
+        this._collectWarmItems();
+    }
+    /**
+     * 扫一遍本对象的子树，把「还没收过的那一档」压进清单。
+     * @returns 这次新收了几个（0 = 确实没有新东西 ⇒ 调用方据此收尾，⛔ 不是每帧空转）
+     */
+    _collectWarmItems() {
+        const items = this._warmItems;
+        const seen = this._warmSeen;
+        if (!items || !seen)
+            return 0;
+        let added = 0;
+        // ⚠️ 遍历**不看 `visible`**（与 `_ensureWarmScene` 里那趟剪枝的灯正好相反）：隐藏期里展品的槽、图片的层都是
+        //   先压着不亮的（`setModels` 那一路进来就是 `visible = false`），要挡它们就等于把这次要治的那一族又漏回去。
+        this.traverse((o) => {
+            const mesh = o;
+            if (!mesh.isMesh)
+                return;
+            const g = mesh.geometry;
+            if (!g)
+                return;
+            const mats = (Array.isArray(mesh.material) ? mesh.material : [mesh.material]);
+            if (!mats.length || mats.some((m) => !m || !m.visible))
+                return; // 材质自己就不画 ⇒ 编了也用不上
+            // 「同一件」= 同一份几何 × 同一串材质 × 同一串图。后两截都要进键，因为 program 缓存键里 `USE_MAP` 那一档
+            //   看的是材质真绑没绑；而图片平面那一族的 4 格瓦片走的是 `_uTiles` uniform 数组（`material.map` 恒 null），
+            //   绑上第 1 张那一刻才是「这条 GL 路径第一次真画」⇒ 拿它自带的绑定戳记当尺，图一换就补收一次。
+            const key = `${g.id}|${mats.map((m) => m.id).join("+")}|${mats.map(warmMapId).join("+")}` +
+                (o instanceof ImagePlane ? `|${o.tilesBindingStamp()}` : "");
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            items.push({ src: o, m: mesh.material, g });
+            added++;
+        });
+        return added;
+    }
+    /** 排下一件：先垫一个空函数占一格（全局队列每 tick 只跑一项 ⇒ 真活落在下一个 tick），与全景上传、平面绑定同一手法。 */
+    _scheduleGpuWarmStep(renderer) {
+        threeUtils.addWork(() => { });
+        threeUtils.addWork(() => this._runGpuWarmStep(renderer));
+    }
+    /** 队列回调的全部内容：预热**一件**（一次 1×1 绘制）。清单空了/已被摘牌就收尾。 */
+    _runGpuWarmStep(renderer) {
+        const items = this._warmItems;
+        if (!items)
+            return; // `stopGpuPrewarm`/`dispose` 已摘牌 ⇒ 本项作废
+        if (this.visible) { // 已经亮起来了（进厅）⇒ 不再和真实那帧抢额度
+            this._finishGpuPrewarm();
+            return;
+        }
+        if (!items.length && this._collectWarmItems() === 0) { // 排空了：先补扫（GLB、后绑的图都是晚到的），真没有才收尾
+            this._finishGpuPrewarm();
+            return;
+        }
+        const it = items.shift();
+        const scene = this._ensureWarmScene();
+        let proxy = it.p;
+        if (!proxy) {
+            // 替身 = **原对象自己克隆一颗**（⛔ 自造裸 `Mesh`）：`instancing`/`skinning`/`morphTargets` 都进缓存键，
+            //   裸 Mesh 画实例化材质编的是非实例化那一份 = 白编。克隆体与宿主共享同一份 `geometry`/`material` 对象
+            //   ⇒ 编的是同一个 program、传的是同一个顶点缓冲。子树不要（`recursive = false`）：一件只画一颗。
+            proxy = it.p = it.src.clone(false);
+            proxy.visible = true; // 宿主那颗此刻多半还是 `visible = false` ⇒ 替身得进得了 `projectObject`
+            proxy.frustumCulled = false; // 墙几何是世界坐标、体量又比这 2×2 的取景框大得多 ⇒ 别按包围球剔除
+        }
+        if (it.src.isInstancedMesh) {
+            const src = it.src;
+            const inst = proxy;
+            // `clone()` 里的 `instanceMatrix.copy(...)` 是**快照**（另起一份 Float32Array）⇒ 改回指宿主那一份：
+            // 上传的就是进厅要用的那个 buffer，晚到的落位改动也一起带上
+            inst.instanceMatrix = src.instanceMatrix;
+            inst.count = src.count;
+        }
+        if (this._warmActive && this._warmActive !== proxy)
+            scene.remove(this._warmActive); // 一帧只画这一件
+        if (proxy.parent !== scene)
+            scene.add(proxy);
+        this._warmActive = proxy;
+        const prevTarget = renderer.getRenderTarget();
+        renderer.setRenderTarget(this._warmRt);
+        renderer.render(scene, GPU_WARM_CAMERA);
+        renderer.setRenderTarget(prevTarget);
+        this._scheduleGpuWarmStep(renderer);
+    }
+    /**
+     * 造（并记住）预热那间小屋子：只建一次。
+     * `fog` / `environment` 照抄、宿主的灯**逐盏克隆**摆进来 —— 这三样都进 program 缓存键，
+     *   少一样就是编出一份进厅用不上的 program。
+     */
+    _ensureWarmScene() {
+        if (this._warmScene)
+            return this._warmScene;
+        const scene = new Scene();
+        const lights = [];
+        const host = this._findHostScene();
+        if (host) {
+            scene.fog = host.fog; // `USE_FOG` 进键
+            scene.environment = host.environment; // `envMap` 进键（Standard 那族吃场景环境图）
+            const walk = (o) => {
+                if (!o.visible)
+                    return; // 与 three 的 `projectObject` 同一道闸：此刻不计数的灯，进厅那份 define 组里也没有
+                const light = o;
+                if (light.isLight) {
+                    const clone = light.clone(true);
+                    // `light.clone()` 里 `shadow = source.shadow.clone()` ⇒ 克隆体自带一份**新的** shadow
+                    //   （边长、bias、投影相机范围都照抄，实测不与宿主共享），所以这里只管把它压小；
+                    //   压小的理由与「为什么压了还编得出同一份 program」都写在 `GPU_WARM_SHADOW_MAP_SIZE` 上。
+                    const shadow = clone.shadow;
+                    if (shadow?.mapSize)
+                        shadow.mapSize.set(GPU_WARM_SHADOW_MAP_SIZE, GPU_WARM_SHADOW_MAP_SIZE);
+                    // target 同样是新克隆的一份（位置一起带过来）⇒ 挂进这间屋子，`updateMatrixWorld` 才走得到它、
+                    //   光照方向才与宿主一致。⛔ 不许把宿主那颗挂过来：`Object3D.add` 会先从原父节点 `remove`，
+                    //   楼外那圈自由视角的阴影当场就被摘歪了。
+                    const target = clone.target;
+                    if (target)
+                        scene.add(target);
+                    scene.add(clone);
+                    lights.push(clone);
+                }
+                for (const child of o.children)
+                    walk(child);
+            };
+            walk(host);
+        }
+        this._warmLights = lights;
+        this._warmScene = scene;
+        if (!this._warmRt)
+            this._warmRt = new WebGLRenderTarget(1, 1);
+        return scene;
+    }
+    /** 沿 `parent` 往上找到的第一个 Scene = 宿主场景（本站是 `largeScreenRender` 那一棵）。 */
+    _findHostScene() {
+        for (let p = this.parent; p; p = p.parent) {
+            if (p.isScene)
+                return p;
+        }
+        return null;
+    }
+    /**
+     * 收尾（跑完 / 进厅 / 宿主叫停 / `dispose` 四条路都汇到这里）：清单作废 + 临时资源拆掉。
+     *
+     * ⚠️ **不动 `_warmSeen`**：自然跑完那一路后面还会有内容落位（GLB、后绑的瓦片），补排时全靠这张表跳过已经画过的旧档
+     *   —— 清掉它等于把同一批东西再画一遍。真正的「摘牌」只有 `stopGpuPrewarm`/`dispose`，它们先把这颗归 null。
+     */
+    _finishGpuPrewarm() {
+        this._warmItems = null;
+        this._releaseWarmHarness();
+    }
+    /**
+     * 拆掉预热那套临时资源（1×1 渲染目标 + 克隆的灯 + 小场景）。
+     * 替身只是从小屋子里摘出来 —— 它的 `geometry`/`material` 都是宿主那一份对象 ⇒ ⛔ 在此 dispose，会把展厅要用的资源释放掉。
+     */
+    _releaseWarmHarness() {
+        if (this._warmRt)
+            this._warmRt.dispose();
+        this._warmRt = null;
+        for (const light of this._warmLights || []) {
+            const shadow = light.shadow;
+            if (shadow?.dispose)
+                shadow.dispose(); // 放掉的是克隆体自己那张阴影图（`clone()` 给的是新 shadow）
+        }
+        this._warmLights = null;
+        if (this._warmScene)
+            this._warmScene.clear(); // 只摘孩子（替身、克隆灯、灯的 target）
+        this._warmScene = null;
+        this._warmActive = null;
+    }
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName) {
@@ -1442,6 +1714,9 @@ export default class MktMesh extends Mesh {
         this._imgBindDone.clear();
         this._modelMountQueued.clear();
         this._revealPending = [];
+        // 隐藏期预热：清单、去重表与小屋子那套临时资源随本对象一起退场（那张 1×1 渲染目标是本类**唯一**自建的 RT）。
+        // 走 `stopGpuPrewarm` 而不是 `_finishGpuPrewarm`：本对象都要没了，去重表再留着就是泄漏。
+        this.stopGpuPrewarm();
         this._stitcher.dispose();
         this._glRenderer = null;
         if (this._placeholder)