cx-viewer 1.0.3 → 1.0.4

package/src/utils/ultraplanExperts.js

@@ -0,0 +1,86 @@
+// UltraPlan「专家」列表的纯逻辑：把内置专家(codeExpert / researchExpert)与用户自定义专家
+// (customUltraplanExperts)合成一份「有序 + 可显隐」的统一列表，供 PC popover、移动端弹窗、
+// 以及「管理专家」弹窗共用同一份真源。无 React / antd / i18n 依赖，可直接在 node:test 下 import。
+//
+// 变体键(key)约定(与发送侧 TerminalPanel 的解析一致，保持稳定)：
+//   · 内置：'codeExpert' / 'researchExpert'
+//   · 自定义：'custom:' + item.id
+//
+// 持久化(preferences.json)：
+//   · ultraplanExpertOrder: string[]  —— 全量有序键;缺省=自然序。
+//   · ultraplanExpertHidden: string[] —— 被隐藏的键;缺省=全部可见。
+// 二者都按「当前 customExperts」重算：指向已删除自定义专家的陈旧键一律忽略，绝不抛错。
+
+// 内置专家键，固定排在自然序最前。
+export const BUILTIN_EXPERT_KEYS = ['codeExpert', 'researchExpert'];
+
+function safeCustomList(customExperts) {
+  return Array.isArray(customExperts) ? customExperts.filter(e => e && e.id != null) : [];
+}
+
+// 自然序：内置在前，自定义按其数组顺序在后。
+export function naturalExpertKeys(customExperts) {
+  return [
+    ...BUILTIN_EXPERT_KEYS,
+    ...safeCustomList(customExperts).map(e => 'custom:' + e.id),
+  ];
+}
+
+// 有效有序键：先取 order 中「仍存在」的键(去重)，再把剩余自然序键追加到末尾。
+// → 新建/未知键自动落到末尾;order 里的陈旧键被过滤。
+export function orderedExpertKeys(customExperts, order) {
+  const natural = naturalExpertKeys(customExperts);
+  const naturalSet = new Set(natural);
+  const seen = new Set();
+  const known = [];
+  for (const k of Array.isArray(order) ? order : []) {
+    if (naturalSet.has(k) && !seen.has(k)) { seen.add(k); known.push(k); }
+  }
+  for (const k of natural) {
+    if (!seen.has(k)) { seen.add(k); known.push(k); }
+  }
+  return known;
+}
+
+// 有序描述符列表，供渲染：{ key, kind:'builtin'|'custom', item|null, hidden:boolean }。
+export function buildExpertList(customExperts, order, hidden) {
+  const hiddenSet = new Set(Array.isArray(hidden) ? hidden : []);
+  const byKey = new Map(safeCustomList(customExperts).map(e => ['custom:' + e.id, e]));
+  return orderedExpertKeys(customExperts, order).map(key => {
+    const kind = key.startsWith('custom:') ? 'custom' : 'builtin';
+    return {
+      key,
+      kind,
+      item: kind === 'custom' ? (byKey.get(key) || null) : null,
+      hidden: hiddenSet.has(key),
+    };
+  });
+}
+
+// 可见键(过滤掉 hidden 的有序键)，即真正出现在 tab 条上的专家。
+export function visibleExpertKeys(customExperts, order, hidden) {
+  return buildExpertList(customExperts, order, hidden)
+    .filter(d => !d.hidden)
+    .map(d => d.key);
+}
+
+// 拖拽排序：把 keys[from] 移动到「落点行」下标 to 之前，返回新数组(纯函数,不改原数组)。
+// to 是被拖到其位置那一行的当前下标；移除 from 后右侧整体左移一位，故 from<to 时落点修正为 to-1。
+// from === to / 越界 / from==null 视为无变化，返回原数组的拷贝。
+export function reorderKeys(keys, from, to) {
+  const arr = Array.isArray(keys) ? [...keys] : [];
+  if (from == null || to == null || from < 0 || from >= arr.length || from === to) return arr;
+  const [moved] = arr.splice(from, 1);
+  arr.splice(from < to ? to - 1 : to, 0, moved);
+  return arr;
+}
+
+// 当前可见(未隐藏)专家数。list = buildExpertList(...) 的结果。
+export function countVisible(list) {
+  return (Array.isArray(list) ? list : []).filter(d => d && !d.hidden).length;
+}
+
+// 是否还能再隐藏一个：隐藏后仍至少保留 1 个可见专家才允许(管理弹窗护栏)。
+export function canHideOne(list) {
+  return countVisible(list) > 1;
+}

