modelstage 0.0.0-stage → 0.5.24

package/src/web/app/entry-report.js

@@ -0,0 +1,71 @@
+// app/entry-report.js —— 装载结果上报（契约《条目状态与展示归属》§三 的前端侧）
+//
+// 为什么要有这一层：装载成功/失败都必须写进服务端的条目状态，并且**立刻**把那一行画对。
+//   服务端的 POST /api/entries/result 是"写读一体"的：响应里就带回重算后的
+//   display/support/loadResult。所以这里一次请求同时完成两件事，不需要再拉 /api/catalog
+//   （那是秒级扫描，为一行颜色付这个代价是浪费，而且刚解包时它未必已经能看到）。
+//
+// 旁路原则（契约 INV-D3）：上报失败**绝不能**影响装载结果 —— 所有异常在这里吞掉只记日志。
+import { postJson } from '../infra/api.js';
+import { stageLog } from './status.js';
+import { state } from './context.js';
+
+/**
+ * 条目的状态键：与 VFS 前缀同构，`${rootId}/${rel}`。
+ *
+ * 为什么不用条目 id：容器 id 是 `bundle-<rootId>-<rel 把 / 换成 _>` 派生的，**不可逆**，
+ *   不同 rel 可能撞成同一个键；而 rootId/rel 是解包与存储都天然认得的形态。
+ * @param {object} model 名册条目
+ * @returns {string} 空串 = 这个条目没有可用的键（调用方应跳过上报）
+ */
+export function entryStateKey(model) {
+  const rootId = String((model && model.rootId) || '');
+  const rel = String((model && (model.rel || model.srcDir || model.name)) || '');
+  if (!rootId || !rel) return '';
+  return `${rootId}/${rel}`;
+}
+
+/**
+ * 上报一次装载结果，并用响应就地更新名册那一行。
+ *
+ * @param {object} model 名册条目
+ * @param {{result: 'ok'|'failed', reason?: string|null, message?: string|null,
+ *          provider?: string|null}} outcome 结果（reason 用契约码，message 是人话）
+ * @returns {Promise<object|null>} 服务端重算后的三字段；失败/未上报返回 null
+ */
+export async function reportEntryResult(model, outcome) {
+  const key = entryStateKey(model);
+  if (!key) return null;
+  const body = {
+    key,
+    result: outcome.result === 'ok' ? 'ok' : 'failed',
+    reason: outcome.reason || null,
+    message: outcome.message || null,
+    provider: outcome.provider || null,
+    size: Number.isFinite(model && model.size) ? Number(model.size) : undefined,
+    source: 'client',
+  };
+  try {
+    const res = await postJson('/api/entries/result', body, { retries: 0 });
+    const computed = res && res.entry ? res.entry : null;
+    if (computed) {
+      // 必须走名册的写回入口，不能只刷 DOM：
+      //   传进来的 model 是 normalizeEntry 的**副本**（`{ ...entry }`），
+      //   改它不会影响名册渲染用的那个对象 ⇒ 下一次 render 就读回旧值，
+      //   表现为"当场变了色、一切换/搜索就掉回中性色"（实测的老 bug）。
+      //   setEntryState 按 id 找到名册持有的原对象、写回三字段，再重画那一行。
+      const roster = state.roster;
+      const id = String((model && (model.id || model.name)) || '');
+      try {
+        if (roster && typeof roster.setEntryState === 'function' && id) roster.setEntryState(id, computed);
+      } catch { /* 名册刷新失败不影响装载，也不影响已写入的服务端状态 */ }
+    }
+    return computed;
+  } catch (e) {
+    // 旁路：上报失败只记一条 info，绝不升级成装载失败
+    try {
+      stageLog('info', `装载结果未上报（${(e && e.message) || e}）：${key}`, { key, result: body.result });
+    } catch { /* 日志失败也不影响 */ }
+    return null;
+  }
+}

package/src/web/app/memory-bars.js

