[Task] UI rewrite v2 Area A: message flow modular rollout

[Astro-Han]

Goal

Rebuild the session message flow so the timeline can be shipped incrementally behind the perf gate instead of through another large slice like PR #589.

Scope

In scope:

• User message bubbles.
• Agent prose and reasoning output.
• Tool call trows in collapsed and expanded states.
• Inline copy buttons.
• Attachment chips.
• Interrupted and system events.
• Reset / Fork toolbar entries.
• Streaming state such as work timer, thinking label, and animation timing.

Out of scope:

• Right panel work from [Task] UI rewrite v2 Area B: right panel modular rollout #602.
• Home work from [Task] UI rewrite v2 Area C: home surface modular rollout #603.
• Visual shell or final shell work from [Task] UI rewrite v2 Area E1: visual shell modular rollout #605 and [Task] UI rewrite v2 Area E2: final shell modular rollout #606.
• Any implementation before [Task] UI rewrite v2 PR0: perf-gated regression CI #600 lands.

Relevant files or context

Parent: #599

Audit-first file set:

• packages/ui/src/components/message-part.tsx
• packages/app/src/pages/session/message-timeline.tsx
• packages/ui/src/components/session-turn.tsx
• packages/app/src/pages/session.tsx
• packages/app/src/pages/session/use-session-commands.tsx
• packages/ui/src/components/markdown.tsx (decide whether this area still needs to touch it; default defer)
• packages/app/src/pages/session/session-timeline-scroll-controller.ts

Constraints carried from the master plan:

