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 July 16, 2026, 12:07 AM ET / 04:07 UTC.

Summary
Keep open. Current main still depends on the in-repository FunctionalUI project and has no Reactor dependency or migration path, so the requested architectural change remains unimplemented; however, adopting a new UI framework and migrating every tray surface requires explicit maintainer direction before engineering begins.

Reproducibility: not applicable. This issue proposes replacing an internal UI architecture rather than reporting broken behavior with a current-main reproduction path.

Root-cause cluster
Relationship: canonical
Canonical: #996
Summary: This issue is the canonical proposal for replacing FunctionalUI; the linked picker and RichTextBlock items demonstrate framework pressure but retain distinct user-facing scopes.

Members:

• partial_overlap: fix(chat): replace NativeElement escape hatch with FunctionalUI ComboBox primitive (supersedes #973) #991 - The merged pull request added a missing ComboBox primitive and demonstrates the maintenance concern, but it fixed a specific picker lifecycle problem rather than migrating frameworks.
• partial_overlap: improve(chat): make prose and simple lists one selectable text block #997 - The open pull request adds RichTextBlock support and selection preservation within FunctionalUI while explicitly leaving the Reactor migration to this issue.
• adjacent_distinct: Custom cross-control selection engine so the whole chat transcript is drag-selectable #995 - Cross-control transcript selection may need compatibility with any future framework, but it is a separate user-facing selection-engine feature.

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.
• Include redacted logs or terminal output.

Next step
A maintainer must first choose the supported UI framework and dependency direction; the proposed repository-wide migration is too broad for an autonomous repair lane.

Maintainer decision needed

• Question: Should the Windows tray adopt Microsoft.UI.Reactor as its supported UI architecture and dependency, beginning with a bounded leaf-screen spike, or continue investing in the in-repository FunctionalUI framework?
• Rationale: Source inspection can establish that the migration is absent and technically motivated, but it cannot choose the repository’s long-term UI dependency, maintenance, and migration strategy.
• Likely owner: shanselman — This choice governs the tray’s long-term architecture and external dependency strategy rather than one individual primitive implementation.
• Options:
  • Sponsor a bounded spike (recommended): Port one low-coupling screen alongside FunctionalUI and require dependency, testing, accessibility, selection, and runtime proof before approving further migration.
  • Retain FunctionalUI: Keep the current framework and define a narrower policy for adding tested primitives only when concrete product needs arise.
  • Approve the full migration: Commit to an incremental Reactor migration now, with one ownership seam per pull request and FunctionalUI removal only after all consumers and invariants move.

Review details

Best possible solution:

Approve a time-boxed feasibility spike that ports one low-coupling leaf screen, documents dependency and testing implications, and proves equivalent UIA, reconciliation, selection, and runtime behavior before deciding whether to sponsor an incremental full migration.

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

Not applicable: this issue proposes replacing an internal UI architecture rather than reporting broken behavior with a current-main reproduction path.

Is this the best way to solve the issue?

Unclear as a full migration; a one-screen compatibility and maintainability spike is the narrowest safe way to determine whether Reactor is preferable to improving FunctionalUI incrementally.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A full migration affects chat, canvas, connection, onboarding, Command Center, and Settings, creating substantial regression exposure across reconciliation, persisted UI state, accessibility, and startup behavior.
• Changing the reconciler could invalidate the stable-control and selection-preservation invariants recently added for ComboBox and RichTextBlock unless those behaviors receive explicit characterization coverage.
• The repository has not yet established whether the chosen Reactor library, version, support model, and WinAppSDK compatibility are acceptable long-term dependencies.

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

Label changes

Label changes:

• add P3: This is a fresh, speculative architecture and maintenance proposal without evidence of a currently blocked user workflow or regression.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P3: This is a fresh, speculative architecture and maintenance proposal without evidence of a currently blocked user workflow or regression.

Evidence reviewed

What I checked:

• FunctionalUI remains active on current main: The tray application still has a direct project reference to OpenClawTray.FunctionalUI at current main SHA bf0fa8a. (src/OpenClaw.Tray.WinUI/OpenClaw.Tray.WinUI.csproj, bf0fa8a9bde4)
• No Reactor dependency is configured: The tray project package references include WinAppSDK and supporting libraries but not Microsoft.UI.Reactor, confirming that the proposed migration is not already underway on current main. (src/OpenClaw.Tray.WinUI/OpenClaw.Tray.WinUI.csproj, bf0fa8a9bde4)
• FunctionalUI is a first-class repository project: The solution includes both OpenClawTray.FunctionalUI and its dedicated test project, showing that current architecture and validation remain organized around the bespoke implementation. (openclaw-windows-node.slnx, bf0fa8a9bde4)
• Recent main history continues extending FunctionalUI: Merged pull request fix(chat): replace NativeElement escape hatch with FunctionalUI ComboBox primitive (supersedes #973) #991 added a first-class ComboBox primitive in merge commit a0042af rather than replacing the framework. (src/OpenClawTray.FunctionalUI/FunctionalUI.cs, a0042affb8c0)
• Related RichTextBlock work does not implement the migration: Open pull request improve(chat): make prose and simple lists one selectable text block #997 proposes another FunctionalUI primitive and cites this issue as a larger follow-up, so it is related motivation rather than a canonical fix. (src/OpenClaw.Tray.WinUI/Chat/Markdown/ChatMarkdownRenderer.cs, 47b335d25428)
• Repository architecture policy favors a bounded spike: AGENTS.md requires small, reviewable ownership transfers, characterization tests, and one seam per PR for tray architecture work; that guidance supports the suggested leaf-screen spike but not an unsponsored all-screens migration. (AGENTS.md, bf0fa8a9bde4)

Likely related people:

• karkarl: Authored the merged ComboBox primitive work in pull request fix(chat): replace NativeElement escape hatch with FunctionalUI ComboBox primitive (supersedes #973) #991 and the current RichTextBlock follow-up, providing recent implementation knowledge of the framework’s limitations and invariants. (role: recent FunctionalUI contributor; confidence: high; commits: a0042affb8c0; files: src/OpenClawTray.FunctionalUI/FunctionalUI.cs, src/OpenClawTray.FunctionalUI/ElementModifiers.cs, src/OpenClaw.Tray.WinUI/Chat/Markdown/ChatMarkdownRenderer.cs)
• arturict: Developed the earlier stable-native-control approach superseded by the merged ComboBox primitive and is credited in that merged history, making them relevant to reconciliation and control-lifecycle preservation. (role: recent adjacent UI lifecycle contributor; confidence: medium; commits: a0042affb8c0, 9c1b92684792; files: src/OpenClawTray.FunctionalUI/FunctionalUI.cs, tests/OpenClawTray.FunctionalUI.Tests)
• shanselman: The repository identifies Scott Hanselman as the project creator, making him the strongest available routing candidate for a tray-wide dependency and architecture-direction decision. (role: project architecture owner; confidence: medium; files: README.md, openclaw-windows-node.slnx, src/OpenClaw.Tray.WinUI/OpenClaw.Tray.WinUI.csproj)

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.