feresaria/docs/portals.md

Desktop portals

Applications call the standard org.freedesktop.portal.Desktop frontend. Ferese's native backend implements desktop integration; GTK remains the fallback for standard file, print and application dialogs. Install both backends.

Native services

• Settings: Ferese's color scheme, accent color, contrast preference and reduced-motion setting. Changes are signalled after valid KDL appearance changes; malformed saves leave the last valid preferences intact.
• Screenshot: screen, selected-area, selected-window and active-window PNG captures, plus a screen color picker. Window captures render the selected toplevel and its subsurfaces in isolation, preserving transparency; occluding windows, separate popups, shell layers and compositor borders are excluded. The native window picker lists window titles and application IDs. Every capture asks for consent. Interactive requests offer area selection; area and color selection use slurp. Captures use Ferese's bounded screenshot IPC. The helper must disappear from the compositor before capture starts.
• Wallpaper: a preview and confirmation, then an atomic configuration update. Desktop and lock-screen wallpaper can be set independently, or together. Ferese copies accepted local images into its own private data directory so temporary portal files can disappear safely. Image bytes and decoded dimensions are bounded. theme.background.lock-path overrides the lock-screen image; without it the lock screen follows theme.background.path.
• Background: native open-window/app state, change signals and per-instance background consent. Legacy autostart requests create managed XDG desktop entries; current frontends manage those files themselves. Direct sessions launch standard XDG autostart entries after importing the display environment. User overrides, Hidden, OnlyShowIn, NotShowIn and TryExec are respected; previews skip autostart.
• Lockdown: standard printing, save-to-disk, application-handler, location, camera, microphone and sound-output restrictions. All default to unrestricted. Configure boolean disable-* fields under portals { lockdown { ... } }; changes are signalled to the frontend. Invalid policy types retain the current policy. Only the portal frontend may write backend policy properties.
• USB: native confirmation showing device vendor/model and requested read-only or read/write access. The portal frontend handles device enumeration and opening.
• GlobalShortcuts: session-scoped keyboard shortcuts with native trigger selection, conflict checking, activation/release signals and reconfiguration. Applications cannot replace Ferese bindings or reserved escape/VT shortcuts. Closing a session or losing its compositor connection releases its shortcuts; shortcuts do not activate on the lock screen. Saved choices are offered for future sessions, with explicit approval before registering them.
• Inhibit: connection-scoped logout, suspend and idle inhibitors, backed by logind descriptors and compositor idle inhibition. Native session monitors report lock state and Running/QueryEnd/Ending transitions. Ending queries wait for acknowledgements for up to one second. Power confirmations list blockers and recheck them before acting; authentication failure cancels the query. UserSwitch is recorded, but Ferese currently has no user-switch operation.
• ScreenCast: monitor and isolated window sharing with a native picker, PipeWire streams and explicit opt-in saved permissions. The frontend stores and revokes saved choices. Invalid restore data or changed display identity requires fresh consent. See screen sharing for lifetime and recording details.

Native request dialogs use Ferese's theme and are floating windows. Screenshot, PickColor, Wallpaper, USB and ScreenCast consent dialogs use Wayland parent identifiers to establish a transient relationship with the requesting window. Cancelling a request or losing the portal frontend terminates its pending helper.

The packaged ferese-portals.conf selects these interfaces explicitly. Existing user overrides in ~/.config/xdg-desktop-portal/ may take precedence. Install the new compositor, backend and preference files together; screenshot synchronization requires the updated compositor IPC.

GNOME compatibility audit

The audit compares the GNOME backend's registered interfaces with the standard backend D-Bus contracts. Matching D-Bus signatures does not establish complete feature parity.

Interface	Ferese integration
Settings	Native, including appearance change signals
Screenshot	Native screen/area/window/active-window capture and PickColor
Wallpaper	Native desktop, lock-screen and combined targets
ScreenCast	Native v4 monitors and isolated windows, logical geometry, live window resizing and opt-in saved display permissions
Access, Account, AppChooser, DynamicLauncher, FileChooser, Notification, Print	Delegated to GTK
Background	Native application state, per-instance consent and XDG autostart
Usb	Native consent; standard frontend handles enumeration and device descriptors
GlobalShortcuts	Native sessions, configurable keyboard triggers, conflict checks and activation/release signals
RemoteDesktop	Deferred: authorized input injection and EIS transport
Clipboard	Deferred with RemoteDesktop
InputCapture	Missing zones, pointer barriers and EIS transport
Lockdown	Native seven-property policy provider with persisted configuration and change signals
Inhibit	Native inhibitors and session monitors; UserSwitch recorded until a switch operation exists

The frontend supplies additional APIs such as OpenURI, network monitoring, document export and permission storage. Adding a similarly named backend service is neither required nor sufficient for those APIs.

Window streams render only the selected toplevel and its subsurfaces, including on an inactive workspace. Overlapping apps, shell layers, separate popup windows and compositor decorations are excluded. The private capture protocol is available only to the native portal executable and checks session opt-in and locking. Window resizing renegotiates PipeWire video dimensions. Closing the selected window ends sharing; its lifetime ID cannot select a replacement app. Window selections require fresh consent and are not saved as display permissions. InputCapture still needs native zones, barriers and EIS transport. RemoteDesktop and its Clipboard integration remain deferred.

Validation

Build the backend and run unit tests, then check its contracts on a private bus:

cargo build --locked -p xdg-desktop-portal-ferese
cargo test --locked -p xdg-desktop-portal-ferese
python3 scripts/tests/test_portal_contracts.py

With a Wayland host and a built compositor, check shortcut connection cleanup and configuration conflicts in an isolated nested compositor:

FERESE_TEST_SHORTCUTS=1 python3 scripts/tests/test_shortcuts_isolated.py

Check window capture isolation, transparency and orientation with overlapping clients in a temporary nested compositor:

FERESE_TEST_WINDOW_CAPTURE=1 python3 scripts/tests/test_window_capture_isolated.py

Capture a managed window directly from the CLI with feresectl screenshot-window <window-id> > capture.png; feresectl get-windows lists IDs.

The contract test compares introspection against the installed official backend XML, verifies appearance changes and invalid-save retention, and checks that sensitive methods reject callers outside the portal frontend. It does not open consent dialogs or capture the host desktop. Interactive consent, fractional-scale capture, polkit and hotplug still require a live session test.

Check native inhibitor lifetimes, acknowledgement generations and session-ending transitions against a mock logind in an isolated nested compositor:

FERESE_TEST_INHIBIT=1 python3 scripts/tests/test_inhibit_isolated.py

The shell now requires version 4 of Ferese's shell protocol; rebuild the shell and compositor together when upgrading.

Check restored sharing, mode downgrade, stale-data fallback, output-generation validation and frontend-disconnect cleanup with synthetic monitor identities on an isolated bus and nested compositor:

FERESE_TEST_RESTORE=1 python3 scripts/tests/test_restore_isolated.py

Check live window pixels, overlap isolation, inactive workspaces, resizing and closure using a disposable nested compositor and a real PipeWire consumer:

FERESE_TEST_WINDOW_STREAM=1 python3 scripts/tests/test_window_stream_isolated.py