modelstage 0.5.24 → 0.6.1

package/src/web/roster/view.js

@@ -1,506 +1,119 @@
-// roster-view.js —— 名册视图层：三级树（游戏 → 角色 → 变体）+ 搜索 + 选中态（M2）
+// roster-view.js —— 名册视图层（M2）：三级树（游戏 → 角色 → 变体）+ 搜索 + 选中态
 //
-// 做什么：
-//   1. 一级：按资源根配置的 name 合并成游戏节点（同名根合并）；展开该游戏时才请求其各根模型；
-//   2. 二级：角色跨根归并——同一角色在多个根下的模型归到一个角色节点（不是把各根的行拼起来）；
-//   3. 三级：变体（模型）。行上带类型标签（Spine / Live2D / 资源包）与来源根 id；
-//   4. 搜索：前端过滤（角色名 / 服装名 / 资源名 / 目录名），命中即自动展开到变体层；
-//   5. 选中态：点变体行高亮并记录（M4 渲染用），状态写 localStorage（键名/结构沿用既有）；
-//   6. 顶部「收起」只清空展开状态，面板本身保留（面板显隐由顶栏「模型库」按钮控制）。
-//
-// 状态全部收在 state 里，DOM 只是投影：这样"点一下到底改了什么"可以直接读 state 验证。
+// 本文件只做**装配**（拆分后）：store.js = 名册唯一状态持有者；load.js = 加载编排；render.js = 渲染；
+//   events.js = DOM 事件。依赖方向（单向，无环）：store ← load ← render/events ← view。
+// 产品行为（与拆分前一致）：① 一级按资源根 name 合并成游戏节点（同名根合并，展开时才请求模型）；
+//   ② 二级角色跨根归并（同一角色多根模型归到一个节点，不是把各根的行拼起来）；
+//   ③ 三级变体带类型标签（Spine / Live2D / 资源包）与来源根 id；④ 搜索是前端过滤，命中即展开到变体层；
+//   ⑤ 选中态写 localStorage（键名沿用既有，字段用 group 口径）；⑥ 顶部「收起」只清空展开状态，面板本身保留。
 
 import { createReveal } from './reveal.js';
-import { visibleChars } from './filter.js';
 import { snapshotRoster } from './snapshot.js';
-import { readSaved, saveState } from './persist.js';
-import {
-  createNameIndex, mergeNameTable, loadRootModels, loadRootNames, buildChars,
-} from './list.js';
-import { el, renderGameRow, renderCharRow, renderVariantRow, applyEntryState } from './rows.js';
-import { formatError } from '../infra/api.js';
-// 名册就绪那句 info 走项目统一的日志通道（与 catalog/bundle 那些 diag 同一出口）
-import { stageLog } from '../app/status.js';
-// 渲染调度（rAF 合批 + 后台标签页兜底）抽到公共层，行为与原先内联实现一致
+import { createRosterStore } from './store.js';
+import { readSaved, saveState, readLastModel, saveLastModel } from './persist.js';
+import { createNameIndex, buildChars } from './list.js';
+import { applyEntryState } from './rows.js';
 import { createScheduler } from '../infra/schedule.js';
