* fix(desktop): stop layering Windows glass windows, and don't make them transparent
A Windows chat window under glass rendered while focused and went dead the
moment it lost it. Two things put it on a compositing path DWM will not draw
acrylic behind, both no-ops that looked free:
`opacity: windowOpacity()` was passed on every window. Under glass on Windows
fade is 0, so the value is always 1 — but Electron's `SetOpacity` calls
`SetLayered()` and `SetLayeredWindowAttributes(..., LWA_ALPHA)` before it looks
at the value, and nothing ever takes `WS_EX_LAYERED` back off. A layered window
composites through the legacy redirection surface, which Windows documents as
mutually exclusive with `UpdateLayeredWindow`. Opacity is now only passed when
the state actually fades, and the runtime path keeps setting it for a window
that is already faded so it can still come back to opaque.
`transparent: true` was set on every glass-capable Windows chat window, on the
premise that DWM materials only reach the client area that way (electron#49443,
which was closed as need-info against an EOL Electron 28). They do not need it:
`IsTranslucent` answers yes off `background_material_` alone, which is what
gives the page its transparent default backing, and `SetBackgroundMaterial`
flips widget translucency live. Its one gate is a frameless window, and
`titleBarStyle: 'hidden'` already satisfies it. What `transparent` did add was
permanent — the widget pinned to kTranslucent for the window's whole life, so
even glass-OFF windows paid a DirectComposition redraw per frame
(electron#39895), plus the documented transparent-window limits, including that
a resizable transparent window is unsupported and breaks (electron#48421).
Both landed latent in #89837 and only surfaced when #90587 turned glass on by
default and dropped the opaque backing that had been hiding them.
* docs(desktop): name the one thing the opacity guard cannot undo
Electron exposes no way back off WS_EX_LAYERED, so a Windows window that has
been faded once keeps the layered compositing path until it is recreated. Not
opening the door on the default path is the whole of the fix; say so where the
guard lives rather than leaving a reviewer to work out the gap.
The light default carries a single point of fade so the window edge reads as
glass rather than as paint. That point followed anyone who dragged the tint
to zero, leaving a window that asked to be opaque sitting at 0.9999.
Fade now applies only while glass is actually active, not merely selected.
Translucency was one number serving both appearances and both platforms,
resting at zero. A lever that starts at zero is a feature nobody finds, and
one number cannot serve four situations: a tint that reads as a whisper over
a dark palette is a milky sheet over a light one, and the same numbers that
read as frost on macOS vibrancy read as a washed sheet over Windows acrylic,
which composites its own tint in DWM before the page is drawn.
So the state splits. `mode` stays global — clear versus glass is a choice
about the window, not the palette — while the values resolve through a
ladder, per key: the appearance you are looking at, then a shared base, then
the platform default. Tuning light mode stays in light mode; an untouched
dark keeps inheriting. A v1 state lands in base, so a window someone already
tuned crosses the upgrade with exactly what was on screen.
Main reads the same defaults at window creation, because a window born
opaque cannot reliably be swapped to glass afterwards.
The chat backdrop goes off by default in the same pass: it was competing
with the glass field for the same surface.
The HUD asked for vibrancy directly and always with the 'hud' material —
one of the two rungs the macOS census rejected, because it collapses into
under-window on blur and so changed the frost the moment another app took
focus. It also ignored the translucency setting entirely: Glass off still
frosted, and Windows got nothing at all.
hudFrostFor is the mapping for a transparent window, beside vibrancyFor in
the shared module both processes read. Two gates give it its answer: the
renderer's report that the band actually covers the window, and the user's
Glass setting. Off resolves to no material rather than a resting one, since
a transparent window has no opaque page to hide an unwanted frost behind.
Windows 11 rides setBackgroundMaterial through the same call, so the HUD
follows the frost ladder on both platforms. Main self-diffs and keys the
latch to the window, so a Settings change re-frosts a live HUD, a tint drag
touches nothing native, and a HUD respawned on another profile is not
mistaken for the window that already carried the material.
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.
Window Translucency shipped defaulting to Clear, which means the mode worth
finding is the one nobody sees — Glass is the better-looking half and the
reason the feature exists. A fresh macOS profile now starts with Glass
selected.
Nothing turns on. The intensity still defaults to 0, so the window is
byte-for-byte what it is today until the user moves the lever; the default
only decides which mode that lever will drive. windowOpacityFor stays 1 and
the window is still born with its opaque backing.
The one profile that must NOT flip is one already carrying a non-zero
intensity with no mode recorded: it predates the setting, has been rendering
as clear the whole time, and defaulting it to glass would change a window
someone deliberately tuned. normalizeMode takes the saved intensity and keeps
those on clear.
The renderer store was hand-rolling its own copy of this rule, so it now
routes through the shared normalizer and the two can't disagree.
The store's default test only passed because a beforeEach reset the atom
before it looked — it asserted the post-reset value, not the default, so it
would have stayed green through this change. It now snapshots the atom at
import time. All three mutations (default back to clear, escape hatch
removed, glass leaking onto non-mac) fail the suite.
Dragging the intensity slider was janky, and the four frost levels looked
nearly identical. Same cause.
At step=1 a drag emits ~100 updates, and every one of them did four
expensive things: a synchronous localStorage.setItem, an IPC wake, a
synchronous fs.writeFileSync in main, and setVibrancy + setBackgroundColor
on every open window. The vibrancy call is the one that also broke the
frost picker — it animates over 150ms, so re-issuing it per tick restarted
the animation before macOS could ever settle the material. The levels
weren't indistinguishable, they were never finishing.
The fix follows from a property the mode already has: under glass the
intensity is a pure renderer concern. windowOpacityFor returns 1 for the
whole range, so main has nothing to do on an intensity change at all.
- main diffs the incoming state against the current one and passes a
`changed` set to applyWindowTranslucency. An intensity-only change under
glass now touches zero native properties. Crossing zero still moves the
backing, since that flips glass on and off.
- main's disk write is coalesced onto a 250ms trailing timer, flushed on
before-quit. Only a cold launch reads that file.
- the renderer paints every tick (the field has to track the hand) but
coalesces the localStorage write and the IPC send onto a 120ms trailing
timer, flushed on pagehide.
Covered as contracts rather than timings: a table asserting exactly what
each kind of update changes natively (nothing, across the whole intensity
range under glass), and store tests that a six-tick drag produces one write
and one IPC call while every intermediate value still paints. Both
directions mutation-checked — restoring per-tick writes fails, and
debouncing the paint fails too.
Restores the four features SHL0MS built on #84329 that an earlier pass on
this branch had carved out, reconciled onto the shared translucency state
rather than the four-atom store they were written against.
- Frost picker. macOS exposes no blur-radius knob, so the vibrancy material
IS the frost control. The four in the ladder come from a pixel census on
macOS 26: the 14 Electron materials collapse to 9 distinct looks, and
these four are the widest separations that stay distinct in BOTH
appearances. sidebar/hud collapse into under-window when unfocused, which
is why they're deliberately absent -- normalizeMaterial rejects them, with
a test saying why.
- Sidebar-only glass, the Finder shape. <body> stays the single painter and
splits at the rail's live-measured edge with a hard gradient stop, so
there's no smear across the seam and no per-layer tint stacking. RTL
mirrors.
- Full-range tint. glassSurfaceKeep runs linear to zero, so the top of the
lever is bare untinted blur instead of stopping at a 30% wash. Text, cards
and the composer keep their own opaque tokens, which is what makes 100%
usable rather than unreadable.
- Peek. The settings overlay covers the very effect its slider controls, so
holding the slider ghosts the whole overlay layer and the live window
becomes the preview. A counter, not a boolean: a held drag and a timed
pulse from a picker click overlap, and the drag must not be cancelled by a
pulse expiring underneath it.
One change from the original: the peek's transition is scoped with :has() to
the overlay that arms it. The version on #84329 shipped a bare
`[data-overlay-surface] { transition: opacity 420ms }`, which gave every
overlay in the app -- command center, cron, agents, model picker -- a 420ms
opacity transition for the life of the process to serve one slider. Verified
by running the candidate rules through lightningcss: the scoped selectors
survive minification and no un-gated overlay transition remains.
visualEffectState is pinned to 'active' at each chat window, because several
materials collapse to a shared inactive look on blur -- without it the frost
choice silently erases itself whenever the user clicks another app.
Co-authored-by: SHL0MS <SHL0MS@users.noreply.github.com>
The mapping had grown three copies: the clear-mode ramp in
electron/window-opacity.ts, a second clamp + mode normalizer in
electron/translucency.ts, and a third clamp in the renderer store, with a
"keep in sync" comment standing in for a shared type. Anything the two
processes must agree on -- what a mode is, where the lever clamps, what
intensity means as an opacity -- now lives in apps/shared/src/translucency.ts
and both ends import it.
electron/translucency.ts keeps only the piece that needs a BrowserWindow to
mean anything (the constructor backing), and re-exports the rest so main.ts
has a single import. Its relative specifier is deliberate: the electron
bundle is built by esbuild with no tsconfig path resolution, so a bare
@hermes/shared/translucency would typecheck and then fail to bundle -- the
same constraint connection-registry.test.ts documents for backendScopeKey.
The renderer's tsconfig drops its reference to the electron project. With
both projects claiming the shared file, that edge made the renderer resolve
it through the electron project's build output and demand a prior
`tsc --build`. Nothing in src/ consumes electron's emitted types, so the
reference bought nothing; `npm run typecheck` still checks both projects.
Constructor backgroundColor with alpha is silently treated as opaque on a
non-transparent window (Electron only documents constructor alpha with
`transparent: true`), so windows created while glass was persisted were
born with an opaque backing and the vibrancy material never showed —
exactly the state a user lands in after toggling glass on and relaunching,
or when the renderer re-reports the persisted state at boot (the IPC
handler correctly dedupes it, so no runtime swap ever fired).
Measured on macOS 26 / Electron 40 (side-by-side spike windows, pixel
luminance): ctor '#00000000' = flat opaque (lum 38, same as no glass);
omitting backgroundColor entirely = vibrancy visible (lum 57). Runtime
setBackgroundColor swaps are also LOST while a fresh process's compositor
is settling — swaps at 1s/3s/6s after creation never landed, including
from 'ready-to-show' and 'did-finish-load'; a 10s swap stuck. So cold
launches must be right at creation: windowBackingOptions() spreads either
{} (glass) or the themed anti-flash backing (everything else) into the
three chat-window constructors. The runtime swap path stays for live
Settings toggles, where the window is long settled.
Two opaque layers sat between the transparent page and the vibrancy material, so glass read as a slight lightening instead of a blur. The contrib shell root and the SidebarProvider wrapper paint full-window opaque fills above body; both are cleared under glass so body's tint is the window's only field paint. And Chromium composites the page against the window backgroundColor before macOS composites the window, so chat windows now get an alpha-0 backing when glass is active, at creation for cold launches and via setBackgroundColor on runtime toggles, scoped to registered chat windows so the transparent special-purpose windows (HUD, pet, quick entry) are untouched.
The translucency slider maps to native window opacity, which fades the whole window including text; over a busy wallpaper even low settings get hard to read. This adds a second mode to the same lever: Glass keeps the window opaque at the native level and instead thins the renderer's field surfaces (chat surface + sidebar) over the macOS vibrancy material every chat window already carries, so the desktop shows through as a smooth matte blur while text keeps full contrast.
One lever, two modes: Clear stays the default and is byte-identical in behavior; Glass is macOS-only (other platforms normalize to clear on both sides of the IPC). Mode persists next to intensity in translucency.json and localStorage, applies live to all open windows, and survives cold launch. Raised surfaces (cards, popovers, composer, terminal) keep opaque fills; the terminal surface is pinned because xterm resolves its background to a concrete color for its canvas.
brooklyn!