markstream-react

Markstream React

ホストアプリが React または Next の場合に、このスキルを使用して Markstream を安全に接続します。

ワークフロー

1. リポジトリが React 18 以降、またはベータ版レンダラー API に対応した Next ホストであることを確認します。
2. markstream-react と、リクエストされたオプションのピア依存関係のみをインストールします。
3. アプリのシェルまたはクライアントエントリーポイントから markstream-react/index.css をインポートします。
4. レンダリング境界に合ったエントリーポイントを選択します。
   • 通常のクライアントレンダラーには markstream-react を使用します。
   • Next 専用のコンポーネント API には markstream-react/next を使用します。
   • クライアントフックを使わずにサーバーレンダリングする場合は markstream-react/server を使用します。
5. まずは content を使用します。
   • ストリーミングや高頻度の AI 出力では、content を維持し、まず組み込みのスムーズストリーミングを使用します。
     • smoothStreaming="auto" がデフォルトで、typewriter={true} または maxLiveNodes <= 0 の場合に有効になります。
     • typewriter は点滅カーソルのみを制御し、デフォルトは false です。
     • fade はノードの表示時とストリーミングテキストのフェードアニメーションを制御し、デフォルトは true です。
   • ストリーミングと履歴の復元：チャット UI では、同じレンダラーでストリーミングを開始し、後から final={true} にして履歴へ切り替えます。
     • ストリーミング：smoothStreaming="auto"、fade={false}、typewriter={true}。これは慎重を期した表示・パフォーマンス上の選択であり、API の非互換性によるものではありません。このアダプターでは Vue 3 の制限付き追加フェードを採用していないため、両方を有効にする前にアニメーションの動作を確認してください。
     • 履歴の復元：smoothStreaming={false}、fade={true}、typewriter={false}。コンテンツはすでに完成しているため、表示のペース調整は遅くなりますが、フェードによって洗練された表示アニメーションになります。
     • 動的な切り替え：smoothStreaming={isStreaming ? 'auto' : false}、fade={!isStreaming}。
   • ワーカープロセスで事前解析したコンテンツ、共有 AST ストア、またはカスタム AST の制御が必要な場合に限り、nodes と final に移行します。
   • htmlPolicy のデフォルト値は safe になり、Mermaid の厳格モードは mermaidProps を通じてデフォルトで有効になっていることに注意してください。
6. Next の SSR 境界を守ります。
   • ブラウザー専用のピア依存関係を使用する場合は、use client、ssr: false を指定した動的インポート、またはその他のクライアント専用境界を優先します。
7. カスタムパーサーを作成する前に、レンダラーにローカルなコンポーネントを使用します。
   • streamingComponents はパーサーに基づく NodeComponentProps を受け取り、未完了のカスタムタグに対応し、そのキーを有効な customHtmlTags リストに自動的に追加します。
   • htmlComponents はサニタイズ済み HTML 属性と children を受け取ります。パーサーノードや読み込み状態のインターフェースは受け取りません。
   • 型付きマップには defineStreamingComponents(...) と defineHtmlComponents(...) を優先して使用します。
   • 組み込みノードのオーバーライドや共有の互換性登録には、スコープ付きの setCustomComponents を使用します。
   • parseOptions の変換は、移行にトークンや AST の変更が必要な場合に限って使用します。
8. 必要最小限の開発、ビルド、または型チェック用コマンドで検証します。

デフォルトの判断基準

• まずレンダラーの配線を行い、その後に移行時の整理を行います。
• リポジトリですでに react-markdown を使用している場合は、このスキルと markstream-migration を併用してください。
• ほとんどの AI チャット／トークンストリーミング画面では、組み込みのスムーズなストリーミング機能を備えた content を優先してください。
• ストリーミングと履歴の復元：チャットメッセージがストリーミングから履歴に切り替わるとき（例：final が true になるとき）は、プロパティを動的に切り替えてください。ストリーミング中は smoothStreaming="auto"、fade={false}、履歴では smoothStreaming={false}、fade={true} を設定します。詳しい例は docs/guide/ai-chat-streaming.md を参照してください。
• 解析や AST 変換を別のレイヤーが担当している場合に限り、nodes に切り替えてください。
• グローバルレジストリの変更より、レンダラー内のカスタムタグマップを優先してください。
• SSR の問題を解決するために必要な、最小限のクライアント専用境界を使用してください。
• 画面の最初の SSR コンテンツを空の状態から意図的に開始する場合を除き、smoothStreaming={true} は避けてください。auto モードではマウント済みゲートが使用されます。
• 信頼できる従来のレンダリングを維持する場合を除き、htmlPolicy="safe" と Mermaid の strict モードを維持してください。
• 信頼できる画面で以前の動作が必要な場合は、その画面に限って htmlPolicy="trusted" と mermaidProps={{ isStrict: false }} を使用し、その理由を説明してください。

参考になるドキュメント

• docs/guide/react-quick-start.md
• docs/guide/react-installation.md
• docs/guide/react-components.md
• docs/guide/react-next-ssr.md
• docs/guide/react-markdown-migration.md
• docs/guide/component-overrides.md