three-base 2.0.193 → 2.0.195

package/MktMesh/panoTileStitcher.d.ts

@@ -8,10 +8,21 @@ export interface PanoStitcher {
     /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做）。
      *  新增可选 `layout` 参数：缺省 = PANO_TILE_LAYOUT（全景 8×4 / 2 槽 / 6144×6144，2026-10-27 需求）；
      *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。
-     *  新增可选 `front` 参数（2026-10-29 需求）：`true` ⇒ 这一批**挪到在册顺序最前** = 每帧那三道工序
-     *  先取它的料（下载额度「每帧 2 张」先归它）。消费方每帧点一次 ⇒ 换渲染器那次整份作废后，
-     *  下一帧又把头名抢回来（⛔ 光靠「先入册」做不到，见 `MktMesh.prefetchHeadPanoramas` 的说明）。 */
-    ensure(urls: string[], layout?: TileLayout, front?: boolean): void;
+     *  ⚠️ 2026-10-30「加载任务队列」：本方法只负责**入册**（新组追加到在册顺序末尾 ⇒ 排在队列里等），
+     *  点名优先的那一路换成交换 `prioritize()`（10-29 那版挂在第三个参 `front` 上的「挪到队首」已并进那里，
+     *  ⛔ 一处排队只有 `prioritize` 一张尺）。 */
+    ensure(urls: string[], layout?: TileLayout): void;
+    /**
+     * 把某批瓦片登记进**加载任务队列**（2026-10-30 需求，逐字：「依次把前 2 个全景的顺序把瓦片加载任务添加到
+     * 任务队列里面，第一个加载完了，就把这个加载任务从任务队列里面去掉，然后加载第二个；后续按距离需要哪个全景
+     * 的时候同样添加到队列后面等待加载」）。
+     * 语义 = 先 `ensure` 入册（不在册就建组），再把批次键登记进队列**末尾**（已在队列里就不再挪，所以先登记的排前面）。
+     * 排队规则见 `_pumpDownloads`：**队首那组落定（32 格全画进 RT，或该格本就缺地址/判死）之前，队列里后面的组
+     * 和一切没登记的名册组一片都不发** ⇒ 第 1 颗全景独享全部下载额度、最快出全图。
+     * ⚠️ 消费方每帧点一次（`MktMesh.prefetchHeadPanoramas`）：预览每开一次都换渲染器，`_switchRenderer` 会把在册组
+     * 整份作废 ⇒ 队列跟着清空，下一帧重新登记才能把顺序抢回来（只在 `importData` 里点一次等于白点）。
+     */
+    prioritize(urls: string[], layout?: TileLayout): void;
     /**
      * 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）。
      * ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：**传了 `renderer` 且该槽一格都还没画时，
@@ -40,6 +51,10 @@ export interface PanoStitcher {
 export declare class PanoTileStitcher implements PanoStitcher {
     /** 批次组（键 = 32 张瓦片的第一张**非空**地址，与消费方同一个 `rtStitchBatchOf`） */
     private _groups;
+    /** 加载任务队列（2026-10-30 需求）：批次键的**串行带**，队首那组落定才开下一组。
+     *  由 `prioritize` 登记（存档里前 2 颗全景），`_pumpDownloads` 每帧出清；`_switchRenderer`/`dispose`/`disposeGroup`
+     *  跟着组一起拆。⛔ 这是「谁先下载」的唯一一把尺 —— 在册顺序（`_groups` 的 Map 序）只决定「同不带队列时」的补料次序。 */
+    private _queue;
     /** 瓦片纹理（url → `{tex, uploaded}`）。画进自己那一格就立刻释放 ⇒ 只在册期间占显存/内存。 */
     private _texs;
     /** 仍在册的组还需要的地址（迟到的加载回调据此判断「这条已经没人要了，立刻释放」） */
@@ -77,10 +92,14 @@ export declare class PanoTileStitcher implements PanoStitcher {
      *  ⚠️ 唯一按张数**能混进来**的是 10-06 那版同为 32 片的老档（切片顺序与槽分组两版一致 ⇒ 不会错位），
      *  但它的瓦片是 1024²、被画进 1536² 的格子 = 1.5× 放大 ⇒ 发虚，那类老点仍要重传一次。
      *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null]` —— 槽数再变会漏改）。 */
-    ensure(urls: string[], layout?: TileLayout, front?: boolean): void;
-    /** 把一批挪到在册顺序的**最前**（只动 Map 的顺序，⛔ 不动组里任何东西：RT、已画格子、瓦片账本原样）。
-     *  已在最前 ⇒ 一次 `keys().next()` 就返回（每帧点名走的就是这条零成本支路）。 */
-    private _toFront;
+    ensure(urls: string[], layout?: TileLayout): void;
+    /** 登记进加载任务队列（语义与排队规则见接口上那一段）。已在队列里 ⇒ 不挪（先登记的仍在前）。 */
+    prioritize(urls: string[], layout?: TileLayout): void;
+    /** 地址数组 → 批次键（补齐到满批再取首条非空，与 `ensure` 里同一条尺 ⇒ 两处不会各算各的）。
+     *  超限或全空 ⇒ 空串（`ensure` 那一步同样不收，这里也不入队）。 */
+    private _batchKeyOf;
+    /** 这一组的每一格要么已经画进 RT，要么根本没有地址 / 地址已判死 ⇒ 该下的都下完了（队列出清判据）。 */
+    private _isSettled;
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 `cellsPerSlot` 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
     peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null;
@@ -92,14 +111,20 @@ export declare class PanoTileStitcher implements PanoStitcher {
     progressStamp(): number;
     /** 每帧驱动（三道工序，顺序固定：补下载 → 画已进 GPU 的 → 再传一张新的）。 */
     pump(renderer: WebGLRenderer | null): void;
-    /** 释放整组（2 张 RT + 该组还没画掉的瓦片纹理） */
+    /** 释放一整组（2 张 RT + 该组还没画掉的瓦片纹理）；队列里那一记任务跟着撤（组没了还排着 = 队首永远等不到落定） */
     disposeGroup(batch: string): void;
     /** 释放全部（持有者 `dispose()` 时调用）；共享的那套 quad/材质/空白纹理一并退掉 */
     dispose(): void;
     private _now;
-    /** 工序 1：按「槽 0 格 0 → 槽 3 格 15」的顺序补齐还没发起的下载，受三道闸约束（每帧 2 张 /
-     *  下载中 ≤8 / 已解码待上传 ≤8）⇒ 一片瓦片终身只 `fetch` 一次（在册条目不重复发）。 */
+    /** 工序 1：按「槽 0 格 0 → …」的顺序补齐还没发起的下载，受三道闸约束（每帧 2 张 / 下载中 ≤8 /
+     *  已解码待上传 ≤8）⇒ 一片瓦片终身只 `fetch` 一次（在册条目不重复发）。
+     *  ⭐ 2026-10-30「加载任务队列」：队列非空时**只喂队首那一组**，它落定（`_isSettled`）就出队、下一帧轮到下一个；
+     *  ⇒ 存档里第 1 颗全景独享额度下满，才轮到第 2 颗，之后才轮到名册按距离点到、排在队尾等着的那些全景。
+     *  队列为空 ⇒ 退回原来的在册顺序逐组补料（图片平面那一路不入队，照旧按在册顺序）。 */
     private _pumpDownloads;
+    /** 某一组的取料循环：把「还没画、有地址、没判死、没发起过」的格子交给 `_loadTile`。
+     *  返回 false = 三道闸里有一道合上了 ⇒ 本帧别再往下看（`ctx` 是连扣的，跨组也接着算）。 */
+    private _issueCells;
     /** 工序 2：把所有「已进 GPU 且还没画」的格子画进各自的 RT —— 一帧画多少格都行（旨②）。
      *  ⛔ 准入只看一件事：`uploaded`。没上传过的纹理当场画 = `texImage2D` 藏进 `render()` 里
      *  = 每帧一张新纹理那道闸形同虚设（这正是本轮要治的卡顿本体）。 */

package/MktMesh/panoTileStitcher.js

@@ -41,6 +41,8 @@
  *
  * ── 每帧的三道工序（旨②那两句话逐条落地，顺序固定）────────────────────────────────
  *   1. `_pumpDownloads()`：补发缺图的下载（每帧 ≤2 张、在册 ≤8、已解码待上传 ≤8）⇒ ⛔ 一批几十条 XHR 一起炸。
+ *      ⭐ 2026-10-30 需求「加载任务队列」：`_queue` 非空时**只喂队首那一组**，那一组落定才出队开下一组
+ *      ⇒ 存档前 2 颗全景是一颗一颗下的（第 1 颗下满才轮到第 2 颗），名册按距离点到的排在后面等。
  *   2. `_drawPass()`：**只画「已经在 GPU 上的」瓦片**，一帧内画多少格都行（旨②「已经载入过的纹理，才可以
  *      一次性全部渲染到 RT 上面去」）。画完立刻释放那片 ⇒ 显存峰值 = 一格的量。
  *   3. `_uploadPass()`：**每帧至多一张**新纹理 `initTexture` 进 GPU（旨②「每一帧同样也是只载入一张新纹理
@@ -166,6 +168,10 @@ void main() {
 export class PanoTileStitcher {
     /** 批次组（键 = 32 张瓦片的第一张**非空**地址，与消费方同一个 `rtStitchBatchOf`） */
     _groups = new Map();
+    /** 加载任务队列（2026-10-30 需求）：批次键的**串行带**，队首那组落定才开下一组。
+     *  由 `prioritize` 登记（存档里前 2 颗全景），`_pumpDownloads` 每帧出清；`_switchRenderer`/`dispose`/`disposeGroup`
+     *  跟着组一起拆。⛔ 这是「谁先下载」的唯一一把尺 —— 在册顺序（`_groups` 的 Map 序）只决定「同不带队列时」的补料次序。 */
+    _queue = [];
     /** 瓦片纹理（url → `{tex, uploaded}`）。画进自己那一格就立刻释放 ⇒ 只在册期间占显存/内存。 */
     _texs = new Map();
     /** 仍在册的组还需要的地址（迟到的加载回调据此判断「这条已经没人要了，立刻释放」） */
@@ -220,20 +226,17 @@ export class PanoTileStitcher {
      *  ⚠️ 唯一按张数**能混进来**的是 10-06 那版同为 32 片的老档（切片顺序与槽分组两版一致 ⇒ 不会错位），
      *  但它的瓦片是 1024²、被画进 1536² 的格子 = 1.5× 放大 ⇒ 发虚，那类老点仍要重传一次。
      *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null]` —— 槽数再变会漏改）。 */
-    ensure(urls, layout, front = false) {
+    ensure(urls, layout) {
         const L = layout ?? PANO_TILE_LAYOUT;
         const maxTiles = tilesPerBatchOf(L);
         if (!urls || urls.length === 0 || urls.length > maxTiles)
             return;
+        const batch = this._batchKeyOf(urls, L);
+        if (this._groups.has(batch))
+            return;
         const u = urls.slice();
         while (u.length < maxTiles)
             u.push("");
-        const batch = rtStitchBatchOf(u);
-        if (this._groups.has(batch)) {
-            if (front)
-                this._toFront(batch);
-            return;
-        }
         const slotCount = L.slotCount;
         const cellsPerSlot = cellsPerSlotOf(L);
         this._groups.set(batch, {
@@ -247,25 +250,41 @@ export class PanoTileStitcher {
             drawnCount: Array.from({ length: slotCount }, () => 0),
             pending: slotCount,
         });
-        if (front)
-            this._toFront(batch);
         this._stamp++;
     }
-    /** 把一批挪到在册顺序的**最前**（只动 Map 的顺序，⛔ 不动组里任何东西：RT、已画格子、瓦片账本原样）。
-     *  已在最前 ⇒ 一次 `keys().next()` 就返回（每帧点名走的就是这条零成本支路）。 */
-    _toFront(batch) {
-        const g = this._groups.get(batch);
-        if (!g)
+    /** 登记进加载任务队列（语义与排队规则见接口上那一段）。已在队列里 ⇒ 不挪（先登记的仍在前）。 */
+    prioritize(urls, layout) {
+        this.ensure(urls, layout);
+        const batch = this._batchKeyOf(urls, layout ?? PANO_TILE_LAYOUT);
+        if (!batch || !this._groups.has(batch) || this._queue.includes(batch))
             return;
-        const head = this._groups.keys().next();
-        if (!head.done && head.value === batch)
-            return;
-        const rest = [...this._groups.entries()];
-        this._groups.clear();
-        this._groups.set(batch, g);
-        for (const [k, v] of rest)
-            if (k !== batch)
-                this._groups.set(k, v);
+        this._queue.push(batch);
+    }
+    /** 地址数组 → 批次键（补齐到满批再取首条非空，与 `ensure` 里同一条尺 ⇒ 两处不会各算各的）。
+     *  超限或全空 ⇒ 空串（`ensure` 那一步同样不收，这里也不入队）。 */
+    _batchKeyOf(urls, L) {
+        const maxTiles = tilesPerBatchOf(L);
+        if (!urls || urls.length === 0 || urls.length > maxTiles)
+            return "";
+        const u = urls.slice(0, maxTiles);
+        while (u.length < maxTiles)
+            u.push("");
+        return rtStitchBatchOf(u);
+    }
+    /** 这一组的每一格要么已经画进 RT，要么根本没有地址 / 地址已判死 ⇒ 该下的都下完了（队列出清判据）。 */
+    _isSettled(g) {
+        for (let slot = 0; slot < g.layout.slotCount; slot++) {
+            const ids = g.slotTiles[slot];
+            for (let cell = 0; cell < g.cellsPerSlot; cell++) {
+                if (g.drawn[slot] & (1 << cell))
+                    continue;
+                const url = g.urls[ids[cell]];
+                if (!url || this._dead.has(url))
+                    continue;
+                return false;
+            }
+        }
+        return true;
     }
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 `cellsPerSlot` 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
@@ -318,13 +337,16 @@ export class PanoTileStitcher {
         this._drawPass(renderer);
         this._uploadPass(renderer);
     }
-    /** 释放整组（2 张 RT + 该组还没画掉的瓦片纹理） */
+    /** 释放一整组（2 张 RT + 该组还没画掉的瓦片纹理）；队列里那一记任务跟着撤（组没了还排着 = 队首永远等不到落定） */
     disposeGroup(batch) {
         const g = this._groups.get(batch);
         if (!g)
             return;
         this._dropGroupGpu(g);
         this._groups.delete(batch);
+        const qi = this._queue.indexOf(batch);
+        if (qi >= 0)
+            this._queue.splice(qi, 1);
         this._stamp++;
     }
     /** 释放全部（持有者 `dispose()` 时调用）；共享的那套 quad/材质/空白纹理一并退掉 */
@@ -346,38 +368,58 @@ export class PanoTileStitcher {
     _now() {
         return typeof performance !== "undefined" ? performance.now() : Date.now();
     }
-    /** 工序 1：按「槽 0 格 0 → 槽 3 格 15」的顺序补齐还没发起的下载，受三道闸约束（每帧 2 张 /
-     *  下载中 ≤8 / 已解码待上传 ≤8）⇒ 一片瓦片终身只 `fetch` 一次（在册条目不重复发）。 */
+    /** 工序 1：按「槽 0 格 0 → …」的顺序补齐还没发起的下载，受三道闸约束（每帧 2 张 / 下载中 ≤8 /
+     *  已解码待上传 ≤8）⇒ 一片瓦片终身只 `fetch` 一次（在册条目不重复发）。
+     *  ⭐ 2026-10-30「加载任务队列」：队列非空时**只喂队首那一组**，它落定（`_isSettled`）就出队、下一帧轮到下一个；
+     *  ⇒ 存档里第 1 颗全景独享额度下满，才轮到第 2 颗，之后才轮到名册按距离点到、排在队尾等着的那些全景。
+     *  队列为空 ⇒ 退回原来的在册顺序逐组补料（图片平面那一路不入队，照旧按在册顺序）。 */
     _pumpDownloads() {
-        let inflight = 0;
-        let decoded = 0;
+        while (this._queue.length > 0) {
+            const head = this._groups.get(this._queue[0]);
+            if (head && !this._isSettled(head))
+                break;
+            this._queue.shift();
+        }
+        const ctx = { budget: PANO_STITCH_DOWNLOADS_PER_FRAME, inflight: 0, decoded: 0 };
         for (const rec of this._texs.values()) {
             if (rec.tex)
-                decoded++;
+                ctx.decoded++;
             else
-                inflight++;
+                ctx.inflight++;
+        }
+        if (this._queue.length > 0) {
+            const head = this._groups.get(this._queue[0]);
+            if (head)
+                this._issueCells(head, ctx);
+            return;
         }
-        let budget = PANO_STITCH_DOWNLOADS_PER_FRAME;
         for (const g of this._groups.values()) {
-            if (budget <= 0 || inflight >= PANO_STITCH_MAX_INFLIGHT || decoded >= PANO_STITCH_MAX_DECODED_AHEAD)
+            if (ctx.budget <= 0 || ctx.inflight >= PANO_STITCH_MAX_INFLIGHT || ctx.decoded >= PANO_STITCH_MAX_DECODED_AHEAD)
                 return;
-            for (let slot = 0; slot < g.layout.slotCount; slot++) {
-                const ids = g.slotTiles[slot];
-                for (let cell = 0; cell < g.cellsPerSlot; cell++) {
-                    if (g.drawn[slot] & (1 << cell))
-                        continue;
-                    const url = g.urls[ids[cell]];
-                    if (!url || this._dead.has(url))
-                        continue;
-                    if (this._texs.has(url))
-                        continue;
-                    this._loadTile(url);
-                    inflight++;
-                    if (--budget <= 0 || inflight >= PANO_STITCH_MAX_INFLIGHT || decoded >= PANO_STITCH_MAX_DECODED_AHEAD)
-                        return;
-                }
+            if (!this._issueCells(g, ctx))
+                return;
+        }
+    }
+    /** 某一组的取料循环：把「还没画、有地址、没判死、没发起过」的格子交给 `_loadTile`。
+     *  返回 false = 三道闸里有一道合上了 ⇒ 本帧别再往下看（`ctx` 是连扣的，跨组也接着算）。 */
+    _issueCells(g, ctx) {
+        for (let slot = 0; slot < g.layout.slotCount; slot++) {
+            const ids = g.slotTiles[slot];
+            for (let cell = 0; cell < g.cellsPerSlot; cell++) {
+                if (g.drawn[slot] & (1 << cell))
+                    continue;
+                const url = g.urls[ids[cell]];
+                if (!url || this._dead.has(url))
+                    continue;
+                if (this._texs.has(url))
+                    continue;
+                this._loadTile(url);
+                ctx.inflight++;
+                if (--ctx.budget <= 0 || ctx.inflight >= PANO_STITCH_MAX_INFLIGHT || ctx.decoded >= PANO_STITCH_MAX_DECODED_AHEAD)
+                    return false;
             }
         }
+        return true;
     }
     /** 工序 2：把所有「已进 GPU 且还没画」的格子画进各自的 RT —— 一帧画多少格都行（旨②）。
      *  ⛔ 准入只看一件事：`uploaded`。没上传过的纹理当场画 = `texImage2D` 藏进 `render()` 里

package/MktMesh/panoTileStitcher.ts

@@ -41,6 +41,8 @@
  *
  * ── 每帧的三道工序（旨②那两句话逐条落地，顺序固定）────────────────────────────────
  *   1. `_pumpDownloads()`：补发缺图的下载（每帧 ≤2 张、在册 ≤8、已解码待上传 ≤8）⇒ ⛔ 一批几十条 XHR 一起炸。
+ *      ⭐ 2026-10-30 需求「加载任务队列」：`_queue` 非空时**只喂队首那一组**，那一组落定才出队开下一组
+ *      ⇒ 存档前 2 颗全景是一颗一颗下的（第 1 颗下满才轮到第 2 颗），名册按距离点到的排在后面等。
  *   2. `_drawPass()`：**只画「已经在 GPU 上的」瓦片**，一帧内画多少格都行（旨②「已经载入过的纹理，才可以
  *      一次性全部渲染到 RT 上面去」）。画完立刻释放那片 ⇒ 显存峰值 = 一格的量。
  *   3. `_uploadPass()`：**每帧至多一张**新纹理 `initTexture` 进 GPU（旨②「每一帧同样也是只载入一张新纹理
@@ -239,10 +241,21 @@ export interface PanoStitcher {
     /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做）。
      *  新增可选 `layout` 参数：缺省 = PANO_TILE_LAYOUT（全景 8×4 / 2 槽 / 6144×6144，2026-10-27 需求）；
      *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。
-     *  新增可选 `front` 参数（2026-10-29 需求）：`true` ⇒ 这一批**挪到在册顺序最前** = 每帧那三道工序
-     *  先取它的料（下载额度「每帧 2 张」先归它）。消费方每帧点一次 ⇒ 换渲染器那次整份作废后，
-     *  下一帧又把头名抢回来（⛔ 光靠「先入册」做不到，见 `MktMesh.prefetchHeadPanoramas` 的说明）。 */
-    ensure(urls: string[], layout?: TileLayout, front?: boolean): void;
+     *  ⚠️ 2026-10-30「加载任务队列」：本方法只负责**入册**（新组追加到在册顺序末尾 ⇒ 排在队列里等），
+     *  点名优先的那一路换成交换 `prioritize()`（10-29 那版挂在第三个参 `front` 上的「挪到队首」已并进那里，
+     *  ⛔ 一处排队只有 `prioritize` 一张尺）。 */
+    ensure(urls: string[], layout?: TileLayout): void;
+    /**
+     * 把某批瓦片登记进**加载任务队列**（2026-10-30 需求，逐字：「依次把前 2 个全景的顺序把瓦片加载任务添加到
+     * 任务队列里面，第一个加载完了，就把这个加载任务从任务队列里面去掉，然后加载第二个；后续按距离需要哪个全景
+     * 的时候同样添加到队列后面等待加载」）。
+     * 语义 = 先 `ensure` 入册（不在册就建组），再把批次键登记进队列**末尾**（已在队列里就不再挪，所以先登记的排前面）。
+     * 排队规则见 `_pumpDownloads`：**队首那组落定（32 格全画进 RT，或该格本就缺地址/判死）之前，队列里后面的组
+     * 和一切没登记的名册组一片都不发** ⇒ 第 1 颗全景独享全部下载额度、最快出全图。
+     * ⚠️ 消费方每帧点一次（`MktMesh.prefetchHeadPanoramas`）：预览每开一次都换渲染器，`_switchRenderer` 会把在册组
+     * 整份作废 ⇒ 队列跟着清空，下一帧重新登记才能把顺序抢回来（只在 `importData` 里点一次等于白点）。
+     */
+    prioritize(urls: string[], layout?: TileLayout): void;
     /**
      * 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）。
      * ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：**传了 `renderer` 且该槽一格都还没画时，
@@ -272,6 +285,10 @@ export interface PanoStitcher {
 export class PanoTileStitcher implements PanoStitcher {
     /** 批次组（键 = 32 张瓦片的第一张**非空**地址，与消费方同一个 `rtStitchBatchOf`） */
     private _groups: Map<string, StitchGroup> = new Map();
+    /** 加载任务队列（2026-10-30 需求）：批次键的**串行带**，队首那组落定才开下一组。
+     *  由 `prioritize` 登记（存档里前 2 颗全景），`_pumpDownloads` 每帧出清；`_switchRenderer`/`dispose`/`disposeGroup`
+     *  跟着组一起拆。⛔ 这是「谁先下载」的唯一一把尺 —— 在册顺序（`_groups` 的 Map 序）只决定「同不带队列时」的补料次序。 */
+    private _queue: string[] = [];
     /** 瓦片纹理（url → `{tex, uploaded}`）。画进自己那一格就立刻释放 ⇒ 只在册期间占显存/内存。 */
     private _texs: Map<string, TileRec> = new Map();
     /** 仍在册的组还需要的地址（迟到的加载回调据此判断「这条已经没人要了，立刻释放」） */
@@ -329,17 +346,14 @@ private _uploadQueued: Set<TileRec> = new Set();
      *  ⚠️ 唯一按张数**能混进来**的是 10-06 那版同为 32 片的老档（切片顺序与槽分组两版一致 ⇒ 不会错位），
      *  但它的瓦片是 1024²、被画进 1536² 的格子 = 1.5× 放大 ⇒ 发虚，那类老点仍要重传一次。
      *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null]` —— 槽数再变会漏改）。 */
-    ensure(urls: string[], layout?: TileLayout, front = false): void {
+    ensure(urls: string[], layout?: TileLayout): void {
         const L = layout ?? PANO_TILE_LAYOUT;
         const maxTiles = tilesPerBatchOf(L);
         if (!urls || urls.length === 0 || urls.length > maxTiles) return;
+        const batch = this._batchKeyOf(urls, L);
+        if (this._groups.has(batch)) return;
         const u = urls.slice();
         while (u.length < maxTiles) u.push("");
-        const batch = rtStitchBatchOf(u);
-        if (this._groups.has(batch)) {
-            if (front) this._toFront(batch);
-            return;
-        }
         const slotCount = L.slotCount;
         const cellsPerSlot = cellsPerSlotOf(L);
         this._groups.set(batch, {
@@ -353,21 +367,39 @@ private _uploadQueued: Set<TileRec> = new Set();
             drawnCount: Array.from({ length: slotCount }, () => 0),
             pending: slotCount,
         });
-        if (front) this._toFront(batch);
         this._stamp++;
     }
 
-    /** 把一批挪到在册顺序的**最前**（只动 Map 的顺序，⛔ 不动组里任何东西：RT、已画格子、瓦片账本原样）。
-     *  已在最前 ⇒ 一次 `keys().next()` 就返回（每帧点名走的就是这条零成本支路）。 */
-    private _toFront(batch: string): void {
-        const g = this._groups.get(batch);
-        if (!g) return;
-        const head = this._groups.keys().next();
-        if (!head.done && head.value === batch) return;
-        const rest = [...this._groups.entries()];
-        this._groups.clear();
-        this._groups.set(batch, g);
-        for (const [k, v] of rest) if (k !== batch) this._groups.set(k, v);
+    /** 登记进加载任务队列（语义与排队规则见接口上那一段）。已在队列里 ⇒ 不挪（先登记的仍在前）。 */
+    prioritize(urls: string[], layout?: TileLayout): void {
+        this.ensure(urls, layout);
+        const batch = this._batchKeyOf(urls, layout ?? PANO_TILE_LAYOUT);
+        if (!batch || !this._groups.has(batch) || this._queue.includes(batch)) return;
+        this._queue.push(batch);
+    }
+
+    /** 地址数组 → 批次键（补齐到满批再取首条非空，与 `ensure` 里同一条尺 ⇒ 两处不会各算各的）。
+     *  超限或全空 ⇒ 空串（`ensure` 那一步同样不收，这里也不入队）。 */
+    private _batchKeyOf(urls: string[], L: TileLayout): string {
+        const maxTiles = tilesPerBatchOf(L);
+        if (!urls || urls.length === 0 || urls.length > maxTiles) return "";
+        const u = urls.slice(0, maxTiles);
+        while (u.length < maxTiles) u.push("");
+        return rtStitchBatchOf(u);
+    }
+
+    /** 这一组的每一格要么已经画进 RT，要么根本没有地址 / 地址已判死 ⇒ 该下的都下完了（队列出清判据）。 */
+    private _isSettled(g: StitchGroup): boolean {
+        for (let slot = 0; slot < g.layout.slotCount; slot++) {
+            const ids = g.slotTiles[slot];
+            for (let cell = 0; cell < g.cellsPerSlot; cell++) {
+                if (g.drawn[slot] & (1 << cell)) continue;
+                const url = g.urls[ids[cell]];
+                if (!url || this._dead.has(url)) continue;
+                return false;
+            }
+        }
+        return true;
     }
 
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 `cellsPerSlot` 格画满）。
@@ -421,12 +453,14 @@ private _uploadQueued: Set<TileRec> = new Set();
         this._uploadPass(renderer);
     }
 
-    /** 释放整组（2 张 RT + 该组还没画掉的瓦片纹理） */
+    /** 释放一整组（2 张 RT + 该组还没画掉的瓦片纹理）；队列里那一记任务跟着撤（组没了还排着 = 队首永远等不到落定） */
     disposeGroup(batch: string): void {
         const g = this._groups.get(batch);
         if (!g) return;
         this._dropGroupGpu(g);
         this._groups.delete(batch);
+        const qi = this._queue.indexOf(batch);
+        if (qi >= 0) this._queue.splice(qi, 1);
         this._stamp++;
     }
 
@@ -451,31 +485,49 @@ private _uploadQueued: Set<TileRec> = new Set();
         return typeof performance !== "undefined" ? performance.now() : Date.now();
     }
 
-    /** 工序 1：按「槽 0 格 0 → 槽 3 格 15」的顺序补齐还没发起的下载，受三道闸约束（每帧 2 张 /
-     *  下载中 ≤8 / 已解码待上传 ≤8）⇒ 一片瓦片终身只 `fetch` 一次（在册条目不重复发）。 */
+    /** 工序 1：按「槽 0 格 0 → …」的顺序补齐还没发起的下载，受三道闸约束（每帧 2 张 / 下载中 ≤8 /
+     *  已解码待上传 ≤8）⇒ 一片瓦片终身只 `fetch` 一次（在册条目不重复发）。
+     *  ⭐ 2026-10-30「加载任务队列」：队列非空时**只喂队首那一组**，它落定（`_isSettled`）就出队、下一帧轮到下一个；
+     *  ⇒ 存档里第 1 颗全景独享额度下满，才轮到第 2 颗，之后才轮到名册按距离点到、排在队尾等着的那些全景。
+     *  队列为空 ⇒ 退回原来的在册顺序逐组补料（图片平面那一路不入队，照旧按在册顺序）。 */
     private _pumpDownloads(): void {
-        let inflight = 0;
-        let decoded = 0;
+        while (this._queue.length > 0) {
+            const head = this._groups.get(this._queue[0]);
+            if (head && !this._isSettled(head)) break;
+            this._queue.shift();
+        }
+        const ctx = { budget: PANO_STITCH_DOWNLOADS_PER_FRAME, inflight: 0, decoded: 0 };
         for (const rec of this._texs.values()) {
-            if (rec.tex) decoded++;
-            else inflight++;
+            if (rec.tex) ctx.decoded++;
+            else ctx.inflight++;
+        }
+        if (this._queue.length > 0) {
+            const head = this._groups.get(this._queue[0]);
+            if (head) this._issueCells(head, ctx);
+            return;
         }
-        let budget = PANO_STITCH_DOWNLOADS_PER_FRAME;
         for (const g of this._groups.values()) {
-            if (budget <= 0 || inflight >= PANO_STITCH_MAX_INFLIGHT || decoded >= PANO_STITCH_MAX_DECODED_AHEAD) return;
-            for (let slot = 0; slot < g.layout.slotCount; slot++) {
-                const ids = g.slotTiles[slot];
-                for (let cell = 0; cell < g.cellsPerSlot; cell++) {
-                    if (g.drawn[slot] & (1 << cell)) continue;
-                    const url = g.urls[ids[cell]];
-                    if (!url || this._dead.has(url)) continue;
-                    if (this._texs.has(url)) continue;
-                    this._loadTile(url);
-                    inflight++;
-                    if (--budget <= 0 || inflight >= PANO_STITCH_MAX_INFLIGHT || decoded >= PANO_STITCH_MAX_DECODED_AHEAD) return;
-                }
+            if (ctx.budget <= 0 || ctx.inflight >= PANO_STITCH_MAX_INFLIGHT || ctx.decoded >= PANO_STITCH_MAX_DECODED_AHEAD) return;
+            if (!this._issueCells(g, ctx)) return;
+        }
+    }
+
+    /** 某一组的取料循环：把「还没画、有地址、没判死、没发起过」的格子交给 `_loadTile`。
+     *  返回 false = 三道闸里有一道合上了 ⇒ 本帧别再往下看（`ctx` 是连扣的，跨组也接着算）。 */
+    private _issueCells(g: StitchGroup, ctx: { budget: number; inflight: number; decoded: number }): boolean {
+        for (let slot = 0; slot < g.layout.slotCount; slot++) {
+            const ids = g.slotTiles[slot];
+            for (let cell = 0; cell < g.cellsPerSlot; cell++) {
+                if (g.drawn[slot] & (1 << cell)) continue;
+                const url = g.urls[ids[cell]];
+                if (!url || this._dead.has(url)) continue;
+                if (this._texs.has(url)) continue;
+                this._loadTile(url);
+                ctx.inflight++;
+                if (--ctx.budget <= 0 || ctx.inflight >= PANO_STITCH_MAX_INFLIGHT || ctx.decoded >= PANO_STITCH_MAX_DECODED_AHEAD) return false;
             }
         }
+        return true;
     }
 
     /** 工序 2：把所有「已进 GPU 且还没画」的格子画进各自的 RT —— 一帧画多少格都行（旨②）。

package/MktMesh/types.d.ts

@@ -1,7 +1,6 @@
 import type { Matrix4 } from "three";
 import type { ImagePlaneData } from "./imagePlane";
 import type { ModelSlotData } from "./modelSlot";
-import type { GlassPaneData } from "./glassPane";
 /**
  * 单个纹理的运行时信息：url + 矩阵（位置 + 旋转，缩放忽略）。
  * ⚠️ 这个矩阵记在 MktMesh **自身局部（制图）空间**，与 `wallPoints` 同一空间 —— 不是世界矩阵：
@@ -88,9 +87,4 @@ export interface MktMeshData {
     images?: ImagePlaneData[];
     /** 模型槽层（同一道旨）：`url` 是 .glb 的相对地址；空串 = 还没上传 ⇒ 显示占位小立方体 */
     models?: ModelSlotData[];
-    /**
-     * 玻璃面层（2026-10-28 需求「正方的面」）：正方形、双面、transmission 折射，反射环境取运行时第一个全景。
-     * ⛔ 这一层不落任何素材地址 ⇒ 既不过 `stripAssetHost` 也不过 `absAssetUrl`，只有位置/旋转/边长。
-     */
-    glass?: GlassPaneData[];
 }

package/MktMesh/types.ts

@@ -8,7 +8,6 @@
 import type { Matrix4 } from "three";
 import type { ImagePlaneData } from "./imagePlane";
 import type { ModelSlotData } from "./modelSlot";
-import type { GlassPaneData } from "./glassPane";
 
 /**
  * 单个纹理的运行时信息：url + 矩阵（位置 + 旋转，缩放忽略）。
@@ -100,9 +99,4 @@ export interface MktMeshData {
     images?: ImagePlaneData[];
     /** 模型槽层（同一道旨）：`url` 是 .glb 的相对地址；空串 = 还没上传 ⇒ 显示占位小立方体 */
     models?: ModelSlotData[];
-    /**
-     * 玻璃面层（2026-10-28 需求「正方的面」）：正方形、双面、transmission 折射，反射环境取运行时第一个全景。
-     * ⛔ 这一层不落任何素材地址 ⇒ 既不过 `stripAssetHost` 也不过 `absAssetUrl`，只有位置/旋转/边长。
-     */
-    glass?: GlassPaneData[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-base",
-  "version": "2.0.193",
+  "version": "2.0.195",
   "description": "A Three.js extension library providing common 3D components, animations, materials, and utilities",
   "author": "xiaosihan",
   "publishConfig": {
@@ -47,11 +47,6 @@
       "import": "./MktMesh/modelSlot.js",
       "require": "./MktMesh/modelSlot.js"
     },
-    "./MktMesh/glassPane": {
-      "types": "./MktMesh/glassPane.d.ts",
-      "import": "./MktMesh/glassPane.js",
-      "require": "./MktMesh/glassPane.js"
-    },
     "./MktMesh/boxLine2": {
       "types": "./MktMesh/boxLine2.d.ts",
       "import": "./MktMesh/boxLine2.js",

package/MktMesh/glassPane.d.ts

@@ -1,43 +0,0 @@
-import { Mesh, MeshPhysicalMaterial, PlaneGeometry, Texture } from "three";
-/** 玻璃面的持久化数据（进 `MktMesh.exportData` 的 `glass` 键 / `importData` 还原） */
-export interface GlassPaneData {
-    name?: string;
-    position: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    rotation: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** 正方形边长（米）：宽 = 高 = 本值，⛔ 不拆成两档 */
-    size: number;
-}
-export declare class GlassPane extends Mesh<PlaneGeometry, MeshPhysicalMaterial> {
-    private _originalColor;
-    /** 反射环境纹理的身份（由 `MktMesh` 注入，本类只持有引用、⛔ 从不 dispose 它 —— 那张按地址缓存在库里） */
-    private _envTex;
-    constructor(name?: string);
-    get paneSize(): number;
-    /** 换正方形边长（宽高等比跟着走：几何只有这一把尺） */
-    setPaneSize(size: number): void;
-    /**
-     * 绑/摘反射环境纹理（`null` = 还没有可用的环境源）。
-     * ⚠️ 判等在前：`material.needsUpdate = true` 会涨材质版本 ⇒ 程序要重编译。库里给同一批玻璃面注入的是
-     *   **同一个 Texture 对象**（反射源只下载一次），逐颗重复赋同一张时必须早退，不然就是 N 次无谓重编译。
-     * ⚠️ 传进来的纹理必须已标 `EquirectangularReflectionMapping`：three 的 `WebGLCubeUVMaps` 只认那个标记才会
-     *   自动把它卷积成立方 UV（PMREM）；直接给一张普通 UV 纹理（例如全景拼合槽的那两张 RT）采出来是花屏。
-     */
-    setEnvironmentTexture(tex: Texture | null): void;
-    highlight(): void;
-    restoreColor(): void;
-    toData(): GlassPaneData;
-    applyData(d: GlassPaneData): void;
-    /** 只释放自己的几何与材质；反射纹理归 `MktMesh` 管（多颗共用一张）。 */
-    dispose(): void;
-}
-export declare const GLASS_PANE_DEFAULTS: {
-    size: number;
-};