s3m-three 0.3.5 → 0.3.6

package/src/render/TextureFactory.ts

@@ -1,32 +1,18 @@
 /**
  * S3M 纹理 → three.js Texture
  *
- * S3M 的纹理是「裸块」：没有容器头，只有 width/height/compressType/dataSize/pixelFormat + 原始字节。
- * 该走哪条解码路径由 compressType 决定（见 core/TextureFormat.ts）：DXT 族直接解块，
- * CRN（26 / 27 / 38001 / 50000）先用 crunch wasm 转码回 DXT，WEBP 交给浏览器，
- * RGB 系逐像素拷贝。
+ * 解码本体已下沉到 core/TextureDecode.ts（three 无关，主线程 / Worker 共用），
+ * 本文件只负责两件事：
+ *   1. 优先把解码派给 Worker（setTextureOffThreadDecode 注入，S3MViewer 装配），
+ *      Worker 不可用时用同一份 decodeTextureData 在主线程兜底；
+ *   2. 把纯数据解码产物包成 three Texture 并按 atlas / 普通 分别配置采样参数。
  */
 import * as THREE from 'three';
-import DXTTextureDecode from '../core/DXTTextureDecode.js';
-import { transcodeCRN } from '../core/CRNDecode.js';
-import { dxtPixelFormatOf, resolveTextureKind } from '../core/TextureFormat.js';
 import type { S3MTexture } from '../core/types.js';
+import { decodeTextureData } from '../core/TextureDecode.js';
+import type { DecodedTextureData } from '../core/TextureDecode.js';
 
-export const PixelFormat = {
-  RGB: 10,
-  BGR: 11,
-  ARGB: 12,
-  ABGR: 13,
-  BGRA: 14,
-  RGBA: 28,
-  WEBP: 25,
-  DXT1: 17,
-  DXT3: 19,
-  DXT4: 20,
-  DXT5: 21,
-  CRN_DXT5: 26,
-  STANDARD_CRN: 27,
-} as const;
+export { PixelFormat } from '../core/TextureFormat.js';
 
 /** 由 S3MLayer 在拿到 GL 上下文后注入，用于斜视角下保持纹理清晰 */
 let maxAnisotropy = 1;
@@ -41,6 +27,26 @@ export interface DecodedTexture {
   decoded: string;
 }
 
+/**
+ * 注入「离线解码」实现（S3MViewer 装配：走共享解析 Worker）。
+ * 返回 null = Worker 不可用 / 崩溃，createTexture 自动退回主线程 decodeTextureData。
+ */
+let offThreadDecode: ((tex: S3MTexture) => Promise<DecodedTextureData | null>) | null = null;
+
+export function setTextureOffThreadDecode(
+  fn: ((tex: S3MTexture) => Promise<DecodedTextureData | null>) | null
+): void {
+  offThreadDecode = fn;
+}
+
+async function decodeTexture(tex: S3MTexture): Promise<DecodedTextureData> {
+  if (offThreadDecode) {
+    const viaWorker = await offThreadDecode(tex);
+    if (viaWorker) return viaWorker;
+  }
+  return decodeTextureData(tex);
+}
+
 function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   tex.wrapS = THREE.RepeatWrapping;
   tex.wrapT = THREE.RepeatWrapping;
@@ -74,117 +80,32 @@ function configureAtlas<T extends THREE.Texture>(tex: T): T {
   return tex;
 }
 