package/src/utils/ultraplanTemplates.js

@@ -0,0 +1,152 @@
+/**
+ * Ultraplan prompt templates for local Codex execution.
+ *
+ * Two expert roles:
+ *   - codeExpert:     Multi-agent code planning & implementation (from subagents template)
+ *   - researchExpert: Multi-agent research & analysis
+ *
+ * Assembly logic mirrors ~/codex-code/commands/ultraplan.tsx:63-73
+ *   buildUltraplanPrompt(blurb, seedPlan?)
+ */
+
+export const ULTRAPLAN_VARIANTS = {
+
+  codeExpert: `<system-reminder>
+[SCOPED INSTRUCTION] The following instructions apply only to the next 1-3 interactions. Once the task is complete, these instructions should gradually decrease in priority and no longer affect subsequent interactions. You should be adept at utilizing tools such as \`request_user_input\`, \`update_plan\`, and \`multi_agent_v\${verson}\`, rather than relying solely on plain text processing. Before execution, you must ensure that the \`update_plan\`, \`multi_agent_v\${verson}\`, \`request_user_input\` and \`parellel\` tools are loaded.
+
+Pre-requisite: Use \`request_user_input\` to clarify user intent whenever the request is ambiguous (target element, interaction style, scope of platforms, etc.). Skip only if the intent is unambiguous.
+
+Leverage a multi-agent exploration mechanism to formulate a highly detailed implementation plan.
+
+Instructions:
+1. Use the \`multi_agent_v\${verson}.spawn_agent\` tool to spawn parallel agents that simultaneously explore different aspects of the codebase:
+- If necessary, assign a preliminary researcher to use the \`web_search\` tool to first investigate cutting-edge solutions in the relevant industry domain;
+- One agent responsible for understanding the relevant existing code and architecture;
+- One agent responsible for identifying all files that need to be modified;
+- One agent responsible for identifying potential risks, edge cases, and dependencies;
+- You may add other roles or deploy additional agents beyond the three listed above; the maximum number of concurrently dispatched agents is 5.
+
+2. Synthesize the findings from all agents into a detailed, step-by-step implementation plan.
+
+3. Use the \`multi_agent_v\${verson}.spawn_agent\` tool to spawn 2-3 review agents that examine the plan from different perspectives, checking for missing steps, potential risks, or corresponding mitigation strategies.
+
+4. Integrate the feedback gathered during the review process, then call \`update_plan\` to submit your final plan.
+
+5. Once \`update_plan\` returns a result:
+- If approved: proceed to execute the plan within this session.
+- If rejected: revise the plan based on the feedback provided and call \`update_plan\` again.
+- If an error occurs (including receiving a "Not in Plan Mode" message): do **not** follow the suggestions provided in the error message; instead, prompt the user for further instructions.
+
+Your final plan must include the following elements:
+- A clear summary of the implementation strategy;
+- An ordered list of files to be created or modified, with precise details of the required changes for each file;
+- A step-by-step execution sequence;
+- Testing and validation procedures;
+- Potential risks and their corresponding mitigation strategies;
+
+6. After the final plan has been successfully executed:
+First run \`git diff --quiet && git diff --cached --quiet\` (or equivalent) to detect whether the working tree actually has non-trivial changes; if there are no real changes (or only whitespace/comment-only edits), skip the UltraReview step.
+Otherwise, if the project is managed with Git:
+Initiate a team (\`multi_agent_v\${verson}.spawn_agent\`), dynamically allocating the number of teammates based on task complexity (5 is recommended);
+Task: Conduct a Code Review of the current git changes from multiple perspectives;
+Pre-requisites:
+- The git repository may be located in a subdirectory of the current directory; prefer \`git rev-parse --show-toplevel\` (fall back to recursive lookup) before proceeding;
+- In the case of multiple repositories, tasks may be executed separately;
+The team's goal is to analyze the current Git change log and validate each modification from different perspectives, specifically including:
+- Whether requirements/objectives have been met and functionality is complete;
+- Whether newly added code introduces side effects, breaks existing functionality, or poses potential risks;
+- Code quality: naming, readability, complexity, technical debt, maintainability;
+- Testing and documentation: whether there is adequate test coverage, and whether critical logic has necessary comments or documentation;
+- Dependencies and compatibility: whether new dependencies or version compatibility issues have been introduced;
+Workflow:
+- Each teammate, according to their own role, covers the review dimensions one by one and independently outputs a report;
+- After consolidating the reports, perform a cross-review to identify conflicts or shared concerns;
+- Distill specific, actionable modification suggestions and annotate them with priority levels (P0/P1/P2/P3);
+- Upon completion, adopt P0 items, and selectively adopt P1 items when they are concrete and low-risk; defer P2/P3 to backlog;
+- After execution is complete, close the team (\`multi_agent_v\${verson}.close_agent\`);
+</system-reminder>`,
+
+  researchExpert: `<system-reminder>
+[SCOPED INSTRUCTION] The following instructions are intended for the next 1–3 interactions. Once the task is complete, these instructions should be gradually deprioritized and no longer influence subsequent interactions. You should be adept at utilizing Codex tools such as \`request_user_input\`, \`update_plan\`, \`tool_search\`, and \`web_search\`, rather than relying solely on plain text processing. Before execution, ensure that \`request_user_input\`, \`update_plan\`, and \`tool_search\` are available; use \`tool_search\` to discover any deferred multi-agent tools before attempting to spawn agents.
+
+Pre-requisite: Use \`request_user_input\` to clarify the research scope, target audience, and deliverable format whenever the user's intent is ambiguous. Skip only if the intent is unambiguous.
+
+Leverage a multi-agent exploration mechanism to formulate an exceptionally detailed implementation plan.
+
+Instructions:
+1. Use \`tool_search\` to discover multi-agent tools, then spawn parallel agents when those tools are available so they can simultaneously explore various facets of the requirements:
+- If necessary, deploy a preliminary investigator to conduct an initial survey of industry-specific solutions using \`web_search\`;
+- If necessary, deploy a specialized investigator to research authoritative sources—such as academic papers, news articles, and research reports—using \`web_search\`;
+- Assign an agent to synthesize the target solution, while simultaneously verifying the rigor and credibility of the gathered papers, news, and research reports;
+- If necessary, assign an agent to analyze competitor data to provide supplementary analytical perspectives;
+- If necessary, assign an agent to handle the implementation of a product demo (generating outputs such as HTML, Markdown, etc.);
+- If the task is sufficiently complex, you may assign additional teammates to the roles defined above, or introduce other specialized roles; you are permitted to schedule up to 5 teammates concurrently.
+
+2. Synthesize the findings from the aforementioned agents into a comprehensive, step-by-step implementation plan.
+
+3. Use the available multi-agent tools to spawn a set of parallel review agents; these agents shall scrutinize the plan from multiple roles and perspectives to identify any omitted steps and to propose reasonable additions or optimizations.
+
+4. Consolidate the feedback received from the review agents, then call \`update_plan\` with the final plan and use \`request_user_input\` to ask the user whether to proceed, revise, or stop.
+
+5. Once the user responds:
+- If approved: proceed to execute the plan within this current session.
+- If revisions are requested or the plan is rejected: revise the plan based on the provided feedback, call \`update_plan\` again, and ask for confirmation.
+- If an error occurs: do *not* improvise around missing tools; instead, prompt the user for further instructions.
+
+Your final plan must include the following elements:
+- A clear summary of the proposed implementation strategy;
+- An ordered list of files to be created or modified, specifying the exact changes required for each;
+- A step-by-step sequence for executing the implementation;
+- Identification of potential risks and corresponding mitigation strategies;
+- Creative ideation and suggestions for advanced enhancements;
+- If a product demo was generated, place the corresponding demo output in an appropriate location and notify the user.
+</system-reminder>`,
+
+};
+
+/**
+ * Wrap user-authored custom instruction body with the same scoped-instruction
+ * preamble used by the built-in variants. Produces a full <system-reminder>
+ * block ready to be inlined into a Codex prompt.
+ */
+export function buildCustomTemplate(content) {
+  const body = (content || '').trim();
+  if (!body) return '';
+  // 用户已自带外壳(预填的样板壳或手写)时不再重复包裹;用 startsWith 而非 includes,
+  // 避免正文里只是「提到」<system-reminder> 字样就误判而漏掉作用域声明。
+  if (body.startsWith('<system-reminder>')) return body;
+  return `<system-reminder>
+[SCOPED INSTRUCTION] The following instructions apply only to the next 1-3 interactions. Once the task is complete, these instructions should gradually decrease in priority and no longer affect subsequent interactions. You should be adept at utilizing tools such as \`request_user_input\`, \`update_plan\`, and \`multi_agent_v\${verson}\`, rather than relying solely on plain text processing. Before execution, you must ensure that the \`update_plan\`, \`multi_agent_v\${verson}\`, \`request_user_input\` and \`parellel\` tools are loaded.
+
+${body}
+</system-reminder>`;
+}
+
+/**
+ * Assemble a local ultraplan prompt.
+ * Mirrors ~/codex-code/commands/ultraplan.tsx:63-73 buildUltraplanPrompt()
+ *
+ * @param {string} userPrompt - User's task description
+ * @param {'codeExpert'|'researchExpert'|'custom'} variant - Template variant
+ * @param {string} [seedPlan] - Optional draft plan to refine
+ * @param {string} [customContent] - Required when variant === 'custom': the user-authored body
+ * @returns {string} Assembled prompt ready to send to Codex
+ */
+export function buildLocalUltraplan(userPrompt, variant = 'codeExpert', seedPlan, customContent) {
+  let template;
+  if (variant === 'custom') {
+    template = buildCustomTemplate(customContent);
+    if (!template) return '';
+  } else {
+    template = ULTRAPLAN_VARIANTS[variant] || ULTRAPLAN_VARIANTS.codeExpert;
+  }
+  const parts = [];
+  if (seedPlan) {
+    parts.push('Here is a draft plan to refine:', '', seedPlan, '');
+  }
+  parts.push(template);
+  if (userPrompt) {
+    parts.push('', userPrompt);
+  }
+  return parts.join('\n');
+}

