16 · 已知坑与规避清单

      // 漏掉 'system' 分支会导致「曾选过跟随系统 + 系统深色」的用户每次加载先闪浅色。
      ;(function () {
        const theme = localStorage.getItem('tools-theme')
        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
        const isDark = theme === 'dark' || ((!theme || theme === 'system') && prefersDark)
        const root = document.documentElement
        if (isDark) {
          root.classList.add('dark')
          root.setAttribute('data-theme', 'dark')
        } else {
          root.classList.add('light')
          root.setAttribute('data-theme', 'light')
        }
      })()

// 主题判定的唯一来源：模块级 computed（单例、响应式）。
// 此前是 () => theme.value === 'dark' 的函数形式，导致全站三种写法并存
// （函数调用 / 组件内自建 computed / 直接比较 theme.value），其中
// UniversalCodeBlock 的自建实现读的是 document classList，主题切换后不更新。
export const isDark = computed(() => theme.value === 'dark')
export const isLight = computed(() => theme.value === 'light')

// 报告 #14 修复：原实现把 `watch(theme, applyTheme)` 延迟到首次 useTheme() 调用
// 时注册，被绑定到该组件作用域；若该组件卸载（如 HMR 重建），watch 被 stop，
// 后续切换主题再也不会同步到 DOM。改用独立 effectScope，把响应式副作用与组件
// 生命周期解耦，watch 永不停止。
const themeScope = effectScope(true)
let themeWatchInitialized = false

themeScope.run(() => {
  watch(theme, applyTheme, { immediate: true })
  themeWatchInitialized = true
})

    alias: [
      {
        // monaco-editor 的 package.json **只有 module 字段**（没有 main / exports / types），
        // vitest 的 SSR 式解析因此拿不到包入口，报
        // "Failed to resolve import \"monaco-editor\""。dev / build 走 Vite 客户端解析，
        // 本就能落到 module，无需此别名。
        // 替身而非真实模块：真实 monaco 是 3.7MB 的 ESM 图，内联转换会让单个用例文件从 ~2s
        // 涨到 ~21s；且 jsdom 没有 Worker，真实 Monaco 在测试里本来也无法工作。
        // 用带 $ 的正则而非字符串：字符串别名按前缀匹配，会把
        // `monaco-editor/esm/vs/.../xxx.worker?worker` 这类子路径一并改写坏。
        find: /^monaco-editor$/,
        replacement: fileURLToPath(new URL('./src/test/monaco-module-stub.ts', import.meta.url)),
      },

const SKIP: Record<string, string> = {
  'dev-screen-recorder': 'jsdom 无真实 canvas 2d context（需 node-canvas）',
}

/**
 * 全量工具页冒烟：逐个挂载，断言能渲染出内容。
 *
 * ## 覆盖范围
 *
 * 只做「挂载 + 渲染出内容」断言，不校验像素或运行结果：jsdom 不实现 canvas，
 * `getContext('2d')` 恒为 null。能抓到的是 import 错误、模板语法破坏、
 * setup 阶段抛错、组件缺失 —— 重构里最容易改坏的那几类。

    // 显式 instant 让路由跳转瞬时归位，平滑只留给页内锚点。
    if (savedPosition) return { ...savedPosition, behavior: 'instant' }
    await new Promise((resolve) => requestAnimationFrame(resolve))
    return { top: 0, behavior: 'instant' }
  },

  html {
    scroll-behavior: smooth;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
  }

 * 这里先拦一道并给中文提示，文案与项目其他颜色工具（ColorConverterPage / ColorHarmonyPage）保持一致。
 * 复用 color-tools 的 hexToRgb（3 位 / 6 位、可带 #），避免另写一套正则。
 */
const validateColors = (): boolean => {
  if (!hexToRgb(fgColor.value)) {
    setError('无法识别的颜色格式，前景色请输入 #RGB 或 #RRGGBB')
    return false
  }
  if (!hexToRgb(bgColor.value)) {
    setError('无法识别的颜色格式，背景色请输入 #RGB 或 #RRGGBB')
    return false
  }
  return true

// 检测动态 import 失败（如部署后旧 chunk 失效），自动刷新页面。
// **报告 #6 修复**：用 sessionStorage 持久化重试状态，避免持续失败场景下无限 reload 循环。
// 同一来源（pathname）10 分钟内最多自动 reload 1 次；超限后保留在错误态，由用户手动刷新。
const RELOAD_DEDUPE_KEY = 'tools:chunk-reload-dedupe'
const RELOAD_DEDUPE_WINDOW_MS = 10 * 60 * 1000

const shouldAutoReload = (): boolean => {
  if (typeof window === 'undefined') return false
  const last = Number(window.sessionStorage.getItem(RELOAD_DEDUPE_KEY) ?? 0)
  return !Number.isFinite(last) || last === 0 || Date.now() - last > RELOAD_DEDUPE_WINDOW_MS
}

  // 只保留真正的超时定时器（previewMessageTimer）。
  // 历史 bug（报告 #7）：原实现另设 `loadingStateTimer`，在 `loadingIndicatorDelayMs`
  // 后无条件把 `isRunning` 置为 false。但 React/TS 加载 vendor（~9.4MB）+ 编译远超 400ms，
  // 期间运行按钮（`:disabled="isRunning"`）会提前可点，用户连点即叠加多次运行。
  // 现在 isRunning 仅由「收到 ready/error 消息」「超时」「主动取消/清空」终止；
  // 加载指示的视觉延迟如有需要可由调用方在 UI 层另实现。
  let previewMessageTimer: ReturnType<typeof setTimeout> | null = null

/**
 * 在 DOM 节点上为 <a> 合并补全 `rel="noopener noreferrer"`，防止钓鱼和反向 tabnabbing。
 *
 * **报告 #10 修复**：原实现是「DOMPurify 输出字符串后用正则二次改写 HTML」——
 * HTML 序列化时属性值里的 `>` 不会被转义（只转义 `&` 和 `"`），因此
 * `<a title="a>b" href="/x">` 会被 `<a\b([^>]*)>` 在 `>` 处截断，生成畸形标签；
 * 再次插入 innerHTML 时可能产生意外的属性解析。改为在 DOM 节点上操作，
 * 再序列化输出，彻底避免「用正则解析 HTML」。
 *
 * SSR / 非 DOM 环境降级为 noop（保持原 dirty）。
 */