# markstream-install

Adopt this skill: https://proskills.md/skills/other/simon-he95-markstream-vue-agents-skills-markstream-install

Page: https://proskills.md/skills/other/simon-he95-markstream-vue-agents-skills-markstream-install
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .agents/skills/markstream-install/SKILL.md
size: 9207
sha: b9b6107b702be17ee9b531634b522c527a2ea535
upstream: https://github.com/simon-he95/markstream-vue/blob/main/.agents/skills/markstream-install/SKILL.md

```text
---
name: markstream-install
description: Install and wire markstream-vue, markstream-react, markstream-vue2, markstream-angular, markstream-svelte, or markstream-solid into an existing repository. Use when Codex needs to choose the right package, install the smallest framework-specific peer-dependency set, fix CSS/reset order, choose Vue 3 renderer mode and built-in, plain, or custom code-block paths, decide between `content`, `nodes`, and Vue 3 virtual-scroll coordination, or add a minimal working renderer example.
---

# Markstream Install

Use this skill when the task is "add markstream to an app" or "fix a broken markstream install".

Read [references/scenarios.md](references/scenarios.md) before making dependency choices.

## Workflow

1. Detect the target framework and CSS stack.
   - Check `package.json`, app entry files, Tailwind or UnoCSS config, and whether the repo is SSR or streaming-focused.
   - Choose the package that matches the host app: `markstream-vue`, `markstream-vue2`, `markstream-react`, `markstream-angular`, `markstream-svelte`, or `markstream-solid`.
   - Use `markstream-svelte` only for Svelte 5 apps.
   - Detect `solid-js` / `@solidjs/start` before classifying TSX as React. For Solid 1.9/SolidStart, follow [markstream-solid](../markstream-solid/SKILL.md), including workspace-preview dependencies, ESM file workers and scoped SSR configuration.
2. Install the smallest peer set that matches the requested features.
   - Add peers only for features the user actually needs. Check the chosen package's `peerDependencies`; peer availability differs by renderer.
   - Vue 3 fenced code uses the built-in renderer automatically. Add `stream-diffs` for the enhanced File/Diff surface, omit it for automatic `<pre><code>` fallback, or set `render-code-blocks-as-pre` to force the plain path.
   - Add `@antv/infographic` plus `setInfographicLoader(...)` only when infographic fences are needed.
   - Do not install every optional peer by default.
   - For Vue 3 enhanced code-block preloading, use `preloadCodeBlockRuntime` from `markstream-vue`. If the application intentionally owns a runtime controller, import that advanced API directly from `stream-diffs`.
3. Fix CSS order.
   - Put reset styles before Markstream styles.
   - In Tailwind or UnoCSS projects, use `@import 'markstream-*/index.css' layer(components);`.
   - Do not rely on renderer imports to inject CSS; import the package CSS subpath explicitly.
   - Import `katex/dist/katex.min.css` when math is enabled.
4. Add the smallest working render example.
    - Use `content` for static or low-frequency rendering.
    - In Vue 3 apps with long AI conversations, thread restore, or an existing message virtualizer such as `vue-virtual-scroller`, do not stop at a trivial renderer. Use `MarkstreamVirtualTimeline` or `useMarkstreamVirtualAdapter()` and follow `docs/guide/performance.md`.
    - For Vue 3, choose renderer `mode` by surface before tuning lower-level props.
      - `mode="chat"`: AI chat or SSE output; lightweight batches, `fade=false`, `max-live-nodes=0`, and `smooth-streaming="auto"`.
      - `mode="docs"`: rich document surfaces; default mode, larger batches, tooltips, and fade.
      - `mode="minimal"`: lightweight non-chat surfaces.
      - 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.
      - Regular fenced code uses the built-in renderer, enhanced by `stream-diffs` when installed. Use `render-code-blocks-as-pre` for a forced plain path or `setCustomComponents(customId, { code_block: ... })` for a scoped application-owned renderer.
    - For streaming AI chat in other Markstream packages, start with `content` and built-in smooth streaming.
      - Auto mode is the default: `smoothStreaming="auto"` / `smooth-streaming="auto"`.
      - Auto pacing activates when `typewriter=true` or `maxLiveNodes <= 0` / `max-live-nodes <= 0`.
      - `typewriter` only controls the blinking cursor and defaults to `false`.
      - `fade` controls node enter and streamed-text fade animations and defaults to `true`.
      - For high-frequency smooth streams, consider `fade=false` / `:fade="false"` / `[fade]="false"` to avoid fade stacking.
    - **Streaming vs recovering history**: in chat UIs the same renderer starts streaming and later switches to history when `final` becomes `true`.
      - Vue 3 streaming: `mode="chat"`, `final`, optional `fade` for gradual reveal, and optional `typewriter` for a cursor.
      - Vue 3 recovering/completed chat history: keep `mode="chat"` on the same chat row; use `:smooth-streaming="false"`, `typewriter=false`, and choose fade independently; it may remain enabled during both streaming and history display.
      - Use `mode="minimal"` for lightweight non-chat recovered content, and use `mode="docs"` only for rich document surfaces.
      - Other packages streaming: `smoothStreaming="auto"` / `smooth-streaming="auto"`, `fade=false`, `typewriter=true`.
      - Other packages recovering history: `smoothStreaming=false` / `smooth-streaming=false`, `fade=true`, `typewriter=false`.
      - Optional policy for other packages: `smoothStreaming={isStreaming ? 'auto' : false}`, `fade={!isStreaming}`; this is not a required coupling.
    - Use `nodes` + `final` only for worker preparsing, shared AST stores, or custom AST control.
    - In Vue 3, use `typewriter="simple"` for a lightweight cursor on high-frequency streams; use precise mode only when the cursor must follow complex inline layout.
    - For a non-virtual Vue 3 chat scroller, import `useStickToBottom` from `markstream-vue/utils`; call `scheduleScrollToBottom()` after the content update instead of starting a smooth `scrollIntoView()` animation for every token. Use `MarkstreamVirtualTimeline` with `stick-to-bottom="auto"` for long mixed timelines.
    - For manual pacing with `nodes`, use `useSmoothMarkdownStream`: `enqueue()` chunks, `finish()` when done, render from `visible`, wait for `caughtUp` before final parsing.
    - Preserve the default hardening: HTML policies now default to `safe`, and Mermaid runs in strict mode by default.
5. Keep customization scoped.
    - If the task requires overrides, prefer `customId` / `custom-id` plus scoped `setCustomComponents(...)`.
6. Validate.
   - Run the smallest relevant build, typecheck, test, or docs build command.
   - Report which peers were installed, where CSS lives, and whether the repo should later adopt `nodes`.

## Default Decisions

- Prefer the minimal peer set over "install everything".
- For Vue 3, omit `mode` only when the surface should use rich docs defaults.
- Prefer `content` for most streaming chat now that built-in smooth streaming is available across Vue 3, Vue 2, React, Svelte, and Angular.
- Move to `nodes` only when another layer owns parsing or AST transforms.
- For Vue 3 apps that already virtualize messages, keep the outer virtualizer responsible for mounted rows; use Markstream virtual-scroll coordination so item height comes from `metrics.totalHeight`, not the renderer DOM height.
- When using `content` for streaming, smooth streaming (`smooth-streaming="auto"`) is on by default for `typewriter` or `max-live-nodes <= 0`. Set `:smooth-streaming="false"` to preserve raw chunk cadence.
- Streaming vs recovering history: keep the renderer mode stable. In Vue 3, fade is independent of pacing and can stay enabled throughout a stream. The conservative fade-off streaming examples for other packages are not an API restriction; those adapters have not adopted the Vue 3 bounded fade implementation. See `docs/guide/ai-chat-streaming.md` for Vue 3 examples.
- Treat CSS order as a first-class part of installation, not a later cleanup.
- When the request includes SSR, explicitly gate browser-only peers behind client-only boundaries.
- Do not widen HTML or Mermaid security defaults unless the user explicitly needs trusted legacy compatibility.
- Enhanced code blocks in every Markstream package use `stream-diffs`; there is no `stream-monaco` or Shiki direct integration in current versions.
- Direct `CodeBlockNode` and top-level renderer configuration use the same `codeBlockOptions` / `CodeBlockOptions` contract. Keep component chrome in `codeBlockProps`; do not nest runtime options there.
- In Vue 3, large code blocks can be highlighted off the main thread by injecting an upstream `@pierre/diffs` `WorkerPoolManager` through `setStreamDiffsWorkerPool(...)`. The host builds the pool with its own bundler and adds `@pierre/diffs` as a direct dependency. This is a Vue 3-only enhancement; the other framework packages do not expose it.
- If compatibility requires it, scope the opt-out to the trusted surface with `htmlPolicy` / `html-policy="trusted"` and `mermaidProps.isStrict = false` instead of changing app-wide defaults blindly.

## Useful Doc Targets

- `docs/guide/installation.md`
- `docs/guide/usage.md`
- `docs/guide/performance.md`
- `docs/guide/troubleshooting.md`
- `docs/guide/component-overrides.md`
```

