modelstage 0.0.0-stage → 0.5.28

package/src/web/infra/document.js

@@ -0,0 +1,269 @@
+// infra/document.js —— Model Document 的组装层（Assets 层，document/v1）
+//
+// 职责（契约 Document契约 §一/§二）：把 catalog entry 变成 **ready 的 Document**——
+//   · 资源地址一律先经 VirtualFS 解析（命中用虚拟地址、未命中回落原 URL，与 M3 的两套前置同一口径）
+//   · 取字节/读定义也在这里发生（这是 Assets 层的工作）；渲染器只拿"资源在哪 + 校验结果"
+//   · 失败不产半成品：state='error' + warnings 写明可读原因，绝不进入渲染层
+//
+// 为什么取资源必须在这一层：渲染器目录（spine/、live2d/、render/）里不允许出现模型资源的
+//   fetch —— 一旦渲染器自己取资源，就会出现"取失败分支"在渲染层里长出来（契约 D4）。
+//   把这件事收到这里，渲染器只消费地址，取不到的情况在进入渲染层之前就已经变成 error 文档。
+//
+// 说明（M4 阶段的能力边界，已在交付说明里如实登记）：
+//   · skeleton.bones / slots 需要 Spine 运行时解析 .skel 才能得到，属引擎职责；
+//     本轮只保证**形状齐全**（空数组），animations/skins 能拿到的（Live2D 定义、Spine 条目元数据）照填。
+//   · Document 不注册 VFS 前缀（注册由提供者负责），因此 dispose() 只撤销"本层自己注册过的"前缀；
+//     当前没有这种前缀 ⇒ dispose 是幂等空操作，绝不会和别处的 revoke 撞车（无双重撤销）。
+import { getSharedVirtualFS } from './vfs.js';
+// 内容类型是否受支持 = 查渲染面元数据表（唯一真相在 render/surfaces.js）
+import { isKnownKind } from '../render/surfaces.js';
+// 模型文件必须走带重试的 fetch：几十个并发裸 fetch 遇上 keep-alive race 会直接 Failed to fetch，
+//   一个文件失败整个模型就画不出来（现场表现：Spine 空白、资源包正常——后者走 blob 不过网络）。
+import { fetchWithRetry } from './api.js';
+
+/** 默认取共享 VFS 实例（与渲染器、验收脚本同一个） */
+function pickVfs(deps) {
+  if (deps && deps.vfs) return deps.vfs;
+  try {
+    return getSharedVirtualFS();
+  } catch {
+    return null;
+  }
+}
+
+/** 资源地址解析：命中用虚拟地址，未命中回落原 URL；异常一律回落 */
+function resolveUrl(vfs, url) {
+  if (!url) return null;
+  try {
+    const hit = vfs && typeof vfs.resolve === 'function' ? vfs.resolve(url) : null;
+    return hit || url;
+  } catch {
+    return url;
+  }
+}
+
+/** 读一个资源的字节；失败只记 warning，不抛（由调用方汇总成 error 文档） */
+async function readBytes(url, label, warnings) {
+  try {
+    // 带重试：网络错误 / 5xx 会退避重试（4xx 不重试）
+    const res = await fetchWithRetry(url, { timeoutMs: 8000, label: 'model-bytes' });
+    if (!res || !res.ok) {
+      warnings.push(`${label} 读取失败：HTTP ${(res && res.status) || '?'}（${url}）`);
+      return null;
+    }
+    const buf = await res.arrayBuffer();
+    if (!buf || !buf.byteLength) {
+      warnings.push(`${label} 内容为空（${url}）`);
+      return null;
+    }
+    return buf;
+  } catch (e) {
+    warnings.push(`${label} 读取失败：${(e && e.message) || e}（${url}）`);
+    return null;
+  }
+}
+
+/** 判定内容类型：显式 kind 优先，其次按条目形状推断 */
+function detectKind(entry) {
+  if (!entry) return null;
+  // 显式 kind 只认**受支持的渲染面**（查表，不写死枚举）。
+  //   原先这里是 `kind === 'spine' || kind === 'live2d'` —— 加第三个面时它会把 3d 判成 null，
+  //   而 null 在 buildDocument 里意味着 state='error'，于是新面永远进不了渲染层且不报"不支持"。
+  if (isKnownKind(entry.kind)) return entry.kind;
+  if (entry.skeletonFile) return 'spine';
+  if (entry.modelUrl || (entry.entry && entry.entry.url)) return 'live2d';
+  return null;
+}
+
+/** 组装公共只读字段（kind/source/provider/根信息/state/warnings 等） */
+function baseDocument(entry, kind, vfs) {
+  return {
+    // ── 只读（契约 §一）
+    id: entry.id || null,
+    kind,
+    source: entry.source || (entry.provider ? 'bundle' : 'files'),
+    provider: entry.provider || null,
+    rootId: entry.rootId || (entry.root && entry.root.id) || null,
+    rootName: entry.rootName || (entry.root && entry.root.name) || null,
+    name: entry.name || entry.id || null,
+    srcDir: entry.srcDir || entry.dir || null,
+    assets: { entry: null, textures: [], atlas: null },
+    skeleton: { bones: [], slots: [], animations: [], skins: [] },
+    meta: { version: entry.version || null, bbox: null, motions: null, expressions: null, motionDurations: {}, extras: {} },
+    state: 'ready',
+    warnings: [],
+    // ── 可写（契约 §六：只留形状，加编辑器时实现）
+    params: {},
+    dirty: false,
+    history: { undo() {}, redo() {} },
+  };
+}
+
+/** Spine：骨架 / atlas / 贴图页三件套（地址已解析，字节一并带上供引擎消费） */
+async function buildSpineAssets(doc, entry, vfs) {
+  const warn = doc.warnings;
+  const skelUrl = resolveUrl(vfs, entry.skeletonFile && entry.skeletonFile.url);
+  const atlasUrl = resolveUrl(vfs, entry.atlasFile && entry.atlasFile.url);
+  const texEntries = Array.isArray(entry.textureFiles) ? entry.textureFiles : [];
+  if (!skelUrl) warn.push('缺少骨架地址（skeletonFile.url）');
+  if (!atlasUrl) warn.push('缺少 atlas 地址（atlasFile.url）');
+  if (!texEntries.length) warn.push('缺少贴图页（textureFiles 为空）');
+
+  const [skelBytes, atlasBytes] = await Promise.all([
+    skelUrl ? readBytes(skelUrl, '骨架', warn) : null,
+    atlasUrl ? readBytes(atlasUrl, 'atlas', warn) : null,
+  ]);
+  doc.assets.entry = { role: 'skeleton', name: (entry.skeletonFile && entry.skeletonFile.name) || '', url: skelUrl, bytes: skelBytes };
+  doc.assets.atlas = { role: 'atlas', name: (entry.atlasFile && entry.atlasFile.name) || '', url: atlasUrl, bytes: atlasBytes };
+
+  for (const tex of texEntries) {
+    const url = resolveUrl(vfs, tex && tex.url);
+    if (!url) { warn.push(`贴图缺地址：${(tex && tex.name) || '?'}`); continue; }
+    const bytes = await readBytes(url, `贴图 ${tex.name || ''}`, warn);
+    doc.assets.textures.push({ role: 'texture', name: (tex && tex.name) || '', url, bytes });
+  }
+  // 动画/皮肤快照：条目里能给的先填（引擎返回的更权威，但 Document 只读部分不应该等运行时）
+  const animations = Array.isArray(entry.animations) ? entry.animations : [];
+  doc.skeleton.animations = animations.map((a) => (typeof a === 'string' ? a : (a && (a.name || a.Name)) || '')).filter(Boolean);
+  doc.skeleton.skins = Array.isArray(entry.skins) ? entry.skins.slice() : [];
+  doc.meta.extras = { atlasPma: entry.atlasPma === undefined ? null : entry.atlasPma };
+  return doc;
+}
+
+/** 动作时长缓存：定义地址 → { 动作文件 → 秒数 }（跨多次组装复用） */
+const motionDurationCache = new Map();
+
+/**
+ * 预取 Live2D 每个动作文件的时长（Meta.Duration）。
+ *
+ * 为什么放在 Assets 层：时长要读动作文件，而"取模型资源"是 Assets 层的职责——
+ *   渲染器里不允许 fetch（契约 D4）。之前这套逻辑在 live2d/bridge 里，收到本层后
+ *   渲染器只读 document.meta.motionDurations，动作时长不会因为"没人预取"而整片消失。
+ *
+ * 键用**动作文件相对路径**（model3.json 里的 File 原值，如 `motions/idle.motion3.json`）：
+ *   动作标签（`group / 文件名`）的拼法只有一处实现（live2d/model.js 的 motionLabel），
+ *   这里再写一份必然漂移；桥接层拿标签对应的文件来查即可。
+ *
+ * 取不到就**不写这个键**（不填 0 冒充），前端自然显示为"无时长"。
+ * @param {object} doc Document（就地写 doc.meta.motionDurations）
+ * @param {object} ref model3.json 的 FileReferences
+ * @param {string} baseRef **解析前**的模型定义地址（vfs:// 或 http://）——
+ *   动作文件的相对路径必须以它为基址拼接：拿解析后的 blob 当基址会拼出
+ *   `blob:…/motions/x.motion3.json` 这种永不命中的地址（资源包时长整片 null 的真因）。
+ * @param {string} entryUrl 定义文件地址（用于把相对 File 拼成可读地址）
+ * @param {object} vfs VirtualFS
+ */
+async function fillMotionDurations(doc, ref, baseRef, vfs) {
+  // 同一模型反复组装（切模型来回点、测试反复装载）时不必重复预取：按定义地址缓存一份。
+  //   14 个动作文件就是 14 次请求，重复预取既慢又给测试增加时序抖动。
+  const cached = motionDurationCache.get(baseRef);
+  if (cached) { doc.meta.motionDurations = { ...cached }; return; }
+  const base = String(baseRef || '').replace(/[^/]*$/, '');
+  const files = [];
+  for (const group of Object.keys(ref.Motions || {})) {
+    for (const mo of (ref.Motions[group] || [])) {
+      const file = mo && (mo.File || mo.Name);
+      if (file && !files.includes(file)) files.push(file);
+    }
+  }
+  const out = {};
+  const jobs = files.map(async (file) => {
+    const abs = /^[a-z][a-z0-9+.-]*:/i.test(file) || file.startsWith('/') ? file : `${base}${file}`;
+    const url = resolveUrl(vfs, abs);
+    try {
+      const res = await fetchWithRetry(url, { timeoutMs: 8000, label: 'motion3' });
+      if (!res || !res.ok) return;
+      const json = await res.json();
+      const d = Number(json && json.Meta && json.Meta.Duration);
+      if (Number.isFinite(d) && d > 0) out[file] = d;
+    } catch { /* 单个动作读不到就跳过，不影响其它动作与整体装载 */ }
+  });
+  await Promise.all(jobs);
+  doc.meta.motionDurations = out;
+  motionDurationCache.set(baseRef, out);
+}
+
+/** Live2D：入口 model3.json 定义（地址已解析；内部引用由 live2d/vfs-settings 在装载时解析） */
+async function buildLive2dAssets(doc, entry, vfs) {
+  const warn = doc.warnings;
+  const raw = (entry.entry && entry.entry.url) || entry.modelUrl || null;
+  const url = resolveUrl(vfs, raw);
+  if (!url) { warn.push('缺少模型定义地址（entry.url / modelUrl）'); return doc; }
+  // ref 保留**解析前**的原始地址：Live2D 内部相对引用要靠它推出 vfs 前缀
+  //   （url 是解析后的 blob，blob 不能当基址；vfs-settings 需要 vfs:// 形态才能把
+  //    motions/x.motion3.json 这类引用映射回已注册的前缀）。
+  doc.assets.entry = { role: 'definition', name: raw.split('/').pop() || '', url, ref: raw, bytes: null };
+  try {
+    const res = await fetchWithRetry(url, { timeoutMs: 8000, label: 'model-def' });
+    if (!res || !res.ok) {
+      warn.push(`模型定义读取失败：HTTP ${(res && res.status) || '?'}（${url}）`);
+      return doc;
+    }
+    const json = await res.json();
+    const ref = (json && json.FileReferences) || {};
+    const motions = ref.Motions || {};
+    doc.meta.version = json && json.Version ? Number(json.Version) : doc.meta.version;
+    // meta.motions 必须是**完整映射** { 组: [{ File, ... }] }，不是组名数组：
+    //   渲染层要凭 File 去查预取时长表（live2d/bridge.js 的 motionFileOf），
+    //   只留组名的话 duration 一律取不到 ⇒ 动作列表时长整片 null（冷缓存下 34/34 全空）。
+    doc.meta.motions = motions;
+    doc.meta.expressions = (ref.Expressions || []).map((e) => (e && e.Name) || '');
+    doc.skeleton.animations = Object.keys(motions);
+    doc.meta.extras = { moc: ref.Moc || null, textures: (ref.Textures || []).slice(), json };
+    // 传 raw（解析前地址）而不是 url（blob）：相对路径要相对"来源"拼，不是相对 blob
+    await fillMotionDurations(doc, ref, raw, vfs);
+  } catch (e) {
+    warn.push(`模型定义解析失败：${(e && e.message) || e}（${url}）`);
+  }
+  return doc;
+}
+
+/** 给 Document 装上幂等的 dispose（契约 D2） */
+function attachDispose(doc, vfs) {
+  let disposed = false;
+  // 本层不注册前缀（注册是提供者的职责）⇒ 通常没有要撤的前缀；
+  //   若将来本层自己注册，把前缀记在 doc._ownedPrefix 上，这里会撤且只撤一次。
+  doc.dispose = function dispose() {
+    if (disposed) return false;
+    disposed = true;
+    const prefix = doc._ownedPrefix;
+    if (prefix && vfs && typeof vfs.revoke === 'function') {
+      try { vfs.revoke(prefix); } catch { /* 撤销失败不影响幂等语义 */ }
+    }
+    return true;
+  };
+  return doc;
+}
+
+/**
+ * 把 catalog entry 变成 ready/error 的 Document。
+ * @param {object} entry catalog 条目（可能是模型条目，也可能已带 kind）
+ * @param {{vfs?: object, log?: Function}} [deps]
+ * @returns {Promise<object>} Document（state 只会是 'ready' 或 'error'）
+ */
+export async function buildDocument(entry, deps = {}) {
+  const vfs = pickVfs(deps);
+  const kind = detectKind(entry);
+  if (!entry || !kind) {
+    const bad = baseDocument(entry || {}, null, vfs);
+    bad.state = 'error';
+    bad.warnings.push(entry ? `无法判定内容类型（既没有 skeletonFile 也没有 entry.url/modelUrl）` : '缺少 catalog 条目');
+    return attachDispose(bad, vfs);
+  }
+  const doc = baseDocument(entry, kind, vfs);
+  try {
+    // 组装分支**显式列全 + 未知抛错**，不再用 `if spine else live2d` 的二分。
+    //   二分写法隐含"只有两个面"：加第三个面时它会被当 live2d 组装，产出一份字段错位的 Document
+    //   （不报错、只是后面渲染乱），比直接失败难排得多。
+    if (kind === 'spine') await buildSpineAssets(doc, entry, vfs);
+    else if (kind === 'live2d') await buildLive2dAssets(doc, entry, vfs);
+    else throw new Error(`不支持的渲染面「${kind}」：组装分支未在 render/surfaces.js 登记`);
+  } catch (e) {
+    doc.warnings.push(`组装异常：${(e && e.message) || e}`);
+  }
+  // 任何 warning 都意味着"资源不全" ⇒ 不进入渲染层（契约 §二 硬规则 1）
+  if (doc.warnings.length) doc.state = 'error';
+  return attachDispose(doc, vfs);
+}
+
+export default buildDocument;

