modelstage 0.0.0-stage → 0.5.24

package/src/web/roster/list.js

@@ -0,0 +1,276 @@
+// roster.js —— 名册数据层：资源根 → 模型列表 → 角色归并（M2）
+//
+// 做什么：
+//   1. 按资源根取模型清单（三类来源，按根的 kind 与扫描结果选择）；
+//   2. 取该根的角色名表并与其它根合并（同一份名表只取一次）；
+//   3. 把模型归并成「角色 → 变体」，规则固定（不各自发明）：
+//      · charKeyOf：去 cutscene_ 前缀 → 去 _hx 后缀 → 去尾部 _N（顺序不可换，见该文件注释）
+//      · assetCandidates：查表逐级放宽 原样 → 剥 _hx → 再剥 _N
+//      · 命中名表用英文名做分组键、标题显示「中文名 英文名」；未命中用 charKeyOf 结果兜底
+//      · 变体排序：立绘在前、技能（cutscene_）在后，再按资源名数字序
+//      · 角色排序：按显示名
+//   4. 本模块只做数据，不碰 DOM（DOM 在 roster-view.js），便于单独验证归并结果。
+//
+// 数据源选择（实测依据）：
+//   · 统一走 /api/catalog：它把 spine 模型、live2d 模型、容器单文件合并成一份清单，
+//     所以发现阶段不再按"根的 kind"猜该问哪个扫描器（同一个根可以混合内容）；
+//   · 容器单文件（资源包）由列举层用魔数标记 `container`，kind 取插件声明的产出类型；
+//     改取 /api/live2d/models。
+
+import { pickName } from '/shared/names.mjs';
+import { getJson } from '../infra/api.js';
+import { diagEvent } from '../app/status.js';
+// 类型显示名来自面元数据表（label 字段）
+import { byKind } from '../render/surfaces.js';
+
+/** 资源名后缀归一化候选（与 char-tree.js 的 ASSET_SUFFIX_PATTERNS 一致） */
+const ASSET_SUFFIX_PATTERNS = [/_hx$/i];
+
+/**
+ * 基础角色键：去 cutscene_ 前缀 → 去 _hx → 去尾部 _N。
+ * 顺序不可换：`dafeng_2_hx` 先剥 _N 会因结尾非数字而剥不动，必须先剥 _hx。
+ * @param {string} name
+ * @returns {string}
+ */
+export function charKeyOf(name) {
+  return String(name || '')
+    .replace(/^cutscene_/i, '')
+    .replace(/_hx$/i, '')
+    .replace(/_\d+$/, '');
+}
+
+/**
+ * 查表候选键（小写），逐级放宽：原样 → 剥 _hx → 再剥尾部 _N。
+ * @param {string} name
+ * @returns {string[]}
+ */
+export function assetCandidates(name) {
+  // 键 = 真实资源文件名，**保留原始大小写**（设计：名表键原样，不做归一）
+  const raw = String(name || '');
+  const out = [raw];
+  for (const re of ASSET_SUFFIX_PATTERNS) {
+    const prev = out[out.length - 1];
+    const next = prev.replace(re, '');
+    if (next && next !== prev) out.push(next);
+  }
+  const prev = out[out.length - 1];
+  const noNum = prev.replace(/_\d+$/, '');
+  if (noNum && noNum !== prev) out.push(noNum);
+  return out;
+}
+
+/** 名表合并容器：byAsset（资源名 → 角色 id）+ characters（id → 角色信息） */
+export function createNameIndex() {
+  return { byAsset: {}, characters: {}, cache: new Map() };
+}
+
+/**
+ * 把一份名表并进索引（多个资源根共用同一份名表时只并一次）。
+ * @param {{byAsset?: object, characters?: object}} index
+ * @param {{byAsset?: object, characters?: object}} table
+ */
+export function mergeNameTable(index, table) {
+  if (!table) return;
+  Object.assign(index.byAsset, table.byAsset || {});
+  Object.assign(index.characters, table.characters || {});
+  index.cache.clear(); // 合并后旧查询结果作废
+}
+
+/**
+ * 查角色名（带缓存）。命中返回 {name, costume}，未命中返回 null。
+ * @param {{byAsset: object, characters: object, cache: Map}} index
+ * @param {string} assetName
+ * @returns {{name: string, costume: string}|null}
+ */
+export function lookupName(index, assetName) {
+  // 精确匹配：资产名与名表键都按**原样**比对，不做小写归一（名表键 = 真实文件名）。
+  //   归一化会让「只差大小写的两个资产」被错误合并，也会掩盖名表里写错的键。
+  const raw = String(assetName || '');
+  if (index.cache.has(raw)) return index.cache.get(raw);
+  let hit = null;
+  if (index.byAsset && index.characters) {
+    for (const key of assetCandidates(raw)) {
+      // byAsset 的值就只是角色 id 字符串，没有别的形态
+      const id = index.byAsset[key];
+      const c = id ? index.characters[id] : null;
+      const name = c ? pickName(c.name) : '';
+      if (name) {
+        hit = { name, costume: c ? pickName(c.costume) : '' };
+        break;
+      }
+    }
+  }
+  index.cache.set(raw, hit);
+  return hit;
+}
+
+/**
+ * 取一个资源根的模型清单 —— **全仓唯一的 catalog 消费入口**。
+ *
+ * 为什么抽出来：此前有两处各写一遍、失败处理还不一致（url-params 静默吞 ⇒ 深链失效零提示；
+ *   roster 直接抛 ⇒ 上层各自 catch）。现在统一成：失败一律
+ *   ① 记一条 diag warn（带 root id 与原因）② 返回空清单 + 可读 reason（**不抛**），
+ *   由调用方按自己的语义决定"要不要把 reason 变成用户可见的失败状态"。
+ * 判据只看"有没有拿到 entries 数组"，**不看 HTTP 状态码**
+ *   （服务端对缺 root 的状态码正在从 404 改 400，按状态码写死会跟着坏）。
+ * `warnings` / `rootWarning` / `reason` 是**三档不同的东西**，别混：
+ *   · reason      = **拿不到清单**（rootId 不存在 / 5xx / 网络失败）—— 查询失败，可考虑重试
+ *   · rootWarning = **清单拿到了，但这一根自己的扫描有问题**（服务端结构化字段，正常根为 null）：
+ *                   路径不存在 / 不是目录 / 不可读 / 扫描失败 / 扫完没有任何条目。
+ *                   **这是唯一可以拿去拼用户提示的一档**（文案由服务端给，带 rootId、不含绝对路径）
+ *   · warnings    = 通用说明（如"有 2 个插件能解包"），**混着与根无关的内容**。
+ *                   拿它拼因果会得出"因为有两个插件所以没模型"这种错误结论 —— 只能进日志，不许进提示。
+ * @param {string} rootId
+ * @returns {Promise<{entries: object[], reason: string|null, warnings: string[], rootWarning: string|null}>}
+ */
+export async function fetchRootEntries(rootId) {
+  const id = String(rootId || '');
+  if (!id) return { entries: [], reason: '资源根 id 为空', warnings: [], rootWarning: null };
+  let data = null;
+  try {
+    data = await getJson(`/api/catalog?root=${encodeURIComponent(id)}`);
+  } catch (e) {
+    const why = (e && e.message) || String(e);
+    diagEvent('catalog.fail', { root: id, reason: why }, { level: 'warn', src: 'app' });
+    return { entries: [], reason: `清单取不到：${why}`, warnings: [], rootWarning: null };
+  }
+  const warnings = Array.isArray(data && data.warnings) ? data.warnings.map((w) => String(w)) : [];
+  // 服务端的结构化"这一根怎么了"（正常根 null）。**只透传，不在这里编文案**
+  const rootWarning = (data && typeof data.rootWarning === 'string' && data.rootWarning) ? data.rootWarning : null;
+  const entries = Array.isArray(data && data.entries) ? data.entries : null;
+  if (!entries) {
+    diagEvent('catalog.fail', { root: id, reason: '响应里没有 entries 数组' }, { level: 'warn', src: 'app' });
+    return { entries: [], reason: '清单响应里没有 entries 数组', warnings, rootWarning };
+  }
+  // 成功但一条都没有、且服务端明确说了这一根有问题 ⇒ 记一条 warn：
+  //   否则 UI 只会显示"该游戏没有可加载模型"，与"这个根真的没有模型"完全无法区分。
+  if (!entries.length && rootWarning) {
+    diagEvent('catalog.empty', { root: id, rootWarning }, { level: 'warn', src: 'app' });
+  }
+  return {
+    entries, reason: null, warnings, rootWarning,
+    // 服务端自报的清单来源（cache=命中清单缓存 / built=真扫盘重建）；老服务端没有这个字段时为 null。
+    //   只透传、不在这里推断 —— 前端拿不到"服务端是命中还是重建"的任何本地证据。
+    serverSource: (data && (data.source === 'cache' || data.source === 'built')) ? data.source : null,
+    // 后台形态探测还剩多少条待探（服务端 §八 的附加字段）。
+    //   **本次不做 UI**：这里只做透传，展示位由 view.js 挂到名册 state 上（见 state.probe 注释）。
+    //   老服务端没有这个字段 ⇒ null（不推断成 0，0 会被误读成"已探完"）。
+    probeRemaining: (data && Number.isFinite(data.probeRemaining)) ? Number(data.probeRemaining) : null,
+  };
+}
+
+/**
+ * 取一个资源根的模型清单。
+ * @param {{id: string, name: string, kind?: string}} root
+ * @returns {Promise<{models: object[], source: string}>}
+ * @throws 清单取不到时抛（上层 view.js 据此把该根标成 error 状态并显示原因，这条 UI 语义要保留）
+ */
+export async function loadRootModels(root) {
+  // 单一发现路径：/api/catalog 一次给出该根下的**全部**模型条目
+  //   （spine 模型 + live2d 模型 + 容器单文件），所以不必再"按根类型猜该问哪个扫描器"，
+  //   同一个根里既能放普通模型目录、也能放容器文件。
+  //   容器条目的 kind 由插件声明（解包后是什么内容），并带 `container` 标记供装载层解包用。
+  const { entries: models, reason, serverSource, probeRemaining } = await fetchRootEntries(root.id);
+  // 抛给上层：view.js 捕获后把根标成 status='error' + 显示 error 文案。
+  //   若这里改成"返回空清单不抛"，UI 会从"加载失败"退化成"这个根有 0 个模型"—— 信息反而更少。
+  if (reason) throw new Error(`${root.name || root.id}：${reason}`);
+  const containers = models.filter((m) => m.container).length;
+  diagEvent('bundle.parse', { root: encodeURIComponent(root.id), source: 'catalog', models: models.length, containers }, { level: 'info', src: 'app' });
+  // serverSource 只用于名册计时（perRoot.source），不参与渲染与缓存判断
+  // probeRemaining 同理只往上透传：名册把它挂在 state 上供将来面板读取（本次不做 UI）
+  return { models, source: 'catalog', serverSource: serverSource || null, probeRemaining: probeRemaining ?? null };
+}
+
+/**
+ * 取一个资源根的名表（未配置 names 时服务端返回 names:null，这里当作"没有名表"）。
+ * @param {string} rootId
+ * @returns {Promise<object|null>}
+ */
+export async function loadRootNames(rootId) {
+  try {
+    const r = await getJson(`/api/names?root=${encodeURIComponent(rootId)}`);
+    if (!r || !r.byAsset || !r.characters) return null;
+    return r;
+  } catch {
+    // 名表缺失/损坏不应阻断名册（无表时按资源名归组），但要把原因带给调用方显示
+    return null;
+  }
+}
+
+/** 变体标签：Spine / Live2D / 资源包（与 char-tree.js 的 variantLabel 语义一致） */
+export function variantLabel(m) {
+  if (!m) return 'Spine';
+  // 先判"是不是容器单文件"：它的 kind 现在是内容类型（live2d），
+  //   若先判 kind 就会把资源包标成 Live2D，用户看不出它是包。
+  if (m.container) return '资源包';
+  // 类型名查面元数据表的 label（加新面时不必再来这里补一个三元式）
+  const meta = byKind(m.kind);
+  return meta ? meta.label : 'Spine';
+}
+
+/**
+ * 变体行的主文本：服装名（名表）优先，无名表时退回目录名/资源名。
+ * @param {object} m
+ * @param {object|null} nm 名表命中结果
+ * @returns {{text: string, origName: string}}
+ */
+export function variantText(m, nm) {
+  const dirName = String(m.srcDir || '').split('/').slice(-1)[0] || '';
+  const origName = String(m.name || '');
+  const text = nm && nm.costume ? nm.costume : (dirName || origName);
+  return { text, origName };
+}
+
+/**
+ * 把一批模型归并成角色数组（照 char-tree.js 的 buildTree + finalizeTree 规则）。
+ * @param {object[]} models 同一游戏（可能来自多个资源根）的全部模型
+ * @param {object} nameIndex
+ * @param {string} [gameName] 游戏名；给了就拼进角色键（`char:游戏名|组名`，*   避免不同游戏下同名角色共用同一个展开键）
+ * @returns {{chars: object[], stats: {models: number, exact: number, suffix: number, miss: number}}}
+ */
+export function buildChars(models, nameIndex, gameName = '') {
+  const stats = { models: models.length, exact: 0, suffix: 0, miss: 0 };
+  const charMap = new Map();
+
+  for (const m of models) {
+    const nm = lookupName(nameIndex, m.name);
+    if (nm) {
+      // via 只用于统计：原样命中 vs 剥后缀后才命中
+      const keys = assetCandidates(m.name);
+      const hitKey = keys.find((k) => nameIndex.byAsset[k]);
+      stats[hitKey === keys[0] ? 'exact' : 'suffix'] += 1;
+    } else {
+      stats.miss += 1;
+    }
+    const groupName = nm ? nm.name : charKeyOf(m.name);
+    const key = gameName ? `char:${gameName}|${groupName}` : `char:${groupName}`;
+    if (!charMap.has(key)) {
+      charMap.set(key, {
+        key,
+        groupName,
+        // 标题就是显示名（旧表时代 nameZh 几乎全空，等价于直接取 groupName）
+        title: groupName,
+        variants: [],
+      });
+    }
+    charMap.get(key).variants.push({ model: m, nm });
+  }
+
+  const chars = [...charMap.values()];
+  for (const c of chars) {
+    // 组内：立绘（非 cutscene_）在前，其余按资源名数字序
+    c.variants.sort((a, b) => rankVariant(a.model) - rankVariant(b.model)
+      || String(a.model.name).localeCompare(String(b.model.name), undefined, { numeric: true }));
+    c.baseName = c.variants.length ? charKeyOf(String(c.variants[0].model.name || '')) : '';
+    c.iconUrl = c.variants.map((v) => v.model.iconUrl).find(Boolean) || null;
+  }
+  // 角色排序：按显示名
+  chars.sort((a, b) => a.title.localeCompare(b.title, undefined, { numeric: true }));
+
+  return { chars, stats };
+}
+
+/** 组内排序权重：技能/剧情变体（cutscene_）排后面 */
+function rankVariant(model) {
+  return /^cutscene_/i.test(String(model.name || '')) ? 1 : 0;
+}

