three-base 2.0.192 → 2.0.193

package/EventMap.d.ts

@@ -8,6 +8,12 @@ export interface LoadingEvent {
 export interface OnLoadEvent {
     type: "onLoad";
 }
+export interface LoaderProgressEvent {
+    type: "progress";
+    url: string;
+    loaded: number;
+    total: number;
+}
 export interface BeforeRenderEvent {
     type: "beforeRender";
 }
@@ -53,6 +59,7 @@ export interface MeshBaseEventMap extends Object3DEventMap {
 export interface ThreeLoaderEventMap extends Object3DEventMap {
     "loadding": LoadingEvent;
     "onLoad": OnLoadEvent;
+    "progress": LoaderProgressEvent;
 }
 export interface ThreeBaseEventTypeMap extends Object3DEventMap {
     "loadding": LoadingEvent;

package/EventMap.ts

@@ -29,6 +29,13 @@ import type { Object3DEventMap, Vector3 } from "three";
 export interface LoadedEvent { type: "loaded"; }
 export interface LoadingEvent { type: "loadding"; }
 export interface OnLoadEvent { type: "onLoad"; }
+// 资源加载进度：`DefaultLoadingManager.onProgress` 的三个数原样带出（url / 已完成项数 / 总项数）
+export interface LoaderProgressEvent {
+    type: "progress";
+    url: string;
+    loaded: number;
+    total: number;
+}
 export interface BeforeRenderEvent { type: "beforeRender"; }
 export interface AfterRenderEvent { type: "afterRender"; }
 
@@ -77,6 +84,7 @@ export interface MeshBaseEventMap extends Object3DEventMap {
 export interface ThreeLoaderEventMap extends Object3DEventMap {
     "loadding": LoadingEvent;
     "onLoad": OnLoadEvent;
+    "progress": LoaderProgressEvent;
 }
 
 export interface ThreeBaseEventTypeMap extends Object3DEventMap {

package/MktMesh/MktMesh.d.ts

@@ -4,6 +4,7 @@ import { type PanoStitcher } from "./panoTileStitcher";
 import type { MktMeshData, MktTextureInfo, WallPoint, WallSide } from "./types";
 import { ImagePlane, type ImagePlaneData } from "./imagePlane";
 import { ModelSlot, type ModelSlotData } from "./modelSlot";
+import { GlassPane, type GlassPaneData } from "./glassPane";
 export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
     textures: MktTextureInfo[];
@@ -128,6 +129,23 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     imagePlanes: ImagePlane[];
     /** 模型槽层（同一棵子树，口径同上） */
     models: ModelSlot[];
+    /**
+     * 玻璃面层（⭐ 2026-10-28 需求「正方的面」）：同一棵子树，口径与上面两层一致。
+     * 与那两层的区别只在材质（MeshPhysicalMaterial + transmission + DoubleSide，见 `./glassPane.ts`）
+     * ⇒ 它**没有自己的内容纹理**，反射源共用下面那一张 `_glassEnvTex`。
+     */
+    glassPanes: GlassPane[];
+    /**
+     * 玻璃面反射环境的**源地址** = 第一个全景的整图地址（`textures[0].url`），空串 = 还没有全景可用。
+     * ⚠️ 这里存的是**未拼尺寸参数的原始地址**（与 `_texCache` 的键同一口径）⇒ 全景换了地址才发现要重载；
+     *    下载时按当前 `_ossSize` 档过 `resolveOssUrl`（默认为 1024 那一档）。PMREM 卷积输出的分辨率上限远小于 1024
+     *    ⇒ 反射精度由那一步决定，用缩放副本不降低观感，换来的是省掉整张原图（实测 11904×5952 ≈ 283MB）的解码内存。
+     * ⚠️ 为什么不用「第一个全景那两张拼合槽 RT」：每张 RT 装的是原图**左/右半幅**且压成 1:1 方图，
+     *    当等距柱状环境采会横向拉伸一倍 + 缺半边；且它的 mapping 是 UVMapping，three 不会替它做 PMREM ⇒ 采出花屏。
+     */
+    private _glassEnvKey;
+    /** 已就绪的反射环境纹理（null = 未就绪 / 没有全景）；同一张共用给所有玻璃面 ⇒ 只下载、只卷积一次 */
+    private _glassEnvTex;
     /**
      * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
      * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不会再空一格；只随本对象 `dispose()` 释放。
@@ -374,6 +392,32 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     private _queueModelMount;
     /** 全局队列里的那一帧：只挂这一槽，挂好才回调（`onEachLoad` = 按需渲染宿主的标脏钩子） */
     private _mountModelStep;
+    /** 单颗玻璃面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 + 先吃当前反射源，再确认源在下路没有 */
+    addGlassPane(gp: GlassPane): GlassPane;
+    /** 摘掉一颗并释放它的几何/材质；反射纹理是共用那张 ⇒ 最后一颗也摘掉时才由 `syncGlassEnvironment` 收（按源地址记账，⛔ 不在这里直接 dispose） */
+    removeGlassPane(gp: GlassPane): void;
+    /**
+     * 整层重建玻璃面（`importData` 与预览那一路）。玻璃面不引用任何素材文件 ⇒ ⛔ 不过 `absAssetUrl`
+     * （地址只有反射源那一处，而它取的是**本对象内存里**的 `textures[0].url`，已经是补过域名的形态）。
+     */
+    setGlassPanes(datas: GlassPaneData[]): void;
+    /**
+     * 把「第一个全景」的整图当成玻璃面的反射环境（2026-10-28 需求）。
+     *
+     * 判据 = 源地址变了没有（⛔ 不按下标记：删掉 0 号景点后原 1 号自动顶上来，那时地址会变 ⇒ 自愈）。
+     * 调用点只有四处，⛔ 不进 `onBeforeRender` 自驱：① 单颗入层 ② 单颗摘除 ③ 整层重建 ④ 编辑态每帧 tick 里与
+     * `feedImagePlaneTiles()` 并排那一句（源地址没变就一句比较直接返回 ⇒ 无玻璃面的场景零成本，
+     * 而全景被增删/换图那些路都不必各自记得再来点一次）。
+     *
+     * ⚠️ 换源那一步必须**先摘后放**：材质还指着这张、位图却已 `close()` ⇒ 采出来是空图。
+     * ⚠️ 下载走 `loadPanoTexture`（解码在工作线程）并自动向 `DefaultLoadingManager` 记账 ⇒ 预览弹窗那个
+     *    加载进度条能看见它，与全景瓦片同一本账。
+     * ⚠️ 结果只存进 `_glassEnvTex`，⛔ 不进 `_texCache`：那张表在 `setOssSize` 换档时会被整批 dispose
+     *    （`_reloadActiveTexture`），而正在被材质引用的这张不能被那样顺手清掉。
+     */
+    syncGlassEnvironment(): void;
+    /** 把同一张反射源发给每一颗玻璃面（`GlassPane` 内部按对象判等 ⇒ 重复发同一张不会重编译）。 */
+    private _applyGlassEnv;
     /**
      * 把各颗平面那 4 张瓦片的纹理绑进材质（10-22 晚定的口径：不走拼合器 RT）。
      * 2026-10-26 决定改成**逐帧**：一次把整层地址全丢给下载器（下载/解码在网络与工作线程侧，不占这一帧），
@@ -405,6 +449,37 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址
      *  @param onModelLoad 每只 GLB 落地时回调一次（可选）——按需渲染的宿主（编辑器）拿它标脏；每帧真画的预览不传 */
     importData(data: MktMeshData, projName?: string, onModelLoad?: () => void): void;
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
+    /**
+     * 把**存档里前 `PANO_IMPORT_PRIORITY` 个全景**的素材点名抢在别的之前加载（2026-10-29 需求）。
+     * 由两处渲染循环每帧点一次：基类 `onBeforeRender`（预览弹窗 / 发布页）与编辑器的 `updateFloorTexture`
+     *（`MktDevMesh` 覆写了 `onBeforeRender`，只点 `syncProjInvMatrix` + `tickProgressiveReveal`，库内那句在编辑态不跑）。
+     *
+     * 为什么能「先加载」：拼合器每帧那三道工序（补下载 → 画已进 GPU 的 → 再传一张）都按
+     *   `_groups` 这张 Map 的**在册顺序**取料，而下载额度只有「每帧 2 张 / 在途 ≤8 / 已解码待上传 ≤8」
+     *   （`panoTileStitcher.ts` 顶部那三个常数）⇒ 排在头部的两组把额度吃满，其余全景要等它们画满才轮得到。
+     *   平时这个顺序由每帧的槽位名册定（离注视点近的先下），本方法把它钉成「存档数组的前两个」，与机位无关。
+     * ⚠️⚠️ 为什么点名时要带第三个参 `front = true`（每帧把这两批**挪回队首**）而⛔ 不只是「先入册」：
+     *   在册顺序是拼合器自己的状态 —— 后入册的只会**追加到队尾**，而 `ensure` 幂等、已在册就不再移动。
+     *   预览这条路恰好是最坏的那种排法：`feedFaceMapping` 开头还有一记 `pump`，拼合器**第一次**拿到渲染器时
+     *   必走 `_switchRenderer`（`null → 真 renderer` 也算换，弹窗每开一次就是换一次）把在册组整份作废，
+     *   随后名册按距离重新入册占了队首 ⇒ 本方法下一帧重新入册只能排在它们后面，而且**从此再也翻不了身**。
+     *   2026-10-29 逐帧打点就是这个形状：帧 1 `p0,p1,p11…p4` → 帧 2 起 `p11…p4,p0,p1`，
+     *   40 帧下来 p0 只下到 1 片、p1 下到 30 片，离注视点最近那颗第 13 条请求就开始了 = 线上报的现象。
+     *   ⇒ 带 `front` 之后顺序每帧重新成立，与谁先入册、作废过几次、机位在哪都无关
+     *   （真跑自证在护栏 BE ④：`D` 后入册排队尾，带 `front` 再点一次 ⇒ 立刻回到队首、下一帧下载全归它）。
+     * ⚠️ 为什么是**每帧**而不是「载入那一次点一记」：上面那次作废就发生在载入之后的第一帧，
+     *   只在 `importData` 里点名等于白点；本方法点在 `pump` 之后、名册逐槽 `ensure` 之前，且每帧都点
+     *   （已在册且已在队首 ⇒ `_toFront` 里一次 `keys().next()` 就返回，没有额外开销）。
+     * ⛔ 不另立第二把下载尺：这里用的就是 `feedFaceMapping` 每帧在用的同一个 `ensure(info.tiles, …)`
+     *   与同一个批次键（第一条非空瓦片地址）⇒ 后面那句自然判重，一片瓦片终身只 `fetch` 一次。
+     * ⚠️ 形态判据读 `this._panoTexMode`（整图形态那一档一张全景只有一张整图，走 `_texCache` 那条路，
+     *   走错档就是白下 32 片）⇒ 宿主若用自己那份形态变量（编辑器的 `store.panoTexMode`），
+     *   要在调 `importData` 之前先 `setPanoTexMode` 推进来，编辑器那侧已按此接线。
+     * ⚠️ 代价如实记：这两颗全景若本来不在开机那一刻的名册里，它们的瓦片与拼合槽 RT 会被**提前**建出来
+     *   （现行口径每颗全景 2 槽 × 6144² ≈ 400MB 显存）—— 组在运行中不淘汰，走进那两个景点迟早要建，
+     *   这里只是把这一笔挪到了载入的第一帧。
+     */
+    prefetchHeadPanoramas(): void;
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，2026-10-02 决定）、拼合器、平面图 / 模型 / 玻璃面三层、几何、材质 */
     dispose(): this;
 }

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, EquirectangularReflectionMapping, Float32BufferAttribute, Matrix4, Mesh, Shape, ShapeGeometry, SRGBColorSpace, Vector3, Vector4, } 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";
@@ -51,6 +51,12 @@ import { stripAssetHost, absAssetUrl } from "./assetUrl";
 import { ImagePlane } from "./imagePlane";
 import { ModelSlot } from "./modelSlot";
 import { ImagePlaneTileLoader } from "./imageTileLoader";
+// ⭐ 2026-10-28 需求「正方的面 + 双面 + 反射用第一个全景 + 进 json 回显」：第三层，形状与上面两层同口径
+//   （挂在本网格子树、随展品一起走；数据由自己的 `toData/applyData` 逐字存）。
+import { GlassPane } from "./glassPane";
+/** 载入 JSON 时**优先**加载几个全景的素材（2026-10-29 需求「优先加载前 2 个全景图的素材，然后再加载其他的」）。
+ *  口径 = 存档 `textures` 数组的前 n 项；其余全景照常按每帧的槽位名册（离注视点最近 8 个）排队，只是排在它们后面。 */
+const PANO_IMPORT_PRIORITY = 2;
 export default class MktMesh extends Mesh {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
     textures = [];
@@ -185,6 +191,23 @@ export default class MktMesh extends Mesh {
     imagePlanes = [];
     /** 模型槽层（同一棵子树，口径同上） */
     models = [];
+    /**
+     * 玻璃面层（⭐ 2026-10-28 需求「正方的面」）：同一棵子树，口径与上面两层一致。
+     * 与那两层的区别只在材质（MeshPhysicalMaterial + transmission + DoubleSide，见 `./glassPane.ts`）
+     * ⇒ 它**没有自己的内容纹理**，反射源共用下面那一张 `_glassEnvTex`。
+     */
+    glassPanes = [];
+    /**
+     * 玻璃面反射环境的**源地址** = 第一个全景的整图地址（`textures[0].url`），空串 = 还没有全景可用。
+     * ⚠️ 这里存的是**未拼尺寸参数的原始地址**（与 `_texCache` 的键同一口径）⇒ 全景换了地址才发现要重载；
+     *    下载时按当前 `_ossSize` 档过 `resolveOssUrl`（默认为 1024 那一档）。PMREM 卷积输出的分辨率上限远小于 1024
+     *    ⇒ 反射精度由那一步决定，用缩放副本不降低观感，换来的是省掉整张原图（实测 11904×5952 ≈ 283MB）的解码内存。
+     * ⚠️ 为什么不用「第一个全景那两张拼合槽 RT」：每张 RT 装的是原图**左/右半幅**且压成 1:1 方图，
+     *    当等距柱状环境采会横向拉伸一倍 + 缺半边；且它的 mapping 是 UVMapping，three 不会替它做 PMREM ⇒ 采出花屏。
+     */
+    _glassEnvKey = "";
+    /** 已就绪的反射环境纹理（null = 未就绪 / 没有全景）；同一张共用给所有玻璃面 ⇒ 只下载、只卷积一次 */
+    _glassEnvTex = null;
     /**
      * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
      * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不会再空一格；只随本对象 `dispose()` 释放。
@@ -247,6 +270,11 @@ export default class MktMesh extends Mesh {
             this._glRenderer = renderer;
             this.syncProjInvMatrix();
             this.updateTexture(camera);
+            // ⭐ 2026-10-29 需求「载入 json 优先加载前 2 个全景图的素材，然后再加载其他的」：必须点在
+            //   `updateTexture`（它里面那记 `pump` 是「第一次拿到 renderer ⇒ 在册组整份作废」的现场）之后、
+            //   `feedFaceMapping`（名册逐槽入册）之前 —— 顺序倒过来就是「名册在前、我们垫底」= 静默失效。
+            //   编辑态那份在 `MktDevMesh` 的宿主循环里照同一相对位置点（⛔ 别在这儿加第三处）。
+            this.prefetchHeadPanoramas();
             this.feedFaceMapping();
             this.tickProgressiveReveal();
         };
@@ -1183,6 +1211,91 @@ export default class MktMesh extends Mesh {
         if (ms.mountStaged() && onEachLoad)
             onEachLoad();
     }
+    // ───────────── 玻璃面层（⭐ 2026-10-28 需求「正方的面：双面 + 反射用第一个全景 + 进 json 回显」） ─────────────
+    /** 单颗玻璃面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 + 先吃当前反射源，再确认源在下路没有 */
+    addGlassPane(gp) {
+        this.glassPanes.push(gp);
+        this.add(gp);
+        gp.setEnvironmentTexture(this._glassEnvTex);
+        this.syncGlassEnvironment();
+        return gp;
+    }
+    /** 摘掉一颗并释放它的几何/材质；反射纹理是共用那张 ⇒ 最后一颗也摘掉时才由 `syncGlassEnvironment` 收（按源地址记账，⛔ 不在这里直接 dispose） */
+    removeGlassPane(gp) {
+        const i = this.glassPanes.indexOf(gp);
+        if (i >= 0)
+            this.glassPanes.splice(i, 1);
+        this.remove(gp);
+        gp.dispose();
+        this.syncGlassEnvironment();
+    }
+    /**
+     * 整层重建玻璃面（`importData` 与预览那一路）。玻璃面不引用任何素材文件 ⇒ ⛔ 不过 `absAssetUrl`
+     * （地址只有反射源那一处，而它取的是**本对象内存里**的 `textures[0].url`，已经是补过域名的形态）。
+     */
+    setGlassPanes(datas) {
+        for (const gp of this.glassPanes) {
+            this.remove(gp);
+            gp.dispose();
+        }
+        this.glassPanes = [];
+        for (const d of datas) {
+            const gp = new GlassPane(d.name);
+            gp.applyData(d);
+            this.glassPanes.push(gp);
+            this.add(gp);
+        }
+        this.syncGlassEnvironment();
+    }
+    /**
+     * 把「第一个全景」的整图当成玻璃面的反射环境（2026-10-28 需求）。
+     *
+     * 判据 = 源地址变了没有（⛔ 不按下标记：删掉 0 号景点后原 1 号自动顶上来，那时地址会变 ⇒ 自愈）。
+     * 调用点只有四处，⛔ 不进 `onBeforeRender` 自驱：① 单颗入层 ② 单颗摘除 ③ 整层重建 ④ 编辑态每帧 tick 里与
+     * `feedImagePlaneTiles()` 并排那一句（源地址没变就一句比较直接返回 ⇒ 无玻璃面的场景零成本，
+     * 而全景被增删/换图那些路都不必各自记得再来点一次）。
+     *
+     * ⚠️ 换源那一步必须**先摘后放**：材质还指着这张、位图却已 `close()` ⇒ 采出来是空图。
+     * ⚠️ 下载走 `loadPanoTexture`（解码在工作线程）并自动向 `DefaultLoadingManager` 记账 ⇒ 预览弹窗那个
+     *    加载进度条能看见它，与全景瓦片同一本账。
+     * ⚠️ 结果只存进 `_glassEnvTex`，⛔ 不进 `_texCache`：那张表在 `setOssSize` 换档时会被整批 dispose
+     *    （`_reloadActiveTexture`），而正在被材质引用的这张不能被那样顺手清掉。
+     */
+    syncGlassEnvironment() {
+        // 没有玻璃面 ⇒ 源地址按「空」算：下面那一段照常走换源流程，把共用那张位图关干净（⛔ 不让它悬着）
+        const key = this.glassPanes.length === 0 ? "" : (this.textures[0]?.url ?? "");
+        if (key === this._glassEnvKey)
+            return;
+        this._glassEnvKey = key;
+        if (this._glassEnvTex) {
+            this._applyGlassEnv(null);
+            releasePanoTexture(this._glassEnvTex);
+            this._glassEnvTex = null;
+        }
+        if (!key)
+            return;
+        loadPanoTexture(this.resolveOssUrl(key, false)).then((tex) => {
+            // 这一张到货时源可能已被后来的换源（切项目 / 换全景）顶掉 ⇒ 就地释放，⛔ 不许写回材质
+            if (this._glassEnvKey !== key) {
+                releasePanoTexture(tex);
+                return;
+            }
+            tex.colorSpace = SRGBColorSpace;
+            // three 的 `WebGLCubeUVMaps` 只对这个标记才自动 PMREM 卷积（示例也是把等距柱状图直接挂 material.envMap）
+            tex.mapping = EquirectangularReflectionMapping;
+            this._glassEnvTex = tex;
+            this._applyGlassEnv(tex);
+        }, () => {
+            // 单次失败：清掉记账 ⇒ 下一次有人调本方法（新增/重建玻璃面、编辑态 tick）自然重试，
+            // 与全景瓦片那条「失败后下一帧同键再试」同口径，只是这里由调用点驱动而非每帧驱动。
+            this._glassEnvKey = "";
+        });
+    }
+    /** 把同一张反射源发给每一颗玻璃面（`GlassPane` 内部按对象判等 ⇒ 重复发同一张不会重编译）。 */
+    _applyGlassEnv(tex) {
+        for (const gp of this.glassPanes)
+            gp.setEnvironmentTexture(tex);
+    }
     /**
      * 把各颗平面那 4 张瓦片的纹理绑进材质（10-22 晚定的口径：不走拼合器 RT）。
      * 2026-10-26 决定改成**逐帧**：一次把整层地址全丢给下载器（下载/解码在网络与工作线程侧，不占这一帧），
@@ -1304,6 +1417,9 @@ export default class MktMesh extends Mesh {
                 const d = ms.toData();
                 return { ...d, url: d.url ? stripAssetHost(d.url, pn) : "" };
             }),
+            // 玻璃面层（2026-10-28 需求）：只有位置/旋转/边长，⛔ 不过 `stripAssetHost` —— 它不引用任何素材，
+            //   反射源是运行时从 `textures[0].url` 取的（上面那个键自己就落进存档了）。
+            glass: this.glassPanes.map((gp) => gp.toData()),
         };
     }
     /** 导入数据：重建墙体几何与纹理列表，并激活第一个纹理
@@ -1359,9 +1475,57 @@ export default class MktMesh extends Mesh {
             tiles: (d.tiles ?? []).map((u) => absAssetUrl(u, pn)),
         })));
         this.setModels((data.models ?? []).map((d) => ({ ...d, url: d.url ? absAssetUrl(d.url, pn) : "" })), onModelLoad);
+        // 玻璃面层（2026-10-28 需求）：排在 setTextures **之后**是硬要求 —— 它的反射源读的就是刚还原好的
+        //   `textures[0].url`（补过域名的形态），排在前面会用上一次项目的地址起一次错的载。
+        //   旧存档没有这个键 ⇒ 空数组 = 整层清空，与上面两层的口径逐字一致。
+        this.setGlassPanes(data.glass ?? []);
+    }
+    /**
+     * 把**存档里前 `PANO_IMPORT_PRIORITY` 个全景**的素材点名抢在别的之前加载（2026-10-29 需求）。
+     * 由两处渲染循环每帧点一次：基类 `onBeforeRender`（预览弹窗 / 发布页）与编辑器的 `updateFloorTexture`
+     *（`MktDevMesh` 覆写了 `onBeforeRender`，只点 `syncProjInvMatrix` + `tickProgressiveReveal`，库内那句在编辑态不跑）。
+     *
+     * 为什么能「先加载」：拼合器每帧那三道工序（补下载 → 画已进 GPU 的 → 再传一张）都按
+     *   `_groups` 这张 Map 的**在册顺序**取料，而下载额度只有「每帧 2 张 / 在途 ≤8 / 已解码待上传 ≤8」
+     *   （`panoTileStitcher.ts` 顶部那三个常数）⇒ 排在头部的两组把额度吃满，其余全景要等它们画满才轮得到。
+     *   平时这个顺序由每帧的槽位名册定（离注视点近的先下），本方法把它钉成「存档数组的前两个」，与机位无关。
+     * ⚠️⚠️ 为什么点名时要带第三个参 `front = true`（每帧把这两批**挪回队首**）而⛔ 不只是「先入册」：
+     *   在册顺序是拼合器自己的状态 —— 后入册的只会**追加到队尾**，而 `ensure` 幂等、已在册就不再移动。
+     *   预览这条路恰好是最坏的那种排法：`feedFaceMapping` 开头还有一记 `pump`，拼合器**第一次**拿到渲染器时
+     *   必走 `_switchRenderer`（`null → 真 renderer` 也算换，弹窗每开一次就是换一次）把在册组整份作废，
+     *   随后名册按距离重新入册占了队首 ⇒ 本方法下一帧重新入册只能排在它们后面，而且**从此再也翻不了身**。
+     *   2026-10-29 逐帧打点就是这个形状：帧 1 `p0,p1,p11…p4` → 帧 2 起 `p11…p4,p0,p1`，
+     *   40 帧下来 p0 只下到 1 片、p1 下到 30 片，离注视点最近那颗第 13 条请求就开始了 = 线上报的现象。
+     *   ⇒ 带 `front` 之后顺序每帧重新成立，与谁先入册、作废过几次、机位在哪都无关
+     *   （真跑自证在护栏 BE ④：`D` 后入册排队尾，带 `front` 再点一次 ⇒ 立刻回到队首、下一帧下载全归它）。
+     * ⚠️ 为什么是**每帧**而不是「载入那一次点一记」：上面那次作废就发生在载入之后的第一帧，
+     *   只在 `importData` 里点名等于白点；本方法点在 `pump` 之后、名册逐槽 `ensure` 之前，且每帧都点
+     *   （已在册且已在队首 ⇒ `_toFront` 里一次 `keys().next()` 就返回，没有额外开销）。
+     * ⛔ 不另立第二把下载尺：这里用的就是 `feedFaceMapping` 每帧在用的同一个 `ensure(info.tiles, …)`
+     *   与同一个批次键（第一条非空瓦片地址）⇒ 后面那句自然判重，一片瓦片终身只 `fetch` 一次。
+     * ⚠️ 形态判据读 `this._panoTexMode`（整图形态那一档一张全景只有一张整图，走 `_texCache` 那条路，
+     *   走错档就是白下 32 片）⇒ 宿主若用自己那份形态变量（编辑器的 `store.panoTexMode`），
+     *   要在调 `importData` 之前先 `setPanoTexMode` 推进来，编辑器那侧已按此接线。
+     * ⚠️ 代价如实记：这两颗全景若本来不在开机那一刻的名册里，它们的瓦片与拼合槽 RT 会被**提前**建出来
+     *   （现行口径每颗全景 2 槽 × 6144² ≈ 400MB 显存）—— 组在运行中不淘汰，走进那两个景点迟早要建，
+     *   这里只是把这一笔挪到了载入的第一帧。
+     */
+    prefetchHeadPanoramas() {
+        const n = Math.min(PANO_IMPORT_PRIORITY, this.textures.length);
+        // ⚠️ **倒着**点：`front` 是「挪到最前」，正着点会让 0 号被 1 号压到后面（实测队首变成 `p1,p0`）
+        //   ⇒ 倒着点，最后一手挪的是 0 号，存档序号小的仍排在更前。
+        for (let i = n - 1; i >= 0; i--) {
+            const info = this.textures[i];
+            // 与 `feedFaceMapping` 里那一句同判据：真瓦片才进拼合器，整图形态进瓦片缓存
+            // 第三个参 `true` = 把这批**挪到在册顺序最前**（⛔ 光靠「先入册」押不住顺序，见方法头）
+            if (mktPanoTiledFlag(info.tiles, this._panoTexMode) === 1)
+                this._stitcher.ensure(info.tiles, undefined, true);
+            else if (info.url)
+                this.ensureTileTexture(info.url, false);
+        }
     }
     // ───────────────────────── 释放 ─────────────────────────
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，2026-10-02 决定）、拼合器、平面图 / 模型 / 玻璃面三层、几何、材质 */
     dispose() {
         // ⚠️ rt 虚拟键从不进 `_texCache`（拼合槽纹理由 `_stitcher` 自己持有并释放），这里清的都是本类下载的 Texture。
         // ⭐ 甲（2026-10-05）：`releasePanoTexture` 除 `dispose()` 外还要 `ImageBitmap.close()` —— 位图的原生内存
@@ -1384,6 +1548,16 @@ export default class MktMesh extends Mesh {
             ms.dispose();
         }
         this.models = [];
+        // 玻璃面层：几何/材质各归各颗释放；那张共用的反射纹理在这里连位图一起关
+        //   （⛔ 它从不在 `_texCache` 里 ⇒ 上面那一轮清不到它，漏了这一句就是每次换页漏一张全景整图）。
+        for (const gp of this.glassPanes) {
+            this.remove(gp);
+            gp.dispose();
+        }
+        this.glassPanes = [];
+        releasePanoTexture(this._glassEnvTex);
+        this._glassEnvTex = null;
+        this._glassEnvKey = "";
         this._imgTileLoader.clear();
         this._imgBindQueued.clear();
         this._imgBindDone.clear();

package/MktMesh/MktMesh.ts

@@ -28,6 +28,7 @@ import {
     BufferGeometry,
     Camera,
     BackSide,
+    EquirectangularReflectionMapping,
     Float32BufferAttribute,
     Material,
     Matrix4,
@@ -71,6 +72,13 @@ import { stripAssetHost, absAssetUrl } from "./assetUrl";
 import { ImagePlane, type ImagePlaneData } from "./imagePlane";
 import { ModelSlot, type ModelSlotData } from "./modelSlot";
 import { ImagePlaneTileLoader } from "./imageTileLoader";
+// ⭐ 2026-10-28 需求「正方的面 + 双面 + 反射用第一个全景 + 进 json 回显」：第三层，形状与上面两层同口径
+//   （挂在本网格子树、随展品一起走；数据由自己的 `toData/applyData` 逐字存）。
+import { GlassPane, type GlassPaneData } from "./glassPane";
+
+/** 载入 JSON 时**优先**加载几个全景的素材（2026-10-29 需求「优先加载前 2 个全景图的素材，然后再加载其他的」）。
+ *  口径 = 存档 `textures` 数组的前 n 项；其余全景照常按每帧的槽位名册（离注视点最近 8 个）排队，只是排在它们后面。 */
+const PANO_IMPORT_PRIORITY = 2;
 
 export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
@@ -211,6 +219,23 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     imagePlanes: ImagePlane[] = [];
     /** 模型槽层（同一棵子树，口径同上） */
     models: ModelSlot[] = [];
+    /**
+     * 玻璃面层（⭐ 2026-10-28 需求「正方的面」）：同一棵子树，口径与上面两层一致。
+     * 与那两层的区别只在材质（MeshPhysicalMaterial + transmission + DoubleSide，见 `./glassPane.ts`）
+     * ⇒ 它**没有自己的内容纹理**，反射源共用下面那一张 `_glassEnvTex`。
+     */
+    glassPanes: GlassPane[] = [];
+    /**
+     * 玻璃面反射环境的**源地址** = 第一个全景的整图地址（`textures[0].url`），空串 = 还没有全景可用。
+     * ⚠️ 这里存的是**未拼尺寸参数的原始地址**（与 `_texCache` 的键同一口径）⇒ 全景换了地址才发现要重载；
+     *    下载时按当前 `_ossSize` 档过 `resolveOssUrl`（默认为 1024 那一档）。PMREM 卷积输出的分辨率上限远小于 1024
+     *    ⇒ 反射精度由那一步决定，用缩放副本不降低观感，换来的是省掉整张原图（实测 11904×5952 ≈ 283MB）的解码内存。
+     * ⚠️ 为什么不用「第一个全景那两张拼合槽 RT」：每张 RT 装的是原图**左/右半幅**且压成 1:1 方图，
+     *    当等距柱状环境采会横向拉伸一倍 + 缺半边；且它的 mapping 是 UVMapping，three 不会替它做 PMREM ⇒ 采出花屏。
+     */
+    private _glassEnvKey: string = "";
+    /** 已就绪的反射环境纹理（null = 未就绪 / 没有全景）；同一张共用给所有玻璃面 ⇒ 只下载、只卷积一次 */
+    private _glassEnvTex: Texture | null = null;
     /**
      * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
      * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不会再空一格；只随本对象 `dispose()` 释放。
@@ -272,6 +297,11 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             this._glRenderer = renderer;
             this.syncProjInvMatrix();
             this.updateTexture(camera as Camera);
+            // ⭐ 2026-10-29 需求「载入 json 优先加载前 2 个全景图的素材，然后再加载其他的」：必须点在
+            //   `updateTexture`（它里面那记 `pump` 是「第一次拿到 renderer ⇒ 在册组整份作废」的现场）之后、
+            //   `feedFaceMapping`（名册逐槽入册）之前 —— 顺序倒过来就是「名册在前、我们垫底」= 静默失效。
+            //   编辑态那份在 `MktDevMesh` 的宿主循环里照同一相对位置点（⛔ 别在这儿加第三处）。
+            this.prefetchHeadPanoramas();
             this.feedFaceMapping();
             this.tickProgressiveReveal();
         };
@@ -1217,6 +1247,96 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         if (ms.mountStaged() && onEachLoad) onEachLoad();
     }
 
+    // ───────────── 玻璃面层（⭐ 2026-10-28 需求「正方的面：双面 + 反射用第一个全景 + 进 json 回显」） ─────────────
+
+    /** 单颗玻璃面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 + 先吃当前反射源，再确认源在下路没有 */
+    addGlassPane(gp: GlassPane): GlassPane {
+        this.glassPanes.push(gp);
+        this.add(gp);
+        gp.setEnvironmentTexture(this._glassEnvTex);
+        this.syncGlassEnvironment();
+        return gp;
+    }
+
+    /** 摘掉一颗并释放它的几何/材质；反射纹理是共用那张 ⇒ 最后一颗也摘掉时才由 `syncGlassEnvironment` 收（按源地址记账，⛔ 不在这里直接 dispose） */
+    removeGlassPane(gp: GlassPane): void {
+        const i = this.glassPanes.indexOf(gp);
+        if (i >= 0) this.glassPanes.splice(i, 1);
+        this.remove(gp);
+        gp.dispose();
+        this.syncGlassEnvironment();
+    }
+
+    /**
+     * 整层重建玻璃面（`importData` 与预览那一路）。玻璃面不引用任何素材文件 ⇒ ⛔ 不过 `absAssetUrl`
+     * （地址只有反射源那一处，而它取的是**本对象内存里**的 `textures[0].url`，已经是补过域名的形态）。
+     */
+    setGlassPanes(datas: GlassPaneData[]): void {
+        for (const gp of this.glassPanes) {
+            this.remove(gp);
+            gp.dispose();
+        }
+        this.glassPanes = [];
+        for (const d of datas) {
+            const gp = new GlassPane(d.name);
+            gp.applyData(d);
+            this.glassPanes.push(gp);
+            this.add(gp);
+        }
+        this.syncGlassEnvironment();
+    }
+
+    /**
+     * 把「第一个全景」的整图当成玻璃面的反射环境（2026-10-28 需求）。
+     *
+     * 判据 = 源地址变了没有（⛔ 不按下标记：删掉 0 号景点后原 1 号自动顶上来，那时地址会变 ⇒ 自愈）。
+     * 调用点只有四处，⛔ 不进 `onBeforeRender` 自驱：① 单颗入层 ② 单颗摘除 ③ 整层重建 ④ 编辑态每帧 tick 里与
+     * `feedImagePlaneTiles()` 并排那一句（源地址没变就一句比较直接返回 ⇒ 无玻璃面的场景零成本，
+     * 而全景被增删/换图那些路都不必各自记得再来点一次）。
+     *
+     * ⚠️ 换源那一步必须**先摘后放**：材质还指着这张、位图却已 `close()` ⇒ 采出来是空图。
+     * ⚠️ 下载走 `loadPanoTexture`（解码在工作线程）并自动向 `DefaultLoadingManager` 记账 ⇒ 预览弹窗那个
+     *    加载进度条能看见它，与全景瓦片同一本账。
+     * ⚠️ 结果只存进 `_glassEnvTex`，⛔ 不进 `_texCache`：那张表在 `setOssSize` 换档时会被整批 dispose
+     *    （`_reloadActiveTexture`），而正在被材质引用的这张不能被那样顺手清掉。
+     */
+    syncGlassEnvironment(): void {
+        // 没有玻璃面 ⇒ 源地址按「空」算：下面那一段照常走换源流程，把共用那张位图关干净（⛔ 不让它悬着）
+        const key = this.glassPanes.length === 0 ? "" : (this.textures[0]?.url ?? "");
+        if (key === this._glassEnvKey) return;
+        this._glassEnvKey = key;
+        if (this._glassEnvTex) {
+            this._applyGlassEnv(null);
+            releasePanoTexture(this._glassEnvTex);
+            this._glassEnvTex = null;
+        }
+        if (!key) return;
+        loadPanoTexture(this.resolveOssUrl(key, false)).then(
+            (tex) => {
+                // 这一张到货时源可能已被后来的换源（切项目 / 换全景）顶掉 ⇒ 就地释放，⛔ 不许写回材质
+                if (this._glassEnvKey !== key) {
+                    releasePanoTexture(tex);
+                    return;
+                }
+                tex.colorSpace = SRGBColorSpace;
+                // three 的 `WebGLCubeUVMaps` 只对这个标记才自动 PMREM 卷积（示例也是把等距柱状图直接挂 material.envMap）
+                tex.mapping = EquirectangularReflectionMapping;
+                this._glassEnvTex = tex;
+                this._applyGlassEnv(tex);
+            },
+            () => {
+                // 单次失败：清掉记账 ⇒ 下一次有人调本方法（新增/重建玻璃面、编辑态 tick）自然重试，
+                // 与全景瓦片那条「失败后下一帧同键再试」同口径，只是这里由调用点驱动而非每帧驱动。
+                this._glassEnvKey = "";
+            }
+        );
+    }
+
+    /** 把同一张反射源发给每一颗玻璃面（`GlassPane` 内部按对象判等 ⇒ 重复发同一张不会重编译）。 */
+    private _applyGlassEnv(tex: Texture | null): void {
+        for (const gp of this.glassPanes) gp.setEnvironmentTexture(tex);
+    }
+
     /**
      * 把各颗平面那 4 张瓦片的纹理绑进材质（10-22 晚定的口径：不走拼合器 RT）。
      * 2026-10-26 决定改成**逐帧**：一次把整层地址全丢给下载器（下载/解码在网络与工作线程侧，不占这一帧），
@@ -1334,6 +1454,9 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
                 const d = ms.toData();
                 return { ...d, url: d.url ? stripAssetHost(d.url, pn) : "" };
             }),
+            // 玻璃面层（2026-10-28 需求）：只有位置/旋转/边长，⛔ 不过 `stripAssetHost` —— 它不引用任何素材，
+            //   反射源是运行时从 `textures[0].url` 取的（上面那个键自己就落进存档了）。
+            glass: this.glassPanes.map((gp) => gp.toData()),
         };
     }
 
@@ -1396,11 +1519,58 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             (data.models ?? []).map((d) => ({ ...d, url: d.url ? absAssetUrl(d.url, pn) : "" })),
             onModelLoad
         );
+        // 玻璃面层（2026-10-28 需求）：排在 setTextures **之后**是硬要求 —— 它的反射源读的就是刚还原好的
+        //   `textures[0].url`（补过域名的形态），排在前面会用上一次项目的地址起一次错的载。
+        //   旧存档没有这个键 ⇒ 空数组 = 整层清空，与上面两层的口径逐字一致。
+        this.setGlassPanes(data.glass ?? []);
+    }
+
+    /**
+     * 把**存档里前 `PANO_IMPORT_PRIORITY` 个全景**的素材点名抢在别的之前加载（2026-10-29 需求）。
+     * 由两处渲染循环每帧点一次：基类 `onBeforeRender`（预览弹窗 / 发布页）与编辑器的 `updateFloorTexture`
+     *（`MktDevMesh` 覆写了 `onBeforeRender`，只点 `syncProjInvMatrix` + `tickProgressiveReveal`，库内那句在编辑态不跑）。
+     *
+     * 为什么能「先加载」：拼合器每帧那三道工序（补下载 → 画已进 GPU 的 → 再传一张）都按
+     *   `_groups` 这张 Map 的**在册顺序**取料，而下载额度只有「每帧 2 张 / 在途 ≤8 / 已解码待上传 ≤8」
+     *   （`panoTileStitcher.ts` 顶部那三个常数）⇒ 排在头部的两组把额度吃满，其余全景要等它们画满才轮得到。
+     *   平时这个顺序由每帧的槽位名册定（离注视点近的先下），本方法把它钉成「存档数组的前两个」，与机位无关。
+     * ⚠️⚠️ 为什么点名时要带第三个参 `front = true`（每帧把这两批**挪回队首**）而⛔ 不只是「先入册」：
+     *   在册顺序是拼合器自己的状态 —— 后入册的只会**追加到队尾**，而 `ensure` 幂等、已在册就不再移动。
+     *   预览这条路恰好是最坏的那种排法：`feedFaceMapping` 开头还有一记 `pump`，拼合器**第一次**拿到渲染器时
+     *   必走 `_switchRenderer`（`null → 真 renderer` 也算换，弹窗每开一次就是换一次）把在册组整份作废，
+     *   随后名册按距离重新入册占了队首 ⇒ 本方法下一帧重新入册只能排在它们后面，而且**从此再也翻不了身**。
+     *   2026-10-29 逐帧打点就是这个形状：帧 1 `p0,p1,p11…p4` → 帧 2 起 `p11…p4,p0,p1`，
+     *   40 帧下来 p0 只下到 1 片、p1 下到 30 片，离注视点最近那颗第 13 条请求就开始了 = 线上报的现象。
+     *   ⇒ 带 `front` 之后顺序每帧重新成立，与谁先入册、作废过几次、机位在哪都无关
+     *   （真跑自证在护栏 BE ④：`D` 后入册排队尾，带 `front` 再点一次 ⇒ 立刻回到队首、下一帧下载全归它）。
+     * ⚠️ 为什么是**每帧**而不是「载入那一次点一记」：上面那次作废就发生在载入之后的第一帧，
+     *   只在 `importData` 里点名等于白点；本方法点在 `pump` 之后、名册逐槽 `ensure` 之前，且每帧都点
+     *   （已在册且已在队首 ⇒ `_toFront` 里一次 `keys().next()` 就返回，没有额外开销）。
+     * ⛔ 不另立第二把下载尺：这里用的就是 `feedFaceMapping` 每帧在用的同一个 `ensure(info.tiles, …)`
+     *   与同一个批次键（第一条非空瓦片地址）⇒ 后面那句自然判重，一片瓦片终身只 `fetch` 一次。
+     * ⚠️ 形态判据读 `this._panoTexMode`（整图形态那一档一张全景只有一张整图，走 `_texCache` 那条路，
+     *   走错档就是白下 32 片）⇒ 宿主若用自己那份形态变量（编辑器的 `store.panoTexMode`），
+     *   要在调 `importData` 之前先 `setPanoTexMode` 推进来，编辑器那侧已按此接线。
+     * ⚠️ 代价如实记：这两颗全景若本来不在开机那一刻的名册里，它们的瓦片与拼合槽 RT 会被**提前**建出来
+     *   （现行口径每颗全景 2 槽 × 6144² ≈ 400MB 显存）—— 组在运行中不淘汰，走进那两个景点迟早要建，
+     *   这里只是把这一笔挪到了载入的第一帧。
+     */
+    prefetchHeadPanoramas(): void {
+        const n = Math.min(PANO_IMPORT_PRIORITY, this.textures.length);
+        // ⚠️ **倒着**点：`front` 是「挪到最前」，正着点会让 0 号被 1 号压到后面（实测队首变成 `p1,p0`）
+        //   ⇒ 倒着点，最后一手挪的是 0 号，存档序号小的仍排在更前。
+        for (let i = n - 1; i >= 0; i--) {
+            const info = this.textures[i];
+            // 与 `feedFaceMapping` 里那一句同判据：真瓦片才进拼合器，整图形态进瓦片缓存
+            // 第三个参 `true` = 把这批**挪到在册顺序最前**（⛔ 光靠「先入册」押不住顺序，见方法头）
+            if (mktPanoTiledFlag(info.tiles, this._panoTexMode) === 1) this._stitcher.ensure(info.tiles, undefined, true);
+            else if (info.url) this.ensureTileTexture(info.url, false);
+        }
     }
 
     // ───────────────────────── 释放 ─────────────────────────
 
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，2026-10-02 决定）、拼合器、平面图 / 模型 / 玻璃面三层、几何、材质 */
     dispose(): this {
         // ⚠️ rt 虚拟键从不进 `_texCache`（拼合槽纹理由 `_stitcher` 自己持有并释放），这里清的都是本类下载的 Texture。
         // ⭐ 甲（2026-10-05）：`releasePanoTexture` 除 `dispose()` 外还要 `ImageBitmap.close()` —— 位图的原生内存
@@ -1422,6 +1592,16 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             ms.dispose();
         }
         this.models = [];
+        // 玻璃面层：几何/材质各归各颗释放；那张共用的反射纹理在这里连位图一起关
+        //   （⛔ 它从不在 `_texCache` 里 ⇒ 上面那一轮清不到它，漏了这一句就是每次换页漏一张全景整图）。
+        for (const gp of this.glassPanes) {
+            this.remove(gp);
+            gp.dispose();
+        }
+        this.glassPanes = [];
+        releasePanoTexture(this._glassEnvTex);
+        this._glassEnvTex = null;
+        this._glassEnvKey = "";
         this._imgTileLoader.clear();
         this._imgBindQueued.clear();
         this._imgBindDone.clear();

package/MktMesh/glassPane.d.ts

@@ -0,0 +1,43 @@
+import { Mesh, MeshPhysicalMaterial, PlaneGeometry, Texture } from "three";
+/** 玻璃面的持久化数据（进 `MktMesh.exportData` 的 `glass` 键 / `importData` 还原） */
+export interface GlassPaneData {
+    name?: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** 正方形边长（米）：宽 = 高 = 本值，⛔ 不拆成两档 */
+    size: number;
+}
+export declare class GlassPane extends Mesh<PlaneGeometry, MeshPhysicalMaterial> {
+    private _originalColor;
+    /** 反射环境纹理的身份（由 `MktMesh` 注入，本类只持有引用、⛔ 从不 dispose 它 —— 那张按地址缓存在库里） */
+    private _envTex;
+    constructor(name?: string);
+    get paneSize(): number;
+    /** 换正方形边长（宽高等比跟着走：几何只有这一把尺） */
+    setPaneSize(size: number): void;
+    /**
+     * 绑/摘反射环境纹理（`null` = 还没有可用的环境源）。
+     * ⚠️ 判等在前：`material.needsUpdate = true` 会涨材质版本 ⇒ 程序要重编译。库里给同一批玻璃面注入的是
+     *   **同一个 Texture 对象**（反射源只下载一次），逐颗重复赋同一张时必须早退，不然就是 N 次无谓重编译。
+     * ⚠️ 传进来的纹理必须已标 `EquirectangularReflectionMapping`：three 的 `WebGLCubeUVMaps` 只认那个标记才会
+     *   自动把它卷积成立方 UV（PMREM）；直接给一张普通 UV 纹理（例如全景拼合槽的那两张 RT）采出来是花屏。
+     */
+    setEnvironmentTexture(tex: Texture | null): void;
+    highlight(): void;
+    restoreColor(): void;
+    toData(): GlassPaneData;
+    applyData(d: GlassPaneData): void;
+    /** 只释放自己的几何与材质；反射纹理归 `MktMesh` 管（多颗共用一张）。 */
+    dispose(): void;
+}
+export declare const GLASS_PANE_DEFAULTS: {
+    size: number;
+};

package/MktMesh/glassPane.js

@@ -0,0 +1,97 @@
+/*
+ * @Description: 正方形玻璃面 —— 2026-10-28 需求「mkteditor 还需要增加一个 正方的面的 功能, 要双面显示,
+ *   环境贴图就用第一个全景, 效果用 three.js 的 webgl_materials_physical_transmission 案例, 并且要写入 json 数据和回显」。
+ *
+ * 定位：与「图片平面」（`./imagePlane.ts`）同为挂在 `MktMesh` 子树下的独立 Mesh，但材质完全不同：
+ * - 图片平面 = MeshBasicMaterial + FrontSide + 自带内容瓦片（单面可见是 2026-10-22 单独点名的，⛔ 不适用于本类）；
+ * - 玻璃面 = MeshPhysicalMaterial + DoubleSide + transmission（本次点名「要双面显示」⇒ 正反两面都画、都折射）。
+ *   它自己没有内容纹理：画面 = 背后的东西被折射 + 一层反射，反射来自 `MktMesh` 给的**第一个全景**（`setEnvironmentTexture`）。
+ *
+ * 材质参数逐字对齐官方示例 `webgl_materials_physical_transmission` 的默认档
+ * （transmission 1 / ior 1.5 / thickness 0.01 / roughness 0 / metalness 0 / specularIntensity 1 /
+ *   specularColor 白 / envMapIntensity 1 / color 白 / opacity 1 / transparent true / side DoubleSide）。
+ * ⛔ 示例 GUI 里那颗 `transmissionResolutionScale` 在 three 0.167 的构建里不存在（属主渲染器且该版本无此属性），
+ *   写了会直接把类型检查打红 ⇒ 本文件与宿主都不设它，折射全屏缓冲用引擎默认分辨率。
+ * ⛔ 不设 `alphaMap`：示例把它挂在那颗圆环上（切面形状用），玻璃面就是一块方板，没有alpha 轮廓要描。
+ *
+ * 形状：正方形 ⇒ 存档只有**一个**边长 `size`（米），宽恒等于高。几何仍是 PlaneGeometry(size, size)，
+ * 原点在板中心，落地/贴墙那两种落点由调用者摆（与图片平面同一条口径，见编辑器 `addGlassPaneAt`）。
+ */
+import { Color, DoubleSide, Mesh, MeshPhysicalMaterial, PlaneGeometry } from "three";
+const DEFAULT_SIZE = 1.5;
+/** 选中高亮色：与图片平面/模型槽同一档（同族观感一致，只换颜色不换形态） */
+const HIGHLIGHT_COLOR = "#ffd24a";
+export class GlassPane extends Mesh {
+    _originalColor = "#ffffff";
+    /** 反射环境纹理的身份（由 `MktMesh` 注入，本类只持有引用、⛔ 从不 dispose 它 —— 那张按地址缓存在库里） */
+    _envTex = null;
+    constructor(name) {
+        const geo = new PlaneGeometry(DEFAULT_SIZE, DEFAULT_SIZE);
+        const mat = new MeshPhysicalMaterial({
+            color: new Color("#ffffff"),
+            // 双面（本次点名「要双面显示」）：正面反面都画，也都能被射线打中
+            //（three 的射线拾取按材质 side 剔背面，见 `node_modules/three/src/objects/Mesh.js`）。
+            side: DoubleSide,
+            transparent: true,
+            opacity: 1,
+            // ↓ 以下六档 + 上面两档 = 官方示例的默认 GUI 值，一字未改
+            transmission: 1,
+            ior: 1.5,
+            thickness: 0.01,
+            roughness: 0,
+            metalness: 0,
+            specularIntensity: 1,
+            specularColor: new Color("#ffffff"),
+            envMapIntensity: 1,
+        });
+        super(geo, mat);
+        this.name = name || "玻璃面";
+    }
+    get paneSize() { return this.geometry.parameters.width; }
+    /** 换正方形边长（宽高等比跟着走：几何只有这一把尺） */
+    setPaneSize(size) {
+        this.geometry.dispose();
+        this.geometry = new PlaneGeometry(size, size);
+    }
+    /**
+     * 绑/摘反射环境纹理（`null` = 还没有可用的环境源）。
+     * ⚠️ 判等在前：`material.needsUpdate = true` 会涨材质版本 ⇒ 程序要重编译。库里给同一批玻璃面注入的是
+     *   **同一个 Texture 对象**（反射源只下载一次），逐颗重复赋同一张时必须早退，不然就是 N 次无谓重编译。
+     * ⚠️ 传进来的纹理必须已标 `EquirectangularReflectionMapping`：three 的 `WebGLCubeUVMaps` 只认那个标记才会
+     *   自动把它卷积成立方 UV（PMREM）；直接给一张普通 UV 纹理（例如全景拼合槽的那两张 RT）采出来是花屏。
+     */
+    setEnvironmentTexture(tex) {
+        if (this._envTex === tex)
+            return;
+        this._envTex = tex;
+        this.material.envMap = tex;
+        this.material.needsUpdate = true;
+    }
+    highlight() {
+        this.material.color.set(HIGHLIGHT_COLOR);
+    }
+    restoreColor() {
+        this.material.color.set(this._originalColor);
+    }
+    toData() {
+        return {
+            name: this.name || undefined,
+            position: { x: this.position.x, y: this.position.y, z: this.position.z },
+            rotation: { x: this.rotation.x, y: this.rotation.y, z: this.rotation.z },
+            size: this.paneSize,
+        };
+    }
+    applyData(d) {
+        if (d.name)
+            this.name = d.name;
+        this.position.set(d.position.x, d.position.y, d.position.z);
+        this.rotation.set(d.rotation.x, d.rotation.y, d.rotation.z);
+        this.setPaneSize(d.size);
+    }
+    /** 只释放自己的几何与材质；反射纹理归 `MktMesh` 管（多颗共用一张）。 */
+    dispose() {
+        this.geometry.dispose();
+        this.material.dispose();
+    }
+}
+export const GLASS_PANE_DEFAULTS = { size: DEFAULT_SIZE };

package/MktMesh/glassPane.ts

@@ -0,0 +1,116 @@
+/*
+ * @Description: 正方形玻璃面 —— 2026-10-28 需求「mkteditor 还需要增加一个 正方的面的 功能, 要双面显示,
+ *   环境贴图就用第一个全景, 效果用 three.js 的 webgl_materials_physical_transmission 案例, 并且要写入 json 数据和回显」。
+ *
+ * 定位：与「图片平面」（`./imagePlane.ts`）同为挂在 `MktMesh` 子树下的独立 Mesh，但材质完全不同：
+ * - 图片平面 = MeshBasicMaterial + FrontSide + 自带内容瓦片（单面可见是 2026-10-22 单独点名的，⛔ 不适用于本类）；
+ * - 玻璃面 = MeshPhysicalMaterial + DoubleSide + transmission（本次点名「要双面显示」⇒ 正反两面都画、都折射）。
+ *   它自己没有内容纹理：画面 = 背后的东西被折射 + 一层反射，反射来自 `MktMesh` 给的**第一个全景**（`setEnvironmentTexture`）。
+ *
+ * 材质参数逐字对齐官方示例 `webgl_materials_physical_transmission` 的默认档
+ * （transmission 1 / ior 1.5 / thickness 0.01 / roughness 0 / metalness 0 / specularIntensity 1 /
+ *   specularColor 白 / envMapIntensity 1 / color 白 / opacity 1 / transparent true / side DoubleSide）。
+ * ⛔ 示例 GUI 里那颗 `transmissionResolutionScale` 在 three 0.167 的构建里不存在（属主渲染器且该版本无此属性），
+ *   写了会直接把类型检查打红 ⇒ 本文件与宿主都不设它，折射全屏缓冲用引擎默认分辨率。
+ * ⛔ 不设 `alphaMap`：示例把它挂在那颗圆环上（切面形状用），玻璃面就是一块方板，没有alpha 轮廓要描。
+ *
+ * 形状：正方形 ⇒ 存档只有**一个**边长 `size`（米），宽恒等于高。几何仍是 PlaneGeometry(size, size)，
+ * 原点在板中心，落地/贴墙那两种落点由调用者摆（与图片平面同一条口径，见编辑器 `addGlassPaneAt`）。
+ */
+import { Color, DoubleSide, Mesh, MeshPhysicalMaterial, PlaneGeometry, Texture } from "three";
+
+/** 玻璃面的持久化数据（进 `MktMesh.exportData` 的 `glass` 键 / `importData` 还原） */
+export interface GlassPaneData {
+    name?: string;
+    position: { x: number; y: number; z: number };
+    rotation: { x: number; y: number; z: number };
+    /** 正方形边长（米）：宽 = 高 = 本值，⛔ 不拆成两档 */
+    size: number;
+}
+
+const DEFAULT_SIZE = 1.5;
+/** 选中高亮色：与图片平面/模型槽同一档（同族观感一致，只换颜色不换形态） */
+const HIGHLIGHT_COLOR = "#ffd24a";
+
+export class GlassPane extends Mesh<PlaneGeometry, MeshPhysicalMaterial> {
+    private _originalColor: string = "#ffffff";
+    /** 反射环境纹理的身份（由 `MktMesh` 注入，本类只持有引用、⛔ 从不 dispose 它 —— 那张按地址缓存在库里） */
+    private _envTex: Texture | null = null;
+
+    constructor(name?: string) {
+        const geo = new PlaneGeometry(DEFAULT_SIZE, DEFAULT_SIZE);
+        const mat = new MeshPhysicalMaterial({
+            color: new Color("#ffffff"),
+            // 双面（本次点名「要双面显示」）：正面反面都画，也都能被射线打中
+            //（three 的射线拾取按材质 side 剔背面，见 `node_modules/three/src/objects/Mesh.js`）。
+            side: DoubleSide,
+            transparent: true,
+            opacity: 1,
+            // ↓ 以下六档 + 上面两档 = 官方示例的默认 GUI 值，一字未改
+            transmission: 1,
+            ior: 1.5,
+            thickness: 0.01,
+            roughness: 0,
+            metalness: 0,
+            specularIntensity: 1,
+            specularColor: new Color("#ffffff"),
+            envMapIntensity: 1,
+        });
+        super(geo, mat);
+        this.name = name || "玻璃面";
+    }
+
+    get paneSize(): number { return (this.geometry as PlaneGeometry).parameters.width; }
+
+    /** 换正方形边长（宽高等比跟着走：几何只有这一把尺） */
+    setPaneSize(size: number): void {
+        this.geometry.dispose();
+        this.geometry = new PlaneGeometry(size, size);
+    }
+
+    /**
+     * 绑/摘反射环境纹理（`null` = 还没有可用的环境源）。
+     * ⚠️ 判等在前：`material.needsUpdate = true` 会涨材质版本 ⇒ 程序要重编译。库里给同一批玻璃面注入的是
+     *   **同一个 Texture 对象**（反射源只下载一次），逐颗重复赋同一张时必须早退，不然就是 N 次无谓重编译。
+     * ⚠️ 传进来的纹理必须已标 `EquirectangularReflectionMapping`：three 的 `WebGLCubeUVMaps` 只认那个标记才会
+     *   自动把它卷积成立方 UV（PMREM）；直接给一张普通 UV 纹理（例如全景拼合槽的那两张 RT）采出来是花屏。
+     */
+    setEnvironmentTexture(tex: Texture | null): void {
+        if (this._envTex === tex) return;
+        this._envTex = tex;
+        this.material.envMap = tex;
+        this.material.needsUpdate = true;
+    }
+
+    highlight(): void {
+        this.material.color.set(HIGHLIGHT_COLOR);
+    }
+
+    restoreColor(): void {
+        this.material.color.set(this._originalColor);
+    }
+
+    toData(): GlassPaneData {
+        return {
+            name: this.name || undefined,
+            position: { x: this.position.x, y: this.position.y, z: this.position.z },
+            rotation: { x: this.rotation.x, y: this.rotation.y, z: this.rotation.z },
+            size: this.paneSize,
+        };
+    }
+
+    applyData(d: GlassPaneData): void {
+        if (d.name) this.name = d.name;
+        this.position.set(d.position.x, d.position.y, d.position.z);
+        this.rotation.set(d.rotation.x, d.rotation.y, d.rotation.z);
+        this.setPaneSize(d.size);
+    }
+
+    /** 只释放自己的几何与材质；反射纹理归 `MktMesh` 管（多颗共用一张）。 */
+    dispose(): void {
+        this.geometry.dispose();
+        this.material.dispose();
+    }
+}
+
+export const GLASS_PANE_DEFAULTS = { size: DEFAULT_SIZE };

package/MktMesh/panoBitmapTexture.d.ts

@@ -16,8 +16,11 @@ import { Texture } from "three";
  * 明说「已经翻过了」。1×2 像素对照实测：`<img>`+flipY=true 与 bitmap(flipY)+flipY=false 逐行一致。
  */
 /** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
- *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
- *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
+ *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（用户决定 2026-09-25），
+ *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。
+ *  ⭐ 这一步走的是原生 `fetch`，不经过 three 的 `Loader`，所以它**自己**向 `DefaultLoadingManager`
+ *  报一次 `itemStart` / `itemEnd`（失败再多一次 `itemError`，与 `FileLoader` 的口径一致）——
+ *  否则页面拿到的加载状态只算模型和 `TextureLoader` 那些路，全景切片的下载完全不在里面。 */
 export declare function loadPanoTexture(url: string): Promise<Texture>;
 /** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**
  *  （不像 `<img>` 能等 GC —— 一张 270MB 的位图挂着不关，切几轮全景就把进程吃爆）。

package/MktMesh/panoBitmapTexture.js

@@ -1,4 +1,4 @@
-import { Texture } from "three";
+import { DefaultLoadingManager, Texture } from "three";
 /**
  * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
  *
@@ -16,10 +16,14 @@ import { Texture } from "three";
  * 明说「已经翻过了」。1×2 像素对照实测：`<img>`+flipY=true 与 bitmap(flipY)+flipY=false 逐行一致。
  */
 /** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
- *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
- *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
+ *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（用户决定 2026-09-25），
+ *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。
+ *  ⭐ 这一步走的是原生 `fetch`，不经过 three 的 `Loader`，所以它**自己**向 `DefaultLoadingManager`
+ *  报一次 `itemStart` / `itemEnd`（失败再多一次 `itemError`，与 `FileLoader` 的口径一致）——
+ *  否则页面拿到的加载状态只算模型和 `TextureLoader` 那些路，全景切片的下载完全不在里面。 */
 export function loadPanoTexture(url) {
-    return fetch(url)
+    DefaultLoadingManager.itemStart(url);
+    const task = fetch(url)
         .then((res) => {
         if (!res.ok)
             throw new Error(`HTTP ${res.status}`);
@@ -38,6 +42,12 @@ export function loadPanoTexture(url) {
         tex.userData.url = url;
         return tex;
     });
+    // 一条 promise 只 settle 一次 ⇒ 开始/结束各报一次，两边都不会漏；reject 原样透给调用方。
+    task.then(() => DefaultLoadingManager.itemEnd(url), () => {
+        DefaultLoadingManager.itemError(url);
+        DefaultLoadingManager.itemEnd(url);
+    });
+    return task;
 }
 /** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**
  *  （不像 `<img>` 能等 GC —— 一张 270MB 的位图挂着不关，切几轮全景就把进程吃爆）。

package/MktMesh/panoBitmapTexture.ts

@@ -1,4 +1,4 @@
-import { Texture } from "three";
+import { DefaultLoadingManager, Texture } from "three";
 
 /**
  * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
@@ -18,10 +18,14 @@ import { Texture } from "three";
  */
 
 /** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
- *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
- *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
+ *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（用户决定 2026-09-25），
+ *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。
+ *  ⭐ 这一步走的是原生 `fetch`，不经过 three 的 `Loader`，所以它**自己**向 `DefaultLoadingManager`
+ *  报一次 `itemStart` / `itemEnd`（失败再多一次 `itemError`，与 `FileLoader` 的口径一致）——
+ *  否则页面拿到的加载状态只算模型和 `TextureLoader` 那些路，全景切片的下载完全不在里面。 */
 export function loadPanoTexture(url: string): Promise<Texture> {
-    return fetch(url)
+    DefaultLoadingManager.itemStart(url);
+    const task = fetch(url)
         .then((res) => {
             if (!res.ok) throw new Error(`HTTP ${res.status}`);
             return res.blob();
@@ -41,6 +45,15 @@ export function loadPanoTexture(url: string): Promise<Texture> {
             tex.userData.url = url;
             return tex;
         });
+    // 一条 promise 只 settle 一次 ⇒ 开始/结束各报一次，两边都不会漏；reject 原样透给调用方。
+    task.then(
+        () => DefaultLoadingManager.itemEnd(url),
+        () => {
+            DefaultLoadingManager.itemError(url);
+            DefaultLoadingManager.itemEnd(url);
+        }
+    );
+    return task;
 }
 
 /** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**

package/MktMesh/panoTileStitcher.d.ts

@@ -7,8 +7,11 @@ import { type TileLayout } from "./mktShader";
 export interface PanoStitcher {
     /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做）。
      *  新增可选 `layout` 参数：缺省 = PANO_TILE_LAYOUT（全景 8×4 / 2 槽 / 6144×6144，2026-10-27 需求）；
-     *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。 */
-    ensure(urls: string[], layout?: TileLayout): void;
+     *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。
+     *  新增可选 `front` 参数（2026-10-29 需求）：`true` ⇒ 这一批**挪到在册顺序最前** = 每帧那三道工序
+     *  先取它的料（下载额度「每帧 2 张」先归它）。消费方每帧点一次 ⇒ 换渲染器那次整份作废后，
+     *  下一帧又把头名抢回来（⛔ 光靠「先入册」做不到，见 `MktMesh.prefetchHeadPanoramas` 的说明）。 */
+    ensure(urls: string[], layout?: TileLayout, front?: boolean): void;
     /**
      * 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）。
      * ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：**传了 `renderer` 且该槽一格都还没画时，
@@ -74,7 +77,10 @@ export declare class PanoTileStitcher implements PanoStitcher {
      *  ⚠️ 唯一按张数**能混进来**的是 10-06 那版同为 32 片的老档（切片顺序与槽分组两版一致 ⇒ 不会错位），
      *  但它的瓦片是 1024²、被画进 1536² 的格子 = 1.5× 放大 ⇒ 发虚，那类老点仍要重传一次。
      *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null]` —— 槽数再变会漏改）。 */
-    ensure(urls: string[], layout?: TileLayout): void;
+    ensure(urls: string[], layout?: TileLayout, front?: boolean): void;
+    /** 把一批挪到在册顺序的**最前**（只动 Map 的顺序，⛔ 不动组里任何东西：RT、已画格子、瓦片账本原样）。
+     *  已在最前 ⇒ 一次 `keys().next()` 就返回（每帧点名走的就是这条零成本支路）。 */
+    private _toFront;
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 `cellsPerSlot` 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
     peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null;

package/MktMesh/panoTileStitcher.js

@@ -220,7 +220,7 @@ export class PanoTileStitcher {
      *  ⚠️ 唯一按张数**能混进来**的是 10-06 那版同为 32 片的老档（切片顺序与槽分组两版一致 ⇒ 不会错位），
      *  但它的瓦片是 1024²、被画进 1536² 的格子 = 1.5× 放大 ⇒ 发虚，那类老点仍要重传一次。
      *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null]` —— 槽数再变会漏改）。 */
-    ensure(urls, layout) {
+    ensure(urls, layout, front = false) {
         const L = layout ?? PANO_TILE_LAYOUT;
         const maxTiles = tilesPerBatchOf(L);
         if (!urls || urls.length === 0 || urls.length > maxTiles)
@@ -229,8 +229,11 @@ export class PanoTileStitcher {
         while (u.length < maxTiles)
             u.push("");
         const batch = rtStitchBatchOf(u);
-        if (this._groups.has(batch))
+        if (this._groups.has(batch)) {
+            if (front)
+                this._toFront(batch);
             return;
+        }
         const slotCount = L.slotCount;
         const cellsPerSlot = cellsPerSlotOf(L);
         this._groups.set(batch, {
@@ -244,8 +247,26 @@ export class PanoTileStitcher {
             drawnCount: Array.from({ length: slotCount }, () => 0),
             pending: slotCount,
         });
+        if (front)
+            this._toFront(batch);
         this._stamp++;
     }
+    /** 把一批挪到在册顺序的**最前**（只动 Map 的顺序，⛔ 不动组里任何东西：RT、已画格子、瓦片账本原样）。
+     *  已在最前 ⇒ 一次 `keys().next()` 就返回（每帧点名走的就是这条零成本支路）。 */
+    _toFront(batch) {
+        const g = this._groups.get(batch);
+        if (!g)
+            return;
+        const head = this._groups.keys().next();
+        if (!head.done && head.value === batch)
+            return;
+        const rest = [...this._groups.entries()];
+        this._groups.clear();
+        this._groups.set(batch, g);
+        for (const [k, v] of rest)
+            if (k !== batch)
+                this._groups.set(k, v);
+    }
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 `cellsPerSlot` 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
     peek(batch, slot, renderer) {

package/MktMesh/panoTileStitcher.ts

@@ -238,8 +238,11 @@ interface StitchGroup {
 export interface PanoStitcher {
     /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做）。
      *  新增可选 `layout` 参数：缺省 = PANO_TILE_LAYOUT（全景 8×4 / 2 槽 / 6144×6144，2026-10-27 需求）；
-     *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。 */
-    ensure(urls: string[], layout?: TileLayout): void;
+     *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。
+     *  新增可选 `front` 参数（2026-10-29 需求）：`true` ⇒ 这一批**挪到在册顺序最前** = 每帧那三道工序
+     *  先取它的料（下载额度「每帧 2 张」先归它）。消费方每帧点一次 ⇒ 换渲染器那次整份作废后，
+     *  下一帧又把头名抢回来（⛔ 光靠「先入册」做不到，见 `MktMesh.prefetchHeadPanoramas` 的说明）。 */
+    ensure(urls: string[], layout?: TileLayout, front?: boolean): void;
     /**
      * 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）。
      * ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：**传了 `renderer` 且该槽一格都还没画时，
@@ -326,14 +329,17 @@ private _uploadQueued: Set<TileRec> = new Set();
      *  ⚠️ 唯一按张数**能混进来**的是 10-06 那版同为 32 片的老档（切片顺序与槽分组两版一致 ⇒ 不会错位），
      *  但它的瓦片是 1024²、被画进 1536² 的格子 = 1.5× 放大 ⇒ 发虚，那类老点仍要重传一次。
      *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null]` —— 槽数再变会漏改）。 */
-    ensure(urls: string[], layout?: TileLayout): void {
+    ensure(urls: string[], layout?: TileLayout, front = false): void {
         const L = layout ?? PANO_TILE_LAYOUT;
         const maxTiles = tilesPerBatchOf(L);
         if (!urls || urls.length === 0 || urls.length > maxTiles) return;
         const u = urls.slice();
         while (u.length < maxTiles) u.push("");
         const batch = rtStitchBatchOf(u);
-        if (this._groups.has(batch)) return;
+        if (this._groups.has(batch)) {
+            if (front) this._toFront(batch);
+            return;
+        }
         const slotCount = L.slotCount;
         const cellsPerSlot = cellsPerSlotOf(L);
         this._groups.set(batch, {
@@ -347,9 +353,23 @@ private _uploadQueued: Set<TileRec> = new Set();
             drawnCount: Array.from({ length: slotCount }, () => 0),
             pending: slotCount,
         });
+        if (front) this._toFront(batch);
         this._stamp++;
     }
 
+    /** 把一批挪到在册顺序的**最前**（只动 Map 的顺序，⛔ 不动组里任何东西：RT、已画格子、瓦片账本原样）。
+     *  已在最前 ⇒ 一次 `keys().next()` 就返回（每帧点名走的就是这条零成本支路）。 */
+    private _toFront(batch: string): void {
+        const g = this._groups.get(batch);
+        if (!g) return;
+        const head = this._groups.keys().next();
+        if (!head.done && head.value === batch) return;
+        const rest = [...this._groups.entries()];
+        this._groups.clear();
+        this._groups.set(batch, g);
+        for (const [k, v] of rest) if (k !== batch) this._groups.set(k, v);
+    }
+
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 `cellsPerSlot` 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
     peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null {

package/MktMesh/types.d.ts

@@ -1,6 +1,7 @@
 import type { Matrix4 } from "three";
 import type { ImagePlaneData } from "./imagePlane";
 import type { ModelSlotData } from "./modelSlot";
+import type { GlassPaneData } from "./glassPane";
 /**
  * 单个纹理的运行时信息：url + 矩阵（位置 + 旋转，缩放忽略）。
  * ⚠️ 这个矩阵记在 MktMesh **自身局部（制图）空间**，与 `wallPoints` 同一空间 —— 不是世界矩阵：
@@ -87,4 +88,9 @@ export interface MktMeshData {
     images?: ImagePlaneData[];
     /** 模型槽层（同一道旨）：`url` 是 .glb 的相对地址；空串 = 还没上传 ⇒ 显示占位小立方体 */
     models?: ModelSlotData[];
+    /**
+     * 玻璃面层（2026-10-28 需求「正方的面」）：正方形、双面、transmission 折射，反射环境取运行时第一个全景。
+     * ⛔ 这一层不落任何素材地址 ⇒ 既不过 `stripAssetHost` 也不过 `absAssetUrl`，只有位置/旋转/边长。
+     */
+    glass?: GlassPaneData[];
 }

package/MktMesh/types.ts

@@ -8,6 +8,7 @@
 import type { Matrix4 } from "three";
 import type { ImagePlaneData } from "./imagePlane";
 import type { ModelSlotData } from "./modelSlot";
+import type { GlassPaneData } from "./glassPane";
 
 /**
  * 单个纹理的运行时信息：url + 矩阵（位置 + 旋转，缩放忽略）。
@@ -99,4 +100,9 @@ export interface MktMeshData {
     images?: ImagePlaneData[];
     /** 模型槽层（同一道旨）：`url` 是 .glb 的相对地址；空串 = 还没上传 ⇒ 显示占位小立方体 */
     models?: ModelSlotData[];
+    /**
+     * 玻璃面层（2026-10-28 需求「正方的面」）：正方形、双面、transmission 折射，反射环境取运行时第一个全景。
+     * ⛔ 这一层不落任何素材地址 ⇒ 既不过 `stripAssetHost` 也不过 `absAssetUrl`，只有位置/旋转/边长。
+     */
+    glass?: GlassPaneData[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-base",
-  "version": "2.0.192",
+  "version": "2.0.193",
   "description": "A Three.js extension library providing common 3D components, animations, materials, and utilities",
   "author": "xiaosihan",
   "publishConfig": {
@@ -47,6 +47,11 @@
       "import": "./MktMesh/modelSlot.js",
       "require": "./MktMesh/modelSlot.js"
     },
+    "./MktMesh/glassPane": {
+      "types": "./MktMesh/glassPane.d.ts",
+      "import": "./MktMesh/glassPane.js",
+      "require": "./MktMesh/glassPane.js"
+    },
     "./MktMesh/boxLine2": {
       "types": "./MktMesh/boxLine2.d.ts",
       "import": "./MktMesh/boxLine2.js",

package/threeLoader.js

@@ -28,6 +28,8 @@ class ThreeLoader extends EventDispatcher {
         };
         // 资源加载进度
         DefaultLoadingManager.onProgress = (url, loaded, total) => {
+            // 三个数一并转发：首页只认「还在不在加载」，弹窗一类要看进度
+            this.dispatchEvent({ type: "progress", url, loaded, total });
             if (loaded < total) {
                 this.dispatchEvent({ type: "loadding" });
             }

package/threeLoader.ts

@@ -32,6 +32,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
         };
         // 资源加载进度
         DefaultLoadingManager.onProgress = (url: string, loaded: number, total: number) => {
+            // 三个数一并转发：首页只认「还在不在加载」，弹窗一类要看进度
+            this.dispatchEvent({ type: "progress", url, loaded, total });
             if (loaded < total) {
                 this.dispatchEvent({ type: "loadding" });
             }