markstream-react

Markstream React 是一个用于在 React 或 Next 宿主应用中安全接入 Markstream 的技能。适用前提是宿主应用为 React 18+ 或兼容的 Next，并且可以接受 beta 渲染器 API。

用途

该技能用于将 beta 版 markstream-react 包集成到 React 18+ 或 Next 应用中。当宿主应用是 React 或 Next，并且任务需要安全接入 Markstream 渲染器时使用。

确认仓库为 React 18+ 或兼容的 Next 宿主，并接受 beta 渲染器 API。
安装 markstream-react 以及仅被请求的可选 peer 依赖。
从应用外壳或客户端入口导入 markstream-react/index.css。
根据渲染边界选择入口点：常规客户端渲染使用 markstream-react；Next 专用组件接口使用 markstream-react/next；无客户端 hooks 的服务端渲染使用 markstream-react/server。
从 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}。内容已经完整，节奏控制会拖慢速度，但 fade 可提供精致的进入动画。
动态切换：smoothStreaming={isStreaming ? 'auto' : false}，fade={!isStreaming}。
仅在内容由 worker 预处理、共享 AST 存储或需要自定义 AST 控制时，才转向 nodes + final。
htmlPolicy 现在默认值为 safe，Mermaid 严格模式通过 mermaidProps 默认开启。

在 Next 中尊重 SSR 边界。当涉及仅浏览器可用的 peer 依赖时，优先使用 use client、ssr: false 的动态导入或其他仅客户端边界。

在自定义解析器工作之前，优先使用渲染器本地组件。
streamingComponents 接收由解析器支持的 NodeComponentProps，支持不完整的自定义标签，并自动将其键贡献到有效的 customHtmlTags 列表。
htmlComponents 接收经过清理的 HTML 属性以及 children；它不接收解析器 node/loading 契约。
优先使用 defineStreamingComponents(...) 和 defineHtmlComponents(...) 获得类型化映射。
对于内置节点覆盖或共享兼容性注册，保留作用域内的 setCustomComponents。
仅当迁移需要 token 或 AST 变更时，才使用 parseOptions 转换。
用最小的有效 dev、build 或 typecheck 命令进行验证。

先完成渲染器接入，再处理迁移清理。
如果仓库已使用 react-markdown，可将此技能与 markstream-migration 搭配使用。
对于大多数 AI 聊天或 token 流式场景，优先使用 content 与内置平滑流式。
流式与恢复历史：当聊天消息从流式转为历史（例如 final 变为 true）时，动态切换 props——流式时 smoothStreaming="auto"、fade={false}；历史时 smoothStreaming={false}、fade={true}。完整示例见 docs/guide/ai-chat-streaming.md。
仅当另一层负责解析或 AST 转换时才转向 nodes。
优先使用渲染器本地的自定义标签映射，而非全局注册表变更。
优先使用能解决 SSR 问题的最小仅客户端边界。
除非有意从空白开始，否则避免对首屏 SSR 内容使用 smoothStreaming={true}；auto 模式使用 mounted 门控。
除非请求是保留受信任的旧版渲染，否则保持 htmlPolicy="safe" 和 Mermaid 严格模式。
如果受信任表面需要旧行为，仅在该表面使用 htmlPolicy="trusted" 和 mermaidProps={{ isStrict: false }}，并说明原因。