path: root/docs/DEFAULTS.md

# SRDWM Default Configuration Reference

## Overview
This document describes all default configuration values and available options for SRDWM. These defaults provide a sensible starting point that works well across all platforms.

## Configuration Structure

### Global Settings (`general.*`)
```lua
srd.set("general.default_layout", "dynamic")           -- Default: "dynamic"
srd.set("general.window_gap", 8)                       -- Default: 8
srd.set("general.animations", true)                    -- Default: true
srd.set("general.animation_duration", 200)             -- Default: 200ms
srd.set("general.shadows", true)                       -- Default: true
srd.set("general.resize_margin", 6)                    -- Default: 6px
srd.set("general.rounded_corners", true)               -- Default: true on GLES/winit, false on udev/Pixman (opt-in there)
srd.set("general.focus_follows_mouse", false)          -- Default: false - hover a window to focus it, no click needed
srd.set("general.auto_raise", false)                   -- Default: false - also raise on hover-focus, not just focus
```
`general.smart_placement`/`general.border_width` are not listed: neither
is implemented - new-window placement always uses smart placement
unconditionally (no toggle exists), and the real, working border-width
setting is `theme.decorations.border.width` below.
`general.mouse_follows_focus` (warp the pointer to match a keybinding-
driven focus change) and `general.auto_focus` (no clear distinct meaning
found beyond what plain click-to-focus already does) aren't implemented
either.

### Monitor Settings (`monitor.*`)
```lua
srd.set("monitor.primary_layout", "dynamic")           -- Default: "dynamic"
srd.set("monitor.secondary_layout", "tiling")          -- Default: "tiling"
srd.set("monitor.auto_detect", true)                   -- Default: true
```
srdwm has one flat workspace list shared by every monitor, not an
independent set per monitor - there is no "this monitor's primary
workspace"/"this monitor's workspace count" to configure. `workspace.count`
below is the actual knob.