package/src/web/roster/persist.js

@@ -0,0 +1,52 @@
+// roster/persist.js —— 名册展开态与"上次选中"的持久化
+//
+// 键名与结构（modelstage.tree-state.v1）：
+//   { games: [], chars: [], activeGame: '游戏名', lastByGame: { '游戏名': '变体id' }, lastModelId? }
+// 单独成模块的原因：读写逻辑与渲染无关，且 view.js 需要守住单文件行数上限。
+
+import * as uiState from '../app/ui-state.js';
+
+/**
+ * 名册状态存储键（**当前唯一键**，不是历史遗留）。
+ *
+ * 键名沿用项目早期命名，改名会让已有用户的"上次选中的模型/展开态"丢失，故保持不变；
+ * 读写统一经 app/ui-state 工厂代理，字段结构 `{games, chars, activeGame, lastByGame}` 不动。
+ */
+export const LS_KEY = uiState.TREE_STATE_KEY;
+
+/** 读展开态与上次选中（结构的 {games, chars, activeGame, lastByGame}） */
+export function readSaved() {
+  try {
+    const s = uiState.getTreeState();
+    return {
+      games: new Set(Array.isArray(s.games) ? s.games : []),
+      chars: new Set(Array.isArray(s.chars) ? s.chars : []),
+      activeGame: typeof s.activeGame === 'string' ? s.activeGame : null,
+      lastByGame: s.lastByGame && typeof s.lastByGame === 'object' ? s.lastByGame : {},
+      // 旧格式：只有单个 lastModelId（更早版本写入的），读出来用于兼容恢复
+      lastModelId: typeof s.lastModelId === 'string' ? s.lastModelId : null,
+    };
+  } catch {
+    return { games: new Set(), chars: new Set(), activeGame: null, lastByGame: {}, lastModelId: null };
+  }
+}
+
+/**
+ * 写展开态与每个游戏上次选中的变体（键名/结构沿用既有：activeGame 存游戏名）。
+ * @param {object} state 名册状态（读 expandedGames/expandedChars/activeGame/selected）
+ */
+export function saveState(state) {
+  try {
+    const s = readSaved();
+    const lastByGame = { ...s.lastByGame };
+    if (state.activeGame && state.selected) lastByGame[state.activeGame] = state.selected.modelId;
+    uiState.setTreeState({
+      games: [...state.expandedGames],
+      chars: [...state.expandedChars],
+      activeGame: state.activeGame || s.activeGame,
+      lastByGame,
+    });
+  } catch {
+    // 隐私模式等写不了就忽略：持久化是增强，不影响当前会话
+  }
+}

