cx-viewer 1.0.3 → 1.0.4

package/src/utils/imageCompress.js

@@ -0,0 +1,83 @@
+// 浏览器端图片压缩 → base64 dataURL
+// 用于 MDXEditor 的 imageUploadHandler：粘贴/拖入图片时本地压缩后内联到 markdown，
+// 零后端依赖、保证 .md 文件可移植。
+
+const DEFAULT_MAX_EDGE = 2000;
+const DEFAULT_QUALITY = 0.85;
+// 输入硬上限：原图 > 10MB 时直接拒绝（即使压缩后能控制在 5MB 内，原图占内存也太大）。
+// 5MB 是后端 writeFileContent 的上限；原图按经验 base64 后 +33%，压缩后通常 100-300KB，
+// 给 30x 余量已足。
+const MAX_INPUT_BYTES = 10 * 1024 * 1024;
+// 这里的 KEEP 集合 = 「不走 canvas resize、保留原始数据 base64」的 MIME。
+//   - PNG / WEBP：透明区在 canvas 转 JPEG 时会变黑底，且压缩收益取决于内容；保留原图最稳。
+//   - GIF：canvas drawImage 只能取首帧，会丢失全部动画——必须直通。
+const PASSTHROUGH_TYPES = new Set(['image/png', 'image/gif', 'image/webp', 'image/svg+xml']);
+
+function readAsDataURL(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result);
+    reader.onerror = () => reject(new Error('FileReader failed'));
+    reader.readAsDataURL(file);
+  });
+}
+
+function loadImage(src) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(new Error('Image decode failed'));
+    img.src = src;
+  });
+}
+
+export async function compressImageToDataURL(file, opts = {}) {
+  if (!(file instanceof Blob)) {
+    throw new Error('compressImageToDataURL: input must be a File or Blob');
+  }
+  if (!file.type || !file.type.startsWith('image/')) {
+    throw new Error(`Unsupported file type: ${file.type || 'unknown'}`);
+  }
+  if (file.size > MAX_INPUT_BYTES) {
+    throw new Error(`Image too large: ${(file.size / 1024 / 1024).toFixed(1)}MB > ${MAX_INPUT_BYTES / 1024 / 1024}MB limit`);
+  }
+
+  const maxEdge = opts.maxEdge ?? DEFAULT_MAX_EDGE;
+  const quality = opts.quality ?? DEFAULT_QUALITY;
+
+  // PNG / GIF / WEBP / SVG 直通 base64（GIF 保留动画，PNG/WEBP 保留透明，SVG 保留矢量）
+  if (PASSTHROUGH_TYPES.has(file.type)) {
+    return await readAsDataURL(file);
+  }
+
+  const originalDataURL = await readAsDataURL(file);
+  const img = await loadImage(originalDataURL);
+
+  const longestEdge = Math.max(img.naturalWidth, img.naturalHeight);
+  const scale = longestEdge > maxEdge ? maxEdge / longestEdge : 1;
+  const targetW = Math.max(1, Math.round(img.naturalWidth * scale));
+  const targetH = Math.max(1, Math.round(img.naturalHeight * scale));
+
+  const canvas = document.createElement('canvas');
+  canvas.width = targetW;
+  canvas.height = targetH;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    return originalDataURL;
+  }
+  ctx.drawImage(img, 0, 0, targetW, targetH);
+
+  // JPEG 透明区会变黑——在 PASSTHROUGH 已涵盖 PNG/WEBP/GIF 的前提下，能进到这里的
+  // 都是 image/jpeg / image/bmp / image/heic 等非透明类型，统一压成 JPEG。
+  let compressed;
+  try {
+    compressed = canvas.toDataURL('image/jpeg', quality);
+  } catch {
+    return originalDataURL;
+  }
+
+  if (!compressed || compressed === 'data:,' || compressed.length >= originalDataURL.length) {
+    return originalDataURL;
+  }
+  return compressed;
+}

package/src/utils/imageDownscale.js

