feresaria/docs/ferese-shell-design.md

# 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.