markstream-vue 0.0.14-beta.6 → 0.0.14-beta.8

package/.agents/skills/markstream-angular/SKILL.md

@@ -16,7 +16,12 @@ Use this skill when the host app is Angular and the task is to adopt the Angular
 4. Prefer standalone Angular integration.
    - Use `MarkstreamAngularComponent` in `imports` and keep examples signal-friendly.
 5. Start with `[content]`.
-   - Use `[final]`, `[codeBlockStream]`, and other streaming inputs only when the UI actually streams.
+   - For streaming AI chat, keep `[content]` and use built-in smooth streaming first.
+     - `[smoothStreaming]="'auto'"` is the default and activates when `[typewriter]="true"` or `[maxLiveNodes]="0"`.
+     - `[typewriter]` only controls the blinking cursor and defaults to `false`.
+     - `[fade]` controls node enter and streamed-text fade animations and defaults to `true`.
+   - Use `[final]` for end-of-stream state; final parsing is gated until visible content catches up when smooth streaming is active.
+   - Move to `nodes` + `final` only for worker-preparsed content, shared AST stores, or custom AST control.
    - Remember that `[htmlPolicy]` now defaults to `'safe'`, and Mermaid strict mode is on by default through `[mermaidProps]`.
 6. Use `[customHtmlTags]` and `[customComponents]` for trusted tag workflows.
 7. Validate with the smallest useful Angular dev or build command.
@@ -24,7 +29,7 @@ Use this skill when the host app is Angular and the task is to adopt the Angular
 ## Default Decisions
 
 - Standalone Angular first, NgModule-era patterns only when the repo still depends on them.
-- Treat streaming flags as opt-in.
+- Treat the cursor as opt-in (`typewriter=false` by default), but keep fade animations enabled by default (`fade=true`).
 - Keep optional peers minimal and explicit.
 - Keep `[htmlPolicy]="'safe'"` and Mermaid strict mode unless the task is preserving trusted legacy rendering.
 - If a trusted surface needs broader old behavior, opt out locally with `[htmlPolicy]="'trusted'"` and `[mermaidProps]="{ isStrict: false }"`, and document that trust boundary.

package/.agents/skills/markstream-custom-components/SKILL.md

@@ -24,6 +24,7 @@ Read [references/patterns.md](references/patterns.md) before choosing an overrid
 4. Preserve nested Markdown when needed.
    - For trusted custom tags with inner Markdown, render `node.content` with a nested renderer.
    - Pass the same custom-tag allowlist to nested renderers.
+   - Nested renderers inside a smooth-streaming parent are automatically suppressed from double pacing — do not add `smooth-streaming` to child renderers.
 5. Keep props and cleanup intact.
    - Preserve `node`, `loading`, `indexKey`, `customId`, and `isDark`.
    - For `mermaid` and `infographic` overrides, preserve `estimatedPreviewHeightPx` so async preview shells keep stable height during remounts.

package/.agents/skills/markstream-install/SKILL.md

@@ -21,11 +21,18 @@ Read [references/scenarios.md](references/scenarios.md) before making dependency
    - For Vue 3 Monaco preloading, use `preloadCodeBlockRuntime` from `markstream-vue` so the renderer runtime knows Monaco is warm. Existing `getUseMonaco()` calls are still compatible.
 3. Fix CSS order.
    - Put reset styles before Markstream styles.
-   - In Tailwind or UnoCSS projects, place `markstream-*/index.css` inside `@layer components`.
+   - In Tailwind or UnoCSS projects, use `@import 'markstream-*/index.css' layer(components);`.
    - Import `katex/dist/katex.min.css` when math is enabled.
 4. Add the smallest working render example.
     - Use `content` for static or low-frequency rendering.
-    - Use `nodes` plus `final` when the app receives streaming updates.
+    - For streaming AI chat, start with `content` and built-in smooth streaming.
+      - Auto mode is the default: `smoothStreaming="auto"` / `smooth-streaming="auto"`.
+      - Auto pacing activates when `typewriter=true` or `maxLiveNodes <= 0` / `max-live-nodes <= 0`.
+      - `typewriter` only controls the blinking cursor and defaults to `false`.
+      - `fade` controls node enter and streamed-text fade animations and defaults to `true`.
+      - For high-frequency smooth streams, consider `fade=false` / `:fade="false"` / `[fade]="false"` to avoid fade stacking.
+    - Use `nodes` + `final` only for worker preparsing, shared AST stores, or custom AST control.
+    - For manual pacing with `nodes`, use `useSmoothMarkdownStream`: `enqueue()` chunks, `finish()` when done, render from `visible`, wait for `caughtUp` before final parsing.
     - Preserve the default hardening: HTML policies now default to `safe`, and Mermaid runs in strict mode by default.
 5. Keep customization scoped.
     - If the task requires overrides, prefer `customId` / `custom-id` plus scoped `setCustomComponents(...)`.
