markstream-vue

Markstream Vue 3

ホストアプリが通常の Vue 3 アプリで、一般的に Vite ベースであり、Nuxt ではない場合にこのスキルを使用します。

ワークフロー

1. リポジトリが Vue 3 であり、Nuxt ではないことを確認します。
2. markstream-vue と、必要な機能に必要なオプションのピア依存関係のみをインストールします。
3. リセットCSSの後に markstream-vue/index.css をインポートします。
   • Tailwind または UnoCSS のプロジェクトでは、@import 'markstream-vue/index.css' layer(components); を使用します。
   • ルートの JS インポートではスタイルは注入されません。markstream-vue/index.css または markstream-vue/index.px.css を明示的に使用します。
4. content から始め、表示領域に応じてレンダラーモードを選択します。
   • AI チャットや SSE 出力には mode="chat" を使用します。軽量なバッチを使用し、fade=false と max-live-nodes=0 を設定します。smooth-streaming="auto" は表示中の出力のペースを調整します。
   • リッチなドキュメント表示領域には mode="docs" を使用します。これはデフォルトで、より大きなバッチ、ツールチップ、フェードを有効にします。
   • 表示領域は軽量でもチャットではない場合は、mode="minimal" を使用します。
   • 通常のフェンス付きコードには組み込みの CodeBlockNode が使用されます。オプションのピア依存関係である stream-diffs がインストールされている場合は拡張され、そうでない場合は <pre><code> にフォールバックします。プレーンな経路を強制するには render-code-blocks-as-pre=true を設定します。アプリ側でレンダラーを管理する場合は、スコープを限定した setCustomComponents(...) で code_block を置き換えます。
   • ラッパーに依存するフェード、バッチ処理、遅延処理、仮想化、タイプライター、カスタムコンポーネントなどの機能も無効にできる場合にのみ、dom-mode="minimal" を使用します。それ以外の場合はフル DOM にフォールバックします。
   • typewriter が制御するのは点滅カーソルのみで、デフォルトは false です。高頻度のチャットには typewriter="simple" を推奨します。複雑なインラインカーソルの配置には precise モードを使用します。
   • チャンクの生のタイミングを維持するには :smooth-streaming="false" を設定します。初回画面のコンテンツでも滑らかなペースを強制するには :smooth-streaming="true" を設定します（SSR ではハイドレーションの不一致が発生する可能性があります）。
   • Vue 3（Nuxt を含む）では、smooth-streaming は出力のペースを制御し、fade は不透明度を制御します。両方を同時に有効にできます。mode="chat" では、軽量なデフォルトとして fade=false が維持されます。テキストを徐々に表示したい場合は fade を追加し、アニメーションのコストを重視する場合は無効のままにします。Vue 3 の追加時フェードでは、安定したバッチ（200 ms、50 ms の結合ウィンドウ、テキストノードあたり最大 4 バッチ）が使用されます。後から追加した内容によって、先行するバッチが再開されることはありません。
   • ストリーミングと履歴の復元：チャット UI では、同じ MarkdownRender がストリーミングを開始し、後から final=true になると履歴表示に切り替わります。
     • ストリーミング：mode="chat" と final から始めます。テキストを表示するには fade を追加し、カーソルを表示する場合にのみ typewriter を追加します。
     • 復元後または完了済みのチャット履歴：final=true のときにレイアウト戦略が切り替わらないよう、同じチャット行で mode="chat" を維持します。:smooth-streaming="false" と typewriter=false を使用し、希望する表示開始／表示効果に応じて fade を個別に選択します。意図した視覚的な方針でない限り、ストリーミング状態の反転値に連動させないでください。
     • 軽量な非チャットの復元コンテンツには mode="minimal" を使用します。mode="docs" はリッチなドキュメント表示領域にのみ使用し、既存のチャットメッセージを確定するためには使用しません。
   • アプリでカスタム AST 制御、ワーカーによる事前解析、またはペース調整を超える構造更新が必要な場合にのみ、nodes と final に切り替えます。
   • html-policy のデフォルトが safe になったこと、および mermaid-props によって Mermaid の strict モードがデフォルトで有効になったことに留意してください。
5. 長い AI の会話履歴や既存のメッセージ仮想化機能には、仮想スクロールの経路を選択します。
   • アプリでタイムラインの仮想化をすでに管理していない場合は、MarkstreamVirtualTimeline を優先します。
   • アプリですでに vue-virtual-scroller の DynamicScroller を使用している場合は、useMarkstreamVirtualAdapter() を使い、Markdown の項目に adapter.markdownProps(item, index) をバインドします。
   • 行の装飾も項目の高さに含めるため、タイムラインの外側の行に adapter.measureItem(item, index, el) を設定します。
   • レンダラー要素の現在の offsetHeight ではなく、Markstream が報告する論理高さ（アダプター／仮想化機能を通じた metrics.totalHeight）を使用します。Markdown ノードの仮想化では、表示中のウィンドウのみがマウントされる場合があるためです。
   • スレッドを切り替える際は、スクローラーのキャッシュとともに adapter.captureThreadState() を保存します。Markstream のアンカーを復元する前に、スクローラーのキャッシュを復元します。
