three-base 2.0.137 → 2.0.145

package/MktMesh/assetUrl.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 全景图片地址的「相对 ⇄ 绝对」互转 —— **零 import 纯函数**（护栏可用 esbuild 直接转译真跑）。
+ *
+ * ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」；
+ *    同日 18:46 补充「图片路径要相对路径，**前面不要有 `/`**」⇒ 落盘形态最终定为
+ *   **纯相对路径**（`three-base_upload/panorama/xxx_0.jpg`，⛔ 无前导 `/`），换来两件事：
+ *     ① 换域名 / 换环境部署时，已有存档与下载的 zip 不用改一字就能用；
+ *     ② 导出的 json 里不再写死机器名，人眼可读、可 diff。
+ *   为什么连前导 `/` 都不留：站点部署在子路径 `/three-base/` 下，相对路径随 `<base href>`
+ *   一起解析，换部署位置仍指到同一张图；根相对 `/xxx` 会被钉死在域名根，放到子目录就 404。
+ *
+ * ⛔ 代价必须在同一处偿还：落盘时剥了域名，**加载前就必须补回来**。
+ *   补的动作由 `MktMesh.importData()` 一处统一做（⛔ 不许在拼合器 / 预览 / UI 各补一份 ——
+ *   那就是老坑「旁路即失控」的重演）。同理，剥的动作只在 `MktMesh.exportData()` 一处。
+ *
+ * 🔒 两个函数必须满足两条硬性质（护栏 BR 组逐条真跑）：
+ *   - **幂等**：`strip(strip(x)) === strip(x)`、`abs(abs(x)) === abs(x)`
+ *     ⇒ 旧存档本来存的绝对地址绝不会被反复剥/补成一串 `https://host/https://host/...`
+ *   - **互逆**：`strip(abs(rel)) === rel`（相对 → 绝对 → 相对，回到原样）
+ * ⚠️ **向后兼容**：`absAssetUrl` 同时认「纯相对」与「旧存档的根相对」两种形态
+ *   （`/a/b.jpg` 也补成绝对）⇒ 上午发布前存下的那些存档**不必重存**也能正常加载。
+ *
+ * ⚠️ 本模块刻意**不 import 任何东西**（连 three 都不）：它是地址字符串规则，不是渲染代码，
+ *    保持零依赖才能被测试单独转译真跑。
+ */
+/** 资源公网域名（⛔ 与 `panoramaUpload.OSS_PUBLIC_HOST` 必须同值，护栏 BR ② 钉着两边一致） */
+export declare const MKT_ASSET_HOST = "https://www.3dkeshihua.com";
+/**
+ * 剥掉本站域名 ⇒ **纯相对路径**（⭐ 皇上旨10-08 18:46「图片路径要相对路径，前面不要有 "/"」）。
+ * @param projName 项目名。给了 ⇒ 落盘成 `{项目名}/文件名.jpg`（19:53 旨）；没给 ⇒ 落成 `文件名.jpg`。
+ * - 已是相对 / 根相对 / blob / data / 别的域名 ⇒ **原样返回**（幂等，也保证旧存档安全）
+ * - `https://www.3dkeshihua.com/a/b.jpg` ⇒ `a/b.jpg`（⛔ 不带前导 `/`）
+ * - `https://www.3dkeshihua.com/three-base_upload/panorama/x_0.jpg` ⇒ `x_0.jpg` 或 `{proj}/x_0.jpg`
+ * - host 后面直接跟 `?` `#` 也认（OSS 地址可能带参），或直接到尾 ⇒ `""`（空串：无路径可留）
+ *
+ * ⚠️ 为何要「不带 `/`」：站点部署在子路径 `/three-base/` 下，相对路径能随
+ *   `<base href>` 一起解析，换部署位置仍指到同一张图；而根相对 `/xxx` 会被钉死在域名根，
+ *   放到子目录就404。
+ * ⚠️ 为何要顶掉上传目录前缀：落盘地址是给「换环境部署 / 交给别人」用的，
+ *   `three-base_upload/panorama` 是本项目的 OSS 内部目录，跟内容无关；顶成项目名后
+ *   「一个项目一套目录」的语义直接体现在地址里。
+ */
+export declare function stripAssetHost(url: string, projName?: string): string;
+/**
+ * 补回域名 ⇒ 绝对地址（加载前的唯一落点）。
+ * - 已是绝对 / blob / data ⇒ **原样返回**（幂等⇒ 旧存档进 `importData` 不会被二次拼接）
+ * - `a/b.jpg` ⇒ `https://www.3dkeshihua.com/a/b.jpg`
+ * - `/a/b.jpg`（旧存档的根相对形态）⇒ 同样认，补成绝对（**旧存档不必重存也能用**）
+ * - `{项目名}/x_0.jpg`（19:53 旨落盘形态）⇒ 还原成真身
+ *   `https://host/three-base_upload/panorama/x_0.jpg`
+ *   ⚠️ 落盘时顶掉了上传目录前缀，这里必须还原，否则 json 里的地址永远指不回原图。
+ *
+ * ⛔ 认错的后果（所以判据要严）：把「项目名段」误当成真目录，地址会指向**不存在的图**（图片裂开）；
+ *   漏认则地址多一段目录名，同样指不到图。两种都只影响显示、不会崩，所以宁可漏认不可误认 ——
+ *   判据 =「首段命中已知站点目录 ⇒ 一律不还原」+「首段等于传入项目名 ⇒ 才还原」。
+ *
+ * @param projName 项目名。**传了就以它为准**（最可靠）；没传则只认「首段是已知站点目录之外的名字」这一条。
+ */
+export declare function absAssetUrl(url: string, projName?: string): string;