@@ -36,7 +43,9 @@ Read [references/scenarios.md](references/scenarios.md) before making dependency
 ## Default Decisions
 
 - Prefer the minimal peer set over "install everything".
-- Prefer `content` unless the app is clearly SSE, chat, token-streaming, or worker-preparsed.
+- Prefer `content` for most streaming chat now that built-in smooth streaming is available across Vue 3, Vue 2, React, Svelte, and Angular.
+- Move to `nodes` only when another layer owns parsing or AST transforms.
+- When using `content` for streaming, smooth streaming (`smooth-streaming="auto"`) is on by default for `typewriter` or `max-live-nodes <= 0`. Set `:smooth-streaming="false"` to preserve raw chunk cadence.
 - Treat CSS order as a first-class part of installation, not a later cleanup.
 - When the request includes SSR, explicitly gate browser-only peers behind client-only boundaries.
 - Do not widen HTML or Mermaid security defaults unless the user explicitly needs trusted legacy compatibility.

package/.agents/skills/markstream-install/references/scenarios.md

@@ -24,11 +24,16 @@
 
 - reset first
 - Markstream CSS after reset
-- in Tailwind or UnoCSS projects, keep Markstream CSS inside `@layer components`
+- in Tailwind or UnoCSS projects, use `@import '...' layer(components)`
 - import KaTeX CSS when math is used
 - when standalone node components are rendered directly, wrap them with the package root class such as `.markstream-vue`, `.markstream-react`, or `.markstream-svelte`
 
 ## Input choice
 
-- `content`: docs pages, static articles, low-frequency updates
-- `nodes` + `final`: SSE, token streaming, AI chat, worker-preparsed content
+- `content`: docs pages, static articles, low-frequency updates, and most SSE / token streaming / AI chat surfaces.
+- `content` + built-in smooth streaming: jittery AI streams where visible output should be paced independently from raw chunk cadence.
+  - `smoothStreaming="auto"` / `smooth-streaming="auto"` is the default.
+  - Auto mode enables pacing when `typewriter=true` or `maxLiveNodes <= 0` / `max-live-nodes <= 0`.
+  - `typewriter` only controls the blinking cursor and defaults to `false`.
+  - `fade` controls node enter and streamed-text fade animations and defaults to `true`.
+- `nodes` + `final`: worker-preparsed content, shared AST stores, custom AST transforms, or cases where another layer already owns parsing.

package/.agents/skills/markstream-migration/SKILL.md

@@ -29,8 +29,10 @@ Read [references/adoption-checklist.md](references/adoption-checklist.md) before
 5. Review gaps honestly.
    - Do not claim 1:1 parity where none exists.
    - Call out parser, plugin, security, or HTML behavior that still needs manual review.
-6. Treat streaming as a second pass unless clearly required now.
-   - Move to `nodes` only when the app receives streaming or high-frequency updates.
+6. Consider smooth streaming before jumping to `nodes`.
+   - If the app streams `content` and only needs pacing, `smooth-streaming="auto"` (the default) handles it without requiring `nodes`.
+   - Move to `nodes` only when the app needs custom AST control, worker preparsing, or high-frequency structural updates.
+   - When smooth streaming is on, pair it with `:fade="false"`.
 7. Validate and summarize.
    - Run the smallest relevant tests or build.
    - Report direct mappings, TODOs, and remaining verification work.
@@ -38,6 +40,7 @@ Read [references/adoption-checklist.md](references/adoption-checklist.md) before
 ## Default Decisions
 
 - Renderer swap first, streaming optimization second.
+- Smooth streaming is an intermediate option between "just content" and "full nodes migration": it paces visible output without requiring AST control.
 - Preserve safety over feature parity when HTML or security rules are involved.
 - Prefer explicit TODOs over vague claims.
 - Recommend against migration when the current stack depends heavily on transforms that Markstream does not mirror directly.
@@ -47,6 +50,7 @@ Read [references/adoption-checklist.md](references/adoption-checklist.md) before
 
 - `docs/guide/react-markdown-migration.md`
 - `docs/guide/react-markdown-migration-cookbook.md`
