modelstage 0.0.0-stage → 0.5.24

package/src/web/live2d/runtime-adapter.js

@@ -0,0 +1,289 @@
+// live2d/runtime-adapter.js —— Live2D 运行时的**唯一入口**
+//
+// 为什么要有这一层：运行时库换过世代，API 名字与调用形状都变过（settings 类名、
+//   Application 的 init 时机等）。如果让业务代码各自判断，加一个版本就要改多处，必漏。
+//   这里把"版本差异"收成一张兼容表 + 几个中性函数，业务侧只说"要什么"，不认具体类名。
+//
+// **允许出现旧类名字样的唯一位置**（grep 门禁）：PIXI.live2d.* / Cubism4ModelSettings 等
+//   只在本文件里出现，其它业务文件一律走这里的函数。
+
+// 缺库提示（把服务端给的完整指引拼进错误消息）；与 spine 侧共用同一个组装模块
+import { live2dMissingHint } from '../spine/runtime-hint.js';
+
+/** 运行时库（顺序不可颠倒：cubismcore 必须最先，pixi-live2d-display 初始化会检查它） */
+export const RUNTIME_LIBS = [
+  '/live2d-lib/live2dcubismcore.min.js',
+  '/live2d-lib/live2d.min.js',
+  '/live2d-lib/pixi.min.js',
+  '/live2d-lib/index.min.js',
+];
+
+/**
+ * 版本差异矩阵 —— **唯一真相**（代码与文档共用）。
+ * 一行 = 一个世代；加新版本只需加一行，业务代码零改动。
+ *
+ *   settings[].  同一能力的候选类名，按"该世代的新名 → 兼容旧名"顺序尝试
+ *   appInit      构造 PIXI.Application 的策略：
+ *                  'ctor'  = new Application(opts)（6.x 同步构造）
+ *                  'async' = new Application() + await app.init(opts)（8.x）
+ *                  'auto'  = 运行时探测 prototype.init（未登记世代的兜底）
+ *   filter/model 两代的 Filter 构造与 Live2DModel.from 签名一致，这里没有分叉
+ */
+const VERSION_MATRIX = {
+  6: {
+    label: 'v6',
+    appInit: 'ctor',
+    settings: {
+      cubism4: ['Cubism4ModelSettings', 'CubismModelSettings'],
+      cubism2: ['Cubism2ModelSettings', 'CubismLegacyModelSettings'],
+    },
+  },
+  8: {
+    label: 'v8',
+    appInit: 'async',
+    settings: {
+      cubism4: ['CubismModelSettings', 'Cubism4ModelSettings'],
+      cubism2: ['CubismLegacyModelSettings', 'Cubism2ModelSettings'],
+    },
+  },
+};
+
+/** 未登记世代的兜底：候选名取并集、appInit 走能力探测（新版本不会立刻挂） */
+const FALLBACK_PROFILE = {
+  label: 'unknown',
+  appInit: 'auto',
+  settings: {
+    cubism4: ['CubismModelSettings', 'Cubism4ModelSettings'],
+    cubism2: ['CubismLegacyModelSettings', 'Cubism2ModelSettings'],
+  },
+};
+
+/** 按运行时实际 PIXI 主版本取矩阵行（取不到就用兜底） */
+function profile() {
+  const PIXI = pixiLib();
+  const major = PIXI && PIXI.VERSION ? Number(String(PIXI.VERSION).split('.')[0]) : NaN;
+  return VERSION_MATRIX[major] || FALLBACK_PROFILE;
+}
+
+/** 当前世代的标签（runtimeInfo / 排障用） */
+export function runtimeFamily() {
+  return profile().label;
+}
+
+/** loadRuntime 的单例 Promise：并发调用共用同一次加载 */
+let loadingPromise = null;
+
+function pixiLib() {
+  return (typeof window !== 'undefined' && window.PIXI) ? window.PIXI : null;
+}
+
+/**
+ * <script> 加载失败时浏览器只给通用 error —— **读不到响应体**。
+ * 而服务端在 404/503 时已经把完整指引（官网 URL、目标目录、"不代下"的原因）写在 JSON error 里，
+ * 不取回来那句提示就白给了。所以补一次 fetch 只为接上那段文本（不是重试，不改变加载行为）。
+ * @param {string} url
+ * @returns {Promise<string>} 服务端 error 文本；取不到返回空串
+ */
+async function readServerError(url) {
+  try {
+    // 5s：这一步是在 <script> **已失败**之后补读一次响应体，结果会被 await 进 reject 之前，
+    //   所以它自己绝不能挂住 —— 否则"加载失败"永远不 reject，Live2D 激活会一直悬着。
+    //   5s 依据：服务端这条是纯本地 JSON（服务端已实测毫秒级返回），5s 只作兜底。
+    const r = await fetch(url, { cache: 'no-store', signal: AbortSignal.timeout(5000) });
+    const text = await r.text();
+    try {
+      const j = JSON.parse(text);
+      return (j && j.error) || '';
+    } catch {
+      return '';
+    }
+  } catch {
+    return '';
+  }
+}
+
+/** 注入一个 <script>；失败要摘掉标签，否则重试时页面上留着坏标签 */
+function injectScript(src) {
+  return new Promise((resolve, reject) => {
+    const el = document.createElement('script');
+    el.src = src;
+    el.onload = () => resolve(src);
+    el.onerror = () => {
+      el.remove();
+      // 把服务端的完整指引拼进错误消息 ⇒ 上层 stageLog 原样打进调试日志窗口
+      readServerError(src).then((detail) => {
+        reject(new Error(live2dMissingHint(src, detail)));
+      });
+    };
+    document.head.appendChild(el);
+  });
+}
+
+/**
+ * 注入全部运行时脚本（幂等）。
+ * 失败**不缓存**：一次瞬时失败（服务重启、网络抖动）若留着 rejected promise，
+ *   Live2D 就永久激活不了，只能刷新页面。
+ * @param {(msg:string, level?:string)=>void} [note]
+ * @returns {Promise<void>}
+ */
+export async function loadRuntime(note = () => {}) {
+  if (loadingPromise) return loadingPromise;
+  loadingPromise = (async () => {
+    for (const src of RUNTIME_LIBS) {
+      await injectScript(src);
+      note(`运行时已加载：${src.split('/').pop()}`);
+    }
+    const PIXI = pixiLib();
+    if (!PIXI || !PIXI.live2d) {
+      throw new Error('PIXI.live2d 不存在：运行时库顺序或版本不匹配（live2dcubismcore 必须最先）');
+    }
+    note(`Live2D 运行时就绪（PIXI ${PIXI.VERSION || 'unknown'}）`);
+  })().catch((err) => {
+    loadingPromise = null;   // 失败不缓存
+    throw err;
+  });
+  return loadingPromise;
+}
+
+/** 运行时是否已就绪（同步判断，不触发加载） */
+export function isReady() {
+  const PIXI = pixiLib();
+  return !!(PIXI && PIXI.live2d);
+}
+
+/** 等运行时就绪（没加载过就先加载） */
+export async function waitReady(note) {
+  if (isReady()) return;
+  await loadRuntime(note);
+}
+
+/**
+ * 实际版本与解析结果（排障/验收用）。
+ * 抓不到的写 unknown —— 版本写错比 unknown 危险。
+ * @returns {{pixi:string, display:string, cubism2:string, settingsCtorName:string|null}}
+ */
+export function runtimeInfo() {
+  const PIXI = pixiLib();
+  const lib = PIXI && PIXI.live2d ? PIXI.live2d : null;
+  const prof = profile();
+  const ctorName = lib ? (prof.settings.cubism4.find((n) => typeof lib[n] === 'function')
+    || prof.settings.cubism2.find((n) => typeof lib[n] === 'function')
+    || null) : null;
+  // cubism core 的版本只能运行时问
+  let cubismCore = 'unknown';
+  try {
+    const ver = window.Live2DCubismCore && window.Live2DCubismCore.Version
+      && typeof window.Live2DCubismCore.Version.csmGetVersion === 'function'
+      ? window.Live2DCubismCore.Version.csmGetVersion() : null;
+    if (ver) cubismCore = String(ver);
+  } catch { /* 取不到就 unknown */ }
+  return {
+    pixi: (PIXI && PIXI.VERSION) || 'unknown',
+    display: 'unknown',      // index.min.js 是 UMD 包装，无版本字符串（VERSIONS.json 里人工填）
+    cubism2: 'unknown',      // live2d.min.js 混淆代码，无版本字符串
+    cubismCore,
+    settingsCtorName: ctorName,
+  };
+}
+
+/**
+ * 取设置构造器（版本差异只在这里收敛）。
+ *
+ * **取不到就抛 version-unsupported，不再 return null 静默降级**：
+ *   过去的做法是返回 null、上层 warn 一句然后回落 URL 路径，结果是
+ *   "vfs:// 直接交给库 → Invalid URL → 模型对象残缺 → doDrawModel 报 undefined[0]"，
+ *   一串症状掩盖了真正原因（类名对不上）。宁可当场报清楚。
+ * @param {'cubism4'|'cubism2'} kind
+ * @returns {Function}
+ */
+export function getSettingsCtor(kind) {
+  const PIXI = pixiLib();
+  const lib = PIXI && PIXI.live2d ? PIXI.live2d : null;
+  if (!lib) throw new Error('version-unsupported: PIXI.live2d 不存在（运行时未加载）');
+  const names = profile().settings[kind === 'cubism2' ? 'cubism2' : 'cubism4'];
+  for (const name of names) {
+    if (typeof lib[name] === 'function') return lib[name];
+  }
+  const available = Object.keys(lib).filter((k) => /Settings$/.test(k));
+  throw new Error(`version-unsupported: 找不到 ${kind} 的设置类（试过 ${names.join(' / ')}）`
+    + `；库实际导出的 Settings 类有：${available.join(', ') || '(无)'}`);
+}
+
+/**
+ * 建模型实例（兼容 settings 实例与 URL 两种入参）。
+ *
+ * **URL 回落路径也要把 vfs:// 换成可 fetch 的 blob**：库不认识自定义协议，
+ *   直接喂 vfs:// 会 `Failed to construct 'URL': Invalid URL`。这里是"库版本不支持时的
+ *   唯一退路"，退路本身不能是坏的。
+ * @param {object|string} source settings 实例，或模型定义地址
+ * @param {{autoInteract?:boolean, resolveVfs?:(url:string)=>string|null}} [opts]
+ */
+export async function createModel(source, opts = {}) {
+  const PIXI = pixiLib();
+  if (!PIXI || !PIXI.live2d || !PIXI.live2d.Live2DModel) {
+    throw new Error('Live2DModel 不可用：运行时未加载或版本不支持');
+  }
+  let arg = source;
+  if (typeof source === 'string') {
+    // URL 形态：先换 blob（转换函数由调用方注入，复用它的 VFS 句柄，不在这里另建一个）
+    const resolved = typeof opts.resolveVfs === 'function' ? opts.resolveVfs(source) : null;
+    if (!resolved) {
+      throw new Error(`模型地址无法解析（不是可 fetch 的地址）：${source}`);
+    }
+    arg = resolved;
+  }
+  return PIXI.live2d.Live2DModel.from(arg, { autoInteract: opts.autoInteract === true });
+}
+
+/**
+ * 建 PIXI.Application（8.x 是异步 init，6.x 是构造时给 options）。
+ * @param {object} opts 传给 Application 的选项
+ * @returns {Promise<object>} 已就绪的 app
+ */
+export async function createApplication(opts = {}) {
+  const PIXI = pixiLib();
+  if (!PIXI || typeof PIXI.Application !== 'function') throw new Error('PIXI.Application 不可用');
+  // 策略来自版本矩阵；未登记世代（'auto'）按 prototype.init 能力探测兜底
+  const mode = profile().appInit;
+  const useAsync = mode === 'async'
+    || (mode === 'auto' && typeof PIXI.Application.prototype.init === 'function');
+  if (!useAsync) return new PIXI.Application(opts);   // 6.x：构造时给 options
+  const app = new PIXI.Application();                 // 8.x：先构造再 await init
+  await app.init(opts);
+  return app;
+}
+
+/**
+ * 把模型挂到舞台上（挂载方式收在一处，业务侧不关心 addChild 细节）。
+ * @param {object} app
+ * @param {object} model
+ */
+export function attachToStage(app, model) {
+  if (!app || !app.stage || !model) return false;
+  if (typeof app.stage.addChild === 'function') app.stage.addChild(model);
+  return true;
+}
+
+/**
+ * 设/清滤镜（含 filterArea 固定整屏；摘除时只脱引用不 destroy）。
+ * @param {object} app
+ * @param {object[]|null} filters null/空数组 = 摘掉
+ * @returns {boolean}
+ */
+export function setFilters(app, filters) {
+  if (!app || !app.stage) return false;
+  if (!filters || !filters.length) {
+    app.stage.filters = null;
+    return true;
+  }
+  app.stage.filterArea = app.screen;
+  app.stage.filters = filters;
+  return true;
+}
+
+/** 建一个滤镜实例（Filter 构造签名两代一致，但仍收在这里以满足"业务侧不碰 PIXI.*"） */
+export function createFilter(fragmentSrc, uniforms) {
+  const PIXI = pixiLib();
+  if (!PIXI || typeof PIXI.Filter !== 'function') return null;
+  return new PIXI.Filter(null, fragmentSrc, uniforms);
+}

