modelstage 0.5.24 → 0.6.1

package/src/web/roster/scan-stream.js

@@ -0,0 +1,346 @@
+// roster/scan-stream.js —— 扫描进度：NDJSON 流读取 + 状态机 + 状态行文案（纯逻辑，不碰 DOM）
+//
+// 为什么单独成模块：
+//   ① 流读取（逐行切帧）与"什么时候算卡住"是可以脱离 DOM 单测的纯逻辑；
+//   ② 视图层只做"把文案贴到游戏行的状态位上"，两者分开才好测（有 node 单测，见 test/scan-stream.test.mjs）。
+//
+// 数据形状（设计 §5.2，一帧一行 NDJSON）：
+//   start    { kind, rootId, rootPath, startedAt }
+//   progress { scanned, dirs, currentPath, elapsedMs }
+//   done     { count, cached:false, elapsedMs }
+//   cached   { count, ts }
+//   error    { message, scanned, currentPath }
+//
+// 关键点：**P0 的流只带进度，不带模型数据**。拿到 done/cached 之后，模型清单仍走原来的
+//   `/api/catalog` 一次请求（那时服务端已落盘，命中缓存很快）。
+
+import { SCAN_STALL_MS, resolveScanStallMs } from '../../shared/scan-limits.mjs';
+
+/** 哪些内容类型有"扫描"这一说（其余类型没有对应端点，直接跳过进度） */
+const SCAN_KINDS = new Set(['spine', 'live2d']);
+
+/**
+ * 该根要用哪条流式端点；没有对应扫描端点时返回 null（调用方直接走普通 JSON）。
+ * @param {{id: string, kind?: string}} root
+ * @param {{base?: string}} [opts]
+ * @returns {string|null}
+ */
+export function scanStreamUrl(root, opts = {}) {
+  const id = root && root.id ? String(root.id) : '';
+  const kind = root && root.kind ? String(root.kind) : '';
+  if (!id || !SCAN_KINDS.has(kind)) return null;
+  const base = (opts && opts.base) || '';
+  return `${base}/api/${kind}/models?root=${encodeURIComponent(id)}&stream=1`;
+}
+
+/**
+ * 逐帧读 NDJSON。
+ *
+ * 为什么手写切行而不是 TextDecoderStream 管道：一行可能被任意切在两次 read 之间，
+ *   必须自己攒 buffer；手写也只有十几行，行为可控（尾行残缺时不抛错，直接丢弃）。
+ *
+ * @param {Response} response fetch 的响应（必须是流式的 body）
+ * @param {(frame: object) => void} onFrame 每解析出一帧回调一次
+ * @returns {Promise<void>} 流结束（正常结束或 body 读空）
+ */
+export async function readNdjsonStream(response, onFrame) {
+  const body = response && response.body;
+  if (!body || typeof body.getReader !== 'function') return;
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  const emit = (line) => {
+    const text = line.trim();
+    if (!text) return;
+    let frame;
+    try { frame = JSON.parse(text); } catch { return; }   // 坏行丢掉：进度是增强，不能因一行脏数据中断
+    if (frame && typeof frame === 'object') onFrame(frame);
+  };
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let cut = buffer.indexOf('\n');
+    while (cut >= 0) {
+      emit(buffer.slice(0, cut));
+      buffer = buffer.slice(cut + 1);
+      cut = buffer.indexOf('\n');
+    }
+  }
+  buffer += decoder.decode();
+  emit(buffer);
+}
+
+/**
+ * 扫描状态机：idle → scanning → (loaded | stalled ⇄ scanning | failed)。
+ *
+ * 判死规则（设计 §7.3）：收到**任意一帧**就重置计时；超阈值 ⇒ stalled，**只改状态与文案，
+ *   不自动取消请求**（服务端可能只是慢；自动取消会把"慢"变成"失败"）。
+ * 定时器/时钟都可注入，便于单测（不引入假定时器库）。
+ *
+ * @param {{stallMs?: number, now?: () => number, setTimer?: Function, clearTimer?: Function,
+ *          onChange?: (snap: object) => void}} [opts]
+ */
+export function createScanMonitor(opts = {}) {
+  const stallMs = resolveScanStallMs(opts.stallMs != null ? opts.stallMs : SCAN_STALL_MS);
+  const now = typeof opts.now === 'function' ? opts.now : () => Date.now();
+  const setTimer = typeof opts.setTimer === 'function' ? opts.setTimer : ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = typeof opts.clearTimer === 'function' ? opts.clearTimer : ((t) => clearTimeout(t));
+  const onChange = typeof opts.onChange === 'function' ? opts.onChange : () => {};
+
+  const snap = {
+    phase: 'idle',       // idle | scanning | stalled | failed | loaded
+    scanned: 0,
+    dirs: 0,
+    currentPath: '',
+    stalledFor: 0,       // 已无进展多久（只在 stalled 时有意义）
+    message: '',         // failed 的原因
+    lastFrameAt: 0,
+  };
+  let stallTimer = null;
+  let tickTimer = null;   // stalled 期间每秒刷新"已 N 秒无进展"
+  let phaseBeforeStall = null;
+
+  const emit = () => { try { onChange({ ...snap }); } catch { /* 视图回调出错不影响状态机 */ } };
+
+  const clearTimers = () => {
+    if (stallTimer !== null) { clearTimer(stallTimer); stallTimer = null; }
+    if (tickTimer !== null) { clearTimer(tickTimer); tickTimer = null; }
+  };
+
+  const armStall = () => {
+    if (stallTimer !== null) clearTimer(stallTimer);
+    stallTimer = setTimer(() => {
+      stallTimer = null;
+      if (snap.phase !== 'scanning') return;
+      phaseBeforeStall = snap.phase;
+      snap.phase = 'stalled';
+      snap.stalledFor = Math.max(0, now() - snap.lastFrameAt);
+      emit();
+      // 每秒刷新一次"已 N 秒无进展"，让用户看到时间在走（状态本身不变）
+      tickTimer = setTimer(function tick() {
+        tickTimer = null;
+        if (snap.phase !== 'stalled') return;
+        snap.stalledFor = Math.max(0, now() - snap.lastFrameAt);
+        emit();
+        tickTimer = setTimer(tick, 1000);
+      }, 1000);
+    }, stallMs);
+  };
+
+  /** 收到一帧之前先更新"最后收到帧的时间"并（必要时）从 stalled 回到 scanning */
+  const touch = () => {
+    snap.lastFrameAt = now();
+    if (snap.phase === 'stalled') {
+      snap.phase = 'scanning';
+      snap.stalledFor = 0;
+      if (tickTimer !== null) { clearTimer(tickTimer); tickTimer = null; }
+      phaseBeforeStall = null;
+    }
+    if (snap.phase === 'scanning') armStall();
+  };
+
+  return {
+    get state() { return { ...snap }; },
+
+    /** 开始一次（或重试一次）扫描：计数清零、状态回 scanning、重新起判死计时 */
+    begin() {
+      clearTimers();
+      snap.phase = 'scanning';
+      snap.scanned = 0;
+      snap.dirs = 0;
+      snap.currentPath = '';
+      snap.stalledFor = 0;
+      snap.message = '';
+      snap.lastFrameAt = now();
+      phaseBeforeStall = null;
+      armStall();
+      emit();
+    },
+
+    /** 处理一帧：任何帧都算"还活着"（含 error/done，它们之后的状态由帧类型决定） */
+    frame(frame) {
+      if (!frame || typeof frame !== 'object') return;
+      const type = String(frame.type || '');
+      if (type === 'error') {
+        // 失败也是"有响应"，先重置计时再落状态，避免刚收到 error 就被判成卡住
+        snap.lastFrameAt = now();
+        clearTimers();
+        snap.phase = 'failed';
+        snap.message = String(frame.message || '扫描失败（服务端未给原因）');
+        if (Number.isFinite(Number(frame.scanned))) snap.scanned = Number(frame.scanned);
+        if (frame.currentPath) snap.currentPath = String(frame.currentPath);
+        emit();
+        return;
+      }
+      if (type === 'done' || type === 'cached') {
+        snap.lastFrameAt = now();
+        clearTimers();
+        snap.phase = 'loaded';
+        if (Number.isFinite(Number(frame.count))) snap.scanned = Number(frame.count);
+        snap.currentPath = '';
+        emit();
+        return;
+      }
+      if (type === 'progress') {
+        if (Number.isFinite(Number(frame.scanned))) snap.scanned = Number(frame.scanned);
+        if (Number.isFinite(Number(frame.dirs))) snap.dirs = Number(frame.dirs);
+        if (frame.currentPath) snap.currentPath = String(frame.currentPath);
+        touch();
+        emit();
+        return;
+      }
+      // start 与未知帧：只算"活着的证据"
+      if (type === 'start' && frame.rootId) snap.currentPath = '';
+      touch();
+      emit();
+    },
+
+    /** 请求层失败（非 error 帧：网络断了 / 非 2xx） */
+    fail(message) {
+      clearTimers();
+      snap.phase = 'failed';
+      snap.message = String(message || '扫描请求失败');
+      emit();
+    },
+
+    /** 流结束但没有 done/cached/error（连接被对端关掉）：按失败处理，别假装完成 */
+    end() {
+      if (snap.phase === 'loaded' || snap.phase === 'failed') return;
+      clearTimers();
+      snap.phase = 'failed';
+      snap.message = '进度流提前结束（未收到完成帧）';
+      emit();
+    },
+
+    /** 主动停止（关流/换游戏）：不产生任何状态变更 */
+    abort() { clearTimers(); },
+  };
+}
+
+/**
+ * 把"已完成根的计数"并入基线（单调不减的来源）。
+ *
+ * 为什么需要基线：同一个游戏挂着多个根时是**逐根扫**的 —— 第一根扫完后它就从活跃集合里消失，
+ *   若聚合只统计活跃根，总数会从"135 条"掉回"0 条"，看起来像重来了一次。
+ *   所以每根结束时把它的最终计数累加进基线，聚合 = 基线 + 活跃根。
+ *
+ * @param {{scanned:number, dirs:number}|null} baseline
+ * @param {{scanned?:number, dirs?:number}} snap 刚结束那根的最终快照
+ * @returns {{scanned:number, dirs:number}}
+ */
+export function mergeScanBaseline(baseline, snap) {
+  const base = baseline || { scanned: 0, dirs: 0 };
+  return {
+    scanned: (base.scanned || 0) + (Number(snap && snap.scanned) || 0),
+    dirs: (base.dirs || 0) + (Number(snap && snap.dirs) || 0),
+  };
+}
+
+/**
+ * 聚合一个游戏下所有**活跃**扫描（多根并行/串行时共用一行状态）。
+ *
+ * 阶段优先级：scanning > stalled > failed > loaded
+ *   —— 只要还有一根在出帧，整体就算"扫描中"；否则才报卡住/失败。
+ *      （反过来的话，一根卡住而另一根仍在推进时会误报 stalled，正是设计 §7.3 要避免的误判）
+ * 计数：基线（已完成根）+ 所有活跃根之和 ⇒ 对用户而言单调不减。
+ *
+ * @param {Array<object>} snaps 活跃根的状态快照（createScanMonitor().state）
+ * @param {{scanned:number, dirs:number}} [baseline]
+ * @returns {object|null} null = 没有活跃扫描（调用方保持现状/交给正常渲染）
+ */
+export function aggregateScanSnapshots(snaps, baseline) {
+  const active = Array.isArray(snaps) ? snaps.filter(Boolean) : [];
+  if (!active.length) return null;
+  const has = (phase) => active.some((snap) => snap.phase === phase);
+  const phase = has('scanning') ? 'scanning' : has('stalled') ? 'stalled' : has('failed') ? 'failed' : 'loaded';
+  const base = baseline || { scanned: 0, dirs: 0 };
+  // 只累加**还在跑**的根：已 loaded 的根其计数已经并入基线，再算一次会翻倍
+  const running = active.filter((snap) => snap.phase !== 'loaded');
+  const sum = (key) => running.reduce((n, snap) => n + (Number(snap[key]) || 0), 0);
+  const stalledSnap = active.find((snap) => snap.phase === 'stalled') || null;
+  const failedSnap = active.find((snap) => snap.phase === 'failed') || null;
+  const scanningSnap = active.find((snap) => snap.phase === 'scanning') || null;
+  return {
+    phase,
+    scanned: (base.scanned || 0) + sum('scanned'),
+    dirs: (base.dirs || 0) + sum('dirs'),
+    currentPath: (stalledSnap && stalledSnap.currentPath) || (failedSnap && failedSnap.currentPath)
+      || (scanningSnap && scanningSnap.currentPath) || '',
+    stalledFor: Math.max(0, ...active.map((snap) => Number(snap.stalledFor) || 0)),
+    message: (failedSnap && failedSnap.message) || '',
+  };
+}
+
+/**
+ * **游戏行状态的唯一判定**（单一真相）。
+ *
+ * 为什么必须只有一处：曾经行上的状态位来自"扫描监控"，而"加载失败 · 重试"来自 catalog 的 entry.status，
+ *   两者各画一套 ⇒ 同一行同时出现「扫描中 · 已读取 89 条」和「加载失败 · 重试」，
+ *   用户看到的是"明明还在读却说失败"。这里把两个来源合成一个枚举，视图只认它。
+ *
+ * 优先级（高 → 低）：
+ *   scanning   扫描流活着（未 stalled）⇒ 只能是"扫描中"，**绝不允许同时显示失败**
+ *   stalled    流超过阈值无帧 ⇒ 显示"疑似卡住"（可重试）
+ *   loading    没有流在跑，但有根正在取清单
+ *   error      取清单失败且**没有**活跃扫描（这才是真失败）
+ *   ready      至少一个根有数据
+ *   idle       从没加载过
+ *
+ * @param {{scan?: object|null, rootStates?: string[]}} input
+ *        scan = aggregateScanSnapshots(...) 的返回值；rootStates = 每个根的 entry.status
+ * @returns {'scanning'|'stalled'|'loading'|'error'|'ready'|'idle'}
+ */
+export function resolveGroupPhase({ scan, rootStates } = {}) {
+  const states = Array.isArray(rootStates) ? rootStates.filter(Boolean) : [];
+  const phase = scan && scan.phase ? String(scan.phase) : '';
+  // 流在推进：无论 catalog 那边报什么，行状态只能是扫描中
+  if (phase === 'scanning') return 'scanning';
+  if (phase === 'stalled') return 'stalled';
+  if (states.includes('loading')) return 'loading';
+  if (states.length && states.every((state) => state === 'error')) return 'error';
+  if (states.includes('error') && !states.includes('ready') && !states.includes('loading')) return 'error';
+  if (states.includes('ready')) return 'ready';
+  if (phase === 'failed') return 'error';
+  if (states.includes('idle') || !states.length) return 'idle';
+  return 'ready';
+}
+
+/**
+ * catalog 失败时该不该"暂缓判死"。
+ *
+ * 判据只有一条：该根的扫描流**仍在推进**（phase='scanning'）⇒ 清单没回来是"还在扫"，
+ *   不是"失败了"；应当保持 loading，等 done 帧后自动补取一次。
+ * 流已 stalled（超过阈值无帧）/ failed / 已结束 ⇒ 不再等，按失败处理。
+ * @param {string} scanPhase createScanMonitor().state.phase
+ * @returns {boolean}
+ */
+export function shouldDeferCatalogFailure(scanPhase) {
+  return String(scanPhase || '') === 'scanning';
+}
+
+/**
+ * 状态行文案（设计 §7.2）。返回 '' 表示"不显示额外提示"（交给原有渲染）。
+ * @param {object} snap createScanMonitor().state
+ * @returns {string}
+ */
+export function formatScanStatus(snap) {
+  if (!snap) return '';
+  if (snap.phase === 'scanning') {
+    return `扫描中 · 已读取 ${snap.scanned} 条 / ${snap.dirs} 个目录`;
+  }
+  if (snap.phase === 'stalled') {
+    const seconds = Math.max(1, Math.round(snap.stalledFor / 1000));
+    const where = snap.currentPath ? ` · 当前 ${snap.currentPath}` : '';
+    return `疑似卡住 · 已读取 ${snap.scanned} 条 · ${seconds} 秒无进展${where}`;
+  }
+  if (snap.phase === 'failed') {
+    return `扫描失败 · ${snap.message || '未知原因'}`;
+  }
+  return '';
+}
+
+/** 该状态是否需要显示〔重试〕按钮 */
+export function scanNeedsRetry(snap) {
+  return !!snap && (snap.phase === 'stalled' || snap.phase === 'failed');
+}

