refactor(app): extract timeline staging helper

[Astro-Han]

Topology Update (2026-05-16)

Final base: dev.
Dependency status: root of the only retained stack. Child order: #671 -> #672 -> #674 -> #675.
Review order: review after #667/#669, then before #671. #667 and #669 are merged into dev.
Verification after rebase: bun --cwd packages/app test --preload ./happydom.ts src/pages/session/session-timeline-staging.test.ts src/pages/session/use-session-history-window.test.ts src/pages/session/session-timeline-scroll-controller.test.ts src/pages/session/session-timeline-scroll-anchors.test.ts -> 1110 pass / 2674 expects; bun run typecheck -> 8 successful; git diff --check -> pass.

---

Summary

• Extracts createTimelineStaging from MessageTimeline into session-timeline-staging.ts.
• Adds focused browser-condition staging checks for non-windowed render, 10+3 staged batches, active-session message growth while staging, completed-session backfill, and session-switch rAF cancellation.
• Updates the frontend architecture manifest with the concrete refactor(app): extract timeline staging helper #670 / [Task] UI rewrite v2 Area A: message flow modular rollout #601 boundary.

Why

This is the first #601 message-flow architecture slice after the governance and contract stack. The #601 audit identified createTimelineStaging as a launch-path contract inside the oversized MessageTimeline; this PR gives that owner a small file and locks the existing behavior before later message-flow refactors.

Related Issue

Refs #601.

Depends on #667 and #669, both now merged. Base branch is dev.

Human Review Status

Pending. A human should make the final merge decision after reviewing the final diff and verification evidence.

Review Focus

• Confirm the extraction is behavior-preserving: MessageTimeline still passes the same sessionKey, turnStart, renderedUserMessages, and { init: 10, batch: 3 } config.
• Check the test harness: the outer test runs under the repo's default Bun test conditions, while the child process uses --conditions=browser so Solid effects and solid-js/web render semantics are actually exercised.
• Confirm this stays scoped to staging ownership and does not mix in visual [Task] UI rewrite v2 Area A: message flow modular rollout #601 slices or [Task] Design token system debt log (drift, redundancy, dual systems) #642 typography work.

Risk Notes

Behavior should be unchanged except for the reviewed bug fix that preserves active staging when the same session receives more messages mid-stage. The main risk is staging timing around historical windows, completed sessions, rapid session switches, or streaming growth; the browser-condition tests cover those contracts. No dependency, storage, permissions, updater, packaging, or platform behavior changes.

How To Verify

Focused staging and adjacent session tests on latest dev: pass, 1110 tests / 2674 expects
bun --cwd packages/app test --preload ./happydom.ts src/pages/session/session-timeline-staging.test.ts src/pages/session/use-session-history-window.test.ts src/pages/session/session-timeline-scroll-controller.test.ts src/pages/session/session-timeline-scroll-anchors.test.ts

Typecheck: pass, 8 successful tasks
bun run typecheck

Diff check: pass
git diff --check

PR CI: rerunning after manifest commit
GitHub Actions checks are expected to refresh for head 84a757038.

Screenshots or Recordings

Not applicable: no visible UI or copy changes. Electron manual verification was not run because this is a behavior-preserving extraction plus tests, not a rendered UI surface change.

Checklist

• Human review status is stated above as pending, approved, or not required
• I linked the related issue, or stated why there is no issue
• This PR has type, primary area, and priority labels, or I requested maintainer labeling
• I described the review focus and any meaningful risks
• I listed the relevant verification steps and the key result for each
• I did not introduce unrelated refactors, dependencies, generated files, or file changes beyond the stated scope
• I manually checked visible UI or copy changes when needed, with screenshots or recordings
• I considered macOS and Windows impact for platform, packaging, updater, signing, paths, shell, or permissions changes
• I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, generated content, or local file changes when relevant
• I reviewed the final diff for unrelated changes and suspicious dependency changes

[coderabbitai]

Warning

Rate limit exceeded

@Astro-Han has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 10 minutes and 9 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 11c99259-9218-4114-b0e4-352de103c780

📥 Commits

Reviewing files that changed from the base of the PR and between 187a929 and 84a7570.

📒 Files selected for processing (4)

