Decision: declarative native window chrome

Copy Markdown View Source

GPUI exposes two renderer-independent window chrome modes:

window "Application" do
  chrome(:system)
  root(MyView)
end

window "Application" do
  chrome(:content)
  root(MyView)
end

:system is the default. The platform owns the title bar and its ordinary controls. :content extends application content into the title-bar region and lets the application compose its visible chrome from ordinary elements.

Neutral control regions

Application-rendered chrome uses window_control on ordinary containers:

<div class="flex h-10 items-center" window_control="drag">
  <text>Application</text>
  <div class="flex grow" />
  <button window_control="minimize"><text>–</text></button>
  <button window_control="maximize"><text>□</text></button>
  <button window_control="close"><text>×</text></button>
</div>

The closed vocabulary is:

  • drag
  • minimize
  • maximize
  • close

These are native window-control regions, not ordinary application events. Visible labels, icons, spacing, hover presentation, and control arrangement remain application-owned. Consumers must not assume identical control geometry or placement across platforms.

Platform interpretation

  • macOS: content chrome uses a transparent full-size title bar and retains the system traffic lights. Drag regions ask AppKit to perform the current window drag. Application-rendered minimize/maximize/close controls are supported but usually unnecessary when traffic lights remain visible.
  • Windows: content chrome removes the standard caption presentation. Control regions use native non-client hit testing, preserving Snap Layouts and ordinary caption-button behavior.
  • Linux: content chrome requests client-side decorations. Wayland compositors may refuse the request; X11 may fall back to server decorations when no compositor supports client decoration. When client decoration is active, the application must render usable controls.

Chrome does not promise pixel-identical windows or identical system-control placement.

Snapshot authority and reconciliation

Chrome is a GPUI.WindowSpec fact and is serialized in ordinary snapshots, including remote snapshots. It is not an imperative remote-window RPC.

Chrome is a creation-time platform option in the pinned GPUI APIs. If a snapshot changes a window's chrome or another creation-time window option, the local display closes and reopens that native window while retaining the same session window ID. Native focus, position, and other transient platform state may therefore reset. Applications should normally keep chrome stable for a window's lifetime.

The window title remains an accessibility and task-switcher fact even when the visible title is application-rendered.

Close policy

A content-chrome close control enters the same asynchronous close-request path as ordinary system chrome. It never blocks the GPUI loop waiting for the BEAM. Views with handle_window_event/3 may keep the window open with {:noreply, assigns} or approve closure with {:close, assigns}.

Deliberately deferred

The first contract does not expose:

  • macOS traffic-light coordinates;
  • arbitrary platform button layouts;
  • custom window-menu policy;
  • Mica, blur, or transparent window backgrounds;
  • controlled minimized, maximized, or fullscreen state;
  • window geometry commands;
  • platform-specific title-bar APIs.

Those require separate bounded contracts and platform evidence.