modelstage 0.0.0-stage → 0.5.28

package/src/web/panel/settings-io.js

@@ -0,0 +1,291 @@
+// panel/settings-io.js —— 设置导出 / 导入（右栏「设置」组底部那三个按钮的后两个）
+//
+// 导出：一个 JSON 同时带走「服务端配置原文」（GET /api/config/export）与「前端偏好」（localStorage）。
+// 导入：项目配置交给 POST /api/config/import（校验→备份→写→回读自检），偏好写回 localStorage 并立即生效。
+//
+// 依赖注入的原因：面板桥（重载名册/应用偏好）与状态行都在装配层，这里不反向 import，避免环。
+import { formatError, getJson } from '../infra/api.js';
+import { readViewSettings, VIEW_SETTINGS_KEY } from '../app/view-settings.js';
+import { stageLog, stageStatus } from '../app/status.js';
+import { state } from '../app/context.js';
+
+/** 装配层注入：面板设置回放、导入后重载、偏好应用 */
+let ioBridge = {
+  applyPanelSetting: null,
+  applyViewerPrefs: null,
+  reloadApp: null,
+  panelSettings: () => ({}),
+};
+
+export function connectSettingsIo(bridge) {
+  ioBridge = { ...ioBridge, ...(bridge || {}) };
+}
+
+/** 取服务端项目配置原文（失败不抛出，返回 error 供状态行提示） */
+async function fetchProjectFiles() {
+  try {
+    // 幂等 GET 的小 JSON（实测 58ms）⇒ 走统一层拿重试与统一超时/错误归类。
+    //   非 2xx 现在会被 api.js 抛成带 status 的错误（原来在这里读 data.error），
+    //   两种来源都会落进下面的 catch 变成可读文案，状态行展示口径不变。
+    const data = await getJson('/api/config/export');
+    if (data && data.files) return { files: data.files, error: null };
+    return { files: null, error: (data && data.error) || '服务端未返回 files' };
+  } catch (err) {
+    return { files: null, error: (err && err.message) || String(err) };
+  }
+}
+
+/** 触发浏览器下载（内容同时留在 dataset 供断言） */
+function downloadJson(text, fileName) {
+  const url = URL.createObjectURL(new Blob([text], { type: 'application/json' }));
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = fileName;
+  document.body.append(link);
+  link.click();
+  link.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+/**
+ * 导出：一个 JSON 文件同时带走「服务端配置原文」+「前端偏好」。
+ * 结构：{ _meta, schema, project:{files}, panel, view }
+ * 项目配置取不到时仍导出偏好，并在状态行注明（一半失败不牵连整体）。
+ */
+export async function exportSettingsFile() {
+  const project = await fetchProjectFiles();
+  const payload = {
+    _meta: {
+      app: 'modelstage',
+      formatVersion: 1,
+      exportedAt: new Date().toISOString(),
+      note: 'project=服务端配置原文（资源根+名表）；panel/view=前端偏好',
+    },
+    schema: 'modelstage-settings/v2',
+    project: project.files ? { files: project.files } : null,
+    panel: { ...(ioBridge.panelSettings() || {}) },
+    view: readViewSettings(),
+  };
+  const text = JSON.stringify(payload, null, 2);
+  const panelCount = Object.keys(payload.panel).length;
+  const projectCount = project.files ? Object.keys(project.files).length : 0;
+  window.__WEB__ && (window.__WEB__.settingsExport = {
+    text, panelCount, projectFiles: projectCount, projectError: project.error,
+  });
+  document.documentElement.dataset.settingsExport = String(text.length);
+  try {
+    downloadJson(text, `modelstage-settings-${payload._meta.exportedAt.slice(0, 10)}.json`);
+    stageStatus(
+      `已导出设置：前端偏好 ${panelCount} 项`
+      + (projectCount ? ` + 项目配置 ${projectCount} 个文件` : `（项目配置未取到：${project.error}）`)
+      + `，${text.length} 字节`, 'info', { show: true });
+    return true;
+  } catch (err) {
+    stageLog('error', `导出设置失败：${formatError(err)}`, { err: formatError(err) });
+    return false;
+  }
+}
+
+/**
+ * 打开导入文件选择器。
+ * 说明：浏览器不允许脚本直接读本地文件，只能由用户选文件；所以这里造一个隐藏 input，
+ *   选完立刻移除，文本交给 importSettingsFromText 处理（该函数也可被自动化直接调用）。
+ */
+export function openImportPicker() {
+  // <label> 包 <input type="file">：点 label 即触发选择框（原生行为，不靠 JS 绑 click）
+  const label = document.createElement('label');
+  label.classList.add('file-picker-hidden');
+  const input = document.createElement('input');
+  input.type = 'file';
+  input.accept = '.json,application/json';
+  label.append(input);
+  document.body.append(label);
+  input.addEventListener('change', async () => {
+    const file = input.files && input.files[0];
+    label.remove();
+    if (!file) return;
+    let text = '';
+    try { text = await file.text(); } catch (err) {
+      stageLog('error', `读取文件失败：${formatError(err)}`, { err: formatError(err) });
+      return;
+    }
+    await importSettingsFromText(text);
+  }, { once: true });
+  label.click();   // 点 label 等价于点 input（原生行为）
+  stageStatus('已打开导入文件选择器：选一个之前导出的 JSON', 'info', { show: true });
+  return true;
+}
+
+/**
+ * 把导入文本解析成对象（不做语义判断，只回答"能不能读成对象"）。
+ * @param {string} text
+ * @returns {{ok: boolean, value?: object, error?: string}}
+ */
+function parseImportText(text) {
+  let value = null;
+  try { value = JSON.parse(String(text || '')); } catch (err) {
+    return { ok: false, error: `不是合法 JSON（${(err && err.message) || err}）` };
+  }
+  if (!value || typeof value !== 'object') return { ok: false, error: '内容为空或不是对象' };
+  return { ok: true, value };
+}
+
+/**
+ * 从解析结果里认出三类内容。
+ * 兼容三种来源：本项目导出（view/panel）、旧版实现导出（viewer）、最早期的"顶层直接是偏好"。
+ * @param {object} parsed
+ * @returns {{projectFiles: object|null, viewPrefs: object|null, panelPrefs: object|null}}
+ */
+/** 取"对象型字段"的值；不是对象就当年没有 */
+function objectField(value) {
+  return value && typeof value === 'object' ? value : null;
+}
+
+/** 这份对象看起来是不是"视图偏好本体"（最早期导出没有包装层） */
+function looksLikePrefs(obj) {
+  if (!obj) return false;
+  // 只认"确实还在用"的偏好字段；已下线的字段不再参与识别
+  //   （否则一份只剩 partFilter* 的旧导出会被误当成偏好本体）
+  return !!(obj.uiTheme || obj.background);
+}
+
+/** 已下线的设置字段：导入时**忽略并记一条 warn**，绝不因此中断整份导入 */
+const DEPRECATED_PREF_FIELDS = ['partFilterEnabled', 'partFilterKeywords'];
+
+
+function classifyImportPayload(parsed) {
+  const obj = objectField(parsed) || {};
+  // 向后兼容：老导出文件里可能带已下线的字段（如 partFilter*）。
+  //   这里只提示一句、照常继续导入 —— 不能因为一个废弃字段让整份配置导入失败。
+  const deprecated = DEPRECATED_PREF_FIELDS.filter((k) => obj[k] !== undefined
+    || (obj.view && obj.view[k] !== undefined) || (obj.viewer && obj.viewer[k] !== undefined));
+  if (deprecated.length) {
+    try {
+      stageLog('warn', `导入配置里含已下线字段（${deprecated.join('、')}），已忽略，其余设置照常导入`, { deprecated });
+    } catch { /* 状态行不可用不影响导入 */ }
+    document.documentElement.dataset.settingsImportDeprecated = deprecated.join(',');
+  }
+  const projectFiles = obj.project && obj.project.files ? obj.project.files : null;
+  const viewer = objectField(obj.viewer);
+  const viewPrefs = objectField(obj.view) || viewer || (looksLikePrefs(obj) ? obj : null);
+  return { projectFiles, viewPrefs, panelPrefs: objectField(obj.panel) };
+}
+
+/** 后端拒绝时拼一句可读原因（成功返回 null） */
+function rejectReason(res, data) {
+  if (res && res.ok && data && data.ok === true) return null;
+  const details = Array.isArray(data && data.details) ? data.details : [];
+  const why = (data && data.error) || `HTTP ${res ? res.status : 'unknown'}`;
+  return `项目配置被拒绝（${why}）${details.length ? `：${details.join('；')}` : ''}`;
+}
+
+/** 统一的失败出口：状态行 + dataset 标记 + 返回值，三处口径一致 */
+function importFail(stage, error) {
+  const msg = `导入失败：${error}`;
+  stageLog('error', msg, { source: 'import-config' });
+  document.documentElement.dataset.settingsImport = `fail|${msg}`;
+  return { ok: false, mode: stage, error: msg };
+}
+
+/**
+ * 项目配置落地：交给后端自己校验/备份/写/回读。
+ * @param {object} files 相对 config/ 的路径 → 文件文本
+ * @returns {Promise<{ok: boolean, written?: string[], backup?: string|null, mode?: string, error?: string}>}
+ */
+async function importProjectFiles(files) {
+  let res = null;
+  let data = null;
+  try {
+    res = await fetch('/api/config/import', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ files }),
+      // 30s：一次要写多个配置文件**并且**先备份现有配置（backupConfigFile 落盘到 CIFS，
+      //   每个文件是"写临时文件 + rename"两次往返，几 MB 配置在 CIFS 上可能数秒）。
+      //   导出侧实测 58ms 但那只是读；给 30s 是留足"多文件写入 + 备份"的余量，
+      //   而不是把慢但正常的情况判成失败。
+      signal: AbortSignal.timeout(30000),
+    });
+    data = await res.json();
+  } catch (err) {
+    // 说清是"超时/中断"而不是笼统的"请求失败"：30s 到点就掐断（见上面的 signal），
+    //   用户需要知道是服务端慢/卡住了，而不是自己填错了什么。
+    return importFail('network', `项目配置导入超时或中断（上限 30s）：${formatError(err)}`);
+  }
+  const rejected = rejectReason(res, data);
+  if (rejected) return importFail('project', rejected);
+  if (typeof ioBridge.reloadApp === 'function') {
+    try { await ioBridge.reloadApp(); } catch { /* 重载失败不影响导入结果展示 */ }
+  }
+  return { ok: true, written: data.written || [], backup: data.backup || null };
+}
+
+/**
+ * 前端偏好落地：视图偏好写 localStorage 后立刻生效，面板设置逐项回放。
+ * @param {object|null} viewPrefs
+ * @param {object|null} panelPrefs
+ * @returns {number} 实际应用项数
+ */
+function importPrefs(viewPrefs, panelPrefs) {
+  let applied = 0;
+  if (viewPrefs) {
+    try {
+      const merged = { ...readViewSettings(), ...viewPrefs };
+      localStorage.setItem(VIEW_SETTINGS_KEY, JSON.stringify(merged));
+      if (typeof ioBridge.applyViewerPrefs === 'function') ioBridge.applyViewerPrefs(merged);
+      else applyTheme(merged.uiTheme || 'dark-cyan');
+      applied += Object.keys(viewPrefs).length;
+    } catch (err) {
+      stageLog('warn', `前端偏好写入失败：${formatError(err)}`, { err: formatError(err) });
+    }
+  }
+  if (panelPrefs && typeof ioBridge.applyPanelSetting === 'function') {
+    for (const [id, value] of Object.entries(panelPrefs)) {
+      try {
+        ioBridge.applyPanelSetting(id, value);
+        // 面板控件同步：导入只写引擎会出现"设置生效了、读数还是旧值"，
+        //   而读数是用户唯一可见的生效出口 —— 必须跟着走到新值（契约：显示值=真实值）
+        if (state.panel && typeof state.panel.setValue === 'function') state.panel.setValue(id, value);
+        applied += 1;
+      } catch { /* 单项失败继续 */ }
+    }
+  }
+  return applied;
+}
+
+/**
+ * 导入一个导出文件：识别 → 校验 → 项目配置落地 → 偏好落地 → 汇总提示。
+ * @param {string} text JSON 文本
+ * @returns {Promise<{ok:boolean, mode:string, written?:string[], backup?:string, error?:string}>}
+ */
+export async function importSettingsFromText(text) {
+  const parsed = parseImportText(text);
+  if (!parsed.ok) return importFail('parse', parsed.error);
+  const { projectFiles, viewPrefs, panelPrefs } = classifyImportPayload(parsed.value);
+  if (!projectFiles && !viewPrefs && !panelPrefs) {
+    return importFail('shape', '既没有项目配置（project.files）也没有可识别的偏好字段');
+  }
+  let written = null;
+  let backup = null;
+  if (projectFiles) {
+    const res = await importProjectFiles(projectFiles);
+    if (!res.ok) return res;
+    written = res.written;
+    backup = res.backup;
+  }
+  const applied = importPrefs(viewPrefs, panelPrefs);
+  const parts = [];
+  if (projectFiles) parts.push(`项目配置 ${written.length} 个文件${backup ? `（备份 ${backup}）` : ''}`);
+  if (applied) parts.push(`前端偏好 ${applied} 项`);
+  const msg = `已导入：${parts.join(' + ') || '无变更'}`;
+  stageStatus(msg, 'info', { show: true });
+  document.documentElement.dataset.settingsImport = `ok|${msg}`;
+  return { ok: true, mode: projectFiles ? 'project' : 'prefs', written, backup };
+}
+
+// 自动化入口：文件选择器在无头环境里点不了，测试直接喂 JSON 文本。
+// 注意 __WEB__ 可能比本模块晚初始化，所以这里"没有就建"（与 app/context.js 同一写法）。
+if (typeof window !== 'undefined') {
+  window.__WEB__ = window.__WEB__ || {};
+  window.__WEB__.settingsIo = { importText: importSettingsFromText, exportNow: exportSettingsFile };
+}

