cardbuddy 0.7.0 → 0.9.0

package/dist/server-core/logStream.js

@@ -0,0 +1,275 @@
+/**
+ * server/core/logStream.js
+ * 服务进程日志流：终端输出镜像 + 环形缓冲 + 订阅推送，供编辑器底部「服务日志」面板实时消费。
+ *
+ * 为什么镜像 stdout/stderr 而不是只挂 logger.js：
+ *  - logger.js 的 emit() 只覆盖 log.info/ok/warn/error；server/core 里仍有直接 console.*
+ *    （renderStatus / cardSave / cardHistory），第三方依赖（vite SSR、playwright、chokidar）
+ *    与 Node 自身的告警也只写 stdout/stderr。镜像 write() 才能拿到「终端上看到的同一份内容」。
+ *  - 镜像保留原始 ANSI（chalk 真彩 38;2;r;g;b），前端解析后即可 1:1 还原终端配色，
+ *    包括 logger.js 的 box() / rule() 框线；不做服务端转 HTML，避免把展示逻辑沉到后端。
+ *
+ * 数据形态：每条 = { seq, t, text }
+ *  - seq：进程内单调递增序号。前端断线重连后可用 GET /__logs?since=<seq> 精确补齐缺口，
+ *    不必重拉整段历史。
+ *  - t：服务端收到该行的时间（epoch ms）。logger 行自带 HH:MM:SS.mmm，但 console.* 与
+ *    第三方输出没有，统一补一个接收时刻便于排序与展示。
+ *  - text：原始行内容（含 ANSI，已去掉行尾 \r）。
+ *
+ * 端点（见 createLogMiddleware，随 mountCoreMiddlewares 一起挂载）：
+ *  - GET  /__logs?limit=300&since=<seq> → { ok, enabled, startedAt, pid, seq, dropped, lines }
+ *  - POST /__logs/ingest  body { text } → 外部进程（如启动器 tools/dev.mjs）注入日志行
+ * 实时推送复用 cardbuddy 既有的 SSE hub：standalone.js 里 subscribeLog() → notify({lines}, 'service-log')。
+ *
+ * 开关与安全：
+ *  - CARDBUDDY_STREAM_LOGS=0 完全关闭（不镜像、端点返回 enabled:false）。
+ *  - 服务只绑 127.0.0.1，但 CORS 反射任意来源，日志比卡片列表更敏感（远端地址、错误栈、cardId）；
+ *    logger.js 的 redact() 已对大段正文脱敏，配置了 DSL_DEV_TOKEN 时 /__logs 与其它 API 一样受
+ *    tokenMiddleware 保护（EventSource 不能带 header，故 SSE 侧支持 ?token= 查询参数）。
+ *
+ * 稳健性铁律：镜像与推送都包在 try/catch 里，任何异常都不得影响原始 write() 与主流程。
+ */
+
+/** 环形缓冲上限（条）。800 行 × 约 200 字符 ≈ 160KB 常驻，足够回溯一次操作链。 */
+const MAX_LINES = Number(process.env.CARDBUDDY_LOG_BUFFER || 800)
+/** 单行长度上限：超长行（如整段 JSON dump）截断，避免一行吃掉整个缓冲。 */
+const MAX_LINE_CHARS = 4000
+/** 批量推送间隔（ms）：合并同一轮操作的多行，避免 SSE 逐行刷屏。 */
+const FLUSH_MS = 100
+/** 批量条数阈值：突发日志（截图 / 批量校验）达到即立刻推，不等定时器。 */
+const FLUSH_BATCH = 40
+/** /__logs/ingest 请求体上限（字节）。 */
+const MAX_BODY = 256 * 1024
+/** 未换行的残留缓冲上限：进度条类输出（只有 \r 没有 \n）不会无限堆积。 */
+const MAX_PARTIAL = 8000
+
+/** 是否启用日志流（进程启动时定一次，运行期不切换）。 */
+export const logStreamEnabled = process.env.CARDBUDDY_STREAM_LOGS !== '0'
+
+/** @type {{ seq: number, t: number, text: string }[]} */
+const buffer = []
+/** 因缓冲上限被淘汰的行数（前端据此提示「仅保留最近 N 行」）。 */
+let dropped = 0
+/** 已分配的最大 seq（0 表示尚无日志）。 */
+let lastSeq = 0
+const startedAt = Date.now()
+
+/** @type {Set<(lines: {seq:number,t:number,text:string}[]) => void>} */
+const subscribers = new Set()
+/** @type {{seq:number,t:number,text:string}[]} */
+let pending = []
+let flushTimer = null
+
+function flush() {
+  if (flushTimer) {
+    clearTimeout(flushTimer)
+    flushTimer = null
+  }
+  if (!pending.length) return
+  const batch = pending
+  pending = []
+  for (const cb of subscribers) {
+    try {
+      cb(batch)
+    } catch {
+      /* 单个订阅者异常不影响其它订阅者与主流程 */
+    }
+  }
+}
+
+function scheduleFlush() {
+  if (pending.length >= FLUSH_BATCH) return flush()
+  if (!flushTimer) flushTimer = setTimeout(flush, FLUSH_MS)
+}
+
+/** 归一化并收纳一行；返回入库的记录（未启用时返回 null）。 */
+function record(line) {
+  if (!logStreamEnabled) return null
+  let text = String(line).replace(/\r$/, '')
+  if (!text) return null
+  if (text.length > MAX_LINE_CHARS) text = text.slice(0, MAX_LINE_CHARS) + '…(truncated)'
+  const entry = { seq: ++lastSeq, t: Date.now(), text }
+  buffer.push(entry)
+  if (buffer.length > MAX_LINES) {
+    dropped += buffer.length - MAX_LINES
+    buffer.splice(0, buffer.length - MAX_LINES)
+  }
+  pending.push(entry)
+  scheduleFlush()
+  return entry
+}
+
+/**
+ * 注入一行日志（镜像与 ingest 端点共用入口）。
+ * @param {string} line
+ */
+export function pushLogLine(line) {
+  try {
+    return record(line)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 注入一段可能含多行的文本（ingest 端点 / 外部进程转发用）。
+ * @param {string} text
+ * @returns {number} 实际入库行数
+ */
+export function pushLogText(text) {
+  const raw = String(text || '')
+  if (!raw) return 0
+  let n = 0
+  for (const line of raw.split('\n')) if (record(line)) n++
+  return n
+}
+
+/**
+ * 取历史快照。
+ * @param {{ limit?: number, since?: number }} [opts]
+ *   - since：只返回 seq > since 的行（断线补漏）；
+ *   - limit：最多返回多少行（默认 300，取最新的）。
+ */
+export function getLogSnapshot({ limit = 300, since = 0 } = {}) {
+  const max = Math.max(1, Math.min(MAX_LINES, Number(limit) || 300))
+  const from = Number(since) || 0
+  const rows = from > 0 ? buffer.filter((e) => e.seq > from) : buffer
+  const lines = rows.length > max ? rows.slice(rows.length - max) : rows
+  return {
+    ok: true,
+    enabled: logStreamEnabled,
+    startedAt,
+    pid: process.pid,
+    seq: lastSeq,
+    dropped,
+    buffered: buffer.length,
+    truncated: rows.length > lines.length,
+    lines,
+  }
+}
+
+/** 清空缓冲（面板「清空」可选调用；seq 不回退，since 语义保持单调）。 */
+export function clearLogBuffer() {
+  buffer.length = 0
+  pending = []
+  dropped = 0
+}
+
+/**
+ * 订阅新日志（批量回调）。
+ * @param {(lines: {seq:number,t:number,text:string}[]) => void} cb
+ * @returns {() => void} 取消订阅
+ */
+export function subscribeLog(cb) {
+  if (typeof cb !== 'function') return () => {}
+  subscribers.add(cb)
+  return () => subscribers.delete(cb)
+}
+
+/** 当前订阅者数量（诊断用）。 */
+export function logSubscriberCount() {
+  return subscribers.size
+}
+
+let mirrorInstalled = false
+
+/**
+ * 镜像本进程 stdout/stderr 到日志流。幂等；CLI 入口尽早调用即可覆盖启动期日志。
+ *
+ * 实现要点：
+ *  - 包装 write() 而非监听 'data'：后者只在管道/TTY 的可读侧成立，且拿不到本进程自己的写入。
+ *  - 按 \n 切行并保留跨 chunk 的半行（partial）；一行日志可能被拆成多个 chunk 写入。
+ *  - 纯 \r 刷新（进度条）不产行，partial 超过 MAX_PARTIAL 时强制截断入库，防止无界增长。
+ *  - 原始 write() 一定被调用并原样返回，镜像失败也不影响终端输出。
+ */
+export function installLogMirror() {
+  if (mirrorInstalled || !logStreamEnabled) return false
+  mirrorInstalled = true
+  for (const stream of [process.stdout, process.stderr]) {
+    if (!stream || typeof stream.write !== 'function') continue
+    const original = stream.write.bind(stream)
+    let partial = ''
+    stream.write = function patchedWrite(chunk, ...rest) {
+      try {
+        const text = typeof chunk === 'string' ? chunk : Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk)
+        partial += text
+        let idx
+        while ((idx = partial.indexOf('\n')) >= 0) {
+          const line = partial.slice(0, idx)
+          partial = partial.slice(idx + 1)
+          record(line)
+        }
+        // 只允许最后一个 \r 之后的内容作为「当前进度行」留存，其余直接丢弃并记一行，
+        // 避免进度条把 partial 撑爆（同时保留最终状态可见）。
+        const cr = partial.lastIndexOf('\r')
+        if (cr >= 0) partial = partial.slice(cr + 1)
+        if (partial.length > MAX_PARTIAL) {
+          record(partial.slice(0, MAX_PARTIAL))
+          partial = ''
+        }
+      } catch {
+        /* 镜像绝不抛出：日志流故障不能拖垮服务 */
+      }
+      return original(chunk, ...rest)
+    }
+  }
+  return true
+}
+
+/**
+ * 日志流 HTTP 端点：GET /__logs（历史/补漏）、POST /__logs/ingest（外部进程注入）。
+ * 挂在 mountCoreMiddlewares 里，因此 Vite 插件形态与 cardbuddy 独立服务形态同时可用。
+ */
+export function createLogMiddleware() {
+  const sendJson = (res, status, payload) => {
+    res.statusCode = status
+    res.setHeader('Content-Type', 'application/json')
+    res.setHeader('Cache-Control', 'no-store')
+    res.end(JSON.stringify(payload))
+  }
+
+  const readBody = (req, limit = MAX_BODY) =>
+    new Promise((resolve, reject) => {
+      let body = ''
+      req.on('data', (c) => {
+        body += c
+        if (body.length > limit) {
+          reject(new Error('body too large'))
+          req.destroy()
+        }
+      })
+      req.on('end', () => resolve(body))
+      req.on('error', reject)
+    })
+
+  return async function logMiddleware(req, res, next) {
+    const raw = (req.url || '').split('?')[0]
+    if (raw !== '/__logs' && raw !== '/__logs/ingest') return next()
+    const method = (req.method || 'GET').toUpperCase()
+
+    if (raw === '/__logs' && method === 'GET') {
+      if (!logStreamEnabled) return sendJson(res, 200, { ok: true, enabled: false, lines: [] })
+      const q = new URLSearchParams((req.url || '').split('?')[1] || '')
+      return sendJson(
+        res,
+        200,
+        getLogSnapshot({ limit: Number(q.get('limit')) || 300, since: Number(q.get('since')) || 0 })
+      )
+    }
+
+    if (raw === '/__logs/ingest' && method === 'POST') {
+      if (!logStreamEnabled) return sendJson(res, 200, { ok: true, enabled: false, accepted: 0 })
+      let payload
+      try {
+        payload = JSON.parse((await readBody(req)) || '{}')
+      } catch {
+        return sendJson(res, 400, { ok: false, error: 'invalid json' })
+      }
+      const text = typeof payload.text === 'string' ? payload.text : ''
+      const accepted = pushLogText(text)
+      return sendJson(res, 200, { ok: true, accepted, seq: lastSeq })
+    }
+
+    return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+  }
+}

package/dist/standalone.js

@@ -22,7 +22,7 @@ import vue from '@vitejs/plugin-vue'
 import chokidar from 'chokidar'
 import chalk from 'chalk'
 
-import { mountCoreMiddlewares } from './core.js'
+import { mountCoreMiddlewares, installLogMirror, subscribeLog } from './core.js'
 import { loadConfig } from './config.js'
 
 const MIME_TYPES = {
@@ -259,11 +259,17 @@ function corsMiddleware(req, res, next) {
   next()
 }
 
-/** 可选 token 鉴权。 */
+/**
+ * 可选 token 鉴权。
+ * 浏览器原生 EventSource 无法自定义请求头，故 SSE（/__events，服务日志与卡片变更推送都走它）
+ * 额外允许经查询参数携带：?token=<t>（别名 ?access_token=<t>）。其余端点仍以 header 为准。
+ */
 function tokenMiddleware(token) {
   return (req, res, next) => {
     if (req.method === 'OPTIONS') return next()
-    if (req.headers['x-dev-token'] !== token) {
+    const query = new URLSearchParams((req.url || '').split('?')[1] || '')
+    const provided = req.headers['x-dev-token'] || query.get('token') || query.get('access_token')
+    if (provided !== token) {
       res.statusCode = 403
       res.setHeader('Content-Type', 'application/json')
       return res.end(JSON.stringify({ error: 'invalid x-dev-token' }))
@@ -290,8 +296,8 @@ function createEventsEndpoint() {
       clients.delete(res)
     })
   }
-  const notify = (data) => {
-    const payload = `event: cards-changed\ndata: ${JSON.stringify(data)}\n\n`
+  const notify = (data, event = 'cards-changed') => {
+    const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
     for (const res of clients) res.write(payload)
   }
   return { handler, notify }
@@ -395,9 +401,30 @@ export async function startServer(userConfig = {}) {
   const events = createEventsEndpoint()
   app.use(events.handler)
 
+  // 服务日志流：镜像本进程 stdout/stderr（含 chalk ANSI）→ 环形缓冲 → SSE 批量推送。
+  // 编辑器底部「服务日志」面板订阅 event: service-log；历史与断线补漏走 GET /__logs。
+  // installLogMirror 幂等，CLI 入口已先行安装，这里兜住以编程方式调用 startServer 的场景。
+  installLogMirror()
+  subscribeLog((lines) => events.notify({ lines }, 'service-log'))
+
   const vite = await createEmbeddedVite(config)
   // upstream（FINMALL_BASE_URL）透传给资源代理中间件，使其能回源 FinMall 取站内资源
-  mountCoreMiddlewares(app, { root: config.root, viteServer: vite, upstream: config.upstream })
+  mountCoreMiddlewares(app, {
+    root: config.root,
+    viteServer: vite,
+    upstream: config.upstream,
+    notify: events.notify,
+    // 代码桥单文件监听注入 chokidar 版：原子保存（改名覆盖）由 add 兜住，awaitWriteFinish 防半截读
+    watchFile: (file, onChange) => {
+      const watcher = chokidar.watch(file, {
+        ignoreInitial: true,
+        awaitWriteFinish: { stabilityThreshold: 120, pollInterval: 40 },
+      })
+      watcher.on('change', onChange)
+      watcher.on('add', onChange)
+      return watcher
+    },
+  })
 
   watchCards(config.root, events.notify)
 

package/dist/vendored/App.vue

@@ -328,7 +328,9 @@
         </div>
       </div>
 
-      <!-- 拖拽分隔条：位于预览列与操作面板之间，拖动调整预览宽度（手机自动缩放填充） -->
+
+      <!-- 左分隔条：预览列 | 工作区 接缝。底面板 / 状态栏的左缘即此缝（随预览宽度联动），
+           故定位在 .app__stage 通到底部，全程可拖；右分隔条才收进两栏容器内。 -->
       <div
         v-show="!chromeOff"
         class="splitter"
@@ -337,22 +339,24 @@
         title="拖拽调整预览区域宽度"
       ></div>
 
-      <!-- 拖拽分隔条：位于调试面板与右侧「接口调用」面板之间，拖动调整右栏宽度。
-           约束：中栏（调试面板）最小宽度 ≥ 屏宽 1/3，右栏最小宽度 ≥ 320px（见 startApiDrag） -->
-      <div
-        v-show="!chromeOff && apiPanelOpen"
-        class="splitter splitter--api"
-        :class="{ 'is-dragging': apiDragging }"
-        @mousedown.prevent="startApiDrag"
-        title="拖拽调整接口调用面板宽度"
-      ></div>
-
       <!-- 中右工作区：上为「调试面板 + 接口调用面板」两栏，下为贯穿两栏的共同状态栏。
-           状态栏由 DebugPanel 内 Teleport 注入 #app-workside-bar；Teleport 目标须在 DOM 中
-           先于面板挂载，故 .workside__bar 写在前面，以 flex order 视觉置底。 -->
+           状态栏与底部弹出面板（运行态 / 事件 / 变量绑定）均由 DebugPanel 内 Teleport 注入
+           #app-workside-bar / #app-workside-panels，宽度贯穿中右两栏；Teleport 目标须在 DOM 中
+           先于面板挂载，故两个空容器写在前面，以 flex order 视觉置底。 -->
       <div class="workside" v-show="!chromeOff">
         <div id="app-workside-bar" class="workside__bar"></div>
+        <div id="app-workside-panels" class="workside__panels"></div>
         <div class="workside__cols">
+          <!-- 拖拽分隔条：置于两栏容器内（定位上下文），只贯穿列区高度，不穿过底部弹出面板与状态栏 -->
+          <!-- 中右分隔条：调试面板 | 接口调用面板 接缝，拖动调整右栏宽度。
+               约束：中栏最小宽度 ≥ 屏宽 1/3，右栏最小宽度 ≥ 320px（见 startApiDrag） -->
+          <div
+            v-show="!chromeOff && apiPanelOpen"
+            class="splitter splitter--api"
+            :class="{ 'is-dragging': apiDragging }"
+            @mousedown.prevent="startApiDrag"
+            title="拖拽调整接口调用面板宽度"
+          ></div>
           <DebugPanel
             :chrome-off="chromeOff"
             :rt="rt"
@@ -379,6 +383,7 @@
             :dev-svc-class="devSvcClass"
             :dev-svc-title="devSvcTitle"
             :dev-svc-label="devSvcLabel"
+            :dev-svc-conn="devSvcConn"
           />
 
           <!-- 右侧常驻「接口调用」面板：与预览列 / 调试面板呈左中右布局，
@@ -399,8 +404,9 @@
       @close="remotePreviewOpen = false"
     />
     <!-- 登录凭据弹窗：远程同步检测到缺凭据时弹出，填写账号密码（MD5 后）写入 .local/credentials.json -->
+    <Transition name="modal">
     <div v-if="loginModal" class="login-mask" @click.self="closeLoginModal">
-      <div class="login-modal" role="dialog" aria-modal="true">
+      <div class="login-modal modal-card" role="dialog" aria-modal="true">
         <div class="login-modal__title">FinMall 登录凭据</div>
         <div class="login-modal__desc">
           本地登录凭据缺失，请填写账号与密码。密码仅做 MD5 后保存，不落明文。
@@ -448,12 +454,15 @@
         </div>
       </div>
     </div>
+    </Transition>
     <!-- 组件选择面板：点击结构树每行的「＋」后弹出，选择类型即插入对应节点 -->
-    <ComponentPalette
-      v-if="addNodePanelOpen"
-      @pick="onPickComponent"
-      @close="cancelAddNode"
-    />
+    <Transition name="modal">
+      <ComponentPalette
+        v-if="addNodePanelOpen"
+        @pick="onPickComponent"
+        @close="cancelAddNode"
+      />
+    </Transition>
     <!-- 二次确认弹窗：版本推送 / 当前同步 / 全量同步 等写/覆盖类操作前弹出，确认后才执行 -->
     <ConfirmDialog
       :visible="confirm.show"

package/dist/vendored/ansi.js

@@ -0,0 +1,185 @@
+/**
+ * preview/ansi.js
+ * 终端 ANSI 转义 → HTML 的最小解析器，供底部「服务日志」面板 1:1 还原 cardbuddy 终端配色。
+ *
+ * 为什么自己写而不引 ansi_up / ansi-to-html：
+ *  - 只需覆盖本项目实际产出的子集：chalk 的真彩 SGR（38;2;r;g;b）、256 色（38;5;n）、
+ *    基础 8/16 色、粗体/暗淡/斜体/下划线，以及需要丢弃的 CSI 擦除类与 OSC 序列；
+ *  - 零依赖、零体积负担，且输出形态可控（style 内联 + 语义 class），便于与主题令牌对齐；
+ *  - 解析器行为可单测（tools/tests/ansi.test.mjs），不受第三方版本变更影响。
+ *
+ * 安全：所有文本片段先做 HTML 转义再拼接，样式值只来自白名单数字（RGB 分量 / 关键字），
+ * 不存在把日志内容当 HTML 注入的路径（v-html 消费本模块输出）。
+ */
+
+/** 匹配一段 ANSI 转义：CSI 序列 / OSC 序列 / 双字符 ESC 序列。 */
+const ANSI_RE =
+  // eslint-disable-next-line no-control-regex
+  /\x1b\[[0-9;:?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g
+
+/** 去掉全部 ANSI 转义，得到纯文本（用于复制、搜索、宽度计算）。 */
+export function stripAnsi(input) {
+  return String(input == null ? '' : input).replace(ANSI_RE, '')
+}
+
+/** 基础 8 色（xterm 常规档），与终端默认调色板一致的近似值。 */
+const BASIC = [
+  [0, 0, 0],
+  [170, 0, 0],
+  [0, 170, 0],
+  [170, 85, 0],
+  [0, 0, 170],
+  [170, 0, 170],
+  [0, 170, 170],
+  [170, 170, 170],
+]
+/** 高亮 8 色（bold / 90-97 使用）。 */
+const BRIGHT = [
+  [85, 85, 85],
+  [255, 85, 85],
+  [85, 255, 85],
+  [255, 255, 85],
+  [85, 85, 255],
+  [255, 85, 255],
+  [85, 255, 255],
+  [255, 255, 255],
+]
+
+function clamp255(n) {
+  const v = Math.round(Number(n))
+  if (!Number.isFinite(v)) return 0
+  return v < 0 ? 0 : v > 255 ? 255 : v
+}
+
+/** 256 色索引 → RGB（0-7 基础 / 8-15 高亮 / 16-231 6×6×6 立方 / 232-255 灰阶）。 */
+export function color256(n) {
+  const i = clamp255(n)
+  if (i < 8) return BASIC[i]
+  if (i < 16) return BRIGHT[i - 8]
+  if (i < 232) {
+    const k = i - 16
+    const step = (v) => (v ? v * 40 + 55 : 0)
+    return [step(Math.floor(k / 36)), step(Math.floor((k % 36) / 6)), step(k % 6)]
+  }
+  const g = 8 + (i - 232) * 10
+  return [g, g, g]
+}
+
+function escapeHtml(s) {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+function rgbCss(rgb) {
+  return `rgb(${rgb[0]},${rgb[1]},${rgb[2]})`
+}
+
+/** 新建一份 SGR 状态（全部为默认值）。 */
+function newState() {
+  return { fg: null, bg: null, bold: false, dim: false, italic: false, underline: false }
+}
+
+function isDefault(st) {
+  return !st.fg && !st.bg && !st.bold && !st.dim && !st.italic && !st.underline
+}
+
+/** 按状态生成 style 串；默认态返回空串（调用方据此决定是否包 span）。 */
+function styleOf(st) {
+  const parts = []
+  // 终端惯例：粗体 + 基础色 → 走高亮档，还原 chalk.magenta.bold 之类的观感
+  let fg = st.fg
+  if (fg && fg.basic != null) fg = { rgb: st.bold ? BRIGHT[fg.basic] : BASIC[fg.basic] }
+  if (fg) parts.push(`color:${rgbCss(fg.rgb)}`)
+  if (st.bg) parts.push(`background-color:${rgbCss(st.bg.rgb)}`)
+  if (st.bold) parts.push('font-weight:600')
+  if (st.dim) parts.push('opacity:.72')
+  if (st.italic) parts.push('font-style:italic')
+  if (st.underline) parts.push('text-decoration:underline')
+  return parts.join(';')
+}
+
+/**
+ * 解析一段 SGR 参数（`\x1b[<params>m` 里的 params），就地修改状态。
+ * 支持：0 重置、1/2/3/4 与 22/23/24 关闭、30-37/90-97 前景、40-47/100-107 背景、
+ * 39/49 默认前景背景、38;5;n 与 38;2;r;g;b（含 48 背景版、冒号分隔变体）。
+ */
+function applySgr(state, paramStr) {
+  const raw = String(paramStr || '')
+  // 冒号变体（38:2::r:g:b / 38:5:n）统一按分号处理，ITU-T T.416 形式在本项目不出现，取近似即可
+  const codes = (raw === '' ? '0' : raw).split(/[;:]/).map((c) => (c === '' ? 0 : Number(c)))
+  for (let i = 0; i < codes.length; i++) {
+    const c = codes[i]
+    if (!Number.isFinite(c)) continue
+    if (c === 0) {
+      Object.assign(state, newState())
+    } else if (c === 1) state.bold = true
+    else if (c === 2) state.dim = true
+    else if (c === 3) state.italic = true
+    else if (c === 4) state.underline = true
+    else if (c === 22) {
+      state.bold = false
+      state.dim = false
+    } else if (c === 23) state.italic = false
+    else if (c === 24) state.underline = false
+    else if (c === 39) state.fg = null
+    else if (c === 49) state.bg = null
+    else if (c >= 30 && c <= 37) state.fg = { basic: c - 30 }
+    else if (c >= 90 && c <= 97) state.fg = { rgb: BRIGHT[c - 90] }
+    else if (c >= 40 && c <= 47) state.bg = { basic: c - 40 }
+    else if (c >= 100 && c <= 107) state.bg = { rgb: BRIGHT[c - 100] }
+    else if (c === 38 || c === 48) {
+      const mode = codes[i + 1]
+      let rgb = null
+      let consumed = 0
+      if (mode === 5) {
+        rgb = color256(codes[i + 2])
+        consumed = 2
+      } else if (mode === 2) {
+        rgb = [clamp255(codes[i + 2]), clamp255(codes[i + 3]), clamp255(codes[i + 4])]
+        consumed = 4
+      }
+      if (rgb) {
+        if (c === 38) state.fg = { rgb }
+        else state.bg = { rgb }
+        i += consumed
+      }
+    }
+    // 其余（5 闪烁 / 7 反显 / 9 删除线 …）本项目不产出，忽略即可
+  }
+}
+
+/**
+ * 单行 ANSI → HTML。
+ * @param {string} line 原始行（可含 ANSI）
+ * @returns {string} 转义后的 HTML（默认态文本不包 span，避免无谓节点）
+ */
+export function ansiToHtml(line) {
+  const text = String(line == null ? '' : line)
+  if (!text) return ''
+  if (text.indexOf('\x1b') < 0) return escapeHtml(text)
+  const state = newState()
+  let out = ''
+  let last = 0
+  let m
+  ANSI_RE.lastIndex = 0
+  while ((m = ANSI_RE.exec(text)) !== null) {
+    if (m.index > last) {
+      out += renderSegment(text.slice(last, m.index), state)
+    }
+    last = m.index + m[0].length
+    const seq = m[0]
+    // 只处理 SGR（…m）；CSI 擦除/光标类与 OSC 一律丢弃（浏览器面板里没有光标语义）
+    if (seq[1] === '[' && /[m]$/.test(seq)) applySgr(state, seq.slice(2, -1))
+  }
+  if (last < text.length) out += renderSegment(text.slice(last), state)
+  return out
+}
+
+function renderSegment(chunk, state) {
+  if (!chunk) return ''
+  const esc = escapeHtml(chunk)
+  if (isDefault(state)) return esc
+  const style = styleOf(state)
+  return style ? `<span style="${style}">${esc}</span>` : esc
+}
+
+export default ansiToHtml