modelstage 0.0.0-stage → 0.5.28

package/src/web/app/renderer-setting.js

@@ -0,0 +1,70 @@
+// app/renderer-setting.js —— 面板/交互层设置下发的唯一通道（契约 INV-01）
+//
+// 为什么要有这个模块：设置只能经 `renderer.setSetting(key, value)` 落地，不允许任何调用点
+//   直接摸舞台的 set 方法。之前 9 处直连的问题不是"写错"，而是**绕过渲染器**：
+//   Live2D 模式下那些调用会打到隐藏的 spine 舞台上（改了没人看的对象），表现为"点了没反应"。
+//
+// 这个模块集中三件事：
+//   ① 只认 state.currentRenderer（当前渲染面），不认 stage
+//   ② 三态：渲染器没声明该能力键 ⇒ 记一条 warn 并返回 false（控件由面板置灰，这里兜底）
+//   ③ 契约 §六：setSetting 返回 false 时记 warn，并回读 getSetting 的**生效值**供调用方回退
+//
+// 注意：同一条键只警告一次（Set 去重）。否则"恢复上次偏好"这类路径会在每次装载时刷屏。
+import { state } from './context.js';
+import { stageLog, stageStatus } from './status.js';
+import { repaintActive } from '../render/playback.js';
+
+/** 已警告过的键（避免同一条能力缺失反复刷日志） */
+const warned = new Set();
+
+/** 记一次去重后的警告 */
+function warnOnce(key, message) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  stageLog('warn', message, { key: String(key || ''), source: 'renderer-setting' });
+}
+
+/** 渲染器是否声明了某能力键（未声明 ⇒ 面板置灰，这里不硬发） */
+export function rendererSupports(key) {
+  const r = state.currentRenderer;
+  const list = (r && r.capabilities && r.capabilities.settings) || [];
+  return list.includes(key);
+}
+
+/**
+ * 经渲染器下发一项设置。
+ * @param {string} key 能力键（skin / mixMode / mixTime / animation / fps / speed / pma …）
+ * @param {any} value 目标值
+ * @returns {{ok: boolean, applied: any}} ok=false 时 applied 是回读到的生效值（可能为 null）
+ */
+export function setRendererSetting(key, value) {
+  const renderer = state.currentRenderer;
+  if (!renderer || typeof renderer.setSetting !== 'function') {
+    warnOnce(key, `当前渲染器不可用，设置 ${key} 未下发`);
+    return { ok: false, applied: null };
+  }
+  if (!rendererSupports(key)) {
+    // 这里**故意不记日志**：能力不支持的控件在 applyCapabilities 阶段就根本不构建，
+    //   "该项不可用（面板应置灰）"指向一个用户看不到的东西；同类告警在面板侧也已删除。
+    //   能力是否支持属于自检结论（selfCheck 的 checked/violations），不该每次运行时刷一条。
+    return { ok: false, applied: null };
+  }
+  let ok = false;
+  try { ok = renderer.setSetting(key, value) === true; } catch { ok = false; }
+  // 暂停中改设置：引擎/渲染循环都停着，必须显式补一帧，否则"改了看不见"
+  if (state.playing === false) { try { repaintActive(state.surface); } catch { /* 忽略 */ } }
+  let applied = null;
+  try { applied = renderer.getSetting ? renderer.getSetting(key) : null; } catch { applied = null; }
+  if (!ok) {
+    // 契约 §六：返回 false 必须留痕，并让调用方拿到生效值做回退
+    warnOnce(key, `设置 ${key}=${String(value)} 未被渲染器接受，已回退到生效值 ${String(applied)}`);
+  }
+  return { ok, applied };
+}
+
+/** 回读某键的生效值（不改变任何状态） */
+export function getRendererSetting(key) {
+  const renderer = state.currentRenderer;
+  if (!renderer || typeof renderer.getSetting !== 'function') return null;
+  try { return renderer.getSetting(key); } catch { return null; }
+}

package/src/web/app/root-manager.js

