For developers · App internals
Window frame
On this page
How the popover window is framed per platform and build type, and why the App Store build stays free of
private API. Code: src-tauri/src/frame.rs and frame_macos.rs (native side), src/ui/tokens.css (block "Window frame").
Per platform#
| Build | Frame | Corners |
|---|---|---|
| macOS direct | transparent window over Liquid Glass (macOS 26+) or the popover material | rounded, 12 pt |
| macOS App Store | solid, the page paints --color-bg, normal window shadow | rounded, 12 pt |
| Windows 11 | solid | rounded by DWM |
| Windows 10, Linux | solid | square |
| Plain browser | solid (no data-frame from the shell) | n/a |
The shell sets data-frame="vibrancy" or data-frame="solid" on <html> through an initialization script,
so the first paint already matches. Only vibrancy lets the material show through; every other value keeps
the solid tokens.
Store build: no private API#
A transparent webview needs WebKit's private key drawsBackground (wry sets it whenever Tauri asks for
transparent). App Store review rejects private API, so the store build keeps an opaque webview and only
rounds the window (Frame::Rounded):
- The main window is declared with
"create": falseintauri.conf.jsonand built inframe::create_main. Transparency and effects are only requested whenframe_for(Platform::Mac, store = false)returnsVibrancy. The store build (Cargo featurestore) never callstransparent, so the private key is never touched and the frame is the normal opaque window. macOSPrivateApistays off in every config.- Corners:
frame_macos::round_cornersgives the window's content view a layer (NSView.wantsLayer) withCALayer.cornerRadius=frame::CORNER_RADIUS,cornerCurvecontinuous andmasksToBounds, so the webview is clipped. The window turns non-opaque with a clear background (NSWindow.isOpaque,NSWindow.backgroundColor=NSColor.clearColor): only the clipped corners are see-through, the page still paints--color-bgbehind every pixel, so the frame stays solid (also with Reduce transparency). - Shadow: kept on (
NSWindow.hasShadow, theninvalidateShadow). For a non-opaque window macOS derives the shadow from the drawn pixels, so it follows the rounded corners; the square outline of the direct build does not occur here because there is no effect view in the square frame. - No
unsafe: theNSWindowis looked up amongNSApplication.windowsby comparing it with Tauri'sns_window()handle, so no raw pointer is dereferenced. All calls are safe objc2 bindings (objc2-app-kit,objc2-quartz-core);kCALayerCornerCurveContinuousis passed by its documented string valuecontinuousinstead of reading the extern static. - No window-vibrancy
setCornerRadiusand noNSVisualEffectView/NSGlassEffectViewin this build; translucency there is a separate spike. - The string
drawsBackgroundstill exists in the binary as a constant in wry's code; that branch only runs fortransparent, which the store build never requests. It is no Objective-C selector (__objc_methnamedoes not contain it).
Public API used (Apple documentation): NSView.wantsLayer, NSView.layer, CALayer.cornerRadius,
CALayer.cornerCurve, CALayer.masksToBounds, NSWindow.isOpaque, NSWindow.backgroundColor,
NSColor.clearColor, NSWindow.hasShadow, NSWindow.invalidateShadow(), NSApplication.windows.
macOS direct build#
- Effects list
[LiquidGlassRegular, Popover], stateActive, radiusframe::CORNER_RADIUS(12 pt, mirrored as--radius-window). Tauri applies the first effect the system supports:- macOS 26 and later:
NSGlassEffectViewwith its publiccornerRadius. - macOS 15 and older:
NSVisualEffectViewwith the popover material; the corner radius goes through window-vibrancy's undocumentedsetCornerRadius. Acceptable only because this build is not reviewed by Apple; it is the second reason the store build stays solid.
- macOS 26 and later:
- No window shadow (
shadow(false)). macOS computes the shadow from the square window frame, not from the rounded material, which left a square dark outline around the corners. - The page paints a veil over the material (
--color-window, 55 % of the solid ground) so text keeps the solid contrast values in light and dark. Dark mode adds a 1 px light inner edge so the window separates from dark wallpapers without a shadow. - The veil sits on
#rootwithborder-radius: var(--radius-window), never onbody: with a transparent<html>, a body background propagates to the whole square canvas and fills the corners. - Reduce transparency (
prefers-reduced-transparency: reduce): macOS draws the material opaque and the veil switches to--color-bg, so the window is solid with the regular contrast.
Windows and Linux#
Opaque windows with the page background. Windows 11 rounds undecorated windows itself (DWM, shadow: true
from the config). Windows 10 and Linux stay square; no effect API is used there. Since the frame is
solid, the page never draws an inner card here: the popover is the DWM-rounded window itself, and the
detached window is a normal decorated window with the page edge to edge (checked on Windows 11, light
and dark, #248).
Resizing#
The popover keeps its tray-anchored, title-bar-free look and can still be resized by dragging any edge or
corner. Code: src-tauri/src/window_size.rs, tray::place_main, core store/window.rs.
- Native resizing, no extra grip: the window is
"resizable": truewith"decorations": false.- macOS: tao uses the style mask
Borderless | Resizable, so AppKit offers the invisible resize edges and corners of a normal window, in both builds. - Windows: tao hit-tests the undecorated window (
WM_NCHITTEST) and, with the DWM shadow on, keeps the invisible resize borders outside the page, so every edge and corner works.
- macOS: tao uses the style mask
- Bounds: at least 400 x 320 logical points (
minWidth/minHeightintauri.conf.json); at most the work area of the screen the tray icon is on (set_max_sizeeach time the window opens).store::fit_sizeapplies both bounds to the remembered size; on a screen smaller than the minimum the minimum wins and the placement keeps the top-left corner on screen. - Size: the popover always opens in the remembered size (default 400 x 680 until the user resizes it); the page never reports a content height and nothing resizes the window on its own.
- Placement:
tray::place_maingives the window its fitted size first and then centres it below (menu bar) or above (bottom taskbar) the tray icon with that size, clamped to the work area, so it never leaves the screen. Without an icon rect the positioner plugin places it as before. - Persistence:
window.jsonin the app config directory (logical points, versioned like the other stores, corrupt or missing file gives the default). The size is stored when the window hides and when the app quits, only if the user changed it: a size the app shrank to fit a smaller screen does not overwrite the wish for a larger one. Local to the installation: settings export and import do not carry it. - Reset: Settings, General, "Window size", button
settings-window-size-reset(commandreset_window_size) stores the default and resizes an open window in place at the tray icon. - Frame at any size: the vibrancy material (direct build) and the content view's rounded layer (store
build) resize with their views; the store build recomputes its pixel-derived shadow after every resize
(
frame::resized,NSWindow.invalidateShadow()). The page has no fixed widths; lists, detail and settings fill the extra space, centred empty states keep a readable measure.
Detached window#
The popover can become a normal app window, for a longer look at the overview. Code:
src-tauri/src/window_mode.rs, core store/detached.rs.
- Detach: header button
shell-detachor Cmd+Shift+D (macOS) / Ctrl+Shift+D (Windows, Linux), commanddetach_window. The same window changes its style, so the page keeps its state: title bar, task bar entry (Dock icon on macOS), not always on top, freely resizable (at least 400 x 320, no upper bound) and no longer hidden on blur. The tray icon and its click keep working and bring the window to the front. - Back: header button
shell-attach, the same shortcut, or closing the window (red button, Alt+F4). The window hides and turns back into the popover; the app keeps running in the tray. Quit stays in the tray menu. - Frame: position and size are stored in
detached-window.jsonwhenever the window goes back (and before quit), in logical points of the desktop.store::place_detachedreopens it there when enough of it lies on a current screen (shrunk to that screen), otherwise at 900 x 700 centred on the main screen (shrunk to its work area on a smaller screen). Local to the installation likewindow.json. - End of the onboarding (#617): its fixed, centred window (never stored as the frame) becomes the
detached window in the stored frame, else the default, and stays in front
(
finish_onboarding_window); the overview and the pending introduction tour open in it, or the setup assistant after an orchestrator run. Closing it returns to the tray like any detached window. It does not switch back to the tray panel: on macOS that made the app an accessory app, which resigned it active, and the blur dismissed the freshly shown panel at once, so nothing appeared. - Size: a size the user dragged is the stored frame; the popover keeps its own size in
window.json, so switching back restores the popover size and switching again restores the window frame. - Frame per build: the detached window always has the system title bar, shadow and corners, and its
content runs edge to edge below the title bar, without the popover's inner card. Switching the mode
switches the native frame too (
frame::apply_mode): the direct macOS build swaps the rounded Liquid Glass / popover material for the square window background material (follows the active state), the store build drops its 12 pt content clip, Windows and Linux keep their solid native frame. The page drops its drawn corners and edge viadata-window="detached"(tokens.css). - Title bar on macOS (#617): framed windows (detached, onboarding, the test build) get a transparent
title bar without its title, the page reaching up beneath it (
frame::title_bar,frame_macos::overlay_title_bar). An empty unified toolbar makes the bar 52 pt tall, so the window buttons sit centred beside the page's top bar: the header with the lockup, or the onboarding's brand bar with the lockup and phases. The page learns it throughdata-titlebar="overlay"and keeps--titlebar-inset(physical left in every language) free for the buttons and--titlebar-heightas its minimum height. The inset is where the zoom button ends plus 14 pt (#741):frame_macos::window_buttons_endmeasures it natively and hands it over as--titlebar-buttons-endwhen the bar switches on and after every resize (so 0 in full screen, where the buttons leave the bar); without a measurement the page assumes 80 pt (macOS 26/27). Both bars aredata-tauri-drag-region="deep": dragging moves the window, a double click zooms it, buttons keep their clicks (capabilitycore:window:allow-start-dragging,core:window:allow-internal-toggle-maximize). The popover switches it all off again. Windows and Linux keep the system title bar. - The page learns the mode from
get_window_modeand thewindow-modeevent (popoverordetached); in detached mode it reports its height but the window keeps the size the user chose.
Test build#
The test build (Cargo feature test-access, "Gitoodo Test") starts with its window open and never hides it
on blur, so automation can drive it without a tray click. Code: frame::framed, window_mode::place_start_window.
- Frame: the window is decorated (system title bar, square corners) from the start, although its logical
mode stays
popoverso theshell-detachandshell-attachflows behave as in the normal build.frame::framedis true for it, so it gets the detached window's native frame, and the shell addsdata-decoratedon<html>; tokens.css then drops the drawn corners and shadow of#root([data-frame="vibrancy"][data-decorated]), so no grey strip or rounded inner card shows below the title bar (#359). - Size (#363): the start window takes the detached frame, not the popover size: the remembered frame from
detached-window.json, otherwise 900 x 700 centred on the main screen, clamped to the work area like the detached window (store::place_detached). Its frame is stored when it is closed, detached or the app quits, so a dragged size comes back on the next start. Aftershell-attachit is the regular popover with the popover size until the next start. - Windows: the same logic applies (work areas from Tauri's monitor list, logical points); the frame is the solid, OS-decorated window.