three-base 2.0.196 → 2.0.198

package/MktMesh/MktMesh.ts

@@ -29,6 +29,8 @@ import {
     Camera,
     BackSide,
     Float32BufferAttribute,
+    InstancedMesh,
+    Light,
     Material,
     Matrix4,
     Object3D,
@@ -73,16 +75,35 @@ import { stripAssetHost, absAssetUrl } from "./assetUrl";
 //    原先各住在本站两个渲染器里一份 ⇒ 下游直接用包里的 `MktMesh` 时，存档里的 `images`/`models` 两键没人读。
 //    入库之后它们挂在 `MktMesh` **自己的子树**下，与墙同一棵变换 ⇒ 预览那三根 transform 滑杆搬得动整份展品。
 import { ImagePlane, type ImagePlaneData } from "./imagePlane";
-import { ModelSlot, type ModelSlotData } from "./modelSlot";
+import { ModelSlot, glbFileName, type ModelSlotData } from "./modelSlot";
 import { ImagePlaneTileLoader } from "./imageTileLoader";
 
-/** 载入 JSON 时**优先**加载几个全景的素材（2026-10-29 需求「优先加载前 2 个全景图的素材，然后再加载其他的」）。
- *  口径 = 存档 `textures` 数组的前 n 项；其余全景照常按每帧的槽位名册（离注视点最近 8 个）排队，只是排在它们后面。 */
-const PANO_IMPORT_PRIORITY = 2;
+/** 载入 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;
 
 /** 隐藏期预热那一次绘制用的镜头（模块级共用：它只是个「有合法的投影矩阵可读」的载体，永不动 ⇒ ⛔ 不必每实例造一份）。 */
 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[] = [];
@@ -212,6 +233,15 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         return this._panoTexMode;
     }
 
+    /** 优先加载的全景个数（存档 `textures` 的前 n 项）：**-1 = 全部、0 = 一个都不提前、n = 前 n 个**（2026-11-05 需求）。
+     *  默认取 `PANO_IMPORT_PRIORITY_DEFAULT`（=4）；宿主想换档在渲染循环跑起来之前 `setPanoPriorityCount(-1)` 一行即可
+     *  （与 `_ossSize`、`_panoTexMode` 同一套注入路径 ⇒ 编辑器与预览各自的配置各自推下来）。 */
+    private _panoPriorityCount: number = PANO_IMPORT_PRIORITY_DEFAULT;
+    /** 当前优先加载个数（只读，回显用）。 */
+    get panoPriorityCount(): number {
+        return this._panoPriorityCount;
+    }
+
     // 复用临时对象（避免每帧 new，降低 GC 压力）
     private _tmpV3: Vector3 = new Vector3();
 
@@ -257,14 +287,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;
 
@@ -299,6 +334,7 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             //   `updateTexture`（它里面那记 `pump` 是「第一次拿到 renderer ⇒ 在册组整份作废」的现场）之后、
             //   `feedFaceMapping`（名册逐槽入册）之前 —— 顺序倒过来就是「名册在前、我们垫底」= 静默失效。
             //   编辑态那份在 `MktDevMesh` 的宿主循环里照同一相对位置点（⛔ 别在这儿加第三处）。
+            //   2026-11-05 需求：这一批点几颗改由 `panoPriorityCount` 定（默认 4，-1 = 存档全部）⇒ 本句不动。
             this.prefetchHeadPanoramas();
             this.feedFaceMapping();
             this.tickProgressiveReveal();
@@ -1084,6 +1120,18 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         this._panoTexMode = next;
     }
 
+    /** 设置优先加载的全景个数：-1 = 全部 / 0 = 不提前 / n = 存档前 n 个（2026-11-05 需求）。
+     *  收口：负数（含 -2、NaN 一类）一律归到 -1「全加载」，正数向下取整；非有限值回落默认档。
+     *  改档⛔ 需要重新 `importData` —— 名册每帧重排，下一帧 `prefetchHeadPanoramas` 直接用新数点名
+     *  （`prioritize` 幂等 ⇒ 已在队列里的那批不重复投喂，也不会把已出队的旧批再塞回去）。 */
+    setPanoPriorityCount(count: number): void {
+        if (!Number.isFinite(count)) this._panoPriorityCount = PANO_IMPORT_PRIORITY_DEFAULT;
+        else {
+            const n = Math.floor(count);
+            this._panoPriorityCount = n < 0 ? -1 : n;
+        }
+    }
+
     /**
      * 记下「当前激活（名册 0 号槽 = 中心）是第几个全景」。
      * ⭐ 皇上旨 2026-10-03 旨②：预览立方体已与墙**共用同一份材质**，原来那句「把中心那几张抄给立方体单全景材质」
@@ -1213,6 +1261,9 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             ms.dispose();
         }
         this.models = [];
+        // 用户 2026-11-04「日志少打印点吧」⇒ 这一路（进厅 / 切项目 / 预览的整层重建）几十颗⛔ 不再一颗一行：
+        //   名单先攒着，循环结束打**一条**（文件名口径与 `setModelUrl` 那一记共用 `glbFileName`）⇒ 一颗不落、一行到位。
+        const glbNames: string[] = [];
         for (const d of datas) {
             const ms = new ModelSlot(d.name);
             ms.applyData(d);
@@ -1224,9 +1275,11 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
                 //（⚠️ 与旧的「GLB 在路上时这一槽露出占位方块」不同：整层重建这一路一颗都不露，直到轮到自己亮）
                 ms.visible = false;
                 this._revealPending.push(ms);
+                glbNames.push(glbFileName(d.url));
                 void ms.loadModel(d.url).then(() => this._queueModelMount(ms, onEachLoad));
             }
         }
+        if (glbNames.length > 0) console.log(`[MktMesh] 整层重建加载 ${glbNames.length} 个 glb：${glbNames.join("、")}`);
     }
 
     /** 把「备好待挂」的那一槽交给全局队列；⛔ 去重闸门自备（`addWork` 按闭包引用判重，新闭包它判不出来） */
