markstream-vue 0.0.3-beta.1 → 0.0.3-beta.2

package/README.md

@@ -5,24 +5,63 @@
 [![NPM version](https://img.shields.io/npm/v/markstream-vue?color=a1b858&label=)](https://www.npmjs.com/package/markstream-vue)
 [![中文版](https://img.shields.io/badge/docs-中文文档-blue)](README.zh-CN.md)
 [![Docs](https://img.shields.io/badge/docs-vitepress-blue)](https://markstream-vue-docs.simonhe.me/)
+[![Playground](https://img.shields.io/badge/playground-live-34c759)](https://markstream-vue.simonhe.me/)
+[![Test page](https://img.shields.io/badge/test-shareable%20repro-0A84FF)](https://markstream-vue.simonhe.me/test)
 [![NPM downloads](https://img.shields.io/npm/dm/markstream-vue)](https://www.npmjs.com/package/markstream-vue)
 [![Bundle size](https://img.shields.io/bundlephobia/minzip/markstream-vue)](https://bundlephobia.com/package/markstream-vue)
+[![Release](https://img.shields.io/github/v/release/Simon-He95/markstream-vue?display_name=release&logo=github)](https://github.com/Simon-He95/markstream-vue/releases)
+[![Discussions](https://img.shields.io/github/discussions/Simon-He95/markstream-vue?logo=github)](https://github.com/Simon-He95/markstream-vue/discussions)
+[![Discord](https://img.shields.io/discord/986352439269560380?label=discord&logo=discord&logoColor=fff&color=5865F2)](https://discord.gg/vkzdkjeRCW)
+[![Support](https://img.shields.io/badge/support-guide-ff6f61)](./SUPPORT.md)
+[![Security](https://img.shields.io/badge/security-policy-8A2BE2)](./SECURITY.md)
+[![CI](https://github.com/Simon-He95/markstream-vue/actions/workflows/ci.yml/badge.svg)](https://github.com/Simon-He95/markstream-vue/actions/workflows/ci.yml)
 [![License](https://img.shields.io/npm/l/markstream-vue)](./LICENSE)
 
+## Contents
+
+- [TL;DR Highlights](#tldr-highlights)
+- [Try It Now](#-try-it-now)
+- [Quick Start](#-quick-start)
+- [Common commands](#-common-commands)
+- [Streaming in 30 seconds](#-streaming-in-30-seconds)
+- [Performance presets](#-performance-presets)
+- [Key props & options](#-key-props--options-cheatsheet)
+- [Where it shines](#-where-it-shines)
+- [FAQ](#-faq-quick-answers)
+- [Why markstream-vue](#-why-markstream-vue-over-a-typical-markdown-renderer)
+- [Releases](#-releases)
+- [Showcase](#-showcase--examples)
+- [Contributing & community](#-contributing--community)
+- [Community & support](#-community--support)
+- [Troubleshooting](#troubleshooting--common-issues)
 > 📖 All detailed documentation, API, examples, and advanced usage have been migrated to the VitePress documentation site:
 > https://markstream-vue-docs.simonhe.me/guide/
 
-## 🚀 Playground & Demo
+## TL;DR Highlights
+
+- Purpose-built for **streaming Markdown** (AI/chat/SSE) with zero flicker and predictable memory.
+- **Two render modes**: virtual window for long docs, incremental batching for “typing” effects.
+- **Progressive diagrams** (Mermaid) and **streaming code blocks** (Monaco/Shiki) that keep up with diffs.
+- Works with **raw Markdown strings or pre-parsed nodes**, supports **custom Vue components** inline.
+- TypeScript-first, ship-ready defaults — import CSS and render.
+
+## 🚀 Try It Now
 
 - Playground (interactive demo): https://markstream-vue.simonhe.me/
-- Interactive test page: https://markstream-vue.simonhe.me/test
+- Interactive test page (shareable links, easy reproduction): https://markstream-vue.simonhe.me/test
+- Docs: https://markstream-vue-docs.simonhe.me/guide/
+- One-click StackBlitz demo: https://stackblitz.com/github/Simon-He95/markstream-vue?file=playground/src/App.vue
+- Changelog: [CHANGELOG.md](./CHANGELOG.md)
+- Nuxt playground: `pnpm play:nuxt`
+- Discord: https://discord.gg/vkzdkjeRCW
 
-Try the interactive test page to quickly verify and debug:
-https://markstream-vue.simonhe.me/test
+## 💬 Community & support
 
-This page provides a left editor and right live preview (powered by this library). It includes "generate & copy share link" functionality, encoding your input into the URL for sharing. If the input is too long, fallback options are provided to open directly or pre-fill a GitHub Issue.
+- Discussions: https://github.com/Simon-He95/markstream-vue/discussions
+- Discord: https://discord.gg/vkzdkjeRCW
+- Issues: please use templates and attach a repro link (https://markstream-vue.simonhe.me/test)
 
-You can use this page to reproduce rendering issues, verify math/Mermaid/code block behavior, and quickly generate shareable links or reproducible issues.
+The test page gives you an editor + live preview plus “generate share link” that encodes the input in the URL (with a fallback to open directly or pre-fill a GitHub Issue for long payloads).
 
 ## ⚡ Quick Start
 
@@ -50,6 +89,123 @@ createApp({
 
 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`, `mermaid`, and `katex` only when you need Monaco code blocks, Shiki highlighting, diagrams, or math.
 
+Enable heavy peers only when needed:
+
+```ts
+import { enableKatex, enableMermaid } from 'markstream-vue'
+import 'markstream-vue/index.css'
+
+// after you install `mermaid` / `katex` peers
+enableMermaid()
+enableKatex()
+```
+
+### Nuxt quick drop-in
+
+```ts
+// plugins/markstream-vue.client.ts
+import { defineNuxtPlugin } from '#app'
+import MarkdownRender from 'markstream-vue'
+import 'markstream-vue/index.css'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.vueApp.component('MarkdownRender', MarkdownRender)
+})
+```
+
+Then use `<MarkdownRender :content="md" />` in your pages.
+
+## 🛠️ Common commands
+
+- `pnpm dev` — playground dev server
+- `pnpm play:nuxt` — Nuxt playground dev
+- `pnpm build` — library + CSS build
+- `pnpm test` — Vitest suite (`pnpm test:update` for snapshots)
+- `pnpm typecheck` / `pnpm lint` — type and lint checks
+
+## ⏱️ Streaming in 30 seconds
+
+Render streamed Markdown (SSE/websocket) with incremental updates:
+
+```ts
+import type { ParsedNode } from 'markstream-vue'
+import MarkdownRender, {
+  getMarkdown,
+
+  parseMarkdownToStructure
+} from 'markstream-vue'
+import { ref } from 'vue'
+
+const nodes = ref<ParsedNode[]>([])
+const buffer = ref('')
+const md = getMarkdown()
+
+function addChunk(chunk: string) {
+  buffer.value += chunk
+  nodes.value = parseMarkdownToStructure(buffer.value, md)
+}
+
+// e.g., inside your SSE/onmessage handler
+eventSource.onmessage = event => addChunk(event.data)
+
+// template
+// <MarkdownRender
+//   :nodes="nodes"
+//   :max-live-nodes="0"
+//   :batch-rendering="{
+//     renderBatchSize: 16,
+//     renderBatchDelay: 8,
+//   }"
+// />
+```
+
+Switch rendering style per surface:
+
+- Virtualized window (default): steady scrolling and memory usage for long docs.
+- Incremental batches: set `:max-live-nodes="0"` for AI-like “typing” with lightweight placeholders.
+
+### SSR / Worker usage (deterministic output)
+
+Pre-parse Markdown on the server or in a worker and render typed nodes on the client:
+
+```ts
+// server or worker
+import { getMarkdown, parseMarkdownToStructure } from 'markstream-vue'
+
+const md = getMarkdown()
+const nodes = parseMarkdownToStructure('# Hello\n\nThis is parsed once', md)
+// send `nodes` JSON to the client
+```
+
+```vue
+<!-- client -->
+<MarkdownRender :nodes="nodesFromServer" />
+```
+
+This avoids client-side parsing and keeps SSR/hydration deterministic.
+
+### Hybrid: SSR + streaming handoff
+
+- Server: parse the first Markdown batch to nodes and serialize `initialNodes` (and the raw `initialMarkdown` if you also stream later chunks).
+- Client: hydrate with the same parser options, then keep streaming:
+
+```ts
+import type { ParsedNode } from 'markstream-vue'
+import { getMarkdown, parseMarkdownToStructure } from 'markstream-vue'
+import { ref } from 'vue'
+
+const nodes = ref<ParsedNode[]>(initialNodes)
+const buffer = ref(initialMarkdown)
+const md = getMarkdown() // match server setup
+
+function addChunk(chunk: string) {
+  buffer.value += chunk
+  nodes.value = parseMarkdownToStructure(buffer.value, md)
+}
+```
+
+This avoids re-parsing SSR content while letting later SSE/WebSocket chunks continue the stream.
+
 ## ⚙️ Performance presets
 
 - **Virtual window (default)** – keep `max-live-nodes` at its default `320` to enable virtualization. Nodes render immediately and the renderer keeps a sliding window of elements mounted so long docs remain responsive without showing skeleton placeholders.
@@ -57,6 +213,99 @@ Import `markstream-vue/index.css` after your reset (e.g., Tailwind `@layer compo
 
 Pick one mode per surface: virtualization for best scrollback and steady memory usage, or incremental batching for AI-style “typing” previews.
 
+> Tip: In chats, combine `max-live-nodes="0"` with small `renderBatchSize` (e.g., `16`) and a tiny `renderBatchDelay` (e.g., `8ms`) to keep the “typing” feel smooth without jumping large chunks. Tune `renderBatchBudgetMs` down if you need to cap CPU per frame.
+
+## 🧰 Key props & options (cheatsheet)
+
+- `content` vs `nodes`: pass raw Markdown or pre-parsed nodes (from `parseMarkdownToStructure`).
+- `max-live-nodes`: `320` (default virtualization) or `0` (incremental batches).
+- `batchRendering`: fine-tune batches with `initialRenderBatchSize`, `renderBatchSize`, `renderBatchDelay`, `renderBatchBudgetMs`.
+- `enableMermaid` / `enableKatex` / `enableMonaco`: opt-in heavy deps when needed.
+- `parse-options`: reuse parser hooks (e.g., `preTransformTokens`, `requireClosingStrong`) on the component.
+- `custom-components`: register inline Vue components for custom tags/markers.
+
+Example: map Markdown placeholders to Vue components
+
+```ts
+import { setCustomComponents } from 'markstream-vue'
+
+setCustomComponents({
+  CALLOUT: () => import('./components/Callout.vue'),
+})
+
+// Markdown: [[CALLOUT:warning title="Heads up" body="Details here"]]
+```
+
+Or pass per-renderer:
+
+```vue
+<MarkdownRender
+  :content="doc"
+  :custom-components="{
+    CALLOUT: () => import('./components/Callout.vue'),
+  }"
+/>
+```
+
+Parse hooks example (match server + client):
+
+```vue
+<MarkdownRender
+  :content="doc"
+  :parse-options="{
+    requireClosingStrong: true,
+    preTransformTokens: (tokens) => tokens,
+  }"
+/>
+```
+
+## 🔥 Where it shines
+
+- AI/chat UIs with long-form answers and Markdown tokens arriving over SSE/websocket.
+- Docs, changelogs, and knowledge bases that need instant load but stay responsive as they grow.
+- Streaming diffs and code review panes that benefit from Monaco live updates.
+- Diagram-heavy content that should render progressively (Mermaid) without blocking.
+- Embedding Vue components in Markdown-driven surfaces (callouts, widgets, CTA buttons).
+
+## ❓ FAQ (quick answers)
+
+- Mermaid/KaTeX not rendering? Install the peer (`mermaid` / `katex`) and pass `:enable-mermaid="true"` / `:enable-katex="true"` or call the loader setters.
+- Bundle size: peers are optional and not bundled; import only `markstream-vue/index.css` once. Use Shiki (`MarkdownCodeBlockNode`) when Monaco is too heavy.
+- Custom UI: register components via `setCustomComponents` (global) or `custom-components` prop, then emit markers/placeholders in Markdown and map them to Vue components.
+
+## 🆚 Why markstream-vue over a typical Markdown renderer?
+
+| Needs | Typical Markdown preview | markstream-vue |
+| --- | --- | --- |
+| Streaming input | Re-renders whole tree, flashes | Incremental batches with virtual windowing |
+| Large code blocks | Slow re-highlight | Monaco streaming updates + Shiki option |
+| Diagrams | Blocks while parsing | Progressive Mermaid with graceful fallback |
+| Custom UI | Limited slots | Inline Vue components & typed nodes |
+| Long docs | Memory spikes | Configurable live-node cap for steady usage |
+
+## 🗺️ Roadmap (snapshot)
+
+- More “instant start” templates (Vite + Nuxt + Tailwind) and updated StackBlitz.
+- Additional codeblock presets (diff-friendly Shiki themes, Monaco decoration helpers).
+- Cookbook docs for AI/chat patterns (SSE/WebSocket, retry/resume, markdown mid-states).
+- More showcase examples for embedding Vue components inside Markdown surfaces.
+
+## 📦 Releases
+
+- Latest: [Releases](https://github.com/Simon-He95/markstream-vue/releases) — see highlights and upgrade notes.
+- Full history: [CHANGELOG.md](./CHANGELOG.md)
+- Recent highlights (0.0.3-beta.1/beta.0):
+  - Parser bumped to `stream-markdown-parser@0.0.36` for parsing fixes.
+  - Monaco upgrades with more languages/themes + diff-friendly code block tweaks.
+  - HTML/SVG preview dialog and AST debug view in the playground.
+
+## 🧭 Showcase & examples
+
+Build something with markstream-vue? Open a PR to add it here (include a link + 1 screenshot/GIF). Ideal fits: AI/chat UIs, streaming docs, diff/code-review panes, or Markdown-driven pages with embedded Vue components.
+
+- **FlowNote** — streaming Markdown note app demo (SSE + virtual window) — https://markstream-vue.simonhe.me/
+- **AI Chat surface** — playground “test” page showing incremental batches + share links — https://markstream-vue.simonhe.me/test
+
 ## 📺 Introduction Video
 
 A short video introduces the key features and usage of markstream-vue:
@@ -79,6 +328,25 @@ Watch on Bilibili: [Open in Bilibili](https://www.bilibili.com/video/BV17Z4qzpE9
 - 🎨 Flexible code block rendering: choose Monaco editor (`CodeBlockNode`) or lightweight Shiki highlighting (`MarkdownCodeBlockNode`)
 - 🧰 Parser toolkit: [`stream-markdown-parser`](./packages/markdown-parser) now documents how to reuse the parser in workers/SSE streams and feed `<MarkdownRender :nodes>` directly, plus APIs for registering global plugins and custom math helpers.
 
+## 🙌 Contributing & community
+
+- Read the contributor guide: [CONTRIBUTING.md](./CONTRIBUTING.md) and follow the PR template.
+- Be kind and follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
+- Issues: use templates for bugs/requests; attach a repro from https://markstream-vue.simonhe.me/test when possible.
+- Questions? Start a discussion: https://github.com/Simon-He95/markstream-vue/discussions
+- Chat live: Discord https://discord.gg/vkzdkjeRCW
+- Looking to contribute? Start with [good first issues](https://github.com/Simon-He95/markstream-vue/labels/good%20first%20issue).
+- Support guide: [SUPPORT.md](./SUPPORT.md)
+- PRs: follow Conventional Commits, add tests for parser/render changes, and include screenshots/GIFs for UI tweaks.
+- If the project helps you, consider starring and sharing the repo — it keeps the work sustainable.
+- Security: see [SECURITY.md](./SECURITY.md) to report vulnerabilities privately.
+
+### Quick ways to help
+
+- Add repro links/screenshots to existing issues.
+- Improve docs/examples (especially streaming + SSR/worker patterns).
+- Share playground/test links that showcase performance edge cases.
+
 ## Troubleshooting & Common Issues
 
 Troubleshooting has moved into the docs:
@@ -87,6 +355,11 @@ https://markstream-vue-docs.simonhe.me/guide/troubleshooting
 If you can't find a solution there, open a GitHub issue:
 https://github.com/Simon-He95/markstream-vue/issues
 
+### Report an issue quickly
+
+1. Reproduce in the test page and click “generate share link”: https://markstream-vue.simonhe.me/test
+2. Open a bug report with the link and a screenshot: https://github.com/Simon-He95/markstream-vue/issues/new?template=bug_report.yml
+
 ## Thanks
 
 This project uses and benefits from:

package/README.zh-CN.md

@@ -4,33 +4,63 @@
 
 [![NPM version](https://img.shields.io/npm/v/markstream-vue?color=a1b858&label=)](https://www.npmjs.com/package/markstream-vue)
 [![Docs](https://img.shields.io/badge/docs-中文文档-blue)](https://markstream-vue-docs.simonhe.me/zh/guide/)
+[![Playground](https://img.shields.io/badge/playground-在线体验-34c759)](https://markstream-vue.simonhe.me/)
+[![Test page](https://img.shields.io/badge/test-可分享复现-0A84FF)](https://markstream-vue.simonhe.me/test)
 [![NPM downloads](https://img.shields.io/npm/dm/markstream-vue)](https://www.npmjs.com/package/markstream-vue)
 [![Bundle size](https://img.shields.io/bundlephobia/minzip/markstream-vue)](https://bundlephobia.com/package/markstream-vue)
+[![Release](https://img.shields.io/github/v/release/Simon-He95/markstream-vue?display_name=release&logo=github)](https://github.com/Simon-He95/markstream-vue/releases)
+[![Discussions](https://img.shields.io/github/discussions/Simon-He95/markstream-vue?logo=github)](https://github.com/Simon-He95/markstream-vue/discussions)
+[![Discord](https://img.shields.io/discord/986352439269560380?label=discord&logo=discord&logoColor=fff&color=5865F2)](https://discord.gg/vkzdkjeRCW)
+[![Support](https://img.shields.io/badge/support-guide-ff6f61)](./SUPPORT.md)
+[![Security](https://img.shields.io/badge/security-policy-8A2BE2)](./SECURITY.md)
+[![CI](https://github.com/Simon-He95/markstream-vue/actions/workflows/ci.yml/badge.svg)](https://github.com/Simon-He95/markstream-vue/actions/workflows/ci.yml)
 [![License](https://img.shields.io/npm/l/markstream-vue)](./LICENSE)
 
+## 目录
+
+- [速览](#速览)
+- [立即试用](#-立即试用)
+- [快速上手](#-快速上手)
+- [常用命令](#-常用命令)
+- [30 秒流式接入](#-30-秒流式接入)
+- [性能模式](#-性能模式)
+- [关键属性速览](#-关键属性速览)
+- [适用场景](#-适用场景)
+- [快问快答](#-快问快答)
+- [为什么选择 markstream-vue](#-为什么选择-markstream-vue而不是普通-markdown-渲染器)
+- [发布](#-发布)
+- [案例与展示](#-案例与展示)
+- [贡献与社区](#-贡献与社区)
+- [社区与支持](#-社区与支持)
+- [故障排查](#故障排查--常见问题)
 > 📖 所有详细文档、API、示例和高级用法已迁移至 VitePress 中文文档站点：
 > https://markstream-vue-docs.simonhe.me/zh/guide/
 
-## 🚀 实时演示
+## 速览
 
-- Playground（交互演示）： https://markstream-vue.simonhe.me/
-- 交互测试页面： https://markstream-vue.simonhe.me/test
-
-### 交互测试页面
-
-- 试用交互式测试页面以便快速验证与调试： https://markstream-vue.simonhe.me/test
+- 为 **流式 Markdown**（AI/聊天/SSE）打造，避免闪烁，内存可预期。
+- **双渲染模式**：长文档虚拟化窗口，或“打字机”式增量批次。
+- **渐进式图表**（Mermaid）与 **流式代码块**（Monaco/Shiki），跟上 diff/增量输出。
+- 同时支持 **Markdown 字符串或预解析节点**，可在 Markdown 中嵌入 **自定义 Vue 组件**。
+- TypeScript 优先，开箱默认即可上线（导入 CSS 即用）。
 
-  此页面提供左侧编辑器与右侧实时预览（由本库驱动）。页面包含“生成并复制分享链接”功能，会将你的输入编码到 URL 中以便分享；当输入过长无法嵌入 URL 时，会提供直接打开或预填 GitHub Issue 的回退流程。
+## 🚀 立即试用
 
-  你可以使用该页面复现渲染问题，验证数学公式 / Mermaid / 代码块的渲染行为，并快速生成可共享链接或带复现信息的 issue。
+- Playground（交互演示）： https://markstream-vue.simonhe.me/
+- 交互测试页（可分享链接，便于复现）： https://markstream-vue.simonhe.me/test
+- 文档： https://markstream-vue-docs.simonhe.me/zh/guide/
+- 一键 StackBlitz 体验： https://stackblitz.com/github/Simon-He95/markstream-vue?file=playground/src/App.vue
+- 更新日志： [CHANGELOG.md](./CHANGELOG.md)
+- Nuxt playground：`pnpm play:nuxt`
+- Discord： https://discord.gg/vkzdkjeRCW
 
-### 介绍视频
+## 💬 社区与支持
 
-一段短视频介绍了 markstream-vue 的关键特性与使用方式。
+- Discussions：https://github.com/Simon-He95/markstream-vue/discussions
+- Discord：https://discord.gg/vkzdkjeRCW
+- Issues：请使用模板并附上复现链接（https://markstream-vue.simonhe.me/test）
 
-[![在 Bilibili 查看介绍](https://i1.hdslb.com/bfs/archive/f073718bd0e51acaea436d7197880478213113c6.jpg)](https://www.bilibili.com/video/BV17Z4qzpE9c/)
-
-在 Bilibili 上观看： [Open in Bilibili](https://www.bilibili.com/video/BV17Z4qzpE9c/)
+测试页内置编辑器 + 实时预览，并提供“生成分享链接”功能（过长内容会回退为直接打开或预填 GitHub Issue）。
 
 ## ⚡ 快速上手
 
@@ -58,6 +88,123 @@ createApp({
 
 确保在 CSS reset（如 `@tailwind base` 或 `@unocss/reset`）之后导入 `markstream-vue/index.css`，最好放在 `@layer components` 中以避免 Tailwind/UnoCSS 覆盖组件样式。根据需求再按需安装可选 peer 依赖：`stream-monaco`（Monaco 代码块）、`shiki`（Shiki 高亮）、`mermaid`（Mermaid 图表）、`katex`（数学公式）。
 
+按需启用重型依赖：
+
+```ts
+import { enableKatex, enableMermaid } from 'markstream-vue'
+import 'markstream-vue/index.css'
+
+// 安装对应 peer 后再启用
+enableMermaid()
+enableKatex()
+```
+
+### Nuxt 快速接入
+
+```ts
+// plugins/markstream-vue.client.ts
+import { defineNuxtPlugin } from '#app'
+import MarkdownRender from 'markstream-vue'
+import 'markstream-vue/index.css'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.vueApp.component('MarkdownRender', MarkdownRender)
+})
+```
+
+然后在页面中直接使用 `<MarkdownRender :content=\"md\" />`。
+
+## 🛠️ 常用命令
+
+- `pnpm dev` — playground 开发
+- `pnpm play:nuxt` — Nuxt playground 开发
+- `pnpm build` — 构建库与 CSS
+- `pnpm test` — Vitest 测试（快照用 `pnpm test:update`）
+- `pnpm typecheck` / `pnpm lint` — 类型检查与 Lint
+
+## ⏱️ 30 秒流式接入
+
+用 SSE / WebSocket 增量渲染 Markdown：
+
+```ts
+import type { ParsedNode } from 'markstream-vue'
+import MarkdownRender, {
+  getMarkdown,
+
+  parseMarkdownToStructure
+} from 'markstream-vue'
+import { ref } from 'vue'
+
+const nodes = ref<ParsedNode[]>([])
+const buffer = ref('')
+const md = getMarkdown()
+
+function addChunk(chunk: string) {
+  buffer.value += chunk
+  nodes.value = parseMarkdownToStructure(buffer.value, md)
+}
+
+// 例如在 SSE / onmessage 处理器中
+eventSource.onmessage = event => addChunk(event.data)
+
+// template
+// <MarkdownRender
+//   :nodes="nodes"
+//   :max-live-nodes="0"
+//   :batch-rendering="{
+//     renderBatchSize: 16,
+//     renderBatchDelay: 8,
+//   }"
+// />
+```
+
+按页面需要切换渲染风格：
+
+- 虚拟化窗口（默认）：长文档滚动平稳、内存稳定。
+- 增量批次：将 `:max-live-nodes="0"`，获得更明显的“打字机”体验与轻量占位。
+
+### SSR / Worker（确定性输出）
+
+在服务端或 Worker 预解析 Markdown，前端直接渲染节点：
+
+```ts
+// server or worker
+import { getMarkdown, parseMarkdownToStructure } from 'markstream-vue'
+
+const md = getMarkdown()
+const nodes = parseMarkdownToStructure('# Hello\n\n服务端解析一次', md)
+// 将 nodes JSON 下发到客户端
+```
+
+```vue
+<!-- client -->
+<MarkdownRender :nodes="nodesFromServer" />
+```
+
+这样可以避免前端解析，保持 SSR/水合的一致性。
+
+### 混合模式：SSR + 流式续写
+
+- 服务端：解析首批 Markdown，序列化 `initialNodes`（以及 `initialMarkdown`，便于后续流式追加）。
+- 客户端：用相同的解析配置水合，然后继续流式追加：
+
+```ts
+import type { ParsedNode } from 'markstream-vue'
+import { getMarkdown, parseMarkdownToStructure } from 'markstream-vue'
+import { ref } from 'vue'
+
+const nodes = ref<ParsedNode[]>(initialNodes)
+const buffer = ref(initialMarkdown)
+const md = getMarkdown() // 与服务端保持一致
+
+function addChunk(chunk: string) {
+  buffer.value += chunk
+  nodes.value = parseMarkdownToStructure(buffer.value, md)
+}
+```
+
+这样无需重新解析 SSR 内容，同时还能通过 SSE/WebSocket 持续追加后续片段。
+
 ## ⚙️ 性能模式
 
 - **默认虚拟化窗口**：保持 `max-live-nodes` 默认值（`320`），渲染器会立即渲染当前窗口的节点，同时只保留有限数量的 DOM 节点，实现平滑滚动与可控内存，占位骨架极少。
@@ -65,7 +212,108 @@ createApp({
 
 可根据页面类型选择最合适的模式：虚拟化适合长文档/回溯需求，增量流式适合聊天或 AI 输出面板。
 
-## 快速链接
+> 小贴士：聊天场景可使用 `max-live-nodes="0"`，并将 `renderBatchSize` 调小（如 `16`），`renderBatchDelay` 设为较小值（如 `8ms`），获得平滑的“打字”节奏且避免大段跳变。如需限制单帧 CPU，可适当调低 `renderBatchBudgetMs`。
+
+## 🧰 关键属性速览
+
+- `content` 与 `nodes`：传原始 Markdown 或预解析节点（来自 `parseMarkdownToStructure`）。
+- `max-live-nodes`：`320`（默认虚拟化）或 `0`（增量批次）。
+- `batchRendering`：用 `initialRenderBatchSize`、`renderBatchSize`、`renderBatchDelay`、`renderBatchBudgetMs` 微调批次。
+- `enableMermaid` / `enableKatex` / `enableMonaco`：按需启用重型依赖。
+- `parse-options`：在组件上复用解析钩子（如 `preTransformTokens`、`requireClosingStrong`）。
+- `custom-components`：为自定义标签/标记注册内嵌 Vue 组件。
+
+示例：将 Markdown 占位符映射到 Vue 组件
+
+```ts
+import { setCustomComponents } from 'markstream-vue'
+
+setCustomComponents({
+  CALLOUT: () => import('./components/Callout.vue'),
+})
+
+// Markdown: [[CALLOUT:warning title="提示" body="具体内容"]]
+```
+
+或在组件上按需传入：
+
+```vue
+<MarkdownRender
+  :content="doc"
+  :custom-components="{
+    CALLOUT: () => import('./components/Callout.vue'),
+  }"
+/>
+```
+
+解析钩子示例（服务端/客户端保持一致）：
+
+```vue
+<MarkdownRender
+  :content="doc"
+  :parse-options="{
+    requireClosingStrong: true,
+    preTransformTokens: (tokens) => tokens,
+  }"
+/>
+```
+
+## 🔥 适用场景
+
+- AI / 聊天界面：Markdown token 通过 SSE/WebSocket 持续抵达，要求无闪烁与稳定内存。
+- 文档、变更日志、知识库：需要即时加载，同时保持长内容滚动的流畅性。
+- 流式 diff / 代码审查：Monaco 增量更新让大代码块也能跟上变更。
+- 图表与示意：Mermaid 渐进式渲染，避免阻塞主渲染。
+- Markdown 驱动的界面中嵌入 Vue 组件（callout、交互式挂件、CTA 等）。
+
+## ❓ 快问快答
+
+- Mermaid / KaTeX 不显示？安装对应 peer（`mermaid` / `katex`），并传入 `:enable-mermaid="true"` / `:enable-katex="true"` 或调用 loader 设置函数。
+- 体积问题：可选 peer 不会被打包，CSS 只需导入一次；对代码块可用 Shiki（`MarkdownCodeBlockNode`）替代 Monaco 以减轻体积。
+- 自定义 UI：通过 `setCustomComponents`（全局）或 `custom-components` prop 注册组件，在 Markdown 中放置占位标记并映射到 Vue 组件。
+
+## 🆚 为什么选择 markstream-vue，而不是普通 Markdown 渲染器？
+
+| 需求 | 普通 Markdown 预览 | markstream-vue |
+| --- | --- | --- |
+| 流式输入 | 全量重渲染、易闪烁 | 虚拟窗口 + 增量批次 |
+| 大代码块 | 重新高亮速度慢 | Monaco 流式更新 + 可选 Shiki |
+| 图表 | 解析/渲染阻塞 | Mermaid 渐进式渲染与回退 |
+| 自定义 UI | 插槽有限 | Markdown 内嵌 Vue 组件与类型化节点 |
+| 长文档 | 内存峰值高 | 可配置 live-node 上限，滚动稳定 |
+
+## 🗺️ Roadmap（快照）
+
+- 更多「即开即用」模板（Vite / Nuxt / Tailwind）与 StackBlitz 更新。
+- 代码块预设扩展（适合 diff 的 Shiki 主题、Monaco 装饰/标注辅助）。
+- AI / 聊天场景的 Cookbook（SSE/WebSocket、重试与续传、Markdown 中间态处理）。
+- 展示更多在 Markdown 中嵌入 Vue 组件的示例与实践。
+
+## 📦 发布
+
+- 最新版本与升级提示：[Releases](https://github.com/Simon-He95/markstream-vue/releases)
+- 完整历史：[CHANGELOG.md](./CHANGELOG.md)
+- 最新亮点（0.0.3-beta.1/beta.0）：
+  - 解析器升级到 `stream-markdown-parser@0.0.36`，修复多项解析问题。
+  - Monaco 升级，更多语言/主题，代码块对 diff 更友好。
+  - Playground 增加 HTML/SVG 预览对话框与 AST 调试视图。
+
+## 🧭 案例与展示
+
+用 markstream-vue 做了什么？欢迎提 PR 把你的项目放到这里（附链接 + 截图/GIF）。理想场景：AI/聊天界面、流式文档、diff/代码审查、或在 Markdown 驱动页面中嵌入 Vue 组件。
+
+- **FlowNote** —— 流式 Markdown 笔记示例（SSE + 虚拟化窗口）：https://markstream-vue.simonhe.me/
+- **AI Chat 场景** —— playground “test” 页展示增量批次与分享链接：https://markstream-vue.simonhe.me/test
+
+## 介绍视频
+
+一段短视频介绍了 markstream-vue 的关键特性与使用方式。
+
+[![在 Bilibili 查看介绍](https://i1.hdslb.com/bfs/archive/f073718bd0e51acaea436d7197880478213113c6.jpg)](https://www.bilibili.com/video/BV17Z4qzpE9c/)
+
+在 Bilibili 上观看： [Open in Bilibili](https://www.bilibili.com/video/BV17Z4qzpE9c/)
+
+## 核心特性
 
 - ⚡ 极致性能：为流式场景设计的最小化重渲染和高效 DOM 更新
 - 🌊 流式优先：原生支持不完整或频繁更新的 token 化 Markdown 内容
@@ -79,6 +327,25 @@ createApp({
 - 🎨 灵活的代码块渲染：可选 Monaco 编辑器 (`CodeBlockNode`) 或轻量的 Shiki 高亮 (`MarkdownCodeBlockNode`)
 - 🧰 解析工具集：[`stream-markdown-parser`](./packages/markdown-parser) 文档现已覆盖如何在 Worker/SSE 流中复用解析器、直接向 `<MarkdownRender :nodes>` 输送 AST、以及注册全局插件/数学辅助函数的方式。
 
+## 🙌 贡献与社区
+
+- 阅读贡献指南与 PR 模板：[CONTRIBUTING.md](./CONTRIBUTING.md)
+- 遵守 [行为准则](./CODE_OF_CONDUCT.md)。
+- 提交 Issue 时使用模板；渲染问题尽量附上测试页复现链接：https://markstream-vue.simonhe.me/test
+- 有问题先讨论：https://github.com/Simon-He95/markstream-vue/discussions
+- 实时交流：Discord https://discord.gg/vkzdkjeRCW
+- 新手贡献入口：[good first issues](https://github.com/Simon-He95/markstream-vue/labels/good%20first%20issue)
+- 支持与求助入口：[SUPPORT.md](./SUPPORT.md)
+- 提交 PR 时遵循 Conventional Commits，渲染/解析改动补充测试，UI 改动附上截图/GIF。
+- 如果本项目对你有帮助，欢迎点 Star、分享给需要的人，助力项目持续演进。
+- 安全披露：请通过 [SECURITY.md](./SECURITY.md) 中的邮件私下报告潜在漏洞。
+
+### 快速参与的方式
+
+- 在现有 issue 中补充复现链接/截图。
+- 完善文档或示例（尤其是流式 + SSR/Worker 场景）。
+- 分享 playground/test 链接，展示性能边界或有趣用法。
+
 ## 故障排查 & 常见问题
 
 详细故障排查与常见问题已迁移至文档站点：
@@ -87,6 +354,11 @@ https://markstream-vue-docs.simonhe.me/zh/guide/troubleshooting
 如需更多帮助，请到 GitHub Issues 创建问题：
 https://github.com/Simon-He95/markstream-vue/issues
 
+### 快速提交问题
+
+1. 在测试页复现并点击“生成分享链接”：https://markstream-vue.simonhe.me/test
+2. 打开 Bug 模板并附上链接与截图：https://github.com/Simon-He95/markstream-vue/issues/new?template=bug_report.yml
+
 ## 鸣谢
 
 本项目使用并受益于：