PR #76991: fix(ui): prevent programmatic scrollTo from flipping chatUserNearBott…

• Repository: openclaw/openclaw
• Author: nickmopen
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/76991

Description (problem / solution / changelog)

Summary

• Problem: During streaming assistant responses in Control UI/webchat, calling scrollTo() to pin the viewport to the bottom fires a synchronous scroll event. Because new content has grown scrollHeight between the scrollTo call and the event, handleChatScroll computes a large distanceFromBottom (≥ 450 px) and flips chatUserNearBottom to false, breaking the auto-scroll loop for all subsequent streaming tokens.
• Why it matters: Every user running streaming responses in the webchat could see the viewport drift upward mid-generation, forcing a manual scroll-down while the assistant is still responding.
• What changed: A chatIsProgrammaticScroll boolean flag is set on the host before each programmatic scrollTo/scrollTop write and cleared via requestAnimationFrame after. handleChatScroll returns early when the flag is set, so our own scroll events cannot corrupt the near-bottom state.
• What did NOT change: Threshold values, user-initiated scroll detection, force semantics, logs scroll logic, or any non-scroll UI behavior are untouched.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Fixes https://github.com/openclaw/openclaw/issues/76966
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: scheduleChatScroll calls target.scrollTo({top: scrollHeight}) to pin the viewport. This fires a scroll event that handleChatScroll handles. By the time that event fires, streamed content has already grown scrollHeight, so distanceFromBottom = newScrollHeight - oldScrollTop - clientHeight exceeds NEAR_BOTTOM_THRESHOLD (450 px). handleChatScroll then sets chatUserNearBottom = false, and all subsequent streaming ticks see shouldStick = false — auto-scroll breaks.
• Missing detection / guardrail: No distinction between scroll events caused by the user versus those caused by our own scrollTo calls. handleChatScroll treated both identically.
• Contributing context: The bug is intermittent because it depends on how fast content grows between the scrollTo call and the scroll event dispatch — slower models or short responses may not trigger it.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: ui/src/ui/app-scroll.test.ts
• Scenario the test should lock in: When chatIsProgrammaticScroll is true, calling handleChatScroll with a scroll event whose distanceFromBottom exceeds the threshold must NOT flip chatUserNearBottom to false.
• Why this is the smallest reliable guardrail: Pure unit test, no DOM rendering needed — just the flag + event handler interaction.
• Existing test that already covers this: None before this PR.
• If no new test is added, why not: N/A — three new tests added in the "programmatic scroll guard" suite (16 total, all passing).

User-visible / Behavior Changes

• Streaming assistant responses in Control UI/webchat now stay pinned to the bottom of the viewport. Previously the chat could scroll upward mid-stream and require manual scroll-down.
• User-initiated scroll-up while streaming still correctly pauses auto-scroll (behavior unchanged).

Diagram (if applicable)

Before:
[streaming token] -> scheduleChatScroll -> scrollTo(bottom)
                  -> scroll event fires -> handleChatScroll
                  -> distanceFromBottom > 450 (content grew)
                  -> chatUserNearBottom = false
                  -> next token: shouldStick = false -> viewport drifts up

After:
[streaming token] -> scheduleChatScroll -> chatIsProgrammaticScroll = true -> scrollTo(bottom)
                  -> scroll event fires -> handleChatScroll
                  -> chatIsProgrammaticScroll == true -> return early (no state change)
                  -> rAF fires -> chatIsProgrammaticScroll = false
                  -> next token: chatUserNearBottom still true -> stays pinned

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux (Ubuntu, kernel 7.0.0-14-generic) / macOS
• Runtime/container: npm global install, Node 24
• Model/provider: OpenAI GPT-5.5
• Integration/channel: Control UI / webchat
• Relevant config: default

Steps

1. Open Control UI webchat
2. Send a prompt that produces a long streaming assistant response
3. Watch the chat viewport while tokens stream in

Expected

• Viewport stays pinned to the newest streamed token throughout generation

Actual (before fix)

• Viewport scrolls upward intermittently; newest content is no longer visible without manually scrolling down

Evidence

• Failing test/log before + passing after — app-scroll.test.ts: 16 tests pass after the fix; the new "programmatic scroll guard" suite directly exercises the previously missing guard. Before this PR, handleChatScroll with distanceFromBottom > 450 would unconditionally set chatUserNearBottom = false even during a programmatic scroll.

Human Verification (required)

• Verified scenarios: Unit test suite for app-scroll.ts passes (16/16). Flag lifecycle (set before scroll, cleared after rAF) verified in "scheduleChatScroll sets chatIsProgrammaticScroll…" test.
• Edge cases checked: Flag already cleared before user scroll — real user scroll-up correctly flips chatUserNearBottom to false (verified in third new test). resetChatScroll also clears the flag.
• What you did not verify: Live browser smoke against a running gateway with a real streaming response.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: requestAnimationFrame fires before the browser dispatches the scroll event in some edge cases (e.g. very fast rAF in a headless environment), clearing the flag too early.
  • Mitigation: In that case the behavior degrades to the pre-fix behavior for that single tick — the retry path in scheduleChatScroll (120 ms timeout) re-scrolls and sets the flag again, recovering on the very next cycle.

Changed files

• CHANGELOG.md (modified, +1/-0)
• ui/src/ui/app-scroll.test.ts (modified, +69/-0)
• ui/src/ui/app-scroll.ts (modified, +16/-0)
• ui/src/ui/app.ts (modified, +1/-0)