feat(desktop): back window glass with Windows 11 system materials

Glass was macOS-only because it rode setVibrancy. Windows 11 22H2 has a
first-party equivalent in setBackgroundMaterial, so the mode now resolves
its backing per platform instead of per-OS-check: macOS keeps vibrancy,
Windows 11 gets DWM acrylic / tabbed / mica, and everything older stays on
Clear. No third-party native addon.

Two Windows-specific details the mapping has to respect. DWM only paints
the client area of a transparent window (electron#49443), so glass-capable
Windows chat windows are born transparent with the opaque themed
backgroundColor covering them while glass is off — a live Clear/Glass
toggle then needs no window recreate. And Windows exposes three backdrops
for four frost rungs, so the two heaviest both resolve to mica; the mapping
stays total so a frost saved on a Mac still renders.

Glass support is computed once from os.release() and shared: main uses it
for the persisted default and every window, preload publishes it to the
renderer so the UI can't offer a mode the window can't back.
This commit is contained in:
Brooklyn Nicholson
2026-08-19 02:09:58 -05:00
parent b5455fdd16
commit eb52328857
17 changed files with 476 additions and 93 deletions
+8
View File
@@ -63,6 +63,7 @@ export {
type SkinColorToken
} from './skin'
export {
backgroundMaterialFor,
clampIntensity,
DEFAULT_GLASS_MATERIAL,
DEFAULT_GLASS_SCOPE,
@@ -71,6 +72,9 @@ export {
glassActive,
type GlassMaterial,
type GlassScope,
glassMaterialForPicker,
glassMaterialsFor,
glassSupportedOn,
glassSurfaceKeep,
normalizeMaterial,
normalizeMode,
@@ -83,7 +87,11 @@ export {
TRANSLUCENCY_STEP,
type TranslucencyMode,
type TranslucencyState,
translucencySupportedOn,
vibrancyFor,
WINDOWS_BACKGROUND_MATERIALS,
WINDOWS_GLASS_MIN_BUILD,
type WindowsBackgroundMaterial,
windowOpacityFor
} from './translucency'
export {
+148 -30
View File
@@ -8,10 +8,11 @@
* - 'clear' — the main process maps the lever to native window opacity
* (`setOpacity`), so the whole window fades, text included. macOS + Windows;
* `setOpacity` is a no-op on Linux.
* - 'glass' — macOS only. The window stays fully opaque at the native level and
* the renderer thins its page surfaces instead, letting the vibrancy material
* every chat window already carries read as a matte blur while text keeps
* full contrast.
* - 'glass' — the window stays fully opaque at the native level and the
* renderer thins its page surfaces instead, letting a platform material
* read as a matte blur while text keeps full contrast. macOS rides
* `setVibrancy`; Windows 11 (22H2+) rides `setBackgroundMaterial`. Linux
* has no first-party desktop material, so glass is not offered there.
*
* The renderer owns the value and mirrors it to main over IPC; main persists it
* so a cold launch can apply it at window creation, before the renderer reports
@@ -53,8 +54,59 @@ export type GlassScope = (typeof GLASS_SCOPES)[number]
export const DEFAULT_GLASS_SCOPE: GlassScope = 'window'
/**
* Electron `setBackgroundMaterial` values. `'auto'` is deliberately absent —
* it lets DWM pick, which would silently erase the frost choice.
*/
export const WINDOWS_BACKGROUND_MATERIALS = ['acrylic', 'tabbed', 'mica', 'none'] as const
export type WindowsBackgroundMaterial = (typeof WINDOWS_BACKGROUND_MATERIALS)[number]
/**
* Frost (sheer → heavy) → Windows 11 system backdrop. Acrylic is the live-blur
* transient material, closest to macOS under-window vibrancy; tabbed and mica
* sample the wallpaper and read more opaque.
*
* Three backdrops for four rungs, so the two heaviest both land on mica. The
* mapping stays total — a frost saved on a Mac still resolves — and the PICKER
* drops the duplicate instead (see `glassMaterialsFor`).
*/
const WINDOWS_MATERIAL_BY_FROST: Record<GlassMaterial, Exclude<WindowsBackgroundMaterial, 'none'>> = {
'under-window': 'acrylic',
popover: 'tabbed',
titlebar: 'mica',
header: 'mica'
}
/**
* The frost rungs Windows can render as DISTINCT looks: the first rung for each
* backdrop. Shipping two options that composite identically is the mistake the
* macOS census already corrected once (sidebar/hud); deriving the list from the
* mapping means a change there can never reintroduce a duplicate.
*/
const WINDOWS_GLASS_MATERIALS: readonly GlassMaterial[] = GLASS_MATERIALS.filter(
(material, index) =>
GLASS_MATERIALS.findIndex(rung => WINDOWS_MATERIAL_BY_FROST[rung] === WINDOWS_MATERIAL_BY_FROST[material]) === index
)
/**
* Windows 11 22H2 (build 22621) is the floor Electron documents for
* `setBackgroundMaterial`. Windows 11 still reports kernel 10.0; the build
* number is the discriminator. Fail closed on a missing/unparseable release.
*
* @see https://www.electronjs.org/docs/latest/api/browser-window#winsetbackgroundmaterialmaterial-windows
*/
export const WINDOWS_GLASS_MIN_BUILD = 22621
export interface TranslucencyState {
intensity: number
/**
* Glass only: native window opacity, on the same ramp Clear's lever uses.
* Defaults to 0 (no fade) because fading a glass window fades its text too —
* the very thing Glass exists to avoid. It is offered as a deliberate second
* lever, never as part of the tint.
*/
fade: number
mode: TranslucencyMode
material: GlassMaterial
scope: GlassScope
@@ -84,20 +136,49 @@ export function clampIntensity(value: unknown): number {
}
/**
* Glass rides on the macOS vibrancy material, so it is macOS-only and 'clear'
* is the fallback everywhere else.
*
* With no mode recorded, macOS gets glass — it is the better-looking half of
* the feature and the one worth finding, and pre-selecting it costs a fresh
* profile nothing because the intensity still starts at 0 (the whole feature
* is off until the user raises the lever). `legacyIntensity` is the escape
* hatch: a profile that already carries a NON-ZERO intensity but no mode
* predates this setting and has been rendering as clear all along, so it keeps
* rendering as clear. Flipping a window someone already tuned is the one thing
* a default must not do.
* Whether this OS can do ANY translucency. Clear rides `setOpacity`, which
* Electron documents as doing nothing on Linux, and glass needs a native
* material Linux does not have — so the whole setting is dead there and the
* row should not be shown at all.
*/
export function normalizeMode(value: unknown, isMac: boolean, legacyIntensity = 0): TranslucencyMode {
if (!isMac) {
export function translucencySupportedOn(platform: string): boolean {
return platform === 'darwin' || platform === 'win32'
}
/**
* Whether this OS can back glass with a first-party Electron material.
* macOS: `setVibrancy`. Windows 11 22H2+: `setBackgroundMaterial`. Linux and
* older Windows: no.
*/
export function glassSupportedOn(platform: string, release = ''): boolean {
if (platform === 'darwin') {
return true
}
if (platform !== 'win32') {
return false
}
const build = Number.parseInt(release.split('.')[2] ?? '', 10)
return Number.isFinite(build) && build >= WINDOWS_GLASS_MIN_BUILD
}
/**
* Glass needs a native window material, so unsupported platforms stay on
* 'clear'.
*
* With no mode recorded, a glass-capable OS gets glass — it is the
* better-looking half of the feature and the one worth finding, and
* pre-selecting it costs a fresh profile nothing because the intensity still
* starts at 0 (the whole feature is off until the user raises the lever).
* `legacyIntensity` is the escape hatch: a profile that already carries a
* NON-ZERO intensity but no mode predates this setting and has been rendering
* as clear all along, so it keeps rendering as clear. Flipping a window
* someone already tuned is the one thing a default must not do.
*/
export function normalizeMode(value: unknown, glassSupported: boolean, legacyIntensity = 0): TranslucencyMode {
if (!glassSupported) {
return 'clear'
}
@@ -119,32 +200,38 @@ export function normalizeScope(value: unknown): GlassScope {
}
/** Parse a persisted translucency.json / IPC payload into a safe state. */
export function normalizeState(payload: unknown, isMac: boolean): TranslucencyState {
export function normalizeState(payload: unknown, glassSupported: boolean): TranslucencyState {
const record = payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : {}
const intensity = clampIntensity(record.intensity)
return {
intensity,
mode: normalizeMode(record.mode, isMac, intensity),
fade: clampIntensity(record.fade),
mode: normalizeMode(record.mode, glassSupported, intensity),
material: normalizeMaterial(record.material),
scope: normalizeScope(record.scope)
}
}
/**
* Native window opacity for a state. Glass never fades the native window — its
* see-through effect is painted by the renderer over the vibrancy material.
*/
export function windowOpacityFor({ intensity, mode }: TranslucencyState): number {
if (mode === 'glass') {
return 1
}
const ratio = clampIntensity(intensity) / TRANSLUCENCY_MAX
/** Lever percent → native window opacity, floored so it stays usable. */
function opacityRamp(lever: number): number {
const ratio = clampIntensity(lever) / TRANSLUCENCY_MAX
return 1 - (1 - TRANSLUCENCY_OPACITY_FLOOR) * Math.pow(ratio, TRANSLUCENCY_CURVE)
}
/**
* Native window opacity for a state.
*
* Under Clear the lever IS the opacity. Under Glass the lever paints the tint
* and only the separate `fade` reaches the window, so a glass window stays at
* 1 until the user opts into fading it — which is what keeps a tint drag from
* touching anything native.
*/
export function windowOpacityFor({ intensity, fade, mode }: TranslucencyState): number {
return opacityRamp(mode === 'glass' ? fade : intensity)
}
/**
* Whether glass is visually active. Both processes branch on this: main to
* decide a window's backing, the renderer to decide whether to thin surfaces.
@@ -155,7 +242,7 @@ export function glassActive({ intensity, mode }: TranslucencyState): boolean {
/**
* Percent of the surface tint the renderer KEEPS at a given intensity. Linear
* to zero: at 100 the tint is fully gone — bare vibrancy glass — so the slider
* to zero: at 100 the tint is fully gone — bare platform glass — so the slider
* spans the whole range from opaque theme to untinted blur. Text and cards
* keep their own opaque tokens for contrast; only the field surfaces thin.
*/
@@ -172,3 +259,34 @@ export function glassSurfaceKeep(intensity: number): number {
export function vibrancyFor(state: TranslucencyState): GlassMaterial | 'sidebar' {
return glassActive(state) ? state.material : 'sidebar'
}
/**
* The Windows 11 system backdrop a chat window should carry. 'none' while
* glass is off so DWM does not keep drawing mica/acrylic under the opaque
* themed backing.
*/
export function backgroundMaterialFor(state: TranslucencyState): WindowsBackgroundMaterial {
return glassActive(state) ? WINDOWS_MATERIAL_BY_FROST[state.material] : 'none'
}
/** The frost rungs to offer on this platform. */
export function glassMaterialsFor(isWindows: boolean): readonly GlassMaterial[] {
return isWindows ? WINDOWS_GLASS_MATERIALS : GLASS_MATERIALS
}
/**
* The rung the picker highlights. A frost with no rung of its own here — a
* Mac's 'header' read on Windows — folds onto the rung that renders the same
* backdrop, so the picker shows a truthful selection without rewriting the
* value the user saved on their other machine.
*/
export function glassMaterialForPicker(material: GlassMaterial, isWindows: boolean): GlassMaterial {
if (!isWindows) {
return material
}
return (
WINDOWS_GLASS_MATERIALS.find(rung => WINDOWS_MATERIAL_BY_FROST[rung] === WINDOWS_MATERIAL_BY_FROST[material]) ??
DEFAULT_GLASS_MATERIAL
)
}