package/src/utils/userImageRefs.js

@@ -0,0 +1,49 @@
+// 从用户消息文本里提取「应渲染为图片」的引用，供 ChatMessage 把路径换成 <img>。
+//
+// 识别三种写法（均需以图片扩展名结尾才算数）：
+//   1. [Image: source: /path/to/x.png] 或 [Image #N: …]   —— Codex CLI 的占位写法
+//   2. "/tmp/cx-viewer-uploads/x.png"                       —— 引号包裹的上传路径(拖拽/合成器流程)
+//   3.  /tmp/cx-viewer-uploads/x.png                        —— 裸路径(终端粘贴流程直接拼进提示词,无引号)
+//
+// 第 3 种是历史缺口：终端粘贴时路径被原样拼到文本里、没有引号,旧正则只认引号包裹的写法,
+// 于是这类图片只显示成纯文本路径。上传目录前缀(/tmp/cx-viewer-uploads/ 及 macOS realpath
+// 解析出的 /private 变体)足够特异,去掉引号要求不会误伤正常文案。
+
+// 路径必须以图片扩展名结尾才渲染(与服务端 /api/file-raw 支持的类型一致)。
+export const IMAGE_EXTS = /\.(?:png|jpe?g|gif|webp|avif|svg|bmp|ico|icns)$/i;
+
+// 上传目录前缀：/tmp/cx-viewer-uploads/ 与 macOS 下 realpath 解析出的 /private/tmp/... 两种。
+const UPLOAD = String.raw`(?:\/private)?\/tmp\/cx-viewer-uploads\/`;
+const EXT = String.raw`(?:png|jpe?g|gif|webp|avif|svg|bmp|ico|icns)`;
+
+// 三选一(顺序有意义：引号分支在裸路径分支之前,确保引号被一并吃掉,不会残留成文本)：
+//   group1 = [Image …] 内的路径；group2 = 双引号路径；group3 = 单引号路径；group4 = 裸上传路径。
+// 引号分支(双/单)都排在裸路径分支之前,确保整对引号被一并吃掉,不残留成文本。
+const PATTERN =
+  String.raw`\[Image(?:\s*#\d+)?(?::?\s*source)?:\s*([^\]]+)\]` +
+  String.raw`|"(${UPLOAD}[^"]+?)"` +
+  String.raw`|'(${UPLOAD}[^']+?)'` +
+  String.raw`|(${UPLOAD}[^\s"'\]\)]+?\.${EXT})`;
+
+/**
+ * 扫描文本,返回按出现顺序排列的图片引用。
+ * @param {string} text
+ * @returns {Array<{ path: string, raw: string, index: number }>}
+ *   path  = 用于请求的文件路径(已 trim)
+ *   raw   = 命中的原始子串(用于 fallback 文案,以及计算文本切片边界)
+ *   index = raw 在 text 中的起始下标
+ */
+export function findUserImageRefs(text) {
+  if (!text || typeof text !== 'string') return [];
+  // 每次新建正则,避免共享 lastIndex 带来的跨调用状态污染。
+  const re = new RegExp(PATTERN, 'gi');
+  const refs = [];
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    if (m[0] === '') { re.lastIndex++; continue; } // 防御零宽匹配死循环
+    const path = (m[1] || m[2] || m[3] || m[4] || '').trim();
+    if (!path || !IMAGE_EXTS.test(path)) continue;
+    refs.push({ path, raw: m[0], index: m.index });
+  }
+  return refs;
+}