package/src/web/infra/dom.js

@@ -0,0 +1,31 @@
+// infra/dom.js —— 最小 DOM 工厂（跨模块公共层）
+//
+// 本文件是 `el()` 的**唯一实现**。panel/dom.js 与 roster/rows.js 只是 re-export ——
+//   **不要在任何地方再新增 el 的实现**（历史上曾有三份各自漂移：panel / roster / debug）。
+//   判据是"函数体只有一份"，不是"文本只出现一次"：re-export 不算第二份实现。
+//
+// 为什么收在 infra/：panel / roster / debug 三个功能层都要建节点，
+//   而这个工厂与业务无关；放在任何单一功能层都会让另外两层反向依赖它。
+
+/**
+ * 建元素：tag + class + 文本。
+ *
+ * 三处判空的语义（改动前历史实现一致，逐条都是刻意的，别"简化"）：
+ *   · className 用 falsy 判空 ⇒ 传 '' / undefined / null / 0 都**不设 class 属性**
+ *     （不是设成空字符串 —— 那会在 outerHTML 里留下 `class=""`）
+ *   · text 用 `!== undefined && !== null` 判空 ⇒ **`0` 与 `''` 会被写入**
+ *     （数字 0 是常见内容，用 falsy 判空会把 0 吞掉）
+ *   · text 一律 `String(...)` 后再写入 ⇒ 传对象得到 "[object Object]"，
+ *     但调用方实际传的通常是对象索引取值后的字符串（见 panel/view.js）
+ *
+ * @param {string} tag 标签名
+ * @param {string} [className] 类名（可空）
+ * @param {string|number} [text] 文本内容（0 与空串都会写入）
+ * @returns {HTMLElement}
+ */
+export function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined && text !== null) node.textContent = String(text);
+  return node;
+}

