modelstage 0.0.0-stage → 0.5.28

package/src/web/engine/pma/resolve.js

@@ -0,0 +1,112 @@
+// engine/pma/resolve.js —— 决策：**唯一**算"怎么画"的地方（档位 + 探测结论 + 运行时能力 → 一份 decision）
+//
+// 上传（upload.js）与混合（blend.js / render-frame）都必须从这里派生，不允许各自再判断一次。
+// 本文件不读 DOM、不碰 GL —— 纯函数，便于单测钉住每一档。
+
+/**
+ * 档位 → decision。字段含义：
+ *   effectiveMode  最终生效的路径：premultiplied（源图已预乘）/ upload（上传时乘）/ straight（直通混合）
+ *   needPremultiply 是否**需要在上传时乘一次**（只有 upload 路径为 true）
+ *   blendMode      混合口径：premultiplied（src 因子用 ONE）/ straight（用 SRC_ALPHA）
+ *   degraded       是否因运行时能力不足而降级（显式 straight 落到 upload 时才是 true）
+ * @param {string} mode auto | premultiplied | straight | upload
+ * @param {{finalIsPremultiplied: boolean}} detection
+ * @param {boolean} supportsStraight 运行时是否支持非预乘直通混合
+ */
+export function resolvePmaInfo(mode, detection, supportsStraight) {
+  const auto = detection && detection.finalIsPremultiplied;
+  switch (mode) {
+    case 'premultiplied':
+      return { effectiveMode: 'premultiplied', needPremultiply: false, blendMode: 'premultiplied', runtimeSupportsStraight: supportsStraight, degraded: false };
+    case 'straight':
+      return supportsStraight
+        ? { effectiveMode: 'straight', needPremultiply: false, blendMode: 'straight', runtimeSupportsStraight: supportsStraight, degraded: false }
+        : { effectiveMode: 'upload', needPremultiply: true, blendMode: 'premultiplied', runtimeSupportsStraight: supportsStraight, degraded: true };
+    case 'upload':
+      return { effectiveMode: 'upload', needPremultiply: true, blendMode: 'premultiplied', runtimeSupportsStraight: supportsStraight, degraded: false };
+    case 'auto':
+    default: {
+      // 三态处理：明确预乘 / 明确非预乘 / **检测不出**
+      //   检测不出（auto 为 null/undefined）时**按已预乘**，对齐既有口径三条兜底（init-default / safe-fallback /
+      //   atlas 未声明）都默认 true 的做法。
+      //   理由与「沿袭既有」无关，而是**失败代价不对称**：
+      //     · 兜底成"非预乘" ⇒ needPremultiply=true ⇒ 若图其实是预乘的 ⇒ **双重预乘 ⇒ 明显黑圈**
+      //     · 兜底成"已预乘" ⇒ 不乘 ⇒ 若图其实是直通 ⇒ 只是混合略暗
+      //   少乘的可接受程度远高于多乘，所以不确定时选"不乘"。
+      if (auto === false) {
+        // 检测为"非预乘"。**运行时支持直通时，这一档必须与显式 straight 完全等价**：
+        //   都走 straight 混合、都不预乘。不看能力就无条件 upload（上传时预乘 + premultiplied 混合）
+        //   会让"自动"与"用户强制选非预乘"对同一张图给出两种画面 —— 实测就是面部/眼周白斑。
+        //   能力不允许时才退回 upload（与显式 straight 的降级方向一致，但 degraded 保持 false：
+        //   这不是"降级"，而是这台运行时唯一可行的路径，与改动前逐字段相同）。
+        return supportsStraight
+          ? { effectiveMode: 'straight', needPremultiply: false, blendMode: 'straight', runtimeSupportsStraight: supportsStraight, degraded: false }
+          : { effectiveMode: 'upload', needPremultiply: true, blendMode: 'premultiplied', runtimeSupportsStraight: supportsStraight, degraded: false };
+      }
+      return { effectiveMode: 'premultiplied', needPremultiply: false, blendMode: 'premultiplied', runtimeSupportsStraight: supportsStraight, degraded: false };
+    }
+  }
+}
+
+/**
+ * 上传口径：这一页贴图要不要在 `texImage2D` 那一下让浏览器乘一次 alpha。
+ *
+ * 三种输入（恰好是 `resolvePmaInfo` 的三个出口），只有第三种必须乘：
+ *   · 源图已预乘（`effectiveMode:'premultiplied'`，needPremultiply=false）⇒ **不乘**：再乘就是双重预乘（明显黑圈）
+ *   · 源图 straight 且走 straight 路径（`effectiveMode:'straight'`，needPremultiply=false）⇒ **不乘**：
+ *     乘了就和 straight 混合错配（数据是预乘、blend 却按直通）
+ *   · 源图 straight 且走 upload 路径（`effectiveMode:'upload'`，needPremultiply=true）⇒ **乘**：
+ *     运行时不支持直通混合，只能把数据也预乘，让"预乘数据 + 预乘 blend"配套（不乘就是白斑）
+ *
+ * 为什么单列成纯函数：`needPremultiply` 曾只作诊断、没有任何地方执行它，
+ *   于是 upload 路径「要求预乘却没乘」⇒ GPU 上是直通数据、却按预乘混合绘制 ⇒ 半透明边缘发白。
+ *   抽出来才能用单测把三种输入钉死，避免再次退化成"硬编码 false"。
+ * @param {{needPremultiply?: boolean}} info `resolvePmaInfo` 的结果
+ * @returns {boolean} 是否在上传时预乘
+ */
+export function shouldPremultiplyOnUpload(info) {
+  return !!(info && info.needPremultiply === true);
+}
+
+/**
+ * 上传口径的**完整派生**：`{ unpack, pmaFlag }`。
+ *
+ * 两个字段都是"从 decision 读出来"的派生量，不允许调用方再自己判断一次：
+ *   unpack   上传时要不要让浏览器乘一次 alpha —— 只有 upload 路径要（见 shouldPremultiplyOnUpload）
+ *   pmaFlag  **上传完成后 GPU 上的数据是否预乘**：
+ *              premultiplied（源图本来就预乘，原样传）⇒ true
+ *              upload       （上传时乘过一次，现在也是预乘）⇒ **true**
+ *              straight     （原样传，仍是直通）          ⇒ false
+ *            早前这里写成 `effectiveMode === 'premultiplied'`，把 upload 路径也标成 false ——
+ *            与"它其实已经预乘"自相矛盾。虽有该字段的消费方目前是保留路径（无运行时带 pma 属性），
+ *            但语义必须与数据真实形态一致，否则下一个人会照它做判断。
+ * @param {{effectiveMode?: string, needPremultiply?: boolean}} info `resolvePmaInfo` 的结果
+ * @returns {{unpack: boolean, pmaFlag: boolean}}
+ */
+export function planTextureUpload(info) {
+  const mode = (info && info.effectiveMode) || '';
+  return {
+    unpack: shouldPremultiplyOnUpload(info),
+    pmaFlag: mode === 'premultiplied' || mode === 'upload',
+  };
+}
+
+// 混合口径只有两种结果，预建成冻结常量：planBlend 在**每帧**都会被调用，
+//   每次 new 一个对象等于每帧一次 GC 压力。返回共享常量既零分配也不会被误改。
+const BLEND_PREMULTIPLIED = Object.freeze({ premultiplied: true });
+const BLEND_STRAIGHT = Object.freeze({ premultiplied: false });
+
+/**
+ * 混合口径派生：只回答一件事 —— **绘制时按预乘还是直通混合**。
+ *
+ * `premultiplied` 直接喂给绘制层（决定 blend 的 src 因子是 `ONE` 还是 `SRC_ALPHA`、
+ *   以及顶点色是否乘 alpha）。"要不要改写 blendFunc"这件事**不在这里回答**：
+ *   blend.js 的 `installBlendHooks` 在每个上下文上装一次钩子，改写与否由它自己在
+ *   每次 `blendFunc` 调用时按 `pmaInfo.blendMode` 判断 —— 这里再给一个 needHook 字段
+ *   只会多出一份没人消费的平行语义（早前版本就这么干过，已删）。
+ * @param {{blendMode?: string}} info `resolvePmaInfo` 的结果
+ * @returns {{premultiplied: boolean}} 冻结的共享常量（零分配）
+ */
+export function planBlend(info) {
+  return (info && info.blendMode === 'premultiplied') ? BLEND_PREMULTIPLIED : BLEND_STRAIGHT;
+}