package/src/web/roster/snapshot.js

@@ -4,16 +4,16 @@
 //   DOM 里真的渲染了几行、最近一次定位动作是什么"一次性摊平，测试只读这份快照。
 
 /**
- * @param {{state: object, listEl: HTMLElement, gameStatus: (game: object) => string}} deps
+ * @param {{state: object, listEl: HTMLElement, groupStatus: (group: object) => string}} deps
  */
-export function snapshotRoster({ state, listEl, gameStatus }) {
-  const games = state.games.map((g) => {
-    const chars = state.gameChars.get(g.key);
+export function snapshotRoster({ state, listEl, groupStatus }) {
+  const groups = state.groups.map((g) => {
+    const chars = state.groupChars.get(g.key);
     return {
       key: g.key,
       name: g.name,
       roots: g.roots.map((r) => r.id),
-      status: gameStatus(g),
+      status: groupStatus(g),
       sources: g.roots.map((r) => (state.loaded.get(r.id) || {}).source || '').filter(Boolean),
       chars: chars ? chars.chars.length : 0,
       variants: chars ? chars.chars.reduce((n, c) => n + c.variants.length, 0) : 0,
@@ -21,15 +21,23 @@ export function snapshotRoster({ state, listEl, gameStatus }) {
     };
   });
   return {
-    games,
-    expandedGames: [...state.expandedGames],
+    groups,
+    expandedGroups: [...state.expandedGroups],
     expandedChars: [...state.expandedChars],
     keyword: state.keyword,
+    /** 类型筛选的选中集合（**存储原样**，可能含当前名册里不存在的失效项） */
+    typeFilter: state.typeFilter ? [...state.typeFilter] : [],
+    /** 正在扫描的根（断言"状态行数字在动"时读这里，不必解析文案） */
+    scan: state.scan ? [...state.scan.entries()].map(([rootId, cur]) => ({
+      rootId, phase: cur.monitor.state.phase, scanned: cur.monitor.state.scanned,
+      dirs: cur.monitor.state.dirs, currentPath: cur.monitor.state.currentPath,
+      stalledFor: cur.monitor.state.stalledFor,
+    })) : [],
     selected: state.selected,
     /** 最近一次"定位当前角色"的结果（visible / scrolled / skipped-user-scrolling / …） */
     lastReveal: state.lastReveal || null,
     domRows: {
-      games: listEl.querySelectorAll('[data-game-key].tree-game').length,
+      groups: listEl.querySelectorAll('[data-group-key].tree-game').length,
       chars: listEl.querySelectorAll('[data-char-key].tree-char').length,
       variants: listEl.querySelectorAll('[data-model-id]').length,
     },

package/src/web/roster/store.js

@@ -0,0 +1,292 @@
+// roster/store.js —— 名册**唯一状态持有者**（状态收口）
+//
+// 为什么要有它：名册原先有 7 份状态（loaded / scan / groupChars / expandedGroups /
+//   expandedChars / selected / scanBaseline）分散在 mount、ensureRootLoaded、trackScanProgress、
+//   loadGroup、ensureGroupLoaded、rebuildGroupChars、restoreLast、render 里各自直接改写。
+//   写入点一多，任何新功能（例如"增量加条目"）都会变成第 8、9 个写入点，行为难以推理。
+//
+// 约定：
+//   · **只有本文件可以写 state 的字段**；外部（view.js / snapshot.js）只读。
+//   · 所有变更走下面的动作方法；动作保持"最小原子"：只改状态，不夹带 UI 逻辑。
+//   · 渲染时机分两种（别假设"改完就一定会重画"）：
+//       ① 改结构/活跃分组的动作（setRoots / setActiveGroup）内部调 notify → 视图的 onChange；
+//       ② 其余动作**不** notify —— 由调用方在合适的时机自己补一次渲染（名册走 rAF 合批的 scheduleRender）。
+//     为什么②不统一 notify：加载期一条路径会连改十几次状态，每次 notify 就是十几次整树重绘；
+//       合批是名册首屏性能的关键（见 infra/schedule.js 文件头）。
+
+/**
+ * @param {{buildChars: Function, nameIndex?: Map, onChange?: () => void}} deps
+ *        buildChars(models, nameIndex, groupName) ⇒ { chars, stats }（由 view.js 注入，避免本文件依赖构建细节）
+ *        nameIndex 名表索引（同样由 view.js 注入）：本文件要"写完 models 就重算角色树"，
+ *          而归并需要它 —— 让 store 自己持有，调用方就不必每次记得传
+ */
+export function createRosterStore({ buildChars, nameIndex, onChange } = {}) {
+  const state = {
+    /** 按 name 合并后的游戏列表（结构：{ key, name, roots[] }） */
+    groups: [],
+    /** rootId → { status, models, source, error, promise, pendingCatalogRetry } */
+    loaded: new Map(),
+    /** rootId → { monitor, controller, group }（扫描进行中的根） */
+    scan: new Map(),
+    /** groupKey → { chars, stats }（跨根归并后的角色树） */
+    groupChars: new Map(),
+    expandedGroups: new Set(),
+    expandedChars: new Set(),
+    selected: null,
+    keyword: '',
+    typeFilter: new Set(),
+    /** groupKey → { scanned, dirs }（多根逐根扫描时的计数基线） */
+    scanBaseline: new Map(),
+    /** 当前活跃的**分组**名（注意：语义是"分组"，不假设它一定是游戏） */
+    activeGroup: null,
+    /** 本页生命周期内已经跑过进度流的根（防止重复订阅） */
+    scannedRoots: new Set(),
+    /** 后台形态探测队列快照：{ remaining, at, rootId }（UI 未实现，数据先就绪） */
+    probe: { remaining: null, at: null, rootId: null },
+    /** 最近一次"定位到当前项"的结果（滚动/已可见/用户正在滚动…） */
+    lastReveal: null,
+  };
+
+  const notify = () => {
+    if (typeof onChange === 'function') {
+      try { onChange(); } catch { /* 视图回调异常不影响状态 */ }
+    }
+  };
+
+  /** 读：某根的加载条目（不存在返回 null，不隐式创建） */
+  const rootEntry = (rootId) => state.loaded.get(String(rootId)) || null;
+
+  /**
+   * 跨根归并该组的角色树（内部实现，`setRootModels` 与公开动作 `rebuildChars` 共用一份）。
+   *
+   * 只收 `status === 'ready'` 的根：还在 loading / 已 error 的根不参与归并，
+   *   否则半截数据会先被画出来（用户看到角色数忽多忽少）。
+   * @param {string} groupKey
+   */
+  function rebuildCharsFor(groupKey) {
+    const group = state.groups.find((g) => g.key === String(groupKey));
+    if (!group) return null;
+    const models = [];
+    for (const root of group.roots) {
+      const entry = state.loaded.get(root.id);
+      if (entry && entry.status === 'ready') models.push(...(entry.models || []));
+    }
+    const built = buildChars(models, nameIndex, group.name);
+    state.groupChars.set(group.key, built);
+    return built;
+  }
+
+  const actions = {
+    state,
+
+    // ---------------------------------------------------------------- 根与游戏
+    /**
+     * 重建游戏列表（按 name 合并同名根）。
+     * @param {Array} roots /api/roots 的 roots
+     * @returns {Array} 合并后的 groups
+     */
+    setRoots(roots) {
+      const byName = new Map();
+      for (const root of Array.isArray(roots) ? roots : []) {
+        const name = root.name || root.id;
+        if (!byName.has(name)) byName.set(name, { key: `group:${name}`, name, roots: [] });
+        byName.get(name).roots.push(root);
+      }
+      state.groups = [...byName.values()];
+      notify();
+      return state.groups;
+    },
+
+    /** 某根所属的游戏 */
+    groupOfRoot(rootId) {
+      return state.groups.find((g) => g.roots.some((r) => r.id === rootId)) || null;
+    },
+
+    // ---------------------------------------------------------------- 根的加载状态
+    /**
+     * 写某根的加载状态（浅合并；不传的字段保持不变）。
+     * @param {string} rootId
+     * @param {object} patch 例：{ status:'loading' } / { status:'error', error:'…' }
+     */
+    setRootStatus(rootId, patch) {
+      const id = String(rootId);
+      const cur = state.loaded.get(id) || { status: 'idle', models: [], source: '', error: null, promise: null };
+      state.loaded.set(id, { ...cur, ...(patch || {}) });
+    },
+
+    /** 读某根条目 */
+    getRoot(rootId) {
+      return rootEntry(rootId);
+    },
+
+    /** 清掉若干根的加载状态（重试用：让它们回到"未加载"） */
+    resetRoots(rootIds) {
+      for (const id of rootIds || []) state.loaded.delete(String(id));
+    },
+
+    /**
+     * 写某根的模型清单（权威全量）。
+     *
+     * **写完自动重算该根所属组的角色树**（派生状态跟着源状态走）。
+     *   为什么在这里而不是让调用方各自记得调 rebuildChars：调用方一多必然漏 ——
+     *   实测过一次：restoreLast 那条路径漏了归并 ⇒ 加载完成后行上 0 角色、
+     *   收起再展开才出现（第二次走的是另一条会归并的路径）。把重算钉在唯一的
+     *   写入入口上，新增调用方就不可能再漏。
+     * @param {string} rootId
+     * @param {Array} models
+     * @param {{authoritative?: boolean, source?: string}} [opts]
+     */
+    setRootModels(rootId, models, opts = {}) {
+      const id = String(rootId);
+      const entry = state.loaded.get(id);
+      if (!entry) return;
+      entry.models = Array.isArray(models) ? models : [];
+      if (opts.source) entry.source = String(opts.source);
+      if (opts.authoritative !== false) entry.status = 'ready';
+      // 就绪状态已落地，此刻归并才拿得到这份 models（rebuildChars 只收 status==='ready' 的根）
+      const group = actions.groupOfRoot(id);
+      if (group) rebuildCharsFor(group.key);
+    },
+
+    // ---------------------------------------------------------------- 扫描
+    updateScan(rootId, payload) {
+      state.scan.set(String(rootId), payload);
+    },
+
+    clearScan(rootId) {
+      state.scan.delete(String(rootId));
+    },
+
+    getScan(rootId) {
+      return state.scan.get(String(rootId)) || null;
+    },
+
+    setScanBaseline(groupKey, base) {
+      state.scanBaseline.set(String(groupKey), base);
+    },
+
+    getScanBaseline(groupKey) {
+      return state.scanBaseline.get(String(groupKey)) || null;
+    },
+
+    clearScanBaseline(groupKey) {
+      state.scanBaseline.delete(String(groupKey));
+    },
+
+    // ---------------------------------------------------------------- 角色树
+    /**
+     * 用该组各根**已就绪**的模型重建角色树（跨根归并）。
+     *
+     * 正常流程里不需要手动调：`setRootModels` 写完就会自动重算（见那里的注释）。
+     *   留成公开动作是为了"幂等兜底"：某些路径上模型早已就绪、本次没有新的写入
+     *   （例如重复展开一个已加载的组），调用方仍可显式要求"确保已归并"。
+     * @param {string} groupKey
+     * @returns {object|null} { chars, stats }
+     */
+    rebuildChars(groupKey) {
+      return rebuildCharsFor(groupKey);
+    },
+
+    // ---------------------------------------------------------------- 展开态
+    toggleGroup(groupKey) {
+      const key = String(groupKey);
+      const next = !state.expandedGroups.has(key);
+      if (next) state.expandedGroups.add(key); else state.expandedGroups.delete(key);
+      return next;
+    },
+
+    expandGroup(groupKey) {
+      state.expandedGroups.add(String(groupKey));
+    },
+
+    collapseAll() {
+      state.expandedGroups.clear();
+      state.expandedChars.clear();
+    },
+
+    toggleChar(charKey) {
+      const key = String(charKey);
+      const next = !state.expandedChars.has(key);
+      if (next) state.expandedChars.add(key); else state.expandedChars.delete(key);
+      return next;
+    },
+
+    expandChar(charKey) {
+      state.expandedChars.add(String(charKey));
+    },
+
+    /** 恢复持久化里的展开态（只保留仍存在的游戏） */
+    restoreExpanded({ groups, chars }) {
+      const keys = new Set(state.groups.map((g) => g.key));
+      for (const key of groups || []) if (keys.has(key)) state.expandedGroups.add(key);
+      for (const key of chars || []) state.expandedChars.add(key);
+    },
+
+    // ---------------------------------------------------------------- 选中 / 关键词 / 筛选
+    /**
+     * 写选中项。
+     * @param {{modelId:string, groupKey:string, groupName:string|null, charKey:string}|null} payload
+     */
+    selectModel(payload) {
+      state.selected = payload || null;
+    },
+
+    setKeyword(keyword) {
+      state.keyword = String(keyword || '').trim().toLowerCase();
+    },
+
+    toggleTypeFilter(typeKey) {
+      const key = String(typeKey);
+      const next = !state.typeFilter.has(key);
+      if (next) state.typeFilter.add(key); else state.typeFilter.delete(key);
+      return next;
+    },
+
+    clearTypeFilter() {
+      state.typeFilter.clear();
+    },
+
+    /** 一次性把筛选集合替换掉（测试/外部恢复用；正常交互请用 toggleTypeFilter） */
+    setTypeFilter(keys) {
+      state.typeFilter = new Set(keys || []);
+    },
+
+    // ---------------------------------------------------------------- 分组 / 订阅标记 / 探测 / 定位
+    /**
+     * 写"当前活跃分组"（分组名，不是 groupKey）。
+     * @param {string|null} name
+     */
+    setActiveGroup(name) {
+      state.activeGroup = name ? String(name) : null;
+      notify();
+    },
+
+    /** 标记某根已订阅过进度流（防重复订阅） */
+    markRootSubscribed(rootId) {
+      state.scannedRoots.add(String(rootId));
+    },
+
+    unmarkRootSubscribed(rootId) {
+      state.scannedRoots.delete(String(rootId));
+    },
+
+    hasRootSubscribed(rootId) {
+      return state.scannedRoots.has(String(rootId));
+    },
+
+    /**
+     * 写后台形态探测快照。
+     * @param {{remaining:number|null, at:number, rootId:string|null}} snapshot
+     */
+    setProbe(snapshot) {
+      state.probe = { ...(snapshot || {}) };
+    },
+
+    /** 写"最近一次定位结果"（reveal 的返回值，排障与断言读它） */
+    setLastReveal(result) {
+      state.lastReveal = result || null;
+    },
+  };
+
+  return actions;
+}