cx-viewer 1.0.2 → 1.0.4

package/src/utils/teammateAvatars.js

@@ -0,0 +1,194 @@
+import analystSvg from '../img/teammates/analyst.svg?raw';
+import auditorSvg from '../img/teammates/auditor.svg?raw';
+import builderSvg from '../img/teammates/builder.svg?raw';
+import defaultSvg from '../img/teammates/default.svg?raw';
+import designerSvg from '../img/teammates/designer.svg?raw';
+import executorSvg from '../img/teammates/executor.svg?raw';
+import expertSvg from '../img/teammates/expert.svg?raw';
+import explorerSvg from '../img/teammates/explorer.svg?raw';
+import implementerSvg from '../img/teammates/implementer.svg?raw';
+import investigatorSvg from '../img/teammates/investigator.svg?raw';
+import researcherSvg from '../img/teammates/researcher.svg?raw';
+import reviewerSvg from '../img/teammates/reviewer.svg?raw';
+import scannerSvg from '../img/teammates/scanner.svg?raw';
+import securitySvg from '../img/teammates/security.svg?raw';
+import tracerSvg from '../img/teammates/tracer.svg?raw';
+import translatorSvg from '../img/teammates/translator.svg?raw';
+import workerSvg from '../img/teammates/worker.svg?raw';
+
+export const ROLE_MAP = {
+  worker:       { svg: workerSvg },
+  reviewer:     { svg: reviewerSvg },
+  researcher:   { svg: researcherSvg },
+  explorer:     { svg: explorerSvg },
+  analyst:      { svg: analystSvg },
+  tracer:       { svg: tracerSvg },
+  investigator: { svg: investigatorSvg },
+  builder:      { svg: builderSvg },
+  implementer:  { svg: implementerSvg },
+  auditor:      { svg: auditorSvg },
+  translator:   { svg: translatorSvg },
+  security:     { svg: securitySvg },
+  scanner:      { svg: scannerSvg },
+  expert:       { svg: expertSvg },
+  executor:     { svg: executorSvg },
+  designer:     { svg: designerSvg },
+  default:      { svg: defaultSvg },
+};
+
+const PREFIX_RULES = [
+  { prefix: 'worker-',       role: 'worker' },
+  { prefix: 'reviewer-',     role: 'reviewer' },
+  { prefix: 'researcher-',   role: 'researcher' },
+  { prefix: 'explorer-',     role: 'explorer' },
+  { prefix: 'explore-',      role: 'explorer' },
+  { prefix: 'translator-',   role: 'translator' },
+  { prefix: 'svg-creator-',  role: 'designer' },
+];
+
+const SUFFIX_RULES = [
+  { suffix: '-reviewer',      role: 'reviewer' },
+  { suffix: '-analyst',       role: 'analyst' },
+  { suffix: '-tracer',        role: 'tracer' },
+  { suffix: '-investigator',  role: 'investigator' },
+  { suffix: '-builder',       role: 'builder' },
+  { suffix: '-impl',          role: 'implementer' },
+  { suffix: '-auditor',       role: 'auditor' },
+  { suffix: '-scanner',       role: 'scanner' },
+  { suffix: '-expert',        role: 'expert' },
+  { suffix: '-executor',      role: 'executor' },
+];
+
+const CONTAINS_RULES = [
+  { keyword: 'security',     role: 'security' },
+  { keyword: 'implementer',  role: 'implementer' },
+  { keyword: 'review',       role: 'reviewer' },
+  { keyword: 'explor',       role: 'explorer' },
+  { keyword: 'research',     role: 'researcher' },
+  { keyword: 'analy',        role: 'analyst' },
+  { keyword: 'trac',         role: 'tracer' },
+  { keyword: 'investigat',   role: 'investigator' },
+  { keyword: 'build',        role: 'builder' },
+  { keyword: 'audit',        role: 'auditor' },
+  { keyword: 'translat',     role: 'translator' },
+  { keyword: 'scan',         role: 'scanner' },
+  { keyword: 'expert',       role: 'expert' },
+  { keyword: 'execut',       role: 'executor' },
+  { keyword: 'design',       role: 'designer' },
+  { keyword: 'work',         role: 'worker' },
+];
+
+const ABBREV_PREFIX_RULES = [
+  { prefix: 'cr-', role: 'reviewer' },
+  { prefix: 'r-',  role: 'reviewer' },
+  { prefix: 'ui-', role: 'reviewer' },
+  { prefix: 'ux-', role: 'reviewer' },
+];
+
+// Hash-based fallback: deterministic role from name (visual variety for unmatched names)
+const ROLE_KEYS = Object.keys(ROLE_MAP).filter(k => k !== 'default');
+
+function resolveRole(name) {
+  const lower = name.toLowerCase();
+
+  for (const { prefix, role } of PREFIX_RULES) {
+    if (lower.startsWith(prefix)) return role;
+  }
+
+  for (const { suffix, role } of SUFFIX_RULES) {
+    if (lower.endsWith(suffix)) return role;
+  }
+
+  for (const { keyword, role } of CONTAINS_RULES) {
+    if (lower.includes(keyword)) return role;
+  }
+
+  for (const { prefix, role } of ABBREV_PREFIX_RULES) {
+    if (lower.startsWith(prefix)) return role;
+  }
+
+  // Hash fallback: same name always maps to same role
+  if (lower.length > 0) {
+    let hash = 0;
+    for (let i = 0; i < lower.length; i++) hash = lower.charCodeAt(i) + ((hash << 5) - hash);
+    return ROLE_KEYS[((hash % ROLE_KEYS.length) + ROLE_KEYS.length) % ROLE_KEYS.length];
+  }
+
+  return 'default';
+}
+
+// 20 个 CSS 变量引用：背景色由 global.css 按当前主题（曜石黑 / 雪山白）决定。
+// 运行时不做主题判定，避免初次渲染时 data-theme 未就绪导致的误判。
+// 索引对应 `--avatar-bg-0..19`，顺序由 nameToColorIndex 决定。
+const AVATAR_BG_VAR_COUNT = 20;
+
+function nameToColorIndex(name) {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) hash = name.charCodeAt(i) + ((hash << 5) - hash);
+  return ((hash % AVATAR_BG_VAR_COUNT) + AVATAR_BG_VAR_COUNT) % AVATAR_BG_VAR_COUNT;
+}
+
+// Removes SMIL <animate> elements from an avatar SVG string. DESIGN.md's
+// degradation rule guarantees the static markup IS the finished portrait
+// (all animate elements are self-closing and hold their hidden states inside
+// the animate itself), so the stripped string renders the complete image.
+// The narrow regex (only self-closing <animate>) is intentionally coupled to
+// test/teammate-svg-assets.test.js, whose element allowlist and self-closing
+// assertion forbid animateTransform/animateMotion/<set> and open-form
+// <animate> — keep both in sync if that allowlist ever relaxes.
+export function stripSvgAnimations(svg) {
+  return svg.replace(/<animate\b[^>]*\/>/g, '');
+}
+
+// Static (animation-stripped) variant per role, computed once so the strip
+// regex does not rerun on every render of every old row.
+const _staticSvgCache = new Map();
+
+function getStaticSvg(role, svg) {
+  let cached = _staticSvgCache.get(role);
+  if (cached === undefined) {
+    cached = stripSvgAnimations(svg);
+    _staticSvgCache.set(role, cached);
+  }
+  return cached;
+}
+
+// Policy: a teammate avatar plays its one-shot draw-in only when its message
+// timestamp is within windowMs of the newest item's timestamp. Missing or
+// unparseable timestamps animate (today's behavior). latestTs may be an ISO
+// string or epoch ms.
+export function shouldAnimateTeammateAvatar(msgTs, latestTs, windowMs = 60000) {
+  const msgMs = typeof msgTs === 'number' ? msgTs : Date.parse(msgTs);
+  const latestMs = typeof latestTs === 'number' ? latestTs : Date.parse(latestTs);
+  if (Number.isNaN(msgMs) || Number.isNaN(latestMs)) return true;
+  return latestMs - msgMs <= windowMs;
+}
+
+// Scan helper for ChatView.buildAllItems: given [{ts, isTeammateAvatar}] in
+// render order, returns the max parseable timestamp (epoch ms; NaN entries
+// skipped) and the index of the last teammate-avatar row (-1 if none).
+export function pickAvatarAnimationTargets(entries) {
+  let latestMs = NaN;
+  let newestTeammateIdx = -1;
+  for (let i = 0; i < entries.length; i++) {
+    const { ts, isTeammateAvatar } = entries[i];
+    const ms = typeof ts === 'number' ? ts : Date.parse(ts);
+    if (!Number.isNaN(ms) && (Number.isNaN(latestMs) || ms > latestMs)) latestMs = ms;
+    if (isTeammateAvatar) newestTeammateIdx = i;
+  }
+  return { latestMs, newestTeammateIdx };
+}
+
+export function getTeammateAvatar(name, { animated = true } = {}) {
+  let clean = (name || '').trim();
+  // Strip "Teammate: " prefix (from formatTeammateLabel)
+  clean = clean.replace(/^Teammate:\s*/i, '');
+  // Strip trailing "(model-info)" suffix
+  clean = clean.replace(/\([^)]*\)\s*$/, '').trim();
+  const role = resolveRole(clean);
+  const entry = ROLE_MAP[role];
+  // SVG 表达角色，CSS 变量引用表达个体身份——浏览器按当前 [data-theme] 选值
+  const color = `var(--avatar-bg-${nameToColorIndex(clean)})`;
+  const svg = animated ? entry.svg : getStaticSvg(role, entry.svg);
+  return { svg, color, role };
+}