@@ -0,0 +1,254 @@
+// app/root-manager.js —— 资源根管理（左栏）：新增 / 改名 / 启停 / 删除
+//
+// 为什么是"输入服务端绝对路径"而不是目录选择器：
+//   模型是**服务端**扫描自己文件系统加载的，浏览器 File System Access API 拿到的是客户端
+//   FileSystemDirectoryHandle（浏览器沙箱内的句柄），根本无法变成服务端可读的路径 —— 传过去
+//   毫无意义。项目也没有"服务端目录浏览"接口（那属于 M5 插件接口范畴），所以这里用文本框收
+//   绝对路径 + 用已有根做 datalist 提示 + 把后端校验错误原样显示给用户（400/409/404 都有文案）。
+//
+// 每个动作结束后都用后端返回的 rootsAll 重建列表（含停用项），再回调 onChanged 让名册树刷新。
+
+/** 后端错误文案优先，其次状态码，最后兜底 —— 一律原样呈现，不吞不猜 */
+function describeError(status, payload, formatError) {
+  const text = payload && typeof payload.error === 'string' && payload.error
+    ? payload.error
+    : (typeof formatError === 'function' ? formatError({ status }) : `HTTP ${status}`);
+  return `${text}（HTTP ${status}）`;
+}
+
+/**
+ * 创建资源根管理器。
+ * @param {{els: object, onChanged?: Function, formatError?: Function}} deps
+ *   els 需要：list（根条目容器）、form/pathInput/nameInput（新增表单）、msg（提示区）、
+ *            count（数量文案）、toggleBtn/body（管理区展开/收起）
+ */
+export function createRootManager({ els, onChanged, formatError } = {}) {
+  const state = {
+    /** 最近一次拿到的完整根列表（含停用项）：GET 只给启用的，所以以 POST 返回的 rootsAll 为准 */
+    roots: [],
+    /** 正在内联编辑改名的根 id */
+    editingId: null,
+    /** 正在二次确认删除的根 id */
+    confirmingId: null,
+    /** 最近一次动作结果（断言用） */
+    last: null,
+  };
+
+  /** 统一的提示：文案 + 级别（ok/err），同时写进 dataset 供断言读 */
+  function notify(text, level = 'info') {
+    if (els.msg) {
+      els.msg.textContent = text || '';
+      els.msg.dataset.level = level;
+    }
+    document.documentElement.dataset.rootMsg = `${level}|${text || ''}`;
+    return text;
+  }
+
+  /** 发一次写请求：返回 {ok, status, data}；HTTP 非 2xx 不抛，交给调用方决定怎么提示 */
+  async function post(body) {
+    const res = await fetch('/api/roots', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      // 写操作：**不加去重、不自动重试**（重复写会建两个根），只补超时信号防"永久转圈"。
+      //   8s 依据：服务端只改一份 resources.json + 落盘备份（backupConfigFile），正常 <1s，
+      //   留 8 倍余量覆盖 CIFS 落盘抖动。不用 api.js：它的默认重试会重发写请求。
+      signal: AbortSignal.timeout(8000),
+    });
+    let data = null;
+    try { data = await res.json(); } catch { data = null; }
+    state.last = { action: body && body.action, status: res.status, data };
+    return { ok: res.ok, status: res.status, data };
+  }
+
+  /** 用一份完整根列表重建 UI（后端给的 rootsAll 优先；没有就退回 GET 的 roots） */
+  function render(roots) {
+    if (Array.isArray(roots)) state.roots = roots;
+    const list = state.roots;
+    if (els.count) els.count.textContent = String(list.length);
+    if (!els.list) return list;
+    els.list.replaceChildren();
+    if (!list.length) {
+      const empty = document.createElement('p');
+      empty.className = 'muted-hint';
+      empty.textContent = '还没有资源根';
+      els.list.append(empty);
+      return list;
+    }
+    for (const root of list) els.list.append(renderRow(root));
+    return list;
+  }
+
+  /** 单条根：名字 / id / 路径 / 启停状态 + 三个操作（改名为内联编辑，删除二次确认） */
+  function renderRow(root) {
+    const row = document.createElement('div');
+    row.className = 'root-row';
+    row.dataset.rootId = root.id;
+    row.dataset.enabled = String(root.enabled !== false);
+
+    const title = document.createElement('span');
+    title.dataset.role = 'name';
+    title.className = 'root-name';
+    title.textContent = `${root.name || root.id}${root.enabled === false ? '（已停用）' : ''}`;
+    row.append(title);
+
+    const pathEl = document.createElement('span');
+    pathEl.dataset.role = 'path';
+    pathEl.className = 'muted-hint root-path';
+    pathEl.textContent = root.path || '';
+    row.append(pathEl);
+
+    if (state.editingId === root.id) {
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.dataset.role = 'rename-input';
+      input.className = 'root-rename-input';
+      input.value = root.name || root.id;
+      row.append(input);
+      row.append(miniBtn('保存', 'rename-save', () => submitRename(root.id, input.value)));
+      row.append(miniBtn('取消', 'rename-cancel', () => { state.editingId = null; render(); }));
+      return row;
+    }
+
+    row.append(miniBtn('改名', 'rename', () => { state.editingId = root.id; render(); }));
+    row.append(miniBtn(root.enabled === false ? '启用' : '停用', 'toggle',
+      () => submitToggle(root.id, root.enabled === false)));
+
+    if (state.confirmingId === root.id) {
+      const ask = document.createElement('span');
+      ask.dataset.role = 'confirm';
+      ask.className = 'root-confirm-ask';
+    ask.textContent = '确认删除？';
+      row.append(ask);
+      row.append(miniBtn('确认删除', 'remove-confirm', () => submitRemove(root.id)));
+      row.append(miniBtn('取消', 'remove-cancel', () => { state.confirmingId = null; render(); }));
+    } else {
+      row.append(miniBtn('删除', 'remove', () => { state.confirmingId = root.id; render(); }));
+    }
+    return row;
+  }
+
+  /** 小按钮工厂：统一 class 与 dataset，便于断言按 data-role 定位 */
+  function miniBtn(text, role, onClick) {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'mini-btn';
+    btn.textContent = text;
+    btn.dataset.role = role;
+    btn.addEventListener('click', onClick);
+    return btn;
+  }
+
+  /** 用后端最新列表刷新（后端成功响应都带 rootsAll: 含停用项） */
+  function applyResult(data) {
+    const next = data && (data.rootsAll || data.roots);
+    if (Array.isArray(next)) render(next);
+    if (typeof onChanged === 'function') {
+      try { onChanged(data); } catch { /* 名册刷新失败不影响管理列表 */ }
+    }
+    return Array.isArray(next) ? next : state.roots;
+  }
+
+  /** 最近一次"添加资源根"的失败原因（空 = 上次成功或还没试过） */
+  let lastAddError = '';
+
+  // ------------------------------------------------------------------ 四个动作
+
+  /** 新增：path 必填（服务端绝对路径）；name 可空（空则用目录名） */
+  async function submitAdd(pathValue, nameValue) {
+    const path = String(pathValue || '').trim();
+    const name = String(nameValue || '').trim();
+    // 失败原因要能被目录选择对话框取到：它弹在屏幕中央，左栏那行提示在用户背后（实测用户看不到）。
+    //   返回值仍是布尔（既有调用方与测试都按布尔断言），文案另存一份。
+    const fail = (msg) => { lastAddError = msg; notify(msg, 'err'); return false; };
+    lastAddError = '';
+    if (!path) return fail('请填写要添加的目录（服务端绝对路径）');
+    const body = { action: 'add', path };
+    if (name) body.name = name;
+    const res = await post(body);
+    if (!res.ok) return fail(describeError(res.status, res.data, formatError));
+    const merged = !!(res.data && res.data.changed && res.data.changed.merged);
+    const root = (res.data && res.data.changed && res.data.changed.root) || {};
+    applyResult(res.data);
+    notify(merged
+      ? `已合并到同名根：${root.name || name || root.id}`
+      : `已添加资源根：${root.name || name || root.id}（${root.path || path}）`, 'ok');
+    return true;
+  }
+
+  /** 改名：命中已有名字时后端返回 merged:true —— 必须如实提示"已合并"，不能显示成改名成功 */
+  async function submitRename(id, nameValue, apiOnly = false) {
+    const name = String(nameValue || '').trim();
+    if (!apiOnly && !name) { notify('新名字不能为空', 'err'); return false; }
+    const res = await post({ action: 'rename', id, name });
+    if (!res.ok) { notify(describeError(res.status, res.data, formatError), 'err'); return false; }
+    const changed = (res.data && res.data.changed) || {};
+    state.editingId = null;
+    applyResult(res.data);
+    if (changed.merged) {
+      notify(`已合并到同名根「${changed.to}」（条目由 ${changedFrom(res)} 变为 ${(res.data.roots || []).length} 个）`, 'warn');
+    } else {
+      notify(`已改名为「${changed.to || name}」`, 'ok');
+    }
+    return true;
+  }
+
+  /** toggle 必须传真布尔，否则后端 400（字符串 "false" 会被拒） */
+  async function submitToggle(id, enabled) {
+    const res = await post({ action: 'toggle', id, enabled: enabled === true });
+    if (!res.ok) { notify(describeError(res.status, res.data, formatError), 'err'); return false; }
+    applyResult(res.data);
+    notify(`已${enabled === true ? '启用' : '停用'}：${id}`, 'ok');
+    return true;
+  }
+
+  /** 删除：界面上先二次确认，再发请求 */
+  async function submitRemove(id) {
+    const res = await post({ action: 'remove', id });
+    if (!res.ok) { notify(describeError(res.status, res.data, formatError), 'err'); return false; }
+    state.confirmingId = null;
+    applyResult(res.data);
+    notify(`已删除资源根：${id}`, 'ok');
+    return true;
+  }
+
+  /** 合并提示里需要"合并前后条目数"：后端不给 before，这里用 roots 数量差反推 */
+  function changedFrom(res) {
+    const after = (res.data && res.data.roots) || [];
+    return String(after.length + 1);
+  }
+
+  /** 目录浏览器的默认起点（上次添加的目录的父目录）；空则从 / 开始 */
+  let pickerStart = '';
+
+  // 「选择目录」：打开服务端目录浏览器，选完目录直接添加，面板里不填路径
+  if (els.triggerBtn) {
+    els.triggerBtn.addEventListener('click', () => {
+      if (!els.picker) { notify('目录浏览器未就绪', 'err'); return; }
+      els.picker.open(pickerStart);
+    });
+  }
+
+  // 管理区展开/收起
+  if (els.toggleBtn && els.body) {
+    els.toggleBtn.addEventListener('click', () => {
+      const open = els.body.hidden;
+      els.body.hidden = !open;
+      els.toggleBtn.setAttribute('aria-expanded', String(open));
+      els.toggleBtn.textContent = open ? '收起' : '管理';
+    });
+  }
+
+  return {
+    render, post, notify,
+    /** 目录浏览器实例（测试/排障用：open/goto/state） */
+    get picker() { return els.picker || null; },
+    /** 设置目录浏览器的默认起点（由装配方按现有根推算） */
+    setPickerStart(path) { pickerStart = String(path || ''); },
+    submitAdd, submitRename, submitToggle, submitRemove,
+    /** 最近一次添加失败的原因（对话框用它把错误显示在自己身上） */
+    getLastAddError: () => lastAddError,
+    get roots() { return state.roots; },
+    get last() { return state.last; },
+  };
+}