-/** 行序翻转（原地）。S3MBLOCK 图集按 GL 方向存储（v=0 在最后一行），解码后要翻一次行 */
-function flipRows(rgba: Uint8Array, width: number, height: number): void {
-  const row = width * 4;
-  const tmp = new Uint8Array(row);
-  for (let y = 0; y < height >> 1; y++) {
-    const a = y * row;
-    const b = (height - 1 - y) * row;
-    tmp.set(rgba.subarray(a, a + row));
-    rgba.copyWithin(a, b, b + row);
-    rgba.set(tmp, b);
-  }
-}
-
-/** 该像素格式自带 alpha 通道（DXT1 的 1bit alpha 不算，历史上没开过 alphaTest） */
-function hasAlphaChannel(pixelFormat: number): boolean {
-  return (
-    pixelFormat === PixelFormat.DXT3 ||
-    pixelFormat === PixelFormat.DXT4 ||
-    pixelFormat === PixelFormat.DXT5 ||
-    pixelFormat === PixelFormat.ARGB ||
-    pixelFormat === PixelFormat.ABGR ||
-    pixelFormat === PixelFormat.BGRA ||
-    pixelFormat === PixelFormat.RGBA
-  );
-}
-
-/** 解 DXT 到 RGBA8。DXT5 是 1 字节/像素，DXT1 是 0.5 字节/像素。 */
-/** DXT 解码只需要尺寸 / 格式 / 字节，CRN 转码出来的结果也走这条路 */
-function decodeDXT(tex: Pick<S3MTexture, 'width' | 'height' | 'pixelFormat' | 'data' | 'flipY'>): THREE.DataTexture {
-  const { width, height, pixelFormat, data } = tex;
-  const out = new Uint8Array(width * height * 4);
-  DXTTextureDecode.decode(out, width, height, data, pixelFormat);
-  if (tex.flipY) flipRows(out, width, height);
-  const dt = new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
-  if (hasAlphaChannel(pixelFormat)) dt.userData.s3mHasAlpha = true;
-  return dt;
-}
-
-function fromRawRGB(tex: S3MTexture): THREE.DataTexture {
-  const { width, height, pixelFormat, data } = tex;
-  const out = new Uint8Array(width * height * 4);
-  // RGBA / BGRA / ARGB / ABGR 都是 4 字节，前两个是「尾字节是 alpha」，后两个是「首字节是 alpha」
-  const hasAlpha =
-    pixelFormat === PixelFormat.RGBA ||
-    pixelFormat === PixelFormat.BGRA ||
-    pixelFormat === PixelFormat.ARGB ||
-    pixelFormat === PixelFormat.ABGR;
-  const swapRB = pixelFormat === PixelFormat.BGR || pixelFormat === PixelFormat.BGRA;
-  const alphaFirst = pixelFormat === PixelFormat.ARGB || pixelFormat === PixelFormat.ABGR;
-  const src = hasAlpha ? 4 : 3;
-  for (let i = 0, s = 0, d = 0; i < width * height; i++, s += src, d += 4) {
-    const p = alphaFirst ? s + 1 : s;
-    out[d] = swapRB ? data[p + 2] : data[p];
-    out[d + 1] = data[p + 1];
-    out[d + 2] = swapRB ? data[p] : data[p + 2];
-    out[d + 3] = hasAlpha ? data[alphaFirst ? s : s + 3] : 255;
-  }
-  if (tex.flipY) flipRows(out, width, height);
-  const dt = new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
-  if (hasAlphaChannel(pixelFormat)) dt.userData.s3mHasAlpha = true;
-  return dt;
-}
-
 export async function createTexture(tex: S3MTexture | null | undefined): Promise<DecodedTexture> {
   if (!tex || !tex.width || !tex.height) return { texture: null, decoded: 'empty' };
 
   // 图集纹理（flipY 的原始 DXT 图集 / AtlasPack 拼出来的 RGBA 大图 / leaf 组合画布）都必须
   // 关 GPU mip，层级由 StyleMaterial.s3mAtlasUnit 的内联金字塔自己算。
   const isAtlas = tex.packed === true || tex.flipY === true || tex.composed === true;
-  const asAtlas = <T extends THREE.Texture>(t: T): T => (isAtlas ? configureAtlas(t) : configure(t));
 
-  // 判定只能看 compressType：v3.00 的 CRN 纹理 pixelFormat 是 13（ABGR）、
-  // 行标的 CRN 是 32856（GL_RGBA8），都不是 26 / 27（见 core/TextureFormat.ts）
-  const kind = resolveTextureKind(tex.compressType ?? 0, tex.pixelFormat);
+  const data = await decodeTexture(tex);
 
-  if (kind === 'crn') {
-    try {
-      const crn = await transcodeCRN(tex.data);
-      const decoded = decodeDXT({
-        width: crn.width,
-        height: crn.height,
-        pixelFormat: crn.dxtFormat === 1 ? 17 : 21,
-        data: crn.data,
-      });
-      return { texture: asAtlas(decoded), decoded: `crn->dxt${crn.dxtFormat}` };
-    } catch (e) {
+  if (!data.rgba && !data.bitmap) {
+    if (data.error) {
       // 一张纹理坏了不该带崩整个瓦片，如实上报并降级成无贴图
-      console.warn('[s3m] CRN 转码失败：', e);
-      return { texture: null, decoded: 'crn(failed)' };
+      console.warn('[s3m] CRN 转码失败：', data.error);
     }
+    return { texture: null, decoded: data.kind };
   }
 
-  if (kind === 'dxt1' || kind === 'dxt3' || kind === 'dxt4' || kind === 'dxt5') {
-    const decoded = decodeDXT({ ...tex, pixelFormat: dxtPixelFormatOf(kind) });
-    // flipY 为真即 S3MBLOCK 图集（见 core/types.ts），必须无 mip
-    return { texture: asAtlas(decoded), decoded: kind };
+  let texture: THREE.Texture;
+  if (data.bitmap) {
+    texture = new THREE.Texture(data.bitmap);
+  } else {
+    const dt = new THREE.DataTexture(data.rgba!, data.width, data.height, THREE.RGBAFormat, THREE.UnsignedByteType);
+    if (data.hasAlpha) dt.userData.s3mHasAlpha = true;
+    texture = dt;
   }
-
-  if (kind === 'webp') {
-    const blob = new Blob([tex.data as BlobPart], { type: 'image/webp' });
-    const bmp = await createImageBitmap(blob);
-    const t = new THREE.Texture(bmp);
-    t.needsUpdate = true;
-    return { texture: asAtlas(t), decoded: 'webp' };
-  }
-
-  if (kind === 'raw') {
-    const decoded = fromRawRGB(tex);
-    return { texture: asAtlas(decoded), decoded: 'raw' };
-  }
-
-  // KTX2 / ETC 需要额外解码器，先如实上报而不是静默出错
-  return { texture: null, decoded: `unsupported(${tex.compressType}/${tex.pixelFormat})` };
+  texture.needsUpdate = true;
+  // flipY 为真即 S3MBLOCK 图集（见 core/types.ts），必须无 mip
+  return { texture: isAtlas ? configureAtlas(texture) : configure(texture), decoded: data.kind };
 }

package/src/tileset/S3MTileset.ts

@@ -7,6 +7,7 @@
  *   命中阈值就请求 childTile，实现渐进式细化。
  */
 import { parseS3MB } from '../core/S3MBParser.js';
+import { getSharedS3MWorker, S3MWorkerClient, WorkerDeadError } from '../worker/S3MWorkerClient.js';
 import {
   composeLeafAtlas,
   expandTexblockRequestNames,
@@ -235,6 +236,15 @@ export interface S3MTilesetOptions {
   /** 原始图像/子图集缓存上限（LRU），默认 128 */
   maxImageCache?: number;
   buildTile?: BuildTileFn | null;
+  /**
+   * 是否用 Web Worker 解析经典 `.s3mb` 瓦片（默认开）。
+   *
+   * Worker 里跑 parseS3MB 全链路（inflate / Draco / MeshOpt 内联 wasm 解码），
+   * 主线程只做 fetch 与几何组装，消除加载阶段的解析卡顿。
+   * Worker 创建失败或崩溃时自动**永久**降级回主线程解析，行为与关闭时完全一致。
+   * S3MBLOCK 路径（图集补齐与主线程缓存强耦合）暂不进 Worker，仍主线程解析。
+   */
+  useWorker?: boolean;
   uniforms?: StyleUniforms | null;
   onTile?: (node: TileNode) => void;
   /** 超过 maxTiles 被淘汰时回调，调用方要自己把场景里的对象和拾取表清掉 */
@@ -330,6 +340,8 @@ export class S3MTileset {
   private isS3MV1 = false;
   private _buildTile: BuildTileFn | null;
   private readonly _uniforms: StyleUniforms | null;
+  /** 经典 .s3mb 的 Worker 解析客户端；undefined = 尚未尝试创建，null = 不可用/已降级 */
+  private _workerClient: S3MWorkerClient | null | undefined;  private readonly _useWorker: boolean;
   private _queue: string[] = [];
   private _active = 0;
 
@@ -346,6 +358,7 @@ export class S3MTileset {
     this._buildTile = options.buildTile ?? null;
     // 着色器共享 uniform，由 S3MLayer 持有并传进来
     this._uniforms = options.uniforms ?? null;
+    this._useWorker = options.useWorker !== false;
 
     // 并发与总量限制：iServer 公开服务上别把人家打爆
     this.maxConcurrent = options.maxConcurrent ?? 4;
@@ -677,6 +690,30 @@ export class S3MTileset {
     return this._buildTile;
   }
 
+  /**
+   * 经典 `.s3mb` 瓦片解析：优先走 Worker（把 inflate / Draco / MeshOpt 的 CPU 密集
+   * 解码搬离主线程），Worker 不可用或已崩溃时主线程兜底，两条路径输出完全一致。
+   */
+  private async _parseClassicTile(buffer: ArrayBuffer): Promise<ParsedTile> {
+    if (this._useWorker && this._workerClient === undefined) {
+      // 与纹理解码共用进程级单例，避免每个数据集各起一个 Worker
+      this._workerClient = getSharedS3MWorker();
+    }
+    if (this._workerClient) {
+      try {
+        return await this._workerClient.parseTile(buffer);
+      } catch (e) {
+        if (e instanceof WorkerDeadError) {
+          // 脚本加载失败 / 崩溃属于环境问题，永久退回主线程；瓦片本身的问题照常抛
+          this._workerClient = null;
+        } else {
+          throw e;
+        }
+      }
+    }
+    return parseS3MB(buffer);
+  }
+
   /**
    * 记住一个块文件里解析出来的全部 LOD 组。
    *
@@ -970,7 +1007,7 @@ export class S3MTileset {
           groupNames = set.names;
           tile = set.tiles[groupIndex] ?? set.tiles[0]!;
         } else {
-          tile = await parseS3MB(buffer);
+          tile = await this._parseClassicTile(buffer);
         }
       }
       if (isBlock) {
@@ -1269,6 +1306,7 @@ export class S3MTileset {
   }
 
   dispose(): void {
+    this._workerClient?.dispose();
     for (const node of this.nodes.values()) {
       node.group.traverse((o) => {
         const mesh = o as {

package/src/worker/S3MWorkerClient.ts

@@ -0,0 +1,150 @@
+/**
+ * 解析 Worker 的主线程客户端。
+ *
+ * 生命周期约定（由 S3MTileset 使用）：
+ * - `create()` 返回 null = 环境不可用（无 Worker / 脚本同步创建失败），调用方直接走主线程解析；
+ * - `parseTile()` 抛 `WorkerDeadError` = Worker 脚本加载失败或已崩溃，调用方应**永久**
+ *   退回主线程解析（不要再给这个 client 发活，也别让每块瓦片都白白失败两轮重试）；
+ * - 抛普通 Error = Worker 活着、但解析本身失败（网络字节坏了 / S3M1 容器永久错误等），
+ *   语义与主线程 `parseS3MB` 抛错完全一致，原样向上传。
+ */
+import type { ParsedTile, S3MTexture } from '../core/types.js';
+import type { DecodedTextureData } from '../core/TextureDecode.js';
+
+/** Worker 崩溃 / 不可用 —— 与「瓦片数据本身有问题」区分开，调用方据此决定降级还是重试 */
+export class WorkerDeadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WorkerDeadError';
+  }
+}
+
+interface ParseOkResponse {
+  id: number;
+  ok: true;
+  tile: ParsedTile;
+}
+
+interface TexOkResponse {
+  id: number;
+  ok: true;
+  data: DecodedTextureData;
+}
+
+interface ErrResponse {
+  id: number;
+  ok: false;
+  message: string;
+  permanent: boolean;
+}
+
+type Response = ParseOkResponse | TexOkResponse | ErrResponse;
+
+export class S3MWorkerClient {
+  private readonly _worker: Worker;
+  private _seq = 0;
+  private readonly _pending = new Map<number, { resolve: (v: unknown) => void; reject: (err: unknown) => void }>();
+  /** true = 已崩溃 / 已终止，后续请求直接拒绝 */
+  dead = false;
+
+  /** 创建失败返回 null（不抛），调用方据此走主线程解析 */
+  static create(): S3MWorkerClient | null {
+    if (typeof Worker === 'undefined') return null;
+    try {
+      // 路径锚定本模块的编译产物（dist/worker/s3mWorker.js）；
+      // Vite 打包时会把这个 pattern 转成独立 worker 资产，IIFE 直引场景由死锁降级兜底
+      const worker = new Worker(new URL('./s3mWorker.js', import.meta.url), { type: 'module' });
+      return new S3MWorkerClient(worker);
+    } catch {
+      return null;
+    }
+  }
+
+  private constructor(worker: Worker) {
+    this._worker = worker;
+    worker.onmessage = (e: MessageEvent<Response>) => {
+      const msg = e.data;
+      const waiter = this._pending.get(msg.id);
+      if (!waiter) return;
+      this._pending.delete(msg.id);
+      if (!msg.ok) {
+        // 还原主线程 parseS3MB 的错误形状：permanent 标记驱动瓦片级的「永久失败」分支
+        const err = new Error(msg.message);
+        (err as { permanent?: boolean }).permanent = msg.permanent;
+        waiter.reject(err);
+      } else if ('tile' in msg) {
+        waiter.resolve(msg.tile);
+      } else {
+        waiter.resolve(msg.data);
+      }
+    };
+    worker.onerror = () => this._die('s3m 解析 Worker 加载失败/崩溃');
+    worker.onmessageerror = () => this._die('s3m 解析 Worker 消息无法反序列化');
+  }
+
+  /** 解析一块瓦片。buffer 会被 structured clone（不 transfer），主线程保留原 buffer 以便崩溃后降级重解 */
+  parseTile(buffer: ArrayBuffer): Promise<ParsedTile> {
+    if (this.dead) return Promise.reject(new WorkerDeadError('s3m 解析 Worker 已终止'));
+    const id = ++this._seq;
+    return new Promise<ParsedTile>((resolve, reject) => {
+      this._pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      this._worker.postMessage({ type: 'parse', id, buffer });
+    });
+  }
+
+  /** 解码一张纹理（DXT / CRN / WEBP / RGB 系）。tex.data 走 structured clone，主线程保留原数据 */
+  decodeTexture(tex: S3MTexture): Promise<DecodedTextureData> {
+    if (this.dead) return Promise.reject(new WorkerDeadError('s3m 解析 Worker 已终止'));
+    const id = ++this._seq;
+    return new Promise<DecodedTextureData>((resolve, reject) => {
+      this._pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      this._worker.postMessage({ type: 'tex', id, tex });
+    });
+  }
+
+  dispose(): void {
+    this._die('dispose');
+  }
+
+  private _die(reason: string): void {
+    if (this.dead) return;
+    this.dead = true;
+    try {
+      this._worker.terminate();
+    } catch {
+      /* 已死的 worker terminate 不会再抛 */
+    }
+    const err = new WorkerDeadError(`${reason}，退回主线程解析`);
+    for (const waiter of this._pending.values()) waiter.reject(err);
+    this._pending.clear();
+  }
+}
+
+/* ------------------------------------------------------------------ 共享单例 */
+
+/**
+ * 进程级共享的解析 Worker（解析 + 纹理解码共用一个线程，避免每个数据集 /
+ * 每个渲染层各起一个 Worker 把内存和调度打爆）。懒创建，崩溃后返回 null。
+ */
+let sharedClient: S3MWorkerClient | null | undefined;
+
+export function getSharedS3MWorker(): S3MWorkerClient | null {
+  if (sharedClient === undefined) sharedClient = S3MWorkerClient.create();
+  if (sharedClient && sharedClient.dead) return null;
+  return sharedClient;
+}
+
+/**
+ * 纹理解码的「Worker 优先」入口，供 TextureFactory.setTextureOffThreadDecode 装配。
+ * 永不 reject：Worker 不可用 / 崩溃 / 单张解码失败都返回 null，调用方主线程兜底
+ * （解码失败本身在 decodeTextureData 里也不抛错，走 crn(failed) 之类的标记）。
+ */
+export async function decodeTextureWithWorker(tex: S3MTexture): Promise<DecodedTextureData | null> {
+  const client = getSharedS3MWorker();
+  if (!client) return null;
+  try {
+    return await client.decodeTexture(tex);
+  } catch {
+    return null;
+  }
+}

package/src/worker/s3mWorker.ts

@@ -0,0 +1,58 @@
+/**
+ * S3M 解析 / 纹理解码 Worker 入口。
+ *
+ * 职责：把 CPU 密集的解码搬离主线程——
+ *   - parse：`.s3mb`（含 S3M 1.x / Draco / MeshOpt 内联 wasm 解码）整块解析；
+ *   - tex：  纹理解码（DXT 解块 / CRN wasm 转码 / WEBP createImageBitmap），
+ *            与主线程共用 core/TextureDecode.ts 的同一份实现。
+ * 抓取（fetch）仍由 S3MTileset 在主线程做——重试、退避、content-type 检查这些
+ * 语义都留在原处不动，Worker 只收字节、吐纯数据结果。
+ *
+ * 协议：
+ *   { type:'parse', id, buffer } → { id, ok:true, tile } | { id, ok:false, message, permanent }
+ *   { type:'tex',  id, tex }     → { id, ok:true, data } | { id, ok:false, message }
+ *
+ * 线程安全：两个入口都无模块级可变状态；每次调用用独立的 reader / 解码器实例。
+ */
+import { parseS3MB } from '../core/S3MBParser.js';
+import { decodeTextureData } from '../core/TextureDecode.js';
+import type { ParsedTile, S3MTexture } from '../core/types.js';
+import { collectTransferables } from './transferables.js';
+
+type ParseRequest = { type: 'parse'; id: number; buffer: ArrayBuffer };
+type TexRequest = { type: 'tex'; id: number; tex: S3MTexture };
+type Request = ParseRequest | TexRequest;
+
+type ParseResponse =
+  | { id: number; ok: true; tile: ParsedTile }
+  | { id: number; ok: false; message: string; permanent: boolean };
+
+type TexResponse = { id: number; ok: true; data: Awaited<ReturnType<typeof decodeTextureData>> };
+
+const ctx = self as unknown as Worker;
+
+/** 纹理解码响应的传输清单：RGBA 像素 buffer + WEBP 的 ImageBitmap 都走零拷贝 */
+function texTransferList(data: Awaited<ReturnType<typeof decodeTextureData>>): ArrayBuffer[] {
+  const list = collectTransferables(data);
+  if (data.bitmap) list.push(data.bitmap as unknown as ArrayBuffer);
+  return list;
+}
+
+ctx.onmessage = async (e: MessageEvent<Request>) => {
+  const msg = e.data;
+  const { id } = msg;
+  try {
+    if (msg.type === 'parse') {
+      const tile = await parseS3MB(msg.buffer);
+      // 响应整体过线（零拷贝）；请求 buffer 是主线程 structured clone 过来的副本，无需回传
+      ctx.postMessage({ id, ok: true, tile } satisfies ParseResponse, collectTransferables(tile));
+    } else {
+      const data = await decodeTextureData(msg.tex);
+      ctx.postMessage({ id, ok: true, data } satisfies TexResponse, texTransferList(data));
+    }
+  } catch (err) {
+    const permanent = (err as { permanent?: boolean } | null)?.permanent === true;
+    const message = String((err as Error | null)?.message ?? err);
+    ctx.postMessage({ id, ok: false, message, permanent });
+  }
+};

package/src/worker/transferables.ts

@@ -0,0 +1,58 @@
+/**
+ * 传输清单收集：递归扫出对象图里所有可 Transfer 的 ArrayBuffer（去重）。
+ *
+ * 用于 Worker 往返的零拷贝：postMessage 的 transferList 传这个清单后，
+ * 线程间共享同一块内存（structured clone 只拷贝「壳」，不拷字节）。
+ *
+ * 安全性约定：**要么全转，要么不转** —— 同一块 ArrayBuffer 上可能挂着多个视图
+ * （positions / normals 常是同一块顶点缓冲的 subarray），transferList 里出现它一次
+ * 之后所有视图共享的底层数据整体过线，视图本身仍然有效；但如果只转一半视图、
+ * 另一半留在原地，留在原地的会因 detach 变成空数据。所以只允许「把整个对象图
+ * 的 buffer 全部收集」或「完全不收集」两种用法，不支持挑着转。
+ */
+
+/** 递归深度上限。ParsedTile 的层级是固定的（tile → geoPackage → geode → package），远用不到 12 层 */
+const MAX_DEPTH = 12;
+
+export function collectTransferables(root: unknown): ArrayBuffer[] {
+  const buffers = new Set<ArrayBuffer>();
+  const seen = new Set<object>();
+
+  const walk = (value: unknown, depth: number): void => {
+    if (value == null || depth > MAX_DEPTH) return;
+    if (ArrayBuffer.isView(value)) {
+      const b = (value as ArrayBufferView).buffer;
+      if (b instanceof ArrayBuffer) buffers.add(b);
+      return;
+    }
+    if (value instanceof ArrayBuffer) {
+      buffers.add(value);
+      return;
+    }
+    if (typeof value !== 'object') return;
+    const obj = value as object;
+    if (seen.has(obj)) return;
+    seen.add(obj);
+    if (Array.isArray(obj)) {
+      for (const item of obj) walk(item, depth + 1);
+      return;
+    }
+    if (obj instanceof Map) {
+      for (const [k, v] of obj) {
+        walk(k, depth + 1);
+        walk(v, depth + 1);
+      }
+      return;
+    }
+    if (obj instanceof Set) {
+      for (const item of obj) walk(item, depth + 1);
+      return;
+    }
+    for (const key of Object.keys(obj)) {
+      walk((obj as Record<string, unknown>)[key], depth + 1);
+    }
+  };
+
+  walk(root, 0);
+  return [...buffers];
+}