three-base 2.0.137 → 2.0.142

package/MktMesh/MktMesh.ts

@@ -0,0 +1,1075 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2026-08-25
+ * @Description: MktMesh —— 墨卡托模型（普通 Mesh + 墨卡托投影全景 + 由点位挤出生成的墙体）。
+ *
+ * 定位：继承 THREE.Mesh（普通网格，不再用 InstancedMesh）。
+ * 墙面几何由一组「地面折线点位」（wallPoints，XZ 平面）通过挤出生成：
+ *   - 墙体侧面：复用 three-base 的 ExtrudeMesh（shapePath = [[0,0],[0,墙高]] 沿点位挤出一道幕墙）；
+ *   - 墙体上/下两个多边形封盖：用 three.js 自带的 ShapeGeometry 由点位三角化生成。
+ * 墨卡托投影全景纹理（panorama）实时映射到墙面上：每帧按槽位名册（中心 ± 邻居）决定 shader 那 8 格装哪 8 张。
+ *
+ * 核心特性：
+ *  1. 墙面 = 普通 Mesh 几何（世界坐标），MktMesh 自身保持单位变换；
+ *  2. 纹理列表 textures：每个纹理含 url + 世界矩阵（位置=墨卡托投影中心，旋转=朝向）；
+ *  3. 默认每帧（onBeforeRender）按「离**名册锚点**最近的水平距离（XZ）」算出**槽位名册**（中心 ± 邻居，见
+ *     `panoSlotRoster.ts`；皇上旨 2026-10-03 起预览/发布与编辑器共用同一份算法 ⇒ 两边装同一批全景）。
+ *     ⭐ 皇上旨 2026-10-07 第二十一道旨：锚点 = 外部控制器的中心点（`setRosterCenter` 注入），没注入才回落相机位置；
+ *     中心变化或名册里有空格被补上人时加载新瓦片 → 设置 shader 的 8 个全景槽 panorama + textureMatrix；
+ *  4. exportData / importData 支持导入导出（墙点位 + 纹理数组）。
+ *  5. ⚠️ 铁律：激活纹理（墙面上正在绘制的全景）的旋转/位置变化，必须立即同步到
+ *     shader 的 textureMatrix uniform（见 setTexture），否则平面纹理不跟着全景球转。
+ *
+ * 说明：所有实例共享同一份 material（单一 panorama uniform），
+ * 同一时刻只激活名册 0 号槽（中心）那一个纹理（全局共享单激活方案）。
+ */
+import {
+    BufferAttribute,
+    BufferGeometry,
+    Camera,
+    BackSide,
+    Float32BufferAttribute,
+    Material,
+    Matrix4,
+    Side,
+    Mesh,
+    Shape,
+    ShapeGeometry,
+    ShaderMaterial,
+    SRGBColorSpace,
+    Texture,
+    Vector3,
+} from "three";
+import type { WebGLRenderer } from "three";
+import { createPlaceholderTexture, MKT_PANO_MAX_SLOTS, isPanoTexMode, mktPanoTiledFlag, mktPanoTexUrls, isRtStitchKey, rtStitchKeyParts, RT_STITCH_KEY_PREFIX, RT_STITCH_SLOT_COUNT, type PanoTexMode } from "./mktShader";
+import { createMktFloorMappingShaderMaterial } from "./mktMappingShader";
+// ⭐ 皇上旨 2026-10-06：拼合 = shader 逐格画进 WebGLRenderTarget，**一份实现**（canvas 2D 那一份连同
+//    `?panoStitch=canvas` 开关整条删除）
+import { PanoTileStitcher, type PanoStitcher } from "./panoTileStitcher";
+import { panoSlotRosterStep, PANO_SLOT_SWAP_MARGIN_M } from "./panoSlotRoster";
+// ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：整图/瓦片的下载与解码一律走这里（解码在浏览器工作线程，
+//    不再让上传那一拍的 `texImage2D(<img>)` 替我们在主线程同步解 270MB）。编辑态同一份实现。
+import { loadPanoTexture, releasePanoTexture } from "./panoBitmapTexture";
+// ⭐ 皇上旨 2026-10-03「整套搬进库（彻底同源）」：「一个点槽的左右 2 张拼合槽纹理怎么换绑」只有这一份策略实现，
+//    编辑态 `mktMeshEditRenderer._bindSlotTiles` 与库侧都只「委托一行」+ 注入各自取图口（⛔ 不许有第二份）。
+import { panoSlotBind, panoSlotTileKeys } from "./panoSlotBind";
+import threeUtils from "../threeUtils";
+import ExtrudeMesh from "../ExtrudeMesh";
+import type { MktMeshData, MktTextureInfo, WallPoint, WallSide } from "./types";
+
+// ⭐ 皇上旨 2026-10-07「上下封口的三角面能不能不要那么长 / 三角面再细分一下」：封盖三角化之后
+//    再按**最长边二分**切细（算法本体在 `./wallCapTessellate`，零依赖纯函数 ⇒ 护栏能单独真跑）。
+import { subdivideCapTriangles, WALL_CAP_MAX_EDGE_M } from "./wallCapTessellate";
+// ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」：
+//    导出时剥域名（`exportData`）、导入时补回来（`importData`）——**各只有这一处**，⛔ 不许在别处另剥/另补。
+import { stripAssetHost, absAssetUrl } from "./assetUrl";
+
+export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
+    /** 纹理列表（每个纹理的 url + 世界矩阵） */
+    textures: MktTextureInfo[] = [];
+    /** 当前激活（正在绘制）的纹理索引，-1 表示尚未激活。⭐ 10-03 起该值 = 槽位名册的**中心**（`_slotPanos[0]`），不是「每帧纯最近那张」 */
+    activeIndex: number = -1;
+
+    /** 墙体地面折线点位（XZ 平面，世界坐标） */
+    wallPoints: WallPoint[] = [];
+    /** 墙体高度（沿 +Y 挤出） */
+    wallHeight: number = 3;
+    /** 墙体折线是否闭合（首尾相连成环） */
+    wallClosed: boolean = true;
+    /** 墙体正反面显示（字段保留兼容存档；09-29 晚旨后无论何值材质一律 BackSide，见 _wallSideToThree） */
+    wallSide: WallSide = "double";
+    /** 是否跳过墙体上/下多边形封盖（true = 只留侧面幕墙）。⚠️ 2026-09-26 核实：本库与编辑态**都取默认 false**
+     *  （旧注释写「编辑态 MktDevMesh 设为 true」是错的 —— MktDevMesh 明确保留封盖，与发布态一致，
+     *   见其类头注释）。封盖与侧面**同一份几何、同一份材质** ⇒ 正反面（material.side）天然同步，
+     *   没有「封盖不跟墙体正反面」的第二套口径（这正是皇上 09-26 第①条要查的点）。 */
+    skipWallCaps: boolean = false;
+    /**
+     * ⭐ 皇上旨 2026-10-07「上下封口的三角面能不能不要那么长 / 三角面再细分一下，不要那么大」：
+     *  上/下封盖在耳切三角化之后，再按**最长边二分**切到每条边都 ≤ 本值（米）。粒度越细 ⇒
+     *  封盖上「一个三角面 = 一张全景」的区块越小，序号映射 / 取图在天花板和地面上分得越准
+     *  （原先一个耳切大三角能横跨整个房间 ⇒ 整片天花板只能是同一张全景）。
+     *  ⛔ 0 / 负数 = 不细分（= 10-07 之前的形状）。
+     *  ⚠️ 改这个值会**改变面数** ⇒ 存档里的逐面序号按「块」继承（见 `importData` 那句 warn）。
+     */
+    wallCapMaxEdgeM: number = WALL_CAP_MAX_EDGE_M;
+
+    /**
+     * 全景「序号直接取」映射：每个三角面（faceIndex）→ 被指派的「全景全局序号」（-1=未设）。
+     * 序号直接取由着色器读取 geometry 的 aPanoIndex；与 panoIndices 槽数组配合取对应全景纹理。
+     * 长度 = 几何三角面数，随 rebuildWallGeometry 按位置重算（保留旧映射，见下方注释）。
+     * 该数据随工程存档持久化（MktMeshData.panoFaceMapping），编辑器/预览/发布三端同源。
+     */
+    panoFaceMapping: number[] = [];
+    /**
+     * 全景点坐标数组（每全景 3 个数 = 中心点 xyz，世界坐标）。
+     * ⭐ 2026-09-30 旨：全景点数据是**独立的纯几何数据**，与纹理图片是否加载/解码无关；
+     *    智能序号只认这份，不认 textures。由 setTextures/addTexture/removeTexture/setTexture(矩阵变更) 派生（_syncPanoCenters）。
+     *    本数组是「每全景 xyz」的**源**；序号映射最终烘焙成几何属性 `aPanoCenter`（每三角面9数，与 position 对齐），见 _syncPanoCenterAttr。
+     * ⚠️⚠️ 2026-10-01 血案修复：本字段改为**读取时实时派生**（getter），不再依赖「谁记得调 _syncPanoCenters」。
+     *    起因：`MktDevMesh.setTextures` 覆写了基类（编辑态不激活单全景），直接 `this.textures = textures` 而**不调
+     *    super** ⇒ 派生点整条被绕过，`panoCenters` 恒为空 ⇒ 映射模式下点「智能序号」在 centerCount===0 处静默 return，
+     *    墙上全空且无任何提示。派生点式缓存在有子类覆写时就必然漏，**改为实时派生才是根治**（读一次 O(全景数)，
+     *    调用方只有智能序号与 _syncPanoCenterAttr，都不是每帧路径）。
+     */
+    get panoCenters(): number[] {
+        this._syncPanoCenters();
+        return this._panoCentersCache;
+    }
+    /** 派生结果的落点（勿直接读写，统一走 panoCenters getter / _syncPanoCenters） */
+    private _panoCentersCache: number[] = [];
+    /** 旧几何的「面中心 XZ→{y, 序号}」索引，用于改墙/改高后按位置保留全景序号映射（皇上旨 2026-09-28 决策②）。 */
+    private _panoXZMap: Map<string, { y: number; idx: number }[]> = new Map();
+
+    /**
+     * ⭐ 槽位名册（皇上旨 2026-10-03「库侧也一并改成中心 ± 邻居」）：每帧由 `updateTexture` 走
+     *    `panoSlotRosterStep` 算出，**0 号槽 = 中心**（⭐ 10-07 第二十一道旨：离**控制器中心点** XZ 最近那张，
+     *    带 `PANO_SLOT_SWAP_MARGIN_M` 死区；锚点见 `_rosterCenter`），
+     *    1..7 = 中心在全景列表里的序号一层层往外扩的邻居（⭐ 10-07 旨「尽可能填满 8 个全景位置」⇒ 越界的序号不占格、
+     *    继续往有货那侧扩 ⇒ 填几格 = min(项目全景总数, 8)，只有全景总数不够时才有空格）。
+     *    ⇒ 与编辑态 `mktMeshEditRenderer._slotPanos` **同一份算法、同一个常数**（预览看到的那几张 = 编辑器里的那几张，均为 8 个全景槽）。
+     *    存**对象引用**不存下标（删点会让下标整体前移，引用不会认错人）。
+     *    消费方 = `feedFaceMapping`（墙 8 格）；⭐ 10-03 旨② 后预览立方体与墙**共用同一份材质**，
+     *    立方体几何无 `aPanoIndex` ⇒ `vPanoIndex ≡ 0` ⇒ 它显示的就是 0 号槽那张（墙与立方体天然同源，
+     *    原来那条「把中心那几张抄给立方体单全景材质」的 `currentTiles` 旁路已整条删除）。
+     */
+    private _slotPanos: (MktTextureInfo | undefined)[] = [];
+    /**
+     * ⭐ 名册那把尺子的**锚点**（皇上旨 2026-10-07 第二十一道旨：「判断使用哪些全景球的判断条件，
+     *    从距离相机的距离改成判断距离控制器的中心点的距离」）。这里存外部控制器的中心点
+     *    （轨道控制器 = `controls.target`，也就是画面正中央那个注视点），由消费方经 `setRosterCenter()` 注入。
+     *  · 只读 XZ ⇒ 与名册历代那把「水平距离」尺同一把（09-28 旨），高度差不进尺子。
+     *  · `null` ⇒ 回落 `camera.position`（老口径）：发布页那一路没有控制器引用，不注入就一切照旧。
+     *  · 存的是**引用**（OrbitControls 原地改它那个 Vector3）⇒ 消费方设一次即可，不必每帧重设。
+     *  · ⚠️ 全景点矩阵本就是**世界矩阵**，锚点也取世界坐标；⛔ 别再乘一遍 `matrixWorld`（同 `updateTexture` 里那句提醒）。
+     */
+    private _rosterCenter: Vector3 | null = null;
+    /**
+     * ⭐ 皇上旨 2026-10-03「整套搬进库（彻底同源）」：库侧不再自养「按全景序号取整槽、齐活才写」那一路，
+     *    改成与编辑态**同一份换绑策略**（`./panoSlotBind`）+ 同一口径的三张表：
+     *    地址→纹理缓存、已上传 GPU 集合、待上传排队集合。治的两个病：
+     *    ① 换景点闪一帧灰（库侧原先没有「未就绪整槽沿用上一批」这层兜底）；
+     *    ② 图与投影矩阵来自**不同批**（原先矩阵无条件 copy，纹理却可能还在路上）。
+     *    地址 → 已解码纹理；值为 `null` = 该地址正在加载（占位 ⇒ 同一地址不会被问两次就下两遍）。
+     *    ⚠️ 皇上旨 2026-10-02：运行中**不淘汰**任何一张，只在 `dispose()` 整批释放。
+     */
+    private _texCache: Map<string, Texture | null> = new Map();
+    /** 已上传 GPU 的纹理：没进这张表的**不许**绑进 shader（首绑现场 `texImage2D` 就是那一下卡顿，皇上旨 09-29「两个大头别在同一帧」） */
+    private _texUploaded: WeakSet<Texture> = new WeakSet();
+    /** 已排进全局队列、等着「只干上传那一句」的纹理（`addWork` 按闭包判重判不出来 ⇒ 必须自备集合） */
+    private _uploadQueued: Set<Texture> = new Set();
+    /** 加载地址真的拼了 ossSize 缩放参数的条目 ⇒ 换档只重载这些（真瓦片一律原图，不进此集） */
+    private _ossSizeDepKeys: Set<string> = new Set();
+    /** 渲染器：由 `onBeforeRender` 每帧捕获，预上传走它的 `initTexture`；没捕获到就退回 three 的自绑路径（不报错） */
+    private _glRenderer: WebGLRenderer | null = null;
+    /** ⭐ 32 瓦片（横 8 × 竖 4 切片）离屏拼合器：左右 2 槽纹理由它逐格拼出（每帧一张新纹理进 GPU + 已进 GPU 的逐格画）。
+     *  编辑器渲染器经 `panoStitcher` 复用同一实例（同一份槽纹理缓存，⛔ 不另建第二份显存）。
+     *  皇上旨 2026-10-06「不用 canvas 2D 的 drawImage 拼合, 用一个 shader 一个一个渲染到 RT 上面去」
+     *  +「canvas 是什么意思, 按照我的想法, 不应该有 canvas 才对啊」⇒ **只此一份实现**：旧的 canvas 2D
+     *  那一份连同 `?panoStitch=canvas` 对照开关整条删除。⚠️ RT 是 GL 上下文私有资源 ⇒ 见拼合器 `_switchRenderer`。 */
+    private _stitcher: PanoStitcher = new PanoTileStitcher();
+    /** 拼合器只读访问（编辑器渲染器共用；⛔ 不另建第二实例） */
+    get panoStitcher(): PanoStitcher {
+        return this._stitcher;
+    }
+    /** 融合材质未绑纹理时的占位（避免空纹理采样报错；深灰兜底由着色器 uFaceMissingColor 负责） */
+    protected _placeholder!: Texture;
+    // 纹理下载/解码走 `loadPanoTexture`（甲，2026-10-05），结果按**地址**进 `_texCache`，运行中不淘汰、只随 `dispose()` 释放。
+    // ⛔ 别换回 `TextureLoader`：它只等 `img.onload`（不解码），解码会被拽到上传那一拍的 `texImage2D(<img>)` 上同步做完。
+    /** 纹理 OSS 缩放尺寸（1024 / 2048 / 空=原图），由外部 setOssSize 注入；默认 1024 保持旧行为。
+     *  编辑器渲染器与预览渲染器各自把 store.ossSize 推下来，使全景球/预览按该尺寸加载。 */
+    private _ossSize: "1024" | "2048" | "" = "1024";
+    /** 全景纹理形态：tiled=左右 2 槽各装一张**拼合槽纹理**（该点 32 片 横 8 × 竖 4 → 2 张 4096×4096，10-06 晚旨）
+     *  / whole=2 槽同为一张完整等距柱状原图。
+     *  由外部 setPanoTexMode 注入（与 _ossSize 同一套注入路径），默认 tiled 保持改造前行为。 */
+    private _panoTexMode: PanoTexMode = "tiled";
+    /** 当前全景纹理形态（只读）。消费方（预览立方体等自持材质的路径）据此算 `mktPanoTiledFlag`，
+     *  必须与基类喂纹理处用同一个值，否则标记与地址不同源 ⇒ 整图被按 1/2 横向铺满球面（10-06 晚起纵向不分块，四槽时代是 1/4）。 */
+    get panoTexMode(): PanoTexMode {
+        return this._panoTexMode;
+    }
+
+    // 复用临时对象（避免每帧 new，降低 GC 压力）
+    private _tmpV3: Vector3 = new Vector3();
+
+    constructor(opts: { wallHeight?: number; wallClosed?: boolean } = {}) {
+        // 发布/预览态墙：**固定**用「全景序号直取」着色器（皇上旨 2026-09-29：mktmesh 就只有按照 attribute
+        // 配置来显示全景这一种固定的 shader——每帧由 feedFaceMapping 按 panoFaceMapping 把被引用的全景
+        // 喂进 8 个全景槽，按三角面 aPanoIndex 取对应纹理；原 blend+uFaceMappingMode 运行时分支已拆出独立 shader）。
+        const material = createMktFloorMappingShaderMaterial({ maxPano: MKT_PANO_MAX_SLOTS });
+        const placeholder = createPlaceholderTexture();
+        super(new BufferGeometry(), material);
+        this._placeholder = placeholder;
+        // ⭐ 2026-09-26 彻查「正反面」：材质 face 朝向**只有一个写入口** = setWallSide()（内部走 _wallSideToThree）。
+        //    这里过去写死 `material.side = DoubleSide`，与那条映射并列出第二份「谁决定正面」的写法；
+        //    改成构造末尾用自身字段回灌：值仍是默认 "double" ⇒ **当时**画面逐字不变，但侧面上不再有两处口径。
+        //    ⚠️ 那句「画面逐字不变」只在那一天成立：09-29 晚旨之后 `_wallSideToThree` 三档全落 BackSide ⇒
+        //    这一行回灌落地的**就是**反面（不是双面）。皇上旨 2026-10-07「mktmesh 的 shader 和 mktdevmesh 的映射 shader 保持一致」
+        //    之后预览也删了自己那句手写 DoubleSide 覆盖 ⇒ 「朝向只有一个写入口」这条对库侧/编辑态/预览三处同时成立。
+        //    （必须在 super() 之后调用 —— this.wallSide 是类字段，早于 super() 读不到。）
+        this.setWallSide(this.wallSide);
+        // 保险：禁止视锥剔除，避免 boundingSphere 边界问题导致 GPU 跳过绘制
+        this.frustumCulled = false;
+        if (opts.wallHeight !== undefined) this.wallHeight = opts.wallHeight;
+        if (opts.wallClosed !== undefined) this.wallClosed = opts.wallClosed;
+        // 每帧渲染前：① 同步「投影空间逆矩阵」（让墙的投影与 MktMesh 整体变换解耦）；
+        // ② 按**名册锚点**（⭐ 10-07 第二十一道旨：控制器中心点，未注入时才是相机位置）的 XZ 距离算**槽位名册**（中心 ± 邻居），中心换人时更新 `activeIndex`；
+        // ③ 发布/预览态墙按全景序号直接取喂食，8 格 = 名册那 8 张（皇上旨 2026-09-28 决策③ + 10-03「库侧同口径」）
+        this.onBeforeRender = (renderer, _scene, camera) => {
+            this._glRenderer = renderer;
+            this.syncProjInvMatrix();
+            this.updateTexture(camera as Camera);
+            this.feedFaceMapping();
+        };
+    }
+
+    // ───────────────────────── 墙体几何（由点位挤出） ─────────────────────────
+
+    /**
+     * 设置墙体地面折线点位，并重建墙体几何。
+     * @param points 地面折线点位（XZ 平面，世界坐标），至少 2 个点才能生成墙体
+     * @param opts.closed 是否闭合（首尾相连成环），默认沿用当前 wallClosed
+     * @param opts.height 墙高（沿 +Y 挤出），默认沿用当前 wallHeight
+     */
+    setWallPoints(points: WallPoint[], opts: { closed?: boolean; height?: number } = {}): void {
+        // ⚠️ 必须保留每个点的 y（离地高度），否则「墙点 Y 高度可调」会丢值
+        this.wallPoints = points.map((p) => ({ x: p.x, y: p.y ?? 0, z: p.z }));
+        if (opts.closed !== undefined) this.wallClosed = opts.closed;
+        if (opts.height !== undefined) this.wallHeight = opts.height;
+        this.rebuildWallGeometry();
+    }
+
+    /** 读取墙点位（副本，含 y，调用方可自行修改再回设） */
+    getWallPoints(): WallPoint[] {
+        return this.wallPoints.map((p) => ({ x: p.x, y: p.y, z: p.z }));
+    }
+
+    /**
+     * 墙正面/反面枚举 → three.js Side 常量。
+     * ⭐ 2026-09-29 晚旨「shader 设反面显示、不要双面」：三档**全部**落到 BackSide（对应历史上
+     *   的 wallSide="back" 档 —— 零厚度幕墙只画**朝房间内的那一面**，从房间外看穿过去、看不到内部全景）。
+     * API 形参与 wallSide 字段保留（存档/调用方兼容）。⚠️ 地板/立方体**不由这里控制**：编辑态地板恒走「仅显示选中」工厂（DoubleSide）；
+     *   立方体在 mapping 档与墙**共用同一份材质实例**（皇上旨 2026-10-02），⇒ 朝向跟着墙 = BackSide，
+     *   另两档（blend / selected）另建一份 mapping 并显式拉回 DoubleSide（见渲染器 `_applyDisplayMode`；预览自 10-07 旨起与编辑态同口径）。
+     * ⚠️ 若实测房间内反而看不到墙（几何法线朝向与预期相反），把这里的 BackSide 换成 FrontSide 即可（一行）。
+     */
+    private _wallSideToThree(_side: WallSide): Side {
+        return BackSide;
+    }
+
+    /** 设置墙体正反面显示（**材质 side 的唯一写入口**；参数保留兼容，当前无论传什么都渲染**反面**，见 _wallSideToThree） */
+    setWallSide(side: WallSide): void {
+        this.wallSide = side;
+        (this.material as Material).side = this._wallSideToThree(side);
+    }
+
+    /** 由 wallPoints / wallHeight / wallClosed 重建墙体几何：侧面(ExtrudeMesh) + 上下封盖(ShapeGeometry) */
+    private rebuildWallGeometry(): void {
+        const pts = this.wallPoints;
+        const height = this.wallHeight;
+        const positions: number[] = [];
+
+        // ── 全景序号映射：改墙/改高后按位置保留（皇上旨 2026-09-28 决策②）──
+        //    捕获旧几何面中心 + 旧映射（this.geometry 此刻仍是旧几何，尚未 dispose）。
+        //    ⭐ 10-07 封盖细分之后：新面中心**多半不再落在旧面中心那几个 XZ 上**（细分是在三角形内部加了一堆点）
+        //    ⇒ 只认「XZ 键精确相等」的话，封盖那一整片序号会被丢光 ⇒ 这里多留一份**旧三角形的 XZ 顶点**，
+        //    新面中心改用「它落在哪个旧三角形里」来认祖（点在三角形内），认不到才退回精确键那一路。
+        const oldPosAttr = this.geometry.getAttribute("position") as BufferAttribute | undefined;
+        const oldFaceCount = oldPosAttr ? Math.floor(oldPosAttr.count / 3) : 0;
+        const oldCentroids: { x: number; y: number; z: number }[] = new Array(oldFaceCount);
+        const oldTris: { ax: number; az: number; bx: number; bz: number; cx: number; cz: number; y: number; idx: number }[] = [];
+        const oldMapping = this.panoFaceMapping;
+        for (let f = 0; f < oldFaceCount; f++) {
+            const a = 3 * f, b = 3 * f + 1, c = 3 * f + 2;
+            const ax = oldPosAttr!.getX(a), ay = oldPosAttr!.getY(a), az = oldPosAttr!.getZ(a);
+            const bx = oldPosAttr!.getX(b), by = oldPosAttr!.getY(b), bz = oldPosAttr!.getZ(b);
+            const cx = oldPosAttr!.getX(c), cy = oldPosAttr!.getY(c), cz = oldPosAttr!.getZ(c);
+            oldCentroids[f] = { x: (ax + bx + cx) / 3, y: (ay + by + cy) / 3, z: (az + bz + cz) / 3 };
+            oldTris.push({ ax, az, bx, bz, cx, cz, y: (ay + by + cy) / 3, idx: oldMapping[f] ?? -1 });
+        }
+
+        if (pts.length >= 2) {
+            // —— 墙体侧面：复用 ExtrudeMesh，shapePath=[[0,0],[0,height]] 沿地面折线挤出一道幕墙 ——
+            // 路径点的 vector3[1] = p.y，即墙基离地高度；ExtrudeMesh 把整个截面抬到该高度再向上挤出 height，
+            // 故底面落在 p.y、顶面落在 p.y + height（支点位高低错落 / 阶梯墙基）。
+            const paths = pts.map((p, i) => ({
+                vector3: [p.x, p.y, p.z] as [number, number, number],
+                radius: 0,
+                segments: 0,
+                scale: { x: 1, y: 1 },
+                name: `w${i}`,
+            }));
+            const tmp = new ExtrudeMesh(
+                { paths, shapePath: [[0, 0], [0, height]], closed: this.wallClosed },
+                undefined as unknown as Material
+            );
+            const sidePos = tmp.geometry.getAttribute("position");
+            for (let i = 0; i < sidePos.count; i++) {
+                positions.push(sidePos.getX(i), sidePos.getY(i), sidePos.getZ(i));
+            }
+            tmp.geometry.dispose();
+
+            // —— 墙体上/下两个多边形封盖：用 three.js 自带的 ShapeGeometry 由点位三角化 ——
+            // ⚠️ 2026-09-26 更正：此前这句注释写的是「编辑态只要幕墙、不要封顶」——**与事实相反**，勿再照它理解。
+            //    `skipWallCaps` 在库侧与编辑态 `MktDevMesh` 都保持默认 false —— 封盖与侧面**推进同一份 geometry、
+            //    共用同一份 material**（见下方 positions.push 与 `this.geometry = geo`），故「墙体正反面」参数一改，
+            //    封盖与侧面同帧跟着翻，不存在第二处需要同步的 side。本开关只留给「只要幕墙不要封顶」的外部调用方，
+            //    本项目内**无人置 true**。
+            if (!this.skipWallCaps) {
+                // Shape 用 2D 坐标（x, z）；rotateX(90°) 把 (x,y,0)→(x,0,y)，故 shape 的 (px,pz) 落回世界 (px,0,pz)，与侧面点位一致。
+                // 每个封盖顶点按 (x,z) 反查对应点位的 y：下封盖 y=p.y，上封盖 y=p.y+height，使封盖随墙基高低错落。
+                const shape = new Shape();
+                pts.forEach((p, i) => {
+                    if (i === 0) shape.moveTo(p.x, p.z);
+                    else shape.lineTo(p.x, p.z);
+                });
+                if (this.wallClosed) shape.closePath();
+                const cap = new ShapeGeometry(shape);
+                cap.rotateX(Math.PI / 2);
+                const capNI = cap.toNonIndexed();
+                const capPos = capNI.getAttribute("position");
+                // 坐标→Y 映射：**三角化后的顶点都是多边形点的副本**（没有插值点）⇒ 可按 (x,z) 精确落回点位高度。
+                // ⚠️ 细分切出来的**内部点**不在多边形点的位置上 ⇒ 这张表查不到（会打成 0 ⇒ 封盖塌下去），
+                //    它们的 y 由下面的细分函数按两端平均插值（落在原平面上）。
+                const yByXZ = new Map<string, number>();
+                for (const p of pts) yByXZ.set(`${p.x},${p.z}`, p.y);
+                const yOf = (x: number, z: number): number => {
+                    const v = yByXZ.get(`${x},${z}`);
+                    return v === undefined ? 0 : v;
+                };
+                // ⭐ 10-07 旨「封盖三角面不要那么长 / 再细分一下」：先把封盖三角化结果摊成扁平三角形
+                //   （每个顶点带上它那处墙基的 y），再按**最长边二分**切到每条边都不长于 `wallCapMaxEdgeM`
+                //   （0 / 负数 = 不细分）。细分只在封盖平面内加顶点 ⇒ **形状一点不变，只是面变小**。
+                const rawCap: number[] = [];
+                for (let i = 0; i < capPos.count; i++) {
+                    const x = capPos.getX(i);
+                    const z = capPos.getZ(i);
+                    rawCap.push(x, yOf(x, z), z);
+                }
+                const capTris = subdivideCapTriangles(rawCap, this.wallCapMaxEdgeM);
+                // 下封盖（level=0）→ y=p.y；上封盖（level=height）→ y=p.y+height
+                for (let lv = 0; lv <= 1; lv++) {
+                    const base = lv === 0 ? 0 : height;
+                    if (lv === 0) {
+                        // 下封盖：顶点顺序与 shape 一致，法线朝下（指向地面外侧）
+                        for (let i = 0; i < capTris.length; i += 9) {
+                            positions.push(capTris[i], capTris[i + 1] + base, capTris[i + 2]);
+                            positions.push(capTris[i + 3], capTris[i + 4] + base, capTris[i + 5]);
+                            positions.push(capTris[i + 6], capTris[i + 7] + base, capTris[i + 8]);
+                        }
+                    } else {
+                        // 上封盖：每个三角形的**顶点顺序倒过来** ⇒ 绕序翻转 ⇒ 法线由朝下翻为朝上（朝天/朝外，
+                        // 与「盒子封盖朝外」一致；单面（front/back）模式下从外部俯视可见、内部仰视不可见）。
+                        for (let i = 0; i < capTris.length; i += 9) {
+                            positions.push(capTris[i + 6], capTris[i + 7] + base, capTris[i + 8]);
+                            positions.push(capTris[i + 3], capTris[i + 4] + base, capTris[i + 5]);
+                            positions.push(capTris[i], capTris[i + 1] + base, capTris[i + 2]);
+                        }
+                    }
+                }
+                capNI.dispose();
+                cap.dispose();
+            }
+        }
+
+        const geo = new BufferGeometry();
+        geo.setAttribute("position", new Float32BufferAttribute(positions, 3));
+        // ⭐ 必须算法线（皇上旨 2026-09-24「模型面上映射要先判全景点方向与面法线夹角 <90°」）：
+        //    本几何是非索引三角形汤（侧面 + 上下封盖），computeVertexNormals 因此给出**逐面**法线，
+        //    正好就是「面的法线」。缺它着色器读到 (0,0,0) ⇒ 点积恒 0 ⇒ 夹角门永远筛不到候选（会走兜底，不崩但白改）。
+        geo.computeVertexNormals();
+
+        // ── 按位置重算全景序号映射（保留旧指派，决策②）──
+        const faceCount = Math.floor(positions.length / 9);
+        const newMapping: number[] = new Array(faceCount).fill(-1);
+        const rk = (v: number): number => Math.round(v * 1000) / 1000; // 1mm 量化做 XZ 键
+        // 旧 XZ 索引：同一 XZ 可能对应上下两个封盖（y 不同），故一个键挂一个 {y,idx} 列表
+        const oldMap = new Map<string, { y: number; idx: number }[]>();
+        for (let f = 0; f < oldFaceCount; f++) {
+            const c = oldCentroids[f];
+            const key = `${rk(c.x)},${rk(c.z)}`;
+            const arr = oldMap.get(key) ?? [];
+            arr.push({ y: c.y, idx: oldMapping[f] ?? -1 });
+            oldMap.set(key, arr);
+        }
+        // ⭐ 10-07 封盖细分后**新加的一层**：新面中心「落在哪个旧三角形里」就继承那一片的序号。
+        //   只在上面那道精确 XZ 键**没命中**时才走（命中 = 老口径，一个字没改）。
+        //   ⚠️ 非加不可的理由：封盖被切成几百上千个小面后，新面中心几乎不可能正好等于某个旧面中心
+        //   ⇒ 没有这一层，改墙高 / 改墙点之后封盖的序号会整片变 -1（得重跑一次「智能序号」才看得见图）。
+        const insideBudget = oldTris.length * faceCount <= 4000000; // 兜底闸：面数大到离谱就跳过这层，别把改墙那一下卡死
+        const side2 = (ax: number, az: number, bx: number, bz: number, px: number, pz: number): number =>
+            (bx - ax) * (pz - az) - (bz - az) * (px - ax);
+        /** 点在 XZ 平面上的三角形内（叉积同号）判据：命中多个（上下封盖同 XZ）时取 y 最近那一片 */
+        const pickInside = (px: number, pz: number, cy: number): number => {
+            let best = -1;
+            let bestD = Infinity;
+            for (let i = 0; i < oldTris.length; i++) {
+                const t = oldTris[i];
+                const d1 = side2(t.ax, t.az, t.bx, t.bz, px, pz);
+                const d2 = side2(t.bx, t.bz, t.cx, t.cz, px, pz);
+                const d3 = side2(t.cx, t.cz, t.ax, t.az, px, pz);
+                // 三个叉积里有正有负 ⇒ 点在三角形外（全 0 = 退化成一条线的面，也算命中，交给 y 差挑）
+                if ((d1 > 0 || d2 > 0 || d3 > 0) && (d1 < 0 || d2 < 0 || d3 < 0)) continue;
+                const d = Math.abs(t.y - cy);
+                if (d < bestD) { bestD = d; best = t.idx; }
+            }
+            return best;
+        };
+        for (let f = 0; f < faceCount; f++) {
+            const a = 9 * f;
+            const cx = (positions[a] + positions[a + 3] + positions[a + 6]) / 3;
+            const cz = (positions[a + 2] + positions[a + 5] + positions[a + 8]) / 3;
+            const cy = (positions[a + 1] + positions[a + 4] + positions[a + 7]) / 3;
+            const cand = oldMap.get(`${rk(cx)},${rk(cz)}`);
+            if (cand && cand.length) {
+                // 同 XZ 多个候选（上/下封盖）时取 y 最近者，避免把底盖映射错配到顶盖
+                let best = cand[0];
+                let bestD = Math.abs(best.y - cy);
+                for (let i = 1; i < cand.length; i++) {
+                    const d = Math.abs(cand[i].y - cy);
+                    if (d < bestD) { bestD = d; best = cand[i]; }
+                }
+                newMapping[f] = best.idx;
+            } else if (insideBudget && oldTris.length) {
+                const v = pickInside(cx, cz, cy);
+                if (v >= 0) newMapping[f] = v; // -1 = 那一片本来就没指派，保持未指派
+            }
+        }
+        this.panoFaceMapping = newMapping;
+        // 重建 XZ 索引（供下次改墙保留）
+        const xzMap = new Map<string, { y: number; idx: number }[]>();
+        for (let f = 0; f < faceCount; f++) {
+            const a = 9 * f;
+            const cx = (positions[a] + positions[a + 3] + positions[a + 6]) / 3;
+            const cz = (positions[a + 2] + positions[a + 5] + positions[a + 8]) / 3;
+            const cy = (positions[a + 1] + positions[a + 4] + positions[a + 7]) / 3;
+            const key = `${rk(cx)},${rk(cz)}`;
+            const arr = xzMap.get(key) ?? [];
+            arr.push({ y: cy, idx: newMapping[f] });
+            xzMap.set(key, arr);
+        }
+        this._panoXZMap = xzMap;
+        // aPanoIndex 几何属性（每三角面 3 顶点同值 = 该面归属的全景全局序号；默认 -1 = 未设）
+        const panoIdxAttr = new Float32Array(faceCount * 3);
+        for (let f = 0; f < faceCount; f++) {
+            const v = newMapping[f] ?? -1;
+            panoIdxAttr[3 * f] = v;
+            panoIdxAttr[3 * f + 1] = v;
+            panoIdxAttr[3 * f + 2] = v;
+        }
+        geo.setAttribute("aPanoIndex", new Float32BufferAttribute(panoIdxAttr, 1));
+
+        this.geometry.dispose();
+        this.geometry = geo;
+        this._syncPanoCenterAttr(); // ⭐ 2026-09-30：同步 aPanoCenter（每三角面9数，与 position 对齐）
+    }
+
+    /**
+     * 设置某个三角面（faceIndex）归属的全景全局序号；-1=清除（序号模式下显示深灰兜底色）。
+     * 更新映射数组 + 几何 aPanoIndex 属性（仅该面 3 顶点），并同步 XZ 索引供后续改墙保留。
+     */
+    setFacePanoIndex(faceIndex: number, globalIndex: number): void {
+        if (faceIndex < 0 || faceIndex >= this.panoFaceMapping.length) return;
+        this.panoFaceMapping[faceIndex] = globalIndex;
+        const attr = this.geometry.getAttribute("aPanoIndex") as Float32BufferAttribute | undefined;
+        if (attr && attr.count === this.panoFaceMapping.length * 3) {
+            attr.setXYZ(faceIndex * 3, globalIndex, globalIndex, globalIndex);
+            attr.needsUpdate = true;
+            // ⭐ 2026-09-30：同步该面 aPanoCenter（每三角面9数，与 position 对齐）
+            const cAttr = this.geometry.getAttribute("aPanoCenter") as Float32BufferAttribute | undefined;
+            if (cAttr && cAttr.count === this.panoFaceMapping.length * 3) {
+                const nPano = this.panoCenters.length / 3;
+                let cx = 0, cy = 0, cz = 0;
+                if (globalIndex >= 0 && globalIndex < nPano) {
+                    cx = this.panoCenters[globalIndex * 3];
+                    cy = this.panoCenters[globalIndex * 3 + 1];
+                    cz = this.panoCenters[globalIndex * 3 + 2];
+                }
+                for (let v = 0; v < 3; v++) cAttr.setXYZ(faceIndex * 3 + v, cx, cy, cz);
+                cAttr.needsUpdate = true;
+            }
+        } else {
+            // 属性缺失/长度不符（极少）：整面重建（按位置保留会把它当成 -1，但此处是显式指定，可接受）
+            this.rebuildWallGeometry();
+        }
+        this._rebuildXZMap();
+    }
+
+    /** 重建 XZ 索引（映射变化后调用，保证下次改墙按位置保留） */
+    private _rebuildXZMap(): void {
+        const pos = this.geometry.getAttribute("position") as BufferAttribute | undefined;
+        const faceCount = pos ? Math.floor(pos.count / 3) : 0;
+        const rk = (v: number): number => Math.round(v * 1000) / 1000;
+        const m = new Map<string, { y: number; idx: number }[]>();
+        for (let f = 0; f < faceCount; f++) {
+            const a = 9 * f;
+            const cx = (pos!.getX(a) + pos!.getX(a + 3) + pos!.getX(a + 6)) / 3;
+            const cz = (pos!.getZ(a) + pos!.getZ(a + 3) + pos!.getZ(a + 8)) / 3;
+            const cy = (pos!.getY(a) + pos!.getY(a + 3) + pos!.getY(a + 7)) / 3;
+            const key = `${rk(cx)},${rk(cz)}`;
+            const arr = m.get(key) ?? [];
+            arr.push({ y: cy, idx: this.panoFaceMapping[f] ?? -1 });
+            m.set(key, arr);
+        }
+        this._panoXZMap = m;
+    }
+
+    /** 三角面总数（= 几何顶点数 / 3，因非索引三角形汤） */
+    getFaceCount(): number {
+        const pos = this.geometry.getAttribute("position") as BufferAttribute | undefined;
+        return pos ? Math.floor(pos.count / 3) : 0;
+    }
+
+    /**
+     * 返回被三角面引用的全景全局序号集合（去重），按引用面数降序、最多 maxSlots 个。
+     * ⚠️ 2026-10-03 起**不在喂料路上**（墙那 8 格改由槽位名册决定，见 `feedFaceMapping`）；保留为公共查询 API
+     *   （外部若要按「哪几张全景被指派得最多」统计仍可用），⛔ 不许再拿它决定 shader 装哪几张。
+     */
+    getReferencedPanoIndices(maxSlots: number): number[] {
+        const cnt = new Map<number, number>();
+        for (const idx of this.panoFaceMapping) {
+            if (idx >= 0) cnt.set(idx, (cnt.get(idx) ?? 0) + 1);
+        }
+        const sorted = [...cnt.entries()].sort((a, b) => b[1] - a[1]).map((e) => e[0]);
+        return sorted.slice(0, maxSlots);
+    }
+
+    /** 仅重建 aPanoIndex 几何属性（映射数据变化、几何未变时调用，避免整面重建） */
+    rebuildPanoIndexAttribute(): void {
+        const faceCount = this.panoFaceMapping.length;
+        const attr = this.geometry.getAttribute("aPanoIndex") as Float32BufferAttribute | undefined;
+        if (attr && attr.count === faceCount * 3) {
+            for (let f = 0; f < faceCount; f++) {
+                const v = this.panoFaceMapping[f] ?? -1;
+                attr.setXYZ(f * 3, v, v, v);
+            }
+            attr.needsUpdate = true;
+        } else {
+            this.rebuildWallGeometry();
+        }
+        this._rebuildXZMap();
+        this._syncPanoCenterAttr(); // ⭐ 2026-09-30：同步 aPanoCenter（每三角面9数，与 position 对齐）
+    }
+
+    // ───────────────────────── 纹理列表管理 ─────────────────────────
+
+    /** 从 textures 各矩阵平移分量（elements[12,13,14]，即墨卡托投影中心）派生 panoCenters（每全景 xyz）。
+     *  全景点位置与纹理图片加载解耦，纯几何；智能序号只依赖这份数据。 */
+    protected _syncPanoCenters(): void {
+        const out: number[] = new Array(this.textures.length * 3);
+        for (let i = 0; i < this.textures.length; i++) {
+            const e = this.textures[i].matrix.elements;
+            out[i * 3] = e[12];
+            out[i * 3 + 1] = e[13];
+            out[i * 3 + 2] = e[14];
+        }
+        // ⚠️ 写缓存字段而非 this.panoCenters —— 后者是 getter，会递归回本方法
+        this._panoCentersCache = out;
+    }
+
+    /**
+     * 写 aPanoCenter 几何属性：每三角面 9 数（该面归属全景的中心 xyz，复制到 3 顶点），
+     * itemSize=3、count = position.count，与 position **完全对齐**
+     * （皇上旨 2026-09-30 第③点：「每个三角面 9 个数一组，全景也按 9 数一组、和顶点数组长度对齐」）。
+     * 源 = panoCenters（每全景 xyz）；面未映射（gi<0 或越界）填 0。
+     * rebuildWallGeometry / rebuildPanoIndexAttribute / setFacePanoIndex 都会调它保持同步。
+     */
+    private _syncPanoCenterAttr(): void {
+        const faceCount = this.panoFaceMapping.length;
+        const posAttr = this.geometry.getAttribute("position") as BufferAttribute | undefined;
+        if (!posAttr || posAttr.count !== faceCount * 3) return; // 几何与映射不一致先跳过
+        const centers = this.panoCenters;
+        const nPano = centers.length / 3;
+        let attr = this.geometry.getAttribute("aPanoCenter") as Float32BufferAttribute | undefined;
+        if (!attr || attr.count !== faceCount * 3) {
+            attr = new Float32BufferAttribute(new Float32Array(faceCount * 9), 3);
+            this.geometry.setAttribute("aPanoCenter", attr);
+        }
+        const arr = attr.array as Float32Array;
+        for (let f = 0; f < faceCount; f++) {
+            const gi = this.panoFaceMapping[f] ?? -1;
+            let cx = 0, cy = 0, cz = 0;
+            if (gi >= 0 && gi < nPano) {
+                cx = centers[gi * 3]; cy = centers[gi * 3 + 1]; cz = centers[gi * 3 + 2];
+            }
+            const a = 9 * f; // 每三角面 9 数，与 position 同布局
+            for (let v = 0; v < 3; v++) {
+                const o = a + v * 3;
+                arr[o] = cx; arr[o + 1] = cy; arr[o + 2] = cz;
+            }
+        }
+        attr.needsUpdate = true;
+    }
+
+    /** 设置纹理列表并激活第一个（或最近的）纹理 */
+    setTextures(textures: MktTextureInfo[]): void {
+        // ⭐ 皇上旨 2026-10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」⇒ 换工程**不**清 `_texCache`
+        //    （旧项目的瓦片留到本对象 dispose 再释放；清它等于下次切回来重走一遍下载 + 解码 = 卡顿源头）。
+        //    要清的只有**名册**：里面躺的是上一批 `MktTextureInfo` 对象引用，留着会让下一帧拿已删景点的 URL 去喂槽。
+        this._slotPanos = [];
+        this.textures = textures;
+        this.activeIndex = -1;
+        this._syncPanoCenters(); // ⭐ 2026-09-30：派生全景点坐标（与纹理解耦）
+        if (this.textures.length > 0) {
+            this.activateTexture(0);
+        }
+    }
+
+    /** 追加一个纹理 */
+    addTexture(info: MktTextureInfo): void {
+        this.textures.push(info);
+        this._syncPanoCenters();
+    }
+
+    /** 删除一个纹理；若删除的是当前激活纹理则回退，索引随之前移 */
+    removeTexture(index: number): void {
+        if (index < 0 || index >= this.textures.length) {
+            return;
+        }
+        this.textures.splice(index, 1);
+        this._syncPanoCenters();
+        // ⭐ 10-03 旨⑤：缓存键是**地址**不是「全景序号」⇒ 删点导致序号整体前移**不需要**清缓存
+        //    （旧写法 `_invalidateTileCache()` 是因为按序号缓存、不清就把旧地址挂在新序号上）；
+        //    名册存对象引用 ⇒ 被删的那个对象下一帧自然从名册里掉出去（`panoSlotRosterStep` 只认 dists 里还有的人）。
+        if (this.activeIndex === index) {
+            this.activeIndex = -1;
+        } else if (this.activeIndex > index) {
+            this.activeIndex--;
+        }
+    }
+
+    /**
+     * 更新单个纹理的 url / 名称 / 矩阵；若改的是「当前激活纹理」则同步生效。
+     *
+     * ⚠️ 需求铁律（防止回归）：墙面绘制的是「当前激活纹理」，其朝向由 shader 的 textureMatrix uniform 决定。
+     * 所以只要激活纹理的位置/旋转变了，必须**立即**把新矩阵 copy 进 textureMatrix uniform——
+     * 否则用户旋转/移动全景球时，平面纹理不会跟着一起转。
+     * 另：改旋转不要触发纹理网络 reload，只有 url 真正变化才重载。
+     */
+    setTexture(index: number, opts: { url?: string; name?: string; matrix?: Matrix4; tiles?: string[] }): void {
+        if (index < 0 || index >= this.textures.length) {
+            return;
+        }
+        const cur = this.textures[index];
+        if (opts.url !== undefined) {
+            cur.url = opts.url;
+        }
+        // 名称只是标识，不参与渲染，改它**不**触发纹理 reload（见下方 opts.url 分支）
+        if (opts.name !== undefined) {
+            cur.name = opts.name;
+        }
+        if (opts.tiles !== undefined) {
+            cur.tiles = opts.tiles;
+        }
+        if (opts.matrix !== undefined) {
+            cur.matrix.copy(opts.matrix);
+            this._syncPanoCenters(); // ⭐ 全景位置/旋转一变，全景点坐标同步派生
+        }
+        if (index === this.activeIndex) {
+            // 关键：激活纹理的矩阵一变，立刻同步到 shader uniform（墙面纹理才会跟着转）。
+            // ⚠️ 基类材质现改为融合形态（textureMatrices 数组），无单数 textureMatrix；
+            // 单全景形态用 textureMatrix、融合形态用 textureMatrices[0]，两者都接住。
+            const tm = (this.material.uniforms.textureMatrix?.value ??
+                this.material.uniforms.textureMatrices?.value?.[0]) as Matrix4 | undefined;
+            if (tm) tm.copy(cur.matrix);
+            // ⭐ 10-03 旨⑤：改地址/瓦片**不需要**在这里手工失效重载 —— 缓存按地址建键，新 URL 天然是新条目，
+            //    下一帧 `feedFaceMapping` 见「账本里的地址 ≠ 目标地址」就走整槽换人（判不齐则沿用上一批），
+            //    跨形态（32 片拼合 ↔ 整片）那一次由 binder 的整档判齐支负责。旧写法（清序号缓存 + 重新 activate）已整条删除。
+        }
+    }
+
+    /**
+     * 把 inverse(matrixWorld) 写进当前材质的 uProjInvMatrix（每帧一次）—— 「投影与自身变换解耦」的唯一写入点。
+     *
+     * ⚠️ 需求铁律（皇上旨 2026-09-19）：「墙的矩阵和全景的矩阵是相对的，无论 MktMesh 模型整体
+     * 怎么移动/旋转/缩放，墙上的纹理都保持不变」。
+     * 达成条件是「取样方向的两个操作数都对 MktMesh 的整体变换免疫」：
+     *   · 全景点矩阵（textureMatrix）是**世界矩阵**、属独立于 MktMesh 的外部数据 → 本就不随它动；
+     *   · 墙顶点经 modelMatrix 升到世界坐标 → **会**随它动 → 一个动一个不动，方向即变，纹理在墙上滑动。
+     * 故此处把 inverse(matrixWorld) 交给着色器，把墙顶点也拉回「与整体变换无关的几何局部坐标」，
+     * 两个操作数双双免疫，方向恒定，纹理稳稳贴在墙上。
+     * ⚠️ M ≠ I 时 vProjPos（局部）与 textureMatrix（世界）并不在同一空间 —— 这是**刻意**的：
+     *    皇上要的是「纹理贴在墙上不动」，条件是「两个操作数都不随 M 变」，而非「同处一个空间」。
+     *    千万别"好心"再去把 textureMatrix 也乘一遍 inverse(matrixWorld)，那会让纹理重新动起来。
+     *
+     * 每帧无条件重算（一次 4x4 求逆，代价可忽略）：用户拖预览变换面板时 matrixWorld 每帧都在变，
+     * 靠「变更时通知」容易漏，无条件同步最稳。材质被替换（如编辑态 blend↔single 重建）时按当前材质重新取
+     * uniform，故 **MktDevMesh 也必须每帧调用本方法**（它同样会重建材质，见该类 onBeforeRender 注释）。
+     * 材质没有该 uniform（旧材质/第三方材质）时静默跳过 —— 退化为「世界坐标」的旧行为。
+     */
+    syncProjInvMatrix(): void {
+        const mat = this.material as ShaderMaterial;
+        const u = mat && mat.uniforms ? mat.uniforms.uProjInvMatrix : undefined;
+        if (!u) return;
+        (u.value as Matrix4).copy(this.matrixWorld).invert();
+    }
+
+    // ───────────────────────── 每帧最近纹理计算 ─────────────────────────
+
+    /** 每帧算「离**名册锚点**最近」的水平距离（XZ）⇒ 走**槽位名册**（中心 ± 邻居）⇒ 名册中心变化时切换激活纹理。
+     *  ⭐ 皇上旨 2026-10-07 第二十一道旨：锚点 = 外部控制器的中心点（`setRosterCenter` 注入的轨道注视点）；
+     *  没注入（如发布页那一路）才回落相机位置。 */
+    updateTexture(camera: Camera): void {
+        const n = this.textures.length;
+        if (n === 0) {
+            this._slotPanos = [];
+            this.activeIndex = -1;
+            return;
+        }
+        const ref = this._rosterCenter ?? camera.position;
+        const dists: { t: MktTextureInfo; d: number }[] = [];
+        for (let i = 0; i < n; i++) {
+            const e = this.textures[i].matrix.elements;
+            this._tmpV3.set(e[12], e[13], e[14]);
+            // ⚠️ 全景点矩阵**本身就是世界矩阵**（见上方 textures 字段注释），位置已在世界空间，
+            //    可直接与锚点的世界坐标比距离 —— 这里**绝不能再乘 matrixWorld**：那是双重变换，
+            //    MktMesh 一有整体变换就会算错「离锚点最近的是哪张」（选错全景）。
+            //    （2026-09-19 曾误以为它记在模型空间而多乘了一次，趁 MktDevMesh 对齐时一并纠正。）
+            // ⭐ 09-28 09:33 旨：挑图与编辑器取图同一把「**水平距离**」尺（XZ 平面，不含高度差）。
+            // const d = this._tmpV3.distanceTo(camera.position);   // 旧原理：三维直线距离——全景点同高（y 恒 1.6）时与本式排序等价，注释保留备查
+            // ⭐ 10-07 第二十一道旨：尺子的另一端从相机位置换成 `ref`（控制器中心点；未注入时它就是相机位置）。
+            dists.push({ t: this.textures[i], d: Math.hypot(this._tmpV3.x - ref.x, this._tmpV3.z - ref.z) });
+        }
+        // ⭐ 皇上旨 2026-10-03「1.可以」：预览/发布态的 8 格**也**按「中心 ± 邻居」名册挑（算法与死区常数
+        //    都在 ./panoSlotRoster，编辑态那份读的是同一处 ⇒ 预览与编辑器逐字同一批全景）；
+        //    ⛔ 不再按「引用面数取前 4」（getReferencedPanoIndices 那套静态名单只留作公共 API，不进喂料路）。
+        this._slotPanos = panoSlotRosterStep(this._slotPanos, dists, MKT_PANO_MAX_SLOTS, PANO_SLOT_SWAP_MARGIN_M);
+        // ⭐ 10-03 旨②：中心那张不再要「抄给立方体」（立方体已与墙共用同一份材质），但**仍**留 `activeIndex`
+        //    作为「名册中心有没有换人」的闩锁（下面的比较 + 外部只读），换人才重新激活。
+        const center = this._slotPanos[0];
+        const target = center ? this.textures.indexOf(center) : -1;
+        if (target >= 0 && target !== this.activeIndex) {
+            this.activateTexture(target);
+        }
+        // 每帧**只**驱动一次拼合器（皇上旨 09-29「一帧里别同时处理很多纹理」+ 10-06「每帧只载入一张新纹理到 GPU」
+        // ⇒ 拼合器内部分两段：每帧最多 1 次新纹理上传，画进 RT 只认已在显存里的那几格）：
+        // 下面的 `feedFaceMapping` 与各槽 `ensureTileTexture` 一律只 peek，不在这里重复 pump。
+        // ⭐ 10-06：RT 要在 renderer 上才画得进去 —— `_glRenderer` 由 `onBeforeRender` 在**这一句之前**捕获
+        //   （构造后头一帧还没捕获到就传 null：那一帧什么都不画，下一帧自然补上）。
+        this._stitcher.pump(this._glRenderer);
+    }
+
+    /** 给纹理地址追加 OSS 图片缩放参数（1024 / 2048 / 空=不缩放）。
+     *  尺寸由外部 setOssSize 控制（默认 1024，与编辑器渲染器 resolveOssUrl 语义一致）；
+     *  预览/发布库经 setOssSize 注入，使全景球按所选尺寸加载。
+     *  ⚠️ `original=true`（这一槽喂的是**真瓦片地址**，即 rt 虚拟键那一路）时**一律走原图**、不拼尺寸参数
+     *  （皇上旨 2026-09-23「切换到4片瓦片的时候, 就不需要设置oss 尺寸参数了, 默认使用原图」）。
+     *  判据与喂地址、写 `uPanoTiled` 同源（`mktPanoTiledFlag`），别另算一套。 */
+    private resolveOssUrl(url: string, original = false): string {
+        // ⭐ 32 瓦片拼合的虚拟键不是真 URL（纹理由 PanoTileStitcher 提供），原样放行、绝不拼 OSS 参数
+        if (!url || url.startsWith(RT_STITCH_KEY_PREFIX) || url.includes("x-oss-process")) {
+            return url;
+        }
+        if (original) return url;
+        const size = this._ossSize;
+        if (!size) return url;
+        const sep = url.includes("?") ? "&" : "?";
+        return `${url}${sep}x-oss-process=image/resize,m_lfit,w_${size}`;
+    }
+
+    /** ⭐ 皇上旨 2026-10-07 第二十一道旨：把「用哪些全景球」那把尺子的锚点从相机位置换成**控制器中心点**。
+     *  消费方（预览弹窗）把轨道控制器的 `target` 交进来即可；传 `null` = 回落相机位置（老口径，发布页照旧）。
+     *  存引用不存副本 ⇒ 轨道控制器原地改那个 Vector3，设一次就一直跟着走。 */
+    setRosterCenter(center: Vector3 | null): void {
+        this._rosterCenter = center;
+    }
+
+    /** 设置纹理 OSS 缩放尺寸（1024 / 2048 / 空=原图）；变化即按新尺寸重载当前激活纹理。
+     *  编辑器 MktDevMesh 关闭了 activateTexture（activeIndex=-1），此处为 no-op；预览/发布库用基类激活，会真正按新尺寸重载。 */
+    setOssSize(size: "1024" | "2048" | ""): void {
+        const next = size === "1024" || size === "2048" || size === "" ? size : "1024";
+        if (next === this._ossSize) return;
+        this._ossSize = next;
+        this._reloadActiveTexture();
+    }
+
+    /** ossSize 换档后重载「加载地址拼了尺寸参数」的那批条目（与编辑态 `_reloadFloorTextures` 同口径：
+     *  dispose + 删条目，下一帧 `_peekTileAt` 自然按新档重拉）。
+     *  ⚠️ 真瓦片（现行 32 片/全景）一律走原图 ⇒ 不在重载范围；整图档才受尺寸档影响（皇上旨 09-23）。 */
+    private _reloadActiveTexture(): void {
+        if (this._ossSizeDepKeys.size === 0) return;
+        for (const key of this._ossSizeDepKeys) {
+            releasePanoTexture(this._texCache.get(key)); // 换档丢掉的这张要连位图一起关（见 `releasePanoTexture`）
+            this._texCache.delete(key);
+        }
+        this._ossSizeDepKeys.clear();
+    }
+
+    // ───────────── 全景瓦片缓存（按地址 + 每 tick 一张上传；与编辑态同一份策略） ─────────────
+
+    /** 换绑一个点槽的左右 2 张拼合槽纹理：策略全在 `./panoSlotBind`（皇上旨 10-03「整套搬进库」⇒ 编辑器与库**同一份**），
+     *  这里只把本类的取图口与占位纹理注入进去。返回 true = 图与点位配好了（调用方才写投影矩阵）。 */
+    private _bindSlotTiles(
+        mat: ShaderMaterial, panos: Texture[], base: number, tiles: string[], tiled: boolean, slot: number
+    ): boolean {
+        return panoSlotBind(mat, panos, base, tiles, tiled, slot, {
+            peek: (key, original) => this._peekTileAt(key, original),
+            // 跨形态（瓦片 ↔ 整片）那一次要「整槽同进同退」：库里没有过渡档那一层，逐张 peek 攒成整槽即可。
+            // ⛔ 长度由 `RT_STITCH_SLOT_COUNT` 派生（10-06 晚旨后是 2 张，⛔ 别写死 4 个下标）
+            peekSlot: (t, original) =>
+                Array.from({ length: RT_STITCH_SLOT_COUNT }, (_, k) => this._peekTileAt(t[k], original)),
+            placeholder: this._placeholder,
+        });
+    }
+
+    /** 本材质「panoramas[i] 这一格认的是哪张瓦片地址」——逐张换绑的账本（⚠️ 账本实体在 `./panoSlotBind`，
+     *  与编辑态共一本，按材质实例分键 ⇒ 两处材质不同实例、天然不串味）。 */
+    private _tileKeys(mat: ShaderMaterial, len: number): string[] {
+        return panoSlotTileKeys(mat, len);
+    }
+
+    /** 按缓存键要一张**已经设进 shader** 的纹理：没有就当场发起下载（异步代码一律不进全局队列 —— 皇上旨 2026-09-25），
+     *  解码完还没上传的排一个「只干上传那一句」的队列项；两关都过了才返回给它去绑。
+     *  ⭐ `rt:` 虚拟键（32 瓦片拼合槽）走拼合器 peek；⛔ 不在这里 pump（每帧驱动点唯一，见 `updateTexture`，
+     *    否则一帧画好几格 = 把「每帧只载入一张新纹理」那道闸从后门拆了）。 */
+    private _peekTileAt(key: string, original: boolean): Texture | null {
+        if (isRtStitchKey(key)) {
+            const p = rtStitchKeyParts(key);
+            if (!p) return null;
+            const tex = this._stitcher.peek(p.batch, p.slot);
+            if (!tex) return null;
+            // ⭐ 皇上旨 09-29「两个大头别在同一帧」：普通瓦片不许在 render 首绑现场 texSubImage2D ⇒ 走
+            //    「每 tick 一张」预上传队列；没排到的帧返回 null，自动推迟绑定 ⇒ render 里从此没有首绑上传。
+            // ⭐ 皇上旨 10-06 换成 RT 那一份后这一闸**自动跳过**：RT 的附件纹理本来就在显存里，
+            //    压根没有「上传」那一下（⛔ 也别拿 `initTexture` 去喂它 —— 那是 three 自己管的渲染目标）。
+            if (!this._stitcher.resident(tex) && !this._texUploaded.has(tex)) {
+                this._commitTileToShader(tex);
+                return null;
+            }
+            return tex;
+        }
+        const tex = this._texCache.get(key);
+        if (!tex) {
+            // 未开始或加载中：直接发起（缓存里以 null 占位 ⇒ 同一地址不会被问两次就下两遍）。
+            // 发起只是把 XHR 丢出去（微秒级），主线程成本可忽略；真正贵的解码/上传各自有闸。
+            this.ensureTileTexture(key, original);
+            return null;
+        }
+        if (!this._texUploaded.has(tex)) {
+            this._commitTileToShader(tex); // 已解码但还没上 GPU：排它自己的那一个 tick，这一帧不绑
+            return null;
+        }
+        return tex;
+    }
+
+    /** 真正发起一张瓦片纹理的加载（`key` = 原始地址；rt 虚拟键由 `_peekTileAt` 上半段拦走，不会到这里）。
+     *  ⚠️ 皇上旨 2026-09-28「加载瓦片的时候, 瓦片纹理不需要添加 oss 的参数」⇒ 真瓦片（`original=true`，现行 32 片/全景）走原图，
+     *     整图档才按 ossSize 档缩（`resolveOssUrl`）。 */
+    private ensureTileTexture(key: string, original = false): Texture | null {
+        const cached = this._texCache.get(key);
+        if (cached) return cached;
+        if (cached === null) return null; // 加载中
+        this._texCache.set(key, null); // 标记加载中
+        const loadUrl = this.resolveOssUrl(key, original);
+        if (loadUrl !== key) this._ossSizeDepKeys.add(key);
+        loadPanoTexture(loadUrl).then(
+            (tex) => {
+                tex.colorSpace = SRGBColorSpace;
+                // 该键可能已被 `_reloadActiveTexture`（换档）删掉并重新发起 ⇒ 按键写回即可：地址就是本条目的身份，
+                // 不存在「过期回调写脏另一个地址」的问题（与编辑态 `_floorTexCache` 同一口径）。
+                this._texCache.set(key, tex);
+                // 解码已在浏览器工作线程做完（甲）⇒ 这里只排它**自己那一个**队列项（只含「上传 GPU」那一句）：
+                // 一批里几张同时解完 ⇒ 各自排各自的 tick 逐张落地，上传那一拍不再顺带同步解码。
+                this._commitTileToShader(tex);
+            },
+            () => {
+                // 单张失败：摘掉「加载中」占位 ⇒ 下一帧同键判定仍是未就绪，自动重试（旧库路径本来就会重试，口径不变）。
+                if (this._texCache.get(key) === null) this._texCache.delete(key);
+            }
+        );
+        return null;
+    }
+
+    /** ⭐ 把一张「已经加载解码好」的纹理排进全局队列，排到的那个 tick 只做一件事：把它上传到 GPU。
+     *  皇上旨 2026-09-25 原文：「队列里面的代码就是 把加载好的纹理 设置给 shader 的 这一句代码」——
+     *  所以下载、淘汰、绑定判断统统不许出现在回调里。
+     *  ⚠️ 去重闸门必须是自己的 `_uploadQueued`：`addWork` 用 `workList.includes(work)` 判重，而每次都是新闭包 ⇒ 判不出来。
+     *  ⭐ 皇上旨 2026-10-05：「你在调用 addWork 的时候，再调一次 addWork 传入一个空函数，这样真正需要执行的方法就会隔一帧执行」
+     *  ⇒ 真活前面先垫一个空函数占一格（全局队列每 tick 只跑一项 ⇒ 多一格 = 晚一帧），与编辑态 `_commitTileToShader` 同一口径。
+     *  ⚠️ 空函数**必须内联每次现造**：`addWork` 按引用判重，共用一个常量引用时第二张起空格进不了队列 ⇒ 改动静默失效。 */
+    private _commitTileToShader(tex: Texture): void {
+        if (this._texUploaded.has(tex) || this._uploadQueued.has(tex)) return;
+        this._uploadQueued.add(tex);
+        threeUtils.addWork(() => {}); // 占一格（什么都不干），把下面那一项推到下一个 tick
+        threeUtils.addWork(() => this._uploadTileTexture(tex));
+    }
+
+    /** 队列回调的全部内容：把这一张纹理上传到 GPU（`texImage2D` + mipmap 才是那一下贵的），每 tick 一张。 */
+    private _uploadTileTexture(tex: Texture): void {
+        // 排上队之后已被清掉（那张 dispose 过了）⇒ 本项作废：再上传会把显存凭空建回来且无人回收。
+        if (!this._uploadQueued.delete(tex)) return;
+        try {
+            // `_glRenderer` 还没被 `onBeforeRender` 捕获到（构造后尚未渲染过一帧）⇒ 跳过预上传，
+            // 交给 three 在绑定那一帧自己上传 —— 那是改造前的老路径，不会报错，只是那一张没享受「错峰」。
+            if (this._glRenderer) this._glRenderer.initTexture(tex);
+        } catch (e) {
+            console.warn("[MktMesh] 瓦片预上传失败，交给常规渲染路径自行上传：", e);
+        }
+        // ⚠️ 成败都记「已处理」。不记 ⇒ 这张永远进不了 `_texUploaded` ⇒ 那一格永远换不上新图，
+        //    比「卡一下」严重得多；记了最坏也只是退回 three 在绑定那一帧自己上传的老路径。
+        this._texUploaded.add(tex);
+    }
+
+    /**
+     * 序号直接取模式喂食（皇上旨 2026-09-28 决策③：MktMesh 基类只有这一种模式）。
+     * ⭐ 皇上旨 2026-10-03「1.可以」：shader 各槽装的是**槽位名册**那 `MKT_PANO_MAX_SLOTS` 张（`_slotPanos`，
+     *   中心 ± 邻居，与编辑态 `mktMeshEditRenderer.feedFaceMapping` 同一份算法、同一个死区常数）
+     *   ⇒ 预览/发布与编辑器同一屏装同一批全景。⛔ 不再按「被引用面数取前 4」（那是 09-28 的静态名单，
+     *   与相机无关 ⇒ 走近的景点进不了槽，正是他这次报「预览里 shader 不对」的根因）。
+     * 片元按 aPanoIndex 在 panoIndices 里找对应 slot 取纹理；指派的那张不在当前名册里 ⇒ 该面回落 `uFaceMissingColor` 深灰，
+     * 把**名册锚点**挪近那张景点后自动出图（⭐ 10-07 第二十一道旨：预览轨道模式 = 控制器中心点，第一人称/未注入 = 相机位置；与编辑态同一份已知代价）。
+     */
+    feedFaceMapping(): void {
+        this._stitcher.pump(this._glRenderer); // 每帧驱动拼合器（≤1 片/帧；下方逐槽只 peek 不驱动）
+        const mat = this.material as ShaderMaterial;
+        const u = mat.uniforms;
+        if (!u.panoIndices) return; // 非融合材质（防御）
+        u.uPanoramaVisible.value = 1;
+        // 复用统一喂料：填 panoramas[]/textureMatrices[]/weights[] + uPanoramaVisible
+        // （材质本身就是序号直取 shader，恒按 panoIndices 选槽取图——原 uFaceMappingMode=1 翻转已随拆分删除；
+        //  ⚠️ 本函数**从来没写过** uColorSpace：那句旧注释是骗人的。色彩空间 2026-10-07 已整条退路——
+        //  纹理恒标 SRGBColorSpace 由硬件解码一次，shader 不再手动 pow，故连 uniform 都不存在了。）
+        const maxPano = (u.panoIndices.value as Float32Array).length;
+        const panos = u.panoramas.value as Texture[];
+        const mats = u.textureMatrices.value as Matrix4[];
+        const ws = u.weights.value as Float32Array;
+        const idxU = u.panoIndices.value as Float32Array;
+        const keys = this._tileKeys(mat, panos.length);
+        for (let s = 0; s < maxPano; s++) {
+            const base = s * RT_STITCH_SLOT_COUNT; // ⛔ 不是 s*4：10-06 晚旨后一个全景只占左右 2 槽
+            const info = this._slotPanos[s]; // 名册没这一格（项目全景总数不够 / 首帧未算）⇒ 走下面的清空支
+            if (!info) {
+                for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) panos[base + k] = this._placeholder;
+                mats[s].identity();
+                ws[s] = 0;
+                idxU[s] = -1;
+                continue;
+            }
+            idxU[s] = this.textures.indexOf(info);
+            // 各槽喂什么地址 = 「用户选的形态 + 该点有没有切过片」共同决定（whole 或无 tiles ⇒ 各槽同为一张整图）
+            const tiles = mktPanoTexUrls(info.url, info.tiles, this._panoTexMode);
+            // ⚠️ 「是不是真瓦片」只算一次：喂地址（走不走 OSS 尺寸档）与写 uPanoTiled 共用同一个值
+            const tiled = mktPanoTiledFlag(info.tiles, this._panoTexMode) === 1;
+            // ⭐ 10-06 晚旨「只支持 32 张（8×4）」：任意 1~32 条瓦片整组交拼合器（不足 32 张的格子涂灰）；
+            //    这 2 槽是虚拟键，这里只负责「每帧把真 URL 喂给拼合器」（虚拟键本身不含完整地址）。
+            if (tiled && info.tiles && info.tiles.length > 0) this._stitcher.ensure(info.tiles);
+            // ⭐ 皇上旨 2026-10-03「整套搬进库」：换绑成败由**共用的那份策略**判定（未就绪 ⇒ 整槽沿用上一批）。
+            //    没换成就**矩阵也别动** ⇒ 旧图永远配旧矩阵（原来矩阵无条件 copy = 新矩阵配旧图，正是②的错配）。
+            const bound = this._bindSlotTiles(mat, panos, base, tiles, tiled, s);
+            if (bound) mats[s].copy(info.matrix);
+            // 左上格当整槽的代表。⚠️ 判据必须**同时**看账本：`keys[base]` 为空串 ⇒ 这座槽**从没成功绑过**，
+            // 此刻 `panos[base]` 里躺的是占位/工厂默认 1×1，而矩阵还是单位阵 —— 给它权重等于拿「世界原点」
+            // 当投影中心投一片素色。已绑过的槽（账本非空）换人没判齐时权重照给 ⇒ 沿用上一批，不整体退出。
+            const hasReal = !!keys[base] && !!panos[base] && panos[base] !== this._placeholder;
+            // 库侧单点不混合 ⇒ 权重恒 1（编辑态那份是距离反比 camW，这里没有「多张混出一个面」的事）
+            ws[s] = hasReal ? 1 : 0;
+        }
+    }
+
+    /** 设置全景纹理形态（tiled=8×4 三十二片走拼合器 / whole=一整片原图）；非法值回落 tiled。
+     *  ⭐ 10-03 旨⑤：这里**不再**手工重载纹理 —— 形态一变目标地址就变了（瓦片 URL ↔ 整图 URL），
+     *     下一帧 `feedFaceMapping` 里共用的那份 binder 见「槽内现有形态 ≠ 目标形态」自动走整档判齐、一次换绑并同帧翻标记。
+     *  编辑器 MktDevMesh 走的是自己那路（同一个 binder、同一份策略），本方法对它只是记下形态。 */
+    setPanoTexMode(mode: PanoTexMode): void {
+        const next = isPanoTexMode(mode) ? mode : "tiled";
+        if (next === this._panoTexMode) return;
+        this._panoTexMode = next;
+    }
+
+    /**
+     * 记下「当前激活（名册 0 号槽 = 中心）是第几个全景」。
+     * ⭐ 皇上旨 2026-10-03 旨②：预览立方体已与墙**共用同一份材质**，原来那句「把中心那几张抄给立方体单全景材质」
+     *   的 `currentTiles` 旁路整条删除 ⇒ 本方法不再加载瓦片、不再写 `uPanoTiled`（形态标记归 binder 逐槽写，
+     *   地址/标记/分辨率三者同源的判据在 `feedFaceMapping`）。留着它是因为 `updateTexture` 用它做「中心换人」的闩锁，
+     *   且它是发布态的公共 API（外部只读 `activeIndex` 靠这里维护）。
+     */
+    activateTexture(index: number): void {
+        if (index < 0 || index >= this.textures.length) {
+            return;
+        }
+        this.activeIndex = index;
+    }
+
+    // ───────────────────────── 导入 / 导出 ─────────────────────────
+
+    /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵） */
+    exportData(): MktMeshData {
+        return {
+            wallPoints: this.wallPoints.map((p) => ({ x: p.x, y: p.y, z: p.z })),
+            wallHeight: this.wallHeight,
+            wallClosed: this.wallClosed,
+            wallSide: this.wallSide,
+            // 全景序号映射：每个三角面归属的全景全局序号（与 wallPoints 同几何拓扑绑定，随存档走）
+            panoFaceMapping: this.panoFaceMapping.slice(),
+            textures: this.textures.map((t) => ({
+                // ⭐ 10-08 旨：存档里只落**根相对路径**（域名在读 JavaScript 之外也用不上，还锁死环境）。
+                //   `stripAssetHost` 幂等 ⇒ 内存里已经是相对的不会出问题，旧存档的绝对地址也不会反复剥。
+                url: stripAssetHost(t.url),
+                name: t.name ?? "",
+                // 2026-09-20：导出 4 瓦片（顺序 [左上, 右上, 左下, 右下]）；旧数据无 tiles 时导空数组
+                tiles: (t.tiles && t.tiles.length ? t.tiles.map(stripAssetHost) : []) as string[],
+                matrix: t.matrix.toArray(),
+            })),
+        };
+    }
+
+    /** 导入数据：重建墙体几何与纹理列表，并激活第一个纹理 */
+    importData(data: MktMeshData): void {
+        this.setWallPoints(data.wallPoints ?? [], {
+            closed: data.wallClosed,
+            height: data.wallHeight,
+        });
+        // ⭐ 还原全景序号映射**放在 setTextures 之后**：rebuildPanoIndexAttribute 会顺手烘焙 aPanoCenter
+        //   （源 = panoCenters，由 textures 实时派生），排在 setTextures 前面 = 拿旧/空纹理列表算圆心 ⇒ 属性里全是 0。
+        this.setWallSide(data.wallSide ?? "double");
+        this.setTextures(
+            (data.textures ?? []).map((t) => {
+                // ⭐ 10-08 旨的成对另一半：存档落的是根相对路径 ⇒ 进内存前在这里**唯一一处**补回域名，
+                //   下游（拼合器 / 预览 / UI `<img>`）拿到的仍是绝对地址 ⇒ 它们一行都不用改。
+                //   `absAssetUrl` 幂等 ⇒ 旧存档里已是绝对地址的（= 升级前存的）不会被拼成 `https://host/https://host/...`
+                const urlAbs = absAssetUrl(t.url as string);
+                return {
+                    url: urlAbs,
+                    name: t.name ?? "",
+                    // 2026-09-20：导入瓦片；缺省回退 [url]（旧存档整图占 1 格）——10-06 晚旨「只支持 32 张（横 8 × 竖 4）」后
+                    // 该点走拼合器：整图缩在 1/32 格 + 其余 31 格涂灰，数据不全一眼可见（重传 32 片切片即修复）
+                    tiles: t.tiles && t.tiles.length ? t.tiles.map(absAssetUrl) : [urlAbs],
+                    matrix: new Matrix4().fromArray(t.matrix),
+                };
+            })
+        );
+        // setWallPoints 已按位置重算过映射（旧为空 → 全 -1），此处用存档里的逐面指派覆盖。
+        // 几何拓扑由同一份 wallPoints 重建，面索引与导出时一致 ⇒ 逐面写入即可对齐。
+        // ⭐ 皇上旨 2026-10-03「补」：长度不符**不再整份丢弃**——按较小长度逐面灌回（存档多出的面丢掉，
+        //   墙变长多出来的那些面保持 setWallPoints 按位置继承到的值），并把两个数 warn 出来（不静默吞）。
+        const imported = (data.panoFaceMapping && data.panoFaceMapping.length ? data.panoFaceMapping : []) as number[];
+        const faceCount = this.panoFaceMapping.length;
+        if (imported.length && imported.length !== faceCount) {
+            console.warn(`[MktMesh] 存档序号映射面数 ${imported.length} ≠ 当前墙体面数 ${faceCount}，按较小者逐面还原（差值来自墙点/墙高变化）`);
+        }
+        const restore = Math.min(imported.length, faceCount);
+        if (restore > 0) {
+            for (let f = 0; f < restore; f++) this.panoFaceMapping[f] = imported[f];
+            this.rebuildPanoIndexAttribute();
+        }
+    }
+
+    // ───────────────────────── 释放 ─────────────────────────
+
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、几何、材质 */
+    dispose(): this {
+        // ⚠️ rt 虚拟键从不进 `_texCache`（拼合槽纹理由 `_stitcher` 自己持有并释放），这里清的都是本类下载的 Texture。
+        // ⭐ 甲（2026-10-05）：`releasePanoTexture` 除 `dispose()` 外还要 `ImageBitmap.close()` —— 位图的原生内存
+        //    不像 `<img>` 能等 GC，一张 270MB 挂着不关，切几轮全景就把进程吃爆。
+        for (const tex of this._texCache.values()) releasePanoTexture(tex);
+        this._texCache.clear();
+        this._texUploaded = new WeakSet(); // WeakSet 无 clear ⇒ 整只换掉
+        this._uploadQueued.clear(); // 排队项即便回调仍触发，也会因 `!this._uploadQueued.delete(tex)` 早退
+        this._ossSizeDepKeys.clear();
+        this._stitcher.dispose();
+        this._glRenderer = null;
+        if (this._placeholder) this._placeholder.dispose();
+        this.geometry.dispose();
+        this.material.dispose();
+        return this;
+    }
+}