markstream-vue 0.0.7-beta.2 → 0.0.7-beta.4

package/README.md

@@ -100,7 +100,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`, `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., 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.
 
 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`.
 
@@ -111,6 +111,7 @@ Enable heavy peers only when needed:
 ```ts
 import { enableKatex, enableMermaid } from 'markstream-vue'
 import 'markstream-vue/index.css'
+import 'katex/dist/katex.min.css'
 
 // after you install `mermaid` / `katex` peers
 enableMermaid()
@@ -280,32 +281,30 @@ Pick one mode per surface: virtualization for best scrollback and steady memory
 - `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.
+- `enableMermaid` / `enableKatex`: (re)enable heavy peers or custom loaders when needed (pairs with `disableMermaid` / `disableKatex`).
 - `parse-options`: reuse parser hooks (e.g., `preTransformTokens`, `requireClosingStrong`) on the component.
 - `final`: marks end-of-stream; disables mid-state loading parsing and forces unfinished constructs to settle.
 - `custom-html-tags`: extend streaming HTML allowlist for custom tags and emit them as custom nodes for `setCustomComponents` (e.g., `['thinking']`).
-- `custom-components`: register inline Vue components for custom tags/markers.
+- `setCustomComponents(customId?, mapping)`: register inline Vue components for custom tags/markers (scoped by `custom-id` when provided).
 
-Example: map Markdown placeholders to Vue components
+Example: map Markdown placeholders to Vue components (scoped)
 
 ```ts
 import { setCustomComponents } from 'markstream-vue'
 
-setCustomComponents({
+setCustomComponents('docs', {
   CALLOUT: () => import('./components/Callout.vue'),
 })
 
 // Markdown: [[CALLOUT:warning title="Heads up" body="Details here"]]
 ```
 
-Or pass per-renderer:
+Use the same `custom-id` on the renderer:
 
 ```vue
 <MarkdownRender
   :content="doc"
-  :custom-components="{
-    CALLOUT: () => import('./components/Callout.vue'),
-  }"
+  custom-id="docs"
 />
 ```
 
@@ -334,7 +333,7 @@ Parse hooks example (match server + client):
 - Mermaid/KaTeX not rendering? Install the peer (`mermaid` / `katex`) and pass `:enable-mermaid="true"` / `:enable-katex="true"` or call the loader setters. If you load them via CDN script tags, the library will also pick up `window.mermaid` / `window.katex`.
 - CDN + KaTeX worker: if you don't bundle `katex` but still want off-main-thread rendering, create and inject a worker that loads KaTeX via CDN (UMD) using `createKaTeXWorkerFromCDN()` + `setKaTeXWorker()`.
 - 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.
+- Custom UI: register components via `setCustomComponents` (global or scoped), then emit markers/placeholders in Markdown and map them to Vue components.
 
 ## 🆚 Why markstream-vue over a typical Markdown renderer?
 

package/README.zh-CN.md

@@ -101,7 +101,7 @@ createApp({
 }).mount('#app')
 ```
 
-确保在 CSS reset（如 `@tailwind base` 或 `@unocss/reset`）之后导入 `markstream-vue/index.css`，最好放在 `@layer components` 中以避免 Tailwind/UnoCSS 覆盖组件样式。根据需求再按需安装可选 peer 依赖：`stream-monaco`（Monaco 代码块）、`shiki`（Shiki 高亮）、`mermaid`（Mermaid 图表）、`katex`（数学公式）。
+确保在 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 会作用于内部 `.markstream-vue` 容器下，以尽量降低对全局的影响；如果你脱离 `MarkdownRender` 单独使用导出的节点组件，请在外层包一层带 `markstream-vue` 类名的容器。
 
@@ -112,6 +112,7 @@ createApp({
 ```ts
 import { enableKatex, enableMermaid } from 'markstream-vue'
 import 'markstream-vue/index.css'
+import 'katex/dist/katex.min.css'
 
 // 安装对应 peer 后再启用
 enableMermaid()
@@ -281,32 +282,30 @@ function addChunk(chunk: string) {
 - `content` 与 `nodes`：传原始 Markdown 或预解析节点（来自 `parseMarkdownToStructure`）。
 - `max-live-nodes`：`320`（默认虚拟化）或 `0`（增量批次）。
 - `batchRendering`：用 `initialRenderBatchSize`、`renderBatchSize`、`renderBatchDelay`、`renderBatchBudgetMs` 微调批次。
-- `enableMermaid` / `enableKatex` / `enableMonaco`：按需启用重型依赖。
+- `enableMermaid` / `enableKatex`：用于（重新）启用重型依赖或自定义 loader（可与 `disableMermaid` / `disableKatex` 配合）。
 - `parse-options`：在组件上复用解析钩子（如 `preTransformTokens`、`requireClosingStrong`）。
 - `final`：标记“最终态/流结束”，关闭中间态 loading 解析并强制收敛未闭合结构。
 - `custom-html-tags`：扩展流式 HTML 白名单并将这些标签输出为自定义节点，便于 `setCustomComponents` 直接映射（如 `['thinking']`）。
-- `custom-components`：为自定义标签/标记注册内嵌 Vue 组件。
+- `setCustomComponents(customId?, mapping)`：为自定义标签/标记注册内嵌 Vue 组件（传 `custom-id` 可限定作用域）。
 
-示例：将 Markdown 占位符映射到 Vue 组件
+示例：将 Markdown 占位符映射到 Vue 组件（作用域）
 
 ```ts
 import { setCustomComponents } from 'markstream-vue'
 
-setCustomComponents({
+setCustomComponents('docs', {
   CALLOUT: () => import('./components/Callout.vue'),
 })
 
 // Markdown: [[CALLOUT:warning title="提示" body="具体内容"]]
 ```
 
-或在组件上按需传入：
+渲染时使用同一个 `custom-id`：
 
 ```vue
 <MarkdownRender
   :content="doc"
-  :custom-components="{
-    CALLOUT: () => import('./components/Callout.vue'),
-  }"
+  custom-id="docs"
 />
 ```
 
@@ -335,7 +334,7 @@ setCustomComponents({
 - Mermaid / KaTeX 不显示？安装对应 peer（`mermaid` / `katex`），并传入 `:enable-mermaid="true"` / `:enable-katex="true"` 或调用 loader 设置函数。如果你是用 CDN `<script>` 引入，库也会自动读取 `window.mermaid` / `window.katex`。
 - CDN + KaTeX worker：如果你不打包 `katex` 但仍希望公式在 worker 中渲染（不占主线程），可以用 `createKaTeXWorkerFromCDN()` 创建一个“CDN 加载 KaTeX”的 worker，然后通过 `setKaTeXWorker()` 注入。
 - 体积问题：可选 peer 不会被打包，CSS 只需导入一次；对代码块可用 Shiki（`MarkdownCodeBlockNode`）替代 Monaco 以减轻体积。
-- 自定义 UI：通过 `setCustomComponents`（全局）或 `custom-components` prop 注册组件，在 Markdown 中放置占位标记并映射到 Vue 组件。
+- 自定义 UI：通过 `setCustomComponents`（全局或作用域）注册组件，在 Markdown 中放置占位标记并映射到 Vue 组件。
 
 ## 🆚 为什么选择 markstream-vue，而不是普通 Markdown 渲染器？