docs: install canonical Ferese specifications
This commit is contained in:
Samuel Onoja committed
1 parent
e963b82a9e
commit
e1f1c1b9b6
4 files changed
+1584
-138
No files matched your search
@@ -0,0 +1,454 @@
|
||||
# Ferese Shell Design Specification
|
||||
|
||||
Status: Draft for implementation
|
||||
Target: Ferese desktop tier
|
||||
Normative owner: shell behavior and interaction
|
||||
|
||||
Companion documents:
|
||||
- `ferese-window-manager-spec.md` — compositor mechanism and policy
|
||||
- `ferese-theme-ui-spec.md` — visual tokens and exact component geometry
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
`ferese-shell` provides the integrated desktop interface around Ferese-managed
|
||||
windows.
|
||||
|
||||
The initial shell consists of:
|
||||
|
||||
- one floating top bar per output;
|
||||
- an apps-only launcher;
|
||||
- overview controls;
|
||||
- top-bar popovers and a compact control center;
|
||||
- notifications and notification history; and
|
||||
- volume/brightness OSD.
|
||||
|
||||
Ferese deliberately provides no persistent dock or bottom application bar.
|
||||
|
||||
The shell MUST remain optional. If it crashes, managed windows, layout trees,
|
||||
workspaces, focus topology, and client sessions remain valid.
|
||||
|
||||
## 2. Document boundaries
|
||||
|
||||
This document owns:
|
||||
|
||||
```text
|
||||
shell visibility
|
||||
layer-shell roles
|
||||
exclusive-zone behavior
|
||||
focus acquisition/restoration
|
||||
launcher behavior
|
||||
top-bar actions
|
||||
notification/DND behavior
|
||||
modal interaction
|
||||
fullscreen shell behavior
|
||||
shell restart behavior
|
||||
```
|
||||
|
||||
It MUST NOT define raw colors, pixel heights, radii, blur amounts, icon sizes,
|
||||
font sizes, or shadows. Those belong to `ferese-theme-ui-spec.md`.
|
||||
|
||||
## 3. Surface architecture
|
||||
|
||||
The shell uses public layer-shell for normal shell surfaces.
|
||||
|
||||
```text
|
||||
background(output) background layer, optional
|
||||
top_bar(output) top layer, exclusive zone
|
||||
launcher(output) overlay layer, exclusive_zone = 0
|
||||
notification_stack(output) overlay layer, exclusive_zone = 0
|
||||
osd(output) overlay layer, exclusive_zone = 0
|
||||
popover(output) overlay/top, exclusive_zone = 0
|
||||
modal(output) overlay layer, exclusive_zone = 0
|
||||
```
|
||||
|
||||
`ferese-shell-v1` is a private control protocol only. It MUST NOT duplicate
|
||||
layer-shell geometry or roles.
|
||||
|
||||
Its initial responsibilities are:
|
||||
|
||||
```text
|
||||
window list and lifecycle
|
||||
application identity metadata
|
||||
focused / urgent state
|
||||
activate managed window
|
||||
request close
|
||||
enter / exit overview
|
||||
select overview window / workspace
|
||||
```
|
||||
|
||||
## 4. Top bar
|
||||
|
||||
A top bar exists on every active output unless disabled.
|
||||
|
||||
Its conceptual regions are:
|
||||
|
||||
```text
|
||||
LEFT
|
||||
Ferese mark
|
||||
workspace switcher
|
||||
focused application
|
||||
|
||||
CENTER
|
||||
clock / date
|
||||
|
||||
RIGHT
|
||||
notifications
|
||||
sound
|
||||
power
|
||||
control-center entry
|
||||
```
|
||||
|
||||
The top bar is the only persistent shell surface that reserves workspace space.
|
||||
|
||||
Workspace controls MUST use compositor workspace truth and ordinary Ferese
|
||||
workspace policy.
|
||||
|
||||
The top bar SHOULD remain non-keyboard-interactive during ordinary use.
|
||||
|
||||
## 5. Fullscreen behavior
|
||||
|
||||
Entering fullscreen hides the top bar visually.
|
||||
|
||||
The underlying tiled workspace layout region MUST remain unchanged while
|
||||
fullscreen is active.
|
||||
|
||||
A temporary top-bar reveal over fullscreen:
|
||||
|
||||
```text
|
||||
uses overlay presentation
|
||||
uses exclusive_zone = 0
|
||||
does not resize the fullscreen client
|
||||
does not mutate the underlying workspace layout
|
||||
```
|
||||
|
||||
Leaving fullscreen restores the ordinary top-bar presentation without
|
||||
reconfiguring hidden tiled windows merely because the bar reappears.
|
||||
|
||||
## 6. Shell reservation lease
|
||||
|
||||
If `ferese-shell` disconnects unexpectedly, Ferese SHOULD retain the most recent
|
||||
valid Ferese-owned top-bar reservation for a short bounded grace period.
|
||||
|
||||
If the shell reconnects before expiry with a compatible reservation, tiled
|
||||
windows MUST NOT reflow.
|
||||
|
||||
If the grace period expires, Ferese removes the reservation and performs at most
|
||||
one ordinary layout reflow.
|
||||
|
||||
Default:
|
||||
|
||||
```text
|
||||
reservation_grace_ms = 2000
|
||||
```
|
||||
|
||||
## 7. Launcher
|
||||
|
||||
The initial launcher is apps-only.
|
||||
|
||||
Default invocation:
|
||||
|
||||
```text
|
||||
Super + Space
|
||||
```
|
||||
|
||||
The launcher MAY also be opened by a Ferese control in the top bar.
|
||||
|
||||
The launcher:
|
||||
|
||||
- receives keyboard focus immediately;
|
||||
- discovers XDG desktop applications;
|
||||
- searches by application name and normalized desktop identity;
|
||||
- supports pointer and keyboard navigation;
|
||||
- launches selected applications with XDG activation;
|
||||
- dismisses on Escape; and
|
||||
- restores the previous valid managed-window focus on dismissal.
|
||||
|
||||
Initial placeholder:
|
||||
|
||||
```text
|
||||
Search apps…
|
||||
```
|
||||
|
||||
The launcher MUST NOT expose dead tabs for files, settings, commands, or recents.
|
||||
|
||||
Future search providers MAY extend it without changing the base interaction
|
||||
model.
|
||||
|
||||
## 8. Application identity and launch state
|
||||
|
||||
The launcher consumes the compositor's normalized application identity and launch
|
||||
association model.
|
||||
|
||||
It MUST NOT assume strings such as:
|
||||
|
||||
```text
|
||||
firefox
|
||||
org.mozilla.firefox
|
||||
Mozilla Firefox
|
||||
```
|
||||
|
||||
are the same application unless desktop-entry or activation metadata establishes
|
||||
that relationship.
|
||||
|
||||
Ferese does not maintain a persistent running-application strip.
|
||||
|
||||
## 9. Top-bar popovers
|
||||
|
||||
A top-bar control may own one anchored popover.
|
||||
|
||||
Only one primary top-bar popover SHOULD be open per output at a time.
|
||||
|
||||
Initial popovers MAY include:
|
||||
|
||||
```text
|
||||
calendar / time
|
||||
sound
|
||||
battery / power status
|
||||
notifications
|
||||
control center
|
||||
```
|
||||
|
||||
Network and Bluetooth configuration are not part of the initial desktop tier and
|
||||
MUST NOT appear as required or placeholder rows.
|
||||
|
||||
Opening another primary popover closes the previous one on that output.
|
||||
|
||||
## 10. Control center
|
||||
|
||||
The initial control center MAY expose only services backed by real providers:
|
||||
|
||||
```text
|
||||
sound
|
||||
battery / power status
|
||||
Do Not Disturb
|
||||
notification state
|
||||
Ferese Settings
|
||||
```
|
||||
|
||||
Unavailable capabilities are omitted.
|
||||
|
||||
## 11. Do Not Disturb
|
||||
|
||||
When DND is off:
|
||||
|
||||
```text
|
||||
eligible notifications may create transient toasts
|
||||
notifications enter history according to normal policy
|
||||
```
|
||||
|
||||
When DND is on:
|
||||
|
||||
```text
|
||||
normal transient toasts are suppressed
|
||||
notifications still enter history
|
||||
unread state still updates
|
||||
```
|
||||
|
||||
A future explicitly defined critical-urgency policy MAY bypass DND.
|
||||
|
||||
No application-name heuristic may bypass DND.
|
||||
|
||||
DND state persists across shell restart.
|
||||
|
||||
## 12. Notifications
|
||||
|
||||
`ferese-shell` implements `org.freedesktop.Notifications`.
|
||||
|
||||
Initial support:
|
||||
|
||||
```text
|
||||
summary
|
||||
body
|
||||
icon metadata
|
||||
expiry
|
||||
replacement
|
||||
close
|
||||
actions
|
||||
urgency metadata
|
||||
```
|
||||
|
||||
Notification content is untrusted.
|
||||
|
||||
Transient toasts:
|
||||
|
||||
- do not reserve workspace space;
|
||||
- appear beneath the top bar;
|
||||
- obey DND;
|
||||
- do not take keyboard focus by default.
|
||||
|
||||
## 13. Notification center
|
||||
|
||||
Notification history opens from the top bar.
|
||||
|
||||
The initial implementation SHOULD use a large anchored popover rather than a
|
||||
permanent side drawer.
|
||||
|
||||
The center may take shell keyboard focus while interactive and MUST restore the
|
||||
previous managed-window focus when dismissed.
|
||||
|
||||
## 14. OSD
|
||||
|
||||
OSD handles transient state such as:
|
||||
|
||||
```text
|
||||
volume
|
||||
brightness
|
||||
microphone mute
|
||||
keyboard backlight
|
||||
```
|
||||
|
||||
OSD surfaces:
|
||||
|
||||
```text
|
||||
use overlay layer
|
||||
use exclusive_zone = 0
|
||||
never take keyboard focus
|
||||
dismiss automatically
|
||||
```
|
||||
|
||||
## 15. Overview
|
||||
|
||||
`Super+Tab` enters overview.
|
||||
|
||||
Managed-window previews remain compositor-owned live scene nodes.
|
||||
|
||||
The shell provides:
|
||||
|
||||
```text
|
||||
selection affordances
|
||||
application/window labels
|
||||
workspace controls
|
||||
optional later search UI
|
||||
```
|
||||
|
||||
The shell MUST NOT implement overview by continuously copying each managed
|
||||
window into the shell process.
|
||||
|
||||
Window activation and close actions use `ferese-shell-v1`.
|
||||
|
||||
## 16. Modal interaction
|
||||
|
||||
Shell modals are reserved for:
|
||||
|
||||
```text
|
||||
destructive confirmation
|
||||
security-sensitive confirmation
|
||||
irreversible shell action
|
||||
```
|
||||
|
||||
Ordinary settings MUST NOT use shell modals.
|
||||
|
||||
When a shell modal opens:
|
||||
|
||||
```text
|
||||
SeatState.keyboard_focus -> FocusTarget::Shell(modal)
|
||||
```
|
||||
|
||||
The compositor presents the modal above a scrim.
|
||||
|
||||
Input outside the modal is consumed by the scrim and MUST NOT reach managed
|
||||
applications.
|
||||
|
||||
On dismissal, the previous valid managed-window focus is restored.
|
||||
|
||||
Ferese does not ship a polkit authentication agent in the initial desktop tier.
|
||||
|
||||
## 17. Shell restart
|
||||
|
||||
On restart:
|
||||
|
||||
```text
|
||||
managed windows remain unchanged
|
||||
workspace assignments remain unchanged
|
||||
layout trees remain unchanged
|
||||
managed-window focus remains valid where possible
|
||||
```
|
||||
|
||||
The restarted shell reconstructs:
|
||||
|
||||
```text
|
||||
top bars
|
||||
workspace indicators
|
||||
focused-app metadata
|
||||
notification service/state
|
||||
DND state
|
||||
```
|
||||
|
||||
from compositor truth and persistent shell state.
|
||||
|
||||
## 18. Shell configuration
|
||||
|
||||
Representative behavior-only configuration:
|
||||
|
||||
```toml
|
||||
[shell]
|
||||
enabled = true
|
||||
reservation_grace_ms = 2000
|
||||
|
||||
[shell.top_bar]
|
||||
enabled = true
|
||||
hide_in_fullscreen = true
|
||||
show_workspaces = true
|
||||
show_focused_app = true
|
||||
show_clock = true
|
||||
|
||||
[shell.launcher]
|
||||
enabled = true
|
||||
binding = "Super+Space"
|
||||
|
||||
[shell.overview]
|
||||
enabled = true
|
||||
binding = "Super+Tab"
|
||||
|
||||
[shell.notifications]
|
||||
enabled = true
|
||||
do_not_disturb = false
|
||||
```
|
||||
|
||||
Visual measurements do not belong here.
|
||||
|
||||
## 19. First shell implementation slice
|
||||
|
||||
```text
|
||||
top bar
|
||||
launcher
|
||||
one top-bar popover
|
||||
OSD
|
||||
```
|
||||
|
||||
Demo:
|
||||
|
||||
```text
|
||||
1. Start Ferese.
|
||||
2. Top bar appears.
|
||||
3. Workspace and focused-app state are correct.
|
||||
4. Press Super+Space.
|
||||
5. Launcher opens and receives focus.
|
||||
6. Search for Foot and launch it.
|
||||
7. Foot enters the current workspace through normal tiling policy.
|
||||
8. Open Sound from the top bar.
|
||||
9. Sound popover anchors to its invoking control.
|
||||
10. Enter fullscreen.
|
||||
11. Top bar hides without changing the underlying tiled layout region.
|
||||
12. Reveal top bar temporarily as an overlay.
|
||||
13. Exit fullscreen.
|
||||
14. Top bar returns to normal reserved presentation.
|
||||
15. Restart ferese-shell.
|
||||
16. Tiled windows do not reflow during the reservation grace period.
|
||||
```
|
||||
|
||||
## 20. Completion criteria
|
||||
|
||||
The initial shell is complete when:
|
||||
|
||||
1. every active output has a functional top bar;
|
||||
2. launcher search and application launching work;
|
||||
3. workspace indicators reflect compositor truth;
|
||||
4. focused application state is accurate;
|
||||
5. top-bar popovers anchor correctly;
|
||||
6. notifications and DND work;
|
||||
7. OSD works without taking focus;
|
||||
8. overview uses compositor-owned live windows;
|
||||
9. fullscreen hide/reveal does not alter underlying layout geometry;
|
||||
10. shell restart does not disturb managed windows; and
|
||||
11. all visual presentation is supplied through the theme/UI token system.
|
||||
Reference in new issue
Block a user