## File: .agents/skills/markstream-install/references/scenarios.md
size: 2769
sha: c46a73ff625b75868813d6082ab8c875024feced
upstream: https://github.com/simon-he95/markstream-vue/blob/main/.agents/skills/markstream-install/references/scenarios.md

```text
# Install Scenarios

## Package selection

| Host app | Package |
|----------|---------|
| Vue 3 / Nuxt 3 | `markstream-vue` |
| Vue 2.6 / 2.7 | `markstream-vue2` |
| React 18+ | `markstream-react` |
| Angular 20+ | `markstream-angular` |
| Svelte 5 | `markstream-svelte` |
| SolidJS 1.9 / SolidStart | `markstream-solid` |

## Peer selection

Peer sets are package-specific. Confirm the selected package's current `peerDependencies` before installing anything.

| Feature | Peers | Package notes |
|---------|-------|---------------|
| Enhanced File/Diff and diff code blocks | `stream-diffs` | All packages |
| Mermaid | `mermaid` | All renderer packages |
| D2 | `@terrastruct/d2` | All renderer packages |
| KaTeX math | `katex` | All renderer packages |
| Infographic blocks | `@antv/infographic` | All renderer packages; Vue 3 also requires `setInfographicLoader(...)` |

## CSS checklist

- reset first
- Markstream CSS after reset
- in Tailwind or UnoCSS projects, use `@import '...' layer(components)`
- import KaTeX CSS when math is used
- when standalone node components are rendered directly, wrap them with the package root class such as `.markstream-vue`, `.markstream-react`, or `.markstream-svelte`

## Input choice

- `content`: docs pages, static articles, low-frequency updates, and most SSE / token streaming / AI chat surfaces.
- `content` + built-in smooth streaming: jittery AI streams where visible output should be paced independently from raw chunk cadence.
  - `smoothStreaming="auto"` / `smooth-streaming="auto"` is the default.
  - Auto mode enables pacing when `typewriter=true` or `maxLiveNodes <= 0` / `max-live-nodes <= 0`.
  - `typewriter` only controls the blinking cursor and defaults to `false`.
  - `fade` controls node enter and streamed-text fade animations. Vue 3 `chat`/`minimal` modes default it to `false`; Vue 3 `docs` mode defaults it to `true`.
  - 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.
- `nodes` + `final`: worker-preparsed content, shared AST stores, custom AST transforms, or cases where another layer already owns parsing.

## Solid-specific setup

Use the `markstream-solid` skill and [Solid API reference](https://markstream.simonhe.me/guide/solid-api). Use `vite-plugin-solid`, camelCase TSX props/callbacks and accessors. File workers require Vite `worker.format = "es"`; Mermaid inline workers cannot resolve its split diagram modules. Workspace previews require parser/core/Solid tarballs built together; publication requires the corresponding new dependency versions.
```

