modelstage 0.0.0-stage → 0.5.28

package/src/web/debug/race-probe.js

@@ -0,0 +1,82 @@
+// race-probe.js —— 竞态验收探针（跨 kind 连点，last-wins 后终态必须非空白）
+//
+// 判空白的方式（重要）：
+//   · 终态 spine 面 → stage.samplePixels().ratio（读的是 Spine WebGL 画布）
+//   · 终态 Live2D 面 → 不能用 samplePixels（那是 Spine 画布，此时被隐藏），
+//     改用 live2d.collectCmp() 的 extract.opaqueRatio（PIXI extract 出模型实际画出来的像素占比）
+(async () => {
+  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+  const q = (s) => document.querySelector(s);
+  const qa = (s) => [...document.querySelectorAll(s)];
+  const w = window.__WEB__;
+  const stageEl = q('#stage');
+  for (let i = 0; i < 80 && qa('[data-game-key]').length === 0; i += 1) await sleep(150);
+
+  const trajectory = [];
+  let last = '__init__';
+  const watch = setInterval(() => {
+    const v = stageEl.getAttribute('data-stage-mode');
+    if (v !== last) { last = v; trajectory.push(v); }
+  }, 30);
+
+  const click = async (kw, root) => {
+    const input = q('#roster-search');
+    input.value = kw;
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    for (let i = 0; i < 140 && qa('[data-model-id]').length === 0; i += 1) await sleep(150);
+    await sleep(250);
+    const row = qa('[data-model-id]').find((n) => n.dataset.rootId === root);
+    if (!row) return false;
+    row.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    return true;
+  };
+
+  /** 终态"画面上有没有东西"的量化：按当前面选口径 */
+  const contentRatio = async () => {
+    if (stageEl.getAttribute('data-stage-mode') === 'live2d') {
+      const rec = w.live2d.collectCmp('race-probe');
+      const ex = rec && rec.extract;
+      return ex && typeof ex.opaqueRatio === 'number' ? +ex.opaqueRatio.toFixed(4) : null;
+    }
+    return +w.stage.samplePixels().ratio.toFixed(4);
+  };
+
+  const L = ['abeikelongbi', 'azurlane'];
+  const S = ['aijier', 'azurlane_spine'];
+  const rounds = [];
+  for (const gap of [60, 150, 300]) {
+    for (const pair of [[L, S, 'spine'], [S, L, 'live2d']]) {
+      const [first, second, wantMode] = pair;
+      trajectory.length = 0;
+      const a = await click(first[0], first[1]);
+      await sleep(gap);
+      const b = await click(second[0], second[1]);
+      // 等到切换真正落定（首次装载 Live2D 要按需加载运行时库，固定 sleep 会误判成"还在 loading"）
+      for (let i = 0; i < 120 && stageEl.getAttribute('data-stage-mode') === 'loading'; i += 1) await sleep(150);
+      await sleep(1200);
+      const s = w.stage.stats();
+      const ratio = await contentRatio();
+      rounds.push({
+        gapMs: gap,
+        lastClick: second[1],
+        clicked: [a, b],
+        mode: stageEl.getAttribute('data-stage-mode'),
+        wantMode,
+        modeOk: stageEl.getAttribute('data-stage-mode') === wantMode,
+        live2dActive: !!(w.live2d && w.live2d.isActive()),
+        contentRatio: ratio,
+        nonBlank: ratio !== null && ratio > 0.05,
+        lastError: s.lastError,
+        stageReady: document.documentElement.dataset.stageReady,
+        hadLoading: trajectory.includes('loading'),
+        visibleFacesAtEnd: qa('#stage canvas').filter((c) => getComputedStyle(c).visibility !== 'hidden'
+          && getComputedStyle(c.parentElement || c).display !== 'none').length,
+        trajectory: trajectory.slice(0, 10).join('>'),
+      });
+    }
+  }
+  clearInterval(watch);
+  const logs = (w.stageLog || []).slice(-10).map((x) => `${x.level}:${x.line}`.slice(0, 88));
+  const failed = rounds.filter((r) => !r.modeOk || !r.nonBlank || r.lastError || !r.hadLoading).length;
+  return { failed, rounds, logs };
+})()