@@ -0,0 +1,28 @@
+// Retina 屏幕截图为 2x 分辨率，上传前按 devicePixelRatio 缩小到 1x，减少文件体积。
+// 非 Retina 屏幕、Canvas 不可用、或 img.onerror 时，静默返回原始文件（graceful fallback）。
+export function downscaleForRetina(file) {
+  const dpr = window.devicePixelRatio || 1;
+  if (dpr <= 1) return Promise.resolve(file);
+
+  return new Promise((resolve) => {
+    const img = new Image();
+    const url = URL.createObjectURL(file);
+    img.onload = () => {
+      URL.revokeObjectURL(url);
+      const w = Math.round(img.width / dpr);
+      const h = Math.round(img.height / dpr);
+      const canvas = document.createElement('canvas');
+      canvas.width = w;
+      canvas.height = h;
+      const ctx = canvas.getContext('2d');
+      if (!ctx) { resolve(file); return; }
+      ctx.drawImage(img, 0, 0, w, h);
+      canvas.toBlob((blob) => {
+        if (!blob) { resolve(file); return; }
+        resolve(new File([blob], file.name || 'clipboard.png', { type: file.type }));
+      }, file.type);
+    };
+    img.onerror = () => { URL.revokeObjectURL(url); resolve(file); };
+    img.src = url;
+  });
+}

package/src/utils/imageResize.js

@@ -0,0 +1,112 @@
+// 图片上传前尺寸压缩：任意一边超过 maxDim 时，按比例缩放至 maxDim 以内。
+// 非图片 / 解码失败时原样返回；HEIC/AVIF/GIF/BMP 等只要浏览器能解码就会处理。
+
+// 输出格式：原 PNG/WebP 保留以避免不必要的有损再编码，其余一律转 JPEG。
+const KEEP_FORMAT = new Set(['image/png', 'image/webp']);
+
+export function pickOutputType(inputType) {
+  return KEEP_FORMAT.has(inputType) ? inputType : 'image/jpeg';
+}
+
+function loadImageBitmap(file) {
+  if (typeof createImageBitmap === 'function') {
+    return createImageBitmap(file).catch(() => loadViaImgElement(file));
+  }
+  return loadViaImgElement(file);
+}
+
+function loadViaImgElement(file) {
+  return new Promise((resolve, reject) => {
+    const url = URL.createObjectURL(file);
+    const img = new Image();
+    img.onload = () => { URL.revokeObjectURL(url); resolve(img); };
+    img.onerror = (e) => { URL.revokeObjectURL(url); reject(e); };
+    img.src = url;
+  });
+}
+
+function canvasToBlob(canvas, type, quality) {
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => (blob ? resolve(blob) : reject(new Error('toBlob returned null'))),
+      type,
+      quality,
+    );
+  });
+}
+
+export async function resizeImageIfNeeded(file, maxDim = 2000) {
+  if (!file || typeof file !== 'object') return file;
+  const type = (file.type || '').toLowerCase();
+  if (!type.startsWith('image/')) return file;
+  // GIF 走 canvas 会只保留第一帧 + 转 JPEG，动图彻底丢。
+  // 直接放行原文件（Codex API 对 GIF 有自己的降采样，即便 >2000px 也由后端处理）。
+  if (type === 'image/gif') return file;
+
+  let source;
+  try {
+    source = await loadImageBitmap(file);
+  } catch {
+    return file;
+  }
+
+  const srcW = source.width || source.naturalWidth;
+  const srcH = source.height || source.naturalHeight;
+  if (!srcW || !srcH) {
+    try { source.close?.(); } catch {}
+    return file;
+  }
+
+  const maxSide = Math.max(srcW, srcH);
+  if (maxSide <= maxDim) {
+    try { source.close?.(); } catch {}
+    return file;
+  }
+
+  const scale = maxDim / maxSide;
+  const dstW = Math.max(1, Math.round(srcW * scale));
+  const dstH = Math.max(1, Math.round(srcH * scale));
+
+  const canvas = document.createElement('canvas');
+  canvas.width = dstW;
+  canvas.height = dstH;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    try { source.close?.(); } catch {}
+    return file;
+  }
+  ctx.imageSmoothingEnabled = true;
+  ctx.imageSmoothingQuality = 'high';
+  try {
+    ctx.drawImage(source, 0, 0, dstW, dstH);
+  } catch {
+    try { source.close?.(); } catch {}
+    return file;
+  }
+  try { source.close?.(); } catch {}
+
+  const outType = pickOutputType(type);
+  const quality = outType === 'image/png' ? undefined : 0.92;
+
+  let blob;
+  try {
+    blob = await canvasToBlob(canvas, outType, quality);
+  } catch {
+    return file;
+  }
+
+  // 走到这里说明 maxSide > maxDim，必须返回缩放版本以满足 API 尺寸限制
+  // （即使重编码后字节反而更大 —— 如低色 PNG 转 JPEG —— 也不能回退原图）
+  const nameOut = renameForType(file.name || 'image', outType);
+  return new File([blob], nameOut, { type: outType, lastModified: Date.now() });
+}
+
+export function renameForType(originalName, outType) {
+  const ext = outType === 'image/jpeg' ? 'jpg'
+    : outType === 'image/png' ? 'png'
+    : outType === 'image/webp' ? 'webp'
+    : 'img';
+  const dot = originalName.lastIndexOf('.');
+  const stem = dot > 0 ? originalName.slice(0, dot) : originalName;
+  return `${stem}.${ext}`;
+}

