opencode-skills-collection 4.0.5 → 4.0.6

package/bundled-skills/markstream-install/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: markstream-install
+description: "Install and configure Markstream streaming Markdown renderers for Vue, React, Svelte, Angular, Nuxt, Next.js, and Vue 2 applications."
+category: frontend
+risk: safe
+source: https://github.com/Simon-He95/markstream-vue/tree/main/.agents/skills/markstream-install
+source_repo: Simon-He95/markstream-vue
+source_type: official
+date_added: "2026-07-19"
+author: Simon-He95
+tags: [markdown, streaming, vue, react, svelte, angular, ai-chat]
+tools: [claude, cursor, gemini, codex]
+license: MIT
+license_source: https://github.com/Simon-He95/markstream-vue/blob/main/license
+---
+
+# Markstream Install
+
+## Overview
+
+Integrate the correct [Markstream](https://github.com/Simon-He95/markstream-vue) streaming Markdown renderer into an existing frontend application. This skill selects the framework package, installs only requested optional peers, preserves safe HTML and Mermaid defaults, and handles CSS, streaming state, and SSR boundaries.
+
+Read [references/scenarios.md](references/scenarios.md) before selecting packages or optional peers.
+
+## When to Use
+
+Use this skill when the user asks to:
+
+- add streaming Markdown rendering to an AI chat or document interface;
+- install Markstream in Vue, Nuxt, React, Next.js, Svelte, Angular, or Vue 2;
+- repair missing Markstream styles, an incorrect framework package, or an SSR failure;
+- replace another Markdown renderer with Markstream;
+- choose between static content, built-in smooth streaming, or externally parsed AST input.
+
+## How It Works
+
+### 1. Inspect the host application
+
+Before changing dependencies, inspect:
+
+- the framework and version in `package.json`;
+- the existing package-manager lockfile;
+- whether the application uses SSR;
+- reset, Tailwind, UnoCSS, or design-system styles;
+- required optional features such as highlighted code, Monaco, Mermaid, D2, or KaTeX.
+
+Do not select `markstream-vue` merely because the source repository has Vue in its name. Choose the framework-specific package from the scenario table.
+
+### 2. Install the smallest dependency set
+
+Install exactly one framework package and preserve the repository's package manager. Add optional peers only when the requested UI uses their feature.
+
+Examples:
+
+```bash
+npm install markstream-vue
+npm install markstream-react
+npm install markstream-svelte
+npm install markstream-angular
+npm install markstream-vue2
+```
+
+For Vue 2.6, also install and register `@vue/composition-api`. Vue 2.7 has a built-in Composition API and must not install that plugin.
+
+### 3. Wire styles in the correct order
+
+Import application resets before Markstream styles. Import package CSS explicitly instead of relying on component imports to inject it.
+
+For Tailwind or UnoCSS, put the matching package stylesheet in a component layer:
+
+```css
+@import 'markstream-vue/index.css' layer(components);
+```
+
+When math rendering is enabled, also import:
+
+```css
+@import 'katex/dist/katex.min.css';
+```
+
+Vue CLI 4 and other Webpack 4-based Vue 2 projects do not understand package export maps. Use the published file path in those projects:
+
+```ts
+import 'markstream-vue2/dist/index.css'
+```
+
+### 4. Add the smallest working renderer
+
+Prefer `content` for static documents and most streaming chat interfaces. Markstream's built-in smooth streaming can pace irregular token delivery without requiring the host application to maintain an AST.
+
+Use `nodes` plus `final` only when a worker, shared AST store, custom transform, or another application layer already owns parsing.
+
+### 5. Handle framework boundaries
+
+- In Nuxt, keep browser-only optional peers behind client boundaries.
+- In Next.js, use root `markstream-react` inside a `'use client'` component for live SSE or WebSocket streams.
+- Use `markstream-react/next` for SSR-first HTML with hydration and `markstream-react/server` for server-only rendering.
+- Use `markstream-svelte` only with Svelte 5.
+- Confirm the host meets the current `markstream-angular` version requirement.
+- In Vue 3, use `mode="chat"` for AI chat, `mode="docs"` for rich documents, and `mode="minimal"` for lightweight non-chat surfaces.
+
+### 6. Preserve safe defaults
+
+HTML policy defaults to `safe`, and Mermaid uses strict mode. Do not broaden either setting unless the user explicitly identifies a trusted legacy surface that requires it. Scope any exception to that surface.
+
+### 7. Validate
+
+Run the smallest relevant build, typecheck, or test command. Confirm:
+
+1. the selected package matches the framework;
+2. only requested optional peers were added;
+3. styles load after resets;
+4. SSR pages do not evaluate browser-only peers on the server;
+5. static content and at least one incremental update render correctly.
+
+Report the selected package, added peers, CSS location, streaming input choice, and validation command.
+
+## Examples
+
+### Vue 3 streaming chat
+
+```vue
+<MarkdownRender
+  mode="chat"
+  :content="markdown"
+  :final="false"
+  smooth-streaming="auto"
+  :fade="false"
+  typewriter
+/>
+```
+
+### Vue 3 completed chat history
+
+```vue
+<MarkdownRender
+  mode="chat"
+  :content="markdown"
+  :final="true"
+  :smooth-streaming="false"
+  :fade="true"
+  :typewriter="false"
+/>
+```
+
+Setting `final=true` tells the parser that the document is complete; disabling pacing alone does not finalize trailing constructs.
+
+## Best Practices
+
+- Install the minimal peer set instead of every optional integration.
+- Keep the renderer mode stable when a chat message transitions from streaming to history.
+- Let an existing outer message virtualizer own mounted rows; coordinate Markstream height metrics instead of adding a competing virtualizer.
+- Scope component overrides with `customId` or `custom-id` when multiple render surfaces coexist.
+- Test SSR and incremental client updates separately.
+
+## Limitations
+
+- This skill does not choose application-specific visual styling or chat architecture.
+- Optional browser-heavy peers can require framework-specific client boundaries and bundler configuration.
+- Vue 2.6 and legacy Webpack projects require the compatibility steps documented above.
+- Current package and framework requirements must be checked against the host lockfile and Markstream documentation before installation.
+
+## Security & Safety Notes
+
+- Package installation changes the dependency manifest and lockfile. Review the proposed package set before running the install command.
+- Do not enable trusted HTML or non-strict Mermaid rendering for untrusted model output.
+- Keep optional browser runtimes out of server-only execution paths.
+- Run installs only inside the intended project directory and use its existing package manager.
+
+## Common Pitfalls
+
+- **Problem:** Styles appear missing or are overwritten.
+  **Solution:** Load resets first, then the matching Markstream stylesheet explicitly.
+- **Problem:** A completed response still looks incomplete.
+  **Solution:** Set `final=true` when the stream finishes, not only `smoothStreaming=false`.
+- **Problem:** Next.js evaluates browser-only code on the server.
+  **Solution:** Select the root, `/next`, or `/server` entry according to the render boundary.
+- **Problem:** Lightweight highlighting does not activate after installing `stream-markdown`.
+  **Solution:** On Vue, Vue 2, or React, configure `MarkdownCodeBlockNode` as the `code_block` override.
+
+## Additional Resources
+
+- [Installation](https://markstream.simonhe.me/guide/installation)
+- [AI chat and streaming](https://markstream.simonhe.me/guide/ai-chat-streaming)
+- [Performance](https://markstream.simonhe.me/guide/performance)
+- [Troubleshooting](https://markstream.simonhe.me/guide/troubleshooting)
+- [Component overrides](https://markstream.simonhe.me/guide/component-overrides)

package/bundled-skills/markstream-install/references/scenarios.md

@@ -0,0 +1,48 @@
+# Install Scenarios
+
+## Package selection
+
+| Host app | Package and setup |
+|----------|-------------------|
+| Vue 3 / Nuxt 3 or 4 | `markstream-vue` |
+| Vue 2.6 | `markstream-vue2` plus `@vue/composition-api`; register the plugin before mounting the app |
+| Vue 2.7 | `markstream-vue2`; use Vue's built-in Composition API and do not install `@vue/composition-api` |
+| React 18+ / Next.js | `markstream-react` |
+| Angular 20+ | `markstream-angular` |
+| Svelte 5 | `markstream-svelte` |
+
+## Peer selection
+
+| Feature | Peer | Supported packages | Activation |
+|---------|------|--------------------|------------|
+| Lightweight highlighted code blocks | `stream-markdown` | `markstream-vue`, `markstream-vue2`, `markstream-react` | Configure the package's `MarkdownCodeBlockNode` as the `code_block` override |
+| Monaco-powered code blocks | `stream-monaco` | All framework packages | Install only when Monaco interactions are required |
+| Mermaid diagrams | `mermaid` | All framework packages | Install when Mermaid fences are rendered |
+| D2 diagrams | `@terrastruct/d2` | All framework packages | Install when D2 fences are rendered |
+| KaTeX math | `katex` | All framework packages | Install and load KaTeX CSS when math is rendered |
+
+## CSS checklist
+
+- Load reset styles first.
+- Load the framework-specific Markstream CSS after the reset.
+- In Tailwind or UnoCSS projects, use `@import '...' layer(components)`.
+- Import KaTeX CSS when math is enabled.
+- When rendering standalone node components directly, wrap them with the relevant package root class such as `.markstream-vue`, `.markstream-react`, or `.markstream-svelte`.
+
+## Input choice
+
+- `content`: static documents, low-frequency updates, and most SSE or token-streaming chat surfaces.
+- `content` with built-in smooth streaming: irregular AI streams whose visible output should be paced independently from raw chunk cadence.
+  - `smoothStreaming="auto"` or `smooth-streaming="auto"` is the default.
+  - Auto pacing activates when `typewriter=true` or `maxLiveNodes <= 0` / `max-live-nodes <= 0`.
+  - `typewriter` controls the cursor and defaults to `false`.
+  - `fade` controls node-entry and streamed-text fade effects.
+- `nodes` plus `final`: worker-preparsed content, shared AST stores, custom AST transforms, or cases where another layer already owns parsing.
+
+## Next.js entry selection
+
+| Surface | Entry |
+|---------|-------|
+| Live SSE or WebSocket output in a Client Component | `markstream-react` |
+| SSR-first HTML with client hydration | `markstream-react/next` |
+| Server-only Markdown rendering | `markstream-react/server` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-collection",
-  "version": "4.0.5",
+  "version": "4.0.6",
   "description": "OpenCode CLI plugin that automatically downloads and keeps skills up to date.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills_index.json

@@ -27550,6 +27550,41 @@
       "reasons": []
     }
   },
+  {
+    "id": "markstream-install",
+    "path": "skills/markstream-install",
+    "category": "frontend",
+    "name": "markstream-install",
+    "description": "Install and configure Markstream streaming Markdown renderers for Vue, React, Svelte, Angular, Nuxt, Next.js, and Vue 2 applications.",
+    "risk": "safe",
+    "source": "https://github.com/Simon-He95/markstream-vue/tree/main/.agents/skills/markstream-install",
+    "date_added": "2026-07-19",
+    "plugin": {
+      "targets": {
+        "codex": "supported",
+        "claude": "supported"
+      },
+      "setup": {
+        "type": "none",
+        "summary": "",
+        "docs": null
+      },
+      "reasons": []
+    },
+    "source_type": "official",
+    "source_repo": "Simon-He95/markstream-vue",
+    "license": "MIT",
+    "license_source": "https://github.com/Simon-He95/markstream-vue/blob/main/license",
+    "tags": [
+      "markdown",
+      "streaming",
+      "vue",
+      "react",
+      "svelte",
+      "angular",
+      "ai-chat"
+    ]
+  },
   {
     "id": "mason",
     "path": "skills/agent-squad/mason",