+- `docs/guide/ai-chat-streaming.md`
 - `docs/guide/installation.md`
 - `docs/guide/component-overrides.md`
 - `docs/guide/advanced.md`

package/.agents/skills/markstream-nuxt/SKILL.md

@@ -14,13 +14,19 @@ Use this skill when the host app is Nuxt and SSR boundaries matter.
 3. Keep browser-only peers behind client-only boundaries.
    - Prefer `<client-only>` wrappers, `.client` plugins, or guarded setup paths.
 4. Import `markstream-vue/index.css` from a client-safe app shell or plugin.
-5. Start with `content`, and move to `nodes` plus `final` only when the UI is streaming.
+5. Start with `content`, and move to `nodes` plus `final` only when the UI needs custom AST control.
+   - For streaming AI chat, use `typewriter` or `:max-live-nodes="0"` — smooth streaming (`smooth-streaming="auto"`) paces visible output automatically.
+   - `typewriter` only controls the blinking cursor and defaults to `false`.
+   - `fade` controls node enter and streamed-text fade animations and defaults to `true`.
+   - When smooth streaming is on, pair it with `:fade="false"` to avoid delta fade stacking with high-commit pacing.
+   - In SSR, avoid `smooth-streaming="true"` on first-screen content; the mounted gate inside `auto` prevents hydration mismatch.
    - Remember that `html-policy` now defaults to `safe`, and Mermaid strict mode is on by default through `mermaid-props`.
 6. Validate with the smallest relevant Nuxt dev, build, or typecheck command.
 
 ## Default Decisions
 
 - SSR safety comes before feature completeness.
+- Smooth streaming is SSR-safe in `auto` mode (the default) because it gates on mount. Do not use `smooth-streaming="true"` for first-screen SSR content — it bypasses the mounted gate and can cause hydration mismatch or blank flash.
 - Avoid import-time access to browser globals from server code paths.
 - Treat Monaco, Mermaid workers, and similar heavy peers as client-only unless the repo already has a proven SSR pattern.
 - Keep `html-policy="safe"` and Mermaid strict mode unless the task is preserving trusted legacy rendering.

package/.agents/skills/markstream-react/SKILL.md

@@ -13,7 +13,11 @@ Use this skill when the host app is React or Next and the task is to wire Markst
 2. Install `markstream-react` plus only the requested optional peers.
 3. Import `markstream-react/index.css` from the app shell or client entry.
 4. Start with `content`.
-   - Move to `nodes` plus `final` only when the UI receives streaming or high-frequency updates.
+   - For streaming or high-frequency AI output, keep `content` and use built-in smooth streaming first.
+     - `smoothStreaming="auto"` is the default and activates when `typewriter={true}` or `maxLiveNodes <= 0`.
+     - `typewriter` only controls the blinking cursor and defaults to `false`.
+     - `fade` controls node enter and streamed-text fade animations and defaults to `true`.
+   - Move to `nodes` + `final` only for worker-preparsed content, shared AST stores, or custom AST control.
    - Remember that `htmlPolicy` now defaults to `safe`, and Mermaid strict mode is on by default through `mermaidProps`.
 5. Respect SSR boundaries in Next.
    - Prefer `use client`, dynamic imports with `ssr: false`, or other client-only boundaries when browser-only peers are involved.
@@ -24,7 +28,10 @@ Use this skill when the host app is React or Next and the task is to wire Markst
 
 - Renderer wiring first, migration cleanup second.
 - If the repo already uses `react-markdown`, pair this skill with `markstream-migration`.
+- Prefer `content` with built-in smooth streaming for most AI chat / token streaming surfaces.
+- Move to `nodes` only when another layer owns parsing or AST transforms.
 - Prefer the smallest client-only boundary that solves the SSR issue.
+- Avoid `smoothStreaming={true}` for first-screen SSR content unless intentionally starting from blank; auto mode uses the mounted gate.
 - Keep `htmlPolicy="safe"` and Mermaid strict mode unless the request is preserving trusted legacy rendering.
 - If a trusted surface needs older behavior, use `htmlPolicy="trusted"` and `mermaidProps={{ isStrict: false }}` only on that surface and explain why.
 

package/.agents/skills/markstream-svelte/SKILL.md

@@ -8,7 +8,12 @@ description: Integrate markstream-svelte in Svelte 5 apps. Svelte 4 unsupported.
 - Confirm Svelte 5; ask Svelte 4 users to upgrade.
 - Add package and only requested peers.
 - Import CSS after resets; KaTeX CSS for math.
