Add native appearance, screenshot and wallpaper portals

docs/installation.md

@@ -13,7 +13,7 @@ desktop instead of direct access to the graphics device.
 
 Build with **Rust 1.95 or newer**, a C/C++ toolchain, CMake, pkg-config, and the
 native development libraries below. The installer builds Ferese, its shell,
-Settings, command-line tools, locker, polkit agent, and ScreenCast portal together. It does not install system
+Settings, command-line tools, locker, polkit agent, and desktop portal backend together. It does not install system
 packages or enable background services at boot. On systemd systems, the installed
 session helper activates `ferese-session.target` after exporting the compositor's
 Wayland display, and stops it when the shell exits. This keeps
@@ -105,7 +105,7 @@ The installer adds:
 - Commands under `/usr/local/bin/`, including `ferese-session`, `ferese-settings`,
   `feresectl`, `ferese-lock`, `ferese-polkit-agent`, `ferese-screenshot`, and
   `xdg-desktop-portal-ferese`, and `ferese-record`.
-- D-Bus activation and Ferese-specific ScreenCast portal registration.
+- D-Bus activation and Ferese-specific desktop portal registration.
 - A Wayland session entry at `/usr/share/wayland-sessions/ferese.desktop`.
 - A Settings application entry, icons, the default wallpaper, and an example config.
 - `/etc/pam.d/ferese-lock`, using your distribution's authentication stack.

docs/portals.md

@@ -0,0 +1,80 @@
+# 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:** whole-screen and selected-area PNG captures, plus a screen
+  color picker. Every capture asks for consent. Interactive requests offer area
+  selection. Selection uses `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`.
+- **ScreenCast:** monitor sharing with a native picker and PipeWire streams.
+  See [screen sharing](screen-sharing.md) for lifetime and recording details.
+
+Native request dialogs use Ferese's theme and are floating windows. Screenshot,
+PickColor and Wallpaper 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](https://github.com/GNOME/xdg-desktop-portal-gnome/blob/main/data/meson.build)
+with the [standard backend D-Bus contracts](https://flatpak.github.io/xdg-desktop-portal/docs/impl-dbus-interfaces.html).
+Matching D-Bus signatures does not establish complete feature parity.
+
+| Interface | Ferese integration |
+| --- | --- |
+| Settings | Native, including appearance change signals |
+| Screenshot | Native screen/area capture and PickColor; true window capture remains missing |
+| Wallpaper | Native desktop, lock-screen and combined targets |
+| ScreenCast | Native monitors; window sources, persistence and richer metadata remain missing |
+| Access, Account, AppChooser, DynamicLauncher, FileChooser, Notification, Print | Delegated to GTK |
+| Background | Missing native application state and background consent |
+| Usb | Missing native device consent |
+| GlobalShortcuts | Missing session-scoped compositor registration and activation signals |
+| RemoteDesktop | Missing authorized input injection and EIS transport |
+| Clipboard | Missing remote-session clipboard transfer |
+| InputCapture | Missing zones, pointer barriers and EIS transport |
+| Lockdown | GTK availability depends on the installed build; no native policy provider |
+| Inhibit | GTK's GNOME-session/ScreenSaver integration does not provide complete Ferese session inhibition |
+
+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.
+
+Do not advertise window capture or input services until the compositor provides
+the corresponding operation. Screen crops include occluding windows and cannot
+serve as isolated window captures. GNOME's remote-input features require native
+compositor/session work, rather than substituting successful empty replies.
+
+## Validation
+
+Build the backend and run unit tests, then check its contracts on a private bus:
+
+```sh
+cargo build --locked -p xdg-desktop-portal-ferese
+cargo test --locked -p xdg-desktop-portal-ferese
+python3 scripts/tests/test_portal_contracts.py
+```
+
+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.

docs/screen-sharing.md

@@ -47,7 +47,9 @@ The [standard installer](installation.md) builds and installs the backend, its
 D-Bus activation entry, and a Ferese-specific portal preference file. Install
 `pipewire`, a PipeWire session manager such as `wireplumber`,
 `xdg-desktop-portal`, and `xdg-desktop-portal-gtk` using your distribution's package
-manager. The GTK backend supplies other portal interfaces such as file selection.
+manager. The GTK backend supplies standard dialogs such as file selection. Ferese also
+provides native Settings, Screenshot and Wallpaper services; see
+[desktop portals](portals.md).
 The built-in recorder also needs GStreamer’s PipeWire, base, and good plugins
 (`pipewiresrc`, `videoconvert`, `vp8enc`, and `webmmux`). The installation guide
 includes these packages.