three-base 2.0.180 → 2.0.187

package/MktMesh/MktMesh.d.ts

@@ -2,6 +2,8 @@ import { BufferGeometry, Camera, Matrix4, Mesh, ShaderMaterial, Texture, Vector3
 import { type PanoTexMode } from "./mktShader";
 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";
 export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
     textures: MktTextureInfo[];
@@ -119,6 +121,32 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *  必须与基类喂纹理处用同一个值，否则标记与地址不同源 ⇒ 整图被按 1/2 横向铺满球面（10-06 晚起纵向不分块，四槽时代是 1/4）。 */
     get panoTexMode(): PanoTexMode;
     private _tmpV3;
+    /**
+     * 图片平面层（⭐ 10-26 旨入库）：对象挂在**本 MktMesh 的子树**里，⛔ 不是场景根
+     * ⇒ 移动/旋转/缩放这个展品时，墙 + 全景 + 平面图 + 模型一起走。
+     */
+    imagePlanes: ImagePlane[];
+    /** 模型槽层（同一棵子树，口径同上） */
+    models: ModelSlot[];
+    /**
+     * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
+     * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不会再空一格；只随本对象 `dispose()` 释放。
+     */
+    private _imgTileLoader;
+    /**
+     * 逐帧绑定用的两张账（2026-10-26 定的方案：地址一次性全部丢给下载，绑材质改成「一帧一颗平面」）。
+     * 全局 rAF 每拍只跑一项 `addWork`，而 `addWork` 按闭包引用判重 ⇒ 每次现造的新闭包它判不出来，
+     * ⛔ 去重闸门必须像全景上传那张 `_uploadQueued` 一样自备。
+     */
+    private _imgBindQueued;
+    /** 平面 → 「它 4 条地址全部落定（就绪或失败）时的那串地址」⇒ 地址不换就不再重排；上传换图会改这串 ⇒ 自动重排 */
+    private _imgBindDone;
+    /**
+     * 模型槽「GLB 已取回、等这一帧把它挂进父元素」的在册表 —— 与上面图片绑定同一手法（用户 10-26 需求：
+     * 一次性全部拿去加载，用 `threeUtils.addWork` 逐帧加到场景里）。整层十几个槽同时到货时，
+     * 一帧只有一颗进 `_contentRoot`（进图那一拍要重算包围盒 + 排布 + 首次把几何送上 GPU）。
+     */
+    private _modelMountQueued;
     constructor(opts?: {
         wallHeight?: number;
         wallClosed?: boolean;
@@ -295,12 +323,55 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     projectName: string;
     /** 注入项目名（导出 json 前调一次即可；导入时无须调——还原靠落盘地址自身的首段） */
     setProjectName(name: string): void;
+    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 + 起排它自己的逐帧绑定 */
+    addImagePlane(ip: ImagePlane): ImagePlane;
+    /** 摘掉一颗并释放它自己的几何/材质；那 4 张瓦片纹理归 `_imgTileLoader` 管 ⇒ ⛔ 不在这里 dispose */
+    removeImagePlane(ip: ImagePlane): void;
+    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用） */
+    addModel(ms: ModelSlot): ModelSlot;
+    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾；排在后头的挂载帧靠「不在册」早退） */
+    removeModel(ms: ModelSlot): void;
+    /**
+     * 整层重建图片平面（`importData` 与预览那一路）。
+     * ⚠️ 进来的地址必须是**已补回域名**的绝对形态：补域名只有 `importData` 那一处（与 `textures` 同一把 `assetUrl` 尺），
+     *   ⛔ 本方法里不许再补一遍，也⛔ 不许在调用方各自补。
+     */
+    setImagePlanes(datas: ImagePlaneData[]): void;
+    /**
+     * 整层重建模型槽（`importData` 与预览那一路），地址口径的要求同 `setImagePlanes`。
+     * ⚠️ GLB 逐只**异步取、不 await**（十几只串一条队会把载入卡死），每只落地那一刻各回调一次 `onEachLoad`：
+     *   预览每帧真画 ⇒ 不传；编辑器是按需渲染 ⇒ 传一个「标脏」的钩子，否则模型挂上来屏幕不动。
+     * 2026-10-26 决定：取回与「挂进父元素」分两拍 —— 地址一次性全交给下载（网络 + 解析不占渲染帧），
+     *   真正进场景图那一步交给 `threeUtils.addWork` ⇒ 全局 rAF 每拍只跑一项 = **一帧只挂一颗槽**
+     *   （挂载那一拍要重算包围盒 + 排布 + 首次把整棵子树的几何送上 GPU，十几颗挤在同一帧就是他要拆掉的那一卡）。
+     */
+    setModels(datas: ModelSlotData[], onEachLoad?: () => void): void;
+    /** 把「备好待挂」的那一槽交给全局队列；⛔ 去重闸门自备（`addWork` 按闭包引用判重，新闭包它判不出来） */
+    private _queueModelMount;
+    /** 全局队列里的那一帧：只挂这一槽，挂好才回调（`onEachLoad` = 按需渲染宿主的标脏钩子） */
+    private _mountModelStep;
+    /**
+     * 把各颗平面那 4 张瓦片的纹理绑进材质（10-22 晚定的口径：不走拼合器 RT）。
+     * 2026-10-26 决定改成**逐帧**：一次把整层地址全丢给下载器（下载/解码在网络与工作线程侧，不占这一帧），
+     * 真正写 uniform 的那一步交给 `threeUtils.addWork` —— 全局 rAF 每拍只跑一项 ⇒ 一帧只绑一颗平面，
+     * 一整层平面的纹理上传被摊到多帧，不再挤在同一记调用里（旧写法一记 `feed` 就把所有平面全绑完）。
+     * ⛔ 不进 `onBeforeRender` 自驱；持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次只是「补排漏网的平面」，
+     * 而整层重建（`setImagePlanes`）末尾自己起排 ⇒ 只调 `importData(整串)` 的宿主不必自己驱动也会长出来。
+     * 还没下载完/缺格的那一格绑 null ⇒ 片元那一格整格 discard，不落像素（用户 10-26 连收两条：先「不要默认图」，
+     * 再「不是显示灰色, 而是直接 discard 丢弃」）。
+     */
+    feedImagePlaneTiles(): void;
+    /** 一颗平面排一帧的绑定工作：先把它那 4 条地址**一次性全部**交给下载器，再把「写材质」排进全局队列。 */
+    private _queueImagePlaneBind;
+    /** 队列里的一格：只绑**这一颗**平面里已就绪的那几格；还有在途的就重新排队，⛔ 不在这里等、也⛔ 不顺手把别的平面一起做完。 */
+    private _bindImagePlaneStep;
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName?: string): MktMeshData;
     /** 导入数据：重建墙体几何与纹理列表，并激活第一个纹理
-     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址 */
-    importData(data: MktMeshData, projName?: string): void;
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、几何、材质 */
+     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址
+     *  @param onModelLoad 每只 GLB 落地时回调一次（可选）——按需渲染的宿主（编辑器）拿它标脏；每帧真画的预览不传 */
+    importData(data: MktMeshData, projName?: string, onModelLoad?: () => void): void;
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
     dispose(): this;
 }

package/MktMesh/MktMesh.js

@@ -16,14 +16,14 @@
  *     `panoSlotRoster.ts`；皇上旨 2026-10-03 起预览/发布与编辑器共用同一份算法 ⇒ 两边装同一批全景）。
  *     ⭐ 皇上旨 2026-10-07 第二十一道旨：锚点 = 外部控制器的中心点（`setRosterCenter` 注入），没注入才回落相机位置；
  *     中心变化或名册里有空格被补上人时加载新瓦片 → 设置 shader 的 8 个全景槽 panorama + textureMatrix；
- *  4. exportData / importData 支持导入导出（墙点位 + 纹理数组）。
+ *  4. exportData / importData 支持导入导出（墙点位 + 纹理数组 + ⭐ 10-26 旨起的平面图 / 模型两层）。
  *  5. ⚠️ 铁律：激活纹理（墙面上正在绘制的全景）的旋转/位置变化，必须立即同步到
  *     shader 的 textureMatrix uniform（见 setTexture），否则平面纹理不跟着全景球转。
  *
  * 说明：所有实例共享同一份 material（单一 panorama uniform），
  * 同一时刻只激活名册 0 号槽（中心）那一个纹理（全局共享单激活方案）。
  */
-import { BufferGeometry, BackSide, Float32BufferAttribute, Matrix4, Mesh, Shape, ShapeGeometry, SRGBColorSpace, Vector3, } from "three";
+import { BufferGeometry, BackSide, 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";
@@ -45,6 +45,12 @@ import { subdivideCapTriangles, WALL_CAP_MAX_EDGE_M } from "./wallCapTessellate"
 // ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」：
 //    导出时剥域名（`exportData`）、导入时补回来（`importData`）——**各只有这一处**，⛔ 不许在别处另剥/另补。
 import { stripAssetHost, absAssetUrl } from "./assetUrl";
+// ⭐ 皇上旨 2026-10-26「按这个方案，把图片平面和模型一起搬进库里」：这两层（含每帧喂瓦片那条编排）
+//    原先各住在本站两个渲染器里一份 ⇒ 下游直接用包里的 `MktMesh` 时，存档里的 `images`/`models` 两键没人读。
+//    入库之后它们挂在 `MktMesh` **自己的子树**下，与墙同一棵变换 ⇒ 预览那三根 transform 滑杆搬得动整份展品。
+import { ImagePlane } from "./imagePlane";
+import { ModelSlot } from "./modelSlot";
+import { ImagePlaneTileLoader } from "./imageTileLoader";
 export default class MktMesh extends Mesh {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
     textures = [];
@@ -172,6 +178,32 @@ export default class MktMesh extends Mesh {
     }
     // 复用临时对象（避免每帧 new，降低 GC 压力）
     _tmpV3 = new Vector3();
+    /**
+     * 图片平面层（⭐ 10-26 旨入库）：对象挂在**本 MktMesh 的子树**里，⛔ 不是场景根
+     * ⇒ 移动/旋转/缩放这个展品时，墙 + 全景 + 平面图 + 模型一起走。
+     */
+    imagePlanes = [];
+    /** 模型槽层（同一棵子树，口径同上） */
+    models = [];
+    /**
+     * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
+     * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不会再空一格；只随本对象 `dispose()` 释放。
+     */
+    _imgTileLoader = new ImagePlaneTileLoader();
+    /**
+     * 逐帧绑定用的两张账（2026-10-26 定的方案：地址一次性全部丢给下载，绑材质改成「一帧一颗平面」）。
+     * 全局 rAF 每拍只跑一项 `addWork`，而 `addWork` 按闭包引用判重 ⇒ 每次现造的新闭包它判不出来，
+     * ⛔ 去重闸门必须像全景上传那张 `_uploadQueued` 一样自备。
+     */
+    _imgBindQueued = new Set();
+    /** 平面 → 「它 4 条地址全部落定（就绪或失败）时的那串地址」⇒ 地址不换就不再重排；上传换图会改这串 ⇒ 自动重排 */
+    _imgBindDone = new Map();
+    /**
+     * 模型槽「GLB 已取回、等这一帧把它挂进父元素」的在册表 —— 与上面图片绑定同一手法（用户 10-26 需求：
+     * 一次性全部拿去加载，用 `threeUtils.addWork` 逐帧加到场景里）。整层十几个槽同时到货时，
+     * 一帧只有一颗进 `_contentRoot`（进图那一拍要重算包围盒 + 排布 + 首次把几何送上 GPU）。
+     */
+    _modelMountQueued = new Set();
     constructor(opts = {}) {
         // 发布/预览态墙：**固定**用「全景序号直取」着色器（皇上旨 2026-09-29：mktmesh 就只有按照 attribute
         // 配置来显示全景这一种固定的 shader——每帧由 feedFaceMapping 按 panoFaceMapping 把被引用的全景
@@ -1008,6 +1040,168 @@ export default class MktMesh extends Mesh {
     setProjectName(name) {
         this.projectName = typeof name === "string" ? name : "";
     }
+    // ───────────── 平面图 / 模型两层（⭐ 皇上旨 2026-10-26「把图片平面和模型一起搬进库里」） ─────────────
+    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 + 起排它自己的逐帧绑定 */
+    addImagePlane(ip) {
+        this.imagePlanes.push(ip);
+        this.add(ip);
+        this._queueImagePlaneBind(ip);
+        return ip;
+    }
+    /** 摘掉一颗并释放它自己的几何/材质；那 4 张瓦片纹理归 `_imgTileLoader` 管 ⇒ ⛔ 不在这里 dispose */
+    removeImagePlane(ip) {
+        const i = this.imagePlanes.indexOf(ip);
+        if (i >= 0)
+            this.imagePlanes.splice(i, 1);
+        this._imgBindQueued.delete(ip);
+        this._imgBindDone.delete(ip);
+        this.remove(ip);
+        ip.dispose();
+    }
+    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用） */
+    addModel(ms) {
+        this.models.push(ms);
+        this.add(ms);
+        return ms;
+    }
+    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾；排在后头的挂载帧靠「不在册」早退） */
+    removeModel(ms) {
+        const i = this.models.indexOf(ms);
+        if (i >= 0)
+            this.models.splice(i, 1);
+        this._modelMountQueued.delete(ms);
+        this.remove(ms);
+        ms.dispose();
+    }
+    /**
+     * 整层重建图片平面（`importData` 与预览那一路）。
+     * ⚠️ 进来的地址必须是**已补回域名**的绝对形态：补域名只有 `importData` 那一处（与 `textures` 同一把 `assetUrl` 尺），
+     *   ⛔ 本方法里不许再补一遍，也⛔ 不许在调用方各自补。
+     */
+    setImagePlanes(datas) {
+        this._imgBindQueued.clear();
+        this._imgBindDone.clear();
+        for (const ip of this.imagePlanes) {
+            this.remove(ip);
+            ip.dispose();
+        }
+        this.imagePlanes = [];
+        for (const d of datas) {
+            const ip = new ImagePlane(d.name);
+            ip.applyData(d);
+            this.imagePlanes.push(ip);
+            this.add(ip);
+        }
+        // 整层重建完立刻起排：地址一次性全交给下载、绑材质逐帧一记 ⇒ 宿主不驱动这一层也长得出来
+        this.feedImagePlaneTiles();
+    }
+    /**
+     * 整层重建模型槽（`importData` 与预览那一路），地址口径的要求同 `setImagePlanes`。
+     * ⚠️ GLB 逐只**异步取、不 await**（十几只串一条队会把载入卡死），每只落地那一刻各回调一次 `onEachLoad`：
+     *   预览每帧真画 ⇒ 不传；编辑器是按需渲染 ⇒ 传一个「标脏」的钩子，否则模型挂上来屏幕不动。
+     * 2026-10-26 决定：取回与「挂进父元素」分两拍 —— 地址一次性全交给下载（网络 + 解析不占渲染帧），
+     *   真正进场景图那一步交给 `threeUtils.addWork` ⇒ 全局 rAF 每拍只跑一项 = **一帧只挂一颗槽**
+     *   （挂载那一拍要重算包围盒 + 排布 + 首次把整棵子树的几何送上 GPU，十几颗挤在同一帧就是他要拆掉的那一卡）。
+     */
+    setModels(datas, onEachLoad) {
+        this._modelMountQueued.clear();
+        for (const ms of this.models) {
+            this.remove(ms);
+            ms.dispose();
+        }
+        this.models = [];
+        for (const d of datas) {
+            const ms = new ModelSlot(d.name);
+            ms.applyData(d);
+            this.models.push(ms);
+            this.add(ms); // 槽本体（占位小立方体）当场进图 ⇒ GLB 在路上时这一槽不凭空消失
+            if (d.url)
+                void ms.loadModel(d.url).then(() => this._queueModelMount(ms, onEachLoad));
+        }
+    }
+    /** 把「备好待挂」的那一槽交给全局队列；⛔ 去重闸门自备（`addWork` 按闭包引用判重，新闭包它判不出来） */
+    _queueModelMount(ms, onEachLoad) {
+        if (this._modelMountQueued.has(ms))
+            return;
+        this._modelMountQueued.add(ms);
+        threeUtils.addWork(() => { });
+        threeUtils.addWork(() => this._mountModelStep(ms, onEachLoad));
+    }
+    /** 全局队列里的那一帧：只挂这一槽，挂好才回调（`onEachLoad` = 按需渲染宿主的标脏钩子） */
+    _mountModelStep(ms, onEachLoad) {
+        this._modelMountQueued.delete(ms);
+        // 槽已退场（换项目 / 删除）：待挂那棵由 `ModelSlot.dispose` → `_detachModel` 当场释放，这里不挂
+        if (!this.models.includes(ms))
+            return;
+        if (ms.mountStaged() && onEachLoad)
+            onEachLoad();
+    }
+    /**
+     * 把各颗平面那 4 张瓦片的纹理绑进材质（10-22 晚定的口径：不走拼合器 RT）。
+     * 2026-10-26 决定改成**逐帧**：一次把整层地址全丢给下载器（下载/解码在网络与工作线程侧，不占这一帧），
+     * 真正写 uniform 的那一步交给 `threeUtils.addWork` —— 全局 rAF 每拍只跑一项 ⇒ 一帧只绑一颗平面，
+     * 一整层平面的纹理上传被摊到多帧，不再挤在同一记调用里（旧写法一记 `feed` 就把所有平面全绑完）。
+     * ⛔ 不进 `onBeforeRender` 自驱；持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次只是「补排漏网的平面」，
+     * 而整层重建（`setImagePlanes`）末尾自己起排 ⇒ 只调 `importData(整串)` 的宿主不必自己驱动也会长出来。
+     * 还没下载完/缺格的那一格绑 null ⇒ 片元那一格整格 discard，不落像素（用户 10-26 连收两条：先「不要默认图」，
+     * 再「不是显示灰色, 而是直接 discard 丢弃」）。
+     */
+    feedImagePlaneTiles() {
+        for (const ip of this.imagePlanes)
+            this._queueImagePlaneBind(ip);
+    }
+    /** 一颗平面排一帧的绑定工作：先把它那 4 条地址**一次性全部**交给下载器，再把「写材质」排进全局队列。 */
+    _queueImagePlaneBind(ip) {
+        const tiles = ip.tiles;
+        const sig = (tiles ?? []).join("|");
+        // 两道闸：已排在队里 = 不重复排；这串地址已经落定过 = 不再动它（换图会改这串 ⇒ 自然会重排）
+        if (this._imgBindQueued.has(ip) || this._imgBindDone.get(ip) === sig)
+            return;
+        const zero = new Vector4(0, 0, 1, 1);
+        // ⛔ 旧存档 16 条地址（> 满批 4）直接不收 ⇒ 整张不落像素（四格全 discard），按 10-20 口径重传即可；空 tiles 同样
+        if (!tiles || tiles.length !== 4) {
+            ip.setTileTextures([null, null, null, null], [zero, zero.clone(), zero.clone(), zero.clone()]);
+            this._imgBindDone.set(ip, sig);
+            return;
+        }
+        for (const url of tiles)
+            this._imgTileLoader.preload(url); // ① 一次性全部拿去加载
+        this._imgBindQueued.add(ip);
+        threeUtils.addWork(() => { }); // 占一格（什么都不干），把下面那一项推到下一个 tick —— 与全景上传同一手法
+        threeUtils.addWork(() => this._bindImagePlaneStep(ip, sig));
+    }
+    /** 队列里的一格：只绑**这一颗**平面里已就绪的那几格；还有在途的就重新排队，⛔ 不在这里等、也⛔ 不顺手把别的平面一起做完。 */
+    _bindImagePlaneStep(ip, sig) {
+        this._imgBindQueued.delete(ip);
+        if (!this.imagePlanes.includes(ip))
+            return; // 已摘掉（删平面 / 切项目整层重建）⇒ 这一格什么都不做
+        const tiles = ip.tiles;
+        if ((tiles ?? []).join("|") !== sig)
+            return; // 地址中途换了 ⇒ 下一记 feed 按新拼串重排
+        const zero = new Vector4(0, 0, 1, 1);
+        const texs = [null, null, null, null];
+        const insets = [zero.clone(), zero.clone(), zero.clone(), zero.clone()];
+        let pending = false;
+        for (let i = 0; i < 4; i++) {
+            const url = tiles[i];
+            if (!url)
+                continue;
+            const e = this._imgTileLoader.get(url);
+            if (e && e.tex) {
+                texs[i] = e.tex;
+                insets[i] = this._imgTileLoader.inset(e, i);
+            }
+            else if (this._imgTileLoader.isPending(url)) {
+                pending = true; // 还在下载/解码 ⇒ 这一格先绑已到的，剩下的下一拍再看
+            }
+        }
+        ip.setTileTextures(texs, insets);
+        if (pending) {
+            this._queueImagePlaneBind(ip);
+            return;
+        }
+        this._imgBindDone.set(ip, sig); // 全部落定（含下载失败那格：它留 null，那一格就永久 discard）
+    }
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName) {
@@ -1030,11 +1224,29 @@ export default class MktMesh extends Mesh {
                 tiles: (t.tiles && t.tiles.length ? t.tiles.map((u) => stripAssetHost(u, pn)) : []),
                 matrix: t.matrix.toArray(),
             })),
+            // ⭐ 10-26 旨入库：这两层的地址与 `textures` 共用上面那一条剥域名口径（⛔ 不是另起一把尺），
+            //   其余字段（位置/旋转/宽高/瓦片数/落点面/原始包围盒）由各自的 `toData()` 逐字存。
+            images: this.imagePlanes.map((ip) => {
+                const d = ip.toData();
+                return {
+                    ...d,
+                    url: d.url ? stripAssetHost(d.url, pn) : "",
+                    tiles: d.tiles.length ? d.tiles.map((u) => stripAssetHost(u, pn)) : [],
+                };
+            }),
+            models: this.models.map((ms) => {
+                const d = ms.toData();
+                return { ...d, url: d.url ? stripAssetHost(d.url, pn) : "" };
+            }),
         };
     }
     /** 导入数据：重建墙体几何与纹理列表，并激活第一个纹理
-     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址 */
-    importData(data, projName) {
+     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址
+     *  @param onModelLoad 每只 GLB 落地时回调一次（可选）——按需渲染的宿主（编辑器）拿它标脏；每帧真画的预览不传 */
+    importData(data, projName, onModelLoad) {
+        // ⭐ 10-08 旨的「补回域名」那颗项目名，10-26 旨之后全景/平面图/模型**三层共用同一个**（原来在 textures 的
+        //   map 里就地取，下面那两层也要用 ⇒ 提到方法开头，⛔ 不是第二处口径）。
+        const pn = typeof projName === "string" && projName ? projName : this.projectName;
         this.setWallPoints(data.wallPoints ?? [], {
             closed: data.wallClosed,
             height: data.wallHeight,
@@ -1049,7 +1261,6 @@ export default class MktMesh extends Mesh {
             //     （`/three-base_upload/…`）不必重存也能正常加载，不会被拼成 `https://host/https://host/…`
             //   · 19:53 旨后还要把 `{项目名}/x_0.jpg` **还原**成真身 OSS 地址（顶掉的上传目录要补回来），
             //     否则 json 里的地址指不回原图（图片裂）。`pn` 取入参、回落 `setProjectName` 注入的那个。
-            const pn = typeof projName === "string" && projName ? projName : this.projectName;
             const urlAbs = absAssetUrl(t.url, pn);
             return {
                 url: urlAbs,
@@ -1073,9 +1284,18 @@ export default class MktMesh extends Mesh {
                 this.panoFaceMapping[f] = imported[f];
             this.rebuildPanoIndexAttribute();
         }
+        // ⭐ 10-26 旨「把图片平面和模型一起搬进库里」的另一半：这两层也从**同一份 JSON** 里读，
+        //   地址在这一处补回域名（与上面 textures 同一条尺）⇒ 下游只调 `importData(整串)` 就全画出来。
+        //   旧存档没有这两个键 ⇒ 空数组 = 整层清空，与「墙 + 全景」那套逐字同口径。
+        this.setImagePlanes((data.images ?? []).map((d) => ({
+            ...d,
+            url: d.url ? absAssetUrl(d.url, pn) : "",
+            tiles: (d.tiles ?? []).map((u) => absAssetUrl(u, pn)),
+        })));
+        this.setModels((data.models ?? []).map((d) => ({ ...d, url: d.url ? absAssetUrl(d.url, pn) : "" })), onModelLoad);
     }
     // ───────────────────────── 释放 ─────────────────────────
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、几何、材质 */
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
     dispose() {
         // ⚠️ rt 虚拟键从不进 `_texCache`（拼合槽纹理由 `_stitcher` 自己持有并释放），这里清的都是本类下载的 Texture。
         // ⭐ 甲（2026-10-05）：`releasePanoTexture` 除 `dispose()` 外还要 `ImageBitmap.close()` —— 位图的原生内存
@@ -1086,6 +1306,22 @@ export default class MktMesh extends Mesh {
         this._texUploaded = new WeakSet(); // WeakSet 无 clear ⇒ 整只换掉
         this._uploadQueued.clear(); // 排队项即便回调仍触发，也会因 `!this._uploadQueued.delete(tex)` 早退
         this._ossSizeDepKeys.clear();
+        // ⭐ 10-26 旨入库的两层：子对象逐个 dispose，平面那 4 张瓦片的缓存**只在这里**整批清
+        //   （与上面 `_texCache` 同一条旨 ⇒ 切工程不重建这一份、也就不会再空出一格）。
+        for (const ip of this.imagePlanes) {
+            this.remove(ip);
+            ip.dispose();
+        }
+        this.imagePlanes = [];
+        for (const ms of this.models) {
+            this.remove(ms);
+            ms.dispose();
+        }
+        this.models = [];
+        this._imgTileLoader.clear();
+        this._imgBindQueued.clear();
+        this._imgBindDone.clear();
+        this._modelMountQueued.clear();
         this._stitcher.dispose();
         this._glRenderer = null;
         if (this._placeholder)