three-base 2.0.142 → 2.0.145

package/MktMesh/panoSlotBind.ts

@@ -1,153 +1,153 @@
-/*
- * @Author: xiaosihan
- * @Date: 2026-10-03
- * @Description: 「一个点槽（同一个全景点的 `RT_STITCH_SLOT_COUNT` 张瓦片）如何换绑进 shader」的**唯一**策略实现
- * （皇上旨 2026-10-03「整套搬进库（彻底同源）」）。
- *
- * ⭐ 2026-10-06 晚皇上旨「每个全景纹理由**左右 2 个 RT** 组成」⇒ 一个点槽的张数从 4 降到 **2**，
- *    同屏全景数从 4 涨到 **8**。本文件里所有「几张」一律由 `RT_STITCH_SLOT_COUNT` 派生，
- *    ⛔ 不许再出现字面量 4（槽数再变会漏改 —— 这正是当年两侧分家的老毛病）。
- *
- * 来历：这套判据原先只活在编辑态 `mktMeshEditRenderer._bindSlotTiles`（皇上旨 09-24「一张一张替换上去，别 4 张一起换」
- * + 09-25「未就绪整槽沿用上一批」+ 09-25「绝不让一张已显示的全景因为正在补第 3 格瓦片而整体退出」）。
- * 库侧（预览 / 发布态 `MktMesh.feedFaceMapping`）走的是另一套「齐活才写、矩阵无条件 copy」⇒ ① 换景点会闪一帧灰，
- * ② 图与投影矩阵可能来自**不同批**（旧图配新矩阵）。皇上看的是线上观感，两侧必须同一份代码，故整条搬进来。
- *
- * ⛔ 本文件是这个问题的**第一份也是唯一一份**实现：编辑器与库都只许「委托一行」并把各自的取图口注入进来。
- *    出现第二份 = 两侧又会分家（护栏里有反钉）。
- *
- * 依赖注入的原因：编辑器与库的纹理来源不同（编辑器有自己的 `_floorTexCache` + `threeUtils` 上传队列；
- * 库读自身那份），但「什么时候可以换、换要换几个、没换成该怎么办」这个**决策**必须完全一致 ⇒
- * 决策留在本文件，取货与占位纹理由 `deps` 交进来。
- */
-import type { ShaderMaterial, Texture } from "three";
-import { RT_STITCH_SLOT_COUNT, setMktPanoTiled } from "./mktShader";
-
-/** 取一张「已解码**且**已上传 GPU」的瓦片；未就绪要**当场**自行起载 / 排上传，然后返回 null。
- *  ⚠️ 语义硬约束（皇上旨 09-25「队列里的代码就是把加载好的纹理设进 shader 这一句」）：
- *     本回调**不许**做同步的重活（解码、上传、绑定判断都不许在 render 里现场发生），只负责「发起 + 报告就绪」。 */
-export interface PanoSlotBindDeps {
-    peek(key: string, original: boolean): Texture | null;
-    /** 整槽口径（**只**给跨形态翻转那一次用）：同一个点的 `RT_STITCH_SLOT_COUNT` 张一起要，缺的返回 null。
-     *  编辑器实现 = `_peekSlotGen`（带 `proxy:` 过渡档墓碑分支），库实现 = 逐张 `peek`；
-     *  「判不齐就整档不换」这个**决定**仍然只在本文件里下。 */
-    peekSlot(tiles: string[], original: boolean): (Texture | null)[];
-    /** 该槽从没成功绑过任何图时用来垫 sampler 的 1×1 占位（⛔ 空 sampler 会报错） */
-    placeholder: Texture;
-}
-
-/**
- * 「panoramas[i] 这一格认的是哪张瓦片地址」——逐张换绑的**账本**，按材质实例分 WeakMap 键。
- * 放模块级 ⇒ 编辑器与库**共一本账**（两侧材质是不同实例，天然不串味）；材质重建后自动从空账开始。
- */
-const slotTileKeys = new WeakMap<ShaderMaterial, string[]>();
-
-/** 取（必要时建）某材质的逐格地址账本；`len` = `panoramas.length`（= 点数 × `RT_STITCH_SLOT_COUNT`）。 */
-export function panoSlotTileKeys(mat: ShaderMaterial, len: number): string[] {
-    let keys = slotTileKeys.get(mat);
-    if (!keys) {
-        keys = new Array(len).fill("");
-        slotTileKeys.set(mat, keys);
-    }
-    return keys;
-}
-
-/**
- * 把一个「点槽」的 `RT_STITCH_SLOT_COUNT` 张瓦片换绑进 `panoramas[base .. base + RT_STITCH_SLOT_COUNT - 1]`。
- *
- * 返回 true = 本槽这一帧的图与点位**配好了**（调用方据此写投影矩阵）；false = 沿用上一批（调用方矩阵也别动）。
- *
- * ⚠️ 只有一条例外必须整槽同帧：`uPanoTiled` 是**按槽一个标记**（每点一个数，不是每张一个），
- *    它告诉着色器「这几个槽装的是左右两张拼合槽(1) 还是一张整图(0)」。跨形态那一次（瓦片 ↔ 整片、
- *    或某点压根没切过片）若逐张换，中间几帧会拿整图按半幅采（或反之）⇒ 瞬间拉伸错位。
- *    所以「目标形态 ≠ 本槽现有形态」时走整档判齐口径。
- * ⚠️ 同形态内也分两条路（09-25 治本）：**整槽换人**（有格正贴着另一批的真图 ⇒ 全部同帧换，判不齐一张都不动）与
- *    **逐张补格**（本槽空着或同一批地址还缺的格 ⇒ 到一张补一张）。
- *    「这一格认的是哪张地址」记在 `panoSlotTileKeys`，换人不成就连账本都不改，下一帧重试。
- */
-export function panoSlotBind(
-    mat: ShaderMaterial,
-    panos: Texture[],
-    base: number,
-    tiles: string[],
-    tiled: boolean,
-    slot: number | undefined,
-    deps: PanoSlotBindDeps,
-): boolean {
-    // 单全景材质的 uPanoTiled 是标量（写的时候忽略槽位）；融合/映射材质是每点一个的数组 ⇒ 读法两样，判定同一个。
-    const uv = mat.uniforms.uPanoTiled?.value as number | ArrayLike<number> | undefined;
-    const curTiled = uv === undefined ? tiled
-        : (typeof uv === "number" ? uv > 0.5 : (uv[slot ?? 0] as number) > 0.5);
-
-    if (curTiled !== tiled) {
-        // ── 跨形态：整槽判齐、一次写入、同一帧翻标记（见上面 ⚠️）──
-        //    ⭐ 09-28 旨「瓦片纹理不需要添加 oss 的参数」后，过渡缩图档与原图档下载的是**同一张图**，
-        //    「原图没齐先上缩图」的兜底只剩双下载 ⇒ 整条删除；判不齐就沿用上一批。
-        const ready = deps.peekSlot(tiles, tiled);
-        // ⛔ 判齐用「本点槽数」派生（不许写 `ready[0] && ready[1] && ready[2] && ready[3]`）
-        const all = ready.length >= RT_STITCH_SLOT_COUNT && ready.slice(0, RT_STITCH_SLOT_COUNT).every((t) => !!t);
-        if (all) {
-            const keys = panoSlotTileKeys(mat, panos.length);
-            for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-                panos[base + k] = ready[k] as Texture;
-                keys[base + k] = tiles[k];
-            }
-            // ⚠️ 纹理与形态标记必须同一帧落地（分叉过一次 = 整片形态按瓦片 UV 采整图 ⇒ 半幅拉伸）
-            setMktPanoTiled(mat, tiled ? 1 : 0, slot);
-            return true;
-        }
-        // 整档还没齐：本槽沿用上一批（sampler 读到 undefined 会报错，所以压根没绑过才填占位）
-        if (!panos[base]) {
-            const keys = panoSlotTileKeys(mat, panos.length);
-            for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-                panos[base + k] = deps.placeholder;
-                keys[base + k] = tiles[k];
-            }
-            setMktPanoTiled(mat, tiled ? 1 : 0, slot); // 占位是 1×1 素色，两种采法无差别，直接把标记对准目标
-        }
-        return false;
-    }
-
-    // ── 同形态 ──
-    const keys = panoSlotTileKeys(mat, panos.length);
-    // ⭐ 换人（皇上旨 09-25「绝不让一张已显示的全景因为正在补第 3 格瓦片而整体退出」）：
-    //    只要**有任何一格正贴着别的批次的真图**，本槽这次就是「整槽换人」⇒ 整槽所有张必须同帧落地，
-    //    判不齐就一张都不动（连账本也不动 ⇒ 下一帧照判「要换」继续重试，缺的那几张的下载/上传已由 `deps.peek` 当场发起）。
-    //    否则旧全景的第 1 张会配新全景的投影矩阵、且权重照给 ⇒ 墙上的图一会儿这张一会儿那张（正是他报的现象）。
-    let swapping = false;
-    for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-        const cur = panos[base + k];
-        if (cur && cur !== deps.placeholder && keys[base + k] !== tiles[k]) {
-            swapping = true;
-            break;
-        }
-    }
-    if (swapping) {
-        const got: (Texture | null)[] = [];
-        for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-            // ⭐ 09-28 旨后不再退缩图档（过渡档去参 = 同一张原图，兜底只剩双下载）
-            got.push(deps.peek(tiles[k], tiled));
-        }
-        if (!got.every((t) => !!t)) return false; // 沿用上一批：图 + 矩阵 + 账本一概留着
-        for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-            panos[base + k] = got[k] as Texture;
-            keys[base + k] = tiles[k];
-        }
-        return true;
-    }
-
-    // ── 逐张补格（皇上的口径）：走到这里说明本槽没有任何一格贴着别的批次的真图
-    //    ⇒ 不是「首次那几帧」（整槽都是 1×1 占位），就是「同一批地址里还缺的格」。
-    //    两种都各判各的、到一张补一张，缺的格露的是素色占位而非另一张全景 ⇒ 无需攒齐。──
-    let bound = false;
-    for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
-        const i = base + k;
-        // ⭐ 09-28 旨后不再退缩图档（过渡档去参 = 同一张原图，兜底只剩双下载）
-        const tex = deps.peek(tiles[k], tiled);
-        if (!tex) continue; // 还在路上（缺的这张已由 deps.peek 当场发起下载 / 排上传）
-        keys[i] = tiles[k];
-        if (panos[i] !== tex) panos[i] = tex;
-        bound = true;
-    }
-    return bound;
-}
+/*
+ * @Author: xiaosihan
+ * @Date: 2026-10-03
+ * @Description: 「一个点槽（同一个全景点的 `RT_STITCH_SLOT_COUNT` 张瓦片）如何换绑进 shader」的**唯一**策略实现
+ * （皇上旨 2026-10-03「整套搬进库（彻底同源）」）。
+ *
+ * ⭐ 2026-10-06 晚皇上旨「每个全景纹理由**左右 2 个 RT** 组成」⇒ 一个点槽的张数从 4 降到 **2**，
+ *    同屏全景数从 4 涨到 **8**。本文件里所有「几张」一律由 `RT_STITCH_SLOT_COUNT` 派生，
+ *    ⛔ 不许再出现字面量 4（槽数再变会漏改 —— 这正是当年两侧分家的老毛病）。
+ *
+ * 来历：这套判据原先只活在编辑态 `mktMeshEditRenderer._bindSlotTiles`（皇上旨 09-24「一张一张替换上去，别 4 张一起换」
+ * + 09-25「未就绪整槽沿用上一批」+ 09-25「绝不让一张已显示的全景因为正在补第 3 格瓦片而整体退出」）。
+ * 库侧（预览 / 发布态 `MktMesh.feedFaceMapping`）走的是另一套「齐活才写、矩阵无条件 copy」⇒ ① 换景点会闪一帧灰，
+ * ② 图与投影矩阵可能来自**不同批**（旧图配新矩阵）。皇上看的是线上观感，两侧必须同一份代码，故整条搬进来。
+ *
+ * ⛔ 本文件是这个问题的**第一份也是唯一一份**实现：编辑器与库都只许「委托一行」并把各自的取图口注入进来。
+ *    出现第二份 = 两侧又会分家（护栏里有反钉）。
+ *
+ * 依赖注入的原因：编辑器与库的纹理来源不同（编辑器有自己的 `_floorTexCache` + `threeUtils` 上传队列；
+ * 库读自身那份），但「什么时候可以换、换要换几个、没换成该怎么办」这个**决策**必须完全一致 ⇒
+ * 决策留在本文件，取货与占位纹理由 `deps` 交进来。
+ */
+import type { ShaderMaterial, Texture } from "three";
+import { RT_STITCH_SLOT_COUNT, setMktPanoTiled } from "./mktShader";
+
+/** 取一张「已解码**且**已上传 GPU」的瓦片；未就绪要**当场**自行起载 / 排上传，然后返回 null。
+ *  ⚠️ 语义硬约束（皇上旨 09-25「队列里的代码就是把加载好的纹理设进 shader 这一句」）：
+ *     本回调**不许**做同步的重活（解码、上传、绑定判断都不许在 render 里现场发生），只负责「发起 + 报告就绪」。 */
+export interface PanoSlotBindDeps {
+    peek(key: string, original: boolean): Texture | null;
+    /** 整槽口径（**只**给跨形态翻转那一次用）：同一个点的 `RT_STITCH_SLOT_COUNT` 张一起要，缺的返回 null。
+     *  编辑器实现 = `_peekSlotGen`（带 `proxy:` 过渡档墓碑分支），库实现 = 逐张 `peek`；
+     *  「判不齐就整档不换」这个**决定**仍然只在本文件里下。 */
+    peekSlot(tiles: string[], original: boolean): (Texture | null)[];
+    /** 该槽从没成功绑过任何图时用来垫 sampler 的 1×1 占位（⛔ 空 sampler 会报错） */
+    placeholder: Texture;
+}
+
+/**
+ * 「panoramas[i] 这一格认的是哪张瓦片地址」——逐张换绑的**账本**，按材质实例分 WeakMap 键。
+ * 放模块级 ⇒ 编辑器与库**共一本账**（两侧材质是不同实例，天然不串味）；材质重建后自动从空账开始。
+ */
+const slotTileKeys = new WeakMap<ShaderMaterial, string[]>();
+
+/** 取（必要时建）某材质的逐格地址账本；`len` = `panoramas.length`（= 点数 × `RT_STITCH_SLOT_COUNT`）。 */
+export function panoSlotTileKeys(mat: ShaderMaterial, len: number): string[] {
+    let keys = slotTileKeys.get(mat);
+    if (!keys) {
+        keys = new Array(len).fill("");
+        slotTileKeys.set(mat, keys);
+    }
+    return keys;
+}
+
+/**
+ * 把一个「点槽」的 `RT_STITCH_SLOT_COUNT` 张瓦片换绑进 `panoramas[base .. base + RT_STITCH_SLOT_COUNT - 1]`。
+ *
+ * 返回 true = 本槽这一帧的图与点位**配好了**（调用方据此写投影矩阵）；false = 沿用上一批（调用方矩阵也别动）。
+ *
+ * ⚠️ 只有一条例外必须整槽同帧：`uPanoTiled` 是**按槽一个标记**（每点一个数，不是每张一个），
+ *    它告诉着色器「这几个槽装的是左右两张拼合槽(1) 还是一张整图(0)」。跨形态那一次（瓦片 ↔ 整片、
+ *    或某点压根没切过片）若逐张换，中间几帧会拿整图按半幅采（或反之）⇒ 瞬间拉伸错位。
+ *    所以「目标形态 ≠ 本槽现有形态」时走整档判齐口径。
+ * ⚠️ 同形态内也分两条路（09-25 治本）：**整槽换人**（有格正贴着另一批的真图 ⇒ 全部同帧换，判不齐一张都不动）与
+ *    **逐张补格**（本槽空着或同一批地址还缺的格 ⇒ 到一张补一张）。
+ *    「这一格认的是哪张地址」记在 `panoSlotTileKeys`，换人不成就连账本都不改，下一帧重试。
+ */
+export function panoSlotBind(
+    mat: ShaderMaterial,
+    panos: Texture[],
+    base: number,
+    tiles: string[],
+    tiled: boolean,
+    slot: number | undefined,
+    deps: PanoSlotBindDeps,
+): boolean {
+    // 单全景材质的 uPanoTiled 是标量（写的时候忽略槽位）；融合/映射材质是每点一个的数组 ⇒ 读法两样，判定同一个。
+    const uv = mat.uniforms.uPanoTiled?.value as number | ArrayLike<number> | undefined;
+    const curTiled = uv === undefined ? tiled
+        : (typeof uv === "number" ? uv > 0.5 : (uv[slot ?? 0] as number) > 0.5);
+
+    if (curTiled !== tiled) {
+        // ── 跨形态：整槽判齐、一次写入、同一帧翻标记（见上面 ⚠️）──
+        //    ⭐ 09-28 旨「瓦片纹理不需要添加 oss 的参数」后，过渡缩图档与原图档下载的是**同一张图**，
+        //    「原图没齐先上缩图」的兜底只剩双下载 ⇒ 整条删除；判不齐就沿用上一批。
+        const ready = deps.peekSlot(tiles, tiled);
+        // ⛔ 判齐用「本点槽数」派生（不许写 `ready[0] && ready[1] && ready[2] && ready[3]`）
+        const all = ready.length >= RT_STITCH_SLOT_COUNT && ready.slice(0, RT_STITCH_SLOT_COUNT).every((t) => !!t);
+        if (all) {
+            const keys = panoSlotTileKeys(mat, panos.length);
+            for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+                panos[base + k] = ready[k] as Texture;
+                keys[base + k] = tiles[k];
+            }
+            // ⚠️ 纹理与形态标记必须同一帧落地（分叉过一次 = 整片形态按瓦片 UV 采整图 ⇒ 半幅拉伸）
+            setMktPanoTiled(mat, tiled ? 1 : 0, slot);
+            return true;
+        }
+        // 整档还没齐：本槽沿用上一批（sampler 读到 undefined 会报错，所以压根没绑过才填占位）
+        if (!panos[base]) {
+            const keys = panoSlotTileKeys(mat, panos.length);
+            for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+                panos[base + k] = deps.placeholder;
+                keys[base + k] = tiles[k];
+            }
+            setMktPanoTiled(mat, tiled ? 1 : 0, slot); // 占位是 1×1 素色，两种采法无差别，直接把标记对准目标
+        }
+        return false;
+    }
+
+    // ── 同形态 ──
+    const keys = panoSlotTileKeys(mat, panos.length);
+    // ⭐ 换人（皇上旨 09-25「绝不让一张已显示的全景因为正在补第 3 格瓦片而整体退出」）：
+    //    只要**有任何一格正贴着别的批次的真图**，本槽这次就是「整槽换人」⇒ 整槽所有张必须同帧落地，
+    //    判不齐就一张都不动（连账本也不动 ⇒ 下一帧照判「要换」继续重试，缺的那几张的下载/上传已由 `deps.peek` 当场发起）。
+    //    否则旧全景的第 1 张会配新全景的投影矩阵、且权重照给 ⇒ 墙上的图一会儿这张一会儿那张（正是他报的现象）。
+    let swapping = false;
+    for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+        const cur = panos[base + k];
+        if (cur && cur !== deps.placeholder && keys[base + k] !== tiles[k]) {
+            swapping = true;
+            break;
+        }
+    }
+    if (swapping) {
+        const got: (Texture | null)[] = [];
+        for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+            // ⭐ 09-28 旨后不再退缩图档（过渡档去参 = 同一张原图，兜底只剩双下载）
+            got.push(deps.peek(tiles[k], tiled));
+        }
+        if (!got.every((t) => !!t)) return false; // 沿用上一批：图 + 矩阵 + 账本一概留着
+        for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+            panos[base + k] = got[k] as Texture;
+            keys[base + k] = tiles[k];
+        }
+        return true;
+    }
+
+    // ── 逐张补格（皇上的口径）：走到这里说明本槽没有任何一格贴着别的批次的真图
+    //    ⇒ 不是「首次那几帧」（整槽都是 1×1 占位），就是「同一批地址里还缺的格」。
+    //    两种都各判各的、到一张补一张，缺的格露的是素色占位而非另一张全景 ⇒ 无需攒齐。──
+    let bound = false;
+    for (let k = 0; k < RT_STITCH_SLOT_COUNT; k++) {
+        const i = base + k;
+        // ⭐ 09-28 旨后不再退缩图档（过渡档去参 = 同一张原图，兜底只剩双下载）
+        const tex = deps.peek(tiles[k], tiled);
+        if (!tex) continue; // 还在路上（缺的这张已由 deps.peek 当场发起下载 / 排上传）
+        keys[i] = tiles[k];
+        if (panos[i] !== tex) panos[i] = tex;
+        bound = true;
+    }
+    return bound;
+}