• PR0 perf gate must be green on every PR.
• Do not regress PR feat(ui,app): sidebar L35 row rewrite (slice 09, issue #440) #495 or PR feat(ui,app): composer rewrite (slice 10, issue #440) #508.
• Soft file-size rule: 500 LOC, ideal 200 LOC, no splitting for the sake of splitting.

Verification

• Every Area A PR passes [Task] UI rewrite v2 PR0: perf-gated regression CI #600.
• The area-specific read-only audit exists before the first code PR.
• The 5-minute visual pass in docs/design/session-view-w1-manual-checklist.md passes.
• W1 e2e coverage in the [Task] chore(e2e): strengthen W1 regression coverage #598 family remains green.

Execution mode

Agent should investigate and propose a plan first

[Astro-Han]

补一条和 #615 / 上游性能工作的关联。

Area A 后续应该承接 #615 里和 message flow 直接相关的部分：timeline 渲染成本、message-part / SessionTurn 拆分、tool body 延迟挂载，以及是否需要引入真正的 timeline virtualization。

上游正在做的 anomalyco/opencode#26949 可以作为重点参考：它走的是 row 级别 virtualized session timeline，而不是简单按 turn 粗粒度虚拟化。这个方向不一定能直接搬，但值得用它的实现取舍、smoke 覆盖和 guardrail 结果来对照 PawWork 的 PR0 数据。

这里先不把方案写死。等 #600 的数据能说明瓶颈在哪一层，再决定 Area A 的第一批 PR 怎么拆。

[Astro-Han]

Area A read-only audit (2026-05-14)

按 issue Verification "area-specific read-only audit exists before the first code PR" 要求补做。本评论只描述现状，不开方案。后续 sub-slice PR 应该 link 本评论作为拆分参考。

2026-05-14 修订 v1：根据 GPT Pro 复核，修正了 #615 根因数（4→5）、BasicTool callsite 数（13→17）、补充了 message.part.delta 数据路径、createTimelineStaging 行为、ready 在 defaultOpen=true 时初始即为 true 的细节，并把 session-timeline-scroll-controller.ts 单独列入虚拟化前的风险面。

2026-05-14 修订 v2：GPT Pro 复核 v1，要求把可静态补的三项 inventory 从"未覆盖"移出，补充 BasicTool 计数依据，并修掉第 5 节旧稿矛盾语。本次落地：第 1/3 节补 BasicTool 17 处计数依据；第 4 节上游 commits 描述降精度；第 5 节去掉"audit 没单列"矛盾语；第 7 节拆为"已静态补的 read-only inventory"和"仍待动态测量的限制"两块。

1. 组件拓扑

6 个核心文件全部超 500 LOC 软 cap：

文件	LOC	超倍数
packages/ui/src/components/message-part.tsx	2461	4.9×
packages/app/src/pages/session/message-timeline.tsx	1216	2.4×
packages/ui/src/components/session-turn.tsx	753	1.5×
packages/app/src/pages/session.tsx	694	1.4×
packages/app/src/pages/session/use-session-commands.tsx	618	1.2×
packages/app/src/pages/session/session-timeline-scroll-controller.ts	595	1.2×

组件树：

Page (session.tsx)
└── SessionMainView
    └── MessageTimeline (message-timeline.tsx)
        └── ScrollView
            └── For each={rendered()}    ← 当前是普通 For,未接 virtua
                                          ← 上层还有 createTimelineStaging
                                            (message-timeline.tsx:213) 做
                                            bounded mount / staged render
                └── SessionTurn (session-turn.tsx)
                    ├── Message (message-part.tsx)
                    ├── MessageDivider
                    └── AssistantParts (message-part.tsx)
                        └── Index each={grouped()}
                            └── Switch
                                ├── Match "context" → ContextToolGroup
                                └── Match "part" → Part
                                    └── Dynamic component={PART_MAPPING[type]}

职责堆积：

• message-part.tsx 单文件混了:part plugin 注册系统、文本流速渲染（createPacedValue）、context group 聚合、shell output 处理、UserMessageDisplay / AssistantMessageDisplay / AssistantParts 三个 display 组件、17 处 <BasicTool> callsite（grep <BasicTool 计数；分布范围 L1641-2459）。
• MessageTimeline 在列表渲染之外，还内联了 session title 编辑、turn change 拉取+重试、webSearch toast、export 功能、scroll 事件路由、以及 createTimelineStaging（L213）— 即 staged/bounded-mount 行为不是单纯的列表渲染。
• session-timeline-scroll-controller.ts 是纯逻辑状态机，结构上跟 UI 解耦，但行为面跟 [Performance] Session UI typing lag and scroll stuttering #615 第 5 根因（"复杂的滚动状态机"）直接相关，不是已经安全的解耦。

2. 数据通路（细粒度状态良好，含两条流式路径）

packages/app/src/context/global-sync/event-reducer.ts：

• store.message[sessionID] 数组存 message metadata；store.part[messageID] 数组存 part 内容，两者分开
• message.part.updated 事件走 reconcile(part)（L243-255）—— part-level 细粒度更新，不是 message-level reconcile
• message.part.delta 事件在 L284 是 streaming token 追加路径 —— 跟 part.updated 是两条不同的热路径，下一刀若碰 streaming/rendering，不能只用 part.updated 证明数据粒度已经够好
• AssistantParts 在 message-part.tsx 用 <Index each={grouped()}> + <Switch/Match>：Index 对 key 稳定的位置不重渲

已知潜在热点：grouped() 是 createMemo 聚合 context tool group，每次 part 更新都得重算整组。具体重算成本未直接测量。

3. Tool body 挂载策略（基础设施在,但 defaultOpen 路径会绕开 lazy）

packages/ui/src/components/basic-tool.tsx:235-239：

<Show when={!props.animated && props.children && !props.hideDetails}>
  <Collapsible.Content>
    <Show when={!props.defer || ready()}>{props.children}</Show>
  </Collapsible.Content>
</Show>

• defer prop + ready() signal 已实现 lazy-mount 雏形
• 关键细节：basic-tool.tsx:47 ready: props.defaultOpen ?? false，即在 defaultOpen=true 的 callsite 上，ready 一开始就是 true，光传 defer 不会触发延迟挂载
• <Collapsible.Content>（Kobalte）默认折叠时保留 DOM、靠 style/attribute 控制 —— 折叠状态下 children 仍在 reactive scope 内
• message-part.tsx 共 17 处 <BasicTool> callsite（grep <BasicTool 计数；分布 L1641, L1670, L1690, L1717, L1747, L1793, L1814, L1830, L1907, L1944, L1999, L2071, L2153, L2245, L2331, L2409, L2459），0 处显式设置 defer；要真正复现上游收益还需要看哪些 callsite 是 defaultOpen=true
• 巨型 tool output（如 grep 1000 行）当前无特殊处理路径

4. 上游 anomalyco/opencode#26949 参考

PR 状态 Open，18 commits，作者 Hona。核心方案：

• 把会话 flatten 成 TimelineRow discriminated union（8 种类型：comment-strip / user-message / turn-divider / assistant-part / thinking / retry / diff-summary / error + bottom-spacer）
• 用 virtua/solid 的 <Virtualizer> 逐行虚拟化，fallback item size 60px
• 边角处理：
  • deferred tool body 挂载：basic-tool.tsx 引入全局 deferredMounts queue + rAF 批处理，靠近底部的 tool 优先出列。上游延迟的是 "default-open heavy body"，跟当前 PawWork ready 的初始化策略不同，移植时不能只接 prop。
  • scroll restore：timelineCache Map 存 virtualizer state 快照，LRU 上限 16 个 session
  • hash scroll：use-session-hash-scroll.ts 的 revealMessage 回调 + rAF retry 最多 4 次
  • 对象身份优化：reuseTimelineRows 对结构相同的 row 返回旧引用

PawWork 现状：package.json 装了 virtua@0.42.3，但 message-timeline.tsx 仍用普通 <For>，虚拟化基础设施已在依赖里，未接入。注意上游 PR 把 virtua 升到 0.49.1，并不是基于 0.42.3 跑通的，照搬要算升级成本。

上游 diff/修复点提示的适配风险：上游 PR body 明确包含 row-level virtualization、anchors/hash reveal、diff rendering、BasicTool default-open body work、virtua 升级等修复方向，说明这些都不是顺手就能搞定的细节。具体 commit 标题/链接未在本 audit 内逐条核到，参考时以上游 PR diff 为准。

不可直接搬：上游专用 hook（useSync / useGlobalSDK）、session.tsx 的 history loader（含 TODO 半成品）、./session-diff UI export。

5. 与 #615 性能问题的对应关系（5 个根因）

#615 根因	audit 位置
1. 缺虚拟滚动（<For each={rendered()}> 在 message-timeline.tsx:1106）	第 1 节（virtua 装了未接）+ 第 4 节（上游 row-level 方案可参考）
2. message-part.tsx 276 个 reactive 调用	第 1 节（2461 LOC 多职责堆积）+ 第 2 节（grouped memo 重算面）
3. ScrollView 滚动未节流（scroll-view.tsx:111-139）	本 audit 未覆盖实现细节，留给后续 sub-slice；注意若下一刀做 virtua，scroll owner / anchor / height estimation 都会变，不能当独立 CSS 小修
4. content-visibility 使用不当	本 audit 未覆盖实现细节，留给后续 sub-slice；与上一条同样跟 virtua 绑定
5. 复杂的滚动状态机（session-timeline-scroll-controller.ts）	旧版未单列；本修订已在第 1 节、第 6 节列为虚拟化前的决策风险面 —— 接 virtua 会改变 scroll owner / anchor / following-latest 语义

6. 后续 sub-slice 拆分候选（描述性,不拍板）

按"先收缩职责，再接虚拟化"的依赖顺序，候选若干刀（顺序与具体边界由后续 PR 决定）：

• message-part.tsx 结构切分（纯 refactor 轴）：把 tool components（17 处 BasicTool dispatcher）抽到独立文件。零行为变更，单文件从 2461 行降一截。
• 启用 BasicTool defer（行为变更轴）：跟上一条不能合并成一刀。需要先决定哪些 callsite 是 defaultOpen=true、是否要改 ready 初始值策略、还是参照上游引入全局 deferredMounts queue。这是行为变更，要过 PR0 perf gate 测。
• MessageTimeline 职责剥离：把 title 编辑、turn pull、export、toast 各自抽 hook 或子组件，让 MessageTimeline 回到"列表渲染 + staging"主责。注意 createTimelineStaging 是现有契约的一部分,剥离时不能丢。
• scroll controller 收敛：在接 virtua 前，先把 session-timeline-scroll-controller.ts 当前的状态语义（following_latest / reading_history / targeting_message）+ ScrollView 节流 + content-visibility 一并审视，因为下一刀的 virtua 会动 scroll owner / anchor / height estimation,这三个不能当独立小修。
• timeline flatten + 接 virtua：参照上游 #26949 的 TimelineRow union + Virtualizer 思路。前提：上面两 / 三刀的职责堆积和 scroll 契约已经收敛。需要预先盘点 row identity / anchor / hash reveal / active message / comment strip / turn-change / reset/fork / copy target 这些"行级身份"作为虚拟化必须保留的契约清单（见第 7 节 7.1 静态 owner 清单）。
• streaming 热点优化：grouped() memo 边界、context group 聚合策略、message.part.delta 实际重算成本，必要时插测量。

7. Inventory 与限制

7.1 Row 契约 owner 静态清单（read-only）

虚拟化必须保留的"行级身份"契约，对应当前 owner：

契约	Owner 文件 / 入口
Row identity（用户消息为锚的 row key）	message-timeline.tsx:353 rendered = renderedUserMessages.map(m => m.id)；DOM 上 data-message-id 由 row 写入
Anchor（DOM id 锚点 + 滚动定位）	message-timeline.tsx:317 props.anchor: (id) => string prop；行为面 session-timeline-scroll-anchors.ts（messageElementByID / firstVisibleMessage / restoreReading / sampleTimelineSafePosition）
Hash reveal（URL hash → 滚到指定消息）	use-session-hash-scroll-core.ts:97 scrollToMessage；wire 在 use-session-timeline-interaction.ts:296 activeMessage.setScrollToMessage(hashScroll.scrollToMessage)
Active message（当前焦点消息 + 键盘导航）	use-session-active-message.ts createSessionActiveMessage；wire 在 use-session-timeline-interaction.ts:127；timeline 内 activeMessageID memo 在 message-timeline.tsx:733，row 内 active memo 在 L1111
Scroll controller 状态	session-timeline-scroll-controller.ts（595 LOC，状态语义 following_latest / reading_history / targeting_message）

接 virtua 时，上述 owner 在虚拟化前后都必须能取到 row 的 DOM 句柄或 row metadata，否则 anchor / hash reveal / active message 三条会同时失语。

7.2 createTimelineStaging 静态行为摘要（read-only）

定义于 message-timeline.tsx:213，调用于 L789。stageCfg = { init: 10, batch: 3 }（L788）。

• bounded mount 阈值：init: 10 —— 首批只挂载最后 10 条用户消息所属 turn；batch: 3 —— 每个 rAF 帧再追加 3 条
• 触发条件：同时满足 turnStart > 0（即处于历史窗口模式）+ messages.length > init + 当前 sessionKey 既不在 state.activeSession 也不在 state.completedSession（L249-253）
• 推进：requestAnimationFrame(step)；step 内重新读 messages.length 以容纳 backfill；count >= currentTotal 时标记 completedSession = sessionKey 并结束
• session 切换契约：
  • 切到新 sessionKey 时 cancel() 当前 rAF，重新评估
  • 已 completedSession === sessionKey 时 stagedCount 直接返回 total（L223），永不再 stage 同一 session
  • step 内每帧检查 input.sessionKey() !== sessionKey 提前退出，避免快速切换时把上一 session 的 staging 灌进当前 session

剥离 MessageTimeline 时若动 staging 触发条件或时机，必须保留"历史窗口模式才 stage"、"completed 不重 stage"、"session 切换 cancel" 这三条不变。

7.3 测试 / guardrail 覆盖与缺口清单（read-only）

Guardrail	文件	覆盖了哪段 message-flow
PR0 perf gate（baseline）	packages/app/e2e/perf/perf-probe.spec.ts + e2e/perf/probe.ts + e2e/perf/profiles.ts + e2e/perf/timeline-fixture.ts	安装 perf probe → seed timelineRecomputeSession fixture → 录 scenario 指标到 pr0.1-baseline.json；profile 支持 baseline / low-end 切换
Session scroll position e2e	packages/app/e2e/session/session-scroll-position.spec.ts	INITIAL_SESSION_WINDOW_MESSAGES=10 入口窗口验证；session 切换前后 timeline metrics、owner、composer/messageList 节点身份
Renderer diagnostics e2e	packages/app/e2e/session/session-renderer-diagnostics.spec.ts	抓 __pawwork_renderer_diagnostics 事件（含 timeline session id / route session id / trace id），用来对滚动与导航事件做断言
Scroll controller 单测	packages/app/src/pages/session/session-timeline-scroll-controller.test.ts + session-timeline-scroll-anchors.test.ts + session-auto-scroll.test.ts + use-session-scroll-dock.test.ts + file-tab-scroll.test.ts	滚动状态机、anchor sample/restore、auto scroll、composer dock 滚动、文件 tab 滚动
Hash scroll 单测	packages/app/src/pages/session/use-session-hash-scroll.test.ts	URL hash → message reveal 路径
Timeline 数据 / rename 单测	packages/app/test/session/turn-change-fetch.test.ts + message-timeline-rename.test.ts	turn change 拉取行为、rename 路径
UI 主题守护	packages/ui/test/dark-media-guard.test.ts	dark mode @media guard 源码扫描，跟 message flow 无关，仅作为既有 source-scanner pattern 参考

已知缺口（要在拆 slice 时补，本 audit 只标记，不开 PR）：

• BasicTool defer 行为切换（17 callsite）没有专项单测验证 mount 时机
• message.part.delta streaming append 路径没有单测固定 reconcile vs streaming 的契约
• createTimelineStaging init=10 / batch=3 阈值切换、session 切换 cancel 行为没有专项单测
• Row identity ↔ virtua row key 之间的契约（接 virtua 后才需要）暂无测试
• 视觉 5 分钟 manual checklist 不在 CI，依赖人工

7.4 仍待动态测量的限制（本 audit 不能现场补）

本 audit 未做、也不打算在 read-only 范围内做的事：

• ScrollView 节流效果验证（[Performance] Session UI typing lag and scroll stuttering #615 第 3 根因，需 perf probe）
• content-visibility 高度估算影响验证（[Performance] Session UI typing lag and scroll stuttering #615 第 4 根因，需 perf probe）
• grouped() createMemo 的实际重算成本（需要跑 perf probe / instrument）
• streaming 期间真实 re-render 数量（需要 instrument）
• message.part.delta 热路径的具体重算面（需要 instrument）

后续若需要，可再做一份性能侧 audit 用 PR0 perf gate / renderer diagnostics 把这几块用数据填上。