three-base 2.0.190 → 2.0.193

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/imagePlane.d.ts

@@ -37,9 +37,13 @@ export declare class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
     private _uInset;
     private _uValid;
     private _data;
+    /** 内容是否已落定：4 格里至少有一格真的绑上了纹理。**只朝 true 翻一次**（之后逐张显影继续，但不再回退成「没内容」）。 */
+    private _loaded;
     constructor(name?: string);
     get imageWidth(): number;
     get imageHeight(): number;
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded(): boolean;
     setPlaneSize(w: number, h: number): void;
     setPlaneData(d: Pick<ImagePlaneData, "url" | "tiles" | "naturalW" | "naturalH">): void;
     get tiles(): string[];

package/MktMesh/imagePlane.js

@@ -70,6 +70,8 @@ export class ImagePlane extends Mesh {
         url: "",
         tiles: [],
     };
+    /** 内容是否已落定：4 格里至少有一格真的绑上了纹理。**只朝 true 翻一次**（之后逐张显影继续，但不再回退成「没内容」）。 */
+    _loaded = false;
     constructor(name) {
         const geo = new PlaneGeometry(DEFAULT_WIDTH, DEFAULT_HEIGHT);
         const mat = new MeshBasicMaterial({
@@ -108,6 +110,8 @@ export class ImagePlane extends Mesh {
     }
     get imageWidth() { return this.geometry.parameters.width; }
     get imageHeight() { return this.geometry.parameters.height; }
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded() { return this._loaded; }
     setPlaneSize(w, h) {
         this.geometry.dispose();
         this.geometry = new PlaneGeometry(w, h);
@@ -127,6 +131,10 @@ export class ImagePlane extends Mesh {
             if (insets[i])
                 this._uInset.value[i].copy(insets[i]);
             this._uValid.value[i] = t ? 1 : 0;
+            // 第一格就绪 = 这一颗有东西可画了 ⇒ 落定（点亮闸认的就是这一条，⛔ 不是「4 格全到齐」：
+            // 「逐张就绪逐张显影」是本文件 10-22 晚定下的口径，等到全到齐会让先到的那几格白等几帧）。
+            if (t)
+                this._loaded = true;
         }
     }
     /** 只读「此刻材质里绑了什么」的戳记：4 格就绪位 + 已绑纹理的版本号。

package/MktMesh/imagePlane.ts

@@ -102,6 +102,8 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
         url: "",
         tiles: [],
     };
+    /** 内容是否已落定：4 格里至少有一格真的绑上了纹理。**只朝 true 翻一次**（之后逐张显影继续，但不再回退成「没内容」）。 */
+    private _loaded = false;
 
     constructor(name?: string) {
         const geo = new PlaneGeometry(DEFAULT_WIDTH, DEFAULT_HEIGHT);
@@ -145,6 +147,8 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
 
     get imageWidth(): number { return (this.geometry as PlaneGeometry).parameters.width; }
     get imageHeight(): number { return (this.geometry as PlaneGeometry).parameters.height; }
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded(): boolean { return this._loaded; }
 
     setPlaneSize(w: number, h: number): void {
         this.geometry.dispose();
@@ -167,6 +171,9 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
             this._uTiles.value[i] = t || PLACEHOLDER_TEX;
             if (insets[i]) this._uInset.value[i].copy(insets[i]);
             this._uValid.value[i] = t ? 1 : 0;
+            // 第一格就绪 = 这一颗有东西可画了 ⇒ 落定（点亮闸认的就是这一条，⛔ 不是「4 格全到齐」：
+            // 「逐张就绪逐张显影」是本文件 10-22 晚定下的口径，等到全到齐会让先到的那几格白等几帧）。
+            if (t) this._loaded = true;
         }
     }
 

package/MktMesh/modelSlot.d.ts

@@ -66,6 +66,12 @@ export declare class ModelSlot extends Group {
     private _staged;
     /** 载入令牌：换地址/删除后迟到的回调靠它作废（否则旧模型会挂进新槽） */
     private _loadToken;
+    /**
+     * 内容是否已落定：真模型挂进了 `_contentRoot`，或这一颗压根没在等什么（空地址 / 取回失败 ⇒ 停在占位小立方体）。
+     * ⚠️ 落定**不等于**已经画进 GPU —— 顶点缓冲与首次 program 编译发生在「亮出来的那一帧」，
+     *   所以逐帧限流必须闸在点亮这一下（`MktMesh.tickProgressiveReveal`），闸在挂载那一下拦不住 GPU 侧的账。
+     */
+    private _loaded;
     private _disposed;
     constructor(name?: string);
     get size(): number;
@@ -78,6 +84,8 @@ export declare class ModelSlot extends Group {
     } | undefined;
     /** 是否已经挂上真模型（false = 仍是占位小立方体） */
     get hasModel(): boolean;
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded(): boolean;
     /** 改尺寸档（米，最长边）：立刻重缩内容 */
     setSize(size: number): void;
     /**

package/MktMesh/modelSlot.js

@@ -107,6 +107,12 @@ export class ModelSlot extends Group {
     _staged = null;
     /** 载入令牌：换地址/删除后迟到的回调靠它作废（否则旧模型会挂进新槽） */
     _loadToken = 0;
+    /**
+     * 内容是否已落定：真模型挂进了 `_contentRoot`，或这一颗压根没在等什么（空地址 / 取回失败 ⇒ 停在占位小立方体）。
+     * ⚠️ 落定**不等于**已经画进 GPU —— 顶点缓冲与首次 program 编译发生在「亮出来的那一帧」，
+     *   所以逐帧限流必须闸在点亮这一下（`MktMesh.tickProgressiveReveal`），闸在挂载那一下拦不住 GPU 侧的账。
+     */
+    _loaded = false;
     _disposed = false;
     constructor(name) {
         super();
@@ -126,6 +132,8 @@ export class ModelSlot extends Group {
     get naturalSize() { return this._naturalSize; }
     /** 是否已经挂上真模型（false = 仍是占位小立方体） */
     get hasModel() { return this._model !== null; }
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded() { return this._loaded; }
     /** 改尺寸档（米，最长边）：立刻重缩内容 */
     setSize(size) {
         this._size = size > 0 ? size : this._size;
@@ -161,13 +169,25 @@ export class ModelSlot extends Group {
     async loadModel(url) {
         this._url = url;
         const token = ++this._loadToken;
+        this._loaded = false;
         this._detachModel();
         // 先立刻退回占位小立方体：GLB 在路上那段窗口（慢网/大模型）⛔ 不许让这一槽凭空消失
         //   （取回失败那条支路本来也是停在占位上，两段时间里画面一致）
         this._layout();
-        if (!url)
+        if (!url) {
+            // 空地址 = 这一颗压根没在等什么 ⇒ 当场落定（占位小立方体就是它的最终内容）
+            this._loaded = true;
             return true;
-        const obj = await threeLoader.loadModel(url);
+        }
+        // 取回失败（404 / 解析报错都从这一档走）：`threeLoader.loadModel` 是会 reject 的，⚠️ 必须当「落定在占位方块」处理
+        //   —— 整层重建时这一颗是压着不亮的，不落定就永远隐形（旧写法里它至少还露得出占位方块）。
+        let obj;
+        try {
+            obj = await threeLoader.loadModel(url);
+        }
+        catch {
+            obj = undefined;
+        }
         // 迟到回调：这一槽已经改指向别的地址、或已经删除 ⇒ 当场释放，别留一份没人认领的显存
         if (this._disposed || token !== this._loadToken) {
             if (obj)
@@ -175,6 +195,7 @@ export class ModelSlot extends Group {
             return false;
         }
         if (!obj) {
+            this._loaded = true;
             this._layout();
             return false;
         }
@@ -189,6 +210,7 @@ export class ModelSlot extends Group {
         this._staged = null;
         this._model = obj;
         this._contentRoot.add(obj);
+        this._loaded = true;
         this._layout();
         return true;
     }
@@ -220,6 +242,8 @@ export class ModelSlot extends Group {
         this._size = d.size > 0 ? d.size : MODEL_SLOT_DEFAULT_SIZE;
         this._naturalSize = d.naturalSize;
         this._url = d.url || "";
+        // 落定判据跟着地址走：空地址 = 没在等什么（占位方块就是最终内容）；有地址 = 等 GLB 那一拍
+        this._loaded = !this._url;
         if (!this._url)
             this._detachModel();
         this._layout();

package/MktMesh/modelSlot.ts

@@ -137,6 +137,12 @@ export class ModelSlot extends Group {
     private _staged: Object3D | null = null;
     /** 载入令牌：换地址/删除后迟到的回调靠它作废（否则旧模型会挂进新槽） */
     private _loadToken = 0;
+    /**
+     * 内容是否已落定：真模型挂进了 `_contentRoot`，或这一颗压根没在等什么（空地址 / 取回失败 ⇒ 停在占位小立方体）。
+     * ⚠️ 落定**不等于**已经画进 GPU —— 顶点缓冲与首次 program 编译发生在「亮出来的那一帧」，
+     *   所以逐帧限流必须闸在点亮这一下（`MktMesh.tickProgressiveReveal`），闸在挂载那一下拦不住 GPU 侧的账。
+     */
+    private _loaded = false;
     private _disposed = false;
 
     constructor(name?: string) {
@@ -164,6 +170,8 @@ export class ModelSlot extends Group {
     get naturalSize(): { x: number; y: number; z: number } | undefined { return this._naturalSize; }
     /** 是否已经挂上真模型（false = 仍是占位小立方体） */
     get hasModel(): boolean { return this._model !== null; }
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded(): boolean { return this._loaded; }
 
     /** 改尺寸档（米，最长边）：立刻重缩内容 */
     setSize(size: number): void {
@@ -201,18 +209,31 @@ export class ModelSlot extends Group {
     async loadModel(url: string): Promise<boolean> {
         this._url = url;
         const token = ++this._loadToken;
+        this._loaded = false;
         this._detachModel();
         // 先立刻退回占位小立方体：GLB 在路上那段窗口（慢网/大模型）⛔ 不许让这一槽凭空消失
         //   （取回失败那条支路本来也是停在占位上，两段时间里画面一致）
         this._layout();
-        if (!url) return true;
-        const obj = await threeLoader.loadModel(url);
+        if (!url) {
+            // 空地址 = 这一颗压根没在等什么 ⇒ 当场落定（占位小立方体就是它的最终内容）
+            this._loaded = true;
+            return true;
+        }
+        // 取回失败（404 / 解析报错都从这一档走）：`threeLoader.loadModel` 是会 reject 的，⚠️ 必须当「落定在占位方块」处理
+        //   —— 整层重建时这一颗是压着不亮的，不落定就永远隐形（旧写法里它至少还露得出占位方块）。
+        let obj: Object3D | undefined;
+        try {
+            obj = await threeLoader.loadModel(url);
+        } catch {
+            obj = undefined;
+        }
         // 迟到回调：这一槽已经改指向别的地址、或已经删除 ⇒ 当场释放，别留一份没人认领的显存
         if (this._disposed || token !== this._loadToken) {
             if (obj) disposeSubtree(obj);
             return false;
         }
         if (!obj) {
+            this._loaded = true;
             this._layout();
             return false;
         }
@@ -227,6 +248,7 @@ export class ModelSlot extends Group {
         this._staged = null;
         this._model = obj;
         this._contentRoot.add(obj);
+        this._loaded = true;
         this._layout();
         return true;
     }
@@ -257,6 +279,8 @@ export class ModelSlot extends Group {
         this._size = d.size > 0 ? d.size : MODEL_SLOT_DEFAULT_SIZE;
         this._naturalSize = d.naturalSize;
         this._url = d.url || "";
+        // 落定判据跟着地址走：空地址 = 没在等什么（占位方块就是最终内容）；有地址 = 等 GLB 那一拍
+        this._loaded = !this._url;
         if (!this._url) this._detachModel();
         this._layout();
     }

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;