package/src/web/infra/events.mjs

@@ -0,0 +1,27 @@
+// src/web/infra/events.mjs —— 宿主对外事件的**协议常量**（唯一来源）
+//
+// 为什么要单独一个文件：这些事件名原先以字符串字面量散落在多个文件里
+//   （派发点与监听点各写一遍），任何批量重命名都可能顺手命中它 ——
+//   真发生过：`spineviewer:plugins-loaded` 被批量替换成 `spineviewer:plugins-ctx.loaded`，
+//   于是"卸载后面板不重建 / document.files 就绪后不重绘"，不报错、只静默失效。
+//   收成常量 + 一条"不许再出现字面量"的单测（test/events-const.test.mjs）后，
+//   改坏会当场红，而不是等到用户发现功能没反应。
+//
+// 使用口径：
+//   · 派发：window.dispatchEvent(new CustomEvent(EVENTS.PLUGINS_LOADED, { detail }))
+//   · 监听：window.addEventListener(EVENTS.PLUGINS_LOADED, handler)
+//   · **不要**在任何业务文件里再写 `'spineviewer:...'` 字面量（单测会拦）
+//
+// 加新事件：在这里登记一个键，然后派发/监听两端都用常量；事件名本身是外部契约
+//   （面板/插件可能按名字监听），改动要当成破坏性变更对待。
+
+export const EVENTS = Object.freeze({
+  /** 插件装载/卸载完成（面板侧据此重建；detail: { reason? , unloaded? }） */
+  PLUGINS_LOADED: 'spineviewer:plugins-loaded',
+  /** 单个插件注册成功（detail: { id }） */
+  PLUGIN_REGISTERED: 'spineviewer:plugin-registered',
+  /** 插件向宿主上报的通知（detail: { kind, msg }） */
+  NOTIFY: 'spineviewer:notify',
+});
+
+export default EVENTS;

