three-base 2.0.196 → 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

@@ -163,14 +163,19 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      */
     private _revealPending;
     /**
-     * 隐藏期 GPU 预热的在册清单（元素 = 一个「材质 × 几何」组合，也就是一个会进渲染列表的物件）。
+     * 隐藏期 GPU 预热的在册清单（元素 = 一个「会进渲染列表的物件」，即它的材质组合 × 几何）。
      * null = 没在预热（未启动 / 已跑完 / `stopGpuPrewarm` / `dispose` 四种都是它）。
      */
     private _warmItems;
-    /** 预热用的小场景：只装 `_warmProxy` 一颗，宿主场景的 `fog` 抄过来（fog 进 program 缓存键） */
+    /** 已收过的去重键（`几何 × 材质数组 × 各材质的 map`）⇒ 跨轮次只补收新出现的组合，不重复编同一条 GL 路径。
+     *  自然收尾时**故意留着**（晚到的内容补排时靠它跳过旧档）；只有 `stopGpuPrewarm`/`dispose` 把它归 null = 摘牌。 */
+    private _warmSeen;
+    /** 预热用的小场景：只挂当前这一件的替身 + 宿主灯光的克隆，`fog`/`environment` 照抄（都进 program 缓存键） */
     private _warmScene;
-    /** 预热用的替身物件：每次把在册那一件的 `material`/`geometry` 原对象赋给它再画一次 */
-    private _warmProxy;
+    /** 此刻挂在预热小场景里的那一颗替身（一帧只画一件 ⇒ 换件时先把上一颗摘下来） */
+    private _warmActive;
+    /** 预热小场景里的那几盏灯 = 宿主灯的克隆体（各持一份 `shadow` ⇒ 收尾时释放的是它们自己的阴影图，碰不到宿主的） */
+    private _warmLights;
     /** 预热落点：1×1 渲染目标（只有像素不要，要的是「这条 GL 路径确实走完了」），随预热结束/dispose 释放 */
     private _warmRt;
     constructor(opts?: {
@@ -411,7 +416,7 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      */
     tickProgressiveReveal(): void;
     /**
-     * 开始隐藏期预热：把「进厅第一帧要现编的那份墙着色器」提前编掉，一帧只放**一件**。
+     * 开始隐藏期预热：把「进厅第一帧要现编的那些 program + 要第一次上传的那些几何/纹理」提前跑掉，一帧只放**一件**。
      *
      * 为什么必须在隐藏期做：`visible = false` 时 three 的遍历第一句就 `if (object.visible === false) return`
      *   （与上面 `tickProgressiveReveal` 注释同一颗雷）⇒ 墙根本进不了渲染列表，那份大 shader 从来没进过
@@ -424,22 +429,67 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *   编出来的正是同一份 program（three 的缓存按 `材质 × 几何属性形态 × 场景光照/雾` 计键），
      *   顶点缓冲也真上了 GPU；那 1×1 的像素直接扔掉，不占显存、不污染画面。
      *
-     * ⚠️ 只收**不带灯**的材质（墙的 mapping ShaderMaterial、图片平面的 MeshBasicMaterial）：预热那间小屋子里没有灯，
-     *   带灯材质（GLB 那些 Lambert/Standard）在这儿编出来的 define 组（方向光数、阴影开关…）与真实场景那份
-     *   不是同一个 program，白编一遍还挤缓存。那一族本来就由 `tickProgressiveReveal` 在进厅后一帧放一颗，
-     *   亮出来的那一帧就是它们的预热帧 ⇒ 这次一字未动。
+     * ⚠️ 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;
-    /** 拆掉预热那套临时资源（1×1 渲染目标 + 小场景 + 替身）；清单本身由调用方置 null。 */
+    /**
+     * 造（并记住）预热那间小屋子：只建一次。
+     * `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` */

package/MktMesh/MktMesh.js

@@ -56,6 +56,18 @@ import { ImagePlaneTileLoader } from "./imageTileLoader";
 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 = [];
@@ -224,14 +236,19 @@ export default class MktMesh extends Mesh {
      */
     _revealPending = [];
     /**
-     * 隐藏期 GPU 预热的在册清单（元素 = 一个「材质 × 几何」组合，也就是一个会进渲染列表的物件）。
+     * 隐藏期 GPU 预热的在册清单（元素 = 一个「会进渲染列表的物件」，即它的材质组合 × 几何）。
      * null = 没在预热（未启动 / 已跑完 / `stopGpuPrewarm` / `dispose` 四种都是它）。
      */
     _warmItems = null;
-    /** 预热用的小场景：只装 `_warmProxy` 一颗，宿主场景的 `fog` 抄过来（fog 进 program 缓存键） */
+    /** 已收过的去重键（`几何 × 材质数组 × 各材质的 map`）⇒ 跨轮次只补收新出现的组合，不重复编同一条 GL 路径。
+     *  自然收尾时**故意留着**（晚到的内容补排时靠它跳过旧档）；只有 `stopGpuPrewarm`/`dispose` 把它归 null = 摘牌。 */
+    _warmSeen = null;
+    /** 预热用的小场景：只挂当前这一件的替身 + 宿主灯光的克隆，`fog`/`environment` 照抄（都进 program 缓存键） */
     _warmScene = null;
-    /** 预热用的替身物件：每次把在册那一件的 `material`/`geometry` 原对象赋给它再画一次 */
-    _warmProxy = null;
+    /** 此刻挂在预热小场景里的那一颗替身（一帧只画一件 ⇒ 换件时先把上一颗摘下来） */
+    _warmActive = null;
+    /** 预热小场景里的那几盏灯 = 宿主灯的克隆体（各持一份 `shadow` ⇒ 收尾时释放的是它们自己的阴影图，碰不到宿主的） */
+    _warmLights = null;
     /** 预热落点：1×1 渲染目标（只有像素不要，要的是「这条 GL 路径确实走完了」），随预热结束/dispose 释放 */
     _warmRt = null;
     constructor(opts = {}) {
@@ -1203,6 +1220,8 @@ export default class MktMesh extends Mesh {
             return;
         if (ms.mountStaged() && onEachLoad)
             onEachLoad();
+        // 挂进来的那一族此刻才在子树里 ⇒ 补排预热（清单已排空时，这一颗是重新开工的唯一触发点）
+        this._topUpGpuPrewarm();
     }
     /**
      * 把各颗平面那 4 张瓦片的纹理绑进材质（10-22 晚定的口径：不走拼合器 RT）。
@@ -1264,6 +1283,9 @@ export default class MktMesh extends Mesh {
             }
         }
         ip.setTileTextures(texs, insets);
+        // 瓦片是一张一张就绪的 ⇒ 每绑上一张，这一颗的「待画纹理」就换一档（去重键带绑定戳记）⇒ 补排一次，
+        // 让上传发生在隐藏期而不是进厅那一帧。
+        this._topUpGpuPrewarm();
         if (pending) {
             this._queueImagePlaneBind(ip);
             return;
@@ -1291,7 +1313,7 @@ export default class MktMesh extends Mesh {
     }
     // ─────────────────── 隐藏期 GPU 预热（2026-11-01 需求：进厅那一下不要再现编着色器） ───────────────────
     /**
-     * 开始隐藏期预热：把「进厅第一帧要现编的那份墙着色器」提前编掉，一帧只放**一件**。
+     * 开始隐藏期预热：把「进厅第一帧要现编的那些 program + 要第一次上传的那些几何/纹理」提前跑掉，一帧只放**一件**。
      *
      * 为什么必须在隐藏期做：`visible = false` 时 three 的遍历第一句就 `if (object.visible === false) return`
      *   （与上面 `tickProgressiveReveal` 注释同一颗雷）⇒ 墙根本进不了渲染列表，那份大 shader 从来没进过
@@ -1304,10 +1326,22 @@ export default class MktMesh extends Mesh {
      *   编出来的正是同一份 program（three 的缓存按 `材质 × 几何属性形态 × 场景光照/雾` 计键），
      *   顶点缓冲也真上了 GPU；那 1×1 的像素直接扔掉，不占显存、不污染画面。
      *
-     * ⚠️ 只收**不带灯**的材质（墙的 mapping ShaderMaterial、图片平面的 MeshBasicMaterial）：预热那间小屋子里没有灯，
-     *   带灯材质（GLB 那些 Lambert/Standard）在这儿编出来的 define 组（方向光数、阴影开关…）与真实场景那份
-     *   不是同一个 program，白编一遍还挤缓存。那一族本来就由 `tickProgressiveReveal` 在进厅后一帧放一颗，
-     *   亮出来的那一帧就是它们的预热帧 ⇒ 这次一字未动。
+     * ⚠️ 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)`，它本来就是隐藏期的入口）
@@ -1320,38 +1354,68 @@ export default class MktMesh extends Mesh {
         this._glRenderer = renderer;
         if (this._warmItems)
             return; // 已在预热 ⇒ ⛔ 不重建清单（重复点会打断还没跑的那几件）
-        const items = [];
-        const seen = new Set();
+        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 m = mesh.material;
             const g = mesh.geometry;
-            if (!m || !g)
-                return;
-            // 白名单，不是黑名单：r167 里「带不带灯」不再写在 `material.lights` 上（除 ShaderMaterial 之外全是 undefined），
-            // 只有这两个是本站这条链上确定不吃场景光照的 ⇒ 别的材质类型一律不收。
-            if (!m.isShaderMaterial && !m.isMeshBasicMaterial)
-                return;
-            // 平面的图还没绑上（`map` 这一档还空着）⇒ 跳过：那样编出来的是 `USE_MAP` 关闭的那一份，
-            //   与绑上图后真正要用的不是同一个 program，白编（绑图那一拍会重新排进 `_imgBindQueued`，照样亮得出）。
-            const withMap = m;
-            if ("map" in withMap && !withMap.map)
+            if (!g)
                 return;
-            const key = `${m.id}:${g.id}`;
+            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; // 同一份材质 + 同一份几何 = 同一个 program，画一次就够
+                return;
             seen.add(key);
-            items.push({ m, g });
+            items.push({ src: o, m: mesh.material, g });
+            added++;
         });
-        this._warmItems = items;
-        this._scheduleGpuWarmStep(renderer);
-    }
-    /** 停止隐藏期预热（宿主进入展厅时调）：剩下的清单直接作废 —— 亮出来那一帧本来就要编要传，不必再抢额度。 */
-    stopGpuPrewarm() {
-        this._warmItems = null;
-        this._releaseWarmHarness();
+        return added;
     }
     /** 排下一件：先垫一个空函数占一格（全局队列每 tick 只跑一项 ⇒ 真活落在下一个 tick），与全景上传、平面绑定同一手法。 */
     _scheduleGpuWarmStep(renderer) {
@@ -1364,55 +1428,125 @@ export default class MktMesh extends Mesh {
         if (!items)
             return; // `stopGpuPrewarm`/`dispose` 已摘牌 ⇒ 本项作废
         if (this.visible) { // 已经亮起来了（进厅）⇒ 不再和真实那帧抢额度
-            this._warmItems = null;
-            this._releaseWarmHarness();
+            this._finishGpuPrewarm();
             return;
         }
-        if (!items.length) {
-            this._warmItems = null;
-            this._releaseWarmHarness();
+        if (!items.length && this._collectWarmItems() === 0) { // 排空了：先补扫（GLB、后绑的图都是晚到的），真没有才收尾
+            this._finishGpuPrewarm();
             return;
         }
         const it = items.shift();
-        let proxy = this._warmProxy;
-        let scene = this._warmScene;
-        if (!proxy || !scene) {
-            scene = new Scene();
-            // 雾抄宿主那份：`USE_FOG` 进 MeshBasicMaterial 的 program 缓存键，不抄就是编了一份用不上的。
-            //   宿主场景 = 沿 `parent` 往上找到的第一个 Scene（本站是 `largeScreenRender` 那一棵）。
-            let host = null;
-            for (let p = this.parent; p; p = p.parent) {
-                if (p.isScene) {
-                    host = p;
-                    break;
-                }
-            }
-            scene.fog = host ? host.fog : null;
-            proxy = new Mesh();
+        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 的取景框大得多 ⇒ 别按包围球剔除
-            scene.add(proxy);
-            this._warmScene = scene;
-            this._warmProxy = proxy;
         }
-        if (!this._warmRt)
-            this._warmRt = new WebGLRenderTarget(1, 1);
-        proxy.geometry = it.g;
-        proxy.material = it.m;
+        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);
     }
-    /** 拆掉预热那套临时资源（1×1 渲染目标 + 小场景 + 替身）；清单本身由调用方置 null。 */
+    /**
+     * 造（并记住）预热那间小屋子：只建一次。
+     * `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;
-        if (this._warmScene && this._warmProxy)
-            this._warmScene.remove(this._warmProxy);
+        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._warmProxy = null;
+        this._warmActive = null;
     }
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
@@ -1580,9 +1714,9 @@ export default class MktMesh extends Mesh {
         this._imgBindDone.clear();
         this._modelMountQueued.clear();
         this._revealPending = [];
-        // ⭐ 2026-11-01 隐藏期预热：清单与小那套临时资源随本对象一起退场（那张 1×1 渲染目标是本类**唯一**自建的 RT）
-        this._warmItems = null;
-        this._releaseWarmHarness();
+        // 隐藏期预热：清单、去重表与小屋子那套临时资源随本对象一起退场（那张 1×1 渲染目标是本类**唯一**自建的 RT）。
+        // 走 `stopGpuPrewarm` 而不是 `_finishGpuPrewarm`：本对象都要没了，去重表再留着就是泄漏。
+        this.stopGpuPrewarm();
         this._stitcher.dispose();
         this._glRenderer = null;
         if (this._placeholder)

package/MktMesh/MktMesh.ts

@@ -29,6 +29,8 @@ import {
     Camera,
     BackSide,
     Float32BufferAttribute,
+    InstancedMesh,
+    Light,
     Material,
     Matrix4,
     Object3D,
@@ -83,6 +85,23 @@ 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;
+
+/** 只取预热要动的那两颗字段（`LightShadow` 的类型名不在这页的导入清单里，结构类型够用且不必扩面）。 */
+type WarmShadow = { mapSize?: { set(w: number, h: number): unknown }; dispose?(): void };
+
+/** 「同一件」判据里要看的那张主图 id：ShaderMaterial 那一族没有 `map` 这一档 ⇒ 恒 0；图片平面绑上图才换一档。 */
+const warmMapId = (m: Material): number => (m as Material & { map?: Texture | null }).map?.id ?? 0;
+
 export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
     textures: MktTextureInfo[] = [];
@@ -257,14 +276,19 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     private _revealPending: Array<ImagePlane | ModelSlot> = [];
 
     /**
-     * 隐藏期 GPU 预热的在册清单（元素 = 一个「材质 × 几何」组合，也就是一个会进渲染列表的物件）。
+     * 隐藏期 GPU 预热的在册清单（元素 = 一个「会进渲染列表的物件」，即它的材质组合 × 几何）。
      * null = 没在预热（未启动 / 已跑完 / `stopGpuPrewarm` / `dispose` 四种都是它）。
      */
-    private _warmItems: Array<{ m: Material; g: BufferGeometry }> | null = null;
-    /** 预热用的小场景：只装 `_warmProxy` 一颗，宿主场景的 `fog` 抄过来（fog 进 program 缓存键） */
+    private _warmItems: Array<{ src: Object3D; m: Material | Material[]; g: BufferGeometry; p?: Object3D }> | null = null;
+    /** 已收过的去重键（`几何 × 材质数组 × 各材质的 map`）⇒ 跨轮次只补收新出现的组合，不重复编同一条 GL 路径。
+     *  自然收尾时**故意留着**（晚到的内容补排时靠它跳过旧档）；只有 `stopGpuPrewarm`/`dispose` 把它归 null = 摘牌。 */
+    private _warmSeen: Set<string> | null = null;
+    /** 预热用的小场景：只挂当前这一件的替身 + 宿主灯光的克隆，`fog`/`environment` 照抄（都进 program 缓存键） */
     private _warmScene: Scene | null = null;
-    /** 预热用的替身物件：每次把在册那一件的 `material`/`geometry` 原对象赋给它再画一次 */
-    private _warmProxy: Mesh | null = null;
+    /** 此刻挂在预热小场景里的那一颗替身（一帧只画一件 ⇒ 换件时先把上一颗摘下来） */
+    private _warmActive: Object3D | null = null;
+    /** 预热小场景里的那几盏灯 = 宿主灯的克隆体（各持一份 `shadow` ⇒ 收尾时释放的是它们自己的阴影图，碰不到宿主的） */
+    private _warmLights: Light[] | null = null;
     /** 预热落点：1×1 渲染目标（只有像素不要，要的是「这条 GL 路径确实走完了」），随预热结束/dispose 释放 */
     private _warmRt: WebGLRenderTarget | null = null;
 
@@ -1243,6 +1267,8 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         // 槽已退场（换项目 / 删除）：待挂那棵由 `ModelSlot.dispose` → `_detachModel` 当场释放，这里不挂
         if (!this.models.includes(ms)) return;
         if (ms.mountStaged() && onEachLoad) onEachLoad();
+        // 挂进来的那一族此刻才在子树里 ⇒ 补排预热（清单已排空时，这一颗是重新开工的唯一触发点）
+        this._topUpGpuPrewarm();
     }
 
     /**
@@ -1300,6 +1326,9 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             }
         }
         ip.setTileTextures(texs, insets);
+        // 瓦片是一张一张就绪的 ⇒ 每绑上一张，这一颗的「待画纹理」就换一档（去重键带绑定戳记）⇒ 补排一次，
+        // 让上传发生在隐藏期而不是进厅那一帧。
+        this._topUpGpuPrewarm();
         if (pending) {
             this._queueImagePlaneBind(ip);
             return;
@@ -1329,7 +1358,7 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     // ─────────────────── 隐藏期 GPU 预热（2026-11-01 需求：进厅那一下不要再现编着色器） ───────────────────
 
     /**
-     * 开始隐藏期预热：把「进厅第一帧要现编的那份墙着色器」提前编掉，一帧只放**一件**。
+     * 开始隐藏期预热：把「进厅第一帧要现编的那些 program + 要第一次上传的那些几何/纹理」提前跑掉，一帧只放**一件**。
      *
      * 为什么必须在隐藏期做：`visible = false` 时 three 的遍历第一句就 `if (object.visible === false) return`
      *   （与上面 `tickProgressiveReveal` 注释同一颗雷）⇒ 墙根本进不了渲染列表，那份大 shader 从来没进过
@@ -1342,10 +1371,22 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *   编出来的正是同一份 program（three 的缓存按 `材质 × 几何属性形态 × 场景光照/雾` 计键），
      *   顶点缓冲也真上了 GPU；那 1×1 的像素直接扔掉，不占显存、不污染画面。
      *
-     * ⚠️ 只收**不带灯**的材质（墙的 mapping ShaderMaterial、图片平面的 MeshBasicMaterial）：预热那间小屋子里没有灯，
-     *   带灯材质（GLB 那些 Lambert/Standard）在这儿编出来的 define 组（方向光数、阴影开关…）与真实场景那份
-     *   不是同一个 program，白编一遍还挤缓存。那一族本来就由 `tickProgressiveReveal` 在进厅后一帧放一颗，
-     *   亮出来的那一帧就是它们的预热帧 ⇒ 这次一字未动。
+     * ⚠️ 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)`，它本来就是隐藏期的入口）
@@ -1356,35 +1397,65 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         //（原先 `_glRenderer` 只在 `onBeforeRender` 里捕获 ⇒ 隐藏期排上的队全走「three 自己绑」的降级路）。
         this._glRenderer = renderer;
         if (this._warmItems) return; // 已在预热 ⇒ ⛔ 不重建清单（重复点会打断还没跑的那几件）
+        this._warmItems = [];
+        this._warmSeen = new Set<string>();
+        this._collectWarmItems();
+        this._scheduleGpuWarmStep(renderer);
+    }
+
+    /** 停止隐藏期预热（宿主进入展厅时调）：剩下的清单直接作废并**摘牌** —— 亮出来那一帧本来就要编要传，不必再抢额度；摘牌后晚到的内容也不再来补排。 */
+    stopGpuPrewarm(): void {
+        this._warmSeen = null; // 这颗就是「摘牌」本身：`_topUpGpuPrewarm` 只认它
+        this._finishGpuPrewarm();
+    }
+
+    /**
+     * 内容后落位时补排预热（GLB 挂进子树那一拍、平面绑上瓦片纹理那一拍各调一次）。
+     *
+     * 为什么必须有这一颗：预热是隐藏期跑的，而隐藏期里展厅的内容**还没长齐** —— GLB 十几只各走一条异步下载链、
+     *   逐帧只挂一颗，平面那 4 格图也是逐张就绪逐张绑。一次性清单在几拍之内就排空了 ⇒ 晚到的那一族一件都没被画过，
+     *   进厅那一帧照样现编现传（这就是第一版「预热跑了、人还是卡了一下」的根）。
+     *
+     * 只在隐藏期响应：`_warmSeen` 归 null = 宿主已叫停（进厅）⇒ 晚到的东西交给「逐帧点亮」那一拍自己编，⛔ 别再抢额度。
+     */
+    private _topUpGpuPrewarm(): void {
+        if (!this._warmSeen || this.visible) return;
+        if (!this._warmItems) {
+            this._warmItems = []; // 上一轮已经收尾 ⇒ 重新开工（去重表还在 ⇒ 只补新出现的那几档，旧的不会重画）
+            this._scheduleGpuWarmStep(this._glRenderer!); // `_warmSeen` 非空 ⇒ `startGpuPrewarm` 早已把渲染器交进来
+        }
+        this._collectWarmItems();
+    }
 
-        const items: Array<{ m: Material; g: BufferGeometry }> = [];
-        const seen = new Set<string>();
+    /**
+     * 扫一遍本对象的子树，把「还没收过的那一档」压进清单。
+     * @returns 这次新收了几个（0 = 确实没有新东西 ⇒ 调用方据此收尾，⛔ 不是每帧空转）
+     */
+    private _collectWarmItems(): number {
+        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 as Mesh;
             if (!mesh.isMesh) return;
-            const m = mesh.material as Material;
             const g = mesh.geometry as BufferGeometry;
-            if (!m || !g) return;
-            // 白名单，不是黑名单：r167 里「带不带灯」不再写在 `material.lights` 上（除 ShaderMaterial 之外全是 undefined），
-            // 只有这两个是本站这条链上确定不吃场景光照的 ⇒ 别的材质类型一律不收。
-            if (!(m as ShaderMaterial).isShaderMaterial && !(m as Material & { isMeshBasicMaterial?: boolean }).isMeshBasicMaterial) return;
-            // 平面的图还没绑上（`map` 这一档还空着）⇒ 跳过：那样编出来的是 `USE_MAP` 关闭的那一份，
-            //   与绑上图后真正要用的不是同一个 program，白编（绑图那一拍会重新排进 `_imgBindQueued`，照样亮得出）。
-            const withMap = m as Material & { map?: Texture | null };
-            if ("map" in withMap && !withMap.map) return;
-            const key = `${m.id}:${g.id}`;
-            if (seen.has(key)) return; // 同一份材质 + 同一份几何 = 同一个 program，画一次就够
+            if (!g) return;
+            const mats = (Array.isArray(mesh.material) ? mesh.material : [mesh.material]) as 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 as ImagePlane).tilesBindingStamp()}` : "");
+            if (seen.has(key)) return;
             seen.add(key);
-            items.push({ m, g });
+            items.push({ src: o, m: mesh.material as Material | Material[], g });
+            added++;
         });
-        this._warmItems = items;
-        this._scheduleGpuWarmStep(renderer);
-    }
-
-    /** 停止隐藏期预热（宿主进入展厅时调）：剩下的清单直接作废 —— 亮出来那一帧本来就要编要传，不必再抢额度。 */
-    stopGpuPrewarm(): void {
-        this._warmItems = null;
-        this._releaseWarmHarness();
+        return added;
     }
 
     /** 排下一件：先垫一个空函数占一格（全局队列每 tick 只跑一项 ⇒ 真活落在下一个 tick），与全景上传、平面绑定同一手法。 */
@@ -1398,50 +1469,117 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         const items = this._warmItems;
         if (!items) return; // `stopGpuPrewarm`/`dispose` 已摘牌 ⇒ 本项作废
         if (this.visible) { // 已经亮起来了（进厅）⇒ 不再和真实那帧抢额度
-            this._warmItems = null;
-            this._releaseWarmHarness();
+            this._finishGpuPrewarm();
             return;
         }
-        if (!items.length) {
-            this._warmItems = null;
-            this._releaseWarmHarness();
+        if (!items.length && this._collectWarmItems() === 0) { // 排空了：先补扫（GLB、后绑的图都是晚到的），真没有才收尾
+            this._finishGpuPrewarm();
             return;
         }
         const it = items.shift()!;
-        let proxy = this._warmProxy;
-        let scene = this._warmScene;
-        if (!proxy || !scene) {
-            scene = new Scene();
-            // 雾抄宿主那份：`USE_FOG` 进 MeshBasicMaterial 的 program 缓存键，不抄就是编了一份用不上的。
-            //   宿主场景 = 沿 `parent` 往上找到的第一个 Scene（本站是 `largeScreenRender` 那一棵）。
-            let host: Scene | null = null;
-            for (let p: Object3D | null = this.parent; p; p = p.parent) {
-                if ((p as Scene).isScene) { host = p as Scene; break; }
-            }
-            scene.fog = host ? host.fog : null;
-            proxy = new Mesh();
+        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 的取景框大得多 ⇒ 别按包围球剔除
-            scene.add(proxy);
-            this._warmScene = scene;
-            this._warmProxy = proxy;
         }
-        if (!this._warmRt) this._warmRt = new WebGLRenderTarget(1, 1);
-        proxy.geometry = it.g;
-        proxy.material = it.m;
+        if ((it.src as InstancedMesh).isInstancedMesh) {
+            const src = it.src as InstancedMesh;
+            const inst = proxy as InstancedMesh;
+            // `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.setRenderTarget(this._warmRt!);
         renderer.render(scene, GPU_WARM_CAMERA);
         renderer.setRenderTarget(prevTarget);
         this._scheduleGpuWarmStep(renderer);
     }
 
-    /** 拆掉预热那套临时资源（1×1 渲染目标 + 小场景 + 替身）；清单本身由调用方置 null。 */
+    /**
+     * 造（并记住）预热那间小屋子：只建一次。
+     * `fog` / `environment` 照抄、宿主的灯**逐盏克隆**摆进来 —— 这三样都进 program 缓存键，
+     *   少一样就是编出一份进厅用不上的 program。
+     */
+    private _ensureWarmScene(): Scene {
+        if (this._warmScene) return this._warmScene;
+        const scene = new Scene();
+        const lights: Light[] = [];
+        const host = this._findHostScene();
+        if (host) {
+            scene.fog = host.fog; // `USE_FOG` 进键
+            scene.environment = host.environment; // `envMap` 进键（Standard 那族吃场景环境图）
+            const walk = (o: Object3D) => {
+                if (!o.visible) return; // 与 three 的 `projectObject` 同一道闸：此刻不计数的灯，进厅那份 define 组里也没有
+                const light = o as Light;
+                if (light.isLight) {
+                    const clone = light.clone(true) as Light;
+                    // `light.clone()` 里 `shadow = source.shadow.clone()` ⇒ 克隆体自带一份**新的** shadow
+                    //   （边长、bias、投影相机范围都照抄，实测不与宿主共享），所以这里只管把它压小；
+                    //   压小的理由与「为什么压了还编得出同一份 program」都写在 `GPU_WARM_SHADOW_MAP_SIZE` 上。
+                    const shadow = (clone as unknown as { shadow?: WarmShadow }).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 as unknown as { target?: Object3D }).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` 那一棵）。 */
+    private _findHostScene(): Scene | null {
+        for (let p: Object3D | null = this.parent; p; p = p.parent) {
+            if ((p as Scene).isScene) return p as Scene;
+        }
+        return null;
+    }
+
+    /**
+     * 收尾（跑完 / 进厅 / 宿主叫停 / `dispose` 四条路都汇到这里）：清单作废 + 临时资源拆掉。
+     *
+     * ⚠️ **不动 `_warmSeen`**：自然跑完那一路后面还会有内容落位（GLB、后绑的瓦片），补排时全靠这张表跳过已经画过的旧档
+     *   —— 清掉它等于把同一批东西再画一遍。真正的「摘牌」只有 `stopGpuPrewarm`/`dispose`，它们先把这颗归 null。
+     */
+    private _finishGpuPrewarm(): void {
+        this._warmItems = null;
+        this._releaseWarmHarness();
+    }
+
+    /**
+     * 拆掉预热那套临时资源（1×1 渲染目标 + 克隆的灯 + 小场景）。
+     * 替身只是从小屋子里摘出来 —— 它的 `geometry`/`material` 都是宿主那一份对象 ⇒ ⛔ 在此 dispose，会把展厅要用的资源释放掉。
+     */
     private _releaseWarmHarness(): void {
         if (this._warmRt) this._warmRt.dispose();
         this._warmRt = null;
-        if (this._warmScene && this._warmProxy) this._warmScene.remove(this._warmProxy);
+        for (const light of this._warmLights || []) {
+            const shadow = (light as unknown as { shadow?: WarmShadow }).shadow;
+            if (shadow?.dispose) shadow.dispose(); // 放掉的是克隆体自己那张阴影图（`clone()` 给的是新 shadow）
+        }
+        this._warmLights = null;
+        if (this._warmScene) this._warmScene.clear(); // 只摘孩子（替身、克隆灯、灯的 target）
         this._warmScene = null;
-        this._warmProxy = null;
+        this._warmActive = null;
     }
 
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
@@ -1617,9 +1755,9 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         this._imgBindDone.clear();
         this._modelMountQueued.clear();
         this._revealPending = [];
-        // ⭐ 2026-11-01 隐藏期预热：清单与小那套临时资源随本对象一起退场（那张 1×1 渲染目标是本类**唯一**自建的 RT）
-        this._warmItems = null;
-        this._releaseWarmHarness();
+        // 隐藏期预热：清单、去重表与小屋子那套临时资源随本对象一起退场（那张 1×1 渲染目标是本类**唯一**自建的 RT）。
+        // 走 `stopGpuPrewarm` 而不是 `_finishGpuPrewarm`：本对象都要没了，去重表再留着就是泄漏。
+        this.stopGpuPrewarm();
         this._stitcher.dispose();
         this._glRenderer = null;
         if (this._placeholder) this._placeholder.dispose();

package/MktMesh/modelSlot.js

@@ -195,6 +195,9 @@ export class ModelSlot extends Group {
             return false;
         }
         if (!obj) {
+            // 画面停在占位方块之外，还要让页面知道「这一颗没出来」：报进加载状态那唯一出口，带上槽名。
+            // 同一地址重复失败由 `threeLoader.reportLoadError` 去重（下载本身失败已由 manager 计过一次 ⇒ 这里只补「是哪颗槽」）。
+            threeLoader.reportLoadError(url, "model", this.name);
             this._loaded = true;
             this._layout();
             return false;

package/MktMesh/modelSlot.ts

@@ -233,6 +233,9 @@ export class ModelSlot extends Group {
             return false;
         }
         if (!obj) {
+            // 画面停在占位方块之外，还要让页面知道「这一颗没出来」：报进加载状态那唯一出口，带上槽名。
+            // 同一地址重复失败由 `threeLoader.reportLoadError` 去重（下载本身失败已由 manager 计过一次 ⇒ 这里只补「是哪颗槽」）。
+            threeLoader.reportLoadError(url, "model", this.name);
             this._loaded = true;
             this._layout();
             return false;

package/MktMesh/panoBitmapTexture.js

@@ -1,4 +1,5 @@
 import { DefaultLoadingManager, Texture } from "three";
+import threeLoader from "../threeLoader";
 /**
  * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
  *
@@ -25,8 +26,11 @@ export function loadPanoTexture(url) {
     DefaultLoadingManager.itemStart(url);
     const task = fetch(url)
         .then((res) => {
-        if (!res.ok)
+        // 状态码先记进 `threeLoader`（页面据此分「服务器明说没有」与「断网」：前者才敢删那条数据）
+        if (!res.ok) {
+            threeLoader.markUrlStatus(url, res.status);
             throw new Error(`HTTP ${res.status}`);
+        }
         return res.blob();
     })
         .then((blob) => createImageBitmap(blob, {

package/MktMesh/panoBitmapTexture.ts

@@ -1,4 +1,5 @@
 import { DefaultLoadingManager, Texture } from "three";
+import threeLoader from "../threeLoader";
 
 /**
  * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
@@ -27,7 +28,11 @@ export function loadPanoTexture(url: string): Promise<Texture> {
     DefaultLoadingManager.itemStart(url);
     const task = fetch(url)
         .then((res) => {
-            if (!res.ok) throw new Error(`HTTP ${res.status}`);
+            // 状态码先记进 `threeLoader`（页面据此分「服务器明说没有」与「断网」：前者才敢删那条数据）
+            if (!res.ok) {
+                threeLoader.markUrlStatus(url, res.status);
+                throw new Error(`HTTP ${res.status}`);
+            }
             return res.blob();
         })
         .then((blob) =>

package/package.json

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

package/threeLoader.d.ts

@@ -9,6 +9,20 @@ import { PLYLoader } from "three/examples/jsm/Addons";
 import type { ThreeLoaderEventMap } from "./EventMap";
 declare class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
     constructor();
+    /** 已经报过的失败地址（去重只服务「计数」，不影响事件本身 —— 事件仍每次发，页面可按 `isNew` 决定要不要提示） */
+    private _failedUrls;
+    /** 全站累计**失败地址数**（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零 ⇒ 页面自己算「本次」） */
+    loadErrorCount: number;
+    /** 地址 → 服务端回的状态码。只有**拿到过回复**的那两路写得进来：`loadPanoTexture` 的非 2xx（全景整图/32 片切片、平面 4 片）
+     *  与 `loadModel` 的下载失败（GLB 等）。用来把「服务器明说没有」和「断网 / 解码失败」分开 —— 前者页面才敢删数据。 */
+    private _urlStatus;
+    /** 记下一个地址的服务端状态码（键必须与失败上报用的那一个地址串一致） */
+    markUrlStatus(url: string, status: number): void;
+    /** 失败的唯一上报口：`DefaultLoadingManager.onError`（素材那一路）与 `ModelSlot` 那颗 GLB 没出来（模型那一路）都走这里。 */
+    reportLoadError(url: string, kind: "asset" | "model", label?: string): void;
+    /** 从加载器抛出的错误里取 HTTP 状态码，记在**调用方那一个地址**上（`url` 原样，不是内部补全后的地址）。
+     *  three 的 `FileLoader` 非 2xx 抛 `HttpError`（`err.response.status`），个别加载器只把码写进 message。 */
+    private _noteErrStatus;
     getFilename(url: string): string;
     uuid: string;
     anisotropy: number;

package/threeLoader.js

@@ -40,6 +40,12 @@ class ThreeLoader extends EventDispatcher {
         DefaultLoadingManager.onLoad = () => {
             this.onload = true;
         };
+        // 资源加载失败：走 manager 计数的每一条（全景整图/32 片切片、图片平面 4 片、GLB 下载与内嵌贴图）
+        // 都只从这里出，页面侧仍只订本类这一个出口（与 onProgress 同规矩，⛔ 页面不许自己占 manager 的槽位）。
+        // 同一地址去重：全景/平面那两路失败会每帧重发请求 ⇒ 不去重「失败数」会被刷成无穷大。
+        DefaultLoadingManager.onError = (url) => {
+            this.reportLoadError(url, "asset");
+        };
         // 资源替换
         DefaultLoadingManager.setURLModifier((url) => {
             //全路径匹配资源
@@ -58,6 +64,40 @@ class ThreeLoader extends EventDispatcher {
             return new_url;
         });
     }
+    /** 已经报过的失败地址（去重只服务「计数」，不影响事件本身 —— 事件仍每次发，页面可按 `isNew` 决定要不要提示） */
+    _failedUrls = new Set();
+    /** 全站累计**失败地址数**（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零 ⇒ 页面自己算「本次」） */
+    loadErrorCount = 0;
+    /** 地址 → 服务端回的状态码。只有**拿到过回复**的那两路写得进来：`loadPanoTexture` 的非 2xx（全景整图/32 片切片、平面 4 片）
+     *  与 `loadModel` 的下载失败（GLB 等）。用来把「服务器明说没有」和「断网 / 解码失败」分开 —— 前者页面才敢删数据。 */
+    _urlStatus = new Map();
+    /** 记下一个地址的服务端状态码（键必须与失败上报用的那一个地址串一致） */
+    markUrlStatus(url, status) {
+        if (url)
+            this._urlStatus.set(url, status);
+    }
+    /** 失败的唯一上报口：`DefaultLoadingManager.onError`（素材那一路）与 `ModelSlot` 那颗 GLB 没出来（模型那一路）都走这里。 */
+    reportLoadError(url, kind, label) {
+        const isNew = !this._failedUrls.has(url);
+        if (isNew) {
+            this._failedUrls.add(url);
+            this.loadErrorCount++;
+        }
+        const status = this._urlStatus.get(url);
+        // 403 与 404 并一档：OSS 私有桶里「key 不存在」回的正是 403（AccessDenied 用来不泄露对象是否存在）。
+        const missing = status === 404 || status === 403;
+        this.dispatchEvent({ type: "loadError", url, kind, label, status, missing, failed: this.loadErrorCount, isNew });
+    }
+    /** 从加载器抛出的错误里取 HTTP 状态码，记在**调用方那一个地址**上（`url` 原样，不是内部补全后的地址）。
+     *  three 的 `FileLoader` 非 2xx 抛 `HttpError`（`err.response.status`），个别加载器只把码写进 message。 */
+    _noteErrStatus(url, err) {
+        if (!isString(url))
+            return;
+        const e = err;
+        const raw = e?.status ?? e?.response?.status ?? Number(/(?:responded with|HTTP) (\d{3})/.exec(e?.message ?? "")?.[1]);
+        if (Number.isFinite(raw))
+            this.markUrlStatus(url, raw);
+    }
     // 从url 中提取文件名
     getFilename(url) {
         // 移除URL的查询字符串和哈希部分
@@ -364,7 +404,8 @@ class ThreeLoader extends EventDispatcher {
                     });
                     return res;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`);
                     return undefined;
                 });
@@ -381,6 +422,7 @@ class ThreeLoader extends EventDispatcher {
                     return res.scene;
                 })
                     .catch((err) => {
+                    this._noteErrStatus(url, err);
                     // 打印详细错误信息，方便调试
                     console.error(`${url},加载失败`, err);
                     return undefined;
@@ -398,7 +440,8 @@ class ThreeLoader extends EventDispatcher {
                         roughness: 0.5,
                     }));
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`);
                     return undefined;
                 });
@@ -434,7 +477,8 @@ class ThreeLoader extends EventDispatcher {
                     }
                     return plyMesh;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`);
                     return undefined;
                 });