@@ -1243,6 +1296,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 +1355,9 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             }
         }
         ip.setTileTextures(texs, insets);
+        // 瓦片是一张一张就绪的 ⇒ 每绑上一张，这一颗的「待画纹理」就换一档（去重键带绑定戳记）⇒ 补排一次，
+        // 让上传发生在隐藏期而不是进厅那一帧。
+        this._topUpGpuPrewarm();
         if (pending) {
             this._queueImagePlaneBind(ip);
             return;
@@ -1329,7 +1387,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 +1400,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 +1426,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();
+    }
 
-        const items: Array<{ m: Material; g: BufferGeometry }> = [];
-        const seen = new Set<string>();
+    /**
+     * 内容后落位时补排预热（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();
+    }
+
+    /**
+     * 扫一遍本对象的子树，把「还没收过的那一档」压进清单。
+     * @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 +1498,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 + 矩阵）
@@ -1545,11 +1712,12 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     }
 
     /**
-     * 把**存档里前 `PANO_IMPORT_PRIORITY` 个全景**按存档顺序登记进拼合器的**加载任务队列**
+     * 把**存档里前 `panoPriorityCount` 个全景**（-1 = 整份全加载）按存档顺序登记进拼合器的**加载任务队列**
      *（2026-10-29 需求「优先加载前 2 个全景素材」+ 2026-10-30 需求逐字：「给 mktmesh 内部加一个加载任务队列，
      *  把模型和平面图排在最前面，然后按照顺序，依次把前 2 个全景的顺序把瓦片加载任务添加到任务队列里面，
      *  第一个加载完了，就把这个加载任务从任务队列里面去掉，然后加载第二个；
-     *  如果后续再按照距离计算需要加载哪个全景的时候，同样地添加到加载任务队列的后面等待加载」）。
+     *  如果后续再按照距离计算需要加载哪个全景的时候，同样地添加到加载任务队列的后面等待加载」
+     *  + 2026-11-05 需求「提前加载多少个全景改由配置决定，-1 全加载 / 0 不加载 / n 前 n 个，默认 4」）。
      * 由两处渲染循环每帧点一次：基类 `onBeforeRender`（预览弹窗 / 发布页）与编辑器的 `updateFloorTexture`
      *（`MktDevMesh` 覆写了 `onBeforeRender`，只点 `syncProjInvMatrix` + `tickProgressiveReveal`，库内那句在编辑态不跑）。
      *
@@ -1558,27 +1726,31 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *      （GLB 逐只 `loadModel` 不 throttle；平面那 4 片一次性 `_imgTileLoader.preload`），
      *      而全景瓦片最早也要等下一帧的 `pump` 才发第一片 ⇒ 发起次序天然是「模型 → 平面图 → 全景」，
      *      ⛔ 这里不再把它们塞进队列重复管一遍（塞了就是第二把尺）。
-     *   ② 本方法把存档 0 号、1 号依次 `prioritize` 进队列 ⇒ 拼合器每帧**只喂队首那一组**，
+     *   ② 本方法把存档 0 号起这 n 号依次 `prioritize` 进队列 ⇒ 拼合器每帧**只喂队首那一组**，
      *      0 号 32 格全落定（画进 RT，或该格本就缺地址/判死）才出队、1 号才开始发第一片。
      *      比 10-29 那版（只是把两批挪到在册顺序前面、额度仍被两批分摊）更硬：**第 1 颗独享额度，最快出全图**。
+     *      n = -1（全加载）时这一条变成「整份存档按存档顺序串行」⇒ 距离名册插不到前面，出清速度取决于总片数。
      *   ③ 名册按距离点到的其他全景走 `feedFaceMapping` 里那句 `ensure(t.tiles)`（不带队列）⇒ 只入册、
      *      排在队列后面等，队列空了才按在册顺序补料（现行口径不变）。
      * ⚠️⚠️ 为什么每帧点而⛔ 只在 `importData` 里点一记：预览每开一次都换渲染器，`_switchRenderer` 把在册组
      *   整份作废（队列里的键也在同一刻失效）；只在载入那次点名等于白点。本方法点在 `pump` 之后、名册逐槽
-     *   `ensure` 之前 ⇒ 每帧把这两记任务补回队列头部（`prioritize` 幂等，已在队列里就不挪，所以 0 号恒在 1 号前）。
+     *   `ensure` 之前 ⇒ 每帧把这几记任务补回队列头部（`prioritize` 幂等，已在队列里就不挪，所以存档次序恒不变）。
      * ⚠️ 代价如实记：
-     *   · 队列非空时**其他全景一片都不发** ⇒ 开机那几秒里，离注视点最近、但不在存档前两颗的那面墙会多灰一会儿。
+     *   · 队列非空时**其他全景一片都不发** ⇒ 开机那几秒里，离注视点最近、但不在存档前 n 颗的那面墙会多灰一会儿。
      *   · 一颗「永远下不完」的瓦片（下载失败还没累计到判死）会压住队列；判死阈值是解码失败 3 次
-     *     （`_dead`），退避重试期间队首不落定 ⇒ 第 2 颗跟着延后。真实数据里缺片是「地址为空/404」，
+     *     （`_dead`），退避重试期间队首不落定 ⇒ 后面几颗跟着延后。真实数据里缺片是「地址为空/404」，
      *     404 走三次即判死、那一格拼合涂灰 ⇒ 队列照样出清。
-     *   · 这两颗全景若本来不在开机那一刻的名册里，它们的瓦片与拼合槽 RT 会被**提前**建出来
-     *     （现行口径每颗全景 2 槽 × 6144² ≈ 384MB 显存）—— 组在运行中不淘汰，走进这两个景点迟早要建。
+     *   · 这批全景若本来不在开机那一刻的名册里，它们的瓦片与拼合槽 RT 会被**提前**建出来
+     *     （现行口径每颗全景 2 槽 × 6144² ≈ 384MB 显存）—— 组在运行中不淘汰，走进这些景点迟早要建；
+     *     ⚠️ n = -1（全加载）时这一条按存档全景总数放大，显存与在途请求都跟着涨。
      * ⚠️ 形态判据读 `this._panoTexMode`（整图形态那一档一张全景只有一张整图，走 `_texCache` 那条路，
      *   走错档就是白下 32 片）⇒ 宿主若用自己那份形态变量（编辑器的 `store.panoTexMode`），
      *   要在调 `importData` 之前先 `setPanoTexMode` 推进来，编辑器那侧已按此接线。
      */
     prefetchHeadPanoramas(): void {
-        const n = Math.min(PANO_IMPORT_PRIORITY, this.textures.length);
+        const total = this.textures.length;
+        // -1 = 整份；0 = 一个都不提前（这一句直接空转，其余全景仍按距离名册排队 = 回到 10-29 之前的行为）
+        const n = this._panoPriorityCount < 0 ? total : Math.min(this._panoPriorityCount, total);
         // 正着点：0 号先入队 ⇒ 队首是它，落定后才轮到 1 号（`prioritize` 对已在队列里的键不挪位置）
         for (let i = 0; i < n; i++) {
             const info = this.textures[i];
@@ -1617,9 +1789,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/imagePlane.d.ts

@@ -39,6 +39,10 @@ export declare class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
     private _data;
     /** 内容是否已落定：4 格里至少有一格真的绑上了纹理。**只朝 true 翻一次**（之后逐张显影继续，但不再回退成「没内容」）。 */
     private _loaded;
+    /** 此刻是不是编辑器的选中态（决定上不上黄、边框亮不亮） */
+    private _selected;
+    /** 选中边框：懒建（预览/发布那一路从不选中 ⇒ 一颗都不建） */
+    private _outline;
     constructor(name?: string);
     get imageWidth(): number;
     get imageHeight(): number;
@@ -57,6 +61,16 @@ export declare class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
     tilesBindingStamp(): string;
     highlight(): void;
     restoreColor(): void;
+    /**
+     * 选中态的三样东西一起算（颜色 + 边框），一处规则：
+     * - 黄只在**还没上传图**那一档：片元里贴图是乘进 diffuse 的（`diffuseColor *= imgTexel`），有图还套黄 ⇒ 整张图发黄。
+     * - 边框在有图/没图两档都亮：没图那四格是整格 `discard`（一个像素都不落），只靠黄等于没有反馈，看不见也找不着。
+     */
+    private _syncSelection;
+    /** 选中边框懒建：预览/发布那一路从不选中 ⇒ 一颗 LineSegments2 都不建（与模型槽那圈 `BoxLine2` 同口径） */
+    private _ensureOutline;
+    /** 四条边按当前几何的宽高铺在平面那一平面上（局部 z=0，中心为原点） */
+    private _layoutOutline;
     toData(): ImagePlaneData;
     applyData(d: ImagePlaneData): void;
     dispose(): void;