three-base 2.0.168 → 2.0.172

package/MktMesh/panoTileStitcher.d.ts

@@ -6,8 +6,14 @@ import { Texture, type WebGLRenderer } from "three";
 export interface PanoStitcher {
     /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做） */
     ensure(urls: string[]): void;
-    /** 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）；没画过 / 没这组返回 null。 */
-    peek(batch: string, slot: number): Texture | null;
+    /**
+     * 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）。
+     * ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：**传了 `renderer` 且该槽一格都还没画时，
+     *   先把 RT 建出来（建完即整张涂 `MISSING_TILE_GRAY` 缺失灰）并返回它** ⇒ 调用方切批次的那一帧
+     *   拿到的就是**深灰底**而非 null（null 会让它沿用上一批 ⇒ 墙上闪上一个全景）。
+     *   ⛔ 没传 `renderer`（诊断/测试路径）仍旧返回 null —— 不能在无 GL 上下文时凭空建 RT。
+     */
+    peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null;
     /** 每帧驱动（消费方每帧只调一次）。`renderer` = 调用方当前的 WebGLRenderer，还没捕获到就传 null
      *  ⇒ 这一帧什么都不画（⛔ 不打假读数，也⛔ 不退回任何 CPU 拼合路径）。 */
     pump(renderer: WebGLRenderer | null): void;
@@ -36,6 +42,12 @@ export declare class PanoTileStitcher implements PanoStitcher {
     private _retryAt;
     private _fails;
     private _dead;
+    /** 已排进 `threeUtils.addWork` 队列、等着「只干上传那一句」的瓦片（皇上 2026-10-09 旨：上传走公共队列）。
+     *  ⛔ 必须自备：`addWork` 用 `workList.includes(work)` 判重，而每次排的都是**新闭包** ⇒ 它判不出来。
+     *  这个 Set 兼作「作废哨兵」：`_uploadTile` 开头 `if (!this._uploadQueued.delete(rec)) return;`
+     *  —— 该瓦片若已先被 `_dropTile`/`_switchRenderer`清掉（dispose 过），这一项就作废，
+     *  否则会对已释放的纹理 `initTexture` ⇒ 凭空建显存且无人回收。 */
+    private _uploadQueued;
     /** 建 RT 时用的渲染器（换 renderer ⇒ 在册组全清，见文件头） */
     private _renderer;
     /** 推进计数（`progressStamp`）*/
@@ -59,7 +71,7 @@ export declare class PanoTileStitcher implements PanoStitcher {
     ensure(urls: string[]): void;
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 16 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
-    peek(batch: string, slot: number): Texture | null;
+    peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null;
     /** ⭐ 这条路交出去的槽纹理本来就是 GL 渲染目标的附件 —— 像素已经在显存里，没有「上传」这一步。
      *  消费方（`MktMesh._peekTileAt` / 编辑器 `_peekTileAt`）据此**跳过**「每 tick 一张 `initTexture`」那道闸。 */
     resident(tex: Texture): boolean;
@@ -82,11 +94,27 @@ export declare class PanoTileStitcher implements PanoStitcher {
     private _drawPass;
     /** 工序 3：每帧至多把**一张**新纹理传进 GPU（旨②），这一趟只上传、不画。
      *  按「槽 0 格 0 → …」的顺序挑第一张已解码没上传的 ⇒ RT 从左上角起逐格显影，观感可预期。 */
+    /**
+     * 工序 3：**只入队一张**，真正上传交给 `threeUtils.addWork`（皇上 2026-10-09 旨）。
+     *
+     * ⚠️⛔ 为什么不用「函数内局部 budget」了：那个 `budget` 每次调用都重新初始化为 1，
+     *   只管得住「**本次 pump 内**≤1 张」，管不住「一帧被 pump 多次」——
+     *   而消费方 `MktMesh.onBeforeRender` 里 `updateTexture` 与 `feedFaceMapping` **各调了一次 pump**
+     *   （两处注释都以为对方在驱动，实际各驱动一次）⇒ 实际每帧上传 2 张，
+     *   违背本文件头「每一帧同样也是只载入一张新纹理」的承诺（实测 Performance 面板一帧看到多次 initTexture）。
+     *
+     * ⭐ 改挂`threeUtils.addWork` 的三个好处：
+     *   ① 节流**跨调用天然成立** —— 队列每帧只`splice(0,1)` 取一项，无论 pump 调几次都只上传一张；
+     *   ② 与库内既有范式同口径（`MktMesh._commitTileToShader` 就是这么排的），上传路径全走同一条队列；
+     *   ③ 保留皇上 10-05 旨的「占一格」手法（下面 `addWork(() => {})`）⇒ 真活晚一帧执行，
+     *      与 `_drawPass` 天然错开（上传与绘制不落同一拍，正是 09-29「两个大头别在同一帧」的延续）。
+     */
     private _uploadPass;
-    /** 上传一片瓦片的纹理（`texImage2D` + mipmap 才是那一下贵的，所以单独成工序）。
-     *  ⚠️ 成败都记 `uploaded`：不记 ⇒ 那一格永远进不了 `_drawPass` ⇒ 该槽永远画不满、每帧白烧一个预算，
-     *  比「那一帧没错峰」严重得多；记了最坏也只是退回 three 在绑定那一帧自己上传的老路径。
-     *  （与 `MktMesh._uploadTileTexture` 同一口径，皇上旨 2026-09-25「队列里只放上传那一句」。） */
+    /** 队列回调的全部内容：把这**一片**瓦片的纹理上传到 GPU（`texImage2D` + mipmap 才是那一下贵的）。
+     *  ⚠️ 开头那句判空是**作废闸**（皇上 2026-10-09 旨加）：本项在队列里等tick 期间，
+     *   那片瓦片可能已被 `_dropTile`（画完即弃）/ `_switchRenderer` 清掉并 dispose ⇒ 此时必须作废，
+     *   否则会对已释放纹理 `initTexture` ⇒ 凭空把显存建回来且无人回收。
+     *   （与 `MktMesh._uploadTileTexture` 的「排上队之后已被清掉 ⇒ 本项作废」同一口径。） */
     private _uploadTile;
     /** 画一格：把那片瓦片的**中间那块**铺进该槽第 `cell` 格（16 格里的一格）。
      *  ⚠️⚠️ `autoClear` 必须关掉：three 每次 `render()` 默认清屏，而这里**同一张 RT 要连画 16 帧**，

package/MktMesh/panoTileStitcher.js

@@ -76,8 +76,15 @@
  */
 import { ClampToEdgeWrapping, DataTexture, LinearFilter, LinearMipmapLinearFilter, Mesh, NoBlending, OrthographicCamera, PlaneGeometry, RGBAFormat, Scene, ShaderMaterial, SRGBColorSpace, UnsignedByteType, Vector3, Vector4, WebGLRenderTarget, } from "three";
 import { loadPanoTexture, releasePanoTexture } from "./panoBitmapTexture";
+// ⭐ 2026-10-09 皇上旨「上传也走 threeUtils.addWork 队列」：上传节流改为挂公共队列，见 `_uploadPass`。
+import threeUtils from "../threeUtils";
 import { MISSING_TILE_GRAY, RT_STITCH_CELLS_PER_SLOT, RT_STITCH_SLOT_COUNT, RT_STITCH_SLOT_H, RT_STITCH_SLOT_TILES, RT_STITCH_SLOT_W, RT_STITCH_SLOT_GRID, RT_STITCH_TILES_PER_BATCH, rtStitchBatchOf, rtStitchCellPos, rtStitchTileInset, } from "./mktShader";
-/** 每帧最多几张**新**纹理进 GPU（旨②「每一帧同样也是只载入一张新纹理到 GPU 里面去」）*/
+/**
+ * ⛔⛔ 2026-10-09 皇上旨：「每帧最多几张新纹理进 GPU」这条**节流已不再由此常量实现**，改由
+ *   `threeUtils.addWork` 队列承担（见 `_uploadPass`）—— 因为函数内局部 budget 管不住「一帧多次 pump」。
+ *   此常量保留仅作**文档锚点**，标出「一帧一张」这个不可回退的设计承诺（改队列实现前先看这里）。
+ *   ⛔ 别再拿它去写 budget 循环：那正是「一帧上传 2 张」的根因（消费方 onBeforeRender 里 pump 了两次）。
+ */
 const PANO_STITCH_UPLOADS_PER_FRAME = 1;
 /** 每帧最多发起几张下载（32 片一批，⛔ 不加以限制就是一帧甩 32 条 XHR + 32 次解码） */
 const PANO_STITCH_DOWNLOADS_PER_FRAME = 2;
@@ -141,6 +148,12 @@ export class PanoTileStitcher {
     _retryAt = new Map();
     _fails = new Map();
     _dead = new Set();
+    /** 已排进 `threeUtils.addWork` 队列、等着「只干上传那一句」的瓦片（皇上 2026-10-09 旨：上传走公共队列）。
+     *  ⛔ 必须自备：`addWork` 用 `workList.includes(work)` 判重，而每次排的都是**新闭包** ⇒ 它判不出来。
+     *  这个 Set 兼作「作废哨兵」：`_uploadTile` 开头 `if (!this._uploadQueued.delete(rec)) return;`
+     *  —— 该瓦片若已先被 `_dropTile`/`_switchRenderer`清掉（dispose 过），这一项就作废，
+     *  否则会对已释放的纹理 `initTexture` ⇒ 凭空建显存且无人回收。 */
+    _uploadQueued = new Set();
     /** 建 RT 时用的渲染器（换 renderer ⇒ 在册组全清，见文件头） */
     _renderer = null;
     /** 推进计数（`progressStamp`）*/
@@ -198,10 +211,24 @@ export class PanoTileStitcher {
     }
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 16 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
-    peek(batch, slot) {
+    peek(batch, slot, renderer) {
         const g = this._groups.get(batch);
-        if (!g || !g.drawnCount[slot])
+        if (!g)
             return null;
+        if (!g.drawnCount[slot]) {
+            // ⭐ 皇上 2026-10-09 旨「切换全景时上一个全景的内容要渲染成深灰」：
+            //   换批次的瞬间新全景还没画进任何格，若此处照旧返回 null，消费方 `panoSlotBind` 会
+            //   **沿用上一批的 RT 纹理** ⇒ 墙上继续显示上一个全景（皇上报的现象）。
+            //   这里改为：只要调用方给了 renderer，就**先把这张 RT 建出来**（`_ensureRt` 建完立刻
+            //   整张涂 `MISSING_TILE_GRAY` 缺失灰）并交出去 ⇒ 切换瞬间该象限就是**深灰底**，
+            //   随后随`pump` 逐格显影。观感 = 深灰 → 逐格填图，不再闪上一个全景的内容。
+            //   ⛔ 没给 renderer（诊断/测试路径）仍旧返回 null —— 不能在无 GL 上下文时凭空建 RT。
+            if (!renderer)
+                return null;
+            if (!this._renderer)
+                return null;
+            return this._ensureRt(this._renderer, g, slot).texture;
+        }
         const rt = g.rts[slot];
         return rt ? rt.texture : null;
     }
@@ -247,6 +274,7 @@ export class PanoTileStitcher {
         for (const batch of [...this._groups.keys()])
             this.disposeGroup(batch);
         this._texs.clear();
+        this._uploadQueued.clear(); // ⭐ 2026-10-09 旨：同上，连队列里那批未执行的项一并作废
         this._wanted.clear();
         this._retryAt.clear();
         this._fails.clear();
@@ -323,8 +351,28 @@ export class PanoTileStitcher {
     }
     /** 工序 3：每帧至多把**一张**新纹理传进 GPU（旨②），这一趟只上传、不画。
      *  按「槽 0 格 0 → …」的顺序挑第一张已解码没上传的 ⇒ RT 从左上角起逐格显影，观感可预期。 */
+    /**
+     * 工序 3：**只入队一张**，真正上传交给 `threeUtils.addWork`（皇上 2026-10-09 旨）。
+     *
+     * ⚠️⛔ 为什么不用「函数内局部 budget」了：那个 `budget` 每次调用都重新初始化为 1，
+     *   只管得住「**本次 pump 内**≤1 张」，管不住「一帧被 pump 多次」——
+     *   而消费方 `MktMesh.onBeforeRender` 里 `updateTexture` 与 `feedFaceMapping` **各调了一次 pump**
+     *   （两处注释都以为对方在驱动，实际各驱动一次）⇒ 实际每帧上传 2 张，
+     *   违背本文件头「每一帧同样也是只载入一张新纹理」的承诺（实测 Performance 面板一帧看到多次 initTexture）。
+     *
+     * ⭐ 改挂`threeUtils.addWork` 的三个好处：
+     *   ① 节流**跨调用天然成立** —— 队列每帧只`splice(0,1)` 取一项，无论 pump 调几次都只上传一张；
+     *   ② 与库内既有范式同口径（`MktMesh._commitTileToShader` 就是这么排的），上传路径全走同一条队列；
+     *   ③ 保留皇上 10-05 旨的「占一格」手法（下面 `addWork(() => {})`）⇒ 真活晚一帧执行，
+     *      与 `_drawPass` 天然错开（上传与绘制不落同一拍，正是 09-29「两个大头别在同一帧」的延续）。
+     */
     _uploadPass(renderer) {
-        let budget = PANO_STITCH_UPLOADS_PER_FRAME;
+        // ⛔⛔ 队列里已有待上传项 ⇒ **本次直接不排**。
+        //   这一句是本改法的关键闸门：若只靠下面 `has(rec)` 跳过「同一片」，遍历会**继续往下找下一片**
+        //   于是 pump 几次就把多张全排进队列（13 全景 × 32 片 = 416 项 ⇒ workList 膨胀、`includes` 退化成 O(n)、
+        //   队尾那张要等几百帧才传完）。先判「队列非空就收手」⇒ 队列恒 ≤2 项（一占位+一真活），延迟最低。
+        if (this._uploadQueued.size > 0)
+            return;
         for (const g of this._groups.values()) {
             if (g.pending <= 0)
                 continue;
@@ -339,18 +387,25 @@ export class PanoTileStitcher {
                     const rec = this._texs.get(url);
                     if (!rec || !rec.tex || rec.uploaded)
                         continue;
-                    this._uploadTile(rec);
-                    if (--budget <= 0)
-                        return; // 旨②「每一帧只载入一张新纹理」⇒ 这一趟到此为止
+                    // ⛔ 已在队列里 ⇒ 跳过（`addWork` 按引用判重对「新闭包」无效 ⇒ 必须自备 Set，见 `_uploadQueued`）
+                    if (this._uploadQueued.has(rec))
+                        continue;
+                    this._uploadQueued.add(rec);
+                    threeUtils.addWork(() => { }); // 占一格（什么都不干），把真活推到下一个 tick
+                    threeUtils.addWork(() => this._uploadTile(rec));
+                    return; // ⛔ 本次 pump 只排一张：其余名额留给下一帧的队列，绝不在这一帧再排第二张
                 }
             }
         }
     }
-    /** 上传一片瓦片的纹理（`texImage2D` + mipmap 才是那一下贵的，所以单独成工序）。
-     *  ⚠️ 成败都记 `uploaded`：不记 ⇒ 那一格永远进不了 `_drawPass` ⇒ 该槽永远画不满、每帧白烧一个预算，
-     *  比「那一帧没错峰」严重得多；记了最坏也只是退回 three 在绑定那一帧自己上传的老路径。
-     *  （与 `MktMesh._uploadTileTexture` 同一口径，皇上旨 2026-09-25「队列里只放上传那一句」。） */
+    /** 队列回调的全部内容：把这**一片**瓦片的纹理上传到 GPU（`texImage2D` + mipmap 才是那一下贵的）。
+     *  ⚠️ 开头那句判空是**作废闸**（皇上 2026-10-09 旨加）：本项在队列里等tick 期间，
+     *   那片瓦片可能已被 `_dropTile`（画完即弃）/ `_switchRenderer` 清掉并 dispose ⇒ 此时必须作废，
+     *   否则会对已释放纹理 `initTexture` ⇒ 凭空把显存建回来且无人回收。
+     *   （与 `MktMesh._uploadTileTexture` 的「排上队之后已被清掉 ⇒ 本项作废」同一口径。） */
     _uploadTile(rec) {
+        if (!this._uploadQueued.delete(rec))
+            return;
         const renderer = this._renderer;
         if (!renderer || !rec.tex)
             return;
@@ -477,6 +532,8 @@ export class PanoTileStitcher {
         for (const batch of [...this._groups.keys()])
             this.disposeGroup(batch);
         this._texs.clear();
+        // ⭐ 2026-10-09 旨：在册组整份作废 ⇒ 上传队列里那些项的 rec 也一并作废（否则会拿旧 renderer 上传）
+        this._uploadQueued.clear();
         this._wanted.clear();
         this._retryAt.clear();
         this._fails.clear();
@@ -510,6 +567,9 @@ export class PanoTileStitcher {
         const rec = this._texs.get(url);
         if (rec && rec.tex)
             releasePanoTexture(rec.tex);
+        // ⭐ 2026-10-09 旨：已排进上传队列的那一片也要**作废**（否则队列回调会对已释放纹理 initTexture）
+        if (rec)
+            this._uploadQueued.delete(rec);
         this._texs.delete(url);
         this._wanted.delete(url);
     }

package/MktMesh/panoTileStitcher.ts

@@ -96,6 +96,8 @@ import {
     type WebGLRenderer,
 } from "three";
 import { loadPanoTexture, releasePanoTexture } from "./panoBitmapTexture";
+// ⭐ 2026-10-09 皇上旨「上传也走 threeUtils.addWork 队列」：上传节流改为挂公共队列，见 `_uploadPass`。
+import threeUtils from "../threeUtils";
 import {
     MISSING_TILE_GRAY,
     RT_STITCH_CELLS_PER_SLOT,
@@ -110,7 +112,12 @@ import {
     rtStitchTileInset,
 } from "./mktShader";
 
-/** 每帧最多几张**新**纹理进 GPU（旨②「每一帧同样也是只载入一张新纹理到 GPU 里面去」）*/
+/**
+ * ⛔⛔ 2026-10-09 皇上旨：「每帧最多几张新纹理进 GPU」这条**节流已不再由此常量实现**，改由
+ *   `threeUtils.addWork` 队列承担（见 `_uploadPass`）—— 因为函数内局部 budget 管不住「一帧多次 pump」。
+ *   此常量保留仅作**文档锚点**，标出「一帧一张」这个不可回退的设计承诺（改队列实现前先看这里）。
+ *   ⛔ 别再拿它去写 budget 循环：那正是「一帧上传 2 张」的根因（消费方 onBeforeRender 里 pump 了两次）。
+ */
 const PANO_STITCH_UPLOADS_PER_FRAME = 1;
 
 /** 每帧最多发起几张下载（32 片一批，⛔ 不加以限制就是一帧甩 32 条 XHR + 32 次解码） */
@@ -199,8 +206,14 @@ interface StitchGroup {
 export interface PanoStitcher {
     /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做） */
     ensure(urls: string[]): void;
-    /** 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）；没画过 / 没这组返回 null。 */
-    peek(batch: string, slot: number): Texture | null;
+    /**
+     * 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）。
+     * ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：**传了 `renderer` 且该槽一格都还没画时，
+     *   先把 RT 建出来（建完即整张涂 `MISSING_TILE_GRAY` 缺失灰）并返回它** ⇒ 调用方切批次的那一帧
+     *   拿到的就是**深灰底**而非 null（null 会让它沿用上一批 ⇒ 墙上闪上一个全景）。
+     *   ⛔ 没传 `renderer`（诊断/测试路径）仍旧返回 null —— 不能在无 GL 上下文时凭空建 RT。
+     */
+    peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null;
     /** 每帧驱动（消费方每帧只调一次）。`renderer` = 调用方当前的 WebGLRenderer，还没捕获到就传 null
      *  ⇒ 这一帧什么都不画（⛔ 不打假读数，也⛔ 不退回任何 CPU 拼合路径）。 */
     pump(renderer: WebGLRenderer | null): void;
@@ -230,6 +243,12 @@ export class PanoTileStitcher implements PanoStitcher {
     private _retryAt: Map<string, number> = new Map();
     private _fails: Map<string, number> = new Map();
     private _dead: Set<string> = new Set();
+    /** 已排进 `threeUtils.addWork` 队列、等着「只干上传那一句」的瓦片（皇上 2026-10-09 旨：上传走公共队列）。
+     *  ⛔ 必须自备：`addWork` 用 `workList.includes(work)` 判重，而每次排的都是**新闭包** ⇒ 它判不出来。
+     *  这个 Set 兼作「作废哨兵」：`_uploadTile` 开头 `if (!this._uploadQueued.delete(rec)) return;`
+     *  —— 该瓦片若已先被 `_dropTile`/`_switchRenderer`清掉（dispose 过），这一项就作废，
+     *  否则会对已释放的纹理 `initTexture` ⇒ 凭空建显存且无人回收。 */
+private _uploadQueued: Set<TileRec> = new Set();
     /** 建 RT 时用的渲染器（换 renderer ⇒ 在册组全清，见文件头） */
     private _renderer: WebGLRenderer | null = null;
     /** 推进计数（`progressStamp`）*/
@@ -288,9 +307,21 @@ export class PanoTileStitcher implements PanoStitcher {
 
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 16 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
-    peek(batch: string, slot: number): Texture | null {
+    peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null {
         const g = this._groups.get(batch);
-        if (!g || !g.drawnCount[slot]) return null;
+        if (!g) return null;
+        if (!g.drawnCount[slot]) {
+            // ⭐ 皇上 2026-10-09 旨「切换全景时上一个全景的内容要渲染成深灰」：
+            //   换批次的瞬间新全景还没画进任何格，若此处照旧返回 null，消费方 `panoSlotBind` 会
+            //   **沿用上一批的 RT 纹理** ⇒ 墙上继续显示上一个全景（皇上报的现象）。
+            //   这里改为：只要调用方给了 renderer，就**先把这张 RT 建出来**（`_ensureRt` 建完立刻
+            //   整张涂 `MISSING_TILE_GRAY` 缺失灰）并交出去 ⇒ 切换瞬间该象限就是**深灰底**，
+            //   随后随`pump` 逐格显影。观感 = 深灰 → 逐格填图，不再闪上一个全景的内容。
+            //   ⛔ 没给 renderer（诊断/测试路径）仍旧返回 null —— 不能在无 GL 上下文时凭空建 RT。
+            if (!renderer) return null;
+            if (!this._renderer) return null;
+            return this._ensureRt(this._renderer, g, slot).texture;
+        }
         const rt = g.rts[slot];
         return rt ? rt.texture : null;
     }
@@ -338,6 +369,7 @@ export class PanoTileStitcher implements PanoStitcher {
     dispose(): void {
         for (const batch of [...this._groups.keys()]) this.disposeGroup(batch);
         this._texs.clear();
+        this._uploadQueued.clear(); // ⭐ 2026-10-09 旨：同上，连队列里那批未执行的项一并作废
         this._wanted.clear();
         this._retryAt.clear();
         this._fails.clear();
@@ -408,8 +440,27 @@ export class PanoTileStitcher implements PanoStitcher {
 
     /** 工序 3：每帧至多把**一张**新纹理传进 GPU（旨②），这一趟只上传、不画。
      *  按「槽 0 格 0 → …」的顺序挑第一张已解码没上传的 ⇒ RT 从左上角起逐格显影，观感可预期。 */
+    /**
+     * 工序 3：**只入队一张**，真正上传交给 `threeUtils.addWork`（皇上 2026-10-09 旨）。
+     *
+     * ⚠️⛔ 为什么不用「函数内局部 budget」了：那个 `budget` 每次调用都重新初始化为 1，
+     *   只管得住「**本次 pump 内**≤1 张」，管不住「一帧被 pump 多次」——
+     *   而消费方 `MktMesh.onBeforeRender` 里 `updateTexture` 与 `feedFaceMapping` **各调了一次 pump**
+     *   （两处注释都以为对方在驱动，实际各驱动一次）⇒ 实际每帧上传 2 张，
+     *   违背本文件头「每一帧同样也是只载入一张新纹理」的承诺（实测 Performance 面板一帧看到多次 initTexture）。
+     *
+     * ⭐ 改挂`threeUtils.addWork` 的三个好处：
+     *   ① 节流**跨调用天然成立** —— 队列每帧只`splice(0,1)` 取一项，无论 pump 调几次都只上传一张；
+     *   ② 与库内既有范式同口径（`MktMesh._commitTileToShader` 就是这么排的），上传路径全走同一条队列；
+     *   ③ 保留皇上 10-05 旨的「占一格」手法（下面 `addWork(() => {})`）⇒ 真活晚一帧执行，
+     *      与 `_drawPass` 天然错开（上传与绘制不落同一拍，正是 09-29「两个大头别在同一帧」的延续）。
+     */
     private _uploadPass(renderer: WebGLRenderer): void {
-        let budget = PANO_STITCH_UPLOADS_PER_FRAME;
+        // ⛔⛔ 队列里已有待上传项 ⇒ **本次直接不排**。
+        //   这一句是本改法的关键闸门：若只靠下面 `has(rec)` 跳过「同一片」，遍历会**继续往下找下一片**
+        //   于是 pump 几次就把多张全排进队列（13 全景 × 32 片 = 416 项 ⇒ workList 膨胀、`includes` 退化成 O(n)、
+        //   队尾那张要等几百帧才传完）。先判「队列非空就收手」⇒ 队列恒 ≤2 项（一占位+一真活），延迟最低。
+        if (this._uploadQueued.size > 0) return;
         for (const g of this._groups.values()) {
             if (g.pending <= 0) continue;
             for (let slot = 0; slot < RT_STITCH_SLOT_COUNT; slot++) {
@@ -420,18 +471,24 @@ export class PanoTileStitcher implements PanoStitcher {
                     if (!url || this._dead.has(url)) continue;
                     const rec = this._texs.get(url);
                     if (!rec || !rec.tex || rec.uploaded) continue;
-                    this._uploadTile(rec);
-                    if (--budget <= 0) return; // 旨②「每一帧只载入一张新纹理」⇒ 这一趟到此为止
+                    // ⛔ 已在队列里 ⇒ 跳过（`addWork` 按引用判重对「新闭包」无效 ⇒ 必须自备 Set，见 `_uploadQueued`）
+                    if (this._uploadQueued.has(rec)) continue;
+                    this._uploadQueued.add(rec);
+                    threeUtils.addWork(() => {}); // 占一格（什么都不干），把真活推到下一个 tick
+                    threeUtils.addWork(() => this._uploadTile(rec));
+                    return; // ⛔ 本次 pump 只排一张：其余名额留给下一帧的队列，绝不在这一帧再排第二张
                 }
             }
         }
     }
 
-    /** 上传一片瓦片的纹理（`texImage2D` + mipmap 才是那一下贵的，所以单独成工序）。
-     *  ⚠️ 成败都记 `uploaded`：不记 ⇒ 那一格永远进不了 `_drawPass` ⇒ 该槽永远画不满、每帧白烧一个预算，
-     *  比「那一帧没错峰」严重得多；记了最坏也只是退回 three 在绑定那一帧自己上传的老路径。
-     *  （与 `MktMesh._uploadTileTexture` 同一口径，皇上旨 2026-09-25「队列里只放上传那一句」。） */
+    /** 队列回调的全部内容：把这**一片**瓦片的纹理上传到 GPU（`texImage2D` + mipmap 才是那一下贵的）。
+     *  ⚠️ 开头那句判空是**作废闸**（皇上 2026-10-09 旨加）：本项在队列里等tick 期间，
+     *   那片瓦片可能已被 `_dropTile`（画完即弃）/ `_switchRenderer` 清掉并 dispose ⇒ 此时必须作废，
+     *   否则会对已释放纹理 `initTexture` ⇒ 凭空把显存建回来且无人回收。
+     *   （与 `MktMesh._uploadTileTexture` 的「排上队之后已被清掉 ⇒ 本项作废」同一口径。） */
     private _uploadTile(rec: TileRec): void {
+        if (!this._uploadQueued.delete(rec)) return;
         const renderer = this._renderer;
         if (!renderer || !rec.tex) return;
         try {
@@ -562,6 +619,8 @@ export class PanoTileStitcher implements PanoStitcher {
         this._renderer = renderer;
         for (const batch of [...this._groups.keys()]) this.disposeGroup(batch);
         this._texs.clear();
+        // ⭐ 2026-10-09 旨：在册组整份作废 ⇒ 上传队列里那些项的 rec 也一并作废（否则会拿旧 renderer 上传）
+        this._uploadQueued.clear();
         this._wanted.clear();
         this._retryAt.clear();
         this._fails.clear();
@@ -595,6 +654,8 @@ export class PanoTileStitcher implements PanoStitcher {
     private _dropTile(url: string): void {
         const rec = this._texs.get(url);
         if (rec && rec.tex) releasePanoTexture(rec.tex);
+        // ⭐ 2026-10-09 旨：已排进上传队列的那一片也要**作废**（否则队列回调会对已释放纹理 initTexture）
+        if (rec) this._uploadQueued.delete(rec);
         this._texs.delete(url);
         this._wanted.delete(url);
     }

package/MktMesh/types.d.ts

@@ -1,6 +1,10 @@
 import type { Matrix4 } from "three";
 /**
- * 单个纹理的运行时信息：url + 世界矩阵（位置 + 旋转，缩放忽略）。
+ * 单个纹理的运行时信息：url + 矩阵（位置 + 旋转，缩放忽略）。
+ * ⚠️ 这个矩阵记在 MktMesh **自身局部（制图）空间**，与 `wallPoints` 同一空间 —— 不是世界矩阵：
+ * 着色器里 `vProjPos = uProjInvMatrix·modelMatrix·position` 恰好把顶点拉回局部，片元再拿
+ * `vProjPos - 矩阵位置` 求投影方向，两端必须同空间纹理才贴得住（网格整体旋转/平移时尤其要紧，
+ * 名册挑图那把尺子也因此先把世界锚点 `worldToLocal` 再比距离，见 `MktMesh.updateTexture`）。
  * 纹理矩阵的「位置」即墨卡托投影的中心点（shader 里以它为原点求方向向量）。
  */
 export interface MktTextureInfo {

package/MktMesh/types.ts

@@ -8,7 +8,11 @@
 import type { Matrix4 } from "three";
 
 /**
- * 单个纹理的运行时信息：url + 世界矩阵（位置 + 旋转，缩放忽略）。
+ * 单个纹理的运行时信息：url + 矩阵（位置 + 旋转，缩放忽略）。
+ * ⚠️ 这个矩阵记在 MktMesh **自身局部（制图）空间**，与 `wallPoints` 同一空间 —— 不是世界矩阵：
+ * 着色器里 `vProjPos = uProjInvMatrix·modelMatrix·position` 恰好把顶点拉回局部，片元再拿
+ * `vProjPos - 矩阵位置` 求投影方向，两端必须同空间纹理才贴得住（网格整体旋转/平移时尤其要紧，
+ * 名册挑图那把尺子也因此先把世界锚点 `worldToLocal` 再比距离，见 `MktMesh.updateTexture`）。
  * 纹理矩阵的「位置」即墨卡托投影的中心点（shader 里以它为原点求方向向量）。
  */
 export interface MktTextureInfo {

package/ThreeBase.d.ts

@@ -90,8 +90,8 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
     /**
      * 调试用：深度预览模式。由面板「深度调试」切换，便于逐一看各深度图排查"深度测试全部失效"根因。
      *   - "none"    ：正常渲染（默认）
-     *   - "global"  ：仅预览全局深度图（baseDepthTexture，排除地板）。全白=深度为空→renderAoDepthPass 没写进深度。
-     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入的含地板深度）。用于确认深度管线本身是否工作。
+     *   - "global"  ：仅预览可见深度图（baseDepthTexture，含地板）。全白=深度为空→renderVisibleDepthPass 没写进深度。
+     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入）。用于确认深度管线本身是否工作。
      *   - "compare" ：R=全局 base 深度，G=最近一次 glow/stroke 选区 select 深度。两路任一全白即该侧写入失败。
      *   - "excluded"：深度图灰度 + 「被排除出深度图的面」叠红（红=该面写不进深度，永远挡不住后处理）。
      *                 物体区域（G 暗）若 B 全黑 → 判定从不触发；再看该区 R/G 谁大即可定位是谁缺深度。
@@ -99,15 +99,6 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
      * 通用控制台入口：任意页面都可 `window.__TB_DEBUG_DEPTH = "judge"`（优先级高于面板属性）。
      */
     debugDepthPreview: DebugDepthMode;
-    /**
-     * 可见深度图是否包含「标了 userData.aoFloor 的地板」（如 Ground1）。
-     *
-     * 默认 false —— 原设计：地板可透视，透过地板看到的物体照常显示（不被地板挡住）。
-     * 置 true 后地板会写进 baseDepthTexture，**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
-     * 排查"怎么都挡不住"时先开这个试一下：若开了就正常，说明挡你的正是可透视地板。
-     */
-    get baseDepthIncludeFloor(): boolean;
-    set baseDepthIncludeFloor(v: boolean);
     normalRenderTarget: WebGLRenderTarget<Texture>;
     screenRenderTarget: WebGLRenderTarget<Texture>;
     screenCopyShader: import("three").ShaderMaterial;

package/ThreeBase.js

@@ -18,7 +18,7 @@ import frosted_glass_pass from "./pass/frosted_glass_pass";
 import { flushLensflareOverlays } from "./lensflare/LensFlare";
 import glow_pass from "./pass/glow_pass";
 import stroke_pass from "./pass/stroke_pass";
-import ssao_pass, { renderAoDepthPass, renderExcludedMaskPass, visibleDepthOptions } from "./pass/ssao_pass";
+import ssao_pass, { renderVisibleDepthPass, renderExcludedMaskPass } from "./pass/ssao_pass";
 import screenBloomPass from "./pass/screen_bloom_pass";
 import copyShader from "./shaders/copyShader";
 import { baseTextureToRenderShader } from "./shaders/baseTextureToRenderShader";
@@ -260,12 +260,13 @@ export default class ThreeBase extends EventDispatcher {
         stencilBuffer: false,
         depthTexture: this.baseDepthTexture,
     });
-    // AO 深度纹理（含地板）：**不再单独渲染一遍** —— 它挂在 normalRenderTarget 上当 depth attachment，
-    // 法线 pass（renderAoNormalPass，includeFloor=true）渲染时深度由光栅器顺带写入，白拿一张含地板深度。
-    // （2026-09-14 优化：删掉原 ssao_pass 内那次 renderAoDepthPass(true)，每帧省一次全场景遍历。）
-    // SSAO 的 GTAO 采样它（地板保留为实体 → 接触 AO），合成时再与 depthRenderTarget
-    // （地板排除 = 可见深度）比对，作废"透过半透明地板看到的实体"上的地板接触 AO。
-    // 见 three-base/pass/ssao_pass.ts 的复合守卫说明。
+    // AO 深度纹理：**不再单独渲染一遍** —— 它挂在 normalRenderTarget 上当 depth attachment，
+    // 法线 pass（renderAoNormalPass，excludeTransparent=true）渲染时深度由光栅器顺带写入，白拿一张。
+    // （2026-09-14 优化：删掉原 ssao_pass 内那次独立的含地板深度 pass，每帧省一次全场景遍历。）
+    // SSAO 的 GTAO 采样它（与法线同源）；合成时再与 depthRenderTarget（可见深度 = 各物体自身材质渲染）
+    // 比对：AO 侧更近说明那像素记到屏幕上不可见的面（抠图空隙 / 单面墙背面）→ 作废该像素 AO。
+    // ⚠️ 2026-10-11：地板（Ground1）现在两张图都写（旧的 aoFloor 排除特例已整条拆除），
+    //   见 three-base/pass/ssao_pass.ts 文件头与复合守卫说明。
     aoDepthTexture = (() => {
         const t = new DepthTexture(4096, 4096);
         t.format = DepthFormat;
@@ -276,8 +277,8 @@ export default class ThreeBase extends EventDispatcher {
     /**
      * 调试用：深度预览模式。由面板「深度调试」切换，便于逐一看各深度图排查"深度测试全部失效"根因。
      *   - "none"    ：正常渲染（默认）
-     *   - "global"  ：仅预览全局深度图（baseDepthTexture，排除地板）。全白=深度为空→renderAoDepthPass 没写进深度。
-     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入的含地板深度）。用于确认深度管线本身是否工作。
+     *   - "global"  ：仅预览可见深度图（baseDepthTexture，含地板）。全白=深度为空→renderVisibleDepthPass 没写进深度。
+     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入）。用于确认深度管线本身是否工作。
      *   - "compare" ：R=全局 base 深度，G=最近一次 glow/stroke 选区 select 深度。两路任一全白即该侧写入失败。
      *   - "excluded"：深度图灰度 + 「被排除出深度图的面」叠红（红=该面写不进深度，永远挡不住后处理）。
      *                 物体区域（G 暗）若 B 全黑 → 判定从不触发；再看该区 R/G 谁大即可定位是谁缺深度。
@@ -285,20 +286,6 @@ export default class ThreeBase extends EventDispatcher {
      * 通用控制台入口：任意页面都可 `window.__TB_DEBUG_DEPTH = "judge"`（优先级高于面板属性）。
      */
     debugDepthPreview = "none";
-    /**
-     * 可见深度图是否包含「标了 userData.aoFloor 的地板」（如 Ground1）。
-     *
-     * 默认 false —— 原设计：地板可透视，透过地板看到的物体照常显示（不被地板挡住）。
-     * 置 true 后地板会写进 baseDepthTexture，**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
-     * 排查"怎么都挡不住"时先开这个试一下：若开了就正常，说明挡你的正是可透视地板。
-     */
-    get baseDepthIncludeFloor() {
-        return visibleDepthOptions.includeFloor;
-    }
-    set baseDepthIncludeFloor(v) {
-        visibleDepthOptions.includeFloor = v;
-        this.needRender = true;
-    }
     // 法线专用渲染目标（无 MSAA，存储视图空间法线，供 GTAO 风格 SSAO 使用真实法线）
     normalRenderTarget = new WebGLRenderTarget(128, 128, {
         minFilter: LinearFilter,
@@ -1019,10 +1006,11 @@ export default class ThreeBase extends EventDispatcher {
             this.renderer.setRenderTarget(this.baseRenderTarget);
             this.renderer.clear();
             this.renderer.render(this.scene, camera);
-            // 深度 pass：固定排除非实体表面后渲到 depthRenderTarget（生成 baseDepthTexture）。
+            // 可见深度 pass：用各物体自身材质渲染（含地板；sprite/线条/点与显式 aoTransparent 面除外），
+            // 产出 baseDepthTexture 供描边/发光/覆盖/磨砂做遮挡判定。
             // 必须在 base render 之后、所有依赖深度的特效（描边/发光/覆盖/磨砂）之前更新，
             // 否则这些特效会用到上一帧旧深度 → 遮挡判定错乱。法线 pass 已收进 ssao_pass 内部。
-            renderAoDepthPass(this.renderer, camera, this.scene, this.depthRenderTarget);
+            renderVisibleDepthPass(this.renderer, camera, this.scene, this.depthRenderTarget);
             // 切回 baseRenderTarget，后处理 pass 需要把效果叠加到颜色渲染目标上
             this.renderer.setRenderTarget(this.baseRenderTarget);
             // 效果 mask 灰度图尺寸 = effectiveRatio × resolution，与 baseRenderTarget / baseDepthTexture 同倍率，
@@ -1088,7 +1076,7 @@ export default class ThreeBase extends EventDispatcher {
             // 分辨率按实际帧缓冲像素（已乘 dpr）设置，修复高分屏下 FXAA 采样比例偏大失效的问题。
             // ⚠️ 深度调试预览（面板「深度调试」切换，定位"深度测试全部失效"根因）：
             //   旧控制台入口 `window.__BASE_DEPTH_VIS = true` 仍可用，等价于切到 "global"。
-            //   global  → baseDepthTexture 灰度。全白=深度为空(renderAoDepthPass 没写进)→后处理一律显示在前；有灰阶=深度正常，问题在比对侧。
+            //   global  → baseDepthTexture 灰度。全白=深度为空(renderVisibleDepthPass 没写进)→后处理一律显示在前；有灰阶=深度正常，问题在比对侧。
             //   ao      → aoDepthTexture 灰度（含地板）。确认深度管线本身是否工作（GTAO 是否拿到正确深度）。
             //   compare → R=全局 base 深度，G=最近一次 glow/stroke 选区的 select 深度。两路任一全白即该侧写入失败。
             //   judge   → R=base 原始深度、G=select 原始深度、B=判定结果(1=判为被遮挡应 discard)。

package/ThreeBase.ts

@@ -19,7 +19,7 @@ import frosted_glass_pass from "./pass/frosted_glass_pass";
 import { flushLensflareOverlays } from "./lensflare/LensFlare";
 import glow_pass from "./pass/glow_pass";
 import stroke_pass from "./pass/stroke_pass";
-import ssao_pass, { renderAoDepthPass, renderExcludedMaskPass, visibleDepthOptions } from "./pass/ssao_pass";
+import ssao_pass, { renderVisibleDepthPass, renderExcludedMaskPass } from "./pass/ssao_pass";
 import screenBloomPass from "./pass/screen_bloom_pass";
 import copyShader from "./shaders/copyShader";
 import { baseTextureToRenderShader } from "./shaders/baseTextureToRenderShader";
@@ -321,12 +321,13 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
         stencilBuffer: false,
         depthTexture: this.baseDepthTexture,
     });
-    // AO 深度纹理（含地板）：**不再单独渲染一遍** —— 它挂在 normalRenderTarget 上当 depth attachment，
-    // 法线 pass（renderAoNormalPass，includeFloor=true）渲染时深度由光栅器顺带写入，白拿一张含地板深度。
-    // （2026-09-14 优化：删掉原 ssao_pass 内那次 renderAoDepthPass(true)，每帧省一次全场景遍历。）
-    // SSAO 的 GTAO 采样它（地板保留为实体 → 接触 AO），合成时再与 depthRenderTarget
-    // （地板排除 = 可见深度）比对，作废"透过半透明地板看到的实体"上的地板接触 AO。
-    // 见 three-base/pass/ssao_pass.ts 的复合守卫说明。
+    // AO 深度纹理：**不再单独渲染一遍** —— 它挂在 normalRenderTarget 上当 depth attachment，
+    // 法线 pass（renderAoNormalPass，excludeTransparent=true）渲染时深度由光栅器顺带写入，白拿一张。
+    // （2026-09-14 优化：删掉原 ssao_pass 内那次独立的含地板深度 pass，每帧省一次全场景遍历。）
+    // SSAO 的 GTAO 采样它（与法线同源）；合成时再与 depthRenderTarget（可见深度 = 各物体自身材质渲染）
+    // 比对：AO 侧更近说明那像素记到屏幕上不可见的面（抠图空隙 / 单面墙背面）→ 作废该像素 AO。
+    // ⚠️ 2026-10-11：地板（Ground1）现在两张图都写（旧的 aoFloor 排除特例已整条拆除），
+    //   见 three-base/pass/ssao_pass.ts 文件头与复合守卫说明。
     aoDepthTexture: DepthTexture = (() => {
         const t = new DepthTexture(4096, 4096);
         t.format = DepthFormat;
@@ -337,8 +338,8 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
     /**
      * 调试用：深度预览模式。由面板「深度调试」切换，便于逐一看各深度图排查"深度测试全部失效"根因。
      *   - "none"    ：正常渲染（默认）
-     *   - "global"  ：仅预览全局深度图（baseDepthTexture，排除地板）。全白=深度为空→renderAoDepthPass 没写进深度。
-     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入的含地板深度）。用于确认深度管线本身是否工作。
+     *   - "global"  ：仅预览可见深度图（baseDepthTexture，含地板）。全白=深度为空→renderVisibleDepthPass 没写进深度。
+     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入）。用于确认深度管线本身是否工作。
      *   - "compare" ：R=全局 base 深度，G=最近一次 glow/stroke 选区 select 深度。两路任一全白即该侧写入失败。
      *   - "excluded"：深度图灰度 + 「被排除出深度图的面」叠红（红=该面写不进深度，永远挡不住后处理）。
      *                 物体区域（G 暗）若 B 全黑 → 判定从不触发；再看该区 R/G 谁大即可定位是谁缺深度。
@@ -347,20 +348,6 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
      */
     public debugDepthPreview: DebugDepthMode = "none";
 
-    /**
-     * 可见深度图是否包含「标了 userData.aoFloor 的地板」（如 Ground1）。
-     *
-     * 默认 false —— 原设计：地板可透视，透过地板看到的物体照常显示（不被地板挡住）。
-     * 置 true 后地板会写进 baseDepthTexture，**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
-     * 排查"怎么都挡不住"时先开这个试一下：若开了就正常，说明挡你的正是可透视地板。
-     */
-    public get baseDepthIncludeFloor(): boolean {
-        return visibleDepthOptions.includeFloor;
-    }
-    public set baseDepthIncludeFloor(v: boolean) {
-        visibleDepthOptions.includeFloor = v;
-        this.needRender = true;
-    }
     // 法线专用渲染目标（无 MSAA，存储视图空间法线，供 GTAO 风格 SSAO 使用真实法线）
     normalRenderTarget: WebGLRenderTarget<Texture> = new WebGLRenderTarget(128, 128, {
         minFilter: LinearFilter,
@@ -1131,10 +1118,11 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
             this.renderer.setRenderTarget(this.baseRenderTarget);
             this.renderer.clear();
             this.renderer.render(this.scene, camera);
-            // 深度 pass：固定排除非实体表面后渲到 depthRenderTarget（生成 baseDepthTexture）。
+            // 可见深度 pass：用各物体自身材质渲染（含地板；sprite/线条/点与显式 aoTransparent 面除外），
+            // 产出 baseDepthTexture 供描边/发光/覆盖/磨砂做遮挡判定。
             // 必须在 base render 之后、所有依赖深度的特效（描边/发光/覆盖/磨砂）之前更新，
             // 否则这些特效会用到上一帧旧深度 → 遮挡判定错乱。法线 pass 已收进 ssao_pass 内部。
-            renderAoDepthPass(this.renderer, camera, this.scene, this.depthRenderTarget);
+            renderVisibleDepthPass(this.renderer, camera, this.scene, this.depthRenderTarget);
             // 切回 baseRenderTarget，后处理 pass 需要把效果叠加到颜色渲染目标上
             this.renderer.setRenderTarget(this.baseRenderTarget);
             // 效果 mask 灰度图尺寸 = effectiveRatio × resolution，与 baseRenderTarget / baseDepthTexture 同倍率，
@@ -1204,7 +1192,7 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
             // 分辨率按实际帧缓冲像素（已乘 dpr）设置，修复高分屏下 FXAA 采样比例偏大失效的问题。
             // ⚠️ 深度调试预览（面板「深度调试」切换，定位"深度测试全部失效"根因）：
             //   旧控制台入口 `window.__BASE_DEPTH_VIS = true` 仍可用，等价于切到 "global"。
-            //   global  → baseDepthTexture 灰度。全白=深度为空(renderAoDepthPass 没写进)→后处理一律显示在前；有灰阶=深度正常，问题在比对侧。
+            //   global  → baseDepthTexture 灰度。全白=深度为空(renderVisibleDepthPass 没写进)→后处理一律显示在前；有灰阶=深度正常，问题在比对侧。
             //   ao      → aoDepthTexture 灰度（含地板）。确认深度管线本身是否工作（GTAO 是否拿到正确深度）。
             //   compare → R=全局 base 深度，G=最近一次 glow/stroke 选区的 select 深度。两路任一全白即该侧写入失败。
             //   judge   → R=base 原始深度、G=select 原始深度、B=判定结果(1=判为被遮挡应 discard)。

package/WaterFlow/WaterFlow.d.ts

@@ -26,7 +26,7 @@ import type { BasinConfig, FluidParameters, FluidQuality, ReservoirState, WaterF
  *     depthMode: 'logarithmic',
  *   });
  *   // 每帧：先 renderer.setRenderTarget(baseRenderTarget); renderer.render(scene, camera);
- *   //       再 renderAoDepthPass(renderer, camera, scene, depthRenderTarget);  // 写 baseDepthTexture
+ *   //       再 renderVisibleDepthPass(renderer, camera, scene, depthRenderTarget);  // 写 baseDepthTexture
  *   //       然后 water.update(dt, elapsed);
  *   //       最后 setRenderTarget(screenRT); fsQuad.render(renderer, pass.material);
  *   // 注意：WaterFlow 的 composite 是纯消费 base 纹理的 fsQuad，可直接放进你的链。