package/src/web/roster/reveal.js

@@ -0,0 +1,77 @@
+// roster/reveal.js —— 「定位当前角色」：把选中的那一行滚进可视区
+//
+// 三条纪律（F3）：
+//   ① 行已可见就不动 —— 绝大多数选中都不需要滚，乱跳反而干扰阅读
+//   ② 用户正在滚 / 刚滚过 SCROLL_IDLE_MS 内不滚 —— 绝不跟用户抢滚动位置
+//   ③ 目标被折叠时不硬滚，先按"展开状态"把父级展开（渲染出这一行）再滚
+//
+// 为什么单独成模块：这段是纯"滚动策略"，与树的渲染/数据加载无关，拆开后 view.js 也能守住行数上限。
+
+/** 用户停手多久之后才允许自动滚动（毫秒） */
+export const SCROLL_IDLE_MS = 800;
+
+/**
+ * 创建定位控制器。
+ * @param {{listEl: HTMLElement, getState: () => object, render: () => void}} deps
+ *   getState 返回名册状态（expandedGames / expandedChars / selected）
+ *   render   重新渲染整棵树（展开父级后需要它把目标行画出来）
+ */
+export function createReveal({ listEl, getState, render }) {
+  // 自己触发的 scrollIntoView 也会派发 scroll 事件：用它区分"用户的滚"与"我们的滚"
+  let autoScrollUntil = 0;
+  let lastUserScrollAt = 0;
+
+  /** 记录一次"用户滚动"（程序触发的滚动不计） */
+  function markUserScroll() {
+    if (Date.now() < autoScrollUntil) return;
+    lastUserScrollAt = Date.now();
+  }
+
+  /** 挂上用户滚动信号：滚轮 / 触摸 / 指针按下 / 滚动条拖动（scroll 事件同时覆盖键盘与拖滚动条） */
+  function attachUserScrollListeners() {
+    listEl.addEventListener('scroll', markUserScroll, { passive: true });
+    listEl.addEventListener('wheel', markUserScroll, { passive: true });
+    listEl.addEventListener('touchstart', markUserScroll, { passive: true });
+    listEl.addEventListener('pointerdown', markUserScroll, { passive: true });
+  }
+
+  /**
+   * 把当前选中的变体行滚进可视区。
+   * @returns {'visible'|'scrolled'|'skipped-user-scrolling'|'no-selection'|'no-row'}
+   *   visible：本来就在可视区，没动；skipped-user-scrolling：用户正在滚，主动让位
+   */
+  function revealActive() {
+    const state = getState();
+    const selected = state && state.selected;
+    if (!selected || !selected.modelId) return 'no-selection';
+    // ③ 折叠时先展开父级：没渲染出这一行，后面也就无从滚起
+    let expanded = false;
+    if (selected.gameKey && !state.expandedGames.has(selected.gameKey)) {
+      state.expandedGames.add(selected.gameKey);
+      expanded = true;
+    }
+    if (selected.charKey && !state.expandedChars.has(selected.charKey)) {
+      state.expandedChars.add(selected.charKey);
+      expanded = true;
+    }
+    if (expanded) render();
+    // 按 dataset 值逐个比对：模型 id 里可能有引号等字符，拼选择器不可靠
+    const row = [...listEl.querySelectorAll('[data-model-id]')]
+      .find((node) => node.dataset.modelId === selected.modelId);
+    if (!row) return 'no-row';
+    const box = listEl.getBoundingClientRect();
+    const r = row.getBoundingClientRect();
+    if (r.top >= box.top - 1 && r.bottom <= box.bottom + 1) return 'visible'; // ① 已可见
+    if (Date.now() - lastUserScrollAt < SCROLL_IDLE_MS) return 'skipped-user-scrolling'; // ② 不抢
+    autoScrollUntil = Date.now() + 300;
+    row.scrollIntoView({ block: 'nearest' });
+    return 'scrolled';
+  }
+
+  /** 只读：最近一次用户滚动距今毫秒（断言用） */
+  function sinceUserScroll() {
+    return Date.now() - lastUserScrollAt;
+  }
+
+  return { revealActive, markUserScroll, attachUserScrollListeners, sinceUserScroll };
+}