package/src/utils/teammateDetector.js

@@ -0,0 +1,106 @@
+/**
+ * Native Teammate 检测器
+ *
+ * 识别 Codex 同进程内通过当前 collab 工具启动的 native teammate。
+ * 与外部进程 teammate（通过 --agent-name 参数启动）不同，native teammate
+ * 的 API 请求没有 req.teammate 字段，需要通过 instructions 特征检测。
+ *
+ * 特征：instructions 中包含 "You are a Codex agent" 标记
+ * （主 agent 的 instructions 是 "You are Codex"）
+ *
+ * 版本兼容：
+ * - Codex v2.1.81+: instructions includes "You are a Codex agent".
+ * - 未来版本如果特征变化，在此文件中添加新的检测规则即可
+ */
+
+import { getInputItemText, getInstructionsText, getResponseInputItems, getResponseInstructions } from '../../lib/openai-body.js';
+
+// Native teammate 特征：instructions 包含 "You are a Codex agent"
+// 注意区分 "You are Codex"（主 agent）
+// 但 "You are a Codex agent" 对所有 SDK agent（含普通 subagent）都匹配，
+// 单这一条判据会把普通 subagent 误判为 teammate。
+// 真正区分：teammate 之间通过 send_input 通信，subagent 不会被授予该工具。
+const NATIVE_TEAMMATE_RE = /You are a Codex agent/i;
+
+// WeakMap cache 避免重复检测
+const _cache = new WeakMap();
+
+/**
+ * 判断请求是否为 native teammate（同进程内的 Agent 子代理）
+ * @param {object} req - 请求对象
+ * @returns {boolean}
+ */
+export function isNativeTeammate(req) {
+  if (!req) return false;
+  const cached = _cache.get(req);
+  if (cached !== undefined) return cached;
+
+  // 已有 teammate 字段（外部进程 teammate）→ 不是 native teammate
+  if (req.teammate) {
+    _cache.set(req, false);
+    return false;
+  }
+
+  const instructionsText = getInstructionsText(req.body || {});
+  if (!NATIVE_TEAMMATE_RE.test(instructionsText)) {
+    _cache.set(req, false);
+    return false;
+  }
+
+  // send_input 是 teammate 间通信必需工具，普通 subagent 不会被授予。
+  // 命中正则但没 send_input → 是普通 subagent，不是 teammate。
+  const tools = req.body?.tools;
+  const hasSendInput = Array.isArray(tools) && tools.some(t => t && t.name === 'send_input');
+  const result = hasSendInput;
+  _cache.set(req, result);
+  return result;
+}
+
+/**
+ * 从 native teammate 请求中提取名字
+ * 优先从首条 user input item 中匹配 "You are XXX" 模式
+ * @param {object} req - 请求对象
+ * @returns {string|null}
+ */
+export function extractNativeTeammateName(req) {
+  if (!req?.body) return null;
+
+  const input = getResponseInputItems(req.body);
+  if (input.length === 0) return null;
+
+  // 搜索所有 user input items（上下文压缩后 hook 可能不在 input[0] 中）
+  for (const m of input) {
+    if (m.role !== 'user') continue;
+    const text = getInputItemText(m);
+    if (!text) continue;
+
+    // 匹配名字模式（按优先级尝试）
+    const nameMatch =
+      // OMC hook: "agent oh-my-codexcode:code-reviewer started"
+      text.match(/agent\s+(?:oh-my-codexcode:)?(\S+)\s+started/i)
+      // 任务提示: "You are CRer2, ..."
+      || text.match(/You are (\w+)[,.]/)
+      // 显式名字: "name: CRer2"
+      || text.match(/name[：:]\s*["']?(\w+)/i);
+    if (nameMatch) return nameMatch[1];
+  }
+
+  return null;
+}
+
+/**
+ * 从 instructions block 中提取版本号。
+ * Codex-native entries should prefer explicit metadata when available.
+ * @param {object} req - 请求对象
+ * @returns {string|null} 版本号如 "2.1.90" 或 null
+ */
+export function extractCcVersion(req) {
+  const instructions = getResponseInstructions(req?.body);
+  if (!Array.isArray(instructions)) return null;
+  for (const block of instructions) {
+    if (!block?.text) continue;
+    const m = block.text.match(/cc_version=([\d.]+[a-fA-F0-9]*)/);
+    if (m) return m[1];
+  }
+  return null;
+}

package/src/utils/termDiag.js

@@ -0,0 +1,114 @@
+/**
+ * termDiag —— 终端渲染管线最小可观测性（Windows 卡死排查回报通道）。
+ *
+ * 纯本地、仅数值计数器/水位，不含任何命令内容、无任何上报。
+ * 使用方式（用户侧）：
+ *   - 控制台执行 `__cxvTermDiag()` 获取快照；
+ *   - `localStorage.cxv_term_diag = '1'` 后每 5s console.warn 一行
+ *     `[cxv-diag] {...}`（沿既有 [cx-viewer] 英文诊断日志惯例，非 UI 文案，
+ *     不走 i18n）。
+ *
+ * 指标：
+ *   trimCount        writeQueue 积压丢弃次数（2MB 高水位触发）
+ *   resyncCount      服务端 data-resync 次数（behind→resume 振荡的标尺）
+ *   longtaskCount    主线程 ≥50ms 长任务数（PerformanceObserver，仅计数不降级）
+ *   writeQPendingBytes / chunkSize / cbLatencyEwma   喂入闭环水位（P2 自适应接线）
+ *   detect*          promptDetect 耗时统计（>50ms 计 overrun——仅监测计数，无熔断降级）
+ *
+ * 纯 JS、浏览器 API 全部能力守卫（node:test 可直接 import 测纯逻辑）。
+ */
+import { getPromptDetectStats } from './promptDetect.js';
+
+const counters = {
+  trimCount: 0,
+  resyncCount: 0,
+  longtaskCount: 0,
+};
+
+const gauges = {
+  writeQPendingBytes: 0,
+  chunkSize: 0,
+  cbLatencyEwma: 0,
+};
+
+export function diagCount(name, n = 1) {
+  if (typeof counters[name] === 'number') counters[name] += n;
+}
+
+export function diagSet(name, value) {
+  if (typeof gauges[name] === 'number' && typeof value === 'number') gauges[name] = value;
+}
+
+/** 指数加权滑动平均（alpha 默认 0.2），返回更新后的值 */
+export function diagEwma(name, sample, alpha = 0.2) {
+  if (typeof gauges[name] !== 'number' || typeof sample !== 'number') return 0;
+  gauges[name] = gauges[name] === 0 ? sample : gauges[name] * (1 - alpha) + sample * alpha;
+  return gauges[name];
+}
+
+export function getTermDiagSnapshot() {
+  const detect = getPromptDetectStats();
+  return {
+    ...counters,
+    writeQPendingBytes: Math.round(gauges.writeQPendingBytes),
+    chunkSize: Math.round(gauges.chunkSize),
+    cbLatencyEwma: Math.round(gauges.cbLatencyEwma * 10) / 10,
+    detectCalls: detect.calls,
+    detectLastMs: Math.round(detect.lastMs * 10) / 10,
+    detectMaxMs: Math.round(detect.maxMs * 10) / 10,
+    detectOverruns: detect.overruns,
+  };
+}
+
+/** 仅测试用：清零本模块计数（promptDetect 的统计不归此处管） */
+export function _resetTermDiagForTest() {
+  for (const k of Object.keys(counters)) counters[k] = 0;
+  for (const k of Object.keys(gauges)) gauges[k] = 0;
+}
+
+let _installed = false;
+let _logTimer = null;
+let _ltObserver = null;
+
+/**
+ * 浏览器侧安装（幂等）：window.__cxvTermDiag + longtask 计数 + 可选周期日志。
+ * 在 node 环境（无 window）下为 no-op。
+ */
+export function installTermDiag() {
+  if (_installed || typeof window === 'undefined') return;
+  _installed = true;
+
+  window.__cxvTermDiag = getTermDiagSnapshot;
+
+  // 长任务仅计数不降级（与 TerminalPanel WebGL 守卫的能力检测同模式）
+  try {
+    if (typeof PerformanceObserver !== 'undefined'
+        && PerformanceObserver.supportedEntryTypes?.includes('longtask')) {
+      _ltObserver = new PerformanceObserver((list) => {
+        diagCount('longtaskCount', list.getEntries().length);
+      });
+      _ltObserver.observe({ entryTypes: ['longtask'] });
+    }
+  } catch {}
+
+  // 周期日志：localStorage 开关，运行期改动即时生效（每 tick 重查）
+  try {
+    _logTimer = setInterval(() => {
+      try {
+        if (localStorage.getItem('cxv_term_diag') === '1') {
+          console.warn('[cxv-diag] ' + JSON.stringify(getTermDiagSnapshot()));
+        }
+      } catch {}
+    }, 5000);
+  } catch {}
+}
+
+/** 仅测试/热重载用：卸载 observer 与定时器 */
+export function uninstallTermDiag() {
+  if (_ltObserver) { try { _ltObserver.disconnect(); } catch {} _ltObserver = null; }
+  if (_logTimer) { clearInterval(_logTimer); _logTimer = null; }
+  if (typeof window !== 'undefined' && window.__cxvTermDiag === getTermDiagSnapshot) {
+    try { delete window.__cxvTermDiag; } catch {}
+  }
+  _installed = false;
+}

package/src/utils/terminalClipboard.js

@@ -0,0 +1,117 @@
+// ============================================================================
+// 终端复制/粘贴键位判定 + 剪贴板写入（共用于 TerminalPanel / ScratchTerminal）
+// ----------------------------------------------------------------------------
+// 背景：xterm 6 的键盘处理把 Ctrl+C / Ctrl+V 当控制字符（\x03 / \x16）发往 PTY，
+// 并对该 keydown 调用 preventDefault（CoreBrowserTerminal._keyDown 末尾的 cancel）。
+// 后果（仅 Win/Linux，Mac 用 Cmd+C/V 走 metaKey 不受影响）：
+//   - Ctrl+V：浏览器原生 paste 默认动作被压掉 → 无法粘贴（只有 Ctrl+Shift+V 能用，
+//             因为带 Shift 不进 ctrl-letter 控制字符分支，xterm 不 cancel，原生 paste 照常）。
+//   - Ctrl+C：恒发 SIGINT，永远不会复制。
+// 这里把 Ctrl+C/Ctrl+V 还原成"智能复制/粘贴"（对齐 Windows Terminal / VS Code 终端）：
+// 在 attachCustomKeyEventHandler（最先执行、且返回 false 时 xterm 不会 cancel/preventDefault）
+// 里判定动作，由调用方主动读剪贴板并走安全送出路径。
+// ============================================================================
+
+/**
+ * 判断键盘事件是否应触发终端的复制/粘贴。
+ * 仅在 keydown、Ctrl 按下（且非 Shift/Alt/Meta）、非 Mac、物理键为 C/V 时命中。
+ * 纯函数，不读取任何全局状态（isMac 由调用方传入），便于单测。
+ *
+ * @param {KeyboardEvent} e
+ * @param {{ isMac?: boolean }} [opts]
+ * @returns {'copy'|'paste'|null}
+ */
+export function clipboardKeyAction(e, opts = {}) {
+  // Mac：Ctrl+C/V 维持终端原义（SIGINT / 字面插入），复制粘贴走 Cmd（metaKey），不在此接管。
+  if (opts.isMac) return null;
+  if (!e || e.type !== 'keydown') return null;
+  if (!e.ctrlKey || e.shiftKey || e.altKey || e.metaKey) return null;
+  // e.code 是物理键位（布局无关）；同时兼容只有 e.key 的场景。
+  const key = typeof e.key === 'string' ? e.key.toLowerCase() : '';
+  if (e.code === 'KeyC' || key === 'c') return 'copy';
+  if (e.code === 'KeyV' || key === 'v') return 'paste';
+  // 刻意不接管 Ctrl+X：终端里它是合法控制字符（\x18，如 emacs/nano 前缀键），剪切语义不适用，交回 xterm。
+  return null;
+}
+
+/**
+ * 计算粘贴时应发送给 PTY 的字节串：bracketed-paste 包裹 + 注入消毒决策。
+ * 抽出原 _handlePaste / _pasteText（及 scratch 对应）中重复的判定，便于单测覆盖这段最易回归的逻辑。
+ *
+ * @param {string} text 剪贴板文本
+ * @param {{ bracketedPasteMode?: boolean, active?: boolean, sanitize?: (s:string)=>string }} [opts]
+ *   - active=false（原生 paste 路径）：bracketedPasteMode 且无注入时返回 null（交 xterm 自动包裹）；
+ *     单行且无包裹模式也返回 null（交浏览器原生插入）；其余包裹。
+ *   - active=true（主动读剪贴板，无原生 paste 事件）：bracketedPasteMode 时也自行包裹；单行原样返回。
+ * @returns {string|null} 要 ws.send 的 data；null 表示此处不发送（交由 xterm / 原生处理）
+ */
+export function planPasteSend(text, opts = {}) {
+  if (typeof text !== 'string' || text.length === 0) return null;
+  const { bracketedPasteMode = false, active = false, sanitize = (s) => s } = opts;
+  const hasInjection = /\x1b\[20[01]~/.test(text);
+  // 原生路径下：shell 已开 bracketed paste 且无注入序列 → xterm 会自动包裹，无需干预
+  if (!active && bracketedPasteMode && !hasInjection) return null;
+  const isMultiline = text.includes('\n') || text.includes('\r');
+  const needWrap = active ? (bracketedPasteMode || hasInjection || isMultiline)
+                          : (hasInjection || isMultiline);
+  if (needWrap) return `\x1b[200~${sanitize(text)}\x1b[201~`;
+  // active：单行无包裹模式 → 原样发送；原生路径：交浏览器默认插入（不发送）
+  return active ? text : null;
+}
+
+/**
+ * 将文本写入剪贴板：安全上下文优先 navigator.clipboard.writeText，
+ * 否则退回隐藏 textarea + document.execCommand('copy')（覆盖 LAN HTTP 等非安全上下文），
+ * 并在结束后还原原焦点，避免抢走终端焦点。
+ *
+ * @param {string} text
+ * @returns {Promise<boolean>} 是否复制成功
+ */
+export async function copyTextToClipboard(text) {
+  if (typeof text !== 'string' || text.length === 0) return false;
+  const clip = typeof navigator !== 'undefined' ? navigator.clipboard : null;
+  if (clip && typeof clip.writeText === 'function') {
+    try {
+      await clip.writeText(text);
+      return true;
+    } catch {
+      // 安全上下文但权限/焦点等原因失败 → 落到 execCommand 兜底
+    }
+  }
+  return execCommandCopy(text);
+}
+
+function execCommandCopy(text) {
+  if (typeof document === 'undefined' || !document.body) return false;
+  const prevActive = document.activeElement;
+  const ta = document.createElement('textarea');
+  ta.value = text;
+  ta.setAttribute('readonly', '');
+  ta.style.position = 'fixed';
+  ta.style.top = '-9999px';
+  ta.style.left = '-9999px';
+  ta.style.opacity = '0';
+  document.body.appendChild(ta);
+  let ok = false;
+  try {
+    ta.focus();
+    ta.select();
+    ok = document.execCommand('copy');
+  } catch {
+    ok = false;
+  }
+  try {
+    document.body.removeChild(ta);
+  } catch {
+    /* noop */
+  }
+  // 还原焦点（execCommand 复制需要短暂聚焦临时 textarea，复制后交还原元素）
+  if (prevActive && typeof prevActive.focus === 'function') {
+    try {
+      prevActive.focus();
+    } catch {
+      /* noop */
+    }
+  }
+  return ok;
+}