-- Default to `<MarkdownRender {content} />`; use `nodes`+`final` for streaming/workers.
+- Default to `<MarkdownRender {content} />`.
+  - For streaming AI chat, keep `content` and use built-in smooth streaming first.
+    - `smoothStreaming="auto"` is the default and activates when `typewriter={true}` or `maxLiveNodes <= 0`.
+    - `typewriter` only controls the blinking cursor and defaults to `false`.
+    - `fade` controls node enter and streamed-text fade animations and defaults to `true`.
+  - Use `nodes` + `final` for worker-preparsed content, shared AST stores, or custom AST control.
 - Use `$props()` and callbacks.
 - Workers: `setKaTeXWorker`, `setMermaidWorker`, `workers/*?worker`.
 - Custom UI: scoped `setCustomComponents`, `customId`, `customHtmlTags`.

package/.agents/skills/markstream-vue/SKILL.md

@@ -12,9 +12,14 @@ Use this skill when the host app is plain Vue 3, typically Vite-based, and not N
 1. Confirm the repo is Vue 3 and not Nuxt.
 2. Install `markstream-vue` plus only the optional peers required by the requested features.
 3. Import `markstream-vue/index.css` after resets.
-   - In Tailwind or UnoCSS projects, keep Markstream styles inside `@layer components`.
+   - In Tailwind or UnoCSS projects, use `@import 'markstream-vue/index.css' layer(components);`.
 4. Start with `<MarkdownRender :content="markdown" />`.
-   - Switch to `nodes` plus `final` only for streaming, SSE, or high-frequency updates.
+   - For AI chat or streaming UIs, use `typewriter` or `:max-live-nodes="0"` — smooth streaming is auto-enabled (`smooth-streaming="auto"`, the default) and paces visible output so bursty chunks appear steadily.
+   - `typewriter` only controls the blinking cursor and defaults to `false`.
+   - `fade` controls node enter and streamed-text fade animations and defaults to `true`.
+   - Set `:smooth-streaming="false"` to preserve raw chunk cadence; set `:smooth-streaming="true"` to force smooth pacing even on first-screen content (may cause hydration mismatch in SSR).
+   - When smooth streaming is on, pair it with `:fade="false"` to avoid delta fade (280 ms) stacking with high-commit pacing.
+   - Switch to `nodes` plus `final` only when the app needs custom AST control, worker preparsing, or structural updates beyond pacing.
    - Remember that `html-policy` now defaults to `safe`, and Mermaid strict mode is on by default through `mermaid-props`.
 5. Use `custom-id` plus scoped `setCustomComponents(...)` for overrides.
 6. Validate with the smallest useful dev, build, or typecheck command.
@@ -22,6 +27,8 @@ Use this skill when the host app is plain Vue 3, typically Vite-based, and not N
 ## Default Decisions
 
 - Vue 3 apps default to `content`.
+- Smooth streaming (`smooth-streaming="auto"`) is on by default when `typewriter` or `max-live-nodes <= 0`. It only paces the `content` path; `nodes` mode is never affected.
+- For manual pacing with `nodes`, use `useSmoothMarkdownStream` directly: `enqueue()` chunks, `finish()` when done, render from `visible`, and wait for `caughtUp` before final parsing.
 - Prefer local component registration unless the repo already uses a shared plugin entry.
 - When Monaco code blocks need app-level preloading, import `preloadCodeBlockRuntime` from `markstream-vue`. Existing `getUseMonaco()` preloads remain valid; do not import `stream-monaco` directly just to warm workers.
 - Keep `html-policy="safe"` and Mermaid strict mode unless the task is explicitly preserving trusted legacy behavior.
@@ -33,4 +40,5 @@ Use this skill when the host app is plain Vue 3, typically Vite-based, and not N
 - `docs/guide/quick-start.md`
 - `docs/guide/installation.md`
 - `docs/guide/usage.md`
+- `docs/guide/ai-chat-streaming.md`
 - `docs/guide/component-overrides.md`

package/.agents/skills/markstream-vue2/SKILL.md

@@ -14,6 +14,11 @@ Use this skill when the host app is Vue 2 and not specifically a Vue CLI / Webpa
    - Add `@vue/composition-api` only when the repo is Vue 2.6 and uses Composition API patterns.
 3. Import `markstream-vue2/index.css` after resets.
 4. Start with `<MarkdownRender :content="markdown" />`.
