markstream-vue 0.0.4-beta.1 → 0.0.4-beta.3

package/README.md

@@ -104,6 +104,38 @@ enableMermaid()
 enableKatex()
 ```
 
+If you load KaTeX via CDN and want KaTeX rendering in a Web Worker (no bundler / optional peer not installed), inject a CDN-backed worker:
+
+```ts
+import { createKaTeXWorkerFromCDN, setKaTeXWorker } from 'markstream-vue'
+
+const { worker } = createKaTeXWorkerFromCDN({
+  mode: 'classic',
+  // UMD builds used by importScripts() inside the worker
+  katexUrl: 'https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.js',
+  mhchemUrl: 'https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/contrib/mhchem.min.js',
+})
+
+if (worker)
+  setKaTeXWorker(worker)
+```
+
+If you load Mermaid via CDN and want off-main-thread parsing (used by progressive Mermaid rendering), inject a Mermaid parser worker:
+
+```ts
+import { createMermaidWorkerFromCDN, setMermaidWorker } from 'markstream-vue'
+
+const { worker } = createMermaidWorkerFromCDN({
+  // Mermaid CDN builds are commonly ESM; module worker is recommended.
+  mode: 'module',
+  workerOptions: { type: 'module' },
+  mermaidUrl: 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs',
+})
+
+if (worker)
+  setMermaidWorker(worker)
+```
+
 ### Nuxt quick drop-in
 
 ```ts
@@ -210,6 +242,8 @@ function addChunk(chunk: string) {
 
 This avoids re-parsing SSR content while letting later SSE/WebSocket chunks continue the stream.
 
+> Tip: when you know the stream has ended (the message is complete), use `parseMarkdownToStructure(buffer.value, md, { final: true })` or pass `:final="true"` to the component. This disables mid-state (`loading`) parsing so trailing delimiters (like `$$` or an unclosed code fence) won’t get stuck showing perpetual loading.
+
 ## ⚙️ 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.
@@ -226,6 +260,7 @@ Pick one mode per surface: virtualization for best scrollback and steady memory
 - `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.
+- `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.
 
@@ -274,7 +309,8 @@ Parse hooks example (match server + client):
 
 ## ❓ 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.
+- 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.
 

package/README.zh-CN.md

@@ -103,6 +103,38 @@ enableMermaid()
 enableKatex()
 ```
 
+如果你是用 CDN 引入 KaTeX，并且希望公式在 Web Worker 中渲染（不打包 / 不安装可选 peer），可以注入一个“CDN 加载 KaTeX”的 worker：
+
+```ts
+import { createKaTeXWorkerFromCDN, setKaTeXWorker } from 'markstream-vue'
+
+const { worker } = createKaTeXWorkerFromCDN({
+  mode: 'classic',
+  // worker 内通过 importScripts() 加载的 UMD 构建
+  katexUrl: 'https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.js',
+  mhchemUrl: 'https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/contrib/mhchem.min.js',
+})
+
+if (worker)
+  setKaTeXWorker(worker)
+```
+
+如果你是用 CDN 引入 Mermaid，并且希望 Mermaid 的解析在 worker 中进行（用于渐进式 Mermaid 渲染的后台解析），可以注入 Mermaid parser worker：
+
+```ts
+import { createMermaidWorkerFromCDN, setMermaidWorker } from 'markstream-vue'
+
+const { worker } = createMermaidWorkerFromCDN({
+  // Mermaid CDN 构建通常是 ESM，推荐 module worker。
+  mode: 'module',
+  workerOptions: { type: 'module' },
+  mermaidUrl: 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs',
+})
+
+if (worker)
+  setMermaidWorker(worker)
+```
+
 ### Nuxt 快速接入
 
 ```ts
@@ -209,6 +241,8 @@ function addChunk(chunk: string) {
 
 这样无需重新解析 SSR 内容，同时还能通过 SSE/WebSocket 持续追加后续片段。
 
+> 提示：当你明确知道流已结束（消息已完整）时，建议用 `parseMarkdownToStructure(buffer.value, md, { final: true })` 或在组件上设置 `:final="true"`，以关闭解析器的中间态（loading）策略，避免末尾残留分隔符（如 `$$`、未闭合 code fence）导致永久 loading。
+
 ## ⚙️ 性能模式
 
 - **默认虚拟化窗口**：保持 `max-live-nodes` 默认值（`320`），渲染器会立即渲染当前窗口的节点，同时只保留有限数量的 DOM 节点，实现平滑滚动与可控内存，占位骨架极少。
@@ -225,6 +259,7 @@ function addChunk(chunk: string) {
 - `batchRendering`：用 `initialRenderBatchSize`、`renderBatchSize`、`renderBatchDelay`、`renderBatchBudgetMs` 微调批次。
 - `enableMermaid` / `enableKatex` / `enableMonaco`：按需启用重型依赖。
 - `parse-options`：在组件上复用解析钩子（如 `preTransformTokens`、`requireClosingStrong`）。
+- `final`：标记“最终态/流结束”，关闭中间态 loading 解析并强制收敛未闭合结构。
 - `custom-html-tags`：扩展流式 HTML 白名单并将这些标签输出为自定义节点，便于 `setCustomComponents` 直接映射（如 `['thinking']`）。
 - `custom-components`：为自定义标签/标记注册内嵌 Vue 组件。
 
@@ -273,7 +308,8 @@ setCustomComponents({
 
 ## ❓ 快问快答
 
-- Mermaid / KaTeX 不显示？安装对应 peer（`mermaid` / `katex`），并传入 `:enable-mermaid="true"` / `:enable-katex="true"` 或调用 loader 设置函数。
+- 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 组件。