package/src/web/infra/log.js

@@ -0,0 +1,153 @@
+// infra/log.js —— 统一的日志工厂（调试日志整理的第 ① 步）
+//
+// 解决的问题：现在页面里同时存在四条各写各的通路（diag.push / stageStatus / diagEvent / console 镜像），
+//   同一件事可能从两条路进来，级别口径也不一致。这里只定义"一条日志记录长什么样 + 怎么写"，
+//   **不接管任何现有调用点**：现有通路改由适配层转调（第 ② 步做），因此本模块可以独立上线、独立测试。
+//
+// 四档的分界不是"严重程度"，而是"给谁看"：
+//   debug  给机器：事件名 + 结构化 detail，字段名稳定可解析（断言/回归对比靠它）
+//   info   给人和 AI：一句人话，正常流程（设置回显、操作确认、进度）
+//   warn   给人和 AI：人话 + 为什么会这样（预期内的失败、可降级）
+//   error  给人和 AI：人话 + 可排查上下文（错误对象、输入）
+//
+// 记录形状（四档完全一致，只有 level 不同）：
+//   { at, level, tag, event?, msg?, detail?, src }
+//   可选字段：debug 必须给 event；info/warn/error 必须给 msg。detail 可选，但给了就保持结构化。
+
+/** 允许的级别（顺序即严重度递增，面板按此排序） */
+export const LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
+
+/** 允许的来源：app=本应用主动打的；console=包装原生 console 抓到的（可能混第三方）；server=服务端转发 */
+export const LOG_SOURCES = ['app', 'console', 'server'];
+
+/** 内存里保留多少条（够面板展示与测试取用，又不至于无限涨） */
+export const LOG_LIMIT = 500;
+
+/** 环形缓冲：最近若干条记录（面板/测试/自检都从这里取，避免各自再存一份） */
+const buffer = [];
+/** 订阅者：每条新记录都会同步推给他们（面板渲染、测试断言） */
+const sinks = new Set();
+
+/**
+ * 把 detail 归一成"结构化但可序列化"的值。
+ *
+ * 关键点：**对象必须原样保留**，绝不能 String() —— 一旦变成 "[object Object]"，机器就没法解析了
+ *   （这也是 debug 级存在的唯一理由）。Error 不是普通可枚举对象，单独拆成可读字段。
+ * @param {unknown} detail
+ * @returns {object|undefined} 归一后的 detail；没给就返回 undefined
+ */
+function normalizeDetail(detail) {
+  if (detail === undefined || detail === null) return undefined;
+  if (detail instanceof Error) {
+    return { name: detail.name, message: detail.message, stack: detail.stack || '' };
+  }
+  if (typeof detail === 'object') return detail;      // 保留结构（数组/普通对象都原样带走）
+  return { value: detail };                          // 原始值包一层，保证 detail 永远是对象
+}
+
+/**
+ * 组装一条记录（四档共用，保证形状一致）。
+ * @param {string} level 级别（必须在 LOG_LEVELS 内）
+ * @param {string} tag 模块标签
+ * @param {object} fields { event?, msg?, detail? }
+ * @param {'app'|'console'|'server'} src 来源
+ * @returns {object} 统一形状的记录
+ */
+function makeRecord(level, tag, fields, src) {
+  const record = { at: Date.now(), level, tag, src };
+  if (fields.event) record.event = String(fields.event);
+  if (fields.msg !== undefined && fields.msg !== null && fields.msg !== '') record.msg = String(fields.msg);
+  const detail = normalizeDetail(fields.detail);
+  if (detail !== undefined) record.detail = detail;
+  return record;
+}
+
+/** 写入一条记录：进环形缓冲 + 推给订阅者（订阅者异常不能反过来影响业务） */
+function push(record) {
+  buffer.push(record);
+  if (buffer.length > LOG_LIMIT) buffer.splice(0, buffer.length - LOG_LIMIT);
+  for (const sink of sinks) {
+    try { sink(record); } catch { /* 消费方自己出错不该污染日志通路 */ }
+  }
+  return record;
+}
+
+/**
+ * 创建一个带模块标签的 logger。
+ *
+ * @param {string} tag 模块标签（进每条记录，便于按模块过滤；如 'unpack' / 'panel' / 'stage'）
+ * @param {{src?: 'app'|'console'|'server'}} [opts] src 缺省为 'app'
+ * @returns {{
+ *   debug: (event: string, detail?: object) => object,
+ *   info: (msg: string, detail?: object) => object,
+ *   warn: (msg: string, detail?: object) => object,
+ *   error: (msg: string, detail?: object) => object,
+ * }}
+ */
+export function createLogger(tag, opts) {
+  if (typeof tag !== 'string' || !tag) throw new TypeError('createLogger: tag 必须是非空字符串');
+  const src = (opts && opts.src) || 'app';
+  if (!LOG_SOURCES.includes(src)) {
+    throw new TypeError(`createLogger: src 必须是 ${LOG_SOURCES.join('/')} 之一（收到 ${String(src)}）`);
+  }
+  const name = String(tag);
+
+  return {
+    /**
+     * 机器友好日志：**必须给事件名**（点分命名，如 'unpack.pair'），detail 用固定键。
+     * 只给 msg 不给 event 会直接抛错——否则它就退化成了一条"人话日志"，
+     *   而 debug 级存在的唯一理由就是"字段名稳定、可被机器解析"。
+     */
+    debug(event, detail) {
+      if (typeof event !== 'string' || !event) {
+        throw new TypeError('log.debug: 必须给事件名（点分命名，如 "unpack.pair"），不能只给 msg');
+      }
+      if (!/^[a-z][\w-]*(\.[\w-]+)+$/i.test(event)) {
+        throw new TypeError(`log.debug: 事件名应点分命名（收到 "${event}"）`);
+      }
+      return push(makeRecord('debug', name, { event, detail }, src));
+    },
+    /** 一句人话，正常流程（设置回显 / 操作确认 / 进度） */
+    info(msg, detail) {
+      if (typeof msg !== 'string' || !msg) throw new TypeError('log.info: 必须给一句人话 msg');
+      return push(makeRecord('info', name, { msg, detail }, src));
+    },
+    /** 人话 + 为什么会这样（预期内的失败、可降级的情况） */
+    warn(msg, detail) {
+      if (typeof msg !== 'string' || !msg) throw new TypeError('log.warn: 必须给一句人话 msg');
+      return push(makeRecord('warn', name, { msg, detail }, src));
+    },
+    /** 人话 + 可排查上下文（非预期失败：错误对象、输入、状态） */
+    error(msg, detail) {
+      if (typeof msg !== 'string' || !msg) throw new TypeError('log.error: 必须给一句人话 msg');
+      return push(makeRecord('error', name, { msg, detail }, src));
+    },
+  };
+}
+
+/**
+ * 订阅新记录（面板渲染、测试断言用）。
+ * @param {(record: object) => void} sink
+ * @returns {() => void} 取消订阅
+ */
+export function subscribe(sink) {
+  if (typeof sink !== 'function') throw new TypeError('subscribe: 必须传函数');
+  sinks.add(sink);
+  return () => { sinks.delete(sink); };
+}
+
+/**
+ * 取最近的若干条记录（不传就全取，受 LOG_LIMIT 限制）。
+ * @param {number} [n]
+ * @returns {object[]} 记录的浅拷贝数组（外部改它不影响内部缓冲）
+ */
+export function recent(n) {
+  if (n === undefined || n === null) return buffer.slice();
+  const count = Math.max(0, Math.floor(Number(n) || 0));
+  return count ? buffer.slice(-count) : [];
+}
+
+/** 清空缓冲区（只清日志，不动订阅者；测试与"清空日志"按钮都用它） */
+export function clearLogs() {
+  buffer.length = 0;
+}