package/src/web/engine/pma/upload.js

@@ -0,0 +1,127 @@
+// engine/pma/upload.js —— 上传：按 decision 把贴图传到 GPU（**全项目唯一的纹理上传路径**）
+//
+// 上传口径只从 resolve.js 的 shouldPremultiplyOnUpload 派生，本文件不自己判断"要不要乘"。
+// 关键：预乘要在 texImage2D 那一下由浏览器完成，**不经 2D canvas 中转** ——
+//   2D canvas 的后备存储是预乘的，texImage2D(canvas) 在 UNPACK=false 时会把 alpha 除回去
+//   （un-premultiply）⇒ "CPU 先乘一遍"白做，上传到 GPU 仍是直通数据。
+//   所以要么用 Uint8Array 源、要么用原图 + UNPACK 开关，才能真正控制上传字节。
+
+import { planTextureUpload } from './resolve.js';
+
+/**
+ * 按 PMA 口径上传贴图。
+ * pma 语义：`pma = true` 表示**这张图（现在）已经是预乘的**。
+ * @param {{gl: WebGLRenderingContext, GLTextureCtor: Function|null, entries: Map,
+ *          effectiveMode: string, needPremultiply: boolean, textureFilter: string,
+ *          log?: Function, onUpload?: Function}} ctx
+ * @returns {Promise<Map<string, object>>} 页名 → 纹理对象
+ */
+export async function uploadTextures(ctx) {
+  const { gl, GLTextureCtor, entries, effectiveMode, needPremultiply, textureFilter, log = () => {}, onUpload } = ctx;
+  // 上传口径整份来自 decision（不在这里二次判断），见 resolve.js 的 planTextureUpload
+  const { unpack, pmaFlag } = planTextureUpload({ effectiveMode, needPremultiply });
+  const plan = {
+    unpack,
+    pmaFlag,
+    // 诊断标签用"走的哪条路"（upload / straight / premultiplied），不能拿 pmaFlag 代替它：
+    //   pmaFlag 回答的是"上传后数据是不是预乘"（upload 路径也是 true），两者语义不同。
+    mode: effectiveMode,
+    textureFilter,
+    log,
+    onUpload,
+  };
+  const out = new Map();
+  for (const [pageName, entry] of (entries || new Map())) {
+    const tex = uploadOnePage(gl, GLTextureCtor, pageName, entry, plan);
+    if (tex) out.set(pageName, tex);
+  }
+  if (out.size === 0) throw new Error('没有成功上传任何贴图到 GPU，无法创建 TextureAtlas');
+  return out;
+}
+
+/**
+ * 上传单页（GLTexture 优先，失败回退手动上传）。
+ * @returns {object|null} 纹理对象
+ */
+function uploadOnePage(gl, GLTextureCtor, pageName, entry, plan) {
+  const source = entry.img || entry.canvas || null;   // 原图（或透明占位画布）直传
+  if (!source) return null;
+  if (GLTextureCtor) {
+    const viaCtor = uploadViaGLTexture(gl, GLTextureCtor, pageName, entry, source, plan);
+    if (viaCtor) return viaCtor;
+  }
+  return uploadManually(gl, pageName, entry, source, plan);
+}
+
+/** 用运行时的 GLTexture 上传（构造期即完成上传） */
+function uploadViaGLTexture(gl, GLTextureCtor, pageName, entry, source, plan) {
+  const prevUnpack = readUnpack(gl);
+  try {
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, plan.unpack);
+    const tex = new GLTextureCtor(gl, source);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, prevUnpack);
+    applyTextureFilterLike(gl, tex, plan.textureFilter);
+    notify(plan, { page: pageName, mode: plan.mode,
+      unpack: plan.unpack, source: entry.img ? 'img' : 'canvas', path: 'GLTexture', texHasPma: 'pma' in tex });
+    return tex;
+  } catch (e) {
+    plan.log('warn', `创建 GLTexture 失败 ${pageName}: ${(e && e.message) || e}，回退手动上传`, 'loader');
+    try { gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, prevUnpack); } catch { /* 忽略 */ }
+    return null;
+  }
+}
+
+/** 回退：手动 createTexture + texImage2D（同样按 plan.unpack 决定是否让浏览器乘） */
+function uploadManually(gl, pageName, entry, source, plan) {
+  const tex = gl.createTexture();
+  if (!tex) return null;
+  const prevUnpack = readUnpack(gl);
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+  gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, plan.unpack);
+  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+  gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, prevUnpack);
+  const filterMode = plan.textureFilter === 'nearest' ? gl.NEAREST : gl.LINEAR;
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filterMode);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filterMode);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  notify(plan, { page: pageName, mode: plan.mode,
+    unpack: plan.unpack, source: 'manual', path: 'manual', texHasPma: false });
+  return {
+    _image: source, getImage() { return this._image; },
+    setFilters(min, mag) {
+      try {
+        gl.bindTexture(gl.TEXTURE_2D, tex);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, min);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, mag);
+      } catch { /* 忽略 */ }
+    },
+    setWraps() {}, dispose() { try { gl.deleteTexture(tex); } catch { /* 忽略 */ } }, texture: tex,
+  };
+}
+
+/** 读当前 UNPACK 状态（拿不到返回 false） */
+function readUnpack(gl) {
+  try { return gl.getParameter(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL); } catch { return false; }
+}
+
+/** 观测回调（默认打到 debug 日志；不参与逻辑） */
+function notify(plan, detail) {
+  try {
+    if (typeof plan.onUpload === 'function') plan.onUpload(detail);
+    else plan.log('debug', 'pma.upload', detail);
+  } catch { /* 观测不能影响上传 */ }
+}
+
+/** 过滤参数（与 textures.js 的 applyTextureFilter 等价；此处内联以避免循环依赖） */
+function applyTextureFilterLike(gl, texture, mode) {
+  const filterMode = mode === 'nearest' ? gl.NEAREST : gl.LINEAR;
+  try {
+    if (typeof texture.setFilters === 'function') texture.setFilters(filterMode, filterMode);
+    else {
+      gl.bindTexture(gl.TEXTURE_2D, texture.texture || texture);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filterMode);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filterMode);
+    }
+  } catch { /* 过滤设置失败不影响可用性 */ }
+}