### Window Behavior (`window.*`)
Not implemented: this whole namespace duplicated `general.*`'s own focus
keys (see above for the two of those that are real) plus three genuinely
unbuilt per-app-window-state-persistence keys (`remember_position`/
`remember_size`/`remember_state` - no window remembers anything about a
previous run; every new window starts at a hardcoded size, see
`crates/wayland/src/xwayland.rs`/`state/lifecycle.rs`'s `new_managed_window`).
```

### Workspace Settings (`workspace.*`)
```lua
srd.set("workspace.count", 10)                         -- Default: 10
srd.set("workspace.names", {"1", "2", "3", "4", "5", "6", "7", "8", "9", "0"})
srd.set("workspace.auto_back_and_forth", false)        -- Default: false
```
(`workspace.auto_switch`/`workspace.persistent` are not implemented - not
listed here since setting either currently does nothing.)

### Performance Settings (`performance.*`)
```lua
srd.set("performance.vsync", true)                     -- Default: true
srd.set("performance.max_fps", 60)                     -- Default: 60
srd.set("performance.window_cache_size", 100)          -- Default: 100
srd.set("performance.event_queue_size", 1000)          -- Default: 1000
srd.set("performance.layout_timeout", 16)              -- Default: 16ms
srd.set("performance.enable_caching", true)            -- Default: true
```

### Debug Settings (`debug.*`)
```lua
srd.set("debug.logging", true)                         -- Default: true
srd.set("debug.log_level", "info")                     -- Default: "info"
srd.set("debug.profile", false)                        -- Default: false
srd.set("debug.trace_events", false)                   -- Default: false
srd.set("debug.show_layout_bounds", false)             -- Default: false
srd.set("debug.show_window_geometry", false)           -- Default: false
```

## Layout-Specific Defaults

### Tiling Layout (`layout.tiling.*`)
```lua
srd.layout.configure("tiling", {
    split_ratio = 0.5,                                 -- Default: 0.5
    master_ratio = 0.6,                                -- Default: 0.6
    auto_swap = true,                                  -- Default: true
    gaps = {
        inner = 8,                                      -- Default: 8
        outer = 16                                      -- Default: 16
    },
    behavior = {
        new_window_master = false,                      -- Default: false
        auto_balance = true,                            -- Default: true
        preserve_ratio = true                           -- Default: true
    }
})
```

### Dynamic Layout (`layout.dynamic.*`)
```lua
srd.layout.configure("dynamic", {
    snap_threshold = 20,                                -- Default: 20
    grid_size = 6,                                      -- Default: 6
    cascade_offset = 30,                                -- Default: 30
    smart_placement = true,                             -- Default: true
    gaps = {
        inner = 8,                                      -- Default: 8
        outer = 16                                      -- Default: 16
    },
    behavior = {
        remember_positions = true,                      -- Default: true
        auto_arrange = true,                            -- Default: true
        overlap_prevention = true                       -- Default: true
    }
})
```

### Floating Layout (`layout.floating.*`)
```lua
srd.layout.configure("floating", {
    default_position = "center",                        -- Default: "center"
    remember_position = true,                           -- Default: true
    always_on_top = false,                             -- Default: false
    gaps = {
        inner = 0,                                      -- Default: 0
        outer = 16                                      -- Default: 16
    },
    behavior = {
        allow_resize = true,                            -- Default: true
        allow_move = true,                              -- Default: true
        snap_to_edges = true                            -- Default: true
    }
})
```

## Theme Defaults

### Colors (`theme.colors.*`)
```lua
srd.theme.set_colors({
    background = "#2e3440",                             -- Default: Nord dark
    foreground = "#eceff4",                             -- Default: Nord light
    primary = "#88c0d0",                                -- Default: Nord blue
    secondary = "#81a1c1",                              -- Default: Nord blue-gray
    accent = "#5e81ac",                                 -- Default: Nord blue
    error = "#bf616a",                                  -- Default: Nord red
    warning = "#ebcb8b",                                -- Default: Nord yellow
    success = "#a3be8c"                                 -- Default: Nord green
})
```

### Window Decorations (`theme.decorations.*`)
```lua
srd.theme.set_decorations({
    border = {
        width = 2,                                      -- Default: 2
        active_color = "#88c0d0",                       -- Default: Nord blue
        inactive_color = "#2e3440",                     -- Default: Nord dark
        focused_style = "solid",                        -- Default: "solid"
        unfocused_style = "solid"                       -- Default: "solid"
    },
    title_bar = {
        height = 24,                                    -- Default: 24
        show = true,                                    -- Default: true
        font = "JetBrains Mono 10",                     -- Default: "JetBrains Mono 10"
        background = "#2e3440",                         -- Default: Nord dark
        foreground = "#eceff4"                          -- Default: Nord light
    }
})
```

## Key Binding Defaults

### Essential Bindings
```lua
- Layout switching
srd.bind("Mod4+1", function() srd.layout.set("tiling") end)      -- Default: Mod4+1
srd.bind("Mod4+2", function() srd.layout.set("dynamic") end)     -- Default: Mod4+2
srd.bind("Mod4+3", function() srd.layout.set("floating") end)    -- Default: Mod4+3

- Window management
srd.bind("Mod4+q", function() srd.window.close() end)            -- Default: Mod4+q
srd.bind("Mod4+m", function() srd.window.minimize() end)         -- Default: Mod4+m
srd.bind("Mod4+f", function() srd.window.maximize() end)         -- Default: Mod4+f

- Window movement (vim-style)
srd.bind("Mod4+h", function() srd.window.focus("left") end)      -- Default: Mod4+h
srd.bind("Mod4+j", function() srd.window.focus("down") end)      -- Default: Mod4+j
srd.bind("Mod4+k", function() srd.window.focus("up") end)        -- Default: Mod4+k
srd.bind("Mod4+l", function() srd.window.focus("right") end)     -- Default: Mod4+l

- Workspace management
srd.bind("Mod4+Tab", function() srd.workspace.next() end)        -- Default: Mod4+Tab
srd.bind("Mod4+Shift+Tab", function() srd.workspace.prev() end)  -- Default: Mod4+Shift+Tab

- Quick actions
srd.bind("Mod4+d", function() srd.spawn("rofi -show drun") end) - Default: Mod4+d
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)
- `pinned` (bool) - always-on-top
- `opacity` (number, `0.0`..=`1.0`) - content opacity; srdwm's own
  titlebar/border/shadow always stay fully opaque regardless
