Port OpenClawTray.FunctionalUI to Reactor to stop hand-maintaining bespoke UI primitives

[karkarl]

Problem

OpenClawTray.FunctionalUI is an in-house MVU/reconciler with a hand-maintained set of primitives and element modifiers. Every new control need has to be added and maintained by hand, and non-trivial chat/UI features keep extending it:

• fix(chat): replace NativeElement escape hatch with FunctionalUI ComboBox primitive (supersedes #973) #991 replaced a NativeElement escape hatch with a first-class FunctionalUI ComboBox primitive (superseded fix(chat): keep session picker open during status renders #973) — i.e. we're still filling gaps in the primitive set.
• The RichTextBlock chat-bubble work (branch karkarl-chat-bubble-richtextblock, commits 2fa7279 + 47b335d) added a RichTextBlock primitive and imperative block population purely to get selectable chat bubbles.

Both are maintenance we take on only because FunctionalUI is bespoke. Porting to Microsoft.UI.Reactor (or the agreed Reactor-style MVU library) would let us bypass hand-rolling and maintaining these primitives and lean on an upstream-maintained component surface.

Goal

Migrate the tray UI from OpenClawTray.FunctionalUI to Reactor, so:

• New controls come from the upstream library instead of bespoke primitives + modifiers.
• Existing screens (chat/canvas, Connection, onboarding, Command Center, Settings) keep current behavior and tests.
• The selection-preservation and inert-markdown invariants from the chat work are preserved (or re-expressed) under Reactor.

Suggested phasing

1. Spike: stand up Reactor alongside FunctionalUI; port one leaf screen to validate patterns, testing, and reconcile/selection behavior.
2. Port primitives currently unique to FunctionalUI (ComboBox from fix(chat): replace NativeElement escape hatch with FunctionalUI ComboBox primitive (supersedes #973) #991, RichTextBlock from this branch, etc.) to Reactor equivalents.
3. Migrate screens incrementally behind the existing god-file-reduction guardrails (App.xaml.cs / ConnectionPage.xaml.cs) — one seam per PR with characterization tests.
4. Remove FunctionalUI once no consumers remain.

Constraints / guardrails

• Follow AGENTS.md architecture guardrails: small, reviewable, one seam per PR; characterization tests before moving behavior.
• Keep the chat inert-markdown security posture and the RichTextBlock selection-preservation cache invariant.
• Preserve accessibility (UIA names/roles, live regions) and existing UI/MCP proof requirements.

References

• PR fix(chat): replace NativeElement escape hatch with FunctionalUI ComboBox primitive (supersedes #973) #991 — replace NativeElement escape hatch with FunctionalUI ComboBox primitive (supersedes fix(chat): keep session picker open during status renders #973): fix(chat): replace NativeElement escape hatch with FunctionalUI ComboBox primitive (supersedes #973) #991
• Branch karkarl-chat-bubble-richtextblock, commits 2fa7279 + 47b335d (RichTextBlock chat-bubble primitive + list coalescing) — PR pending from this branch; cross-link once opened.
• Related follow-up: custom cross-control chat selection engine (Custom cross-control selection engine so the whole chat transcript is drag-selectable #995) — the Reactor port should keep that path viable.

[karkarl]

Referenced PR now open: #997 (FunctionalUI RichTextBlock primitive + chat-bubble coalescing). Reinforces the case for porting FunctionalUI to Reactor instead of hand-maintaining bespoke primitives.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 5, 2026, 4:14 AM ET / 08:14 UTC.

Summary
Keep open for a maintainer architecture decision. Current main moved the default chat surfaces to Reactor, but FunctionalUI still renders successful Cron output and remains a tray-project dependency, so the requested tray-wide retirement is incomplete.

Reproducibility: not applicable. this is an architectural migration proposal rather than one failing behavior with a runtime reproduction.

Root-cause cluster
Relationship: canonical
Canonical: #996
Summary: This issue remains the canonical umbrella for the FunctionalUI retirement decision after the chat portion landed.

Members:

• partial_overlap: feat(chat): migrate chat surface to Reactor #1055 - The merged Reactor migration completed the default chat path but not the remaining Cron FunctionalUI dependency.
• adjacent_distinct: Custom cross-control selection engine so the whole chat transcript is drag-selectable #995 - Cross-control selection has distinct user behavior and design constraints.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Maintainer decision needed

Question	Recommendation
Should the tray complete FunctionalUI retirement by porting the remaining Cron result renderer to Reactor, or retain a deliberately narrow FunctionalUI compatibility island?	Complete retirement: Port Cron results to Reactor with characterization coverage, then remove FunctionalUI only after no production consumers remain.

Why: Current main proves the central chat migration, but the value and acceptable cost of removing the remaining Cron dependency requires product and architecture intent.

Next step
A maintainer must select the remaining FunctionalUI boundary before a safe, bounded implementation plan can begin.

Review details

Best possible solution:

Choose the permanent renderer boundary, then migrate the Cron result surface in a small characterized PR before removing FunctionalUI and its legacy-only chat coverage.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is an architectural migration proposal rather than one failing behavior with a runtime reproduction.

Is this the best way to solve the issue?

No: a one-shot tray-wide port is not yet the best path. The safest route is a maintainer-approved renderer boundary followed by a narrow Cron migration with preserved behavior coverage.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A broad removal without a chosen and characterized Cron renderer could change successful-run markdown output or remove a currently compiled dependency prematurely.

Codex review notes: model internal, reasoning high; reviewed against d2de6150753b.

Label changes

Label justifications:

• P3: This is a broad renderer-consolidation proposal, not a current user-facing outage or established regression.

Evidence reviewed

What I checked:

• Default chat uses Reactor: Both full and compact chat hosts mount Reactor directly into their XAML chat targets. (src/OpenClaw.Tray.WinUI/Pages/ChatPage.xaml.cs:292, d2de6150753b)
• FunctionalUI remains in production: Successful Cron results sanitize markdown, mount FunctionalHostControl, and render through ChatMarkdownRenderer; the tray project still references FunctionalUI. (src/OpenClaw.Tray.WinUI/Pages/CronPage.xaml.cs:1643, d2de6150753b)
• Architecture ledger: The ledger makes Reactor authoritative for the production chat timeline and closes the FunctionalUI default-chat mount, while allowing legacy FunctionalUI chat files for compatibility coverage. (docs/ARCHITECTURE.md:135, d2de6150753b)
• Feature provenance: FunctionalUI chat dates to the original native-chat commit; the current history records the later Reactor chat migration on main. (src/OpenClawTray.FunctionalUI/FunctionalUI.cs:1, 08cab69a038c)
• Maturity helper unavailable: No maturity label selected because the supplied helper could not find qa/maturity-scores.yaml in this checkout.

Likely related people:

• karkarl: Authored the merged Reactor chat migration and the later Reactor theme work recorded in current history. (role: recent area contributor; confidence: high; commits: 9acafa606a4d, ff1901275a41; files: src/OpenClaw.Tray.WinUI/Chat/ReactorChatHostExtensions.cs, src/OpenClaw.Tray.WinUI/Chat/OpenClawReactorChatRoot.cs)
• Régis Brid: Introduced the original native FunctionalUI chat experience that remains the basis of the legacy renderer. (role: introduced prior renderer; confidence: high; commits: 08cab69a038c; files: src/OpenClawTray.FunctionalUI/FunctionalUI.cs)
• AlexAlves87: Current blame attributes the remaining FunctionalUI-backed Cron output path to this contributor's Cron change. (role: Cron-surface contributor; confidence: high; commits: f536bcf06559; files: src/OpenClaw.Tray.WinUI/Pages/CronPage.xaml.cs)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[karkarl]

Concrete evidence for this port: the chat timeline scroll bug

While fixing "scrollbar doesn't reach the bottom while the agent is thinking/streaming" I traced the root cause straight back to us hand-maintaining a vendored fork of Reactor, which is exactly what this issue proposes to stop doing. Recording the findings here as a data point.

What's forked today

• src/OpenClaw.Shared/Markdown/Md4c/VENDORED.md — markdown engine is a copy of Reactor's src/Reactor/Markdown/ pinned to commit 01bb3fb.
• src/OpenClaw.Tray.WinUI/Chat/OpenClawChatTimeline.cs is a derivative of Reactor's samples/apps/chat/Chat.UI/ChatTimeline.cs — near-identical refs (isFollowingRef, suppressAutoFollowRef, prev*Ref), same FollowThreshold = 60, same QueueScrollToBottom / QueuePreservePrependOffset / prepend-append-session logic.

The divergence that caused the bug

• Upstream's chat sample is non-virtualized: VStack (StackPanel) in a ScrollViewer. Its follow-to-bottom works because StackPanel.SizeChanged is a reliable signal for in-place row growth.
• We swapped to VirtualVStack (ItemsRepeater) for virtualization. ItemsRepeater reports an estimated extent that climbs across realization frames, so in-place streaming growth no longer fires a reliable SizeChanged — the upstream follow path misses and the view lands a few px short. We bolted on a reactive ViewChanged re-pin, which is jaggy and fights the user.

Relevant framework capability we do NOT inherit

• Reactor's reconciler ships src/Reactor/Core/Reconciler.RichTextScrollAnchor.cs (issue MXC: replace Node bridge with direct wxc-exec.exe spawn #487 mitigation + [Repo Assist] fix(setup): cancel wizard session before disconnect to prevent stale-session errors #717 root-cause PinExtentAcrossInlineUiMutation) that pins extent / restores offset when a streaming RichTextBlock with inline UI transiently collapses. Our vendored OpenClawTray.FunctionalUI reconciler has none of this.

Notes that de-risk this port

• Virtualization is already in the Reactor NuGet (LazyVStack<T>, LazyHStack<T>, ItemsRepeater<T>, ItemsView<T>, and LazyStack = ScrollViewer+ItemsRepeater). Only the sample is non-virtualized, so porting does not cost us virtualization and does not require adding virtualization to Reactor.
• Follow-to-bottom is app-level in Reactor too — there is no framework StickToBottom/AutoScroll/follow primitive. We own follow either way.
• Porting constraint to keep in mind: keep an explicit ScrollViewer hosting ItemsRepeater<T>/LazyVStack<T> (not the opaque LazyStack) so the follow/anchor logic retains ScrollViewer access.

Immediate action (separate PR, does not block this issue)

Fixing the live bug now via ScrollViewer.VerticalAnchorRatio = 1.0 scroll anchoring + intent-based follow (keeps virtualization). That anchor technique is required for any virtualized chat — ours now or Reactor's post-port — so it carries forward. It's arguably worth upstreaming to Reactor's chat sample, which will hit the same issue the moment anyone virtualizes it.

[karkarl]

Follow-up from the scroll-anchoring fix (chat timeline)

Landing the temporary follow-to-bottom fix in OpenClawChatTimeline via WinUI ScrollViewer.VerticalAnchorRatio = 1.0 (Option B). This resolves the "scrollbar doesn't reach the bottom while the agent is thinking" bug: the bottom-most realized row is now pinned to the viewport bottom before paint as the ItemsRepeater extent climbs during streaming, so there's no intermediate short frame and no programmatic ChangeView fighting the user's own scrolling.

Known residual (acceptable for now): while messages virtualize/realize and assistant text streams in, the scroll is still slightly jittery as the available viewport expands. Anchoring keeps the bottom pinned but the per-frame extent re-estimation from ItemsRepeater still produces small visible jumps during rapid in-place row growth. Good enough as a temporary fix; the clean solution is the Reactor port tracked by this issue.

Why this reinforces the port to Reactor:

• Follow-to-bottom / stick-to-bottom is app-level in both worlds — Reactor ships no framework follow primitive, so we hand-maintain this in OpenClawChatTimeline (a fork of Reactor's non-virtualized samples/apps/chat/Chat.UI/ChatTimeline.cs).
• Reactor's chat sample is non-virtualized (VStack/StackPanel + reliable SizeChanged), which is exactly the signal our virtualized ItemsRepeater path lacks. Virtualization itself is already in the Reactor NuGet (LazyVStack<T>, ItemsRepeater<T>, etc.) — porting does not regress virtualization.
• Reactor also ships src/Reactor/Core/Reconciler.RichTextScrollAnchor.cs (MXC: replace Node bridge with direct wxc-exec.exe spawn #487/[Repo Assist] fix(setup): cancel wizard session before disconnect to prevent stale-session errors #717) that our vendored FunctionalUI reconciler does not inherit.

When we port, keep an explicit ScrollViewer hosting the virtualized repeater (not the opaque LazyStack compound) so the follow/anchor logic retains ScrollViewer access, and consider upstreaming Option B + a residual-jitter mitigation to Reactor's chat sample.