s3m-three 0.3.0 → 0.3.1

package/dist/tileset/S3MTileset.js

@@ -7,6 +7,8 @@
  *   命中阈值就请求 childTile，实现渐进式细化。
  */
 import { parseS3MB } from '../core/S3MBParser.js';
+import { composeLeafAtlas, expandTexblockRequestNames, parseS3MBlockGroups, parseTexblockSegments, rebuildBlockTextureState, unpackBlockTextures, } from '../core/S3MBlockParser.js';
+import { evaluateAtlasUpgrade } from '../core/AtlasUpgrade.js';
 function dirOf(url) {
     return url.slice(0, url.lastIndexOf('/') + 1);
 }
@@ -31,36 +33,135 @@ function resolveUrl(base, rel) {
     if (!rel)
         return null;
     try {
-        return new URL(rel, base).href;
+        return fixPathEncoding(new URL(rel, base).href);
     }
     catch {
         // base 不是合法绝对地址时，退化为手工拼接，避免静默拿到错误路径
-        return `${dirOf(base)}${rel}`;
+        return fixPathEncoding(`${dirOf(base)}${rel}`);
     }
 }
-/** 兼容解析 JSON 与 XML 格式的 SuperMap .scp / config 配置文件 */
-function parseConfigText(text) {
+/**
+ * 修补路径里没被编码、但会被服务端改写的字符。
+ *
+ * 最典型的是 `+`：OSGB 转 S3M 的缓存瓦片名就是 `Tile_+002_+001`，而 iServer 的 Java 侧
+ * 按 URLDecoder 解路径，未编码的 `+` 会变成空格 → 404「瓦片数据不存在」。
+ * new URL() 的序列化器认为 `+` 在 path 里是合法字符，所以不会替我们编码，必须自己补上。
+ * 只动 path，不动 query/hash：query 里的 `+` 本来就是空格的约定，改了反而换味。
+ */
+export function fixPathEncoding(url) {
+    if (!/[+ ]/.test(url))
+        return url;
+    const hashAt = url.indexOf('#');
+    const hash = hashAt < 0 ? '' : url.slice(hashAt);
+    const body = hashAt < 0 ? url : url.slice(0, hashAt);
+    const queryAt = body.indexOf('?');
+    const path = queryAt < 0 ? body : body.slice(0, queryAt);
+    const query = queryAt < 0 ? '' : body.slice(queryAt);
+    return `${path.replace(/\+/g, '%2B').replace(/ /g, '%20')}${query}${hash}`;
+}
+/** 每度对应的米数（等距圆柱近似），与 demo 里量测瓦片尺寸用的是同一套系数 */
+const METERS_PER_DEG_LAT = 110540;
+const METERS_PER_DEG_LON_EQUATOR = 111320;
+/**
+ * 判断 config.geoBounds 是不是一张「真的能用」的经纬度范围。
+ *
+ * 挡掉三种情况：字段缺失 / 非有限值；超出经纬度量级（OSGB 那类只给米制局部坐标的，
+ * 反算不出来就是这种）；以及退化成一条线或一个点的全 0 框。
+ * 退化框尤其危险：拿它去 fitBounds 会把视角甩到几内亚湾 (0,0)，
+ * 拿它去校验 position 又会把唯一正确的 position 判成异常。
+ */
+export function usableGeoBounds(b) {
+    if (!b || typeof b !== 'object')
+        return null;
+    const g = b;
+    const v = [g.left, g.bottom, g.right, g.top];
+    if (!v.every((n) => typeof n === 'number' && Number.isFinite(n)))
+        return null;
+    const { left, bottom, right, top } = g;
+    if (Math.abs(left) > 180 || Math.abs(right) > 180 || Math.abs(top) > 90 || Math.abs(bottom) > 90)
+        return null;
+    if (right === left && top === bottom)
+        return null;
+    return { left, bottom, right, top };
+}
+/**
+ * S3M 1.x（SuperMapCache）的子瓦地址。
+ *
+ * XML 的 RangeDataList 写的是切片时的原始文件名（`Tile_+002_+001_L16_0.osgb`），
+ * 而 iServer 实际发布的是**同名换 .s3m 后缀**、并且插在 `datas/<数据源>/data/path/` 下：
+ *   .../datas/Config/Tile_+002_+001/Tile_+002_+001.s3m                     ← 根
+ *   .../datas/Config/data/path/Tile_+002_+001/Tile_+002_+001_L16_0.s3m     ← 子
+ * 实测 L16/L17/L18 都是 200，`?sceneName=` 不参与寻址。
+ */
+export function s3m1ChildUrl(tileUrl, child) {
+    if (!child)
+        return null;
+    const name = child.replace(/\.(osgb|s3mb|s3m)$/i, '.s3m');
+    // 根瓦地址：  <前缀>/datas/<数据源>/<瓦片目录>/<文件名>.s3m
+    // 子瓦地址：  <前缀>/datas/<数据源>/data/path/<瓦片目录>/<子瓦名>.s3m
+    const parts = tileUrl.split('/');
+    const file = parts.pop() ?? '';
+    const dir = parts.pop() ?? '';
+    const datasIdx = parts.lastIndexOf('datas');
+    if (!file || !dir || datasIdx < 1) {
+        // 不像 datas/<ds>/<dir>/<file> 的结构，退回按父目录解析
+        return resolveUrl(dirOf(tileUrl), name);
+    }
+    // 父瓦自己就已经在 data/path 下面了（再往下细化），那只换文件名，别再插一层
+    const alreadyPath = parts[parts.length - 1] === 'path' && parts[parts.length - 2] === 'data';
+    const base = alreadyPath ? `${parts.join('/')}/${dir}` : `${parts.join('/')}/data/path/${dir}`;
+    return fixPathEncoding(`${base}/${name}`);
+}
+/** 兼容解析 JSON 与 XML 格式的 SuperMap .scp / config 配置文件（导出以便单测与自建数据集列表复用） */
+export function parseConfigText(text) {
     const trimmed = text.trim();
     if (trimmed.startsWith('<')) {
         const tagVal = (tag) => {
             const m = new RegExp(`<(?:[a-zA-Z0-9_-]+:)?${tag}[^>]*>([^<]+)<\\/`, 'i').exec(trimmed);
             return m ? m[1].trim() : null;
         };
-        const posX = parseFloat(tagVal('X') ?? '0');
-        const posY = parseFloat(tagVal('Y') ?? '0');
-        const posZ = parseFloat(tagVal('Z') ?? '0');
-        const left = parseFloat(tagVal('Left') ?? '0');
-        const right = parseFloat(tagVal('Right') ?? '0');
-        const top = parseFloat(tagVal('Top') ?? '0');
-        const bottom = parseFloat(tagVal('Bottom') ?? '0');
+        const num = (tag) => parseFloat(tagVal(tag) ?? '');
+        const posX = num('X') || 0;
+        const posY = num('Y') || 0;
+        const posZ = num('Z') || 0;
+        let left = num('Left');
+        let right = num('Right');
+        let top = num('Top');
+        let bottom = num('Bottom');
+        // SuperMapCache（OSGB 转出来的那类 XML）压根不给经纬度范围，只给
+        // 「以 Position 为原点、局部 ENU 米制」的 BoundingBox。不反算的话 geoBounds 就是
+        // 全 0：getBounds() 会把视角甩到几内亚湾，_resolveAnchor 还会反过来把正确的
+        // position 判成「与 geoBounds 不一致」而退回 (0,0)，位置错得彻彻底底。
+        if (![left, right, top, bottom].every(Number.isFinite)) {
+            const minX = num('MinX');
+            const maxX = num('MaxX');
+            const minY = num('MinY');
+            const maxY = num('MaxY');
+            if ([minX, maxX, minY, maxY].every(Number.isFinite) && posX && posY) {
+                const kx = METERS_PER_DEG_LON_EQUATOR * Math.cos((posY * Math.PI) / 180);
+                if (kx > 1e-6) {
+                    left = posX + minX / kx;
+                    right = posX + maxX / kx;
+                    bottom = posY + minY / METERS_PER_DEG_LAT;
+                    top = posY + maxY / METERS_PER_DEG_LAT;
+                }
+            }
+        }
         const fileMatches = trimmed.matchAll(/<(?:[a-zA-Z0-9_-]+:)?FileName[^>]*>([^<]+)<\//gi);
         const tiles = [];
         for (const m of fileMatches) {
             tiles.push({ url: m[1].trim() });
         }
+        // SuperMapCache 用 MinHeight/MaxHeight 声明成果的高程范围（米）。
+        // 不读出来的话 align: 'bottom' 无从计算 —— 这类 OSGB 数据的 z 是从 120m 起飞的，
+        // 不贴地就会整片悬在地图上方，斜视下看起来像散在别处的碎片。
+        const minH = num('MinHeight');
+        const maxH = num('MaxHeight');
         return {
+            fileType: tagVal('FileType') ?? undefined,
             position: { x: posX, y: posY, z: posZ, units: 'Degree' },
             geoBounds: { left, right, top, bottom },
+            heightRange: Number.isFinite(minH) || Number.isFinite(maxH) ? { min: minH, max: maxH } : undefined,
             rootTiles: tiles,
             tiles,
         };
@@ -70,12 +171,37 @@ function parseConfigText(text) {
 export class S3MTileset {
     configUrl;
     config = null;
+    /**
+     * S3MBLOCK 数据集的完整瓦片清单（config.tiles 解析成绝对 URL）。
+     * 这类数据的 pageLOD 会引用服务端并不存在的子块（LOD 树占位），
+     * 按清单过滤可以避免成片的 404。经典 scp 不建这个索引，行为不变。
+     */
+    _blockTileIndex = null;
     anchor = { lon: 0, lat: 0, height: 0 };
     rootUrls = [];
     nodes = new Map();
     failed = new Set();
     textureCache = new Map();
     pending = new Set();
+    /** 是否请求 `.texblock` 子图集，默认关，见 S3MTilesetOptions.atlasLod */
+    atlasLod;
+    /** 根图集 id → 已拉到的清晰版子图集；null = 正在请求或确认没有，避免重复发请求 */
+    atlasLodCache = new Map();
+    /** 块 URL → 该文件里的全部 LOD 组（一个 .s3mblock 是一棵子树，不是一块瓦片） */
+    _groupCache = new Map();
+    /** 独立 `.texblock` 图集缓存：id → 图像；null 表示正在请求或确认不可用 */
+    externalAtlasCache = new Map();
+    /**
+     * leaf 子请求缓存：去扩展名的子请求名（`Tex_0_000` / `Tile_6_000000`）→ 响应里的记录；
+     * null = 已判定不可用。精灵按全局共享（同名同内容），跨瓦片复用。
+     */
+    leafRequestCache = new Map();
+    /** 进行中的 leaf 请求（stem → Promise），跨瓦片并发时同名只发一次 */
+    _leafPending = new Map();
+    /** 真正被高清版顶替掉的图集 id（判定通过） */
+    atlasUpgraded = new Set();
+    /** 拿到高清版但判定不通过 → 原因。用于排查「为什么这块还是糊的」 */
+    atlasUpgradeSkipped = new Map();
     stats = { tiles: 0, loading: 0, failed: 0, meshes: 0, vertices: 0, triangles: 0, datasets: 1 };
     maxConcurrent;
     maxTiles;
@@ -99,13 +225,20 @@ export class S3MTileset {
     /** 子瓦片 URL → 父瓦片 URL，用于淘汰后补洞 */
     _parentOf = new Map();
     _frame = 0;
+    _lodDbgOnce = false;
+    /** 格式类永久错误只向上报一次，避免整棵瓦片树刷同样的日志 */
+    _permanentReported = false;
+    /** 请求量的硬上限（软上限 maxTiles 的超额余量），见构造函数注释 */
+    hardCap = 96;
+    /** 本数据集是 S3M 1.x（SuperMapCache，.s3m）：子瓦地址规则与 3.x 不同 */
+    isS3MV1 = false;
     _buildTile;
     _uniforms;
     _queue = [];
     _active = 0;
     constructor(options) {
         this.configUrl = options.configUrl;
-        this.lodRangeScale = options.lodRangeScale ?? 1.0;
+        this.lodRangeScale = options.lodRangeScale ?? 3.0;
         this._onTile = options.onTile ?? (() => { });
         this._onTileRemoved = options.onTileRemoved ?? (() => { });
         this._onError = options.onError ?? ((e) => console.warn(e));
@@ -118,6 +251,11 @@ export class S3MTileset {
         // 并发与总量限制：iServer 公开服务上别把人家打爆
         this.maxConcurrent = options.maxConcurrent ?? 4;
         this.maxTiles = options.maxTiles ?? 64;
+        // 硬上限 = 软上限 + 余量。淘汰只在「新瓦片已经落地并接管显示」之后做（make-before-break），
+        // 所以中间态允许临时超出 maxTiles；硬上限只用来挡住失控的请求量，不用于挤掉正在显示的内容。
+        this.hardCap = this.maxTiles + Math.max(8, Math.ceil(this.maxTiles * 0.5));
+        // 默认开启清晰版子图集：根图集是 level=0 的低清代理，拿它平铺就是一堆马赛克
+        this.atlasLod = options.atlasLod !== false;
     }
     async init() {
         this.configUrl = toAbsolute(this.configUrl);
@@ -138,6 +276,21 @@ export class S3MTileset {
             if (u)
                 this.rootUrls.push(u);
         }
+        // S3M 1.x（SuperMapCache，.s3m）容器：早点说清楚，别等几十块瓦片全失败才看出来。
+        // 位置与范围是按配置反算出来的，所以视角会正确落到模型上，只是这种容器还没接解码。
+        this.isS3MV1 =
+            /OSGB/i.test(String(config.fileType ?? '')) ||
+                /OSGB/i.test(String(config.dataType ?? '')) ||
+                (this.rootUrls.length > 0 && this.rootUrls.every((u) => /\.s3m($|\?)/i.test(u)));
+        // S3MBLOCK：config.tiles 就是全部瓦片，子引用超出清单的一律不请求
+        if (this.rootUrls.every((u) => /\.s3mblock($|\?)/i.test(u))) {
+            this._blockTileIndex = new Set(this.rootUrls);
+            for (const r of roots) {
+                const u = resolveUrl(this.configUrl, r.url);
+                if (u)
+                    this._blockTileIndex.add(u);
+            }
+        }
         // 首棵树同步加载，保证 init 返回时已有内容可渲染
         await this._load(this.rootUrls[0]);
         for (const r of this.rootUrls.slice(1))
@@ -157,11 +310,12 @@ export class S3MTileset {
         const retryAt = this._retryAt.get(url);
         if (retryAt !== undefined && performance.now() < retryAt)
             return;
-        // 满了就淘汰最久没被用到的，而不是干等着永远不再出图
-        while (this.nodes.size + this.pending.size >= this.maxTiles) {
-            if (!this._evictOne())
-                return;
-        }
+        // 不在这里淘汰！「为了塞新的先删旧的」会立刻在画面上开一个洞 —— 旧的已经没了、
+        // 新的还没下载完，而洞那块地下一帧又要靠它回补，于是「删 → 补 → 再删」就是闪烁。
+        // 改成 make-before-break：新瓦片落地并接管显示之后，再由 update() 末尾的
+        // _trimBudget() 统一裁。这里只用硬上限挡住失控的请求量。
+        if (this.nodes.size + this.pending.size + this._queue.length >= this.hardCap)
+            return;
         this._queue.push(url);
         this._pump();
     }
@@ -177,8 +331,9 @@ export class S3MTileset {
      * 两轮都按「最久没进有效范围」排，同帧再比距离。
      * 淘汰最细一级时，如果上一级也不在内存里，顺手把上一级排回队列补洞。
      */
-    _evictOne() {
-        const victim = this._pickVictim(false) ?? this._pickVictim(true);
+    _evictOne(allowUncovered = false) {
+        // 只挑安全候选：叶子 → 已被子瓦接手的父瓦。allowUncovered 仅在超出硬上限时开启（内存兜底）
+        const victim = this._pickVictim(false, allowUncovered) ?? this._pickVictim(true, allowUncovered);
         if (!victim)
             return false;
         const parentUrl = victim.parentUrl ?? this._parentOf.get(victim.url);
@@ -188,23 +343,82 @@ export class S3MTileset {
         victim.group.parent?.remove(victim.group);
         this._onTileRemoved(victim);
         this._parentOf.delete(victim.url);
+        // 淘汰的是中间层时，把已加载的子孙改挂到它的父级上：
+        // 不然它们瞬间"无父"，父级那边还留着指向 victim 的 childUrls，
+        // 于是 allChildrenReady 永远为假 —— 既显示不对，也白占预算。
+        const kids = childUrls.filter((u) => u !== victim.url && this.nodes.has(u));
+        if (kids.length) {
+            for (const k of kids) {
+                const kn = this.nodes.get(k);
+                if (!kn)
+                    continue;
+                kn.parentUrl = parentUrl ?? undefined;
+                if (parentUrl)
+                    this._parentOf.set(k, parentUrl);
+                else
+                    this._parentOf.delete(k);
+            }
+            if (parentUrl) {
+                const pn = this.nodes.get(parentUrl);
+                if (pn) {
+                    const merged = new Set(pn.childUrls ?? []);
+                    if (pn.childUrl)
+                        merged.add(pn.childUrl);
+                    merged.delete(victim.url);
+                    for (const k of kids)
+                        merged.add(k);
+                    pn.childUrls = [...merged];
+                    pn.childUrl = pn.childUrls[0] ?? null;
+                }
+            }
+        }
         // 删的是最细一级、而上一级又不在内存里 → 把上一级排回去，别让那块地空着
         if (isLeaf && parentUrl && !this.nodes.has(parentUrl) && !this.pending.has(parentUrl)) {
             this._enqueue(parentUrl);
         }
         return true;
     }
+    /**
+     * 预算裁剪 —— 必须在可见性算完之后调用（make-before-break）：
+     * 新瓦片已经落地、也已经决定由谁负责显示，这时候才把没人依赖的那块裁掉。
+     * 只踢「当前不显示」或「位置已被可见子瓦接手」的瓦片；挑不出安全候选时允许
+     * 暂时超出 maxTiles，等下一帧再裁 —— 宁可多占一会儿内存，也不在画面上开洞。
+     */
+    _trimBudget() {
+        let removed = false;
+        let guard = 0;
+        // 在途的也算进"预期驻留数"：不然一批瓦片同时落地时会先把画面撑爆再疯狂裁
+        while (this.nodes.size + this.pending.size > this.maxTiles && guard++ <= this.maxTiles + 8) {
+            if (!this._evictOne(this.nodes.size + this.pending.size > this.hardCap))
+                break;
+            removed = true;
+        }
+        return removed;
+    }
     /**
      * 挑淘汰候选。
-     * @param allowRefined false = 只挑叶子；true = 只挑「子节点已全部加载」的父瓦片
+     * @param allowRefined false = 只挑叶子；true = 也允许挑「子节点已全部加载」的父瓦片
+     * @param allowUncovered true = 允许淘汰「正在显示、但位置还没被子瓦接手」的瓦片。
+     *   默认 false：这种瓦片一踢，画面上立刻是一个洞，下一帧调度又会把它请回来补洞，
+     *   于是「淘汰 → 开洞 → 回补 → 再淘汰」无限循环 = 屏幕不停闪烁。
+     *   只有在实在挑不出安全候选时才允许（否则预算满死锁、相机移到哪都不出图）。
      */
-    _pickVictim(allowRefined) {
+    _pickVictim(allowRefined, allowUncovered = false) {
         let victim = null;
         for (const node of this.nodes.values()) {
             const childUrls = node.childUrls ?? (node.childUrl ? [node.childUrl] : []);
             const refined = childUrls.length > 0 && childUrls.some((u) => u !== node.url && this.nodes.has(u));
             if (refined !== allowRefined)
                 continue;
+            // 正在显示且没有可见子瓦接手 → 踢了就是洞
+            if (!allowUncovered && node.group.visible) {
+                const covered = childUrls.some((u) => {
+                    const c = this.nodes.get(u);
+                    return !!c && c.group.visible;
+                });
+                if (!covered)
+                    continue;
+            }
             if (!victim) {
                 victim = node;
                 continue;
@@ -238,18 +452,23 @@ export class S3MTileset {
      * 定位锚点。规范里 position 是局部 ENU 坐标系原点，
      * 但实际数据里 position 偶尔是生产时的占位值（与 geoBounds 不符），
      * 所以这里做一次一致性检查，不一致就退回 geoBounds 中心。
+     *
+     * 前提是 geoBounds 真的可用：OSGB/SuperMapCache 这类配置只给米制局部包围盒，
+     * 全 0 的退化框不能反过来否定一个正常的 position —— 那等于把模型甩到 (0,0)。
      */
     _resolveAnchor(config) {
         const raw = config.position;
         const p = raw?.point3D ?? raw;
-        const b = config.geoBounds;
+        const okP = !!p && Number.isFinite(p.x) && Number.isFinite(p.y);
+        const b = usableGeoBounds(config.geoBounds);
         const centerLon = b ? (b.left + b.right) / 2 : undefined;
         const centerLat = b ? (b.bottom + b.top) / 2 : undefined;
         // ENU 原点在椭球面上，position.z 就是它的高度；用 heightRange.min 会引入垂直偏移
         const z = p?.z ?? 0;
-        if (!p)
+        if (!okP)
             return { lon: centerLon ?? 0, lat: centerLat ?? 0, height: 0 };
-        const units = config.position?.units ?? 'Degree';
+        // 两种写法都得认：老数据是 position.units，v3.01 起改成了 position.unit
+        const units = raw?.units ?? raw?.unit ?? 'Degree';
         if (units !== 'Degree')
             return { lon: p.x, lat: p.y, height: z };
         const offLon = centerLon === undefined ? 0 : Math.abs(p.x - centerLon);
@@ -277,31 +496,339 @@ export class S3MTileset {
         }
         return this._buildTile;
     }
+    /**
+     * 记住一个块文件里解析出来的全部 LOD 组。
+     *
+     * 一棵 LOD 子树的几层几何加图集动辄好几 MB，全数据集都留着会把内存吃光，
+     * 所以只保留最近 24 个块（LRU 足够：相机在附近移动时命中的永远是同几个块）。
+     */
+    _rememberGroups(baseUrl, set) {
+        this._groupCache.delete(baseUrl);
+        this._groupCache.set(baseUrl, set);
+        while (this._groupCache.size > 24) {
+            const oldest = this._groupCache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this._groupCache.delete(oldest);
+        }
+    }
+    /**
+     * 补齐「图集像素不在块文件里」的那一半 —— 官方 `requestSubTextures` 的等价物。
+     *
+     * 根瓦片（如 6.s3mblock）的图集是内嵌的（isSaveData=1）；但**子瓦片**（6_00 / 6_01）
+     * 的图集段只有元信息：`data = null` + `requestNames`，像素在同目录的 `.texblock` 里。
+     * 不补这一步的后果不是「糊一点」，而是子瓦片整块无贴图：`tile.textures` 里根本没有
+     * 这条纹理，材质拿不到 map，建筑变成纯白几何——精细 LOD 一旦真的加载进来就会显露。
+     *
+     * ★ 只认 requestNames。`childTexNames` 是**下一级 LOD 的图集指针**（官方 `_ancestorTexture`
+     *   用它继承 batchTable 的 rect），它有自己的 subTexInfos：同一个精灵在父级叫 `1460_3`
+     *   96x64、子级叫 `1460_2` 192x128，排布也不一样。拿父级的 rect 去套子级像素必然错位 ——
+     *   上一版就是这么把画面搞坏的。官方从不拿它换像素，那个 LOD 的瓦片自己会加载。
+     *
+     * requestNames 展开（见 `expandTexblockRequestNames`，逐字对应官方 `_subRequestNames`）：
+     *
+     * 1. **整图**（`['-704919438.texblock']`，单条记录 = 整张图集）→ 用 `evaluateAtlasUpgrade`
+     *    验证后整体替换；根块自带缩略图必须验证过才能换，子瓦片（无基准）至少要求长宽比一致。
+     * 2. **leaf 多精灵**（`['Tex_0.texblock#000009…', 'Tile_6_000000.texblock']`，官方 isLeaf）→
+     *    图集本身没有像素，只有 `subTexInfos` 里每块一个精灵 rect。按 subName 把精灵贴回
+     *    各 rect（`composeLeafAtlas`），组合出整张自上而下 RGBA 画布（compressType=0 /
+     *    pixelFormat=28 / flipY=false）。精灵自带「左 2/3 base + 右 1/3 内联 mip 金字塔」，
+     *    与 StyleMaterial 的 `s3mAtlasLod` 2/3 采样公式直接配套，rect 一个像素都不用改。
+     *
+     * 请求方式：pack 组按官方 `Uci` 合并成
+     * `GET Tex_0_<code>.texblock?extratiles=Tex_0_000;Tex_0_009;…`（extratiles **去扩展名**、
+     * 段序 = 请求序，kMi 取第 i 段）；`Tile_*` 是普通多记录容器，整文件解析后按记录名分发。
+     *
+     * 不补/补失败时保持缩略图（或无贴图），由上层照常渲染几何，绝不清空已有纹理表。
+     */
+    async _fillExternalAtlases(tile, url) {
+        const blockTile = tile;
+        const tp = blockTile.texturePackage;
+        if (!tp)
+            return;
+        // 拼图块：先退回原始图集。拼图是把多张图集重排进一张大图，
+        // 换高清图必须在拼图**之前**做，否则 rect 和像素两套排布对不上。
+        const wasPacked = unpackBlockTextures(blockTile);
+        /** 只要像素被动过，纹理表 / rect 就必须重算 —— 否则子瓦片会整块白膜 */
+        let changed = false;
+        // ① 展开 requestNames，跨图集汇总本块还缺哪些子请求（同名只拉一次）
+        const plans = new Map();
+        const packMiss = new Map();
+        const plainMiss = [];
+        for (const [id, tex] of Object.entries(tp)) {
+            const plan = expandTexblockRequestNames(tex.requestNames);
+            if (!plan.names.length)
+                continue; // 只挂了 childTexNames（根瓦片形态）→ 一个请求都不发
+            plans.set(id, { tex, plan });
+            for (const [base, group] of plan.packGroups) {
+                const miss = group.filter((n) => !this.leafRequestCache.has(n));
+                if (!miss.length)
+                    continue;
+                const acc = packMiss.get(base) ?? [];
+                for (const n of miss)
+                    if (!acc.includes(n))
+                        acc.push(n);
+                packMiss.set(base, acc);
+            }
+            for (const n of plan.plain) {
+                if (!this.leafRequestCache.has(n) && !plainMiss.includes(n))
+                    plainMiss.push(n);
+            }
+        }
+        // ② 拉取（先全部 await，再动图集状态；跨瓦片并发时同名请求共享同一个 Promise）
+        const pending = [];
+        for (const [base, names] of packMiss) {
+            let groupFetch = null;
+            const start = () => (groupFetch ??= this._fetchLeafPack(url, base, names));
+            for (const n of names)
+                pending.push(this._ensureLeafFetch(n, start));
+        }
+        for (const n of plainMiss)
+            pending.push(this._ensureLeafFetch(n, () => this._fetchLeafFile(url, n)));
+        if (pending.length)
+            await Promise.all(pending);
+        // ③ 逐图集：leaf 组合优先；没匹配上任何精灵就退回「整图替换 + 验证」
+        for (const [id, { tex, plan }] of plans) {
+            const sprites = new Map();
+            for (const n of plan.names) {
+                const recs = this.leafRequestCache.get(n);
+                if (!recs)
+                    continue;
+                for (const r of recs)
+                    sprites.set(r.id, { source: n, image: r });
+            }
+            const composed = composeLeafAtlas(tex, sprites);
+            if (composed) {
+                const t = tex;
+                t.composed = true;
+                t.leafSig = composed.sig;
+                t.flipY = false; // 画布自上而下（语义见 S3MBlockTexture.flipY 注释）
+                tex.data = composed.data;
+                tex.compressType = 0;
+                tex.pixelFormat = 28; // RGBA
+                tex.width = composed.width;
+                tex.height = composed.height;
+                tex.rectScale = 1; // 画布与 subTexInfos 同一像素空间，rect 原样、不缩放
+                this.atlasUpgraded.add(id);
+                changed = true;
+                if (composed.missing.length || composed.mismatched.length) {
+                    // 官方对缺失精灵同样跳过（留透明）；尺寸不一致照样贴。都只告警，不整块拒收。
+                    console.warn('[s3m] leaf 图集部分精灵异常：', id, {
+                        missing: composed.missing,
+                        mismatched: composed.mismatched,
+                    });
+                }
+                continue;
+            }
+            // —— 整图替换回退（官方 isLeaf=false 的路径）——
+            // 子瓦片的图集段只有元信息（data = null），没有可比的基准，只能直接采用；
+            // 根块自带缩略图，必须验证过才能换。
+            const hasBaseline = !!tex.data;
+            const accept = (img) => {
+                if (!hasBaseline) {
+                    // 没有缩略图可比，但至少要挡住「根本不是同一张图集」的情况：
+                    // 长宽比必须一致，否则 subTexInfos 的 rect 一贴就错位。
+                    const loAsp = tex.width / tex.height;
+                    const hiAsp = img.width / img.height;
+                    if (!(Math.abs(hiAsp / loAsp - 1) <= 0.02)) {
+                        this.atlasUpgradeSkipped.set(id, `aspect(no-baseline) ${tex.width}x${tex.height} vs ${img.width}x${img.height}`);
+                        return false;
+                    }
+                    return true;
+                }
+                const v = evaluateAtlasUpgrade(tex, img);
+                if (v.ok)
+                    return true;
+                this.atlasUpgradeSkipped.set(id, `${v.reason} aspectΔ=${(v.aspectDelta * 100).toFixed(1)}% scale=${v.scale} err=${Number.isNaN(v.meanAbsError) ? 'n/a' : v.meanAbsError.toFixed(1)}`);
+                return false;
+            };
+            // ★ 不能无条件换图。实测 3D-OlympicGreen/Building 两块共 8 张图集里，
+            //   只有 2 张的 child 是「同一套排布的等比放大」（长宽比 0.0%、下采样色差 8.5/11.2），
+            //   其余是**重新排版**过的另一张图（长宽比偏差 5.6%~200%，色差 43~86）。
+            //   直接套用 subTexInfos 会整张错位，比不换更糟 —— 所以换之前先验一遍。
+            const apply = (img) => {
+                const t = tex;
+                // 整图是 DXT 原图（底朝上），清掉 leaf 组合状态
+                t.composed = false;
+                t.leafSig = undefined;
+                t.flipY = true;
+                // 覆盖解析阶段按内嵌缩略图填好的那份；判定不通过时不会走到这里，原样保留
+                tex.data = img.data;
+                tex.compressType = img.compressType;
+                tex.pixelFormat = img.pixelFormat;
+                // rect 是归一化的，但 subTexInfos 的 offset/width 是像素，必须按倍数换算
+                tex.rectScale = tex.width > 0 ? img.width / tex.width : 1;
+                tex.width = img.width || tex.width;
+                tex.height = img.height || tex.height;
+                this.atlasUpgraded.add(id);
+                changed = true;
+            };
+            // 候选只可能是普通请求名的第一条记录；Tex pack 段是子精灵，不是整图（与旧实现一致）。
+            let candidate = this.externalAtlasCache.get(id);
+            if (candidate === null)
+                continue; // 已判定不可用
+            if (candidate === undefined) {
+                candidate = null;
+                for (const n of plan.plain) {
+                    const recs = this.leafRequestCache.get(n);
+                    if (recs?.length) {
+                        candidate = recs[0];
+                        break;
+                    }
+                }
+                this.externalAtlasCache.set(id, candidate);
+            }
+            if (candidate) {
+                if (accept(candidate))
+                    apply(candidate);
+            }
+            else if (!this.atlasUpgradeSkipped.has(id)) {
+                this.atlasUpgradeSkipped.set(id, 'no usable external image（请求失败或只拿到子精灵）');
+            }
+        }
+        // 像素定下来了，重新拼图并重算 rect / 纹理表（两者必须一起重算）。
+        //
+        // ★ 这里必须用 `wasPacked || changed`，不能只看 wasPacked：
+        //   **子瓦片**的图集是 `data = null` + `requestNames`，根本没参与拼图（wasPacked=false），
+        //   像素是刚从 .texblock 拉回来的。只看 wasPacked 的后果是 `tile.textures` 永远是空的
+        //   → 近看整片白膜；同时 atlasRects 也没按 rectScale 重算 → 远处马赛克噪点。
+        if (wasPacked || changed)
+            rebuildBlockTextureState(blockTile);
+    }
+    /** 同名子请求去重：命中缓存立即返回；否则共享进行中的 Promise（跨瓦片并发只发一次） */
+    _ensureLeafFetch(stem, start) {
+        if (this.leafRequestCache.has(stem))
+            return Promise.resolve();
+        const inflight = this._leafPending.get(stem);
+        if (inflight)
+            return inflight;
+        const p = start().finally(() => this._leafPending.delete(stem));
+        this._leafPending.set(stem, p);
+        return p;
+    }
+    /**
+     * pack 组请求 —— 官方 `Uci`：URL = 组内第一个请求的 URL，追加
+     * `extratiles=<全组 quadKey，去扩展名，';' 连接>`；响应是 kMi pack，段序 = extratiles 序。
+     *
+     * 实测服务端两种写法都 200，但带 `.texblock` 的 extratiles 会解出 recs=4 的错内容，
+     * 所以必须用**去扩展名**的 quadKey。
+     */
+    async _fetchLeafPack(baseUrl, base, names) {
+        const u = resolveUrl(dirOf(baseUrl), `${names[0]}.texblock?extratiles=${names.join(';')}`);
+        try {
+            if (!u)
+                throw new Error('无法拼出 URL');
+            const res = await fetch(u);
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const segments = await parseTexblockSegments(await res.arrayBuffer());
+            if (segments.length !== names.length) {
+                throw new Error(`pack 段数 ${segments.length} ≠ 请求名 ${names.length}`);
+            }
+            names.forEach((n, i) => this.leafRequestCache.set(n, segments[i]));
+        }
+        catch (e) {
+            console.warn('[s3m] leaf pack 请求失败：', u, e);
+            for (const n of names)
+                if (!this.leafRequestCache.has(n))
+                    this.leafRequestCache.set(n, null);
+        }
+    }
+    /** 普通 `.texblock`（整图或多记录容器）：文件里的全部记录都归这个子请求名 */
+    async _fetchLeafFile(baseUrl, stem) {
+        const u = resolveUrl(dirOf(baseUrl), `${stem}.texblock`);
+        try {
+            if (!u)
+                throw new Error('无法拼出 URL');
+            const res = await fetch(u);
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const records = (await parseTexblockSegments(await res.arrayBuffer())).flat();
+            this.leafRequestCache.set(stem, records);
+        }
+        catch (e) {
+            console.warn('[s3m] leaf texblock 请求失败：', u, e);
+            if (!this.leafRequestCache.has(stem))
+                this.leafRequestCache.set(stem, null);
+        }
+    }
+    /**
+     * @deprecated 已由 `_fillExternalAtlases` 覆盖，保留仅为兼容 `atlasLod` 选项。
+     *
+     * 旧实现「像素数更大就整体换图」，正是被证伪的那个前提：实测 8 张图集里只有 2 张的
+     * child 是等比放大，其余是重新排版过的另一张图，硬换会整张错位。
+     * 现在换图统一走 `_fillExternalAtlases` + `evaluateAtlasUpgrade` 的验证流程。
+     */
+    async _upgradeAtlasLod(_tile, _url) {
+        return;
+    }
     async _load(url) {
         if (this.nodes.has(url) || this.pending.has(url) || this.failed.has(url))
             return;
         this.pending.add(url);
         this.stats.loading++;
         try {
-            const res = await fetch(url);
-            if (!res.ok) {
-                throw new Error(`HTTP ${res.status} 加载瓦片失败: ${url}`);
+            // URL 里的 `#N` 表示「同一个 .s3mblock 文件里的第 N 个 LOD 组」。
+            // 一个块文件打包的是一整棵 LOD 子树（6_01 → 6_0100 → 6_010000 → …），
+            // 这些下层瓦片**不是独立文件**，用 `#N` 直接命中已缓存的组，不再发请求。
+            const hashAt = url.indexOf('#');
+            const baseUrl = hashAt >= 0 ? url.slice(0, hashAt) : url;
+            const groupIndex = hashAt >= 0 ? Number(url.slice(hashAt + 1)) || 0 : 0;
+            const isBlock = /\.s3mblock($|\?)/i.test(baseUrl);
+            let tile;
+            let groupNames = [];
+            const cachedSet = this._groupCache.get(baseUrl);
+            if (cachedSet) {
+                groupNames = cachedSet.names;
+                tile = cachedSet.tiles[groupIndex] ?? cachedSet.tiles[0];
             }
-            const ctype = res.headers.get('content-type') || '';
-            if (ctype.includes('text/html')) {
-                throw new Error(`瓦片请求返回了 HTML 页面（通常为 404/500 服务端拦截）: ${url}`);
+            else {
+                const res = await fetch(baseUrl);
+                if (!res.ok) {
+                    throw new Error(`HTTP ${res.status} 加载瓦片失败: ${baseUrl}`);
+                }
+                const ctype = res.headers.get('content-type') || '';
+                if (ctype.includes('text/html')) {
+                    throw new Error(`瓦片请求返回了 HTML 页面（通常为 404/500 服务端拦截）: ${baseUrl}`);
+                }
+                const buffer = await res.arrayBuffer();
+                // S3MBLOCK（TextureSharing / 单文件存储）走专用解析：容器 + 内嵌 v2 瓦片体 + 图集纹理
+                if (isBlock) {
+                    const set = await parseS3MBlockGroups(buffer);
+                    this._rememberGroups(baseUrl, set);
+                    groupNames = set.names;
+                    tile = set.tiles[groupIndex] ?? set.tiles[0];
+                }
+                else {
+                    tile = await parseS3MB(buffer);
+                }
+            }
+            if (isBlock) {
+                // 子瓦片的图集像素在独立 .texblock 里，必须先补齐，否则整块无贴图
+                await this._fillExternalAtlases(tile, baseUrl);
+                await this._upgradeAtlasLod(tile, baseUrl);
             }
-            const buffer = await res.arrayBuffer();
-            const tile = await parseS3MB(buffer);
             const build = await this._builder();
             const { group, stats } = await build(tile, { textureCache: this.textureCache, uniforms: this._uniforms });
             const lod = this._pickLod(tile);
             const childUrls = [];
             for (const l of tile.groupNode?.pageLods ?? []) {
-                const u = resolveUrl(dirOf(url), l.childTile);
-                if (u && u !== url && !childUrls.includes(u)) {
+                // 下一层如果就在本文件里（实测 6_01 的 5 个组是连成一条链的），直接指向 `#index`，
+                // 不产生任何网络请求；只有真正的外部文件才走 URL 解析。
+                const childName = String(l.childTile ?? '').replace(/\.s3mblock$/i, '');
+                const sameFile = isBlock && childName ? groupNames.indexOf(childName) : -1;
+                const u = sameFile >= 0
+                    ? `${baseUrl}#${sameFile}`
+                    : this.isS3MV1
+                        ? s3m1ChildUrl(url, l.childTile)
+                        : resolveUrl(dirOf(url), l.childTile);
+                // 注意：不能拿 rootTiles 清单去筛子瓦片。S3MBLOCK 的 config.tiles 只是**根**瓦片，
+                // 实测 6.s3mblock 的 pageLOD 指向 6_00/6_01.s3mblock（HTTP 200，37 KB / 549 KB），
+                // 都在清单之外。按清单筛的后果是 childUrls 恒为空 → update() 永远不细化 →
+                // 任何机位都只渲染最粗一级的根图集（一栋楼只剩十几像素，再按 uv 平铺几十遍），
+                // 表现为「整栋微缩建筑照片贴满立面」。是否可取由服务器 404 + failed 退避来兜。
+                if (u && u !== url && !childUrls.includes(u))
                     childUrls.push(u);
-                }
             }
             const node = {
                 url,
@@ -310,7 +837,7 @@ export class S3MTileset {
                 sphere: lod?.boundingSphere ?? null,
                 rangeValue: lod?.rangeValue ?? 0,
                 rangeMode: lod?.rangeMode ?? 1,
-                childUrl: childUrls[0] ?? resolveUrl(dirOf(url), lod?.childTile),
+                childUrl: childUrls[0] ?? (this.isS3MV1 ? s3m1ChildUrl(url, lod?.childTile) : resolveUrl(dirOf(url), lod?.childTile)),
                 childUrls,
                 parentUrl: this._parentOf.get(url),
                 state: 'ready',
@@ -323,9 +850,12 @@ export class S3MTileset {
             this._onTile(node);
         }
         catch (e) {
+            // 格式层面的永久错误（例如 S3M 1.x 容器）重试一万次也不会变好，
+            // 直接判失败，免得反复重下一整块瓦片还拖慢首屏
+            const permanent = e?.permanent === true;
             const attempts = (this._retryCount.get(url) ?? 0) + 1;
             this._retryCount.set(url, attempts);
-            if (attempts <= this._maxRetries) {
+            if (!permanent && attempts <= this._maxRetries) {
                 // 退避重试：不进 failed，下一帧 update() 会重新入队，避免网络抖一下就留个永久空洞
                 this._retryAt.set(url, performance.now() + 800 * attempts);
             }
@@ -335,8 +865,27 @@ export class S3MTileset {
                 this.stats.failed++;
                 this.failed.add(url);
                 this._retryAt.delete(url);
+                // 从父瓦片的子列表里摘掉：S3MBLOCK 里有些 pageLOD 的 childTile 在服务器上根本不存在
+                // （实测 64_0000 / 65_0200 全是 404）。留着会让父瓦片永远「子未全就绪」→ 永不细化，
+                // 症状就是贴着看也一直渲染最粗一级。
+                const pUrl = this._parentOf.get(url);
+                const pNode = pUrl ? this.nodes.get(pUrl) : undefined;
+                if (pNode?.childUrls) {
+                    pNode.childUrls = pNode.childUrls.filter((u) => u !== url);
+                    pNode.childUrl = pNode.childUrls[0] ?? null;
+                }
+            }
+            // 同一类永久错误只报一次：OSGB 服务一上来几十块瓦片都是同一个原因，
+            // 刷屏会把真正值得看的日志埋掉
+            if (permanent) {
+                if (!this._permanentReported) {
+                    this._permanentReported = true;
+                    this._onError(e);
+                }
+            }
+            else {
+                this._onError(e);
             }
-            this._onError(e);
         }
         finally {
             this.pending.delete(url);
@@ -365,22 +914,49 @@ export class S3MTileset {
             const dist = Math.sqrt(dx * dx + dy * dy + dz * dz) || 1e-6;
             node.distance = dist;
             let metric;
-            if (node.rangeMode === 0) {
+            // RangeMode 语义（规范只写了 0/1）：
+            //   0 Distance_From_EyePoint —— rangeValue 是米，离得越近越该细化
+            //   1 Pixel_Size_OnScreen     —— rangeValue 是屏幕像素，投影半径超过它就细化
+            //   2 规范枚举里没有这一档（文档里记作 Geometric_Error）。实测高斯泼溅 / 点云服务用的是
+            //     这一档，且 rangeValue ≈ 包围球半径的固定比例（根瓦片 0.664/10.455，子瓦片
+            //     0.332/3.7，比例都约 0.064），像是「相对屏幕尺寸的几何误差」而非绝对像素。
+            //     这里先按 1 处理：方向是对的（近处细化），只是阈值偏小会多下几层，靠 lodRangeScale 收着。
+            const byDistance = node.rangeMode === 0;
+            if (byDistance) {
                 metric = dist; // Distance_From_EyePoint：距离越小越该细化
             }
             else {
-                // 屏幕像素半径
-                metric = ((node.sphere.radius / dist) / Math.tan(fovRad / 2)) * screenHeight * 0.5;
+                // 屏幕像素尺寸。照抄官方 PageLod.calcPixFromCam（SourceRelease/_3437c37f.js）：
+                //   pix = (drawingBufferHeight/2) / tan(PI_OVER_FOUR * 0.5) * radius / distance * 2
+                //       = drawingBufferHeight * 2.4142 * radius / distance
+                // 两个要点：① 视场角是**写死的 45°**（tan(22.5°)），不取渲染器实际 fov；
+                // ② 末尾那个 *2（即用直径量屏幕尺寸）。少这个 *2 会让 metric 只有官方的一半，
+                //    needRefine 的门槛就永远差一级 —— 表现就是「贴着看也一直在渲染最粗的根图集，
+                //    一张整楼雪碧被 uv 平铺几十遍」。实测瓦片 6_01：radius 293.4、rangeValue 586.8，
+                //    distance ≈ 824 m、H = 854 → 官方算 734 > 586.8 该细化，我们旧公式只有 326。
+                metric = ((screenHeight * 0.5) / Math.tan(Math.PI / 8)) * (node.sphere.radius / dist) * 2;
+                void fovRad;
             }
             // 在有效范围内（留一倍余量）的算「正在用」，淘汰时按这个帧号排优先级
             const scale = this.lodRangeScale > 0 ? this.lodRangeScale : 1.0;
             const threshold = node.rangeValue * scale;
-            const inRange = node.rangeMode === 0 ? dist < threshold * 2 : metric > threshold * 0.5;
+            const inRange = byDistance ? dist < threshold * 2 : metric > threshold * 0.5;
             if (inRange)
                 node.lastSeen = this._frame;
             const childUrls = node.childUrls ?? (node.childUrl ? [node.childUrl] : []);
-            const needRefine = childUrls.length > 0 && (node.rangeMode === 0 ? metric < threshold : metric > threshold);
+            const needRefine = childUrls.length > 0 && (byDistance ? metric < threshold : metric > threshold);
             node.needRefine = needRefine;
+            const dbgSeen = (globalThis.__S3M_LOD_SEEN ??= new Set());
+            if (globalThis.__S3M_LOD_DEBUG && !dbgSeen.has(node.url) && dbgSeen.size < 260) {
+                dbgSeen.add(node.url);
+                // eslint-disable-next-line no-console
+                console.log('[LOD]', JSON.stringify({
+                    url: node.url.split('/').pop(), mode: node.rangeMode, rangeValue: node.rangeValue,
+                    radius: node.sphere.radius, dist: +dist.toFixed(1), metric: +metric.toFixed(1),
+                    threshold: +threshold.toFixed(1), needRefine, childUrls: childUrls.map((u) => u.split('/').pop()),
+                    parent: node.parentUrl ? node.parentUrl.split('/').pop() : null,
+                }));
+            }
             if (needRefine) {
                 for (const childUrl of childUrls) {
                     if (!this.failed.has(childUrl) && !this.nodes.has(childUrl) && !this.pending.has(childUrl)) {
@@ -392,12 +968,16 @@ export class S3MTileset {
         }
         // 树状递归更新所有瓦片的可见性（确保每个位置只渲染一层最适合的 LOD，避免父子瓦片重叠 Z-fighting）
         const visited = new Set();
-        const roots = this.rootUrls.length > 0
-            ? this.rootUrls
-            : [...this.nodes.keys()].filter((u) => {
-                const p = this.nodes.get(u)?.parentUrl;
-                return !p || !this.nodes.has(p);
-            });
+        // 根集合 = 配置里的入口瓦片 + 所有「父瓦已不在档」的瓦片。
+        // 后者必须有：淘汰掉一块中间层瓦片后，它下面的子孙会瞬间变成"无父"状态，
+        // 如果只按 rootUrls 走，它们全部不可达，会被下面那条防御规则一起隐藏 ——
+        // 症状就是「进去先渲染出来，然后整片消失，偶尔闪一下」。
+        const roots = new Set(this.rootUrls);
+        for (const [url, node] of this.nodes) {
+            const p = node.parentUrl ?? this._parentOf.get(url);
+            if (!p || !this.nodes.has(p))
+                roots.add(url);
+        }
         for (const rootUrl of roots) {
             if (this._updateNodeVisibility(rootUrl, true, visited)) {
                 hasChanges = true;
@@ -412,12 +992,46 @@ export class S3MTileset {
                 }
             }
         }
+        // 显示职责已经分配完毕，现在才裁预算（make-before-break）：
+        // 此时「谁在负责显示这块地」是确定的，只踢没人依赖的那块，不会开出洞来
+        if (this._trimBudget())
+            hasChanges = true;
+        // 兜底：绝不允许空场。
+        // 可见性递归是按「先访问先决定」处理的，而 LOD 图不一定是严格的树 —— 同一个子瓦可能
+        // 被多个父瓦引用（不同层级指向同一份数据），它可能先在某条"隐藏分支"里被访问掉，
+        // 之后就再也拿不到显示机会，最终出现「一块都不显示」的整片消失。
+        // 这里做最后一次校正：凡是位置没有被任何可见子瓦接手的瓦片，一律自己显示。
+        let anyVisible = false;
+        for (const node of this.nodes.values()) {
+            if (node.group.visible) {
+                anyVisible = true;
+                break;
+            }
+        }
+        if (!anyVisible && this.nodes.size > 0) {
+            for (const node of this.nodes.values()) {
+                const childUrls = node.childUrls ?? (node.childUrl ? [node.childUrl] : []);
+                const covered = childUrls.some((u) => {
+                    const c = this.nodes.get(u);
+                    return !!c && c !== node && c.group.visible;
+                });
+                if (!covered && !node.group.visible) {
+                    node.group.visible = true;
+                    hasChanges = true;
+                }
+            }
+        }
         return hasChanges;
     }
     _updateNodeVisibility(url, parentInBranch, visited) {
         const node = this.nodes.get(url);
         if (!node)
             return false;
+        // 必须挡住重复访问：可见性图不是严格的树 —— 同一个子瓦可能被多个父瓦引用（不同 LOD 源
+        // 指向同一份数据）、淘汰后重挂父级也可能临时造出交叉引用。没有这道守卫，
+        // 递归会指数级展开甚至成环，直接 RangeError: Maximum call stack size exceeded。
+        if (visited.has(url))
+            return false;
         visited.add(url);
         let changed = false;
         const childUrls = node.childUrls ?? (node.childUrl ? [node.childUrl] : []);
@@ -433,10 +1047,12 @@ export class S3MTileset {
             return changed;
         }
         const hasChildren = childUrls.length > 0;
-        const allChildrenReady = hasChildren && childUrls.every((cUrl) => this.nodes.has(cUrl));
-        const anyChildFailed = childUrls.some((cUrl) => this.failed.has(cUrl));
-        // 细化前提：需要细化、拥有子瓦片、子瓦片全部加载就绪且没有任何一个子瓦片失败
-        const shouldRefine = !!node.needRefine && allChildrenReady && !anyChildFailed;
+        // 「就绪」= 已加载；失败的已经从 childUrls 里摘掉，剩下的只要都到了就能接手显示
+        const readyChildren = childUrls.filter((cUrl) => this.nodes.has(cUrl));
+        const allResolved = childUrls.every((cUrl) => this.nodes.has(cUrl) || this.failed.has(cUrl));
+        // 细化前提：需要细化、至少有一个子瓦片就绪、且没有还在下载途中的子瓦片
+        // （不等「全部就绪」是因为个别 childTile 在服务器上就是 404，等它等于永远不细化）
+        const shouldRefine = !!node.needRefine && hasChildren && readyChildren.length > 0 && allResolved;
         if (shouldRefine) {
             // 子节点接替当前节点渲染，当前父节点隐藏
             if (node.group.visible) {