-// 容器条目的装载失败记忆：渲染时读出注入行渲染（保持 rows.js 的"纯 DOM 工厂"性质）
-
-/** localStorage 键名：不得改名（M7 要用它做持久化，改名会让用户既有状态失效） */
-
-/** 渲染上限：每个游戏最多渲染多少角色行（避免 2000+ 角色一次铺满）。
- *  默认值只是兜底，可用 window.__WEB_CONFIG__.renderLimitPerGame 覆盖 */
-const RENDER_LIMIT_DEFAULT = 400;
-function renderLimitPerGame() {
-  const custom = Number(window.__WEB_CONFIG__ && window.__WEB_CONFIG__.renderLimitPerGame);
-  return Number.isFinite(custom) && custom > 0 ? custom : RENDER_LIMIT_DEFAULT;
-}
-
-/**
- * 名册状态：games 是按 name 合并后的游戏列表；loaded 按资源根缓存加载结果；
- * gameChars 按游戏缓存跨根归并后的角色；expandedGames/expandedChars 是两级展开键；
- * keyword 是搜索词；selected 是当前选中变体；activeGame 是最后活跃的游戏名。
- */
+import { createRosterLoad } from './load.js';
+import { createRosterRender } from './render.js';
+import { createRosterEvents } from './events.js';
 
 /** 创建名册视图并挂到容器上；返回对外 API（供 main.js 与自动化验证使用） */
 export function createRosterView({ listEl, countEl, searchEl, collapseBtn, onSelect }) {
-  const state = {
-    games: [],
-    loaded: new Map(),
-    gameChars: new Map(),
-    expandedGames: new Set(),
-    expandedChars: new Set(),
-    keyword: '',
-    selected: null,
-    activeGame: null,
-    /**
-     * 后台形态探测的进度快照（**本次不做 UI，数据先就绪**）。
-     *
-     * 将来要加面板/进度条时，**直接读这里，不用再改服务端**：
-     *   state.probe = { remaining, at, rootId }
-     *     remaining 剩余待探条目数（服务端 probeRemaining 原值；null = 老服务端没这字段）
-     *     at        这次取到它的时间戳（性能无关，只用于判断"多久没更新了"）
-     *     rootId    最近一次刷新它的资源根（每列一个根都会刷新，值是**全局**队列深度）
-     * 读法示例：`window.__WEB__.state.roster.state.probe.remaining`
-     * 更细的计数（runs/probed/unsupported/unknown/skipped/lastBatchMs/lastTrigger）
-     *   走 `GET /api/entries/probe`，那才是权威，这里只是"最近一次 catalog 响应顺带回来的"。
-     */
-    probe: { remaining: null, at: null, rootId: null },
-  };
-  // 定位控制器：把"选中后滚到可见"的策略外置（见 roster/reveal.js）
-  /**
-   * 调试计数器（**纯计量**，只做 ++，不影响任何调度与渲染结果）。
-   * 用途：首屏渲染次数是"每个根各触发一次全树 render"这个性能问题的直接指标，
-   *   优化前后必须用同一口径对比（见 __WEB__ 侧的 counters() 取数）。
-   */
-  const counters = { render: 0, ensureRootLoaded: 0, renderScheduled: 0 };
-
-  // ------------------------------------------------------------ 名册加载计时（A）
-  //
-  // 口径（写清是为了以后不要"人均一套秒表"）：
-  //   · 起点 = 第一次调用 ensureRootLoaded（第一个根开始取 catalog）
-  //   · 终点 = **所有已知根都 settle**（ready 与 error 都算 settle）
-  //     为什么把 error 也算：不然一个根失败会让总时长永远不结束，这个数就永远出不来。
-  //   · 计时一律 performance.now()（单调），不用 Date.now()（会被系统时间校准拉走）。
-  //   · 不做阈值判断、不认根名：这里只报事实。
-  let rosterT0 = null;
-  /** rootId → { rootId, ms, count, source, at, error? }（同一根只留最新一次） */
-  const rosterPerRoot = new Map();
-  /** 「名册就绪」只打一次：之后再有根被补加载（懒加载/搜索）不再重复刷屏 */
-  let rosterLogged = false;
+  // 类型胶囊行：容器由 index.html 提供（#roster-type-filter）；取不到（旧页面/单测）就整体降级为"没有类型筛选"
+  const typeFilterEl = typeof document !== 'undefined' ? document.getElementById('roster-type-filter') : null;
 
-  /** 记一个根的加载结果；若此刻所有已知根都已 settle，打一条 info 日志并定稿 */
-  function recordRootLoad(rootId, t0, count, source, error) {
-    rosterPerRoot.set(String(rootId), {
-      rootId: String(rootId),
-      ms: Math.round(performance.now() - t0),
-      count: Number(count) || 0,
-      source: error ? 'error' : (source || 'built'),
-      at: Date.now(),
-      ...(error ? { error: String(error) } : {}),
-    });
-    if (rosterLogged) return;
-    const all = state.games.flatMap((g) => g.roots.map((r) => String(r.id)));
-    if (!all.length || !all.every((id) => rosterPerRoot.has(id))) return;
-    rosterLogged = true;
-    // 延后一拍再取数：根 settle 的那一刻，调用方（ensureGameLoaded）的
-    //   「跨根归并角色」还没跑（它在 await 之后才执行），此刻取 chars 会偏小，
-    //   导致日志里的角色数与 rosterStats() 对不上。放到宏任务里取，归并已完成。
-    setTimeout(() => {
-      const s = rosterStats();
-      // 走既有 say/log 通道（与 catalog/bundle 那些 diag 同一出口），文案里不带路径与根名
-      stageLog('info', `名册就绪：${s.roots} 根 / ${s.chars} 角色 / ${s.ms} ms`, {
-        tag: 'roster', roots: s.roots, entries: s.entries, chars: s.chars, ms: s.ms,
-        slowest: s.perRoot.slice().sort((a, b) => b.ms - a.ms).slice(0, 3),
-      });
-    }, 0);
-  }
-
-  /**
-   * 名册加载统计快照（`window.__WEB__.rosterStats()` 的实现在这里）。
-   *
-   * 主要用途是**看哪一根慢/失败**：perRoot 按实际加载顺序给出每根的耗时与来源，
-   *   `source` 的 cache/built 来自服务端 `/api/catalog` 的自报（前端拿不到这个证据），
-   *   失败根为 `error` 并带 `error` 文本 —— 失败绝不从表里消失。
-   * @returns {{at: number|null, ms: number, roots: number, entries: number, chars: number,
-   *            perRoot: Array<{rootId: string, ms: number, count: number, source: string, at: number, error?: string}>}}
-   */
-  function rosterStats() {
-    const perRoot = [...rosterPerRoot.values()].map((r) => ({ ...r }));
-    let chars = 0;
-    for (const v of state.gameChars.values()) chars += Array.isArray(v && v.chars) ? v.chars.length : 0;
-    // 汇总只算**名册自己的根**：perRoot 允许出现额外条目（别的调用方加载过某个根），
-    //   但那不属于"名册加载"，算进来会让 roots/entries 与左栏数字对不上。
-    const named = new Set(state.games.flatMap((g) => g.roots.map((r) => String(r.id))));
-    const mine = perRoot.filter((r) => named.has(r.rootId));
-    return {
-      at: mine.length ? Math.max(...mine.map((r) => r.at)) : null,
-      // 全部根还没 settle 时给"到目前为止"的耗时：仍是有意义的读数，不是假值
-      ms: rosterT0 === null ? 0 : Math.round(performance.now() - rosterT0),
-      roots: named.size,
-      entries: mine.reduce((s, r) => s + r.count, 0),
-      chars,
-      perRoot,
-    };
-  }
+  /** 调试计数器（纯计量，只做 ++）：首屏渲染次数是"每个根各触发一次全树 render"的直接指标，优化前后同口径对比 */
+  const counters = { render: 0, ensureRootLoaded: 0, renderScheduled: 0 };
 
-  // ------------------------------------------------------------ 渲染调度（rAF 合并）
-  // 加载阶段每条路径都会触发一次全树重绘（N 个资源根 ≈ 2N+ 次），中间态在同一帧里根本看不到；
-  //   合批后既省时间也减少闪烁。三条性质与"为什么"见 infra/schedule.js 的文件头。
-  // 这里只保留两样名册专属的东西：跑什么（render）与计量钩子（renderScheduled）。
+  // 渲染调度（rAF 合批 + 后台标签页兜底）：三条性质与"为什么"见 infra/schedule.js 文件头
   const scheduler = createScheduler(() => render(), { onRequest: () => { counters.renderScheduled += 1; } });
   const scheduleRender = scheduler.request;
   const flushRender = scheduler.flush;
 
+  // 名表索引（跨根共用一份）：store 写完 models 要自动重算角色树，归并时也要用它 ⇒ 先于 store 建
+  const nameIndex = createNameIndex();
+  // 名册状态由 store 统一持有（**唯一可写者**）；view 只读 state、通过动作改
+  const store = createRosterStore({ buildChars, nameIndex, onChange: () => scheduleRender() });
+  const state = store.state;
+  // 定位控制器：把"选中后滚到可见"的策略外置（见 roster/reveal.js）
   const reveal = createReveal({ listEl, getState: () => state, render: () => render() });
 
-  const nameIndex = createNameIndex();
+  // 名册持有的模型对象（渲染与选中都读它，跨模块共用同一份引用）
   const namesLoaded = new Set();
   const modelById = new Map();
 
-  // ------------------------------------------------------------ 数据加载
-
-  /** 上一次写进调试日志的"剩余待探"数（只用来去重：数值没变就不再记一行） */
-  let lastLoggedProbeRemaining = null;
-
-  /**
-   * 记录后台形态探测的进度：写进 state.probe（**给将来 UI 读**），并在数值变化时记一行日志。
-   *
-   * 为什么只在变化时记：一次启动会按根拉九次 catalog，每根都记一行会把调试面板刷满同类信息；
-   *   真正有用的是"剩余数发生变化"这个事件。
-   * 为什么不做 UI：本轮只要求可见性 + 数据面预留，展示位留待后续。
-   * @param {string} rootId 本次刷新它的根（值是全局队列深度，与根无关，只作溯源）
-   * @param {number|null} remaining 服务端 probeRemaining 原值；null = 老服务端没该字段
-   */
-  function noteProbeProgress(rootId, remaining) {
-    if (!Number.isFinite(remaining)) return;      // 没这个字段 ⇒ 不更新、不记录（不把未知当 0）
-    state.probe = { remaining: Number(remaining), at: Date.now(), rootId };
-    if (remaining === lastLoggedProbeRemaining) return;
-    lastLoggedProbeRemaining = remaining;
-    stageLog('info', `后台形态探测：还剩 ${remaining} 个容器待探（UI 未实现，数据已挂 state.probe）`, {
-      root: rootId, remaining,
-    });
-  }
-
-  /**
-   * 确保某个资源根的模型已加载。
-   * 并发要点：正在加载中的根必须**可等待**（entry.promise），否则后到的调用方会拿到空数据
-   *   ——启动恢复与"恢复展开态"的加载会并发进来，这一点决定恢复能否命中。
-   * @param {object} root
-   * @returns {Promise<object>} 该根的加载状态条目（ready / error）
-   */
-  function ensureRootLoaded(root) {
-    counters.ensureRootLoaded += 1;
-    // 名册计时：从**第一次**请求某根开始，到"所有已知根都 settle"结束。
-    //   为什么用 performance.now()：单调时钟，系统时间校准不会把耗时拉成负数。
-    if (rosterT0 === null) rosterT0 = performance.now();
-    const cur = state.loaded.get(root.id);
-    if (cur && cur.promise) return cur.promise.then(() => cur);
-    if (cur && cur.status === 'ready') return Promise.resolve(cur);
-    const entry = { status: 'loading', models: [], source: '', error: null, promise: null };
-    const rootT0 = performance.now();
-    entry.promise = (async () => {
-      try {
-        // 名表按根取一次并合并进全局索引（同名表只并一次，避免重复 assign）
-        if (!namesLoaded.has(root.id)) {
-          namesLoaded.add(root.id);
-          const table = await loadRootNames(root.id);
-          if (table) mergeNameTable(nameIndex, table);
-        }
-        const { models, source, serverSource, probeRemaining } = await loadRootModels(root);
-        for (const m of models) {
-        // 名册持有的就是这个对象本身（buildChars 的 variants[].model 也是它），
-        //   所以"写回三字段"必须落在这里 —— 只改 DOM 的话，下一次 render 读的还是旧对象，
-        //   表现为"当场变了色、一切换/搜索就掉回中性色"。
-        modelById.set(m.id, { model: m, rootId: root.id });
-      }
-        entry.status = 'ready';
-        entry.models = models;
-        entry.source = source;
-        // 探测进度：顺带记进 state.probe 与调试日志（只在数值变化时记一行，避免刷屏）
-        noteProbeProgress(root.id, probeRemaining);
-        recordRootLoad(root.id, rootT0, models.length, serverSource || 'built', null);
-      } catch (err) {
-        entry.status = 'error';
-        entry.error = formatError(err);
-        // 失败也要进 perRoot（source:'error'）：否则"某个根挂了"在计时里凭空消失，
-        //   总耗时看起来还挺快 —— 那正是这个功能最该暴露的情形。
-        recordRootLoad(root.id, rootT0, 0, 'error', entry.error);
-      }
-      entry.promise = null;
-      scheduleRender();          // 加载完成：合并到下一帧（不再每个根各渲一次）
-    })();
-    state.loaded.set(root.id, entry);
-    scheduleRender();            // 开始加载：同上（视觉上只是把游戏行标成 loading）
-    return entry.promise.then(() => entry);
-  }
-
-  /** 某游戏的全部根是否都已就绪（有失败也算"可渲染"，错误在游戏节点下提示） */
-  function gameStatus(game) {
-    const entries = game.roots.map((r) => state.loaded.get(r.id));
-    if (entries.some((e) => e && e.status === 'loading')) return 'loading';
-    if (entries.some((e) => !e || e.status === 'idle')) return 'idle';
-    if (entries.every((e) => e && e.status === 'error')) return 'error';
-    return 'ready';
-  }
-
-  /**
-   * 重新归并某游戏的角色（跨根）：把该游戏所有已就绪根的模型并成一个数组再归并。
-   * 为什么在游戏层归并：同一角色可能同时有 Live2D 与 Spine 变体（来自不同根），
-   *   按根各自归并会得到两个同名角色节点，造成不一致。
-   * @param {object} game
-   */
-  function rebuildGameChars(game) {
-    const models = [];
-    for (const root of game.roots) {
-      const entry = state.loaded.get(root.id);
-      if (entry && entry.status === 'ready') models.push(...entry.models);
-    }
-    const { chars, stats } = buildChars(models, nameIndex, game.name);
-    state.gameChars.set(game.key, { chars, stats });
-  }
-
-  /**
-   * 确保某游戏的模型已加载：先等在飞的根加载完，再补齐未开始的根，最后跨根归并。
-   * @param {object} game
-   */
-  async function ensureGameLoaded(game) {
-    const entries = game.roots.map((r) => state.loaded.get(r.id));
-    const inflight = entries.filter((e) => e && e.promise).map((e) => e.promise);
-    if (inflight.length) await Promise.all(inflight);
-    const pending = game.roots.filter((r) => {
-      const e = state.loaded.get(r.id);
-      return !e || e.status === 'idle' || e.status === 'error';
-    });
-    if (pending.length) await Promise.all(pending.map((r) => ensureRootLoaded(r)));
-    rebuildGameChars(game);
-    scheduleRender();
-  }
-
-  /** 搜索需要全局数据：首次输入关键词时把所有游戏补加载（并行，服务端有缓存） */
-  async function ensureAllLoaded() {
-    await Promise.all(state.games.map((g) => ensureGameLoaded(g)));
-    // 硬约束①：所有加载完成后**一定**有一次渲染，不依赖 rAF 是否被节流
-    flushRender();
-  }
-
-  // ------------------------------------------------------------ 过滤
-
-  /** 单条变体的可搜索文本（资源名 / 目录名 / 角色名 / 服装名） */
-  // ------------------------------------------------------------ 渲染
-
-  /** 渲染整棵树（只渲染可见部分；展开的角色才生成变体行） */
-  function render() {
-    counters.render += 1;
-    listEl.replaceChildren();
-
-    // 首次渲染时插件指纹还没取到 ⇒ 这一帧不显示"不支持"标记（避免用过期结论误导），
-    //   指纹就绪后再重画一次。之所以放在 render 里而不是 mount 里：mount 是同步函数。
-    // 徽标颜色 / ⚠ / 文案全部来自条目自带的三字段（display/support/loadResult，契约 §一）：
-    //   名册不再有"本地失败缓存"这一层，也就不需要指纹初始化与快照拉取。
-
-    const searching = state.keyword.length > 0;
-    let totalChars = 0;
-    let totalVariants = 0;
-    let rendered = 0;
-    let loadedGames = 0;
-
-    for (const game of state.games) {
-      const status = gameStatus(game);
-      if (status === 'ready') loadedGames += 1;
-      const chars = visibleChars(game, state);
-      const open = state.expandedGames.has(game.key) || (searching && chars.length > 0);
-
-      listEl.append(renderGameRow(game, {
-        open: state.expandedGames.has(game.key),
-        status,
-        charCount: chars.length,
-      }));
-      if (!open) continue;
-
-      if (status === 'loading') {
-        listEl.append(el('p', 'muted-hint tree-hint', '加载中…'));
-        continue;
-      }
-      if (status === 'error') {
-        listEl.append(el('p', 'error-banner', `加载失败：${game.roots.map((r) => r.id).join(', ')}`));
-        continue;
-      }
-
-      totalChars += chars.length;
-      const limit = renderLimitPerGame(); // 每次渲染读一次：改配置后刷新即生效
-      const selectedId = state.selected ? state.selected.modelId : null;
-      for (const c of chars) {
-        if (rendered >= limit) break;
-        rendered += 1;
-        const charOpen = state.expandedChars.has(c.key) || searching;
-        listEl.append(renderCharRow(game, c, charOpen));
-        // 变体数按数据统计（不依赖是否展开），与「N 游戏 / M 角色 / K 变体」口径一致
-        totalVariants += c.variants.length;
-        if (!charOpen) continue;
-        for (const v of c.variants) {
-          // 行内的颜色 / ⚠ / 文案全部由条目自带的三字段渲染（display/support/loadResult），
-          //   这里不再注入任何本地失败记录 —— 服务端是唯一权威（契约 §一）。
-          listEl.append(renderVariantRow(game, c, v, selectedId));
-        }
-      }
-      if (!chars.length) {
-        listEl.append(el('p', 'muted-hint tree-hint', searching ? '无匹配' : '该游戏没有可加载模型'));
-      }
-    }
-
-    // 计数文案：全量已加载时用统一口径（N 游戏 / M 角色 / K 变体），否则标注已加载多少
-    const allLoaded = loadedGames === state.games.length;
-    const prefix = allLoaded ? `${state.games.length} 游戏` : `${state.games.length} 游戏 / 已加载 ${loadedGames}`;
-    countEl.textContent = searching
-      ? `搜索「${state.keyword}」：${totalChars} 角色 / ${totalVariants} 变体`
-      : `${prefix}：${totalChars} 角色 / ${totalVariants} 变体`;
-
-    // 供自动化断言：把状态投影成可读快照
-    document.documentElement.dataset.rosterReady = '1';
-    document.documentElement.dataset.rosterSnapshot = JSON.stringify(snapshot());
-  }
-
-  /** 状态快照（自动化断言与排查用，避免每次都去数 DOM） */
-  /** 快照：投影逻辑在 roster/snapshot.js（断言只读这份） */
-  const snapshot = () => snapshotRoster({ state, listEl, gameStatus });
-
-  // ------------------------------------------------------------ 事件
-
-  /** 点一级：折叠/展开游戏（首次展开触发该游戏所有根的数据加载） */
-  async function onGameClick(gameKey) {
-    if (state.expandedGames.has(gameKey)) {
-      state.expandedGames.delete(gameKey);
-      render();
-      saveState(state);
-      return;
-    }
-    state.expandedGames.add(gameKey);
-    // 先渲染一次：已加载过的游戏直接出角色行（ensureGameLoaded 在无待加载根时不会单独渲染）
-    render();
-    const game = state.games.find((g) => g.key === gameKey);
-    if (game) await ensureGameLoaded(game);
-    saveState(state);
-  }
-
-  /** 点二级：折叠/展开角色（变体已在内存，不发请求） */
-  function onCharClick(charKey) {
-    if (state.expandedChars.has(charKey)) state.expandedChars.delete(charKey);
-    else state.expandedChars.add(charKey);
-    render();
-    saveState(state);
-  }
-
-  /** 点三级：选中变体（高亮 + 记录状态，M4 用它去渲染） */
-  function onVariantClick(modelId, gameKey, charKey) {
-    const game = state.games.find((g) => g.key === gameKey);
-    state.selected = { modelId, gameKey, gameName: game ? game.name : null, charKey };
-    state.activeGame = game ? game.name : state.activeGame;
-    render();
-    state.lastReveal = reveal.revealActive(); // 选中后把这一行滚到可视区（已可见/用户正在滚都会跳过）
-    saveState(state);
-    if (typeof onSelect === 'function') {
-      const hit = modelById.get(modelId);
-      onSelect(hit ? hit.model : null);
-    }
-  }
-
-  /** 事件委托：树行是动态生成的，统一在容器上监听一次 */
-  function bindEvents() {
-    /** 按行的类型分派到对应动作（鼠标与键盘共用，避免两套逻辑走偏） */
-    function activate(row) {
-      if (row.dataset.modelId) {
-        onVariantClick(row.dataset.modelId, row.dataset.gameKey, row.dataset.charKey);
-      } else if (row.dataset.charKey) {
-        onCharClick(row.dataset.charKey);
-      } else if (row.dataset.gameKey) {
-        onGameClick(row.dataset.gameKey);
-      }
-    }
-
-    // 用户滚动信号由 reveal 控制器统一挂（滚轮 / 触摸 / 指针 / 滚动条）
-    reveal.attachUserScrollListeners();
-
-    listEl.addEventListener('click', (e) => {
-      const row = e.target.closest('[data-model-id], [data-char-key], [data-game-key]');
-      if (row) activate(row);
-    });
-
-    // 键盘可达：树行带 tabindex="0"，Enter / 空格与点击等价
-    listEl.addEventListener('keydown', (e) => {
-      if (e.key !== 'Enter' && e.key !== ' ') return;
-      const row = e.target.closest('[data-model-id], [data-char-key], [data-game-key]');
-      if (!row) return;
-      e.preventDefault();
-      activate(row);
-    });
-
-    searchEl.addEventListener('input', () => {
-      state.keyword = searchEl.value.trim().toLowerCase();
-      // 搜索要全局数据：首次输入时把所有游戏补上（之后都走缓存，不再请求）
-      if (state.keyword && [...state.gameChars.keys()].length < state.games.length) {
-        ensureAllLoaded();
-      } else {
-        render();
-      }
-    });
-
-    // 「收起」：只清空两级展开状态，面板保留
-    collapseBtn.addEventListener('click', () => {
-      state.expandedGames.clear();
-      state.expandedChars.clear();
-      render();
-      saveState(state);
-    });
-  }
+  // ------------------------------------------------------------ 模块装配
+  // store/reveal 只持有"延迟调用"的引用（() => render()），能写在渲染模块前面；render 用函数声明避免 TDZ。
+  // render 转调渲染模块（四处装配行都通过它拿最新实现）；snapshot 的投影逻辑在 roster/snapshot.js。
+  function render() { return renderModule.render(); }
+  function snapshot() { return snapshotRoster({ state, listEl, groupStatus: renderModule.groupStatus }); }
+
+  // 队列位次由 load 提供，但 render 要先建出来 ⇒ 用一层转发，避免两个工厂互相引用
+  let queuePositionOfRef = () => 0;
+  const renderModule = createRosterRender({
+    store, counters, listEl, countEl, typeFilterEl,
+    snapshotOf: () => snapshot(),
+    queuePositionOf: (group) => queuePositionOfRef(group),
+  });
+
+  const load = createRosterLoad({
+    store, counters, nameIndex, namesLoaded, modelById,
+    render, scheduleRender, flushRender,
+    rebuildGroupChars: renderModule.rebuildGroupChars,
+    aggregateScan: renderModule.aggregateScan,
+    applyScanStatusToRow: renderModule.applyScanStatusToRow,
+  });
+  queuePositionOfRef = load.queuePositionOf;
+
+  const events = createRosterEvents({
+    store, listEl, searchEl, collapseBtn, typeFilterEl, reveal, render, load, modelById, onSelect,
+  });
 
   /**
    * 初始化：把资源根按 name 合并成游戏 → 渲染（不加载任何模型，等用户展开）
-   * @param {object[]} roots /api/roots 的 roots
-   * @param {{restoreExpanded?: boolean}} opts restoreExpanded=false 时不恢复任何展开态（自动恢复被关闭时用）
+   * @param {{restoreExpanded?: boolean}} opts restoreExpanded=false 时不恢复任何展开态
    */
   function mount(roots, opts) {
     const restoreExpanded = !opts || opts.restoreExpanded !== false;
-    // 同名根合并成一个游戏节点（照 char-tree.js：name 是归一 key）
-    const byName = new Map();
-    for (const root of roots) {
-      const name = root.name || root.id;
-      if (!byName.has(name)) byName.set(name, { key: `game:${name}`, name, roots: [] });
-      byName.get(name).roots.push(root);
-    }
-    state.games = [...byName.values()];
-
+    const skipRestore = !!(opts && opts.skipRestore);
+    store.setTypeFilter([]);          // 类型筛选不持久化：每次打开都是不筛选（当次会话内的临时动作）
+    store.setRoots(roots);            // 同名根合并成游戏节点：规则收在 store.setRoots
     const saved = readSaved();
     if (restoreExpanded) {
       // 展开状态恢复：只恢复仍存在的游戏，避免历史配置残留导致空节点
-      const gameKeys = new Set(state.games.map((g) => g.key));
-      for (const k of saved.games) if (gameKeys.has(k)) state.expandedGames.add(k);
-      for (const c of saved.chars) state.expandedChars.add(c);
-      state.activeGame = saved.activeGame;
+      store.restoreExpanded({ groups: saved.groups, chars: saved.chars });
+      store.setActiveGroup(saved.activeGroup);   // 存储字段与内存同名（activeGroup）
     }
-
-    bindEvents();
+    events.bindEvents();
     render();
-    // 恢复展开的游戏要补加载数据（用户上次就是展开的）
-    if (restoreExpanded) {
-      for (const key of [...state.expandedGames]) {
-        const game = state.games.find((g) => g.key === key);
-        if (game) ensureGameLoaded(game);
+    // 启动后：上次所用模型所在的那一个根**优先**加载（restoreLast），其余分组排进队列按顺序串行加载。
+    //   不再需要用户点「点击加载」：队列会自己往下走，行上只显示"排队中（第 N 位）/ 加载中"。
+    //   串行而不是并行，是因为服务端扫描是重活，并发会互相抢 IO 把整站拖慢。
+    //   **队列必须等首个模型装载落地再放行**：restoreLast 里 await 的是"根清单 + 装载完成"，
+    //   真正确认能出画才算 settle；否则队列一开始扫别的根，就把首模型的资源请求挤到后面
+    //   （现象就是"列表全加载完，模型才出来"）。失败同样放行，避免一个坏根把队列卡死。
+    //   **返回这个 promise**：调用方（loadRoots）要拿恢复结果，不要再自己调一次 restoreLast。
+    return (async () => {
+      let info = { restored: false, reason: skipRestore ? 'skipped' : 'no-pointer' };
+      if (!skipRestore) {
+        try { info = await restoreLast(); } catch { /* 恢复失败不影响队列 */ }
       }
-    }
+      load.enqueueRemaining();
+      load.startQueue();
+      return info;
+    })();
   }
 
-  /** 从存档里取出"上次选中的变体 id"：优先按活跃游戏取，其次旧格式单个 id，最后取任一非空值 */
-  function targetModelId(saved) {
-    const byGame = saved.lastByGame || {};
-    if (saved.activeGame && byGame[saved.activeGame]) return byGame[saved.activeGame];
-    if (saved.lastModelId) return saved.lastModelId;
-    const first = Object.values(byGame).find((v) => typeof v === 'string' && v);
-    return first || null;
+  /** 某组是否已归并出角色（判据是"真有 chars"，不是"根有 models"） */
+  function hasGroupChars(group) {
+    const entry = state.groupChars.get(group.key);
+    return !!(entry && Array.isArray(entry.chars) && entry.chars.length);
   }
 
   /** 在某游戏已加载的角色里找该变体，命中返回 { charKey, variant }（变体对象形如 { model, nm }） */
-  function findVariant(game, modelId) {
-    const entry = state.gameChars.get(game.key);
+  function findVariant(group, modelId) {
+    const entry = state.groupChars.get(group.key);
     if (!entry) return null;
     for (const c of entry.chars) {
       const v = c.variants.find((x) => x.model && x.model.id === modelId);
@@ -510,27 +123,23 @@ export function createRosterView({ listEl, countEl, searchEl, collapseBtn, onSel
   }
 
   /**
-   * 把左栏树**从上到下**摊平成变体序列（翻页的池子就是它）。
-   *
-   * 为什么不让外部自己请求接口：树的"游戏"节点是**同名根合并**出来的
-   *   （例如「碧蓝航线」= azurlane + azurlane_spine + azurlane_bundle 三个根），
-   *   外部按单个 rootId 取清单会漏掉另外两个根 ⇒ 表现为"只能在 live2d 之间翻，翻不到 spine"。
-   * 用树自己的数据结构（含合并、含排序）作唯一真相源，顺序天然与用户看到的一致。
-   * @returns {Promise<Array<{model:object, gameKey:string, charKey:string}>>}
+   * 把左栏树**从上到下**摊平成变体序列（翻页的池子就是它）。用树自己的数据结构（含同名根合并、含排序）
+   *   作唯一真相源 —— 外部按单 rootId 取清单会漏掉同名的另外几个根。
+   * @returns {Promise<Array<{model:object, groupKey:string, charKey:string}>>}
    */
   async function listVariants() {
     const out = [];
-    for (const game of state.games) {
-      if (state.expandedGames && !state.expandedGames.size) { /* 未展开也要能翻：下面统一加载 */ }
+    for (const group of state.groups) {
+      if (state.expandedGroups && !state.expandedGroups.size) { /* 未展开也要能翻：下面统一加载 */ }
       // 目标游戏可能还没加载（用户没展开过）：按需加载一次，保证序列完整
-      if (!state.gameChars.get(game.key)) {
-        try { await ensureGameLoaded(game); } catch { continue; }
+      if (!state.groupChars.get(group.key)) {
+        try { await load.ensureGroupLoaded(group); } catch { continue; }
       }
-      const entry = state.gameChars.get(game.key);
+      const entry = state.groupChars.get(group.key);
       if (!entry) continue;
       for (const c of entry.chars) {
         for (const v of c.variants) {
-          if (v && v.model && v.model.id) out.push({ model: v.model, gameKey: game.key, charKey: c.key });
+          if (v && v.model && v.model.id) out.push({ model: v.model, groupKey: group.key, charKey: c.key });
         }
       }
     }
@@ -539,103 +148,98 @@ export function createRosterView({ listEl, countEl, searchEl, collapseBtn, onSel
 
   /**
    * 取某个变体的**兄弟变体**（同一角色/同一 charKey 下的全部变体）。
-   * @param {string} modelId
-   * @returns {Promise<Array<{model:object, gameKey:string, charKey:string}>>}
+   * @returns {Promise<Array<{model:object, groupKey:string, charKey:string}>>}
    */
   async function variantsOf(modelId) {
-    for (const game of state.games) {
-      if (!state.gameChars.get(game.key)) {
-        try { await ensureGameLoaded(game); } catch { continue; }
+    for (const group of state.groups) {
+      if (!state.groupChars.get(group.key)) {
+        try { await load.ensureGroupLoaded(group); } catch { continue; }
       }
-      const entry = state.gameChars.get(game.key);
+      const entry = state.groupChars.get(group.key);
       if (!entry) continue;
       for (const c of entry.chars) {
         const hit = c.variants.some((v) => v && v.model && v.model.id === modelId);
-        if (hit) return c.variants.filter((v) => v && v.model).map((v) => ({ model: v.model, gameKey: game.key, charKey: c.key }));
+        if (hit) return c.variants.filter((v) => v && v.model).map((v) => ({ model: v.model, groupKey: group.key, charKey: c.key }));
       }
     }
     return [];
   }
 
   /**
-   * 按 modelId 选中某个变体并同步左栏（**外部入口专用**）。
-   *
-   * 为什么需要它：左栏点击时选中态由 onVariantClick 自己维护，但"上一个/下一个"、快捷键等
-   *   外部入口只调装载、不碰左栏 ⇒ 树上高亮停在上一个模型，看起来像没切过去。
-   *   这里把"选中态 + 展开 + 渲染 + 定位 + 存盘"收成一处，外部入口只调它。
-   * 不触发 onSelect：装载由调用方的统一入口负责，避免同一次切换装载两遍。
-   * @param {string} modelId
+   * 按 modelId 选中某个变体并同步左栏（**外部入口专用**：上/下一个、快捷键等只调装载、不碰左栏，
+   *   树上高亮就会停在上一个模型）。不触发 onSelect：装载由调用方统一入口负责，避免切换装载两遍。
    * @param {{reveal?: boolean}} [opts] reveal=false 时不滚动定位（默认滚到可视区）
-   * @returns {Promise<{ok:boolean, gameKey?:string, charKey?:string, reason?:string}>}
+   * @returns {Promise<{ok:boolean, groupKey?:string, charKey?:string, reason?:string}>}
    */
   async function selectById(modelId, opts = {}) {
     if (!modelId) return { ok: false, reason: 'no-id' };
-    for (const game of state.games) {
+    for (const group of state.groups) {
       // 目标可能属于还没展开/加载的游戏：按需加载一次（与启动恢复同策略，不预取全部）
-      if (!state.gameChars.get(game.key)) {
-        try { await ensureGameLoaded(game); } catch { continue; }
+      if (!state.groupChars.get(group.key)) {
+        try { await load.ensureGroupLoaded(group); } catch { continue; }
       }
-      const hit = findVariant(game, modelId);
+      const hit = findVariant(group, modelId);
       if (!hit) continue;
-      state.selected = { modelId, gameKey: game.key, gameName: game.name, charKey: hit.charKey };
-      state.activeGame = game.name;
+      store.selectModel({ modelId, groupKey: group.key, groupName: group.name, charKey: hit.charKey });
+      store.setActiveGroup(group.name);
+      try { saveLastModel(hit.variant && hit.variant.model ? hit.variant.model : null); } catch { /* 忽略 */ }
       // 不展开的话目标行根本没渲染出来，高亮也就无从显示
-      state.expandedGames.add(game.key);
-      state.expandedChars.add(hit.charKey);
+      store.expandGroup(group.key);
+      store.expandChar(hit.charKey);
       render();
-      if (opts.reveal !== false) state.lastReveal = reveal.revealActive();
+      if (opts.reveal !== false) store.setLastReveal(reveal.revealActive());
       saveState(state);
-      return { ok: true, gameKey: game.key, charKey: hit.charKey };
+      return { ok: true, groupKey: group.key, charKey: hit.charKey };
     }
     return { ok: false, reason: 'not-found' };
   }
 
   /**
-   * 启动恢复：按存档把上次选中的变体重新选中并渲染。
-   * 懒加载顺序：目标变体所属游戏可能还没加载 ⇒ 先按游戏逐个加载再看命中，不预取全部。
-   * 失效兜底：所有游戏都找过仍没有 ⇒ 安静回落空舞台（不展开、不报错、不留半选中状态）。
+   * 启动恢复：按存档把上次选中的变体重新选中并渲染。找不到 ⇒ 安静回落空舞台（不展开、不报错、不留半选中）
    * @returns {Promise<{restored: boolean, modelId?: string, reason?: string}>}
    */
   async function restoreLast() {
-    const saved = readSaved();
-    const modelId = targetModelId(saved);
-    if (!modelId) return { restored: false, reason: 'no-saved' };
-
-    // 活跃游戏先试（多数命中在第一个），再按顺序找其余游戏
-    const ordered = [...state.games];
-    const active = ordered.find((g) => g.name === saved.activeGame);
-    if (active) ordered.unshift(...ordered.splice(ordered.indexOf(active), 1));
-
-    for (const game of ordered) {
-      await ensureGameLoaded(game);
-      const hit = findVariant(game, modelId);
-      if (!hit) continue;
-      state.expandedGames.add(game.key);
-      state.expandedChars.add(hit.charKey);
-      state.selected = { modelId, gameKey: game.key, gameName: game.name, charKey: hit.charKey };
-      state.activeGame = game.name;
+    // 冷启动加载策略（唯一允许的启动加载）：读「上次所用模型」指针 → **只加载它所在的那一个根**
+    //   → 展开并定位到它。没有指针 ⇒ 一个根都不扫；有指针但失败 ⇒ 该行显示「加载失败 · 重试」。
+    const pointer = readLastModel();
+    if (!pointer) return { restored: false, reason: 'no-pointer' };
+
+    const group = state.groups.find((g) => g.roots.some((r) => r.id === pointer.rootId));
+    if (!group) return { restored: false, reason: 'root-gone', rootId: pointer.rootId };
+    const root = group.roots.find((r) => r.id === pointer.rootId);
+
+    try {
+      await load.ensureRootLoaded(root);         // 只有这一个根（1 次 catalog + 1 条进度流）
+    } catch {
+      return { restored: false, reason: 'load-failed', rootId: pointer.rootId };
+    }
+    // 归并判据是"**groupChars 里该组真有 chars**"，不是"根有 models"：
+    //   根就绪 ≠ 角色树已归并（归并是另一件事，任何一条路径漏了它都会让下面 findVariant
+    //   误判成 model-gone —— 表现就是"加载完成后 0 角色、收起再展开才出现"）。
+    //   正常情况下 setRootModels 已经自动归并过，这里只是一次幂等兜底。
+    if (!hasGroupChars(group)) renderModule.rebuildGroupChars(group);
+    store.expandGroup(group.key);
+
+    const hit = findVariant(group, pointer.modelId);
+    if (!hit) {
       render();
-      // 自动恢复同样把恢复到的那一行滚进视野；但用户若正在滚动就不会抢（守卫在 revealActive 里）
-      state.lastReveal = reveal.revealActive();
-      saveState(state); // 顺带把旧格式迁移成 lastByGame（saveState 只写 lastByGame）
-      if (typeof onSelect === 'function') onSelect(modelById.get(modelId)?.model || null);
-      return { restored: true, modelId, gameKey: game.key, charKey: hit.charKey };
+      saveState(state);
+      return { restored: false, reason: 'model-gone', rootId: pointer.rootId };
     }
-    // 存档里的模型已不存在：清掉半状态，保持空舞台
-    state.selected = null;
-    render();
-    return { restored: false, reason: 'missing', modelId };
+    store.expandChar(hit.charKey);
+    // 关键：复用"用户点击变体"的同一入口 —— 它写入选中态、存盘，并调用 onSelect 真正装载模型。
+    //   只设置 state.selected + render() 是不够的：那只是"列表里高亮"，画布上什么都不会出现。
+    //   **等它落地**：调用方（mount）要等首个模型真的出来才放行加载队列，
+    //   否则队列的整根扫描会和首个模型的资源请求抢同一份磁盘 IO。
+    await events.onVariantClick(pointer.modelId, group.key, hit.charKey);
+    store.setLastReveal(reveal.revealActive());
+    return { restored: true, modelId: pointer.modelId, rootId: pointer.rootId, groupKey: group.key };
   }
 
   /**
    * 把服务端的三字段写回名册条目并就地重画那一行（契约 §一 INV-D1 的前端落点）。
-   *
-   * 为什么"写回对象"和"刷 DOM"两件事都要做（只刷 DOM 就是之前那个 bug）：
-   *   DOM 是一次性快照，`render()` 每次都用条目对象重画该行。
-   *   实测过的错位：装载成功后只改了 DOM ⇒ 当场看着对了，
-   *   随后任意一次重渲染（切换模型 / 搜索 / 展开折叠）又把旧值画回来 ⇒ "马上变回中性色"。
-   *   所以权威写回必须落在**名册持有的那个对象**上（modelById 与 buildChars 的
-   *   variants[].model 是同一引用，改它两边都生效）。
+   * 为什么"写回对象"和"刷 DOM"都要做（只刷 DOM 就是之前那个 bug）：DOM 是一次性快照，render() 每次都用
+   *   条目对象重画 ⇒ 只改 DOM 的话，任一次重渲染又把旧值画回来（"马上变回中性色"）。
    * @param {string} modelId 条目 id
    * @param {{display?:object, support?:object, loadResult?:object}|null} entryState 服务端三字段
    * @returns {boolean} 条目不在名册里返回 false（调用方可忽略）
@@ -653,15 +257,15 @@ export function createRosterView({ listEl, countEl, searchEl, collapseBtn, onSel
   }
 
   return {
-    mount, state, snapshot, render, ensureGameLoaded, selectById, listVariants, variantsOf,
+    mount, state, snapshot, render, ensureGroupLoaded: load.ensureGroupLoaded, selectById, listVariants, variantsOf,
     setEntryState,
     restoreLast,
     revealActive: reveal.revealActive,
     markUserScroll: reveal.markUserScroll,
     /** 调试计数（渲染/加载次数）：优化前后用同一口径对比 */
     counters: () => ({ ...counters }),
-    /** 名册加载计时快照（`window.__WEB__.rosterStats()` 用它；口径见文件内"名册加载计时"注释） */
-    rosterStats,
+    /** 名册加载计时快照（`window.__WEB__.rosterStats()` 用它；口径见 load.js） */
+    rosterStats: load.rosterStats,
     /** 立刻落地待渲染的请求（测试/自检用：不依赖 rAF 时机） */
     flushRender,
     /** 归零计数（测量前调用，避免把上一段的调用混进来） */