package/src/web/roster/rows.js

@@ -0,0 +1,248 @@
+// roster-rows.js —— 名册三级树的「行」渲染（纯 DOM 工厂，无状态）（M2）
+//
+// 做什么：把一条树数据渲染成一个可点击的 treeitem 行，三级别各一个函数。
+// 为什么单独一个文件：
+//   1. 单文件 ≤400 行的硬约束（视图逻辑 + 行结构放一起会超）；
+//   2. 职责分离：本文件只管"一行长什么样"，roster-view.js 只管"状态怎么变、事件怎么派"。
+// 约定：每行都带 data-* 标识与 tabindex=0（键盘可达），事件由 roster-view.js 在容器上委托。
+
+import { variantLabel, variantText } from './list.js';
+
+// el 的唯一实现在 infra/dom.js。
+//   本文件自己要用它（rowBase 等 15 处），所以必须 import 绑定到本地作用域；
+//   同时对外转发导出，roster/view.js 的 `import { el, ... } from './rows.js'` 无需改动。
+//   注意：只写 `export { el } from '...'` 是**不绑定本地**的 —— 那些内部调用会变成 undefined。
+import { el } from '../infra/dom.js';
+// 名册徽标的配色类来自面元数据表（badge 字段）
+import { byKind } from '../render/surfaces.js';
+
+export { el };
+
+/** 建一个树行骨架（三级别共用：data 属性 + treeitem 语义 + 键盘可达） */
+function rowBase(className, dataset) {
+  const row = el('div', `tree-row ${className}`);
+  Object.assign(row.dataset, dataset);
+  row.setAttribute('role', 'treeitem');
+  row.tabIndex = 0; // 键盘可达：Enter/空格与点击等价
+  return row;
+}
+
+/**
+ * 展开箭头：内联 SVG 而不是 ▸/▾ 文字。
+ * 为什么不用文字：无桌面字体环境（无头 chromium / 精简系统）里 ▸ ▾ 会渲染成豆腐块，
+ *   而它是"能不能展开"的唯一视觉提示，必须稳定可见。
+ * @param {boolean} open
+ */
+function arrowEl(open) {
+  const NS = 'http://www.w3.org/2000/svg';
+  const svg = document.createElementNS(NS, 'svg');
+  svg.setAttribute('viewBox', '0 0 16 16');
+  svg.setAttribute('class', 'tree-arrow');
+  svg.setAttribute('aria-hidden', 'true');
+  const path = document.createElementNS(NS, 'path');
+  path.setAttribute('d', open ? 'M4 6l4 4 4-4' : 'M6 4l4 4-4 4');
+  path.setAttribute('fill', 'none');
+  path.setAttribute('stroke', 'currentColor');
+  path.setAttribute('stroke-width', '2');
+  path.setAttribute('stroke-linecap', 'round');
+  path.setAttribute('stroke-linejoin', 'round');
+  svg.append(path);
+  return svg;
+}
+
+/**
+ * 一级：游戏行（按资源根配置的 name 合并后的节点）。
+ * 一个游戏可能由多个资源根供给（碧蓝航线 = 3 个根），所以徽标显示根数量、title 列出具体根 id，
+ * 数据属性 data-root-ids 供自动化断言核对"这些根都在同一个游戏节点下"。
+ * @param {{key: string, name: string, roots: object[]}} game
+ * @param {{open: boolean, status: string, charCount: number}} view
+ */
+export function renderGameRow(game, view) {
+  const rootIds = game.roots.map((r) => r.id);
+  const row = rowBase('tree-game', { gameKey: game.key, rootIds: rootIds.join(',') });
+  row.setAttribute('aria-expanded', String(view.open));
+  if (view.open) row.classList.add('is-open');
+
+  row.append(arrowEl(view.open));
+  row.append(el('span', 'tree-game-name', game.name));
+  // 多根时标注根数（单根不标注，避免噪音）
+  if (rootIds.length > 1) {
+    const badge = el('span', 'tree-badge', `${rootIds.length} 根`);
+    badge.title = rootIds.join(' · ');
+    row.append(badge);
+  } else {
+    row.append(el('span', 'tree-badge', rootIds[0] || ''));
+  }
+
+  if (view.status === 'ready') row.append(el('span', 'tree-count', `${view.charCount} 角色`));
+  else if (view.status === 'loading') row.append(el('span', 'tree-count', '加载中…'));
+  return row;
+}
+
+/**
+ * 二级：角色行（头像 + 显示名 + 原名标签 + 变体数）。
+ * @param {object} game
+ * @param {object} c 角色（title/baseName/iconUrl/variants）
+ * @param {boolean} open
+ */
+export function renderCharRow(game, c, open) {
+  const row = rowBase('tree-char', { charKey: c.key, gameKey: game.key });
+  row.setAttribute('aria-expanded', String(open));
+  if (open) row.classList.add('is-open');
+
+  row.append(arrowEl(open));
+
+  if (c.iconUrl) {
+    const img = document.createElement('img');
+    img.className = 'tree-icon';
+    img.src = c.iconUrl;
+    img.alt = '';
+    img.loading = 'lazy';
+    img.decoding = 'async';
+    row.append(img);
+  } else {
+    row.append(el('span', 'tree-icon'));
+  }
+
+  row.append(el('span', 'tree-char-title', c.title));
+  // 「原名」标签：归一化键与显示名不同才有信息增量（照 char-tree.js 的去重规则）
+  if (c.baseName && c.baseName !== String(c.title)) row.append(el('span', 'tree-orig', c.baseName));
+  row.append(el('span', 'tree-count', c.variants.length));
+  return row;
+}
+
+/**
+ * 三级：变体行（类型标签 + 服装名/目录名 + 原名后缀）。
+ * 行上带 data-root-id：证明同一角色节点下确实聚合了来自不同资源根的变体。
+ * @param {object} game
+ * @param {object} c
+ * @param {{model: object, nm: object|null}} v
+ * @param {string|null} selectedId 当前选中的模型 id
+ */
+export function renderVariantRow(game, c, v, selectedId) {
+  const m = v.model;
+  const { text, origName } = variantText(m, v.nm);
+  const row = rowBase('tree-variant', {
+    modelId: m.id, gameKey: game.key, charKey: c.key, rootId: m.rootId || '',
+  });
+
+  const isSelected = selectedId === m.id;
+  if (isSelected) {
+    row.classList.add('is-selected');
+    row.setAttribute('aria-selected', 'true');
+  }
+
+  const label = variantLabel(m);
+  // 样式类只用来分组（容器单文件用 bundle 类），**不带颜色**。
+  //   颜色/归属/可装载性/失败原因全部来自服务端三字段（契约 §一 INV-D1）：
+  //     display.accent  徽标底色（null ⇒ 中性色）
+  //     display.provider 归属提供者 id（展示名按 /api/plugins 的 label 查）
+  //     display.candidates 候选提供者（按 matchPriority 降序）
+  //     support.state   ready | unknown | unsupported
+  //     support.detail  不支持时的 { reason, message }（与装载失败文案同源）
+  //     loadResult      最近一次真实装载尝试的结果
+  //   前端**不做任何判定**：不按 kind 猜色、不自己算"能不能装"、不读 localStorage。
+  const meta = byKind(m.kind);
+  const kindClass = m.container ? 'bundle' : (meta ? meta.badge : 'spine');
+  const typeBadge = el('span', `tree-type tree-type-${kindClass}`, label);
+  const display = (m && m.display) || {};
+  if (display.accent) typeBadge.style.setProperty('--badge-accent', String(display.accent));
+  // 悬浮文案：归属定了说"谁"，没定就把候选列出来（用户悬停就知道该找哪个插件）
+  const cands = Array.isArray(display.candidates) ? display.candidates : [];
+  if (display.provider) typeBadge.title = `归属：${display.provider}`;
+  else if (cands.length) typeBadge.title = `归属待定（候选：${cands.join('、')}）`;
+  row.append(typeBadge);
+  row.append(el('span', 'tree-variant-text', text));
+  if (origName && origName !== text) row.append(el('span', 'tree-variant-orig', ` · ${origName}`));
+
+  // ⚠ 只有一处来源：support 判"装不动"，或 loadResult 判"上次失败"。
+  //   两者的文案都由服务端给（support.detail.message / loadResult.message），前端只展示。
+  //   契约保证 support.unsupported 与 loadResult.ok 不并存 ⇒ 这里不会出现"一边说不行一边说刚成功"。
+  const support = (m && m.support) || {};
+  const loadResult = (m && m.loadResult) || null;
+  const warnText = (support.state === 'unsupported' && support.detail && support.detail.message)
+    ? String(support.detail.message)
+    : (loadResult && loadResult.result === 'failed'
+      ? String(loadResult.message || loadResult.reason || '装载失败')
+      : '');
+  if (warnText) {
+    const badge = el('span', 'tree-variant-warn', '⚠');
+    // 打标记：applyEntryState 就地刷新时**只认这个标记**找回已有的 ⚠。
+    //   不打的话它会以为"这行还没有警告"，于是再 append 一个 ⇒ 同一行挂两个 ⚠（实测踩过）。
+    badge.dataset.entryWarn = '1';
+    badge.title = warnText;
+    row.append(badge);
+    row.classList.add('is-incomplete');
+  }
+  row.title = `${origName}${m.srcDir && m.srcDir !== origName ? `  ·  ${m.srcDir}` : ''}${warnText ? `\n⚠ ${warnText}` : ''}`;
+  return row;
+}
+
+/**
+ * 按条目**就地**刷新徽标：只动命中那一行，**不重渲染整棵名册**。
+ *
+ * 为什么不能整棵重渲染：名册是带展开态 / 选中态 / 滚动位置的树，
+ *   重渲染会把这三样全部丢掉 —— 用户看到的是"点一下模型，列表跳回顶部、节点全折叠"。
+ *
+ * 服务端返回的 display/support/loadResult 是唯一真相（契约 §一 INV-D1）：
+ *   本函数只把三个字段"画"到那一行，不接收前端自造的失败记录、不猜颜色。
+ *   ⇒ 装载成功后服务端 recompute 一变，照着画就对（这就是"当场变色"的全部机制）。
+ *
+ * @param {object} model 名册条目（只需 id / name）
+ * @param {{display?:object, support?:object, loadResult?:object}|null} entryState 服务端三字段；
+ *        null/缺省 = 该条目已无状态（等价于全部清空）
+ * @returns {boolean} 命中并处理了返回 true；该条目当前不在名册里（被折叠/搜索过滤）返回 false
+ */
+export function applyEntryState(model, entryState) {
+  const id = String((model && (model.id || model.name)) || '');
+  if (!id) return false;
+  // 不用属性选择器：条目 id 里常有空格 / 斜杠 / 引号，拼进选择器必须转义，
+  //   而 CSS.escape 不是所有环境都有。名册数百行量级，直接遍历更稳也更清楚。
+  let row = null;
+  for (const candidate of document.querySelectorAll('.tree-row.tree-variant')) {
+    if (candidate.dataset && candidate.dataset.modelId === id) { row = candidate; break; }
+  }
+  if (!row) return false;
+
+  const st = entryState || {};
+  const display = st.display || {};
+  const support = st.support || {};
+  const loadResult = st.loadResult || null;
+
+  // ① 徽标颜色：只认 display.accent（null ⇒ 中性色，绝不按 kind 猜）
+  const typeBadge = row.querySelector('.tree-type');
+  if (typeBadge) {
+    if (display.accent) typeBadge.style.setProperty('--badge-accent', String(display.accent));
+    else typeBadge.style.removeProperty('--badge-accent');
+    const cands = Array.isArray(display.candidates) ? display.candidates : [];
+    if (display.provider) typeBadge.title = `归属：${display.provider}`;
+    else if (cands.length) typeBadge.title = `归属待定（候选：${cands.join('、')}）`;
+    else typeBadge.title = '';
+  }
+
+  // ② ⚠：support 说"装不动" 或 loadResult 说"上次失败"；文案由服务端给
+  const warnText = (support.state === 'unsupported' && support.detail && support.detail.message)
+    ? String(support.detail.message)
+    : (loadResult && loadResult.result === 'failed'
+      ? String(loadResult.message || loadResult.reason || '装载失败')
+      : '');
+  const existing = row.querySelector('[data-entry-warn="1"]');
+  if (warnText) {
+    if (existing) existing.title = warnText;
+    else {
+      const badge = el('span', 'tree-variant-warn', '⚠');
+      badge.dataset.entryWarn = '1';
+      badge.title = warnText;
+      row.append(badge);
+    }
+    row.classList.add('is-incomplete');
+  } else {
+    if (existing) existing.remove();
+    if (!row.querySelector('.tree-variant-warn')) row.classList.remove('is-incomplete');
+  }
+
+  // ③ 行级 title：正文（原名 / 目录）原样保留，只替换末尾那句警告
+  const baseTitle = String(row.title || '').replace(/\n⚠ [^\n]*$/, '');
+  row.title = warnText ? `${baseTitle}\n⚠ ${warnText}` : baseTitle;
+  return true;
+}