cc-viewer 1.6.348 → 1.7.1

package/src/utils/promptDetect.js

@@ -0,0 +1,196 @@
+/**
+ * promptDetect —— PTY prompt 检测（ChatView._detectPrompt 的提取 + 线性化重写）。
+ *
+ * 为什么存在：旧实现的 Pattern 1/2 多行正则带嵌套量词
+ *   /([^\n]*\?)\s*\n((?:\s*[❯>]?\s*\d+\.\s+[^\n]+\n?){2,})(?:\n[^\d❯>\n][^\n]*|\n)*$/
+ * 中 `\s*` 可吃换行、`[^\n]+` 可吃空格、行内 `\d+\.`（版本号）提供多重切分点，
+ * 失配时回溯组合数按行数指数爆炸——实测 /plugins 菜单形态文本 4 行 84ms、
+ * 6 行 2.2s、8 行 >90s；_ptyBuffer 4KB ≈ 40~80 行 → 单次同步 match 永久占死
+ * 主线程（Windows /plugins 菜单整页卡死的根因）。
+ *
+ * detectPromptInBuffer 用「行式扫描」复刻旧正则语义，可证 O(n·行长)：
+ * 全程只对单行跑 `^...$` 锚定、无嵌套量词的正则。语义对齐要点（以
+ * test/prompt-detect.test.js 的等价回归 fixture 为准绳）：
+ *   - 按 /\r?\n/ 分行：Windows ConPTY 输出 CRLF，行尾 \r 必须在分行时吃掉
+ *     （单行正则的 `.`/`$` 都不容忍 \r，legacy 靠 [^\n] 容忍——此处对齐）；
+ *   - leftmost：与 JS regex 一致，自上而下取第一个结构成立的 question 行；
+ *   - Pattern 1 question 行须以 `?` 结尾（容尾随空白）；选项块=连续编号行，
+ *     块内/块前允许空行；块后所有行须为 trailing（空行或首字符 ∉ {数字,❯,>}）；
+ *   - Pattern 2 question 为任意非空行；选项块成员=两段空白结构
+ *     `\s+[❯>]?\s+内容` 的行（与旧块正则同构，单段空白如 " X" 不是成员）；
+ *     须 ≥2 项且含 ❯/> 选中项；trailing 定义不同（空行或首字符 ∉ {空白,❯,>}）；
+ *     与旧实现一致，结构首次匹配后验证失败即整体放弃（不向后重试）；
+ *   - 输出形状 {question, options:[{number,text,selected}]} 与旧实现逐字段一致。
+ *
+ * The original regex implementation (detectPromptLegacy) and its
+ * ccv_legacy_prompt_detect escape hatch were removed after the linear rewrite
+ * (first shipped in 1.6.308) proved stable in the field; its behavior is
+ * pinned by the golden-master corpus in test/prompt-detect.test.js.
+ *
+ * 纯 JS、无浏览器全局依赖（node:test 可直接 import）。
+ */
+import { now } from './monotime.js';
+
+// 与 ChatView._stripAnsi 同源（4 个正则均线性安全）。单一实现：ChatView 与
+// test/permission-detect.test.js 均从这里 import，消除多份拷贝漂移。
+export function stripAnsi(str) {
+  // Remove CSI sequences (ESC [ ... final byte), OSC sequences (ESC ] ... ST), and other escape sequences
+  return str
+    .replace(/\x1b\[[?0-9;]*[A-Za-z]/g, '')
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
+    .replace(/\x1b[^[\]](.|$)/g, '')
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');
+}
+
+// 跨 write 撕裂防护：把 data 切成 [可安全 strip 的前段, 尾部未终结的 CSI/OSC 半截]。
+// ANSI 序列被 PTY 分片切断时（"\x1b[3" | "6m…"）按单次 write strip 会让两半都剥不掉、
+// 残字污染 buffer 致漏检；调用方把 carry 缓带到下一片拼接后再 strip。
+// maxCarry 上限防畸形流（如 OSC 永不终结）让 carry 无限囤积——超限放弃缓带按原样剥。
+export function splitTrailingAnsiCarry(data, maxCarry = 512) {
+  const m = data.match(/\x1b(?:\[[?0-9;]*|\][^\x07\x1b]*)?$/);
+  if (m && m[0].length < maxCarry) return [data.slice(0, m.index), m[0]];
+  return [data, ''];
+}
+
+// false-positive 过滤（从 ChatView 平移，单行正则、线性）。返回 true = 应忽略。
+export function isFalsePositiveQuestion(question) {
+  // 形如文件/目录路径或状态栏输出
+  if (/^[■\s]*[~\/.:]/.test(question) && /\//.test(question)) return true;
+  // Claude Code 计时/状态输出（如 "*Crunchedfor2m18s"）
+  if (/^[*■✦⏎]/.test(question)) return true;
+  return false;
+}
+
+// ── 单行判定正则（均 ^...$ 锚定、无嵌套量词，单行长度有界 → 线性）──
+// Pattern 1 选项行：可缩进 + 可选 ❯/> 光标 + 编号 + ". " + 文本
+const P1_OPTION_RE = /^\s*([❯>])?\s*(\d+)\.\s+(.+)$/;
+// Pattern 2 块成员准入：与 legacy 块正则 \s+[❯>]?\s+[^\n]+ 同构——
+// ≥1 空白 + 可选光标 + ≥1 空白 + ≥1 字符。单段空白行（" X"）不是成员。
+const P2_MEMBER_RE = /^\s+[❯>]?\s+./;
+// Pattern 2 选项行解析（与旧 ChatView 的 per-line 解析一致）
+const P2_OPTION_PARSE_RE = /^\s*([❯>])?\s+(.+)$/;
+// trailing 合法性为「反向」判定：match = 首字符打断 trailing → 该 prompt 不成立。
+// Pattern 1 合法 trailing 行 = 空行或首字符 ∉ {数字,❯,>}
+const P1_TRAILING_BREAK_RE = /^[\d❯>]/;
+// Pattern 2 合法 trailing 行 = 空行或首字符 ∉ {空白,❯,>}
+const P2_TRAILING_BREAK_RE = /^[\s❯>]/;
+
+// overrun 监测阈值：超过仅告警 + 计数（无熔断、无降级——线性实现 4KB 封顶
+// 实践上不会触发，留作 Windows 实机回报的哨兵指标）
+const OVERRUN_MS = 50;
+
+// 诊断统计（termDiag 接线读取；>OVERRUN_MS 计 overrun）
+const _stats = { calls: 0, lastMs: 0, maxMs: 0, overruns: 0 };
+export function getPromptDetectStats() {
+  return { ..._stats };
+}
+
+function parseP1Option(line) {
+  const m = line.match(P1_OPTION_RE);
+  if (!m) return null;
+  return { number: parseInt(m[2], 10), text: m[3].trim(), selected: !!m[1] };
+}
+
+/**
+ * Pattern 1：编号选项 — "Question?\n  ❯ 1. Option A\n    2. Option B"
+ * 允许尾随空行与 hint 行（如 "\n\nEsc to cancel · Tab to amend"）。
+ */
+function detectPattern1(lines) {
+  for (let i = 0; i < lines.length - 1; i++) {
+    const q = lines[i].trimEnd();
+    if (!q.endsWith('?')) continue;
+    // 问句行下方：跳过空行后须紧跟编号选项块（块内允许夹空行）
+    const options = [];
+    let j = i + 1;
+    let lastOptionEnd = j; // 选项块后第一行（trailing 起点）
+    for (; j < lines.length; j++) {
+      const line = lines[j];
+      if (!line.trim()) continue;          // 空行：块前/块内均容忍
+      const opt = parseP1Option(line);
+      if (!opt) break;                     // 非选项非空行：块结束
+      options.push(opt);
+      lastOptionEnd = j + 1;
+    }
+    if (options.length < 2) continue;
+    // 块后全部行须为 trailing（空行或首字符 ∉ {数字,❯,>}），否则该问句不成立
+    let trailingOk = true;
+    for (let k = lastOptionEnd; k < lines.length; k++) {
+      if (P1_TRAILING_BREAK_RE.test(lines[k])) { trailingOk = false; break; }
+    }
+    if (!trailingOk) continue;
+    return { question: q.trim(), options };
+  }
+  return null;
+}
+
+/**
+ * Pattern 2：无编号光标选项（Ink Select）— "Some prompt text\n  ❯ Allow once\n    Deny"
+ * 问句行可不带 "?"；须 ≥2 项且含 ❯/> 选中项。与旧实现一致：结构首次匹配后
+ * 验证（项数/选中）失败即整体放弃，不向后重试。
+ */
+function detectPattern2(lines) {
+  for (let i = 0; i < lines.length - 1; i++) {
+    if (lines[i].length === 0) continue;   // question 须非空行（与旧 [^\n]+ 一致，纯空白行也算）
+    // 块成员：两段空白结构（P2_MEMBER_RE，与 legacy 块正则同构）；块内允许夹空行
+    const memberLines = [];
+    let j = i + 1;
+    let lastOptionEnd = j;
+    for (; j < lines.length; j++) {
+      const line = lines[j];
+      if (!line.trim()) continue;
+      if (!P2_MEMBER_RE.test(line)) break;
+      memberLines.push(line);
+      lastOptionEnd = j + 1;
+    }
+    if (memberLines.length < 2) continue;
+    let trailingOk = true;
+    for (let k = lastOptionEnd; k < lines.length; k++) {
+      if (P2_TRAILING_BREAK_RE.test(lines[k])) { trailingOk = false; break; }
+    }
+    if (!trailingOk) continue;
+    // 结构成立（leftmost）→ 解析验证；失败则与旧实现一致整体放弃
+    const parsed = [];
+    for (const line of memberLines) {
+      const m = line.match(P2_OPTION_PARSE_RE);
+      if (m && m[2].trim()) {
+        parsed.push({ number: parsed.length + 1, text: m[2].trim(), selected: !!m[1] });
+      }
+    }
+    if (parsed.length >= 2 && parsed.some(p => p.selected)) {
+      const question = lines[i].trim();
+      // 纯空白问句行：与旧实现等价——结构成立但 question 为空即整体放弃（不向后重试）
+      if (!question) return null;
+      return { question, options: parsed };
+    }
+    return null;
+  }
+  return null;
+}
+
+/**
+ * 检测 PTY buffer 尾部是否呈现交互式 prompt。
+ * @param {string} buf - ANSI-stripped PTY buffer（≤4KB）
+ * @returns {{question: string, options: Array<{number:number,text:string,selected:boolean}>} | null}
+ *   不含 false-positive 过滤（调用方按需用 isFalsePositiveQuestion，
+ *   ChatView 对「过滤」与「未检出」有不同的 dismiss 语义）。
+ */
+export function detectPromptInBuffer(buf) {
+  const t0 = now();
+  let result = null;
+  const trimmed = (buf || '').trimEnd();
+  if (trimmed) {
+    // /\r?\n/ 分行吃掉 CRLF 行尾的 \r（Windows ConPTY），否则单行正则的
+    // `.`/`$` 均不容忍 \r → 选项行整行失配 → 目标平台全量漏检
+    const lines = trimmed.split(/\r?\n/);
+    result = detectPattern1(lines) || detectPattern2(lines);
+  }
+  const ms = now() - t0;
+  _stats.calls++;
+  _stats.lastMs = ms;
+  if (ms > _stats.maxMs) _stats.maxMs = ms;
+  if (ms > OVERRUN_MS) {
+    _stats.overruns++;
+    try { console.warn(`[cc-viewer] promptDetect overrun: ${ms.toFixed(1)}ms (buf ${trimmed.length}B)`); } catch {}
+  }
+  return result;
+}

package/src/utils/promptNav.js

@@ -0,0 +1,60 @@
+import { getSlashCommandLabel } from './slashCommandLabels.js';
+
+// buildPromptNavItems：从「当前可见项」与权威的 mainAgentSessions 计算用户 Prompt 导航的数据项。
+// 纯函数（无 React/DOM），渲染留在 ChatView——便于单测覆盖会话边界标记、去重与无 ts 容错。
+//
+// @param {Array<{props?:{role?:string,text?:string,timestamp?:string|null}}>} visible 当前渲染项
+// @param {Array<{messages?:Array<{_timestamp?:string}>}>} mainAgentSessions 权威会话数组
+// @returns {Array<{display:string, visibleIdx:number, timestamp:string|null, sessionIdx:number|null, newSession?:boolean}>}
+export function buildPromptNavItems(visible, mainAgentSessions) {
+  if (!Array.isArray(visible) || visible.length === 0) return [];
+
+  // 会话分界：用权威的 mainAgentSessions 把每条 prompt 的 _timestamp 映射到所属 session 序号。
+  // 不依赖主视图的 <Divider>（其在角色过滤时会被滤掉），保证导航里始终能标出会话边界。
+  const sessions = mainAgentSessions || [];
+  const tsToSession = new Map();
+  for (let si = 0; si < sessions.length; si++) {
+    const msgs = sessions[si] && sessions[si].messages;
+    if (!Array.isArray(msgs)) continue;
+    for (const m of msgs) {
+      const ts = m && m._timestamp;
+      if (ts != null && !tsToSession.has(ts)) tsToSession.set(ts, si);
+    }
+  }
+
+  const prompts = [];
+  const seen = new Set();
+  for (let i = 0; i < visible.length; i++) {
+    const props = visible[i] && visible[i].props;
+    if (!props || props.role !== 'user') continue;
+    const raw = props.text || '';
+    if (!raw) continue;
+    // 清理图片标记，只保留文字部分用于导航列表显示
+    const cleaned = raw
+      .replace(/\[Image(?:\s*#\d+)?(?::?\s*source)?:\s*[^\]]+\]/gi, '')
+      .replace(/"\/tmp\/cc-viewer-uploads\/[^"]+"/g, '')
+      .trim();
+    if (!cleaned) continue;
+    // 内置 slash 命令(/theme /clear …)在 nav 列表里也显示本地化标签，与主气泡保持一致；
+    // 未命中白名单的命令/普通文本走原文。
+    const text = getSlashCommandLabel(cleaned) || cleaned;
+    const key = text.substring(0, 100);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const display = text.length > 80 ? text.substring(0, 80) + '...' : text;
+    // 使用 visible 索引作为定位标识（兼容无 timestamp 的遗留消息）
+    const sessionIdx = (props.timestamp != null && tsToSession.has(props.timestamp))
+      ? tsToSession.get(props.timestamp) : null;
+    prompts.push({ display, visibleIdx: i, timestamp: props.timestamp || null, sessionIdx });
+  }
+
+  // 标记跨 session 的 prompt（其前插入会话分隔线）。session 未知（无 ts）的 prompt 不打断链路。
+  let lastSessionIdx = null;
+  for (const p of prompts) {
+    if (p.sessionIdx == null) continue;
+    if (lastSessionIdx != null && p.sessionIdx !== lastSessionIdx) p.newSession = true;
+    lastSessionIdx = p.sessionIdx;
+  }
+
+  return prompts;
+}

package/src/utils/ptyChunkBuilder.js

@@ -0,0 +1,251 @@
+/**
+ * PTY Chunk Builder — pure functions for building keystroke sequences.
+ * Separates "what to send" from "how to send".
+ *
+ * Claude Code AskUserQuestion prompt model:
+ * - Single question: options list, Enter selects and submits
+ * - Multi question: tabbed form [Q1] [Q2] ... [Submit]
+ *   - Single select: ↓↓...Enter (selects and auto-advances to next tab)
+ *   - Multi select: ↓Space↓Space...→ (toggles then → to next tab)
+ *   - Last tab → to Submit, Enter to confirm
+ */
+
+const ARROW_DOWN = '\x1b[B';
+const ARROW_UP = '\x1b[A';
+const ARROW_RIGHT = '\x1b[C';
+const SPACE = ' ';
+const ENTER = '\r';
+
+/**
+ * Build navigation arrows from currentIdx to targetIdx.
+ */
+function buildArrows(currentIdx, targetIdx) {
+  const chunks = [];
+  const diff = targetIdx - currentIdx;
+  const arrow = diff > 0 ? ARROW_DOWN : ARROW_UP;
+  for (let i = 0; i < Math.abs(diff); i++) {
+    chunks.push(arrow);
+  }
+  return chunks;
+}
+
+/**
+ * Get current cursor position from prompt.
+ */
+function getCursorIdx(prompt) {
+  if (prompt && prompt.options) {
+    const idx = prompt.options.findIndex(o => o.selected);
+    return idx >= 0 ? idx : 0;
+  }
+  return 0;
+}
+
+/**
+ * Build chunks for a single-select answer.
+ * Navigate to target option, then Enter.
+ * @param {object} answer - { optionIndex, isLast }
+ * @param {object} prompt - ptyPrompt with options
+ * @param {boolean} isMultiQuestion - whether this is part of a multi-question form
+ */
+export function buildSingleSelectChunks(answer, prompt, isMultiQuestion = false) {
+  const chunks = [];
+  let currentIdx = getCursorIdx(prompt);
+
+  // For multi-question, map optionIndex to prompt option by number
+  let targetIdx = answer.optionIndex;
+  if (prompt && prompt.options) {
+    const targetNumber = answer.optionIndex + 1;
+    const found = prompt.options.findIndex(o => o.number === targetNumber);
+    if (found >= 0) targetIdx = found;
+  }
+
+  chunks.push(...buildArrows(currentIdx, targetIdx));
+  chunks.push(ENTER); // Select and confirm (auto-advances in multi-question)
+
+  // Multi-question last question: Enter above advances to Review page,
+  // need another Enter to confirm "Submit answers"
+  if (isMultiQuestion && answer.isLast) {
+    chunks.push(ENTER);
+  }
+  return chunks;
+}
+
+/**
+ * Build chunks for a multi-select answer.
+ * Navigate + Space for each selection, then → to advance tab.
+ * @param {object} answer - { selectedIndices, isLast }
+ * @param {object} prompt - ptyPrompt with options
+ * @param {boolean} isMultiQuestion - whether this is part of a multi-question form
+ */
+export function buildMultiSelectChunks(answer, prompt, isMultiQuestion = false) {
+  const chunks = [];
+  const indices = (answer.selectedIndices || []).slice().sort((a, b) => a - b);
+  let currentIdx = getCursorIdx(prompt);
+
+  for (const targetIdx of indices) {
+    chunks.push(...buildArrows(currentIdx, targetIdx));
+    chunks.push(SPACE); // Toggle
+    currentIdx = targetIdx;
+  }
+
+  // → to advance to next tab (or Submit tab if last)
+  chunks.push(ARROW_RIGHT);
+
+  // Last question in multi-question, or single question: Enter on Submit tab
+  if (answer.isLast || !isMultiQuestion) {
+    chunks.push(ENTER);
+  }
+
+  return chunks;
+}
+
+/**
+ * Build chunks for a single-select "Other" (free text) answer.
+ *
+ * Single-question mode:
+ *   Navigate to "Type something" → Enter (activate text input) → type text → Enter (confirm)
+ *
+ * Multi-question tabbed form:
+ *   In tabbed forms, Enter on "Type something" auto-advances to the next tab
+ *   (same as regular single-select). Text input is NOT inline — Claude Code
+ *   prompts for it separately after the form is submitted.
+ *   So we treat it like a regular single-select: navigate → Enter.
+ *
+ * @param {object} answer - { optionIndex, text, isLast }
+ * @param {object} prompt - ptyPrompt with options
+ * @param {boolean} isMultiQuestion - whether part of multi-question form
+ */
+export function buildOtherChunks(answer, prompt, isMultiQuestion = false) {
+  const chunks = [];
+  let currentIdx = getCursorIdx(prompt);
+  const targetIdx = answer.optionIndex;
+
+  chunks.push(...buildArrows(currentIdx, targetIdx));
+
+  // "Type something" 选项：直接输入文字，不需要 Enter 激活
+  // inquirer 在光标停在此选项时接受直接键入文字
+  const text = answer.text || '';
+  for (const ch of text) {
+    chunks.push(ch);
+  }
+  chunks.push(ENTER); // Confirm text and submit
+
+  // Multi-question last question: Enter above auto-advances to Submit tab,
+  // need another Enter to confirm
+  if (isMultiQuestion && answer.isLast) {
+    chunks.push(ENTER);
+  }
+  return chunks;
+}
+
+/**
+ * Build chunks for a multi-select "Other" (Type something) answer.
+ * "Type something" is a text-input option in the checkbox list.
+ * Sequence: navigate → type text + sacrifice_char → → (settle) → ↑ (exit, drops sacrifice_char) → → (next tab) → Enter (if last)
+ * inquirer drops the last char on ↓/↑ exit; sacrifice char absorbs the loss.
+ * Uses ↑ instead of ↓ to exit: "Type something" is the last option, so ↓ keeps cursor there
+ * and → may re-enter text mode. ↑ moves to a non-text option, making → reliably navigate tabs.
+ * @param {object} answer - { optionIndex, text, isLast }
+ * @param {object} prompt - ptyPrompt with options
+ * @param {boolean} isMultiQuestion - whether part of multi-question form
+ */
+export function buildMultiSelectOtherChunks(answer, prompt, isMultiQuestion = false) {
+  const chunks = [];
+  let currentIdx = getCursorIdx(prompt);
+  const targetIdx = answer.optionIndex;
+
+  chunks.push(...buildArrows(currentIdx, targetIdx));
+
+  // Type text directly into the "Type something" field
+  // Typing auto-checks the checkbox — no Space/Enter needed
+  const text = answer.text || '';
+  for (const ch of text) {
+    chunks.push(ch);
+  }
+
+  // Sacrifice char: ↑/↓ drops exactly one character when exiting text input mode.
+  // Append ONE duplicate of the last char so the exit key drops the sacrifice, not the real text.
+  if (text.length > 0) {
+    const chars = [...text]; // handle multi-byte (e.g. CJK) correctly
+    chunks.push(chars[chars.length - 1]); // sacrifice for ↑
+  }
+
+  // → in text input mode: no-op (cursor already at end), provides settleMs delay
+  chunks.push(ARROW_RIGHT);
+  // ↑ exits text input mode — drops one char (the sacrifice above), real text preserved.
+  // Use ↑ instead of ↓: "Type something" is typically the last option, so ↓ may leave
+  // cursor on the same item (no option below). ↑ moves to the previous *non-text* option,
+  // ensuring the subsequent → is interpreted as tab navigation, not text cursor movement.
+  chunks.push(ARROW_UP);
+  // → goes to next tab (Submit tab for last/single question, next question tab otherwise)
+  chunks.push(ARROW_RIGHT);
+
+  // Enter on Submit/Review page to confirm — only for last question or single-question form
+  if (answer.isLast || !isMultiQuestion) {
+    chunks.push(ENTER);
+  }
+
+  return chunks;
+}
+
+/**
+ * Build chunks for a single answer (dispatches by type).
+ * @param {object} answer - { type, optionIndex, selectedIndices, text, isLast, isMultiSelect }
+ * @param {object} prompt - ptyPrompt with options
+ * @param {boolean} isMultiQuestion - whether part of multi-question form
+ */
+export function buildChunksForAnswer(answer, prompt, isMultiQuestion = false) {
+  if (answer.type === 'multi') {
+    return buildMultiSelectChunks(answer, prompt, isMultiQuestion);
+  }
+  if (answer.type === 'other' && answer.isMultiSelect) {
+    return buildMultiSelectOtherChunks(answer, prompt, isMultiQuestion);
+  }
+  if (answer.type === 'other') {
+    return buildOtherChunks(answer, prompt, isMultiQuestion);
+  }
+  return buildSingleSelectChunks(answer, prompt, isMultiQuestion);
+}
+
+/**
+ * settleMs after a bracket-paste-end chunk. Ink TUI needs ~1 frame to settle
+ * paste→normal state; if \r arrives in the same PTY write it gets swallowed.
+ */
+export const BRACKET_PASTE_SUBMIT_SETTLE_MS = 250;
+
+/**
+ * 剥离粘贴文本里内嵌的 bracketed-paste end 序列 `\x1b[201~`。
+ *
+ * 防 paste-injection：xterm.js 6.0 的 bracketed paste 不 sanitize 粘贴内容（上游修复
+ * PR #5716 在 7.0），剪贴板里的 `\x1b[201~` 会提前闭合 paste 包裹，余下字节被当作真实
+ * 按键/控制序列注入。剥离后再包裹即可堵住（该序列正常文本中不会出现，剥离无副作用）。
+ * 同时剥 `\x1b[200~` 以防成对伪造。
+ *
+ * 循环剥离到稳定：单趟 /g replace 删掉中间一个完整序列后，左右残片会重新相邻拼成
+ * 新序列（如 `\x1b[20` + `\x1b[201~` + `1~` → 删中段后 `\x1b[20`+`1~` = `\x1b[201~`），
+ * 绕过单趟剥离。循环到不再变化才安全。
+ * 正则覆盖 7-bit `\x1b[`（ESC [）与 8-bit C1 CSI `\x9b` 两种 introducer。
+ * @param {string} text
+ * @returns {string}
+ */
+export function sanitizeBracketPasteText(text) {
+  if (typeof text !== 'string') return text;
+  const re = /(?:\x1b\[|\x9b)20[01]~/g;
+  let prev;
+  do {
+    prev = text;
+    text = text.replace(re, '');
+  } while (text !== prev);
+  return text;
+}
+
+/**
+ * Wrap content in bracket paste mode and append Enter as a separate chunk,
+ * so the consumer can space them with settleMs.
+ * @param {string} content - non-empty string to paste-and-submit
+ * @returns {string[]} [pasteBlock, '\r']; [] if content is falsy or non-string
+ */
+export function buildBracketPasteSubmitChunks(content) {
+  if (typeof content !== 'string' || content.length === 0) return [];
+  return [`\x1b[200~${sanitizeBracketPasteText(content)}\x1b[201~`, ENTER];
+}

package/src/utils/quickMenuHoverIntent.js

@@ -0,0 +1,35 @@
+// 级联子菜单 hover-intent（终端工具栏与对话输入栏的四芒星快捷菜单共用）：
+// 从下排行斜向上滑向其子菜单高处选项时，路径会扫过相邻行，立即切换会抢走展开态
+// 致子菜单中途消失。进入（已有展开行时）/离开都延迟 HOVER_INTENT_MS 提交，扫过的
+// 行来不及生效，路径上的误触发被后续 clearTimeout 撤销；无展开行时进入即时响应不付延迟。
+
+export const HOVER_INTENT_MS = 140;
+
+// getExpanded 必须现场读宿主最新值（class 读 this.state，hooks 读 latest-value ref）：
+// 延迟提交时展开行可能已被后续 enter/点击改写，闭包快照会误收别行的展开态。
+// skip：宿主整体不参与 hover 展开（如 iPad tap 的 synthetic mouseEnter 会与 click 切换互抵）；
+// holdOpen：延迟收起提交时刻判定是否保住展开（如 AgentTeam 启用请求进行中保住 loading 反馈）。
+export function createQuickMenuHoverIntent({ getExpanded, setExpanded, skip, holdOpen }) {
+  let timer = null;
+  return {
+    enter(key) {
+      if (skip?.()) return;
+      clearTimeout(timer);
+      const current = getExpanded();
+      if (current === key) return;
+      if (current === null) setExpanded(key);
+      else timer = setTimeout(() => setExpanded(key), HOVER_INTENT_MS);
+    },
+    leave(key) {
+      if (skip?.()) return;
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        if (holdOpen?.(key)) return;
+        if (getExpanded() === key) setExpanded(null);
+      }, HOVER_INTENT_MS);
+    },
+    cancel() {
+      clearTimeout(timer);
+    },
+  };
+}

package/src/utils/rateLimitParser.js

@@ -0,0 +1,119 @@
+// 解析 Anthropic 订阅(coding plan / OAuth)在响应头里下发的统一限流信息
+// （anthropic-ratelimit-unified-* 家族），归一化成前端血条旁「套餐用量」组件可直接用的结构。
+//
+// 纯函数、零依赖：仅做字符串 → 数值的安全转换，便于单元测试，也避免被
+// ESM 后缀缺失的传递依赖污染（参考 readResultPool 测试注释）。
+//
+// 数据来源：cc-viewer 拦截器已把响应头原样写进日志(interceptor.js)，前端的
+// request.response.headers 即可直接读到，无需任何服务端改动。
+//
+// 关键事实（基于真实日志校验）：
+//   - 所有取值都是字符串，例如 utilization="0.19"（0~1 的占比，不是 token 数）；
+//   - reset 是 unix epoch「秒」，需 ×1000 转毫秒；
+//   - key 集合并非固定（个别项目还多出 -fallback 等），解析必须容忍缺失/多余 key。
+
+const PREFIX = 'anthropic-ratelimit-unified-';
+
+// 安全转数值：非有限值（NaN/Infinity/null/空串）一律返回 null，避免污染显示。
+function toNum(v) {
+  if (v == null || v === '') return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+// 把 headers 的 key 统一成小写做大小写无关查找（fetch 一般已小写，这里再兜底一次）。
+function lowerKeyMap(headers) {
+  const map = {};
+  for (const k of Object.keys(headers)) map[k.toLowerCase()] = headers[k];
+  return map;
+}
+
+/**
+ * 解析单个窗口（如 '5h' / '7d'）。三项全缺则返回 null（该窗口不存在）。
+ * @returns {{id:string, utilization:number|null, status:string|null, resetAt:number|null}|null}
+ */
+function parseWindow(map, id) {
+  const utilization = toNum(map[`${PREFIX}${id}-utilization`]);
+  const resetSec = toNum(map[`${PREFIX}${id}-reset`]);
+  const status = map[`${PREFIX}${id}-status`] || null;
+  if (utilization == null && resetSec == null && !status) return null;
+  return {
+    id,
+    utilization,                                   // 0~1 占比
+    status,                                         // allowed / rejected / queued ...
+    resetAt: resetSec != null ? resetSec * 1000 : null, // epoch 秒 → 毫秒
+  };
+}
+
+/**
+ * 解析统一限流响应头。
+ * @param {Record<string,string>|null|undefined} headers - request.response.headers
+ * @returns {null | {
+ *   source: 'plan',
+ *   windows: Array<{id, utilization, status, resetAt}>,
+ *   overallStatus: string|null,
+ *   representativeClaim: string|null,
+ *   overage: { status: string|null, disabledReason: string|null },
+ *   fallbackPercentage: number|null,
+ * }}
+ * 无任何 unified header 时返回 null（调用方据此决定不渲染套餐用量）。
+ */
+export function parseRateLimitHeaders(headers) {
+  if (!headers || typeof headers !== 'object') return null;
+  const map = lowerKeyMap(headers);
+
+  // 没有任何 unified-* 头 → 不是订阅计划下发的限流信息，直接放弃。
+  const hasUnified = Object.keys(map).some((k) => k.startsWith(PREFIX));
+  if (!hasUnified) return null;
+
+  const windows = [parseWindow(map, '5h'), parseWindow(map, '7d')].filter(Boolean);
+  if (windows.length === 0) return null;
+
+  return {
+    source: 'plan',
+    windows,
+    overallStatus: map[`${PREFIX}status`] || null,
+    representativeClaim: map[`${PREFIX}representative-claim`] || null,
+    overage: {
+      status: map[`${PREFIX}overage-status`] || null,
+      disabledReason: map[`${PREFIX}overage-disabled-reason`] || null,
+    },
+    fallbackPercentage: toNum(map[`${PREFIX}fallback-percentage`]),
+  };
+}
+
+/**
+ * 从 requests 列表里取「最近一条带统一限流头」的响应，解析成套餐用量。
+ * 统一限流头是账号级、随每条 200 响应下发的，所以从后往前找第一条可解析的即可
+ * （不依赖 isMainAgent，保持本模块零依赖、可独立单测）。
+ * @param {Array} requests
+ * @returns {ReturnType<typeof parseRateLimitHeaders>}
+ */
+export function extractLatestPlanUsage(requests) {
+  if (!Array.isArray(requests)) return null;
+  for (let i = requests.length - 1; i >= 0; i--) {
+    const headers = requests[i] && requests[i].response && requests[i].response.headers;
+    if (!headers) continue;
+    const pu = parseRateLimitHeaders(headers);
+    if (pu) return pu;
+  }
+  return null;
+}
+
+/**
+ * 选出「当前绑定」的代表窗口，用于 pill 的主色与主进度。
+ * 规则：representative-claim='five_hour' → 5h；明显的周/天 → 7d；
+ *      无法识别时回落到使用率更高的窗口（更接近“离限额最近”的语义）。
+ */
+export function pickHeadlineWindow(planUsage) {
+  if (!planUsage || !Array.isArray(planUsage.windows) || planUsage.windows.length === 0) return null;
+  const claim = planUsage.representativeClaim;
+  let id = null;
+  if (claim === 'five_hour') id = '5h';
+  else if (claim && /(day|week|7d|seven)/i.test(claim)) id = '7d';
+  if (id) {
+    const hit = planUsage.windows.find((w) => w.id === id);
+    if (hit) return hit;
+  }
+  return planUsage.windows.reduce((a, b) => ((b.utilization || 0) > (a.utilization || 0) ? b : a));
+}