Skip to content

fix(window): reflow on macOS occlusion-reveal so the bottom bar is not clipped - #10056

Merged
brennanb2025 merged 3 commits into
mainfrom
brennanb2025/sta2383-bottom-bar
Jul 24, 2026
Merged

brennanb2025 merged 3 commits into
mainfrom
brennanb2025/sta2383-bottom-bar

Conversation

@brennanb2025

@brennanb2025 brennanb2025 commented Jul 23, 2026 •

Copy link
Copy Markdown
Contributor

Fixes STA-2383 ("no bottom bar" after the window is uncovered).

Root cause

On macOS the main window is background-throttled while fully occluded. When it is uncovered again, no restore/show fires — only focus — and the focus handler deliberately runs webContents.invalidate() only (the setSize jiggle there would SIGWINCH every terminal on every Cmd+Tab). invalidate() repaints but does not reflow, so the app-shell h-dvh root keeps the stale dynamic-viewport height it had while throttled. The layout is taller than the real window, and the StatusBar at the bottom of that root sits below the viewport — "no bottom bar" until a manual resize forces a reflow.

Before / after

Stale layout on occlusion-reveal (before) After the forced reflow (after)
sta2383-bottom-bar-before.png sta2383-bottom-bar-after.png

Same 1200×620 window. In the before shot the root is laid out ~100 px taller than the window, so the bottom StatusBar (usage/memory bar) is clipped off-screen; after the reflow it is back. (Visual pair staged by pinning the root to the stale height in the live app — the organic repro needs a viewport change while the renderer is throttled, which the automated rig can't produce without Accessibility access. The fix's actual trigger path is verified live below.)

Fix

The renderer relays a genuine hidden→visible reveal (visibilitychange) to main via a new ui.notifyWindowRevealed IPC; main runs the same proven forceRepaint (invalidate + setSize jiggle) that show/restore/resume already get, which forces the reflow that recomputes the stale layout.

  • Occlusion-gated: a visible-but-unfocused window never changes visibilityState, so plain Cmd+Tab focus switches still never jiggle (no per-focus SIGWINCH regression). Only genuine occlusion-reveals — exactly the broken case — trigger it.
  • Darwin-scoped, sender-guarded, leak-free: runtime platform checks on both sides, paired-web/SSH client gets a no-op stub, event.sender must be the main window's webContents, listener removed in the same closed handler as the existing repaint timer.
  • User resizes win: the 32 ms jiggle restore only runs when bounds are still exactly the transient width+1 × height, so a real user resize/maximize/fullscreen during the jiggle owns the final bounds.

Live verification (dev build, real occlusion)

Covered the window with another app's window for ~25–75 s, then uncovered it, with in-page event recorders and a temporary main-process log:

  • Renderer: visibilitychange → hidden on cover, visible on uncover (genuine occlusion transitions, backgroundThrottling on).
  • Main: reveal IPC accepted -> forceRepaint — the relay fires and passes the sender guard on uncover.
  • With the relay disabled (pre-fix behavior), the same occlusion-reveal produced zero resize/reflow triggers — confirming invalidate-only recovery is what strands the stale layout.

macOS 26 note (post-#10253 merge)

main's #10253 makes forceRepaint skip the setSize nudge entirely on macOS 26+ (re-entrant frame updates can deadlock AppKit there), so on Tahoe this reveal path degrades to invalidate-only — the reveal IPC still fires (verified live on a macOS 26 machine) but the reflow does not. On macOS ≤ 15 the full fix applies. If STA-2383 reports come in from macOS 26, the follow-up needs a frame-safe reflow trigger (renderer-side) rather than un-gating the jiggle.

Test plan

  • createMainWindow.test.ts (77 ✓): reveal → full repaint with deferred nudge, wrong-sender no-op, jiggle dedup on repeated reveals, mid-jiggle user-resize preservation, listener cleanup on close, Tahoe nudge skip, focus stays invalidate-only.
  • web-preload-api.test.ts (79 ✓): paired-web stub.
  • Live occlusion QA on macOS 26 as above.

…t clipped

Fixes STA-2383.

On macOS the window is background-throttled while hidden; on occlusion-uncover only 'focus' fires and its handler runs webContents.invalidate() (the setSize jiggle is skipped to avoid SIGWINCH-ing terminals). invalidate() repaints but does not reflow, so the app-shell h-dvh root keeps a stale dynamic-viewport height and the StatusBar is clipped below the viewport ('no bottom bar'); a manual resize restores it.

Fix: renderer relays a genuine hidden->visible reveal (visibilitychange) to main via new ui.notifyWindowRevealed IPC; main runs the same proven forceRepaint. Occlusion-gated (no per-Cmd+Tab SIGWINCH regression), darwin-scoped, sender-guarded, cleaned up on close.

Test plan: vitest createMainWindow + web-preload-api green. Recommend on-device macOS occlusion QA before merge.
@coderabbitai

coderabbitai Bot commented Jul 23, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Adds a macOS renderer visibility listener and preload API method that emit ui:window-revealed. The main window validates the sender, triggers repaint recovery, protects user resizes during the jiggle, and removes the listener during teardown. A web API stub and preload contract expose the method. Tests cover sender gating, repaint behavior, repeated reveals, user resizing, and cleanup.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check ⚠️ Warning The description is detailed, but it omits required template sections like AI Review Report, Security Audit, and Notes. Add the missing template sections, including the testing checklist status, AI review findings, security audit, and any platform-specific notes.
✅ Passed checks (3 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly summarizes the macOS occlusion-reveal repaint fix and matches the main change.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@brennanb2025
brennanb2025 merged commit 1b5db4b into main Jul 24, 2026
4 checks passed
enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
…t clipped (stablyai#10056)

* fix(window): reflow on macOS occlusion-reveal so the bottom bar is not clipped

Fixes STA-2383.

On macOS the window is background-throttled while hidden; on occlusion-uncover only 'focus' fires and its handler runs webContents.invalidate() (the setSize jiggle is skipped to avoid SIGWINCH-ing terminals). invalidate() repaints but does not reflow, so the app-shell h-dvh root keeps a stale dynamic-viewport height and the StatusBar is clipped below the viewport ('no bottom bar'); a manual resize restores it.

Fix: renderer relays a genuine hidden->visible reveal (visibilitychange) to main via new ui.notifyWindowRevealed IPC; main runs the same proven forceRepaint. Occlusion-gated (no per-Cmd+Tab SIGWINCH regression), darwin-scoped, sender-guarded, cleaned up on close.

Test plan: vitest createMainWindow + web-preload-api green. Recommend on-device macOS occlusion QA before merge.

* fix(window): preserve user resizes during reveal repaint
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant