modelstage 0.0.0-stage → 0.5.28

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,92 @@
+// roster/persist.js —— 名册展开态与"上次选中"的持久化
+//
+// 键名与结构（modelstage.tree-state.v1）：
+//   { games: [], chars: [], activeGame: '游戏名', lastByGame: { '游戏名': '变体id' }, lastModelId? }
+// 单独成模块的原因：读写逻辑与渲染无关，且 view.js 需要守住单文件行数上限。
+
+import * as uiState from '../app/ui-state.js';
+
+/**
+ * 类型筛选的存储键。
+ *
+ * 为什么不并进 TREE_STATE_KEY：两者的生命周期不同——展开态是"临时视图状态"，
+ *   类型筛选是跨会话保留的选择；分开存也让"读不懂的值直接忽略"只影响筛选，不牵动整棵树。
+ */
+export const TYPE_FILTER_KEY = 'roster.typeFilter';
+
+/**
+ * 名册状态存储键（**当前唯一键**，不是历史遗留）。
+ *
+ * 键名沿用项目早期命名，改名会让已有用户的"上次选中的模型/展开态"丢失，故保持不变；
+ * 读写统一经 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 {
+    // 隐私模式等写不了就忽略：持久化是增强，不影响当前会话
+  }
+}
+
+/**
+ * 读类型筛选的选中集合（数组；读不到/形状不对一律当空）。
+ * 注意：这里**不校验 key 是否仍然有效**——失效项的忽略发生在渲染期（见 roster/type-filter.js
+ *   的 usableTypeSelection），这样存储里的值不会被我们悄悄删掉。
+ * @returns {string[]}
+ */
+export function readTypeFilter() {
+  try {
+    const raw = localStorage.getItem(TYPE_FILTER_KEY);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((key) => typeof key === 'string' && key) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 写类型筛选（失败静默：筛选是增强，隐私模式/配额满都不该影响当前会话）。
+ * @param {Iterable<string>} keys
+ * @returns {boolean} 是否写入成功（调用方一般不需要它，测试用）
+ */
+export function saveTypeFilter(keys) {
+  try {
+    const list = [...(keys || [])].map(String).filter(Boolean);
+    localStorage.setItem(TYPE_FILTER_KEY, JSON.stringify(list));
+    return true;
+  } catch {
+    return false;
+  }
+}

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 };
+}