package/src/web/panel/shell-controls.js

@@ -0,0 +1,274 @@
+// panel/shell-controls.js —— 四个「外壳级」控件的真实实现
+//
+// 这四项与渲染器能力无关（主题/背景那类才走 panel 的能力过滤），所以归外壳自己管：
+//   ctl-show-status   显示状态信息    → 控制舞台顶部状态行的显隐（日志照旧写）
+//   ctl-debug-log     调试日志        → 控制 debug/panel.js 浮层的显隐（采集与展示分离）
+//   ctl-hang-guard    防卡死保护      → 帧停滞看门狗（检出 + 自愈 + 计数）
+//   ctl-settings-io   导出/导入/恢复默认 → 导出走前端生成 JSON；导入依赖后端（未实现即如实禁用）
+//
+// 与 main.js 的分工：main.js 只做装配（把 SHELL_APPLIERS 指向这里导出的函数），
+//   跨模块需要的"面板重放"通过 connectShellControls 注入，避免 main ↔ 本模块循环依赖。
+
+import { createDebugLog } from '../debug/log.js';
+import { setStageVisible } from '../app/memory-bars.js';
+import { mountDebugPanel } from '../debug/panel.js';
+import { formatError } from '../infra/api.js';
+import { dom, state, stage } from '../app/context.js';
+import { resetViewViaRenderer } from '../render/reset-view.js';
+import { stageLog, stageStatus } from '../app/status.js';
+import * as memoryGuard from '../app/memory-guard.js';
+import { VIEW_SETTINGS_KEY, applyBackground, applyTheme, readViewSettings, saveViewSettings } from '../app/view-settings.js';
+import {
+  connectSettingsIo, exportSettingsFile, importSettingsFromText, openImportPicker,
+} from './settings-io.js';
+
+/**
+ * 防卡死保护的参数：单点定义，测试与排障都读这里（不许在逻辑里散落裸数字）。
+ *   tickMs     采样间隔
+ *   stallLimit 连续多少次"帧数不增长"判定为卡死（3 次 ≈ 3 秒）
+ */
+export const hangGuardConfig = { tickMs: 1000, stallLimit: 3 };
+
+/** 面板桥：恢复默认要"按面板声明的默认值重放一遍"，由 main.js 在装配完成后注入 */
+let panelBridge = {
+  applyPanelSetting: null,
+  getPanelDefaults: () => ({}),
+  /** 导入项目配置后需要重载资源根与名册树（由 main.js 注入） */
+  reloadApp: null,
+  /** 应用导入的视图偏好（主题/背景/部件筛除） */
+  applyViewerPrefs: null,
+};
+
+/**
+ * 注入面板桥（在 main.js 里装配好面板后调用一次）。
+ * @param {{applyPanelSetting?: Function, getPanelDefaults?: Function}} bridge
+ */
+export function connectShellControls(bridge) {
+  panelBridge = { ...panelBridge, ...(bridge || {}) };
+  // 设置导入/导出模块用同一套桥（重载名册、应用偏好、面板回放）
+  connectSettingsIo({
+    applyPanelSetting: (id, value) => panelBridge.applyPanelSetting?.(id, value),
+    applyViewerPrefs: (prefs) => panelBridge.applyViewerPrefs?.(prefs),
+    reloadApp: () => panelBridge.reloadApp?.(),
+    panelSettings: () => state.panelSettings || {},
+  });
+  window.__WEB__ && (window.__WEB__.hangGuardConfig = hangGuardConfig);
+}
+
+/**
+ * 显示状态信息（ctl-show-status）：控制舞台顶部那条状态行的显隐。
+ * 关掉只是不显示，日志与控制台照旧（排障不能因为藏了提示就断线）。
+ */
+export function applyShowStatus(on) {
+  // 舞台顶部的内存条与状态行同策略：关掉「显示状态信息」时它也不显示
+  setStageVisible(on !== false);
+  state.showStatus = on !== false;
+  document.documentElement.dataset.showStatus = state.showStatus ? 'on' : 'off';
+  if (dom.stageHint && !state.showStatus) {
+    dom.stageHint.textContent = '';
+    dom.stageHint.hidden = true;
+  }
+  stageStatus(`状态信息显示：${state.showStatus ? '开' : '关'}`, 'info', { show: true });
+}
+
+/**
+ * 调试日志（ctl-debug-log）：控制 debug/panel.js 浮层的显隐。
+ * 采集与展示分开——关掉只隐藏面板，已采内容保留，重新打开能接着看。
+ */
+export function applyDebugLog(on) {
+  state.debugLog = on !== false;
+  document.documentElement.dataset.debugLog = state.debugLog ? 'on' : 'off';
+  const host = ensureDebugPanelHost();
+  if (host) host.hidden = !state.debugLog;
+  if (state.debugLogHandle && typeof state.debugLogHandle.setEnabled === 'function') {
+    try { state.debugLogHandle.setEnabled(state.debugLog); } catch { /* 开关失败不影响渲染 */ }
+  }
+  // S4：把持久化的"收起/展开"补上（面板可能比启动读回更早挂载，挂载那一刻还读不到持久值）
+  if (state.debugPanel && typeof state.debugPanel.restoreCollapsed === 'function') {
+    try { state.debugPanel.restoreCollapsed(); } catch { /* 回放失败保持当前形态 */ }
+  }
+  stageStatus(`调试日志：${state.debugLog ? '开' : '关'}`, 'info', { show: true });
+}
+
+/** 调试日志浮层的容器与实例（懒建；样式由 debug/panel.js 自己注入） */
+export function ensureDebugPanelHost() {
+  if (state.debugPanelHost) return state.debugPanelHost;
+  const host = document.createElement('div');
+  host.id = 'debug-panel-host';
+  // 位置/尺寸在 style.css 的 #debug-panel-host（契约：设计值不进 JS）
+  document.body.append(host);
+  state.debugPanelHost = host;
+  try {
+    state.debugLogHandle = createDebugLog({ capacity: 200 });
+    state.debugPanel = mountDebugPanel({ log: state.debugLogHandle, container: host });
+    window.__WEB__ && (window.__WEB__.debugLog = state.debugLogHandle);
+  } catch (err) {
+    stageLog('warn', `调试日志面板不可用：${formatError(err)}`, { err: formatError(err) });
+    state.debugLogHandle = null;
+  }
+  return state.debugPanelHost;
+}
+
+/**
+ * 防卡死保护（ctl-hang-guard）：防的是「画面停住但没人知道」。
+ * 做法：每 tickMs 采一次舞台累计帧数，连续 stallLimit 次不增长（且已有模型在渲染）判为停滞 →
+ *   写一条 warn + 尝试 pause→play 自愈一次；计数写进 __WEB__.hangGuard 供断言。
+ * 只看"有没有新帧"，不看帧率高低（慢 ≠ 卡死）。关掉时定时器直接停，不留后台轮询。
+ */
+export function applyHangGuard(on) {
+  state.hangGuard = on !== false;
+  document.documentElement.dataset.hangGuard = state.hangGuard ? 'on' : 'off';
+  if (state.hangGuardTimer) {
+    clearInterval(state.hangGuardTimer);
+    state.hangGuardTimer = null;
+  }
+  if (!state.hangGuard) {
+    stageStatus('防卡死保护：关', 'info', { show: true });
+    return;
+  }
+  state.hangGuardStats = { ticks: 0, stalls: 0, recoveries: 0, lastFrames: null, skippedHidden: 0 };
+  window.__WEB__ && (window.__WEB__.hangGuard = state.hangGuardStats);
+  state.hangGuardTimer = setInterval(hangGuardTick, hangGuardConfig.tickMs);
+  stageStatus(`防卡死保护：开（连续 ${hangGuardConfig.stallLimit}s 无新帧则尝试恢复）`, 'info', { show: true });
+}
+
+/**
+ * 内存保护（ctl-memory-guard）：与防卡死保护并列、互不替代。
+ *   · 开关开（默认）＝ 服务端解包前按可用内存准入 + 前端加载前查 JS 堆占用；
+ *   · 开关关 ＝ 服务端放行超预算解包（用户自担风险），前端预检也不再拦。
+ * 这里只翻转状态并刷新判据读数，真正的判断在 app/memory-guard.js 与服务端 capacity.mjs。
+ * @param {boolean} on
+ */
+export function applyMemoryGuard(on) {
+  const value = memoryGuard.setMemoryGuard(on);
+  stageStatus(value ? '内存保护：开（解包按可用内存准入）' : '内存保护：关（允许超预算解包，请自行确认内存充足）', 'info', { show: true });
+}
+
+/** 把看门狗计数发布到 dataset（纯可观测性，失败不影响任何行为） */
+function publishHangGuardStats(stats) {
+  try {
+    document.documentElement.dataset.hangGuardStats =
+      `ticks=${stats.ticks} stalls=${stats.stalls} rec=${stats.recoveries}`
+      + ` skip=${stats.skippedHidden || 0} skipPaused=${stats.skippedPaused || 0}`;
+  } catch { /* dataset 只是可观测性 */ }
+}
+
+/** 看门狗单次采样 */
+function hangGuardTick() {
+  const stats = state.hangGuardStats;
+  if (!stats || !stage || typeof stage.stats !== 'function') return;
+  // 标签页在后台时**直接跳过，连统计都不做**：
+  //   浏览器按规范会暂停后台页的 requestAnimationFrame（省电），frames 自然不增长 ——
+  //   那是浏览器的正常行为，不是我们的渲染卡死。在这儿统计只会得出"后台=卡死"的假结论，
+  //   而且下一段的 stallLimit 一到就会真的去 pause()/play() 自愈一次（多余动作）。
+  // 计数单独记 skippedHidden（不是把 stalls 归零），让它可观测：将来要看"到底跳过了多少次"有据可查。
+  if (typeof document !== 'undefined' && document.visibilityState === 'hidden') {
+    stats.skippedHidden = (stats.skippedHidden || 0) + 1;
+    return;
+  }
+  let snap = null;
+  try { snap = stage.stats(); } catch { snap = null; }
+  if (!snap) return;
+
+  // **暂停时完全跳过**（不碰 ticks / stalls / lastFrames），与"后台标签页"同型：
+  //   暂停本来就不该有帧（canvas-api 的 pause() 会 stopFrameTick），拿它去判"渲染停滞"必然误判。
+  // 实测代价（8899，spine char000101）：暂停后每 tick frames 不涨 ⇒ stalls 累加到 3
+  //   ⇒ 看门狗执行 pause();play() 自愈 ⇒ rec 0→1、paused 被改回 false、
+  //   引擎 animationId 从"字段不存在"变成 522 并持续递增。
+  //   ⇒ 用户点了暂停，**画面 3~4 秒后自己继续动** —— 这是用户可见的功能缺陷，不是计数虚涨。
+  // 计 skippedPaused 保持可观测（与 skippedHidden 一致），但**不参与停滞判定**；
+  //   注意不要改成"暂停时把 stalls 归零"（那是另一种语义：仍在拿不该涨的东西当判据）。
+  if (snap.paused === true) {
+    stats.skippedPaused = (stats.skippedPaused || 0) + 1;
+    stats.wasPaused = true;
+    publishHangGuardStats(stats);
+    return;
+  }
+
+  // 从暂停回到播放的第一个 tick **只重置基线、不比较**：
+  //   frames 在暂停期间冻住，若直接拿 lastFrames（暂停前的旧值）去比，
+  //   恢复播放后可能立刻算成一次停滞（同一个误报的镜像）。
+  if (stats.wasPaused) {
+    stats.wasPaused = false;
+    stats.lastFrames = null;
+    stats.stalls = 0;
+    stats.ticks += 1;
+    publishHangGuardStats(stats);
+    return;
+  }
+
+  stats.ticks += 1;
+  const frames = typeof snap.frames === 'number' ? snap.frames : null;
+  // 没模型在渲染时不计停滞：没东西可卡，报了就是误报。
+  // 只看 model：`snap.phase` 是**恒假**的死条件 —— statsOf() 不返回 phase
+  //   （`phase: 'ready'` 只出现在 canvas-api 的 onStatus 回调里，不是 stats() 快照的一部分）。
+  const loaded = !!snap.model;
+  if (!loaded || frames === null) { stats.lastFrames = frames; return; }
+  stats.stalls = stats.lastFrames !== null && frames <= stats.lastFrames ? stats.stalls + 1 : 0;
+  stats.lastFrames = frames;
+  if (stats.stalls >= hangGuardConfig.stallLimit) {
+    stats.stalls = 0;
+    stats.recoveries += 1;
+    stageLog('warn', `检测到渲染停滞（${hangGuardConfig.stallLimit}s 无新帧），已尝试恢复`, { stallLimit: hangGuardConfig.stallLimit });
+    try { stage.pause(); stage.play(); } catch { /* 自愈失败不影响主流程 */ }
+  }
+  publishHangGuardStats(stats);
+}
+
+// 从后台切回可见时**重置基线**：
+//   后台期间 rAF 停着、frames 冻住，stats.lastFrames 是"很久以前的旧值"。
+//   不重置就直接比，会把整个后台时长一次性算成停滞 ⇒ 切回来第一个 tick 就报"渲染停滞"，
+//   和后台误报是同一个病，只是晚了一步。
+// 这里只清基线（lastFrames=null 让下一个 tick 只记录不比较；stalls 归零），
+//   不动 recoveries/skippedHidden（那是累计事实，不该被一次切页抹掉）。
+// 幂等注册：模块只加载一次，监听只挂一次。
+if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+  document.addEventListener('visibilitychange', () => {
+    const stats = state.hangGuardStats;
+    if (!stats) return;
+    if (document.visibilityState === 'visible') {
+      stats.lastFrames = null;
+      stats.stalls = 0;
+    }
+  });
+}
+
+/**
+ * 设置导入导出（ctl-settings-io）：三个动作共用一条通路，按按钮文字分派。
+ * 导入依赖后端写接口，接口没实现就不假装能做（按钮在 schema 里已带禁用原因）。
+ */
+// 自动化入口：文件选择器在无头环境里没法点，测试直接喂 JSON 文本
+window.__WEB__ && (window.__WEB__.settingsIo = { importText: importSettingsFromText, exportNow: exportSettingsFile });
+
+export function runSettingsAction(action) {
+  if (action === '导出设置') return exportSettingsFile();
+  if (action === '导入设置') return openImportPicker();
+  if (action === '恢复默认') return restoreDefaultSettings();
+  stageLog('warn', `设置动作不可用：${action}`, { action });
+  return false;
+}
+
+/** 恢复默认：清本地存储 → 按面板声明的默认值重放一遍 → 视图复位 */
+export function restoreDefaultSettings() {
+  try { localStorage.removeItem(VIEW_SETTINGS_KEY); } catch { /* 存储不可用不算失败 */ }
+  state.panelSettings = {};
+  try { saveViewSettings({ panel: {} }); } catch { /* 存储不可用忽略 */ }
+  const defaults = panelBridge.getPanelDefaults() || {};
+  for (const [id, value] of Object.entries(defaults)) {
+    // MSAA 默认值已由建上下文时生效，重放会白等一次上下文重建
+    if (id === 'ctl-msaa') continue;
+    if (typeof panelBridge.applyPanelSetting === 'function') panelBridge.applyPanelSetting(id, value);
+  }
+  applyTheme('dark-cyan');
+  applyBackground('checkerboard');
+  const panel = state.panel;
+  if (panel && panel.setValue) {
+    panel.setValue('ctl-theme', state.viewTheme);
+    panel.setValue('ctl-bg-mode', state.viewBg);
+  }
+  // 视图复位走统一入口（只认当前渲染器，避免 Live2D 面打到隐藏的 Spine 舞台）
+  try { resetViewViaRenderer(state.currentRenderer); } catch { /* 视图复位失败不影响设置 */ }
+  document.documentElement.dataset.settingsRestored = String(Date.now());
+  stageStatus('已恢复默认设置（本地存储已清空、视图已复位）', 'info', { show: true });
+  return true;
+}