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.

HistoryChangeDescription

One change described: its id, the sentence, and which provider and model wrote it.

HistoryChangeFacts

What a model may know about one change it is asked to describe: the change’s id as History lists it (32 lowercase hex characters), its own summary, the action and resource it named, and what it wrote. Never who made it: History shows that beside the description.

HostNetworkStatus

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

PointedControl

One control of an app’s window as the shell names it when a person points at it: its semantic id, its role and its accessible name. What a field holds is never part of it.

Recipient

One recipient of a message sent from a window: who it goes to, and what the person reads on its chip.

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”).

RecipientKind

What a recipient of a sent message is: someone the search found, or the agent the person is making by sending.

Constants

FLOATING_SURFACE_APP_ID_PREFIX

FLOATING_SURFACE_PROTOCOL_VERSION

The app ↔ shell interface’s one version: everything an app and the session shell say on the shell-ui connection (floating-surface lifecycle, the window’s appearance, tabs, selection). The app’s first frame is FloatingSurfaceClientMessage::Hello with this number; a shell at another number answers FloatingSurfaceHostMessage::VersionMismatch and closes, and updates whichever side is behind (docs/architecture/compatibility.md). There is no negotiation and nothing kept for an older number. interface.toml beside this crate holds the schema, and the repository policy fails a change to it that keeps the number.

FLOATING_SURFACE_SERVICE

Functions

app_owned_content_window_rect

The native allocation around retained interactive content, including the floating card’s frame, its edge 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 (an app’s call or navigation card).

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

snap_to_edges

rect moved onto an edge of bounds it stands within 32 px of, gap in from it: the settle every floating thing uses, cards and windows alike.

translate_input_rect

Move a declared interactive region with its host geometry.