package/src/utils/ingestPipeline.js

@@ -0,0 +1,47 @@
+// 冷启动摄取分帧管线基础设施 — 把 load_end 的同步 O(n×m) 处理切成批次,批间让出主线程。
+// 背景:`cxv -c` 大会话的全量 checkpoint(单条数十 MB、数千 messages)让 reconstruct/slim/
+// process 在一个任务里跑数十秒,Windows 上页面全面卡死。分帧不改变任何一步的执行顺序与
+// 语义(同一循环插入 await 让步),只把长任务拆成 <16ms 批次。
+// 纯函数 + 依赖注入,React-free,node:test 可直测。
+
+export const INGEST_BATCH_SIZE = 250;
+
+/**
+ * 让出主线程。优先 scheduler.yield()(Chrome/Edge 129+/Electron:带优先级续行,
+ * 不会排在无关任务之后);回退 setTimeout(0)(通用;await 链非嵌套,4ms clamp 不生效)。
+ * 不用 requestIdleCallback(交互期可被无限饿死,must-complete 管线会卡住)、
+ * 不用 rAF(后台标签页完全暂停 —— Windows 用户加载期 alt-tab 是常态)。
+ */
+export const yieldToMain = (typeof scheduler !== 'undefined' && typeof scheduler.yield === 'function')
+  ? () => scheduler.yield()
+  : () => new Promise(resolve => setTimeout(resolve, 0));
+
+/**
+ * 分帧驱动一个严格有序的 per-index pass:对 i=0..total-1 顺序调用 step(i),
+ * 每 batchSize 个让步一次,让步后检查 shouldAbort。
+ *
+ * 调用序列与同步 for 循环完全一致 —— 仅插入 await,不重排、不切片、不并行,
+ * 保证有状态消费者(createEntrySlimmer / mergeMainAgentSessions 链)语义零变化。
+ *
+ * @param {number} total
+ * @param {(i: number) => void} step
+ * @param {object} [ctl]
+ * @param {() => boolean} [ctl.shouldAbort] - 每次让步后检查;true 则立即终止(不补跑剩余 step)
+ * @param {(done: number) => void} [ctl.onProgress] - 每批让步前 + 结束时回报已处理条数(单调递增)
+ * @param {() => Promise<void>} [ctl.yieldFn] - 让步原语(测试可注入)
+ * @param {number} [ctl.batchSize]
+ * @returns {Promise<{aborted: boolean}>}
+ */
+export async function runChunkedPass(total, step, ctl = {}) {
+  const { shouldAbort, onProgress, yieldFn = yieldToMain, batchSize = INGEST_BATCH_SIZE } = ctl;
+  for (let i = 0; i < total; i++) {
+    step(i);
+    if ((i + 1) % batchSize === 0 && i + 1 < total) {
+      if (onProgress) onProgress(i + 1);
+      await yieldFn();
+      if (shouldAbort && shouldAbort()) return { aborted: true };
+    }
+  }
+  if (onProgress && total > 0) onProgress(total);
+  return { aborted: false };
+}

package/src/utils/lazyWithReload.js