package/src/web/engine/pma.js

@@ -0,0 +1,5 @@
+// engine/pma.js —— 转发层：实现已按职责拆到 `pma/` 目录（detect / resolve / upload / blend）。
+//
+// 保留本文件是为了**对外导入路径不变**：textures.js / appearance.js / pipeline.js
+//   都还写 `./pma.js`（textures.js 那层再转发也保留）。真正的代码在本目录的 index.js 里再导出。
+export * from './pma/index.js';

package/src/web/engine/render-frame.js

@@ -0,0 +1,93 @@
+// engine/render-frame.js —— 帧循环与绘制（从 player 抽出，控制单文件规模）
+//
+// 帧调度选择：**渲染器自建 rAF（方案 A）**，与现状一致；
+//   StageSurface 只负责尺寸与背景，不接管渲染帧（统一调度属 B6 收尾，需同时改 surface 与 canvas.js）。
+
+import { hideFilteredSlots, restoreFilteredSlots } from './skins.js';
+import { createFrameGate } from './frame-gate.js';
+import { planBlend } from './pma.js';
+
+/** 绘制一帧 */
+export function renderFrame(engine) {
+  // 重建期间不出帧：loadingModel 之前只有"设"没有人"读"，这里让它真的生效
+  //   （重建会把 skeleton/renderer 短暂处于半换血状态，画出来只会闪）
+  if (engine.loadingModel) return;
+  const { gl, skeleton, renderTarget } = engine;
+  if (!gl || !skeleton || !renderTarget || !engine.adapters) return;
+  gl.clearColor(0, 0, 0, 0);
+  gl.clear(gl.COLOR_BUFFER_BIT);
+  // 混合口径由 pma 决策派生出（不是纹理是否预乘）：planBlend 返回共享常量，热路径零分配
+  const blendPma = planBlend(engine.pmaInfo).premultiplied;
+  // 部件过滤要在绘制前摘件、绘制后挂回（finally 保证异常路径也不缺件）
+  hideFilteredSlots(engine);
+  let ok = false;
+  try {
+    ok = engine.adapters.renderer.draw(renderTarget, skeleton, blendPma);
+    // 调试层叠在主绘制之上（全关时 drawDebug 自身直接返回，不碰 GL）
+    engine.adapters.renderer.drawDebug(renderTarget, skeleton, engine.debugDraw, blendPma);
+  } finally {
+    restoreFilteredSlots(engine);
+  }
+  if (!ok && !engine.renderWarned) {
+    engine.renderWarned = true;
+    engine.log('error', '渲染失败：适配器未能绘制（详见能力告警）', 'renderer');
+  }
+}
+
+/** 首帧：更新一次状态并立即绘制 */
+export function presentFirstFrame(engine) {
+  if (!engine.skeleton || !engine.renderer) {
+    engine.pendingPresent = false;
+    return;
+  }
+  try {
+    if (engine.state && engine.state.apply) {
+      engine.state.update(0);
+      engine.state.apply(engine.skeleton);
+    }
+    if (engine.adapters) engine.adapters.skeleton.updateWorldTransform(engine.skeleton);
+    renderFrame(engine);
+  } catch { /* 首帧失败留给主循环 */ }
+  engine.pendingPresent = false;
+}
+
+/** 起主循环（幂等：已在跑则只把 isPlaying 置真） */
+export function startLoop(engine) {
+  if (engine.animationId !== null) { engine.isPlaying = true; return; }
+  engine.isPlaying = true;
+  engine.lastTime = performance.now();
+  engine.fpsLastTime = engine.lastTime;
+  engine.fpsFrames = 0;
+  // 帧率门控用累加器（见 frame-gate.js）：单门限会把每帧的零头丢掉，
+  //   长期平均偏低，且相位抖动时会连放两帧（90Hz 屏上表现为帧率超过目标）。
+  engine.frameGate = createFrameGate(() => engine.fpsLimit);
+  engine.lastTickAt = engine.lastTime;
+  const loop = () => {
+    if (!engine.isPlaying) return;
+    engine.animationId = requestAnimationFrame(loop);
+    const now = performance.now();
+    // 先算"距上一 tick 的间隔"再判门控：动画时钟 lastTime 只在实际渲染时推进，语义不变
+    const tickDelta = now - engine.lastTickAt;
+    engine.lastTickAt = now;
+    if (!engine.frameGate.shouldRender(tickDelta)) return;
+    let dt = (now - engine.lastTime) / 1000;
+    engine.lastTime = now;
+    dt = Math.min(dt, 0.1);
+    engine.fpsFrames += 1;
+    if (now - engine.fpsLastTime >= 500) {
+      engine.currentFps = (engine.fpsFrames * 1000) / (now - engine.fpsLastTime);
+      engine.fpsFrames = 0;
+      engine.fpsLastTime = now;
+    }
+    engine.update(dt);
+    renderFrame(engine);
+  };
+  loop();
+}
+
+/** 停主循环 */
+export function stopLoop(engine) {
+  if (engine.animationId !== null) cancelAnimationFrame(engine.animationId);
+  engine.animationId = null;
+  engine.isPlaying = false;
+}