- `resize_margin` (number, logical pixels) - per-window override of
  `general.resize_margin` (Hyprland's per-window `extend_border_grab_area`).
  Also settable live via `srd.window.set_resize_margin(n)` on the focused
  window.

```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)
```lua
- Auto-detect backend
srd.set("platform.backend", "auto")                    -- Default: "auto"

- X11 specific
srd.set("platform.x11.use_ewmh", true)                 -- Default: true
srd.set("platform.x11.use_netwm", true)                -- Default: true

- Wayland specific
srd.set("platform.wayland.use_xdg_shell", true)        -- Default: true
srd.set("platform.wayland.use_layer_shell", true)      -- Default: true
```

### Windows
```lua
- Windows specific
srd.set("platform.windows.use_dwm", true)              -- Default: true
srd.set("platform.windows.use_win32", true)            -- Default: true
srd.set("platform.windows.global_hooks", true)         -- Default: true
```

### macOS
```lua
- macOS specific
srd.set("platform.macos.use_cocoa", true)              -- Default: true
srd.set("platform.macos.use_core_graphics", true)      -- Default: true
srd.set("platform.macos.accessibility_enabled", true)  -- Default: true
```

## Configuration File Locations

### Linux
- **Config**: `~/.config/srd/`
- **Themes**: `~/.config/srdwm/themes/`
- **Scripts**: `~/.config/srdwm/scripts/`
- **Cache**: `~/.cache/srdwm/`
- **Logs**: `~/.local/share/srdwm/logs/`

### Windows
- **Config**: `%APPDATA%\srdwm\srd\`
- **Themes**: `%APPDATA%\srdwm\themes\`
- **Scripts**: `%APPDATA%\srdwm\scripts\`
- **Cache**: `%LOCALAPPDATA%\srdwm\cache\`
- **Logs**: `%LOCALAPPDATA%\srdwm\logs\`

### macOS
- **Config**: `~/Library/Application Support/srdwm/`
- **Themes**: `~/Library/Application Support/srdwm/themes/`
- **Scripts**: `~/Library/Application Support/srdwm/scripts/`
- **Cache**: `~/Library/Caches/srdwm/`
- **Logs**: `~/Library/Logs/srdwm/`

## Environment Variables

```bash
# Configuration path override
export SRDWM_CONFIG_PATH="/path/to/config"

# Theme override
export SRDWM_THEME="nord"

# Debug level
export SRDWM_DEBUG_LEVEL="debug"

# Platform override
export SRDWM_PLATFORM="wayland"

# Performance settings
export SRDWM_MAX_FPS="120"
export SRDWM_VSYNC="false"
```

## Reset to Defaults

To reset any setting to its default value:

```lua
- Reset specific setting
srd.reset("general.window_gap")

- Reset all settings
srd.reset_all()

- Reset specific category
srd.reset_category("general")
```

## Validation Rules

### Numeric Values
- **Gaps**: 0-100 pixels
- **Border width**: 0-20 pixels
- **Animation duration**: 0-1000ms
- **FPS**: 30-240
- **Cache size**: 10-10000

### String Values
- **Layout names**: Must be registered layouts
- **Theme names**: Must be valid theme files
- **Font names**: Must be system fonts
- **Color values**: Must be valid hex colors

### Boolean Values
- **Features**: true/false
- **Debug options**: true/false
- **Performance options**: true/false

## Best Practices

1. **Start with defaults**: Don't change settings unless necessary
2. **Test changes**: Always test configuration changes
3. **Backup configs**: Keep backups of working configurations
4. **Use comments**: Document custom configurations
5. **Validate syntax**: Use `srd.validate_config()` before reloading

## Troubleshooting

### Common Issues
- **Config not loading**: Check file permissions and syntax
- **Settings not applying**: Verify setting names and values
- **Performance issues**: Check performance settings
- **Layout problems**: Verify layout configuration

### Debug Commands
```lua
- Check configuration status: returns { keys, bound_keys, log_entries, config_dir }
local status = srd.debug.config_status()

- 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: logs every key = value and returns them as a table
local settings = srd.debug.show_settings()

- Performance profiling: profile_stop() returns elapsed seconds (number)
srd.debug.profile_start()
local elapsed = srd.debug.profile_stop()
```

This documentation provides a comprehensive reference for all default values and configuration options in SRDWM.