package/src/web/infra/mem-stats.js

@@ -0,0 +1,112 @@
+// infra/mem-stats.js —— 资源与上下文计数（**只读观测**，不改变任何清理/渲染逻辑）
+//
+// 为什么需要它：现场症状是"加载资源包/切 Live2D 之后画布黑 + 网络失败"，
+//   而 `stage.stats().contexts` 只是 `gl ? 1 : 0`（恒 0/1），**验证不了泄漏**。
+//   浏览器对 WebGL 上下文有硬上限（约 16 个），超了会丢弃最旧的 ⇒ 画布黑。
+//   所以这里自己维护"累计创建 / 已释放 / 仍存活"三档计数，把"累积"变成可读数字。
+//
+// 实现方式：包装 HTMLCanvasElement.prototype.getContext 与 WEBGL_lose_context.loseContext，
+//   只做计数，不改变返回值与行为（幂等安装，重复调用安全）。
+
+const st = {
+  installed: false,
+  created: 0,      // 累计创建成功的 webgl/webgl2 上下文数（单调递增，泄漏会线性涨）
+  lost: 0,         // 观测到的 loseContext 次数
+  byType: {},      // 'webgl' / 'webgl2' → 次数
+  contexts: [],    // 每条 {type, at, connected}（at=创建时刻，connected=canvas 是否仍在文档里）
+};
+
+/** 安装计数钩子（幂等） */
+export function installMemStats() {
+  if (st.installed || typeof HTMLCanvasElement === 'undefined') return;
+  st.installed = true;
+  const proto = HTMLCanvasElement.prototype;
+  const orig = proto.getContext;
+  proto.getContext = function patched(type, ...rest) {
+    const ctx = orig.call(this, type, ...rest);
+    try {
+      if (ctx && /webgl2?$/i.test(String(type))) {
+        // ⚠ 只统计**新创建**的上下文：同一 canvas 重复 getContext 会返回同一个上下文，
+        //   若按调用次数累加就会把"特征探测/像素读取"误记成泄漏（我第一版就错了，差点误判根因）。
+        const already = st.contexts.find((r) => r.canvas === this && r.type === String(type));
+        if (already) return ctx;
+        st.created += 1;
+        st.byType[type] = (st.byType[type] || 0) + 1;
+        const rec = { type: String(type), at: Date.now(), canvas: this,
+          // 记录身份特征，便于指认"这些 canvas 是谁建的"
+          id: this.id || '', cls: (this.className && String(this.className).slice(0, 40)) || '',
+          w: this.width, h: this.height };
+        st.contexts.push(rec);
+        // 包装 loseContext：真被释放了就记一笔（用于算"仍存活"）
+        const lose = ctx.getExtension && ctx.getExtension('WEBGL_lose_context');
+        if (lose && typeof lose.loseContext === 'function' && !lose.__counted) {
+          const origLose = lose.loseContext.bind(lose);
+          try {
+            lose.loseContext = () => { st.lost += 1; rec.lost = true; return origLose(); };
+            lose.__counted = true;
+          } catch { /* 只读扩展对象：忽略 */ }
+        }
+      }
+    } catch { /* 计数失败不影响页面 */ }
+    return ctx;
+  };
+}
+
+/**
+ * 读当前计数。
+ * @returns {{glContexts: number, glContextsLive: number, glContextsLost: number, byType: object,
+ *   canvases: number, canvasesWithGl: number, orphanGl: number, jsHeapMB: number|null}}
+ *   glContexts   累计创建数（泄漏判据：随切换线性增长）
+ *   glContextsLive 创建 − 已释放（近似"同时存活"数）
+ *   orphanGl     上下文仍在、但 canvas 已脱离文档（"旧 canvas 没删"）
+ *   canvases     DOM 里的 canvas 数
+ */
+export function memStats() {
+  let canvases = 0;
+  let canvasesWithGl = 0;
+  try {
+    const list = [...document.querySelectorAll('canvas')];
+    canvases = list.length;
+    for (const c of list) {
+      st.contexts.forEach((r) => { if (r.canvas === c) canvasesWithGl += 1; });
+    }
+  } catch { /* 忽略 */ }
+  const orphanGl = st.contexts.filter((r) => !r.lost && r.canvas && !r.canvas.isConnected).length;
+  let jsHeapMB = null;
+  let jsHeapLimitMB = null;
+  let jsHeapPct = null;
+  try {
+    const m = performance && performance.memory;
+    if (m && m.usedJSHeapSize) {
+      jsHeapMB = Math.round((m.usedJSHeapSize / 1048576) * 10) / 10;
+      // 内存保护（T11）需要的是"占上限的比例"，只给 MB 无法判断还剩多少余量。
+      //   totalJSHeapSize 是"已分配额度"、jsHeapSizeLimit 才是硬上限 ⇒ 后者才是判据。
+      if (m.jsHeapSizeLimit) {
+        jsHeapLimitMB = Math.round((m.jsHeapSizeLimit / 1048576) * 10) / 10;
+        jsHeapPct = m.usedJSHeapSize / m.jsHeapSizeLimit;
+      }
+    }
+  } catch { /* 非 Chrome：保持 null，调用方按"无法判断"处理 */ }
+  return {
+    glContexts: st.created,
+    glContextsLive: Math.max(0, st.created - st.lost),
+    glContextsLost: st.lost,
+    byType: { ...st.byType },
+    canvases,
+    canvasesWithGl,
+    orphanGl,
+    // 逐条明细（排障用）：哪些 canvas 拿了上下文、是否仍在文档里
+    jsHeapLimitMB,
+    jsHeapPct,
+    records: st.contexts.map((r) => ({
+      type: r.type, id: r.id, cls: r.cls, w: r.w, h: r.h,
+      lost: !!r.lost, connected: !!(r.canvas && r.canvas.isConnected),
+    })),
+    jsHeapMB,
+  };
+}
+
+/** 供测试重置（仅测试用） */
+export function __resetMemStatsForTest() {
+  st.created = 0; st.lost = 0; st.byType = {}; st.contexts = [];
+}