@@ -0,0 +1,53 @@
+// 共享：动态 chunk 加载失败时的自愈逻辑。
+//
+// 触发场景：服务端升级后，dist/ 里 chunk 哈希变了；浏览器旧标签页 / 缓存的入口 JS
+// 还在请求被替换的旧文件名 → server.js 给 /assets/ 不存在的请求返回 404 →
+// import() 抛 TypeError "Failed to fetch dynamically imported module"。
+//
+// 自愈策略：每个 chunk name 单独维护一个 sessionStorage timestamp，5 分钟外允许
+// reload 一次；窗口内的二次失败抛出原 error 让上游处理（避免连续两次升级死循环）。
+// sessionStorage 在 Safari Private / quota 满 / sandboxed iframe / 严格 CSP 下访问会抛
+// SecurityError 或 QuotaExceededError，全部用 try/catch 静默吞掉 —— 拿不到上次时间戳
+// 时优先 reload（次数过多比"永不刷"更可恢复）。
+//
+// 三个导出：
+//   - shouldReloadStaleChunk(name) → boolean。仅判断 + 写时间戳，不做 reload。
+//     用作底层 primitive，便于把"是否要刷"和"何时真刷"解耦。
+//   - reloadOnStaleChunk(name) → boolean。立即 reload。给 main.jsx 这种没 UI 的地方用。
+//   - handleStaleChunk(name, err, { onReload }) → Promise / throw。给 React.lazy 的 .catch
+//     用：onReload 先跑（toast 之类），200ms 后才真 reload，让 UI 有机会画出来。
+//     返回永不 resolve 的 Promise 把 React 卡在 Suspense fallback 里等 reload 接管。
+
+const RELOAD_WINDOW_MS = 5 * 60 * 1000;
+const RELOAD_GRACE_MS = 200; // 留给 toast / message 渲染一帧的时间
+
+function safeStorage(key, value) {
+  try {
+    if (value === undefined) return Number(sessionStorage.getItem(key) || 0);
+    sessionStorage.setItem(key, value);
+  } catch {
+    /* private mode / quota / sandbox — 读返回 0（→ 触发一次 reload，比卡死好），写忽略 */
+  }
+  return 0;
+}
+
+export function shouldReloadStaleChunk(name) {
+  const key = `_chunkReloadedAt:${name}`;
+  const last = safeStorage(key);
+  if (Date.now() - last <= RELOAD_WINDOW_MS) return false;
+  safeStorage(key, String(Date.now()));
+  return true;
+}
+
+export function reloadOnStaleChunk(name) {
+  if (!shouldReloadStaleChunk(name)) return false;
+  window.location.reload();
+  return true;
+}
+
+export function handleStaleChunk(name, err, { onReload } = {}) {
+  if (!shouldReloadStaleChunk(name)) throw err;
+  try { onReload?.(); } catch { /* toast 抛错不能阻止 reload */ }
+  setTimeout(() => window.location.reload(), RELOAD_GRACE_MS);
+  return new Promise(() => {}); // 让 Suspense fallback 一直显示直到 reload 接管
+}

package/src/utils/markdown.js

@@ -0,0 +1,30 @@
+import { marked } from 'marked';
+import DOMPurify from 'dompurify';
+import { escapeHtml } from './helpers';
+import { setupMermaidAutoRender } from '../hooks/useMermaidRender';
+import { measureParse } from './markdownProfiler';
+
+setupMermaidAutoRender();
+
+const _mdCache = new Map();
+const _MD_CACHE_MAX = 1024;
+
+export function renderMarkdown(text) {
+  if (!text) return '';
+  const hit = _mdCache.get(text);
+  if (hit !== undefined) return hit;
+
+  let html;
+  try {
+    html = measureParse(() => DOMPurify.sanitize(marked.parse(text, { breaks: true })));
+  } catch (e) {
+    html = escapeHtml(text);
+  }
+
+  if (_mdCache.size >= _MD_CACHE_MAX) {
+    // evict oldest (Map preserves insertion order)
+    _mdCache.delete(_mdCache.keys().next().value);
+  }
+  _mdCache.set(text, html);
+  return html;
+}

package/src/utils/markdownIncremental.js