package/src/web/live2d/stage-ctx.js

@@ -0,0 +1,152 @@
+// live2d/stage-ctx.js —— Live2D 舞台的运行时上下文（状态 + 薄工具）
+//
+// 为什么单独成模块：整个 Live2D 分支是"一个对象 + 一堆方法"的形状，状态（st / handleRef）
+//   是它们共同的隐式参数。把这个上下文集中到一处，其余模块按职责切开时才有明确的边界。
+//
+// 约定：ctx.st 对子模块可见（读写）。这些函数本来就是同一个对象的内部实现，
+//   再套一层 getter/setter 只增加噪音，换不来真实约束。
+//   ctx.api 是装配期注册表：stage.js 依次建好各模块后挂进来，模块之间不直接 import（避免环）。
+import { CAMERA } from '../render/camera/constants.js';
+
+/** 覆盖层容器 id */
+export const OVERLAY_ID = 'live2d-overlay';
+/** 覆盖层内 canvas 的 id */
+export const OVERLAY_CANVAS_ID = 'live2d-overlay-canvas';
+/** 运行时库（顺序不可颠倒：cubismcore 必须最先，pixi-live2d-display 初始化会检查它） */
+export const LIBS = [
+  '/live2d-lib/live2dcubismcore.min.js',
+  '/live2d-lib/live2d.min.js',
+  '/live2d-lib/pixi.min.js',
+  '/live2d-lib/index.min.js',
+];
+/** 缩放范围唯一来源：render/camera/constants.js（禁止在此写裸数字） */
+export const ZOOM_MIN = CAMERA.MIN;
+export const ZOOM_MAX = CAMERA.MAX;
+
+/**
+ * 判定"带 scheme 的引用"（拼接目录时用）：任意 scheme 或 data: 都不要拼目录。
+ *
+ * 为什么拼接前必须判：模型定义里允许写绝对 URL，拼上去会变成
+ *   `/files/dir/http://host/x.motion3.json` 这种无效地址（曾导致 14 次 miss）。
+ *   注意这里包含 `vfs://` —— 它的作用是"别再前缀目录"，不是"可直连"。
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isAbsoluteRef(url) {
+  const text = String(url == null ? '' : url);
+  if (!text) return false;
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(text)) return true;
+  return /^data:/i.test(text);   // data: 可能不带 //
+}
+
+/**
+ * 判定"浏览器可直接取用"的地址（resolveAsset 短接用）：http/https/blob/data。
+ *
+ * **不能包含 vfs://**：vfs:// 是虚拟地址，必须交给 VirtualFS 解析成 blob/真实地址；
+ *   当成"可直连"放行会让浏览器直接 fetch('vfs://…') → Network error
+ *   （这条我自己先踩了一次：短接后 vfs:// 装载全挂、hits 变 0）。
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isDirectUrl(url) {
+  const text = String(url == null ? '' : url);
+  if (!text) return false;
+  if (/^(https?|blob):/i.test(text)) return true;
+  return /^data:/i.test(text);
+}
+
+/** 创建运行时上下文。
+ * @param {{vfs?: object, getOverlayHost?: Function, log?: Function}} options
+ * @returns {object} ctx（st / handleRef / 薄工具 / api 注册表）
+ */
+export function createStageContext({ vfs, getOverlayHost, log } = {}) {
+  const ctx = {
+    vfs: vfs || null,
+    getOverlayHost: typeof getOverlayHost === 'function' ? getOverlayHost : null,
+    /** 装配期注册表：overlay / pixiApp / view / probe / model 依次挂进来 */
+    api: {},
+  };
+  /** StageSurface 句柄（画布/尺寸/DPR 由 Surface 提供；为空时退回自建覆盖层） */
+  ctx.handleRef = null;
+
+  const st = {
+    app: null,          // 渲染应用实例（经 runtime-adapter 创建）
+    model: null,        // 模型实例（经 runtime-adapter 创建）
+    libsReady: null,    // 库加载 Promise
+    active: false,      // 是否处于激活态（引擎 l2dActive 依赖它）
+    zoomRatio: 1,       // 缩放倍数（唯一写入方是 bridge.setZoomRatio）
+    panX: 0,
+    panY: 0,
+    modelId: null,      // 当前模型 id（引擎用它判断复用）
+    meta: null,         // 当前模型元数据（motions / expressions）
+    motionMap: new Map(), // 标签 -> { group, index }
+  };
+  ctx.st = st;
+
+  /** 统一日志出口（缺省静默） */
+  function note(message, level = 'info') {
+    if (typeof log === 'function') {
+      try { log(message, level); } catch { /* 日志失败不影响渲染 */ }
+    }
+  }
+
+  /** 资源入口经 VirtualFS 解析（命中用 Blob URL，未命中回落原 URL） */
+  function resolveAsset(url) {
+    if (!url) return null;
+    // 已经可直接取用（http/https/blob/data）就不必问 VFS：它对这些永远 miss
+    // 注意 vfs:// 不在此列 —— 那是虚拟地址，必须由 VirtualFS 解析
+    if (isDirectUrl(url)) return url;
+    try {
+      const hit = vfs && typeof vfs.resolve === 'function' ? vfs.resolve(url) : null;
+      return hit || url;
+    } catch {
+      return url;
+    }
+  }
+
+  /** 取条目的入口地址（兼容 entry.url / modelUrl） */
+  function entryUrlOf(doc) {
+    if (!doc) return null;
+    if (doc.entry && doc.entry.url) return doc.entry.url;
+    return doc.modelUrl || null;
+  }
+
+  /**
+   * Surface 下发的几何（唯一尺寸来源）。
+   *
+   * 必须兼容两种"句柄"形态，因为调用方给的并不总是同一个东西：
+   *   · 真 handle：`{ geometry(), dpr, ... }` —— Surface 在 mount / render(handle) 时传；
+   *   · 轻量盒：  `{ size: { width, height }, dpr }` —— render/live2d.js 在 resize() 里传。
+   * 早期只认第一种，于是渲染器 resize 那条路径上 `surfaceGeometry()` 恒为 null：
+   *   渲染器自己 resize 了 PIXI，但覆盖层**容器**的 CSS 盒拿不到尺寸、没人更新 ⇒
+   *   画布被旧容器裁掉（真机旋转后"模型挤在左侧窄带"）。这里补上第二种形态即可。
+   *
+   * @returns {{cssW:number, cssH:number, dpr:number, res:number}|null}
+   */
+  function surfaceGeometry() {
+    try {
+      const h = ctx.handleRef;
+      if (!h) return null;
+      if (typeof h.geometry === 'function') return h.geometry();
+      const size = h.size || null;
+      if (size && size.width > 0 && size.height > 0) {
+        // 轻量盒没有 res 字段时用 dpr 顶上（Surface 的 res 缺省就是设备比）
+        const res = Number(h.res) > 0 ? Number(h.res) : (Number(h.dpr) > 0 ? Number(h.dpr) : 1);
+        return { cssW: size.width, cssH: size.height, dpr: res, res };
+      }
+      return null;
+    } catch { return null; }
+  }
+
+  /** Surface 下发的 CSS 尺寸 */
+  function surfaceSize() {
+    const g = surfaceGeometry();
+    return g ? { width: g.cssW, height: g.cssH } : null;
+  }
+
+  function width8() { const g = surfaceGeometry(); return g ? g.cssW : 0; }
+  function height8() { const g = surfaceGeometry(); return g ? g.cssH : 0; }
+
+  Object.assign(ctx, { note, resolveAsset, entryUrlOf, surfaceGeometry, surfaceSize, width8, height8 });
+  return ctx;
+}

