WEFT_OS/docs/architecture/weft-shell-protocol.md

WEFT Shell Protocol Design

This document defines the WEFT-specific protocol boundary between weft-compositor and servo-shell.

Status

Defined for WEFT repository planning and future implementation.

Not implemented.

Not proposed as a standard Wayland extension.

Participants

• weft-compositor
• servo-shell

weft-compositor is authoritative for:

• Wayland connection ownership
• surface lifecycle
• input focus at the surface level
• surface stacking between independent client surfaces
• output geometry and presentation timing

servo-shell is authoritative for:

• shell DOM structure
• shell chrome layout
• window metadata presentation inside the shell UI
• shell requests to create, move, resize, and destroy shell-managed windows

Problem boundary

The shell needs to represent desktop windows as DOM elements while the compositor owns the actual client surfaces.

The protocol exists to let the shell request and manage compositor-backed window surfaces without pretending that app content lives inside Servo's DOM tree.

Object model

The protocol defines a shell session and a set of shell-managed window objects.

Shell session

A shell session is created when servo-shell binds the WEFT global.

The session has exactly one active owner.

If the shell disconnects, the compositor invalidates the session and destroys all shell-owned protocol objects.

Shell window object

A shell window object represents a compositor-managed surface slot associated with one visual shell window.

Each shell window object has:

• window_id
• app_id
• title
• role
• geometry
• state
• z_hint

window_id is generated by the compositor and is stable only for the lifetime of the session.

Core requests

create_window

Sent by servo-shell to request creation of a shell-managed window slot.

Inputs:

• app_id
• title
• role
• initial geometry
• initial state

Result:

• success with assigned window_id
• failure with a reason code

The compositor creates the server-side object and returns a window_id.

update_window_metadata

Sent by servo-shell when title, role, or state hints change.

Metadata updates are advisory except where explicitly marked authoritative in this document.

set_window_geometry

Sent by servo-shell to request a geometry change.

The compositor validates the request against output bounds, policy, and current window state.

The compositor is not required to honor the requested geometry exactly.

destroy_window

Sent by servo-shell when the shell no longer wants the window slot.

The compositor destroys the protocol object and any shell-owned chrome surfaces associated with it.

Core compositor events

window_configured

Sent by the compositor when the effective geometry or state changes.

servo-shell must treat this as authoritative and update its DOM layout to match.

focus_changed

Sent by the compositor when surface-level focus changes.

The shell updates visual focus state but does not override compositor focus directly.

window_closed

Sent by the compositor when a window object is no longer valid.

After this event, the window_id is dead and cannot be reused by the shell.

presentation_feedback

Sent by the compositor to report frame presentation timing relevant to shell-managed surfaces.

This event exists to align shell animations and resize flows with compositor timing.

Surface ownership rules

The compositor owns the actual application content surfaces.

The shell may own separate chrome surfaces where needed.

The shell does not embed application pixels into the Servo DOM.

The compositor remains the authority for final stacking and composition.

Failure model

Shell crash

If servo-shell disconnects:

• the compositor invalidates the shell session
• shell-owned protocol objects are destroyed
• application surfaces remain alive if supervised elsewhere
• a restarted shell receives a new session and must rebuild its model

Compositor crash

If weft-compositor crashes:

• Wayland connections are lost
• the shell must reconnect after compositor restart
• all protocol object identifiers from the prior session are invalid
• the shell rebuilds state from the authoritative process manager once the compositor is ready

Stale identifiers

A window_id is session-scoped.

A stale window_id must be rejected by the compositor.

Security model

The shell can request metadata and geometry changes, but the compositor enforces:

• output bounds
• focus routing
• stacking policy
• lifecycle validity

The shell is not trusted to define final compositor state.

Test requirements

Implementation work against this protocol must include:

• unit tests for object lifecycle and stale identifier rejection
• integration tests for shell reconnect behavior
• integration tests for compositor restart handling
• validation of focus and configure event ordering

Deferred topics

This document does not define:

• client application protocol toward weft-appd
• package or launcher metadata schemas
• accessibility mappings
• persistence of shell layout state across sessions