three-base 2.0.190 → 2.0.192

package/MeshBase.ts

@@ -1,257 +1,301 @@
-/*
- * @Author: xiaosihan
- * @Date: 2022-02-24 22:49:42
- * @Last Modified by: xiaosihan
- * @Last Modified time: 2025-06-25
- */
-import { AnimationAction, AnimationClip, AnimationMixer, Clock, Group, Mesh, Object3D, Vector3 } from "three";
-import threeUtils from "./threeUtils";
-import threeLoader from "./threeLoader";
-import * as SkeletonUtils from "three/examples/jsm/utils/SkeletonUtils";
-import { isString } from "lodash";
-import { dispatchCustomEvent } from "./EventMap";
-
-// 模型基类
-export default class MeshBase extends Group {
-    constructor(url?: string) {
-        super();
-        url && this.loadModel(url);
-    }
-
-    url: string = "";
-    // 模型对象
-    static models: Map<string, Object3D> = new Map();
-    // 模型是否在加载中
-    static loadModeling: Map<string, boolean> = new Map();
-    // 加载完成
-    loaded: boolean = false;
-    // 是否有动画
-    hasAnimation: boolean = false;
-    //动画混合器
-    mixer?: AnimationMixer;
-    //动画剪辑对象数组
-    animationActions: {
-        [key: string]: AnimationAction;
-    } = {};
-    // 获取文件名的后缀
-    getSuffix(filename: string): string {
-        const match = filename.match(/\.([^\.]+)$/);
-        return match ? match[1].toLowerCase() : "";
-    }
-    reset(...object: Object3D[]): this {
-        threeUtils.dipose(this);
-        for (const child of this.children) {
-            child.parent = null;
-        }
-        for (const item of object) {
-            this.add(item);
-        }
-        return this;
-    }
-    // 兜底：为缺失顶点法线的几何体计算法线。
-    // 某些 glb/stl 模型仅有 POSITION 没有 NORMAL（如 public/models/bottle.glb），
-    // 会让法线 pass 输出零向量 -> AO 算出 NaN -> 整片被乘黑，且 PBR 金属材质无法正确受光 -> 发黑。
-    // 在加载完成后统一兜底，保证光照与 AO 都正确；已含法线的模型不受影响。
-    protected ensureNormals(root: Object3D): void {
-        root.traverse((obj) => {
-            if (obj instanceof Mesh && obj.geometry && !obj.geometry.getAttribute("normal")) {
-                obj.geometry.computeVertexNormals();
-            }
-        });
-    }
-    // 如果url 是blob地址的话,就用suffix字段来制定模型的类型
-    async loadModel(url: string | File | Array<File>, filename: string = ""): Promise<void> {
-        //获取模型文件的地址
-        const modelurl = await (async (): Promise<string> => {
-            if (isString(url)) {
-                return url;
-            }
-            else if (url instanceof File) {
-                return url.name;
-            }
-            else if (url instanceof Array) {
-                let modelurl = "";
-                const suffixs = [
-                    "zip",
-                    "obj",
-                    "glb",
-                    "gltf",
-                    "fbx",
-                    "dae",
-                    "stl",
-                    "usdz",
-                ];
-                for (let file of url) {
-                    if (suffixs.includes(threeUtils.getSuffix(file.name))) {
-                        modelurl = file.name;
-                    }
-                }
-                return modelurl;
-            }
-            return "";
-        })();
-        this.url = modelurl || "";
-        if (!modelurl) {
-            return;
-        }
-        this.loaded = false;
-        // 没有模型并且没有加载任务时就去加载模型
-        if (!MeshBase.models.get(modelurl) &&
-            !MeshBase.loadModeling.get(modelurl)) {
-            MeshBase.loadModeling.set(modelurl, true);
-            // 万能加载器
-            let modal = await threeLoader.loadModel(url, filename);
-            MeshBase.models.set(modelurl, modal);
-            MeshBase.loadModeling.set(modelurl, false);
-        }
-        // 如果模型还在加载中, 就等待模型加载完成
-        do {
-            await new Promise((resolve) => setTimeout(resolve, 50));
-        } while (MeshBase.loadModeling.get(modelurl));
-        if (MeshBase.models.get(modelurl)) {
-            const mesh = MeshBase.models.get(modelurl)!;
-            // 兜底：为缺失顶点法线的几何体补算法线。某些 glb/stl 模型只有 POSITION，
-            // 没有 NORMAL，会导致：① 法线 pass 输出零向量 -> AO 算出 NaN -> 整片被乘黑；
-            // ② PBR 金属材质无法正确光照 -> 颜色发黑。统一在加载后兜底，光照与 AO 都正确。
-            this.ensureNormals(mesh);
-            // 判断是否有动画
-            this.hasAnimation = (mesh as Group & { animations: AnimationClip[] }).animations.length > 0;
-            if (this.hasAnimation) {
-                const model = SkeletonUtils.clone(mesh);
-                this.mixer = new AnimationMixer(model);
-                this.animationActions = {};
-                (mesh as Group & { animations: AnimationClip[] }).animations.map((animation: AnimationClip) => {
-                    const animationAction = this.mixer!.clipAction(animation).play();
-                    animationAction.weight = 0;
-                    this.animationActions[animation.name] = animationAction;
-                });
-                this.reset(model);
-            }
-            else {
-                this.reset(mesh.clone(true));
-            }
-        }
-        // ⭐ 2026-10-09 皇上旨：走 threeUtils 公共 rAF 链，不再另起独立 rAF 回调
-        await threeUtils.waitNextFrame();
-        this.loaded = true;
-        // 加载完成事件
-        dispatchCustomEvent(this, { type: "loaded" });
-    }
-    // 超出绘制区域时不绘制
-    frustumCulled: boolean = false;
-    // 创建阴影
-    castShadow: boolean = false;
-    // 接受阴影
-    receiveShadow: boolean = false;
-    // promise.resole 队列
-    resoles: Array<(value: void | PromiseLike<void>) => void> = [];
-    // 等待加载加载完成
-    async awaitLoaded(): Promise<void> {
-        if (!this.loaded) {
-            await new Promise<void>((resolve) => {
-                if (this.resoles.length === 0) {
-                    (async () => {
-                        while (!this.loaded) {
-                            //⭐ 2026-10-09 皇上旨「整条 rAF 链只走 threeUtils 一条」：
-                            //   原生 rAF 是**独立于主循环的另一个回调**，同一帧并行跑；
-                            //   模型多时（十几个 GLB 同时 awaitLoaded）每帧多十几个回调 ⇒ 卡顿。
-                            await threeUtils.waitNextFrame();
-                        }
-                        while (this.resoles.length > 0) {
-                            const resole = this.resoles.pop();
-                            resole && resole();
-                        }
-                    })();
-                }
-                this.resoles.unshift(resolve);
-            });
-        }
-    }
-    //遍历模型
-    async traverseMesh(callback: (mesh: Mesh) => void): Promise<void> {
-        // 等待加载完成
-        await this.awaitLoaded();
-        this.traverse((obj) => {
-            if (obj instanceof Mesh) {
-                callback(obj);
-            }
-        });
-    }
-    clock: Clock = new Clock();
-    //设置动画的权重
-    async setClipActionWeight(weights: {
-        [key: string]: number;
-    } = {}): Promise<void> {
-        // 等待加载完成
-        await this.awaitLoaded();
-        for (let key in this.animationActions) {
-            this.animationActions[key].weight = weights[key] || 0;
-        }
-    }
-    //获取动画列表
-    getAnimas(): string[] {
-        return Object.keys(this.animationActions);
-    }
-    //播放指定动画
-    setAnimas(anima: string = ""): void {
-        this.setClipActionWeight({ [anima]: 1 });
-    }
-    //停止所有动画
-    stop(): void {
-        this.setClipActionWeight();
-    }
-    updateMatrix(): void {
-        //播放动画
-        if (this.mixer) {
-            this.mixer.update(this.clock.getDelta());
-        }
-        // 深度应用属性
-        this.traverse((obj) => {
-            if (obj instanceof Mesh) {
-                obj.frustumCulled = this.frustumCulled;
-                obj.castShadow = this.castShadow;
-                obj.receiveShadow = this.receiveShadow;
-            }
-        });
-        super.updateMatrix();
-    }
-    // 获取模型的尺寸
-    async getSize(): Promise<Vector3> {
-        await this.awaitLoaded();
-        return threeUtils.getSize(this);
-    }
-    // 居中
-    async center(): Promise<void> {
-        await this.awaitLoaded();
-        threeUtils.center(this);
-    }
-    //底对齐
-    async alignBottom(y: number = 0): Promise<void> {
-        await this.awaitLoaded();
-        threeUtils.alignBottom(this, y);
-    }
-    // 放大到指定尺寸
-    async scaleTo(size: number = 1, key: Array<"x" | "y" | "z"> = ["x", "y", "z"]): Promise<void> {
-        await this.awaitLoaded();
-        threeUtils.scaleTo(this, size, key);
-    }
-    //按照法线拓展
-    expandBynormal(length: number): void {
-        this.traverseMesh((mesh) => {
-            // 没有法线就计算法线
-            mesh.geometry = mesh.geometry.clone();
-            if (!mesh.geometry.getAttribute("normal")) {
-                mesh.geometry.computeVertexNormals();
-            }
-            const normal = mesh.geometry.getAttribute("normal");
-            const position = mesh.geometry.getAttribute("position");
-            const v3 = new Vector3(0, 0, 0);
-            for (let i = 0; i < position.count; i++) {
-                v3.set(normal.getX(i), normal.getY(i), normal.getZ(i));
-                v3.setLength(length);
-                position.setXYZ(i, position.getX(i) + v3.x, position.getY(i) + v3.y, position.getZ(i) + v3.z);
-            }
-            position.needsUpdate = true;
-        });
-    }
-}
+/*
+ * @Author: xiaosihan
+ * @Date: 2022-02-24 22:49:42
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2025-06-25
+ */
+import { AnimationAction, AnimationClip, AnimationMixer, Clock, Group, Mesh, Object3D, Vector3 } from "three";
+import threeUtils from "./threeUtils";
+import threeLoader from "./threeLoader";
+import * as SkeletonUtils from "three/examples/jsm/utils/SkeletonUtils";
+import { isString } from "lodash";
+import { dispatchCustomEvent } from "./EventMap";
+
+// 模型基类
+export default class MeshBase extends Group {
+    constructor(url?: string) {
+        super();
+        url && this.loadModel(url);
+    }
+
+    url: string = "";
+    // 模型对象
+    static models: Map<string, Object3D> = new Map();
+    // 模型是否在加载中
+    static loadModeling: Map<string, boolean> = new Map();
+    // 加载完成
+    loaded: boolean = false;
+    // 是否有动画
+    hasAnimation: boolean = false;
+    //动画混合器
+    mixer?: AnimationMixer;
+    //动画剪辑对象数组
+    animationActions: {
+        [key: string]: AnimationAction;
+    } = {};
+    // 获取文件名的后缀
+    getSuffix(filename: string): string {
+        const match = filename.match(/\.([^\.]+)$/);
+        return match ? match[1].toLowerCase() : "";
+    }
+    reset(...object: Object3D[]): this {
+        threeUtils.dipose(this);
+        for (const child of this.children) {
+            child.parent = null;
+        }
+        for (const item of object) {
+            this.add(item);
+        }
+        return this;
+    }
+    /** 「压着等放行」的内容子对象在册表（摘牌 = 从这里删掉，放行那一拍便不再写它的 `visible`） */
+    private readonly _revealPending = new Set<Object3D>();
+    /**
+     * ⭐ 2026-10-28「这个方案也可以用在 MeshBase 对象上面，让每个模型对象都逐帧显示出来，就不用一起阻塞了」：
+     *   刚进场景图的这几颗内容先压住，再交给 `threeUtils` 的全局队列 —— 那一拍每帧只跑一项
+     *   （`requestAnimationFrame()` 里 `workList.splice(0, 1)`），且派发点在渲染之后 ⇒ 一帧只放行一个对象，
+     *   它下一帧才被真画出来。几十只模型同时落地时，「顶点缓冲上传 + 首次 program 编译」（都发生在真被画的
+     *   那一帧）就摊到几十帧上，不再是进门那一下的一整卡。
+     * ⚠️ 压的是**内容子对象**的 `visible`，⛔ 不是 MeshBase 自己：`ManyModelGroup.setDatas` 拿 MeshBase 的
+     *   `visible` 当「这条数据还在不在」的筛子 ⇒ 那个旋钮归消费者，这里不许占用。
+     * ⚠️ 只压「这一次新加进来的」那几颗 ⇒ 换模型（`reset`）时不会把旁边早已点亮的内容一起按下去。
+     * ⚠️ ⛔ 别改成「每颗在自己的 `onBeforeRender` 里轮询 loaded」：three 的 `projectObject` 第一句就是
+     *   `if (object.visible === false) return;`（`node_modules/three/build/three.module.js:29837`）⇒
+     *   隐形对象一次回调都收不到，自己等自己 = 永远不亮。
+     * ⚠️ `visible` 是业务的旋钮，这里只是**借一下**：进场时就压着的那几颗⛔ 不收进这一轮（不替别人放开）；
+     *   要在放行之前接管某颗，调 `releaseReveal(item)` 摘牌 ⇒ 放行那一拍跳过它，`visible` 归调用方。
+     */
+    protected revealSoon(items: Object3D[]): void {
+        const held: Object3D[] = [];
+        for (const item of items) {
+            if (!item.visible) continue; // 本来就压着 ⇒ 显隐归业务，⛔ 不收进这一轮、也不替它放开
+            item.visible = false;
+            this._revealPending.add(item);
+            held.push(item);
+        }
+        if (!held.length) return;
+        threeUtils.addWork(() => {
+            for (const item of held) {
+                if (!this._revealPending.delete(item)) continue; // 已被摘牌 ⇒ 这一拍不碰它的 visible
+                item.visible = true;
+            }
+        });
+    }
+
+    /**
+     * 把某颗内容的显隐控制权交回调用方（2026-10-28：`visible` 上有业务在用，加载窗口期内写的那一笔⛔ 不能被
+     * 放行那一拍覆盖）。摘牌后它**仍是压着的**（`false`），要它可见就自己写 `true`。
+     */
+    releaseReveal(item: Object3D): void {
+        this._revealPending.delete(item);
+    }
+    // 兜底：为缺失顶点法线的几何体计算法线。
+    // 某些 glb/stl 模型仅有 POSITION 没有 NORMAL（如 public/models/bottle.glb），
+    // 会让法线 pass 输出零向量 -> AO 算出 NaN -> 整片被乘黑，且 PBR 金属材质无法正确受光 -> 发黑。
+    // 在加载完成后统一兜底，保证光照与 AO 都正确；已含法线的模型不受影响。
+    protected ensureNormals(root: Object3D): void {
+        root.traverse((obj) => {
+            if (obj instanceof Mesh && obj.geometry && !obj.geometry.getAttribute("normal")) {
+                obj.geometry.computeVertexNormals();
+            }
+        });
+    }
+    // 如果url 是blob地址的话,就用suffix字段来制定模型的类型
+    async loadModel(url: string | File | Array<File>, filename: string = ""): Promise<void> {
+        //获取模型文件的地址
+        const modelurl = await (async (): Promise<string> => {
+            if (isString(url)) {
+                return url;
+            }
+            else if (url instanceof File) {
+                return url.name;
+            }
+            else if (url instanceof Array) {
+                let modelurl = "";
+                const suffixs = [
+                    "zip",
+                    "obj",
+                    "glb",
+                    "gltf",
+                    "fbx",
+                    "dae",
+                    "stl",
+                    "usdz",
+                ];
+                for (let file of url) {
+                    if (suffixs.includes(threeUtils.getSuffix(file.name))) {
+                        modelurl = file.name;
+                    }
+                }
+                return modelurl;
+            }
+            return "";
+        })();
+        this.url = modelurl || "";
+        if (!modelurl) {
+            return;
+        }
+        this.loaded = false;
+        // 没有模型并且没有加载任务时就去加载模型
+        if (!MeshBase.models.get(modelurl) &&
+            !MeshBase.loadModeling.get(modelurl)) {
+            MeshBase.loadModeling.set(modelurl, true);
+            // 万能加载器
+            let modal = await threeLoader.loadModel(url, filename);
+            MeshBase.models.set(modelurl, modal);
+            MeshBase.loadModeling.set(modelurl, false);
+        }
+        // 如果模型还在加载中, 就等待模型加载完成
+        do {
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        } while (MeshBase.loadModeling.get(modelurl));
+        if (MeshBase.models.get(modelurl)) {
+            const mesh = MeshBase.models.get(modelurl)!;
+            // 兜底：为缺失顶点法线的几何体补算法线。某些 glb/stl 模型只有 POSITION，
+            // 没有 NORMAL，会导致：① 法线 pass 输出零向量 -> AO 算出 NaN -> 整片被乘黑；
+            // ② PBR 金属材质无法正确光照 -> 颜色发黑。统一在加载后兜底，光照与 AO 都正确。
+            this.ensureNormals(mesh);
+            // 判断是否有动画
+            this.hasAnimation = (mesh as Group & { animations: AnimationClip[] }).animations.length > 0;
+            if (this.hasAnimation) {
+                const model = SkeletonUtils.clone(mesh);
+                this.mixer = new AnimationMixer(model);
+                this.animationActions = {};
+                (mesh as Group & { animations: AnimationClip[] }).animations.map((animation: AnimationClip) => {
+                    const animationAction = this.mixer!.clipAction(animation).play();
+                    animationAction.weight = 0;
+                    this.animationActions[animation.name] = animationAction;
+                });
+                this.reset(model);
+                this.revealSoon([model]);
+            }
+            else {
+                const clone = mesh.clone(true);
+                this.reset(clone);
+                this.revealSoon([clone]);
+            }
+        }
+        // ⭐ 2026-10-09 皇上旨：走 threeUtils 公共 rAF 链，不再另起独立 rAF 回调
+        await threeUtils.waitNextFrame();
+        this.loaded = true;
+        // 加载完成事件
+        dispatchCustomEvent(this, { type: "loaded" });
+    }
+    // 超出绘制区域时不绘制
+    frustumCulled: boolean = false;
+    // 创建阴影
+    castShadow: boolean = false;
+    // 接受阴影
+    receiveShadow: boolean = false;
+    // promise.resole 队列
+    resoles: Array<(value: void | PromiseLike<void>) => void> = [];
+    // 等待加载加载完成
+    async awaitLoaded(): Promise<void> {
+        if (!this.loaded) {
+            await new Promise<void>((resolve) => {
+                if (this.resoles.length === 0) {
+                    (async () => {
+                        while (!this.loaded) {
+                            //⭐ 2026-10-09 皇上旨「整条 rAF 链只走 threeUtils 一条」：
+                            //   原生 rAF 是**独立于主循环的另一个回调**，同一帧并行跑；
+                            //   模型多时（十几个 GLB 同时 awaitLoaded）每帧多十几个回调 ⇒ 卡顿。
+                            await threeUtils.waitNextFrame();
+                        }
+                        while (this.resoles.length > 0) {
+                            const resole = this.resoles.pop();
+                            resole && resole();
+                        }
+                    })();
+                }
+                this.resoles.unshift(resolve);
+            });
+        }
+    }
+    //遍历模型
+    async traverseMesh(callback: (mesh: Mesh) => void): Promise<void> {
+        // 等待加载完成
+        await this.awaitLoaded();
+        this.traverse((obj) => {
+            if (obj instanceof Mesh) {
+                callback(obj);
+            }
+        });
+    }
+    clock: Clock = new Clock();
+    //设置动画的权重
+    async setClipActionWeight(weights: {
+        [key: string]: number;
+    } = {}): Promise<void> {
+        // 等待加载完成
+        await this.awaitLoaded();
+        for (let key in this.animationActions) {
+            this.animationActions[key].weight = weights[key] || 0;
+        }
+    }
+    //获取动画列表
+    getAnimas(): string[] {
+        return Object.keys(this.animationActions);
+    }
+    //播放指定动画
+    setAnimas(anima: string = ""): void {
+        this.setClipActionWeight({ [anima]: 1 });
+    }
+    //停止所有动画
+    stop(): void {
+        this.setClipActionWeight();
+    }
+    updateMatrix(): void {
+        //播放动画
+        if (this.mixer) {
+            this.mixer.update(this.clock.getDelta());
+        }
+        // 深度应用属性
+        this.traverse((obj) => {
+            if (obj instanceof Mesh) {
+                obj.frustumCulled = this.frustumCulled;
+                obj.castShadow = this.castShadow;
+                obj.receiveShadow = this.receiveShadow;
+            }
+        });
+        super.updateMatrix();
+    }
+    // 获取模型的尺寸
+    async getSize(): Promise<Vector3> {
+        await this.awaitLoaded();
+        return threeUtils.getSize(this);
+    }
+    // 居中
+    async center(): Promise<void> {
+        await this.awaitLoaded();
+        threeUtils.center(this);
+    }
+    //底对齐
+    async alignBottom(y: number = 0): Promise<void> {
+        await this.awaitLoaded();
+        threeUtils.alignBottom(this, y);
+    }
+    // 放大到指定尺寸
+    async scaleTo(size: number = 1, key: Array<"x" | "y" | "z"> = ["x", "y", "z"]): Promise<void> {
+        await this.awaitLoaded();
+        threeUtils.scaleTo(this, size, key);
+    }
+    //按照法线拓展
+    expandBynormal(length: number): void {
+        this.traverseMesh((mesh) => {
+            // 没有法线就计算法线
+            mesh.geometry = mesh.geometry.clone();
+            if (!mesh.geometry.getAttribute("normal")) {
+                mesh.geometry.computeVertexNormals();
+            }
+            const normal = mesh.geometry.getAttribute("normal");
+            const position = mesh.geometry.getAttribute("position");
+            const v3 = new Vector3(0, 0, 0);
+            for (let i = 0; i < position.count; i++) {
+                v3.set(normal.getX(i), normal.getY(i), normal.getZ(i));
+                v3.setLength(length);
+                position.setXYZ(i, position.getX(i) + v3.x, position.getY(i) + v3.y, position.getZ(i) + v3.z);
+            }
+            position.needsUpdate = true;
+        });
+    }
+}

