markstream-vue 1.0.1-beta.3 → 1.0.1-beta.4

package/README.md

@@ -161,6 +161,30 @@ Import `markstream-vue/index.css` after your reset (e.g., use `@import 'markstre
 For untrusted user-generated content, prefer `htmlPolicy="escape"` so raw HTML is rendered as text.
 If your app intentionally scales root font size on mobile, use `markstream-vue/index.px.css` to avoid `rem`-based global scaling side effects.
 
+Choose the renderer mode by surface:
+
+```vue
+<!-- AI chat / SSE output: steady pacing, no opacity animation flicker -->
+<MarkdownRender
+  mode="chat"
+  :content="message"
+  :final="isDone"
+  smooth-streaming="auto"
+  :fade="false"
+/>
+
+<!-- Rich docs: larger render batches, tooltips, and fade are enabled by default -->
+<MarkdownRender
+  mode="docs"
+  :content="doc"
+  :final="true"
+/>
+```
+
+Use `mode="minimal"` when you want the same lightweight defaults as `chat`, but prefer a neutral mode name for non-chat surfaces. Avoid combining high-frequency `smooth-streaming` with `fade`; it can turn a steady stream into repeated opacity restarts.
+For the same chat message, do not switch from `mode="chat"` to `mode="docs"` only because `final` changed. Keep the mode stable and switch pacing/animation props (`smooth-streaming`, `typewriter`, `fade`) instead; `docs` changes the default code renderer and layout strategy.
+For docs pages that do not need Monaco-backed code blocks, set `:render-code-blocks-as-pre="true"`. If you want the rich Monaco-backed code-block UI, install `stream-monaco`; otherwise the renderer intentionally falls back to `<pre>` rendering.
+
 Renderer CSS is scoped under an internal `.markstream-vue` container to minimize global style conflicts. If you render exported node components outside of `MarkdownRender`, wrap them in an element with class `markstream-vue`.
 
 For dark theme variables, either add a `.dark` class on an ancestor, or pass `:is-dark="true"` to `MarkdownRender` to scope dark mode to the renderer.
@@ -175,7 +199,7 @@ Prefer the unified code-block `theme` prop for new integrations. When you render
 />
 ```
 
-Language icons use the built-in `material` theme by default. Advanced integrations can inspect or switch icon themes with the exported helpers, or set an initial theme with `app.use(VueRendererMarkdown, { iconTheme })`:
+Language icons use the built-in `material` theme by default. For new integrations, inspect or switch icon themes with the exported helpers before `app.mount()`. The legacy `app.use(VueRendererMarkdown, { iconTheme })` option still works in 1.x, but prefer helpers because icon configuration is process-global state.
 
 ```ts
 import { getRegisteredThemes, setIconTheme } from 'markstream-vue'

package/README.zh-CN.md

@@ -153,6 +153,30 @@ createApp({
 确保在 CSS reset（如 `@tailwind base` 或 `@unocss/reset`）之后导入 `markstream-vue/index.css`，推荐使用 `@import 'markstream-vue/index.css' layer(components);` 以避免 Tailwind/UnoCSS 覆盖组件样式。根据需求再按需安装可选 peer 依赖：`stream-monaco`（Monaco 代码块）、`shiki` + `stream-markdown`（Shiki 高亮）、`mermaid`（Mermaid 图表）、`katex`（数学公式）。
 如果你的移动端会主动调大根字号（`html`/`body`），建议改用 `markstream-vue/index.px.css`，避免 `rem` 跟随根字号导致整体放大。
 
+按使用场景选择渲染模式：
+
+```vue
+<!-- AI 聊天 / SSE 输出：稳定节奏，不叠加透明度动画，避免闪烁 -->
+<MarkdownRender
+  mode="chat"
+  :content="message"
+  :final="isDone"
+  smooth-streaming="auto"
+  :fade="false"
+/>
+
+<!-- 富文档：默认启用更大的渲染批次、tooltip 和 fade -->
+<MarkdownRender
+  mode="docs"
+  :content="doc"
+  :final="true"
+/>
+```
+
+当你想要和 `chat` 相同的轻量默认值，但当前页面不是聊天语义时，可以使用 `mode="minimal"`。避免把高频 `smooth-streaming` 和 `fade` 同时开启，否则稳定的流式输出可能变成反复重启的透明度动画。
+同一条聊天消息不要仅因为 `final` 变为 `true` 就从 `mode="chat"` 切到 `mode="docs"`。保持 mode 稳定，只切换 `smooth-streaming`、`typewriter`、`fade` 等节奏/动画 props；`docs` 会改变默认代码块渲染器和布局策略。
+如果文档页不需要 Monaco 代码块，建议设置 `:render-code-blocks-as-pre="true"`；如果需要富 Monaco 代码块 UI，请安装 `stream-monaco`，否则渲染器会按设计降级为 `<pre>` 渲染。
+
 渲染器的 CSS 会作用于内部 `.markstream-vue` 容器下，以尽量降低对全局的影响；如果你脱离 `MarkdownRender` 单独使用导出的节点组件，请在外层包一层带 `markstream-vue` 类名的容器。
 
 暗色变量可以通过给祖先节点加 `.dark`，或直接给 `MarkdownRender` 传入 `:is-dark="true"`（仅对渲染器生效）。
@@ -167,7 +191,7 @@ createApp({
 />
 ```
 
-语言图标默认使用内置的 `material` theme。进阶接入可以用导出的 helper 查看或切换 icon theme，也可以在 `app.use(VueRendererMarkdown, { iconTheme })` 时指定初始主题：
+语言图标默认使用内置的 `material` theme。新接入建议在 `app.mount()` 之前通过导出的 helper 查看或切换 icon theme。旧的 `app.use(VueRendererMarkdown, { iconTheme })` 选项在 1.x 仍可用，但它会修改进程级全局状态，因此优先使用 helper。
 
 ```ts
 import { getRegisteredThemes, setIconTheme } from 'markstream-vue'