\n```\n\n当你想要和 `chat` 相同的轻量默认值，但当前页面不是聊天语义时，可以使用 `mode=\"minimal\"`。在 Vue 3（含 Nuxt）中，`smooth-streaming` 控制出字节奏，`fade` 控制透明度，两者可以同时开启。`mode=\"chat\"` 保留 `fade=false` 作为轻量默认值；需要文字渐显时添加 `fade`，更看重动画成本时保持关闭。\n同一条聊天消息不要仅因为 `final` 变为 `true` 就从 `mode=\"chat\"` 切到 `mode=\"docs\"`。保持 mode 稳定，只切换 `smooth-streaming`、`typewriter`、`fade` 等节奏/动画 props；`docs` 会改变布局策略。\n如果某个渲染面不需要增强代码块，建议设置 `:render-code-blocks-as-pre=\"true\"`；如果需要富 `CodeBlockNode` UI 与 File/Diff 渲染，请安装 `stream-diffs`，否则渲染器会按设计降级为 `` 渲染。如果应用要完全接管普通 fenced code，用 `setCustomComponents` 注册带作用域的 `code_block`。\n`stream-diffs` 是与框架无关的 DOM runtime；由 `CodeBlockNode` 决定何时把流式 `` 切换为最终的 File 或 FileDiff surface。\n\n使用顶层 `code-block-options` 配置内置 surface；直接使用 `CodeBlockNode` 时接收同一个 `codeBlockOptions` object。六个框架 adapter 共享 `CodeBlockOptions`。它包含宿主管理的排版/布局字段（`fontSize`、`lineHeight`、`fontFamily`、number 类型且单位为 px 的 `maxHeight`、number 类型且单位为 px 的上下对称 `padding`、`tabSize`），以及受支持的 File/FileDiff、交互、annotation 与 callback 字段。主题、code/language、流式状态、header、挂载、显示与释放仍由宿主管理。\n\n渲染器的 CSS 会作用于内部 `.markstream-vue` 容器下，以尽量降低对全局的影响；如果你脱离 `MarkdownRender` 单独使用导出的节点组件，请在外层包一层带 `markstream-vue` 类名的容器。\n\n暗色变量可以通过给祖先节点加 `.dark`，或直接给 `MarkdownRender` 传入 `:is-dark=\"true\"`（仅对渲染器生效）。\n\n新的接入建议优先使用统一代码块 `theme` prop。如果你是通过 `MarkdownRender` 统一下发，可以放到 `code-block-props`：\n\n```vue\n\n```\n\n主题值使用已注册名称：直接 `CodeBlockNode.theme` 接收固定 string 或 `{ dark, light }`，`themes` 是要加载的 `[dark, light]` 对。旧 Monaco JSON theme object 不会直接改名；先调用 `stream-diffs/pierre` 的 `registerCustomTheme`，再传入注册名称。\n\n`code-block-props` 只会透传面向用户的代码块 props；`node`、`key`、`ref`、`ctx`、`renderNode`、`indexKey`、`__proto__`、`prototype`、`constructor` 等渲染器结构字段会被忽略。\n\n语言图标默认使用内置的 `material` theme。新接入建议在 `app.mount()` 之前通过导出的 helper 查看或切换 icon theme。旧的 `app.use(VueRendererMarkdown, { iconTheme })` 选项在 1.x 仍可用，但它会修改进程级全局状态，因此优先使用 helper。\n\n```ts\nimport { getRegisteredThemes, setIconTheme } from 'markstream-vue'\n\nconsole.log(getRegisteredThemes()) // ['material']\nsetIconTheme('material')\n```\n\n如果你需要接自己的图标包，可以继续使用 `registerIconTheme()` 注册。\n\n按需启用重型依赖：\n\n```ts\nimport { enableKatex, enableMermaid } from 'markstream-vue'\nimport 'markstream-vue/index.css'\nimport 'katex/dist/katex.min.css'\n\n// 安装对应 peer 后再启用\nenableMermaid()\nenableKatex()\n```\n\n\n可选：CDN Worker（KaTeX / Mermaid）
\n\n如果你是用 CDN 引入 KaTeX，并且希望公式在 Web Worker 中渲染（不打包 / 不安装可选 peer），可以注入一个“CDN 加载 KaTeX”的 worker：\n\n```ts\nimport { createKaTeXWorkerFromCDN, setKaTeXWorker } from 'markstream-vue'\n\nconst { worker } = createKaTeXWorkerFromCDN({\n mode: 'classic',\n // worker 内通过 importScripts() 加载的 UMD 构建\n katexUrl: 'https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.js',\n mhchemUrl: 'https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/contrib/mhchem.min.js',\n})\n\nif (worker)\n setKaTeXWorker(worker)\n```\n\n如果你是用 CDN 引入 Mermaid，并且希望 Mermaid 的解析在 worker 中进行（用于渐进式 Mermaid 渲染的后台解析），可以注入 Mermaid parser worker：\n\n```ts\nimport { createMermaidWorkerFromCDN, setMermaidWorker } from 'markstream-vue'\n\nconst { worker } = createMermaidWorkerFromCDN({\n // Mermaid CDN 构建通常是 ESM，推荐 module worker。\n mode: 'module',\n workerOptions: { type: 'module' },\n mermaidUrl: 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs',\n})\n\nif (worker)\n setMermaidWorker(worker)\n```\n\n \n\n\nNuxt 快速接入
\n\n```ts\n// plugins/markstream-vue.client.ts\nimport { defineNuxtPlugin } from '#app'\nimport MarkdownRender from 'markstream-vue'\nimport 'markstream-vue/index.css'\n\nexport default defineNuxtPlugin((nuxtApp) => {\n nuxtApp.vueApp.component('MarkdownRender', MarkdownRender)\n})\n```\n\n然后在页面中直接使用 ``。\n\n \n\n## 🛠️ 常用命令\n\n- `pnpm dev` — playground 开发\n- `pnpm play:nuxt` — Nuxt playground 开发\n- `pnpm build` — 构建库与 CSS\n- `pnpm build:analyze` — 带可视化报告的构建（输出 `bundle-visualizer.html`、`bundle-visualizer-tailwind.html`）\n- `pnpm size:check` — 本地执行 dist + npm 包体积预算检查（与 CI 一致）\n- `pnpm test` — Vitest 测试（快照用 `pnpm test:update`）\n- `pnpm typecheck` / `pnpm lint` — 类型检查与 Lint\n\n## ⏱️ 30 秒流式接入\n\n用 SSE / WebSocket 结合内置平滑节奏渲染 Markdown：\n\n```ts\nimport MarkdownRender from 'markstream-vue'\nimport { ref } from 'vue'\n\nconst content = ref('')\nconst final = ref(false)\n\neventSource.onmessage = (event) => {\n content.value += event.data\n}\neventSource.addEventListener('done', () => {\n final.value = true\n})\n\n// template\n// \n```\n\n`smooth-streaming` 在打字机/增量模式（`typewriter` 或 `max-live-nodes <= 0`）默认开启；如果希望严格按原始 chunk 节奏显示，可按实例设置 `:smooth-streaming=\"false\"`。\n\n按页面需要切换渲染风格：\n\n- 虚拟化窗口（默认）：长文档滚动平稳、内存稳定。\n- 增量批次：将 `:max-live-nodes=\"0\"`，获得更明显的“打字机”体验与轻量占位。\n\n\n进阶：SSR / Worker / 流式续写
\n\n### SSR / Worker（确定性输出）\n\n在服务端或 Worker 预解析 Markdown，前端直接渲染节点：\n\n```ts\n// server or worker\nimport { getMarkdown, parseMarkdownToStructure } from 'markstream-vue'\n\nconst md = getMarkdown()\nconst nodes = parseMarkdownToStructure('# Hello\\n\\n服务端解析一次', md)\n// 将 nodes JSON 下发到客户端\n```\n\n> 注意：`parseMarkdownToStructure` 默认是 `streamParse: 'auto'`：兼容的 `md` 实例会在非 final 顶层解析时使用 `md.stream.parse`，并保留最近一次 source/token cache。final 一次性解析默认走普通 parser；需要强制 stream 时传 `{ streamParse: true }`，需要关闭时传 `{ streamParse: false }`。如果复用同一个 `md` 解析互不相关的一次性文档，请传 `{ final: true }` 或 `{ streamParse: false }`。\n\n```vue\n\n\n```\n\n这样可以避免前端解析，保持 SSR/水合的一致性。\n\n### 混合模式：SSR + 流式续写\n\n- 服务端：解析首批 Markdown，序列化 `initialNodes`（以及 `initialMarkdown`，便于后续流式追加）。\n- 客户端：用相同的解析配置水合，然后继续流式追加：\n\n```ts\nimport type { ParsedNode } from 'markstream-vue'\nimport { getMarkdown, parseMarkdownToStructure } from 'markstream-vue'\nimport { ref } from 'vue'\n\nconst nodes = ref(initialNodes)\nconst buffer = ref(initialMarkdown)\nconst md = getMarkdown() // 与服务端保持一致\n\nfunction addChunk(chunk: string) {\n buffer.value += chunk\n nodes.value = parseMarkdownToStructure(buffer.value, md)\n}\n```\n\n这样无需重新解析 SSR 内容，同时还能通过 SSE/WebSocket 持续追加后续片段。\n\n> 提示：当你明确知道流已结束（消息已完整）时，建议用 `parseMarkdownToStructure(buffer.value, md, { final: true })` 或在组件上设置 `:final=\"true\"`，以关闭解析器的中间态（loading）策略，避免末尾残留分隔符（如 `$$`、未闭合 code fence）导致永久 loading。\n\n \n\n## ⚙️ 性能模式\n\n- **默认虚拟化窗口**：`docs` 模式的 `max-live-nodes` 默认值为 `220`，渲染器会立即渲染当前窗口的节点，同时只保留有限数量的 DOM 节点，实现平滑滚动与可控内存，占位骨架极少。\n- **增量流式模式**：当需要更明显的“打字机”体验时，将 `:max-live-nodes=\"0\"`。这会关闭虚拟化并启用 `batchRendering` 系列参数控制的增量渲染，新的节点会以小批次加上占位骨架的形式进入视图。\n\n可根据页面类型选择最合适的模式：虚拟化适合长文档/回溯需求，增量流式适合聊天或 AI 输出面板。\n\n> 小贴士：聊天场景可使用 `max-live-nodes=\"0\"`，并将 `renderBatchSize` 调小（如 `16`），`renderBatchDelay` 设为较小值（如 `8ms`），获得平滑的“打字”节奏且避免大段跳变。如需限制单帧 CPU，可适当调低 `renderBatchBudgetMs`。\n\n## 🧰 关键属性速览\n\n- `content` 与 `nodes`：传原始 Markdown 或预解析节点（来自 `parseMarkdownToStructure`）。\n- `max-live-nodes`：`docs` 模式默认为 `220`；`chat` / `minimal` 模式默认为 `0`。\n- `batchRendering`：用 `initialRenderBatchSize`、`renderBatchSize`、`renderBatchDelay`、`renderBatchBudgetMs` 微调批次。\n- `enableMermaid` / `enableKatex`：用于（重新）启用重型依赖或自定义 loader（可与 `disableMermaid` / `disableKatex` 配合）。\n- `parse-options`：在组件上复用解析钩子（如 `preTransformTokens`、`requireClosingStrong`）。\n- `final`：标记“最终态/流结束”，关闭中间态 loading 解析并强制收敛未闭合结构。\n- `custom-html-tags`：扩展流式 HTML 白名单并将这些标签输出为自定义节点，便于 `setCustomComponents` 直接映射（如 `['thinking']`）。\n 声明过的自定义节点会尽量让 `content`/`raw` 保留原始标签 payload，`children` 则仍作为富文本场景下的 Markdown 渲染结果。\n- `setCustomComponents(customId?, mapping)`：为自定义标签/标记注册内嵌 Vue 组件（传 `custom-id` 可限定作用域）。\n\n示例：将 Markdown 占位符映射到 Vue 组件（作用域）\n\n```ts\nimport { setCustomComponents } from 'markstream-vue'\n\nsetCustomComponents('docs', {\n CALLOUT: () => import('./components/Callout.vue'),\n})\n\n// Markdown: [[CALLOUT:warning title=\"提示\" body=\"具体内容\"]]\n```\n\n渲染时使用同一个 `custom-id`：\n\n```vue\n\n```\n\n解析钩子示例（服务端/客户端保持一致）：\n\n```vue\n tokens,\n }\"\n/>\n```\n\n## 🔥 适用场景\n\n- AI / 聊天界面：Markdown token 通过 SSE/WebSocket 持续抵达，要求无闪烁与稳定内存。\n- 文档、变更日志、知识库：需要即时加载，同时保持长内容滚动的流畅性。\n- 流式 diff / 代码审查：`stream-diffs` 增量更新让大代码块也能跟上变更。\n- 图表与示意：Mermaid 渐进式渲染，避免阻塞主渲染。\n- Markdown 驱动的界面中嵌入 Vue 组件（callout、交互式挂件、CTA 等）。\n\n## ❓ 快问快答\n\n- Mermaid / KaTeX 不显示？安装对应 peer（`mermaid` / `katex`），并传入 `:enable-mermaid=\"true\"` / `:enable-katex=\"true\"` 或调用 loader 设置函数。如果你是用 CDN `
![\"支付宝收款码\"](\"https://raw.githubusercontent.com/Simon-He95/markstream-vue/main/docs/public/sponsor/zhifubao.jpg\")
| ![\"微信收款码\"](\"https://raw.githubusercontent.com/Simon-He95/markstream-vue/main/docs/public/sponsor/weixin.jpg\")
|\n\n## ⚡ 快速上手\n\n### Vue / Nuxt\n\n2.x 稳定版已发布在 npm `latest`。基础 Markdown 只需要安装主包：\n\n```bash\npnpm add markstream-vue\n```\n\n需要增强代码块和 diff 时再安装 `stream-diffs`。从 1.x 升级前请阅读 [2.0 迁移指南](https://markstream.simonhe.me/zh/guide/migration-2-0)；如需继续锁定维护中的 1.x，请显式使用 `markstream-vue@1`。\n\n```bash\npnpm add markstream-vue@1\n```\n\n```vue\n\n\n\n