markstream-vue2 0.0.19-beta.9 → 0.0.20

package/README.md

@@ -139,6 +139,55 @@ new Vue({
 }).$mount('#app')
 ```
 
+## Streaming best practices
+
+- For high-frequency SSE / token streaming, prefer parsing outside the renderer and pass `nodes` instead of reparsing the whole `content` string every chunk.
+- Keep `viewport-priority` enabled unless you explicitly want eager rendering. Mermaid / Monaco / D2 blocks now stay idle while offscreen and resume when they approach the viewport.
+
+```vue
+<template>
+  <MarkdownRender
+    :nodes="nodes"
+    :final="final"
+    :viewport-priority="true"
+    :defer-nodes-until-visible="true"
+  />
+</template>
+```
+
+## Heavy-node prop forwarding
+
+`MarkdownRender` can forward framework-level props directly into specialized heavy renderers:
+
+```vue
+<template>
+  <MarkdownRender
+    :content="markdown"
+    :mermaid-props="{
+      showHeader: false,
+      renderDebounceMs: 180,
+      previewPollDelayMs: 500
+    }"
+    :d2-props="{ progressiveIntervalMs: 500 }"
+    :infographic-props="{ showHeader: false }"
+  />
+</template>
+```
+
+Notes:
+- Use kebab-case in templates: `mermaid-props`, `d2-props`, `infographic-props`.
+- These props are forwarded to the built-in Mermaid / D2 / Infographic blocks and to custom `mermaid` / `d2` / `infographic` overrides registered with `setCustomComponents(...)`.
+
+## Mermaid tuning
+
+Common `mermaid-props` keys for streaming scenarios:
+
+- `renderDebounceMs`: delay partial/full progressive work during rapid token bursts.
+- `contentStableDelayMs`: how long source mode waits before auto-switching back to preview when content stabilizes.
+- `previewPollDelayMs`: initial delay before preview polling tries to upgrade a partial preview into a full render.
+- `previewPollMaxDelayMs`: cap for preview polling backoff.
+- `previewPollMaxAttempts`: maximum retry count while the Mermaid source is still incomplete.
+
 ## Build and size checks
 
 ```bash
@@ -174,6 +223,64 @@ Fix: align both to the same version (e.g. `2.6.14` or `2.7.16`).
 Cause: Vue 2.6 + Composition API missing `_setupProxy` patch, or plugin not installed.
 Fix: ensure `@vue/composition-api` is installed + `Vue.use(...)`, and update to the latest markstream-vue2 build.
 
+### Custom node renders trigger `infinite update loop`
+Cause: in Vue 2.6 / Vue CLI 4, recursively mounting another `MarkdownRender` inside a custom node component can create a render loop when the parent renderer is still streaming.
+Fix: prefer `NestedRenderer` for nested streaming content. If you only need static HTML output, `renderNestedMarkdownToHtml(...)` is still available.
+
+```ts
+import { NestedRenderer } from 'markstream-vue2'
+
+export default {
+  components: { NestedRenderer },
+  props: {
+    node: { type: Object, required: true },
+  },
+}
+```
+
+```vue
+<template>
+  <NestedRenderer
+    :node="node"
+    custom-id="chat-demo"
+    :custom-html-tags="['thinking']"
+    :typewriter="false"
+    :batch-rendering="false"
+    :viewport-priority="false"
+    :defer-nodes-until-visible="false"
+  />
+</template>
+```
+
+`NestedRenderer` keeps the inner content streamable, but switches the nested renderer to the `nodes` path so Vue 2.6 does not recurse through a second `content`-driven renderer.
+
+If you cannot mount another renderer and just need a static nested body, use `renderNestedMarkdownToHtml(...)`:
+
+```ts
+import { renderNestedMarkdownToHtml } from 'markstream-vue2'
+
+export default {
+  props: {
+    node: { type: Object, required: true },
+  },
+  computed: {
+    renderedHtml() {
+      return renderNestedMarkdownToHtml(
+        { node: this.node },
+        {
+          customHtmlTags: ['thinking'],
+          customNodeClass(node) {
+            return node.type === 'thinking' ? 'thinking-node__nested' : ''
+          },
+        },
+      )
+    },
+  },
+}
+```
+
+This keeps deeply nested custom content streamable without recursively mounting a second `content`-driven `MarkdownRender` / `NodeRenderer`.
+
 ## Tailwind
 
 If your app uses Tailwind and you want to avoid shipping duplicated utility CSS, import the Tailwind-ready output instead: