fix(scroll): coalesce forced repaints across a new-content burst (WebKitGTK half-freeze) (#1012)

## Summary

Fixes the residual WebKitGTK "half-freeze" that testers still hit on
0.17.x — even though #860 (pin-loop convergence) shipped in 0.17.1.

**Root cause.** The pin-to-bottom `forceRepaint()` (an `overflowY`
toggle → forced reflow) is a *full scroller re-layout + repaint* on
WebKitGTK, ~50–150ms each (near-free on Chromium/WKWebView-macOS). #860
made each pin run *converge*, but never coalesced the **rate** of runs:
the `new-message` trigger is ungated, so every arriving message
supersedes the loop and fires a fresh synchronous repaint. A **burst**
of new content — live group chatter, a reaction/media storm, or a
reconnect flushing queued messages — therefore fires one forced
WebKitGTK repaint per arrival, saturating the main thread for up to
~1.5s.

This matches the field reports exactly: the freeze only ever reproduces
while **new content arrives** (messages, reactions, pictures), never on
scrolling or room-switching, and correlates with flaky/Tor connections
(a reconnect delivers a burst).

**Why it stayed unconfirmed.** `[PinLoopProbe]` is per-run with a 50ms
threshold + 5s cooldown, so a burst of ten 60ms repaints logs *one* line
and hides the other ~540ms — structurally blind to bursts.

## Fix

Generalizes the existing MAM-catchup repaint suppression to **live
bursts** (new pure module `pinRepaintBurst.ts`): while content-arrival
pins keep firing within `PIN_BURST_WINDOW_MS` (200ms), the intermediate
`forceRepaint`s are suppressed — the scroll position is still written
via `scrollToIndex`, so the layout stays correct; only the paint is
deferred — and the pin loop's convergence forces exactly **one**
trailing repaint. A burst of N repaints collapses to ~1–2. The first
arrival of a burst still paints immediately, so single sends stay
snappy. Burst state is a hook-level ref so the debt survives loop
supersede and is flushed by whichever run finally converges; reset on
user-scroll takeover and conversation switch.

Also adds a burst-aware `[PinBurstProbe] burst settled: …
suppressedRepaints=N` log line so an on-device log confirms the
mechanism was real and the coalescing engaged.

## Verification

- TDD red/green: `MessageList.pinBottomRepaint.test.tsx` → a burst of 8
messages produces 8 forced repaints without the fix, <8 with it; plus 8
unit tests for the tracker.
- All 50 `test:scroll` WebKit + Chromium scroll invariants pass
(send-stick, at-bottom-stick, reaction-stick, media-drift all intact).
- 653 conversation unit tests, full typecheck (SDK + app), and lint all
green.

WebKitGTK repaint cost is not reproducible on macOS/Chromium, so
on-device confirmation from the reporter (via the new `[PinBurstProbe]`
line) is the final check.

Author: mremond

apps/fluux/src/components/conversation/MessageList.pinBottomRepaint.test.tsx

@@ -132,4 +132,51 @@ describe('MessageList — pin forces a repaint after a programmatic scroll (WebK
     expect(repaint.overflowSets).toContain('hidden')
     expect(repaint.overflowSets[repaint.overflowSets.length - 1]).toBe('')
   })