@@ -0,0 +1,91 @@
+// app/memory-bars.js —— 内存三色条的两个挂载点（舞台顶部 / 设置面板）统一管理
+//
+// 为什么要这一层：面板会重建、舞台容器常在，两处各有自己的生命周期。
+//   组件本身（panel/memory-bar.js）只管"画一条"；谁该在什么时候拉数据、要不要显示，
+//   集中在这么一个小模块里，免得散落到 model-actions / panel-settings / shell-controls 各处。
+//
+// 刷新时机（事件驱动，无定时器）：
+//   · 模型加载成功后          → refreshStage()
+//   · 面板重建（展开设置时）  → refreshPanel()
+//   · 「显示状态信息」开关    → setStageVisible()（关掉时舞台那条跟着消失，与状态行同策略）
+
+import { mountMemoryBar } from '../panel/memory-bar.js';
+
+/** 舞台顶部那条（容器在 index.html 里） */
+const stageBar = mountMemoryBar('#mem-bar-stage');
+
+/** 设置面板里那条（容器由 schema 的 ctl-memory-bar 提供） */
+const panelBar = mountMemoryBar('#right-panel [data-ctl="ctl-memory-bar"]');
+
+/** 舞台那条是否允许显示（跟「显示状态信息」开关走，默认开） */
+let stageVisible = true;
+
+/**
+ * 刷新舞台顶部那条（模型加载成功后调用）。
+ * @returns {Promise<boolean>} 是否显示成功
+ */
+export async function refreshStage() {
+  if (!stageVisible) { stageBar.hide(); return false; }
+  return stageBar.refresh();
+}
+
+/**
+ * 刷新设置面板那条（面板重建后调用）。
+ * @returns {Promise<boolean>}
+ */
+export async function refreshPanel() {
+  return panelBar.refresh();
+}
+
+/**
+ * 「显示状态信息」开关联动：关掉时舞台那条立即隐藏（不拉数据、不留空壳）。
+ * @param {boolean} on
+ */
+export function setStageVisible(on) {
+  stageVisible = on !== false;
+  if (!stageVisible) { stageBar.hide(); return; }
+  // 打开时补拉一次（此刻可能还没有数据）
+  refreshStage().catch(() => { /* 失败已由组件内部记 warn 并隐藏 */ });
+}
+
+/**
+ * 绑定「展开设置面板 → 拉一次」（文档 §五）。
+ * 面板重建时也会调 refreshPanel，但"点开设置组"不重建面板 ⇒ 单独绑点击。
+ * 幂等：只绑一次。
+ * @returns {boolean} 本次是否新绑定
+ */
+let bound = false;
+export function bindPanelBarRefresh() {
+  if (bound) return false;
+  bound = true;
+  document.addEventListener('click', (ev) => {
+    const trigger = ev.target && typeof ev.target.closest === 'function'
+      ? ev.target.closest('#right-panel .acc-trigger')
+      : null;
+    if (!trigger) return;
+    const label = (trigger.textContent || '').trim();
+    // 只关心「设置」组：其它组与内存无关，不必拉数据
+    if (!label.includes('设置')) return;
+    refreshPanel().catch(() => { /* 失败已由组件记 warn 并隐藏 */ });
+  }, true);
+  return true;
+}
+
+/** 供断言：两处当前显示的数值（无数据返回 null） */
+export function memoryBarSnapshot() {
+  const read = (sel) => {
+    const bar = document.querySelector(sel);
+    if (!bar || bar.hidden) return null;
+    return {
+      aria: bar.getAttribute('aria-label'),
+      text: (bar.querySelector('.mem-bar-text') || {}).textContent || '',
+      pct: {
+        server: bar.dataset.pctServer, other: bar.dataset.pctOther, avail: bar.dataset.pctAvail,
+      },
+    };
+  };
+  return {
+    stage: read('#mem-bar-stage .mem-bar'),
+    panel: read('#right-panel [data-ctl="ctl-memory-bar"] .mem-bar'),
+  };
+}

package/src/web/app/memory-budget.js