package/src/utils/voicePackPlayer.js

@@ -0,0 +1,233 @@
+// Singleton voice-pack playback for ApprovalModal / AppBase / Mobile.
+//
+// Responsibilities:
+//   1. Resolve event → URL based on per-event binding ('default' | <uuid> | null).
+//   2. Serialise playback through one shared <Audio> element (no overlap when
+//      multiple lifecycle events fire simultaneously —).
+//   3. Honor a per-event cooldown so noisy events (turnEnd) don't spam the user.
+//   4. Survive autoplay-policy block: play() rejection falls back to Web Audio
+//      chime so the user still gets *some* signal even before they've interacted.
+//   5. Keep a separate Audio element for Settings preview so previews don't
+//      compete with live event playback.
+//
+// Pure module state — one queue per browsing context. Multi-tab Electron each
+// have their own module instance (different webContents = different module);
+// that's fine: each tab unlocks its own audio independently per browser policy.
+
+import { apiUrl } from './apiUrl.js';
+import { BUNDLED_PACK_IDS } from '../../server/lib/voice-pack-events.js';
+
+// Mirror BUNDLED_PACK_IDS into a Set for O(1) lookup in the hot URL-building
+// path. Frozen array ↔ Set conversion at module load is fine; the source list
+// is itself frozen so the Set can't drift.
+const BUNDLED_PACK_ID_SET = new Set(BUNDLED_PACK_IDS);
+
+let mainAudio = null;
+let previewAudio = null;
+const queue = [];
+let playing = false;
+let unlocked = false;
+const lastFireAt = new Map(); // eventKey → ts
+const lastDedupeKey = new Map(); // eventKey → caller-supplied dedupe key
+
+function urlForBinding(eventKey, binding) {
+  const head = '/api/voice-pack/audio';
+  // Bundled packs route as /<packId>/<eventKey>; user uploads as /<uuid>.
+  // null / undefined binding falls back to 'default' so the chime-fallback layer
+  // still gets a real URL to attempt (404 → chime is handled in startPlay).
+  // The Set check (not equality with 'default') is critical — without it,
+  // binding='sanguo' would route to /api/voice-pack/audio/sanguo (no event
+  // suffix), hit the uuid branch, fail isValidId, and 404 → silent chime.
+  const packId = (!binding) ? 'default' : binding;
+  const path = BUNDLED_PACK_ID_SET.has(packId)
+    ? `${head}/${packId}/${encodeURIComponent(eventKey)}`
+    : `${head}/${encodeURIComponent(binding)}`;
+  // apiUrl injects the ?token=... LAN auth query when present — same path other API calls use.
+  return apiUrl(path);
+}
+
+function getMainAudio() {
+  if (mainAudio) return mainAudio;
+  mainAudio = new Audio();
+  mainAudio.preload = 'auto';
+  mainAudio.addEventListener('ended', advanceQueue);
+  // 'error' also drains so a 404 / decode failure doesn't deadlock the queue.
+  mainAudio.addEventListener('error', () => { playChimeFallback(); advanceQueue(); });
+  return mainAudio;
+}
+
+let _webAudioCtx = null;
+// Two-tone chime — exported so ApprovalModal can also use it for the legacy
+// `soundEnabled` path. Single Web Audio context lives here (was duplicated
+// across player + ApprovalModal until they were deduped here).
+export function playChimeFallback() {
+  try {
+    const Ctx = window.AudioContext || window.webkitAudioContext;
+    if (!Ctx) return;
+    if (!_webAudioCtx) _webAudioCtx = new Ctx();
+    const ctx = _webAudioCtx;
+    const now = ctx.currentTime;
+    const osc = ctx.createOscillator();
+    const gain = ctx.createGain();
+    osc.type = 'sine';
+    osc.frequency.setValueAtTime(660, now);
+    osc.frequency.linearRampToValueAtTime(880, now + 0.18);
+    gain.gain.setValueAtTime(0, now);
+    gain.gain.linearRampToValueAtTime(0.18, now + 0.02);
+    gain.gain.exponentialRampToValueAtTime(0.0001, now + 0.24);
+    osc.connect(gain).connect(ctx.destination);
+    osc.start(now);
+    osc.stop(now + 0.26);
+  } catch { /* ignore */ }
+}
+
+function advanceQueue() {
+  playing = false;
+  const next = queue.shift();
+  if (next) startPlay(next);
+}
+
+function startPlay({ url, volume }) {
+  const audio = getMainAudio();
+  playing = true;
+  try {
+    audio.src = url;
+    audio.volume = Math.max(0, Math.min(1, volume));
+    const p = audio.play();
+    if (p && typeof p.catch === 'function') {
+      p.catch(() => {
+        // Autoplay blocked OR audio 404 — fire chime so user is at least notified,
+        // and immediately drain so we don't sit on a poisoned queue.
+        playChimeFallback();
+        advanceQueue();
+      });
+    }
+  } catch {
+    playChimeFallback();
+    advanceQueue();
+  }
+}
+
+// Per-event cooldown (review: kept as a module constant, not user-configurable.
+// The previous prefs.cooldownMs override was phantom config — neither persisted
+// nor exposed in Settings — so it was removed to avoid half-built
+// flexibility users couldn't actually use).
+// SUNSET-MARKER: cxv-turn-end-debounce
+// Frontend caller-side cooldown，作为 server 端 trailing debounce 漏掉时的兜底二保险
+// （SSE 重连重发、server 罕见广播失序等）。**与 server `CXV_TURN_END_DEBOUNCE_MS`
+// 自动对齐**：AppBase.jsx 监听 SSE `server_config` 事件并调 `setTurnEndCooldownMs` 注入
+// server 实际生效的 debounce 值，无需运维手工同步两边常量。
+const COOLDOWN_MS = {
+  turnEnd: 10_000,
+};
+
+/**
+ * Update the turnEnd caller-side cooldown at runtime — called by AppBase on
+ * receipt of `server_config` SSE event. Keeps frontend in sync with the server's
+ * `CXV_TURN_END_DEBOUNCE_MS` env override without redeploy.
+ * Mirrors server clamp [100, 60000] so a malformed/tampered server_config payload
+ * (n=0 disables cooldown → voice spam) can't kill the二保险.
+ */
+export function setTurnEndCooldownMs(ms) {
+  const n = Number(ms);
+  if (!Number.isFinite(n) || n < 100 || n > 60_000) {
+    try { console.warn(`[voicePack] setTurnEndCooldownMs(${ms}) out of [100,60000]; keeping`, COOLDOWN_MS.turnEnd); } catch {}
+    return;
+  }
+  COOLDOWN_MS.turnEnd = n;
+}
+
+// Main entry point.
+//   eventKey:  'planApproval' | 'askQuestion' | 'turnEnd'
+//   prefs:     prefs.approvalModal.voicePack — { enabled, volume, events: { ... } }
+//   opts.dedupeKey:  optional string; second call with same key for same event is ignored
+export function playEvent(eventKey, prefs, opts = {}) {
+  if (typeof window === 'undefined') return false;
+  if (!prefs || prefs.enabled !== true) return false;
+  const binding = prefs.events && prefs.events[eventKey];
+  if (binding === null || binding === undefined) return false; // event disabled
+
+  // Per-event cooldown (constants only — no prefs override; see COOLDOWN_MS).
+  const cooldown = COOLDOWN_MS[eventKey] || 0;
+  if (cooldown > 0) {
+    const last = lastFireAt.get(eventKey) || 0;
+    if (Date.now() - last < cooldown) return false;
+  }
+
+  // Caller-side dedupe (e.g. same approval modal kind re-rendering shouldn't
+  // refire). Per-event key isolation so concurrent kinds don't suppress each other.
+  if (opts.dedupeKey) {
+    if (lastDedupeKey.get(eventKey) === opts.dedupeKey) return false;
+    lastDedupeKey.set(eventKey, opts.dedupeKey);
+  }
+
+  lastFireAt.set(eventKey, Date.now());
+  const url = urlForBinding(eventKey, binding);
+  const volume = typeof prefs.volume === 'number' ? Math.max(0, Math.min(1, prefs.volume)) : 0.3;
+
+  if (playing) {
+    queue.push({ url, volume });
+  } else {
+    startPlay({ url, volume });
+  }
+  return true;
+}
+
+// Settings preview — independent of the live queue, so previewing while a
+// real event is playing doesn't either kill the live audio or wait behind it.
+export function previewEvent(eventKey, prefs) {
+  if (typeof window === 'undefined') return Promise.resolve();
+  if (!previewAudio) previewAudio = new Audio();
+  try {
+    previewAudio.pause();
+    previewAudio.currentTime = 0;
+  } catch { /* ignore */ }
+  const binding = (prefs?.events && prefs.events[eventKey]) || 'default';
+  previewAudio.src = urlForBinding(eventKey, binding);
+  previewAudio.volume = typeof prefs?.volume === 'number' ? Math.max(0, Math.min(1, prefs.volume)) : 0.3;
+  const p = previewAudio.play();
+  if (p && typeof p.catch === 'function') {
+    return p.catch(() => { playChimeFallback(); });
+  }
+  return Promise.resolve();
+}
+
+export function stopPreview() {
+  if (previewAudio) {
+    try { previewAudio.pause(); previewAudio.currentTime = 0; } catch { /* ignore */ }
+  }
+}
+
+// Call from a click / keypress handler (Settings open is a good spot) to satisfy
+// Chrome/Safari/Firefox autoplay policy. Plays a silent 1-sample WAV so the
+// audio element is "blessed" for programmatic playback for the rest of the tab's life.
+export function unlockAudio() {
+  if (unlocked) return Promise.resolve(true);
+  if (typeof window === 'undefined') return Promise.resolve(false);
+  try {
+    const audio = getMainAudio();
+    audio.volume = 0;
+    audio.src = 'data:audio/wav;base64,UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=';
+    const p = audio.play();
+    if (p && typeof p.then === 'function') {
+      return p.then(() => { unlocked = true; return true; }).catch(() => false);
+    }
+    unlocked = true;
+    return Promise.resolve(true);
+  } catch { return Promise.resolve(false); }
+}
+
+// Test hook — reset module state between unit tests. **Do not call from app code.**
+// Exported as a named function so an "unused exports" linter can see it's referenced
+// by test/voice-pack-player.test.js (— without this, a future cleanup pass
+// could mistake it for dead code).
+export function _resetForTests() {
+  mainAudio = null;
+  previewAudio = null;
+  queue.length = 0;
+  playing = false;
+  unlocked = false;
+  lastFireAt.clear();
+  lastDedupeKey.clear();
+  _webAudioCtx = null;
+}