package/src/web/live2d/stage.js

@@ -0,0 +1,204 @@
+// live2d/stage.js —— Live2D 渲染器装配（原生 ES 模块，无构建）
+//
+// 角色：作为「2D 渲染器」的 Live2D 分支实现，与 Spine 共用同一套相机与交互。
+//   · 覆盖层 canvas 覆盖在 Spine 画布之上（pointer-events:none）⇒ 指针事件落到舞台区域，
+//     由交互层驱动当前渲染器的相机；Live2D 侧的相机动作经 bridge 落到 PIXI。
+//   · 本文件只做**装配**：建上下文 → 依次建各职责模块 → 组装 handle → 装诊断 HUD。
+//     具体实现在同目录下：
+//       stage-ctx.js      状态与薄工具（st / handleRef / 尺寸 / vfs 解析 / 常量）
+//       overlay.js        覆盖层容器与画布的 DOM 显隐（尺寸由 overlay.setBox 写）
+//       pixi-app.js       运行时库懒加载与 PIXI 实例、渲染器尺寸校准
+//       view.js           视图数学：computeFit / applyZoom / syncRect / syncSize
+//       probe.js          只读诊断：像素采样 / MODELCMP / rendererInfo / rendererSize
+//       probe-geometry.js 只读诊断：inspectGeometry（几何取证）
+//       model.js          模型装载与动作表
+//       bridge.js         相机 backend 与播放控制（对外能力面）
+//
+// 资源入口先经 VirtualFS.resolve()（命中用 Blob URL，未命中回落原 URL）——不 patch PIXI 加载器。
+import { installDiagHud } from '../debug/diag-hud.js';
+import { createStageContext, OVERLAY_CANVAS_ID } from './stage-ctx.js';
+import { releaseLive2DResources } from './release.js';
+import { createOverlay } from './overlay.js';
+import { createPixiApp } from './pixi-app.js';
+import { createView } from './view.js';
+import { createProbe } from './probe.js';
+import { createProbeGeometry } from './probe-geometry.js';
+import { createModel } from './model.js';
+import { createBridge } from './bridge.js';
+
+/**
+ * 创建 Live2D 舞台。
+ * @param {{
+ *   vfs?: { resolve: (url: string) => string|null },
+ *   getOverlayHost?: () => HTMLElement|null,
+ *   log?: (message: string, level?: 'info'|'warn'|'error') => void,
+ * }} options
+ */
+export function createLive2DStage({ vfs, getOverlayHost, log } = {}) {
+  const ctx = createStageContext({ vfs, getOverlayHost, log });
+
+  // 装配顺序 = 依赖顺序（无环）：
+  //   overlay → pixiApp → view → probe → probeGeometry → model → bridge
+  // 为什么用 ctx.api 注册表而不是模块间直接 import：模块之间是"互相调用"的关系
+  //   （overlay 要 pixiApp.fitAppToOverlay、model 要 view.applyZoom…），直接 import 会成环；
+  //   装配期一次性挂进来，运行期只按名字取。
+  const overlay = createOverlay(ctx);
+  ctx.api.overlay = overlay;
+  const pixiApp = createPixiApp(ctx);
+  ctx.api.pixiApp = pixiApp;
+  const view = createView(ctx);
+  ctx.api.view = view;
+  const probe = createProbe(ctx);
+  ctx.api.probe = probe;
+  const probeGeometry = createProbeGeometry(ctx);
+  ctx.api.probeGeometry = probeGeometry;
+  const model = createModel(ctx);
+  ctx.api.model = model;
+  const bridge = createBridge(ctx);
+  ctx.api.bridge = bridge;
+
+  // 诊断 HUD 句柄（延迟到首次模型加载成功后安装，见 model.loadModel 末尾）
+  let diagHandle = null;
+
+  /**
+   * 装载入口（渲染器调它）。
+   * @param {object} doc 文档/条目
+   * @param {object} handle StageSurface 句柄
+   */
+  /**
+   * 断言"Live2D 画布真的在页面上"。
+   *
+   * 为什么需要这个断言（血的教训）：
+   *   PIXI 在**游离 canvas** 上渲染时，画面完全不可见，但 `readPixels`/像素采样**照样能读到有效像素**——
+   *   于是"ratio>0 / alpha=255"这类判据会把白屏判成正常。唯一可靠的判据是 DOM 关系：
+   *   canvas 在容器里、容器在文档里、且 `app.view` 就是这张 canvas。
+   * @returns {{ok: boolean, detail: object}}
+   */
+  function assertCanvasAttached() {
+    const app = ctx.st.app;
+    const el = (ctx.st.overlay && ctx.st.overlay.isConnected) ? ctx.st.overlay : document.getElementById('live2d-overlay');
+    const canvas = document.getElementById(OVERLAY_CANVAS_ID);
+    const inContainer = !!(canvas && el && typeof el.contains === 'function' && el.contains(canvas));
+    const inDom = !!(canvas && canvas.isConnected);
+    const viewOk = !!(app && app.view && app.view.isConnected === true);
+    const viewIsCanvas = !!(app && canvas && app.view === canvas);
+    return {
+      ok: inContainer && inDom && viewOk && viewIsCanvas,
+      detail: {
+        hasCanvas: !!canvas, inContainer, inDom, viewOk, viewIsCanvas,
+        appViewId: app && app.view ? (app.view.id || '(无 id)') : null,
+      },
+    };
+  }
+
+  async function mount(doc, handle) {
+    ctx.handleRef = handle || null;
+    const entry = doc && (doc.model || doc);
+    const result = await bridge.loadForEngine(entry);
+    // 装载后立刻校验"画布在页面上"：同面切换曾因 canvas 被 PIXI 摘掉而整屏空白，
+    //   而 stats/像素采样全都报正常；这里让缺陷当场变成一条 warn（自检也会读它）。
+    const chk = assertCanvasAttached();
+    if (!chk.ok) ctx.note(`Live2D 画布不在页面上（画面将不可见）：${JSON.stringify(chk.detail)}`, 'warn');
+    return result;
+  }
+
+  /**
+   * 卸载 / 彻底释放：**同一条释放路径**（实现在 live2d/release.js，便于静态回归）。
+   *
+   * 为什么 live2d 两面不做区分（与 spine 相反）：
+   *   PIXI `app.destroy(true)` 的 removeView 会摘掉 canvas 只留容器，留下「容器在、canvas 不在」
+   *   的中间态；一旦下游按容器复用，PIXI 就会渲染到**不在 DOM 的游离画布**上——页面全白，
+   *   而 stats 与像素采样全都正常（曾真实发生）。app 与覆盖层 DOM 重建成本都很低，
+   *   不值得为"保留 DOM"维护第二套生命周期。下次 mount 由 buildOverlay 全量重建。
+   * spine 相反：重建引擎要重注入运行时源码并按版本选运行时，代价高，所以那边保留引擎。
+   */
+  function unmount() {
+    // **只卸内容、保留引擎**（与 spine 同语义）：surface-switch 对"同一渲染器换内容"选 unmount，
+    //   本意就是复用引擎/PIXI 覆盖层。
+    //
+    // 为什么改（实测依据）：原来 unmount 与 dispose 走同一条 release 路径 ⇒ 每次 live2d→live2d
+    //   都 `app.destroy(true)` 再新建 PIXI.Application ⇒ 每切一次净增 2 个存活 WebGL 上下文
+    //   （1 个匿名 0x0 探测画布 + 1 个 overlay canvas），累积到浏览器上限（~16）后最旧上下文被丢弃
+    //   ⇒ 画布黑（现场："加载过那个角色的 Live2D/资源包之后，后续请求全挂"）。
+    //   而"容器在、canvas 不在"的旧坑是 **destroy(true) 的 removeView** 造成的——只要 unmount 不销毁 app，
+    //   这个中间态就不会出现。
+    if (ctx.st.app) {
+      try { if (ctx.st.model) { ctx.st.app.stage.removeChild(ctx.st.model); } } catch { /* 忽略 */ }
+      try { if (ctx.st.model) ctx.st.model.destroy({ children: true }); } catch { /* 忽略 */ }
+      ctx.st.model = null;
+      ctx.st.modelId = null;
+      try { if (typeof ctx.st.app.stop === 'function') ctx.st.app.stop(); } catch { /* 忽略 */ }
+      try { if (ctx.st.overlay) ctx.st.overlay.style.display = 'none'; } catch { /* 忽略 */ }
+      ctx.st.active = false;
+      stopDiagOnUnmount();
+      return true;
+    }
+    // 没有 app（异常时序）：退回完整释放，保证不留半截状态
+    releaseLive2DResources({ st: ctx.st, note: ctx.note, stopDiag: takeDiagStop() });
+    return true;
+  }
+
+  /** 停诊断 HUD（unmount 走轻路径时也要停，否则 HUD 会在隐藏的覆盖层上空转） */
+  function stopDiagOnUnmount() {
+    try { const stop = takeDiagStop(); if (typeof stop === 'function') stop(); } catch { /* 忽略 */ }
+  }
+
+  /** 彻底释放：与 unmount 同一路径（渲染器实例是否丢弃由调用方决定） */
+  function dispose() {
+    releaseLive2DResources({ st: ctx.st, note: ctx.note, stopDiag: takeDiagStop() });
+  }
+
+  /** 取出并清空诊断 HUD 停止函数（幂等：第二次返回 null） */
+  function takeDiagStop() {
+    const h = diagHandle;
+    diagHandle = null;
+    return h && typeof h.stop === 'function' ? () => h.stop() : null;
+  }
+
+  // 诊断 HUD：仅在 ?diag=1 时创建；所有取值都延迟到调用时（此处 app 可能为 null）
+  diagHandle = installDiagHud({
+    getRendererInfo: () => {
+      try {
+        const w = typeof window !== 'undefined' ? window.__WEB__ : null;
+        return w && w.live2d && typeof w.live2d.rendererInfo === 'function' ? w.live2d.rendererInfo() : null;
+      } catch { return null; }
+    },
+    readCanvasPixels: (...args) => probe.readCanvasPixels(...args),
+    overlayCanvasId: OVERLAY_CANVAS_ID,
+    log: (m) => ctx.note(m),
+  });
+
+  // 对外面：成员集合与顺序属于契约，增删需同步渲染器与面板
+  return {
+    id: 'live2d',
+    bridge,
+    mount,
+    unmount,
+    dispose,
+    show: (m) => bridge.loadForEngine(m),
+    hide: () => overlay.hide(),
+    isActive: () => ctx.st.active,
+    debug: () => bridge.readState(),
+    /** 诊断：按当前状态采一条 MODELCMP（不改渲染） */
+    collectCmp: (tag) => probe.collectCmp(tag),
+    syncRect: () => view.syncRect(),
+    readCanvasPixels: (points) => probe.readCanvasPixels(points),
+    /** 只读：取 PIXI app 引用（诊断实验用，不改变渲染逻辑） */
+    getApp() { return ctx.st.app; },
+    rendererInfo: () => probe.rendererInfo(),
+    inspectGeometry: () => probeGeometry.inspectGeometry(),
+    rendererSize: () => probe.rendererSize(),
+    /**
+     * 尺寸同步：Surface 量好尺寸后调用（渲染器不自己读 DOM）。
+     * @param {object} handle StageSurface 句柄
+     */
+    syncSize: (handle) => view.syncSize(handle),
+    /** 写一条日志（供渲染器记录切换断言） */
+    note: (message) => ctx.note(message),
+    /**
+     * 断言"画布真的在页面上"（切换/装载后自检用）。
+     * 像素采样在游离 canvas 上照样能读到有效像素，所以可见性只能用 DOM 关系判定。
+     */
+    assertCanvasAttached,
+  };
+}