Repository navigation
feat(macos): make the translucent window surface an opt-in setting - #1788
Merged
Merged
Conversation
The macOS main window stacked the native `sidebar` vibrancy material behind a transparent Electron surface. WindowServer recomposites that material on every frame the window stays dirty, so an idle focused window held GPU near 40% on Apple Silicon while a minimized one returned to the desktop baseline (issue #1064). Bounding idle indicator animations reduced the load but could not remove it, because the material itself kept the window in the compositor's per-frame path regardless of what the renderer painted. macOS now paints the same opaque native background the other platforms already use. The frameless `hiddenInset` titlebar, the inset traffic-light position, and the renderer's sidebar tint and sheen are unchanged, so the surface still reads as glass over the host palette. `applyNativeThemeSource` no longer re-applies a material, and the `window.setBackgroundColor` IPC no longer returns early on darwin, which means a granted `windowAppearance.backgroundColor` plugin theme is applied on macOS like everywhere else (ADR 0248). ADR 0330 records the decision and the measurement; the specs that described the vibrancy plate are updated in the same change. (cherry picked from commit 1a535a2)
An opaque macOS surface keeps the window out of WindowServer's per-frame recomposition path (#1064), but it also drops the live wallpaper blur some users want. The surface is now one explicit choice: opaque by default, and Settings > General > Appearance > Translucent window restores the sidebar vibrancy material. Electron fixes `transparent` when a window is created, so the preference is read before `new BrowserWindow` and applies on the next launch. The settings row asks the main process which surface it actually created (window control getState) and shows a restart hint while the two disagree, rather than mutating a live window or faking the switch. `macosWindowSurfaceOptions` is now the only declaration of the macOS surface, so a theme change keeps repainting the opaque window while a translucent one keeps its material, and ADR 0332 records the revised decision.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Off (and absent) keeps the opaque native surface that keeps the window out of
WindowServer's per-frame recomposition path ([Bug] macOS：侧栏“运行中”状态动画导致 WindowServer GPU 占用显著升高 #1064); on restores the
sidebarvibrancy material behind a transparent backing.macosWindowSurfaceOptions(translucent, color)becomes the only declaration ofthe macOS surface;
mainWindowBackgroundOptions("darwin", color)still returnsthe opaque one, and
applyMainWindowBackgroundkeeps repainting it on themechanges.
window.setBackgroundColorno longer paints a plugin theme colour over it.
transparentat window creation, so the preference is readbefore
new BrowserWindowand a change applies on the next launch. The rowreads the surface the main process actually created (
window/controlgetState) and shows a "Restart to apply" badge while the two disagree.This builds on #1752 by keeping its opaque-surface fix as the default and adding
the user-facing choice the ADR had rejected as a default, not as an option.
Verification
apps/desktoptypecheck: passbiome lint(repo config): 125 files, no findingsapps/desktopnode --test: 4143 tests, 4140 pass, 0 fail (3 skipped)packages/sharedvitest: 1280 pass;packages/i18nvitest: 30 passapps/desktop/test/macos-window-translucency.test.mjscovers the settingdefault, the creation-only surface, the darwin-only row, and write validation.
Not run:
verify:ui:*(native translucency is verified by the unit contractsonly; no Electron instance was started).
Docs: ADR 0332 (revised decision), ADR 0248,
04-ux/06-settings-ia.md,04-ux/08-component-spec.md,04-ux/07-ui-design-system.md, plugin permissionsmatrix, decisions log (D666).