• .github/frontend-architecture-manifest.md
• packages/app/src/pages/session/message-timeline.tsx
• packages/app/src/pages/session/session-timeline-staging.test.ts
• packages/app/src/pages/session/session-timeline-staging.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/message-flow-staging-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request extracts the createTimelineStaging logic from MessageTimeline into a standalone session helper and introduces a new test suite to verify its behavior. The frontend architecture manifest was also updated to document this staging PR. A bug was identified in the staging effect where an unconditional call to cancel() and the shouldStage check cause staging to prematurely abort when new messages arrive, leading to a visual pop; a code suggestion was provided to ensure staging continues correctly for the active session.

[github-actions]

Perf delta summary

Comparator: pass

Profile / Scenario	interaction median	interaction worst	long task max	tbt	frame gap p95	frame gap max	jank count	cls	status
default / homepage-cold	40 -> 40 (0)	56 -> 64 (+8)	86 -> 66 (-20)	36 -> 16 (-20)	33.3 -> 16.8 (-16.5)	166.7 -> 166.6 (-0.1)	4 -> 3 (-1)	0 -> 0 (0)	pass
default / long-session-input-lag	48 -> 48 (0)	48 -> 48 (0)	0 -> 0 (0)	0 -> 0 (0)	16.7 -> 16.8 (+0.1)	16.8 -> 16.8 (0)	0 -> 0 (0)	0 -> 0 (0)	pass
default / session-streaming-long	48 -> 40 (-8)	72 -> 56 (-16)	0 -> 0 (0)	0 -> 0 (0)	33.4 -> 16.8 (-16.6)	50 -> 33.4 (-16.6)	0 -> 0 (0)	0 -> 0 (0)	pass
default / tool-call-expand	16 -> 16 (0)	24 -> 24 (0)	0 -> 0 (0)	0 -> 0 (0)	16.8 -> 16.8 (0)	16.8 -> 16.8 (0)	0 -> 0 (0)	0 -> 0 (0)	pass
default / tool-default-open-heavy-bash	24 -> 24 (0)	24 -> 32 (+8)	66 -> 65 (-1)	16 -> 15 (-1)	33.3 -> 50 (+16.7)	166.5 -> 99.9 (-66.6)	1 -> 2 (+1)	0 -> 0 (0)	pass
default / terminal-side-panel-open	56 -> 48 (-8)	56 -> 48 (-8)	0 -> 0 (0)	0 -> 0 (0)	50 -> 33.3 (-16.7)	50 -> 33.4 (-16.6)	0 -> 0 (0)	0 -> 0 (0)	pass
default / session-scroll-reading	32 -> 24 (-8)	32 -> 40 (+8)	0 -> 0 (0)	0 -> 0 (0)	16.8 -> 16.8 (0)	16.8 -> 16.8 (0)	0 -> 0 (0)	0.505 -> 0.505 (0)	warn: cls
low-end / session-scroll-reading-long	64 -> 72 (+8)	64 -> 72 (+8)	78 -> 90 (+12)	46 -> 48 (+2)	16.8 -> 16.8 (0)	83.3 -> 166.6 (+83.3)	2 -> 3 (+1)	0.011 -> 0.011 (0)	pass
low-end / session-timeline-recompute	120 -> 112 (-8)	136 -> 120 (-16)	108 -> 104 (-4)	179 -> 170 (-9)	100 -> 83.4 (-16.6)	183.3 -> 183.2 (-0.1)	3 -> 3 (0)	0.081 -> 0.081 (0)	pass
low-end / concurrent-shimmer-extreme	0 -> 0 (0)	0 -> 0 (0)	0 -> 0 (0)	0 -> 0 (0)	16.7 -> 16.8 (+0.1)	16.8 -> 16.8 (0)	0 -> 0 (0)	0 -> 0 (0)	pass

[github-actions]

Suggested priority: P2 (includes user-path files (packages/app/src/pages/session/message-timeline.tsx, packages/app/src/pages/session/session-timeline-staging.test.ts, packages/app/src/pages/session/session-timeline-staging.ts)).

P1/P0 are reserved for maintainer confirmation. Please relabel manually if this is a release blocker, security issue, data-loss risk, or updater/runtime failure.