package/src/web/engine/runtime-capabilities.js

@@ -0,0 +1,209 @@
+// engine/runtime-capabilities.js —— 运行时能力探测（一次，缓存）
+//
+// 设计原则：
+//   · **只探测，不看版本号**：拿到命名空间后逐项问"这个方法/类在不在"；
+//   · 版本号仅用于日志与 getRendererInfo 展示，不参与任何行为分支；
+//   · 探测结果即"能力矩阵"：渲染/纹理/图集/骨架四组，业务层只读该矩阵；
+//   · 探测失败不静默：写进 `warns`，由调用方统一打到 log(warn)。
+//
+// 为什么必须这样做（实测教训）：切片按 4.x 的调用写死了 `texture.bind()`，
+//   而 3.8 的纹理对象没有 bind ⇒ 每帧抛错、画面全空且错误被 catch 进 lastError，极难定位。
+
+/** 在命名空间顶层与 `webgl` 子命名空间里找类/方法（3.x 的 WebGL 类只在子命名空间） */
+export function pickMember(ns, name) {
+  if (!ns) return null;
+  if (ns[name] != null) return ns[name];
+  const w = ns.webgl;
+  if (w && w[name] != null) return w[name];
+  return null;
+}
+
+/** 探测某个类的原型上是否有指定方法 */
+function hasProtoMethod(cls, name) {
+  try { return !!(cls && cls.prototype && typeof cls.prototype[name] === 'function'); } catch { return false; }
+}
+
+/** 构造签名探测：用 `Function.prototype.length` 判断必填参数个数 */
+function arityOf(cls) {
+  try { return cls && typeof cls === 'function' ? cls.length : 0; } catch { return 0; }
+}
+
+/** 诊断开关：URL 里 `?missing-capability=<key>` 可强制某项探测为 false，用于验证降级路径 */
+function simulatedMissing() {
+  try {
+    const v = new URLSearchParams(window.location.search).get('missing-capability');
+    return v ? new Set(v.split(',').map((s) => s.trim()).filter(Boolean)) : new Set();
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * 一次性取出运行时成员（顺序与原实现逐条一致，**不要重排**）。
+ * 为什么集中在一处调用而不是各段自己取：成员读取是"读事实"，
+ *   集中取能保证四段只做"判断"、不各自重取同一成员 —— 顺序一变，
+ *   `pickMember` 的调用序列就变了，等价验证会当场失败。
+ * @param {object} spine 运行时命名空间
+ */
+function collectMembers(spine) {
+  return {
+    Texture: pickMember(spine, 'Texture'),
+    GLTexture: pickMember(spine, 'GLTexture'),
+    TextureAtlas: pickMember(spine, 'TextureAtlas'),
+    SceneRenderer: pickMember(spine, 'SceneRenderer'),
+    SkeletonRenderer: pickMember(spine, 'SkeletonRenderer'),
+    OrthoCamera: pickMember(spine, 'OrthoCamera'),
+    PolygonBatcher: pickMember(spine, 'PolygonBatcher'),
+    SkeletonJson: pickMember(spine, 'SkeletonJson'),
+    SkeletonBinary: pickMember(spine, 'SkeletonBinary'),
+    AtlasAttachmentLoader: pickMember(spine, 'AtlasAttachmentLoader'),
+    Vector2: pickMember(spine, 'Vector2'),
+    Skin: pickMember(spine, 'Skin'),
+    // 调试绘制渲染器：3.x/4.x 都叫 SkeletonDebugRenderer（个别版本叫 DebugRenderer），没有就只能不画
+    SkeletonDebugRenderer: pickMember(spine, 'SkeletonDebugRenderer') || pickMember(spine, 'DebugRenderer'),
+  };
+}
+
+/** 纹理组：3.x 的 GLTexture 有 bind()/setFilters()；4.x 也有，但若换成 Texture 基类则没有 */
+function probeTexture(m, missing, say) {
+  const hasBind = say(!missing.has('textureBind') && (hasProtoMethod(m.GLTexture, 'bind') || hasProtoMethod(m.Texture, 'bind')),
+    'texture.bind', '纹理对象没有 bind()（批处理器需要它）');
+  const hasSetFilters = hasProtoMethod(m.GLTexture, 'setFilters') || hasProtoMethod(m.Texture, 'setFilters');
+  const hasDispose = hasProtoMethod(m.GLTexture, 'dispose') || hasProtoMethod(m.Texture, 'dispose');
+  return { hasBind, hasSetFilters, hasDispose, glTextureCtor: m.GLTexture, textureCtor: m.Texture };
+}
+
+/** 图集组：4.x 的 TextureAtlas 只吃 (data)；3.x 吃 (data, resolver) */
+function probeAtlas(m, missing, say) {
+  const arity = arityOf(m.TextureAtlas);
+  const acceptsResolver = say(!missing.has('atlasResolver') && arity >= 2,
+    'atlas.resolver', `TextureAtlas 构造只接受 ${arity} 个参数，纹理需要构造后补挂`);
+  return { ctor: m.TextureAtlas, acceptsResolver, arity };
+}
+
+/** 渲染器组：3.x SceneRenderer(canvas, gl) 自带相机；4.x 可能只有 SkeletonRenderer(gl) */
+function probeRenderer(m, warns) {
+  const sceneArity = arityOf(m.SceneRenderer);
+  const kind = m.SceneRenderer ? 'scene' : (m.SkeletonRenderer ? 'skeleton' : 'none');
+  if (kind === 'none') warns.push('renderer：没有 SceneRenderer / SkeletonRenderer，无法渲染');
+  const hasCameraOnScene = !!(m.SceneRenderer && m.SceneRenderer.prototype && 'camera' in m.SceneRenderer.prototype);
+  return {
+    kind,
+    sceneCtor: m.SceneRenderer,
+    skeletonCtor: m.SkeletonRenderer,
+    sceneArity,
+    hasCameraOnScene,
+    orthoCtor: m.OrthoCamera,
+    orthoArity: arityOf(m.OrthoCamera),
+    batcherCtor: m.PolygonBatcher,
+    // 调试绘制（bones/meshes/... 八类）：没有构造器时该能力整体不可用，由调用方降级
+    debugCtor: m.SkeletonDebugRenderer,
+  };
+}
+
+/**
+ * 骨架组：四个构造器 + skeletonOps 的四项方法探测。
+ *
+ * `pickMember(spine,'Skeleton')` **只取一次**（局部变量 Skeleton）。
+ *   早先这里是 5 次（setToSetupPose 那行因短路写了两遍、其余三项各一次），当时刻意不合并，
+ *   理由是"合并会改变成员读取次数这个可观测事实"，留给后续单独一轮处理 —— 本轮就是那一轮：
+ *   已合并，读取次数从 5 次（无 Spine 时因短路为 4 次）降为 1 次。
+ *   四项探测结果逐项不变；等价脚本的判据也从"读取序列相同"改成"探测结果相同"
+ *   （见 tool/.tmp-caps-equiv.mjs 的 diff 注释：读取次数是该优化的目标本身，不能同时当等价标尺）。
+ */
+function probeSkeleton(spine, m, warns) {
+  const Skeleton = pickMember(spine, 'Skeleton');
+  const skeletonOps = {
+    setToSetupPose: !!(Skeleton && hasProtoMethod(Skeleton, 'setToSetupPose')),
+    updateWorldTransform: hasProtoMethod(Skeleton, 'updateWorldTransform'),
+    getBounds: hasProtoMethod(Skeleton, 'getBounds'),
+    setSkin: hasProtoMethod(Skeleton, 'setSkin'),
+  };
+  for (const [k, ok] of Object.entries(skeletonOps)) {
+    if (!ok) warns.push(`skeletonOps.${k}：缺失（相关功能会降级）`);
+  }
+  return {
+    skeleton: { jsonCtor: m.SkeletonJson, binaryCtor: m.SkeletonBinary, attachmentLoaderCtor: m.AtlasAttachmentLoader, vector2: m.Vector2 },
+    ops: skeletonOps,
+  };
+}
+
+/**
+ * 精简矩阵的构造（给 getRendererInfo 展示用）。由返回对象的 `matrix()` 传 this 进来调用，
+ *   抽出成独立函数只是为了让 detectCapabilities 本体保持"只做编排"。
+ * @param {object} caps detectCapabilities 的产出（必须有 texture/atlas/renderer/skeleton/skeletonOps）
+ */
+function matrixOf(caps) {
+  return {
+    textureBind: caps.texture.hasBind,
+    textureFilters: caps.texture.hasSetFilters,
+    atlasResolver: caps.atlas.acceptsResolver,
+    rendererKind: caps.renderer.kind,
+    sceneHasCamera: caps.renderer.hasCameraOnScene,
+    batcher: !!caps.renderer.batcherCtor,
+    skeletonJson: !!caps.skeleton.jsonCtor,
+    skeletonBinary: !!caps.skeleton.binaryCtor,
+    orthoCamera: !!caps.renderer.orthoCtor,
+    skeletonDebug: !!caps.renderer.debugCtor,
+    ops: { ...caps.skeletonOps },
+  };
+}
+
+/**
+ * 探测一个运行时命名空间的能力。
+ * @param {object} spine 运行时命名空间
+ * @param {string} version 版本号（仅记录）
+ * @returns {object} 能力矩阵
+ */
+export function detectCapabilities(spine, version) {
+  const missing = simulatedMissing();
+  const warns = [];
+  /** say：探测结果收集器 —— 不 ok 就记一条 warn，并把 ok 原样返回（供三元/&& 链式使用） */
+  const say = (ok, key, reason) => { if (!ok) warns.push(`${key}：${reason}`); return ok; };
+
+  const m = collectMembers(spine);
+  const texture = probeTexture(m, missing, say);
+  const atlas = probeAtlas(m, missing, say);
+  const renderer = probeRenderer(m, warns);
+  const sk = probeSkeleton(spine, m, warns);
+
+  return {
+    version, // 仅用于展示
+    texture,
+    atlas,
+    renderer,
+    skeleton: sk.skeleton,
+    skinCtor: m.Skin,
+    skeletonOps: sk.ops,
+    warns,
+    /**
+     * 精简矩阵（给 getRendererInfo 展示用）。
+     * 这是**返回对象上的方法**，把 `this` 交给 matrixOf 构造 ——
+     *   不要改成箭头函数（箭头函数没有自己的 this，会读到模块作用域）；
+     *   也不要把 capabilities 深拷贝 / JSON 序列化后跨线程传（this 会失效，调用即抛错）。
+     */
+    matrix() { return matrixOf(this); },
+  };
+}
+
+/** 按版本缓存探测结果（同一运行时只探测一次） */
+const cache = new Map();
+
+/**
+ * 取（或首次探测）某版本的能力矩阵。
+ * @param {object} spine
+ * @param {string} version
+ * @returns {object}
+ */
+export function capabilitiesFor(spine, version) {
+  const key = String(version || 'unknown');
+  if (cache.has(key)) return cache.get(key);
+  const caps = detectCapabilities(spine, key);
+  cache.set(key, caps);
+  return caps;
+}
+
+/** 清空缓存（测试/重建上下文时用） */
+export function resetCapabilities() {
+  cache.clear();
+}

package/src/web/engine/runtime.js

@@ -0,0 +1,37 @@
+// engine/runtime.js —— 取 Spine 运行时命名空间（按骨架版本，带降级）
+//
+// 为什么不在这里自己加载源码：运行时管理已由 `spine/runtimes.js` 负责（版本清单、源码缓存、
+//   隔离执行、能力探测）。引擎只消费它的结果，避免出现两套版本选择逻辑。
+
+/**
+ * 解析某骨架版本对应的运行时命名空间。
+ * @param {object} manager SpineRuntimeManager 实例（由调用方注入，引擎不自己 new）
+ * @param {string} version 骨架版本（如 '3.8' / '4.1'）
+ * @returns {Promise<{spine: object, version: string, supportsStraightAlpha: boolean}>}
+ */
+export async function resolveRuntime(manager, version) {
+  if (!manager || typeof manager.getRuntimeWithFallback !== 'function') {
+    throw new Error('engine: 缺少运行时管理器（需要 getRuntimeWithFallback）');
+  }
+  const entry = await manager.getRuntimeWithFallback(version);
+  if (!entry || !entry.spine) throw new Error(`engine: 运行时 ${version} 不可用`);
+  return { spine: entry.spine, version: entry.version, supportsStraightAlpha: entry.supportsStraightAlpha !== false };
+}
+
+/**
+ * 按名字取运行时里的类。
+ * 为什么需要：目录里 7 个版本的命名空间形状不同 ——
+ *   · 3.x：核心类（TextureAtlas/SkeletonJson/Skeleton…）在顶层，WebGL 类只挂在 `spine.webgl`；
+ *   · 4.x：全部平铺在顶层（没有 `webgl` 子命名空间）。
+ *   统一走这个名字解析，避免每处都写一遍兼容分支。
+ * @param {object} spine 运行时命名空间
+ * @param {string} name 类名
+ * @returns {Function|null}
+ */
+export function pickClass(spine, name) {
+  if (!spine) return null;
+  if (typeof spine[name] === 'function') return spine[name];
+  const w = spine.webgl;
+  if (w && typeof w[name] === 'function') return w[name];
+  return null;
+}