6. ローカルでオーバーライドするには custom-id とスコープを限定した setCustomComponents(...) を使用します。リポジトリにアプリレベルのプラグインエントリがすでにある場合は、markstream-vue から { VueRendererMarkdown } をインポートして登録します。
7. 必要最小限の開発、ビルド、または型チェックのコマンドで検証します。

デフォルトの判断

• Vue 3 アプリでは、デフォルトで content を使用します。低レベルのレンダリング用 props を細かく調整する前に、mode を選択してください。
• リッチなドキュメント向けのデフォルト設定を使用する場合に限り、mode を省略してください。
• スムーズなストリーミング（smooth-streaming="auto"）は、typewriter または max-live-nodes <= 0 の場合にデフォルトで有効です。ペース調整の対象は content の経路のみで、nodes モードには影響しません。
• nodes で手動のペース調整を行うには、useSmoothMarkdownStream を直接使用します。チャンクを enqueue() し、完了時に finish() を呼び出し、visible からレンダリングして、最終解析の前に caughtUp を待ちます。
• ストリーミング出力に追従させる非仮想化のチャットスクローラーでは、markstream-vue/utils から useStickToBottom をインポートし、Vue が新しいコンテンツを反映した後に scheduleScrollToBottom() を呼び出します。書き込みをまとめて処理し、手動でのスクロールバックを維持します。トークンごとに scrollIntoView({ behavior: 'smooth' }) を実行しないでください。長い混在タイムラインには、代わりに stick-to-bottom="auto" を指定した MarkstreamVirtualTimeline を使用します。
• ストリーミングと履歴の復元では、同じチャット行に対して同じレンダラーモードを維持します。完了済みの履歴では、ペース調整やカーソルを無効にできます。フェードは独立した視覚的な選択肢で、ストリーミング中も完了後も有効にしておけます。コンテンツを別のリッチドキュメント用サーフェスに移す場合に限り、mode="docs" に切り替えてください。例については docs/guide/ai-chat-streaming.md を参照してください。
• リポジトリですでに共有プラグインのエントリーポイントを使用している場合を除き、コンポーネントはローカルで登録することを推奨します。
• Vue 3 アプリですでにメッセージを仮想化している場合は、外側の仮想化機能に処理を任せ、大きな Markdown メッセージに限り virtual-scroll を有効にしてください。
• vue-virtual-scroller では、sessionKey をコンテンツの識別情報（thread:item:revision）に、measurementKey を幅、テーマ、フォント、密度などのレイアウトの識別情報に関連付けてください。
• 強化されたコードブロックでアプリレベルの事前読み込みが必要な場合は、preloadCodeBlockRuntime を使用してください。意図的に低レベルのコントローラーを使用する場合は、stream-diffs から高度な API を直接インポートしてください。markstream-vue の raw-runtime getter には依存しないでください。
• Vue 3 の強化コード用サーフェスでは stream-diffs のみを使用します。stream-monaco はインストールしないでください。
• Vue 3 で大きなコードブロック（数万行）を扱う場合は、markstream-vue の setStreamDiffsWorkerPool(...) を使い、上流の @pierre/diffs の WorkerPoolManager を注入して、Shiki のトークン化を Web Worker に委譲してください。ホスト側で独自のバンドラーを使ってプールを構築し（@pierre/diffs/worker/worker.js?worker）、@pierre/diffs を直接の依存関係に追加します。markstream-vue はこれをランタイムオプション workerManager として転送し、アクティブな isDark／theme／themes のテーマが変更されるたびにプールと同期します。注入がない場合、またはプールが利用不可と報告した場合、ハイライト処理はメインスレッドで行われます（動作に変更はありません）。ライブラリ内でワーカーをバンドルしたり起動したりしないでください。
• 組み込みサーフェスは、トップレベルの code-block-options または直接の CodeBlockNode.codeBlockOptions で設定します。ヘッダー／ツールバーの props は code-block-props に維持してください。Markstream はテーマ、コード／言語、ストリーミングのライフサイクル、ヘッダー、マウント／表示のタイミング、および破棄の管理を担います。
• タスクで信頼済みのレガシー動作を明示的に維持する場合を除き、html-policy="safe" と Mermaid の strict モードを維持してください。
• 信頼済みのサーフェスで強化前の動作が必要な場合は、html-policy="trusted" と :mermaid-props="{ isStrict: false }" をローカルで指定してオプトアウトし、最終引き継ぎ時に信頼境界を明記してください。
• ホストが実際に Nuxt の場合、SSR 固有の設定は markstream-nuxt に任せてください。

参考にするドキュメント

• docs/guide/quick-start.md
• docs/guide/installation.md
• docs/guide/usage.md
• docs/guide/ai-chat-streaming.md
• docs/guide/performance.md
• docs/guide/component-overrides.md
• docs/guide/code-block-runtime.md