modelstage 0.0.0-stage → 0.5.28

package/src/web/live2d/probe-geometry.js

@@ -0,0 +1,329 @@
+// live2d/probe-geometry.js —— 只读诊断：模型运行时几何（inspectGeometry）
+//
+// 这一段是"取证型"代码：displayObject 尺寸 / 包围盒 / Cubism 画布尺寸 / clipping mask /
+//   drawable 与 part 的可用 API 全部列出来，用于判断 fit 口径与"内容被框在矩形里"的成因。
+//
+// 为什么拆成这么多小函数：早期它是一个 128 行、圈复杂度 95 的大函数，读的人只能顺序扫下来
+//   才知道每段在取证什么。现在按「取证哪一类事实」分组，每段只回答一个问题：
+//     readBounds           模型包围盒
+//     readCoreCanvas       Cubism 画布尺寸（coreModel.getCanvasWidth/Height）
+//     readInternalSize     internalModel 的尺寸与原始尺寸
+//     readFitRatios        两种 fit 口径的比值（判断该用哪个基准）
+//     readClipProbe        clipping mask 相关字段（"内容被框住"的第一嫌疑）
+//     readDrawableProbe    drawable / part 的可用 API 与顶点范围
+//   inspectGeometry 只做编排与组装，保证**返回结构逐键不变**（它是 handle 上的对外方法）。
+import { CAMERA } from '../render/camera/constants.js';
+
+/** 取模型包围盒（getBounds 可能抛，抛了就当没有） */
+function readBounds(model) {
+  try {
+    const bb = model.getBounds();
+    if (!bb) return null;
+    return { x: +bb.x.toFixed(2), y: +bb.y.toFixed(2), w: +bb.width.toFixed(2), h: +bb.height.toFixed(2) };
+  } catch {
+    return null;
+  }
+}
+
+/** 取 Cubism 画布尺寸与 coreModel 引用 */
+function readCoreCanvas(internal) {
+  const core = internal && internal.coreModel;
+  const hasW = core && typeof core.getCanvasWidth === 'function';
+  const hasH = core && typeof core.getCanvasHeight === 'function';
+  return {
+    core,
+    coreW: hasW ? core.getCanvasWidth() : null,
+    coreH: hasH ? core.getCanvasHeight() : null,
+  };
+}
+
+/** 取 internalModel 的尺寸（含未缩放的原始尺寸） */
+function readInternalSize(internal) {
+  if (!internal) return null;
+  return { w: internal.width, h: internal.height, originalW: internal.originalWidth, originalH: internal.originalHeight };
+}
+
+/**
+ * 两种 fit 口径的比值。
+ *   当前实现用 getBounds 口径并乘 0.98（历史值，仅做对照，不重置模型）；
+ *   期望口径是 Cubism 画布 + 常量边距。ratio 用来判断两者差多少。
+ */
+function readFitRatios(b, coreW, coreH, vpW, vpH) {
+  const curFit = b && vpW && vpH ? Math.min(vpW / b.w, vpH / b.h) * 0.98 : null;
+  const coreFit = coreW && coreH && vpW && vpH ? Math.min(vpW / coreW, vpH / coreH) * (1 - CAMERA.FIT_MARGIN) : null;
+  return { curFit, coreFit, ratio: curFit && coreFit ? +(curFit / coreFit).toFixed(3) : null };
+}
+
+/** 在候选键里找一个"数组状"字段，返回 { key, len }（不同 Cubism 版本字段名不同） */
+function pickArrayLike(obj, keys) {
+  for (const k of keys) {
+    try {
+      const v = obj && obj[k];
+      if (v && typeof v.length === 'number') return { key: k, len: v.length };
+    } catch { /* 不可读字段 */ }
+  }
+  return null;
+}
+
+/** clipping 管理器上的两个"上下文列表"（mask / draw） */
+function readClipLists(cm) {
+  if (!cm) return { maskList: null, drawList: null };
+  return {
+    maskList: pickArrayLike(cm, ['_clippingContextListForMask', 'clippingContextListForMask', '_clippingContextList', 'clippingContextList']),
+    drawList: pickArrayLike(cm, ['_clippingContextListForDraw', 'clippingContextListForDraw', '_clippingContextListForDraws']),
+  };
+}
+
+/** 对象上与 clip|mask 有关的键名（判断字段是否换名） */
+function clipKeyNames(obj) {
+  if (!obj) return [];
+  return Object.keys(obj).filter((k) => /clip|mask/i.test(k)).slice(0, 12);
+}
+
+/** clipping mask 取证：拿不到就报 err，拿到就只回字段值 */
+function readClipProbe(internal) {
+  try {
+    const r = internal && internal.renderer;
+    if (!r) return { err: 'no renderer' };
+    const cm = r._clippingManager || r.clippingManager || null;
+    const { maskList, drawList } = readClipLists(cm);
+    return {
+      hasClippingManager: !!cm,
+      maskList,
+      drawList,
+      maskBufferSize: cm && cm._clippingMaskBufferSize != null ? cm._clippingMaskBufferSize : null,
+      cmKeys: clipKeyNames(cm),
+      rendererClipKeys: clipKeyNames(r),
+      // 历史字段：曾想读网格数，目前恒为 null（保留键名不破坏对外结构）
+      meshCount: null,
+    };
+  } catch (e) {
+    return { err: String(e && e.message).slice(0, 80) };
+  }
+}
+
+/** 取 part id（不同版本的返回值类型不同：字符串 / CubismString / 数字） */
+function readPartId(raw, i) {
+  try {
+    if (typeof raw.getPartId !== 'function') return null;
+    const id = raw.getPartId(i);
+    if (!id) return null;
+    if (typeof id === 'string') return id;
+    if (typeof id.getString === 'function') return id.getString();
+    if (id.s !== undefined) return String(id.s);
+    return String(id);
+  } catch {
+    return null;
+  }
+}
+
+/** 顶点范围（只算包围盒，用于判断 drawable 是否落在画布某一块） */
+function readVertexBbox(raw, i, vertexCount) {
+  if (typeof raw.getDrawableVertexPositions !== 'function' || !(vertexCount > 0)) return null;
+  const v = raw.getDrawableVertexPositions(i);
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (let k = 0; k + 1 < v.length; k += 2) {
+    const x = v[k], y = v[k + 1];
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+    if (y < minY) minY = y;
+    if (y > maxY) maxY = y;
+  }
+  return { x: +minX.toFixed(3), y: +minY.toFixed(3), w: +(maxX - minX).toFixed(3), h: +(maxY - minY).toFixed(3) };
+}
+
+/** 读 drawable 的父 part 索引（API 不存在或抛错都当没有） */
+function readParentPart(raw, i, has) {
+  try {
+    if (!has('getDrawableParentPartIndex')) return null;
+    return raw.getDrawableParentPartIndex(i);
+  } catch {
+    return null;
+  }
+}
+
+/** 单个 drawable 的取证条目 */
+function readDrawableItem(raw, i, has) {
+  const item = { i, parentPart: null, partId: null, vertexCount: null, bbox: null };
+  item.parentPart = readParentPart(raw, i, has);
+  if (item.parentPart != null && item.parentPart >= 0) item.partId = readPartId(raw, item.parentPart);
+  try { if (has('getDrawableVertexCount')) item.vertexCount = raw.getDrawableVertexCount(i); } catch { /* 忽略 */ }
+  try {
+    const box = readVertexBbox(raw, i, item.vertexCount);
+    if (box) item.bbox = box;
+  } catch (e) {
+    item.bboxErr = String(e && e.message).slice(0, 40);
+  }
+  return item;
+}
+
+/** coreModel 上哪些 API 可用（决定能取证到什么粒度） */
+function readApiAvailability(has) {
+  return {
+    getDrawableCount: has('getDrawableCount'),
+    getDrawableVertexPositions: has('getDrawableVertexPositions'),
+    getDrawableVertexCount: has('getDrawableVertexCount'),
+    getDrawableParentPartIndex: has('getDrawableParentPartIndex'),
+    getPartCount: has('getPartCount'),
+    getPartId: has('getPartId'),
+  };
+}
+
+/** 枚举对象自身可枚举的方法（对象上可能有会抛的 getter，逐个兜住） */
+function listOwnMethods(obj) {
+  const names = [];
+  try {
+    for (const k in obj) {
+      try { if (typeof obj[k] === 'function') names.push(k); } catch { /* 不可读字段 */ }
+    }
+  } catch { /* 整体不可枚举 */ }
+  return names;
+}
+
+/** 收集某一层原型上的方法名（该层不可读就返回空） */
+function collectProtoNames(obj, proto) {
+  const names = [];
+  try {
+    Object.getOwnPropertyNames(proto).forEach((n) => {
+      try { if (typeof obj[n] === 'function') names.push(n); } catch { /* 不可读字段 */ }
+    });
+  } catch { /* 该层原型不可读 */ }
+  return names;
+}
+
+/** 沿原型链追加方法名（层数有上限，避免异常对象拖死） */
+function listProtoMethods(obj, names) {
+  let proto = null;
+  try { proto = Object.getPrototypeOf(obj); } catch { proto = null; }
+  let guard = 0;
+  while (proto && proto !== Object.prototype && guard < 4) {
+    names.push(...collectProtoNames(obj, proto));
+    try { proto = Object.getPrototypeOf(proto); } catch { proto = null; }
+    guard += 1;
+  }
+  return names;
+}
+
+/** 收集对象自身 + 原型链上的方法名 */
+function collectMethodNames(obj) {
+  return listProtoMethods(obj, listOwnMethods(obj));
+}
+
+/** 枚举一个对象（含原型链）上"看起来与几何相关"的方法名，用于发现未公开的 API */
+function probeMethodNames(obj, label, depth) {
+  if (!obj || typeof obj !== 'object' || depth > 3) return null;
+  const names = collectMethodNames(obj);
+  const hit = [...new Set(names)].filter((n) => /draw|part|texture|vertex|canvas|bounds|geometry/i.test(n));
+  return {
+    label,
+    ctor: obj.constructor ? obj.constructor.name : typeof obj,
+    methodCount: names.length,
+    matched: hit.slice(0, 18),
+  };
+}
+
+/** 列出几个可能的 API 宿主对象，逐个枚举方法（只读，用于定位未公开接口） */
+function readApiPaths(core, internal) {
+  const out = [];
+  const targets = [
+    [core, 'coreModel', 0],
+    [core && core._model, 'coreModel._model', 1],
+    [core && core._model && core._model._model, 'coreModel._model._model', 2],
+    [core && core._model && core._model.drawables, 'coreModel._model.drawables', 2],
+    [internal && internal.renderer, 'internalModel.renderer', 1],
+  ];
+  for (const [obj, label, depth] of targets) {
+    const hit = probeMethodNames(obj, label, depth);
+    if (hit) out.push(hit);
+  }
+  return out;
+}
+
+/** 取 coreModel 上真正带 API 的 raw 对象（不同版本挂载层级不同） */
+function readRawCore(internal) {
+  const core = internal && internal.coreModel;
+  if (!core) return null;
+  return core._model ? core._model : core;
+}
+
+/** part id 列表（上限 12 个，够判断命名风格即可） */
+function readPartIds(raw, partCount) {
+  const partIds = [];
+  const max = Math.min(partCount || 0, 12);
+  for (let i = 0; i < max; i += 1) partIds.push(readPartId(raw, i));
+  return partIds;
+}
+
+/** drawable 取证条目（上限 8 个） */
+function readDrawableSamples(raw, count, has) {
+  const sample = [];
+  const max = Math.min(count || 0, 8);
+  for (let i = 0; i < max; i += 1) sample.push(readDrawableItem(raw, i, has));
+  return sample;
+}
+
+/** drawable / part 取证（主体包围盒问题的第二嫌疑） */
+function readDrawableProbe(internal) {
+  try {
+    const raw = readRawCore(internal);
+    if (!raw) return { err: 'no coreModel' };
+    const has = (k) => typeof raw[k] === 'function';
+    const count = has('getDrawableCount') ? raw.getDrawableCount() : null;
+    const partCount = has('getPartCount') ? raw.getPartCount() : null;
+    return {
+      coreType: raw.constructor ? raw.constructor.name : typeof raw,
+      drawableCount: count,
+      partCount,
+      partIds: readPartIds(raw, partCount),
+      api: readApiAvailability(has),
+      sample: readDrawableSamples(raw, count, has),
+      apiPaths: readApiPaths(internal && internal.coreModel, internal),
+    };
+  } catch (e) {
+    return { err: String(e && e.message).slice(0, 80) };
+  }
+}
+
+/**
+ * 创建几何取证模块。
+ * @param {object} ctx 运行时上下文
+ * @returns {{inspectGeometry:Function}}
+ */
+export function createProbeGeometry(ctx) {
+  const { st, surfaceSize } = ctx;
+
+  /**
+   * 只读：模型运行时几何（**不触发任何重排**）。
+   *
+   * 返回结构是对外契约（handle.inspectGeometry），键名与嵌套形状不得变化：
+   *   display / bounds / coreCanvas / internalSize / viewport /
+   *   fitByBounds / fitByCore / ratio / clipProbe / drawableProbe
+   * @returns {object|null}
+   */
+  function inspectGeometry() {
+    const model = st.model;
+    if (!model) return null;
+    const b = readBounds(model);
+    const internal = model.internalModel || null;
+    const { core, coreW, coreH } = readCoreCanvas(internal);
+    const size = surfaceSize();
+    const vpW = size ? size.width : null;
+    const vpH = size ? size.height : null;
+    const { curFit, coreFit, ratio } = readFitRatios(b, coreW, coreH, vpW, vpH);
+    void core;
+    return {
+      display: { w: model.width, h: model.height, scale: model.scale ? +model.scale.x.toFixed(4) : null, x: model.x, y: model.y },
+      bounds: b,
+      coreCanvas: { w: coreW, h: coreH },
+      internalSize: readInternalSize(internal),
+      viewport: { w: vpW, h: vpH },
+      fitByBounds: curFit,
+      fitByCore: coreFit,
+      ratio,
+      clipProbe: readClipProbe(internal),
+      drawableProbe: readDrawableProbe(internal),
+    };
+  }
+
+  return { inspectGeometry };
+}

