Floating Surface Runtime

Floating Surface is the shell runtime for persistent mini utility controls.

Current Implementation

The first registered surface is the Music mini player. When a Music window is minimized, the shell derives a FloatingSurfaceItem from the minimized window and renders it through FloatingSurfaceLayer.

Key files:

• apps/os-shell/src/shell/floating-surfaces/types.ts
• apps/os-shell/src/shell/floating-surfaces/FloatingSurfaceLayer.tsx
• apps/os-shell/src/shell/desktop/DesktopOverlayLayer.tsx

Model

The runtime models:

• FloatingSurfacePosition: top, bottom, left, or right.
• FloatingSurfaceItem: app id, title, subtitle, icon, kind, position, and actions.
• FloatingSurfaceAction: label, icon hint, variant, and action id.

The current adapter derives items from shell window state. A future app contract can allow cooperative apps to register richer mini controls without importing shell internals.

Settings

Display Options exposes "Floating surface" with top, bottom, left, and right positions. The current setting affects the Music mini player and is stored locally.

Boundary

Floating Surface is for persistent mini utility controls. It is different from Slidepad, which is a corner-summoned quick app panel, and from Switchbar, which is a transient open-with chooser.