@@ -462,6 +506,7 @@ class ThreeLoader extends EventDispatcher {
                     return res;
                 })
                     .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`, err);
                     return undefined;
                 });

package/threeLoader.ts

@@ -44,6 +44,12 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
         DefaultLoadingManager.onLoad = () => {
             this.onload = true;
         };
+        // 资源加载失败：走 manager 计数的每一条（全景整图/32 片切片、图片平面 4 片、GLB 下载与内嵌贴图）
+        // 都只从这里出，页面侧仍只订本类这一个出口（与 onProgress 同规矩，⛔ 页面不许自己占 manager 的槽位）。
+        // 同一地址去重：全景/平面那两路失败会每帧重发请求 ⇒ 不去重「失败数」会被刷成无穷大。
+        DefaultLoadingManager.onError = (url: string) => {
+            this.reportLoadError(url, "asset");
+        };
         // 资源替换
         DefaultLoadingManager.setURLModifier((url: string) => {
             //全路径匹配资源
@@ -62,6 +68,37 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
             return new_url;
         });
     }
+    /** 已经报过的失败地址（去重只服务「计数」，不影响事件本身 —— 事件仍每次发，页面可按 `isNew` 决定要不要提示） */
+    private _failedUrls: Set<string> = new Set();
+    /** 全站累计**失败地址数**（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零 ⇒ 页面自己算「本次」） */
+    loadErrorCount: number = 0;
+    /** 地址 → 服务端回的状态码。只有**拿到过回复**的那两路写得进来：`loadPanoTexture` 的非 2xx（全景整图/32 片切片、平面 4 片）
+     *  与 `loadModel` 的下载失败（GLB 等）。用来把「服务器明说没有」和「断网 / 解码失败」分开 —— 前者页面才敢删数据。 */
+    private _urlStatus: Map<string, number> = new Map();
+    /** 记下一个地址的服务端状态码（键必须与失败上报用的那一个地址串一致） */
+    markUrlStatus(url: string, status: number): void {
+        if (url) this._urlStatus.set(url, status);
+    }
+    /** 失败的唯一上报口：`DefaultLoadingManager.onError`（素材那一路）与 `ModelSlot` 那颗 GLB 没出来（模型那一路）都走这里。 */
+    reportLoadError(url: string, kind: "asset" | "model", label?: string): void {
+        const isNew = !this._failedUrls.has(url);
+        if (isNew) {
+            this._failedUrls.add(url);
+            this.loadErrorCount++;
+        }
+        const status = this._urlStatus.get(url);
+        // 403 与 404 并一档：OSS 私有桶里「key 不存在」回的正是 403（AccessDenied 用来不泄露对象是否存在）。
+        const missing = status === 404 || status === 403;
+        this.dispatchEvent({ type: "loadError", url, kind, label, status, missing, failed: this.loadErrorCount, isNew });
+    }
+    /** 从加载器抛出的错误里取 HTTP 状态码，记在**调用方那一个地址**上（`url` 原样，不是内部补全后的地址）。
+     *  three 的 `FileLoader` 非 2xx 抛 `HttpError`（`err.response.status`），个别加载器只把码写进 message。 */
+    private _noteErrStatus(url: string | File | Array<File>, err: unknown): void {
+        if (!isString(url)) return;
+        const e = err as { status?: number; response?: { status?: number }; message?: string };
+        const raw = e?.status ?? e?.response?.status ?? Number(/(?:responded with|HTTP) (\d{3})/.exec(e?.message ?? "")?.[1]);
+        if (Number.isFinite(raw)) this.markUrlStatus(url, raw);
+    }
     // 从url 中提取文件名
     getFilename(url: string): string {
         // 移除URL的查询字符串和哈希部分
@@ -370,7 +407,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     });
                     return res;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`);
                         return undefined;
                     });
@@ -387,6 +425,7 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     return res.scene;
                 })
                     .catch((err) => {
+                        this._noteErrStatus(url, err);
                         // 打印详细错误信息，方便调试
                         console.error(`${url},加载失败`, err);
                         return undefined;
@@ -404,7 +443,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                         roughness: 0.5,
                     }));
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`);
                         return undefined;
                     });
@@ -440,7 +480,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     }
                     return plyMesh;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`);
                         return undefined;
                     });
@@ -467,6 +508,7 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     return res;
                 })
                     .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`, err);
                         return undefined;
                     });