package/src/web/live2d/probe.js

@@ -0,0 +1,119 @@
+// live2d/probe.js —— 只读诊断（渲染器状态 / 像素采样 / MODELCMP 采集）
+//
+// 全部只读：不重置视图、不改渲染、不触发重排。之所以独立成文件，
+//   是因为这些函数是"排查用"的，和渲染主链路没有调用关系，混在一起会掩盖主干。
+// 注：rendererInfo 里的 __transparentClear* 等字段对应的 GL 包装代码已删除，
+//   这些键现在恒为 null/false（历史遗留），保留是为了不改变对外返回键集合。
+import { collectLive2DModelCmp } from '../debug/model-cmp.js';
+
+/** 渲染器自身的清屏配置（PIXI 字段，不做 GL 查询） */
+function readClearConfig(r, gl) {
+  return {
+    backgroundAlpha: r.backgroundAlpha,
+    backgroundColor: r.backgroundColor,
+    clearBeforeRender: r.clearBeforeRender,
+    resolution: r.resolution,
+    width: r.width,
+    height: r.height,
+    rendererType: r.type,
+    dirty: !!r.dirty,
+    // 以下三项对应的 GL 包装代码已删除，现恒为 null/false（历史遗留，保留键名）
+    wrapped: !!(gl && gl.__transparentClearInstalled),
+    clearCalls: gl ? gl.__transparentClearCalls : null,
+    clearBufferCalls: gl && gl.__clearBufferCalls ? { ...gl.__clearBufferCalls } : null,
+    wrappedChained: gl ? !!gl.__transparentClearChained : null,
+  };
+}
+
+/** 逐项读一个 GL 参数（读失败返回 null，绝不抛） */
+function glParam(gl, name, map) {
+  try {
+    const v = gl.getParameter(gl[name]);
+    return map ? map(v) : v;
+  } catch {
+    return null;
+  }
+}
+
+/** GL 状态里与"清屏/裁剪"相关的项（每项都可能抛，逐项兜住） */
+function readGlState(gl) {
+  if (!gl) return {};
+  const out = {};
+  try { out.contextLost = gl.isContextLost(); } catch { out.contextLost = null; }
+  try { out.scissorTest = gl.isEnabled(gl.SCISSOR_TEST); } catch { out.scissorTest = null; }
+  out.scissorBox = glParam(gl, 'SCISSOR_BOX', (v) => (v ? Array.from(v) : null));
+  out.clearColor = glParam(gl, 'COLOR_CLEAR_VALUE', (v) => (v ? Array.from(v) : null));
+  // 最可疑的一项：alpha 写入被关掉时，清什么都保持旧 alpha ⇒ 出现"这块透明那块不透明"
+  out.colorWriteMask = glParam(gl, 'COLOR_WRITEMASK', (v) => (v ? Array.from(v) : null));
+  out.samples = glParam(gl, 'SAMPLES');
+  try {
+    const a = gl.getContextAttributes ? gl.getContextAttributes() : null;
+    out.contextAlpha = a ? a.alpha : null;
+    out.antialias = a ? a.antialias : null;
+  } catch { /* 忽略 */ }
+  return out;
+}
+
+/**
+ * 创建只读诊断模块。
+ * @param {object} ctx 运行时上下文
+ * @returns {{readCanvasPixels:Function, collectCmp:Function, rendererInfo:Function, rendererSize:Function}}
+ */
+export function createProbe(ctx) {
+  const { st, surfaceSize } = ctx;
+
+  async function readCanvasPixels(points = []) {
+    const app = st.app;
+    if (!app || !app.renderer) return null;
+    const gl = app.renderer.gl;
+    if (!gl) return null;
+    const res = app.renderer.resolution || 1;
+    const h = app.renderer.height;
+    const buf = new Uint8Array(4);
+    const out = [];
+    await new Promise((r) => requestAnimationFrame(() => r()));
+    try { app.renderer.render(app.stage); } catch { /* 忽略 */ }
+    for (const p of points) {
+      const px = Math.round(p[0] * res);
+      const py = Math.round(h - p[1] * res);
+      try {
+        gl.readPixels(px, py, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, buf);
+        out.push({ x: p[0], y: p[1], rgba: [buf[0], buf[1], buf[2], buf[3]] });
+      } catch (e) { out.push({ x: p[0], y: p[1], err: String(e && e.message).slice(0, 40) }); }
+    }
+    return out;
+  }
+
+  function collectCmp(tag) {
+    const rootEl = document.getElementById('stage');
+    return collectLive2DModelCmp({
+      app: st.app,
+      model: st.model,
+      internal: st.model && st.model.internalModel ? st.model.internalModel : null,
+      size: surfaceSize(),
+      dpr: ctx.handleRef ? ctx.handleRef.dpr : null,
+      meta: st.meta,
+      modelId: st.modelId,
+      zoomRatio: st.zoomRatio,
+      stageMode: rootEl ? rootEl.getAttribute('data-stage-mode') : null,
+      tag: String(tag || 'default'),
+    });
+  }
+
+  function rendererInfo() {
+    const app = st.app;
+    if (!app || !app.renderer) return null;
+    const r = app.renderer;
+    const gl = r.gl || null;
+    return { ...readClearConfig(r, gl), ...readGlState(gl) };
+  }
+
+  function rendererSize() {
+    if (!st.app || !st.app.renderer) return null;
+    const r = st.app.renderer;
+    const size = surfaceSize() || { width: 0, height: 0 };
+    return { w: r.width, h: r.height, res: r.resolution || 1, cssW: size.width, cssH: size.height };
+  }
+
+  return { readCanvasPixels, collectCmp, rendererInfo, rendererSize };
+}