+   - For AI chat or streaming UIs, keep `content` and use built-in smooth streaming first.
+     - `smooth-streaming="auto"` is the default and activates when `typewriter=true` or `max-live-nodes <= 0`.
+     - `typewriter` only controls the blinking cursor and defaults to `false`.
+     - `fade` controls node enter and streamed-text fade animations and defaults to `true`.
+   - Move to `nodes` + `final` only for worker-preparsed content, shared AST stores, or custom AST control.
    - Remember that `html-policy` now defaults to `safe`, and Mermaid strict mode is on by default through `mermaid-props`.
 5. Use scoped custom component mappings when the task needs overrides or trusted tags.
 6. Validate with the smallest useful dev or build command.

package/.agents/skills/markstream-vue2-cli/SKILL.md

@@ -16,6 +16,11 @@ Use this skill when the host app is Vue 2 on Vue CLI or another Webpack 4-style
    - Use `createKaTeXWorkerFromCDN(...)` and `createMermaidWorkerFromCDN(...)` when workers are needed.
 5. Prefer stable code block defaults over brittle Monaco wiring.
    - `MarkdownCodeBlockNode` plus `stream-markdown` is safer than Monaco in Webpack 4-era repos.
+   - For AI chat or streaming UIs, keep `content` and use built-in smooth streaming first.
+     - `smooth-streaming="auto"` is the default and activates when `typewriter=true` or `max-live-nodes <= 0`.
+     - `typewriter` only controls the blinking cursor and defaults to `false`.
+     - `fade` controls node enter and streamed-text fade animations and defaults to `true`.
+   - Move to `nodes` + `final` only for worker-preparsed content, shared AST stores, or custom AST control.
    - Remember that `html-policy` now defaults to `safe`, and Mermaid strict mode is on by default through `mermaid-props`.
 6. Validate with the smallest useful local dev or build command.
 

package/.agents/skills/markstream-vue2-vite/SKILL.md

@@ -15,6 +15,11 @@ Use this skill when the host app is Vue 2 and the bundler is Vite.
 4. Use Vite worker imports when the repo needs bundled workers.
    - `markstream-vue2/workers/... ?worker` or `?worker&inline` patterns are allowed here.
 5. Keep Composition API decisions explicit for Vue 2.6 repos.
+   - For AI chat or streaming UIs, keep `content` and use built-in smooth streaming first.
+     - `smooth-streaming="auto"` is the default and activates when `typewriter=true` or `max-live-nodes <= 0`.
+     - `typewriter` only controls the blinking cursor and defaults to `false`.
+     - `fade` controls node enter and streamed-text fade animations and defaults to `true`.
+   - Move to `nodes` + `final` only for worker-preparsed content, shared AST stores, or custom AST control.
    - Remember that `html-policy` now defaults to `safe`, and Mermaid strict mode is on by default through `mermaid-props`.
 6. Validate with the smallest useful Vite dev or build command.
 

package/README.md

@@ -151,7 +151,7 @@ createApp({
 }).mount('#app')
 ```
 
-Import `markstream-vue/index.css` after your reset (e.g., Tailwind `@layer components`) so renderer styles win over utility classes. Install optional peers such as `stream-monaco`, `shiki`, `stream-markdown`, `mermaid`, and `katex` only when you need Monaco code blocks, Shiki highlighting, diagrams, or math.
+Import `markstream-vue/index.css` after your reset (e.g., use `@import 'markstream-vue/index.css' layer(components);` for Tailwind) so renderer styles win over utility classes. Install optional peers such as `stream-monaco`, `shiki`, `stream-markdown`, `mermaid`, and `katex` only when you need Monaco code blocks, Shiki highlighting, diagrams, or math.
 If your app intentionally scales root font size on mobile, use `markstream-vue/index.px.css` to avoid `rem`-based global scaling side effects.
 
 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`.
@@ -258,36 +258,38 @@ Then use `<MarkdownRender :content="md" />` in your pages.
 
 ## ⏱️ Streaming in 30 seconds
 
