ai-shifu/markdown-flow-ui/content-render-typewriter-stream-story

ContentRender 打字机流式 story

核心规则

当目标是验证阅读模式里的流式文本体验时，优先把打字机能力沉淀为 ContentRender 的可选配置项，并保持默认关闭；story 只负责复现“源流到达”，不要让未传配置的 ContentRender 偏离原有即时渲染行为。

工作流

1. 将后端返回的原始文本片段定义为独立 fixture 常量，保持“多数情况下按句到达”的真实形态。
2. 若项目里已经有 tests/fixtures/ai-shifu-run-stream.sse 这类 SSE fixture，优先通过 ?raw 导入原始文本，再按 data: 行解析成事件并抽取真实 text 元素内容，不要手写一份近似文案。
3. 在 ContentRender 上增加类似 typewriter 的可选 prop，至少包含开关和节奏参数；默认不传时应继续直接渲染 content。
4. 组件内部处理 append-only 文本逐步显示时，优先兼容内容持续追加的场景；若流式内容不是追加关系，应安全回退，不要让普通渲染卡住。
5. story preview wrapper 里只保留“后端分段到达”的状态，真正的逐字显示由 ContentRender 配置项接管。
6. 若需要强调体验差异，可在 story 中同时展示“后端已收到全文”和“当前已到达组件的流式 payload”两个面板，方便肉眼对比。
7. story 命名保持英文，名称直接体现 typewriter 或 streaming 语义。
8. 如果目标是复现 ai-shifu 学习页，优先按真实 element 事件流逐条回放，而不是把所有文本先拼成一个大字符串；text、html 等 block 要分别渲染。
9. 学习页型 story 需要把“内容块 + 追问入口”一起展示，追问按钮应跟随每个已渲染内容块出现，方便核对真实阅读模式的节奏与结构。
10. 当 story 要模拟学习页追问按钮时，按钮出现时机必须跟随 block 完成态：text 要等打字机结束，html/其他静态块要等该 element 不再继续收到流式更新后再显示。
11. 当 story 需要判断“当前正在渲染哪个 element”时，要区分“后端事件当前流到的 element”与“前端界面当前仍未完成的 element”；前者可基于 target_element_bid 追踪，后者要结合每个 text block 的打字机完成态与 element 级流结束态共同判断。
12. 当后续 element 已经从流里到达，但前一个 text block 仍在打字时，后续 element 只能进入缓存态，不能立即进入可见列表；可见列表应按前一个 block 的 renderComplete 状态逐个放行。

约束

• 该类 story 的重点是复现节奏体验，不要顺手改动 ContentRender 的 markdown 解析逻辑，除非已经确认是组件级缺陷。
• 打字机批次和间隔应抽成常量，避免把 2、120ms 这类节奏值散落在 JSX 或 effect 内部。
• 若故事里需要重置回放，优先通过 content 依赖统一清空 story 自身的 source 状态，并让组件内部自行处理 typewriter 状态重建。
• 当多个 story 都要消费同一份 SSE fixture 解析逻辑时，提到公共 utils，不要在 story 文件里各自复制一份解析器。