Global Overlays And Dialogs

Purpose

Global overlays are OS-level presentation layers that must escape the clipping, scrolling, and stacking context of an app window. App details, confirmation dialogs, registration forms, shell settings, and future permission prompts should not be trapped inside the app that opened them when the user expects an OS modal.

Current Primitive

Use WindowDialog from @prox-os/os-ui for app-owned dialogs that need global modal behavior.

WindowDialog provides:

a portal to document.body;
a subdued global backdrop;
a window-like titlebar with title, optional subtitle, optional icon, and a close button;
bounded height with body scrolling;
optional footer slot for actions;
Escape key handling through the shared dialog hook;
token-driven radius, border, surface, and shadow styles.

When To Use It

Use WindowDialog when an app opens a modal that should feel like a small OS window rather than app-local content:

App Store app details.
App Store deploy confirmation.
Deploy app registration.
Alma settings.
Future permission, install, publish, export, and destructive-action prompts.

Keep shell-owned overlays in their shell overlay layer when they are part of the desktop runtime itself, such as system dialogs, screensaver, Mission Control, context menus, and shell drawers.

Layering Rules

App-owned global dialogs use WindowDialog; app code should not hand-roll its own fixed overlay shell.
Shell-owned dialogs use the shell overlay layer and must sit above managed app windows, app-owned popovers, Studio-local fixed elements, Global App Window, Mission Control, and shell menus.
Studio surfaces create a bounded stacking context. App-local fixed overlays may be high inside the Studio frame, but they must not outrank shell-owned dialogs or escape the rounded Studio boundary.
App-owned menu portals may use high app-menu z-index values, but they must remain below the shell dialog layer. Avoid unbounded values such as browser integer maxima.
The dialog is a modal surface, not a managed desktop window. It does not get a WindowInstance, Dock item, route, z-index entry, or saved layout.
The titlebar should name the dialog task, not duplicate the app window title.
Long content belongs in the dialog body with internal scrolling; action buttons belong in the footer.
Do not use native browser UI for new OS-facing controls when an os-ui primitive exists. Use SelectControl for token-aligned dropdowns.
Do not bypass browser security boundaries. External web embedding fallback dialogs should explain CSP or X-Frame-Options limitations instead of using a proxy workaround.

Audit Notes

The current dialog scan found these app-owned surfaces and moved them onto the shared primitive:

AppDetailsModal in App Store details.
ConfirmDeployDialog in App Store deploy handoff.
AppRegistrationDialog in Deploy.
AlmaSettingsDialog in the shell sidecar.

Shell-level dialogs in apps/os-shell/src/shell/dialogs/ShellDialogs.tsx are already rendered by the shell overlay layer. They may later adopt WindowDialog, but they are not trapped inside an app window today.

Storybook

Reusable form controls that appear inside dialogs should be documented in UI Workshop. SelectControl has Storybook coverage for normal dropdowns, compact composer placement, top-opening menus, and right-aligned menus.