markstream-nuxt

Markstream Nuxt

ホストアプリが Nuxt で、SSR の境界が重要な場合にこのスキルを使用します。

ワークフロー

1. リポジトリが Nuxt 3 または 4 であることを確認します。
2. markstream-vue と、必要な機能に必要なオプションのピア依存関係のみをインストールします。
3. ブラウザー専用のピア依存関係は、クライアント専用の境界内に配置します。
   • <client-only> ラッパー、.client プラグイン、またはガード付きのセットアップパスを優先します。
4. markstream-vue/index.css を、クライアントセーフなアプリシェルまたはプラグインからインポートします。
   • ルートの JS インポートではスタイルは注入されません。markstream-vue/index.css または markstream-vue/index.px.css を明示的に使用します。
5. content から始め、表示面に応じてレンダラーモードを選び、UI でカスタム AST の制御が必要な場合にのみ nodes と final に移行します。
   • AI チャットまたは SSE 出力には mode="chat" を使用します。軽量なバッチ、fade=false、max-live-nodes=0 が適用されます。smooth-streaming="auto" は、表示される出力の速度を調整します。
   • リッチなドキュメント表示面には mode="docs" を使用します。これがデフォルトで、大きなバッチ、ツールチップ、フェードが有効になります。
   • 軽量な非チャット表示面には mode="minimal" を使用します。
   • 通常のフェンス付きコードには組み込みレンダラーが使われ、オプションのピア依存関係がインストールされている場合は stream-diffs によって機能が強化されます。強制的にプレーンな表示にするには render-code-blocks-as-pre を、スコープを限定したアプリ所有のレンダラーには setCustomComponents(customId, { code_block: ... }) を使用します。
   • typewriter が制御するのは点滅カーソルのみで、デフォルトは false です。高頻度のチャットには typewriter="simple" を優先します。
   • 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 を指定します。
     • 復元するチャット履歴／完了済みのチャット履歴：同じチャット行で mode="chat" を維持し、:smooth-streaming="false" と typewriter=false を使用します。fade は、希望する表示開始時の効果に合わせて個別に選びます。視覚的な方針として意図している場合を除き、ストリーミング状態の反転に連動させないでください。
     • 軽量な非チャットの復元コンテンツには mode="minimal" を使用し、リッチなドキュメント表示面にのみ mode="docs" を使用します。
   • SSR では、初回画面に表示されるコンテンツで smooth-streaming="true" を避けます。auto 内のマウント済みゲートが、ハイドレーションの不一致を防ぎます。
   • html-policy のデフォルトが safe になり、Mermaid の厳格モードが mermaid-props によってデフォルトで有効になっていることを忘れないでください。
6. 最小限の関連する Nuxt の開発、ビルド、または型チェックコマンドで検証します。

デフォルトの判断基準

• 機能の完全性よりも SSR の安全性を優先します。
• 対象のサーフェスでリッチドキュメントのデフォルト設定を使用する場合に限り、mode を省略します。
• スムーズなストリーミングは、マウント時に制御されるため、auto モード（デフォルト）では SSR に安全です。最初の画面に表示する SSR コンテンツでは、smooth-streaming="true" を使用しないでください。マウント済みかどうかの制御を迂回するため、ハイドレーションの不一致や空白のフラッシュが発生する可能性があります。
• 非仮想化チャットスクローラーでは、markstream-vue/utils から useStickToBottom をインポートし、Vue が新しいコンテンツを反映した後に scheduleScrollToBottom() を呼び出します。このコンポーザブルはマウント後にブラウザーのリスナーを登録します。長い複合タイムラインには、stick-to-bottom="auto" を指定して MarkstreamVirtualTimeline を使用します。
• サーバーコードのパスから、インポート時にブラウザーのグローバル変数へアクセスすることは避けてください。
• 拡張コードランタイム、Mermaid ワーカーなど、負荷の大きいピア依存関係は、リポジトリですでに実証済みの SSR パターンがない限り、クライアント専用として扱います。
• 大きなコードブロックでは、オプションのオフスレッドハイライトプール（上流の @pierre/diffs の WorkerPoolManager を基盤とする、markstream-vue の setStreamDiffsWorkerPool）もクライアント専用です。クライアント専用のプラグインまたはコンポーネントで注入し、サーバーコードのパスでは使用しないでください。
• すべての Markstream パッケージの拡張コードブロックでは stream-diffs を使用します。stream-monaco はインストールしないでください。
• サポートされている組み込みのコードサーフェス設定には、トップレベルの code-block-options を使用します。テーマ、コードと言語、ストリーミングのライフサイクル、ヘッダー、マウント、表示、破棄は Markstream の制御下に置いてください。
• 信頼できる従来のレンダリングを維持する場合を除き、html-policy="safe" と Mermaid の厳格モードを維持してください。
• 信頼できるクライアント専用サーフェスで以前の動作が必要な場合は、html-policy="trusted" と :mermaid-props="{ isStrict: false }" をローカルで指定してオプトアウトし、そのサーフェスが信頼できる理由を記載してください。

参考になるドキュメント

• docs/nuxt-ssr.md
• docs/guide/installation.md
• docs/guide/usage.md
• docs/guide/troubleshooting.md