modelstage 0.0.0-stage → 0.5.28

package/src/web/spine/canvas-api-groups.js

@@ -0,0 +1,267 @@
+// spine/canvas-api-groups.js —— 各能力组的具体挂载
+//
+// 四个组：设置（fps/dpr/纹理过滤/PMA/调试绘制）→ 资产（皮肤/混合模式/部件筛除）→
+//   视图（相机与取景）→ 渲染（动作/播放/抗锯齿重建）。
+// 红线：组内 setDebug 会被渲染组覆盖，两组必须在同一模块内且按此顺序装配。
+
+import { buildDocument } from '../infra/document.js';
+import { createStageCamera } from '../render/camera/spine.js';
+import { applySettings, ensureStageEngine, ensureStageEngineWith, loadIntoStage } from './canvas-engine.js';
+import { pickEngineCtor } from './canvas-runtime.js';
+import { captureViewBase, viewOf } from './canvas-view.js';
+
+/** 通用 setter（fit/纹理过滤/速度/循环/调试/帧率/DPR）与 PMA 四档 */
+export function attachSettingSetters(api, st) {
+
+// PMA 不走通用 setter：切它必须重传贴图，单列一个方法（见下）
+for (const key of ['fit', 'textureFilter', 'speed', 'loop', 'debug', 'fpsLimit', 'dprMode']) {
+  api[`set${key[0].toUpperCase()}${key.slice(1)}`] = (v) => applySettings(
+    st, { [key]: key === 'fpsLimit' ? Number(v) : v },
+  );
+}
+/**
+ * 切换 PMA 模式：true=预乘、false=直通。
+ * 为什么单列：引擎没有 setPmaMode，切预乘必须重建贴图纹理（rebuildTextures）。
+ */
+/**
+ * 切换 PMA 模式（auto / premultiplied / straight / upload 四档）。
+ * 四档都会重传贴图：auto 需要重新采样像素判断，其余三档要按新口径重上传。
+ * @param {string} mode
+ */
+/**
+ * 组装 Document（Assets 层入口，测试/工具用）。
+ * 产品路径由 app/model-actions 组装；舞台只消费 ready 的 Document，绝不自己取资源。
+ * @param {object} entry catalog 条目（含 kind / rootId / entry.url 等）
+ * @returns {Promise<object>} Document（state 可能是 'error'，调用方自行判断）
+ */
+api.buildDocument = (entry) => buildDocument(entry || {});
+
+api.setPma = async (mode) => {
+  const m = ['auto', 'premultiplied', 'straight', 'upload'].includes(mode) ? mode : 'auto';
+  const prev = (st.settings && st.settings.pma) || 'auto';
+  applySettings(st, { pma: m });
+  const eng = st.engine;
+  if (!eng || typeof eng.rebuildTextures !== 'function') return m;
+  // 必须 await：rebuildTextures 是异步的（要重新解包贴图 + 重建骨架），
+  //   不 await 会让"同步 try/catch"抓不到失败，UI 以为切换成功而实际没生效。
+  let ok = false;
+  try {
+    ok = await eng.rebuildTextures(m);
+  } catch (e) {
+    try { eng.log('error', `PMA 切换异常: ${e && e.message ? e.message : e}`, 'pma'); } catch { /* 忽略 */ }
+    ok = false;
+  }
+  if (ok) return m;
+  // 失败如实反映：把档位回滚为上一档，面板/持久化读到的就是"实际生效值"
+  applySettings(st, { pma: prev });
+  try { eng.log('warn', `PMA 切换失败（${m}），已回滚为 ${prev}`, 'pma'); } catch { /* 忽略 */ }
+  return prev;
+};
+
+/**
+ * 调试绘制开关（8 个独立项，可同时开）。
+ * 每次只传变化的键，引擎内部会合并；状态同步记到 settings.debug 便于断言。
+ * @param {object} patch 形如 { bones: true, meshes: false }
+ */
+}
+
+/** 资产相关：皮肤列表与切换、混合模式、部件筛除 */
+export function attachAssetApi(api, st) {
+/** 当前模型的皮肤名列表（无皮肤时返回 [default]） */
+api.getSkins = () => {
+  if (!st.engine || typeof st.engine.getSkins !== 'function') return ['default'];
+  try {
+    const list = st.engine.getSkins() || [];
+    return list.length ? list : ['default'];
+  } catch {
+    return ['default'];
+  }
+};
+
+/**
+ * 当前**实际生效**的皮肤名（引擎侧记账，装载时自动选中的那个也在内）。
+ *
+ * 为什么需要它：面板刷新时若拿"皮肤列表里有没有 default"去猜当前项，会把
+ *   "自动选中了具名皮肤"的资源显示成 default —— 设置里写 A、画面是 B，排查时会被这条假信息带偏。
+ * 返回 null 表示引擎还没设过皮肤（调用方自行决定回落成什么）。
+ * @returns {string|null}
+ */
+api.getActiveSkin = () => {
+  if (!st.engine) return null;
+  const list = st.engine.activeSkins;
+  return Array.isArray(list) && list.length ? list[0] : null;
+};
+
+/**
+ * 切换皮肤（引擎按名称匹配；找不到时保持原皮肤）。
+ * 成功与否必须取引擎返回值：否则面板会记下一个并不存在的皮肤名，
+ *   表现为"设置里显示 skin_X、画面还是 default"，且下次重建贴图时又按错名字去设一遍。
+ * @param {string} name
+ * @returns {boolean} 是否真的切过去了
+ */
+api.setSkin = (name) => {
+  if (!st.engine || typeof st.engine.setSkins !== 'function') return false;
+  try {
+    const ok = st.engine.setSkins([name]) !== false;
+    if (ok) st.settings.skin = name;
+    return ok;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * 动作清单（名称 + 时长）：时长来自 skeletonData.animations 的 duration。
+ * 面板与底栏都读这一份，避免"两处各取一处"导致条数/时长不一致。
+ * @returns {Array<{name: string, duration: number|null}>}
+ */
+api.animationDetails = () => {
+  try {
+    const e = st.engine; // 与同一 api 里其它方法一致：引擎挂在 st 上
+    const anims = (e && e.skeletonData && e.skeletonData.animations) || [];
+    return anims.map((a) => {
+      const d = Number(a && a.duration);
+      return { name: String(a && a.name || ''), duration: Number.isFinite(d) && d > 0 ? d : null };
+    }).filter((a) => a.name);
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * 动画切换的交叉淡化时长（秒）：混合模式开 = 用它，关 = 0（硬切）。
+ * 提成命名常量：这个值同时被「混合模式开关」与「换肤临时套用」用到，
+ *   散落的裸 0.2 一旦改一处忘另一处，动作过渡与换肤过渡就会不一致。
+ */
+const MIX_TIME_CROSSFADE_SEC = 0.2;
+
+api.setMixMode = (on) => api.setMixTime(on ? MIX_TIME_CROSSFADE_SEC : 0);
+
+/**
+ * 混合时长（秒）：0 表示**不混合**（硬切），>0 表示动作/皮肤切换时的交叉淡化秒数。
+ * 面板的「混合时长」滑块走这里；原来的「混合模式」开关等价于 setMixMode(0|默认值)。
+ * @param {number} t 0~1 秒
+ * @returns {number} 生效值
+ */
+api.setMixTime = (t) => {
+  // 范围夹到 0~1：与面板滑块一致，避免外部传入巨大值把过渡拖成几秒
+  const v = Math.max(0, Math.min(1, Number(t) || 0));
+  st.settings.mixTime = v;
+  if (st.engine && typeof st.engine.setMixTime === 'function') {
+    try { st.engine.setMixTime(v); } catch { /* 版本不支持则只记状态 */ }
+  }
+  return v;
+};
+
+
+}
+
+/** 相机视图入口：只读读数 + 薄转发（不换算） */
+export function attachViewApi(api, st) {
+/** 相机统一入口（全部委托引擎原生方法，本文件不做任何坐标换算） */
+st.camera = createStageCamera({ getEngine: () => st.engine });
+api.camera = st.camera;
+
+/** 只读视图读数：zoom 取引擎 userScale 与基准的比值，pan 用入口累计的屏幕位移 */
+api.getView = () => viewOf(st);
+
+/**
+ * 兼容入口（交互层仍调用 setView）。这里**只转发**，不换算：
+ *   · zoom → camera.zoomTo(基准 × 倍数)（倍乘即「相对 fit 的倍数」，clamp 由引擎负责）
+ *   · panX/panY → camera.panBy(增量)，单位是屏幕像素，
+ */
+api.setView = (patch = {}) => {
+  const camera = st.camera;
+  if (!camera) return viewOf(st);
+  if (typeof patch.zoom === 'number' && Number.isFinite(patch.zoom)) {
+    const base = st.viewBaseScale || 1;
+    camera.zoomTo(base * patch.zoom);
+  }
+  if (typeof patch.panX === 'number' || typeof patch.panY === 'number') {
+    const cur = st.viewPan || { x: 0, y: 0 };
+    const nx = typeof patch.panX === 'number' && Number.isFinite(patch.panX) ? patch.panX : cur.x;
+    const ny = typeof patch.panY === 'number' && Number.isFinite(patch.panY) ? patch.panY : cur.y;
+    if (nx !== cur.x || ny !== cur.y) {
+      camera.panBy(nx - cur.x, ny - cur.y);
+      st.viewPan = { x: nx, y: ny };
+    }
+  }
+  return viewOf(st);
+};
+
+/** 视图复位：交给引擎 resetCamera 重新 fit，然后重取基准 */
+  /**
+   * 幂等入口：确保引擎实例已创建（只建上下文与相机，不加载模型）。
+   * 谁需要：Live2D 分支要接管引擎的 Live2D 态（l2dActive 依赖 l2dModelId + 引擎实例），
+   *   而引擎是懒创建的 —— 用户先点 Live2D 时还没有实例。
+   * @returns {Promise<object|null>} 引擎实例
+   */
+  api.ensureEngineReady = async () => {
+    if (st.engine) return st.engine;
+    try {
+      const Engine = await pickEngineCtor();
+      if (!ensureStageEngine(st, Engine, st.canvas)) return null;
+      return st.engine;
+    } catch {
+      return null;
+    }
+  };
+
+api.resetView = () => {
+  if (st.camera) st.camera.reset();
+  captureViewBase(st);
+  return viewOf(st);
+};
+}
+
+/** 渲染相关：调试绘制、滤镜预设、MSAA 重建 */
+export function attachRenderApi(api, st) {
+api.setDebug = (patch) => {
+  const next = { ...(st.settings.debug || {}), ...(patch || {}) };
+  st.settings.debug = next;
+  if (st.engine && typeof st.engine.setDebugDraw === 'function') {
+    try { st.engine.setDebugDraw(patch || {}); } catch { /* 版本不支持则只记状态 */ }
+  }
+  return next;
+};
+
+/** 切换滤镜预设（id 见引擎预设表；未知 id 由引擎回落原画） */
+api.setFilter = (id) => {
+  if (!st.engine || typeof st.engine.setFilter !== 'function') {
+    // 与 applySettings 同一约定：引擎还没建时也要把设置记进快照，
+    //   装载时由引擎按 settings.filter 应用 —— 否则启动阶段下发会静默丢失
+    st.settings.filter = id;
+    return id;
+  }
+  try {
+    st.engine.setFilter(id);
+    st.settings.filter = st.engine.getFilter ? st.engine.getFilter() : id;
+    return st.settings.filter;
+  } catch { return null; }
+};
+
+/**
+ * 切换 MSAA：GL 的 antialias 只在建上下文时生效，必须换 canvas 节点重建。
+ * 流程：换节点 → dispose → init(antialias) → 重新加载最近一次的模型。
+ * @param {boolean} on
+ * @returns {Promise<{antialias:boolean, restoreMs:number, restored:boolean}>}
+ */
+api.rebuildWithAntialias = async (on) => {
+  const arg = st.lastArg;
+  const old = st.canvas;
+  const next = old.cloneNode(false);
+  old.replaceWith(next);
+  st.canvas = next;
+  try { if (st.engine && st.engine.dispose) st.engine.dispose(); } catch { /* 释放失败继续重建 */ }
+  st.engine = null;
+  st.model = null;
+  st.disposes += 1; // 重建也计入释放次数，便于用 loads/disposes 判泄漏
+  st.settings.msaa = on ? 'auto' : 'off';
+  const t0 = performance.now();
+  const Engine = await pickEngineCtor();
+  const ok = ensureStageEngineWith(st, Engine, on);
+  if (!ok) return { antialias: !!on, restoreMs: 0, restored: false };
+  if (arg) await loadIntoStage(st, arg);
+  return { antialias: !!on, restoreMs: Math.round(performance.now() - t0), restored: !!arg };
+};
+}

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

@@ -0,0 +1,97 @@
+// spine/canvas-api.js —— 对外 31 键契约的装配入口
+//
+// 职责：buildStageApi 组装核心键（load/unload/stats/samplePixels/...），
+//   attachExtraApi 按固定顺序挂上四组能力（设置 → 资产 → 视图 → 渲染）。
+// 红线：挂载顺序即语义 —— 设置组与渲染组各定义一次 setDebug，后挂的覆盖前者；
+//   调换顺序会让调试绘制静默变样（渲染器契约 §2.1）。
+
+import { attachAssetApi, attachRenderApi, attachSettingSetters, attachViewApi } from './canvas-api-groups.js';
+import { abortedError } from './canvas-document.js';
+import { applySettings, loadIntoStage, unloadModel , startFrameTick, stopFrameTick, repaintOnce } from './canvas-engine.js';
+import { samplePixels } from './canvas-pixels.js';
+import { statsOf } from './canvas-view.js';
+
+/**
+ * 创建舞台（对外契约见 docs/参考/渲染与纹理.md §14）。
+ * @param {{canvas: HTMLCanvasElement, onStatus?: (s:object)=>void}} opts
+ */
+/**
+ * 组装舞台对外 API 的"基础方法"（加载/释放/统计/采样/播放控制）。
+ * 拆出来是为了让 createSpineStage 只做编排（单函数过长会被审计拦截）。
+ * @param {object} st 舞台状态
+ * @param {{status: Function, fail: Function}} ctx 状态回调与失败包装
+ */
+export function buildStageApi(st, ctx) {
+  const { status, fail } = ctx;
+const api = {
+  async load(arg) {
+    try {
+      const info = await loadIntoStage(st, arg);
+      // 被取代时 loadIntoStage 返回 null：必须显式抛 aborted，不能"静默成功"让调用方读到空结果
+      if (!info) throw abortedError();
+      status({ phase: 'ready', ...info });
+      return info;
+    } catch (err) {
+      if (err && err.business) {
+        // 业务错误也要落到状态里（页面提示与遥测都靠 lastError）
+        st.lastError = String(err.message || err);
+        status({ phase: 'error', error: st.lastError });
+        throw err;
+      }
+      if (err && err.name === 'AbortError') { st.lastError = '加载已被新的选择取代'; throw abortedError(st.lastError, err); }
+      throw fail(`加载失败：${err && err.message ? err.message : err}`, err);
+    }
+  },
+  unload() { unloadModel(st); status({ phase: 'unload' }); },
+  stats: () => statsOf(st),
+  samplePixels: () => samplePixels(st),
+  applySettings: (patch) => applySettings(st, patch),
+  play() {
+    if (st.engine && st.engine.start) { try { st.engine.start(); } catch { /* 已在播放 */ } }
+    st.paused = false;      // 恢复：重启帧计数循环（单实例由 startFrameTick 保证）
+    startFrameTick(st);
+  },
+  pause() {
+    if (st.engine && st.engine.stop) { try { st.engine.stop(); } catch { /* 已暂停 */ } }
+    st.paused = true;       // 暂停：停掉帧计数循环，避免空转重绘同一张静止画面
+    stopFrameTick(st);
+    repaintOnce(st);        // 停循环前补一帧，保证"按下瞬间"的画面是最新的
+  },
+  repaint: () => repaintOnce(st),
+  seek(t) { if (st.engine && st.engine.seek) { try { st.engine.seek(t); } catch { /* 越界忽略 */ } } },
+  setAnimation(name, loop) {
+    if (!st.engine || !name) return false;
+    try { st.engine.setAnimation(name, typeof loop === 'boolean' ? loop : st.settings.loop); return true; } catch { return false; }
+  },
+  resize() {
+    if (!st.engine) return;
+    try { if (st.engine.refreshResolution) st.engine.refreshResolution(); } catch { /* 忽略 */ }
+    try { if (st.engine.resetCamera) st.engine.resetCamera(); } catch { /* 忽略 */ }
+  },
+  dispose() {
+    const e = st.engine;
+    st.engine = null; st.model = null; st.seq++;
+    if (!e) return;
+    try { if (e.dispose) e.dispose(); } catch { /* 忽略 */ }
+    st.disposes++;
+  },
+  // debug 同时给出统计字段（验收脚本从 debug() 读 frames 等）
+  debug: () => ({ ...statsOf(st), engine: st.engine, tickCalls: st.tickCalls || 0, paused: !!st.paused }),
+};
+  return api;
+}
+
+/**
+ * 给舞台 API 挂"可选能力"：PMA 四档、滤镜、皮肤、混合模式、调试绘制、MSAA 重建。
+ * 这些方法依赖模块级工具（applySettings / loadIntoStage…），与工厂解耦。
+ */
+/**
+ * 给舞台 API 挂"可选能力"。按职责拆成四段，便于维护与审计（单函数长度）。
+ * 依赖模块级工具（applySettings / loadIntoStage…），与工厂解耦。
+ */
+export function attachExtraApi(api, st) {
+  attachSettingSetters(api, st);
+  attachAssetApi(api, st);
+  attachViewApi(api, st);
+  attachRenderApi(api, st);
+}

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

@@ -0,0 +1,80 @@
+// spine/canvas-document.js —— Document → 舞台描述符
+//
+// 职责：把（已就绪的）Document 翻成引擎能直接吃的描述符，并区分两类失败：
+//   aborted（用户切换导致的中止，属正常）与 business（真实失败，要显示给用户）。
+// 契约：Document 是渲染层唯一输入，这里不做资源抓取，只读已经解析好的地址。
+
+import { buildDocument } from '../infra/document.js';
+
+/**
+ * 被取代的装载错误：业务错误 + aborted 标记。
+ * 为什么单列：调用方必须能区分"装载失败"与"被更新的选择取代"——后者是正常竞态结果，
+ *   不该显示成红色故障，也不该被当成"成功"继续读结果字段（曾经因此抛 TypeError 留下空白画面）。
+ */
+export function abortedError(msg = '加载已被新的选择取代', cause) {
+  const e = businessError(msg, cause);
+  e.aborted = true;
+  return e;
+}
+
+/** 业务错误：调用方只更新提示，不抛控制台 */
+export function businessError(msg, cause) {
+  const e = new Error(msg);
+  e.business = true;
+  if (cause) e.cause = cause;
+  return e;
+}
+
+// 说明：模型资源（骨架 / atlas / 贴图）的**取用已上移到 infra/document.js**（Assets 层），
+//   本文件只消费 Document 给出的地址与字节 —— 渲染器里不再有 fetch / XHR 取模型资源，
+//   因此也不会有"取资源失败"分支（契约 渲染器契约 §五-6、Document 契约 D4）。
+//   运行时库（/spine-runtimes/*）仍在这里加载：那是**库**不是模型资产，属已批准的豁免项。
+
+/**
+ * 取出 ready 的 Document（舞台入参的唯一形态）。
+ * 只认 { document }：非 Document 直接抛，ready 之外（error）也抛并留痕。
+ *   组装是调用方的事（api.buildDocument 或 app/model-actions），舞台不代劳。
+ * @param {object} st 舞台状态
+ * @param {object} arg 只接受 { document }
+ * @returns {object} ready 的 Document
+ */
+export function resolveDocument(st, arg) {
+  // **只接受 Document**，不做旧形状（catalog entry）的兜底组装：
+  //   兜底留着，调用方忘了组装就会静默走它，而"组装失败"这条路径永远没人覆盖。
+  //   组装入口是 api.buildDocument（Assets 层 infra/document.js），调用方显式两步走。
+  const doc = arg && arg.document;
+  if (!doc || typeof doc.state !== 'string') {
+    // 旧形状（{ root, model }）要点名，否则调用方只看到 undefined 不知错在哪
+    const got = arg && arg.model
+      ? `旧形状 { root, model }（kind=${(arg.model.kind) || '?'}）`
+      : (doc && typeof doc === 'object' ? `普通对象（kind=${doc.kind || '?'}）` : String(doc));
+    throw businessError(`stage.load 只接受 Document（请先 buildDocument 组装），收到：${got}`);
+  }
+  if (doc.state !== 'ready') {
+    const why = (doc.warnings || []).join('；') || '未提供原因';
+    st.lastError = why;   // 组装失败要留痕：下一次成功装载会清掉它
+    throw businessError(`Document 不是 ready 状态（${doc.state}）：${why}`);
+  }
+  return doc;
+}
+
+/**
+ * engine 的模型描述符（字段名是 engine 的契约，见文档 §14）。
+ * 数据全部来自 **Document.assets**（地址已由 Assets 层经 VirtualFS 解析、字节也由那一层取好）。
+ * @param {object} doc ready 的 Document
+ * @param {string} ver 运行时版本
+ */
+export function buildDescriptor(doc, ver) {
+  const assets = (doc && doc.assets) || {};
+  const entry = assets.entry || {};
+  const atlas = assets.atlas || {};
+  const textures = Array.isArray(assets.textures) ? assets.textures : [];
+  return {
+    name: (doc && (doc.name || doc.id)) || '',
+    version: ver,
+    skeletonFile: { name: entry.name || '', content: entry.bytes },
+    atlasFile: { name: atlas.name || '', content: atlas.bytes },
+    textureFiles: textures.map((t) => ({ name: t.name || '', content: t.bytes })),
+    atlasPma: doc && doc.meta && doc.meta.extras ? doc.meta.extras.atlasPma : null,
+  };
+}

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

@@ -0,0 +1,193 @@
+// spine/canvas-engine.js —— 引擎生命周期与装载流程
+//
+// 职责：建引擎（含抗锯齿重建）、装载骨架、启动/停止播放循环、卸载模型。
+// 为什么单独成模块：这里是唯一持有/销毁 WebGL 上下文的地方（契约 §五-7 的落点），
+//   卸载语义（unload 保留引擎 / dispose 销毁引擎）必须能在一屏内读完。
+
+import { installRuntimeManager } from './runtimes.js';
+import { abortedError, buildDescriptor, businessError, resolveDocument } from './canvas-document.js';
+import { availableVersions, ensureRuntimeSource, pickEngineCtor, pickRuntimeVersion, takeForcedRuntime } from './canvas-runtime.js';
+// 缺运行时时的可读提示（含服务端给的落地目录绝对路径与可复制命令）
+import { loadRuntimeHint, spineMissingHint } from './runtime-hint.js';
+import { captureViewBase } from './canvas-view.js';
+
+/** 应用设置（全部走 engine 的 setter，缺哪个就跳过哪个） */
+export function applySettings(st, patch) {
+  if (patch && typeof patch === 'object') Object.assign(st.settings, patch);
+  const e = st.engine;
+  if (!e) return;
+  const s = st.settings;
+  const call = (fn, ...args) => { try { if (typeof fn === 'function') fn.apply(e, args); } catch { /* 版本不支持则跳过 */ } };
+  if (s.fit) call(e.setFitMode, s.fit);
+  if (s.textureFilter) call(e.setTextureFilter, s.textureFilter);
+  if (typeof s.fpsLimit === 'number') call(e.setFpsLimit, s.fpsLimit);
+  if (s.dprMode !== undefined && s.dprMode !== null) call(e.setDprMode, s.dprMode);
+  if (typeof s.speed === 'number') call(e.setSpeed, s.speed);
+  if (typeof s.loop === 'boolean') call(e.setLoop, s.loop);
+  if (s.debug) call(e.setDebugDraw, s.debug);
+}
+
+/** 释放当前模型（保留 engine 实例） */
+export function unloadModel(st) {
+  const e = st.engine;
+  st.model = null;
+  st.seq++; // 让在途加载失效
+  if (!e) return;
+  try { e.stop(); } catch { /* 已停止 */ }
+  try { if (e.clearSkeleton) e.clearSkeleton(); } catch { /* 清理失败不阻塞 */ }
+  st.disposes++;
+}
+
+/** 首次进入时创建 engine；canvas 尺寸变化由 engine 的 refreshResolution 处理 */
+export function ensureStageEngine(st, Engine, canvas) {
+  if (st.engine) return true;
+  // 不写死 antialias：交给 ensureStageEngineWith 按 settings.msaa 决定（默认自动=开）
+  return ensureStageEngineWith(st, Engine, undefined, canvas);
+}
+
+/** 建引擎；antialias 只在此时能生效（换画布重建时传 true） */
+export function ensureStageEngineWith(st, Engine, antialias, canvasOverride) {
+  const canvas = canvasOverride || st.canvas;
+  // 未显式指定时按设置走：'auto' = 开抗锯齿（与面板默认一致）
+  const wantAA = typeof antialias === 'boolean' ? antialias : st.settings.msaa === 'auto';
+  const engine = new Engine({
+    log: (level, msg, scope) => { if (level === 'error') st.lastError = `${scope || 'engine'}: ${msg}`; },
+    onLoadComplete: (info) => { st.model = info; },
+    onError: (msg) => { st.lastError = String(msg); },
+  });
+  if (!engine.init(canvas, { antialias: wantAA, allowParseOnly: false })) return false;
+  st.engine = engine;
+  applySettings(st);
+  return true;
+}
+
+/**
+ * 帧计数循环（验收口径：stats().frames 必须真实反映"画面在推进"）。
+ *
+ * 为什么可暂停：暂停后仍每帧跑一遍这条 rAF 纯烧 CPU（部署机无 GPU、纯软件 WebGL），
+ *   而它只是计数循环，与引擎是否绘制无关。暂停时**停掉循环本身**，恢复时重启。
+ * 单实例保证：用 st.frameRaf 记录句柄，已在跑就直接返回，避免重复排帧。
+ * @param {object} st 舞台内部状态
+ */
+export function startFrameTick(st) {
+  if (st.frameRaf) return;               // 已在跑：绝不重复启动
+  const tick = () => {
+    st.frameRaf = 0;
+    if (!st.model || st.model !== st.frameInfo) return;   // 模型已换/卸载：自然结束
+    st.tickCalls = (st.tickCalls || 0) + 1;               // 打点：验收直接看"循环被调了几次"
+    if (st.paused) return;                                // 暂停：不再排帧（resume 时重启）
+    st.frames++;
+    st.frameRaf = requestAnimationFrame(tick);
+  };
+  st.frameRaf = requestAnimationFrame(tick);
+}
+
+/**
+ * 单帧重绘（暂停中按需渲染的唯一入口）。
+ * 引擎在 stop() 之后不会自己画，而交互/改设置/切动作都改了状态 ⇒ 必须显式补一帧，
+ * 否则"暂停"会变成"点了没反应"。
+ * @param {object} st 舞台内部状态
+ * @returns {boolean} 是否成功请求到一次绘制
+ */
+export function repaintOnce(st) {
+  const e = st && st.engine;
+  if (!e) return false;
+  try {
+    // 按需渲染也算一帧：frames 的语义是"真的画了一次"，暂停期间的交互/改设置都体现在这里
+    if (typeof e.requestRender === 'function') { e.requestRender(); st.frames += 1; return true; }
+    if (typeof e.presentFirstFrame === 'function') { e.presentFirstFrame(); st.frames += 1; return true; }
+  } catch { /* 引擎不支持就放弃 */ }
+  return false;
+}
+
+/** 停掉帧计数循环（暂停/卸载时调用） */
+export function stopFrameTick(st) {
+  if (st.frameRaf) { try { cancelAnimationFrame(st.frameRaf); } catch { /* 忽略 */ } }
+  st.frameRaf = 0;
+}
+
+/** 播第一个动作 + 启动渲染循环 + 帧计数（验收用） */
+function startPlayback(st, info, loop) {
+  const e = st.engine;
+  const anims = e.getAnimations ? e.getAnimations() : [];
+  const motion = anims.length ? anims[0] : null;
+  if (motion) { try { e.setAnimation(motion, loop); } catch { /* 播不了就停首帧 */ } }
+  try { e.start(); } catch { /* 循环已在跑 */ }
+  try { if (e.presentFirstFrame) e.presentFirstFrame(); } catch { /* 留给下一帧 */ }
+  st.frames = 0;
+  st.frameInfo = info;
+  startFrameTick(st);
+  return { animations: anims, motion };
+}
+
+/** 加载主流程（编排：校验 Document → 选版本 → 注入源码 → 建 engine → 加载 → 起播） */
+export async function loadIntoStage(st, arg) {
+  // 入参只有一种形状：{ document }（ready）。资源地址与字节都在组装阶段备好，本层不取。
+  const doc = resolveDocument(st, arg);
+  const model = doc;
+  const seq = ++st.seq;
+  // 每次装载开始都清掉上一次的错误：lastError 语义是"最近一次装载的结果状态"，
+  //   成功后若不清，后面每次成功采样都会带着旧的失败原因（实测会污染对照表的每一格）
+  st.lastError = null;
+  // 切模型：中止上一个在途加载的请求（被中止属预期，不产生控制台报错）
+  if (st.abort) st.abort.abort();
+  const ctl = new AbortController();
+  st.abort = ctl;
+  // 上一个模型由 engine.loadModel 内部 stop+disposeTexturesAndAtlas 负责释放，这里只记账
+  if (st.model) { st.model = null; st.disposes++; }
+  // 先装运行时管理器：引擎取某个版本的运行时源码时要经它（多版本共存的单一入口）
+  installRuntimeManager();
+  const Engine = await pickEngineCtor();
+  const avail = await availableVersions();
+  // 版本来自 Document 的 meta（Document 形状里没有顶层 version）：
+  //   读错会挑到不匹配的运行时 —— 表现为骨架解析报 "Bone name must not be null" 这类怪错
+  const skeletonVer = (doc.meta && doc.meta.version) || doc.version;
+  // 一次性覆盖（URL 的 ?runtime=，由 app/url-params.js 设置）：取走即清空，天然只生效一次。
+  //   这是**唯一**的"手动指定运行时"入口，最终都落到下面这段选版逻辑上 —— 不另写优选规则。
+  const forced = takeForcedRuntime();
+  let ver;
+  if (forced) {
+    if (!avail.includes(forced)) {
+      // 这里才是"全新机器上缺运行时"最常撞到的地方：清单里根本没有这个版本，
+      //   请求压根不会发出去（也就走不到 sourceOf 的 404 分支）⇒ hint 必须在这里拼。
+      const hint = await loadRuntimeHint();
+      throw businessError(`指定的运行时 ${forced} 不可用（可用：${avail.join(' / ') || '运行时清单不可用'}）\n`
+        + spineMissingHint(forced, hint, null));
+    }
+    ver = forced;   // 给了就用，**绝不**回落到其它版本 —— 自动降级会让排查得出错误结论
+  } else {
+    ver = pickRuntimeVersion(skeletonVer, avail);   // 现状行为，一行没改
+  }
+  if (!ver) {
+    // 同理：清单全空（一个运行时都没装）时也不会发请求 ⇒ 在这里给补齐方案
+    const hint = await loadRuntimeHint();
+    throw businessError('无法确定该模型的 Spine 版本：元数据缺少 version，且运行时清单不可用\n'
+      + spineMissingHint(skeletonVer || '4.x', hint, null));
+  }
+  await ensureRuntimeSource(ver);
+  if (seq !== st.seq) throw abortedError();
+  if (seq !== st.seq) throw abortedError();
+  if (!ensureStageEngine(st, Engine, st.canvas)) throw businessError('当前环境没有可用的 WebGL，无法渲染 Spine');
+  if (!st.runtimeKeys.includes(ver)) st.runtimeKeys.push(ver);
+  st.loads++;
+  let info;
+  try {
+    info = await st.engine.loadModel(buildDescriptor(doc, ver));
+  } catch (e) {
+    // 手动指定时补一行"骨架版本 vs 所选版本"的对照 —— 这是手动覆盖与自动保证唯一实质分歧点：
+    //   自动在同 major 内会退到最大可用 minor，手动**不退**。不写清用户会以为两者选的是同一个东西。
+    if (forced) {
+      const autoVer = pickRuntimeVersion(skeletonVer, avail);
+      throw businessError(`模型加载失败：骨架版本 ${skeletonVer || '未知'}，当前指定的是运行时 ${ver}`
+        + `（去掉 ?runtime= 让自动选择，当前会自动用 ${autoVer || '未知'}；可用：${avail.join(' / ') || '清单不可用'}）`
+        + `。原始错误：${(e && e.message) || e}`);
+    }
+    throw e;
+  }
+  if (seq !== st.seq) throw abortedError();
+  if (!info) throw businessError('模型加载失败（引擎未返回结果）');
+  st.lastArg = arg; // 供 MSAA 重建上下文后恢复同一模型
+  captureViewBase(st); // 新模型 fit 完成：把当前取景记为视图基准
+  const playing = startPlayback(st, info, st.settings.loop);
+  return { version: ver, animations: playing.animations, motion: playing.motion };
+}

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

@@ -0,0 +1,28 @@
+// spine/canvas-entry.js —— createSpineStage 入口
+//
+// 构造期只接受 opts.canvas / opts.onStatus；其余设置一律经 applySettings 或各 setter 下发
+//   （构造期塞设置会让"面板设置"与"构造参数"出现两套真相）。
+
+import { attachExtraApi, buildStageApi } from './canvas-api.js';
+import { businessError } from './canvas-document.js';
+import { DEFAULT_SETTINGS, statsOf } from './canvas-view.js';
+
+export function createSpineStage(opts) {
+  const o = opts || {};
+  if (!o.canvas) throw new Error('createSpineStage 需要 canvas');
+  const onStatus = typeof o.onStatus === 'function' ? o.onStatus : () => {};
+  const st = {
+    canvas: o.canvas, lastArg: null,
+    engine: null, seq: 0, loads: 0, disposes: 0, lastError: null,
+    runtimeKeys: [], model: null, frames: 0, settings: { ...DEFAULT_SETTINGS },
+  };
+  const status = (patch) => { try { onStatus({ ...statsOf(st), ...patch }); } catch { /* 回调不影响渲染 */ } };
+  const fail = (msg, cause) => {
+    st.lastError = String(msg);
+    status({ phase: 'error', error: st.lastError });
+    return businessError(st.lastError, cause);
+  };
+  const api = buildStageApi(st, { status, fail });
+  attachExtraApi(api, st);
+  return api;
+}