three-base 2.0.192 → 2.0.195

package/EventMap.d.ts

@@ -8,6 +8,12 @@ export interface LoadingEvent {
 export interface OnLoadEvent {
     type: "onLoad";
 }
+export interface LoaderProgressEvent {
+    type: "progress";
+    url: string;
+    loaded: number;
+    total: number;
+}
 export interface BeforeRenderEvent {
     type: "beforeRender";
 }
@@ -53,6 +59,7 @@ export interface MeshBaseEventMap extends Object3DEventMap {
 export interface ThreeLoaderEventMap extends Object3DEventMap {
     "loadding": LoadingEvent;
     "onLoad": OnLoadEvent;
+    "progress": LoaderProgressEvent;
 }
 export interface ThreeBaseEventTypeMap extends Object3DEventMap {
     "loadding": LoadingEvent;

package/EventMap.ts

@@ -29,6 +29,13 @@ import type { Object3DEventMap, Vector3 } from "three";
 export interface LoadedEvent { type: "loaded"; }
 export interface LoadingEvent { type: "loadding"; }
 export interface OnLoadEvent { type: "onLoad"; }
+// 资源加载进度：`DefaultLoadingManager.onProgress` 的三个数原样带出（url / 已完成项数 / 总项数）
+export interface LoaderProgressEvent {
+    type: "progress";
+    url: string;
+    loaded: number;
+    total: number;
+}
 export interface BeforeRenderEvent { type: "beforeRender"; }
 export interface AfterRenderEvent { type: "afterRender"; }
 
@@ -77,6 +84,7 @@ export interface MeshBaseEventMap extends Object3DEventMap {
 export interface ThreeLoaderEventMap extends Object3DEventMap {
     "loadding": LoadingEvent;
     "onLoad": OnLoadEvent;
+    "progress": LoaderProgressEvent;
 }
 
 export interface ThreeBaseEventTypeMap extends Object3DEventMap {

package/MktMesh/MktMesh.d.ts

@@ -405,6 +405,40 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址
      *  @param onModelLoad 每只 GLB 落地时回调一次（可选）——按需渲染的宿主（编辑器）拿它标脏；每帧真画的预览不传 */
     importData(data: MktMeshData, projName?: string, onModelLoad?: () => void): void;
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
+    /**
+     * 把**存档里前 `PANO_IMPORT_PRIORITY` 个全景**按存档顺序登记进拼合器的**加载任务队列**
+     *（2026-10-29 需求「优先加载前 2 个全景素材」+ 2026-10-30 需求逐字：「给 mktmesh 内部加一个加载任务队列，
+     *  把模型和平面图排在最前面，然后按照顺序，依次把前 2 个全景的顺序把瓦片加载任务添加到任务队列里面，
+     *  第一个加载完了，就把这个加载任务从任务队列里面去掉，然后加载第二个；
+     *  如果后续再按照距离计算需要加载哪个全景的时候，同样地添加到加载任务队列的后面等待加载」）。
+     * 由两处渲染循环每帧点一次：基类 `onBeforeRender`（预览弹窗 / 发布页）与编辑器的 `updateFloorTexture`
+     *（`MktDevMesh` 覆写了 `onBeforeRender`，只点 `syncProjInvMatrix` + `tickProgressiveReveal`，库内那句在编辑态不跑）。
+     *
+     * 队列怎么排（`panoTileStitcher` 的 `_queue`，一处排队一张尺）：
+     *   ① **模型与平面图天然在最前面** —— 这两族的下载不在拼合器里，`importData` 当场同步发起
+     *      （GLB 逐只 `loadModel` 不 throttle；平面那 4 片一次性 `_imgTileLoader.preload`），
+     *      而全景瓦片最早也要等下一帧的 `pump` 才发第一片 ⇒ 发起次序天然是「模型 → 平面图 → 全景」，
+     *      ⛔ 这里不再把它们塞进队列重复管一遍（塞了就是第二把尺）。
+     *   ② 本方法把存档 0 号、1 号依次 `prioritize` 进队列 ⇒ 拼合器每帧**只喂队首那一组**，
+     *      0 号 32 格全落定（画进 RT，或该格本就缺地址/判死）才出队、1 号才开始发第一片。
+     *      比 10-29 那版（只是把两批挪到在册顺序前面、额度仍被两批分摊）更硬：**第 1 颗独享额度，最快出全图**。
+     *   ③ 名册按距离点到的其他全景走 `feedFaceMapping` 里那句 `ensure(t.tiles)`（不带队列）⇒ 只入册、
+     *      排在队列后面等，队列空了才按在册顺序补料（现行口径不变）。
+     * ⚠️⚠️ 为什么每帧点而⛔ 只在 `importData` 里点一记：预览每开一次都换渲染器，`_switchRenderer` 把在册组
+     *   整份作废（队列里的键也在同一刻失效）；只在载入那次点名等于白点。本方法点在 `pump` 之后、名册逐槽
+     *   `ensure` 之前 ⇒ 每帧把这两记任务补回队列头部（`prioritize` 幂等，已在队列里就不挪，所以 0 号恒在 1 号前）。
+     * ⚠️ 代价如实记：
+     *   · 队列非空时**其他全景一片都不发** ⇒ 开机那几秒里，离注视点最近、但不在存档前两颗的那面墙会多灰一会儿。
+     *   · 一颗「永远下不完」的瓦片（下载失败还没累计到判死）会压住队列；判死阈值是解码失败 3 次
+     *     （`_dead`），退避重试期间队首不落定 ⇒ 第 2 颗跟着延后。真实数据里缺片是「地址为空/404」，
+     *     404 走三次即判死、那一格拼合涂灰 ⇒ 队列照样出清。
+     *   · 这两颗全景若本来不在开机那一刻的名册里，它们的瓦片与拼合槽 RT 会被**提前**建出来
+     *     （现行口径每颗全景 2 槽 × 6144² ≈ 384MB 显存）—— 组在运行中不淘汰，走进这两个景点迟早要建。
+     * ⚠️ 形态判据读 `this._panoTexMode`（整图形态那一档一张全景只有一张整图，走 `_texCache` 那条路，
+     *   走错档就是白下 32 片）⇒ 宿主若用自己那份形态变量（编辑器的 `store.panoTexMode`），
+     *   要在调 `importData` 之前先 `setPanoTexMode` 推进来，编辑器那侧已按此接线。
+     */
+    prefetchHeadPanoramas(): void;
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，2026-10-02 决定）、拼合器、平面图 / 模型 / 玻璃面三层、几何、材质 */
     dispose(): this;
 }

package/MktMesh/MktMesh.js

@@ -51,6 +51,9 @@ import { stripAssetHost, absAssetUrl } from "./assetUrl";
 import { ImagePlane } from "./imagePlane";
 import { ModelSlot } from "./modelSlot";
 import { ImagePlaneTileLoader } from "./imageTileLoader";
+/** 载入 JSON 时**优先**加载几个全景的素材（2026-10-29 需求「优先加载前 2 个全景图的素材，然后再加载其他的」）。
+ *  口径 = 存档 `textures` 数组的前 n 项；其余全景照常按每帧的槽位名册（离注视点最近 8 个）排队，只是排在它们后面。 */
+const PANO_IMPORT_PRIORITY = 2;
 export default class MktMesh extends Mesh {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
     textures = [];
@@ -247,6 +250,11 @@ export default class MktMesh extends Mesh {
             this._glRenderer = renderer;
             this.syncProjInvMatrix();
             this.updateTexture(camera);
+            // ⭐ 2026-10-29 需求「载入 json 优先加载前 2 个全景图的素材，然后再加载其他的」：必须点在
+            //   `updateTexture`（它里面那记 `pump` 是「第一次拿到 renderer ⇒ 在册组整份作废」的现场）之后、
+            //   `feedFaceMapping`（名册逐槽入册）之前 —— 顺序倒过来就是「名册在前、我们垫底」= 静默失效。
+            //   编辑态那份在 `MktDevMesh` 的宿主循环里照同一相对位置点（⛔ 别在这儿加第三处）。
+            this.prefetchHeadPanoramas();
             this.feedFaceMapping();
             this.tickProgressiveReveal();
         };
@@ -1360,8 +1368,53 @@ export default class MktMesh extends Mesh {
         })));
         this.setModels((data.models ?? []).map((d) => ({ ...d, url: d.url ? absAssetUrl(d.url, pn) : "" })), onModelLoad);
     }
+    /**
+     * 把**存档里前 `PANO_IMPORT_PRIORITY` 个全景**按存档顺序登记进拼合器的**加载任务队列**
+     *（2026-10-29 需求「优先加载前 2 个全景素材」+ 2026-10-30 需求逐字：「给 mktmesh 内部加一个加载任务队列，
+     *  把模型和平面图排在最前面，然后按照顺序，依次把前 2 个全景的顺序把瓦片加载任务添加到任务队列里面，
+     *  第一个加载完了，就把这个加载任务从任务队列里面去掉，然后加载第二个；
+     *  如果后续再按照距离计算需要加载哪个全景的时候，同样地添加到加载任务队列的后面等待加载」）。
+     * 由两处渲染循环每帧点一次：基类 `onBeforeRender`（预览弹窗 / 发布页）与编辑器的 `updateFloorTexture`
+     *（`MktDevMesh` 覆写了 `onBeforeRender`，只点 `syncProjInvMatrix` + `tickProgressiveReveal`，库内那句在编辑态不跑）。
+     *
+     * 队列怎么排（`panoTileStitcher` 的 `_queue`，一处排队一张尺）：
+     *   ① **模型与平面图天然在最前面** —— 这两族的下载不在拼合器里，`importData` 当场同步发起
+     *      （GLB 逐只 `loadModel` 不 throttle；平面那 4 片一次性 `_imgTileLoader.preload`），
+     *      而全景瓦片最早也要等下一帧的 `pump` 才发第一片 ⇒ 发起次序天然是「模型 → 平面图 → 全景」，
+     *      ⛔ 这里不再把它们塞进队列重复管一遍（塞了就是第二把尺）。
+     *   ② 本方法把存档 0 号、1 号依次 `prioritize` 进队列 ⇒ 拼合器每帧**只喂队首那一组**，
+     *      0 号 32 格全落定（画进 RT，或该格本就缺地址/判死）才出队、1 号才开始发第一片。
+     *      比 10-29 那版（只是把两批挪到在册顺序前面、额度仍被两批分摊）更硬：**第 1 颗独享额度，最快出全图**。
+     *   ③ 名册按距离点到的其他全景走 `feedFaceMapping` 里那句 `ensure(t.tiles)`（不带队列）⇒ 只入册、
+     *      排在队列后面等，队列空了才按在册顺序补料（现行口径不变）。
+     * ⚠️⚠️ 为什么每帧点而⛔ 只在 `importData` 里点一记：预览每开一次都换渲染器，`_switchRenderer` 把在册组
+     *   整份作废（队列里的键也在同一刻失效）；只在载入那次点名等于白点。本方法点在 `pump` 之后、名册逐槽
+     *   `ensure` 之前 ⇒ 每帧把这两记任务补回队列头部（`prioritize` 幂等，已在队列里就不挪，所以 0 号恒在 1 号前）。
+     * ⚠️ 代价如实记：
+     *   · 队列非空时**其他全景一片都不发** ⇒ 开机那几秒里，离注视点最近、但不在存档前两颗的那面墙会多灰一会儿。
+     *   · 一颗「永远下不完」的瓦片（下载失败还没累计到判死）会压住队列；判死阈值是解码失败 3 次
+     *     （`_dead`），退避重试期间队首不落定 ⇒ 第 2 颗跟着延后。真实数据里缺片是「地址为空/404」，
+     *     404 走三次即判死、那一格拼合涂灰 ⇒ 队列照样出清。
+     *   · 这两颗全景若本来不在开机那一刻的名册里，它们的瓦片与拼合槽 RT 会被**提前**建出来
+     *     （现行口径每颗全景 2 槽 × 6144² ≈ 384MB 显存）—— 组在运行中不淘汰，走进这两个景点迟早要建。
+     * ⚠️ 形态判据读 `this._panoTexMode`（整图形态那一档一张全景只有一张整图，走 `_texCache` 那条路，
+     *   走错档就是白下 32 片）⇒ 宿主若用自己那份形态变量（编辑器的 `store.panoTexMode`），
+     *   要在调 `importData` 之前先 `setPanoTexMode` 推进来，编辑器那侧已按此接线。
+     */
+    prefetchHeadPanoramas() {
+        const n = Math.min(PANO_IMPORT_PRIORITY, this.textures.length);
+        // 正着点：0 号先入队 ⇒ 队首是它，落定后才轮到 1 号（`prioritize` 对已在队列里的键不挪位置）
+        for (let i = 0; i < n; i++) {
+            const info = this.textures[i];
+            // 与 `feedFaceMapping` 里那一句同判据：真瓦片才进拼合器，整图形态进瓦片缓存
+            if (mktPanoTiledFlag(info.tiles, this._panoTexMode) === 1)
+                this._stitcher.prioritize(info.tiles);
+            else if (info.url)
+                this.ensureTileTexture(info.url, false);
+        }
+    }
     // ───────────────────────── 释放 ─────────────────────────
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，2026-10-02 决定）、拼合器、平面图 / 模型 / 玻璃面三层、几何、材质 */
     dispose() {
         // ⚠️ rt 虚拟键从不进 `_texCache`（拼合槽纹理由 `_stitcher` 自己持有并释放），这里清的都是本类下载的 Texture。
         // ⭐ 甲（2026-10-05）：`releasePanoTexture` 除 `dispose()` 外还要 `ImageBitmap.close()` —— 位图的原生内存

package/MktMesh/MktMesh.ts

@@ -72,6 +72,10 @@ import { ImagePlane, type ImagePlaneData } from "./imagePlane";
 import { ModelSlot, type ModelSlotData } from "./modelSlot";
 import { ImagePlaneTileLoader } from "./imageTileLoader";
 
+/** 载入 JSON 时**优先**加载几个全景的素材（2026-10-29 需求「优先加载前 2 个全景图的素材，然后再加载其他的」）。
+ *  口径 = 存档 `textures` 数组的前 n 项；其余全景照常按每帧的槽位名册（离注视点最近 8 个）排队，只是排在它们后面。 */
+const PANO_IMPORT_PRIORITY = 2;
+
 export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
     textures: MktTextureInfo[] = [];
@@ -272,6 +276,11 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             this._glRenderer = renderer;
             this.syncProjInvMatrix();
             this.updateTexture(camera as Camera);
+            // ⭐ 2026-10-29 需求「载入 json 优先加载前 2 个全景图的素材，然后再加载其他的」：必须点在
+            //   `updateTexture`（它里面那记 `pump` 是「第一次拿到 renderer ⇒ 在册组整份作废」的现场）之后、
+            //   `feedFaceMapping`（名册逐槽入册）之前 —— 顺序倒过来就是「名册在前、我们垫底」= 静默失效。
+            //   编辑态那份在 `MktDevMesh` 的宿主循环里照同一相对位置点（⛔ 别在这儿加第三处）。
+            this.prefetchHeadPanoramas();
             this.feedFaceMapping();
             this.tickProgressiveReveal();
         };
@@ -1398,9 +1407,53 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         );
     }
 