package/src/web/live2d/release.js

@@ -0,0 +1,66 @@
+// live2d/release.js —— Live2D 面的统一资源释放（unmount 与 dispose 共用）
+//
+// 为什么单独成模块：这段是「契约 §五-7（unmount/dispose 不得遗留自建 GL 资源）」的落地实现，
+//   也是曾经出过 bug 的地方（PIXI 的 destroy(true) 会摘掉 canvas 只留容器，下游按容器复用 ⇒
+//   渲染到不在 DOM 的游离画布上、页面全白而 stats 与像素采样都正常）。
+//   抽出来之后可以用 `node --test` 做静态回归（最小 DOM 垫片即可），不必每次都开浏览器验。
+//
+// 释放清单（顺序有意义：先停诊断 → 藏容器 → 销毁 app → 移除容器 → 复位状态）：
+//   ① 诊断 HUD 句柄停掉（它会定时取数据，留着会读到已销毁的 app）
+//   ② 覆盖层隐藏（视觉上立刻消失，避免销毁过程中的中间帧露出来）
+//   ③ PIXI app.destroy(true) —— 释放 WebGL 上下文与整棵 display tree（自建 GL 资源的唯一持有者）
+//   ④ 移除 #live2d-overlay 容器（不做"保留容器以便快速切回"：那个中间态正是上面那个 bug 的来源）
+//   ⑤ 状态复位（否则 isActive()/debug() 继续报告"还有模型在显示"）
+
+export const OVERLAY_ID = 'live2d-overlay';
+
+/**
+ * 释放 Live2D 面持有的全部资源与状态。
+ * @param {{
+ *   st: object,                       // live2d 舞台状态（app/model/modelId/meta/motionMap/vfsStats/active/overlay/libsReady）
+ *   note?: Function,                  // 日志通道
+ *   stopDiag?: Function|null,         // 停诊断 HUD（可选）
+ *   doc?: object,                     // 文档对象（默认 globalThis.document，便于测试注入）
+ * }} opts
+ * @returns {boolean} 是否真的释放了什么（用于幂等与日志判断）
+ */
+export function releaseLive2DResources({ st, note, stopDiag, doc } = {}) {
+  const d = doc || (typeof document !== 'undefined' ? document : null);
+  if (!st) return false;
+  const hadApp = !!st.app;
+  const hadOverlay = !!(d && d.getElementById && d.getElementById(OVERLAY_ID));
+
+  try { if (typeof stopDiag === 'function') stopDiag(); } catch { /* 停诊断失败不阻塞释放 */ }
+  try { if (st.overlay && typeof st.overlay.style === 'object') st.overlay.style.display = 'none'; } catch { /* 忽略 */ }
+  // **app 常驻**：不 destroy（`destroy(true)` 的 removeView 会摘掉 canvas，那才是孤儿上下文的来源）。
+  //   每次 spine↔live2d 切换都 `new PIXI.Application()` 会新建 1 个匿名探测上下文且永不释放，
+  //   累积到浏览器上限（~16）就丢最旧 ⇒ 画布黑（实测：来回切 15 次即到顶）。
+  //   所以释放只做三件事：停渲染循环、释放纹理（GPU 内存大头）、隐藏覆盖层；app/canvas/context 保留，
+  //   下次切回来直接复用（只重建纹理，比 new Application 便宜得多）。
+  if (st.app) {
+    try { if (st.model) { st.app.stage.removeChild(st.model); } } catch { /* 忽略 */ }
+    try { if (st.model) st.model.destroy({ children: true, texture: true, baseTexture: true }); } catch { /* 忽略 */ }
+    try { if (typeof st.app.stop === 'function') st.app.stop(); } catch { /* 忽略 */ }
+    // 释放纹理缓存（PIXI 的内存大头）；拿不到就跳过，不影响正确性
+    try {
+      const r = st.app.renderer;
+      if (r && r.textureGC && typeof r.textureGC.run === 'function') r.textureGC.run();
+    } catch { /* 忽略 */ }
+    try { if (st.overlay && typeof st.overlay.style === 'object') st.overlay.style.display = 'none'; } catch { /* 忽略 */ }
+  }
+  // 覆盖层 DOM 保留（app 常驻 ⇒ 它的 canvas 还得留着，摘掉就是旧坑"容器在、canvas 不在"）
+  st.overlay = (d && d.getElementById) ? (d.getElementById(OVERLAY_ID) || st.overlay) : st.overlay;
+  st.libsReady = null;
+  st.model = null;
+  st.modelId = null;
+  st.meta = null;
+  st.motionMap = new Map();
+  st.vfsStats = null;
+  // 与 model.js 的 publishVfsStats 对称：释放后 dataset 里的读数必须消失，否则下一次排查会读到旧值
+  try { if (d && d.documentElement) delete d.documentElement.dataset.vfsStats; } catch { /* 忽略 */ }
+  st.active = false;
+
+  const did = hadApp || hadOverlay;
+  if (did && typeof note === 'function') note('Live2D 已释放（纹理释放、渲染停止、覆盖层隐藏；app 常驻复用）');
+  return did;
+}