## File: .agents/skills/markstream-install/agents/openai.yaml
size: 259
sha: b57a12b98d8c173cd6ba01c93973c7d8662f5f7e
upstream: https://github.com/simon-he95/markstream-vue/blob/main/.agents/skills/markstream-install/agents/openai.yaml

```text
interface:
  display_name: Markstream Install
  short_description: Install markstream with the right peers and CSS order
  default_prompt: Use $markstream-install to add the correct Markstream package to this repository with the smallest peer-dependency set.
```

## File: README.md
upstream: https://github.com/simon-he95/markstream-vue/blob/main/README.md

````text
# Markstream — Streaming Markdown renderers for AI chat

Markstream is a streaming Markdown renderer family for Vue, React, Octane, SolidJS, Svelte, Angular, and Vue 2, with AI chat, LLM token streams, SSE/WebSocket output, incomplete Markdown, long AI responses, Mermaid, KaTeX, and streaming code blocks.

Use sibling packages for non-Vue frameworks; use `markstream-vue` when your Vue/Nuxt/VitePress UI needs stable partial Markdown states, mobile WebView rendering, safe component rendering, and progressive heavy blocks.

[![中文版](https://img.shields.io/badge/docs-中文文档-blue)](README.zh-CN.md)
[![Docs](https://img.shields.io/badge/docs-vitepress-blue)](https://markstream.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)

Vue package:

[![markstream-vue npm version](https://img.shields.io/npm/v/markstream-vue?color=a1b858&label=markstream-vue)](https://www.npmjs.com/package/markstream-vue)
[![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)

<a href="https://trendshift.io/repositories/27243?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-27243" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/27243/weekly?language=Vue" alt="Simon-He95%2Fmarkstream-vue | Trendshift" width="250" height="55"/></a>
<a href="https://trendshift.io/repositories/27243?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-27243" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/27243/daily?language=Vue" alt="Simon-He95%2Fmarkstream-vue | Trendshift" width="250" height="55"/></a>
<a href="https://trendshift.io/repositories/27243?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-27243" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/27243/monthly?language=Vue" alt="Simon-He95%2Fmarkstream-vue | Trendshift" width="250" height="55"/></a>

Other packages:

[![markstream-react npm version](https://img.shields.io/npm/v/markstream-react?label=markstream-react)](https://www.npmjs.com/package/markstream-react)
[![markstream-solid npm version](https://img.shields.io/npm/v/markstream-solid?label=markstream-solid)](https://www.npmjs.com/package/markstream-solid)
[![markstream-svelte npm version](https://img.shields.io/npm/v/markstream-svelte?label=markstream-svelte)](https://www.npmjs.com/package/markstream-svelte)
[![markstream-angular npm version](https://img.shields.io/npm/v/markstream-angular?label=markstream-angular)](https://www.npmjs.com/package/markstream-angular)
[![markstream-vue2 npm version](https://img.shields.io/npm/v/markstream-vue2?label=markstream-vue2)](https://www.npmjs.com/package/markstream-vue2)

[![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)

## Install markstream-vue

Markstream 2.x is stable on npm's `latest` tag:

```bash
pnpm add markstream-vue
```

Add the optional `stream-diffs` peer only when you need enhanced code and diff blocks. `markstream-vue@1` pins the maintained 1.x line; it is also preserved on the `legacy` npm tag, with 1.x prereleases on `legacy-next`. See the [1.x to 2.0 migration guide](https://markstream.simonhe.me/guide/migration-2-0) for the code-block runtime changes.

For applications that must stay on the 1.x line across the 2.x cutover:

```bash
pnpm add markstream-vue@1
```

```vue
<script setup lang="ts">
import MarkdownRender from 'markstream-vue'
import 'markstream-vue/index.css'

defineProps<{
  content: string
  isDone: boolean
}>()
</script>

<template>
  <MarkdownRender mode="chat" :content="content" :final="isDone" />
</template>
```

## Why not marked / markdown-it / react-markdown?

Use `marked`, `markdown-it`, or `react-markdown` for finished Markdown documents.

Use Markstream when the Markdown is still changing while the user is reading it.

Detailed comparisons: [vue-stream-markdown](https://markstream.simonhe.me/compare/vue-stream-markdown), [Streamdown](https://markstream.simonhe.me/compare/streamdown), [react-markdown](https://markstream.simonhe.me/compare/react-markdown), and [marked / markdown-it](https://markstream.simonhe.me/compare/marked-markdown-it).

## Packages

Start with the [framework overview](https://markstream.simonhe.me/frameworks) if you are choosing between packages.

| Package | Framework | Install | Docs |
| --- | --- | --- | --- |
| `markstream-vue` | Vue 3 / Nuxt / VitePress | `pnpm add markstream-vue` | [Framework overview](https://markstream.simonhe.me/frameworks) · [Vue landing](https://markstream.simonhe.me/frameworks/vue) · [Nuxt landing](https://markstream.simonhe.me/frameworks/nuxt) |
| `markstream-react` | React / Next.js / Remix | `pnpm add markstream-react` | [React landing](https://markstream.simonhe.me/frameworks/react) · [Next.js landing](https://markstream.simonhe.me/frameworks/next) |
| `markstream-octane` | Octane | `pnpm add markstream-octane octane` | [Package guide](./packages/markstream-octane/README.md) · [Online playground](https://markstream-octane.pages.dev/) · [Local playground](./playground-octane) |
| `markstream-solid` | SolidJS 1.9 / SolidStart | `pnpm add markstream-solid solid-js@^1.9` | [Solid guide](https://markstream.simonhe.me/guide/solid) · [Components and API](https://markstream.simonhe.me/guide/solid-api) |
| `markstream-svelte` | Svelte 5 | `pnpm add markstream-svelte svelte@^5` | [Svelte landing](https://markstream.simonhe.me/frameworks/svelte) · [Quick start](https://markstream.simonhe.me/guide/svelte) |
| `markstream-angular` | Angular standalone | `pnpm add markstream-angular` | [Angular landing](https://markstream.simonhe.me/frameworks/angular) · [Quick start](https://markstream.simonhe.me/guide/angular-quick-start) |
| `markstream-vue2` | Vue 2.6 / 2.7 | `pnpm add markstream-vue2` | [Vue 2 landing](https://markstream.simonhe.me/frameworks/vue2) · [Quick start](https://markstream.simonhe.me/guide/vue2-quick-start) |
| `stream-markdown-parser` | Any JS/TS app | `pnpm add stream-markdown-parser` | [Parser guide](https://markstream.simonhe.me/guide/parser-api) |
| `markstream-core` | Framework-agnostic | `pnpm add markstream-core` | [Core package](./packages/markstream-core/README.md) |

### Which package should I use?

- **Vue 3 / Nuxt / VitePress** → `markstream-vue`
- **React / Next.js / Remix** → `markstream-react`
- **Octane** → `markstream-octane`
- **SolidJS 1.9 / SolidStart** → `markstream-solid`
- **Svelte 5** → `markstream-svelte`
- **Angular standalone** → `markstream-angular`
- **Vue 2.6 / 2.7** → `markstream-vue2`
- **Framework-agnostic parsing only** → `stream-markdown-parser`
- **Streaming controller utilities** → `markstream-core`

## Stability

`markstream-vue` 2.x is stable and published on npm's `latest` tag. The ma
````
