fix(macos): narrow ChatView.body observation scope to prevent window-focus hang (LUM-1273)

[ashleeradka]

ChatView.body tracked ~42 @Observable properties in a single observation scope because all @ViewBuilder helper functions (mainContentStack, activeConversationContent, composerSection, btwOverlay) execute during the parent's body evaluation. When the window regains focus via TitleBarZoomableWindow.becomeKey, deferred observation changes flush simultaneously, forcing a synchronous full body re-evaluation in one AttributeGraph pass — causing 2000ms+ main-thread hangs (Sentry: VELLUM-ASSISTANT-MACOS-Q7).

This narrows the scope to ~3 reads by wrapping mainContentStack in ObservationBoundaryView and extracting btwOverlay into a standalone BtwOverlayView struct. Also updates clients/AGENTS.md to explicitly document the @ViewBuilder observation scope anti-pattern.

Why this is safe

Pure observation scope reorganization — same properties are read, same handlers fire, same view hierarchy is rendered. No new state, no new modifiers, no removed functionality. The .onKeyPress(.escape) handler reads viewModel.btwResponse only in its action closure (on key press), not during body evaluation — no observation scope issue.

What was NOT done and why

• Full View struct extraction of mainContentStack: The Apple-recommended approach and what clients/AGENTS.md line 197 prescribes. However, mainContentStack → activeConversationContent → composerSection together require threading 20+ parameters (viewModel + callbacks, flags, bindings). ObservationBoundaryView achieves identical observation isolation with a single wrapper — same pragmatic tradeoff made for MainWindowView in LUM-841.
• Wrapping entire ChatView.body in one boundary: Too coarse — collapses all observation into one node, defeating property-level tracking and breaking SwiftUI structural diffing.
• Adding @State window-focus tracking: Adds a new observation source rather than narrowing the existing scope.
• DispatchQueue.main.async / withAnimation workarounds: Don't address the root cause (scope width); just defer or mask the cascade.

Root cause analysis

1. How did the code get into this state? ChatView accumulated @ViewBuilder helper functions incrementally as features were added (message list, composer, btw overlay, error banners, queued messages). Each function was the simplest decomposition approach, but @ViewBuilder functions execute in the caller's body scope — all reads are tracked as if they were inline in ChatView.body.

2. What mistakes led to it? The @ViewBuilder function pattern was appropriate in the ObservableObject era (whole-object invalidation anyway), but defeats @Observable's property-level tracking. The @Observable migration didn't narrow observation scopes to match the new tracking granularity — the body structure was carried over as-is.

3. Were there warning signs? Yes — the identical pattern was fixed in MainWindowView (LUM-841) using the same ObservationBoundaryView technique. ChatView wasn't addressed in that fix because it was a separate scope.

4. What can we do to prevent this? When adding new @Observable property reads to a view, audit whether the view's observation scope is still appropriately narrow. The key signal is a @ViewBuilder private function that reads @Observable properties — those reads are tracked in the parent, not in a separate scope.

5. AGENTS.md update: Added a note to the "Scope observation narrowly" guideline in clients/AGENTS.md explicitly calling out that @ViewBuilder functions do NOT create separate observation scopes, and recommending standalone View structs or ObservationBoundaryView as alternatives.

References

• WWDC23 — Discover Observation in SwiftUI — observation tracking is per-View body evaluation
• Apple — Managing model data in your app — recommended pattern: pass @Observable objects to child View structs
• Creating Tracked Scopes with Observation in SwiftUI — community validation of ObservationScope (same concept as ObservationBoundaryView)

Apple refs checked (2026-04-28): WWDC23-10149, Managing-model-data-in-your-app

---

• Requested by: @ashleeradka
• Session: https://app.devin.ai/sessions/fcf2d608f7424a84a093a670f1a8bc11

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[linear]

LUM-1273 App Hanging: App hanging for at least 2000 ms.

[vex-assistant-bot]

✦ APPROVE

Value: Eliminates 2000ms+ window-focus hangs (Sentry VELLUM-ASSISTANT-MACOS-Q7) by applying the same observation scope narrowing that fixed MainWindowView in LUM-841. Verified independently against source — approach is correct and consistent with the established pattern.

What this does: Wraps mainContentStack in ObservationBoundaryView and extracts the btwOverlay @ViewBuilder into a standalone BtwOverlayView struct. This isolates ~42 @Observable property reads from ChatView.body — changes to btwResponse/btwLoading no longer cascade a full ChatView.body re-evaluation. Also removes the dead @Environment(\.colorScheme) property that was tracking color scheme changes for no reason (adjacent to the empty chatBackground).

Verified:

• ObservationBoundaryView definition confirmed: @escaping @ViewBuilder closure deferred to its own body, creating a separate AttributeGraph node — exactly as described. Same struct used in MainWindowView LUM-841 fix. ✅
• BtwOverlayView uses @Bindable var viewModel: ChatViewModel — consistent with the established pattern in TopBarView, ACPSessionsPanel, iOS views. ✅
• Both ObservationBoundaryView and ChatView are in clients/macos/vellum-assistant/ (same Swift module, internal access works). ✅
• .animation(VAnimation.fast, value: viewModel.btwResponse != nil) moved from the parent .overlay modifier chain into BtwOverlayView.body — semantically equivalent: the animation still fires on btwResponse presence change, and now it's scoped to the subview's own body so it doesn't contribute to parent re-evaluation. ✅
• Removed @Environment(\.colorScheme) confirmed dead — chatBackground is EmptyView() and doesn't reference it. Correct deletion. ✅
• AGENTS.md update: @ViewBuilder functions don't create separate observation scopes, and ObservationBoundaryView is the recommended alternative when full View struct extraction is impractical. Clear, accurate, well-placed. ✅

One note (non-blocking): ObservationBoundaryView lives in Features/MainWindow/ while ChatView is in Features/Chat/. Both are in the same module so it compiles fine, but if this pattern spreads further it may be worth relocating ObservationBoundaryView to a shared location (e.g. DesignSystem/ or a SwiftUIHelpers/ file). Not a blocker — just worth tracking if it gets adopted in 3+ features.

Root cause analysis quality: The PR description correctly identifies the deferred observation flush mechanism (becomeKey → pending obs flush → full ChatView.body cascade) and the ConversationArtifactsButton v0.6.6 amplifier. The AGENTS.md callout on @ViewBuilder scope is exactly what's needed to prevent this class of issue from recurring.