s3m-three 0.3.5 → 0.3.7

package/src/render/S3MViewer.ts

@@ -23,7 +23,8 @@
 import * as THREE from 'three';
 import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
 import type { BuildTileFn, TileNode } from '../tileset/S3MTileset.js';
-import { setMaxAnisotropy } from './TextureFactory.js';
+import { setMaxAnisotropy, setCompressedTexturesSupported, setTextureOffThreadDecode } from './TextureFactory.js';
+import { decodeTextureWithWorker } from '../worker/S3MWorkerClient.js';
 import {
   STYLE,
   STYLE_LABELS,
@@ -193,6 +194,8 @@ export interface S3MViewerOptions {
   maxTiles?: number;
   /** 每个数据集并发请求数 */
   maxConcurrent?: number;
+  /** 是否用 Web Worker 解析经典 .s3mb 瓦片（默认开，崩溃自动降级主线程），见 S3MTilesetOptions.useWorker */
+  useWorker?: boolean;
   /** LOD 切换范围缩放系数（默认 1.0），> 1 更倾向保留粗模，< 1 提前换细模 */
   lodRangeScale?: number;
   /** 自定义瓦片构建器（测试 / 服务端渲染时注入） */
@@ -401,6 +404,8 @@ export class S3MViewer {
     );
 
     this.uniforms = createSharedUniforms();
+    // 纹理解码优先派给共享解析 Worker（崩溃自动回主线程，见 decodeTextureWithWorker）
+    setTextureOffThreadDecode(decodeTextureWithWorker);
     this.style = { ...DEFAULT_STYLE, ...(options.style ?? {}) };
     this.outlineMaterial = createOutlineMaterial(this.uniforms);
 
@@ -433,8 +438,7 @@ export class S3MViewer {
    * MapLibre 宿主由 S3MLayer 在 onAdd 里调用；纯 three 宿主直接传自己的 canvas / gl。
    */
   /** 创建并配置一个绑定到给定 gl 上下文的 three renderer（mount 与上下文恢复共用） */
-  private _createRenderer(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): THREE.WebGLRenderer {
-    const r = new THREE.WebGLRenderer({
+  private _createRenderer(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): THREE.WebGLRenderer {    const r = new THREE.WebGLRenderer({
       canvas,
       context: gl as WebGLRenderingContext,
       antialias: true,
@@ -447,11 +451,19 @@ export class S3MViewer {
     return r;
   }
 
+  /** 按 GL 能力开/关 DXT 压缩直传：两个 s3tc 扩展都要在（srgb 缺了贴图会发白失配） */
+  private _syncTextureCapabilities(gl: WebGLRenderingContext | WebGL2RenderingContext): void {
+    const s3tc = !!gl.getExtension('WEBGL_compressed_texture_s3tc');
+    const s3tcSrgb = !!gl.getExtension('WEBGL_compressed_texture_s3tc_srgb');
+    setCompressedTexturesSupported(s3tc && s3tcSrgb);
+  }
+
   mount(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): void {
     this.canvas = canvas;
 
     this.renderer = this._createRenderer(canvas, gl);
     setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy());
+    this._syncTextureCapabilities(gl);
 
     this.scene = new THREE.Scene();
     this.scene.add(this.groundManager.group);
@@ -493,6 +505,7 @@ export class S3MViewer {
     }
     this.renderer = this._createRenderer(this.canvas, gl);
     setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy());
+    this._syncTextureCapabilities(gl);
     this.picker?.dispose();
     this.picker = new Picker(this.renderer);
     // 共享 uniform / 材质引用不变，three 重新编译着色器时会自然接管；
@@ -604,7 +617,8 @@ export class S3MViewer {
 
   private _normalizeDatasets(options: S3MViewerOptions): S3MDatasetOptions[] {
     if (Array.isArray(options.datasets)) return options.datasets.filter((d) => !!d?.configUrl);
-    if (options.configUrl) return [{ id: 'default', name: '默认数据集', configUrl: options.configUrl }];
+    if (options.configUrl)
+      return [{ id: 'default', name: '默认数据集', configUrl: options.configUrl, useWorker: options.useWorker }];
     return [];
   }
 

package/src/render/StyleMaterial.ts

@@ -499,6 +499,12 @@ const FRAG_COLOR = /* glsl */ `
       diffuseColor.rgb = bState.rgb;
       hasCustomColor = true;
     }
+    // 单体独立透明度（状态纹理第 2 行 alpha，0 = 无覆盖）。
+    // 与全局 uOpacity（diffuseColor.a 初值）和图集贴图自带 alpha 逐级叠乘
+    vec4 bOffset = texture2D( uBatchTex, vec2( ( s3mBid + 0.5 ) / uBatchTexWidth, 0.75 ) );
+    if ( bOffset.a > 0.0 ) {
+      diffuseColor.a *= bOffset.a;
+    }
   }
 
   // 3. 选中单体高亮 + 其余压暗

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;
@@ -35,12 +21,46 @@ export function setMaxAnisotropy(n: number): void {
   maxAnisotropy = Math.max(1, n | 0);
 }
 
+/**
+ * DXT 压缩直传开关（S3MViewer 在 mount / 上下文恢复时按 GL 能力注入）：
+ * 需要 WEBGL_compressed_texture_s3tc 与 s3tc_srgb 两个扩展同时可用 ——
+ * 纹理是 SRGBColorSpace，缺 srgb 变体会出现贴图发白的颜色失配。
+ * 移动端大多没有 s3tc，自动回退 Worker 解码成 RGBA 上传，行为同旧版。
+ */
+let compressedTexturesSupported = false;
+
+export function setCompressedTexturesSupported(v: boolean): void {
+  compressedTexturesSupported = v;
+}
+
 export interface DecodedTexture {
   texture: THREE.Texture | null;
   /** 实际走的解码路径，`unsupported(26)` 这类值会进 stats.skipped */
   decoded: string;
 }
 
+/**
+ * 注入「离线解码」实现（S3MViewer 装配：走共享解析 Worker）。
+ * 返回 null = Worker 不可用 / 崩溃，createTexture 自动退回主线程 decodeTextureData。
+ */
+let offThreadDecode:
+  | ((tex: S3MTexture, compressed: boolean) => Promise<DecodedTextureData | null>)
+  | null = null;
+
+export function setTextureOffThreadDecode(
+  fn: ((tex: S3MTexture, compressed: boolean) => Promise<DecodedTextureData | null>) | null
+): void {
+  offThreadDecode = fn;
+}
+
+async function decodeTexture(tex: S3MTexture, compressed: boolean): Promise<DecodedTextureData> {
+  if (offThreadDecode) {
+    const viaWorker = await offThreadDecode(tex, compressed);
+    if (viaWorker) return viaWorker;
+  }
+  return decodeTextureData(tex, { compressed });
+}
+
 function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   tex.wrapS = THREE.RepeatWrapping;
   tex.wrapT = THREE.RepeatWrapping;
@@ -74,117 +94,52 @@ 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);
-
-  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) {
+
+  // 压缩直传只在「宿主 GL 支持 + 非图集」时开：图集要 flipY / 无 mip，压缩上传做不了翻行
+  const wantCompressed = compressedTexturesSupported && !isAtlas;
+  const data = await decodeTexture(tex, wantCompressed);
+
+  if (!data.rgba && !data.blocks && !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 if (data.blocks && data.blockFormat) {
+    // DXT 块直传：GPU 硬件解压，省 4~8 倍上传带宽与显存。压缩纹理不能 generateMipmaps
+    // （WebGL 限制），远处靠 LinearFilter 兜底；s3mHasAlpha 走 alphaTest 的 DXT1 1bit
+    // alpha 历史上没开过，DXT5 的 hasAlpha 由 decodeTextureData 判定
+    const format =
+      data.blockFormat === 'dxt1' ? THREE.RGB_S3TC_DXT1_Format : THREE.RGBA_S3TC_DXT5_Format;
+    texture = new THREE.CompressedTexture(
+      [{ data: data.blocks, width: data.width, height: data.height }],
+      data.width,
+      data.height,
+      format,
+      THREE.UnsignedByteType
+    );
+  } 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' };
+  texture.needsUpdate = true;
+  const configured = isAtlas ? configureAtlas(texture) : configure(texture);
+  if (data.blocks) {
+    configured.generateMipmaps = false;
+    configured.minFilter = THREE.LinearFilter;
   }
-
-  if (kind === 'raw') {
-    const decoded = fromRawRGB(tex);
-    return { texture: asAtlas(decoded), decoded: 'raw' };
-  }
-
-  // KTX2 / ETC 需要额外解码器，先如实上报而不是静默出错
-  return { texture: null, decoded: `unsupported(${tex.compressType}/${tex.pixelFormat})` };
+  // flipY 为真即 S3MBLOCK 图集（见 core/types.ts），必须无 mip
+  return { texture: configured, 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,
@@ -26,6 +27,7 @@ import type {
   TexblockRequestPlan,
 } from '../core/S3MBlockParser.js';
 import type { Anchor, ParsedTile, Stats, StyleUniforms } from '../core/types.js';
+import type { TileGeometryData } from '../core/TileGeometry.js';
 import type { Group, Texture } from 'three';
 
 function dirOf(url: string): string {
@@ -225,7 +227,12 @@ export interface TileNode {
 /** 瓦片构建器可注入，用于测试 / 服务端渲染（此时不需要 three） */
 export type BuildTileFn = (
   tile: ParsedTile,
-  options: { textureCache: Map<string, Texture>; uniforms: StyleUniforms | null }
+  options: {
+    textureCache: Map<string, Texture>;
+    uniforms: StyleUniforms | null;
+    /** Worker 侧已完成的纯数据几何组装（经典 .s3mb 路径），构建器直接包装成 three 对象 */
+    assembled?: TileGeometryData;
+  }
 ) => Promise<{ group: Group; stats: Partial<Stats> }>;
 
 export interface S3MTilesetOptions {
@@ -235,6 +242,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 +346,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 +364,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 +696,31 @@ export class S3MTileset {
     return this._buildTile;
   }
 
+  /**
+   * 经典 `.s3mb` 瓦片解析：优先走 Worker（inflate / Draco / MeshOpt / 几何组装
+   * 全在 Worker 做，一次往返带回 tile + 纯数据几何），Worker 不可用或已崩溃时
+   * 主线程兜底，两条路径输出完全一致。
+   */
+  private async _parseClassicTile(buffer: ArrayBuffer): Promise<{ tile: ParsedTile; geometry?: TileGeometryData }> {
+    if (this._useWorker && this._workerClient === undefined) {
+      // 与纹理解码共用进程级单例，避免每个数据集各起一个 Worker
+      this._workerClient = getSharedS3MWorker();
+    }
+    if (this._workerClient) {
+      try {
+        return await this._workerClient.parseTile(buffer, true);
+      } catch (e) {
+        if (e instanceof WorkerDeadError) {
+          // 脚本加载失败 / 崩溃属于环境问题，永久退回主线程；瓦片本身的问题照常抛
+          this._workerClient = null;
+        } else {
+          throw e;
+        }
+      }
+    }
+    return { tile: await parseS3MB(buffer) };
+  }
+
   /**
    * 记住一个块文件里解析出来的全部 LOD 组。
    *
@@ -948,6 +992,7 @@ export class S3MTileset {
       const isBlock = /\.s3mblock($|\?)/i.test(baseUrl);
 
       let tile: ParsedTile;
+      let assembled: TileGeometryData | undefined;
       let groupNames: string[] = [];
       const cachedSet = this._groupCache.get(baseUrl);
       if (cachedSet) {
@@ -970,7 +1015,9 @@ export class S3MTileset {
           groupNames = set.names;
           tile = set.tiles[groupIndex] ?? set.tiles[0]!;
         } else {
-          tile = await parseS3MB(buffer);
+          const parsed = await this._parseClassicTile(buffer);
+          tile = parsed.tile;
+          assembled = parsed.geometry;
         }
       }
       if (isBlock) {
@@ -980,7 +1027,11 @@ export class S3MTileset {
       }
 
       const build = await this._builder();
-      const buildRes = await build(tile, { textureCache: this.textureCache, uniforms: this._uniforms });
+      const buildRes = await build(tile, {
+        textureCache: this.textureCache,
+        uniforms: this._uniforms,
+        assembled,
+      });
       const { group, stats } = buildRes;
       const texKeys = (buildRes as any).textureKeys ?? (group.userData?.textureKeys as string[] | undefined) ?? Object.keys(tile.textures ?? {});
       this.registerTileTextures(url, texKeys);
@@ -1269,6 +1320,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,159 @@
+/**
+ * 解析 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';
+import type { TileGeometryData } from '../core/TileGeometry.js';
+
+/** Worker 崩溃 / 不可用 —— 与「瓦片数据本身有问题」区分开，调用方据此决定降级还是重试 */
+export class WorkerDeadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WorkerDeadError';
+  }
+}
+
+interface ParseOkResponse {
+  id: number;
+  ok: true;
+  tile: ParsedTile;
+  geometry?: TileGeometryData;
+}
+
+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({ tile: msg.tile, geometry: msg.geometry });
+      } else {
+        waiter.resolve(msg.data);
+      }
+    };
+    worker.onerror = () => this._die('s3m 解析 Worker 加载失败/崩溃');
+    worker.onmessageerror = () => this._die('s3m 解析 Worker 消息无法反序列化');
+  }
+
+  /**
+   * 解析一块瓦片。buffer 会被 structured clone（不 transfer），主线程保留原 buffer 以便崩溃后降级重解。
+   * assemble = true 时顺带在 Worker 里做纯数据几何组装，返回 { tile, geometry } 一次带回。
+   */
+  parseTile(buffer: ArrayBuffer, assemble = false, batching = true): Promise<{ tile: ParsedTile; geometry?: TileGeometryData }> {
+    if (this.dead) return Promise.reject(new WorkerDeadError('s3m 解析 Worker 已终止'));
+    const id = ++this._seq;
+    return new Promise<{ tile: ParsedTile; geometry?: TileGeometryData }>((resolve, reject) => {
+      this._pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      this._worker.postMessage({ type: 'parse', id, buffer, assemble, batching });
+    });
+  }
+
+  /** 解码一张纹理（DXT / CRN / WEBP / RGB 系）。tex.data 走 structured clone，主线程保留原数据 */
+  decodeTexture(tex: S3MTexture, compressed = false): 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, compressed });
+    });
+  }
+
+  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) 之类的标记）。
+ * compressed 由 TextureFactory 按宿主 GL 能力传入，Worker 端据此跳过 DXT 解码。
+ */
+export async function decodeTextureWithWorker(
+  tex: S3MTexture,
+  compressed: boolean
+): Promise<DecodedTextureData | null> {
+  const client = getSharedS3MWorker();
+  if (!client) return null;
+  try {
+    return await client.decodeTexture(tex, compressed);
+  } catch {
+    return null;
+  }
+}