package/src/web/debug/upload.js

@@ -0,0 +1,130 @@
+// debug/upload.js —— 把页面内存里的调试日志上传到服务端「调试日志上传」按钮的行为
+//
+// 背景：调试日志只在内存（刷新即丢），用户描述问题时说不清、AI 又读不到浏览器。这个按钮把
+//   当前日志一次性交给服务端落盘（data/logs/），之后 AI 用 GET /api/diag/uploads 就能自己查到文件。
+//
+// 数据源**只从统一工厂取**（infra/log.js 的 recent）：那里的内容已经同时包含
+//   stageStatus 状态行（tag='stage'）与 diag 事件（tag='diag'）——这正是"走工厂化"的验证点，
+//   也避免出现"面板有、上传缺"的半套日志。
+//
+// 三态必须可见（不许静默）：
+//   上传中 → 按钮禁用 + 文案「上传中…」
+//   成功   → 「已上传：diag-….json（N 条 / X KB）」
+//   失败   → 「上传失败：<原因>（点按钮重试）」
+// 同时把状态写进 <html> 的 dataset（logUpload / logUploadMsg / logUploadCount），供自动化断言。
+
+import { postJson } from '../infra/api.js';
+import { recent } from '../infra/log.js';
+
+/** 一次最多捞多少条：与后端默认 maxCount 对齐（后端还会按配置再截一次） */
+const MAX_UPLOAD_COUNT = 5000;
+
+/** 字节数转人话（KB/MB 保留一位小数） */
+function humanBytes(n) {
+  const bytes = Number(n) || 0;
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(0)}KB`;
+  return `${bytes}B`;
+}
+
+/**
+ * 收集要上传的日志与上下文。
+ * meta 是为了"离线也能定位"：哪一版、哪个页面、什么模型/渲染器、什么浏览器。
+ * @param {() => object} readState 取应用状态的函数（避免本模块直接依赖 context.js）
+ * @returns {{logs: object[], meta: object, truncated: boolean}}
+ */
+export function collectPayload(readState) {
+  const all = recent();                       // 工厂里的全部（受 LOG_LIMIT 限制）
+  const truncated = all.length > MAX_UPLOAD_COUNT;
+  const logs = truncated ? all.slice(-MAX_UPLOAD_COUNT) : all;
+  let app = {};
+  try { app = (typeof readState === 'function' ? readState() : null) || {}; } catch { app = {}; }
+  const model = app.selectedModel || null;
+  const meta = {
+    version: app.version || '',
+    url: typeof location !== 'undefined' ? location.href : '',
+    ua: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+    at: Date.now(),
+    model: model ? (model.id || model.name || null) : null,
+    renderer: app.renderer || null,
+    count: logs.length,
+    clientTruncated: truncated,
+  };
+  return { logs, meta, truncated };
+}
+
+/**
+ * 建一个上传器：把按钮与状态文本接起来。
+ * @param {{
+ *   button: HTMLButtonElement,
+ *   statusEl?: HTMLElement,
+ *   readState?: () => object,
+ *   post?: (path: string, body: object) => Promise<any>,
+ * }} opts
+ * @returns {{run: () => Promise<object|null>, state: () => string, destroy: () => void}}
+ */
+export function createUploader(opts) {
+  const { button, statusEl } = opts;
+  const readState = opts.readState;
+  const post = typeof opts.post === 'function' ? opts.post : postJson;
+  let current = 'idle';
+  let lastResult = null;
+
+  /** 统一写状态：按钮文案/禁用、状态文本、<html> dataset 三处同源 */
+  function paint(next, text) {
+    current = next;
+    if (button) {
+      button.disabled = next === 'uploading';
+      // 文案用独立 span（避免把图标冲掉）：没有就退回纯文本
+      const label = button.querySelector('[data-upload-label]');
+      const word = next === 'uploading' ? '上传中…' : '上传日志';
+      if (label) label.textContent = word;
+      else button.textContent = word;
+      button.setAttribute('aria-busy', String(next === 'uploading'));
+    }
+    if (statusEl) {
+      statusEl.textContent = text || '';
+      statusEl.hidden = !text;
+    }
+    if (typeof document !== 'undefined' && document.documentElement) {
+      const ds = document.documentElement.dataset;
+      ds.logUpload = next;
+      ds.logUploadMsg = text || '';
+    }
+  }
+
+  /** 执行一次上传（幂等：上传中再点无效） */
+  async function run() {
+    if (current === 'uploading') return null;
+    const { logs, meta } = collectPayload(readState);
+    if (!logs.length) {
+      paint('fail', '上传失败：当前还没有日志可上传');
+      return null;
+    }
+    paint('uploading', `上传中…（${logs.length} 条）`);
+    try {
+      const res = await post('/api/diag/upload', { logs, meta });
+      if (!res || res.ok !== true) throw new Error((res && res.error) || '服务端未确认');
+      lastResult = res;
+      const extra = res.truncated ? '（服务端按上限截断）' : '';
+      paint('ok', `已上传：${res.file}（${res.count} 条 / ${humanBytes(res.bytes)}）${extra}`);
+      if (typeof document !== 'undefined' && document.documentElement) {
+        document.documentElement.dataset.logUploadCount = String(res.count);
+        document.documentElement.dataset.logUploadFile = String(res.file || '');
+      }
+      return res;
+    } catch (err) {
+      const reason = err && err.message ? err.message : String(err);
+      paint('fail', `上传失败：${reason}（点按钮重试）`);
+      return null;
+    }
+  }
+
+  return {
+    run,
+    state: () => current,
+    lastResult: () => lastResult,
+    /** 复位到空闲（重新打开面板/清空日志时用） */
+    reset: () => paint('idle', ''),
+  };
+}

package/src/web/engine/adapters/atlas.js

@@ -0,0 +1,47 @@
+// adapters/atlas.js —— 图集适配（构造签名差异 + 页纹理挂载）
+//
+// 3.x：`new TextureAtlas(text, imageResolver)` —— resolver 的返回值就是页纹理；
+// 4.x：`new TextureAtlas(text)` —— 不吃 resolver，必须构造后逐页补挂。
+// 这里用能力矩阵判断，不读版本号。
+
+/**
+ * @param {{caps: object, texture: object, onWarn?: Function}} ctx
+ */
+export function createAtlasAdapter({ caps, texture, onWarn }) {
+  const Ctor = caps.atlas.ctor;
+  if (!Ctor) throw new Error('运行时缺少 TextureAtlas');
+
+  /** 给尚未挂纹理的页补挂（4.x 路径；也兜住 3.x 中 resolver 未覆盖的页） */
+  function attachPages(atlas, resolveImage, premultiplied) {
+    for (const page of (atlas && atlas.pages) || []) {
+      if (page.texture) continue;
+      const img = resolveImage(page.name);
+      const tex = img ? texture.create(img, premultiplied) : texture.placeholder();
+      if (typeof page.setTexture === 'function') page.setTexture(tex);
+      else page.texture = tex;
+    }
+  }
+
+  /**
+   * 建图集。
+   * @param {string} text atlas 文本
+   * @param {(pageName: string) => any|null} resolveImage 页名 → 图片源
+   * @param {boolean} premultiplied
+   * @returns {object} atlas
+   */
+  function create(text, resolveImage, premultiplied) {
+    if (caps.atlas.acceptsResolver) {
+      // resolver 的返回值会被直接当作页纹理 ⇒ 必须在这里创建纹理对象（不能返回裸图片）
+      return new Ctor(text, (pageName) => {
+        const img = resolveImage(pageName);
+        return img ? texture.create(img, premultiplied) : texture.placeholder();
+      });
+    }
+    onWarn && onWarn(`atlas：该运行时 TextureAtlas 只接受 ${caps.atlas.arity} 个参数，改用"构造后补挂纹理"路径`);
+    const atlas = new Ctor(text);
+    attachPages(atlas, resolveImage, premultiplied);
+    return atlas;
+  }
+
+  return { create };
+}

package/src/web/engine/adapters/index.js

@@ -0,0 +1,22 @@
+// adapters/index.js —— 适配器装配：能力矩阵 → 各组适配器
+//
+// 业务层（player / loader / render-frame）只拿这里的对象，不直接摸 spine 库 API；
+// 于是"换运行时版本"只影响本目录，业务代码不含任何版本判断。
+
+import { createTextureAdapter } from './texture.js';
+import { createAtlasAdapter } from './atlas.js';
+import { createSkeletonAdapter } from './skeleton.js';
+import { createRendererAdapter } from './renderer.js';
+
+/**
+ * @param {{spine: object, caps: object, gl: WebGLRenderingContext, canvas: HTMLCanvasElement,
+ *          size: {w: number, h: number}, onWarn?: Function}} ctx
+ * @returns {{texture: object, atlas: object, skeleton: object, renderer: object, caps: object}}
+ */
+export function createAdapters({ spine, caps, gl, canvas, size, onWarn }) {
+  const texture = createTextureAdapter({ caps, gl, onWarn });
+  const atlas = createAtlasAdapter({ caps, texture, onWarn });
+  const skeleton = createSkeletonAdapter({ caps, spine, onWarn });
+  const renderer = createRendererAdapter({ caps, canvas, gl, size, onWarn });
+  return { texture, atlas, skeleton, renderer, caps };
+}

package/src/web/engine/adapters/renderer.js

@@ -0,0 +1,223 @@
+// adapters/renderer.js —— 渲染器适配（SceneRenderer / SkeletonRenderer + 相机 + 绘制）
+//
+// 差异点：
+//   · 3.x：`new SceneRenderer(canvas, gl)`，自带 camera，绘制走 drawSkeleton(skeleton, premultiplied)
+//   · 4.x：可能只有 `SkeletonRenderer(gl)`，相机要自己 `new OrthoCamera(w, h)`，绘制走 draw(skeleton)
+// 本适配器用能力矩阵选择，并在运行时校验方法引用（避免"方法存在但签名不同"）。
+
+/**
+ * @param {{caps: object, canvas: HTMLCanvasElement, gl: WebGLRenderingContext,
+ *          size: {w: number, h: number}, onWarn?: Function}} ctx
+ */
+export function createRendererAdapter({ caps, canvas, gl, size, onWarn }) {
+  const R = caps.renderer;
+
+  /** 建渲染器（同时给出相机） */
+  function create() {
+    if (R.kind === 'scene') return createScene();
+    if (R.kind === 'skeleton') return createSkeleton();
+    throw new Error('运行时既没有 SceneRenderer 也没有 SkeletonRenderer');
+  }
+
+  function createScene() {
+    // 3.x 需要 canvas；个别版本只要 gl —— 用构造参数个数探测，不看版本号
+    const renderer = R.sceneArity >= 2 ? new R.sceneCtor(canvas, gl) : new R.sceneCtor(gl);
+    const camera = renderer.camera || (R.orthoCtor ? new R.orthoCtor(size.w, size.h) : null);
+    if (!renderer.camera && camera) onWarn && onWarn('renderer：SceneRenderer 未自带相机，已改用 OrthoCamera');
+    return { renderer, camera, kind: 'scene' };
+  }
+
+  function createSkeleton() {
+    const renderer = new R.skeletonCtor(gl);
+    const camera = R.orthoCtor ? new R.orthoCtor(Math.max(1, size.w), Math.max(1, size.h)) : null;
+    if (!camera) onWarn && onWarn('renderer：没有 OrthoCamera，绘制可能不可见');
+    return { renderer, camera, kind: 'skeleton' };
+  }
+
+  /**
+   * 画一帧。
+   * @param {{renderer: object, kind: string}} target create() 的返回值
+   * @param {object} skeleton
+   * @param {boolean} premultiplied
+   */
+  function draw(target, skeleton, premultiplied) {
+    const r = target && target.renderer;
+    if (!r || !skeleton) return false;
+    try {
+      if (typeof r.begin === 'function') r.begin();
+      try {
+        if (typeof r.drawSkeleton === 'function') {
+          // 不要用 drawSkeleton.length 判断"接不接受第二个参数"——那是错的判据：
+          //   4.0 的签名是 `drawSkeleton(skeleton, premultipliedAlpha = false, slotRangeStart = -1, …)`，
+          //   第 2 个参数**带默认值** ⇒ Function.length 只数默认值之前的形参 ⇒ 结果是 1，
+          //   `length >= 2` 恒为假 ⇒ 永远走单参分支 ⇒ 从来不传 premultiplied。
+          // 后果在 spine-webgl-4.0 的 SceneRenderer.drawSkeleton 内部：
+          //   this.skeletonRenderer.premultipliedAlpha = premultipliedAlpha   ← 一直停在默认 false
+          // 而 `_SkeletonRenderer` 里这个字段同时决定两件事：
+          //   :10544  srcFunc = premultipliedAlpha ? gl.ONE : gl.SRC_ALPHA        ← blend 的 src 因子
+          //   :10809  if (premultipliedAlpha) { finalColor.r *= finalColor.a; … } ← 顶点色是否乘 alpha
+          // 于是 atlas 声明 pma:true 的模型（像素已预乘）变成"预乘纹理 + 非预乘公式"，
+          //   柔边被二次乘 alpha ⇒ 眼周/嘴周发暗。
+          // 老版本只有 1 个形参时，多传的那个参数会被 JS 忽略，所以统一传两个是安全的。
+          r.drawSkeleton(skeleton, premultiplied === true);
+        } else if (typeof r.draw === 'function') {
+          r.draw(skeleton);
+        } else {
+          onWarn && onWarn('renderer：既没有 drawSkeleton 也没有 draw，无法绘制');
+          return false;
+        }
+      } finally {
+        if (typeof r.end === 'function') r.end();
+      }
+      return true;
+    } catch (e) {
+      onWarn && onWarn(`renderer.draw 失败：${e.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * 取（或首次创建）调试渲染器。
+   * 优先用渲染器自带的 skeletonDebugRenderer；否则用能力矩阵探测到的构造器自己建一个。
+   * 为什么要缓存：调试渲染器持有 GPU 资源，每帧新建会持续泄漏。
+   * @param {{renderer: object, camera?: object}} target create() 的返回值
+   */
+  function ensureDebugRenderer(target) {
+    const r = target && target.renderer;
+    if (!r) return null;
+    if (r.skeletonDebugRenderer) return r.skeletonDebugRenderer;
+    if (target.debugRenderer !== undefined && target.debugRenderer !== null) return target.debugRenderer;
+    const Ctor = R.debugCtor;
+    if (!Ctor) return null;
+    try {
+      target.debugRenderer = new Ctor(gl);
+      return target.debugRenderer;
+    } catch (e) {
+      onWarn && onWarn(`调试渲染器创建失败：${e.message}`);
+      target.debugRenderer = null;
+      return null;
+    }
+  }
+
+  /**
+   * 八类开关 → SkeletonDebugRenderer 的 draw* 属性。
+   * 属性名按运行时实际存在才写（不同版本命名有差异），映射口径：
+   *   bones→drawBones  regions→drawRegionAttachments  boundingBoxes→drawBoundingBoxes
+   *   hulls→drawMeshHull  meshes→drawMeshTriangles  paths→drawPaths
+   *   points→drawPoints  clipping→drawClipping
+   * @param {object} dbg 调试渲染器
+   * @param {object} flags { bones, meshes, ... }
+   */
+  function applyDebugFlags(dbg, flags) {
+    if (!dbg) return [];
+    const f = flags || {};
+    const map = {
+      drawBones: f.bones,
+      drawRegionAttachments: f.regions,
+      drawBoundingBoxes: f.boundingBoxes,
+      drawMeshHull: f.hulls,
+      drawMeshTriangles: f.meshes,
+      drawPaths: f.paths,
+      drawPoints: f.points,
+      drawClipping: f.clipping,
+    };
+    const missing = [];
+    for (const [prop, on] of Object.entries(map)) {
+      // 属性不存在 = 该运行时的调试渲染器不支持这一类（例如 3.8/4.1 都没有 drawPoints），
+      //   记下来交给上层如实上报，而不是静默吞掉让"点了没反应"
+      if (prop in dbg) dbg[prop] = !!on;
+      else if (on) missing.push(prop);
+    }
+    return missing;
+  }
+
+  /**
+   * 调试绘制能力探测（确定性，不依赖"是否已经画过一帧"）。
+   * 为什么要它：面板要如实显示哪几类画不出来，若靠绘制时记录，暂停/未出帧时就会误报"都支持"。
+   * @param {object} target create() 的返回值
+   * @returns {{available: boolean, missing: string[]}} missing 为运行时没有对应属性的项
+   */
+  function debugSupport(target) {
+    const dbg = ensureDebugRenderer(target);
+    if (!dbg) return { available: false, missing: [] };
+    const props = ['drawBones', 'drawRegionAttachments', 'drawBoundingBoxes',
+      'drawMeshHull', 'drawMeshTriangles', 'drawPaths', 'drawPoints', 'drawClipping'];
+    return { available: true, missing: props.filter((p) => !(p in dbg)) };
+  }
+
+  /**
+   * 画一帧调试层。全关时不触碰 GL（避免"开关关了还在画"的假象）。
+   * @param {object} target create() 的返回值
+   * @param {object} skeleton
+   * @param {object} flags 八类开关
+   * @param {boolean} premultiplied 与主绘制同口径
+   * @returns {boolean} 是否真的画了
+   */
+  function drawDebug(target, skeleton, flags, premultiplied) {
+    const any = !!flags && Object.keys(flags).some((k) => flags[k]);
+    if (!any || !skeleton) return false;
+    const r = target && target.renderer;
+    if (!r) return false;
+    const dbg = ensureDebugRenderer(target);
+    if (!dbg) return false;
+    const missing = applyDebugFlags(dbg, flags);
+    if (missing.length) {
+      // 同一个缺失项只告警一次（每帧都刷会把日志冲爆）
+      target.debugMissing = missing;
+      if (!target.debugMissingWarned) {
+        target.debugMissingWarned = {};
+      }
+      for (const prop of missing) {
+        if (target.debugMissingWarned[prop]) continue;
+        target.debugMissingWarned[prop] = true;
+        onWarn && onWarn(`调试渲染器没有 ${prop}：该运行时画不出这一类调试绘制`);
+      }
+    }
+    try {
+      if (typeof r.begin === 'function') r.begin();
+      try {
+        if (typeof r.drawSkeletonDebug === 'function') {
+          // 渲染器自带调试绘制入口（3.x/4.x 都是这个名），二参是是否预乘
+          if (r.drawSkeletonDebug.length >= 2) r.drawSkeletonDebug(skeleton, premultiplied === true);
+          else r.drawSkeletonDebug(skeleton);
+        } else if (typeof dbg.draw === 'function') {
+          // 兜底：自己调调试渲染器的 draw，需要把相机的投影矩阵交给它
+          const cam = target.camera;
+          if (cam && cam.projection && 'projection' in dbg) dbg.projection = cam.projection;
+          dbg.draw(skeleton);
+        } else {
+          onWarn && onWarn('调试渲染器既无 drawSkeletonDebug 也无 draw，调试绘制不可用');
+          return false;
+        }
+      } finally {
+        if (typeof r.end === 'function') r.end();
+      }
+      return true;
+    } catch (e) {
+      onWarn && onWarn(`renderer.drawDebug 失败：${e.message}`);
+      return false;
+    }
+  }
+
+  /** 释放渲染器（有的版本没有 dispose） */
+  function dispose(target) {
+    const r = target && target.renderer;
+    const own = target && target.debugRenderer;
+    // 只释放自己建的（渲染器自带的 skeletonDebugRenderer 由渲染器自己回收）
+    if (own && own !== r && typeof own.dispose === 'function') {
+      try { own.dispose(); } catch { /* 忽略 */ }
+    }
+    if (target) target.debugRenderer = null;
+    if (r && typeof r.dispose === 'function') {
+      try { r.dispose(); } catch { /* 忽略 */ }
+    }
+  }
+
+  /** 相机视口跟随（缺 setViewport 时静默跳过） */
+  function syncViewport(camera, w, h) {
+    if (!camera || typeof camera.setViewport !== 'function') return false;
+    try { camera.setViewport(w, h); return true; } catch { return false; }
+  }
+
+  return { create, draw, drawDebug, debugSupport, dispose, syncViewport };
+}