package/MktMesh/assetUrl.js

@@ -0,0 +1,154 @@
+/**
+ * 全景图片地址的「相对 ⇄ 绝对」互转 —— **零 import 纯函数**（护栏可用 esbuild 直接转译真跑）。
+ *
+ * ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」；
+ *    同日 18:46 补充「图片路径要相对路径，**前面不要有 `/`**」⇒ 落盘形态最终定为
+ *   **纯相对路径**（`three-base_upload/panorama/xxx_0.jpg`，⛔ 无前导 `/`），换来两件事：
+ *     ① 换域名 / 换环境部署时，已有存档与下载的 zip 不用改一字就能用；
+ *     ② 导出的 json 里不再写死机器名，人眼可读、可 diff。
+ *   为什么连前导 `/` 都不留：站点部署在子路径 `/three-base/` 下，相对路径随 `<base href>`
+ *   一起解析，换部署位置仍指到同一张图；根相对 `/xxx` 会被钉死在域名根，放到子目录就 404。
+ *
+ * ⛔ 代价必须在同一处偿还：落盘时剥了域名，**加载前就必须补回来**。
+ *   补的动作由 `MktMesh.importData()` 一处统一做（⛔ 不许在拼合器 / 预览 / UI 各补一份 ——
+ *   那就是老坑「旁路即失控」的重演）。同理，剥的动作只在 `MktMesh.exportData()` 一处。
+ *
+ * 🔒 两个函数必须满足两条硬性质（护栏 BR 组逐条真跑）：
+ *   - **幂等**：`strip(strip(x)) === strip(x)`、`abs(abs(x)) === abs(x)`
+ *     ⇒ 旧存档本来存的绝对地址绝不会被反复剥/补成一串 `https://host/https://host/...`
+ *   - **互逆**：`strip(abs(rel)) === rel`（相对 → 绝对 → 相对，回到原样）
+ * ⚠️ **向后兼容**：`absAssetUrl` 同时认「纯相对」与「旧存档的根相对」两种形态
+ *   （`/a/b.jpg` 也补成绝对）⇒ 上午发布前存下的那些存档**不必重存**也能正常加载。
+ *
+ * ⚠️ 本模块刻意**不 import 任何东西**（连 three 都不）：它是地址字符串规则，不是渲染代码，
+ *    保持零依赖才能被测试单独转译真跑。
+ */
+/** 资源公网域名（⛔ 与 `panoramaUpload.OSS_PUBLIC_HOST` 必须同值，护栏 BR ② 钉着两边一致） */
+export const MKT_ASSET_HOST = "https://www.3dkeshihua.com";
+/** http 明文版 host：历史数据里可能存过这个形态，一并认，避免出现「剥不掉」的漏网地址 */
+const MKT_ASSET_HOST_HTTP = "http://www.3dkeshihua.com";
+/**
+ * 这些前缀的地址**不参与**剥/补 —— 它们压根不是远端资源：
+ * `blob:` 是本地内存里的 File/ObjectURL，`data:` 是内联字节，补域名只会把它们弄坏。
+ */
+function isLocalUrl(url) {
+    return url.startsWith("blob:") || url.startsWith("data:");
+}
+/** 是不是「路径式地址」（相对 `three-base_upload/xxx` 或根相对 `/three-base_upload/xxx`；`//host/x` 是协议相对 = 绝对，不算） */
+function isPathLike(url) {
+    return !url.startsWith("//") && (url.startsWith("/") || !/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(url));
+}
+/**
+ * OSS 上传目录前缀（`three-base_upload/panorama/…`）⇒ 落盘时整段丢掉，只留**文件名**。
+ * ⭐ 皇上旨10-08 19:53「导出时图片地址改成 `{项目名称}/xxx.jpg`」⇒ 这一段要被**项目名**顶替。
+ * 取不到项目名时（库内直接调 `exportData()` 而没传）**仍按老口径剥成纯相对**（不退回带`/` 的形态）。
+ */
+/** OSS 上传目录（`three-base_upload/panorama/`）——⛔ **不带尾斜杠**（拼接时自己补 `/`，否则会拼出双斜杠） */
+const UPLOAD_DIR_PREFIX = "three-base_upload";
+/** 上传目录的**完整**两级路径（还原时用） */
+const UPLOAD_FULL_PREFIX = `${UPLOAD_DIR_PREFIX}/panorama`;
+/**
+ * 本桶上「不是资源目录」的一级目录名—— 命中它们就说明是**站点自身路径**，不是项目名。
+ *（`three-base/` = 站点根，`three-base_upload/` = 资源上传根；两者都是固定目录，与项目名无关。）
+ */
+const KNOWN_TOP_DIRS = [UPLOAD_DIR_PREFIX, "three-base"];
+/** 首段看起来像「项目名」（= 不是已知站点目录）—— `strip` 与 `abs` 两侧**必须用同一把尺**，否则闭环对不上 */
+function segs0IsProjectDir(seg0) {
+    return seg0.length > 0 && !KNOWN_TOP_DIRS.includes(seg0);
+}
+/**
+ * 文件名安全化（与 `projectZipLayout.safeFileSegment` **逐字同口径**，两处必须同步 ——
+ * 一个存 json 里的地址、一个存zip 里的目录名，规则不一致会让「按 json 里的地址去 zip 找图」扑空）。
+ * Windows 与URL 都待见的字符 → 下划线；空名回落。
+ */
+function safeSeg(name) {
+    const s = (name || "").replace(/[\\/:*?"<>|]+/g, "_").trim();
+    return s.length > 0 ? s : "";
+}
+/**
+ * 剥掉本站域名 ⇒ **纯相对路径**（⭐ 皇上旨10-08 18:46「图片路径要相对路径，前面不要有 "/"」）。
+ * @param projName 项目名。给了 ⇒ 落盘成 `{项目名}/文件名.jpg`（19:53 旨）；没给 ⇒ 落成 `文件名.jpg`。
+ * - 已是相对 / 根相对 / blob / data / 别的域名 ⇒ **原样返回**（幂等，也保证旧存档安全）
+ * - `https://www.3dkeshihua.com/a/b.jpg` ⇒ `a/b.jpg`（⛔ 不带前导 `/`）
+ * - `https://www.3dkeshihua.com/three-base_upload/panorama/x_0.jpg` ⇒ `x_0.jpg` 或 `{proj}/x_0.jpg`
+ * - host 后面直接跟 `?` `#` 也认（OSS 地址可能带参），或直接到尾 ⇒ `""`（空串：无路径可留）
+ *
+ * ⚠️ 为何要「不带 `/`」：站点部署在子路径 `/three-base/` 下，相对路径能随
+ *   `<base href>` 一起解析，换部署位置仍指到同一张图；而根相对 `/xxx` 会被钉死在域名根，
+ *   放到子目录就404。
+ * ⚠️ 为何要顶掉上传目录前缀：落盘地址是给「换环境部署 / 交给别人」用的，
+ *   `three-base_upload/panorama` 是本项目的 OSS 内部目录，跟内容无关；顶成项目名后
+ *   「一个项目一套目录」的语义直接体现在地址里。
+ */
+export function stripAssetHost(url, projName) {
+    if (typeof url !== "string" || url === "")
+        return url;
+    if (isLocalUrl(url) || isPathLike(url))
+        return url;
+    for (const host of [MKT_ASSET_HOST, MKT_ASSET_HOST_HTTP]) {
+        if (!url.startsWith(host))
+            continue;
+        const rest = url.slice(host.length);
+        // host 是前缀但后面不是 path/query/fragment 的边界 ⇒ 不是本站资源（例如`...3dkeshihua.com.evil.com`）
+        if (rest !== "" && !/^[/?#]/.test(rest))
+            return url;
+        // 去掉前导 `/`：得到真正的相对路径（`/a/b.jpg` → `a/b.jpg`；`/` → `""`）
+        let path = rest.replace(/^\/+/, "");
+        // 上传目录前缀整段丢掉，只留文件名（query / fragment 原样跟在后面）
+        if (path === UPLOAD_DIR_PREFIX || path.startsWith(`${UPLOAD_DIR_PREFIX}/`)) {
+            const tail = path.slice(UPLOAD_DIR_PREFIX.length + 1); // 越过 `three-base_upload/` ⇒ `panorama/x_0.jpg`
+            const cut = tail.search(/[/?#]/); // 截到第一个分隔符（`/` `?` `#`）
+            // ⚠️ slice(cut) 会把那个分隔符一起带上（`panorama/x.jpg` → `/x.jpg`）⇒ 要 slice(cut+1)
+            const file = cut < 0 ? tail : tail.slice(cut + 1); // 文件名（含后面的 ?/#）
+            const dir = safeSeg(projName ?? "");
+            path = dir ? `${dir}/${file}` : file;
+            return path;
+        }
+        // ⭐ 幂等对称：`{项目名}/x.jpg` 这种**已顶替过**的形态（还原回绝对后再剥）要认出来，
+        //   否则项目名段会被原样留着、形态跟首轮落盘的不一致 ⇒ 导出→导入→导出闭环对不上。
+        //   判据 = 首段既不是已知站点目录、也不是上传目录（与 `absAssetUrl` 的还原判据镜像）。
+        const seg0 = path.split("/")[0];
+        if (segs0IsProjectDir(seg0)) {
+            const tail = path.slice(seg0.length + 1); // 越过 `{项目名}/`
+            const dir = safeSeg(projName ?? "");
+            // 传了项目名且首段与它一致 ⇒ 剥掉首段还原成裸文件名（无项目名时的落盘形态）
+            if (dir && seg0 === dir)
+                return tail;
+            // 没传项目名 ⇒ 首段无从确认是不是项目名，⛔ 原样留着（宁可多一段也不猜错）
+            return path;
+        }
+        return path;
+    }
+    return url;
+}
+/**
+ * 补回域名 ⇒ 绝对地址（加载前的唯一落点）。
+ * - 已是绝对 / blob / data ⇒ **原样返回**（幂等⇒ 旧存档进 `importData` 不会被二次拼接）
+ * - `a/b.jpg` ⇒ `https://www.3dkeshihua.com/a/b.jpg`
+ * - `/a/b.jpg`（旧存档的根相对形态）⇒ 同样认，补成绝对（**旧存档不必重存也能用**）
+ * - `{项目名}/x_0.jpg`（19:53 旨落盘形态）⇒ 还原成真身
+ *   `https://host/three-base_upload/panorama/x_0.jpg`
+ *   ⚠️ 落盘时顶掉了上传目录前缀，这里必须还原，否则 json 里的地址永远指不回原图。
+ *
+ * ⛔ 认错的后果（所以判据要严）：把「项目名段」误当成真目录，地址会指向**不存在的图**（图片裂开）；
+ *   漏认则地址多一段目录名，同样指不到图。两种都只影响显示、不会崩，所以宁可漏认不可误认 ——
+ *   判据 =「首段命中已知站点目录 ⇒ 一律不还原」+「首段等于传入项目名 ⇒ 才还原」。
+ *
+ * @param projName 项目名。**传了就以它为准**（最可靠）；没传则只认「首段是已知站点目录之外的名字」这一条。
+ */
+export function absAssetUrl(url, projName) {
+    if (typeof url !== "string" || url === "")
+        return url;
+    if (isLocalUrl(url) || !isPathLike(url))
+        return url;
+    const path = url.replace(/^\/+/, "");
+    const segs = path.split("/");
+    // 只在「恰好两段」且「首段不是已知站点目录」时，才按「项目名/文件名」还原
+    if (segs.length === 2 && !KNOWN_TOP_DIRS.includes(segs[0])) {
+        const dir = safeSeg(projName ?? "");
+        // 传了项目名就严格比它（最可靠）；没传才放宽到「非已知目录即可认」
+        if (!dir || segs[0] === dir)
+            return `${MKT_ASSET_HOST}/${UPLOAD_FULL_PREFIX}/${segs[1]}`;
+    }
+    return `${MKT_ASSET_HOST}/${path}`;
+}

package/MktMesh/assetUrl.ts

@@ -0,0 +1,155 @@
+/**
+ * 全景图片地址的「相对 ⇄ 绝对」互转 —— **零 import 纯函数**（护栏可用 esbuild 直接转译真跑）。
+ *
+ * ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」；
+ *    同日 18:46 补充「图片路径要相对路径，**前面不要有 `/`**」⇒ 落盘形态最终定为
+ *   **纯相对路径**（`three-base_upload/panorama/xxx_0.jpg`，⛔ 无前导 `/`），换来两件事：
+ *     ① 换域名 / 换环境部署时，已有存档与下载的 zip 不用改一字就能用；
+ *     ② 导出的 json 里不再写死机器名，人眼可读、可 diff。
+ *   为什么连前导 `/` 都不留：站点部署在子路径 `/three-base/` 下，相对路径随 `<base href>`
+ *   一起解析，换部署位置仍指到同一张图；根相对 `/xxx` 会被钉死在域名根，放到子目录就 404。
+ *
+ * ⛔ 代价必须在同一处偿还：落盘时剥了域名，**加载前就必须补回来**。
+ *   补的动作由 `MktMesh.importData()` 一处统一做（⛔ 不许在拼合器 / 预览 / UI 各补一份 ——
+ *   那就是老坑「旁路即失控」的重演）。同理，剥的动作只在 `MktMesh.exportData()` 一处。
+ *
+ * 🔒 两个函数必须满足两条硬性质（护栏 BR 组逐条真跑）：
+ *   - **幂等**：`strip(strip(x)) === strip(x)`、`abs(abs(x)) === abs(x)`
+ *     ⇒ 旧存档本来存的绝对地址绝不会被反复剥/补成一串 `https://host/https://host/...`
+ *   - **互逆**：`strip(abs(rel)) === rel`（相对 → 绝对 → 相对，回到原样）
+ * ⚠️ **向后兼容**：`absAssetUrl` 同时认「纯相对」与「旧存档的根相对」两种形态
+ *   （`/a/b.jpg` 也补成绝对）⇒ 上午发布前存下的那些存档**不必重存**也能正常加载。
+ *
+ * ⚠️ 本模块刻意**不 import 任何东西**（连 three 都不）：它是地址字符串规则，不是渲染代码，
+ *    保持零依赖才能被测试单独转译真跑。
+ */
+
+/** 资源公网域名（⛔ 与 `panoramaUpload.OSS_PUBLIC_HOST` 必须同值，护栏 BR ② 钉着两边一致） */
+export const MKT_ASSET_HOST = "https://www.3dkeshihua.com";
+
+/** http 明文版 host：历史数据里可能存过这个形态，一并认，避免出现「剥不掉」的漏网地址 */
+const MKT_ASSET_HOST_HTTP = "http://www.3dkeshihua.com";
+
+/**
+ * 这些前缀的地址**不参与**剥/补 —— 它们压根不是远端资源：
+ * `blob:` 是本地内存里的 File/ObjectURL，`data:` 是内联字节，补域名只会把它们弄坏。
+ */
+function isLocalUrl(url: string): boolean {
+    return url.startsWith("blob:") || url.startsWith("data:");
+}
+
+/** 是不是「路径式地址」（相对 `three-base_upload/xxx` 或根相对 `/three-base_upload/xxx`；`//host/x` 是协议相对 = 绝对，不算） */
+function isPathLike(url: string): boolean {
+    return !url.startsWith("//") && (url.startsWith("/") || !/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(url));
+}
+
+/**
+ * OSS 上传目录前缀（`three-base_upload/panorama/…`）⇒ 落盘时整段丢掉，只留**文件名**。
+ * ⭐ 皇上旨10-08 19:53「导出时图片地址改成 `{项目名称}/xxx.jpg`」⇒ 这一段要被**项目名**顶替。
+ * 取不到项目名时（库内直接调 `exportData()` 而没传）**仍按老口径剥成纯相对**（不退回带`/` 的形态）。
+ */
+/** OSS 上传目录（`three-base_upload/panorama/`）——⛔ **不带尾斜杠**（拼接时自己补 `/`，否则会拼出双斜杠） */
+const UPLOAD_DIR_PREFIX = "three-base_upload";
+/** 上传目录的**完整**两级路径（还原时用） */
+const UPLOAD_FULL_PREFIX = `${UPLOAD_DIR_PREFIX}/panorama`;
+/**
+ * 本桶上「不是资源目录」的一级目录名—— 命中它们就说明是**站点自身路径**，不是项目名。
+ *（`three-base/` = 站点根，`three-base_upload/` = 资源上传根；两者都是固定目录，与项目名无关。）
+ */
+const KNOWN_TOP_DIRS = [UPLOAD_DIR_PREFIX, "three-base"];
+
+/** 首段看起来像「项目名」（= 不是已知站点目录）—— `strip` 与 `abs` 两侧**必须用同一把尺**，否则闭环对不上 */
+function segs0IsProjectDir(seg0: string): boolean {
+    return seg0.length > 0 && !KNOWN_TOP_DIRS.includes(seg0);
+}
+
+/**
+ * 文件名安全化（与 `projectZipLayout.safeFileSegment` **逐字同口径**，两处必须同步 ——
+ * 一个存 json 里的地址、一个存zip 里的目录名，规则不一致会让「按 json 里的地址去 zip 找图」扑空）。
+ * Windows 与URL 都待见的字符 → 下划线；空名回落。
+ */
+function safeSeg(name: string): string {
+    const s = (name || "").replace(/[\\/:*?"<>|]+/g, "_").trim();
+    return s.length > 0 ? s : "";
+}
+
+/**
+ * 剥掉本站域名 ⇒ **纯相对路径**（⭐ 皇上旨10-08 18:46「图片路径要相对路径，前面不要有 "/"」）。
+ * @param projName 项目名。给了 ⇒ 落盘成 `{项目名}/文件名.jpg`（19:53 旨）；没给 ⇒ 落成 `文件名.jpg`。
+ * - 已是相对 / 根相对 / blob / data / 别的域名 ⇒ **原样返回**（幂等，也保证旧存档安全）
+ * - `https://www.3dkeshihua.com/a/b.jpg` ⇒ `a/b.jpg`（⛔ 不带前导 `/`）
+ * - `https://www.3dkeshihua.com/three-base_upload/panorama/x_0.jpg` ⇒ `x_0.jpg` 或 `{proj}/x_0.jpg`
+ * - host 后面直接跟 `?` `#` 也认（OSS 地址可能带参），或直接到尾 ⇒ `""`（空串：无路径可留）
+ *
+ * ⚠️ 为何要「不带 `/`」：站点部署在子路径 `/three-base/` 下，相对路径能随
+ *   `<base href>` 一起解析，换部署位置仍指到同一张图；而根相对 `/xxx` 会被钉死在域名根，
+ *   放到子目录就404。
+ * ⚠️ 为何要顶掉上传目录前缀：落盘地址是给「换环境部署 / 交给别人」用的，
+ *   `three-base_upload/panorama` 是本项目的 OSS 内部目录，跟内容无关；顶成项目名后
+ *   「一个项目一套目录」的语义直接体现在地址里。
+ */
+export function stripAssetHost(url: string, projName?: string): string {
+    if (typeof url !== "string" || url === "") return url;
+    if (isLocalUrl(url) || isPathLike(url)) return url;
+    for (const host of [MKT_ASSET_HOST, MKT_ASSET_HOST_HTTP]) {
+        if (!url.startsWith(host)) continue;
+        const rest = url.slice(host.length);
+        // host 是前缀但后面不是 path/query/fragment 的边界 ⇒ 不是本站资源（例如`...3dkeshihua.com.evil.com`）
+        if (rest !== "" && !/^[/?#]/.test(rest)) return url;
+        // 去掉前导 `/`：得到真正的相对路径（`/a/b.jpg` → `a/b.jpg`；`/` → `""`）
+        let path = rest.replace(/^\/+/, "");
+        // 上传目录前缀整段丢掉，只留文件名（query / fragment 原样跟在后面）
+        if (path === UPLOAD_DIR_PREFIX || path.startsWith(`${UPLOAD_DIR_PREFIX}/`)) {
+            const tail = path.slice(UPLOAD_DIR_PREFIX.length + 1); // 越过 `three-base_upload/` ⇒ `panorama/x_0.jpg`
+            const cut = tail.search(/[/?#]/);                        // 截到第一个分隔符（`/` `?` `#`）
+            // ⚠️ slice(cut) 会把那个分隔符一起带上（`panorama/x.jpg` → `/x.jpg`）⇒ 要 slice(cut+1)
+            const file = cut < 0 ? tail : tail.slice(cut + 1);        // 文件名（含后面的 ?/#）
+            const dir = safeSeg(projName ?? "");
+            path = dir ? `${dir}/${file}` : file;
+            return path;
+        }
+        // ⭐ 幂等对称：`{项目名}/x.jpg` 这种**已顶替过**的形态（还原回绝对后再剥）要认出来，
+        //   否则项目名段会被原样留着、形态跟首轮落盘的不一致 ⇒ 导出→导入→导出闭环对不上。
+        //   判据 = 首段既不是已知站点目录、也不是上传目录（与 `absAssetUrl` 的还原判据镜像）。
+        const seg0 = path.split("/")[0];
+        if (segs0IsProjectDir(seg0)) {
+            const tail = path.slice(seg0.length + 1); // 越过 `{项目名}/`
+            const dir = safeSeg(projName ?? "");
+            // 传了项目名且首段与它一致 ⇒ 剥掉首段还原成裸文件名（无项目名时的落盘形态）
+            if (dir && seg0 === dir) return tail;
+            // 没传项目名 ⇒ 首段无从确认是不是项目名，⛔ 原样留着（宁可多一段也不猜错）
+            return path;
+        }
+        return path;
+    }
+    return url;
+}
+
+/**
+ * 补回域名 ⇒ 绝对地址（加载前的唯一落点）。
+ * - 已是绝对 / blob / data ⇒ **原样返回**（幂等⇒ 旧存档进 `importData` 不会被二次拼接）
+ * - `a/b.jpg` ⇒ `https://www.3dkeshihua.com/a/b.jpg`
+ * - `/a/b.jpg`（旧存档的根相对形态）⇒ 同样认，补成绝对（**旧存档不必重存也能用**）
+ * - `{项目名}/x_0.jpg`（19:53 旨落盘形态）⇒ 还原成真身
+ *   `https://host/three-base_upload/panorama/x_0.jpg`
+ *   ⚠️ 落盘时顶掉了上传目录前缀，这里必须还原，否则 json 里的地址永远指不回原图。
+ *
+ * ⛔ 认错的后果（所以判据要严）：把「项目名段」误当成真目录，地址会指向**不存在的图**（图片裂开）；
+ *   漏认则地址多一段目录名，同样指不到图。两种都只影响显示、不会崩，所以宁可漏认不可误认 ——
+ *   判据 =「首段命中已知站点目录 ⇒ 一律不还原」+「首段等于传入项目名 ⇒ 才还原」。
+ *
+ * @param projName 项目名。**传了就以它为准**（最可靠）；没传则只认「首段是已知站点目录之外的名字」这一条。
+ */
+export function absAssetUrl(url: string, projName?: string): string {
+    if (typeof url !== "string" || url === "") return url;
+    if (isLocalUrl(url) || !isPathLike(url)) return url;
+    const path = url.replace(/^\/+/, "");
+    const segs = path.split("/");
+    // 只在「恰好两段」且「首段不是已知站点目录」时，才按「项目名/文件名」还原
+    if (segs.length === 2 && !KNOWN_TOP_DIRS.includes(segs[0])) {
+        const dir = safeSeg(projName ?? "");
+        // 传了项目名就严格比它（最可靠）；没传才放宽到「非已知目录即可认」
+        if (!dir || segs[0] === dir) return `${MKT_ASSET_HOST}/${UPLOAD_FULL_PREFIX}/${segs[1]}`;
+    }
+    return `${MKT_ASSET_HOST}/${path}`;
+}

package/MktMesh/mktMappingShader.d.ts

@@ -0,0 +1,12 @@
+import { ShaderMaterial } from "three";
+/**
+ * 创建「全景序号直取」着色器材质（皇上旨 2026-09-29「三模式三 shader」之二）：
+ * 编辑器「映射设置模式」的墙材质 + **基类 MktMesh（发布/预览）的固定墙材质**
+ * （皇上旨：mktmesh 就只有按照 attribute 配置来显示全景这一种固定的 shader）。
+ * uniform 形状与 blend 工厂同档（panoramas[16]/textureMatrices[8]/weights[8]/uPanoTiled[8]）⇒
+ * 喂料复用 feedBlendProjection 的槽位指派路（feedFaceMapping），零新喂料路。
+ * uFloorCoreRadius/uFloorFadeRange/uFloorOpacity 三根本 shader 不读，但喂料统一入口会写 ⇒ JS 侧留着（静默忽略）。
+ */
+export declare function createMktFloorMappingShaderMaterial(options?: {
+    maxPano?: number;
+}): ShaderMaterial;

package/MktMesh/mktMappingShader.js

@@ -0,0 +1,139 @@
+/*
+ * 全景「序号直取」投射着色器（mapping shader）：MktMesh 基类（发布/预览）、
+ * 编辑器 mapping 档墙体、家具立方体三处共用。
+ *
+ * 取图口径：按几何 attribute aPanoIndex 在 panoIndices 槽里对号取图，不看距离、不看夹角。
+ * 与 blend / selected 共用同一份 floorVertexShader 与同一套采样口径（改采样两处同改）。
+ */
+import { BackSide, Matrix4, ShaderMaterial, Vector3 } from "three";
+import { createPlaceholderTexture, floorVertexShader, MKT_PANO_MAX_SLOTS, RT_STITCH_SLOT_COUNT } from "./mktShader";
+/**
+ * 序号直取片元（皇上旨 2026-09-29「三模式三 shader」之二）：
+ * 按三角面 aPanoIndex 在 panoIndices 槽里找对应全景纹理 —— **不看距离、不看夹角**（blend 那套打分/归约整段没有）。
+ * 槽内采样段（等距柱状投射 + 左右 2 张拼合槽 + 采样即线性、不再手动 pow 解码）与 blend **逐字同口径**；改采样口径两处同改。
+ * 未设序号 / 序号不在槽里 / 该槽瓦片没绑好（weights≤0）→ uFaceMissingColor 深灰兜底
+ * （皇上旨 09-28「装不下就深灰」；weights 闸是 09-29 拆分时补的 —— 原运行时分支没这道闸，
+ * 槽没绑好但序号命中会采到 vec3(0) 纯黑，深灰才是钦定兜底色）。
+ */
+function buildFloorMappingFragment(maxPano) {
+    // 每个全景点占 **2** 张拼合槽纹理（32 片每 16 片拼一张：左半幅 / 右半幅）⇒ 8 × 2 = 16 = sampler 硬顶
+    const tileCount = maxPano * RT_STITCH_SLOT_COUNT;
+    let slotCalc = ""; // 每槽各自采样出 linK（weights[k]>0 才采；没绑好保持 0，由 facePick 的 weights 闸兜成深灰）
+    let slotFacePick = ""; // 逐槽展开「panoIndices[k]==vPanoIndex 则取 lin{k}」（ANGLE 禁动态索引 ⇒ JS 常量展开）
+    for (let k = 0; k < maxPano; k++) {
+        const base = k * RT_STITCH_SLOT_COUNT; // 本点占 2 个连续纹理槽：base=k*2 .. base+1（顺序 [左半幅, 右半幅]）
+        slotFacePick += `
+        if (panoIndices[${k}] >= 0.0 && weights[${k}] > 0.0 && abs(panoIndices[${k}] - vPanoIndex) < 0.5) faceCol = lin${k};`;
+        slotCalc += `
+        // ── 点槽 ${k}（纹理 ${base}..${base + 1}）──
+        vec3 lin${k} = vec3(0.0);
+        if (weights[${k}] > 0.0) {
+            mat4 tm = textureMatrices[${k}];
+            vec3 texPos = tm[3].xyz;            // 投影中心 = 纹理矩阵位置
+            mat3 texRot = mat3(tm);             // 纹理朝向 = 旋转分量
+            vec3 dir = normalize(vProjPos - texPos);
+            dir = texRot * dir;                 // 转到纹理局部方向
+            float lon = atan(dir.z, dir.x);
+            float u = lon * 0.15915494309189535 + 0.5; // 经度 -> u
+            float lat = asin(clamp(dir.y, -1.0, 1.0));
+            // 等距柱状线性 v（= 全图 UV），与 blend / 单全景分支**逐字同口径**
+            float v = 0.5 + lat * 0.3183098861837907; // 1/PI
+            // 左右两半 -> 拼合槽下标 [左半幅=0, 右半幅=1]（每槽 = 8×4 网格里 4×4=16 片拼成，见 RT_STITCH_SLOT_TILES）
+            // ⭐ 10-06 晚旨：竖着不再分块 ⇒ 槽只随 u 走（与 blend / 单全景分支**逐字同口径**）
+            int tileIdx = (u >= 0.5) ? 1 : 0;
+            float localU = (u < 0.5) ? (u * 2.0) : (u * 2.0 - 1.0);
+            // ⛔ 纵向不再减半（槽就是全高）⇒ localV 恒等于 v；写成 2v/2v-1 = 纵向分辨率白丢一半
+            float localV = v;
+            // 🧩 该点这 2 槽装的是整图（whole 形态 / 没切过片）⇒ 还原成全图 UV 再采样（与 blend 逐字同口径）
+            float panoU = (uPanoTiled[${k}] > 0.5) ? localU : u;
+            float panoV = (uPanoTiled[${k}] > 0.5) ? localV : v;
+            // ⚠️ ANGLE(D3D) 禁止动态索引 sampler 数组：以下 2 个采样下标均为「base + 字面量」常量表达式，编译安全
+            // ⭐ 采样即线性（与单全景 / blend / selected 三路同一条口径，10-07 旨「色彩空间统一使用 liner」）：纹理都标了
+            //    colorSpace = SRGBColorSpace ⇒ 硬件上传成 SRGB8_ALPHA8、texture2D 已解码一次；
+            //    这里**不再手动 pow 解码**（那遍是二次解码 = 整体压暗），末端只编码一次 ⇒ 与源图逐字节还原。
+            if (tileIdx == 0) lin${k} = texture2D(panoramas[${base}], vec2(panoU, panoV)).rgb;
+            else lin${k} = texture2D(panoramas[${base + 1}], vec2(panoU, panoV)).rgb;
+        }`;
+    }
+    return /* glsl */ `
+    #include <logdepthbuf_pars_fragment>
+    uniform sampler2D panoramas[${tileCount}];
+    uniform mat4 textureMatrices[${maxPano}];
+    uniform float weights[${maxPano}];     // 该槽瓦片绑好了没（writeSlot 按账本写）
+    uniform float uPanoTiled[${maxPano}];
+    // ── 全景序号映射（皇上旨 2026-09-28）：本材质**只有这一种取图方式**（原 uFaceMappingMode 运行时分支已按
+    //    09-29「三模式三 shader」拆出成独立 shader）──
+    uniform float panoIndices[${maxPano}]; // 每个 slot 对应的「全景全局序号」（-1=空）
+    uniform vec3 uFaceMissingColor;        // 未设序号 / 序号不在槽里 / 槽没绑好 时的深灰兜底色（线性空间）
+    // 色彩空间只有一条路（10-07 旨「统一使用 liner」）：原 uniform float uColorSpace; + 那段 pow 分支已整条撤除（与 blend 同口径）
+    uniform float uPanoramaVisible;
+    varying vec3 vProjPos;
+    varying float vPanoIndex;
+    #ifdef USE_INSTANCING_COLOR
+    varying vec3 vInstanceColor;
+    #endif
+    void main() {
+        // ⭐ 先逐槽采样出 linK（weights[k]>0 才采；没绑好保持 vec3(0)，由下面 facePick 的 weights 闸兜成深灰）。
+        //    ⛔ 这一段必须先跑：下面 slotFacePick 直接引用 linK —— 漏插本段就是
+        //    「ERROR: 'lin0' : undeclared identifier」编译失败（2026-10-02 shader error 1282 的根因）。
+${slotCalc}
+        vec3 faceCol = uFaceMissingColor;  // 默认深灰（未设序号 vPanoIndex<0 / 不在 panoIndices 里 / 槽没绑好）
+${slotFacePick}
+        vec3 col = faceCol;
+        // 全景投射显隐：关闭时回落中性素色（与 blend 一致）
+        if (uPanoramaVisible < 0.5) col = vec3(0.78, 0.78, 0.80);
+        #ifdef USE_INSTANCING_COLOR
+            col *= vInstanceColor;
+        #endif
+        gl_FragColor = vec4(col, 1.0);
+        // 输出颜色空间编码：渲染到线性 RT（主编辑器后处理链）时 passthrough，渲染到 sRGB 屏幕（预览弹窗）时自动编码 sRGB
+        #include <colorspace_fragment>
+        #include <logdepthbuf_fragment>
+    }
+`;
+}
+/**
+ * 创建「全景序号直取」着色器材质（皇上旨 2026-09-29「三模式三 shader」之二）：
+ * 编辑器「映射设置模式」的墙材质 + **基类 MktMesh（发布/预览）的固定墙材质**
+ * （皇上旨：mktmesh 就只有按照 attribute 配置来显示全景这一种固定的 shader）。
+ * uniform 形状与 blend 工厂同档（panoramas[16]/textureMatrices[8]/weights[8]/uPanoTiled[8]）⇒
+ * 喂料复用 feedBlendProjection 的槽位指派路（feedFaceMapping），零新喂料路。
+ * uFloorCoreRadius/uFloorFadeRange/uFloorOpacity 三根本 shader 不读，但喂料统一入口会写 ⇒ JS 侧留着（静默忽略）。
+ */
+export function createMktFloorMappingShaderMaterial(options = {}) {
+    const maxPano = Math.min(options.maxPano ?? MKT_PANO_MAX_SLOTS, MKT_PANO_MAX_SLOTS);
+    const tileCount = maxPano * RT_STITCH_SLOT_COUNT; // 8 点 × 左/右 2 槽 = 16 = sampler 硬顶
+    const panoramas = [];
+    const matrices = [];
+    for (let i = 0; i < tileCount; i++)
+        panoramas.push(createPlaceholderTexture());
+    for (let i = 0; i < maxPano; i++)
+        matrices.push(new Matrix4());
+    return new ShaderMaterial({
+        uniforms: {
+            panoramas: { value: panoramas },
+            textureMatrices: { value: matrices },
+            weights: { value: new Float32Array(maxPano) },
+            uPanoTiled: { value: new Float32Array(maxPano).fill(1) },
+            panoIndices: { value: new Float32Array(maxPano).fill(-1) },
+            uFaceMissingColor: { value: new Vector3(0.18, 0.18, 0.18) },
+            // 喂料统一入口会写（见上注释）；本 shader 不读 ⇒ 声明在此只为喂料零分支
+            uFloorCoreRadius: { value: 4 },
+            uFloorFadeRange: { value: 4 },
+            uFloorOpacity: { value: 1 },
+            uPanoramaVisible: { value: 1 },
+            // 色彩空间只有一条路（10-07 旨「统一使用 liner」）⇒ 原 `uColorSpace: { value: 0 }` 已随那段 pow 分支整条撤除
+            // 投影空间逆矩阵：与 blend 同口径（顶点着色器共用 floorVertexShader）
+            uProjInvMatrix: { value: new Matrix4() },
+        },
+        vertexShader: floorVertexShader,
+        fragmentShader: buildFloorMappingFragment(maxPano),
+        // ⭐ 墙专用材质（基类 MktMesh = 预览/发布 + 编辑器 mapping 模式墙，**同一座工厂同一份参数**，
+        //   皇上旨 2026-10-07 明确以此为准）：shader 默认**反面显示**（BackSide），零厚度幕墙只画朝房间内的那一面。
+        //   地板走「仅显示选中」工厂、维持 DoubleSide；立方体 mapping 档与墙共用这份实例 ⇒ 朝向跟着墙（10-02 旨），
+        //   另两档另建一份并显式拉回 DoubleSide（见渲染器 `_applyDisplayMode`）。
+        side: BackSide,
+        transparent: false,
+        toneMapped: false,
+    });
+}