Markstream Vue

Markstream Vue 3

Use this skill when the host app is plain Vue 3, typically Vite-based, and not Nuxt.

Workflow

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, use @import 'markstream-vue/index.css' layer(components);.
   • The root JS import does not inject styles; use markstream-vue/index.css or markstream-vue/index.px.css explicitly.
4. Start with content and choose the renderer mode by surface.
   • Use mode="chat" for AI chat or SSE output. It uses lightweight batches, fade=false, and max-live-nodes=0; smooth-streaming="auto" paces visible output.
   • Use mode="docs" for rich document surfaces. It is the default and enables larger batches, tooltips, and fade.
   • Use mode="minimal" when the surface is lightweight but not chat.
   • Regular fenced code uses the built-in CodeBlockNode, enhanced by stream-diffs when that optional peer is installed and otherwise falling back to <pre><code>. Set render-code-blocks-as-pre=true to force the plain path, or replace code_block through scoped setCustomComponents(...) when the app owns the renderer.
   • Use dom-mode="minimal" only when the surface can also disable wrapper-dependent features such as fade, batching, deferral, virtualization, typewriter, and custom components; otherwise it falls back to full DOM.
   • typewriter only controls the blinking cursor and defaults to false. Prefer typewriter="simple" for high-frequency chat and precise mode for complex inline cursor placement.
   • 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).
   • In Vue 3 (including Nuxt), smooth-streaming controls output pacing and fade controls opacity; they can be enabled together. mode="chat" keeps fade=false as a lightweight default. Add fade when gradual text reveal is desired; keep it off when animation cost matters more. Vue 3 append fades use stable batches (200 ms, 50 ms coalescing window, at most four batches per text node); later appends do not restart earlier batches.
   • Streaming vs recovering history: in chat UIs the same MarkdownRender starts streaming and later switches to history when final=true.
     • Streaming: start with mode="chat" and final; add fade for text reveal and typewriter only when a cursor is wanted.
     • Recovering/completed chat history: keep mode="chat" on the same chat row to avoid switching layout strategy when final=true; use :smooth-streaming="false", typewriter=false, and choose fade independently for the desired entry/reveal effect. Do not bind it to the inverse of streaming state unless that visual policy is intentional.
     • Use mode="minimal" for lightweight non-chat recovered content, and use mode="docs" only for rich document surfaces, not for finalizing an existing chat message.
   • 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. For long AI transcripts or existing message virtualizers, choose the virtual-scroll path.
   • Prefer MarkstreamVirtualTimeline when the app does not already own timeline virtualization.
   • If the app already uses vue-virtual-scroller DynamicScroller, use useMarkstreamVirtualAdapter() and bind adapter.markdownProps(item, index) to Markdown items.
   • Put adapter.measureItem(item, index, el) on the outer timeline row so row chrome is included in item height.
   • Use Markstream's reported logical height (metrics.totalHeight through the adapter/virtualizer), not the renderer element's current offsetHeight, because Markdown node virtualization may only mount the live window.
   • On thread switches, save adapter.captureThreadState() together with the scroller cache; restore the scroller cache before restoring the Markstream anchor.
6. Use custom-id plus scoped setCustomComponents(...) for local overrides, or import { VueRendererMarkdown } from markstream-vue and install it when the repo already has an app-level plugin entry.
7. Validate with the smallest useful dev, build, or typecheck command.