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
@@ -2,7 +2,8 @@
|
||||
|
||||
Ferese is an experimental Wayland tiling compositor written in Rust with
|
||||
Smithay. The nested compositor is complete and development currently targets
|
||||
the M1 native protocol and interaction milestone in [spec.md](spec.md).
|
||||
the M2 tiling and workspaces milestone in the
|
||||
[window-manager specification](docs/ferese-window-manager-spec.md).
|
||||
|
||||
## Development
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -0,0 +1,807 @@
|
||||
# Ferese Theme and UI Specification
|
||||
|
||||
Status: Draft for implementation
|
||||
Target: Ferese desktop tier
|
||||
Normative owner: visual tokens and component geometry
|
||||
|
||||
Companion documents:
|
||||
- `ferese-window-manager-spec.md` — compositor mechanism and policy
|
||||
- `ferese-shell-design.md` — shell behavior and interaction
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the Ferese visual language.
|
||||
|
||||
It owns:
|
||||
|
||||
- desktop background treatment;
|
||||
- color tokens;
|
||||
- semantic surface tokens;
|
||||
- typography;
|
||||
- iconography;
|
||||
- spacing;
|
||||
- exact top-bar geometry;
|
||||
- launcher geometry;
|
||||
- popover/menu/modal geometry;
|
||||
- notification geometry;
|
||||
- OSD geometry;
|
||||
- settings UI primitives;
|
||||
- motion tokens; and
|
||||
- glass, translucent, and solid visual profiles.
|
||||
|
||||
It does not define shell focus, fullscreen behavior, workspace policy, launcher
|
||||
behavior, notification policy, or compositor security.
|
||||
|
||||
Ferese intentionally has no persistent dock or bottom application bar.
|
||||
|
||||
## 2. Design language
|
||||
|
||||
Ferese UI should feel:
|
||||
|
||||
```text
|
||||
quiet
|
||||
precise
|
||||
soft
|
||||
material
|
||||
low-latency
|
||||
high-contrast
|
||||
spatially consistent
|
||||
```
|
||||
|
||||
The shell MUST avoid:
|
||||
|
||||
- excessive glow;
|
||||
- RGB/gamer styling;
|
||||
- ornamental gradients;
|
||||
- gratuitous transparency;
|
||||
- oversized shadows;
|
||||
- arbitrary component styling;
|
||||
- large chrome that steals workspace area; and
|
||||
- pixel-for-pixel imitation of another operating system.
|
||||
|
||||
Ferese must still look complete with blur disabled.
|
||||
|
||||
## 3. Theme model
|
||||
|
||||
Components request semantic surface roles:
|
||||
|
||||
```text
|
||||
surface.panel
|
||||
surface.panel_elevated
|
||||
surface.popover
|
||||
surface.menu
|
||||
surface.notification
|
||||
surface.hud
|
||||
surface.modal
|
||||
```
|
||||
|
||||
The active profile maps each role to material parameters.
|
||||
|
||||
Themes change appearance, not component structure or behavior.
|
||||
|
||||
## 4. Material styles
|
||||
|
||||
```rust
|
||||
pub enum MaterialStyle {
|
||||
Glass,
|
||||
Translucent,
|
||||
Solid,
|
||||
}
|
||||
```
|
||||
|
||||
### Glass
|
||||
|
||||
Backdrop blur plus restrained tint, saturation, brightness, and optional noise.
|
||||
|
||||
### Translucent
|
||||
|
||||
Alpha-composited semantic tint with no backdrop blur.
|
||||
|
||||
### Solid
|
||||
|
||||
Opaque semantic surface with identical geometry.
|
||||
|
||||
Changing material style MUST NOT move, resize, or restructure shell components.
|
||||
|
||||
## 5. Built-in profiles
|
||||
|
||||
```text
|
||||
ferese-glass
|
||||
ferese-translucent
|
||||
ferese-solid
|
||||
```
|
||||
|
||||
All share:
|
||||
|
||||
```text
|
||||
component geometry
|
||||
spacing
|
||||
typography
|
||||
icon metrics
|
||||
interaction states
|
||||
motion semantics
|
||||
```
|
||||
|
||||
## 6. Background
|
||||
|
||||
Supported:
|
||||
|
||||
```text
|
||||
solid color
|
||||
image fill
|
||||
image fit
|
||||
```
|
||||
|
||||
Ferese SHOULD NOT globally blur the wallpaper.
|
||||
|
||||
Optional restrained adjustments MAY include:
|
||||
|
||||
```text
|
||||
brightness
|
||||
dimming
|
||||
saturation
|
||||
```
|
||||
|
||||
Default fallback:
|
||||
|
||||
```text
|
||||
#0B0F14
|
||||
```
|
||||
|
||||
## 7. Color tokens
|
||||
|
||||
Representative dark profile:
|
||||
|
||||
```toml
|
||||
[theme.colors]
|
||||
desktop_background = "#0B0F14"
|
||||
|
||||
surface_base = "#111821"
|
||||
surface_raised = "#18212C"
|
||||
surface_elevated = "#202B37"
|
||||
|
||||
text_primary = "#F4F7FB"
|
||||
text_secondary = "#B7C0CB"
|
||||
text_muted = "#7F8A98"
|
||||
text_disabled = "#58616D"
|
||||
|
||||
accent = "#5B8CFF"
|
||||
accent_soft = "#8EAFFF"
|
||||
accent_text = "#FFFFFF"
|
||||
|
||||
success = "#4CC38A"
|
||||
warning = "#F0B45B"
|
||||
danger = "#F06A6A"
|
||||
|
||||
border = "#FFFFFF18"
|
||||
border_strong = "#FFFFFF2A"
|
||||
|
||||
shadow = "#00000055"
|
||||
scrim = "#05070AB8"
|
||||
```
|
||||
|
||||
## 8. Surface tokens
|
||||
|
||||
Representative glass profile:
|
||||
|
||||
```toml
|
||||
[theme.surface.panel]
|
||||
style = "glass"
|
||||
opacity = 0.78
|
||||
blur = 24.0
|
||||
saturation = 1.08
|
||||
brightness = 1.02
|
||||
noise = 0.012
|
||||
border_opacity = 0.10
|
||||
shadow = "soft"
|
||||
|
||||
[theme.surface.panel_elevated]
|
||||
style = "glass"
|
||||
opacity = 0.84
|
||||
blur = 28.0
|
||||
saturation = 1.10
|
||||
brightness = 1.03
|
||||
noise = 0.014
|
||||
border_opacity = 0.12
|
||||
shadow = "elevated"
|
||||
|
||||
[theme.surface.popover]
|
||||
style = "glass"
|
||||
opacity = 0.84
|
||||
blur = 28.0
|
||||
saturation = 1.10
|
||||
brightness = 1.03
|
||||
noise = 0.014
|
||||
border_opacity = 0.12
|
||||
shadow = "elevated"
|
||||
|
||||
[theme.surface.hud]
|
||||
style = "glass"
|
||||
opacity = 0.88
|
||||
blur = 30.0
|
||||
saturation = 1.06
|
||||
brightness = 1.04
|
||||
noise = 0.010
|
||||
border_opacity = 0.12
|
||||
shadow = "elevated"
|
||||
```
|
||||
|
||||
## 9. Geometry tokens
|
||||
|
||||
```toml
|
||||
[theme.geometry]
|
||||
base_unit = 8.0
|
||||
|
||||
window_radius = 14.0
|
||||
|
||||
top_bar_height = 32.0
|
||||
top_bar_margin_top = 8.0
|
||||
top_bar_margin_horizontal = 10.0
|
||||
top_bar_radius = 16.0
|
||||
|
||||
launcher_width = 560.0
|
||||
launcher_radius = 20.0
|
||||
|
||||
popover_radius = 16.0
|
||||
menu_radius = 14.0
|
||||
modal_radius = 18.0
|
||||
hud_radius = 18.0
|
||||
|
||||
panel_padding = 12.0
|
||||
control_gap = 8.0
|
||||
section_gap = 16.0
|
||||
```
|
||||
|
||||
Only the top bar consumes persistent shell space.
|
||||
|
||||
## 10. Typography
|
||||
|
||||
Initial roles:
|
||||
|
||||
```text
|
||||
caption 11-12 px
|
||||
body 13-14 px
|
||||
body-strong 13-14 px medium
|
||||
label 12-13 px medium
|
||||
title 16-18 px semibold
|
||||
display 22-28 px semibold
|
||||
```
|
||||
|
||||
Use the system UI sans-serif by default.
|
||||
|
||||
Clocks and changing numeric values SHOULD use tabular numerals where available.
|
||||
|
||||
## 11. Iconography
|
||||
|
||||
System icons are monochrome vectors.
|
||||
|
||||
```text
|
||||
visual box 16-20 px
|
||||
stroke approximately 1.5-2 px
|
||||
style simple and optically balanced
|
||||
```
|
||||
|
||||
Application icons retain original artwork.
|
||||
|
||||
System icons MUST NOT use arbitrary gradients.
|
||||
|
||||
## 12. Top bar
|
||||
|
||||
Default composition:
|
||||
|
||||
```text
|
||||
╭──────────────────────────────────────────────────────────────╮
|
||||
│ F 1 2 3 4 Zed 09:41 🔊 ◉ │
|
||||
╰──────────────────────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
Surface role:
|
||||
|
||||
```text
|
||||
surface.panel
|
||||
```
|
||||
|
||||
### Workspace state
|
||||
|
||||
Inactive workspaces use muted text.
|
||||
|
||||
Active workspace uses a compact filled or accent-backed indicator.
|
||||
|
||||
### Focused application
|
||||
|
||||
May display:
|
||||
|
||||
```text
|
||||
application icon
|
||||
application name
|
||||
```
|
||||
|
||||
Full changing window titles are not part of the default bar.
|
||||
|
||||
### Clock
|
||||
|
||||
Compact:
|
||||
|
||||
```text
|
||||
09:41
|
||||
```
|
||||
|
||||
Optional wide:
|
||||
|
||||
```text
|
||||
Mon, Sep 23 09:41
|
||||
```
|
||||
|
||||
## 13. Launcher
|
||||
|
||||
The launcher is the primary application-selection surface.
|
||||
|
||||
Default placement:
|
||||
|
||||
```text
|
||||
centered horizontally
|
||||
upper-middle or center of usable workspace
|
||||
```
|
||||
|
||||
Surface role:
|
||||
|
||||
```text
|
||||
surface.panel_elevated
|
||||
```
|
||||
|
||||
Default geometry:
|
||||
|
||||
```text
|
||||
width theme.geometry.launcher_width
|
||||
max height 70% of usable output
|
||||
radius theme.geometry.launcher_radius
|
||||
```
|
||||
|
||||
Initial content:
|
||||
|
||||
```text
|
||||
╭──────────────────────────────────────╮
|
||||
│ Search apps… │
|
||||
├──────────────────────────────────────┤
|
||||
│ │
|
||||
│ Zed Firefox Foot │
|
||||
│ Files Settings Music │
|
||||
│ │
|
||||
╰──────────────────────────────────────╯
|
||||
```
|
||||
|
||||
Initial implementation is apps-only.
|
||||
|
||||
## 14. Launcher search field
|
||||
|
||||
```text
|
||||
height 44-48 px
|
||||
radius 12 px
|
||||
```
|
||||
|
||||
Placeholder:
|
||||
|
||||
```text
|
||||
Search apps…
|
||||
```
|
||||
|
||||
The search field is the visual focus.
|
||||
|
||||
## 15. Launcher application grid
|
||||
|
||||
Recommended:
|
||||
|
||||
```text
|
||||
4-6 columns depending on launcher width
|
||||
```
|
||||
|
||||
Entries show:
|
||||
|
||||
```text
|
||||
application icon
|
||||
one-line application name
|
||||
```
|
||||
|
||||
Long names truncate with ellipsis.
|
||||
|
||||
## 16. Top-bar popovers
|
||||
|
||||
Surface:
|
||||
|
||||
```text
|
||||
surface.popover
|
||||
```
|
||||
|
||||
Recommended:
|
||||
|
||||
```text
|
||||
width 280-360 px
|
||||
padding 12 px
|
||||
radius theme.geometry.popover_radius
|
||||
anchor gap 8 px
|
||||
```
|
||||
|
||||
They visually align with the invoking top-bar control.
|
||||
|
||||
## 17. Control center
|
||||
|
||||
Representative:
|
||||
|
||||
```text
|
||||
╭──────────────────────────────╮
|
||||
│ Sound │
|
||||
│ ━━━━━━━━━━━●━━━━━━ │
|
||||
│ │
|
||||
│ Battery 92% │
|
||||
│ Do Not Disturb Off │
|
||||
│ Notifications 3 │
|
||||
│ │
|
||||
│ Ferese Settings │
|
||||
╰──────────────────────────────╯
|
||||
```
|
||||
|
||||
Network/Bluetooth rows are not part of the initial visual contract.
|
||||
|
||||
## 18. Menus
|
||||
|
||||
Menus use:
|
||||
|
||||
```text
|
||||
surface.menu
|
||||
```
|
||||
|
||||
Row:
|
||||
|
||||
```text
|
||||
icon label shortcut
|
||||
```
|
||||
|
||||
Disabled items use `text_disabled`.
|
||||
|
||||
## 19. Modals
|
||||
|
||||
Modals use:
|
||||
|
||||
```text
|
||||
surface.modal
|
||||
```
|
||||
|
||||
Default width:
|
||||
|
||||
```text
|
||||
360-480 px
|
||||
```
|
||||
|
||||
Background scrim uses `theme.colors.scrim`.
|
||||
|
||||
Modal visuals do not imply a Ferese authentication agent.
|
||||
|
||||
## 20. Notifications
|
||||
|
||||
Toast surface:
|
||||
|
||||
```text
|
||||
surface.notification
|
||||
```
|
||||
|
||||
Recommended width:
|
||||
|
||||
```text
|
||||
320-360 px
|
||||
```
|
||||
|
||||
Structure:
|
||||
|
||||
```text
|
||||
icon
|
||||
summary
|
||||
body
|
||||
time
|
||||
optional actions
|
||||
```
|
||||
|
||||
Newest appears nearest the top bar.
|
||||
|
||||
## 21. OSD
|
||||
|
||||
Surface:
|
||||
|
||||
```text
|
||||
surface.hud
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
╭──────────────────────╮
|
||||
│ 🔊 ━━━━━━━●━━━━━ │
|
||||
╰──────────────────────╯
|
||||
```
|
||||
|
||||
Default placement is centered or lower-middle.
|
||||
|
||||
## 22. Overview chrome
|
||||
|
||||
Managed windows remain live compositor surfaces.
|
||||
|
||||
Theme/UI owns only:
|
||||
|
||||
```text
|
||||
selection ring
|
||||
labels
|
||||
workspace strip
|
||||
scrim
|
||||
overview control surfaces
|
||||
```
|
||||
|
||||
Selected preview uses an accent ring, not a large glow.
|
||||
|
||||
## 23. Interaction states
|
||||
|
||||
Controls support:
|
||||
|
||||
```text
|
||||
rest
|
||||
hover
|
||||
pressed
|
||||
focused
|
||||
selected
|
||||
disabled
|
||||
urgent where applicable
|
||||
```
|
||||
|
||||
Hover changes color/contrast only.
|
||||
|
||||
Pressed controls MAY use a tiny local scale response around `0.98`.
|
||||
|
||||
There is no dock-style magnification behavior.
|
||||
|
||||
## 24. Focus rings
|
||||
|
||||
Keyboard focus:
|
||||
|
||||
```text
|
||||
2 px accent ring
|
||||
2 px visual separation where needed
|
||||
```
|
||||
|
||||
Focus rings MUST NOT alter component geometry.
|
||||
|
||||
## 25. Shadows
|
||||
|
||||
Levels:
|
||||
|
||||
```text
|
||||
none
|
||||
soft
|
||||
elevated
|
||||
```
|
||||
|
||||
Representative:
|
||||
|
||||
```toml
|
||||
[theme.shadow.soft]
|
||||
offset_y = 4.0
|
||||
blur = 18.0
|
||||
opacity = 0.20
|
||||
|
||||
[theme.shadow.elevated]
|
||||
offset_y = 10.0
|
||||
blur = 36.0
|
||||
opacity = 0.28
|
||||
```
|
||||
|
||||
Top bar uses `soft`.
|
||||
|
||||
Launcher, popovers, notifications, modals, and HUDs typically use `elevated`.
|
||||
|
||||
## 26. Borders
|
||||
|
||||
Default:
|
||||
|
||||
```text
|
||||
1 logical px
|
||||
```
|
||||
|
||||
Glass uses subtle highlight borders.
|
||||
|
||||
Solid may use slightly stronger borders.
|
||||
|
||||
Borders MUST NOT resemble neon outlines.
|
||||
|
||||
## 27. Motion tokens
|
||||
|
||||
```text
|
||||
spatial spring
|
||||
bounded easing
|
||||
```
|
||||
|
||||
Approximate ranges:
|
||||
|
||||
```text
|
||||
micro feedback 80-120 ms
|
||||
popover/menu 140-200 ms
|
||||
launcher 180-240 ms
|
||||
notification 160-220 ms
|
||||
```
|
||||
|
||||
Managed-window and overview motion remains compositor spring-driven.
|
||||
|
||||
## 28. Reduced motion
|
||||
|
||||
Reduced motion:
|
||||
|
||||
```text
|
||||
removes decorative scale
|
||||
shortens/removes large shell translation
|
||||
uses opacity where spatial context is unnecessary
|
||||
does not animate blur intensity
|
||||
```
|
||||
|
||||
## 29. Fullscreen visual presentation
|
||||
|
||||
When fullscreen is active, the top bar is visually absent.
|
||||
|
||||
Temporary reveal uses the same visual tokens without implying any layout change.
|
||||
|
||||
## 30. Settings application
|
||||
|
||||
Ferese Settings consumes the same tokens.
|
||||
|
||||
Representative layout:
|
||||
|
||||
```text
|
||||
╭──────────────────────────────────────────────╮
|
||||
│ sidebar │ content │
|
||||
│ │ │
|
||||
│ General │ Appearance │
|
||||
│ Appearance │ │
|
||||
│ Tiling │ live preview │
|
||||
│ Workspaces │ controls │
|
||||
│ Shortcuts │ │
|
||||
│ Input │ │
|
||||
╰──────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
## 31. Appearance settings
|
||||
|
||||
Expose:
|
||||
|
||||
```text
|
||||
material style
|
||||
accent
|
||||
corner radius
|
||||
shadow intensity
|
||||
glass blur
|
||||
glass opacity
|
||||
animation speed
|
||||
reduced motion
|
||||
```
|
||||
|
||||
Material style:
|
||||
|
||||
```text
|
||||
Glass
|
||||
Translucent
|
||||
Solid
|
||||
```
|
||||
|
||||
Changing style MUST preserve geometry.
|
||||
|
||||
## 32. Theme configuration
|
||||
|
||||
```toml
|
||||
[theme]
|
||||
profile = "ferese-glass"
|
||||
mode = "dark"
|
||||
|
||||
[theme.colors]
|
||||
accent = "#5B8CFF"
|
||||
|
||||
[theme.material]
|
||||
style = "glass"
|
||||
|
||||
[theme.material.glass]
|
||||
blur = 24.0
|
||||
opacity = 0.80
|
||||
saturation = 1.08
|
||||
noise = 0.012
|
||||
|
||||
[theme.geometry]
|
||||
window_radius = 14.0
|
||||
top_bar_height = 32.0
|
||||
top_bar_radius = 16.0
|
||||
launcher_width = 560.0
|
||||
launcher_radius = 20.0
|
||||
|
||||
[theme.motion]
|
||||
speed = 1.0
|
||||
reduced_motion = false
|
||||
```
|
||||
|
||||
## 33. Validation
|
||||
|
||||
Reject:
|
||||
|
||||
```text
|
||||
non-finite dimensions
|
||||
negative radii
|
||||
negative blur
|
||||
opacity outside 0..1
|
||||
invalid colors
|
||||
unknown material style
|
||||
invalid font sizes
|
||||
invalid motion factors
|
||||
```
|
||||
|
||||
Theme changes use the same transactional Ferese configuration path.
|
||||
|
||||
## 34. Custom theme scope
|
||||
|
||||
Themes MAY change:
|
||||
|
||||
```text
|
||||
colors
|
||||
material parameters
|
||||
radii
|
||||
shadows
|
||||
typography
|
||||
accent
|
||||
icon tint
|
||||
motion scale
|
||||
validated component geometry tokens
|
||||
```
|
||||
|
||||
Themes MUST NOT change:
|
||||
|
||||
```text
|
||||
top-bar behavior
|
||||
launcher behavior
|
||||
focus behavior
|
||||
workspace behavior
|
||||
notification policy
|
||||
Wayland roles
|
||||
security behavior
|
||||
```
|
||||
|
||||
Ferese intentionally does not expose arbitrary CSS.
|
||||
|
||||
## 35. Performance degradation
|
||||
|
||||
Priority:
|
||||
|
||||
```text
|
||||
1. geometry correctness
|
||||
2. input latency
|
||||
3. text/icon clarity
|
||||
4. animation continuity
|
||||
5. shadow quality
|
||||
6. blur quality
|
||||
7. decorative effects
|
||||
```
|
||||
|
||||
Allowed degradation:
|
||||
|
||||
```text
|
||||
glass
|
||||
-> lower-resolution glass
|
||||
-> translucent
|
||||
-> solid
|
||||
```
|
||||
|
||||
Component geometry remains unchanged.
|
||||
|
||||
## 36. Visual acceptance criteria
|
||||
|
||||
Implementation succeeds when:
|
||||
|
||||
1. top bar, launcher, popovers, notifications, OSD, overview chrome, and Settings
|
||||
share one spacing/material/typography system;
|
||||
2. glass, translucent, and solid profiles preserve geometry;
|
||||
3. typography remains readable on bright and dark backgrounds;
|
||||
4. icons have consistent optical weight;
|
||||
5. launcher and popovers look anchored and intentional;
|
||||
6. focus/selection/urgent states remain distinct without relying on glow;
|
||||
7. disabling blur does not make the desktop look unfinished;
|
||||
8. reduced-motion mode remains coherent; and
|
||||
9. the desktop feels complete without a persistent dock or bottom application bar.
|
||||
@@ -9,7 +9,7 @@ Display protocol: Wayland
|
||||
|
||||
Ferese is a Wayland tiling compositor for a conventional, keyboard-friendly
|
||||
desktop. It combines predictable window management with compositor-owned rounded
|
||||
geometry, shadows, animation, transparency, and semantic glass materials.
|
||||
geometry, shadows, animation, transparency, and semantic surface materials.
|
||||
|
||||
This document is the implementation source of truth for Ferese v0 and records
|
||||
the gated desktop-tier roadmap. The terms **MUST**, **MUST NOT**, **SHOULD**,
|
||||
@@ -26,6 +26,24 @@ the gated desktop-tier roadmap. The terms **MUST**, **MUST NOT**, **SHOULD**,
|
||||
7. The nested compositor is the primary development environment.
|
||||
8. Security-sensitive operations are unavailable to untrusted clients.
|
||||
|
||||
### 2.1 Companion specification ownership
|
||||
|
||||
Ferese uses three normative documents with non-overlapping ownership:
|
||||
|
||||
| Concern | Normative owner |
|
||||
| --- | --- |
|
||||
| compositor mechanism, Wayland policy, focus, layout, rendering, IPC, security | this document |
|
||||
| shell interaction, visibility, launcher, notifications, DND, shell focus | `ferese-shell-design.md` |
|
||||
| colors, semantic surface tokens, typography, icons, and exact shell component geometry | `ferese-theme-ui-spec.md` |
|
||||
|
||||
The shell specification MUST reference visual tokens instead of duplicating
|
||||
pixel, radius, color, shadow, blur, or typography values. The theme/UI
|
||||
specification MUST NOT redefine focus, fullscreen, workspace, launcher,
|
||||
notification, or security behavior.
|
||||
|
||||
If companion documents conflict, the owner in this table is authoritative for
|
||||
that concern.
|
||||
|
||||
## 3. Scope
|
||||
|
||||
### 3.1 v0 core requirements
|
||||
@@ -58,8 +76,8 @@ for basic window management or application launching.
|
||||
|
||||
The desktop tier builds on the v0 core and includes:
|
||||
|
||||
- backdrop blur and semantic glass materials;
|
||||
- the Ferese overview, launcher UI, workspace strip, OSD, and notifications;
|
||||
- semantic surface materials with glass, translucent, and solid rendering;
|
||||
- the Ferese top bar, overview, launcher UI, workspace UI, OSD, and notifications;
|
||||
- the graphical settings application;
|
||||
- portal-backed screenshots and screen sharing; and
|
||||
- X11 compatibility through `xwayland-satellite` unless an architectural
|
||||
@@ -73,8 +91,8 @@ terminating the compositor or invalidating managed-window state.
|
||||
The following are outside v0:
|
||||
|
||||
- a file manager, display manager, or lock screen;
|
||||
- network, Bluetooth, or package-management UI;
|
||||
- a general plugin, scripting, or theme system;
|
||||
- network, Bluetooth, or package-management UI in v0 or the initial desktop-tier shell;
|
||||
- a general plugin or scripting system, or arbitrary CSS/component-replacement theme engine;
|
||||
- desktop widgets;
|
||||
- advanced dynamic layout algorithms;
|
||||
- exhaustive support for every Wayland protocol or toolkit edge case; and
|
||||
@@ -90,7 +108,7 @@ daemon is not part of v0.
|
||||
| Executable | Responsibility |
|
||||
| --- | --- |
|
||||
| `ferese` | Compositing, policy, input, scene construction, and rendering |
|
||||
| `ferese-shell` | Overview controls, launcher, workspace UI, notifications, and OSD |
|
||||
| `ferese-shell` | Top bar, overview controls, launcher, workspace UI, notifications, and OSD |
|
||||
| `ferese-settings` | Graphical configuration editor |
|
||||
| `feresectl` | Command-line IPC client |
|
||||
|
||||
@@ -372,6 +390,40 @@ set initial workspace, floating state, dimensions, or fullscreen state. Rules
|
||||
MUST be evaluated deterministically before insertion. Title matching SHOULD be
|
||||
avoided when a stable `app_id` exists.
|
||||
|
||||
### 5.5 Application identity and launch association
|
||||
|
||||
Ferese exposes normalized application identity to trusted shell clients without
|
||||
making application identity part of layout policy.
|
||||
|
||||
```rust
|
||||
pub struct ApplicationIdentity {
|
||||
pub desktop_id: Option<String>,
|
||||
pub app_id: Option<String>,
|
||||
pub startup_wm_class: Option<String>,
|
||||
}
|
||||
|
||||
pub struct LaunchAssociation {
|
||||
pub id: LaunchId,
|
||||
pub desktop_id: Option<String>,
|
||||
pub activation_token: Option<String>,
|
||||
pub child_pid: Option<u32>,
|
||||
pub started_at: Instant,
|
||||
}
|
||||
```
|
||||
|
||||
Application identity resolution MUST prefer explicit desktop-entry association,
|
||||
then normalized Wayland `app_id`, then `StartupWMClass`/X11 class metadata when
|
||||
available. Ferese MUST NOT guess that unrelated strings are equivalent merely
|
||||
because they are similar. Case and an optional `.desktop` suffix MAY be
|
||||
normalized only where desktop-entry semantics make that comparison unambiguous.
|
||||
|
||||
A shell-initiated launch MUST be tracked until the resulting window is
|
||||
associated or the launch expires. XDG activation information is the preferred
|
||||
association; process ancestry and normalized application identity MAY be used as
|
||||
fallbacks. The association exists to drive shell state such as `launching`,
|
||||
`running`, and focus. It MUST NOT bypass ordinary window rules or workspace
|
||||
policy.
|
||||
|
||||
## 6. Layout
|
||||
|
||||
```rust
|
||||
@@ -617,149 +669,256 @@ intermediates rather than full-resolution per-frame blur.
|
||||
|
||||
## 10. Material system
|
||||
|
||||
This section specifies the desktop-tier material system. It is not a v0 release
|
||||
gate.
|
||||
This section specifies compositor support for desktop-tier semantic surfaces. It
|
||||
is not a v0 release gate. Theme token values and exact component geometry belong
|
||||
to `ferese-theme-ui-spec.md`.
|
||||
|
||||
Initial semantic materials are:
|
||||
Initial semantic surface roles are:
|
||||
|
||||
```text
|
||||
normal
|
||||
glass.panel
|
||||
glass.popover
|
||||
glass.menu
|
||||
glass.hud
|
||||
surface.panel
|
||||
surface.panel_elevated
|
||||
surface.popover
|
||||
surface.menu
|
||||
surface.notification
|
||||
surface.hud
|
||||
surface.modal
|
||||
```
|
||||
|
||||
The compositor maps semantic names to theme-controlled parameters. Clients
|
||||
SHOULD request names rather than shader values.
|
||||
Clients request semantic roles rather than raw shader values.
|
||||
|
||||
The compositor resolves each role through the active material style:
|
||||
|
||||
```rust
|
||||
pub enum MaterialStyle {
|
||||
Glass,
|
||||
Translucent,
|
||||
Solid,
|
||||
}
|
||||
```
|
||||
|
||||
`ferese-effects-v1` is private to trusted Ferese components. It MAY set or clear
|
||||
a semantic surface material. It MUST NOT expose shader code, unrestricted
|
||||
capture, or unbounded effect values. Its global MUST be advertised only to
|
||||
Wayland clients granted the `effects` capability by the private-client mechanism
|
||||
in Section 13.
|
||||
a semantic surface role. It MUST NOT expose shader code, unrestricted capture,
|
||||
arbitrary renderer state, or unbounded effect values. Its global MUST be
|
||||
advertised only to Wayland clients granted the `effects` capability by the
|
||||
private-client mechanism in Section 13.
|
||||
|
||||
Glass renders as:
|
||||
For `Glass`, the compositor-owned rendering pipeline is:
|
||||
|
||||
```text
|
||||
lower scene content
|
||||
-> capture expanded region
|
||||
-> downsample
|
||||
-> dual Kawase blur
|
||||
-> blur
|
||||
-> upsample
|
||||
-> saturation and brightness
|
||||
-> tint and noise
|
||||
-> glass foreground
|
||||
-> tint and optional noise
|
||||
-> semantic surface foreground
|
||||
```
|
||||
|
||||
Blur MUST exclude the glass surface and all content above it. Sampling bounds
|
||||
MUST include the kernel radius.
|
||||
Blur MUST exclude the requesting surface and all content above it. Sampling
|
||||
bounds MUST include the kernel radius.
|
||||
|
||||
For `Translucent`, the compositor applies semantic tint and alpha without
|
||||
backdrop capture. For `Solid`, the compositor uses an opaque semantic surface
|
||||
color. Changing material style MUST NOT change component geometry, focus, input
|
||||
regions, layer-shell roles, or shell behavior.
|
||||
|
||||
A blur cache entry MUST identify its output and scale, visible and sample
|
||||
regions, material parameters, contributing lower-layer generations, and result
|
||||
texture. Changes to content, stacking, geometry, scale, transform, material,
|
||||
workspace, or output MUST invalidate affected entries. A global generation MAY
|
||||
be used initially; region-aware invalidation SHOULD replace it before performance
|
||||
tuning is complete.
|
||||
regions, semantic role and resolved material parameters, contributing
|
||||
lower-layer generations, and result texture. Changes to content, stacking,
|
||||
geometry, scale, transform, resolved material, workspace, or output MUST
|
||||
invalidate affected entries. A global generation MAY be used initially;
|
||||
region-aware invalidation SHOULD replace it before performance tuning is
|
||||
complete.
|
||||
|
||||
### 10.1 Built-in visual profile
|
||||
|
||||
The desktop tier provides one restrained dark profile rather than a theme
|
||||
engine. Its defaults are a subtle blue focus accent, 14 logical-pixel window
|
||||
radius, 10 logical-pixel tiling gaps, soft shadows, 24 logical-pixel backdrop
|
||||
blur, and mildly increased glass saturation. Focused and foreground content MUST remain distinguishable
|
||||
without requiring transparency. Blur, glow, borders, and shadows SHOULD establish
|
||||
hierarchy rather than compete for attention. Settings, overview, notifications,
|
||||
launcher, and OSD MUST use the same semantic materials and spacing system.
|
||||
The desktop tier provides one restrained Ferese visual language with glass,
|
||||
translucent, and solid profiles. Exact values for colors, radii, shadows,
|
||||
typography, spacing, and material parameters are normative only in
|
||||
`ferese-theme-ui-spec.md`.
|
||||
|
||||
Focused and foreground content MUST remain distinguishable without transparency.
|
||||
Blur, borders, and shadows SHOULD establish hierarchy rather than compete for
|
||||
attention. Settings, top bar, overview chrome, notifications, launcher, popovers,
|
||||
and OSD MUST consume the same semantic surface and spacing tokens.
|
||||
|
||||
## 11. Shell and overview
|
||||
|
||||
This section specifies desktop-tier behavior. `ferese-shell` owns overview
|
||||
controls, launcher, workspace strip, notifications, and volume and brightness
|
||||
OSD. Screenshot UI MAY be added after capture policy and implementation are
|
||||
complete. The shell uses a capability-scoped private Wayland connection plus
|
||||
authenticated IPC.
|
||||
This section specifies compositor-facing desktop-tier shell behavior. Detailed
|
||||
interaction is normative in `ferese-shell-design.md`; visual tokens and exact
|
||||
component geometry are normative in `ferese-theme-ui-spec.md`.
|
||||
|
||||
`ferese-shell` owns the top bar, overview controls, launcher, workspace UI,
|
||||
notifications, and volume and brightness OSD. Screenshot UI MAY be added after
|
||||
capture policy and implementation are complete. The shell uses a
|
||||
capability-scoped private Wayland connection plus authenticated IPC.
|
||||
|
||||
Ferese deliberately has no persistent dock or bottom application bar.
|
||||
|
||||
Overview MUST NOT require copying each managed window into the shell process.
|
||||
The compositor owns the live window presentation and enters an overview scene
|
||||
mode in which existing window scene nodes receive temporary visual transforms.
|
||||
`ferese-shell` supplies controls such as labels, selection affordances, workspace
|
||||
UI, and later search.
|
||||
`ferese-shell` supplies controls such as labels, selection affordances,
|
||||
workspace UI, and later search.
|
||||
|
||||
The overview binding is `Super+Tab`. Entering overview MUST animate windows from
|
||||
their current visible geometry into overview geometry. Pointer and keyboard
|
||||
selection MUST target the compositor-owned live window nodes. Dismissing overview
|
||||
MUST animate those same nodes back to the current layout targets. Workspace
|
||||
switching from overview MUST obey Section 5.4. Search MAY wait for the launcher
|
||||
milestone.
|
||||
selection MUST target the compositor-owned live window nodes. Dismissing
|
||||
overview MUST animate those same nodes back to the current layout targets.
|
||||
Workspace switching from overview MUST obey Section 5.4.
|
||||
|
||||
### 11.1 Shell surfaces
|
||||
### 11.1 Public layer-shell
|
||||
|
||||
`ferese-shell` MUST use standard layer-shell for launcher, workspace UI,
|
||||
notifications, and OSD surfaces. Such a surface is not a managed application
|
||||
window and MUST NOT enter tiling, workspace focus history, or normal application
|
||||
task switching. Ferese MAY use a minimal private `ferese-shell-v1` protocol for
|
||||
overview control and compositor-owned live-window selection, but it MUST NOT
|
||||
duplicate the standard layer-shell role or geometry model.
|
||||
`ferese-shell` MUST use standard layer-shell for the top bar, launcher,
|
||||
workspace UI, notifications, popovers, and OSD surfaces. Such surfaces are not
|
||||
managed application windows and MUST NOT enter tiling, workspace focus history,
|
||||
or normal application task switching.
|
||||
|
||||
Initial semantic roles are:
|
||||
Layer-shell is a public standard role and remains available to ordinary
|
||||
third-party panels, launchers, notification daemons, and wallpapers under
|
||||
Section 8 policy. Binding layer-shell MUST NOT grant Ferese-specific metadata,
|
||||
overview control, capture, virtual input, or semantic-surface capability.
|
||||
|
||||
The compositor enforces layer, exclusive-zone, keyboard-interactivity,
|
||||
input-region, namespace, and output policy.
|
||||
|
||||
### 11.2 Top bar, fullscreen, and reservation
|
||||
|
||||
The Ferese top bar is the only persistent Ferese shell surface that reserves
|
||||
workspace space.
|
||||
|
||||
Fullscreen is a presentation state over the preserved underlying workspace
|
||||
layout. Entering fullscreen MUST hide the Ferese top bar visually without
|
||||
changing the underlying workspace usable layout region. Leaving fullscreen MUST
|
||||
restore the bar without reconfiguring hidden tiled windows merely because the
|
||||
bar reappears.
|
||||
|
||||
A temporary top-bar reveal over fullscreen MUST use overlay presentation and
|
||||
`exclusive_zone = 0`. It MUST NOT resize the fullscreen client or alter the
|
||||
underlying workspace layout.
|
||||
|
||||
If `ferese-shell` disconnects unexpectedly, the compositor SHOULD retain the
|
||||
last valid Ferese-owned top-bar reservation for a short bounded grace period.
|
||||
If the shell reconnects with a compatible reservation before the lease expires,
|
||||
tiled windows MUST NOT reflow. If the grace period expires, Ferese removes the
|
||||
reservation and performs at most one ordinary layout reflow.
|
||||
|
||||
### 11.3 Private shell control protocol
|
||||
|
||||
`ferese-shell-v1` is a private control and metadata protocol. It MUST NOT
|
||||
duplicate layer-shell roles, exclusive zones, or general surface placement.
|
||||
|
||||
Its initial responsibilities are limited to:
|
||||
|
||||
```text
|
||||
launcher
|
||||
overview-controls
|
||||
workspace-ui
|
||||
notification
|
||||
osd
|
||||
managed-window list and lifecycle
|
||||
application identity metadata
|
||||
focused and urgent state
|
||||
activate managed window
|
||||
request close
|
||||
enter / exit overview
|
||||
select overview window / workspace
|
||||
```
|
||||
|
||||
The compositor enforces layer, exclusive-zone, focus, input-region, and output
|
||||
policy. The shell provides content and requests a standard layer-shell role; it
|
||||
MUST NOT receive unrestricted arbitrary z-order or geometry authority.
|
||||
Interactive shell surfaces MAY receive keyboard/pointer focus while active, but
|
||||
Ferese MUST restore the prior managed-window focus when the interaction ends.
|
||||
Destroying or disconnecting the shell client MUST remove its shell surfaces
|
||||
without changing managed-window state.
|
||||
The protocol requires the `shell-control` capability from Section 13. Requests
|
||||
MUST be validated against current stable identifiers and flow through the same
|
||||
domain operations as keyboard, pointer, and IPC actions.
|
||||
|
||||
### 11.2 Application launching and notifications
|
||||
### 11.4 Launcher and application launching
|
||||
|
||||
The launcher MUST execute configured argument vectors directly and MUST NOT pass
|
||||
them through a shell. Before launch, it MUST obtain an xdg-activation token tied
|
||||
to the triggering user interaction and make the token available to the child.
|
||||
The child receives the public Wayland display and normal session environment.
|
||||
It MUST NOT inherit a private Wayland descriptor, IPC capability, or bearer
|
||||
secret. A private descriptor deliberately inherited when the compositor starts a
|
||||
trusted component is the sole exception during that component's initial exec;
|
||||
the component MUST mark it close-on-exec before it can launch any child.
|
||||
The initial Ferese launcher is apps-only. Its default binding is `Super+Space`.
|
||||
It discovers XDG desktop applications, searches application names and normalized
|
||||
application identity, and launches selected applications.
|
||||
|
||||
The initial search placeholder is:
|
||||
|
||||
```text
|
||||
Search apps…
|
||||
```
|
||||
|
||||
Files, recents, settings, and command providers MAY be added later. The shell
|
||||
MUST NOT display dead tabs for unavailable providers.
|
||||
|
||||
Before launch, the shell MUST obtain an xdg-activation token tied to the
|
||||
triggering user interaction and make the token available to the child. The child
|
||||
receives the public Wayland display and normal session environment. It MUST NOT
|
||||
inherit a private Wayland descriptor, IPC capability, or bearer secret.
|
||||
|
||||
A private descriptor deliberately inherited when the compositor starts a trusted
|
||||
component is the sole exception during that component's initial exec; the
|
||||
component MUST mark it close-on-exec before it can launch any child.
|
||||
|
||||
### 11.5 Shell focus and modals
|
||||
|
||||
Interactive shell surfaces MAY receive `FocusTarget::Shell`. The persistent top
|
||||
bar SHOULD remain non-keyboard-interactive during ordinary use.
|
||||
|
||||
The launcher receives keyboard focus while open and MUST restore the previous
|
||||
valid managed-window focus on dismissal where possible. Interactive popovers and
|
||||
modals follow the same restoration rule.
|
||||
|
||||
A shell modal is appropriate only for destructive confirmation,
|
||||
security-sensitive confirmation, or an irreversible shell action. While a modal
|
||||
is active, the compositor presents a scrim and directs keyboard focus to the
|
||||
modal. Input outside the modal is consumed by the scrim and MUST NOT reach
|
||||
managed applications.
|
||||
|
||||
Destroying a shell surface or disconnecting the shell MUST never leave a dead
|
||||
`FocusTarget::Shell`.
|
||||
|
||||
Ferese does not ship a polkit authentication agent in the initial desktop tier.
|
||||
System authentication requiring polkit uses an external agent until a separate
|
||||
authentication-agent security specification exists.
|
||||
|
||||
### 11.6 Notifications and Do Not Disturb
|
||||
|
||||
`ferese-shell` MUST implement the standard `org.freedesktop.Notifications` D-Bus
|
||||
service for basic notifications. The desktop tier MUST support summary, body,
|
||||
icon metadata, expiry, replacement, close, and actions. Notification content is untrusted:
|
||||
markup, image paths, and action identifiers MUST be parsed and rendered without
|
||||
command execution. If the shell restarts, it MUST reacquire the service and
|
||||
continue without affecting managed windows.
|
||||
icon metadata, expiry, replacement, close, actions, and urgency metadata.
|
||||
|
||||
Notification content is untrusted: markup, image paths, and action identifiers
|
||||
MUST be parsed and rendered without command execution.
|
||||
|
||||
When Do Not Disturb is disabled, eligible notifications MAY create transient
|
||||
toasts and enter notification history. When Do Not Disturb is enabled, normal
|
||||
transient toasts are suppressed but notifications still enter history and
|
||||
unread state still updates. A future explicitly defined critical-urgency policy
|
||||
MAY bypass DND; application-name heuristics MUST NOT.
|
||||
|
||||
Network and Bluetooth control UI are outside the initial desktop-tier shell and
|
||||
MUST NOT appear as required or placeholder controls.
|
||||
|
||||
If the shell restarts, it MUST reacquire the notification service and reconstruct
|
||||
shell state without affecting managed windows.
|
||||
|
||||
## 12. Configuration
|
||||
|
||||
The primary file is `$XDG_CONFIG_HOME/ferese/config.toml`, falling back to
|
||||
`~/.config/ferese/config.toml`.
|
||||
|
||||
Configuration has one authoritative representation. Namespace ownership is:
|
||||
|
||||
```text
|
||||
[theme.*] visual tokens/material mapping ferese-theme-ui-spec.md
|
||||
[shell.*] shell behavior ferese-shell-design.md
|
||||
|
||||
[animations] compositor animation policy this document
|
||||
[tiling] layout policy this document
|
||||
[input] input policy this document
|
||||
[commands] launch command vectors this document
|
||||
[[bindings]] compositor bindings this document
|
||||
[[window_rules]] window placement rules this document
|
||||
```
|
||||
|
||||
There is no separate legacy visual namespace. Blur, opacity, radii, shadows,
|
||||
surface colors, typography, and shell component geometry belong only to
|
||||
`[theme.*]`.
|
||||
|
||||
Representative core configuration:
|
||||
|
||||
```toml
|
||||
[appearance]
|
||||
glass = true
|
||||
blur_radius = 24.0
|
||||
glass_opacity = 0.82
|
||||
corner_radius = 14.0
|
||||
|
||||
[appearance.shadow]
|
||||
enabled = true
|
||||
radius = 32.0
|
||||
offset_y = 8.0
|
||||
opacity = 0.28
|
||||
|
||||
[appearance.active_border]
|
||||
style = "subtle"
|
||||
width = 2.0
|
||||
|
||||
[animations]
|
||||
enabled = true
|
||||
reduced_motion = false
|
||||
@@ -828,16 +987,27 @@ floating = true
|
||||
Command values are argument arrays, never shell command strings. Binding records
|
||||
use a normalized key chord, match mode, action, and optional argument. `keysym`
|
||||
matching is the default and follows the active XKB layout. `physical` matching
|
||||
uses XKB physical key names and is independent of the selected layout. The
|
||||
complete built-in set is listed in Section 14; when a user supplies a record for
|
||||
the same chord and match mode it replaces that default. A record with
|
||||
uses XKB physical key names and is independent of the selected layout.
|
||||
|
||||
The complete built-in set is listed in Section 14; when a user supplies a record
|
||||
for the same chord and match mode it replaces that default. A record with
|
||||
`disabled = true` and no action explicitly unbinds the matching default.
|
||||
|
||||
Duplicate normalized bindings, unknown actions, invalid arguments, and
|
||||
references to missing commands MUST fail validation. Every built-in binding
|
||||
MUST be expressible, replaceable, and removable through this schema.
|
||||
|
||||
Unknown fields SHOULD warn. Invalid types, non-finite values, negative sizes,
|
||||
and out-of-range opacity MUST fail validation.
|
||||
`ferese-config` MUST assemble all enabled namespace schemas and validate the
|
||||
entire candidate configuration before applying any part of it. No companion
|
||||
component may maintain an independent competing copy of visual or shell
|
||||
configuration.
|
||||
|
||||
The launcher and overview actions are desktop-tier defaults and MUST be installed
|
||||
only when their shell features are available. Their absence from a v0-only
|
||||
installation is not a validation error.
|
||||
|
||||
Unknown fields SHOULD warn. Invalid types and invalid domain values MUST fail the
|
||||
owning schema's validation.
|
||||
|
||||
Reload MUST debounce duplicate events, read the entire file, parse, validate,
|
||||
construct, and apply the difference as one transaction. Invalid input MUST NOT
|
||||
@@ -861,8 +1031,7 @@ capabilities are:
|
||||
|
||||
```text
|
||||
effects
|
||||
overview-control
|
||||
global-metadata
|
||||
shell-control
|
||||
capture
|
||||
virtual-input
|
||||
```
|
||||
@@ -874,22 +1043,27 @@ client, and passes the client end only through an inherited descriptor such as
|
||||
arguments, environment secrets, or a discoverable private socket path.
|
||||
|
||||
The compositor associates an explicit capability set with each private Wayland
|
||||
client and filters private globals and requests against that set. In particular,
|
||||
`ferese-effects-v1` requires `effects` and the private overview requests in
|
||||
`ferese-shell-v1` require `overview-control`. `ferese-shell` receives only the
|
||||
capabilities required by enabled shell features.
|
||||
`ferese-settings` receives `effects` when spawned as a trusted Ferese component;
|
||||
its configuration changes still use the normal validated IPC path.
|
||||
client and filters private globals and requests against that set.
|
||||
|
||||
The private `capture` capability permits unattended capture only for a trusted
|
||||
component. Public screencopy clients remain subject to the interactive or
|
||||
configured capture policy and do not acquire this capability merely by binding
|
||||
the public screencopy global.
|
||||
`ferese-effects-v1` requires `effects`. `ferese-shell-v1` requires
|
||||
`shell-control`. `ferese-shell` receives only the capabilities required by
|
||||
enabled shell features. `ferese-settings` MAY receive `effects` when spawned as
|
||||
a trusted Ferese component; its configuration changes still use the normal
|
||||
validated configuration/IPC path.
|
||||
|
||||
Public layer-shell does not require a private capability. The private `capture`
|
||||
capability permits unattended capture only for a trusted component. Public
|
||||
screencopy clients remain subject to interactive or configured capture policy
|
||||
and do not acquire `capture` merely by binding a public global.
|
||||
|
||||
If a trusted component launches another privileged Ferese component, it MUST ask
|
||||
the compositor to create and pass a new capability-scoped private connection;
|
||||
it MUST NOT forward its own Wayland descriptor or capabilities.
|
||||
|
||||
Ferese does not ship a polkit authentication agent in the initial desktop tier.
|
||||
Security-sensitive actions requiring system authentication MUST use an external
|
||||
agent until a separate authentication-agent security specification exists.
|
||||
|
||||
### 13.2 Framing
|
||||
|
||||
IPC v0 uses unsigned 32-bit big-endian length-prefixed UTF-8 JSON:
|
||||
@@ -940,12 +1114,13 @@ show-overview hide-overview
|
||||
show-launcher hide-launcher
|
||||
```
|
||||
|
||||
Enumerating all window titles or capturing pixels requires shell privilege.
|
||||
Managed-window enumeration, application identity metadata, shell activation,
|
||||
close, and overview-selection operations used by `ferese-shell` belong to the
|
||||
private `ferese-shell-v1` protocol rather than widening normal user-control IPC.
|
||||
|
||||
Events include `window-opened`, `window-closed`, `window-focused`,
|
||||
`window-moved`, `workspace-changed`, `output-added`, `output-removed`,
|
||||
`config-changed`, and `config-error`. Payloads MUST omit titles and application
|
||||
IDs without shell privilege.
|
||||
`config-changed`, and `config-error`.
|
||||
|
||||
Subscribers have bounded queues. The server MUST disconnect a subscriber whose
|
||||
queue overflows rather than block the compositor.
|
||||
@@ -1028,7 +1203,7 @@ The target is sustained output refresh at 60 Hz on integrated graphics during
|
||||
ordinary use. Animation MUST also work at higher and variable refresh rates.
|
||||
|
||||
Ferese SHOULD track frame, render, layout and blur duration; damaged pixels;
|
||||
missed presentation deadlines; surface and glass-region counts; and active
|
||||
missed presentation deadlines; surface, semantic-material, and blur-region counts; and active
|
||||
animations. Performance tracing MUST be optional. Suggested targets are
|
||||
`ferese::wayland`, `ferese::layout`, `ferese::render`, `ferese::input`,
|
||||
`ferese::ipc`, and `ferese::xwayland`.
|
||||
@@ -1049,13 +1224,14 @@ stack cardinality, and do not duplicate or lose windows.
|
||||
Tests MUST cover defaults, partial files, unknown fields, invalid and non-finite
|
||||
values, duplicate key chords, unknown binding actions, missing command
|
||||
references, keysym versus physical matching, default unbinding, window-rule
|
||||
ordering, reload rollback, serialization, and atomic updates.
|
||||
ordering, theme/shell namespace ownership, reload rollback, serialization, and atomic updates.
|
||||
|
||||
### 17.3 IPC and security
|
||||
|
||||
Tests MUST cover partial reads, multiple frames per read, oversized frames,
|
||||
unsupported versions, subscriptions, slow clients, peer-UID rejection, and
|
||||
denial of privileged commands without capability. Launch tests MUST prove that
|
||||
denial of privileged commands without capability, `shell-control` filtering, and
|
||||
public layer-shell remaining unprivileged. Launch tests MUST prove that
|
||||
children receive the public display and activation token but cannot inherit any
|
||||
private Wayland or privileged IPC descriptor.
|
||||
|
||||
@@ -1068,7 +1244,8 @@ visual geometry, configured client size, and committed client size. Nested
|
||||
integration tests SHOULD cover configure/commit behavior, inverse-transformed
|
||||
input during animation, clipboard, popups, drag-and-drop, focus, fullscreen,
|
||||
xdg-activation, output removal, private-client capability filtering, overview
|
||||
scene transitions, notification replacement/actions, and shell restart.
|
||||
scene transitions, top-bar reservation restart grace, application-identity association,
|
||||
DND behavior, notification replacement/actions, and shell restart.
|
||||
|
||||
## 18. Milestones
|
||||
|
||||
@@ -1148,14 +1325,16 @@ configured terminal launches without shell parsing; malformed clients do not
|
||||
affect availability; a 24-hour native-client soak has no compositor crash or
|
||||
unbounded resource growth; all Section 3.1 requirements pass.
|
||||
|
||||
### M7: Glass materials
|
||||
### M7: Semantic surface materials
|
||||
|
||||
Before choosing a shell toolkit, build a minimal `wayland-client` probe that
|
||||
creates a layer-shell surface and sets a semantic material through
|
||||
`ferese-effects-v1`. Then implement capture, dual Kawase blur, tint, saturation,
|
||||
noise, caching, and invalidation.
|
||||
creates a layer-shell surface and requests `surface.panel` through
|
||||
`ferese-effects-v1`. Then implement semantic role resolution for glass,
|
||||
translucent, and solid styles plus backdrop capture, blur, tint, saturation,
|
||||
optional noise, caching, and invalidation.
|
||||
|
||||
Acceptance: the probe blurs only content behind its surface; backdrop changes
|
||||
Acceptance: the probe can switch among glass, translucent, and solid without
|
||||
changing geometry; glass blurs only content behind its surface; backdrop changes
|
||||
invalidate correctly; the effects global is visible only to a client with the
|
||||
`effects` capability; a public client cannot bind it; the demo meets its frame
|
||||
budget on the reference integrated GPU.
|
||||
@@ -1165,17 +1344,21 @@ budget on the reference integrated GPU.
|
||||
First spike GPUI layer-surface creation, output discovery, focus, configure, and
|
||||
shutdown behavior. If the spike fails its lifecycle tests, use a thin native
|
||||
Wayland shell adapter or record a toolkit decision before proceeding. Implement
|
||||
the compositor overview scene, minimal `ferese-shell-v1` overview control,
|
||||
launcher UI, workspace strip, OSD, and the standard notifications D-Bus service.
|
||||
the compositor overview scene, minimal `ferese-shell-v1` control/metadata
|
||||
protocol, top bar, apps-only launcher UI, workspace UI, OSD, and the standard
|
||||
notifications D-Bus service.
|
||||
|
||||
Acceptance: normal shell windows use layer-shell; `Super+Tab` controls overview;
|
||||
managed windows remain compositor-owned live scene nodes; selection follows
|
||||
visual geometry; notification replacement/actions work; shell restart does not
|
||||
disrupt windows; each trusted process receives only its assigned capabilities.
|
||||
Acceptance: normal shell surfaces use public layer-shell; `Super+Tab` controls
|
||||
overview; managed windows remain compositor-owned live scene nodes; selection
|
||||
follows visual geometry; the apps-only launcher uses application identity and
|
||||
XDG activation; DND and notification replacement/actions work; fullscreen hides
|
||||
the top bar without changing underlying layout geometry; shell restart preserves
|
||||
the top-bar reservation through its grace period; each trusted process receives
|
||||
only its assigned capabilities.
|
||||
|
||||
### M9: Settings and portals
|
||||
|
||||
Build Appearance, Tiling, Shortcuts, Input, Workspaces, Displays, and About.
|
||||
Build Theme/Appearance, Tiling, Shortcuts, Input, Workspaces, Displays, and About.
|
||||
Implement the portal backend and PipeWire integration for screenshots and screen
|
||||
sharing.
|
||||
|
||||
@@ -1212,8 +1395,8 @@ round identically; terminal changes damage the correct regions; and all
|
||||
interaction remains responsive.
|
||||
|
||||
M4 follows this nested slice immediately so frame pacing is validated on real
|
||||
hardware. Glass, GPUI, Settings, XWayland, notifications, portals, and theming
|
||||
MUST NOT delay it or the v0 core.
|
||||
hardware. Semantic materials, GPUI, Settings, XWayland, notifications, portals, and the
|
||||
graphical shell MUST NOT delay it or the v0 core.
|
||||
|
||||
## 20. Definition of v0
|
||||
|
||||
@@ -1234,7 +1417,8 @@ Ferese v0 is complete when a user can:
|
||||
restarts.
|
||||
|
||||
The intended v0 result is a low-latency, independently usable tiling compositor.
|
||||
The desktop tier adds a coherent Ferese shell, glass, graphical settings,
|
||||
The desktop tier adds a coherent Ferese shell, semantic surface materials,
|
||||
graphical settings,
|
||||
portals, and X11 compatibility without redefining core correctness. Visual
|
||||
effects support hierarchy and usability; they do not replace correctness,
|
||||
responsiveness, or security.
|
||||
Reference in new issue
Block a user