@@ -0,0 +1,228 @@
+// app/memory-budget.js —— 内存判据的**唯一决策入口**（策略层）
+//
+// 为什么要有这一层：项目里曾经同时存在三处"防内存打爆"的判断，各写各的
+//   ① capacity.mjs 用「可用内存 × 0.5 vs 预估峰值」——有权威翻译器、受开关控、文案带数字
+//   ② memory-guard.js 用「JS 堆 85%」——受开关控
+//   ③ plugin-host.js 用「裸包字节 > 512MB 硬编码」——不受开关控、文案丢数字、更不看内存余量
+//   同一个包在 8GB 机器上没事、在 2GB 机器上必炸，第③处却一视同仁地拦。
+//   所以这里把"能不能做"收成一个函数，谁要判断都问它。
+//
+// 🔴 铁律：**前端不自己算倍数**。
+//   「包字节 → 预估峰值」的权威实现只有服务端 capacity.mjs 的 estimatePeakMb（三档实测上包络），
+//   前端自己写 bytes*20 之类的倍数 = 又造一个新口径，正是本任务要消灭的东西。
+//
+// 数据源分工（不许越界）：
+//   · 服务端内存：只能从 GET /api/unpack/capacity 拿（浏览器里读不到系统内存）
+//   · 前端堆占用：只能从浏览器 performance.memory 拿（服务端读不到）
+
+import { memStats } from '../infra/mem-stats.js';
+import { stageLog } from './status.js';
+
+/**
+ * 前端堆占用阈值（路径 B / C 与 assess 共用**同一个**值）。
+ * 为什么放在这里：判据口径只允许有一份，memory-guard 从这里 import ——
+ *   两边各写一个 0.85 就是新一轮"同一事实两处表达"，迟早漂移。
+ *
+ * 缺省 0.85；服务端可用 **MODELSTAGE_ADMIT_HEAP_RATIO** 覆盖，
+ *   经 `GET /api/web-config` 的 `admitHeapRatio` 下发到前端（前端读不到 env）。
+ * 这里用 `let` 而不是 const：下发值要在启动后覆盖缺省，而 import 方拿到的是**活绑定**，
+ *   memory-guard 里那些 `h.pct > HEAP_RATIO` 无需改动就会看到新值。
+ */
+export let HEAP_RATIO = 0.85;
+/** 缺省值（下发值缺失/非法时回落到它；也是文档里写的那个数） */
+export const DEFAULT_HEAP_RATIO = 0.85;
+
+/**
+ * 应用服务端下发的准入配置（幂等；非法值回落缺省并 warn 一次）。
+ * @param {{admitHeapRatio?: number}} cfg /api/web-config 的响应
+ * @returns {{ratio: number, applied: boolean}}
+ */
+export function applyAdmitConfig(cfg) {
+  if (!cfg || cfg.admitHeapRatio === undefined || cfg.admitHeapRatio === null) {
+    return { ratio: HEAP_RATIO, applied: false };
+  }
+  const v = Number(cfg.admitHeapRatio);
+  const ok = Number.isFinite(v) && v > 0 && v <= 1;
+  if (!ok) {
+    // 不静默：下发值非法时说明白用的是哪个数，否则"为什么阈值没变"只能靠猜
+    try { stageLog('warn', `准入堆比例下发值非法（${JSON.stringify(cfg.admitHeapRatio)}）—— 继续用 ${HEAP_RATIO}`); } catch { /* 日志失败不影响判据 */ }
+    return { ratio: HEAP_RATIO, applied: false };
+  }
+  HEAP_RATIO = v;
+  try { stageLog('info', `准入堆比例已按服务端下发调整：${v}`); } catch { /* 同上 */ }
+  return { ratio: HEAP_RATIO, applied: true };
+}
+
+/** 服务端判据缓存时长：同一个包在短时间内反复判断不该每次都打服务端 */
+const CAP_TTL_MS = 5000;
+
+/** 开关状态镜像（由 memory-guard.setMemoryGuard 同步过来，避免两层互相 import 成环） */
+let guardEnabled = true;
+
+/** 缓存：key = 包 MB（取整）/ 'machine' → { at, value } */
+const capCache = new Map();
+
+/** 实际发起过的服务端请求次数（验收"缓存生效"用） */
+let fetchCount = 0;
+
+/**
+ * 同步"内存保护开关"状态。memory-guard.setMemoryGuard 里会调它。
+ * @param {boolean} on
+ */
+export function setBudgetGuardEnabled(on) {
+  guardEnabled = on !== false;
+}
+
+/** @returns {boolean} 当前是否受开关约束 */
+export function isBudgetGuardEnabled() {
+  return guardEnabled;
+}
+
+/**
+ * 取服务端判据（带 5 秒缓存）。
+ * @param {number} sourceMb 包大小（MB）；0/缺省 ⇒ 只问机器级信息
+ * @returns {Promise<object|null>} 拿不到返回 null（调用方按"这一路不可用"处理）
+ */
+async function fetchServerJudgement(sourceMb) {
+  const key = sourceMb > 0 ? String(Math.round(sourceMb)) : 'machine';
+  const hit = capCache.get(key);
+  if (hit && Date.now() - hit.at < CAP_TTL_MS) return hit.value;
+  const qs = sourceMb > 0 ? `?sourceMb=${encodeURIComponent(sourceMb)}` : '';
+  try {
+    fetchCount += 1;
+    const res = await fetch(`/api/unpack/capacity${qs}`, {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(2000),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const j = await res.json();
+    capCache.set(key, { at: Date.now(), value: j });
+    return j;
+  } catch (err) {
+    stageLog('warn', `内存判据取不到服务端数据：${String((err && err.message) || err)}`, { sourceMb });
+    return null;
+  }
+}
+
+/** 读前端堆占用（不可用返回 null，不瞎估） */
+function heapStats() {
+  try {
+    const s = memStats();
+    if (s.jsHeapPct === null || s.jsHeapPct === undefined) return null;
+    return { pct: s.jsHeapPct, usedMB: s.jsHeapMB, limitMB: s.jsHeapLimitMB };
+  } catch {
+    return null;
+  }
+}
+
+/** 百分比显示：不足 1% 写成 <1%（写 0% 会让人以为没数据） */
+function pctText(pct) {
+  return pct < 0.01 ? '<1' : String(Math.round(pct * 100));
+}
+
+/**
+ * 统一决策：这次操作能不能做。
+ *
+ * 判据取**更严格的一路**（任一路不通过即不通过）；两路都拿不到 ⇒ **放行 + 记日志**
+ *   —— 拿不到真值时不假装保护，否则会变成"在某些浏览器上永远加载不了"。
+ *
+ * @param {object} opts
+ * @param {number} [opts.bytesHint] 已知的包字节数（能算出预估峰值）
+ * @param {'web-load'|'web-unpack'|'web-long-op'} [opts.where] 调用场景（只影响文案与默认策略）
+ * @param {string} [opts.label] 对象名（写进文案，让用户知道是哪一步被拦）
+ * @returns {Promise<{ok:boolean, reason:string, numbers:object, message:string}>}
+ *   numbers: { pkgBytes, peakEstMb, budgetMb, availMb, heapPct, usedMB, limitMB }
+ */
+export async function assess(opts = {}) {
+  const where = opts.where || 'web-load';
+  const label = String(opts.label || '').trim();
+  const bytes = Number(opts.bytesHint) > 0 ? Number(opts.bytesHint) : 0;
+  const numbers = {
+    pkgBytes: bytes || null,
+    peakEstMb: null,
+    budgetMb: null,
+    availMb: null,
+    heapPct: null,
+    usedMB: null,
+    limitMB: null,
+  };
+
+  if (!guardEnabled) {
+    // 开关关闭：**连绝对兜底也不拦**（用户明示要试）
+    return { ok: true, reason: 'guard-off', numbers, message: '' };
+  }
+
+  // 路 A｜服务端：包字节 → 预估峰值 / 预算 / 可用
+  const srv = await fetchServerJudgement(bytes > 0 ? bytes / 1024 / 1024 : 0);
+  const heap = heapStats();
+  let serverJudged = false;
+  let serverFails = false;
+  let serverDetail = '';
+  if (srv && Number.isFinite(srv.peakEstMb) && Number.isFinite(srv.budgetMb)) {
+    serverJudged = true;
+    numbers.peakEstMb = srv.peakEstMb;
+    numbers.budgetMb = srv.budgetMb;
+    numbers.availMb = Number.isFinite(srv.memAvailableMb) ? srv.memAvailableMb : null;
+    if (srv.peakEstMb > srv.budgetMb) {
+      serverFails = true;
+      serverDetail = `预估峰值 ${srv.peakEstMb}MB 超过可用预算 ${srv.budgetMb}MB（当前可用 ${numbers.availMb}MB × 0.5）`;
+    }
+  }
+  if (heap) {
+    numbers.heapPct = heap.pct;
+    numbers.usedMB = heap.usedMB;
+    numbers.limitMB = heap.limitMB;
+  }
+
+  // 两路都拿不到 ⇒ 放行 + 记日志（不假装保护）
+  if (!serverJudged && !heap) {
+    stageLog('warn', `内存判据两路都不可用，放行（${where}${label ? ` · ${label}` : ''}）`, { where, bytes });
+    return { ok: true, reason: 'unjudgeable', numbers, message: '' };
+  }
+
+  const heapFails = !!(heap && heap.pct > HEAP_RATIO);
+  if (serverFails || heapFails) {
+    return {
+      ok: false,
+      reason: serverFails ? 'insufficient-memory' : 'heap-high',
+      numbers,
+      message: buildMessage({ where, label, serverFails, heapFails, serverDetail, numbers }),
+    };
+  }
+  return { ok: true, reason: 'ok', numbers, message: '' };
+}
+
+/**
+ * 统一文案模板（三处同一套格式）：`无法<动作>「<对象>」：<判据含真实数字>。<能怎么办>`
+ *
+ * 为什么必须带数字：只说"内存不足/文件过大"，用户无法判断该关标签页、拆包还是换机器。
+ * @returns {string}
+ */
+export function buildMessage({ where, label, serverFails, heapFails, serverDetail, numbers }) {
+  const obj = label ? `「${label}」` : '';
+  const verb = where === 'web-unpack' ? '解包' : (where === 'web-long-op' ? '继续' : '加载');
+  const parts = [];
+  if (serverFails && serverDetail) parts.push(serverDetail);
+  if (heapFails && numbers.heapPct !== null) {
+    parts.push(`内存占用较高（${numbers.usedMB} MB / ${numbers.limitMB} MB，${pctText(numbers.heapPct)}%）`);
+  }
+  const why = parts.join('；');
+  const advice = where === 'web-unpack'
+    ? '可先关闭其他程序，或改用更小的包。'
+    : (where === 'web-long-op'
+      ? '已完成的文件保留，可稍后重试剩余部分。'
+      : '请关闭其他标签页后重试。');
+  return `无法${verb}${obj}：${why}。${advice}`;
+}
+
+/** 验收用：已发起的服务端判据请求次数 */
+export function budgetStats() {
+  return { fetchCount, cachedKeys: [...capCache.keys()] };
+}
+
+/** 供测试重置 */
+export function __resetMemoryBudgetForTest() {
+  capCache.clear();
+  fetchCount = 0;
+  guardEnabled = true;
+}

package/src/web/app/memory-guard.js

@@ -0,0 +1,204 @@
+// app/memory-guard.js —— 内存保护（一个开关管三条路径）
+//
+// 与 ctl-hang-guard 的区别（别混）：
+//   memoryGuard（本文件） = **内存容量**保护 → 防 OOM / 页面崩溃
+//   ctl-hang-guard        = **帧停滞**看门狗 → 画面停住时尝试自愈
+//   两者并列、互不替代。
+//
+// 三条路径：
+//   A 服务端解包准入：开关开＝超预算拒绝（既有行为）；关＝请求带 allowOverLimit 强行解包。
+//     判断全在服务端（capacity.mjs 读系统内存），前端不自己算阈值。
+//   B 前端加载前预检：jsHeap 占上限比例 > HEAP_RATIO 就拒绝并给出真实数字。
+//   C 长操作中监控：解包/批量加载期间按帧采样 jsHeap，超限即中止（已完成的文件保留）。
+//
+// 为什么数值必须取真值：只说"内存不足"用户无法判断该拆包还是该关标签页 ——
+//   所以所有提示都带「当前 / 上限 / 百分比 / MB」。
+
+import { memStats } from '../infra/mem-stats.js';
+import { HEAP_RATIO, assess, buildMessage, setBudgetGuardEnabled } from './memory-budget.js';
+
+export { HEAP_RATIO };
+
+/** 操作中监控的采样间隔（帧）—— 每 20 帧约 1/3 秒，够快且不干扰渲染 */
+export const MONITOR_FRAME_STRIDE = 20;
+
+/** 开关状态（默认开：保持"服务端永远准入判断"的现状，关才放行） */
+let enabled = true;
+
+/** 最近一次判据读数（面板显示 + 断言都用它，避免各处各取一次导致数字对不上） */
+let readout = { availMb: null, totalMb: null, peakEstMb: null, budgetMb: null, at: 0, error: '' };
+
+/**
+ * 设置开关（面板 ctl-memory-guard 变化时调用）。
+ * @param {boolean} on
+ * @returns {boolean} 生效后的值
+ */
+export function setMemoryGuard(on) {
+  enabled = on !== false;
+  setBudgetGuardEnabled(enabled);   // 判据层与开关状态保持同步（它不 import 本文件，避免成环）
+  try { document.documentElement.dataset.memoryGuard = enabled ? 'on' : 'off'; } catch { /* 忽略 */ }
+  return enabled;
+}
+
+/** @returns {boolean} 内存保护是否开启 */
+export function isMemoryGuardOn() {
+  return enabled;
+}
+
+/**
+ * 读前端堆占用（真值来自 performance.memory，不可用时返回 null 而不是瞎估）。
+ * @returns {{usedMB:number|null, limitMB:number|null, pct:number|null}}
+ */
+export function heapSnapshot() {
+  const s = memStats();
+  return { usedMB: s.jsHeapMB, limitMB: s.jsHeapLimitMB, pct: s.jsHeapPct };
+}
+
+/**
+ * 路径 B：加载大模型前的预检。
+ *
+ * 判不了（浏览器不暴露 performance.memory，如 Firefox/Safari）就**放行** ——
+ *   拿不到真值时不假装保护，否则会变成"在部分浏览器上永远加载不了"。
+ * @param {string} what 要加载的东西（写进提示，便于用户知道是哪一步被拦）
+ * @returns {{ok: boolean, message?: string, usedMB?: number|null, limitMB?: number|null, pct?: number|null}}
+ */
+export async function preflightLoad(what) {
+  // 判断口径全部交给 memory-budget.assess（服务端容量 + 前端堆两路取更严格），
+  //   这里只负责把结果翻成调用方要的形状，不自己算任何阈值。
+  if (!enabled) return { ok: true };
+  const r = await assess({ where: 'web-load', label: what });
+  return { ok: r.ok, message: r.message, reason: r.reason, ...r.numbers };
+}
+
+/**
+ * 解包判据（供 plugin-host 在装载容器包前调用）：包字节 → 预估峰值 vs 可用预算。
+ * 内部就是 assess({ where:'web-unpack' })，前端不算任何倍数。
+ * @param {string} label 对象名
+ * @param {number} bytes 包字节数
+ * @returns {Promise<{ok:boolean, reason:string, numbers:object, message:string}>}
+ */
+export function assessUnpack(label, bytes) {
+  if (!enabled) return Promise.resolve({ ok: true, reason: 'guard-off', numbers: {}, message: '' });
+  return assess({ where: 'web-unpack', label, bytesHint: bytes });
+}
+
+/**
+ * 路径 C：长操作中的内存监控。
+ *
+ * 用法：
+ *   const mon = startMemoryMonitor('解包');
+ *   for (...) { await one(); if (mon.aborted()) break; }   // 中止但保留已完成的部分
+ *   mon.stop();
+ *
+ * 为什么按帧采样而不是 setInterval：跟着渲染循环走，页面不可见时自然降频，
+ *   不会在后台标签页里空转（符合《事件驱动优先》）。
+ * @param {string} label 操作名（写进日志与提示）
+ * @returns {{stop: () => void, aborted: () => boolean, reason: () => string, samples: () => number}}
+ */
+export function startMemoryMonitor(label) {
+  const state = { hit: false, why: '', n: 0, frames: 0 };
+  let raf = 0;
+  let cancelled = false;
+
+  /** 采一次样并判定（帧回调与同步检查共用这一处，避免两套判定漂移） */
+  const sample = () => {
+    if (state.hit || cancelled) return;
+    state.n += 1;
+    const h = heapSnapshot();
+    if (!enabled || h.pct === null || h.pct <= HEAP_RATIO) return;
+    state.hit = true;
+    // 文案走统一模板（三处同一套格式），不再各处手拼
+    state.why = buildMessage({
+      where: 'web-long-op',
+      label: String(label).trim(),
+      serverFails: false,
+      heapFails: true,
+      serverDetail: '',
+      numbers: { heapPct: h.pct, usedMB: h.usedMB, limitMB: h.limitMB },
+    });
+    try { document.documentElement.dataset.memGuardAbort = label; } catch { /* 忽略 */ }
+  };
+
+  const tick = () => {
+    if (cancelled || state.hit) return;
+    state.frames += 1;
+    // 首帧就采一次，之后每 MONITOR_FRAME_STRIDE 帧一次。
+    //   原来只在 %STRIDE===0 时采 ⇒ "几帧内跑完"的短操作等于没有监控
+    //   （实测：取 19 个小文件一帧都没跨过，监控从未触发）。
+    if (state.frames === 1 || state.frames % MONITOR_FRAME_STRIDE === 0) sample();
+    if (state.hit) return;
+    raf = requestAnimationFrame(tick);
+  };
+  if (typeof requestAnimationFrame === 'function') raf = requestAnimationFrame(tick);
+
+  return {
+    stop: () => { cancelled = true; try { cancelAnimationFrame(raf); } catch { /* 忽略 */ } },
+    aborted: () => state.hit,
+    reason: () => state.why,
+    samples: () => state.n,
+    /**
+     * 同步采样一次，返回是否已越线。
+     *
+     * 为什么需要：按帧采样对"密集但总时长短"的循环无能为力 —— 取 19 个小文件可能一帧都没跨过，
+     *   那时监控等于不存在。调用方在每步开始前调它，就能在"还没排到下一帧"时也发现越线。
+     */
+    checkNow: () => { sample(); return state.hit; },
+  };
+}
+
+/**
+ * 刷新判据读数（面板「内存判据」那行显示的真实值）。
+ *
+ * 数值来源必须是服务端的 /api/unpack/capacity（由它读系统内存），
+ *   前端不许自己拍脑袋算"大概够不够"。
+ * @param {{rootId?: string, rel?: string}} [target] 给了就带上该包的需求估算
+ * @returns {Promise<object>} 服务端返回的判据（失败时返回 {error}）
+ */
+export async function refreshMemoryReadout(target) {
+  const qs = target && target.rootId && target.rel
+    ? `?rootId=${encodeURIComponent(target.rootId)}&rel=${encodeURIComponent(target.rel)}`
+    : '';
+  try {
+    const res = await fetch(`/api/unpack/capacity${qs}`, {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(2000),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const j = await res.json();
+    readout = {
+      availMb: Number.isFinite(j.memAvailableMb) ? j.memAvailableMb : null,
+      totalMb: Number.isFinite(j.memTotalMb) ? j.memTotalMb : null,
+      peakEstMb: Number.isFinite(j.peakEstMb) ? j.peakEstMb : null,
+      budgetMb: Number.isFinite(j.budgetMb) ? j.budgetMb : null,
+      at: Date.now(),
+      error: '',
+    };
+    return { ...j, readout };
+  } catch (err) {
+    readout = { ...readout, at: Date.now(), error: String((err && err.message) || err) };
+    return { error: readout.error, readout };
+  }
+}
+
+/** 最近一次读数（断言用） */
+export function memoryReadout() {
+  return { ...readout };
+}
+
+/** 供测试/断言的整体快照 */
+export function memGuardSnapshot() {
+  return {
+    enabled,
+    heapRatio: HEAP_RATIO,
+    heap: heapSnapshot(),
+    readout: memoryReadout(),
+    abortedLabel: (() => { try { return document.documentElement.dataset.memGuardAbort || ''; } catch { return ''; } })(),
+  };
+}
+
+/** 供测试重置（仅测试用） */
+export function __resetMemoryGuardForTest() {
+  enabled = true;
+  readout = { availMb: null, totalMb: null, peakEstMb: null, budgetMb: null, at: 0, error: '' };
+  try { delete document.documentElement.dataset.memGuardAbort; } catch { /* 忽略 */ }
+}