Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · App internals

Window frame

On this page
  1. Per platform
  2. Store build: no private API
  3. macOS direct build
  4. Windows and Linux
  5. Resizing
  6. Detached window
  7. Test build

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#

BuildFrameCorners
macOS directtransparent window over Liquid Glass (macOS 26+) or the popover materialrounded, 12 pt
macOS App Storesolid, the page paints --color-bg, normal window shadowrounded, 12 pt
Windows 11solidrounded by DWM
Windows 10, Linuxsolidsquare
Plain browsersolid (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": false in tauri.conf.json and built in frame::create_main. Transparency and effects are only requested when frame_for(Platform::Mac, store = false) returns Vibrancy. The store build (Cargo feature store) never calls transparent, so the private key is never touched and the frame is the normal opaque window.
  • macOSPrivateApi stays off in every config.
  • Corners: frame_macos::round_corners gives the window's content view a layer (NSView.wantsLayer) with CALayer.cornerRadius = frame::CORNER_RADIUS, cornerCurve continuous and masksToBounds, 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-bg behind every pixel, so the frame stays solid (also with Reduce transparency).
  • Shadow: kept on (NSWindow.hasShadow, then invalidateShadow). 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: the NSWindow is looked up among NSApplication.windows by comparing it with Tauri's ns_window() handle, so no raw pointer is dereferenced. All calls are safe objc2 bindings (objc2-app-kit, objc2-quartz-core); kCALayerCornerCurveContinuous is passed by its documented string value continuous instead of reading the extern static.
  • No window-vibrancy setCornerRadius and no NSVisualEffectView/NSGlassEffectView in this build; translucency there is a separate spike.
  • The string drawsBackground still exists in the binary as a constant in wry's code; that branch only runs for transparent, which the store build never requests. It is no Objective-C selector (__objc_methname does 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], state Active, radius frame::CORNER_RADIUS (12 pt, mirrored as --radius-window). Tauri applies the first effect the system supports:
    • macOS 26 and later: NSGlassEffectView with its public cornerRadius.
    • macOS 15 and older: NSVisualEffectView with the popover material; the corner radius goes through window-vibrancy's undocumented setCornerRadius. Acceptable only because this build is not reviewed by Apple; it is the second reason the store build stays solid.
  • 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 #root with border-radius: var(--radius-window), never on body: 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": true with "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.
  • Bounds: at least 400 x 320 logical points (minWidth/minHeight in tauri.conf.json); at most the work area of the screen the tray icon is on (set_max_size each time the window opens). store::fit_size applies 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_main gives 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.json in 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 (command reset_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-detach or Cmd+Shift+D (macOS) / Ctrl+Shift+D (Windows, Linux), command detach_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.json whenever the window goes back (and before quit), in logical points of the desktop. store::place_detached reopens 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 like window.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 via data-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 through data-titlebar="overlay" and keeps --titlebar-inset (physical left in every language) free for the buttons and --titlebar-height as its minimum height. The inset is where the zoom button ends plus 14 pt (#741): frame_macos::window_buttons_end measures it natively and hands it over as --titlebar-buttons-end when 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 are data-tauri-drag-region="deep": dragging moves the window, a double click zooms it, buttons keep their clicks (capability core: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_mode and the window-mode event (popover or detached); 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 popover so the shell-detach and shell-attach flows behave as in the normal build. frame::framed is true for it, so it gets the detached window's native frame, and the shell adds data-decorated on <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. After shell-attach it 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.
Docs version: dev