mirror of
https://github.com/marcoallegretti/WEFT_OS.git
synced 2026-03-27 09:23:09 +00:00
197 lines
5.1 KiB
Markdown
197 lines
5.1 KiB
Markdown
# 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
|