package/src/web/engine/adapters/skeleton.js

@@ -0,0 +1,105 @@
+// adapters/skeleton.js —— 骨架数据与骨架操作适配
+//
+// 差异点：JSON/Binary 读取器、AttachmentLoader、以及 skeleton 的世界变换/包围盒方法；
+// 缺失的能力通过能力矩阵降级并 warn（不静默）。
+
+/**
+ * @param {{caps: object, spine: object, onWarn?: Function}} ctx
+ */
+export function createSkeletonAdapter({ caps, spine, onWarn }) {
+  /** 附件装载器（把图集区域绑到附件上） */
+  function attachmentLoader(atlas) {
+    const Ctor = caps.skeleton.attachmentLoaderCtor;
+    if (!Ctor) throw new Error('运行时缺少 AtlasAttachmentLoader');
+    return new Ctor(atlas);
+  }
+
+  /** 读二进制骨架 */
+  function readBinary(loader, bytes) {
+    const Ctor = caps.skeleton.binaryCtor;
+    if (!Ctor) throw new Error('运行时缺少 SkeletonBinary');
+    return new Ctor(loader).readSkeletonData(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+  }
+
+  /** 读 JSON 骨架 */
+  function readJson(loader, json) {
+    const Ctor = caps.skeleton.jsonCtor;
+    if (!Ctor) throw new Error('运行时缺少 SkeletonJson');
+    return new Ctor(loader).readSkeletonData(json);
+  }
+
+  /** 建骨架 + 动画状态机 */
+  function createRuntime(data) {
+    const skeleton = new spine.Skeleton(data);
+    const stateData = new spine.AnimationStateData(data);
+    const state = new spine.AnimationState(stateData);
+    return { skeleton, stateData, state };
+  }
+
+  /** 摆到 setup pose（fit 取包围盒前必须做） */
+  function setupPose(skeleton) {
+    try { if (caps.skeletonOps.setToSetupPose) skeleton.setToSetupPose(); } catch { /* 忽略 */ }
+  }
+
+  /** 更新世界变换（2 = 物理模式；缺能力时退回无参调用） */
+  function updateWorldTransform(skeleton) {
+    if (!skeleton || !caps.skeletonOps.updateWorldTransform) return;
+    try {
+      if (skeleton.updateWorldTransform.length >= 1) skeleton.updateWorldTransform(2);
+      else skeleton.updateWorldTransform();
+    } catch { /* 忽略 */ }
+  }
+
+  /** 取骨架包围盒（用运行时的 Vector2；缺能力返回 null） */
+  function bounds(skeleton) {
+    const V = caps.skeleton.vector2;
+    if (!skeleton || !caps.skeletonOps.getBounds || !V) return null;
+    try {
+      const offset = new V();
+      const size = new V();
+      skeleton.getBounds(offset, size, []);
+      const w = Number(size.x);
+      const h = Number(size.y);
+      if (!Number.isFinite(w) || !Number.isFinite(h) || w <= 0 || h <= 0) return null;
+      return { x: Number(offset.x) || 0, y: Number(offset.y) || 0, w, h };
+    } catch (e) {
+      onWarn && onWarn(`skeleton.bounds 失败：${e.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * 在"全部皮肤合并"的形态下取一次值，然后还原原皮肤与 setup pose。
+   * 为什么要合并：算 fit 包围盒前会把所有皮肤合成一个临时 skin，
+   *   否则只按默认皮肤测量，多皮肤模型的包围盒会偏小（实测 7 动作模型 reset 后 zoom 差 0.18%）。
+   * @param {object} ctx {skeleton, skeletonData}
+   * @param {Function} fn 测量回调
+   */
+  function withAllSkins({ skeleton, skeletonData }, fn) {
+    const Skin = caps.skinCtor;
+    const skins = (skeletonData && skeletonData.skins) || [];
+    if (!Skin || !skeleton || skins.length <= 1) return fn();
+    let prev = null;
+    try {
+      prev = skeleton.skin;
+      const merged = new Skin('_all_skins_bounds');
+      for (const sk of skins) {
+        try { merged.addSkin(sk); } catch { /* 单个皮肤合并不了不影响其它 */ }
+      }
+      skeleton.setSkin(merged);
+      setupPose(skeleton);
+      updateWorldTransform(skeleton);
+      return fn();
+    } catch {
+      return fn();
+    } finally {
+      try {
+        skeleton.setSkin(prev || null);
+        setupPose(skeleton);
+        updateWorldTransform(skeleton);
+      } catch { /* 还原失败不影响结果 */ }
+    }
+  }
+
+  return { attachmentLoader, readBinary, readJson, createRuntime, setupPose, updateWorldTransform, bounds, withAllSkins };
+}

package/src/web/engine/adapters/texture.js

@@ -0,0 +1,64 @@
+// adapters/texture.js —— 纹理适配（创建 / 占位 / 释放 / 上传绑定）
+//
+// 业务层只调这里，不直接 `new GLTexture(...)`：不同版本可能是 GLTexture 或 Texture，
+// 且有 bind()/setFilters() 与否的差异，全部收敛在本文件。
+
+/** 1×1 透明画布（占位纹理的像素源） */
+function blankCanvas() {
+  const c = document.createElement('canvas');
+  c.width = 1;
+  c.height = 1;
+  const ctx = c.getContext('2d');
+  if (ctx) ctx.clearRect(0, 0, 1, 1);
+  return c;
+}
+
+/**
+ * @param {{caps: object, gl: WebGLRenderingContext, onWarn?: Function}} ctx
+ */
+export function createTextureAdapter({ caps, gl, onWarn }) {
+  const Ctor = caps.texture.glTextureCtor || caps.texture.textureCtor;
+  if (!Ctor) onWarn && onWarn('texture：运行时没有 GLTexture/Texture，纹理将无法创建');
+
+  /** 由图片源创建纹理 */
+  function create(image, premultiplied) {
+    if (!Ctor) return null;
+    return new Ctor(gl, image, false, premultiplied === true);
+  }
+
+  /** 占位纹理（必须是与运行时同源的纹理对象：Spine 批处理器会对它调 bind） */
+  function placeholder() {
+    if (!Ctor) return null;
+    return new Ctor(gl, blankCanvas(), false, false);
+  }
+
+  /** 释放纹理（有 dispose 用 dispose，否则直接删 GL 纹理） */
+  function dispose(tex) {
+    if (!tex) return;
+    try {
+      if (caps.texture.hasDispose && typeof tex.dispose === 'function') { tex.dispose(); return; }
+      const handle = tex.glTexture || tex.texture;
+      if (handle && gl) gl.deleteTexture(handle);
+    } catch { /* 释放失败不影响后续 */ }
+  }
+
+  /** 显式绑定（批处理器内部也会绑；这里给"需要手动绑定"的路径用） */
+  function bind(tex) {
+    if (!tex || !gl) return false;
+    try {
+      if (caps.texture.hasBind && typeof tex.bind === 'function') { tex.bind(); return true; }
+      const handle = tex.glTexture || tex.texture;
+      if (!handle) {
+        onWarn && onWarn('texture.bind：纹理既没有 bind() 也没有 GL 句柄，已跳过绑定');
+        return false;
+      }
+      gl.bindTexture(gl.TEXTURE_2D, handle);
+      return true;
+    } catch (e) {
+      onWarn && onWarn(`texture.bind 失败：${e.message}`);
+      return false;
+    }
+  }
+
+  return { create, placeholder, dispose, bind, caps: caps.texture };
+}