+
+  // Regression for the WebKitGTK "half-freeze": a BURST of new bottom rows (live chatter, a reconnect
+  // flushing queued messages, a reaction/media storm) used to fire one forced overflow-toggle repaint
+  // PER arrival. On WebKitGTK each is a ~50–150ms full scroller re-layout+repaint, so a burst
+  // saturated the main thread. The burst coalescer suppresses the intermediate repaints (position is
+  // still written) and forces ONE trailing repaint on settle — a burst of N collapses to ~1–2 toggles.
+  it('coalesces a burst of new messages into far fewer forced repaints', () => {
+    const isAtBottomRef = { current: true }
+    const base = makeMessages(50)
+    const { container, rerender } = render(
+      <MessageList messages={base} conversationId="conv-burst" isAtBottomRef={isAtBottomRef} {...props} />,
+    )
+    const scroller = container.querySelector('[data-message-list]') as HTMLElement
+    instrumentScroller(scroller)
+    flush(70) // settle the entry pin
+    repaint.overflowSets = []
+    scrollToEndCalls.count = 0
+
+    // BURST — 8 incoming messages land in rapid succession, each growing the content and firing the
+    // new-message pin, with only a couple of frames between them (the loop cannot fully settle).
+    const burst: BaseMessage[] = []
+    for (let i = 0; i < 8; i++) {
+      burst.push({
+        id: `burst-${i}`, from: `user${i}@example.com`, body: `burst ${i}`,
+        timestamp: new Date(2024, 0, 1, 13, i), isOutgoing: false, type: 'chat',
+      })
+      geo.scrollHeight = 2000 + (i + 1) * 40
+      rerender(
+        <MessageList messages={[...base, ...burst]} conversationId="conv-burst" isAtBottomRef={isAtBottomRef} {...props} />,
+      )
+      flush(2)
+    }
+    // Arrival stops — let the loop converge and flush the single trailing repaint.
+    flush(20)
+
+    // Position was still written for every arrival (layout stays correct — nothing is stranded).
+    expect(scrollToEndCalls.count).toBeGreaterThanOrEqual(8)
+
+    // But the expensive forced repaints were coalesced: far fewer overflow 'hidden' toggles than the
+    // 8 arrivals. Pre-fix this was ~8+ (one per arrival); post-fix it is the first arrival's immediate
+    // paint plus the trailing settle paint.
+    const hiddenToggles = repaint.overflowSets.filter((v) => v === 'hidden').length
+    expect(hiddenToggles).toBeLessThan(8)
+    expect(hiddenToggles).toBeGreaterThan(0) // the final position IS painted (not left stale)
+    // Whatever the last toggle, overflow is restored so scrolling still works.
+    expect(repaint.overflowSets[repaint.overflowSets.length - 1]).toBe('')
+  })
 })

apps/fluux/src/components/conversation/pinRepaintBurst.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest'
+import { createPinRepaintBurst, pinBurstProbeLine, PIN_BURST_WINDOW_MS } from './pinRepaintBurst'
+
+describe('createPinRepaintBurst', () => {
+  it('does NOT suppress an isolated single arrival (snappy common case)', () => {
+    const b = createPinRepaintBurst()
+    b.note(1000)
+    expect(b.suppress(1000)).toBe(false) // first arrival always paints
+    expect(b.owed()).toBe(false)
+  })
+
+  it('suppresses once a second arrival lands within the window', () => {
+    const b = createPinRepaintBurst({ windowMs: 200 })
+    b.note(1000)
+    expect(b.suppress(1000)).toBe(false)
+    b.note(1100) // 100ms later → burst
+    expect(b.suppress(1100)).toBe(true)
+    expect(b.suppress(1200)).toBe(true) // still inside window (1200 - 1100 < 200)
+  })
+
+  it('stops suppressing once the window elapses with no further arrival', () => {
+    const b = createPinRepaintBurst({ windowMs: 200 })
+    b.note(1000)
+    b.note(1100)
+    expect(b.suppress(1100)).toBe(true)
+    expect(b.suppress(1301)).toBe(false) // 1301 - 1100 = 201 >= 200 → window expired
+  })
+
+  it('collapses a burst of N repaints to one owed trailing repaint', () => {
+    const b = createPinRepaintBurst({ windowMs: 200 })
+    let suppressed = 0
+    // Simulate 6 arrivals ~30ms apart, each of which would have painted.
+    for (let i = 0; i < 6; i++) {
+      const now = 1000 + i * 30
+      b.note(now)
+      const wouldPaint = true
+      if (wouldPaint && b.suppress(now)) {
+        b.markSuppressed()
+        suppressed++
+      }
+    }
+    // First arrival painted (not suppressed); the other five were coalesced.
+    expect(suppressed).toBe(5)
+    expect(b.owed()).toBe(true)
+    const summary = b.settle()
+    expect(summary.triggers).toBe(6)
+    expect(summary.suppressedRepaints).toBe(5)
+    expect(summary.spanMs).toBe(150)
+    expect(b.owed()).toBe(false) // settle consumed the debt
+  })
+
+  it('a fresh burst after a quiet gap starts a new count', () => {
+    const b = createPinRepaintBurst({ windowMs: 200 })
+    b.note(1000)
+    b.note(1050)
+    b.settle()
+    b.note(5000) // long gap → new burst
+    expect(b.suppress(5000)).toBe(false)
+    b.note(5050)
+    expect(b.suppress(5050)).toBe(true)
+  })
+
+  it('reset drops all state', () => {
+    const b = createPinRepaintBurst()
+    b.note(1000)
+    b.note(1050)
+    b.markSuppressed()
+    expect(b.owed()).toBe(true)
+    b.reset()
+    expect(b.owed()).toBe(false)
+    expect(b.suppress(1050)).toBe(false)
+  })
+
+  it('exports a sane default window', () => {
+    expect(PIN_BURST_WINDOW_MS).toBeGreaterThanOrEqual(133) // above the 8-frame settle
+  })
+
+  it('probe line reports the coalesced burst', () => {
+    const line = pinBurstProbeLine('new-message', { triggers: 10, suppressedRepaints: 9, spanMs: 280 })
+    expect(line).toContain('[PinBurstProbe]')
+    expect(line).toContain('trigger=new-message')
+    expect(line).toContain('arrivals=10')
+    expect(line).toContain('suppressedRepaints=9')
+    expect(line).toContain('spanMs=280')
+  })
+})