package/MktMesh/MktMesh.d.ts

@@ -147,6 +147,20 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      * 一帧只有一颗进 `_contentRoot`（进图那一拍要重算包围盒 + 排布 + 首次把几何送上 GPU）。
      */
     private _modelMountQueued;
+    /**
+     * 「压着不亮、等内容落定后一帧放一颗」的在册表（2026-10-28 需求：进展厅时平面图与 GLB 全在同几帧里
+     * 首次送 GPU —— 顶点缓冲上传 + program 编译都在「亮出来的那一帧」，几十颗挤一起就是那一下卡）。
+     *
+     * ⚠️ 为什么闸口在**本对象的 `onBeforeRender`**、不在这颗平面/模型自己的：three 遍历场景图的第一句就是
+     *   `if ( object.visible === false ) return;`（`node_modules/three/build/three.module.js:29837`），
+     *   它和整棵子树当帧直接跳过 ⇒ 隐形对象**一次都不会**收到 `onBeforeRender`，挂在自己身上 = 永远不亮。
+     *   墙（本对象）每帧都进渲染列表，所以闸口设在这座上，在册表里逐帧放行。
+     * ⚠️ 单颗新增那两路（编辑态双击落点 / 复制 / 上传）⛔ 不进这张表 —— 刚加的东西必须当场看得见。
+     * ⚠️ `visible` 本是业务的旋钮，这里只是**借一帧**：整层重建那两路的对象是当场新建的（默认可见），所以进表前
+     *    不需要再看它一眼；但**放行那一拍之前**要接管某颗的显隐，必须调 `releaseReveal(o)` 摘牌，
+     *    否则它会在轮到自身那一帧被写回可见（`boolean` 只有一个位，放行那里分不出这笔是谁写的）。
+     */
+    private _revealPending;
     constructor(opts?: {
         wallHeight?: number;
         wallClosed?: boolean;
@@ -327,10 +341,17 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     addImagePlane(ip: ImagePlane): ImagePlane;
     /** 摘掉一颗并释放它自己的几何/材质；那 4 张瓦片纹理归 `_imgTileLoader` 管 ⇒ ⛔ 不在这里 dispose */
     removeImagePlane(ip: ImagePlane): void;
-    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用） */
+    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用）：⛔ 不压点亮 —— 刚加的必须当场看得见 */
     addModel(ms: ModelSlot): ModelSlot;
     /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾；排在后头的挂载帧靠「不在册」早退） */
     removeModel(ms: ModelSlot): void;
+    /** 出「逐帧点亮」那张在册表（删除 / 整层重建旧的一批都走这里，⛔ 不许留已经 dispose 的对象） */
+    private _dropReveal;
+    /**
+     * 把某颗平面/模型的显隐控制权交回调用方（2026-10-28：`visible` 上有业务在用，点亮那一拍⛔ 不能覆盖
+     * 放行之前写下的那一笔）。摘牌后它**仍是压着的**（整层重建那一路进来就是 `false`），要它可见就自己写 `true`。
+     */
+    releaseReveal(o: ImagePlane | ModelSlot): void;
     /**
      * 整层重建图片平面（`importData` 与预览那一路）。
      * ⚠️ 进来的地址必须是**已补回域名**的绝对形态：补域名只有 `importData` 那一处（与 `textures` 同一把 `assetUrl` 尺），
@@ -344,6 +365,9 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      * 2026-10-26 决定：取回与「挂进父元素」分两拍 —— 地址一次性全交给下载（网络 + 解析不占渲染帧），
      *   真正进场景图那一步交给 `threeUtils.addWork` ⇒ 全局 rAF 每拍只跑一项 = **一帧只挂一颗槽**
      *   （挂载那一拍要重算包围盒 + 排布 + 首次把整棵子树的几何送上 GPU，十几颗挤在同一帧就是他要拆掉的那一卡）。
+     * 2026-10-28 再加第三拍「点亮」：挂载那一拍走的是 setTimeout 链，主线程被几十次 GLB 解析压住时渲染帧会滞后，
+     *   于是好几颗在同一记 render 里首次上 GPU ⇒ 整层重建出来的槽先压着不亮，由 `tickProgressiveReveal`
+     *   **一帧只放一颗**（那一下顶点缓冲上传 + program 编译才真正摊到 N 帧上）。单颗那两路（落点新增 / 复制 / 上传）不受这一拍管。
      */
     setModels(datas: ModelSlotData[], onEachLoad?: () => void): void;
     /** 把「备好待挂」的那一槽交给全局队列；⛔ 去重闸门自备（`addWork` 按闭包引用判重，新闭包它判不出来） */
@@ -365,6 +389,15 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     private _queueImagePlaneBind;
     /** 队列里的一格：只绑**这一颗**平面里已就绪的那几格；还有在途的就重新排队，⛔ 不在这里等、也⛔ 不顺手把别的平面一起做完。 */
     private _bindImagePlaneStep;
+    /**
+     * 逐帧点亮：每帧从在册表里放行**一颗**（内容已落定的第一颗），亮完就把这一颗出册。
+     * ⚠️ 一记只放一颗 ⇒ 顶点缓冲上传与首次 program 编译被摊到 N 帧，而不是同几帧里全上（那一下卡）。
+     * ⚠️ 由 `onBeforeRender` 每帧调（编辑态那份在 `MktDevMesh`，覆写时⛔ 不许漏掉这一句）；
+     *    表空了它就是一句 `length` 判断，⛔ 不需要再像旧写法那样把钩子置 null（钩子上还挂着全景投影那三件事）。
+     * ⚠️ 这里写的 `visible` 只针对**自己压进表的那几颗** ⇒ 表外的对象（单颗新增、已 dispose、被 `releaseReveal`
+     *    摘牌的）一律不碰；要在放行前接管某颗，调 `releaseReveal(o)`。
+     */
+    tickProgressiveReveal(): void;
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName?: string): MktMeshData;