package/src/web/app/status.js

@@ -0,0 +1,138 @@
+// app/status.js —— 舞台状态行的唯一写入口
+//
+// 一条状态行有三个去处，全部由这里统一分发（顺序不能颠倒）：
+//   ① 进 window.__WEB__.stageLog（自动化断言的唯一真相，前端一切"发生了什么"都靠它）
+//   ② 进调试日志浮层的缓冲（若已建）
+//   ③ 按"显示状态信息"开关决定要不要写到舞台顶部那一行
+//
+// 为什么不让调用方自己写 DOM：状态行是"最近一次发生了什么"，多处各写一处必然漂移；
+//   而且 error/warn 必须始终可见，info 只在被要求时显示——这条策略只能有一份实现。
+
+import { dom, state } from './context.js';
+import { createLogger } from '../infra/log.js';
+
+// 适配层：状态行的文本同时进统一日志工厂（面板与"上传日志"只认工厂这一份）。
+//   注意：状态行的**展示策略**仍在本文件（什么时候写 stageHint），工厂只管"记一条"。
+const logStage = createLogger('stage');
+
+/**
+ * 记录一条状态行（**无条件执行**，与"显不显示"完全无关）。
+ *
+ * 记录有三个去处，缺一不可：
+ *   ① `window.__WEB__.stageLog` —— 自动化断言的唯一真相
+ *   ② 调试日志浮层的缓冲（面板看得到）
+ *   ③ 统一日志工厂（"上传日志"导出）—— 只有 `toLog` 为真的调用才进
+ *
+ * 为什么要单独抽出来：以前这条记录写在显示分支之后，两处 early return（没有 stageHint、
+ *   或「显示状态信息」被关掉）会**连日志一起跳过**。后果是：用户为了少看 UI 噪音关掉状态行，
+ *   真出问题想上传日志时恰好是空的——最需要日志的时刻没有日志。
+ *   现在记录在前、显示在后，开关只影响"看不看得见"，不影响"有没有记"。
+ *
+ * @param {'info'|'warn'|'error'} level
+ * @param {string} line 已转成字符串的文本
+ * @param {object} [detail] 结构化上下文（仅 toLog 时进工厂）
+ * @param {{toLog?: boolean}} [flags] toLog=true ⇒ 同时写入统一日志工厂
+ */
+function record(level, line, detail, flags) {
+  if (typeof window !== 'undefined' && window.__WEB__) {
+    const bag = (window.__WEB__.stageLog = window.__WEB__.stageLog || []);
+    bag.push({ at: Date.now(), level, line });
+    if (bag.length > 200) bag.shift();
+  }
+  try {
+    console.info(`%c[STAGE:${level}]`, 'color:#8b8b8b', line);
+  } catch { /* 控制台不可用时忽略 */ }
+  if (state.debugLogHandle && typeof state.debugLogHandle.log === 'function') {
+    try { state.debugLogHandle.log('STAGE', line, { level }); } catch { /* 日志失败不影响业务 */ }
+  }
+  if (!flags || flags.toLog !== true) return;
+  try {
+    const lv = level === 'warn' || level === 'error' ? level : 'info';
+    logStage[lv](line, detail);
+  } catch { /* 工厂异常不影响状态行 */ }
+}
+
+/**
+ * 按「显示状态信息」开关与级别决定要不要写舞台顶部那一行。
+ * 只碰 DOM，不碰任何日志通路。
+ * @param {string} line
+ * @param {'info'|'warn'|'error'} level
+ * @param {{show?: boolean}} opts
+ */
+function renderStatusLine(line, level, opts) {
+  const visible = state.showStatus !== false;
+  if (!dom.stageHint) return;
+  if (!visible) {
+    dom.stageHint.textContent = '';
+    dom.stageHint.hidden = true;
+    return;
+  }
+  const show = opts.show === true || level === 'error' || level === 'warn';
+  if (show) {
+    dom.stageHint.textContent = line;
+    dom.stageHint.hidden = false;
+  } else {
+    dom.stageHint.textContent = '';
+    dom.stageHint.hidden = true;
+  }
+}
+
+/**
+ * 写一条状态行（**只上状态行**，不额外记日志）。
+ *
+ * ---- 什么时候用 stageStatus、什么时候用 stageLog（总则，新增状态行前先读这段）----
+ * 判据：这句话说的是"**现在是什么**"还是"**刚刚发生了什么**"？
+ *   · "现在是什么"（设置回显 / 操作回执 / 进度 / 装载结果） → **stageStatus**
+ *     只占状态行，不额外记日志 —— 状态行本来就是"当前状态"，再记一条只会把日志刷屏。
+ *   · "刚刚发生了什么"（失败 / 被拒绝 / 跳过了什么） → **stageLog**
+ *     带结构化 detail 进面板与"上传日志"，排查时要靠它回溯。
+ * 例外：错误与告警类即使描述的是某种状态，也一律走 stageLog —— 人需要能回溯，不能只闪一下。
+ * 注意：日志不能走 console.error，否则页面错误统计会把正常状态当成异常。
+ * @param {string} text
+ * @param {'info'|'warn'|'error'} [level]
+ * @param {{show?: boolean}} [opts] show=true 表示这条 info 也要显示在状态行上
+ * @returns {string} 写进状态行的文本
+ */
+export function stageStatus(text, level = 'info', opts = {}) {
+  const line = String(text == null ? '' : text);
+  record(level, line, undefined, { toLog: false });
+  renderStatusLine(line, level, opts || {});
+  return line;
+}
+
+/**
+ * 写状态行 + 记一条**带结构化 detail** 的日志（(a) 类：既要人看见，也要进面板与上传）。
+ *
+ * 为什么单开一个入口：失败类与"预期内不可用"要进日志，而且必须带可排查上下文
+ *   （错误对象、输入、当前模型…）——纯文本的 stageStatus 记不出结构化字段。
+ *   **状态行的可见性策略不变**（error/warn 始终可见），日志记录也不受显示开关影响。
+ * @param {'info'|'warn'|'error'} level
+ * @param {string} text 人话（同时写进状态行与日志的 msg）
+ * @param {object} [detail] 结构化上下文（对象原样保留，不会被字符串化成 [object Object]）
+ * @param {{show?: boolean}} [opts] 同 stageStatus
+ * @returns {string} 写进状态行的文本
+ */
+export function stageLog(level, text, detail, opts) {
+  const lv = level === 'warn' || level === 'error' ? level : 'info';
+  const line = String(text == null ? '' : text);
+  record(lv, line, detail, { toLog: true });
+  renderStatusLine(line, lv, opts || {});
+  return line;
+}
+
+/**
+ * 向诊断探针上报一条"应用语义"事件（plugin.load / bundle.parse / model.mount 等）。
+ * 探针不在（未装/被禁用）时静默跳过——日志是旁路，不能影响主流程。
+ * @param {string} name 事件名（点号分隔，如 model.mount）
+ * @param {object} [data] 结构化字段
+ * @param {{level?: string, src?: string}} [opts]
+ */
+export function diagEvent(name, data, opts) {
+  try {
+    const diag = typeof window !== 'undefined' ? window.__DIAG__ : null;
+    if (!diag || typeof diag.event !== 'function') return null;
+    return diag.event(name, data || {}, opts || {});
+  } catch {
+    return null; // 上报失败不影响业务
+  }
+}