aria/feresaria
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add panel-wide styles and the Morph hub (#26)

Browse Source 
Panel appearance now applies to the whole panel, with seven styles: Floating, Capsules, Notch, Edge to edge, Fused islands, Adaptive and Morph.

- Share composition, geometry, and motion through the renderer-independent `ferese-panel` crate, including native materials, input regions, and Settings previews.
- Add the Morph hub with media, calendar, notifications, controls, workspace previews, hover feedback, and attached mode. Keep recording and low-battery status visible and respect window clearance.
- Cache workspace preview geometry, draw thumbnails directly, centralize Morph transitions, and keep rendering settings local to each shell instance.
- Put Record Screen in the Morph header and show the display control only when an external monitor is connected. Update panel documentation, the desktop screenshot, and native check style names.

Local validation included 660 compositor tests, 191 shell tests, isolated preview-cache checks, GPU Morph captures at 1×/1.25×/1.5×, formatting, and Clippy with warnings denied. The final header change passed all 23 Morph tests. Release workflow jobs are skipped for this PR.
This commit is contained in:
Samuel Onoja authored and GitHub committed 2026-10-12 01:31:34 +01:00
1 parent 42c3b290dd
commit e22f0ebef9
131 files changed
+12562 -1634
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/README.md
+1 -1
View File
@@ -4,6 +4,7 @@
- [Installation](installation.md): install dependencies, log in, preview changes, update and recover a session.
- [Configuration](configuration.md): configure layouts, input, shortcuts and displays in KDL.
- [Panel configuration](panel-configuration.md): choose a panel style, arrange groups and items, and configure the Morph hub.
- [Why Ferese](why-ferese.md): window layouts and a shared theme for the desktop.
- [Screenshots](screenshots.md): see the themes, overview and shell controls.
@@ -21,5 +22,4 @@
- [Development](development.md): build Ferese, run tests and check portal contracts.
- [Nested resize checks](nested-resize-testing.md).
- [Client soak testing](native-soak-testing.md).
- [Performance measurements](performance-baseline.md).
- [Website development](../site/README.md).
docs/animation-model.md
+7 -1
View File
@@ -69,6 +69,12 @@ The main spring responds more quickly than the viewport spring, allowing a windo
Bounce must be strictly between −1 and 1. Negative values produce overdamping; positive values require `overshoot #true` so the crossing policy permits the requested bounce. Duration and speed must be finite and positive, and the resolved stiffness and damping must remain finite and positive too. If the configuration fails these checks, Ferese keeps the last accepted settings.
The [Morph panel](panel-configuration.md#morph) uses the same spring solver,
with its own response and the shared speed and reduced-motion settings. Content
is laid out at the destination size while the shape expands around it, and
fades handle changes between views. The space kept clear of windows stays
unchanged throughout; regular status popups continue to use the main shell spring.
The global speed setting scales elapsed spring time, so 0.5 takes twice as long and 2.0 takes half as long. It applies to both compositor and Ferese shell motion. Setting `reduced-motion #true` takes precedence over enabled animations and applies the destination directly. Neither setting controls animations that applications draw inside their own windows.
## Passing a gesture’s velocity into the release
@@ -107,7 +113,7 @@ These slides use the viewport spring through [workspace navigation](../composito
An application’s surface lifetime does not always match the duration of its visible exit. Window entrance starts when content is available, but on unmap the live surface can disappear before a closing animation would finish. Ferese retains content for that exit, moving toward 98% of the current bounds while opacity, emphasis, and shadow fade to zero.
Closing during resize also retains the resize snapshots and their handoffs. Their progress must continue during close so the old buffer does not remain frozen over the exiting image. Retaining a picture is only part of the work; the presentation state that determines how it blends with the newer content has to continue advancing too.
Closing during resize also retains the resize snapshots and their handoffs. Their progress must continue during close so the old buffer does not remain frozen over the exiting image. The presentation state must keep advancing so the retained image can blend with the newer content.
Shell popups keep their surface until the closing motion settles, then destroy it. If you reopen the same panel during close, Ferese retargets that existing motion. Switching from Battery to Wi-Fi is different: the surface stays, but the new panel gets its own entrance. This behavior lives in [panel lifecycle handling](../shell/ferese-shell/src/status_ui/lifecycle.rs) and avoids a destroy-then-create gap between panels.
docs/configuration.md
+58 -176
View File
@@ -40,15 +40,16 @@ output-profile "docked" {
```
Lists use repeated `panel`, `group`, `item`, `binding`, `window-rule`,
`output-profile`, `output`, `note`, and `autostart` nodes. Bindings take their keys,
action, and argument positionally; profiles, outputs, and notes take a positional
name, match, or ID. Panels, groups, and items use positional IDs, while autostart
`output-profile`, `output`, and `autostart` nodes. Bindings take their keys,
action, and argument positionally; profiles and outputs take a positional
name or match. Panels, groups, and items use positional IDs, while autostart
commands use positional arguments. Other fields can be properties or child nodes,
but duplicate fields are rejected. The dotted paths in the reference tables
below describe nested sections.
Settings preserves comments and custom fields when editing, while normalizing
indentation.
Settings preserves comments and untouched configuration content when editing,
while normalizing indentation. Panel item annotations belong in an explicit
`metadata` section; unrecognized built-in options are rejected.
The Settings sidebar groups pages under Desktop, Interaction, and System, with
Motion under Windows and Shortcuts under Keyboard & mouse. Search includes both
@@ -57,10 +58,10 @@ views and opens the matching setting directly.
## Saving and validation
Settings saves text when you press Enter or leave the field, and sliders when
you release them. Undo restores the previous save. Reload reads external edits
without merging unfinished drafts. Wallpaper browsing needs `zenity`, but you
can also enter a path directly.
Settings keeps `config.kdl.settings-backup` before saving.
you release them, keeping `config.kdl.settings-backup` before each save. Use
Undo to restore the previous save, or Reload to read external edits without
merging unfinished drafts. To browse for a wallpaper, install `zenity`; you can
also enter its path directly.
File edits reload automatically, including atomic editor saves, so changes to
appearance, wallpaper, motion, input, bindings, rules, layouts, displays,
@@ -93,10 +94,10 @@ cancels pending pairing. Passwords are sent to NetworkManager, not saved in KDL;
pairing keys are managed by BlueZ. These controls affect the system even when
Settings is opened with a separate preview config.
Defaults below are built-in defaults, not your personal or packaged overrides.
Dimensions are logical pixels unless noted; numbers must be finite. Optional
values are omitted, not `null`. Colors use `#RRGGBB` or `#RRGGBBAA`.
Live config is limited to 60 KiB.
The tables below give built-in defaults; your configuration or the packaged
example may override them. Dimensions use logical pixels unless noted, and
numbers must be finite. Omit optional values rather than writing `null`, use
`#RRGGBB` or `#RRGGBBAA` for colors, and keep the live config within 60 KiB.
## Layout
@@ -186,6 +187,10 @@ immediate. Reduced motion takes precedence over `enabled #true`; setting
`speed 0` is invalid. These settings control Ferese's animations, not animations
inside other applications.
Morph animates its shape with its own spring and fades between views, while
following the shared speed and reduced-motion policy; see the
[panel guide](panel-configuration.md#morph) for its states and size controls.
Shell animations sample motion on each surface's redraw, paced by its Wayland
frame callbacks. They request animation frames only while moving.
Menus, modals, notifications and hover fades use this path instead of a fixed
@@ -326,6 +331,7 @@ is set.
| `theme.colors` key | Default | Meaning |
| --- | --- | --- |
| `surface-base` | `"#111821"` | Material/card base color |
| `surface-raised` | `"#1E2530"` | Raised surfaces, including the Morph hub |
| `text-primary` | `"#F4F7FB"` | Main text |
| `text-muted` | `"#8793A2"` | Secondary text |
| `accent` | `"#3D7BE6"` | Active controls and solid focus ring |
@@ -339,14 +345,14 @@ Filled controls choose a contrasting text color automatically.
| `border-width` | number ≥ 0 | `1` | Window border thickness |
| `focus-ring-width` | number ≥ 0 | `2` | Focused border thickness |
| `window-radius` | number ≥ 0 | `14` | Managed-window corners, independent of the shell |
| `shell-radius` | number ≥ 0 | `14` | All shell surfaces, cards and interaction backgrounds; fractional radii are preserved; 0 makes them square |
| `control-gap` | number ≥ 0 | `12` | Right-side control spacing |
| `shell-radius` | number ≥ 0 | `14` | Shell surfaces and controls, apart from panel shapes; fractional radii are preserved; 0 makes them square |
| `control-gap` | number ≥ 0 | `12` | Shared control spacing token; panel spacing belongs to its groups |
| Section / key | Type | Default | Meaning |
| --- | --- | --- | --- |
| `theme.surface.bar.background` | color | `"#1C202EF2"` | Shell fallback background; compositor materials use `surface-base` |
| `theme.surface.bar.text-primary` | color | `"#F0F3FA"` | Bar text/icons |
| `theme.surface.bar.text-muted` | color | `"#AAB4C7"` | Inactive bar foreground |
| `theme.surface.bar.background` | color | `"#111821"` | Regular panel background color; Morph uses `surface-raised` |
| `theme.surface.bar.text-primary` | color | `"#F4F7FB"` | Panel text/icons |
| `theme.surface.bar.text-muted` | color | `"#8793A2"` | Inactive panel foreground |
| `theme.shadow.soft.offset-y` | number | `4` | Window shadow vertical offset |
| `theme.shadow.soft.blur` | number ≥ 0 | `18` | Window shadow softness |
| `theme.shadow.soft.opacity` | number 0–1 | `0.20` | Window shadow strength |
@@ -808,116 +814,43 @@ intentionally turning off the last working one.
## Panel composition
Ferese shows one panel on each output, at the top by default. You can use the
default arrangement or define a `panel` block with its own geometry, surface
defaults, ordered groups, and item settings.
Ferese uses one panel configuration across all outputs, with each output laying
out its own workspace controls and focused-window title. Open **Settings →
Panel & Shell** to choose a style and position, then **Edit panel** to arrange
items in Start, Center and End groups. The composition preview stays visible
while you edit, and changes save automatically.
In Settings → **Panel & Shell**, **Panels** contains the position, background,
size, spacing, and corner-radius controls. Choose **Edit panel** to open
**Arrange**, where you can organize groups and items while the composition preview
stays visible above the independently scrolling editor and inspector.
**Back to Panels** returns to the panel controls.
Choose style, opacity and corners for the whole panel; groups control layout and
spacing. The available styles are Floating, Capsules, Notch, Edge to edge,
Fused islands, Adaptive and Morph. Capsules and Fused islands join neighboring
**groups within a zone**, so a zone with one group remains a single island.
Adaptive follows window state independently on each output, while Morph combines
the panel into a centered hub with expandable workspace, media and status views.
Use **Position** to choose Top or Bottom, or set `edge "top"` or `edge "bottom"`
inside the KDL panel block. Menus and notifications open toward the desktop, with
window clearance and **Edge margin** following that screen edge. Panel dimensions
live in a separate `geometry` block, so appearance changes do not resize the
panel. Its fields are `height` (24–128), `edge-margin`, `side-margins`, and
`window-clearance` (0–4096), plus `inner-padding` (0–64); their defaults are 28, 0,
0, 0, and 12 logical pixels respectively.
Each group has an **Add item** menu. Select a control to open its inspector, where
you can change visibility, overflow, preferred size, and placement, or remove the
item. To reorder it, use the **Up / Down** arrow buttons or drag its handle; dragging
also lets you move it to another group, and dropping into an empty zone creates a
group. Hidden controls remain in the editor with faded icons and labels. These
changes use the existing save and Undo controls, and `ferese-settings --page bar`
opens the page directly.
Use **Add group** in Start, Center, or End to create an empty group, then select
its name to change placement, surface, spacing, and padding. Arrow buttons reorder
groups within a zone; before removing a group, move or remove its controls.
The **Background** presets set the panel fill and default group surface together:
Continuous uses `solid` for the panel and `none` for groups, while Islands uses
`none` for the panel and `island` for groups. Applying either preset clears group
surface overrides while keeping your arrangement intact.
Use **Default group surface** to choose what groups inherit, or select Default,
None, Inset, or Island in an individual group's inspector. None adds no fill,
Inset wraps the padded content in a rounded surface, and Island adds a full-height
surface with island padding. Groups on a filled panel use a subtle local tint,
allowing arrangements such as a continuous panel with one media island or
navigation and status islands around an undecorated title. With mixed settings,
neither preset button is selected.
**Group borders** controls the outlines of all groups and is off by default,
while opacity and corner radii apply across the panel.
**Background opacity** overrides shell opacity for the panel background in either
arrangement, without fading controls or changing popups. **Use shell opacity**
restores inheritance.
Choose **Customize corners** to override the radius for the whole panel,
including its groups. The four sliders control top left, top right, bottom right,
and bottom left, saving each change when you release the slider.
In KDL, pixel values follow CSS shorthand: one value sets all corners; two set
top-left/bottom-right and top-right/bottom-left; three set
top-left, top-right/bottom-left, and bottom-right; four run clockwise from
top-left. For example, `4px 8px 12px 16px` gives each corner a different radius.
Values must be finite and nonnegative; percentages and elliptical `/` syntax are
not supported. Radii are clamped to half the shorter surface dimension.
At zero edge margin, panel backgrounds reach the selected screen edge with square
corners where they touch it, without changing the saved radii. Islands preserve
the gaps between groups, while Continuous fills the whole panel.
**Side margins** moves the left and right ends inward together over a range of
0–4096 px. The shell limits the requested inset for each output using measured
content widths: controls may compact, but the inset stops before causing
additional overflow. As content grows or the output gets smaller, the applied
inset shrinks to make room. If the controls cannot fit even at zero margin, the
panel uses its normal overflow behavior.
The panel follows the shell radius unless you set an override, which stays in
place when the shell radius changes. **Use shell radius** clears that override
without changing the arrangement; **Remove custom panel** restores both the
default arrangement and its inherited radius.
Dragging changes the drop hint until release, then saves the complete move once.
Escape, focus loss, and release outside a drop target cancel without saving.
The composition preview follows your draft and adapts to the Settings window's
width using sample content with every service available. Select a preview control
to edit that instance, or use the chevron to reveal overflow items. Browsing and
selection do not save anything: the first edit saves the composition and the
change together. The preview shares the shell's sizing resolver, while live
service state and exact vertical styling can differ.
Most panels default to 36 logical pixels high, Morph to 34, and detached styles
use 8-pixel margins unless your configuration overrides them. The packaged
configuration includes its own geometry overrides. For the complete options and
examples, see the [panel configuration guide](panel-configuration.md).
```kdl
panel "main" {
surface "none"
group-surface "island"
geometry { height 30; edge-margin 6; side-margins 18; window-clearance 4; }
border #false
background-opacity 0.85
edge "top"
style "floating"
geometry { height 36; edge-margin 8; window-clearance 4; }
start {
group "navigation" {
item "overview" kind="overview" overflow="never"
item "workspaces" kind="workspaces" overflow="never"
item "workspaces" kind="workspaces" style="dots" overflow="never"
}
}
center {
group "title" {
surface "none"
item "title" kind="focused-window" overflow="never"
}
}
end {
group "status" {
item "network" kind="network" overflow="always"
item "audio" kind="audio"
item "quick-settings" kind="quick-settings"
item "battery" kind="battery" percentage=#true
item "clock" kind="clock" representation="compact"
}
@@ -925,64 +858,11 @@ panel "main" {
}
```
Start, center, and end contain ordered groups of item instances. Their IDs must
be unique within the panel, contain 1–128 ASCII letters/digits or `-_.:@`, and not
start with `_`. Exactly one panel can be configured, without per-output overrides.
Built-in kinds are `overview`, `workspaces`, `focused-window`, `media`,
`quick-settings`, `network`, `audio`, `recording`, `notifications`, `battery`,
`clock`, and `display-mode`. Availability still follows the associated service
or hardware. Duplicate kinds are allowed when their IDs differ; clock instances
currently share the same clock format and timezone.
| Scope / key | Values / default | Meaning |
| --- | --- | --- |
| Panel `surface` | `solid` (default), `none` | Full panel fill or transparent space between decorated groups |
| Panel `group-surface` | `none` (default), `inset`, `island` | Inherited group surface |
| Group `surface` | omit to inherit, `none`, `inset`, `island` | Override surface independently of other groups |
| Panel `geometry` | height 28, edge/side margins 0, window clearance 0, inner padding 12 | Dimensions independent of the theme |
| Panel `border` | boolean; default `false` | Show group outlines |
| Panel `corner-radius` | optional px string, e.g. `"4px 8px"` | Override shell radius for all panel surfaces |
| Zone `spacing` | 0–64; default 8 | Gap between groups |
| Panel `background-opacity` | optional 0–1; inherits shell opacity | Override panel background opacity in either arrangement |
| Groups per panel | at most 31 | Reserves one of the 32 material regions for overflow |
| Group `spacing` | 0–64; default 1 | Gap between items |
| Group `padding` | two integers 0–32; default `2 3` | Vertical and horizontal inner padding |
| Group `island-padding` | 0–32; default 4 | Additional horizontal padding for islands |
| Item `visible` | boolean; default `true` | Allow the item when available |
| Item `overflow` | `auto` (default), `never`, `always` | Move when needed, keep visible, or place in overflow |
| Item `priority` | integer 0–100; default 50 | Lower priorities yield space first |
| Item `representation` | omit, `wide`, `compact`, `icon` | Preferred supported form; smaller forms may be used |
| Item `gap-before` | 0–64; unset | Override the preceding gap within a group |
| Item `metadata` | optional section | Custom data preserved by the editor; no shell behavior |
| Workspaces `style` | `numbers`, `dots` (default), `tabs`, `window-stacks`, `app-icons` | Workspace indicators; choose in the Workspaces item inspector |
| Battery `percentage` | boolean; default `true` | Include percentage in its full form |
| Focused window `visible` | boolean; default `true` | Include the title |
Media and clock support all three representations. Battery with a percentage
supports `wide` and `icon`; other controls keep their existing form. Unsupported
preferences use the kind's normal form. The title can shrink and ellipsize;
workspace controls scroll within their allocation. The panel itself does not scroll.
Workspace indicators keep the same width as their state changes. Dots use a pill
for the active workspace, a filled dot for an occupied workspace, and an outline
for an empty one. Tabs show workspace names, window stacks show up to three
window outlines, and app icons show up to two distinct running applications.
Hover for the workspace name and window count. Active transitions follow the
animation and reduced-motion settings. Explicitly set `style="numbers"`
to retain numbered indicators.
Item-specific settings belong to their kind: Workspaces uses `style`, Battery
uses `percentage`, and Focused window uses the shared `visible` flag. Unrecognized
options, including misspellings, are rejected, so custom data belongs in an
explicit `metadata` section such as
`item "clock" kind="clock" { metadata { note "Desk clock"; }; }`.
The center stays screen-centered. When controls cannot fit, lower-priority items
adapt first, with definition order breaking ties. The overflow chevron appears
before the end controls and opens displaced items through their usual menus.
`never` moves to overflow only when the mandatory controls cannot fit. A surface
narrower than the chevron's padded minimum clips that control.
If you omit the panel block, Ferese uses its default composition; if you write
one, its groups and items define the contents, and empty zones stay empty. Only
one panel block is accepted, and group and item IDs must be unique within it.
Use `edge "bottom"` to move the same arrangement to the bottom, with popups
opening toward the desktop and edge-relative corners mirroring vertically.
## Status controls
@@ -992,15 +872,16 @@ narrower than the chevron's padded minimum clips that control.
| `low-battery-threshold` | integer 0–100 | `20` | Warning-color threshold |
| `settings-command` | argument array | `["ferese-settings"]` | Settings launcher; `[]` hides the action |
Configure panel surfaces in **Panel & Shell** or in the `panel` block above.
Transparent gaps pass clicks through. Group islands use panel opacity and corner
radii; changing their surface leaves modal transparency and window clearance
unchanged. Island padding belongs to each group and applies only to islands.
Configure the panel in **Panel & Shell** or its KDL block, as described in the
[panel guide](panel-configuration.md). The panel's appearance applies to every
group, while popup and notification backgrounds follow the shared shell theme.
Transparent gaps between islands pass clicks through to the windows beneath.
### Now Playing
The media control on the right shows artwork, the track title and a play/pause
button. Click the artwork or title to open playback controls for MPRIS players.
The Media item can show artwork, the track title and a play/pause button wherever
you place it in the panel. Click the artwork or title to open playback controls
for MPRIS players; Morph presents playback in its Music view.
Scroll over the control to change the player's volume, or
middle-click to raise its window when supported. The menu has previous/next
buttons, a seek slider when supported, and a player chooser. It uses the same
@@ -1140,7 +1021,8 @@ and blur masks. Small controls cap the radius to fit their size; circles and pil
keep circular outlines. The measured profile has small tangent and curvature
discontinuities at its internal segment joins. Window rounding remains under
Settings → Windows. Shell rounding comes from `theme.geometry.shell-radius`,
which defaults to 14 px, with an optional corner override for each panel.
which defaults to 14 px. Panel corners follow their selected style and height,
with optional overrides in the [panel configuration](panel-configuration.md#background-outline-and-corners).
## X11 support (xwayland-satellite)
docs/development.md
+5 -6
View File
@@ -19,11 +19,11 @@ Run CI manually when a change needs it. Ordinary pushes and pull requests do not
start build runners, and website deployment is manual. Release tags and pull
requests labeled `release` run the release checks and package builds.
CI checks formatting, lints and tests across the whole workspace, including the
shell, settings, portal and CLI. The Fedora workspace job also builds desktop
binaries and runs installer, session-recovery and private portal-contract checks. The
compositor job runs offscreen capture regressions with software Mesa. Opt-in
nested and hardware checks remain separate.
The workspace workflow checks formatting, lints and tests on Ubuntu, including
the shell, Settings, portal and CLI. It builds the desktop binaries, runs the
Python integration suite and checks offscreen capture with software Mesa, then
uses those binaries for isolated panel and XWayland checks on a headless Wayland
host. Hardware checks remain separate.
## Test guides
@@ -32,7 +32,6 @@ nested and hardware checks remain separate.
- [Output management tests](output-management-testing.md): profiles, hotplug, mirroring, lid handling and failed DRM commits.
- [Nested resize checks](nested-resize-testing.md): wallpaper and bar responsiveness.
- [Client soak testing](native-soak-testing.md): repeated client lifecycle and resource growth.
- [Performance measurements](performance-baseline.md): sampling and historical results.
## Portal checks
docs/images/screenshots/ferese-morph.webp
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.5 MiB

docs/installation.md
+10 -10
View File
@@ -61,22 +61,23 @@ libraries.
To run X11-only applications, Ferese launches
[xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite),
which in turn needs an `Xwayland` binary. Both are runtime dependencies, not
build dependencies, and neither is needed to build Ferese.
which in turn needs an `Xwayland` binary. Both are runtime dependencies, so
neither is needed to build Ferese.
- `Xwayland` ships with the X.Org server packages: `xorg-x11-server-Xwayland`
on Fedora and Debian/Ubuntu, `xorg-xwayland` on Arch.
- `xwayland-satellite` is not packaged by most distributions. Build or install
it from its upstream releases **with its `systemd` feature enabled**
(`cargo build --release --features systemd`). That feature is what sends the
`READY=1` readiness notification Ferese waits for. Upstream's default feature
set is empty, so a default build never sends it, Ferese's fixed 10-second
startup budget expires, and the service reports a startup failure instead of
a display. A spawned process that is still alive is not readiness.
(`cargo build --release --features systemd`), which sends the `READY=1`
notification Ferese waits for. Upstream's default feature set is empty, so a
default build never sends that notification: even if the process remains alive,
Ferese's fixed 10-second startup budget expires and the service reports a
startup failure instead of a display.
Both the compositor's default and the packaged configuration ship with X11
enabled, so a session with the two pieces above needs no configuration change.
If you maintain your own `config.kdl`, the block to keep is
If you maintain your own `config.kdl`, keep this block in
`~/.config/ferese/config.kdl`:
```kdl
xwayland {
@@ -86,8 +87,7 @@ xwayland {
}
```
in `~/.config/ferese/config.kdl` and starting a new session, then check
`feresectl xwayland status`. See
Start a new session, then check `feresectl xwayland status`. See
[X11 support](configuration.md#x11-support-xwayland-satellite) for the full key
list, diagnostics, and known limitations.
docs/nested-resize-testing.md
+4 -4
View File
@@ -16,10 +16,10 @@ this at fractional scaling too.
## Compare renderers
Repeat the check with `ICED_BACKEND=wgpu` and `ICED_BACKEND=tiny-skia` to compare
renderers. The shell and Settings prefer software rendering with GPU fallback,
which keeps Settings labels visible inside scrolling content but can be slower
when resampling wallpaper. Setting `ICED_BACKEND` explicitly overrides that
preference.
renderers. The shell prefers tiny-skia with a wgpu fallback for its small
surfaces, while Settings prefers wgpu with a tiny-skia fallback for larger
scrolling pages. An explicit `ICED_BACKEND` selects the requested backend, and
the shell's automatic preference is not passed to Settings when it launches it.
Follow the trace from host resize through layer configure, client acknowledgement,
new buffer commit and compositor rendering. A quick acknowledgement does not mean
docs/panel-configuration.md
+382
View File
@@ -0,0 +1,382 @@
# Panel configuration
Use **Settings → Panel & Shell** to change the panel's style, position and
contents, or edit the `panel` block in `~/.config/ferese/config.kdl`. Settings
writes to this file, so you can arrange controls visually and then adjust their
values in KDL. Changes apply live, and an invalid edit leaves the last working
configuration active.
Ferese uses one panel configuration across all outputs. Each output lays out
its own panel using the space and services available there; workspace controls
and the focused-window title belong to that output. If you omit the `panel`
block, Ferese supplies its default composition. Once you write one, its groups
and items define the composition, including any zones you leave empty.
## Arrange the panel in Settings
The composition preview stays above the editor while you change the panel.
It uses sample content, so it can show a battery, media player or external
display control even when that service is unavailable in your session. Its
layout adapts to the width of the Settings window using the same allocation
rules as the shell.
Choose a **Style** from the compact dropdown, then use **Position** to place the
panel at the top or bottom. The appearance controls set its background opacity,
outline and corners, while **Size & spacing** controls its height and distance
from windows and screen edges. A reset button beside a dimension clears that
override; **Reset to style** clears geometry and corner overrides together.
Choose **Edit panel** to open Arrange, where **Add group** creates a group in
Start, Center or End. Use its **Add item** menu to fill it, then select an item
to change its placement, visibility, overflow, preferred size or options
specific to that control. Select the group itself to change its placement,
item spacing and padding; before removing it, move or remove its items.
Use the drag handles to move items within or between groups, or the arrow
buttons to reorder them. A drop hint shows where the item will go, and dropping
it into an empty zone creates a group there. The move saves on release;
Escape, focus loss or a release outside a valid target cancels it.
Other controls save automatically, with sliders saving when you release them.
**Undo** restores the previous save, **Reload configuration** reads external
edits, and **Back to Panels** returns to the appearance controls.
**Remove custom panel** restores the built-in composition, style and geometry;
Undo brings back the composition you removed.
You can open this page directly with `ferese-settings --page bar`.
## Choose a style
Choose the style for the whole panel; its groups share that appearance and
control only arrangement and spacing.
| Settings name | KDL value | Appearance and behavior |
| --- | --- | --- |
| Floating | `floating` | Separate rounded islands for occupied groups, with transparent gaps between them |
| Capsules | `capsules` | One rounded capsule per occupied zone, with dividers between its groups |
| Notch | `notch` | Groups attached to the screen edge, with curved shoulders around the centered group |
| Edge to edge | `flat` | A continuous full-width background with square outer corners |
| Fused islands | `fused` | Rounded groups with connecting necks where neighboring groups are close enough |
| Adaptive | `adaptive` | Floating with ordinary windows, edge to edge when maximized, and hidden in fullscreen |
| Morph | `morph` | One centered hub that expands into workspace, media and status controls |
Capsules and Fused islands join groups **within the same zone**, so a zone with
one group appears as a single pill in either style. To see the joins, put
Overview and Workspaces in separate Start groups, or separate the status controls
and Clock into two End groups. With Capsules, those groups touch and have a
divider between them; Fused islands keeps their configured spacing and blends
nearby shapes, while Floating leaves the gaps open.
When a group has no visible items, its background disappears, and the remaining
shapes adjust as items become unavailable or move into overflow. Clicks in
transparent gaps reach the windows underneath. If the active workspace contains
a fullscreen window, the panel hides on that output and releases its reserved
space.
Changing the style preserves your composition and saved appearance overrides.
Adaptive evaluates each output independently, with a 150 ms delay between
ordinary and maximized presentations to avoid switching back and forth during
brief state changes. Entering or leaving fullscreen takes effect immediately.
## Position, size and spacing
Set `edge "top"` or `edge "bottom"` on the panel. Its controls keep the same
order, while edge-relative corners and attached shapes mirror vertically.
Popups and notifications open toward the desktop.
Dimensions use logical pixels, so output scaling applies afterward. The
`geometry` block contains optional overrides; omitting a value lets the selected
style supply it.
| `geometry` key | Default | Accepted values | Meaning |
| --- | --- | --- | --- |
| `height` | 36; Morph uses 34 | Number 24–128 | Panel height, or Morph's collapsed height |
| `edge-margin` | 8 for detached styles; 0 for Notch and Edge to edge | Integer 0–4096 | Distance from the selected screen edge |
| `side-margins` | 8 for detached styles; 0 for Notch and Edge to edge | Integer 0–4096 | Requested inset at both ends of the panel |
| `window-clearance` | 0 | Integer 0–4096 | Additional reserved space between the panel and windows |
| `inner-padding` | 12 | Number 0–64 | Space inside the row before its first and after its last group |
Notch and Edge to edge use zero edge and side margins even if you have saved
overrides for them. Those values remain in the file and apply again when you
choose a detached style. Attached Morph also uses zero edge margin, while its
saved floating margin returns when attachment is disabled.
Ferese uses the requested side margins only while the content fits. It measures
the controls on each output and reduces the inset when the output narrows or
more content appears, so the margins do not cause additional overflow. Settings
limits the slider to the available display and preview measurements; KDL accepts
the wider range shown above.
Morph reserves space for its collapsed height plus window clearance. Its
expanded views overlay windows, so increasing their height does not push windows
down. At the panel edge, Morph accounts for the layout's outer gap rather than
adding the two gaps together.
## Background, outline and corners
`background-opacity` accepts a number from 0 to 1 and affects the panel
background without fading its text or icons. Omit it to inherit shell opacity,
or use the reset control beside **Background opacity** in Settings. It does not
change the opacity of popups, notifications or application windows.
The panel uses the shared material settings under `theme.material`, including
translucency and backdrop blur. Morph uses the theme's `surface-raised` color
and suppresses the material shadow. **Reduce Transparency** takes precedence
over a panel opacity override, making the background opaque and removing blur.
See [Appearance](configuration.md#appearance) for the shared theme controls.
Set `border #true` to draw the panel outline. Its color comes from
`theme.colors.border`, and Capsules also uses that color for its dividers.
Leave it at the default `#false` for no outline.
Automatic corners follow the style and panel height. Choose **Custom** to pin
them, or return to **Automatic** to remove the override. The four controls are
**Edge left**, **Edge right**, **Outer left** and **Outer right**, so they retain
their meaning when you move the panel to the bottom.
In KDL, `corner-radius` is a pixel string using CSS-style shorthand. One value
sets every corner; two set opposite pairs; three set the first corner, the
second/fourth pair and the third; four give each corner its own value. The
stored order is edge-left, edge-right, outer-right, outer-left:
```kdl
corner-radius "4px 8px 12px 16px"
```
On a top panel, that order runs clockwise from top-left. On a bottom panel,
the same values mirror vertically. Values must be finite and nonnegative, with
`px` units except for a bare `0`; percentages and elliptical `/` syntax are
not supported. Ferese scales radii to fit when adjacent corners would overlap,
and Edge to edge keeps its outer corners square. Corner pins stay saved when
you switch styles.
## Groups and items
Place groups in Start on the left, Center in the middle or End on the right,
then arrange items within them. Center stays centered on the panel even when
the two sides have different widths. Each group and item has an ID, so Settings
keeps track of the one you are editing when you move it.
Panel IDs, group IDs and item IDs contain 1–128 ASCII letters or digits, or
`-_.:@`, and cannot start with `_`. Group IDs must be unique across the panel,
as must item IDs; different instances of the same item kind are allowed when
their IDs differ. A panel supports up to 31 authored groups.
| Scope / key | Default | Accepted values | Meaning |
| --- | --- | --- | --- |
| Zone `spacing` | 8 | Number 0–64 | Gap between groups; Capsules and Notch use zero |
| Group `spacing` | 1 | Number 0–64 | Gap between items |
| Group `padding` | `2 3` | Two integers 0–32 | Vertical padding followed by horizontal padding |
| Group `island-padding` | 4 | Number 0–32 | Extra horizontal padding for island styles |
| Item `visible` | `#true` | Boolean | Show the item when its service or hardware is available |
| Item `overflow` | `auto` | `auto`, `never`, `always` | Overflow when needed, keep visible, or always use overflow |
| Item `priority` | 50 | Integer 0–100 | Lower values yield space first |
| Item `representation` | Preferred supported form | `wide`, `compact`, `icon`, or omit | Starting form before adapting to available space |
| Item `gap-before` | Unset | Number 0–64 | Override the gap before this item within its group |
| Item `metadata` | Empty | Nested section | Custom data preserved by Settings, without shell behavior |
Horizontal padding and island padding add together for island styles. Group
padding changes the space around that group's controls; it does not give the
group a separate height, style or set of corners.
`gap-before` has no effect on the first visible item in a group.
### Item catalog
The Add item catalog contains these twelve kinds. Service-dependent controls
appear when their service or hardware is available, and a focused-window item
disappears when that output has no window title to show.
| Settings name | `kind` | Item-specific options |
| --- | --- | --- |
| Overview | `overview` | Opens the workspace overview |
| Workspaces | `workspaces` | `style`: `numbers`, `dots`, `tabs`, `window-stacks`, `app-icons`; default `dots` |
| Focused window | `focused-window` | Use the shared `visible` field to show or hide the title |
| Media | `media` | Full, Compact and Icon representations |
| Quick Settings | `quick-settings` | Opens Control Center |
| Network | `network` | Opens Wi-Fi controls |
| Audio | `audio` | Opens audio controls |
| Recording | `recording` | Opens recording controls or stops the active recording |
| Notifications | `notifications` | Opens notifications |
| Battery | `battery` | `percentage`: boolean, default `#true` |
| Clock | `clock` | Full, Compact and Icon representations |
| Display mode | `display-mode` | Appears when an external display is connected |
Workspace styles change the regular panel's indicators. Numbers shows workspace
numbers and Tabs shows their names, while Dots uses a pill for the active
workspace. Window stacks uses
small window outlines, and App icons shows up to two distinct running apps.
Hovering an indicator shows its workspace name and window count. Clock
instances share the shell's clock format and timezone.
Unknown options are rejected, so put custom annotations inside `metadata`:
```kdl
item "desk-clock" kind="clock" {
metadata { note "Clock beside the audio control"; }
}
```
### Adaptation and overflow
In the inspector, **Full**, **Compact** and **Icon** correspond to `wide`,
`compact` and `icon`. Media and Clock support all three; Battery with percentage
supports Full and Icon. Workspaces and Focused window have one form that can
shrink, while other controls use icons. An unsupported preference falls back
to the item's normal form.
When space runs short, lower-priority items yield first, with their order in the
composition breaking ties. Flexible content can shrink, and items can switch
to smaller supported forms; overflow keeps the remaining controls accessible
from the chevron. **Keep visible** maps to `never`, **When needed** to `auto`,
and **Always** to `always`. Even `never` can move into overflow if the mandatory
controls cannot fit at their minimum sizes.
The overflow chevron appears before the End controls, and selecting an entry
opens that item's usual controls. The panel itself does not scroll; workspace
indicators may scroll within the space they receive, while long window titles
end with an ellipsis.
## Morph
Morph combines the panel into one centered hub. Alongside a compact workspace
strip, it shows artwork, the track title and an equalizer during playback.
Otherwise it shows the focused-window title, falling back to the date when
there is no title. Recording and low-battery states take priority over ordinary
content. Hovering can expand a preview, and clicking opens the hub's Workspaces,
Music, Calendar,
Notifications or Controls view. Escape or the close button collapses it.
The Workspaces view shows miniature window layouts. Click a tile to switch
workspace, use Tab and the arrow keys to navigate it, or drag a miniature window
to another tile on the same output. Scrolling over the collapsed hub changes
workspace, with a brief workspace preview after a switch.
Morph keeps your saved composition for when you switch back to a regular panel.
The hub uses its own layouts and compact workspace dots, so Start/Center/End
positions, group padding and the regular workspace indicator style do not apply
inside it. Item settings still determine which configured controls appear in
its Controls view and shortcuts.
Turn on **Attach to screen edge** to join the hub to the chosen edge with curved
shoulders, or set `morph { attached #true; }`. **Preview on hover** maps to
`peek-on-hover`; disabling it leaves click-to-open behavior available. These
two switches appear in Settings when Morph is selected, while the size values
below can be adjusted in KDL.
| `morph` key | Default | Meaning |
| --- | --- | --- |
| `attached` | `#false` | Join the hub to the selected screen edge |
| `peek-on-hover` | `#true` | Show a preview when the pointer enters |
| `idle-width` | 150 | Collapsed content width budget |
| `peek-width` | 260 | Hover preview width budget |
| `peek-height` | 44 | Hover preview height |
| `toast-width` | 320 | Notification toast width |
| `toast-height` | 48 | Notification toast height |
| `expanded-width` | 340 | Width of expanded views |
| `workspaces-height` | 176 | Workspace view height |
| `media-height` | 170 | Music view height |
| `calendar-height` | 230 | Calendar view height |
| `notifications-height` | 176 | Notifications view height |
| `controls-height` | 248 | Maximum Controls view height before scrolling |
| `expanded-radius` | 26 | Default corners for expanded views |
All width and height values must be finite numbers from 24 to 1024, and
`expanded-radius` accepts 0–128. The collapsed hub and workspace feedback fit
their content, Controls may open at a shorter height, and all views stay within
the available output area. A configured width therefore allows room for content
without forcing empty space around it.
For ordinary media and date previews, the maximum width is `peek-width` clamped
to 200–280 pixels. Activity previews choose their own width, and workspace
feedback can be narrower. If you have pinned the panel's corners, those values
override `expanded-radius`.
Morph follows animation speed and reduced motion. As it expands, the area that
accepts clicks follows its shape while the space kept clear of windows stays
unchanged; if you interrupt a transition, it continues from the shape already
on screen.
## Examples
### Joined groups with a centered title
This composition puts Overview and Workspaces in separate Start groups so
Capsules can join them with a divider. The title stays centered, and the two
End groups keep status controls together while separating the clock.
```kdl
panel "main" {
edge "top"
style "capsules"
border #true
background-opacity 0.85
geometry {
height 36
edge-margin 8
side-margins 8
window-clearance 4
}
start {
group "overview" {
item "overview" kind="overview" overflow="never" priority=100
}
group "navigation" {
item "workspaces" kind="workspaces" style="dots" overflow="never" priority=100
}
}
center {
group "title" {
padding 0 0
item "title" kind="focused-window" overflow="never"
}
}
end {
group "status" {
item "media" kind="media" representation="wide"
item "quick-settings" kind="quick-settings"
item "network" kind="network"
item "audio" kind="audio"
item "recording" kind="recording"
item "notifications" kind="notifications"
item "battery" kind="battery" percentage=#true
}
group "time" {
item "clock" kind="clock" representation="compact"
item "display" kind="display-mode"
}
}
}
```
Change only `style` to `floating` or `fused` to compare the same composition
with separate or blended islands, or use `adaptive` to let window state choose
between Floating and Edge to edge.
### An attached Morph hub
Keep the groups from the previous example, set `style "morph"`, and add this
section inside the same panel block. Changing `edge` to `bottom` mirrors the
attached shape without changing the profile.
```kdl
morph {
attached #true
peek-on-hover #true
expanded-width 360
media-height 180
controls-height 248
}
```
To return to a floating hub, set `attached #false`; its saved edge margin then
applies again. The profile stays in the file when you choose another style, so
you can return to Morph without re-entering these values.
## Validate a file
Save your edit and run `ferese --check-config ~/.config/ferese/config.kdl` to
validate it without applying changes. The file accepts one `panel` block;
unknown fields, duplicate IDs, unavailable styles and out-of-range dimensions
are errors. See [Saving and validation](configuration.md#saving-and-validation)
for how Settings and live reloads handle a failed validation.
docs/screen-sharing.md
+7 -7
View File
@@ -1,12 +1,12 @@
# Screen sharing and recording
Share a monitor or window from a Wayland-compatible recording or conferencing app,
or save a video using the top bar. [Installation](installation.md) includes the
portal and PipeWire dependencies.
or save a video using the panel's Recording control. The
[installation guide](installation.md) covers the portal and PipeWire dependencies.
## Record from the top bar
## Record from the panel
1. Click the recording icon.
1. Click the Recording item in the panel, or open Controls → Recording in Morph.
2. Choose a display and an audio source: **Off**, **System sound**, **Microphone**,
or **Both**. Audio is off by default; the other choices use
your default output or input device from audio settings.
@@ -38,9 +38,9 @@ The picker follows your shell colors, font, corners, opacity, and blur.
## Stop sharing
Click **Stop sharing** or close the sharing window. For the built-in recorder,
use the stop button in the top bar. Sharing also ends when the app closes or
Ferese locks. If you disconnect a shared monitor or change its capture size,
its stream ends and you need to start sharing again.
use the panel's stop button, which Morph also shows while recording. Sharing
also ends when the app closes or Ferese locks. If you disconnect a shared monitor
or change its capture size, its stream ends and you need to start sharing again.
## Remember permissions
docs/screenshots.md
+2 -1
View File
@@ -34,7 +34,8 @@ Six themes, each with paired light and dark colours.
## Panel & Shell
Panel composition, position and surface settings.
The composition preview and panel controls in Settings. See the
[panel configuration guide](panel-configuration.md) for the current styles and options.
[![Panel and Shell settings with a composition preview and island surfaces.](images/screenshots/ferese-panel-settings.webp)](images/screenshots/ferese-panel-settings.webp)
docs/why-ferese.md
+10 -12
View File
@@ -1,16 +1,16 @@
# Why Ferese
When you use a window manager, arranging windows is only part of using the desktop. You still need to connect to Wi-Fi, change an audio device, adjust a display, read notifications and lock the screen. Those tasks involve different components, but you encounter them as parts of the same environment. When their settings and behaviour are maintained separately, making them fit together becomes another job.
Alongside a window manager, you need Wi-Fi, audio and display controls, notifications and a lock screen. Choosing separate desktop components remains useful when you want that independence, though keeping them consistent becomes another job when their settings and behaviour are maintained separately.
Ferese brings window management and desktop controls into one project. It includes a Wayland compositor, a desktop shell, Settings, Control Center and a lock screen, with configuration and theming shared across its components. Building them together makes it possible to decide how a desktop change should work across those components, rather than leaving each one to interpret it independently.
Ferese includes a Wayland compositor, desktop shell, Settings, Control Center and a lock screen with shared configuration and theming. It keeps window management configurable while defining how a desktop change applies across those components.
## Settings that apply beyond one component
Changing an accent colour should affect the places where Ferese uses that colour. Changing motion speed should affect both window transitions and shell transitions. These are desktop preferences, even though the compositor and shell run in separate processes. Ferese’s shared theme and motion settings give those processes a common definition to work from.
An accent-colour change should reach the places where Ferese uses it, just as a motion-speed change should affect both window and shell transitions. The compositor and shell run in separate processes, but their shared theme and motion settings give them the same values to work from.
Settings and `~/.config/ferese/config.kdl` are two ways to edit the same configuration. You can use the graphical interface for a display change, then open the file to adjust a binding or window rule. Settings preserves comments and custom fields when saving. File changes reload automatically, and invalid edits leave the last working configuration active. This lets the graphical controls remain useful without making the configuration file a secondary or unsupported way to manage the desktop.
Settings and `~/.config/ferese/config.kdl` edit the same configuration, so you can change a display in Settings, then open the file to adjust a binding or window rule. Settings preserves comments and untouched configuration content when saving, and file changes reload automatically. If an edit is invalid, the last working configuration stays active.
The shared settings have a defined scope. Ferese can coordinate the surfaces it draws and the transitions it manages; it does not control every animation an application draws inside its own window. That distinction matters when describing a consistent desktop: consistency between Ferese’s components should not be confused with taking over application behaviour.
Ferese can coordinate the surfaces it draws and the transitions it manages; it does not control every animation an application draws inside its own window.
[![Ferese Appearance settings with six paired light and dark themes.](images/screenshots/ferese-appearance.webp)](images/screenshots/ferese-appearance.webp)
@@ -20,7 +20,7 @@ A scrolling layout is useful when several windows need more space than can comfo
Ferese supports both, with the layout selected per workspace. Floating windows are also available and remember their size and placement. A workspace can therefore use scrolling columns for a sequence of wide windows, while another uses tree tiling for a smaller set that needs to be viewed together.
Even within scrolling, moving focus does not always need to move the desktop. Ferese’s minimal focus strategy leaves a fully visible column where it is and scrolls only far enough to reveal a hidden edge. Other strategies centre the focused column or arrange columns into viewport-sized pages. These choices affect how much the desktop moves while you work, so they belong in the layout’s behaviour rather than being treated as visual decoration.
Even within scrolling, moving focus does not always need to move the desktop. Ferese’s minimal focus strategy leaves a fully visible column where it is and scrolls only far enough to reveal a hidden edge. Other strategies centre the focused column or arrange columns into viewport-sized pages.
[![Ferese Overview with open windows and three workspace previews.](images/screenshots/ferese-overview.webp)](images/screenshots/ferese-overview.webp)
@@ -28,12 +28,10 @@ Even within scrolling, moving focus does not always need to move the desktop. Fe
An animation often starts before you have finished deciding what to do. You might focus another window while the viewport is moving, reverse a fullscreen transition, or reopen a panel before it has finished closing. The desktop needs to handle that next input using the state already on screen.
Continuum, Ferese’s shared motion system, keeps a moving value’s current position, velocity and destination. Changing the destination can preserve the existing movement instead of restarting from rest. Direct manipulation follows a different rule: a dragged window follows the pointer directly, while a released gesture hands its velocity to a spring. The distinction keeps the animation from adding a trailing movement between your hand and the window.
Continuum, Ferese’s shared motion system, keeps a moving value’s current position, velocity and destination. Changing the destination can preserve the existing movement instead of restarting from rest. A dragged window follows the pointer directly so it does not trail your hand; when you release a gesture, its velocity passes to a spring.
This coordination extends beyond position. A window’s content, clipping and border need to follow the same presented bounds. When the application closes, its live surface may disappear before the visual exit finishes, so Ferese retains an image for that transition. When a shell panel closes, its content and compositor-drawn material need to leave together. Otherwise, the text can disappear while its background or blur remains. These are practical reasons for designing the motion system alongside the compositor and shell.
A window’s content, clipping and border need to follow the same presented bounds. When the application closes, its live surface may disappear before the visual exit finishes, so Ferese retains an image for that transition. Shell content and its compositor-drawn material also need to leave together, or the text can disappear while its background or blur remains.
## Taking responsibility for the whole interaction
## Testing the whole interaction
Including more of the desktop also means taking responsibility for more of its behaviour. A common theme does not resolve a late application buffer, and a correct spring equation does not make a missed frame arrive on time. Resize coordination, output timing and interrupted transitions still need testing, including measurements on the hardware where the desktop runs.
Ferese’s reason for existing is to work on those interactions together while keeping window management configurable. Choosing separate desktop components remains useful when that independence is what you want. Ferese takes responsibility for the components it includes, so changing the layout, adjusting the appearance or using an everyday desktop control does not also require maintaining the connections between them.
A shared theme does not resolve a late application buffer, and a correct spring equation does not make a missed frame arrive on time. Resize coordination, output timing and interrupted transitions still need testing and measurements on the hardware where the desktop runs.