1# Desktop window controls overlay23Use this experimental recipe when a desktop productivity app has noncritical navigation that earns4the titlebar space. Window Controls Overlay is not Baseline and is currently limited to some desktop5browsers. The generated app remains fully usable in `standalone` mode without it.67## Manifest opt-in and fallback89Keep the portable fallback in `display` and put the experimental mode first in `display_override`:1011```json12{13 "display": "standalone",14 "display_override": ["window-controls-overlay"]15}16```1718The override matters only for an installed desktop app in a supporting browser. A user can toggle19the overlay, so feature presence never means it is visible. Existing installs may require a manifest20refresh, browser restart, or reinstall before a changed display mode takes effect.2122## Collision-free layout2324Let the browser-provided physical geometry define the usable titlebar area. Keep the ordinary header25as the default, then reposition only while the display mode is active:2627```css28.app-titlebar {29 min-block-size: 3rem;30 display: flex;31 align-items: center;32 gap: 0.75rem;33 border-block-end: 1px solid CanvasText;34}3536@media (display-mode: window-controls-overlay) {37 .app-titlebar {38 position: fixed;39 left: env(titlebar-area-x, 0px);40 top: env(titlebar-area-y, 0px);41 width: env(titlebar-area-width, 100%);42 height: env(titlebar-area-height, 3rem);43 min-block-size: 0;44 app-region: drag;45 }4647 .app-titlebar :is(a, button, input, select, textarea) {48 app-region: no-drag;49 }5051 main {52 padding-block-start: env(titlebar-area-height, 3rem);53 }54}5556@media (display-mode: window-controls-overlay) and (max-width: 32rem) {57 .app-titlebar .noncritical-action {58 display: none;59 }60}6162@media (forced-colors: active) {63 .app-titlebar {64 border-color: CanvasText;65 }66}67```6869Do not assume controls are on the right: macOS, Windows, browser UI, RTL, zoom, and resizing can all70change the available physical rectangle. The `titlebar-area-*` variables already exclude system71window controls. Never position content outside their rectangle or cover system-critical controls.7273Only noninteractive empty space should be draggable. Links, buttons, menus, inputs, and focus rings74must remain keyboard reachable and `no-drag`. Preserve a visible title and border in high-contrast75mode, do not communicate state by color alone, and remove noncritical actions before compressing76interactive targets in a narrow window.7778## Runtime geometry7980CSS should own layout. Observe geometry only when application state genuinely needs it:8182```ts83import { observeWindowControlsOverlay } from "@nzip/lofi/recipes/window-controls-overlay";8485const observer = observeWindowControlsOverlay({86 onGeometry({ visible, titlebarArea }) {87 document.documentElement.toggleAttribute("data-overlay-visible", visible);88 console.debug("available titlebar width", titlebarArea.width);89 },90});9192// During component teardown:93observer.dispose();94```9596The observer feature-detects the API, reports initial and changed geometry, and stops cleanly. The97standalone header remains the fallback when unsupported. Geometry events can fire rapidly while98resizing, so avoid synchronous layout reads/writes in the callback and coalesce expensive work.99100Test installed and ordinary browser windows, overlay on/off, resize and zoom, controls on both101sides, LTR and RTL, narrow width, keyboard-only use, drag/no-drag regions, high contrast, offline102startup, manifest updates, and uninstall/reinstall.103104## Tabbed display: no ship105106Lofi does not expose `display_override: ["tabbed"]` or `tab_strip`. As of this evaluation, tabbed107mode remains an incubation proposal without a credible cross-browser installed-app test matrix. Its108home tab rules can also redirect ordinary same-document navigation into other application contexts,109which needs product-specific lifecycle testing. The manifest validator reports it as lacking a110tested lofi recipe. Continue using ordinary in-app document navigation, browser tabs, or separate111standalone windows until implementations and automation support make the semantics portable and112testable.113114References:115[MDN Window Controls Overlay API](https://developer.mozilla.org/en-US/docs/Web/API/Window_Controls_Overlay_API),116[WICG Window Controls Overlay draft](https://wicg.github.io/window-controls-overlay/), and the117[WICG tabbed-mode explainer](https://wicg.github.io/manifest-incubations/tabbed-mode-explainer.html).