-Render streamed Markdown (SSE/websocket) with incremental updates:
+Render streamed Markdown (SSE/websocket) with built-in smooth pacing:
 
 ```ts
-import type { ParsedNode } from 'markstream-vue'
-import MarkdownRender, { getMarkdown, parseMarkdownToStructure } from 'markstream-vue'
+import MarkdownRender from 'markstream-vue'
 import { ref } from 'vue'
 
-const nodes = ref<ParsedNode[]>([])
-const buffer = ref('')
-const md = getMarkdown()
+const content = ref('')
+const final = ref(false)
 
-function addChunk(chunk: string) {
-  buffer.value += chunk
-  nodes.value = parseMarkdownToStructure(buffer.value, md)
+eventSource.onmessage = (event) => {
+  content.value += event.data
 }
-
-// e.g., inside your SSE/onmessage handler
-eventSource.onmessage = event => addChunk(event.data)
+eventSource.addEventListener('done', () => {
+  final.value = true
+})
 
 // template
 // <MarkdownRender
-//   :nodes="nodes"
+//   :content="content"
+//   :final="final"
 //   :max-live-nodes="0"
-//   :batch-rendering="{
-//     renderBatchSize: 16,
-//     renderBatchDelay: 8,
-//   }"
+//   :batch-rendering="true"
+//   :render-batch-size="16"
+//   :render-batch-delay="8"
+//   :render-batch-budget-ms="4"
+//   :fade="false"
+//   :typewriter="true"
 // />
 ```
 
+`smooth-streaming` is enabled by default in typewriter/incremental mode (`typewriter` or `max-live-nodes <= 0`). Disable per surface with `:smooth-streaming="false"` if you want raw chunk cadence.
+
 Switch rendering style per surface:
 
 - Virtualized window (default): steady scrolling and memory usage for long docs.
@@ -332,7 +334,7 @@ const md = getMarkdown() // match server setup
 
 function addChunk(chunk: string) {
   buffer.value += chunk
-  nodes.value = parseMarkdownToStructure(buffer.value, md)
+  nodes.value = parseMarkdownToStructure(buffer.value, md, { final: false })
 }
 ```
 

package/README.zh-CN.md

@@ -152,7 +152,7 @@ createApp({
 }).mount('#app')
 ```
 
-确保在 CSS reset（如 `@tailwind base` 或 `@unocss/reset`）之后导入 `markstream-vue/index.css`，最好放在 `@layer components` 中以避免 Tailwind/UnoCSS 覆盖组件样式。根据需求再按需安装可选 peer 依赖：`stream-monaco`（Monaco 代码块）、`shiki` + `stream-markdown`（Shiki 高亮）、`mermaid`（Mermaid 图表）、`katex`（数学公式）。
+确保在 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` 跟随根字号导致整体放大。
 
 渲染器的 CSS 会作用于内部 `.markstream-vue` 容器下，以尽量降低对全局的影响；如果你脱离 `MarkdownRender` 单独使用导出的节点组件，请在外层包一层带 `markstream-vue` 类名的容器。
@@ -259,36 +259,38 @@ export default defineNuxtPlugin((nuxtApp) => {
 
 ## ⏱️ 30 秒流式接入
 
-用 SSE / WebSocket 增量渲染 Markdown：
+用 SSE / WebSocket 结合内置平滑节奏渲染 Markdown：
 
 ```ts
-import type { ParsedNode } from 'markstream-vue'
-import MarkdownRender, { getMarkdown, parseMarkdownToStructure } from 'markstream-vue'
+import MarkdownRender from 'markstream-vue'
 import { ref } from 'vue'
 
-const nodes = ref<ParsedNode[]>([])
-const buffer = ref('')
-const md = getMarkdown()
+const content = ref('')
+const final = ref(false)
 
-function addChunk(chunk: string) {
-  buffer.value += chunk
-  nodes.value = parseMarkdownToStructure(buffer.value, md)
+eventSource.onmessage = (event) => {
+  content.value += event.data
 }
-
-// 例如在 SSE / onmessage 处理器中
-eventSource.onmessage = event => addChunk(event.data)
+eventSource.addEventListener('done', () => {
+  final.value = true
+})
 
 // template
 // <MarkdownRender
-//   :nodes="nodes"
+//   :content="content"
+//   :final="final"
 //   :max-live-nodes="0"
-//   :batch-rendering="{
-//     renderBatchSize: 16,
-//     renderBatchDelay: 8,
-//   }"
+//   :batch-rendering="true"
+//   :render-batch-size="16"
+//   :render-batch-delay="8"
+//   :render-batch-budget-ms="4"
+//   :fade="false"
+//   :typewriter="true"
 // />
 ```
 
+`smooth-streaming` 在打字机/增量模式（`typewriter` 或 `max-live-nodes <= 0`）默认开启；如果希望严格按原始 chunk 节奏显示，可按实例设置 `:smooth-streaming="false"`。
+
 按页面需要切换渲染风格：
 
 - 虚拟化窗口（默认）：长文档滚动平稳、内存稳定。