package/src/utils/webResultGrouping.js

@@ -0,0 +1,111 @@
+/**
+ * Web search rendering helpers.
+ *
+ * Anthropic 的 server-side web_search 工具在 assistant message 的 content 数组里
+ * 直接放两个兄弟块：server_tool_use（搜索发起）+ web_search_tool_result（结果）。
+ * 紧随其后的 text 块（含带 citations 的）是模型基于结果生成的综合回复。
+ *
+ * 本文件提供：
+ *   - extractWebResultGroups(content): 识别 [server_tool_use, web_search_tool_result, ...synthesis text]
+ *     子序列，返回 groups + content 全局 index 的 consumedIndices Set。
+ *   - safeHref(url): URL 协议白名单（仅 http/https），防 javascript:/data:/file:// 协议 XSS。
+ *   - getHostname(url): try/catch 包装的 new URL(url).hostname。
+ *
+ * 设计上故意做成纯 JS（无 React/CSS 依赖），让 Node test runner 能直接 import。
+ */
+
+export function extractWebResultGroups(content) {
+  const groups = [];
+  const consumedIndices = new Set();
+
+  if (!Array.isArray(content) || content.length === 0) {
+    return { groups, consumedIndices };
+  }
+
+  for (let i = 0; i < content.length; i++) {
+    const block = content[i];
+    if (!block || typeof block !== 'object') continue;
+
+    if (block.type === 'server_tool_use') {
+      let resultIdx = -1;
+      for (let j = i + 1; j < content.length; j++) {
+        const b = content[j];
+        if (!b || typeof b !== 'object') continue;
+        if (b.type === 'thinking') continue;
+        if (b.type === 'web_search_tool_result' && b.tool_use_id === block.id) {
+          resultIdx = j;
+        }
+        break;
+      }
+
+      if (resultIdx === -1) {
+        groups.push({
+          serverToolUseIndex: i,
+          serverToolUse: block,
+          webSearchResultIndex: -1,
+          webSearchResult: null,
+          synthesisTextIndices: [],
+        });
+        consumedIndices.add(i);
+        continue;
+      }
+
+      const synthesisIndices = [];
+      for (let k = resultIdx + 1; k < content.length; k++) {
+        const b = content[k];
+        if (!b || typeof b !== 'object') break;
+        if (b.type === 'text') {
+          synthesisIndices.push(k);
+          continue;
+        }
+        if (b.type === 'thinking') break;
+        if (b.type === 'tool_use' || b.type === 'server_tool_use') break;
+        break;
+      }
+
+      groups.push({
+        serverToolUseIndex: i,
+        serverToolUse: block,
+        webSearchResultIndex: resultIdx,
+        webSearchResult: content[resultIdx],
+        synthesisTextIndices: synthesisIndices,
+      });
+      consumedIndices.add(i);
+      consumedIndices.add(resultIdx);
+      for (const k of synthesisIndices) consumedIndices.add(k);
+    } else if (block.type === 'web_search_tool_result') {
+      if (consumedIndices.has(i)) continue;
+      groups.push({
+        serverToolUseIndex: -1,
+        serverToolUse: null,
+        webSearchResultIndex: i,
+        webSearchResult: block,
+        synthesisTextIndices: [],
+      });
+      consumedIndices.add(i);
+    }
+  }
+
+  return { groups, consumedIndices };
+}
+
+const SAFE_PROTOCOLS = new Set(['http:', 'https:']);
+
+export function safeHref(url) {
+  if (typeof url !== 'string' || !url) return null;
+  try {
+    const u = new URL(url);
+    return SAFE_PROTOCOLS.has(u.protocol) ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+export function getHostname(url) {
+  if (typeof url !== 'string' || !url) return '';
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return url.length > 40 ? url.slice(0, 40) + '…' : url;
+  }
+}