apps/fluux/src/components/conversation/pinRepaintBurst.ts

@@ -0,0 +1,156 @@
+/**
+ * Cross-run burst coalescing for `pinVirtualizedBottom`'s forced repaint.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The pin's `forceRepaint()` (an `overflowY` toggle → forced reflow) is the
+ * dominant main-thread cost on WebKitGTK — a full scroller re-layout + repaint,
+ * ~50–150ms each (near-free on Chromium / WKWebView-macOS). PR #860 made each
+ * INDIVIDUAL pin run converge, but the `new-message` trigger is ungated: every
+ * arriving message supersedes the running loop and starts a fresh run whose first
+ * `writePin` forces a repaint. A BURST of new content — live group chatter, a
+ * reaction storm, images decoding, or a reconnect flushing queued messages —
+ * therefore fires one forced WebKitGTK repaint per message/per frame, saturating
+ * the main thread for hundreds of ms: the "half-freeze" testers hit only while new
+ * content is arriving (never while merely scrolling or switching rooms, which add
+ * no bottom row).
+ *
+ * WHAT IT DOES
+ * ------------
+ * This generalizes the MAM-catch-up suppression (`shouldForceRepaint`'s
+ * `suppressForBackgroundLoad`) to LIVE bursts: while content-arrival pins keep
+ * firing within a short window, intermediate forced repaints are suppressed (the
+ * scroll position is still written, so the layout stays correct — only the paint
+ * is deferred, exactly as during a catch-up). Once arrival quiesces, the pin loop's
+ * convergence forces exactly ONE trailing repaint. A burst of N repaints collapses
+ * to ~1, turning a multi-hundred-ms freeze into a single paint.
+ *
+ * The state lives OUTSIDE any single pin run (a burst spans many superseded runs),
+ * so it is owned by the hook and passed timestamps — pure and unit-testable, like
+ * `pinBottomRun.ts`.
+ */
+
+/**
+ * Two content-arrival pins landing within this window count as a burst; while a
+ * burst is live, forced repaints are suppressed. Sized a touch above the pin
+ * loop's settle time (8 frames ≈ 133ms) so that "arrival stopped long enough for
+ * the loop to converge" reliably implies "burst window expired", letting the
+ * convergence own the single trailing repaint.
+ */
+export const PIN_BURST_WINDOW_MS = 200
+
+/** Summary of a coalesced burst, emitted on the trailing repaint for fluux.log. */
+export interface PinBurstSummary {
+  /** Content-arrival pins observed during the burst (the first one still painted). */
+  triggers: number
+  /** Forced repaints suppressed by the burst — each ~50–150ms of WebKitGTK freeze avoided. */
+  suppressedRepaints: number
+  /** Wall-clock span from the first to the last arrival in the burst. */
+  spanMs: number
+}
+
+export interface PinRepaintBurst {
+  /**
+   * Record a content-arrival pin (new-message / content-growth / media-load /
+   * reaction / mam-catchup-complete). Call at the top of `pinVirtualizedBottom`
+   * for those triggers — BEFORE it supersedes the running loop — so every arrival
+   * is counted even though its run may be immediately replaced.
+   */
+  note(now: number): void
+  /**
+   * Should this frame's forced repaint be suppressed because a burst is in
+   * progress? True once ≥2 arrivals have landed within {@link PIN_BURST_WINDOW_MS}
+   * and the most recent is still inside the window. The very first arrival of a
+   * burst is NOT suppressed, so an isolated single message still paints promptly.
+   */
+  suppress(now: number): boolean
+  /** Note that a forced repaint was skipped due to the burst (a trailing paint is now owed). */
+  markSuppressed(): void
+  /** Whether a trailing repaint is owed (repaints were suppressed since the last settle). */
+  owed(): boolean
+  /**
+   * Consume the owed trailing repaint: clears the owed flag and returns the burst
+   * summary for the probe line. Call from the pin loop's convergence / frames-
+   * exhausted path right before forcing the one final repaint.
+   */
+  settle(): PinBurstSummary
+  /** Drop all burst state (conversation switch, user-scroll takeover). */
+  reset(): void
+}
+
+export function createPinRepaintBurst(
+  opts: { windowMs?: number } = {}
+): PinRepaintBurst {
+  const windowMs = opts.windowMs ?? PIN_BURST_WINDOW_MS
+
+  let firstNoteAt: number | null = null
+  let lastNoteAt: number | null = null
+  let triggers = 0
+  let suppressedRepaints = 0
+  let owedRepaint = false
+
+  const active = (now: number): boolean =>
+    lastNoteAt !== null && triggers >= 2 && now - lastNoteAt < windowMs
+
+  return {
+    note(now: number): void {
+      if (lastNoteAt !== null && now - lastNoteAt >= windowMs) {
+        // The previous burst went quiet long enough to end; this arrival starts a
+        // fresh one. (A trailing repaint owed by the old burst is left owed for the
+        // converging loop to flush.)
+        firstNoteAt = now
+        triggers = 1
+      } else {
+        if (firstNoteAt === null) firstNoteAt = now
+        triggers++
+      }
+      lastNoteAt = now
+    },
+
+    suppress(now: number): boolean {
+      return active(now)
+    },
+
+    markSuppressed(): void {
+      suppressedRepaints++
+      owedRepaint = true
+    },
+
+    owed(): boolean {
+      return owedRepaint
+    },
+
+    settle(): PinBurstSummary {
+      const summary: PinBurstSummary = {
+        triggers,
+        suppressedRepaints,
+        spanMs:
+          firstNoteAt !== null && lastNoteAt !== null
+            ? Math.round(lastNoteAt - firstNoteAt)
+            : 0,
+      }
+      firstNoteAt = null
+      lastNoteAt = null
+      triggers = 0
+      suppressedRepaints = 0
+      owedRepaint = false
+      return summary
+    },
+
+    reset(): void {
+      firstNoteAt = null
+      lastNoteAt = null
+      triggers = 0
+      suppressedRepaints = 0
+      owedRepaint = false
+    },
+  }
+}
+
+/** One fluux.log line attributing a coalesced burst (emitted on the trailing repaint). */
+export function pinBurstProbeLine(trigger: string, summary: PinBurstSummary): string {
+  return (
+    `[PinBurstProbe] burst settled: trigger=${trigger} arrivals=${summary.triggers} ` +
+    `suppressedRepaints=${summary.suppressedRepaints} spanMs=${summary.spanMs} trailingRepaint=1`
+  )
+}