English
Part of #5793.
Problem
A1 promises lossless layout refactors, but nothing in the current workflow shows whether a change moved pixels. storybook-visual-smoke.mjs checks render completion, focus, and the accessibility tree, and states that it "does not compare pixels".
This issue is about the verification loop used while implementing A1, B, C1, and D. It is not about adding permanent screenshot testing to Maka's CI.
Desired outcome
A developer working on a chat surface change can run a small, repeatable capture before and after the change and see a pixel diff for each affected story. The loop:
- Build the Storybook catalog once.
- Serve
storybook-static and drive a headless browser against a fixed list of chat surface stories.
- For each story, wait for a stable signal, freeze time, and disable animation, then save a screenshot in light and dark at the smoke runner's default viewport.
- Compare the before and after directories image by image and print changed pixels per story.
Stable capture needs three things:
- A fixed clock, for example Playwright
page.clock, because the session rail renders relative times such as "3mo".
- Disabled animations and
prefers-reduced-motion: reduce, because spinners, the streaming caret, and disclosure transitions otherwise differ between runs.
- The same machine for both runs. Comparing a local capture against one made on another OS is not meaningful, since the font stack starts with
-apple-system.
Initial story set (adjust to what the stories actually reach):
Product/Shell Official AppShell: NativeConversation, StreamingTurn, FailedTurnWithToolError, ProviderRetrying, WideAssistantProse, WaitingForPermission, NewChatComposer, EmptyHome.packages/ui/stories: the Markdown transcript story and the tool activity stories.
Acceptance criteria
Non-goals
- A required or advisory CI check.
- Committed baseline images, Git LFS, or a baseline manifest in the repository.
- Changing
storybook-visual-smoke.mjs or scripts/ci-test-plan.mjs. No merge into main changes what other PRs must run.
中文
属于 #5793。
问题
A1 承诺做无损布局重构，但当前工作流里没有任何东西能显示一次修改是否移动了像素。storybook-visual-smoke.mjs 只检查渲染完成、焦点和无障碍树，并注明它"不比较像素"。
本 issue 是关于 A1、B、C1、D 实施过程中使用的验证手段，不是给 Maka 的 CI 引入常驻的截图对比。
期望结果
开发者在改对话界面时，可以在修改前后各跑一次简单的截图流程，并对每个受影响的故事看到像素差异。流程如下：
- 构建一次 Storybook 目录。
- 启动
storybook-static，用无头浏览器访问一份固定的对话界面故事清单。
- 对每个故事等待稳定信号、冻结时间并关闭动画，然后在浅色和深色模式下、按冒烟测试脚本的默认视口各保存一张截图。
- 对修改前和修改后两个目录逐图对比，输出每个故事的像素差异。
稳定截图需要三件事：
- 固定时钟，例如 Playwright 的
page.clock，因为会话侧栏会渲染"3mo"这类相对时间。
- 关闭动画并模拟
prefers-reduced-motion: reduce，否则加载指示器、流式光标和折叠过渡在不同运行之间会不同。
- 修改前后在同一台机器上截图。字体栈以
-apple-system 开头，本地截图和另一个操作系统上生成的截图对比没有意义。
初始故事范围（按故事实际能到达的状态调整）：
Product/Shell Official AppShell：NativeConversation、StreamingTurn、FailedTurnWithToolError、ProviderRetrying、WideAssistantProse、WaitingForPermission、NewChatComposer、EmptyHome。packages/ui/stories：Markdown 对话流故事和工具活动故事。
验收标准
非目标
- 必跑或建议性的 CI 检查。
- 把基准图片、Git LFS 或基准清单提交进仓库。
- 修改
storybook-visual-smoke.mjs 或 scripts/ci-test-plan.mjs。合入主干不会改动其他 PR 需要运行的内容。
English
Part of #5793.
Problem
A1 promises lossless layout refactors, but nothing in the current workflow shows whether a change moved pixels.
storybook-visual-smoke.mjschecks render completion, focus, and the accessibility tree, and states that it "does not compare pixels".This issue is about the verification loop used while implementing A1, B, C1, and D. It is not about adding permanent screenshot testing to Maka's CI.
Desired outcome
A developer working on a chat surface change can run a small, repeatable capture before and after the change and see a pixel diff for each affected story. The loop:
storybook-staticand drive a headless browser against a fixed list of chat surface stories.Stable capture needs three things:
page.clock, because the session rail renders relative times such as "3mo".prefers-reduced-motion: reduce, because spinners, the streaming caret, and disclosure transitions otherwise differ between runs.-apple-system.Initial story set (adjust to what the stories actually reach):
Product/Shell Official AppShell:NativeConversation,StreamingTurn,FailedTurnWithToolError,ProviderRetrying,WideAssistantProse,WaitingForPermission,NewChatComposer,EmptyHome.packages/ui/stories: the Markdown transcript story and the tool activity stories.Acceptance criteria
scripts/orapps/desktop/scripts/captures the story set above into a directory, with the clock frozen and animation disabled.apps/desktop/stories/AGENTS.mdor the script's own header) shows the capture-compare-attach loop each refactor PR must follow.Non-goals
storybook-visual-smoke.mjsorscripts/ci-test-plan.mjs. No merge into main changes what other PRs must run.中文
属于 #5793。
问题
A1 承诺做无损布局重构，但当前工作流里没有任何东西能显示一次修改是否移动了像素。
storybook-visual-smoke.mjs只检查渲染完成、焦点和无障碍树，并注明它"不比较像素"。本 issue 是关于 A1、B、C1、D 实施过程中使用的验证手段，不是给 Maka 的 CI 引入常驻的截图对比。
期望结果
开发者在改对话界面时，可以在修改前后各跑一次简单的截图流程，并对每个受影响的故事看到像素差异。流程如下：
storybook-static，用无头浏览器访问一份固定的对话界面故事清单。稳定截图需要三件事：
page.clock，因为会话侧栏会渲染"3mo"这类相对时间。prefers-reduced-motion: reduce，否则加载指示器、流式光标和折叠过渡在不同运行之间会不同。-apple-system开头，本地截图和另一个操作系统上生成的截图对比没有意义。初始故事范围（按故事实际能到达的状态调整）：
Product/Shell Official AppShell：NativeConversation、StreamingTurn、FailedTurnWithToolError、ProviderRetrying、WideAssistantProse、WaitingForPermission、NewChatComposer、EmptyHome。packages/ui/stories：Markdown 对话流故事和工具活动故事。验收标准
scripts/或apps/desktop/scripts/下有一个脚本，在冻结时钟和关闭动画的条件下，把上述故事集截图保存到一个目录。apps/desktop/stories/AGENTS.md的一小节或脚本头部注释中写明 A1 的每个 PR 必须遵循的"截图—对比—贴图"流程。非目标
storybook-visual-smoke.mjs或scripts/ci-test-plan.mjs。合入主干不会改动其他 PR 需要运行的内容。