modelstage 0.0.0-stage → 0.5.28

package/src/web/spine/canvas-pixels.js

@@ -0,0 +1,36 @@
+// spine/canvas-pixels.js —— 像素采样与画面签名
+//
+// 职责：从画布读回像素、算画面签名（自检/回归判据）。
+// 注意：preserveDrawingBuffer=false 时直接 readPixels 常读到全 0，判据用 ratio 而不是绝对值；
+//   另外「像素非空」不能证明画面可见（存活在游离画布上时照样有像素），可见性请用 DOM 关系判。
+
+const ALPHA_THRESHOLD = 8;
+
+/** 像素签名：对读回的缓冲做一次轻量哈希（验收用"两帧不同"判定，不做加密） */
+function pixelSignature(buf) {
+  let h = 2166136261;
+  for (let i = 0; i < buf.length; i += 97) { // 稀疏采样：覆盖全画面且够快
+    h ^= buf[i];
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h.toString(16);
+}
+
+/** 同帧采样：非透明像素占比（先渲染一帧再读，避免读到来不及呈现的缓冲） */
+export function samplePixels(st) {
+  const e = st.engine;
+  const gl = e && e.gl;
+  if (!gl) return { ratio: 0, w: 0, h: 0, reason: 'no-gl' };
+  try {
+    if (e.presentFirstFrame) e.presentFirstFrame();
+    const w = gl.drawingBufferWidth;
+    const h = gl.drawingBufferHeight;
+    const buf = new Uint8Array(w * h * 4);
+    gl.readPixels(0, 0, w, h, gl.RGBA, gl.UNSIGNED_BYTE, buf);
+    let n = 0;
+    for (let i = 3; i < buf.length; i += 4) if (buf[i] > ALPHA_THRESHOLD) n++;
+    return { ratio: +(n / (w * h)).toFixed(4), w, h, signature: pixelSignature(buf) };
+  } catch (err) {
+    return { ratio: 0, w: 0, h: 0, reason: String(err && err.message ? err.message : err) };
+  }
+}

package/src/web/spine/canvas-runtime.js

@@ -0,0 +1,127 @@
+// spine/canvas-runtime.js —— 运行时源码的获取与版本选择
+//
+// 职责：向服务端要运行时清单、按语义化版本挑一个、把源码文本缓存起来喂给引擎。
+// 为什么单独成模块：这段是唯一做网络请求与版本比较的地方，与舞台装配无关，
+//   混在 canvas.js 里时最长的那几个 try/catch 都在这里，出错排查面很窄。
+
+import { SpineEngine as NextEngine } from '../engine/index.js';
+// 清单读取走统一 HTTP 层（重试 + 统一超时/错误归类）
+import { getJson } from '../infra/api.js';
+// 缺运行时时的可读提示（含服务端给的落地目录绝对路径与可复制命令）
+import { loadRuntimeHint, spineMissingHint } from './runtime-hint.js';
+
+const RUNTIME_BASE = '/spine-runtimes/spine-webgl-';
+
+const RUNTIME_MANIFEST = '/spine-runtimes/index.json';
+
+const runtimeSourceCache = new Map(); // ver -> 源码文本
+
+let manifestPromise = null;
+
+let availableCache = null;
+
+/** '3.8.99' -> '3.8' */
+function majorMinor(v) {
+  const m = String(v || '').trim().match(/^(\d+)\.(\d+)/);
+  return m ? `${m[1]}.${m[2]}` : String(v || '');
+}
+
+/** 运行时目录清单（dev-server 扫目录生成；客户端不写死版本列表） */
+function fetchManifest() {
+  if (manifestPromise) return manifestPromise;
+  // 幂等 GET 的小 JSON ⇒ 走统一层（重试 + 统一超时/错误归类）。no-store 保留：新版本要立刻可见。
+  const p = getJson(RUNTIME_MANIFEST, { cache: 'no-store' })
+    .then((j) => (j && Array.isArray(j.versions) ? j.versions : []))
+    .catch(() => []);
+  manifestPromise = p;
+  p.then((list) => {
+    // 空结果多为"服务刚起/网络抖动"，缓存它会让后续加载永久拿不到版本 ⇒ 清掉待下次重试
+    if (!list.length && manifestPromise === p) manifestPromise = null;
+  });
+  return p;
+}
+
+/** 本机可用版本：直接采用 dev-server 扫目录生成的清单（不再逐版发 HEAD 探测，
+ *  避免并发探测请求在切换/卸载时被中断成 ERR_ABORTED）。 */
+export async function availableVersions() {
+  if (availableCache && availableCache.length) return availableCache;
+  let list = await fetchManifest();
+  // 服务刚起/抖动时清单可能一时为空：同一次加载内立即重试一次，避免把"瞬时失败"变成"这次一定失败"
+  if (!list.length) {
+    await new Promise((r) => setTimeout(r, 150));
+    list = await fetchManifest();
+  }
+  if (list.length) availableCache = list; // 只缓存非空结果
+  return list;
+}
+
+/**
+ * 本次装载的**运行时覆盖值**（来自 URL 的 ?runtime=）。
+ *
+ * 语义严格限定为"只生效一次"：
+ *   · 不落 localStorage / uiState —— 绝不记忆。自动选版本是**正确性保证**
+ *     （骨架 4.1.20 只能用 4.1 运行时），一旦记住人工覆盖，
+ *     下次打开不兼容的模型会莫名失败，且用户看不出是自己上次设的。
+ *   · 由 canvas-engine 在选版时 takeForcedRuntime() 取走并**立刻清空**，
+ *     所以"带参数装载成功后去掉参数刷新 ⇒ 回到自动"天然成立。
+ * @type {string|null}
+ */
+let forcedRuntime = null;
+
+/** 设置一次性覆盖值（传 null/'' 表示清除） */
+export function setForcedRuntime(version) {
+  forcedRuntime = version ? String(version) : null;
+}
+
+/** 取走覆盖值（取一次即清空，天然只生效一次） */
+export function takeForcedRuntime() {
+  const v = forcedRuntime;
+  forcedRuntime = null;
+  return v;
+}
+
+/** 精确命中优先，否则同 major 的最大 minor，最后退清单里最大的 */
+export function pickRuntimeVersion(version, available) {
+  const want = majorMinor(version);
+  if (!available.length) return want || null; // 清单不可用：有版本用版本，没版本交给调用方报错
+  if (!want) return available[available.length - 1]; // 模型缺版本号：用清单里最新的一档
+  if (available.includes(want)) return want;
+  const major = want.split('.')[0];
+  const same = available.filter((v) => v.split('.')[0] === major);
+  if (same.length) return same[same.length - 1];
+  return available[available.length - 1];
+}
+
+/** 取运行时源码文本并塞进 engine 的懒加载钩子（隔离执行由 engine 负责） */
+export async function ensureRuntimeSource(ver) {
+  window.__SPINE_SINGLE_FILE__ = true;
+  window.__SPINE_RUNTIME_SOURCES__ = window.__SPINE_RUNTIME_SOURCES__ || {};
+  if (window.__SPINE_RUNTIME_SOURCES__[ver]) return;
+  let text = runtimeSourceCache.get(ver);
+  if (!text) {
+    // 20s：运行时脚本实测 439KB（spine-webgl 4.1.0），CIFS/NAS 上读大文件可能数秒。
+    //   不给超时会让"装载模型"永久卡在"加载运行时"（用户看不出是卡住还是慢）。
+    let r;
+    try {
+      r = await fetch(`${RUNTIME_BASE}${ver}.js`, { cache: 'no-store', signal: AbortSignal.timeout(20000) });
+    } catch (e) {
+      // 超时/中断必须翻译成人话：裸的 "The operation was aborted." 分不清是
+      //   "这台机器没装这个版本"（要补文件）还是"服务端/磁盘慢"（等或换机器）—— 两者的处置完全不同。
+      throw new Error(`运行时 ${ver} 加载超时或中断（上限 20s）：${(e && e.message) || e}`);
+    }
+    if (!r.ok) {
+      // 404 最常见的原因是"这台机器上没放这个版本" ⇒ 附上服务端给的可复制补齐方案，
+      //   否则用户只看到一句 HTTP 404，不知道要下什么、放哪里（这条日志会进调试面板）。
+      const hint = await loadRuntimeHint();
+      throw new Error(spineMissingHint(ver, hint, r.status));
+    }
+    text = await r.text();
+    runtimeSourceCache.set(ver, text);
+  }
+  window.__SPINE_RUNTIME_SOURCES__[ver] = text;
+}
+
+/** 取引擎构造器：只有新引擎（可读实现）。旧脚本注入路径已随引擎重写收尾删除。 */
+export async function pickEngineCtor() {
+  return NextEngine;
+}

package/src/web/spine/canvas-view.js

@@ -0,0 +1,108 @@
+// spine/canvas-view.js —— 视口/相机/设置快照
+//
+// 职责：相机缩放与取景、设置默认值与回读、stats 快照的组装。
+// 为什么单独成模块：这些是「纯状态换算」，不碰引擎生命周期；拆开后 canvas.js 只留装配。
+// 注意：settings 快照是设置类 setter 的"回显权威"（getSetting 读它判成功），字段名不可改。
+
+/**
+ * 相机视图约定（交互层按此实现，勿改）：
+ *   · pan 单位 = 屏幕像素，原点 = 画布中心（即 fit 视图的中心），向右/向下为正；
+ *   · zoom = 相对 fit 的倍数，reset 后为 1.0，取值 0.2~8；
+ *   · 世界单位 ↔ 屏幕像素的换算只在本文件做：屏幕 = 世界差值 × base.zoom × zoom。
+ */
+
+/** 相机视图：缩放范围（相对 fit 的倍数）与取景基准缓存 */
+const VIEW_ZOOM_MIN = 0.2;
+
+const VIEW_ZOOM_MAX = 8;
+
+export const DEFAULT_SETTINGS = {
+  pma: 'auto', fit: 'subject', textureFilter: 'linear', speed: 1, loop: true, debug: null,
+  fpsLimit: 60, dprMode: 'auto', msaa: 'auto', filter: 'original',
+};
+
+/** 当前相机对象（部分运行时用 scale 而非 zoom） */
+function cameraOf(st) {
+  return st.engine && st.engine.camera ? st.engine.camera : null;
+}
+
+/** 读相机缩放（统一成"越大越放大"的 zoom 语义） */
+function cameraZoom(cam) {
+  if (!cam) return 1;
+  if (cam.zoom !== undefined) return cam.zoom;
+  if (cam.scale) return 1 / cam.scale;
+  return 1;
+}
+
+/** 写相机缩放（与 cameraZoom 的两种字段对应） */
+function setCameraZoom(cam, zoom) {
+  if (!cam) return;
+  if (cam.zoom !== undefined) cam.zoom = zoom;
+  else if (cam.scale !== undefined) cam.scale = 1 / zoom;
+}
+
+/**
+ * 取"fit 后的缩放"作为视图基准。
+ * 引擎的 baseZoom 就是 fit 结果；只有在拿不到时才退回当前相机 zoom。
+ * （曾经用"调用时的相机 zoom"当基准，导致 reset 之后基准被上一次的缩放污染）
+ */
+
+/**
+ * 记录视图基准：缩放基准取引擎的 userScale（引擎语义「越大越放大」），平移累计归零。
+ * 不在本文件推导相机字段——引擎的 camera.zoom 是 userScale 的倒数，自己算必错。
+ */
+export function captureViewBase(st) {
+  const engine = st.engine;
+  // 基准 = 当前 userScale（引擎的 getCameraZoom 是唯一真相；resetCamera 之后取一次即可）
+  st.viewBaseScale = engine && typeof engine.getCameraZoom === 'function' ? engine.getCameraZoom() : 1;
+  st.viewPan = { x: 0, y: 0 };
+}
+
+/**
+ * 标定「平移输入 1 像素 → 画面位移多少像素」。
+ * 为什么要标定：引擎 applyPan 内部有 `×2` 与 flip 系数，直接原样传会让拖动比手指快一倍多。
+ * 做法：applyPan(±1) 探测相机世界位移，再乘「每世界单位对应多少屏幕像素」，探测后立即复原（净位移 0）。
+ */
+
+/**
+ * 视图快照（对外单位约定）。
+ *   zoom = 相对 fit 的倍数：engine.getCameraZoom() / 基准 userScale；reset 后为 1；
+ *   panX/panY = **屏幕像素**，原点画布中心，向右/向下为正（累计值）。
+ */
+export function viewOf(st) {
+  const engine = st.engine;
+  const base = st.viewBaseScale || 1;
+  const cur = engine && typeof engine.getCameraZoom === 'function' ? engine.getCameraZoom() : base;
+  const pan = st.viewPan || { x: 0, y: 0 };
+  return {
+    zoom: +(cur / base).toFixed(4),
+    panX: +pan.x.toFixed(2),
+    panY: +pan.y.toFixed(2),
+    userScale: +cur.toFixed(6),
+    baseUserScale: +base.toFixed(6),
+    available: !!engine,
+  };
+}
+
+/** 只读统计（不暴露 engine 内部对象） */
+export function statsOf(st) {
+  const e = st.engine;
+  return {
+    model: st.model ? { name: st.model.name, version: st.model.version } : null,
+    runtimeVersion: e && e.getRuntimeVersion ? e.getRuntimeVersion() : null,
+    runtimeKeys: [...st.runtimeKeys],
+    contexts: e && e.gl ? 1 : 0,
+    frames: st.frames,
+    // 暂停状态（给外部读快照用：看门狗要判断"这段时间本来就不该有帧"）。
+    //   放这里而不是让调用方改用 debug()：stats() 每秒被看门狗调一次，
+    //   而 debug() 内部是 `{...statsOf(st), engine, tickCalls, paused}` —— 每秒多造一层对象纯属浪费。
+    paused: !!st.paused,
+    fps: e && e.getCurrentFps ? e.getCurrentFps() : null,
+    loads: st.loads,
+    disposes: st.disposes,
+    lastError: st.lastError,
+    animations: e && e.getAnimations ? e.getAnimations() : [],
+    settings: { ...st.settings },
+    view: viewOf(st),
+  };
+}

package/src/web/spine/canvas.js

@@ -0,0 +1,7 @@
+// spine/canvas.js —— 舞台的**唯一出口**（拆分后只做再导出）。
+//
+// 保留这个文件名是因为导入路径属于既有契约：调用方一律 `import { createSpineStage } from './spine/canvas.js'`。
+// 实现分在同目录 canvas-*.js（runtime / document / view / pixels / engine / api / api-groups / entry）。
+// 契约（渲染器契约 §2.1）：对外键一个不能少；setDebug 在设置组与渲染组各定义一次，
+//   后挂载者生效 —— 挂载顺序由 attachExtraApi 固定，勿调整。
+export { createSpineStage } from './canvas-entry.js';

package/src/web/spine/runtime-hint.js

@@ -0,0 +1,73 @@
+// spine/runtime-hint.js —— 把「缺运行时怎么补」拼成一句可读提示
+//
+// 为什么 hint 要从服务端拿：提示里最有用的那条是**落地目录的绝对路径**，
+//   而数据根（dataRoot）只有服务端知道 —— 前端自己拼只能写"某个目录"，用户还得猜。
+//   服务端在 GET /spine-runtimes/index.json 的 runtimeHint 字段里给出模板，前端只做版本号替换。
+//
+// 为什么单独一个模块：canvas-runtime.js 与 runtimes.js 两条加载路径都要用它，
+//   复制两份必然漂移（同一句话在两个文件里各说各话，是本项目反复栽过的坑）。
+import { getJson } from '../infra/api.js';
+
+/** hint 缓存（60s）：只在"加载失败"时才需要它，但失败可能连续发生，别每次都问服务端 */
+const CACHE_TTL_MS = 60000;
+let cache = null;   // { at:number, hint:object|null }
+
+/**
+ * 取服务端给的运行时提示模板（失败返回 null，绝不因此抛错）。
+ * @returns {Promise<object|null>}
+ */
+export async function loadRuntimeHint() {
+  if (cache && Date.now() - cache.at < CACHE_TTL_MS) return cache.hint;
+  let hint = null;
+  try {
+    const j = await getJson('/spine-runtimes/index.json', { cache: 'no-store' });
+    hint = (j && j.runtimeHint) || null;
+  } catch {
+    hint = null;   // 拿不到就退回"没有 hint"的降级文案
+  }
+  cache = { at: Date.now(), hint };
+  return hint;
+}
+
+/** 模板占位替换：服务端给的模板里用 {ver} 表示版本号 */
+function fill(tpl, ver) {
+  return String(tpl || '').split('{ver}').join(String(ver));
+}
+
+/** Spine 3.x 判断（3.x 官方没有 npm 包，只能给出 curl 自备的引导） */
+function isSpine3(ver) {
+  return String(ver || '').trim().startsWith('3.');
+}
+
+/**
+ * Spine 运行时缺失的可读提示。
+ * @param {string} ver 版本号（如 '4.1'）
+ * @param {object|null} hint 服务端给的模板
+ * @param {number|null} status HTTP 状态（拿得到就带上，方便判断是"没这个版本"还是"服务端没起来"）
+ * @returns {string}
+ */
+export function spineMissingHint(ver, hint, status) {
+  const h = hint || {};
+  const head = `运行时 ${ver} 加载失败${status ? `（HTTP ${status}）` : ''}。`;
+  if (isSpine3(ver)) {
+    const lines = [head, `缺少 Spine ${ver} 运行时。官方 npm 未发布 3.x（最早 4.0.1），只能自备：`];
+    if (h.spine3Curl) lines.push(`  ${fill(h.spine3Curl, ver)}`);
+    if (h.spine3Note) lines.push(`  （${h.spine3Note}）`);
+    return lines.join('\n');
+  }
+  const lines = [head, `缺少 Spine ${ver} 运行时。可执行：${fill(h.spineFetch || 'node tool/fetch-runtimes.mjs --spine {ver}', ver)}`];
+  if (h.spineTarget) lines.push(`  （或把 spine-webgl-${ver}.js 放到 ${fill(h.spineTarget, ver)}）`);
+  return lines.join('\n');
+}
+
+/**
+ * Live2D 运行时缺失的可读提示。
+ * `serverError` 是服务端 503/404 响应体里的 error 文本（已包含官网 URL 与目标目录）。
+ * @param {string} url 加载失败的脚本地址
+ * @param {string} [serverError]
+ * @returns {string}
+ */
+export function live2dMissingHint(url, serverError) {
+  const head = `Live2D 运行时加载失败：${url}`;
+  return serverError ? `${head}\n${serverError}` : head;
+}

package/src/web/spine/runtimes.js

@@ -0,0 +1,212 @@
+// ============================================================================
+// src/web/spine/runtimes.js —— Spine 运行时管理器（提供 `Is` 能力）
+//
+// 作用：把"按版本取运行时源码 → 隔离执行 → 交出该版本的 spine 命名空间"收敛到一处，
+//   引擎侧只需问它要某个版本，不关心源码从哪来、怎么执行。
+//
+// 为什么需要它：多版本共存要求每个版本的 `var spine` 不互相覆盖（详见下方"必须隔离执行"）。
+//
+// 关键点：**必须隔离执行**。每个 `spine-webgl-<ver>.js` 都是顶层 `var spine = …`；
+//   若用 `<script src>` 加载，后加载的会覆盖 `window.spine`，导致先加载版本的类在运行期
+//   解析到新版基类而崩（典型：`Class constructor Texture cannot be invoked without 'new'`）。
+//   用 `Function` 构造器执行源码时 `var spine` 成了**函数局部绑定**，
+//   各版本天然隔离（旧 app 的 `evalRuntimeIsolated` 也是这个原理）。
+// ============================================================================
+
+const RUNTIME_BASE = '/spine-runtimes/spine-webgl-';
+
+// 清单读取走统一 HTTP 层（重试 + 统一超时/错误归类）。api.js 顶层不引用 window/document，
+//   所以这个 import 在 node 侧被间接加载时也安全。
+import { getJson } from '../infra/api.js';
+// 缺运行时提示与 canvas-runtime 共用同一份（含服务端给的落地目录与可复制命令）
+import { loadRuntimeHint, spineMissingHint } from './runtime-hint.js';
+
+/** 运行时必须导出的类（缺任一即视为该版本不可用） */
+const REQUIRED_CLASSES = ['Skeleton', 'AnimationState', 'TextureAtlas', 'AtlasAttachmentLoader'];
+const REQUIRED_PARSERS = ['SkeletonJson', 'SkeletonBinary'];
+
+function majorMinor(v) {
+  const m = String(v || '').trim().match(/^(\d+)\.(\d+)/);
+  return m ? `${m[1]}.${m[2]}` : String(v || '');
+}
+
+/** 某个 spine 命名空间里取类：优先 webgl 子命名空间，其次根（两代布局不同） */
+function rtClass(rt, name) {
+  if (!rt) return null;
+  return (rt.webgl && rt.webgl[name]) || rt[name] || null;
+}
+
+/** 检查运行时是否完整（缺什么就报出来，便于定位） */
+function missingClasses(rt) {
+  const missing = [];
+  for (const n of REQUIRED_CLASSES) if (!rtClass(rt, n)) missing.push(n);
+  if (!REQUIRED_PARSERS.some((n) => rtClass(rt, n))) missing.push('SkeletonJson/SkeletonBinary');
+  if (!rtClass(rt, 'SceneRenderer') && !rtClass(rt, 'SkeletonRenderer')) missing.push('SceneRenderer/SkeletonRenderer');
+  if (!rtClass(rt, 'GLTexture')) missing.push('GLTexture');
+  if (!rtClass(rt, 'OrthoCamera') && !rtClass(rt, 'SceneRenderer')) missing.push('OrthoCamera');
+  return missing;
+}
+
+/** 运行时是否支持 straight alpha（4.1+ 的 SkeletonRenderer 有 premultipliedAlpha 字段） */
+function detectStraightAlpha(rt, version) {
+  // **判据：按运行时版本号 >= 4.1 判定**（判据原文 `parseFloat(T.version||"0")>=4.1`）。
+  // 为什么不用能力探测：spine 4.1 的 `SkeletonRenderer.premultipliedAlpha` 是**类字段（实例属性）**，
+  //   不在 prototype 上 ⇒ `'premultipliedAlpha' in SR.prototype` 恒为 false ⇒ 4.1 被误判"不支持直通"
+  //   ⇒ 面板显示"直通支持: 不支持"、`straight` 档被降级成 upload（同为 4.1 时本实现的判据更严格，会报不支持）。
+  //   实测：4.1 类定义 `SkeletonRenderer = class { premultipliedAlpha = false; … }`；3.8 段内无此字段。
+  const ver = Number(version);
+  if (Number.isFinite(ver)) return ver >= 4.1;
+  // 版本号拿不到时退回能力探测（旧行为）
+  const SR = rtClass(rt, 'SkeletonRenderer');
+  if (!SR || !SR.prototype) return false;
+  return 'premultipliedAlpha' in SR.prototype;
+}
+
+
+/**
+ * 在隔离作用域执行运行时源码，返回它自己的 spine 对象。
+ * 注意：这里不碰 window.spine —— 每个版本的 `var spine` 都在此函数体内，互不影响。
+ */
+function evalIsolated(source, version) {
+  let spineObj = null;
+  try {
+    spineObj = new Function(`${source}\n;return (typeof spine !== "undefined") ? spine : null;`)(); // dsh-skip-sensitive 运行时隔离执行本地可信源码（src/spine-runtimes/*.js），不接收任何外部输入
+  } catch (err) {
+    throw new Error(`Spine ${version} 运行时执行失败：${err && err.message ? err.message : err}`);
+  }
+  if (!spineObj || typeof spineObj !== 'object') {
+    throw new Error(`Spine ${version} 运行时执行后没有导出 spine 对象（源码形态不符）`);
+  }
+  const missing = missingClasses(spineObj);
+  if (missing.length) throw new Error(`Spine ${version} 运行时缺少核心类：${missing.join('、')}`);
+  return spineObj;
+}
+
+/** 运行时管理器（提供 getInstance / setLogCallback / getRuntimeWithFallback 三项能力） */
+export class SpineRuntimeManager {
+  static getInstance() {
+    if (!SpineRuntimeManager._inst) SpineRuntimeManager._inst = new SpineRuntimeManager();
+    return SpineRuntimeManager._inst;
+  }
+
+  constructor() {
+    this.cache = new Map();      // ver -> { version, spine, supportsStraightAlpha }
+    this.sources = new Map();    // ver -> 源码文本
+    this.loading = new Map();
+    this.logCallback = null;
+  }
+
+  setLogCallback(cb) { this.logCallback = typeof cb === 'function' ? cb : null; }
+
+  log(level, msg, scope) {
+    try { if (this.logCallback) this.logCallback(level, msg, scope || 'runtime'); } catch { /* 日志回调不得影响渲染 */ }
+  }
+
+  /** 版本规整：'3.8.99' -> '3.8' */
+  normalizeVersion(v) { return majorMinor(v); }
+
+  isLoaded(version) { return this.cache.has(this.normalizeVersion(version)); }
+
+  getCachedVersions() { return [...this.cache.keys()]; }
+
+  /** 可用版本：优先用页面注入的源码表，否则按 URL 探测 */
+  async listVersions() {
+    const fromSources = Object.keys(window.__SPINE_RUNTIME_SOURCES__ || {});
+    if (fromSources.length) return fromSources.sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+    try {
+      // 幂等 GET 的小 JSON 清单 ⇒ 走统一层（重试 + 统一超时 + 错误归类）。
+      //   no-store 必须保留：换了运行时版本要立刻看到新清单。
+      const j = await getJson('/spine-runtimes/index.json', { cache: 'no-store' });
+      if (j && Array.isArray(j.versions) && j.versions.length) return j.versions;
+    } catch { /* 清单取不到就走空表 */ }
+    return [];
+  }
+
+  /** 取某版源码文本（页面已注入则直接用；否则 fetch 一次并缓存） */
+  async sourceOf(version) {
+    const injected = (window.__SPINE_RUNTIME_SOURCES__ || {})[version];
+    if (injected) return injected;
+    if (this.sources.has(version)) return this.sources.get(version);
+    // 20s：与 canvas-runtime 同口径（运行时脚本实测 439KB），别让"加载运行时"无限挂着
+    let r;
+    try {
+      r = await fetch(`${RUNTIME_BASE}${version}.js`, { cache: 'no-store', signal: AbortSignal.timeout(20000) });  // dsh-skip-quality 本地同源运行时脚本读取，既有代码
+    } catch (e) {
+      // 同 canvas-runtime：把裸的 abort 翻成"超时/中断"，否则与"没装这个版本"混为一谈
+      throw new Error(`运行时 ${version} 加载超时或中断（上限 20s）：${(e && e.message) || e}`);
+    }
+    if (!r.ok) {
+      // 与 canvas-runtime 同一条提示口径（共用一个模块，别各写一份）：
+      //   404 时把"下哪个版本 / 放到哪个绝对路径 / 可复制的命令"一起给出来
+      const hint = await loadRuntimeHint();
+      throw new Error(spineMissingHint(version, hint, r.status));
+    }
+    const text = await r.text();
+    this.sources.set(version, text);
+    return text;
+  }
+
+  /** 取运行时（缓存；并发去重） */
+  async getRuntime(version) {
+    const ver = this.normalizeVersion(version);
+    if (this.cache.has(ver)) return this.cache.get(ver);
+    if (this.loading.has(ver)) return this.loading.get(ver);
+    const p = (async () => {
+      const src = await this.sourceOf(ver);
+      const spine = evalIsolated(src, ver);
+      const entry = { version: ver, spine, supportsStraightAlpha: detectStraightAlpha(spine, ver) };
+      this.cache.set(ver, entry);
+      this.loading.delete(ver);
+      this.log('info', `Spine ${ver} 运行时已就绪`, 'runtime');
+      return entry;
+    })().catch((err) => {
+      this.loading.delete(ver);
+      this.log('error', `加载 Spine ${ver} 运行时失败：${err.message}`, 'runtime');
+      throw err;
+    });
+    this.loading.set(ver, p);
+    return p;
+  }
+
+  /** 取运行时，失败时按"同 major 相邻 → 清单最大"降级 */
+  async getRuntimeWithFallback(version) {
+    const want = this.normalizeVersion(version);
+    try { return await this.getRuntime(want); } catch { /* 继续降级 */ }
+    const list = await this.listVersions();
+    const major = want.split('.')[0];
+    const same = list.filter((v) => v.split('.')[0] === major && v !== want);
+    const candidates = [...same, ...list.filter((v) => v !== want && v.split('.')[0] !== major).reverse()];
+    for (const v of candidates) {
+      try {
+        const entry = await this.getRuntime(v);
+        this.log('warn', `Spine ${want} 不可用，已降级到 ${v}`, 'runtime');
+        return entry;
+      } catch { /* 试下一个 */ }
+    }
+    throw new Error(`无法加载 Spine ${want} 运行时（清单：${list.join('、') || '空'}）`);
+  }
+}
+
+/**
+ * 打包器的 class-field 助手（engine 切片里 88 处调用它，但切片没带这个定义）。
+ * 语义：把 value 定义到 obj[key] 上并返回 value；键已存在时用 defineProperty 覆盖，
+ * 避免继承来的只读属性导致赋值失败（esbuild/tsc 的等价实现）。
+ */
+function defineField(obj, key, value) {
+  if (key in obj) {
+    Object.defineProperty(obj, key, { value, enumerable: true, configurable: true, writable: true });
+  } else {
+    obj[key] = value;
+  }
+  return value;
+}
+/**
+ * 安装到全局：引擎取某个版本的运行时源码时经它取实例，
+ * 所以必须在装载模型**之前**调用。
+ */
+export function installRuntimeManager() {
+  if (!window.de) window.de = defineField; // engine 切片依赖的 class-field 助手
+  if (window.Is) return window.Is;
+  window.Is = SpineRuntimeManager;
+  return window.Is;
+}