@@ -0,0 +1,39 @@
+import { renderMarkdown } from './markdown';
+
+// 在"不在未闭合 fence 里"的最后一处 \n\n 切开：前半段是已稳定的完成块，
+// 后半段是正在增长的尾巴。流式渲染时只有 tail 每个 chunk 重新解析，
+// frozen 段走 renderMarkdown 的 _mdCache（几乎必中），解析时间下降 30-50%。
+export function splitFrozenTail(text) {
+  if (!text) return ['', ''];
+
+  // 仍在未闭合 fence 内 —— 不能切，否则会把 ``` 切散
+  const fenceCount = (text.match(/^```/gm) || []).length;
+  if (fenceCount % 2 === 1) return ['', text];
+
+  // 存在引用式链接定义时保守回退 —— `[x]: url` 和 `[text][x]` 可能跨越分界
+  // 点，一旦定义落到 frozen 而使用落到 tail（或反过来），链接就不解析。
+  // LLM 回答里较少见，回退到全量解析是可接受的成本。
+  if (/^\[[^\]]+\]:\s/m.test(text)) return ['', text];
+
+  const idx = text.lastIndexOf('\n\n');
+  if (idx < 0) return ['', text];
+
+  // 分界点紧邻表格行（| 开头）时不切 —— 表头 + 分隔行和数据行要在同一次解析
+  // 里才能识别成 <table>，切开会渲染成两段残缺片段。
+  const prevLineStart = text.lastIndexOf('\n', idx - 1) + 1;
+  const lineBefore = text.slice(prevLineStart, idx);
+  const nextLineEnd = text.indexOf('\n', idx + 2);
+  const lineAfter = text.slice(idx + 2, nextLineEnd < 0 ? text.length : nextLineEnd);
+  if (lineBefore.trimStart().startsWith('|') || lineAfter.trimStart().startsWith('|')) {
+    return ['', text];
+  }
+
+  return [text.slice(0, idx + 2), text.slice(idx + 2)];
+}
+
+// 仅用于 trailingCursor=true（流式中）的渲染路径；
+// 非流式或完成消息仍走 renderMarkdown 的单次全量解析 + 缓存。
+export function renderIncremental(text) {
+  const [frozen, tail] = splitFrozenTail(text);
+  return renderMarkdown(frozen) + (tail ? renderMarkdown(tail) : '');
+}

package/src/utils/markdownProfiler.js

@@ -0,0 +1,113 @@
+/**
+ * Dev-only instrumentation for the Markdown render pipeline.
+ *
+ * Gated on `import.meta.env.DEV` — production builds compile every export to a
+ * no-op and tree-shake the module state away, so runtime cost in prod is zero.
+ *
+ * API:
+ *   measureParse(fn)        — wrap a sync parse call; records duration as a
+ *                             parse sample and emits an `md-parse` measure.
+ *   recordMountSample(ms)   — append a mount-cycle duration (typically the
+ *                             delta between render-return and the next effect)
+ *                             and emit an `md-mount` measure.
+ *
+ * Inspection:
+ *   window.__mdStats.summary()  → { parseP50, parseP95, mountP50, mountP95, ... }
+ *   window.__mdStats.reset()
+ *   window.__mdStats.samples    → raw { parse: [], mount: [] }
+ *
+ * DevTools Performance timeline shows `md-parse` / `md-mount` measures under
+ * the User Timing track. A recorded slice of a streaming session can then be
+ * inspected to attribute time between parse, reconcile, layout, and paint.
+ *
+ * The module auto-prunes performance.measure entries once per 500 samples so
+ * long-running dev sessions do not accumulate unbounded DevTools entries.
+ */
+
+const DEV = typeof import.meta !== 'undefined'
+  && import.meta.env
+  && import.meta.env.DEV === true;
+
+const MAX_SAMPLES = 2000;
+const CLEAR_MARKS_EVERY = 500;
+
+export function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.floor(sorted.length * p));
+  return sorted[idx];
+}
+
+export function createStats() {
+  const parse = [];
+  const mount = [];
+  let writeCount = 0;
+
+  function pushBounded(arr, v) {
+    arr.push(v);
+    if (arr.length > MAX_SAMPLES) arr.splice(0, arr.length - MAX_SAMPLES);
+  }
+
+  function maybeClearMarks() {
+    writeCount += 1;
+    if (writeCount % CLEAR_MARKS_EVERY === 0
+        && typeof performance !== 'undefined'
+        && typeof performance.clearMeasures === 'function') {
+      try {
+        performance.clearMeasures('md-parse');
+        performance.clearMeasures('md-mount');
+      } catch { /* ignore */ }
+    }
+  }
+
+  return {
+    samples: { parse, mount },
+    recordParse(ms) { pushBounded(parse, ms); maybeClearMarks(); },
+    recordMount(ms) { pushBounded(mount, ms); maybeClearMarks(); },
+    summary() {
+      const p = [...parse].sort((a, b) => a - b);
+      const m = [...mount].sort((a, b) => a - b);
+      return {
+        parseN: parse.length,
+        parseP50: +percentile(p, 0.5).toFixed(2),
+        parseP95: +percentile(p, 0.95).toFixed(2),
+        parseMax: +(p[p.length - 1] || 0).toFixed(2),
+        mountN: mount.length,
+        mountP50: +percentile(m, 0.5).toFixed(2),
+        mountP95: +percentile(m, 0.95).toFixed(2),
+        mountMax: +(m[m.length - 1] || 0).toFixed(2),
+      };
+    },
+    reset() {
+      parse.length = 0;
+      mount.length = 0;
+      writeCount = 0;
+    },
+  };
+}
+
+const stats = DEV ? createStats() : null;
+
+if (DEV && typeof window !== 'undefined') {
+  window.__mdStats = stats;
+}
+
+export function measureParse(fn) {
+  if (!DEV) return fn();
+  const start = performance.now();
+  const result = fn();
+  const ms = performance.now() - start;
+  stats.recordParse(ms);
+  try { performance.measure('md-parse', { start, end: start + ms }); } catch { /* ignore */ }
+  return result;
+}
+
+export function recordMountSample(ms) {
+  if (!DEV || !Number.isFinite(ms) || ms < 0) return;
+  stats.recordMount(ms);
+  try {
+    const start = performance.now() - ms;
+    performance.measure('md-mount', { start, end: start + ms });
+  } catch { /* ignore */ }
+}
+
+export const DEV_PROFILER_ENABLED = DEV;

package/src/utils/mdExtensionDetect.js

@@ -0,0 +1,64 @@
+// 检测 markdown 内容是否含 MDXEditor 默认不支持的扩展语法
+// 命中任意一项时，打开 .md 文件应自动 fallback 到旧 marked 渲染（保留语义完整性），
+// 避免 MDXEditor 解析时丢失或损坏这些扩展块。
+
+const RE_MERMAID_FENCE = /^[ \t]*```\s*mermaid\b/m;
+const RE_MATH_FENCE = /^[ \t]*```\s*(?:math|latex|tex|katex)\b/im;
+const RE_BLOCK_MATH = /\$\$[\s\S]+?\$\$/;
+const RE_DIRECTIVE = /^[ \t]*:::[A-Za-z][\w-]*\b/m;
+
+// 行内数学 $...$ 容易和货币符号 / 转义符 / 代码块里的 $ 撞，规则:
+//   - 必须在同一行内成对
+//   - $ 前后不能是数字（排除 $5、3$）
+//   - 至少包含一个数学常见字符（字母、运算符、括号）
+//   - 整体不少于 3 字符
+//   - 排除位于代码块（```）内的情况由调用方先剥除三连引号块（这里做粗略过滤）
+// 注：lookbehind `(?<!...)` 在老 Safari (<16.4) 抛 SyntaxError；construct 用 try/catch 包裹，
+// 失败时 RE_INLINE_MATH = null，相当于跳过行内数学检测（保守 fallback）。
+let RE_INLINE_MATH = null;
+try {
+  RE_INLINE_MATH = new RegExp("(?<![\\d$\\\\])\\$([^\\s$][^$\\n]{0,200}?[^\\s$\\\\])\\$(?![\\d])");
+} catch {
+  RE_INLINE_MATH = null;
+}
+
+function stripFences(md) {
+  // 粗略剥掉 ``` 围栏代码块，避免行内数学误判命中代码示例里的 $...$
+  return md.replace(/```[\s\S]*?```/g, '');
+}
+
+export function detectMdExtensions(markdown) {
+  const result = {
+    hasMermaid: false,
+    hasKatex: false,
+    hasDirective: false,
+    anyExtension: false,
+  };
+  if (typeof markdown !== 'string' || markdown.length === 0) {
+    return result;
+  }
+  // 整体 try/catch 兜底：极端情况（畸形 markdown / 某些环境的 regex 异常）下不应让组件崩白屏。
+  try {
+    if (RE_MERMAID_FENCE.test(markdown)) result.hasMermaid = true;
+    if (RE_MATH_FENCE.test(markdown) || RE_BLOCK_MATH.test(markdown)) {
+      result.hasKatex = true;
+    }
+    if (RE_DIRECTIVE.test(markdown)) result.hasDirective = true;
+
+    if (!result.hasKatex && RE_INLINE_MATH) {
+      const stripped = stripFences(markdown);
+      if (RE_INLINE_MATH.test(stripped)) {
+        const inlineMatch = stripped.match(RE_INLINE_MATH);
+        if (inlineMatch && /[a-zA-Z\\^_=<>+\-*/(){}[\]]/.test(inlineMatch[1])) {
+          result.hasKatex = true;
+        }
+      }
+    }
+  } catch {
+    // 检测失败时返回保守 false（即把内容当成纯标准 markdown 让 MDXEditor 处理），
+    // 避免阻塞用户。如果真有扩展语法，MDXEditor 自身的 onError 会兜底。
+  }
+
+  result.anyExtension = result.hasMermaid || result.hasKatex || result.hasDirective;
+  return result;
+}

package/src/utils/memoryLinkParser.js

@@ -0,0 +1,44 @@
+// 持久记忆 markdown 内 <a> 链接拦截：白名单设计——只放行 #anchor 和单段 .md basename。
+// CachePopoverContent.jsx + MemoryDetailModal.jsx 共用，避免双份 paste 漂移。
+//
+// 返回 discriminated union（而非简单 string | null）的理由：
+//   调用方需要区分三种动作——打开 detail / 透传给浏览器（锚点滚动）/ 阻止默认行为。
+//   { open: name } / { allow: true } / { reject: true } 让调用方一目了然，
+//   编译期就能 catch 漏分支（不像 string | null 容易把 reject 误当 allow）。
+//
+// 拒绝规则（白名单优先）：
+//   - 任意 scheme（http://, javascript:, chrome-extension:, custom-app:, x-anything: 等）一律拒绝。
+//     持久记忆面板内不导航外站；上游受信任 markdown 也禁止 deep-link 至浏览器协议处理器。
+//   - 绝对路径 / 路径分隔符 / `..` 段 / 隐藏文件（以 . 开头）
+//   - 非 .md 后缀
+const ANCHOR_PREFIX = '#';
+
+export function parseMemoryLink(hrefRaw) {
+  if (!hrefRaw) return { reject: true };
+
+  const trimmed = hrefRaw.trim();
+  if (!trimmed) return { reject: true };
+
+  // 锚点链接（#section）放过，让浏览器原地滚动
+  if (trimmed.startsWith(ANCHOR_PREFIX)) return { allow: true };
+
+  // 任何 scheme 标记（首段 [a-z][a-z0-9+.-]*: 模式）一律拒绝。
+  // 大小写不敏感（toLowerCase 规范化防 `JaVaScRiPt:` 之类绕过）。
+  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return { reject: true };
+
+  // 去掉 query/hash + URL 解码 → 候选 basename
+  let candidate;
+  try {
+    candidate = decodeURIComponent(trimmed.split('#')[0].split('?')[0]);
+  } catch {
+    return { reject: true };
+  }
+
+  if (!candidate) return { reject: true };
+  if (candidate.startsWith('/') || candidate.startsWith('\\')) return { reject: true };
+  if (candidate.includes('/') || candidate.includes('\\')) return { reject: true };
+  if (candidate === '..' || candidate.startsWith('.')) return { reject: true };
+  if (!/\.md$/i.test(candidate)) return { reject: true };
+
+  return { open: candidate };
+}

package/src/utils/modalMask.js

@@ -0,0 +1,15 @@
+// Blurred-overlay mask for the six hamburger-menu feature modals (Log
+// Management, Export user prompts, Plugin Management, CXV Process Manager,
+// Messaging Integration, Hot-Switch Proxy).
+//
+// Values mirror the request_user_input / plan approval overlay (`.backdrop` in
+// src/components/approval/ApprovalModal.module.css) — KEEP IN SYNC, guarded by
+// test/modal-mask.test.js. Applied per Modal instance via the antd semantic
+// `styles={{ mask }}` API: inline style, so it cannot leak to other modals —
+// a global `.ant-modal-mask` rule would hit every Modal and Modal.confirm in
+// the app, which is explicitly out of scope.
+export const BLUR_MASK_STYLE = Object.freeze({
+  background: 'rgba(0, 0, 0, 0.45)',
+  backdropFilter: 'blur(2px)',
+  WebkitBackdropFilter: 'blur(2px)',
+});

package/src/utils/monotime.js

@@ -0,0 +1,6 @@
+/**
+ * 单调毫秒时钟：performance.now 优先（单调、亚毫秒），无则回退 Date.now
+ * （node:test / 老环境）。promptDetect 与 terminalWriteQueue 共用，
+ * 单一实现避免拷贝漂移。
+ */
+export const now = () => (globalThis.performance?.now ? globalThis.performance.now() : Date.now());