From 43175c78a5b450eb108738187b72e80d36a7bf5d Mon Sep 17 00:00:00 2001
From: srdusr <99972264+srdusr@users.noreply.github.com>
Date: Tue, 2 Apr 2024 01:07:00 +0200
Subject: Add window rules, real config validation, and a Wayland DRM/udev
 backend

- srd.rule(): match windows by title/class, apply floating/maximized/
  workspace/geometry/decoration actions on creation (crates/core/src/rules.rs)
- srd.validate_config()/srd.debug.*: real range/format checks and
  status/profiling helpers, replacing the always-true stub
- Wayland titlebar text rendering via fontdue, unit-tested without a
  display (crates/wayland/src/decoration.rs)
- Wayland precise keybinding matching, replacing the "any Super-held key"
  heuristic, sharing the keysym table with X11 (moved to
  crates/core/src/keysyms.rs)
- Wayland DRM/udev backend (crates/wayland/src/udev.rs): runs as the real
  compositor on a bare TTY via libseat/libinput/KMS, software rendering
  via Pixman + dumb buffers (no GBM/EGL required)
- srdwm_platform::detect() fix, found via VM testing: a bare TTY with no
  DISPLAY/WAYLAND_DISPLAY now correctly resolves to Wayland instead of an
  X11 backend that can never work there
- XWayland integration groundwork (crates/wayland/src/xwayland.rs): spawn,
  X11Wm, and full XwmHandler event routing into the same WindowManager/
  Space pipeline as native clients. Windows don't render yet - a real
  glamor-vs-software-renderer conflict in XWayland's own fallback path,
  root-caused via WAYLAND_DEBUG tracing and documented in
  docs/IMPLEMENTATION_STATUS.md rather than worked around blind.

All verified live in an isolated QEMU VM: X11 backend shows two
decorated, correctly-tiled xterms with real title text; the DRM/udev
Wayland backend opens the GPU, initializes input, and scans out a
rendered frame via KMS page-flip.
---
 docs/DEFAULTS.md | 46 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 38 insertions(+), 8 deletions(-)

(limited to 'docs/DEFAULTS.md')

diff --git a/docs/DEFAULTS.md b/docs/DEFAULTS.md
index 9b36f5a..74dfba6 100644
--- a/docs/DEFAULTS.md
+++ b/docs/DEFAULTS.md
@@ -191,6 +191,33 @@ srd.bind("Mod4+d", function() srd.spawn("rofi -show drun") end) - Default: Mod4+
 srd.bind("Mod4+Return", function() srd.spawn("alacritty") end)  -- Default: Mod4+Return
 ```
 
+## Window Rules
+
+Match windows by title/class and apply actions once, when they're first
+created:
+
+```lua
+srd.rule(matcher, actions)
+```
+
+`matcher` fields (at least one required; an empty matcher matches nothing):
+- `title` - case-insensitive substring match against the window title.
+- `class` (alias `app_id`) - case-insensitive exact match against the
+  window's `WM_CLASS` (X11) / `app_id` (Wayland).
+
+`actions` fields (all optional):
+- `floating` (bool), `maximized` (bool)
+- `workspace` (number) - workspace id to place the window on
+- `x`, `y`, `width`, `height` (number) - explicit geometry; all four must be
+  given together to take effect
+- `decorated` (bool)
+- `border_color` (`{r, g, b}`), `border_width` (number)
+
+```lua
+srd.rule({ class = "pavucontrol" }, { floating = true })
+srd.rule({ title = "Picture-in-Picture" }, { floating = true, width = 480, height = 270 })
+```
+
 ## Platform-Specific Defaults
 
 ### Linux (X11/Wayland)
@@ -319,18 +346,21 @@ srd.reset_category("general")
 
 ### Debug Commands
 ```lua
-- Check configuration status
-srd.debug.config_status()
+- Check configuration status: returns { keys, bound_keys, log_entries, config_dir }
+local status = srd.debug.config_status()
 
-- Validate current configuration
-srd.debug.validate_config()
+- Validate current configuration against docs/DEFAULTS.md's ranges/formats:
+- returns ok (bool), errors (array of human-readable strings, empty when ok)
+local ok, errors = srd.debug.validate_config()
+- equivalently, at the top level:
+local ok, errors = srd.validate_config()
 
-- Show current settings
-srd.debug.show_settings()
+- Show current settings: logs every key = value and returns them as a table
+local settings = srd.debug.show_settings()
 
-- Performance profiling
+- Performance profiling: profile_stop() returns elapsed seconds (number)
 srd.debug.profile_start()
-srd.debug.profile_stop()
+local elapsed = srd.debug.profile_stop()
 ```
 
 This documentation provides a comprehensive reference for all default values and configuration options in SRDWM.
-- 
cgit v1.2.3