diff --git a/README.md b/README.md index 6fa78eb..25c0c3a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Ferese

-

A complete Wayland desktop built around personalization

+

A configurable Wayland desktop

Install · @@ -11,7 +11,7 @@ Documentation

-Ferese is a window manager and desktop shell built together and configured in one place, for people who want their desktop to be their own. +Ferese combines a window manager and desktop shell with one configuration. ![Ferese Blue desktop with Settings and Control Center](docs/images/screenshots/ferese-main-hero.png) @@ -19,14 +19,16 @@ Ferese is a window manager and desktop shell built together and configured in on ## Features -- Scrolling columns, tree tiling and floating windows, with an overview of all your workspaces -- Keyboard shortcuts and touchpad gestures you can remap -- Multiple monitors with fractional scaling -- Themes, wallpapers, blur and corners that update live, with Light/Dark/Auto modes and custom KDL themes +- Scrolling columns with window grouping, tree tiling and floating windows that remember their size and placement +- Workspace overview and recent-window switching +- Remappable keyboard shortcuts and touchpad gestures +- Multiple monitors with fractional scaling and automatic refresh-rate switching on low battery +- Themes, wallpapers and blur that update live, with Light/Dark/Auto modes and custom KDL themes +- Squircle window corners with matching borders and shadows - Desktop widgets, including a clock and sticky notes -- Screenshots with annotation, plus screen sharing and built-in recording -- A built-in lock screen -- Integrated Settings and Control Center for configuring your desktop +- Screenshots with annotation, screen sharing and built-in recording +- A built-in lock screen and authentication dialogs +- Settings and Control Center with Wi-Fi, Bluetooth and audio controls ## Install @@ -45,9 +47,8 @@ guide](docs/installation.md) also walks you through previews, updates and recove ## Configure -Make it yours through **Control Center → Settings** or `~/.config/ferese/config.kdl`, -with changes applying as you make them and the last working configuration staying in -place if an edit is invalid. +Configure Ferese through **Control Center → Settings** or `~/.config/ferese/config.kdl`. +Changes apply live. Invalid edits leave the last working configuration in place. The [configuration reference](docs/configuration.md) and [example config](packaging/config.kdl) cover everything from appearance and window layouts to @@ -78,16 +79,14 @@ Shortcuts** whenever you want to change a shortcut or gesture. | Three-finger swipe up / down | Next / previous workspace | | Three-finger swipe left / right | Focus the window to the right / left | -Explore [all shortcuts and mouse actions](docs/shortcuts.md) for more ways to arrange -your windows and move between workspaces. +See [all shortcuts and mouse actions](docs/shortcuts.md) for window and workspace controls. ## Documentation -The [documentation index](docs/README.md) brings the desktop guides together, while -[development instructions](docs/development.md) cover building, testing and -contributing. +The [documentation index](docs/README.md) lists the desktop guides. +[Development instructions](docs/development.md) cover building, testing and contributing. -Ferese is written in Rust using Smithay, with development happening [on +Ferese is written in Rust using Smithay. Development happens [on GitHub](https://github.com/ferese-wm/ferese). If something goes wrong, [open an issue](https://github.com/ferese-wm/ferese/issues) with the steps to reproduce it and any relevant logs. diff --git a/crates/ferese-theme/README.md b/crates/ferese-theme/README.md index 29b7ed6..2d77c85 100644 --- a/crates/ferese-theme/README.md +++ b/crates/ferese-theme/README.md @@ -1,7 +1,7 @@ # Ferese theme -The shared native UI theme for the shell, settings, lock screen, authentication -prompt and screen-sharing/recording chooser. +This crate supplies the shared native UI theme used by the shell, settings, lock +screen, authentication prompt and screen-sharing/recording chooser. - `Palette` resolves KDL colors and corners and builds the native toolkit theme. - `PRESETS` defines twelve variants in six families. @@ -17,8 +17,8 @@ prompt and screen-sharing/recording chooser. Keep the attachment alive with its window and make the client background transparent after attachment succeeds. Other compositors retain the client fill. -Applications supply layout, data, actions, and animation progress. Extend shared -components when a style is needed across apps. +Each application supplies its layout, data, actions and animation progress. +Add styles used by several apps to the shared components. ```rust let palette = ferese_theme::Palette::from_document(Some(&document)); @@ -28,5 +28,5 @@ let font = ferese_theme::font(Some("Inter")); let label = ferese_theme::text("Appearance", font); ``` -The compositor owns backdrop blur and material rendering. This crate does not -provide a client-side imitation of those effects. +Backdrop blur and material rendering happen in the compositor. This crate does +not reproduce those effects on the client. diff --git a/docs/README.md b/docs/README.md index 4e97502..e541cbf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,23 +2,21 @@ ## Get started -- [Installation](installation.md): dependencies, login, previews, updates, and recovery. -- [Configuration](configuration.md): KDL syntax, layouts, input, shortcuts, and displays. -- [Why Ferese](why-ferese.md): layouts and the shared desktop theme. - -- [Screenshots](screenshots.md): desktop themes, overview and shell controls. +- [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. +- [Why Ferese](why-ferese.md): window layouts and a shared theme for the desktop. +- [Screenshots](screenshots.md): see the themes, overview and shell controls. ## Use the desktop -- [Shortcuts and gestures](shortcuts.md): keyboard navigation, Super-drag, resize, and window grouping. - -- [Lock screen](locking.md): appearance, automatic locking, and display sleep. -- [Screen sharing and recording](screen-sharing.md): choosing sources and stopping a session. -- [Desktop portals](portals.md): application integration and supported services. +- [Shortcuts and gestures](shortcuts.md): keyboard navigation, moving and resizing with Super-drag, and window grouping. +- [Lock screen](locking.md): change its appearance, set up automatic locking and configure display sleep. +- [Screen sharing and recording](screen-sharing.md): choose a source and stop sharing. +- [Desktop portals](portals.md): services available to applications. ## Develop Ferese -- [Development](development.md): builds, tests, and portal checks. +- [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). diff --git a/docs/configuration.md b/docs/configuration.md index 6e9178c..7fddafe 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -39,21 +39,22 @@ output-profile "docked" { } ``` -Repeated `binding`, `window-rule`, `output-profile`, `output`, `note` and -`autostart` nodes describe lists of settings. Bindings accept positional -keys/action/argument; profiles, outputs and notes accept a positional name, -match or ID. Other fields can be properties or child nodes. Autostart accepts -its command as positional arguments. Duplicate fields are rejected. +Use repeated `binding`, `window-rule`, `output-profile`, `output`, `note` and +`autostart` nodes for lists of settings. Bindings accept keys, an action and its +argument positionally. Profiles, outputs and notes accept a positional name, +match or ID; other fields can be properties or child nodes. Autostart commands +use positional arguments. 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. Configuration uses KDL. +indentation. ## Saving and validation -Settings saves automatically: text on Enter/focus loss, sliders when released. -Undo restores the previous save; Reload picks up external edits without merging -unfinished drafts. Wallpaper browsing needs `zenity`; a path can also be entered. +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. File edits reload automatically, including atomic editor saves. Invalid changes @@ -414,11 +415,12 @@ window rules can override that behavior. | `width`, `height` | numbers > 0 | Application-chosen floating size | | `fullscreen` | boolean | Leave fullscreen state unchanged | -At least one matcher is required; supplied matchers must all match. Rules apply -in order, with later fields overriding earlier ones. Dimensions imply floating -when `floating` is omitted. Floating apps without dimensions choose their own -size. Placement first centers transients on the visible part of their parent, -then tries remembered geometry, then the position with least summed overlap. +Every rule needs at least one matcher, and supplied matchers must all match. +Rules apply in order; later fields override earlier ones. Dimensions imply +floating when `floating` is omitted. Floating apps without dimensions choose +their own size. Ferese first tries to center transient windows on the visible +part of their parent, then tries saved geometry, then the position with the least +summed overlap. Equal-overlap candidates favor the focused window's center. If the size cannot fit, a per-output cascade advances by 32 logical pixels and wraps to the work-area origin. Placement respects layer-shell exclusive zones and client minimum sizes; @@ -426,10 +428,11 @@ an oversized window keeps its size with its top-left corner reachable. Successful move/resize completion saves ordinary floating geometry by app ID in `$XDG_STATE_HOME/ferese/floating.json` (normally `~/.local/state/ferese/floating.json`). -The output name and work-area fractions preserve placement across resolution -changes. Missing outputs and restores with less than 25% visibility are skipped. -Saves run on a worker and pending updates coalesce to the latest snapshot; -drag completion updates memory immediately without waiting for storage. +Geometry is stored with the output name and as fractions of its work area, so +placement survives resolution changes. Restores are skipped if the output is +missing or less than 25% of the window would be visible. A worker saves the +latest snapshot, combining pending updates. Completing a drag updates memory +immediately without waiting for storage. Transient dialogs and cancelled drags do not update this memory. Floating → tiled → floating also restores the window's last floating geometry. Nested previews keep drag memory in process and do not write the user's saved placements. diff --git a/docs/development.md b/docs/development.md index 892a561..93ad39c 100644 --- a/docs/development.md +++ b/docs/development.md @@ -27,9 +27,9 @@ cargo test --locked -p xdg-desktop-portal-ferese python3 scripts/tests/test_portal_contracts.py ``` -The contract test uses a private bus. It checks signatures, appearance changes, -invalid-config retention, and caller authorization. It does not prove complete -compatibility with every app or open consent dialogs. +The contract test runs on a private bus and checks signatures, appearance changes, +caller authorization and retention of the last working config after invalid edits. +It does not open consent dialogs or prove complete compatibility with every app. With release binaries built, run isolated integration checks: @@ -41,9 +41,9 @@ FERESE_TEST_RESTORE=1 python3 scripts/tests/test_restore_isolated.py FERESE_TEST_WINDOW_STREAM=1 python3 scripts/tests/test_window_stream_isolated.py ``` -These cover shortcut cleanup, window capture, inhibitors, restored permissions, -and live window streams. Check each script's dependencies before running it. -They use disposable nested sessions or private buses. +These checks use disposable nested sessions or private buses to test shortcut +cleanup, window capture, inhibitors, restored permissions and live window streams. +Check each script's dependencies before running it. For monitor streaming and lock revocation, install Python GI/GStreamer with `pipewiresrc`, `dbus-daemon`, `xdg-desktop-portal`, and `bwrap`, then run: @@ -77,17 +77,17 @@ access tokens, or private window content. ## Resume recovery -The direct backend retains known GPU identities while their DRM resources are -unavailable. Hotplug, configuration and lid changes reconcile through one path; -inactive sessions defer that work. Activation reads the lid asynchronously, then -re-enumerates devices and connectors before allowing presentation. A logind -system-wake signal follows the same path, including when seat ownership did not -change. Newer libinput observations supersede in-flight lid reads. A failed read -preserves the last observation; a three-second deadline prevents a stalled bus -from blocking recovery indefinitely. +The direct backend keeps track of known GPUs when their DRM resources are +unavailable. It handles hotplug, configuration and lid changes through the same +recovery path, deferring the work while the session is inactive. On activation, +it reads the lid state asynchronously and re-enumerates devices and connectors +before allowing presentation. A logind system-wake signal triggers the same work, +even if seat ownership has not changed. New libinput observations take precedence +over pending lid reads. If a read fails, Ferese keeps the last observation. Reads +have a three-second deadline so a stalled bus cannot block recovery indefinitely. -Device failures retire their output globals and retry with exponential backoff -capped at 32 seconds. Working devices remain usable. Known hardware can return +When a device fails, Ferese removes its output globals and retries with exponential +backoff capped at 32 seconds. Working devices remain usable. Known hardware can return under a different `cardN` path. This does not expand support to previously unmanaged secondary GPUs. Connected-output reports mark a mode active only when output creation succeeded. Lock ownership is retained throughout recovery. diff --git a/docs/installation.md b/docs/installation.md index 1f93c99..fdd75f3 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,13 +1,13 @@ # Installation -Ferese runs on Linux as its own Wayland session, alongside your existing desktop, and -you can launch it from a login manager, a command-based greeter or a local TTY. +Ferese runs on Linux as its own Wayland session alongside your existing desktop. +Launch it from a login manager, a command-based greeter or a local TTY. ## Requirements For a full session, you’ll need a Wayland-capable graphics driver and a local user -session with seat access through logind or seatd, while a nested preview runs inside the -Wayland desktop you already use. +session with seat access through logind or seatd. A nested preview runs inside your +existing Wayland desktop. To build Ferese, install **Rust 1.95 or newer**, a C/C++ toolchain, CMake, pkg-config and the libraries below. The installer builds the Ferese components once those system @@ -49,10 +49,10 @@ sudo apt install build-essential git curl cmake pkg-config libwayland-dev \ gstreamer1.0-plugins-good ``` -Fedora is the tested installation path, and package names or versions may differ on -other distributions, where the [Smithay -dependencies](https://github.com/Smithay/smithay#system-dependencies) can help you find -equivalent libraries. +Installation has been tested on Fedora. Package names or versions may differ on +other distributions; check the [Smithay +dependencies](https://github.com/Smithay/smithay#system-dependencies) for equivalent +libraries. ### Rust toolchain @@ -82,17 +82,17 @@ cd ferese ./scripts/install.sh ``` -The script builds locked release binaries as your normal user and then asks for -administrator access through `sudo` or `pkexec` to install them, so leave the build +The script builds locked release binaries as your normal user, then asks for +administrator access through `sudo` or `pkexec` to install them. Leave the build itself unprivileged. The first build needs network access to fetch Rust dependencies. -Installation brings together the session launcher, desktop tools, portal backend, login +The installer adds the session launcher, desktop tools, portal backend, login entry, icons, default wallpaper and example config. Releases live under `/usr/local/lib/ferese/releases/` and commands under `/usr/local/bin/`, with `current` and `previous` links for switching between releases during updates and rollback. -Your configuration, other desktop sessions and existing PAM policy stay in place, while -Ferese starts its authentication agent and portal services together with the session. +The installer preserves your configuration, other desktop sessions and existing PAM +policy. Ferese starts its authentication agent and portal services with the session. The authentication agent registers for the login session, so requests from desktop apps use the Ferese dialog. Remove other polkit agents from your Ferese autostart configuration to avoid competing session registrations. @@ -110,8 +110,8 @@ if [ ! -e "${XDG_CONFIG_HOME:-$HOME/.config}/ferese/config.kdl" ]; then fi ``` -After login, open **Control Center → Settings** or run `ferese-settings` to shape your -desktop, using [Configuration](configuration.md) for themes, displays, shortcuts and +After login, open **Control Center → Settings** or run `ferese-settings` to configure +your desktop. See [Configuration](configuration.md) for themes, displays, shortcuts and startup apps. The default terminal is `foot`, which you can replace with your preferred terminal command in Settings. @@ -144,8 +144,8 @@ If your greeter asks for a session command instead of reading desktop files, use /usr/local/bin/ferese-session ``` -For greetd, set this as the session command after authentication using the [greetd -documentation](https://sr.ht/~kennylevinsen/greetd/), and the launcher will start the +For greetd, set this as the session command after authentication; see the [greetd +documentation](https://sr.ht/~kennylevinsen/greetd/). The launcher starts the compositor, shell and session services together. ### From a TTY @@ -176,7 +176,7 @@ Install these through your distribution when you want the corresponding features | Audio controls | PipeWire, WirePlumber, and `wpctl` | | Bluetooth controls | BlueZ, `bluetoothctl`, and its running service | -Package names and availability vary by distribution, so use Satty’s [upstream +Package names and availability vary by distribution. Use Satty’s [upstream instructions](https://github.com/Satty-org/Satty#install) if it isn’t in your repositories. Ferese leaves service setup to you and preserves your existing service configuration during installation. @@ -184,8 +184,8 @@ configuration during installation. Use **Print Screen** to capture the active monitor, **Super+Shift+S** to select an area, or `ferese-screenshot --all` to capture all monitors in one image. -The native locker follows your shell theme and can be personalized in **Settings → Lock -Screen**, with `ferese-lock --preview` opening an ordinary preview window. Before +The native locker follows your shell theme. Customize it in **Settings → Lock +Screen**, and run `ferese-lock --preview` to open an ordinary preview window. Before enabling automatic locking, test real unlocking and read [Native locker](locking.md) for authentication, idle locking and limits. @@ -230,11 +230,11 @@ git pull --ff-only ./scripts/install.sh ``` -Log out and back in to start using the new release, as a running session keeps its -existing processes and release paths until it restarts. +Log out and back in to use the new release. A running session keeps its existing +processes and release paths until it restarts. Each release records the portal configuration it ships so later upgrades can identify -it, and installation stops if it encounters modified or untracked administrator files. +it. Installation stops if it encounters modified or untracked administrator files. To replace Ferese portal configuration from an earlier development install, build first and run `./scripts/install.sh --skip-build --replace-portal-config`, which backs up the existing files in the new release’s `portal-config.previous/` directory. @@ -268,8 +268,8 @@ process: pgrep -a -u "$USER" -x ferese ``` -Replace `PID` with the affected session’s process ID and use `kill PID` to end it, -bearing in mind that its applications will close and unsaved work may be lost. You can +Replace `PID` with the affected session’s process ID and use `kill PID` to end it. +Its applications will close and unsaved work may be lost. You can then choose another desktop at the next login. ### Roll back a release @@ -312,8 +312,8 @@ configuration; reinstalling Ferese restores the desktop session entry. ## Screen sharing and recording -Ferese’s native ScreenCast portal is included in the installation, which backs up the -old user service override pointing to `~/.local/libexec/ferese` so new sessions use the -installed release. Custom overrides are preserved and reported before building, and -[Screen sharing](screen-sharing.md) covers consent, PipeWire setup, supported sources +The installer includes Ferese’s native ScreenCast portal and backs up the old user +service override pointing to `~/.local/libexec/ferese`, so new sessions use the +installed release. Custom overrides are preserved and reported before building. +See [Screen sharing](screen-sharing.md) for consent, PipeWire setup, supported sources and recording limits. diff --git a/docs/locking.md b/docs/locking.md index e5f9f93..2ad8cda 100644 --- a/docs/locking.md +++ b/docs/locking.md @@ -15,9 +15,9 @@ ferese-lock --foreground # stay attached until unlock Do not enter your real password in a preview. The account picture comes from AccountsService or `~/.face`; a silhouette is used when neither is available. -Escape clears the password. Caps Lock is shown beside authentication status. -Failed attempts show an error and delay retries. Authentication uses the system's -PAM policy; both password and account validation must succeed. +Press Escape to clear the password. The authentication status also shows whether +Caps Lock is on. A failed attempt displays an error and delays the next retry. +Authentication uses the system's PAM policy; both password and account validation must succeed. ## Automatic locking @@ -46,23 +46,23 @@ lock-screen { } ``` -These delays start after locking, independently of the automatic-lock timer. +Both delays start when the session locks, separately from the automatic-lock timer. Display sleep does not suspend the computer. A nested preview shows black instead of powering off the host display. ## Recovery and limits -The lock covers all displays, including newly connected ones. If the lock UI -crashes, the compositor keeps the session protected and permits a replacement -locker to take over. A running locker cannot be replaced. Launch `ferese-lock` -with the affected session's Wayland environment to recover; ending the session -from another TTY remains an option (see [Recovery](installation.md#logout-and-recovery)). +The lock covers all displays, including displays connected after locking. If the +lock UI crashes, the compositor keeps the session protected and allows a replacement +locker to take over. A running locker cannot be replaced. To recover, launch +`ferese-lock` with the affected session's Wayland environment. You can also end the +session from another TTY; see [Recovery](installation.md#logout-and-recovery). -Readiness is reported only after protocol confirmation: every connected output -has presented protected content, or there are no outputs. The pinned Iced runtime -also emits a synthetic `Locked` event when making the request. The locker retains -its two-event guard until upstream distinguishes request initiation from protocol -confirmation; dependency upgrades must re-audit this workaround. +The locker reports readiness only after protocol confirmation. At that point, +every connected output has presented protected content, or there are no outputs. +The pinned Iced runtime also emits a synthetic `Locked` event when it sends the +request. The locker keeps a two-event guard until upstream separates that event +from protocol confirmation. Dependency upgrades must re-audit this workaround. Password messages use zeroizing storage. Avatar files are limited to 8 MiB, 4096 pixels per dimension, and a 32 MiB decoding budget. The clock updates at diff --git a/docs/native-soak-testing.md b/docs/native-soak-testing.md index e3fc31e..fa38b65 100644 --- a/docs/native-soak-testing.md +++ b/docs/native-soak-testing.md @@ -1,13 +1,12 @@ # Native-client soak testing -The soak runner repeatedly creates and destroys native Wayland clients while -exercising focus, resize, column width, fullscreen, floating, and workspace -paths. Every tenth iteration also terminates a client abruptly. If a local -malformed-client probe is available, it opens three isolated connections that -send malformed Wayland messages. The runner requires -Ferese to disconnect each malformed client and then checks that the compositor -and authenticated IPC socket remain responsive. It also records compositor RSS -growth. +The soak runner repeatedly opens and closes native Wayland clients, testing focus, +resize, column width, fullscreen, floating windows and workspace changes. Every +tenth iteration terminates a client abruptly. When a local malformed-client probe +is available, it sends malformed Wayland messages through three isolated connections. +The runner requires Ferese to disconnect each malformed client, then checks that +the compositor and authenticated IPC socket still respond. It also records +compositor RSS growth. Build `ferese` and `feresectl` and start a disposable [nested session](installation.md#preview-and-logs). Select its Wayland socket and @@ -29,10 +28,10 @@ FERESE_SOAK_SECONDS=300 \ ./scripts/soak-native.sh ``` -Development probes are local-only, not distributed in the Cargo workspace. -Supply an existing executable with `FERESE_MALFORMED_CLIENT` to enable protocol -checks. An explicitly configured missing probe is an error; without a probe, -the runner reports that protocol checks are skipped. +Development probes are local tools and are not distributed in the Cargo workspace. +Set `FERESE_MALFORMED_CLIENT` to an existing executable to enable protocol checks. +If you explicitly configure a probe that does not exist, the runner reports an +error. Without a probe, it reports that protocol checks are skipped. The local probe can also be run independently against a disposable Ferese session: diff --git a/docs/nested-resize-testing.md b/docs/nested-resize-testing.md index 6e8dde7..baa928c 100644 --- a/docs/nested-resize-testing.md +++ b/docs/nested-resize-testing.md @@ -9,18 +9,18 @@ WAYLAND_DEBUG=1 FERESE_TRACE_PERFORMANCE=1 \ target/release/ferese-shell 2>/tmp/ferese-resize.log ``` -Use a wallpaper, drag each edge of the host window, and repeatedly maximize and -restore it. Check that the wallpaper and bar follow without long stalls, including -at fractional scaling. +Set a wallpaper, then drag each edge of the host window and repeatedly maximize +and restore it. The wallpaper and bar should resize without long stalls. Check +this at fractional scaling too. ## Compare renderers Repeat with `ICED_BACKEND=wgpu` and `ICED_BACKEND=tiny-skia`. The shell enables wgpu; software fallback can be slower when resampling wallpaper. -Trace the whole sequence: host resize, layer configure, client acknowledgement, -new buffer commit, then compositor rendering. A quick acknowledgement does not -mean the client has finished drawing. `FERESE_TRACE_PERFORMANCE` measures compositor +Follow the trace from host resize through layer configure, client acknowledgement, +new buffer commit and compositor rendering. A quick acknowledgement does not mean +the client has finished drawing. `FERESE_TRACE_PERFORMANCE` measures compositor work, not shell rasterization. ## Historical check @@ -28,8 +28,8 @@ work, not shell rasterization. A KDE Wayland check at 175% scale used debug binaries and protocol tracing. Median configure acknowledgement was 1.35 ms with tiny-skia and 2.27 ms with wgpu. Wallpaper buffer intervals were 5919 ms with tiny-skia (only two buffers) -and 9.85 ms median with wgpu. Capture durations differed, so these are diagnostic -observations rather than throughput benchmarks. GPU intervals also had stalls +and 9.85 ms median with wgpu. The captures had different durations, so these +observations do not establish comparative throughput. GPU intervals also had stalls up to about 200 ms. Repeat on the current build. A nested result does not establish direct-session diff --git a/docs/performance-baseline.md b/docs/performance-baseline.md index 450c1c0..ac7c79d 100644 --- a/docs/performance-baseline.md +++ b/docs/performance-baseline.md @@ -13,13 +13,13 @@ FERESE_TRACE_PERFORMANCE=1 target/release/ferese --backend nested \ --grant-effects --grant-shell-control -- target/release/ferese-shell ``` -Compare idle, several windows, overview, Settings navigation, translucent -popovers, and screen capture separately. Allow startup to settle and repeat each -sample. Record process CPU, child-process CPU, RSS, render attempts, and damaged -frames. Keep build work and unrelated activity outside the sampling interval. +Measure idle, several windows, overview, Settings navigation, translucent popovers +and screen capture separately. Wait for startup to settle, then repeat each sample. +Record process CPU, child-process CPU, RSS, render attempts and damaged frames. +Do not build or run unrelated workloads during the sample. -CPU percentages below use one core as 100%. Short samples are observations, -not guarantees or hardware-session benchmarks. +CPU percentages below use one core as 100%. These short samples describe observed +behavior; they are not guarantees or hardware-session benchmarks. ## Direct frame timing @@ -33,11 +33,11 @@ For a direct session, enable `FERESE_TRACE_PERFORMANCE=1` and `RUST_LOG=ferese::render=debug` before starting Ferese. The timing records include the planned render start, actual render start, timer lateness, presentation target, DRM presentation timestamp, and request-to-presentation duration. -Missed deadlines compare submitted frames with their targets; idle gaps do not -count. Request-to-presentation starts at the compositor's redraw request, so it -does not include device input latency, client rendering before the request, or -the display's pixel response. Render cost measures CPU preparation and queueing; -asynchronous GPU work is covered conservatively by feedback-driven margins. +Missed deadlines are counted against submitted frames' presentation targets; +idle gaps do not count. Request-to-presentation timing starts at the compositor's +redraw request. It does not include device input latency, client rendering before +the request or the display's pixel response. Render cost measures CPU preparation +and queueing. Feedback-driven margins allow conservatively for asynchronous GPU work. Check sustained animation, idle wakeup, callback-only clients, and mixed-refresh outputs separately. Nested sessions do not exercise the DRM scheduler. @@ -52,23 +52,22 @@ while a render timer was scheduled or a frame was in flight. Compare these with coalesce and are not themselves rendered frames. `animation fallback scheduling` reports watchdog arms, cancellations, wakeups, -recovery requests and observations of animations with an intact normal frame -chain. Summaries are emitted during redraw activity every five seconds and on -normal exit. The fallback counters reset with each summary. An orphaned animation -gets a watchdog deadline two refresh intervals after its own output loses its -frame chain. Recovery also retains a requested final frame if another output -settles that animation while scheduling is unavailable. Idle, powered-off and -disconnected outputs do not set that deadline. -An already scheduled render or pending page flip suppresses the watchdog; this -policy does not replace DRM error recovery or diagnose a permanently lost flip. +recovery requests and animations whose normal frame chain is intact. Ferese emits +summaries every five seconds during redraw activity and on normal exit, resetting +the fallback counters each time. When an animation loses its output's frame chain, +the watchdog deadline is two refresh intervals later. Recovery keeps a requested +final frame even if another output settles the animation while scheduling is +unavailable. Idle, powered-off and disconnected outputs do not set that deadline. +The watchdog is suppressed when a render is already scheduled or a page flip is +pending. It does not replace DRM error recovery or diagnose a permanently lost flip. The regression replays use a 60 Hz animation beside an idle 240 Hz output. The old fallback rule produces 60 unnecessary wakes in one simulated second; the new rule produces zero while the normal chain remains intact. Three cursor moves within one output require three output requests rather than the old six. -These are deterministic scheduling counts, not live DRM CPU, latency or battery -measurements. Verify those separately with the same hardware workload before -making claims about power savings. +These counts come from deterministic scheduling replays. They do not measure live +DRM CPU use, latency or battery consumption. Measure those separately with the same +hardware workload before claiming power savings. ## Settled overview damage @@ -79,8 +78,8 @@ Intel Core Ultra 7 258V and Mesa 26.2.3. Ten-second process samples measured removing forced full damage from unchanged rounded thumbnails. A settled five-second interval changed from 300 damaged frames to zero. -The nested backend still makes about 300 no-damage render attempts per interval; -this change avoids unchanged submissions rather than changing nested scheduling. +The nested backend still makes about 300 no-damage render attempts per interval. +The change skips unchanged submissions; it does not alter nested scheduling. These short samples exclude host compositor CPU and do not measure battery discharge or direct DRM performance. @@ -115,8 +114,8 @@ cached reading; the existing `wpctl` reader preserves volume and device semantic Disconnected subscriptions retain bounded polling, and missing sinks retry. Brightness and other status polling remain unchanged. -These are short nested observations, exclude the host compositor, and do not -measure battery discharge. Raw measurements and profiles were saved locally in +These short nested samples exclude the host compositor and do not measure battery +discharge. Raw measurements and profiles were saved locally in `/tmp/ferese-shell-profile-20261002`. The subscription regression starts its own PipeWire server, changes default diff --git a/docs/portals.md b/docs/portals.md index 4f90803..65e0de5 100644 --- a/docs/portals.md +++ b/docs/portals.md @@ -1,8 +1,8 @@ # Desktop portals -Desktop portals let applications request screen sharing, screenshots, wallpaper -changes, and other desktop services. Ferese provides themed consent dialogs; -GTK supplies file, print, and other standard dialogs. +Applications use desktop portals to request screen sharing, screenshots, wallpaper +changes and other desktop services. Ferese supplies themed consent dialogs, while +GTK handles file, print and other standard dialogs. Install `xdg-desktop-portal`, `xdg-desktop-portal-gtk`, and Ferese's backend through [Installation](installation.md). The session launcher starts the services with @@ -29,23 +29,24 @@ This does not affect ordinary application clipboard use. ## Consent and capture -Screenshot and screen-sharing requests ask for approval. Screen sharing can -remember display permissions when the application requests it and the user opts -in. Window sharing always asks again. See [Screen sharing](screen-sharing.md). +Screenshot and screen-sharing requests need approval. Display-sharing permissions +can be remembered when the application requests it and the user opts in. Window +sharing always asks again. See [Screen sharing](screen-sharing.md). Window captures contain the selected app and its subsurfaces; separate popups, other apps, shell layers, and compositor decorations are excluded. -InputCapture starts at an approved display-edge barrier. **Ctrl+Alt+Escape** -returns local control. Locking, disconnecting the receiver, or changing displays -or the keyboard layout stops capture. Touch and remembered InputCapture grants -are not supported. InputCapture forwards local input; it does not inject remote input. +InputCapture starts at an approved barrier at the edge of a display. Press +**Ctrl+Alt+Escape** to regain local control. Capture stops when you lock the session, +disconnect the receiver, change displays or change the keyboard layout. Touch and +remembered InputCapture grants are not supported. InputCapture forwards local +input; it does not inject remote input. Wallpaper approval copies the image into Ferese's data directory and updates the config. Set `theme.background.lock-path` for a separate lock-screen image; otherwise it follows the desktop wallpaper. Global shortcuts cannot replace Ferese bindings or reserved escape/console keys. -They stop when the app session closes and never activate on the lock screen. +They stop when the app session closes. They never activate on the lock screen. Power confirmations show app inhibitors before proceeding. Ferese has no user-switch operation. diff --git a/docs/screen-sharing.md b/docs/screen-sharing.md index 8766648..4c364fc 100644 --- a/docs/screen-sharing.md +++ b/docs/screen-sharing.md @@ -10,9 +10,9 @@ portal and PipeWire dependencies. 2. Select a monitor and click **Share**. 3. Click the stop square to finish. -Videos are saved as VP8 WebM files in your XDG Videos folder under `Ferese`. -A notification shows the saved path. Audio and region recording are not supported -by the built-in recorder; other recording apps can handle audio separately. +The recorder saves VP8 WebM files under `Ferese` in your XDG Videos folder, then +shows the path in a notification. The built-in recorder does not support audio or +region recording; other recording apps can handle audio separately. If recording fails, a notification reports the error and any unfinished `.webm.part` file. @@ -23,18 +23,19 @@ choose a display or window and click **Share**. Nothing is selected initially. Apps requesting multiple sources can select up to eight. A shared display includes everything visible on it, including notifications. -A shared window includes only that app's content and subsurfaces, even when -covered or on another workspace. Separate popups and compositor decorations are -excluded. Resizing a shared window updates its video size; closing it ends sharing. +Window sharing captures only the selected app's content and subsurfaces, even if +the window is covered or on another workspace. It excludes separate popups and +compositor decorations. The video size follows window resizes; closing the window +ends sharing. The picker follows your shell colors, font, corners, opacity, and blur. ## Stop sharing -Click **Stop sharing** in the sharing window, or close that window. The built-in -recorder uses the top-bar stop button instead. Sharing also ends when the app -closes or Ferese locks. Disconnecting a shared monitor or changing its capture -size ends its stream; start sharing again afterward. +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. ## Remember permissions @@ -55,9 +56,9 @@ see the [package lists](installation.md#requirements). The installer supplies Ferese's portal backend and selects it for screen sharing. Log into a new Ferese session after installation. -Streams run at up to 30 fps and support hidden or embedded cursors. Capture copies -frames through CPU-accessible buffers, so large or multiple streams can use -substantial CPU and memory bandwidth. +Streams run at up to 30 fps with hidden or embedded cursors. Frames are copied +through CPU-accessible buffers. Large streams or several simultaneous streams +can therefore use substantial CPU and memory bandwidth. ## Troubleshooting diff --git a/docs/screenshots.md b/docs/screenshots.md index 8b2fd5a..efea528 100644 --- a/docs/screenshots.md +++ b/docs/screenshots.md @@ -1,6 +1,6 @@ # Screenshots -Captured on September 30, 2026. Select an image to view it at full size. +These screenshots were taken on September 30, 2026. Click an image to open it at full size. ## Ferese Blue @@ -22,7 +22,7 @@ Windows and workspaces over a custom wallpaper. ## Power controls -Power profiles and restart, power off and suspend actions. +Power controls for selecting a profile, restarting, powering off and suspending. [![Power profiles and restart, power off and suspend actions.](images/screenshots/power-controls.png)](images/screenshots/power-controls.png) @@ -34,7 +34,7 @@ Application previews and workspace selection. ## Shortcut guide -The login guide shows the configured keyboard shortcuts. +The shortcut guide displayed at login, using the configured keyboard shortcuts. [![The login guide shows the configured keyboard shortcuts.](images/screenshots/shortcut-guide.png)](images/screenshots/shortcut-guide.png) diff --git a/docs/shortcuts.md b/docs/shortcuts.md index f6d45dd..3382d2c 100644 --- a/docs/shortcuts.md +++ b/docs/shortcuts.md @@ -3,6 +3,8 @@ `Super` is usually the Windows key. These are the built-in defaults. Open **Settings → Shortcuts** to change bindings and gestures or disable the login guide. Your saved bindings can override these defaults. +The [example config](../packaging/config.kdl) adds the app, media and arrow-key +shortcuts listed below. ## Move and resize with the mouse @@ -25,6 +27,9 @@ to nearby edges; continuing to drag beyond 20 logical pixels releases the snap. | Shortcut | Action | | --- | --- | | Super + H / J / K / L | Focus in that direction | +| Super + Backspace | Return to the last focused window, including on another workspace or monitor | +| Alt + Tab | Preview recent windows in focus order | +| Alt + Shift + Tab | Preview recent windows in reverse focus order | | Super + Shift + H / J / K / L | Move the focused window in that direction | | Super + Ctrl + H / J / K / L | Resize in that direction | | Super + Q | Close the focused window | @@ -34,6 +39,10 @@ to nearby edges; continuing to drag beyond 20 logical pixels releases the snap. Maximize fills the available workspace. Fullscreen also hides the bar and window decorations. +Keep Alt held to cycle through recent windows. Release Alt to select the previewed +window, or press Escape to cancel. Repeating Super + Backspace toggles between the +two most recently focused windows. + ## Columns and layouts | Shortcut | Action | @@ -61,8 +70,8 @@ overview. | Super + Shift + 1–9 | Move the window to that workspace | | Super + Escape | Toggle between the last two visited workspaces on this monitor | -Workspaces are created as needed. Selecting one visible on another monitor focuses -that monitor. +Workspaces are created as needed and numbered separately on each monitor. +Workspace shortcuts select a workspace on the focused monitor. To make pressing the current workspace's shortcut toggle back too, enable **Settings → Windows → Toggle back with the same workspace shortcut**. It is off @@ -99,6 +108,39 @@ Gestures can use the same actions as keyboard bindings, including overview or moving a window. Four- and five-finger bindings are supported too. +## Reserved and context controls + +These controls are handled by the compositor rather than configurable bindings. + +| Control | Action | +| --- | --- | +| Enter in overview | Activate the selected window | +| Escape in overview | Close overview | +| Escape during Alt + Tab | Cancel the preview without changing focus | +| Release Alt during Alt + Tab | Focus the previewed window | +| Ctrl + Alt + Escape | Release an active shortcut inhibitor or input-capture session | +| Ctrl + Alt + F1–F12 | Switch virtual terminals in a direct session | + +Virtual-terminal switching is unavailable in nested previews. + +## Example-config shortcuts + +The [example config](../packaging/config.kdl) adds these to the built-in defaults. +App and hardware controls require their configured programs to be installed. + +| Shortcut | Action | +| --- | --- | +| Super + B | Open Firefox | +| Super + Z | Open Zed | +| Super + Alt + L | Lock with `ferese-lock` | +| Super + Left / Down / Up / Right | Focus in that direction | +| Super + Ctrl + Left / Down / Up / Right | Move the focused window in that direction | +| Super + Alt + Left / Down / Up / Right | Resize in that direction | +| Brightness up / down | Adjust brightness with `brightnessctl` | +| Volume up / down | Adjust volume with `wpctl` | +| Audio mute | Toggle output mute with `wpctl` | +| Microphone mute | Toggle microphone mute with `wpctl` | + ## Add a shortcut For example, bind a lock command and use a swipe to open overview: diff --git a/docs/why-ferese.md b/docs/why-ferese.md index fa68357..a1ee686 100644 --- a/docs/why-ferese.md +++ b/docs/why-ferese.md @@ -1,17 +1,16 @@ # Why Ferese -Most Wayland desktops are assembled from separate programs such as a compositor, a bar, a notification daemon, a launcher, a lock screen with each having its own config and its own idea of how things should look. Ferese is built as one desktop. Window management and the shell share a single configuration, so personalizing it means changing one thing, not five. +Most Wayland desktops are assembled from separate programs: a compositor, a bar, a notification daemon, a launcher and a lock screen, each with its own config and appearance settings. Ferese's window manager and shell share a single configuration. -## Choose how windows fit +## Window layouts Keep windows at useful widths and move through them horizontally with scrolling columns, divide the screen into nested splits with tree tiling, or let individual windows float -alongside either layout. When you want to see how everything fits together, overview -brings your windows and workspaces into view. +alongside either layout. Overview shows your windows and workspaces together. ![Ferese Overview showing windows and workspaces](images/screenshots/ferese-blue-overview.png) -## Change the desktop together +## Appearance Choose a theme in Settings and build on it with your own wallpaper, colors, font, corners and motion, with changes applying across the desktop as you make them. Window @@ -29,6 +28,6 @@ theme { } ``` -Explore [Configuration](configuration.md) for everything you can change, or follow +See [Configuration](configuration.md) for available settings, or follow [Installation](installation.md) to try Ferese inside your current desktop with a nested preview. diff --git a/site/README.md b/site/README.md index 59494bc..0fac9b9 100644 --- a/site/README.md +++ b/site/README.md @@ -1,8 +1,7 @@ # Ferese website and handbook -The website introduces Ferese as one desktop you can make your own, with a handbook -built from the project’s Markdown guides so the website and repository share the same -documentation. +The website's handbook is built from the project's Markdown guides, so the website +and repository share the same documentation. ## Local preview @@ -14,8 +13,7 @@ python3 -m http.server 8080 --bind 127.0.0.1 --directory build/site ``` Open http://localhost:8080 for the homepage or http://localhost:8080/docs/ for the -handbook, then rebuild and refresh the browser whenever you change the site sources or -guides. +handbook. Rebuild and refresh the browser after changing the site sources or guides. - `site/index.html` and `site/styles.css`: homepage and shared visual design. - `site/content/index.md`: handbook introduction. @@ -28,8 +26,8 @@ guides. ## GitHub Pages Choose **Settings → Pages → Source → GitHub Actions** to publish through the Pages -workflow, which runs when site or documentation changes reach `main` and can also be -started manually. The expected address is https://ferese-wm.github.io/ferese/. +workflow. It runs when site or documentation changes reach `main`; you can also +start it manually. The expected address is https://ferese-wm.github.io/ferese/. The site uses relative links, including for handbook search, so it also works under the `/ferese/` project path. Each build copies screenshots from `docs/images` into diff --git a/site/content/index.md b/site/content/index.md index c85b37e..1b7b93b 100644 --- a/site/content/index.md +++ b/site/content/index.md @@ -1,11 +1,10 @@ # Ferese handbook -Ferese is a window manager and desktop shell built together and configured in one place, -for people who want their desktop to be their own. This handbook helps you get settled, -shape the desktop around the way you work and understand what you can change. +Ferese combines a window manager and desktop shell with one configuration. +This handbook covers installation, settings and desktop controls. [Browse screenshots](screenshots.md) to see the themes, layouts and desktop controls in -use +use. ## Get started @@ -44,9 +43,8 @@ group windows, resize them and move between workspaces. - [Screen sharing and recording](screen-sharing.md): share an app or display, or save a video. - [Desktop portals](portals.md): integration with applications. -Personalize the desktop in Settings or edit `~/.config/ferese/config.kdl` directly, with -changes applying live and the last working configuration staying in place if an edit is -invalid. +Configure the desktop in Settings or edit `~/.config/ferese/config.kdl` directly. +Changes apply live. Invalid edits leave the last working configuration in place. ## Troubleshooting @@ -54,6 +52,6 @@ If you need to end a session, `feresectl request-logout` asks for confirmation a `feresectl exit` exits immediately, so save your work first. The [logs and recovery guide](installation.md#logout-and-recovery) helps when something stops responding. -You can [report a problem](https://github.com/ferese-wm/ferese/issues) with the steps to +To [report a problem](https://github.com/ferese-wm/ferese/issues), include the steps to reproduce it, relevant logs and whether you were using a nested preview or a direct -session, or start with [Development](development.md) if you’d like to contribute. +session. See [Development](development.md) to contribute. diff --git a/site/index.html b/site/index.html index 5921ee5..7ae34e2 100644 --- a/site/index.html +++ b/site/index.html @@ -5,9 +5,9 @@ - + - + @@ -36,12 +36,11 @@

- A Wayland desktop built around personalization. + A configurable Wayland desktop.

- Ferese is a window manager and desktop shell - built together and configured in one place, - for people who want their desktop to be their own. + Ferese combines a window manager and desktop shell + with one configuration.

Install Ferese @@ -64,7 +63,7 @@
-

Flexible layouts

+

Window layouts

Scrolling columns, tree tiling, floating windows, and a workspace overview. Use keyboard shortcuts or gestures to move around. @@ -72,15 +71,14 @@ Configure layouts →

-

A native desktop

+

Desktop tools

- A menu bar, Control Center, Settings, notifications, and desktop - widgets, designed to work together. + A menu bar, Control Center, Settings, notifications, and desktop widgets.

Explore Ferese →
-

Make it yours

+

Appearance

Choose your theme, wallpaper, colors, and motion. Change settings through the app or a KDL config, with live reload. @@ -118,4 +116,4 @@ - \ No newline at end of file +