three-base 2.0.197 → 2.0.199

package/MktMesh/imagePlane.d.ts

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

package/MktMesh/imagePlane.js

@@ -16,7 +16,10 @@
  *     而是直接 discrad 丢弃」⇒ 默认图与缺图灰两条都已删，没就绪就是透明没有。）
  * - UV 标准 [0,1]²（PlaneGeometry 自带），4 张瓦片按 2×2 象限铺满 ⇒ 不需要投影 shader，也不需要离屏 RT。
  */
-import { Color, DataTexture, FrontSide, Mesh, MeshBasicMaterial, PlaneGeometry, RGBAFormat, Vector4, } from "three";
+import { Color, DataTexture, FrontSide, Mesh, MeshBasicMaterial, PlaneGeometry, RGBAFormat, Vector2, Vector4, } from "three";
+import { LineMaterial } from "three/examples/jsm/lines/LineMaterial.js";
+import { LineSegments2 } from "three/examples/jsm/lines/LineSegments2.js";
+import { LineSegmentsGeometry } from "three/examples/jsm/lines/LineSegmentsGeometry.js";
 /*
  * ⭐ 2026-10-22 晚旨：图片平面**不用拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，
  * 片元按 UV 象限选片 + 用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。
@@ -61,6 +64,9 @@ const IMG_PLANE_MAP_FRAG = `
 const DEFAULT_WIDTH = 2;
 const DEFAULT_HEIGHT = 1.5;
 const HIGHLIGHT_COLOR = "#ffd24a";
+/** 选中边框：颜色/粗细与模型槽那圈 `BoxLine2` 的朝向相机的棱同一档（0x00ff00 / 2 屏幕像素） */
+const SELECT_LINE_COLOR = 0x00ff00;
+const SELECT_LINE_WIDTH_PX = 2;
 export class ImagePlane extends Mesh {
     _originalColor = "#ffffff";
     _uTiles;
@@ -72,6 +78,10 @@ export class ImagePlane extends Mesh {
     };
     /** 内容是否已落定：4 格里至少有一格真的绑上了纹理。**只朝 true 翻一次**（之后逐张显影继续，但不再回退成「没内容」）。 */
     _loaded = false;
+    /** 此刻是不是编辑器的选中态（决定上不上黄、边框亮不亮） */
+    _selected = false;
+    /** 选中边框：懒建（预览/发布那一路从不选中 ⇒ 一颗都不建） */
+    _outline = null;
     constructor(name) {
         const geo = new PlaneGeometry(DEFAULT_WIDTH, DEFAULT_HEIGHT);
         const mat = new MeshBasicMaterial({
@@ -115,6 +125,7 @@ export class ImagePlane extends Mesh {
     setPlaneSize(w, h) {
         this.geometry.dispose();
         this.geometry = new PlaneGeometry(w, h);
+        this._layoutOutline(); // 边框跟着宽高走，否则面板改完尺寸框还停在旧那一圈
     }
     setPlaneData(d) {
         this._data = { url: d.url, tiles: d.tiles, naturalW: d.naturalW, naturalH: d.naturalH };
@@ -125,6 +136,7 @@ export class ImagePlane extends Mesh {
     get naturalH() { return this._data.naturalH; }
     /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 那一片整格 discard，不落像素）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
     setTileTextures(texs, insets) {
+        const hadContent = this._loaded;
         for (let i = 0; i < 4; i++) {
             const t = texs[i] || null;
             this._uTiles.value[i] = t || PLACEHOLDER_TEX;
@@ -136,6 +148,10 @@ export class ImagePlane extends Mesh {
             if (t)
                 this._loaded = true;
         }
+        // 上传前这颗是选中态（黄），第一张图一到就把黄摘掉 ⇒ 否则「有图不上色」只在再次选中时才生效，
+        // 而他报的正是「上传后」那一刻。
+        if (!hadContent && this._loaded)
+            this._syncSelection();
     }
     /** 只读「此刻材质里绑了什么」的戳记：4 格就绪位 + 已绑纹理的版本号。
      *  按需渲染的宿主拿它比对画面：逐帧绑定只写 uniform 值，⛔ 不动 `material.version`、也不动几何 ⇒ 场景指纹看不见这一变。 */
@@ -148,10 +164,66 @@ export class ImagePlane extends Mesh {
         return s;
     }
     highlight() {
-        this.material.color.set(HIGHLIGHT_COLOR);
+        this._selected = true;
+        this._syncSelection();
     }
     restoreColor() {
-        this.material.color.set(this._originalColor);
+        this._selected = false;
+        this._syncSelection();
+    }
+    /**
+     * 选中态的三样东西一起算（颜色 + 边框），一处规则：
+     * - 黄只在**还没上传图**那一档：片元里贴图是乘进 diffuse 的（`diffuseColor *= imgTexel`），有图还套黄 ⇒ 整张图发黄。
+     * - 边框在有图/没图两档都亮：没图那四格是整格 `discard`（一个像素都不落），只靠黄等于没有反馈，看不见也找不着。
+     */
+    _syncSelection() {
+        this.material.color.set(this._selected && !this._loaded ? HIGHLIGHT_COLOR : this._originalColor);
+        if (!this._selected) {
+            if (this._outline)
+                this._outline.visible = false;
+            return;
+        }
+        this._ensureOutline();
+        this._layoutOutline();
+    }
+    /** 选中边框懒建：预览/发布那一路从不选中 ⇒ 一颗 LineSegments2 都不建（与模型槽那圈 `BoxLine2` 同口径） */
+    _ensureOutline() {
+        if (this._outline)
+            return;
+        const material = new LineMaterial({
+            color: SELECT_LINE_COLOR,
+            worldUnits: false,
+            linewidth: SELECT_LINE_WIDTH_PX,
+            // ⚠️ `depthTest: false`：这一圈就躺在平面自己那一平面上，留着深度测试必与图打摆（闪烁）
+            depthTest: false,
+            resolution: new Vector2(1, 1),
+        });
+        const outline = new LineSegments2(new LineSegmentsGeometry(), material);
+        outline.name = `${this.name}-选中边框`;
+        outline.renderOrder = 100; // 与 `BoxLine2` 那圈同档：压在图/墙之后
+        outline.frustumCulled = false;
+        outline.userData.pickIgnored = true;
+        outline.raycast = () => { }; // 拾取打平面本体，边框不是可点的东西
+        outline.onBeforeRender = (renderer) => {
+            renderer.getSize(material.resolution); // 屏幕像素粗细要每帧拿画布尺寸
+        };
+        this.add(outline);
+        this._outline = outline;
+    }
+    /** 四条边按当前几何的宽高铺在平面那一平面上（局部 z=0，中心为原点） */
+    _layoutOutline() {
+        if (!this._outline)
+            return;
+        const w = this.imageWidth / 2;
+        const h = this.imageHeight / 2;
+        const c = [
+            [-w, -h, 0], [w, -h, 0],
+            [w, -h, 0], [w, h, 0],
+            [w, h, 0], [-w, h, 0],
+            [-w, h, 0], [-w, -h, 0],
+        ].flat();
+        this._outline.geometry.setPositions(c);
+        this._outline.visible = true;
     }
     toData() {
         return {
@@ -177,6 +249,10 @@ export class ImagePlane extends Mesh {
     dispose() {
         this.geometry.dispose();
         this.material.dispose();
+        if (this._outline) {
+            this._outline.geometry.dispose();
+            this._outline.material.dispose();
+        }
     }
 }
 export const IMAGE_PLANE_DEFAULTS = { width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT };

package/MktMesh/imagePlane.ts

@@ -25,8 +25,13 @@ import {
     PlaneGeometry,
     RGBAFormat,
     Texture,
+    Vector2,
     Vector4,
+    WebGLRenderer,
 } from "three";
+import { LineMaterial } from "three/examples/jsm/lines/LineMaterial.js";
+import { LineSegments2 } from "three/examples/jsm/lines/LineSegments2.js";
+import { LineSegmentsGeometry } from "three/examples/jsm/lines/LineSegmentsGeometry.js";
 
 /*
  * ⭐ 2026-10-22 晚旨：图片平面**不用拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，
@@ -92,6 +97,9 @@ export interface ImagePlaneData {
 const DEFAULT_WIDTH = 2;
 const DEFAULT_HEIGHT = 1.5;
 const HIGHLIGHT_COLOR = "#ffd24a";
+/** 选中边框：颜色/粗细与模型槽那圈 `BoxLine2` 的朝向相机的棱同一档（0x00ff00 / 2 屏幕像素） */
+const SELECT_LINE_COLOR = 0x00ff00;
+const SELECT_LINE_WIDTH_PX = 2;
 
 export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
     private _originalColor: string = "#ffffff";
@@ -104,6 +112,10 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
     };
     /** 内容是否已落定：4 格里至少有一格真的绑上了纹理。**只朝 true 翻一次**（之后逐张显影继续，但不再回退成「没内容」）。 */
     private _loaded = false;
+    /** 此刻是不是编辑器的选中态（决定上不上黄、边框亮不亮） */
+    private _selected = false;
+    /** 选中边框：懒建（预览/发布那一路从不选中 ⇒ 一颗都不建） */
+    private _outline: LineSegments2 | null = null;
 
     constructor(name?: string) {
         const geo = new PlaneGeometry(DEFAULT_WIDTH, DEFAULT_HEIGHT);
@@ -153,6 +165,7 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
     setPlaneSize(w: number, h: number): void {
         this.geometry.dispose();
         this.geometry = new PlaneGeometry(w, h);
+        this._layoutOutline(); // 边框跟着宽高走，否则面板改完尺寸框还停在旧那一圈
     }
 
     setPlaneData(d: Pick<ImagePlaneData, "url" | "tiles" | "naturalW" | "naturalH">): void {
@@ -166,6 +179,7 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
 
     /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 那一片整格 discard，不落像素）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
     setTileTextures(texs: (Texture | null)[], insets: Vector4[]): void {
+        const hadContent = this._loaded;
         for (let i = 0; i < 4; i++) {
             const t = texs[i] || null;
             this._uTiles.value[i] = t || PLACEHOLDER_TEX;
@@ -175,6 +189,9 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
             // 「逐张就绪逐张显影」是本文件 10-22 晚定下的口径，等到全到齐会让先到的那几格白等几帧）。
             if (t) this._loaded = true;
         }
+        // 上传前这颗是选中态（黄），第一张图一到就把黄摘掉 ⇒ 否则「有图不上色」只在再次选中时才生效，
+        // 而他报的正是「上传后」那一刻。
+        if (!hadContent && this._loaded) this._syncSelection();
     }
 
     /** 只读「此刻材质里绑了什么」的戳记：4 格就绪位 + 已绑纹理的版本号。
@@ -189,11 +206,67 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
     }
 
     highlight(): void {
-        this.material.color.set(HIGHLIGHT_COLOR);
+        this._selected = true;
+        this._syncSelection();
     }
 
     restoreColor(): void {
-        this.material.color.set(this._originalColor);
+        this._selected = false;
+        this._syncSelection();
+    }
+
+    /**
+     * 选中态的三样东西一起算（颜色 + 边框），一处规则：
+     * - 黄只在**还没上传图**那一档：片元里贴图是乘进 diffuse 的（`diffuseColor *= imgTexel`），有图还套黄 ⇒ 整张图发黄。
+     * - 边框在有图/没图两档都亮：没图那四格是整格 `discard`（一个像素都不落），只靠黄等于没有反馈，看不见也找不着。
+     */
+    private _syncSelection(): void {
+        this.material.color.set(this._selected && !this._loaded ? HIGHLIGHT_COLOR : this._originalColor);
+        if (!this._selected) {
+            if (this._outline) this._outline.visible = false;
+            return;
+        }
+        this._ensureOutline();
+        this._layoutOutline();
+    }
+
+    /** 选中边框懒建：预览/发布那一路从不选中 ⇒ 一颗 LineSegments2 都不建（与模型槽那圈 `BoxLine2` 同口径） */
+    private _ensureOutline(): void {
+        if (this._outline) return;
+        const material = new LineMaterial({
+            color: SELECT_LINE_COLOR,
+            worldUnits: false,
+            linewidth: SELECT_LINE_WIDTH_PX,
+            // ⚠️ `depthTest: false`：这一圈就躺在平面自己那一平面上，留着深度测试必与图打摆（闪烁）
+            depthTest: false,
+            resolution: new Vector2(1, 1),
+        });
+        const outline = new LineSegments2(new LineSegmentsGeometry(), material);
+        outline.name = `${this.name}-选中边框`;
+        outline.renderOrder = 100; // 与 `BoxLine2` 那圈同档：压在图/墙之后
+        outline.frustumCulled = false;
+        outline.userData.pickIgnored = true;
+        outline.raycast = (): void => { }; // 拾取打平面本体，边框不是可点的东西
+        outline.onBeforeRender = (renderer: WebGLRenderer): void => {
+            renderer.getSize(material.resolution); // 屏幕像素粗细要每帧拿画布尺寸
+        };
+        this.add(outline);
+        this._outline = outline;
+    }
+
+    /** 四条边按当前几何的宽高铺在平面那一平面上（局部 z=0，中心为原点） */
+    private _layoutOutline(): void {
+        if (!this._outline) return;
+        const w = this.imageWidth / 2;
+        const h = this.imageHeight / 2;
+        const c = [
+            [-w, -h, 0], [w, -h, 0],
+            [w, -h, 0], [w, h, 0],
+            [w, h, 0], [-w, h, 0],
+            [-w, h, 0], [-w, -h, 0],
+        ].flat();
+        this._outline.geometry.setPositions(c);
+        this._outline.visible = true;
     }
 
     toData(): ImagePlaneData {
@@ -221,6 +294,10 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
     dispose(): void {
         this.geometry.dispose();
         this.material.dispose();
+        if (this._outline) {
+            this._outline.geometry.dispose();
+            this._outline.material.dispose();
+        }
     }
 }
 

package/MktMesh/mktResManager.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `MktMesh` 的资源管理器（2026-11-05 需求逐字：「只已经预载入的资源才显示出来, 或者放到 shader 里面去显示出来.
+ *  可以专门写一个资源管理器来管理, 每个 mktmesh 都有自己的一个资源管理器来管理」）。
+ *
+ * 管的是三族资源：全景（32 片拼成左右 2 张槽纹理）、GLB（模型槽）、平面图（4 格瓦片）。
+ * 职责只有两件事：
+ *   ① **推**：`preRender(renderer)` 起一条全局队列链，每 tick 推进一步（全景 = 补下载 → 画已进显存的格 → 传一张新的；
+ *      平面 = 把瓦片交给下载并补排绑定；GLB/平面/墙 = 隐藏期预热那件 1×1 绘制）。
+ *      为什么非得有人推：`visible = false` 时 three 遍历第一句就 `if ( object.visible === false ) return;`
+ *      ⇒ 墙一次都收不到 `onBeforeRender`，藏起来的展厅里那三族本来一帧都不推进（这就是「资源等不到渲染器」的根）。
+ *   ② **记账**：哪一档真的画进过显存。`MktMesh.tickProgressiveReveal` 拿这本账决定一颗平面 / 一槽模型许不许亮
+ *      ⇒ 「已经预载入的才显示出来」落在这一条上（需求第 4 点）。
+ *
+ * ⛔ 本文件不下载、不解码、不 `initTexture`、不建纹理、不拼合、不编译 —— 那几件事各自只有一份实现
+ *   （`./panoTileStitcher` 的三道工序、`./imageTileLoader`、`./modelSlot`、`MktMesh` 的隐藏期预热）。
+ *   这里只经 `MktResHost` 那几只手**点它们**，并把预热报回来的那一档记上账 ⇒ 全工程只此一把「进显存」尺。
+ * ⚠️ 全景「进 shader」那一道闸不在这里：`MktMesh._peekTileAt` 见拼合器 `resident()` 为假就返回 null ⇒ 那一格当帧不绑，
+ *   已由「没进显存不许绑」管住；这里只管**驱动**与**亮出来的那一族**。
+ */
+import type { Object3D, WebGLRenderer } from "three";
+/** 管理器向宿主（一颗 `MktMesh`）要的那几只手 —— 全部是宿主上现成的入口，⛔ 不许在这里另起一套实现。 */
+export interface MktResHost {
+    /** 隐藏期 GPU 预热（一 tick 画一件：program 编译 + 顶点缓冲/纹理首传）；重复点不重建清单 */
+    prewarm(renderer: WebGLRenderer): void;
+    /** 摘牌（进厅 / 退场）：清单作废，晚到的内容不再补排 */
+    stopPrewarm(): void;
+    /** 预热还挂着牌吗（`_warmSeen` 非空且还没 `visible`）⇒ 只有挂着牌，「没进显存先别亮」这道闸才谈得上生效 */
+    prewarming(): boolean;
+    /** 已经亮出来了 ⇒ 每帧由 `onBeforeRender` 自己驱动，本管理器那条链就该停下来不抢额度 */
+    shown(): boolean;
+    /** 全景拼合推进一步（补下载 → 画已进显存的格 → 传一张新的）；⚠️ 必须排在 `prefetchPano` **之前** */
+    pumpPano(renderer: WebGLRenderer): void;
+    /** 把存档前 n 颗全景（`panoPriorityCount`，n = -1 为整份）点名回加载任务队列头部；幂等 */
+    prefetchPano(): void;
+    /** 把整层平面的瓦片地址交给下载并补排「一帧一颗」的绑定；幂等 */
+    feedPlanes(): void;
+}
+/**
+ * 一颗 `MktMesh` 一份（`MktMesh._res`，由构造期注入的 `MktResHost` 绑回宿主）。
+ * 状态机很简单：`preRender` 把链起起来并开闸，链每 tick 推进一步，宿主亮出来（`shown()`）就自停；
+ * 摘牌（`stop()`）同时关掉显示闸 ⇒ 没用过 `preRender` 的宿主行为与改造前逐字一致。
+ */
+export declare class MktResourceManager {
+    private host;
+    /** 宿主交进来的那台渲染器（隐藏期库里自己拿不到 ⇒ 只有 `preRender` 这一路） */
+    private renderer;
+    /** 全景/平面那条链是否还排在 `threeUtils.workList` 里（防重复起链） */
+    private driving;
+    /** `preRender` 点过 ⇒ 显示闸才生效（⛔ 没点过的宿主一律照常放行，不许凭空黑屏） */
+    private armed;
+    /** 对象 → 预热清单里那一档的去重键。键的**算式**只在 `MktMesh._collectWarmItems` 一处，这里只登记结果 */
+    private warmKey;
+    /** 已经真画进显存的那几档（键）⇒ 同一档的第二第三颗也算过了，不必再压 */
+    private warmDrawn;
+    constructor(host: MktResHost);
+    /**
+     * 预载入：拿宿主的渲染器，把「已经准备好的」逐 tick 推进 GPU（需求第 1 点）。
+     * 幂等 ⇒ 隐藏期里宿主每帧点一次、或只点一次都行；换了渲染器再点 ⇒ 拼合器自己会把在册组整份作废（`_switchRenderer`）。
+     */
+    preRender(renderer: WebGLRenderer | null): void;
+    /** 摘牌（宿主进厅 / `MktMesh.dispose`）：链停、闸开、账清；预热交回宿主那句 `stopGpuPrewarm` 去收。 */
+    stop(): void;
+    /** 登记「这一颗对应预热清单里哪一档」（`_collectWarmItems` 收进来那一拍调）。 */
+    noteWarmKey(o: Object3D, key: string): void;
+    /** 记这一档刚刚真画进显存（`_runGpuWarmStep` 画完那一拍调）⇒ 这颗从此许亮。 */
+    markWarmDrawn(o: Object3D): void;
+    /**
+     * 显示闸（需求第 4 点）：这颗平面 / 模型此刻该不该被压着不亮。
+     * 只在「`preRender` 点过 + 预热还挂着牌 + 这一档登记过但还没画过」三条同时成立时才拦；
+     * ⛔ 压根没进过预热清单的一律放行 —— 那属于「还没扫到」，把它当「没进显存」就是永久黑屏。
+     */
+    holdsReveal(o: Object3D): boolean;
+    /** 队列里那一格：推进一步，然后只再排自己下一格（⛔ 不在这里一轮推光）。 */
+    private step;
+    /** 一步里干的三件事，次序固定：先推拼合（第一次拿到渲染器时它把在册组整份作废），再点名，再补排平面绑定。 */
+    private feed;
+}

package/MktMesh/mktResManager.js

@@ -0,0 +1,89 @@
+import threeUtils from "../threeUtils";
+/**
+ * 一颗 `MktMesh` 一份（`MktMesh._res`，由构造期注入的 `MktResHost` 绑回宿主）。
+ * 状态机很简单：`preRender` 把链起起来并开闸，链每 tick 推进一步，宿主亮出来（`shown()`）就自停；
+ * 摘牌（`stop()`）同时关掉显示闸 ⇒ 没用过 `preRender` 的宿主行为与改造前逐字一致。
+ */
+export class MktResourceManager {
+    host;
+    /** 宿主交进来的那台渲染器（隐藏期库里自己拿不到 ⇒ 只有 `preRender` 这一路） */
+    renderer = null;
+    /** 全景/平面那条链是否还排在 `threeUtils.workList` 里（防重复起链） */
+    driving = false;
+    /** `preRender` 点过 ⇒ 显示闸才生效（⛔ 没点过的宿主一律照常放行，不许凭空黑屏） */
+    armed = false;
+    /** 对象 → 预热清单里那一档的去重键。键的**算式**只在 `MktMesh._collectWarmItems` 一处，这里只登记结果 */
+    warmKey = new WeakMap();
+    /** 已经真画进显存的那几档（键）⇒ 同一档的第二第三颗也算过了，不必再压 */
+    warmDrawn = new Set();
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * 预载入：拿宿主的渲染器，把「已经准备好的」逐 tick 推进 GPU（需求第 1 点）。
+     * 幂等 ⇒ 隐藏期里宿主每帧点一次、或只点一次都行；换了渲染器再点 ⇒ 拼合器自己会把在册组整份作废（`_switchRenderer`）。
+     */
+    preRender(renderer) {
+        if (!renderer)
+            return;
+        this.armed = true;
+        this.renderer = renderer;
+        this.host.prewarm(renderer); // GLB / 平面图 / 墙：一 tick 一件，它自己会接着排下一件
+        this.feed(); // 全景 + 平面：先立刻推一步，别让第一格空转
+        if (this.driving)
+            return;
+        this.driving = true;
+        threeUtils.addWork(() => { }); // 占一格 ⇒ 真活落下一 tick，与预热 / 上传 / 绑定同一手法
+        threeUtils.addWork(() => this.step());
+    }
+    /** 摘牌（宿主进厅 / `MktMesh.dispose`）：链停、闸开、账清；预热交回宿主那句 `stopGpuPrewarm` 去收。 */
+    stop() {
+        this.driving = false;
+        this.armed = false;
+        this.renderer = null;
+        this.warmDrawn.clear();
+        this.host.stopPrewarm();
+    }
+    /** 登记「这一颗对应预热清单里哪一档」（`_collectWarmItems` 收进来那一拍调）。 */
+    noteWarmKey(o, key) {
+        this.warmKey.set(o, key);
+    }
+    /** 记这一档刚刚真画进显存（`_runGpuWarmStep` 画完那一拍调）⇒ 这颗从此许亮。 */
+    markWarmDrawn(o) {
+        const key = this.warmKey.get(o);
+        if (key)
+            this.warmDrawn.add(key);
+    }
+    /**
+     * 显示闸（需求第 4 点）：这颗平面 / 模型此刻该不该被压着不亮。
+     * 只在「`preRender` 点过 + 预热还挂着牌 + 这一档登记过但还没画过」三条同时成立时才拦；
+     * ⛔ 压根没进过预热清单的一律放行 —— 那属于「还没扫到」，把它当「没进显存」就是永久黑屏。
+     */
+    holdsReveal(o) {
+        if (!this.armed || !this.host.prewarming())
+            return false;
+        const key = this.warmKey.get(o);
+        return key !== undefined && !this.warmDrawn.has(key);
+    }
+    /** 队列里那一格：推进一步，然后只再排自己下一格（⛔ 不在这里一轮推光）。 */
+    step() {
+        if (!this.driving)
+            return; // `stop()` 已摘牌 ⇒ 这一项作废
+        if (this.host.shown()) { // 亮出来了 ⇒ 交回 `onBeforeRender` 每帧那一路，不再抢额度
+            this.driving = false;
+            return;
+        }
+        this.feed();
+        threeUtils.addWork(() => { });
+        threeUtils.addWork(() => this.step());
+    }
+    /** 一步里干的三件事，次序固定：先推拼合（第一次拿到渲染器时它把在册组整份作废），再点名，再补排平面绑定。 */
+    feed() {
+        const renderer = this.renderer;
+        if (!renderer)
+            return;
+        this.host.pumpPano(renderer);
+        this.host.prefetchPano();
+        this.host.feedPlanes();
+    }
+}

package/MktMesh/mktResManager.ts

@@ -0,0 +1,130 @@
+/**
+ * `MktMesh` 的资源管理器（2026-11-05 需求逐字：「只已经预载入的资源才显示出来, 或者放到 shader 里面去显示出来.
+ *  可以专门写一个资源管理器来管理, 每个 mktmesh 都有自己的一个资源管理器来管理」）。
+ *
+ * 管的是三族资源：全景（32 片拼成左右 2 张槽纹理）、GLB（模型槽）、平面图（4 格瓦片）。
+ * 职责只有两件事：
+ *   ① **推**：`preRender(renderer)` 起一条全局队列链，每 tick 推进一步（全景 = 补下载 → 画已进显存的格 → 传一张新的；
+ *      平面 = 把瓦片交给下载并补排绑定；GLB/平面/墙 = 隐藏期预热那件 1×1 绘制）。
+ *      为什么非得有人推：`visible = false` 时 three 遍历第一句就 `if ( object.visible === false ) return;`
+ *      ⇒ 墙一次都收不到 `onBeforeRender`，藏起来的展厅里那三族本来一帧都不推进（这就是「资源等不到渲染器」的根）。
+ *   ② **记账**：哪一档真的画进过显存。`MktMesh.tickProgressiveReveal` 拿这本账决定一颗平面 / 一槽模型许不许亮
+ *      ⇒ 「已经预载入的才显示出来」落在这一条上（需求第 4 点）。
+ *
+ * ⛔ 本文件不下载、不解码、不 `initTexture`、不建纹理、不拼合、不编译 —— 那几件事各自只有一份实现
+ *   （`./panoTileStitcher` 的三道工序、`./imageTileLoader`、`./modelSlot`、`MktMesh` 的隐藏期预热）。
+ *   这里只经 `MktResHost` 那几只手**点它们**，并把预热报回来的那一档记上账 ⇒ 全工程只此一把「进显存」尺。
+ * ⚠️ 全景「进 shader」那一道闸不在这里：`MktMesh._peekTileAt` 见拼合器 `resident()` 为假就返回 null ⇒ 那一格当帧不绑，
+ *   已由「没进显存不许绑」管住；这里只管**驱动**与**亮出来的那一族**。
+ */
+import type { Object3D, WebGLRenderer } from "three";
+import threeUtils from "../threeUtils";
+
+/** 管理器向宿主（一颗 `MktMesh`）要的那几只手 —— 全部是宿主上现成的入口，⛔ 不许在这里另起一套实现。 */
+export interface MktResHost {
+    /** 隐藏期 GPU 预热（一 tick 画一件：program 编译 + 顶点缓冲/纹理首传）；重复点不重建清单 */
+    prewarm(renderer: WebGLRenderer): void;
+    /** 摘牌（进厅 / 退场）：清单作废，晚到的内容不再补排 */
+    stopPrewarm(): void;
+    /** 预热还挂着牌吗（`_warmSeen` 非空且还没 `visible`）⇒ 只有挂着牌，「没进显存先别亮」这道闸才谈得上生效 */
+    prewarming(): boolean;
+    /** 已经亮出来了 ⇒ 每帧由 `onBeforeRender` 自己驱动，本管理器那条链就该停下来不抢额度 */
+    shown(): boolean;
+    /** 全景拼合推进一步（补下载 → 画已进显存的格 → 传一张新的）；⚠️ 必须排在 `prefetchPano` **之前** */
+    pumpPano(renderer: WebGLRenderer): void;
+    /** 把存档前 n 颗全景（`panoPriorityCount`，n = -1 为整份）点名回加载任务队列头部；幂等 */
+    prefetchPano(): void;
+    /** 把整层平面的瓦片地址交给下载并补排「一帧一颗」的绑定；幂等 */
+    feedPlanes(): void;
+}
+
+/**
+ * 一颗 `MktMesh` 一份（`MktMesh._res`，由构造期注入的 `MktResHost` 绑回宿主）。
+ * 状态机很简单：`preRender` 把链起起来并开闸，链每 tick 推进一步，宿主亮出来（`shown()`）就自停；
+ * 摘牌（`stop()`）同时关掉显示闸 ⇒ 没用过 `preRender` 的宿主行为与改造前逐字一致。
+ */
+export class MktResourceManager {
+    private host: MktResHost;
+    /** 宿主交进来的那台渲染器（隐藏期库里自己拿不到 ⇒ 只有 `preRender` 这一路） */
+    private renderer: WebGLRenderer | null = null;
+    /** 全景/平面那条链是否还排在 `threeUtils.workList` 里（防重复起链） */
+    private driving = false;
+    /** `preRender` 点过 ⇒ 显示闸才生效（⛔ 没点过的宿主一律照常放行，不许凭空黑屏） */
+    private armed = false;
+    /** 对象 → 预热清单里那一档的去重键。键的**算式**只在 `MktMesh._collectWarmItems` 一处，这里只登记结果 */
+    private warmKey = new WeakMap<Object3D, string>();
+    /** 已经真画进显存的那几档（键）⇒ 同一档的第二第三颗也算过了，不必再压 */
+    private warmDrawn = new Set<string>();
+
+    constructor(host: MktResHost) {
+        this.host = host;
+    }
+
+    /**
+     * 预载入：拿宿主的渲染器，把「已经准备好的」逐 tick 推进 GPU（需求第 1 点）。
+     * 幂等 ⇒ 隐藏期里宿主每帧点一次、或只点一次都行；换了渲染器再点 ⇒ 拼合器自己会把在册组整份作废（`_switchRenderer`）。
+     */
+    preRender(renderer: WebGLRenderer | null): void {
+        if (!renderer) return;
+        this.armed = true;
+        this.renderer = renderer;
+        this.host.prewarm(renderer); // GLB / 平面图 / 墙：一 tick 一件，它自己会接着排下一件
+        this.feed(); // 全景 + 平面：先立刻推一步，别让第一格空转
+        if (this.driving) return;
+        this.driving = true;
+        threeUtils.addWork(() => {}); // 占一格 ⇒ 真活落下一 tick，与预热 / 上传 / 绑定同一手法
+        threeUtils.addWork(() => this.step());
+    }
+
+    /** 摘牌（宿主进厅 / `MktMesh.dispose`）：链停、闸开、账清；预热交回宿主那句 `stopGpuPrewarm` 去收。 */
+    stop(): void {
+        this.driving = false;
+        this.armed = false;
+        this.renderer = null;
+        this.warmDrawn.clear();
+        this.host.stopPrewarm();
+    }
+
+    /** 登记「这一颗对应预热清单里哪一档」（`_collectWarmItems` 收进来那一拍调）。 */
+    noteWarmKey(o: Object3D, key: string): void {
+        this.warmKey.set(o, key);
+    }
+
+    /** 记这一档刚刚真画进显存（`_runGpuWarmStep` 画完那一拍调）⇒ 这颗从此许亮。 */
+    markWarmDrawn(o: Object3D): void {
+        const key = this.warmKey.get(o);
+        if (key) this.warmDrawn.add(key);
+    }
+
+    /**
+     * 显示闸（需求第 4 点）：这颗平面 / 模型此刻该不该被压着不亮。
+     * 只在「`preRender` 点过 + 预热还挂着牌 + 这一档登记过但还没画过」三条同时成立时才拦；
+     * ⛔ 压根没进过预热清单的一律放行 —— 那属于「还没扫到」，把它当「没进显存」就是永久黑屏。
+     */
+    holdsReveal(o: Object3D): boolean {
+        if (!this.armed || !this.host.prewarming()) return false;
+        const key = this.warmKey.get(o);
+        return key !== undefined && !this.warmDrawn.has(key);
+    }
+
+    /** 队列里那一格：推进一步，然后只再排自己下一格（⛔ 不在这里一轮推光）。 */
+    private step(): void {
+        if (!this.driving) return; // `stop()` 已摘牌 ⇒ 这一项作废
+        if (this.host.shown()) { // 亮出来了 ⇒ 交回 `onBeforeRender` 每帧那一路，不再抢额度
+            this.driving = false;
+            return;
+        }
+        this.feed();
+        threeUtils.addWork(() => {});
+        threeUtils.addWork(() => this.step());
+    }
+
+    /** 一步里干的三件事，次序固定：先推拼合（第一次拿到渲染器时它把在册组整份作废），再点名，再补排平面绑定。 */
+    private feed(): void {
+        const renderer = this.renderer;
+        if (!renderer) return;
+        this.host.pumpPano(renderer);
+        this.host.prefetchPano();
+        this.host.feedPlanes();
+    }
+}

package/MktMesh/modelSlot.d.ts

@@ -1,4 +1,6 @@
 import { Group } from "three";
+/** glb 地址 → 文件名（日志唯一口径：去掉查询串取最后一段；⛔ 别在打印点各写一份 split） */
+export declare function glbFileName(url: string): string;
 /** 模型槽的持久化数据（进 exportData / importData / 预览 loadData） */
 export interface ModelSlotData {
     name?: string;

package/MktMesh/modelSlot.js

@@ -32,6 +32,10 @@ import { Box3, BoxGeometry, Color, Group, Mesh, MeshBasicMaterial, Vector3, } fr
 import threeLoader from "../threeLoader";
 import threeUtils from "../threeUtils";
 import BoxLine2 from "./boxLine2";
+/** glb 地址 → 文件名（日志唯一口径：去掉查询串取最后一段；⛔ 别在打印点各写一份 split） */
+export function glbFileName(url) {
+    return url.split("?")[0].split("/").pop() || url;
+}
 /** 占位小立方体的棱长（米）—— 皇上要的是「小立方体」，比「加立方体」那颗 1m 的单位方块小一档 */
 export const MODEL_SLOT_PLACEHOLDER = 0.3;
 /** 默认尺寸档（米，最长边）：还没上传模型时占位方块用不上它；上传成功后 `useNativeSize()` 会把它填成模型原最长边 ⇒ 一比一 */
@@ -179,6 +183,9 @@ export class ModelSlot extends Group {
             this._loaded = true;
             return true;
         }
+        // 用户 2026-11-04「日志少打印点吧」⇒ 这一颗的取回入口⛔ 不出声：整层重建一次几十颗，逐颗一行会刷屏。
+        //   文件名改由两个批次入口各打一条 —— 单颗动作（上传/复制/换地址）在下面的 `setModelUrl`，
+        //   整层重建在 `MktMesh.setModels`（那边一条列全）⇒ 一颗不落，但一拍一条。
         // 取回失败（404 / 解析报错都从这一档走）：`threeLoader.loadModel` 是会 reject 的，⚠️ 必须当「落定在占位方块」处理
         //   —— 整层重建时这一颗是压着不亮的，不落定就永远隐形（旧写法里它至少还露得出占位方块）。
         let obj;
@@ -224,6 +231,11 @@ export class ModelSlot extends Group {
      * @returns 是否真的挂上了（地址无效/载入失败/这次结果已作废 ⇒ false；空地址 = 退回占位，返回 true）
      */
     async setModelUrl(url) {
+        // 用户 2026-11-04「日志少打印点吧」⇒ 逐颗一行从 `loadModel` 挪到这里：这一路一次动作只动一/几颗
+        //   （上传 .glb、复制模型、换同名 glb），一条就是他能对上号的那一颗；整层重建那几十颗由
+        //   `MktMesh.setModels` 攒成一条 ⇒ 文件名仍「一颗不落」，行数从 N 降到 1。空地址 = 退回占位，不打。
+        if (url)
+            console.log(`[MktMesh] 加载 glb「${this.name}」：${glbFileName(url)}`);
         if (!(await this.loadModel(url)))
             return false;
         if (this._staged)