+    /**
+     * 把**存档里前 `PANO_IMPORT_PRIORITY` 个全景**按存档顺序登记进拼合器的**加载任务队列**
+     *（2026-10-29 需求「优先加载前 2 个全景素材」+ 2026-10-30 需求逐字：「给 mktmesh 内部加一个加载任务队列，
+     *  把模型和平面图排在最前面，然后按照顺序，依次把前 2 个全景的顺序把瓦片加载任务添加到任务队列里面，
+     *  第一个加载完了，就把这个加载任务从任务队列里面去掉，然后加载第二个；
+     *  如果后续再按照距离计算需要加载哪个全景的时候，同样地添加到加载任务队列的后面等待加载」）。
+     * 由两处渲染循环每帧点一次：基类 `onBeforeRender`（预览弹窗 / 发布页）与编辑器的 `updateFloorTexture`
+     *（`MktDevMesh` 覆写了 `onBeforeRender`，只点 `syncProjInvMatrix` + `tickProgressiveReveal`，库内那句在编辑态不跑）。
+     *
+     * 队列怎么排（`panoTileStitcher` 的 `_queue`，一处排队一张尺）：
+     *   ① **模型与平面图天然在最前面** —— 这两族的下载不在拼合器里，`importData` 当场同步发起
+     *      （GLB 逐只 `loadModel` 不 throttle；平面那 4 片一次性 `_imgTileLoader.preload`），
+     *      而全景瓦片最早也要等下一帧的 `pump` 才发第一片 ⇒ 发起次序天然是「模型 → 平面图 → 全景」，
+     *      ⛔ 这里不再把它们塞进队列重复管一遍（塞了就是第二把尺）。
+     *   ② 本方法把存档 0 号、1 号依次 `prioritize` 进队列 ⇒ 拼合器每帧**只喂队首那一组**，
+     *      0 号 32 格全落定（画进 RT，或该格本就缺地址/判死）才出队、1 号才开始发第一片。
+     *      比 10-29 那版（只是把两批挪到在册顺序前面、额度仍被两批分摊）更硬：**第 1 颗独享额度，最快出全图**。
+     *   ③ 名册按距离点到的其他全景走 `feedFaceMapping` 里那句 `ensure(t.tiles)`（不带队列）⇒ 只入册、
+     *      排在队列后面等，队列空了才按在册顺序补料（现行口径不变）。
+     * ⚠️⚠️ 为什么每帧点而⛔ 只在 `importData` 里点一记：预览每开一次都换渲染器，`_switchRenderer` 把在册组
+     *   整份作废（队列里的键也在同一刻失效）；只在载入那次点名等于白点。本方法点在 `pump` 之后、名册逐槽
+     *   `ensure` 之前 ⇒ 每帧把这两记任务补回队列头部（`prioritize` 幂等，已在队列里就不挪，所以 0 号恒在 1 号前）。
+     * ⚠️ 代价如实记：
+     *   · 队列非空时**其他全景一片都不发** ⇒ 开机那几秒里，离注视点最近、但不在存档前两颗的那面墙会多灰一会儿。
+     *   · 一颗「永远下不完」的瓦片（下载失败还没累计到判死）会压住队列；判死阈值是解码失败 3 次
+     *     （`_dead`），退避重试期间队首不落定 ⇒ 第 2 颗跟着延后。真实数据里缺片是「地址为空/404」，
+     *     404 走三次即判死、那一格拼合涂灰 ⇒ 队列照样出清。
+     *   · 这两颗全景若本来不在开机那一刻的名册里，它们的瓦片与拼合槽 RT 会被**提前**建出来
+     *     （现行口径每颗全景 2 槽 × 6144² ≈ 384MB 显存）—— 组在运行中不淘汰，走进这两个景点迟早要建。
+     * ⚠️ 形态判据读 `this._panoTexMode`（整图形态那一档一张全景只有一张整图，走 `_texCache` 那条路，
+     *   走错档就是白下 32 片）⇒ 宿主若用自己那份形态变量（编辑器的 `store.panoTexMode`），
+     *   要在调 `importData` 之前先 `setPanoTexMode` 推进来，编辑器那侧已按此接线。
+     */
+    prefetchHeadPanoramas(): void {
+        const n = Math.min(PANO_IMPORT_PRIORITY, this.textures.length);
+        // 正着点：0 号先入队 ⇒ 队首是它，落定后才轮到 1 号（`prioritize` 对已在队列里的键不挪位置）
+        for (let i = 0; i < n; i++) {
+            const info = this.textures[i];
+            // 与 `feedFaceMapping` 里那一句同判据：真瓦片才进拼合器，整图形态进瓦片缓存
+            if (mktPanoTiledFlag(info.tiles, this._panoTexMode) === 1) this._stitcher.prioritize(info.tiles);
+            else if (info.url) this.ensureTileTexture(info.url, false);
+        }
+    }
+
     // ───────────────────────── 释放 ─────────────────────────
 
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，2026-10-02 决定）、拼合器、平面图 / 模型 / 玻璃面三层、几何、材质 */
     dispose(): this {
         // ⚠️ rt 虚拟键从不进 `_texCache`（拼合槽纹理由 `_stitcher` 自己持有并释放），这里清的都是本类下载的 Texture。
         // ⭐ 甲（2026-10-05）：`releasePanoTexture` 除 `dispose()` 外还要 `ImageBitmap.close()` —— 位图的原生内存

package/MktMesh/panoBitmapTexture.d.ts

@@ -16,8 +16,11 @@ import { Texture } from "three";
  * 明说「已经翻过了」。1×2 像素对照实测：`<img>`+flipY=true 与 bitmap(flipY)+flipY=false 逐行一致。
  */
 /** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
- *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
- *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
+ *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（用户决定 2026-09-25），
+ *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。
+ *  ⭐ 这一步走的是原生 `fetch`，不经过 three 的 `Loader`，所以它**自己**向 `DefaultLoadingManager`
+ *  报一次 `itemStart` / `itemEnd`（失败再多一次 `itemError`，与 `FileLoader` 的口径一致）——
+ *  否则页面拿到的加载状态只算模型和 `TextureLoader` 那些路，全景切片的下载完全不在里面。 */
 export declare function loadPanoTexture(url: string): Promise<Texture>;
 /** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**
  *  （不像 `<img>` 能等 GC —— 一张 270MB 的位图挂着不关，切几轮全景就把进程吃爆）。

package/MktMesh/panoBitmapTexture.js

@@ -1,4 +1,4 @@
-import { Texture } from "three";
+import { DefaultLoadingManager, Texture } from "three";
 /**
  * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
  *
@@ -16,10 +16,14 @@ import { Texture } from "three";
  * 明说「已经翻过了」。1×2 像素对照实测：`<img>`+flipY=true 与 bitmap(flipY)+flipY=false 逐行一致。
  */
 /** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
- *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
- *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
+ *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（用户决定 2026-09-25），
+ *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。
+ *  ⭐ 这一步走的是原生 `fetch`，不经过 three 的 `Loader`，所以它**自己**向 `DefaultLoadingManager`
+ *  报一次 `itemStart` / `itemEnd`（失败再多一次 `itemError`，与 `FileLoader` 的口径一致）——
+ *  否则页面拿到的加载状态只算模型和 `TextureLoader` 那些路，全景切片的下载完全不在里面。 */
 export function loadPanoTexture(url) {
-    return fetch(url)
+    DefaultLoadingManager.itemStart(url);
+    const task = fetch(url)
         .then((res) => {
         if (!res.ok)
             throw new Error(`HTTP ${res.status}`);
@@ -38,6 +42,12 @@ export function loadPanoTexture(url) {
         tex.userData.url = url;
         return tex;
     });
+    // 一条 promise 只 settle 一次 ⇒ 开始/结束各报一次，两边都不会漏；reject 原样透给调用方。
+    task.then(() => DefaultLoadingManager.itemEnd(url), () => {
+        DefaultLoadingManager.itemError(url);
+        DefaultLoadingManager.itemEnd(url);
+    });
+    return task;
 }
 /** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**
  *  （不像 `<img>` 能等 GC —— 一张 270MB 的位图挂着不关，切几轮全景就把进程吃爆）。

package/MktMesh/panoBitmapTexture.ts

@@ -1,4 +1,4 @@
-import { Texture } from "three";
+import { DefaultLoadingManager, Texture } from "three";
 
 /**
  * ⭐ 甲（皇上旨 2026-10-05「你试试甲」）：一张全景图（整图 / 单片瓦片，现行 32 片/全景）的**异步解码**建纹理。
@@ -18,10 +18,14 @@ import { Texture } from "three";
  */
 
 /** 发起一张全景纹理的加载（下载 + 异步解码都在浏览器工作线程，主线程只拿结果）。
- *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（皇上旨 2026-09-25），
- *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。 */
+ *  与 `TextureLoader.load` 同口径：**不许**把这一步排进 `threeUtils` 的全局队列（用户决定 2026-09-25），
+ *  排队的是「上传那一句」，见两侧的 `_commitTileToShader`。
+ *  ⭐ 这一步走的是原生 `fetch`，不经过 three 的 `Loader`，所以它**自己**向 `DefaultLoadingManager`
+ *  报一次 `itemStart` / `itemEnd`（失败再多一次 `itemError`，与 `FileLoader` 的口径一致）——
+ *  否则页面拿到的加载状态只算模型和 `TextureLoader` 那些路，全景切片的下载完全不在里面。 */
 export function loadPanoTexture(url: string): Promise<Texture> {
-    return fetch(url)
+    DefaultLoadingManager.itemStart(url);
+    const task = fetch(url)
         .then((res) => {
             if (!res.ok) throw new Error(`HTTP ${res.status}`);
             return res.blob();
@@ -41,6 +45,15 @@ export function loadPanoTexture(url: string): Promise<Texture> {
             tex.userData.url = url;
             return tex;
         });
+    // 一条 promise 只 settle 一次 ⇒ 开始/结束各报一次，两边都不会漏；reject 原样透给调用方。
+    task.then(
+        () => DefaultLoadingManager.itemEnd(url),
+        () => {
+            DefaultLoadingManager.itemError(url);
+            DefaultLoadingManager.itemEnd(url);
+        }
+    );
+    return task;
 }
 
 /** 释放一张由 `loadPanoTexture` 建出来的纹理：`dispose()` 只退显存，**ImageBitmap 的原生内存要 `close()`**

package/MktMesh/panoTileStitcher.d.ts

@@ -7,8 +7,22 @@ import { type TileLayout } from "./mktShader";
 export interface PanoStitcher {
     /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做）。
      *  新增可选 `layout` 参数：缺省 = PANO_TILE_LAYOUT（全景 8×4 / 2 槽 / 6144×6144，2026-10-27 需求）；
-     *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。 */
+     *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。
+     *  ⚠️ 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` 且该槽一格都还没画时，
@@ -37,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;
     /** 仍在册的组还需要的地址（迟到的加载回调据此判断「这条已经没人要了，立刻释放」） */
@@ -75,6 +93,13 @@ export declare class PanoTileStitcher implements PanoStitcher {
      *  但它的瓦片是 1024²、被画进 1536² 的格子 = 1.5× 放大 ⇒ 发虚，那类老点仍要重传一次。
      *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null]` —— 槽数再变会漏改）。 */
     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;
@@ -86,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();
     /** 仍在册的组还需要的地址（迟到的加载回调据此判断「这条已经没人要了，立刻释放」） */
@@ -225,12 +231,12 @@ export class PanoTileStitcher {
         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))
-            return;
         const slotCount = L.slotCount;
         const cellsPerSlot = cellsPerSlotOf(L);
         this._groups.set(batch, {
@@ -246,6 +252,40 @@ export class PanoTileStitcher {
         });
         this._stamp++;
     }
+    /** 登记进加载任务队列（语义与排队规则见接口上那一段）。已在队列里 ⇒ 不挪（先登记的仍在前）。 */
+    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;
+        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 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
     peek(batch, slot, renderer) {
@@ -297,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/材质/空白纹理一并退掉 */
@@ -325,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（旨②「每一帧同样也是只载入一张新纹理
@@ -238,8 +240,22 @@ interface StitchGroup {
 export interface PanoStitcher {
     /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做）。
      *  新增可选 `layout` 参数：缺省 = PANO_TILE_LAYOUT（全景 8×4 / 2 槽 / 6144×6144，2026-10-27 需求）；
-     *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。 */
+     *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。
+     *  ⚠️ 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` 且该槽一格都还没画时，
@@ -269,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();
     /** 仍在册的组还需要的地址（迟到的加载回调据此判断「这条已经没人要了，立刻释放」） */
@@ -330,10 +350,10 @@ private _uploadQueued: Set<TileRec> = new Set();
         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)) return;
         const slotCount = L.slotCount;
         const cellsPerSlot = cellsPerSlotOf(L);
         this._groups.set(batch, {
@@ -350,6 +370,38 @@ private _uploadQueued: Set<TileRec> = new Set();
         this._stamp++;
     }
 
+    /** 登记进加载任务队列（语义与排队规则见接口上那一段）。已在队列里 ⇒ 不挪（先登记的仍在前）。 */
+    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` 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
     peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null {
@@ -401,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++;
     }
 
@@ -431,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-base",
-  "version": "2.0.192",
+  "version": "2.0.195",
   "description": "A Three.js extension library providing common 3D components, animations, materials, and utilities",
   "author": "xiaosihan",
   "publishConfig": {

package/threeLoader.js

@@ -28,6 +28,8 @@ class ThreeLoader extends EventDispatcher {
         };
         // 资源加载进度
         DefaultLoadingManager.onProgress = (url, loaded, total) => {
+            // 三个数一并转发：首页只认「还在不在加载」，弹窗一类要看进度
+            this.dispatchEvent({ type: "progress", url, loaded, total });
             if (loaded < total) {
                 this.dispatchEvent({ type: "loadding" });
             }

package/threeLoader.ts

@@ -32,6 +32,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
         };
         // 资源加载进度
         DefaultLoadingManager.onProgress = (url: string, loaded: number, total: number) => {
+            // 三个数一并转发：首页只认「还在不在加载」，弹窗一类要看进度
+            this.dispatchEvent({ type: "progress", url, loaded, total });
             if (loaded < total) {
                 this.dispatchEvent({ type: "loadding" });
             }