package/MktMesh/panoSlotRoster.d.ts

@@ -1,22 +1,22 @@
-/** ⭐ 槽位「中心死区」（米）：离**锚点**（控制器中心点；发布页未注入时 = 相机位置）水平距离最近的那张是中心；挑战者必须比现任中心**近出这么多**才抢得走。
- *  没有死区 ⇒ 锚点停在两点的等距带附近每帧换中心 ⇒ 换中心 = 整组邻居重排 = 一整组瓦片重绑（正是 09-24/25 报的「切全景卡一下」）。
- *  定义在此是因为编辑态与库侧共用（全项目**只此一处**，两侧都 import 它）。 */
-export declare const PANO_SLOT_SWAP_MARGIN_M = 0.5;
-/** 一个候选：`t` 是全景点对象（存引用不存下标 —— 删点会让下标整体前移，引用不会认错人），`d` 是它到**锚点**的水平距离（锚点由调用方决定，本函数不认识它） */
-export interface PanoRosterCand<T> {
-    t: T;
-    d: number;
-}
-/**
- * 算出下一帧的槽位名册（**不修改传进来的 roster**，返回新数组）。
- * @param roster   当前名册（0 号槽 = 上一帧的中心），长度可以小于 maxSlots（内部按 undefined 补齐）
- * @param dists    本帧全部全景点及其到**锚点**的距离（锚点 = 调用方那把尺子的端点；⭐ 10-07 第二十一道旨后 = 控制器中心点），**数组顺序 = 全景列表顺序**（下标就是旨意里说的「几号全景」）
- * @param maxSlots shader 的槽位上限（= `MKT_PANO_MAX_SLOTS`；⭐ 2026-10-06 晚旨后是 **8**：8 点 × 每个全景
- *          左右 2 张 RT = 16 sampler 仍是 GLSL 物理上限。⛔ 本函数不许假设它恒等于 4）
- * @param margin   抢中心的死区（米，= `PANO_SLOT_SWAP_MARGIN_M`）
- * @returns 长度恒 = maxSlots 的新名册：**0 号槽 = 中心**，其余槽 = 列表里按序号一层层往外扩的那些
- *          （同一层先取离锚点更近那侧）。⭐ 10-07 旨「尽可能填满」⇒ 越界的序号不占格、外扩继续往有货那侧走，
- *          所以**填几格 = min(项目全景总数, maxSlots)**；只有列表里的人不够时才留空（= `undefined`）。
- *          中心没换人 ⇒ 在册的一格都不动，只把**空格**补上。
- */
-export declare function panoSlotRosterStep<T>(roster: (T | undefined)[], dists: PanoRosterCand<T>[], maxSlots: number, margin: number): (T | undefined)[];
+/** ⭐ 槽位「中心死区」（米）：离**锚点**（控制器中心点；发布页未注入时 = 相机位置）水平距离最近的那张是中心；挑战者必须比现任中心**近出这么多**才抢得走。
+ *  没有死区 ⇒ 锚点停在两点的等距带附近每帧换中心 ⇒ 换中心 = 整组邻居重排 = 一整组瓦片重绑（正是 09-24/25 报的「切全景卡一下」）。
+ *  定义在此是因为编辑态与库侧共用（全项目**只此一处**，两侧都 import 它）。 */
+export declare const PANO_SLOT_SWAP_MARGIN_M = 0.5;
+/** 一个候选：`t` 是全景点对象（存引用不存下标 —— 删点会让下标整体前移，引用不会认错人），`d` 是它到**锚点**的水平距离（锚点由调用方决定，本函数不认识它） */
+export interface PanoRosterCand<T> {
+    t: T;
+    d: number;
+}
+/**
+ * 算出下一帧的槽位名册（**不修改传进来的 roster**，返回新数组）。
+ * @param roster   当前名册（0 号槽 = 上一帧的中心），长度可以小于 maxSlots（内部按 undefined 补齐）
+ * @param dists    本帧全部全景点及其到**锚点**的距离（锚点 = 调用方那把尺子的端点；⭐ 10-07 第二十一道旨后 = 控制器中心点），**数组顺序 = 全景列表顺序**（下标就是旨意里说的「几号全景」）
+ * @param maxSlots shader 的槽位上限（= `MKT_PANO_MAX_SLOTS`；⭐ 2026-10-06 晚旨后是 **8**：8 点 × 每个全景
+ *          左右 2 张 RT = 16 sampler 仍是 GLSL 物理上限。⛔ 本函数不许假设它恒等于 4）
+ * @param margin   抢中心的死区（米，= `PANO_SLOT_SWAP_MARGIN_M`）
+ * @returns 长度恒 = maxSlots 的新名册：**0 号槽 = 中心**，其余槽 = 列表里按序号一层层往外扩的那些
+ *          （同一层先取离锚点更近那侧）。⭐ 10-07 旨「尽可能填满」⇒ 越界的序号不占格、外扩继续往有货那侧走，
+ *          所以**填几格 = min(项目全景总数, maxSlots)**；只有列表里的人不够时才留空（= `undefined`）。
+ *          中心没换人 ⇒ 在册的一格都不动，只把**空格**补上。
+ */
+export declare function panoSlotRosterStep<T>(roster: (T | undefined)[], dists: PanoRosterCand<T>[], maxSlots: number, margin: number): (T | undefined)[];