Module floating_surface 

Shared placement contract for app-bound overlays and shell-owned PiP.

Apps describe what should float; this module owns how it moves. The same state machine is used while a surface is attached to its app and after the shell adopts it as desktop PiP, avoiding a second set of drag/snap rules.

Structs

FloatingPlacement

Placement + drag state shared by call, navigation, browser PiP and arbitrary captured regions.

FloatingSurfacePresentation

App-owned presentation currently living in desktop coordinates. The UI runtime uses this one read-only description both to render the secondary window and to stream placement changes to the compositor.

FloatingSurfaceProtocolRequest

FloatingSurfaceRequest

FloatingSurfaceServiceClient

Non-blocking app-side connection to the session shell. The launcher hands the already-connected socket into the sandbox as TILO_SVC_SHELL-UI_FD; newline-delimited JSON keeps the tiny lifecycle protocol inspectable and lets the compositor service evolve independently of app/widget releases.

HostNetworkStatus

Sanitized host network hints. Unknown is distinct from known unmetered; this carries no connection name, device, address or network permission.

Enums

Attachment

Where the floating surface currently belongs.

CaptureStudioProtocolMode

Starting mode for an app-requested session-shell chooser. The request only opens trusted shell UI; it never grants an app capture permission or pixels.

DeviceShellOperation

Owner-only operations on Terminal’s existing device-shell PTY. Every input/read operation is bound to the exact currently open local session.

FloatingRole

Presentation hints understood by both app and shell hosts.

FloatingSource

Stable identity of content that can survive an app → desktop hand-off.

FloatingSurfaceClientMessage

App → shell lifecycle. Suspend is the reversible half of an attached ↔ desktop handoff: the authenticated native surface and its renderer stay warm while its pixels return to the app. Dismiss is deliberately permanent and reserved for hang-up, navigation-end, or an explicit close.

FloatingSurfaceHostMessage

Shell → app lifecycle. The shell supplies one authoritative combined desktop coordinate space and explicitly acknowledges ownership changes; transports must not infer either from timing.

FloatingSurfaceProtocolRole

Roles are additive wire values: an older peer refuses an unknown role; it must never reinterpret interactive content as a capture mirror. Adding a role preserves the existing framing, geometry, and legacy role values.

FloatingSurfaceProtocolSource

Handoff

Result of updating a drag. Hosts use the edge to animate the hand-off.

Material

What a floating surface’s body is made of. A surface names its material; the toolkit and compositor decide how it renders — the blur radius, the tint and the opaque fallback are never the caller’s (docs/design-language.md, “Material and transparency”).

Constants

FLOATING_SURFACE_APP_ID_PREFIX

FLOATING_SURFACE_PROTOCOL_VERSION

Version of the app ↔ shell wire contract on the shell-ui channel: floating-surface lifecycle and the window’s appearance. Geometry is encoded as plain logical-pixel arrays rather than renderer types so sandbox services, Wayland protocol shims, and test transports can all carry the same messages.

FLOATING_SURFACE_SERVICE

Functions

app_owned_content_window_rect

The native allocation around retained interactive content, including the shared floating silhouette, its rim and the themed elevation. Content geometry stays unchanged: the extra pixels are a transparent frame gutter, not padding inserted into the app’s layout or input coordinates.

paint_app_owned_content

Paint the framework-owned frame around one interactive app-owned surface.

paint_material

Paint a floating surface’s body: shape filled with material. Edges, shadows and content are drawn by the caller on top, exactly as on an opaque surface.

protocol_input_rect

Validate optional interactive geometry without enlarging the native window.

protocol_rect

Convert protocol coordinates into a validated rectangle.

protocol_rect_array

translate_input_rect

Move a declared interactive region with its host geometry.